Complete reference for every patch branch integrated into this fork, grouped by topic. Each entry lists its use case, limits, and patch branch. For a short highlight list see the README. For branch ownership and rebuild rules see MAINTAIN.md.
The single-executable bundle, update verification, and packaging fixes. See the update guide for commands, mirrors, verification and backup handling.
- Single-file executable with embedded Bun runtime (JIT) and precompiled JavaScript bytecode; the extracted
piis the complete product, no Node.js, npm, or companion binary required.- Use case: Run Pi by downloading and extracting one ZIP, on a machine with no JavaScript tooling.
- Builds: All 14 Release targets use
--minify --bytecode --format=esm. Precompilation moves parsing and initial bytecode generation to build time; runtime JIT remains enabled. The current build helper still omits bytecode for cross-OS/architecture builds as a downstream restriction, although Bun 1.4.1 fixed the historical cross-compilation defect. - Patch branch:
patch/single-executable
- Retry failed
pi updateoperations up to three additional times, waiting 3, 6, and 12 seconds. Covers self-update, Git/npm extension updates and explicit model-catalog refresh without repeating completed sibling updates.- Use case: Recover from a transient TLS EOF or dropped connection without rerunning the command.
- Limits: Four attempts maximum per failed operation; retries cannot repair permanent failures. Signature/checksum verification, pinned versions, rollback and final failure reports remain enforced.
- Details: Automatic update retries
- Patch branch:
patch/single-executable
- Run the native FreeBSD amd64 and arm64 executables with CLI, TUI, extension loading, self-update, and cleanup of obsolete backup copies.
- Use case: Use Pi on FreeBSD without a Linux compatibility layer or a separately installed JavaScript runtime.
- Limits: FreeBSD 14.3 or newer. The arm64 ZIP is accepted in an emulated (QEMU TCG) guest because GitHub has no arm64 KVM host. Install
fd-findandripgrepfor find/grep tools. X11 clipboard reads requirelibxcb; Wayland useswl-clipboard, and SSH/headless copy uses OSC 52. - Patch branches:
patch/freebsd-support,patch/single-executable
- Keep the fork/pre-release changelog baseline, display, and version handling correct across downstream release cycles.
- Use case: Keep downstream prerelease display and changelog lookup correct when package and release versions differ.
- Patch branch:
patch/single-executable
- Refuse
pi update --selffor channel-managed installations. A package manager marks its install by writing an empty.<channel>.managed.lockfile next to the executable;pi update --selfdetects any*.managed.lockmarker before any release lookup, refuses to replace the binary offline, and points the user at the owning channel.- Use case: Stop Scoop or a Gentoo ebuild install from fighting the package manager's own upgrades, while keeping the direct-download Release executable channel-neutral.
- Patch branch:
patch/single-executable
- Remove old executable backups with
pi update --clean. Only regular files named exactlypi-<distribution version>(.exeon Windows) next to the running executable are deleted; the running executable, symlinks, directories, and other files are left alone, and files that cannot be deleted (for example a still-running backup on Windows) are kept and reported.- Use case: Free disk after several
pi update --selfcycles. - Patch branch:
patch/single-executable
- Use case: Free disk after several
- Fix standalone extension installation and updates failing when an external package manager is unavailable by using the Bun embedded in the xz-dev bundle. Explicit
npmCommandsettings take precedence; otherwise package operations spawn the running Pi executable itself, so they work when Pi is launched by absolute path withoutpionPATH, and without separately installing Node.js, npm, or Bun.- Use case: Install a Git extension with runtime dependencies on a machine that only has Pi and Git. Managed npm updates retain version selectors and exact pins. If metadata lookup fails, Pi warns about possible downgrade and continues; successful queries still skip equal or older targets.
- Limits: Official Bun 1.4.2 requires a project manifest for metadata queries. Registry configuration, lockfiles, dependency scripts, and native modules are not guaranteed to behave like npm; Pi does not broaden script trust or install native build tools automatically.
- Details: Package-manager selection
- Patch branch:
patch/single-executable
Available only in builds containing patch/plugin-dependency-updates; older binaries lack dependency refresh. Existing package update notifications and commands also detect
and update floating runtime dependencies when the extension's npm version or Git
commit has not changed.
- Use case: Pick up an in-range library fix or eligible Git HEAD/named-branch change without waiting for the extension author to publish another version or commit.
- Commands:
pi update --extensions,pi update <source>andpi update --all. Barepi updateremains self-only; the existing notification distinguishes package, dependency and combined updates without installing them automatically. - Managers: npm/Bun cover direct and indirect registry dependencies and eligible Git HEAD/named branches in managed npm and Git-plugin roots, including Bun hoisted/isolated layouts. pnpm covers direct/indirect registry dependencies, but Git refresh is limited to direct, unaliased dependencies of Git-sourced extensions. Its default exotic-subdependency policy still blocks indirect Git, including managed npm-plugin paths; Pi does not disable it.
- Limits: Exact dependency versions, Git SHAs/tags, effective author locks and shared constraints remain enforced. Pi-generated installation locks may refresh. Dependency-only planning skips unsupported refs/native locks, unsafe or unknown graphs, workspace/override contexts and bundled/author-locked subtrees rather than downgrade another instance or advertise an impossible update. Local development directories, development dependencies and host-provided peers are not maintained. Restart Pi after updating.
- Details: Extension dependencies
- Patch branch:
patch/plugin-dependency-updates
Manual and automatic retry of interrupted work, plus transport-level recovery.
- Continue from the nearest protocol-safe conversation boundary with
/retryor RPCretry, preserving superseded history as an append-only sibling branch, retaining completed tool results, and synthesizing explicit unknown-outcome errors only for missing results without replaying old tool calls.- Use case: Resume after Pi or its provider was interrupted, without replaying completed tool calls.
- Patch branch:
patch/manual-retry
- Recover once on interactive cold startup, such as
pi -corpi --session, when an unfinished working run has a safe retryable conversation tail and no new input takes priority. Closed runs and sessions without run records remain manual-only; older run records derive working flags from their state. Pending recovery showsThis session will automatically run /retry shortly.; otherwise idle retryable sessions show a dim/retryhint, clickable in fullscreen with(click to run).- Use case: Continue interrupted work after restarting Pi, or click the hint to retry manually without losing an editor draft.
- Limits: Explicit user cancellation, natural completion, and output-limit endings do not auto-recover; in-process
/resumedoes not trigger recovery. New input takes priority, including during authentication. Esc or Ctrl+C cancels pending recovery durably, and startup navigation cannot redirect it to another branch. Runtime error-retry limits and backoff are unchanged. Concurrent writers to one session file and exactly-once external tool effects are not guaranteed. - Details: Interrupted work
- Patch branch:
patch/cold-start-retry
- Keep input in the editor until interactive startup has bound the session and rendered its history. An early Enter shows
Session is still starting; press Enter again after startup to submit/retryor an ordinary prompt. Custom editors receive the same submit handler.- Use case: Press
/retryimmediately afterpi -cwithout losing the native Working indication when the resumed response streams. - Patch branch:
patch/startup-submit-readiness
- Use case: Press
- Recover Codex WebSocket transport after transient failures, then resume incremental context instead of leaving the session permanently on SSE.
auto: Make an initial WS attempt plus three fixed retries using Pi's global backoff (2, 4, and 8 seconds by default), even when ordinary retry is disabled. If these fail, use SSE with a fresh full global retry budget.- Recovery: After five minutes on SSE, the next real request starts one logical WS probe. Transport failure renews the cooldown; success sends full context once on a fresh socket, then later requests can use deltas again. Probes never run in the background.
- Explicit
websocketandwebsocket-cachednever downgrade; they follow the global retry settings. Failed partial output is kept in history but omitted from automatic retry context. - Use case: Recover from a socket or proxy interruption without restarting Pi or repeatedly sending full context after WebSocket recovery.
- Limits: Logical attempts may include existing bounded protocol repairs before output. SDK callers need a stable
sessionIdand an outer retry owner for the same policy; sessionless SDK calls retain their prior behavior. - Extensions can still inspect/reset session recovery state through
getOpenAICodexWebSocketDebugStatsLazy(sessionId)andresetOpenAICodexWebSocketDebugStatsLazy(sessionId?)from@earendil-works/pi-ai/compat(orpi-aiin the extension runtime). Reset also clears counters; omitting the ID resets all sessions. - Details: Network and retries
- Patch branch:
patch/codex-websocket-recovery
- Use cached WebSocket continuations for ordinary OpenAI Responses, including API-key authentication, Sign in with ChatGPT, and custom compatible endpoints.
autotries WebSocket first for allopenai-responsesendpoints and uses the same bounded recovery and SSE cooldown policy as Codex. Unsupported proxies may incur connection attempts before fallback; choosesseto avoid them. Explicit WebSocket modes never silently downgrade.- Connections and continuation state are isolated by endpoint and authentication. Without an eligible Response checkpoint, a dropped connection is rebuilt with full local context, then subsequent successful requests can send only new input. Connection-local state alone does not preserve the old connection's server-side cache or guarantee prompt-cache hits.
- Use case: Reduce repeated context uploads in tool loops while recovering from transient socket failures without restarting Pi.
- Limits: New ChatGPT sign-in tokens use the public Responses endpoint, not the legacy Codex backend. Custom gateways must support the Responses WebSocket protocol; a Chat Completions-compatible endpoint alone is not sufficient.
- Patch branch:
patch/responses-websocket-transport
- Allow
settings.retry.nonRetryableErrorPatternsto fail-fast on gateway-specific terminal quota/limit error messages without expanding the built-in retry classifier.- Use case: Stop retrying when a gateway returns a known terminal quota or limit message.
- Patch branch:
patch/retry-non-retryable-patterns
- Send the full request instead of a cached OpenAI Codex Responses WebSocket continuation when the input delta is empty.
- Use case: Retry an unchanged request without reusing a stale continuation that contains no new input.
- Patch branch:
patch/ws-cached-empty-delta
- Show assistant provider errors immediately while Pi's global retry policy runs, without copying the same error into every unexecuted tool preview. Errors remain visible after a successful retry and transcript reconstruction; exhausted retries, non-retryable errors, and cancellation remain visible without pretending the previewed tools executed.
- Use case: See why a Responses WebSocket request is retrying without seeing a separate false failure for each tool. Cancelling during retry backoff remains visible after transcript redraw or session resume; its saved display record never enters model context.
- Limits: This changes interactive error presentation, not retry classification, attempt limits, backoff, transport fallback, or real tool execution results.
- Patch branch:
patch/retry-error-presentation
- earendil-works/pi#6234: make Esc abort recover from lifecycle hooks, extension hooks, provider setup, provider streams, or listener dispatch that never settle.
- Use case: Recover control when Esc is pressed during a hook, provider setup, stream, or listener that does not settle.
- Patch branch:
patch/esc-abort
Resume stored Responses state after a socket reconnect or session restart without replacing local conversation history.
- Use case: Send only new input after reconnecting or reopening a session when the endpoint still retains the verified response.
- Enable: Eligible cached transports default to
responseCheckpointMode: "always"and an absent exclusion list behaves as[]. UseresponseCheckpointMode: "declared"to require declared capability, orresponseCheckpointExclude: ["*"]to opt out. See settings. - Compatibility: Use
autoorwebsocket-cached. Indeclaredmode, custom endpoints need verified persistent Responses support andcompat.supportsResponseCheckpoints: true; generic OpenAI compatibility or a response ID is not proof. The defaultalwayspolicy can try without that declaration. SSE, uncachedwebsocket, and unsupported Codex/ChatGPT modes retain their existing behavior. - Companion plugin: The independent OpenAI API plugin's checkpoint guide covers its settings, privacy and recovery. When loaded on the fork, that extension remains the sole request owner.
- Privacy: Enabling checkpoints requests remote
store: true. An explicit payload-hookstore: falsedisables durable use and capture; a server'sstore: falseprevents capture. Check the service's retention policy before enabling this. - History: Full session JSONL remains canonical. Bounded assistant metadata is reused only after exact active-branch, request and credential/endpoint scope validation; invalid metadata falls back to full history. There is no side database.
- Limits: No universal retention time, prompt/KV-cache hit, reduced billing, or live-service durability guarantee. Existing validation uses loopback fixtures, not every real gateway or account-isolation policy.
- Details: Settings, endpoint capability, SDK policy and repair boundaries, and maintenance ownership and validation record.
- Patch branch:
patch/responses-websocket-transport
Losslessly reduce model-upload bytes without changing JSON or image data. HTTP senders use a conservative encoding fallback policy; Responses WebSockets negotiate compression separately.
- Visibility: The default Working indicator appends the actual algorithm, for example
SSE ZstdorWS/continuation DEFLATE. Names use their standard casing:Zstd,gzip,DEFLATE,Brotli. Uncompressed or unobservable compression keeps the protocol label unchanged. - Details: Request compression — supported paths, codec levels, refusal rules and compatibility limits.
- Companion plugin: Host requirements and bridge integration.
- Patch branch:
patch/request-compression
Pi stores sessions as plain JSONL, exactly as upstream writes them, and does not compress them itself. Extensions, forks, grep and child processes keep reading ordinary text, and no compression work runs while the agent works.
- Use case: Save disk space with transparent compression from the operating system or filesystem (for example NTFS compression, btrfs or ZFS) instead of a Pi-specific format.
- Guidance: The built-in
/session-disk-compression [folder]prompt has the agent inspect the session folder, measure it read-only and recommend the best transparent compression setup. It changes nothing without explicit approval. A same-named user or project prompt overrides it. - Tip: The first interactive start shows a one-time tip about the prompt, then saves the global setting
sessionDiskCompressionHintasfalse. Pi never inspects the filesystem for it. - Compatibility: Sessions that earlier downstream releases (1.5.0-xz.399 until this change) wrote in compressed form are no longer read. They are standard Zstandard frames plus skippable frames; recover one with
zstd -dc FILE > FILE.plain, then replace the original. The--enable-compress-sessionsmaintenance flag and theenableCompressSessionssetting are removed. - Details: Disk compression.
- Patch branch:
patch/session-compression
Pi owns every subprocess it starts and stops the whole tree, including cmd &, double forks and setsid descendants, when a task is cancelled or times out or when Pi exits. Command output, exit status, interaction, timeouts and the moment a command returns are unchanged.
- Use case: background jobs and MCP servers no longer outlive the session; the model can see running tasks with
process_listand stop them withprocess_kill. - Default on. Opt out per invocation with
--no-process-ownership, or for nested invocations withPI_NO_PROCESS_OWNERSHIP=1; both skip the helper entirely. An enabled build with a missing helper fails instead of silently opting out. - Build control:
PROCWARD=0builds without the helper (GentooUSE=procward). It is a build capability, not a runtime switch. - Work that must outlive Pi: the built-in
persistent-background-tasksskill hands it to an external service manager or an existing tmux server. - Limits: not a security sandbox. macOS cleanup is best effort, not kernel containment. On Windows, Job close on owner loss can end Pi before shutdown hooks run.
- Details: Process ownership: integration, process tools, platform guarantees and verification.
- Patch branch:
patch/process-ownership
Presentation-only changes: layout, selectors, thinking display, startup screen.
- Show the current model request's actual established protocol beside the default Working indicator:
Working(SSE),Working(WS/full), orWorking(WS/continuation).- Responses WebSocket requests show
fullwhen sending full context andcontinuationonly when the prepared request uses a validatedprevious_response_id. This follows the actual request, not the configuredwebsocket-cachedpreference; first requests and reconnects showfull. These labels do not claim a prompt-cache hit. - Use case: Tell whether a request uses WebSocket or has fallen back to SSE, including Claude and custom endpoints that use built-in adapters.
- Limits: This describes only Pi's connection to its configured endpoint, not a proxy's upstream hop. Unknown custom streams have no suffix unless they report through the optional
onTransportcallback. Tool execution and retry backoff do not retain a prior request's protocol. Explicit extension working messages remain unchanged; protocol status is not saved in conversation history. - Patch branch:
patch/provider-transport-indicator
- Responses WebSocket requests show
- Preview thinking in one scrolling line by default, following the newest text without growing the transcript. Preview rows render Markdown styles and retain the same tail when thinking ends. When earlier content is hidden,
… (N chars)reports the omitted visible characters; narrow terminals can reduce the hint to….Ctrl+Tcycles preview, full text, and static-folded styles;Ctrl+Oalso expands or folds thinking with tool output.- Use case: Keep the latest reasoning next to the following tool call or answer, and open the full reasoning only when needed.
- Limits: Fullscreen mouse clicks toggle individual thinking blocks during or after streaming, and their state survives completion. A later global display action reapplies its state. Regular terminal mode uses keyboard controls and leaves mouse selection to the terminal. This changes presentation, not the model's thinking effort or saved reasoning.
- Details: Thinking display settings, Keybindings
- Patch branch:
patch/thinking-preview
- In fullscreen mode, the input toggle and automatic dock collapse follow the same scrollback state as
Jump to latest message. Each visit starts collapsed: the standard editor retains one editable draft line between its borders, while completion menus, selectors, and custom panels such as ask are hidden without resetting their state. UseExpand input/Collapse inputbeside Jump to change the layout without leaving scrollback. On narrow terminals the toggle appears above Jump. Resizing and incoming output retain the choice; returning to latest restores the full dock.- Use case: Read history while an ask questionnaire is open, then expand it or return to latest to continue with the saved answers.
- Limits: Hidden panels do not receive typing, Enter, or right-click paste. Stacked controls need at least two terminal rows; short layouts may clip editor borders to keep both controls visible.
- Patch branch:
patch/compact-input-dock
- Size built-in selection panels to their allocated terminal rows in fullscreen and regular mode. Search and the highlighted choice stay visible as the software keyboard opens or closes; Enter confirms that highlighted choice. This covers model/scoped-model, OAuth, extension selection, fork, settings/theme, session, tree and resource configuration, including CLI
--resumeandpi config.- Use case: Open
/modelon a phone with the software keyboard shown, browse the list, and confirm the choice that is visibly highlighted without hiding the keyboard. - Limits: Custom components retain their existing rendering unless they opt in. Extremely small viewports cannot show every detail; resize notices mark omitted details, and extension choices cannot be confirmed while their explanation does not fit. Fullscreen PageUp/PageDown still scroll the transcript; selector page shortcuts can be rebound. Scrollback continues to hide panels without losing their state.
- Patch branch:
patch/responsive-selectors
- Use case: Open
- Hide
[Skill conflicts]/[Prompt conflicts]/[Extension issues]/[Theme conflicts]startup diagnostic blocks by default; enable them withshowStartupDiagnostics: trueinsettings.json.- Use case: Keep the startup screen clean unless actively debugging resource conflicts or extension loading issues.
- Patch branch:
patch/slow-hook-tui-only
- Show the prompt-template or skill command you typed, such as
/review src/a.tsor/skill:review check this, instead of its long expansion. This applies to chat messages, session restore,/treepreview, search, copy and refill, the/forklist and refill, input history, and the queued-message list. Turn it off withcollapseExpandedInput: falseor in/settings.- Use case: Find and re-edit an earlier
/reviewcall in/treeor/forkwithout scrolling through the template body. - Limits: Only the terminal UI changes. The model,
/retry, RPC, SDK, JSONLmessage.contentand HTML export keep the full expansion. Pi stores the typed template command as the optional__raw_inputTextfield on the message entry only when an interactive template expanded into different text. Skills are rebuilt from the stored skill block and get no extra field. Messages from older sessions, extensions or SDK calls show their stored text. Refilled commands expand again with the current template when you submit them. - Details: Settings, Session format
- Patch branch:
patch/collapse-expanded-input
- Use case: Find and re-edit an earlier
- Show a typed prompt template in the chat as a collapsed
[prompt]card, styled like the skill card. Click it or use the tool-output expand key (app.tools.expand,Ctrl+Oby default) to read the expansion that was sent.- Use case: Keep long template bodies out of the chat while still being able to check exactly what the model received.
- Limits: Only messages with a recorded command get a card, independent of
collapseExpandedInput. The expanded state is kept in memory only; a restored session starts collapsed. - Details: Prompt templates
- Patch branch:
patch/prompt-invocation-cards
Show pending changes in the message list: Model: old → new and Thinking level: high → xhigh. Each line settles in place to its new value when the next request starts.
- Use case: Change thinking effort while a response streams and see that the new choice applies to the next request, not the request already in flight. Model and thinking hints remain independent of each other and ordinary status messages.
- Controls: Keyboard cycling,
/thinking, and the thinking selector use the same feedback. Saving a default keeps its separate confirmation. Reselecting the current model or effective thinking level adds no switch indicator. - Limits: Hints report the effective session choice after model-capability clamping. They are interactive display feedback, not provider acknowledgements or persisted conversation entries; changing a choice does not restart or modify an issued request.
- Patch branch:
patch/message-origin
Model catalog refresh, selection, and provider-facing fixes.
- Wait for extension-provider registration refreshes before startup resolves configured models, while preserving synchronous registration and caller-owned cancellation.
- Use case: Start with models an extension registered asynchronously instead of resolving a stale catalog.
- Patch branch:
patch/model-refresh
- Rebind active and scoped sessions to refreshed same-ID model metadata so context percentages and automatic compaction use the current context window.
- Use case: Keep context percentages and compaction limits correct after a provider refreshes model metadata.
- Patch branch:
patch/model-refresh-session-rebind
- Add
--refreshtopi --list-modelsso the command loads extension providers, force-refreshes every loaded catalog, then prints refreshed models while preserving cached entries for failed providers. Keeppi update --modelsextension-free for Pi-managed catalog maintenance.- Use case: Refresh and inspect a third-party provider's latest model list from one non-interactive CLI command.
- Patch branch:
patch/model-refresh
- List models with a configured override first in
/settings-> Default thinking level per model, with configured and unconfigured models each sorted byprovider/model-id; the current model is preselected instead of pinned to the top.- Use case: See and edit saved per-model thinking levels without scanning the whole model list.
- Patch branch:
patch/model-thinking-sort
- Preserve the
/modelpicker's highlighted row when a background model catalog refresh completes while the picker is open. The selection is restored by provider and model id after the list rebuild; a removed model falls back to the existing current-model highlight. Mirrors the scoped-models selector behavior.- Use case: Browse the model list and press refresh-in-progress without the cursor snapping back to the first row mid-selection.
- Patch branch:
patch/model-selector-refresh-selection
- Drop user and assistant messages whose content is empty or whitespace-only in
transformMessages, the choke point shared by every provider converter. Tool results, assistant messages with tool calls, and blocks carrying thinking/text signatures are always kept.- Use case: Extension-injected custom messages (for example watchdog inquiry fold markers) become empty user messages that some providers reject, e.g. Gemini
contents.parts must not be empty. - Patch branch:
patch/ai-drop-empty-messages
- Use case: Extension-injected custom messages (for example watchdog inquiry fold markers) become empty user messages that some providers reject, e.g. Gemini
- Replay tool call arguments exactly as the model sent them on OpenAI Responses (including Azure and Codex), Chat Completions, and Mistral. Pi keeps the original arguments text when a fresh encoding would change it (for example
{"command": "echo one"}instead of{"command":"echo one"}) and replays it while it still encodes the current arguments; changed arguments are re-encoded. Anthropic, Bedrock, and Google send arguments as objects and are unaffected. Follows Codex, which stores Responses arguments as the raw string.- Use case: A gateway that emits spaced arguments no longer makes Pi's replay differ from the stored response, so response checkpoints can be captured.
- Patch branch:
patch/preserve-tool-arguments-json
- Defer automatic threshold and successful-response overflow compaction until another model request needs the context. Completed idle replies do not generate an unused summary; tool-loop compaction, extension/queued continuations, manual
/compact, and immediate overflow/length retry recovery remain supported. No new setting is required.- Use case: Stop after an answer without paying for a summary that would only be useful if the session continued.
- Details: Automatic compaction
- Patch branch:
patch/defer-threshold-compaction
- Insert a compaction summary at its kept boundary instead of appending it at the leaf: the summary becomes the parent of the first kept entry (
A -> S -> B -> C), and the leaf does not move. The interactive transcript shows the summary before the kept entries both live and after reload, and/treenavigation back to a kept entry still uses the summary.- Use case: Make the visible transcript match what the model receives, and stop a rollback to a kept entry from dropping the summary and compacting again.
- Patch branch:
patch/compaction-boundary-insert
- Optionally summarize threshold compaction in the background. Off by default; turn it on with the Background compaction On/Off row next to Auto-compact in
/settings(persisted ascompaction.background). It requires Auto-compact. With thresholdT = contextWindow - reserveTokens, Pi starts atT - min(32768, (1 - backgroundStartRatio) * T)(backgroundStartRatiodefaults to0.85and bounds the earliest start), snapshots the branch, runssession_before_compactand the summary while the agent keeps working, and persists it at the next request boundary; messages appended meanwhile stay verbatim. If threshold compaction, overflow recovery or manual/compactarrives first, it waits for the pending summary instead of cancelling it or generating a concurrent summary. A still-valid result is committed once and reused; failure or staleness permits ordinary foreground fallback only after settlement. Manual reuse reportsCompaction skipped: reusing completed compaction, even with custom instructions; fallback preserves those instructions and extension hooks. Cancelling a foreground waiter does not start fallback. Turning the row or Auto-compact off revokes unclaimed work; a summary already claimed by a foreground caller continues.- Status: a separate
Compacting(background)...indicator uses an italic label while retaining the existing spinner and colors. It coexists with Working/transport/retry, using──inside the editor border and|in a standalone row. Waiting does not add another foreground compaction indicator, and each status clears independently. - Accounting and failures: each provider attempt (including retries, discarded results and partial two-stage failures) is recorded once as a usage entry of the originating session, attributed to the response model, and not counted again through the compaction entry. A failed background summary shows one nonblocking warning without provider text and is not retried until history compacts.
- Use case: Keep a long tool-heavy run going instead of stalling on a summarization request every time context fills.
- Limits: compaction starts earlier, so long sessions compact somewhat more often; a summary that waited for the threshold keeps a longer tail. Late usage of a job whose in-memory session was replaced is dropped instead of being written into the new session. Latency and cost benefits depend on the provider and were not benchmarked.
- Details: Background compaction
- Patch branch:
patch/async-compaction
- Status: a separate
Extension tooling, skills, and subprocess environment.
-
Detach eligible long-running AI tool calls into session-owned managed executions, with
tool_taskcontrols for status, bounded waits, and cancellation requests while preserving exactly one result for each original tool call.- Use case: Let Pi continue reasoning while opted-in shell or extension work runs, without turning untrusted tool output into a steering message or losing cancellation/lifecycle ownership.
- Patch branch:
patch/managed-tool-executions
-
Record where each message came from — interactive terminal input, an extension, RPC, the SDK, or command-line arguments — as an optional
originfield persisted in session history. Extensions read the structured origin through input and message events and history; identical text from different senders stays distinct for plugins, queue matching, and resume. Extensionpi.sendUserMessage()/pi.sendMessage()calls and custom messages returned by hooks are attributed automatically to the calling extension without any per-extension change, and the model sees a deterministic source annotation on nonhuman entries while provider protocol roles stay unchanged. Nonhuman transcript entries render with a source heading and the same gray tool-style body used for tool output.- Use case: Two extensions and a human can each send the literal text
continue; plugin code can tell which extension produced a message, and the model sees that an instruction came from extensionfoorather than from interactive input. Display-hidden injected context still surfaces as a folded source heading in the transcript, so it stays inspectable. - Limits: Origin is provenance metadata, not a security boundary. It does not authenticate a remote or human sender, does not infer authorship of older unrecorded messages, does not stop a plugin or a raw PTY key injection from supplying input, and does not audit arbitrary context or provider-payload transformations. An extension message is not a system/developer instruction and grants no new authorization. Display-hidden nonempty messages render as a folded source heading; empty control markers stay invisible and keep empty model content. Legacy messages show an unrecorded-source heading rather than claiming human authorship. Per-item click toggles only in supported fullscreen mouse mode, and the existing global
Ctrl+Oexpansion state supersedes item overrides. Expanding a folded source heading keeps the current transcript scroll offset instead of jumping to the end, so a heading clicked near the bottom stays in view while revealing its body. - Details: Extensions, Message types, Session file format
- Patch branch:
patch/message-origin
- Use case: Two extensions and a human can each send the literal text
-
Support per-package Skill visibility overrides through
skillOverrides.<name>.disableModelInvocation, retaining manual/skill:<name>invocation and project-over-global precedence.- Use case: Keep a skill available to
/skill:<name>while preventing automatic model invocation. - Patch branch:
patch/skill-overrides
- Use case: Keep a skill available to
-
Show awaited extension handlers exceeding
slowSyncHookThresholdMs(plain-value handlers) orslowAsyncHookThresholdMs(promise-returning handlers) only in interactive TUI, with synchronous handlers in warning yellow and asynchronous handlers in default gray. During shutdown, show the current handler while waiting, clear fast handlers, and keep slow handlers on the terminal without writing timing diagnostics to session history, model context, RPC/print events, or disk. Both thresholds default to-1(disabled); set a value>= 0insettings.jsonto opt in.- Use case: Diagnose slow extension hooks without persisting diagnostic records.
- Patch branch:
patch/slow-hook-tui-only
-
Set
LC_ALL=C.UTF-8,LANG=C.UTF-8,LANGUAGE=enat startup so tools, MCP servers, and extension subprocesses run with an English locale while Pi's own UI locale stays unchanged. Override with globalenvOverrides(KEY=VALUElist, replaces the default);[]disables.- Use case: Keep tool output the model reads in English on a non-English desktop.
- Patch branch:
patch/env-overrides
-
Drain already-queued output before ending native process collection at the post-exit silence deadline.
- Use case: Preserve final protocol bytes when the process runner resumes after its deadline with output already queued.
- Limits: The existing 100 ms silence grace is unchanged; silent descendant-held pipes still stop after that grace.
- Patch branch:
patch/env-process-output-drain
Patches with no direct user-facing surface: test stability, fork CI plumbing, benchmark bounds.
-
Retired
patch/chord-registry-gc-observation: upstreamcd5e3d2a6242250db693d1a3e49bb7a3184c76c9captures test WeakRefs before releasing readers, and7e713da291119a91bdf91b0f8bba1bb801782fc9gives file-summary fixtures deterministic timestamps. The upstream collection and exact ordering assertions remain; no skip is added. -
Diagnose native environment tests with an independent build-target architecture oracle, retained-output tool fixtures, per-stream output equality, real foreground-job readiness and monotonic cold listing cancellation/recovery observations.
- Limits: Listing setup preserves all 10,100 entries and has its own measured 60000ms bound; the cold daemon request, actual aborted error and both same-connection recoveries retain their separate 5000ms operation deadline. Foreground readiness retains 100 polls at 20ms and the 20000ms case deadline. Independent stdout/stderr arrival order is not an equality oracle; exact content per stream, successful tool results, missing-file rejection and nonzero exit remain checked. Darwin wrong-target JSON exposes actual child status and selected failures only after strict equality-rejection checks. Observations do not prove REQUEST/CANCEL transmission or child exit.
- Patch branch:
patch/env-native-test-fixtures
-
Make the coalesced-reload auth-storage test deterministic by writing a different-size payload, so mtime-tick collisions cannot make the reader take the stale cached path.
- Patch branch:
patch/quarantine-auth-storage-flake
- Patch branch:
-
Bound and report startup benchmarks: emit synchronous startup stage/completion markers, exit benchmark runs without waiting on arbitrary handles, and bound fd/rg version probes.
- Patch branch:
patch/startup-benchmark-exit
- Patch branch:
The Esc and manual-retry patches share patch/agent-run-failure-seam. Managed tool executions are integrated before those two patches, and patch/esc-abort carries the managed-execution abort drain. See downstream maintenance for the current integration rules.
-
patch/model-catalog-test-fixturesis retired from sync because upstream now supplies the Xiaomi MiMo 2.6 fixture updates. Tests and assertions remain upstream; no skip is added. The retained source differs only in descriptive names. -
patch/tui-synchronized-cursor-fleetis temporarily retired from generatedmain. Its synchronized-output implementation can emit excessive terminal data and now conflicts with upstream's bounded main-screen writer. The source branch remains retained for a corrected design and independent validation; do not mask the product conflict with a CI resolver.
patch/mimo-thinking-toggle-testis no longer integrated: upstream now contains the identical Xiaomi replay assertion correction. The source branch is retained; the replay and thinking-toggle checks remain enabled upstream.- Provider-transparent Responses remote compaction and its dependent pre-provider compaction patch have been removed, and both source branches have been permanently deleted. Classic compaction remains the default path. A third-party extension such as
@ogulcancelik/pi-codex-compactioncan provide Codex-native remote compaction without adding provider-specific behavior to core. - The remote-client run-end wait patch has been retired: upstream now waits on
run_end/run_suspendoperation boundaries before resolving an accepted prompt response (operationBoundaries/boundaryWaitersinpackages/coding-agent/src/experimental/client.ts), which covers the same transcript-lifecycle guarantee without a timeout heuristic. The source branch is kept asretired/remote-client-run-end-wait.