@visual-z/xeno 0.8.0 → 0.8.2

package/src/runtime/provider.ts

@@ -35,10 +35,12 @@ 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 { isToolStopWithoutCall } from "../core/response-recovery.ts";
 import type { UsageSample } from "./usage.ts";
 import { type Effort, type ModelSpec, CLAUDE_OPUS_5 } from "./model.ts";
 import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
 import { anthropicOAuthHeaders } from "./oauth.ts";
+import { XENO_VERSION } from "./version.ts";
 import type { ProviderSendOptions } from "./provider-tool-policy.ts";
 
 export interface ToolSchema {
@@ -159,6 +161,27 @@ export class FailedResponseError extends Error {
   }
 }
 
+/**
+ * A 200 response that contradicts itself, such as a tool stop with no tool
+ * call. retry.ts treats it like a transient stream failure: a fresh sample is
+ * the remedy, and exhausting retries must surface as a provider error rather
+ * than reach the loop as a silent final answer. The output token count tells
+ * "generated but lost in transit" apart from "nothing generated".
+ */
+export class MalformedResponseError extends FailedResponseError {
+  constructor(detail: string, usage?: UsageSample) {
+    super(`malformed provider response: ${detail}${usage ? ` (${usage.output_tokens} output tokens)` : ""}`, usage);
+    this.name = "MalformedResponseError";
+  }
+}
+
+/** Every adapter returns through this, so no dialect can hand the loop a contradictory turn. */
+export function coherentTurn(turn: Turn, usageKnown = true): Turn {
+  if (isToolStopWithoutCall(turn.stopReason, turn.blocks))
+    throw new MalformedResponseError(`stop_reason ${JSON.stringify(turn.stopReason)} without a tool call`, usageKnown ? turn.usage : undefined);
+  return turn;
+}
+
 /** Thrown for a refusal, which arrives as HTTP 200 rather than an error. */
 export class RefusalError extends FailedResponseError {
   readonly category: string | null;
@@ -176,6 +199,12 @@ function buildAnthropicClient(
   apiKey: string | undefined,
   options: { fetch?: typeof fetch; oauth?: boolean; baseUrl?: string },
 ): AnthropicTransport {
+  // D18: the User-Agent, not SDK headers, identifies xeno on the wire. Left alone
+  // the SDK sends `Anthropic/JS <version>`, which model gateways fold into "custom
+  // client" attribution; provider-request.ts already stamps xeno's UA on the Pi
+  // path. Constructor defaultHeaders merge after the SDK's built-in UA, so this
+  // entry wins without touching per-request headers.
+  const identity = { "User-Agent": `xeno/${XENO_VERSION}` };
   if (options.oauth === true && apiKey) {
     // authToken is Bearer. Passing apiKey here would send x-api-key, which
     // an OAuth token is not accepted as.
@@ -183,7 +212,7 @@ function buildAnthropicClient(
       maxRetries: 0,
       ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
       authToken: apiKey,
-      defaultHeaders: anthropicOAuthHeaders(),
+      defaultHeaders: { ...anthropicOAuthHeaders(), ...identity },
       ...(options.fetch ? { fetch: options.fetch } : {}),
     });
   }
@@ -191,6 +220,7 @@ function buildAnthropicClient(
     maxRetries: 0,
     ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
     ...(apiKey ? { apiKey } : {}),
+    defaultHeaders: identity,
     ...(options.fetch ? { fetch: options.fetch } : {}),
   });
 }
@@ -319,11 +349,11 @@ export class AnthropicProvider implements Provider {
       throw new RefusalError(details?.category ?? null, details?.explanation ?? null, assembled.usageKnown ? usage : undefined);
     }
 
-    return {
+    return coherentTurn({
       blocks: assembled.blocks,
       stopReason: assembled.stopReason,
       usage,
-    };
+    }, assembled.usageKnown);
   }
 }
 

package/src/runtime/retry.ts

@@ -33,6 +33,11 @@ function isStreamFailure(error: unknown): error is Error & { code?: string } {
   return error instanceof Error && error.name === "StreamError";
 }
 
+/** provider.ts MalformedResponseError: a self-contradictory 200, structural for the same reason. */
+function isMalformedResponse(error: unknown): boolean {
+  return error instanceof Error && error.name === "MalformedResponseError";
+}
+
 export interface RetryPolicy {
   /**
    * Attempts after the first. Four means a request can take about 15s of
@@ -140,8 +145,10 @@ export function retryDecision(
   // A failure reported inside a 200 stream carries no status. Relays and
   // Anthropic's own `overloaded_error` use it for exactly the conditions a
   // 5xx would signal; anything else in a stream is a real rejection.
-  if (status === undefined && isStreamFailure(error)) {
-    if (!TRANSIENT_STREAM.test(`${error.code ?? ""} ${error.message}`)) {
+  if (status === undefined && (isStreamFailure(error) || isMalformedResponse(error))) {
+    // A contradictory response is a bad sample, not a rejection of the request:
+    // resend it like a dropped stream, and let the bound turn it into an error.
+    if (isStreamFailure(error) && !TRANSIENT_STREAM.test(`${error.code ?? ""} ${error.message}`)) {
       return { retry: false, reason: "the stream reported a non-transient error" };
     }
     const base = Math.min(0.5 * 2 ** attempt, 8) * 1000;

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/runtime/usage.ts

@@ -88,6 +88,34 @@ export function totalUsage(samples: readonly UsageSample[]): UsageTotals {
   return t;
 }
 
+/**
+ * Below this a request's speed is not shown: a response that returns at once
+ * (a test double, a local cache) would divide into thousands of tokens per
+ * second. Assumed, not measured.
+ */
+export const SPEED_MIN_MS = 250;
+
+/**
+ * Output tokens per second over a set of model requests, or undefined when
+ * none can be measured (feat-sidebar-goal-and-speed). OpenCode's built-in
+ * turnTokensPerSecond uses the same definition: output over the time the
+ * requests took, each request counted once. Not output over the time since
+ * the first visible output -- output counts include reasoning that providers
+ * do not always stream (OpenAI summaries arrive late, Anthropic can omit
+ * them), so that would keep reasoning tokens and drop reasoning time, and
+ * overstate. Whole request time never overstates; an overloaded upstream
+ * reads slow, which is what the user is waiting on.
+ */
+export function generationSpeed(samples: readonly UsageSample[]): number | undefined {
+  let tokens = 0, ms = 0;
+  for (const sample of samples) {
+    if (sample.output_tokens <= 0 || !(sample.ms >= SPEED_MIN_MS)) continue;
+    tokens += sample.output_tokens;
+    ms += sample.ms;
+  }
+  return ms > 0 ? tokens / (ms / 1000) : undefined;
+}
+
 /**
  * Cost in equivalent base-input tokens, the unit appendix A's model uses.
  *

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

package/src/store/worktree.ts

@@ -20,8 +20,10 @@
  *   is for cooperative branches, not adversarial ones.
  */
 
-import { mkdtemp, rm, realpath } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, mkdtemp, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, join } from "node:path";
 import { tmpdir } from "node:os";
 
 /** Branch prefix, so a stale worktree is identifiable months later. */
@@ -37,6 +39,37 @@ export type CreateResult =
   | { ok: true; path: string; branch: string; snapshot: { head: string; tree: string } }
   | { ok: false; error: string };
 
+export interface CreateOptions {
+  /**
+   * Where the checkout goes. Default: a fresh temp directory, which suits a
+   * writing branch that lives for one subtask. A model-entered worktree is
+   * kept across sessions, so it names a stable parent and its own leaf.
+   */
+  location?: { parent: string; leaf: string };
+  /** Carry the parent's uncommitted files (default, as a branch needs). */
+  includeChanges?: boolean;
+}
+
+/**
+ * The stable home of model-entered worktrees for one repository.
+ *
+ * Under xeno's config directory rather than the project: inside `.xeno` it
+ * would collide with the rule that session state is never edited, and a
+ * sibling directory leaves xeno's checkouts in the user's project tree (Codex
+ * keeps its worktrees under its own home for the same reason). The digest of
+ * the repository path keeps two clones with the same name apart.
+ */
+export function persistentWorktreeParent(configDir: string, repo: string): string {
+  const digest = createHash("sha256").update(repo).digest("hex").slice(0, 8);
+  return join(configDir, "worktrees", `${basename(repo)}-${digest}`);
+}
+
+/** The repository's main checkout: `git worktree list` always lists it first. */
+export async function mainWorktree(dir: string): Promise<string | null> {
+  const listed = await listWorktrees(dir).catch(() => []);
+  return listed[0]?.path ?? null;
+}
+
 export type RemoveResult =
   | { ok: true }
   | { ok: false; error: string; dirty: boolean };
@@ -61,7 +94,7 @@ export async function isGitRepo(dir: string): Promise<boolean> {
   return git(dir, ["rev-parse", "--git-dir"]).code === 0;
 }
 
-export async function createWorktree(repo: string, name: string): Promise<CreateResult> {
+export async function createWorktree(repo: string, name: string, options: CreateOptions = {}): Promise<CreateResult> {
   // Refused rather than degraded. Falling back to the shared directory is the
   // exact failure isolation exists to prevent: parallel writing branches
   // would overwrite each other with nothing to indicate isolation was never
@@ -107,13 +140,24 @@ export async function createWorktree(repo: string, name: string): Promise<Create
   } finally { await rm(scratch, { recursive: true, force: true }); }
 
   const branch = `${WORKTREE_BRANCH_PREFIX}${name}`;
-  const created = await mkdtemp(join(tmpdir(), `xeno-wt-${name}-`));
-  // Resolved through symlinks, because git reports the real path and a
-  // caller comparing the two would never match. On macOS /var is a symlink
-  // to /private/var, so every temp path differs by default.
-  const path = await realpath(created);
-  // mkdtemp created it; git worktree add needs the path not to exist.
-  await rm(path, { recursive: true, force: true });
+  if (git(repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]).code === 0) {
+    return { ok: false, error: `branch ${branch} already exists; choose another name or work in its existing checkout` };
+  }
+  let path: string;
+  if (options.location) {
+    await mkdir(options.location.parent, { recursive: true });
+    // Resolved for the same reason as the temp path below.
+    path = join(await realpath(options.location.parent), options.location.leaf);
+    if (existsSync(path)) return { ok: false, error: `${path} already exists; choose another name` };
+  } else {
+    const created = await mkdtemp(join(tmpdir(), `xeno-wt-${name}-`));
+    // Resolved through symlinks, because git reports the real path and a
+    // caller comparing the two would never match. On macOS /var is a symlink
+    // to /private/var, so every temp path differs by default.
+    path = await realpath(created);
+    // mkdtemp created it; git worktree add needs the path not to exist.
+    await rm(path, { recursive: true, force: true });
+  }
 
   // --lock in the same call: locking afterwards leaves a window in which a
   // concurrent prune can remove the worktree that was just created.
@@ -121,6 +165,7 @@ export async function createWorktree(repo: string, name: string): Promise<Create
   if (add.code !== 0) {
     return { ok: false, error: `git worktree add failed: ${add.stderr.trim()}` };
   }
+  if (options.includeChanges === false) return { ok: true, path, branch, snapshot: { head: head.stdout.trim(), tree: git(path, ["rev-parse", "HEAD^{tree}"]).stdout.trim() } };
   // Only this freshly created disposable checkout is reset. The child index
   // carries the parent's uncommitted input, so normal diff/inspection still sees it.
   const hydrate = git(path, ["read-tree", "--reset", "-u", tree]);

package/src/tui/ui/duration.ts

@@ -0,0 +1,16 @@
+/**
+ * Elapsed time as people read it (feat-sidebar-goal-and-speed): `59s`, then
+ * `1m 00s`, then `1h 01m 01s`. The steps are Codex's fmt_elapsed_compact; a
+ * running turn used to read `3725s`.
+ *
+ * Every field after the first is two digits, so a running clock keeps its
+ * width within a unit instead of jittering the labels beside it. Parts of a
+ * second never round up: the clock shows seconds that have fully passed.
+ */
+export function formatElapsed(ms: number): string {
+  const total = Number.isFinite(ms) && ms > 0 ? Math.floor(ms / 1000) : 0;
+  if (total < 60) return `${total}s`;
+  const seconds = String(total % 60).padStart(2, "0");
+  if (total < 3600) return `${Math.floor(total / 60)}m ${seconds}s`;
+  return `${Math.floor(total / 3600)}h ${String(Math.floor(total % 3600 / 60)).padStart(2, "0")}m ${seconds}s`;
+}

package/src/tui/ui/layout.ts

@@ -48,7 +48,7 @@ export function screenLayout(cols: number, rows: number, sidebarWanted = true):
   return { tier: "bare", sidebarWidth: 0, mainWidth: c, topbar: false };
 }
 
-export const STATUS_FIELDS = ["mode", "provider", "activity", "git", "model", "thinking", "context", "title", "workspace", "branch", "usage", "cost", "handoff", "tasks", "files", "background", "resources", "extension"] as const;
+export const STATUS_FIELDS = ["mode", "provider", "activity", "git", "model", "thinking", "context", "goal", "title", "workspace", "branch", "usage", "cost", "handoff", "tasks", "files", "background", "resources", "extension"] as const;
 export type StatusField = (typeof STATUS_FIELDS)[number];
 /** Screen surfaces only; the terminal title is outside the frame and listed separately. */
 export type Place = "sidebar" | "topbar" | "topEdge" | "bottomEdge" | "hidden";
@@ -61,13 +61,13 @@ export type Place = "sidebar" | "topbar" | "topEdge" | "bottomEdge" | "hidden";
 export function placement(tier: Tier): Readonly<Record<StatusField, Place>> {
   switch (tier) {
     case "sidebar":
-      return { mode: "bottomEdge", provider: "topbar", activity: "topEdge", git: "sidebar", model: "bottomEdge", thinking: "bottomEdge", context: "sidebar", title: "sidebar", workspace: "sidebar", branch: "sidebar",
+      return { mode: "bottomEdge", provider: "topbar", activity: "topEdge", git: "sidebar", model: "bottomEdge", thinking: "bottomEdge", context: "sidebar", goal: "sidebar", title: "sidebar", workspace: "sidebar", branch: "sidebar",
         usage: "sidebar", cost: "sidebar", handoff: "sidebar", tasks: "sidebar", files: "sidebar", background: "sidebar", resources: "sidebar", extension: "sidebar" };
     case "topbar":
-      return { mode: "bottomEdge", provider: "topbar", activity: "topEdge", git: "hidden", model: "bottomEdge", thinking: "bottomEdge", context: "bottomEdge", title: "topbar", workspace: "topbar", branch: "topbar",
+      return { mode: "bottomEdge", provider: "topbar", activity: "topEdge", git: "hidden", model: "bottomEdge", thinking: "bottomEdge", context: "bottomEdge", goal: "bottomEdge", title: "topbar", workspace: "topbar", branch: "topbar",
         usage: "hidden", cost: "topbar", handoff: "topbar", tasks: "hidden", files: "hidden", background: "topbar", resources: "hidden", extension: "topbar" };
     case "bare":
-      return { mode: "bottomEdge", provider: "hidden", activity: "topEdge", git: "hidden", model: "bottomEdge", thinking: "bottomEdge", context: "bottomEdge", title: "hidden", workspace: "hidden", branch: "hidden",
+      return { mode: "bottomEdge", provider: "hidden", activity: "topEdge", git: "hidden", model: "bottomEdge", thinking: "bottomEdge", context: "bottomEdge", goal: "bottomEdge", title: "hidden", workspace: "hidden", branch: "hidden",
         usage: "hidden", cost: "hidden", handoff: "hidden", tasks: "hidden", files: "hidden", background: "hidden", resources: "hidden", extension: "hidden" };
     default: return assertNever(tier, "placement");
   }