---
id: submodule-server-agent
type: submodule-design
status: active
title: agent — in-process pi sessions
parent: module-server
depends-on: [module-contracts, module-pi-delegation, module-pi-subagents, module-pi-background-commands]
references: [module-spec-graph, central-integration, submodule-server-extensions]
tags: [pi]
---

## Responsibility

The in-process `pi` engine: a current shared model/auth runtime generation for pre-session work and future
chats, the lifecycle of `AgentSession`s (one per chat tab, rooted in a workspace's worktree and retaining the
runtime generation they were created with), Pi resource/skill loading (including portable
cross-agent skill discovery + a pre-session skill catalog), the **extension-UI bridge** that turns pi's
in-process `uiContext` dialog calls into WS frames, the host-owned **`ask_user_question`** tool + its
answer-injection path, and the **restart repair** that keeps re-opened transcripts provider-valid.

## Boundary

- **Owns:**
  - `piRuntime` (the current shared `ModelRuntime` generation — pi's canonical model/auth facade for
    catalogs, credentials, availability, login/logout, and request dispatch). Sibling consumers use the
    `usePiRuntime()` callback to capture the current generation rather than receiving a mutable singleton;
    host boot initializes it before any model work, while later Central artifact changes prepare and atomically
    activate a fresh generation. Tests configure the factory before initialization. Every runtime is created
    with **ambient network OFF** —
    `allowModelNetwork: false` **plus a scoped `PI_OFFLINE` around construction** (pi 0.81 derives the
    runtime's ambient-network default from that env at construction; the option now gates only the
    create-time refresh — in 0.80.x it fed both; the scoped value is restored immediately, a user-set
    one untouched — pinned by `piRuntime.test.ts`): catalog reads stay local (builtins + models.json +
    the persisted models-store), because a network-enabled `refresh()` (pi 0.82 folded the old
    `reloadConfig()` into it) awaits remote pi.dev catalog
    checks with no timeout — on the `provider.status` and host-boot paths that stalls wherever
    egress is slow or blocked. The one deliberate opt-in to
    live catalogs is the single-flighted **`refreshCatalogs(runtime)`** (issue #98, mirroring pi's own
    `/model`) behind two triggers: a detached task from `model.list` only
    (`listAvailableModels` fires it, then serves the current snapshot — the picker read never awaits the
    network; broader triggers — `model.default`, new-chat default resolution, host boot — were considered
    and declined, so those read the snapshot through `listSettledModels`) and
    **awaited** via `model.refresh` (`refreshAvailableModels`, the picker's freshness affordance: await
    the refresh, then serve the post-refresh snapshot **with `complete`** — `refreshCatalogs` resolves a
    `CatalogRefreshOutcome` saying whether the pass it waited on settled, and that verdict travels to the
    client as `RefreshedModels.complete`, because a capped wait can only promise a *current* list, not a
    settled one, and catalog authority must key on the difference). Per-call `refresh({ allowNetwork: true, force })`,
    where **`force` is the caller's intent, not a constant**: an *implicit* trigger (`model.list`, opening
    the picker) leaves it off and pi's **4h provider freshness throttle** decides whether anything is
    fetched, while a *user-initiated* refresh (the picker's Refresh row → `model.refresh({force:true})`)
    bypasses it — inside that window pi returns early **before issuing any request at all** (its
    `If-None-Match` revalidation included), so an unforced explicit refresh would fetch nothing at all. **Single-flight per runtime instance** (pi's
    `refresh()` doesn't dedupe concurrent calls) **keyed with the kind**: an implicit caller joins any
    pass, a forced caller never joins a throttled one (it would inherit the no-op) and instead queues
    behind it. The **15s budget** (pi's model-selector one) is applied **twice**, both on **unref'd**
    timers (must not hold a shutting-down host or a test process open): as `models.refresh`'s **abort**
    signal (a hung refresh must self-expire or single-flight would wedge) *and* as the ceiling on what a
    **caller awaits**, because the signal bounds neither pi's unsignalled `forceRefreshAvailability()`
    fan-out after it nor a forced pass queued behind a throttled one — without it one slow provider leaves
    every picker's refresh row spinning. A timed-out caller serves the registry as it stands (reporting
    `completed: false`) while single-flight keeps tracking the unbounded pass (so it cannot start a second concurrent refresh); failures emit only a closed generic/count warn log (never provider ids or errors) + are swallowed, never the picker's problem; **`PI_OFFLINE`**
    (pi's env convention) disables it — resolving as a *completed* pass, since with nothing fetchable the
    registry as it stands is the settled answer; the e2e webServer env and the manager's unit suite set it for
    hermeticity. The **provider-credential surface** over this runtime —
    `provider.status` + in-app login — lives in the sibling `auth` module (which consumes the shared
    `usePiRuntime` callback), **not** here.

    Candidate preparation takes only the reviewed opaque Central path set, builds a fresh runtime, applies the
    composition root's invariant generation initializer (the source-mode e2e host uses it for its gated fake
    providers), records that pre-opaque provider-id allowlist for `provider.status` together with each id's
    display name at that moment, and then applies the opaque
    extensions once through PI's public headless loader. The generation separately records ids introduced
    or replaced by that loader (`opaqueProviderIds`) through opaque registration-identity comparison, never
    configuration values. The allowlist stays the full pre-opaque set: a novel Central id was never in it
    and so never becomes a row, while a replaced built-in (`anthropic`, `openai`, …) stays visible and
    auth attributes it to Central by intersecting the two sets. (Subtracting the opaque set from the allowlist
    — briefly done for analytics attribution — made every Central-routed provider vanish from the Providers
    section; the two facts must stay separate.) Thus auth never inspects or emits Central's provider
    configuration, while an add/remove/replace can never drop process-local provider registrations. The
    initializer must be configured before the first generation and runs for every candidate. The path is the
    only artifact fact this module receives;
    it never reads, parses, hashes, snapshots, logs, copies, or serves the file. Initializer/extension/loader/
    provider failures discard the candidate and collapse to a closed `load-failed` outcome; raw diagnostics
    never reach `pi.extensionUi`, the wire, logs, analytics, persistence, or snapshots. Auth owns file watching,
    coalescing, and stale-candidate rejection; agent only prepares and activates a generation.

    `getSessionRuntimeGeneration` exposes a live session's retained generation for synchronous host metadata
    reads. Activation changes the current pointer for pre-session reads and future session creation; it never
    mutates, drains, or recreates existing sessions. A live session keeps its original runtime generation. A disk session
    attached after activation keeps its saved model when that model is available in the current runtime.
    If it is unavailable, PI chooses the current default without changing the saved model on open.
    PI records the replacement when the user sends a message, so later restarts restore that model.
    Merely opening a chat preserves its original model for when that provider returns. With no available
    model, the transcript remains readable and no placeholder model is persisted as a replacement.

    Every models **read** goes through **`settledAvailableModels(runtime)`** — pi's
    `getAvailableSnapshot()`, **never `getAvailable()`**: that one awaits `refreshAvailability()`, which
    returns the pending per-provider auth fan-out *or starts one*, all unsignalled — so reading through it
    would hand `model.list` (whose contract is to answer without touching the network), `model.default` and
    every inbound model-ref check an unbounded wait, and would escape the refresh deadline one line after
    applying it. The snapshot is what pi's last *settled* pass concluded (written at `create()`, after every
    `refresh()`, and on login/logout), plus a provisional entry pi writes the moment a provider with a stored
    credential or configured key is registered — config and native (`registerNativeProvider`) registrations
    alike, so a Central or delegation-mirrored provider is readable before its availability pass lands. Being
    the one read makes the picker, default, and model resolution agree within a generation.
  - `modelContext` — a narrow settings adapter for the `contextWindow` override in pi's shared
    `getAgentDir()/models.json`, not a second model registry. It lists the OpenAI Responses / Codex
    Responses models from `settledAvailableModels` whose effective budget still equals the contracts'
    272K editing minimum (the cap this setting exists to lift), plus any model that already carries an
    override so it can always be reverted; each entry pairs pi's effective `contextWindow` with the
    file's explicit `override` (`null` = pi default). Eligibility is derived from pi's catalog, never
    from a model-id list, so catalog defaults above 1M stay untouched by a bulk save. A save validates
    the contracts' 272K–1M range first, patches `providers.<p>.modelOverrides.<id>.contextWindow` for the
    target — or, for `available`, every eligible pair the contracts' `isSharedModelContextTarget` admits, so
    a shared save never rewrites an override outside the range that only a targeted save can touch — with
    `jsonc-parser` so comments, BOM and unrelated
    configuration survive, prunes override objects it empties (never `providers`), refuses invalid JSON
    or a read-only file rather than patching it, then writes a temp file beside the resolved target with
    the original's mode (`0o600` for a new file) and renames it into place — following a symlinked
    `models.json` to its target, and creating a dangling link's target rather than replacing the link. Saves are serialized in-process; a changed file is followed by one
    network-disabled `runtime.refresh` on the current generation and the host's `provider.changed`
    signal; a no-op save does neither. Every read also refreshes locally first so external pi CLI edits
    appear. Live sessions keep the model they were created with; new chats resolve the updated metadata.
    pi owns schema validation and the effective value; error messages are generic and never carry file
    contents. Accepted gap: a Central rebuild whose runtime loaded the file before a save and activated
    after its refresh serves the old budget until the next read refreshes it.
  - `agentSessionManager` — sessions keyed by `session.sessionId` (each `Entry` also tracks its
    `workspaceId`), `createSession({ cwd, workspaceId, model?, thinkingLevel? })` → `createAgentSession(...)`
    with a per-session `SessionManager` **and `buildSessionSettings(cwd, projectTrusted)`** (the user's
    real settings + an in-memory `images.autoResize:false` override — never persisted — so the `read` tool
    sends image files **raw**, bypassing pi's photon/WASM resizer that the single-file binary can't bundle;
    the web UI downsizes user-attached images itself at attach time — `apps/web`'s `chat/imageAttachment`
    caps the long edge at 1568px — and the `imageGuard` extension below is the in-context second line of
    defense). The override is **re-applied after every `settings.reload()`**: pi's `SettingsManager.reload()`
    rebuilds settings from disk and drops `applyOverrides`, and the resource loader reloads settings on every
    `reload()` — including inside `createAgentSession` — so a one-shot override never reached a prompt. Since
    pi 0.87 the same setting also governs prompt-attached and tool-result images, so the override is what keeps
    pi from rewriting user text with `[Image omitted…]` hints (which would defeat the client's optimistic-echo
    dedup). Delegated children run on the same settings: `delegation` binds `buildSessionSettings` as the
    core's `buildChildSettings`, which receives the trust the parent context's `isProjectTrusted`
    answers (`liveParentContext`; pi-delegation decision #31, issue #604). A shared `registerSession`
    publishes each event
    tagged with its id + `bindExtensions({ mode:'rpc', uiContext })`. The event projection retains the
    final `agent_end` assistant's reported terminal metadata and attaches it to `agent_settled`, so the
    wire has one authoritative automatic-work terminal even when compaction/retry happens between those
    events; it forwards rather than re-derives pi's result. A `compaction_end` is separately projected to
    a **fresh allowlisted event**: its `result` carries only `tokensBefore` and optional
    `estimatedTokensAfter`, never pi's summary, entry id, usage, or extension details. Tool
    `tool_execution_end` / `tool_execution_update` frames drop `structuredContent` from the (partial)
    result: pi's value for programmatic callers (bash puts up to 1 MiB of raw output there), never
    persisted and never rendered, so forwarding it would only grow every live frame and the browser
    store. The live entry retains
    that settlement in `SessionSummary.lastSettlement` for reconnect after Pi removed a failed attempt from its rebuilt
    context; a new `agent_start` exposes explicit `null` (no current terminal) so an older persisted failure
    cannot reappear mid-run, while disk sessions remain transcript-authoritative. A live summary also
    carries pi's queue snapshot (`SessionQueueState`, only when non-empty): `queue_update` fires only on
    changes, so this is the read-side seed that lets a client attaching mid-run render messages queued
    before it connected. Each queue lane also retains the complete content of browser-queued messages only
    while Pi reports the corresponding text entry pending. That transient mirror exists solely because Pi's
    destructive queue API returns text but drops image blocks; Pi's queue events remain authoritative for
    membership/order. The host projects only a conservative `hasImages` aggregate into summaries/events, so
    image bytes do not ride the ordinary read stream.

    **One membership override compensates for a Pi defect: a delivered image-only (empty-text) queued
    message is never cleared.** Pi keys its on-delivery queue removal on the delivered user message's text
    (`contentText`), so a message queued with images but no text stays in Pi's `_steeringMessages` /
    `_followUpMessages` forever and its "Steering"/"Follow-up" chip never disappears. The manager therefore
    counts such deliveries per lane (`stuckEmptyDeliveries`): on a user `message_start` whose text is empty,
    whose content carries an image, and for which Pi still reports more empty-text entries in a lane than
    already counted, it increments that lane's counter and **synthesizes the emptying `queue_update`** Pi
    withheld. Every place that reads a lane for display — the projected `queue_update`, the transient-mirror
    sync, and `queueStateOf` — first drops that many empty-text entries from Pi's list, so a later genuine
    `queue_update` cannot resurrect the phantom. The counter is per live entry only (Pi's ephemeral queues
    never survive a process restart) and resets whenever `clearQueue()` empties both lanes.

    **Remove this whole override on the pi bump that ships the upstream fix** (earendil-works/pi#8612,
    still open when last checked). Once Pi clears empty-text image deliveries natively, drop
    `stuckEmptyDeliveries`, `displayedLane`, the synthesized `queue_update`, and the `effectivePendingCount`
    adjustment. The removal gate is the installed code, not the PR state: on every pi bump grep the installed
    `agent-session.js` for the `if (messageText)` guard around `this._steeringMessages.indexOf` — while that
    guard is present the workaround is still required; when it is gone the fix has shipped.

  - **Normalized session state** is one host projection over orthogonal facts, never a second agent runtime.
    Live derivation reads Pi execution/queue state, the question phase registry's exact expected/waiting id,
    the extension-dialog registry, final settlement, and explicit-Stop intent. Needs-input outranks working
    for presentation while the underlying execution may remain running. Only `agent_settled` creates a
    normal completion; one terminal classifier distinguishes success, error, length, abort, and missing work.
    Explicit Stop records its current run id as cancelled before abort and stays quiet; an unfinished run
    found after restart becomes interrupted.

    **Background work holds unread.** While an idle chat still owns a running/stopping background command
    or a queued/running delegation child, its completion is reported but `completionUnread` stays false,
    so neither the attention dot nor an out-of-app notification fires while the agent's work is still in
    flight; needs-input is never held. The command change listener and the delegation lifecycle listener
    republish the parent's state on a coalesced `setImmediate`, after the same-tick completion delivery
    that wakes the parent has already flipped it to running — so the last finishing child never flashes
    the dot before the woken turn. A completion that does not wake the parent (user stop) releases the hold
    on that republish; a delivery gated by a reload or trash hold also releases first, and its later wake
    clears the unread again. Disk-only sessions have no live work and never hold. The same fact is published as
    `backgroundWork`, so clients show the idle chat as working (contracts' `isSessionWorking`) instead of
    quietly finished.

    State ids come from Pi's active session-entry chain: run/interruption from the latest user entry,
    completion from the decisive assistant entry, questions/dialogs from their interaction ids. Disk state
    is reconstructed from the complete active branch; a file read/parse failure fails the all-workspace
    snapshot rather than omitting a row. Receipt initialization runs unless both metadata files load (first
    install, or a file persistence set aside as unreadable, which is logged): it marks existing completion
    ids handled but never suppresses unresolved input. Because it runs before serving, it is the one
    best-effort reader: an unreadable transcript or session directory is logged and left unbaselined
    instead of blocking host startup, while the later snapshot keeps failing until the file is repaired.
    Receipt writes are serialized and atomic.
    Sessions publish full state records on semantic change. Pending extension dialogs retain their
    full request so reconnecting clients can render and answer the exact blocker rather than seeing an
    unusable needs-input marker.

    `listSessionStates` returns every top-level live/disk session; `acknowledgeCompletion`
    compare-and-sets only the current exact unread completion; `markWorkspaceUnread` drops the receipt of
    the workspace's most recently active session (latest branch-entry timestamp) that
    `canMarkCompletionUnread` admits — idle, unblocked, background-free, a non-cancelled read result —
    and `markWorkspaceRead` receipts every unread completion in the workspace; both cover disk-only sessions
    and publish each changed record. The shared collector awaits disk discovery *first* and then assembles
    live and disk sources in one synchronous pass (live wins by id), so a chat that attaches mid-scan is
    counted once instead of slipping between the two lists — the same holds for `listSessionStates`; `nudgeSession` atomically skips needs-input,
    queues while running, or prompts while idle. `SessionSummary.state` and `session.state` use the same
    derivation, so a client proves the exact rendered completion by id rather than inventing lifecycle.

    New-session and pre-session entrypoints capture the current generation; operations on a live session use
    that session's retained runtime. `abort` remains available as the cancellation control path.
    `prompt`/`steer`/`followUp` (with images) /
    — **both `promptSession` and `followUpSession` resolve the delivery mode against the session's
    LIVE `isStreaming`, never the caller's belief about it**: `prompt()` throws mid-turn (so it falls
    back to `steer`), and pi's `followUp()` only *enqueues* into a queue that a run already in flight
    drains (so on an idle session it falls back to `prompt`, else the message parks forever — the way a
    `review.sendBatch` into a re-attached review chat marked its comments sent to an agent that never
    saw them) / **`clearQueueSession`** (Pi's `clearQueue()`: drains both queues but returns only text,
    while the host snapshots its reconciled transient mirror first and returns complete per-message text +
    images. Pi emits the emptying `queue_update`). Its optional text-only precondition rejects before
    touching Pi whenever either tracked lane has queued images; manual compaction uses that guard, while
    **`abortSession(..., true)`** synchronously claims the Stop and drains the queue in one manager operation.
    If an accepted question result is still persisting, Stop grants it a bounded grace period before signalling
    Pi's abort; this prevents an async post-tool hook from deadlocking Stop while still preserving the normal
    fast path. It drains once more immediately before abort and appends those late arrivals to their original
    lanes; it then waits for idle and returns the complete ordered queue, so deferred Stop cannot race a
    continuation or lose images /
    **`removeQueuedSession(sessionId, kind, index)`** — per-item queue removal, which Pi's
    API lacks (queues are bare string arrays, `clearQueue` is all-or-nothing): drain via the complete-content
    path, drop `lane[index]` (out-of-range → `removed: null`, everything re-queued), and re-queue each keeper
    with its images in order (`steer()`/`followUp()` per lane — each re-queue emits its own `queue_update`, so
    clients converge by events alone). **No-loss guarantee:** if the run settled during the operation the
    re-queued keepers would park forever (Pi's queues only drain inside a run), so the idle case drains them
    through the same idle-delivery fallback as `followUpSession` — the first becomes a `prompt`, the rest
    steer into the run it starts; delivery timing may degrade across that race window, content is never lost
    (pinned by the idle-fallback unit test) —
    `setModel` / `setThinkingLevel` / **manual `compact` guarded per session** (a second overlapping request
    is rejected before Pi can overwrite its one compaction controller; an active Pi compaction also blocks
    entry) / `getSessionStats` (+ contextUsage) / `getSessionCommands` /
    `listAvailableModels` / `listSettledModels` (the same snapshot without starting a refresh) / **`clampThinkingForModel`** (pi's `clampThinkingLevel` for a `{model, level}`
    pair — `model.clampThinking`; the host uses it so defaults and live-session effort changes follow Pi).
    Earlier, #394 showed ThinkRail's `available[0]` differed from Pi's pick and hit a proxy 400. ThinkRail
    now resolves defaults host-side from `AppConfig`, falling back to the first available model; it always
    passes the chosen model explicitly so the UI and session agree. Accepted risk: the first available model
    may not be the provider default; users can set one in Settings → Models. Plan review uses this same
    `resolveNewChatModel({})` for unset reviewer overrides: AppConfig `defaultModel`/`defaultEffort`, with
    the first available model and `medium` effort as fallbacks.

    **Models cross the wire as `WireModel` (never pi's raw `Model`):** `toWireModel` projects a
    `Model` onto the wire's **allowlist** (see `WireModel`) — so `baseUrl`, `headers`, extension/provider
    routing data, and any other field are excluded by
    default — and the inbound side re-resolves the ref by `{provider,id}` via `resolveWireModel` against
    **`settledAvailableModels`**: `createSession` uses the current generation, while `setModel` uses that live
    session's retained runtime. Therefore a model newly shown in the global picker can be unavailable to an
    older live chat and fails with a closed model-unavailable error rather than crossing generations. Pi uses
    `Model.baseUrl` verbatim, so a client's baseUrl
    is never trusted (blocks disclosure *and* arbitrary-URL injection). The **hydration read side** —
    `listSessions(workspaceId, cwd)` (live sessions
    **unioned with on-disk** ones pi persisted under `cwd`, live winning on id → `SessionSummary[]` tagged
    `live`; before treating the **detached** disk list as authoritative it strictly scans every transcript
    header and verifies pi returned every file, so an unreadable/malformed/skipped transcript rejects the
    read rather than masquerading as absent and being tombstoned by reconnect reconciliation. A `.jsonl`
    whose first parsed entry is not a session header is not a transcript — pi's own listing skips those
    files, and extensions keep sidecar logs there (e.g. pi-automode's `<session>-pi-automode.jsonl`) — but a
    file with no parsed entry at all still rejects. A registered live
    session's own exact `SessionManager.getSessionFile()` path is excluded from that disk preflight: its
    in-memory entry is already authoritative, and pi may truncate/rewrite that path while the host lists,
    so treating the transient physical state as a detached corrupt chat would blank every chat on reload) +
    `getSessionMessages(sessionId, workspaceId, cwd)` (re-opens a disk session into the manager if
    not live, first resolving any model named by the transcript in the active process runtime,
    retrying pi's renamed providers under their current ids; when
    that model is unavailable, PI selects the current default without persisting a model change on open;
    PI records the replacement when the user sends a message. Legacy transcripts with no persisted model
    reference also use PI's model resolver—then returns `{ summary, messages }` —
    `TranscriptMessage[]`: the pi-canonical subset **plus
    `custom` messages**, which carry the `ask-user-answers` replies the questionnaire card pairs by tool
    call id, **plus `compactionSummary`**, pi's durable marker for the messages compaction summarized away —
    kept precisely because pi's resolved transcript is all that survives, so dropping it would hand the
    client a chat that starts mid-conversation with nothing to explain the gap. Which roles those are is
    **not decided here**: the filter is contracts' `isTranscriptMessageRole`, shared with `history`'s index
    so the two cannot drift and shift `messageIndex`), plus **`ensureSessionAttached(sessionId, workspaceId, cwd)`** — the same single-flighted
    re-open with no transcript read, for a caller that only needs the session *promptable* again (the
    review send's follow-up into an existing chat). It answers **`false` only when the id names no transcript
    in that cwd** — the sole case a caller may recover from by starting a new chat — and **throws** on
    every other re-open failure, so a merely-unreadable session can never be mistaken for an absent one
    and silently forked; the disk half is what survives a host **restart** — and re-attaching runs
    **`repairDanglingToolCalls` (the `sessionRepair` sibling) BEFORE `createAgentSession` seeds its
    context**: a host death mid-tool leaves the final replayable assistant tool batch unpaired, every
    provider rejects such a leaf (the chat would brick), and appending behind a live session would desync
    its in-memory state — so the missing results are paired at the one choke point every post-restart
    session passes. Repair is **tail-only and replay-aware**: pi positionally closes a pending tool batch
    before examining the next assistant message, then drops `error` / `aborted` / `length` attempts. Pi never
    executes tool calls from a length-truncated response because their arguments may be incomplete; those
    calls therefore repair with ordinary error results, never an answerable ask ack. Failed attempts
    never contribute candidates but still close an older one; any later user, custom,
    compaction, or assistant message makes that gap ineligible for a persisted leaf append. Only unique
    results whose call id **and tool name** match the final candidate batch may follow it, and parallel
    calls already carrying valid results are left alone. This prevents a late result from surviving
    without its omitted call and permanently poisoning OpenAI replay. Generic
    missing calls get pi's abort convention (`isError` "Operation aborted (host restarted…)"); a dangling
    ask gets the canonical ack (`details {kind:"ack"}`), so its card remains answerable while the transcript
    is provider-valid;
    **`answerQuestion(sessionId, toolCallId, result)`** — the `ask_user_question` reply path (see the
    `askUserQuestion` bullet); **`settleSessionsForShutdown(timeoutMs)`** — the polite half of shutdown:
    synchronously close every command service and subagent completion owner and start every hidden-child
    cascade before aborting any streaming parent. Preserve parents with a recoverable live ask phase
    (`expected`, `waiting`, or `answer-accepted-uncommitted`); dispose every hidden child (including those
    whose parent is idle), include cascades already pending from concurrent removal, and wait for all under the one
    bound. Shutdown atomically closes answer admission before it snapshots phases: an expected/waiting ask
    stays dangling for ack repair, while an already accepted answer reaches its native persisted result and
    then the continuation is aborted. A reply racing after that snapshot is rejected rather than accepted and
    lost during disposal. Destructive teardown drains both Pi input queues before abort/disposal, including
    recoverable chat deletion, workspace archive, polite shutdown and emergency disposal. Pi's
    `abort()` only signals the current core run and waits for session idle; post-run handling can continue
    queued input with a fresh abort controller, so abort alone can restart work and strand disposal.
    Removal/archive/deletion reuse Stop's entry-based drain and bounded accepted-answer grace, draining
    again immediately before abort to discard input queued during that grace. Public commands retain their
    deletion guard; captured-entry teardown bypasses it so archive still settles tombstoned parents.
    Polite shutdown instead preserves unanswered asks for restart repair, drains again at an accepted
    result's persistence boundary, and retains its existing shared shutdown budget. Synchronous disposal
    (including failed preparation) clears queues before disconnecting Pi, after the host unsubscribes so
    disposal does not publish an extra queue event.
    Explicit user Stop synchronously claims an unanswered ask before signalling Pi; when
    Submit already won it gives that exact result boundary a bounded grace period, then signals abort even if
    persistence is still pending. The answer RPC resolves only when `turn_end` contains the accepted native
    result; a replaced or missing result rejects it. Every disposal path abandons the registry before
    unsubscribing so accepted-answer promises cannot strand.
    `abandon()` is process-disposal plumbing, not semantic cancellation: it unblocks the in-memory tool only
    immediately before synchronous session disposal, and real-`SessionManager` restart coverage pins that its
    returned result is not persisted ahead of attach-time repair. `disposeAllSessions` remains the synchronous
    emergency stop, but registers its best-effort child cascades
    in the same pending set; `getSessionWorkspaceId(sessionId)` (the live session→workspace
    lookup the host's `set_title` handler keys on); `removeSession`/`disposeAllSessions`;
    **`removeWorkspaceSessions(workspaceId, cwd?)`** (the **archive teardown**: close session admission for
    the workspace before its first await, capture every registered parent, synchronously close its resource
    owners, and start parent abort/removal while concurrently draining preparations from the retired
    workspace generation. A preparation that finishes afterward disposes its unregistered owners/session
    instead of publishing into the archived workspace. An unanswered question is not preserved for restart
    during destructive removal. After both barriers settle, dispose every live session for the workspace
    **unconditionally** — bypassing the per-chat delete
    guard that `removeSession` enforces, so a chat whose recoverable delete is mid-trash cannot abort the
    teardown loop and strand its siblings — then delete pi's on-disk transcripts rooted at
    the worktree `cwd` — pi's `SessionManager` is append-only, so purge = `list(cwd)` then `rm` the files
    whose recorded `cwd` matches, never `rm -rf` the encoded dir since pi's cwd→dir encoding can alias
    distinct cwds; `cwd` omitted on a double-archive skips only the disk purge);
    **`deleteSession(sessionId, workspaceId, cwd)`** (mark it deleted before any await so an in-flight disk
    attach cannot register afterward; that tombstone also makes a retained live entry non-addressable to
    **every session command, including `session.dispose`, for the full delete transaction**, so another
    client cannot append a turn behind the pending trash move or destroy the rollback target. **The
    transaction is single-flighted per session id**: a concurrent second trash click (another tab/client)
    for the same chat joins the running transaction (or is rejected as unknown when a foreign workspace
    names the id) rather than starting a rival one — two owners of the shared tombstone would let the
    loser's failure roll it back mid-move and briefly re-open the chat — and **only the transaction that
    installed the tombstone clears it on failure**, so an earlier successful deletion's permanent tombstone
    survives a later spurious re-delete. Abort a live turn if needed but retain the live entry, resolve a
    live transcript from that session's own `SessionManager` (never a lossy directory listing), otherwise
    use the same strict disk lookup above, move the exact matching-cwd transcript to the OS trash via
    `trashFile`, then dispose the live entry and publish `SessionDeletedPayload` for client convergence;
    a newly created empty live chat whose reserved JSONL path has not materialized has nothing recoverable to
    trash and is disposed directly. Any lookup or trash failure throws, rolls back the tombstone it installed,
    restores command access to the same
    transcript/live entry, and publishes nothing; there is deliberately no permanent-unlink fallback behind
    a recoverable UI action);
    `setSessionPublisher` + `setSessionCreatedPublisher` (broadcast the initial `SessionSummary` after
    `createSession` registers a new host-owned session—not when an existing transcript reattaches—so peer
    frontends discover it without inheriting placement) +
    `setSessionDeletedPublisher` + `setSessionManagerFactory` seams.
  - `oneshot` — one-shot LLM completions **without** an `AgentSession` (no tools/extensions/disk):
    `completeOnce(request)` picks a model from the shared runtime's authenticated set and dispatches a
    single `runtime.completeSimple()` — pi's canonical provider-agnostic request path, which resolves
    the model's auth itself (OAuth refresh included) and also serves providers that only implement
    `streamSimple` (extension-registered ones). `pickModel(tier)` = the model choice: `cheap` prefers a
    curated small/fast allowlist ∩ the authenticated set, else the cheapest by per-token cost; `default`
    = first available; `null` when nothing is authenticated. This is the primitive the `assist` tasks
    (plan summaries, PR drafting) run on — the only place model **dispatch** happens outside a session.
  - `webUiContext` — `createWebUiContext(sessionId, currentToolCall?)` builds the `ExtensionUIContext` pi
    calls (dialogs round-trip to the browser, fire-and-forget methods push). A dialog names the tool call
    it is about (`toolCallId`) so the web asks on that call's card: the manager passes pi's own
    `agent.state.pendingToolCalls` and a dialog anchors only while **exactly one** call is running (the
    common gate-before-a-tool case; parallel calls stay unanchored rather than guess), and
    `selectForToolCall` anchors explicitly and carries the call's `toolInput` (the MCP guard). `setExtUiPublisher`
    (server→client push seam; an optional `ExtUiAudience` narrows a push to clients below a protocol
    version), `resolveExtUi` (browser reply), `cancelExtUiForSession` (on dispose, and once pi accepts a
    user message — a steer or follow-up pi `"queued"`, or an idle prompt whose `preflightResult` says
    `"started"`/`"queued"` — which then answers every pending dialog of that chat; a message an input
    extension `"handled"`, or one preflight rejects (no model, no credentials), leaves the dialog open, and
    the queue's own re-queuing in `removeQueuedSession` cancels nothing),
    `notifyExtUi`, `notifyExtensionError` (pi's `ExtensionError` → one client-visible `error` notify
    carrying extension + event + cause — the cause capped at 500 chars because `error.error` is
    remote-shaped, and the extension named by its **directory** when its file is an anonymous
    entrypoint (`SKILL.md`, `index.ts`), never "Extension SKILL.md failed"; a bare
    "An extension failed." is what made #277 unreadable from the UI alone). The manager's
    `bindExtensions({onError})` wraps it in `reportExtensionError`, which does **two** things the notify
    cannot: for a live entry, it writes one `warn` to the rotated host log carrying the **full**
    `extensionPath` and the extension's own `stack` (rehydrated onto an `Error` so it lands in the structured `err` field — the
    chat gets the short name, the log gets the unambiguous one, and a crash stays findable after the tab
    is closed), and it **gates the client push** on `entry.registered`, the explicit flag
    `registerSession` sets when it puts the entry in the map. The event path's `sessions.get(id) === entry`
    cannot be reused: `bindExtensions` runs inside `prepareSessionEntry`, *before* registration, so the
    stricter form would suppress the `session_start` failure #277 is about. Nor can *absence* from the map
    stand in for "not registered yet" — `disposeSession` deletes without leaving a tombstone, so a disposed
    entry is indistinguishable from an unregistered one, and a late error would be pushed at a client that
    can never drain it. The log is never gated for a live entry, but an entry the host has **disposed**
    (`entry.disposed`, set before `session.dispose()` in every teardown path) downgrades the report to a
    single `debug` line with no stack and no client push: pi 0.87's `finishTurn` agent-loop hook outlives
    `AgentSession.dispose()` and still dispatches `turn_end`/`context` boundaries into the runner we just
    invalidated, so its “stale ctx” and “could not resolve the persisted assistant entry ID” reports are
    echoes of our own teardown, not extension crashes; pi 0.86 disconnected from the agent first, so they
    never surfaced. For a live entry, it attaches an `Error` **only when pi supplied a stack**: several of
    pi's own `emitError` sites omit it (`runner.js` message_end, `agent-session.js` command/`<runtime>`),
    and synthesising one there would record the *host's* stack — pointing the reader at
    `prepareSessionEntry` instead of the extension, which is the opposite of why the line exists.
    **Members split three ways, not two.** *Untranslatable* ones are inert no-ops and rightly so — they take a
    TUI `Component` factory a web host cannot render (`setFooter`, `setHeader`, `setEditorComponent`,
    `custom`, `setWidget`'s factory overload; the string-array overload **is** rendered).
    *Translatable* ones must behave: **`theme` is a real `Theme`** (`plainTextTheme`) whose every
    decorator returns its input unchanged. *Translatable but unimplemented* is the third group and is named
    here so the split does not read as exhaustive: `setEditorText` / `pasteToEditor` are forwarded to the
    host by pi's own rpc mode and a web composer could honour them; ours stay inert until something needs
    them. What separates the theme from that group is the cost of being inert — an unimplemented editor
    call loses one feature, an unimplemented theme kills the whole extension on its first line. `getAllThemes: []` / `getTheme: undefined` match pi's own
    rpc mode; `setTheme`'s `{success:true}` is a known lie, tracked separately — a web host has no TUI
    theme to switch to, so pi's rpc-mode form (`{success:false}`) is the honest answer.
    `plainTextTheme` subclasses pi's `Theme` and overrides `fg`/`bg`/`style`/`bold`/`italic`/`underline`/
    `inverse`/`strikethrough`/`getFgAnsi`/`getBgAnsi`; `getThinkingBorderColor` /
    `getBashModeBorderColor` stay plain only because pi routes them through `this.fg` — an inherited
    guarantee, so `webUiContext.test.ts` pins them explicitly. **Three inherited members still answer for
    the terminal, as data rather than escapes:** `getColorMode` (`truecolor`, from the constructor — pi's
    `ColorMode` is `"truecolor" | "256color"` with no "renders no colour" value), and the `colors` /
    `appearance` getters, which resolve every `""` token to pi's guessed terminal defaults (for example
    `colors.accent` is an RGB value) and report pi's detected light/dark appearance. No honest plain
    answer exists for any of them. They cost nothing while an extension colours *through* the theme —
    every such path returns plain text — and only bite one that reads a mode or colour and then emits ANSI
    on its own, which is the unsanitised-bridge gap tracked outside this module. Its colour table exists
    **only** to satisfy the constructor signature: every method that would turn a colour into an escape is
    overridden, and the members that still answer for the terminal read the constructor's *mode* or pi's
    terminal guesses, never an escape. A pi
    bump that changes the palette breaks the build as a *notice that the theme surface moved*, not as a
    defect.
    **Rejected alternatives** (the one place these decisions are recorded): (1) `{} as
    ExtensionUIContext["theme"]` — the #277 bug itself. It assumed the TUI members are unreachable in
    `rpc` mode, but `ctx.ui.theme` is called by the **extension**, not by pi's renderer, and pi's own rpc
    mode hands out a live theme. (2) An object literal implementing `Theme` structurally — impossible
    without a cast: `Theme` carries private fields. (3) A real `Theme` built from blank colours, no
    overrides — pi maps `""` to the *default-colour* escape (`\x1b[39m`), not to nothing, so status text
    would reach the browser as literal escape bytes. (4) Forwarding pi's exported `theme` singleton — it
    is a `Proxy` that throws `Theme not initialized` until `initTheme()` runs, and `initTheme` is called
    only from pi's own CLI entrypoints, never when pi is embedded via `createAgentSession`. Every
    embedder of pi-as-a-library hits this; an upstream fix would not reach us until a deliberate pi bump.
  - `askUserQuestion` — the host-owned **`ask_user_question`** pi custom tool, registered per session with
    a session-bound phase registry. New and reopened parent sessions create one `AskUserQuestionWaiters`
    in `createParentSession`, shared by the SDK `customTools` definition and the registered entry.
    SDK custom tools take precedence over same-name extension tools, including after resource reload.
    This keeps the host's structured questionnaire and answer channel paired: an installed terminal
    questionnaire must not replace execution with `ui.input` while the web client still renders the host
    card. Other tools, commands, and hooks from that extension remain available. An eligible
    live call is **sequential and blocking**: after validation its `execute` waits for
    `session.answerQuestion`, then returns the person's real
    `AskUserQuestionResult`/`buildQuestionnaireResponse` as the native tool result. Eligibility is shared:
    an assistant stopped by `error`, `aborted`, or `length` cannot execute an ask. A `message_end` normalizer
    makes the first ask the response's sole tool call (non-tool content stays; sibling calls are dropped for
    the model to re-issue after the answer), avoiding Pi's sequential-abort hole where unexecuted siblings
    receive no result. The question array has **no tool-level maximum**: one round carries every question
    answerable now, while each question retains the 2–4 option bound. Header/label/`recommendedReason`
    lengths are **advisory** (stated in the field descriptions, not schema `maxLength`): pi's schema
    validation rejects the whole call and echoes every argument back, so a few extra characters would
    cost a failed card plus a full retry, while the card already wraps/scrolls long text. Questions that
    depend on an open answer wait for a later round; the multi-round interview norm itself lives in the
    workflow family's `asking-user-questions` concept skill ([[submodule-workflow-skills]]).

    The registry tracks `expected` (eligible call observed), `waiting`, `answer-accepted-uncommitted`, and
    `stopped` through `turn_end`. This includes Pi's real asynchronous gap from `tool_execution_start` through
    pre-tool hooks to `execute`: graceful shutdown freezes new answer admission and preserves an expected call;
    an answer accepted before that freeze remains authoritative and is persisted before shutdown/Stop aborts
    its continuation. Stop-first synchronously marks an expected/waiting call stopped, so a later answer cannot
    reverse the winner. Semantic validation still gates execution: an answer accepted in the pre-execute
    window is acknowledged only if the real ask returned and `turn_end` contains its result; validation error
    or a missing result rejects the answer RPC rather than hanging or claiming success. Every expected call Pi
    does not execute is cleared at `turn_end`. The answer RPC resolves the phase and acknowledges only after
    the matching result reaches the persisted `turn_end` boundary. Explicit Stop drains the queue and aborts
    an unanswered phase with a stable stopped error; after Submit wins, Stop defers Pi abort until the answer
    persists and then ends only the continuation. Either ordering leaves one terminal provider-valid result.

    **Typing instead of answering supersedes the live card, exactly as after a restart.** `steerSession` and
    a streaming-time `promptSession` queue the text in Pi's steering lane first and, only when `steer()`
    reports the `queued` disposition (an extension `input` handler that returns `handled` queues nothing, so
    no user turn would follow the ack), `supersede()` every expected/waiting call: the tool returns the same canonical ack (`ASK_ACK_TEXT`, `details {kind:"ack"}`)
    the restart repair writes, Pi drains the steering message as the next user turn, and the card derives
    `superseded` from the transcript through the one shape it already understands (ack + later user
    message). A later answer RPC fails with the `superseded` answerability error; a call already in
    `answer-accepted-uncommitted` is never superseded (the answer wins and the steering delivers after it).
    Scope is deliberately narrow: only the user's own composer send supersedes — the follow-up lane
    (Cmd+Enter), steering queued *before* the card appeared, `removeQueuedSession`'s internal re-queue, and
    nudges (which already stop at `needsInput`) all leave the card open.

    A process restart deliberately changes only the continuation mechanism: attach-time repair writes the
    canonical ack (`details {kind:"ack"}`) only for an eligible dangling ask before `createAgentSession`,
    leaving the card answerable but the session idle. A length-truncated ask receives the same error repair
    as any other non-executable tool call. With no live phase, `answerQuestion` injects the existing
    `ask-user-answers` custom message through `sendCustomMessage({triggerTurn:true})`. Thus the question
    survives without restoring a JavaScript promise or calling low-level `Agent.continue`; an uncommitted
    Submit simply appears again. Queue entries remain Pi-owned and live-only by explicit scope. The card
    derives both forms from the transcript (native live result versus repaired ack + custom answer).

    Rejected alternatives: immediate ack on every live call lets Pi drain input queued *before* the card
    and supersede it unseen; restoring a dangling invocation exactly requires a lifecycle-safe resume API Pi
    does not expose; a durable host queue/SQLite outbox is unnecessary when only the question must survive;
    a client-side "skip then steer" pair races the answer path and leaves a decline in the transcript
    where the restored path leaves an ack.
  - `sessionRepair` — `repairDanglingToolCalls(sessionManager)`: the restart safety net (rationale under
    the manager bullet above). Pure over pi's `SessionManager` (compaction-aware via
    `buildSessionContext`; idempotent; appends only missing results from the active tail batch) —
    unit-tested against `SessionManager.inMemory`, including failed-attempt and historical-gap replay.
  - `imageGuard` — the oversized-image guard: an inline extension (`oversizedImageGuard`, one of
    `buildResourceLoader`'s shared factories and the whole delegated-child base set) hooked on pi's
    **`context` event** (fired before every LLM
    call, live sessions included). **Anthropic-family only**: the caps are Anthropic's model-level rules,
    so the handler gates on the context's active model (`isAnthropicFamilyModel` — native
    `anthropic`/`anthropic-messages`, or a Claude model id through Bedrock/Vertex/aggregators; unknown
    model ⇒ no-op) and every other provider's image context passes through untouched. It sniffs each image block's pixel dimensions straight from the base64
    header bytes (PNG/JPEG/GIF/WebP — no codec, never strips what it can't sniff; **bounded work per
    pass**: only a 256KiB decoded prefix is ever materialized — a JPEG whose SOF lies beyond it sniffs as
    unknown, not stripped — and each block is sniffed exactly once per pass) and replaces any block
    violating a provider rule with a text note naming the violated rule plus a re-attach hint. Five
    rules, in order: the **provider-accepted media types** (`ACCEPTED_IMAGE_TYPES`, shared with the
    composer via `contracts` — pi forwards an image's media type verbatim, so a legacy `image/heic`
    block 400s the whole request; stripping it heals sessions poisoned before the composer refused such
    files); the **4.5MB encoded-base64 payload ceiling** (`IMAGE_MAX_BASE64_BYTES`, shared
    with the composer via `contracts` — pi's own headroom under Anthropic's 5MB API limit, compared
    against `data.length` since the wire carries base64, so it applies even to unsniffable formats); the **8000px per-side hard cap**; the **count-aware 2000px cap** once the
    whole context carries more than 20 images — stripping changes the very count that selects that cap,
    so 2000px violators are stripped **largest-first only until the survivors fit back under the
    threshold** (18 small + 3 at 2500px ⇒ one stripped, the other two stay legal under 8000px); and the
    **request-wide `REQUEST_IMAGE_BASE64_BUDGET`** (24MB of base64, headroom under Anthropic's 32MB
    per-request cap — several per-image-legal blocks can still overflow the whole request), enforced by
    stripping survivors **largest-first until the aggregate fits**. This is what un-bricks a session poisoned by an oversized image
    (history is re-sent every turn, so one bad image 400s forever): sessions are append-only and the host
    has no image codec (the autoResize tradeoff above), so the guard transforms the **outgoing context
    only** — session file and transcript stay untouched, and a stuck chat recovers on its very next
    message. The count-aware cap also degrades a raw >2000px `read`-tool image to a note instead of a
    brick once a session crosses 21 images. Pure core (`guardOversizedImages`, `imageDimensions`)
    unit-tested with hand-built header bytes.
  - `delegation` — ThinkRail's embedding of the portable **`pi-delegation`** core +
    **`pi-subagents`** layer ([[module-pi-delegation]], [[module-pi-subagents]]): binds what only
    the host knows — the delegation root under the data dir (`<dataDir>/delegation`),
    `scope = workspaceId`, and the manager's `liveParentContext` projection (`ParentContext`, core
    decision #23), including the exact `ModelRuntime` retained by that parent session. Existing
    parents and their children therefore stay on their runtime generation across a Central change,
    while parents created afterward project the new generation. The host-wide `getPiRuntime` resolver
    is passed as the core's dynamic fallback rather than captured at service creation. One
    `DelegationService` per workspace is cached (`delegationServiceFor`, synchronous — nothing awaits
    at bind time). A host-injected `setSubagentConcurrencyResolver` supplies each service's per-chat
    limit at creation, and `refreshSubagentConcurrency(workspaceId?)` re-resolves and live-resizes the
    cached services (core `setMaxConcurrentPerParent`) after a global or workspace limit change; `subagentsFor(workspaceId, isEnabled, canDeliverCompletion)` creates one retained portable
    `Subagents` owner per parent; its extension is injected on every resource load. A host-injected
    `setSubagentsEnabledResolver` maps that
    workspace id to its current effective policy without creating an `agent` → settings/workspaces edge.
    The predicate reaches the extension's launch-time guard and initial/reload activation. For live
    policy changes, `refreshSubagentTools(workspaceId?)` removes/adds `Agent` +
    `get_subagent_result` through pi's active-tool API: idle sessions update synchronously, streaming
    sessions retain only a pending reevaluation applied at `agent_settled`, and repeated changes resolve
    the latest policy then. Session registration re-resolves once after async extension binding and before
    creation is published, so a policy mutation cannot fall into the bind-before-registry gap. Policy changes never replace the retained
    owner, so already-running detached children finish and retain completion delivery; a disabled launch is still rejected immediately by the live
    predicate even before a streaming parent's tool set can be refreshed.
    The plan-review `request_review` tool follows the same live-toggle shape: it is always registered, but
    `setAgentReviewEnabledResolver` (host-injected, global — no `agent` → settings edge) decides whether it
    stays in a session's active set, and `refreshAgentReviewTool(workspaceId?)` applies a change idle-sync /
    streaming-deferred to `agent_settled`, exactly like the subagent tools. Because `setActiveToolsByName`
    rebuilds the system prompt from active tools' guidelines, dropping the tool drops its guidance too. Only
    the tool is gated — the `startPlanReview` button path is a separate host seam. See `submodule-server-host-plan-review`.
    **Registry extensions** follow the same shape, keyed by extension name instead of workspace. A
    host-injected `setDisabledExtensionsResolver(() => ReadonlySet<string>)` (global — no `agent` →
    settings edge; a throwing resolver means nothing disabled) is read by `buildResourceLoader` at **every
    loader reload** (snapshotted beside project trust), so the gated registry factories skip a disabled
    extension and `extensionsOverride` omits its `<inline:…>` entry — new parents never load it — and by
    `childExtensionFactories()` when a hidden child's loader runs. `refreshExtensionTools()` updates live
    sessions: tools whose `sourceInfo.path` belongs to a disabled registry extension leave the active set
    (remembered per entry so re-enabling restores exactly the withheld tools, never ones that were inactive
    by default) idle-sync / streaming-deferred to `agent_settled`, latest policy wins, and
    `setActiveToolsByName` drops their guidance with them. Hooks of a disabled extension keep running in an
    open session until its next resource reload — pi cannot unload an extension, and reloading on every
    disable would bust the prompt cache. The reverse is the one reload: an enabled extension the session
    never loaded (created while it was off) and that did not fail to load triggers a gated
    `requestSessionReload`. Registration applies the same reconciliation, and a completed reload reapplies
    it without requesting another reload, so a toggle that lands mid-reload converges.
    The **`set_title`** tool (`titleTool.ts`) is how chats and workspaces get named: the main agent calls it
    with `chat_title?` / `workspace_name?` / `branch?` (English kebab slug). It is always registered and
    active, and listed via `promptSnippet`; toggling it off after naming would rebuild the system prompt
    mid-session and bust the prompt cache. Its `promptGuidelines` carry the naming rules: once per
    conversation, as the **first action** of the first turn with a concrete task, even for a one-line answer
    (or right after reading a linked PR/issue/ticket). Names are in the user's language, and a PR/issue/ticket
    uses `<Verb> #<n> <title verbatim>`. Guidelines alone proved too weak (live e2e, Claude Opus: named 1 of
    3 real-task turns; 0 of 3 when the prompt asked for a one-sentence answer). So while the chat (pi session
    name) or its workspace is still unnamed, a `before_agent_start` hook adds a state-specific
    **`pending-naming`** system-prompt section ("this chat has no title yet … call set_title with chat_title
    before your other tool calls … otherwise ignore this note"); with it the same real-task turn named 3 of 3.
    The section and the guidelines name the fields still missing (`workspace_name` and `branch` while the
    workspace is unnamed) because "once" alone let a call name only the chat. Its wording is
    deliberately low-pressure: an earlier "first action … even when the answer is one sentence" made the model
    add narration preambles on unrelated tool-only turns. The section disappears once both are named, which
    costs one prompt-cache miss per chat, early in it. The write policy and the workspace half of that state are
    not here: the host injects both through `setTitleToolHost({ apply, workspaceNeedsName })`, because naming
    composes `agent` + `workspaces`.
    Cascades: `removeSession`/`disposeAllSessions` fire
    `disposeSessionChildren` — `removeSession` returns that cascade, the **delete transaction
    awaits it before `publishDeleted`/resolving** (safe: the cascade carries its own swallow, so a
    failing child abort can never fail a delete whose transcript is already trashed), and workspace
    archival **awaits it per session** — plus every **pending cascade registered for the
    workspace** (`disposeSession` removes the entry from `sessions` at cascade *start*, so a
    concurrent archive would otherwise see no parent to await while a delete's or remove's child
    cascade is still running; every `disposeSession` cascade registers in a per-workspace registry
    the archive drains — PR #303 review finding + the concurrent half found in the same sweep,
    both test-pinned via a test-gated child turn, deterministic in both directions: red because a
    pre-fix archive `rm -rf`s in its synchronous prefix while the gate is provably closed, green
    because the archive's completion is await-chained behind the cascade. Deliberately **cascades,
    not delete transactions**: archival must stay unblocked by a delete wedged mid-trash — the
    recycle-bin step has unbounded latency and never touches the store; that independence is its
    own pinned behavior) — before `removeWorkspaceDelegation` (drops the service + deletes
    `delegation/<workspaceId>`), so the store is never deleted under a live child — hidden
    children never outlive their workspace.
    `readChildTranscript` serves `subagent.getTranscript` from the store by
    `(workspaceId, parentSessionId, childSessionId)` — the ids are wire strings that become path
    segments, so it rejects path-like values (separators, `..`; the handler additionally validates
    the workspace like every sibling read) — and returns the run's current registry `status`
    alongside the messages, built from the raw entries via pi's canonical projection
    (`buildSessionContext` — the same entry→message path a live `session.messages` takes) and
    filtered through contracts' shared `isTranscriptMessageRole` exactly like `getSessionMessages`
    (a private message-entry loop here once drifted: compaction is an entry *type*, not a message
    role, so a compacted child's transcript lost its `compactionSummary` marker — PR #303 review
    finding, test-pinned; absent after restart/dispose; wire meaning: [[module-contracts]]).
    Pi writes the first transcript file lazily. A registered child belonging to the requested parent
    therefore returns an empty message list with its authoritative status until that file exists;
    queued/running remains pollable, including before the first provider reply. This is not a
    reconstruction from task text. A missing file without that owned handle throws
    `CodedError("SUBAGENT_TRANSCRIPT_NOT_FOUND")` — the **permanent**
    miss the web dialog stops polling on, named on the wire instead of pattern-matched from the
    message ([[module-contracts]] owns the code set; this uses the agent module's narrow
    `@thinkrail/shared/codedError` edge, shared with Chat Resources and mirroring `git`'s use).
    Children opting into extensions
    (`extensions: true` in their definition) get the **curated child set**
    (`childExtensionFactories` in `extensions`, pi `InlineExtension`s): the headless-search policy +
    `pi-web-access` + `pi-spec-graph` + every registry extension's `childExtensions` (named inline,
    from [[submodule-server-extensions]]; none today) — deliberately not the parent's full set
    (rationale + the listed-children carve-out: core decision #25). **Every** child, opted in or not,
    also loads the core's base set (`childBaseExtensionFactories`, same decision): just
    `oversizedImageGuard`, since a child's `read` returns raw images under the shared settings (see the
    `buildSessionSettings` bullet). Web-access reaches the child set via a **named bundled-seam
    field** (`BundledExtensions.webAccessFactory`) in the binary and a Bun `require` in dev — its raw
    third-party `.ts` must stay out of the strict tsc graph.
  - `extensions` — Pi resource wiring. Candidate generation loads the reviewed external Central path once
    through a headless `DefaultResourceLoader` to apply provider registrations, without inspecting it.
    `buildResourceLoader(cwd, settingsManager, getAdmission, excludedPaths, extraFactories?)` then resolves
    Pi's normal settings/package +
    `.pi` / `.agents` extension set, removes that exact opaque identity **before loading**, and explicitly loads
    the remaining paths: sessions use the provider objects already owned by their retained generation, so
    arbitrary Central factory/errors/UI cannot reach `pi.extensionUi`. The Central identity is always excluded
    from session discovery—even if the global artifact changes—so a session cannot mutate its generation.
    That explicit path set is **not frozen at construction**: the loader's public `reload()` is wrapped so
    every reload first re-resolves the set through the host's own `DefaultPackageManager` (current settings
    and trust, `builtin:*` entries by name so `-builtin:*` is honoured) and mutates the host-owned array pi
    reads in place, then relabels discovered-path provenance after the load — pi's `extensionsOverride` is
    not used because it runs after factories have executed. All other user extensions
    retain normal discovery. The loader then adds
    automatic **portable cross-agent skill aliases**, then loads the four bundled pi packages — **`pi-web-access`**
    (`web_search` + `fetch_content`), **`pi-spec-graph`** (the `spec_*`
    tools + its `before_agent_start` rule), **`pi-thinkrail-workflow`** (the workflow-router rule +
    workflow skills), and **`pi-todos`** (the `todo_*` tools + its skill) — and the **ThinkRail extensions
    from the server registry** ([[submodule-server-extensions]]; today `visualize`, whose server half
    injects the strict mermaid validator) as named inline extensions. Existing personal aliases are Claude
    (`${CLAUDE_CONFIG_DIR:-~/.claude}/skills`), Codex (`${CODEX_HOME:-~/.codex}/skills`), Copilot
    (`~/.copilot/skills`), and Gemini (`${GEMINI_CLI_HOME:-~}/.gemini/skills`), **plus each installed Claude
    plugin's `skills/` dir** (read from `~/.claude/plugins/installed_plugins.json` — the resolved `installPath`,
    never a cache sweep, so stale versions and transitive `node_modules/**/skills` are excluded); project-root
    aliases are `.claude/skills`, `.github/skills`, and `.gemini/skills`. The pure
    **`isProjectSkillPath(relativePath)`** predicate is the one server-side definition used by the worktree
    watcher (injected through `host`): it recognizes those aliases plus Pi's native `.pi/skills` and
    `.agents/skills`, so capped filesystem batches carry truthful skill-change evidence without making
    `watch` depend on `agent`. The fixed project/personal alias roots are registered as candidate skill paths
    **whether or not they exist yet**, so a `loader.reload()` picks up one a branch switch / pull / clone
    creates mid-session (plugin dirs are the set installed at construction — a plugin added later
    needs a fresh session); classification still only counts dirs that actually exist. Still never arbitrary
    dot-directory scanning, plugin caches, commands, or nested downward discovery. Pi remains the parser:
    vendor-only macros/hooks/models/subagents/metadata are not emulated. First-name-wins precedence is
    Pi native/configured/shared → ThinkRail-bundled → personal aliases → project aliases, so a repo can
    never shadow your own or ThinkRail's skills; source metadata preserves truthful `project` / `user` scope.
    **Admission gate (`skillAdmission`):** committed **project-scoped** aliases are attacker-controlled for a
    clone and injected into the system prompt, so per-skill they resolve to `load` / `untrusted` /
    `pending-ack` / `disabled` from an **admission context** — the project's `trusted` + `acknowledgedSkills`
    (granting trust acknowledges only what's present, so a later pull/branch skill is `pending-ack` until
    confirmed) + `disabledSkills` / **`disabledGroups`** baselines (a group key = a plugin name, a source tier
    `project`/`personal`/`bundled`/`pi`, or the special `@plugins` — assigned per skill by `skillGroup`, matching
    `SkillCatalogEntry.group`), layered with the workspace's per-skill `skillOverrides` (the trust gate is
    checked before the toggle layer, so an "on" override can never un-gate an untrusted alias, and a per-skill
    `on` beats a group disable). `skillsGate` filters + relabels in one `skillsOverride`; only `load` skills
    reach the system prompt / `/skill:` list.
    The host resolves the context via the **`setSkillAdmissionResolver`** seam (keyed by `workspaceId`, fails
    closed); `buildResourceLoader` takes the resolver as a thunk and `skillsGate` re-resolves **both** the admission
    context (`getCtx`) **and** the live compatibility source set (fresh discovery) on every `loader.reload()`, so
    `session.reloadResources` picks up a mid-session trust grant, skill/group toggle, **or a newly-appeared alias
    dir** — and a late-appearing project alias is still classified + trust-gated, never slipping through as an
    unclassified load. Personal and bundled resources are never trust-gated (only the enable/disable layer), and
    this gate is scoped to the compatibility aliases. pi-native project resources (`.pi/` settings, extensions,
    skills, prompts and themes, `SYSTEM.md`, ancestor `.agents/skills`) follow pi-level trust instead: pi gates
    them on the project-trusted flag ThinkRail derives from `Project.piResourceTrust` and re-applies before
    every load (MCP servers › Trust).
    `listSkillCommands(cwd, admission)` reuses the same gated inputs through a short-lived skills-only
    `DefaultResourceLoader` (no model/session/transcript, no extension factories) for pre-workspace
    autocomplete, cached briefly per `(cwd, admission)`; **`listSkillCatalog(cwd, admission)`** is the Skills
    manager's unfiltered variant (every discovered skill + its `group` + `decision`) — driven with a workspace
    (via `skills.state`) or a project (via `project.skills`, current checkout, no overrides) — and
    **`listProjectAliasSkillNames`** is the notice's present-alias count. The full session loader supports
    **two modes**:
    - **Run-from-source (default):** `additionalExtensionPaths` pointing at the pi packages' raw `.ts`
      entries (pi's loader jiti-loads them — no value-import into our typecheck graph), resolved
      **lazily on first use** (never at module load: the resolve requires `node_modules`, which a
      compiled binary lacks). The workspace packages' `pi.skills` manifests aren't auto-discovered for
      file-path entries — their `skills/` dirs (`pi-spec-graph`, `pi-thinkrail-workflow`, `pi-todos`), the
      host's own skills (`packages/server/skills`: ThinkRail-only guidance such as
      `managing-mcp-servers`, which would be wrong under vanilla pi and so cannot live in a portable
      package) plus the registry extensions' owner-resolved skill roots are wired via
      **`additionalSkillPaths`**; `build-support`'s `skillRoots` lists the same host root for both bundles.
      Registry extensions themselves are never path-loaded: they are the same named inline factories in
      both modes (one composition mode; `{ name, factory }` keeps `<inline:visualize>` in diagnostics).
    - **Bundled launchers (compiled CLI binary and packaged desktop runtime):** the launcher awaits the
      **`registerBundledRuntime({ factories, skillsDir, trashHelpers, webAccessFactory })` seam** before the first session — the same four pi packages as
      **value-imported default-export factories** (pi gives `extensionFactories` full API parity with path loading; what's lost —
      file-relative `baseDir`, per-reload re-evaluation — none of them use) plus a staged on-disk
      skills dir (pi reads `SKILL.md` via plain fs, so skills must live on the real filesystem; the
      bundled runtime uses **only** this staged root — it never resolves an extension-owned package from
      the host's `createRequire`). Registry extensions need no seam field: `@thinkrail/server`'s static
      import of each `@thinkrail/ext-*/server` carries them into the binary and the desktop bundle. The
      seam also performs the **bundled-artifact pi registrations**: pi hides Node-only provider code behind
      bundler-opaque variable-specifier dynamic imports (so browser bundles can't reach `node:http`
      OAuth servers / the AWS SDK), which a single-file binary can't resolve at runtime — every OAuth
      sign-in died with `Cannot find module './openai-codex.js'`. pi ships static registration seams
      for exactly this, and we mirror pi's own binary entry (`pi-coding-agent` `dist/bun/cli.js`):
      **`registerBunOAuthFlows()`** (`@earendil-works/pi-ai/bun-oauth`) + **`setBedrockProviderModule(
      bedrockProviderModule)`** (`…/compat` + `…/bedrock-provider`). Both load via **dynamic literal
      imports inside the seam** — literal specifiers are statically bundled by both `bun build --compile`
      and the desktop server-runtime build, while dev (which never calls the seam) never loads the flow
      modules or the AWS SDK. Registration
      lands in the same `pi-ai` instance pi consults at login time because the catalog pins one exact
      `pi-ai` version repo-wide (one store entry → one bundled module instance). Chat trash has two
      artifact seams behind the same registration, both owned by the `trash` module: the procfs parser it
      statically installs, and the `trashHelpers` the launcher stages and `registerBundledRuntime` injects
      through `setBundledTrashHelpers` (rationale: [[submodule-server-trash]]). No platform degrades to
      permanent unlink.
    The desktop server/factory bundle is built with pi's `PI_BUNDLED_NODE=true` compile-time define. That
    is pi's own switch for bundled-but-not-compiled distributions: it selects the embedded-modules extension
    loader (jiti's static entry with Babel bundled in, plus pi's virtual modules). Without it pi treats the
    bundle as a plain Node runtime and reaches for jiti's lazy `../dist/babel.cjs` relative to a file that
    does not exist inside a single-file bundle, so the Central candidate fails to load (pi 0.86.0 made the
    loader choice runtime-dependent; 0.84.x always used the static entry). The candidate loader also forces
    jiti's transform (`JITI_TRY_NATIVE=false`, plus `JITI_REBUILD_FS_CACHE=1` so a stale transform cache
    never survives a pi bump): with native import allowed, Bun would resolve an external extension's bare
    `@earendil-works/pi-coding-agent` import itself — auto-installing a second pi copy, since nothing under
    `~/.pi/agent/extensions` has `node_modules` — instead of pi's virtual-module mapping onto the bundled
    instance. Together the define and the forced transform are the tested artifact seam (the shared artifact
    probe's synthetic extension value-imports pi and fails closed without them); the `server-runtime.ts`
    filename is only a name.
    In every mode, the optional Central artifact remains an external filesystem path loaded by PI's public
    Jiti seam; it is never bundled, staged, or copied into ThinkRail. Both modes append
    `extensionFactories`: a **headless-search policy** (a `tool_call` hook defaulting
    `web_search`'s `workflow` to `"none"`, since pi-web-access would otherwise open a browser curator our
    `rpc` host can't render), `askUserQuestionExtension` (normalizes ask-only assistant batches),
    `oversizedImageGuard` (the context-level image-size guard, see the `imageGuard` bullet), **and the
    caller's `extraFactories`** — per-session host bindings (the workspace-bound subagents extension),
    value-imported so dev and the compiled binary take the same path. pi's own built-in extensions
    (`llama.cpp`, `codemode`, `tool-search`, `mcp`) are loaded only by pi's CLI; an SDK host opts in per
    factory. ThinkRail opts into **`mcp` and `tool-search`** with pi's own descriptors
    (`{ name, factory, replaceable: true, builtin: true }`, so a user-installed `/mcp` extension replaces
    them and `-builtin:mcp` in pi settings disables them) — registered only once the protections in the MCP
    section below had landed, so no build ever started servers without them; there is no runtime flag
    beyond pi's own `-builtin:mcp`. `codemode` and `llama.cpp` are not loaded (codemode needs a
    QuickJS worker + wasm seam the compiled binary and desktop bundle do not have). See
    [MCP servers](#mcp-servers).
    Both session paths pass it as `resourceLoader`. `buildResourceLoader` stays internal; the seam +
    its types are on the barrel.
- **Public surface (barrel):** the manager operations (incl. `answerQuestion` +
  `settleSessionsForShutdown`) + `CreateSessionInput`/`CreateSessionResult` + `SessionEventPayload`;
  the runtime-generation facade (`usePiRuntime`, candidate prepare/activate, current generation id, and the
  closed `load-failed` outcome—no manager internals) plus `configurePiRuntime`/factory test seams and the
  pre-bootstrap `configurePiRuntimeGenerationInitializer` composition seam; `listModelContextSettings` /
  `setModelContextWindow` / `setModelContextPublisher` (the `modelContext` adapter and its
  `provider.changed` seam); `piLoginOptions` (pi login options
  carrying the lazily created installation device id, for `auth`);
  `completeOnce`/`pickModel` +
  `OneShotRequest`/`OneShotResult`/`ModelTier`; the `webUiContext` seams; the `askUserQuestion` pure
  helpers (`validateQuestionnaire`/`buildQuestionnaireResponse`/`assessAnswerability`/
  `buildAnswersMessage`/`awaitingQuestionToolCallId`); normalized-state operations
  (`listSessionStates`/`acknowledgeCompletion`/`markWorkspaceUnread`/`markWorkspaceRead`/`nudgeSession` +
  publisher/project seams);
  `repairDanglingToolCalls`; `liveParentContext` + `readChildTranscript`
  (the delegation embedding); the skill catalog helpers
  `listSkillCommands(cwd, admission)` (filtered, pre-session autocomplete) / `listSkillCatalog(cwd, admission)`
  (unfiltered, the manager's `skills.state`) / `listProjectAliasSkillNames(cwd)` (present-alias count) /
  `isProjectSkillPath(relativePath)` (watch-classification predicate);
  `reloadSessionResources(sessionId)` (active-chat reload; throws while the reload gate is blocked) +
  `requestSessionReload(sessionId)` (the deferring variant: `"reloaded"` now or `"deferred"` until the gate
  opens — settlement, the release of an admitted prompt, or a compaction's end; requests coalesce); the **`setSkillAdmissionResolver`** seam (host
  wires `workspaceId` → the admission context, derived once by `admissionContextFor(project, overrides)`);
  the **`setMcpPolicyResolver`** seam (host wires `workspaceId` → the project's MCP approvals, overrides
  and tool grants, derived by `mcpPolicyOf(project)`) and its writer twin **`setMcpToolGrantWriter`**; the MCP management surface — `listMcpServers`,
  `mcpOwnershipGuard` (resolves pi settings, then answers synchronously who manages MCP instead of
  ThinkRail — what `listMcpServers` reports as `handledElsewhere` — so the host checks it in the same call
  stack as every management mutation), `refreshMcpStatus`,
  `setMcpStatusPublisher`, `mcpSessionView` / `liveSessionIdsOf`, `dispatchSessionMcpCommand` (with an
  optional `notify` that takes the dispatch's notifications instead of the chat), `reconnectMcpServer`,
  `readMcpServerLog` (one server's masked lines from pi's shared `mcp.log`),
  `setSessionMcpServerEnabled` (the chat-local disable, applied through the reload gate), the config
  effective-config read `effectiveMcpServerConfig` and the config
  writers `writeMcpServerEntry` / `removeMcpServerEntry` / `mcpEntryFingerprint` /
  `shareMcpOverrideWithRepo` (pi-rule validation, `MCP_CONFIG_INVALID` / `MCP_PATH_UNSAFE`) and the
  sign-in probe (`startMcpProbe`, `replyMcpProbe`, `cancelMcpProbe`, `cancelMcpProbesOwnedBy`,
  `cancelAllMcpProbes`, `setMcpLoginPublisher`, `isMcpLoginId`);
  the pi-level trust surface — `applyPiResourceTrust(workspaceIds)`
  (gated reload of every live session whose trust is stale), `piTrustsProjectPath(path)` (whether pi already
  trusts a path: its `trust.json` decision by nearest ancestor, else its global `defaultProjectTrust` is
  `always`; an unreadable store answers `false` — the host's seed for a newly added project) and
  `projectTrustSummary(cwd)` (the trust notice's facts: alias names and the `ProjectResourceKind`s present —
  the `.pi/` entries pi's `hasTrustRequiringProjectResources` gates, ancestor `.agents/skills`, and project
  definitions from `pi-subagents`' `discoverAgentDefinitions`; the entry list mirrors pi's private one, minus
  `mcp.json`, whose entries are counted separately as `mcpServers` because each also needs its own approval,
  so a pi upgrade that gates a new entry must extend it);
  the subagent-policy seams
  **`setSubagentsEnabledResolver`** + **`refreshSubagentTools`** (host resolves the effective global default
  plus workspace override; manager owns live-session activation timing) and the concurrency seams
  **`setSubagentConcurrencyResolver`** + **`refreshSubagentConcurrency`** (same split; `delegation` owns
  applying the limit to its cached services);
  the extension on/off seams **`setDisabledExtensionsResolver`** + **`refreshExtensionTools`** (host owns the
  set; this module owns compose-time filtering and live activation timing);
  the `set_title` seam (`setTitleToolHost` + `TitleToolHost`/`SET_TITLE_TOOL_NAME`/`SetTitleParams`);
  the bundled-artifact seam (`registerBundledRuntime` +
  `BundledExtensions`/`BundledExtensionFactory`).
- **Allowed deps:** `@earendil-works/pi-coding-agent` (runtime); `@earendil-works/pi-ai` (types + test
  fixtures + **pure catalog helpers value-imported from the package root** — today exactly
  `getSupportedThinkingLevels` + `clampThinkingLevel`, data-only projections over `Model`; *dispatch*
  still goes through the shared `ModelRuntime`, never pi-ai's stream/complete — plus the `/bun-oauth` + `/bedrock-provider`
  + `/compat` subpaths, value-imported **only** inside `registerBundledRuntime`'s dynamic imports);
  `pi-delegation` + `pi-subagents` (the portable delegation runtime and Agent-tool composition,
  value-imported by the host embedding); `pi-background-commands` (the session-bound command
  capability, likewise value-imported by its host embedding); `pi-web-access` + `pi-spec-graph` +
  `pi-thinkrail-workflow` + `pi-todos` (the bundled pi packages — parent sessions load the set through
  resource-loader paths or launcher factories; delegated children value-import `pi-spec-graph` and receive
  the named `pi-web-access` factory through the bundled runtime seam; the source-mode equivalent loads it
  lazily through `jiti` — the loader pi uses for extension paths — so a parent never pays for it and the
  barrel stays Node-loadable for the workflow harness ([[module-workflow-tests]])); the sibling `extensions` registry module (the ThinkRail extensions' inline factories and
  skill roots — `agent` never imports an `@thinkrail/ext-*` package or its pi package directly); `jiti` (the source-mode child `pi-web-access` load above); `typebox` (the `ask_user_question` parameter schema); `jsonc-parser` (targeted
  `models.json` edits in `modelContext`); `trash` (reached only through the
  sibling **`trash` module** — see [[submodule-server-trash]]: one path, globbing disabled, allowed to
  throw, never degraded to `unlink`; the launcher's staged-helper and procfs-parser seams live there too,
  because `changes`' whole-file revert needs the same primitive);
  `contracts` (`PiEvent`/`Model`/`ThinkingLevel`/`ImageContent`/`SessionStats`/`SessionSummary`/
  `Session*Payload`/`SlashCommandInfo`/`ExtUi*`/`AskUserQuestion*`/`ProviderStatus*`); `log` (diagnostics +
  session-lifecycle debug traces); `persistence` (`dataDir` for delegation plus the narrow session
  receipt stores); `trash` (the recoverable-delete primitive); Node.
- **Forbidden:** `host`; sibling features other than `log`, `trash` and those narrow persistence surfaces (session
  worktree `cwd` remains an input, never a workspace-registry lookup); Central process/filesystem knowledge—the
  caller supplies only the desired opaque extension paths for a candidate.

## Continue in workspace

`continueTool.ts` registers `continue_in_workspace({ summary })` the way `titleTool.ts` registers
`set_title`: a global inline extension whose behaviour is a host-injected `ContinueToolHost`
(`setContinueToolHost`), so `agent` never imports `host`. The tool's description tells the agent it only
works after ThinkRail asked (the request card); the host side refuses every call without a pending
binding, which also keeps delegation children out. `clampHandoffSummary` bounds the summary to
`CHAT_HANDOFF_SUMMARY_MAX_LENGTH`. `sendHostMessageToSession(sessionId, customType, content, details)` is
the one way the host authors a message the agent answers: a `display: true` custom message delivered as a
follow-up with `triggerTurn`, queued behind a running turn and never a steer — the review-fix request
rides it too.

## Session titles

`agentSessionManager` is the only durable chat-title writer. Its `renameSession(sessionId,
workspaceId, cwd, title, { onlyIfUnnamed? })` validates one non-blank, single-line title within contracts'
length limit, resolves the session strictly inside the supplied workspace/cwd, and avoids an append when the
normalized title is already current. A live session writes through `AgentSession.setSessionName`; a disk-only
session opens its exact transcript with `SessionManager.open(...).appendSessionInfo(...)` without attaching an
agent or resolving a model. Both paths publish the same `session_info_changed` Pi event, while
`SessionSummary.title` remains the hydration projection. The title is also **exposed, not copied, on the
state record**: `SessionStateRecord.title` carries pi's current session name (live entries from
`sessionName`, disk records from the transcript header), the publication fingerprint includes it so a
title-only change republishes `session.state`, and the disk-only rename path publishes a fresh record
itself — the Chats rows, the topbar and the palette read titles from there, with no per-workspace
`session.list` backfill needed for a host of this protocol.

The guarded write remains authoritative across the async race. `onlyIfUnnamed` performs the check immediately
beside the append and is the compare-and-set the `set_title` handler uses (its `false` return is how the
handler learns the chat was already named); the manual wire mutation is unconditional. So an agent title can
never overwrite a durable name, and the first name is final. No generated/manual provenance or title sidecar
belongs here: the absent-vs-present pi name is sufficient. The architecture's accepted no-cross-process
coordination rule still applies.

**First prompt beside the title.** Every `SessionSummary` and `SessionStateRecord` the manager projects
(`summaryOf`, the disk rows of `listSessions`, the state publishes and `listSessionStates` sources) also
carries `firstPrompt` — contracts' `firstPromptHead` of the transcript's first user message that has text
and is not a control message — so clients can label a chat the agent has not named. One derivation,
`firstPromptOf(entries)`, reads the **full** `SessionManager.getEntries()` for live and disk sessions alike:
`AgentSession.messages` is the compaction-aware projection, whose first user message after a compaction
is no longer the chat's first prompt, and pi's `SessionInfo.firstMessage` substitutes a placeholder string
when no text exists. A live entry caches the answer either way — found or absent — and re-reads only the
entries appended since its last scan, and only when `getEntryCount()` grew, so the per-event state publish
never rescans a transcript whose user turns are all packages or images. The value is
read-only: no write path accepts it, `renameSession` and `onlyIfUnnamed` are untouched, and a named chat
still carries it so a client can show the title and keep the prompt as a tooltip.

## Chat Resources integration

The manager retains one [[module-pi-background-commands]] service per parent chat alongside its Pi
session and injects its extension through the normal resource-loader path. The same binding supplies
live session context, effective shell settings and lifecycle in source and packaged hosts. The
first version loads this capability into parent chats only, not the curated hidden-child extension
set; ordinary child Bash remains visible in its transcript.

A small agent-barrel facade serves the resource snapshot, command output/stop and subagent
stop/stop-all operations defined in [[module-contracts]]. It projects command services plus
`DelegationService.childrenOf(parent)`; no aggregate registry owns copies of their lifecycles.
Subagent summaries include direct foreground and background children and omit handles with no run
snapshot yet. Keep all active children and the latest twenty terminal children by record creation order,
without disposing older handles or transcripts. Task and role summaries are capped at 2,000 and 200
characters. One lifecycle subscription per workspace service and each command service's change subscription
publish scoped invalidations through a host-injected publisher; no per-token/output broadcast is added.

Each operation validates actual workspace/session membership, child lineage and the manager's deletion
gate before touching a handle. Persisted parents use the existing single-flighted attachment path;
unknown parents never masquerade as empty catalogs. Missing/foreign/evicted resources share the
`RESOURCE_UNAVAILABLE` path (command output alone returns `available:false` after parent validation).
Resource control never depends on the UI having seen a tool event or on starting/restarting a provider turn. Natural completion and requested cancellation remain source
outcomes; stopped state is not synthesized from an acknowledged RPC.

User subagent controls supply the `"user"` cancellation reason defined by [[module-pi-delegation]];
completion delivery belongs to [[module-pi-subagents]], not a host suppression set. Stop-all signals
all captured active children before returning its target count; individual and bulk controls acknowledge
intent without awaiting provider/tool settlement. Their detached abort promises always carry rejection
handlers, lifecycle invalidations remain terminal authority, and neither control uses `disposeChildrenOf`
as a substitute.

Command services outlive view placement and parent-turn cancellation. Actual session disposal and
workspace archive close command admission and signal command/child work before awaiting teardown
under the existing host shutdown budget. A per-session teardown tombstone prevents a persisted parent
from reattaching until its previous resource cascade settles. Workspace archive closes a generation and
awaits in-flight parent preparation before removing delegation/transcript storage, so stale preparation
cannot register after teardown. Resource closure runs for every captured workspace parent before
any parent abort is awaited; individual removal likewise signals resources before waiting for the main turn.
Streaming destructive removal reuses the manager's queue-draining Stop path, discarding the drained
input while retaining the same bounded accepted-answer persistence grace before the parent is disposed.
Main-turn Stop alone never closes Resource owners.
Command and detached-subagent completion delivery respect pending session deletion and its rollback;
no notice may append or wake the parent behind a transcript being moved to trash. The tombstone is
temporary and does not dispose either owner. Resource reload retains the command service and portable
`Subagents` owner and rebinds their completion senders. The manager stores no completion queue. The
SessionManager exists before SDK session creation, giving the service its immutable identity. Its
context reads the current session's
cwd/model/thinking/session file and effective SettingsManager shell path/prefix at launch. Completion
requires that exact registered owner, no deletion tombstone, no resource closure and no recoverable
live question. A non-waking user-stop notice must not append behind an unanswered tool call and break
tail-only restart repair. Resource inspection and cancellation remain available while delivery waits
in the existing portable owners. The native `turn_end` result boundary clears the question phase and
flushes both owners, as do registration, resource reload and deletion rollback. `closeSessionResources` synchronously disposes
the subagent owner before child cancellation or any await, including preparation failures. Permanent
closure survives shutdown-budget expiry and suppresses late outcomes; Pi disposal does not emit extension
shutdown, so the cascade emits `session_shutdown` itself after the synchronous owner disposal (see
[MCP servers](#mcp-servers)). The existing cached resource cascade remains the sole teardown owner. Both
SDK creation and entry preparation failures close the owners. A failure after registration also
removes that exact entry through the normal teardown path, rather than leaving a disposed session
advertised as live.
A restarted host has no control handles or retained command output to reconstruct from history.

`getSessionResources`, `readBackgroundCommandOutput`, `stopBackgroundCommand`, `stopSubagent`,
`stopAllSubagents` and `setSessionResourcesPublisher` are public only through this module's barrel.
`stopBackgroundCommand` acknowledges before settlement, so a test that stops a command waits for `stopped`
before it ends, and a test publisher (process-global) ignores other chats' notices and keeps any read it
starts handled: a late `stopped` notice once reached the next test's publisher, whose rejected read became
an unhandled rejection that bun charged to every following test while that publisher stayed installed.
Its only new external dependency is `pi-background-commands`; there is no `agent` → `terminal`, `subprocess`,
settings or workspaces edge. The owning parent graph records this package dependency.

## MCP servers

pi's built-in MCP is the only MCP engine: connections, OAuth, exposure, resources, result truncation and
the `/mcp` command stay pi's; ThinkRail owns what a multi-session GUI host owes around it.

- **Registration.** The two built-in descriptors above, per parent session only, built by the session's
  `createMcpSessionHost` together with the call guard and a status invalidation callback. The manager
  injects the guard's two ports — `askForToolCall` (→ `selectForToolCall(sessionId, { toolCallId, toolInput }, …)`,
  so the approval is anchored to its call even among parallel calls and lists the call's input) and `grantTool` (→ the grant-writer
  seam) — and the host injects the workspace's project policy (`setMcpPolicyResolver` → `Project.mcpApprovals` / `mcpOverrides` /
  `mcpToolGrants`, fail-closed to none). Child (subagent) sessions load neither — the curated child set carries no engine —
  and the `Agent` tool's description says subagents cannot call MCP tools.
  Parent chats make pi's `openUrl` a no-op (a remote client must never get a browser opened on the host
  machine); pi's rpc-mode `/mcp login` still shows the URL and the paste-back dialog. In the
  Central-exclusion loader mode both built-ins go through the per-reload path re-resolution described
  under `extensions`, so `-builtin:*` applies there too.
- **Configuration** ([[submodule-server-agent-mcp]]). pi's `mcp.json` files are the source of truth
  (`~/.pi/agent/mcp.json`, trusted `.pi/mcp.json`). The loader ThinkRail supplies is a port of pi's
  `loadMcpConfig` + validation (parity tests run the same fixtures through pi's installed loader, re-checked
  on every pi bump) because pi does not export them; it also applies
  the project record's enablement/exposure overrides, drops repo-defined entries the user has not approved,
  and normalizes `codemode` exposure to `deferred` in memory while codemode is absent. Config writers are
  ThinkRail's (synchronous temp-file rename, unknown keys kept, only the defining file touched, no symlinked
  `.pi/` paths, secret literals masked in every UI). Servers registered by third-party extensions bypass
  the loader; the `mcp` descriptor's factory registers its own `session_start` / `mcp_servers_change`
  handlers ahead of pi's so `tool_search` is active before pi checks reachability whenever
  `pi.getMcpServers()` is non-empty (no "neither is active" warning, and nothing to do when another
  extension replaced the built-in).
- **Trust.** Every `SettingsManager` the host builds for a project passes its real pi-level trust
  (`Project.piResourceTrust`, [[submodule-server-projects]]) instead of a forced `true`.
  - **Sites.** Sessions (`buildSessionSettings`), pre-session loaders and child sessions. The alias-name
    listing alone passes `false`: alias roots are explicit paths, so it never needs project settings.
  - **Every load.** The session loader's `reload()` applies the admission context's current trust
    (`setProjectTrusted`) before every load, so any reload — a grant, a config change or a manual reload — loads exactly
    what the record allows. A grant or revoke therefore only asks the gate to reload the sessions whose
    trust is stale (`applyPiResourceTrust`: idle now, busy at settlement). A session still opening when
    trust changes is not in that scan, so registration re-checks its loaded trust against the record and
    reloads it before `createSession` returns.
  - **Children.** A child's trust comes from its parent context: `liveParentContext.isProjectTrusted`
    answers the parent's *loaded* trust AND the current record. A child therefore never holds more than
    its parent (a grant deferred on a busy parent does not reach its new children before the parent
    reloads) nor more than the record (a revoke reaches new children at once).
  - **Revoke.** A child captures its trust at creation and `pi-subagents` retains children across a
    parent reload, so a revoke also stops every live child of a stale parent (`stopSessionChildren`,
    reason `"user"`: the revoke is the user's own action, and the parent is told without being woken). It
    waits until those runs have actually ended — a child whose abort fails is disposed — before the
    parent's reload is requested. A **busy** parent is not interrupted: its current turn finishes with the
    resources it already loaded and it reloads at settlement (`"deferred"`), which the Stop-trusting
    confirmation discloses ("open chats reload when idle"). So when `project.setTrust` returns, no child
    and no idle chat runs under the revoked trust, and a busy chat stops at the end of its turn.
  - **Failures.** A reload that fails is reported as `"failed"` in the returned dispositions, and
    `project.setTrust` then fails after persisting and publishing the record, naming the chats still on
    the previous trust. A deferred reload that fails later reaches the user as an `error` notify on that
    chat asking to close or reload it. A grant leaves running children alone, since they merely lack the
    project's resources.
  - **Consent.** The pi-level grant is its own consent, separate from alias trust: only
    `project.setTrust` with `resources: true`, sent by a surface that names what it loads, grants it
    ([[submodule-server-projects]]). Repo-defined MCP entries additionally need a per-entry approval
    keyed to a fingerprint of the whole original entry object (approval state in the project record).
    The trust notice is shown for alias skills, pi's own trust-requiring resources, project subagent
    definitions and project MCP entries alike.
- **Lifecycle.** `AgentSession.dispose()` never emits `session_shutdown`, so the resource cascade
  (`closeSessionResources`) runs it itself — synchronously, after the synchronous owner disposal, so handlers
  have started before the synchronous teardown path disposes the pi session. pi's runner awaits handlers one
  after another in load order, and file extensions load before `builtin:mcp`, so one that never settles would
  keep pi's MCP shutdown from ever starting (pi's process-exit hook only sends SIGTERM). The cascade therefore
  first runs the `mcp` factory's own `session_shutdown` handler directly (`McpSessionHost.shutdownEngine`,
  with the event and the runner's `createContext()` pi would pass), then
  `session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" })` for every extension. The
  captured and runner-emitted MCP shutdown share one per-load cleanup promise, so clearing pi's server
  list early cannot make a second dispatch lose the first dispatch's completion ([[submodule-server-agent-mcp]]).
  Gated reloads await that actual MCP cleanup with reason `reload` before calling pi's `session.reload()`;
  they never use the bounded quit wait to admit a replacement while old resources still live. A hanging
  unrelated shutdown handler may delay the reload, but cannot keep MCP processes alive through a trust
  or resource change. Closure checks before reload, in the public `beforeSessionStart` hook, and after
  dispatch reject when the entry is disposed or its resources are closing. The hook alone is insufficient:
  an earlier async `session_start` handler can pause the dispatch through closure, so the engine guards
  its actual startup/change callbacks with the load's synchronously closed flag. Closure does not await
  an unbounded resource loader or startup dispatch. If pi later builds a replacement
  runner, the reload owner gives that runner its own bounded shutdown and disposes it. Shutdown is
  single-flight per runner, including when emergency disposal follows graceful closure mid-reload;
  each disposal continuation may dispose only the runner whose shutdown it awaited. Closed reloads never
  flush completions, restart MCP status, or schedule another reload.
  Every teardown path goes through this cascade: delete/remove, workspace archive/removal, quit
  (`settleSessionsForShutdown` + `disposeAllSessions`) and a preparation that fails after binding —
  including one whose registration is refused because the workspace closed or the host began quitting
  meanwhile. Every one of them defers `session.dispose()` (`disposePiSessionAfterShutdown`) until both
  settle or the budget (`SESSION_SHUTDOWN_BUDGET_MS`, 3 s — pi escalates stdin-close → SIGTERM → SIGKILL
  over 2.5 s) elapses, because `dispose()` invalidates the extension context the handlers are still
  using; the host shutdown settle budget is that same 3 s. Retained sessions keep their servers
  (no eviction); they appear as the third list of `SessionResources` (`mcpServers`: name, state, tool
  count, transport from the session's latest status snapshot, `registered: true` with the registration's
  transport for a server an extension registered; a change publishes `session.resourcesChanged`) with
  per-chat "Disable in this chat" applied at the next idle reload (a deferred one shows the server
  `pending-reload` at once). The overlay reaches `mcp.json` servers only, so `setSessionMcpServerEnabled`
  refuses (`MCP_CONFIG_INVALID`) to disable a server the chat did not load from its files — for a
  registered one the message says it is registered by an extension and can't be disabled per chat — and
  refuses with `MCP_HANDLED_ELSEWHERE` where `builtin:mcp` does not own `/mcp`. Ownership and file
  provenance are validated before both enable and disable, even for no-op requests; a disabled entry
  retained across a reload that replaces `/mcp` cannot be re-enabled through the host. A failed reload
  never rolls back the chat-local disable intent; repeating the same value retries while its MCP reload
  failure remains, rather than returning unchanged. If that failure cleared the loaded snapshot, a retry
  validates file provenance against the currently admitted configuration; unknown or extension-only names
  remain refused and a replacement command owner still makes the control read-only.
  Config or trust changes reload only the affected sessions: the session's `loadConfig` records the
  per-server effective config pi received at its last start (`McpSessionHost.loaded()`, cleared at the start
  of every load), and `reconcileMcpSessions` compares it with what the loader would produce now
  (`pendingMcpReload`) — an unapproved repo entry, for example, changes nothing and reloads nothing. A
  session whose `/mcp` another extension owns, or none does, has nothing to compare (the built-in's loader
  never runs there) and is not reconciled unless an earlier failed MCP reload remains retryable.
  Reconciliation runs after every
  host mutation, when the user file changes (`watchUserMcpConfig`: one directory watcher on pi's agent dir,
  300 ms debounce; a missing agent dir is created first — pi creates it on first use anyway — so a file the
  user adds later is still seen; a rename or watcher error retires the old watch and rearms it with
  capped retry backoff, including after the agent directory is recreated; stopping cancels retries), when a workspace change nudge touches `.pi`, and at each session's
  `agent_settled` (so an edit the agent made itself applies once the run ends); a deferred reload shows the
  changed servers as `pending-reload` until it runs. Every MCP-affecting gated reload (immediate,
  deferred, manual, trust/settings, or chat-local override) shares one failure recorder in `mcpSessions`:
  the existing tracked status object retains the retry marker even if the failed load already replaced
  or cleared its config snapshot. The gate captures whether the built-in engine was loaded before
  replacement; that provenance, a newly loaded engine, or an existing failure makes the reload
  MCP-affecting. Hosts where MCP was never managed acquire no MCP failure marker. Each failed attempt
  logs and notifies once with redacted details; deferred and reconciliation callers do not report it again.
  Failure does not restart authoritative status or immediately drain another pending reload; a later
  reconciliation or explicit retry can recover without any config delta. Only a successful reload clears
  the marker and restarts status. Closing or disposed entries neither report failures nor restart.
  Reloads go through `session.reload()` behind a per-session reload gate: while a reload runs, every
  admission seam (`promptSession`, `steerSession`, `followUpSession`, `nudgeSession`, queue requeues,
  `answerQuestion`, `sendReviewFixToSession`, `compactSession`) refuses with "reloading", and completion
  delivery waits in its owners through `canDeliverCompletion` and flushes afterwards; the gate opens only
  when pi is `isIdle`, no admitted prompt is still in preflight (the host reserves the window from
  admission to `agent_start` — pi ≤ 1.1 reported idle throughout it and pi 1.2 still does until
  `before_agent_start`, through `input` handlers and expansion; a prompt handled as a slash command never
  starts a run), no queued-message removal is putting the kept messages back (`removeQueuedSession` holds a
  reservation `agent_start` does not release from its drain to its last requeue, so a run that settles
  meanwhile cannot start a reload that would refuse — and lose — the rest), and no manual or automatic
  compaction is in flight; a pending reload is reconsidered at `agent_settled`, on every reservation release
  and on compaction end / `compactSession`'s `finally`.
- **Status** (`mcpSessions.ts`). Exposed, not recomputed: connection truth is pi's headless `/mcp` text,
  obtained by dispatching the session's own command (`dispatchSessionMcpCommand` →
  `extensionRunner.getCommand("mcp").handler`). The capture goes by provenance, never by format: that
  dispatch gets `createCommandContext()` with its `ui` getter redefined (`Object.defineProperty`, so pi's
  other lazy getters stay untouched) to a forwarding proxy of pi's UI whose `notify` alone reports to the
  capture. It therefore takes exactly its own dispatch's notices, nothing it prints ever reaches the chat,
  and a user's own `/mcp` (pi's prompt path, pi's context) always prints there, even mid-capture. The
  reconnects (`reconnectMcpServer`: `mcp.reconnect` and the post-sign-in ones) dispatch the same way:
  success is silent, pi's error notice becomes the call's rejection (through `redactMcpText`), and a chat
  where `builtin:mcp` does not own `/mcp` is refused with `MCP_HANDLED_ELSEWHERE`. pi's startup "MCP
  servers need attention" notice is unsolicited, so it alone is recognised by its fixed prefix through
  `interceptExtUiNotify` ([`webUiContext`]), installed before `bindExtensions`: it becomes a partial status
  update plus a full refresh instead of a toast — except for clients below `MCP_PROTOCOL_VERSION`, which
  are not subscribed to `mcp.status` and still receive the notice as a toast (`notifyExtUi` with an
  `ExtUiAudience`, delivered per socket and redacted before delivery), since the web client and host ship independently. pi's `/mcp` awaits every startup connection before it
  answers, so registration and every successful gated reload first seed the snapshot from what pi was given
  (`McpSessionHost.loaded()` plus the servers extensions registered): each enabled one reads `starting`, a
  disabled one its disabled state through the same derivation, and the previous load's report never
  survives a reload. Then a capture starts; one begun before that (re)start is dropped (a per-session load
  epoch), so a stale report never replaces the seed. Refreshes also run at `agent_settled` and after a
  chat's own MCP login/logout/reconnect settles, including failures; status reads never invalidate
  themselves. The capture continues after a read caller's wait budget and publishes its eventual answer.
  At most one
  capture per session is in flight and a caller waits a bounded time. Each snapshot merges pi's report with
  configuration (`deriveMcpServerStatuses`: disabled by this chat / the project, pending approval, invalid
  config; the last report stands when pi did not answer), carries a per-session monotonic generation, and
  is published to the `mcp.status` channel. pi does not redact its status text (connection errors, HTTP
  error bodies, a stdio server's stderr tail), so every `detail` and `configError` passes the host's
  `redactMcpText` ([[submodule-server-agent-mcp]]) before it leaves the host. Configuration problems are
  reported, never dropped: every named entry keeps its summary (one that is not an object reads
  `server "<name>" must be an object`), and `listMcpServers` adds the two files' file-level problems
  (unparsable JSON, `mcpServers` not an object, a mistyped key; `summarizeMcpConfigErrors`, masked) as
  `configErrors` — pi's own report of them is the startup notice the host intercepts. Only a session whose
  `/mcp` belongs to `builtin:mcp` is queried; another owner makes `listMcpServers` report
  `handledElsewhere` (`by` = that extension's path, or `pi settings` for a live chat without `/mcp`), and
  the refresh after the reload that handed `/mcp` over retires that session's statuses and resource rows
  once (an empty `mcp.status` snapshot, one `session.resourcesChanged`). pi settings that turn the built-in
  off are known with no chat open: `listMcpServers` resolves them the way the exclusion loader does
  (`DefaultPackageManager` with the built-in's name, its `builtin:mcp` resource's `enabled`; missing
  packages are skipped, never installed) and reports `by: "pi settings (-builtin:mcp)"`. Whether an
  enabled non-built-in extension registers `/mcp` is not knowable without loading it, so a replacement is
  only seen through a live chat's owner.
- **Calls.** The per-session host extension ([[submodule-server-agent-mcp]]) asks on the call's card
  before any `mcp__*` call without `readOnlyHint` (Deny · Allow once · Allow in this chat · Always allow;
  anything but an affirmative answer blocks, and a user message answers it like any dialog). "Allow in
  this chat" is session memory; "Always allow" is a project grant written through the
  **`setMcpToolGrantWriter`** seam (host → `grantProjectMcpTool`; a failed write is logged and the call
  still runs) and read back through the policy resolver on every call. Its `tool_result` handler
  adds the bounded, base64-free `McpResultSummary` under `details.thinkrail` (`summarizeMcpResult`), and
  `readMcpToolOutput` serves a result's recorded full output (`mcp.readOutput`) from exactly its
  `fullOutputPath` (pi's owner-only temp file; at most 1 MiB, `truncated` beyond) — `unavailable` for a
  result that recorded none, `expired` once the file is gone. Settings' *Show log* reads `readMcpServerLog`
  ([[submodule-server-agent-mcp]]): pi appends what servers log (`notifications/message`) to one `mcp.log`
  per agent directory for every session, so a server's lines are picked by their entry head and masked.
- **Sign-in** (`mcpSignIn.ts`; pi ≥ 1.1.0 for cancellable sign-in, #10565). `startMcpProbe({ action:
  login | test | logout })` opens a short-lived, unregistered, in-memory pi session whose loader carries only
  `builtin:mcp` with the one server (forced enabled) and whose UI context is the probe's own, dispatches
  pi's `/mcp login|logout <name>` or headless `/mcp`, then emits `session_shutdown` (which also aborts a
  running sign-in) and disposes it. Frames ride the `provider.login` family with `target: { kind: "mcp" }`
  and `loginId` `mcplogin_*`, to the owning connection only (`setMcpLoginPublisher(push, ownerClientKey)`);
  replies and cancels from any other connection fail with `LOGIN_NOT_OWNER`. Pi's public `openUrl`
  callback supplies the `authUrl` frame directly, only for `https:` or loopback `http:` addresses; its redirect
  prompt becomes the paste-back `prompt` frame, and the outcome is derived from pi's captured
  notifications (signed in / failure text / cancelled), never from the command promise alone. pi's wait for
  the browser or the paste-back has no overall timeout, so every probe has a deadline (`PROBE_DEADLINE_MS`,
  10 minutes; `startMcpProbe`'s optional `deadlineMs` is the test seam, which the host never passes) after
  which it ends exactly like a cancel — `error` frame "Sign-in timed out.",
  `session_shutdown` (which closes pi's loopback listener), lock released once the session is closed — and
  the host cancels the probes a client owned when it reaps that client (`cancelMcpProbesOwnedBy`), so a
  reloaded page or a discarded tab never holds a server until restart. After a successful sign-in, the
  workspace's live chats that report the server as *needs sign-in* get `/mcp reconnect <name>` instead of
  waiting for their next turn. Test connection is HTTP-only (a stdio server is verified when a chat starts
  it) and reports *connected · N tools* or the reason; every `error` frame's message (pi's reason or
  notice) is redacted like a status detail. A live chat's own `/mcp login` keeps pi's rpc path:
  the sign-in address arrives as a transcript notice (never auto-opened; `openUrl` is a no-op on the host)
  next to pi's paste dialog. The probe's loader forces `builtin:mcp`, so the host starts no probe where
  `listMcpServers` reports `handledElsewhere` (`MCP_HANDLED_ELSEWHERE`, [[submodule-server-host]]).
- **One sign-in per server, whoever runs it.** pi keeps one client registration and pending PKCE state per
  server in the shared `mcp-auth.json`, so two concurrent flows for a server break each other. A probe
  holds the server's lock (`acquireMcpSignInLock`, [[submodule-server-agent-mcp]]) from its start until its
  session is closed and refuses with "already running" ("… in a chat" when a chat holds it); a live chat's
  `/mcp login|logout <name>` holds the same lock for the command's duration (the engine's wrapped `/mcp`)
  and, while anything else holds it, says so in the chat instead of starting pi's flow. A bare
  `/mcp login` / `/mcp logout` is not locked — the accepted gap: pi picks the server inside its handler
  (the only OAuth server, the only one needing sign-in, or the answer to its own picker), so there is no
  name to lock before its flow writes state; pi's status text and hint always name the server
  (`run /mcp login <name>`).

## Get right

- `prompt()` throws while a session is streaming → `promptSession` falls back to `steer()`.
- Errors arrive via the event stream + thrown methods, not a crash signal — wrap + forward.
- **A re-opened disk session is repaired before it is seeded** (`repairDanglingToolCalls` between
  `SessionManager.open` and `createAgentSession`) — never append to a session file behind a live
  `AgentSession`, its in-memory context would desync.
- **A live ask blocks only in its session-bound phase registry; restart state stays transcript-derived.**
  The registry is forgotten on disposal and never restored. Only a tool-executable dangling ask is repaired
  to ack before attach; `length`/`error`/`aborted` attempts are terminal. `assessAnswerability` remains the
  one reply-validity authority; rejections fail the WS request loud.
- Share one **current** `ModelRuntime` for pre-session reads and new sessions. Every session receives and
  retains its generation as `createAgentSession`'s `modelRuntime`; give each its own `SessionManager` and
  `dispose()` it on removal. Old runtimes remain reachable only through old live sessions and become
  collectible with them; `AgentSession.reload()` is resource-only and never changes generations.
- **A `pi` `Model` must never cross the wire raw** — provider/extension configuration may carry secrets in
  `baseUrl`, headers, auth, or provider closures. Every model-bearing frame (`model.list`/`model.refresh`/`model.default`, the
  `session.create` result, `SessionSummary.model`) goes through `toWireModel` — the list paths share the
  one `readAvailableWireModels` read so the projection can't be bypassed by adding a caller; every inbound
  model ref (`session.create` /
  `session.setModel`) is **re-resolved** host-side by `{provider,id}` (`resolveWireModel`), never trusted.
  The wire type `WireModel = Pick<Model, id|name|provider|contextWindow|reasoning> + thinkingLevels +
  cost{input,output} + input + auth` is an
  **allowlist** — it fails closed, so a future `Model` field can't leak by default (a unit test pins the
  exact key set). `thinkingLevels` is a computed field: pi-ai's `getSupportedThinkingLevels(model)`
  mapped at the same choke point, so the effort picker renders pi's per-model support truth without the
  client re-deriving it. `cost` keeps only the two list prices (pi's `ModelCost` tiers and cache rates stay
  host-side) and `input` the modality list. **`auth`** is the per-provider connection kind projected onto
  each model (`providerAuth.ts` → `catalogProviderAuth`, from pi's synchronous `isUsingOAuth` /
  `getProviderAuthStatus` plus the generation's opaque Central ids) so the picker can say *plan* / *API key*
  / *env* / *JetBrains AI* without the `provider.status` refresh; `describeProviderAuth` is the one
  kind/detail mapping and `auth/providerStatus` reuses it, so the picker and Settings → Providers cannot
  disagree. `toWireModel(model, auth?)` takes the projection as a value: the catalog read computes it once
  per provider (`readAvailableWireModels`), the session result, summary and `setSessionModel` paths derive
  it from their own generation (`sessionWireModel`).
- A live slash-command list is derived from the **same three sources Pi's rpc mode uses**
  (`extensionRunner.getRegisteredCommands()` + `promptTemplates` + `resourceLoader.getSkills()`). The
  pre-session catalog maps only `resourceLoader.getSkills()` through the same skill→command helper and
  applies the **same project-trust gate**, so New Workspace preview and a real session cannot disagree
  except for the accepted base-branch/current-checkout timing difference.
- Dialog promises honor abort/timeout and are settled (+ dismissed in the UI) on session disposal — a
  bridged `uiContext` call must never hang.
- **Prompt-template `/name` expansion** — typed-through references like `/name args` in a prompt ride
  the agent's default `expandPromptTemplates: true` (no agent code change). It expands from the
  session's **create-time template snapshot** — a template saved mid-session is **NOT** seen by an
  already-open session's typed-through path (pi passes unknown `/name` text through verbatim). The
  composer's `/` menu path is always fresh via `template.list` (see `templates/SPEC.md` freshness rule).
