@visual-z/xeno 0.8.2 → 0.8.4

package/src/runtime/loop.ts

@@ -18,11 +18,12 @@
  * request.
  */
 
-import type { LogEvent, AssistantBlock, NodeRef, CutReason, ToolInvocationEvent } from "../core/events.ts";
+import type { LogEvent, AssistantBlock, NodeRef, CutReason, ToolInvocationEvent, FailureCause } from "../core/events.ts";
 import { userInputData, submissionImages, type UserInput, type ImageRef } from "../core/images.ts";
 import { hydrateImages } from "./images.ts";
 import type { Handoff } from "../core/handoff.ts";
 import { boundHandoff, DEFAULT_HANDOFF_TOKENS } from "../core/history.ts";
+import { CURRENT_WORKING_SET_VERSION } from "../core/working-set.ts";
 import { boundaryPreparation, continuationGuidance } from "../core/continuation.ts";
 import type { FrozenPrefix, Message, ProjectInput } from "../core/project.ts";
 import { projectContext, toolCallIdentityViolations } from "../core/project.ts";
@@ -76,7 +77,11 @@ import { skillTools, type Skill } from "../core/skills.ts";
 import type { WorkItem } from "../core/work-state.ts";
 import { parseAcceptanceContract, type AcceptanceContract, type AcceptanceCriterion, type AcceptanceState } from "../core/acceptance.ts";
 import { deadlineNotice } from "../core/deadline.ts";
-import { statusOf } from "./retry.ts";
+import { describeFailure, failureCause, statusOf } from "./retry.ts";
+import { XENO_VERSION } from "./version.ts";
+import { SECRET_GUIDANCE, SecretKeeper } from "./secrets.ts";
+import { secretEnvironmentValues } from "../core/secrets.ts";
+import { copyVault } from "../store/secrets.ts";
 import { assertNever } from "../core/exhaustive.ts";
 import { isLogEvent } from "../core/event-validation.ts";
 import {
@@ -177,6 +182,8 @@ export interface LoopEvent {
   /** branch_start: wall-clock milliseconds, for asserting the stagger. */
   at?: number;
   outcome?: ExecutionOutcome;
+  /** done: credential-free cause of a failed request, recorded on its outcome. */
+  failure?: FailureCause;
   /** Q23: task evidence is separate from the execution outcome; rebuilt from original receipts. */
   request?: RequestState;
   progress?: Extract<StreamDelta, { kind: "tool" | "retry" }> | { kind: "output"; text: string; name: string }
@@ -214,6 +221,11 @@ export const DEFAULT_BRANCH_LIMITS: BranchLimits = {
 };
 
 export interface SessionConfig {
+  /**
+   * Where secret-named environment values are read from (S.9). Defaults to
+   * process.env; a test supplies its own so it never depends on the machine.
+   */
+  secretEnvironment?: Readonly<Record<string, string | undefined>>;
   /** Runtime-only output contract, explicitly selected by the current caller. */
   validateOutput?: (text: string) => { ok: boolean; error?: string };
   /** Persist a selector, never persisted profile code or authorization (D6/D13). */
@@ -365,6 +377,15 @@ export type CommittedItem = { node: number; id: string; type: LogEvent["t"] };
 export class Session {
   private readonly execOwner = randomUUID();
   private readonly jobs = new BranchJobs<DeferredToolResult>();
+  /**
+   * Branches the user started (/review-code), owned apart from `jobs`: an Esc
+   * on a parent turn cancels the model's branches, never these. Their joins
+   * wait in `pendingJoins` until the parent is idle and pairable.
+   */
+  private readonly userJobs = new BranchJobs<Extract<LogEvent, { t: "joined" }>>();
+  private readonly pendingJoins: { joined: LogEvent; note: string; usage: readonly UsageSample[] }[] = [];
+  /** Spawned but not yet handed to `userJobs` (its prelude is still recording): already running to an observer. */
+  private readonly startingUserBranches = new Set<number>();
   private readonly children = new Map<number, Session>();
   private cleanup: Promise<void> | null = null;
   private closing: Promise<void> | null = null;
@@ -381,12 +402,19 @@ export class Session {
   private stall: StallState | null = null;
   private recovery: RecoveryState | null = null;
   private processWake = new AbortController();
+  /**
+   * The exception the last provider request ended with, compared by identity
+   * in send()'s catch. Wrapping the error instead would break every check that
+   * reads it (FailedResponseError, statusOf, context overflow).
+   */
+  private providerFailure: { error: unknown; retries: number } | undefined;
   private pendingAdoption: number | null = null;
   /** A worktree enter/exit moves the root only once its tool round is paired, like adoption. */
   private pendingRoot: string | null = null;
   private readonly allocatedEventIds = new Set<string>();
   private recordTail: Promise<void> = Promise.resolve();
   private readonly recordListeners = new Set<(item: CommittedItem) => void>();
+  private readonly branchRecordListeners = new Set<(item: CommittedItem) => void>();
   readonly config: SessionConfig;
   /**
    * Replaced by switchModel. Not readonly: a live session can change which
@@ -397,6 +425,8 @@ export class Session {
   readonly clock: Clock;
   state: SessionState;
   private readonly allocation: { next: number };
+  /** S.9: the vault behind placeholders. A branch is handed its parent's, like `allocation`. */
+  private secrets: SecretKeeper;
 
   constructor(config: SessionConfig, provider: Provider, clock: Clock = systemClock(), allocation = { next: 1 }) {
     if (config.acceptanceContract) parseAcceptanceContract(config.acceptanceContract);
@@ -406,6 +436,7 @@ export class Session {
     schedulingWindow([], 0, config.maxParallelTools ?? 3);
     validateRequestBudget(config.maxTurns, config.stallLimit ?? DEFAULT_STALL_LIMIT);
     this.allocation = allocation;
+    this.secrets = new SecretKeeper(config.logDir, secretEnvironmentValues(config.secretEnvironment ?? process.env));
     this.config = { ...config, ...(config.acceptanceContract ? { acceptanceContract: parseAcceptanceContract(config.acceptanceContract) } : {}), tools: { ...config.tools, execOwner: this.execOwner, historyCache: new HistoryCache(),
       processWait: { wake: () => this.processWake.signal } } };
     // A child or restored Session must never inherit another live invocation scope.
@@ -419,6 +450,8 @@ export class Session {
     // Branch capability sets are owned by branchTools; a parent's optional catalog is not a grant.
     if ((config.branchDepth ?? 0) > 0) delete this.config.tools.deferredTools;
     this.config.tools.outputStore ??= join(config.logDir, "artifacts");
+    // Read at call time, so a branch that is handed its parent's keeper expands the parent's values.
+    this.config.tools.expandSecrets = input => this.secrets.expand(input);
     this.config.tools.historyEvents = async () => {
       const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
       if (!history.ok) throw Error(history.error);
@@ -498,6 +531,7 @@ export class Session {
   async start(): Promise<void> {
     this.resetDerivedToolState();
     const dir = this.config.logDir;
+    await this.secrets.load();
     const model = this.provider.config.spec.id;
     const existing = await listNodes(dir);
     const recordedCursor = await readCursor(dir);
@@ -607,6 +641,7 @@ export class Session {
    */
   async fork(destLogDir: string, untilEvent?: string, position: "at" | "before" = "at"): Promise<void> {
     await copyAncestryTo(this.config.logDir, destLogDir, this.clock.now(), untilEvent, position);
+    await copyVault(this.config.logDir, destLogDir);
     if (untilEvent !== undefined) {
       const cursor = await readCursor(destLogDir);
       if (!cursor) throw new Error("missing fork cursor");
@@ -749,8 +784,18 @@ export class Session {
    * 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.
+   *
+   * An empty projection is the exception (fix-switch-model-empty-segment).
+   * With no events there is no old model's block to keep away from the new
+   * one, and the frozen prefix does not change here, so the cursor alone
+   * records the switch. Cutting anyway sealed an empty segment and opened
+   * the next from an empty handoff, which the model read as earlier work to
+   * resume. The check is the projection, not the node file: an inherit-basis
+   * node can be empty on disk while still projecting ancestor thinking.
+   *
+   * Returns whether a segment was cut, so the caller can say so truthfully.
    */
-  async switchModel(next: Provider): Promise<void> {
+  async switchModel(next: Provider): Promise<boolean> {
     if (this.running || this.isHalfRound()) {
       throw new Error(
         "cannot switch models mid-turn: a tool_use is still unpaired. " +
@@ -758,9 +803,12 @@ export class Session {
       );
     }
 
-    await this.performCut("model_checkpoint", next.config.spec.id, undefined, next.config.spec.provider, next.config.effort);
+    const cut = this.state.events.length > 0;
+    if (cut) await this.performCut("model_checkpoint", next.config.spec.id, undefined, next.config.spec.provider, next.config.effort);
+    else this.state.anchor = null;
     this.provider = next;
     await this.saveCursor();
+    return cut;
   }
 
   /** D6: changing the frozen prefix is an explicit checkpoint, never in-place prompt surgery. */
@@ -890,10 +938,15 @@ export class Session {
       updated_at: this.clock.now(),
       workspace: this.config.tools.root,
       context_ref: contextRef ?? await this.persistContext(),
+      xeno_version: XENO_VERSION,
     });
   }
 
   /** Q24: publish identities only after durable append, including non-model user actions. */
+  /** Commits inside this session's branches (their node numbers), for a client showing one live. */
+  subscribeBranchRecords(listener: (item: CommittedItem) => void): () => void {
+    this.branchRecordListeners.add(listener); return () => { this.branchRecordListeners.delete(listener); };
+  }
   subscribeRecords(listener: (item: CommittedItem) => void): () => void {
     this.recordListeners.add(listener); return () => { this.recordListeners.delete(listener); };
   }
@@ -902,6 +955,10 @@ export class Session {
     // D8: runtime callers may retain mutable results. The in-memory projection
     // must own the same JSON value that was appended, independent of later edits.
     event = JSON.parse(JSON.stringify(event)) as LogEvent;
+    // S.9: credentials become placeholders before anything is written, so no
+    // projection, handoff, export or history page can carry the value.
+    const redacted = await this.secrets.redact(event, this.lastAssistantText());
+    event = redacted.event;
     const saved = this.recordTail.then(async () => {
       await appendEvent(this.config.logDir, this.state.node, event);
       this.state.events.push(event);
@@ -913,6 +970,9 @@ export class Session {
     });
     this.recordTail = saved.catch(() => {});
     await saved;
+    if (redacted.added > 0 && !this.state.events.some(item => item.t === "guidance" && item.reason === "secret")) {
+      await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "secret", text: SECRET_GUIDANCE, sources: [event.id] });
+    }
     if (event.t === "tool_result" && event.ok && event.effect?.kind === "read") {
       const path = resolve(this.config.tools.root, event.effect.path);
       const skill = this.config.skills?.find(item => item.filePath === path);
@@ -925,6 +985,19 @@ export class Session {
     }
   }
 
+  /** The text the user is answering, for recognising a solicited credential. */
+  private lastAssistantText(): string | undefined {
+    for (let i = this.state.events.length - 1; i >= 0; i--) {
+      const event = this.state.events[i]!;
+      if (event.t === "user") return undefined;
+      if (event.t === "assistant") {
+        const text = event.blocks.flatMap(block => block.type === "text" ? [block.text] : []).join("\n");
+        if (text.trim()) return text;
+      }
+    }
+    return undefined;
+  }
+
   private allowedNames(): string[] {
     return this.config.frozen.tools.flatMap(tool => tool !== null && typeof tool === "object" && "name" in tool && typeof tool.name === "string" &&
       (this.config.tools.allow === undefined || this.config.tools.allow.includes(tool.name)) ? [tool.name] : []);
@@ -1000,7 +1073,7 @@ export class Session {
 
   private async boundCarried(full: Handoff, tools = this.adviceNames()): Promise<Handoff> {
     return carriedHandoff(this.config.logDir, this.state.node, full, { handoff_tokens: DEFAULT_HANDOFF_TOKENS,
-      ...(this.config.workingSet ? { working_set_version: 2 as const } : {}), guidance_tools: tools });
+      ...(this.config.workingSet ? { working_set_version: CURRENT_WORKING_SET_VERSION } : {}), guidance_tools: tools });
   }
 
   async acceptanceState(): Promise<AcceptanceState | undefined> {
@@ -1152,6 +1225,69 @@ export class Session {
     } finally { owned.finish(); }
   }
 
+  /**
+   * D14 for a branch the user opened rather than the model. Returns once
+   * `spawn` is recorded; the child runs in the background with the caller's
+   * explicit config (its own prompt, tools and roots: nothing of the parent's
+   * transcript, so a review stays independent of the work it judges). When it
+   * ends, `joined` plus one guidance line reach the parent at its next idle,
+   * pairable point -- the line is how the parent model learns to read it.
+   */
+  async startUserBranch(spec: {
+    purpose: string; prompt: string; config: SessionConfig; provider?: Provider;
+    /** Events the branch records before its first request (a review's premise receipt). */
+    prelude?: (branch: Session) => Promise<void>;
+    /** The guidance the parent model gets once the branch joined. */
+    note: (node: number, joined: Extract<LogEvent, { t: "joined" }>) => string;
+  }): Promise<number> {
+    if (this.cleanup || this.closing) throw new Error("session is draining or disposed");
+    const node = this.state.nextNode++;
+    this.startingUserBranches.add(node);
+    try { return await this.launchUserBranch(node, spec); } finally { this.startingUserBranches.delete(node); }
+  }
+  private async launchUserBranch(node: number, spec: Parameters<Session["startUserBranch"]>[0]): Promise<number> {
+    const sourceEvent = this.state.events.findLast(event => event.t === "user")?.id;
+    const { ref, branch } = await this.openBranch({ node, purpose: spec.purpose, background: true, ...(sourceEvent ? { sourceEvent } : {}),
+      inputWorkspace: { kind: "shared_readonly" }, worktree: null, config: spec.config, ...(spec.provider ? { provider: spec.provider } : {}) });
+    // Not in `children`: the parent's cancel() disposes those, and an Esc must not stop this one.
+    try { await spec.prelude?.(branch); await this.saveCursor(); }
+    catch (error) { await branch.dispose(); throw error; }
+    const controller = new AbortController();
+    this.userJobs.start(node, controller, async () => {
+      const { outcome, text } = await this.runChild(node, branch, spec.prompt, true, controller.signal, true);
+      const { joined } = await this.closeBranch(ref, branch, outcome, text);
+      if (joined.t !== "joined") throw new Error("a closed branch must produce a joined event");
+      this.pendingJoins.push({ joined, note: spec.note(node, joined), usage: [...branch.state.usage] });
+      await this.flushUserJoins();
+      return joined;
+    }, () => {});
+    return node;
+  }
+  /** User branches still running, so a client can show and stop them. */
+  get userBranches(): readonly number[] {
+    return [...this.startingUserBranches, ...this.userJobs.nodes().filter(node => this.userJobs.state(node) === "running")];
+  }
+  /** Every branch with a live child here: the model's (foreground or background) and the user's. */
+  get runningBranches(): readonly number[] { return [...new Set([...this.children.keys(), ...this.userBranches])]; }
+  cancelUserBranch(node: number): void { this.userJobs.cancel(node); }
+  /**
+   * The branch's join once it ended -- recorded, or still waiting for the
+   * parent to be idle and pairable. Undefined if its finalization failed.
+   */
+  async whenUserBranch(node: number): Promise<Extract<LogEvent, { t: "joined" }> | undefined> {
+    await this.userJobs.drain(node); return (await this.userJobs.wait(node, 0))?.value;
+  }
+  /** Appends joins that waited for an idle, pairable parent. Never mid-turn: the guidance enters model context. */
+  private async flushUserJoins(): Promise<void> {
+    while (this.pendingJoins.length > 0 && !this.running && !this.cleanup && !this.isHalfRound()) {
+      const item = this.pendingJoins.shift()!;
+      this.state.usage.push(...item.usage);
+      await this.record(item.joined);
+      await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "branch", text: item.note, sources: [item.joined.id] });
+      await this.saveCursor();
+    }
+  }
+
   private async drainProcesses(): Promise<void> {
     const results = await disposeExecSessions(this.execOwner, this.config.tools.outputStore!, this.config.tools.maxOutputBytes);
     await this.config.tools.workspace?.abandonCommands();
@@ -1170,7 +1306,9 @@ export class Session {
   dispose(): Promise<void> {
     if (this.closing) return this.closing;
     this.cancel();
-    this.closing = this.whenIdle().then(() => this.rootTools?.close());
+    // User branches outlive interrupts, not the session. Their joins are still recorded.
+    this.userJobs.cancel();
+    this.closing = this.whenIdle().then(async () => { await this.userJobs.drain(); await this.flushUserJoins(); }).then(() => this.rootTools?.close());
     return this.closing;
   }
 
@@ -1256,6 +1394,7 @@ export class Session {
           if (item.value.outcome && item.value.outcome.reason !== "model_end") await this.record({
             t: "outcome", id: this.clock.nextId(), at: this.clock.now(),
             reason: item.value.reason ?? item.value.outcome.reason, outcome: item.value.outcome,
+            ...(item.value.failure ? { failure: item.value.failure } : {}),
           });
           const request = await this.requestState();
           if (request) item.value.request = request;
@@ -1270,9 +1409,14 @@ export class Session {
         yield { kind: "done", reason: "stopped: request ended without a terminal outcome", outcome, ...(request ? { request } : {}) };
       }
     } catch (error) {
-      // Raw provider exceptions can contain credentials; persist only the execution fact.
+      // Raw exceptions can contain credentials; persist the category, never the message.
+      // Only the provider request's own exception is a provider error: this catch
+      // also sees failures in history reads and in the harness itself.
+      const provider = this.providerFailure?.error === error ? this.providerFailure : undefined;
+      const failure = failureCause(error, provider);
       await this.record({ t: "outcome", id: this.clock.nextId(), at: this.clock.now(),
-        reason: "request failed before completion; no complete response was committed", outcome: executionOutcome("provider_error") });
+        reason: `request failed before completion (${describeFailure(failure)}); no complete response was committed`,
+        outcome: executionOutcome(provider ? "provider_error" : "execution_error"), failure });
       throw error;
     } finally {
       // Closing a consumer is not a user cancellation. Preserve the existing
@@ -1287,6 +1431,8 @@ export class Session {
         if (owned.signal.aborted) this.cancel();
         owned.finish();
         if (owned.signal.aborted) await this.whenIdle();
+        // A user branch that ended mid-turn joins now that the parent is idle.
+        if (this.pendingJoins.length > 0) await this.flushUserJoins().catch(() => {});
       }
     }
   }
@@ -1404,7 +1550,9 @@ export class Session {
           }
           if (phase === "finalize") {
             yield { kind: "discard" };
-            yield { kind: "done", reason: await report("final response failed; no additional request was made", turn + 1), outcome: executionOutcome("provider_error") };
+            const failure = failureCause(error, this.providerFailure?.error === error ? this.providerFailure : { retries: 0 });
+            yield { kind: "done", reason: await report(`final response failed (${describeFailure(failure)}); no additional request was made`, turn + 1),
+              outcome: executionOutcome("provider_error"), failure };
             return;
           }
           if (!(error instanceof Error) || !isContextOverflow(error.message, statusOf(error))) throw error;
@@ -1737,8 +1885,9 @@ export class Session {
   ): AsyncGenerator<LoopEvent, Turn> {
     const hydrated = await hydrateImages(messages, this.config.blobDir ?? join(this.config.logDir, "blobs"),
       this.provider.config.spec.input?.includes("image") ?? false);
-    return yield* withProgress<Turn, LoopEvent>(emit => this.provider.send(
-      this.config.frozen, hydrated, this.state.node, signal, (delta: StreamDelta): void => {
+    let retries = 0;
+    this.providerFailure = undefined;
+    const progress = (emit: (event: LoopEvent) => void) => (delta: StreamDelta): void => {
       switch (delta.kind) {
         case "text":
           emit({ kind: "text_delta", text: delta.text });
@@ -1749,13 +1898,25 @@ export class Session {
         case "discard":
           emit({ kind: "discard" });
           break;
-        case "tool": case "retry":
+        case "retry":
+          retries = Math.max(retries, delta.attempt);
+          emit({ kind: "progress", progress: delta });
+          break;
+        case "tool":
           emit({ kind: "progress", progress: delta });
           break;
         default:
           return assertNever(delta, "onDelta");
       }
-    }, options));
+    };
+    try {
+      return yield* withProgress<Turn, LoopEvent>(emit => this.provider.send(
+        this.config.frozen, hydrated, this.state.node, signal, progress(emit), options));
+    } catch (error) {
+      // The outcome needs to know this exception came from the request, and after how many retries.
+      this.providerFailure = { error, retries };
+      throw error;
+    }
   }
 
   /**
@@ -1829,7 +1990,10 @@ export class Session {
       let context: ToolContext = { ...this.config.tools, ...(this.readOnlyRequest ? { workflowMode: "plan" as const, planHint: READ_ONLY_HINT } : {}),
         imageStore: this.config.blobDir ?? join(this.config.logDir, "blobs"),
         advice: this.allowedNames(),
-        imageAutoResize: this.config.imageOptions?.autoResize ?? true, ...(signal ? { signal } : {}) };
+        imageAutoResize: this.config.imageOptions?.autoResize ?? true, ...(signal ? { signal } : {}),
+        // feat-approval-events: the broker has already recorded this call's
+        // invocation, and its result comes after execution, so the order is fixed.
+        onApproval: approval => this.record({ t: "approval", id: this.clock.nextId(), at: this.clock.now(), ...approval }) };
       if (native) context = nativeCommandContext(context);
       const decoder = new TextDecoder();
       context.onOutput = chunk => emit({ kind: "progress", progress: { kind: "output", name: call.name, text: decoder.decode(chunk, { stream: true }) } });
@@ -2036,7 +2200,6 @@ export class Session {
 
     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.
 
     // A writing branch needs its own checkout, or parallel branches overwrite
@@ -2056,20 +2219,9 @@ export class Session {
       this.state.worktrees.set(node, worktree);
     }
 
-    await this.record({
-      t: "spawn", id: this.clock.nextId(), at: this.clock.now(), branch: ref, purpose,
-      ...(args["background"] === true ? { background: true as const } : {}),
-      input: { source_event: sourceEvent, tools: allowed, max_turns: Math.min(this.config.maxTurns, 15), workspace: inputWorkspace },
-      ...(worktree ? { workspace: worktree } : {}),
-    });
-
-    // 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(
-      {
+    const { ref, branch } = await this.openBranch({
+      node, purpose, background: args["background"] === true, sourceEvent, inputWorkspace, worktree,
+      config: {
         ...this.config,
         acceptanceContract: null,
         frozen: { system: this.config.frozen.system, tools: branchTools(writes, allowed) },
@@ -2086,40 +2238,14 @@ export class Session {
         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;
+    });
     if (skill) await branch.recordSkill(skill, "fork", skillOrigin);
     this.children.set(node, branch);
     yield { kind: "branch_start", node, reason: purpose, at: Date.now() };
 
-    let finalParts: string[] = [];
-    let outcome = executionOutcome("unknown");
-    try {
-      for await (const e of branch.send(prompt, signal)) {
-        if (e.kind === "turn_start" || e.kind === "discard") finalParts = [];
-        if (e.kind === "assistant_text") finalParts.push(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");
-    } finally { try { await branch.dispose(); } finally { this.children.delete(node); } }
-    if (args["background"] === true) await branch.record({ t: "outcome", id: this.clock.nextId(), at: this.clock.now(), outcome, reason: "background branch execution ended" });
-    // Node numbers the branch allocated are taken.
-
-    const tip = branch.state.node;
-    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());
+    const { outcome, text } = await this.runChild(node, branch, prompt, args["background"] === true, signal);
+    const closed = await this.closeBranch(ref, branch, outcome, text);
+    const { tip, summary, receipt, receiptRef, joined } = closed;
 
     // The worktree stays until the branch is resolved: its uncommitted work
     // is the branch's result, and removing it here would discard exactly
@@ -2128,19 +2254,6 @@ export class Session {
       ? `\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 text = finalParts.join("\n");
-    const summary = text.trim() || "(the branch produced no closing message)";
-    const receiptHistory = await readNodeHistory(this.config.logDir, tip, undefined, "context");
-    if (!receiptHistory.ok) throw new Error(receiptHistory.error);
-    const receipt = deriveBranchReceipt({ source: await this.nodeRefFor(tip), outcome, handoff, nodes: receiptHistory.nodes });
-    const receiptRef = await putBlob(join(this.config.logDir, "artifacts"), JSON.stringify(receipt));
-    const joined: LogEvent = {
-      t: "joined", id: this.clock.nextId(), at: this.clock.now(),
-      branch: ref, tip: await this.nodeRefFor(tip), handoff_ref: handoffPath(this.config.logDir, tip), summary,
-      model: branch.provider.config.spec.id,
-      outcome,
-      receipt_ref: receiptRef,
-    };
 
     // Only the summary crosses back. The branch's own calls stay in its node,
     // which is the entire reason to branch rather than read in place.
@@ -2169,6 +2282,84 @@ export class Session {
     };
   }
 
+  /**
+   * D14: the parent records `spawn`, the branch gets its own node file with
+   * basis "none" (it starts fresh; the parent pointer is provenance only).
+   * Shared by model-spawned branches and user-started ones (/review-code).
+   */
+  private async openBranch(spec: {
+    /** Omitted for a user command in an empty session: the spawn is then its own request. */
+    node: number; purpose: string; background: boolean; sourceEvent?: string;
+    inputWorkspace: { kind: "shared_readonly" } | { kind: "git_tree"; head: string; tree: string };
+    worktree: { path: string; branch: string } | null; config: SessionConfig; provider?: Provider;
+  }): Promise<{ ref: NodeRef; branch: Session }> {
+    const { node, purpose, worktree } = spec;
+    const ref = await this.nodeRefFor(node), id = this.clock.nextId();
+    await this.record({
+      t: "spawn", id, at: this.clock.now(), branch: ref, purpose,
+      ...(spec.background ? { background: true as const } : {}),
+      input: { source_event: spec.sourceEvent ?? id, tools: spec.config.tools.allow ?? [], max_turns: spec.config.maxTurns, workspace: spec.inputWorkspace },
+      ...(worktree ? { workspace: worktree } : {}),
+    });
+    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(spec.config, spec.provider ?? (this.config.branchProvider ? this.config.branchProvider() : this.provider), this.clock, this.allocation);
+    branch.state.node = node;
+    branch.state.nextNode = this.state.nextNode;
+    branch.secrets = this.secrets;
+    branch.subscribeRecords(item => { for (const listener of this.branchRecordListeners) { try { listener(item); } catch { /* observers never own the append */ } } });
+    return { ref, branch };
+  }
+
+  /** Runs the child to its end. Its closing text is the last turn's text; a throw becomes a bounded outcome. */
+  private async runChild(node: number, branch: Session, prompt: string, background: boolean, signal?: AbortSignal, keepRecorded = false): Promise<{ outcome: ExecutionOutcome; text: string }> {
+    let finalParts: string[] = [];
+    let outcome = executionOutcome("unknown");
+    try {
+      for await (const e of branch.send(prompt, signal)) {
+        if (e.kind === "turn_start" || e.kind === "discard") finalParts = [];
+        if (e.kind === "assistant_text") finalParts.push(e.text ?? "");
+        if (e.kind === "done") outcome = e.outcome ?? executionOutcome("unknown");
+      }
+    } catch {
+      // Persist a bounded failure classification, never a provider's raw error body.
+      // A model's branch joins as execution_error (its caller sees a failed tool). A user branch keeps the
+      // classification its own send recorded (provider_error vs execution_error), as the detached review did.
+      const recorded = keepRecorded ? branch.state.events.findLast(event => event.t === "outcome") : undefined;
+      outcome = signal?.aborted ? executionOutcome("cancelled") : recorded?.t === "outcome" ? recorded.outcome : executionOutcome("execution_error");
+      await branch.answerUnpairedTools("the branch execution failed; this tool's outcome is unknown; inspect before retrying");
+    } finally { try { await branch.dispose(); } finally { this.children.delete(node); } }
+    if (background) await branch.record({ t: "outcome", id: this.clock.nextId(), at: this.clock.now(), outcome, reason: "background branch execution ended" });
+    return { outcome, text: finalParts.join("\n") };
+  }
+
+  /** Closes the branch's tip with its derived handoff and builds the `joined` the parent will record (D15). */
+  private async closeBranch(ref: NodeRef, branch: Session, outcome: ExecutionOutcome, text: string) {
+    // 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());
+    const summary = text.trim() || "(the branch produced no closing message)";
+    const receiptHistory = await readNodeHistory(this.config.logDir, tip, undefined, "context");
+    if (!receiptHistory.ok) throw new Error(receiptHistory.error);
+    const receipt = deriveBranchReceipt({ source: await this.nodeRefFor(tip), outcome, handoff, nodes: receiptHistory.nodes });
+    const receiptRef = await putBlob(join(this.config.logDir, "artifacts"), JSON.stringify(receipt));
+    const joined: LogEvent = {
+      t: "joined", id: this.clock.nextId(), at: this.clock.now(),
+      branch: ref, tip: await this.nodeRefFor(tip), handoff_ref: handoffPath(this.config.logDir, tip), summary,
+      model: branch.provider.config.spec.id,
+      outcome,
+      receipt_ref: receiptRef,
+    };
+    return { tip, summary, receipt, receiptRef, joined };
+  }
+
   private async runWorktree(input: unknown, pathRoot?: string): Promise<ToolResult> {
     const args = (typeof input === "object" && input !== null ? input : {}) as Record<string, unknown>;
     const root = this.config.tools.root;
@@ -2881,7 +3072,7 @@ export class Session {
         next_thinking: nextThinking,
         ...(nextContextRef === undefined ? {} : { next_context_ref: nextContextRef }),
         handoff_tokens: DEFAULT_HANDOFF_TOKENS,
-        ...(this.config.workingSet ? { working_set_version: 2 as const } : {}),
+        ...(this.config.workingSet ? { working_set_version: CURRENT_WORKING_SET_VERSION } : {}),
         guidance_tools: guidanceTools,
         ...(retainedFrom === undefined ? {} : { retained_from: retainedFrom }),
       });

package/src/runtime/open-image.ts

@@ -0,0 +1,42 @@
+/**
+ * Open a stored image in the system viewer (docs/tasks/feat-tui-image-full-size.md).
+ *
+ * Blobs are content-addressed and have no extension, and viewers recognise a
+ * file by its extension, so the verified bytes are copied once to
+ * `<tmpdir>/xeno-images/<sha256>.<ext>` and that file is opened. The name is
+ * the hash: opening the same picture again reuses the file, and a file under
+ * that name can only hold those bytes because we never write it twice.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getBlobBytes } from "../store/blobs.ts";
+import { MAX_IMAGE_SOURCE_BYTES } from "../core/image-limits.ts";
+import { detectSupportedImageMimeType } from "../vendor/pi-rich/mime.ts";
+
+const EXTENSIONS: Readonly<Record<string, string>> = { "image/png": "png", "image/jpeg": "jpg", "image/gif": "gif", "image/webp": "webp", "image/bmp": "bmp" };
+
+/** The platform's "open with the default application" command. */
+function launchViewer(path: string): void {
+  Bun.spawn([process.platform === "darwin" ? "open" : "xdg-open", path], { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+}
+
+/** Opens the blob; returns why it could not, or null once the viewer was started. */
+export async function openImageFile(blobDir: string, sha256: string,
+  options: { dir?: string; launch?: (path: string) => void } = {}): Promise<string | null> {
+  let bytes: Uint8Array | null;
+  try { bytes = await getBlobBytes(blobDir, sha256, MAX_IMAGE_SOURCE_BYTES); } catch (error) { return `Cannot open image: ${error instanceof Error ? error.message : String(error)}`; }
+  if (bytes === null) return "Cannot open image: it is no longer in the session's blob store";
+  const mime = detectSupportedImageMimeType(bytes);
+  const extension = mime === null ? undefined : EXTENSIONS[mime];
+  if (extension === undefined) return "Cannot open image: unrecognised image format";
+  const dir = options.dir ?? join(tmpdir(), "xeno-images");
+  const path = join(dir, `${sha256}.${extension}`);
+  try {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // `wx`: an existing file is a previous copy of these same bytes.
+    await writeFile(path, bytes, { flag: "wx", mode: 0o600 }).catch((error: NodeJS.ErrnoException) => { if (error.code !== "EEXIST") throw error; });
+    (options.launch ?? launchViewer)(path);
+  } catch (error) { return `Cannot open image: ${error instanceof Error ? error.message : String(error)}`; }
+  return null;
+}