@gajae-code/coding-agent 0.13.0 → 0.13.1

package/dist/types/sdk/bus/kind-aware-reconciliation.d.ts

@@ -3,11 +3,13 @@
  * Preserves Q26 admit/first-terminal/capacity/TTL semantics; indexes and caps are per-kind.
  */
 import type { PromptReconciliationStatus, SdkPromptTerminalOutcome, TurnPromptReconciliation } from "../prompt-status";
+import { type TurnResultContent, type TurnResultPage } from "../turn-result";
 import { type PromptCorrelation } from "./prompt-reconciliation";
 import type { ReconciliationKind, ReconciliationStore } from "./reconciliation-store";
 export type { ReconciliationKind };
 export interface KindCorrelation extends PromptCorrelation {
     kind: ReconciliationKind;
+    content?: TurnResultContent;
 }
 export interface KindAwareReconciliation {
     admit(kind: ReconciliationKind, clientRef?: string): void;
@@ -17,21 +19,28 @@ export interface KindAwareReconciliation {
     }): Promise<void>;
     noteTransition(kind: ReconciliationKind, correlation: PromptCorrelation | undefined, frame: {
         type: "agent_start" | "agent_end";
+        content?: TurnResultContent;
     } | {
         type: "agent_failed";
         error: unknown;
+        content?: TurnResultContent;
     }): Promise<void>;
     claimPendingOutcome(correlation: PromptCorrelation, outcome: SdkPromptTerminalOutcome): Promise<SdkPromptTerminalOutcome>;
     finalizePromptOutcome(correlation: PromptCorrelation, outcome?: SdkPromptTerminalOutcome, recordError?: {
         code: string;
         message: string;
-    }): Promise<void>;
+    }, content?: unknown): Promise<void>;
     peekPendingOutcome(correlation: PromptCorrelation): SdkPromptTerminalOutcome | undefined;
     lookup(kind: ReconciliationKind, selector: {
         commandId?: string;
         turnId?: string;
         clientRef?: string;
     }): TurnPromptReconciliation;
+    lookupResult(kind: ReconciliationKind, selector: {
+        commandId?: string;
+        turnId?: string;
+        clientRef?: string;
+    }): TurnResultPage;
     cleanup(): void;
     activeCount(kind: ReconciliationKind): number;
     /** Hydrate from durable store (call once at session host start). */

package/dist/types/sdk/bus/reconciliation-store.d.ts

@@ -1,4 +1,5 @@
 import type { PromptReconciliationStatus, SdkPromptTerminalOutcome } from "../prompt-status";
+import { type TurnResultContent } from "../turn-result";
 import type { PromptCorrelation } from "./prompt-reconciliation";
 export declare const RECONCILIATION_STORE_VERSION = 1;
 export declare const RECONCILIATION_SESSION_ID_PATTERN: RegExp;
@@ -19,6 +20,7 @@ export interface DurableReconciliationRecord extends PromptCorrelation {
     pendingOutcome?: SdkPromptTerminalOutcome;
     /** Skill-only safe token; never skill args bodies. */
     skillName?: string;
+    content?: TurnResultContent;
 }
 export interface ReconciliationStoreDocument {
     version: typeof RECONCILIATION_STORE_VERSION;

package/dist/types/sdk/bus/telegram-daemon-contract.d.ts

@@ -93,9 +93,18 @@ export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
  * the exact grace deadline when a failed archive publication rolls back.
  * Generation 59 publishes the owner's attached OPEN-socket count in the
  * heartbeat sidecar so `gjc notify health` can report a live daemon that is
- * attached to no registered endpoint (#4128).
+ * attached to no registered endpoint (#4128). Generation 60 contains transient
+ * heartbeat-sidecar publication failures: a Windows EPERM/EACCES/EBUSY on the
+ * sidecar rename is retried bounded under the ownership-lock fence and an
+ * exhausted publication keeps the daemon alive as `publish_failed` instead of
+ * escaping as an uncaught exception, while only a proven state/lock mismatch
+ * (`not_owner`) stops the owner (#4200). Generation 61 keeps authenticated
+ * same-session transports attached while predecessor archival converges and
+ * settles non-forum close responses. Generation 62 rejects replay-gap
+ * authority claims that do not match the requested cursor, answer bounds,
+ * and retained replay suffix.
  */
-export declare const DAEMON_GENERATION = 59;
+export declare const DAEMON_GENERATION = 62;
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 5
  * requires the complete generation-36 topic authority contract, so older

package/dist/types/sdk/bus/telegram-daemon.d.ts

@@ -296,6 +296,20 @@ export declare function readOwnerFreshnessSnapshot(input: {
     settings: Settings;
     fs?: TelegramDaemonFs;
 }): Promise<OwnerFreshnessSnapshot>;
+/** Outcome of a steady heartbeat sidecar renewal. */
+export type OwnerHeartbeatSidecarRenewal = 
+/** The sidecar was published under a still-matching ownership lock. */
+"renewed"
+/** This process no longer matches the persisted state/lock; stop renewing. */
+ | "not_owner"
+/**
+ * Ownership still held, but the sidecar publication failed (e.g. a transient
+ * Windows EPERM/EBUSY while another process holds the destination). The
+ * daemon must stay alive and publish again on the next cycle (#4200); a
+ * persistently failing publication eventually stales the heartbeat for
+ * outside observers, whose takeover then surfaces here as `not_owner`.
+ */
+ | "publish_failed";
 /** Marker-free steady heartbeat renewal. The final lock reread fences a stale writer. */
 export declare function renewOwnerHeartbeatSidecar(input: {
     settings: Settings;
@@ -311,7 +325,7 @@ export declare function renewOwnerHeartbeatSidecar(input: {
      * rather than falsely claiming zero attachments.
      */
     attachedEndpoints?: number;
-}): Promise<boolean>;
+}): Promise<OwnerHeartbeatSidecarRenewal>;
 export interface NotificationRootRegistration {
     root?: string;
     managed?: boolean;
@@ -946,6 +960,8 @@ interface SessionSocket {
     pingTimer: ReturnType<typeof setInterval> | undefined;
     /** Correlation id for the startup replay barrier. */
     replayId: string;
+    /** Sequence cursor sent by the current startup replay request. */
+    replaySinceSeq: number;
     /** Queues live frames until startup replay is applied. */
     replayPending: boolean;
     replayQueue: Record<string, unknown>[];

package/dist/types/sdk/host/query/cursor.d.ts

@@ -28,6 +28,10 @@ export interface CursorSelector {
     resourceKind?: string;
     resourceId?: string;
     itemId?: string;
+    kind?: string;
+    clientRef?: string;
+    commandId?: string;
+    turnId?: string;
 }
 export interface CursorPosition {
     offset?: number;

package/dist/types/sdk/host/query/handlers.d.ts

@@ -44,6 +44,12 @@ export interface SessionSurface {
         turnId?: string;
         clientRef?: string;
     }): unknown | Promise<unknown>;
+    getTurnResult?(selector: {
+        kind: "prompt" | "skill";
+        clientRef?: string;
+        commandId?: string;
+        turnId?: string;
+    }): unknown | Promise<unknown>;
     /** Q27 effective model-profile catalog from the live session registry. */
     getModelProfiles?(): unknown[] | Promise<unknown[]>;
     /**

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

@@ -92,6 +92,11 @@ export interface InvocationReconciliation {
         turnId?: string;
         clientRef?: string;
     }): unknown;
+    lookupResult(kind: InvocationKind, selector: {
+        commandId?: string;
+        turnId?: string;
+        clientRef?: string;
+    }): unknown;
     hydrate(): Promise<void>;
 }
 export declare function createInvocationReconciliation(options?: {
@@ -112,12 +117,8 @@ export interface SdkSurfaceFactoryOptions {
     configOverrides?: ReadonlyMap<string, unknown>;
     /** Session settings; used for model-usage preferences in profile-limit resolution. */
     settings?: Settings;
-    promptStatusLookup?: (selector: {
-        commandId?: string;
-        turnId?: string;
-        clientRef?: string;
-    }) => unknown;
-    skillStatusLookup?: (selector: {
+    turnResultLookup?: (selector: {
+        kind: "prompt" | "skill";
         commandId?: string;
         turnId?: string;
         clientRef?: string;

package/dist/types/sdk/host/websocket-transport.d.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import type { SessionSdkTransport } from "./session-runtime";
 export interface SdkWebSocketTransportDependencies {
-    readonly filesystem?: Pick<typeof fs, "mkdir" | "writeFile" | "chmod" | "rm">;
+    readonly filesystem?: Pick<typeof fs, "mkdir" | "writeFile" | "chmod" | "rename" | "readFile" | "rm">;
     readonly serve?: typeof Bun.serve;
 }
 export type SdkTransportLifecycleErrorCode = "endpoint_write_failed" | "endpoint_chmod_failed" | "endpoint_remove_failed" | "server_stop_failed";

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

@@ -8,3 +8,4 @@ export * from "./prompt-status";
 export type { ActiveProviderConnectionKind, ActiveProviderDescriptor } from "./providers";
 export * from "./session";
 export * from "./session-directory";
+export * from "./turn-result";

package/dist/types/sdk/turn-result.d.ts

@@ -0,0 +1,37 @@
+/** Canonical durable turn-result DTOs. */
+export declare const TURN_RESULT_VERSION: 1;
+export declare const TURN_RESULT_CONTENT_MAX_BYTES = 16384;
+export declare const TURN_RESULT_ERROR_MESSAGE_MAX_LENGTH = 512;
+export type TurnResultSelector = {
+    kind: "prompt" | "skill";
+    clientRef: string;
+} | {
+    kind: "prompt" | "skill";
+    commandId: string;
+    turnId: string;
+};
+export type TurnResultStatus = "unknown" | "accepted" | "in_flight" | "terminal_ok" | "failed";
+export interface TurnResultContent {
+    version: typeof TURN_RESULT_VERSION;
+    type: "text";
+    text: string;
+    byteLength: number;
+    truncated: boolean;
+}
+export interface TurnResultError {
+    code: string;
+    message: string;
+}
+export interface TurnResultPage {
+    status: TurnResultStatus;
+    kind?: "prompt" | "skill";
+    commandId?: string;
+    turnId?: string;
+    clientRef?: string;
+    acceptedAt?: number;
+    startedAt?: number;
+    terminalAt?: number;
+    content?: TurnResultContent;
+    error?: TurnResultError;
+}
+export declare function sanitizeTurnResultContent(text: unknown): TurnResultContent | undefined;

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

@@ -629,7 +629,7 @@ export declare class AgentSession {
     /** Suspend provider state without closing it while a temporary model is active. */
     beginTemporaryProviderSessionScope(reason: TemporaryModelReason): TemporaryProviderSessionScope;
     /** Restore a temporary scope, unwinding any auto-owned scopes above it. */
-    restoreTemporaryProviderSessionScope(token: TemporaryProviderSessionScope): boolean;
+    restoreTemporaryProviderSessionScope(token: TemporaryProviderSessionScope): Promise<boolean>;
     /** Promote a temporary scope. The suspended provider state is permanently closed. */
     commitTemporaryProviderSessionScope(token: TemporaryProviderSessionScope): boolean;
     buildForkContextSeed(options: ForkContextSeedOptions): Promise<ForkContextSeed>;
@@ -1251,19 +1251,16 @@ export declare class AgentSession {
      */
     isFastModeEnabled(): boolean;
     /**
-     * True when the configured `serviceTier` resolves to `"priority"` for the
-     * given model `provider`. Returns false for scoped tiers that don't match
-     * (e.g. `"openai-only"` on an anthropic provider) and when `provider` is
-     * undefined. This is the canonical provider-aware fast-mode predicate.
+     * True when the configured tier is realized as a fast-mode field on the
+     * provider's wire protocol. Providers that silently drop unscoped priority
+     * intent return false so UI indicators match the request that is sent.
      */
-    isFastForProvider(provider?: string): boolean;
+    isFastForProvider(provider?: string, supportsServiceTier?: boolean): boolean;
     /**
-     * Provider-aware fast-mode predicate for task-tool subagent roles, evaluated
-     * against the effective subagent tier (`task.serviceTier`) rather than the
-     * main session tier. Use this for `task.agentModelOverrides` role rows so the
-     * ⚡ glyph reflects the tier the subagent actually runs under.
+     * Wire-effective fast-mode predicate for task-tool subagent roles, evaluated
+     * against `task.serviceTier` rather than the main session tier.
      */
-    isFastForSubagentProvider(provider?: string): boolean;
+    isFastForSubagentProvider(provider?: string, supportsServiceTier?: boolean): boolean;
     /**
      * True when the configured `serviceTier` resolves to `"priority"` for the
      * *currently selected model's provider* AND fast mode was not auto-disabled

package/dist/types/session/blob-store.d.ts

@@ -27,7 +27,7 @@ export declare class ResidentCacheTrustError extends Error {
     readonly path: string;
     constructor(reason: string, path: string, options?: ErrorOptions);
 }
-export declare function disposeVerifiedResidentCacheInstanceDir(instanceDir: string): void;
+export declare function disposeVerifiedResidentCacheInstanceDir(instanceDir: string, parentDescriptor?: number): void;
 /**
  * Best-effort cleanup of abandoned resident-cache instances. The root is
  * re-verified before scanning, work is bounded, and all failures fail closed.
@@ -84,6 +84,7 @@ export declare class BlobStore {
 }
 interface EphemeralBlobStoreOptions {
     readonly adoptVerifiedDir?: boolean;
+    readonly disposalParentDescriptor?: number;
 }
 /** Resident-cache directories still tracked by this process. Test seam. */
 export declare function trackedResidentCacheDirsForTest(): string[];
@@ -213,8 +214,10 @@ export interface CanonicalBlobEntry {
     readonly path: string;
     readonly bytes: number;
     readonly mtimeMs: number;
-    readonly dev: number;
-    readonly ino: number;
+    readonly mtimeNs: bigint;
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly nlink: bigint;
 }
 /** Longest possible `blob:sha256:<hash>` reference, used to bound chunked scans. */
 export declare const BLOB_REFERENCE_MAX_LENGTH: number;

package/dist/types/slash-commands/helpers/fast-status-report.d.ts

@@ -1,4 +1,4 @@
-import type { Model } from "@gajae-code/ai/core";
+import { type Model } from "@gajae-code/ai/core";
 /**
  * A single line in the `/fast status` report: a labelled model and whether fast
  * mode is effective for it. The `fast` flag is resolved by the caller
@@ -36,7 +36,7 @@ export declare function formatFastStatusReport(args: FormatFastStatusReportArgs)
 export interface FastStatusSessionLike {
     readonly model?: Model;
     /** Fast predicate against the main session tier (current model + `modelRoles`). */
-    isFastForProvider(provider?: string): boolean;
+    isFastForProvider(provider?: string, supportsServiceTier?: boolean): boolean;
     /**
      * Current-model EFFECTIVE fast state (intent minus any provider auto-disable).
      * Used for the current-model row so it matches what the next request does.
@@ -44,10 +44,19 @@ export interface FastStatusSessionLike {
      */
     isFastModeActive?(): boolean;
     /** Fast predicate against the effective subagent tier (`task.agentModelOverrides` roles). */
-    isFastForSubagentProvider(provider?: string): boolean;
+    isFastForSubagentProvider(provider?: string, supportsServiceTier?: boolean): boolean;
     resolveRoleModelWithThinking(role: string): {
         model?: Model;
     };
+    /** Runtime fallback position for the configured DEFAULT chain. */
+    getDefaultFallbackRuntimeState?(): {
+        chain: {
+            entries: readonly string[];
+        };
+        controller: {
+            activeIndex: number;
+        };
+    };
 }
 /** A role to enumerate in the report, with the tier source its subagent runs under. */
 export interface FastStatusRoleTarget {

package/dist/types/task/executor.d.ts

@@ -4,7 +4,7 @@
  * Runs each subagent on the main thread and forwards AgentEvents for progress tracking.
  */
 import type { AgentTelemetryConfig, ThinkingLevel } from "@gajae-code/agent-core";
-import type { Model, ServiceTier } from "@gajae-code/ai/core";
+import { type Model, type ServiceTier } from "@gajae-code/ai/core";
 import { ModelRegistry } from "../config/model-registry";
 import type { PromptTemplate } from "../config/prompt-templates";
 import { Settings } from "../config/settings";
@@ -82,14 +82,11 @@ export interface ExecutorOptions {
     /** Parent session's registry; shared by child sessions for IRC routing and roster visibility. */
     agentRegistry?: AgentRegistry;
     /**
-     * Live service-tier intent of the parent session (`AgentSession.serviceTier`),
-     * used as the inherited tier when `task.serviceTier === "inherit"`. Passing the
-     * live value (not the stale settings snapshot) lets a runtime `/fast on` reach
-     * subagents, and a main-model fast-mode auto-disable does not clobber it.
+     * Parent service-tier intent captured when the child is spawned. Used when
+     * `task.serviceTier === "inherit"` so request serialization and reporting use
+     * the same immutable child settings snapshot.
      */
     inheritedServiceTier?: ServiceTier;
-    /** Resolve whether the effective subagent tier grants fast mode for the selected provider. */
-    isFastForSubagentProvider?: (provider?: string) => boolean;
     /** Override local:// protocol options so subagent shares parent's local:// root */
     localProtocolOptions?: LocalProtocolOptions;
     /**

package/dist/types/tools/index.d.ts

@@ -237,7 +237,7 @@ export interface ToolSession {
     /** Live service-tier intent of the parent session, inherited by `inherit` subagents. */
     serviceTier?: ServiceTier;
     /** Whether the effective subagent tier grants fast mode for a resolved provider. */
-    isFastForSubagentProvider?: (provider?: string) => boolean;
+    isFastForSubagentProvider?: (provider?: string, supportsServiceTier?: boolean) => boolean;
     /** Plan mode state (if active) */
     getPlanModeState?: () => PlanModeState | undefined;
     /** Goal mode state (if active or paused) */

package/dist/types/tools/read.d.ts

@@ -90,7 +90,7 @@ export declare class ReadTool implements AgentTool<typeof readSchema, ReadToolDe
     readonly name = "read";
     readonly label = "Read";
     readonly loadMode = "essential";
-    readonly description: string;
+    get description(): string;
     readonly parameters: z.ZodObject<{
         path: z.ZodString;
         truncation: z.ZodOptional<z.ZodEnum<{

package/dist/types/tools/search.d.ts

@@ -58,7 +58,7 @@ export declare class SearchTool implements AgentTool<typeof searchSchema, Search
     readonly label = "Search";
     readonly loadMode = "discoverable";
     readonly summary = "Search file contents using ripgrep (fast text search)";
-    readonly description: string;
+    get description(): string;
     readonly parameters: z.ZodObject<{
         pattern: z.ZodString;
         paths: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/types/utils/edit-mode.d.ts

@@ -1,13 +1,82 @@
 export type EditMode = "replace" | "patch" | "hashline" | "vim" | "apply_patch";
+/** Setting value for `edit.mode`: an executable mode or `auto` (model-family routing). */
+export type EditModeSetting = "auto" | EditMode;
+/** Fallback executable mode used when automatic routing cannot identify the model. */
 export declare const DEFAULT_EDIT_MODE: EditMode;
+/** Default `edit.mode` setting value. */
+export declare const DEFAULT_EDIT_MODE_SETTING: EditModeSetting;
 export declare const EDIT_MODES: EditMode[];
+export declare const EDIT_MODE_SETTINGS: EditModeSetting[];
 export declare function normalizeEditMode(mode?: string | null): EditMode | undefined;
+export type ModelEditFamily = "gpt" | "codex" | "claude" | "deepseek" | "qwen" | "minimax" | "glm" | "kimi" | "unknown";
+/**
+ * Detect the model family from a model ID, ignoring the provider prefix so
+ * equivalent models served through different providers route identically
+ * (`openai/gpt-5.4`, `openrouter/openai/gpt-5.4`, `company-gateway/gpt-5.4`).
+ *
+ * Matching only examines the final path segment. A direct family prefix or a
+ * known provider-qualified family name is accepted, while arbitrary token
+ * substrings return `unknown` instead of guessing.
+ */
+export declare function detectModelEditFamily(modelId: string | undefined): ModelEditFamily;
+/** Built-in mode for a detected family; `undefined` for `unknown`. */
+export declare function builtinEditModeForFamily(family: ModelEditFamily): EditMode | undefined;
+export type EditModeSource = "environment" | "model-override" | "setting" | "catalog" | "builtin-family" | "fallback";
+export type ResolvedEditModeDetails = {
+    mode: EditMode;
+    source: EditModeSource;
+    modelId?: string;
+    family?: ModelEditFamily;
+    matchedRule?: string;
+};
+/** Raw `edit.modelVariants` match: pattern plus the configured (unvalidated) value. */
+export type EditVariantMatch = {
+    pattern: string;
+    value: string;
+};
 export interface EditModeSettingsLike {
     get(key: "edit.mode"): unknown;
+    /** Legacy accessor: first *valid* matching `edit.modelVariants` value. */
     getEditVariantForModel?(model: string | undefined): EditMode | null;
+    /**
+     * Discriminated accessor: first matching `edit.modelVariants` rule with its
+     * raw value. Lets the resolver fail closed on invalid matched values
+     * instead of silently falling through to another mode.
+     */
+    matchEditVariantForModel?(model: string | undefined): EditVariantMatch | null;
 }
 export interface EditModeSessionLike {
     settings: EditModeSettingsLike;
     getActiveModelString?: () => string | undefined;
+    /**
+     * Optional model-catalog edit recommendation; beats the built-in family
+     * mapping when present.
+     *
+     * Extension point: production sessions do not wire this yet — the model
+     * catalog does not expose an edit-protocol recommendation (`applyPatchToolType`
+     * is the OpenAI wire representation of an already-selected `apply_patch`
+     * mode, not a mode selector). Catalog metadata generation is deliberately
+     * deferred until the family-based path is proven for arbitrary custom-provider
+     * IDs; when it lands, sessions can expose this hook without a resolver change.
+     */
+    getCatalogEditMode?: () => EditMode | undefined;
 }
+/**
+ * Read the forced edit mode from `GJC_EDIT_VARIANT`/`PI_EDIT_VARIANT`.
+ * The environment force is the emergency kill switch and beats every other
+ * source. Invalid values fail fast; empty and `auto` mean "not forced".
+ */
+export declare function resolveForcedEnvEditMode(): EditMode | undefined;
+/**
+ * Resolve the active edit mode with provenance.
+ *
+ * Precedence:
+ * 1. `GJC_EDIT_VARIANT`/`PI_EDIT_VARIANT` environment force (invalid → throw).
+ * 2. Matching user `edit.modelVariants` rule (matched invalid → throw).
+ * 3. Explicit `edit.mode` setting when it is not `auto`.
+ * 4. Model-catalog edit recommendation, when the session exposes one.
+ * 5. Built-in model-family mapping.
+ * 6. `hashline` fallback.
+ */
+export declare function resolveEditModeDetails(session: EditModeSessionLike): ResolvedEditModeDetails;
 export declare function resolveEditMode(session: EditModeSessionLike): EditMode;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.13.0",
+	"version": "0.13.1",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -54,13 +54,13 @@
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.13.0",
-		"@gajae-code/agent-core": "0.13.0",
-		"@gajae-code/ai": "0.13.0",
-		"@gajae-code/bridge-client": "0.13.0",
-		"@gajae-code/natives": "0.13.0",
-		"@gajae-code/tui": "0.13.0",
-		"@gajae-code/utils": "0.13.0",
+		"@gajae-code/stats": "0.13.1",
+		"@gajae-code/agent-core": "0.13.1",
+		"@gajae-code/ai": "0.13.1",
+		"@gajae-code/bridge-client": "0.13.1",
+		"@gajae-code/natives": "0.13.1",
+		"@gajae-code/tui": "0.13.1",
+		"@gajae-code/utils": "0.13.1",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/generate-hotkeys-docs.ts

@@ -19,16 +19,18 @@ function defaultKeys(
 	bindingId: keyof typeof KEYBINDINGS,
 ): string {
 	const defaultsByPlatform = DOCUMENTATION_PLATFORMS.map(platform => {
+		let keys: string | readonly string[];
 		switch (bindingId) {
 			case "app.message.queue":
-				return defaultMessageQueueKeysForPlatform(platform);
+				keys = defaultMessageQueueKeysForPlatform(platform);
+				break;
 			case "app.clipboard.pasteImage":
-				return defaultClipboardPasteImageKeysForPlatform(platform);
-			default: {
-				const keys = value.defaultKeys;
-				return (Array.isArray(keys) ? keys : [keys]).join(", ") || "_(none)_";
-			}
+				keys = defaultClipboardPasteImageKeysForPlatform(platform);
+				break;
+			default:
+				keys = value.defaultKeys;
 		}
+		return (typeof keys === "string" ? keys : keys.join(", ")) || "_(none)_";
 	});
 	const groups = new Map<string, string[]>();
 	for (const [index, keys] of defaultsByPlatform.entries()) {

package/src/commands/sdk.ts

@@ -24,6 +24,7 @@ import {
 	writeSessionLifecycleReady,
 } from "../sdk/broker/lifecycle";
 import { processIncarnation } from "../sdk/broker/process-incarnation";
+import { writeBrokerStartupFailureMarker } from "../sdk/broker/startup-failure";
 import { runSdkSessionCli } from "../sdk/cli";
 import { runSdkGuidesCli } from "../sdk/guides/cli";
 import { type CreateLifecycleAgentSessionResult, createLifecycleAgentSession } from "../sdk/lifecycle-session";
@@ -913,8 +914,28 @@ export default class Sdk extends Command {
 				return policy === "disabled" ? "disabled" : "copy-retain";
 			},
 		});
-		await broker.start();
-		if (!broker.ownsDiscovery) return;
+		try {
+			await broker.start();
+		} catch (error) {
+			// Surface why this detached broker failed before discovery: the caller
+			// spawns with stdio ignored, so the durable marker is the only channel.
+			await writeBrokerStartupFailureMarker(agentDir, {
+				reason: error instanceof Error ? error.message : String(error),
+				exitCode: 1,
+				signal: null,
+			});
+			throw error;
+		}
+		if (!broker.ownsDiscovery) {
+			// Another broker owns discovery; this process exits cleanly (code 0) as
+			// the race loser. Record why so the caller can diagnose a missing winner.
+			await writeBrokerStartupFailureMarker(agentDir, {
+				reason: "Another broker owns the lock/discovery; this broker exited as the race loser.",
+				exitCode: 0,
+				signal: null,
+			});
+			return;
+		}
 		// A live broker must not keep advertising sessions whose host process is
 		// gone; the sweep is the broker-side half of the host reaping bound.
 		const stopSweep = startBrokerDeadRegistrationSweep(broker);

package/src/config/file-lock.ts

@@ -8,11 +8,13 @@ export interface FileLockOptions {
 	staleMs?: number;
 	retries?: number;
 	retryDelayMs?: number;
+	signal?: AbortSignal;
+	onAcquired?: () => void;
 	/** Stable host identity required to safely reclaim locks on a shared volume. */
 	ownerHostId?: string;
 }
 
-const DEFAULT_OPTIONS: Required<Omit<FileLockOptions, "ownerHostId">> = {
+const DEFAULT_OPTIONS: Required<Omit<FileLockOptions, "ownerHostId" | "signal" | "onAcquired">> = {
 	staleMs: 10_000,
 	retries: 50,
 	retryDelayMs: 100,
@@ -258,13 +260,18 @@ async function removeStaleLockForAcquire(lockPath: string, snapshot: LockStaleSn
 	}
 }
 
-async function tryAcquireLock(lockPath: string, ownerHostId?: string): Promise<LockInfo | null> {
+async function tryAcquireLock(
+	lockPath: string,
+	ownerHostId?: string,
+	onAcquired?: () => void,
+): Promise<LockInfo | null> {
 	await fs.mkdir(path.dirname(lockPath), { recursive: true });
 	const afterParentMkdir = FileLockTestHooks.afterParentMkdir;
 	if (afterParentMkdir) await afterParentMkdir(lockPath);
 	if (ownerHostId === undefined) {
 		try {
 			await fs.mkdir(lockPath);
+			onAcquired?.();
 			return await writeLockInfo(lockPath, lockInfo());
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code === "EEXIST") return null;
@@ -279,6 +286,7 @@ async function tryAcquireLock(lockPath: string, ownerHostId?: string): Promise<L
 		await writeLockInfo(pendingPath, owner);
 		try {
 			await fs.rename(pendingPath, lockPath);
+			onAcquired?.();
 			return owner;
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
@@ -308,12 +316,24 @@ async function acquireLock(filePath: string, options: FileLockOptions = {}): Pro
 	const lockPath = getLockPath(filePath);
 	const contentionStartTimes = new Map<string, string | null>();
 	for (let attempt = 0; attempt < opts.retries; attempt++) {
-		const owner = await tryAcquireLock(lockPath, opts.ownerHostId);
+		if (opts.signal?.aborted) throw opts.signal.reason ?? new Error("File lock acquisition aborted");
+		const owner = await tryAcquireLock(lockPath, opts.ownerHostId, opts.onAcquired);
 		if (owner) return () => releaseLock(lockPath, owner);
-
 		const stale = await staleLockSnapshot(lockPath, opts.staleMs, opts.ownerHostId, contentionStartTimes);
 		if (await removeStaleLockForAcquire(lockPath, stale)) continue;
-		await Bun.sleep(opts.retryDelayMs);
+		if (!opts.signal) {
+			await Bun.sleep(opts.retryDelayMs);
+			continue;
+		}
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		const onAbort = (): void => reject(opts.signal?.reason ?? new Error("File lock acquisition aborted"));
+		opts.signal.addEventListener("abort", onAbort, { once: true });
+		void Bun.sleep(opts.retryDelayMs).then(resolve);
+		try {
+			await promise;
+		} finally {
+			opts.signal.removeEventListener("abort", onAbort);
+		}
 	}
 	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
 }