@visual-z/xeno 0.8.1 → 0.8.2

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/tools.ts

@@ -33,7 +33,7 @@ import {
 import { recoverProcessReceipt, type ProcessReceipt, type latestProcessReceipt } from "../core/process-receipt.ts";
 import { observeCommand, observeArgvCommand } from "../store/command.ts";
 import { executionOutcome, type ExecutionOutcome } from "../core/outcome.ts";
-import { commandCompletion, commandTimeout } from "../core/command-contract.ts";
+import { commandCompletion, commandTimeout, negativeAnswer, outputBytesForTokens } from "../core/command-contract.ts";
 import { linesWithin, previewReadObservation, readObservationText, type ObservationReceipt } from "../core/read-observation.ts";
 import { checkFilePrecondition, isFileDigest, isFileReadDescriptor, type FileReadDescriptor, type FilePrecondition } from "../core/file-precondition.ts";
 import { previewSearchObservation, searchObservationText } from "../core/search-observation.ts";
@@ -571,6 +571,34 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
       required: ["node", "resolution"],
     },
   },
+  {
+    /**
+     * The model's way into an isolated checkout of this repository.
+     *
+     * Edits are confined to the session root, so isolation the model builds
+     * itself with `git worktree add` is unusable: outside the root is refused,
+     * and inside `.xeno` is session state. This creates the checkout where
+     * xeno keeps them and moves the root after the tool round, the way an
+     * adopted branch does; the cursor records the root, so resume stays there.
+     */
+    name: "worktree",
+    access: "state", execution: "exclusive", branch: "none",
+    example: { action: "enter", name: "fix-parser" },
+    description:
+      "enter: create a git worktree of this repository on a new branch xeno/<name> from HEAD, kept under xeno's config directory, " +
+      "and move this session's root there after the current tool round, so later edits and commands run in the isolated checkout. " +
+      "Use it when the shared working tree has changes by others or must stay untouched. include_changes copies the current uncommitted files. " +
+      "exit: move the root back to the repository's main checkout. The worktree and its branch are kept; nothing is merged or deleted.",
+    input_schema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["enter", "exit"] },
+        name: { type: "string", description: "enter: letters, digits, dot, dash or underscore; becomes the branch xeno/<name>" },
+        include_changes: { type: "boolean", description: "enter: start from the current uncommitted files instead of HEAD; default false" },
+      },
+      required: ["action"],
+    },
+  },
   {
     name: "bash",
     example: { command: "bun test", workdir: ".", timeout: 300 },
@@ -631,6 +659,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
         workdir: { type: "string", description: "Directory to run in; default the workspace root" },
         tty: { type: "boolean", description: "Run in a pseudo-terminal; default false" },
         yield_time_ms: { type: "integer", description: "Milliseconds to wait before returning; default 10000; effective range 100-30000, values outside are clamped" },
+        max_output_tokens: { type: "integer", minimum: 1, description: "Lower this call's inline output preview to about this many tokens; full output stays recoverable" },
         timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Seconds before the session is killed; default 300" },
       },
       required: ["cmd"],
@@ -651,6 +680,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
         session_id: { type: "integer", minimum: 1 },
         chars: { type: "string", description: "Characters to write; empty to poll" },
         yield_time_ms: { type: "integer", description: "Bounded wait when sending input or using low-level polling; effective range 100-30000, values outside are clamped; agent empty waits are owned until an observation changes" },
+        max_output_tokens: { type: "integer", minimum: 1, description: "Lower this call's inline output preview to about this many tokens; full output stays recoverable" },
       },
       required: ["session_id"],
     },
@@ -663,7 +693,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     description:
       "Search file contents for a regex. Stays inside the workspace, does " +
       "not follow symlinks, and skips .git, node_modules and .xeno. Uses " +
-      "ripgrep when it is already on PATH, otherwise a TypeScript walk. " +
+      "ripgrep when it is on PATH or in xeno's bin directory, otherwise a TypeScript walk. " +
       "Reports scan completeness separately from preview truncation. Long matches and omitted results remain in an immutable history artifact; use its sha256 and byte offset to recover them. Unknown or partial coverage cannot prove absence.",
     input_schema: {
       type: "object",
@@ -1040,7 +1070,7 @@ async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promi
   const observation = await commandFingerprint(ctx);
   const header = commandHeader({ exit, wallMs: captured.wallMs, timeoutMs,
     ...(requestedMs !== undefined ? { requestedMs } : {}),
-    ...(captured.stopped ? { stopped: captured.stopped } : {}) });
+    ...(captured.stopped ? { stopped: captured.stopped } : {}) }) + answerLabel(command, exit, captured.stopped);
   const artifactSummary = commandArtifactSummary(artifacts);
 
   return {
@@ -1049,7 +1079,7 @@ async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promi
     content: header + artifactSummary + "\n" + observationView(captured,
       ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, captured.prefixBytes, adviceTools(ctx)),
     content_ref: captured.ref,
-    ...commandCompletion(exit, captured.stopped, captured.cleanup),
+    ...commandCompletion(exit, captured.stopped, captured.cleanup, command),
     data: { exit, output: captured.ref, ...(captured.cleanup ? { cleanup: "unknown" } : {}), ...(artifacts ? { artifacts } : {}) },
     effect: {
       kind: "command",
@@ -1090,7 +1120,8 @@ async function toolExec(ctx: ToolContext, input: Record<string, unknown>): Promi
     ...(ctx.execOwner === undefined ? {} : { owner: ctx.execOwner }) });
   if ("error" in session) return failure("execution_failed", session.error);
   const wait = yieldWait(input["yield_time_ms"]);
-  return sessionResult(ctx, command, timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, wait.ms, "", ctx.signal), wait.note);
+  const view = { ...ctx, maxOutputBytes: outputBytesForTokens(input["max_output_tokens"], ctx.maxOutputBytes) };
+  return sessionResult(view, command, timeoutMs, await pollSession(session, outputStore, view.maxOutputBytes, wait.ms, "", ctx.signal), wait.note);
 }
 
 async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
@@ -1109,7 +1140,8 @@ async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>):
   }
   const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
   const wait = yieldWait(input["yield_time_ms"]);
-  return sessionResult(ctx, session.command, session.timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, wait.ms, chars, ctx.signal,
+  const view = { ...ctx, maxOutputBytes: outputBytesForTokens(input["max_output_tokens"], ctx.maxOutputBytes) };
+  return sessionResult(view, session.command, session.timeoutMs, await pollSession(session, outputStore, view.maxOutputBytes, wait.ms, chars, ctx.signal,
     ctx.processWait && chars.length === 0 ? { wake: ctx.processWait.wake(), onWaiting: active => ctx.onProcessWait?.(id, active) } : undefined), wait.note);
 }
 
@@ -1139,7 +1171,7 @@ export async function sessionResult(ctx: ToolContext, command: string, timeoutMs
     ? `running · session ${id} · ${(taken.wallMs / 1000).toFixed(1)}s elapsed; ` + (adviceTools(ctx).includes("write_stdin")
       ? `poll or send input with write_stdin(session_id=${id})`
       : "process-control capability unavailable; execution remains unfinished; do not replay")
-    : commandHeader({ exit, wallMs: taken.wallMs, timeoutMs, managed: true, ...(taken.stopped ? { stopped: taken.stopped } : {}) }) + ` · session ${id} closed`;
+    : commandHeader({ exit, wallMs: taken.wallMs, timeoutMs, managed: true, ...(taken.stopped ? { stopped: taken.stopped } : {}) }) + ` · session ${id} closed` + answerLabel(command, exit, taken.stopped);
   const header = shown + waitNote;
   const artifactSummary = commandArtifactSummary(taken.receipt.artifacts);
   const content = header + artifactSummary + "\n" + observationView(stored, ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, 0, adviceTools(ctx));
@@ -1150,7 +1182,7 @@ export async function sessionResult(ctx: ToolContext, command: string, timeoutMs
   const gate = matchGate(ctx, command);
   const observation = await commandFingerprint(ctx);
   return {
-    ...commandCompletion(exit, taken.stopped),
+    ...commandCompletion(exit, taken.stopped, undefined, command),
     content, content_ref: stored.ref, content_sha256: stored.ref.sha256,
     data: taken.receipt, ...(warnings.length ? { warnings } : {}),
     effect: { kind: "command", cmd: command, exit, ...(gate !== undefined ? { gate } : {}),
@@ -1158,6 +1190,12 @@ export async function sessionResult(ctx: ToolContext, command: string, timeoutMs
   };
 }
 
+/** The program's own meaning of exit 1 (grep: no match), appended to the header; the exit itself stays. */
+function answerLabel(command: string, exit: number, stopped?: "cancelled" | "timeout"): string {
+  const meaning = stopped === undefined ? negativeAnswer(command, exit) : null;
+  return meaning === null ? "" : ` · ${meaning}`;
+}
+
 const utf8Length = (text: string) => new TextEncoder().encode(text).length;
 
 /**

package/src/store/command.ts

@@ -1,5 +1,7 @@
 /** O.1: own the process group, preserve partial observations, and drain before returning. */
 import { captureCommandObservation } from "./observations.ts";
+import { configDir } from "./config.ts";
+import { xenoBinDir } from "./tool-binaries.ts";
 import { commandArgv, commandEnvironment, COMMAND_TERMINATION_GRACE_MS } from "../core/command-contract.ts";
 import { ToolFault, NOT_STARTED, failureDiagnostic } from "../core/tool-failure.ts";
 
@@ -44,7 +46,7 @@ async function executeCaptured(input: CommandCaptureInput, argv: string[], nativ
       cwd: input.cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe", detached: true,
       // Preserve the trusted native API's inherited environment; shell tools
       // retain their explicit noninteractive policy and login-shell startup.
-      env: native ? process.env : commandEnvironment(process.env),
+      env: native ? process.env : commandEnvironment(process.env, xenoBinDir(configDir())),
     }); } catch (error) {
       const os = (error as { code?: string }).code;
       throw new ToolFault(os === "ENOENT" || os === "ENOTDIR" ? "environment_missing" : os === "EACCES" || os === "EPERM" ? "permission_denied" : "execution_failed", String(error), NOT_STARTED);

package/src/store/file-checkpoints.ts

@@ -4,12 +4,15 @@ import { resolve, relative, dirname, join, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { blobAddress, putBlob, getBlobBytes, verifyBlob } from "./blobs.ts";
 import { sameVersion, changedPaths, type FileVersion, type FileChanges } from "../core/checkpoints.ts";
-import { ToolFault, NOT_STARTED, READ_ATTEMPTED, failureFromError } from "../core/tool-failure.ts";
+import { ToolFault, NOT_STARTED, READ_ATTEMPTED, STATE_PATH_GUIDANCE, failureFromError } from "../core/tool-failure.ts";
 
 export async function editablePath(root: string, path: string): Promise<string> {
   const base = resolve(root), absolute = resolve(base, path), rel = relative(base, absolute);
-  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || resolve(rel) === rel ||
-      rel.split(sep).some(part => part === ".git" || part === ".xeno")) throw new ToolFault("permission_denied", `unsafe file checkpoint path: ${path}`, NOT_STARTED);
+  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || resolve(rel) === rel) throw new ToolFault("permission_denied", `unsafe file checkpoint path: ${path}`, NOT_STARTED);
+  // Session logs and blobs are the evidence; an edit there could rewrite it.
+  if (rel.split(sep).some(part => part === ".git" || part === ".xeno")) {
+    throw new ToolFault("permission_denied", `unsafe file checkpoint path: ${path} is inside .git or .xeno, which edit tools never change`, NOT_STARTED, { next: STATE_PATH_GUIDANCE });
+  }
   let current = base;
   for (const part of rel.split(sep)) {
     current = join(current, part);

package/src/store/search.ts

@@ -18,9 +18,12 @@ import { lstat, readdir, readFile } from "node:fs/promises";
 import { isAbsolute, join, relative, sep } from "node:path";
 import { Worker } from "node:worker_threads";
 import { assertNever } from "../core/exhaustive.ts";
+import { jsPatternFromRipgrep } from "../core/regex-dialect.ts";
 import { buildFileIndex, gitIgnored } from "./file-index.ts";
 import { DEFAULT_IGNORE } from "./workspace.ts";
 import { blobAddress } from "./blobs.ts";
+import { configDir } from "./config.ts";
+import { findRipgrep } from "./tool-binaries.ts";
 import { previewSearchObservation, type SearchObservation } from "../core/search-observation.ts";
 import { failureDiagnostic, failureFromError, READ_ATTEMPTED, NOT_STARTED } from "../core/tool-failure.ts";
 import type { ToolDiagnostic } from "../core/tool-contract.ts";
@@ -459,7 +462,7 @@ function rgText(value: Record<string, unknown>): string {
 }
 
 async function grepRipgrep(opts: GrepOpts, abs: string, limit: number): Promise<SearchResult | null> {
-  const rg = findOnPath("rg");
+  const rg = findRipgrep(configDir());
   if (rg === null) return null;
   const args = [
     "--json",
@@ -491,8 +494,9 @@ function compareMatch(a: MatchLine, b: MatchLine): number {
 }
 
 async function grepWalk(opts: GrepOpts, abs: string, kind: "file" | "dir", rel: string, limit: number): Promise<SearchResult> {
+  const pattern = jsPatternFromRipgrep(opts.pattern);
   try {
-    new RegExp(opts.pattern);
+    new RegExp(pattern);
   } catch (err) {
     return searchFailure("invalid_input", `invalid regex: ${(err as Error).message}`);
   }
@@ -538,7 +542,7 @@ async function grepWalk(opts: GrepOpts, abs: string, kind: "file" | "dir", rel:
       // Reserve the worst-case formatted hits before matching, never discard already observed hits.
       const reservation = Buffer.byteLength(text) + lines.length * (Buffer.byteLength(fileRel) + String(MAX_FILE_BYTES).length + 3);
       if (capturedBytes + reservation > budget) { reasons.push({ code: "capture_budget", path: fileRel }); break; }
-      const matched = await matcher.match(opts.pattern, "", lines, deadline - performance.now(), opts.signal);
+      const matched = await matcher.match(pattern, "", lines, deadline - performance.now(), opts.signal);
       if (matched === "cancelled") { reasons.push({ code: "cancelled", path: fileRel }); break; }
       if (matched === "timeout") {
         reasons.push({ code: "match_timeout", path: fileRel });
@@ -580,11 +584,11 @@ export async function grep(opts: GrepOpts): Promise<SearchResult> {
       return grepWalk(opts, opts.path, target.kind, target.rel, limit);
     case "ripgrep": {
       const got = await grepRipgrep(opts, opts.path, limit);
-      if (got === null) return searchFailure("environment_missing", "ripgrep is not on PATH");
+      if (got === null) return searchFailure("environment_missing", "ripgrep is not on PATH or in xeno's bin directory");
       return got;
     }
     case "auto": {
-      if (findOnPath("rg") !== null) {
+      if (findRipgrep(configDir()) !== null) {
         const got = await grepRipgrep(opts, opts.path, limit);
         if (got !== null) return got;
       }

package/src/store/tool-binaries.ts

@@ -0,0 +1,90 @@
+/**
+ * xeno's own copy of ripgrep, for machines that have none.
+ *
+ * Where it lives: `<configDir>/bin`, next to settings and auth, so one
+ * install serves every workspace. Who sees it: the grep tool (after PATH)
+ * and shell commands, whose PATH gets the directory appended -- appended so a
+ * user who later installs rg keeps theirs (core/command-contract.ts).
+ *
+ * The network fetch is injected: store owns the filesystem, the caller owns
+ * the request (as runtime/update-check.ts does for the registry).
+ */
+import { existsSync } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { ripgrepAsset, type RipgrepAsset } from "../core/ripgrep-release.ts";
+
+export function xenoBinDir(configDir: string): string {
+  return join(configDir, "bin");
+}
+
+function onPath(name: string, pathEnv: string): string | null {
+  for (const dir of pathEnv.split(process.platform === "win32" ? ";" : ":")) {
+    if (dir.length === 0) continue;
+    const candidate = join(dir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** The user's rg first, then xeno's; null when neither exists. */
+export function findRipgrep(configDir: string, pathEnv = process.env["PATH"] ?? ""): string | null {
+  const own = join(xenoBinDir(configDir), "rg");
+  return onPath("rg", pathEnv) ?? (existsSync(own) ? own : null);
+}
+
+export type ProvisionResult =
+  | { ok: true; path: string; installed: boolean }
+  | { ok: false; error: string };
+
+export interface ProvisionOptions {
+  configDir: string;
+  fetchBytes: (url: string, signal?: AbortSignal) => Promise<Uint8Array>;
+  /** Defaults to the user's PATH; injected so tests are not decided by the machine. */
+  path?: string;
+  /** Defaults to the pinned build for this platform. */
+  asset?: RipgrepAsset | null;
+  signal?: AbortSignal;
+}
+
+/**
+ * Installs the pinned ripgrep unless one is already reachable.
+ *
+ * Nothing becomes visible until it is proven: the archive is hashed before
+ * extraction, only the one member is extracted, and the executable reaches
+ * `bin/rg` by rename, so a crash or a mismatch never leaves a partial or
+ * unverified binary where the shell would find it.
+ */
+export async function provisionRipgrep(options: ProvisionOptions): Promise<ProvisionResult> {
+  const existing = findRipgrep(options.configDir, options.path);
+  if (existing !== null) return { ok: true, path: existing, installed: false };
+  const asset = options.asset === undefined ? ripgrepAsset(process.platform, process.arch) : options.asset;
+  if (asset === null) return { ok: false, error: `no pinned ripgrep build for ${process.platform} ${process.arch}` };
+
+  const bin = xenoBinDir(options.configDir);
+  await mkdir(bin, { recursive: true });
+  // Inside bin, so the final rename stays on one filesystem and is atomic.
+  const stage = await mkdtemp(join(bin, ".rg-install-"));
+  try {
+    const bytes = await options.fetchBytes(asset.url, options.signal);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== asset.sha256) return { ok: false, error: `ripgrep archive sha256 ${digest} does not match pinned ${asset.sha256}` };
+    const archive = join(stage, "rg.tar.gz");
+    await writeFile(archive, bytes);
+    const extracted = Bun.spawnSync(["tar", "-xzf", archive, "-C", stage, asset.member], { stdout: "ignore", stderr: "pipe" });
+    if (extracted.exitCode !== 0) return { ok: false, error: `cannot extract ripgrep: ${extracted.stderr.toString().trim()}` };
+    const executable = join(stage, asset.member);
+    // The digest pins the archive, but chmod and rename follow what tar
+    // wrote; a member that is not a plain file is refused before either.
+    if (!(await lstat(executable)).isFile()) return { ok: false, error: "ripgrep archive member is not a regular file" };
+    await chmod(executable, 0o755);
+    const target = join(bin, "rg");
+    await rename(executable, target);
+    return { ok: true, path: target, installed: true };
+  } catch (error) {
+    return { ok: false, error: `cannot install ripgrep: ${error instanceof Error ? error.message : String(error)}` };
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
+}