@gajae-code/coding-agent 0.12.19 → 0.12.21

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.12.21] - 2026-08-09
+
+### Fixed
+- Strict session resume now sanitizes stale replay metadata in memory without mutating the selected transcript, then publishes the terminal resume breadcrumb only after the first durable user-visible write. Declined auto-continuations restore their deferred predecessor terminal instead of dropping client settlement evidence.
+- Todo completion reminders now honor `todo.reminders.max` across an interactive turn rather than stopping after the first reminder.
+- Hidden `nextTurn` messages that trigger a follow-up model call no longer deadlock the predecessor prompt during post-prompt settlement.
+
+## [0.12.20] - 2026-08-09
+
+### Fixed
+- Parallel task children now use their durable parent/task ownership tuple as a stable provider-facing continuity identity, preventing nested managed children from contending for one websocket owner while preserving logical session headers, artifact hierarchy, detached-resume identity, and explicit provider-session overrides.
+- Session contexts no longer retain materialized resident text after the backing cache disappears; subsequent reads rematerialize the existing public-safe missing-blob placeholder. Headless `--export` coverage now expects the established error for a nonexistent source file.
+- SDK prompt reconciliation now preserves bounded safe provider failure codes after `agent_failed`, while retaining the fixed redacted wire/persisted message and recording a bounded local diagnostic.
+
+- Shadow-mode cold-session builds now compare the actual sidecar-derived provider context against the authoritative eager context and expose check/mismatch counters in `/session`; corrupt provider metadata produces a counted mismatch without weakening transcript authority. Cold branch activation now resolves compacted 10k-entry branches through one bounded ordinal-index scan and one bounded transcript range read instead of scanning a dictionary partition for every ancestor, and cold dictionary lookup skips unrelated JSON decoding while retaining full partition-digest verification. Bounded first-open, exact-reopen, and lazy cold-entry paths apply the same stale OpenAI Responses replay-metadata sanitation as eager resume.
+- ACP startup now rejects unrecognized command flags and incompatible terminal-auth modes through the normal CLI usage-error path, while preserving separate dash-leading system-prompt text.
+
+- `gjc --mode acp` no longer aborts on flags it advertises in `--help`. `parseArgs` never recognized `--extension`/`-e`, `--hook`, `--no-extensions`, `--no-skills`, or `--skills`, so every one of them landed in `unknownFlags`; once unknown flags became a hard ACP failure, launching ACP with `--no-extensions` crashed at startup with `Unsupported under SDK-backed ACP: extension flags`. All five are parsed again, so `--no-extensions` starts normally while `--extension`, `--hook`, `--no-skills`, and `--skills` are rejected under ACP by their own names — the rejection list in `resolveAcpStartupOptions` had been dead code because nothing ever populated the fields it tested. A genuinely unknown flag is now reported as `unknown flags: --typo` instead of being mislabeled an extension flag.
+
+### Added
+
+- Bounded-memory cold-session disk offloading is rollout-ready behind the `sessionMemory` settings namespace. `sessionMemory.mode` (default `"shadow"`) selects `off`/`shadow`/`enabled`: shadow measures without changing observable session behavior, and canary/default-on remain release-channel decisions rather than user-facing enum values. Fixed implementation budgets preserve the ≤64 MiB steady-state guarantee; transcript v5 stays authoritative and derived `.spill.*` sidecars remain disposable. Context materialization uses the typed `SessionContextTooLargeError` preflight, while `sessionMemory.contextOverflowRecovery` independently controls the async compact-once recovery path.
+- Enabled explicit-path resumes validate descriptor-bound commit metadata, base/tail hashes, terminal proof, and hot-record digests before loading only the authenticated post-compaction tail. Fresh-process gates cover 120k compaction cycles, direct/captured forks, and one-million-record first build plus exact lazy reopen. Managed retained-authority startup remains on the eager compatibility path pending retained-authority range support.
+- Enabled canary sessions fail closed to shadow/eager behavior after repeated sidecar build failures or failed adoption, expose the live auto-disable reason through `/session`, and clear the session-local latch through the existing `off` rollback mode. Live `enabled` → `shadow`/`off` rollback keeps existing cold entries lazily readable for the current process; the next `off`-mode start ignores derived state and restores eager compatibility.
+
 ## [0.12.19] - 2026-08-08
 
 ### Fixed
@@ -11,9 +36,10 @@
 ## [0.12.18] - 2026-08-08
 
 ### Fixed
+- Repeated provider idle-stream stalls now stop after `retry.maxRetries` instead of inheriting the unbounded transient-error retry path. A one-off stall still retries normally, while a persistently silent stream surfaces its error rather than resubmitting the same billable context indefinitely.
 
 - SDK snapshot spill writes now retry once with a fresh temporary file when Bun reports `EBADF` during write or `fsync` under heavily contended descriptor teardown, and no longer fail when `close()` reports `EBADF` after a successful write and sync. The atomic writer removes the abandoned attempt before retrying, preserves primary I/O failures, accepts only the proven already-closed close case, and keeps every non-`EBADF` error or repeated descriptor failure fatal.
-- ACP now imports the synthetic model-profile provider namespace from a dependency-free SDK constant module, keeping the machine entrypoint out of model-registry, session-host, MCP-manager, and extension-runner closures enforced by `check:runtime`.
+- Discord Gateway ingestion now decodes text and binary WebSocket payloads, resolves a thread's missing parent-channel metadata through Discord's REST API, and stops reconnecting after terminal authentication, sharding, version, or intent close codes.
 
 ## [0.12.17] - 2026-08-08
 
@@ -94,14 +120,6 @@
 - GJC no longer advertises `mcpCapabilities.sse`. The legacy MCP HTTP+SSE transport (spec 2024-11-05, deprecated) is not implemented: an `sse` config is routed to the Streamable HTTP transport, which never performs the required `endpoint`-event handshake, so a genuine legacy-SSE server offered by an ACP client could not connect. Locally configured `sse` entries still resolve through `createTransport` and keep working.
 - Reverse ACP responses (`fs/read_text_file`, terminal output) are now measured as the full serialized frame rather than only the inner `result`. A near-limit result passed the 256 KiB check and then tripped the WebSocket total-frame ceiling, closing the whole session instead of raising the typed `payload_too_large`.
 - `todo_write` now accepts `complete` and `completed` as aliases for the `done` operation. The status this operation sets is spelled `completed`, so models repeatedly emitted `op: "complete"` and hit a hard mid-turn tool failure; the operation vocabulary is otherwise unchanged and a completion still requires a task or phase target.
-||||||| parent of d5f44548e (fix(todo): accept the operation and field synonyms models actually emit)
-- ACP `session/prompt` no longer hangs forever when the agent continues mid-prompt. Any continuation (todo reminder, TTSR resume, auto-continue) re-enters the agent loop and emits a second `agent_start`, which shifted the already-empty pending queue and overwrote the live prompt correlation with `undefined`. The prompt's `agent_end` then carried no correlation, `terminalizePrompt` never ran, and every ACP client (Paseo, Zed, JetBrains Air) waited until the 30-minute `sdk.promptDeadlineMs` before failing with `prompt_deadline_exceeded` — despite the answer having already streamed. `agent_start` now claims a pending correlation only when the session has no active one, and the todo-completion continuation holds the predecessor `agent_end` like every other continuation call site.
-- ACP clients can now render the user's own message and its image attachments. A live prompt turn emitted no `user_message_chunk` at all — that update only existed on the `session/load` replay path — so an attached image reached the model but never appeared in the client transcript. `session/prompt` now echoes the prompt's text and image content blocks as `user_message_chunk` before dispatching the turn.
-- An oversize ACP prompt now fails with a typed, actionable error instead of killing the session. The SDK WebSocket server caps a request frame at 256 KiB (`REQUEST_FRAME_BYTES`) and answers an oversize frame with `CloseCode::Size`, which surfaced to clients as an opaque `-32603 connection_closed` mid-turn; a 244 KiB PNG reproduced it while a 59 KiB PNG succeeded. The prompt is now measured inside its real `control_request` envelope and rejected up front with `-32602` naming the actual and permitted size.
-- ACP `session/cancel` and `session/close` now settle the pending `session/prompt` with `stopReason: "cancelled"` instead of surfacing a transport error. A cancel that landed during prompt preflight rejected with `busy`, and `session/close` rejected with `connection_closed`, both of which clients display as spurious errors for the user's own action. The spec requires agents to "catch these errors and return the semantically meaningful `cancelled` stop reason"; involuntary teardown still rejects.
-- GJC no longer advertises `mcpCapabilities.sse`. The legacy MCP HTTP+SSE transport (spec 2024-11-05, deprecated) is not implemented: an `sse` config is routed to the Streamable HTTP transport, which never performs the required `endpoint`-event handshake, so a genuine legacy-SSE server offered by an ACP client could not connect. Locally configured `sse` entries still resolve through `createTransport` and keep working.
-- Reverse ACP responses (`fs/read_text_file`, terminal output) are now measured as the full serialized frame rather than only the inner `result`. A near-limit result passed the 256 KiB check and then tripped the WebSocket total-frame ceiling, closing the whole session instead of raising the typed `payload_too_large`.
-- `todo_write` now accepts `complete` and `completed` as aliases for the `done` operation. The status this operation sets is spelled `completed`, so models repeatedly emitted `op: "complete"` and hit a hard mid-turn tool failure; the operation vocabulary is otherwise unchanged and a completion still requires a task or phase target.
 
 - `todo_write` now rejects malformed raw arguments with bounded, authority-controlled correction codes instead of a generic rejection: unknown root keys, unknown operation-entry keys, done/drop entries without a task or phase target, and unknown init list-entry keys each surface a fixed message naming the accepted shape without echoing the offending input, while recoverable payloads keep the passthrough/coercion path and the existing ask-tool codes are untouched (#3916).
 - The Alibaba Token Plan onboarding preset and `alibaba-token-plan-qwen-deepseek` profile now reference the provider-supported `qwen3.8-max` model id instead of `qwen-3.8-max`, preventing the built-in profile from selecting an HTTP 400 unsupported model (#3909).

package/dist/types/commands/gc.d.ts

@@ -20,6 +20,10 @@ export default class Gc extends Command {
             description: string;
             default: boolean;
         };
+        disk: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
         "repair-session-index": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
             description: string;
             default: boolean;

package/dist/types/commands/sdk.d.ts

@@ -26,11 +26,77 @@ export declare function watchSessionHostBrokerLiveness(deps: {
     graceMs?: number;
     pollMs?: number;
 }): Promise<void>;
+/**
+ * How long a session host that has served at least one client tolerates having
+ * no client attached before treating itself as abandoned.
+ *
+ * This cannot fire during healthy work. "Attached" is the host's own live
+ * socket-subscription count, so a client that is merely idle — an editor
+ * sitting on an open ACP session, a long agent turn with nobody typing — still
+ * holds a socket and resets the window on every poll. Only a client that is
+ * actually gone opens it, and 30 minutes is far longer than any client
+ * reconnect budget (ACP's is seconds), so a crashed-and-restarted client
+ * reattaches long before the window closes.
+ */
+export declare const SESSION_HOST_DETACHED_IDLE_GRACE_MS: number;
+/**
+ * How long a freshly spawned session host waits for its very first client
+ * before treating itself as abandoned.
+ *
+ * A host is ready before its client has finished dialing, so a host that has
+ * never seen an attachment must not be judged by the detached window above. One
+ * hour is orders of magnitude beyond the slowest observed cold start (worktree
+ * preparation, MCP server launch, model-profile application) and beyond any
+ * lifecycle readiness deadline the broker will wait on, so it can only elapse
+ * for a host nobody ever came for.
+ */
+export declare const SESSION_HOST_FIRST_ATTACH_GRACE_MS: number;
+/**
+ * Resolves once this host is provably abandoned: either it has been detached
+ * from every client for the full idle grace, or nobody has come for it at all
+ * for the full first-attach grace.
+ *
+ * `readAttachedClients` reports the host's own live client/socket subscription
+ * count; `undefined` means the SDK endpoint publishes no such evidence yet and
+ * is deliberately *not* treated as detachment, so a host can never be reaped on
+ * missing evidence — only on observed absence of clients.
+ *
+ * `readWorkInFlight` reports whether the host is running agent work right now.
+ * Work is positive proof that a client did come for this host: a prompt can
+ * only arrive over the endpoint a client dialed. So for a host that has never
+ * been *observed* attached — a client that connected, prompted and dropped
+ * between two 30s polls, or a client count that is momentarily unreadable — the
+ * first-attach window is measured from the last moment work was in flight
+ * rather than from process start. That still bounds a host whose SDK runtime
+ * never came up: with no transport it can never receive a prompt, so it never
+ * reports work and its window keeps running from start. And any real turn ends,
+ * after which the window resumes; live work defers the bound, never removes it.
+ */
+export declare function watchSessionHostClientAttachment(deps: {
+    readAttachedClients: () => number | undefined;
+    readWorkInFlight?: () => boolean;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    idleGraceMs?: number;
+    firstAttachGraceMs?: number;
+    pollMs?: number;
+}): Promise<void>;
 /** Opens lifecycle-authorized history without letting replacement content reach readiness. */
 export declare function openLifecycleSessionManager(request: SessionLifecycleLaunchRequest, cwd: string, agentDir: string): Promise<{
     parsed: ParsedArgs;
     sessionManager: SessionManager | undefined;
 }>;
+/**
+ * Starts the memory backend a lifecycle session deferred past its readiness
+ * window.
+ *
+ * Deliberately not awaited: the local backend summarises every queued rollout
+ * through the model, so its duration scales with the backlog and would eat the
+ * broker's readiness budget. The session is already published as ready here, so
+ * a failure is a degraded-memory condition, not a startup failure — it is
+ * logged and swallowed instead of surfacing as an unhandled rejection.
+ */
+export declare function startMemoryBackendAfterReadiness(start: () => Promise<void>): void;
 /** Runs the same persisted AgentSession bootstrap used by the production CLI. */
 export declare function runSessionHost(timing?: {
     now?: () => number;

package/dist/types/config/settings-schema.d.ts

@@ -2500,6 +2500,15 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
+    readonly "sessionMemory.mode": {
+        readonly type: "enum";
+        readonly values: readonly ["off", "shadow", "enabled"];
+        readonly default: "shadow";
+    };
+    readonly "sessionMemory.contextOverflowRecovery": {
+        readonly type: "boolean";
+        readonly default: true;
+    };
     readonly "edit.mode": {
         readonly type: "enum";
         readonly values: import("../edit").EditMode[];
@@ -3273,6 +3282,26 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Parent-process RSS (MB) above which idle tabs are opportunistically evicted LRU.";
         };
     };
+    readonly "gc.sessions.maxAgeDays": {
+        readonly type: "number";
+        readonly default: 60;
+        readonly validate: (value: number) => boolean;
+    };
+    readonly "gc.sessions.maxTotalBytes": {
+        readonly type: "number";
+        readonly default: 0;
+        readonly validate: (value: number) => boolean;
+    };
+    readonly "gc.natives.keepVersions": {
+        readonly type: "number";
+        readonly default: 2;
+        readonly validate: (value: number) => boolean;
+    };
+    readonly "gc.backups.maxAgeDays": {
+        readonly type: "number";
+        readonly default: 30;
+        readonly validate: (value: number) => boolean;
+    };
     readonly "resourceGc.sweepIntervalMs": {
         readonly type: "number";
         readonly default: 30000;
@@ -4465,6 +4494,10 @@ export interface ShellMinimizerSettings {
     except: string[];
     maxCaptureBytes: number;
 }
+export interface SessionMemorySettings {
+    mode: "off" | "shadow" | "enabled";
+    contextOverflowRecovery: boolean;
+}
 export interface MemoryGuardSettings {
     enabled: boolean;
     checkIntervalMs: number;
@@ -4538,6 +4571,7 @@ export interface GroupTypeMap {
     thinkingBudgets: ThinkingBudgetsSettings;
     stt: SttSettings;
     memoryGuard: MemoryGuardSettings;
+    sessionMemory: SessionMemorySettings;
     modelRoles: Record<string, ModelSelectorValue>;
     modelTags: ModelTagsSettings;
     cycleOrder: string[];

package/dist/types/gjc-runtime/gc-runtime.d.ts

@@ -122,6 +122,11 @@ export interface GcReport {
     session_index?: GcSessionIndexHealth;
     /** Managed-scope capacity, reported only when it is near or past the budget. */
     session_scope?: GcSessionScopeUsage;
+    /**
+     * Disk-retention findings. Present only when `--disk` was passed; the
+     * PID-liveness axis above is unchanged by its absence or presence.
+     */
+    disk?: GcDiskReport;
 }
 export interface GcRunResult {
     stdout: string;
@@ -149,9 +154,100 @@ export declare function collectGcReport(adapters: GcStoreAdapter[], ctx: GcConte
  * - prune mode with a failed intended removal => 1
  * - warnings alone never fail the run
  * - otherwise => 0
+ *
+ * The disk axis reuses the same policy against its own errors/failures, and is
+ * inert when `--disk` was not passed (`report.disk` is then undefined). A
+ * fail-closed KEEP is never a failure — only a hard scan error or a reclaim
+ * that was attempted and threw.
  */
 export declare function computeExitCode(report: GcReport): number;
-export declare function runGjcGcCommand(argv: string[], cwd?: string, env?: NodeJS.ProcessEnv, adapters?: GcStoreAdapter[]): Promise<GcRunResult>;
+export declare function runGjcGcCommand(argv: string[], cwd?: string, env?: NodeJS.ProcessEnv, adapters?: GcStoreAdapter[], diskPolicy?: Partial<GcDiskPolicy>): Promise<GcRunResult>;
 export declare function gcHelpText(): string;
 /** Lazily assemble the real store adapters (kept lazy to avoid import cycles). */
 export declare function defaultGcAdapters(): Promise<GcStoreAdapter[]>;
+/** On-disk surfaces the retention axis can reclaim. */
+export type GcDiskSurface = "sessions" | "blobs" | "natives" | "backups";
+export declare const GC_DISK_SURFACES: readonly GcDiskSurface[];
+export type GcDiskAction = "keep" | "would_reclaim" | "reclaimed" | "reclaim_failed";
+export interface GcDiskRecord {
+    surface: GcDiskSurface;
+    /** Session id, blob hash, natives version, or backup entry name. */
+    id: string;
+    path: string;
+    bytes: number;
+    age_days: number;
+    action: GcDiskAction;
+    reason: string;
+    error?: string;
+    /** Set when `bytes` is a floor because a walk was capped or partially unreadable. */
+    partial?: true;
+    /** Set when this entry was a reclaim candidate that its surface withheld on incomplete evidence. */
+    withheld?: true;
+}
+/**
+ * Why a surface refused to reclaim anything, and how much it withheld to stay
+ * fail-closed. Present only when the surface declined.
+ */
+export interface GcDiskDeclined {
+    reason: string;
+    withheld: number;
+    withheld_bytes: number;
+}
+export interface GcDiskSurfaceReport {
+    surface: GcDiskSurface;
+    root: string;
+    scanned: number;
+    scanned_bytes: number;
+    reclaimable: number;
+    reclaimable_bytes: number;
+    reclaimed: number;
+    reclaimed_bytes: number;
+    kept: number;
+    kept_bytes: number;
+    failed: number;
+    /** Set when the surface declined to reclaim anything because its evidence was incomplete. */
+    declined?: GcDiskDeclined;
+    records: GcDiskRecord[];
+}
+export interface GcDiskError {
+    surface: GcDiskSurface;
+    scope: string;
+    message: string;
+}
+/** Retention policy, mirroring the `gc.*` settings one-for-one. */
+export interface GcDiskPolicy {
+    sessions_max_age_days: number;
+    /** 0 disables the size axis; only the age axis retires transcripts then. */
+    sessions_max_total_bytes: number;
+    natives_keep_versions: number;
+    backups_max_age_days: number;
+}
+export interface GcDiskReport {
+    dry_run: boolean;
+    policy: GcDiskPolicy;
+    surfaces: Record<GcDiskSurface, GcDiskSurfaceReport>;
+    totals: {
+        scanned_bytes: number;
+        reclaimable_bytes: number;
+        reclaimed_bytes: number;
+        kept_bytes: number;
+        failed: number;
+    };
+    errors: GcDiskError[];
+}
+/** Schema-backed defaults, so the CLI and the settings surface cannot drift. */
+export declare const GC_DISK_POLICY_DEFAULTS: GcDiskPolicy;
+export declare function resolveGcDiskPolicy(overrides?: Partial<GcDiskPolicy>): GcDiskPolicy;
+/**
+ * Run the disk-retention axis. Nothing is mutated unless `prune` is true; the
+ * dry-run report projects exactly the same decisions a prune would make.
+ */
+export declare function collectGcDiskReport(input: {
+    agentDir: string;
+    env: NodeJS.ProcessEnv;
+    policy: GcDiskPolicy;
+    prune: boolean;
+    now?: number;
+    runningVersion?: string;
+}): Promise<GcDiskReport>;
+export declare function buildGcDiskReportText(disk: GcDiskReport): string;

package/dist/types/modes/acp/acp-agent.d.ts

@@ -1,5 +1,6 @@
 import { type Agent, type AgentSideConnection, type AuthenticateRequest, type AuthenticateResponse, type AvailableCommand, type ClientCapabilities, type CloseSessionRequest, type CloseSessionResponse, type DeleteSessionRequest, type DeleteSessionResponse, type ForkSessionRequest, type ForkSessionResponse, type InitializeRequest, type InitializeResponse, type ListSessionsRequest, type ListSessionsResponse, type LoadSessionRequest, type LoadSessionResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type ResumeSessionRequest, type ResumeSessionResponse, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
 import { type AcpProviderRegistration, type AcpReverseConnection, AcpSdkAdapter } from "../../sdk/acp";
+import { type PromptWatchdogClock } from "../../sdk/prompt-watchdog";
 import type { AcpStartupOptions } from "./startup-options";
 type JsonObject = Record<string, unknown>;
 /** Applies ACP's offset cursor after narrowing the broker listing to the requested cwd. */
@@ -30,7 +31,37 @@ export interface TranscriptReplayContent {
         reason: "historical_transcript_images_unavailable";
     };
 }
-export declare function transcriptReplayContent(entry: unknown): TranscriptReplayContent;
+/** Machine-readable reason replay could not restore a transcript entry. */
+export type TranscriptReplaySkipReason = "transcript_body_unavailable" | "transcript_tool_call_unavailable";
+/**
+ * Replay decides per entry. An entry whose production body is missing is not
+ * replayable, and the caller reports that boundary instead of failing the whole
+ * load; fabricating an empty body would replay a message that never existed.
+ */
+export type TranscriptReplayEntry = {
+    replayable: true;
+    content: TranscriptReplayContent;
+} | {
+    replayable: false;
+    reason: TranscriptReplaySkipReason;
+};
+export declare function transcriptReplayContent(entry: unknown): TranscriptReplayEntry;
+/**
+ * `transcript.list` answers an entry larger than one page with a body-less row
+ * `{ id, error: { code: "item_too_large" }, continuations }`. Each continuation is a
+ * `Q23` (`resource.body`) descriptor for one indexed string field of that entry, so
+ * the row is a pointer to the largest message in the session rather than a broken
+ * entry. Replay follows it instead of dropping the message.
+ */
+export interface TranscriptContinuation {
+    query: string;
+    resourceKind: string;
+    resourceId: string;
+    revision: string;
+    itemId: string;
+    field: string;
+}
+export declare function transcriptContinuations(entry: unknown): TranscriptContinuation[];
 /**
  * Collect every page of `providers.list/active` (Q29, GJC >= 0.12.8) and
  * return the providers with usable stored credentials or credentialless
@@ -250,6 +281,7 @@ export declare class AcpAgent implements Agent {
         agentDir?: string;
         startupOptions?: AcpStartupOptions;
         cancelSettlementGraceMs?: number;
+        promptWatchdogClock?: PromptWatchdogClock;
     } | unknown);
     initialize(params: InitializeRequest): Promise<InitializeResponse>;
     authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse>;

package/dist/types/modes/components/bash-execution.d.ts

@@ -26,4 +26,11 @@ export declare class BashExecutionComponent extends Container {
      * Get the command that was executed.
      */
     getCommand(): string;
+    /**
+     * Record that this execution's message reached session state, so a transcript
+     * rebuild renders it from the session instead of keeping this live block parked.
+     */
+    markResultPersisted(): void;
+    /** Whether the session already holds this execution's message. */
+    hasPersistedResult(): boolean;
 }

package/dist/types/modes/components/eval-execution.d.ts

@@ -20,4 +20,11 @@ export declare class EvalExecutionComponent extends Container {
     }): void;
     getOutput(): string;
     getCode(): string;
+    /**
+     * Record that this execution's message reached session state, so a transcript
+     * rebuild renders it from the session instead of keeping this live block parked.
+     */
+    markResultPersisted(): void;
+    /** Whether the session already holds this execution's message. */
+    hasPersistedResult(): boolean;
 }

package/dist/types/modes/utils/ui-helpers.d.ts

@@ -37,6 +37,15 @@ export declare class CollapsedChatHistoryComponent implements Component {
     invalidate(): void;
 }
 export declare function addChatChild(ctx: InteractiveModeContext, component: Component): void;
+/**
+ * Parked `!`/`$` execution components are listed in `pendingBashComponents` /
+ * `pendingPythonComponents`, but `pendingMessagesContainer` is the only
+ * authority on parentage: `/clear`, `/context-clear`, extension redraws and the
+ * selector all call `pendingMessagesContainer.clear()`, which disposes and
+ * evicts parked components without touching those arrays. Drop every entry the
+ * container no longer holds so nothing downstream can move a dead component.
+ */
+export declare function syncPendingExecutionComponents(ctx: InteractiveModeContext): void;
 export declare function trimChatChildren(ctx: InteractiveModeContext): void;
 export declare class UiHelpers {
     #private;
@@ -84,7 +93,7 @@ export declare class UiHelpers {
     flushCompactionQueue(options?: {
         willRetry?: boolean;
     }): Promise<void>;
-    /** Move pending bash components from pending area to chat */
+    /** Move pending bash/python components from the pending area to chat */
     flushPendingBashComponents(): void;
     findLastAssistantMessage(): AssistantMessage | undefined;
     extractAssistantText(message: AssistantMessage): string;

package/dist/types/sdk/acp/adapter.d.ts

@@ -1,4 +1,6 @@
-import { SdkClient, SdkClientError, type SdkClientOptions, type SdkFrame } from "../client";
+import { SdkClient, SdkClientError, type SdkFrame } from "../client";
+import { ACP_SESSION_RECONNECT } from "../session-reconnect";
+import type { SessionLifecycleMcpServer } from "./mcp";
 type JsonObject = Record<string, unknown>;
 /** The small agent-side ACP surface used for reverse requests. */
 export interface AcpReverseConnection {
@@ -26,23 +28,14 @@ export declare class AcpSdkAdapterError extends Error {
     readonly code: string;
     constructor(code: string, message?: string);
 }
-export type AcpReconnectFailedHandler = (error: SdkClientError) => void;
-export type AcpFrameHandler = (frame: SdkFrame) => void;
-type AcpSessionReconnectOptions = Required<Pick<SdkClientOptions, "reconnectAttempts" | "reconnectBackoffMs" | "reconnectMaxBackoffMs">>;
 /**
- * Reconnect budget for long-lived ACP sessions.
- *
- * Invariant: the client's total reconnect budget must outlive the host heartbeat
- * TTL ({@link HEARTBEAT_TTL_MS}). The SDK host drops a session whose client has
- * not ponged within that TTL, so a client that gives up reconnecting sooner turns
- * every stall the host reaps into a permanently lost session ("SDK WebSocket
- * reconnect attempts exhausted"). The transport defaults (3 attempts at 25ms base
- * = 175ms total) are correct only for one-shot request clients.
- *
- * Backoff ramps 250 -> 500 -> 1000 and then holds at the 2s cap, so individual
- * sleeps stay short and recovery is prompt once the host answers again.
+ * The error an ACP session launch must throw once a lifecycle request that carried MCP
+ * servers has failed.
  */
-export declare const ACP_SESSION_RECONNECT: AcpSessionReconnectOptions;
+export declare function acpMcpLaunchFailure(error: unknown, mcpServers: SessionLifecycleMcpServer[]): unknown;
+export type AcpReconnectFailedHandler = (error: SdkClientError) => void;
+export type AcpFrameHandler = (frame: SdkFrame) => void;
+export { ACP_SESSION_RECONNECT };
 /**
  * Pure ACP-to-SDK adapter. It deliberately owns neither an AgentSession nor an
  * ACP bridge: all session work is performed through authenticated v3 frames.
@@ -81,4 +74,3 @@ export declare class AcpSdkAdapter {
     handle(method: string, params?: JsonObject): Promise<unknown>;
     registerProvider(provider: AcpProviderRegistration): Promise<void>;
 }
-export {};

package/dist/types/sdk/acp/index.d.ts

@@ -1,2 +1,2 @@
 export type { AcpProviderRegistration, AcpReverseConnection, AcpSdkAdapterOptions } from "./adapter";
-export { ACP_SESSION_RECONNECT, AcpSdkAdapter, AcpSdkAdapterError } from "./adapter";
+export { ACP_SESSION_RECONNECT, AcpSdkAdapter, AcpSdkAdapterError, acpMcpLaunchFailure } from "./adapter";

package/dist/types/sdk/broker/broker.d.ts

@@ -19,7 +19,7 @@ type ResolvedBrokerSettings = {
     heartbeatTtlMs: number;
     resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
 };
-export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "readiness_timeout" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
+export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "startup_admission_timeout" | "startup_admission_refused" | "readiness_timeout" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
 export type BrokerCleanupIdentity = {
     dev: string;
     ino: string;
@@ -120,6 +120,77 @@ export type BrokerResponse = {
     durableEffects?: LifecycleDurableEffectsReceipt;
     startupFailure?: LifecycleStartupFailureReceipt;
 };
+/** Tombstone prefix used by {@link Broker.reclaimStaleLock} when a dead owner's lock is renamed aside. */
+export declare const BROKER_LOCK_TOMBSTONE_PREFIX = ".broker.lock.stale-";
+/**
+ * Recovery directories left beside the lock by manual and older automated broker
+ * restarts. Nothing writes them today, but installs that ever recovered by hand
+ * still carry them, so the reaper owns them alongside its own tombstones.
+ */
+export declare const BROKER_LOCK_BACKUP_PREFIXES: readonly ["broker-restart-backup-", "broker-stale-backup-"];
+/**
+ * Age bound before a reclaimed lock artifact may be removed. Generous enough
+ * that a broker still settling after a reclaim can never have its own successor
+ * state deleted underneath it.
+ */
+export declare const BROKER_LOCK_ARTIFACT_GRACE_MS: number;
+/** Why a candidate lock artifact survived a reap pass. */
+export type BrokerLockArtifactRetentionReason = "within-grace" | "owner-alive" | "owner-record-unreadable" | "owner-record-missing" | "not-a-directory" | "removal-failed";
+export interface BrokerLockArtifactRetention {
+    path: string;
+    reason: BrokerLockArtifactRetentionReason;
+}
+export interface BrokerLockArtifactReapResult {
+    removed: string[];
+    retained: BrokerLockArtifactRetention[];
+}
+/**
+ * Remove reclaimed broker lock tombstones and legacy restart backups older than
+ * the grace window.
+ *
+ * `#reclaimStaleLock` renames a dead owner's lock to a tombstone named by a hash
+ * of the lock's dev+ino, so a machine accrues one directory per dead owner and
+ * nothing ever removed them (54 on the install in #3963). Reaping is
+ * best-effort and fail-closed: anything live, unreadable, permission-denied, or
+ * otherwise ambiguous is kept and the reason is logged.
+ */
+export declare function reapStaleBrokerLockArtifacts(input: {
+    agentDir: string;
+    now?: number;
+    graceMs?: number;
+    pidAlive?: (pid: number) => boolean;
+}): Promise<BrokerLockArtifactReapResult>;
+export interface StartupAdmissionTiming {
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+export type StartupAdmissionResult<T> = {
+    status: "completed";
+    admittedAt: number;
+    value: T;
+} | {
+    status: "admission_timeout";
+    reason: "admission_timeout";
+} | {
+    status: "admission_refused";
+    reason: "admission_refused";
+};
+export declare function sdkHostStartupConcurrency(availableParallelism?: number): number;
+export declare class StartupAdmissionQueue {
+    #private;
+    readonly limit: number;
+    constructor(limit: number);
+    run<T>(queueWaitMs: number, timing: StartupAdmissionTiming, task: (admittedAt: number) => Promise<T>): Promise<StartupAdmissionResult<T>>;
+    /**
+     * Refuse every queued startup and every later one. A broker that can no longer
+     * prove it owns the published root must not spawn children through slots that
+     * free up while it is fenced. The epoch also invalidates a waiter that was
+     * granted but has not crossed the task execution boundary yet.
+     */
+    close(): void;
+    /** Accept later startups after fresh publication ownership has been proven. */
+    reopen(): void;
+}
 export declare class Broker {
     #private;
     readonly settings: ResolvedBrokerSettings;
@@ -127,11 +198,30 @@ export declare class Broker {
     readonly ledger: LifecycleLedger;
     discovery: BrokerDiscovery | null;
     constructor(settings: BrokerSettings);
+    runStartup<T>(queueWaitMs: number, timing: StartupAdmissionTiming, task: (admittedAt: number) => Promise<T>): Promise<StartupAdmissionResult<T>>;
     start(): Promise<BrokerDiscovery>;
     get ownsDiscovery(): boolean;
     get completion(): Promise<void>;
     status(): RedactedBrokerDiscovery | null;
     heartbeat(): Promise<void>;
+    /**
+     * Revalidate retained publication ownership and begin one synchronous effect in
+     * the same stack. The callback is the authority boundary: callers must perform
+     * the authorized effect inside it, so no awaited work can separate proof from
+     * the effect it authorizes.
+     */
+    runSynchronousEffectWithFreshPublicationAuthority<T>(effect: () => T, ..._synchronousOnly: T extends PromiseLike<unknown> ? [never] : []): {
+        authorized: true;
+        value: T;
+    } | {
+        authorized: false;
+    };
+    /**
+     * A stop may take the owning path only while it can prove it still owns the root.
+     * Claiming ownership it cannot prove keeps the admission queue open, so a startup
+     * queued behind this broker is granted a slot that frees after completion and
+     * spawns a child the broker has no authority over.
+     */
     stop(): Promise<void>;
     handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string): Promise<BrokerResponse>;
 }
@@ -139,6 +229,8 @@ export declare class Broker {
 export declare function setTerminalPersistenceHookForTest(broker: Broker, hook: (() => void) | undefined): void;
 /** Test-only hook for shortening the bounded ambiguity deadline. */
 export declare function setAmbiguityGraceForTest(broker: Broker, graceMs: number | undefined): void;
+/** Test-only hook for shortening the startup lock-artifact reap bound. */
+export declare function setLockArtifactGraceForTest(broker: Broker, graceMs: number | undefined): void;
 /** Test-only hook for forcing the observation the publication watchdog sees. */
 export declare function setPublicationObservationForTest(broker: Broker, observation: BrokerPublicationObservation | undefined): void;
 export {};

package/dist/types/sdk/broker/ensure.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess } from "node:child_process";
+import type { FileHandle } from "node:fs/promises";
 import { type BrokerDiscovery } from "./discovery";
 import { type SdkInternalSpawnCommand } from "./runtime";
 export interface EnsureBrokerSettings {
@@ -11,6 +12,22 @@ export interface EnsureBrokerSettings {
      */
     env?: NodeJS.ProcessEnv;
 }
+/**
+ * Tail of the detached broker's stderr folded into a discovery failure.
+ *
+ * The broker used to spawn with `stdio: "ignore"`, so a broker that exited
+ * cleanly told the caller nothing beyond `code=0` (#3963). Its stderr goes to a
+ * file instead of a pipe because the child is detached and outlives this
+ * process: a pipe would break under it the moment the parent exits.
+ */
+export declare const BROKER_SPAWN_LOG_TAIL_BYTES = 4096;
+export interface BrokerSpawnLog {
+    path: string;
+    handle: FileHandle;
+}
+/** Opens an isolated, bounded-lifetime diagnostic sink for one broker spawn. */
+export declare function openBrokerSpawnLog(agentDir: string): Promise<BrokerSpawnLog | undefined>;
+export declare function readBrokerSpawnLogTail(spawnLogPath: string): Promise<string>;
 export interface FixtureBrokerLease {
     /** Backward-compatible fixture cleanup alias for exact child termination. */
     close(): Promise<void>;

package/dist/types/sdk/broker/index.d.ts

@@ -5,4 +5,5 @@ export * from "./identity";
 export * from "./lifecycle";
 export * from "./lifecycle-ledger";
 export * from "./session-index";
+export * from "./startup-budget";
 export * from "./transport";