@mmerterden/multi-agent-pipeline 20.30.0 → 20.33.0

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -40,10 +40,12 @@ const CONTRACT = JSON.parse(
   readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8"),
 );
 const PHASES = CONTRACT.phases;
+// A mode may name its steps itself: the analysis command runs the six slots as
+// Intake, Evidence, Synthesis, Review, Publish and Report.
 const modePhases = (name) =>
   CONTRACT.modes[name].phases.map((id) => {
     const p = PHASES.find((x) => x.id === id);
-    return `${p.id}:${p.name}`;
+    return `${p.id}:${CONTRACT.modes[name].names?.[id] ?? p.name}`;
   });
 
 const PHASE_NAMES = PHASES.map((p) => `${p.id}:${p.name}`);

package/pipeline/scripts/job-launch.mjs

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+/**
+ * job-launch.mjs  -  turn an office job into one unattended background session.
+ *
+ * A job is an entry of schemas/office-jobs.json: a command, the role that does
+ * it, whether it is a team job (a pipeline run, which meets in a room) or a
+ * solo one (one agent at a desk), and typed parameters. Nothing here takes
+ * free text except a team job's work item, which goes through the launch
+ * request rules (launch-request.mjs inputErrors) like every other launch.
+ *
+ * planJob checks a job against the catalog and builds what the server starts:
+ * the same `claude --bg` shape launch.json declares for background runs, the
+ * unattended permission profile, no permission prompts, and the environment
+ * that marks the session unattended. A team job writes a launch request the
+ * run's Phase 0 reads; a solo job names its command and arguments directly.
+ * startJob starts it through lib/bg-launch.mjs with the autopilot runner's
+ * sandbox check, and records the session under the office log so the floor
+ * can seat it where it belongs. A team job is refused while another run is
+ * live in the same repository, as the autopilot queue does: two runs in one
+ * checkout fight over the git index.
+ *
+ *   node job-launch.mjs list          the catalog with availability (JSON)
+ *
+ * @module pipeline/scripts/job-launch
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize, sep } from "node:path";
+
+import { startBackgroundAsync } from "../lib/bg-launch.mjs";
+import { listSessions, sessionLiveness } from "../lib/claude-sessions.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { unattendedLogsRoot } from "../lib/pr-request-location.mjs";
+import { unattendedSettingsPath } from "../lib/unattended-settings-location.mjs";
+import { commandsDir } from "./commands.mjs";
+import {
+  CONTRACT_VERSION as LAUNCH_VERSION,
+  configuredJiraHost,
+  inputErrors,
+  launchSpec,
+  planLaunch,
+  workingTreeState,
+  writeRequestFile,
+} from "./launch-request.mjs";
+import { listRuns, logsRoot } from "./_run-paths.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+
+const JOBS = JSON.parse(
+  readFileSync(new URL("../schemas/office-jobs.json", import.meta.url), "utf8"),
+);
+
+const JIRA_KEY = /^[A-Z][A-Z0-9]+-[0-9]+$/;
+const GH_OWNER = "[A-Za-z0-9][A-Za-z0-9-]{0,38}";
+const GH_REPO = "[A-Za-z0-9._-]{1,100}";
+const PR_URL = new RegExp(`^https://github\\.com/${GH_OWNER}/${GH_REPO}/pull/[1-9][0-9]{0,9}$`);
+const ISSUE_URL = new RegExp(
+  `^https://github\\.com/${GH_OWNER}/${GH_REPO}/issues/[1-9][0-9]{0,9}$`,
+);
+const SHORT_REF = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}#[1-9][0-9]{0,9}$/;
+const NUMBER_REF = /^#[1-9][0-9]{0,9}$/;
+const RUN_ID = /^[A-Za-z0-9#][A-Za-z0-9#._-]{0,127}$/;
+const BRANCH = /^(?!-)(?!.*\.\.)(?!.*\/\/)[A-Za-z0-9._/-]{1,200}(?<![./])$/;
+const REPO_PATH = /^(?![/-])(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/-]{1,300}$/;
+
+export class JobError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.code = code;
+    this.extra = extra;
+  }
+}
+
+/** Every job in the catalog, in catalog order. */
+export const jobs = () => JOBS.jobs;
+
+export const jobById = (id) => JOBS.jobs.find((j) => j.id === id) ?? null;
+
+/**
+ * The catalog as GET /v1/jobs serves it: each job with whether its command is
+ * installed here, and why not when it is not.
+ */
+export function jobsDocument() {
+  const dir = commandsDir();
+  return {
+    contractVersion: CONTRACT_VERSION,
+    jobs: JOBS.jobs.map((j) => {
+      const installed =
+        j.command === "multi-agent" || Boolean(dir && existsSync(join(dir, j.command, "SKILL.md")));
+      return { ...j, available: installed, reason: installed ? null : "command-not-installed" };
+    }),
+  };
+}
+
+/** A path inside the repository, relative, that exists there. */
+function insideRepo(repoPath, rel) {
+  if (!REPO_PATH.test(rel)) return false;
+  const full = normalize(join(repoPath, rel));
+  if (full !== repoPath && !full.startsWith(repoPath + sep)) return false;
+  try {
+    const real = realpathSync(full);
+    const root = realpathSync(repoPath);
+    return real === root || real.startsWith(root + sep);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every reason `args` do not fit `job`. A run id must be a run the index
+ * knows; a repository path must stay inside the repository.
+ */
+export function paramErrors(
+  job,
+  args,
+  { repoPath, jiraHost = configuredJiraHost(), knownRun } = {},
+) {
+  const errors = [];
+  const given = args && typeof args === "object" && !Array.isArray(args) ? args : null;
+  if (!given) return ["args must be an object"];
+  for (const k of Object.keys(given)) {
+    if (!job.params.some((p) => p.name === k)) errors.push(`unknown parameter ${k}`);
+  }
+  for (const p of job.params) {
+    const v = given[p.name];
+    if (v === undefined || v === "") {
+      if (p.required) errors.push(`${p.name} is required`);
+      continue;
+    }
+    if (typeof v !== "string" || v.length > 4000) {
+      errors.push(`${p.name} must be a string`);
+      continue;
+    }
+    const bad = (why) => errors.push(`${p.name}: ${why}`);
+    switch (p.kind) {
+      case "work-item":
+        for (const e of inputErrors(v, { channel: "desktop", jiraHost })) bad(e);
+        break;
+      case "pull-request":
+        if (!PR_URL.test(v) && !SHORT_REF.test(v) && !NUMBER_REF.test(v))
+          bad("a GitHub pull request URL, repo#N or #N");
+        break;
+      case "github-issue":
+        if (!ISSUE_URL.test(v) && !SHORT_REF.test(v) && !NUMBER_REF.test(v))
+          bad("a GitHub issue URL, repo#N or #N");
+        break;
+      case "jira-key":
+        if (!JIRA_KEY.test(v)) bad("a Jira key such as PROJ-123");
+        break;
+      case "branch":
+        if (!BRANCH.test(v)) bad("a branch name");
+        break;
+      case "run-id":
+        if (!RUN_ID.test(v)) bad("a run id");
+        else if (knownRun && !knownRun(v)) bad("no run has that id");
+        break;
+      case "enum":
+        if (!p.values.includes(v)) bad(`one of ${p.values.join(", ")}`);
+        break;
+      case "repo-path":
+        if (!repoPath || !insideRepo(repoPath, v)) bad("a path inside the repository");
+        break;
+      default:
+        bad("unknown kind");
+    }
+  }
+  return errors;
+}
+
+// A team job started here holds its room until its run writes agent-state.json,
+// which takes a moment; without this a second start in that moment would pass.
+const HOLD_MS = 5 * 60 * 1000;
+const LIST_GRACE_MS = 60 * 1000;
+const held = new Map();
+
+/** Hold the room; returns the key to release it with, or null. */
+function holdRoom(repoPath, taskId, sessionId) {
+  try {
+    const key = realpathSync(repoPath);
+    held.set(key, { taskId, sessionId, at: Date.now() });
+    return key;
+  } catch {
+    // A folder that cannot be resolved has no room to hold.
+    return null;
+  }
+}
+
+/** The run live in `repoPath` right now, or null. A list that cannot be read concludes nothing. */
+export function liveRunIn(repoPath, { sessions = listSessions() } = {}) {
+  let root;
+  try {
+    root = realpathSync(repoPath);
+  } catch {
+    return null;
+  }
+  const hold = held.get(root);
+  // The hold ends after HOLD_MS, or once its session has had time to show up
+  // in the session list and is not there or not live.
+  const age = hold ? Date.now() - hold.at : Infinity;
+  const gone =
+    Boolean(hold) && age > LIST_GRACE_MS && sessionLiveness(hold.sessionId, sessions) === false;
+  if (hold && age < HOLD_MS && !gone) return hold.taskId;
+  if (hold) held.delete(root);
+  for (const rec of startedJobs().values()) {
+    if (!rec.team || !rec.repoPath) continue;
+    let at;
+    try {
+      at = realpathSync(rec.repoPath);
+    } catch {
+      continue;
+    }
+    if (at === root && sessionLiveness(rec.sessionId, sessions) === true) return `job ${rec.jobId}`;
+  }
+  for (const base of new Set([logsRoot(), unattendedLogsRoot()])) {
+    for (const run of listRuns(base)) {
+      let state;
+      try {
+        state = JSON.parse(readFileSync(join(run.dir, "agent-state.json"), "utf8"));
+      } catch {
+        continue;
+      }
+      if (!["in_progress", "awaiting_input"].includes(state?.status)) continue;
+      let at;
+      try {
+        at = realpathSync(state.projectRoot ?? "");
+      } catch {
+        continue;
+      }
+      if (at !== root) continue;
+      if (sessionLiveness(state.sessionId, sessions) === false) continue;
+      return run.taskId;
+    }
+  }
+  return null;
+}
+
+const fill = (template, values) =>
+  template.replace(/\{([a-zA-Z]+)\}/g, (whole, k) => (k in values ? values[k] : whole));
+
+/** The prompt a solo job's session receives: the command and its arguments, in catalog order. */
+export function soloPrompt(job, args) {
+  const parts = job.params.map((p) => args[p.name]).filter((v) => typeof v === "string" && v);
+  return [`/multi-agent:${job.command}`, ...parts].join(" ");
+}
+
+/**
+ * What the server starts for a job. Pure apart from the files it reads (the
+ * launch spec, the questions) and, for a team job, the request file it writes
+ * when `write` is true.
+ *
+ * @returns {{argv: string[], cwd: string, env: Record<string,string>, prompt: string,
+ *   requestFile: string|null}}
+ */
+export function planJob({ job, args, answers = {}, repoPath, sessionId, write = false }) {
+  const settingsFile = unattendedSettingsPath();
+  const runLogsRoot = unattendedLogsRoot();
+  if (job.launch) {
+    const mode = job.launch === "autopilot" ? "autopilot" : "background";
+    const request = {
+      contractVersion: LAUNCH_VERSION,
+      input: args.input,
+      mode,
+      ...(mode === "background" ? { kind: job.launch } : {}),
+      answers,
+    };
+    const requestFile = write
+      ? writeRequestFile(request, sessionId)
+      : join(runLogsRoot, "pending", `${sessionId}.json`);
+    const r = planLaunch({
+      request,
+      requestFile,
+      repoPath,
+      sessionId,
+      settingsFile,
+      runLogsRoot,
+      workingTree: workingTreeState(repoPath),
+    });
+    if (r.code !== 0) {
+      throw new JobError(r.reason ?? "invalid-request", "the launch request was refused", {
+        errors: r.out.errors,
+      });
+    }
+    return {
+      argv: r.out.argv,
+      cwd: r.out.cwd,
+      env: r.out.env,
+      prompt: r.out.argv[r.out.argv.length - 1],
+      requestFile: write ? requestFile : null,
+    };
+  }
+  const shape = launchSpec().hosts.claude.background.development;
+  const values = { sessionId, settingsFile, runLogsRoot, repoPath, requestFile: "" };
+  const prompt = soloPrompt(job, args);
+  const argv = shape.argv.slice(0, -1).map((a) => fill(a, values));
+  const env = Object.fromEntries(
+    Object.entries(shape.env)
+      // A solo job reads the operator's runs, so it keeps the operator's logs root.
+      .filter(([k]) => k !== "MA_LAUNCH_REQUEST" && k !== "LOGS_ROOT")
+      .map(([k, v]) => [k, fill(v, values)]),
+  );
+  return { argv: [...argv, prompt], cwd: repoPath, env, prompt, requestFile: null };
+}
+
+/** Where the office records the sessions it started, one 0600 file each. */
+export const jobsDir = (env = process.env) =>
+  join(env.HOME || homedir(), ".claude", "logs", "multi-agent", "office", "jobs");
+
+// A record seats its session for a day at most; older ones are dropped when
+// the next job starts, so the directory stays small for a server that runs on.
+const KEEP_MS = 24 * 60 * 60 * 1000;
+
+function pruneJobs(env) {
+  const dir = jobsDir(env);
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const n of names) {
+    if (!/^[0-9a-f-]{36}\.json$/.test(n)) continue;
+    try {
+      if (now - statSync(join(dir, n)).mtimeMs > KEEP_MS) rmSync(join(dir, n), { force: true });
+    } catch {
+      // Gone already.
+    }
+  }
+}
+
+/** The jobs the office started, by session id, for the floor to seat. */
+export function startedJobs(env = process.env) {
+  const out = new Map();
+  const dir = jobsDir(env);
+  if (!existsSync(dir)) return out;
+  for (const n of readdirSync(dir)) {
+    if (!/^[0-9a-f-]{36}\.json$/.test(n)) continue;
+    try {
+      const rec = JSON.parse(readFileSync(join(dir, n), "utf8"));
+      if (
+        rec &&
+        typeof rec.sessionId === "string" &&
+        Date.now() - Date.parse(rec.startedAt) < KEEP_MS
+      )
+        out.set(rec.sessionId, rec);
+    } catch {
+      // A record that does not parse seats nobody.
+    }
+  }
+  return out;
+}
+
+/**
+ * Check a job request and describe it, starting nothing: the preview the
+ * confirmation shows.
+ */
+export function previewJob({ jobId, args = {}, answers, repoPath, knownRun, sessions }) {
+  const job = jobById(jobId);
+  if (!job) throw new JobError("unknown-job", "no such job");
+  const doc = jobsDocument().jobs.find((j) => j.id === jobId);
+  if (!doc.available) throw new JobError("command-not-installed", "that command is not installed");
+  if (!isAbsolute(repoPath ?? ""))
+    throw new JobError("invalid-repo", "the repository path must be absolute");
+  const errors = paramErrors(job, args, { repoPath, knownRun });
+  if (
+    answers !== undefined &&
+    (!job.launch || typeof answers !== "object" || Array.isArray(answers))
+  )
+    errors.push("answers are only for a pipeline run, as an object");
+  if (errors.length)
+    throw new JobError("invalid-args", "the job does not fit its parameters", { errors });
+  if (job.team) {
+    const busy = liveRunIn(repoPath, sessions ? { sessions } : undefined);
+    if (busy)
+      throw new JobError("room-busy", "a run is already live in this repository", { taskId: busy });
+  }
+  const plan = planJob({ job, args, answers, repoPath, sessionId: randomUUID() });
+  return { job, prompt: plan.prompt };
+}
+
+/**
+ * Start a job that previewJob accepted. `precondition` is the unattended
+ * sandbox check; `start` is lib/bg-launch.mjs startBackgroundAsync (a test
+ * passes a stand-in). Resolves to the record written.
+ */
+export async function startJob({
+  jobId,
+  args = {},
+  answers,
+  repoPath,
+  repoName,
+  knownRun,
+  sessions,
+  precondition,
+  start = startBackgroundAsync,
+  env = process.env,
+}) {
+  const { job } = previewJob({ jobId, args, answers, repoPath, knownRun, sessions });
+  const sessionId = randomUUID();
+  const plan = planJob({ job, args, answers, repoPath, sessionId, write: true });
+  const { MA_RUN_BASE_SHA: _stale, ...base } = env;
+  const deny = [base.MCP_TOOLKIT_INDEX_DENY, plan.env.MCP_TOOLKIT_INDEX_DENY]
+    .flatMap((v) => String(v || "").split(","))
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const childEnv = {
+    ...base,
+    ...plan.env,
+    ...(deny.length ? { MCP_TOOLKIT_INDEX_DENY: [...new Set(deny)].join(",") } : {}),
+  };
+  const key = job.team ? holdRoom(repoPath, `job ${job.id}`, sessionId) : null;
+  const release = () => {
+    if (key) held.delete(key);
+    if (plan.requestFile) rmSync(plan.requestFile, { force: true });
+  };
+  let r;
+  try {
+    r = await start({ argv: plan.argv, cwd: plan.cwd, env: childEnv, precondition });
+  } catch (err) {
+    release();
+    throw err;
+  }
+  if (r.blocked || r.status !== 0) {
+    // A launcher that timed out may have left its session running: the room
+    // stays held and the request file stays for it.
+    if (!r.timedOut) release();
+    // What claude printed can name paths; the page gets a fixed message and
+    // the reason stays in the server's own output.
+    const why = String(r.blocked || r.stderr || r.error?.message || "").trim();
+    if (why) process.stderr.write(`job-launch: ${job.id}: ${why.slice(0, 300)}\n`);
+    if (r.blocked)
+      throw new JobError("sandbox-unavailable", "the unattended sandbox is not available");
+    throw new JobError("launch-failed", "the session did not start");
+  }
+  const record = {
+    contractVersion: CONTRACT_VERSION,
+    sessionId,
+    jobId: job.id,
+    command: job.command,
+    role: job.role,
+    team: job.team,
+    repo: repoName,
+    repoPath,
+    prompt: plan.prompt,
+    startedAt: new Date().toISOString(),
+  };
+  mkdirSync(jobsDir(env), { recursive: true, mode: 0o700 });
+  pruneJobs(env);
+  writeFileSync(join(jobsDir(env), `${sessionId}.json`), JSON.stringify(record, null, 2) + "\n", {
+    mode: 0o600,
+    flag: "wx",
+  });
+  return record;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("job-launch", () => {
+    const [cmd] = process.argv.slice(2);
+    if (cmd !== "list") {
+      process.stderr.write("usage: job-launch.mjs list\n");
+      process.exit(2);
+    }
+    process.stdout.write(JSON.stringify(jobsDocument(), null, 2) + "\n");
+  });
+}

package/pipeline/scripts/launch-request.mjs

@@ -99,6 +99,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, isAbsolute, join } from "node:path";
 import { catalog, commandsDir } from "./commands.mjs";
@@ -108,6 +109,7 @@ import { autopilotRoot, unattendedLogsRoot } from "../lib/pr-request-location.mj
 import { lockTimeoutFrom, updateJsonFileSync } from "../lib/json-file-lock.mjs";
 import { unattendedSettingsPath } from "../lib/unattended-settings-location.mjs";
 import { isUnattended } from "../lib/unattended.mjs";
+import { listRuns, logsRoot } from "./_run-paths.mjs";
 
 export const CONTRACT_VERSION = "1.1.0";
 export const MODES = ["interactive", "autopilot", "background"];
@@ -548,6 +550,84 @@ export function launchRepos(env = process.env) {
   return out;
 }
 
+/** A stable, path-free handle for a repository path, as a client names one. */
+export const repoId = (p) => createHash("sha256").update(String(p)).digest("hex").slice(0, 16);
+
+const isCheckout = (real) => existsSync(join(real, ".git"));
+
+/**
+ * Checkouts earlier runs worked in that a launch does not accept yet: each
+ * run's projectRoot (and every projects[].projectRoot) under both log roots,
+ * by real path, kept when it is a git checkout and neither the home directory
+ * nor the root. A client offers them for registration; nothing is accepted
+ * until registerRepo stores one.
+ *
+ * @returns {{id: string, path: string, name: string}[]}
+ */
+export function suggestedRepos(env = process.env) {
+  const allowed = allowedLaunchRepos(env);
+  const home = realDir(homedir());
+  const out = new Map();
+  for (const root of new Set([logsRoot(), unattendedLogsRoot()])) {
+    for (const run of listRuns(root)) {
+      const state = readJsonOr(join(run.dir, "agent-state.json"), null);
+      if (!state || typeof state !== "object") continue;
+      const roots = [
+        state.projectRoot,
+        ...(Array.isArray(state.projects) ? state.projects.map((x) => x?.projectRoot) : []),
+      ];
+      for (const raw of roots) {
+        if (typeof raw !== "string" || !isAbsolute(raw)) continue;
+        const real = realDir(raw);
+        if (!real || real === "/" || real === home || allowed.has(real) || out.has(real)) continue;
+        if (!isCheckout(real)) continue;
+        out.set(real, { id: repoId(real), path: real, name: basename(real) });
+      }
+    }
+  }
+  return [...out.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Registered entries that are no longer a directory, as a client lists them
+ * for removal: launchRepos leaves them out, so nothing else would show them.
+ *
+ * @returns {{id: string, path: string, name: string}[]}
+ */
+export function missingRepos(env = process.env) {
+  const registered = readJsonOr(launchReposPath(env), {});
+  return (Array.isArray(registered?.repos) ? registered.repos : [])
+    .filter((p) => typeof p === "string" && p && !realDir(expandHome(p)))
+    .map((p) => ({ id: repoId(p), path: p, name: basename(p) }));
+}
+
+/**
+ * Remove one registered entry, named by repoId of its stored path. Configured
+ * autopilot repos are not touched: they belong to the autopilot config.
+ * Returns the removed path, or null when no entry has that id.
+ */
+export function unregisterRepo(id, env = process.env) {
+  let removed = null;
+  updateJsonFileSync(
+    launchReposPath(env),
+    (current) => {
+      const repos = Array.isArray(current?.repos) ? current.repos : [];
+      const keep = repos.filter((p) => {
+        // The list shows entries by their real path, so match that form too.
+        const real = typeof p === "string" ? realDir(expandHome(p)) : null;
+        if (removed === null && (repoId(p) === id || (real && repoId(real) === id))) {
+          removed = p;
+          return false;
+        }
+        return true;
+      });
+      return { ...current, repos: keep };
+    },
+    { fallback: {}, mode: 0o600, timeoutMs: lockTimeoutFrom(env) },
+  );
+  return removed;
+}
+
 /** Is `repoPath` a directory a launch may start in? Compared by real path. */
 export function launchRepoAllowed(repoPath, env = process.env) {
   const real = typeof repoPath === "string" && isAbsolute(repoPath) ? realDir(repoPath) : null;
@@ -560,7 +640,7 @@ export function launchRepoAllowed(repoPath, env = process.env) {
  * The read-modify-write holds the file's lock and replaces it atomically, so
  * two registrations at once both land. Returns the stored path.
  */
-export function registerRepo(repoPath, env = process.env) {
+export function registerRepo(repoPath, env = process.env, { requireCheckout = false } = {}) {
   if (typeof repoPath !== "string" || !isAbsolute(repoPath))
     throw new Error("the path must be absolute");
   const real = realDir(repoPath);
@@ -568,6 +648,7 @@ export function registerRepo(repoPath, env = process.env) {
   if (real === "/" || real === realDir(homedir())) {
     throw new Error("the home directory or the root is not a repository");
   }
+  if (requireCheckout && !isCheckout(real)) throw new Error("the path is not a git checkout");
   const file = launchReposPath(env);
   mkdirSync(autopilotRoot(env), { recursive: true, mode: 0o700 });
   updateJsonFileSync(
@@ -798,12 +879,15 @@ function planMain(rest) {
 }
 
 /** The `repos` document: launchRepos() with contractVersion; paths dropped under redact. */
-export function reposDocument({ redact = false, env = process.env } = {}) {
+export function reposDocument({ redact = false, env = process.env, extras = false } = {}) {
   const repos = launchRepos(env);
-  return {
-    contractVersion: CONTRACT_VERSION,
-    repos: redact ? repos.map(({ path: _p, ...r }) => r) : repos,
-  };
+  const strip = (list) => (redact ? list.map(({ path: _p, ...r }) => r) : list);
+  const doc = { contractVersion: CONTRACT_VERSION, repos: strip(repos) };
+  if (extras) {
+    doc.suggested = strip(suggestedRepos(env));
+    doc.missing = strip(missingRepos(env));
+  }
+  return doc;
 }
 
 function resumeMain(rest) {
@@ -857,11 +941,12 @@ function main(argv) {
   const [cmd, ...rest] = argv;
   if (cmd === "repos") {
     const redact = rest.includes("--redact");
-    if (rest.some((a) => a !== "--redact")) {
-      process.stderr.write("launch-request: repos takes only --redact\n");
+    const extras = rest.includes("--all");
+    if (rest.some((a) => a !== "--redact" && a !== "--all")) {
+      process.stderr.write("launch-request: repos takes only --redact and --all\n");
       return 2;
     }
-    process.stdout.write(JSON.stringify(reposDocument({ redact }), null, 2) + "\n");
+    process.stdout.write(JSON.stringify(reposDocument({ redact, extras }), null, 2) + "\n");
     return 0;
   }
   if (cmd === "questions" || cmd === "spec") {