@visual-z/xeno 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # xeno changelog
 
+## 0.8.2 — 2026-10-11
+
+The stall watchdog no longer stops work that is merely long:
+- A run is treated as stuck only when it repeats the same tool call, or the same cycle of up to five calls, three times without learning anything new. Re-reading files, rerunning a test after an edit, a failing test whose output changes, and waiting on a running process never count.
+- The first time, the model is told to change its method. If the cycle comes back, an interactive session asks you: Continue, Stop, or type instructions for the agent. Without anyone to ask (headless), the request still ends as stalled.
+- The old request-wide allowance of twelve exchanges without new evidence is gone. It stopped a long, finished task right after its final answer.
+
+The input box after a turn:
+- A finished turn reads `✓ Turn finished · 32m 34s` in the success colour, with how long the turn ran. The time stays until the next turn starts.
+- A turn the harness stopped reads `■ Stopped · no progress` (or request limit, context budget, output limit, time limit) in the warning colour, instead of `Awaiting input`. `Awaiting input` now means a question is waiting for you. A failed turn reads `✗ Failed` in the error colour.
+- A stop report names the tools that failed (`Failed tools: exec_command ×2, edit ×1`) instead of listing receipt ids, and says when the model had already given a final reply before the stop.
+
+Tools:
+- Where `rg` is missing, interactive sessions install a pinned ripgrep (14.1.1, checked against its SHA-256) into `~/.xeno/bin` in the background and add it to the end of the command PATH. Nothing is downloaded with `--offline`, in CI or from a source checkout. The environment tells the model whether `rg` is available.
+- A new `worktree` tool lets the model create an isolated Git worktree under `~/.xeno/worktrees`, on a branch `xeno/<name>`, and move the session into it; leaving returns to the main checkout and keeps the worktree and branch. Resumed sessions add the tool after their existing tools.
+- `exec_command` and `write_stdin` accept Codex's `max_output_tokens`. It lowers the inline preview only, and near spellings such as `max_output_chars` are pointed at the right name.
+- `grep`, `rg`, `diff`, `cmp` and `test` exiting 1 as the last command is read as their answer (no match, files differ), not a failure. The receipt keeps the real exit code.
+- A leading `(?i)` in a grep pattern means the same with or without ripgrep.
+
+Fixes:
+- A new segment no longer sends the model to `history` first when every user message is already in its handoff. Before, the first tool call of almost every session was that read.
+- The completion check says that a verification command counts only when run on its own, without redirects, pipes, `$()`, `;` or `&&`. The read it asks for no longer counts toward the stall watchdog.
+- Refusing an edit under `.git` or `.xeno` now says it is a fixed rule, instead of asking for a policy change that no setting can make.
+
 ## 0.8.1 — 2026-10-11
 
 The sidebar now follows your goal:

package/docs/install.md

@@ -144,6 +144,31 @@ check described above is a separate action):
 - the run is not the interactive app: `-p`, `--mode json`, `--export`, `--list-models`, `models --refresh`, package and `config` commands, `--version`
 - xeno runs from a checkout: its package root is not under `node_modules`, or has a `.git` (`bun src/apps/cli.ts`, `bun run agent`, `bun link`)
 
+## ripgrep
+
+Agents reach for `rg` in shell commands, and xeno's grep tool is faster with
+it. When neither `PATH` nor `~/.xeno/bin` has one, the interactive app
+installs ripgrep 14.1.1 into `~/.xeno/bin/rg` in the background:
+
+- **Only that build.** The archive comes from the ripgrep GitHub release and
+  must match a sha256 pinned in xeno (`src/core/ripgrep-release.ts`).
+  Anything else is discarded before extraction; only the `rg` executable is
+  unpacked.
+- **Yours wins.** `~/.xeno/bin` is appended to the end of the PATH of tool
+  commands, so an `rg` you install yourself is used instead.
+- **What the model is told.** The session's environment section says whether
+  `rg` exists in the shell at session start. A copy that finishes
+  downloading during the first session appears in the next one's line, but
+  shell commands can use it immediately.
+- **When not.** The same conditions as background update checks, except the
+  update settings: `--offline` / `XENO_OFFLINE`, `CI` /
+  `CONTINUOUS_INTEGRATION`, a non-interactive run, or running from a
+  checkout. `XENO_NO_TOOL_INSTALL` turns off only this download. Quitting
+  cancels it.
+
+Platforms: macOS arm64 and x64, Linux x64 (static musl) and arm64 (glibc).
+Elsewhere grep uses its built-in TypeScript search.
+
 ## Credentials
 
 Resolution order, first match wins:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visual-z/xeno",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "license": "UNLICENSED",
   "type": "module",
   "description": "Segmented append-only agent log with pure context and handoff projections",

package/src/apps/cli.ts

@@ -13,7 +13,7 @@
  */
 
 import {
-  parseArgs, startup, readPipedStdin, mergePrintPrompt, isInteractiveSession, printCliHelp,
+  parseArgs, startup, readPipedStdin, mergePrintPrompt, isInteractiveSession, printCliHelp, provisionToolsInBackground,
 } from "./startup.ts";
 import { createStartupInput } from "./startup-input.ts";
 import { runPrompt, runRepl } from "./shell.ts";
@@ -37,6 +37,7 @@ const args = parseArgs(process.argv.slice(serverMode || acpMode || reviewMode ?
 if (serverMode || acpMode) { args.print = true; args.mode = "json"; if (args.prompt) throw Error("protocol servers receive prompts through their client"); }
 if (reviewMode) args.print = true;
 let closeControl: (() => Promise<void>) | undefined;
+let stopToolInstall = (): void => {};
 const input = createStartupInput({ interactive: isInteractiveSession(args) && !args.packageCommand && !args.version && !args.exportFile && !args.listModels && !args.modelsCommand });
 process.once("exit", input.restore);
 try {
@@ -60,6 +61,7 @@ try {
     catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = controller.signal.aborted ? 130 : 1; }
     finally { process.off("SIGINT", cancel); process.off("SIGTERM", cancel); }
   } else {
+    stopToolInstall = provisionToolsInBackground(args);
     const app = await startup(args, input);
     if (args.controlSocket) closeControl = await listenControl(args.controlSocket, () => sessionControl(app.session));
     if (serverMode) {
@@ -90,6 +92,7 @@ try {
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1;
 } finally {
+  stopToolInstall();
   await closeControl?.();
   process.off("exit", input.restore);
   input.restore();

package/src/apps/startup.ts

@@ -29,6 +29,10 @@ import {
   resolveCredential, envLabel, storedIsOAuth,
   type AuthFile, type ResolveEffects, type Resolved, describeMissingCredential } from "../runtime/auth.ts";
 import { authPath, configDir, readJsonFile } from "../store/config.ts";
+import { findRipgrep, provisionRipgrep } from "../store/tool-binaries.ts";
+import { packageLocation } from "../store/update-cache.ts";
+import { installKind } from "../core/update-check.ts";
+import { toolInstallAllowed } from "../core/ripgrep-release.ts";
 import { loadUiResources, loadTextResources, type UiResources } from "../store/resources.ts";
 import { discoverResources, type ResourceIndex } from "../store/resource-index.ts";
 import { pickProjectTrust, pickStartupSession, runResourceConfig } from "./ui/standalone.ts";
@@ -108,9 +112,29 @@ export function sessionEnvironment(workspace: string): SessionEnvironment {
     cwd: workspace,
     date: `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`,
     git,
+    ripgrep: findRipgrep(configDir()) !== null,
   };
 }
 
+/**
+ * Fills the rg gap in the background for interactive sessions only: scripts,
+ * protocol servers and test subprocesses must not reach the network on their
+ * own. Failure is silent because grep keeps its TypeScript engine; the next
+ * session's environment line reports what is actually there. The returned
+ * stop aborts the download, so quitting never waits for it.
+ */
+export function provisionToolsInBackground(args: Args): () => void {
+  const location = packageLocation();
+  if (!isInteractiveSession(args) || !toolInstallAllowed({ env: process.env, offline: args.offline === true, install: installKind(location.root, location.git) })) return () => {};
+  const controller = new AbortController();
+  void provisionRipgrep({ configDir: configDir(), signal: controller.signal, fetchBytes: async (url, signal) => {
+    const response = await fetch(url, { ...(signal ? { signal } : {}), redirect: "follow" });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return new Uint8Array(await response.arrayBuffer());
+  } }).catch(() => { /* grep falls back to its own engine */ });
+  return () => controller.abort();
+}
+
 /**
  * Session policy a CLI coding session differs from a benchmark run in.
  * Benchmarks construct their own SessionConfig and keep the core defaults.
@@ -366,8 +390,9 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
   let updateExtensions = false;
   const args: Args = {
     cliFlags: argv.filter(value => value.startsWith("-")),
-    // No default request cap (S.6 item 1): the stall watchdog ends a run that
-    // stops producing evidence; --max-turns or an agent budget sets a hard cap.
+    // No default request cap (S.6 item 1): the stall watchdog catches a run
+    // repeating a cycle without evidence, and asks the user when one can answer
+    // (S.8); --max-turns or an agent budget sets a hard cap.
     workspace: process.cwd(), logDir: "", maxTurns: Infinity, prompt: "",
     // Overridable so a node boundary can be forced in a short session --
     // otherwise cutting is only reachable after tens of thousands of tokens,

package/src/core/activity-status.ts

@@ -14,10 +14,19 @@ export interface ActivityFacts {
 }
 export interface ActivityStatus { readonly state: ProgramStatus["state"]; readonly label: string; readonly detail: string; readonly queued: number }
 
+const STOP_CAUSE: Partial<Record<ExecutionOutcome["reason"], string>> = {
+  stalled: "no progress", no_progress: "no progress", max_turns: "request limit", context_budget: "context budget",
+  output_limit: "output limit", timeout: "time limit",
+};
+
 export function activityStatus(facts: ActivityFacts): ActivityStatus {
   const status = programStatus(facts), queued = Math.max(0, Math.floor(facts.queued));
   const view = (label: string, detail = status.msg ?? ""): ActivityStatus => ({ state: status.state, label, detail, queued });
-  if (status.state === "blocked") return view(status.kind === "auth" ? "Sign in required" : status.kind === "permission" ? "Awaiting approval" : "Awaiting input");
+  // A harness stop is not a question: saying "Awaiting input" left the user
+  // guessing what to answer (fix-finished-turn-status). The OSC state stays blocked.
+  if (!facts.running && !facts.waiting && facts.outcome?.status === "stopped") return view("Stopped", STOP_CAUSE[facts.outcome.reason] ?? facts.outcome.reason.replaceAll("_", " "));
+  if (status.state === "blocked") return view(status.kind === "auth" ? "Sign in required" : status.kind === "permission" ? "Awaiting approval"
+    : !facts.waiting && facts.goal === "awaiting_human" ? "Awaiting review" : "Awaiting input");
   if (status.state === "error") return view("Failed");
   if (!facts.running) return view(status.state === "done" ? "Turn finished" : facts.outcome?.status === "cancelled" ? "Cancelled" : "Ready");
   if (facts.retry) return view("Retrying", `attempt ${facts.retry.attempt} · ${Math.max(0, Math.ceil(facts.retry.seconds))}s`);

package/src/core/command-contract.ts

@@ -10,10 +10,18 @@ export function commandArgv(command: string): string[] {
   return ["bash", "-o", "pipefail", "-lc", command];
 }
 
-/** Preserve inherited values except documented noninteractive defaults; never mutate the host. */
-export function commandEnvironment(base: Readonly<Record<string, string | undefined>>): Record<string, string> {
+/**
+ * Preserve inherited values except documented noninteractive defaults; never mutate the host.
+ *
+ * `appendPath` is xeno's own tool directory (store/tool-binaries.ts). It goes
+ * last, so anything the user installed wins and xeno only fills a gap.
+ */
+export function commandEnvironment(base: Readonly<Record<string, string | undefined>>, appendPath?: string): Record<string, string> {
   const env: Record<string, string> = {};
   for (const [key, value] of Object.entries(base)) if (value !== undefined) env[key] = value;
+  if (appendPath !== undefined && appendPath.length > 0 && !(env["PATH"] ?? "").split(":").includes(appendPath)) {
+    env["PATH"] = env["PATH"] ? `${env["PATH"]}:${appendPath}` : appendPath;
+  }
   Object.assign(env, {
     TERM: "dumb", PAGER: "cat", GIT_PAGER: "cat", NO_COLOR: "1",
     GIT_TERMINAL_PROMPT: "0", DEBIAN_FRONTEND: "noninteractive",
@@ -22,14 +30,80 @@ export function commandEnvironment(base: Readonly<Record<string, string | undefi
   return env;
 }
 
+/**
+ * Codex's `max_output_tokens` as an inline byte budget for one call. It can
+ * only lower the session ceiling: full output is still captured and
+ * recoverable, so this shapes the preview, never the receipt.
+ *
+ * Assumed, not measured: 4 bytes per token rounds the ASCII estimate in
+ * tokens.ts (about 3.6) up, so the model never gets less than it asked for.
+ * The 1 KiB floor keeps room for the header and recovery hint (about 300
+ * bytes); below it a preview shows almost no output and forces a re-read.
+ */
+export const OUTPUT_BYTES_PER_TOKEN = 4;
+export const MIN_OUTPUT_BYTES = 1_024;
+export function outputBytesForTokens(tokens: unknown, ceiling: number): number {
+  if (typeof tokens !== "number" || !Number.isFinite(tokens) || tokens <= 0) return ceiling;
+  return Math.min(ceiling, Math.max(MIN_OUTPUT_BYTES, Math.floor(tokens) * OUTPUT_BYTES_PER_TOKEN));
+}
+
 /** Model seconds and host milliseconds meet once; a yield is never a command deadline. */
 export function commandTimeout(requestedSeconds: number | undefined, defaultMs: number, maximumMs = defaultMs): number {
   return Math.min(requestedSeconds === undefined ? defaultMs : requestedSeconds * 1000, maximumMs);
 }
 
+/**
+ * Programs whose exit 1 is an answer rather than a fault (POSIX: grep's 1 is
+ * "no match" and >1 an error; diff and cmp use 1 for "differ"; test for
+ * false). Reporting them as failures tells the model to inspect and retry an
+ * answer it already holds -- the same reading Claude Code's command semantics
+ * give these programs.
+ */
+const NEGATIVE_ANSWERS: Readonly<Record<string, string>> = {
+  grep: "no match", egrep: "no match", fgrep: "no match", rg: "no match",
+  diff: "files differ", cmp: "files differ", test: "condition false", "[": "condition false",
+};
+
+/**
+ * What exit 1 of the command's final simple command means, or null.
+ *
+ * Only the last segment after a top-level `;`, newline, `||` or `|` is read.
+ * After `&&` the 1 may come from the command that short-circuited, so it is
+ * not classified. Under pipefail an earlier pipeline stage can also set the
+ * status; the exit is kept in the receipt either way, and the label states
+ * the program's meaning rather than claiming success. Anything this scanner
+ * cannot read with certainty -- unbalanced quotes, subshells, compound
+ * statements, substitutions -- yields null.
+ */
+export function negativeAnswer(command: string, exit: number): string | null {
+  if (exit !== 1) return null;
+  let quote: "'" | "\"" | null = null, start = 0, separator = "";
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i]!;
+    if (quote !== null) {
+      if (c === "\\" && quote === "\"") i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "\\") { i++; continue; }
+    if (c === "'" || c === "\"") { quote = c; continue; }
+    if (c === "`" || c === "(" || c === ")" || c === "{" || c === "}" || (c === "$" && command[i + 1] === "(")) return null;
+    const two = command.slice(i, i + 2);
+    if (two === "&&" || two === "||") { separator = two; start = i + 2; i++; continue; }
+    if (c === ";" || c === "\n" || c === "|") { separator = c; start = i + 1; continue; }
+    if (c === "&" && command[i + 1] !== ">" && command[i - 1] !== ">") return null;
+  }
+  if (quote !== null || separator === "&&") return null;
+  const words = command.slice(start).trim().split(/\s+/).filter(word => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(word));
+  const program = (words[0] ?? "").replace(/^.*\//, "");
+  if (program === "git") return words[1] === "grep" ? "no match" : null;
+  return Object.hasOwn(NEGATIVE_ANSWERS, program) ? NEGATIVE_ANSWERS[program]! : null;
+}
+
 /** A trap can exit zero after cancellation: successful exit alone does not erase the stop. */
-export function commandCompletion(exit: number, stopped?: "cancelled" | "timeout", cleanup?: ToolDiagnostic) {
-  return { ok: stopped === undefined && exit === 0 && cleanup === undefined,
-    outcome: executionOutcome(stopped ?? (exit === 0 && cleanup === undefined ? "tool_completed" : "tool_failed")),
+export function commandCompletion(exit: number, stopped?: "cancelled" | "timeout", cleanup?: ToolDiagnostic, command?: string) {
+  const answered = exit === 0 || command !== undefined && negativeAnswer(command, exit) !== null;
+  return { ok: stopped === undefined && answered && cleanup === undefined,
+    outcome: executionOutcome(stopped ?? (answered && cleanup === undefined ? "tool_completed" : "tool_failed")),
     ...(cleanup ? { warnings: [cleanup] } : {}) };
 }

package/src/core/completion-review.ts

@@ -69,7 +69,7 @@ export function requestCompletion(state: RequestState, remainingRequests: number
   if (state.used_tools && text.length === 0) gaps.push("the final reply is empty");
   // Strict verification counts only configured gates (O.11); say so, since a successful `cat` would otherwise look like a check.
   if (freshCheck && freshCheck.status !== "pass") gaps.push(freshCheck.gate_only
-    ? "files were changed but no configured verification gate (a test, typecheck, lint, build or check command) has passed since the last edit; reading or printing files does not count"
+    ? "files were changed but no configured verification gate (a test, typecheck, lint, build or check command) has passed since the last edit; reading or printing files does not count, and a gate counts only when run as its own plain command, without redirects, pipes, $(), ; or &&"
     : "files were changed but no command has succeeded since the last edit");
   if (acceptance?.status === "needs_work") gaps.push(`declared acceptance criteria need evidence: ${[
     ...missingCommands.map(item => `${item.id}=${item.status}`),

package/src/core/environment.ts

@@ -19,6 +19,12 @@ export interface SessionEnvironment {
   /** Local calendar date, YYYY-MM-DD. */
   date: string;
   git: boolean;
+  /**
+   * Whether `rg` resolves in tool shells at session start. Models reach for
+   * it by habit; without this line a missing one costs an exit-127 request.
+   * Optional so environments recorded before it existed still render.
+   */
+  ripgrep?: boolean;
 }
 
 export function environmentSection(env: SessionEnvironment): string {
@@ -29,6 +35,7 @@ export function environmentSection(env: SessionEnvironment): string {
     `- Working directory: ${env.cwd}`,
     `- Date: ${env.date}`,
     `- Git repository: ${env.git ? "yes" : "no"}`,
+    ...(env.ripgrep === undefined ? [] : [`- ripgrep (rg) in the shell: ${env.ripgrep ? "yes" : "no — use the grep and find tools"}`]),
   ].join("\n");
 }
 

package/src/core/history.ts

@@ -2,6 +2,7 @@
 import { emitHandoff, type Handoff } from "./handoff.ts";
 import { estimateTokens } from "./tokens.ts";
 import { recoveryWorkingSet } from "./working-set.ts";
+import { recoveryInstructions } from "./prompt-policy.ts";
 import type { RecoveryNodes } from "./recovery-sources.ts";
 
 // A carried handoff must leave room for another segment's work. This budget is
@@ -122,6 +123,11 @@ export function boundRecoveryHandoff(full: Handoff, nodes: RecoveryNodes, budget
   const legacy = boundHandoff(full, budget);
   const view = recoveryWorkingSet(full, nodes, budget * .4, tools);
   if (!view) return legacy;
-  try { return boundHandoff({ ...full, working_set: view }, budget); }
+  let carried: Handoff;
+  try { carried = boundHandoff({ ...full, working_set: view }, budget); }
   catch (error) { if (error instanceof RangeError) return legacy; throw error; }
+  // Whether the user turns survived bounding is known only now. The inline
+  // wording is shorter, so swapping it in cannot push the handoff over budget.
+  const inline = tools?.includes("history") && carried.user_turns_truncated === undefined && (carried.history?.sections["user_turns"]?.offset ?? 0) === 0;
+  return inline && carried.working_set ? { ...carried, working_set: { ...carried.working_set, recovery: recoveryInstructions(tools!, true) } } : carried;
 }

package/src/core/permissions.ts

@@ -45,9 +45,10 @@ export type ToolSource = "builtin" | "extension";
 
 /** Task capabilities are frozen once at session creation (O.7); not permissions. */
 export const TOOL_PROFILES = {
-  coding: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note"],
-  // An explicit preset preserves the measured legacy ten-tool coding contract.
-  foundation: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note", "question", "apply_patch", "diff", "webfetch", "websearch", "format", "lsp"],
+  // worktree joined the measured ten (2026-10-11, feat-worktree-tool): without
+  // it a model needing isolation had no checkout it was allowed to edit.
+  coding: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note", "worktree"],
+  foundation: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note", "worktree", "question", "apply_patch", "diff", "webfetch", "websearch", "format", "lsp"],
   readonly: ["read", "grep", "find", "history", "note"],
   research: ["read", "grep", "find", "history", "note", "branch", "resolve"],
   data: ["read", "grep", "find", "history", "note", "query"],

package/src/core/prompt-policy.ts

@@ -23,9 +23,16 @@ export function toolDescription(description: string, guidance: readonly ToolGuid
   return [description, ...guidance.filter(item => item.requires.every(name => tools.includes(name))).map(item => item.text)].join(" ");
 }
 
-export function recoveryInstructions(tools: readonly string[]): string {
+/**
+ * `usersInline`: the carried `user_turns` hold every user message verbatim.
+ * Telling the model to page them anyway costs a guaranteed first-call read
+ * that returns what it already has -- or an empty page after a model switch
+ * on a fresh session (Horizyn mv3nsske-x50u, fix-recovery-inline-users).
+ */
+export function recoveryInstructions(tools: readonly string[], usersInline = false): string {
   return (tools.includes("history")
-    ? "Read original user messages before continuing: history(node=source.node,recovery=users,offset=0). Other pages: failures, environment, next_actions; event=ID reads one original. history(work_id=ID) recovers work. "
+    ? (usersInline ? "User messages are verbatim in user_turns. Other history(node=source.node,recovery=...) pages: failures, environment, next_actions; " : "Read original user messages before continuing: history(node=source.node,recovery=users,offset=0). Other pages: failures, environment, next_actions; ") +
+      "event=ID reads one original. history(work_id=ID) recovers work. "
     : "Original user messages and evidence remain at the source references. The original-source recovery capability is unavailable; state any resulting evidence gap instead of guessing. ") +
     "Abandoned messages are cancelled; annotations are not user instructions. Observations are historical: recheck resource, host and current permissions before acting.";
 }

package/src/core/regex-dialect.ts

@@ -0,0 +1,25 @@
+/**
+ * Brings the ripgrep regex dialect to JS RegExp where the two differ in
+ * spelling, not meaning.
+ *
+ * grep runs ripgrep when it is on PATH and a TypeScript walk otherwise, and
+ * the model writes for ripgrep (Rust regex), where a leading `(?i)` is the
+ * usual way to ask for case-insensitivity. JS rejects that spelling but
+ * accepts the scoped form `(?i:...)`, so a leading global group is rewritten
+ * into a scoped group around the rest of the pattern. Without this the same
+ * call works or fails depending on whether rg happens to be installed.
+ *
+ * Only the leading form and only flags JS modifiers support (i, m, s) are
+ * rewritten; anything else is passed through so RegExp reports it as it is.
+ */
+const LEADING_FLAGS = /^\(\?([ims]+)\)/;
+
+export function jsPatternFromRipgrep(pattern: string): string {
+  const match = LEADING_FLAGS.exec(pattern);
+  if (match === null) return pattern;
+  const flags = match[1]!;
+  // A repeated flag is a SyntaxError inside a modifier group; ripgrep
+  // tolerates it, so duplicates are dropped rather than surfaced.
+  const unique = [...new Set(flags)].join("");
+  return `(?${unique}:${pattern.slice(match[0].length)})`;
+}

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 };
 }