omp-conductor 0.3.18 → 0.3.20

package/src/daemon.ts

@@ -10,34 +10,41 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
-import { configPath, findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
+import { configPath, findProject, loadConfig, resolveCaps, resolveReleasePolicy, stateDir } from "./config.ts";
 import { createEscalator, escalationIssueRef } from "./escalate.ts";
+import { pendingCodeGraph, probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
 import { graphHint } from "./graph.ts";
 import { livingDaemon } from "./lifecycle.ts";
 import { STALL_MARKER_FILE } from "./orchestrator-tick.ts";
 import { startOrchestrator } from "./orchestrator.ts";
 import type { OrchestratorHandle } from "./orchestrator.ts";
+import { recordReleaseBlock } from "./release-policy.ts";
 import { branchName, route } from "./routing.ts";
 import type { Routed, UnroutableReason } from "./routing.ts";
-import { openStore } from "./store.ts";
+import { dbPath, openStore } from "./store.ts";
 import { makeTracker } from "./tracker/github.ts";
 import type {
+  AdmissionHoldReason,
   Caps,
+  DispatchSummary,
   Escalation,
   PrState,
   ProjectConfig,
   ReadyIssue,
   RepoTarget,
   RunRecord,
+  RunState,
   Store,
   Tracker,
 } from "./types.ts";
-import { type KilledBy, renderBrief, runWorker } from "./worker.ts";
+import { type KilledBy, type WorkerResult, renderBrief, runWorker } from "./worker.ts";
 import {
   addWorktree,
+  cleanupRetainedWorktree,
   mirrorPathFor,
   removeWorktree,
   salvageWip,
+  type RetainedWorktreeCleanup,
   type SalvageOutcome,
   worktreePathFor,
 } from "./worktree.ts";
@@ -45,6 +52,7 @@ import {
 /** Long enough that the tracker is not polled raw, short enough that a human
  *  who labels an issue sees it picked up within a coffee break. */
 const TICK_INTERVAL_MS = 5 * 60_000;
+const GRAPH_HEALTH_INTERVAL_MS = 60_000;
 const DEFAULT_PORT = 8787;
 const BRIEF_TEMPLATE_PATH = join(import.meta.dir, "briefs", "worker.md");
 
@@ -72,16 +80,14 @@ interface Deps {
   tracker: Tracker;
   store: Store;
   escalate(e: Escalation): Promise<void>;
+  turnLimits: TurnLimitRegistry;
   integrity: IntegrityGate;
   stall: StallGate;
+  cleanup?: RetainedCleanupCursor;
 }
 
 // ---------------------------------------------------------------- paths & pause
 
-/** Single database for every project; the store partitions by project name. */
-export function dbPath(): string {
-  return join(stateDir(), "conductor.db");
-}
 
 // ------------------------------------------------------- orchestrator liveness
 
@@ -501,6 +507,85 @@ export async function buildBrief(
 
 // ------------------------------------------------------------------- one issue
 
+/** `stops` are the operational ends that each require one resume. */
+export function hasContinuationBudget(stops: number, maxContinuations: number): boolean {
+  return stops <= maxContinuations;
+}
+
+export type ExtendTurnLimitResult =
+  | { kind: "extended"; runId: string; maxTurns: number }
+  | { kind: "not-increase"; runId: string; maxTurns: number }
+  | { kind: "not-active" };
+
+export interface TurnLimitController {
+  maxTurns(): number;
+  close(): void;
+}
+
+export interface TurnLimitRegistry {
+  open(project: string, issue: number, runId: string, maxTurns: number): TurnLimitController;
+  extend(project: string, issue: number, maxTurns: number): ExtendTurnLimitResult;
+}
+
+/**
+ * Authoritative live-run turn controls. Persistence happens synchronously
+ * before the in-memory ceiling changes, so no turn event can interleave.
+ */
+export function createTurnLimitRegistry(
+  persist: (runId: string, maxTurns: number) => void,
+): TurnLimitRegistry {
+  const active = new Map<string, { runId: string; maxTurns: number }>();
+  const key = (project: string, issue: number): string => `${project}\0${issue}`;
+  return {
+    open(project, issue, runId, maxTurns) {
+      const k = key(project, issue);
+      if (active.has(k)) throw new Error(`#${issue} already has a live turn controller`);
+      const entry = { runId, maxTurns };
+      active.set(k, entry);
+      return {
+        maxTurns: () => entry.maxTurns,
+        close: () => {
+          if (active.get(k) === entry) active.delete(k);
+        },
+      };
+    },
+    extend(project, issue, maxTurns) {
+      if (!Number.isSafeInteger(maxTurns) || maxTurns < 1) {
+        throw new RangeError(`turn ceiling must be a positive integer, got ${maxTurns}`);
+      }
+      const entry = active.get(key(project, issue));
+      if (entry === undefined) return { kind: "not-active" };
+      if (maxTurns <= entry.maxTurns) {
+        return { kind: "not-increase", runId: entry.runId, maxTurns: entry.maxTurns };
+      }
+      persist(entry.runId, maxTurns);
+      entry.maxTurns = maxTurns;
+      return { kind: "extended", runId: entry.runId, maxTurns };
+    },
+  };
+}
+
+export async function verifyPushedGreenClaim(
+  tracker: Pick<Tracker, "verifyPr">,
+  claim: Pick<WorkerResult, "prUrl" | "headSha">,
+): Promise<{
+  state: "pushed-green" | "pushed-pending" | "failed";
+  reason?: string;
+}> {
+  if (claim.prUrl === undefined || claim.headSha === undefined) {
+    return { state: "failed", reason: "Worker did not report a PR URL and observed head SHA" };
+  }
+  const verification = await tracker.verifyPr(claim.prUrl, claim.headSha);
+  if (verification === undefined) {
+    return { state: "pushed-pending", reason: "GitHub PR verification unavailable; retrying" };
+  }
+  if (verification.status === "green") return { state: "pushed-green" };
+  return {
+    state: verification.status === "pending" ? "pushed-pending" : "failed",
+    reason: verification.reason,
+  };
+}
+
 /**
  * One attempt at one issue, from claim to terminal state. Everything is inside
  * a single try/catch so that a bad issue costs its own run and nothing else.
@@ -517,6 +602,7 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
   // mid-dispatch is one of the non-graceful ends whose uncommitted work has to
   // be salvaged too, and it is the path least likely to have committed first.
   let worktreePath: string | undefined;
+  let turnLimit: TurnLimitController | undefined;
 
   try {
     // Claim on the tracker FIRST, before any local work. The label — not the
@@ -536,9 +622,11 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       attempt,
       turns: 0,
       spendUsd: 0,
+      maxTurns: caps.workerMaxTurns,
       startedAt: Date.now(),
     });
     const runId = run.id;
+    turnLimit = d.turnLimits.open(project.name, issue, runId, caps.workerMaxTurns);
 
     // A run's tree is <workspaceRoot>/<issue> and addWorktree refuses to reuse
     // an existing path, so a retry — or a tree kept from a failed attempt — has
@@ -569,22 +657,38 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         (provisioned.reattached ? " (continuation: reattached existing branch)" : ""),
     );
 
-    const result = await runWorker({
-      brief: await buildBrief(project, r, branch, worktreePath, {
-        continuation: provisioned.reattached,
-        defaultBranch: r.repo.defaultBranch,
-      }),
-      cwd: worktreePath,
-      caps,
-      sessionDir,
-      ...(project.workerModel === undefined ? {} : { model: project.workerModel }),
-      onTurn: (n) => store.updateRun(runId, { turns: n }),
-      // Recorded the moment the session opens its transcript, not when the run
-      // ends: `omp-conductor tail` resolves an issue to a file through this row,
-      // and a path written at completion is a path nobody can follow live. The
-      // completion-time update below writes the same value again, harmlessly.
-      onSessionFile: (f) => store.updateRun(runId, { sessionFile: f }),
-    });
+    let result: WorkerResult;
+    try {
+      result = await runWorker({
+        brief: await buildBrief(project, r, branch, worktreePath, {
+          continuation: provisioned.reattached,
+          defaultBranch: r.repo.defaultBranch,
+        }),
+        cwd: worktreePath,
+        caps,
+        maxTurns: () => turnLimit?.maxTurns() ?? caps.workerMaxTurns,
+        sessionDir,
+        ...(project.workerModel === undefined ? {} : { model: project.workerModel }),
+        releasePolicy: resolveReleasePolicy(project),
+        onReleaseBlocked: (shape) => recordReleaseBlock(project.name, "worker", shape),
+        onTurn: (n) => store.updateRun(runId, { turns: n }),
+        onSpend: (usd) => store.updateRun(runId, { spendUsd: usd }),
+        onKilled: () => {
+          turnLimit?.close();
+          turnLimit = undefined;
+        },
+        // Recorded the moment the session opens its transcript, not when the run
+        // ends: `omp-conductor tail` resolves an issue to a file through this row,
+        // and a path written at completion is a path nobody can follow live. The
+        // completion-time update below writes the same value again, harmlessly.
+        onSessionFile: (f) => store.updateRun(runId, { sessionFile: f }),
+      });
+    } finally {
+      // This is the authoritative settlement edge for `extend`: close before
+      // PR verification or terminal row writes can leave stale `running` state.
+      turnLimit?.close();
+      turnLimit = undefined;
+    }
 
     // A configured model the harness could not honour means this run was done by
     // a different model than the operator chose. Logged per run, because it is
@@ -593,16 +697,26 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       log(`#${issue} model fallback: ${result.modelFallbackMessage}`);
     }
 
+    const verified: { state: RunState; reason?: string } =
+      result.state === "pushed-green"
+        ? await verifyPushedGreenClaim(tracker, result)
+        : { state: result.state };
+    const state = verified.state;
+    const finalReport =
+      verified.reason === undefined ? result.report : `${verified.reason}\n\n${result.report}`;
+
     store.updateRun(runId, {
-      state: result.state,
+      state,
       endedAt: Date.now(),
       turns: result.turns,
       spendUsd: result.spendUsd,
       prUrl: result.prUrl,
+      headSha: result.headSha,
       sessionFile: result.sessionFile,
+      ...(verified.reason === undefined ? {} : { lastError: verified.reason }),
     });
 
-    if (result.state === "blocked") {
+    if (state === "blocked") {
       await swapLabel(tracker, issue, inProgress, project.stateLabels.blocked);
       await safeEscalate(d, {
         tier: 1,
@@ -612,20 +726,22 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         summary: `#${issue} is blocked on attempt ${attempt} and needs a decision`,
         detail: [`${r.issue.title}`, r.issue.url, "", result.report].join("\n"),
       });
-    } else if (result.state === "failed" || result.state === "killed") {
-      // Turns-cap with attempts left: salvage, put the issue back on the queue,
-      // and skip the failed label so the next tick reclaims as a continuation
-      // instead of burning a human triage cycle (#50 / #21).
+    } else if (state === "failed" || state === "killed") {
+      // A turns cap consumes the independent continuation budget, not an
+      // implementation-failure attempt. The row is already `killed`, so this
+      // count includes the segment that just ended.
+      const continuation = store.continuationsFor(project.name, issue);
       const continueTurns =
-        result.killedBy === "turns" && attempt < caps.maxAttemptsPerIssue;
+        result.killedBy === "turns" &&
+        hasContinuationBudget(continuation, caps.maxContinuationsPerIssue);
       const salvaged = await salvage(issue, attempt, endedBy(result.killedBy), worktreePath);
 
       if (continueTurns) {
         await tracker.removeLabel(issue, inProgress);
         await tracker.addLabel(issue, project.queueLabel);
         log(
-          `#${issue} turns-cap on attempt ${attempt}/${caps.maxAttemptsPerIssue} — ` +
-            `salvaged and re-queued for continuation`,
+          `#${issue} turns-cap on run ${attempt}, continuation ` +
+            `${continuation}/${caps.maxContinuationsPerIssue} — salvaged and re-queued`,
         );
         await safeEscalate(d, {
           tier: 1,
@@ -664,24 +780,27 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
             ...salvaged,
             `Session: ${result.sessionFile ?? "(no transcript)"}`,
             "",
-            result.report,
+            finalReport,
           ].join("\n"),
         });
       }
     } else {
-      // pushed-green: the PR belongs to a human now. The in-progress label
-      // stays on until the merge closes the issue, which is also what keeps
-      // the next tick from re-claiming it.
-      log(`#${issue} ${result.state}${result.prUrl ? ` ${result.prUrl}` : ""}`);
+      // A verified or still-pending PR keeps the in-progress label until its
+      // checks or merge settle, preventing another worker from duplicating it.
+      log(`#${issue} ${state}${result.prUrl ? ` ${result.prUrl}` : ""}`);
     }
 
     // A failed or killed tree is evidence — keep it. Anything else is just
     // disk, and the mirror means re-provisioning is cheap. (The kept tree is
     // wiped by the next attempt, not left to accumulate forever.)
-    if (result.state !== "failed" && result.state !== "killed") {
+    if (state !== "failed" && state !== "killed") {
       await removeWorktree(mirrorPath, worktreePath);
     }
   } catch (err) {
+    // Dispatch setup can fail after the controller opens but before runWorker's
+    // inner settlement guard exists. Latch it before any terminal write or await.
+    turnLimit?.close();
+    turnLimit = undefined;
     const detail = errText(err);
     log(`#${issue} errored: ${detail}`);
     if (run) {
@@ -713,6 +832,8 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
     });
     // The worktree, if one was created, is deliberately left in place: this is
     // a failure path, and whatever it still held is now a commit on the branch.
+  } finally {
+    turnLimit?.close();
   }
 }
 
@@ -782,12 +903,13 @@ export async function settlePushedGreen(
   // is live workers plus these, so the list is bounded by the worker cap plus
   // the number of PRs awaiting a merge — a handful, by construction. A fleet
   // where that is not a handful has a merge problem, not a dispatch one.
-  const pending = store.activeRuns(project.name).filter((r) => r.state === "pushed-green");
+  const pending = store
+    .activeRuns(project.name)
+    .filter((r) => r.state === "pushed-green" || r.state === "pushed-pending");
 
   for (const run of pending) {
-    // Nothing to ask about. A green push means a PR, so this row should not
-    // exist; if one ever does, it must not buy a `gh` call every five minutes
-    // forever to be told nothing.
+    // Nothing to ask about. A pushed result requires a PR, so a malformed row
+    // must not buy a `gh` call every five minutes forever.
     if (run.prUrl === undefined) continue;
 
     let pr: PrState | undefined;
@@ -803,12 +925,123 @@ export async function settlePushedGreen(
     }
 
     const settlement = settlementFor(pr, run.prUrl);
-    if (settlement === undefined) continue;
+    if (settlement !== undefined) {
+      const patch: Partial<RunRecord> = { state: settlement.state, endedAt: Date.now() };
+      if (settlement.state === "failed") patch.lastError = settlement.reason;
+      store.updateRun(run.id, patch);
+      log(`#${run.issue} settled: ${settlement.reason}`);
+      continue;
+    }
+
+    if (run.state !== "pushed-pending" || pr !== "open" || run.headSha === undefined) continue;
+    let verification;
+    try {
+      verification = await tracker.verifyPr(run.prUrl, run.headSha);
+    } catch (err) {
+      log(`#${run.issue} checks not settled (${errText(err)}) — retrying next tick`);
+      continue;
+    }
+    if (verification === undefined) continue;
+    if (verification.status === "green") {
+      store.updateRun(run.id, { state: "pushed-green", lastError: undefined });
+      log(`#${run.issue} checks settled: ${verification.reason}`);
+    } else if (verification.status === "failed") {
+      store.updateRun(run.id, { state: "failed", lastError: verification.reason });
+      log(`#${run.issue} checks failed: ${verification.reason}`);
+    } else {
+      store.updateRun(run.id, { lastError: verification.reason });
+    }
+  }
+}
+
+const RETAINED_CLEANUP_BATCH = 10;
+
+export interface RetainedCleanupCursor {
+  next: number;
+}
+
+type CleanupRetainedWorktree = (
+  mirrorPath: string,
+  worktreePath: string,
+  branch: string,
+) => Promise<RetainedWorktreeCleanup>;
+
+/**
+ * Bounded, rotating cleanup for failure-path trees. Tracker state proves the
+ * run is terminal; local git state independently proves deletion cannot erase
+ * dirty or uniquely unpushed work.
+ */
+export async function cleanupRetainedRuns(
+  d: Pick<Deps, "project" | "tracker" | "store">,
+  queuedIssues: ReadonlySet<number>,
+  cursor: RetainedCleanupCursor,
+  cleanup: CleanupRetainedWorktree = cleanupRetainedWorktree,
+): Promise<void> {
+  const { project, tracker, store } = d;
+  const candidates = store.retainedRuns(project.name);
+  if (candidates.length === 0) {
+    cursor.next = 0;
+    return;
+  }
+
+  const occupied = new Set(store.activeRuns(project.name).map((run) => run.issue));
+  const liveRepos = new Set(store.liveRuns(project.name).map((run) => run.repo));
+  const start = cursor.next % candidates.length;
+  const count = Math.min(RETAINED_CLEANUP_BATCH, candidates.length);
+  const batch = Array.from({ length: count }, (_, offset) => candidates[(start + offset) % candidates.length]!);
+  cursor.next = (start + count) % candidates.length;
+
+  for (const run of batch) {
+    if (occupied.has(run.issue) || queuedIssues.has(run.issue) || liveRepos.has(run.repo)) continue;
+    // Attempts reuse one physical path and deterministic branch. An older row
+    // cannot authorize deleting the newest failed attempt's evidence merely
+    // because its own PR resolved first.
+    const latest = store.latestRun(project.name, run.issue);
+    if (
+      latest !== undefined &&
+      latest.id !== run.id &&
+      latest.state !== "merged" &&
+      latest.worktree !== ""
+    ) {
+      continue;
+    }
 
-    const patch: Partial<RunRecord> = { state: settlement.state, endedAt: Date.now() };
-    if (settlement.state === "failed") patch.lastError = settlement.reason;
-    store.updateRun(run.id, patch);
-    log(`#${run.issue} settled: ${settlement.reason}`);
+    let terminal = false;
+    try {
+      if (run.prUrl !== undefined) {
+        const pr = await tracker.prState(run.prUrl);
+        if (pr === undefined) continue;
+        if (pr === "merged" || pr === "closed") {
+          terminal = true;
+        } else {
+          const issue = await tracker.issueState(run.issue);
+          if (issue === undefined) continue;
+          terminal = issue === "closed";
+        }
+      } else {
+        const issue = await tracker.issueState(run.issue);
+        if (issue === undefined) continue;
+        terminal = issue === "closed";
+      }
+    } catch (err) {
+      log(`#${run.issue} retained cleanup deferred: tracker state failed (${errText(err)})`);
+      continue;
+    }
+    if (!terminal) continue;
+
+    const repo = Object.values(project.routing.repos).find((candidate) => candidate.name === run.repo);
+    if (repo === undefined) {
+      log(`#${run.issue} retained cleanup deferred: repo ${run.repo} is no longer configured`);
+      continue;
+    }
+
+    const outcome = await cleanup(mirrorPathFor(repo, project.mirrorRoot), run.worktree, run.branch);
+    if (outcome.kind === "removed") {
+      store.updateRun(run.id, { worktree: "" });
+      log(`#${run.issue} retained worktree reaped: ${run.worktree} (${run.branch})`);
+    } else {
+      log(`#${run.issue} retained worktree kept (${outcome.reason}): ${outcome.detail}`);
+    }
   }
 }
 
@@ -820,9 +1053,52 @@ export interface Admission {
   attempt: number;
 }
 
+export interface AdmissionHold {
+  issue: number;
+  reason: AdmissionHoldReason;
+}
+
+export interface AdmissionPass {
+  admitted: Admission[];
+  holds: AdmissionHold[];
+}
+
+const HOLD_SAMPLE_SIZE = 5;
+const DEGRADED_HOLDS: ReadonlySet<AdmissionHoldReason> = new Set([
+  "parent-lookup-error",
+  "open-pr-lookup-error",
+]);
+
+/** Groups transient decisions into the bounded record exposed by status. */
+export function summarizeDispatch(
+  ready: number,
+  routed: number,
+  admitted: number,
+  holds: readonly AdmissionHold[],
+  completedAt = Date.now(),
+): DispatchSummary {
+  const groups = new Map<AdmissionHoldReason, { count: number; issues: number[] }>();
+  for (const hold of holds) {
+    const group = groups.get(hold.reason) ?? { count: 0, issues: [] };
+    group.count += 1;
+    if (group.issues.length < HOLD_SAMPLE_SIZE) group.issues.push(hold.issue);
+    groups.set(hold.reason, group);
+  }
+  return {
+    completedAt,
+    ready,
+    routed,
+    admitted,
+    degraded: holds.some((hold) => DEGRADED_HOLDS.has(hold.reason)),
+    holds: [...groups]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([reason, group]) => ({ reason, ...group })),
+  };
+}
+
 /**
  * Which routed candidates get a worker this tick — in queue order, never more
- * than `slots` of them.
+ * than `slots` of them. Every non-admission receives a stable reason code.
  *
  * Exported so the admission rules can be pinned without spawning a worker.
  * Every one of them exists because of a live incident, and each guards a
@@ -837,10 +1113,14 @@ export async function admitCandidates(
   d: Pick<Deps, "project" | "caps" | "tracker" | "store" | "escalate">,
   routed: Routed[],
   slots: number,
-): Promise<Admission[]> {
+): Promise<AdmissionPass> {
   const { project, caps, tracker, store } = d;
   const busyIssues = store.activeRuns(project.name).map((r) => r.issue);
   const busy = new Set(busyIssues);
+  const holds: AdmissionHold[] = [];
+  const hold = (issue: number, reason: AdmissionHoldReason): void => {
+    holds.push({ issue, reason });
+  };
 
   // parent -> blocking issue. Seeded from active runs (including pushed-green),
   // then extended by candidates admitted earlier in this same pass so two
@@ -870,43 +1150,69 @@ export async function admitCandidates(
 
   const admitted: Admission[] = [];
   for (const r of routed) {
-    if (admitted.length >= slots) break;
-    if (busy.has(r.issue.number)) continue;
+    const issue = r.issue.number;
+    if (admitted.length >= slots) {
+      hold(issue, "capacity");
+      continue;
+    }
+    if (busy.has(issue)) {
+      hold(issue, "issue-active");
+      continue;
+    }
 
-    const prior = store.attemptsFor(project.name, r.issue.number);
-    if (prior >= caps.maxAttemptsPerIssue) {
+    const priorRuns = store.attemptsFor(project.name, issue);
+    const failures = store.failuresFor(project.name, issue);
+    if (failures >= caps.maxAttemptsPerIssue) {
+      hold(issue, "failed-attempts");
       await safeEscalate(d, {
         tier: 1,
         project: project.name,
-        issue: r.issue.number,
-        summary: `#${r.issue.number} has used all ${caps.maxAttemptsPerIssue} attempts`,
+        issue,
+        summary: `#${issue} has used all ${caps.maxAttemptsPerIssue} failed attempts`,
         detail: [
           r.issue.title,
           r.issue.url,
-          "Another attempt almost always means the issue itself is underspecified.",
+          "Another implementation attempt almost always means the issue itself is underspecified.",
           "Rewrite the acceptance criteria, or take it off the queue.",
         ].join("\n"),
       });
       continue;
     }
 
+    const continuations = store.continuationsFor(project.name, issue);
+    if (!hasContinuationBudget(continuations, caps.maxContinuationsPerIssue)) {
+      hold(issue, "continuations");
+      await safeEscalate(d, {
+        tier: 1,
+        project: project.name,
+        issue,
+        summary: `#${issue} exceeded its ${caps.maxContinuationsPerIssue}-continuation budget`,
+        detail: [
+          r.issue.title,
+          r.issue.url,
+          "Repeated cap kills, daemon orphans, or answered blocks need an operator to inspect progress.",
+        ].join("\n"),
+      });
+      continue;
+    }
+
     // Soft concurrency per epic: at most one in-flight child of a given parent.
     // No parent means today's concurrent admission. Cheap local filters already
     // ran; this sits before the open-PR API call so a held sibling frees the
     // slot for unrelated work without spending a closers query.
     let parent: number | undefined;
     try {
-      parent = await resolveParent(r.issue.number);
+      parent = await resolveParent(issue);
     } catch (err) {
-      log(`#${r.issue.number} held: parent check failed (${errText(err)}) — retrying next tick`);
+      hold(issue, "parent-lookup-error");
+      log(`#${issue} held: parent check failed (${errText(err)}) — retrying next tick`);
       continue;
     }
     if (parent !== undefined) {
       const blocker = occupiedParents.get(parent);
       if (blocker !== undefined) {
-        log(
-          `#${r.issue.number} skipped: sibling #${blocker} in flight under epic #${parent}`,
-        );
+        hold(issue, "sibling-active");
+        log(`#${issue} skipped: sibling #${blocker} in flight under epic #${parent}`);
         continue;
       }
     }
@@ -917,36 +1223,85 @@ export async function admitCandidates(
     // like fresh work, and a worker sent at it re-implements a finished PR. The
     // tracker is the only party that remembers, so it is asked. The cost is
     // bounded by free slots, not by queue depth: the call sits behind the two
-    // cheap local filters and the loop stops once the slots are full.
+    // cheap local filters and candidates beyond capacity skip it.
     let closer: string | undefined;
     try {
-      closer = await tracker.openCloserFor(r.issue.number);
+      closer = await tracker.openCloserFor(issue);
     } catch (err) {
       // Fail closed, per candidate. An API error means "unknown whether
       // finished work exists", and admitting on unknown recreates precisely the
       // duplicate-work failure this guard exists to kill: the worst case of
       // holding is a five-minute delay, the worst case of admitting is a burned
       // attempt and a second PR on the same issue. Holding one candidate rather
-      // than aborting the loop is what keeps a transient GitHub failure from
-      // deadlocking the whole dispatcher; the next tick retries by itself.
-      log(`#${r.issue.number} held: open-PR check failed (${errText(err)}) — retrying next tick`);
+      // than aborting the loop keeps a transient GitHub failure from deadlocking
+      // the whole dispatcher; the next tick retries by itself.
+      hold(issue, "open-pr-lookup-error");
+      log(`#${issue} held: open-PR check failed (${errText(err)}) — retrying next tick`);
       continue;
     }
     if (closer !== undefined) {
-      log(`#${r.issue.number} skipped: open PR ${closer} already closes it`);
-      continue;
+      const latest = store.latestRun(project.name, issue);
+      const retainedContinuation =
+        latest?.prUrl === closer &&
+        (latest.state === "blocked" ||
+          latest.state === "failed" ||
+          latest.state === "killed" ||
+          latest.state === "orphaned");
+      if (!retainedContinuation) {
+        hold(issue, "open-pr");
+        log(`#${issue} skipped: open PR ${closer} already closes it`);
+        continue;
+      }
+      log(`#${issue} continuing retained PR ${closer} from ${latest.state} run`);
     }
 
-    admitted.push({ r, attempt: prior + 1 });
-    if (parent !== undefined) occupiedParents.set(parent, r.issue.number);
+    admitted.push({ r, attempt: priorRuns + 1 });
+    if (parent !== undefined) occupiedParents.set(parent, issue);
   }
 
-  return admitted;
+  return { admitted, holds };
+}
+
+export interface WorkerPool {
+  launch(work: Promise<void>): void;
+  activeCount(): number;
+  drain(): Promise<void>;
+}
+
+/** Keeps background workers alive without making the five-minute tick await them. */
+export function createWorkerPool(): WorkerPool {
+  const active = new Set<Promise<void>>();
+  return {
+    launch(work) {
+      active.add(work);
+      void work.then(
+        () => active.delete(work),
+        () => active.delete(work),
+      );
+    },
+    activeCount: () => active.size,
+    async drain() {
+      await Promise.allSettled(active);
+    },
+  };
+}
+
+/** `--once` awaits workers; the resident daemon registers them for shutdown. */
+export async function dispatchAdmissions(
+  admitted: readonly Admission[],
+  run: (admission: Admission) => Promise<void>,
+  pool?: WorkerPool,
+): Promise<void> {
+  if (pool !== undefined) {
+    for (const admission of admitted) pool.launch(run(admission));
+    return;
+  }
+  await Promise.allSettled(admitted.map(run));
 }
 
 // ----------------------------------------------------------------------- a tick
 
-async function tick(d: Deps): Promise<void> {
+export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   // Before the pause check, deliberately. This one is not about dispatch: the
   // orchestrator is a different process, and it can be wedged while this fleet
   // is paused — which is exactly the state the reference fleet was in when the
@@ -954,6 +1309,12 @@ async function tick(d: Deps): Promise<void> {
   // know their supervising session stopped reading its queue.
   await watchOrchestrator(d);
 
+  // Settlement is maintenance, not dispatch. Run it before every gate that can
+  // stop claiming — pause, integrity, spend, and capacity — so status converges
+  // while the fleet is parked or workers are still active. Resident workers run
+  // through the pool without blocking this five-minute tick.
+  await settlePushedGreen(d);
+
   // A paused fleet claims nothing. Checked first so pausing takes effect on the
   // next tick without signalling the process.
   if (isPaused()) return;
@@ -1011,16 +1372,25 @@ async function tick(d: Deps): Promise<void> {
     return;
   }
 
-  // Above admission on purpose: a row settled this tick frees its issue for
-  // this same tick, so a merge and a re-queue no longer cost five minutes each.
-  // Above the spend cap too, which returns early — settling is bookkeeping about
-  // work already paid for, and a fleet that halts itself is exactly when an
-  // operator reads `status` and needs it to be true.
-  await settlePushedGreen(d);
-
   // route() filters the queue through isEligible() itself, so anything already
   // carrying a state label is gone before it gets here.
-  const { routed, unroutable } = route(await d.tracker.listReady(), project);
+  const ready = await d.tracker.listReady();
+  await cleanupRetainedRuns(
+    d,
+    new Set(ready.map((issue) => issue.number)),
+    d.cleanup ?? { next: 0 },
+  );
+  const { routed, unroutable } = route(ready, project);
+  const routingHolds: AdmissionHold[] = unroutable.map((u) => ({
+    issue: u.issue.number,
+    reason: `unroutable:${u.reason}`,
+  }));
+  const recordDispatch = (admitted: number, holds: readonly AdmissionHold[]): void => {
+    store.recordDispatch(
+      project.name,
+      summarizeDispatch(ready.length, routed.length, admitted, holds),
+    );
+  };
 
   // An issue nobody can route never reaches a worker: guessing the target repo
   // is exactly the kind of improvisation this system exists to prevent. The
@@ -1061,6 +1431,10 @@ async function tick(d: Deps): Promise<void> {
         "No further work will be claimed until `omp-conductor resume` (or /conductor resume).",
       ].join("\n"),
     });
+    recordDispatch(0, [
+      ...routingHolds,
+      ...routed.map((r) => ({ issue: r.issue.number, reason: "daily-spend-cap" as const })),
+    ]);
     return;
   }
 
@@ -1072,20 +1446,119 @@ async function tick(d: Deps): Promise<void> {
   const slots = caps.maxConcurrentWorkers - live.length;
   if (slots <= 0) {
     log(`at capacity: ${live.length}/${caps.maxConcurrentWorkers} workers`);
+    recordDispatch(0, [
+      ...routingHolds,
+      ...routed.map((r) => ({ issue: r.issue.number, reason: "capacity" as const })),
+    ]);
     return;
   }
 
-  const admitted = await admitCandidates(d, routed, slots);
+  const pass = await admitCandidates(d, routed, slots);
+  recordDispatch(pass.admitted.length, [...routingHolds, ...pass.holds]);
 
-  if (admitted.length === 0) return;
+  if (pass.admitted.length === 0) return;
 
-  log(`dispatching ${admitted.map((a) => `#${a.r.issue.number}`).join(" ")}`);
-  // handleIssue never rejects; allSettled is the belt to that braces.
-  await Promise.allSettled(admitted.map((a) => handleIssue(d, a.r, a.attempt)));
+  log(`dispatching ${pass.admitted.map((a) => `#${a.r.issue.number}`).join(" ")}`);
+  await dispatchAdmissions(
+    pass.admitted,
+    (a) => handleIssue(d, a.r, a.attempt),
+    workers,
+  );
 }
 
 // --------------------------------------------------------------- read-only views
 
+export interface DaemonHealthSnapshot {
+  ok: true;
+  paused: boolean;
+  activeRuns: number;
+  project: string;
+  /** Resident set of this daemon; workers are in-process omp sessions. */
+  rssBytes: number;
+  dispatch?: DispatchSummary;
+  codeGraph?: CodeGraphHealth;
+}
+
+export function daemonHealthSnapshot(
+  store: Store,
+  project: string,
+  paused = isPaused(),
+  rssBytes = process.memoryUsage().rss,
+  codeGraph?: CodeGraphHealth,
+): DaemonHealthSnapshot {
+  const dispatch = store.latestDispatch(project);
+  return {
+    ok: true,
+    paused,
+    activeRuns: store.activeRuns(project).length,
+    project,
+    rssBytes,
+    ...(dispatch === undefined ? {} : { dispatch }),
+    ...(codeGraph?.configured === true ? { codeGraph } : {}),
+  };
+}
+
+export async function turnLimitResponse(
+  req: Request,
+  project: string,
+  store: Pick<Store, "latestRun">,
+  registry: TurnLimitRegistry,
+): Promise<Response | undefined> {
+  const url = new URL(req.url);
+  const match = /^\/runs\/(\d+)\/turn-limit$/.exec(url.pathname);
+  if (req.method !== "PUT" || match === null) return undefined;
+  if (!req.headers.get("content-type")?.startsWith("application/json")) {
+    return Response.json({ error: "content-type must be application/json" }, { status: 415 });
+  }
+
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return Response.json({ error: "request body must be valid JSON" }, { status: 400 });
+  }
+  if (body === null || typeof body !== "object") {
+    return Response.json({ error: "request body must be a JSON object" }, { status: 400 });
+  }
+  const requestedProject = Reflect.get(body, "project");
+  if (typeof requestedProject !== "string" || requestedProject.length === 0) {
+    return Response.json({ error: "project must be a non-empty string" }, { status: 400 });
+  }
+  if (requestedProject !== project) {
+    return Response.json(
+      { error: `daemon serves project "${project}", not requested project "${requestedProject}"` },
+      { status: 409 },
+    );
+  }
+  const maxTurns = Reflect.get(body, "maxTurns");
+  if (!Number.isSafeInteger(maxTurns) || (maxTurns as number) < 1) {
+    return Response.json({ error: "maxTurns must be a positive integer" }, { status: 400 });
+  }
+
+  const issue = Number(match[1]);
+  const outcome = registry.extend(project, issue, maxTurns as number);
+  if (outcome.kind === "extended") return Response.json(outcome);
+  if (outcome.kind === "not-increase") {
+    return Response.json(
+      { error: `#${issue} already has a ${outcome.maxTurns}-turn ceiling` },
+      { status: 409 },
+    );
+  }
+
+  const latest = store.latestRun(project, issue);
+  if (latest === undefined) {
+    return Response.json({ error: `no run recorded for #${issue}` }, { status: 404 });
+  }
+  return Response.json(
+    {
+      error:
+        `#${issue} has no live worker controller; its session already settled ` +
+        `or belongs to another daemon (stored state: ${latest.state})`,
+    },
+    { status: 409 },
+  );
+}
+
 export interface StatusSnapshot {
   project: string;
   configPath: string;
@@ -1098,33 +1571,65 @@ export interface StatusSnapshot {
   liveWorkers: number;
   runsToday: number;
   spendTodayUsd: number;
+  dispatch?: DispatchSummary;
 }
 
-/** Opens and closes its own store handle so the CLI and the plugin can read
- *  status while a daemon in another process is writing (the store runs in WAL
- *  mode for exactly this). */
+/** Builds a status reading from an already-open store. Long-lived operator
+ * surfaces use this path so a one-second refresh does not repeatedly open and
+ * initialise SQLite connections. */
+export function statusSnapshotFromStore(p: ProjectConfig, caps: Caps, store: Store): StatusSnapshot {
+  const since = startOfToday();
+  const dispatch = store.latestDispatch(p.name);
+  return {
+    project: p.name,
+    configPath: configPath(),
+    stateDir: stateDir(),
+    paused: isPaused(),
+    caps,
+    activeRuns: store.activeRuns(p.name),
+    liveWorkers: store.liveRuns(p.name).length,
+    runsToday: store.runsStartedSince(p.name, since),
+    spendTodayUsd: store.spendSince(p.name, since),
+    ...(dispatch === undefined ? {} : { dispatch }),
+  };
+}
+
+/** Opens and closes its own store handle so one-shot CLI and plugin readers can
+ * read status while a daemon in another process is writing (the store runs in
+ * WAL mode for exactly this). */
 export function statusSnapshot(project?: string): StatusSnapshot {
   const cfg = loadConfig();
   const p = findProject(cfg, project);
   const store = openStore(dbPath());
   try {
-    const since = startOfToday();
-    return {
-      project: p.name,
-      configPath: configPath(),
-      stateDir: stateDir(),
-      paused: isPaused(),
-      caps: resolveCaps(p, cfg.defaults),
-      activeRuns: store.activeRuns(p.name),
-      liveWorkers: store.liveRuns(p.name).length,
-      runsToday: store.runsStartedSince(p.name, since),
-      spendTodayUsd: store.spendSince(p.name, since),
-    };
+    return statusSnapshotFromStore(p, resolveCaps(p, cfg.defaults), store);
   } finally {
     store.close();
   }
 }
 
+export function formatDispatchSummary(summary?: DispatchSummary): string {
+  if (summary === undefined) return "last dispatch  (none recorded)";
+  const lines = [
+    `last dispatch  ${new Date(summary.completedAt).toISOString()}${summary.degraded ? "  DEGRADED" : ""}`,
+    `  candidates    ${summary.ready} ready / ${summary.routed} routed`,
+    `  admitted      ${summary.admitted}`,
+  ];
+  if (summary.holds.length === 0) {
+    lines.push("  held          0");
+  } else {
+    lines.push("  held");
+    for (const hold of summary.holds) {
+      const sample =
+        hold.issues.length === 0
+          ? ""
+          : ` (#${hold.issues.join(", #")}${hold.count > hold.issues.length ? ", …" : ""})`;
+      lines.push(`    ${hold.reason}  ${hold.count}${sample}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 export function formatStatus(s: StatusSnapshot): string {
   const lines = [
     `project   ${s.project}${s.paused ? "  (PAUSED)" : ""}`,
@@ -1137,9 +1642,12 @@ export function formatStatus(s: StatusSnapshot): string {
     s.caps.dailySpendUsd === null
       ? `  spend today        $${s.spendTodayUsd.toFixed(2)} (no daily cap)`
       : `  spend today        $${s.spendTodayUsd.toFixed(2)} / $${s.caps.dailySpendUsd.toFixed(2)}`,
-    `  worker max turns   ${s.caps.workerMaxTurns}`,
+    `  new worker turns   ${s.caps.workerMaxTurns}`,
     `  worker wall clock  ${Math.round(s.caps.workerWallClockMs / 60_000)}m`,
-    `  attempts per issue ${s.caps.maxAttemptsPerIssue}`,
+    `  failed attempts    ${s.caps.maxAttemptsPerIssue}`,
+    `  continuations      ${s.caps.maxContinuationsPerIssue}`,
+    "",
+    formatDispatchSummary(s.dispatch),
     "",
   ];
   if (s.activeRuns.length === 0) {
@@ -1149,7 +1657,7 @@ export function formatStatus(s: StatusSnapshot): string {
     for (const r of s.activeRuns) {
       lines.push(
         `  #${r.issue}  ${r.repo}  ${r.state}  attempt ${r.attempt}  ` +
-          `${r.turns} turns  $${r.spendUsd.toFixed(2)}  ${r.branch}` +
+          `${r.turns}/${r.maxTurns} turns  $${r.spendUsd.toFixed(2)}  ${r.branch}` +
           (r.prUrl ? `  ${r.prUrl}` : ""),
       );
     }
@@ -1180,14 +1688,15 @@ export interface QueuePreview {
  * label, run row or worktree. This is what makes `/conductor setup` honest: the
  * dry run is the same routing code the loop uses, not a description of it.
  */
-export async function previewQueue(project?: string): Promise<QueuePreview> {
-  const cfg = loadConfig();
-  const p = findProject(cfg, project);
+export async function previewProject(
+  p: ProjectConfig,
+  path: string = configPath(),
+): Promise<QueuePreview> {
   const { routed, unroutable } = route(await makeTracker(p).listReady(), p);
   const states = Object.values(p.stateLabels).join(", ");
   return {
     project: p.name,
-    configPath: configPath(),
+    configPath: path,
     queueDescription:
       `open issues in ${p.tracker.repo} labelled "${p.queueLabel}", ` +
       `minus anything already labelled ${states}, ` +
@@ -1208,14 +1717,20 @@ export async function previewQueue(project?: string): Promise<QueuePreview> {
   };
 }
 
+export async function previewQueue(project?: string): Promise<QueuePreview> {
+  const cfg = loadConfig();
+  return previewProject(findProject(cfg, project));
+}
+
 /**
- * The one mutation `/conductor setup` performs, and only after the operator has
- * seen the dry run: create the state directory and schema, then clear the pause
- * flag so the daemon is allowed to claim work.
+ * Creates the state store and holds dispatch while setup verifies the host.
+ *
+ * Setup calls this immediately after consent. Every later setup error therefore
+ * leaves the fleet paused instead of exposing a partially written runtime.
  */
-export function armConductor(): void {
+export function prepareConductor(): void {
   openStore(dbPath()).close();
-  setPaused(false);
+  setPaused(true);
 }
 
 /**
@@ -1317,6 +1832,10 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
         "a time, freshness-checked against the base branch, per the Releases section of your POLICY.md."
       : "You never edit product code, push a branch, or merge a PR — a worker session edits and pushes, and a " +
         "human merges.",
+    `Release tool gate: releasePolicy=${resolveReleasePolicy(project)}. ` +
+      (resolveReleasePolicy(project) === "none"
+        ? "Release and deploy tool calls are mechanically blocked."
+        : "Release and deploy tool calls are permitted only by the operator brief."),
     "Handle each escalation below before the next one.",
   ].join("\n");
 
@@ -1334,7 +1853,12 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
     log("orchestrator: external — tier-1 escalations post as issue comments for the external session's drain duty");
   } else {
     try {
-      orchestrator = await startOrchestrator({ cwd: stateDir(), brief });
+      orchestrator = await startOrchestrator({
+        cwd: stateDir(),
+        brief,
+        releasePolicy: resolveReleasePolicy(project),
+        onReleaseBlocked: (shape) => recordReleaseBlock(project.name, "orchestrator", shape),
+      });
       const transcript = orchestrator.sessionFile();
       log(`orchestrator session ready${transcript === undefined ? "" : ` · ${transcript}`}`);
     } catch (err) {
@@ -1348,16 +1872,21 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   }
 
   const escalator = createEscalator(project, tracker, store, orchestrator);
+  const turnLimits = createTurnLimitRegistry((runId, maxTurns) => {
+    store.updateRun(runId, { maxTurns });
+  });
   const d: Deps = {
     project,
     caps,
     tracker,
     store,
     escalate: (e) => escalator.escalate(e),
+    turnLimits,
     integrity,
     // Fresh per daemon run, like the integrity gate: a restart is entitled to
     // page again about a stall that is still on disk.
     stall: { paged: false },
+    cleanup: { next: 0 },
   };
 
   if (o.once) {
@@ -1370,33 +1899,49 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
     return;
   }
 
+  // Graphs are optional, so their bounded probes run beside dispatch and feed
+  // a cache. /healthz remains an in-memory answer and never blocks liveness on
+  // the indexer or systemd.
+  let codeGraph = pendingCodeGraph(project);
+  let graphProbe: Promise<void> | undefined;
+  const refreshCodeGraph = (): void => {
+    if (graphProbe !== undefined) return;
+    graphProbe = probeCodeGraph(project)
+      .then((health) => {
+        codeGraph = health;
+      })
+      .catch(() => {
+        log("code-graph health probe failed unexpectedly; retaining the previous bounded result");
+      })
+      .finally(() => {
+        graphProbe = undefined;
+      });
+  };
+  refreshCodeGraph();
+  const graphTimer = setInterval(refreshCodeGraph, GRAPH_HEALTH_INTERVAL_MS);
+
+  const workers = createWorkerPool();
   let stopping = false;
   let wake: (() => void) | undefined;
   const stop = (): void => {
     if (stopping) return;
     stopping = true;
-    log("shutting down after the current tick");
+    log("shutting down after active workers finish");
     wake?.();
   };
   process.on("SIGINT", stop);
   process.on("SIGTERM", stop);
 
   const server = Bun.serve({
+    hostname: "127.0.0.1",
     port: o.port ?? DEFAULT_PORT,
-    fetch(req) {
+    async fetch(req) {
       const url = new URL(req.url);
       if (req.method === "GET" && url.pathname === "/healthz") {
-        return Response.json({
-          ok: true,
-          paused: isPaused(),
-          activeRuns: store.activeRuns(project.name).length,
-          project: project.name,
-          // Resident set of *this* process: workers are in-process omp sessions,
-          // so the unit's Memory peak is this number, not a separate worker pid.
-          rssBytes: process.memoryUsage().rss,
-        });
+        return Response.json(daemonHealthSnapshot(store, project.name, undefined, undefined, codeGraph));
       }
-      return new Response("not found\n", { status: 404 });
+      const control = await turnLimitResponse(req, project.name, store, turnLimits);
+      return control ?? new Response("not found\n", { status: 404 });
     },
   });
   log(`serving /healthz on :${server.port}, project ${project.name}`);
@@ -1404,7 +1949,7 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   try {
     while (!stopping) {
       try {
-        await tick(d);
+        await tick(d, workers);
       } catch (err) {
         // A tick that blows up outside an issue (the tracker is down, say) must
         // not end the daemon; the next one will retry.
@@ -1423,6 +1968,8 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   } finally {
     process.off("SIGINT", stop);
     process.off("SIGTERM", stop);
+    clearInterval(graphTimer);
+    await workers.drain();
     await server.stop(true);
     // Before the store closes: a queued injection that rejects on the way out
     // falls back to an issue comment, and that path writes the dedup marker.