@gajae-code/coding-agent 0.11.2 → 0.11.4

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## [Unreleased]
 
+## [0.11.4] - 2026-07-20
+### Added
+- Bracketed pastes containing complete lists of saved static-image paths can now attach up to 16 images in source order after explicit confirmation. Paste transactions are cancellation-safe, disabled in command modes, enforce source, encoded-output, dimension, and decoded-memory budgets before commit, reject animated, remote, linked, or path-swapped sources, and restore the literal paste on cancellation or failure.
+- Rich tool-call rendering in the transcript viewer: both the session-observer and main-session transcript viewers now share one formatter so tool calls render identically (args summary + intent, then a result block with ✓ done / ✗ error / ⏳ pending states). Fixes a latent bug where a tool call with no result rendered as a false "✓ done"; expanded results cap at 100 source lines with raw/copy exposing the full text (#2656).
+
+### Changed
+- Updated the Kimi Coding Plan Eco, Medium, and Pro presets to Kimi K3 with its supported `low`, `high`, and `max` reasoning efforts.
+
+### Removed
+- Removed the legacy worktree cleanup implementation behind the `@gajae-code/coding-agent/cli/worktree-cli` and `@gajae-code/coding-agent/commands/worktree` package subpaths (base and `.js` forms). The `gjc worktree`/`wt` CLI command has been unregistered since the workflow-surface narrowing; the modules behind it (including the recursive-deletion `clear` path) were only reachable as package imports. The subpaths now resolve to throwing tombstone modules whose error explains the deliberate removal and the supported replacement: inspect leftover managed worktrees under `~/.gjc/wt` manually and use `git worktree remove` / `git worktree prune`.
+
+### Fixed
+- Telegram `/btw` rich-delivery E2E coverage now awaits native and daemon teardown ownership, records exact per-iteration lifecycle phases, and uses an internal exact-tuple terminal-delivery receipt to keep fallback stress deterministic under shard load without extending the original test timeout.
+- Malformed spurious Round-0 review metadata no longer blocks an otherwise valid locked-intent question/gate, while durable intent safety remains fail-closed (#2643).
+- Restricted role-agent `gjc state` command authorization now fails closed on argv-classification disagreement: one shared manifest-aware native state argv grammar (action names, flag arity, positionals, effective modifiers, selector candidates) is consumed by both runtime dispatch and the policy boundary, which rejects ambiguous selectors, malformed flags, destructive actions, and file-backed input (#2665).
+- Browser tab workers now bootstrap through their actual isolated entry without accidentally loading native bindings through broad imports, and startup fails closed instead of falling back to unguarded inline execution; compiled/package smoke now exercises the tab worker, with a PR-head darwin-arm64 CI gate (#2598).
+- Added evidence-preserving recovery for legacy multi-writer SDK session-index corruption: `gjc gc` now diagnoses corrupt prefixes, `--repair-session-index` quarantines the original snapshot/log under the session-index lock before atomically restoring only the checksum-valid monotonic prefix, and append failures point operators to the explicit repair path (#2654).
+- Malformed selectors on internal read URLs now fail explicitly instead of silently falling back to an unbounded resource read.
+- Newly registered earlier resource-GC policies advance the pending sweep without postponing an already earlier sweep.
+- Provider onboarding wizard completion is now deterministic under CI load: duplicate in-flight confirmation is suppressed, success tests await the real refresh/notification/status boundary instead of fixed sleeps, and the newly configured model is verified through the subsequent model selector.
+- OpenAI-compatible web search now turns malformed successful response bodies into bounded provider errors while preserving normal provider fallback (#2593).
+- Windows session storage now keeps a symlink-resolved drive-letter path for Bun filesystem I/O instead of a native Volume GUID identity path, preventing `ENOENT` failures during resident-cache writes that could drop the final assistant message at turn completion.
+- On platforms with verified retained publication identity support, detached SDK broker processes now stop after durable loss or replacement of their owned publication while preserving warm reuse and protocol/state formats (#2583). Bounded-practical limitation: requests admitted before the first definitive loss observation—or after authoritative same-object recovery and before a later loss observation—may still perform pathname-based index, ledger, lifecycle, cleanup, or child effects. A detached session-host child spawned by an admitted request may outlive broker exit and may continue pathname effects for the session lifetime. Broker self-reap does not cancel or signal that child and does not provide absolute hostile replacement isolation.
+
+## [0.11.3] - 2026-07-19
+
+### Changed
+- The `read` tool is now receipt-by-default: bare and unparseable reads return a bounded receipt (≤50 lines / 10 KiB) with a re-read-with-selector footer only when truncated, `:raw` stays pure verbatim up to a max(2 MiB, spill threshold) ceiling, structural summaries cap unit-granularly at 20 KiB while preserving elision and source-recovery footers, and directories are byte/line capped and never spill. Only an explicit full-content selector (`:raw` or an explicit range) with real content is spill-eligible. Subagent previews now enforce a real byte/code-point cap via per-shape render budgets plus a shape-aware artifact-eligibility tag enforced centrally in output-meta.
+
+### Fixed
+- Workflow-state handoff no longer self-locks the active-state cache, so a same-turn skill handoff (e.g. ultragoal → ralplan) completes instead of stalling behind a lock the handoff itself still holds (#2638).
+- SDK host shutdown now retries a failed broker unregister instead of short-circuiting with a stale broker-index entry, while retained startup-cleanup owner-release failures remain isolated from the red extension-error path (#2625).
+- Non-TTY launches now fail fast when stdin is empty and automatically use print mode for positional prompts and `@file` inputs, preventing orphaned interactive TUI processes (#2507).
+
 ## [0.11.2] - 2026-07-19
 
 ### Changed

package/dist/types/cli/launch-disposition.d.ts

@@ -0,0 +1,23 @@
+export type LaunchMode = "text" | "json" | "acp";
+export interface LaunchDisposition {
+    autoPrint: boolean;
+    isInteractive: boolean;
+    /** Set when an interactive launch is impossible (non-TTY stdin, nothing to run). */
+    nonInteractiveError?: string;
+}
+/**
+ * Decides between interactive, auto-print, and fail-fast launches.
+ *
+ * A non-TTY stdin means the TUI can never receive input, so an interactive
+ * launch would execute the initial prompt and then block in the event loop
+ * forever. Prepared command-line input degrades to print mode; without any
+ * input to run we fail fast instead of hanging. Explicit `--print` and
+ * `--mode` launches are left untouched.
+ */
+export declare function resolveLaunchDisposition(args: {
+    stdinIsTTY: boolean | undefined;
+    pipedInput: string | undefined;
+    hasPreparedInput: boolean;
+    print: boolean;
+    mode: LaunchMode | undefined;
+}): LaunchDisposition;

package/dist/types/cli/worktree-cli.d.ts

@@ -1,26 +1,9 @@
-type WorktreeKind = "pr-checkout" | "task-isolation" | "empty" | "stray";
-export interface WorktreeEntry {
-    /** Absolute path to the worktree dir (or stray container) under `~/.gjc/wt/`. */
-    path: string;
-    /** Classification of what we found on disk. */
-    kind: WorktreeKind;
-    /** Parent repo root, when this is a registered git worktree. */
-    parentRepo?: string;
-    /** Branch name extracted from the parent's tracking file, when available. */
-    branch?: string;
-    /** When set, the entry is unhealthy and `gjc worktree clear` will remove it. */
-    orphanReason?: string;
-}
-export interface ListWorktreesOptions {
-    json: boolean;
-}
-export interface ClearWorktreesOptions {
-    /** Remove every entry, including live PR-checkout worktrees. */
-    all: boolean;
-    /** Print what would be removed without touching the filesystem. */
-    dryRun: boolean;
-    json: boolean;
-}
-export declare function listWorktrees(options: ListWorktreesOptions): Promise<void>;
-export declare function clearWorktrees(options: ClearWorktreesOptions): Promise<void>;
+/**
+ * Tombstone for the removed legacy worktree cleanup API.
+ *
+ * The recursive-deletion implementation that previously lived here
+ * (`listWorktrees`/`clearWorktrees`) was deliberately removed and does not
+ * come back through this subpath. This module exists only to fail imports
+ * with actionable migration guidance.
+ */
 export {};

package/dist/types/commands/gc.d.ts

@@ -20,6 +20,10 @@ export default class Gc extends Command {
             description: string;
             default: boolean;
         };
+        "repair-session-index": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
     };
     static examples: string[];
     run(): Promise<void>;

package/dist/types/commands/worktree.d.ts

@@ -1,34 +1,9 @@
 /**
- * List and clean up agent-managed git worktrees under `~/.gjc/wt`.
+ * Tombstone for the removed legacy `worktree` CLI command module.
+ *
+ * The `gjc worktree`/`wt` command was unregistered during the
+ * workflow-surface narrowing and its implementation was deliberately
+ * removed. This module exists only to fail imports with actionable
+ * migration guidance.
  */
-import { Command } from "@gajae-code/utils/cli";
-export default class Worktree extends Command {
-    static description: string;
-    static aliases: string[];
-    static args: {
-        action: import("@gajae-code/utils/cli").ArgDescriptor & {
-            description: string;
-            required: false;
-            options: string[];
-            default: string;
-        };
-    };
-    static flags: {
-        all: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            description: string;
-            default: boolean;
-        };
-        "dry-run": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            char: string;
-            description: string;
-            default: boolean;
-        };
-        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            char: string;
-            description: string;
-            default: boolean;
-        };
-    };
-    static examples: string[];
-    run(): Promise<void>;
-}
+export {};

package/dist/types/config/settings-schema.d.ts

@@ -662,15 +662,15 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "tools.readArtifactSpillThreshold": {
         readonly type: "number";
-        readonly default: 0;
+        readonly default: 256;
         readonly ui: {
             readonly tab: "tools";
-            readonly label: "Experimental read-tool artifact spill threshold (KB)";
-            readonly description: "Advanced opt-in only: combined-size cap for `read` output across all requested ranges. Above this the full output is saved as an artifact and a bounded head+tail snippet is kept inline. Live layofflabs/gpt-5.5 medium evidence on 2026-07-07 found no token savings and a lower cache-hit rate at 50 KB, so normal coding sessions should leave this Off unless intentionally measuring large-read behavior.";
+            readonly label: "Read artifact spill threshold (KB)";
+            readonly description: "Explicit large reads above this combined size are saved as an artifact with a bounded head-and-tail snippet inline. Bare reads, directories, and converted-document receipts remain inline.";
             readonly options: readonly [{
                 readonly value: "0";
                 readonly label: "Off";
-                readonly description: "Default; no read-specific spill (backstop only)";
+                readonly description: "No read-specific spill (backstop only)";
             }, {
                 readonly value: "50";
                 readonly label: "50 KB";
@@ -682,7 +682,7 @@ export declare const SETTINGS_SCHEMA: {
             }, {
                 readonly value: "256";
                 readonly label: "256 KB";
-                readonly description: "~64K tokens";
+                readonly description: "Default; ~64K tokens";
             }, {
                 readonly value: "512";
                 readonly label: "512 KB";
@@ -696,11 +696,11 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "tools.fileMentionInlineBytes": {
         readonly type: "number";
-        readonly default: 20;
+        readonly default: 10;
         readonly ui: {
             readonly tab: "tools";
             readonly label: "File-mention inline cap (KB)";
-            readonly description: "Inline byte cap for auto-read `@path` file mentions, deliberately below the read-tool cap so an incidental mention injects a smaller snippet than an explicit read. The full file is still available via the read tool.";
+            readonly description: "Inline byte cap for auto-read `@path` file mentions, aligned with the 10 KiB bare-read receipt so incidental mentions stay within the same bounded context budget. The full file is still available via the read tool.";
             readonly options: readonly [{
                 readonly value: "5";
                 readonly label: "5 KB";
@@ -708,15 +708,15 @@ export declare const SETTINGS_SCHEMA: {
             }, {
                 readonly value: "10";
                 readonly label: "10 KB";
-                readonly description: "~2.5K tokens";
+                readonly description: "Default; ~2.5K tokens";
             }, {
                 readonly value: "20";
                 readonly label: "20 KB";
-                readonly description: "Default; ~5K tokens";
+                readonly description: "~5K tokens";
             }, {
                 readonly value: "50";
                 readonly label: "50 KB";
-                readonly description: "~12.5K tokens (matches read cap)";
+                readonly description: "~12.5K tokens (matches bare-read receipt)";
             }];
         };
     };
@@ -2437,6 +2437,81 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
+    readonly "read.receiptBudgetLines": {
+        readonly type: "number";
+        readonly default: 50;
+        readonly ui: {
+            readonly tab: "editing";
+            readonly label: "Read Receipt Line Budget";
+            readonly description: "Maximum lines included in a bare read receipt before a selector footer is shown";
+            readonly options: readonly [{
+                readonly value: "25";
+                readonly label: "25 lines";
+            }, {
+                readonly value: "50";
+                readonly label: "50 lines";
+                readonly description: "Default";
+            }, {
+                readonly value: "100";
+                readonly label: "100 lines";
+            }, {
+                readonly value: "200";
+                readonly label: "200 lines";
+            }];
+        };
+    };
+    readonly "read.receiptBudgetBytes": {
+        readonly type: "number";
+        readonly default: 10;
+        readonly ui: {
+            readonly tab: "editing";
+            readonly label: "Read Receipt Byte Budget (KB)";
+            readonly description: "Maximum UTF-8 body size for a bare read receipt before a selector footer is shown";
+            readonly options: readonly [{
+                readonly value: "5";
+                readonly label: "5 KB";
+                readonly description: "~1.25K tokens";
+            }, {
+                readonly value: "10";
+                readonly label: "10 KB";
+                readonly description: "Default; ~2.5K tokens";
+            }, {
+                readonly value: "20";
+                readonly label: "20 KB";
+                readonly description: "~5K tokens";
+            }, {
+                readonly value: "50";
+                readonly label: "50 KB";
+                readonly description: "~12.5K tokens";
+            }];
+        };
+    };
+    readonly "read.summaryMaxBytes": {
+        readonly type: "number";
+        readonly default: 20;
+        readonly ui: {
+            readonly tab: "editing";
+            readonly label: "Read Summary Size Budget (KB)";
+            readonly description: "Maximum UTF-8 size for a structural read summary before additional units are elided";
+            readonly options: readonly [{
+                readonly value: "10";
+                readonly label: "10 KB";
+                readonly description: "~2.5K tokens";
+            }, {
+                readonly value: "20";
+                readonly label: "20 KB";
+                readonly description: "Default; ~5K tokens";
+            }, {
+                readonly value: "50";
+                readonly label: "50 KB";
+                readonly description: "~12.5K tokens";
+            }, {
+                readonly value: "100";
+                readonly label: "100 KB";
+                readonly description: "~25K tokens";
+            }];
+        };
+    };
     readonly "read.summarize.enabled": {
         readonly type: "boolean";
         readonly default: true;

package/dist/types/gjc-runtime/gc-runtime.d.ts

@@ -95,11 +95,20 @@ export interface GcCounts {
         failed: number;
     }>;
 }
+export interface GcSessionIndexHealth {
+    status: "healthy" | "corrupt" | "repaired" | "unsupported" | "repair_failed";
+    valid_prefix_seq: number;
+    snapshot_seq?: number;
+    reason?: string;
+    quarantine_path?: string;
+}
 export interface GcReport {
     dry_run: boolean;
+    operation?: "dry_run" | "prune" | "repair_session_index";
     stores: Record<GcStore, GcRecord[]>;
     counts: GcCounts;
     errors: GcError[];
+    session_index?: GcSessionIndexHealth;
 }
 export interface GcRunResult {
     stdout: string;

package/dist/types/gjc-runtime/state-argv.d.ts

@@ -0,0 +1,38 @@
+export type StateAction = "read" | "write" | "clear" | "contract" | "handoff" | "graph" | "prune" | "gc" | "migrate" | "status" | "doctor";
+export declare const STATE_ACTION_NAMES: ReadonlySet<StateAction>;
+export declare const STATE_FLAGS_WITH_VALUES: ReadonlySet<string>;
+export declare const STATE_BOOLEAN_FLAGS: ReadonlySet<string>;
+export interface StateFlagOccurrence {
+    name: string;
+    index: number;
+    value?: string;
+    arity: "boolean" | "value";
+    form: "separate" | "attached";
+    malformed: boolean;
+}
+export interface StateSelectorCandidate {
+    source: "mode" | "positional" | "input.mode" | "input.skill";
+    value: string | undefined;
+    index: number;
+}
+export type StateInputKind = "empty" | "inline" | "file" | "invalid";
+export interface StateInputClassification {
+    index: number;
+    raw: string;
+    kind: StateInputKind;
+    selectors: StateSelectorCandidate[];
+}
+export interface StateArgvClassification {
+    argv: readonly string[];
+    action: StateAction;
+    effectiveAction: StateAction;
+    positionalSkill?: string;
+    positionals: readonly string[];
+    flags: readonly StateFlagOccurrence[];
+    unknownFlags: readonly string[];
+    inputs: readonly StateInputClassification[];
+    runtimeSelectorCandidates: readonly StateSelectorCandidate[];
+    selectorCandidates: readonly StateSelectorCandidate[];
+}
+export declare function firstStateFlagValue(classification: StateArgvClassification, name: string): string | undefined;
+export declare function classifyStateArgv(argv: readonly string[]): StateArgvClassification;

package/dist/types/main.d.ts

@@ -118,6 +118,7 @@ export interface RunRootCommandDependencies {
     };
     initTheme?: typeof initTheme;
     readPipedInput?: typeof readPipedInput;
+    stdinIsTTY?: boolean;
     runStartupCredentialAutoImportIfNeeded?: typeof runStartupCredentialAutoImportIfNeeded;
     getChangelogForDisplay?: typeof getChangelogForDisplay;
     createInteractiveMode?: CreateInteractiveMode;

package/dist/types/modes/components/custom-editor.d.ts

@@ -2,6 +2,11 @@ import { Editor, type KeyId } from "@gajae-code/tui";
 import { type AppKeybinding } from "../../config/keybindings";
 type ConfigurableEditorAction = Extract<AppKeybinding, "app.interrupt" | "app.clear" | "app.exit" | "app.suspend" | "app.thinking.cycle" | "app.commandPalette.open" | "app.model.cycleForward" | "app.model.cycleBackward" | "app.model.select" | "app.model.selectTemporary" | "app.tools.expand" | "app.thinking.toggle" | "app.editor.external" | "app.history.search" | "app.message.dequeue" | "app.message.followUp" | "app.message.queue" | "app.clipboard.pasteImage" | "app.clipboard.copyPrompt">;
 type PastePendingClearReason = "timeout" | "queue-limit";
+export interface PasteTextContext {
+    readonly signal: AbortSignal;
+    /** Run one synchronous composer mutation only while this paste transaction is current. */
+    commit(commit: () => boolean): boolean;
+}
 /**
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */
@@ -35,9 +40,9 @@ export declare class CustomEditor extends Editor {
     /** Called when the configured image-paste shortcut is pressed. */
     onPasteImage?: () => Promise<boolean>;
     /** Called before bracketed paste content is inserted. Return true to consume it. */
-    onPasteText?: (text: string) => boolean | Promise<boolean>;
-    /** Called when async paste handling drops queued input instead of replaying it. */
-    onPastePendingInputCleared?: (reason: PastePendingClearReason, droppedInputCount: number) => void;
+    onPasteText?: (text: string, context: PasteTextContext) => boolean | Promise<boolean>;
+    /** Called when pending paste handling is cancelled after restoring queued input. */
+    onPastePendingInputCleared?: (reason: PastePendingClearReason, restoredInputCount: number) => void;
     /** Called when the configured dequeue shortcut is pressed. */
     onDequeue?: () => void;
     /** Called when the configured queue shortcut is pressed. */

package/dist/types/modes/components/tool-transcript-format.d.ts

@@ -0,0 +1,19 @@
+export declare const MAX_TOOL_ARGS_CHARS = 500;
+export declare const TOOL_RESULT_MAX_EXPANDED_LINES = 100;
+type ToolCallFields = {
+    name: string;
+    args: Record<string, unknown>;
+    intent?: string;
+};
+type ToolResultFields = {
+    resultText: string;
+    isError: boolean;
+    hasResult: boolean;
+};
+export type ToolTranscriptFields = ToolCallFields & ToolResultFields;
+export declare function formatToolArgs(name: string, args: Record<string, unknown>): string;
+export declare function composeToolCall({ name, args, intent }: ToolCallFields): string;
+export declare function composeToolResult({ resultText, isError, hasResult }: ToolResultFields): string;
+export declare function composeToolText(fields: ToolTranscriptFields): string;
+export declare function toolDisplayText(fields: ToolTranscriptFields, expanded: boolean): string;
+export {};

package/dist/types/modes/controllers/input-controller.d.ts

@@ -1,13 +1,18 @@
 import { type AutocompleteProvider, type SlashCommand } from "@gajae-code/tui";
 import { type ComposerSubmissionOptions, type InteractiveModeContext } from "../../modes/types";
+import { loadPastedImageBatch } from "../../utils/pasted-image-loading";
 import { ActionRegistry } from "../action-registry";
+import type { PasteTextContext } from "../components/custom-editor";
 export declare const INTERACTIVE_ABORT_CLEANUP_TIMEOUT_MS = 5000;
 export declare const BACKGROUND_FOLD_DOUBLE_PRESS_MS = 750;
+interface InputControllerDependencies {
+    loadPastedImageBatch?: typeof loadPastedImageBatch;
+}
 export declare class InputController {
     #private;
     private ctx;
     readonly actionRegistry: ActionRegistry<void>;
-    constructor(ctx: InteractiveModeContext);
+    constructor(ctx: InteractiveModeContext, dependencies?: InputControllerDependencies);
     setupKeyHandlers(): void;
     setupEditorSubmitHandler(): void;
     submitText(text: string, composer: ComposerSubmissionOptions): Promise<void>;
@@ -28,7 +33,7 @@ export declare class InputController {
     }): number;
     handleBackgroundCommand(): void;
     handleForegroundToolBackgroundFold(): boolean;
-    handleTextPaste(text: string): boolean | Promise<boolean>;
+    handleTextPaste(text: string, context: PasteTextContext): boolean | Promise<boolean>;
     handleImagePaste(): Promise<boolean>;
     createAutocompleteProvider(commands: SlashCommand[], basePath: string): AutocompleteProvider;
     /** Copy the current editor line to the system clipboard. */
@@ -47,3 +52,4 @@ export declare class InputController {
     openExternalEditor(): Promise<void>;
     registerExtensionShortcuts(): void;
 }
+export {};

package/dist/types/modes/prompt-action-autocomplete.d.ts

@@ -30,6 +30,10 @@ export declare class PromptActionAutocompleteProvider implements AutocompletePro
         items: AutocompleteItem[];
         prefix: string;
     } | null>;
+    getForceFileSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
     applyCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
         lines: string[];
         cursorLine: number;

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

@@ -109,6 +109,7 @@ export declare class Broker {
     constructor(settings: BrokerSettings);
     start(): Promise<BrokerDiscovery>;
     get ownsDiscovery(): boolean;
+    get completion(): Promise<void>;
     status(): RedactedBrokerDiscovery | null;
     heartbeat(): Promise<void>;
     stop(): Promise<void>;

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

@@ -1,5 +1,11 @@
 import { processIncarnation } from "./process-incarnation";
 import { SDK_STATE_VERSION } from "./state-version";
+export type BrokerPublicationObservation = "owned" | "absent" | "replaced" | "ambiguous";
+export interface RetainedBrokerDiscovery {
+    observe(): BrokerPublicationObservation;
+    heartbeat(heartbeatAt: number): Promise<boolean>;
+    close(): void;
+}
 export declare const BROKER_HEARTBEAT_TTL_MS = 15000;
 export interface BrokerDiscovery {
     version: typeof SDK_STATE_VERSION;
@@ -26,5 +32,9 @@ 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>;
+/** Publish once by name, then retain no-follow native authority for recurring heartbeats. */
+export declare function publishBrokerDiscovery(agentDir: string, discovery: BrokerDiscoveryWrite, platform?: NodeJS.Platform): Promise<RetainedBrokerDiscovery>;
+/** Heartbeat through retained authority, or the explicit Windows compatibility path. */
+export declare function heartbeatBrokerDiscoveryRetained(publication: RetainedBrokerDiscovery, heartbeatAt: number): Promise<boolean>;
 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

@@ -12,11 +12,28 @@ export interface EnsureBrokerSettings {
     env?: NodeJS.ProcessEnv;
 }
 export interface FixtureBrokerLease {
+    /** Backward-compatible fixture cleanup alias for exact child termination. */
     close(): Promise<void>;
 }
+export interface ExactFixtureBrokerLease extends FixtureBrokerLease {
+    /** Observes the retained child only; it never signals a process. */
+    waitForExit(timeoutMs: number): Promise<boolean>;
+    /** Signals only the retained ChildProcess, never a discovery-derived PID. */
+    terminateExactChild(): Promise<void>;
+}
+export interface FixtureBrokerCommand {
+    file: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface StartedFixtureBrokerCommand {
+    lease: ExactFixtureBrokerLease;
+    control: NodeJS.WritableStream;
+}
 export interface StartedFixtureBroker {
     discovery: BrokerDiscovery;
-    lease: FixtureBrokerLease;
+    lease: ExactFixtureBrokerLease;
 }
 interface BrokerOwner {
     stop(): Promise<void>;
@@ -31,6 +48,12 @@ interface ReapTiming {
 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-only launch surface for topology fixtures. It accepts an already-resolved
+ * command and retains the exact spawned child; no production selection path
+ * reaches this function.
+ */
+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: drives the detached-broker reap on a controllable child surface. */

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

@@ -0,0 +1,3 @@
+import type { Broker } from "./broker";
+/** Wait for broker-local completion, then terminate only the current broker process. */
+export declare function completeBrokerProcess(broker: Broker, exit?: (code: number) => never): Promise<never>;

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

@@ -36,12 +36,24 @@ export interface SessionList {
     sessions: IndexedSession[];
     warnings: string[];
 }
+export interface SessionIndexDiagnosis {
+    status: "healthy" | "corrupt" | "unsupported";
+    validPrefixSeq: number;
+    snapshotSeq: number;
+    reason?: string;
+}
+export interface SessionIndexRepairResult extends SessionIndexDiagnosis {
+    repaired: boolean;
+    quarantinePath?: string;
+}
 export declare const sessionIndexChecksum: (event: Omit<SessionIndexEvent, "checksum">) => string;
 export declare class SessionIndex {
     #private;
     constructor(agentDir: string);
     open(): Promise<this>;
     replay(): Promise<void>;
+    diagnose(): Promise<SessionIndexDiagnosis>;
+    repair(): Promise<SessionIndexRepairResult>;
     refresh(): Promise<void>;
     get indexSeq(): number;
     append(input: Omit<SessionIndexEvent, "version" | "indexSeq" | "checksum" | "ts"> & Partial<Pick<SessionIndexEvent, "ts">>): Promise<SessionIndexEvent>;

package/dist/types/sdk/broker/state-version.d.ts

@@ -3,8 +3,9 @@ export declare const SESSION_INDEX_SNAPSHOT_VERSION = 2;
 export declare class UnsupportedStateVersionError extends Error {
     readonly file: string;
     readonly version: number;
+    readonly maximumSupportedVersion: number;
     readonly code = "unsupported_state_version";
-    constructor(file: string, version: number);
+    constructor(file: string, version: number, maximumSupportedVersion?: number);
 }
 export declare function assertSupportedStateVersion(file: string, value: unknown): void;
 export declare function assertSupportedSnapshotVersion(file: string, value: unknown): void;

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

@@ -338,6 +338,8 @@ export declare function createNotificationsExtension(api: ExtensionAPI, options?
     /** Suppress auto-delivery for a GJC-spawned child under `sessionScope=primary`. */
     spawnedByGjc?: boolean;
     controller?: NotificationSessionController;
+    /** Whether this host mode can own the root SDK endpoint. Default: true. */
+    sdkHostModeSupported?: boolean;
     onSdkRequest?: (kind: "control" | "query", connectionId: string, frame: Record<string, unknown>) => void;
     runEphemeralTurn?: (promptText: string, signal: AbortSignal) => Promise<{
         replyText: string;

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

@@ -150,6 +150,8 @@ export interface CreateAgentSessionOptions {
     hasUI?: boolean;
     /** Whether this host mode can own a notification session endpoint. Default: true. */
     notificationHostModeSupported?: boolean;
+    /** Whether this host mode can own the root SDK endpoint. Default: true. */
+    sdkHostModeSupported?: boolean;
     /**
      * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
      * Passing `{}` enables the loop's GenAI-semantic-convention spans. See