@gajae-code/coding-agent 0.12.11 → 0.12.12

package/dist/types/sdk/bus/topic-registry.d.ts

@@ -1,21 +1,28 @@
 /**
  * Per-session forum-topic registry for the threaded session surface.
  *
- * Each GJC session owns one active Telegram forum topic in the paired private
- * DM. The topic is created via `createForumTopic`, reused while the session
- * remains active, and removed from the registry when the daemon deletes it on
- * shutdown. The registry also tracks whether the one-time identity header has
- * already been pinned, so it is sent exactly once per active topic, even across
- * reconnects.
+ * Each GJC session owns one active Telegram forum topic. Remote archive closes
+ * daemon-created topics without deleting their durable records; rotated
+ * successors move inactive records into retained history before creating a new
+ * active authority. The registry also tracks whether the one-time identity
+ * header has already been pinned.
  *
  * State is a plain serialisable map persisted beside the daemon state files;
  * topic creation is injected so this module is pure and unit-testable without a
  * live Bot API.
  */
 /** Persisted record for one session's topic. */
+export type TopicLifecycleState = "active" | "disconnect_grace" | "archive_pending" | "archive_exhausted" | "inactive" | "legacy_quarantined"
+/** Read-only input compatibility; normalized to archive_pending during load. */
+ | "delete_pending";
+/** Persisted record for one immutable session identity's topic. */
 export interface TopicRecord {
     /** Telegram forum topic id (message_thread_id). */
     topicId: string;
+    /** Whether Telegram created this topic for the daemon or it was explicitly adopted from a user. */
+    topicOrigin: "daemon_created" | "user_created";
+    /** Immutable UUID record identity; never derive authority from a title or PID. */
+    sessionUuid?: string;
     /** Whether the one-time identity header has been sent/pinned. */
     identitySent: boolean;
     /** Creation timestamp (ms epoch). */
@@ -40,10 +47,8 @@ export interface TopicRecord {
     authorityEpoch?: number;
     /** Immutable authority epoch held when this remote topic create began. */
     creationLeaseEpoch?: number;
-    /** An uncertain delete fences future creation and inbound routing. */
-    authorityState?: "active" | "delete_pending";
-    /** Provenance for topics created by the user and adopted by GJC. Missing means daemon-created. */
-    topicOrigin?: "user_created";
+    /** Durable non-destructive lifecycle state. */
+    authorityState?: TopicLifecycleState;
     /** Telegram chat and endpoint authority last proven to use this topic. */
     chatId?: string;
     /** Canonical endpoint tuple (URL + token) that currently holds the lease. */
@@ -54,17 +59,68 @@ export interface TopicRecord {
     endpointGeneration?: number;
     /** Monotonic authenticated endpoint handoffs; legacy bindings begin at zero. */
     endpointIncarnation?: number;
+    /** Shared-authority lease owner (installation UUID), heartbeat, and expiry. */
+    leaseOwner?: string;
+    leaseHeartbeatAt?: number;
+    leaseExpiresAt?: number;
+    /** Durable archive initiator; a live foreign owner cannot be displaced. */
+    archiveHostId?: string;
+    /** Authority epoch captured by the archive initiator when it published the fence. */
+    archiveLeaseEpoch?: number;
+    disconnectGraceExpiresAt?: number;
     /** True when persisted binding fields were present but malformed; recovery must fail closed. */
     bindingMalformed?: true;
 }
+/** Durable claim published before invoking createForumTopic. */
+export interface TopicCreateClaim {
+    sessionId: string;
+    hostId?: string;
+    leaseOwner?: string;
+    authorityEpoch: number;
+    createdAt: number;
+    binding?: TopicEndpointBinding;
+}
+export interface ArchiveJob {
+    sessionId: string;
+    topicId: string;
+    /** Number of archive calls that have returned an ambiguous outcome. */
+    attempt: number;
+    /** First ambiguous result; bounds retry lifetime. */
+    firstAttemptAt?: number;
+    /** Compatibility read for pre-journal snapshots; normalized to `attempt`. */
+    retryCount?: number;
+    backoffMs: number;
+    nextAttemptAt: number;
+    safeDiagnostic?: string;
+}
 /** Serialisable shape persisted to disk. */
 export interface TopicRegistryState {
+    /** Writer format. Missing is the quarantined legacy format; future versions fail closed. */
+    version?: 2;
+    /** Monotonically increasing snapshot generation used by shared CAS stores. */
+    registryGeneration?: number;
     /** sessionId -> record. */
     topics: Record<string, TopicRecord>;
-    /** Durable deletion epochs retained after a definite delete. */
+    /** Durable lifecycle epochs retained after an archive starts. */
     fences?: Record<string, number>;
     /** Closed transport endpoint leases; unchanged endpoint discovery remains fenced across restart. */
     closedEndpoints?: Record<string, TopicEndpointBinding>;
+    /** Persistent host identity used to distinguish concurrent installations. */
+    installationHostId?: string;
+    /** Bounded durable archive work; no topic record is physically deleted. */
+    archiveJobs?: Record<string, ArchiveJob>;
+    /** Durable create claims. A claim fences concurrent creators before remote I/O. */
+    createClaims?: Record<string, TopicCreateClaim>;
+    /** Retained inactive predecessors keyed by logical session id. */
+    retiredTopics?: Record<string, TopicRecord[]>;
+}
+/**
+ * Shared registry authority. Filesystem atomic rename is sufficient for a single
+ * installation, but it cannot serialize two hosts sharing a state volume.
+ */
+export interface TopicRegistryCasAuthority {
+    read(): Promise<TopicRegistryState | undefined>;
+    compareAndSet(expectedGeneration: number, next: TopicRegistryState): Promise<boolean>;
 }
 /** Authenticated runtime binding for a durable topic lease. */
 export interface TopicEndpointBinding {
@@ -83,7 +139,7 @@ export type TopicEndpointAuthority = {
     state: "ambiguous";
 };
 /** Conditional rollback token for a delete fence publication. */
-export interface TopicDeleteAuthoritySnapshot {
+export interface TopicArchiveAuthoritySnapshot {
     sessionId: string;
     topicId?: string;
     authorityEpoch?: number;
@@ -92,18 +148,12 @@ export interface TopicDeleteAuthoritySnapshot {
     /** Exact fenced record, retained to restore an in-memory tombstone after a failed clear publication. */
     record?: TopicRecord;
 }
+export declare function emptyTopicRegistryState(): TopicRegistryState;
 /**
- * Proof that a definite delete was settled in memory and still owes its durable
- * commit. Handed back only by a settlement that actually happened, so a refused
- * settlement structurally cannot be followed by a rollback.
+ * Reject snapshots written by a newer daemon. Missing versions are preserved as
+ * evidence but quarantined: legacy records must never route or mutate remotely.
  */
-export interface TopicSettledDelete {
-    sessionId: string;
-    topicId: string;
-    /** Authority epoch proven current when the record was removed. */
-    settledEpoch: number;
-}
-export declare function emptyTopicRegistryState(): TopicRegistryState;
+export declare function parseTopicRegistryState(value: unknown): TopicRegistryState | undefined;
 /**
  * In-memory registry over a serialisable state. Topic creation is injected via
  * `getOrCreateTopic`'s `create` callback (the daemon supplies a real
@@ -124,6 +174,14 @@ export declare class TopicRegistry {
     private readonly creatingBindings;
     /** Monotonic authority epochs, including deletion fences for absent records. */
     private readonly epochs;
+    /** Archive work is retained and retryable; records are never physically removed. */
+    private readonly archiveJobs;
+    /** Durable pre-create claims; remote creation is forbidden until published. */
+    private readonly createClaims;
+    /** Inactive predecessor evidence retained across successor generations. */
+    private readonly retiredTopics;
+    /** Generation of the last loaded/published snapshot. */
+    private registryGeneration;
     constructor(state?: TopicRegistryState);
     /** Replace all runtime state after a successfully persisted staged publication. */
     replace(state: TopicRegistryState): void;
@@ -134,10 +192,18 @@ export declare class TopicRegistry {
     sessionForTopic(topicId: string): string | undefined;
     /** All session ids with a persisted topic record. */
     sessionIds(): string[];
-    /** Persisted remote deletes that must be reconciled before recovery can proceed. */
-    deletePendingSessionIds(): string[];
     /** The existing topic record for a session, if any. */
     get(sessionId: string): TopicRecord | undefined;
+    /** Durable claims restored from disk require explicit authoritative reconciliation. */
+    pendingCreateClaims(): TopicCreateClaim[];
+    /**
+     * Resolve a durable pre-create claim only with authoritative topic evidence.
+     * An absent or malformed topic deliberately leaves the claim in place, fencing
+     * subsequent creators after a crash.
+     */
+    reconcileCreateClaim(sessionId: string, topic?: TopicRecord): boolean;
+    /** Clear a claim only when the local create attempt proved no remote topic was accepted. */
+    abandonCreateClaim(sessionId: string, authorityEpoch: number): boolean;
     /** Current immutable authority epoch for a creation lease. */
     authorityEpoch(sessionId: string): number;
     /** Whether this session has an active, unambiguous topic authority. */
@@ -160,6 +226,12 @@ export declare class TopicRegistry {
     uniqueSessionForEndpoint(binding: TopicEndpointBinding): string | undefined;
     /** Whether this exact session owns the complete durable endpoint binding. */
     matchesEndpoint(sessionId: string, binding: TopicEndpointBinding): boolean;
+    /**
+     * Retire a remotely settled inactive topic only when an authenticated
+     * successor proves a different endpoint authority. The inactive predecessor
+     * is serialized into retained history before the active slot is released.
+     */
+    retireInactiveEndpointForSuccessor(sessionId: string, binding: TopicEndpointBinding): boolean;
     /**
      * Rebind an existing topic to an authenticated successor endpoint. The exact
      * logical session id is proved by replay before this method is called. A
@@ -177,6 +249,17 @@ export declare class TopicRegistry {
     getOrCreateTopic(sessionId: string, create: () => Promise<unknown>, now?: () => number, name?: string, binding?: TopicEndpointBinding, commit?: () => Promise<void>, transientClaimant?: object, topicOrigin?: TopicRecord["topicOrigin"]): Promise<TopicRecord>;
     /** Mark the identity header as sent for a session. Idempotent. */
     markIdentitySent(sessionId: string): void;
+    /** Generation used as the compare value for a shared CAS publication. */
+    registryVersion(): number;
+    /** Advance only after a successful shared compare-and-set publication. */
+    markRegistryPublished(generation: number): void;
+    /**
+     * Acquire or renew a host lease. Another unexpired host is never displaced;
+     * a disconnected owner may resume the exact topic during its grace window.
+     */
+    acquireLease(sessionId: string, hostId: string, now: number, ttlMs: number, graceMs: number): boolean;
+    /** Record a disconnect without losing the topic identity needed for a grace resume. */
+    releaseLeaseToGrace(sessionId: string, hostId: string, now: number, graceMs: number): boolean;
     /** Whether the identity header still needs sending for this session. */
     needsIdentity(sessionId: string): boolean;
     /** Remember stable repo/branch identity independently of the displayed name. */
@@ -206,73 +289,35 @@ export declare class TopicRegistry {
     markUserNamePending(sessionId: string, name: string): boolean;
     /** Commit a successfully-applied daemon topic title. */
     markNameApplied(sessionId: string, name: string): void;
-    /** Capture only authority fields that a failed delete publication may restore. */
-    captureDeleteAuthority(sessionId: string): TopicDeleteAuthoritySnapshot;
-    /** Restore a failed delete fence only while its exact authority mutation remains current. */
-    restoreDeleteAuthority(snapshot: TopicDeleteAuthoritySnapshot): boolean;
-    /**
-     * Restore the exact delete fence after a failed compensation publication.
-     *
-     * Settlement rebuilds derived routes, which can make a surviving colliding
-     * record routable. Rebuild again on successful restoration so the reinstated
-     * fence re-quarantines the topic id instead of leaving inbound routing open to
-     * the collision partner despite the restored fence.
-     */
-    restoreDeleteFence(snapshot: TopicDeleteAuthoritySnapshot): boolean;
-    /** Fence new work before the remote delete starts, including an absent in-flight create. */
-    beginDelete(sessionId: string): TopicRecord | undefined;
+    /** Capture only authority fields that a failed archive-fence publication may restore. */
+    captureArchiveAuthority(sessionId: string): TopicArchiveAuthoritySnapshot;
+    /** Restore a failed archive fence only while its exact authority mutation remains current. */
+    restoreArchiveAuthority(snapshot: TopicArchiveAuthoritySnapshot): boolean;
+    /** Restore the exact archive fence after a failed compensation publication. */
+    restoreArchiveFence(snapshot: TopicArchiveAuthoritySnapshot): boolean;
+    /** Fence new work before the remote archive starts, including an absent in-flight create. */
+    beginArchive(sessionId: string, hostId?: string, now?: number): TopicRecord | undefined;
+    /** Verify the durable archive initiator immediately before remote dispatch. */
+    archiveAuthorityAllows(sessionId: string, hostId: string, pairedChatId: string, now: number): boolean;
+    /** @deprecated Production dispatch must provide the current paired chat id. */
+    archiveAuthorityAllows(sessionId: string, hostId: string, now: number): boolean;
     /** Retain an accepted create as deletion-fenced before remote compensation can begin. */
-    fenceAcceptedCreate(sessionId: string, topicId: string, now?: () => number, name?: string, binding?: TopicEndpointBinding): TopicRecord;
+    fenceAcceptedCreate(sessionId: string, topicId: string, now?: () => number, name?: string, binding?: TopicEndpointBinding, topicOrigin?: TopicRecord["topicOrigin"], archiveChatId?: string): TopicRecord;
     /** Fence an accepted create only when its exact creator lease still owns the record. */
-    fenceAcceptedCreateForLease(sessionId: string, topicId: string, creationLeaseEpoch: number, now?: () => number, name?: string, binding?: TopicEndpointBinding): TopicRecord | undefined;
+    fenceAcceptedCreateForLease(sessionId: string, topicId: string, creationLeaseEpoch: number, hostId: string, now?: () => number, name?: string, binding?: TopicEndpointBinding, topicOrigin?: TopicRecord["topicOrigin"], archiveChatId?: string): TopicRecord | undefined;
     /** Wait for a revoked create to settle before admitting a later lifecycle epoch. */
     awaitInflight(sessionId: string): Promise<void>;
     /**
-     * Phase 1 of settling a definite remote delete: remove the record while
-     * deliberately RETAINING its topic-id quarantine.
-     *
-     * `dispatchedAuthorityEpoch` is the authority epoch the caller held when it
-     * dispatched the remote delete. Settlement requires that epoch to still equal
-     * both the record's own authority epoch and the registry's current epoch for
-     * the session, so a held earlier delete can never settle a newer fence: if a
-     * scan or close-started delete re-fenced the same session/topic after this
-     * delete was dispatched, the stale definite result is refused and the newer
-     * `delete_pending` record plus its topic-id quarantine stay intact.
-     *
-     * An epoch outside the safe-integer range cannot identify a generation, and at
-     * `Number.MAX_SAFE_INTEGER` epoch advancement has saturated so distinct
-     * generations are no longer distinguishable. Both fail closed: settlement can
-     * no longer be proven fresh, so the fence is kept.
-     *
-     * Derived routing tables are deliberately NOT rebuilt here. Until the cleared
-     * snapshot is durably persisted the clear is not authoritative, so publishing
-     * routes now would make a colliding survivor routable (and the settled id
-     * adoptable) during the held write, and a failed persist would re-quarantine
-     * too late. Publish with {@link commitSettledDelete} once the persist
-     * succeeds, or undo with {@link rollbackSettledDelete} when it fails.
-     */
-    settleDelete(sessionId: string, topicId: string, dispatchedAuthorityEpoch: number): TopicSettledDelete | undefined;
-    /**
-     * Phase 2: publish derived routing tables once the cleared state is durable.
-     *
-     * Only here does the settled topic id lose its quarantine, so a surviving
-     * colliding record becomes routable and a settled id becomes adoptable without
-     * waiting for a daemon restart.
-     */
-    commitSettledDelete(settled: TopicSettledDelete): boolean;
-    /**
-     * Compare-and-swap undo for a settlement whose durable clear failed.
-     *
-     * Restoration applies only while the registry still holds exactly the state
-     * that this settlement produced: the settlement is still awaiting commit, the
-     * session still has no record, and the session epoch is still the settled
-     * epoch. Any mismatch means a newer generation intervened, so the restore is
-     * refused and the newer state is left untouched. A refused settlement produced
-     * no token, so it can never reach this path.
+     * Retain a topic record after a definite remote archive only while the exact
+     * dispatched authority epoch is still current.
      */
-    rollbackSettledDelete(settled: TopicSettledDelete): boolean;
-    /** Remove a topic record immediately for local/test cleanup compatibility. */
-    delete(sessionId: string): boolean;
+    settleArchive(sessionId: string, topicId: string, dispatchedAuthorityEpoch: number): boolean;
+    /** Durable archive jobs that are eligible for a retry at `now`. */
+    archivePendingSessionIds(now?: number): string[];
+    /** Durable/manual recovery candidates that exceeded the automatic archive retry budget. */
+    archiveExhaustedSessionIds(): string[];
+    /** Persist an indefinitely discoverable retry after an ambiguous archive result. */
+    scheduleArchiveRetry(sessionId: string, now: number, diagnostic?: string): ArchiveJob | undefined;
     /** Serialise active records plus unpublished staged creates for atomic commit. */
     serialize(): TopicRegistryState;
 }

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

@@ -2,6 +2,35 @@ import { type EventFrame, SessionEventStream } from "./events";
 import { ReverseLeaseRuntime } from "./reverse-leases";
 import type { BrokerIndexWriter, HostEndpointAdapters, SdkFrame } from "./types";
 export type SdkRequestObserver = (kind: "control" | "query", connectionId: string, frame: SdkFrame) => void;
+/**
+ * When a session publishes its replayable readiness signal.
+ *
+ * `immediate` is the stock contract: `start()` publishes `session_ready` at
+ * once, so a chat daemon that attaches (or replays late) surfaces the session
+ * and creates its stock root. `deferred` prepares the session instead: the
+ * session id, endpoint, and broker registration become discoverable authority,
+ * but no readiness exists for any consumer to act on until `activate()` runs.
+ * That ordering is what lets an operator adopt an existing chat root before the
+ * daemon would otherwise have published one of its own.
+ */
+export type SessionReadinessMode = "immediate" | "deferred";
+/**
+ * Replayable signal that a deferred session is fully initialized and holding
+ * endpoint authority while its readiness stays withheld.
+ *
+ * It is deliberately not `session_ready`: a broker lifecycle wait can
+ * authenticate it as the child's semantic completion receipt, while every
+ * readiness consumer — chat daemons above all — keeps ignoring it and publishes
+ * no root until the session is explicitly activated.
+ */
+export declare const SESSION_PREPARED_EVENT = "session_prepared";
+/** Every terminal answer an activation attempt can produce. */
+export type SessionActivationOutcome = "activated" | "already" | "not_prepared" | "generation_changed" | "not_authorized" | "authority_unavailable";
+/** Proves that a prepared session may publish readiness at this exact generation. */
+export type SessionActivationGate = (input: {
+    sessionId: string;
+    generation: number;
+}) => boolean | Promise<boolean>;
 export interface SessionSdkHostOptions extends HostEndpointAdapters {
     control?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
     query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
@@ -16,6 +45,14 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
     onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
     /** Best-effort capabilities mirrored from the native transport for out-of-band consumers. */
     connectionCapabilities?: (connectionId: string) => ReadonlySet<string> | undefined;
+    /** Readiness publication mode; defaults to the stock immediate contract. */
+    readiness?: SessionReadinessMode;
+    /**
+     * Authorization for a deferred activation. It is consulted on every attempt
+     * that would publish readiness and never on an idempotent replay, and a gate
+     * that fails is never read as authorization.
+     */
+    activationGate?: SessionActivationGate;
 }
 /** SDK hosting is independent of notification configuration. Only root sessions host an endpoint. */
 export declare function shouldHostSdk(_settings: unknown, isTopLevel: boolean, env?: NodeJS.ProcessEnv): boolean;
@@ -27,6 +64,10 @@ export declare class SessionSdkHost {
     constructor(options: SessionSdkHostOptions);
     get started(): boolean;
     get generation(): number;
+    /** True while the session holds endpoint authority but has published no readiness. */
+    get prepared(): boolean;
+    /** True once readiness for the current generation has been published. */
+    get ready(): boolean;
     /** Current installed definitions for a live provider capability. */
     getProviderDefinitions(capability: string): unknown | undefined;
     /** Release reverse leases after the transport reports a WebSocket disconnect. */
@@ -34,6 +75,17 @@ export declare class SessionSdkHost {
     /** Adds an event to the resumable event ring. Transport delivery is owned by bus wiring. */
     emitEvent(frame: SdkFrame): EventFrame;
     start(): Promise<"started" | "already">;
+    /**
+     * Publish the readiness signal a prepared session withheld.
+     *
+     * The attempt is refused unless the session is still started at exactly
+     * `expectedGeneration` (when supplied) and the activation gate authorizes it
+     * at that same generation. Authority is re-proved after the gate resolves,
+     * because a stop or an endpoint roll can land while it is in flight, and an
+     * exact retry after a successful activation is answered `already` instead of
+     * publishing a second readiness signal.
+     */
+    activate(expectedGeneration?: number): Promise<SessionActivationOutcome>;
     stop(): Promise<"stopped" | "already">;
     registerWithBroker(writer: BrokerIndexWriter): Promise<void>;
 }

package/dist/types/sdk/lifecycle-session.d.ts

@@ -18,6 +18,12 @@ export type CreateLifecycleAgentSessionOptions = CreateAgentSessionOptions & {
      * the manager's short default ceiling.
      */
     mcpStartupTimeoutMs?: number;
+    /**
+     * The broker-issued readiness intent from this session's launch request.
+     * `deferred` prepares the session: it holds endpoint authority and publishes
+     * a prepared signal instead of readiness until it is explicitly activated.
+     */
+    readiness?: "immediate" | "deferred";
 };
 /** Internal lifecycle-only session construction with an owner-bound SDK startup result. */
 export declare function createLifecycleAgentSession(options?: CreateLifecycleAgentSessionOptions): Promise<CreateLifecycleAgentSessionResult>;

package/dist/types/sdk/session-activation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The activation exchange a prepared session answers, and nothing else.
+ *
+ * A prepared session holds discoverable endpoint authority while its readiness
+ * stays withheld; activation is the one request that asks it to publish that
+ * readiness. Every caller shares this exchange whatever proved the endpoint
+ * authority beforehand: the `gjc notify activate-thread` CLI resolves it from
+ * the local session index, and the Coordinator resolves it from the broker's
+ * incarnation-bound binding.
+ *
+ * It lives outside `sdk/bus` on purpose. The existing-thread module reaches the
+ * chat-daemon and settings graph to prove a Slack binding, and the Coordinator
+ * MCP entrypoint may not reach that graph at all, so the exchange the machine
+ * entrypoint needs carries no notification, daemon, or settings dependency.
+ */
+export type SessionActivationErrorCode = "session_not_live" | "not_prepared" | "not_bound" | "activation_unavailable" | "activation_outcome_unknown";
+/** A fail-closed rejection while activating a prepared session. */
+export declare class SessionActivationError extends Error {
+    readonly code: SessionActivationErrorCode;
+    constructor(code: SessionActivationErrorCode, message: string);
+}
+/** Safe confirmation of an activation. It carries identifiers only. */
+export interface ActivatedPreparedSession {
+    sessionId: string;
+    endpointGeneration: number;
+    status: "activated" | "already";
+}
+/** The narrow transport surface activation needs from an SDK connection. */
+export interface PreparedSessionActivationClient {
+    request(frame: Record<string, unknown>): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}
+/**
+ * Ask one already-connected session to publish the readiness it withheld.
+ *
+ * The frame names the exact session and endpoint generation, and the answer is
+ * accepted only when it proves both, so a replacement session can never be
+ * activated in place of the requested one. Activation is idempotent: an exact
+ * retry answers `already` without a second readiness signal.
+ */
+export declare function requestPreparedSessionActivation(client: PreparedSessionActivationClient, sessionId: string, endpointGeneration: number): Promise<ActivatedPreparedSession>;

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

@@ -120,6 +120,16 @@ export interface CreateAgentSessionOptions {
     /** Load MCP tools for a top-level session only from this caller-owned absolute config file path.
      * Mutually exclusive with mcpManager. */
     mcpConfigPath?: string;
+    /**
+     * Defer connecting an exact MCP config until the interactive UI is ready.
+     * @internal CLI-only startup optimization; SDK callers retain synchronous loading by default.
+     */
+    deferMcpConfigStartup?: boolean;
+    /**
+     * Defer memory backend startup until the caller has applied startup model profiles.
+     * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
+     */
+    deferMemoryBackendStartup?: boolean;
     /** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
     enableLsp?: boolean;
     /** Skip Python kernel availability check and prelude warmup */
@@ -202,6 +212,10 @@ export interface CreateAgentSessionResult {
     setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
     /** MCP manager for server lifecycle management (undefined if MCP disabled or an exact tools-only config is session-owned) */
     mcpManager?: MCPManager;
+    /** Starts a deferred exact-config MCP connection. Present only when deferMcpConfigStartup was requested. */
+    startDeferredMcpConfig?: () => Promise<DeferredMcpConfigStartupResult>;
+    /** Starts a deferred memory backend. Present only when deferMemoryBackendStartup was requested. */
+    startDeferredMemoryBackend?: () => void;
     /** Warning if session was restored with a different model than saved */
     modelFallbackMessage?: string;
     /** LSP servers configured for lazy startup in interactive mode */
@@ -214,6 +228,10 @@ export interface CreateAgentSessionResult {
      */
     gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
 }
+export interface DeferredMcpConfigStartupResult {
+    loadedToolCount: number;
+    hasErrors: boolean;
+}
 export type { PromptTemplate } from "../config/prompt-templates";
 export { Settings, type SkillsSettings } from "../config/settings";
 export type { CustomCommand, CustomCommandFactory } from "../extensibility/custom-commands/types";

package/dist/types/sdk/startup-capability.d.ts

@@ -48,9 +48,16 @@ export declare function normalizeSdkStartupFailure(phase: SdkStartupPhase, reaso
 export declare class SdkStartupCapability {
     #private;
     readonly rollback?: SdkStartupRollbackTracker | undefined;
+    readonly readiness: "immediate" | "deferred";
     get cancelled(): boolean;
     cancel(): void;
-    constructor(rollback?: SdkStartupRollbackTracker | undefined);
+    /**
+     * The broker-issued, session-scoped readiness intent this child was launched
+     * with. It is carried on the capability rather than read from the ambient
+     * environment so bus wiring can never mistake an inherited process-global
+     * flag for a broker-managed preparation.
+     */
+    constructor(rollback?: SdkStartupRollbackTracker | undefined, readiness?: "immediate" | "deferred");
     normalizeFailure(phase: SdkStartupPhase, reason: SdkStartupReason, error?: unknown): SdkStartupFailure;
     get result(): SdkStartupResult | undefined;
     get promise(): Promise<SdkStartupResult>;

package/dist/types/session/agent-session.d.ts

@@ -262,6 +262,8 @@ export interface AgentSessionConfig {
     discoveryMode?: "off" | "mcp-only" | "all";
     /** MCP tool names to activate for the current session when discovery mode is enabled. */
     initialSelectedMCPToolNames?: string[];
+    /** Keep persisted MCP names until a deferred exact catalog becomes available. */
+    preserveUnavailableInitialMCPToolSelection?: boolean;
     /** Built-in discoverable tool names restored for the current all-discovery session. */
     initialSelectedDiscoveredBuiltinToolNames?: string[];
     /** Discoverable built-ins active for configured or explicit reasons independently of persisted discovery selection. */
@@ -307,6 +309,8 @@ export interface AgentSessionConfig {
      * process-global manager **MUST NOT** dispose it on their own teardown.
      */
     ownedMcpManager?: MCPManager;
+    /** Optional startup dependency that must settle before the first provider turn. */
+    startupTurnBarrier?: Promise<void>;
     /** Optional fork-context seed used to initialize a child session before its first prompt. */
     forkContextSeed?: ForkContextSeed;
     /** Optional provider state override. Fork-context children should omit this by default. */
@@ -558,6 +562,7 @@ export declare class AgentSession {
         nonEditDeterminations: number;
     };
     readonly rawSseDebugBuffer: RawSseDebugBuffer;
+    extendStartupTurnBarrier(barrier: Promise<void>): void;
     constructor(config: AgentSessionConfig);
     /**
      * Resolves when constructor-time workflow-gate tool restoration (ask
@@ -634,7 +639,9 @@ export declare class AgentSession {
      *  separately inside `sendCustomMessage`. */
     enqueueCustomMessageDisplay(text: string, mode: "steer" | "followUp"): string;
     getAgentId(): string | undefined;
+    get isDisposed(): boolean;
     registerToolSessionCleanup(cleanup: () => Promise<void> | void): () => void;
+    registerToolSessionTransitionCleanup(cleanup: () => Promise<void> | void): () => void;
     getAsyncJobSnapshot(options?: {
         recentLimit?: number;
     }): AsyncJobSnapshot | null;

package/dist/types/session/artifacts.d.ts

@@ -54,8 +54,8 @@ export declare class ArtifactManager {
      */
     removeNamedBestEffort(filename: string): Promise<boolean>;
     /**
-     * Atomically allocate next artifact ID.
-     * IDs are sequential within the session.
+     * Atomically claim the next artifact ID after this manager has been initialized.
+     * Prefer `allocatePath` or `save`; this synchronous seam exists for pruning callbacks.
      */
     allocateId(): number;
     /**

package/dist/types/session/session-manager.d.ts

@@ -615,6 +615,7 @@ interface SessionManagerStateSnapshot {
     needsFullRewriteOnNextPersist: boolean;
     fileEntries: FileEntry[];
     materializedFileEntries: FileEntry[];
+    adoptedArtifactManager: ArtifactManager | null;
 }
 /** Benchmark-derived cap for strong materialized session snapshots. */
 export declare const MATERIALIZED_CACHE_MAX_BYTES: number;
@@ -623,6 +624,7 @@ export declare const SessionManagerTestHooks: {
     materializedCacheMaxBytesOverride?: number;
     beforeResidentTransitionIndexBuild?: () => void;
     afterForkSnapshot?: () => void | Promise<void>;
+    beforeEphemeralArtifactManagerInstall?: (dir: string) => void | Promise<void>;
 };
 export declare class SessionManager {
     #private;
@@ -643,7 +645,9 @@ export declare class SessionManager {
     captureState(): SessionManagerStateSnapshot;
     restoreState(snapshot: SessionManagerStateSnapshot): void;
     /** Switch to a different session file (used for resume and branching). */
-    setSessionFile(sessionFile: string): Promise<void>;
+    setSessionFile(sessionFile: string, options?: {
+        deferEphemeralArtifactRetirement?: boolean;
+    }): Promise<void>;
     /** Start a new session. Closes any existing writer first. */
     newSession(options?: NewSessionOptions): Promise<string | undefined>;
     /**
@@ -751,13 +755,23 @@ export declare class SessionManager {
      * the parent session's artifact directory and ID counter.
      */
     adoptArtifactManager(manager: ArtifactManager): void;
+    /** Release only the matching externally adopted manager. */
+    releaseArtifactManager(manager: ArtifactManager): void;
+    /** Temporarily release adopted authority while an outer transition validates its successor. */
+    stageAdoptedArtifactManagerForTransition(): void;
+    /** Prove manager authority by exact object identity, never by pathname shape. */
+    isArtifactManagerAuthorized(manager: ArtifactManager): boolean;
     /**
      * Returns the ArtifactManager this session writes through. Lazily creates
      * one bound to the current session file unless an external manager was
-     * adopted via `adoptArtifactManager`. Returns null only for non-persistent
-     * sessions with no adopted manager.
+     * adopted via `adoptArtifactManager`. Falls back to the lazily created
+     * ephemeral filesystem store once a non-persistent session has saved an
+     * artifact, so `artifact://` stays resolvable. Returns null only when no
+     * store has been established yet.
      */
     getArtifactManager(): ArtifactManager | null;
+    /** Linearizably establish this session's persistent or ephemeral artifact manager. */
+    ensureArtifactManager(): Promise<ArtifactManager | null>;
     /**
      * Allocate a new artifact path and ID for the current session.
      * Returns an empty object when the session is not persisted.
@@ -768,14 +782,18 @@ export declare class SessionManager {
     }>;
     /**
      * Save artifact content under the current session and return artifact ID.
-     * Returns an artifact ID for all sessions (file-backed for persistent, in-memory fallback otherwise).
+     * Persistent sessions write into the session artifact directory; non-persistent
+     * sessions write into a lazily created temporary directory so the content is
+     * read back from the filesystem instead of being retained in memory.
      */
     saveArtifact(content: string, toolType: string): Promise<string | undefined>;
     /**
      * Resolve an artifact ID to an on-disk path for the current session.
-     * Returns null when missing or when the session is not persisted.
+     * Returns null when the artifact is missing.
      */
     getArtifactPath(id: string): Promise<string | null>;
+    /** Retire predecessor ephemeral artifacts after an outer logical transition commits. */
+    retireEphemeralArtifactsAfterTransition(): void;
     /**
      * Persist (or clear) the current editor draft so the next resume of this
      * session can restore it. Empty text deletes any stale draft. No-op when the

package/dist/types/tools/index.d.ts

@@ -219,6 +219,14 @@ export interface ToolSession {
     getAuthorizedArtifactsDirs?: () => readonly string[];
     /** Get the ArtifactManager backing this session (shared across parent + subagents). */
     getArtifactManager?: () => ArtifactManager | null;
+    /** Prove that an ArtifactManager belongs to this concrete session or its explicitly adopted parent tree. */
+    isArtifactManagerAuthorized?: (manager: ArtifactManager) => boolean;
+    /** Adopt a task-created fallback manager into the concrete session owner. */
+    adoptArtifactManager?: (manager: ArtifactManager) => void;
+    /** Linearizably establish the concrete session owner's canonical artifact manager. */
+    ensureArtifactManager?: () => Promise<ArtifactManager | null>;
+    /** Release a task-created fallback manager when its logical session ends. */
+    releaseArtifactManager?: (manager: ArtifactManager) => void;
     /** Register teardown work owned by the current logical session. */
     registerSessionCleanup?: (cleanup: () => Promise<void> | void) => () => void;
     /** Allocate a new artifact path and ID for session-scoped truncated output. */