@gajae-code/coding-agent 0.17.2 → 0.17.5

package/dist/types/main.d.ts

@@ -5,6 +5,7 @@
  * createAgentSession() options. The SDK does the heavy lifting.
  */
 import type { ImageContent } from "@gajae-code/ai/core";
+import { postmortem } from "@gajae-code/utils";
 import type { Args } from "./cli/args";
 import { ModelRegistry } from "./config/model-registry";
 import { Settings } from "./config/settings";
@@ -17,6 +18,8 @@ import { initTheme } from "./modes/theme/theme";
 import type { SubmittedUserInput } from "./modes/types";
 import type { MCPManager } from "./runtime-mcp";
 import { type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSession, discoverAuthStorage } from "./sdk";
+import { processIncarnation } from "./sdk/broker/process-incarnation";
+import { SessionIndex } from "./sdk/broker/session-index";
 import type { AgentSession } from "./session/agent-session";
 import { type ResumeSessionIdentity, type SessionDestination, type SessionDirectoryMigrationPolicy, type SessionInfo, SessionManager, type StrictSessionOpenResult } from "./session/session-manager";
 import { resolveStartupAuthConfig } from "./session/startup-auth-config";
@@ -55,7 +58,7 @@ type StartupModelProfileArgs = {
     session: AgentSession;
     settings: Settings;
     modelRegistry: ModelRegistry;
-    parsedArgs: Pick<Args, "default" | "model" | "mpreset" | "thinking">;
+    parsedArgs: Pick<Args, "continue" | "default" | "fork" | "model" | "mpreset" | "resume" | "thinking">;
     startupModel?: CreateAgentSessionOptions["model"];
     startupThinkingLevel?: CreateAgentSessionOptions["thinkingLevel"];
     preferCachedModels?: boolean;
@@ -117,6 +120,7 @@ export declare class SessionNotFoundError extends Error {
     get sessionId(): string;
 }
 export declare function operatorFacingSessionOpenMessage(value: unknown): string | undefined;
+export declare function shouldNotifyModelFallback(authBootstrap: boolean | undefined, isInteractive: boolean): boolean;
 export declare function runInteractiveMode(session: AgentSession, version: string, changelogMarkdown: string | undefined, notifs: (InteractiveModeNotify | null)[], startupUpdate: StartupUpdateOrchestrator, initialMessages: string[], setExtensionUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void, lspServers: LspStartupServerInfo[] | undefined, mcpManager: MCPManager | undefined, eventBus?: EventBus, initialMessage?: string, initialImages?: ImageContent[], createInteractiveMode?: CreateInteractiveMode, resumeAction?: "continue-tail" | "open-idle", startDeferredMcpConfig?: CreateAgentSessionResult["startDeferredMcpConfig"], startDeferredModelProfiles?: DeferredModelProfileStartup, options?: {
     stopAfterFirstPaint?: boolean;
 }): Promise<void>;
@@ -153,6 +157,24 @@ export interface RunRootCommandDependencies {
     initializeSettings?: typeof Settings.init;
     loadSettingsForScope?: typeof Settings.loadForScope;
 }
+type DirectSessionManager = Pick<SessionManager, "getCwd" | "getSessionFile" | "getSessionId">;
+/**
+ * Direct CLI liveness is meaningful only for sessions with a durable transcript.
+ * An in-memory manager has no artifacts for GC to fence and must not touch the
+ * shared SDK session-index lock.
+ */
+export declare function directSessionRegistrationId(sessionManager: DirectSessionManager | undefined, lifecycleRequestId: string | undefined): string | undefined;
+interface DirectSessionRegistrationDependencies {
+    createIndex?: (agentDir: string) => SessionIndex;
+    processIncarnation?: typeof processIncarnation;
+    registerPostmortem?: typeof postmortem.register;
+    masterRole?: {
+        ownerSessionId: string;
+        attestationEpoch: string;
+    };
+}
+/** Register a durable direct CLI session while leaving ephemeral sessions lock-free. */
+export declare function registerDirectSession(sessionManager: DirectSessionManager | undefined, agentDir: string, lifecycleRequestId: string | undefined, dependencies?: DirectSessionRegistrationDependencies): Promise<void>;
 export interface ModelRoleOverrides {
     smol?: string;
     slow?: string;

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

@@ -1,6 +1,6 @@
 import { type Agent, type AgentSideConnection, type AuthenticateRequest, type AuthenticateResponse, type AvailableCommand, type CancelNotification, 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, AcpSdkAdapterError } from "../../sdk/acp";
-import type { SdkPromptTerminalOutcome } from "../../sdk/prompt-status";
+import type { SdkPromptFailureCategory, SdkPromptFailurePhase, SdkPromptTerminalOutcome } from "../../sdk/prompt-status";
 import { type PromptWatchdogClock } from "../../sdk/prompt-watchdog";
 import type { AcpStartupOptions } from "./startup-options";
 /**
@@ -58,6 +58,60 @@ export declare class AcpPromptFailureError extends AcpSdkAdapterError {
     readonly failure: SdkPromptFailedOutcome;
     constructor(failure: SdkPromptFailedOutcome);
 }
+/**
+ * The wire projection of a prompt terminal's classification (issue #5615).
+ *
+ * `super(failure.code, failure.message)` above narrows the error to the generic
+ * `prompt_failed` plus its fixed redacted message, so the classification the
+ * terminal already computed used to die at the JSON-RPC boundary: an ACP client
+ * saw only `-32603 {code, details}` and could not tell a transient provider blip
+ * from a dead session without parsing English. These fields carry it across.
+ *
+ * `providerCode` is re-checked against the safe-token rule rather than trusted:
+ * `terminalOutcome` accepts the host's `providerCode` on a `typeof` check alone,
+ * and this is the first path that puts it on the wire, so an unbounded value is
+ * dropped instead of becoming a leak of provider text (the redaction contract in
+ * `sanitizePromptFailure`). A dropped or absent code is omitted, never nulled.
+ */
+export declare const OPERATOR_UPSTREAM_LABEL = "Upstream provider failure";
+export declare const OPERATOR_UPSTREAM_SUFFIX = ": the model provider ended this turn.";
+/**
+ * `post_start` proves execution began, so tools may already have run and had effects before the
+ * provider died. The wording therefore qualifies the turn rather than absolving the task: saying
+ * the task was unaffected would assert something the bounded classifiers do not establish.
+ */
+export declare const OPERATOR_PARTIAL_WORK_NOTE = " Work this turn had already performed may have taken effect; check before retrying.";
+/**
+ * Operator-facing wording for a post-start terminal, assembled ONLY from bounded safe tokens: the
+ * classifier `phase`, the `category`, and a `providerCode` that passes `isSafePromptFailureCode`.
+ * Raw provider text never reaches this function and must never reach it.
+ *
+ * Gated on BOTH `phase === "post_start"` and `category === "provider_transport"`. A submission-phase
+ * provider failure is rejected by the phase gate: nothing executed, so wording about a turn the
+ * provider ended would describe an event that never occurred.
+ *
+ * It claims only what those tokens prove — that the upstream provider ended the turn — and says
+ * nothing about whether the operator's work survived. `post_start` proves execution began, so the
+ * wording qualifies that earlier work may already have taken effect instead of absolving the task.
+ *
+ * This is additive. The wire `code`/`details` pair and every `PROMPT_FAILURE_MESSAGE_*` constant
+ * stay exactly as they are — pinned ACP core-v1 conformance asserts on them — so this wording
+ * travels alongside the redacted message instead of repurposing it.
+ *
+ * It says NOTHING about the worktree, deliberately. Nothing on this path inspects the worktree, so
+ * any sentence about uncommitted work would assert a check that never ran — reporting an
+ * uninspected tree as clean is the absence-of-evidence-as-evidence-of-absence error, and an
+ * operator who believed it would sweep work away. Silence is the only honest option until something
+ * actually looks.
+ *
+ * Returns `undefined` for every other category: `phase` and `category` are already on the wire, so
+ * restating them in prose tells an operator nothing they do not already have.
+ */
+export declare function postStartOperatorMessage(input: {
+    phase: SdkPromptFailurePhase;
+    category: SdkPromptFailureCategory;
+    providerCode?: string;
+}): string | undefined;
 /**
  * What an ACP `plan` update said the turn intended to do. Structural rather than the SDK's
  * `PlanEntry` so only the fields this evidence reads are depended on.

package/dist/types/modes/acp/startup-provenance.d.ts

@@ -0,0 +1,16 @@
+type JsonObject = Record<string, unknown>;
+export type PrimaryControlSurface = "cli" | "sdk";
+/**
+ * Startup-control provenance is the authority record ACP needs before it may take
+ * permission, provider, and lifecycle ownership of a session. Hosts serving that
+ * record report capabilities carrying `promptTerminalOutcomeVersion`
+ * and `primaryControlSurface`; a host that predates the record reports neither, and a
+ * host that cannot answer at all reports nothing. Those are three different operator
+ * problems, so they get three different messages instead of one "restart the session".
+ */
+export declare function resolveStartupProvenance(input: {
+    sessionId: string;
+    capabilities: JsonObject | undefined;
+    queryFailure: unknown;
+}): PrimaryControlSurface;
+export {};

package/dist/types/modes/components/custom-provider-wizard.d.ts

@@ -2,10 +2,28 @@ import { Container } from "@gajae-code/tui";
 import type { ProviderSetupInput } from "../../setup/provider-onboarding";
 export type CustomProviderCredentialSource = "env" | "literal";
 export type CustomProviderWizardSubmit = ProviderSetupInput;
+export interface CustomProviderWizardDiscoveryDeps {
+    discoverModels?: (input: {
+        baseUrl: string;
+        apiKeyEnv?: string;
+        apiKey?: string;
+        signal?: AbortSignal;
+    }) => Promise<{
+        models: string[];
+    }>;
+}
 export declare class CustomProviderWizardComponent extends Container {
     #private;
-    constructor(onSubmit: (input: CustomProviderWizardSubmit) => void, onCancel: () => void, onRender?: () => void);
+    constructor(onSubmit: (input: CustomProviderWizardSubmit) => void, onCancel: () => void, onRender?: () => void, discoveryDeps?: CustomProviderWizardDiscoveryDeps);
     setSubmitError(error: string): void;
     handleInput(keyData: string): void;
     complete(): void;
+    /** Generation token for the latest submit attempt. */
+    currentSubmitGeneration(): number;
+    /**
+     * Whether a submit attempt is still current: same generation and not
+     * dismissed. Revision or cancel invalidates pending completions so a
+     * stale refresh cannot report success or rerender over new inputs.
+     */
+    isSubmitCurrent(generation: number): boolean;
 }

package/dist/types/modes/components/session-selector.d.ts

@@ -19,14 +19,16 @@ declare class SessionList implements Component {
     onCancel?: () => void;
     onExit: () => void;
     onDeleteRequest?: (session: SessionInfo) => void;
+    onToggleStarRequest?: (session: SessionInfo) => void;
     constructor(allSessions: SessionInfo[], showCwd?: boolean);
     setInputFrozen(frozen: boolean): void;
     removeSession(sessionPath: string): void;
+    setSessionStarred(sessionPath: string, starred: boolean): void;
     invalidate(): void;
     render(width: number): string[];
     handleInput(keyData: string): void;
 }
-/** A one-shot resume consent selector. It never opens or mutates sessions. */
+/** A one-shot resume consent selector with host-owned deletion and star persistence. */
 export declare class SessionSelectorComponent extends Container {
     #private;
     private readonly onSelect;
@@ -35,7 +37,8 @@ export declare class SessionSelectorComponent extends Container {
     private readonly onDelete?;
     private readonly inspector?;
     private readonly onSelection?;
-    constructor(sessions: SessionInfo[], onSelect: (sessionPath: string) => void | Promise<void>, onCancel: () => void, onExit: () => void, onDelete?: ((session: SessionInfo) => Promise<boolean>) | undefined, inspector?: SessionInspector | undefined, onSelection?: ((selection: SessionSelectionResult) => void) | undefined);
+    private readonly onSetStarred?;
+    constructor(sessions: SessionInfo[], onSelect: (sessionPath: string) => void | Promise<void>, onCancel: () => void, onExit: () => void, onDelete?: ((session: SessionInfo) => Promise<boolean>) | undefined, inspector?: SessionInspector | undefined, onSelection?: ((selection: SessionSelectionResult) => void) | undefined, onSetStarred?: ((session: SessionInfo, starred: boolean) => Promise<void>) | undefined);
     setOnRequestRender(callback: () => void): void;
     handleInput(keyData: string): void;
     getSessionList(): SessionList;

package/dist/types/modes/components/user-message-selector.d.ts

@@ -13,16 +13,19 @@ declare class UserMessageList implements Component {
     onSelect?: (entryId: string) => void;
     onCancel?: () => void;
     constructor(messages: UserMessageItem[]);
+    setAvailableRows(rows: number): void;
     invalidate(): void;
     render(width: number): string[];
     handleInput(keyData: string): void;
 }
 /**
- * Component that renders a user message selector for branching
+ * Component that renders a prompt selector for creating a new session
  */
 export declare class UserMessageSelectorComponent extends Container {
     #private;
-    constructor(messages: UserMessageItem[], onSelect: (entryId: string) => void, onCancel: () => void);
+    private readonly getViewportRows;
+    constructor(messages: UserMessageItem[], onSelect: (entryId: string) => void, onCancel: () => void, getViewportRows: () => number);
+    render(width: number): string[];
     getMessageList(): UserMessageList;
 }
 export {};

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

@@ -30,7 +30,7 @@ export declare class CommandController {
     handleDropCommand(): Promise<boolean>;
     handleForkCommand(): Promise<void>;
     handleMoveCommand(targetPath: string): Promise<void>;
-    handleRenameCommand(title: string): Promise<void>;
+    handleRenameCommand(title?: string): Promise<void>;
     handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
     handleCompactCommand(customInstructions?: string): Promise<CompactionOutcome>;

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/loader.d.ts

@@ -2,6 +2,7 @@ import type { LoadedCustomTool } from "../extensibility/custom-tools/types";
 import { AgentStorage } from "../session/agent-storage";
 import type { AuthStorage } from "../session/auth-storage";
 import { MCPManager } from "./manager";
+import { MCPToolCache } from "./tool-cache";
 /** Result from loading MCP tools */
 export interface MCPToolsLoadResult {
     /** MCP manager (for lifecycle management) */
@@ -37,6 +38,7 @@ export interface MCPToolsLoadOptions {
     /** Idle retention for shared MCP pool entries. */
     sharedPoolIdleMs?: number;
 }
+export declare function resolveMCPToolCache(storage?: AgentStorage | null, dbPath?: string): Promise<MCPToolCache | null>;
 /**
  * Discover and load MCP tools from .mcp.json files.
  *

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) */
@@ -83,10 +98,10 @@ export interface MCPManagerOptions {
     /** Restrict this instance to tools from an explicit MCP config. */
     toolsOnly?: boolean;
     /**
-     * Ceiling for the startup wait, in milliseconds. Only ACP lifecycle launches
-     * set this, so a slow ACP MCP handshake gets the readiness budget while every
-     * other consumer keeps the short default. Non-positive or non-finite values
-     * are ignored and the default applies.
+     * Ceiling for the startup wait, in milliseconds. ACP lifecycle launches and
+     * plugin MCP startup use bounded caller-owned budgets; other consumers keep
+     * the short default. Non-positive or non-finite values are ignored and the
+     * default applies.
      */
     maxStartupTimeoutMs?: number;
     /** Connection pool used for every physical MCP open/close. */
@@ -95,11 +110,37 @@ export interface MCPManagerOptions {
     sessionId?: string;
     /** Idle retention for shared pool entries. */
     sharedPoolIdleMs?: number;
+    /** Limit tool-cache reads and writes to this manager's conventional servers. */
+    toolCacheServerNames?: ReadonlySet<string>;
     /** Test seam for deterministic reconnect backoff scheduling. */
     sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
     /** 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.
  *
@@ -118,7 +159,10 @@ export declare class MCPManager {
     static setInstance(value: MCPManager | undefined): void;
     /** Reset the process-global instance. Test-only. */
     static resetForTests(): void;
+    /** Block config mutations and reloads while keeping existing servers reconnectable. */
+    freezeConnectionSet(): void;
     sealConnectionSet(): void;
+    isConnectionSetMutationBlocked(): boolean;
     isConnectionSetSealed(): boolean;
     constructor(cwd: string, toolCache?: MCPToolCache | null, options?: MCPManagerOptions);
     isToolsOnly(): boolean;
@@ -127,9 +171,11 @@ export declare class MCPManager {
      */
     setOnNotification(handler: (serverName: string, method: string, params: unknown) => void): void;
     /**
-     * Set a callback to fire when any server's tools change.
+     * Set a callback to receive a read-only catalog snapshot when server tools change.
      */
-    setOnToolsChanged(handler: (tools: CustomTool<TSchema, MCPToolDetails>[]) => void): void;
+    setOnToolsChanged(handler: (tools: readonly Readonly<CustomTool<TSchema, MCPToolDetails>>[]) => void): void;
+    /** Subscribe to readonly catalog snapshots without replacing the manager owner's callback. */
+    subscribeToToolsChanged(handler: (tools: readonly Readonly<CustomTool<TSchema, MCPToolDetails>>[]) => void): () => void;
     /**
      * Set a callback to fire when any server's resources change.
      */
@@ -164,6 +210,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>;
 }
 /**