@visual-z/xeno 0.2.1 → 0.4.0

package/src/runtime/loop.ts

@@ -18,53 +18,78 @@
  * request.
  */
 
-import type { LogEvent, AssistantBlock, NodeRef, CutReason } from "../core/events.ts";
+import type { LogEvent, AssistantBlock, NodeRef, CutReason, ToolInvocationEvent } from "../core/events.ts";
 import { userInputData, submissionImages, type UserInput, type ImageRef } from "../core/images.ts";
 import { hydrateImages } from "./images.ts";
 import type { Handoff } from "../core/handoff.ts";
 import { boundHandoff, DEFAULT_HANDOFF_TOKENS } from "../core/history.ts";
 import { boundaryPreparation, continuationGuidance } from "../core/continuation.ts";
-import type { FrozenPrefix, Message } from "../core/project.ts";
-import { projectContext } from "../core/project.ts";
+import type { FrozenPrefix, Message, ProjectInput } from "../core/project.ts";
+import { projectContext, PROJECTION_VERSION, toolCallIdentityViolations } from "../core/project.ts";
 import { deriveHandoff, carryForward } from "../core/derive.ts";
-import { DEFAULT_BOUNDARY, shouldStopAndAsk, type BoundaryConfig } from "../core/boundary.ts";
-import { decideContext, DEFAULT_CONTEXT_POLICY, estimateBoundaryCost, isContextPolicy, type ContextPolicy } from "../core/context-policy.ts";
-import { retainedContext, selectRecentContext, windowBudget } from "../core/context-window.ts";
+import { latestObservedFileVersion } from "../core/file-precondition.ts";
+import { latestProcessReceipt } from "../core/process-receipt.ts";
+import { advanceRecovery, emptyRecoveryState, recoveryReview, type RecoveryState } from "../core/failure-recovery.ts";
+import { shouldStopAndAsk, type BoundaryConfig } from "../core/boundary.ts";
+import {
+  contextLimits, decideContext, DEFAULT_CONTEXT_POLICY, estimateBoundaryCost, isContextPolicy,
+  type ContextLimits, type ContextPolicy,
+} from "../core/context-policy.ts";
+import { retainedContext, selectRecentContext } from "../core/context-window.ts";
 import { advanceStall, emptyStallState, stallDecision, DEFAULT_STALL_LIMIT, type StallState } from "../core/stall.ts";
 import { DEFAULT_OUTPUT_RECOVERY_LIMIT, isCompleteResponse, incompleteToolText, knownUnexecutedTool, outputRecoveryNotice, validateOutputRecoveryLimit } from "../core/response-recovery.ts";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { pendingToolCalls } from "../core/execution.ts";
+import { declaredToolNames, recordedDeclarations } from "../core/tool-discovery.ts";
+import { DISCOVERY_TOOL, DISCOVERY_TOOL_NAME, currentDeferredTools, discoveryFingerprint, discoveryPermitted, searchDeferredTools } from "./tool-discovery.ts";
 import { executionOutcome, modelOutcome, type ExecutionOutcome } from "../core/outcome.ts";
+import { commandCompletion } from "../core/command-contract.ts";
 import { ExecutionControl } from "./execution-control.ts";
+import { BranchJobs } from "./branch-jobs.ts";
+import { HistoryCache } from "./history-cache.ts";
+import { RuntimeTargets } from "./runtime-target.ts";
+import { ToolBroker, MAX_NESTED_ARGUMENT_BYTES, MAX_INLINE_RESULT_DATA_BYTES, type BrokerReceipt, type BrokerExecution } from "./tool-broker.ts";
+import { ToolQueue } from "./tool-queue.ts";
+import { NATIVE_COMMAND_NAME, nativeCommandContext, nativeCommandResult, type NativeCommandInput, type NativeCommandResult } from "./tools.ts";
+import { isJsonValue, type JsonValue } from "../core/tool-contract.ts";
+import { archiveObservation } from "../store/observations.ts";
+import { disposeExecSessions, runningSessions } from "./exec-sessions.ts";
+import { branchStatus, processStatus, deriveProcesses, type ProcessObservation } from "../core/process-state.ts";
 import { schedulingWindow } from "../core/scheduling.ts";
 import { estimateTokens, anchoredCount, scaledCounter, type TokenCounter, type Anchor } from "../core/tokens.ts";
 import { isContextOverflow } from "../core/overflow.ts";
-import { completionReview } from "../core/completion-review.ts";
+import { requestCompletion } from "../core/completion-review.ts";
+import { deriveRequestState, type RequestState } from "../core/request-state.ts";
 import { churnReview } from "../core/churn.ts";
+import { deriveBranchReceipt } from "../core/branch-receipt.ts";
+import { skillTools, type Skill } from "../core/skills.ts";
+import type { WorkItem } from "../core/work-state.ts";
+import { parseAcceptanceContract, type AcceptanceContract, type AcceptanceState } from "../core/acceptance.ts";
 import { deadlineNotice } from "../core/deadline.ts";
 import { statusOf } from "./retry.ts";
 import { assertNever } from "../core/exhaustive.ts";
 import { isLogEvent } from "../core/event-validation.ts";
 import {
   initNode, appendEvent, readNode, closeNode, digestNode, handoffPath, nodePath, manifestPath,
-  listNodes, readCursor, readCursorAt, writeCursor,
+  listNodes, readManifest, readCursor, readCursorAt, writeCursor,
 } from "../store/log.ts";
-import { replayContext } from "../store/replay.ts";
+import { replayContext, carriedHandoff } from "../store/replay.ts";
 import { recoverCut } from "../store/recovery.ts";
 import { runHistoryTool } from "./history-tools.ts";
 import { prepareWorkingNote } from "./working-notes.ts";
 import { copyAncestryTo } from "../store/sessions.ts";
-import type { Provider, Turn, StreamDelta } from "./provider.ts";
+import { FailedResponseError, type Provider, type Turn, type StreamDelta } from "./provider.ts";
 import {
   scanWorkspace, diffScans, reconcile, DEFAULT_IGNORE, workspaceVersion,
   type FileSet, type RestoreResult,
 } from "../store/workspace.ts";
 import { putBlob, getBlob, putFileBlob } from "../store/blobs.ts";
+import { hydrateProcessReceipts } from "../store/process-receipts.ts";
 import { readNodeHistory, planRestoreToNode, applyRestorePlan } from "../store/restore.ts";
 import { createWorktree, removeWorktree } from "../store/worktree.ts";
 import {
-  runTool, parseNote, matchGate, branchTools, gateTool, finishToolResult, prepareTool, toolDefinition,
+  parseNote, matchGate, branchTools, finishToolResult, prepareNormalizedTool, presentObservation, toolDefinition, modelToolSchema, adviceTools,
   BRANCH_TOOL_NAMES, WRITING_BRANCH_TOOL_NAMES,
   type ToolContext, type Annotation, type ToolResult,
 } from "./tools.ts";
@@ -79,6 +104,10 @@ import { resolveHistoryPosition } from "../store/session-position.ts";
 import { observeCommand } from "../store/command.ts";
 import { headTailView } from "../core/observation-view.ts";
 import { withProgress } from "./progress.ts";
+import { WorkspaceLifecycle } from "./workspace-lifecycle.ts";
+import { changedPaths, sameVersion, type CheckpointEvent, type FileChanges } from "../core/checkpoints.ts";
+import { readEditableFile, preflightChanges, applyFileChanges } from "../store/file-checkpoints.ts";
+import { planCheckpointRestore } from "../store/checkpoint-history.ts";
 
 /** Ids and timestamps come from here so the loop stays the only impure part. */
 export interface Clock {
@@ -122,6 +151,8 @@ export interface LoopEvent {
   /** branch_start: wall-clock milliseconds, for asserting the stagger. */
   at?: number;
   outcome?: ExecutionOutcome;
+  /** Q23: task evidence is separate from the execution outcome; rebuilt from original receipts. */
+  request?: RequestState;
   progress?: Extract<StreamDelta, { kind: "tool" | "retry" }> | { kind: "output"; text: string; name: string };
 }
 
@@ -156,6 +187,18 @@ export const DEFAULT_BRANCH_LIMITS: BranchLimits = {
 };
 
 export interface SessionConfig {
+  /** P.3: legacy full snapshots are an explicit compatibility mode, never the CLI default. */
+  workspaceTracking?: "journal" | "legacy";
+  shellCheckpoints?: boolean;
+  skills?: readonly Skill[];
+  acceptanceContract?: AcceptanceContract | null;
+  strictVerification?: boolean;
+  /** O.10: opt-in carried view; legacy sessions and evaluations retain D20. */
+  workingSet?: boolean;
+  /** R9: CLI opts into source-priority views; absent preserves v1 experiment/old-session behavior. */
+  workingSetVersion?: 1 | 2;
+  /** R10: new CLI guidance; absence retains old carried/prefix wording on resume. */
+  guidanceVersion?: 1;
   logDir: string;
   frozen: FrozenPrefix;
   tools: ToolContext;
@@ -287,14 +330,30 @@ export type RewindResult =
   | { ok: false; error: string };
 
 /** O.5: child execution returns facts; only the parent coordinator accepts them. */
-type DeferredToolResult = ToolResult & { accept?: () => Promise<LoopEvent[]> };
+type DeferredToolResult = ToolResult & { accept?: () => Promise<LoopEvent[]>; annotation?: LogEvent };
 type ToolCall = Extract<AssistantBlock, { type: "tool_use" }>;
+type SessionBrokerReceipt = BrokerReceipt<DeferredToolResult> & { events: LoopEvent[] };
+type PreparedBrokerCall = { run(emit?: (event: LoopEvent) => void): Promise<SessionBrokerReceipt> };
+export type CommittedItem = { node: number; id: string; type: LogEvent["t"] };
 
 export class Session {
+  private readonly execOwner = randomUUID();
+  private readonly jobs = new BranchJobs<DeferredToolResult>();
+  private readonly children = new Map<number, Session>();
+  private cleanup: Promise<void> | null = null;
+  private closing: Promise<void> | null = null;
+  private turnTools: ToolContext | null = null;
   private readonly execution = new ExecutionControl();
+  private readonly runtimeTargets = new RuntimeTargets();
+  private rootTools: ToolQueue | undefined;
+  private hostOwner: ReturnType<ExecutionControl["begin"]> | undefined;
+  private readonly hostPending = new Set<Promise<NativeCommandResult>>();
   private stall: StallState | null = null;
+  private recovery: RecoveryState | null = null;
   private pendingAdoption: number | null = null;
   private readonly allocatedEventIds = new Set<string>();
+  private recordTail: Promise<void> = Promise.resolve();
+  private readonly recordListeners = new Set<(item: CommittedItem) => void>();
   readonly config: SessionConfig;
   /**
    * Replaced by switchModel. Not readonly: a live session can change which
@@ -307,13 +366,36 @@ export class Session {
   private readonly allocation: { next: number };
 
   constructor(config: SessionConfig, provider: Provider, clock: Clock = systemClock(), allocation = { next: 1 }) {
+    if (config.acceptanceContract) parseAcceptanceContract(config.acceptanceContract);
     if (config.contextPolicy !== undefined && !isContextPolicy(config.contextPolicy)) throw new Error("unknown context policy");
     stallDecision(emptyStallState(), config.stallLimit ?? DEFAULT_STALL_LIMIT);
     validateOutputRecoveryLimit(config.outputRecoveryLimit ?? DEFAULT_OUTPUT_RECOVERY_LIMIT);
     schedulingWindow([], 0, config.maxParallelTools ?? 3);
     this.allocation = allocation;
-    this.config = config;
+    this.config = { ...config, ...(config.acceptanceContract ? { acceptanceContract: parseAcceptanceContract(config.acceptanceContract) } : {}), tools: { ...config.tools, execOwner: this.execOwner, historyCache: new HistoryCache() } };
+    // A child or restored Session must never inherit another live invocation scope.
+    delete this.config.tools.invoke;
+    delete this.config.tools.invokeHost;
+    delete this.config.tools.runOwnedCommand;
+    delete this.config.tools.drainNested;
+    delete this.config.tools.origin;
+    delete this.config.tools.parentCallId;
+    delete this.config.tools.callId;
+    // Branch capability sets are owned by branchTools; a parent's optional catalog is not a grant.
+    if ((config.branchDepth ?? 0) > 0) delete this.config.tools.deferredTools;
     this.config.tools.outputStore ??= join(config.logDir, "artifacts");
+    // R4 / D8: full ancestry, not the bounded model view or a second mutable ledger.
+    // Each child Session installs its own callback even when contexts are copied.
+    this.config.tools.observedFileVersion = async absolute => {
+      const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+      if (!history.ok) throw new Error(history.error);
+      return latestObservedFileVersion(history.nodes.flatMap(node => node.events), absolute, path => resolve(this.config.tools.root, path));
+    };
+    this.config.tools.observedProcess = async session => {
+      const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+      if (!history.ok) throw new Error(history.error);
+      return latestProcessReceipt(await hydrateProcessReceipts(history.nodes, this.config.tools.outputStore!), session);
+    };
     this.provider = provider;
     this.clock = {
       now: () => clock.now(),
@@ -333,6 +415,34 @@ export class Session {
       set nextNode(value: number) { allocation.next = value; },
       worktrees: new Map(),
     };
+    this.installWorkspace();
+  }
+
+  private installWorkspace(): void {
+    delete this.config.tools.workspace;
+    this.config.tools.ownedStatePaths = [this.config.logDir, ...(this.config.blobDir ? [this.config.blobDir] : [])];
+    this.config.tools.legacyWorkspace = this.config.workspaceTracking === "legacy";
+    if (this.config.blobDir && this.config.workspaceTracking !== "legacy") this.config.tools.workspace = new WorkspaceLifecycle(
+      this.config.tools.root, this.config.blobDir, this.config.shellCheckpoints === true,
+      event => this.record({ ...event, id: this.clock.nextId(), at: this.clock.now() }),
+      join(this.config.logDir, "checkpoints"),
+      this.config.tools.ownedStatePaths,
+    );
+  }
+
+  private async observeEvidence(): Promise<void> {
+    let proof = this.state.events.findLast(event => event.t === "tool_result" && event.effect?.kind === "command");
+    let prior = proof?.t === "tool_result" && proof.effect?.kind === "command" ? proof.effect.workspace_sha256 :
+      this.state.handoff?.state.completed.at(-1)?.evidence.workspace_sha256;
+    // A short task need not create a completed note. Its last command still
+    // establishes the comparison version when the current segment is empty.
+    if (!proof && this.config.tools.workspace) {
+      const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+      if (!history.ok) throw new Error(history.error);
+      proof = history.nodes.flatMap(part => part.events).findLast(event => event.t === "tool_result" && event.effect?.kind === "command");
+      if (proof?.t === "tool_result" && proof.effect?.kind === "command") prior = proof.effect.workspace_sha256;
+    }
+    if (proof || prior || this.config.acceptanceContract) await this.config.tools.workspace?.observe(prior);
   }
 
   /**
@@ -345,7 +455,7 @@ export class Session {
    * session quietly different from a continuous one.
    */
   async start(): Promise<void> {
-    this.stall = null;
+    this.resetDerivedToolState();
     const dir = this.config.logDir;
     const model = this.provider.config.spec.id;
     const existing = await listNodes(dir);
@@ -368,6 +478,11 @@ export class Session {
         break;
 
       case "resume": {
+        this.config.acceptanceContract = null;
+        this.config.strictVerification = false;
+        this.config.workingSet = false;
+        this.config.workingSetVersion = 1;
+        delete this.config.guidanceVersion;
         // Logs predating explicit policies meant segmented, regardless of today's default.
         this.config.contextPolicy = "segmented";
         this.config.maxParallelTools = 1;
@@ -377,7 +492,19 @@ export class Session {
         if (plan.cursor.context_ref) {
           const saved = await getBlob(join(dir, "artifacts"), plan.cursor.context_ref);
           if (saved === null) throw new Error("missing frozen session context");
-          const context = JSON.parse(saved) as { frozen: FrozenPrefix; boundary?: Partial<BoundaryConfig>; contextPolicy?: unknown; stallLimit?: number; outputRecoveryLimit?: number; guidance?: boolean; gates: Record<string, string>; snapshotIgnore?: readonly string[]; workNamespace?: string; maxParallelTools?: number };
+          const context = JSON.parse(saved) as { skills?: Skill[]; acceptanceContract?: AcceptanceContract; strictVerification?: boolean; workingSet?: boolean; workingSetVersion?: 1 | 2; guidanceVersion?: 1; projectionVersion?: number; frozen: FrozenPrefix; boundary?: Partial<BoundaryConfig>; contextPolicy?: unknown; stallLimit?: number; outputRecoveryLimit?: number; guidance?: boolean; gates: Record<string, string>; snapshotIgnore?: readonly string[]; workspaceTracking?: "journal" | "legacy"; shellCheckpoints?: boolean; workNamespace?: string; maxParallelTools?: number };
+          if (context.projectionVersion !== undefined && context.projectionVersion !== PROJECTION_VERSION) throw new Error("unsupported saved projection version");
+          this.config.workingSet = context.workingSet === true;
+          if (context.workingSetVersion !== undefined && ![1, 2].includes(context.workingSetVersion)) throw new Error("unsupported saved working-set version");
+          this.config.workingSetVersion = context.workingSetVersion ?? 1;
+          if (context.guidanceVersion !== undefined && context.guidanceVersion !== 1) throw new Error("unsupported saved guidance version");
+          if (context.guidanceVersion === 1) this.config.guidanceVersion = 1;
+          this.config.workspaceTracking = context.workspaceTracking ?? "journal";
+          this.config.shellCheckpoints = context.shellCheckpoints === true;
+          if (context.acceptanceContract) { parseAcceptanceContract(context.acceptanceContract); this.config.acceptanceContract = context.acceptanceContract; }
+          this.config.strictVerification = context.strictVerification === true;
+          this.config.skills = context.skills ?? [];
+          this.installSkillResources();
           this.config.workNamespace = context.workNamespace ?? "main";
           this.config.maxParallelTools = context.maxParallelTools ?? 1;
           schedulingWindow([], 0, this.config.maxParallelTools);
@@ -427,7 +554,7 @@ export class Session {
         this.state.anchor = null;
         // Compare disk against the durable file projection. Treating current
         // disk as the baseline would erase unlogged effects of a crashed tool.
-        if (this.config.blobDir) {
+        if (this.config.blobDir && this.config.workspaceTracking === "legacy") {
           const files = await planRestoreToNode(dir, this.state.node);
           if (!files.ok) throw new Error(files.error);
           this.state.lastScan = files.files;
@@ -447,7 +574,13 @@ export class Session {
         return assertNever(plan, "Session.start");
     }
 
-    if (cursor?.needs_model_checkpoint || needsReplayCheckpoint(this.state.events, providerReplayKey(this.provider.config.spec), nativeReplay(this.provider.config.spec))) {
+    this.installWorkspace();
+    if (this.config.workspaceTracking !== "legacy") await this.recoverFileOperations();
+    this.restoreDeclaredTools();
+    // Consume the original pending receipt before another checkpoint can replace this projection.
+    const declarationCut = await this.applyDiscoveredTools();
+    await this.refreshRuntimeTargets();
+    if (!declarationCut && (cursor?.needs_model_checkpoint || needsReplayCheckpoint(this.state.events, providerReplayKey(this.provider.config.spec), nativeReplay(this.provider.config.spec)))) {
       await this.performCut("model_checkpoint", model);
     }
     await this.saveCursor();
@@ -461,6 +594,17 @@ export class Session {
    */
   async fork(destLogDir: string, untilEvent?: string, position: "at" | "before" = "at"): Promise<void> {
     await copyAncestryTo(this.config.logDir, destLogDir, this.clock.now(), untilEvent, position);
+    if (untilEvent !== undefined && this.config.workspaceTracking !== "legacy") {
+      const cursor = await readCursor(destLogDir);
+      if (!cursor) throw new Error("missing fork cursor");
+      const tip = (await readNode(this.config.logDir, this.state.node)).events.at(-1);
+      const filesFrom = { ...await digestedRef(this.config.logDir, this.state.node), ...(tip ? { at_event: tip.id } : {}) };
+      const header = (await readNode(destLogDir, cursor.node)).header;
+      const event: LogEvent = { t: "rewind", id: this.clock.nextId(), at: this.clock.now(), mode: "context", from: header?.parent ?? filesFrom,
+        files_from: filesFrom, prompt: "Forked conversation", restored: [], removed: [], unrecoverable: [], divergence: [] };
+      await appendEvent(destLogDir, cursor.node, event);
+      await writeCursor(destLogDir, { ...cursor, at_event: event.id, updated_at: event.at });
+    }
   }
 
   async setThinking(effort: Effort): Promise<void> {
@@ -468,25 +612,60 @@ export class Session {
     await this.saveCursor();
   }
 
-  /** Pi user bash shares process ownership and archival with tools, never their authority or model dispatch. */
+  /** Trusted extension commands share the Session owner without inventing a user turn. */
+  runExtensionCommand(command: string, args: string[], options?: { cwd?: string; timeout?: number; signal?: AbortSignal }): Promise<NativeCommandResult> {
+    if (this.cleanup || this.closing) return Promise.reject(new Error("session is draining or disposed"));
+    const input: NativeCommandInput = { argv: [command, ...args], ...(options?.cwd !== undefined ? { cwd: options.cwd } : {}),
+      ...(options?.timeout !== undefined ? { timeout: options.timeout } : {}) };
+    if (!this.execution.running) this.hostOwner = this.execution.begin();
+    const signals = [this.execution.signal, options?.signal].filter((signal): signal is AbortSignal => signal !== undefined);
+    const signal = AbortSignal.any(signals);
+    const result = (async () => {
+      const call: ToolCall = { type: "tool_use", call_id: `host-${randomUUID()}`, name: NATIVE_COMMAND_NAME, input };
+      const preparation = this.prepareBrokerCall(call, () => 0, false, signal, true);
+      let prepared: PreparedBrokerCall;
+      for (;;) { const step = await preparation.next(); if (step.done) { prepared = step.value; break; } }
+      const receipt = await prepared.run();
+      await receipt.commit();
+      await this.saveCursor();
+      return nativeCommandResult(receipt.value, this.config.tools.outputStore!);
+    })();
+    this.hostPending.add(result);
+    const finished = () => {
+      this.hostPending.delete(result);
+      if (this.hostPending.size === 0 && this.hostOwner) { this.hostOwner.finish(); this.hostOwner = undefined; }
+    };
+    void result.then(finished, finished);
+    return result;
+  }
+
   async runUserBash(command: string, excludeFromContext: boolean, signal?: AbortSignal,
     onOutput?: (chunk: Uint8Array) => void): Promise<Extract<LogEvent, { t: "user_bash" }>> {
+    if (this.cleanup || this.closing) throw new Error("session is draining or disposed");
     const owned = this.execution.begin(signal);
+    let release: (() => void) | undefined;
     try {
+      this.rootTools ??= new ToolQueue(this.config.maxParallelTools ?? 3);
+      release = await this.rootTools.acquire("exclusive");
       if (!command.trim()) throw new Error("empty user command");
       for await (const event of this.snapshotTurn([], false, "idle")) {
         if (event.kind === "snapshot_failed") throw new Error(event.reason);
       }
-      const captured = await observeCommand({ command, cwd: this.config.tools.root,
-        outputStore: join(this.config.logDir, "artifacts"), maxOutputBytes: this.config.tools.maxOutputBytes,
-        timeoutMs: this.config.tools.timeoutMs, signal: owned.signal, ...(onOutput ? { onOutput } : {}) });
-      const outcome = executionOutcome(captured.stopped === "cancelled" ? "cancelled" : captured.stopped === "timeout" ? "timeout"
-        : captured.exit === 0 ? "tool_completed" : "tool_failed");
-      const preview = headTailView(captured.head, captured.tail, captured.ref.bytes, this.config.tools.maxOutputBytes,
-        omitted => `\n[${omitted} bytes omitted; complete output: ${captured.ref.path}]\n`);
-      const content = `${preview}\nexit ${captured.exit} · ${outcome.status} · ${outcome.reason}`;
+      const execute = async (): Promise<ToolResult> => {
+        const captured = await observeCommand({ command, cwd: this.config.tools.root,
+          outputStore: join(this.config.logDir, "artifacts"), maxOutputBytes: this.config.tools.maxOutputBytes,
+          timeoutMs: this.config.tools.timeoutMs, signal: owned.signal, ...(onOutput ? { onOutput } : {}) });
+        const completion = commandCompletion(captured.exit, captured.stopped, captured.cleanup);
+        const preview = headTailView(captured.head, captured.tail, captured.ref.bytes, this.config.tools.maxOutputBytes,
+          omitted => `\n[${omitted} bytes omitted; complete output: ${captured.ref.path}]\n`);
+        return { ...completion, content: `${preview}\nexit ${captured.exit} · ${completion.outcome.status} · ${completion.outcome.reason}` +
+          (captured.cleanup ? `\n${captured.cleanup.message}` : ""),
+          content_ref: captured.ref, effect: { kind: "command", cmd: command, exit: captured.exit } };
+      };
+      const result = this.config.tools.workspace ? await this.config.tools.workspace.command("bash", { command }, execute, owned.signal) : await execute();
+      if (result.effect?.kind !== "command" || !result.content_ref || !result.outcome) throw new Error("missing user command observation");
       const event: Extract<LogEvent, { t: "user_bash" }> = { t: "user_bash", id: this.clock.nextId(), at: this.clock.now(),
-        command, content, exit: captured.exit, excludeFromContext, outcome, content_ref: captured.ref };
+        command, content: result.content, exit: result.effect.exit, excludeFromContext, outcome: result.outcome, content_ref: result.content_ref };
       await this.record(event);
       for await (const snapshot of this.snapshotTurn([])) {
         if (snapshot.kind === "snapshot_failed") throw new Error(snapshot.reason);
@@ -497,7 +676,11 @@ export class Session {
       await this.record({ t: "outcome", id: this.clock.nextId(), at: this.clock.now(),
         reason: "user command failed before completion; inspect the workspace before retrying", outcome: executionOutcome("execution_error") });
       throw error;
-    } finally { owned.finish(); }
+    } finally {
+      release?.();
+      while (this.hostPending.size > 0) await Promise.allSettled(this.hostPending);
+      owned.finish();
+    }
   }
 
   async userMessages(): Promise<{ id: string; node: number; text: string; images?: readonly ImageRef[] }[]> {
@@ -515,11 +698,17 @@ export class Session {
     const dir = this.config.logDir;
     const users = await this.userMessages();
     const target = await resolveHistoryPosition(dir, eventId, users.some(user => user.id === eventId) ? "before" : "at");
+    const previous = (await readNode(dir, this.state.node)).events.at(-1);
+    const filesFrom = { ...await digestedRef(dir, this.state.node), ...(previous ? { at_event: previous.id } : {}) };
     for await (const event of this.snapshotTurn([], false, "idle")) {
       if (event.kind === "snapshot_failed") throw new Error(event.reason);
     }
     const node = this.state.nextNode++;
     await initNode(dir, node, target.parent, this.clock.now(), target.basis);
+    if (this.config.workspaceTracking !== "legacy") await appendEvent(dir, node, {
+      t: "rewind", id: this.clock.nextId(), at: this.clock.now(), mode: "context", from: target.parent ?? filesFrom,
+      files_from: filesFrom, prompt: target.editorText ?? "Selected conversation position", restored: [], removed: [], unrecoverable: [], divergence: [],
+    });
     const cursor = await readCursor(dir);
     if (!cursor) throw new Error("missing current session cursor");
     const next = { ...cursor, node, next_node: this.state.nextNode, updated_at: this.clock.now(),
@@ -571,18 +760,47 @@ export class Session {
   }
 
   /** D6: changing the frozen prefix is an explicit checkpoint, never in-place prompt surgery. */
-  async reloadResources(frozen: FrozenPrefix): Promise<boolean> {
-    if (JSON.stringify(frozen) === JSON.stringify(this.config.frozen)) return false;
+  async reloadResources(frozen: FrozenPrefix, skills = this.config.skills): Promise<boolean> {
+    if (JSON.stringify(frozen) === JSON.stringify(this.config.frozen) && JSON.stringify(skills) === JSON.stringify(this.config.skills)) return false;
     if (this.running || this.isHalfRound()) throw new Error("cannot reload resources while a turn is active or a tool call is unpaired");
-    const contextRef = await this.persistContext(frozen);
+    const contextRef = await this.persistContext(frozen, skills);
     await this.performCut("model_checkpoint", this.provider.config.spec.id, undefined,
       this.provider.config.spec.provider, this.provider.config.effort, contextRef);
     this.config.frozen = frozen;
+    if (skills !== undefined) this.config.skills = skills;
+    this.installSkillResources();
     this.config.tools.allow = frozen.tools.flatMap(tool => tool !== null && typeof tool === "object" && "name" in tool && typeof tool.name === "string" ? [tool.name] : []);
     await this.saveCursor();
     return true;
   }
 
+  /** Restoring a declaration never installs code: only the current selected local catalog can supply it. */
+  private restoreDeclaredTools(): void {
+    const declared = new Set(declaredToolNames(this.config.frozen.tools));
+    const loaded = currentDeferredTools(this.config.tools).filter(tool => declared.has(tool.name)).map(tool => tool.name);
+    if (loaded.length && this.config.tools.allow !== undefined) this.config.tools.allow = [...new Set([...this.config.tools.allow, ...loaded])];
+  }
+
+  /** D5/D6: consume original discovery receipts only after every invocation has its result. */
+  private async applyDiscoveredTools(): Promise<boolean> {
+    if (this.isHalfRound() || (this.config.branchDepth ?? 0) > 0 || this.config.tools.extensions?.get(DISCOVERY_TOOL_NAME) !== DISCOVERY_TOOL) return false;
+    const declared = new Set(declaredToolNames(this.config.frozen.tools));
+    const requested = new Map(recordedDeclarations(this.state.events).map(item => [item.name, item.fingerprint]));
+    const additions = currentDeferredTools(this.config.tools).filter(tool => !declared.has(tool.name) &&
+      requested.get(tool.name) === discoveryFingerprint(tool) && discoveryPermitted(this.config.tools, tool.name));
+    if (additions.length === 0) return false;
+    const frozen = { ...this.config.frozen, tools: [...this.config.frozen.tools, ...additions] };
+    const contextRef = await this.persistContext(frozen);
+    await this.performCut("model_checkpoint", this.provider.config.spec.id, undefined,
+      this.provider.config.spec.provider, this.provider.config.effort, contextRef);
+    this.config.frozen = frozen;
+    this.restoreDeclaredTools();
+    // send() restores its base tool scope at the end; keep accepted declarations there too.
+    if (this.turnTools?.allow !== undefined) this.turnTools.allow = [...new Set([...this.turnTools.allow, ...additions.map(tool => tool.name)])];
+    await this.saveCursor();
+    return true;
+  }
+
   /**
    * The same pairing check switchModel already used. A user message
    * between tool_use and tool_result is the same unpairable request a
@@ -609,6 +827,7 @@ export class Session {
     if (pull === undefined || this.isHalfRound()) return null;
     const text = await pull("after_tools");
     if (text === null || typeof text === "string" && text.length === 0) return null;
+    if (this.turnTools) this.config.tools = { ...this.turnTools };
     return text;
   }
 
@@ -619,8 +838,17 @@ export class Session {
    * resuming from -- a crash, a kill, a closed laptop -- do not run exit
    * handlers.
    */
-  private async persistContext(frozen = this.config.frozen): Promise<string> {
+  private async persistContext(frozen = this.config.frozen, skills = this.config.skills): Promise<string> {
     return putBlob(join(this.config.logDir, "artifacts"), JSON.stringify({
+      projectionVersion: PROJECTION_VERSION,
+      workspaceTracking: this.config.workspaceTracking ?? "journal",
+      shellCheckpoints: this.config.shellCheckpoints === true,
+      ...(skills?.length ? { skills } : {}),
+      ...(this.config.acceptanceContract ? { acceptanceContract: this.config.acceptanceContract } : {}),
+      ...(this.config.strictVerification ? { strictVerification: true } : {}),
+      ...(this.config.workingSet ? { workingSet: true } : {}),
+      ...(this.config.workingSet && this.config.workingSetVersion === 2 ? { workingSetVersion: 2 } : {}),
+      ...(this.config.guidanceVersion === 1 ? { guidanceVersion: 1 } : {}),
       frozen, gates: this.config.tools.gates,
       workNamespace: this.config.workNamespace ?? "main",
       maxParallelTools: this.config.maxParallelTools ?? 3,
@@ -652,10 +880,211 @@ export class Session {
     });
   }
 
+  /** Q24: publish identities only after durable append, including non-model user actions. */
+  subscribeRecords(listener: (item: CommittedItem) => void): () => void {
+    this.recordListeners.add(listener); return () => { this.recordListeners.delete(listener); };
+  }
+
   private async record(event: LogEvent): Promise<void> {
-    await appendEvent(this.config.logDir, this.state.node, event);
-    this.state.events.push(event);
-    if (this.stall !== null) this.stall = advanceStall(this.stall, [{ node: this.state.node, event }]);
+    // D8: runtime callers may retain mutable results. The in-memory projection
+    // must own the same JSON value that was appended, independent of later edits.
+    event = JSON.parse(JSON.stringify(event)) as LogEvent;
+    const saved = this.recordTail.then(async () => {
+      await appendEvent(this.config.logDir, this.state.node, event);
+      this.state.events.push(event);
+      if (this.stall !== null) this.stall = advanceStall(this.stall, [{ node: this.state.node, event }]);
+      if (this.recovery !== null) this.recovery = advanceRecovery(this.recovery, [event], path => resolve(this.config.tools.root, path));
+      for (const listener of this.recordListeners) {
+        try { listener({ node: this.state.node, id: event.id, type: event.t }); } catch { /* observers never own the append */ }
+      }
+    });
+    this.recordTail = saved.catch(() => {});
+    await saved;
+    if (event.t === "tool_result" && event.ok && event.effect?.kind === "read") {
+      const path = resolve(this.config.tools.root, event.effect.path);
+      const skill = this.config.skills?.find(item => item.filePath === path);
+      if (skill && !skill.disableModelInvocation) {
+        await this.recordSkill(skill, "read", "model");
+        this.config.tools.allow = skillTools(this.allowedNames(), skill);
+        // Restricted skill scopes cannot grow their capability set by searching a parent directory.
+        if (skill.allowedTools !== undefined || skill.disallowedTools !== undefined) this.config.tools.deferredTools = [];
+      }
+    }
+  }
+
+  private allowedNames(): string[] {
+    return this.config.frozen.tools.flatMap(tool => tool !== null && typeof tool === "object" && "name" in tool && typeof tool.name === "string" &&
+      (this.config.tools.allow === undefined || this.config.tools.allow.includes(tool.name)) ? [tool.name] : []);
+  }
+
+  private adviceNames(frozen = this.config.frozen): string[] {
+    const declared = frozen.tools.flatMap(tool => tool !== null && typeof tool === "object" && "name" in tool && typeof tool.name === "string" ? [tool.name] : []);
+    return adviceTools({ ...this.config.tools, advice: declared, ...(frozen === this.config.frozen ? {} : { allow: declared }) });
+  }
+
+  private installSkillResources(): void {
+    this.config.tools.skillResources = (this.config.skills ?? []).map(skill => ({ path: skill.filePath,
+      text: skill.sourceText ?? skill.body, modelInvocable: !skill.disableModelInvocation && skill.context !== "fork" }));
+  }
+
+  private async recordSkill(skill: Skill, mode: "inline" | "fork" | "read", origin: "user" | "model"): Promise<void> {
+    const artifact = await putBlob(join(this.config.logDir, "artifacts"), skill.sourceText ?? skill.body);
+    await this.record({ t: "skill_loaded", id: this.clock.nextId(), at: this.clock.now(), name: skill.name, path: skill.filePath,
+      sha256: artifact, artifact, mode, origin });
+  }
+
+  /** O.12: main instructions are durable; permissions apply to this invocation only. */
+  async *sendSkill(skill: Skill, prompt: UserInput, signal?: AbortSignal): AsyncGenerator<LoopEvent> {
+    if (this.running || this.cleanup || this.closing || this.isHalfRound()) throw new Error("a skill requires an idle paired session");
+    skill = this.config.skills?.find(item => item.name === skill.name && item.filePath === skill.filePath) ?? skill;
+    if (skill.userInvocable === false) throw new Error("this skill cannot be invoked by users");
+    const savedTools = this.config.tools;
+    this.config.tools = { ...savedTools, allow: skillTools(this.allowedNames(), skill) };
+    if (skill.allowedTools !== undefined || skill.disallowedTools !== undefined) this.config.tools.deferredTools = [];
+    try {
+      await this.recordSkill(skill, skill.context === "fork" ? "fork" : "inline", "user");
+      if (skill.context !== "fork") { yield* this.send(prompt, signal); return; }
+      const owned = this.execution.begin(signal);
+      try {
+        await this.record({ t: "user", id: this.clock.nextId(), at: this.clock.now(), text: `Run isolated skill ${skill.name}; source ${skill.filePath}.` });
+        const writes = skill.allowedTools?.some(name => this.allowedNames().includes(name) &&
+          WRITING_BRANCH_TOOL_NAMES.includes(name) && !BRANCH_TOOL_NAMES.includes(name)) ?? false;
+        const result = yield* this.runBranch({ purpose: `skill ${skill.name}`, prompt: userInputData(prompt).text, writes }, 0, owned.signal, skill);
+        await result.accept?.();
+        await this.record({ t: "extension", id: this.clock.nextId(), at: this.clock.now(), customType: "skill_result", content: result.content,
+          display: true, inContext: true });
+        await this.saveCursor();
+        yield { kind: "assistant_text", text: result.content };
+        yield { kind: "done", outcome: result.outcome ?? executionOutcome("execution_error"), reason: "isolated skill finished" };
+      } finally { owned.finish(); }
+    } finally { this.config.tools = savedTools; this.restoreDeclaredTools(); }
+  }
+
+  /** O.8: dispatch and diagnostics share exact source hints, including forks. */
+  contextInput(): ProjectInput {
+    return { frozen: this.config.frozen, handoff: this.state.handoff, events: this.state.events,
+      logHint: { manifestPath: manifestPath(this.config.logDir),
+        ...(this.config.guidanceVersion === 1 ? { scopedGuidance: true } : {}),
+        segmentPath: this.state.handoff?.predecessor?.log_ref ?? nodePath(this.config.logDir, this.state.node) } };
+  }
+
+  private async boundCarried(full: Handoff, tools = this.adviceNames()): Promise<Handoff> {
+    return carriedHandoff(this.config.logDir, this.state.node, full, { handoff_tokens: DEFAULT_HANDOFF_TOKENS,
+      ...(this.config.workingSet ? { working_set_version: this.config.workingSetVersion ?? 1 } : {}),
+      ...(this.config.guidanceVersion === 1 ? { guidance_tools: tools } : {}) });
+  }
+
+  async acceptanceState(): Promise<AcceptanceState | undefined> {
+    if (!this.running) await this.observeEvidence();
+    // External editor changes must invalidate proof before the user reads it.
+    if (!this.running) for await (const result of this.snapshotTurn([], false, "idle")) {
+      if (result.kind === "snapshot_failed") throw new Error(`cannot inspect an unobserved workspace: ${result.reason}`);
+    }
+    if (!this.running) await this.refreshRuntimeTargets();
+    return (await this.currentHandoff()).acceptance;
+  }
+
+  async requestState(): Promise<RequestState | undefined> {
+    // Use the same idle workspace/target observation boundary as /acceptance.
+    if (!this.running) await this.acceptanceState();
+    const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+    if (!history.ok) throw new Error(history.error);
+    return deriveRequestState(history.nodes);
+  }
+
+  /** Only called at paired, owned boundaries; probes never enter a pending model tool exchange. */
+  private async refreshRuntimeTargets(): Promise<void> {
+    const state = (await this.currentHandoff()).acceptance;
+    const observations: string[] = [];
+    for (const target of state?.targets ?? []) if (target.observation || target.binding) {
+      const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+      if (!history.ok) throw Error(history.error);
+      const observed = await this.runtimeTargets.perform(this.config.tools, history.nodes, { action: "inspect", target: target.id });
+      const id = this.clock.nextId();
+      await this.record({ t: "target_observation", id, at: this.clock.now(), observation: observed.observation });
+      observations.push(id);
+    }
+    if (!observations.length) return;
+    const current = (await this.currentHandoff()).acceptance;
+    if (current?.targets?.some(target => {
+      const before = state?.targets?.find(item => item.id === target.id);
+      return before?.status !== target.status || before.binding !== target.binding || before.build_event !== target.build_event;
+    })) await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "runtime_acceptance", sources: observations,
+      text: `Runtime acceptance observations changed. Status ${current.status}; targets ${JSON.stringify(current.targets)}. Only a ready owned instance can receive human acceptance; old observations do not grant current ownership.` });
+  }
+
+  async workItems(): Promise<readonly WorkItem[]> {
+    const replayed = await replayContext(this.config.logDir, this.state.node);
+    return deriveHandoff({ prev: replayed.fullHandoff, events: replayed.events, depth: replayed.depth,
+      self: await this.nodeRefFor(this.state.node) }).state.work_items ?? [];
+  }
+
+  /** What the next handoff would carry if the segment were cut now. Pure derivation; nothing is written. */
+  async previewHandoff(): Promise<Handoff> { return this.currentHandoff(); }
+
+  private async currentHandoff(): Promise<Handoff> {
+    const replayed = await replayContext(this.config.logDir, this.state.node);
+    return deriveHandoff({ prev: replayed.fullHandoff, events: replayed.events, depth: replayed.depth, self: await this.nodeRefFor(this.state.node) });
+  }
+  async branchStatuses() {
+    return (await this.currentHandoff()).branches.map(item => ({ ...item, status: branchStatus(item, this.jobs.state(item.node)) }));
+  }
+  async processStatuses() {
+    const handles = new Map(runningSessions(this.execOwner).map(session => [session.id, session.exit === null ? "running" as const : "ended_unobserved" as const]));
+    const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+    if (!history.ok) throw new Error(history.error);
+    let processes: ProcessObservation[] = [];
+    for (const part of await hydrateProcessReceipts(history.nodes, this.config.tools.outputStore!)) processes = deriveProcesses(processes, part.events, part.node);
+    return processes.map(item => ({ ...item, status: processStatus(item, handles.get(item.session)) }));
+  }
+  /** User lifecycle commands share the coordinator; no model request is needed. */
+  async resolveBranch(node: number, resolution: "wait" | "cancel" | "status", waitMs = 10_000): Promise<ToolResult> {
+    if (this.running || this.cleanup || this.closing) throw new Error("branch commands require an idle session");
+    const owned = this.execution.begin();
+    try {
+      const result = await this.runResolve({ node, resolution, wait_ms: waitMs });
+      await this.saveCursor(); return finishToolResult(result);
+    } finally { owned.finish(); }
+  }
+
+  private async drainProcesses(): Promise<void> {
+    const results = await disposeExecSessions(this.execOwner, this.config.tools.outputStore!, this.config.tools.maxOutputBytes);
+    await this.config.tools.workspace?.abandonCommands();
+    for (const result of results) {
+      await this.record({ t: "process_exit", id: this.clock.nextId(), at: this.clock.now(), ...result, reason: "disposed" });
+    }
+    if (results.length > 0) await this.saveCursor();
+  }
+  private async acceptReadyBranches(): Promise<void> {
+    for (const node of this.jobs.nodes()) {
+      const done = await this.jobs.wait(node, 0);
+      if (done?.value?.accept) await done.value.accept();
+      this.jobs.forget(node);
+    }
+  }
+  dispose(): Promise<void> {
+    if (this.closing) return this.closing;
+    this.cancel();
+    this.closing = this.whenIdle().then(() => this.rootTools?.close());
+    return this.closing;
+  }
+
+  /** Only the app's user command calls this; note never grants human acceptance. */
+  async acceptCriterion(criterion: string): Promise<AcceptanceState> {
+    if (this.running || this.isHalfRound()) throw new Error("acceptance requires an idle, paired request");
+    for await (const result of this.snapshotTurn([], true)) {
+      if (result.kind === "snapshot_failed") throw new Error(`cannot accept an unobserved workspace: ${result.reason}`);
+    }
+    const current = await this.acceptanceState();
+    const item = current?.criteria.find(item => item.id === criterion && item.kind === "human");
+    if (!current || !item || item.kind !== "human") throw new Error("unknown human acceptance criterion");
+    const target = item.target ? current.targets?.find(target => target.id === item.target) : undefined;
+    if (item.target && (target?.status !== "ready" || !target.binding || !target.observation)) throw Error("human acceptance requires a current ready target instance");
+    await this.record({ t: "acceptance_decision", id: this.clock.nextId(), at: this.clock.now(), request: current.request,
+      contract_id: current.contract_id, criterion, actor: "user",
+      ...(target?.binding && target.observation ? { target_binding: target.binding, target_observation: target.observation } : {}) });
+    await this.saveCursor();
+    return (await this.acceptanceState())!;
   }
 
   async appendExtension(entry: Omit<Extract<LogEvent, { t: "extension" }>, "t" | "id" | "at">): Promise<void> {
@@ -671,8 +1100,21 @@ export class Session {
     return totalUsage(this.state.usage);
   }
 
-  cancel(): void { this.execution.cancel(); }
-  whenIdle(): Promise<void> { return this.execution.whenIdle(); }
+  cancel(): void {
+    this.execution.cancel(); this.jobs.cancel();
+    for (const child of this.children.values()) child.cancel();
+    if (!this.cleanup) this.cleanup = (async () => {
+      await this.execution.whenIdle(); await this.jobs.drain();
+      // A consumer can close at the preparation marker before execution is
+      // admitted. Those children still have an owner, even without a job.
+      for (const [node, child] of this.children) { await child.dispose(); this.children.delete(node); }
+      await this.acceptReadyBranches(); await this.drainProcesses();
+    })().then(() => { this.cleanup = null; });
+    // A void cancellation caller may await later. Preserve rejection for the
+    // owner while preventing an unhandled rejection from bypassing that path.
+    void this.cleanup.catch(() => {});
+  }
+  async whenIdle(): Promise<void> { await this.execution.whenIdle(); await this.cleanup; }
   get running(): boolean { return this.execution.running; }
 
   /**
@@ -690,9 +1132,15 @@ export class Session {
     userText: UserInput,
     signal?: AbortSignal,
     pull?: (phase: Phase) => Promise<UserInput | null>,
+    requestId?: string,
   ): AsyncGenerator<LoopEvent> {
+    if (this.cleanup || this.closing) throw new Error("session is draining or disposed");
     const owned = this.execution.begin(signal);
-    const events = this.run(userText, owned.signal, pull);
+    const savedTools = this.config.tools;
+    this.turnTools = savedTools;
+    this.config.tools = { ...savedTools };
+    this.installSkillResources();
+    const events = this.run(userText, owned.signal, pull, requestId);
     let terminal = false;
     let exhausted = false;
     try {
@@ -705,13 +1153,16 @@ export class Session {
             t: "outcome", id: this.clock.nextId(), at: this.clock.now(),
             reason: item.value.reason ?? item.value.outcome.reason, outcome: item.value.outcome,
           });
+          const request = await this.requestState();
+          if (request) item.value.request = request;
         }
         yield item.value;
       }
       if (!terminal) {
         const outcome = executionOutcome("snapshot_failed");
         await this.record({ t: "outcome", id: this.clock.nextId(), at: this.clock.now(), reason: "workspace snapshot failed", outcome });
-        yield { kind: "done", reason: "stopped: workspace snapshot failed", outcome };
+        const request = await this.requestState();
+        yield { kind: "done", reason: "stopped: workspace snapshot failed", outcome, ...(request ? { request } : {}) };
       }
     } catch (error) {
       // Raw provider exceptions can contain credentials; persist only the execution fact.
@@ -725,7 +1176,13 @@ export class Session {
         if (!exhausted) {
           await events.return(undefined);
         }
-      } finally { owned.finish(); }
+      } finally {
+        while (this.hostPending.size > 0) await Promise.allSettled(this.hostPending);
+        this.config.tools = savedTools; this.turnTools = null;
+        if (owned.signal.aborted) this.cancel();
+        owned.finish();
+        if (owned.signal.aborted) await this.whenIdle();
+      }
     }
   }
 
@@ -733,7 +1190,10 @@ export class Session {
     userText: UserInput,
     signal?: AbortSignal,
     pull?: (phase: Phase) => Promise<UserInput | null>,
+    requestId?: string,
   ): AsyncGenerator<LoopEvent> {
+    // A crash after a discovery receipt but before its cut is recovered from that same receipt.
+    if (!signal?.aborted) await this.applyDiscoveredTools();
     if (needsReplayCheckpoint(this.state.events, providerReplayKey(this.provider.config.spec), nativeReplay(this.provider.config.spec))) {
       if (this.isHalfRound()) throw new Error("Cannot change a wire profile while tool results are pending");
       await this.performCut("model_checkpoint");
@@ -744,9 +1204,10 @@ export class Session {
       if (this.isHalfRound()) throw new Error("Cannot change image transmission while tool results are pending");
       await this.performCut("model_checkpoint");
     }
-    await this.record({
-      t: "user", id: this.clock.nextId(), at: this.clock.now(), ...userInputData(userText, blocked),
-    });
+    const request = requestId ?? this.clock.nextId();
+    await this.record({ t: "user", id: request, at: this.clock.now(), ...userInputData(userText, blocked) });
+    if (this.config.acceptanceContract) await this.record({ t: "acceptance_contract", id: this.clock.nextId(), at: this.clock.now(),
+      request: this.state.events.at(-1)!.id, contract: this.config.acceptanceContract });
     // Idle changes belong to the new prompt. Recording them before `user`
     // would silently move the preceding exchange's restore point forward.
     for await (const event of this.snapshotTurn([])) {
@@ -774,12 +1235,11 @@ export class Session {
         yield { kind: "turn_start", node: this.state.node };
 
         if (this.config.guidance !== false) {
-          const names = this.config.frozen.tools.flatMap((tool) => {
-            if (tool === null || typeof tool !== "object" || !("name" in tool) || typeof tool.name !== "string") return [];
-            return this.config.tools.allow === undefined || this.config.tools.allow.includes(tool.name) ? [tool.name] : [];
-          });
-          const guidance = continuationGuidance({ events: this.state.events, handoff: this.state.handoff,
+          const names = this.adviceNames();
+          const guidance = (this.config.harnessReviews === false ? null : await this.recoveryGuidance(names)) ??
+            continuationGuidance({ events: this.state.events, handoff: this.state.handoff,
             tools: names, remainingRequests: this.config.maxTurns - turn,
+            ...(this.config.guidanceVersion === 1 ? { taskAware: true } : {}),
             ...(this.config.continuationAfter === undefined ? {} : { minAssistantTurns: this.config.continuationAfter }) }) ??
             (this.config.timeBudgetMs === undefined ? null
               : deadlineNotice(requestStarted, this.clock.now(), this.config.timeBudgetMs, this.state.events)) ??
@@ -793,15 +1253,7 @@ export class Session {
           yield { kind: "done", reason: "stopped: context cannot fit the model window", outcome: executionOutcome("context_budget") };
           return;
         }
-        const projected = projectContext({
-          frozen: this.config.frozen,
-          handoff: this.state.handoff,
-          events: this.state.events,
-          logHint: {
-            manifestPath: manifestPath(this.config.logDir),
-            segmentPath: nodePath(this.config.logDir, Math.max(0, this.state.node - 1)),
-          },
-        });
+        const projected = projectContext(this.contextInput());
 
         // Pairing violations are a 400 waiting to happen; surface them here,
         // where the cause is still visible, rather than as a request failure.
@@ -826,6 +1278,8 @@ export class Session {
         try {
           result = yield* this.awaitProvider(projected.messages, signal);
         } catch (error) {
+          // D11: retain a typed response receipt once, without anchoring rejected content or trusting arbitrary error fields.
+          if (error instanceof FailedResponseError && error.usage !== undefined) this.state.usage.push({ ...error.usage });
           if (signal?.aborted) {
             yield* this.closeInterrupted(completedThisTurn);
             return;
@@ -836,8 +1290,7 @@ export class Session {
           // shrink is a cut, so force one and send once more; a second
           // overflow means even the retained tail is misjudged, and another
           // attempt would only be paid for.
-          if (overflowRetried || (this.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY) !== "windowed" ||
-              windowBudget(this.provider.config.spec.contextWindow, this.provider.config.maxTokens) === null) {
+          if (overflowRetried || this.policyLimits().kind !== "window") {
             yield { kind: "done", reason: `stopped: provider rejected the prompt as too long (${error.message})`, outcome: executionOutcome("context_budget") };
             return;
           }
@@ -852,6 +1305,14 @@ export class Session {
 
         const previous = this.state.usage.at(-1);
         this.state.usage.push(result.usage);
+        // Q24: an adapter may finish after abort. Keep measured usage, but cancellation
+        // owns termination and a late response cannot enter context or execute tools.
+        if (signal?.aborted) {
+          yield { kind: "usage", usage: result.usage, ok: true };
+          yield { kind: "discard" };
+          yield* this.closeInterrupted(completedThisTurn);
+          return;
+        }
         const promptTokens =
           result.usage.input_tokens +
           result.usage.cache_creation_input_tokens +
@@ -890,6 +1351,15 @@ export class Session {
           };
         }
 
+        // D5: ambiguous IDs cannot be persisted or paired safely. Keep sampled
+        // usage, but stop before observer hooks or any tool effect can run.
+        const identityViolations = toolCallIdentityViolations(result.blocks);
+        if (identityViolations.length > 0) {
+          yield { kind: "done", outcome: executionOutcome("provider_error"),
+            reason: `stopped: invalid provider tool call identity (${identityViolations.map(violation => `${violation.code}: ${violation.detail}`).join("; ")})` };
+          return;
+        }
+
         await this.record({
           t: "assistant", id: this.clock.nextId(), at: this.clock.now(), blocks: result.blocks, stop_reason: result.stopReason,
           replay_key: providerReplayKey(this.provider.config.spec),
@@ -912,7 +1382,7 @@ export class Session {
           }
           const extra = await this.pullSteering(pull);
           if (extra !== null) {
-            await this.record({ t: "user", id: this.clock.nextId(), at: this.clock.now(), ...userInputData(extra, blocked) });
+            await this.record({ t: "user", id: this.clock.nextId(), at: this.clock.now(), request, ...userInputData(extra, blocked) });
             continue;
           }
           const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
@@ -935,18 +1405,25 @@ export class Session {
           const extra = await this.pullSteering(pull);
           if (extra !== null) {
             await this.record({
-              t: "user", id: this.clock.nextId(), at: this.clock.now(), ...userInputData(extra, blocked),
+              t: "user", id: this.clock.nextId(), at: this.clock.now(), request, ...userInputData(extra, blocked),
             });
             continue;
           }
-          const review = this.config.guidance === false || this.config.harnessReviews === false ? null
-            : completionReview(this.state.events, this.config.maxTurns - turn - 1);
-          if (review) {
-            await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), ...review });
+          if (this.config.acceptanceContract) await this.refreshRuntimeTargets();
+          const state = await this.requestState();
+          const decision = !state || this.config.guidance === false || this.config.harnessReviews === false ? { action: "finish" as const }
+            : requestCompletion(state, this.config.maxTurns - turn - 1, {
+              ...(this.config.guidanceVersion === 1 ? { taskAware: true } : {}),
+              ...(this.config.strictVerification ? { strictVerification: true } : {}),
+            });
+          if (decision.action === "continue") {
             if (yield* this.maybeCut(counter, true)) {
               yield { kind: "done", reason: "stopped: no verifiable progress", outcome: executionOutcome("no_progress") };
               return;
             }
+            // Q23: a notice appended before a cut can disappear from the next
+            // projection. Append at the destination so the provider sees it once.
+            await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), ...decision.guidance });
             continue;
           }
           const stopped = yield* this.maybeCut(counter, false);
@@ -959,7 +1436,7 @@ export class Session {
         }
 
         let branchesThisTurn = 0;
-        type Settled = { ok: true; value: DeferredToolResult } | { ok: false; error: unknown };
+        type Settled = { ok: true; value: SessionBrokerReceipt } | { ok: false; error: unknown };
         const pending = new Map<string, Promise<Settled>>();
         const modes = calls.map(call => this.executionMode(call));
         try { for (let callIndex = 0; callIndex < calls.length; callIndex++) {
@@ -975,88 +1452,33 @@ export class Session {
               const planned = calls[index]!;
               yield { kind: "tool_call", tool: { name: planned.name, input: planned.input } };
               if (signal?.aborted) break;
-              const dispatch = yield* this.prepareConcurrentCall(planned, planned.name === "branch" ? branchesThisTurn++ : 0, signal);
-              pending.set(planned.call_id, dispatch().then(value => ({ ok: true as const, value }), error => ({ ok: false as const, error })));
+              const dispatch = yield* this.prepareBrokerCall(planned, () => branchesThisTurn++, blocked, signal);
+              pending.set(planned.call_id, dispatch.run().then(value => ({ ok: true as const, value }), error => ({ ok: false as const, error })));
             }
           }
 
-          let out: DeferredToolResult;
-          let annotation: LogEvent | undefined;
+          let receipt: SessionBrokerReceipt;
           const dispatched = pending.get(call.call_id);
           if (dispatched) {
             const settled = await dispatched;
             pending.delete(call.call_id);
             if (!settled.ok) throw settled.error;
-            out = settled.value;
+            receipt = settled.value;
           } else {
             if (signal?.aborted) { yield* this.closeInterrupted(completedThisTurn); return; }
-
             yield { kind: "tool_call", tool: { name: call.name, input: call.input } };
-
-            // Checked again after the yield: that is the window a consumer has
-            // after seeing the call and before it runs. The first check above
-            // covers abort arriving between calls.
-            if (signal?.aborted) {
-              yield* this.closeInterrupted(completedThisTurn);
-              return;
-            }
-
-            // Three tools are not workspace actions and are handled here:
-            // `note` writes an annotation the handoff is built from, and
-            // `branch`/`resolve` act on the tree. Each still produces an ordinary
-            // tool_result so the turn stays pairable. They go through the same
-            // gate as read/write/edit/bash, which runTool applies itself.
-            const toolContext = { ...this.config.tools, imageStore: this.config.blobDir ?? join(this.config.logDir, "blobs"), imageAutoResize: this.config.imageOptions?.autoResize ?? true, ...(signal ? { signal } : {}) };
-            if (call.name === "note" || call.name === "branch" || call.name === "resolve" || call.name === "history") {
-              const gated = await gateTool(toolContext, call.name, call.input);
-              if (gated) {
-                out = gated;
-              } else if (call.name === "history") {
-                out = await runHistoryTool(this.config.logDir, this.state.node, toolContext, call.input);
-              } else if (call.name === "note") {
-                const parsed = parseNote(call.input);
-                const prepared = await prepareWorkingNote(this.config.logDir, this.state.node, this.config.workNamespace ?? "main",
-                  parsed.annotation ? this.toEvent(parsed.annotation) : undefined, parsed.result);
-                out = prepared.out; annotation = prepared.annotation;
-              } else if (call.name === "branch") {
-                out = yield* this.runBranch(call.input, branchesThisTurn++, signal);
-              } else {
-                out = await this.runResolve(call.input);
-              }
-            } else {
-              const decoder = new TextDecoder();
-              out = yield* withProgress<ToolResult, LoopEvent>(emit => runTool({ ...toolContext, callId: call.call_id,
-                onOutput: chunk => emit({ kind: "progress", progress: { kind: "output", name: call.name, text: decoder.decode(chunk, { stream: true }) } }),
-              }, call.name, call.input));
-            }
+            if (signal?.aborted) { yield* this.closeInterrupted(completedThisTurn); return; }
+            const prepared = yield* this.prepareBrokerCall(call, () => branchesThisTurn++, blocked, signal);
+            receipt = yield* withProgress<SessionBrokerReceipt, LoopEvent>(emit => prepared.run(emit));
           }
-          if (out.accept) for (const event of await out.accept()) yield event;
-          out = finishToolResult(out);
-          // Observation precedes persistence, preserving the after-effect crash
-          // boundary. A lost process here recovers as unknown, never as success.
+          await receipt.settle();
+          for (const event of receipt.events.splice(0)) yield event;
+          const out = finishToolResult(receipt.value);
+          // Observation still precedes persistence: crashes here remain unknown,
+          // while nested receipts have already been committed before their caller resumed.
           yield { kind: "tool_result", text: out.content, ok: out.ok, outcome: out.outcome! };
+          await receipt.commit();
 
-          // Recorded before the tool_result so a claim can never precede the
-          // evidence it cites -- deriveHandoff resolves a claim against runs at
-          // or before it, and an annotation is about work already done.
-          if (annotation) await this.record(annotation);
-
-          await this.record({
-            t: "tool_result",
-            id: this.clock.nextId(),
-            at: this.clock.now(),
-            call_id: call.call_id,
-            ok: out.ok,
-            content: out.content,
-            outcome: out.outcome!,
-            ...(out.data !== undefined ? { data: out.data } : {}),
-            ...(out.observation_sha256 !== undefined ? { observation_sha256: out.observation_sha256 } : {}),
-            ...(out.diagnostic !== undefined ? { diagnostic: out.diagnostic } : {}),
-            ...(out.content_sha256 ? { content_sha256: out.content_sha256 } : {}),
-            ...(out.content_ref ? { content_ref: out.content_ref } : {}),
-            ...(out.images?.length ? { images: submissionImages(out.images, blocked) } : {}),
-            ...(out.effect ? { effect: out.effect } : {}),
-          });
           completedThisTurn.push(call.call_id);
           if (signal?.aborted && pending.size === 0) {
             yield* this.closeInterrupted(completedThisTurn);
@@ -1068,6 +1490,8 @@ export class Session {
         // that means anything, and per-call would be the character-level
         // granularity the research warns against.
         yield* this.snapshotTurn(calls.map((c) => c.call_id));
+        const declarationNode = this.state.node;
+        if (!signal?.aborted && await this.applyDiscoveredTools()) yield { kind: "cut", node: declarationNode, reason: "model_checkpoint" };
         if (this.pendingAdoption !== null) await this.adoptPendingBranch();
 
         // Between complete exchanges is the only safe place to cut.
@@ -1079,7 +1503,7 @@ export class Session {
         const extra = await this.pullSteering(pull);
         if (extra !== null) {
           await this.record({
-            t: "user", id: this.clock.nextId(), at: this.clock.now(), ...userInputData(extra, blocked),
+            t: "user", id: this.clock.nextId(), at: this.clock.now(), request, ...userInputData(extra, blocked),
           });
         }
       }
@@ -1111,6 +1535,9 @@ export class Session {
           id: this.clock.nextId(),
           at: this.clock.now(),
           call_id: block.call_id,
+          ...(block.invocation_id ? { invocation_ref: { node: this.state.node, event: block.invocation_id } } : {}),
+          ...(block.parent_call_id ? { parent_call_id: block.parent_call_id } : {}),
+          ...(block.origin ? { origin: block.origin } : {}),
           ok: false,
           content: resultText,
           outcome: executionOutcome("unknown"),
@@ -1200,6 +1627,8 @@ export class Session {
    * delta rather than a copy of the workspace.
    */
   private async *snapshotTurn(callIds: readonly string[], baseline = false, phase: "turn" | "idle" = "turn"): AsyncGenerator<LoopEvent> {
+    // P.3: retained only for explicit historical compatibility. New sessions never scan here.
+    if (this.config.workspaceTracking !== "legacy") return;
     const blobDir = this.config.blobDir;
     if (!blobDir) return;
 
@@ -1278,41 +1707,207 @@ export class Session {
    * the same thing, so nothing here has to reimplement the loop.
    */
   private executionMode(call: ToolCall): "parallel" | "exclusive" {
+    if (this.config.tools.extensionHooks?.serial?.()) return "exclusive";
+    if (call.name === "read" && typeof call.input === "object" && call.input !== null &&
+      this.config.skills?.some(skill => skill.filePath === resolve(this.config.tools.root, String((call.input as Record<string, unknown>)["path"])))) return "exclusive";
     if (call.name === "branch" && typeof call.input === "object" && call.input !== null &&
-        (call.input as Record<string, unknown>)["writes"] !== true) return "parallel";
+        (call.input as Record<string, unknown>)["writes"] !== true && (call.input as Record<string, unknown>)["background"] !== true) return "parallel";
     return toolDefinition(call.name, this.config.tools)?.execution ?? "exclusive";
   }
 
-  private async *prepareConcurrentCall(call: ToolCall, branchIndex: number, signal?: AbortSignal): AsyncGenerator<LoopEvent, () => Promise<DeferredToolResult>> {
-    const ctx = { ...this.config.tools, callId: call.call_id, imageStore: this.config.blobDir ?? join(this.config.logDir, "blobs"), imageAutoResize: this.config.imageOptions?.autoResize ?? true, ...(signal ? { signal } : {}) };
-    if (call.name !== "branch") {
-      const prepared = await prepareTool(ctx, call.name, call.input);
-      return typeof prepared === "function" ? prepared : async () => prepared;
-    }
-    const gated = await gateTool(ctx, call.name, call.input);
-    if (gated) return async () => gated;
-    const branch = this.runBranch(call.input, branchIndex, signal);
-    while (true) {
-      const step = await branch.next();
-      if (step.done) return async () => step.value;
-      yield step.value;
-      // Spawn and snapshot preparation remain ordered. Advancing past this
-      // marker starts only the child's execution, which may overlap siblings.
-      if (step.value.kind === "branch_start") return async () => {
-        const result = await branch.next();
-        if (result.done) return result.value;
-        throw new Error(`unexpected child execution event: ${result.value.kind}`);
-      };
+  private async *dispatchBranch(input: unknown, index: number, signal?: AbortSignal): AsyncGenerator<LoopEvent, DeferredToolResult> {
+    if (typeof input !== "object" || input === null || !("background" in input) || input.background !== true) return yield* this.runBranch(input, index, signal);
+    if (this.jobs.active >= (this.config.maxParallelTools ?? 3)) return { ok: false, content: "background branch capacity reached; wait or cancel an owned branch first" };
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    const detach = () => signal?.removeEventListener("abort", abort);
+    const child = this.runBranch(input, index, controller.signal);
+    let registered = false;
+    try {
+      for (;;) {
+        const step = await child.next();
+        if (step.done) return step.value;
+        yield step.value;
+        if (step.value.kind !== "branch_start") continue;
+        const node = step.value.node!;
+        this.jobs.start(node, controller, async () => {
+          const result = await child.next();
+          if (!result.done) throw new Error("unexpected background child yield");
+          return result.value;
+        }, detach);
+        registered = true;
+        return { ok: true, content: `branch ${node} running; ` + (this.adviceNames().includes("resolve")
+          ? `use resolve(node=${node}, resolution='status'|'wait'|'cancel')` : "branch-observation capability unavailable; completion is unknown"), data: { node, background: true, running: true } };
+      }
+    } finally { if (!registered) detach(); }
+  }
+
+  private async *prepareBrokerCall(call: ToolCall, nextBranch: () => number, blockedImages: boolean,
+    signal?: AbortSignal, native = false): AsyncGenerator<LoopEvent, PreparedBrokerCall> {
+    this.rootTools ??= new ToolQueue(this.config.maxParallelTools ?? 3);
+    const release = await this.rootTools.acquire(this.executionMode(call));
+    let transferred = false;
+    let scope: BrokerExecution<DeferredToolResult> | undefined;
+    try {
+      const events: LoopEvent[] = [];
+      let emit = (event: LoopEvent) => { events.push(event); };
+      let context: ToolContext = { ...this.config.tools, imageStore: this.config.blobDir ?? join(this.config.logDir, "blobs"),
+        advice: this.allowedNames(),
+        imageAutoResize: this.config.imageOptions?.autoResize ?? true, ...(signal ? { signal } : {}) };
+      if (native) context = nativeCommandContext(context);
+      const decoder = new TextDecoder();
+      context.onOutput = chunk => emit({ kind: "progress", progress: { kind: "output", name: call.name, text: decoder.decode(chunk, { stream: true }) } });
+      const broker = new ToolBroker<DeferredToolResult>({
+        parallelLimit: this.config.maxParallelTools ?? 3,
+        callId: () => `nested-${randomUUID()}`,
+        mode: request => this.executionMode(request),
+        invocation: (request, ctx, parent) => this.recordInvocation(request, ctx, parent),
+        prepare: (request, ctx) => this.prepareSessionAction(request, ctx, nextBranch, event => emit(event)),
+        settle: async result => {
+          if (result.accept) events.push(...await result.accept());
+          if (!result.content_ref) Object.assign(result, await presentObservation(context, result.content));
+        },
+        result: async (invocation, result) => {
+          if (result.annotation) await this.record(result.annotation);
+          await this.recordToolReceipt(invocation, finishToolResult(result), blockedImages);
+        },
+      });
+      const execute = yield* withProgress<BrokerExecution<DeferredToolResult>, LoopEvent>(async output => {
+        emit = output;
+        scope = await broker.prepare(call, context);
+        return scope;
+      });
+      emit = event => { events.push(event); };
+      transferred = true;
+      return { run: async output => {
+        if (output) emit = output;
+        let commitOwnsSlot = false;
+        try {
+          const receipt = await execute();
+          if (native) {
+            // An idle host result has no generator consumer to own its commit.
+            // Retain the slot so a checkpoint cannot split invocation from receipt.
+            commitOwnsSlot = true;
+            return { ...receipt, events, commit: async () => { try { await receipt.commit(); } finally { release(); } } };
+          }
+          return { ...receipt, events };
+        } finally { emit = event => { events.push(event); }; if (!commitOwnsSlot) release(); }
+      } };
+    } finally { if (!transferred) { try { await scope?.close(); } finally { release(); } } }
+  }
+
+  private async recordInvocation(call: ToolCall, ctx: ToolContext, parent?: ToolInvocationEvent): Promise<ToolInvocationEvent> {
+    const store = ctx.outputStore ?? join(this.config.logDir, "artifacts");
+    const encode = (value: unknown) => new TextEncoder().encode(JSON.stringify(value));
+    const archive = async (bytes: Uint8Array) => {
+      async function* source() { yield bytes; }
+      return (await archiveObservation(store, source(), 0)).ref;
+    };
+    let valid = false;
+    try { valid = isJsonValue(call.input); } catch { /* Cyclic or excessively deep host input is not a JSON request. */ }
+    const bytes = encode(valid ? call.input : { unavailable: "non-JSON arguments", type: typeof call.input });
+    const definition = toolDefinition(call.name, ctx);
+    const declared = this.config.frozen.tools.find(tool => tool !== null && typeof tool === "object" && "name" in tool && tool.name === call.name &&
+      "description" in tool && typeof tool.description === "string" && "input_schema" in tool) as ReturnType<typeof modelToolSchema> | undefined;
+    const schema = definition ? declared ?? modelToolSchema(definition, adviceTools(ctx)) : undefined;
+    const descriptor = definition ? { version: 1, ...schema,
+      ...(declared && JSON.stringify(declared.input_schema) !== JSON.stringify(definition.input_schema) ? { admission_schema: definition.input_schema } : {}),
+      access: definition.access, execution: definition.execution, branch: definition.branch, hiddenInputs: definition.hiddenInputs ?? [], result_version: 1 } : null;
+    const original = this.state.events.findLast(event => event.t === "assistant" && event.blocks.some(block => block.type === "tool_use" && block.call_id === call.call_id));
+    const originalInput = original?.t === "assistant" ? original.blocks.find(block => block.type === "tool_use" && block.call_id === call.call_id) : undefined;
+    const changed = originalInput?.type !== "tool_use" || valid && JSON.stringify(originalInput.input) !== JSON.stringify(call.input);
+    const event: ToolInvocationEvent = { t: "tool_invocation", id: this.clock.nextId(), at: this.clock.now(), call_id: call.call_id, name: call.name,
+      ...(ctx.origin ? { origin: ctx.origin } : {}),
+      input_ref: await archive(bytes), schema_ref: descriptor ? await archive(encode(descriptor)) : null,
+      ...(parent ? { parent_call_id: parent.call_id, parent_ref: { node: this.state.node, event: parent.id } } : {}),
+      ...(valid && bytes.length <= MAX_NESTED_ARGUMENT_BYTES && (parent || changed) ? { input: call.input as JsonValue } : {}) };
+    await this.record(event); return event;
+  }
+
+  private async recordToolReceipt(invocation: ToolInvocationEvent, out: ToolResult, blockedImages: boolean): Promise<void> {
+    let data = out.data;
+    let dataRef;
+    if (data !== undefined) {
+      const bytes = new TextEncoder().encode(JSON.stringify(data));
+      if (bytes.length > MAX_INLINE_RESULT_DATA_BYTES) {
+        async function* source() { yield bytes; }
+        dataRef = (await archiveObservation(this.config.tools.outputStore!, source(), 0)).ref;
+        data = undefined;
+      }
     }
+    await this.record({ t: "tool_result", id: this.clock.nextId(), at: this.clock.now(), call_id: invocation.call_id,
+      invocation_ref: { node: this.state.node, event: invocation.id },
+      ...(invocation.origin ? { origin: invocation.origin } : {}),
+      ...(invocation.parent_call_id ? { parent_call_id: invocation.parent_call_id } : {}), ok: out.ok, content: out.content,
+      ...(out.outcome ? { outcome: out.outcome } : {}), ...(data !== undefined ? { data } : {}), ...(dataRef ? { data_ref: dataRef } : {}),
+      ...(out.observation_sha256 !== undefined ? { observation_sha256: out.observation_sha256 } : {}),
+      ...(out.observation ? { observation: out.observation } : {}), ...(out.diagnostic ? { diagnostic: out.diagnostic } : {}),
+      ...(out.warnings ? { warnings: out.warnings } : {}), ...(out.content_sha256 ? { content_sha256: out.content_sha256 } : {}),
+      ...(out.content_ref ? { content_ref: out.content_ref } : {}),
+      ...(out.images?.length ? { images: submissionImages(out.images, blockedImages) } : {}), ...(out.effect ? { effect: out.effect } : {}) });
+  }
+
+  private async prepareSessionAction(call: ToolCall, ctx: ToolContext, nextBranch: () => number,
+    emit: (event: LoopEvent) => void): Promise<DeferredToolResult | (() => Promise<DeferredToolResult>)> {
+    // SDK callers may omit allow or preauthorize an optional name. Permission is
+    // distinct from a declaration: neither direct nor nested calls may run it early.
+    const declared = declaredToolNames(this.config.frozen.tools);
+    if (ctx.deferredTools?.some(tool => tool.name === call.name) && !declared.includes(call.name)) {
+      return prepareNormalizedTool({ ...ctx, allow: (ctx.allow ?? declared).filter(name => name !== call.name) }, call.name, call.input);
+    }
+    const forkSkill = call.name === "read" && typeof call.input === "object" && call.input !== null ? this.config.skills?.find(skill =>
+      skill.context === "fork" && skill.filePath === resolve(ctx.root, String((call.input as Record<string, unknown>)["path"]))) : undefined;
+    const discovery = call.name === DISCOVERY_TOOL_NAME && ctx.extensions?.get(call.name) === DISCOVERY_TOOL;
+    if (!forkSkill && !discovery && !["note", "branch", "resolve", "history", "target"].includes(call.name)) return prepareNormalizedTool(ctx, call.name, call.input);
+    const branchIndex = forkSkill || call.name === "branch" ? nextBranch() : 0;
+    return prepareNormalizedTool(ctx, call.name, call.input, async () => {
+      if (discovery) return async () => searchDeferredTools(ctx, call.input as Record<string, unknown>, this.allowedNames());
+      if (call.name === "history") return () => runHistoryTool(this.config.logDir, this.state.node, ctx, call.input);
+      if (call.name === "target") return async () => {
+        const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+        if (!history.ok) throw Error(history.error);
+        const observed = await this.runtimeTargets.perform(ctx, history.nodes, call.input as Parameters<RuntimeTargets["perform"]>[2]);
+        return { ...observed.result, annotation: { t: "target_observation" as const, id: this.clock.nextId(), at: this.clock.now(), observation: observed.observation } };
+      };
+      if (call.name === "note") return async () => {
+        await this.observeEvidence();
+        const parsed = parseNote(call.input);
+        const prepared = await prepareWorkingNote(this.config.logDir, this.state.node, this.config.workNamespace ?? "main",
+          parsed.annotation ? this.toEvent(parsed.annotation) : undefined, parsed.result);
+        return { ...prepared.out, ...(prepared.annotation ? { annotation: prepared.annotation } : {}) };
+      };
+      if (call.name === "resolve") return () => this.runResolve(call.input);
+      if (forkSkill?.disableModelInvocation) return async () => ({ ok: false, content: "this skill requires explicit user invocation" });
+      if (forkSkill) await this.recordSkill(forkSkill, "fork", "model");
+      const task = this.state.events.findLast(event => event.t === "user");
+      const branch = forkSkill ? this.runBranch({ purpose: `skill ${forkSkill.name}`, prompt: `${forkSkill.body}\n\nCurrent task: ${task?.t === "user" ? task.text : ""}` },
+        branchIndex, ctx.signal, forkSkill, skillTools(this.allowedNames(), forkSkill), "model") : this.dispatchBranch(call.input, branchIndex, ctx.signal);
+      while (true) {
+        const step = await branch.next();
+        if (step.done) return async () => step.value;
+        emit(step.value);
+        if (step.value.kind === "branch_start") return async () => {
+          const result = await branch.next();
+          if (!result.done) throw new Error(`unexpected child execution event: ${result.value.kind}`);
+          return result.value;
+        };
+      }
+    });
   }
 
   private async *runBranch(
     input: unknown,
     indexThisTurn: number,
     signal?: AbortSignal,
+    skill?: Skill,
+    allowedOverride?: readonly string[],
+    skillOrigin: "user" | "model" = "user",
   ): AsyncGenerator<LoopEvent, DeferredToolResult> {
     const limits = this.limits;
     const depth = this.config.branchDepth ?? 0;
+    if (this.children.size >= (this.config.maxParallelTools ?? 3)) return { ok: false, content: "branch capacity reached; wait or cancel an owned branch first" };
 
     // Every refusal is a normal tool_result: an unanswered tool_use makes the
     // next request unpairable, and a refusal can say what to do instead.
@@ -1349,7 +1944,7 @@ export class Session {
     if (!purpose || !prompt) {
       return { content: "a branch needs both a purpose and a prompt", ok: false };
     }
-    const parentAllow = this.config.tools.allow;
+    const parentAllow = allowedOverride ?? this.config.tools.allow;
     const branchNames = writes ? WRITING_BRANCH_TOOL_NAMES : BRANCH_TOOL_NAMES;
     const allowed: string[] = parentAllow
       ? branchNames.filter(name => parentAllow.includes(name)) : [...branchNames];
@@ -1387,6 +1982,7 @@ export class Session {
 
     await this.record({
       t: "spawn", id: this.clock.nextId(), at: this.clock.now(), branch: ref, purpose,
+      ...(args["background"] === true ? { background: true as const } : {}),
       input: { source_event: sourceEvent, tools: allowed, max_turns: Math.min(this.config.maxTurns, 15), workspace: inputWorkspace },
       ...(worktree ? { workspace: worktree } : {}),
     });
@@ -1399,7 +1995,8 @@ export class Session {
     const branch = new Session(
       {
         ...this.config,
-        frozen: { system: this.config.frozen.system, tools: branchTools(writes).filter((t) => allowed.includes(t.name)) },
+        acceptanceContract: null,
+        frozen: { system: this.config.frozen.system, tools: branchTools(writes, allowed) },
         // The same list twice: the schema shapes what the model asks for, the
         // allow-list decides what actually runs. Intersected with the parent
         // so `--exclude-tools bash` cannot be undone by opening a branch.
@@ -1407,6 +2004,7 @@ export class Session {
           ...this.config.tools,
           ...(worktree ? { root: worktree.path } : {}),
           allow: allowed,
+          readonlyBranch: !writes,
         },
         branchDepth: depth + 1,
         workNamespace: `branch-${node}`,
@@ -1419,14 +2017,16 @@ export class Session {
     branch.state.node = node;
     branch.state.nextNode = this.state.nextNode;
     branch.state.lastScan = { ...this.state.lastScan };
+    if (skill) await branch.recordSkill(skill, "fork", skillOrigin);
+    this.children.set(node, branch);
     yield { kind: "branch_start", node, reason: purpose, at: Date.now() };
-    for await (const event of branch.snapshotTurn([], true)) {
-      if (event.kind === "snapshot_failed") throw new Error(`cannot establish branch baseline: ${event.reason}`);
-    }
 
     let text = "";
     let outcome = executionOutcome("unknown");
     try {
+      for await (const event of branch.snapshotTurn([], true)) {
+        if (event.kind === "snapshot_failed") throw new Error(`cannot establish branch baseline: ${event.reason}`);
+      }
       for await (const e of branch.send(prompt, signal)) {
         if (e.kind === "assistant_text" && e.text) text = e.text;
         if (e.kind === "done") outcome = e.outcome ?? executionOutcome("unknown");
@@ -1435,7 +2035,8 @@ export class Session {
       // Persist a bounded failure classification, never a provider's raw error body.
       outcome = executionOutcome(signal?.aborted ? "cancelled" : "execution_error");
       await branch.answerUnpairedTools("the branch execution failed; this tool's outcome is unknown; inspect before retrying");
-    }
+    } finally { try { await branch.dispose(); } finally { this.children.delete(node); } }
+    if (args["background"] === true) await branch.record({ t: "outcome", id: this.clock.nextId(), at: this.clock.now(), outcome, reason: "background branch execution ended" });
     // Node numbers the branch allocated are taken.
 
     const tip = branch.state.node;
@@ -1455,29 +2056,40 @@ export class Session {
         "not in your files. Adopting continues in that checkout without merging it into this one."
       : "";
     const summary = text.trim() || "(the branch produced no closing message)";
+    const receiptHistory = await readNodeHistory(this.config.logDir, tip, undefined, "context");
+    if (!receiptHistory.ok) throw new Error(receiptHistory.error);
+    const receipt = deriveBranchReceipt({ source: await this.nodeRefFor(tip), outcome, handoff, nodes: receiptHistory.nodes });
+    const receiptRef = await putBlob(join(this.config.logDir, "artifacts"), JSON.stringify(receipt));
     const joined: LogEvent = {
       t: "joined", id: this.clock.nextId(), at: this.clock.now(),
       branch: ref, tip: await this.nodeRefFor(tip), handoff_ref: handoffPath(this.config.logDir, tip), summary,
       model: branch.provider.config.spec.id,
       outcome,
+      receipt_ref: receiptRef,
     };
 
     // Only the summary crosses back. The branch's own calls stay in its node,
     // which is the entire reason to branch rather than read in place.
     return {
       content:
-        `branch ${node} (${purpose}) ended: ${JSON.stringify(outcome)}.\n\n${summary}${where}\n\n` +
+        `branch ${node} (${purpose}) ended: ${JSON.stringify(outcome)}.\n` +
+        `Evidence receipt: ${receipt.commands.length} commands, ${receipt.changes.length} file edits, ${receipt.unfinished.length} unfinished items; verification=${receipt.verification}; task acceptance=not assessed.\n` +
+        (this.adviceNames().includes("history") ? `Read history(artifact='${receiptRef}'), then history(branch=${node}, event='source ID') for original evidence.\n`
+          : `Evidence receipt artifact=${receiptRef}; original-source recovery capability unavailable.\n`) +
+        `Child closing statement (unverified):\n${summary}${where}\n\n` +
         `Its full state is at ${handoffPath(this.config.logDir, tip)}. ` +
-        `Resolve it with resolve(node: ${node}, ...).`,
+        (this.adviceNames().includes("resolve") ? `Resolve it with resolve(node: ${node}, ...).` : "Branch-resolution capability unavailable."),
       ok: outcome.status === "completed",
       outcome,
       accept: async () => {
+        if ((await this.branchStatuses()).some(item => item.node === node && item.handoff_ref)) return [];
         this.state.usage.push(...branch.state.usage);
-        await this.saveCursor();
         await this.record(joined);
+        await this.saveCursor();
         return [{ kind: "branch_done", node, text: summary, outcome, ok: outcome.status === "completed" }];
       },
       data: { node, outcome, handoff_ref: handoffPath(this.config.logDir, tip), requests: branch.state.usage.length,
+        receipt_ref: receiptRef,
         input: { source_event: sourceEvent, workspace: inputWorkspace } },
     };
   }
@@ -1502,10 +2114,33 @@ export class Session {
       return { ok: false, content: `branch ${node} is already resolved` };
     }
 
+    const joined = events.find((e) => e.t === "joined" && e.branch.node === node);
+    if (resolution === "status") {
+      const item = (await this.branchStatuses()).find(branch => branch.node === node)!;
+      return { ok: true, content: `branch ${node}: ${item.status}`, data: { node, status: item.status } };
+    }
+    if (resolution === "wait" || resolution === "cancel") {
+      if (joined) return { ok: true, content: `branch ${node} already joined; receipt ${joined.t === "joined" ? joined.receipt_ref ?? "not recorded" : ""}` };
+      if (resolution === "cancel" && this.jobs.state(node) === undefined) return { ok: false, content: `branch ${node}: unknown after restart; no owned handle to cancel` };
+      if (resolution === "cancel") { this.jobs.cancel(node); await this.jobs.drain(node); }
+      const waitMs = args["wait_ms"] === undefined ? 10_000 : args["wait_ms"];
+      if (typeof waitMs !== "number" || !Number.isFinite(waitMs) || waitMs < 0 || waitMs > 60_000) return { ok: false, content: "wait_ms must be between 0 and 60000" };
+      const result = await this.jobs.wait(node, waitMs);
+      if (result?.running) return { ok: true, content: `branch ${node} running; wait reached its deadline`, data: { node, running: true } };
+      if (result?.error) return { ok: false, content: result.error };
+      const complete = result?.value ?? await this.recoverBranchResult(node);
+      if (!complete) return { ok: false, content: `branch ${node}: unknown after restart; no sealed execution outcome; inspect before retrying` };
+      if (complete.accept) await complete.accept();
+      this.jobs.forget(node);
+      return complete;
+    }
+    if (this.jobs.state(node) === "running") return { ok: false, content: `branch ${node} running; wait or cancel before resolving it` };
+    if (!joined && this.jobs.state(node) === "ready") return { ok: false, content: `branch ${node} has not joined; wait before resolving it` };
+
     const ref = await this.nodeRefFor(node);
     if (resolution === "adopt") {
+      if ((await this.branchStatuses()).some(item => item.node !== node && item.background && !item.handoff_ref && item.resolution === null)) return { ok: false, content: "wait or cancel other unjoined background branches before adoption" };
       if (this.pendingAdoption !== null) return { content: "resolve one adoption per tool round", ok: false };
-      const joined = events.find((e) => e.t === "joined" && e.branch.node === node);
       if (!joined) return { content: `branch ${node} has not joined`, ok: false };
       await this.record({ t: "adopt", id: this.clock.nextId(), at: this.clock.now(), branch: ref });
       this.pendingAdoption = node;
@@ -1533,52 +2168,97 @@ export class Session {
       }
       return { content: `discarded branch ${node}`, ok: true };
     }
-    return { content: `resolution must be "adopt" or "discard"`, ok: false };
+    return { content: `resolution must be wait, cancel, status, adopt or discard`, ok: false };
+  }
+
+  private async recoverBranchResult(root: number): Promise<DeferredToolResult | undefined> {
+    // Recover only a unique sealed continuation. An open or ambiguous branch
+    // cannot be replayed safely because tools may already have had effects.
+    const headers = await Promise.all((await listNodes(this.config.logDir)).map(async node => ({ node, header: (await readNode(this.config.logDir, node)).header })));
+    let tip = root;
+    const seen = new Set<number>();
+    for (;;) {
+      if (seen.has(tip)) return undefined;
+      seen.add(tip);
+      const children = headers.filter(item => item.header?.parent?.node === tip && item.header.basis !== "none");
+      if (children.length > 1) return undefined;
+      if (children.length === 0) break;
+      tip = children[0]!.node;
+    }
+    if (!(await readManifest(this.config.logDir)).nodes.some(item => item.node === tip && item.handoff_ref)) return undefined;
+    const history = await readNodeHistory(this.config.logDir, tip, undefined, "context");
+    if (!history.ok) throw new Error(history.error);
+    const outcomeEvent = history.nodes.flatMap(part => part.events).findLast(event => event.t === "outcome");
+    if (outcomeEvent?.t !== "outcome") return undefined;
+    const handoff = await replayContext(this.config.logDir, tip);
+    const full = deriveHandoff({ prev: handoff.fullHandoff, events: handoff.events, depth: handoff.depth, self: await this.nodeRefFor(tip) });
+    const receipt = deriveBranchReceipt({ source: await this.nodeRefFor(tip), outcome: outcomeEvent.outcome, handoff: full, nodes: history.nodes });
+    const receiptRef = await putBlob(join(this.config.logDir, "artifacts"), JSON.stringify(receipt));
+    const last = history.nodes.flatMap(part => part.events).findLast(event => event.t === "assistant");
+    const summary = last?.t === "assistant" ? last.blocks.flatMap(block => block.type === "text" ? [block.text] : []).join("\n") : "(no closing message)";
+    return { ok: outcomeEvent.outcome.status === "completed", outcome: outcomeEvent.outcome,
+      content: `branch ${root} recovered from sealed node ${tip}; receipt ${receiptRef}; closing statement is unverified: ${summary}`,
+      data: { node: root, outcome: outcomeEvent.outcome, receipt_ref: receiptRef, handoff_ref: handoffPath(this.config.logDir, tip) },
+      accept: async () => {
+        if ((await this.branchStatuses()).some(item => item.node === root && item.handoff_ref)) return [];
+        await this.record({ t: "joined", id: this.clock.nextId(), at: this.clock.now(), branch: await this.nodeRefFor(root), tip: await this.nodeRefFor(tip),
+          handoff_ref: handoffPath(this.config.logDir, tip), receipt_ref: receiptRef, summary, outcome: outcomeEvent.outcome });
+        await this.saveCursor(); return [];
+      } };
   }
 
   /** D15: finish the parent's tool round before moving to the chosen branch. */
   private async adoptPendingBranch(): Promise<void> {
-    const root = this.pendingAdoption;
-    if (root === null) return;
-    const history = await readNodeHistory(this.config.logDir, this.state.node);
-    if (!history.ok) throw new Error(history.error);
-    const events = history.nodes.flatMap((n) => n.events);
-    const joined = events.find((e) => e.t === "joined" && e.branch.node === root);
-    const spawned = events.find((e) => e.t === "spawn" && e.branch.node === root);
-    if (joined?.t !== "joined" || spawned?.t !== "spawn") throw new Error(`missing provenance for adoption ${root}`);
-    const parent = this.state.node;
-    const annotations = carryForward(events, spawned.id, parent);
-    const tip = joined.tip ?? joined.branch;
-    const intent = events.findLast((e) => e.t === "adopt" && e.branch.node === root && e.next_node !== undefined);
-    const node = intent?.t === "adopt" && intent.next_node !== undefined ? intent.next_node : this.state.nextNode++;
-    if (!intent) await this.record({ t: "adopt", id: this.clock.nextId(), at: this.clock.now(), branch: joined.branch, next_node: node });
-    const parentRef = await this.nodeRefFor(parent);
-    const existing = await readNode(this.config.logDir, node);
-    if (existing.header === null) await initNode(this.config.logDir, node, tip, this.clock.now(), "inherit", { adopted_from: parentRef });
-    else if (existing.header.adopted_from?.node !== parent || existing.header.parent?.node !== tip.node) {
-      throw new Error(`INTEGRITY: adoption successor ${node} belongs to another transition`);
-    }
-    const rebuilt = await replayContext(this.config.logDir, node);
-    this.state.node = node;
-    this.state.nextNode = Math.max(this.state.nextNode, node + 1);
-    this.state.events = rebuilt.contextEvents;
-    this.stall = null;
-    this.state.handoff = rebuilt.handoff;
-    this.state.depth = rebuilt.depth;
-    this.state.anchor = null;
-    const copied = new Set(existing.events.flatMap((e) => "carried_from" in e && e.carried_from ? [e.carried_from.event] : []));
-    for (const event of annotations) if (!copied.has(event.carried_from!.event)) await this.record({ ...event, id: this.clock.nextId() });
-    if (!existing.events.some((e) => e.t === "adopt" && e.applied && e.branch.node === root)) {
-      await this.record({ t: "adopt", id: this.clock.nextId(), at: this.clock.now(), branch: joined.branch, applied: true });
-    }
-    const checkout = this.state.worktrees.get(root);
-    if (checkout) this.config.tools.root = checkout.path;
-    const scan = await scanWorkspace(this.config.tools.root, this.ignore);
-    if (!scan.ok) throw new Error(`cannot adopt workspace: ${scan.error}`);
-    this.state.lastScan = scan.files;
-    await this.saveCursor();
-    this.pendingAdoption = null;
-    if (joined.model !== undefined && joined.model !== this.provider.config.spec.id) await this.performCut("model_checkpoint");
+    this.rootTools ??= new ToolQueue(this.config.maxParallelTools ?? 3);
+    const release = await this.rootTools.acquire("exclusive");
+    let checkpoint = false;
+    try {
+      const root = this.pendingAdoption;
+      if (root === null) return;
+      const history = await readNodeHistory(this.config.logDir, this.state.node);
+      if (!history.ok) throw new Error(history.error);
+      const events = history.nodes.flatMap((n) => n.events);
+      const joined = events.find((e) => e.t === "joined" && e.branch.node === root);
+      const spawned = events.find((e) => e.t === "spawn" && e.branch.node === root);
+      if (joined?.t !== "joined" || spawned?.t !== "spawn") throw new Error(`missing provenance for adoption ${root}`);
+      const parent = this.state.node;
+      const annotations = carryForward(events, spawned.id, parent);
+      const tip = joined.tip ?? joined.branch;
+      const intent = events.findLast((e) => e.t === "adopt" && e.branch.node === root && e.next_node !== undefined);
+      const node = intent?.t === "adopt" && intent.next_node !== undefined ? intent.next_node : this.state.nextNode++;
+      if (!intent) await this.record({ t: "adopt", id: this.clock.nextId(), at: this.clock.now(), branch: joined.branch, next_node: node });
+      const parentRef = await this.nodeRefFor(parent);
+      const existing = await readNode(this.config.logDir, node);
+      if (existing.header === null) await initNode(this.config.logDir, node, tip, this.clock.now(), "inherit", { adopted_from: parentRef });
+      else if (existing.header.adopted_from?.node !== parent || existing.header.parent?.node !== tip.node) {
+        throw new Error(`INTEGRITY: adoption successor ${node} belongs to another transition`);
+      }
+      const rebuilt = await replayContext(this.config.logDir, node);
+      this.state.node = node;
+      this.state.nextNode = Math.max(this.state.nextNode, node + 1);
+      this.state.events = rebuilt.contextEvents;
+      this.resetDerivedToolState();
+      this.state.handoff = rebuilt.handoff;
+      this.state.depth = rebuilt.depth;
+      this.state.anchor = null;
+      const copied = new Set(existing.events.flatMap((e) => "carried_from" in e && e.carried_from ? [e.carried_from.event] : []));
+      for (const event of annotations) if (!copied.has(event.carried_from!.event)) await this.record({ ...event, id: this.clock.nextId() });
+      if (!existing.events.some((e) => e.t === "adopt" && e.applied && e.branch.node === root)) {
+        await this.record({ t: "adopt", id: this.clock.nextId(), at: this.clock.now(), branch: joined.branch, applied: true });
+      }
+      const checkout = this.state.worktrees.get(root);
+      if (checkout) this.config.tools.root = checkout.path;
+      if (this.config.workspaceTracking === "legacy") {
+        const scan = await scanWorkspace(this.config.tools.root, this.ignore);
+        if (!scan.ok) throw new Error(`cannot adopt workspace: ${scan.error}`);
+        this.state.lastScan = scan.files;
+      }
+      this.installWorkspace();
+      await this.saveCursor();
+      this.pendingAdoption = null;
+      checkpoint = joined.model !== undefined && joined.model !== this.provider.config.spec.id;
+    } finally { release(); }
+    if (checkpoint) await this.performCut("model_checkpoint");
   }
 
   private toEvent(a: Annotation): LogEvent {
@@ -1595,7 +2275,9 @@ export class Session {
         };
       }
       case "next_action":
-        return { t: "next_action", ...stamp, what: a.what, next_action: a.next_action, ...(a.work_id ? { work_id: a.work_id } : {}) };
+        return { t: "next_action", ...stamp, what: a.what, next_action: a.next_action, ...(a.work_id ? { work_id: a.work_id } : {}), ...(a.depends_on ? { depends_on: a.depends_on } : {}) };
+      case "work_owner": return { ...a, ...stamp, owner: this.config.workNamespace ?? "main" };
+      case "work_dependencies": return { ...a, ...stamp };
       case "decision":
         return {
           t: "decision", ...stamp, chose: a.chose, because: a.because,
@@ -1617,12 +2299,85 @@ export class Session {
 
   // ---- rewind ---------------------------------------------------------------
 
+  /** A prepared edit can be reconciled by its exact path; unknown commands are never replayed. */
+  private async recoverFileOperations(): Promise<void> {
+    if (!this.config.blobDir) return;
+    // A cut is only legal after paired tools, so pending operations belong to this node.
+    const history = (await readNode(this.config.logDir, this.state.node)).events.filter((event): event is CheckpointEvent => event.t === "checkpoint");
+    const pending = new Map<string, CheckpointEvent>();
+    for (const event of history) {
+      if (event.phase === "prepared") pending.set(event.operation, event);
+      else pending.delete(event.operation);
+    }
+    for (const event of pending.values()) {
+      let applied = event.source !== "git" && changedPaths(event.changes).length > 0;
+      for (const [path, change] of Object.entries(event.changes)) {
+        try { if (!sameVersion((await readEditableFile(this.config.tools.root, path)).version, change.after)) applied = false; }
+        catch { applied = false; }
+      }
+      await this.record({ ...event, id: this.clock.nextId(), at: this.clock.now(), phase: applied ? "applied" : "unavailable",
+        reason: applied ? "observed the prepared file version after restart; tool outcome remains unknown" : "interrupted checkpoint; inspect files before retrying" });
+    }
+  }
+
+  private async rewindJournal(point: RestorePoint, mode: RewindMode): Promise<RewindResult> {
+    const dir = this.config.logDir, root = this.config.tools.root, blobs = this.config.blobDir;
+    if (mode !== "context" && !blobs) return { ok: false, error: "this session stores no file checkpoints" };
+    try {
+      const target = { node: point.node, atEvent: point.atEvent };
+      // Reading the log validates the target. Context-only navigation never reads workspace contents.
+      const history = await readNodeHistory(dir, point.node);
+      if (!history.ok) throw new Error(history.error);
+      if (!history.nodes.find(part => part.node === point.node)?.events.some(event => event.id === point.atEvent)) throw new Error(`NO_SUCH_EVENT: ${point.atEvent}`);
+      const changes: FileChanges = await planCheckpointRestore(dir, this.state.node, target).catch(error => {
+        if (mode !== "context") throw error;
+        return {};
+      });
+      const paths = changedPaths(changes);
+      const historical = await readCursorAt(dir, point.node, point.atEvent);
+      const from: NodeRef = { ...await digestedRef(dir, point.node), at_event: point.atEvent };
+      const latest = (await readNode(dir, this.state.node)).events.at(-1);
+      const filesFrom: NodeRef = { ...await digestedRef(dir, this.state.node), ...(latest ? { at_event: latest.id } : {}) };
+      if (mode !== "context" && blobs) {
+        await preflightChanges(root, blobs, changes);
+        // Persist the intention before files move; recovery never invents command completion.
+        const operation = this.clock.nextId();
+        await this.record({ t: "checkpoint", id: operation, at: this.clock.now(), operation, source: "restore", phase: "prepared", changes });
+        await applyFileChanges(root, blobs, changes);
+        await this.record({ t: "checkpoint", id: this.clock.nextId(), at: this.clock.now(), operation, source: "restore", phase: "applied", changes });
+      }
+      const restored = mode === "context" ? [] : paths.filter(path => changes[path]!.after !== null);
+      const removed = mode === "context" ? [] : paths.filter(path => changes[path]!.after === null);
+      const event: LogEvent = { t: "rewind", id: this.clock.nextId(), at: this.clock.now(), mode, from, prompt: point.prompt,
+        restored, removed, unrecoverable: [], divergence: mode === "both" ? [] : paths,
+        ...(mode === "context" ? { files_from: filesFrom } : {}) };
+      if (mode === "files") await this.record(event);
+      else {
+        const node = this.state.nextNode++;
+        await initNode(dir, node, from, this.clock.now(), "inherit");
+        const replayed = await replayContext(dir, node);
+        this.state.node = node; this.state.events = [...replayed.contextEvents]; this.state.handoff = replayed.handoff;
+        this.state.depth = replayed.depth; this.state.anchor = null; this.resetDerivedToolState();
+        await this.record(event);
+        if (historical === null || !sameModel(historical, { model: this.provider.config.spec.id, provider: this.provider.config.spec.provider })) {
+          const cursor = await readCursor(dir);
+          if (cursor) await writeCursor(dir, { ...cursor, node, next_node: this.state.nextNode, needs_model_checkpoint: true });
+          await this.performCut("model_checkpoint", this.provider.config.spec.id);
+        }
+      }
+      await this.saveCursor();
+      return { ok: true, node: this.state.node, restored, removed, unrecoverable: [], note: mode === "context"
+        ? "Only the conversation moved; workspace files were left unchanged."
+        : "Restored recorded file changes. Unrelated files, ignored paths and external effects were left unchanged; command recovery requires captured Git checkpoints." };
+    } catch (error) { return { ok: false, error: String(error) }; }
+  }
+
   private get ignore(): readonly string[] {
     return this.config.snapshotIgnore ?? DEFAULT_IGNORE;
   }
 
   /**
-   * Every completed exchange on the current ancestry that changed a file.
+   * Every completed exchange, including abandoned branches and conversation-only turns.
    *
    * An exchange runs from one user message to just before the next, so its
    * last event is where a fork belongs: the conversation is whole there, and
@@ -1668,6 +2423,8 @@ export class Session {
         }
       };
       for (const e of n.events) {
+        if (e.t === "workspace_observation") continue;
+        if (e.t === "checkpoint" && e.source === "restore") { close(); open = null; continue; }
         if (e.t === "snapshot" && e.phase === "idle") {
           close();
           open = null;
@@ -1683,6 +2440,7 @@ export class Session {
         }
         if (!open) continue;
         open.last = e.id;
+        if (e.t === "checkpoint" && e.phase === "applied") open.changed += changedPaths(e.changes).length;
         if (e.t === "snapshot") {
           open.changed +=
             Object.keys(e.added).length + Object.keys(e.changed).length + e.removed.length;
@@ -1696,12 +2454,26 @@ export class Session {
   /**
    * What a rewind would do, without doing it.
    *
-   * Going back deletes whatever the target did not have, which necessarily
-   * includes a file a person wrote by hand while the session was idle. That
-   * is the right behaviour -- a half-restored workspace is worse -- but it is
-   * the half of the operation nobody asked for, so it is shown first.
+   * P.3 previews only logged paths and preflights conflicts when files will move.
+   * Context-only navigation consults history without reading workspace contents.
    */
-  async previewRewind(point: RestorePoint): Promise<RewindPreview> {
+  async previewRewind(point: RestorePoint, mode: RewindMode = "both"): Promise<RewindPreview> {
+    if (mode === "context") {
+      const history = await readNodeHistory(this.config.logDir, point.node);
+      if (!history.ok) return history;
+      if (!history.nodes.find(part => part.node === point.node)?.events.some(event => event.id === point.atEvent)) return { ok: false, error: `NO_SUCH_EVENT: ${point.atEvent}` };
+      const changes = await planCheckpointRestore(this.config.logDir, this.state.node, { node: point.node, atEvent: point.atEvent }).catch((): FileChanges => ({}));
+      return { ok: true, willWrite: changedPaths(changes).filter(path => changes[path]!.after !== null),
+        willDelete: changedPaths(changes).filter(path => changes[path]!.after === null) };
+    }
+    if (this.config.workspaceTracking !== "legacy") {
+      try {
+        const changes = await planCheckpointRestore(this.config.logDir, this.state.node, { node: point.node, atEvent: point.atEvent });
+        if (this.config.blobDir) await preflightChanges(this.config.tools.root, this.config.blobDir, changes);
+        return { ok: true, willWrite: changedPaths(changes).filter(path => changes[path]!.after !== null),
+          willDelete: changedPaths(changes).filter(path => changes[path]!.after === null) };
+      } catch (error) { return { ok: false, error: String(error) }; }
+    }
     const plan = await planRestoreToNode(
       this.config.logDir, { node: point.node, atEvent: point.atEvent },
       undefined, this.config.tools.root, this.ignore,
@@ -1721,14 +2493,12 @@ export class Session {
    * still a node, so it is still a restore target, and "rewound too far" is
    * recoverable rather than terminal.
    *
-   * BOTH HALVES OR NEITHER. Moving the cursor without the files leaves the
-   * session on a node whose context describes a workspace that is not on
-   * disk. Claude Code's own docs warn that this divergence causes unexpected
-   * behaviour; we would additionally flag the whole restore as undeclared
-   * damage at the next turn boundary. So the files move first and the node is
-   * opened only if that worked.
+   * P.3 records a separate physical file cursor for context-only navigation.
+   * In combined mode, file restoration must succeed before opening the new
+   * conversation node. File-only restoration appends its observed transition.
    */
   async rewind(point: RestorePoint, mode: RewindMode = "both"): Promise<RewindResult> {
+    if (this.config.workspaceTracking !== "legacy") return this.rewindJournal(point, mode);
     const dir = this.config.logDir;
     const root = this.config.tools.root;
     const target = { node: point.node, atEvent: point.atEvent };
@@ -1817,7 +2587,7 @@ export class Session {
     this.state.node = node;
     this.state.events = [];
     this.state.handoff = replayed.handoff;
-    this.stall = null;
+    this.resetDerivedToolState();
     this.state.depth = replayed.depth;
     // The new node's prefix has never been sent, so nothing to anchor to.
     this.state.anchor = null;
@@ -1868,6 +2638,20 @@ export class Session {
     ].sort();
   }
 
+  private resetDerivedToolState(): void {
+    this.stall = null;
+    this.recovery = null;
+  }
+
+  private async recoveryGuidance(tools: readonly string[]): Promise<ReturnType<typeof recoveryReview>> {
+    if (this.recovery === null) {
+      const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+      if (!history.ok) throw new Error(history.error);
+      this.recovery = advanceRecovery(emptyRecoveryState(), history.nodes.flatMap(node => node.events), path => resolve(this.config.tools.root, path));
+    }
+    return recoveryReview(this.recovery, tools);
+  }
+
   private async *checkStall(): AsyncGenerator<LoopEvent, boolean> {
     const limit = this.config.stallLimit ?? DEFAULT_STALL_LIMIT;
     if (limit === 0) return false;
@@ -1894,8 +2678,8 @@ export class Session {
    * prompt reads as exactly over the usable window.
    */
   private async *maybeWindowCut(counter: TokenCounter, willContinue: boolean, overflowed = false): AsyncGenerator<LoopEvent, boolean> {
-    const budget = windowBudget(this.provider.config.spec.contextWindow, this.provider.config.maxTokens);
-    if (!willContinue || budget === null || pendingToolCalls(this.state.events).length > 0) return false;
+    const budget = this.policyLimits();
+    if (!willContinue || budget.kind !== "window" || pendingToolCalls(this.state.events).length > 0) return false;
     const project = () => projectContext({ frozen: this.config.frozen, handoff: this.state.handoff, events: this.state.events });
     let projected = project();
     const measured = anchoredCount(projected.messages, projected.system, this.state.anchor, counter, this.config.frozen.tools).tokens;
@@ -1906,7 +2690,7 @@ export class Session {
     const replayed = await replayContext(this.config.logDir, this.state.node);
     let draft: Handoff;
     try {
-      draft = boundHandoff(deriveHandoff({ prev: replayed.fullHandoff, events: replayed.events,
+      draft = await this.boundCarried(deriveHandoff({ prev: replayed.fullHandoff, events: replayed.events,
         depth: replayed.depth, self: await digestedRef(this.config.logDir, this.state.node),
         config: { maxUserTurns: Infinity, maxUserTurnBytes: Infinity } }));
     } catch (error) {
@@ -1948,8 +2732,19 @@ export class Session {
     return false;
   }
 
+  /** Every threshold the loop acts at. The footer and banner read the same function. */
+  private policyLimits(): ContextLimits {
+    return contextLimits({
+      policy: this.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY,
+      contextWindow: this.provider.config.spec.contextWindow,
+      outputReserve: this.provider.config.maxTokens,
+      ...(this.config.boundary ? { boundary: this.config.boundary } : {}),
+    });
+  }
+
   private async *maybeCut(counter: TokenCounter, canPrepare: boolean): AsyncGenerator<LoopEvent, boolean> {
-    if ((this.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY) === "windowed" && this.provider.config.spec.contextWindow !== undefined) {
+    const limits = this.policyLimits();
+    if (limits.kind === "window") {
       return yield* this.maybeWindowCut(counter, canPrepare);
     }
     const projected = projectContext({
@@ -1976,20 +2771,19 @@ export class Session {
     const inheritedTokens = counter.count(floor.messages, floor.system, this.config.frozen.tools);
 
     const policy = this.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY;
-    const cfg = { ...DEFAULT_BOUNDARY, ...this.config.boundary };
     let draft: Handoff | null = null;
-    if (policy !== "continuous" && tokens >= cfg.triggerTokens - (cfg.hardTokens - cfg.triggerTokens)) {
+    if (limits.kind === "segment" && tokens >= limits.prepare) {
       // Read the same full ancestry used by the actual cut. A bounded carried
       // page is insufficient to decide whether all active work is completed.
       const replayed = await replayContext(this.config.logDir, this.state.node);
-      draft = boundHandoff(deriveHandoff({ prev: replayed.fullHandoff, events: replayed.events,
+      draft = await this.boundCarried(deriveHandoff({ prev: replayed.fullHandoff, events: replayed.events,
         depth: replayed.depth, self: await digestedRef(this.config.logDir, this.state.node),
         config: { maxUserTurns: Infinity, maxUserTurnBytes: Infinity } }));
       const noteEnabled = this.config.frozen.tools.some((tool) => tool !== null && typeof tool === "object" && "name" in tool && tool.name === "note") &&
         (this.config.tools.allow === undefined || this.config.tools.allow.includes("note"));
-      if (canPrepare && this.config.guidance !== false && noteEnabled && tokens < cfg.hardTokens) {
+      if (canPrepare && this.config.guidance !== false && noteEnabled && tokens < limits.hard) {
         const notice = boundaryPreparation({ events: this.state.events, tokens, inheritedTokens,
-          continuationReady: draft.continuation_valid, config: cfg });
+          continuationReady: draft.continuation_valid, config: limits.config });
         if (notice) {
           await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), ...notice });
           const updated = projectContext({ frozen: this.config.frozen, handoff: this.state.handoff, events: this.state.events });
@@ -2058,56 +2852,68 @@ export class Session {
    */
   private async performCut(reason: CutReason, nextModel = this.provider.config.spec.id, retainedFrom?: string,
     nextProvider = this.provider.config.spec.provider, nextThinking = this.provider.config.effort, nextContextRef?: string): Promise<void> {
-    const dir = this.config.logDir;
-    const node = this.state.node;
-
-    const replayed = await replayContext(dir, node);
-    const fromDisk = replayed.events;
-    const retained = retainedFrom === undefined ? [] : retainedContext(replayed.contextEvents, retainedFrom);
+    this.rootTools ??= new ToolQueue(this.config.maxParallelTools ?? 3);
+    const release = await this.rootTools.acquire("exclusive");
+    try {
+      const dir = this.config.logDir;
+      const node = this.state.node;
+
+      const replayed = await replayContext(dir, node);
+      const fromDisk = replayed.events;
+      const retained = retainedFrom === undefined ? [] : retainedContext(replayed.contextEvents, retainedFrom);
+      let guidanceTools = this.adviceNames();
+      if (this.config.guidanceVersion === 1 && nextContextRef !== undefined) {
+        const saved = await getBlob(join(dir, "artifacts"), nextContextRef);
+        if (saved === null) throw new Error("missing successor guidance context");
+        guidanceTools = this.adviceNames((JSON.parse(saved) as { frozen: FrozenPrefix }).frozen);
+      }
 
-    // The cut event is part of the closed file. Digest after appending it
-    // so predecessor.sha256 matches what closeNode writes into the manifest.
-    await this.record({
-      t: "cut",
-      id: this.clock.nextId(),
-      at: this.clock.now(),
-      handoff_ref: handoffPath(dir, node),
-      predecessor: this.state.handoff?.predecessor ?? null,
-      reason,
-      next_node: this.state.nextNode,
-      next_model: nextModel,
-      next_provider: nextProvider,
-      next_thinking: nextThinking,
-      ...(nextContextRef === undefined ? {} : { next_context_ref: nextContextRef }),
-      handoff_tokens: DEFAULT_HANDOFF_TOKENS,
-      ...(retainedFrom === undefined ? {} : { retained_from: retainedFrom }),
-    });
-    const self = await digestedRef(dir, node);
-    const handoff = boundHandoff(deriveHandoff({
-      prev: replayed.fullHandoff,
-      depth: replayed.depth,
-      events: fromDisk,
-      self,
-      config: { maxUserTurns: Infinity, maxUserTurnBytes: Infinity },
-    }));
-    await closeNode(dir, node, handoff, (await readNode(dir, node)).events.length, this.clock.now());
-
-    // One allocator for the whole session. A cut used to take node + 1 while
-    // a branch took nextNode++, so a cut after a branch reached the branch's
-    // id and overwrote its log.
-    this.state.node = this.state.nextNode++;
-    this.state.depth += 1;
-    this.state.handoff = handoff;
-    this.state.events = retained;
-    // The new node's prefix has never been sent, so there is nothing to anchor
-    // to until its first response comes back.
-    this.state.anchor = null;
-    // A cut declares a handoff basis: the closed node's events do not replay,
-    // its derived state does. Relying on the default here would silently make
-    // every boundary a fork and replay the whole history.
-    await initNode(dir, this.state.node, self, this.clock.now(), "handoff");
-    // The durable successor already belongs to the target provider, even if
-    // the process exits before switchModel installs its in-memory adapter.
-    await this.saveCursor(nextModel, nextProvider, nextThinking, nextContextRef);
+      // The cut event is part of the closed file. Digest after appending it
+      // so predecessor.sha256 matches what closeNode writes into the manifest.
+      await this.record({
+        t: "cut",
+        id: this.clock.nextId(),
+        at: this.clock.now(),
+        handoff_ref: handoffPath(dir, node),
+        predecessor: this.state.handoff?.predecessor ?? null,
+        reason,
+        next_node: this.state.nextNode,
+        next_model: nextModel,
+        next_provider: nextProvider,
+        next_thinking: nextThinking,
+        ...(nextContextRef === undefined ? {} : { next_context_ref: nextContextRef }),
+        handoff_tokens: DEFAULT_HANDOFF_TOKENS,
+        ...(this.config.workingSet ? { working_set_version: this.config.workingSetVersion ?? 1 } : {}),
+        ...(this.config.guidanceVersion === 1 ? { guidance_tools: guidanceTools } : {}),
+        ...(retainedFrom === undefined ? {} : { retained_from: retainedFrom }),
+      });
+      const self = await digestedRef(dir, node);
+      const handoff = await this.boundCarried(deriveHandoff({
+        prev: replayed.fullHandoff,
+        depth: replayed.depth,
+        events: fromDisk,
+        self,
+        config: { maxUserTurns: Infinity, maxUserTurnBytes: Infinity },
+      }), guidanceTools);
+      await closeNode(dir, node, handoff, (await readNode(dir, node)).events.length, this.clock.now());
+
+      // One allocator for the whole session. A cut used to take node + 1 while
+      // a branch took nextNode++, so a cut after a branch reached the branch's
+      // id and overwrote its log.
+      this.state.node = this.state.nextNode++;
+      this.state.depth += 1;
+      this.state.handoff = handoff;
+      this.state.events = retained;
+      // The new node's prefix has never been sent, so there is nothing to anchor
+      // to until its first response comes back.
+      this.state.anchor = null;
+      // A cut declares a handoff basis: the closed node's events do not replay,
+      // its derived state does. Relying on the default here would silently make
+      // every boundary a fork and replay the whole history.
+      await initNode(dir, this.state.node, self, this.clock.now(), "handoff");
+      // The durable successor already belongs to the target provider, even if
+      // the process exits before switchModel installs its in-memory adapter.
+      await this.saveCursor(nextModel, nextProvider, nextThinking, nextContextRef);
+    } finally { release(); }
   }
 }