omp-conductor 0.19.7 → 0.20.1

package/src/dashboard/app.js

@@ -574,6 +574,62 @@ function orDash(value, format) {
   return value === null || value === undefined ? "—" : format(value);
 }
 
+/**
+ * The attribution block (phase 4): where the spend went, as opposed to what it
+ * bought. Rendered in the empty case too — a dry queue is exactly when the
+ * daemon's own grooming sessions run, and that spend bought no outcome, which
+ * is the number an operator most wants to see.
+ */
+function renderAttribution(out, report) {
+  const models = report.models ?? [];
+  if (models.length > 0) {
+    const box = el("div", "chart");
+    box.appendChild(el("h4", undefined, "Per model (grouped on the model actually billed)"));
+    const rows = el("div", "summary");
+    for (const m of models) {
+      // Nothing metered at all is stated as unknown: "$0.00 metered" is true and
+      // still reads as free, which is the misreading this panel exists to
+      // prevent — the same rule the CLI's human form follows.
+      const cost =
+        m.spendUsd === 0 && m.unmeteredRuns === m.runs
+          ? "cost unknown — no run on this model metered"
+          : `${usd(m.spendUsd)} metered · ${orDash(m.spendPerMerge, usd)} / merge` +
+            (m.unmeteredRuns > 0 ? ` · ${m.unmeteredRuns} unmetered` : "");
+      rows.appendChild(statLine(m.model, `${m.runs} run(s) · ${m.merges} merge(s) · ${cost}`));
+    }
+    box.appendChild(rows);
+    out.appendChild(box);
+  }
+
+  const ran = (report.sessions ?? []).filter((s) => s.sessions > 0);
+  const unmeteredRoles = report.unmeteredRoles ?? [];
+  // Silence rather than a row of zeros: "no grooming ran" and "grooming cost
+  // nothing" are different claims, and only the first would be true.
+  if (ran.length === 0 && unmeteredRoles.length === 0) return;
+  const box = el("div", "chart");
+  box.appendChild(el("h4", undefined, "Daemon-owned sessions (not worker runs)"));
+  const rows = el("div", "summary");
+  for (const s of ran) {
+    // An unmetered session's cost is unknown, so it is stated as a count and
+    // never folded into the dollar figure as a zero.
+    const cost =
+      s.spendUsd === 0 && s.unmeteredSessions === s.sessions
+        ? "cost unknown — no session metered"
+        : `${usd(s.spendUsd)} metered` +
+          (s.unmeteredSessions > 0
+            ? ` · ${s.unmeteredSessions} unmetered (cost unknown, not $0.00)`
+            : "");
+    rows.appendChild(statLine(s.role, `${s.sessions} session(s) · ${s.turns} turn(s) · ${cost}`));
+  }
+  for (const role of unmeteredRoles) {
+    rows.appendChild(
+      statLine(role, "unmetered — no usage events observable, so the cost is unknown"),
+    );
+  }
+  box.appendChild(rows);
+  out.appendChild(box);
+}
+
 function hours(ms) {
   return `${(ms / 3_600_000).toFixed(1)}h`;
 }
@@ -594,6 +650,7 @@ async function refreshStats() {
       ),
     );
     out.appendChild(statLine("GitHub API calls", String(report.ghCalls)));
+    renderAttribution(out, report);
     return;
   }
 
@@ -657,6 +714,7 @@ async function refreshStats() {
       (v) => String(v),
     ),
   );
+  renderAttribution(out, report);
 }
 
 statsWindowBar.addEventListener("click", (event) => {

package/src/dashboard/controls.ts

@@ -47,6 +47,7 @@ import { makeTracker } from "../tracker/github.ts";
 import { dbPath, openStore } from "../store.ts";
 import { loadConfig, resolveCaps } from "../config.ts";
 import { acknowledgeUpgradeRecovery } from "../upgrade-verify.ts";
+import { httpAuthHeader, missingHttpTokenMessage } from "../http-token.ts";
 import type { ProjectConfig } from "../types.ts";
 
 /** The source string every dashboard mutation attributes itself with. */
@@ -265,8 +266,24 @@ export function dashboardAnswerDecision(id: string, body: unknown, d: ControlDep
 
 // ------------------------------------------------------- production wiring --
 
-/** Forward to the living daemon's own HTTP surface, or report there is none. */
-async function defaultProxy(
+/**
+ * Forward to the living daemon's own HTTP surface, or report there is none.
+ *
+ * Every route this forwards to is mutating, so the request carries the
+ * daemon's bearer token (Phase 4). Note this is deliberately *not* the
+ * dashboard's own token: the browser authenticated to the dashboard, and the
+ * dashboard authenticates to the daemon as a second, separately-scoped hop.
+ * A missing daemon token is its own answer rather than the 502 "no living
+ * daemon" — the daemon may be perfectly alive; what is missing is the
+ * credential file, and telling the operator "start the daemon" when it is
+ * already running would send them chasing the wrong thing.
+ *
+ * Exported so the suite can drive the *production* forwarder — the one that
+ * actually builds the request — against a stub daemon. Every other test injects
+ * `ControlDeps.proxy`, which by construction cannot prove this function sends
+ * the credential.
+ */
+export async function defaultProxy(
   project: ProjectConfig,
   path: string,
   body: unknown,
@@ -277,13 +294,15 @@ async function defaultProxy(
   // would apply an operator's action to the wrong fleet.
   if (record === undefined) return undefined;
   if (record.project !== undefined && record.project !== project.name) return undefined;
+  const auth = httpAuthHeader();
+  if (auth === undefined) return { status: 503, body: { error: missingHttpTokenMessage() } };
   // Cheap liveness first, so an unreachable daemon is a 502 rather than a
   // mutation attempt that hangs the browser.
   if (!(await healthCheck(record.port)).ok) return undefined;
   try {
     const res = await fetch(`http://127.0.0.1:${record.port}${path}`, {
       method: "PUT",
-      headers: { "content-type": "application/json" },
+      headers: { "content-type": "application/json", ...auth },
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(10_000),
     });

package/src/dashboard/server.ts

@@ -331,6 +331,10 @@ async function statsProducer(name: string, since: string): Promise<StatsReport |
       window,
       ghCalls: store.ghCallsBetween(window.sinceDay, window.untilDay),
       runs: store.statsRuns(name, window.sinceEpochMs),
+      // Phase 4 attribution: daemon-owned session spend lives in its own table,
+      // deliberately outside `runs`, so it is a second read rather than more
+      // rows in the first one.
+      sessions: store.sessionSpendSince(name, window.sinceEpochMs),
     });
   } finally {
     store.close();

package/src/diff-flags.ts

@@ -438,20 +438,125 @@ const ASSERTION =
   /^(?:await\s+)?(?:expect|assert|assert_[a-z_]+|assertEquals?|assertTrue|assertFalse|assertThat|assertRaises|assertRaisesRegex|self\.assert[A-Za-z]*|should|chai\.|t\.(?:Error|Fatal)f?|require\.[A-Z][A-Za-z]*|Expect)\s*[.(]/;
 
 /**
- * A named timeout and its value. Only a *raised* one is a finding — a brand-new
- * timeout on a new test is not a weakening — so the value is compared against
- * the same key on the pre-image side and silence is the answer whenever the key
- * appears on only one side.
+ * A named timeout and its value, but only on the test runner's own timeout
+ * surface ({@link onRunnerSurface}) — a matching key handed to the code under
+ * test is a domain parameter, not a runner deadline (#1062). Only a *raised*
+ * one is a finding — a brand-new timeout on a new test is not a weakening — so
+ * the value is compared against the same key on the pre-image side and silence
+ * is the answer whenever the key appears on only one side.
  */
 const TIMEOUT =
-  /\b(timeout|timeoutMs|timeout_ms|timeoutSeconds|deadline|maxDuration|wallClock(?:Ms)?|setTimeout|jest\.setTimeout|retries)\b\s*[:=(]\s*(\d[\d_]*)/gi;
+  /\b(timeout|timeoutMs|timeout_ms|timeoutSeconds|deadline|maxDuration|wallClock(?:Ms)?|setTimeout|jest\.setTimeout|retries)\b\s*([:=(])\s*(\d[\d_]*)/gi;
+
+/** Identifiers that name the test runner itself when a timeout-shaped key is
+ *  called on or passed to them. `t` is the test context (vitest, node:test, a
+ *  Go `*testing.T` helper); `pytest` names the Python runner module. */
+const RUNNER_BINDINGS: Record<string, true> = {
+  test: true,
+  it: true,
+  describe: true,
+  context: true,
+  suite: true,
+  bench: true,
+  jest: true,
+  t: true,
+  pytest: true,
+};
+
+/**
+ * Whether a {@link TIMEOUT} match sits on the runner's own timeout surface of
+ * its line, as opposed to an argument handed to the code under test.
+ *
+ * The audit sees hunks, not files, so the judgement is structural on the
+ * changed line alone, and anything it cannot vouch for stays silent: a flag is
+ * advisory, and a false positive costs the trust in every flag after it
+ * (measured: #614/#896 read a raised `timeoutMs` passed to `arm(...)` — the
+ * challenge window of the code under test — as a weakened test).
+ *
+ * Two positions qualify, both on the runner's own call:
+ *
+ * - the key is called on the runner — `jest.setTimeout(...)`,
+ *   `t.timeout(...)`, `test.setTimeout(...)`, `pytest.mark.timeout(...)` —
+ *   the dotted receiver before the key starts with a runner binding;
+ * - the key is a property of an object literal that is a direct argument of a
+ *   runner call — the trailing per-test configuration: `test("x", fn, {
+ *   timeout: 45_000 })`, `test.use({ retries: 3 })`,
+ *   `describe.configure({ retries: 3 })`.
+ *
+ * Everything else is the code under test: `await arm({ timeoutMs: 60_000 })`,
+ * `const opts = { timeout: 45000 }`, `server.setTimeout(30_000)`. A shape
+ * whose decisive frame is on another line — `}, { timeout: 45000 });` after a
+ * multi-line `test(` — cannot be vouched for from the line alone and also
+ * stays silent.
+ */
+function onRunnerSurface(code: string, match: RegExpMatchArray): boolean {
+  const key = match[1]?.toLowerCase() ?? "";
+  if (RUNNER_BINDINGS[key.split(".")[0] ?? ""] === true) return true;
+
+  const before = code.slice(0, match.index);
+  // The dotted receiver the key is called on: `t.timeout(5000)` reads `t.`,
+  // `pytest.mark.timeout(500)` reads `pytest.mark.`. No receiver — a bare
+  // `timeout: 5000` property — falls through to the config-object rule.
+  let at = before.length - 1;
+  while (at >= 0 && /[A-Za-z0-9_$.]/.test(before[at] ?? "")) at--;
+  const receiver = before.slice(at + 1).replace(/\.$/, "").split(".")[0];
+  if (RUNNER_BINDINGS[receiver ?? ""] === true) return true;
+
+  // A property key (`key: value`) needs the object around it to be the
+  // runner's own configuration; a `key = value` assignment or a bare
+  // `key(5000)` call on the line is never that.
+  if (match[2] !== ":") return false;
+  return inRunnerConfigObject(before);
+}
+
+type RunnerFrame = { kind: "call"; base: string | undefined } | { kind: "obj" };
+
+/** Whether the key sits in an object literal that is a direct argument of a
+ *  call on a runner binding — the trailing per-test configuration:
+ *  `test("x", fn, { timeout: 45_000 })`, `test.use({ retries: 3 })`,
+ *  `describe.configure({ retries: 3 })`. The frames are walked over the line
+ *  prefix only, with strings already stripped by {@link splitCode}, so the
+ *  object's nesting inside the call — a direct argument versus a property of
+ *  a nested object or of the callback's own body — decides the verdict. */
+function inRunnerConfigObject(before: string): boolean {
+  const frames: RunnerFrame[] = [];
+  for (let at = 0; at < before.length; at++) {
+    const ch = before[at];
+    if (ch === "(") {
+      // The dotted name the call was opened on, if any: `test.use(` reads
+      // `test.use`. No name — an arrow's parameter list, or a call on a
+      // previous call's result — means the object below it is not a runner
+      // surface.
+      let end = at;
+      while (end > 0 && /[A-Za-z0-9_$.]/.test(before[end - 1] ?? "")) end--;
+      const chain = before.slice(end, at);
+      frames.push({
+        kind: "call",
+        base: chain.length > 0 && !chain.endsWith(".") ? chain : undefined,
+      });
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
+      frames.push({ kind: "obj" });
+      continue;
+    }
+    if (ch === ")" || ch === "}" || ch === "]") frames.pop();
+  }
+  const object = frames.at(-1);
+  if (object?.kind !== "obj") return false;
+  const enclosing = frames.at(-2);
+  if (enclosing?.kind !== "call") return false;
+  const firstSegment = enclosing.base?.split(".")[0];
+  return firstSegment !== undefined && RUNNER_BINDINGS[firstSegment] === true;
+}
 
 function timeouts(text: string): { key: string; value: number }[] {
   const found: { key: string; value: number }[] = [];
   for (const match of text.matchAll(TIMEOUT)) {
     const key = match[1]?.toLowerCase();
-    const raw = match[2]?.replaceAll("_", "");
+    const raw = match[3]?.replaceAll("_", "");
     if (key === undefined || raw === undefined) continue;
+    if (!onRunnerSurface(text, match)) continue;
     const value = Number(raw);
     if (Number.isSafeInteger(value)) found.push({ key, value });
   }
@@ -813,14 +918,35 @@ function claimRegion(body: string): string {
   return next === null ? rest : rest.slice(0, marker[0].length + next.index);
 }
 
+/**
+ * An executable token: the shape a claimed command's first word must have to
+ * be a program somebody could have run. Either an ordinary command name — an
+ * ASCII letter or `_` first, then letters, digits, `_`, `.`, `+`, `-` (`bun`,
+ * `bash`, `cd`, `export`, `omp-conductor`, `python3.12`) — or a `./`-relative
+ * executable path built from those same characters plus `/`
+ * (`./scripts/deploy.sh`).
+ *
+ * Nothing else is a command, and that exclusion is the whole point (#1039):
+ * this predicate used to accept any first word that merely lacked a `/`, so
+ * the malformed-JSON fixture `{not json` described in a PR's verified prose
+ * became a "claimed" command with no transcript match, and a green PR settled
+ * with a false `claimed-proof-missing`. The grammar therefore refuses
+ * punctuation-led fragments (`{not`, `{"kind":`, `[1,`), quote-led values
+ * (`"some value"`), tokens carrying `:` or `=` (config expressions like
+ * `retry.modelFallback: true`, env assignments), digit-led data literals
+ * (timestamps like `2026-08-24 09:14Z`) and flag-led spans (`--json`). An
+ * absolute path stays excluded as it always was: it carries `/` without the
+ * leading `./`.
+ */
+const EXECUTABLE_TOKEN = /^(?:[A-Za-z_][A-Za-z0-9_.+-]*|\.\/[A-Za-z0-9_.+\-/]+)$/;
+
 /** One backticked span that reads as a whole command: at least two shell words
- *  and a first word that is an executable (no path separator, or a `./` one).
+ *  and a first word that is an {@link EXECUTABLE_TOKEN}.
  *  A span that names a single file or a config key is not a command claim. */
 function claimedCommand(span: string): boolean {
   const words = span.split(/\s+/).filter((word) => word.length > 0);
   if (words.length < 2) return false;
-  const first = words[0] ?? "";
-  return first.startsWith("./") || !first.includes("/");
+  return EXECUTABLE_TOKEN.test(words[0] ?? "");
 }
 
 /**

package/src/doctor.ts

@@ -1345,8 +1345,8 @@ function armAckProbe(probes: Probes, p: ProjectConfig): Finding {
   if (sighting.expiresAt !== undefined && now >= sighting.expiresAt) {
     return warnFinding(
       "arm-ack",
-      `[${p.name}] an arming challenge from ${window} expired without being settled — it is inert (replies past expiry are refused), but it lingers until this project's next arm replaces it`,
-      `no action needed; the next \`arm\` for this project settles it — re-run doctor afterwards to confirm`,
+      `[${p.name}] an arming challenge from ${window} expired without being settled — it is inert (replies past expiry are refused); the fleet session notifies the operator and clears it once its notice goes out, or the next arm replaces it`,
+      `the code is dead — no reply to it can arm. Re-run the ceremony: \`omp-conductor arm --project ${p.name}\``,
     );
   }
   if (sighting.acknowledgedAt !== undefined) {

package/src/failure-class.ts

@@ -34,6 +34,14 @@ export interface ClassifyFacts {
    *  reachable. Lets the table tell an infrastructure outage (#177) from a
    *  deterministic test failure by the log's own words. */
   failingLog?: string;
+  /** The PR's changed-file list, derived at the settle call site from the
+   *  diff the settlement already fetches (#1059). Lets the table tell a
+   *  Compose dependency-startup failure no PR could have caused from one a
+   *  PR's own diff did — a PR that touches no container configuration cannot
+   *  have broken `docker compose up`. Absent means the diff could not be
+   *  read (or was cut short), which is "could not tell": the conditional
+   *  signature below then stays silent and the attempt is charged. */
+  changedFiles?: string[];
 }
 
 export interface Classification {
@@ -62,6 +70,16 @@ const INFRA_CHECK_STATES: Record<string, true> = {
 /** States that mean "this check has a verdict and it is good". */
 const SUCCESS_CHECK_STATES: Record<string, true> = { success: true, neutral: true };
 
+/**
+ * The runner's own sentence for "the agent under this job went away": written
+ * when the runner service is stopped, auto-updates, or is torn down under a
+ * live job. Named once because two different accountings quote it — the
+ * implementation-attempt waiver below ({@link INFRA_LOG_SIGNATURES}, #177) and
+ * the review-correction waiver ({@link runnerInfraFailure}) — and a second
+ * spelling of it would waive one while charging the other.
+ */
+const RUNNER_SHUTDOWN_SIGNAL = "the runner has received a shutdown signal";
+
 /**
  * Substrings in a failed check's log that prove the failure was infrastructure,
  * not the diff (#177). Each is a registry/docker/runner fault a worker cannot
@@ -87,7 +105,7 @@ const INFRA_LOG_SIGNATURES = [
   // the runner's, and must not be waived (#637, #639).
   "response status code does not indicate success: 429 (too many requests)",
   "failed to resolve source metadata for",
-  "the runner has received a shutdown signal",
+  RUNNER_SHUTDOWN_SIGNAL,
   "could not resolve host",
 ];
 
@@ -103,6 +121,70 @@ export function infraLogSignature(log: string): string | undefined {
   return INFRA_LOG_SIGNATURES.find((signature) => lower.includes(signature));
 }
 
+/**
+ * Runner-infrastructure wordings: a red check whose own text says the *runner*
+ * failed, not the diff (Phase 3, #1043 lane). Matched lowercased as substrings
+ * against the failing job's log — the same surface {@link infraLogSignature}
+ * reads — and each entry is the real GitHub Actions sentence, verified against
+ * the runner's own reports rather than invented:
+ *
+ * Kept as its own list rather than folded into {@link INFRA_LOG_SIGNATURES}
+ * for two reasons. The consumers differ: that list waives an *implementation
+ * attempt* for a settled run (#177), this one waives a *correction round* for
+ * a live pull request's red check. And {@link infraSignatureVersion} is a
+ * persisted cursor fingerprint — growing that list restarts the historical
+ * reconciliation, which recognising a runner-lost red has no business doing.
+ * The one overlap, {@link RUNNER_SHUTDOWN_SIGNAL}, is shared by reference so
+ * the two accountings can never disagree about that wording.
+ */
+const RUNNER_INFRA_SIGNATURES = [
+  // "The self-hosted runner: <name> lost communication with the server." and
+  // its hosted sibling "The hosted runner: <name> lost communication with the
+  // server." — the runner process was killed, starved or cut off mid-job
+  // (actions/runner#3539, community#84877, community#173431). The name varies,
+  // so only the invariant tail is matched.
+  "lost communication with the server",
+  // The runner service was stopped or auto-updated under the job: an
+  // infrastructure cancellation, not a verdict on the diff.
+  RUNNER_SHUTDOWN_SIGNAL,
+  // "The job was not acquired by Runner of type hosted even after multiple
+  // attempts" — the job never reached a runner at all, so nothing in the diff
+  // was ever executed (community#186216, community#165287).
+  "was not acquired by runner",
+  // "The hosted runner encountered an error while running your job. (Error
+  // Type: Failure)." — GitHub's own statement that its runner broke
+  // (community#126539). The parenthesised error type varies; the sentence does
+  // not.
+  "the hosted runner encountered an error while running your job",
+];
+
+/**
+ * The runner-infrastructure wording a red CI check's text carries, or
+ * `undefined` when it carries none.
+ *
+ * Exists so the review-correction accounting can decline to charge a
+ * correction round for a red that the worker's diff did not cause: a lost
+ * runner, a runner shut down under the job, or a job no runner ever picked up.
+ * The return value is the matched wording, so whatever waives a round can say
+ * *which* sentence waived it instead of asserting "infra" unexplained.
+ *
+ * Fails closed in both directions, and deliberately narrower than it could be:
+ *
+ * - Unclassifiable, empty or unread text is `undefined` — an unexplained red
+ *   still counts, and a log-fetch failure hands this function nothing to match,
+ *   so it never waives.
+ * - "The operation was canceled." is *not* here: it is what a failed `needs:`
+ *   dependency and an operator's own cancel both print, so matching it would
+ *   waive rounds for ordinary red.
+ * - "…has exceeded the maximum execution time of N minutes" is *not* here
+ *   either: a job that ran until the ceiling is usually a hanging test or an
+ *   infinite loop, which is exactly the diff's problem to fix.
+ */
+export function runnerInfraFailure(log: string): string | undefined {
+  const lower = log.toLowerCase();
+  return RUNNER_INFRA_SIGNATURES.find((signature) => lower.includes(signature));
+}
+
 /**
  * The cap kills that produced nothing: the worker reached a ceiling with no PR,
  * no observed head and no salvage commit.
@@ -134,6 +216,62 @@ export function infraSignatureVersion(): string {
   return INFRA_LOG_SIGNATURES.join("|");
 }
 
+/**
+ * Compose's own sentence for a dependency that failed its healthcheck during
+ * `docker compose up`: "dependency failed to start: container
+ * chad-postgres-1 is unhealthy" (#1059). Matched with its trailing context,
+ * never a bare `is unhealthy` — that phrase is common enough in application
+ * logs to be unsafe on its own. Shared with the settle call site so the diff
+ * fetch and the classifier can never disagree about which log sentence needs
+ * the changed-file list.
+ */
+export const COMPOSE_DEPENDENCY_STARTUP_SIGNATURE =
+  "dependency failed to start: container ";
+
+/**
+ * A changed path that configures the containers Compose jobs run, or the
+ * workflow that invokes them: a compose file — `docker-compose*.ya?ml`,
+ * Compose v2's default `compose.ya?ml`, or any `*.ya?ml` directly inside a
+ * `compose/` directory (#1071) — anywhere in the tree, a `Dockerfile*`, or
+ * anything under `.github/workflows/`. A PR touching any of these can have
+ * broken `docker compose up` itself — that is what turns the signature below
+ * from infrastructure into a charged, deterministic failure. Matched
+ * case-insensitively: the price of missing a container file is waiving a
+ * genuine attempt, while a false positive (a path merely *named* like one)
+ * only charges one.
+ */
+const CONTAINER_CONFIG_PATH =
+  /(?:^|\/)(?:docker-compose[^/]*\.ya?ml|compose\.ya?ml|compose\/[^/]+\.ya?ml|Dockerfile[^/]*)$|(?:^|\/)\.github\/workflows\//i;
+
+/**
+ * Evidence that a failed check's log names a Compose dependency-startup
+ * failure, or `undefined` when the log does not name one or the PR's own diff
+ * could have caused it (#1059).
+ *
+ * Deliberately conditional on the PR's changed-file list, and deliberately
+ * left out of {@link INFRA_LOG_SIGNATURES}: a job that runs `docker compose`
+ * can be broken by the diff itself — a bad `docker-compose.yml` in a PR
+ * produces this exact sentence — so the blanket signature would waive the
+ * implementation attempt for a real defect. Only when the diff touches no
+ * compose file, no Dockerfile and no workflow is the fault one the PR cannot
+ * have introduced, and the recovery (`rerun-checks`) is bounded by the strike
+ * cap either way.
+ *
+ * Fails closed: `undefined` changedFiles is "could not read the diff", never
+ * "clean", and stays silent — an unknown or truncated diff must not waive an
+ * attempt.
+ */
+export function composeDependencyStartup(
+  log: string,
+  changedFiles: string[] | undefined,
+): string | undefined {
+  if (changedFiles === undefined) return undefined;
+  const lower = log.toLowerCase();
+  if (!lower.includes(COMPOSE_DEPENDENCY_STARTUP_SIGNATURE)) return undefined;
+  if (changedFiles.some((path) => CONTAINER_CONFIG_PATH.test(path))) return undefined;
+  return COMPOSE_DEPENDENCY_STARTUP_SIGNATURE.trim();
+}
+
 /** Lowercased check state — `gh pr checks` has emitted both `failure` and
  *  `FAILURE` across versions, and the classifier's callers must agree on one
  *  spelling so log selection and classification see the same set of checks. */
@@ -527,6 +665,69 @@ export function noVerdictExit(run: RunRecord): string | undefined {
   return `the session ended without delivering a settlement verdict; last words: "${lastWords.slice(0, 80)}"`;
 }
 
+/** A reliable PR reference inside a blocker's prose: a `PR #N`/
+ *  `pull request #N` mention or a GitHub `…/pull/N` URL. Named once so the
+ *  evidence's "the next act is an observation of this PR" claim and the code
+ *  that finds the PR stay one pattern (#1068). */
+const PR_REFERENCE_PATTERN =
+  /(?:PR|pull request)\s+#?\s*\d+|github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+/i;
+
+/**
+ * The `blockers:` list of a blocked settlement's stored report, in order
+ * (#1068). The worker's structured yield renders one item per blocker as
+ * `  - <item>` under a `blockers:` heading, and prose settlements that use the
+ * same heading parse the same way. `undefined` when the report carries no
+ * such section — a report that names no blockers and a missing report read
+ * identically, which is honest: the worker did not name a condition to
+ * observe.
+ */
+function blockedSettlementBlockers(report: string | undefined): string[] | undefined {
+  if (report === undefined) return undefined;
+  const blockers: string[] = [];
+  let inBlockers = false;
+  for (const line of report.split("\n")) {
+    if (inBlockers) {
+      const item = /^ {2,}-\s+(.*)$/.exec(line);
+      if (item === null) break;
+      blockers.push(item[1]!.trim());
+      continue;
+    }
+    if (/^blockers:\s*$/i.test(line)) inBlockers = true;
+  }
+  return blockers.length === 0 ? undefined : blockers;
+}
+
+/**
+ * An explicit question in the blocked row's own words, or `undefined` when the
+ * row names none (#1068). The worker's question travels in the pre-existing
+ * `lastError` slot, or as a `blockers:` item that ends interrogative; a
+ * blocker that names a condition to observe ("PR #1067 checks still
+ * pending…") is not a question. Quoted verbatim into the escalation evidence,
+ * because the orchestrator answers the worker's own words rather than a
+ * paraphrase.
+ */
+function blockedQuestion(run: RunRecord): string | undefined {
+  if (run.lastError !== undefined && run.lastError.trim() !== "") return run.lastError;
+  return blockedSettlementBlockers(run.report)?.find((b) => /[?？]\s*$/.test(b));
+}
+
+/**
+ * The report's first substantive line: skips the `status:`/`pr:`/`branch:`/
+ * `head:` headers and blank lines a structured settlement puts on top, and
+ * bounds the quote so a prose dump cannot balloon an evidence line. `undefined`
+ * when the report is empty or carries nothing but scaffold.
+ */
+function firstReportContentLine(report: string | undefined): string | undefined {
+  if (report === undefined) return undefined;
+  for (const raw of report.split("\n")) {
+    const line = raw.trim();
+    if (line === "") continue;
+    if (/^(?:status|pr|branch|head):\s*\S/.test(line)) continue;
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+  }
+  return undefined;
+}
+
 export function classifyRun(
   run: RunRecord,
   facts: ClassifyFacts,
@@ -670,10 +871,44 @@ export function classifyRun(
   }
 
   if (run.state === "blocked") {
+    // `blocked` is overloaded (#1068). A worker that finishes its work and
+    // stops because it is waiting on an observable condition — almost always
+    // its PR's checks — records that condition as `blockers:` in its
+    // settlement report; a worker that stops to ask records an actual
+    // question. Only the second shape is a human escalation: the first names
+    // the next act (observe, then the sweep settles the row the way it
+    // settles `settlement-stuck` when the PR resolves), so escalating it
+    // wakes the orchestrator for a question that does not exist and the act
+    // that *is* required appears nowhere. The evidence never claims the
+    // worker "left no report" — it quotes the question or the first blocker,
+    // and when the report genuinely is empty it says which fields are.
+    const question = blockedQuestion(run);
+    if (question !== undefined) {
+      return { cls: "question", recovery: "escalate", evidence: question };
+    }
+    const blockers = blockedSettlementBlockers(run.report);
+    if (blockers !== undefined) {
+      // Prefer the blocker that names a PR: the reader's next act is an
+      // observation of that PR and a merge, and the evidence must say so.
+      const named = blockers.find((b) => PR_REFERENCE_PATTERN.test(b)) ?? blockers[0]!;
+      return {
+        cls: "awaiting-observation",
+        recovery: "observe",
+        evidence: `waiting on ${named}`,
+      };
+    }
+    const reportEmpty = run.report === undefined || run.report.trim() === "";
+    const firstContent = firstReportContentLine(run.report);
     return {
       cls: "question",
       recovery: "escalate",
-      evidence: run.lastError ?? "the worker stopped to ask a question and left no report",
+      evidence: reportEmpty
+        ? `the worker stopped without a run report (run.report is empty${
+            run.lastError === undefined || run.lastError.trim() === "" ? "; lastError is empty too" : ""
+          })`
+        : firstContent === undefined
+          ? "the worker stopped without asking a question or naming a blocker (run.report is non-empty but has no readable content)"
+          : `the worker stopped without asking a question or naming a blocker — ${firstContent}`,
     };
   }
 
@@ -780,6 +1015,26 @@ export function classifyRun(
             evidence: `infrastructure signature in ${check?.name === undefined ? "failed check" : check.name} log: "${signature}"`,
           };
         }
+        // A Compose dependency-startup failure is infra only when the PR's
+        // diff could not have caused it (#1059): a job that runs `docker
+        // compose` is broken by a PR that breaks its own compose file, and
+        // that attempt is genuinely spent. The settlement hands the
+        // classifier the PR's changed-file list, so "did this diff touch any
+        // container configuration" is a fact, not a guess from the log alone.
+        // Absent list (or a log without the sentence) stays silent and the
+        // row reads `ci-deterministic`.
+        const compose = composeDependencyStartup(facts.failingLog, facts.changedFiles);
+        if (compose !== undefined) {
+          const check = checks.find((c) => normalise(c.state) === "failure");
+          return {
+            cls: "ci-infra",
+            recovery: "rerun-checks",
+            // Both halves, so the evidence says *which* sentence matched and
+            // *why* it was not the diff's fault — the changed-file list
+            // showed no container configuration.
+            evidence: `infrastructure signature in ${check?.name === undefined ? "failed check" : check.name} log: "${compose}" — the PR diff touches no container configuration, so the PR cannot have failed this check`,
+          };
+        }
       }
       const failing = unresolved.filter((c) => normalise(c.state) === "failure");
       if (failing.length > 0) {