@visual-z/xeno 0.2.1 → 0.4.0

package/src/core/tool-mode-protocol.ts

@@ -0,0 +1,25 @@
+/** Q.21: the retired orchestration contrast cannot enter new direct-query trials. */
+export const TOOL_MODE_FACTORS = ["querySyntax"] as const;
+export const TOOL_MODE_TASKS = ["tool-small", "tool-batch", "tool-aggregate"] as const;
+export type ToolModeTask = typeof TOOL_MODE_TASKS[number];
+export const isToolModeTask = (task: string): task is ToolModeTask => (TOOL_MODE_TASKS as readonly string[]).includes(task);
+export interface ToolModeEngine { packages: Record<string, string>; assets: Record<string, string> }
+export function validateToolModeEngine(engine: ToolModeEngine | undefined): asserts engine is ToolModeEngine {
+  if (!engine || engine.packages["@earendil-works/pi-ai"] !== "0.99.1" || Object.keys(engine.packages).length !== 1 ||
+    !engine.assets || !Object.entries(engine.assets).every(([path, sha]) =>
+      /^@earendil-works\/pi-ai\/[a-zA-Z0-9_./-]+$/.test(path) && !path.split("/").includes("..") && /^[a-f0-9]{64}$/.test(sha)) ||
+    ["@earendil-works/pi-ai/package.json", "@earendil-works/pi-ai/dist/api/openai-codex-responses.js"].some(path => !engine.assets[path]))
+    throw Error("tool mode engine assets are missing or unsupported");
+}
+export interface ToolModeMetrics {
+  elapsedMs: number; queryCalls: number; primitiveCalls: number;
+  sourcePaths: string[]; requiredSourcePaths: string[]; sourceComplete: boolean;
+}
+export function isToolModeMetrics(value: unknown): value is ToolModeMetrics {
+  if (!value || typeof value !== "object") return false;
+  const v = value as ToolModeMetrics;
+  const paths = (list: unknown): list is string[] => Array.isArray(list) && list.every(item => typeof item === "string") && new Set(list).size === list.length;
+  return Number.isFinite(v.elapsedMs) && v.elapsedMs >= 0 && [v.queryCalls, v.primitiveCalls].every(n => Number.isSafeInteger(n) && n >= 0) &&
+    paths(v.sourcePaths) && paths(v.requiredSourcePaths) && v.requiredSourcePaths.length > 0 &&
+    v.sourceComplete === v.requiredSourcePaths.every(path => v.sourcePaths.includes(path));
+}

package/src/core/transcript.ts

@@ -9,6 +9,8 @@ export type TranscriptItem = Identity & (
   | { kind: "assistant" | "thinking" | "notice"; text: string }
   | { kind: "custom"; text: string; customType: string; data?: unknown; entry: boolean; timestamp: string }
   | { kind: "tool"; callId: string; name: string; input: unknown; result: { text: string; ok: boolean; data?: unknown; images?: readonly ImageRef[] } | null }
+  | { kind: "shell"; command: string; output: string; exit: number; excluded: boolean }
+  | { kind: "segment"; reason: string; handoff: string; nextNode?: number; nextModel?: string }
 );
 
 export function projectTranscript(events: readonly LogEvent[], entryTypes: ReadonlySet<string> = new Set()): TranscriptItem[] {
@@ -26,8 +28,7 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
         users.set(event.id, items.length);
         items.push({ ...identity, kind: "user", text: event.text, interrupted: false, ...(event.images?.length ? { images: event.images } : {}) });
         break;
-      case "user_bash": items.push({ ...identity, kind: "notice",
-        text: `${event.excludeFromContext ? "!!" : "!"}${event.command}\n${event.content}` }); break;
+      case "user_bash": items.push({ ...identity, kind: "shell", command: event.command, output: event.content, exit: event.exit, excluded: event.excludeFromContext }); break;
       case "outcome": items.push({ ...identity, kind: "notice",
         text: `${event.outcome.status} · ${event.outcome.reason} · ${event.reason}` }); break;
       case "assistant":
@@ -39,6 +40,12 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
           } else items.push({ id, revision: id, kind: block.type === "text" ? "assistant" : "thinking", text: block.text });
         });
         break;
+      case "tool_invocation": {
+        if (!event.parent_call_id && !event.origin) break;
+        calls.set(event.call_id, items.length);
+        items.push({ ...identity, kind: "tool", callId: event.call_id, name: event.name, input: event.input ?? { artifact: event.input_ref.sha256 }, result: null });
+        break;
+      }
       case "tool_result": {
         const index = calls.get(event.call_id);
         const call = index === undefined ? undefined : items[index];
@@ -54,13 +61,21 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
         items.push({ ...identity, kind: "notice", text: "Turn interrupted" });
         break;
       }
-      case "cut": items.push({ ...identity, kind: "notice", text: `Context boundary · ${event.reason} · ${event.handoff_ref}` }); break;
+      // A segment boundary is the log's own structure; the view draws it as a divider (D20).
+      case "cut": items.push({ ...identity, kind: "segment", reason: event.reason, handoff: event.handoff_ref,
+        ...(event.next_node === undefined ? {} : { nextNode: event.next_node }), ...(event.next_model === undefined ? {} : { nextModel: event.next_model }) }); break;
       case "rewind": items.push({ ...identity, kind: "notice", text: `Navigated context (${event.mode}) · ${event.prompt}` }); break;
       case "spawn": items.push({ ...identity, kind: "notice", text: `Branch ${event.branch.node} · ${event.purpose}` }); break;
       case "joined": items.push({ ...identity, kind: "notice", text: `Branch ${event.branch.node} finished · ${event.summary}` }); break;
       case "adopt": items.push({ ...identity, kind: "notice", text: `Adopted branch ${event.branch.node}` }); break;
       case "discard": items.push({ ...identity, kind: "notice", text: `Discarded branch ${event.branch.node} · ${event.reason}` }); break;
-      case "guidance": case "snapshot": case "claim": case "decision": case "pitfall": case "blocked": case "question": case "next_action": case "work_status": case "evidence_link":
+      case "skill_loaded": items.push({ ...identity, kind: "notice", text: `Skill ${event.name} · ${event.mode} · ${event.sha256}` }); break;
+      case "process_exit": items.push({ ...identity, kind: "notice", text: `Process ${event.session} exited ${event.exit} · output ${event.output.sha256}` }); break;
+      case "acceptance_contract": items.push({ ...identity, kind: "notice", text: `Acceptance contract · ${event.contract.id}` }); break;
+      case "target_observation": items.push({ ...identity, kind: "notice", text: `Target ${event.observation.target} · ${event.observation.state} · ${event.observation.reason}` }); break;
+      case "acceptance_decision": items.push({ ...identity, kind: "notice", text: `User accepted · ${event.criterion}` }); break;
+      case "checkpoint": case "workspace_observation":
+      case "guidance": case "snapshot": 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.
         break;
       default: assertNever(event, "projectTranscript");

package/src/core/trial-lifecycle.ts

@@ -0,0 +1,14 @@
+/** R12 / Q.14: runner observations complement, but never replace, gateway billing evidence. */
+export type TrialInterruption = { source: "deadline" | "caller"; phase: "initialization" | "execution"; backendRequests: number };
+export type TrialLifecycle = { version: 1; backendRequests: number; interruption: TrialInterruption | null; cleanup: "complete" | "failed" };
+
+export function isTrialLifecycle(value: unknown): value is TrialLifecycle {
+  if (!value || typeof value !== "object") return false;
+  const v=value as Record<string,unknown>, n=v["backendRequests"], interruption=v["interruption"];
+  if (v["version"]!==1 || typeof n!=="number" || !Number.isSafeInteger(n) || n<0 || v["cleanup"]!=="complete" && v["cleanup"]!=="failed") return false;
+  if (interruption===null) return true;
+  if (!interruption || typeof interruption!=="object") return false;
+  const stop=interruption as Record<string,unknown>;
+  return (stop["source"]==="deadline" || stop["source"]==="caller") && (stop["phase"]==="initialization" || stop["phase"]==="execution")
+    && stop["backendRequests"]===n && (stop["phase"]!=="initialization" || n===0);
+}

package/src/core/tui-mode.ts

@@ -0,0 +1,29 @@
+/**
+ * Which screen an interactive session uses. Pure: flag, environment and
+ * setting go in, a concrete mode and the reason come out.
+ *
+ * Fullscreen is the default (OpenCode, grok-build and Pi 1.0 all default to
+ * the alternate screen). `auto` is Codex's / grok-build's policy rather than
+ * "always", because the alternate screen has known dead ends: Zellij keeps
+ * no scrollback for it (zellij#1032, Codex turns it off there), and a dumb
+ * terminal cannot address the screen at all. Every route back to native
+ * scrollback stays: `--tui-mode regular`, `XENO_TUI_MODE`, the setting.
+ */
+export type TuiModeSetting = "auto" | "regular" | "fullscreen";
+export type TuiMode = "regular" | "fullscreen";
+
+export interface TuiModeInput {
+  readonly flag?: TuiMode | undefined;
+  readonly setting?: TuiModeSetting | undefined;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+export function resolveTuiMode(input: TuiModeInput): { mode: TuiMode; reason: string } {
+  if (input.flag) return { mode: input.flag, reason: "--tui-mode" };
+  const fromEnv = input.env["XENO_TUI_MODE"];
+  if (fromEnv === "regular" || fromEnv === "fullscreen") return { mode: fromEnv, reason: "XENO_TUI_MODE" };
+  if (input.setting === "regular" || input.setting === "fullscreen") return { mode: input.setting, reason: "settings" };
+  if (input.env["TERM"] === "dumb") return { mode: "regular", reason: "TERM=dumb cannot draw a fullscreen UI" };
+  if (input.env["ZELLIJ"] !== undefined) return { mode: "regular", reason: "Zellij keeps no scrollback for the alternate screen" };
+  return { mode: "fullscreen", reason: "default" };
+}

package/src/core/update-check.ts

@@ -0,0 +1,97 @@
+/**
+ * Whether to look for a newer xeno and what to say about it (docs/tasks/feat-update-check.md). Pure.
+ *
+ * Notify only: xeno names the command for the way it was installed and never
+ * runs it. At most one registry request a day, recorded even when it fails,
+ * and none at all offline, in CI, when turned off, or from a source checkout
+ * (where the right update is `git pull`, not a package manager). Clock,
+ * environment and the cached answer are all arguments, so every rule is a
+ * plain function of its inputs.
+ */
+import { isUpgrade } from "./version.ts";
+
+export const PACKAGE_NAME = "@visual-z/xeno";
+/** One request a day, like update-notifier; Codex uses 20 hours. Assumed. */
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+export type InstallKind = "bun" | "npm" | "other" | "checkout";
+
+export interface UpdateCache {
+  /** Epoch ms of the last attempt, successful or not. */
+  readonly checkedAt: number;
+  /** The newest published version seen, when the last success had one. */
+  readonly latest?: string;
+}
+
+export interface UpdateInput {
+  readonly current: string;
+  readonly now: number;
+  readonly cache: UpdateCache | null;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly offline: boolean;
+  /** Settings `updateCheck`; undefined means on. */
+  readonly enabled: boolean | undefined;
+  readonly install: InstallKind;
+}
+
+export interface UpdatePlan {
+  /** Ask the registry now. */
+  readonly check: boolean;
+  /** What to tell the person, if anything is newer. */
+  readonly notice?: string;
+}
+
+function truthy(value: string | undefined): boolean {
+  return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
+
+/** Reasons not to send a request at all, in the order they are checked. */
+export function updateDisabled(input: Pick<UpdateInput, "env" | "offline" | "enabled" | "install">): string | undefined {
+  if (input.install === "checkout") return "running from a source checkout";
+  if (input.offline || truthy(input.env["XENO_OFFLINE"])) return "offline";
+  if (input.enabled === false) return "updateCheck is off";
+  if (truthy(input.env["XENO_NO_UPDATE_CHECK"]) || truthy(input.env["NO_UPDATE_NOTIFIER"])) return "turned off by environment";
+  if (truthy(input.env["CI"]) || truthy(input.env["CONTINUOUS_INTEGRATION"])) return "running in CI";
+  return undefined;
+}
+
+export function updatePlan(input: UpdateInput): UpdatePlan {
+  if (updateDisabled(input)) return { check: false };
+  const due = !input.cache || !Number.isFinite(input.cache.checkedAt) || input.now - input.cache.checkedAt >= CHECK_INTERVAL_MS
+    || input.cache.checkedAt > input.now; // a clock set back must not silence checks for a year
+  const latest = input.cache?.latest;
+  return { check: due, ...(latest && isUpgrade(latest, input.current) ? { notice: updateNotice(latest, input.current, input.install) } : {}) };
+}
+
+export function upgradeCommand(install: InstallKind): string | undefined {
+  switch (install) {
+    case "bun": return `bun add -g ${PACKAGE_NAME}@latest`;
+    case "npm": return `npm i -g ${PACKAGE_NAME}@latest`;
+    case "other": case "checkout": return undefined;
+  }
+}
+
+/** Two lines: what is new, then the command on its own line so it can be copied whole. */
+export function updateNotice(latest: string, current: string, install: InstallKind): string {
+  const command = upgradeCommand(install);
+  return `xeno ${latest} is available (you have ${current})\n  ${command ?? "see docs/install.md to update"}`;
+}
+
+/**
+ * How this copy was installed, from where its package root really lives.
+ * Detected from the path rather than by running package managers, which
+ * costs seconds at startup (OpenCode runs up to seven list commands).
+ */
+export function installKind(packageRoot: string, hasGit: boolean): InstallKind {
+  const path = packageRoot.replaceAll("\\", "/");
+  if (hasGit || !path.includes("/node_modules/")) return "checkout";
+  if (path.includes("/.bun/install/global/")) return "bun";
+  if (path.includes("/lib/node_modules/") || /\/npm\/node_modules\//i.test(path)) return "npm";
+  return "other";
+}
+
+/** The registry's dist-tags for the package, honouring npm's registry setting. */
+export function distTagsUrl(registry: string | undefined): string {
+  const base = (registry && /^https?:\/\//.test(registry) ? registry : "https://registry.npmjs.org/").replace(/\/+$/, "");
+  return `${base}/-/package/${PACKAGE_NAME.replace("/", "%2f")}/dist-tags`;
+}

package/src/core/version.ts

@@ -0,0 +1,55 @@
+/**
+ * Semantic version comparison (semver.org §11), without a dependency. Pure.
+ *
+ * Used to decide whether a published version is newer than the running one
+ * (docs/tasks/feat-update-check.md). Anything that does not parse is not a
+ * version, and an unparseable version never produces an update notice.
+ */
+
+export interface Version {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  /** Dot-separated pre-release identifiers; empty for a release. */
+  readonly prerelease: readonly (number | string)[];
+}
+
+const PATTERN = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export function parseVersion(text: string): Version | null {
+  const match = PATTERN.exec(text.trim());
+  if (!match) return null;
+  const numbers = [match[1], match[2], match[3]].map(Number);
+  if (numbers.some(n => !Number.isSafeInteger(n))) return null;
+  const prerelease = match[4] ? match[4].split(".").map(part => /^\d+$/.test(part) ? Number(part) : part) : [];
+  return { major: numbers[0]!, minor: numbers[1]!, patch: numbers[2]!, prerelease };
+}
+
+/** -1, 0 or 1, by §11: numbers, then a release outranks its pre-releases, then identifiers left to right. Build metadata is ignored. */
+export function compareVersions(a: Version, b: Version): -1 | 0 | 1 {
+  for (const key of ["major", "minor", "patch"] as const) if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1;
+  const x = a.prerelease, y = b.prerelease;
+  if (!x.length || !y.length) return x.length === y.length ? 0 : x.length ? -1 : 1;
+  for (let i = 0; i < Math.min(x.length, y.length); i++) {
+    const p = x[i]!, q = y[i]!;
+    if (p === q) continue;
+    if (typeof p === "number" && typeof q === "number") return p < q ? -1 : 1;
+    // Numeric identifiers have lower precedence than alphanumeric ones.
+    if (typeof p === "number") return -1;
+    if (typeof q === "number") return 1;
+    return p < q ? -1 : 1;
+  }
+  return x.length === y.length ? 0 : x.length < y.length ? -1 : 1;
+}
+
+/**
+ * Whether `latest` should be offered to someone running `current`. Never a
+ * downgrade, never something unparseable, and a release is not nudged
+ * towards a pre-release (a pre-release user may move to the next release).
+ */
+export function isUpgrade(latest: string, current: string): boolean {
+  const next = parseVersion(latest), now = parseVersion(current);
+  if (!next || !now) return false;
+  if (next.prerelease.length && !now.prerelease.length) return false;
+  return compareVersions(next, now) > 0;
+}

package/src/core/work-state.ts

@@ -15,8 +15,35 @@ export type WorkItem = {
   evidence?: Evidence;
   /** Reopening keeps provenance without carrying a second copy of old proof. */
   previous_evidence?: string;
+  depends_on?: readonly string[];
+  owner?: string;
+  owner_event?: string;
 };
 
+export type WorkReadiness = { ready: boolean; reason: "ready" | "waiting" | "blocked" | "closed" | "owned" | "missing"; waiting_for: string[] };
+export function workReadiness(items: readonly WorkItem[], id: string, actor?: string): WorkReadiness {
+  const item = items.find(work => work.id === id);
+  if (!item) return { ready: false, reason: "missing", waiting_for: [id] };
+  if (item.status === "completed" || item.status === "cancelled") return { ready: false, reason: "closed", waiting_for: [] };
+  const waiting = (item.depends_on ?? []).filter(dep => items.find(work => work.id === dep)?.status !== "completed");
+  const reason = item.status === "blocked" ? "blocked" : waiting.length ? "waiting" : item.owner && item.owner !== actor ? "owned" : "ready";
+  return { ready: reason === "ready", reason, waiting_for: [...waiting] };
+}
+
+function dependencyError(items: readonly WorkItem[], id: string, dependencies: readonly string[]): string | null {
+  if (new Set(dependencies).size !== dependencies.length) return "duplicate work dependencies";
+  if (dependencies.includes(id)) return "work dependency cycle: self dependency";
+  if (dependencies.some(dep => !items.some(item => item.id === dep))) return "unknown work dependency";
+  const seen = new Set<string>(), pending = [...dependencies];
+  while (pending.length) {
+    const dep = pending.pop()!;
+    if (dep === id) return "work dependency cycle";
+    if (seen.has(dep)) continue;
+    seen.add(dep); pending.push(...items.find(item => item.id === dep)?.depends_on ?? []);
+  }
+  return null;
+}
+
 /** O.2: sibling sessions may choose the same local label without aliasing work. */
 export function scopedWorkId(namespace: string, requested: string, items: readonly WorkItem[]): string {
   return items.some(item => item.id === requested) || requested.startsWith(`${namespace}:`)
@@ -26,6 +53,18 @@ export function scopedWorkId(namespace: string, requested: string, items: readon
 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);
+  if ((event.t === "next_action" || event.t === "work_dependencies") && event.depends_on !== undefined) {
+    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}`;
+  if (event.t === "work_owner") {
+    if (!item) return `unknown work_id ${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`;
+  }
+  if (event.t === "claim" && item && (item.depends_on ?? []).some(dep => items.find(work => work.id === dep)?.status !== "completed")) return "work dependencies are not completed";
   if (event.t === "work_status") {
     // D15 carries post-fork instructions, not their whole history. A harness-
     // authenticated transition may seed intent in the adopted branch, never proof.
@@ -51,13 +90,19 @@ export function deriveWorkItems(previous: readonly WorkItem[], events: readonly
   const items = new Map(previous.map(item => [item.id, { ...item }]));
   for (let index = 0; index < events.length; index++) {
     const event = events[index]!;
-    if (!("work_id" in event) || event.work_id === undefined || workChangeError([...items.values()], event)) continue;
+    if ((event.t !== "next_action" && event.t !== "blocked" && event.t !== "work_status" && event.t !== "claim" && event.t !== "work_dependencies" && event.t !== "work_owner") ||
+        event.work_id === undefined || workChangeError([...items.values()], event)) continue;
     const old = items.get(event.work_id);
-    const item: WorkItem = old ? { ...old, what: event.what, updated_at: event.id } : {
+    const item: WorkItem = old ? { ...old, what: event.t === "work_owner" || event.t === "work_dependencies" ? old.what : event.what, updated_at: event.id } : {
       id: event.work_id, what: event.what, status: "active", verification: "not_run",
       opened_at: event.id, updated_at: event.id,
     };
-    if (event.t === "next_action") item.next_action = event.next_action;
+    if (event.t === "next_action") { item.next_action = event.next_action; if (event.depends_on !== undefined) item.depends_on = [...event.depends_on]; }
+    else if (event.t === "work_dependencies") item.depends_on = [...event.depends_on];
+    else if (event.t === "work_owner") {
+      if (event.operation === "claim") { item.owner = event.owner; item.owner_event = event.id; }
+      else { delete item.owner; delete item.owner_event; }
+    }
     else if (event.t === "blocked") {
       item.status = "blocked";
       item.reason = event.reason;
@@ -89,6 +134,7 @@ export function deriveWorkItems(previous: readonly WorkItem[], events: readonly
       } else { item.verification = "unverified"; item.reason = resolved.reason; }
     }
     items.set(item.id, item);
+    if (item.status === "completed" || item.status === "cancelled") { delete item.owner; delete item.owner_event; }
   }
   return [...items.values()].map(item => {
     if (!item.evidence) return item;

package/src/core/working-set.ts

@@ -0,0 +1,91 @@
+/** O.10: prioritize explicit intent and references without changing D20 arrays. */
+import type { Handoff } from "./handoff.ts";
+import type { NodeRef } from "./events.ts";
+import { workReadiness, type WorkItem, type WorkReadiness } from "./work-state.ts";
+import { emitYaml } from "./yaml.ts";
+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";
+
+export type WorkingSet = {
+  version: 1 | 2; source: NodeRef;
+  work: (Pick<WorkItem, "id" | "what" | "status" | "next_action" | "reason" | "depends_on" | "owner"> & { 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;
+  recovery: string;
+};
+
+export function workingSet(full: Handoff, budget: number): WorkingSet | null {
+  if (!full.predecessor) return null;
+  const items = (full.state.work_items ?? []).filter(item => item.status === "blocked" || item.status === "active")
+    .toSorted((a, b) => Number(b.status === "blocked") - Number(a.status === "blocked") || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const active = new Set(items.map(item => item.id));
+  const references: WorkingSet["references"] = [
+    ...(full.evidence_links ?? []).filter(link => active.has(link.work) && !link.superseded_by)
+      .map(link => ({ event: link.event, kind: "evidence", work: link.work })),
+    ...full.decisions.filter(item => item.work_id && active.has(item.work_id) && item.source)
+      .map(item => ({ node: item.source!.node, event: item.source!.event_id, kind: "decision", work: item.work_id! })),
+    ...full.pitfalls.filter(item => item.work_id && active.has(item.work_id) && item.source)
+      .map(item => ({ node: item.source!.node, event: item.source!.event_id, kind: "pitfall", work: item.work_id! })),
+    ...(full.progress_evidence ?? []).toReversed().map(item => ({ node: item.source.node, event: item.source.event_id, kind: item.kind })),
+  ];
+  const view: WorkingSet = { version: 1, source: full.predecessor, work: [], references: [],
+    omitted: { work: items.length, references: references.length }, recovery: "history(work_id=ID), history(event=ID), or history(node=source.node, section=...)" };
+  const fits = () => budget === Infinity || estimateTokens.count([], emitYaml(view)) <= budget;
+  if (!fits()) return null;
+  for (const item of items) {
+    const { id, what, status, next_action, reason, depends_on, owner } = item;
+    view.work.push({ id, what, status, ...(next_action ? { next_action } : {}), ...(reason ? { reason } : {}),
+      ...(depends_on ? { depends_on, readiness: workReadiness(full.state.work_items ?? [], id) } : {}), ...(owner ? { owner } : {}) });
+    view.omitted.work--;
+    if (!fits()) { view.work.pop(); view.omitted.work++; }
+  }
+  for (const reference of references) {
+    view.references.push(reference); view.omitted.references--;
+    if (!fits()) { view.references.pop(); view.omitted.references++; }
+  }
+  return view;
+}
+
+/** 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 {
+  const legacy = workingSet(full, Infinity);
+  if (!legacy) return null;
+  const sources = recoverySources(nodes);
+  const view: WorkingSet = { version: 2, 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;
+  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] : []),
+    ...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--;
+    if (section) view.recovery_sections![section].omitted--;
+    if (!fits()) {
+      view.references.pop(); view.omitted.references++;
+      if (section) view.recovery_sections![section].omitted++;
+    }
+  };
+  // One source per role precedes work prose; round-robin growth thereafter
+  // prevents a long task list or repeated failures starving other categories.
+  for (const queue of queues) { const reference = queue.items[queue.at++]; if (reference) takeReference(reference, queue.section); }
+  let at = 0;
+  while (at < legacy.work.length || at < legacy.references.length || queues.some(queue => queue.at < queue.items.length)) {
+    const work = legacy.work[at];
+    if (work) {
+      view.work.push(work); view.omitted.work--;
+      if (!fits()) { view.work.pop(); view.omitted.work++; }
+    }
+    for (const queue of queues) { const reference = queue.items[queue.at++]; if (reference) takeReference(reference, queue.section); }
+    const reference = legacy.references[at++];
+    if (reference) takeReference(reference);
+  }
+  return view;
+}

package/src/runtime/auth.ts

@@ -22,6 +22,7 @@ import { providerAccess } from "./provider-access.ts";
 import { SOURCE_PROVIDERS } from "./model-data.ts";
 import {
   refreshOAuthCredential,
+  GROK_PROVIDER, GROK_BASE_URL,
   type OAuthCredential,
   type RefreshEffects,
 } from "./oauth.ts";
@@ -167,6 +168,9 @@ function configuredEffects(spec: ModelSpec, fx: ResolveEffects): { ok: true; eff
   if (providerAccess(spec).invalid) return { ok: false, reason: providerAccess(spec).invalid! };
   try {
     const scoped = providerEnvironment(spec, fx).effects;
+    if (spec.provider === GROK_PROVIDER && spec.baseUrl?.replace(/\/$/, "") !== GROK_BASE_URL) {
+      return { ok: false, reason: "Grok account tokens require the official inference proxy" };
+    }
     const access = providerAccess(spec);
     if (["google-generative-ai", "google-vertex"].includes(spec.api) && (access.auth === false || access.authHeader === false || typeof access.authHeader === "string")) {
       return { ok: false, reason: `${spec.api} owns API-key authentication; use apiKey or an OpenAI-compatible local endpoint` };
@@ -268,6 +272,7 @@ export const ENV_VAR: Readonly<Record<string, string | readonly string[]>> = {
   "google-vertex": "GOOGLE_CLOUD_API_KEY",
   "kimi-coding": ["KIMI_CODING_API_KEY", "KIMI_API_KEY"],
   "openai-codex": "OPENAI_CODEX_ACCESS_TOKEN",
+  "xai-grok": "GROK_ACCESS_TOKEN",
   "ant-ling": "ANT_LING_API_KEY",
   "qwen-token-plan": "QWEN_TOKEN_PLAN_API_KEY",
   "qwen-token-plan-cn": "QWEN_TOKEN_PLAN_CN_API_KEY",
@@ -303,9 +308,11 @@ export function envLabel(provider: string): string {
  * small is the difference between trying the tool and closing it.
  */
 export function describeMissingCredential(provider: string): string {
+  const subscription = provider === "openai-codex" ? "codex" : provider === GROK_PROVIDER ? "grok" : provider === "github-copilot" ? "github-copilot" : undefined;
+  if (subscription) return `no credential for ${provider}. Run /provider ${subscription} to sign in, or export ${envLabel(provider)}`;
   return (
-    `no credential for ${provider}. Either export ${envLabel(provider)}, ` +
-    `or run /login ${provider} to store one in ~/.xeno/auth.json`
+    `no credential for ${provider}. Run /provider ${provider} to add a key, ` +
+    `or export ${envLabel(provider)}`
   );
 }
 
@@ -316,7 +323,7 @@ export interface FreshEffects extends RefreshEffects {
 /**
  * Resolve, refreshing an expired OAuth access token first.
  *
- * A dead refresh fails here and names `/login <provider>`. It does not fall
+ * A dead refresh fails here and names `/provider <provider>`. It does not fall
  * through to the environment: that is the same rule as a stored API key that
  * cannot resolve. Otherwise a forgotten export quietly starts billing a
  * different account.
@@ -349,7 +356,7 @@ export async function ensureFreshCredential(
     if (!refreshed.ok) {
       return {
         ok: false,
-        reason: `${spec.provider} OAuth expired. Run /login ${spec.provider} to sign in again.`,
+        reason: `${spec.provider} OAuth expired. Run /provider ${spec.provider} to sign in again.`,
       };
     }
     const next: AuthFile = { ...stored, [spec.provider]: refreshed.credential };

package/src/runtime/branch-jobs.ts

@@ -0,0 +1,36 @@
+/** O.14: volatile ownership, never a replacement for the durable branch log. */
+export class BranchJobs<T> {
+  private readonly jobs = new Map<number, { controller: AbortController; done: Promise<void>; value?: T; error?: string; detach(): void; ready: boolean }>();
+
+  get active(): number { return [...this.jobs.values()].filter(job => !job.ready).length; }
+  state(node: number): "running" | "ready" | undefined {
+    const job = this.jobs.get(node); return job ? job.ready ? "ready" : "running" : undefined;
+  }
+  nodes(): number[] { return [...this.jobs.keys()]; }
+  start(node: number, controller: AbortController, run: () => Promise<T>, detach: () => void): void {
+    if (this.jobs.has(node)) throw new Error("branch already owned");
+    const job: { controller: AbortController; done: Promise<void>; value?: T; error?: string; detach(): void; ready: boolean } = {
+      controller, ready: false, detach, done: Promise.resolve(),
+    };
+    this.jobs.set(node, job);
+    job.done = run().then(value => { job.value = value; }, () => { job.error = "branch finalization failed; inspect its original log"; })
+      .finally(() => { job.ready = true; job.detach(); });
+  }
+  cancel(node?: number): void {
+    for (const [id, job] of this.jobs) if (node === undefined || node === id) job.controller.abort();
+  }
+  async drain(node?: number): Promise<void> { await Promise.all([...this.jobs].filter(([id]) => node === undefined || node === id).map(([, job]) => job.done)); }
+  async wait(node: number, ms: number): Promise<{ value?: T; error?: string; running: boolean } | undefined> {
+    const job = this.jobs.get(node); if (!job) return undefined;
+    if (!Number.isFinite(ms) || ms < 0 || ms > 60_000) throw new RangeError("wait_ms must be between 0 and 60000");
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      if (!job.ready && ms > 0) await Promise.race([job.done, new Promise<void>(resolve => { timer = setTimeout(resolve, ms); })]);
+    } finally { clearTimeout(timer); }
+    return { ...(job.value !== undefined ? { value: job.value } : {}), ...(job.error ? { error: job.error } : {}), running: !job.ready };
+  }
+  forget(node: number): void {
+    if (this.state(node) === "running") throw new Error("cannot forget a running branch");
+    this.jobs.delete(node);
+  }
+}

package/src/runtime/catalog.ts

@@ -15,6 +15,8 @@
  */
 
 import { assertNever } from "../core/exhaustive.ts";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
 import { modelKey } from "../core/session-position.ts";
 import { mergeCatalogs } from "../core/catalog-merge.ts";
 import { parseModelConfiguration } from "./model-config.ts";
@@ -58,6 +60,8 @@ export function loadCatalog(opts: { userText: string | null; cacheText?: string
         delete next.driver; delete next.compat; delete next.nativeCompat; delete next.thinkingLevelMap;
         if (known.compat) next.compat = known.compat;
         if (known.thinkingLevelMap) next.thinkingLevelMap = known.thinkingLevelMap;
+        if (known.driver) next.driver = known.driver;
+        if (known.nativeCompat) next.nativeCompat = known.nativeCompat;
         if (known.baseUrl !== undefined) next.baseUrl = known.baseUrl;
         copyProviderAccess(spec, next);
         return next;
@@ -233,7 +237,7 @@ export function selectModel(
     reason:
       "no model has a credential. Set an API key for one of: " +
       [...new Set(catalog.map((m) => m.provider))].join(", ") +
-      " -- export its environment variable, or run /login",
+      " -- export its environment variable, or run /provider",
   };
 }
 
@@ -242,11 +246,12 @@ export function createProvider(
   config: ProviderConfig,
   apiKey: string,
   onRetry?: (attempt: number, delayMs: number, error: unknown) => void,
-  opts?: { oauth?: boolean; fetch?: typeof fetch; effects?: ResolveEffects },
+  opts?: { oauth?: boolean; fetch?: typeof fetch; effects?: ResolveEffects; sessionId?: string },
 ): Provider {
   const oauth = opts?.oauth === true;
   if (config.spec.driver === "pi" || hasProviderAccess(config.spec)) return new PiProvider(config, apiKey, {
     oauth,
+    ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
     ...(onRetry ? { onRetry } : {}), ...(opts?.fetch ? { fetch: opts.fetch } : {}), ...(opts?.effects ? { effects: opts.effects } : {}),
   });
   switch (config.spec.api) {
@@ -261,8 +266,13 @@ export function createProvider(
       return new OpenAIResponsesProvider(config, apiKey, { ...(onRetry ? { onRetry } : {}) });
     case "azure-openai-responses": case "openai-codex-responses": case "google-generative-ai": case "google-vertex":
     case "bedrock-converse-stream": case "mistral-conversations": case "pi-messages":
-      return new PiProvider(config, apiKey, { ...(onRetry ? { onRetry } : {}), ...(opts?.fetch ? { fetch: opts.fetch } : {}), ...(opts?.effects ? { effects: opts.effects } : {}) });
+      return new PiProvider(config, apiKey, { ...(onRetry ? { onRetry } : {}), ...(opts?.fetch ? { fetch: opts.fetch } : {}), ...(opts?.effects ? { effects: opts.effects } : {}), ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}) });
     default:
       return assertNever(config.spec.api, "createProvider");
   }
 }
+
+/** D6/D8: routing affinity survives reload and cold resume without server-owned history or path disclosure. */
+export function providerSessionId(logDir: string): string {
+  return createHash("sha256").update(resolve(logDir)).digest("hex");
+}