@gajae-code/coding-agent 0.15.5 → 0.16.0

package/dist/types/sdk/host/session-runtime.d.ts

@@ -1,9 +1,27 @@
 import { type Settings } from "../../config/settings";
 import type { ExtensionAPI, ExtensionContext } from "../../extensibility/extensions";
+import { type MasterRoleAttestationV2, SessionIndex, type SessionLocatorV2 } from "../broker/session-index";
+import { type TurnResultContent } from "../turn-result";
 import { SessionSdkHost, type SessionSdkHostOptions } from "./host";
 import { type SessionSurface } from "./query";
 import { type SdkCapabilities, type SdkSurfacePolicy } from "./surface-policy";
 import type { BrokerIndexWriter, SdkFrame } from "./types";
+export type MasterCapabilityReplayState = Map<string, number>;
+export declare function verifyMasterCapabilityFrame(input: {
+    frame: {
+        nonce: unknown;
+        attestationEpoch: unknown;
+        capability: unknown;
+    };
+    expectedCapability: string | undefined;
+    expectedEpoch: string | undefined;
+    replay: MasterCapabilityReplayState;
+    now?: number;
+}): {
+    ok: boolean;
+    nonce: string;
+    attestationEpoch: string;
+};
 /** Transport-neutral endpoint contract consumed by the SDK session runtime. */
 export interface SessionSdkTransport {
     readonly sessionId: string;
@@ -26,6 +44,8 @@ export interface SessionSdkRuntimeOptions extends Omit<SessionSdkHostOptions, "s
     settings?: Settings;
     /** Mutable shadow of patched config values merged into query readback. */
     configOverrides?: Map<string, unknown>;
+    /** Stable master lineage identity retained across session switches/branches. */
+    masterOwnerSessionId?: string;
 }
 export interface SdkOnlyInvocationRecord extends InvocationCorrelation {
     kind: InvocationKind | "terminal" | "steer";
@@ -160,6 +180,8 @@ export interface CreateSdkSessionRuntimeOptions {
     agentDir: string;
     /** Lifecycle-owned sessions require broker publication before they become usable. */
     brokerRegistrationRequired?: boolean;
+    /** Trusted broker-issued lifecycle marker bound to lifecycle host index events. */
+    lifecycleRequestId?: string;
     createTransport(input: {
         sessionId: string;
         stateRoot: string;
@@ -171,6 +193,12 @@ export interface CreateSdkSessionRuntimeOptions {
     onSdkRequest?: SessionSdkHostOptions["onRequest"];
     /** Mutable shadow of patched config values merged into query readback. */
     configOverrides?: Map<string, unknown>;
+    /** In-memory master capability for private broker verification only. */
+    masterCapability?: string;
+    /** Opaque direct-role epoch this effective host may adopt. */
+    masterAttestationEpoch?: string;
+    /** Stable master lineage identity retained across session switches/branches. */
+    masterOwnerSessionId?: string;
     /** Private session-owned terminal-abort capabilities; never exposed on ExtensionContext. */
     terminalAbortSeams?: SdkOnlyTerminalAbortSeams;
     /** Callback when a frame is admitted to the runtime (test harness). */
@@ -194,9 +222,18 @@ export interface InvocationReconciliation {
     noteAccepted(kind: InvocationKind, correlation: InvocationCorrelation, clientRef?: string): Promise<void>;
     noteTransition(kind: InvocationKind, correlation: InvocationCorrelation | undefined, frame: {
         type: "agent_start" | "agent_end";
+        content?: TurnResultContent;
+        hasActivity?: boolean;
+        outcome?: {
+            kind: "stopped";
+            reason: "cancelled";
+            provenance: "client_cancel";
+        };
     } | {
         type: "agent_failed";
         error: unknown;
+        content?: TurnResultContent;
+        hasActivity?: boolean;
     }): Promise<void>;
     lookup(kind: InvocationKind, selector: {
         commandId?: string;
@@ -228,7 +265,11 @@ export interface InvocationReconciliation {
     }, arg4?: (() => boolean) | {
         code: string;
         message: string;
-    }, arg5?: unknown): Promise<void>;
+    }, arg5?: unknown, arg6?: {
+        content?: TurnResultContent;
+        hasActivity?: boolean;
+        outcomeKind?: string;
+    }): Promise<void>;
     markUncertain(kind: InvocationKind, correlation: InvocationCorrelation, isCurrent?: () => boolean, deadlineMaxAt?: number): Promise<void>;
 }
 export declare function createInvocationReconciliation(options?: {
@@ -279,6 +320,31 @@ export declare function createSdkSurfaceFactory(options: SdkSurfaceFactoryOption
 }): SdkSurfaceFactory;
 /** Register the default-session notification command without loading notification adapters. */
 export declare function registerSdkOnlyNotificationCommand(api: ExtensionAPI): void;
+export declare function masterAttestationForEffectiveHost(input: {
+    masterCapability: string | undefined;
+    attestationEpoch: string | undefined;
+    ownerSessionId?: string;
+    sessionId: string;
+    pid: number;
+    processIncarnation: string | undefined;
+    direct: MasterRoleAttestationV2 | undefined;
+}): MasterRoleAttestationV2 | undefined;
+/**
+ * Establish direct master authority for the session currently hosted by this
+ * process. Session identity transitions retain the master capability and epoch
+ * but require a new direct attestation before their effective endpoint can
+ * adopt that authority.
+ */
+export declare function reattestMasterSessionIdentity(input: {
+    index: SessionIndex;
+    locator: SessionLocatorV2;
+    masterCapability: string | undefined;
+    attestationEpoch: string | undefined;
+    ownerSessionId?: string;
+    sessionId: string;
+    pid: number;
+    processIncarnation: string | undefined;
+}): Promise<MasterRoleAttestationV2 | undefined>;
 /** Install a complete SDK host for a session when notifications are inactive. */
 export declare function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: CreateSdkSessionRuntimeOptions): void;
 export {};

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

@@ -6,3 +6,9 @@ export declare class AgentDirSessionLifecycleClient implements SessionLifecycleC
     global(operation: SessionLifecycleOperation, input: Record<string, unknown>, options: SessionLifecycleClientRequestOptions): Promise<unknown>;
 }
 export declare function createBrokerSessionLifecycleService(agentDir: string): SessionLifecycleService;
+/**
+ * Dedicated dispatch for the local master `session.spawn` surface. It shares
+ * the lifecycle client's credential boundary but bypasses the generic mutation
+ * outcome types: spawn responses are validated by the caller's allowlist.
+ */
+export declare function dispatchSpawnGlobal(agentDir: string, input: Record<string, unknown>, idempotencyKey: string, timeoutMs: number): Promise<unknown>;

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

@@ -1,3 +1,4 @@
+import { type ScopeRequestV1, type SdkSearchResultV1 } from "../broker/session-scope";
 export type SessionLifecycleOperation = "session.create" | "session.fork" | "session.resume" | "session.close" | "session.delete" | "session.reconcile_uncertain" | "session.list";
 export interface SessionLifecycleActor {
     readonly id: string;
@@ -104,6 +105,9 @@ export interface SessionDeleteTarget {
 export interface SessionListTarget {
     readonly cwd?: string;
     readonly resolveSessionId?: string;
+    readonly scope?: ScopeRequestV1;
+    readonly limit?: number;
+    readonly cursor?: string;
 }
 interface SessionLifecycleMutationRequestBase<TOperation extends Exclude<SessionLifecycleOperation, "session.list">, TTarget> {
     readonly operation: TOperation;
@@ -141,7 +145,12 @@ export interface SessionLifecycleListEntry {
     readonly live?: boolean;
     readonly endpointGeneration?: number;
     readonly terminalUncertain?: boolean;
-    readonly repo?: string;
+    readonly cwd?: string;
+    readonly locator?: {
+        readonly cwd: string;
+        readonly worktreeRoot: string | null;
+        readonly stateRoot: string;
+    };
 }
 export interface SessionLifecycleListResult {
     readonly indexSeq: number;
@@ -149,6 +158,7 @@ export interface SessionLifecycleListResult {
     readonly warnings: readonly string[];
     readonly savedSession?: SessionLifecycleSavedSession;
 }
+export type SessionScopedListResult = SdkSearchResultV1;
 export interface SessionCreateResult {
     readonly ok: true;
     readonly operation: "session.create";
@@ -182,7 +192,7 @@ export interface SessionReconcileUncertainResult {
 export interface SessionListSuccessResult {
     readonly ok: true;
     readonly operation: "session.list";
-    readonly result: SessionLifecycleListResult;
+    readonly result: SessionLifecycleListResult | SessionScopedListResult;
 }
 export interface SessionLifecycleError {
     readonly code: string;
@@ -229,6 +239,7 @@ export type SessionListFailure = {
     readonly operation: "session.list";
     readonly certainty: SessionLifecycleCertainty;
     readonly error: SessionLifecycleError;
+    readonly result?: SessionScopedListResult;
 };
 export type SessionCreateOutcome = SessionCreateResult | SessionCreateFailure;
 export type SessionForkOutcome = SessionForkResult | SessionForkFailure;
@@ -254,7 +265,8 @@ export declare function validateSessionLifecycleMutationRequest(request: unknown
 export declare class SessionLifecycleService {
     #private;
     constructor(client: SessionLifecycleClient);
-    execute(request: SessionLifecycleMutationRequest): Promise<SessionCreateOutcome | SessionForkOutcome | SessionResumeOutcome | SessionCloseOutcome | SessionDeleteOutcome | SessionReconcileUncertainOutcome>;
+    scopedList(scope: ScopeRequestV1, limit?: number, cursor?: string): Promise<SessionListOutcome>;
+    execute(request: SessionLifecycleMutationRequest, idempotencyKeyOverride?: string): Promise<SessionCreateOutcome | SessionForkOutcome | SessionResumeOutcome | SessionCloseOutcome | SessionDeleteOutcome | SessionReconcileUncertainOutcome>;
     executeWithIdempotencyKey(request: SessionLifecycleMutationRequest, idempotencyKey: string): Promise<SessionCreateOutcome | SessionForkOutcome | SessionResumeOutcome | SessionCloseOutcome | SessionDeleteOutcome | SessionReconcileUncertainOutcome>;
     create(request: Omit<SessionCreateRequest, "operation">): Promise<SessionCreateOutcome>;
     fork(request: Omit<SessionForkRequest, "operation">): Promise<SessionForkOutcome>;

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

@@ -48,6 +48,8 @@ export type CreateLifecycleAgentSessionOptions = Omit<CreateAgentSessionOptions,
      * a prepared signal instead of readiness until it is explicitly activated.
      */
     readiness?: "immediate" | "deferred";
+    /** Broker-issued lifecycle request identity published with host registration. */
+    lifecycleRequestId?: string;
 };
 /** Internal lifecycle-only session construction with an owner-bound SDK startup result. */
 export declare function createLifecycleAgentSession(options?: CreateLifecycleAgentSessionOptions): Promise<CreateLifecycleAgentSessionResult>;

package/dist/types/sdk/prompt-deadline-manager.d.ts

@@ -1,5 +1,6 @@
 import type { KindAwareReconciliation } from "./bus/kind-aware-reconciliation";
 import type { InvocationCorrelation, InvocationReconciliation } from "./host/session-runtime";
+import type { TurnResultContent } from "./turn-result";
 type DeadlineReconciliation = InvocationReconciliation | KindAwareReconciliation;
 export type PromptDeadlineOutcome = {
     kind: "failed";
@@ -7,6 +8,15 @@ export type PromptDeadlineOutcome = {
     message: string;
     provenance: "deadline";
 };
+export interface PromptTerminalTransitionEvidence {
+    content?: TurnResultContent;
+    hasActivity?: boolean;
+    outcome?: {
+        kind: "stopped";
+        reason: "cancelled";
+        provenance: "client_cancel";
+    };
+}
 export declare class PromptDeadlineManager {
     #private;
     constructor(options: {
@@ -28,7 +38,7 @@ export declare class PromptDeadlineManager {
     noteTerminalTransition(correlation: InvocationCorrelation, pendingFailure?: {
         code: string;
         message: string;
-    }): void;
+    }, evidence?: PromptTerminalTransitionEvidence): void;
     clear(correlation: InvocationCorrelation): void;
     clearAll(): void;
     /** For tests: current deadline or undefined if no lease. */

package/dist/types/sdk/protocol/adapter-validation.d.ts

@@ -9,6 +9,8 @@ export type AdapterValidationError = {
     code: "invalid_reload_component" | "invalid_input";
     message: string;
 };
+/** Rejects instruction-bearing controls before correlation or provider work. */
+export declare function validateRequiredPromptText(operation: string, input: Input): AdapterValidationError | undefined;
 /** Validates controls that adapters must reject before forwarding them to a host. */
 export declare function validateAdapterControl(operation: string, input: Input): AdapterValidationError | undefined;
 export {};

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

@@ -1,6 +1,13 @@
 import { type SessionIndex } from "../broker/session-index";
 import { type SdkDispatchContext, type SdkDispatchHandler } from "../client/client";
 import { type ActivatedPreparedSession } from "../session-activation";
+export interface SessionEndpointIdentity {
+    readonly mtimeMs: number;
+    readonly mtimeNs: bigint;
+    readonly ctimeNs: bigint;
+    readonly size: bigint;
+    readonly ino: bigint;
+}
 /**
  * Exact identity of one attached SDK session endpoint. Providers persist it next to
  * their conversation state and re-prove it before every resume, so it must be derived
@@ -14,6 +21,8 @@ export declare function sessionAttachmentAuthorityId(input: {
     endpointMtimeMs: number | undefined;
     url: string;
     token: string;
+    /** Proven no-follow endpoint identity, when the caller has one. */
+    endpointIdentity?: SessionEndpointIdentity;
 }): string;
 /** The only capability a provider may retain for an attached SDK session. */
 export interface SessionAttachment {
@@ -155,6 +164,8 @@ export interface SessionRouterDeps {
 export type SessionRouterProviderDeps = Pick<SessionRouterDeps, "createClient" | "createIndex" | "createBrokerClient" | "setInterval" | "clearInterval" | "setTimeout" | "clearTimeout" | "onReconciled">;
 export interface SessionRouterOptions {
     agentDir: string;
+    /** Limits attachment to exact ids selected by a Broker-scoped operation. */
+    sessionIds?: readonly string[];
     deps?: SessionRouterDeps;
     /** Runtime-specific identity validation; Router supplies a conservative fallback. */
     correlateFrame?: SessionRouterFrameCorrelator;

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

@@ -7,6 +7,7 @@ import { ModelRegistry } from "../config/model-registry";
 import { type ScopedModelSelection } from "../config/model-resolver";
 import { type PromptTemplate } from "../config/prompt-templates";
 import { Settings, type SkillsSettings } from "../config/settings";
+import type { MasterModeContext } from "../master-mode/context";
 import type { BashRestrictionProfile } from "../tools/bash-allowed-prefixes";
 import "../discovery";
 import type { CustomCommandsLoadResult } from "../extensibility/custom-commands";
@@ -176,6 +177,8 @@ export interface CreateAgentSessionOptions {
      * @internal CLI-only startup optimization; SDK callers retain synchronous loading by default.
      */
     deferMcpConfigStartup?: boolean;
+    /** Process-local master authority. Never persist or pass to lifecycle children. */
+    masterModeContext?: MasterModeContext;
     /**
      * Defer memory backend startup until the caller has applied startup model profiles.
      * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
@@ -384,4 +387,17 @@ export declare function createPluginHooksExtension(hooks: ConstrainedPluginHook[
 export declare function resolveIntentTracingEnabled(intentTracingSetting: boolean | undefined, options: {
     subSession: boolean;
 }): boolean;
+/**
+ * Order candidates so each known provider's curated default model is tried
+ * before the rest of the catalog.
+ *
+ * Provider catalogs are not ranked by fitness — a withdrawn model whose ID
+ * carries an older date suffix sorts ahead of its current replacement — so
+ * picking the first credentialed entry can start an unconfigured install on a
+ * model the provider no longer serves. `DEFAULT_MODEL_PER_PROVIDER` is the
+ * curated table `findInitialModel` already sweeps for the same purpose;
+ * reusing it keeps both unconfigured paths on one source of truth. Candidates
+ * that are not a provider default keep their original relative order.
+ */
+export declare function orderByProviderDefaultFirst(candidates: readonly Model[], providerOrder?: readonly string[]): Model[];
 export declare function createAgentSession(options?: CreateAgentSessionOptions): Promise<CreateAgentSessionResult>;

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

@@ -49,6 +49,7 @@ export declare class SdkStartupCapability {
     #private;
     readonly rollback?: SdkStartupRollbackTracker | undefined;
     readonly readiness: "immediate" | "deferred";
+    readonly lifecycleRequestId?: string | undefined;
     get cancelled(): boolean;
     cancel(): void;
     /**
@@ -57,7 +58,7 @@ export declare class SdkStartupCapability {
      * environment so bus wiring can never mistake an inherited process-global
      * flag for a broker-managed preparation.
      */
-    constructor(rollback?: SdkStartupRollbackTracker | undefined, readiness?: "immediate" | "deferred");
+    constructor(rollback?: SdkStartupRollbackTracker | undefined, readiness?: "immediate" | "deferred", lifecycleRequestId?: string | undefined);
     normalizeFailure(phase: SdkStartupPhase, reason: SdkStartupReason, error?: unknown): SdkStartupFailure;
     get result(): SdkStartupResult | undefined;
     get promise(): Promise<SdkStartupResult>;

package/dist/types/session/account-inventory.d.ts

@@ -59,6 +59,7 @@ export interface AccountInventoryInput {
             provider: string;
         }>;
         getProviderBaseUrl?: (provider: string) => string | undefined;
+        getAuthStorageOwner?: () => object;
     };
     sessionId?: string;
     provider?: string;

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

@@ -109,6 +109,7 @@ import { type ConfiguredFallbackChain, type FallbackChainRuntimeState } from "./
 export { DefaultModelSelectionRecoveryError } from "./default-model-selection";
 import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome, ClientBridgePermissionToolCall } from "./client-bridge";
 import { type ContributionPrepOptions, type ContributionPrepResult } from "./contribution-prep";
+import { type FoldAdapter, FoldCoordinator } from "./fold-coordinator";
 import type { MemoryGuardRestoreResult } from "./memory-guard-checkpoint-participant";
 import { type CustomMessage } from "./messages";
 import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, PreparedNewSession, RecoveryHydrationContext, RecoveryHydrationPromotionFence, SessionContext, SessionManagerCloseOutcome, SessionMemoryStats } from "./session-manager";
@@ -426,8 +427,8 @@ export interface PromptOptions {
     }) => void;
     /** Optional invocation-scoped cancellation fence used before an accepted skill starts execution. */
     preflightSignal?: AbortSignal;
-    /** Internal SDK lifecycle owner token. */
-    sdkRunToken?: string;
+    /** Internal host capability; ordinary package callers cannot construct the branded value. */
+    sdkRunCapability?: unknown;
 }
 /** Result from a handoff operation. */
 export interface HandoffResult {
@@ -553,6 +554,14 @@ export type BeforeAgentStartContributor = (event: {
     images?: ImageContent[];
     sessionId: string | undefined;
 }) => Promise<BeforeAgentStartInternalMessage | undefined>;
+export type WorkerIntegrationOutcome = {
+    status: "completed";
+} | {
+    status: "failed";
+    error: string;
+} | {
+    status: "timed_out";
+};
 export declare class WorkerIntegrationRequestScheduler {
     #private;
     readonly request: (signal: AbortSignal) => Promise<void>;
@@ -560,6 +569,7 @@ export declare class WorkerIntegrationRequestScheduler {
     constructor(request: (signal: AbortSignal) => Promise<void>, timeoutMs?: number);
     enqueue(): void;
     flush(): Promise<void>;
+    flushWithOutcome(): Promise<WorkerIntegrationOutcome>;
 }
 export type StreamingEditParsedToolCall = {
     toolCall: ToolCall;
@@ -795,6 +805,11 @@ export declare class AgentSession {
      * proceeds.
      */
     awaitSessionSettlement(): Promise<void>;
+    queueCoordinatorRuntimeStatePersistForTests(event: AgentSessionEvent, gate: Promise<void>): Promise<void>;
+    parkAgentEndForCoordinatorPersistForTests(event: Extract<AgentSessionEvent, {
+        type: "agent_end";
+    }>): void;
+    flushParkedAgentEndForCoordinatorPersistForTests(): void;
     drainAsyncJobDeliveriesForAcp(options?: {
         timeoutMs?: number;
     }): Promise<boolean>;
@@ -837,7 +852,9 @@ export declare class AgentSession {
      * handler, so Ctrl+B-style folding fails closed instead of aborting or
      * shell-suspending arbitrary work.
      */
-    registerForegroundBashBackgroundRequestHandler(handler: () => void): () => void;
+    registerForegroundFoldParticipant(adapter: FoldAdapter): () => void;
+    /** The session-owned fold coordinator, for delivery-side receipt lookup. */
+    get foldCoordinator(): FoldCoordinator;
     /**
      * Returns whether a managed foreground bash call is currently backgroundable.
      * UI key handlers use this to avoid consuming normal editor shortcuts when
@@ -854,7 +871,7 @@ export declare class AgentSession {
      * Ask the active managed foreground bash call to return as a background job.
      * Returns false when no supported foreground tool is currently backgroundable.
      */
-    requestForegroundBashBackground(): boolean;
+    requestForegroundBashBackground(): Promise<boolean>;
     /**
      * Get all configured tool names (built-in via --tools or default, plus custom tools).
      */
@@ -947,7 +964,7 @@ export declare class AgentSession {
     /** Live SDK configuration values exposed through the session query surface. */
     getSdkConfigItems(): Record<string, string>;
     setPlanModeState(state: PlanModeState | undefined): void;
-    invokeSkill(name: string, args?: string, options?: Pick<PromptOptions, "onPreflightAccepted" | "onPreflightAcceptCommit" | "onSkillPrepared" | "preflightSignal" | "sdkRunToken">): Promise<{
+    invokeSkill(name: string, args?: string, options?: Pick<PromptOptions, "onPreflightAccepted" | "onPreflightAcceptCommit" | "onSkillPrepared" | "preflightSignal" | "sdkRunCapability">): Promise<{
         name: string;
         path: string;
         args?: string;
@@ -1002,7 +1019,7 @@ export declare class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;
-    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy" | "onPreflightAccepted" | "onPreflightAcceptCommit" | "preflightSignal" | "sdkRunToken">): Promise<void>;
+    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy" | "onPreflightAccepted" | "onPreflightAcceptCommit" | "preflightSignal" | "sdkRunCapability">): Promise<void>;
     /**
      * Queue a steering message to interrupt the agent mid-run.
      */
@@ -1062,7 +1079,7 @@ export declare class AgentSession {
             startsOwnRun: boolean;
         }) => void;
         preflightSignal?: AbortSignal;
-        sdkRunToken?: string;
+        sdkRunCapability?: unknown;
     }): Promise<void>;
     /**
      * Clear queued messages and return them.

package/dist/types/session/credential-store-errors.d.ts

@@ -0,0 +1 @@
+export declare const CREDENTIAL_STORE_UNREADABLE_MESSAGE = "Credential store is unreadable. Back up the database, then have an operator run PRAGMA integrity_check or REINDEX; no automatic repair was attempted.";

package/dist/types/session/fold-coordinator.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Session-owned fold/wake coordinator.
+ *
+ * Folding a running foreground wait is a lifecycle handoff across three
+ * independently scheduled domains — the tool observer, the job owner, and
+ * agent-turn admission — so it needs ONE linearization point. That is this
+ * coordinator: a synchronous prologue claims the fold and arms the steering
+ * fence with no `await` in between, and only then does an async tail capture and
+ * persist the receipt.
+ *
+ * Two invariants are load-bearing and easy to get wrong:
+ *
+ * 1. **Identity is the `AsyncJob` instance, acquired once.** Job ids and
+ *    generations are manager-local, so two managers can mint the same
+ *    `bg_1`/`job:1` pair. Slots are therefore keyed by the object itself,
+ *    obtained exactly once through the registration-bound
+ *    {@link FoldAdapter.getJob} and retained for the rest of the transaction.
+ *    Nothing in the fold path may consult an ambient, singleton, or
+ *    endpoint-resolved manager.
+ * 2. **A delivery callback can run more than once.** The async job manager
+ *    re-pushes the SAME delivery object on retry, so the receipt is attached to
+ *    a carrier keyed by that object BEFORE the slot is released. A retried
+ *    delivery therefore still carries its receipt and can never silently
+ *    degrade into an ordinary receipt-less completion.
+ */
+import type { AsyncJob } from "../async/job-manager";
+/**
+ * Idle-flush merge window.
+ *
+ * Completions that land within this window coalesce into ONE wake turn. The
+ * previous 1ms debounce meant staggered completions each bought their own full
+ * LLM turn. Deliberately a fixed internal constant, not a setting: the contract
+ * is one merge window, and a per-user knob would let wake behavior differ
+ * between sessions.
+ */
+export declare const FOLD_WAKE_MERGE_WINDOW_MS = 800;
+/** The wait kinds that can be folded. `task`/`subagent` awaits are a non-goal. */
+export type FoldWaitKind = "bash-managed" | "client-terminal" | "bash-pty";
+/** Outcome of settling the foreground caller. Exactly one party may settle it. */
+export type ForegroundSettleOutcome = "resolved" | "already-settled";
+/**
+ * How a folded job's output is retrieved later. Deliberately a structured
+ * handle over already-implemented paths rather than an invented URI scheme:
+ * there is no `job://` resolver, and inventing one would make the reference
+ * unresolvable in exactly the degraded case it exists for.
+ */
+export interface JobOutputRetrieval {
+    jobId: string;
+    generation: string;
+    /** Human/model-facing retrieval instruction naming a real mechanism. */
+    instruction: string;
+}
+/** Durable record captured at fold time and replayed into the wake turn. */
+export interface FoldReceipt {
+    jobId: string;
+    jobGeneration: string;
+    kind: FoldWaitKind;
+    label: string;
+    outputRef: JobOutputRetrieval;
+    /** What the interrupted turn still intended to do, so the wake can finish it. */
+    remainingIntent: string | undefined;
+    foldedAt: number;
+    /** Only command kinds can change directory; task-style waits never do. */
+    cwdSensitive: boolean;
+}
+/** A terminal completion observed for a folded job. */
+export interface ForegroundTerminalPayload {
+    jobId: string;
+    generation: string;
+    text: string;
+}
+/**
+ * Per-wait fold capability. `getJob` is bound at registration over the manager
+ * that registered THIS job, which is what makes cross-manager identity safe.
+ */
+export interface FoldAdapter {
+    readonly kind: FoldWaitKind;
+    readonly jobId: string;
+    readonly jobGeneration: string;
+    readonly label: string;
+    readonly cwdSensitive: boolean;
+    /** Signal for the foreground wait; aborting capture must roll back the fold. */
+    readonly signal?: AbortSignal;
+    /** True only when the adapter was created by a model-owned Agent turn. */
+    readonly originatingTurn?: boolean;
+    readonly outputRef: JobOutputRetrieval;
+    /** Registration-bound resolver: the job for this adapter, or undefined once evicted or reused. */
+    readonly getJob: () => AsyncJob | undefined;
+    /** Settle the foreground caller with the fold result. Idempotent. */
+    readonly detachObserver: (receipt: FoldReceipt) => ForegroundSettleOutcome;
+    /** Hand a parked completion back to a still-attached observer. Idempotent. */
+    readonly resolveForegroundObserver: (payload: ForegroundTerminalPayload) => ForegroundSettleOutcome;
+}
+export type FoldRequestResult = {
+    status: "folded";
+    receipt: FoldReceipt;
+} | {
+    status: "unavailable";
+    reason: string;
+} | {
+    status: "already-terminal";
+    reason: string;
+} | {
+    status: "capture-failed";
+    reason: string;
+};
+/** What a delivery should carry, decided by the durable slot state (T2). */
+export type FoldDeliveryDisposition = {
+    kind: "ordinary";
+} | {
+    kind: "parked";
+} | {
+    kind: "receipt";
+    receipt: FoldReceipt;
+    text: string;
+};
+export interface FoldCoordinatorDeps {
+    /**
+     * Fence old-turn steering admission and return the release handle. Armed
+     * synchronously inside the prologue because the agent loop polls steering
+     * upstream of its pause checkpoint; fencing there keeps queued steering
+     * intact instead of draining it.
+     */
+    armSteeringFence: () => () => void;
+    /** Whether this fold belongs to a currently running Agent turn. */
+    hasActiveTurn?: () => boolean;
+    /** Arm the cooperative stop so the turn ends after the fold result, never via abort. */
+    requestStop: () => void;
+    /** Capture what the interrupted turn still intended to accomplish. */
+    captureRemainingIntent: () => Promise<string | undefined> | string | undefined;
+    /**
+     * Push a parked completion into the wake path. The delivery seam parks a
+     * completion that arrives before the receipt exists; when the fold later
+     * replays it (A6), THIS is what makes the wake happen rather than relying on
+     * an unrelated idle rearm to rescue it.
+     */
+    deliverParked: (job: AsyncJob, disposition: {
+        kind: "receipt";
+        receipt: FoldReceipt;
+        text: string;
+    }) => void;
+}
+/** Why a slot is being retired, which decides whether retiring is safe. */
+export type FoldRetireReason = "cancel" | "evict";
+/**
+ * Render a fold receipt for the wake turn.
+ *
+ * Carries the job id, a real retrieval handle, and the captured remaining
+ * intent, so the wake turn can finish the ORIGINAL task instead of only
+ * reporting that a command ended. The cwd caveat is included only for wait
+ * kinds that can actually change directory.
+ */
+export declare function describeFoldReceipt(receipt: FoldReceipt): string;
+export declare class FoldCoordinator {
+    #private;
+    constructor(deps: FoldCoordinatorDeps);
+    /** Register a foldable wait. The most recently registered wait is the default target. */
+    registerParticipant(adapter: FoldAdapter): () => void;
+    /** Whether any wait is currently foldable, for the key-availability gate. */
+    hasFoldableParticipant(): boolean;
+    /** Deterministic target: newest registration wins, so the chord folds what the user is watching. */
+    resolveTarget(): FoldAdapter | undefined;
+    /**
+     * T1. Synchronous prologue then async durability tail.
+     *
+     * Nothing awaits before the slot is reserved and the fence is armed, so a
+     * completion or a steering submission that races the capture cannot slip
+     * past into the old turn.
+     */
+    requestFold(explicit?: FoldAdapter): Promise<FoldRequestResult>;
+    /**
+     * T2. Decide what a delivery carries, branching on the DURABLE slot state
+     * rather than on transient hand-off state.
+     *
+     * `present` attaches the receipt to the retry-stable carrier BEFORE clearing
+     * the slot, so a retried invocation still finds it.
+     */
+    onDelivery(job: AsyncJob, text: string): FoldDeliveryDisposition;
+    /**
+     * Retirement. T-R2: never drop a slot that holds an undelivered payload or
+     * that a still-possible delivery could consume.
+     *
+     * - `cancel` retires freely, because a cancelled job enqueues no delivery at
+     *   all, so no later consumer can arrive.
+     * - `evict` only retires when the job can no longer deliver. An evicted
+     *   record still delivers with its retained job object, so a completed or
+     *   failed job keeps its slot.
+     */
+    retire(job: AsyncJob, reason: FoldRetireReason): boolean;
+    /**
+     * Claim the single completion notice for a job.
+     *
+     * Returns true exactly once per job. A delivery can be retried with the same
+     * object, so an unguarded notice would repeat for one completion.
+     */
+    claimCompletionNotice(job: AsyncJob): boolean;
+    /** Claim the receipt-bearing queue entry once across manager delivery retries. */
+    claimCompletionDelivery(job: AsyncJob): boolean;
+    /** Test/diagnostic view of the durable slot state for a job. */
+    slotStateFor(job: AsyncJob): "none" | "reserved-empty" | "reserved-parked" | "present" | "carried";
+}

package/dist/types/session/sdk-run-capability-internal.d.ts

@@ -0,0 +1,7 @@
+declare const sdkRunTokenBrand: unique symbol;
+export interface SdkRunCapability {
+    readonly [sdkRunTokenBrand]: string;
+}
+export declare function createSdkRunCapability(token: string): SdkRunCapability;
+export declare function readSdkRunCapability(value: unknown): string | undefined;
+export {};

package/dist/types/session/sdk-run-capability.d.ts

@@ -0,0 +1,2 @@
+export type { SdkRunCapability } from "./sdk-run-capability-internal";
+export { readSdkRunCapability } from "./sdk-run-capability-internal";