@gajae-code/coding-agent 0.15.5 → 0.16.0

package/dist/types/modes/components/frictionless-onboarding-selector.d.ts

@@ -1,5 +1,15 @@
 import { Container } from "@gajae-code/tui";
 import type { OnboardingProfile } from "../../setup/frictionless-onboarding";
+import { type UiLanguage } from "../ui-language";
+export declare const UI_LANGUAGE_CHOICES: readonly {
+    value: UiLanguage;
+    label: string;
+}[];
+export declare class InterfaceLanguageSelectorComponent extends Container {
+    #private;
+    constructor(onSelect: (language: UiLanguage) => void, onCancel: () => void);
+    handleInput(keyData: string): void;
+}
 export type FrictionlessOnboardingAction = "analyze" | "apply" | "skip" | "later" | "manual" | "manual-migration" | "manual-learn";
 export type FrictionlessOnboardingStage = "disclosure" | "manual" | "preview";
 export interface FrictionlessOnboardingCopy {

package/dist/types/modes/components/jobs-overlay-model.d.ts

@@ -7,10 +7,11 @@
  */
 import type { SelectItem } from "@gajae-code/tui";
 import type { JobsSnapshot } from "../jobs-observer";
-export type JobRefKind = "monitor" | "cron";
+export type JobRefKind = "monitor" | "cron" | "folded";
 export interface JobRef {
     kind: JobRefKind;
     id: string;
+    generation?: string;
 }
 /** Compact relative time, e.g. "in 5m", "2m ago", "now". */
 export declare function formatRelative(targetMs: number | undefined, nowMs?: number): string;
@@ -18,7 +19,8 @@ export declare function formatRelative(targetMs: number | undefined, nowMs?: num
 export declare function parseJobRef(value: string): JobRef | null;
 /**
  * Build the grouped jobs list: monitors first (newest-first), then crons
- * (newest-first). The snapshot arrays are already sorted newest-first.
+ * (newest-first), then read-only folded jobs. The snapshot arrays are already
+ * sorted newest-first where a source has a timestamp.
  */
 export declare function buildJobsListItems(snapshot: JobsSnapshot): SelectItem[];
 /**

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

@@ -14,6 +14,7 @@ export declare class OAuthSelectorComponent extends Container {
     #private;
     constructor(mode: "login" | "logout", authStorage: AuthStorage, onSelect: (providerId: string) => void, onCancel: () => void, options?: {
         validateAuth?: (providerId: string) => Promise<boolean>;
+        onValidationError?: (error: unknown) => boolean;
         requestRender?: () => void;
         externalCredentialCandidates?: ImportableCredential[];
     } & Partial<OAuthSelectorAccountOptions>);

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

@@ -0,0 +1,18 @@
+/**
+ * Shortest recognizable model label, derived purely from the model id.
+ *
+ * The rail and the footer both render this form, so a narrow terminal spends
+ * its cells on the part of the id that actually identifies the model:
+ *
+ *   `anthropic/claude-sonnet-4-5-20250929` -> `sonnet-4.5`
+ *   `openai/gpt-4o-2024-05-13`             -> `gpt-4o`
+ *   `google/gemini-3-pro`                  -> `gemini-3-pro`
+ *   `qwen2.5:7b`                           -> `qwen2.5:7b`
+ *
+ * Deliberately a pure heuristic with no curated override table: every provider
+ * in `models.json` must degrade sanely without per-model maintenance. The
+ * function never returns an empty string — an id that the heuristic would
+ * strip to nothing falls back to the previous, longer form.
+ */
+export declare const NO_MODEL_LABEL = "no-model";
+export declare function shortenModelId(rawId: string | undefined | null): string;

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

@@ -0,0 +1,34 @@
+/**
+ * Narrow-width survival row for the status rail.
+ *
+ * The rail evicts segments continuously as the terminal narrows. Without this
+ * row the last thing left at very small widths is the `…+N` overflow marker —
+ * the three things a user actually needs (how much context is left, whether a
+ * goal is running, which model is answering) are exactly what the generic
+ * eviction throws away first or last by accident.
+ *
+ * This row keeps them, in priority order, by stepping each item down its own
+ * ladder instead of dropping it:
+ *
+ *   full form -> shortened form -> single glyph -> dropped
+ *
+ * Context % is never dropped and is the last survivor; the model name is
+ * dropped first of the three. The row is rendered as bare colored text with no
+ * group padding or end caps, so — like the overflow marker — it can survive at
+ * widths where a normal segment group cannot.
+ */
+import type { SegmentContext } from "./types";
+/** Which priority items the active layout is supposed to be carrying. */
+export interface PriorityItemSet {
+    context: boolean;
+    goal: boolean;
+    model: boolean;
+}
+/**
+ * Widest priority row that fits `width`, or null when even the minimal form
+ * cannot fit (callers then fall back to the overflow marker).
+ *
+ * Returns null when neither context nor goal is available: the model name alone
+ * is the lowest-priority item and never justifies replacing the normal rail.
+ */
+export declare function buildPriorityRow(ctx: SegmentContext, width: number, include: PriorityItemSet): string | null;

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

@@ -14,11 +14,43 @@
  */
 import type { AsyncJob, AsyncJobManager } from "../async";
 export type JobsWorstState = "none" | "running" | "failed";
+export type JobDeliveryState = "pending" | "delivered" | "failed-visible";
+/** The manager-owned, one-pass job projection consumed by this observer. */
+export interface AsyncJobSnapshotEntry {
+    id: string;
+    kind: string;
+    label: string;
+    status: AsyncJob["status"];
+    generation: string;
+    backgrounded: boolean;
+    deliveryState: JobDeliveryState;
+}
+/** Scalar delivery failure evidence that may outlive the AsyncJob record. */
+export interface DeadLetteredJobSnapshotEntry {
+    jobId: string;
+    generation: string;
+    ownerId?: string;
+    backgrounded?: boolean;
+    attempt: number;
+    lastError?: string;
+    recordedAt: number;
+}
+export interface AsyncJobsSnapshot {
+    jobs: AsyncJobSnapshotEntry[];
+    deadLettered: DeadLetteredJobSnapshotEntry[];
+}
 export interface MonitorJobView {
     id: string;
     label: string;
     status: AsyncJob["status"];
     startTime: number;
+    generation?: string;
+    backgrounded?: boolean;
+    deliveryState?: JobDeliveryState;
+}
+export interface FoldedJobView extends AsyncJobSnapshotEntry {
+    /** Safe diagnostic retained for a dead-lettered delivery, when available. */
+    errorText?: string;
 }
 export interface CronJobView {
     id: string;
@@ -34,6 +66,10 @@ export interface CronJobView {
 export interface JobsSnapshot {
     monitors: MonitorJobView[];
     crons: CronJobView[];
+    /** Backgrounded work and undeliverable terminal work that must stay visible. */
+    foldedJobs?: FoldedJobView[];
+    /** Scalar dead-letter evidence retained for diagnostics and red-drill-in. */
+    deadLettered?: DeadLetteredJobSnapshotEntry[];
     activeMonitorCount: number;
     activeCronCount: number;
     worstState: JobsWorstState;

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/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

@@ -1,9 +1,11 @@
 import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
 import type { ModelProfileErrorDetails } from "../../config/model-profile-contract";
+import { type SdkHostModelResolver } from "../host/model-pin";
 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;
@@ -11,6 +13,16 @@ 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;
 }
 type ResolvedBrokerSettings = {
     agentDir: string;
@@ -18,6 +30,10 @@ 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 type BrokerCleanupIdentity = {
@@ -112,7 +128,7 @@ export type BrokerResponse = {
     error: {
         code: BrokerErrorCode;
         message: string;
-        details?: ModelProfileErrorDetails;
+        details?: ModelProfileErrorDetails | SpawnSubstrateFailure;
         endpoint?: "unavailable";
         cleanup?: BrokerCleanupEvidence;
     };
@@ -120,6 +136,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. */
@@ -200,6 +268,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/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.d.ts

@@ -5,6 +5,7 @@ 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>;
@@ -111,12 +112,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 +211,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;