@visual-z/xeno 0.8.1 → 0.8.3

package/src/core/secrets.ts

@@ -0,0 +1,188 @@
+/**
+ * Credential redaction at the log boundary (S.9).
+ *
+ * The log is the only truth and every model request is a projection of it, so
+ * a credential that reaches the log is resent on every later request and
+ * survives every cut through `objective` and `user_turns` (D2). Masking at
+ * projection time would leave the original in an append-only file forever.
+ * Redaction therefore happens before an event is written: the secret is
+ * replaced by a placeholder, and the value lives in a separate per-session
+ * vault that no projection reads.
+ *
+ * The placeholder is an exact inverse: tools expand it back to the value when
+ * they run (OpenHands' SecretRegistry does the same with secret names), and
+ * any output that echoes a known value is masked again. A false positive
+ * therefore costs readability, never correctness -- an edit whose old_string
+ * holds a placeholder still matches the file.
+ *
+ * Only high-confidence shapes are detected (gitleaks prefix rules plus
+ * "secret-named key = value"); entropy detection is deliberately absent because
+ * its false positives on hashes and code are irreversible in a live view.
+ * A bare password has no shape, so it is recognised only by context: a short
+ * token the user sends right after the assistant asked for a credential.
+ */
+
+export interface SecretEntry {
+  /** The placeholder's number: `[[xeno-secret-<n>]]`. */
+  n: number;
+  value: string;
+  /** Which rule found it, for the audit trail; never the value. */
+  rule: string;
+}
+
+export type Vault = readonly SecretEntry[];
+
+export const placeholder = (n: number): string => `[[xeno-secret-${n}]]`;
+const PLACEHOLDER = /\[\[xeno-secret-(\d+)\]\]/g;
+
+/**
+ * A known value shorter than this is too likely to occur by accident ("admin",
+ * "123456") to mask everywhere it appears. Assumed, not measured; Codex's
+ * key-assignment rule uses the same 8.
+ */
+export const MIN_SECRET_LENGTH = 8;
+
+interface Rule { id: string; pattern: RegExp; /** Capture group holding the secret; 0 is the whole match. */ group: number }
+
+// Prefix rules follow gitleaks' default config (b58d3f10) and Gemini CLI's
+// environmentSanitization.ts; tskey- is added for Tailscale, which gitleaks lacks.
+const RULES: readonly Rule[] = [
+  { id: "pem-private-key", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z ]*PRIVATE KEY-----/g, group: 0 },
+  { id: "anthropic-key", pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/g, group: 0 },
+  { id: "openai-key", pattern: /\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{20,}/g, group: 0 },
+  { id: "github-token", pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})/g, group: 0 },
+  { id: "gitlab-token", pattern: /\bglpat-[A-Za-z0-9_-]{20,}/g, group: 0 },
+  { id: "slack-token", pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}/g, group: 0 },
+  { id: "aws-access-key", pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, group: 0 },
+  { id: "google-api-key", pattern: /\bAIza[0-9A-Za-z_-]{35}/g, group: 0 },
+  { id: "stripe-key", pattern: /\b[sr]k_live_[0-9A-Za-z]{24,}/g, group: 0 },
+  // tskey-<kind>-<id with a digit>-<secret>; documentation like "tskey-auth-reusable-" has no digit in the id.
+  { id: "tailscale-key", pattern: /\btskey-[a-z]+-[A-Za-z0-9]*\d[A-Za-z0-9]*-[A-Za-z0-9]{10,}/g, group: 0 },
+  { id: "npm-token", pattern: /\bnpm_[A-Za-z0-9]{36}\b/g, group: 0 },
+  { id: "jwt", pattern: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, group: 0 },
+  { id: "bearer-token", pattern: /\bBearer\s+([A-Za-z0-9._~+/=-]{20,})/g, group: 1 },
+  { id: "url-password", pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:([^\s/@]{3,})@/gi, group: 1 },
+  // A secret-named key assigned a literal. The value class excludes quotes,
+  // brackets and parentheses so `token = getToken()` and `password: string`
+  // stay code; requiring a digit or 16+ characters keeps `secret: undefined`.
+  { id: "secret-assignment", group: 1,
+    // Up to three prefix words, so access_token, HUILIANYI_REFRESH_TOKEN and db-password count.
+    pattern: /\b(?:[a-z0-9]+[_-]){0,3}(?:api[_-]?key|access[_-]?key|secret(?:[_-]?key)?|client[_-]?secret|token|password|passwd|pwd)["']?\s*[:=]\s*["']?([^\s"'`(){}[\]<>;,]{8,})/gi },
+  { id: "secret-assignment-zh", group: 1, pattern: /(?:密码|口令|密钥|令牌)\s*(?:是|为|[:：=])\s*["'“]?([^\s"'”，。,;；]{4,})/g },
+];
+
+const plausibleAssigned = (value: string): boolean =>
+  !/^(?:\$|process\.|os\.|env\.|self\.|this\.)/.test(value) && !value.startsWith("[[xeno-secret-") &&
+  // A pure number after a token-named key is a count (input_tokens=12000000), not a credential.
+  !/^\d+$/.test(value) &&
+  // Credentials carry digits; a digit-free value is a path, a member access or a placeholder word
+  // (replayed 2026-10-12 sessions: "internal/server/…", "auth.AccessToken"). A long mixed-case
+  // value without separators is the one digit-free exception.
+  (/\d/.test(value) && /[A-Za-z]/.test(value) || value.length >= 20 && /[A-Z]/.test(value) && /[a-z]/.test(value) && !/[./]/.test(value));
+
+/** Every secret-shaped span in `text`, with the rule that found it. Overlaps resolve to the earliest, longest. */
+export function findSecrets(text: string): { start: number; end: number; rule: string }[] {
+  const spans: { start: number; end: number; rule: string }[] = [];
+  for (const rule of RULES) {
+    for (const match of text.matchAll(rule.pattern)) {
+      const value = match[rule.group];
+      if (value === undefined || match.index === undefined) continue;
+      if (rule.id === "secret-assignment" && !plausibleAssigned(value)) continue;
+      const start = match.index + match[0].lastIndexOf(value);
+      spans.push({ start, end: start + value.length, rule: rule.id });
+    }
+  }
+  spans.sort((a, b) => a.start - b.start || b.end - a.end);
+  const kept: typeof spans = [];
+  for (const span of spans) if (kept.length === 0 || span.start >= kept.at(-1)!.end) kept.push(span);
+  return kept;
+}
+
+/**
+ * Replaces known values and newly found secrets with placeholders. Returns the
+ * vault entries it had to add; the caller persists them before the text is
+ * written anywhere, so a placeholder in the log always has a value to expand to.
+ */
+export function redactText(text: string, vault: Vault, candidates: readonly { value: string; rule: string }[] = []): { text: string; added: SecretEntry[] } {
+  if (text.length === 0) return { text, added: [] };
+  const added: SecretEntry[] = [];
+  let next = vault.reduce((max, entry) => Math.max(max, entry.n), 0) + 1;
+  // Candidates (secret-named environment values) join the vault only when they
+  // actually appear, so a placeholder number is never spent on a value no event holds.
+  const known: SecretEntry[] = [...vault];
+  for (const candidate of candidates) {
+    if (candidate.value.length < MIN_SECRET_LENGTH || !text.includes(candidate.value) || known.some(entry => entry.value === candidate.value)) continue;
+    const entry = { n: next++, value: candidate.value, rule: candidate.rule };
+    known.push(entry); added.push(entry);
+  }
+  let out = maskKnown(text, known);
+  const spans = findSecrets(out);
+  if (spans.length === 0) return { text: out, added };
+  let result = "", at = 0;
+  for (const span of spans) {
+    const value = out.slice(span.start, span.end);
+    const existing = known.find(entry => entry.value === value);
+    const entry = existing ?? { n: next++, value, rule: span.rule };
+    if (!existing) { known.push(entry); added.push(entry); }
+    result += out.slice(at, span.start) + placeholder(entry.n);
+    at = span.end;
+  }
+  // Values found in this pass may occur again where a neighbouring match split
+  // them (two tokens with no delimiter); a second known-value pass closes that.
+  return { text: maskKnown(result + out.slice(at), known), added };
+}
+
+/** Longest first, so a value containing another is masked whole. A short value is masked only where a rule found it. */
+function maskKnown(text: string, known: readonly SecretEntry[]): string {
+  let out = text;
+  for (const entry of known.filter(entry => entry.value.length >= MIN_SECRET_LENGTH).sort((a, b) => b.value.length - a.value.length)) {
+    if (out.includes(entry.value)) out = out.split(entry.value).join(placeholder(entry.n));
+  }
+  return out;
+}
+
+/** The inverse of redactText for tool inputs. An unknown placeholder is left as written. */
+export function expandText(text: string, vault: Vault): string {
+  if (!text.includes("[[xeno-secret-")) return text;
+  return text.replace(PLACEHOLDER, (whole, n: string) => vault.find(entry => entry.n === Number(n))?.value ?? whole);
+}
+
+const ASKED_FOR_CREDENTIAL = /password|passcode|passphrase|credential|api[ _-]?key|access[ _-]?token|\btoken\b|密码|口令|密钥|凭据|凭证|令牌|验证码/i;
+
+/**
+ * A bare password has no shape; what identifies it is the exchange. A message
+ * that is a single token with mixed character classes, sent right after the
+ * assistant asked for a credential, is that credential (the 2026-10-12 ticket
+ * session: the assistant asked for a login password, the user replied with it).
+ */
+export function isSolicitedSecret(userText: string, previousAssistantText: string | undefined): boolean {
+  const value = userText.trim();
+  if (previousAssistantText === undefined || !ASKED_FOR_CREDENTIAL.test(previousAssistantText)) return false;
+  if (!/^\S{6,128}$/.test(value) || value.startsWith("[[xeno-secret-")) return false;
+  // Letters with digits, or three character classes: "dsm612566" and "Pa$$word"
+  // qualify, an identifier like "OPENAI_API_KEY" or a branch name does not.
+  const classes = [/[a-z]/, /[A-Z]/, /\d/, /[^A-Za-z0-9]/].filter(pattern => pattern.test(value)).length;
+  const lettersAndDigits = /[A-Za-z]/.test(value) && /\d/.test(value);
+  return (lettersAndDigits || classes >= 3) && !/^[a-z]+:\/\//i.test(value) && !/^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(value);
+}
+
+/** Applies `redact` to every string in a JSON value, preserving its shape. */
+export function mapStrings(value: unknown, redact: (text: string) => string, skip: (key: string) => boolean = () => false): unknown {
+  if (typeof value === "string") return redact(value);
+  if (Array.isArray(value)) return value.map(item => mapStrings(item, redact, skip));
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) out[key] = skip(key) ? item : mapStrings(item, redact, skip);
+    return out;
+  }
+  return value;
+}
+
+/** Environment variables whose names say they hold a secret; their values are masked wherever they appear. */
+export function secretEnvironmentValues(env: Readonly<Record<string, string | undefined>>): { value: string; rule: string }[] {
+  return Object.entries(env).flatMap(([name, value]) =>
+    value !== undefined && value.length >= MIN_SECRET_LENGTH && !value.startsWith("/") &&
+      /(?:^|_)(?:API_?KEY|KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIALS?|AUTH)(?:_|$)/i.test(name) &&
+      !/(?:^|_)(?:PATH|DIR|FILE|URL|HOST|PORT|USER|NAME|ID|MODE|TYPE)$/i.test(name)
+      ? [{ value, rule: `env:${name}` }] : []).sort((a, b) => a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0);
+}

package/src/core/stall.ts

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

package/src/core/stop-report.ts

@@ -8,7 +8,11 @@ export function stopReport(events: readonly LogEvent[], requests: number, limit:
   const scoped = currentRequestEvents(events);
   const current = scoped.length > 0 ? scoped : events;
   const results = current.filter(event => event.t === "tool_result");
-  const failures = results.filter(event => !event.ok);
+  // Q.22 keeps ok:false on a recorded-but-unverified claim so the model does
+  // not read "recorded" as "done"; to a person reading why work stopped it is
+  // an unproven statement, not a broken tool.
+  const unverified = results.filter(unverifiedClaim);
+  const failures = results.filter(event => !event.ok && !unverifiedClaim(event));
   const exits = results.filter(event => event.effect?.kind === "command" && event.effect.exit === 0).length;
   const ids = new Set<number>();
   for (const event of current) {
@@ -17,10 +21,48 @@ export function stopReport(events: readonly LogEvent[], requests: number, limit:
   }
   const running = [...ids].filter(id => latestProcessReceipt([{ node: 0, events: current }], id)?.receipt.running === true);
   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(", ")}.`] : []),
+    requestLine(exitLine(cause), requests, limit),
+    `Recorded evidence: ${results.length} tool receipts; ${exits} successful command exits; ${failures.length} failed tool receipts${unverified.length ? `; ${unverified.length} unverified claims` : ""}. Task completion is not verified by this stop.`,
+    ...(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");
 }
+
+/**
+ * S.6 removed the default cap. A bare "(80 model requests)" in the same
+ * brackets as "(3/7 model requests)" read as a ceiling that was hit
+ * (fix-stop-report-request-count), so an uncapped run says it is a count.
+ */
+function requestLine(cause: string, requests: number, limit: number): string {
+  if (limit !== Infinity) return `Stopped: ${cause} (${requests}/${limit} model requests).`;
+  return `Stopped: ${cause}. This request sent ${requests} model request${requests === 1 ? "" : "s"}; no request cap is set.`;
+}
+
+/**
+ * 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)` : "");
+}
+
+function unverifiedClaim(event: Extract<LogEvent, { t: "tool_result" }>): boolean {
+  if (event.ok || !event.content.startsWith("{")) return false;
+  try {
+    const body = JSON.parse(event.content) as { recorded?: unknown; verification?: unknown };
+    return body.recorded === true && body.verification === "unverified";
+  } catch { return false; }
+}
+
+/** 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,47 @@ 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.
+ */
+/*
+ * The diagnostic code stays permission_denied because codes are a closed set
+ * validated on every logged tool_result (event-validation.ts); a new code
+ * would change the session format. A model still read that code as "wait for
+ * approval" and stopped (Horizyn mv3nsske), so the text has to say outright
+ * that approval is neither needed nor able to help.
+ */
+const STATE_PATH_RULE = "This path is repository or xeno session state, which edit tools never change. " +
+  "This is not a permission problem and no setting changes this: no user approval allows it, so do not wait for one. ";
+export const STATE_PATH_GUIDANCE = STATE_PATH_RULE +
+  "To work in an isolated checkout, use the worktree tool instead of creating one under .git or .xeno.";
+const STATE_PATH_GUIDANCE_WITHOUT_WORKTREE = STATE_PATH_RULE + "Edit files in a directory 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/transcript.ts

@@ -81,6 +81,9 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
       case "goal": items.push({ ...identity, kind: "notice", text: event.action === "set"
         ? `Goal set · ${event.accepted.length} accepted${event.rejected.length ? `, ${event.rejected.length} rejected` : ""} · ${event.objective}`
         : event.reason === "met" ? "Goal met · every accepted criterion has current evidence" : "Goal cleared" }); break;
+      // Approvals answer "why was this allowed" in /export and history; the person
+      // already saw the prompt, and a notice per auto-allowed command would bury the chat.
+      case "approval":
       case "checkpoint": case "workspace_observation":
       case "guidance": case "claim": case "decision": case "pitfall": case "blocked": case "question": case "next_action": case "work_status": case "work_owner": case "work_dependencies": case "evidence_link":
         // These remain inspectable via /state and /export; they are not chat messages.

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/core/work-state.ts

@@ -50,6 +50,10 @@ export function scopedWorkId(namespace: string, requested: string, items: readon
     ? requested : `${namespace}:${requested}`;
 }
 
+function unknownWork(id: string): string {
+  return `unknown work_id ${id}; create it with a next note (kind=next) first`;
+}
+
 export function workChangeError(items: readonly WorkItem[], event: LogEvent): string | null {
   if (!("work_id" in event) || event.work_id === undefined) return null;
   const item = items.find(item => item.id === event.work_id);
@@ -57,9 +61,10 @@ export function workChangeError(items: readonly WorkItem[], event: LogEvent): st
     const error = dependencyError(items, event.work_id, event.depends_on);
     if (error) return error;
   }
-  if (event.t === "work_dependencies" && !item) return `unknown work_id ${event.work_id}`;
+  // Every unknown-id rejection names the way to make the id exist, or the model retries the same call.
+  if (event.t === "work_dependencies" && !item) return unknownWork(event.work_id);
   if (event.t === "work_owner") {
-    if (!item) return `unknown work_id ${event.work_id}`;
+    if (!item) return unknownWork(event.work_id);
     if (event.operation === "release") return item.owner === event.owner ? null : "only the recorded owner can release work";
     const ready = workReadiness(items, item.id, event.owner);
     return ready.ready ? null : `work ${item.id} is ${ready.reason}; cannot claim it`;

package/src/core/working-set.ts

@@ -7,9 +7,17 @@ import { estimateTokens } from "./tokens.ts";
 import { RECOVERY_SECTIONS, recoverySources, type RecoveryNodes, type RecoveryRanges, type RecoveryReference } from "./recovery-sources.ts";
 import { recoveryInstructions } from "./prompt-policy.ts";
 
+/**
+ * The cut format new sessions record. Live cuts, cold replay and interrupted-cut
+ * repair all select through `carriedHandoff`, so this is only the default for
+ * cuts not yet written; a recorded version is never reinterpreted.
+ */
+export const CURRENT_WORKING_SET_VERSION = 3;
+
 export type WorkingSet = {
-  version: 1 | 2; source: NodeRef;
-  work: (Pick<WorkItem, "id" | "what" | "status" | "next_action" | "reason" | "depends_on" | "owner"> & { readiness?: WorkReadiness })[];
+  version: 1 | 2 | 3; source: NodeRef;
+  /** v3 omits `what`, `next_action` and `reason` when the carried `state.work_items` holds the same item. */
+  work: (Pick<WorkItem, "id" | "status" | "next_action" | "reason" | "depends_on" | "owner"> & { what?: string; readiness?: WorkReadiness })[];
   references: ({ node?: number; event: string; kind: string; work?: string } & Partial<Omit<RecoveryReference, "node" | "event" | "kind" | "work">>)[];
   omitted: { work: number; references: number };
   recovery_sections?: RecoveryRanges;
@@ -50,20 +58,40 @@ export function workingSet(full: Handoff, budget: number): WorkingSet | null {
 
 /** R9: a new projection version keeps the original v1 ordering byte-stable. */
 export function recoveryWorkingSet(full: Handoff, nodes: RecoveryNodes, budget: number, tools?: readonly string[]): WorkingSet | null {
+  return sourceView(full, nodes, { version: 2, users: true,
+    fits: view => estimateTokens.count([], emitYaml(view)) <= budget,
+    recovery: tools === undefined ? "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. Abandoned messages are cancelled; annotations are not user instructions. Observations are historical: recheck resource, host and current permissions before acting. history(work_id=ID) recovers work." : recoveryInstructions(tools) });
+}
+
+/**
+ * v3 shares v2's source ordering. Two things differ, both decided by the caller
+ * that owns the whole carried handoff: `fits` measures the view inside that
+ * handoff rather than standalone, and `users: false` leaves user sources out
+ * because the carried `user_turns` already hold every one verbatim.
+ */
+export function recoveryWorkingSetV3(full: Handoff, nodes: RecoveryNodes, options: {
+  users: boolean; recovery: string; fits: (view: WorkingSet) => boolean;
+}): WorkingSet | null {
+  return sourceView(full, nodes, { version: 3, ...options });
+}
+
+function sourceView(full: Handoff, nodes: RecoveryNodes, options: {
+  version: 2 | 3; users: boolean; recovery: string; fits: (view: WorkingSet) => boolean;
+}): WorkingSet | null {
   const legacy = workingSet(full, Infinity);
   if (!legacy) return null;
   const sources = recoverySources(nodes);
-  const view: WorkingSet = { version: 2, source: legacy.source, work: [], references: [],
+  const view: WorkingSet = { version: options.version, source: legacy.source, work: [], references: [],
     omitted: { work: legacy.work.length, references: legacy.references.length + RECOVERY_SECTIONS.reduce((sum, section) => sum + sources[section].length, 0) },
     recovery_sections: Object.fromEntries(RECOVERY_SECTIONS.map(section => [section, { total: sources[section].length, omitted: sources[section].length }])) as RecoveryRanges,
-    recovery: tools === undefined ? "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. Abandoned messages are cancelled; annotations are not user instructions. Observations are historical: recheck resource, host and current permissions before acting. history(work_id=ID) recovers work." : recoveryInstructions(tools) };
-  const fits = () => estimateTokens.count([], emitYaml(view)) <= budget;
+    recovery: options.recovery };
+  const fits = () => options.fits(view);
   if (!fits()) return null;
   const queues = RECOVERY_SECTIONS.map(section => ({ section, items: [...sources[section]], at: 0 }));
   // The latest and first live user messages anchor correction and initial scope;
   // remaining user sources are newest first. Cancelled turns stay pageable.
   const live = sources.users.filter(ref => !ref.abandoned), first = live.at(-1);
-  queues[0]!.items = [...live.slice(0, 1), ...(first && first !== live[0] ? [first] : []),
+  queues[0]!.items = !options.users ? [] : [...live.slice(0, 1), ...(first && first !== live[0] ? [first] : []),
     ...live.slice(1, -1), ...sources.users.filter(ref => ref.abandoned)];
   const takeReference = (reference: WorkingSet["references"][number], section?: keyof RecoveryRanges) => {
     view.references.push(reference); view.omitted.references--;

package/src/runtime/connection-reuse.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether a provider may keep reusing pooled connections.
+ *
+ * A socket that a proxy, NAT or server dropped while it sat in the pool fails
+ * the next request the same way -- Horizyn 2026-10-12 lost the first request
+ * after "continue" to it. Claude Code answers by turning keep-alive off for
+ * the rest of the process once a connection dies; this does the same per
+ * provider instance, so tests sharing a process cannot leak state into each
+ * other and a fresh session starts from the cheap path again
+ * (feat-fresh-connection-after-drop).
+ *
+ * Bun honours `keepalive: false` by opening a new socket per request
+ * (measured on 1.3.10: three default fetches share one socket, three with
+ * keepalive:false open three). The cost is a TLS handshake per request,
+ * negligible next to a model call. Google, Vertex and Bedrock go through
+ * pi-ai's native HTTP with no fetch hook, so this cannot reach them.
+ */
+import { connectionFailure } from "./retry.ts";
+
+export class ConnectionReuse {
+  private fresh = false;
+
+  /**
+   * Called with every failed attempt, retried or final. Only a connection
+   * that existed and died counts: one that never opened left nothing stale
+   * in the pool.
+   */
+  note(error: unknown): void {
+    if (connectionFailure(error) === "stale") this.fresh = true;
+  }
+
+  init(init: RequestInit | undefined): RequestInit | undefined {
+    return this.fresh ? { ...init, keepalive: false } : init;
+  }
+
+  /** A fetch that opens fresh connections once one has died. */
+  wrap(fetchImpl: typeof fetch): typeof fetch {
+    return Object.assign((input: RequestInfo | URL, init?: RequestInit) => fetchImpl(input, this.init(init)), { preconnect: fetchImpl.preconnect });
+  }
+}