@gajae-code/coding-agent 0.9.5 → 0.10.0

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

@@ -1,10 +1,10 @@
-import type { AgentMessage } from "@gajae-code/agent-core";
+import { type AgentMessage } from "@gajae-code/agent-core";
 import type { ImageContent, Message, MessageAttribution, ServiceTier, TextContent } from "@gajae-code/ai";
 import type { TtsrInjectionRecord } from "../export/ttsr";
 import { ArtifactManager } from "./artifacts";
 import { type BlobPutResult, BlobStore } from "./blob-store";
 import { type BashExecutionMessage, type CustomMessage, type FileMentionMessage, type HookMessage, type PythonExecutionMessage } from "./messages";
-import type { SessionStorage } from "./session-storage";
+import type { SessionStorage, SessionStorageStat, VerifiedSessionDeleteResult, VerifiedSessionDeleteTarget } from "./session-storage";
 export declare const CURRENT_SESSION_VERSION = 3;
 export interface SessionHeader {
     type: "session";
@@ -73,6 +73,13 @@ export interface SessionMessageEntry extends SessionEntryBase {
      *  metadata (not a message field) so strict message types stay intact. */
     evictedContent?: EvictedContentMarker;
 }
+export declare function associateSessionMessageEntryId(message: AgentMessage, entryId: string): void;
+export declare function getSessionMessageEntryId(message: AgentMessage): string | undefined;
+export declare function associateSessionMessageObservationId(message: AgentMessage, observationId: string): string;
+export declare function getSessionMessageObservationId(message: AgentMessage): string | undefined;
+export declare function associateSessionMessageViewportAnchorId(message: AgentMessage, anchorId: string): void;
+export declare function getSessionMessageViewportAnchorId(message: AgentMessage): string | undefined;
+export declare function transferSessionMessageIdentity(source: AgentMessage[], target: AgentMessage[]): void;
 export interface ThinkingLevelChangeEntry extends SessionEntryBase {
     type: "thinking_level_change";
     thinkingLevel?: string | null;
@@ -230,6 +237,40 @@ export interface SessionContext {
     /** Mode-specific data from the last mode_change entry */
     modeData?: Record<string, unknown>;
 }
+/** Immutable fingerprint captured during read-only resume inspection. */
+export interface ResumeSessionIdentity {
+    canonicalPath: string;
+    sessionId: string;
+    dev: bigint;
+    ino: bigint;
+    size: number;
+    mtimeMs: number;
+    mtimeNs: bigint;
+    sha256: string;
+}
+export interface ResumeTailResumable {
+    kind: "resumable";
+    identity: ResumeSessionIdentity;
+}
+export interface ResumeTailTerminal {
+    kind: "terminal";
+    identity: ResumeSessionIdentity;
+}
+export interface ResumeTailError {
+    kind: "error";
+    reason: "missing" | "malformed" | "unstable" | "read-failed";
+}
+export type ResumeTailInspection = ResumeTailResumable | ResumeTailTerminal | ResumeTailError;
+export interface StrictSessionOpenSuccess {
+    kind: "opened";
+    manager: SessionManager;
+}
+export interface StrictSessionOpenFailure {
+    kind: "error";
+    reason: ResumeTailError["reason"] | "identity-mismatch";
+}
+/** Result of opening an inspected session without create-or-rewrite fallback. */
+export type StrictSessionOpenResult = StrictSessionOpenSuccess | StrictSessionOpenFailure;
 export interface SessionInfo {
     path: string;
     id: string;
@@ -246,6 +287,47 @@ export interface SessionInfo {
     firstMessage: string;
     allMessagesText: string;
 }
+/** Kind of failure surfaced by strict scoped inventory. Any failure grants zero authority. */
+export type StrictInventoryFailureKind = "root" | "scan" | "lstat" | "read" | "parse" | "stat" | "header" | "cwd" | "containment" | "identity";
+/** Sanitized strict-inventory failure. Never carries raw file content. */
+export interface StrictInventoryFailure {
+    kind: StrictInventoryFailureKind;
+    message: string;
+    path?: string;
+}
+/** One exact-identity candidate suitable for ACP authorization binding. */
+export interface StrictInventoryCandidate {
+    /** Canonical absolute transcript path. */
+    path: string;
+    /** Session id parsed from the header. */
+    id: string;
+    /** Canonical cwd parsed from the header. */
+    cwd: string;
+    /** Descriptor-bound transcript identity (dev, ino, ...). */
+    identity: SessionStorageStat;
+}
+/**
+ * Strict inventory result. `complete` carries the full validated candidate set;
+ * `failure` carries every sanitized failure and grants zero page/cursor/authority.
+ * A failure result is never reduced to a partial candidate set.
+ */
+export type StrictInventoryResult = {
+    kind: "complete";
+    candidates: StrictInventoryCandidate[];
+} | {
+    kind: "failure";
+    failures: StrictInventoryFailure[];
+};
+/** Certainty-aware close outcome for strict ACP disposal. */
+export type SessionManagerCloseOutcome = {
+    kind: "closed";
+} | {
+    kind: "close_failed_retryable";
+    error: Error;
+} | {
+    kind: "close_unknown";
+    error: Error;
+};
 export type ReadonlySessionManager = Pick<SessionManager, "getCwd" | "getSessionDir" | "getSessionId" | "getSessionFile" | "getSessionName" | "getArtifactsDir" | "getArtifactManager" | "allocateArtifactPath" | "saveArtifact" | "getArtifactPath" | "getLeafId" | "getLeafEntry" | "getEntry" | "getLabel" | "getBranch" | "getHeader" | "getEntries" | "getTree" | "getUsageStatistics" | "putBlob">;
 /** Exported for testing */
 export declare function migrateSessionEntries(entries: FileEntry[]): void;
@@ -257,7 +339,7 @@ export declare function getLatestCompactionEntry(entries: SessionEntry[]): Compa
  * If leafId is provided, walks from that entry to root.
  * Handles compaction and branch summaries along the path.
  */
-export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>): SessionContext;
+export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>, sessionIdentityNamespace?: string): SessionContext;
 /** Exported for testing */
 export declare function loadEntriesFromFile(filePath: string, storage?: SessionStorage): Promise<FileEntry[]>;
 declare class RecentSessionInfo {
@@ -386,6 +468,15 @@ export declare class SessionManager {
     flush(): Promise<void>;
     /** Close the persistent writer after flushing all pending data. */
     close(): Promise<void>;
+    /** Flush while open, then strictly close; retryable close skips the invalid second flush. */
+    flushAndCloseStrict(): Promise<SessionManagerCloseOutcome>;
+    /**
+     * Strictly flush and close the persist writer, returning the certainty-aware close
+     * outcome without manufacturing success. The existing {@link close} path is
+     * preserved for best-effort callers; this seam lets strict ACP disposal prove
+     * writer closure before any destructive operation.
+     */
+    closeStrict(): Promise<SessionManagerCloseOutcome>;
     getCwd(): string;
     /** Get usage statistics across all assistant messages in the session. */
     getUsageStatistics(): UsageStatistics;
@@ -515,7 +606,7 @@ export declare class SessionManager {
      * @param attribution Who initiated this message for billing/attribution semantics
      * @returns Entry id
      */
-    appendCustomMessageEntry<T = unknown>(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: T, attribution?: MessageAttribution): string;
+    appendCustomMessageEntry<T = unknown>(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: T, attribution?: MessageAttribution, observationId?: string): string;
     /**
      * Append an MCP tool selection entry recording the discovery-selected MCP tools.
      * @param selectedToolNames MCP tool names selected for this branch
@@ -639,6 +730,18 @@ export declare class SessionManager {
      * @param sessionDir Optional session directory for /new or /branch. If omitted, derives from file's parent.
      */
     static open(filePath: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionManager>;
+    /**
+     * List sessions for the resume picker without recovery or other maintenance writes.
+     */
+    static listForResumePickerReadOnly(cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionInfo[]>;
+    /** Inspect a selected session without acquiring write-capable ownership. */
+    static inspectSessionTailReadOnly(filePath: string, storage?: SessionStorage): Promise<ResumeTailInspection>;
+    /**
+     * Main startup code MUST retain the consented inspection identity and branch on
+     * the returned discriminant; an error result never creates, rewrites, or adopts
+     * the selected path. Breadcrumb ownership begins only after `kind: "opened"`.
+     */
+    static openExistingStrict(identity: ResumeSessionIdentity, sessionDir?: string, storage?: SessionStorage): Promise<StrictSessionOpenResult>;
     /**
      * Continue the most recent session, or create new if none.
      * @param cwd Working directory
@@ -657,5 +760,22 @@ export declare class SessionManager {
      * List all sessions across all project directories.
      */
     static listAll(storage?: SessionStorage): Promise<SessionInfo[]>;
+    /**
+     * Strict raw scoped inventory for ACP authorization. Enumerates the scoped
+     * session directory without suppressing any root/scan/lstat/read/parse/stat/
+     * header/cwd/containment/identity failure. A failure result carries every
+     * sanitized failure and grants zero authority — it is never reduced to a
+     * partial candidate set. Display/global {@link list} behavior is unaffected.
+     */
+    static inventorySessionsStrict(cwd: string, options?: {
+        sessionDir?: string;
+        storage?: SessionStorage;
+    }): StrictInventoryResult;
+    /**
+     * Propagate the storage-layer verified hard delete bound to exact identity evidence.
+     * Never performs ID lookup or first-match selection; the caller supplies the exact
+     * authorization target captured from a complete strict inventory.
+     */
+    deleteSessionVerified(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
 }
 export {};

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

@@ -1,7 +1,53 @@
 export interface SessionStorageStat {
+    dev: bigint;
+    ino: bigint;
     size: number;
     mtimeMs: number;
+    mtimeNs: bigint;
     mtime: Date;
+    isFile: boolean;
+}
+/** Exact bytes and identity captured from one opened regular-file descriptor. */
+export interface SessionStorageSnapshot {
+    bytes: Uint8Array;
+    stat: SessionStorageStat;
+}
+/**
+ * Four-state writer close lifecycle. Only a successful underlying close confirms
+ * `closed`. A failure certified to have happened BEFORE the OS close was dispatched
+ * is `close_failed_retryable` (ownership of the numeric fd is still proven, so a
+ * later retry/finalizer close is safe). Any exception from an actually dispatched
+ * close call is terminal `close_unknown`: the numeric fd cannot be safely retried
+ * or finalizer-closed, and the writer blocks strict deletion.
+ */
+export type SessionStorageWriterCloseState = "open" | "close_failed_retryable" | "close_unknown" | "closed";
+/**
+ * Thrown by a {@link SessionStorageWriterCloseAdapter} to certify that a close
+ * failure occurred BEFORE the real OS close (`fs.closeSync`-equivalent) was ever
+ * dispatched. Because no OS close ran, the numeric fd is still owned and a retry
+ * is safe. Any other thrown value is treated as a dispatched close failure
+ * (`close_unknown`) and forbids retry/finalizer close of that fd.
+ */
+export declare class SessionStorageWriterRetryableCloseError extends Error {
+    readonly name = "SessionStorageWriterRetryableCloseError";
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Injectable dispatcher for the numeric-fd OS close. The default implementation
+ * calls `fs.closeSync(fd)`. Tests inject adapters that throw
+ * {@link SessionStorageWriterRetryableCloseError} to certify a pre-dispatch
+ * failure, or that call the real close and throw to simulate a dispatched
+ * failure (`close_unknown`).
+ */
+export interface SessionStorageWriterCloseAdapter {
+    close(fd: number): void;
+}
+/** Options for opening a {@link SessionStorageWriter}. */
+export interface SessionStorageWriterOpenOptions {
+    flags?: "a" | "w";
+    onError?: (err: Error) => void;
+    /** Injectable OS-close dispatcher; defaults to `fs.closeSync`. */
+    closeAdapter?: SessionStorageWriterCloseAdapter;
 }
 export interface SessionStorageWriter {
     writeLine(line: string): Promise<void>;
@@ -16,15 +62,35 @@ export interface SessionStorageWriter {
     flush(): Promise<void>;
     fsync(): Promise<void>;
     close(): Promise<void>;
+    /**
+     * Synchronously close the underlying descriptor. The certainty-aware close
+     * state is updated synchronously and any close failure throws before this
+     * returns, so sync callers (atomic rewrite) can observe a close failure
+     * before proceeding to rename. Mirrors {@link close} semantics exactly.
+     */
+    closeSync(): void;
     getError(): Error | undefined;
+    /** Current certainty-aware close lifecycle state. */
+    getCloseState(): SessionStorageWriterCloseState;
+    /** Stored error for non-success close states (`close_failed_retryable`/`close_unknown`). */
+    getCloseError(): Error | undefined;
 }
 export interface SessionStorage {
     ensureDirSync(dir: string): void;
     existsSync(path: string): boolean;
     writeTextSync(path: string, content: string): void;
     readTextSync(path: string): string;
+    /** Exact on-disk bytes for strict read-only session inspection. */
+    readBytesSync?(path: string): Uint8Array;
+    /** Exact bytes and descriptor-bound identity captured from one opened regular file. */
+    readSnapshotSync?(path: string): SessionStorageSnapshot;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
+    /**
+     * Strict directory scan that never suppresses scan/root errors. Used by strict
+     * authorization inventory; the forgiving {@link listFilesSync} stays display-only.
+     */
+    listFilesStrictSync?(dir: string, pattern: string): string[];
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     readTextPrefix(path: string, maxBytes: number): Promise<string>;
@@ -34,18 +100,90 @@ export interface SessionStorage {
     unlink(path: string): Promise<void>;
     unlinkSync(path: string): void;
     deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
-    openWriter(path: string, options?: {
-        flags?: "a" | "w";
-        onError?: (err: Error) => void;
-    }): SessionStorageWriter;
+    /**
+     * Verified hard delete bound to exact identity evidence. Removes the verified
+     * artifact directory first, revalidates, and unlinks the transcript last. Returns
+     * typed partial-cleanup evidence for exact-identity retry; never returns success
+     * for a partial deletion.
+     */
+    deleteSessionVerified?(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
+    openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
 }
+/** Exact (dev, ino) identity fields used for ACP authorization binding. */
+export interface SessionStorageFileIdentity {
+    dev: bigint;
+    ino: bigint;
+}
+/** Kind of verification failure surfaced by {@link deleteSessionVerified}. */
+export type VerifiedDeleteFailureKind = "containment" | "symlink" | "stat" | "identity" | "header" | "cwd" | "artifacts";
+/**
+ * Thrown by {@link deleteSessionVerified} when canonical containment, transcript
+ * non-symlink/identity, header id/cwd, parent identity, or artifact identity
+ * verification fails. These are visible, sanitized failures: they never mutate
+ * the transcript or artifacts and grant zero authority.
+ */
+export declare class SessionDeleteVerificationError extends Error {
+    readonly kind: VerifiedDeleteFailureKind;
+    constructor(kind: VerifiedDeleteFailureKind, message: string, options?: ErrorOptions);
+}
+/**
+ * Exact identity evidence a verified hard delete binds to. All fields are captured
+ * at authorization time; delete revalidates each one before any mutation. Retry
+ * after a partial cleanup supplies the recorded artifact identity via
+ * {@link expectedArtifactsIdentity}.
+ */
+export interface VerifiedSessionDeleteTarget {
+    /** Canonical sessions root; the transcript must be contained within it. */
+    sessionsRoot: string;
+    /** Canonical transcript path (absolute `*.jsonl`). */
+    transcriptPath: string;
+    /** Expected session id parsed from the header. */
+    sessionId: string;
+    /** Expected canonical cwd parsed from the header. */
+    cwd: string;
+    /** Expected transcript file `(dev, ino)` captured at authorization. */
+    transcriptIdentity: SessionStorageFileIdentity;
+    /**
+     * For retry after an `artifacts` `cleanup_pending`: the recorded artifact
+     * directory identity to re-accept. A replacement/different artifact directory
+     * fails closed. Omit on first attempt or to accept recorded absence.
+     */
+    expectedArtifactsIdentity?: SessionStorageFileIdentity;
+}
+/**
+ * Outcome of a verified hard delete. Artifact removal happens first; only after
+ * revalidation is the transcript unlinked last. A partial deletion returns
+ * `cleanup_pending` with exact evidence for same-connection retry — never
+ * `deleted` and never `{}`.
+ */
+export type VerifiedSessionDeleteResult = {
+    kind: "deleted";
+} | {
+    kind: "cleanup_pending";
+    phase: "artifacts";
+    error: Error;
+    /** Artifact directory identity at failure time; undefined when absent. */
+    artifactsIdentity: SessionStorageFileIdentity | undefined;
+    /** Transcript identity (unchanged) for retry binding. */
+    transcriptIdentity: SessionStorageFileIdentity;
+} | {
+    kind: "cleanup_pending";
+    phase: "transcript";
+    error: Error;
+    /** Transcript identity at failure time for retry binding. */
+    transcriptIdentity: SessionStorageFileIdentity;
+};
 export declare class FileSessionStorage implements SessionStorage {
+    #private;
     ensureDirSync(dir: string): void;
     existsSync(path: string): boolean;
     writeTextSync(fpath: string, content: string): void;
     readTextSync(fpath: string): string;
+    readBytesSync(fpath: string): Uint8Array;
+    readSnapshotSync(fpath: string): SessionStorageSnapshot;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
+    listFilesStrictSync(dir: string, pattern: string): string[];
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     readTextPrefix(path: string, maxBytes: number): Promise<string>;
@@ -54,15 +192,18 @@ export declare class FileSessionStorage implements SessionStorage {
     renameSync(path: string, nextPath: string): void;
     unlink(path: string): Promise<void>;
     unlinkSync(path: string): void;
-    openWriter(path: string, options?: {
-        flags?: "a" | "w";
-        onError?: (err: Error) => void;
-    }): SessionStorageWriter;
+    openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
     /**
      * Delete a session file and its artifacts directory.
      * Artifacts are stored in a sibling directory with the same name minus .jsonl extension.
      */
     deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    /**
+     * Verified hard delete bound to exact identity evidence. Artifact directory first,
+     * revalidate, transcript last. Partial deletion returns typed cleanup_pending
+     * evidence; identity/symlink/containment/header/cwd mismatch throws.
+     */
+    deleteSessionVerified(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
 }
 export declare class MemorySessionStorage implements SessionStorage {
     #private;
@@ -70,8 +211,11 @@ export declare class MemorySessionStorage implements SessionStorage {
     existsSync(path: string): boolean;
     writeTextSync(path: string, content: string): void;
     readTextSync(path: string): string;
+    readBytesSync(path: string): Uint8Array;
+    readSnapshotSync(path: string): SessionStorageSnapshot;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
+    listFilesStrictSync(dir: string, pattern: string): string[];
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     readTextPrefix(path: string, maxBytes: number): Promise<string>;
@@ -80,9 +224,7 @@ export declare class MemorySessionStorage implements SessionStorage {
     renameSync(path: string, nextPath: string): void;
     unlink(path: string): Promise<void>;
     unlinkSync(path: string): void;
-    deleteSessionWithArtifacts(_sessionPath: string): Promise<void>;
-    openWriter(path: string, options?: {
-        flags?: "a" | "w";
-        onError?: (err: Error) => void;
-    }): SessionStorageWriter;
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    deleteSessionVerified(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
+    openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
 }

package/dist/types/setup/credential-auto-import.d.ts

@@ -45,7 +45,7 @@ export interface CredentialAutoImportOptions {
     trigger: CredentialAutoImportTrigger;
     sourceLabel?: CredentialAutoImportSourceLabel;
 }
-export declare function runExternalCredentialAutoImport({ authStorage, discover, discoveryOptions }: CredentialAutoImportOptions): Promise<CredentialAutoImportResult>;
+export declare function runExternalCredentialAutoImport({ authStorage, discover, discoveryOptions, }: CredentialAutoImportOptions): Promise<CredentialAutoImportResult>;
 export declare function buildCredentialAutoImportNotice(result: Pick<CredentialAutoImportResult, "imported">): string | undefined;
 export declare function formatCredentialAutoImportResult(result: CredentialAutoImportResult): string[];
 export interface CredentialImportMarkerStore {
@@ -60,4 +60,4 @@ export interface StartupCredentialAutoImportOptions {
     agentDir?: string;
     markerStore?: CredentialImportMarkerStore;
 }
-export declare function runStartupCredentialAutoImportIfNeeded({ authStorage: activeAuthStorage, modelRegistry: activeModelRegistry, discover, version, agentDir, markerStore }: StartupCredentialAutoImportOptions): Promise<string | undefined>;
+export declare function runStartupCredentialAutoImportIfNeeded({ authStorage: activeAuthStorage, modelRegistry: activeModelRegistry, discover, version, agentDir, markerStore, }: StartupCredentialAutoImportOptions): Promise<string | undefined>;

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

@@ -11,6 +11,7 @@ import { Settings } from "../config/settings";
 import { type Skill } from "../extensibility/skills";
 import type { HindsightSessionState } from "../hindsight/state";
 import type { LocalProtocolOptions } from "../internal-urls";
+import { AgentRegistry } from "../registry/agent-registry";
 import type { ForkContextSeed } from "../session/agent-session";
 import type { ArtifactManager } from "../session/artifacts";
 import type { AuthStorage } from "../session/auth-storage";
@@ -61,6 +62,8 @@ export interface ExecutorOptions {
     authStorage?: AuthStorage;
     modelRegistry?: ModelRegistry;
     settings?: Settings;
+    /** 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

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

@@ -1,4 +1,4 @@
-import type { SingleResult, TaskToolDetails } from "./types";
+import { type SingleResult, type TaskToolDetails } from "./types";
 export interface TaskRoi {
     tokens: number;
     contextTokens?: number;
@@ -31,6 +31,7 @@ export interface TaskResultReceipt {
     modelSubstitutionWarning?: SingleResult["modelSubstitutionWarning"];
     usage?: SingleResult["usage"];
     cost?: number;
+    usageCostBreakdownComplete?: true;
     branchName?: string;
     retryFailure?: {
         attempt: number;
@@ -77,6 +78,7 @@ export interface RawTaskToolDetails {
     results: SingleResult[];
     totalDurationMs: number;
     usage?: TaskToolDetails["usage"];
+    usageCostBreakdownComplete?: TaskToolDetails["usageCostBreakdownComplete"];
     async?: TaskToolDetails["async"];
     forkContextClonedTokens?: number;
     roiSummary?: TaskToolDetails["roiSummary"];

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

@@ -387,6 +387,8 @@ export interface SingleResult {
     paused?: boolean;
     /** Aggregated usage from the subprocess, accumulated incrementally from message_end events. */
     usage?: Usage;
+    /** True only when every usage-contributing assistant supplied a complete, non-negative raw cost breakdown. */
+    usageCostBreakdownComplete?: true;
     /** Output path for the task result */
     outputPath?: string;
     /** Patch path for isolated worktree output */
@@ -430,6 +432,10 @@ export interface SingleResult {
         reasons: string[];
     };
 }
+/** True only for complete, factual five-bucket cost accounting. */
+export declare function hasCompleteUsageCostBreakdown(usage: unknown): boolean;
+/** True only when every usage-contributing result has explicit, complete cost provenance. */
+export declare function hasCompleteAggregateUsageCostBreakdown(results: readonly Pick<SingleResult, "usage" | "usageCostBreakdownComplete">[]): boolean;
 /** Tool details for TUI rendering */
 export interface TaskToolDetails {
     projectAgentsDir: string | null;
@@ -437,6 +443,8 @@ export interface TaskToolDetails {
     totalDurationMs: number;
     /** Aggregated usage across all subagents. */
     usage?: Usage;
+    /** True only when every usage-contributing subagent supplied a complete raw cost breakdown. */
+    usageCostBreakdownComplete?: true;
     /** Aggregate cloned tokens copied into fork-context seeds across subagents. */
     forkContextClonedTokens?: number;
     roiSummary?: {

package/dist/types/tools/ask-answer-registry.d.ts

@@ -6,8 +6,13 @@
  * through the extension/runner/controller wiring. A session has at most one
  * source; registering returns a disposer.
  */
+import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/unattended-session";
 import type { AskAnswerSource } from "./index";
 /** Register `source` for `sessionId`. Returns a disposer that clears it. */
 export declare function registerAskAnswerSource(sessionId: string, source: AskAnswerSource): () => void;
 /** The answer source for `sessionId`, if one is registered. */
 export declare function getAskAnswerSource(sessionId: string): AskAnswerSource | undefined;
+/** Publish a session's current workflow-gate emitter after mode initialization. */
+export declare function notifyWorkflowGateEmitterChanged(sessionId: string, emitter: WorkflowGateEmitter | undefined): void;
+/** Observe workflow-gate emitter installation even when it occurs after session_start. */
+export declare function registerWorkflowGateEmitterListener(sessionId: string, listener: (emitter: WorkflowGateEmitter | undefined) => void): () => void;

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

@@ -19,7 +19,7 @@ import { type Component } from "@gajae-code/tui";
 import * as z from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme } from "../modes/theme/theme";
-import type { ToolSession } from ".";
+import type { AskRemoteControl, AskRemoteInteraction, AskSettlement, AskSettlementResult, ToolSession } from ".";
 export declare const askSchema: z.ZodObject<{
     questions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -71,6 +71,30 @@ export interface AskToolDetails {
     /** Multi-part question mode */
     results?: QuestionResult[];
 }
+/** The only remote navigation control; labels are presentation, never protocol. */
+export declare function askRemoteControls(input: {
+    multi: boolean;
+    questionIndex: number;
+    questionCount: number;
+    selectedCount: number;
+    hasNonWhitespaceCustom: boolean;
+}): readonly AskRemoteControl[];
+/** Classify remote input without looking at option labels used for controls. */
+export declare function classifyAskRemoteInteraction(input: {
+    interaction: AskRemoteInteraction;
+    options: readonly string[];
+    controls: readonly AskRemoteControl[];
+    multi: boolean;
+    selectedCount: number;
+    customInput?: string;
+    clarification?: boolean;
+}): AskSettlement;
+/** A one-shot local receipt used to normalize legacy string answer sources. */
+export declare function legacyAskReceipt(value: string): {
+    source: "remote";
+    interaction: AskRemoteInteraction;
+    settle(settlement: AskSettlement): Promise<AskSettlementResult>;
+};
 type AskParams = AskToolInput;
 /**
  * Ask tool for interactive user prompting during execution.

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

@@ -86,7 +86,7 @@ export declare class BashTool implements AgentTool<BashToolSchema, BashToolDetai
         label: string;
         commandCwd: string;
     }>;
-    execute(_toolCallId: string, { command: rawCommand, env: rawEnv, timeout: rawTimeout, cwd, async: asyncRequested, pty }: BashToolInput, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<BashToolDetails>, ctx?: AgentToolContext): Promise<AgentToolResult<BashToolDetails>>;
+    execute(_toolCallId: string, { command: rawCommand, env: rawEnv, timeout: rawTimeout, cwd, async: asyncRequested, pty, }: BashToolInput, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<BashToolDetails>, ctx?: AgentToolContext): Promise<AgentToolResult<BashToolDetails>>;
 }
 export interface BashRenderArgs {
     command?: string;

package/dist/types/tools/browser/tab-supervisor.d.ts

@@ -60,6 +60,12 @@ export interface RunInTabOptions {
 }
 export interface ReleaseTabOptions {
     kill?: boolean;
+    /**
+     * Absolute end-to-end deadline (`Date.now()`-based, ms) for the whole teardown chain.
+     * Shared across a `releaseAllTabs` loop so close/close-all honors ONE aggregate budget.
+     * Omitted (the GC/session-teardown callers) keeps the original unbounded behavior.
+     */
+    deadlineAt?: number;
 }
 export declare function getTab(name: string): TabSession | undefined;
 /** Read-only, GC-facing projection of a live tab. Never exposes the mutable `tabs` map. */

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

@@ -70,16 +70,68 @@ export type ContextFileEntry = {
 };
 export type { DiscoverableMCPTool } from "../runtime-mcp/discoverable-tool-metadata";
 export type { DiscoverableTool, DiscoverableToolSearchIndex, DiscoverableToolSearchResult, DiscoverableToolSource, } from "../tool-discovery/tool-index";
+/** A typed remote action available to an ask answer source. */
+export type AskRemoteControlId = "navigation_forward";
+export interface AskRemoteControl {
+    id: AskRemoteControlId;
+    kind: "navigation";
+    label: "Next" | "Done";
+    enabled: boolean;
+}
+export interface AskAnswerRequest {
+    question: string;
+    options: string[];
+    interaction: "selector" | "custom_editor" | "clarification_editor";
+    controls: readonly AskRemoteControl[];
+}
+export type AskRemoteInteraction = {
+    kind: "value";
+    value: string;
+} | {
+    kind: "control";
+    controlId: AskRemoteControlId;
+};
+export type AskSettlement = {
+    kind: "commit";
+} | {
+    kind: "resolve_without_commit";
+    reason: "toggle" | "other_transition" | "clarification_transition" | "clarification_submitted" | "empty_navigation" | "back_navigation" | "cancelled" | "aborted" | "timed_out" | "exception" | "shutdown";
+} | {
+    kind: "invalid";
+    reason: "invalid_option" | "invalid_control" | "invalid_structured_answer" | "empty_custom" | "empty_clarification";
+};
+export type AskSelectedAckOutcome = {
+    status: "delivered";
+    messageId: number;
+} | {
+    status: "failed";
+    reason: "unsupported" | "no_participant" | "ambiguous_participant" | "route_missing" | "expired" | "cancelled" | "telegram_rejected" | "session_closed";
+} | {
+    status: "unknown";
+    reason: "transport_ambiguous" | "origin_disconnected" | "host_timeout" | "shutdown";
+};
+export type AskSettlementResult = {
+    kind: "committed";
+    ack: AskSelectedAckOutcome;
+} | {
+    kind: "resolved_without_commit";
+} | {
+    kind: "invalid_closed";
+};
+export interface AskRemoteReceipt {
+    source: "remote";
+    interaction: AskRemoteInteraction;
+    settle(value: AskSettlement): Promise<AskSettlementResult>;
+}
+export type AskAnswerSourceResult = AskRemoteReceipt | string | undefined;
 /**
- * Source of remote answers for interactive asks (e.g. a Telegram reply routed
- * through the notifications SDK). Lets a pending ask resolve without RPC mode.
+ * Source of remote answers. `awaitAnswer` remains the legacy wire for existing
+ * integrations; typed sources opt into `awaitAnswerRequest`. This keeps an old
+ * string-only source from accidentally acquiring acknowledgement authority.
  */
 export interface AskAnswerSource {
-    /**
-     * Race a remote answer against the local UI for one question. Resolves with the
-     * chosen option label or free-text answer, or `undefined` to defer to local UI.
-     */
     awaitAnswer(question: string, options: string[], signal?: AbortSignal): Promise<string | undefined>;
+    awaitAnswerRequest?(request: AskAnswerRequest, signal?: AbortSignal): Promise<AskAnswerSourceResult>;
 }
 /** Session context for tool factories */
 export interface ToolSession {