@gajae-code/coding-agent 0.12.21 → 0.13.0

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

@@ -443,6 +443,34 @@ export declare const SETTINGS_SCHEMA: {
             readonly options: "runtime";
         };
     };
+    readonly "modelProfile.proxyProvider": {
+        readonly type: "string";
+        readonly default: undefined;
+        readonly ui: {
+            readonly tab: "model";
+            readonly label: "Proxy Provider";
+            readonly description: "Configured OpenAI-compatible proxy/gateway provider id (e.g. litellm) used by built-in model presets. Leave unset to keep direct provider endpoints.";
+        };
+    };
+    readonly "modelProfile.proxyMode": {
+        readonly type: "enum";
+        readonly values: readonly ["fallback", "always"];
+        readonly default: "fallback";
+        readonly ui: {
+            readonly tab: "model";
+            readonly label: "Proxy Routing Mode";
+            readonly description: "fallback routes only selectors whose direct provider lacks credentials; always routes every proxy-routable built-in preset selector through the configured proxy.";
+            readonly options: readonly [{
+                readonly value: "fallback";
+                readonly label: "Fallback";
+                readonly description: "Use the proxy only when direct provider credentials are unavailable";
+            }, {
+                readonly value: "always";
+                readonly label: "Always";
+                readonly description: "Route proxy-routable built-in preset selectors through the proxy";
+            }];
+        };
+    };
     readonly "session.resumeModelBehavior": {
         readonly type: "enum";
         readonly values: readonly ["keepSessionModel", "useCurrentDefault", "ask"];
@@ -470,6 +498,11 @@ export declare const SETTINGS_SCHEMA: {
     readonly modelProviderOrder: {
         readonly type: "array";
         readonly default: string[];
+        readonly ui: {
+            readonly tab: "providers";
+            readonly label: "Provider Priority Order";
+            readonly description: "Ordered provider priority for automatic model resolution. Providers listed earlier win ties; omitted providers fall back to curated ranking. Unavailable saved entries are retained and skipped at runtime.";
+        };
     };
     readonly cycleOrder: {
         readonly type: "array";
@@ -2502,8 +2535,8 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "sessionMemory.mode": {
         readonly type: "enum";
-        readonly values: readonly ["off", "shadow", "enabled"];
-        readonly default: "shadow";
+        readonly values: readonly ["off", "shadow", "enabled", "auto"];
+        readonly default: "auto";
     };
     readonly "sessionMemory.contextOverflowRecovery": {
         readonly type: "boolean";
@@ -4045,81 +4078,6 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
-    readonly "providers.image": {
-        readonly type: "enum";
-        readonly values: readonly ["auto", "openai", "gemini", "openrouter", "antigravity", "alibaba", "custom"];
-        readonly default: "auto";
-        readonly ui: {
-            readonly tab: "providers";
-            readonly label: "Image Generation";
-            readonly description: "Provider and model for image generation tool";
-            readonly options: readonly [{
-                readonly value: "auto";
-                readonly label: "Auto";
-                readonly description: "Priority: GPT model image tool > Antigravity > OpenRouter > Gemini > Alibaba";
-            }, {
-                readonly value: "openai";
-                readonly label: "OpenAI";
-                readonly description: "Uses gpt-image-2 via OpenAI Responses/Codex";
-            }, {
-                readonly value: "gemini";
-                readonly label: "Gemini";
-                readonly description: "Requires GEMINI_API_KEY";
-            }, {
-                readonly value: "openrouter";
-                readonly label: "OpenRouter";
-                readonly description: "Requires OPENROUTER_API_KEY";
-            }, {
-                readonly value: "antigravity";
-                readonly label: "Antigravity";
-                readonly description: "Requires login with google-antigravity";
-            }, {
-                readonly value: "alibaba";
-                readonly label: "Alibaba Bailian";
-                readonly description: "Requires ALIBABA_TOKEN_PLAN_API_KEY (wan2.7-image via Token Plan)";
-            }, {
-                readonly value: "custom";
-                readonly label: "Custom";
-                readonly description: "OpenAI-compatible endpoint (set providers.imageCustomUrl)";
-            }];
-        };
-    };
-    readonly "providers.imageModel": {
-        readonly type: "string";
-        readonly default: undefined;
-        readonly ui: {
-            readonly tab: "providers";
-            readonly label: "Image Model";
-            readonly description: "Override the default image generation model for the selected provider";
-        };
-    };
-    readonly "providers.imageCustomUrl": {
-        readonly type: "string";
-        readonly default: undefined;
-        readonly ui: {
-            readonly tab: "providers";
-            readonly label: "Image Custom URL";
-            readonly description: "Base URL for custom OpenAI-compatible image endpoint";
-        };
-    };
-    readonly "providers.imageCustomKey": {
-        readonly type: "string";
-        readonly default: undefined;
-        readonly ui: {
-            readonly tab: "providers";
-            readonly label: "Image Custom API Key";
-            readonly description: "API key for custom OpenAI-compatible image endpoint";
-        };
-    };
-    readonly "providers.imageCustomKeyEnv": {
-        readonly type: "string";
-        readonly default: undefined;
-        readonly ui: {
-            readonly tab: "providers";
-            readonly label: "Image Custom API Key Env";
-            readonly description: "Environment variable name holding the API key for custom image endpoint";
-        };
-    };
     readonly "providers.kimiApiFormat": {
         readonly type: "enum";
         readonly values: readonly ["openai", "anthropic"];
@@ -4495,7 +4453,7 @@ export interface ShellMinimizerSettings {
     maxCaptureBytes: number;
 }
 export interface SessionMemorySettings {
-    mode: "off" | "shadow" | "enabled";
+    mode: "off" | "shadow" | "enabled" | "auto";
     contextOverflowRecovery: boolean;
 }
 export interface MemoryGuardSettings {

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

@@ -113,6 +113,8 @@ export declare class Settings implements NotificationSettingsReader {
      * Apply runtime overrides (not persisted).
      */
     override<P extends SettingPath>(path: P, value: SettingValue<P>): void;
+    /** Read the exact runtime override without merged defaults. */
+    getOverride<P extends SettingPath>(path: P): SettingValue<P> | undefined;
     /**
      * Clear a runtime override.
      */

package/dist/types/edit/renderer.d.ts

@@ -11,7 +11,7 @@ import { type VimRenderArgs } from "../tools/vim";
 import type { EditMode } from "../utils/edit-mode";
 import type { DiffError, DiffResult } from "./diff";
 import type { Operation } from "./modes/patch";
-import type { PerFileDiffPreview } from "./streaming";
+import { type PerFileDiffPreview } from "./streaming";
 export { getLspBatchRequest, type LspBatchRequest };
 export interface EditToolPerFileResult {
     path: string;
@@ -53,7 +53,7 @@ export interface EditToolDetails {
     /** Source-of-truth content after the edit; `undefined` for delete operations. */
     newText?: string;
 }
-interface EditRenderArgs {
+export interface EditRenderArgs {
     path?: string;
     file_path?: string;
     oldText?: string;
@@ -76,6 +76,7 @@ type EditRenderEntry = {
     rename?: string;
     move?: string;
     op?: Operation;
+    firstChangedLine?: number;
 };
 /** Extended context for edit tool rendering */
 export interface EditRenderContext {
@@ -108,3 +109,5 @@ export declare const editToolRenderer: {
         renderContext?: EditRenderContext;
     }, uiTheme: Theme, args?: EditRenderArgs): Component;
 };
+export declare function getPerFileEditRenderArgs(args: EditRenderArgs | undefined, path: string, editMode: EditMode | undefined): EditRenderArgs | undefined;
+export declare function getPerFileEditRenderContext(renderContext: EditRenderContext | undefined, path: string): EditRenderContext | undefined;

package/dist/types/edit/streaming.d.ts

@@ -14,6 +14,7 @@
  */
 import type { Theme } from "../modes/theme/theme";
 import { type EditMode, resolveEditMode } from "../utils/edit-mode";
+import { type Operation } from "./modes/patch";
 export interface PerFileDiffPreview {
     path: string;
     diff?: string;
@@ -52,6 +53,18 @@ export interface EditStreamingStrategy<Args = unknown> {
      */
     renderStreamingFallback(args: Args, uiTheme: Theme): string;
 }
+export interface EditRequestTargetInventory {
+    paths: string[];
+    /** Operation of the first target (Create/Delete) when derivable from the
+     * request payload (apply_patch/hashline free-form envelopes carry op on the
+     * parsed entry, not on the top-level args). */
+    firstOp?: Operation;
+    parseError?: string;
+}
+export declare function orderedDistinctPaths(paths: readonly (string | undefined)[]): string[];
+export declare function getEditRequestTargetInventory(args: unknown, editMode: EditMode | undefined, options: {
+    isPartial: boolean;
+}): EditRequestTargetInventory;
 /**
  * Given an edits array parsed from partial JSON, drop the last entry when the
  * corresponding object in `partialJson` does not yet end with a closed `}`.

package/dist/types/extensibility/custom-tools/types.d.ts

@@ -64,6 +64,8 @@ export interface CustomToolContext {
     sessionManager: ReadonlySessionManager;
     /** Model registry - use for API key resolution and model retrieval */
     modelRegistry: ModelRegistry;
+    /** Credential-selection identity for provider authentication. */
+    credentialSessionId?: string;
     /** Current model (may be undefined if no model is selected yet) */
     model: Model | undefined;
     /** Whether the agent is idle (not streaming) */

package/dist/types/extensibility/extensions/compact-handler.d.ts

@@ -12,8 +12,9 @@ interface CompactableSession {
 }
 export declare function runExtensionCompact(session: CompactableSession, instructionsOrOptions: string | CompactOptions | undefined): Promise<void>;
 interface SetModelCapableSession {
+    credentialSessionId?: string;
     modelRegistry: {
-        getApiKey(model: Model): Promise<string | undefined>;
+        getApiKey(model: Model, sessionId?: string): Promise<string | undefined>;
     };
     setModel(model: Model, role?: string, options?: {
         cause?: string;

package/dist/types/extensibility/extensions/types.d.ts

@@ -247,6 +247,8 @@ export interface ExtensionContext {
     sessionMetadata?: ExtensionSessionMetadata;
     /** Model registry for API key resolution */
     modelRegistry: ModelRegistry;
+    /** Credential-selection identity, distinct from logical/provider cache identity. */
+    credentialSessionId?: string;
     /** Current model (may be undefined) */
     model: Model | undefined;
     /** Whether the agent is idle (not streaming) */
@@ -1028,6 +1030,7 @@ export interface ExtensionActions {
 /** Actions for ExtensionContext (ctx.* in event handlers). */
 export interface ExtensionContextActions {
     getModel: () => Model | undefined;
+    getCredentialSessionId?: () => string;
     isIdle: () => boolean;
     /** Stable resource ownership identifier for the active prompt run. */
     getActivePromptHandle?: () => string | undefined;

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

@@ -166,12 +166,12 @@ export declare function gcHelpText(): string;
 /** Lazily assemble the real store adapters (kept lazy to avoid import cycles). */
 export declare function defaultGcAdapters(): Promise<GcStoreAdapter[]>;
 /** On-disk surfaces the retention axis can reclaim. */
-export type GcDiskSurface = "sessions" | "blobs" | "natives" | "backups";
+export type GcDiskSurface = "sessions" | "blobs" | "artifacts" | "natives" | "backups";
 export declare const GC_DISK_SURFACES: readonly GcDiskSurface[];
 export type GcDiskAction = "keep" | "would_reclaim" | "reclaimed" | "reclaim_failed";
 export interface GcDiskRecord {
     surface: GcDiskSurface;
-    /** Session id, blob hash, natives version, or backup entry name. */
+    /** Session id, blob hash, `<session id>/<filename>` artifact, natives version, or backup entry name. */
     id: string;
     path: string;
     bytes: number;
@@ -185,8 +185,20 @@ export interface GcDiskRecord {
     withheld?: true;
 }
 /**
- * Why a surface refused to reclaim anything, and how much it withheld to stay
- * fail-closed. Present only when the surface declined.
+ * Per-family rollup of a surface whose growth is many small files.
+ *
+ * The artifacts surface writes one record per file, which answers "what may go"
+ * but not "what filled the scope". A family is derived from the filename shape
+ * (`*.bash.log`, `.artifact-id-*`, …) rather than a fixed list, so a tool that
+ * starts writing a new kind of log is counted the day it ships.
+ */
+export interface GcDiskFamilyUsage {
+    family: string;
+    count: number;
+    bytes: number;
+}
+/**
+ * Why a surface withheld reclaim candidates because its evidence was incomplete.
  */
 export interface GcDiskDeclined {
     reason: string;
@@ -205,8 +217,10 @@ export interface GcDiskSurfaceReport {
     kept: number;
     kept_bytes: number;
     failed: number;
-    /** Set when the surface declined to reclaim anything because its evidence was incomplete. */
+    /** Set when the surface withheld reclaim candidates because its evidence was incomplete. */
     declined?: GcDiskDeclined;
+    /** Per-family counts and bytes. Only surfaces whose records are individual files set this. */
+    families?: GcDiskFamilyUsage[];
     records: GcDiskRecord[];
 }
 export interface GcDiskError {

package/dist/types/internal-urls/local-protocol.d.ts

@@ -18,6 +18,7 @@ export interface LocalProtocolOptions {
     getArtifactsDir?: () => string | null;
     isManagedDestination?: () => boolean;
     getManagedLegacyLocalMigrationSource?: () => ManagedLegacyLocalMigrationSource | null;
+    getCredentialSessionId?: () => string | null;
     getSessionId?: () => string | null;
 }
 export declare function initializeLocalRoot(options: LocalProtocolOptions): Promise<string>;

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

@@ -26,8 +26,6 @@ export type ModelSelectorSelection = {
 } | {
     kind: "deleteProfile";
     profileName: string;
-} | {
-    kind: "imageGeneration";
 };
 type RoleSelectCallback = (selection: ModelSelectorSelection) => void | Promise<void>;
 /**

package/dist/types/modes/components/provider-order-context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Live context for the Provider Priority Order editor (`modelProviderOrder`).
+ *
+ * Owns the subscriptions that keep the editor current: `modelProviderOrder`
+ * settings changes and credential-generation changes on the session auth
+ * storage. Snapshots are built on demand from the model registry catalog, so
+ * the editor needs no catalog event subscription.
+ */
+import type { ModelRegistry } from "../../config/model-registry";
+import type { Settings } from "../../config/settings";
+/** Normalize a persisted provider id the same way provider selection does: trimmed, lowercased. */
+export declare function normalizeProviderId(raw: string): string;
+/** Normalize a persisted provider order the same way provider selection does: trimmed, lowercased, deduplicated, blanks and non-strings dropped. */
+export declare function normalizeProviderOrder(order: readonly unknown[]): string[];
+/** Display label for a provider id, mirroring the model selector tab presentation. */
+export declare function formatProviderOrderLabel(providerId: string): string;
+export interface ProviderOrderEntry {
+    /** Normalized provider id (trimmed, lowercased). */
+    id: string;
+    /** Display label for the provider. */
+    label: string;
+    /** Whether the provider is present in the model registry catalog right now. */
+    available: boolean;
+    /** Whether the provider has usable auth for this session. */
+    authenticated: boolean;
+    /** Whether the provider is currently persisted in `modelProviderOrder`. */
+    inOrder: boolean;
+}
+export interface ProviderOrderSnapshot {
+    /** Persisted order (normalized, deduplicated). Unavailable entries are retained. */
+    order: string[];
+    /** Union of registry catalog provider ids and persisted ids. */
+    entries: ProviderOrderEntry[];
+}
+export declare class ProviderOrderContext {
+    #private;
+    constructor(registry: ModelRegistry, settings: Settings, onChange?: () => void, credentialSessionId?: string);
+    /** Build the current provider order snapshot from live registry + settings state. */
+    snapshot(): ProviderOrderSnapshot;
+    /** Persist a new ordered provider list and surface durable write failures. */
+    persistOrder(order: readonly string[]): Promise<void>;
+    /** Clear the persisted provider order so default resolution applies. */
+    resetOrder(): Promise<void>;
+    dispose(): void;
+}

package/dist/types/modes/components/provider-order-editor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ordered provider priority editor for `modelProviderOrder`.
+ *
+ * Full-screen custom settings editor (Container + row list, mirroring the
+ * StatusLine custom editor layout) with add/remove/move-up/move-down/reset
+ * actions that persist to settings immediately. Rows are rebuilt from the live
+ * `ProviderOrderContext` snapshot before every render pass, keeping the
+ * previously selected provider highlighted when the underlying order or auth
+ * state changes. Unavailable persisted providers are retained and dimmed.
+ *
+ * The editor owns the `ProviderOrderContext` lifecycle: both normal close
+ * (`#close`) and external teardown (`dispose()`) release the context
+ * subscriptions and dispose the container, idempotently.
+ */
+import { Container } from "@gajae-code/tui";
+import { type ProviderOrderContext } from "./provider-order-context";
+export declare class ProviderOrderEditorComponent extends Container {
+    #private;
+    constructor(context: ProviderOrderContext, onClose: () => void, onError?: (message: string) => void);
+    /** Rebuild rows from the current snapshot. Called by the controller on context changes. */
+    refresh(): void;
+    handleInput(data: string): void;
+    dispose(): void;
+}

package/dist/types/modes/components/settings-defs.d.ts

@@ -38,7 +38,11 @@ export interface SubmenuSettingDef extends BaseSettingDef {
 export interface TextInputSettingDef extends BaseSettingDef {
     type: "text";
 }
-export type SettingDef = BooleanSettingDef | EnumSettingDef | SubmenuSettingDef | TextInputSettingDef;
+/** Array setting rendered by a dedicated ordered-list editor (currently only `modelProviderOrder`). */
+export interface ProviderOrderSettingDef extends BaseSettingDef {
+    type: "providerOrder";
+}
+export type SettingDef = BooleanSettingDef | EnumSettingDef | SubmenuSettingDef | TextInputSettingDef | ProviderOrderSettingDef;
 /** Get all setting definitions with UI */
 export declare function getAllSettingDefs(): SettingDef[];
 /** Get settings for a specific tab */

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

@@ -69,6 +69,8 @@ export interface SettingsCallbacks {
     onPluginsChanged?: () => void;
     /** Called when asynchronously rebuilt settings content needs a repaint. */
     onRenderRequested?: () => void;
+    /** Create the ordered provider-priority editor for `modelProviderOrder`. */
+    createProviderOrderEditor?: (done: () => void) => Container;
     /** Called when an interactive setting cannot be committed. */
     onError?: (message: string) => void;
     /** Called when settings panel is closed */

package/dist/types/quick-lane/classify.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic quick-lane classifier (issue #3984).
+ *
+ * The deep-interview and ralplan skills describe a task-routing surface in
+ * prose: small, clearly scoped, low-risk work should take a quick lane
+ * (minimal orchestration) while vague, ambiguous, risky, or wide-breadth work
+ * keeps the existing deep path. That gate existed only as prompt guidance, so
+ * it was not auditable or testable. This module encodes the same signals as
+ * deterministic, pure code so eligibility and exclusions are explicit and
+ * regression-covered.
+ *
+ * The classifier is intentionally conservative and fail-closed:
+ * - Any exclusion signal forces the `deep` lane, even when the task also names
+ *   concrete files or symbols. Safety is never overridden by a concrete anchor.
+ * - The `deep` lane preserves the existing deep/interview behavior untouched;
+ *   this module only *classifies*, it never routes or mutates.
+ * - A task with neither a concrete anchor nor an exclusion defaults to `deep`
+ *   because boundness cannot be confirmed.
+ */
+export type QuickLane = "quick" | "deep";
+export interface QuickLaneDecision {
+    /** The routed lane: `quick` (bounded, direct execution) or `deep` (planning/interview path). */
+    lane: QuickLane;
+    /** Concrete anchors that made the task eligible for the quick lane (empty when `deep`). */
+    reasons: string[];
+    /** Exclusions that forced the deep lane (empty when `quick`). */
+    exclusions: string[];
+}
+/**
+ * Classify a task request into the quick lane (bounded, direct execution) or
+ * the deep path (existing planning/interview orchestration).
+ *
+ * Order of operations (fail-closed):
+ * 1. Exclusions are authoritative — any risk/ambiguity/breadth signal (including
+ *    two or more distinct file-path anchors) forces `deep`, even when concrete
+ *    anchors are present.
+ * 2. Otherwise, any concrete anchor yields `quick`.
+ * 3. Otherwise, `deep` (boundness could not be confirmed).
+ */
+export declare function classifyQuickLane(input: string): QuickLaneDecision;

package/dist/types/runtime/stt-settings-setup.d.ts

@@ -0,0 +1,18 @@
+export interface SttDependencySetupProgress {
+    stage: string;
+    percent?: number;
+}
+export interface SttDependencySetupOptions {
+    modelName?: string;
+    onProgress?: (progress: SttDependencySetupProgress) => void;
+}
+export type EnsureSttDependencies = (options?: SttDependencySetupOptions) => Promise<void>;
+export interface ConfigureSttFromSettingsOptions {
+    modelName?: string;
+    ensureDependencies?: EnsureSttDependencies;
+    setEnabled(enabled: false): void;
+    flush(): Promise<void>;
+    showStatus(message: string): void;
+    showError(message: string): void;
+}
+export declare function configureSttFromSettings(options: ConfigureSttFromSettingsOptions): Promise<boolean>;

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

@@ -1,8 +1,12 @@
 import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
 import type { ModelProfileErrorDetails } from "../../config/model-profile-contract";
+import { type ElevationOperation } from "../elevation/digest";
+import { type ElevationAnswerAuthority, type ElevationDispatchOutcome } from "../elevation/dispatch-receipt";
+import { ElevationLedger, type ElevationRequester } from "../elevation/grant-ledger";
 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 { OperationReceiptLedger } from "./operation-receipt-ledger";
 import { SessionIndex } from "./session-index";
 export interface BrokerSettings {
     agentDir: string;
@@ -19,7 +23,7 @@ type ResolvedBrokerSettings = {
     heartbeatTtlMs: number;
     resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
 };
-export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "startup_admission_timeout" | "startup_admission_refused" | "readiness_timeout" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | (string & {});
+export type BrokerErrorCode = "idempotency_conflict" | "terminal_uncertain" | "broker_restarting" | "unavailable" | "endpoint_stale" | "resource_gone" | "invalid_input" | "spawn_failed" | "startup_admission_timeout" | "startup_admission_refused" | "readiness_timeout" | "close_refused" | "not_found" | "live_session" | "cleanup_pending" | "ambiguous_session" | (string & {});
 export type BrokerCleanupIdentity = {
     dev: string;
     ino: string;
@@ -196,6 +200,8 @@ export declare class Broker {
     readonly settings: ResolvedBrokerSettings;
     readonly index: SessionIndex;
     readonly ledger: LifecycleLedger;
+    readonly elevation: ElevationLedger;
+    readonly operationReceipts: OperationReceiptLedger;
     discovery: BrokerDiscovery | null;
     constructor(settings: BrokerSettings);
     runStartup<T>(queueWaitMs: number, timing: StartupAdmissionTiming, task: (admittedAt: number) => Promise<T>): Promise<StartupAdmissionResult<T>>;
@@ -204,6 +210,15 @@ export declare class Broker {
     get completion(): Promise<void>;
     status(): RedactedBrokerDiscovery | null;
     heartbeat(): Promise<void>;
+    /**
+     * Production coalesced heartbeat checkpoint seam (C2): delegates to the session
+     * index writer, which appends at most one `host_heartbeat` per session per
+     * {@link SESSION_HEARTBEAT_INTERVAL_MS} for hosts that are alive and, when recorded,
+     * still carry the same OS process incarnation. Returns the number of checkpoints
+     * written. Used by the periodic publication watch, by session reads so a fresh
+     * registration is observed as live, and by tests.
+     */
+    heartbeatSessions(now?: number): Promise<number>;
     /**
      * Revalidate retained publication ownership and begin one synchronous effect in
      * the same stack. The callback is the authority boundary: callers must perform
@@ -223,7 +238,46 @@ export declare class Broker {
      * spawns a child the broker has no authority over.
      */
     stop(): Promise<void>;
-    handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string): Promise<BrokerResponse>;
+    handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string, elevationRequestId?: string): Promise<BrokerResponse>;
+    /**
+     * Elevation issuance (internal). Binds the exact endpoint identity
+     * (endpointStateRoot/generation/incarnation) from the live index record;
+     * the request digest is broker-computed from the full `{kind,sdkId,input}`
+     * triple with the top-level `elevationRequestId` excluded.
+     */
+    elevationIssue(params: {
+        sessionId: string;
+        operation: ElevationOperation;
+        input: Record<string, unknown>;
+        requester: ElevationRequester;
+        elevationRequestId?: string;
+        expiresInMs?: number;
+    }): Promise<BrokerResponse>;
+    /**
+     * Elevation answer (internal, operator-only). There is no public
+     * `elevation.answer` operation: this entry point is reserved for the local
+     * operator approval surface and the separately authorized gate-answer
+     * source, and the ledger enforces the distinct-answer-source boundary.
+     */
+    elevationAnswer(params: {
+        elevationRequestId: string;
+        answer: "approve" | "deny";
+        presentedDigest: string;
+        answerer: ElevationAnswerAuthority;
+    }): Promise<BrokerResponse>;
+    /** Single-use grant claim (internal): consumes the grant before dispatch. */
+    elevationClaim(params: {
+        elevationRequestId: string;
+    }): Promise<BrokerResponse>;
+    /** Records the dispatch outcome for a claimed grant (internal). */
+    elevationDispatch(params: {
+        elevationRequestId: string;
+        outcome: ElevationDispatchOutcome;
+    }): Promise<BrokerResponse>;
+    /** Truthful elevation status read (internal; reconciles expiry and crash state). */
+    elevationResolve(elevationRequestId: string): Promise<BrokerResponse>;
+    /** Truthful elevation listing (internal). */
+    elevationList(): Promise<BrokerResponse>;
 }
 /** Test-only hook for simulating a process crash after terminal persistence verification. */
 export declare function setTerminalPersistenceHookForTest(broker: Broker, hook: (() => void) | undefined): void;

package/dist/types/sdk/broker/operation-receipt-ledger.d.ts

@@ -0,0 +1,25 @@
+import type { BrokerResponse } from "./broker";
+export type OperationReserveResult = {
+    status: "reserved";
+} | {
+    status: "replay";
+    response: BrokerResponse;
+} | {
+    status: "in_progress";
+} | {
+    status: "conflict";
+};
+/**
+ * Target-session-scoped idempotency key for a clientRef. Identical refs on
+ * different sessions are independent, so a receipt can never replay or
+ * conflict across sessions.
+ */
+export declare function operationReceiptKey(sessionId: string, clientRef: string): string;
+export declare function operationReceiptDigest(operation: string, input: Record<string, unknown>, sessionId?: string): string;
+export declare class OperationReceiptLedger {
+    #private;
+    constructor(agentDir: string);
+    open(): Promise<void>;
+    reserve(clientRef: string, digest: string): Promise<OperationReserveResult>;
+    complete(clientRef: string, digest: string, response: BrokerResponse): Promise<void>;
+}