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

package/dist/chunk-UBBC2XSG.js

@@ -0,0 +1,873 @@
+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 {
+  loadReadPlan,
+  partOfWords,
+  readPlanProgress,
+  readPlanRelOf,
+  writeReadPlan
+} from "./chunk-FQXYPF7E.js";
+import {
+  carryOf,
+  checkoutOf,
+  excludesOf,
+  headOf,
+  raiseReadQuestions,
+  readCorrections,
+  readReviewed,
+  reviewedProblemsOf,
+  writeVerifyFiles
+} from "./chunk-CR3MTH32.js";
+import "./chunk-O3WI5KWW.js";
+import {
+  ABOUT_RULE,
+  assistantTier,
+  mapBatchInstructions,
+  readProbes,
+  tierSource,
+  tierWords
+} from "./chunk-IPKHE5D6.js";
+import {
+  FILE_KINDS,
+  SESSION_TOKENS,
+  SHOWN_PROPOSALS,
+  dirSource,
+  exclusionYaml,
+  frameworkTopics,
+  frameworkTopicsOfType,
+  kindsOf,
+  numberedSlice,
+  onlyFiles,
+  planBatches,
+  planParts,
+  proposeExclusions,
+  rereadPlan,
+  sameCommit,
+  sliceText,
+  staleMessage,
+  verifyFacts
+} from "./chunk-PAMPPUR6.js";
+import {
+  loadRepos
+} from "./chunk-EFHQ3TWP.js";
+import "./chunk-GQ4N4WKF.js";
+import {
+  DATA_RULE,
+  HandoffRuntime,
+  PromptTooLong,
+  buildContextPack,
+  currentPromptLimit,
+  estimateTokens,
+  promptBudget,
+  wrapData
+} from "./chunk-CNUKCS2T.js";
+import {
+  AgentDefinition,
+  Fact,
+  REPO_DESCRIPTION_MAX,
+  citedFiles,
+  descriptionNote,
+  descriptionTrust,
+  factsDirOf,
+  factsRelOf,
+  listQuestions,
+  loadOrgPack,
+  orgPackDirOf,
+  parseFacts,
+  runsDirOf,
+  saysNotProduct
+} from "./chunk-S2A7YC3Q.js";
+import {
+  writeFileAtomic
+} from "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/map-commands.js
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+var REPO_READER = "repo-reader";
+var OUTPUT = "facts.jsonl";
+var KEPT_RESERVE = 1500;
+var MIN_KEPT_RESERVE = 1200;
+var MIN_ROOM = 300;
+var EXAMPLE_LIMIT = 12078;
+var AROUND = 12;
+function repoReaderAgent(op) {
+  const own = op?.agents.find((a) => a.id === REPO_READER);
+  if (own)
+    return own;
+  return AgentDefinition.parse({
+    schemaVersion: 1,
+    id: REPO_READER,
+    role: "architect",
+    description: "Reads a repo's code into facts (ADR 0124): what it answers to, calls, stores, the fields that cross those boundaries, its deployment and config, each citing its file and line.",
+    inputs: ["repo-code"],
+    outputArtifact: "data",
+    tokenBudget: op?.runtime.budgets.defaultTokens ?? 15e4,
+    allowedRuntimes: ["hand-off", "model", "headless-claude-code", "mock", "replay"]
+  });
+}
+var plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+var batches = (n) => `${n} ${n === 1 ? "batch" : "batches"}`;
+var changeOf = (repo) => `map-${repo}`;
+var stateFile = (root, repo) => join(runsDirOf(root), changeOf(repo), "state.json");
+async function readState(root, repo) {
+  const text = await readFile(stateFile(root, repo), "utf8").catch(() => void 0);
+  return text ? JSON.parse(text) : void 0;
+}
+async function saveState(root, s) {
+  await mkdir(dirname(stateFile(root, s.repo)), { recursive: true });
+  await writeFileAtomic(stateFile(root, s.repo), JSON.stringify(s, null, 2) + "\n");
+}
+var LEVELS = ["public", "internal", "confidential", "restricted"];
+function instructionTokens(repo, commit, kinds = [], frameworks) {
+  return (
+    // The rule asking what the repo is (ADR 0128) isn't counted here: it is paid for out of the
+    // reserve below (`reserveFor`), so the room planned for files is what it always was.
+    estimateTokens(mapBatchInstructions({ repo, commit, batch: 999, of: 999, kinds, frameworks })) + estimateTokens(DATA_RULE) + // the <atticus-data> wrapper around the batch's files
+    60
+  );
+}
+async function aboutOf(root, repo) {
+  return (await loadRepos(root).catch(() => [])).find((r) => r.id === repo)?.description;
+}
+function aboutSource(repo, d) {
+  return {
+    id: "6-about",
+    kind: "document",
+    origin: "repos.manifest.yaml",
+    text: descriptionNote(repo, d),
+    classification: "internal",
+    priority: 9
+  };
+}
+var aboutTokens = (repo, d) => d ? estimateTokens(wrapData({ id: "6-about", origin: "repos.manifest.yaml", kind: "document" }, descriptionNote(repo, d))) : 0;
+var overheadOf = (repo, commit, frameworks) => {
+  const core = instructionTokens(repo, commit, [], frameworks);
+  return (kinds) => instructionTokens(repo, commit, kinds, frameworks) - core;
+};
+async function frameworksFor(root, repo, facts) {
+  const fromFacts = frameworkTopics(facts);
+  if (fromFacts)
+    return fromFacts;
+  const type = (await loadRepos(root).catch(() => [])).find((r) => r.id === repo)?.type;
+  return frameworkTopicsOfType(type);
+}
+var joinKinds = (a, b) => FILE_KINDS.filter((k) => a.includes(k) || b.includes(k));
+function claimOf(f) {
+  switch (f.kind) {
+    case "entry":
+    case "call":
+      return `${f.method ? `${f.method} ` : ""}${f.path}`;
+    case "store":
+      return `${f.op} ${f.store} ${f.name}`;
+    case "field":
+      return `${f.owner}.${f.name}`;
+    case "deploy":
+      return `${f.platform}${f.resourceName ? ` ${f.resourceName}` : ""}`;
+    case "config":
+      return f.key;
+    case "framework":
+      return `${f.name}${f.version ? ` ${f.version}` : ""}`;
+    case "flow":
+      return f.name;
+  }
+}
+function readAnswer(text, repo, commit) {
+  const facts = /* @__PURE__ */ new Map();
+  const questions = [];
+  const problems = [];
+  let about;
+  text.split(/\r?\n/).forEach((raw, i) => {
+    const line = raw.trim();
+    if (!line || line.startsWith("```"))
+      return;
+    let json;
+    try {
+      json = JSON.parse(line);
+    } catch {
+      problems.push(`line ${i + 1} is not one JSON object: ${line.slice(0, 80)}`);
+      return;
+    }
+    if (!json || typeof json !== "object" || Array.isArray(json)) {
+      problems.push(`line ${i + 1} is not one JSON object`);
+      return;
+    }
+    const o = json;
+    if ("question" in o && !("kind" in o)) {
+      questions.push(o);
+      return;
+    }
+    if ("about" in o && !("kind" in o)) {
+      const text2 = typeof o.about === "string" ? o.about.trim() : "";
+      if (!text2) {
+        problems.push(`line ${i + 1}: "about" needs one line saying what the repo is`);
+        return;
+      }
+      const cites = (Array.isArray(o.cites) ? o.cites : []).flatMap((c) => {
+        const x = c;
+        return typeof x.file === "string" && Number.isInteger(x.line) && Number(x.line) > 0 ? [{ file: x.file, line: Number(x.line) }] : [];
+      }).slice(0, 6);
+      if (!cites.length) {
+        problems.push(`line ${i + 1}: "about" needs "cites": the file and line it was read from, as a fact cites its line`);
+        return;
+      }
+      about ??= { text: text2.slice(0, REPO_DESCRIPTION_MAX), cites };
+      return;
+    }
+    const r = Fact.safeParse({ repo, commit, ...o, verified: "none", by: "assistant" });
+    if (r.success)
+      facts.set(r.data.id, r.data);
+    else
+      problems.push(`line ${i + 1}${typeof o.id === "string" ? ` (${o.id})` : ""}: ${r.error.issues.map((x) => `${x.path.join(".") || "(fact)"}: ${x.message}`).join("; ")}`);
+  });
+  return { facts: [...facts.values()], questions, problems, ...about ? { about } : {} };
+}
+function rejectedText(r, source) {
+  const text = source.read(r.fact.cite.file);
+  const lines = text?.split(/\r?\n/).length ?? 0;
+  const from = Math.max(1, r.fact.cite.line - AROUND);
+  const to = Math.min(lines, r.fact.cite.line + AROUND);
+  return [
+    `${r.fact.id} was rejected (${r.code}): ${r.message}`,
+    `The fact: ${JSON.stringify(r.fact)}`,
+    ...text !== void 0 && from <= to ? [
+      `${r.fact.cite.file} lines ${from}-${to} (numbered as in the file):`,
+      numberedSlice(text, { from, to })
+    ] : []
+  ].join("\n");
+}
+function questionsText(qs) {
+  return [
+    "Questions already on file for this repo. Don't ask them again; follow each answer a person gave.",
+    ...qs.map((q) => `- ${q.question} (${q.evidence.join(", ")}): ${q.state === "answered" ? `answered: ${q.answer?.text ?? q.options[(q.answer?.option ?? 1) - 1]?.label ?? ""}` : "waiting for a person"}`)
+  ].join("\n");
+}
+function keptText(facts, budgetTokens) {
+  const head = "Facts already kept (id, kind, claim, where). Name them by id; don't write them again.";
+  const order = ["entry", "call", "store", "flow", "deploy", "config", "field"];
+  const sorted = [...facts].sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind) || a.id.localeCompare(b.id));
+  const out = [head];
+  let used = estimateTokens(head);
+  for (const [i, f] of sorted.entries()) {
+    const l = `- ${f.id} (${f.kind}): ${claimOf(f)} [${f.cite.file}:${f.cite.line}]`;
+    if (used + estimateTokens(l) > budgetTokens - 20) {
+      out.push(`... and ${sorted.length - i} more`);
+      break;
+    }
+    out.push(l);
+    used += estimateTokens(l);
+  }
+  return out.join("\n");
+}
+async function readFactsFile(root, repo) {
+  const file = join(factsDirOf(root), `${repo}.jsonl`);
+  if (!existsSync(file))
+    return [];
+  const parsed = parseFacts(await readFile(file, "utf8"));
+  if (parsed.ok)
+    return parsed.facts;
+  return `${factsRelOf(root)}/${repo}.jsonl does not read as facts (${parsed.issues[0]?.message ?? "?"}); fix it, or start again with --force after moving it aside.`;
+}
+function rereadInstructions(s) {
+  const r = s.reread;
+  return [
+    `This is a re-read: the facts were read at ${r.from.map((c) => c.slice(0, 12)).join(", ")}, and the checkout moved to ${s.commit}. Only the files changed since are in these batches.`,
+    `The ${plural(r.facts, "fact")} that cite a changed file are listed below as rejected (cite-changed): read the file again (a renamed file under its new path) and write each again at this commit under the same id, with its line as it is now, or leave it out if the code no longer says it.`,
+    `The other ${plural(r.carried, "fact")} cite files that didn't change: they are kept and carried to this commit. Don't write them again; name them by id.`,
+    "Write a fact for anything new in the changed files, as in a first read."
+  ].join("\n");
+}
+async function rereadOf(dir, facts, commit, source, exclude, git) {
+  if (!facts.some((f) => !sameCommit(f.commit, commit)))
+    return { missing: [] };
+  const { carry, missing } = await carryOf(dir, facts, commit, git);
+  if (!Object.keys(carry).length)
+    return { missing };
+  return { plan: rereadPlan({ facts, commit, carry, source, exclude }), missing };
+}
+async function packFor(root, s, batch, source, op, now) {
+  const agent = repoReaderAgent(op);
+  const budget = op.runtime.budgets.perAgent[agent.id] ?? agent.tokenBudget;
+  const fix = batch >= s.batches.length;
+  const about = await aboutOf(root, s.repo);
+  const reserve = reserveFor(s.repo, about);
+  const kept = await readFactsFile(root, s.repo);
+  const facts = typeof kept === "string" ? [] : kept;
+  const onFile = (await listQuestions(root, { repo: s.repo })).questions.filter((q) => q.state !== "retired");
+  const slices = fix ? [] : s.batches[batch];
+  const rejected = s.rejected.map((r) => rejectedText(r, source));
+  const own = kindsOf(slices.map((x) => x.path));
+  const theirs = kindsOf(s.rejected.flatMap((r) => citedFiles(r.fact)));
+  const both = joinKinds(own, theirs);
+  const extra = instructionTokens(s.repo, s.commit, both) - instructionTokens(s.repo, s.commit, own);
+  const kinds = fix ? theirs : extra + rejected.reduce((n, t) => n + estimateTokens(t), 0) <= reserve ? both : own;
+  const sources = [
+    {
+      id: "0-instructions",
+      kind: "instruction",
+      origin: "atticus/map",
+      text: mapBatchInstructions({
+        repo: s.repo,
+        commit: s.commit,
+        batch: batch + 1,
+        of: s.batches.length,
+        ...fix ? { fix: true } : {},
+        kinds,
+        // A-framework: the frameworks the repo's own facts declare, else its type's hint. The
+        // build files are read first, so from the second batch on this is what the code says.
+        frameworks: await frameworksFor(root, s.repo, facts),
+        // Nothing says what this repo is: ask for one line, cited, for a person to confirm.
+        ...about ? {} : { askAbout: true }
+      }),
+      classification: "public",
+      trusted: true
+    },
+    ...s.reread ? [
+      {
+        id: "0-reread",
+        kind: "instruction",
+        origin: "atticus/map",
+        text: rereadInstructions(s),
+        classification: "public",
+        trusted: true
+      }
+    ] : [],
+    ...slices.length ? [
+      {
+        id: "1-files",
+        kind: "code",
+        origin: slices.map((x) => `${x.path}#L${x.from}-${x.to}`).join(", "),
+        text: slices.map((x) => sliceText(source, x)).join("\n\n"),
+        classification: "internal",
+        priority: 10
+      }
+    ] : [],
+    ...s.rejected.map((r, i) => ({
+      id: `2-rejected-${String(i + 1).padStart(3, "0")}`,
+      kind: "document",
+      origin: `${factsRelOf(root)}/${s.repo}.rejected.jsonl`,
+      text: rejected[i],
+      classification: "internal",
+      priority: 6
+    })),
+    ...s.problems.length ? [
+      {
+        id: "3-problems",
+        kind: "document",
+        origin: "the last answer",
+        text: `Lines of your last answer that weren't kept:
+${s.problems.map((p) => `- ${p}`).join("\n")}`,
+        classification: "internal",
+        priority: 5
+      }
+    ] : [],
+    ...onFile.length ? [
+      {
+        id: "4-questions",
+        kind: "document",
+        origin: "questions/",
+        text: questionsText(onFile),
+        classification: "internal",
+        priority: 4
+      }
+    ] : [],
+    // What a person says the repo is (ADR 0128), as data: it orients the read, never leads it.
+    ...about ? [aboutSource(s.repo, about)] : [],
+    ...facts.length ? [
+      {
+        id: "5-kept",
+        kind: "document",
+        origin: `${factsRelOf(root)}/${s.repo}.jsonl`,
+        text: keptText(facts, reserve),
+        classification: "internal",
+        priority: 3
+      }
+    ] : []
+  ];
+  const levels = op.pack?.classification ?? LEVELS;
+  return {
+    agent,
+    pack: buildContextPack({
+      change: changeOf(s.repo),
+      agent: agent.id,
+      budget,
+      sources,
+      levels,
+      maxClassification: levels.includes("internal") ? "internal" : levels.at(-1),
+      now,
+      ...s.maxTokens ? { maxTokens: s.maxTokens } : {},
+      required: slices.length ? ["1-files"] : [],
+      step: `map ${s.repo}`
+    })
+  };
+}
+var COPY_START = "----- copy from here -----";
+var COPY_END = "----- to here -----";
+function limitOf(o, op, tier) {
+  const given = o.maxTokens ?? currentPromptLimit();
+  if (given !== void 0)
+    return { limit: given, from: "flag" };
+  if (tier?.maxTokensFrom === "probe" && tier.maxTokens !== void 0)
+    return { limit: tier.maxTokens, from: "probe" };
+  const maxInput = op.runtime.adapters.model?.settings.maxInput;
+  return typeof maxInput === "number" ? { limit: maxInput, from: "runtime.yaml" } : {};
+}
+async function tierHere(root, op) {
+  return assistantTier(op.runtime, { probes: (await readProbes(root)).results });
+}
+function roomFor(limit, op, repo, commit) {
+  const agent = repoReaderAgent(op);
+  const budget = op.runtime.budgets.perAgent[agent.id] ?? agent.tokenBudget;
+  const fitted = limit === void 0 ? budget : Math.min(budget, promptBudget(limit));
+  return fitted - instructionTokens(repo, commit) - KEPT_RESERVE;
+}
+function reserveFor(repo, about) {
+  const cost = about ? aboutTokens(repo, about) : estimateTokens(ABOUT_RULE);
+  return Math.max(MIN_KEPT_RESERVE, KEPT_RESERVE - cost);
+}
+async function mapCommand(root, repo, o, io, deps = {}) {
+  const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+  const dir = await checkoutOf(root, repo, o.dir);
+  if (!dir || !existsSync(dir)) {
+    io.err(`No checkout of ${repo}: clone it (atticus workspace sync) or give its folder with --dir.`);
+    return 2;
+  }
+  const commit = o.commit ?? await headOf(dir);
+  if (!commit || !/^[0-9a-f]{7,64}$/.test(commit)) {
+    io.err(`${dir} has no Git commit to read at; give one with --commit <sha> (every fact names the commit it was read at).`);
+    return 2;
+  }
+  const op = await loadOrgPack(orgPackDirOf(root));
+  const source = dirSource(dir);
+  const exclude = await excludesOf(root, repo);
+  const factsFile = `${factsRelOf(root)}/${repo}.jsonl`;
+  if (o.estimate)
+    return estimate(root, repo, { o, op, dir, commit, source, exclude, factsFile, ...deps.git ? { git: deps.git } : {} }, io);
+  const runtime = deps.runtime;
+  if (!runtime) {
+    io.err("atticus map needs an AI runtime: run it with --handoff, --copy or --mode <mode>.");
+    return 2;
+  }
+  let s = await readState(root, repo);
+  const continuing = o.next || o.resume !== void 0 || o.copy && o.answer !== void 0;
+  if (continuing) {
+    if (!s || s.done || !s.waiting && o.answer !== void 0) {
+      io.err(`No read of ${repo} is waiting for an answer. Start one with atticus map ${repo}${o.copy ? " --copy" : " --handoff"}.`);
+      return 2;
+    }
+    if (o.resume && o.resume !== s.waiting?.runId) {
+      io.err(`${o.resume} isn't the run the read of ${repo} waits for${s.waiting ? ` (it waits for ${s.waiting.runId})` : ""}.`);
+      return 2;
+    }
+  }
+  if (continuing && s?.waiting) {
+    const runId = s.waiting.runId;
+    if (o.copy && o.answer !== void 0) {
+      const text = o.answer === "-" ? await (deps.stdin ?? readStdin)() : await readFile(o.answer, "utf8").catch(() => void 0);
+      if (text === void 0) {
+        io.err(`Can't read ${o.answer}: save the assistant's answer to that file first.`);
+        return 2;
+      }
+      const out = join(runsDirOf(root), changeOf(repo), runId, OUTPUT);
+      await mkdir(dirname(out), { recursive: true });
+      await writeFile(out, text, "utf8");
+    }
+    let run = await runtime.result(runId);
+    const resultFile = join(runsDirOf(root), changeOf(repo), runId, OUTPUT);
+    if (run.state === "waiting" && runtime instanceof HandoffRuntime && existsSync(resultFile))
+      run = await runtime.done(runId);
+    if (run.state === "waiting" || run.state === "prepared") {
+      io.out(`Run ${runId} is still waiting for its result file: write it, then atticus map ${repo} --next.`);
+      io.report?.({ handoff: { runId } });
+      return 0;
+    }
+    const r = await takeAnswer(root, s, run, s.waiting.batch, source, exclude, now, io, {
+      dir,
+      ...deps.git ? { git: deps.git } : {}
+    });
+    if (typeof r === "number")
+      return r;
+    s = r;
+  } else if (!continuing) {
+    if (s && !s.done && !o.force) {
+      io.out(`A read of ${repo} is under way (batch ${(s.waiting?.batch ?? s.next) + 1} of ${s.batches.length}${s.waiting ? `, waiting for run ${s.waiting.runId}` : ""}). Continue it with atticus map ${repo} --next${o.copy ? " (--copy --answer <file> to paste the answer)" : ""}; start again with --force.`);
+      if (s.waiting) {
+        if (o.copy)
+          return printCopy(s, runtime, io);
+        io.report?.({ handoff: { runId: s.waiting.runId } });
+      }
+      return 0;
+    }
+    const existing = await readFactsFile(root, repo);
+    if (typeof existing === "string") {
+      io.err(existing);
+      return 2;
+    }
+    const { limit } = limitOf(o, op, runtime.kind === "hand-off" ? await tierHere(root, op) : void 0);
+    const room = roomFor(limit, op, repo, commit);
+    const tooSmall = (more) => {
+      const fitted = limit === void 0 ? room : promptBudget(limit);
+      io.err(new PromptTooLong(`map ${repo}`, instructionTokens(repo, commit) + more + KEPT_RESERVE + MIN_ROOM, fitted, limit ?? fitted, []).message);
+      return 2;
+    };
+    if (room < MIN_ROOM)
+      return tooSmall(0);
+    const frameworks = await frameworksFor(root, repo, existing);
+    const re = await rereadOf(dir, existing, commit, source, exclude, deps.git);
+    const reread = re.plan && !re.plan.unknown.length ? re.plan : void 0;
+    const since = reread?.from.map((x) => x.commit.slice(0, 12)).join(", ");
+    if (reread && !reread.files.length && !reread.reread.length) {
+      io.out(`Nothing ${repo}'s facts cite changed since ${since}, and no source file did: atticus verify ${repo} carries its ${plural(reread.carried, "fact")} to ${commit.slice(0, 12)}.`);
+      return 0;
+    }
+    const plan = planBatches(reread ? onlyFiles(source, reread.files.map((f) => f.path)) : source, { room, exclude, overhead: overheadOf(repo, commit, frameworks) });
+    if (plan.leastRoom < MIN_ROOM)
+      return tooSmall(room - plan.leastRoom);
+    if (!plan.batches.length && !reread) {
+      io.out(`${repo} has no source files to read${plan.excluded.length ? ` (${plural(plan.excluded.length, "file")} excluded)` : ""}.`);
+      return 0;
+    }
+    const byId = new Map(existing.map((f) => [f.id, f]));
+    s = {
+      schemaVersion: 1,
+      repo,
+      commit,
+      ...limit ? { maxTokens: limit } : {},
+      room,
+      batches: plan.batches,
+      next: 0,
+      rejected: (reread?.reread ?? []).map((r) => {
+        const fact = byId.get(r.id);
+        return { id: r.id, code: "cite-changed", message: staleMessage(fact, r, commit), fact };
+      }),
+      problems: [],
+      ...reread ? {
+        reread: {
+          from: reread.from.map((x) => x.commit),
+          carried: reread.carried,
+          facts: reread.reread.length
+        }
+      } : {}
+    };
+    await saveState(root, s);
+    io.out(reread ? `Re-reading ${repo} at ${commit.slice(0, 12)}: ${plural(plan.files, "source file")} changed since ${since}, in ${batches(plan.batches.length)}${plan.batches.length ? ` (about ${plan.tokens} tokens${limit ? `, each prompt within ${limit} tokens` : ""})` : ""}; ${plural(reread.reread.length, "fact")} to rewrite, ${reread.carried} carried as they are; facts go to ${factsFile}.` : `Reading ${repo} at ${commit.slice(0, 12)} in ${batches(plan.batches.length)} (${plural(plan.files, "source file")}, about ${plan.tokens} tokens${limit ? `, each prompt within ${limit} tokens` : ""}); facts go to ${factsFile}.`);
+  }
+  if (!s)
+    return 2;
+  for (; ; ) {
+    const fixRound = s.next >= s.batches.length;
+    if (fixRound && (s.fixRound || !s.rejected.length))
+      break;
+    if (fixRound)
+      s.fixRound = true;
+    const { agent, pack } = await packFor(root, s, s.next, source, op, now());
+    const prepared = await runtime.prepare({
+      change: changeOf(repo),
+      agent,
+      pack,
+      outputPath: OUTPUT,
+      outputIn: "run"
+    });
+    const run = await runtime.run(prepared.runId);
+    if (run.state === "waiting" || run.state === "prepared") {
+      s.waiting = { runId: run.runId, batch: s.next };
+      await saveState(root, s);
+      if (o.copy)
+        return printCopy(s, runtime, io);
+      const label = fixRound ? "the fix round for the rejected facts" : `batch ${s.next + 1} of ${s.batches.length}`;
+      io.out(`Handed ${label} to your assistant (run ${run.runId}). When it is done: atticus handoff done ${run.runId}, then atticus map ${repo} --next`);
+      io.report?.({ handoff: { runId: run.runId } });
+      return 0;
+    }
+    const r = await takeAnswer(root, s, run, s.next, source, exclude, now, io, {
+      dir,
+      ...deps.git ? { git: deps.git } : {}
+    });
+    if (typeof r === "number")
+      return r;
+    s = r;
+  }
+  return finish(root, s, io, o);
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin)
+    chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function printCopy(s, runtime, io) {
+  const run = await runtime.result(s.waiting.runId);
+  io.out(COPY_START);
+  io.out(run.request.pack.prompt.trimEnd());
+  io.out(COPY_END);
+  io.out(`Paste it into your assistant's chat (${s.waiting.batch < s.batches.length ? `batch ${s.waiting.batch + 1} of ${s.batches.length}` : "the fix round"}). Save its answer to a file, then run: atticus map ${s.repo} --copy --answer <file> (or --answer - to paste it on stdin).`);
+  io.report?.({ handoff: { runId: run.runId } });
+  return 0;
+}
+async function takeAnswer(root, s, run, batch, source, exclude, now, io, at) {
+  const label = batch < s.batches.length ? `Batch ${batch + 1} of ${s.batches.length}` : "The fix round";
+  if (run.state !== "validated" && run.state !== "produced") {
+    io.err(`${label} got no answer to read (${run.errors.join("; ") || `the run ended ${run.state}`}). Run atticus map ${s.repo} --next to hand it again.`);
+    const { waiting: _w2, ...rest2 } = s;
+    await saveState(root, { ...rest2, next: batch });
+    return 1;
+  }
+  const answer = readAnswer(run.output ?? "", s.repo, s.commit);
+  const existing = await readFactsFile(root, s.repo);
+  if (typeof existing === "string") {
+    io.err(existing);
+    return 2;
+  }
+  const merged = new Map(existing.map((f) => [f.id, f]));
+  for (const f of answer.facts)
+    merged.set(f.id, f);
+  const { carry } = await carryOf(at.dir, [...merged.values()], s.commit, at.git);
+  const reviewed = await readReviewed(root, s.repo);
+  const report = await verifyFacts({
+    facts: [...merged.values()],
+    source,
+    commit: s.commit,
+    carry,
+    exclude,
+    // ADR 0124 addendum D-app: a person's corrections hold through every batch of a read.
+    corrections: (await readCorrections(root, s.repo)).corrections,
+    // ADR 0124 addendum A-read: files the reader read and found nothing in, if it wrote any.
+    reviewed: reviewed.entries
+  });
+  const q = await raiseReadQuestions(root, s.repo, answer.questions, source, {
+    command: `atticus map ${s.repo}`,
+    run: run.runId,
+    at: now().toISOString()
+  });
+  const summary = await writeVerifyFiles(root, s.repo, report, s.commit, q.problems, [], reviewedProblemsOf(reviewed.bad, report));
+  if (answer.about) {
+    const { keepDraftedDescription } = await import("./chunk-DPZHZQKE.js");
+    const d = await keepDraftedDescription(root, s.repo, answer.about, now());
+    if (d.kept)
+      io.out(`Your assistant says ${s.repo} is: "${answer.about.text}" \u2014 written to the manifest as a draft, unconfirmed. Confirm it (atticus repo describe ${s.repo} --accept), change it (--description "...") or drop it (--reject).`);
+    else if (d.why)
+      io.out(`The description your assistant drafted wasn't kept: ${d.why}.`);
+  }
+  const fresh = new Set(answer.facts.map((f) => f.id));
+  const kept = report.accepted.filter((f) => fresh.has(f.id)).length;
+  io.out(`${label}: ${plural(kept, "fact")} kept (${report.accepted.length} in all${report.carried.length ? `, ${report.carried.length} carried from an earlier commit` : ""}), ${report.rejected.length} rejected${q.raised.length ? `, ${plural(q.raised.length, "question")} raised for a person` : ""}${answer.problems.length ? `, ${plural(answer.problems.length, "line")} not read` : ""}.`);
+  const { waiting: _w, ...rest } = s;
+  const rejected = report.rejected.map((r) => ({
+    id: r.fact.id,
+    code: r.code,
+    message: r.message,
+    fact: r.fact
+  }));
+  const settled = /* @__PURE__ */ new Set([...report.accepted.map((f) => f.id), ...rejected.map((r) => r.id)]);
+  const pending = s.rejected.filter((r) => r.code === "cite-changed" && !settled.has(r.id));
+  return {
+    ...rest,
+    next: batch + 1,
+    rejected: [...rejected, ...pending],
+    problems: [...answer.problems, ...q.problems.map((p) => `${p.message}: ${p.line}`)],
+    last: summary
+  };
+}
+async function finish(root, s, io, o) {
+  s.done = true;
+  await saveState(root, s);
+  const last = s.last;
+  const rel = factsRelOf(root);
+  if (o.json) {
+    io.out(JSON.stringify({ state: "done", repo: s.repo, batches: s.batches.length, ...last }, null, 2));
+    return last && last.rejected ? 1 : 0;
+  }
+  if (!last) {
+    io.out(`Read ${s.repo}: nothing was kept.`);
+    return 0;
+  }
+  io.out(`Read ${s.repo} in ${batches(s.batches.length)}: ${plural(last.accepted, "fact")} kept in ${rel}/${s.repo}.jsonl, ${last.rejected} still rejected; coverage ${Math.round(last.coverage.ratio * 100)}% (${last.coverage.read} read, ${last.coverage.reviewed ? `${last.coverage.reviewed} reviewed with nothing to record, ` : ""}${last.coverage.unknown.length} unknown).`);
+  if (last.rejected)
+    io.out(`The rejected facts are in ${rel}/${s.repo}.rejected.jsonl; fix them by hand or with your assistant, then atticus verify ${s.repo}.`);
+  if (last.coverage.unknown.length)
+    io.out(`Files no fact cites yet are listed in ${rel}/${s.repo}.verify.yaml; generated code can be excluded in org-pack/scan/${s.repo}.yaml.`);
+  return last.rejected ? 1 : 0;
+}
+function rereadLines(repo, r) {
+  const head = r.commit.slice(0, 12);
+  const since = r.from.map((x) => x.commit.slice(0, 12)).join(", ");
+  const changed = r.from.reduce((n, x) => n + x.changed, 0);
+  const out = [
+    `A re-read: the facts are of ${since} and the checkout is at ${head}; ${plural(changed, "file")} changed since. Read only what is listed here, not the whole repo.`,
+    `${plural(r.carried, "fact")} still ${r.carried === 1 ? "holds" : "hold"} (every file they cite is unchanged): keep them as they are; atticus verify ${repo} carries them to ${head}, checking each line again.`
+  ];
+  if (r.current)
+    out.push(`${plural(r.current, "fact")} ${r.current === 1 ? "is" : "are"} already of ${head}.`);
+  if (r.reread.length) {
+    out.push(`${plural(r.reread.length, "fact")} ${r.reread.length === 1 ? "cites" : "cite"} a file that changed: read it again, then write each at ${head} under the same id with its line as it is now, or drop it if the code no longer says it:`);
+    for (const f of r.reread)
+      out.push(`  ${f.id} (${f.kind}): ${f.file} was ${f.how === "renamed" ? `renamed to ${f.to}` : f.how}`);
+  }
+  if (r.files.length) {
+    out.push(`${plural(r.files.length, "file")} to read whole (changed since ${since}):`);
+    for (const f of r.files)
+      out.push(`  ${f.path} (${f.facts ? `${plural(f.facts, "fact")} to rewrite` : `${f.status === "added" ? "new" : f.status}; no fact cites it yet`})`);
+  } else if (!r.reread.length)
+    out.push(`Nothing a fact cites changed and no source file did: run atticus verify ${repo} to carry the facts to ${head}.`);
+  return out;
+}
+async function estimate(root, repo, c, io) {
+  const tier = await tierHere(root, c.op);
+  const { limit: given, from } = limitOf(c.o, c.op, tier);
+  const limit = given ?? EXAMPLE_LIMIT;
+  const about = await aboutOf(root, repo);
+  const room = roomFor(limit, c.op, repo, c.commit);
+  const existing = await readFactsFile(root, repo);
+  const re = typeof existing === "string" ? { missing: [] } : await rereadOf(c.dir, existing, c.commit, c.source, c.exclude, c.git);
+  const reread = re.plan && !re.plan.unknown.length ? re.plan : void 0;
+  const readSource = reread ? onlyFiles(c.source, reread.files.map((f) => f.path)) : c.source;
+  const repoWhole = reread ? planBatches(c.source, { room: Number.MAX_SAFE_INTEGER, exclude: c.exclude }) : void 0;
+  const whole = planBatches(readSource, { room: Number.MAX_SAFE_INTEGER, exclude: c.exclude });
+  const planned = room >= MIN_ROOM ? planBatches(readSource, {
+    room,
+    exclude: c.exclude,
+    overhead: overheadOf(repo, c.commit, await frameworksFor(root, repo, typeof existing === "string" ? [] : existing))
+  }) : void 0;
+  const plan = planned && planned.leastRoom >= MIN_ROOM ? planned : void 0;
+  const files = whole.batches.flat().map((s) => ({ path: s.path, tokens: s.tokens }));
+  const proposed = reread ? { proposals: [], before: whole.tokens, after: whole.tokens } : proposeExclusions(files, c.source.list(), (p) => c.source.read(p), {
+    // What the person's description plainly says this repo holds (ADR 0128).
+    saysNotProduct: saysNotProduct(about)
+  });
+  const left = proposed.proposals.map((p) => p.path.slice(0, -2));
+  const session = Math.max(SESSION_TOKENS, Math.floor(0.75 * (given ?? 0)));
+  const product = files.filter((f) => !left.some((d) => f.path.startsWith(d)));
+  const parts = planParts(product, session);
+  const plan0 = await loadReadPlan(root, repo);
+  const same = plan0 !== void 0 && plan0.commit === c.commit && plan0.session === session && plan0.parts.length === parts.length && plan0.parts.every((p, i) => p.paths.length === parts[i].paths.length && p.paths.every((x, j) => x === parts[i].paths[j]));
+  if (parts.length && !same)
+    await writeReadPlan(root, repo, { commit: c.commit, session, parts });
+  const progress = parts.length ? await readPlanProgress(root, repo, { commit: c.commit }) : void 0;
+  const questions = (await listQuestions(root, { repo })).questions.filter((q) => q.state !== "retired");
+  if (c.o.json) {
+    io.out(JSON.stringify({
+      repo,
+      dir: c.dir,
+      commit: c.commit,
+      factsFile: c.factsFile,
+      files: whole.files,
+      lines: whole.lines,
+      tokens: whole.tokens,
+      excluded: whole.excluded,
+      maxTokens: limit,
+      maxTokensGiven: given !== void 0,
+      maxTokensFrom: from ?? "example",
+      batches: plan?.batches.length ?? null,
+      order: whole.batches.flat().map((x) => x.path),
+      // ADR 0128: what a person says the repo is, and whether that eased the proposals.
+      about: about ? { text: about.text, trust: about.trust, eased: saysNotProduct(about) } : null,
+      proposals: {
+        before: proposed.before,
+        after: proposed.after,
+        exclude: proposed.proposals
+      },
+      parts: {
+        session,
+        parts,
+        // A-ledger: the read plan on file and what the facts say each part has covered.
+        ...progress ? {
+          plan: {
+            file: readPlanRelOf(root, repo),
+            total: progress.total,
+            done: progress.done,
+            ...progress.next ? { next: progress.next.part } : {},
+            stale: progress.stale,
+            parts: progress.parts
+          }
+        } : {}
+      },
+      tier,
+      questions: questions.map((q) => ({
+        id: q.id,
+        question: q.question,
+        state: q.state,
+        ...q.answer ? { answer: q.answer } : {}
+      })),
+      // A re-read: what the files and batches above are, and the facts to revisit.
+      reread: reread ? {
+        ...reread,
+        repo: {
+          files: repoWhole.files,
+          lines: repoWhole.lines,
+          tokens: repoWhole.tokens
+        }
+      } : null,
+      ...re.missing.length ? { notComparable: re.missing } : {}
+    }, null, 2));
+    return 0;
+  }
+  io.out(`${repo} at ${c.commit} in ${c.dir}`);
+  io.out(about ? `What it is (${descriptionTrust(about)}${about.by ? `, ${about.by}` : ""}): ${about.text} \u2014 a person's note from the manifest, not read from the code: where the code says otherwise, the code is right.` : `What it is: nothing says yet. A person writes one line (atticus repo describe ${repo} --description "..."); if the files say plainly, hand yours over with atticus repo describe ${repo} --drafted "..." --cites <file>:<line>, and it waits for a person.`);
+  io.out(`Facts file: ${c.factsFile}`);
+  if (reread)
+    for (const l of rereadLines(repo, reread))
+      io.out(l);
+  for (const m of re.missing)
+    io.out(`Some facts are of commit ${m.slice(0, 12)}, which this clone can't compare with ${c.commit.slice(0, 12)} (fetch it, or read the repo again whole): the read below is the whole repo.`);
+  io.out(`${plural(whole.files, "source file")}${reread ? " to read" : ""}, ${plural(whole.lines, "line")}, about ${whole.tokens} tokens${whole.excluded.length ? `; ${whole.excluded.length} excluded` : ""}${reread ? ` (the repo has ${plural(repoWhole.files, "source file")}, about ${repoWhole.tokens} tokens)` : ""}.`);
+  if (proposed.proposals.length) {
+    const scan = relative(root, join(orgPackDirOf(root), "scan", `${repo}.yaml`)).replace(/\\/g, "/");
+    io.out(`Folders that look like data, documentation or vendored code, not the product (${proposed.proposals.length}):`);
+    if (saysNotProduct(about))
+      io.out(`  (${repo}'s description says it is mostly not product code, so a smaller folder is proposed than would be otherwise. Each is still a proposal a person accepts.)`);
+    for (const p of proposed.proposals.slice(0, SHOWN_PROPOSALS))
+      io.out(`  ${p.path} (about ${p.tokens} tokens, ${plural(p.files, "file")}): ${p.why}`);
+    if (proposed.proposals.length > SHOWN_PROPOSALS)
+      io.out(`  ... and ${proposed.proposals.length - SHOWN_PROPOSALS} more (all in the exclude: block below)`);
+    const fresh = !existsSync(join(root, scan));
+    io.out(fresh ? `To leave them out, a person saves this as ${scan} in a pull request (Atticus never writes it):` : `To leave them out, a person adds these entries to the exclude: list of ${scan} in a pull request (Atticus never writes it):`);
+    if (fresh)
+      io.out(`schemaVersion: 1
+repo: ${repo}`);
+    io.out(exclusionYaml(proposed.proposals).trimEnd());
+    io.out(`With them left out: about ${proposed.after} tokens (now ${proposed.before}).`);
+  }
+  if (parts.length) {
+    if (proposed.proposals.length)
+      io.out(`The parts below are planned over what is left with the ${plural(proposed.proposals.length, "proposed folder")} left out (${plural(product.length, "source file")}, about ${proposed.after} tokens); no part reads a proposed folder.`);
+    io.out(`About ${parts.reduce((n, p) => n + p.tokens, 0)} tokens${proposed.proposals.length ? " with those left out" : ""} is more than one session reads (${session} tokens): read it in ${parts.length} parts, one per session or sub-agent, as /atticus-map says:`);
+    const stateOf = (i) => progress?.parts[i]?.state;
+    const words = (s) => s === "done" ? "done" : s === "in-progress" ? "part-read" : "to read";
+    parts.forEach((p, i) => io.out(`  part ${i + 1} (${words(stateOf(i))}, about ${p.tokens} tokens, ${plural(p.files, "file")}): ${p.paths.join(", ")}`));
+    if (progress) {
+      io.out(`Read plan: ${readPlanRelOf(root, repo)}. ${progress.next ? `${partOfWords({ part: progress.next.part, total: progress.total })} is next (${progress.done ? `${progress.done} of ${progress.total} read` : `none of ${progress.total} read yet`}): ${progress.next.paths.join(", ")}.` : `All ${progress.total} parts are read.`} A part counts as read when every folder it covers is in the facts (a fact citing a file, or a line of ${factsRelOf(root)}/${repo}.reviewed.jsonl); atticus next says which comes next.`);
+      for (const p of progress.parts)
+        if (p.state === "in-progress")
+          io.out(`  part ${p.part} is part-read: nothing in the facts yet for ${p.left.join(", ")}.`);
+    }
+  }
+  io.out(`Your assistant: ${tierWords(tier)}, ${tierSource(tier)}. ${tier.how}`);
+  io.out(`Another agentic assistant (Claude Code, Cursor, Gemini CLI) reads it the same way: /atticus-map ${repo}; one without file tools gets batches with atticus map ${repo} --handoff --max-tokens <its limit>.`);
+  if (tier.fallback)
+    io.out(tier.fallback);
+  if (tier.note)
+    io.out(tier.note);
+  if (tier.model)
+    io.out(tier.model);
+  if (tier.measured?.stale)
+    io.out(`That was ${tier.measured.days} days ago: atticus probe measures it again.`);
+  else if (tier.source === "runtime.yaml" && tier.tier !== "off")
+    io.out("atticus probe measures your assistant's tier and limit instead.");
+  io.out(plan ? `In batches at ${limit} tokens a prompt${given === void 0 ? " (GPT-4o mini through Copilot; --max-tokens n for your model's limit)" : from === "probe" ? ` (the limit stated when your assistant was measured on ${tier.measured?.at})` : ""}: ${plural(plan.batches.length, "prompt")}, one more if facts are rejected in the last.` : `A model of ${limit} tokens leaves too little room for the files beside the instructions: use a model with a bigger limit.`);
+  for (const q of questions)
+    io.out(`Question ${q.id}: ${q.question} (${q.state === "answered" ? `answered: ${q.answer?.text ?? q.options[(q.answer?.option ?? 1) - 1]?.label ?? ""}` : "open"})`);
+  if (questions.length)
+    io.out("Follow each answer; don't ask these again.");
+  return 0;
+}
+export {
+  REPO_READER,
+  mapCommand,
+  readAnswer,
+  repoReaderAgent
+};