@visual-z/xeno 0.1.0

package/src/runtime/loop.ts

@@ -0,0 +1,1983 @@
+/**
+ * The agent loop.
+ *
+ * Deliberately thin. Everything that decides anything -- what the model sees,
+ * when to cut a node, what the handoff says -- is a pure function in core, so
+ * this file only sequences them and performs the I/O between. That split is
+ * what makes the interesting behaviour testable without a network, and what
+ * keeps the loop cheap to throw away when the next model generation wants a
+ * different shape.
+ *
+ * One turn:
+ *
+ *   project the log -> send -> record the assistant turn -> run tools ->
+ *   record results -> decide whether to cut -> maybe cut
+ *
+ * The cut decision happens only here, between complete turns, because a node
+ * boundary between a tool_use and its result would produce an unpairable
+ * request.
+ */
+
+import type { LogEvent, AssistantBlock, NodeRef, CutReason } from "../core/events.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 { 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 { 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 { randomUUID } from "node:crypto";
+import { pendingToolCalls } from "../core/execution.ts";
+import { executionOutcome, modelOutcome, type ExecutionOutcome } from "../core/outcome.ts";
+import { ExecutionControl } from "./execution-control.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 { churnReview } from "../core/churn.ts";
+import { deadlineNotice } from "../core/deadline.ts";
+import { statusOf } from "./retry.ts";
+import { assertNever } from "../core/exhaustive.ts";
+import {
+  initNode, appendEvent, readNode, closeNode, digestNode, handoffPath, nodePath, manifestPath,
+  listNodes, readCursor, writeCursor,
+} from "../store/log.ts";
+import { replayContext } 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 {
+  scanWorkspace, diffScans, reconcile, DEFAULT_IGNORE, workspaceVersion,
+  type FileSet, type RestoreResult,
+} from "../store/workspace.ts";
+import { putBlob, getBlob, putFileBlob } from "../store/blobs.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,
+  BRANCH_TOOL_NAMES, WRITING_BRANCH_TOOL_NAMES,
+  type ToolContext, type Annotation, type ToolResult,
+} from "./tools.ts";
+import { diagnosePrefix, totalUsage, type UsageSample, type UsageTotals } from "./usage.ts";
+import { planResume } from "./resume.ts";
+import type { Phase } from "../core/queue.ts";
+
+/** Ids and timestamps come from here so the loop stays the only impure part. */
+export interface Clock {
+  now(): string;
+  nextId(): string;
+}
+
+export function systemClock(): Clock {
+  return {
+    now: () => new Date().toISOString(),
+    nextId: () => randomUUID(),
+  };
+}
+
+export interface LoopEvent {
+  kind:
+    | "turn_start"
+    | "assistant_text"
+    | "thinking"
+    | "text_delta"
+    | "thinking_delta"
+    | "discard"
+    | "tool_call"
+    | "tool_result"
+    | "usage"
+    | "cut"
+    | "stop_and_ask"
+    | "branch_start"
+    | "branch_done"
+    | "snapshot_failed"
+    | "undeclared_change"
+    | "done";
+  text?: string;
+  tool?: { name: string; input: unknown };
+  ok?: boolean;
+  usage?: UsageSample;
+  prefix?: string;
+  node?: number;
+  reason?: string;
+  /** branch_start: wall-clock milliseconds, for asserting the stagger. */
+  at?: number;
+  outcome?: ExecutionOutcome;
+}
+
+/**
+ * Ceilings on branching. Every one of them is a bound on an otherwise
+ * unbounded resource, and the defaults are conservative because the measured
+ * evidence says fan-out is usually a loss: 2.6x the tokens and about five
+ * times the cost of the sequential path, while being slower.
+ */
+export interface BranchLimits {
+  /** How deep branching may nest. 2 means the parent may branch, a branch may not. */
+  maxBranchDepth: number;
+  /** Branches one assistant turn may open. */
+  maxBranchesPerTurn: number;
+  /** Branches a whole session may open. */
+  maxBranchesPerSession: number;
+  /**
+   * Delay between starting sibling branches.
+   *
+   * Simultaneous cold spawns race the prompt cache: a sibling six seconds
+   * behind has been measured writing its full 52k prefix with zero cache
+   * read, because the first had not finished writing it.
+   */
+  branchStaggerMs: number;
+}
+
+export const DEFAULT_BRANCH_LIMITS: BranchLimits = {
+  maxBranchDepth: 2,
+  maxBranchesPerTurn: 3,
+  maxBranchesPerSession: 10,
+  branchStaggerMs: 1500,
+};
+
+export interface SessionConfig {
+  logDir: string;
+  frozen: FrozenPrefix;
+  tools: ToolContext;
+  boundary?: Partial<BoundaryConfig>;
+  /** New sessions default to windowed replay; saved sessions keep their policy. */
+  contextPolicy?: ContextPolicy;
+  /** Complete tool exchanges without new evidence; zero disables this watchdog. */
+  stallLimit?: number;
+  /** Bounded appended continuations after output truncation; saved sessions keep this policy. */
+  outputRecoveryLimit?: number;
+  counter?: TokenCounter;
+  /** Hard ceiling on turns, so a non-converging run cannot spend forever. */
+  maxTurns: number;
+  /** Experimental ablation only; normal sessions append durable working-state guidance. */
+  guidance?: boolean;
+  /**
+   * One-time reconciliation notices: an unverified finish
+   * (core/completion-review.ts) and a rut of repeated failures or edits
+   * (core/churn.ts). On unless false. Benchmark runners turn them off so their
+   * protocol matches the runs they are compared against; a runtime policy,
+   * not persisted.
+   */
+  harnessReviews?: boolean;
+  /**
+   * Wall-clock budget per request, for runs judged against a deadline
+   * (core/deadline.ts). Absent means no notice; nothing is ever stopped by it.
+   */
+  timeBudgetMs?: number;
+  /** Replies before a missing next step is reminded (core/continuation.ts); absent means the core default. */
+  continuationAfter?: number;
+  branches?: Partial<BranchLimits>;
+  /**
+   * Provider for branches. A branch legitimately runs on its own model -- a
+   * cheaper one is often right for read-only exploration -- so this is a
+   * seam rather than a hook. Defaults to the parent's provider.
+   */
+  branchProvider?: () => Provider;
+  /** Depth of this session in the branch tree. Zero for a top-level session. */
+  branchDepth?: number;
+  /** O.2: stable across segment cuts; branches get independent work identities. */
+  workNamespace?: string;
+  /** O.5: default 3 is a conservative runtime quota, not a context threshold. */
+  maxParallelTools?: number;
+  /**
+   * Where blobs go. Snapshots are off when unset, which keeps the loop
+   * usable without the store -- a read-only branch has nothing to snapshot.
+   */
+  blobDir?: string;
+  /** Directory names the scan skips, relative to the workspace root. */
+  snapshotIgnore?: readonly string[];
+}
+
+export interface SessionState {
+  node: number;
+  depth: number;
+  handoff: Handoff | null;
+  events: LogEvent[];
+  usage: UsageSample[];
+  /**
+   * The last prompt size the provider actually charged for. Boundary decisions
+   * anchor to it so only the delta since is estimated -- see core/tokens.ts.
+   */
+  anchor: Anchor | null;
+  /** Branches opened so far, against maxBranchesPerSession. */
+  branchesOpened: number;
+  /** Next free node number. Branches take one each. */
+  nextNode: number;
+  /** The workspace as of the last snapshot, for diffing the next one. */
+  lastScan: FileSet;
+  /** Worktrees created for writing branches, by node. */
+  worktrees: Map<number, { path: string; branch: string }>;
+}
+
+function selfRef(dir: string, node: number, sha: string): NodeRef {
+  return { node, log_ref: nodePath(dir, node), sha256: sha };
+}
+
+/** Digest is I/O; core stays pure and the caller supplies the bytes. */
+async function digestedRef(dir: string, node: number): Promise<NodeRef> {
+  return selfRef(dir, node, await digestNode(dir, node));
+}
+
+/**
+ * One completed exchange that changed files -- somewhere to go back to.
+ *
+ * The unit is a whole exchange, not a snapshot. A snapshot lands mid-turn,
+ * after the tool results and before the model's closing message, so forking
+ * there would cut a turn in half and drop the model's own summary of what it
+ * just did. Claude Code lists prompts for the same reason: the thing a
+ * person means by "before that" is a message they sent, not a tool call.
+ */
+export interface RestorePoint {
+  node: number;
+  /** Last event of the exchange. Inclusive: the exchange itself is kept. */
+  atEvent: string;
+  /** The prompt that opened the exchange, for a caller that has to show it. */
+  prompt: string;
+  /** How many paths the exchange added, changed or removed. */
+  changed: number;
+  /**
+   * True when this exchange is in the context the session is currently in.
+   *
+   * False means a branch the session has left -- usually one it rewound away
+   * from. Those are listed too: a node that survives on disk but cannot be
+   * found again is undestroyed and unreachable, which is the same loss in a
+   * different shape.
+   */
+  onPath: boolean;
+}
+
+export type RewindPreview =
+  | { ok: true; willWrite: string[]; willDelete: string[] }
+  | { ok: false; error: string };
+
+/**
+ * Which of the two halves move.
+ *
+ *   both     the default. Context and disk stay in agreement.
+ *   files    the workspace goes back, the conversation does not.
+ *   context  the conversation goes back, the workspace does not.
+ */
+export type RewindMode = "both" | "files" | "context";
+
+export type RewindResult =
+  | { ok: true; node: number; restored: string[]; removed: string[]; unrecoverable: string[]; note: string }
+  | { ok: false; error: string };
+
+/** O.5: child execution returns facts; only the parent coordinator accepts them. */
+type DeferredToolResult = ToolResult & { accept?: () => Promise<LoopEvent[]> };
+type ToolCall = Extract<AssistantBlock, { type: "tool_use" }>;
+
+export class Session {
+  private readonly execution = new ExecutionControl();
+  private stall: StallState | null = null;
+  private pendingAdoption: number | null = null;
+  private readonly allocatedEventIds = new Set<string>();
+  readonly config: SessionConfig;
+  /**
+   * Replaced by switchModel. Not readonly: a live session can change which
+   * adapter it talks to, and the replacement has to be the same field every
+   * send already reads.
+   */
+  provider: Provider;
+  readonly clock: Clock;
+  state: SessionState;
+  private readonly allocation: { next: number };
+
+  constructor(config: SessionConfig, provider: Provider, clock: Clock = systemClock(), allocation = { next: 1 }) {
+    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.tools.outputStore ??= join(config.logDir, "artifacts");
+    this.provider = provider;
+    this.clock = {
+      now: () => clock.now(),
+      nextId: () => {
+        let id = clock.nextId();
+        // Injected clocks may restart their sequence too. Event identity is a
+        // session invariant, independent of the clock's implementation.
+        if (this.allocatedEventIds.has(id)) id = randomUUID();
+        this.allocatedEventIds.add(id);
+        return id;
+      },
+    };
+    this.state = {
+      node: 0, depth: 1, handoff: null, events: [], usage: [],
+      anchor: null, branchesOpened: 0, lastScan: {},
+      get nextNode() { return allocation.next; },
+      set nextNode(value: number) { allocation.next = value; },
+      worktrees: new Map(),
+    };
+  }
+
+  /**
+   * Opens the session: a new one, or the one this log already holds.
+   *
+   * Resuming restores the state a running session would have had, from the
+   * same ancestry walk the projection itself uses -- so what the model sees
+   * after a restart is what it would have seen had the process never exited.
+   * That equality is the whole contract; anything less makes a resumed
+   * session quietly different from a continuous one.
+   */
+  async start(): Promise<void> {
+    this.stall = null;
+    const dir = this.config.logDir;
+    const model = this.provider.config.spec.id;
+    const existing = await listNodes(dir);
+    const recordedCursor = await readCursor(dir);
+    const cursor = recordedCursor === null ? null : await recoverCut(dir, recordedCursor);
+    const plan = planResume(cursor, model, existing.length > 0);
+
+    switch (plan.kind) {
+      case "refuse":
+        throw new Error(plan.reason);
+
+      case "fresh":
+        this.config.contextPolicy ??= DEFAULT_CONTEXT_POLICY;
+        this.config.stallLimit ??= DEFAULT_STALL_LIMIT;
+        this.config.outputRecoveryLimit ??= DEFAULT_OUTPUT_RECOVERY_LIMIT;
+        await initNode(dir, 0, null, this.clock.now());
+        for await (const event of this.snapshotTurn([], true)) {
+          if (event.kind === "snapshot_failed") throw new Error(`cannot establish workspace baseline: ${event.reason}`);
+        }
+        break;
+
+      case "resume": {
+        // Logs predating explicit policies meant segmented, regardless of today's default.
+        this.config.contextPolicy = "segmented";
+        this.config.maxParallelTools = 1;
+        this.config.stallLimit = 0;
+        this.config.outputRecoveryLimit = 0;
+        const replayed = await replayContext(dir, plan.cursor.node);
+        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 };
+          this.config.workNamespace = context.workNamespace ?? "main";
+          this.config.maxParallelTools = context.maxParallelTools ?? 1;
+          schedulingWindow([], 0, this.config.maxParallelTools);
+          stallDecision(emptyStallState(), context.stallLimit ?? 0);
+          this.config.stallLimit = context.stallLimit ?? 0;
+          validateOutputRecoveryLimit(context.outputRecoveryLimit ?? 0);
+          this.config.outputRecoveryLimit = context.outputRecoveryLimit ?? 0;
+          this.config.frozen = context.frozen;
+          this.config.tools.gates = context.gates;
+          if (context.boundary !== undefined) this.config.boundary = context.boundary;
+          else delete this.config.boundary;
+          if (context.contextPolicy !== undefined) {
+            if (!isContextPolicy(context.contextPolicy)) throw new Error("unknown saved context policy");
+            this.config.contextPolicy = context.contextPolicy;
+          } else this.config.contextPolicy = "segmented";
+          if (context.guidance !== undefined) this.config.guidance = context.guidance;
+          else delete this.config.guidance;
+          if (context.snapshotIgnore !== undefined) this.config.snapshotIgnore = context.snapshotIgnore;
+          else delete this.config.snapshotIgnore;
+        }
+        if (plan.cursor.workspace !== undefined) this.config.tools.root = plan.cursor.workspace;
+        for (const id of existing) {
+          for (const event of (await readNode(dir, id)).events) {
+            this.allocatedEventIds.add(event.id);
+            if (event.t === "spawn") {
+              this.state.branchesOpened++;
+              if (event.workspace) this.state.worktrees.set(event.branch.node, event.workspace);
+            }
+            if (event.t === "discard") this.state.worktrees.delete(event.branch.node);
+          }
+        }
+
+        this.state.node = plan.cursor.node;
+        // From the allocator's recorded state, never from a node count: dead
+        // limbs and resolved branches hold ids, and recomputing this is the
+        // shape of the bug that once had a cut overwrite a branch's log.
+        // A crashed branch can reserve a node before the parent updates its
+        // allocator. Recovery only raises the recorded high-water mark.
+        this.state.nextNode = Math.max(plan.cursor.next_node, ...existing.map((n) => n + 1));
+        this.state.depth = replayed.depth;
+        this.state.events = replayed.contextEvents;
+        this.state.handoff = replayed.handoff;
+        await this.answerUnpairedTools("interrupted: tool outcome is unknown after restart; inspect the workspace or external operation before retrying");
+        // Nothing has been sent this process, so there is no billed prompt
+        // size to anchor to yet; the first response re-establishes it.
+        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) {
+          const files = await planRestoreToNode(dir, this.state.node);
+          if (!files.ok) throw new Error(files.error);
+          this.state.lastScan = files.files;
+          for await (const event of this.snapshotTurn([], false, "idle")) {
+            if (event.kind === "snapshot_failed") throw new Error(event.reason);
+          }
+        }
+        const pending = (await readNode(dir, plan.cursor.node)).events.findLast((e) => e.t === "adopt" && !e.applied);
+        if (pending?.t === "adopt") {
+          this.pendingAdoption = pending.branch.node;
+          await this.adoptPendingBranch();
+        }
+        break;
+      }
+
+      default:
+        return assertNever(plan, "Session.start");
+    }
+
+    await this.saveCursor();
+  }
+
+  /**
+   * Copies this session's current path into `destLogDir`, optionally
+   * stopping at `untilEvent` (inclusive). The source files are only read:
+   * a fork that rewrote the original would leave the user with one line
+   * when they thought they had two.
+   */
+  async fork(destLogDir: string, untilEvent?: string): Promise<void> {
+    await copyAncestryTo(this.config.logDir, destLogDir, this.clock.now(), untilEvent);
+  }
+
+  /**
+   * Cuts the current node, then runs on a different provider.
+   *
+   * The cut is the whole point. Thinking blocks belong to the model that
+   * produced them, and every provider this harness talks to requires them
+   * replayed unchanged. Handing Anthropic's signed block to DeepSeek -- or
+   * even to another Anthropic model -- is a bad request. Filtering the
+   * blocks out of the projection would make what the model sees depend on
+   * a "we switched" flag that is not in the log. Cutting makes the switch
+   * a fact in the log: the new node starts from a handoff, which is plain
+   * YAML, and inherits none of the old blocks.
+   *
+   * Bypasses minNodeWorkTokens. That floor is a cost argument (a handoff
+   * only pays for itself once the node's own history exceeds it). A switch
+   * is a correctness argument, and must be allowed after two turns.
+   *
+   * Only legal between turns. A cut between tool_use and tool_result would
+   * leave the log unpairable (D5).
+   *
+   * Recorded as model_checkpoint, not trigger. "trigger" means this node
+   * reached the token threshold. A switch is not that -- it can happen on
+   * turn two -- and a later reader reconstructing the session from the log
+   * must see that a person changed models, not that the node filled up.
+   * boundary.ts already produces this reason when checkpointRequested is
+   * set; switchModel is the other caller that wants it.
+   */
+  async switchModel(next: Provider): Promise<void> {
+    if (this.isHalfRound()) {
+      throw new Error(
+        "cannot switch models mid-turn: a tool_use is still unpaired. " +
+          "Wait for the turn to finish so every call has a result",
+      );
+    }
+
+    await this.performCut("model_checkpoint", next.config.spec.id);
+    this.provider = next;
+    await this.saveCursor();
+  }
+
+  /**
+   * The same pairing check switchModel already used. A user message
+   * between tool_use and tool_result is the same unpairable request a
+   * model switch would produce — so the queue reuses this, it does not
+   * invent a second half-round test.
+   */
+  private isHalfRound(): boolean {
+    const projected = projectContext({
+      frozen: this.config.frozen,
+      handoff: this.state.handoff,
+      events: this.state.events,
+    });
+    return projected.violations.some((v) => v.code === "UNPAIRED_TOOL_USE");
+  }
+
+  /**
+   * Offers after_tools only when the log is pairable. The UI still owns
+   * the queue; we just ask. A half-round returns null even if the UI
+   * offered a line — writing it would be the pairing bug this guards.
+   */
+  private async pullSteering(
+    pull?: (phase: Phase) => Promise<string | null>,
+  ): Promise<string | null> {
+    if (pull === undefined || this.isHalfRound()) return null;
+    const text = await pull("after_tools");
+    if (text === null || text.length === 0) return null;
+    return text;
+  }
+
+  /**
+   * Records where the session is, after every move.
+   *
+   * Written at each move rather than at exit, because the failures worth
+   * resuming from -- a crash, a kill, a closed laptop -- do not run exit
+   * handlers.
+   */
+  private async saveCursor(): Promise<void> {
+    // Branches share storage but never own the parent's active cursor.
+    if ((this.config.branchDepth ?? 0) > 0) return;
+    const contextRef = await putBlob(join(this.config.logDir, "artifacts"), JSON.stringify({
+      frozen: this.config.frozen, gates: this.config.tools.gates,
+      workNamespace: this.config.workNamespace ?? "main",
+      maxParallelTools: this.config.maxParallelTools ?? 3,
+      ...(this.config.boundary ? { boundary: this.config.boundary } : {}),
+      contextPolicy: this.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY,
+      stallLimit: this.config.stallLimit ?? DEFAULT_STALL_LIMIT,
+      outputRecoveryLimit: this.config.outputRecoveryLimit ?? DEFAULT_OUTPUT_RECOVERY_LIMIT,
+      ...(this.config.guidance === undefined ? {} : { guidance: this.config.guidance }),
+      ...(this.config.snapshotIgnore ? { snapshotIgnore: this.config.snapshotIgnore } : {}),
+    }));
+    await writeCursor(this.config.logDir, {
+      node: this.state.node,
+      next_node: this.state.nextNode,
+      model: this.provider.config.spec.id,
+      updated_at: this.clock.now(),
+      workspace: this.config.tools.root,
+      context_ref: contextRef,
+    });
+  }
+
+  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 }]);
+  }
+
+  get totals(): UsageTotals {
+    return totalUsage(this.state.usage);
+  }
+
+  cancel(): void { this.execution.cancel(); }
+  whenIdle(): Promise<void> { return this.execution.whenIdle(); }
+  get running(): boolean { return this.execution.running; }
+
+  /**
+   * Runs one user message to completion: model turns and tool calls until the
+   * model stops asking for tools.
+   *
+   * `signal` is per-send, matching Provider.send. Abort is a decision, not a
+   * failure: the generator yields `done` with reason `interrupted` and
+   * returns. Any tool_use already on disk is answered with a tool_result
+   * that says so -- otherwise the next request is unpairable (D8: the log
+   * is append-only, so the alternative of deleting the tool_use is not
+   * available, and would also lie about a call that may have had effects).
+   */
+  async *send(
+    userText: string,
+    signal?: AbortSignal,
+    pull?: (phase: Phase) => Promise<string | null>,
+  ): AsyncGenerator<LoopEvent> {
+    const owned = this.execution.begin(signal);
+    const events = this.run(userText, owned.signal, pull);
+    let terminal = false;
+    let exhausted = false;
+    try {
+      for (;;) {
+        const item = await events.next();
+        if (item.done) { exhausted = true; break; }
+        if (item.value.kind === "done") terminal = true;
+        yield item.value;
+      }
+      if (!terminal) yield { kind: "done", reason: "stopped: workspace snapshot failed", outcome: executionOutcome("snapshot_failed") };
+    } finally {
+      // Closing a consumer is not a user cancellation. Preserve the existing
+      // crash/recovery points; only an explicit signal can claim cancellation.
+      try {
+        if (!exhausted) {
+          await events.return(undefined);
+        }
+      } finally { owned.finish(); }
+    }
+  }
+
+  private async *run(
+    userText: string,
+    signal?: AbortSignal,
+    pull?: (phase: Phase) => Promise<string | null>,
+  ): AsyncGenerator<LoopEvent> {
+    await this.record({
+      t: "user", id: this.clock.nextId(), at: this.clock.now(), text: userText,
+    });
+    // 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([])) {
+      yield event;
+      if (event.kind === "snapshot_failed") return;
+    }
+
+    const counter = this.config.counter ?? estimateTokens;
+    const completedThisTurn: string[] = [];
+
+    try {
+      let overflowRetried = false;
+      const requestStarted = this.clock.now();
+      for (let turn = 0; turn < this.config.maxTurns; turn++) {
+        completedThisTurn.length = 0;
+        if (signal?.aborted) {
+          yield* this.closeInterrupted(completedThisTurn);
+          return;
+        }
+
+        if (yield* this.checkStall()) {
+          yield { kind: "done", reason: "stopped: consecutive tool exchanges without new evidence", outcome: executionOutcome("stalled") };
+          return;
+        }
+        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,
+            tools: names, remainingRequests: this.config.maxTurns - turn,
+            ...(this.config.continuationAfter === undefined ? {} : { minAssistantTurns: this.config.continuationAfter }) }) ??
+            (this.config.timeBudgetMs === undefined ? null
+              : deadlineNotice(requestStarted, this.clock.now(), this.config.timeBudgetMs, this.state.events)) ??
+            (this.config.harnessReviews === false ? null : churnReview(this.state.events));
+          if (guidance) await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), ...guidance });
+        }
+
+        // New user/steering input and guidance can overflow a previously safe view.
+        if ((this.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY) === "windowed" &&
+            (yield* this.maybeWindowCut(counter, true))) {
+          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)),
+          },
+        });
+
+        // Pairing violations are a 400 waiting to happen; surface them here,
+        // where the cause is still visible, rather than as a request failure.
+        if (projected.violations.length > 0) {
+          yield {
+            kind: "done",
+            reason: `projection violations: ${projected.violations.map((v) => v.code).join(", ")}`,
+            outcome: executionOutcome("projection_invalid"),
+          };
+          return;
+        }
+
+        const window = this.provider.config.spec.contextWindow;
+        const estimated = anchoredCount(projected.messages, projected.system, this.state.anchor,
+          counter, this.config.frozen.tools).tokens;
+        if (window !== undefined && estimated + this.provider.config.maxTokens > window) {
+          yield { kind: "done", reason: `context budget exceeded: estimated input ${estimated} + output reserve ${this.provider.config.maxTokens} > window ${window}; shorten the input or switch to a larger verified window`, outcome: executionOutcome("context_budget") };
+          return;
+        }
+
+        let result: Turn;
+        try {
+          result = yield* this.awaitProvider(projected.messages, signal);
+        } catch (error) {
+          if (signal?.aborted) {
+            yield* this.closeInterrupted(completedThisTurn);
+            return;
+          }
+          if (!(error instanceof Error) || !isContextOverflow(error.message, statusOf(error))) throw error;
+          // The estimate said this fit and the provider says it does not: the
+          // estimate is wrong for this content. The only projection that can
+          // 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) {
+            yield { kind: "done", reason: `stopped: provider rejected the prompt as too long (${error.message})`, outcome: executionOutcome("context_budget") };
+            return;
+          }
+          overflowRetried = true;
+          if (yield* this.maybeWindowCut(counter, true, true)) {
+            yield { kind: "done", reason: "stopped: context cannot fit the model window", outcome: executionOutcome("context_budget") };
+            return;
+          }
+          continue;
+        }
+        overflowRetried = false;
+
+        const previous = this.state.usage.at(-1);
+        this.state.usage.push(result.usage);
+        const promptTokens =
+          result.usage.input_tokens +
+          result.usage.cache_creation_input_tokens +
+          result.usage.cache_read_input_tokens;
+        // A stream that reported no usage at all maps onto zeros in the
+        // adapter. Anchoring to that fabrication would make shouldCut compare
+        // against a fake small number and never fire. Leave the previous
+        // anchor (null before the first measurement); anchoredCount already
+        // falls back to a plain estimate when anchor is null. Do not invent
+        // a substitute count — diagnosePrefix and /usage must not see a
+        // fabricated prompt size.
+        if (promptTokens > 0 || result.usage.output_tokens > 0) {
+          this.state.anchor = {
+            promptTokens,
+            outputTokens: result.usage.output_tokens,
+            messageCount: projected.messages.length,
+          };
+        }
+        const cache = this.provider.config.spec.cache;
+        if (cache === undefined) {
+          yield {
+            kind: "usage",
+            usage: result.usage,
+            prefix: "cache terms unknown",
+            ok: true,
+          };
+        } else {
+          const verdict = diagnosePrefix(result.usage, previous, cache);
+          yield {
+            kind: "usage",
+            usage: result.usage,
+            prefix: verdict.kind === "healthy"
+              ? `cache read ${verdict.read}, wrote ${verdict.wrote}`
+              : verdict.detail,
+            ok: verdict.kind !== "suspicious",
+          };
+        }
+
+        await this.record({
+          t: "assistant", id: this.clock.nextId(), at: this.clock.now(), blocks: result.blocks, stop_reason: result.stopReason,
+        });
+
+        for (const b of result.blocks) {
+          if (b.type === "text" && b.text.trim()) yield { kind: "assistant_text", text: b.text };
+          if (b.type === "thinking" && b.text.trim()) yield { kind: "thinking", text: b.text };
+        }
+
+        const calls = result.blocks.filter(
+          (b): b is Extract<AssistantBlock, { type: "tool_use" }> => b.type === "tool_use",
+        );
+
+        // N.12: syntactically valid arguments in an unfinished response are not
+        // authorization to execute a partial batch. Pair without side effects.
+        if (!isCompleteResponse(result.stopReason)) {
+          for (const item of await this.answerUnpairedTools(incompleteToolText(result.stopReason))) {
+            yield { kind: "tool_result", text: item.content, ok: false };
+          }
+          const extra = await this.pullSteering(pull);
+          if (extra !== null) {
+            await this.record({ t: "user", id: this.clock.nextId(), at: this.clock.now(), text: extra });
+            continue;
+          }
+          const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+          if (!history.ok) throw new Error(history.error);
+          const notice = outputRecoveryNotice(history.nodes.flatMap(node => node.events),
+            this.config.outputRecoveryLimit ?? DEFAULT_OUTPUT_RECOVERY_LIMIT, this.config.maxTurns - turn - 1);
+          if (notice) {
+            await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), ...notice });
+            if (yield* this.maybeCut(counter, true)) {
+              yield { kind: "done", reason: "stopped: no verifiable progress", outcome: executionOutcome("no_progress") };
+              return;
+            }
+            continue;
+          }
+          yield { kind: "done", reason: result.stopReason ?? "unknown model stop", outcome: modelOutcome(result.stopReason) };
+          return;
+        }
+
+        if (calls.length === 0) {
+          const extra = await this.pullSteering(pull);
+          if (extra !== null) {
+            await this.record({
+              t: "user", id: this.clock.nextId(), at: this.clock.now(), text: extra,
+            });
+            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 (yield* this.maybeCut(counter, true)) {
+              yield { kind: "done", reason: "stopped: no verifiable progress", outcome: executionOutcome("no_progress") };
+              return;
+            }
+            continue;
+          }
+          const stopped = yield* this.maybeCut(counter, false);
+          yield {
+            kind: "done",
+            reason: stopped ? "stopped: no verifiable progress" : result.stopReason ?? "end_turn",
+            outcome: stopped ? executionOutcome("no_progress") : modelOutcome(result.stopReason),
+          };
+          return;
+        }
+
+        let branchesThisTurn = 0;
+        type Settled = { ok: true; value: DeferredToolResult } | { 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++) {
+          const call = calls[callIndex]!;
+          if (signal?.aborted && !pending.has(call.call_id)) {
+            yield* this.closeInterrupted(completedThisTurn);
+            return;
+          }
+
+          if (!pending.has(call.call_id)) {
+            const end = schedulingWindow(modes, callIndex, this.config.maxParallelTools ?? 3);
+            if (end - callIndex > 1) for (let index = callIndex; index < end; index++) {
+              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 })));
+            }
+          }
+
+          let out: DeferredToolResult;
+          let annotation: LogEvent | undefined;
+          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;
+          } 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, ...(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 {
+              out = await runTool(toolContext, call.name, call.input);
+            }
+          }
+          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.
+          yield { kind: "tool_result", text: out.content, ok: out.ok, outcome: out.outcome! };
+
+          // 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.effect ? { effect: out.effect } : {}),
+          });
+          completedThisTurn.push(call.call_id);
+          if (signal?.aborted && pending.size === 0) {
+            yield* this.closeInterrupted(completedThisTurn);
+            return;
+          }
+        } } finally { await Promise.allSettled(pending.values()); }
+
+        // One scan per turn, not per tool call: a turn is the smallest unit
+        // 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));
+        if (this.pendingAdoption !== null) await this.adoptPendingBranch();
+
+        // Between complete exchanges is the only safe place to cut.
+        if (yield* this.maybeCut(counter, turn + 1 < this.config.maxTurns)) {
+          yield { kind: "done", reason: "stopped: no verifiable progress", outcome: executionOutcome("no_progress") };
+          return;
+        }
+
+        const extra = await this.pullSteering(pull);
+        if (extra !== null) {
+          await this.record({
+            t: "user", id: this.clock.nextId(), at: this.clock.now(), text: extra,
+          });
+        }
+      }
+
+      yield { kind: "done", reason: `hit maxTurns (${this.config.maxTurns})`, outcome: executionOutcome("max_turns") };
+    } finally {
+      // If the consumer aborts and stops pulling, the generator is closed
+      // without running the yield* closeInterrupted path. Pairing still
+      // has to happen: an unanswered tool_use on disk is a 400 next turn.
+      if (signal?.aborted) await this.answerUnpairedTools();
+    }
+  }
+
+  /**
+   * Answers every tool_use that has no tool_result yet.
+   *
+   * Append, never delete: the call was issued, and rolling it back would
+   * rewrite the log (D8) and hide a call that may already have touched
+   * disk. Same shape as a refused branch -- a result that says why.
+   */
+  private async answerUnpairedTools(
+    content = "interrupted: the user cancelled before this tool completed",
+  ): Promise<{ callId: string; content: string }[]> {
+    const added: { callId: string; content: string }[] = [];
+    for (const block of pendingToolCalls(this.state.events)) {
+        const resultText = knownUnexecutedTool(this.state.events, block.call_id) ?? content;
+        await this.record({
+          t: "tool_result",
+          id: this.clock.nextId(),
+          at: this.clock.now(),
+          call_id: block.call_id,
+          ok: false,
+          content: resultText,
+          outcome: executionOutcome("unknown"),
+        });
+        added.push({ callId: block.call_id, content: resultText });
+    }
+    return added;
+  }
+
+  private async *closeInterrupted(completedCallIds: readonly string[]): AsyncGenerator<LoopEvent> {
+    const added = await this.answerUnpairedTools();
+    for (const item of added) {
+      yield { kind: "tool_result", text: item.content, ok: false };
+    }
+    if (completedCallIds.length > 0) {
+      yield* this.snapshotTurn(completedCallIds);
+    }
+    await this.recordInterrupt();
+    yield { kind: "done", reason: "interrupted", outcome: executionOutcome("cancelled") };
+  }
+
+  /**
+   * Appends an interrupt event for the user turn this send opened.
+   *
+   * The cancel happened after that user event, so it is a later record --
+   * not a flag written back onto it (D8). Partial assistant text is omitted:
+   * a cancelled generation was never delivered (AGENT_PLAYBOOK: a failed
+   * request is not a conversation that happened).
+   */
+  private async recordInterrupt(): Promise<void> {
+    for (let i = this.state.events.length - 1; i >= 0; i--) {
+      const event = this.state.events[i]!;
+      if (event.t !== "user") continue;
+      await this.record({
+        t: "interrupt",
+        id: this.clock.nextId(),
+        at: this.clock.now(),
+        user_id: event.id,
+      });
+      return;
+    }
+  }
+
+  /**
+   * Runs the provider and yields display deltas as they arrive, so a long
+   * reply is visible before `send` resolves. The returned Turn is still the
+   * complete message -- that is what gets logged.
+   */
+  private async *awaitProvider(
+    messages: readonly Message[],
+    signal?: AbortSignal,
+  ): AsyncGenerator<LoopEvent, Turn> {
+    const queue: LoopEvent[] = [];
+    let notify: (() => void) | null = null;
+    const box: { settled: { ok: true; turn: Turn } | { ok: false; error: unknown } | null } = {
+      settled: null,
+    };
+
+    const onDelta = (delta: StreamDelta): void => {
+      switch (delta.kind) {
+        case "text":
+          queue.push({ kind: "text_delta", text: delta.text });
+          break;
+        case "thinking":
+          queue.push({ kind: "thinking_delta", text: delta.text });
+          break;
+        case "discard":
+          queue.push({ kind: "discard" });
+          break;
+        default:
+          return assertNever(delta, "onDelta");
+      }
+      notify?.();
+    };
+
+    const pending = this.provider
+      .send(this.config.frozen, messages, this.state.node, signal, onDelta)
+      .then(
+        (turn) => {
+          box.settled = { ok: true, turn };
+          notify?.();
+        },
+        (error: unknown) => {
+          box.settled = { ok: false, error };
+          notify?.();
+        },
+      );
+
+    while (box.settled === null || queue.length > 0) {
+      if (queue.length > 0) {
+        yield queue.shift()!;
+        continue;
+      }
+      await new Promise<void>((resolve) => {
+        if (box.settled !== null || queue.length > 0) {
+          resolve();
+          return;
+        }
+        notify = resolve;
+      });
+      notify = null;
+    }
+
+    await pending;
+    const end = box.settled;
+    if (end === null) throw new Error("provider send settled without a result");
+    if (!end.ok) throw end.error;
+    return end.turn;
+  }
+
+  /**
+   * Yields any boundary events and returns true when the session should stop.
+   *
+   * Returning the verdict rather than only announcing it is the point: an
+   * advisory the loop ignores looks like a guard while the budget drains.
+   */
+  /**
+   * Records what the workspace actually did this turn.
+   *
+   * Content goes to the blob store so a later restore has something to
+   * restore from; the event holds only digests, which is what keeps it a
+   * delta rather than a copy of the workspace.
+   */
+  private async *snapshotTurn(callIds: readonly string[], baseline = false, phase: "turn" | "idle" = "turn"): AsyncGenerator<LoopEvent> {
+    const blobDir = this.config.blobDir;
+    if (!blobDir) return;
+
+    const scan = await scanWorkspace(
+      this.config.tools.root,
+      this.config.snapshotIgnore ?? DEFAULT_IGNORE,
+    );
+    if (!scan.ok) {
+      // Reported rather than skipped: without a scan a restore would delete
+      // files it never recorded, so the caller has to know it is blind.
+      yield { kind: "snapshot_failed", reason: scan.error };
+      return;
+    }
+
+    const delta = diffScans(this.state.lastScan, scan.files);
+    const nothingHappened =
+      Object.keys(delta.added).length === 0 &&
+      Object.keys(delta.changed).length === 0 &&
+      delta.removed.length === 0;
+    if (nothingHappened) return;
+
+    // Only this turn's effects: reconciling against the whole node would
+    // report every earlier edit as declared-but-unchanged.
+    const answered = new Set(callIds);
+    const effects = this.state.events
+      .filter((e) => e.t === "tool_result" && answered.has(e.call_id) && e.effect)
+      .map((e) => (e as Extract<LogEvent, { t: "tool_result" }>).effect!);
+    const rec = reconcile(effects, delta);
+
+    for (const [path, sha] of Object.entries({ ...delta.added, ...delta.changed })) {
+      const stored = await putFileBlob(blobDir, join(this.config.tools.root, path));
+      if (stored !== sha) {
+        // The file changed between the scan and the read. Recording the
+        // digest that was actually stored keeps the event honest.
+        if (path in delta.added) delta.added[path] = stored;
+        else delta.changed[path] = stored;
+        scan.files[path] = stored;
+      }
+    }
+
+    await this.record({
+      t: "snapshot",
+      id: this.clock.nextId(),
+      at: this.clock.now(),
+      added: delta.added,
+      changed: delta.changed,
+      removed: delta.removed,
+      undeclared: baseline ? [] : rec.undeclared,
+      declared_but_unchanged: rec.declaredButUnchanged,
+      workspace_sha256: workspaceVersion(scan.files),
+      phase,
+    });
+    this.state.lastScan = scan.files;
+
+    if (!baseline && rec.undeclared.length > 0) {
+      yield {
+        kind: "undeclared_change",
+        reason: `changed with no tool claiming it: ${rec.undeclared.join(", ")}`,
+      };
+    }
+  }
+
+  private get limits(): BranchLimits {
+    return { ...DEFAULT_BRANCH_LIMITS, ...this.config.branches };
+  }
+
+  private nodeRefFor(node: number): Promise<NodeRef> {
+    return digestedRef(this.config.logDir, node);
+  }
+
+  /**
+   * Runs a read-only branch in its own node and returns a summary.
+   *
+   * The branch is an ordinary Session with a different node, a reduced tool
+   * set and no handoff -- the recursion is what keeps a branch and a session
+   * the same thing, so nothing here has to reimplement the loop.
+   */
+  private executionMode(call: ToolCall): "parallel" | "exclusive" {
+    if (call.name === "branch" && typeof call.input === "object" && call.input !== null &&
+        (call.input as Record<string, unknown>)["writes"] !== true) return "parallel";
+    return toolDefinition(call.name)?.execution ?? "exclusive";
+  }
+
+  private async *prepareConcurrentCall(call: ToolCall, branchIndex: number, signal?: AbortSignal): AsyncGenerator<LoopEvent, () => Promise<DeferredToolResult>> {
+    const ctx = { ...this.config.tools, ...(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 *runBranch(
+    input: unknown,
+    indexThisTurn: number,
+    signal?: AbortSignal,
+  ): AsyncGenerator<LoopEvent, DeferredToolResult> {
+    const limits = this.limits;
+    const depth = this.config.branchDepth ?? 0;
+
+    // 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.
+    if (depth + 1 >= limits.maxBranchDepth) {
+      return {
+        content:
+          `refused: branch depth limit (${limits.maxBranchDepth}) reached. ` +
+          "Do this work directly with your own tools.",
+        ok: false,
+      };
+    }
+    if (indexThisTurn >= limits.maxBranchesPerTurn) {
+      return {
+        content:
+          `refused: at most ${limits.maxBranchesPerTurn} branches per turn. ` +
+          "Run the rest in a later turn, or do them yourself -- branching is " +
+          "usually more expensive than working sequentially.",
+        ok: false,
+      };
+    }
+    if (this.state.branchesOpened >= limits.maxBranchesPerSession) {
+      return {
+        content:
+          `refused: this session has opened its ${limits.maxBranchesPerSession} branches. ` +
+          "Continue directly.",
+        ok: false,
+      };
+    }
+
+    const args = (typeof input === "object" && input !== null ? input : {}) as Record<string, unknown>;
+    const purpose = String(args["purpose"] ?? "").trim();
+    const prompt = String(args["prompt"] ?? "").trim();
+    const writes = args["writes"] === true;
+    if (!purpose || !prompt) {
+      return { content: "a branch needs both a purpose and a prompt", ok: false };
+    }
+    const parentAllow = 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];
+    const sourceEvent = this.state.events.findLast(event => event.t === "assistant")?.id ?? this.state.events.at(-1)!.id;
+    let inputWorkspace: { kind: "shared_readonly" } | { kind: "git_tree"; head: string; tree: string } = { kind: "shared_readonly" };
+
+    // Siblings are staggered so the second does not race the first for the
+    // prompt cache and rewrite the whole prefix.
+    if (indexThisTurn > 0 && limits.branchStaggerMs > 0) {
+      await new Promise((r) => setTimeout(r, limits.branchStaggerMs));
+    }
+
+    const node = this.state.nextNode++;
+    this.state.branchesOpened += 1;
+    const ref = await this.nodeRefFor(node);
+    // A fork point must include any preceding tool effects in this batch.
+    yield* this.snapshotTurn([]);
+
+    // A writing branch needs its own checkout, or parallel branches overwrite
+    // each other's files with nothing to show isolation was never in place.
+    // Refused rather than downgraded to read-only: the model asked to change
+    // files, and quietly not letting it would look like the work was done.
+    let worktree: { path: string; branch: string } | null = null;
+    if (writes) {
+      const created = await createWorktree(this.config.tools.root, `b${node}`);
+      if (!created.ok) {
+        this.state.branchesOpened -= 1;
+        this.state.nextNode -= 1;
+        return { content: `refused: ${created.error}`, ok: false };
+      }
+      worktree = { path: created.path, branch: created.branch };
+      inputWorkspace = { kind: "git_tree", ...created.snapshot };
+      this.state.worktrees.set(node, worktree);
+    }
+
+    await this.record({
+      t: "spawn", id: this.clock.nextId(), at: this.clock.now(), branch: ref, purpose,
+      input: { source_event: sourceEvent, tools: allowed, max_turns: Math.min(this.config.maxTurns, 15), workspace: inputWorkspace },
+      ...(worktree ? { workspace: worktree } : {}),
+    });
+
+    // basis "none": the branch starts fresh. The parent pointer is provenance.
+    await initNode(this.config.logDir, node, {
+      ...await this.nodeRefFor(this.state.node), at_event: this.state.events.at(-1)!.id,
+    }, this.clock.now(), "none");
+
+    const branch = new Session(
+      {
+        ...this.config,
+        frozen: { system: this.config.frozen.system, tools: branchTools(writes).filter((t) => allowed.includes(t.name)) },
+        // 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.
+        tools: {
+          ...this.config.tools,
+          ...(worktree ? { root: worktree.path } : {}),
+          allow: allowed,
+        },
+        branchDepth: depth + 1,
+        workNamespace: `branch-${node}`,
+        maxTurns: Math.min(this.config.maxTurns, 15),
+      },
+      this.config.branchProvider ? this.config.branchProvider() : this.provider,
+      this.clock,
+      this.allocation,
+    );
+    branch.state.node = node;
+    branch.state.nextNode = this.state.nextNode;
+    branch.state.lastScan = { ...this.state.lastScan };
+    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 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");
+      }
+    } catch {
+      // 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");
+    }
+    // Node numbers the branch allocated are taken.
+
+    const tip = branch.state.node;
+    const branchContext = await replayContext(this.config.logDir, tip);
+    // Re-digest now: `ref` was taken at spawn, before this node had events.
+    const handoff = deriveHandoff({
+      prev: branchContext.fullHandoff, depth: branchContext.depth, events: branchContext.events, self: await this.nodeRefFor(tip),
+      config: { maxUserTurns: Infinity, maxUserTurnBytes: Infinity },
+    });
+    await closeNode(this.config.logDir, tip, boundHandoff(handoff), (await readNode(this.config.logDir, tip)).events.length, this.clock.now());
+
+    // The worktree stays until the branch is resolved: its uncommitted work
+    // is the branch's result, and removing it here would discard exactly
+    // what the parent is about to decide on.
+    const where = worktree
+      ? `\n\nIts changes are in ${worktree.path} on branch ${worktree.branch}, ` +
+        "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 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,
+    };
+
+    // 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` +
+        `Its full state is at ${handoffPath(this.config.logDir, tip)}. ` +
+        `Resolve it with resolve(node: ${node}, ...).`,
+      ok: outcome.status === "completed",
+      outcome,
+      accept: async () => {
+        this.state.usage.push(...branch.state.usage);
+        await this.saveCursor();
+        await this.record(joined);
+        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,
+        input: { source_event: sourceEvent, workspace: inputWorkspace } },
+    };
+  }
+
+  private async runResolve(input: unknown): Promise<ToolResult> {
+    const args = (typeof input === "object" && input !== null ? input : {}) as Record<string, unknown>;
+    const node = Number(args["node"]);
+    const resolution = String(args["resolution"] ?? "");
+    const why = typeof args["why"] === "string" ? args["why"].trim() : "";
+
+    if (!Number.isInteger(node)) return { content: "resolve needs a node number", ok: false };
+    const history = await readNodeHistory(this.config.logDir, this.state.node);
+    if (!history.ok) return { ok: false, content: history.error };
+    const events = history.nodes.flatMap((n) => n.events);
+    const spawned = events.some(
+      (e) => (e.t === "spawn" || e.t === "joined") && e.branch.node === node,
+    );
+    if (!spawned) {
+      return { content: `no branch ${node} was opened from this node`, ok: false };
+    }
+    if (events.some((e) => (e.t === "adopt" || e.t === "discard") && e.branch.node === node)) {
+      return { ok: false, content: `branch ${node} is already resolved` };
+    }
+
+    const ref = await this.nodeRefFor(node);
+    if (resolution === "adopt") {
+      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;
+      return { content: `adopted branch ${node}; continuation moves after this tool round is paired`, ok: true };
+    }
+    if (resolution === "discard") {
+      await this.record({
+        t: "discard", id: this.clock.nextId(), at: this.clock.now(),
+        branch: ref, reason: why || "no reason given",
+      });
+      // Discarding is the decision that its worktree can go. A dirty one is
+      // reported rather than forced: those changes are what was discarded,
+      // and silently deleting them is the destructive-restore mistake again.
+      const wt = this.state.worktrees.get(node);
+      if (wt) {
+        const removed = await removeWorktree(this.config.tools.root, wt.path, wt.branch);
+        this.state.worktrees.delete(node);
+        if (!removed.ok) {
+          return {
+            content:
+              `discarded branch ${node}, but its checkout is still at ${wt.path}: ${removed.error}`,
+            ok: true,
+          };
+        }
+      }
+      return { content: `discarded branch ${node}`, ok: true };
+    }
+    return { content: `resolution must be "adopt" or "discard"`, ok: false };
+  }
+
+  /** 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");
+  }
+
+  private toEvent(a: Annotation): LogEvent {
+    const stamp = { id: this.clock.nextId(), at: this.clock.now() };
+    switch (a.t) {
+      case "claim": {
+        // A citation naming a configured gate is recorded as a gate query, so
+        // it still resolves when the same suite is invoked differently later.
+        // Everything else stays an exact-command query.
+        const gate = a.proof ? matchGate(this.config.tools, a.proof) : undefined;
+        return {
+          t: "claim", ...stamp, what: a.what, ...(a.work_id ? { work_id: a.work_id } : {}),
+          evidence: gate !== undefined ? { gate } : a.evidence,
+        };
+      }
+      case "next_action":
+        return { t: "next_action", ...stamp, what: a.what, next_action: a.next_action, ...(a.work_id ? { work_id: a.work_id } : {}) };
+      case "decision":
+        return {
+          t: "decision", ...stamp, chose: a.chose, because: a.because,
+          ...(a.rejected ? { rejected: a.rejected } : {}),
+        };
+      case "pitfall":
+        return { t: "pitfall", ...stamp, tried: a.tried, failed_because: a.failed_because };
+      case "blocked":
+        return { t: "blocked", ...stamp, what: a.what, reason: a.reason, ...(a.work_id ? { work_id: a.work_id } : {}) };
+      case "work_status":
+      case "evidence_link":
+        return { ...a, ...stamp };
+      case "question":
+        return { t: "question", ...stamp, text: a.text };
+      default:
+        return assertNever(a, "toEvent");
+    }
+  }
+
+  // ---- rewind ---------------------------------------------------------------
+
+  private get ignore(): readonly string[] {
+    return this.config.snapshotIgnore ?? DEFAULT_IGNORE;
+  }
+
+  /**
+   * Every completed exchange on the current ancestry that changed a file.
+   *
+   * 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
+   * the files are as the exchange left them.
+   *
+   * EVERY exchange, including ones that changed no file. Going back to
+   * before a badly phrased instruction is the main use of a context-only
+   * rewind, and such a turn often only talked -- filtering on "this exchange
+   * wrote something" removes exactly those points. Claude Code lists every
+   * prompt for the same reason and hides only the code options; whether
+   * files would move is a question the preview answers, since what matters
+   * is changes AFTER the point, not changes in it.
+   */
+  async restorePoints(): Promise<RestorePoint[]> {
+    const dir = this.config.logDir;
+    const history = await readNodeHistory(dir, this.state.node);
+    if (!history.ok) return [];
+    // Per EVENT, not per node. A rewind usually forks inside the node it is
+    // sitting in, so that node is on the path and the abandoned exchange is
+    // in the same file, just past the fork point. Marking whole nodes would
+    // hide exactly the exchange most worth getting back to.
+    const onPath = new Set(history.nodes.flatMap((n) => n.events.map((e) => e.id)));
+
+    // Every node, read in full. A node the session rewound away from is
+    // still on disk, and listing only the current path would leave it
+    // undestroyed and unfindable at the same time.
+    const all: { node: number; events: LogEvent[] }[] = [];
+    for (const id of await listNodes(dir)) {
+      const { header, events } = await readNode(dir, id);
+      if (header === null) continue;
+      all.push({ node: id, events });
+    }
+
+    const points: RestorePoint[] = [];
+    for (const n of all) {
+      let open: { prompt: string; changed: number; last: string } | null = null;
+      const close = () => {
+        if (open) {
+          points.push({
+            node: n.node, atEvent: open.last, prompt: open.prompt,
+            changed: open.changed, onPath: onPath.has(open.last),
+          });
+        }
+      };
+      for (const e of n.events) {
+        if (e.t === "snapshot" && e.phase === "idle") {
+          close();
+          open = null;
+          points.push({ node: n.node, atEvent: e.id, prompt: "Observed workspace changes",
+            changed: Object.keys(e.added).length + Object.keys(e.changed).length + e.removed.length,
+            onPath: onPath.has(e.id) });
+          continue;
+        }
+        if (e.t === "user") {
+          close();
+          open = { prompt: e.text, changed: 0, last: e.id };
+          continue;
+        }
+        if (!open) continue;
+        open.last = e.id;
+        if (e.t === "snapshot") {
+          open.changed +=
+            Object.keys(e.added).length + Object.keys(e.changed).length + e.removed.length;
+        }
+      }
+      close();
+    }
+    return points;
+  }
+
+  /**
+   * 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.
+   */
+  async previewRewind(point: RestorePoint): Promise<RewindPreview> {
+    const plan = await planRestoreToNode(
+      this.config.logDir, { node: point.node, atEvent: point.atEvent },
+      undefined, this.config.tools.root, this.ignore,
+    );
+    return plan.ok
+      ? { ok: true, willWrite: plan.willWrite, willDelete: plan.willDelete }
+      : { ok: false, error: plan.error };
+  }
+
+  /**
+   * Goes back to a turn: the files and the conversation move together.
+   *
+   * FORKS, never truncates. claude-code#89646 is the argument for this: their
+   * rewind drops the context and starts a new session, so rewinding too far
+   * loses the work with no way back -- even though the transcript was
+   * append-only on disk the whole time. Here the node rewound away from is
+   * 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.
+   */
+  async rewind(point: RestorePoint, mode: RewindMode = "both"): Promise<RewindResult> {
+    const dir = this.config.logDir;
+    const root = this.config.tools.root;
+    const target = { node: point.node, atEvent: point.atEvent };
+    const movesFiles = mode !== "context";
+
+    const blobDir = this.config.blobDir;
+    // Only the modes that move files need somewhere to read them from. A
+    // context-only rewind is the one thing still worth offering a session
+    // that never took snapshots, so requiring them would refuse it for no
+    // reason.
+    if (movesFiles && !blobDir) {
+      return {
+        ok: false,
+        error: "this session stores no snapshots, so the files cannot be moved back",
+      };
+    }
+
+    // Planned before anything is written: an unresolvable target must leave
+    // the session exactly where it was, not half moved. The plan is also
+    // what every mode needs -- to apply, or to say what it is NOT applying.
+    const plan = await planRestoreToNode(dir, target, undefined, root, this.ignore);
+    if (!plan.ok) return { ok: false, error: plan.error };
+    // Preserve idle edits before moving away from them. An unobserved file is
+    // not disposable just because the target predates it (D8/appendix H).
+    for await (const event of this.snapshotTurn([], false, "idle")) {
+      if (event.kind === "snapshot_failed") return { ok: false, error: event.reason ?? "snapshot failed" };
+    }
+    const beforeFiles = { ...this.state.lastScan };
+
+    // Computed BEFORE anything is applied. Both partial modes diverge over
+    // the same set -- where the target and the workspace as it stands now
+    // disagree -- and only the story differs, which `mode` already carries.
+    // Computing it afterwards gave "files" an empty set, because by then the
+    // disk had become the target: the note still said to re-read but named
+    // nothing, which is the vague form this is meant to replace.
+    const divergence = mode === "both" ? [] : await this.divergenceFrom(plan.files);
+
+    let moved: RestoreResult = {
+      restored: [], removed: [], unrecoverable: [],
+      note: "The workspace was left exactly as it is; only the conversation moved.",
+    };
+    if (movesFiles && blobDir) {
+      // Applied from the plan just computed rather than through
+      // restoreToNode, which would re-plan: a second traversal, and a guard
+      // here that could never fire because the only way the apply fails is a
+      // plan that failed.
+      moved = await applyRestorePlan(
+        root, blobDir, plan.files, this.ignore,
+        `the point where you were asked: ${point.prompt.slice(0, 40)}`,
+      );
+      if (moved.unrecoverable.length > 0) return { ok: true, node: this.state.node, ...moved };
+    }
+
+    const from: NodeRef = { ...await digestedRef(dir, point.node), at_event: point.atEvent };
+    const stamp = { id: this.clock.nextId(), at: this.clock.now() };
+    const event: LogEvent = {
+      t: "rewind", ...stamp, mode, from, prompt: point.prompt,
+      restored: moved.restored, removed: moved.removed,
+      unrecoverable: moved.unrecoverable, divergence,
+    };
+
+    if (mode === "files") {
+      // No fork. The conversation did not move, so the node did not either;
+      // a new node would be identical to this one but for a single event.
+      await this.record(event);
+      this.state.lastScan = beforeFiles;
+      for await (const result of this.snapshotTurn([], true)) {
+        if (result.kind === "snapshot_failed") throw new Error(result.reason);
+      }
+      return { ok: true, node: this.state.node, ...moved };
+    }
+
+    const node = this.state.nextNode++;
+    // "inherit": the point of a rewind is to continue from the target as if
+    // the turns after it had not happened, so the target's events replay.
+    await initNode(dir, node, from, this.clock.now(), "inherit");
+
+    // The running session projects from state.events, which a new node starts
+    // empty -- correct for a cut, where the handoff replaces them, and wrong
+    // here. The inherited events come from the ancestry walk, which is the
+    // same function the projection would use and already honours both the
+    // fork point and any cut further up.
+    const replayed = await replayContext(dir, node);
+
+    this.state.node = node;
+    this.state.events = [];
+    this.state.handoff = replayed.handoff;
+    this.stall = null;
+    this.state.depth = replayed.depth;
+    // The new node's prefix has never been sent, so nothing to anchor to.
+    this.state.anchor = null;
+    // The scan baseline follows the files, which a context-only rewind did
+    // not move. Setting it to the plan there would make the next turn report
+    // the untouched workspace as a change nobody declared.
+    this.state.lastScan = plan.files;
+    // Path depth comes from replay; the monotonic allocator still accounts
+    // for every node spent outside this selected path.
+
+    await this.record(event);
+    // Recorded first, then replayed, so the rewind event stays the node's own
+    // annotation rather than something the inherited context contains.
+    this.state.events = [...replayed.contextEvents, ...this.state.events];
+    // A context-only fork inherits old file history while the disk stays
+    // newer. Record that delta now, so later replay cannot resurrect a stale
+    // workspace and the next tool starts from the actual files.
+    for await (const result of this.snapshotTurn([], true)) {
+      if (result.kind === "snapshot_failed") throw new Error(result.reason);
+    }
+    await this.saveCursor();
+
+    return { ok: true, node, ...moved };
+  }
+
+  /**
+   * Paths where the target and the workspace as it stands now disagree.
+   *
+   * Read off the disk rather than inferred from the plan, because a file a
+   * person changed by hand belongs in the answer just as much as one a
+   * rewound turn wrote.
+   */
+  private async divergenceFrom(target: FileSet): Promise<string[]> {
+    const current = await scanWorkspace(this.config.tools.root, this.ignore);
+    if (!current.ok) return [];
+    const delta = diffScans(target, current.files);
+    return [
+      ...Object.keys(delta.added), ...Object.keys(delta.changed), ...delta.removed,
+    ].sort();
+  }
+
+  private async *checkStall(): AsyncGenerator<LoopEvent, boolean> {
+    const limit = this.config.stallLimit ?? DEFAULT_STALL_LIMIT;
+    if (limit === 0) return false;
+    if (this.stall === null) {
+      const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+      if (!history.ok) throw new Error(history.error);
+      this.stall = advanceStall(emptyStallState(), history.nodes.flatMap(({ node, events }) => events.map((event) => ({ node, event }))));
+    }
+    const decision = stallDecision(this.stall, limit);
+    if (decision.stop) {
+      yield { kind: "stop_and_ask", reason: `${decision.consecutive} consecutive tool exchanges without new evidence or fresh verification; change the approach or provide new input` };
+      return true;
+    }
+    if (decision.warn) await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "stall", sources: [],
+      text: `Harness: ${decision.consecutive} consecutive tool exchanges without new evidence or fresh verification. Change the method, run a meaningful check, or give the final result with unresolved limits. The harness will stop at ${limit} such exchanges. Notes and repeated observations do not count as progress.` });
+    return false;
+  }
+
+  /** N.8: build and check the replacement before committing a durable boundary. */
+  /**
+   * `overflowed` is the provider's own verdict that the current projection
+   * does not fit, which outranks any estimate: the cut is taken as a hard
+   * limit, and retention is sized against the estimate scaled so the rejected
+   * 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 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;
+    const scale = overflowed ? Math.max(1, (budget.usable + 1) / Math.max(1, measured)) : 1;
+    if (overflowed) counter = scaledCounter(counter, scale);
+    let tokens = Math.ceil(measured * scale);
+    if (tokens < budget.prepare) return false;
+    const replayed = await replayContext(this.config.logDir, this.state.node);
+    let draft: Handoff;
+    try {
+      draft = boundHandoff(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) {
+      if (!(error instanceof RangeError)) throw error;
+      // An objective too large for a carried handoff cannot be repaired by another cut.
+      if (tokens <= budget.usable) return false;
+      yield { kind: "stop_and_ask", reason: `context cannot fit the model window: ${error instanceof Error ? error.message : "handoff construction failed"}` };
+      return true;
+    }
+    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 (this.config.guidance !== false && noteEnabled && tokens < budget.trigger && budget.trigger > 1) {
+      const notice = boundaryPreparation({ events: this.state.events, tokens, inheritedTokens: 0,
+        continuationReady: draft.continuation_valid,
+        config: { triggerTokens: budget.trigger, hardTokens: budget.trigger + (budget.trigger - budget.prepare), minNodeWorkTokens: 0 } });
+      if (notice) {
+        await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), ...notice });
+        projected = project();
+        tokens = anchoredCount(projected.messages, projected.system, this.state.anchor, counter, this.config.frozen.tools).tokens;
+      }
+    }
+    if (tokens < budget.trigger) return false;
+    const lastAssistant = this.state.events.findLastIndex((event) => event.t === "assistant");
+    const pendingUser = this.state.events.slice(lastAssistant + 1).find((event) => event.t === "user");
+    const retained = selectRecentContext({ events: this.state.events, frozen: this.config.frozen, handoff: draft,
+      counter, targetTokens: budget.target,
+      ...(pendingUser === undefined ? {} : { requiredUserId: pendingUser.id }) });
+    if (retained === null || retained.tokens >= tokens) {
+      // A large fresh prompt may still fit; let the model answer once. Never discard
+      // it to manufacture space, or record repeated cuts that cannot shrink it.
+      if (tokens <= budget.usable) return false;
+      yield { kind: "stop_and_ask", reason: "context cannot fit the model window while preserving the current request and a complete recent exchange; reduce the input or use a larger verified window" };
+      return true;
+    }
+    const node = this.state.node;
+    const reason = tokens > budget.usable ? "hard_limit" : "trigger";
+    await this.performCut(reason, this.provider.config.spec.id, retained.from);
+    yield { kind: "cut", node, reason };
+    return false;
+  }
+
+  private async *maybeCut(counter: TokenCounter, canPrepare: boolean): AsyncGenerator<LoopEvent, boolean> {
+    if ((this.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY) === "windowed" && this.provider.config.spec.contextWindow !== undefined) {
+      return yield* this.maybeWindowCut(counter, canPrepare);
+    }
+    const projected = projectContext({
+      frozen: this.config.frozen,
+      handoff: this.state.handoff,
+      events: this.state.events,
+    });
+    let { tokens } = anchoredCount(
+      projected.messages, projected.system, this.state.anchor, counter,
+      this.config.frozen.tools,
+    );
+
+    // What this node would cost having done nothing: the frozen prefix plus
+    // the rendered handoff. Cutting cannot reduce it, so it does not count
+    // toward the node having earned a boundary.
+    const floor = projectContext({
+      frozen: this.config.frozen,
+      handoff: this.state.handoff,
+      events: [],
+    });
+    // Counted with the tools, because `tokens` above came from the anchor and
+    // the provider bills schemas on every request. Subtracting a figure that
+    // omitted them would read the difference as work the node had done.
+    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)) {
+      // 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,
+        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) {
+        const notice = boundaryPreparation({ events: this.state.events, tokens, inheritedTokens,
+          continuationReady: draft.continuation_valid, config: cfg });
+        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 });
+          tokens = anchoredCount(updated.messages, updated.system, this.state.anchor, counter, this.config.frozen.tools).tokens;
+        }
+      }
+    }
+    const price = this.provider.config.spec.price;
+    const usage = this.state.usage.at(-1);
+    const replacement = draft ? projectContext({ frozen: this.config.frozen, handoff: draft, events: [] }) : null;
+    const cost = replacement && price?.cacheRead !== undefined && price.cacheWrite !== undefined && usage &&
+      usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens > 0
+      ? estimateBoundaryCost({ retainedTokens: tokens,
+        rebuiltTokens: counter.count(replacement.messages, replacement.system, this.config.frozen.tools),
+        observedCachedTokens: usage.node === this.state.node ? usage.cache_read_input_tokens : 0,
+        inputPrice: price.input, cacheReadPrice: price.cacheRead, cacheWritePrice: price.cacheWrite }) : null;
+    const decision = decideContext({
+      policy, continuationReady: draft?.continuation_valid ?? false, cost,
+      tokens,
+      inheritedTokens,
+      atTurnBoundary: true,
+      ...(this.config.boundary ? { config: this.config.boundary } : {}),
+    });
+
+    if (!decision.cut) {
+      // A floor past the hard limit cannot be worked around by cutting; the
+      // caller has to widen the thresholds or shrink the frozen prefix.
+      if (decision.reason === "inherited_floor_exceeds_limit") {
+        yield {
+          kind: "stop_and_ask",
+          reason:
+            `the inherited context alone is ${inheritedTokens} tokens, at or past the hard ` +
+            `limit -- widen the thresholds or shrink the system prompt`,
+        };
+        return true;
+      }
+      return false;
+    }
+
+    const node = this.state.node;
+    await this.performCut(decision.reason);
+    yield { kind: "cut", node, reason: decision.reason };
+
+    // D9 uses observations and fresh successful checks, not model assertions.
+    // The closed node's handoff is now this.state.handoff.
+    const handoff = this.state.handoff;
+    if (handoff !== null && shouldStopAndAsk(handoff.budget.nodes_without_progress)) {
+      yield {
+        kind: "stop_and_ask",
+        reason:
+          `${handoff.budget.nodes_without_progress} nodes with no verifiable progress. ` +
+          `blocked: ${handoff.state.blocked.length}, open questions: ${handoff.open_questions.length}`,
+      };
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Closes the current node and opens the next with a handoff basis.
+   *
+   * Shared by the automatic boundary and by switchModel. The caller decides
+   * WHETHER to cut -- this only performs it. Putting the work floor in here
+   * would make a model switch wait for minNodeWorkTokens, and the new model
+   * would see the old thinking blocks in the meantime.
+   */
+  private async performCut(reason: CutReason, nextModel = this.provider.config.spec.id, retainedFrom?: 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);
+
+    // 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,
+      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");
+    await this.saveCursor();
+  }
+}