@visual-z/xeno 0.8.1 → 0.8.3

package/src/core/history.ts

@@ -1,7 +1,8 @@
 /** D20: bounded carried state, with deterministic pages rebuilt from the log. */
-import { emitHandoff, type Handoff } from "./handoff.ts";
+import { emitHandoff, type Handoff, type UserTurnRecord } from "./handoff.ts";
 import { estimateTokens } from "./tokens.ts";
-import { recoveryWorkingSet } from "./working-set.ts";
+import { recoveryWorkingSet, recoveryWorkingSetV3 } 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
@@ -64,20 +65,19 @@ function suffixes(h: Handoff, offsets: Record<HistorySection, number>): Handoff
   };
 }
 
-export function boundHandoff(full: Handoff, budget = DEFAULT_HANDOFF_TOKENS): Handoff {
-  if (!Number.isFinite(budget) || budget <= 0) throw new RangeError("handoff budget must be positive");
-  const size = (h: Handoff): number => estimateTokens.count([], emitHandoff(h));
-  if (size(full) <= budget) return full;
-  if (full.predecessor === null) throw new Error("history requires an immutable source");
-  // An absent new section must not change legacy projections or frozen replay.
-  const sections = HISTORY_SECTIONS.filter(section => (section !== "state.work_items" || full.state.work_items !== undefined) &&
+/** Sections a handoff actually has; an absent new section must not change legacy projections or frozen replay. */
+function pageableSections(full: Handoff): HistorySection[] {
+  return HISTORY_SECTIONS.filter(section => (section !== "state.work_items" || full.state.work_items !== undefined) &&
     (section !== "evidence_links" || full.evidence_links !== undefined) &&
     (section !== "acceptance.criteria" || full.acceptance !== undefined) &&
     (section !== "acceptance.targets" || full.acceptance?.targets !== undefined) &&
     (section !== "loaded_skills" || full.loaded_skills !== undefined) &&
     (section !== "processes" || full.processes !== undefined));
-  const offsets = Object.fromEntries(sections.map((s) => [s, historyItems(full, s).length])) as Record<HistorySection, number>;
-  const build = (): Handoff => ({
+}
+
+/** The v2 shape carrying `items.length - offset` newest items of every pageable section. */
+function carriedAt(full: Handoff, sections: readonly HistorySection[], offsets: Record<HistorySection, number>): Handoff {
+  return {
     ...suffixes(full, offsets),
     handoff_version: 2,
     history: {
@@ -86,22 +86,42 @@ export function boundHandoff(full: Handoff, budget = DEFAULT_HANDOFF_TOKENS): Ha
         total: historyItems(full, s).length, offset: offsets[s],
       }])),
     },
-  });
+  };
+}
+
+const handoffSize = (h: Handoff): number => estimateTokens.count([], emitHandoff(h));
+
+/**
+ * `priority` sections grow to completion, newest first, before any other
+ * section gets an item; the rest then share what is left round-robin. The
+ * default (none) is the original D20 order, which recorded cuts replay.
+ */
+export function boundHandoff(full: Handoff, budget = DEFAULT_HANDOFF_TOKENS, priority: readonly HistorySection[] = []): Handoff {
+  if (!Number.isFinite(budget) || budget <= 0) throw new RangeError("handoff budget must be positive");
+  const size = handoffSize;
+  if (size(full) <= budget) return full;
+  if (full.predecessor === null) throw new Error("history requires an immutable source");
+  const sections = pageableSections(full);
+  const offsets = Object.fromEntries(sections.map((s) => [s, historyItems(full, s).length])) as Record<HistorySection, number>;
+  const build = (): Handoff => carriedAt(full, sections, offsets);
   let carried = build();
   // The objective stays verbatim (D2). An oversized objective is an explicit
   // input problem; repeatedly cutting it would create an infinite cut loop.
   if (size(carried) > budget) throw new RangeError("handoff scalar fields exceed budget; shorten the objective or frozen input");
-  const active = new Set<HistorySection>(sections);
+  const grow = (section: HistorySection): boolean => {
+    if (offsets[section] === 0) return false;
+    offsets[section]--;
+    const candidate = build();
+    if (size(candidate) <= budget) { carried = candidate; return true; }
+    offsets[section]++;
+    return false;
+  };
+  for (const section of priority) if (sections.includes(section)) while (grow(section)) { /* newest first until full or out of room */ }
+  const active = new Set<HistorySection>(sections.filter(section => !priority.includes(section)));
   // Round-robin suffix growth prevents one long section starving every other
   // category. Each retained range is contiguous and independently pageable.
   while (active.size > 0) {
-    for (const section of active) {
-      if (offsets[section] === 0) { active.delete(section); continue; }
-      offsets[section]--;
-      const candidate = build();
-      if (size(candidate) <= budget) carried = candidate;
-      else { offsets[section]++; active.delete(section); }
-    }
+    for (const section of active) if (!grow(section)) active.delete(section);
   }
   return carried;
 }
@@ -122,6 +142,96 @@ 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;
+}
+
+/**
+ * D8: join carried turns to their original user events to name attached images
+ * by digest. Turns and events are both the active ancestry in log order; any
+ * disagreement leaves the turns undecorated rather than guessing a pairing.
+ */
+export function userTurnImages(turns: readonly UserTurnRecord[], nodes: RecoveryNodes): readonly UserTurnRecord[] {
+  const users = nodes.flatMap(part => part.events.flatMap(event => event.t === "user" ? [event] : []));
+  if (users.length !== turns.length || users.some((event, i) => event.at !== turns[i]!.at || event.text !== turns[i]!.text)) return turns;
+  return turns.map((turn, i) => {
+    const event = users[i]!;
+    return event.images?.length ? { ...turn, event: event.id,
+      images: event.images.map(({ sha256, name, width, height }) => ({ sha256, name, width, height })) } : turn;
+  });
+}
+
+/**
+ * v3 carries one copy of each work item's prose. `state.in_flight` and
+ * `state.blocked` are compatible projections of identified work (O.2), so a
+ * leading run of items the carried `state.work_items` or working set already
+ * hold moves into the existing page range, which `validateHandoff` accepts for
+ * continuation; D20 arrays stay contiguous suffixes. A working-set entry whose
+ * prose the carried `state.work_items` holds keeps only its id and status, since
+ * `state.work_items` is the canonical identified work. Every change only
+ * removes bytes, so the budget still holds.
+ */
+function oneCopyOfWork(h: Handoff): Handoff {
+  const items = new Map((h.state.work_items ?? []).map(item => [item.id, item]));
+  const viewed = new Map((h.working_set?.work ?? []).map(entry => [entry.id, entry]));
+  const history = h.history && { ...h.history, sections: { ...h.history.sections } };
+  type Prose = { status: string; what?: string; next_action?: string; reason?: string };
+  const holders = (id: string | undefined): Prose[] => {
+    const found: Prose[] = [], item = id === undefined ? undefined : items.get(id), entry = id === undefined ? undefined : viewed.get(id);
+    if (item) found.push(item);
+    if (entry) found.push(entry);
+    return found;
+  };
+  const page = <T extends { work_id?: string }>(section: "state.in_flight" | "state.blocked", list: readonly T[], same: (item: T, holder: Prose) => boolean): readonly T[] => {
+    const range = history?.sections[section];
+    let skip = 0;
+    while (range && skip < list.length && holders(list[skip]!.work_id).some(holder => same(list[skip]!, holder))) skip++;
+    if (skip === 0) return list;
+    history!.sections[section] = { total: range!.total, offset: range!.offset + skip };
+    return list.slice(skip);
+  };
+  const in_flight = page("state.in_flight", h.state.in_flight, (item, holder) => holder.status === "active" && holder.what === item.what && holder.next_action === item.next_action);
+  const blocked = page("state.blocked", h.state.blocked, (item, holder) => holder.status === "blocked" && holder.what === item.what && holder.reason === item.reason);
+  const view = h.working_set && { ...h.working_set, work: h.working_set.work.map(entry => {
+    const item = items.get(entry.id);
+    if (!item || item.what !== entry.what || item.next_action !== entry.next_action || item.reason !== entry.reason) return entry;
+    const { what: _what, next_action: _next, reason: _reason, ...rest } = entry;
+    return rest;
+  }) };
+  return { ...h, ...(view ? { working_set: view } : {}), ...(history ? { history } : {}), state: { ...h.state, in_flight, blocked } };
+}
+
+const USERS_FIRST: readonly HistorySection[] = ["user_turns"];
+
+/**
+ * Working set v3. User turns are the smallest, highest-value carried content
+ * (Codex compaction likewise keeps user messages newest first, verbatim, under
+ * its own cap), so they are reserved before the working set and before every
+ * other page; only turns that alone exceed the budget are cut, newest kept.
+ * While every turn is inline, user references would only point at text already
+ * present, so the view leaves them out. The view keeps v2's 40% allocation
+ * assumption, measured inside the handoff it is carried in.
+ */
+export function boundRecoveryHandoffV3(full: Handoff, nodes: RecoveryNodes, budget = DEFAULT_HANDOFF_TOKENS, tools?: readonly string[]): Handoff {
+  if (!Number.isFinite(budget) || budget <= 0) throw new RangeError("handoff budget must be positive");
+  const base: Handoff = { ...full, user_turns: userTurnImages(full.user_turns, nodes) };
+  const plain = (): Handoff => oneCopyOfWork(boundHandoff(base, budget, USERS_FIRST));
+  if (base.predecessor === null) return plain();
+  const sections = pageableSections(base);
+  const empty = Object.fromEntries(sections.map((s) => [s, historyItems(base, s).length])) as Record<HistorySection, number>;
+  const withUsers = carriedAt(base, sections, { ...empty, user_turns: 0 });
+  const usersInline = base.user_turns_truncated === undefined && handoffSize(withUsers) <= budget;
+  const skeleton = usersInline ? withUsers : carriedAt(base, sections, empty);
+  const cap = Math.min(budget, handoffSize(skeleton) + budget * .4);
+  const recovery = recoveryInstructions(tools ?? ["history"], usersInline, base.user_turns.some(turn => turn.images !== undefined));
+  const view = recoveryWorkingSetV3(base, nodes, { users: !usersInline, recovery,
+    fits: candidate => handoffSize({ ...skeleton, working_set: candidate }) <= cap });
+  if (!view) return plain();
+  try { return oneCopyOfWork(boundHandoff({ ...base, working_set: view }, budget, USERS_FIRST)); }
+  catch (error) { if (error instanceof RangeError) return plain(); throw error; }
 }

package/src/core/observation-view.ts

@@ -85,6 +85,30 @@ export function headTailSelection(
     visible: [...(headEnd ? [[0, headEnd] as [number, number]] : []), ...(kept ? [[total - kept, total] as [number, number]] : [])] };
 }
 
+/**
+ * The text a terminal would finally show for output that redraws lines with
+ * `\r` (progress bars). Within each `\n`-separated line, a carriage return
+ * moves back to column 0 and the following characters overwrite, one code
+ * point each; characters not overwritten stay. `\r\n` is thus a plain line
+ * break. Other control sequences (`ESC[K` and the like) are left as they are.
+ *
+ * A view only: the archived bytes keep every frame (D8). Without this a 6.3KB
+ * brew download of 48 frames reached the model whole (carriage-return-view
+ * card), though a terminal showed one line.
+ */
+export function foldCarriageReturns(text: string): string {
+  if (!text.includes("\r")) return text;
+  return text.split("\n").map(line => {
+    if (!line.includes("\r")) return line;
+    let screen: string[] = [];
+    for (const frame of line.split("\r")) {
+      const chars = Array.from(frame);
+      screen = chars.concat(screen.slice(chars.length));
+    }
+    return screen.join("");
+  }).join("\n");
+}
+
 /** Signals a shell reports as 128+n; the common ones a model can act on. */
 const SIGNALS: Readonly<Record<number, string>> = {
   1: "SIGHUP", 2: "SIGINT", 6: "SIGABRT", 9: "SIGKILL", 11: "SIGSEGV", 13: "SIGPIPE", 15: "SIGTERM",

package/src/core/path-suggestions.ts

@@ -0,0 +1,59 @@
+/**
+ * Existing paths that a missing one probably meant.
+ *
+ * Models guess paths, and most guesses in a reviewed session (flotil: 11 of
+ * 11 ENOENT) had the right file name in the wrong directory or a near
+ * spelling. OpenCode's read tool suggests up to three entries of the same
+ * directory whose name contains, or is contained in, the requested one
+ * (`packages/opencode/src/tool/read.ts`); that misses a wrong directory, so
+ * this ranks the whole workspace listing, file name first.
+ *
+ * Pure and deterministic: the result depends on the set of candidates, never
+ * their order, so the same failure always names the same paths.
+ */
+import { editDistance } from "./text-normalize.ts";
+
+/** OpenCode's count: enough to cover a wrong directory, short enough to read at a glance. */
+export const PATH_SUGGESTION_LIMIT = 3;
+
+/** Containment of a shorter name is too weak a signal below this length (assumed: "a" is in everything). */
+const MIN_CONTAINED = 3;
+
+const baseName = (path: string) => path.slice(path.lastIndexOf("/") + 1);
+const stem = (name: string) => { const dot = name.lastIndexOf("."); return dot > 0 ? name.slice(0, dot) : name; };
+
+/**
+ * Rank tier of `name` against the wanted file name, or null when unrelated.
+ * 0: same name; 1: same name without extension; 2: one name contains the
+ * other; 3: a near spelling (edit distance within a quarter of the length).
+ */
+function tier(name: string, wanted: string, distance: number): number | null {
+  if (name === wanted) return 0;
+  if (stem(name) === stem(wanted) && stem(name).length > 0) return 1;
+  const shorter = name.length < wanted.length ? name : wanted, longer = shorter === name ? wanted : name;
+  if (shorter.length >= MIN_CONTAINED && longer.includes(shorter)) return 2;
+  if (distance <= Math.max(1, Math.floor(wanted.length / 4))) return 3;
+  return null;
+}
+
+/**
+ * Up to `limit` workspace-relative paths from `candidates` closest to the
+ * missing `target`, best first. Paths use "/" separators; comparison ignores
+ * case. The target itself is never suggested.
+ */
+export function nearestPaths(target: string, candidates: readonly string[], limit = PATH_SUGGESTION_LIMIT): string[] {
+  const wantedPath = target.replace(/^\.\//, "").toLowerCase();
+  const wanted = baseName(wantedPath);
+  if (wanted.length === 0 || limit <= 0) return [];
+  const ranked: { path: string; tier: number; name: number; whole: number }[] = [];
+  for (const path of new Set(candidates)) {
+    const lower = path.toLowerCase();
+    if (lower === wantedPath) continue;
+    const name = baseName(lower), distance = editDistance(name, wanted);
+    const rank = tier(name, wanted, distance);
+    if (rank === null) continue;
+    ranked.push({ path, tier: rank, name: distance, whole: editDistance(lower, wantedPath) });
+  }
+  ranked.sort((a, b) => a.tier - b.tier || a.name - b.name || a.whole - b.whole || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return ranked.slice(0, limit).map(item => item.path);
+}

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"],
@@ -161,6 +162,66 @@ export function decideWithSessionRules(
   return decide([...remembered, ...configured], request);
 }
 
+/**
+ * Where a gate outcome came from, for the durable approval record
+ * (feat-approval-events). `auto` is an allow by a rule with no selector --
+ * what `--yolo` compiles to -- so "no approval was required" is derived from
+ * the rule list itself rather than from a side flag. `none` means no rule
+ * matched and the empty-list default allowed: no policy was consulted.
+ */
+export type DecisionSource = "session_rule" | "config" | "auto" | "none";
+export interface DecisionExplanation {
+  readonly action: PermissionAction;
+  readonly source: DecisionSource;
+  readonly rule?: PermissionRule;
+}
+
+/** Mirrors decide() exactly, but keeps the index of the rule that produced the action. */
+function explainList(rules: readonly PermissionRule[], request: PermissionRequest): { action: PermissionAction; index?: number } {
+  if (request.paths && request.paths.length > 1) {
+    const each = request.paths.map(path => explainList(rules, { ...request, paths: [path] }));
+    const actions = each.map(item => item.action);
+    const action: PermissionAction = actions.includes("deny") ? "deny" : actions.includes("ask") ? "ask" : "allow";
+    return each.find(item => item.action === action)!;
+  }
+  const index = rules.findIndex(rule => ruleMatches(rule, request));
+  return index < 0 ? { action: "allow" } : { action: rules[index]!.action, index };
+}
+
+/** decideWithSessionRules plus the rule that decided; the action is always identical (property-tested). */
+export function explainDecision(
+  configured: readonly PermissionRule[], remembered: readonly PermissionRule[], request: PermissionRequest,
+): DecisionExplanation {
+  const ceiling = explainList(configured, request);
+  if (ceiling.action === "deny") return { action: "deny", source: "config", rule: configured[ceiling.index!]! };
+  const combined = [...remembered, ...configured];
+  const found = explainList(combined, request);
+  if (found.index === undefined) return { action: found.action, source: "none" };
+  const rule = combined[found.index]!;
+  const unconditional = rule.tool === undefined && rule.command === undefined && rule.commandPrefix === undefined &&
+    rule.path === undefined && rule.pathGlob === undefined;
+  return { action: found.action, rule,
+    source: found.index < remembered.length ? "session_rule" : unconditional && rule.action === "allow" ? "auto" : "config" };
+}
+
+/**
+ * A call needs a decision when the product default would not silently allow
+ * it, or when the effective policy did not. Calls outside both -- confined
+ * reads and edits under the default -- had nobody's judgement to record.
+ */
+export function approvalNeeded(request: PermissionRequest, effective: PermissionAction): boolean {
+  return effective !== "allow" || decide(defaultRules(), request) !== "allow";
+}
+
+/** Stable one-line rule text for the log and the export; field order is fixed. */
+export function describeRule(rule: PermissionRule): string {
+  return [rule.action, rule.tool ?? "*",
+    ...(rule.command !== undefined ? [`command=${JSON.stringify(rule.command)}`] : []),
+    ...(rule.commandPrefix !== undefined ? [`commandPrefix=${JSON.stringify(rule.commandPrefix.join(" "))}`] : []),
+    ...(rule.path !== undefined ? [`path=${JSON.stringify(rule.path)}`] : []),
+    ...(rule.pathGlob !== undefined ? [`pathGlob=${JSON.stringify(rule.pathGlob)}`] : [])].join(" ");
+}
+
 /** Lexical normalization is pure; the store adds canonical symlink resources. */
 export function normalizePermissionPath(path: string): string {
   const absolute = path.startsWith("/");

package/src/core/prompt-policy.ts

@@ -23,9 +23,18 @@ 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, images = 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. " +
+      // Working set v3: the turn's image references are carried, the pixels are not.
+      (images ? "A user turn's images are not attached here; history(event=ID) with its event reattaches them. " : "")
     : "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");
+}