omp-conductor 0.10.0 → 0.12.0

package/README.md

@@ -1012,6 +1012,13 @@ effective value is persisted and shown beside that active run in `status`; editi
 flight. A cap that fires aborts the run, records it as `killed`, and names the
 ceiling in the escalation.
 
+Pause one live worker cooperatively with
+`omp-conductor worker pause <issue> [--project NAME]`. The daemon aborts the
+active turn to an idle harness state, freezes the remaining wall-clock budget,
+and keeps the run in the Running lane. `omp-conductor worker resume <issue>`
+continues the same session with a prompt to re-check its last action before
+proceeding. This is separate from fleet-level `pause`, which stops new claims.
+
 ### Plan allowance (`planUsage`)
 
 `dailySpendUsd` meters money, which is the only thing an API-billed account can
@@ -1587,7 +1594,8 @@ A complete, valid config for one project with two target repos:
               { "cmd": "bun run lint", "cwd": "." },
               { "cmd": "bun test", "cwd": "." }
             ],
-            "graphProject": "~/.cache/conductor-graph/acme/api"
+            "graphProject": "~/.cache/conductor-graph/acme/api",
+            "migrations": { "dir": "backend/alembic/versions" }
           },
           "worker": {
             "name": "worker",
@@ -1659,12 +1667,13 @@ Field notes:
 | `routing.repos` | At least one entry, or nothing can be routed. `name` defaults to the map key, `defaultBranch` to `main`. |
 | `gates` | The exact cheap commands CI also runs, each with the `cwd` it runs from (`cwd` defaults to `.`). Running the real gate locally is what makes an unattended push safe — a subset lets an error outside the source dir reach the runners. |
 | `graphProject` | Optional, per repo. Absolute path of the **index-only clone** whose code graph this repo's workers query — conductor's own disposable clone, pinned to the repo's default branch, never a checkout you work in and never a worker's worktree. Written by the wizard; `~` is expanded, and a relative path is an error rather than something resolved against whichever cwd happened to read the file. Absent means this repo has no graph and its briefs say nothing about one. See [Code-graph discovery](#code-graph-discovery). |
+| `migrations` | Optional, per repo: `{ "dir": "backend/alembic/versions" }`. Names the repo-relative directory of an Alembic-style ordered migration chain (`revision` / `down_revision` in `*.py`). When set, `conductor_pr_merge` **refuses** a merge that would corrupt the chain at the base tip: reusing a revision id another file already declares, deleting a published migration, or a merge that would leave the combined graph with more than one head (so a stale parent is refused, and a fork-repair merge migration that unifies the heads passes). Absent means the repo opts out of the chain check entirely. Repo-relative only: a leading `/` or `..` is an error. |
 | `caps` | Per-project overrides; omit it or pin only the fields you want to change. |
 | `escalation.fallbackToIssueComment` | Defaults to `true`. Absent means "yes, still tell me". |
 | `escalation.orchestrator` | Optional; `"embedded"` (default) or `"external"`. `external` means an orchestrator session already runs elsewhere: the daemon starts none, and tier-1 escalations post as issue comments for that session to drain. Any other value is an error. |
 | `authority` | Optional; `{ "merge": …, "release": … }`, each `"human"` (default) or `"orchestrator"`. It grants nothing to the daemon — it words the orchestrator's standing orders and the Releases paragraph of the rendered brief, so the config and the prompt cannot disagree about who holds the merge button. Unknown keys and any other value are errors, never folded to the default. |
 | `releasePolicy` | Optional; `"none"` (default) or `"operator-brief"`. `none` installs a pre-tool-call tripwire in worker, embedded-orchestrator and external-orchestrator sessions. It blocks `git tag`, tag pushes, package publishing, GitHub release creation and recognised deploy commands before execution. `operator-brief` opens that gate only for the procedure in the operator-owned brief. Unknown values are errors. Every rejection is written to `release-policy-blocks.jsonl`; the heartbeat carries that day's count into the daily digest so configured intent and observed behaviour cannot drift silently. This is the mechanical gate; `authority.release` still says who owns the decision. |
-| `reporting.scope` | Optional; `"material"` (default), `"decisions"` or `"escalations"`. Every orchestrator tick appends the matching constraint line to its prompt, re-read from this file each tick — see [Your workflow vs. the package](#your-workflow-vs-the-package). It constrains what the session is told to report; it is not an outbound filter. A config written without the key keeps reporting material events — a release never turns an existing fleet's volume down on its own. Any other value is an error, never folded to the default. |
+| `reporting` | Optional; a **legacy scope preset** (`reporting.scope` — `"material"` default, `"decisions"`, `"escalations"`) or the **explicit form** `{ "interruptOn": [...], "digest": { ... } }`. The preset writes which categories may page the operator (`interruptOn`) and when the rollup happens (`digest.cadence`); the explicit form sets both directly and the two forms are mutually exclusive in one config. See [Reporting policy](#reporting-policy-reporting). |
 | `orchestratorReadPaths` | **Retired in 0.4.3.** Still accepted in a config and ignored, so a fleet carrying it upgrades without an edit. It widened the orchestrator's file-tool allowlist; there is no allowlist any more — the orchestrator is [unconfined by design](#the-orchestrator-is-unconfined-deliberately). |
 | `policy` | Optional; the gating conditions a merge or a release must satisfy, in two sections — `policy.merge` and `policy.release`. Any member may be omitted and the loader fills it from the strict default; an unknown key in either section, or a value outside its vocabulary, is an error naming the field, never a silent downgrade. See [Merge and release preconditions](#merge-and-release-preconditions-policy). |
 | `workspaceRoot` / `mirrorRoot` | Optional; default to `worktrees/` and `mirrors/` under the state directory. `~` is expanded. |
@@ -1673,6 +1682,27 @@ Prefer an SSH `cloneUrl`, or an https URL backed by a credential helper. A clone
 with credentials embedded is persisted into the mirror's git config, exactly as it
 would be for a hand-run clone.
 
+### Reporting policy (`reporting`)
+
+What may interrupt the operator's phone, and when the daily rollup happens. Two
+spellings, mutually exclusive in one config (the loader rejects a `scope` next to
+`interruptOn`/`digest`):
+
+- **Preset** — `reporting.scope`, the three legacy values, mapped verbatim:
+  - `material` (default) → `interruptOn: [tier2, decision-needed, fleet-stopped, confirmed-failure, material]`, digest `per-tick`.
+  - `decisions` → `interruptOn: [tier2, decision-needed, fleet-stopped]`, digest `per-tick`.
+  - `escalations` → `interruptOn: [tier2, fleet-stopped]`, digest `daily` (model-timed).
+- **Explicit** — `reporting: { "interruptOn": ["tier2", "fleet-stopped", ...], "digest": { "cadence": "none" | "per-tick" | "daily" } }`.
+  `interruptOn` must be a non-empty array of known categories (`tier2`, `decision-needed`, `fleet-stopped`, `confirmed-failure`, `material`), each an escalation's tier-2 category. `daily` may add `at` (`HH:MM`, 24h) and `timezone` (a known IANA zone, defaulting to the host zone) — both only valid with `daily`.
+
+A tier-2 escalation whose category is **not** in `interruptOn` is not dropped: it
+is held (`held_notices`) and the next accepted digest is its delivery authority.
+The digest itself is at-most-once per local day (`digest:<YYYY-MM-DD>` in the
+configured zone), which remains the delivery authority across restarts. A
+scheduled `daily` digest is only sent on a day it has not already run, once the
+local clock has passed `at`; a restart after `at` still sends today's (one
+catch-up), and a fully missed day is skipped, never sent late.
+
 ### Merge and release preconditions (`policy`)
 
 These used to be sentences in your `POLICY.md`: when a PR may be merged, what
@@ -1959,6 +1989,8 @@ omp-conductor disarm [--project NAME]
 omp-conductor release-pane [--project NAME]
 omp-conductor tail <issue> [--project NAME]
 omp-conductor extend <issue> --turns N [--project NAME]
+omp-conductor worker pause <issue> [--project NAME]
+omp-conductor worker resume <issue> [--project NAME]
 omp-conductor unblock <issue> [--force] [--no-requeue] [--project NAME]
 omp-conductor verb <conductor_*> [--project NAME] [--arg k=v ...]
 omp-conductor friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]
@@ -1991,6 +2023,7 @@ omp-conductor help
 | `release-pane [--project NAME]` | Clear the `halt --pane` recovery pin so herdr-conductor may resume the fleet agent again. |
 | `tail <issue>` | Follow the newest run for that issue: the worker's assistant text as `assistant: …` and each tool it calls as `tool: <name>`, printed as they land. Workers are omp sessions inside the daemon rather than terminals, so this is the only way to watch one live — a herdr pane running it becomes an observation window. Starts from the top of the transcript, not the end, so attaching to a run that is already ten turns in shows those ten turns. Exits `1` with `no run recorded for #N` when the issue has never been dispatched, or `no transcript yet (state: …)` when the attempt has not opened one. Otherwise it runs until `Ctrl-C`, or until the run has finished and its transcript has been silent for five seconds, and prints `run ended: <state>`. |
 | `extend <issue> --turns N [--project NAME]` | Monotonically raise that live worker's effective turn ceiling through its owning daemon. The current omp session keeps running; no restart or continuation is created. The daemon persists the new ceiling for `status` and rejects missing, settled, cap-killed, equal, or lower requests instead of implying that an immutable session changed. |
+| `worker pause <issue>` / `worker resume <issue>` | Cooperatively park one live worker without changing its run state or lane. Pause aborts the active turn to harness idle and freezes the remaining wall-clock budget; resume continues the same session with a prompt to re-check its last action before repeating it. This is distinct from fleet-level `pause`, which stops new claims. |
 | `unblock <issue> [--force] [--no-requeue]` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again, and restore the project queue label by default so the dispatcher actually sees it. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label (and the queue label stays off until that run settles), and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. The label changes go through the [label projection outbox](#the-tick): they are applied inline before the command returns, but **a tracker that refuses them (403, rate limit) no longer fails the verb** — it exits `0`, the intended label state is durable and the daemon retries it, and the output says `label sync queued (N pending) — the daemon retries` instead of claiming the labels were restored. Safety is preserved, but the issue is only claimable once the queue label itself lands: the queue read asks GitHub for issues carrying that label, so a refused queue-label add keeps the issue out of dispatch until projection succeeds. `--no-requeue` clears the state labels only, leaving the queue label untouched — the case where you are about to close the issue. **Refuses, clearing nothing and exiting `3`, when the newest attempt's work could not be committed and its worktree is the only copy** — re-claiming removes that tree. `--force` records the operator's acceptance on the run row and then clears; the salvage failure stays in history. Exits `2` when the issue number is missing or malformed. |
 | `verb <conductor_*> [--arg k=v ...]` | Run one [mediated verb](#the-mediated-verbs-126) as the orchestrator, from the CLI — the external-orchestrator half of the verb surface. Every argument goes in as a `--arg k=v` string; an orchestrator can merge (`conductor_pr_merge`), label (`conductor_label`), release (`conductor_release`), update a branch (`conductor_pr_update_branch`) or title/body (`conductor_pr_update`), or read PR state (`conductor_pr_status`). The daemon applies the same checks and writes the same ledger rows a session's call would; a missing `--arg` is refused exactly as a missing tool argument is, worker-only verbs (`conductor_push`, `conductor_pr_create`) are refused with `role-not-allowed`, and a refusal exits `3`. An unknown verb exits `2`. |
 | `friction <kind> --detail TEXT [--issue N]` | Record one bounded judgment the daemon cannot infer: an escalation belonged in a digest, or a tick report was noise/surprising. The detail is limited to 160 characters. One event never changes policy; three observations inside seven days make the aggregate eligible for one Learning-loop prompt, followed by a seven-day cooldown. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

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";
@@ -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.
@@ -183,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. */
@@ -561,13 +568,15 @@ function normalizeCursor(snapshot: BoardSnapshot, cursor: BoardCursor): void {
 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}`,
   ];
@@ -719,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 (
@@ -820,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),
@@ -844,6 +865,7 @@ 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",
@@ -900,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;
@@ -921,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>(),
+  };
 }
 
 /**
@@ -1020,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?.();
@@ -1051,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()),
@@ -1059,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),
@@ -1137,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:
@@ -1183,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);
           })
@@ -1238,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),
@@ -1329,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

@@ -199,7 +199,8 @@ Keep the queue worth draining.
   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. The quality bar above does not move.
+  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` /
@@ -209,6 +210,10 @@ Keep the queue worth draining.
   - 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
@@ -228,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.
 

package/src/chain-check.ts

@@ -0,0 +1,157 @@
+/**
+ * The ordered-migration-chain guard (#227).
+ *
+ * A project that declares `routing.repos.<repo>.migrations.dir` gets its
+ * merges checked against one invariant: after the merge, the base branch's
+ * `revision`/`down_revision` graph has exactly one head. The check runs on the
+ * base tip at merge time, against the PR's diff — a stale parent, a reused
+ * revision id, or a deleted migration is refused before the merge, because a
+ * wrong merge here is silent production schema drift.
+ *
+ * Alembic-convention only (`revision = "<id>"` / `down_revision = <expr>` in
+ * `*.py`); a repo without the config key is never touched. Pure by
+ * construction: every fact arrives as strings, and the module reads no files.
+ */
+
+import type { PrDiffFile } from "./types.ts";
+
+/** One migration file's identity, as the chain check reasons about it. */
+export interface ChainEntry {
+  /** Repo-relative path of the file that declares the revision. */
+  path: string;
+  /** The revision id this file declares. */
+  id: string;
+  /** Parent revision ids; empty for a root. */
+  parents: string[];
+}
+
+const REVISION_LINE = /^\s*revision(?::[^=]*)?\s*=\s*["']([^"']+)["']/m;
+const DOWN_REVISION_LINE = /^\s*down_revision(?::[^=]*)?\s*=\s*(.*)$/m;
+const QUOTED = /["']([^"']+)["']/g;
+
+/**
+ * Parse one migration file's source into its chain identity, or `undefined`
+ * when it declares no `revision` (not a chain file; skip it).
+ *
+ * `down_revision` may be `"abc"`, `None`, or a tuple `('a', 'b')` (a merge
+ * migration) — the parents are every quoted string on the right-hand side, so
+ * `None`/empty reads as a root without special-casing syntax.
+ */
+export function parseChainSource(path: string, source: string): ChainEntry | undefined {
+  const id = REVISION_LINE.exec(source)?.[1];
+  if (id === undefined) return undefined;
+  const parents: string[] = [];
+  const rhs = DOWN_REVISION_LINE.exec(source)?.[1] ?? "";
+  for (const m of rhs.matchAll(QUOTED)) {
+    const parent = m[1];
+    if (parent !== undefined && !parents.includes(parent)) parents.push(parent);
+  }
+  return { path, id, parents };
+}
+
+/** Post-image source of one diff file: the added lines, rejoined as a file. */
+function postImageSource(file: PrDiffFile): string {
+  const hunks = file.hunks ?? "";
+  const lines: string[] = [];
+  for (const line of hunks.split("\n")) {
+    if (line.startsWith("+")) lines.push(line.slice(1));
+  }
+  return lines.join("\n");
+}
+
+/** Whether one diff entry lives inside the chain directory. */
+function inChainDir(dir: string, path: string): boolean {
+  return path.startsWith(`${dir}/`) && path.endsWith(".py");
+}
+
+/**
+ * What the PR does to the chain: entries added, entries changed (post-image
+ * used — a modified file's base entry stands when its added lines declare no
+ * revision), and chain files deleted.
+ */
+export function chainEntriesFromDiff(
+  files: readonly PrDiffFile[],
+  dir: string,
+): { added: ChainEntry[]; changed: ChainEntry[]; deleted: string[] } {
+  const added: ChainEntry[] = [];
+  const changed: ChainEntry[] = [];
+  const deleted: string[] = [];
+  for (const file of files) {
+    if (!inChainDir(dir, file.path)) continue;
+    if (file.status === "removed") {
+      deleted.push(file.path);
+      continue;
+    }
+    const entry = parseChainSource(file.path, postImageSource(file));
+    if (entry === undefined) continue;
+    if (file.status === "added") added.push(entry);
+    else changed.push(entry); // modified, or renamed into the chain directory
+  }
+  return { added, changed, deleted };
+}
+
+export interface ChainViolationInput {
+  base: ChainEntry[];
+  added: ChainEntry[];
+  changed: ChainEntry[];
+  deleted: string[];
+}
+
+/**
+ * Refuse a merge that would corrupt the ordered chain, or return [] to pass.
+ *
+ * A combined graph that no PR touches is never judged: a broken base is not
+ * this PR's problem.
+ */
+export function chainViolations(input: ChainViolationInput): string[] {
+  const touched = input.added.length + input.changed.length + input.deleted.length;
+  if (touched === 0) return [];
+
+  const violations: string[] = [];
+
+  // 1. The one deletion nothing can justify: a published migration may not
+  //    disappear from the base branch.
+  for (const path of input.deleted) {
+    if (input.base.some((entry) => entry.path === path)) {
+      violations.push(`deletes ${path}, which exists on the base branch — a published migration may never be deleted`);
+    }
+  }
+
+  // 2. Reusing an id that already exists on the base at a DIFFERENT path makes
+  //    two files claim one revision; the graph stops being an order.
+  const baseByPath = new Map(input.base.map((entry) => [entry.path, entry]));
+  for (const entry of [...input.added, ...input.changed]) {
+    const owner = input.base.find((b) => b.id === entry.id);
+    if (owner !== undefined && owner.path !== entry.path) {
+      violations.push(`reuses revision id ${entry.id}, already declared by ${owner.path} on the base branch`);
+    }
+  }
+
+  // 3. Head coherence: the combined graph — base, minus deleted files, minus
+  //    changed files' base entries (replaced by their post-image), plus added
+  //    entries — must have exactly one head. Two heads means a stale parent or
+  //    a fork nobody repaired; one head after a repair merge is the goal. A
+  //    duplicate id inside the PR's own entries is incoherent too.
+  const combined = new Map(baseByPath);
+  for (const path of input.deleted) combined.delete(path);
+  for (const entry of input.changed) combined.delete(entry.path);
+  for (const entry of [...input.changed, ...input.added]) combined.set(entry.path, entry);
+
+  const ids = [...combined.values()].map((entry) => entry.id);
+  const duplicateIds = ids.filter((id, index) => ids.indexOf(id) !== index);
+  if (duplicateIds.length > 0) {
+    violations.push(
+      `the migration graph would declare duplicate revision id${duplicateIds.length > 1 ? "s" : ""} ${[...new Set(duplicateIds)].join(", ")} after merge`,
+    );
+  }
+
+  const referenced = new Set([...combined.values()].flatMap((entry) => entry.parents));
+  const heads = ids.filter((id, index) => ids.indexOf(id) === index && !referenced.has(id));
+  if (heads.length !== 1) {
+    violations.push(
+      `the migration graph would have ${heads.length} heads after merge (${heads.join(", ") || "none"}); parent(s) must be the current tip`,
+    );
+  }
+
+  return violations;
+}