@visual-z/xeno 0.8.0 → 0.8.2

package/src/core/response-recovery.ts

@@ -1,5 +1,5 @@
 /** N.12: a returned response is durable evidence, not necessarily a completed action. */
-import type { GuidanceEvent, LogEvent } from "./events.ts";
+import type { AssistantBlock, GuidanceEvent, LogEvent } from "./events.ts";
 import { currentRequestEvents } from "./request-state.ts";
 
 // One appended attempt is an operational assumption, not a measured optimum.
@@ -15,6 +15,18 @@ export function isCompleteResponse(reason: string | null | undefined): boolean {
   return reason !== undefined && reason !== null && ["stop", "end_turn", "stop_sequence", "tool_calls", "tool_use"].includes(reason);
 }
 
+/**
+ * A stop that asks for tool execution must carry a tool call. One that does not
+ * is a malformed provider response, not the model's answer: taken as a final
+ * reply it ends the request with outcome unknown and nothing on screen
+ * (session mv28chr8-oc3x, an Anthropic-compatible gateway returning
+ * `stop_reason: tool_use` with no content). Adapters reject it inside their
+ * retry so the loop only sees a coherent turn or a definite failure.
+ */
+export function isToolStopWithoutCall(stopReason: string | null | undefined, blocks: readonly AssistantBlock[]): boolean {
+  return (stopReason === "tool_use" || stopReason === "tool_calls") && !blocks.some(block => block.type === "tool_use");
+}
+
 export function isOutputLimit(reason: string | null | undefined): boolean {
   return reason === "length" || reason === "max_tokens";
 }

package/src/core/ripgrep-release.ts

@@ -0,0 +1,64 @@
+/**
+ * The one ripgrep build xeno will install, per platform.
+ *
+ * Models write `rg` in shell commands because the harnesses they were trained
+ * in ship it (Claude Code bundles it; Pi downloads it on first use). On a
+ * machine without it every such command exits 127 and costs a request. xeno
+ * installs it only when the user has none, and only this exact archive:
+ * running a binary fetched from the network needs proof that it is the one
+ * reviewed, which a pinned digest gives and "latest" (Pi's choice) does not.
+ *
+ * Digests are the upstream release's published `.sha256` files for 14.1.1;
+ * the aarch64-apple-darwin archive was also downloaded and hashed locally on
+ * 2026-10-11 and matched. Upgrading means changing this table and releasing.
+ */
+import { truthy } from "./update-check.ts";
+
+export const RIPGREP_VERSION = "14.1.1";
+
+export interface RipgrepAsset {
+  readonly url: string;
+  readonly sha256: string;
+  /** Archive member holding the executable; nothing else is extracted. */
+  readonly member: string;
+}
+
+const DIGESTS: Readonly<Record<string, string>> = {
+  "aarch64-apple-darwin": "24ad76777745fbff131c8fbc466742b011f925bfa4fffa2ded6def23b5b937be",
+  "x86_64-apple-darwin": "fc87e78f7cb3fea12d69072e7ef3b21509754717b746368fd40d88963630e2b3",
+  // musl is static, so it runs on glibc and musl distributions alike.
+  "x86_64-unknown-linux-musl": "4cf9f2741e6c465ffdb7c26f38056a59e2a2544b51f7cc128ef28337eeae4d8e",
+  // 14.1.1 publishes no aarch64 musl build; this one needs glibc.
+  "aarch64-unknown-linux-gnu": "c827481c4ff4ea10c9dc7a4022c8de5db34a5737cb74484d62eb94a95841ab2f",
+};
+
+function target(platform: string, arch: string): string | null {
+  if (platform === "darwin") return arch === "arm64" ? "aarch64-apple-darwin" : arch === "x64" ? "x86_64-apple-darwin" : null;
+  if (platform === "linux") return arch === "arm64" ? "aarch64-unknown-linux-gnu" : arch === "x64" ? "x86_64-unknown-linux-musl" : null;
+  return null;
+}
+
+/** Null for platforms without a pinned build: those keep the TypeScript search. */
+export function ripgrepAsset(platform: string, arch: string): RipgrepAsset | null {
+  const triple = target(platform, arch);
+  if (triple === null) return null;
+  const name = `ripgrep-${RIPGREP_VERSION}-${triple}`;
+  return {
+    url: `https://github.com/BurntSushi/ripgrep/releases/download/${RIPGREP_VERSION}/${name}.tar.gz`,
+    sha256: DIGESTS[triple]!,
+    member: `${name}/rg`,
+  };
+}
+
+/**
+ * Whether xeno may fetch the binary on its own, in the background.
+ *
+ * The same occasions the update check stays off the network (core/update-check.ts):
+ * offline, CI, and a source checkout -- the last is also what keeps test
+ * subprocesses, which run the CLI from this repository, from downloading.
+ * XENO_NO_TOOL_INSTALL opts out explicitly; the user's own rg makes it moot.
+ */
+export function toolInstallAllowed(input: { env: Readonly<Record<string, string | undefined>>; offline: boolean; install: string }): boolean {
+  const on = (name: string) => truthy(input.env[name]);
+  return !input.offline && input.install !== "checkout" && !on("XENO_OFFLINE") && !on("XENO_NO_TOOL_INSTALL") && !on("CI") && !on("CONTINUOUS_INTEGRATION");
+}

package/src/core/stall.ts

@@ -6,23 +6,60 @@ import { deriveProgress, type ProgressEvidence } from "./progress.ts";
 import { isProcessReceipt } from "./process-receipt.ts";
 import { canonicalValue } from "./continuation.ts";
 
-// A conservative hypothesis: enough room to change method after a mid-budget
-// notice, while bounding repeated paid requests. Not a task-quality classifier.
+/**
+ * S.8: the watchdog is now an on/off switch -- 0 disables it, any other
+ * allowed value enables it. Sessions persist this field (S.3); a stored 12
+ * still means "on" and is never reread as "twelve repeats".
+ */
 export const DEFAULT_STALL_LIMIT = 12;
+/**
+ * How many times a cycle must repeat. A hypothesis, not measured: OpenCode's
+ * doom loop, Cline and Roo use 3; OpenHands 4 counting the first, novel,
+ * observation; Gemini 5. Lower asks too often, higher pays for more repeats.
+ */
+export const CYCLE_REPEATS = 3;
+/** Longest cycle recognised; Gemini CLI's bound, and the user's (S.8). */
+export const MAX_CYCLE = 5;
+
+export interface StallExchange { readonly signature: string; readonly progressed: boolean }
 export interface StallState {
   evidence: readonly ProgressEvidence[];
   pending: readonly LogEvent[];
   pendingNode: number;
-  consecutive: number;
-  unproductive: number;
+  /** The request's latest exchanges, oldest first, at most MAX_CYCLE × CYCLE_REPEATS. */
+  recent: readonly StallExchange[];
   failures: number;
   emptyWaits: number;
-  warned: boolean;
+  /** A cycle was already pointed out to the model; the next one goes to the user. */
+  nudged: boolean;
   /** The previous exchange's tool calls, canonical; empty after real user input. */
   previous: string;
+  /**
+   * A completion review just asked the model to re-read the request and
+   * verify. Its answer is the harness's own request, so that one exchange
+   * stays out of the cycle window (fix-review-induced-stall).
+   */
+  reviewed: boolean;
 }
 export function emptyStallState(): StallState {
-  return { evidence: [], pending: [], pendingNode: 0, consecutive: 0, unproductive: 0, failures: 0, emptyWaits: 0, warned: false, previous: "" };
+  return { evidence: [], pending: [], pendingNode: 0, recent: [], failures: 0, emptyWaits: 0, nudged: false, previous: "", reviewed: false };
+}
+
+/**
+ * The shortest period k <= MAX_CYCLE such that the last k × repeats exchanges
+ * are one k-call cycle repeated, none of which brought new evidence -- or null.
+ * Distinct calls that each tell nothing new are not a loop: that is reading
+ * and re-checking, which a cumulative allowance wrongly punished (S.8).
+ */
+export function repeatedCycle(recent: readonly StallExchange[], repeats = CYCLE_REPEATS): number | null {
+  for (let k = 1; k <= MAX_CYCLE; k++) {
+    const n = k * repeats;
+    if (recent.length < n) return null;
+    const window = recent.slice(-n);
+    if (window.some(item => item.progressed)) continue;
+    if (window.every((item, i) => i < k || item.signature === window[i - k]!.signature)) return k;
+  }
+  return null;
 }
 
 /** Name and arguments of every call, order-independent: what the model asked for, not what came back. */
@@ -38,7 +75,7 @@ export function finishStallExchange(state: StallState): StallState {
   const progress = deriveProgress(state.evidence, state.pending, state.pendingNode, checks);
   const signature = exchangeSignature(assistant);
   const waits = new Set(assistant.blocks.flatMap(block => block.type === "tool_use" && block.name === "write_stdin" ? [block.call_id] : []));
-  // S.6 item 2: with no request cap this ledger is the only backstop. Asking
+  // S.6 item 2: asking
   // for exactly what the previous exchange asked for is a rerun on an
   // unchanged premise, so output that differs only by timing (a failing test's
   // "[123ms]") is not news. Reads and edits are content-addressed and keep
@@ -51,9 +88,12 @@ export function finishStallExchange(state: StallState): StallState {
         (event.effect?.kind !== "command" && !isProcessReceipt(event.data))), state.pendingNode, checks).progressed
     : progress.progressed;
   const results = state.pending.filter(event => event.t === "tool_result");
-  return { ...state, pending: [], evidence: progress.evidence, previous: signature,
-    consecutive: rerun ? 0 : state.consecutive + 1,
-    unproductive: state.unproductive + (rerun ? 0 : 1),
+  // Waiting on a process that is still running is not another attempt: its
+  // own timeout bounds it and the user can interrupt (S.8). Only exchanges
+  // that try something enter the cycle window.
+  const waiting = results.length > 0 && results.every(result => waits.has(result.call_id) && isProcessReceipt(result.data) && result.data.running === true);
+  const recent = state.reviewed || waiting ? state.recent : [...state.recent, { signature, progressed: rerun }].slice(-MAX_CYCLE * CYCLE_REPEATS);
+  return { ...state, pending: [], evidence: progress.evidence, previous: signature, reviewed: false, recent,
     failures: state.failures + results.filter(result => !result.ok).length,
     emptyWaits: state.emptyWaits + results.filter(result => waits.has(result.call_id) && isProcessReceipt(result.data) &&
       result.data.running === true && result.data.cursor !== undefined && result.data.cursor.start === result.data.cursor.end).length };
@@ -63,11 +103,16 @@ export function finishStallExchange(state: StallState): StallState {
 export function advanceStall(state: StallState, entries: readonly { node: number; event: LogEvent }[]): StallState {
   let result = state;
   for (const { node, event } of entries) {
-    if (event.t === "assistant" || event.t === "user" || event.t === "cut" || (event.t === "guidance" && event.reason === "stall")) {
+    const review = event.t === "guidance" && event.reason === "completion_review";
+    const nudge = event.t === "guidance" && event.reason === "stall";
+    if (event.t === "assistant" || event.t === "user" || event.t === "cut" || review || nudge) {
       result = finishStallExchange(result);
-      if (event.t === "user") result = { ...result, pending: [], consecutive: 0, unproductive: 0, failures: 0, emptyWaits: 0, warned: false, previous: "" };
+      if (review) result = { ...result, reviewed: true };
+      // A nudge, or the user's "continue", starts a fresh window: only a new
+      // full cycle after it counts, never the one already reported.
+      if (nudge) result = { ...result, nudged: true, recent: [] };
+      if (event.t === "user") result = { ...result, pending: [], recent: [], failures: 0, emptyWaits: 0, nudged: false, previous: "", reviewed: false };
       if (event.t === "assistant") result = { ...result, pending: [event], pendingNode: node };
-      if (event.t === "guidance") result = { ...result, warned: true };
     } else if (result.pending.length > 0) result = { ...result, pending: [...result.pending, event] };
   }
   return result;
@@ -75,9 +120,9 @@ export function advanceStall(state: StallState, entries: readonly { node: number
 export function stallDecision(state: StallState, limit: number) {
   if (!Number.isSafeInteger(limit) || limit < 0 || limit === 1) throw new RangeError("stall limit must be zero or an integer of at least two");
   const current = finishStallExchange(state);
-  // Reuse the existing conservative allowance. Novelty resets a streak, not
-  // the request's spent no-progress budget (research Q.26); failures are diagnostics.
-  return { consecutive: current.consecutive, unproductive: current.unproductive, failures: current.failures, emptyWaits: current.emptyWaits,
-    stop: limit > 0 && (current.consecutive >= limit || current.unproductive >= limit),
-    warn: limit > 0 && current.unproductive >= Math.max(1, Math.floor(limit / 2)) && !current.warned };
+  const cycle = limit > 0 ? repeatedCycle(current.recent) : null;
+  // S.8: the first cycle is pointed out to the model; a second goes to the
+  // user when one can answer, and otherwise ends the request.
+  return { cycle, repeats: CYCLE_REPEATS, failures: current.failures, emptyWaits: current.emptyWaits,
+    warn: cycle !== null && !current.nudged, stop: cycle !== null && current.nudged };
 }

package/src/core/stop-report.ts

@@ -19,8 +19,28 @@ export function stopReport(events: readonly LogEvent[], requests: number, limit:
   return [
     `Stopped: ${exitLine(cause)} (${limit === Infinity ? requests : `${requests}/${limit}`} model requests).`,
     `Recorded evidence: ${results.length} tool receipts; ${exits} successful command exits; ${failures.length} failed tool receipts. Task completion is not verified by this stop.`,
-    ...(failures.length ? [`Inspect failed receipts: ${failures.slice(-3).map(event => exitLine(event.id, 80)).join(", ")}.`] : []),
+    ...(failures.length ? [`Failed tools: ${failedTools(current, failures)}.`] : []),
+    ...(finalReplyGiven(current) ? ["A final reply was given before this stop; read it above — this stop does not mark it wrong."] : []),
     ...(running.length ? [`Last observed running: ${running.slice(0, 3).join(", ")}${running.length > 3 ? ` (+${running.length - 3})` : ""}; inspect the process receipt before replaying a command.`] : []),
     "Next: inspect /state or the recorded tool output, then provide a focused continuation; completed commands should not be replayed just to recover their output.",
   ].join("\n");
 }
+
+/**
+ * The user reads this line; no command looks a receipt up by id, so ids told
+ * them nothing (fix-stop-report-readable). Tool names say where it went wrong.
+ */
+function failedTools(events: readonly LogEvent[], failures: readonly Extract<LogEvent, { t: "tool_result" }>[]): string {
+  const names = new Map<string, string>();
+  for (const event of events) if (event.t === "assistant") for (const block of event.blocks) if (block.type === "tool_use") names.set(block.call_id, block.name);
+  const counts = new Map<string, number>();
+  for (const failure of failures) { const name = names.get(failure.call_id) ?? "unknown"; counts.set(name, (counts.get(name) ?? 0) + 1); }
+  const ranked = [...counts].sort(([a, x], [b, y]) => y - x || (a < b ? -1 : a > b ? 1 : 0));
+  return ranked.slice(0, 3).map(([name, count]) => `${name} ×${count}`).join(", ") + (ranked.length > 3 ? ` (+${ranked.length - 3} more)` : "");
+}
+
+/** A stop after the model already answered must not read as "the task failed". */
+function finalReplyGiven(events: readonly LogEvent[]): boolean {
+  return events.some(event => event.t === "assistant" && !event.blocks.some(block => block.type === "tool_use") &&
+    event.blocks.some(block => block.type === "text" && block.text.trim().length > 0));
+}

package/src/core/tool-contract.ts

@@ -86,6 +86,8 @@ const SYNONYMS: Readonly<Record<string, readonly string[]>> = {
   cmd: ["command"], script: ["command"],
   text: ["content"], contents: ["content"], old_str: ["old_string"], new_str: ["new_string"],
   query: ["pattern"], regex: ["pattern"], timeout_ms: ["timeout"], offset: ["start"], limit: ["end", "limit"],
+  // Different units from max_output_tokens, so a hint rather than a silent conversion.
+  max_output_chars: ["max_output_tokens"], max_output_bytes: ["max_output_tokens"], max_tokens: ["max_output_tokens"],
 };
 
 /** The candidate nearest to `name`, when it is near enough to be the likely intent. */

package/src/core/tool-failure.ts

@@ -21,26 +21,39 @@ const guidance: Record<ToolDiagnostic["code"], string> = {
   command_failed: "Use the actual exit and output to diagnose the command; a nonzero exit alone does not identify its cause.",
 };
 
+/**
+ * The refusal for `.git` and `.xeno` paths. It is a fixed rule protecting the
+ * session's own evidence, not a user policy, so the generic denial ("a user
+ * policy change is required") would send the model to ask for a setting that
+ * does not exist -- which is what a real session did before this text.
+ */
+export const STATE_PATH_GUIDANCE = "This path is repository or xeno session state, which edit tools never change; no setting changes this. " +
+  "To work in an isolated checkout, use the worktree tool instead of creating one under .git or .xeno.";
+const STATE_PATH_GUIDANCE_WITHOUT_WORKTREE = "This path is repository or xeno session state, which edit tools never change; no setting changes this. " +
+  "Edit files outside .git and .xeno.";
+
 export function failureDiagnostic(code: ToolDiagnostic["code"], message: string, facts: FailureFacts,
-  extra: Pick<ToolDiagnostic, "recover" | "example"> = {}): ToolDiagnostic {
+  extra: Pick<ToolDiagnostic, "recover" | "example" | "next"> = {}): ToolDiagnostic {
   const retry = code === "permission_denied" || code === "cancelled" ? "never"
     : code === "unknown_effect" || facts.effects === "possible" ? "after_inspection"
     : code === "transient" ? "backoff" : "after_change";
-  return { code, message, ...facts, retry, next: guidance[code], ...(code === "permission_denied" ? {} : extra) };
+  const { next = guidance[code], ...rest } = extra;
+  return { code, message, ...facts, retry, next, ...(code === "permission_denied" ? {} : rest) };
 }
 
 /** R10: only new advice is scoped; execution facts and historical records are never rewritten. */
 export function scopeFailureGuidance(diagnostic: ToolDiagnostic, tools: readonly string[], recoverAllowed = true): ToolDiagnostic {
   const { recover, ...facts } = diagnostic;
   const next = diagnostic.execution !== undefined && diagnostic.code === "environment_missing" && !tools.includes("environment")
-    ? { next: "Verify the working directory and required executable in the current executor using permitted observations. If the needed capability is unavailable, report that evidence gap before retrying." } : {};
+    ? { next: "Verify the working directory and required executable in the current executor using permitted observations. If the needed capability is unavailable, report that evidence gap before retrying." }
+    : diagnostic.next === STATE_PATH_GUIDANCE && !tools.includes("worktree") ? { next: STATE_PATH_GUIDANCE_WITHOUT_WORKTREE } : {};
   return { ...facts, ...next, ...(recover && recoverAllowed && tools.includes(recover.tool) && diagnostic.code !== "permission_denied" ? { recover } : {}) };
 }
 
 /** Runtime and store throw only facts they own; the outer boundary must retain these facts. */
 export class ToolFault extends Error {
   readonly diagnostic: ToolDiagnostic;
-  constructor(code: ToolDiagnostic["code"], message: string, facts: FailureFacts, extra: Pick<ToolDiagnostic, "recover"> = {}) {
+  constructor(code: ToolDiagnostic["code"], message: string, facts: FailureFacts, extra: Pick<ToolDiagnostic, "recover" | "next"> = {}) {
     super(message); this.name = "ToolFault";
     this.diagnostic = failureDiagnostic(code, message, facts, extra);
   }

package/src/core/update-check.ts

@@ -46,7 +46,8 @@ export interface UpdatePlan {
   readonly notice?: string;
 }
 
-function truthy(value: string | undefined): boolean {
+/** Shared by every background network opt-out, so one variable means the same everywhere. */
+export function truthy(value: string | undefined): boolean {
   return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
 }
 

package/src/runtime/exec-sessions.ts

@@ -23,6 +23,8 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { commandArgv, commandEnvironment, COMMAND_TERMINATION_GRACE_MS } from "../core/command-contract.ts";
 import { archiveObservation, type ArchivedObservation } from "../store/observations.ts";
+import { configDir } from "../store/config.ts";
+import { xenoBinDir } from "../store/tool-binaries.ts";
 import { ToolFault, NOT_STARTED } from "../core/tool-failure.ts";
 import { processReceipt, retainProcessReceipts, type ProcessReceipt, type ProcessSource } from "../core/process-receipt.ts";
 import type { CommandArtifactObserver } from "./command-artifacts.ts";
@@ -170,7 +172,7 @@ export async function startSession(input: {
   await mkdir(input.spoolDir, { recursive: true });
   const spoolPath = join(input.spoolDir, `.${randomUUID()}.session`);
   const spool = await open(spoolPath, "w+", 0o600);
-  const env = commandEnvironment(process.env);
+  const env = commandEnvironment(process.env, xenoBinDir(configDir()));
   let resolveExit!: () => void;
   const exited = new Promise<void>((resolve) => { resolveExit = resolve; });
   const session = {

package/src/runtime/loop.ts

@@ -42,8 +42,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";
@@ -91,7 +92,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 +114,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 {
@@ -380,6 +382,8 @@ export class Session {
   private recovery: RecoveryState | null = null;
   private processWake = new AbortController();
   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>();
@@ -1337,8 +1341,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)) {
@@ -1633,6 +1637,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.
@@ -1931,7 +1936,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 +1955,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");
@@ -2163,6 +2169,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 +2605,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 +2621,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. */

package/src/runtime/openai.ts

@@ -23,7 +23,7 @@ import type { Message, ContentBlock, FrozenPrefix } from "../core/project.ts";
 import { imageData } from "./images.ts";
 import type { AssistantBlock } from "../core/events.ts";
 import { assertNever } from "../core/exhaustive.ts";
-import type { Provider, ProviderConfig, Turn, ToolSchema, OnDelta } from "./provider.ts";
+import { coherentTurn, type Provider, type ProviderConfig, type Turn, type ToolSchema, type OnDelta } from "./provider.ts";
 import { DEFAULT_COMPAT, type Compat, type Effort, type ModelSpec } from "./model.ts";
 import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
 import type { ProviderSendOptions } from "./provider-tool-policy.ts";
@@ -502,7 +502,7 @@ export class OpenAICompletionsProvider implements Provider {
     }
 
     const assembled = await readCompletionsSse(response.body, onDelta);
-    return parseResponse(assembled, node, Date.now() - started);
+    return coherentTurn(parseResponse(assembled, node, Date.now() - started), assembled.usage !== undefined);
   }
 }
 

package/src/runtime/pi-provider.ts

@@ -20,7 +20,7 @@ import { providerRequest } from "./provider-request.ts";
 import { grokVersionHint } from "./oauth.ts";
 import type { ResolveEffects } from "./auth.ts";
 import { imageData } from "./images.ts";
-import { FailedResponseError, type OnDelta, type Provider, type ProviderConfig, type ToolSchema, type Turn } from "./provider.ts";
+import { coherentTurn, FailedResponseError, type OnDelta, type Provider, type ProviderConfig, type ToolSchema, type Turn } from "./provider.ts";
 import { DEFAULT_RETRY, withRetry, type RetryPolicy } from "./retry.ts";
 import { HttpError, StreamError } from "./openai.ts";
 import type { UsageSample } from "./usage.ts";
@@ -392,7 +392,7 @@ export class PiProvider implements Provider {
     if (identityErrors.length) throw new ProviderIntegrityError(identityErrors, hasKnownUsage ? usage : undefined);
     // The SDK has already classified native STOP/end_turn/toolUse/length values. The loop consumes
     // xeno's closed completion vocabulary, never a raw native spelling that could skip tool execution.
-    return { blocks: piBlocks(completed, originalArguments.values), stopReason: completed.stopReason === "length" ? "max_tokens" : completed.stopReason === "toolUse" ? "tool_use" : "end_turn",
-      usage };
+    return coherentTurn({ blocks: piBlocks(completed, originalArguments.values), stopReason: completed.stopReason === "length" ? "max_tokens" : completed.stopReason === "toolUse" ? "tool_use" : "end_turn",
+      usage }, hasKnownUsage);
   }
 }