@robota-sdk/agent-session 3.0.0-beta.78 → 3.0.0-beta.81

package/dist/node/index.d.ts

@@ -1,6 +1,76 @@
-import { IAIProvider, IContextWindowState, IHistoryEntry, IHookTypeExecutor, ISpinner, ITerminalOutput, IToolSchema, IToolWithEventService, IUserInteraction, Robota, TModelEffort, TPermissionMode, TSessionEndReason, TToolArgs, TUniversalMessage, TUniversalValue } from "@robota-sdk/agent-core";
-import { ICompactEvent, TCompactTrigger } from "@robota-sdk/agent-interface-transport";
-
+import { IAIProvider, IContextWindowState, IEventService, IHistoryEntry, IHookTypeExecutor, IResponseFormatConfig, IRunTraceContext, ISpinner, ISubprocessTraceEnv, ITerminalOutput, IToolExecutionContext, IToolExecutionResult, IToolResultSpillStore, IToolSchema, IToolWithEventService, IUserInteraction, Robota, TBackgroundPermissionPolicy, TModelEffort, TModelEffortSelection, TPermissionMode, TSessionEndReason, TToolArgs, TToolChoice, TToolParameters, TUniversalMessage, TUniversalValue } from "@robota-sdk/agent-core";
+import { ICompactEvent, IInteractiveSessionRecord, IInteractiveSessionRecord as IInteractiveSessionRecord$1, IInteractiveSessionRecord as ISessionRecord, IInteractiveSessionStore, IInteractiveSessionStore as IInteractiveSessionStore$1, IInteractiveSessionStore as ISessionStore, IPromptHistoryBlock, IPromptHistoryEntry, IPromptHistoryReadOptions, IPromptHistorySource, IPromptHistoryWriter, ISessionListEntry, ISessionRecordDecodeIssue, TCompactTrigger, TPermissionResultValue, TSessionLoadOutcome } from "@robota-sdk/agent-interface-session";
+//#region src/turn-claim.d.ts
+/**
+ * Thrown when a turn is started on a session that is already running one. RUNTIME-003.
+ *
+ * A distinct type rather than a bare `Error`, because the point of giving the session a claim is to
+ * let consumers STOP maintaining their own busy flags — and a consumer that has to regex-match an
+ * error message to tell "busy, retry later" apart from a provider failure has not been given
+ * anything it can act on. Follows `CompactionError`, this package's existing precedent.
+ */
+declare class SessionBusyError extends Error {
+  /** Always `true`: the caller can run this turn later; nothing about the session is broken. */
+  readonly recoverable = true;
+  constructor(message: string);
+}
+/**
+ * The identity of the turn a session is currently running. RUNTIME-003.
+ *
+ * A session used to express "is something running?" as a bare `AbortController | null` field that
+ * `run()` overwrote on entry. That field was doing three jobs at once — cancellation channel, busy
+ * flag, and turn identity — and it could only do them for ONE turn, so a second concurrent `run()`
+ * orphaned the first: `abort()` reached only whichever turn held the field, and the first turn to
+ * finish cleared it in its `finally`, making `abort()` on the survivor a silent no-op. `isRunning()`
+ * read the same field, so it answered about whichever turn happened to own it. That is why consumers
+ * of this library grew their own busy flags rather than trusting it.
+ *
+ * The fix is to give the unit of work an OWNER. A claim is taken synchronously, it belongs to the
+ * caller that took it, and ONLY that caller releases it.
+ *
+ * REFUSAL, not pre-emption. A session is a single conversation: two turns interleaving on it produce
+ * a history neither of them wrote, and silently cancelling the first would discard work the caller
+ * never asked to abandon. `claim()` throws {@link SessionBusyError}, whose message names the three
+ * ways forward.
+ */
+declare class TurnClaim {
+  private controller;
+  /**
+   * Take the claim for a new turn, or throw if one is already held.
+   *
+   * MUST be called before the first `await` in the turn — a check that yields first is not a claim,
+   * it is a TOCTOU window, and two callers can pass it in the same tick.
+   *
+   * @throws {SessionBusyError} if a turn is already running, INCLUDING one that has been aborted but
+   *   has not finished unwinding. See {@link abort} for why that case is not an exception.
+   */
+  claim(): AbortController;
+  /**
+   * Release the claim — but only if `controller` is still the one holding it.
+   *
+   * The ownership check is what stops the original defect from reappearing in a new shape: a turn
+   * that released unconditionally in its `finally` could free a claim a LATER turn already took, and
+   * `isRunning()` would then report idle while a turn was in flight.
+   */
+  release(controller: AbortController): void;
+  /**
+   * Signal the running turn to stop. Idempotent; a no-op if nothing is running.
+   *
+   * This does NOT release the claim, and that is deliberate. An earlier version cleared it here, so
+   * `isRunning()` answered `false` the instant `abort()` returned — while the aborted turn was still
+   * unwinding, still able to write history and finish tool calls. A new `run()` could then claim the
+   * session and interleave with it: exactly the two-turns-on-one-session defect RUNTIME-003 is
+   * about, just moved behind the abort boundary. Review of the first draft caught it.
+   *
+   * A turn is not over when it is asked to stop; it is over when it has stopped. The claim is
+   * therefore held until the owning turn's `finally` releases it, and until then `isRunning()` says
+   * `true` and a further `run()` is refused. Cancel and restart is `abort()`, then AWAIT the turn,
+   * then `run()` — which is what every caller in this repo already does.
+   */
+  abort(): void;
+  isRunning(): boolean;
+}
+//#endregion
 //#region src/context-window-tracker.d.ts
 /** Auto-compact when context usage reaches this fraction */
 declare const AUTO_COMPACT_THRESHOLD = 0.835;
@@ -32,17 +102,68 @@ declare class ContextWindowTracker {
   reset(): void;
 }
 //#endregion
-//#region src/session-logger.d.ts
+//#region src/auto-mode-gate.d.ts
+/** The call the classifier judges. */
+interface IClassifiedCall {
+  readonly toolName: string;
+  readonly toolArgs: TToolArgs;
+  readonly cwd: string;
+}
+interface IClassifierVerdict {
+  readonly decision: 'allow' | 'block';
+  /** Short, for the model and the user: which rule, and why. */
+  readonly reason: string;
+}
+/**
+ * Judges one call. `undefined` means no usable verdict (an error, a refusal, output that does not
+ * parse): the call is not run. It counts toward a run of refusals, so a classifier that cannot
+ * answer hands the decision to a person instead of refusing every call.
+ */
+interface IPermissionClassifier {
+  classify(call: IClassifiedCall, signal?: AbortSignal): Promise<IClassifierVerdict | undefined>;
+}
+/** Refusals in a row (blocks or unusable verdicts), and blocks in the session, that pause the mode. */
+declare const CONSECUTIVE_BLOCK_LIMIT = 3;
+declare const TOTAL_BLOCK_LIMIT = 20;
+/** `reason` is for the user (`/permissions`); `message` is what the model is told. */
+type TAutoModeJudgement = {
+  readonly kind: 'allow';
+} | {
+  readonly kind: 'block';
+  readonly reason: string;
+  readonly message: string;
+} | {
+  readonly kind: 'unusable';
+  readonly reason: string;
+  readonly message: string;
+};
+declare class AutoModeGate {
+  private readonly classifier;
+  private consecutive;
+  private total;
+  private paused;
+  /** Calls a person allowed to be retried once after the classifier blocked them. */
+  private readonly retries;
+  constructor(classifier: IPermissionClassifier);
+  /** The mode asks a person until one approves. */
+  isPaused(): boolean;
+  /** A person approved while paused: the classifier decides again. */
+  resume(): void;
+  /** Let this exact call through once, without the classifier. */
+  grantRetry(toolName: string, toolArgs: TToolArgs): void;
+  /** Consume a retry grant for this exact call, if there is one. */
+  takeRetry(toolName: string, toolArgs: TToolArgs): boolean;
+  judge(call: IClassifiedCall, signal?: AbortSignal): Promise<TAutoModeJudgement>;
+}
+//#endregion
+//#region src/session-log-reference-types.d.ts
 /**
- * Session Logger — pluggable logging interface for session events.
+ * Leaf type module for {@link IExternalPayloadReference}.
  *
- * ISessionLogger defines the contract. FileSessionLogger is the default
- * implementation that writes JSONL to disk. Consumers can implement their
- * own (e.g., remote, database, silent) and inject via Session constructor.
+ * Split out of `session-logger.ts` so `session-log-sinks.ts` and `session-log-payload.ts` can
+ * depend on this type without importing back from `session-logger.ts`, which previously created
+ * import cycles among the three files.
  */
-/** Session log event data — extensible record of event metadata. */
-type TSessionLogValue = string | number | boolean | object | null | undefined;
-type TSessionLogData = Record<string, TSessionLogValue>;
 interface IExternalPayloadReference {
   kind: 'external-payload';
   encoding: 'json';
@@ -50,10 +171,37 @@ interface IExternalPayloadReference {
   byteLength: number;
   relativePath: string;
 }
+/** Session log event data — extensible record of event metadata. */
+type TSessionLogValue = string | number | boolean | object | null | undefined;
+type TSessionLogData = Record<string, TSessionLogValue>;
 interface IFileSessionLoggerOptions {
   externalPayloadThresholdBytes?: number;
   redactedValue?: string;
 }
+//#endregion
+//#region src/session-log-sinks.d.ts
+/** Canonical validation and construction for every session-log external-payload reference. */
+declare function createSessionLogExternalPayloadReference(sessionId: string, sha256: string, serialized: string): IExternalPayloadReference;
+/** Workspace-neutral sink for content-addressed external JSON payloads. */
+interface IExternalPayloadSink {
+  writeJson(sessionId: string, sha256: string, serialized: string): IExternalPayloadReference;
+}
+/** Workspace-neutral append sink for session-log bytes. */
+interface ISessionLogSink {
+  append(sessionId: string, text: string): void;
+  readonly externalPayloadSink?: IExternalPayloadSink;
+}
+/** Explicit host-filesystem sink for JSONL logs and their content-addressed sidecars. */
+declare class NodeSessionLogSink implements ISessionLogSink, IExternalPayloadSink {
+  private readonly logDirectory;
+  readonly externalPayloadSink: IExternalPayloadSink;
+  private readonly enabled;
+  constructor(logDirectory: string);
+  append(sessionId: string, text: string): void;
+  writeJson(sessionId: string, sha256: string, serialized: string): IExternalPayloadReference;
+}
+//#endregion
+//#region src/session-logger.d.ts
 /**
  * Session logger interface — injected into Session for pluggable logging.
  *
@@ -63,33 +211,59 @@ interface IFileSessionLoggerOptions {
 interface ISessionLogger {
   /** Log a session event with structured data. */
   log(sessionId: string, event: string, data: TSessionLogData): void;
+  /**
+   * Write out anything buffered.
+   *
+   * Optional because an implementation that never buffers has nothing to do. A caller that needs
+   * the log to be complete on disk — session end, or a reader about to parse it — calls this.
+   */
+  flush?(): void;
 }
 /**
- * File-based session logger — writes JSONL to {logDir}/{sessionId}.jsonl.
+ * Sink-driven session logger — writes JSONL through `ISessionLogSink`.
  *
  * This is the default implementation used by the CLI.
  * Each line is a self-contained JSON object with timestamp, sessionId, event, and data.
  */
 declare class FileSessionLogger implements ISessionLogger {
-  private readonly logDir;
+  private readonly sink;
   private readonly options;
-  constructor(logDir: string, options?: IFileSessionLoggerOptions);
+  /** Buffered hot-path lines, per session file. Keyed by session id (CORE-029). */
+  private readonly pending;
+  private pendingBytes;
+  constructor(sink: ISessionLogSink, options?: IFileSessionLoggerOptions);
   log(sessionId: string, event: string, data: TSessionLogData): void;
+  /** Write out every buffered hot-path line. Safe to call when nothing is pending. */
+  flush(): void;
+  private buffer;
+  private write;
+  private report;
 }
-/** No-op logger — used when logging is disabled. */
 declare class SilentSessionLogger implements ISessionLogger {
   log(): void;
 }
 //#endregion
 //#region src/permission-types.d.ts
+/** The part of a sandbox client the permission gate consults. */
+interface ICommandSandboxApproval {
+  /**
+   * Whether `toolName` runs `shellCommand` inside the sandbox and the sandbox's settings let it
+   * proceed without a prompt. Only a tool the sandbox actually wraps may answer yes.
+   */
+  autoApproves(toolName: string, shellCommand: string): boolean;
+}
 /**
- * Permission handler result:
+ * Permission handler result (issue #2052: the union is OWNED by `agent-interface-session` as
+ * `TPermissionResultValue`; this name is the session-layer alias, not a second declaration):
  * - true: allow this invocation
  * - false: deny this invocation
- * - 'allow-session': allow this invocation and auto-approve this tool for the rest of the session
- * - 'allow-project': allow this invocation and persist the approval to .robota/settings.local.json
+ * - 'allow-session': allow this invocation and auto-approve the CONSENT SCOPE — the pattern
+ *   `consentScopeFor` projects from this invocation's argument (issue #2351), e.g. `Bash(git *)` —
+ *   for the rest of the session
+ * - 'allow-project': allow this invocation and persist that same scope pattern to the project's
+ *   local settings; the storage location is owned by the consuming layer (via `onProjectAllowTool`)
  */
-type TPermissionResult = boolean | 'allow-session' | 'allow-project';
+type TPermissionResult = TPermissionResultValue;
 /**
  * Custom permission handler — called when a tool needs user approval.
  * Returns true to allow, false to deny, or 'allow-session' to remember for the session.
@@ -100,12 +274,34 @@ interface IPermissionEnforcerOptions {
   cwd: string;
   getPermissionMode: () => TPermissionMode;
   config: {
+    /** `ask` patterns always ask, in every mode including bypassPermissions (issue #3081). */
     permissions: {
       allow: string[];
       deny: string[];
+      ask?: string[];
     };
     hooks?: Record<string, unknown>;
   };
+  /**
+   * The OS sandbox the shell tools run under, when there is one: whether it confines a command and
+   * lets it run without a prompt.
+   */
+  commandSandbox?: ICommandSandboxApproval;
+  /** Where `~` and `$HOME` point for critical-path removal checks. Defaults to the OS home directory. */
+  homeDirectory?: string;
+  /**
+   * ARCH-040 Group C (issue #1934): the rules BEFORE any preset contributed.
+   *
+   * Supplied by the composition root, never derived here. `config.permissions` already carries the
+   * STARTUP preset's patterns, so capturing a base from it on the first live `/preset` would keep
+   * the first preset's allowlist through every later switch — the accumulation the replace rule
+   * exists to prevent, arriving through the base rather than through the merge. Absent ⇒ no preset
+   * contributed, and `config.permissions` is itself the preset-free base.
+   */
+  presetFreePermissions?: {
+    allow: readonly string[];
+    deny: readonly string[];
+  };
   terminal: ITerminalOutput;
   permissionHandler?: TPermissionHandler;
   promptForApprovalFn?: (terminal: ITerminalOutput, toolName: string, toolArgs: TToolArgs) => Promise<TPermissionResult>;
@@ -125,6 +321,45 @@ interface IPermissionEnforcerOptions {
   transcriptPath?: string;
   /** Called when the user selects "allow for project" — persists the tool pattern to project settings. */
   onProjectAllowTool?: (toolName: string) => void;
+  /**
+   * CORE-025: a background/subagent task permission policy. It adds a ceiling (checked before bypass),
+   * an ask-everything flag and the task's own lists to the one evaluator, so `deny`/`preapproved`/
+   * `inherit-allowlist` still bind under a permissive mode. Absent → no policy constraints.
+   */
+  permissionPolicy?: TBackgroundPermissionPolicy;
+  /**
+   * CORE-025: the task's OWN declared allow/deny rules (distinct from the parent session's `config.permissions`
+   * which `inherit-allowlist` inherits). `preapproved` consults these.
+   */
+  taskPermissions?: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+  };
+  /**
+   * Judges, in `auto` mode, the calls the mode would otherwise ask a person about. Absent → the
+   * session cannot enter `auto`.
+   */
+  permissionClassifier?: IPermissionClassifier;
+}
+//#endregion
+//#region src/permission-denial-log.d.ts
+/**
+ * Why a call was refused:
+ * - `policy`      — the gate answered deny: a deny rule, a background ceiling, or plan mode;
+ * - `user`        — a person was asked and declined, or the turn was cancelled while asking;
+ * - `no-approver` — the call needed a person and none was attached;
+ * - `classifier`  — in `auto` mode, the classifier blocked the call or gave no usable verdict.
+ */
+type TPermissionDenialReason = 'policy' | 'user' | 'no-approver' | 'classifier';
+interface IPermissionDenial {
+  readonly toolName: string;
+  /** The argument the tool's permission profile names (command, path, URL), when it has one. */
+  readonly argument?: string;
+  readonly reason: TPermissionDenialReason;
+  /** The classifier's reason, for a `classifier` denial. */
+  readonly detail?: string;
+  /** Epoch milliseconds. */
+  readonly at: number;
 }
 //#endregion
 //#region src/permission-enforcer.d.ts
@@ -140,30 +375,129 @@ declare class PermissionEnforcer {
   private readonly onToolExecution?;
   private readonly hookTypeExecutors?;
   private readonly transcriptPath?;
+  /**
+   * Issue #2351: consent is remembered as PATTERNS (`consentScopeFor`), not tool names, and read
+   * back through the gate's own matcher — approving one argument does not allow every argument.
+   */
   private readonly sessionAllowedTools;
+  /** The configured rules before any preset contributed — see {@link applyPresetToolLists}. */
+  private readonly presetFreeRules;
   private readonly onProjectAllowTool?;
+  private readonly permissionPolicy?;
+  private readonly taskPermissions?;
+  private readonly homeDirectory;
+  private readonly resolveInWorkspace;
+  private readonly commandSandbox?;
+  private readonly denials;
+  /** A turn a peer's message started is in progress: the one place the reply to that peer exists. */
+  private peerTurn;
+  private readonly autoMode?;
   constructor(options: IPermissionEnforcerOptions);
+  /**
+   * Start a turn, which a peer's message started when `peerTurn` is true. That decides only whether
+   * the reply to the peer exists; every other call is decided exactly as in any turn.
+   */
+  beginTurn(peerTurn: boolean): void;
+  /** End the turn; the reply to a peer is gone until the next peer turn begins. */
+  endTurn(): void;
+  /** Whether `auto` mode can run here: it needs a classifier to decide for it. */
+  hasPermissionClassifier(): boolean;
+  /**
+   * Let the call behind a classifier denial run once, unjudged, when the model tries it again.
+   * Returns the denial, or `undefined` when `index` names no classifier denial.
+   */
+  allowRetryOfDenial(index: number): IPermissionDenial | undefined;
+  /** Every configured pattern, split by the grammar it is held to. */
+  private configuredRules;
+  /**
+   * Whether the model is shown this tool at all. A bare-name deny (`Tool`, `Tool(*)`, a name glob)
+   * removes it rather than offering it and refusing every call (issue #3081). Read live, so a
+   * `/preset` that denies a tool hides it from the next round.
+   */
+  isToolVisible(toolName: string): boolean;
+  /**
+   * Tell the gate each tool's parameter names — the schema is what makes `Tool(name:value)` a
+   * parameter rule — then re-check the rules against them, before any turn runs.
+   */
+  private registerToolParameters;
   /** Wrap all tools with permission checking */
   wrapTools(tools: IToolWithEventService[]): IToolWithEventService[];
-  /** Get tools that have been session-approved (via "Allow always" choice). */
+  /** The consent patterns granted this session via "Allow always" — e.g. `Bash(git *)` (issue #2351). */
   getSessionAllowedTools(): string[];
+  /** The calls this session refused, most recent first (issue #3082). */
+  getRecentDenials(): readonly IPermissionDenial[];
   /** Clear all session-scoped allow rules. */
   clearSessionAllowedTools(): void;
   /**
-   * Wrap a tool with permission checking.
-   * The wrapper intercepts execute() and runs permission evaluation before delegating.
-   * If denied, returns a tool result indicating the action was blocked.
+   * Replace the configured permission rules on a LIVE session (ARCH-040 Group C, issue #1934).
+   *
+   * The seam is this small because `checkPermission` reads `this.config.permissions` on every call
+   * rather than snapshotting it at construction — so the next call sees the new rules and nothing
+   * needs re-wiring. Without a seam the startup path could apply a preset's tool lists and the live
+   * `/preset` path could not, which is the divergence `scan-preset-projection` exists to measure:
+   * one session holding two answers for the same preset depending on WHEN it was chosen.
+   *
+   * **A call already in flight runs to completion.** `checkPermission` is awaited BEFORE the tool
+   * executes, so such a call has already passed its gate, and a gate is a decision at a point in
+   * time. There is also no rollback for a partially applied tool — a file already written stays
+   * written — so a revocation that cannot undo is a stop, not a denial. Building one would rest on
+   * the cancellation path, which RUNTIME-004 records as declared at four layers and honoured at none.
+   *
+   * A newly applied denial DOES outrank an earlier "always allow": `evaluatePermission` answers
+   * `deny` before `promptForApproval` — the only reader of `sessionAllowedTools` — is reached. That
+   * is not new behaviour here; it is the existing precedence, and it agrees with the combine rule
+   * that a denial is not weakened by a later layer.
    */
-  private wrapToolWithPermission;
-  /** Evaluate permission for a tool call using the current mode and config */
-  checkPermission(toolName: string, toolArgs: TToolArgs): Promise<boolean>;
+  /**
+   * The rules the next `checkPermission` will read.
+   *
+   * Exposed so a case can assert what a live re-application PRODUCED, not merely that the method
+   * exists. Review found the first cut composing onto a contaminated base and no test could see it,
+   * because nothing could look at the rules.
+   */
+  currentPermissionRules(): {
+    allow: readonly string[];
+    deny: readonly string[];
+    ask: readonly string[];
+  };
+  applyPresetToolLists(preset: {
+    allowedTools?: readonly string[];
+    deniedTools?: readonly string[];
+  }): void;
+  /** Evaluate permission for a tool call. `signal` — RUNTIME-005; see `decideApproval` for why a
+   * cancelled approval denies. */
+  checkPermission(toolName: string, toolArgs: TToolArgs, signal?: AbortSignal, interaction?: IToolExecutionContext['permissionInteraction'], hookTraceEnv?: IToolExecutionContext['hookTraceEnv']): Promise<boolean>;
+  /**
+   * Decide an action that has `toolName`'s effect but does not run through that tool — a command
+   * that starts a process, say. It passes what the tool call would: the PreToolUse hooks (so
+   * guardrails apply), then the gate's rules, mode, remembered consent and prompt. It never takes
+   * the command sandbox's auto-approval, because the action does not run inside that sandbox.
+   */
+  checkDelegatedToolCall(toolName: string, toolParameters: TToolParameters, signal?: AbortSignal): Promise<boolean>;
+  /** {@link checkPermission}, keeping the reason a refusal carries for the model. */
+  private decidePermission;
+  private decideInAutoMode;
+  /**
+   * The human-approval path: session-scoped allow list → custom handler → injected approval fn → fail-closed
+   * deny. Every `approve` decision comes here, whoever the caller, so every ask fails closed identically
+   * when no approver is attached (e.g. a detached background task).
+   */
+  private promptForApproval;
+  /**
+   * SELFHOST-009: fire the PermissionDecision hook (informational-only, non-blocking) via the shared
+   * `runHooks` path. Fire-and-forget — the result is never awaited or consulted, so it cannot gate the
+   * permission outcome. The sole blocking gate remains PreToolUse (`runPreToolHook`).
+   */
+  private firePermissionDecisionHook;
+  /** Whether the OS sandbox confines this shell command and lets it run without a prompt. */
+  private sandboxAutoApproves;
   /** Delegate session event to the injected logger. */
   private log;
 }
 //#endregion
 //#region src/session-base.d.ts
 declare abstract class SessionBase {
-  protected abstract readonly robota: Robota;
+  protected abstract readonly agent: Robota;
   protected abstract readonly permissionEnforcer: PermissionEnforcer;
   protected abstract readonly contextTracker: ContextWindowTracker;
   protected abstract permissionMode: TPermissionMode;
@@ -175,10 +509,21 @@ declare abstract class SessionBase {
   protected abstract model: string;
   protected abstract systemMessage: string;
   protected abstract messageCount: number;
-  protected abstract abortController: AbortController | null;
+  /** ARCH-010: the session's execution root — owned here, with the check that it was supplied. */
+  protected readonly cwd: string;
+  protected constructor(cwd: string);
+  /**
+   * RUNTIME-003: the turn currently running, and its owner. Was a bare `AbortController | null` that
+   * `run()` overwrote, which is why `abort()` and `isRunning()` below could answer about a turn that
+   * was not the one in flight. See `turn-claim.ts`.
+   */
+  protected readonly turnClaim: TurnClaim;
+  private readonly permissionModeGuards;
   getPermissionMode(): TPermissionMode;
   /** Change the active permission mode — future tool calls will use the new mode. */
   setPermissionMode(mode: TPermissionMode): void;
+  /** Register a synchronous policy check at the single session-mode mutation boundary. */
+  addPermissionModeGuard(guard: (next: TPermissionMode) => void): () => void;
   /** Read the active preset id (PRESET-011 runtime state). */
   getActivePresetId(): string;
   /**
@@ -192,6 +537,14 @@ declare abstract class SessionBase {
   /** Toggle subagent dispatch live. Only effective if the agent runtime was built at assembly. */
   setParallelSubagentsEnabled(enabled: boolean): void;
   getSessionId(): string;
+  /**
+   * The session's execution root (ARCH-010).
+   *
+   * Readable because a caller that derives something FROM the session — a fork, a subagent, a hook
+   * input — must be able to ask which root this session actually runs in. Re-deriving it from
+   * `process.cwd()` is how the two silently diverged.
+   */
+  getCwd(): string;
   getSystemMessage(): string;
   /**
    * Replace the active system message and propagate it so the next provider request carries it.
@@ -211,14 +564,68 @@ declare abstract class SessionBase {
    */
   applyModelOptions(options: {
     model?: string;
-    effort?: TModelEffort;
+    effort?: TModelEffortSelection;
     temperature?: number;
     maxOutputTokens?: number;
   }): Promise<void>;
+  /** Read the selection for the next model call; provider default remains `auto`. */
+  getModelEffort(): TModelEffortSelection;
+  /** Run an operation with a temporary effort override and restore it on every exit path. */
+  withScopedModelEffort<T>(effort: TModelEffort, operation: () => Promise<T>): Promise<T>;
+  /**
+   * Re-apply the agent's identity label to a LIVE session.
+   *
+   * ARCH-040 (issue #1820): a preset's `agentName` reached the agent only at construction, so
+   * starting with a preset set the name while switching to the SAME preset mid-session left the old
+   * one — one preset with two answers, decided by when it was chosen.
+   *
+   * Goes through `updateConfiguration`, the agent's own config seam: the agent's `name` reads THROUGH
+   * its config, so writing the config is the whole rename and no copy is left stale.
+   */
+  applyAgentName(name: string): Promise<void>;
   getToolSchemas(): IToolSchema[];
   getMessageCount(): number;
   /** Get tools that have been session-approved (via "Allow always" choice). */
+  /**
+   * ARCH-040 Group C (issue #1934): re-apply a preset's tool lists to the live enforcer.
+   *
+   * The BASE it composes onto is the session's configured rules minus whatever a previous preset
+   * contributed — which is why the enforcer keeps the original: an allowlist REPLACES the preset
+   * layer's contribution rather than accumulating across successive `/preset` switches, while a
+   * denial UNIONS because it must not be weakened by a later layer that forgot to repeat it.
+   */
+  applyPresetToolLists(preset: {
+    allowedTools?: readonly string[];
+    deniedTools?: readonly string[];
+  }): void;
+  /**
+   * The rules this session's gate reads right now — settings, preset lists and command auto-allows
+   * together — so a subagent inherits what the parent actually enforces (issue #3081). Session-scoped
+   * "allow always" consent is not included: it was given for this session's context.
+   */
+  getPermissionRules(): {
+    allow: string[];
+    deny: string[];
+    ask: string[];
+  };
   getSessionAllowedTools(): string[];
+  /**
+   * Decide an action that reaches `toolName`'s effect by another route (a command that starts a
+   * process), so that route cannot be a way around the tool's own permission: the PreToolUse hooks
+   * and guardrails, then the rules, mode, remembered consent and the prompt. The command sandbox's
+   * auto-approval never applies, because the action does not run inside that sandbox.
+   */
+  checkToolPermission(toolName: string, toolParameters: TToolParameters, signal?: AbortSignal): Promise<boolean>;
+  /** `auto` mode hands decisions to a classifier, so a session without one cannot enter it. */
+  protected requireClassifierFor(mode: TPermissionMode): void;
+  /**
+   * Let the call behind a classifier denial (by its index in the recent denials) run once when the
+   * model tries it again. Returns the denial, or `undefined` when the index names no classifier
+   * denial.
+   */
+  retryPermissionDenial(index: number): IPermissionDenial | undefined;
+  /** The calls this session refused, most recent first (issue #3082). */
+  getRecentPermissionDenials(): readonly IPermissionDenial[];
   clearSessionAllowedTools(): void;
   /** Abort the currently running execution. No-op if nothing is running. */
   abort(): void;
@@ -235,6 +642,17 @@ declare abstract class SessionBase {
     outputTokens: number;
   } | undefined;
   getModelId(): string;
+  /**
+   * The tool schemas the model is offered at the next request (CLI-1990).
+   *
+   * The offered set, not the registered one: a deferred tool that has not been loaded is absent,
+   * because it is absent from the request. `/context` reads this to report what the tool schemas
+   * actually cost, which is the only surface that makes deferral's saving observable.
+   */
+  getOfferedToolSchemas(): IToolSchema[];
+  /** The provider the session sends its turns to now; a provider switch replaces it. */
+  getProvider(): IAIProvider;
+  getProviderId(): string;
   /** Add an event entry to history (not a chat message) */
   addHistoryEntry(entry: IHistoryEntry): void;
   /** Inject a message into conversation history without execution (used for session restore). */
@@ -250,94 +668,6 @@ declare abstract class SessionBase {
   clearHistory(): void;
 }
 //#endregion
-//#region src/session-store.d.ts
-/** A persisted session record */
-interface ISessionRecord {
-  /** Unique session identifier */
-  id: string;
-  /** Optional human-readable session name */
-  name?: string;
-  /** Working directory when the session was created */
-  cwd: string;
-  /** ISO-8601 creation timestamp */
-  createdAt: string;
-  /** ISO-8601 last-updated timestamp */
-  updatedAt: string;
-  /** Conversation messages (opaque to the store) */
-  messages: unknown[];
-  /** Full UI timeline (chat + events) for rendering restoration */
-  history?: unknown[];
-  /** Exact system prompt used to create the session. */
-  systemPrompt?: string;
-  /** Tool schemas registered for the session. */
-  toolSchemas?: IToolSchema[];
-  /** Latest background task snapshots for resume/debugging. */
-  backgroundTasks?: unknown[];
-  /** Durable non-streaming background task events for resume/debugging. */
-  backgroundTaskEvents?: unknown[];
-  /** Latest background job group snapshots for resume/debugging. */
-  backgroundJobGroups?: unknown[];
-  /** Durable background job group events for resume/debugging. */
-  backgroundJobGroupEvents?: unknown[];
-  /** Durable skill activation events for resume/debugging. */
-  skillActivationEvents?: unknown[];
-  /** Durable automatic memory events for resume/debugging. */
-  memoryEvents?: unknown[];
-  /** Memory references used by the latest prompt turn. */
-  usedMemoryReferences?: unknown[];
-  /** SDK-owned context reference inventory for resume/debugging. */
-  contextReferences?: unknown[];
-  /** Provider sandbox snapshot identifier for workspace hydration on resume. */
-  sandboxSnapshotId?: string;
-}
-/** Minimal persistence port consumed by Session. */
-interface ISessionStore {
-  save(session: ISessionRecord): void;
-  load(id: string): ISessionRecord | undefined;
-  list(): ISessionRecord[];
-  delete(id: string): void;
-  /** Return the absolute file path for a session file, if the store is file-backed. */
-  getFilePath?(id: string): string;
-}
-/**
- * Persistent session store backed by individual JSON files.
- *
- * Construct with a custom `baseDir` to redirect storage (useful in tests).
- */
-declare class SessionStore implements ISessionStore {
-  private readonly baseDir;
-  constructor(baseDir?: string);
-  /** Ensure the storage directory exists */
-  private ensureDir;
-  /** Absolute path to a session's JSON file */
-  private filePath;
-  /** Return the absolute file path for a session — implements ISessionStore.getFilePath */
-  getFilePath(id: string): string;
-  /**
-   * Persist a session record to disk atomically (CORE-019).
-   * Creates the storage directory if needed.
-   *
-   * Bytes go to a same-directory temp file first, then move into place with rename —
-   * a crash mid-write can therefore never leave a truncated JSON where the previous
-   * record used to be. Same-directory is load-bearing: cross-device rename is a copy.
-   */
-  save(session: ISessionRecord): void;
-  /**
-   * Load a session by its ID.
-   * Returns `undefined` when the session file does not exist or is corrupt.
-   */
-  load(id: string): ISessionRecord | undefined;
-  /**
-   * List all persisted sessions, sorted by `updatedAt` descending (most recent first).
-   */
-  list(): ISessionRecord[];
-  /**
-   * Delete a session by its ID.
-   * No-ops silently if the session does not exist.
-   */
-  delete(id: string): void;
-}
-//#endregion
 //#region src/session-types.d.ts
 /** Options for graceful session shutdown. */
 interface ISessionShutdownOptions {
@@ -347,20 +677,65 @@ interface ISessionShutdownOptions {
 interface ISessionOptions {
   /** Pre-constructed tools to register with the agent */
   tools: IToolWithEventService[];
+  /**
+   * Applies to a tool added after construction (`Session.addTools`) the wrappers the assembler
+   * applied to `tools`, so a late tool is held to the same safety policy as one present from the
+   * start. The permission gate is applied by the session itself either way.
+   */
+  wrapAddedTools?: (tools: IToolWithEventService[]) => IToolWithEventService[];
   /** Pre-constructed AI provider */
   provider: IAIProvider;
   /** Pre-built system message string */
   systemMessage: string;
   /** Terminal I/O for permission prompts */
   terminal: ITerminalOutput;
+  /**
+   * The session's execution root. REQUIRED — ARCH-010.
+   *
+   * This field did not exist. `Session` read `process.cwd()` in its constructor and that ambient
+   * value became the session's identity everywhere it matters: every hook input,
+   * `CLAUDE_PROJECT_DIR`, `PermissionEnforcer`'s root, and the persisted record. Meanwhile the
+   * subagent spawn contract has always declared `cwd` REQUIRED — and the in-process runner passed
+   * none, because there was no option to pass it to. A session that cannot be told where it runs
+   * silently runs wherever the process happens to be, which for a subagent is not its own workspace.
+   *
+   * A caller that genuinely means "this process's directory" passes `process.cwd()` where a reader
+   * can see the decision.
+   */
+  cwd: string;
   /** Permission and hook configuration */
   permissions?: {
     allow: string[];
     deny: string[];
+    ask?: string[];
+  };
+  /**
+   * ARCH-040 Group C (issue #1934): the permission rules BEFORE any preset contributed.
+   *
+   * Passed rather than inferred. `permissions` above already has the startup preset's patterns baked
+   * in, so an enforcer that captured its own base from it on the first live `/preset` would keep the
+   * FIRST preset's allowlist forever — the accumulation the replace rule exists to prevent, arriving
+   * through the base instead of through the merge. Absent ⇒ no preset contributed and the two are
+   * the same.
+   */
+  presetFreePermissions?: {
+    allow: readonly string[];
+    deny: readonly string[];
   };
   hooks?: Record<string, unknown>;
   /** Initial permission mode */
   permissionMode?: TPermissionMode;
+  /**
+   * CORE-025: background/subagent task permission policy. Resolved BEFORE the session-mode gate, so
+   * `deny`/`preapproved`/`inherit-allowlist` override even a permissive `permissionMode`. Absent on a normal
+   * interactive session (mode gate alone). Set by `createSubagentSession` from the spawn request.
+   */
+  permissionPolicy?: TBackgroundPermissionPolicy;
+  /** CORE-025: the task's OWN allow/deny lists (what `preapproved` consults; distinct from `permissions`). */
+  taskPermissions?: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+  };
   /**
    * Injected "ask the user" port (CMD-005): forwarded into the agent config so model-invoked tools
    * (AskUserQuestion) can solicit a structured answer. Absent in headless/automation sessions.
@@ -382,11 +757,15 @@ interface ISessionOptions {
   /** Maximum number of agentic turns per run() call. Undefined = unlimited. */
   maxTurns?: number;
   /** Optional session store for persistence */
-  sessionStore?: ISessionStore;
+  sessionStore?: IInteractiveSessionStore$1;
   /** Override session ID (used when resuming a session to reuse the original ID) */
   sessionId?: string;
   /** Custom permission handler (overrides terminal-based prompts, used by Ink UI) */
   permissionHandler?: TPermissionHandler;
+  /** The OS sandbox the shell tools run under, which may let a confined command skip the prompt. */
+  commandSandbox?: ICommandSandboxApproval;
+  /** Decides for `auto` mode. Without one the session refuses that mode. */
+  permissionClassifier?: IPermissionClassifier;
   /** Called when the user selects "allow for project" — persists the tool pattern to project settings. */
   onProjectAllowTool?: (toolName: string) => void;
   /** Callback for text deltas — enables streaming text to the UI in real-time */
@@ -409,33 +788,112 @@ interface ISessionOptions {
   onCompact?: (summary: string) => void;
   /** Callback with structured compaction metadata */
   onCompactEvent?: (event: ICompactEvent) => void;
-  /** Instructions to include in the compaction prompt (e.g. from CLAUDE.md) */
+  /** Instructions to include in the compaction prompt (e.g. from project context files) */
   compactInstructions?: string;
+  /**
+   * Replaces the base instruction template of the compaction summarization prompt
+   * (default: `DEFAULT_COMPACTION_PROMPT`, a domain-neutral template). Lets the consuming
+   * layer own the compaction prompt wording entirely.
+   */
+  compactionBasePrompt?: string;
+  /**
+   * Concrete remediation wording for the core's hard-capacity notice, forwarded to the Robota
+   * agent config as `IAgentConfig.contextCapacityHint`. The zero-dependency core emits a
+   * product-neutral default; a surface tier that owns a real remediation command (e.g. a
+   * `/compact` slash command) injects its own actionable hint here. Absent ⇒ the neutral
+   * `DEFAULT_CONTEXT_CAPACITY_HINT` applies.
+   */
+  contextCapacityHint?: string;
   /** Override context max tokens (otherwise derived from model name) */
   contextMaxTokens?: number;
   /** Auto-compact threshold as a 0-1 fraction. Set false to disable automatic compaction. */
   autoCompactThreshold?: TAutoCompactThreshold;
   /** Session logger — injected for pluggable session event logging. */
   sessionLogger?: ISessionLogger;
+  /** Host-projected transcript path for hook compatibility; never inferred from a record store. */
+  transcriptPath?: string;
   /** Additional hook type executors (e.g. prompt, agent) beyond the core defaults. */
   hookTypeExecutors?: IHookTypeExecutor[];
   /** Name reported to the Robota agent config. Defaults to 'agent' if not provided. */
   agentName?: string;
-  /** Request structured output from the provider for this session. */
-  responseFormat?: {
-    type: 'text' | 'json_object';
-  };
   /**
-   * Reasoning-effort dial threaded to the Robota agent config and on to the provider
-   * request builder. When unset, the framework→provider seam defaults it to `'high'`.
+   * Request structured output from the provider for this session. Issue #2056: the agent config's
+   * own shape (`json_schema` included), so a schema request reaches the provider intact.
+   */
+  responseFormat?: IResponseFormatConfig;
+  /**
+   * Reasoning-effort selection threaded to the Robota agent config and provider boundary.
+   * When unset, Core preserves provider-default selection as `auto`.
+   */
+  effort?: TModelEffortSelection;
+  /**
+   * ARCH-040: sampling temperature and output cap, threaded to the agent config at CONSTRUCTION.
+   *
+   * The live `/preset` path has always applied both through `applyModelOptions`, and startup applied
+   * neither — so one session held two answers for the same preset depending on WHEN it was chosen,
+   * which is what `effort` did before ARCH-013 stage 1 fixed it. `maxOutputTokens` maps to the
+   * agent's `maxTokens` channel, the same name `applyModelOptions` already writes.
    */
-  effort?: TModelEffort;
+  temperature?: number;
+  maxOutputTokens?: number;
+}
+/**
+ * The per-TURN options a caller may attach to one `Session.run()`.
+ *
+ * Both are optional and independent, and both are absent on the dominant path, so they are spread
+ * as a group rather than tested one at a time at each call site.
+ */
+interface ISessionRunOptions {
+  /** Cancellation belongs to this submission and remains linked until execution settles. */
+  signal?: AbortSignal;
+  /**
+   * SELFHOST-008 P3: a transient system-role block for THIS turn's provider request only. Never
+   * written to the conversation store.
+   */
+  ephemeralSystemContext?: string;
+  /**
+   * PEER-007 (issue #1915): display attribution for the stored user message — who drove this turn.
+   * Never an authorization input (issue #1809).
+   */
+  driverId?: string;
+  /** Run-scoped model tool directive; 'none' remains in force for this turn only. */
+  toolChoice?: TToolChoice;
+  /**
+   * A message from another agent session started this turn. The reply to that session exists only
+   * here, and the provider's hosted tools are withheld because no permission step can decide them;
+   * every other call is decided by the session's ordinary permissions.
+   */
+  peerTurn?: boolean;
+  /** Host-owned trusted trace context for this turn's provider calls (agent-core `IRunOptions`). */
+  traceContext?: IRunTraceContext;
+}
+interface IProviderCallTraceObservation {
+  readonly callId?: string;
+  readonly round: number;
+  readonly startedAt: string;
+  readonly endedAt: string;
+  readonly outcome: 'success' | 'failure' | 'interrupted';
+  readonly disposition?: 'invoked' | 'cache-hit' | 'preflight-refused';
+  readonly providerId?: string;
+  readonly modelId?: string;
+  readonly usageProvenance?: 'complete' | 'partial' | 'absent';
+  readonly promptTokens?: number;
+  readonly completionTokens?: number;
+  readonly totalTokens?: number;
+  /** Present only for an invoked call whose adapter attested one; never fabricated. */
+  readonly providerRequestId?: string;
 }
 //#endregion
 //#region src/session.d.ts
 /** Wraps a Robota agent with project context, permission state, and optional persistence. */
 declare class Session extends SessionBase {
-  protected readonly robota: Robota;
+  protected readonly agent: Robota;
+  /**
+   * SELFHOST-004: session-owned observable event bus. Injected into the agent so tools (incl. the
+   * `FunctionTool` span-completion emit) publish here; the interactive turn subscribes to it to
+   * project per-operation spans onto session history. Exposed read-only via {@link getEventService}.
+   */
+  protected readonly eventService: IEventService;
   protected readonly permissionEnforcer: PermissionEnforcer;
   protected readonly contextTracker: ContextWindowTracker;
   protected permissionMode: TPermissionMode;
@@ -447,10 +905,8 @@ declare class Session extends SessionBase {
   protected model: string;
   protected systemMessage: string;
   protected messageCount: number;
-  protected abortController: AbortController | null;
   private readonly terminal;
   private readonly sessionStore?;
-  private readonly cwd;
   private readonly hooks?;
   private readonly hookTypeExecutors?;
   private readonly onTextDeltaCallback?;
@@ -461,13 +917,50 @@ declare class Session extends SessionBase {
   private readonly sessionLogger?;
   private readonly maxTurns?;
   private readonly compactionOrchestrator;
+  private readonly runtimeTools;
+  private readonly wrapAddedTools;
+  /** Tools added while a turn ran, applied when the next one starts. */
+  private readonly pendingTools;
+  /** The last tool change; the next one waits for it. */
+  private toolChange;
+  private shuttingDown;
   private shutdownPromise;
   /** Stdout collected from SessionStart hooks, injected on first run(). */
   private sessionStartStdout;
   /** Absolute path to the session transcript file, if file-backed storage is active. */
   private readonly transcriptPath;
   constructor(options: ISessionOptions);
-  run(message: string, rawInput?: string): Promise<string>;
+  /**
+   * @param options.ephemeralSystemContext SELFHOST-008 P3 — a transient system-role block included in this
+   *   turn's model call only, never persisted to history (thin pass-through to agent-core `IRunOptions`).
+   * REJECTS with `SessionBusyError` if a turn is in flight — RUNTIME-003; see `turn-claim.ts`.
+   */
+  run(message: string, rawInput?: string, options?: ISessionRunOptions): Promise<string>;
+  /**
+   * Make tools available from the next turn on — for a capability that became usable mid-session,
+   * such as an MCP server connected after its sign-in. Each goes through the same wrappers and
+   * permission gate as a tool present from the start. A tool whose name the session already has, or
+   * has queued, is left out rather than replacing the one the conversation has been using.
+   *
+   * The tool list is part of what a provider caches a prompt by, and a turn's rounds must all see
+   * the same list: while a turn runs, the tools wait and are applied when the next turn starts;
+   * otherwise they are applied now. Calls are serialized, so two concurrent ones both land.
+   * Resolves to the names that will be offered.
+   */
+  addTools(tools: readonly IToolWithEventService[]): Promise<readonly string[]>;
+  /** Runs `change` after every tool change before it, so each reads the list the last one wrote. */
+  private serializeToolChange;
+  /** Registers the queued tools with the agent. Only ever called inside `serializeToolChange`. */
+  private applyPendingTools;
+  listRuntimeTools(): Promise<IToolSchema[]>;
+  invokeRuntimeTool(name: string, parameters: TToolParameters, options?: {
+    signal?: AbortSignal;
+  }): Promise<IToolExecutionResult>;
+  /**
+   * SELFHOST-004: the session-owned observable event bus the agent's tools publish to. The interactive
+   * turn subscribes to it to collect span-completion events and project them onto session history.
+   */
+  getEventService(): IEventService;
   private log;
   private persistSessionInternal;
   /**
@@ -478,10 +971,16 @@ declare class Session extends SessionBase {
    */
   shutdown(options?: ISessionShutdownOptions): Promise<void>;
   swapProvider(newProvider: IAIProvider, model: string): void;
-  compact(instructions?: string, trigger?: TCompactTrigger): Promise<void>;
+  compact(instructions?: string, trigger?: TCompactTrigger, signal?: AbortSignal): Promise<void>;
+  /** `hookTraceEnv` reaches PreCompact only for a compaction inside a prompt (see `executeRun`). */
+  private compactWith;
   private buildRunContext;
 }
 //#endregion
+//#region src/consent-scope.d.ts
+/** The permission pattern a "don't ask again" answer for this invocation grants. */
+declare function consentScopeFor(toolName: string, toolArgs: TToolArgs): string;
+//#endregion
 //#region src/compaction-orchestrator.d.ts
 /**
  * Thrown when a compaction summary is invalid (non-string or empty provider content).
@@ -491,12 +990,25 @@ declare class Session extends SessionBase {
 declare class CompactionError extends Error {
   constructor(message: string);
 }
+/**
+ * Default base template for the compaction summarization prompt — the one model-facing
+ * prompt surface this package owns (declared in SPEC § Boundaries). Intentionally
+ * domain-neutral: it must not assume a software-development conversation. Replaceable
+ * wholesale via {@link ICompactionOptions.basePrompt}.
+ */
+declare const DEFAULT_COMPACTION_PROMPT: string;
 interface ICompactionOptions {
   sessionId: string;
   cwd: string;
   model: string;
   hooks?: Record<string, unknown>;
   compactInstructions?: string;
+  /**
+   * Replaces the entire base instruction template of the compaction prompt
+   * (default: {@link DEFAULT_COMPACTION_PROMPT}). Focus instructions and the
+   * formatted conversation are appended after it.
+   */
+  basePrompt?: string;
   /** Additional hook type executors (e.g. prompt, agent) beyond the core defaults. */
   hookTypeExecutors?: IHookTypeExecutor[];
 }
@@ -506,31 +1018,97 @@ declare class CompactionOrchestrator {
   private readonly model;
   private readonly hooks?;
   private readonly compactInstructions?;
+  private readonly basePrompt?;
   private readonly hookTypeExecutors?;
   constructor(options: ICompactionOptions);
   /**
    * Run compaction — summarize the conversation to free context space.
    * @param provider - The AI provider to use for summarization
-   * @param history - Current conversation history
+   * @param history - The messages to summarise. Must not be empty: whether there is anything worth
+   *   compacting is the caller's judgement, made before it commits to replacing the conversation
+   *   (CORE-031).
    * @param instructions - Optional focus instructions for the summary
+   * @param signal - The turn's cancellation signal (RUNTIME-004). Checked before the provider call
+   *   and again after it: an abort throws rather than returning, so the caller's existing
+   *   leave-history-untouched path covers a cancel as well as a failure.
+   * @param hookTraceEnv - The prompt's trace for PreCompact's command hooks, only inside a prompt
    * @returns The generated summary string (always a non-empty string)
-   * @throws {CompactionError} when the provider returns a non-string or empty summary —
-   *   callers must leave the conversation history untouched in that case
+   * @throws {CompactionError} when `history` is empty, or when the provider returns a non-string or
+   *   empty summary — callers must leave the conversation history untouched in every such case
    */
-  compact(provider: IAIProvider, history: TUniversalMessage[], instructions?: string): Promise<string>;
+  compact(provider: IAIProvider, history: TUniversalMessage[], instructions?: string, signal?: AbortSignal, trigger?: TCompactTrigger, hookTraceEnv?: ISubprocessTraceEnv): Promise<string>;
   /** Build the compaction prompt from conversation history */
   private buildCompactionPrompt;
 }
 //#endregion
+//#region src/conversation-transcript.d.ts
+/**
+ * Render each message as one entry, in order. An entry is one line, except an assistant message
+ * with several tool calls, which is one line per call. One entry per message so a caller that must
+ * drop the oldest part of a long conversation can drop whole messages.
+ */
+declare function formatConversationEntries(history: readonly TUniversalMessage[]): string[];
+//#endregion
+//#region src/session-artifact.d.ts
+/**
+ * TRANS-006: the envelope type and its version constant are the codec's (`session-record-codec/`).
+ * They used to be declared here as `ISessionArtifact` and a local constant, which was a second name
+ * and a second number for one shape — the envelope the codec decodes and the envelope this module
+ * writes were always the same `{ schemaVersion, record }`. Nothing on disk changed when they were
+ * unified, because there was nothing to change.
+ */
+interface ISerializeSessionArtifactOptions {
+  /**
+   * SHARE-PATH ONLY. An app-supplied, policy-free transform applied to the record before serialization — the app
+   * decides which trust-boundary fields to strip (composing the opt-in `scrubSensitiveKeys`). Omit for the
+   * full-fidelity local round-trip.
+   */
+  redact?: (record: IInteractiveSessionRecord$1) => IInteractiveSessionRecord$1;
+}
+/**
+ * Serialize a session record into a portable, versioned artifact. With no `redact`, this is the full-fidelity
+ * round-trip form; with `redact`, the caller's transform is applied first (the share path).
+ */
+declare function serializeSessionArtifact(record: IInteractiveSessionRecord$1, options?: ISerializeSessionArtifactOptions): string;
+/**
+ * Parse a session artifact back into an `IInteractiveSessionRecord`, rejecting an artifact whose schema version this build
+ * does not understand (so an incompatible artifact is never silently mis-imported).
+ */
+declare function deserializeSessionArtifact(bytes: string): IInteractiveSessionRecord$1;
+//#endregion
+//#region src/scrub-sensitive.d.ts
+/**
+ * SELFHOST-014 — the single source of the sensitive-key redaction (SSOT).
+ *
+ * The recursive secret-key scrub used to live privately in `session-logger.ts`, logging-coupled and not exported.
+ * It is extracted here so exactly ONE definition of "which keys are sensitive" exists, consumed by BOTH the file
+ * session logger (persistence-time redaction) and the SELFHOST-014 share-artifact `redact` transform (an opt-in
+ * the app composes). This utility is a pure, mechanism-level key scrub only: it carries NO field/trust-boundary
+ * policy (which of `cwd`/`sandboxSnapshotId`/… to strip is an app decision) and is NEVER forced into the
+ * full-fidelity local round-trip.
+ */
+/** Values a scrub can walk (mirrors the logger's log-value shape; avoids `any`/`unknown`). */
+type TScrubbableValue = string | number | boolean | object | null | undefined;
+/**
+ * Keys whose VALUE is a secret and must be redacted before persistence or sharing:
+ * `apiKey`/`authorization`/`accessToken`/`refreshToken`/`secret`/`password`/`xApiKey` (case/`-`/`_`-insensitive).
+ */
+declare const SENSITIVE_KEY_PATTERN: RegExp;
+/** True when a key's value should be redacted. The one predicate both the logger and the artifact scrub use. */
+declare function isSensitiveKey(key: string): boolean;
+/**
+ * Deep-copy `value`, replacing any value whose KEY is sensitive with `redactedValue` (default `[REDACTED]`).
+ * Pure — does not mutate the input. Returns the same shape (`T`).
+ */
+declare function scrubSensitiveKeys<T>(value: T, redactedValue?: string): T;
+//#endregion
 //#region src/session-log-events.d.ts
 /**
  * INFRA-017: typed contract for session-log event names + replay keys (SSOT).
  *
- * The `FileSessionLogger` writes JSONL lines `{ timestamp, sessionId, event, ...data }`. The event
- * names were previously implicit string literals scattered across the session/execution code. This
- * module names them once so the writer, the replay validator (`session-log-validation.ts`), and the
- * session-log replay provider (INFRA-017 / TEST-008) share one type-safe schema — without changing
- * what is written (it formalizes the existing format, it does not add a new one).
+ * `FileSessionLogger` owns the `{ schemaVersion, timestamp, sessionId, event }` JSONL envelope.
+ * This module owns its version and event vocabulary; `session-log-codec` validates each payload
+ * before replay or completeness checks.
  *
  * The **replay substrate** is the provider/tool execution layer, keyed deterministically:
  * a `provider_request` (executionId + round) is answered by its recorded
@@ -538,20 +1116,42 @@ declare class CompactionOrchestrator {
  * (executionId + toolCallId) by its `tool_execution_result`. `validateSessionReplayLogEntries`
  * proves a log carries all of these (i.e. is replay-complete).
  */
+/** Supported persisted session-log envelope version. */
+declare const SESSION_LOG_SCHEMA_VERSION = 1;
 /** Canonical session-log event names. */
 declare const SESSION_LOG_EVENT: {
   readonly sessionInit: "session_init";
   readonly sessionShutdown: "session_shutdown";
+  readonly sessionShutdownStepError: "session_shutdown_step_error";
   readonly context: "context";
   readonly contextCompact: "context_compact";
   readonly error: "error";
   readonly historyMutation: "history_mutation";
   readonly providerRequest: "provider_request";
   readonly providerNativeRawPayload: "provider_native_raw_payload";
+  readonly providerStreamRawDelta: "provider_stream_raw_delta";
   readonly providerResponseRaw: "provider_response_raw";
   readonly providerResponseNormalized: "provider_response_normalized";
+  /**
+   * CORE-043: which transport actually carried a structured-output schema on this request, and
+   * whether the schema had to be stated in the prompt instead. Diagnostic, not replay substrate — a
+   * replay answers a `provider_request` from its recorded response, and this line explains why that
+   * request looked the way it did.
+   */
+  readonly structuredOutputTransport: "structured_output_transport";
+  /**
+   * A request moved to another model because the one it was on failed. Diagnostic, not replay
+   * substrate: the `provider_request` announced for the new model is what a replay answers.
+   */
+  readonly providerFallback: "provider_fallback";
+  readonly assistantMessageCommitted: "assistant_message_committed";
   readonly toolExecutionRequest: "tool_execution_request";
   readonly toolExecutionResult: "tool_execution_result";
+  readonly toolBatchStarted: "tool_batch_started";
+  readonly toolMessageCommitted: "tool_message_committed";
+  readonly backgroundTaskEvent: "background_task_event";
+  readonly backgroundJobGroupEvent: "background_job_group_event";
+  readonly memoryEvent: "memory_event";
   readonly user: "user";
   readonly preRun: "pre_run";
   readonly textDelta: "text_delta";
@@ -585,9 +1185,174 @@ declare function isSessionLogEvent<TName extends TSessionLogEventName>(line: ISe
   event: TName;
 };
 //#endregion
+//#region src/session-log-entry-types.d.ts
+interface ISessionLogEntry extends Record<string, TUniversalValue> {
+  schemaVersion?: number;
+  timestamp: string;
+  sessionId: string;
+  event: string;
+}
+//#endregion
+//#region src/session-log-codec/index.d.ts
+type TSessionLogDecodeErrorCode = 'INVALID_JSON' | 'INVALID_EVENT' | 'UNSUPPORTED_VERSION';
+type TDecodedEvent<TName extends TSessionLogEventName> = ISessionLogEntry & {
+  event: TName;
+};
+type TDecodedSessionLogEntry = (TDecodedEvent<'provider_response_normalized'> & {
+  response: TUniversalMessage;
+}) | (TDecodedEvent<'history_mutation'> & {
+  mutation: 'append_message';
+  message: TUniversalMessage;
+}) | (TDecodedEvent<'assistant_message_committed'> & {
+  message: TUniversalMessage | string;
+}) | (TDecodedEvent<'tool_message_committed'> & {
+  message: TUniversalMessage;
+}) | (TDecodedEvent<'background_task_event'> & {
+  backgroundEvent?: object;
+  data?: object;
+}) | (TDecodedEvent<'background_job_group_event'> & {
+  backgroundJobGroupEvent?: object;
+  data?: object;
+}) | (TDecodedEvent<'memory_event'> & {
+  memoryEvent?: object;
+  data?: object;
+}) | TDecodedEvent<Exclude<TSessionLogEventName, 'provider_response_normalized' | 'history_mutation' | 'assistant_message_committed' | 'tool_message_committed' | 'background_task_event' | 'background_job_group_event' | 'memory_event'>>;
+declare class SessionLogDecodeError extends Error {
+  readonly code: TSessionLogDecodeErrorCode;
+  readonly issues: readonly ISessionRecordDecodeIssue[];
+  readonly schemaVersion?: number;
+  constructor(code: TSessionLogDecodeErrorCode, issues: readonly ISessionRecordDecodeIssue[], options?: {
+    schemaVersion?: number;
+    cause?: unknown;
+  });
+}
+/** Validate the full input before returning any entry to replay consumers. */
+declare function decodeSessionLogEntries(entries: unknown, options?: {
+  lineNumbers?: readonly number[];
+}): TDecodedSessionLogEntry[];
+//#endregion
+//#region src/external-payload-source-types.d.ts
+/**
+ * Leaf type module for {@link IExternalPayloadSource} and {@link ISessionLogSource}.
+ *
+ * Split out of `session-log-sources.ts` so `external-payload-resolution-contracts.ts` can depend
+ * on {@link IExternalPayloadSource} without importing back from `session-log-sources.ts`, which
+ * previously created an import cycle between the two.
+ */
+/** Workspace-neutral byte source for relative external-payload references. */
+interface IExternalPayloadSource {
+  readBytes(relativePath: string, maxBytes: number): Uint8Array | undefined;
+}
+/** Workspace-neutral source for one session-log document and its optional payload source. */
+interface ISessionLogSource {
+  readText(): string | undefined;
+  readonly externalPayloadSource?: IExternalPayloadSource;
+}
+//#endregion
+//#region src/session-log-sources.d.ts
+/** Explicit host-filesystem adapter. A file path is never accepted by the neutral parser itself. */
+declare class NodeExternalPayloadSource implements IExternalPayloadSource {
+  private readonly baseDirectory;
+  constructor(baseDirectory: string);
+  readBytes(relativePath: string, maxBytes: number): Uint8Array | undefined;
+}
+/** Explicit host-filesystem adapter for a JSONL session log. */
+declare class NodeSessionLogSource implements ISessionLogSource {
+  private readonly logFile;
+  readonly externalPayloadSource: IExternalPayloadSource;
+  constructor(logFile: string);
+  readText(): string | undefined;
+}
+//#endregion
+//#region src/tool-result-spill-store.d.ts
+type TToolResultSpillErrorCode = 'invalid-options' | 'unsafe-root' | 'write-failed' | 'missing' | 'expired' | 'invalid-reference' | 'read-failed' | 'cleanup-failed' | 'closed';
+declare class ToolResultSpillError extends Error {
+  readonly code: TToolResultSpillErrorCode;
+  constructor(code: TToolResultSpillErrorCode);
+}
+interface INodeToolResultSpillStoreOptions {
+  /** Host-owned parent; defaults to the operating-system temporary directory. */
+  readonly parentDirectory?: string;
+  readonly retentionMs?: number;
+  readonly now?: () => number;
+  /** Receives a fixed, payload-free reason if an idle expiry timer cannot delete a file. */
+  readonly onCleanupFailure?: (reason: 'cleanup-failed') => void;
+}
+/** Node host implementation of core's opaque, session-lifetime spill port. */
+declare class NodeToolResultSpillStore implements IToolResultSpillStore {
+  private readonly directory;
+  private readonly retentionMs;
+  private readonly now;
+  private readonly onCleanupFailure?;
+  private readonly entries;
+  private expiryTimer?;
+  private closed;
+  constructor(options?: INodeToolResultSpillStoreOptions);
+  private assertRoot;
+  private scheduleExpiry;
+  write(content: string): Promise<{
+    readonly reference: string;
+  }>;
+  read(reference: string): Promise<string>;
+  private removeEntry;
+  cleanupExpired(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/prompt-history-file.d.ts
+/** 64 KiB: a few hundred prompts per block — enough for the first frame, small enough to yield often. */
+declare const DEFAULT_PROMPT_HISTORY_BLOCK_BYTES: number;
+interface INodePromptHistoryFileOptions {
+  /** An ancestor of the file the host also owns, tightened along with the directory (SEC-020). */
+  readonly ownedRoot?: string;
+  /** Test seam: the read block size in bytes. */
+  readonly blockBytes?: number;
+}
+/** One line → an entry, or `undefined` when the line is not a well-formed entry. */
+declare function parsePromptHistoryLine(line: string): IPromptHistoryEntry | undefined;
+declare class NodePromptHistoryFile implements IPromptHistoryWriter, IPromptHistorySource {
+  private readonly path;
+  private readonly blockBytes;
+  private readonly ownedRoot;
+  constructor(path: string, options?: INodePromptHistoryFileOptions);
+  append(entry: IPromptHistoryEntry): void;
+  /**
+   * Newest-first blocks. Only a missing file is the empty state (a fresh install, or history off);
+   * any other open or read failure is thrown so the surface renders it instead of an empty list.
+   */
+  read(options: IPromptHistoryReadOptions): AsyncIterable<IPromptHistoryBlock>;
+}
+//#endregion
+//#region src/external-payload-resolution-contracts.d.ts
+type TSessionLogPayloadResolutionErrorCode = 'INVALID_LIMIT' | 'INVALID_REFERENCE' | 'UNRESOLVED_REFERENCE' | 'OUTSIDE_ROOT' | 'PAYLOAD_NOT_FOUND' | 'STABLE_PAYLOAD_READ_UNAVAILABLE' | 'PAYLOAD_UNREADABLE' | 'BYTE_LENGTH_MISMATCH' | 'SHA256_MISMATCH' | 'INVALID_JSON' | 'MAX_DEPTH_EXCEEDED' | 'MAX_TOTAL_BYTES_EXCEEDED' | 'CIRCULAR_REFERENCE';
+interface ISessionLogPayloadResolutionOptions {
+  readonly source?: IExternalPayloadSource;
+  readonly maxDepth?: number;
+  readonly maxTotalBytes?: number;
+}
+interface ISessionLogPayloadResolutionErrorMetadata {
+  readonly relativePath?: string;
+  readonly resolvedPath?: string;
+  readonly depth?: number;
+  readonly expected?: string | number;
+  readonly actual?: string | number;
+}
+declare class SessionLogPayloadResolutionError extends Error {
+  readonly code: TSessionLogPayloadResolutionErrorCode;
+  readonly metadata: Readonly<ISessionLogPayloadResolutionErrorMetadata>;
+  constructor(code: TSessionLogPayloadResolutionErrorCode, message: string, metadata?: ISessionLogPayloadResolutionErrorMetadata, cause?: unknown);
+}
+//#endregion
+//#region src/external-payload-resolver.d.ts
+/**
+ * Hydrate every external JSON payload reference in one value using one aggregate budget.
+ * The input is treated as untrusted and the returned graph contains only JSON-compatible values.
+ */
+declare function resolveSessionLogExternalPayloads(value: unknown, options: ISessionLogPayloadResolutionOptions): unknown;
+//#endregion
 //#region src/session-log-validation.d.ts
 interface ISessionReplayValidationIssue {
-  code: 'PROVIDER_RESPONSE_RAW_MISSING' | 'PROVIDER_NATIVE_RAW_PAYLOAD_MISSING' | 'PROVIDER_RESPONSE_NORMALIZED_MISSING' | 'TOOL_RESULT_MISSING' | 'PAYLOAD_REFERENCE_INVALID';
+  code: 'PROVIDER_RESPONSE_RAW_MISSING' | 'PROVIDER_NATIVE_RAW_PAYLOAD_MISSING' | 'PROVIDER_RESPONSE_NORMALIZED_MISSING' | 'TOOL_RESULT_MISSING' | 'PAYLOAD_REFERENCE_INVALID' | 'UNRESOLVED_REPLAY_PAYLOAD';
   message: string;
   eventIndex?: number;
   executionId?: string;
@@ -601,11 +1366,6 @@ interface ISessionReplayValidationResult {
 declare function validateSessionReplayLogEntries(entries: readonly ISessionLogEntry[]): ISessionReplayValidationResult;
 //#endregion
 //#region src/session-log-replay.d.ts
-interface ISessionLogEntry extends Record<string, TUniversalValue> {
-  timestamp: string;
-  sessionId: string;
-  event: string;
-}
 interface ISessionReplayRecord {
   sessionId: string | undefined;
   cwd: string | undefined;
@@ -617,8 +1377,244 @@ interface ISessionReplayRecord {
   backgroundJobGroupEvents: object[];
   memoryEvents: object[];
 }
-declare function loadSessionLogEntries(logFile: string): ISessionLogEntry[];
+type ISessionLogLoadOptions = Omit<ISessionLogPayloadResolutionOptions, 'source'> & {
+  readonly externalPayloadSource?: IExternalPayloadSource;
+};
+declare function loadSessionLogEntries(source: ISessionLogSource, options?: ISessionLogLoadOptions): ISessionLogEntry[];
 declare function replaySessionLogEntries(entries: readonly ISessionLogEntry[]): ISessionReplayRecord;
 //#endregion
-export { AUTO_COMPACT_THRESHOLD, CompactionError, CompactionOrchestrator, ContextWindowTracker, FileSessionLogger, type IExternalPayloadReference, type IFileSessionLoggerOptions, type IProviderEventKey, type ISessionLogEntry, type ISessionLogLine, type ISessionLogger, type ISessionOptions, type ISessionRecord, type ISessionReplayRecord, type ISessionReplayValidationIssue, type ISessionReplayValidationResult, type ISessionShutdownOptions, type ISessionStore, type ISpinner, type ITerminalOutput, type IToolEventKey, PermissionEnforcer, SESSION_LOG_EVENT, Session, SessionStore, SilentSessionLogger, type TAutoCompactThreshold, type TPermissionHandler, type TPermissionResult, type TSessionLogData, type TSessionLogEventName, type TSessionLogValue, isSessionLogEvent, loadSessionLogEntries, replaySessionLogEntries, validateSessionReplayLogEntries };
+//#region src/session-id.d.ts
+/**
+ * Whether `id` is safe to interpolate into a filesystem path as a single component.
+ *
+ * The pattern admits no `/`, no `\` and no `:`, so the value cannot introduce a path separator or a
+ * Windows drive qualifier; and because it must start with an alphanumeric, it can be neither `.` nor
+ * `..`. With no separator available, an embedded `..` cannot form a traversal component.
+ */
+declare function isSafeSessionId(id: string): boolean;
+/** Throw unless `id` is safe to use as a path component. */
+declare function assertSafeSessionId(id: string): void;
+//#endregion
+//#region src/session-store.d.ts
+/**
+ * Persistent session store backed by individual JSON files.
+ *
+ * Construct with a host-owned `baseDir`; framework project composition uses a separate
+ * authority-backed adapter over the same neutral port.
+ */
+declare class NodeSessionStore implements IInteractiveSessionStore$1 {
+  private readonly baseDir;
+  private readonly ownedRoot;
+  /**
+   * @param baseDir the directory holding the records.
+   * @param ownedRoot an ancestor of `baseDir` the HOST also owns, tightened along with it (SEC-020).
+   *   Optional because this adapter does not interpret its base directory as a trusted root and must
+   *   not guess that a parent belongs to the product — which of them do is composition's knowledge.
+   *   Omitting it leaves a store root an older version created at whatever mode it was given, which
+   *   is what review of PR #2224 found: the leaf was 0700 and the directory above it was not.
+   */
+  constructor(baseDir: string, ownedRoot?: string);
+  /**
+   * Ensure the storage directory exists AND that only its owner can enter it (SEC-020).
+   *
+   * The `existsSync` guard this replaces is the whole defect. It skipped the case that matters: a
+   * directory some earlier version, a shared CI checkout, or another local user left at a wider
+   * mode was adopted as ours with no signal. Measured under umask 022 before this change, a fresh
+   * sessions directory came out 0755 and its records 0644 — and a directory pre-created at 0777
+   * stayed 0777.
+   */
+  private ensureDir;
+  /**
+   * Absolute path to a session's JSON file.
+   *
+   * SEC-006: every public method routes through here, so validating the id at this one point covers
+   * `save` (write), `load` (read), and `delete` (unlink) at once.
+   *
+   * Issue #2240: `assertSafeSessionId` is the guard, and it is sound — no separator, no `.`/`..`
+   * can pass it. But it is a regex reject behind a helper, which static analysis does not model as
+   * a path sanitizer, so `js/path-injection` re-opened on `load` every time this function changed
+   * length. The containment check below is the shape such tools DO recognise: the resolved path
+   * must stay inside the resolved base directory. It is unreachable after the assertion and costs
+   * one `resolve`; it exists so the guard is visible where the sink is, not to replace the guard.
+   */
+  private filePath;
+  /**
+   * Persist a session record to disk atomically (CORE-019).
+   * Creates the storage directory if needed.
+   *
+   * Bytes go to a same-directory temp file first, then move into place with rename —
+   * a crash mid-write can therefore never leave a truncated JSON where the previous
+   * record used to be. Same-directory is load-bearing: cross-device rename is a copy.
+   *
+   * SEC-020: the atomic write now comes from `writeOwnerOnlyFile`, which carries the mode from the
+   * moment the temp file is created. The hand-rolled version here wrote it at the umask's default
+   * and let `rename` carry that mode to the final path, so every record was 0644 — and even setting
+   * the mode after the write would leave a window in which the full transcript was world-readable
+   * on disk.
+   */
+  save(session: IInteractiveSessionRecord$1): void;
+  /**
+   * Load a session by its ID, saying WHICH of the four things happened.
+   *
+   * `undefined` used to answer all four — never saved, damaged, written by a build this one cannot
+   * read, and the read failed — and a caller that meant to preserve fields it does not own then
+   * treated "damaged" as "no prior record" and overwrote the file. The outcome type is what removes
+   * that, by making the caller answer the question it was not asking.
+   */
+  load(id: string): TSessionLoadOutcome;
+  /**
+   * Every session this directory holds, each with what the store concluded about it.
+   *
+   * Unreadable entries are REPORTED rather than skipped. A store that distinguishes four outcomes on
+   * `load` and then hides two of them from the surface a person browses has moved the defect rather
+   * than removed it: the difference a user experiences is between "my session vanished" and "my
+   * session needs a different build".
+   */
+  list(): readonly ISessionListEntry[];
+  /**
+   * The outcome for one directory entry, without letting a bad NAME throw out of `list`.
+   *
+   * `load` validates the id, because an id reaching it is a caller's value and a malformed one is a
+   * bug or an attack (SEC-006). A name read out of the directory is neither: the store did not
+   * choose it, and one file it cannot use as an id must not take the whole listing down with it.
+   * Routing `list` through `load` made exactly that happen — a single `my session.json` in the
+   * sessions directory threw, and the resume picker went with it.
+   *
+   * Reporting it is the same answer `list` gives for every other file it cannot read, which is the
+   * property this work exists to establish.
+   */
+  private outcomeForListedId;
+  /**
+   * Delete a session by its ID.
+   * No-ops silently if the session does not exist.
+   */
+  delete(id: string): void;
+}
+//#endregion
+//#region src/checkpoint-tree.d.ts
+/**
+ * SELFHOST-007 — neutral checkpoint tree (branching time-travel).
+ *
+ * A pure, I/O-free branch-tree over opaque checkpoint-node ids — git-for-a-session with no file I/O,
+ * no persistence, and no retention/prune policy. It lives beside the storage-neutral persistence
+ * primitive (`SessionStore`/`IInteractiveSessionRecord`): same neutral-mechanism class (opaque payloads, no
+ * product policy). The agent-framework checkpoint store consumes it over the existing one-way
+ * `agent-framework → agent-session` edge; the reverse edge would be a cycle and is forbidden.
+ *
+ * Model: each node is `{ id, parentId }` (root has no `parentId`). Adding a checkpoint appends a child
+ * of the active head. Forking moves the active head to a PAST node so the next append DIVERGES — the
+ * original descendants stay reachable (a sibling branch). A "branch" is a leaf (a node with no
+ * children); `switch` moves the active head to any existing node.
+ */
+interface ICheckpointNode {
+  id: string;
+  /** Parent checkpoint id; absent for the root. */
+  parentId?: string;
+}
+declare class CheckpointTree {
+  private readonly nodes;
+  /** Child adjacency (parentId → child ids in insertion order) for O(1) leaf/branch queries. */
+  private readonly children;
+  private activeId;
+  /**
+   * Build a tree from explicit `{ id, parentId }` edges (e.g. reconstructed from persisted checkpoint
+   * manifests). Nodes may arrive in any order — parents are linked by id. The active head is left at
+   * the given `activeId` (or undefined). This is the delegation entry point a consumer store uses to
+   * answer navigation queries (`listBranches`/`ancestors`) without the tree owning any persistence.
+   */
+  static fromNodes(nodes: ICheckpointNode[], activeId?: string): CheckpointTree;
+  /**
+   * Append a checkpoint as a child of the current active head and make it the new active head.
+   * The first append (no active head) becomes the root. Ids must be unique.
+   */
+  addCheckpoint(id: string): void;
+  /**
+   * Fork from a PAST checkpoint: move the active head to `fromId` so the next `addCheckpoint` diverges
+   * into a sibling branch, leaving `fromId`'s original descendants reachable. Returns `fromId`.
+   */
+  fork(fromId: string): string;
+  /** Move the active head to an existing node (typically a branch leaf). */
+  switch(nodeId: string): void;
+  /** The current active head id (undefined for an empty tree). */
+  activeLeaf(): string | undefined;
+  /** All branch tips (leaf nodes with no children), in insertion order. */
+  listBranches(): string[];
+  /**
+   * The chain from `id` up to (and including) the root — nearest first. Empty if `id` is unknown. Only
+   * REGISTERED nodes are included: a dangling `parentId` (edge to a node not in the tree — possible on
+   * manifest drift/corruption) terminates the walk rather than emitting a phantom id.
+   */
+  ancestors(id: string): string[];
+  /** Whether a checkpoint id exists in the tree. */
+  has(id: string): boolean;
+  /** The number of checkpoints in the tree. */
+  get size(): number;
+}
+//#endregion
+//#region src/session-record-codec/decode-outcome.d.ts
+/** What a decode of a persisted session record can conclude. */
+type TSessionRecordDecodeOutcome = {
+  readonly status: 'valid';
+  readonly record: IInteractiveSessionRecord$1;
+} | {
+  readonly status: 'corrupt';
+  readonly issues: readonly ISessionRecordDecodeIssue[];
+} | {
+  readonly status: 'unsupported';
+  readonly schemaVersion: number | undefined;
+};
+//#endregion
+//#region src/session-record-codec/record-decoder.d.ts
+/**
+ * The version of the persisted record envelope this build reads and writes.
+ *
+ * Bump it when the shape changes in a way an older reader would decode WRONGLY rather than not at
+ * all. A reader that meets a version it does not implement reports `unsupported` and stops — it does
+ * not decode the members it recognises, because a partially decoded session is the silent
+ * field-loss this codec replaces.
+ *
+ * ONE concept, not two (issue #2185): the envelope `{ schemaVersion, record }` and the record it
+ * wraps version together — a change to either shape bumps this number, and every consumer of the
+ * envelope reads it: the portable session artifact (`serializeSessionArtifact`) and the session
+ * store (`NodeSessionStore.save`, `WorkspaceSessionStore`). Two constants would let an envelope-only
+ * change reject records that are fine, and the two shapes have never moved apart. The constant is
+ * therefore named for the pair it versions, not for its first consumer: TRANS-006 kept the
+ * incumbent `SESSION_ARTIFACT_SCHEMA_VERSION` (published, written by the producing path) over the
+ * duplicate TRANS-005 introduced, and #2185 renamed it here — prerelease, so no alias.
+ *
+ * Its DECLARATION lives here rather than beside the artifact functions because `session-artifact.ts`
+ * imports this module; declaring it there and importing it back would be a module cycle. The export
+ * from the package barrel is unchanged.
+ */
+declare const SESSION_RECORD_ENVELOPE_VERSION = 1;
+/** A persisted record with the version of the shape it was written in. */
+interface IVersionedInteractiveSessionRecord {
+  schemaVersion: number;
+  record: IInteractiveSessionRecord$1;
+}
+/**
+ * Every key the record contract declares.
+ *
+ * Exported so a test can compare it against `keyof IInteractiveSessionRecord`: a member added to the
+ * contract without a branch below then fails that comparison rather than being silently dropped by
+ * a decoder that never heard of it.
+ */
+declare const INTERACTIVE_SESSION_RECORD_KEYS: readonly string[];
+/**
+ * Decode a bare persisted record.
+ *
+ * The value is decoded, never cast: what comes back is either a record every member of which was
+ * checked, or the list of every place it failed — not the first place.
+ */
+declare function decodeInteractiveSessionRecord(value: unknown): TSessionRecordDecodeOutcome;
+/**
+ * Decode a versioned envelope.
+ *
+ * The version is read BEFORE the record, and a version this build does not implement returns
+ * `unsupported` WITHOUT nested issues: reporting field defects against a shape from another version
+ * describes the reader's expectations, not the data's condition, and a caller cannot act on it.
+ */
+declare function decodeVersionedInteractiveSessionRecord(value: unknown): TSessionRecordDecodeOutcome;
+//#endregion
+export { AUTO_COMPACT_THRESHOLD, AutoModeGate, CONSECUTIVE_BLOCK_LIMIT, CheckpointTree, CompactionError, CompactionOrchestrator, ContextWindowTracker, DEFAULT_COMPACTION_PROMPT, DEFAULT_PROMPT_HISTORY_BLOCK_BYTES, FileSessionLogger, type ICheckpointNode, type IClassifiedCall, type IClassifierVerdict, type ICommandSandboxApproval, type IExternalPayloadReference, type IExternalPayloadSink, type IExternalPayloadSource, type IFileSessionLoggerOptions, type IInteractiveSessionRecord, type IInteractiveSessionStore, INTERACTIVE_SESSION_RECORD_KEYS, type INodePromptHistoryFileOptions, type INodeToolResultSpillStoreOptions, type IPermissionClassifier, type IPermissionDenial, type IProviderCallTraceObservation, type IProviderEventKey, type ISerializeSessionArtifactOptions, type ISessionLogEntry, type ISessionLogLine, type ISessionLogLoadOptions, type ISessionLogPayloadResolutionErrorMetadata, type ISessionLogPayloadResolutionOptions, type ISessionLogSink, type ISessionLogSource, type ISessionLogger, type ISessionOptions, type ISessionRecord, type ISessionReplayRecord, type ISessionReplayValidationIssue, type ISessionReplayValidationResult, type ISessionRunOptions, type ISessionShutdownOptions, type ISessionStore, type ISpinner, type ITerminalOutput, type IToolEventKey, type IVersionedInteractiveSessionRecord, NodeExternalPayloadSource, NodePromptHistoryFile, NodeSessionLogSink, NodeSessionLogSource, NodeSessionStore, NodeToolResultSpillStore, PermissionEnforcer, SENSITIVE_KEY_PATTERN, SESSION_LOG_EVENT, SESSION_LOG_SCHEMA_VERSION, SESSION_RECORD_ENVELOPE_VERSION, Session, SessionBusyError, SessionLogDecodeError, SessionLogPayloadResolutionError, SilentSessionLogger, type TAutoCompactThreshold, type TAutoModeJudgement, type TDecodedSessionLogEntry, TOTAL_BLOCK_LIMIT, type TPermissionDenialReason, type TPermissionHandler, type TPermissionResult, type TScrubbableValue, type TSessionLogData, type TSessionLogDecodeErrorCode, type TSessionLogEventName, type TSessionLogPayloadResolutionErrorCode, type TSessionLogValue, type TSessionRecordDecodeOutcome, type TToolResultSpillErrorCode, ToolResultSpillError, TurnClaim, assertSafeSessionId, consentScopeFor, createSessionLogExternalPayloadReference, decodeInteractiveSessionRecord, decodeSessionLogEntries, decodeVersionedInteractiveSessionRecord, deserializeSessionArtifact, formatConversationEntries, isSafeSessionId, isSensitiveKey, isSessionLogEvent, loadSessionLogEntries, parsePromptHistoryLine, replaySessionLogEntries, resolveSessionLogExternalPayloads, scrubSensitiveKeys, serializeSessionArtifact, validateSessionReplayLogEntries };
 //# sourceMappingURL=index.d.ts.map