@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/autopilot-runner.mjs

@@ -14,17 +14,34 @@
  *   4. TAKE     the head of the queue, and only if this repo is free.
  *   5. RUN      one `claude --bg` child, then SUPERVISED to the end. `--bg`
  *               returns immediately, so the spawn proves only that a run began.
+ *   5c. RESEARCH a run parked on a maturity blocker or on open questions gets a
+ *               research pass before it is left for a person: one more session
+ *               (`/multi-agent:research <id> --autonomous`), then
+ *               research-gate.mjs decides; proceed resumes the run, anything
+ *               else leaves it parked. Bounded by config `maxAskRounds`.
  *   6. RECORD   attempted.jsonl, clear the pid file, refresh status.json.
  *
+ * Around the run, three operations (_autopilot-ops.mjs): a sleep inhibitor held
+ * from the launch to the end of the tick; `maxParallelAgents`, a ceiling on
+ * runner-launched sessions working at once; and two jobs at most once per
+ * local day - the cleanup report over the worktrees this runner created, and
+ * the opt-in digest sent through `reportChannels`.
+ *
  * LIVENESS WITHOUT A LEASE. Lease arithmetic exists to arbitrate between rival
  * writers, and here there are none: one machine, one queue, one writer. The
- * question is only "is the runner I recorded still alive", and three cheap facts
- * answer it exactly - the pid responds to signal 0, the machine has not rebooted
- * since the pid was recorded, and the session is in `claude agents --json`. The
- * middle one is what makes a reboot safe without probing anything: after a
- * restart pids start low, so a recorded 4711 may well belong to something real
- * and unrelated, and a runner that trusted `kill -0` alone would decide another
- * runner was live and do nothing, forever.
+ * question is only "is the run I recorded still alive", and three cheap facts
+ * answer it - the machine has not rebooted since the claim was recorded, the
+ * session is in `claude agents --json`, and either the recorded pid responds to
+ * signal 0 or the session reports itself working. The boot check is what makes
+ * a reboot safe without probing anything: after a restart pids start low, so a
+ * recorded 4711 may well belong to something real and unrelated, and a runner
+ * that trusted `kill -0` alone would decide another runner was live and do
+ * nothing, forever. The session is what decides the rest, because the pid is
+ * the supervisor's and the session outlives it.
+ *
+ * A run that stops to ask a person is PARKED: its claim moves into `running`,
+ * where it holds its repo but not a slot, and it is settled from its own state
+ * once its session ends. Nothing retires it.
  *
  * WHAT IT WILL NOT DO. It does not merge. It does not remove a worktree holding
  * uncommitted work - that is stashed under a named message and the worktree
@@ -42,25 +59,67 @@
 
 import { execFileSync, spawnSync } from "node:child_process";
 import {
+  accessSync,
+  constants as fsConstants,
+  copyFileSync,
   existsSync,
   readFileSync,
+  realpathSync,
   writeFileSync,
   appendFileSync,
   mkdirSync,
+  renameSync,
   rmSync,
   chmodSync,
-  readdirSync,
   statSync,
   openSync,
   readSync,
   closeSync,
   truncateSync,
 } from "node:fs";
-import { join } from "node:path";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { runMain } from "../lib/fatal.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { messages, outputLanguage } from "../lib/user-facing.mjs";
+import {
+  ARTIFACTS_SUBDIR,
+  listRuns,
+  logsRoot,
+  resolveRunFile,
+  runDirCandidates,
+} from "./_run-paths.mjs";
+import { costUsd } from "./_cost.mjs";
+import { configRefusal } from "./_autopilot-config.mjs";
+import {
+  OUTCOME,
+  classifyOutcome,
+  isBlocked,
+  isParked,
+  isTerminal,
+  rateLimited,
+} from "./_autopilot-outcomes.mjs";
+import { prRequestsDir, runRequestsDir, unattendedLogsRoot } from "../lib/pr-request-location.mjs";
+import { prefsHosts, profileGaps, projectSettingsGaps } from "../lib/unattended-profile-check.mjs";
+import { unattendedSettingsPath } from "../lib/unattended-settings-location.mjs";
+import { SUMMARY_SUFFIX, publish, reportAfterPublish, reportDigest } from "./autopilot-publish.mjs";
+import { updateState } from "./gate-ledger.mjs";
+import {
+  agentsInFlight,
+  buildDigest,
+  claimExclusive,
+  dailyDue,
+  digestText,
+  gcReport,
+  holdSleep,
+  localDate,
+  markDaily,
+  parallelCap,
+  pruneDaily,
+  sweepInhibitor,
+} from "./_autopilot-ops.mjs";
 
 const ROOT = process.env.MA_AUTOPILOT_ROOT || join(homedir(), ".claude", "autopilot");
 // Siblings resolve from THIS file's own directory, not from ~/.claude/scripts.
@@ -69,7 +128,40 @@ const ROOT = process.env.MA_AUTOPILOT_ROOT || join(homedir(), ".claude", "autopi
 // host's path means a Codex-only or Copilot-only tick finds nothing and does
 // nothing, with no error anywhere. smoke-autopilot-hosts.sh covers this.
 const SCRIPTS = process.env.MA_AP_SCRIPTS || import.meta.dirname;
-const CLAUDE_BIN = process.env.MA_AP_CLAUDE_BIN || "claude";
+
+function isExecutable(p) {
+  try {
+    accessSync(p, fsConstants.X_OK);
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The `claude` this tick launches.
+ *
+ * launchd does not read a login shell, so the bare word resolves against the
+ * plist's short PATH - and the native installer puts `claude` in ~/.local/bin,
+ * which no default PATH carries. Order: an explicit override, then the absolute
+ * path autopilot-on captured into the plist, then PATH plus ~/.local/bin.
+ *
+ * @returns {string}
+ */
+export function resolveClaudeBin(env = process.env, home = homedir()) {
+  if (env.MA_AP_CLAUDE_BIN) return env.MA_AP_CLAUDE_BIN;
+  const installed = env.MA_AP_CLAUDE_INSTALLED_BIN;
+  if (installed && isAbsolute(installed) && isExecutable(installed)) return installed;
+  const dirs = [...String(env.PATH || "").split(delimiter), join(home, ".local", "bin")];
+  for (const d of dirs) {
+    if (!d) continue;
+    const p = join(d, "claude");
+    if (isExecutable(p)) return p;
+  }
+  return "claude";
+}
+
+const CLAUDE_BIN = resolveClaudeBin();
 const DRY = process.argv.includes("--dry-run");
 const POLL_MS = Number(process.env.MA_AP_POLL_MS || 15000);
 // A run that has not finished in this long is not going to, and holding the
@@ -87,20 +179,124 @@ const LIVE_STATUSES = new Set(["busy", "running", "waiting"]);
 // months it is the thing that fills the disk, and a full disk stops the runs it
 // was logging.
 const LOG_MAX_BYTES = Number(process.env.MA_AP_LOG_MAX_BYTES || 5 * 1024 * 1024);
+// ticks.jsonl is telemetry: past this size only the newest TICKS_KEEP lines stay.
+const TICKS_MAX_BYTES = Number(process.env.MA_AP_TICKS_MAX_BYTES || 2 * 1024 * 1024);
+const TICKS_KEEP = Number(process.env.MA_AP_TICKS_KEEP || 5000);
+// attempted.jsonl is the queue's memory, so past this size it is compacted
+// rather than cut: rows younger than ATTEMPTED_KEEP_SEC stay whole, and older
+// rows stay when intake still needs them (compactAttempted).
+const ATTEMPTED_MAX_BYTES = Number(process.env.MA_AP_ATTEMPTED_MAX_BYTES || 4 * 1024 * 1024);
+const ATTEMPTED_KEEP_SEC = 30 * 86400;
+// The breaker and the rate-limit backoff read the attempts of this trailing
+// window. A row count would let the `blocked-*` row every refused tick writes
+// push the failures it is counting out of view.
+const ATTEMPT_WINDOW_SEC = Number(process.env.MA_AP_ATTEMPT_WINDOW_SEC || 7 * 86400);
 // Consecutive failed attempts before the runner stops taking NEW work. The
 // failure this guards against is a machine-level one - an expired token, a full
 // disk, a `claude` that no longer launches - where every item fails the same
 // way and the queue is consumed one worthless run at a time. Zero disables it.
 const BREAKER_LIMIT = Number(process.env.MA_AP_BREAKER_LIMIT || 3);
+// Publish refusals that describe the machine rather than the run's work: the
+// remote could not be resolved, the push or the PR was refused by the host.
+export const ENVIRONMENTAL_PUBLISH_GATES = new Set(["remote", "push", "pr-create"]);
 // How long an open breaker waits before letting ONE attempt through. Long
 // enough that a broken machine is not burning the queue (default 30 min, so at
 // a 15-minute tick it is every other tick at most), short enough that a machine
 // fixed at 3am is working again by morning without anyone touching it.
 const BREAKER_COOLDOWN_SEC = Number(process.env.MA_AP_BREAKER_COOLDOWN_SEC || 1800);
-// Outcomes that mean the attempt produced nothing. `needs-input` is NOT here:
-// a run parked on a question did work and is waiting for a person, which is the
-// system behaving correctly.
-const FAILED_OUTCOMES = new Set(["launch-failed", "timed-out", "no-state", "failed", "unknown"]);
+// A rate limit belongs to the account, not the item, so after one the runner
+// takes NO new item until the wait is over, doubling per consecutive limit up to
+// the ceiling. Five hours is the longest usage window a limit resets on.
+const RATE_LIMIT_BACKOFF_SEC = Number(process.env.MA_AP_RATE_LIMIT_BACKOFF_SEC ?? 1800);
+const RATE_LIMIT_MAX_SEC = Number(process.env.MA_AP_RATE_LIMIT_MAX_SEC || 5 * 60 * 60);
+// `--bg` returns once the session exists, so a launch that takes this long is
+// not starting.
+const LAUNCH_TIMEOUT_MS = 2 * 60 * 1000;
+// How long an unparseable runner.pid is taken for a claim still being written.
+const UNPARSEABLE_CLAIM_GRACE_MS = 60 * 1000;
+// The deterministic half of a research round. The agent gathers; this decides.
+const RESEARCH_GATE =
+  process.env.MA_AP_RESEARCH_GATE || join(import.meta.dirname, "research-gate.mjs");
+// Tools a research pass may not call. Tracker text is untrusted and often
+// confidential: the research_* tools send their query to an external service,
+// and so does a web search built from that text. The local context_* index
+// stays available.
+export const RESEARCH_DENIED_TOOLS = Object.freeze([
+  "mcp__multi-agent-toolkit__research_ask",
+  "mcp__multi-agent-toolkit__research_search",
+  "WebSearch",
+]);
+// How a session ends that lets a research pass write into the run's state: it
+// left the list, it reported it was done, or it is idle waiting for a person.
+const ENDED = new Set(["gone", "finished", "needs-input"]);
+// The toolkit settings install --unattended writes into settings.json, read
+// from the same profile so the two cannot drift. The URL policy is forced, not
+// defaulted: an unattended child is never less strict than the profile.
+const PROFILE_SCHEMA = (() => {
+  try {
+    return JSON.parse(
+      readFileSync(new URL("../schemas/unattended-profile.json", import.meta.url), "utf-8"),
+    );
+  } catch {
+    return null;
+  }
+})();
+const PROFILE_ENV = Object.fromEntries((PROFILE_SCHEMA?.env || []).map(([k, v]) => [k, v]));
+const TOOLKIT_URL_POLICY = PROFILE_ENV.MCP_TOOLKIT_URL_POLICY || "strict";
+const TOOLKIT_INDEX_DENY =
+  PROFILE_ENV.MCP_TOOLKIT_INDEX_DENY || "~/.ssh,~/.aws,~/.gnupg,~/Library/Keychains";
+// The three PreToolUse registrations install/claude.mjs writes for agent-guard.sh,
+// and the tool names each one has to cover. The web entry is checked against
+// WebFetch and the toolkit tools that reach a host: a web tool, agent_run_steps
+// (which dispatches the web tools) and both open_url tools.
+const GUARD_MATCHERS = [
+  ["Bash", ["Bash"]],
+  ["Edit|Write|NotebookEdit", ["Edit", "Write", "NotebookEdit"]],
+  [
+    "WebFetch|mcp__multi-agent-toolkit__.*",
+    [
+      "WebFetch",
+      "mcp__multi-agent-toolkit__web_goto",
+      "mcp__multi-agent-toolkit__agent_run_steps",
+      "mcp__multi-agent-toolkit__ios_open_url",
+      "mcp__multi-agent-toolkit__android_open_url",
+    ],
+  ],
+];
+// The hook command install/claude.mjs writes. Only this command, with $HOME
+// written literally or expanded, counts as the guard: a command that merely
+// mentions the script path can run anything and still look registered.
+const GUARD_COMMAND = "bash $HOME/.claude/scripts/agent-guard.sh";
+const MANAGED_SETTINGS = "/Library/Application Support/ClaudeCode/managed-settings.json";
+// A phase record without a model is priced at the most expensive tier: an
+// over-estimate stops the spend ceiling early, an under-estimate stops it late.
+const CONSERVATIVE_PRICE = "fable";
+// What the queue says when the arming script answers nothing at all. Read by a
+// person in the menu bar and in the terminal, so it renders in the same
+// preference every other line does.
+const ARM_UNREADABLE = {
+  en: "the arming check returned no verdict - no new item is taken until it does",
+  tr: "hazırlık denetimi bir karar döndürmedi - dönene kadar yeni madde alınmaz",
+};
+
+const RATE_LIMITED_MSG = {
+  en: (min) => `rate limited - no new item is taken for ${min} min`,
+  tr: (min) => `hız sınırına takıldı - ${min} dk boyunca yeni madde alınmaz`,
+};
+
+/**
+ * The phase contract, for the running entry's "phase N/M Name". Beside the
+ * scripts in every install, as runs-index.mjs reads it; a host tree without it
+ * shows the number alone rather than failing the tick.
+ */
+const PHASES = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf-8"))
+      .phases;
+  } catch {
+    return [];
+  }
+})();
 
 const log = (m) => process.stdout.write(`autopilot-runner: ${m}\n`);
 
@@ -116,24 +312,31 @@ function run(cmd, args, opts = {}) {
   }
 }
 
+/**
+ * Every JSON file the runner reads goes through here. Run state and trackers
+ * are written by the run, so anything but a bounded regular file - a FIFO would
+ * block this thread, and with it every run it supervises - reads as absent.
+ */
 function readJson(p, fallback) {
-  if (!existsSync(p)) return fallback;
-  try {
-    return JSON.parse(readFileSync(p, "utf-8"));
-  } catch {
-    return fallback;
-  }
+  return readRegularJson(p, fallback);
 }
 
 function ensureRoot() {
   mkdirSync(ROOT, { recursive: true, mode: 0o700 });
 }
 
+/**
+ * Replace one of the runner's files whole: a temp file beside it, then a
+ * rename, so a reader sees the old document or the new one and never half of
+ * either, and a link in its place is replaced rather than written through.
+ */
 function writeState(name, obj) {
   ensureRoot();
   const p = join(ROOT, name);
-  writeFileSync(p, JSON.stringify(obj, null, 2), { mode: 0o600 });
-  chmodSync(p, 0o600);
+  const tmp = `${p}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2), { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, p);
 }
 
 function record(entry) {
@@ -213,13 +416,40 @@ function tick(entry) {
 export function consecutiveFailures(lines) {
   let count = 0;
   let last = null;
+  // One run can write two rows - `timed-out` when supervision gave up, then
+  // the outcome a later tick retired it with. It is one attempt, counted once.
+  const counted = new Set();
   for (let i = lines.length - 1; i >= 0; i--) {
     const row = lines[i];
     if (!row || typeof row.outcome !== "string") continue;
     // A blocked item never ran: arming refused it, which says nothing about
-    // whether a run would have worked.
-    if (row.outcome.startsWith("blocked-")) continue;
-    if (FAILED_OUTCOMES.has(row.outcome)) {
+    // whether a run would have worked. A rate limit has its own backoff, and
+    // counting it here too would stop the machine twice for one cause. `died`
+    // is a run this runner lost track of - a reboot, a lid closed - which says
+    // nothing about the machine either way, so it neither counts nor passes
+    // for the success that would end the chain.
+    if (
+      isBlocked(row.outcome) ||
+      row.outcome === OUTCOME.RATE_LIMITED ||
+      row.outcome === OUTCOME.DIED
+    ) {
+      continue;
+    }
+    // Every other RETRYABLE outcome is an attempt that produced nothing, and
+    // so is a publish the machine refused: no remote, a push or a PR the host
+    // would not take. Those park the item, but what they say is that the
+    // runner's own credential or network is broken, which every next item
+    // would meet at the same step. Other PARKED and TERMINAL outcomes did
+    // work, and end the chain.
+    if (
+      classifyOutcome(row.outcome) === "retryable" ||
+      (row.outcome === OUTCOME.VERIFICATION_FAILED &&
+        ENVIRONMENTAL_PUBLISH_GATES.has(row.publishGate))
+    ) {
+      if (typeof row.taskId === "string" && row.taskId) {
+        if (counted.has(row.taskId)) continue;
+        counted.add(row.taskId);
+      }
       count++;
       if (!last) last = row.outcome;
       continue;
@@ -229,24 +459,121 @@ export function consecutiveFailures(lines) {
   return { count, last };
 }
 
-function readAttempted() {
-  const p = join(ROOT, "attempted.jsonl");
-  if (!existsSync(p)) return [];
+/**
+ * When the newest real attempt was recorded. A `blocked-*` row is written on
+ * every tick that arming refuses, so letting it move this clock would keep a
+ * breaker's cooldown from ever running out.
+ */
+export function lastAttemptAt(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const row = lines[i];
+    if (!row || typeof row.outcome !== "string" || isBlocked(row.outcome)) continue;
+    return Number(row.at || 0);
+  }
+  return 0;
+}
+
+/**
+ * How long a rate limit still holds the queue, or null when it does not.
+ *
+ * @returns {{count:number, remainingSec:number}|null}
+ */
+export function rateLimitBackoff(
+  lines,
+  { baseSec = RATE_LIMIT_BACKOFF_SEC, maxSec = RATE_LIMIT_MAX_SEC, now = Date.now() / 1000 } = {},
+) {
+  let count = 0;
+  let lastAt = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const row = lines[i];
+    if (!row || typeof row.outcome !== "string" || isBlocked(row.outcome)) continue;
+    if (row.outcome !== OUTCOME.RATE_LIMITED) break;
+    count++;
+    if (!lastAt) lastAt = Number(row.at || 0);
+  }
+  if (!count || !(baseSec > 0)) return null;
+  const wait = Math.min(maxSec, baseSec * 2 ** (count - 1));
+  const remainingSec = Math.ceil(lastAt + wait - now);
+  return remainingSec > 0 ? { count, remainingSec } : null;
+}
+
+/** The attempts of the trailing window the breaker and the backoff judge. */
+function readAttempted(now = Date.now() / 1000) {
+  const since = now - ATTEMPT_WINDOW_SEC;
+  return readAllAttempted().filter((r) => Number(r.at || 0) >= since);
+}
+
+/**
+ * The rows of attempted.jsonl worth keeping once it outgrows its cap.
+ *
+ * Rows younger than `keepSec` are kept whole. An older row is kept when intake
+ * or the cleanup report still reads it: the newest row of its item (what the
+ * item last did), and, for an item that is not finished, every row that is not
+ * a `blocked-*` refusal (its attempt count, research rounds and the task ids
+ * that tie a parked run to its worktree). What goes is the refusal a blocked
+ * tick writes every time, and the superseded rows of finished items.
+ *
+ * @returns {object[]} the kept rows, in their original order
+ */
+export function compactAttempted(
+  rows,
+  { now = Date.now() / 1000, keepSec = ATTEMPTED_KEEP_SEC } = {},
+) {
+  const since = now - keepSec;
+  const newest = new Map();
+  rows.forEach((r, i) => {
+    const key = `${r.source}:${r.id}`;
+    const cur = newest.get(key);
+    if (!cur || Number(r.at || 0) >= Number(rows[cur].at || 0)) newest.set(key, i);
+  });
+  return rows.filter((r, i) => {
+    if (Number(r.at || 0) >= since) return true;
+    const key = `${r.source}:${r.id}`;
+    const last = newest.get(key);
+    if (last === i) return true;
+    if (isTerminal(rows[last].outcome)) return false;
+    return !isBlocked(r.outcome);
+  });
+}
+
+function replaceWhole(p, text) {
+  const tmp = `${p}.${process.pid}.tmp`;
+  writeFileSync(tmp, text, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, p);
+}
+
+/**
+ * Keep ticks.jsonl and attempted.jsonl bounded. Both are opened per append and
+ * never held, so replacing them by rename loses no writer.
+ */
+function rotateJsonl() {
   try {
-    return readFileSync(p, "utf-8")
-      .split("\n")
-      .filter(Boolean)
-      .slice(-50)
-      .map((l) => {
-        try {
-          return JSON.parse(l);
-        } catch {
-          return null;
-        }
-      })
-      .filter(Boolean);
+    const ticks = join(ROOT, "ticks.jsonl");
+    if (existsSync(ticks) && statSync(ticks).size > TICKS_MAX_BYTES) {
+      const lines = readFileSync(ticks, "utf-8").split("\n").filter(Boolean);
+      replaceWhole(ticks, lines.slice(-TICKS_KEEP).join("\n") + "\n");
+    }
   } catch {
-    return [];
+    // Telemetry never fails a tick.
+  }
+  try {
+    const attempted = join(ROOT, "attempted.jsonl");
+    if (existsSync(attempted) && statSync(attempted).size > ATTEMPTED_MAX_BYTES) {
+      const rows = readAllAttempted();
+      const kept = compactAttempted(rows);
+      copyFileSync(attempted, `${attempted}.1`);
+      chmodSync(`${attempted}.1`, 0o600);
+      replaceWhole(
+        attempted,
+        kept.map((r) => JSON.stringify(r)).join("\n") + (kept.length ? "\n" : ""),
+      );
+      log(
+        `attempted.jsonl compacted: ${rows.length} rows -> ${kept.length}, full log in attempted.jsonl.1`,
+      );
+    }
+  } catch (e) {
+    log(`attempted.jsonl could not be compacted: ${e?.message || e}`);
   }
 }
 
@@ -295,20 +622,32 @@ export function agentRow(sessionId, agentsJson) {
   }
 }
 
+/** A listed session that is still working or waiting. A row with no status is not "ended". */
+function sessionIsLive(row) {
+  return Boolean(row) && (!row.status || LIVE_STATUSES.has(row.status));
+}
+
 /**
- * Is the recorded runner still running?
+ * Is the recorded run still running?
+ *
+ * The SESSION decides, not the runner's pid. The pid is this runner's own, and
+ * it exits whenever supervision stops short of the run's end - a timeout, an
+ * unreadable list - while the session it launched carries on. Judging by the
+ * pid would retire a live run on the very next tick. The pid still counts for
+ * one thing: a live supervisor and a listed session is a peer mid-poll, whatever
+ * status the row shows, and it will record the outcome itself.
  *
- * All three conditions, and the boot check is the one that matters after a
- * restart: a pid recorded before the current boot is stale by definition and
- * needs no probe at all.
+ * The boot check comes first: a claim recorded before the current boot is stale
+ * by definition and needs no probe at all.
  */
 export function holderLiveness(holder, { now = bootTime(), agentsJson } = {}) {
   if (!holder || !holder.pid) return "dead";
   if (holder.bootTime && now && holder.bootTime !== now) return "dead";
-  if (!pidAlive(holder.pid)) return "dead";
   const row = agentRow(holder.sessionId, agentsJson);
   if (row === undefined) return "unknown";
-  return row ? "live" : "dead";
+  if (!row) return "dead";
+  if (pidAlive(holder.pid)) return "live";
+  return sessionIsLive(row) ? "live" : "dead";
 }
 
 export function holderIsLive(holder, opts = {}) {
@@ -319,51 +658,156 @@ export function holderIsLive(holder, opts = {}) {
  * The run's own state file, which is what actually knows the worktree.
  *
  * The runner does not create the worktree - Phase 0 of the run does - and the
- * runner's `taskId` (`ap-<epoch>`) is not the run's task id. So the link is made
- * from disk: a state file whose `worktreePath` sits under this repo and which
- * was written after this claim started. `gc-abandoned.sh` builds the same index
- * for the same reason.
- *
- * Returns null rather than guessing. Every field it fills is one `retire()` can
- * act on; without them retire still records the attempt, it just cannot clean
- * anything up.
- */
-export function findRunState(repoPath, startedAtSec, logsRoot) {
-  const root = logsRoot || join(homedir(), ".claude", "logs", "multi-agent");
-  if (!repoPath || !existsSync(root)) return null;
+ * runner's `taskId` (`ap-<epoch>`) is not the run's task id. The link is the
+ * session id: the runner chose it, passed it as `--session-id` and as
+ * MULTI_AGENT_SESSION_ID, and Phase 0 records it as `sessionId`. Both layouts
+ * are read through _run-paths.mjs, because a run's files may be nested under
+ * its project or flat.
+ *
+ * Only a state with NO `sessionId` falls back to the older heuristic: written
+ * after this claim started, with a `worktreePath` under this repo. A state that
+ * names a different session is somebody else's run, however well it matches.
+ * `matchedBy` says which link was used, and only a session match authorises
+ * cleaning anything up.
+ *
+ * Returns null rather than guessing.
+ *
+ * @returns {{statePath:string, worktree:string|null, runTaskId:string, matchedBy:"session"|"heuristic"}|null}
+ */
+export function findRunState({ sessionId, repoPath, startedAtSec } = {}) {
+  if (!sessionId && !repoPath) return null;
   let best = null;
-  for (const dir of readdirSync(root, { withFileTypes: true })) {
-    if (!dir.isDirectory()) continue;
-    const p = join(root, dir.name, "agent-state.json");
-    if (!existsSync(p)) continue;
-    let st;
+  for (const run of listRuns()) {
+    const p = resolveRunFile(run.taskId, "agent-state.json", run.project);
+    if (!p) continue;
+    const doc = readJson(p, null);
+    if (!doc || typeof doc !== "object") continue;
+    const wt = typeof doc.worktreePath === "string" ? doc.worktreePath : null;
+    const runTaskId = doc.taskId || run.taskId;
+    if (sessionId && doc.sessionId === sessionId) {
+      return { statePath: p, worktree: wt, runTaskId, matchedBy: "session" };
+    }
+    if (doc.sessionId || !repoPath) continue;
+    let mtimeMs;
     try {
-      st = statSync(p);
+      mtimeMs = statSync(p).mtimeMs;
     } catch {
       continue;
     }
     // A second of slack: the claim is stamped before the child is spawned.
-    if (st.mtimeMs < (startedAtSec - 1) * 1000) continue;
-    const doc = readJson(p, null);
-    const wt = doc && doc.worktreePath;
+    if (mtimeMs < (startedAtSec - 1) * 1000) continue;
     if (!wt || !(wt === repoPath || wt.startsWith(repoPath + "/"))) continue;
-    if (!best || st.mtimeMs > best.mtimeMs)
-      best = { statePath: p, worktree: wt, mtimeMs: st.mtimeMs };
+    if (!best || mtimeMs > best.mtimeMs) {
+      best = { statePath: p, worktree: wt, runTaskId, matchedBy: "heuristic", mtimeMs };
+    }
   }
+  if (best) delete best.mtimeMs;
   return best;
 }
 
+function realOr(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * May this directory be removed as a run's worktree?
+ *
+ * Only a LINKED worktree that sits inside the repo it belongs to. Never the
+ * repo path itself - a local-workspace run works in the user's own checkout,
+ * which may itself be a linked worktree git would happily remove - and never a
+ * main worktree, whose git dir is the repository.
+ */
+export function removableWorktree(wt, repoPath) {
+  if (!wt || !repoPath || !existsSync(wt)) return false;
+  const w = realOr(wt);
+  const r = realOr(repoPath);
+  if (w === r || !w.startsWith(r + "/")) return false;
+  const gitPath = (flag) =>
+    run("git", ["-C", wt, "rev-parse", "--path-format=absolute", flag]).trim();
+  const gitDir = gitPath("--git-dir");
+  const commonDir = gitPath("--git-common-dir");
+  if (!gitDir || !commonDir) return false;
+  return realOr(gitDir) !== realOr(commonDir);
+}
+
+/**
+ * USD for one run, priced from the token counts its tracker recorded.
+ *
+ * Null - never 0 - when no tracker or no tokens are recorded: the spend ceiling
+ * has to be able to tell "cost nothing" from "cost is not known".
+ *
+ * @returns {number|null}
+ */
+export function runUsd(runTaskId, statePath) {
+  const dirs = [];
+  if (statePath) dirs.push(dirname(statePath));
+  if (runTaskId) dirs.push(...runDirCandidates(runTaskId));
+  let trackerPath = null;
+  for (const d of dirs) {
+    for (const base of [d, join(d, ARTIFACTS_SUBDIR)]) {
+      const p = join(base, "tracker-state.json");
+      if (existsSync(p)) {
+        trackerPath = p;
+        break;
+      }
+    }
+    if (trackerPath) break;
+  }
+  if (!trackerPath) return null;
+  const tracker = readJson(trackerPath, null);
+  const prices = readJson(join(import.meta.dirname, "cost-table.json"), null)?.prices;
+  if (!tracker || !prices) return null;
+  let usd = 0;
+  let tokens = 0;
+  for (const ph of Object.values(tracker.phases || {})) {
+    const tin = Number(ph?.tokens_in || 0);
+    const tout = Number(ph?.tokens_out || 0);
+    const tcached = Number(ph?.tokens_cached || 0);
+    if (!(tin + tout + tcached > 0)) continue;
+    tokens += tin + tout + tcached;
+    usd += costUsd(prices[ph?.model] || prices[CONSERVATIVE_PRICE], tin, tout, tcached) ?? 0;
+  }
+  return tokens > 0 ? Math.round(usd * 10000) / 10000 : null;
+}
+
 /**
  * Retire a run whose session is gone. The worktree is removed BY NAME, never by
  * sweeping: gc-worktrees.sh deliberately skips registered worktrees and always
  * will, and the runner is the only thing that knows which one it created.
+ *
+ * The run's own state speaks first. A run that opened its PR or finished after
+ * supervision stopped watching is recorded as exactly that, and a run parked on
+ * a question is left entirely alone - its state, its worktree and its
+ * attempt count. Only a run that ended without either is `died`.
  */
-function retire(holder) {
+async function retire(holder) {
   const item = holder.item || {};
   const wt = holder.worktree;
   let stashed = null;
+  const pub = await publishStep(holder.sessionId, holder.statePath, item);
+  const state = holder.statePath ? readJson(holder.statePath, null) : null;
+  const prUrl = prFromState(state);
+  const ended = pub.outcome || outcomeFor({ reason: "gone" }, state, prUrl);
+  const usd = runUsd(holder.runTaskId, holder.statePath);
+
+  if (holder.parked || isParked(ended)) {
+    record({
+      source: item.source,
+      id: item.id,
+      taskId: holder.taskId,
+      outcome: ended,
+      usd,
+      ...publishGateOf(pub),
+    });
+    log(`${item.id}: parked (${ended}) - its session, state and worktree are left alone`);
+    return;
+  }
 
-  if (wt && existsSync(wt)) {
+  if (wt && existsSync(wt) && holder.createdWorktree) {
     const dirty = run("git", ["-C", wt, "status", "--porcelain"]).trim();
     if (dirty) {
       // A day of edits is worth more than 750 MB. The stash MESSAGE carries the
@@ -376,30 +820,44 @@ function retire(holder) {
       // the stash commit's third parent, not in its tree. One honest reference
       // beats two, and this is the contract gc-abandoned.sh already keeps.
       const label = `autopilot/abandoned/${holder.taskId || item.id || "unknown"}`;
-      run("git", ["-C", wt, "stash", "push", "-u", "-m", label]);
-      stashed = label;
-      log(`kept ${wt}: uncommitted work stashed as "${label}" (git stash list)`);
-    } else if (holder.createdWorktree) {
+      if (stashWorktree(wt, label)) {
+        stashed = label;
+        log(`kept ${wt}: uncommitted work stashed as "${label}" (git stash list)`);
+      } else {
+        log(`kept ${wt}: uncommitted work left in place - git stash push failed`);
+      }
+    } else if (!removableWorktree(wt, holder.repoPath)) {
+      log(`kept ${wt}: not a linked worktree inside ${holder.repoPath || "its repo"}`);
+    } else if (agentRow(holder.sessionId)) {
       // A clean worktree is only safe to remove once nothing is writing to it.
       // Supervision can end while the run does not - a timeout, or an agent
       // list that could not be read - and `worktree remove --force` under a
       // live session is the one mistake here with nothing to undo it.
-      if (agentRow(holder.sessionId)) {
-        log(`kept ${wt}: session ${holder.sessionId} is still listed`);
-      } else {
-        run("git", ["-C", wt, "worktree", "remove", "--force", wt]);
-        run("git", ["-C", holder.repoPath || wt, "worktree", "prune"]);
-        log(`removed ${wt}`);
-      }
+      log(`kept ${wt}: session ${holder.sessionId} is still listed`);
+    } else {
+      run("git", ["-C", wt, "worktree", "remove", "--force", wt]);
+      run("git", ["-C", holder.repoPath, "worktree", "prune"]);
+      log(`removed ${wt}`);
     }
   }
 
-  if (holder.statePath && existsSync(holder.statePath)) {
-    const st = readJson(holder.statePath, null);
-    if (st) {
-      st.status = "abandoned";
-      st.abandonedBy = "autopilot-runner";
-      writeFileSync(holder.statePath, JSON.stringify(st, null, 2));
+  if (isTerminal(ended)) {
+    record({ source: item.source, id: item.id, taskId: holder.taskId, outcome: ended, prUrl, usd });
+    return;
+  }
+
+  // Only a state this runner's session wrote is marked. A heuristic match may be
+  // an attended run in the same repo, and its state is not ours to rewrite. The
+  // write takes the state lock and bumps `rev`, as every other writer does.
+  if (holder.matchedBy === "session" && state) {
+    try {
+      await updateState(holder.statePath, (s) => ({
+        ...s,
+        status: "abandoned",
+        abandonedBy: "autopilot-runner",
+      }));
+    } catch (e) {
+      log(`${item.id}: could not mark the state abandoned: ${e?.message || e}`);
     }
   }
 
@@ -407,9 +865,75 @@ function retire(holder) {
     source: item.source,
     id: item.id,
     taskId: holder.taskId,
-    outcome: "died",
+    outcome: OUTCOME.DIED,
     stashedTo: stashed,
+    usd,
+  });
+}
+
+/**
+ * Stash a worktree's uncommitted work, untracked files included. True only when
+ * git says it stashed: a stash reference is recorded for a person to find, and
+ * one that does not exist sends them looking for work that is still in the
+ * worktree, or gone.
+ */
+export function stashWorktree(wt, label) {
+  const r = spawnSync("git", ["-C", wt, "stash", "push", "-u", "-m", label], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 120000,
+  });
+  if (r.status !== 0) return false;
+  const top = spawnSync("git", ["-C", wt, "stash", "list", "-n", "1", "--format=%s"], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return top.status === 0 && String(top.stdout).includes(label);
+}
+
+/**
+ * Settle the runs parked in `running`.
+ *
+ * A parked run holds its repo - its session may resume and write to the
+ * worktree - but not the supervisor, which returned when the run stopped to
+ * ask. Nothing about it is retired: once its session ends, whatever its state
+ * then records is written as a new outcome if it is one (a PR opened after the
+ * answer, a failure after it), the slot is released, and the state file and
+ * worktree are never touched.
+ */
+async function reconcileParked() {
+  const q = readJson(join(ROOT, "queue.json"), null);
+  const parked = (q?.running || []).filter((r) => r.state === "parked");
+  if (!parked.length) return;
+  const settled = new Set();
+  for (const e of parked) {
+    const row = agentRow(e.sessionId);
+    if (row === undefined || sessionIsLive(row)) continue;
+    const pub = DRY ? { outcome: null } : await publishStep(e.sessionId, e.statePath, e);
+    const st = e.statePath ? readJson(e.statePath, null) : null;
+    const prUrl = prFromState(st);
+    const outcome = pub.outcome || outcomeFor({ reason: "gone" }, st, prUrl);
+    if (!isParked(outcome) && !DRY) {
+      record({
+        source: e.source,
+        id: e.id,
+        taskId: e.taskId,
+        outcome,
+        prUrl,
+        usd: runUsd(e.runTaskId, e.statePath),
+        ...publishGateOf(pub),
+      });
+    }
+    log(`${e.id}: parked session ended (${outcome}) - slot released`);
+    settled.add(e.id);
+  }
+  if (!settled.size || DRY) return;
+  const after = readJson(join(ROOT, "queue.json"), q);
+  writeState("queue.json", {
+    ...after,
+    running: (after.running || []).filter((r) => !(r.state === "parked" && settled.has(r.id))),
   });
+  refreshStatus();
 }
 
 function refreshStatus() {
@@ -417,15 +941,48 @@ function refreshStatus() {
   if (existsSync(s)) run("bash", [s, "--write"]);
 }
 
+/**
+ * Does `bin/menubar` predate the source it was compiled from?
+ *
+ * The indicator is built from source on demand rather than shipped as a binary,
+ * so the compiled artifact is the one thing in the install that an update does
+ * not replace. Comparing the two timestamps is what ties it to the release: the
+ * installer lays the `.swift` down fresh, and this answers yes exactly once
+ * after it does.
+ */
+export function indicatorStale(src, out) {
+  if (!existsSync(src)) return false;
+  if (!existsSync(out)) return true;
+  return statSync(src).mtimeMs > statSync(out).mtimeMs;
+}
+
+/** Compile the indicator when it is stale. Best effort: no swiftc, no indicator. */
+function ensureIndicator() {
+  const src = join(SCRIPTS, "autopilot-menubar.swift");
+  const out = join(ROOT, "bin", "menubar");
+  if (!indicatorStale(src, out)) return;
+  mkdirSync(dirname(out), { recursive: true, mode: 0o700 });
+  const built = spawnSync("swiftc", ["-O", src, "-o", out], { stdio: "ignore" });
+  // No swiftc means no indicator and nothing else changes - a supported shape,
+  // and one that would otherwise put a line in the log on every tick for the
+  // life of the machine. A compiler that IS here and refused is worth saying.
+  if (built.error?.code === "ENOENT") return;
+  if (built.error || built.status !== 0) {
+    log("swiftc refused the menu bar indicator - the terminal status is unaffected");
+    return;
+  }
+  chmodSync(out, 0o700);
+  log("rebuilt the menu bar indicator from its source");
+}
+
 /**
  * Put the slot back and drop the claim. One place, so every exit agrees.
  *
  * It re-reads queue.json rather than trusting a copy, because intake runs
- * between the read and here. The recovery path calls this too: `retire()` used
- * to record the outcome and delete the claim while leaving the item in
- * `running`, and nothing else on this machine ever removes one - intake copies
- * the list forward verbatim. One crashed runner was enough to wedge the queue
- * at "1/1 slots in use" on every tick from then on.
+ * between the read and here. The recovery path calls this too: nothing else on
+ * this machine removes an entry from `running` - intake copies the list forward
+ * verbatim - so a retirement that dropped the claim without this would leave
+ * the queue at "1/1 slots in use" on every tick.
  */
 function releaseSlot(id, pidPath, queue = { queued: [], running: [] }) {
   const after = readJson(join(ROOT, "queue.json"), queue);
@@ -437,6 +994,157 @@ function releaseSlot(id, pidPath, queue = { queued: [], running: [] }) {
   refreshStatus();
 }
 
+/**
+ * The publish step for one ended session: verify the PR request it left, push,
+ * open the draft PR, then post what the config opts into
+ * (autopilot-publish.mjs). `outcome` is null when there was nothing to publish,
+ * and the run's own state then decides the attempt as before.
+ *
+ * @returns {Promise<{outcome: string|null, prUrl?: string}>}
+ */
+async function publishStep(sessionId, statePath, item) {
+  if (!sessionId || !statePath || !item?.repo) return { outcome: null };
+  const config = readJson(join(ROOT, "config.json"), null);
+  let pub;
+  try {
+    pub = await publish({ sessionId, statePath, item, config });
+  } catch (err) {
+    log(`${item.id}: publish step failed: ${err?.message || err}`);
+    return { outcome: null };
+  }
+  if (!pub.outcome) return pub;
+  if (pub.outcome === OUTCOME.VERIFICATION_FAILED) {
+    log(`${item.id}: publish refused at ${pub.gate}: ${pub.reason}`);
+    return pub;
+  }
+  log(`${item.id}: published (${pub.outcome})${pub.prUrl ? ` ${pub.prUrl}` : ""}`);
+  if (pub.outcome === OUTCOME.PR_OPENED) {
+    const reports = reportAfterPublish({
+      prUrl: pub.prUrl,
+      request: pub.request,
+      item,
+      state: readJson(statePath, null),
+      config,
+      scripts: outwardScripts(),
+    });
+    for (const r of reports) {
+      log(`${item.id}: report ${r.channel} ${r.status}${r.reason ? ` (${r.reason})` : ""}`);
+    }
+  }
+  return pub;
+}
+
+/** The refusing publish gate, for the attempt row the breaker reads. */
+function publishGateOf(pub) {
+  return pub?.outcome === OUTCOME.VERIFICATION_FAILED && pub.gate ? { publishGate: pub.gate } : {};
+}
+
+/** Overrides for the outward scripts, so a test never reaches the real tracker. */
+function outwardScripts() {
+  return process.env.MA_AP_JIRA_PUBLISH ? { jiraPublish: process.env.MA_AP_JIRA_PUBLISH } : {};
+}
+
+/** Every row of attempted.jsonl; the digest needs a full day, not the recent tail. */
+function readAllAttempted() {
+  const p = join(ROOT, "attempted.jsonl");
+  if (!existsSync(p)) return [];
+  try {
+    return readFileSync(p, "utf-8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => {
+        try {
+          return JSON.parse(l);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The two jobs that run at most once per local day, on the first tick of it.
+ * Each is stamped in daily.json whether or not it succeeded, so a job that
+ * fails is retried tomorrow rather than on every tick; the failure is logged
+ * and, for the digest, recorded in its file. Neither ever fails the tick.
+ */
+function dailyJobs(config) {
+  const date = localDate();
+  const queue = readJson(join(ROOT, "queue.json"), { queued: [], running: [] });
+  if (dailyDue(ROOT, "gc", date)) {
+    try {
+      gcReport({
+        root: ROOT,
+        gcScript: join(SCRIPTS, "gc-abandoned.sh"),
+        logsRoot: logsRoot(),
+        config,
+        queue,
+        date,
+        log,
+      });
+    } catch (e) {
+      log(`cleanup report failed: ${e?.message || e}`);
+    }
+    markDaily(ROOT, "gc", date);
+  }
+  if (config?.digest?.enabled === true && dailyDue(ROOT, "digest", date)) {
+    try {
+      const digest = buildDigest({
+        lines: readAllAttempted(),
+        queue,
+        ceilingUsd: Number(config.costCeilingUsd ?? 25),
+      });
+      const text = digestText(digest);
+      const sent = reportDigest({ text, config, scripts: outwardScripts() });
+      for (const r of sent) {
+        log(`digest: ${r.channel} ${r.status}${r.reason ? ` (${r.reason})` : ""}`);
+      }
+      writeFileSync(
+        join(ROOT, `digest-${date}.json`),
+        JSON.stringify({ date, ...digest, sent }, null, 2) + "\n",
+        { mode: 0o600 },
+      );
+      writeFileSync(join(ROOT, `digest-${date}.md`), text, { mode: 0o600 });
+      pruneDaily(ROOT, "digest-");
+      log(
+        `digest: ${digest.items} item(s), ${digest.prsOpened.length} PR(s) - digest-${date}.json`,
+      );
+    } catch (e) {
+      log(`digest failed: ${e?.message || e}`);
+    }
+    markDaily(ROOT, "digest", date);
+  }
+}
+
+/**
+ * The cleanup ledger: one line per worktree this runner can prove it created,
+ * read by the daily cleanup report and by nothing that removes on its own.
+ */
+function recordWorktree(claim) {
+  if (!claim.worktree) return;
+  try {
+    ensureRoot();
+    const p = join(ROOT, "worktrees.jsonl");
+    appendFileSync(
+      p,
+      JSON.stringify({
+        at: Math.floor(Date.now() / 1000),
+        sessionId: claim.sessionId,
+        taskId: claim.taskId,
+        runTaskId: claim.runTaskId || null,
+        repoPath: claim.repoPath || null,
+        worktree: realOr(claim.worktree),
+      }) + "\n",
+      { mode: 0o600 },
+    );
+  } catch {
+    // The ledger only feeds a report; a failed append costs one report line.
+  }
+}
+
 /** The PR a run opened, wherever its state file recorded it. */
 export function prFromState(state) {
   const pr = state && state.pr;
@@ -447,22 +1155,521 @@ export function prFromState(state) {
 }
 
 /**
- * What to call this attempt.
+ * What to call this attempt. Every word it can return is classified in
+ * _autopilot-outcomes.mjs, and test/autopilot-runner.test.mjs fails on one
+ * that is not.
  *
  * The run's own state is the authority; the supervisor only says why waiting
- * stopped. "finished with no PR" is deliberately not "failed": a run can stop
+ * stopped. The order is what the words mean:
+ *
+ *   - a PR first. Phase 5 holds for input AFTER the PR is open, so a session
+ *     parked there has delivered, and calling it anything else re-queues work
+ *     that is already in review. A branch the runner pushed to a host with no
+ *     draft PR (`state.publish`) is delivered the same way.
+ *   - a state waiting on a person (`waitingFor`, `awaiting_input`) next, before
+ *     the supervisor's reasons: a run parked on a maturity question that
+ *     outlived the ceiling is still parked, not timed out.
+ *   - a rate limit before the state's own status, because a limited run's state
+ *     says only where it stopped.
+ *   - `verificationFailed`, written by gate-ledger.mjs `park` when an
+ *     unattended run's own gate rejected its work, before a plain `failed`:
+ *     retrying repeats the same work into the same rejection.
+ *
+ * "finished with no PR" is deliberately not "failed": a run can stop
  * legitimately without opening one, and calling that a failure would put a
  * healthy item into the retry path.
  */
 export function outcomeFor(supervised, state, prUrl) {
-  if (supervised.reason === "timeout") return "timed-out";
-  if (supervised.reason === "unknown") return "unknown";
-  if (supervised.reason === "needs-input") return "needs-input";
-  if (prUrl) return "pr-opened";
+  if (prUrl) return OUTCOME.PR_OPENED;
+  if (state?.publish?.outcome === OUTCOME.PUSHED_AWAITING_PR) return OUTCOME.PUSHED_AWAITING_PR;
+  if (state && (state.waitingFor || state.status === "awaiting_input")) {
+    return OUTCOME.AWAITING_ANSWER;
+  }
+  if (supervised.reason === "timeout") return OUTCOME.TIMED_OUT;
+  if (supervised.reason === "unknown") return OUTCOME.UNKNOWN;
+  if (supervised.reason === "needs-input") return OUTCOME.NEEDS_INPUT;
+  if (rateLimited({ row: supervised.lastRow, state })) return OUTCOME.RATE_LIMITED;
+  if (state && state.verificationFailed) return OUTCOME.VERIFICATION_FAILED;
   const status = state && state.status;
-  if (status === "complete" || status === "completed") return "completed-no-pr";
-  if (status === "failed") return "failed";
-  return state ? `stopped-${status || "unknown"}` : "no-state";
+  if (status === "complete" || status === "completed") return OUTCOME.COMPLETED_NO_PR;
+  if (status === "failed") return OUTCOME.FAILED;
+  return state ? `stopped-${status || "unknown"}` : OUTCOME.NO_STATE;
+}
+
+/**
+ * The `claude` arguments for one item. The shape - background, a session id
+ * this runner chose, no permission prompts, the unattended permission profile
+ * as an extra settings file, one unattended `/multi-agent` item - is pending a
+ * live launch trial; everything that launches or describes a launch derives
+ * from here so a correction is one edit.
+ */
+export function launchArgv(item, sessionId, settingsFile = unattendedSettingsPath()) {
+  return [
+    "--bg",
+    "--session-id",
+    sessionId,
+    "--permission-prompts",
+    "none",
+    "--settings",
+    settingsFile,
+    "-p",
+    `/multi-agent ${item.ref || item.id} autopilot`,
+  ];
+}
+
+/**
+ * The child's environment. MULTI_AGENT_UNATTENDED=1 is the operator contract
+ * (unattended-contract.md) that nobody is watching; MULTI_AGENT_SESSION_ID is
+ * what Phase 0 records as `sessionId`, which is how findRunState finds this
+ * run and no other. LOGS_ROOT puts the run's state under the unattended run
+ * directory, the one place outside the worktree the sandbox lets it write
+ * (an operator's own LOGS_ROOT is kept). MA_RUN_BASE_SHA is the checkout's
+ * HEAD when the item was taken: agent-guard trusts a repository file as a
+ * program only when it is unchanged from that commit, so a file the run
+ * committed itself never counts.
+ *
+ * @param {string} sessionId
+ * @param {Record<string,string|undefined>} [base]
+ * @param {{baseSha?: string|null}} [opts]
+ */
+export function launchEnv(sessionId, base = process.env, { baseSha = null } = {}) {
+  const deny = [
+    ...TOOLKIT_INDEX_DENY.split(","),
+    ...String(base.MCP_TOOLKIT_INDEX_DENY || "").split(","),
+  ]
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const { MA_RUN_BASE_SHA: _stale, ...rest } = base;
+  return {
+    ...rest,
+    MULTI_AGENT_UNATTENDED: "1",
+    MULTI_AGENT_SESSION_ID: sessionId,
+    MCP_TOOLKIT_URL_POLICY: TOOLKIT_URL_POLICY,
+    MCP_TOOLKIT_INDEX_DENY: [...new Set(deny)].join(","),
+    LOGS_ROOT: base.LOGS_ROOT || unattendedLogsRoot(base),
+    ...(baseSha ? { MA_RUN_BASE_SHA: baseSha } : {}),
+  };
+}
+
+/**
+ * Ready the runner's side of a launch: both requests directories exist at
+ * 0700 (the run's, under the unattended run directory, and the runner's own
+ * for verdicts), and nothing is left under this session's name from before.
+ * A request the publish step finds must be one this session wrote.
+ */
+export function prepareLaunch(sessionId, env = process.env) {
+  for (const dir of [prRequestsDir(env), runRequestsDir(env)]) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    for (const suffix of [".json", ".verdict.json", SUMMARY_SUFFIX]) {
+      rmSync(join(dir, `${sessionId}${suffix}`), { force: true });
+    }
+  }
+}
+
+/**
+ * Does the profile file still hold the OS sandbox the unattended contract
+ * rests on, and does the checkout leave it alone? Judged by content, before
+ * every launch (the first run, each research pass, each resume), so a run
+ * that rewrote the file, or a repository whose own settings widen the child,
+ * never reaches the next launch.
+ *
+ * @param {{home?: string, cwd?: string|null}} [opts]
+ * @returns {{ok: boolean, reason?: string}}
+ */
+export function sandboxPrecondition({ home = homedir(), cwd = null } = {}) {
+  const path = unattendedSettingsPath(home);
+  if (!PROFILE_SCHEMA)
+    return {
+      ok: false,
+      reason: "schemas/unattended-profile.json is not installed beside the runner",
+    };
+  if (!existsSync(path))
+    return {
+      ok: false,
+      reason: `the unattended profile ${path} is not installed (install --unattended writes it)`,
+    };
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    return { ok: false, reason: `the unattended profile ${path} does not parse: ${err.message}` };
+  }
+  const gaps = profileGaps(doc, PROFILE_SCHEMA, { extraHosts: prefsHosts(home) });
+  const project = cwd
+    ? [join(cwd, ".claude", "settings.json"), join(cwd, ".claude", "settings.local.json")]
+        .map((f) => readJson(f, null))
+        .filter((d) => d && typeof d === "object")
+    : [];
+  const all = [...gaps.sandbox, ...gaps.permissions, ...projectSettingsGaps(project)];
+  if (all.length)
+    return {
+      ok: false,
+      reason: `the unattended sandbox is not in force: ${all.join("; ")} (install --unattended restores the profile)`,
+    };
+  return { ok: true };
+}
+
+/** The checkout's HEAD commit, or null when it has none. */
+function headSha(cwd) {
+  const r = spawnSync("git", ["-C", cwd, "rev-parse", "--verify", "--quiet", "HEAD^{commit}"], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 10000,
+  });
+  return r.status === 0 ? r.stdout.trim() || null : null;
+}
+
+/** Does a hook matcher (a regex over the tool name, empty or `*` for all) cover this tool? */
+function matcherCovers(matcher, tool) {
+  const m = typeof matcher === "string" ? matcher : "";
+  if (m === "" || m === "*") return true;
+  try {
+    return new RegExp(`^(?:${m})$`).test(tool);
+  } catch {
+    return false;
+  }
+}
+
+/** The guard script, when the hook command is exactly the installer's and the script exists. */
+function guardScriptOf(command, home) {
+  const script = join(home, ".claude", "scripts", "agent-guard.sh");
+  const forms = [GUARD_COMMAND, GUARD_COMMAND.replace("$HOME", "${HOME}"), `bash ${script}`];
+  return forms.includes(String(command || "").trim()) && existsSync(script) ? script : null;
+}
+
+/**
+ * Is agent-guard.sh registered where the child will load it?
+ *
+ * Read the way install/claude.mjs writes it: a PreToolUse entry whose matcher
+ * covers the tool and whose command runs agent-guard.sh. All three matchers are
+ * required: the Bash entry is the one that stops a push, the
+ * Edit|Write|NotebookEdit entry the one that stops a write into a protected
+ * path, and the WebFetch|mcp__multi-agent-toolkit__web_.* entry the one that
+ * holds WebFetch and every toolkit tool to the network host policy. A
+ * matcher is judged as Claude Code judges it, a regex over the tool name, so
+ * the legacy `Bash(git push:*)` does not count. The hook command has to be the
+ * one the installer writes and its script has to exist: a hook whose script is
+ * missing exits non-zero without blocking anything, and a command that only
+ * mentions the script path proves nothing. `disableAllHooks` in any file turns
+ * every hook off.
+ *
+ * Files read for the registration: the user settings (CLAUDE_CONFIG_DIR, else
+ * ~/.claude) and macOS managed settings. The checkout's project settings are
+ * read only for `disableAllHooks`: the repo under work is not where the
+ * guard's registration may come from.
+ *
+ * @returns {{ok: boolean, missing: string[], reason?: string}}
+ */
+export function guardRegistration({
+  home = homedir(),
+  env = process.env,
+  cwd = null,
+  managedPath = MANAGED_SETTINGS,
+} = {}) {
+  const userDir = env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+  const files = [join(userDir, "settings.json"), join(userDir, "settings.local.json"), managedPath];
+  const project = cwd
+    ? [join(cwd, ".claude", "settings.json"), join(cwd, ".claude", "settings.local.json")]
+    : [];
+  const read = (list) =>
+    list.map((f) => readJson(f, null)).filter((d) => d && typeof d === "object");
+  const docs = read(files);
+  const off = [...docs, ...read(project)].find((d) => d.disableAllHooks === true);
+  const required = GUARD_MATCHERS.map(([label]) => label);
+  if (off) return { ok: false, missing: required, reason: "disableAllHooks is set" };
+  const managed = readJson(managedPath, null);
+  const sources = managed?.allowManagedHooksOnly === true ? [managed] : docs;
+  const entries = sources.flatMap((d) =>
+    Array.isArray(d?.hooks?.PreToolUse) ? d.hooks.PreToolUse : [],
+  );
+  const missing = GUARD_MATCHERS.filter(([, tools]) =>
+    tools.some(
+      (tool) =>
+        !entries.some(
+          (e) =>
+            e &&
+            matcherCovers(e.matcher, tool) &&
+            Array.isArray(e.hooks) &&
+            e.hooks.some((h) => h && h.type === "command" && guardScriptOf(h.command, home)),
+        ),
+    ),
+  ).map(([label]) => label);
+  if (missing.length)
+    return {
+      ok: false,
+      missing,
+      reason: `agent-guard.sh is not registered on ${missing.join(", ")}`,
+    };
+  // The child is launched with `--settings <profile>`; without the file there is
+  // no dontAsk default and no narrow allow list, and the run stops at its first
+  // tool call.
+  const profile = unattendedSettingsPath(home);
+  if (!existsSync(profile))
+    return {
+      ok: false,
+      missing: [],
+      reason: `the unattended permission profile ${profile} is not installed (install --unattended writes it)`,
+    };
+  return { ok: true, missing: [] };
+}
+
+/**
+ * Should this run's parked state get a research pass before a person is asked?
+ *
+ * Only the two parks research can act on: the maturity step (`waitingFor:
+ * maturity`, or a Phase 0 halt that still carries blockers) and the Phase 1
+ * open-questions gate. Everything else a run waits on - the channels menu, a
+ * failed verification, a user test - is a person's call and stays one. The
+ * ceiling counts every round this item has had, across runs, because a fresh
+ * run of the same item is a fresh state file and would otherwise start at zero.
+ *
+ * @returns {{route: "research"|"none", kind?: "maturity"|"open-questions", reason?: string}}
+ */
+export function researchRoute(state, prUrl, { roundsUsed = 0, maxAskRounds = 2 } = {}) {
+  if (prUrl || !state || typeof state !== "object") return { route: "none" };
+  let kind = null;
+  const pq = state.pendingQuestion;
+  if (state.waitingFor === "maturity") kind = "maturity";
+  else if (state.waitingFor === "question" && pq?.stepId === "phase-1/open-questions") {
+    kind = "open-questions";
+  } else if (
+    !state.waitingFor &&
+    !state.verificationFailed &&
+    (state.currentPhase ?? 0) === 0 &&
+    state.status !== "complete" &&
+    Array.isArray(state.maturity?.blockers) &&
+    state.maturity.blockers.length > 0
+  ) {
+    kind = "maturity";
+  }
+  if (!kind) return { route: "none" };
+  if (roundsUsed >= maxAskRounds) {
+    return {
+      route: "none",
+      kind,
+      reason: `${roundsUsed} research round(s) used, maxAskRounds ${maxAskRounds} - left for a person`,
+    };
+  }
+  return { route: "research", kind };
+}
+
+/** Research rounds already spent on one item, summed from attempted.jsonl. */
+export function researchRoundsUsed(lines, item) {
+  let n = 0;
+  for (const row of lines || []) {
+    if (!row || row.source !== item?.source || row.id !== item?.id) continue;
+    const r = Number(row.researchRounds || 0);
+    if (Number.isFinite(r) && r > 0) n += r;
+  }
+  return n;
+}
+
+/** The research session's arguments: the same launch shape, one command, fewer tools. */
+export function researchArgv(item, sessionId, statePath, settingsFile = unattendedSettingsPath()) {
+  const state = /\s/.test(statePath) ? JSON.stringify(statePath) : statePath;
+  return [
+    "--bg",
+    "--session-id",
+    sessionId,
+    "--permission-prompts",
+    "none",
+    "--settings",
+    settingsFile,
+    "--disallowedTools",
+    RESEARCH_DENIED_TOOLS.join(","),
+    "-p",
+    `/multi-agent:research ${item.ref || item.id} --autonomous --state ${state}`,
+  ];
+}
+
+/** Continue a parked run after research closed its gaps. */
+export function resumeArgv(runTaskId, sessionId, settingsFile = unattendedSettingsPath()) {
+  return [
+    "--bg",
+    "--session-id",
+    sessionId,
+    "--permission-prompts",
+    "none",
+    "--settings",
+    settingsFile,
+    "-p",
+    `/multi-agent:resume ${runTaskId} autopilot`,
+  ];
+}
+
+/** Point the claim and the running entry at the session now in flight. */
+function rebindSession(claim, item, sessionId) {
+  claim.sessionId = sessionId;
+  writeState("runner.pid", claim);
+  const q = readJson(join(ROOT, "queue.json"), null);
+  if (!q) return;
+  writeState("queue.json", {
+    ...q,
+    running: (q.running || []).map((r) => (r.id === item.id ? { ...r, sessionId } : r)),
+  });
+}
+
+function launch(argv, cwd, sessionId, baseSha) {
+  const sandbox = sandboxPrecondition({ cwd });
+  if (!sandbox.ok)
+    return { status: 1, stderr: `${OUTCOME.BLOCKED_SANDBOX_UNAVAILABLE}: ${sandbox.reason}` };
+  prepareLaunch(sessionId);
+  return spawnSync(CLAUDE_BIN, argv, {
+    cwd,
+    env: launchEnv(sessionId, process.env, { baseSha }),
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: LAUNCH_TIMEOUT_MS,
+  });
+}
+
+/** Run research-gate.mjs on the parked state; its verdict, or null when it gave none. */
+function researchVerdict(statePath, sessionId) {
+  if (!existsSync(RESEARCH_GATE)) return null;
+  const r = spawnSync(process.execPath, [RESEARCH_GATE, "--state", statePath, "--json"], {
+    env: launchEnv(sessionId),
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: LAUNCH_TIMEOUT_MS,
+  });
+  try {
+    const out = JSON.parse(r.stdout || "");
+    return typeof out.decision === "string" ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Research rounds for a run that parked, until one does not proceed.
+ *
+ * Each round is two sessions at most: the research pass, then - only when
+ * research-gate.mjs says the re-run check passed - the parked run resumed. A
+ * resumed run that parks again on the other kind of gap gets another round
+ * while the ceiling allows. Anything short of a clean proceed stops the loop
+ * with the run's state as it is, which the caller records: a parked state is
+ * awaiting-answer, exactly as it would have been without research.
+ */
+function researchRounds(claim, item, run0, { roundsUsed, maxAskRounds }) {
+  let { supervised, state, prUrl } = run0;
+  let rounds = 0;
+  for (;;) {
+    if (!claim.statePath || !ENDED.has(supervised.reason)) break;
+    const route = researchRoute(state, prUrl, { roundsUsed: roundsUsed + rounds, maxAskRounds });
+    if (route.route !== "research") {
+      if (route.reason) log(`${item.id}: ${route.reason}`);
+      break;
+    }
+    const guard = guardRegistration({ cwd: item.localPath });
+    if (!guard.ok) {
+      log(`${item.id}: ${guard.reason} - no research session is launched, left for a person`);
+      break;
+    }
+    rounds++;
+    const rsid = randomUUID();
+    rebindSession(claim, item, rsid);
+    log(`${item.id}: parked on ${route.kind} - research round ${roundsUsed + rounds}`);
+    const rchild = launch(
+      researchArgv(item, rsid, claim.statePath),
+      item.localPath,
+      rsid,
+      claim.baseSha,
+    );
+    if (rchild.status !== 0) {
+      log(`${item.id}: research launch failed - left for a person`);
+      break;
+    }
+    const rs = supervise(rsid, claim, item);
+    if (!ENDED.has(rs.reason)) {
+      supervised = rs;
+      break;
+    }
+    const verdict = researchVerdict(claim.statePath, rsid);
+    state = readJson(claim.statePath, state);
+    if (!verdict || verdict.decision !== "proceed") {
+      log(
+        `${item.id}: research ${verdict ? verdict.decision : "gave no verdict"} - left for a person`,
+      );
+      break;
+    }
+    const runTaskId = claim.runTaskId || state?.taskId;
+    if (!runTaskId) break;
+    const guardAgain = guardRegistration({ cwd: item.localPath });
+    if (!guardAgain.ok) {
+      log(`${item.id}: ${guardAgain.reason} - the run is not resumed, left for a person`);
+      break;
+    }
+    const dsid = randomUUID();
+    rebindSession(claim, item, dsid);
+    log(
+      `${item.id}: research closed ${verdict.closed?.join(", ") || "the gaps"} - resuming ${runTaskId}`,
+    );
+    const dchild = launch(resumeArgv(runTaskId, dsid), item.localPath, dsid, claim.baseSha);
+    if (dchild.status !== 0) {
+      log(`${item.id}: resume launch failed - the run stays parked`);
+      break;
+    }
+    supervised = supervise(dsid, claim, item);
+    state = readJson(claim.statePath, state);
+    prUrl = prFromState(state);
+  }
+  return { supervised, state, prUrl, rounds };
+}
+
+/** Link the claim to the run's state; upgrade a heuristic match once the session's own appears. */
+function trackRunState(claim) {
+  if (claim.matchedBy === "session") return;
+  const found = findRunState({
+    sessionId: claim.sessionId,
+    repoPath: claim.repoPath,
+    startedAtSec: claim.startedAt,
+  });
+  if (!found || found.statePath === claim.statePath) return;
+  if (claim.statePath && found.matchedBy !== "session") return;
+  claim.statePath = found.statePath;
+  claim.worktree = found.worktree;
+  claim.runTaskId = found.runTaskId;
+  claim.matchedBy = found.matchedBy;
+  // Phase 0 opened the worktree, not this runner - but this runner is the only
+  // thing that will be around to remove it, and only when the state is
+  // provably this session's.
+  claim.createdWorktree = found.matchedBy === "session";
+  writeState("runner.pid", claim);
+  if (claim.createdWorktree) recordWorktree(claim);
+  log(`tracking ${found.worktree || found.statePath} (matched by ${found.matchedBy})`);
+}
+
+/** Mirror the run's current phase onto its `running` entry, which the status line renders. */
+function trackProgress(claim, id) {
+  if (!claim.statePath) return;
+  const st = readJson(claim.statePath, null);
+  const phase = st && Number.isInteger(st.currentPhase) ? st.currentPhase : null;
+  if (phase === null || phase === claim.phase) return;
+  claim.phase = phase;
+  const q = readJson(join(ROOT, "queue.json"), null);
+  if (!q) return;
+  const last = PHASES.length ? PHASES[PHASES.length - 1].id : null;
+  const phaseName = PHASES.find((p) => p.id === phase)?.name ?? null;
+  writeState("queue.json", {
+    ...q,
+    running: (q.running || []).map((r) =>
+      r.id === id ? { ...r, phase, phaseName, phaseTotal: last } : r,
+    ),
+  });
+  refreshStatus();
+}
+
+/**
+ * Has this session's own state recorded that the run stopped - to ask a
+ * person, or for good? Only a state matched by session id is believed.
+ */
+export function stateSaysStopped(claim) {
+  if (!claim || claim.matchedBy !== "session" || !claim.statePath) return false;
+  const st = readJson(claim.statePath, null);
+  if (!st || typeof st !== "object") return false;
+  if (st.waitingFor || st.status === "awaiting_input" || st.verificationFailed) return true;
+  return ["complete", "completed", "failed"].includes(st.status);
 }
 
 /**
@@ -474,45 +1681,43 @@ export function outcomeFor(supervised, state, prUrl) {
  * is reached. An unreadable list ends it too, but says "unknown" rather than
  * inventing an outcome.
  *
+ * A session is listed a moment AFTER `--bg` returns, so until it has been seen
+ * once an absent row and an empty or unreadable list are the same thing - not
+ * yet - and both get the registration grace.
+ *
  * The claim is enriched on the way: the first poll that finds the run's state
  * file writes `worktree` and `statePath` into runner.pid, which is what lets a
- * LATER tick's retire() actually clean up. Those fields were read by retire()
- * from the day it was written and never once set by anything.
+ * LATER tick's retire() clean up.
  */
 function supervise(sessionId, claim, item) {
   const startedMs = Date.now();
   const deadline = startedMs + MAX_RUN_MS;
   let sawLive = false;
   let sawBusy = false;
+  let lastRow = null;
   let reason;
 
   for (;;) {
     const row = agentRow(sessionId);
+    const inGrace = !sawLive && Date.now() - startedMs <= REGISTER_GRACE_MS;
 
     if (row === undefined) {
-      reason = "unknown";
-      break;
-    }
-    if (row) {
-      sawLive = true;
-      if (!claim.statePath) {
-        const found = findRunState(claim.repoPath, claim.startedAt);
-        if (found) {
-          claim.statePath = found.statePath;
-          claim.worktree = found.worktree;
-          // Phase 0 opened it, not this runner - but this runner is the only
-          // thing that will be around to remove it.
-          claim.createdWorktree = true;
-          writeState("runner.pid", claim);
-          log(`tracking ${found.worktree}`);
-        }
+      if (!inGrace) {
+        reason = "unknown";
+        break;
       }
+    } else if (row) {
+      sawLive = true;
+      lastRow = row;
+      trackRunState(claim);
+      trackProgress(claim, item.id);
       if (row.status === "busy" || row.status === "running") sawBusy = true;
       if (row.status === "waiting") {
         // Only terminal once the run has actually been working. A session can
         // read as "waiting" in the second after launch, and ending supervision
-        // there would abandon every run at birth.
-        if (sawBusy) {
+        // there would abandon every run at birth. A run that worked between two
+        // polls is not caught by that, so the run's own state is asked too.
+        if (sawBusy || stateSaysStopped(claim)) {
           reason = "needs-input";
           break;
         }
@@ -520,7 +1725,7 @@ function supervise(sessionId, claim, item) {
         reason = "finished";
         break;
       }
-    } else if (sawLive || Date.now() - startedMs > REGISTER_GRACE_MS) {
+    } else if (!inGrace) {
       reason = "gone";
       break;
     }
@@ -532,28 +1737,101 @@ function supervise(sessionId, claim, item) {
     sleepSync(POLL_MS);
   }
 
-  if (!claim.statePath) {
-    const found = findRunState(claim.repoPath, claim.startedAt);
-    if (found) {
-      claim.statePath = found.statePath;
-      claim.worktree = found.worktree;
-      claim.createdWorktree = true;
-    }
-  }
+  trackRunState(claim);
   const waitedSec = Math.round((Date.now() - startedMs) / 1000);
   log(`${item.id}: supervision ended (${reason}) after ${waitedSec}s`);
-  return { reason, waitedSec };
+  return { reason, waitedSec, lastRow };
+}
+
+/**
+ * Hand a run that stopped to ask a person over from the claim to `running`.
+ *
+ * The claim is dropped because this supervisor is done: keeping it in
+ * runner.pid would hold every other repo for as long as nobody answers. The
+ * entry keeps what reconcileParked needs to settle it later, and keeps the
+ * repo occupied, since the session may resume and write to its worktree.
+ */
+function park(claim, item, outcome, pidPath) {
+  const q = readJson(join(ROOT, "queue.json"), { queued: [], running: [] });
+  writeState("queue.json", {
+    ...q,
+    running: (q.running || []).map((r) =>
+      r.id === item.id
+        ? {
+            ...r,
+            state: "parked",
+            outcome,
+            parkedAt: Math.floor(Date.now() / 1000),
+            source: item.source,
+            sessionId: claim.sessionId,
+            taskId: claim.taskId,
+            statePath: claim.statePath || null,
+            runTaskId: claim.runTaskId || null,
+            worktree: claim.worktree || null,
+          }
+        : r,
+    ),
+  });
+  rmSync(pidPath, { force: true });
+  refreshStatus();
+}
+
+/**
+ * The first queued item this tick may take: its repo is free and its checkout
+ * exists. An item whose checkout is missing is recorded as `blocked-no-path`
+ * once - not on every tick - and stepped over, so one moved directory does not
+ * hold the whole queue.
+ */
+function nextItem(queue, busyRepos, attempts) {
+  for (const i of queue.queued || []) {
+    if (busyRepos.has(i.repo)) continue;
+    if (i.localPath && existsSync(i.localPath)) return i;
+    const prev = attempts.findLast((a) => a.source === i.source && a.id === i.id);
+    log(`${i.id}: no checkout at ${i.localPath || "(none configured)"} - not launched`);
+    if (!DRY && prev?.outcome !== OUTCOME.BLOCKED_NO_PATH) {
+      record({ source: i.source, id: i.id, outcome: OUTCOME.BLOCKED_NO_PATH });
+    }
+  }
+  return null;
 }
 
-function main() {
+async function main() {
   const pidPath = join(ROOT, "runner.pid");
+  // An unattended run writes its state under the unattended run directory;
+  // every lookup below (findRunState, the cleanup report, publish) reads it
+  // there. An operator's own LOGS_ROOT is kept.
+  if (!process.env.LOGS_ROOT) process.env.LOGS_ROOT = unattendedLogsRoot();
 
   // ---- 1. RECOVER --------------------------------------------------------
   const holder = readJson(pidPath, null);
+  // A claim file that does not parse names no runner and no session. Left in
+  // place it would refuse every exclusive claim below, forever - but a young
+  // one may be a claim another tick is writing this moment, so it is removed
+  // only once it is older than that could take.
+  if (!holder && existsSync(pidPath)) {
+    let ageMs = Infinity;
+    try {
+      ageMs = Date.now() - statSync(pidPath).mtimeMs;
+    } catch {
+      // Gone between the check and the stat: nothing to remove.
+    }
+    if (ageMs < UNPARSEABLE_CLAIM_GRACE_MS) {
+      log("runner.pid does not parse yet - another tick may be writing it; nothing to do");
+      return 0;
+    }
+    if (!DRY) {
+      log("runner.pid does not parse - removing it");
+      rmSync(pidPath, { force: true });
+    }
+  }
   if (holder) {
     const liveness = holderLiveness(holder);
     if (liveness === "live") {
-      log(`another runner is live (pid ${holder.pid}) - nothing to do`);
+      if (pidAlive(holder.pid)) {
+        log(`another runner is live (pid ${holder.pid}) - nothing to do`);
+      } else {
+        log(`session ${holder.sessionId} is still running - it is retired once it ends`);
+      }
       return 0;
     }
     if (liveness === "unknown") {
@@ -565,7 +1843,7 @@ function main() {
     }
     log(`previous runner is gone (pid ${holder.pid}) - retiring its item`);
     if (!DRY) {
-      retire(holder);
+      await retire(holder);
       releaseSlot(holder.item && holder.item.id, pidPath);
     }
   }
@@ -575,8 +1853,31 @@ function main() {
     log("not configured on this machine - nothing to do");
     return 0;
   }
+  // The numbers in config.json are ceilings, and a value that is not a number
+  // compares false with everything. Nothing is taken or published until the
+  // config is corrected, and the queue says which field is wrong.
+  const refusal = configRefusal(config);
+  if (refusal) {
+    log(`${refusal} - nothing is taken until it is corrected`);
+    if (!DRY) {
+      writeState("queue.json", {
+        ...readJson(join(ROOT, "queue.json"), { queued: [], running: [] }),
+        blockedReason: refusal,
+      });
+      refreshStatus();
+    }
+    tick({ action: "config-invalid", reason: refusal });
+    return 0;
+  }
 
   rotateLog();
+  if (!DRY) rotateJsonl();
+  if (!DRY) ensureIndicator();
+  await reconcileParked();
+  if (!DRY) {
+    sweepInhibitor(ROOT, log);
+    dailyJobs(config);
+  }
 
   // ---- 1b. BREAKER -------------------------------------------------------
   // Three failures in a row is not three unlucky items, it is one broken
@@ -600,7 +1901,7 @@ function main() {
     // not, that probe fails, becomes the new most recent attempt, and the
     // breaker closes again for another cooldown. One wasted run per cooldown is
     // the price of not needing a human to notice.
-    const lastAt = attempts.length ? Number(attempts[attempts.length - 1].at || 0) : 0;
+    const lastAt = lastAttemptAt(attempts);
     const sinceSec = lastAt ? Math.floor(Date.now() / 1000) - lastAt : Infinity;
     const probeDue = sinceSec >= BREAKER_COOLDOWN_SEC;
     if (!probeDue) {
@@ -630,25 +1931,73 @@ function main() {
     tick({ action: "breaker-probe", failures: breaker.count, lastOutcome: breaker.last });
   }
 
+  // ---- 1c. RATE LIMIT ----------------------------------------------------
+  // The limit is the account's, so the next item would hit it too. Waiting it
+  // out costs nothing; a queue that keeps launching into it records one wasted
+  // attempt per item until every item is past its ceiling.
+  const limited = rateLimitBackoff(attempts);
+  if (limited) {
+    const waitMin = Math.ceil(limited.remainingSec / 60);
+    const reason = messages(RATE_LIMITED_MSG, outputLanguage())(waitMin);
+    log(reason);
+    if (!DRY) {
+      writeState("queue.json", {
+        ...readJson(join(ROOT, "queue.json"), { queued: [], running: [] }),
+        blockedReason: reason,
+      });
+      refreshStatus();
+    }
+    tick({ action: "rate-limit-backoff", limits: limited.count, retryInSec: limited.remainingSec });
+    return 0;
+  }
+
   // ---- 2. INTAKE ---------------------------------------------------------
   const intake = join(SCRIPTS, "autopilot-intake.mjs");
   if (existsSync(intake)) run(process.execPath, [intake]);
   const queue = readJson(join(ROOT, "queue.json"), { queued: [], running: [] });
 
   const running = queue.running || [];
+  // A parked run holds its repo but not a slot: it is waiting for a person,
+  // not working, and counting it would let one unanswered question stop the
+  // queue for as long as nobody answers.
+  const active = running.filter((r) => r.state !== "parked");
   const slots = Number(config.slots ?? 1);
-  if (running.length >= slots) {
-    log(`${running.length}/${slots} slots in use - nothing to take`);
-    tick({ action: "slots-full", running: running.length, slots });
+  if (active.length >= slots) {
+    log(`${active.length}/${slots} slots in use - nothing to take`);
+    tick({ action: "slots-full", running: active.length, slots });
     return 0;
   }
 
+  // ---- 2b. PARALLEL CAP ---------------------------------------------------
+  // A ceiling, never a raise: unset keeps exactly the behaviour above. When set,
+  // it also counts parked runs whose session is working again after a person
+  // answered, which `slots` deliberately does not. An agent list that cannot be
+  // read is not zero: under a cap, nothing is taken until it can be.
+  const cap = parallelCap(config);
+  if (cap !== null) {
+    const hasParked = running.some((r) => r.state === "parked");
+    const inFlight = agentsInFlight(
+      running,
+      hasParked ? run(CLAUDE_BIN, ["agents", "--json"]) : "[]",
+    );
+    if (inFlight === undefined) {
+      log("cannot read the agent list - no item is taken under maxParallelAgents");
+      tick({ action: "parallel-cap-unknown", cap });
+      return 0;
+    }
+    if (inFlight >= cap) {
+      log(`${inFlight}/${cap} agent(s) in flight (maxParallelAgents) - nothing to take`);
+      tick({ action: "parallel-cap", inFlight, cap });
+      return 0;
+    }
+  }
+
   // Per-repo concurrency is always 1, whatever `slots` says: two runs in one
   // checkout contend on .git/index.lock, and that is a named failure rather
   // than a slow path. It also means the queue steps around a repo YOU are
   // working in instead of competing with you for it.
   const busyRepos = new Set(running.map((r) => r.repo));
-  const next = (queue.queued || []).find((i) => !busyRepos.has(i.repo));
+  const next = nextItem(queue, busyRepos, attempts);
   if (!next) {
     log(queue.emptyReason || "every queued item belongs to a repo already in flight");
     tick({
@@ -662,12 +2011,33 @@ function main() {
   // ---- 3. ARM ------------------------------------------------------------
   const armScript = join(SCRIPTS, "autopilot-arming.mjs");
   if (existsSync(armScript)) {
-    const out = run(process.execPath, [armScript, "check", "--source", next.source, "--json"]);
+    // --probe: the item's credential must be readable from THIS session, the
+    // background one, where a keychain that locked on sleep answers differently
+    // from the terminal that armed the mode. --repo adds the credential its
+    // repo publishes with (gh for a GitHub host), which the publish step needs
+    // after the run has been paid for.
+    const out = run(process.execPath, [
+      armScript,
+      "check",
+      "--source",
+      next.source,
+      "--repo",
+      next.repo,
+      "--probe",
+      "--json",
+    ]);
     const arm = (() => {
       try {
         return JSON.parse(out);
       } catch {
-        return { armed: true };
+        // No verdict is not a yes. The check it stands in for is a spend
+        // ceiling and a credential gate, and reading silence as "armed" hands
+        // the queue the one answer that costs money.
+        return {
+          armed: false,
+          blockedBy: "internal",
+          reason: messages(ARM_UNREADABLE, outputLanguage()),
+        };
       }
     })();
     if (!arm.armed) {
@@ -681,6 +2051,41 @@ function main() {
     }
   }
 
+  // ---- 3b. GUARD ----------------------------------------------------------
+  // The unattended contract rests on agent-guard.sh running as the child's
+  // PreToolUse hook: it is what blocks a push, a PR, an install or a write into
+  // a protected path. A child launched without it would hold every outward
+  // write the runner is meant to be the only source of.
+  const guard = guardRegistration({ cwd: next.localPath });
+  if (!guard.ok) {
+    log(
+      `not launching: ${guard.reason} (install registers it; see features/unattended-security.md)`,
+    );
+    if (!DRY) {
+      record({ source: next.source, id: next.id, outcome: OUTCOME.BLOCKED_GUARD_MISSING });
+      writeState("queue.json", { ...queue, blockedReason: guard.reason });
+      refreshStatus();
+    }
+    tick({ action: "guard-missing", missing: guard.missing });
+    return 0;
+  }
+
+  // ---- 3c. SANDBOX --------------------------------------------------------
+  // The OS sandbox in the profile file is the boundary for everything the
+  // child runs from Bash. Without it, or with a checkout whose own settings
+  // widen it, there is no launch.
+  const sandbox = sandboxPrecondition({ cwd: next.localPath });
+  if (!sandbox.ok) {
+    log(`not launching: ${sandbox.reason} (see features/unattended-security.md)`);
+    if (!DRY) {
+      record({ source: next.source, id: next.id, outcome: OUTCOME.BLOCKED_SANDBOX_UNAVAILABLE });
+      writeState("queue.json", { ...queue, blockedReason: sandbox.reason });
+      refreshStatus();
+    }
+    tick({ action: "sandbox-unavailable" });
+    return 0;
+  }
+
   // ---- 4. TAKE -----------------------------------------------------------
   const sessionId = randomUUID();
   const taskId = `ap-${Date.now()}`;
@@ -691,6 +2096,7 @@ function main() {
     taskId,
     item: next,
     repoPath: next.localPath,
+    baseSha: headSha(next.localPath),
     startedAt: Math.floor(Date.now() / 1000),
   };
 
@@ -699,7 +2105,14 @@ function main() {
     return 0;
   }
 
-  writeState("runner.pid", claim);
+  // Exclusive create: two ticks that both passed RECOVER race here, and the
+  // loser leaves before touching the queue or launching anything.
+  ensureRoot();
+  if (!claimExclusive(pidPath, claim)) {
+    log("another tick claimed first - nothing to do");
+    return 0;
+  }
+  chmodSync(pidPath, 0o600);
   writeState("queue.json", {
     ...queue,
     running: [
@@ -707,11 +2120,12 @@ function main() {
       {
         id: next.id,
         repo: next.repo,
-        depth: config.depthRouter === "auto" ? undefined : "full",
         stack: next.stack,
         startedAt: claim.startedAt,
         state: "running",
         url: next.url,
+        sessionId,
+        taskId,
       },
     ],
     queued: (queue.queued || []).filter((i) => i.id !== next.id),
@@ -719,86 +2133,128 @@ function main() {
   refreshStatus();
 
   // ---- 5. RUN ------------------------------------------------------------
-  // The child is a normal pipeline run in the mode that already exists: one
-  // item, unattended, stopping at an open PR. Nothing about the per-item
-  // `autopilot` mode changes because a queue is calling it.
-  log(`running ${next.source}:${next.id}`);
-  const child = spawnSync(
-    CLAUDE_BIN,
-    [
-      "--bg",
-      "--session-id",
-      sessionId,
-      "--permission-prompts",
-      "none",
-      "-p",
-      `/multi-agent ${next.ref || next.id} autopilot`,
-    ],
-    { cwd: next.localPath || process.cwd(), encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] },
-  );
-  if (child.status !== 0) {
-    const why = (child.stderr || child.error?.message || "").trim().slice(0, 300);
-    record({ source: next.source, id: next.id, taskId, outcome: "launch-failed", note: why });
-    releaseSlot(next.id, pidPath, queue);
-    log(`${next.id}: launch-failed ${why}`);
-    return 0;
-  }
+  // The sleep inhibitor covers the session and everything after it in this
+  // tick - research, resume, publish - and is released on every way out.
+  const sleepLock = holdSleep({ root: ROOT, log });
+  try {
+    // The child is a normal pipeline run in the mode that already exists: one
+    // item, unattended, stopping at an open PR. Nothing about the per-item
+    // `autopilot` mode changes because a queue is calling it.
+    log(`running ${next.source}:${next.id}`);
+    const child = launch(launchArgv(next, sessionId), next.localPath, sessionId, claim.baseSha);
+    if (child.status !== 0) {
+      const why = (child.stderr || child.error?.message || "").trim().slice(0, 300);
+      // Nothing ran, so nothing was spent: 0 here is a measurement, not a guess.
+      record({
+        source: next.source,
+        id: next.id,
+        taskId,
+        outcome: OUTCOME.LAUNCH_FAILED,
+        note: why,
+        usd: 0,
+      });
+      releaseSlot(next.id, pidPath, queue);
+      log(`${next.id}: launch-failed ${why}`);
+      return 0;
+    }
 
-  // ---- 5b. SUPERVISE -----------------------------------------------------
-  // `claude --bg` returns as soon as the session is started - `claude --help`
-  // says so in as many words. The spawn above therefore proves only that a run
-  // BEGAN. Everything below used to run immediately after it: the outcome was
-  // recorded as "pr-opened" before any work happened, the slot was freed within
-  // a second, and the per-repo guard three steps up became decorative because
-  // `running` was already empty when the next tick read it.
-  const supervised = supervise(sessionId, claim, next);
-
-  // ---- 6. RECORD ---------------------------------------------------------
-  // From the run's own state file, not from the child's exit code and not from
-  // its stdout - with `--bg` the stdout is a session id, so the PR regex that
-  // used to read it could never match.
-  const finalState = claim.statePath ? readJson(claim.statePath, null) : null;
-  const prUrl = prFromState(finalState);
-  const outcome = outcomeFor(supervised, finalState, prUrl);
-  record({
-    source: next.source,
-    id: next.id,
-    taskId,
-    outcome,
-    prUrl,
-    waitedSec: supervised.waitedSec,
-    usd: 0,
-  });
+    // ---- 5b. SUPERVISE -----------------------------------------------------
+    // `claude --bg` returns as soon as the session is started - `claude --help`
+    // says so in as many words. The spawn above therefore proves only that a run
+    // BEGAN; recording or releasing anything before the run ends would free the
+    // slot within a second and leave the per-repo guard with nothing to guard.
+    const firstRun = supervise(sessionId, claim, next);
+    const firstState = claim.statePath ? readJson(claim.statePath, null) : null;
 
-  // "gone" and "finished" are the two reasons that mean the run ENDED. The
-  // other three - a ceiling, an unreadable list, a session parked on a question
-  // - say only that waiting stopped, and the run may still hold its worktree.
-  // Deleting the claim there would strand it: the worktree and state path this
-  // tick just learned are the only record, and the next tick would take another
-  // item in the same repo. Keeping it means the next tick's RECOVER decides,
-  // with retire() free to clean up and releaseSlot to free the slot.
-  if (supervised.reason === "gone" || supervised.reason === "finished") {
-    releaseSlot(next.id, pidPath, queue);
-  } else {
-    log(`${next.id}: claim kept for the next tick (${supervised.reason})`);
-  }
-  log(`${next.id}: ${outcome}${prUrl ? ` ${prUrl}` : ""} (${supervised.waitedSec}s)`);
-  tick({
-    action: "ran",
-    source: next.source,
-    id: next.id,
-    taskId,
-    outcome,
-    reason: supervised.reason,
-    waitedSec: supervised.waitedSec,
-    prOpened: Boolean(prUrl),
-    consecutiveFailuresBefore: breaker.count,
-  });
-  return 0;
+    // ---- 5c. RESEARCH ------------------------------------------------------
+    // A run parked on a gap research can act on gets its rounds here, while the
+    // item is still claimed, so no other tick can take it in between.
+    const {
+      supervised,
+      state: finalState,
+      prUrl,
+      rounds,
+    } = researchRounds(
+      claim,
+      next,
+      { supervised: firstRun, state: firstState, prUrl: prFromState(firstState) },
+      {
+        // The ceiling spans every run of the item, so the whole log is read,
+        // not the tail the breaker looks at.
+        roundsUsed: researchRoundsUsed(readAllAttempted(), next),
+        maxAskRounds: Number(config.maxAskRounds ?? 2),
+      },
+    );
+
+    // ---- 5d. PUBLISH -------------------------------------------------------
+    // A session that ended at the Phase 4 hand-off left a PR request; the runner
+    // verifies it and is the one that pushes and opens the PR. A session that
+    // may still be running (a ceiling, an unreadable list) is not published
+    // from: the next tick's RECOVER does that once the session is gone.
+    let pub = { outcome: null };
+    let stateNow = finalState;
+    let prNow = prUrl;
+    if (!prUrl && ENDED.has(supervised.reason)) {
+      pub = await publishStep(claim.sessionId, claim.statePath, next);
+      if (pub.outcome) {
+        stateNow = claim.statePath ? readJson(claim.statePath, finalState) : finalState;
+        prNow = pub.prUrl || prFromState(stateNow);
+      }
+    }
+
+    // ---- 6. RECORD ---------------------------------------------------------
+    // From the run's own state file, not from the child's exit code and not from
+    // its stdout - with `--bg` the stdout is a session id and nothing else.
+    const outcome = pub.outcome || outcomeFor(supervised, stateNow, prNow);
+    record({
+      source: next.source,
+      id: next.id,
+      taskId,
+      outcome,
+      prUrl: prNow,
+      waitedSec: supervised.waitedSec,
+      usd: runUsd(claim.runTaskId, claim.statePath),
+      ...(rounds ? { researchRounds: rounds } : {}),
+      ...publishGateOf(pub),
+    });
+
+    // A delivered run releases its slot whatever its session is doing - Phase 5
+    // can hold for input after the PR is open, and the item is finished with us.
+    // A run parked on a question moves to `running` as parked, see park().
+    // Otherwise "gone" and "finished" are the two reasons that mean the run
+    // ENDED. The rest - a ceiling, an unreadable list - say only that waiting
+    // stopped, and the run may still hold its worktree. Deleting the claim there
+    // would strand it: the worktree and state path this tick just learned are
+    // the only record, and the next tick would take another item in the same
+    // repo. Keeping it means the next tick's RECOVER decides, by the session.
+    if (isTerminal(outcome) || supervised.reason === "gone" || supervised.reason === "finished") {
+      releaseSlot(next.id, pidPath, queue);
+    } else if (isParked(outcome)) {
+      park(claim, next, outcome, pidPath);
+      log(`${next.id}: parked (${outcome}) - the repo stays held until its session ends`);
+    } else {
+      log(`${next.id}: claim kept for the next tick (${supervised.reason})`);
+    }
+    log(`${next.id}: ${outcome}${prNow ? ` ${prNow}` : ""} (${supervised.waitedSec}s)`);
+    tick({
+      action: "ran",
+      source: next.source,
+      id: next.id,
+      taskId,
+      outcome,
+      reason: supervised.reason,
+      waitedSec: supervised.waitedSec,
+      prOpened: Boolean(prNow),
+      consecutiveFailuresBefore: breaker.count,
+    });
+    return 0;
+  } finally {
+    sleepLock.release();
+  }
 }
 
 if (invokedDirectly(import.meta.url)) {
-  runMain("autopilot-runner", () => {
-    process.exit(main());
+  runMain("autopilot-runner", async () => {
+    process.exit(await main());
   });
 }