@visual-z/xeno 0.1.0

package/src/core/work-state.ts

@@ -0,0 +1,103 @@
+/** O.2: identity and lifecycle are explicit; only command evidence can verify completion. */
+import type { LogEvent } from "./events.ts";
+import type { Evidence } from "./handoff.ts";
+import { isCommandResult, resolveEvidence, evidenceStale } from "./evidence.ts";
+
+export type WorkItem = {
+  id: string;
+  what: string;
+  status: "active" | "blocked" | "completed" | "cancelled";
+  verification: "not_run" | "verified" | "unverified" | "stale";
+  opened_at: string;
+  updated_at: string;
+  next_action?: string;
+  reason?: string;
+  evidence?: Evidence;
+  /** Reopening keeps provenance without carrying a second copy of old proof. */
+  previous_evidence?: string;
+};
+
+/** 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}:`)
+    ? requested : `${namespace}:${requested}`;
+}
+
+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 === "work_status") {
+    // D15 carries post-fork instructions, not their whole history. A harness-
+    // authenticated transition may seed intent in the adopted branch, never proof.
+    if (!item && !event.carried_from) return `unknown work_id ${event.work_id}; create it with a next note first`;
+    if (!item) return event.operation !== "cancel" && !event.next_action?.trim()
+      ? "reactivating work requires a current next_action" : null;
+    if (event.operation === "unblock" && item.status !== "blocked") return `work ${item.id} is not blocked`;
+    if (event.operation === "reopen" && item.status !== "completed" && item.status !== "cancelled") {
+      return `work ${item.id} is not closed; update its next action or unblock it`;
+    }
+    if (event.operation !== "cancel" && !event.next_action?.trim()) return "reactivating work requires a current next_action";
+  } else if (event.t === "claim" && !item) {
+    return `unknown work_id ${event.work_id}; record a next note before doing and verifying the work`;
+  } else if (item && (item.status === "completed" || item.status === "cancelled")) {
+    return `work ${item.id} is ${item.status}; explicitly reopen it before updating it`;
+  } else if (event.t === "claim" && item?.status === "blocked") {
+    return `work ${item.id} is blocked; explicitly unblock it before completing it`;
+  }
+  return null;
+}
+
+export function deriveWorkItems(previous: readonly WorkItem[], events: readonly LogEvent[]): WorkItem[] {
+  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;
+    const old = items.get(event.work_id);
+    const item: WorkItem = old ? { ...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;
+    else if (event.t === "blocked") {
+      item.status = "blocked";
+      item.reason = event.reason;
+    } else if (event.t === "work_status") {
+      if (event.operation === "cancel") {
+        item.status = "cancelled";
+        item.reason = event.reason ?? "cancelled";
+        delete item.next_action;
+      } else {
+        item.status = "active";
+        item.next_action = event.next_action!;
+        delete item.reason;
+        if (event.operation === "reopen") {
+          item.opened_at = event.id;
+          item.verification = "not_run";
+          if (item.evidence) item.previous_evidence = item.evidence.event_id;
+          delete item.evidence;
+        }
+      }
+    } else if (event.t === "claim") {
+      // Preserve D11's same-segment rule and require proof from this activation.
+      const resolved = resolveEvidence(events.slice(0, index), event.evidence, item.opened_at);
+      if (resolved.ok) {
+        item.status = "completed";
+        item.verification = "verified";
+        item.evidence = resolved.evidence;
+        delete item.reason;
+        delete item.next_action;
+      } else { item.verification = "unverified"; item.reason = resolved.reason; }
+    }
+    items.set(item.id, item);
+  }
+  return [...items.values()].map(item => {
+    if (!item.evidence) return item;
+    const proof = item.evidence;
+    const later = events.slice(events.findIndex(event => event.id === proof.event_id) + 1);
+    const latest = later.findLast(event => isCommandResult(event) &&
+      (proof.gate ? event.effect.gate === proof.gate : event.effect.cmd === proof.command));
+    const stale = evidenceStale(events, proof, item.verification === "stale") ||
+      (latest !== undefined && isCommandResult(latest) && latest.effect.exit !== 0);
+    return { ...item, verification: stale ? "stale" : "verified" };
+  });
+}

package/src/core/yaml.ts

@@ -0,0 +1,282 @@
+/**
+ * Restricted, deterministic YAML emitter.
+ *
+ * Why hand-written instead of a dependency: YAML emitters differ in indentation,
+ * quoting and line-wrapping defaults, so the usual advice is "pick one writer and
+ * pin its version". A restricted emitter removes the version-drift risk entirely --
+ * the format is fixed by construction, not by someone else's defaults.
+ *
+ * Guarantees:
+ *   - Block style only (the sole exception is `[]` / `{}` for empty collections).
+ *   - Indent 2, LF endings, exactly one trailing newline, no trailing whitespace.
+ *   - No anchors or aliases, so no topological-ordering hazard.
+ *   - Key order comes from an explicit `keyOrder` resolver; unlisted keys are
+ *     appended in sorted order so a new field can never silently vanish.
+ *   - Byte-identical output for equal input: emit(x) === emit(structuredClone(x)).
+ *
+ * Supported value types: string, finite number, boolean, null, array, plain object.
+ * `undefined` values are omitted (that is how optional fields disappear); `null` is
+ * emitted explicitly, so "absent" and "present but empty" stay distinguishable.
+ */
+
+export type YamlValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | readonly YamlValue[]
+  | { readonly [key: string]: YamlValue };
+
+export interface EmitOptions {
+  /**
+   * Returns the preferred key order for the object at `path`, or undefined to
+   * sort alphabetically. Keys returned but absent from the object are skipped;
+   * keys present but unlisted are appended in sorted order.
+   */
+  keyOrder?: (path: readonly string[]) => readonly string[] | undefined;
+}
+
+const INDENT = "  ";
+
+/**
+ * Short all-scalar arrays render in flow style (`[1, 120]`). Nested block
+ * sequences are legal but read badly -- a line range would otherwise print as
+ * "- - 1" / "  - 120" -- and this file is meant to be reviewed by a person.
+ * The rule is a fixed predicate, so output stays deterministic.
+ */
+const FLOW_MAX_WIDTH = 60;
+
+/** YAML 1.1-era tokens that a bare scalar must not collide with. */
+const RESERVED_PLAIN =
+  /^(|~|null|Null|NULL|true|True|TRUE|false|False|FALSE|yes|Yes|YES|no|No|NO|on|On|ON|off|Off|OFF|y|Y|n|N)$/;
+
+const NUMBER_LIKE =
+  /^[+-]?(\d[\d_]*\.?[\d_]*|\.[\d_]+)([eE][+-]?\d+)?$|^[+-]?0[xXoObB][0-9a-fA-F_]+$|^[+-]?\.(inf|Inf|INF)$|^\.(nan|NaN|NAN)$/;
+
+/** Leading characters that carry structural meaning in YAML. */
+const LEADING_INDICATOR = new Set([
+  "-", "?", ":", ",", "[", "]", "{", "}", "#", "&", "*", "!",
+  "|", ">", "'", '"', "%", "@", "`",
+]);
+
+function hasControlChars(s: string): boolean {
+  for (const ch of s) {
+    const c = ch.codePointAt(0)!;
+    // Allow \n (handled by the block-scalar path); reject every other control char.
+    if ((c < 0x20 && c !== 0x0a) || c === 0x7f) return true;
+  }
+  return false;
+}
+
+function isPlainSafe(s: string): boolean {
+  if (s.length === 0) return false;
+  if (s !== s.trim()) return false;
+  if (s.includes("\n") || hasControlChars(s)) return false;
+  if (LEADING_INDICATOR.has(s[0]!)) return false;
+  if (RESERVED_PLAIN.test(s) || NUMBER_LIKE.test(s)) return false;
+  // ": " opens a mapping; " #" opens a comment; a trailing ":" also reads as a key.
+  if (s.includes(": ") || s.includes(" #") || s.endsWith(":")) return false;
+  return true;
+}
+
+function quoteDouble(s: string): string {
+  let out = '"';
+  for (const ch of s) {
+    const c = ch.codePointAt(0)!;
+    if (ch === '"') out += '\\"';
+    else if (ch === "\\") out += "\\\\";
+    else if (ch === "\n") out += "\\n";
+    else if (ch === "\t") out += "\\t";
+    else if (ch === "\r") out += "\\r";
+    else if (c < 0x20 || c === 0x7f) out += "\\x" + c.toString(16).padStart(2, "0");
+    else out += ch;
+  }
+  return out + '"';
+}
+
+/**
+ * A multi-line string is only emitted as a block scalar when every line is clean.
+ * Leading whitespace on the first line would need an explicit indentation
+ * indicator, and trailing whitespace on any line would violate the
+ * no-trailing-whitespace guarantee -- both fall back to a double-quoted scalar,
+ * which is always correct if less pretty.
+ */
+function canUseBlockScalar(s: string): boolean {
+  if (!s.includes("\n")) return false;
+  if (hasControlChars(s)) return false;
+  // `|+` (keep) is the most ambiguous corner of the spec -- parsers disagree about
+  // trailing blank lines at EOF. Two or more trailing newlines therefore fall back
+  // to a quoted scalar rather than relying on that behaviour.
+  if (/\n\n$/.test(s)) return false;
+  const lines = s.split("\n");
+  const firstNonEmpty = lines.find((l) => l.length > 0);
+  if (firstNonEmpty !== undefined && /^\s/.test(firstNonEmpty)) return false;
+  for (const line of lines) {
+    if (line.length > 0 && line !== line.replace(/\s+$/, "")) return false;
+  }
+  return true;
+}
+
+function blockScalar(s: string, indent: string): string {
+  // canUseBlockScalar() guarantees at most one trailing newline here.
+  const trailing = /\n*$/.exec(s)![0].length;
+  const header = trailing === 0 ? "|-" : "|";
+  const body = trailing === 0 ? s : s.slice(0, -1);
+  const inner = indent + INDENT;
+  const lines = body.split("\n").map((l) => (l.length === 0 ? "" : inner + l));
+  return header + "\n" + lines.join("\n");
+}
+
+function scalar(v: string | number | boolean | null, indent: string): string {
+  if (v === null) return "null";
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) {
+      throw new TypeError(`yaml: non-finite number is not emittable: ${v}`);
+    }
+    // Number#toString is the shortest round-trippable form, hence deterministic.
+    // String(-0) drops the sign, so spell it out.
+    return Object.is(v, -0) ? "-0" : String(v);
+  }
+  if (canUseBlockScalar(v)) return blockScalar(v, indent);
+  if (isPlainSafe(v)) return v;
+  return quoteDouble(v);
+}
+
+function isPlainObject(v: unknown): v is { readonly [key: string]: YamlValue } {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+type Scalar = string | number | boolean | null;
+
+function isScalar(v: YamlValue): v is Scalar {
+  return v === null || ["string", "number", "boolean"].includes(typeof v);
+}
+
+/**
+ * Returns the flow rendering (`[a, b]`) when every element is a scalar that needs
+ * no block form and the result fits FLOW_MAX_WIDTH; otherwise undefined, and the
+ * caller falls back to block style.
+ */
+function tryFlow(items: readonly YamlValue[]): string | undefined {
+  if (items.length === 0) return undefined;
+  if (!items.every(isScalar)) return undefined;
+  const parts: string[] = [];
+  for (const item of items as readonly Scalar[]) {
+    if (typeof item === "string" && item.includes("\n")) return undefined;
+    parts.push(scalar(item, ""));
+  }
+  const text = "[" + parts.join(", ") + "]";
+  return text.length <= FLOW_MAX_WIDTH ? text : undefined;
+}
+
+function orderedKeys(
+  obj: { readonly [key: string]: YamlValue },
+  path: readonly string[],
+  opts: EmitOptions,
+): string[] {
+  const present = Object.keys(obj).filter((k) => obj[k] !== undefined);
+  const preferred = opts.keyOrder?.(path);
+  if (!preferred) return present.sort();
+  const set = new Set(present);
+  const ordered = preferred.filter((k) => set.has(k));
+  const rest = present.filter((k) => !preferred.includes(k)).sort();
+  return [...ordered, ...rest];
+}
+
+function emitKey(k: string): string {
+  return isPlainSafe(k) ? k : quoteDouble(k);
+}
+
+function emitNode(
+  v: YamlValue,
+  indent: string,
+  path: readonly string[],
+  opts: EmitOptions,
+  lines: string[],
+): void {
+  if (Array.isArray(v)) {
+    const items = v.filter((x) => x !== undefined);
+    if (items.length === 0) {
+      lines[lines.length - 1] += " []";
+      return;
+    }
+    for (const item of items) {
+      if (Array.isArray(item)) {
+        const flow = tryFlow(item);
+        if (flow !== undefined) {
+          lines.push(indent + "- " + flow);
+          continue;
+        }
+      }
+      if (Array.isArray(item) || isPlainObject(item)) {
+        const before = lines.length;
+        lines.push(indent + "-");
+        emitNode(item, indent + INDENT, path, opts, lines);
+        // Hoist the first child onto the dash line: "- key: value".
+        const dashLine = lines[before]!;
+        const firstChild = lines[before + 1];
+        if (firstChild !== undefined && dashLine === indent + "-") {
+          lines.splice(before, 2, indent + "- " + firstChild.slice(indent.length + INDENT.length));
+        }
+      } else {
+        lines.push(indent + "- " + scalar(item as string | number | boolean | null, indent));
+      }
+    }
+    return;
+  }
+
+  if (isPlainObject(v)) {
+    const keys = orderedKeys(v, path, opts);
+    if (keys.length === 0) {
+      lines[lines.length - 1] += " {}";
+      return;
+    }
+    for (const k of keys) {
+      const child = v[k]!;
+      const childPath = [...path, k];
+      if (Array.isArray(child)) {
+        const items = child.filter((x) => x !== undefined);
+        const flow = tryFlow(items);
+        if (items.length === 0) {
+          lines.push(indent + emitKey(k) + ": []");
+        } else if (flow !== undefined) {
+          lines.push(indent + emitKey(k) + ": " + flow);
+        } else {
+          lines.push(indent + emitKey(k) + ":");
+          // Indent sequences under their key; valid either way, but readable.
+          emitNode(child, indent + INDENT, childPath, opts, lines);
+        }
+      } else if (isPlainObject(child)) {
+        if (orderedKeys(child, childPath, opts).length === 0) {
+          lines.push(indent + emitKey(k) + ": {}");
+        } else {
+          lines.push(indent + emitKey(k) + ":");
+          emitNode(child, indent + INDENT, childPath, opts, lines);
+        }
+      } else {
+        lines.push(
+          indent + emitKey(k) + ": " +
+            scalar(child as string | number | boolean | null, indent),
+        );
+      }
+    }
+    return;
+  }
+
+  lines.push(indent + scalar(v as string | number | boolean | null, indent));
+}
+
+/** Emit `value` as deterministic block-style YAML with a single trailing newline. */
+export function emitYaml(value: YamlValue, opts: EmitOptions = {}): string {
+  if (value === undefined) return "";
+  const lines: string[] = [];
+  if (Array.isArray(value) || isPlainObject(value)) {
+    emitNode(value, "", [], opts, lines);
+  } else {
+    lines.push(scalar(value as string | number | boolean | null, ""));
+  }
+  if (lines.length === 0) return "{}\n";
+  return lines.join("\n") + "\n";
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./core/events.ts";
+export * from "./core/handoff.ts";
+export * from "./core/derive.ts";
+export * from "./core/project.ts";
+export * from "./core/boundary.ts";
+export * from "./core/permissions.ts";
+export * from "./core/tokens.ts";
+export { assertNever } from "./core/exhaustive.ts";
+export * from "./store/log.ts";
+export { emitYaml, type YamlValue, type EmitOptions } from "./core/yaml.ts";

package/src/runtime/auth.ts

@@ -0,0 +1,255 @@
+/**
+ * Where a credential comes from.
+ *
+ * The difficulty here is entirely in the priority, not in the reading, so the
+ * reading is injected: `env` and `run` are parameters. That is what lets the
+ * one rule that actually bites be pinned by a test that touches no
+ * environment and no keychain --
+ *
+ *   A STORED CREDENTIAL OWNS ITS PROVIDER. The environment is consulted only
+ *   when nothing is stored, and never as a fallback after a stored entry
+ *   fails to resolve. Otherwise someone edits `auth.json`, sees no change,
+ *   and has no way to discover that a forgotten `export` from months ago is
+ *   still winning. pi states this rule outright in its resolver; it is worth
+ *   copying verbatim.
+ *
+ * The order is pi's: command line, then `auth.json`, then the environment.
+ * A fourth position belongs to custom providers declared in `models.json`,
+ * which this build does not have yet.
+ */
+
+import { assertNever } from "../core/exhaustive.ts";
+import type { ModelSpec } from "./model.ts";
+import {
+  refreshOAuthCredential,
+  type OAuthCredential,
+  type RefreshEffects,
+} from "./oauth.ts";
+
+export type KeyValue =
+  | { kind: "literal"; value: string }
+  | { kind: "command"; command: string }
+  | { kind: "interpolate"; template: string };
+
+export type StoredCredential =
+  | { type: "api_key"; key: string }
+  | OAuthCredential;
+
+export interface AuthFile {
+  [provider: string]: StoredCredential | undefined;
+}
+
+export function storedIsOAuth(stored: AuthFile, provider: string): boolean {
+  const entry = stored[provider];
+  return entry !== undefined && entry.type === "oauth";
+}
+
+export type Resolved =
+  | { ok: true; key: string; source: "flag" | "auth.json" | "environment" }
+  | { ok: false; reason: string };
+
+/** The two effects resolution needs, injected so the rules stay testable. */
+export interface ResolveEffects {
+  env(name: string): string | undefined;
+  run(command: string): string;
+}
+
+/**
+ * Which of the three forms a configured key value is.
+ *
+ * A plain uppercase string is a LITERAL, not a variable name. That choice
+ * matters: a provider whose key really is `public` or `ollama` is common, and
+ * guessing that an uppercase word means a lookup would break those silently.
+ * `$` marks a lookup, and nothing else does.
+ */
+export function parseKeyValue(raw: string): KeyValue {
+  if (raw.startsWith("!")) return { kind: "command", command: raw.slice(1) };
+  // The escapes are checked before interpolation so a key that genuinely
+  // begins with `$` or `!` can be written down at all.
+  if (raw.startsWith("$$")) return { kind: "literal", value: `$${raw.slice(2)}` };
+  if (raw.startsWith("$!")) return { kind: "literal", value: `!${raw.slice(2)}` };
+  if (raw.includes("$")) return { kind: "interpolate", template: raw };
+  return { kind: "literal", value: raw };
+}
+
+/** `$FOO_BAR` is the variable FOO_BAR; `${FOO}_BAR` is FOO followed by literal text. */
+const VARIABLE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
+export function resolveKeyValue(
+  raw: string,
+  fx: ResolveEffects,
+): { ok: true; key: string } | { ok: false; reason: string } {
+  const parsed = parseKeyValue(raw);
+  switch (parsed.kind) {
+    case "literal":
+      return { ok: true, key: parsed.value };
+
+    case "command": {
+      let out: string;
+      try {
+        out = fx.run(parsed.command);
+      } catch (err) {
+        return { ok: false, reason: `key command failed: ${(err as Error).message}` };
+      }
+      // Every CLI that prints a secret prints a newline after it, and a key
+      // with a trailing newline is rejected by the API as malformed.
+      const key = out.trim();
+      if (key.length === 0) {
+        return { ok: false, reason: `key command produced no output: ${parsed.command}` };
+      }
+      return { ok: true, key };
+    }
+
+    case "interpolate": {
+      const missing: string[] = [];
+      const key = parsed.template.replace(VARIABLE, (_whole, braced?: string, bare?: string) => {
+        const name = braced ?? bare ?? "";
+        const value = fx.env(name);
+        if (value === undefined || value.length === 0) {
+          missing.push(name);
+          return "";
+        }
+        return value;
+      });
+      // Unresolved is NOT the empty string. An empty key looks legal, gets
+      // sent, and comes back as a 401 that says nothing about the real
+      // mistake -- which is that a variable was never exported.
+      if (missing.length > 0) {
+        return { ok: false, reason: `unset environment variable: ${missing.join(", ")}` };
+      }
+      return { ok: true, key };
+    }
+
+    default: {
+      const never: never = parsed;
+      throw new Error(`unreachable key value: ${JSON.stringify(never)}`);
+    }
+  }
+}
+
+export function resolveCredential(
+  spec: ModelSpec,
+  stored: AuthFile,
+  flagKey: string | undefined,
+  fx: ResolveEffects,
+): Resolved {
+  if (flagKey !== undefined && flagKey.length > 0) {
+    const got = resolveKeyValue(flagKey, fx);
+    return got.ok ? { ok: true, key: got.key, source: "flag" } : got;
+  }
+
+  const entry = stored[spec.provider];
+  if (entry !== undefined) {
+    // Deliberately no fallback to the environment on failure. See the header.
+    if (entry.type === "oauth") {
+      return { ok: true, key: entry.access, source: "auth.json" };
+    }
+    if (entry.type === "api_key") {
+      const got = resolveKeyValue(entry.key, fx);
+      return got.ok
+        ? { ok: true, key: got.key, source: "auth.json" }
+        : { ok: false, reason: `${spec.provider} in auth.json: ${got.reason}` };
+    }
+    return assertNever(entry, "stored credential");
+  }
+
+  for (const variable of envVarsOf(spec.provider)) {
+    const value = fx.env(variable);
+    if (value !== undefined && value.length > 0) {
+      return { ok: true, key: value, source: "environment" };
+    }
+  }
+
+  return { ok: false, reason: describeMissingCredential(spec.provider) };
+}
+
+/**
+ * Environment variable each provider reads. Same names pi uses, so a machine
+ * already set up for one works for the other without re-exporting anything.
+ */
+export const ENV_VAR: Readonly<Record<string, string | readonly string[]>> = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  google: ["GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY", "GEMINI_API_KEY"],
+  deepseek: "DEEPSEEK_API_KEY",
+  xai: "XAI_API_KEY",
+  groq: "GROQ_API_KEY",
+  cerebras: "CEREBRAS_API_KEY",
+  mistral: "MISTRAL_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+  zai: "ZHIPU_API_KEY",
+  moonshotai: "MOONSHOT_API_KEY",
+  together: "TOGETHER_API_KEY",
+};
+
+export function envVarsOf(provider: string): readonly string[] {
+  const v = ENV_VAR[provider];
+  // A provider name is free text in a user catalog; an environment variable
+  // is not. `kimi-coding` must become KIMI_CODING, or no shell can set it.
+  if (v === undefined) return [`${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`];
+  return typeof v === "string" ? [v] : v;
+}
+
+export function envLabel(provider: string): string {
+  return envVarsOf(provider).join(" or ");
+}
+
+/**
+ * What to say when there is no credential.
+ *
+ * Both routes, named concretely. The failure a person hits on first run
+ * should carry its own fix; sending them to read the docs for something this
+ * small is the difference between trying the tool and closing it.
+ */
+export function describeMissingCredential(provider: string): string {
+  return (
+    `no credential for ${provider}. Either export ${envLabel(provider)}, ` +
+    `or run /login ${provider} to store one in ~/.xeno/auth.json`
+  );
+}
+
+export interface FreshEffects extends RefreshEffects {
+  persist: (auth: AuthFile) => Promise<void>;
+}
+
+/**
+ * Resolve, refreshing an expired OAuth access token first.
+ *
+ * A dead refresh fails here and names `/login <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.
+ */
+export async function ensureFreshCredential(
+  spec: ModelSpec,
+  stored: AuthFile,
+  flagKey: string | undefined,
+  fx: ResolveEffects,
+  oauth: FreshEffects,
+): Promise<Resolved> {
+  if (flagKey !== undefined && flagKey.length > 0) {
+    return resolveCredential(spec, stored, flagKey, fx);
+  }
+  const entry = stored[spec.provider];
+  if (entry !== undefined && entry.type === "oauth") {
+    if (oauth.now() < entry.expires) {
+      return { ok: true, key: entry.access, source: "auth.json" };
+    }
+    const refreshOpts: RefreshEffects = {
+      fetch: oauth.fetch,
+      now: oauth.now,
+    };
+    if (oauth.signal !== undefined) refreshOpts.signal = oauth.signal;
+    const refreshed = await refreshOAuthCredential(spec.provider, entry, refreshOpts);
+    if (!refreshed.ok) {
+      return {
+        ok: false,
+        reason: `${spec.provider} OAuth expired. Run /login ${spec.provider} to sign in again.`,
+      };
+    }
+    const next: AuthFile = { ...stored, [spec.provider]: refreshed.credential };
+    await oauth.persist(next);
+    return { ok: true, key: refreshed.credential.access, source: "auth.json" };
+  }
+  return resolveCredential(spec, stored, flagKey, fx);
+}