@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/engine/caserunner-sdk.ts

@@ -0,0 +1,423 @@
+// The scan's leaf runner on the SDK: SetupEngine's `CaseRunner` port
+// (src/setup/engine.ts) over the runtime port, the in-process twin of
+// `piCaseRunner` (src/setup/caserunner.ts). One case is one session on the
+// runtime, with the same pieces the child process gets: the agent file's model,
+// tools and body (appended to pi's own system prompt), bash-guard the one
+// extension, no skill and no context file, a cwd that is first-party ground and
+// never the reviewed checkout, and the allowlisted env. The outcome, the reads
+// and the kept transcript are read off the same event stream by the same
+// reader (`caseReadout`), so a case answers identically whichever host ran it.
+//
+// WHERE IT RUNS. Only in scancli's detached driver, a disposable one-scan
+// process (the scan sandbox or the host process `detachDriver` starts), whose
+// host this module builds and owns (`scanSdkCases`). The long-lived companion
+// pi never imports it: src/scancli.ts loads it on demand, and tests/
+// fences-engine.test.ts pins that no extension's import closure reaches it.
+// That keeps the SDK's process-global HTTP dispatcher and a frozen loop out of
+// the companion (the companion boundary).
+//
+// AUTH. Each case builds its own host on a fresh read-only copy of the owner's
+// login (engineCredentials): a token the companion refreshed mid-scan is
+// picked up at the next case, a token the case would not outlive is refused
+// before it starts, and nothing is ever refreshed or written here.
+import {
+  appendFileSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import {
+  bashGuardConfigFromEnv,
+  createBashGuard,
+} from "@quickchatai/pi-quickreview/extensions/bash-guard.js";
+import { CASE_STOP_GRACE_MS } from "@quickchatai/pi-quickreview/src/casebudget.js";
+import { splitModelSpec } from "../config.js";
+import {
+  AuthError,
+  AuthExpiring,
+  SCAN_AUTH_SRC_ENV,
+  SCAN_CASE_AUTH_BUDGET_MS,
+  engineCredentials,
+  scanAuthExpiring,
+  scanAuthMissing,
+} from "@quickchatai/pi-quickreview/src/engine/auth.js";
+import {
+  TRANSCRIPT_RUNS_KEPT,
+  caseReadout,
+  leafEnv,
+  parseAgentFile,
+  pruneTranscripts,
+  stderrExcerpt,
+  transcriptFile,
+  type AgentFile,
+} from "../setup/caserunner.js";
+import type { CaseOutcome, CaseRunner, CaseSpec } from "../setup/engine.js";
+import { LENS_SESSIONS_DIR } from "@quickchatai/pi-quickreview/src/engine/openable.js";
+import { PiHost } from "@quickchatai/pi-quickreview/src/engine/pisdk.js";
+import type {
+  Runtime,
+  SessionSpec,
+  TurnResult,
+} from "@quickchatai/pi-quickreview/src/engine/port.js";
+import {
+  sdkRuntime,
+  type SessionExtras,
+} from "@quickchatai/pi-quickreview/src/engine/sdkruntime.js";
+import { BUDGET_EXIT_CODE } from "@quickchatai/pi-quickreview/src/engine/budget.js";
+
+/** A leaf turn's hard wall clock. The login's own case budget
+ * (`SCAN_CASE_AUTH_BUDGET_MS`) is the usual bound and aborts first; this one
+ * only backs it where no login budget applies, and is kept past it so the
+ * budget's last-resort step (it ends the process) never races the abort. */
+export const LEAF_TURN_TIMEOUT_MS = SCAN_CASE_AUTH_BUDGET_MS + 15 * 60_000;
+
+/** What the model's bash may draw from the leaf env, beyond pi's defaults:
+ * certificates, proxies, XDG dirs and the temp dirs. Never a provider key. */
+const LEAF_BASH_ENV_ALLOW: readonly string[] = [
+  "TMP",
+  "TEMP",
+  "XDG_*",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "NODE_EXTRA_CA_CERTS",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "ALL_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "all_proxy",
+];
+
+/** The per-session pieces the runner hands whoever builds the runtime: the
+ * `extras` of `sdkRuntime` (packages/pi-plugin/src/engine/sdkruntime.ts). */
+export type LeafExtras = (spec: SessionSpec) => SessionExtras;
+
+export interface SdkCaseRunnerOptions {
+  /** The scan agent build: `<agent>.md` files. */
+  agentsDir: string;
+  /** The leaf's working directory: first-party ground, never the reviewed
+   * checkout (whose own pi config must not load). Also what a relative read is
+   * resolved against. */
+  cwd: string;
+  /** Where each case's event stream is kept; absent, none is. */
+  transcriptDir?: string;
+  /** The env the leaf's env is filtered from. Omitted: process.env. */
+  env?: NodeJS.ProcessEnv;
+  /** The model of an agent that names none. */
+  defaultModel?: string;
+  /** The runtime this case runs on, built with the case's `extras`. Called once
+   * per case: a route that must re-read its login per case builds its host
+   * here. */
+  runtime: (extras: LeafExtras) => Runtime | Promise<Runtime>;
+  /** The guard extension. Omitted: bash-guard over the leaf env. */
+  guard?: ExtensionFactory;
+  /** Wall clock for a case's turn. Omitted: `LEAF_TURN_TIMEOUT_MS`. */
+  timeoutMs?: number;
+}
+
+/** A transcript's path under `dir`, relative and absolute, with its run
+ * directory made (and the old runs pruned when it is new); null when it cannot
+ * be made. A transcript is evidence, never a reason to fail a case. */
+function openTranscript(dir: string, id: string): { rel: string; at: string } | null {
+  try {
+    const rel = transcriptFile(id);
+    const at = join(dir, rel);
+    const runDir = rel.includes("/") ? rel.slice(0, rel.indexOf("/")) : null;
+    const fresh = runDir !== null && !existsSync(join(dir, runDir));
+    mkdirSync(dirname(at), { recursive: true });
+    if (fresh) pruneTranscripts(dir, TRANSCRIPT_RUNS_KEPT, runDir);
+    writeFileSync(at, "", { mode: 0o600 });
+    return { rel, at };
+  } catch {
+    return null;
+  }
+}
+
+/** Where a case's session JSONL goes: `<run>/lens-sessions/<case>/` beside the
+ * transcript `rel` names (`<run>/<case>.jsonl`). */
+export function caseSessionDir(transcriptDir: string, rel: string): string {
+  return join(transcriptDir, dirname(rel), LENS_SESSIONS_DIR, basename(rel, ".jsonl"));
+}
+
+/**
+ * Runs a case as one SDK session, the way `piCaseRunner` runs it as one child:
+ * the agent's model (its `:thinking` suffix as the session's thinking level),
+ * its tools, its body appended to pi's system prompt, the task as the one
+ * message. The answer is the last assistant message's text; the cost is pi's
+ * own per-message accounting summed (null when it reported none); `reads` is the
+ * `read`/`grep` calls that finished without an error, resolved against `cwd`.
+ * With `transcriptDir` the session's whole event stream is kept at
+ * `transcriptFile(spec.id)` under it, the format `pi --mode json` prints, and
+ * its session JSONL beside it (`caseSessionDir`). An
+ * abort stops the session (abort, then dispose after the stop grace). Every
+ * outcome resolves — a runtime that cannot be built or a session that cannot
+ * start is a failed case, never a rejection.
+ */
+export function sdkCaseRunner(opts: SdkCaseRunnerOptions): CaseRunner {
+  return {
+    run: async (
+      spec: CaseSpec,
+      signal: AbortSignal,
+      onCost?: (spentSoFar: number) => void,
+    ): Promise<CaseOutcome> => {
+      if (!/^[a-z][a-z0-9-]*$/.test(spec.agent))
+        return {
+          ok: false,
+          reason: `not an agent name: ${JSON.stringify(spec.agent)}`,
+          cost_usd: 0,
+        };
+      let agent: AgentFile | null;
+      try {
+        agent = parseAgentFile(readFileSync(join(opts.agentsDir, `${spec.agent}.md`), "utf8"));
+      } catch {
+        return { ok: false, reason: `no agent ${spec.agent} in ${opts.agentsDir}`, cost_usd: 0 };
+      }
+      if (agent === null || agent.name !== spec.agent)
+        return { ok: false, reason: `${spec.agent}.md is not an agent file`, cost_usd: 0 };
+      const modelSpec = agent.model ?? opts.defaultModel;
+      if (!modelSpec)
+        return { ok: false, reason: `${spec.agent} names no model and none is set`, cost_usd: 0 };
+      if (signal.aborted) return { ok: false, reason: "stopped before it started", cost_usd: 0 };
+
+      let tmp: string;
+      try {
+        tmp = mkdtempSync(join(tmpdir(), "qcr-case-"));
+      } catch (err) {
+        return { ok: false, reason: `no temp directory for the case: ${String(err)}`, cost_usd: 0 };
+      }
+      let session: Awaited<ReturnType<Runtime["create"]>> | undefined;
+      try {
+        const env = leafEnv(opts.env);
+        const { model, thinking } = splitModelSpec(modelSpec);
+        const guard = opts.guard ?? createBashGuard(bashGuardConfigFromEnv(env, opts.cwd));
+        const extras: LeafExtras = () => ({
+          extensions: [guard],
+          appendSystemPrompt: [agent.systemPrompt],
+          bashEnv: { allow: LEAF_BASH_ENV_ALLOW },
+          ...(thinking !== null
+            ? { thinkingLevel: thinking as NonNullable<SessionExtras["thinkingLevel"]> }
+            : {}),
+        });
+        // The transcript: opened before the session, appended event by event,
+        // abandoned (and its name dropped from the outcome) at the first write
+        // that fails.
+        const opened =
+          opts.transcriptDir !== undefined ? openTranscript(opts.transcriptDir, spec.id) : null;
+        const sessionSpec: SessionSpec = {
+          cwd: opts.cwd,
+          env,
+          model,
+          ...(agent.tools.length > 0 ? { tools: agent.tools } : {}),
+          name: spec.id,
+          // The case's session JSONL beside its transcript, so the case
+          // opens in pi: `qcr open <run dir> --lens <case>`.
+          ...(opts.transcriptDir !== undefined && opened !== null
+            ? { sessionDir: caseSessionDir(opts.transcriptDir, opened.rel) }
+            : {}),
+          eventsFile: join(tmp, "events.jsonl"),
+          stderrFile: join(tmp, "stderr.txt"),
+          limits: { timeoutMs: opts.timeoutMs ?? LEAF_TURN_TIMEOUT_MS },
+        };
+
+        let transcript: string | undefined = opened?.rel;
+        let transcriptAt: string | null = opened?.at ?? null;
+        const keep = (event: unknown): void => {
+          if (transcriptAt === null) return;
+          try {
+            appendFileSync(transcriptAt, JSON.stringify(event) + "\n");
+          } catch {
+            transcriptAt = null;
+            transcript = undefined;
+          }
+        };
+        const readout = caseReadout(opts.cwd, onCost);
+        const finish = <T extends CaseOutcome>(o: T): T =>
+          transcript === undefined ? o : { ...o, transcript };
+
+        try {
+          const runtime = await opts.runtime(extras);
+          session = await runtime.create(sessionSpec);
+        } catch (err) {
+          const reason = err instanceof Error ? err.message : String(err);
+          // A refused login already says what to do; anything else is the host's.
+          return {
+            ok: false,
+            reason: err instanceof AuthError ? reason : `could not start the session: ${reason}`,
+            cost_usd: 0,
+          };
+        }
+        session.subscribe((event) => {
+          keep(event);
+          readout.feed(event);
+        });
+
+        let stopped = false;
+        let hardStop: ((o: CaseOutcome) => void) | undefined;
+        const gone = new Promise<CaseOutcome>((resolve) => {
+          hardStop = resolve;
+        });
+        const onAbort = (): void => {
+          stopped = true;
+          const live = session;
+          void live?.abort().catch(() => {});
+          // The stop grace, then the session is released; a turn still not
+          // settled a grace later is given up on, so the case resolves.
+          setTimeout(() => void live?.dispose().catch(() => {}), CASE_STOP_GRACE_MS).unref();
+          setTimeout(
+            () => hardStop?.({ ok: false, reason: "stopped", cost_usd: readout.spent() }),
+            2 * CASE_STOP_GRACE_MS,
+          ).unref();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted) {
+          onAbort();
+          // Cancelled while the session was being created: no turn starts.
+          return finish({ ok: false, reason: "stopped", cost_usd: 0 });
+        }
+
+        const turn = (async (): Promise<CaseOutcome> => {
+          let result: TurnResult;
+          try {
+            result = await session.prompt(`Task: ${spec.prompt}`);
+          } catch (err) {
+            return {
+              ok: false,
+              reason: `the session failed: ${err instanceof Error ? err.message : String(err)}`,
+              cost_usd: readout.spent(),
+            };
+          }
+          // What a case that ended without an answer had spent: a failure costs
+          // money too, and a caller holding a budget must count it.
+          const cost_usd = readout.spent();
+          if (stopped) return { ok: false, reason: "stopped", cost_usd };
+          if (result.timedOut)
+            return { ok: false, reason: "the case ran past its wall clock", cost_usd };
+          // The model's own reason leads: a provider error also ends the turn non-zero.
+          if (readout.failure !== null) return { ok: false, reason: readout.failure, cost_usd };
+          if (result.code !== 0) {
+            let tail = "";
+            try {
+              tail = stderrExcerpt(readFileSync(sessionSpec.stderrFile, "utf8"));
+            } catch {
+              // No stderr to quote.
+            }
+            return {
+              ok: false,
+              reason: `the session ended without a result${tail ? `: ${tail}` : ""}`,
+              cost_usd,
+            };
+          }
+          if (readout.final.trim() === "")
+            return { ok: false, reason: "the subagent gave no answer", cost_usd };
+          return { ok: true, output: readout.final, cost_usd, reads: readout.reads };
+        })();
+        try {
+          return finish(await Promise.race([turn, gone]));
+        } finally {
+          signal.removeEventListener("abort", onAbort);
+        }
+      } finally {
+        try {
+          await session?.dispose();
+        } catch {
+          // Already released.
+        }
+        rmSync(tmp, { recursive: true, force: true });
+      }
+    },
+  };
+}
+
+// ---- the scan driver's host ----------------------------------------------------
+
+export interface ScanSdkCasesOptions {
+  agentsDir: string;
+  cwd: string;
+  transcriptDir?: string;
+  /** The driver's env: names the login source (`QCR_SCAN_AUTH_SRC`, else
+   * `PI_CODING_AGENT_DIR`, else the home's pi agent dir) and feeds the leaf env. */
+  env: NodeJS.ProcessEnv;
+  /** A private, absolute directory for the host's own files (models list). Never
+   * the operator's pi home. */
+  agentDir: string;
+  /** Hears an expired or missing login, so the run can stop with the fix. */
+  onExpired: (reason: string) => void;
+  /** The host a case runs on, built from its credentials. Omitted: a PiHost that
+   * owns this process (the driver's) and installs pi's HTTP dispatcher. */
+  makeHost?: (o: {
+    agentDir: string;
+    credentials: ReturnType<typeof engineCredentials>["credentials"];
+  }) => Promise<PiHost>;
+}
+
+/** Where the borrowed login is read from: the scan container's read-only mount
+ * of the companion's agent dir, else the process's own pi agent dir. */
+export function scanAuthSource(env: NodeJS.ProcessEnv): string {
+  return (
+    env[SCAN_AUTH_SRC_ENV]?.trim() ||
+    env["PI_CODING_AGENT_DIR"]?.trim() ||
+    join(env["HOME"]?.trim() || homedir(), ".pi", "agent")
+  );
+}
+
+/**
+ * The scan driver's SDK leaf runner: `sdkCaseRunner` over a host per case, each
+ * on the login's refresh-blanked in-memory copy (engineCredentials). A login
+ * that is missing or would expire inside the case stops the run through
+ * `onExpired`, and the case is refused having spent nothing.
+ */
+export function scanSdkCases(o: ScanSdkCasesOptions): CaseRunner {
+  if (!isAbsolute(o.agentDir))
+    throw new Error(`the SDK host's agentDir must be absolute: ${o.agentDir}`);
+  return sdkCaseRunner({
+    agentsDir: o.agentsDir,
+    cwd: o.cwd,
+    ...(o.transcriptDir !== undefined ? { transcriptDir: o.transcriptDir } : {}),
+    env: o.env,
+    runtime: async (extras) => {
+      const src = scanAuthSource(o.env);
+      let auth: ReturnType<typeof engineCredentials>;
+      try {
+        auth = engineCredentials({
+          srcDir: src,
+          // In the scan container the driver's login wrapper ends a case at the case
+          // budget; on the host nothing does, so the login must cover the turn's
+          // whole wall clock.
+          needMs: o.env[SCAN_AUTH_SRC_ENV]?.trim()
+            ? SCAN_CASE_AUTH_BUDGET_MS
+            : LEAF_TURN_TIMEOUT_MS,
+          words: { missing: scanAuthMissing, expiring: scanAuthExpiring },
+        });
+      } catch (err) {
+        if (err instanceof AuthExpiring) o.onExpired(err.message);
+        throw err;
+      }
+      mkdirSync(o.agentDir, { recursive: true, mode: 0o700 });
+      // A custom provider list lives next to the login; the host reads its own copy.
+      const models = join(src, "models.json");
+      const hostModels = join(o.agentDir, "models.json");
+      if (existsSync(models)) copyFileSync(models, hostModels);
+      else rmSync(hostModels, { force: true });
+      const host = await (o.makeHost
+        ? o.makeHost({ agentDir: o.agentDir, credentials: auth.credentials })
+        : PiHost.create({
+            agentDir: o.agentDir,
+            ownsProcess: true,
+            homeDir: homedir(),
+            credentials: auth.credentials,
+          }));
+      // The case driver owns its process: a turn its abort and dispose did not
+      // end exits it (packages/pi-plugin/src/engine/budget.ts).
+      return sdkRuntime(host, { extras, backstop: () => process.exit(BUDGET_EXIT_CODE) });
+    },
+  });
+}

package/src/engine/debugpi.ts

@@ -0,0 +1,235 @@
+// The debug round: `qcr review --debug-pi` runs a review round inside pi's own
+// interactive UI, so the person can watch it live (and steer it).
+//
+// It is the engine's round with a different host for the main session. The round
+// is prepared as any round is (round.ts prepareRound: task files, system prompt,
+// order, env, session dir), then pi is started on the terminal with
+//
+//   - the extensions of a round, our lens tools included, through
+//     extensions/debug-round.ts: lens passes are SDK sessions of that pi process,
+//     which reuse pi's own HTTP dispatcher and never install a second
+//   - `/qcr-round` as its first message, a command of that extension: it launches
+//     the planned discovery wave and then sends the order, which is what the
+//     engine does at round start (rule 9, the engine launches the planned wave)
+//   - the main session persisted under the round's `session/`, and the lens
+//     passes under `lens-sessions/`, so the round opens again later (`qcr open`)
+//
+// When pi exits the round is read as any round is (round.ts settleRound). Pi in
+// interactive mode prints no event stream, so the usage and stage files are
+// rebuilt from the session JSONL it wrote; lens spend comes from the lens ledger.
+//
+// The model still has no GitHub credential and no posting tool: pi gets the round's
+// env, which carries no token, and the extension set below.
+import { spawn } from "node:child_process";
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { FINDING_CLUSTERS_ENTRY, extensionFile } from "../coreext.js";
+import { GITHUB_TOKEN_ENVS } from "@quickchatai/pi-quickreview/src/envstrip.js";
+import { piCliPath } from "../picli.js";
+import {
+  DEBUG_STATUS_FILE,
+  mainSessionOf,
+} from "@quickchatai/pi-quickreview/src/engine/openable.js";
+import {
+  checkToolUid,
+  shareWithToolGroup,
+  toolIsolation,
+  toolUidEnv,
+} from "@quickchatai/pi-quickreview/src/engine/tooluid.js";
+import {
+  prepareRound,
+  settleRound,
+  type PreparedRound,
+  type RoundResult,
+  type RoundSpec,
+} from "@quickchatai/pi-quickreview/src/engine/round.js";
+import type { PiRun } from "@quickchatai/pi-quickreview/src/engine/port.js";
+
+/** The extensions of a debug round: the round's own set with the debug
+ * extension (which carries the lens tools) in the lens tool's place. The env
+ * shims are the app's, by path under the production tree (`extensions/cli/`);
+ * `cluster_findings` is the review core's own extension, found in the core
+ * package (`extensionFile`, src/coreext.ts). Nothing here posts. */
+export const DEBUG_ROUND_EXTENSIONS = [
+  "extensions/cli/bash-guard.ts",
+  "extensions/cli/ledger-pin.ts",
+  "extensions/cli/debug-round.ts",
+  FINDING_CLUSTERS_ENTRY,
+] as const;
+
+/** pi's first message: the extension command that starts the round. */
+export const DEBUG_START_MESSAGE = "/qcr-round";
+
+/** pi's argv for a debug round. Pure. */
+export function debugArgv(o: {
+  root: string;
+  model: string;
+  sysPath: string;
+  sessionDir: string;
+  sessionName: string;
+}): string[] {
+  return [
+    // Host isolation as the round has it: pi discovers no extension or skill of its
+    // own. `-nc` is absent: the cwd's context file is the reviewer stub.
+    "--approve",
+    "-ne",
+    "-ns",
+    "--model",
+    o.model,
+    "--system-prompt",
+    o.sysPath,
+    "--session-dir",
+    o.sessionDir,
+    ...DEBUG_ROUND_EXTENSIONS.flatMap((e) => ["--extension", extensionFile(o.root, e)]),
+    "--name",
+    o.sessionName,
+    DEBUG_START_MESSAGE,
+  ];
+}
+
+/** The env a debug round's pi is started with: the person's terminal env without
+ * any GitHub token, then the round's env, then the names the debug extension reads. */
+export function debugEnv(
+  base: Readonly<Record<string, string | undefined>>,
+  prep: Pick<PreparedRound, "env">,
+  files: { order: string; tasksDir: string },
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...base };
+  for (const k of GITHUB_TOKEN_ENVS) delete env[k];
+  return {
+    ...env,
+    ...prep.env,
+    QCR_DEBUG_ORDER_FILE: files.order,
+    QCR_DEBUG_TASKS_DIR: files.tasksDir,
+  };
+}
+
+/** The event stream a `pi --mode json` run would have written, rebuilt from the
+ * session JSONL: its header, then a `message_end` per message. That is what
+ * usage, stages and the price are read from. */
+export function eventsFromSession(file: string): string[] {
+  const out: string[] = [];
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    let entry: { type?: unknown; message?: unknown };
+    try {
+      entry = JSON.parse(line) as typeof entry;
+    } catch {
+      continue;
+    }
+    if (entry.type === "session") out.push(line);
+    else if (entry.type === "message" && entry.message !== undefined)
+      out.push(JSON.stringify({ type: "message_end", message: entry.message }));
+  }
+  return out;
+}
+
+export interface DebugRoundDeps {
+  /** The pi binary. Omitted: the pinned pi's own CLI (src/picli.ts); the
+   * release image has no `pi` on the PATH. */
+  piBin?: string;
+  /** The environment pi inherits. Omitted: `process.env`. */
+  env?: Readonly<Record<string, string | undefined>>;
+  /** Runs pi on the terminal; resolves its exit code. Omitted: a child with
+   * the terminal's stdio. */
+  run?: (cmd: {
+    bin: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+  }) => Promise<number>;
+}
+
+function onTerminal(cmd: {
+  bin: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+}): Promise<number> {
+  return new Promise((resolve) => {
+    const child = spawn(cmd.bin, cmd.args, { cwd: cmd.cwd, env: cmd.env, stdio: "inherit" });
+    // The terminal's ^C reaches pi and this process alike; pi decides what it means.
+    const ignore = (): void => {};
+    process.on("SIGINT", ignore);
+    process.on("SIGTERM", ignore);
+    const done = (code: number): void => {
+      process.off("SIGINT", ignore);
+      process.off("SIGTERM", ignore);
+      resolve(code);
+    };
+    child.on("error", (e) => {
+      console.error(`could not start ${cmd.bin}: ${e.message}`);
+      done(1);
+    });
+    child.on("close", (code) => done(code ?? 1));
+  });
+}
+
+/** Run one review round inside interactive pi. Resolves when pi exits, with the
+ * round read from what it left in `outDir`. A round the person left early has no
+ * outcome (`error` says what was missing); it is not a failure of the route. */
+export async function runDebugRound(i: RoundSpec, deps: DebugRoundDeps = {}): Promise<RoundResult> {
+  const log = i.log ?? (() => {});
+  const label = i.label ?? `${i.target.repo}#${i.target.number}`;
+  // pi's own bash runs in pi's uid: where the image asks for a separate tool uid
+  // pi is started as that uid (below), and where it asked and could not arrange
+  // it, there is no round.
+  const procEnv = deps.env ?? process.env;
+  checkToolUid(procEnv, {
+    what: "a debug round in pi",
+    instead: "run the review without --debug-pi",
+    isolated: true,
+  });
+  const prep = prepareRound(i, { plannedWave: true });
+  try {
+    for (const f of [prep.events, prep.stderr]) writeFileSync(f, "");
+    // an earlier attempt's progress record is not this round's
+    rmSync(join(i.outDir, DEBUG_STATUS_FILE), { force: true });
+    log(`review: ${label} - debug round in pi, lenses ${prep.prompts.plannedLenses.join(" ")}`);
+    const args = debugArgv({
+      root: i.root,
+      model: i.cfg.models.conversation,
+      sysPath: prep.sysPath,
+      sessionDir: prep.sessionDir,
+      sessionName: prep.sessionName,
+    });
+    const env = debugEnv(deps.env ?? process.env, prep, {
+      order: join(i.outDir, "round-order.md"),
+      tasksDir: join(i.outDir, "tasks"),
+    });
+    // The whole pi runs as the tool uid, as the process route's did: its bash,
+    // and the lens sessions of its extension, get no capability and cannot read
+    // this process.
+    const launch = toolIsolation(deps.piBin ?? piCliPath(), args, procEnv);
+    if ("refused" in launch) throw new Error(`a debug round in pi: ${launch.refused}`);
+    // That pi reads the run's agent dir (its login copy, models, lens agents),
+    // which the run uid made private.
+    if (launch.isolated) shareWithToolGroup(i.agentDir);
+    const code = await (deps.run ?? onTerminal)({
+      bin: launch.bin,
+      args: launch.argv,
+      cwd: i.cwd ?? i.root,
+      // as the tool uid, git needs the run uid's repositories named safe
+      env: launch.isolated ? toolUidEnv(env) : env,
+    });
+    // Interactive pi prints no event stream: usage, stages and the price are read
+    // from the session it kept.
+    const kept = mainSessionOf(i.outDir);
+    if (kept !== null) writeFileSync(prep.events, eventsFromSession(kept).join("\n") + "\n");
+    const piRun: PiRun = { code, timedOut: false, streamError: null };
+    const result: RoundResult = {
+      prompts: prep.prompts,
+      plannedLenses: prep.prompts.plannedLenses,
+      piRun,
+      continued: false,
+      capped: false,
+      warnings: [],
+      costUsd: null,
+      review: null,
+    };
+    if (kept === null) result.error = "pi ended before the round's session wrote anything";
+    return settleRound(i, prep, result, piRun, 0);
+  } finally {
+    if (prep.ownTmp) rmSync(prep.tmpDir, { recursive: true, force: true });
+  }
+}