@yaawn/workflow 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,772 @@
+import { type ChildProcess, execFileSync, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  constants,
+  createWriteStream,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { createInterface } from "node:readline";
+import type { Readable } from "node:stream";
+import {
+  type AgentArguments,
+  type AgentChoice,
+  type AgentName,
+  type SessionKind,
+  agentArguments,
+  agentCli,
+  readAgent,
+  transcriptExtension,
+} from "./agent.js";
+import { keepMacAwakeWhileRunning, printWalkAwayBanner } from "./caffeinate.js";
+import {
+  type LaunchRequest,
+  parseLaunchRequest,
+  preflightMany,
+  readyLaneIssues,
+  runMany,
+} from "./parallel.js";
+import { drainOutput, killProcessGroup } from "./processes.js";
+import { type Stage, stageMarker } from "./stages.js";
+import {
+  type Issue,
+  executionOrder,
+  fetchIssue,
+  isDone,
+  issueRefs,
+  plansDir,
+  resolveTargets,
+  resultPath,
+  unansweredQuestionTexts,
+} from "./targets.js";
+import { runsInOwnWorktree, worktreePath } from "./worktrees.js";
+
+type RunState = "pending" | "running" | "done" | "failed" | "skipped";
+
+interface RunOutcome {
+  states: Map<number, RunState>;
+  tails: Map<number, string[]>;
+}
+
+interface SessionHandle {
+  readonly agent: AgentName;
+  readonly laneIssue: number;
+  current: ChildProcess | null;
+}
+
+interface SessionSpec {
+  agent: AgentName;
+  target: Issue;
+  promptPath: string;
+  kind: SessionKind;
+  nameSuffix: string;
+  transcriptPath: string;
+}
+
+interface TreeSnapshot {
+  head: string;
+  status: string;
+  trackedDiffHash: string;
+  untrackedHash: string;
+}
+
+const sessionPromptPath =
+  ".agents/skills/yaawn-implement-plan/assets/session-prompt.md";
+const reviewPromptPath =
+  ".agents/skills/yaawn-implement-plan/assets/review-prompt.md";
+const fixPromptPath =
+  ".agents/skills/yaawn-implement-plan/assets/fix-prompt.md";
+const implementationPlanHeading = "## Implementation Plan";
+const maxSessionTitleLength = 50;
+const exitCodeTerminated = 143;
+const failureTailLines = 20;
+const maxReviewReportBytes = 256 * 1024;
+const gitOutputMaxBuffer = 512 * 1024 * 1024;
+const outsidePlansDir = ["--", ".", `:!${plansDir}`];
+const transcriptFlags =
+  constants.O_WRONLY |
+  constants.O_CREAT |
+  constants.O_TRUNC |
+  constants.O_NOFOLLOW;
+const scriptPath = ".agents/skills/yaawn-implement-plan/scripts/overnight.ts";
+const usage = [
+  `Usage: npx tsx ${scriptPath} <questions|preflight|run> <issue> [<issue>...] [--max-parallel N] [--agent copilot|claude|vibe]`,
+  `       npx tsx ${scriptPath} <questions|preflight|run> --ready [--max-parallel N] [--agent copilot|claude|vibe]`,
+].join("\n");
+
+const summaryPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-summary.md`;
+
+const llmPlanPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-llm-plan.md`;
+
+const implementTranscriptPath = (issue: number, agent: AgentName): string =>
+  `${plansDir}/yaawn-${issue}-overnight-session${transcriptExtension(agent)}`;
+
+const reviewReportPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-review.md`;
+
+const reviewTranscriptPath = (issue: number, agent: AgentName): string =>
+  `${plansDir}/yaawn-${issue}-review-session${transcriptExtension(agent)}`;
+
+const fixTranscriptPath = (issue: number, agent: AgentName): string =>
+  `${plansDir}/yaawn-${issue}-fix-session${transcriptExtension(agent)}`;
+
+function implementationPlanSection(body: string): string {
+  const lines = body.replace(/\r\n/g, "\n").split("\n");
+  const start = lines.findIndex(
+    (line) => line.trim() === implementationPlanHeading,
+  );
+  if (start === -1) return "";
+  let inFence = false;
+  const end = lines.findIndex((line, index) => {
+    if (/^ {0,3}(```|~~~)/.test(line)) inFence = !inFence;
+    return index > start && !inFence && /^## /.test(line);
+  });
+  return lines
+    .slice(start, end === -1 ? lines.length : end)
+    .join("\n")
+    .trim();
+}
+
+// Fetched fresh right before the session starts, so answers written after
+// the pre-flight are included.
+function writeLlmPlan(issue: number): void {
+  const { title, body } = fetchIssue(issue);
+  writeFileSync(
+    llmPlanPath(issue),
+    `# #${issue} — ${title}\n\n${implementationPlanSection(body)}\n`,
+  );
+}
+
+function printFailures(failures: string[]): void {
+  failures.forEach((failure) => console.log(`FAIL ${failure}`));
+}
+
+function buildPrompt(promptPath: string, issue: number): string {
+  return readFileSync(promptPath, "utf-8").replaceAll(
+    "<target>",
+    String(issue),
+  );
+}
+
+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 slugify(text: string): string {
+  return text
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function truncateAtWord(slug: string, maxLength: number): string {
+  if (slug.length <= maxLength) return slug;
+  const words = slug.slice(0, maxLength + 1).split("-");
+  return words.length > 1
+    ? words.slice(0, -1).join("-")
+    : slug.slice(0, maxLength);
+}
+
+function sessionName({ number, title }: Issue): string {
+  const shortTitle = truncateAtWord(slugify(title), maxSessionTitleLength);
+  return shortTitle ? `${number}-${shortTitle}` : String(number);
+}
+
+function implementSession(target: Issue, agent: AgentName): SessionSpec {
+  return {
+    agent,
+    target,
+    promptPath: sessionPromptPath,
+    kind: "implement",
+    nameSuffix: "",
+    transcriptPath: implementTranscriptPath(target.number, agent),
+  };
+}
+
+// Arguments are passed as an array (no shell), so prompt text and issue
+// titles can never be interpreted as shell syntax.
+function reviewSession(target: Issue, agent: AgentName): SessionSpec {
+  return {
+    agent,
+    target,
+    promptPath: reviewPromptPath,
+    kind: "review",
+    nameSuffix: "-review",
+    transcriptPath: reviewTranscriptPath(target.number, agent),
+  };
+}
+
+function fixSession(target: Issue, agent: AgentName): SessionSpec {
+  return {
+    agent,
+    target,
+    promptPath: fixPromptPath,
+    kind: "fix",
+    nameSuffix: "-fix",
+    transcriptPath: fixTranscriptPath(target.number, agent),
+  };
+}
+
+// O_NOFOLLOW: a session runs with all tools allowed and could leave a
+// symlink at the transcript path — never follow it when writing.
+function writeTranscript(
+  stream: Readable | null,
+  transcriptPath: string,
+  tail: string[],
+): void {
+  if (!stream) return;
+  let descriptor: number;
+  try {
+    descriptor = openSync(transcriptPath, transcriptFlags);
+  } catch (error) {
+    tail.push(`could not write ${transcriptPath}: ${errorMessage(error)}`);
+    return;
+  }
+  const transcript = createWriteStream(transcriptPath, { fd: descriptor });
+  transcript.on("error", (error) => {
+    tail.push(`could not write ${transcriptPath}: ${error.message}`);
+  });
+  stream.on("data", (chunk: Buffer) => {
+    if (transcript.writable) transcript.write(chunk);
+  });
+  stream.on("close", () => {
+    if (transcript.writable) transcript.end();
+  });
+}
+
+function startSession(spec: SessionSpec, tail: string[]): ChildProcess {
+  const command = agentCli(spec.agent, {
+    kind: spec.kind,
+    prompt: buildPrompt(spec.promptPath, spec.target.number),
+    name: `${sessionName(spec.target)}${spec.nameSuffix}`,
+    transcriptPath: spec.transcriptPath,
+  });
+  const session = spawn(command.binary, command.args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: true,
+  });
+  if (command.transcriptFromStdout) {
+    writeTranscript(session.stdout, spec.transcriptPath, tail);
+  }
+  keepTail(session.stdout, tail);
+  keepTail(session.stderr, tail);
+  return session;
+}
+
+function runSession(
+  spec: SessionSpec,
+  tail: string[],
+  handle: SessionHandle,
+): Promise<number | null> {
+  return new Promise((resolve) => {
+    const session = startSession(spec, tail);
+    handle.current = session;
+    let settled = false;
+    const settle = (code: number | null): void => {
+      if (settled) return;
+      settled = true;
+      handle.current = null;
+      resolve(code);
+    };
+    session.on("error", (error) => {
+      tail.push(`failed to start: ${error.message}`);
+      settle(null);
+    });
+    session.on("exit", (code) => {
+      killLeftovers(session, tail);
+      void drainOutput(session).then(() => settle(code));
+    });
+  });
+}
+
+// The session runs in its own process group; whatever it left running
+// (dev servers, watchers) would otherwise keep the lane open.
+function killLeftovers(session: ChildProcess, tail: string[]): void {
+  try {
+    killProcessGroup(session, "SIGTERM");
+  } catch (error) {
+    tail.push(`could not stop leftover processes: ${errorMessage(error)}`);
+  }
+}
+
+function stopCurrentSession(handle: SessionHandle): void {
+  if (!handle.current) return;
+  try {
+    killProcessGroup(handle.current, "SIGTERM");
+  } catch (error) {
+    console.error(`could not stop the session: ${errorMessage(error)}`);
+  }
+}
+
+const shutdownSignals: NodeJS.Signals[] = ["SIGTERM", "SIGINT", "SIGHUP"];
+
+// The parent holds the write end of stdin: when it closes, the parent is
+// gone and the lane must not keep sessions running unattended. The stop
+// path writes no result — the parent owns the run result.
+// Returns a cleanup that releases stdin so a finished lane exits promptly.
+function stopSessionOnShutdown(handle: SessionHandle): () => void {
+  let stopping = false;
+  const stop = (): void => {
+    if (stopping) return;
+    stopping = true;
+    stopCurrentSession(handle);
+    process.exit(exitCodeTerminated);
+  };
+  shutdownSignals.forEach((signal) => process.on(signal, stop));
+  process.stdin.on("end", stop);
+  process.stdin.on("close", stop);
+  process.stdin.resume();
+  return () => {
+    shutdownSignals.forEach((signal) => process.off(signal, stop));
+    process.stdin.off("end", stop);
+    process.stdin.off("close", stop);
+    process.stdin.destroy();
+  };
+}
+
+function announceStage(handle: SessionHandle, stage: Stage): void {
+  console.log(stageMarker(handle.laneIssue, stage));
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function recordExitCode(
+  code: number | null,
+  label: string,
+  tail: string[],
+): void {
+  if (code === 0) return;
+  tail.push(
+    code === null
+      ? `${label} was killed by a signal`
+      : `${label} exited with code ${code}`,
+  );
+}
+
+function git(args: string[]): string {
+  return execFileSync("git", args, {
+    encoding: "utf-8",
+    maxBuffer: gitOutputMaxBuffer,
+  });
+}
+
+function sha256(content: string | Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+// Symlinks are hashed by target path, never followed (e.g. to /dev/zero).
+function untrackedFileContent(file: string): string | Buffer {
+  return lstatSync(file).isSymbolicLink()
+    ? readlinkSync(file)
+    : readFileSync(file);
+}
+
+function untrackedFilesHash(): string {
+  const hash = createHash("sha256");
+  git(["ls-files", "--others", "--exclude-standard", "-z", ...outsidePlansDir])
+    .split("\0")
+    .filter(Boolean)
+    .forEach((file) =>
+      hash.update(file).update("\0").update(untrackedFileContent(file)),
+    );
+  return hash.digest("hex");
+}
+
+// Status alone misses further edits to an already-modified file, so the
+// tracked diff and the untracked files' contents are hashed as well.
+function treeSnapshot(): TreeSnapshot {
+  return {
+    head: git(["rev-parse", "HEAD"]).trim(),
+    status: git([
+      "status",
+      "--porcelain",
+      "--untracked-files=all",
+      ...outsidePlansDir,
+    ]),
+    trackedDiffHash: sha256(
+      git(["diff", "HEAD", "--binary", ...outsidePlansDir]),
+    ),
+    untrackedHash: untrackedFilesHash(),
+  };
+}
+
+function snapshotsMatch(before: TreeSnapshot, after: TreeSnapshot): boolean {
+  return (
+    before.head === after.head &&
+    before.status === after.status &&
+    before.trackedDiffHash === after.trackedDiffHash &&
+    before.untrackedHash === after.untrackedHash
+  );
+}
+
+function removeStaleReviewReport(issue: number): void {
+  try {
+    rmSync(reviewReportPath(issue));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+function readReviewReport(issue: number): string {
+  const path = reviewReportPath(issue);
+  const { size } = statSync(path);
+  if (size > maxReviewReportBytes) {
+    throw new Error(`${path} is ${size} bytes (limit ${maxReviewReportBytes})`);
+  }
+  return readFileSync(path, "utf-8");
+}
+
+function verdictSection(report: string): string {
+  const lines = report.replace(/\r\n/g, "\n").split("\n");
+  const start = lines.findIndex((line) => line.trim() === "## Verdict");
+  if (start === -1) throw new Error("review report has no ## Verdict section");
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((line) => /^#{1,2} /.test(line));
+  return (end === -1 ? rest : rest.slice(0, end)).join("\n");
+}
+
+function blockingCount(report: string): number {
+  const matches = [
+    ...verdictSection(report).matchAll(/^blocking:[ \t]*(\d+)[ \t]*$/gm),
+  ];
+  if (matches.length !== 1) {
+    throw new Error(
+      `review verdict needs exactly one "blocking: N" line, found ${matches.length}`,
+    );
+  }
+  const count = Number(matches[0][1]);
+  if (!Number.isSafeInteger(count))
+    throw new Error("review blocking count is not an integer");
+  return count;
+}
+
+// The review runs --yolo over untrusted code, so the orchestrator — not the
+// prompt — enforces that it leaves HEAD and the working tree untouched.
+// Every error path fails the target (returns null). As with the implement
+// session, a non-zero exit alone is not a failure: the report decides.
+async function reviewTarget(
+  target: Issue,
+  tail: string[],
+  handle: SessionHandle,
+): Promise<number | null> {
+  try {
+    removeStaleReviewReport(target.number);
+    const before = treeSnapshot();
+    const code = await runSession(
+      reviewSession(target, handle.agent),
+      tail,
+      handle,
+    );
+    recordExitCode(code, "review session", tail);
+    if (!snapshotsMatch(before, treeSnapshot())) {
+      tail.push(
+        "review failed: the review session changed HEAD or the working tree (it must be read-only)",
+      );
+      return null;
+    }
+    if (code === null) {
+      tail.push("review failed: the review session did not run to completion");
+      return null;
+    }
+    const blocking = blockingCount(readReviewReport(target.number));
+    tail.push(`review: ${blocking} blocking finding(s)`);
+    return blocking;
+  } catch (error) {
+    tail.push(`review failed: ${errorMessage(error)}`);
+    return null;
+  }
+}
+
+async function fixTarget(
+  target: Issue,
+  tail: string[],
+  handle: SessionHandle,
+): Promise<void> {
+  const code = await runSession(fixSession(target, handle.agent), tail, handle);
+  recordExitCode(code, "fix session", tail);
+}
+
+async function runTarget(
+  target: Issue,
+  tail: string[],
+  handle: SessionHandle,
+): Promise<boolean> {
+  try {
+    writeLlmPlan(target.number);
+  } catch (error) {
+    tail.push(
+      `could not write ${llmPlanPath(target.number)}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return false;
+  }
+  announceStage(handle, "implement");
+  const code = await runSession(
+    implementSession(target, handle.agent),
+    tail,
+    handle,
+  );
+  // The agent CLI can exit non-zero after a session that finished normally
+  // (a shutdown race: ~/.copilot/logs shows "Cannot invoke native session
+  // after disposal has started" after a graceful shutdown). The progress log,
+  // not the exit code, decides whether the target is done — a session that
+  // really stopped early leaves unchecked steps. Keep the exit code in the
+  // failure output for diagnosis.
+  recordExitCode(code, handle.agent, tail);
+  if (!isDone(target.number)) return false;
+  announceStage(handle, "review");
+  const blocking = await reviewTarget(target, tail, handle);
+  if (blocking === null) return false;
+  if (blocking > 0) {
+    announceStage(handle, "fix");
+    await fixTarget(target, tail, handle);
+  }
+  return isDone(target.number);
+}
+
+// One session at a time, in dependency order. A failed target skips its
+// dependents; independent targets still run. Stage markers carry the lane
+// issue, which the parent matches exactly.
+async function runInOrder(
+  ordered: Issue[],
+  handle: SessionHandle,
+): Promise<RunOutcome> {
+  const states = new Map<number, RunState>(
+    ordered.map((issue) => [
+      issue.number,
+      isDone(issue.number) ? "done" : "pending",
+    ]),
+  );
+  const tails = new Map<number, string[]>();
+
+  const setState = (issue: number, state: RunState): void => {
+    states.set(issue, state);
+    console.log(`${new Date().toISOString()} #${issue} ${state}`);
+  };
+
+  for (const target of ordered) {
+    if (states.get(target.number) === "done") continue;
+    if (target.dependsOn.some((dep) => states.get(dep) !== "done")) {
+      setState(target.number, "skipped");
+      continue;
+    }
+    setState(target.number, "running");
+    const tail: string[] = [];
+    tails.set(target.number, tail);
+    const succeeded = await runTarget(target, tail, handle);
+    setState(target.number, succeeded ? "done" : "failed");
+  }
+  return { states, tails };
+}
+
+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)}`;
+}
+
+function reviewResult(issue: number): string {
+  try {
+    return `### Review\n\n${readReviewReport(issue).trim()}`;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return "";
+    return `### Review\n\ncould not read ${reviewReportPath(issue)}: ${errorMessage(error)}`;
+  }
+}
+
+function targetResult(
+  issue: number,
+  state: RunState,
+  tail: string[] = [],
+): string {
+  const parts = [`#${issue} ${state}`];
+  if (existsSync(summaryPath(issue))) {
+    parts.push(readFileSync(summaryPath(issue), "utf-8").trim());
+  }
+  const review = reviewResult(issue);
+  if (review) parts.push(review);
+  if (state === "failed") parts.push(failureLines(tail));
+  return parts.join("\n");
+}
+
+function targetsIn(states: Map<number, RunState>, state: RunState): number[] {
+  return [...states]
+    .filter(([, targetState]) => targetState === state)
+    .map(([issue]) => issue);
+}
+
+function countWithRefs(issues: number[], label: string): string {
+  const refs = issues.length > 0 ? ` (${issueRefs(issues)})` : "";
+  return `${issues.length} ${label}${refs}`;
+}
+
+function runResultLine(states: Map<number, RunState>): string {
+  const done = targetsIn(states, "done");
+  if (done.length === states.size) {
+    return `run result: all ${states.size} targets done`;
+  }
+  const failed = countWithRefs(targetsIn(states, "failed"), "failed");
+  const skipped = countWithRefs(targetsIn(states, "skipped"), "skipped");
+  return `run result: ${done.length} done, ${failed}, ${skipped}`;
+}
+
+function finalResult({ states, tails }: RunOutcome): string {
+  const targets = [...states].map(([issue, state]) =>
+    targetResult(issue, state, tails.get(issue)),
+  );
+  return ["--- summary", ...targets, runResultLine(states)].join("\n\n");
+}
+
+function reportFinalResult(parent: number, outcome: RunOutcome): void {
+  const result = finalResult(outcome);
+  console.log(`\n${result}`);
+  writeFileSync(resultPath(parent), `${result}\n`);
+}
+
+async function run(parent: number, agent: AgentName): Promise<boolean> {
+  rmSync(resultPath(parent), { force: true });
+  const ordered = executionOrder(resolveTargets(parent));
+  await keepMacAwakeWhileRunning();
+  printWalkAwayBanner(agent);
+  const handle: SessionHandle = { agent, laneIssue: parent, current: null };
+  const releaseShutdownWatch = stopSessionOnShutdown(handle);
+  let outcome: RunOutcome;
+  try {
+    outcome = await runInOrder(ordered, handle);
+  } finally {
+    releaseShutdownWatch();
+  }
+  reportFinalResult(parent, outcome);
+  return [...outcome.states.values()].every((state) => state === "done");
+}
+
+// A bad agent choice fails closed before any session starts.
+async function runWithAgent(
+  parent: number,
+  choice: AgentChoice,
+): Promise<boolean> {
+  if (!choice.ok) {
+    printFailures([choice.failure]);
+    return false;
+  }
+  return run(parent, choice.agent);
+}
+
+// Internal: parallel.ts starts `lane <issue> --agent <name>` inside the
+// issue's worktree, so the work never lands in the main copy.
+async function runLaneCommand(
+  args: string[],
+  agentOption: string | null,
+): Promise<void> {
+  if (args.length !== 1 || !/^\d+$/.test(args[0])) throw new Error(usage);
+  const parent = Number(args[0]);
+  const { title } = fetchIssue(parent);
+  if (!runsInOwnWorktree(parent, title)) {
+    throw new Error(
+      `lane #${parent} must run in its worktree ${worktreePath(parent, title)}`,
+    );
+  }
+  mkdirSync(plansDir, { recursive: true });
+  process.exitCode = (await runWithAgent(parent, readAgent(agentOption)))
+    ? 0
+    : 1;
+}
+
+function launchRequest(args: string[]): LaunchRequest {
+  try {
+    return parseLaunchRequest(args);
+  } catch (error) {
+    throw new Error(`${errorMessage(error)}\n${usage}`);
+  }
+}
+
+async function launch(
+  command: string,
+  args: string[],
+  agentOption: string | null,
+): Promise<void> {
+  const request = launchRequest(args);
+  mkdirSync(plansDir, { recursive: true });
+
+  if (command === "preflight")
+    process.exitCode = (await preflightMany(request, agentOption)) ? 0 : 1;
+  else if (command === "run")
+    process.exitCode = (await runMany(request, agentOption)) ? 0 : 1;
+  else throw new Error(usage);
+}
+
+// Fails closed: an issue that cannot be fetched stops the listing, so no
+// question is silently skipped.
+function laneTargets(issue: number): Issue[] {
+  try {
+    return resolveTargets(issue);
+  } catch (error) {
+    throw new Error(
+      `could not fetch #${issue}: ${errorMessage(error).split("\n")[0]}`,
+    );
+  }
+}
+
+function targetQuestions(target: Issue): string[] {
+  return unansweredQuestionTexts(target.body).map(
+    (question) => `#${target.number} ${question}`,
+  );
+}
+
+// Read-only: lists every lane target's unanswered open questions, so they can
+// be asked before the slower pre-flight checks run.
+function listQuestions(args: string[]): void {
+  const request = launchRequest(args);
+  const laneIssues = request.ready ? readyLaneIssues() : request.issues;
+  const questions = laneIssues.flatMap(laneTargets).flatMap(targetQuestions);
+  if (questions.length === 0) console.log("no unanswered questions");
+  else questions.forEach((question) => console.log(question));
+}
+
+function splitAgentArguments(args: string[]): AgentArguments {
+  try {
+    return agentArguments(args);
+  } catch (error) {
+    throw new Error(`${errorMessage(error)}\n${usage}`);
+  }
+}
+
+async function main(): Promise<void> {
+  const [command, ...args] = process.argv.slice(2);
+  const { agentOption, rest } = splitAgentArguments(args);
+  if (command === "lane") await runLaneCommand(rest, agentOption);
+  else if (command === "questions") listQuestions(rest);
+  else await launch(command, rest, agentOption);
+}
+
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});