@gajae-code/coding-agent 0.17.1 → 0.17.4

package/dist/types/modes/controllers/selector-controller.d.ts

@@ -131,7 +131,7 @@ export declare class SelectorController {
         smartRoutingOnly?: boolean;
     }): void;
     showPluginSelector(mode?: "install" | "uninstall"): Promise<void>;
-    showUserMessageSelector(): void;
+    showUserMessageSelector(onCommitted?: () => void): void;
     showTreeSelector(): void;
     showSessionSelector(): Promise<void>;
     handleResumeSession(sessionPath: string): Promise<void>;

package/dist/types/modes/interactive-mode.d.ts

@@ -257,7 +257,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     handleDropCommand(): Promise<boolean>;
     handleForkCommand(): Promise<void>;
     handleMoveCommand(targetPath: string): Promise<void>;
-    handleRenameCommand(title: string): Promise<void>;
+    handleRenameCommand(title?: string): Promise<void>;
     handleMemoryCommand(text: string): Promise<void>;
     handleSTTToggle(): Promise<void>;
     showDebugSelector(): void;

package/dist/types/modes/shared/agent-wire/workflow-gate-broker.d.ts

@@ -8,6 +8,8 @@ export type PersistedResolutionOrigin = {
     kind: "telegram_notification";
     interactionActionId: string;
 };
+/** Keep accepted diagnostics below the coordinator's cumulative Q12 snapshot cap. */
+export declare const MAX_ACCEPTED_WORKFLOW_GATE_QUERY_RECORDS = 32;
 export type PersistedAckPolicy = {
     kind: "none";
     reason: "non_telegram" | "semantic_noncommit" | "legacy_unproven";
@@ -95,7 +97,7 @@ export interface WorkflowGateEmitter {
  */
 export declare class BrokerWorkflowGateEmitter implements WorkflowGateEmitter {
     #private;
-    constructor(runId: string, store: GateStore, emitterHooks?: Pick<BrokerHooks, "advance">);
+    constructor(runId: string, store: GateStore, emitterHooks?: Pick<BrokerHooks, "advance" | "continuationLost">);
     supportsRemoteGateAnswers(): boolean;
     setRuntimeTurnProvider(provider: (() => string | undefined) | null): void;
     emitGate(input: OpenGateInput): Promise<unknown>;
@@ -193,6 +195,11 @@ export type GateAuditEvent = {
 } | {
     event: "gate_response_idempotent_replay";
     gate_id: string;
+}
+/** An idempotent replay refused because this runtime cannot prove the continuation ran. */
+ | {
+    event: "gate_response_replay_unproven";
+    gate_id: string;
 } | {
     event: "gate_response_idempotency_conflict";
     gate_id: string;
@@ -225,6 +232,8 @@ export interface BrokerHooks {
     terminalizeAccepted?(record: PersistedGate): WorkflowGateTerminalProof | Promise<WorkflowGateTerminalProof>;
     /** Runs only after a successful advance has been durably marked advanced. */
     completeAccepted?(record: PersistedGate): void | Promise<void>;
+    /** Notifies the owning runtime when the accepted answer cannot reach its continuation. */
+    continuationLost?(record: PersistedGate): void;
     /** Append-only audit sink. */
     audit?(event: GateAuditEvent): void;
 }
@@ -277,6 +286,7 @@ export declare class WorkflowGateBroker {
     lookupCompletedResolution(response: WorkflowGateResponse): WorkflowGateCompletedResolutionLookup;
     private runShort;
     private hasLiveContinuation;
+    private recordContinuationLoss;
     hasRecoverableAcceptedGate(): boolean;
     prepareTerminalization(gateId: string, proof: WorkflowGateTerminalProof): boolean;
     clearPreparedTerminalization(gateId: string): void;

package/dist/types/modes/shared/agent-wire/workflow-gate-types.d.ts

@@ -117,13 +117,26 @@ export interface WorkflowGateDiagnostic extends WorkflowGate {
     id: string;
     tag: "quarantined";
     lifecycle: WorkflowGateLifecycle;
+    /** Whether the durable broker retained an answer for this gate. */
+    answer_recorded: boolean;
+}
+/** Durable acceptance evidence for a gate that is no longer pending. */
+export interface WorkflowGateResolutionDiagnostic extends WorkflowGate {
+    id: string;
+    tag: "accepted";
+    /** True when the accepted record contains the answer body. */
+    answer_recorded: true;
+    resolved_at: string;
+    /** Single post-accept disposition; raw answers and derived answer values stay private. */
+    post_accept_disposition: "accepted" | "terminalized" | "advanced" | "continuation_lost" | "unknown";
 }
 /** Stable Q12 row preserving the root WorkflowGate shape. */
 export type WorkflowGateQueryRecord = (WorkflowGate & {
     id: string;
     tag: "pending";
     lifecycle?: undefined;
-}) | WorkflowGateDiagnostic;
+    answer_recorded: false;
+}) | WorkflowGateDiagnostic | WorkflowGateResolutionDiagnostic;
 /** Inbound: the agent's answer to a workflow gate. */
 export interface WorkflowGateResponse {
     gate_id: string;

package/dist/types/modes/types.d.ts

@@ -303,7 +303,7 @@ export interface InteractiveModeContext {
     handleHandoffCommand(customInstructions?: string): Promise<void>;
     handleContributionPrepCommand(customInstructions?: string): Promise<void>;
     handleMoveCommand(targetPath: string): Promise<void>;
-    handleRenameCommand(title: string): Promise<void>;
+    handleRenameCommand(title?: string): Promise<void>;
     handleMemoryCommand(text: string): Promise<void>;
     handleSTTToggle(): Promise<void>;
     executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<CompactionOutcome>;
@@ -367,7 +367,7 @@ export interface InteractiveModeContext {
     initHooksAndCustomTools(): Promise<void>;
     emitCustomToolSessionEvent(reason: "start" | "switch" | "branch" | "tree" | "shutdown", previousSessionFile?: string): Promise<void>;
     planModeController: Pick<import("./controllers/plan-mode-controller").PlanModeController, "enabled" | "paused" | "planFilePath" | "handleCommand" | "handleApproval" | "flushPendingModelSwitch">;
-    goalModeController: Pick<import("./controllers/goal-mode-controller").GoalModeController, "enabled" | "paused" | "handleCommand">;
+    goalModeController: Pick<import("./controllers/goal-mode-controller").GoalModeController, "enabled" | "paused" | "handleCommand" | "cancelContinuation" | "scheduleContinuation">;
     setHookWidget(key: string, content: ExtensionWidgetContent, options?: ExtensionWidgetOptions): void;
     setHookStatus(key: string, text: string | undefined): void;
     showHookSelector(title: string, options: string[], dialogOptions?: ExtensionUIDialogOptions): Promise<string | undefined>;

package/dist/types/runtime/process-lifecycle.d.ts

@@ -80,6 +80,8 @@ type ResourceDisposer = () => void | Promise<void>;
 export declare function registerResourceOwner(name: string, disposer: ResourceDisposer): () => void;
 /** Number of registered resource owners. Exposed for leak assertions/tests. */
 export declare function resourceOwnerCount(): number;
+/** True while a process-level resource-owner sweep is in progress. */
+export declare function isResourceOwnerDisposalActive(): boolean;
 /**
  * Run and clear every registered resource disposer. Attempts all disposers even
  * if some throw, then surfaces the failures as an `AggregateError` so callers

package/dist/types/runtime-mcp/manager.d.ts

@@ -14,6 +14,7 @@ import type { MCPProtocolObservation } from "./protocol";
 import type { MCPToolDetails } from "./tool-bridge";
 import type { MCPToolCache } from "./tool-cache";
 import type { MCPGetPromptResult, MCPInputRequestHandler, MCPPrompt, MCPRequestOptions, MCPResource, MCPResourceReadResult, MCPResourceTemplate, MCPServerConfig, MCPServerConnection } from "./types";
+export declare function isMCPStartupTimeoutError(error: unknown): boolean;
 export declare function resolveStartupTimeoutMs(configs: MCPServerConfig[], maxStartupTimeoutMs?: number): number;
 export declare function resolveExactConfigStartupTimeoutMs(configs: MCPServerConfig[]): number;
 /**
@@ -56,6 +57,20 @@ export interface MCPLoadResult {
     /** Extracted Exa API keys from filtered MCP servers */
     exaApiKeys: string[];
 }
+export type MCPToolCatalogPublication = "unpublished" | "published" | "fenced";
+/**
+ * Atomic view of the manager's fenced tool catalog and its publication state.
+ *
+ * `unpublished` is reserved for the initial deferred window where no manager
+ * catalog has been published and no exact control is fencing it. An empty
+ * `published` or `fenced` catalog is authoritative and must not be replaced
+ * with an in-flight discovery result.
+ */
+export interface MCPToolCatalogSnapshot {
+    tools: CustomTool<TSchema, MCPToolDetails>[];
+    publication: MCPToolCatalogPublication;
+    generation: number;
+}
 /** Options for discovering and connecting to MCP servers */
 export interface MCPDiscoverOptions {
     /** Whether to load project-level config (default: true) */
@@ -100,6 +115,30 @@ export interface MCPManagerOptions {
     /** Test seam for fencing the acquisition-to-registration replacement race. */
     afterLeaseAcquiredForTests?: (name: string, lease: MCPPoolLease) => void | Promise<void>;
 }
+export type ExactMcpServerControlStatus = "suspended" | "already-suspended" | "resumed" | "not-suspended" | "reconnected" | "unavailable" | "unknown-server";
+export interface ExactMcpServerControlResult {
+    readonly name: string;
+    readonly status: ExactMcpServerControlStatus;
+    readonly toolCount: number;
+}
+/**
+ * A staged catalog the caller can validate against before it is published.
+ * `commit` is the single publication point; `abort` releases anything the
+ * preparation opened and leaves the manager on its predecessor.
+ */
+export interface PreparedExactMcpCatalog {
+    readonly tools: CustomTool<TSchema, MCPToolDetails>[];
+    canCommit(): boolean;
+    commit(): Promise<void>;
+    abort(): Promise<void>;
+}
+export interface PreparedExactMcpServerControl extends PreparedExactMcpCatalog {
+    readonly result: ExactMcpServerControlResult;
+    /** Validate a resumed replacement before an atomic multi-server publication. */
+    precommit?(): void;
+    /** Publish after every replacement in the catalog has passed precommit. */
+    publish?(): void;
+}
 /**
  * MCP Server Manager.
  *
@@ -164,6 +203,23 @@ export declare class MCPManager {
      * Get all loaded tools.
      */
     getTools(): CustomTool<TSchema, MCPToolDetails>[];
+    /**
+     * Read the fenced catalog and publication state atomically.
+     *
+     * An empty catalog is still authoritative after publication or while an
+     * exact control is in flight. Deferred startup may fall back to its discovery
+     * result only for the explicit `unpublished` state.
+     */
+    getToolCatalogSnapshot(): MCPToolCatalogSnapshot;
+    isExactServerSuppressed(name: string): boolean;
+    /**
+     * Prepare one exact-config control without publishing manager state. Session
+     * registry and prompt validation run against `tools`; commit is the single
+     * publication point and abort releases only an unpublished candidate.
+     */
+    prepareExactServerControl(action: "suspend" | "resume" | "reconnect", name: string): Promise<PreparedExactMcpServerControl>;
+    /** Clear all session-local suppression before this owner adopts a new identity. */
+    prepareExactServerControlReset(): Promise<PreparedExactMcpCatalog>;
     /**
      * Get a specific connection.
      */

package/dist/types/runtime-mcp/pool.d.ts

@@ -145,6 +145,13 @@ export interface MCPPoolLease {
     onEvent(listener: LeaseListener): () => void;
     release(): Promise<void>;
 }
+export interface MCPPreparedReplacement {
+    readonly lease: MCPPoolLease;
+    canCommit(): boolean;
+    publish(): void;
+    commit(): void;
+    abort(): Promise<void>;
+}
 declare class MCPPoolLeaseImpl implements MCPPoolLease {
     #private;
     readonly generation: number;
@@ -187,7 +194,11 @@ export declare class MCPConnectionPool {
     awaitRestart(key: string): Promise<boolean>;
     finishRestart(key: string, error?: unknown): void;
     releaseRestart(key: string): void;
+    private retiredCleanupId;
+    private getRetiredAcquisitionCleanup;
+    private getRetiredAcquisitionCleanupForKey;
     private retainCancelledAcquireCleanup;
+    private retainPreparedCleanup;
     private notifyPendingAcquireCleanup;
     /** @internal Whether this pool still owns the notified abandoned-acquire flight. */
     hasPendingAcquireCleanup(error: MCPPoolAcquireAbortError): boolean;
@@ -202,6 +213,12 @@ export declare class MCPConnectionPool {
     /** @internal Join and retry one generation of abandoned acquisition cleanup. */
     closePendingAcquireCleanup(key: string, generation: number): Promise<void>;
     acquire(name: string, config: MCPServerConfig, options?: MCPPoolAcquireOptions): Promise<MCPPoolLease>;
+    /**
+     * Prepared MCP replacements fence and retain acquisition cleanup ownership
+     * The caller validates its catalog first, then commits the key swap
+     * synchronously or aborts and closes only the candidate.
+     */
+    prepareReplacement(name: string, config: MCPServerConfig, options?: MCPPoolAcquireOptions): Promise<MCPPreparedReplacement>;
     private waitForPendingEntry;
     private scheduleZeroClaimCleanup;
     private cancelPendingEntry;

package/dist/types/runtime-mcp/redaction.d.ts

@@ -1,2 +1,22 @@
+import type { AgentSession } from "../session/agent-session";
 export declare function redactMCPEndpoint(value: string | undefined): string | undefined;
 export declare function redactMCPDiagnosticValue(value: unknown): unknown;
+/**
+ * Capability granted to a session that the root interactive entry point created
+ * with an explicit `--mcp-config` path. Holding it is the only way to read exact
+ * MCP status; it carries no manager, transport, or configuration reference.
+ */
+export interface ExactMcpControls {
+    readonly grantSource: "root-interactive-exact-config";
+    /**
+     * The exact config this session was started with. Status needs it because a
+     * tools-only manager deletes a server from its own bookkeeping when the
+     * connection fails, so the manager alone can never report a server that did
+     * not come up — the very case an operator runs `/mcp` to see.
+     */
+    readonly configPath: string;
+}
+export declare function attachExactMcpControls(session: AgentSession, controls: ExactMcpControls): void;
+export declare function getExactMcpControls(session: AgentSession): ExactMcpControls | undefined;
+/** Revoke controls when the AgentSession object adopts a new logical identity. */
+export declare function revokeExactMcpControls(session: AgentSession): void;

package/dist/types/runtime-mcp/startup-policy.d.ts

@@ -1,4 +1,10 @@
 import type { MCPServerConfig } from "./types";
 export type AutoloadStatus = "autoload" | "autoload-off" | "disabled";
+/** Ordinary standalone sessions stop blocking on MCP startup after this wait. */
+export declare const DEFAULT_MCP_STARTUP_WAIT_MS = 250;
+/** Grace added to the largest declared per-server startup window. */
+export declare const MCP_STARTUP_WAIT_GRACE_MS = 500;
+/** Ordinary startup never blocks longer than this batch ceiling. */
+export declare const MAX_MCP_STARTUP_WAIT_MS = 1750;
 /** Pure startup policy shared by runtime-facing CLI inspection and doctor. */
 export declare function computeAutoloadStatus(name: string, config: Pick<MCPServerConfig, "enabled" | "autoload">, disabledServers: ReadonlySet<string>): AutoloadStatus;

package/dist/types/runtime-mcp/tool-bridge.d.ts

@@ -22,6 +22,13 @@ export interface MCPToolOptions {
      * owning manager/runtime. Resolved per call so late registration still applies.
      */
     inputHandler?: () => MCPInputRequestHandler | undefined;
+    /**
+     * Exact MCP session control: false while the owning manager has this server
+     * suspended. Checked alongside `#sessionControlInvalidated` so a wrapper that
+     * outlives a resume/reconnect still fails locally instead of reaching the
+     * transport for a server this session no longer has active.
+     */
+    isAvailable?: () => boolean;
 }
 export declare function isRetriableConnectionError(error: unknown): boolean;
 /** Details included in MCP tool results for rendering */
@@ -66,6 +73,7 @@ export declare class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
     /** Server name */
     readonly mcpServerName: string;
     private connection;
+    invalidateForSessionControl(): void;
     /** Create MCPTool instances for all tools from an MCP server lease/connection. */
     static fromTools(target: MCPToolTarget, tools: MCPToolDefinition[], reconnect?: MCPReconnect, options?: MCPToolOptions): MCPTool[];
     constructor(target: MCPToolTarget, tool: MCPToolDefinition, reconnect?: MCPReconnect | undefined, options?: MCPToolOptions);
@@ -90,6 +98,7 @@ export declare class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetai
     readonly mcpToolName: string;
     /** Server name */
     readonly mcpServerName: string;
+    invalidateForSessionControl(): void;
     /** Create DeferredMCPTool instances for all tools from an MCP server */
     static fromTools(serverName: string, tools: MCPToolDefinition[], getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect, options?: MCPToolOptions): DeferredMCPTool[];
     constructor(serverName: string, tool: MCPToolDefinition, getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect | undefined, options?: MCPToolOptions);

package/dist/types/runtime-mcp/transports/http.d.ts

@@ -1,5 +1,7 @@
 import type { MCPHttpServerConfig, MCPRequestOptions, MCPSseServerConfig, MCPTransport } from "../../runtime-mcp/types";
 import { type MCPModernClientContext, type MCPProtocolEra } from "../protocol";
+/** Live HTTP/SSE MCP transports awaiting postmortem release. Exposed for leak assertions/tests. */
+export declare function liveHttpTransportCount(): number;
 /**
  * HTTP transport for MCP servers.
  * Uses POST for requests, supports SSE responses.
@@ -38,6 +40,15 @@ export declare class HttpTransport implements MCPTransport {
     startSSEListener(): Promise<void>;
     request<T = unknown>(method: string, params?: Record<string, unknown>, options?: MCPRequestOptions): Promise<T>;
     notify(method: string, params?: Record<string, unknown>): Promise<void>;
+    /**
+     * Terminate the server-side session on a signal or fatal exit, without the
+     * reader drain `close()` does: postmortem runs inside the signal handler,
+     * where an aborted SSE body read is never observed by JS, so awaiting the
+     * readers there never settles and the DELETE stays unreachable. `onClose` is
+     * deliberately not fired - the manager reacts to it by reconnecting, which
+     * would open a fresh server session on the way out.
+     */
+    releaseForPostmortem(signal: AbortSignal): Promise<void>;
     close(): Promise<void>;
 }
 /**

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

@@ -3,6 +3,33 @@ import type { AbortScope } from "../host/control/operations";
 import { type SessionAttachment, type SessionRouter } from "../router";
 import { ACP_SESSION_RECONNECT } from "../session-reconnect";
 import type { SessionLifecycleMcpServer } from "./mcp";
+/**
+ * Registration rounds one provider activation may spend chasing a moving attachment.
+ *
+ * The activation loop restarts whenever the Router attachment changes identity while it
+ * is registering, because the leases it just took belong to a connection that no longer
+ * exists. One reconnect costs one restart, so a handful covers any churn that is actually
+ * converging; beyond that the attachment is rotating faster than registration completes
+ * and another round only re-takes leases that will be invalidated again. Bounding this is
+ * what turns "many session hosts contend for one agent dir" from an unbounded spin into a
+ * reported failure (issue #5658).
+ */
+export declare const PROVIDER_ACTIVATION_MAX_ATTEMPTS = 8;
+/**
+ * Wall-clock budget for the same loop.
+ *
+ * The attempt cap alone bounds rounds, not time: every round is a `#requestSession` round
+ * trip per provider, so under lease contention attempts are slow rather than fast-spinning
+ * and eight of them can still outlast the caller. The budget is sized to a third of
+ * {@link ACP_PROMPT_INACTIVITY_TIMEOUT_MS} so a prompt stalled in provider preflight fails
+ * with this error — which names the contended capability — with room to spare before the
+ * ACP prompt watchdog reports the same stall as undifferentiated silence.
+ *
+ * It gates *starting* another round, never interrupting one in flight: a single slow but
+ * healthy registration keeps whatever time it needs, and only a retry decided after the
+ * deadline is refused.
+ */
+export declare const PROVIDER_ACTIVATION_BUDGET_MS: number;
 type JsonObject = Record<string, unknown>;
 /** The small agent-side ACP surface used for reverse requests. */
 export interface AcpReverseConnection {

package/dist/types/sdk/acp/final-text.d.ts

@@ -16,4 +16,12 @@ export type AcpFinalTextResolution = {
 };
 export declare function boundAcpFinalText(value: string): BoundedAcpFinalText;
 export declare function acpFinalTextFromMessage(message: unknown): BoundedAcpFinalText;
+/**
+ * Assistant-content presence is trimmed everywhere in the prompt pipeline: whitespace carries no
+ * assistant content. The ACP retry gate, prompt reconciliation
+ * (`sdk/bus/prompt-reconciliation.ts`) and terminal publication must agree, otherwise a terminal
+ * the retry gate treats as "no output" can still publish a whitespace chunk alongside the retry's
+ * real answer (review P2 on #5628).
+ */
+export declare function hasAcpFinalTextContent(value: string): boolean;
 export declare function resolveAcpFinalText(streamed: string, finalText: string): AcpFinalTextResolution;

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

@@ -4,7 +4,7 @@ import { type SdkHostModelResolver } from "../host/model-pin";
 import { type DirectoryMigrationPolicy } from "../session-directory";
 import { type BrokerDiscovery, type BrokerPublicationObservation, type RedactedBrokerDiscovery } from "./discovery";
 import { type LifecycleDurableEffectsReceipt, LifecycleLedger, type LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
-import { SessionIndex } from "./session-index";
+import { type IndexedSession, SessionIndex } from "./session-index";
 import { type MasterCapabilityVerifier, type SpawnSubstrateFailure, type SpawnSubstrateProvider } from "./spawn-authority";
 export interface BrokerSettings {
     agentDir: string;
@@ -149,6 +149,9 @@ export type BrokerResponse = {
     durableEffects?: LifecycleDurableEffectsReceipt;
     startupFailure?: LifecycleStartupFailureReceipt;
 };
+export type InputNormalization = {
+    input: Record<string, unknown>;
+} | BrokerResponse;
 /** Complete five-leg child endpoint pin captured at registration. */
 export type SpawnHostRegistration = {
     sessionId: string;
@@ -201,6 +204,13 @@ export interface SpawnPromptLayer {
         pinned: SpawnHostRegistration;
     }): Promise<SpawnQ26Reconciliation>;
 }
+/** Exact admission predicate for the child host row published after launch. */
+export declare function spawnRegistrationMatches(candidate: IndexedSession, expected: {
+    childId: string;
+    cwd: string;
+    stateRoot: string;
+}): boolean;
+export declare function normalizeBrokerInput(operation: string, input: Record<string, unknown>): InputNormalization;
 /** Test seam for lifecycle serialization identity. */
 export declare function lifecycleTargetForTest(operation: string, input: Record<string, unknown>): unknown;
 /** Tombstone prefix used by {@link Broker.reclaimStaleLock} when a dead owner's lock is renamed aside. */
@@ -235,7 +245,8 @@ export interface BrokerLockArtifactReapResult {
  * 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.
+ * otherwise ambiguous is kept. Retained paths are logged at debug level and
+ * summarized in one warning per reap pass.
  */
 export declare function reapStaleBrokerLockArtifacts(input: {
     agentDir: string;

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

@@ -28,6 +28,51 @@ export interface EnsureBrokerSettings {
      */
     env?: NodeJS.ProcessEnv;
 }
+export interface BrokerStartupLockTestHooks {
+    onAcquired?: () => void;
+    onContended?: () => void;
+}
+/**
+ * Test-only phase observation for detached broker startup regressions. The
+ * signal is opt-in through the child environment and never affects broker
+ * ownership or error handling when the test seam is absent.
+ */
+export declare function emitBrokerStartupTestSignal(signal: string): Promise<void>;
+/**
+ * The parent discovery budget published as a composition rather than a number.
+ * A test that stages a fence contention has to time itself against these legs,
+ * and retyping the sum makes it win or lose on scheduler noise while letting a
+ * change to any single leg silently re-tune it (#5604). This is the one source
+ * of truth for how the budget is built; nothing may restate the arithmetic.
+ */
+export declare const BROKER_DISCOVERY_BUDGET: {
+    readonly staleRetirementMs: 5000;
+    readonly startupLockWaitMs: 9000;
+    readonly publicationMs: 15000;
+    /** What the startup fence grants its holder: retirement plus one publication attempt. */
+    readonly fenceOperationMs: number;
+    /**
+     * When a child spawned under the parent's spawn lock gives up on the fence,
+     * measured from that lock acquisition: the parent retires the stale incumbent
+     * first, then the child exhausts its own fence wait. Not a production
+     * constant -- an emergent property of the two legs that precede publication.
+     */
+    readonly childFenceWaitMs: number;
+    readonly discoveryMs: number;
+};
+/**
+ * Clock the discovery budget is measured on. The default is the real one; a test
+ * installs a virtual clock to assert the composition order -- stale retirement,
+ * then the child fence, then startup and publication -- in-process instead of
+ * racing three wall clocks against each other (#5604). Reaping keeps its own
+ * {@link ReapTiming} seam and is deliberately not driven from here.
+ */
+export interface EnsureBrokerTiming {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/** Test hook: drives the discovery budget on a controllable clock. */
+export declare function setEnsureBrokerTimingForTest(timing: EnsureBrokerTiming | undefined): void;
 type SpawnLockOptions = Pick<FileLockOptions, "retries" | "retryDelayMs" | "signal">;
 declare function readBrokerDiscoveryBeforeDeadline(agentDir: string, heartbeatTtlMs: number | undefined, deadline: number): Promise<BrokerDiscovery | null>;
 /**
@@ -48,7 +93,7 @@ declare function acquireSpawnLock(agentDir: string, options?: SpawnLockOptions):
  * The parent-held spawn lock prevents ordinary stampedes; this second fence keeps
  * startup single-flight if that detached child's launcher dies and its lock is reclaimed.
  */
-export declare function withBrokerStartupLock<T>(agentDir: string, operation: (deadline: number) => Promise<T>): Promise<T>;
+export declare function withBrokerStartupLock<T>(agentDir: string, operation: (deadline: number) => Promise<T>, testHooks?: BrokerStartupLockTestHooks): Promise<T>;
 /**
  * Tail of the detached broker's stderr folded into a discovery failure.
  *

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

@@ -1,4 +1,6 @@
 export declare function brokerIdentityPath(agentDir: string): string;
 export declare function getBrokerIdentityKey(agentDir: string): Promise<string>;
-export declare function deriveIdempotencyIdentity(agentDir: string, operation: string, callerKey: string, _protocolVersionOrLegacyTargetHash?: string): Promise<string>;
+export declare function deriveIdempotencyIdentity(agentDir: string, operation: string, callerKey: string, targetHash?: string): Promise<string>;
+/** Identity format used by lifecycle rows written before target binding. */
+export declare function deriveLegacyIdentity(agentDir: string, operation: string, callerKey: string): Promise<string>;
 export declare function deriveLegacyTargetIdentity(agentDir: string, operation: string, callerKey: string, canonicalTargetHash: string): Promise<string>;

package/dist/types/sdk/broker/lifecycle-ledger.d.ts

@@ -95,6 +95,23 @@ export type BeginResult = {
     kind: "in_progress";
     entry: LifecycleLedgerEntry;
 };
+type BoundedSourceReadRejection = "not-regular-file" | "oversized-by-stat" | "oversized-by-read" | "read-error";
+/**
+ * Why a terminal read-back produced no entry. `absent` means nothing terminal is
+ * recorded for the request; `rejected` means the source or a row was refused, which
+ * is evidence of a damaged ledger rather than of an unpersisted operation. Collapsing
+ * the two lets a corrupt source or row read as "not yet written" and unfence the session.
+ */
+export type TerminalReadBackRejection = "bounds" | "shape" | "undecodable" | "row-not-attributable" | "partial-row" | BoundedSourceReadRejection;
+export type TerminalReadBack = {
+    kind: "terminal";
+    entry: LifecycleLedgerEntry;
+} | {
+    kind: "absent";
+} | {
+    kind: "rejected";
+    reason: TerminalReadBackRejection;
+};
 export interface LifecycleLedgerLimits {
     maxBytes?: number;
     maxLineBytes?: number;
@@ -121,14 +138,15 @@ export declare class LifecycleLedger {
      * uncertainly persists that conclusion, and refusing to read it back would report a
      * synced row as unpersisted and replace its true reason with a generic one.
      */
-    readTerminal(identity: string, requestHash: string): Promise<LifecycleLedgerEntry | undefined>;
-    findByOperationKey(operationKey: string): LifecycleLedgerEntry | undefined;
+    readTerminal(identity: string, requestHash: string): Promise<TerminalReadBack>;
+    findByOperationKey(operationKey: string, fingerprint?: string): LifecycleLedgerEntry | undefined;
+    findAnyByOperationKey(operationKey: string): LifecycleLedgerEntry | undefined;
     /**
      * Legacy target-inclusive rows predate the operation/key index. Their opaque
      * identities cannot establish that a different target is safe, so callers
      * must reject rather than create a second admission.
      */
-    hasLegacyIdentity(): boolean;
+    hasLegacyIdentity(excludedIdentities?: ReadonlySet<string>): boolean;
     migrateIdentity(from: string, to: string, metadata: {
         operationKey: string;
         fingerprint: string;
@@ -137,6 +155,7 @@ export declare class LifecycleLedger {
     begin(identity: string, requestHash: string, metadata?: {
         operationKey?: string;
         fingerprint?: string;
+        intendedSessionId?: string;
     }): Promise<BeginResult>;
     transition(identity: string, state: LifecycleState, fields?: Omit<Partial<LifecycleLedgerEntry>, "identity" | "requestHash" | "state" | "ts">): Promise<LifecycleLedgerEntry>;
     assertSupportedStateVersions(): Promise<void>;
@@ -152,3 +171,4 @@ export declare class LifecycleLedger {
     listUncertainCreatesBySessionId(sessionId: string, effectMarker?: string, remoteCreateKey?: string): LifecycleLedgerEntry[];
     findPendingCleanupByTarget(sessionId: string, cwd: string, transcriptPath: string): LifecycleLedgerEntry | undefined;
 }
+export {};

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

@@ -1,5 +1,6 @@
 import { type ChildProcess } from "node:child_process";
 import { type GjcLaunchWorktreePlan } from "../../gjc-runtime/launch-worktree";
+import type { SessionWorkLease } from "../../session/session-work-lease";
 import type { SessionLifecycleMcpServer } from "../acp/mcp";
 import { type SdkStartupFailure, type SdkStartupRollbackResult } from "../startup-capability";
 import type { Broker, BrokerCleanupEvidence, BrokerResponse } from "./broker";
@@ -8,8 +9,11 @@ import { type ProcessIncarnationCommandRunner, type ProcessIncarnationOptions, p
 import { type SdkInternalSpawnCommand } from "./runtime";
 import { type IndexedSession } from "./session-index";
 export { type ProcessIncarnationCommandRunner, type ProcessIncarnationOptions, parseDarwinProcessIncarnation, processIncarnation, };
+/** Remove lifecycle stderr artifacts abandoned by a broker or detached host crash. */
+export declare function reapOrphanedChildStderrLogs(agentDir: string, limit?: number): Promise<number>;
+export declare function lifecycleFailureMessage(message: string, child?: ChildProcess): string;
 export declare function terminalUncertainStartupMessage(response: BrokerResponse): string;
-export declare function waitForChildSpawn(spawned: Pick<ChildProcess, "off" | "on" | "once">, onPostSpawnError?: (error: Error) => void): Promise<void>;
+export declare function waitForChildSpawn(spawned: Pick<ChildProcess, "off" | "on" | "once" | "pid">, onPostSpawnError?: (error: Error) => void): Promise<void>;
 export interface LifecycleDeadlines {
     receivedAt: number;
     requestedReadinessTimeoutMs: number;
@@ -245,8 +249,9 @@ export interface LifecycleExecutionOutcome {
 /** Returns the response together with every durable lifecycle fact needed for truthful replay. */
 export declare function executeLifecycle(broker: Broker, operation: string, input: Input, identity: string, cleanup?: CleanupEvidence): Promise<LifecycleExecutionOutcome>;
 /**
- * The live client/socket subscription count of the SDK session endpoint this
- * process serves, or `undefined` while this process serves no endpoint.
+ * The live SDK demand count of the session endpoint this process serves, or
+ * `undefined` while this process serves no endpoint. Observer-only sockets are
+ * excluded by {@link SessionHostRuntimeEvidence.observerClients}.
  *
  * Only the SDK session runtime owns the real socket table, so it publishes a
  * reader here instead of every consumer re-deriving attachment from the OS.
@@ -257,8 +262,10 @@ export type SessionHostAttachmentReader = () => number;
 export interface SessionHostRuntimeEvidence {
     /** This runtime's own live SDK client/socket subscription count. */
     attachedClients: SessionHostAttachmentReader;
-    /** Whether this runtime currently has agent work in flight. */
-    workInFlight: () => boolean;
+    /** Optional subset of attached sockets that only observes the host. */
+    observerClients?: SessionHostAttachmentReader;
+    /** One authoritative lease held by every admitted or continuing work state. */
+    workLease: SessionWorkLease;
 }
 /** One runtime's live publication, retractable only by its owner. */
 export interface SessionHostRuntimePublication {
@@ -275,19 +282,19 @@ export interface SessionHostRuntimePublication {
  */
 export declare function publishSessionHostRuntimeEvidence(evidence: SessionHostRuntimeEvidence): SessionHostRuntimePublication;
 /**
- * This process's currently attached SDK client count, summed across every
+ * This process's currently demanding SDK client count, summed across every
  * serving runtime, or `undefined` when no runtime publishes a readable count
  * (before startup, after teardown, or when every reader itself fails). Never
  * guesses: absence of a reader is absence of evidence.
  */
 export declare function sessionHostAttachedClients(): number | undefined;
 /**
- * Whether any runtime in this process has agent work in flight right now.
+ * Whether any runtime in this process still holds its authoritative work lease.
  *
  * Positive evidence only: a runtime that publishes nothing, or whose reader
  * fails, reports no work, so this can never keep an abandoned host alive.
  */
-export declare function sessionHostWorkInFlight(): boolean;
+export declare function sessionHostWorkLeaseActive(): boolean;
 /**
  * How often a live broker re-checks its own session registrations against OS
  * process liveness.

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

@@ -1,4 +1,4 @@
-export type SdkInternalAction = "broker-internal" | "session-host-internal";
+export type SdkInternalAction = "broker-internal" | "session-host-internal" | "stderr-drain-internal";
 export type SdkInternalSpawnCommand = {
     kind: "bun-source";
     file: string;