@archme/cli 0.10.0 → 0.11.1

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;
   }
@@ -13140,7 +13157,7 @@ function buildStoryCoverageGate(opts) {
 function buildFormatRefStories(opts) {
   const draftBlock = opts.persistentDrafts ? FORMAT_REF_DRAFT_STORIES_BLOCK : "";
   const uncoveredSubFlowRule = opts.persistentDrafts ? CROSS_REF_UNCOVERED_DRAFT_STUB : CROSS_REF_UNCOVERED_REAL_STORY;
-  const hierarchyExample = opts.persistentDrafts ? `- Example: storyUpdates: [{add: [{id: "auth", title: "Authentication", description: "User auth flows", draft: true, userStories: [{id: "login", title: "log in with email", draft: true, acceptanceCriteria: ["< 1s response"]}]}]}]` : `- Example: storyUpdates: [{add: [{id: "auth", title: "Authentication", description: "User auth flows", userStories: [{id: "login", title: "log in with email", acceptanceCriteria: ["< 1s response"], sequence: "sequenceDiagram\\n    ..."}]}]}]`;
+  const hierarchyExample = opts.persistentDrafts ? `- Example: storyUpdates: [{add: [{id: "auth", title: "Authentication", description: "User auth flows", draft: true, userStories: [{id: "login", title: "log in with email", draft: true}]}]}]` : `- Example: storyUpdates: [{add: [{id: "auth", title: "Authentication", description: "User auth flows", userStories: [{id: "login", title: "log in with email", sequence: "sequenceDiagram\\n    ..."}]}]}]`;
   return `Recursive story hierarchy:
 - Stories can contain child stories via userStories: [...] \u2014 parent stories act as feature groups
 - Use top-level stories with description, links, and nested children to organize by feature area
@@ -13157,11 +13174,6 @@ Story description format (markdown, 1-4 sentences \u2014 render target is a narr
 - Good: "A signed-out user requests a reset link by email and sets a new password from that link. Links expire after an hour and work once."
 - Bad (3x too long, implementation-level, changelog-style): "The forgot-password handler generates a token via crypto.randomUUID(), inserts a row into password_reset_tokens with expires_at = now() + 1 hour, emails it through the SendGrid client, and the reset endpoint validates the token with FOR UPDATE SKIP LOCKED before calling auth.admin.updateUserById..."
 
-Acceptance criteria format:
-- Each criterion should be an observable guarantee or behavior someone could verify without reading the code.
-- Bad: "RLS policy checks auth.uid() against org_members", "Uses FOR UPDATE SKIP LOCKED in claim query"
-- Good: "Only org members can view jobs", "Concurrent workers never claim the same job"
-
 ${draftBlock}Sequence diagram format:
 - Each story has a "sequence" field containing a Mermaid sequence diagram string
 - Use architecture dot-paths as participant IDs (e.g., root.api.gateway)
@@ -13335,14 +13347,13 @@ Connection format:
     FORMAT_REF_DRAFT_STORIES_BLOCK = `Draft stories:
 - Set draft: true for stories where the architecture isn't built yet
 - Draft inheritance: if a parent has draft: true, all descendants are implicitly draft (skip validation)
-- Draft stories can omit sequence entirely \u2014 they're pure requirements
+- Draft stories can omit sequence entirely \u2014 a title and description are enough
 - Draft stories skip all validation (waypoints, connectivity)
-- Use acceptanceCriteria: string[] for PRD-style requirements on draft stories
 - When architecture supports the story, add a sequence and set draft: false
-- Example draft: {id: "send_push", title: "Send push notification", draft: true, acceptanceCriteria: ["Delivered within 5s", "Supports iOS and Android"]}
+- Example draft: {id: "send_push", title: "Send push notification", draft: true, description: "A user gets a push notification on iOS or Android within seconds of the event."}
 
 `;
-    CROSS_REF_UNCOVERED_DRAFT_STUB = `- If no existing story covers the sub-flow but it is reusable across multiple parent stories, create a draft story for it (acceptanceCriteria only, no sequence) and reference that draft. The draft can be wired up later.`;
+    CROSS_REF_UNCOVERED_DRAFT_STUB = `- If no existing story covers the sub-flow but it is reusable across multiple parent stories, create a draft story for it (title and description only, no sequence) and reference that draft. The draft can be wired up later.`;
     CROSS_REF_UNCOVERED_REAL_STORY = `- If no existing story covers the sub-flow but it is reusable across multiple parent stories, create a real story for it \u2014 with its own sequence traced from the code \u2014 and reference that. Do not leave a sequence-less draft stub.`;
     FORMAT_REF_STORIES = buildFormatRefStories({ persistentDrafts: true });
   }
@@ -13608,6 +13619,8 @@ var init_validationCodes = __esm({
       STORY_MISSING_SEQUENCE_FOR_LEAF: "story.add.missing-sequence-for-leaf",
       /** Parent story id referenced by `under` was not found. */
       STORY_UNDER_PARENT_NOT_FOUND: "story.add.under-parent-not-found",
+      /** An MCP write set `acceptanceCriteria`, which only people author. */
+      STORY_ACCEPTANCE_CRITERIA_AGENT_WRITE: "story.add.acceptance-criteria-agent-write",
       // ──────────────────────────────────────────────────────────────────────────
       // story.remove
       // ──────────────────────────────────────────────────────────────────────────
@@ -13904,7 +13917,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 +13926,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.`;
   }
 });
 
@@ -19528,6 +19545,9 @@ Rules:
 ## Data Shape (schemas)
 A data-shape change with unchanged topology is still an architectural change \u2014 the same components can talk in the same order while the shape of the data on the wire changes. If this change adds, removes, or retypes a **DB column**, a **function/RPC parameter**, or a **response/return field**, update the \`schema\` of the affected storage component (table, RPC, queue, any persistence layer) and the **input/output interface children** the data flows through. Compact format: \`{ field: type, field?: type, field!: generated, arr: type[], ... }\`. For a **persisted table**, set \`schemaKind: "table"\` + \`schemaName\` on the component and tag key columns inline (\`id: uuid @pk\`, \`user_id?: uuid @fk(auth.users.id)\`); keep DDL, RLS policies, and indexes OUT of \`schema\` \u2014 those are code (the anchored migration). Match the code exactly \u2014 do NOT invent fields the code doesn't have; a \`schema\` more complete than the code can prove is over-claiming.
 
+## Behaviour at a step
+A behaviour change with unchanged participants is still an architectural change: the same components talk in the same order, but what a step does or guarantees has changed (the caller's real IP now reaches the backend, a failed call is now retried, a limit is now enforced). Show it in the \`sequence\` of the story that draws that step \u2014 reword that arrow, or add a short Note at that step when no arrow can carry it (see Sequence wording). A component \`description\` edit on its own barely shows in review, so it does not stand in for the sequence edit.
+
 ## Draft Story Guidance
 \`draft: true\` is a transient build mechanic, not a deliverable: it skips sequence validation while a story is being assembled, and a parent's draft flag propagates to all descendants (suppressing \`autoCreateConnectionsFromStories\`). Feature-group parent stories that have real, sequenced children are NOT drafts. You may set it mid-run to defer validation while assembling a story, but finish the run with zero drafts you created or touched: give each a real sequence and set \`draft: false\`, or remove it. Pre-existing drafts you didn't touch are not yours to sweep.
 
@@ -19886,6 +19906,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 +19946,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 +19954,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 +20531,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 +20575,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 +20589,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 +20892,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 +20953,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 +20990,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 +21098,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 +21125,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 +22188,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 +22238,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 +23468,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 +23522,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 +23535,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 +23545,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 +24701,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 +24719,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 +24736,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 +24760,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 +24789,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 +24802,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 +24810,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 +24845,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 +24857,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 +24866,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 +24902,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 +24955,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 +24985,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 +25021,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 +25067,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 +25095,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 +25180,7 @@ var init_run3 = __esm({
     init_defaults();
     init_authedClient();
     init_run_scan();
+    init_install();
     init_dispatch3();
     init_web_url();
     init_run_init();
@@ -25129,7 +25207,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 +25220,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 +25227,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 +25238,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 +25292,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 +25692,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 +25757,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 +26166,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.1",
   "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",