@gajae-code/coding-agent 0.10.2 → 0.11.1

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

@@ -0,0 +1,105 @@
+/** Transport-neutral workflow gate contract used by SDK workflow coordination. */
+/** Lifecycle stages that emit machine-addressable SDK workflow gates. */
+export type WorkflowStage = "deep-interview" | "ralplan" | "ultragoal";
+/** Reserved stage names that are explicitly not part of the v1 contract. */
+export declare const RESERVED_WORKFLOW_STAGES: readonly string[];
+export type WorkflowGateKind = "question" | "approval" | "execution";
+/** The documented JSON Schema 2020-12 subset supported by the gate validator. */
+export interface JsonSchema {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+    enum?: unknown[];
+    const?: unknown;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    items?: JsonSchema;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minimum?: number;
+    maximum?: number;
+    title?: string;
+    description?: string;
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+}
+export interface WorkflowGateOption {
+    value: unknown;
+    label: string;
+    description?: string;
+}
+export interface WorkflowGateContext {
+    title?: string;
+    plan?: string;
+    source?: string;
+    prompt?: string;
+    summary?: string;
+    stage_state?: Record<string, unknown>;
+    artifact_refs?: Array<{
+        kind: string;
+        path?: string;
+        sha256?: string;
+    }>;
+    language?: string;
+}
+/** Outbound event: a machine-addressable workflow gate awaiting an answer. */
+export interface WorkflowGate {
+    type: "workflow_gate";
+    gate_id: string;
+    stage: WorkflowStage;
+    kind: WorkflowGateKind;
+    schema: JsonSchema;
+    schema_hash: string;
+    options?: WorkflowGateOption[];
+    context: WorkflowGateContext;
+    created_at: string;
+    required: true;
+}
+/** Non-actionable durable-gate state retained for restart diagnostics. */
+export interface WorkflowGateLifecycle {
+    state: "quarantined";
+    reason: "orphaned_after_process_restart" | "accepted_unadvanced_after_process_restart" | "continuation_owner_lost" | "opened_without_continuation" | "finalization_failed" | "advance_failed";
+    quarantinedAt: string;
+    supersededByGateId?: string;
+}
+/** A quarantined gate is diagnostic-only and must never be presented or answered. */
+export interface WorkflowGateDiagnostic extends WorkflowGate {
+    id: string;
+    tag: "quarantined";
+    lifecycle: WorkflowGateLifecycle;
+}
+/** Stable Q12 row preserving the root WorkflowGate shape. */
+export type WorkflowGateQueryRecord = (WorkflowGate & {
+    id: string;
+    tag: "pending";
+    lifecycle?: undefined;
+}) | WorkflowGateDiagnostic;
+/** Inbound: the agent's answer to a workflow gate. */
+export interface WorkflowGateResponse {
+    gate_id: string;
+    answer: unknown;
+    idempotency_key?: string;
+}
+/** Outcome of resolving a gate, surfaced back to the answering client. */
+export interface WorkflowGateResolution {
+    gate_id: string;
+    status: "accepted" | "rejected";
+    answer_hash: string;
+    resolved_at: string;
+    error?: WorkflowGateValidationError;
+}
+/** Typed error shape for schema validation failures. */
+export interface WorkflowGateValidationError {
+    code: "invalid_workflow_gate_answer";
+    gate_id: string;
+    schema_hash: string;
+    errors: Array<{
+        path: string;
+        keyword: string;
+        message: string;
+        expected?: unknown;
+    }>;
+}

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

@@ -9,6 +9,7 @@ import type { CompactOptions } from "../extensibility/extensions/types";
 import type { Skill } from "../extensibility/skills";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { MCPManager } from "../runtime-mcp";
+import type { NotificationSessionReconcileResult, NotificationSessionStatus } from "../sdk/bus/session-control";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
@@ -80,6 +81,10 @@ export interface InteractiveModeContext {
     historyStorage?: HistoryStorage;
     mcpManager?: MCPManager;
     lspServers?: LspStartupServerInfo[];
+    /** Shared controller query; absent in ACP/lightweight test contexts. */
+    getCurrentSessionNotificationStatus?(): NotificationSessionStatus | undefined;
+    /** Toggle only the current session; absent in ACP/lightweight test contexts. */
+    setCurrentSessionNotificationsEnabled?(enabled: boolean): Promise<NotificationSessionReconcileResult | undefined>;
     readonly ircLedger: IrcObservationLedger;
     isInitialized: boolean;
     isBackgrounded: boolean;
@@ -234,9 +239,9 @@ export interface InteractiveModeContext {
     handleContextCommand(): void;
     handleDumpCommand(): void;
     handleDebugTranscriptCommand(): Promise<void>;
-    handleClearCommand(): Promise<void>;
+    handleClearCommand(): Promise<boolean>;
     handleContextClearCommand(): Promise<void>;
-    handleDropCommand(): Promise<void>;
+    handleDropCommand(): Promise<boolean>;
     handleForkCommand(): Promise<void>;
     handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;

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

@@ -5,6 +5,8 @@ import type { MCPGetPromptResult, MCPPrompt, MCPRequestOptions, MCPResource, MCP
  */
 export declare function connectToServer(name: string, config: MCPServerConfig, options?: {
     signal?: AbortSignal;
+    /** Whether to advertise the roots/list capability (default: true). */
+    advertiseRoots?: boolean;
     onNotification?: (method: string, params: unknown) => void;
     onRequest?: (method: string, params: unknown) => Promise<unknown>;
 }): Promise<MCPServerConnection>;

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

@@ -13,8 +13,10 @@ export interface LoadMCPConfigsOptions {
     filterExa?: boolean;
     /** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
     filterBrowser?: boolean;
-    /** Only include servers eligible for startup connection, i.e. autoload !== false (default: false) */
+    /** Only include startup-eligible servers; exact-config sessions always enforce autoload !== false. */
     autoloadOnly?: boolean;
+    /** Load only this explicit MCP config file. */
+    configPath?: string;
 }
 /** Result of loading MCP configs */
 export interface LoadMCPConfigsResult {
@@ -24,6 +26,8 @@ export interface LoadMCPConfigsResult {
     exaApiKeys: string[];
     /** Source metadata for each server */
     sources: Record<string, SourceMeta>;
+    /** Whether the explicit configuration was unavailable or contained invalid entries. */
+    configurationWarning: boolean;
 }
 /**
  * Load all MCP server configs from standard locations.

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

@@ -42,6 +42,12 @@ export interface MCPDiscoverOptions {
     autoloadOnly?: boolean;
     /** Called when starting to connect to servers */
     onConnecting?: (serverNames: string[]) => void;
+    /** Load only this explicit MCP config file. */
+    configPath?: string;
+}
+export interface MCPManagerOptions {
+    /** Restrict this instance to tools from an explicit MCP config. */
+    toolsOnly?: boolean;
 }
 /**
  * MCP Server Manager.
@@ -58,7 +64,8 @@ export declare class MCPManager {
     static setInstance(value: MCPManager | undefined): void;
     /** Reset the process-global instance. Test-only. */
     static resetForTests(): void;
-    constructor(cwd: string, toolCache?: MCPToolCache | null);
+    constructor(cwd: string, toolCache?: MCPToolCache | null, options?: MCPManagerOptions);
+    isToolsOnly(): boolean;
     /**
      * Set a callback to receive all server notifications.
      */

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

@@ -187,6 +187,10 @@ export interface MCPToolCallResult {
     content: MCPContent[];
     isError?: boolean;
 }
+/** Expected configured-server transport or protocol failure. */
+export declare class MCPExpectedFailure extends Error {
+    constructor(cause?: unknown);
+}
 export interface MCPRequestOptions {
     /** Abort signal (e.g. Escape-to-interrupt) */
     signal?: AbortSignal;

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

@@ -0,0 +1,67 @@
+import { SdkClient, SdkClientError, type SdkFrame } from "../client";
+type JsonObject = Record<string, unknown>;
+/** The small agent-side ACP surface used for reverse requests. */
+export interface AcpReverseConnection {
+    request?(method: string, params: JsonObject): Promise<unknown>;
+    [key: string]: unknown;
+}
+export interface AcpProviderRegistration {
+    capability: string;
+    definitions: unknown;
+}
+export interface AcpSdkAdapterOptions {
+    url: string;
+    token: string;
+    client?: SdkClient;
+    connection?: AcpReverseConnection;
+    providers?: AcpProviderRegistration[];
+    /** Lease IDs persisted by the ACP host across a WebSocket reconnect. */
+    expectedLeaseIds?: Record<string, string>;
+    heartbeatMs?: number;
+    reverseCancelTtlMs?: number;
+}
+export declare class AcpSdkAdapterError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export type AcpReconnectFailedHandler = (error: SdkClientError) => void;
+export type AcpFrameHandler = (frame: SdkFrame) => void;
+/**
+ * Pure ACP-to-SDK adapter. It deliberately owns neither an AgentSession nor an
+ * ACP bridge: all session work is performed through authenticated v3 frames.
+ */
+export declare class AcpSdkAdapter {
+    #private;
+    constructor(options: AcpSdkAdapterOptions);
+    static connect(options: AcpSdkAdapterOptions): Promise<AcpSdkAdapter>;
+    get leaseIds(): ReadonlyMap<string, string>;
+    get connectionId(): string | undefined;
+    onReconnectFailed(handler: AcpReconnectFailedHandler): () => void;
+    onFrame(handler: AcpFrameHandler): () => void;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    prompt(params: JsonObject | string): Promise<unknown>;
+    cancel(): Promise<unknown>;
+    setModel(params: JsonObject | string): Promise<unknown>;
+    control(operation: string, input?: JsonObject): Promise<unknown>;
+    query(query: string, input?: JsonObject, cursor?: string): Promise<unknown>;
+    global(operation: string, input?: JsonObject, idempotencyKey?: string): Promise<unknown>;
+    sdkControl(params: {
+        operation: string;
+        input?: JsonObject;
+    }): Promise<unknown>;
+    sdkQuery(params: {
+        query: string;
+        input?: JsonObject;
+        cursor?: string;
+    }): Promise<unknown>;
+    sdkGlobal(params: {
+        operation: string;
+        input?: JsonObject;
+        idempotencyKey?: string;
+    }): Promise<unknown>;
+    /** Dispatches the ACP extension method names without exposing endpoint credentials. */
+    handle(method: string, params?: JsonObject): Promise<unknown>;
+    registerProvider(provider: AcpProviderRegistration): Promise<void>;
+}
+export {};

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

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

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

@@ -0,0 +1,53 @@
+import { type BrokerDiscovery, redactBrokerDiscovery } from "./discovery";
+import { type LifecycleDurableEffectsReceipt, LifecycleLedger, type LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
+import { SessionIndex } from "./session-index";
+export interface BrokerSettings {
+    agentDir: string;
+    packageGeneration?: string;
+    port?: number;
+    heartbeatTtlMs?: number;
+}
+export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "readiness_timeout" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
+export type BrokerCleanupEvidence = {
+    phase: "artifacts" | "transcript" | "metadata";
+    artifactsIdentity?: {
+        dev: string;
+        ino: string;
+    };
+    transcriptIdentity?: {
+        dev: string;
+        ino: string;
+    };
+};
+export type BrokerResponse = {
+    ok: true;
+    result?: unknown;
+    indexSeq?: number;
+} | {
+    ok: false;
+    error: {
+        code: BrokerErrorCode;
+        message: string;
+        endpoint?: "unavailable";
+        cleanup?: BrokerCleanupEvidence;
+    };
+    indexSeq?: number;
+    durableEffects?: LifecycleDurableEffectsReceipt;
+    startupFailure?: LifecycleStartupFailureReceipt;
+};
+export declare class Broker {
+    #private;
+    readonly settings: Required<BrokerSettings>;
+    readonly index: SessionIndex;
+    readonly ledger: LifecycleLedger;
+    discovery: BrokerDiscovery | null;
+    constructor(settings: BrokerSettings);
+    start(): Promise<BrokerDiscovery>;
+    get ownsDiscovery(): boolean;
+    status(): ReturnType<typeof redactBrokerDiscovery> | null;
+    heartbeat(): Promise<void>;
+    stop(): Promise<void>;
+    handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string): Promise<BrokerResponse>;
+}
+/** Test-only hook for simulating a process crash after terminal persistence verification. */
+export declare function setTerminalPersistenceHookForTest(broker: Broker, hook: (() => void) | undefined): void;

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

@@ -0,0 +1,30 @@
+import { processIncarnation } from "./process-incarnation";
+import { SDK_STATE_VERSION } from "./state-version";
+export declare const BROKER_HEARTBEAT_TTL_MS = 15000;
+export interface BrokerDiscovery {
+    version: typeof SDK_STATE_VERSION;
+    protocolVersion: 3;
+    packageGeneration: string;
+    ownerId: string;
+    pid: number;
+    incarnation: string;
+    host: "127.0.0.1";
+    port: number;
+    url: string;
+    token: string;
+    startedAt: number;
+    heartbeatAt: number;
+}
+export type RedactedBrokerDiscovery = Omit<BrokerDiscovery, "token"> & {
+    token: "[redacted]";
+};
+export type BrokerDiscoveryWrite = Omit<BrokerDiscovery, "incarnation"> & {
+    incarnation?: string;
+};
+export declare const brokerDiscoveryPath: (agentDir: string) => string;
+export declare const newBrokerToken: () => string;
+export declare const brokerProcessIncarnation: typeof processIncarnation;
+export declare function isPidAlive(pid: number): boolean;
+export declare function writeBrokerDiscovery(agentDir: string, discovery: BrokerDiscoveryWrite): Promise<void>;
+export declare function readBrokerDiscovery(agentDir: string, ttlMs?: number): Promise<BrokerDiscovery | null>;
+export declare function redactBrokerDiscovery(discovery: BrokerDiscovery): RedactedBrokerDiscovery;

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

@@ -0,0 +1,42 @@
+import { type ChildProcess } from "node:child_process";
+import { type BrokerDiscovery } from "./discovery";
+import { type SdkInternalSpawnCommand } from "./runtime";
+export interface EnsureBrokerSettings {
+    agentDir: string;
+    heartbeatTtlMs?: number;
+    /**
+     * Environment for the spawned detached broker. Defaults to `process.env`; tests
+     * that pre-start an isolated broker pass the same sanitized child env so the
+     * broker and the child that attaches to it share one owned root.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+export interface FixtureBrokerLease {
+    close(): Promise<void>;
+}
+export interface StartedFixtureBroker {
+    discovery: BrokerDiscovery;
+    lease: FixtureBrokerLease;
+}
+interface BrokerOwner {
+    stop(): Promise<void>;
+    canReuse(discovery: BrokerDiscovery | null): boolean;
+    markReady(discovery: BrokerDiscovery): boolean;
+}
+interface ReapTiming {
+    gracefulMs: number;
+    killVerifyMs: number;
+}
+/** Starts the detached broker entrypoint when discovery has no live owner. */
+export declare function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery>;
+/** Starts one fresh fixture broker and returns its sole exact-child close lease. */
+export declare function startFixtureBrokerWithLeaseForTest(settings: EnsureBrokerSettings): Promise<StartedFixtureBroker>;
+/** Test hook: returns a stop handle for the detached broker this process spawned. */
+export declare function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined;
+/** Test hook: drives the detached-broker reap on a controllable child surface. */
+export declare function reapSpawnedBrokerForTest(child: ChildProcess, timing?: ReapTiming): Promise<void>;
+/** Test hook: resolves the complete broker environment without spawning. */
+export declare function brokerSpawnEnvironmentForTest(command: SdkInternalSpawnCommand, override?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Test hook: installs an exact controllable owner to exercise replacement fencing. */
+export declare function registerBrokerOwnerForTest(agentDir: string, child: ChildProcess, timing?: ReapTiming): BrokerOwner;
+export {};

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

@@ -0,0 +1,3 @@
+export declare function brokerIdentityPath(agentDir: string): string;
+export declare function getBrokerIdentityKey(agentDir: string): Promise<string>;
+export declare function deriveIdempotencyIdentity(agentDir: string, operation: string, callerKey: string, canonicalTargetHash: string): Promise<string>;

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

@@ -0,0 +1,8 @@
+export * from "./broker";
+export * from "./discovery";
+export * from "./ensure";
+export * from "./identity";
+export * from "./lifecycle";
+export * from "./lifecycle-ledger";
+export * from "./session-index";
+export * from "./transport";

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

@@ -0,0 +1,95 @@
+import type { SdkStartupFailure, SdkStartupRollbackResult } from "../startup-capability";
+import { SDK_STATE_VERSION } from "./state-version";
+export type LifecycleState = "accepted" | "effect_started" | "awaiting_ready" | "terminal_ok" | "terminal_error" | "terminal_uncertain";
+export interface LifecycleWorktreeIntent {
+    repoRoot: string;
+    worktreePath: string;
+    detached: boolean;
+    baseRef: string;
+    branchName?: string;
+}
+export interface LifecycleEffectIntent {
+    sessionId: string;
+    stateRoot: string;
+    childOwnershipEstablished?: boolean;
+    worktree?: LifecycleWorktreeIntent;
+}
+/** Durable lifecycle effects retained for exact replay; never implies rollback authority. */
+export interface LifecycleCleanupProof {
+    processExited: true;
+    endpointRemoved: true;
+    hostUnregistered: {
+        state: "unregistered";
+        indexSeq: number;
+        lifecycleRequestId?: string;
+    } | {
+        state: "not_registered";
+    };
+    rollback: {
+        endpointGeneration: number | null;
+        fenced: true;
+        runtimeRemoved: true;
+        hostStopped: true;
+        brokerRegistrationReleased: true;
+    };
+}
+export interface LifecycleStartupFailureReceipt extends SdkStartupFailure {
+    artifactDigest: string;
+    rollback: SdkStartupRollbackResult;
+    cleanupProof?: LifecycleCleanupProof;
+}
+export interface LifecycleDurableEffectsReceipt {
+    worktree?: {
+        cwdDigest: string;
+        created: boolean;
+        reused: boolean;
+        branchDigest?: string;
+    };
+    transcript?: {
+        identityDigest: string;
+        contentDigest: string;
+    };
+    startup?: LifecycleStartupFailureReceipt;
+    digest?: string;
+}
+export interface LifecycleLedgerEntry {
+    version: typeof SDK_STATE_VERSION;
+    identity: string;
+    requestHash: string;
+    state: LifecycleState;
+    intendedSessionId?: string;
+    resultSessionId?: string;
+    effectMarker?: string;
+    effectIntent?: LifecycleEffectIntent;
+    durableEffects?: LifecycleDurableEffectsReceipt;
+    startupFailure?: LifecycleStartupFailureReceipt;
+    endpointGeneration?: number;
+    responseDigest?: string;
+    response?: unknown;
+    ts: number;
+}
+export type BeginResult = {
+    kind: "new";
+    entry: LifecycleLedgerEntry;
+} | {
+    kind: "replay";
+    entry: LifecycleLedgerEntry;
+} | {
+    kind: "idempotency_conflict";
+} | {
+    kind: "terminal_uncertain";
+    entry: LifecycleLedgerEntry;
+} | {
+    kind: "in_progress";
+    entry: LifecycleLedgerEntry;
+};
+export declare class LifecycleLedger {
+    #private;
+    constructor(agentDir: string);
+    open(): Promise<this>;
+    get warnings(): readonly string[];
+    begin(identity: string, requestHash: string): Promise<BeginResult>;
+    transition(identity: string, state: LifecycleState, fields?: Omit<Partial<LifecycleLedgerEntry>, "identity" | "requestHash" | "state" | "ts">): Promise<LifecycleLedgerEntry>;
+    assertSupportedStateVersions(): Promise<void>;
+    get(identity: string): LifecycleLedgerEntry | undefined;
+}

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

@@ -0,0 +1,85 @@
+import type { SdkStartupFailure, SdkStartupRollbackResult } from "../startup-capability";
+import type { Broker, BrokerResponse } from "./broker";
+import type { LifecycleDurableEffectsReceipt, LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
+import { type ProcessIncarnationCommandRunner, type ProcessIncarnationOptions, parseDarwinProcessIncarnation, processIncarnation } from "./process-incarnation";
+import { type SdkInternalSpawnCommand } from "./runtime";
+export { type ProcessIncarnationCommandRunner, type ProcessIncarnationOptions, parseDarwinProcessIncarnation, processIncarnation, };
+export interface LifecycleDeadlines {
+    receivedAt: number;
+    requestedReadinessTimeoutMs: number;
+    semanticReadyDeadlineAt: number;
+    terminationStartDeadlineAt: number;
+    lifecycleCleanupDeadlineAt: number;
+}
+export declare function deriveLifecycleDeadlines(receivedAt: number, requestedReadinessTimeoutMs: number): LifecycleDeadlines;
+export interface LifecycleTiming {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+type LifecycleCommand = SdkInternalSpawnCommand | {
+    file: string;
+    args: string[];
+};
+type LifecycleCommandResolver = () => LifecycleCommand;
+export declare function setLifecycleCommandResolverForTest(broker: Broker, resolver: LifecycleCommandResolver | undefined): void;
+export declare function setLifecycleTimingForTest(broker: Broker, timing: LifecycleTiming | undefined): void;
+export declare function hasValidLifecycleDeadlines(value: LifecycleDeadlines, now?: number): boolean;
+type Input = Record<string, unknown>;
+export declare const isCanonicalSessionId: (value: string) => boolean;
+export interface SessionLifecycleWorktreeTarget {
+    enabled: true;
+    name?: string;
+}
+export interface SessionLifecycleWorktreeReceipt {
+    enabled: true;
+    cwd: string;
+    created: boolean;
+    reused: boolean;
+    branch?: string;
+}
+export interface SessionLifecycleTranscriptIdentity {
+    dev: string;
+    ino: string;
+    size: number;
+    mtimeMs: number;
+    mtimeNs: string;
+}
+export interface SessionLifecycleLaunchRequest {
+    operation: "session.create" | "session.fork" | "session.resume";
+    sessionId: string;
+    cwd: string;
+    stateRoot: string;
+    sourceSessionId?: string;
+    sourceSessionPath?: string;
+    sourceSessionIdentity?: SessionLifecycleTranscriptIdentity;
+    sourceCwd?: string;
+    sessionPath?: string;
+    sessionIdentity?: SessionLifecycleTranscriptIdentity;
+    /** Broker-issued effect marker which the child echoes only after host readiness. */
+    effectMarker?: string;
+    modelPreset?: string;
+    worktree?: SessionLifecycleWorktreeTarget;
+    receivedAt: number;
+    requestedReadinessTimeoutMs: number;
+    semanticReadyDeadlineAt: number;
+    terminationStartDeadlineAt: number;
+    lifecycleCleanupDeadlineAt: number;
+}
+export declare function readSessionLifecycleLaunchRequest(value: string | undefined, now?: number): SessionLifecycleLaunchRequest;
+export declare function setProcessIncarnationForTest(broker: Broker, value: ((pid: number) => string | undefined) | undefined): void;
+/** The child writes this only after its endpoint and semantic ready event are both live. */
+export declare function writeSessionLifecycleReady(root: string, id: string, effectMarker: string): Promise<void>;
+export interface LifecycleTranscriptEvidence {
+    digest: string;
+    identity: SessionLifecycleTranscriptIdentity;
+}
+/** The child writes bounded startup diagnostics before exiting without readiness. */
+export declare function writeSessionLifecycleFailure(root: string, id: string, effectMarker: string, failure: SdkStartupFailure, rollback: SdkStartupRollbackResult, transcript?: LifecycleTranscriptEvidence, ownerIncarnation?: string): Promise<void>;
+export interface LifecycleExecutionOutcome {
+    response: BrokerResponse;
+    durableEffects?: LifecycleDurableEffectsReceipt;
+    startupFailure?: LifecycleStartupFailureReceipt;
+    deferredArtifactCleanup?: () => Promise<void>;
+}
+/** Returns the response together with every durable lifecycle fact needed for truthful replay. */
+export declare function executeLifecycle(broker: Broker, operation: string, input: Input, identity: string): Promise<LifecycleExecutionOutcome>;

package/dist/types/sdk/broker/process-incarnation.d.ts

@@ -0,0 +1,14 @@
+type ProcessIncarnationCommandResult = {
+    exitCode: number | null;
+    stdout: string;
+} | undefined;
+export type ProcessIncarnationCommandRunner = (command: string, args: readonly string[]) => ProcessIncarnationCommandResult;
+export interface ProcessIncarnationOptions {
+    platform?: typeof process.platform;
+    runCommand?: ProcessIncarnationCommandRunner;
+}
+/** Parse the microsecond-resolution start timestamp returned by Darwin proc_pidinfo. */
+export declare function parseDarwinProcessIncarnation(info: Uint8Array): string | undefined;
+/** A PID is reusable; bind it to the strongest OS-provided process start incarnation available. */
+export declare function processIncarnation(pid: number, options?: ProcessIncarnationOptions): string | undefined;
+export {};

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

@@ -0,0 +1,33 @@
+export type SdkInternalAction = "broker-internal" | "session-host-internal";
+export type SdkInternalSpawnCommand = {
+    kind: "bun-source";
+    file: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+} | {
+    kind: "compiled";
+    file: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cwd?: undefined;
+};
+type EmbeddedFile = Blob | {
+    name: string;
+};
+/** Test-only injectable inputs for hostile evidence and platform grammar coverage. */
+export interface SdkInternalRuntimeDescriptorTestOptions {
+    execPath?: string;
+    environment?: NodeJS.ProcessEnv;
+    embeddedFiles?: readonly EmbeddedFile[];
+    markerPath?: string;
+    brokerDirectory?: string;
+    cliPath?: string;
+    configPath?: string;
+    bunAvailable?: boolean;
+}
+/** Resolve the production descriptor from the statically imported marker and current Bun runtime evidence. */
+export declare function resolveSdkInternalSpawnCommand(action: SdkInternalAction): SdkInternalSpawnCommand;
+/** Test hook: injects runtime evidence without weakening the production marker authority. */
+export declare function resolveSdkInternalSpawnCommandForTest(action: SdkInternalAction, options: SdkInternalRuntimeDescriptorTestOptions): SdkInternalSpawnCommand;
+export {};