@maycombhq/atticus 0.0.0-stage → 2.0.0-beta.10

package/dist/chunk-ILFKECGI.js

@@ -0,0 +1,69 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  defaultKeyStore
+} from "./chunk-6EDQE7GO.js";
+import "./chunk-5XDNUJ4P.js";
+import "./chunk-577AJVRS.js";
+import "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/secret-commands.js
+var NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin)
+    chunks.push(typeof c === "string" ? Buffer.from(c) : c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function secretCommand(args, io, deps = {}) {
+  const [verb, name] = args;
+  const store = deps.store ?? defaultKeyStore();
+  const env = deps.env ?? process.env;
+  if (!verb || !["set", "check", "forget"].includes(verb) || !name) {
+    io.err("Usage: atticus secret set|check|forget <name>, the name runtime.yaml gives as keyEnv.");
+    return 2;
+  }
+  if (!NAME.test(name)) {
+    io.err(`${name} isn't a variable's name: use letters, digits and _, such as ATTICUS_MODEL_KEY.`);
+    return 2;
+  }
+  if (verb === "set") {
+    if (process.stdin.isTTY && !deps.read)
+      io.out(`Paste the key for ${name}, then press Enter and Ctrl+Z (Windows) or Ctrl+D:`);
+    const value = (await (deps.read ?? readStdin)()).trim();
+    if (!value) {
+      io.err("No key was given: pipe it in, for example from your password manager.");
+      return 2;
+    }
+    try {
+      store.set(name, value);
+    } catch (e) {
+      io.err(e instanceof Error ? e.message : String(e));
+      return 1;
+    }
+    io.out(`Kept ${name} in this machine's credential store. runtime.yaml names it as keyEnv.`);
+    return 0;
+  }
+  if (verb === "forget") {
+    store.forget(name);
+    io.out(`${name} is no longer kept on this machine.`);
+    return 0;
+  }
+  if (env[name]?.trim()) {
+    io.out(`${name} is set in the environment (it is used before the credential store).`);
+    return 0;
+  }
+  if (store.get(name)) {
+    io.out(`${name} is kept in this machine's credential store.`);
+    return 0;
+  }
+  io.out(`${name} isn't set on this machine: atticus secret set ${name} keeps it.`);
+  return 1;
+}
+export {
+  secretCommand
+};

package/dist/chunk-ISNZYKAS.js

@@ -0,0 +1,53 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  ciArchiveGate,
+  ciDrift,
+  ciSnippet,
+  completeGlossaryScan,
+  glossaryAlias,
+  glossaryDefine,
+  glossaryLink,
+  glossaryList,
+  glossaryScan,
+  testsGenerate,
+  traceCommand
+} from "./chunk-ZE3P35DA.js";
+import "./chunk-7YYEKTYF.js";
+import "./chunk-XEG3FE2R.js";
+import "./chunk-KC5DROFC.js";
+import "./chunk-RK6MKKKP.js";
+import "./chunk-VOGCSYOI.js";
+import "./chunk-47QE246J.js";
+import "./chunk-XQ3YIV5R.js";
+import "./chunk-MGVYVW7Q.js";
+import "./chunk-NGPU2ARF.js";
+import "./chunk-AY2IUF4K.js";
+import "./chunk-6JLPXDWN.js";
+import "./chunk-4GZXS6S2.js";
+import "./chunk-R4TBNKKC.js";
+import "./chunk-NIXVDQVO.js";
+import "./chunk-UR7RMZ3R.js";
+import "./chunk-N4QZJJVB.js";
+import "./chunk-PGKHJYOB.js";
+import "./chunk-MKRBG5EF.js";
+import "./chunk-5XDNUJ4P.js";
+import "./chunk-577AJVRS.js";
+import "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+export {
+  ciArchiveGate,
+  ciDrift,
+  ciSnippet,
+  completeGlossaryScan,
+  glossaryAlias,
+  glossaryDefine,
+  glossaryLink,
+  glossaryList,
+  glossaryScan,
+  testsGenerate,
+  traceCommand
+};

package/dist/chunk-IUD3ME4E.js

@@ -0,0 +1,251 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  isCritic
+} from "./chunk-4Q3NN7VF.js";
+import {
+  lensRunOf
+} from "./chunk-47QE246J.js";
+import {
+  CONTEXT_TOOLS
+} from "./chunk-N4QZJJVB.js";
+import {
+  HandoffRuntime,
+  TOOL_LIMITS,
+  modelEnvOf,
+  stepClassOf
+} from "./chunk-5XDNUJ4P.js";
+import {
+  changesRelOf,
+  listQuestions,
+  loadOrgPack,
+  orgPackDirOf,
+  runsDirOf,
+  runsRelOf,
+  stepModelsOf
+} from "./chunk-577AJVRS.js";
+
+// packages/cli/dist/handoff-flag.js
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+var isStage = (group, command) => group === "change" && (command === "feature" || command === "architecture" || command === "small") || group === "plan" && command === "stories";
+async function runStates(root) {
+  const out = /* @__PURE__ */ new Map();
+  const dir = runsDirOf(root);
+  for (const change of await readdir(dir).catch(() => []))
+    for (const id of await readdir(join(dir, change)).catch(() => [])) {
+      const text = await readFile(join(dir, change, id, "run.json"), "utf8").catch(() => "");
+      if (!text)
+        continue;
+      try {
+        const run = JSON.parse(text);
+        out.set(`${change}/${id}`, { key: `${run.state}:${run.attempt}`, run });
+      } catch {
+      }
+    }
+  return out;
+}
+var OWN_MODES = /* @__PURE__ */ new Set(["model", "headless-claude-code"]);
+function modeOf(argv) {
+  const at = argv.findIndex((a) => a === "--mode" || a.startsWith("--mode="));
+  if (at < 0)
+    return "hand-off";
+  const m = argv[at].includes("=") ? argv[at].split("=")[1] : argv[at + 1] ?? "";
+  return OWN_MODES.has(m) ? m : "hand-off";
+}
+function stepArgs(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--handoff" || a === "--json")
+      continue;
+    if (a === "--mode" || a === "--resume") {
+      i++;
+      continue;
+    }
+    if (a.startsWith("--mode=") || a.startsWith("--resume=") || a.startsWith("--handoff="))
+      continue;
+    out.push(a);
+  }
+  return out;
+}
+var shell = (a) => /^[\w./:@=+-]+$/.test(a) ? a : a.includes('"') ? JSON.stringify(a) : `"${a}"`;
+async function handoffStep(root, argv, io, dispatch) {
+  const args = stepArgs(argv);
+  const resumeAt = argv.findIndex((a) => a === "--resume" || a.startsWith("--resume="));
+  const resume = resumeAt < 0 ? [] : argv[resumeAt].includes("=") ? [argv[resumeAt]] : argv.slice(resumeAt, resumeAt + 2);
+  const json = argv.includes("--json");
+  const before = await runStates(root);
+  const asked = json ? await openQuestions(root) : /* @__PURE__ */ new Map();
+  const out = [];
+  const err = [];
+  const facts = [];
+  let code;
+  try {
+    code = await dispatch([...args, ...resume, "--mode", modeOf(argv)], {
+      out: (l) => out.push(l),
+      err: (l) => err.push(l),
+      report: (f) => facts.push(f)
+    });
+  } catch (e) {
+    if (!json)
+      throw e;
+    err.push(e.message.split("\n")[0]);
+    code = 3;
+  }
+  const after = await runStates(root);
+  const byStart = (a, b) => a.startedAt.localeCompare(b.startedAt) || a.runId.localeCompare(b.runId);
+  const critic = isCritic(args[0], args[1]);
+  const stage = isStage(args[0], args[1]);
+  const queue = critic || stage;
+  const changeArg = critic ? args[1] : stage ? args[2] : void 0;
+  const ofChange = (x) => !changeArg || changeArg.startsWith("-") || x.request.change === changeArg;
+  const waiting = [...after].filter(([path, s]) => s.run.state === "waiting" && before.get(path)?.key !== s.key).map(([, s]) => s.run).filter(ofChange).sort(byStart);
+  const resumed = resume.length ? resume.join("=").split("=").at(-1) : void 0;
+  const resumedRun = [...after.values()].find((s) => s.run.runId === resumed)?.run;
+  const named = facts.map((f) => "handoff" in f ? f.handoff.runId : void 0).filter((x) => !!x).at(-1);
+  const namedRun = named ? [...after.values()].find((s) => s.run.runId === named)?.run : void 0;
+  const still = resumedRun && (resumedRun.state === "waiting" || resumedRun.state === "failed" && namedRun?.runId === resumedRun.runId) ? resumedRun : void 0;
+  const next = queue && resumedRun && !still ? [...after.values()].map((s) => s.run).filter((x) => x.state === "waiting" && x.runId !== resumedRun.runId && x.request.change === resumedRun.request.change && x.startedAt >= resumedRun.startedAt && (critic || !!lensRunOf(x.request))).sort(byStart)[0] : void 0;
+  const waitedOn = !resume.length && namedRun && before.get(`${namedRun.request.change}/${namedRun.runId}`) ? namedRun : void 0;
+  const offered = namedRun && ["waiting", "failed"].includes(namedRun.state) ? namedRun : void 0;
+  const run = offered ?? (queue ? waiting[0] : waiting.at(-1)) ?? still ?? next ?? waitedOn ?? void 0;
+  const pagesLeft = facts.map((f) => "pagesLeft" in f ? f.pagesLeft : void 0).filter((x) => x !== void 0).at(-1);
+  const stillOffered = !!run && (run === still || run === waitedOn);
+  if (json)
+    return printJson(root, argv, args, {
+      run,
+      still: stillOffered,
+      code,
+      out,
+      err,
+      asked,
+      ...pagesLeft !== void 0 ? { pagesLeft } : {}
+    }, io);
+  if (!run) {
+    for (const l of out)
+      io.out(l);
+    for (const l of err)
+      io.err(l);
+    return code;
+  }
+  for (const l of err)
+    io.err(l);
+  if (stillOffered)
+    io.out(`Run ${run.runId} is still waiting for its result file.`);
+  const runsRel = runsRelOf(root);
+  io.out(`Prompt: ${HandoffRuntime.promptRel(run, runsRel)}`);
+  io.out(`Result file: ${HandoffRuntime.outputRel(run, changesRelOf(root), runsRel)}`);
+  const expects = await expectedModel(root, run, process.env);
+  if (expects)
+    io.out(expectedLine(expects));
+  io.out("When the result file is written, run:");
+  io.out(`  atticus handoff done ${run.runId}${rootArg(argv)}`);
+  io.out(`  atticus ${[...args, "--handoff", "--resume", run.runId].map(shell).join(" ")}`);
+  return 0;
+}
+async function openQuestions(root) {
+  const r = await listQuestions(root, { state: "open" });
+  return new Map(r.questions.map((q) => [q.id, `${q.askedBy.at}:${q.alsoAskedBy?.length ?? 0}:${q.rerun}`]));
+}
+var questionOut = (q) => ({
+  id: q.id,
+  repo: q.repo,
+  question: q.question,
+  options: q.options,
+  evidence: q.evidence,
+  answer: `atticus questions answer ${q.id}`
+});
+async function printJson(root, argv, args, s, io) {
+  const { run } = s;
+  if (run) {
+    const runsRel = runsRelOf(root);
+    const doneArgs = ["handoff", "done", run.runId, ...rootArgv(argv)];
+    const resumeArgs = [...args, "--handoff", "--json", "--resume", run.runId];
+    const lens = lensRunOf(run.request);
+    const stepClass = run.stepClass ?? stepClassOf(run.request);
+    const orgModel = (await orgModels(root))[stepClass];
+    io.out(JSON.stringify({
+      state: "handoff",
+      runId: run.runId,
+      // ADR 0115: one of the critic's AI lenses, reviewing what the step wrote.
+      ...lens ? { lens } : {},
+      stepClass,
+      ...orgModel ? { orgModel } : {},
+      root,
+      ...s.still ? { stillWaiting: true } : {},
+      promptFile: HandoffRuntime.promptRel(run, runsRel),
+      resultFile: HandoffRuntime.outputRel(run, changesRelOf(root), runsRel),
+      doneCommand: `atticus ${doneArgs.map(shell).join(" ")}`,
+      doneArgs,
+      resumeCommand: `atticus ${resumeArgs.map(shell).join(" ")}`,
+      resumeArgs,
+      // ADR 0107 addendum: the read-only tools the model may call. A tool call runs as
+      // atticus <callArgs> <tool> --input <json> --round <n> --json <runArgs>, kept in the run.
+      tools: {
+        definitions: CONTEXT_TOOLS,
+        limits: TOOL_LIMITS,
+        callArgs: ["context", "call"],
+        runArgs: ["--run", run.runId, ...rootArgv(argv)]
+      },
+      messages: s.out,
+      // ADR 0115 addendum (2026-10-26): what the step said was wrong with an answer it read,
+      // so a tool that runs the loop shows it instead of re-sending the same prompt silently.
+      ...s.err.length ? { errors: s.err } : {}
+    }, null, 2));
+    return 0;
+  }
+  const text = [...s.out, ...s.err].join("\n");
+  const open = (await listQuestions(root, { state: "open" })).questions;
+  const questions = open.filter((q) => {
+    const was = s.asked.get(q.id);
+    return was === void 0 || was !== `${q.askedBy.at}:${q.alsoAskedBy?.length ?? 0}:${q.rerun}` || text.includes(q.id);
+  });
+  const state = questions.length ? "question" : s.code === 0 ? "done" : s.code === 1 ? "stopped" : "failed";
+  io.out(JSON.stringify({
+    state,
+    exitCode: s.code,
+    root,
+    messages: s.out,
+    errors: s.err,
+    questions: questions.map(questionOut),
+    // A batched scan's pages left for the next batch, as data (never read from its words).
+    ...s.pagesLeft !== void 0 ? { pagesLeft: s.pagesLeft } : {}
+  }, null, 2));
+  return s.code;
+}
+async function orgModels(root) {
+  return stepModelsOf(await loadOrgPack(orgPackDirOf(root)).then((op) => op.runtime).catch(() => void 0));
+}
+async function expectedModel(root, run, env) {
+  const stepClass = run.stepClass ?? stepClassOf(run.request);
+  const set = env[modelEnvOf(stepClass)]?.trim();
+  if (set && set !== "atticus")
+    return { stepClass, model: set, from: "setting" };
+  const org = (await orgModels(root))[stepClass];
+  return org ? { stepClass, model: org, from: "runtime.yaml" } : void 0;
+}
+var expectedLine = (e) => `Model: this is a ${e.stepClass} step, which runs on ${e.model} (${e.from === "setting" ? "your setting" : `runtime.yaml models.${e.stepClass}`}). Pick it in your assistant's model picker before you send the prompt.`;
+function rootArgv(argv) {
+  const i = argv.indexOf("--root");
+  if (i >= 0 && argv[i + 1])
+    return ["--root", argv[i + 1]];
+  const eq = argv.find((a) => a.startsWith("--root="));
+  return eq ? [eq] : [];
+}
+function rootArg(argv) {
+  const i = argv.indexOf("--root");
+  if (i >= 0 && argv[i + 1])
+    return ` --root ${shell(argv[i + 1])}`;
+  const eq = argv.find((a) => a.startsWith("--root="));
+  return eq ? ` ${shell(eq)}` : "";
+}
+
+export {
+  handoffStep,
+  expectedModel,
+  expectedLine
+};

package/dist/chunk-IV7BCWWN.js

@@ -0,0 +1,101 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  scanInputs
+} from "./chunk-R4TBNKKC.js";
+import {
+  documentFormat,
+  readDocument
+} from "./chunk-NIXVDQVO.js";
+import {
+  inputsDirOf
+} from "./chunk-577AJVRS.js";
+
+// packages/cli/dist/inputs-knowledge.js
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+var INPUTS_SOURCE_ID = "inputs";
+var INPUTS_SOURCE = {
+  id: INPUTS_SOURCE_ID,
+  type: "markdown-folder",
+  location: "inputs/",
+  spaces: []
+};
+var NOT_TEXT = {
+  image: "a picture: a person reads it, since AI steps take text only",
+  openapi: "an OpenAPI spec: intake reads it into the catalog (atticus intake)",
+  swagger: "a Swagger spec: intake reads it into the catalog (atticus intake)",
+  asyncapi: "an AsyncAPI spec: intake reads it into the catalog (atticus intake)",
+  diagram: "a diagram: intake reads it (atticus intake)",
+  payload: "a payload sample: intake reads its schema (atticus intake)"
+};
+function markdownOf(read) {
+  const out = [`# ${read.text.title}`, ""];
+  for (const s of read.text.sections) {
+    const page = s.page ? ` (page ${s.page})` : "";
+    if (s.heading)
+      out.push(`${"#".repeat(Math.min(6, Math.max(2, s.level + 1)))} ${s.heading}${page}`, "");
+    else if (page)
+      out.push(`(page ${s.page})`, "");
+    if (s.text.trim())
+      out.push(s.text.trim(), "");
+  }
+  for (const t of read.text.tables ?? []) {
+    t.forEach((row, i) => {
+      out.push(`| ${row.map((c) => c.replace(/\|/g, "\\|")).join(" | ")} |`);
+      if (i === 0)
+        out.push(`|${row.map(() => " --- |").join("")}`);
+    });
+    out.push("");
+  }
+  for (const n of read.notes)
+    out.push(`> ${n}`, "");
+  return out.join("\n");
+}
+async function inputsPages(root, op) {
+  const dir = inputsDirOf(root);
+  const intake = await scanInputs({
+    root,
+    orgPack: op,
+    inputsDir: dir,
+    scannedAt: "1970-01-01T00:00:00Z"
+  });
+  const byId = new Map(intake.documents.filter((d) => d.id).map((d) => [d.id, d]));
+  const pages = [];
+  const skipped = [];
+  const skip = (path, reason) => skipped.push({ source: INPUTS_SOURCE_ID, path, reason });
+  for (const d of [...intake.documents].sort((a, b) => a.path < b.path ? -1 : 1)) {
+    if (d.status === "duplicate") {
+      skip(d.path, `the same file as ${d.duplicateOf ?? "another one in inputs/"}`);
+      continue;
+    }
+    if (d.supersededBy) {
+      const newer = byId.get(d.supersededBy)?.path ?? d.supersededBy;
+      skip(d.path, `an older version: ${newer} is newer, and is the one read`);
+      continue;
+    }
+    const why = NOT_TEXT[d.classification];
+    if (why) {
+      skip(d.path, why);
+      continue;
+    }
+    const rel = d.path.replace(/^inputs\//, "");
+    const bytes = new Uint8Array(await readFile(join(dir, ...rel.split("/"))));
+    if (!documentFormat(rel, bytes.slice(0, 4096))) {
+      skip(d.path, "not a document Atticus reads as text");
+      continue;
+    }
+    const content = /\.(md|markdown)$/i.test(rel) ? new TextDecoder().decode(bytes) : markdownOf(readDocument(rel, bytes));
+    pages.push({ pagePath: rel, path: d.path, content });
+  }
+  return { pages, skipped };
+}
+
+export {
+  INPUTS_SOURCE_ID,
+  INPUTS_SOURCE,
+  inputsPages
+};

package/dist/chunk-IZNSAEBX.js

@@ -0,0 +1,164 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  resumedAttempt,
+  stepClassOf
+} from "./chunk-5XDNUJ4P.js";
+import {
+  RUN_SCHEMA_VERSION,
+  STEP_CLASSES,
+  changesDirOf,
+  runsDirOf,
+  runsRelOf
+} from "./chunk-577AJVRS.js";
+
+// packages/cli/dist/runs-view.js
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join, relative, resolve, sep } from "node:path";
+var RUN_ID = /^run-[0-9a-z-]+$/;
+var sha = (s) => createHash("sha256").update(s).digest("hex");
+var dataBlocks = (prompt) => [
+  ...prompt.matchAll(/<atticus-data [^>]*origin="([^"]+)"[^>]*>\n([\s\S]*?)\n<\/atticus-data>/g)
+].map((m) => ({ origin: m[1], text: m[2].trimEnd() }));
+function handedBack(prompt) {
+  const blocks = dataBlocks(prompt);
+  const out = [];
+  for (const b of blocks) {
+    const m = /^checks on attempt (\d+)$/.exec(b.origin);
+    if (!m)
+      continue;
+    const attempt = Number(m[1]);
+    const problems = b.text.split("\n").filter((l) => l.startsWith("- ")).map((l) => l.slice(2).trim());
+    const previous = blocks.find((x) => x.origin === `attempt ${attempt}`)?.text;
+    out.push({
+      attempt,
+      problems,
+      ...previous !== void 0 ? { previousAnswer: previous } : {}
+    });
+  }
+  return out.sort((a, b) => a.attempt - b.attempt);
+}
+async function readStored(root, change, runId) {
+  const dir = join(runsDirOf(root), change, runId);
+  const text = await readFile(join(dir, "run.json"), "utf8").catch(() => void 0);
+  if (!text)
+    return void 0;
+  const run = JSON.parse(text);
+  const prompt = await readFile(join(dir, "prompt.md"), "utf8").catch(() => void 0) ?? run.request.pack?.prompt ?? "";
+  return { run, dir, prompt };
+}
+async function answerOf(root, s) {
+  if (typeof s.run.output === "string")
+    return s.run.output;
+  const out = s.run.request.outputPath;
+  if (!out)
+    return void 0;
+  const inRun = join(s.dir, basename(out));
+  const inChange = resolve(changesDirOf(root), s.run.request.change, out);
+  const candidates = [inRun];
+  if (s.run.request.outputIn !== "run" && !relative(changesDirOf(root), inChange).startsWith(".."))
+    candidates.push(inChange);
+  for (const f of candidates) {
+    const t = await readFile(f, "utf8").catch(() => void 0);
+    if (t !== void 0)
+      return t;
+  }
+  return void 0;
+}
+async function item(root, s) {
+  const r = s.run;
+  const manifest = await readFile(join(s.dir, "context-manifest.json"), "utf8").catch(() => "");
+  const attempt = r.request.pack?.manifest ? resumedAttempt(r).attempt : r.attempt ?? 1;
+  const back = handedBack(s.prompt);
+  const answer = await answerOf(root, s);
+  const agent = r.request.agent;
+  return {
+    schemaVersion: RUN_SCHEMA_VERSION,
+    runId: r.runId,
+    change: r.request.change,
+    agent: typeof agent === "string" ? agent : agent.id,
+    runtime: r.runtime,
+    state: r.state,
+    startedAt: r.startedAt,
+    ...r.finishedAt ? { finishedAt: r.finishedAt } : {},
+    ...r.request.outputPath ? { output: r.request.outputPath } : {},
+    ...r.usage ? { usage: r.usage } : {},
+    contextManifestSha256: sha(manifest),
+    promptPath: `${runsRelOf(root)}/${r.request.change}/${r.runId}/prompt.md`,
+    attempt,
+    answered: answer !== void 0,
+    handedBack: back.reduce((n, b) => n + b.problems.length, 0),
+    ...r.request.pack?.manifest ? { promptTokens: r.request.pack.manifest.totalTokens } : {},
+    ...r.tools ? { toolCalls: r.tools.calls.length } : {},
+    // ADR 0121 addendum: the kind of step and the model that ran it. A run kept before either
+    // was recorded is given its kind from its agent; its model stays unsaid.
+    ...classOf(r) ? { stepClass: classOf(r) } : {},
+    ...r.model ? { model: r.model } : {}
+  };
+}
+function classOf(r) {
+  if (r.stepClass && STEP_CLASSES.includes(r.stepClass))
+    return r.stepClass;
+  const agent = r.request.agent;
+  return agent && typeof agent === "object" && "id" in agent ? stepClassOf(r.request) : void 0;
+}
+async function allRuns(root, change) {
+  const out = [];
+  const changes = change ? [change] : await readdir(runsDirOf(root)).catch(() => []);
+  for (const c of changes) {
+    if (c.includes("/") || c.includes("\\") || c.includes("..") || c.includes(sep))
+      continue;
+    for (const id of await readdir(join(runsDirOf(root), c)).catch(() => [])) {
+      if (!RUN_ID.test(id))
+        continue;
+      const s = await readStored(root, c, id);
+      if (s)
+        out.push(s);
+    }
+  }
+  return out;
+}
+async function listRuns(root, o = {}) {
+  const items = await Promise.all((await allRuns(root, o.change)).map((s) => item(root, s)));
+  items.sort((a, b) => b.startedAt.localeCompare(a.startedAt) || b.runId.localeCompare(a.runId));
+  return items.slice(0, o.limit ?? 200);
+}
+async function runTranscript(root, runId) {
+  if (!RUN_ID.test(runId))
+    return void 0;
+  const all = await allRuns(root);
+  const s = all.find((x) => x.run.runId === runId);
+  if (!s)
+    return void 0;
+  const agentOf = (x) => {
+    const a = x.run.request.agent;
+    return typeof a === "string" ? a : a.id;
+  };
+  const same = all.filter((x) => x.run.request.change === s.run.request.change && agentOf(x) === agentOf(s));
+  const rounds = await Promise.all(same.map((x) => item(root, x)));
+  rounds.sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.runId.localeCompare(b.runId));
+  const answer = await answerOf(root, s);
+  return {
+    run: await item(root, s),
+    prompt: s.prompt,
+    ...answer !== void 0 ? { answer } : {},
+    ...s.run.tools ? { tools: s.run.tools } : {},
+    ...s.run.request.retrieval ? { retrieval: s.run.request.retrieval } : {},
+    handedBack: handedBack(s.prompt),
+    rounds: rounds.map((x) => ({
+      runId: x.runId,
+      attempt: x.attempt,
+      state: x.state,
+      startedAt: x.startedAt
+    }))
+  };
+}
+
+export {
+  listRuns,
+  runTranscript
+};