@visual-z/xeno 0.8.1 → 0.8.3

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";
@@ -42,8 +43,9 @@ import {
 } from "../core/context-policy.ts";
 import { retainedContext, selectRecentContext } from "../core/context-window.ts";
 import { advanceStall, emptyStallState, stallDecision, DEFAULT_STALL_LIMIT, type StallState } from "../core/stall.ts";
+import { questionRequest, validateQuestionReply } from "../core/question.ts";
 import { DEFAULT_OUTPUT_RECOVERY_LIMIT, isCompleteResponse, incompleteToolText, knownUnexecutedTool, outputRecoveryNotice, validateOutputRecoveryLimit } from "../core/response-recovery.ts";
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { pendingToolCalls } from "../core/execution.ts";
 import { declaredToolNames, recordedDeclarations } from "../core/tool-discovery.ts";
@@ -75,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 {
@@ -91,7 +97,7 @@ import { FailedResponseError, type Provider, type Turn, type StreamDelta } from
 import { putBlob, getBlob } from "../store/blobs.ts";
 import { hydrateProcessReceipts } from "../store/process-receipts.ts";
 import { readNodeHistory } from "../store/restore.ts";
-import { createWorktree, removeWorktree } from "../store/worktree.ts";
+import { createWorktree, listWorktrees, mainWorktree, persistentWorktreeParent, removeWorktree } from "../store/worktree.ts";
 import {
   parseNote, matchGate, branchTools, finishToolResult, prepareNormalizedTool, presentObservation, toolDefinition, modelToolSchema, adviceTools,
   BRANCH_TOOL_NAMES, WRITING_BRANCH_TOOL_NAMES,
@@ -113,6 +119,7 @@ import { changedPaths, invertFileChanges, sameVersion, type CheckpointEvent, typ
 import type { GitCheckpoint } from "../store/git-checkpoints.ts";
 import { readEditableFile, preflightChanges, applyFileChanges } from "../store/file-checkpoints.ts";
 import { planCheckpointRestore } from "../store/checkpoint-history.ts";
+import { configDir } from "../store/config.ts";
 
 /** Ids and timestamps come from here so the loop stays the only impure part. */
 export interface Clock {
@@ -175,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 }
@@ -212,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). */
@@ -379,7 +393,15 @@ 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>();
@@ -393,6 +415,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);
@@ -402,6 +426,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.
@@ -415,6 +440,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);
@@ -494,6 +521,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);
@@ -603,6 +631,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");
@@ -745,8 +774,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. " +
@@ -754,9 +793,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. */
@@ -886,6 +928,7 @@ export class Session {
       updated_at: this.clock.now(),
       workspace: this.config.tools.root,
       context_ref: contextRef ?? await this.persistContext(),
+      xeno_version: XENO_VERSION,
     });
   }
 
@@ -898,6 +941,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);
@@ -909,6 +956,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);
@@ -921,6 +971,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] : []);
@@ -996,7 +1059,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> {
@@ -1252,6 +1315,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;
@@ -1266,9 +1330,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
@@ -1337,8 +1406,8 @@ export class Session {
           return;
         }
 
-        if (yield* this.checkStall()) {
-          yield { kind: "done", reason: await report("no-progress allowance exhausted", turn), outcome: executionOutcome("stalled") };
+        if (yield* this.checkStall(request, signal)) {
+          yield { kind: "done", reason: await report("repeated tool cycle without new evidence", turn), outcome: executionOutcome("stalled") };
           return;
         }
         if (phase === "finalize" && !supportsToolDisabling(this.provider.config.spec.api)) {
@@ -1400,7 +1469,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;
@@ -1633,6 +1704,7 @@ export class Session {
         // granularity the research warns against.
         const declarationNode = this.state.node;
         if (!signal?.aborted && await this.applyDiscoveredTools()) yield { kind: "cut", node: declarationNode, reason: "model_checkpoint" };
+        if (this.pendingRoot !== null) await this.applyPendingRoot();
         if (this.pendingAdoption !== null) await this.adoptPendingBranch();
 
         // Between complete exchanges is the only safe place to cut.
@@ -1732,8 +1804,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 });
@@ -1744,13 +1817,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;
+    }
   }
 
   /**
@@ -1824,7 +1909,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 }) } });
@@ -1931,7 +2019,7 @@ export class Session {
     const forkSkill = call.name === "read" && typeof call.input === "object" && call.input !== null ? this.config.skills?.find(skill =>
       skill.context === "fork" && skill.filePath === resolve(ctx.root, String((call.input as Record<string, unknown>)["path"]))) : undefined;
     const discovery = call.name === DISCOVERY_TOOL_NAME && ctx.extensions?.get(call.name) === DISCOVERY_TOOL;
-    if (!forkSkill && !discovery && !["note", "branch", "resolve", "history", "target"].includes(call.name)) return prepareNormalizedTool(ctx, call.name, call.input);
+    if (!forkSkill && !discovery && !["note", "branch", "resolve", "history", "target", "worktree"].includes(call.name)) return prepareNormalizedTool(ctx, call.name, call.input);
     const branchIndex = forkSkill || call.name === "branch" ? nextBranch() : 0;
     return prepareNormalizedTool(ctx, call.name, call.input, async () => {
       if (discovery) return async () => searchDeferredTools(ctx, call.input as Record<string, unknown>, this.allowedNames());
@@ -1950,6 +2038,7 @@ export class Session {
         return { ...prepared.out, ...(prepared.annotation ? { annotation: prepared.annotation } : {}) };
       };
       if (call.name === "resolve") return () => this.runResolve(call.input);
+      if (call.name === "worktree") return () => this.runWorktree(call.input, ctx.pathRoot);
       if (forkSkill?.disableModelInvocation) return async () => ({ ok: false, content: "this skill requires explicit user invocation" });
       if (forkSkill) await this.recordSkill(forkSkill, "fork", "model");
       const task = this.state.events.findLast(event => event.t === "user");
@@ -2086,6 +2175,7 @@ export class Session {
     );
     branch.state.node = node;
     branch.state.nextNode = this.state.nextNode;
+    branch.secrets = this.secrets;
     if (skill) await branch.recordSkill(skill, "fork", skillOrigin);
     this.children.set(node, branch);
     yield { kind: "branch_start", node, reason: purpose, at: Date.now() };
@@ -2163,6 +2253,50 @@ export class Session {
     };
   }
 
+  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;
+    // A branch already runs in its own checkout and never owns the parent's root.
+    if ((this.config.branchDepth ?? 0) > 0) return { content: "worktree is unavailable inside a branch; the branch already has its own checkout", ok: false };
+    if (this.pendingRoot !== null) return { content: "one worktree switch per tool round; the previous one applies after this round", ok: false };
+    const main = await mainWorktree(root);
+    if (main === null) return { content: `${root} is not inside a git repository, so there is nothing to make a worktree of`, ok: false };
+    const outside = (path: string) => pathRoot !== undefined && relative(pathRoot, path).startsWith("..");
+    if (args["action"] === "exit") {
+      if (main === root) return { content: `already in the main checkout ${main}; nothing to exit`, ok: false };
+      if (outside(main)) return { content: `the main checkout ${main} is outside --path-root ${pathRoot}`, ok: false };
+      const branch = (await listWorktrees(main)).find(wt => wt.path === root)?.branch ?? null;
+      this.pendingRoot = main;
+      return { ok: true, content: [`main ${main}`, `kept ${root}${branch ? ` on ${branch.replace(/^refs\/heads\//, "")}` : ""}`,
+        "The session root moves to the main checkout after this tool round. Nothing was merged or deleted; " +
+        `remove the worktree yourself with \`git worktree remove ${root}\` once its branch is merged or no longer needed.`].join("\n") };
+    }
+    if (args["action"] !== "enter") return { content: "worktree action must be enter or exit", ok: false };
+    const name = typeof args["name"] === "string" ? args["name"] : "";
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name) || name.includes("..")) {
+      return { content: "worktree name must be 1-64 letters, digits, dot, dash or underscore, starting with a letter or digit", ok: false };
+    }
+    const parent = persistentWorktreeParent(configDir(), main);
+    if (outside(parent)) return { content: `xeno's worktree directory ${parent} is outside --path-root ${pathRoot}`, ok: false };
+    const created = await createWorktree(root, name, { location: { parent, leaf: name }, includeChanges: args["include_changes"] === true });
+    if (!created.ok) return { content: `refused: ${created.error}`, ok: false };
+    this.pendingRoot = created.path;
+    return { ok: true, content: [`worktree ${created.path}`, `branch ${created.branch}`, `from ${created.snapshot.head}`,
+      `The session root moves there after this tool round; relative paths, edits and commands then resolve in it. ` +
+      `The working directory in the system prompt still names ${root}. ` +
+      (args["include_changes"] === true ? "It starts from the current uncommitted files." : "It starts from HEAD; uncommitted files in the main checkout were not copied.")].join("\n"),
+      data: { path: created.path, branch: created.branch, head: created.snapshot.head } };
+  }
+
+  private async applyPendingRoot(): Promise<void> {
+    const root = this.pendingRoot;
+    this.pendingRoot = null;
+    if (root === null) return;
+    this.config.tools.root = root;
+    this.installWorkspace();
+    await this.saveCursor();
+  }
+
   private async runResolve(input: unknown): Promise<ToolResult> {
     const args = (typeof input === "object" && input !== null ? input : {}) as Record<string, unknown>;
     const node = Number(args["node"]);
@@ -2555,7 +2689,14 @@ export class Session {
     return recoveryReview(this.recovery, tools);
   }
 
-  private async *checkStall(): AsyncGenerator<LoopEvent, boolean> {
+  /**
+   * S.8: a repeated cycle is pointed out to the model once; the next one is
+   * the user's call when a question client can answer -- continue, stop, or
+   * new instructions -- and ends the request only without one (headless) or
+   * when the user stops it. The answer is recorded as an event, never kept
+   * as loop state: a continue is a `stall` guidance, instructions are steering.
+   */
+  private async *checkStall(request: string, signal?: AbortSignal): AsyncGenerator<LoopEvent, boolean> {
     const limit = this.config.stallLimit ?? DEFAULT_STALL_LIMIT;
     if (limit === 0) return false;
     if (this.stall === null) {
@@ -2564,13 +2705,42 @@ export class Session {
       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.unproductive} total tool exchanges without new evidence (${decision.consecutive} consecutive; ${decision.failures} failed receipts; ${decision.emptyWaits} empty waits); change the approach or provide new input` };
-      return true;
+    if (decision.cycle === null) return false;
+    const pattern = decision.cycle === 1 ? "the same tool call" : `a cycle of ${decision.cycle} tool calls`;
+    const facts = `${pattern} repeated ${decision.repeats} times without new evidence (${decision.failures} failed receipts; ${decision.emptyWaits} empty waits)`;
+    if (decision.warn) {
+      await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "stall", sources: [],
+        text: `Harness: ${facts}. Change the method, run a meaningful check, or give the final result with unresolved limits. If the pattern repeats again, the user decides whether the request continues.` });
+      return false;
     }
-    if (decision.warn) await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "stall", sources: [],
-      text: `Harness: ${decision.unproductive} total tool exchanges without new evidence or fresh verification (${decision.consecutive} consecutive; ${decision.failures} failed receipts; ${decision.emptyWaits} empty waits). Change the method, run a meaningful check, or give the final result with unresolved limits. The harness will stop at ${limit} total unproductive exchanges. Novel observations reset the streak, not the spent allowance. Notes and repeated observations do not count as progress.` });
-    return false;
+    const answer = await this.askAboutCycle(facts, signal);
+    if (answer?.kind === "continue") {
+      await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "stall", sources: [],
+        text: `Harness: the user reviewed this (${facts}) and chose to continue. Do not repeat the same calls expecting a different result; change the method or finish with the result and its limits.` });
+      return false;
+    }
+    if (answer?.kind === "steer") {
+      await this.record({ t: "user", id: this.clock.nextId(), at: this.clock.now(), request, text: answer.text });
+      return false;
+    }
+    yield { kind: "stop_and_ask", reason: `${facts}; change the approach or provide new input` };
+    return true;
+  }
+
+  /** Undefined means nobody answered: no question client (headless), cancelled, or an invalid reply. */
+  private async askAboutCycle(facts: string, signal?: AbortSignal): Promise<{ kind: "continue" } | { kind: "stop" } | { kind: "steer"; text: string } | undefined> {
+    const slot = this.config.tools.questionSlot, adapter = slot?.current, turn = slot?.activeTurn;
+    if (!adapter || !turn || signal?.aborted) return undefined;
+    const request = questionRequest(turn, `stall-${this.clock.nextId()}`, [{ id: "stall", header: "Repeated tool calls",
+      question: `The agent ${facts}. Continue, stop, or type instructions for it?`, multiple: false, custom: true,
+      options: [{ id: "continue", label: "Continue", description: "Let the agent keep working; it is told to change its method." },
+        { id: "stop", label: "Stop", description: "End this request; the log and evidence stay." }] }]);
+    try {
+      const reply = validateQuestionReply(request, await adapter(structuredClone(request), signal ?? new AbortController().signal));
+      const [answer] = reply.answers, text = answer?.text?.trim();
+      if (text) return { kind: "steer", text };
+      return answer?.choices[0] === "continue" ? { kind: "continue" } : answer?.choices[0] === "stop" ? { kind: "stop" } : undefined;
+    } catch { return undefined; }
   }
 
   /** A steering signal releases only the wait; cancellation owns process termination. */
@@ -2795,7 +2965,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;
+}

package/src/runtime/openai-responses.ts

@@ -23,7 +23,10 @@ import { imageData } from "./images.ts";
 import { assertNever } from "../core/exhaustive.ts";
 import type { OnDelta, Provider, ProviderConfig, ToolSchema, Turn } from "./provider.ts";
 import { pushSse, HttpError, StreamError } from "./openai.ts";
-import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
+import { withRetry, retryLabel, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
+import { ConnectionReuse } from "./connection-reuse.ts";
+import { watchIdle, type IdleWatch } from "./stream-idle.ts";
+
 import type { ProviderSendOptions } from "./provider-tool-policy.ts";
 
 /** What this adapter parks in a thinking block's raw: the reasoning item, whole. */
@@ -254,25 +257,30 @@ export class OpenAIResponsesProvider implements Provider {
   readonly config: ProviderConfig;
   private readonly apiKey: string;
   private readonly fetchImpl: typeof fetch;
+  private readonly connections = new ConnectionReuse();
   private readonly retry: RetryPolicy;
   private readonly onRetry: ((attempt: number, delayMs: number, error: unknown) => void) | undefined;
+  private readonly streamIdleMs: number | undefined;
 
   constructor(config: ProviderConfig, apiKey: string, options: {
     fetchImpl?: typeof fetch; retry?: RetryPolicy; onRetry?: (attempt: number, delayMs: number, error: unknown) => void;
+    /** Silence after which one attempt is abandoned; tests shorten it (stream-idle.ts). */
+    streamIdleMs?: number;
   } = {}) {
     this.config = config;
     this.apiKey = apiKey;
     this.fetchImpl = options.fetchImpl ?? fetch;
     this.retry = options.retry ?? DEFAULT_RETRY;
     this.onRetry = options.onRetry;
+    this.streamIdleMs = options.streamIdleMs;
   }
 
   send(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta, options?: ProviderSendOptions): Promise<Turn> {
-    return withRetry(() => this.attempt(frozen, messages, node, signal, onDelta, options), this.retry, undefined,
-      (attempt, delayMs, error) => { onDelta?.({ kind: "discard" }); onDelta?.({ kind: "retry", attempt, delayMs }); this.onRetry?.(attempt, delayMs, error); }, signal);
+    return withRetry(() => watchIdle(signal, this.streamIdleMs, idle => this.attempt(frozen, messages, node, idle, onDelta, options)).catch((error: unknown) => { this.connections.note(error); throw error; }), this.retry, undefined,
+      (attempt, delayMs, error) => { onDelta?.({ kind: "discard" }); onDelta?.({ kind: "retry", attempt, delayMs, max: this.retry.maxRetries, reason: retryLabel(error) }); this.onRetry?.(attempt, delayMs, error); }, signal);
   }
 
-  private async attempt(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta, options?: ProviderSendOptions): Promise<Turn> {
+  private async attempt(frozen: FrozenPrefix, messages: readonly Message[], node: number, idle: IdleWatch, onDelta?: OnDelta, options?: ProviderSendOptions): Promise<Turn> {
     const started = Date.now();
     const baseUrl = this.config.spec.baseUrl;
     if (baseUrl === undefined) throw new Error(`model ${this.config.spec.id} has no baseUrl to send to`);
@@ -282,8 +290,8 @@ export class OpenAIResponsesProvider implements Provider {
       body: JSON.stringify({ ...buildResponsesRequest(this.config, frozen, messages), stream: true,
         ...(options?.toolUse === "disabled" ? { tool_choice: "none" } : {}) }),
     };
-    if (signal !== undefined) init.signal = signal;
-    const response = await this.fetchImpl(`${baseUrl.replace(/\/$/, "")}/responses`, init);
+    init.signal = idle.signal;
+    const response = await this.fetchImpl(`${baseUrl.replace(/\/$/, "")}/responses`, this.connections.init(init));
     if (!response.ok) {
       const text = await response.text();
       let detail = text.slice(0, 200);
@@ -291,6 +299,6 @@ export class OpenAIResponsesProvider implements Provider {
       throw new HttpError(response.status, response.headers, `HTTP ${response.status}: ${detail}`);
     }
     if (response.body === null) throw new Error(`${baseUrl} returned a streaming 200 with no body`);
-    return readResponsesSse(response.body, node, started, onDelta);
+    return readResponsesSse(idle.body(response.body), node, started, onDelta);
   }
 }