@archme/cli 0.10.0 → 0.11.0

package/dist/cli.js

@@ -9838,6 +9838,7 @@ var install_exports = {};
 __export(install_exports, {
   NotSignedInError: () => NotSignedInError,
   PUBLISHED_BIN_RELATIVE: () => PUBLISHED_BIN_RELATIVE,
+  archmeSelfCommand: () => archmeSelfCommand,
   ensureStartPrerequisites: () => ensureStartPrerequisites,
   findPackageRoot: () => findPackageRoot,
   pickCliEntry: () => pickCliEntry,
@@ -9881,6 +9882,9 @@ function resolveCliEntry() {
   const here = dirname6(fileURLToPath3(import.meta.url));
   return pickCliEntry(findPackageRoot(here, existsSync2), existsSync2);
 }
+function archmeSelfCommand() {
+  return [process.execPath, resolveCliEntry()];
+}
 async function ensureStartPrerequisites(opts = {}) {
   const out = opts.out ?? process.stdout;
   const platform3 = opts.platform ?? process.platform;
@@ -10399,6 +10403,11 @@ function buildClaudeArgs(opts) {
     "--allowedTools",
     tools
   ];
+  if (opts.resumeSessionId) {
+    args.push("--resume", opts.resumeSessionId);
+  } else if (opts.sessionId) {
+    args.push("--session-id", opts.sessionId);
+  }
   if (opts.builtinTools) {
     args.push("--tools", opts.builtinTools.join(","));
   }
@@ -10410,6 +10419,9 @@ function buildClaudeArgs(opts) {
   }
   return args.map(stripNulBytes);
 }
+function claudeTimeoutMs(timeoutMs) {
+  return timeoutMs === null ? void 0 : timeoutMs ?? DEFAULT_CLAUDE_TIMEOUT_MS;
+}
 function spawnClaude(opts) {
   requireBinary("claude");
   const env = scrubPrivilegedEnv(process.env);
@@ -10433,7 +10445,7 @@ function spawnClaude(opts) {
     args,
     {
       reject: false,
-      timeout: opts.timeoutMs ?? DEFAULT_CLAUDE_TIMEOUT_MS,
+      timeout: claudeTimeoutMs(opts.timeoutMs),
       cwd: opts.cwd,
       env,
       // Claude reads stdin opportunistically and prints a warning after 3s
@@ -10530,7 +10542,12 @@ var init_spawn_claude = __esm({
       // "Agent" is inherited from DEFAULT_ALLOWED_TOOLS (sub-agent dispatch).
       "Write",
       "Edit",
-      "Bash"
+      "Bash",
+      // The scan prompts research the product's public site and docs. A scan could
+      // already fetch pages through Bash (curl), so this adds search, not reach.
+      // Interactive sessions still ask the person before every fetch.
+      "WebSearch",
+      "WebFetch"
     ];
     DEFAULT_CLAUDE_TIMEOUT_MS = 15 * 60 * 1e3;
   }
@@ -13904,7 +13921,7 @@ function buildRepoContainerDiffGuidance(containerPath) {
   return `## Multi-repo project
 This project holds several repos, each a root-level \`kind: "repo"\` container; this repo's code lives under \`${containerPath}\`. Before modelling anything that crosses repos, read the project's modelling conventions with ${READ_CONVENTIONS}. Never create a root-level external for a system that has a repo container \u2014 connect to the components inside that container instead.`;
 }
-var READ_CONVENTIONS, PLAN_CHANGES_ID, STITCH_PLAN_GUIDANCE;
+var READ_CONVENTIONS, PLAN_CHANGES_ID, STORY_PLAN_SHAPE, STORY_PLAN_GUIDANCE, PLAN_CHANGES_EXPLANATION, STITCH_PLAN_GUIDANCE, READ_FIRST;
 var init_multiRepoScan = __esm({
   "../shared/multiRepoScan.ts"() {
     init_scanPrompts();
@@ -13913,7 +13930,11 @@ var init_multiRepoScan = __esm({
     init_repoContainer();
     READ_CONVENTIONS = `read_context({ path: "root", type: "decision" })`;
     PLAN_CHANGES_ID = "multi-repo-plan-changes";
-    STITCH_PLAN_GUIDANCE = `**Finish the approved story plan, then explain what changed from it.** The user approved a draft story plan before the repos were scanned. Each repo's scan left the stories that cross repos to you, and recorded its own departures from the plan in root context (\`${PLAN_CHANGES_ID}-<container>\` decisions). Write each remaining draft story's sequence against the code on every side it touches, and set \`draft: false\`. Then write ONE root-context decision \u2014 \`update_node_context({ path: "root", add: [{ id: "${PLAN_CHANGES_ID}", type: "decision", title: "What changed from the approved plan, and why", content: "\u2026" }] })\` \u2014 listing every story added, dropped, renamed or re-scoped against the plan, the repos' departures and your own, each with its reason in a plain sentence ("No changes from the approved plan." if there were none). Present it to the user and answer their questions about it before you finish.`;
+    STORY_PLAN_SHAPE = `Write it in one \`update_architecture\` call at root: feature groups holding leaf stories, every leaf \`draft: true\` with a \`title\` and a \`description\` and no \`sequence\`. Each leaf's description names the repos it touches, ending \`Repos: owner/a, owner/b\`. A flow that crosses repos is ONE story naming all of them, never one per repo. If the board already has stories, they are the plan's starting point: keep, edit or remove them rather than starting over.`;
+    STORY_PLAN_GUIDANCE = `**Draft the story plan** every repo's scan will build against. Read each clone only as far as it takes to say what the system does for the people and systems that use it (READMEs, entry points, API and resource definitions) \u2014 don't trace flows. ${STORY_PLAN_SHAPE}`;
+    PLAN_CHANGES_EXPLANATION = `write ONE root-context decision \u2014 \`update_node_context({ path: "root", add: [{ id: "${PLAN_CHANGES_ID}", type: "decision", title: "What changed from the approved plan, and why", content: "\u2026" }] })\` \u2014 listing every story added, dropped, renamed or re-scoped against the plan, the repos' departures and your own, each with its reason in a plain sentence ("No changes from the approved plan." if there were none). Present it to the user and answer their questions about it before you finish.`;
+    STITCH_PLAN_GUIDANCE = `**Finish the approved story plan, then explain what changed from it.** The user approved a draft story plan before the repos were scanned. Each repo's scan left the stories that cross repos to you, and recorded its own departures from the plan in root context (\`${PLAN_CHANGES_ID}-<container>\` decisions). Write each remaining draft story's sequence against the code on every side it touches, and set \`draft: false\`. Then ${PLAN_CHANGES_EXPLANATION}`;
+    READ_FIRST = `**Read first.** \`read_architecture\` at root and ${READ_CONVENTIONS}. A rerun reuses what is already there under the ids below and rewrites it in place.`;
   }
 });
 
@@ -19886,6 +19907,8 @@ var init_identity = __esm({
 // src/scan/authedClient.ts
 var authedClient_exports = {};
 __export(authedClient_exports, {
+  ORCHESTRATED_SCAN_TIMEOUT_MS: () => ORCHESTRATED_SCAN_TIMEOUT_MS,
+  ORCHESTRATED_SCAN_TOKEN_MIN_LIFETIME_MS: () => ORCHESTRATED_SCAN_TOKEN_MIN_LIFETIME_MS,
   SCAN_CLAUDE_TIMEOUT_MS: () => SCAN_CLAUDE_TIMEOUT_MS,
   SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS: () => SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS,
   createAuthedClient: () => createAuthedClient
@@ -19924,7 +19947,7 @@ async function createAuthedClient(opts) {
     accountKind: loaded.kind ?? "oauth"
   };
 }
-var SCAN_CLAUDE_TIMEOUT_MS, SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS;
+var SCAN_CLAUDE_TIMEOUT_MS, SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS, ORCHESTRATED_SCAN_TIMEOUT_MS, ORCHESTRATED_SCAN_TOKEN_MIN_LIFETIME_MS;
 var init_authedClient = __esm({
   "src/scan/authedClient.ts"() {
     "use strict";
@@ -19932,6 +19955,8 @@ var init_authedClient = __esm({
     init_identity();
     SCAN_CLAUDE_TIMEOUT_MS = 45 * 60 * 1e3;
     SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS = SCAN_CLAUDE_TIMEOUT_MS + 5 * 60 * 1e3;
+    ORCHESTRATED_SCAN_TIMEOUT_MS = 6 * 60 * 60 * 1e3;
+    ORCHESTRATED_SCAN_TOKEN_MIN_LIFETIME_MS = ORCHESTRATED_SCAN_TIMEOUT_MS + 5 * 60 * 1e3;
   }
 });
 
@@ -20507,24 +20532,32 @@ var init_claimDefaultProject = __esm({
 });
 
 // src/scan/run-scan.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
 import { createWriteStream as createWriteStream2 } from "node:fs";
-import { mkdir as mkdir13, readFile as readFile14 } from "node:fs/promises";
-import { basename as basename2, join as join21 } from "node:path";
+import { mkdir as mkdir13, readFile as readFile14, writeFile as writeFile12 } from "node:fs/promises";
+import { basename as basename2, dirname as dirname15, join as join21 } from "node:path";
 function modeInstruction(opts) {
   const line = modeLine(opts);
+  if (opts.mode === "orchestrator" && opts.plan) {
+    throw new Error("the orchestrator always plans; start_scan refuses `plan` with it");
+  }
   return line && opts.plan ? `${line} Also pass \`plan: true\`: this bootstrap builds against a draft story plan.` : line;
 }
+function reposArg(opts, mode) {
+  const repos = opts.repos ?? [];
+  if (repos.length === 0 || !repos.every((r) => REPO_SLUG_RE.test(r))) {
+    throw new Error(`${mode} mode needs at least one repo, each \`owner/name\``);
+  }
+  return repos.map((r) => `"${r}"`).join(", ");
+}
 function modeLine(opts) {
   switch (opts.mode) {
     case void 0:
       return null;
-    case "roster": {
-      const repos = opts.repos ?? [];
-      if (repos.length === 0 || !repos.every((r) => REPO_SLUG_RE.test(r))) {
-        throw new Error("roster mode needs at least one repo, each `owner/name`");
-      }
-      return `This is the multi-repo roster session \u2014 pass \`mode: "roster"\` and \`repos: [${repos.map((r) => `"${r}"`).join(", ")}]\` to \`start_scan\`.`;
-    }
+    case "roster":
+      return `This is the multi-repo roster session \u2014 pass \`mode: "roster"\` and \`repos: [${reposArg(opts, "roster")}]\` to \`start_scan\`.`;
+    case "orchestrator":
+      return `This is the multi-repo orchestrator session \u2014 pass \`mode: "orchestrator"\` and \`repos: [${reposArg(opts, "orchestrator")}]\` to \`start_scan\`.`;
     case "repo":
       if (!opts.container || !CONTAINER_ID_RE.test(opts.container)) {
         throw new Error(`invalid container id \`${opts.container ?? ""}\``);
@@ -20543,6 +20576,9 @@ ${briefing}` : BOOTSTRAP_INTERACTIVE_NO_BRIEFING : BOOTSTRAP_HEADLESS;
   if (modeLine2) base += `
 
 ${modeLine2}`;
+  if (opts.runSheet) base += `
+
+${opts.runSheet}`;
   if (!promptVariant) return base;
   if (!PROMPT_VARIANT_RE.test(promptVariant)) {
     throw new Error(
@@ -20554,6 +20590,26 @@ ${modeLine2}`;
 Use scan-prompt variant \`${promptVariant}\` \u2014 pass \`variant: "${promptVariant}"\` to \`start_scan\`.`;
   return base;
 }
+async function writeScanSession(repoPath, session) {
+  const path7 = join21(repoPath, SCAN_SESSION_FILE);
+  await mkdir13(dirname15(path7), { recursive: true });
+  await writeFile12(path7, JSON.stringify(session, null, 2) + "\n");
+}
+async function readScanSession(repoPath) {
+  const path7 = join21(repoPath, SCAN_SESSION_FILE);
+  const raw = await readFile14(path7, "utf8").catch(() => null);
+  if (raw === null) throw new Error(`no scan session to resume at ${path7} \u2014 launch it instead`);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${path7} is not valid JSON; its session id cannot be read`);
+  }
+  if (typeof parsed.sessionId !== "string" || !SESSION_ID_RE.test(parsed.sessionId)) {
+    throw new Error(`${path7} holds no valid session id`);
+  }
+  return { sessionId: parsed.sessionId, pid: typeof parsed.pid === "number" ? parsed.pid : 0 };
+}
 function todayDate() {
   const d = /* @__PURE__ */ new Date();
   const yyyy = d.getUTCFullYear();
@@ -20837,7 +20893,7 @@ async function runScan(opts, deps = {}) {
   });
   log(`  signed in as ${authed2.identity}`);
   const { supabase, userId } = authed2;
-  const workspace = opts.mode === "roster" || opts.mode === "stitch";
+  const workspace = opts.mode === "roster" || opts.mode === "stitch" || opts.mode === "orchestrator";
   let headSha = null;
   if (!workspace) {
     try {
@@ -20898,25 +20954,31 @@ async function runScan(opts, deps = {}) {
   try {
     const model = await resolveRunnableModel(supabase, { warn: log });
     const interactive = opts.interactive !== false;
+    if (interactive && opts.resume) throw new Error("only a headless scan can be resumed");
+    const session = interactive ? null : { sessionId: opts.resume ? (await readScanSession(opts.repoPath)).sessionId : randomUUID2(), pid: process.pid };
+    if (session) await writeScanSession(opts.repoPath, session);
+    const timeoutMs = opts.timeoutMs === void 0 ? SCAN_CLAUDE_TIMEOUT_MS : opts.timeoutMs;
     log(
-      interactive ? `starting claude (mcp config at ${configPath}, model ${model}) \u2014 this session is interactive; answer its questions as they come` : `spawning claude (mcp config at ${configPath}, model ${model}, timeout ${Math.round(SCAN_CLAUDE_TIMEOUT_MS / 6e4)} min)`
+      interactive ? `starting claude (mcp config at ${configPath}, model ${model}) \u2014 this session is interactive; answer its questions as they come` : `${opts.resume ? "resuming" : "spawning"} claude (session ${session.sessionId}, mcp config at ${configPath}, model ${model}, ${timeoutMs === null ? "no timeout" : `timeout ${Math.round(timeoutMs / 6e4)} min`})`
     );
     const spawn2 = deps.spawn ?? spawnClaude;
     const proc = spawn2({
-      prompt: buildBootstrapPrompt({
+      prompt: opts.resume ? opts.resume.message : buildBootstrapPrompt({
         promptVariant: opts.promptVariant,
         interactive,
         briefing: opts.briefing,
         mode: opts.mode,
         container: opts.container,
         repos: opts.repos,
-        plan: opts.plan
+        plan: opts.plan,
+        runSheet: opts.runSheet
       }),
       mcpConfigPath: configPath,
       cwd: opts.repoPath,
       // No timeout interactively — a human is present and can Ctrl-C. Killing a
       // session mid-answer would be worse than any runaway.
-      timeoutMs: interactive ? void 0 : SCAN_CLAUDE_TIMEOUT_MS,
+      timeoutMs: interactive ? void 0 : timeoutMs,
+      ...session ? opts.resume ? { resumeSessionId: session.sessionId } : { sessionId: session.sessionId } : {},
       allowedTools: SCAN_ALLOWED_TOOLS,
       model,
       interactive,
@@ -20929,7 +20991,7 @@ async function runScan(opts, deps = {}) {
     const transcriptDir = join21(opts.repoPath, ".archme", "scan");
     const transcriptPath = join21(transcriptDir, "transcript.log");
     await mkdir13(transcriptDir, { recursive: true });
-    const transcriptStream = createWriteStream2(transcriptPath, { flags: "w" });
+    const transcriptStream = createWriteStream2(transcriptPath, { flags: opts.resume ? "a" : "w" });
     let finalResultText = "";
     const echo = opts.echo ?? ((line) => process.stdout.write(line + "\n"));
     if (proc.stdout) {
@@ -21037,7 +21099,7 @@ async function runScan(opts, deps = {}) {
     });
   }
 }
-var BOOTSTRAP_HEADLESS, BOOTSTRAP_INTERACTIVE, BOOTSTRAP_INTERACTIVE_NO_BRIEFING, PROMPT_VARIANT_RE, CONTAINER_ID_RE, REPO_SLUG_RE;
+var BOOTSTRAP_HEADLESS, BOOTSTRAP_INTERACTIVE, BOOTSTRAP_INTERACTIVE_NO_BRIEFING, PROMPT_VARIANT_RE, CONTAINER_ID_RE, REPO_SLUG_RE, SCAN_SESSION_FILE, SESSION_ID_RE;
 var init_run_scan = __esm({
   "src/scan/run-scan.ts"() {
     "use strict";
@@ -21064,6 +21126,8 @@ Before you call \`start_scan\`, show the user this briefing verbatim and ask the
     PROMPT_VARIANT_RE = /^\d{2}-\d{2}-\d{2}-\d{4}(-[A-Za-z0-9_-]+)?$/;
     CONTAINER_ID_RE = /^[A-Za-z0-9_]+$/;
     REPO_SLUG_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+    SCAN_SESSION_FILE = ".archme/scan/session.json";
+    SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
   }
 });
 
@@ -22125,7 +22189,7 @@ var init_plan = __esm({
 });
 
 // src/init/run-init.ts
-import { mkdtemp as mkdtemp4, rm as rm9, writeFile as writeFile12 } from "node:fs/promises";
+import { mkdtemp as mkdtemp4, rm as rm9, writeFile as writeFile13 } from "node:fs/promises";
 import { tmpdir as tmpdir4 } from "node:os";
 import { join as join24 } from "node:path";
 async function defaultStartDaemon() {
@@ -22175,7 +22239,7 @@ async function defaultRunInstallScript(script, cwd) {
   const dir = await mkdtemp4(join24(tmpdir4(), "archme-init-"));
   const scriptPath = join24(dir, "install-agent.sh");
   try {
-    await writeFile12(scriptPath, script, { mode: 448 });
+    await writeFile13(scriptPath, script, { mode: 448 });
     await execa("sh", [scriptPath], { cwd, stdio: "inherit" });
   } finally {
     await rm9(dir, { recursive: true, force: true });
@@ -23405,7 +23469,8 @@ async function addRepoToBoard(board, add, deps = {}) {
         mode: "repo",
         container: containerId,
         interactive: add.interactive,
-        ...add.plan ? { plan: true } : {},
+        ...add.plan ? { plan: true, timeoutMs: ORCHESTRATED_SCAN_TIMEOUT_MS } : {},
+        ...add.resume ? { resume: add.resume } : {},
         ...add.echo ? { echo: add.echo } : {},
         log
       },
@@ -23458,7 +23523,7 @@ async function runAddRepo(opts, deps = {}) {
     supabaseUrl: cfg.supabaseUrl,
     supabaseAnonKey: cfg.supabaseAnonKey,
     clientId: cfg.archmeDaemonClientId,
-    preSpawnMinLifetimeMs: SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS
+    preSpawnMinLifetimeMs: opts.plan ? ORCHESTRATED_SCAN_TOKEN_MIN_LIFETIME_MS : SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS
   });
   if (!authed2.orgId) return fail(3, "this login is not paired with an org \u2014 run `archme login`");
   const project = await (deps.resolveProject ?? resolveOrCreateProject)(authed2.supabase, authed2.userId, opts.project);
@@ -23471,7 +23536,9 @@ async function runAddRepo(opts, deps = {}) {
       target: { ...early.target, archmeBranch: scanBranch },
       container: flagContainer,
       local: opts.local,
-      interactive: !opts.yes
+      interactive: !opts.yes,
+      ...opts.plan ? { plan: true } : {},
+      ...opts.resume !== void 0 ? { resume: { message: opts.resume } } : {}
     },
     deps
   );
@@ -23479,6 +23546,7 @@ async function runAddRepo(opts, deps = {}) {
   const containerPath = added.containerPath;
   log(`
 \u2713 ${repo} is in ${containerPath}.`);
+  if (opts.plan) return 0;
   log("  Next: run `archme add-repo` inside each remaining repo's clone; once all are in,");
   log(`  run \`archme scan --stitch --project ${opts.project}\` from the directory holding the clones.`);
   log("  Watching queues work; the daemon runs it:  archme daemon start");
@@ -24634,6 +24702,9 @@ function parseAddRepoArgs(argv) {
   let container;
   let local = false;
   let yes = false;
+  let plan = false;
+  let resume = false;
+  let message;
   for (let i2 = 0; i2 < argv.length; i2++) {
     const arg = argv[i2];
     const next = argv[i2 + 1];
@@ -24649,6 +24720,14 @@ function parseAddRepoArgs(argv) {
       local = true;
     } else if (arg === "--yes" || arg === "--no-interactive") {
       yes = true;
+    } else if (arg === "--plan") {
+      plan = true;
+    } else if (arg === "--resume") {
+      resume = true;
+    } else if (arg === "--message") {
+      if (!next) return err2("--message needs the text to resume with");
+      message = next;
+      i2++;
     } else if (arg.startsWith("-")) {
       return err2(`unknown flag '${arg}'`);
     } else if (repoPath === void 0) {
@@ -24658,7 +24737,11 @@ function parseAddRepoArgs(argv) {
     }
   }
   if (!project) return err2("--project <org/slug> is required \u2014 the multi-repo project to add this repo to");
-  return { kind: "run", opts: { repoPath, project, container, local, yes } };
+  if (resume !== (message !== void 0)) return err2("--resume and --message go together: the message is what the scan resumes with");
+  if (resume) {
+    return { kind: "run", opts: { repoPath, project, container, local, yes: true, plan, resume: message } };
+  }
+  return { kind: "run", opts: { repoPath, project, container, local, yes, plan } };
 }
 function printAddRepoHelp() {
   console.log(`archme add-repo \u2014 add one repo to a multi-repo project
@@ -24678,7 +24761,15 @@ Options:
   --local                Poll from this machine instead of the GitHub App
   --yes                  Run the scan headless (no questions)
 
-Several repos at once (plan, scan each, stitch): \`archme add-repos\`.`);
+Used by the \`archme add-repos\` orchestrator:
+  --plan                 Build against the approved story plan, with a
+                         ${ORCHESTRATED_SCAN_HOURS}-hour timeout
+  --resume --message <text>
+                         Continue this repo's last headless scan session,
+                         with its full history, from this message
+
+Several repos at once (one agent plans with you, scans each, stitches):
+\`archme add-repos\`.`);
 }
 async function dispatchAddRepo(argv) {
   const parsed = parseAddRepoArgs(argv);
@@ -24699,10 +24790,12 @@ async function dispatchAddRepo(argv) {
     return 3;
   }
 }
-var PROJECT_SLUG_RE4;
+var ORCHESTRATED_SCAN_HOURS, PROJECT_SLUG_RE4;
 var init_dispatch6 = __esm({
   "src/addRepo/dispatch.ts"() {
     "use strict";
+    init_authedClient();
+    ORCHESTRATED_SCAN_HOURS = ORCHESTRATED_SCAN_TIMEOUT_MS / 36e5;
     PROJECT_SLUG_RE4 = /^[^/\s]+\/[^/\s]+$/;
   }
 });
@@ -24710,6 +24803,7 @@ var init_dispatch6 = __esm({
 // src/addRepos/run.ts
 var run_exports3 = {};
 __export(run_exports3, {
+  buildRunSheet: () => buildRunSheet,
   cloneFromGitHub: () => cloneFromGitHub,
   listClones: () => listClones,
   runAddRepos: () => runAddRepos,
@@ -24717,7 +24811,7 @@ __export(run_exports3, {
   watchedElsewhere: () => watchedElsewhere
 });
 import { readdir as readdir2, stat as stat11 } from "node:fs/promises";
-import { dirname as dirname15, join as join26, resolve as resolve6, sep as sep2 } from "node:path";
+import { dirname as dirname16, join as join26, resolve as resolve6, sep as sep2 } from "node:path";
 function isThisRunsWrite(metadata) {
   return metadata?.kind === "scan" || !!metadata?.repo_fold;
 }
@@ -24752,7 +24846,7 @@ async function listClones(dir) {
   return out.sort();
 }
 function commonDir(paths) {
-  const split = paths.map((p) => dirname15(p).split(sep2));
+  const split = paths.map((p) => dirname16(p).split(sep2));
   const common2 = [];
   for (let i2 = 0; split.every((s) => s[i2] !== void 0 && s[i2] === split[0][i2]); i2++) common2.push(split[0][i2]);
   return common2.join(sep2) || sep2;
@@ -24764,9 +24858,6 @@ function duration(ms) {
   const s = Math.round(ms / 1e3);
   return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
 }
-function plural(n2, word) {
-  return `${n2} ${word}${n2 === 1 ? "" : "s"}`;
-}
 function serialized(fn) {
   let tail = Promise.resolve();
   return (...args) => {
@@ -24776,18 +24867,28 @@ function serialized(fn) {
     return run;
   };
 }
-async function mapLimited(items, limit, fn) {
-  const out = new Array(items.length);
-  let next = 0;
-  await Promise.all(
-    Array.from({ length: Math.min(limit, items.length) }, async () => {
-      while (next < items.length) {
-        const i2 = next++;
-        out[i2] = await fn(items[i2]);
-      }
-    })
-  );
-  return out;
+function buildRunSheet(opts) {
+  const launch = (r) => `${opts.archme} add-repo ${shellQuote(r.root)} --project ${shellQuote(opts.project)} --container ${r.containerId} --plan --yes${opts.local ? " --local" : ""}`;
+  const lines = [
+    "## Session brief",
+    "",
+    `Project \`${opts.project}\`, branch \`${opts.scanBranch}\`; the clones are under \`${opts.workspace}\`.`,
+    "",
+    "Scan these repos. Launch each once; resume a scan rather than relaunch it.",
+    ...opts.scan.flatMap((r) => [
+      "",
+      `### ${r.repo} \u2192 \`root.${r.containerId}\``,
+      `- Clone: \`${r.root}\``,
+      `- Launch: \`${launch(r)}\``,
+      `- Resume: \`${launch(r)} --resume --message "<answer or correction>"\``,
+      `- Session file: \`${join26(r.root, SCAN_SESSION_FILE)}\``
+    ])
+  ];
+  if (opts.context.length > 0) {
+    lines.push("", "Already on the board \u2014 context only, never launch a scan for these:");
+    for (const r of opts.context) lines.push(`- ${r.repo} (\`root.${r.containerId}\`): ${r.why}`);
+  }
+  return lines.join("\n");
 }
 async function runAddRepos(opts, deps = {}) {
   const log = deps.log ?? ((m) => console.log(m));
@@ -24802,7 +24903,7 @@ async function runAddRepos(opts, deps = {}) {
   const session = deps.session ?? runScan;
   const confirm = deps.confirm ?? ((q) => promptYesNo(q, { defaultYes: false }));
   if (!opts.yes && !(deps.isInteractive ?? stdinIsInteractive)()) {
-    return fail(78, "the plan and stitch sessions are interactive and need a terminal \u2014 pass --yes to run everything headless");
+    return fail(78, "the orchestrator session is interactive and needs a terminal \u2014 pass --yes to run everything headless");
   }
   const explicit = opts.targets.length > 0;
   const toClone = (inspected) => {
@@ -24855,7 +24956,7 @@ async function runAddRepos(opts, deps = {}) {
     supabaseUrl: cfg.supabaseUrl,
     supabaseAnonKey: cfg.supabaseAnonKey,
     clientId: cfg.archmeDaemonClientId,
-    preSpawnMinLifetimeMs: SCAN_PRE_SPAWN_TOKEN_MIN_LIFETIME_MS
+    preSpawnMinLifetimeMs: ORCHESTRATED_SCAN_TOKEN_MIN_LIFETIME_MS
   });
   if (!authed2.orgId) return fail(3, "this login is not paired with an org \u2014 run `archme login`");
   const { supabase } = authed2;
@@ -24885,7 +24986,7 @@ async function runAddRepos(opts, deps = {}) {
   const toWatch = done.filter((c3) => !live(c3.target.repo));
   const skipped = done.filter((c3) => live(c3.target.repo));
   const noClone = roster.added.filter((r) => !clones.some((c3) => sameRepo(c3.target.repo, r)));
-  log(`archme add-repos \u2192 ${opts.project} (branch ${scanBranch}), sessions run in ${workspace}`);
+  log(`archme add-repos \u2192 ${opts.project} (branch ${scanBranch}), the orchestrator runs in ${workspace}`);
   for (const c3 of todo) log(`  add:       ${c3.target.repo} \u2192 root.${containerFor(c3.target.repo)}`);
   for (const c3 of toWatch) log(`  watch:     ${c3.target.repo} \u2192 root.${containerFor(c3.target.repo)} (already scanned, so not rescanned)`);
   if (skipped.length) {
@@ -24921,24 +25022,24 @@ async function runAddRepos(opts, deps = {}) {
   Nothing was changed. Unwatch it there first, or add it to that project instead.`);
   }
   if (!opts.local) {
-    const missing = [];
+    const missing2 = [];
     for (const c3 of watching) {
       const found = await (deps.findInstallation ?? findInstallation)(supabase, authed2.orgId, c3.target.repoOwner);
-      if (!found.ok) missing.push(`${c3.target.repo}: ${found.reason}`);
+      if (!found.ok) missing2.push(`${c3.target.repo}: ${found.reason}`);
     }
-    if (missing.length) {
-      return fail(3, `${missing.join("\n  ")}
+    if (missing2.length) {
+      return fail(3, `${missing2.join("\n  ")}
   Nothing was changed. Install the GitHub App there, or re-run with --local to poll from this machine.`);
     }
   }
   const project = existing ?? await (deps.resolveProject ?? resolveOrCreateProject)(supabase, authed2.userId, opts.project);
   const board = { authed: authed2, orgId: authed2.orgId, projectId: project.projectId, project: opts.project, scanBranch };
   if (roster.fold) {
-    const failed2 = await foldForRepos({ supabase, projectId: project.projectId, scanBranch }, roster.fold, "multi-repo add-repos", {
+    const failed = await foldForRepos({ supabase, projectId: project.projectId, scanBranch }, roster.fold, "multi-repo add-repos", {
       foldBoard: deps.foldBoard,
       log
     });
-    if (failed2) return fail(3, `${failed2}
+    if (failed) return fail(3, `${failed}
   Nothing was scanned.`);
   }
   const register = serialized(registerLocalWatch);
@@ -24967,23 +25068,23 @@ async function runAddRepos(opts, deps = {}) {
   ${MULTI_REPO_DAEMON_NOTE}`);
     return 0;
   }
-  const offerUndo = async () => {
+  const offerUndo = async (client) => {
     if (!await confirm("Remove what this run wrote to the board? It goes back to how it was before this run, as one new commit.")) {
       log("  Left the board as it is.");
       return;
     }
     try {
-      const architecture = before.headCommitId ? before.architecture : (await load2(supabase, project.projectId, project.defaultBranch)).architecture;
-      const restored = await (deps.restoreBoard ?? ((s, o2) => restoreBoard(s, o2)))(supabase, {
+      const architecture = before.headCommitId ? before.architecture : (await load2(client, project.projectId, project.defaultBranch)).architecture;
+      const restored = await (deps.restoreBoard ?? ((s, o2) => restoreBoard(s, o2)))(client, {
         projectId: project.projectId,
         branch: scanBranch,
         snapshot: { architecture, headCommitId: before.headCommitId },
-        message: "Undo archme add-repos (plan not approved)",
+        message: "Undo archme add-repos (no repo was scanned)",
         isOwn: isThisRunsWrite
       });
       if (roster.fold && !hasRepoContainers(before.architecture)) {
         await (deps.setRepoContainer ?? ((s, p, r, c3) => setRepoContainer(s, p, r, c3)))(
-          supabase,
+          client,
           project.projectId,
           roster.fold.repo,
           null
@@ -24995,105 +25096,82 @@ async function runAddRepos(opts, deps = {}) {
     }
   };
   const interactive = !opts.yes;
+  const [nodeBin, cliEntry] = deps.archmeCommand === void 0 ? archmeSelfCommand() : [null, null];
+  const runSheet = buildRunSheet({
+    project: opts.project,
+    scanBranch,
+    workspace,
+    archme: deps.archmeCommand ?? `${shellQuote(nodeBin)} ${shellQuote(cliEntry)}`,
+    local: opts.local,
+    scan: todo.map((c3) => ({ repo: c3.target.repo, root: c3.root, containerId: containerFor(c3.target.repo) })),
+    context: [
+      ...done.map((c3) => ({ repo: c3.target.repo, containerId: containerFor(c3.target.repo), why: "already scanned" })),
+      ...noClone.map((repo) => ({ repo, containerId: containerFor(repo), why: "no clone here; read it through the graph" }))
+    ]
+  });
   const t0 = Date.now();
   log(`
-\u2500\u2500 Plan session (${interactive ? "interactive \u2014 exit it when the plan looks right" : "headless"}) \u2500\u2500`);
-  const plan = await session(
-    { repoPath: workspace, project: opts.project, branch: scanBranch, mode: "roster", repos: roster.repos, plan: true, interactive, log },
+\u2500\u2500 Orchestrator session (${interactive ? "interactive \u2014 keep it open until it finishes; closing it stops the scans it runs" : "headless"}) \u2500\u2500`);
+  const orchestrated = await session(
+    {
+      repoPath: workspace,
+      project: opts.project,
+      branch: scanBranch,
+      mode: "orchestrator",
+      repos: roster.repos,
+      runSheet,
+      interactive,
+      timeoutMs: null,
+      log
+    },
     { authed: authed2 }
   );
-  const planExit = dispatchExitCode(plan);
-  log(`  plan session: ${duration(Date.now() - t0)}`);
-  if (planExit !== 0) {
-    log(`archme add-repos: the plan session exited ${planExit}; nothing was scanned.`);
-    if (interactive) await offerUndo();
-    return planExit;
-  }
-  if (interactive) {
-    if (!await confirm(`Scan ${plural(todo.length, "repo")} against this plan?`)) {
-      await offerUndo();
-      return 1;
-    }
-  } else {
-    log("  plan approved (--yes)");
-  }
-  log(`
-\u2500\u2500 Scanning ${plural(todo.length, "repo")}, ${Math.min(opts.parallel, todo.length)} at a time \u2500\u2500`);
-  const results = await mapLimited(todo, opts.parallel, async (clone) => {
-    const tag = `[${clone.target.repoName}]`;
-    const started = Date.now();
-    const containerPath = `root.${containerFor(clone.target.repo)}`;
-    try {
-      const out = await addRepo(
-        board,
-        {
-          root: clone.root,
-          originUrl: clone.originUrl,
-          target: { ...clone.target, archmeBranch: scanBranch },
-          container: containerFor(clone.target.repo),
-          local: opts.local,
-          interactive: false,
-          plan: true,
-          echo: (line) => log(`${tag} ${line}`)
-        },
-        { log: tagged(clone), registerLocalWatch: register }
-      );
-      const ms = Date.now() - started;
-      if (!out.ok) return { clone, containerPath, marker: null, ms, error: { exitCode: out.exitCode, reason: out.reason ?? "the scan failed" } };
-      const marker = await readMarker(supabase, project.projectId, scanBranch, clone.target.repo);
-      const error = marker ? null : { exitCode: 1, reason: "the scan ended without stamping its resume marker (complete_scan)" };
-      return { clone, containerPath: out.containerPath, marker, ms, error };
-    } catch (e) {
-      return { clone, containerPath, marker: null, ms: Date.now() - started, error: { exitCode: 3, reason: e instanceof Error ? e.message : String(e) } };
-    }
+  const sessionExit = dispatchExitCode(orchestrated);
+  log(sessionExit === 0 ? `  orchestrator session: ${duration(Date.now() - t0)}` : `  orchestrator session exited ${sessionExit} after ${duration(Date.now() - t0)}`);
+  const after = await (deps.authenticate ?? createAuthedClient)({
+    supabaseUrl: cfg.supabaseUrl,
+    supabaseAnonKey: cfg.supabaseAnonKey,
+    clientId: cfg.archmeDaemonClientId,
+    preSpawnMinLifetimeMs: ORCHESTRATED_SCAN_TOKEN_MIN_LIFETIME_MS
   });
-  const added = results.filter((r) => !r.error);
-  const failed = results.filter((r) => r.error);
-  let stitchExit = null;
-  if (added.length > 0) {
-    const t1 = Date.now();
-    log(`
-\u2500\u2500 Stitch session (${interactive ? "interactive" : "headless"}) \u2500\u2500`);
-    stitchExit = dispatchExitCode(await session(
-      { repoPath: workspace, project: opts.project, branch: scanBranch, mode: "stitch", plan: true, interactive, log },
-      { authed: authed2 }
-    ));
-    log(`  stitch session: ${duration(Date.now() - t1)}`);
+  const results = [];
+  for (const c3 of todo) {
+    results.push({ clone: c3, marker: await readMarker(after.supabase, project.projectId, scanBranch, c3.target.repo) });
   }
+  const added = results.filter((r) => r.marker);
+  const missing = results.filter((r) => !r.marker);
+  if (added.length === 0 && interactive) await offerUndo(after.supabase);
   const rerun = [
     explicit ? "" : `cd ${shellQuote(workspace)} && `,
     "archme add-repos",
     ...explicit ? clones.map((c3) => ` ${shellQuote(c3.root)}`) : [],
     ` --project ${opts.project}`,
     opts.local ? " --local" : "",
-    opts.parallel !== 2 ? ` --parallel ${opts.parallel}` : "",
     opts.yes ? " --yes" : ""
   ].join("");
   const width = Math.max(...results.map((r) => r.clone.target.repo.length));
   log("\n\u2500\u2500 Summary \u2500\u2500");
   for (const r of added) {
-    log(`  \u2713 ${r.clone.target.repo.padEnd(width)} \u2192 ${r.containerPath}  marker ${r.marker.slice(0, 7)}  (${duration(r.ms)})`);
+    log(`  \u2713 ${r.clone.target.repo.padEnd(width)} \u2192 root.${containerFor(r.clone.target.repo)}  marker ${r.marker.slice(0, 7)}`);
   }
-  for (const r of failed) {
-    log(`  \u2717 ${r.clone.target.repo.padEnd(width)} failed (exit ${r.error.exitCode}): ${r.error.reason}`);
+  for (const r of missing) {
+    log(`  \u2717 ${r.clone.target.repo.padEnd(width)} has no resume marker: its scan did not finish`);
   }
   if (toWatch.length) log(`  watched, already scanned: ${toWatch.map((c3) => c3.target.repo).join(", ")}`);
   if (skipped.length) log(`  skipped, already on the board: ${skipped.map((c3) => c3.target.repo).join(", ")}`);
-  if (failed.length) log(`  Re-run (skips what is already on the board):
+  if (missing.length) log(`  Re-run (skips what is already on the board):
     ${rerun}`);
-  if (stitchExit === null) log("  Stitch: not run \u2014 no repo was added.");
-  else if (stitchExit !== 0) log(`  Stitch: exited ${stitchExit}. Re-run it alone: cd ${shellQuote(workspace)} && archme scan --stitch --project ${opts.project}`);
   log(`  Board: ${deriveWebOrigin(cfg.archmeMcpBaseUrl, "fallback")}/a/${encodeURIComponent(project.orgSlug)}/${encodeURIComponent(project.projectSlug)}/${encodeURIComponent(scanBranch)}`);
-  if (stitchExit !== null) {
-    const after = await load2(supabase, project.projectId, scanBranch).catch(() => null);
-    const changes = after?.architecture.context?.entries.find((e) => e.id === PLAN_CHANGES_ID);
+  const end = await load2(after.supabase, project.projectId, scanBranch).catch(() => null);
+  const changes = end?.architecture.context?.entries.find((e) => e.id === PLAN_CHANGES_ID);
+  if (changes) {
     log("\nWhat changed from the approved plan, and why:");
-    log(changes ? changes.content.split("\n").map((l) => `  ${l}`).join("\n") : "  (the stitch session recorded no explanation)");
+    log(changes.content.split("\n").map((l) => `  ${l}`).join("\n"));
   }
   log(`
   Watching queues work; the daemon runs it:  archme daemon start
   ${MULTI_REPO_DAEMON_NOTE}`);
-  return failed[0]?.error.exitCode ?? (stitchExit && stitchExit !== 0 ? stitchExit : 0);
+  return sessionExit !== 0 ? sessionExit : missing.length > 0 ? 1 : 0;
 }
 var EMPTY, REPO_NAME_RE;
 var init_run3 = __esm({
@@ -25103,6 +25181,7 @@ var init_run3 = __esm({
     init_defaults();
     init_authedClient();
     init_run_scan();
+    init_install();
     init_dispatch3();
     init_web_url();
     init_run_init();
@@ -25129,7 +25208,6 @@ var init_run3 = __esm({
 // src/addRepos/dispatch.ts
 var dispatch_exports7 = {};
 __export(dispatch_exports7, {
-  MAX_PARALLEL: () => MAX_PARALLEL,
   dispatchAddRepos: () => dispatchAddRepos,
   parseAddReposArgs: () => parseAddReposArgs,
   printAddReposHelp: () => printAddReposHelp
@@ -25143,7 +25221,6 @@ function parseAddReposArgs(argv) {
   let project;
   let local = false;
   let yes = false;
-  let parallel = 2;
   for (let i2 = 0; i2 < argv.length; i2++) {
     const arg = argv[i2];
     const next = argv[i2 + 1];
@@ -25151,11 +25228,6 @@ function parseAddReposArgs(argv) {
       if (!next || !PROJECT_SLUG_RE5.test(next)) return err3("--project needs `org/slug`");
       project = next;
       i2++;
-    } else if (arg === "--parallel") {
-      const n2 = Number(next);
-      if (!next || !Number.isInteger(n2) || n2 < 1 || n2 > MAX_PARALLEL) return err3(`--parallel needs a number from 1 to ${MAX_PARALLEL}`);
-      parallel = n2;
-      i2++;
     } else if (arg === "--local") {
       local = true;
     } else if (arg === "--yes" || arg === "--no-interactive") {
@@ -25167,33 +25239,39 @@ function parseAddReposArgs(argv) {
     }
   }
   if (!project) return err3("--project <org/slug> is required \u2014 the multi-repo project to add the repos to");
-  return { kind: "run", opts: { targets, project, local, parallel, yes } };
+  return { kind: "run", opts: { targets, project, local, yes } };
 }
 function printAddReposHelp() {
   console.log(`archme add-repos \u2014 add several repos to a multi-repo project in one run
 
 Usage:
-  archme add-repos [clone-path | owner/name \u2026] --project <org/slug> [--local] [--parallel <n>] [--yes]
+  archme add-repos [clone-path | owner/name \u2026] --project <org/slug> [--local] [--yes]
 
 Each repo is a clone path, or owner/name: a clone of it already in the current
 folder is used, otherwise it is cloned there with your own git access. With
 none given, every git clone directly under the current folder is added.
 Clones of repos the board already holds are read as context, not re-added.
 
-  1. Checks everything first (project, GitHub App, containers); writes nothing
-     until all pass. A single-repo board is folded into its repo's container.
-  2. Plan session, interactive: names every repo's container and the shared
-     externals, and drafts the story plan with you. Exit it, then confirm.
-  3. One headless scan per repo, inside its own clone, against the plan.
-  4. Stitch session, interactive: wires what crosses repos and explains what
-     changed from the plan.
-
+Checks everything first (project, GitHub App, containers) and writes nothing
+until all pass; a single-repo board is folded into its repo's container. Then
+ONE orchestrator agent runs the rest, in an interactive session:
+
+  1. The gist: names every repo's container and the shared externals, studies
+     each repo and the product (web included), and drafts the story plan with
+     you until you approve it.
+  2. Depth: studies each repo's code and git history, revises the plan, and
+     shows you what changed until you approve it.
+  3. Build: launches one scan per repo (\`archme add-repo --plan\`, hours each),
+     supervises them \u2014 answering their questions, pausing and resuming any that
+     go off course \u2014 and stitches what crosses repos as each side lands, then
+     explains what changed from the plan.
+
+Keep the session open until it finishes: closing it stops the scans it runs.
 Re-running skips repos already on the board, so a failed run resumes.
 
 Options:
   --project <org/slug>   The multi-repo project (required)
   --local                Poll from this machine instead of the GitHub App
-  --parallel <n>         Repos scanned at once, 1-${MAX_PARALLEL} (default 2)
   --yes                  Everything headless, no questions; the plan is approved`);
 }
 async function dispatchAddRepos(argv) {
@@ -25215,12 +25293,11 @@ async function dispatchAddRepos(argv) {
     return 3;
   }
 }
-var PROJECT_SLUG_RE5, MAX_PARALLEL;
+var PROJECT_SLUG_RE5;
 var init_dispatch7 = __esm({
   "src/addRepos/dispatch.ts"() {
     "use strict";
     PROJECT_SLUG_RE5 = /^[^/\s]+\/[^/\s]+$/;
-    MAX_PARALLEL = 3;
   }
 });
 
@@ -25616,7 +25693,7 @@ __export(dispatch_exports8, {
   parseDoctorArgs: () => parseDoctorArgs,
   printDoctorHelp: () => printDoctorHelp
 });
-import { mkdtemp as mkdtemp5, rm as rm10, writeFile as writeFile13 } from "node:fs/promises";
+import { mkdtemp as mkdtemp5, rm as rm10, writeFile as writeFile14 } from "node:fs/promises";
 import { tmpdir as tmpdir5 } from "node:os";
 import { join as join28 } from "node:path";
 function parseDoctorArgs(argv) {
@@ -25681,7 +25758,7 @@ async function dispatchDoctor(argv) {
   }
   const dir = await mkdtemp5(join28(tmpdir5(), "archme-doctor-"));
   const mcpConfigPath = join28(dir, "mcp.json");
-  await writeFile13(mcpConfigPath, JSON.stringify({ mcpServers: {} }), { mode: 384 });
+  await writeFile14(mcpConfigPath, JSON.stringify({ mcpServers: {} }), { mode: 384 });
   try {
     const result = await spawnClaude({
       prompt: buildDoctorPrompt(facts, issues),
@@ -26090,7 +26167,8 @@ Other commands:
                                       (--list|--stop|--resume)
   archme add-repos [clone-path | owner/name \u2026] --project <org/slug>
                                       Add several repos to a multi-repo project:
-                                      plan, scan each, stitch (resumable)
+                                      one agent plans with you, scans each,
+                                      stitches as they land (resumable)
   archme add-repo [repo-path] --project <org/slug>
                                       Add one repo to a multi-repo project
   archme uninstall [repo-path]        Stop ArchitectMe for a repo: config,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archme/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Map your codebase into a living architecture diagram: run `archme init` in a repo to scan it, `archme daemon start` to keep it current on every commit.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",