omp-conductor 0.9.1 → 0.12.0

package/src/board.ts

@@ -12,6 +12,7 @@ import {
 } from "./fleet.ts";
 import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
 import { healthCheck, livingDaemon } from "./lifecycle.ts";
+import type { WorkerPausePhase } from "./worker.ts";
 import { dbPath, openStore } from "./store.ts";
 import { formatTranscriptLine } from "./transcript.ts";
 import { makeTracker } from "./tracker/github.ts";
@@ -72,9 +73,9 @@ const COLUMN_DEFS = [
   { key: "blocked", title: "BLOCKED" },
   { key: "failed", title: "FAILED" },
   { key: "orphaned", title: "ORPHANED" },
-  { key: "parked", title: "PARKED" },
   { key: "merged", title: "MERGED" },
-  { key: "history", title: "HISTORY" },
+  { key: "settled", title: "SETTLED" },
+  { key: "parked", title: "PARKED" },
 ] as const satisfies readonly { key: string; title: string }[];
 
 export type BoardLane = (typeof COLUMN_DEFS)[number]["key"];
@@ -136,6 +137,11 @@ export interface BoardHealth {
   codeGraph?: CodeGraphHealth;
 }
 
+interface BoardHealthProbe {
+  health: BoardHealth;
+  pausedPhases: ReadonlyMap<number, WorkerPausePhase>;
+}
+
 /**
  * Which issues currently carry each label the board reasons about, read from
  * the tracker rather than inferred from run rows.
@@ -151,11 +157,15 @@ export interface BoardLabels {
   inProgress: ReadonlySet<number>;
   blocked: ReadonlySet<number>;
   failed: ReadonlySet<number>;
-  /** Issues whose newest run is terminal and unlabelled but that are still open
-   *  on the tracker — the PARKED lane (#173), probed on the same 10s cadence as
-   *  the label sets. An issue missing from this set (closed, or the probe could
-   *  not tell) keeps today's HISTORY/undefined behaviour rather than parking. */
-  open: ReadonlySet<number>;
+  /**
+   * Issues the tracker reports CLOSED, derived only from a *successful* label
+   * snapshot on the same 10s cadence as the other sets. This is the one fact
+   * that separates SETTLED (finished work, issue closed) from PARKED (a human
+   * still has to look): absence from this set means open **or** the probe could
+   * not tell, and either way the run parks rather than falsely asserting
+   * closure. On a failed read the last good set survives behind {@link error}.
+   */
+  closed: ReadonlySet<number>;
   /** Epoch ms of the last read that succeeded; 0 when none has. */
   readAt: number;
   /** Message from the most recent failed read. The sets above are then the last
@@ -171,7 +181,7 @@ const UNREAD_LABELS: BoardLabels = {
   inProgress: new Set<number>(),
   blocked: new Set<number>(),
   failed: new Set<number>(),
-  open: new Set<number>(),
+  closed: new Set<number>(),
   readAt: 0,
 };
 
@@ -179,6 +189,7 @@ export interface BoardSnapshot {
   project: ProjectConfig;
   status: StatusSnapshot;
   health: BoardHealth;
+  pausedPhases: ReadonlyMap<number, WorkerPausePhase>;
   labels: BoardLabels;
   /** Live re-verification of pushed rows (#173): run id → what the tracker says
    *  the PR looks like now. Rendered as a `now:` suffix on the card. */
@@ -225,7 +236,7 @@ function ansiColor(key: BoardLane): string {
       return YELLOW;
     case "failed":
       return RED;
-    case "history":
+    case "settled":
       return DIM;
     default:
       return MAGENTA;
@@ -285,10 +296,11 @@ function humanDuration(ms: number): string {
  * parent issues a human had already cleared (#81, #86) — every one of them a
  * historical terminal run, not one of them failed work.
  *
- * So: the store decides the live lanes, because a running worker is the most
+ * so: the store decides the live lanes, because a running worker is the most
  * current fact there is; the tracker's current labels decide every stopped
  * lane; each issue matches exactly once, first branch wins; and last-run
- * history is answered in HISTORY, under its own name.
+ * history is answered in SETTLED (issue closed) and PARKED (issue still open,
+ * labels cleared), under their own names.
  */
 function laneOf(
   snapshot: BoardSnapshot,
@@ -322,17 +334,19 @@ function laneOf(
   if (queued.has(issue)) return "queue";
   if (run?.state === "merged") return "merged";
   if (run === undefined) return undefined;
-  // PARKED (#173): a terminal run row with no state or queue label left on it,
-  // on an issue the tracker says is still open. A human cleared the labels but
-  // has not acted — the blank lane the four labels used to imply is a lie, and
-  // closed or unreadable issues keep the HISTORY/undefined fallthrough below.
-  // Deliberately not subject to MERGED_HISTORY_MS: parked work does not stop
-  // being the issue's last word after 24 hours.
-  if (PARKED_STATES.has(run.state) && labels.open.has(issue)) return "parked";
-  // What is left is a terminal run row with no current claim on it — a closed
-  // issue, or one a human already cleared. Recent rows stay readable under
-  // HISTORY for the same 24 hours MERGED uses; older ones are not news.
-  return (run.endedAt ?? run.startedAt) >= snapshot.now - MERGED_HISTORY_MS ? "history" : undefined;
+  // SETTLED vs PARKED, decided by the one fact the board can prove: whether the
+  // tracker confirmed the issue closed. Absence from `closed` means open OR the
+  // probe could not tell, and either way the run parks — a failed label read
+  // must render the issue as "a human has to look", never as finished work
+  // (#218). PARKED is deliberately not subject to MERGED_HISTORY_MS: parked work
+  // does not stop being the issue's last word after 24 hours.
+  if (PARKED_STATES.has(run.state) && !labels.closed.has(issue)) return "parked";
+  // What is left is a confirmed-closed issue with a terminal run row. Recent
+  // rows stay readable under SETTLED for the same 24 hours MERGED uses; older
+  // ones are not news. Named for what it means — the run settled and the issue
+  // is closed — not for the vague archive HISTORY read as, which is how one lane
+  // came to look like two different things (#218).
+  return (run.endedAt ?? run.startedAt) >= snapshot.now - MERGED_HISTORY_MS ? "settled" : undefined;
 }
 
 /** Description lines for an issue the store has no run row for. Only the lanes
@@ -467,7 +481,7 @@ export function boardLabelsEqual(a: BoardLabels, b: BoardLabels): boolean {
     sameIssueSet(a.inProgress, b.inProgress) &&
     sameIssueSet(a.blocked, b.blocked) &&
     sameIssueSet(a.failed, b.failed) &&
-    sameIssueSet(a.open, b.open) &&
+    sameIssueSet(a.closed, b.closed) &&
     (a.error === undefined) === (b.error === undefined)
   );
 }
@@ -551,43 +565,54 @@ function normalizeCursor(snapshot: BoardSnapshot, cursor: BoardCursor): void {
   cursor.transcriptOffset = Math.max(0, cursor.transcriptOffset);
 }
 
-function runCardLines(run: RunRecord, snapshot: BoardSnapshot): string[] {
+function runCardLines(run: RunRecord, snapshot: BoardSnapshot, lane: BoardLane): string[] {
   const endedAt = run.endedAt ?? snapshot.now;
   const duration = humanDuration(endedAt - run.startedAt);
+  const phase = lane === "running" ? snapshot.pausedPhases.get(run.issue) : undefined;
+  const pausePrefix = phase === "paused" ? "⏸ PAUSED " : phase === "pausing" ? "… pausing " : "";
   const lines = [
     // The class, when the sweep has attached one and nothing has recovered it
     // yet (#132): a row state says "failed", which four completed issues on this
     // fleet also said. The class says which of the two this is.
     run.failureClass === undefined || run.recoveredAt !== undefined
-      ? `#${run.issue} · ${run.repo}`
-      : `#${run.issue} · ${run.repo} [${run.failureClass}]`,
+      ? `${pausePrefix}#${run.issue} · ${run.repo}`
+      : `${pausePrefix}#${run.issue} · ${run.repo} [${run.failureClass}]`,
     `attempt ${run.attempt} · ${run.turns}/${run.maxTurns}t`,
     `$${run.spendUsd.toFixed(2)} · ${duration}`,
   ];
-  // #173: a live re-verification of a pushed row, when the 60s probe has one.
-  // Guarded on the pushed states: a stale entry must not follow a row that
-  // settled into another lane and keep claiming "now: green" about a PR that
-  // already merged or failed.
-  const live =
-    run.state === "pushed-green" || run.state === "pushed-pending" ? snapshot.pr.get(run.id) : undefined;
-  if (live !== undefined) {
-    const reason = live.reason.split(/\s+/, 1)[0] ?? "";
-    lines.push(
-      live.status === "failed" ? `now: red — ${reason === "" ? "failed" : reason}` : `now: ${prLabel(live.status)}`,
-    );
-  }
-  // #173: a terminal blocked/failed run whose state label is gone reads as the
-  // lane it sits in — which the label being absent made PARKED, not the truth.
-  if (isLastRun(run, snapshot.labels)) lines.push(`last run: ${run.state}`);
-  // Ordered by what needs a human first. An unsalvaged tree outranks even a
-  // last error: the error describes a run that is over, the tree is work that
-  // is still at risk and an issue that will not dispatch (#118).
+  // Exactly one fourth line, so a card stays within the four content lines that
+  // renderColumn's slot arithmetic (`slots = floor((height - 2) / 5)`) allocates
+  // for it. Every fact a card can carry folds into this single priority:
+  // an unsalvaged tree outranks even a live verdict (#118) — the error describes
+  // a run that is over, the tree is work still at risk — then the live probe for
+  // a pushed row, then the word the lane name cannot carry, then the run's own
+  // evidence.
+  //
+  // `isLastRun` is deliberately not a card line: it belongs in the detail header
+  // (renderDetail's `stateShown`), where a full width can spell out `last run:
+  // blocked`. Putting it here too would blow the budget and repeat the #218
+  // conflation on the two-line boundary.
   if (run.salvageError !== undefined && run.salvageAckAt === undefined) lines.push("UNSALVAGED WIP");
-  else if (run.state === "pushed-pending") lines.push("checks pending");
-  else if (run.salvageSha !== undefined) lines.push(`wip @ ${run.salvageSha.slice(0, 7)}`);
-  else if (run.lastError !== undefined) lines.push(run.lastError.replace(/\s+/g, " "));
-  else if (run.prUrl !== undefined) lines.push(run.prUrl.replace(/^https?:\/\//, ""));
-  else lines.push(run.branch);
+  else {
+    // #173: a live re-verification of a pushed row, when the 60s probe has one.
+    // Guarded on the pushed states: a stale entry must not follow a row that
+    // settled into another lane and keep claiming "now: green" about a PR that
+    // already merged or failed.
+    const live =
+      run.state === "pushed-green" || run.state === "pushed-pending" ? snapshot.pr.get(run.id) : undefined;
+    if (live !== undefined) {
+      const reason = live.reason.split(/\s+/, 1)[0] ?? "";
+      lines.push(
+        live.status === "failed" ? `now: red — ${reason === "" ? "failed" : reason}` : `now: ${prLabel(live.status)}`,
+      );
+    } else if (lane === "settled") lines.push("issue closed");
+    else if (lane === "parked") lines.push("needs a label");
+    else if (run.state === "pushed-pending") lines.push("checks pending");
+    else if (run.salvageSha !== undefined) lines.push(`wip @ ${run.salvageSha.slice(0, 7)}`);
+    else if (run.lastError !== undefined) lines.push(run.lastError.replace(/\s+/g, " "));
+    else if (run.prUrl !== undefined) lines.push(run.prUrl.replace(/^https?:\/\//, ""));
+    else lines.push(run.branch);
+  }
   return lines;
 }
 
@@ -616,7 +641,7 @@ function renderColumn(
     lines.push(styledCell(" (empty)", width, DIM));
   } else {
     for (const [offset, card] of shown.entries()) {
-      const raw = card.kind === "run" ? runCardLines(card.run, snapshot) : [`#${card.issue}`, card.reason, card.note];
+      const raw = card.kind === "run" ? runCardLines(card.run, snapshot, key) : [`#${card.issue}`, card.reason, card.note];
       while (raw.length < 4) raw.push("");
       const selected = selectedColumn && start + offset === selectedCard;
       for (const [lineIndex, value] of raw.entries()) {
@@ -703,7 +728,7 @@ function admissionLine(snapshot: BoardSnapshot): string {
   const queue =
     dispatch === undefined
       ? "dispatch not recorded"
-      : `${dispatch.degraded ? "DEGRADED · " : ""}${dispatch.ready} ready · ${dispatch.routed} routed · ${dispatch.admitted} admitted`;
+      : `${dispatch.degraded ? "DEGRADED · " : ""}${dispatch.ready} ready · ${dispatch.claimed ?? 0} in flight · ${dispatch.routed} spare · ${dispatch.admitted} admitted`;
   const holdText = dispatch?.holds.map((hold) => `${hold.reason} ${hold.count}`).join(", ");
   const holds = holdText === undefined || holdText === "" ? "none" : holdText;
   return (
@@ -804,8 +829,20 @@ function renderDetail(snapshot: BoardSnapshot, cursor: BoardCursor, width: numbe
   // #173: a blocked/failed run whose label is gone is the reason this card is
   // parked; the header says so rather than presenting the state as current.
   const stateShown = isLastRun(run, snapshot.labels) ? `last run: ${run.state}` : run.state;
+  const pausePhase = snapshot.pausedPhases.get(run.issue);
   const metadata = [
     styledCell(` RUN #${run.issue}  ${run.repo}  ${stateShown} `, width, `${BOLD}${REVERSE}`),
+    ...(pausePhase === undefined
+      ? []
+      : [
+          styledCell(
+            pausePhase === "paused"
+              ? "worker paused  ·  wall clock frozen"
+              : "worker pausing  ·  draining to harness idle",
+            width,
+            YELLOW,
+          ),
+        ]),
     styledCell(`attempt ${run.attempt}  ·  ${run.turns}/${run.maxTurns} turns  ·  $${run.spendUsd.toFixed(2)}  ·  ${humanDuration((run.endedAt ?? snapshot.now) - run.startedAt)}`, width),
     styledCell(`branch ${run.branch}`, width, DIM),
     styledCell(`worktree ${run.worktree || "removed"}`, width, DIM),
@@ -828,12 +865,15 @@ function renderHelp(width: number, height: number): string[] {
     "↑/↓ or k/j   select card",
     "Enter         inspect/follow transcript",
     "u             unblock selected blocked, failed or orphaned issue",
+    "space         pause/resume selected worker",
     "i             open selected issue",
     "p             open selected pull request",
     "r             refresh health now",
     "?             close help",
     "Esc           back, then quit",
     "q / Ctrl-C    back, then quit",
+    "",
+    "PARKED = issue open, no label — nothing dispatches it until you label it",
   ];
   const top = Math.max(0, Math.floor((height - lines.length) / 2));
   return [
@@ -882,7 +922,37 @@ export function renderBoard(
   ].join("\n");
 }
 
-async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealth> {
+export function workerPhasesFromHealthz(
+  body: string | undefined,
+  project: string,
+): ReadonlyMap<number, WorkerPausePhase> {
+  const phases = new Map<number, WorkerPausePhase>();
+  if (body === undefined) return phases;
+  try {
+    const payload = JSON.parse(body) as unknown;
+    if (payload === null || typeof payload !== "object") return phases;
+    if (Reflect.get(payload, "project") !== project) return phases;
+    const workers = Reflect.get(payload, "workers");
+    if (!Array.isArray(workers)) return phases;
+    for (const worker of workers) {
+      if (worker === null || typeof worker !== "object") continue;
+      const issue = Reflect.get(worker, "issue");
+      const phase = Reflect.get(worker, "phase");
+      if (
+        Number.isSafeInteger(issue) &&
+        (issue as number) > 0 &&
+        (phase === "pausing" || phase === "paused")
+      ) {
+        phases.set(issue as number, phase);
+      }
+    }
+  } catch {
+    // An unreadable health body means no trustworthy pause phase.
+  }
+  return phases;
+}
+
+async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealthProbe> {
   const layers = fleetLayers(project.name);
   const record = livingDaemon();
   const wrongRecord = record?.project !== undefined && record.project !== project.name;
@@ -903,7 +973,18 @@ async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealth> {
     }
   }
   const cachedGraph = daemon === "ok" ? codeGraphFromHealthz(health?.body, project.name) : undefined;
-  return { layers, telegram, daemon, codeGraph: cachedGraph ?? (await probeCodeGraph(project)) };
+  return {
+    health: {
+      layers,
+      telegram,
+      daemon,
+      codeGraph: cachedGraph ?? (await probeCodeGraph(project)),
+    },
+    pausedPhases:
+      daemon === "ok"
+        ? workerPhasesFromHealthz(health?.body, project.name)
+        : new Map<number, WorkerPausePhase>(),
+  };
 }
 
 /**
@@ -916,7 +997,7 @@ async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealth> {
  *
  * One open-issue snapshot per pass, never one list call per label (#203): the
  * four lifecycle sets are derived in memory from it by {@link boardLabelSets},
- * and PARKED openness is read off the same snapshot instead of a per-candidate
+ * and SETTLED closure is read off the same snapshot instead of a per-candidate
  * `issueState` fan-out. The single read rides the conditional-request cache, so
  * an idle board costs no primary rate-limit budget at all. The cadence stays
  * the ten-second health refresh, never the one-second redraw path.
@@ -947,11 +1028,19 @@ export async function probeBoardLabels(
     const parkedCandidates = [...newestRun.values()].filter(
       (run) => PARKED_STATES.has(run.state) && !labelled.has(run.issue),
     );
-    // The snapshot IS the set of open issues, so openness needs no per-issue
-    // lookup: a candidate whose issue appears in it is open.
+    // The snapshot IS the set of open issues, so closure needs no per-issue
+    // lookup: a candidate whose issue does NOT appear in it is closed, *because
+    // this read succeeded*. That last clause is the whole distinction on the
+    // failed path — `closed` is only ever derived here, inside the try, so an
+    // unreadable probe survives as the previous set (or empty) and an issue the
+    // board could not confirm closed keeps parking rather than falsely reading
+    // as SETTLED (#218). Absence from `closed` is therefore open OR unknown,
+    // and both mean PARKED.
     const openNumbers = new Set(open.map((issue) => issue.number));
-    const openSet = new Set(parkedCandidates.map((run) => run.issue).filter((n) => openNumbers.has(n)));
-    return { queued, inProgress, blocked, failed, open: openSet, readAt: Date.now() };
+    const closed = new Set(
+      parkedCandidates.map((run) => run.issue).filter((n) => !openNumbers.has(n)),
+    );
+    return { queued, inProgress, blocked, failed, closed, readAt: Date.now() };
   } catch (err) {
     return {
       ...(previous ?? UNREAD_LABELS),
@@ -994,6 +1083,41 @@ async function unblock(project: ProjectConfig, issue: number): Promise<string> {
   if (code !== 0) return (stderr || stdout).trim().replace(/\s+/g, " ") || `#${issue}: unblock failed`;
   return summarizeUnblockOutput(issue, stdout);
 }
+
+async function toggleWorkerPause(
+  project: ProjectConfig,
+  issue: number,
+  phase: WorkerPausePhase | undefined,
+): Promise<string> {
+  if (phase === "pausing") return "still pausing — wait";
+  const daemon = livingDaemon();
+  if (daemon === undefined) return "daemon is not running";
+  if (daemon.project !== undefined && daemon.project !== project.name) {
+    return `daemon serves project "${daemon.project}", not requested project "${project.name}"`;
+  }
+  const action = phase === "paused" ? "resume" : "pause";
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${daemon.port}/runs/${issue}/${action}`,
+      {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ project: project.name }),
+      },
+    );
+    const payload = (await response.json()) as { error?: unknown; phase?: unknown };
+    if (!response.ok) {
+      return typeof payload.error === "string"
+        ? payload.error
+        : `daemon returned HTTP ${response.status}`;
+    }
+    return typeof payload.phase === "string"
+      ? `#${issue} worker ${payload.phase}`
+      : "daemon returned an invalid worker-control response";
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
 function enqueue(queue: KeyInput[], key: KeyInput, wake: (() => void) | undefined): void {
   queue.push(key);
   wake?.();
@@ -1025,7 +1149,7 @@ export async function boardSnapshotOnce(projectName?: string): Promise<BoardSnap
   const store: Store = openStore(dbPath());
   try {
     const now = Date.now();
-    const [health, labels, planUsage] = await Promise.all([
+    const [healthProbe, labels, planUsage] = await Promise.all([
       probeBoardHealth(project),
       probeBoardLabels(project, store),
       readPlanUsage(caps.planUsage, sharedUsageSource()),
@@ -1033,7 +1157,8 @@ export async function boardSnapshotOnce(projectName?: string): Promise<BoardSnap
     return {
       project,
       status: statusSnapshotFromStore(project, caps, store, planUsage),
-      health,
+      health: healthProbe.health,
+      pausedPhases: healthProbe.pausedPhases,
       labels,
       pr: new Map(),
       runs: store.recentRuns(project.name, now - MERGED_HISTORY_MS),
@@ -1111,11 +1236,13 @@ export async function runBoard(projectName?: string): Promise<void> {
     onCall: () => trackerCalls.push(Date.now()),
     onNotModified: () => trackerFree.push(Date.now()),
   });
-  let [health, labels, planUsage] = await Promise.all([
+  let [healthProbe, labels, planUsage] = await Promise.all([
     probeBoardHealth(project),
     probeBoardLabels(project, store, undefined, boardTracker),
     readPlanUsage(caps.planUsage, sharedUsageSource()),
   ]);
+  let health = healthProbe.health;
+  let pausedPhases = healthProbe.pausedPhases;
   let healthAt = Date.now();
   let healthRefresh: Promise<void> | undefined;
   // The tracker read is gated separately from health and the plan allowance:
@@ -1157,8 +1284,9 @@ export async function runBoard(projectName?: string): Promise<void> {
           // subprocess, and an allowance does not move at 1 Hz.
           readPlanUsage(caps.planUsage, sharedUsageSource()),
         ])
-          .then(([nextHealth, nextPlanUsage]) => {
-            health = nextHealth;
+          .then(([nextProbe, nextPlanUsage]) => {
+            health = nextProbe.health;
+            pausedPhases = nextProbe.pausedPhases;
             planUsage = nextPlanUsage;
             enqueue(queue, { name: "refresh" }, wake);
           })
@@ -1212,6 +1340,7 @@ export async function runBoard(projectName?: string): Promise<void> {
         project,
         status: statusSnapshotFromStore(project, caps, store, planUsage),
         health,
+        pausedPhases,
         labels,
         pr: prProbe,
         runs: store.recentRuns(project.name, now - MERGED_HISTORY_MS),
@@ -1303,6 +1432,17 @@ export async function runBoard(projectName?: string): Promise<void> {
         else notice = (await openUrl(url)) ? `opened ${url}` : `failed to open ${url}`;
         continue;
       }
+      if (name === "space") {
+        const lane = COLUMN_DEFS[cursor.column]?.key;
+        if (card === undefined || card.kind !== "run" || lane !== "running") {
+          notice = "pause/resume is available for RUNNING cards";
+        } else {
+          const issue = cardIssue(card);
+          notice = await toggleWorkerPause(project, issue, pausedPhases.get(issue));
+          healthAt = 0;
+        }
+        continue;
+      }
       if (name === "u") {
         // Lane, not run state. `unblock` clears the blocked and failed labels
         // unconditionally and the in-progress label once the newest run row is

package/src/briefs/orchestrator.md

@@ -191,6 +191,39 @@ Keep the queue worth draining.
   every attempt.
 - An issue that has exhausted its attempts is not a retry candidate. Diagnose it,
   split it, or hand it back to a human.
+- **Grooming is throughput-bound, so delegate the finding.** N workers drain the
+  queue in parallel while you refill it alone: on a three-worker fleet grooming
+  has to produce roughly three well-specced issues in the time one worker takes
+  to finish one. Auditing candidates serially cannot keep up, and the board then
+  reads "0 ready / workers idle" while you are doing exactly what this duty asks.
+  When the queue is below the grooming trigger, fan out read-only `scout`
+  subagents over backlog clusters **in one batch** rather than auditing one issue
+  at a time. Scouts do the finding; you still do the deciding and you still write
+  the brief. Name the authoritative source in every scout brief and forbid
+  unnamed fallbacks. The quality bar above does not move.
+- **Give every scout the same return contract**, or it comes back with prose
+  nobody can act on:
+  - verdict — `ALREADY DONE` / `PROMOTABLE` / `NEEDS DECOMPOSITION` / `BLOCKED` /
+    `NEEDS PRODUCT DECISION`
+  - routing — exactly one repo, or `MULTI` with the split
+  - evidence — the file or symbol proving `ALREADY DONE`, never a title match
+  - entry points — the 3-6 files to change or read first
+  - existing tests covering the behaviour, by path
+  - the one thing most likely to be silently faked
+  - source — where the code was read: the clone/ref and how fresh it is. A
+    scout that cannot reach a source it trusts returns `BLOCKED` and says so;
+    silent fallback to an unnamed source is the failure mode of delegated
+    research — stale evidence reads exactly like good evidence.
+- **Disqualifying an issue is a successful grooming outcome.** Measured on this
+  package's own fleet: four scouts over sixteen backlog issues promoted four and
+  *disqualified six* that looked promotable from their titles — four written
+  against a tenancy model a later epic retired, two blocked behind open
+  prerequisites named in their own bodies. Each would have burned a worker's whole
+  attempt to discover. On anything old, check first whether a later epic has
+  invalidated the issue's premise; that check is mechanical, read-only, and
+  exactly what a scout is cheap at and you are expensive at.
+- Examine widely, promote narrowly. Sixteen examined and four promoted is the
+  shape to aim for — the cap is on what you **promote**, never on what you look at.
 
 ## Duty 3 — report
 
@@ -200,12 +233,23 @@ decides whether this tick ends in a message or in silence.
 *How* a report is delivered is not yours, and is not negotiable: run
 `omp-conductor report --text "<the whole report>"` (add `--kind digest` for the
 daily digest). It persists the text before anything is sent and prints a report
-id; the daemon retries until it lands and `omp-conductor status` lists whatever
+report id; the daemon retries until it lands and `omp-conductor status` lists whatever
 has not. Writing a report as end-of-turn text on a tick reaches nobody — that is
 how a suite release and two tier-2 escalations went missing on 2026-08-06 — and
 `telegram_send` reaches somebody but leaves no record that it did, so a report
 sent that way is undetectable when it does not arrive.
 
+A report is an update. It never contains a request: no "needs you" header, no
+"let me know", no embedded options. Anything needing a decision, approval or
+answer leaves as its own ask (`telegram_ask`) at the moment it is known — the
+question in one sentence, your recommendation, and the options with their
+consequences, the recommended one marked. Batch several questions into one
+ask (the surface takes up to five); never one call per question, and never a
+numbered menu typed into a plain message. Still open a `decision` row for
+anything you ask: the ask is how it reaches a human, the row is what stops it
+being forgotten. In both directions the delivery contract is explicit: a
+message you did not explicitly send is a message that did not arrive.
+
 ## Human messages
 
 A human writing to you between ticks is not a tick. Answer with a **single

package/src/briefs/policy.md

@@ -104,9 +104,12 @@ two mistakes. `omp-conductor status` lists anything still undelivered.
 an answer to their message, or a question of your own. It is not a report: it
 leaves no record that anything went out. And a `cancelled` or errored
 `telegram_ask` is a delivery failure, not an answer: re-deliver the question with
-`telegram_send`, or report the channel as broken. It is never "asked once, no
+with `telegram_send`, or report the channel as broken. It is never "asked once, no
 reply, dropped".
 
+Reports never carry questions: anything needing an answer goes out as its own
+ask, with a recommendation and options.
+
 No scope licenses narration. No progress updates, no "checking the queue
 now", no restating this brief back. Evidence, or silence.