@gajae-code/coding-agent 0.15.6 → 0.16.1

package/dist/types/modes/components/status-line/segments.d.ts

@@ -1,5 +1,15 @@
+import { type ThemeColor } from "../../../modes/theme/theme";
 import type { RenderedSegment, SegmentContext, StatusLineSegment, StatusLineSegmentId } from "./types";
 export type { SegmentContext } from "./types";
+/**
+ * Icon and color for the active goal indicator, or null when goal mode is not
+ * showing. Shared with the narrow-width priority row so the compact glyph keeps
+ * the same status color as the full label.
+ */
+export declare function goalStatusDisplay(ctx: SegmentContext): {
+    icon: string;
+    color: ThemeColor;
+} | null;
 export declare const SEGMENTS: Record<StatusLineSegmentId, StatusLineSegment>;
 export declare function renderSegment(id: StatusLineSegmentId, ctx: SegmentContext): RenderedSegment;
 export declare const ALL_SEGMENT_IDS: StatusLineSegmentId[];

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

@@ -9,7 +9,7 @@ import type { ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetConte
 import type { CompactOptions } from "../extensibility/extensions/types";
 import { type Skill } from "../extensibility/skills";
 import type { NotificationSessionReconcileResult, NotificationSessionStatus } from "../sdk/bus/session-control";
-import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import type { AgentSession, AgentSessionEvent, AsyncJobSnapshotItem } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import type { LspStartupServerInfo } from "../tools";
@@ -42,7 +42,21 @@ export declare function getComposerPlaceholder(keybindings: Pick<KeybindingsMana
     readonly busyPromptMode: "steer" | "queue";
     readonly showActionHints: boolean;
 }): string;
-export declare function resolveActivityIndicatorMessage(foregroundActive: boolean, activeBackgroundTasks: number, foregroundMessage: string): string | undefined;
+/** Running background work split into the three kinds the activity indicator names. */
+export interface BackgroundActivityTally {
+    subagents: number;
+    backgroundBash: number;
+    monitors: number;
+}
+/**
+ * Classify running jobs for the activity indicator using the three locked
+ * predicates: subagents are `task` jobs carrying subagent metadata, monitors
+ * are flagged by `metadata.monitor`, and background bash is a `bash` job that
+ * is not a monitor. A running job matching none of them (a task job without
+ * subagent metadata) is outside this indicator and is not counted.
+ */
+export declare function tallyBackgroundActivity(running: readonly AsyncJobSnapshotItem[]): BackgroundActivityTally;
+export declare function resolveActivityIndicatorMessage(foregroundActive: boolean, activity: BackgroundActivityTally, foregroundMessage: string): string | undefined;
 export declare function getWelcomeTranscriptReservedRows(chatContainer: Container, width: number): number;
 export type WelcomeBannerSettingMode = "auto" | "unicode" | "square" | "ascii";
 export declare function resolveWelcomeLogoMode(mode: WelcomeBannerSettingMode, env?: Record<string, string | undefined>, platform?: NodeJS.Platform): WelcomeLogoMode;

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

@@ -5,6 +5,7 @@
  * - `gjc -p "prompt"` - text output
  * - `gjc --mode json "prompt"` - JSON event stream
  */
+import type { AgentMessage } from "@gajae-code/agent-core";
 import { type ImageContent } from "@gajae-code/ai/core";
 import type { AgentSession } from "../session/agent-session";
 /**
@@ -37,8 +38,24 @@ export interface PrintModeOptions {
  * it is intentionally NOT covered by this exit code.
  */
 export declare const CONTEXT_OVERFLOW_EXIT_CODE = 78;
+declare const EMPTY_TURN_ERROR: {
+    readonly code: "empty_response";
+    readonly message: "Turn completed without assistant text.";
+};
+export type PrintTerminalDisposition = {
+    status: "success";
+    assistantText: true;
+} | {
+    status: "failure";
+    error: typeof EMPTY_TURN_ERROR | {
+        code: "assistant_error";
+        message: string;
+    };
+};
+export declare function resolvePrintTerminalDisposition(messages: readonly AgentMessage[], submittedPrompt: boolean, turnStartIndex?: number): PrintTerminalDisposition | undefined;
 /**
  * Run in print (single-shot) mode.
  * Sends prompts to the agent and outputs the result.
  */
 export declare function runPrintMode(session: AgentSession, options: PrintModeOptions): Promise<void>;
+export {};

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

@@ -6,7 +6,7 @@ export type SymbolPreset = "unicode" | "nerd" | "ascii";
 /**
  * All available symbol keys organized by category.
  */
-export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.goal" | "icon.pause" | "icon.folder" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.time" | "icon.pi" | "icon.agents" | "icon.cache" | "icon.input" | "icon.output" | "icon.host" | "icon.session" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.mic" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.max" | "checkbox.checked" | "checkbox.unchecked" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.editing" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers";
+export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.goal" | "icon.pause" | "icon.folder" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.time" | "icon.pi" | "icon.agents" | "icon.cache" | "icon.input" | "icon.output" | "icon.host" | "icon.session" | "icon.star" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.mic" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.max" | "checkbox.checked" | "checkbox.unchecked" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.editing" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers";
 export type SpinnerType = "status" | "activity";
 export declare const THEME_COLOR_KEYS: readonly ["accent", "border", "borderAccent", "borderMuted", "success", "error", "warning", "muted", "dim", "text", "thinkingText", "selectedBg", "userMessageBg", "userMessageText", "customMessageBg", "customMessageText", "customMessageLabel", "toolPendingBg", "toolSuccessBg", "toolErrorBg", "toolTitle", "toolOutput", "mdHeading", "mdLink", "mdLinkUrl", "mdCode", "mdCodeBlock", "mdCodeBlockBorder", "mdQuote", "mdQuoteBorder", "mdHr", "mdListBullet", "toolDiffAdded", "toolDiffRemoved", "toolDiffContext", "syntaxComment", "syntaxKeyword", "syntaxFunction", "syntaxVariable", "syntaxString", "syntaxNumber", "syntaxType", "syntaxOperator", "syntaxPunctuation", "thinkingOff", "thinkingMinimal", "thinkingLow", "thinkingMedium", "thinkingHigh", "thinkingXhigh", "bashMode", "pythonMode", "statusLineBg", "statusLineSep", "statusLineModel", "statusLinePath", "statusLineGitClean", "statusLineGitDirty", "statusLineContext", "statusLineSpend", "statusLineStaged", "statusLineDirty", "statusLineUntracked", "statusLineOutput", "statusLineCost", "statusLineSubagents"];
 export type ThemeColor = "accent" | "border" | "borderAccent" | "borderMuted" | "success" | "error" | "warning" | "muted" | "dim" | "text" | "thinkingText" | "userMessageText" | "customMessageText" | "customMessageLabel" | "toolTitle" | "toolOutput" | "mdHeading" | "mdLink" | "mdLinkUrl" | "mdCode" | "mdCodeBlock" | "mdCodeBlockBorder" | "mdQuote" | "mdQuoteBorder" | "mdHr" | "mdListBullet" | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext" | "syntaxComment" | "syntaxKeyword" | "syntaxFunction" | "syntaxVariable" | "syntaxString" | "syntaxNumber" | "syntaxType" | "syntaxOperator" | "syntaxPunctuation" | "thinkingOff" | "thinkingMinimal" | "thinkingLow" | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh" | "bashMode" | "pythonMode" | "statusLineSep" | "statusLineModel" | "statusLinePath" | "statusLineGitClean" | "statusLineGitDirty" | "statusLineContext" | "statusLineSpend" | "statusLineStaged" | "statusLineDirty" | "statusLineUntracked" | "statusLineOutput" | "statusLineCost" | "statusLineSubagents";
@@ -128,6 +128,7 @@ export declare class Theme {
         output: string;
         host: string;
         session: string;
+        star: string;
         package: string;
         warning: string;
         rewind: string;

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

@@ -35,6 +35,8 @@ export type CompactionQueuedMessage = {
     text: string;
     mode: "steer" | "followUp";
     followUpQueuePolicy?: "sequential";
+    /** Composer steers stay one per poll even under `steeringMode: "all"`. */
+    steerQueuePolicy?: "sequential";
 };
 export type SubmittedUserInput = {
     text: string;

package/dist/types/modes/ui-language.d.ts

@@ -1,4 +1,4 @@
-export declare const UI_LANGUAGES: readonly ["en", "ko", "ja"];
+export declare const UI_LANGUAGES: readonly ["en", "ko", "zh", "ja"];
 export type UiLanguage = (typeof UI_LANGUAGES)[number];
 declare const ENGLISH_STRINGS: {
     readonly "settings.title": "Settings";
@@ -21,6 +21,7 @@ declare const ENGLISH_STRINGS: {
     readonly "settings.language.description": "Language for human-facing interactive UI text";
     readonly "settings.language.english": "English";
     readonly "settings.language.korean": "Korean (한국어)";
+    readonly "settings.language.chinese": "Chinese (简体中文)";
     readonly "settings.language.japanese": "Japanese (日本語)";
     readonly "language.current": "Current UI language:";
     readonly "language.changed": "UI language changed to";
@@ -29,6 +30,11 @@ declare const ENGLISH_STRINGS: {
 export type UiStringKey = keyof typeof ENGLISH_STRINGS;
 /** User selection is authoritative; invalid or unavailable values deterministically fall back to English. */
 export declare function resolveUiLanguage(value: unknown): UiLanguage;
+/** Resolve explicit startup preference without allowing an invalid value to block startup. */
+export declare function resolveExplicitUiLanguage(configuredValue: unknown, environmentValue: string | undefined): {
+    language: UiLanguage;
+    hasPreference: boolean;
+};
 export declare function uiString(language: unknown, key: UiStringKey): string;
 /** Endonym shown by `/language` and the language submenu. */
 export declare const UI_LANGUAGE_LABELS: Record<UiLanguage, string>;

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

@@ -5,6 +5,7 @@ import { type DirectoryMigrationPolicy } from "../session-directory";
 import { type BrokerDiscovery, type BrokerPublicationObservation, type RedactedBrokerDiscovery } from "./discovery";
 import { type LifecycleDurableEffectsReceipt, LifecycleLedger, type LifecycleStartupFailureReceipt } from "./lifecycle-ledger";
 import { SessionIndex } from "./session-index";
+import { type MasterCapabilityVerifier, type SpawnSubstrateFailure, type SpawnSubstrateProvider } from "./spawn-authority";
 export interface BrokerSettings {
     agentDir: string;
     packageGeneration?: string;
@@ -12,6 +13,14 @@ export interface BrokerSettings {
     heartbeatTtlMs?: number;
     /** Broker-owned migration policy. Client lifecycle frames cannot select it. */
     resolveDirectoryMigration?: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
+    /** Exact managed-substrate authority. Tests inject an in-memory provider. */
+    spawnSubstrateProvider?: SpawnSubstrateProvider;
+    /** Ordered Q26 host control seam; production uses exact endpoint attachments. */
+    spawnPromptLayer?: SpawnPromptLayer;
+    /** Live-only, host-mediated capability verifier. It retains no request input. */
+    masterCapabilityVerifier?: MasterCapabilityVerifier;
+    /** Grace before an orphaned spawn child closes; schema-bounded in production. */
+    masterOrphanGraceMs?: number;
     /** Host model resolver override for lifecycle tests and embedders. */
     resolveModelPin?: SdkHostModelResolver;
 }
@@ -21,8 +30,13 @@ type ResolvedBrokerSettings = {
     port: number;
     heartbeatTtlMs: number;
     resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
+    masterCapabilityVerifier?: MasterCapabilityVerifier;
+    spawnSubstrateProvider?: SpawnSubstrateProvider;
+    spawnPromptLayer?: SpawnPromptLayer;
+    masterOrphanGraceMs: number;
 };
-export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "ready_then_exited" | "endpoint_unreadable" | "startup_admission_timeout" | "startup_admission_refused" | "readiness_timeout" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
+export declare function resolveBrokerPackageGeneration(): string;
+export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "ready_then_exited" | "endpoint_unreadable" | "startup_admission_timeout" | "startup_admission_refused" | "readiness_timeout" | "worktree_preparation_timeout" | "dependency_preparation_timeout" | "worktree_in_use" | "incarnation_unavailable" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
 export type BrokerCleanupIdentity = {
     dev: string;
     ino: string;
@@ -115,7 +129,7 @@ export type BrokerResponse = {
     error: {
         code: BrokerErrorCode;
         message: string;
-        details?: ModelProfileErrorDetails;
+        details?: ModelProfileErrorDetails | SpawnSubstrateFailure;
         endpoint?: "unavailable";
         cleanup?: BrokerCleanupEvidence;
     };
@@ -123,6 +137,58 @@ export type BrokerResponse = {
     durableEffects?: LifecycleDurableEffectsReceipt;
     startupFailure?: LifecycleStartupFailureReceipt;
 };
+/** Complete five-leg child endpoint pin captured at registration. */
+export type SpawnHostRegistration = {
+    sessionId: string;
+    endpointGeneration: number;
+    pid: number;
+    processIncarnation: string;
+    /** Workspace the child was launched into; bound so a colliding pid elsewhere cannot pass. */
+    cwd: string;
+    stateRoot: string;
+};
+export type SpawnPromptDispatch = {
+    kind: "accepted";
+    commandId: string;
+    turnId: string;
+    acceptedAt: number;
+} | {
+    kind: "pre_send_rejected";
+} | {
+    kind: "uncertain";
+};
+export type SpawnQ26Reconciliation = {
+    status: "accepted" | "in_flight" | "terminal_ok" | "failed" | "unknown";
+    clientRef?: string;
+    commandId?: string;
+    turnId?: string;
+    acceptedAt?: number;
+};
+/** Q26-only host control seam. It never receives or returns durable request material. */
+export interface SpawnPromptLayer {
+    awaitRegistration(input: {
+        childId: string;
+        cwd: string;
+        stateRoot: string;
+    }): Promise<{
+        ok: true;
+        registration: SpawnHostRegistration;
+    } | {
+        ok: false;
+    }>;
+    dispatch(input: {
+        sessionId: string;
+        task: string;
+        clientRef: string;
+        /** Endpoint identity proven at registration; implementations must not talk to another endpoint. */
+        pinned: SpawnHostRegistration;
+    }): Promise<SpawnPromptDispatch>;
+    reconcile(input: {
+        sessionId: string;
+        clientRef: string;
+        pinned: SpawnHostRegistration;
+    }): Promise<SpawnQ26Reconciliation>;
+}
 /** Test seam for lifecycle serialization identity. */
 export declare function lifecycleTargetForTest(operation: string, input: Record<string, unknown>): unknown;
 /** Tombstone prefix used by {@link Broker.reclaimStaleLock} when a dead owner's lock is renamed aside. */
@@ -203,6 +269,17 @@ export declare class Broker {
     readonly ledger: LifecycleLedger;
     discovery: BrokerDiscovery | null;
     constructor(settings: BrokerSettings);
+    /** Host capability validation is live-only; no request material is retained. */
+    verifyMasterCapability(ownerSessionId: string, rawCapability: string, attestationEpoch: string): Promise<{
+        allowed: boolean;
+    }>;
+    /**
+     * Replays pending exact closes, then reaps children after confirmed master
+     * loss. Orphan clocks survive recovery and expiry converges through the same
+     * exact close path for only the matching owned child.
+     */
+    /** Deterministic single reap pass; used by maintenance paths and tests. */
+    reapSpawnOrphansOnce(): Promise<void>;
     runStartup<T>(queueWaitMs: number, timing: StartupAdmissionTiming, task: (admittedAt: number) => Promise<T>): Promise<StartupAdmissionResult<T>>;
     start(): Promise<BrokerDiscovery>;
     get ownsDiscovery(): boolean;

package/dist/types/sdk/broker/endpoint-authority.d.ts

@@ -0,0 +1,24 @@
+import * as fs from "node:fs/promises";
+export type EndpointFileRead = {
+    source: string;
+    dev: bigint;
+    ino: bigint;
+    nlink: bigint;
+    size: bigint;
+    mtimeNs: bigint;
+    mtimeMs: number;
+};
+export type EndpointAuthorityFilesystem = Pick<typeof fs, "open">;
+export type IndexedEndpointAuthority = {
+    endpointMtimeMs?: number;
+    endpointFileId?: string;
+};
+/**
+ * Reads one endpoint from the descriptor opened for its pathname. The opened
+ * object must remain a small, singly-linked regular file with stable identity
+ * and metadata for the whole read; a pathname replacement cannot affect the
+ * bytes returned by this function.
+ */
+export declare function readEndpointFile(filePath: string, filesystem?: EndpointAuthorityFilesystem): Promise<EndpointFileRead | undefined>;
+/** Match a descriptor-bound endpoint read to the index representation. */
+export declare function matchesIndexedEndpointFile(file: Pick<EndpointFileRead, "dev" | "ino" | "mtimeMs">, authority: IndexedEndpointAuthority): boolean;

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

@@ -61,6 +61,7 @@ interface ReapTiming {
     gracefulMs: number;
     killVerifyMs: number;
 }
+type BrokerOwnerIdentity = Pick<BrokerDiscovery, "ownerId" | "pid" | "incarnation">;
 /** 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. */
@@ -73,6 +74,8 @@ export declare function startFixtureBrokerWithLeaseForTest(settings: EnsureBroke
 export declare function startFixtureBrokerCommandWithLeaseForTest(command: FixtureBrokerCommand): StartedFixtureBrokerCommand;
 /** Test hook: returns a stop handle for the detached broker this process spawned. */
 export declare function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined;
+/** Test hook: verifies the complete broker owner identity used during stale retirement. */
+export declare function brokerOwnerIdentityMatchesForTest(left: BrokerOwnerIdentity | null, right: BrokerOwnerIdentity): boolean;
 /** 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. */

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

@@ -4,6 +4,9 @@ export * from "./ensure";
 export * from "./identity";
 export * from "./lifecycle";
 export * from "./lifecycle-ledger";
+export * from "./master-capability";
 export * from "./session-index";
+export * from "./spawn-authority";
+export * from "./spawn-substrate";
 export * from "./startup-budget";
 export * from "./transport";

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

@@ -43,6 +43,7 @@ export interface LifecycleDurableEffectsReceipt {
         cwdDigest: string;
         created: boolean;
         reused: boolean;
+        createdBranch: boolean;
         branchDigest?: string;
     };
     transcript?: {
@@ -50,6 +51,11 @@ export interface LifecycleDurableEffectsReceipt {
         contentDigest: string;
     };
     startup?: LifecycleStartupFailureReceipt;
+    timings?: {
+        worktreePreparationMs?: number;
+        dependencyPreparationMs?: number;
+        spawnAuthorizedAtOffsetMs?: number;
+    };
     digest?: string;
 }
 export interface LifecycleLedgerEntry {

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

@@ -1,10 +1,12 @@
 import { type ChildProcess } from "node:child_process";
+import { type GjcLaunchWorktreePlan } from "../../gjc-runtime/launch-worktree";
 import type { SessionLifecycleMcpServer } from "../acp/mcp";
 import { type SdkStartupFailure, type SdkStartupRollbackResult } from "../startup-capability";
 import type { Broker, BrokerCleanupEvidence, 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";
+import { type IndexedSession } from "./session-index";
 export { type ProcessIncarnationCommandRunner, type ProcessIncarnationOptions, parseDarwinProcessIncarnation, processIncarnation, };
 export declare function terminalUncertainStartupMessage(response: BrokerResponse): string;
 export declare function waitForChildSpawn(spawned: Pick<ChildProcess, "off" | "on" | "once">, onPostSpawnError?: (error: Error) => void): Promise<void>;
@@ -25,10 +27,22 @@ type LifecycleCommand = SdkInternalSpawnCommand | {
     args: string[];
 };
 type LifecycleCommandResolver = () => LifecycleCommand;
+type EnsureLaunchWorktreeForTest = (plan: GjcLaunchWorktreePlan, opts: {
+    signal: AbortSignal;
+    deadlineAt: number;
+}) => Promise<SessionLifecycleWorktreeReceipt & {
+    createdBranch: boolean;
+}>;
+type EnsureReusableNodeModulesForTest = (sourceRoot: string, worktreePath: string, opts: {
+    signal: AbortSignal;
+    deadlineAt: number;
+}) => Promise<"symlink" | "present" | "missing">;
 /** Test-only hook for simulating a crash immediately after one exact lifecycle detach. */
 export declare function setLifecycleCleanupHookForTest(broker: Broker, hook: (() => void) | undefined): void;
 export declare function setLifecycleCommandResolverForTest(broker: Broker, resolver: LifecycleCommandResolver | undefined): void;
 export declare function setLifecycleTimingForTest(broker: Broker, timing: LifecycleTiming | undefined): void;
+export declare function setEnsureLaunchWorktreeForTest(_broker: Broker | undefined, fn?: EnsureLaunchWorktreeForTest | undefined): void;
+export declare function setEnsureReusableNodeModulesForTest(_broker: Broker | undefined, fn?: EnsureReusableNodeModulesForTest | undefined): void;
 /** Deterministic platform seam for Windows-only ready-then-exit tolerance. */
 export declare function setLifecycleHostPlatformForTest(platform: NodeJS.Platform | undefined): void;
 export declare function readyThenExitToleranceEnabledForTest(): boolean;
@@ -44,6 +58,7 @@ export interface SessionLifecycleWorktreeReceipt {
     cwd: string;
     created: boolean;
     reused: boolean;
+    createdBranch: boolean;
     branch?: string;
 }
 export interface SessionLifecycleTranscriptIdentity {
@@ -111,12 +126,35 @@ export type SessionLifecycleLaunchRequest = SessionLifecycleLaunchRequestBase &
 });
 export declare function readSessionLifecycleLaunchRequest(value: string | undefined, now?: number): SessionLifecycleLaunchRequest;
 type CleanupEvidence = BrokerCleanupEvidence;
+export declare function validateBrokerModelPresetSync(agentDir: string, requestedProfile: string): string | BrokerResponse;
 export declare function validateBrokerModelPresetForTest(agentDir: string, requestedProfile: string): string | BrokerResponse;
 /** Test seam: the session-host command override as resolved from trusted env. */
 export declare function sdkSessionCommandOverrideForTest(): {
     file: string;
     args: string[];
 } | undefined;
+/**
+ * Reuses the ordinary lifecycle host bootstrap without performing its direct
+ * process spawn. Broker-owned substrate providers receive this exact argv and
+ * split inherited/child-specific environment contract as their only launch
+ * authority for session.spawn.
+ */
+export type SpawnChildHostLaunch = {
+    childId: string;
+    cwd: string;
+    stateRoot: string;
+    argv: readonly string[];
+    inheritedEnv: Readonly<Record<string, string>>;
+    env: Readonly<Record<string, string>>;
+    effectMarker: string;
+};
+export declare function prepareSpawnChildHostLaunch(broker: Broker, input: {
+    cwd: string;
+    modelId?: string;
+    modelPreset?: string;
+    childId?: string;
+    receivedAt?: number;
+}): SpawnChildHostLaunch;
 type EffectMarker = {
     pid: number;
     effectMarker: string;
@@ -187,6 +225,8 @@ export declare function probePublishedReadyAuthorityForTest(root: string, id: st
  * by a reused pid (#4712 review).
  */
 export declare function removeOwnedLifecycleArtifactsForTest(root: string, id: string, expected: EffectMarker): Promise<boolean>;
+/** Test seam for the worktree occupancy boundary. */
+export declare function worktreeOccupantForTest(sessions: IndexedSession[], worktreePath: string, observe?: (pid: number, expectedIncarnation: string | undefined) => ProcessObservation): string | null;
 export declare function canonicalDeleteLocatorPath(pathname: string): string;
 export interface LifecycleExecutionOutcome {
     response: BrokerResponse;

package/dist/types/sdk/broker/master-capability.d.ts

@@ -0,0 +1,10 @@
+import { type IndexedSession, type SessionIndex } from "./session-index";
+import type { MasterCapabilityVerifier } from "./spawn-authority";
+export type SessionEndpoint = {
+    url: string;
+    token: string;
+};
+/** Reads and validates a registered host's authenticated endpoint record. */
+export declare function readEndpoint(record: IndexedSession): Promise<SessionEndpoint | undefined>;
+/** Creates the ephemeral effective-host verifier used by broker spawn admission. */
+export declare function createMasterCapabilityVerifier(index: SessionIndex): MasterCapabilityVerifier;

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

@@ -1,4 +1,4 @@
-import { SDK_STATE_VERSION } from "./state-version";
+import { SDK_STATE_VERSION, SESSION_INDEX_EVENT_VERSION } from "./state-version";
 export type SessionIndexEventType = "host_registered" | "host_heartbeat" | "host_unregistered" | "lifecycle_started" | "lifecycle_terminal" | "session_closed" | "session_deleted" | "record_reconciled";
 export type SessionActivityState = "active" | "idle";
 /** Coalesced broker-owned heartbeat checkpoint (C2): state plus the observation time. */
@@ -28,15 +28,41 @@ export interface SessionIndexProcessObservation {
     readonly incarnation: string;
     readonly isRunning: () => boolean;
 }
+/**
+ * Canonical location facts for one SDK session.
+ *
+ * `cwd` is always a realpath-canonicalized directory. `worktreeRoot` is the
+ * canonical Git worktree root when `cwd` is in a worktree, otherwise `null`.
+ * `stateRoot` retains its host-provided authority spelling and is never derived
+ * from either canonical path.
+ */
+export type SessionLocatorV2 = {
+    cwd: string;
+    worktreeRoot: string | null;
+    stateRoot: string;
+};
+/** Durable master-role facts. `attestationEpoch` is opaque random broker state. */
+export type MasterRoleAttestationV2 = {
+    version: 2;
+    ownerSessionId: string;
+    launchPid: number;
+    launchProcessIncarnation: string;
+    role: "master";
+    attestationEpoch: string;
+};
+export declare function newMasterAttestationEpoch(): string;
+/** Canonicalize a cwd without making an unavailable path a launch failure. */
+export declare function canonicalSessionCwd(cwd: string): Promise<string>;
+/** Resolve the canonical worktree root; non-Git and probe failures are `null`. */
+export declare function sessionWorktreeRoot(cwd: string): Promise<string | null>;
+/** Build the only permitted locator shape for a newly registered session. */
+export declare function resolveSessionLocator(cwd: string, stateRoot: string): Promise<SessionLocatorV2>;
 export interface SessionIndexEvent {
-    version: typeof SDK_STATE_VERSION;
+    version: typeof SDK_STATE_VERSION | typeof SESSION_INDEX_EVENT_VERSION;
     indexSeq: number;
     type: SessionIndexEventType;
     sessionId: string;
-    locator: {
-        repo: string;
-        stateRoot: string;
-    };
+    locator: SessionLocatorV2;
     endpointGeneration: number;
     pid: number;
     /**
@@ -47,26 +73,28 @@ export interface SessionIndexEvent {
      */
     processIncarnation?: string;
     endpointMtimeMs?: number;
+    /** Immutable endpoint file identity captured by the broker at registration. */
+    endpointFileId?: string;
     lifecycleRequestId?: string;
     terminalUncertain?: boolean;
     /** OS process incarnation (C1); absent on legacy v1/v2 events. */
     hostIncarnation?: string;
     /** Present on host_heartbeat checkpoints (C2). */
     activity?: SessionActivity;
+    masterRole?: MasterRoleAttestationV2;
     ts: number;
     checksum: string;
 }
 export interface IndexedSession {
     sessionId: string;
-    locator: {
-        repo: string;
-        stateRoot: string;
-    };
+    locator: SessionLocatorV2;
     endpointGeneration: number;
     pid: number;
     /** OS start incarnation of `pid` as published by its own host at registration. */
     processIncarnation?: string;
     endpointMtimeMs?: number;
+    /** Immutable endpoint file identity captured by the broker at registration. */
+    endpointFileId?: string;
     live: boolean;
     indexSeq: number;
     lifecycleRequestId?: string;
@@ -76,6 +104,7 @@ export interface IndexedSession {
     activity?: SessionActivity;
     /** Wall-clock timestamp of the latest admitted heartbeat, when one exists. */
     lastHeartbeatAt?: number;
+    masterRole?: MasterRoleAttestationV2;
     /** True when more than one unresolved authority-fencing state-root identity claims this session id. */
     ambiguous: boolean;
     /** True when the identity's latest event is terminal (DR-1 retains stopped rows for inspection/offline tail). */
@@ -118,7 +147,7 @@ export interface SessionIndexRepairResult extends SessionIndexDiagnosis {
     quarantinePath?: string;
 }
 /** Admission-fence rejection codes recorded in the durable index audit (C5/C4). */
-export type SessionIndexAuditCode = "rejected_superseded_incarnation" | "rejected_after_tombstone";
+export type SessionIndexAuditCode = "rejected_superseded_incarnation" | "rejected_after_tombstone" | "rejected_legacy_locator";
 export interface SessionIndexAuditRecord {
     version: typeof SDK_STATE_VERSION;
     code: SessionIndexAuditCode;

package/dist/types/sdk/broker/session-scope.d.ts

@@ -0,0 +1,72 @@
+import { type SessionLocatorV2 } from "./session-index";
+export type ScopeNameV1 = "repo" | "pwd" | "global";
+export type ScopeRequestV1 = {
+    version: 1;
+    requested: ScopeNameV1;
+    requestAnchor: {
+        cwd: string;
+        worktreeRoot: string | null;
+    };
+};
+export type ResolvedScopeV1 = {
+    version: 1;
+    requested: ScopeNameV1;
+    requestAnchor: {
+        cwd: string;
+        worktreeRoot: string | null;
+    };
+    resolved: {
+        kind: "repo";
+        worktreeRoot: string;
+    } | {
+        kind: "pwd";
+        cwd: string;
+    } | {
+        kind: "global";
+        visibility: "current-broker";
+    } | null;
+    resolution: "resolved" | "not-in-git-worktree";
+};
+export type SdkSearchRowV1 = {
+    id: string;
+    locator: {
+        cwd: string;
+        worktreeRoot: string | null;
+        stateRoot: string;
+    };
+    live: boolean;
+    probe?: "reachable" | "unreachable" | "stale";
+};
+export type SdkSearchResultV1 = {
+    version: 1;
+    scope: ResolvedScopeV1;
+    status: "populated" | "empty" | "not-in-git-worktree" | "unavailable";
+    observedAt: string;
+    indexSeq?: number;
+    rows: readonly SdkSearchRowV1[];
+    cursor?: string;
+    warnings: readonly string[];
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+export declare class ScopeRequestValidationError extends Error {
+    constructor(message: string);
+}
+/** Strictly validates the versioned request shape before canonical resolution. */
+export declare function scopeRequestV1(value: unknown): ScopeRequestV1 | undefined;
+/** Strictly validates a resolved descriptor returned by Broker pages. */
+export declare function resolvedScopeV1(value: unknown): ResolvedScopeV1 | undefined;
+/** Strictly validates a safe broker-search row. */
+export declare function sdkSearchRowV1(value: unknown): SdkSearchRowV1 | undefined;
+/** Strictly validates the aggregate credential-free search envelope. */
+export declare function sdkSearchResultV1(value: unknown): SdkSearchResultV1 | undefined;
+/** Resolves and validates an anchor against its canonical cwd worktree identity. */
+export declare function resolveScopeRequest(request: ScopeRequestV1): Promise<ResolvedScopeV1>;
+export declare function scopeMatchesLocator(scope: ResolvedScopeV1, locator: Pick<SessionLocatorV2, "cwd" | "worktreeRoot">): boolean;
+export declare function searchRowV1(session: {
+    sessionId: string;
+    locator: SessionLocatorV2;
+    live: boolean;
+}): SdkSearchRowV1;