@yaawn/workflow 0.0.0-stage → 0.4.0

package/agents/skills/yaawn-implement-plan/scripts/parallel.ts

@@ -0,0 +1,1176 @@
+import { type ChildProcess, execFile, spawn } from "node:child_process";
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { createInterface as createPrompt } from "node:readline/promises";
+import type { Readable } from "node:stream";
+import { promisify } from "node:util";
+import {
+  type AgentChoice,
+  type AgentName,
+  readAgent,
+} from "./agent.js";
+import { keepMacAwakeWhileRunning, printWalkAwayBanner } from "./caffeinate.js";
+import {
+  type ImplementationGroup,
+  type LabelAction,
+  type Lane,
+  allCompatibleGroups,
+  assignGroups,
+  conflictGraph,
+  filesToChange,
+  filesToChangeHeading,
+  groupLabel,
+  groupLabelRemovals,
+  groupsOf,
+  labelActions,
+  laneFiles,
+  laneIssueNumbers,
+  laneOwners,
+  lanePairs,
+} from "./groups.js";
+import { drainOutput } from "./processes.js";
+import {
+  type LaneOutcomeState,
+  type StageLabel,
+  laneStartedLabel,
+  parseStageMarker,
+  runResultLine as outcomeResultLine,
+  runningResult,
+  stoppedResult,
+} from "./stages.js";
+import {
+  type Issue,
+  addLabel,
+  ensureGroupLabel,
+  executionOrder,
+  gh,
+  ghAsync,
+  issueFailuresAsync,
+  issueRefs,
+  plansDir,
+  removeGroupLabels,
+  removeLabel,
+  resolveTargets,
+  resolveTargetsAsync,
+  resultPath,
+  succeeds,
+  succeedsAsync,
+  uncommittedChangesAsync,
+} from "./targets.js";
+import {
+  type MainCopyCheck,
+  blockedUpdateReason,
+  branchName,
+  describeMainCopyState,
+  fetchMainCopy,
+  git,
+  isBareLayout,
+  laneWorktreePath,
+  registeredWorktrees,
+  syncMainCopy,
+} from "./worktrees.js";
+
+// Every launch: one lane per issue, each in its own git worktree, each
+// running `overnight.ts lane <issue> --agent <name>` there.
+
+export interface LaunchRequest {
+  issues: number[];
+  ready: boolean;
+  maxParallel: number | null;
+}
+
+type LaneState = LaneOutcomeState;
+
+// The lane issue's title names a new worktree directory; an existing checkout
+// of the lane branch is reused instead.
+interface TitledLane extends Lane {
+  title: string;
+}
+
+// What a pre-flight lookup found, or why it could not look.
+interface Lookup<T> {
+  value: T;
+  failures: string[];
+}
+
+// The lanes that passed every pre-flight check, and the main copy's
+// uncommitted changes (without the plans directory).
+interface CheckedLaunch {
+  lanes: TitledLane[];
+  changes: string;
+}
+
+interface ActiveRun {
+  pid: number;
+  tokens: string[];
+}
+
+interface LaneRun {
+  lane: TitledLane;
+  agent: AgentName;
+  worktree: string;
+  state: LaneState;
+  stage: StageLabel;
+  tail: string[];
+  result: string;
+}
+
+const overnightScript =
+  ".agents/skills/yaawn-implement-plan/scripts/overnight.ts";
+const readyLabel = "Yaawn: Ready To Implement";
+const issueListLimit = "1000";
+const numberPattern = /^\d+$/;
+const exitCodeTerminated = 143;
+const pgrepNoMatch = 1;
+const maxResultBytes = 1024 * 1024;
+const failureTailLines = 20;
+const execFileAsync = promisify(execFile);
+
+// --- arguments
+
+function positiveInteger(token: string | undefined, label: string): number {
+  const value = Number(token);
+  if (
+    !numberPattern.test(token ?? "") ||
+    !Number.isSafeInteger(value) ||
+    value < 1
+  ) {
+    throw new Error(
+      `${label} must be a positive integer, got ${JSON.stringify(token ?? "")}`,
+    );
+  }
+  return value;
+}
+
+export function parseLaunchRequest(args: string[]): LaunchRequest {
+  const issues = new Set<number>();
+  let ready = false;
+  let maxParallel: number | null = null;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--ready") ready = true;
+    else if (arg === "--max-parallel" && maxParallel === null) {
+      index += 1;
+      maxParallel = positiveInteger(args[index], "--max-parallel");
+    } else if (arg.startsWith("-"))
+      throw new Error(`unexpected flag ${JSON.stringify(arg)}`);
+    else issues.add(positiveInteger(arg, "issue"));
+  }
+  if (ready && issues.size > 0)
+    throw new Error("--ready takes no issue numbers");
+  if (!ready && issues.size === 0) throw new Error("no issue given");
+  return { issues: [...issues], ready, maxParallel };
+}
+
+// --- lanes
+
+function toIssueNumber(text: string): number | null {
+  const value = Number(text.trim());
+  return numberPattern.test(text.trim()) &&
+    Number.isSafeInteger(value) &&
+    value > 0
+    ? value
+    : null;
+}
+
+const readyIssuesArgs = [
+  "issue",
+  "list",
+  "--label",
+  readyLabel,
+  "--state",
+  "open",
+  "--json",
+  "number",
+  "--limit",
+  issueListLimit,
+  "--jq",
+  ".[].number",
+];
+
+function laneIssueNumbersFrom(output: string): number[] {
+  const issues = output
+    .split("\n")
+    .map(toIssueNumber)
+    .filter((issue): issue is number => issue !== null);
+  return [...new Set(issues)].sort((a, b) => a - b);
+}
+
+export function readyLaneIssues(): number[] {
+  return laneIssueNumbersFrom(gh(readyIssuesArgs));
+}
+
+async function readyLaneIssuesAsync(): Promise<number[]> {
+  return laneIssueNumbersFrom(await ghAsync(readyIssuesArgs));
+}
+
+function resolvedLane(issue: number): Lane {
+  return { issue, targets: executionOrder(resolveTargets(issue)) };
+}
+
+function titledLane(lane: Lane): TitledLane {
+  return { ...lane, title: lane.targets[0].title };
+}
+
+async function lookedUpLane(issue: number): Promise<Lookup<TitledLane[]>> {
+  return lookup(
+    resolveTargetsAsync(issue).then((targets) => [
+      titledLane({ issue, targets: executionOrder(targets) }),
+    ]),
+    [],
+    `lane #${issue}: could not resolve`,
+  );
+}
+
+// Every lane is fetched in parallel and every lookup runs to completion, so
+// all failures show at once; the lanes keep the order of their issues.
+async function resolveLanes(
+  request: LaunchRequest,
+): Promise<Lookup<TitledLane[]>> {
+  const laneIssues = request.ready
+    ? await lookup(
+        readyLaneIssuesAsync(),
+        [],
+        `could not list "${readyLabel}" issues`,
+      )
+    : { value: request.issues, failures: [] };
+  const lanes = await Promise.all(laneIssues.value.map(lookedUpLane));
+  return {
+    value: lanes.flatMap(({ value }) => value),
+    failures: [
+      ...laneIssues.failures,
+      ...lanes.flatMap(({ failures }) => failures),
+    ],
+  };
+}
+
+// --- worktrees
+
+function branchExists(branch: string): boolean {
+  return succeeds("git", [
+    "show-ref",
+    "--verify",
+    "--quiet",
+    `refs/heads/${branch}`,
+  ]);
+}
+
+// Reused on relaunch: an existing worktree keeps the work of an earlier run.
+function ensureWorktree(worktree: string, issue: number): void {
+  if (registeredWorktrees().has(worktree) && existsSync(worktree)) return;
+  const branch = branchName(issue);
+  const args = branchExists(branch)
+    ? ["worktree", "add", worktree, branch]
+    : ["worktree", "add", "-b", branch, worktree, "HEAD"];
+  git(args);
+}
+
+// --- pre-flight
+
+// Turns a failed lookup into a FAIL line, so parallel lookups never reject.
+async function lookup<T>(
+  work: Promise<T>,
+  fallback: T,
+  failure: string,
+): Promise<Lookup<T>> {
+  try {
+    return { value: await work, failures: [] };
+  } catch (error) {
+    return {
+      value: fallback,
+      failures: [`${failure}: ${firstLine(errorMessage(error))}`],
+    };
+  }
+}
+
+async function output(command: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync(command, args, { encoding: "utf-8" });
+  return stdout;
+}
+
+async function toolFailure(
+  failure: string,
+  command: string,
+  args: string[],
+): Promise<string | null> {
+  return (await succeedsAsync(command, args)) ? null : failure;
+}
+
+// Async counterpart of agent.ts's agentToolCheck; choice.agent comes from its allow-list.
+async function agentToolFailure(choice: AgentChoice): Promise<string | null> {
+  if (!choice.ok) return choice.failure;
+  return toolFailure(`${choice.agent} not installed`, "which", [choice.agent]);
+}
+
+async function toolFailures(choice: AgentChoice): Promise<string[]> {
+  const failures = await Promise.all([
+    toolFailure("gh not authenticated", "gh", ["auth", "status"]),
+    agentToolFailure(choice),
+    toolFailure("caffeinate not installed", "which", ["caffeinate"]),
+    toolFailure("git worktree not available", "git", ["worktree", "list"]),
+  ]);
+  return failures.filter((failure): failure is string => failure !== null);
+}
+
+async function parentPid(pid: number): Promise<number> {
+  try {
+    const parent = Number(
+      (await output("ps", ["-o", "ppid=", "-p", String(pid)])).trim(),
+    );
+    return Number.isSafeInteger(parent) ? parent : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// npx and tsx start this orchestrator through parent processes whose command
+// lines match the run pattern too; none of them is another run.
+async function ownProcessChain(): Promise<Set<number>> {
+  const chain = new Set<number>();
+  for (
+    let pid = process.pid;
+    pid > 1 && !chain.has(pid);
+    pid = await parentPid(pid)
+  ) {
+    chain.add(pid);
+  }
+  return chain;
+}
+
+async function matchingPids(pattern: string): Promise<number[]> {
+  try {
+    return (await output("pgrep", ["-f", pattern]))
+      .split("\n")
+      .filter(Boolean)
+      .map(Number);
+  } catch (error) {
+    if ((error as { code?: unknown }).code === pgrepNoMatch) return [];
+    throw error;
+  }
+}
+
+const runCommandMarker = "yaawn-implement-plan/scripts/overnight.ts run";
+
+async function commandLine(pid: number): Promise<string> {
+  try {
+    return (await output("ps", ["-o", "args=", "-p", String(pid)])).trim();
+  } catch {
+    return "";
+  }
+}
+
+function runArguments(args: string): string[] {
+  const markerIndex = args.indexOf(runCommandMarker);
+  if (markerIndex === -1) return [];
+  return args
+    .slice(markerIndex + runCommandMarker.length)
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+// The values after --max-parallel and --agent are not issues.
+function runIssueArguments(tokens: string[]): number[] {
+  return tokens
+    .filter(
+      (token, index) =>
+        !["--max-parallel", "--agent"].includes(tokens[index - 1]),
+    )
+    .map(toIssueNumber)
+    .filter((value): value is number => value !== null);
+}
+
+// Read before the lanes are known, so it can run alongside the other checks.
+async function otherActiveRuns(): Promise<ActiveRun[]> {
+  const [ownChain, pids] = await Promise.all([
+    ownProcessChain(),
+    matchingPids(runCommandMarker),
+  ]);
+  return Promise.all(
+    pids
+      .filter((pid) => !ownChain.has(pid))
+      .map(async (pid) => ({
+        pid,
+        tokens: runArguments(await commandLine(pid)),
+      })),
+  );
+}
+
+// A --ready run's lanes are not on its command line, so it conflicts with every lane.
+function otherRunFailures(
+  { pid, tokens }: ActiveRun,
+  laneIssues: number[],
+): string[] {
+  if (tokens.includes("--ready"))
+    return [`overnight --ready run already active (pid ${pid})`];
+  const activeIssues = runIssueArguments(tokens);
+  return laneIssues
+    .filter((issue) => activeIssues.includes(issue))
+    .map((issue) => `overnight run already active for #${issue}`);
+}
+
+function activeRunFailures(lanes: Lane[], activeRuns: ActiveRun[]): string[] {
+  const laneIssues = [...new Set(lanes.flatMap(laneIssueNumbers))];
+  const failures = activeRuns.flatMap((run) =>
+    otherRunFailures(run, laneIssues),
+  );
+  return [...new Set(failures)];
+}
+
+function filesFailures(issue: Issue): string[] {
+  const { files, invalid } = filesToChange(issue);
+  const failures: string[] = [];
+  if (files.length === 0) {
+    failures.push(
+      `#${issue.number} lists no files under ### ${filesToChangeHeading} (run yaawn-create-plan)`,
+    );
+  }
+  if (invalid.length > 0) {
+    failures.push(
+      `#${issue.number} ### ${filesToChangeHeading} entries that are not repo-relative paths: ${invalid.join(", ")}`,
+    );
+  }
+  return failures;
+}
+
+// Worktrees live inside the project only in the bare-repo layout, so a repo
+// that has not adopted it fails before any worktree is created.
+async function bareLayoutFailures(): Promise<string[]> {
+  const layout = await lookup(
+    output("git", ["worktree", "list", "--porcelain"]).then(isBareLayout),
+    false,
+    "could not read the git worktree layout",
+  );
+  if (layout.failures.length > 0) return layout.failures;
+  return layout.value
+    ? []
+    : [
+        "this repository does not use the bare-repo layout (project root = bare .git, main copy in <project>/main) — set it up as described in .agents/yaawn-worktrees.md, or stay on the previous @yaawn/workflow version",
+      ];
+}
+
+// Reporting only: pre-flight fetches to count commits but never merges.
+function mainCopyFailures(check: MainCopyCheck, changes: string): string[] {
+  if (!check.ok) return [check.reason];
+  const { state } = check;
+  if (state.kind === "diverged") return [describeMainCopyState(state)];
+  return state.kind === "behind" && changes.trim()
+    ? [blockedUpdateReason(state.behind)]
+    : [];
+}
+
+function printMainCopyState(check: MainCopyCheck): void {
+  if (check.ok && check.state.kind !== "diverged") {
+    console.log(describeMainCopyState(check.state));
+  }
+}
+
+function worktreeFailures(lane: TitledLane): string[] {
+  const worktree = laneWorktreePath(lane.issue, lane.title);
+  return existsSync(worktree) && !registeredWorktrees().has(worktree)
+    ? [
+        `lane #${lane.issue}: ${worktree} exists but is not a git worktree of this repository`,
+      ]
+    : [];
+}
+
+async function targetFailures(target: Issue): Promise<string[]> {
+  return [...(await issueFailuresAsync(target)), ...filesFailures(target)];
+}
+
+async function laneFailures(lane: TitledLane): Promise<string[]> {
+  const targets = await Promise.all(lane.targets.map(targetFailures));
+  return [...targets.flat(), ...worktreeFailures(lane)];
+}
+
+function fileConflicts(lanes: Lane[]): string[] {
+  const files = new Map(lanes.map((lane) => [lane.issue, laneFiles(lane)]));
+  return lanePairs(lanes).flatMap(([first, second]) => {
+    const shared = [...(files.get(first.issue) ?? [])].filter((file) =>
+      files.get(second.issue)?.has(file),
+    );
+    return shared.length === 0
+      ? []
+      : [
+          `lanes #${first.issue} and #${second.issue} both change: ${shared.join(", ")}`,
+        ];
+  });
+}
+
+function sharedTargetConflicts(owners: Map<number, number[]>): string[] {
+  return [...owners]
+    .filter(([, laneIssues]) => laneIssues.length > 1)
+    .map(
+      ([issue, laneIssues]) =>
+        `#${issue} is part of lanes ${issueRefs(laneIssues)}`,
+    );
+}
+
+function dependencyConflicts(
+  lanes: Lane[],
+  owners: Map<number, number[]>,
+): string[] {
+  return lanes.flatMap((lane) =>
+    lane.targets.flatMap((target) =>
+      target.externalDependsOn.flatMap((dependency) =>
+        (owners.get(dependency) ?? [])
+          .filter((owner) => owner !== lane.issue)
+          .map(
+            (owner) =>
+              `#${target.number} (lane #${lane.issue}) depends on #${dependency} (lane #${owner}) — lanes run independently`,
+          ),
+      ),
+    ),
+  );
+}
+
+function crossLaneConflicts(lanes: Lane[]): string[] {
+  const owners = laneOwners(lanes);
+  return [
+    ...sharedTargetConflicts(owners),
+    ...fileConflicts(lanes),
+    ...dependencyConflicts(lanes, owners),
+  ];
+}
+
+function printCompatibleSuggestion(lanes: Lane[], conflicts: string[]): void {
+  if (conflicts.length === 0) return;
+  const graph = conflictGraph(lanes);
+  const allGroups = allCompatibleGroups(
+    lanes.map((lane) => lane.issue),
+    graph,
+  );
+  // Groups of 2+ are the useful "run together" suggestions; singletons are
+  // just issues that can run alone (always possible, not informative here).
+  const groups = allGroups.filter((group) => group.length >= 2);
+  console.log("");
+  if (groups.length === 0) {
+    console.log(
+      "No two issues can be implemented together (all conflict pairwise).",
+    );
+    console.log("Run them one at a time:");
+    lanes.forEach((lane) =>
+      console.log(`  /yaawn-implement-plan ${lane.issue}`),
+    );
+  } else {
+    console.log(
+      "These groups can be implemented together (no shared files within a group):",
+    );
+    groups.forEach((group) =>
+      console.log(`  /yaawn-implement-plan ${group.join(", ")}`),
+    );
+  }
+}
+
+// --- implementation groups
+
+interface OpenIssue {
+  number: number;
+  labels: { name: string }[];
+}
+
+const isSingleIssueRun = (request: LaunchRequest): boolean =>
+  !request.ready && request.issues.length === 1;
+
+const isIssueNumber = (value: unknown): value is number =>
+  Number.isSafeInteger(value) && (value as number) > 0;
+
+function openIssues(): OpenIssue[] {
+  const raw = JSON.parse(
+    gh([
+      "issue",
+      "list",
+      "--state",
+      "open",
+      "--json",
+      "number,labels",
+      "--limit",
+      issueListLimit,
+    ]),
+  ) as unknown;
+  return Array.isArray(raw) ? (raw as OpenIssue[]) : [];
+}
+
+function hasGroupLabel({ number, labels }: OpenIssue): boolean {
+  const names = Array.isArray(labels) ? labels.map(({ name }) => name) : [];
+  return groupLabelRemovals(number, names).length > 0;
+}
+
+// Closed issues keep their labels: they record the group they ran in.
+function wipeGroupLabels(): void {
+  openIssues()
+    .filter(({ number }) => isIssueNumber(number))
+    .filter(hasGroupLabel)
+    .forEach(({ number }) => removeGroupLabels(number));
+}
+
+// Groups span every ready lane issue, not only the lanes of this run.
+function readyLanes(request: LaunchRequest, runLanes: Lane[]): Lane[] {
+  if (request.ready) return runLanes;
+  const known = new Map(runLanes.map((lane) => [lane.issue, lane]));
+  return readyLaneIssues().map(
+    (issue) => known.get(issue) ?? resolvedLane(issue),
+  );
+}
+
+// A failed action only warns.
+function applyLabelActions(actions: LabelAction[]): void {
+  actions.forEach(({ issue, label, kind }) => {
+    try {
+      if (kind === "add") addLabel(issue, label);
+      else removeLabel(issue, label);
+      console.log(
+        `${kind === "add" ? "added" : "removed"} label "${label}" on #${issue}`,
+      );
+    } catch (error) {
+      console.log(
+        `WARN could not ${kind} label "${label}" on #${issue}: ${errorMessage(error)}`,
+      );
+    }
+  });
+}
+
+function ensuredGroupLabels(groups: ImplementationGroup[]): Set<string> {
+  return new Set(
+    groups
+      .map(({ number }) => groupLabel(number))
+      .filter((label) => {
+        try {
+          ensureGroupLabel(label);
+          return true;
+        } catch (error) {
+          console.log(
+            `WARN could not create label "${label}": ${errorMessage(error)}`,
+          );
+          return false;
+        }
+      }),
+  );
+}
+
+// Every group label was just wiped, so the lanes start without any.
+function labelGroups(lanes: Lane[]): ImplementationGroup[] {
+  const assignment = assignGroups(lanes);
+  const groups = groupsOf(assignment);
+  const ensured = ensuredGroupLabels(groups);
+  applyLabelActions(
+    labelActions(assignment, new Map()).filter(({ label }) =>
+      ensured.has(label),
+    ),
+  );
+  return groups;
+}
+
+// At every --ready or multi-issue run start, all group labels are wiped and
+// recalculated from scratch; single-issue runs leave them untouched. Labeling
+// never blocks a launch: on any failure it warns and returns null, as it does
+// for runs without ready lane issues.
+function implementationGroups(
+  request: LaunchRequest,
+  lanes: Lane[],
+): ImplementationGroup[] | null {
+  if (isSingleIssueRun(request)) return null;
+  try {
+    wipeGroupLabels();
+    const ready = readyLanes(request, lanes);
+    return ready.length === 0 ? null : labelGroups(ready);
+  } catch (error) {
+    console.log(
+      `WARN implementation groups not labeled: ${errorMessage(error)}`,
+    );
+    return null;
+  }
+}
+
+function printImplementationGroups(groups: ImplementationGroup[]): void {
+  console.log("");
+  console.log(
+    "Implementation groups (the issues of a group can be implemented together):",
+  );
+  groups.forEach(({ number, issues }) =>
+    console.log(`  ${number}. /yaawn-implement-plan ${issues.join(" ")}`),
+  );
+}
+
+function describeLane(lane: TitledLane): string[] {
+  const header = `  #${lane.issue} — worktree ${laneWorktreePath(lane.issue, lane.title)}, branch ${branchName(lane.issue)}`;
+  const targets = lane.targets.map((target, index) => {
+    const after =
+      target.dependsOn.length > 0
+        ? ` — after ${issueRefs(target.dependsOn)}`
+        : "";
+    return `    ${index + 1}. #${target.number} ${target.title}${after}`;
+  });
+  return [header, ...targets];
+}
+
+function printLanes(lanes: TitledLane[], maxParallel: number | null): void {
+  const limit =
+    maxParallel === null ? "all at once" : `at most ${maxParallel} at once`;
+  console.log(`mode: parallel lanes (${limit}, one worktree each)`);
+  console.log("lanes (targets of a lane run one at a time):");
+  lanes.flatMap(describeLane).forEach((line) => console.log(line));
+}
+
+function printFailures(failures: string[]): void {
+  failures.forEach((failure) => console.log(`FAIL ${failure}`));
+}
+
+function printUncommittedChanges(changes: string): void {
+  console.log(
+    `--- uncommitted changes in the main copy (without ${plansDir}/) — they stay in the main copy and never enter the worktrees; they block the update when the main copy is behind`,
+  );
+  console.log(changes);
+}
+
+// Prints the pre-flight and returns the lanes only when every check passes.
+// Independent checks run in parallel; results print in a fixed order.
+async function checkedLanes(
+  request: LaunchRequest,
+  choice: AgentChoice,
+): Promise<CheckedLaunch | null> {
+  const [tools, layout, mainCopy, activeRuns, changes] = await Promise.all([
+    toolFailures(choice),
+    bareLayoutFailures(),
+    fetchMainCopy(),
+    lookup(otherActiveRuns(), [], "could not check for active overnight runs"),
+    lookup(uncommittedChangesAsync(), "", "could not list uncommitted changes"),
+  ]);
+  if (tools.length > 0) {
+    printFailures(tools);
+    return null;
+  }
+  if (layout.length > 0) {
+    printFailures(layout);
+    return null;
+  }
+  const resolved = await resolveLanes(request);
+  if (resolved.failures.length > 0) {
+    printFailures(resolved.failures);
+    return null;
+  }
+  const lanes = resolved.value;
+  if (lanes.length === 0) {
+    printFailures([
+      `nothing to implement: no open issue is labelled "${readyLabel}"`,
+    ]);
+    return null;
+  }
+  const conflicts = crossLaneConflicts(lanes);
+  const failures = [
+    ...activeRuns.failures,
+    ...activeRunFailures(lanes, activeRuns.value),
+    ...(await Promise.all(lanes.map(laneFailures))).flat(),
+    ...changes.failures,
+    ...mainCopyFailures(mainCopy, changes.value),
+    ...conflicts,
+  ];
+  printLanes(lanes, request.maxParallel);
+  printFailures(failures);
+  printMainCopyState(mainCopy);
+  printUncommittedChanges(changes.value);
+  const groups = implementationGroups(request, lanes);
+  if (groups) printImplementationGroups(groups);
+  if (failures.length > 0) {
+    if (!groups) printCompatibleSuggestion(lanes, conflicts);
+    return null;
+  }
+  return { lanes, changes: changes.value };
+}
+
+// Without a terminal nobody can answer: fail closed so preflight never
+// passes without a confirmation, and the caller asks the human instead.
+async function confirmedUncommittedChanges(): Promise<boolean> {
+  if (!process.stdin.isTTY) {
+    console.log(
+      "uncommitted changes in the main copy — no terminal to confirm; not continuing. Confirm with the human (or commit the changes) before launching",
+    );
+    return false;
+  }
+  const prompt = createPrompt({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await prompt.question("continue anyway? [y/N] ");
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    prompt.close();
+  }
+}
+
+// The agent is read in the main copy: a lane worktree branches from HEAD and
+// may lack an uncommitted settings file, so each lane gets it as --agent.
+export async function preflightMany(
+  request: LaunchRequest,
+  agentOption: string | null,
+): Promise<boolean> {
+  const checked = await checkedLanes(request, readAgent(agentOption));
+  if (checked === null) return false;
+  return checked.changes.trim() ? confirmedUncommittedChanges() : true;
+}
+
+// --- process output
+
+function keepTail(stream: Readable | null, tail: string[]): void {
+  if (!stream) return;
+  createInterface({ input: stream }).on("line", (line) => {
+    tail.push(line);
+    if (tail.length > failureTailLines) tail.shift();
+  });
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+const firstLine = (text: string): string => text.split("\n")[0];
+
+function codeBlock(lines: string[]): string {
+  const longestBacktickRun = Math.max(
+    0,
+    ...lines
+      .flatMap((line) => line.match(/`+/g) ?? [])
+      .map((run) => run.length),
+  );
+  const fence = "`".repeat(Math.max(3, longestBacktickRun + 1));
+  return [fence, ...lines, fence].join("\n");
+}
+
+function failureLines(tail: string[]): string {
+  return tail.length === 0
+    ? "no output captured"
+    : `last ${tail.length} output lines:\n${codeBlock(tail)}`;
+}
+
+// --- run
+
+function logState(run: LaneRun, label: LaneState | StageLabel): void {
+  console.log(`${new Date().toISOString()} #${run.lane.issue} ${label}`);
+}
+
+function setState(run: LaneRun, state: LaneState): void {
+  run.state = state;
+  logState(run, state);
+}
+
+// Only the exact marker of the lane's own issue moves its stage; every other
+// line of lane output is never interpreted.
+function watchStages(run: LaneRun, stream: Readable | null): void {
+  if (!stream) return;
+  createInterface({ input: stream }).on("line", (line) => {
+    const stage = parseStageMarker(line, run.lane.issue);
+    if (stage === undefined || run.state !== "started") return;
+    run.stage = stage;
+    logState(run, stage);
+    saveRunningResult(run);
+  });
+}
+
+// The pipe stays open for the lane's life: the lane stops itself when its
+// stdin ends, so it never outlives this process.
+function keepStdinOpen(child: ChildProcess, run: LaneRun): void {
+  child.stdin?.on("error", (error) => {
+    run.tail.push(`lane stdin closed: ${error.message}`);
+  });
+}
+
+function startLaneProcess(run: LaneRun): ChildProcess {
+  const child = spawn(
+    "npx",
+    [
+      "tsx",
+      overnightScript,
+      "lane",
+      String(run.lane.issue),
+      "--agent",
+      run.agent,
+    ],
+    {
+      cwd: run.worktree,
+      env: { ...process.env, NO_COLOR: "1" },
+      stdio: ["pipe", "pipe", "pipe"],
+    },
+  );
+  keepStdinOpen(child, run);
+  watchStages(run, child.stdout);
+  keepTail(child.stdout, run.tail);
+  keepTail(child.stderr, run.tail);
+  return child;
+}
+
+function runLaneProcess(
+  run: LaneRun,
+  children: Set<ChildProcess>,
+): Promise<number | null> {
+  return new Promise((resolve) => {
+    const child = startLaneProcess(run);
+    children.add(child);
+    let settled = false;
+    const settle = (code: number | null): void => {
+      if (settled) return;
+      settled = true;
+      children.delete(child);
+      resolve(code);
+    };
+    child.on("error", (error) => {
+      run.tail.push(`failed to start: ${error.message}`);
+      settle(null);
+    });
+    child.on("exit", (code) => {
+      void drainOutput(child).then(() => settle(code));
+    });
+  });
+}
+
+function terminateChild(child: ChildProcess): void {
+  try {
+    child.kill("SIGTERM");
+  } catch (error) {
+    console.error(`could not stop lane process: ${errorMessage(error)}`);
+  }
+}
+
+const isUnfinished = (run: LaneRun): boolean =>
+  run.state !== "done" && run.state !== "failed";
+
+function stopLane(run: LaneRun): void {
+  run.state = "stopped";
+  run.result = laneReport(
+    run,
+    `${stoppedResult(run.lane.issue, run.stage)}\n${failureLines(run.tail)}`,
+  );
+  writeLiveResult(run);
+}
+
+function printSummary(runs: LaneRun[]): void {
+  try {
+    console.log(`\n${combinedResult(runs)}`);
+  } catch (error) {
+    console.error(`could not print the summary: ${errorMessage(error)}`);
+  }
+}
+
+// Writes synchronously and exits without waiting for the lanes: one lane's
+// failed write never keeps the others, the summary, or the exit from happening.
+function stopLanesOnSignal(
+  runs: LaneRun[],
+  children: Set<ChildProcess>,
+): void {
+  let stopping = false;
+  const stop = (): void => {
+    if (stopping) return;
+    stopping = true;
+    children.forEach(terminateChild);
+    runs.filter(isUnfinished).forEach(stopLane);
+    printSummary(runs);
+    process.exit(exitCodeTerminated);
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+  process.on("SIGHUP", stop);
+}
+
+// O_NOFOLLOW: the lane's sessions run with all tools allowed, so the result
+// file could be a symlink to a secret — never follow it into the main copy.
+function readBoundedFile(file: string): string {
+  const descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const { size } = fstatSync(descriptor);
+    if (size > maxResultBytes)
+      throw new Error(`${file} is ${size} bytes (limit ${maxResultBytes})`);
+    return readFileSync(descriptor, "utf-8");
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function readWorktreeResult(run: LaneRun): string | null {
+  const file = path.join(run.worktree, resultPath(run.lane.issue));
+  try {
+    return readBoundedFile(file).trim();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      run.tail.push(`could not read ${file}: ${errorMessage(error)}`);
+    }
+    return null;
+  }
+}
+
+// Mirrors the single-issue run: exit code 0 only when every target is done,
+// and its result ends with "run result: all N targets done".
+function isLaneDone(code: number | null, result: string | null): boolean {
+  return (
+    code === 0 &&
+    result !== null &&
+    /^run result: all \d+ targets done$/m.test(result)
+  );
+}
+
+function recordExitCode(code: number | null, tail: string[]): void {
+  if (code === 0) return;
+  tail.push(
+    code === null
+      ? "lane run did not exit normally"
+      : `lane run exited with code ${code}`,
+  );
+}
+
+function laneReport(run: LaneRun, body: string): string {
+  return [
+    body,
+    `worktree: ${run.worktree}`,
+    `branch: ${branchName(run.lane.issue)}`,
+  ].join("\n\n");
+}
+
+function laneResult(run: LaneRun, worktreeResult: string | null): string {
+  return laneReport(
+    run,
+    worktreeResult ??
+      `#${run.lane.issue} ${run.state}\n${failureLines(run.tail)}`,
+  );
+}
+
+function writeResultFile(run: LaneRun): void {
+  writeFileSync(resultPath(run.lane.issue), `${run.result}\n`);
+}
+
+// A live result that cannot be written leaves the lane's state untouched.
+function writeLiveResult(run: LaneRun): void {
+  try {
+    writeResultFile(run);
+  } catch (error) {
+    console.error(
+      `could not write ${resultPath(run.lane.issue)}: ${errorMessage(error)}`,
+    );
+  }
+}
+
+function saveRunningResult(run: LaneRun): void {
+  run.result = laneReport(run, runningResult(run.lane.issue, run.stage));
+  writeLiveResult(run);
+}
+
+// Fails the lane when its main result file cannot be written.
+function saveLaneResult(run: LaneRun): void {
+  try {
+    writeResultFile(run);
+  } catch (error) {
+    const failure = `could not write ${resultPath(run.lane.issue)}: ${errorMessage(error)}`;
+    console.error(failure);
+    run.state = "failed";
+    run.tail.push(failure);
+    run.result = `${run.result}\n\n${failure}`;
+  }
+}
+
+function finishLane(run: LaneRun, code: number | null): void {
+  recordExitCode(code, run.tail);
+  const worktreeResult = readWorktreeResult(run);
+  run.state = isLaneDone(code, worktreeResult) ? "done" : "failed";
+  run.result = laneResult(run, worktreeResult);
+  saveLaneResult(run);
+  setState(run, run.state);
+}
+
+// A lane that cannot get its worktree fails alone; the other lanes go on.
+async function runLane(
+  run: LaneRun,
+  children: Set<ChildProcess>,
+): Promise<void> {
+  setState(run, "started");
+  saveRunningResult(run);
+  try {
+    ensureWorktree(run.worktree, run.lane.issue);
+  } catch (error) {
+    run.tail.push(
+      `could not create worktree ${run.worktree}: ${errorMessage(error)}`,
+    );
+    finishLane(run, null);
+    return;
+  }
+  finishLane(run, await runLaneProcess(run, children));
+}
+
+// A waiting lane starts as soon as a running one ends.
+async function runPool(
+  runs: LaneRun[],
+  maxParallel: number,
+  runOne: (run: LaneRun) => Promise<void>,
+): Promise<void> {
+  const waiting = [...runs];
+  const worker = async (): Promise<void> => {
+    for (let run = waiting.shift(); run !== undefined; run = waiting.shift()) {
+      await runOne(run);
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(maxParallel, runs.length) }, worker),
+  );
+}
+
+function runResultLine(runs: LaneRun[]): string {
+  return outcomeResultLine(
+    runs.map((run) => ({
+      issue: run.lane.issue,
+      state: run.state,
+      stage: run.stage,
+    })),
+  );
+}
+
+function combinedResult(runs: LaneRun[]): string {
+  return [
+    "--- summary",
+    ...runs.map((run) => run.result),
+    runResultLine(runs),
+  ].join("\n\n");
+}
+
+function newLaneRun(lane: TitledLane, agent: AgentName): LaneRun {
+  return {
+    lane,
+    agent,
+    worktree: laneWorktreePath(lane.issue, lane.title),
+    state: "started",
+    stage: laneStartedLabel,
+    tail: [],
+    result: "",
+  };
+}
+
+export async function runMany(
+  request: LaunchRequest,
+  agentOption: string | null,
+): Promise<boolean> {
+  const choice = readAgent(agentOption);
+  const checked = await checkedLanes(request, choice);
+  if (checked === null || !choice.ok) return false;
+  // Once, before any lane's worktree exists, so every lane starts from it.
+  const sync = await syncMainCopy();
+  if (!sync.ok) {
+    printFailures([sync.reason]);
+    return false;
+  }
+  if (sync.updated) console.log("main copy brought up to date");
+  const { lanes } = checked;
+  lanes.forEach((lane) => rmSync(resultPath(lane.issue), { force: true }));
+  const { agent } = choice;
+  const runs = lanes.map((lane) => newLaneRun(lane, agent));
+  await keepMacAwakeWhileRunning();
+  printWalkAwayBanner(agent);
+  const children = new Set<ChildProcess>();
+  stopLanesOnSignal(runs, children);
+  await runPool(runs, request.maxParallel ?? runs.length, (run) =>
+    runLane(run, children),
+  );
+  console.log(`\n${combinedResult(runs)}`);
+  return runs.every((run) => run.state === "done");
+}