omp-conductor 0.20.0 → 0.20.1

package/src/orchestrator-tick.ts

@@ -46,7 +46,7 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { availabilityPrompt, interruptDisposition } from "./availability.ts";
 import {
@@ -132,6 +132,20 @@ import {
   type ToSpecTrackerSeam,
 } from "./groom.ts";
 import { heldNoticeId } from "./notices.ts";
+import {
+  clearArmTransaction,
+  expiredArmChallenges,
+  FLEET_ARM_KEY,
+  resolveArmReply,
+  type ArmChallengeSighting,
+  type ArmReplyMatch,
+} from "./arm-challenge.ts";
+import {
+  readTelegramChannel,
+  readTelegramToken,
+  resolveProjectTopicId,
+  sendTelegram,
+} from "./escalate.ts";
 
 /** The activation file. Absent means "this is not an orchestrator session". */
 export const TICK_CONFIG_FILE = ".conductor-tick.json";
@@ -489,6 +503,10 @@ const AUTONOMOUS_RECOVERY_ACTIONS: Record<RecoveryAction, boolean> = {
   "rerun-checks": true,
   settle: true,
   escalate: false,
+  // An observation row never stamps `recoveredAt` (the recovery IS the later
+  // sweep pass), so it never lands in this digest; `false` is the honest value
+  // if one ever did — it is not "already handled", it is waiting (#1068).
+  observe: false,
   hold: false,
   none: false,
 };
@@ -1638,6 +1656,20 @@ export function resolveArmState(armedFile: string, projectName?: string): ArmSta
   return shared ? { armed: true } : { armed: true, legacy: "honoured" };
 }
 
+/**
+ * The one armed-marker write both settlement paths share — the CLI's
+ * `arm --reply` half and the orchestrator session's mechanical reply consumer
+ * (#1061): same content, same mode, and the same restamp of the pre-per-project
+ * shared marker the heartbeat still honours (#316). It lives here, beside
+ * {@link resolveArmState}, so the session consumer can write the gate it reads
+ * — the reverse import (into `fleet.ts`) would cycle.
+ */
+export function writeArmedMarker(path: string, owner: string, arm: ArmState): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `armed ${new Date().toISOString()} owner=${owner}\n`, { mode: 0o600 });
+  if (arm.legacy === "honoured") rmSync(legacyArmedMarkerPath(), { force: true });
+}
+
 /**
  * Best-effort recompose of `ORCHESTRATOR.md` from the installed package floor +
  * live `POLICY.md`.
@@ -2854,6 +2886,7 @@ async function tick(
   config: TickConfig,
   session: TickSession,
   toSpecTrackerSeam: ToSpecTrackerSeam | undefined,
+  armSeam: ArmConsumerSeam | undefined,
 ): Promise<void> {
   const live = currentConfig(ctx.cwd, config);
   const arm = live.armedFile === undefined ? undefined : resolveArmState(live.armedFile, live.project);
@@ -2863,6 +2896,29 @@ async function tick(
       `[omp-conductor] ${legacyArmedMarkerPath()}: ${LEGACY_ARM_MARKER_DETAIL} — this heartbeat stays disarmed`,
     );
   }
+  // An unanswered ceremony that passed its window is a dead ceremony, not a
+  // silent one (#1061): the tick that notices tells the operator why and how
+  // to re-run it, on the surface the challenge was sent to. Deliberately
+  // before the tick gate — a disarmed fleet is exactly the state an
+  // unanswered challenge leaves, and its death notice must not wait for an
+  // arm to be heard. The scan is synchronous so an idle host (no expired
+  // records) costs the tick nothing; only a send is awaited.
+  const armNow = (armSeam?.now ?? Date.now)();
+  for (const expired of expiredArmChallenges(live.project, armNow)) {
+    const surface: ArmNoticeSurface = { accessFile: live.accessFile, project: live.project };
+    const send = armSeam?.notify ?? sendArmNotice;
+    try {
+      await send(armExpiryNotice(expired, live.project), surface);
+    } catch (err) {
+      // Keep the record: the next heartbeat retries, and `doctor` still
+      // reports it.
+      pi.logger.error(
+        `[omp-conductor] arm expiry notice not delivered: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      continue;
+    }
+    clearArmTransaction(expired.key, expired.id);
+  }
   const decision = tickDecision({
     armed: arm === undefined || arm.armed,
     channelOk: live.accessFile === undefined || channelIsUp(live.accessFile),
@@ -3371,11 +3427,12 @@ function armTickHeartbeat(
   config: TickConfig,
   session: TickSession,
   toSpecTrackerSeam: ToSpecTrackerSeam | undefined,
+  armSeam: ArmConsumerSeam | undefined,
 ): void {
   writeTickRuntimeStatus(pi, ctx.cwd, config.intervalSeconds);
   const runScheduledTick = async (): Promise<void> => {
     try {
-      await tick(pi, ctx, config, session, toSpecTrackerSeam);
+      await tick(pi, ctx, config, session, toSpecTrackerSeam, armSeam);
     } finally {
       writeTickRuntimeStatus(pi, ctx.cwd, config.intervalSeconds);
     }
@@ -3431,7 +3488,7 @@ function armTickHeartbeat(
   // call runs inside the session_start handler dispatch, which cannot see an
   // async rejection — an escaped one reaches the process-level
   // unhandledRejection handler and takes the session down.
-  void tick(pi, ctx, config, session, toSpecTrackerSeam).catch((err) => {
+  void tick(pi, ctx, config, session, toSpecTrackerSeam, armSeam).catch((err) => {
     pi.logger.error(
       `[omp-conductor] arm-time tick failed: ${err instanceof Error ? err.message : String(err)}`,
     );
@@ -3496,6 +3553,209 @@ export interface OrchestratorTickExtensionOptions {
    * present-tense empty queue.
    */
   toSpec?: { tracker?: ToSpecTrackerSeam };
+  /**
+   * The arm ceremony's mechanical consumer seams (#1061). Production omits
+   * them and the extension classifies inbound turns against the pending
+   * challenge records itself, sending confirmations and expiry notices over
+   * the same bridge transport `armTicks` sends the challenge on. Tests inject
+   * a recorder (`notify`) and a fixed clock (`now`) so the settle and the
+   * notices are provable without Telegram or timers.
+   */
+  arm?: {
+    now?: () => number;
+    notify?: ArmNoticeFn;
+  };
+}
+
+/** The send surface an arm notice rides: the live tick config's channel and project. */
+export interface ArmNoticeSurface {
+  accessFile?: string;
+  project?: string;
+}
+
+/**
+ * One mechanical Telegram send the arm consumer raises: the confirmation when
+ * a reply settles the ceremony, or the expiry notice when a challenge dies
+ * unanswered. The default is {@link sendArmNotice}; tests record instead.
+ */
+export type ArmNoticeFn = (text: string, surface: ArmNoticeSurface) => Promise<void> | void;
+
+/** The consumer's injectable clock and transport, carried into the tick's helpers. */
+export interface ArmConsumerSeam {
+  now?: () => number;
+  notify?: ArmNoticeFn;
+}
+
+/**
+ * The plain text of an inbound message, for the arm classifier. Content blocks
+ * join with newlines so a code split across block boundaries still tokenises
+ * whole; non-text blocks contribute nothing. `undefined` for an absent or
+ * empty message, which is ordinary chat either way.
+ */
+function inboundMessageText(content: readonly { type?: string; text?: string }[] | undefined): string | undefined {
+  if (content === undefined || content.length === 0) return undefined;
+  const text = content.map((block) => block.text ?? "").join("\n");
+  return text.length === 0 ? undefined : text;
+}
+
+/**
+ * The ready-to-send expiry notice: the reason — never answered, or answered
+ * but never settled — and the exact command that re-runs the ceremony. The
+ * code is the proof and is never named in a notice; only the window is.
+ */
+function armExpiryNotice(expired: { key: string; sighting: ArmChallengeSighting }, project: string | undefined): string {
+  const reissue =
+    expired.key === FLEET_ARM_KEY || project === undefined || project === ""
+      ? "omp-conductor arm"
+      : `omp-conductor arm --project ${project}`;
+  const sentAt =
+    expired.sighting.sentAt === undefined
+      ? ""
+      : ` sent ${new Date(expired.sighting.sentAt).toISOString()}`;
+  const reason =
+    expired.sighting.acknowledgedAt === undefined
+      ? `The arming challenge${sentAt} expired without being answered — nothing is armed.`
+      : `The arming challenge${sentAt} was answered but never settled before its window closed — nothing is armed.`;
+  return `${reason} Send a fresh one: ${reissue}`;
+}
+
+/**
+ * The default transport for the arm consumer's confirmation and expiry
+ * notices: the same bot token, paired channel and project topic `armTicks`
+ * sends the challenge on, so the notice lands on the surface the operator was
+ * asked in. Deliberately not availability-gated — the ceremony is the
+ * operator's own interaction, exactly like the challenge send itself, and a
+ * notice held for quiet hours would be the silent failure #1061 removes. Any
+ * missing or down fact throws; the caller logs and keeps the challenge record
+ * so the next heartbeat retries and `doctor` still reports it.
+ */
+export async function sendArmNotice(text: string, surface: ArmNoticeSurface): Promise<void> {
+  if (surface.accessFile === undefined) {
+    throw new Error("no accessFile — the arm notice has no channel");
+  }
+  const channel = readTelegramChannel(surface.accessFile);
+  if (channel.kind === "down") {
+    throw new Error(`escalation channel is not up (${surface.accessFile}): ${channel.reason}`);
+  }
+  const token = readTelegramToken();
+  if (token === undefined) {
+    throw new Error("no Telegram bot token readable — the arm notice cannot send");
+  }
+  let topicId: number | undefined;
+  if (surface.project !== undefined) {
+    try {
+      topicId = resolveProjectTopicId(findProject(loadConfig(), surface.project));
+    } catch {
+      /* no project config — flat chat, exactly like armTicks */
+    }
+  }
+  await sendTelegram(token, channel.owner, text, { topicId });
+}
+
+/**
+ * The settle half of the mechanical consumer: write the markers the matched
+ * challenge recorded and clear its transaction, then confirm on the
+ * challenge's surface. The recorded targets are the contract — the exact rule
+ * `armReply` applies — so nothing is ever armed that the challenge did not
+ * name. A pre-targets record (one release of overlap) is not settled here:
+ * nothing in-session may guess a marker the challenge never recorded; the CLI
+ * half still settles it, and the operator is told so.
+ */
+function settleInboundArmMatch(
+  pi: TickApi,
+  match: ArmReplyMatch,
+  notify: (text: string) => void,
+): void {
+  if (match.targets === undefined || match.owner === undefined) {
+    pi.logger.error(
+      "[omp-conductor] an inbound arming code matched a pre-targets challenge — nothing armed in-session; " +
+        'run `omp-conductor arm --reply "<the reply>"` to settle it',
+    );
+    return;
+  }
+  for (const target of match.targets) {
+    const state = resolveArmState(target.armedFile, target.project);
+    writeArmedMarker(target.armedFile, match.owner, state);
+  }
+  clearArmTransaction(match.key, match.id);
+  const label =
+    match.targets.length === 1 && match.targets[0]!.project !== undefined
+      ? `project ${match.targets[0]!.project}`
+      : `${match.targets.length} project(s)`;
+  notify(`Arming verified — ${label} armed. The reply was consumed; nothing else to do.`);
+}
+
+/**
+ * The arm ceremony's mechanical consumer (#1061): classify one inbound user
+ * turn against this host's pending challenges and, on a match, settle the
+ * ceremony exactly as `omp-conductor arm --reply` would — markers for the
+ * recorded targets, transaction cleared, a confirmation on the surface the
+ * challenge was sent to. This is the real owner the ceremony needed on a host
+ * with no console session: the challenge goes to the project topic, which is
+ * this pane's own claimed surface, so the reply lands here and the ceremony
+ * completes with no second human command. A code past its window is answered
+ * with the re-run command and the dead record is cleared; a lookalike matching
+ * nothing stays inert (#415's non-disclosure bound is unchanged).
+ *
+ * Never throws: an inbound message must not take the session down. Failures
+ * are logged and the CLI half of the ceremony stays available.
+ */
+function consumeInboundArmReply(
+  pi: TickApi,
+  cwd: string,
+  startupProject: string | undefined,
+  text: string,
+  seam: ArmConsumerSeam | undefined,
+): void {
+  // The state key the send half derived from the same file, read fresh so a
+  // re-stamp between the send and the reply cannot split the ceremony. An
+  // invalid config cannot be trusted to name either the key or a marker —
+  // fail closed exactly like `armReply`, but without throwing at a message.
+  const reread = readTickConfig(cwd);
+  if (reread.kind === "invalid") {
+    pi.logger.error(
+      `[omp-conductor] inbound arm reply not classified — tick config invalid at ${reread.path}: ` +
+        `${reread.problem}; use \`omp-conductor arm --reply\` on the host`,
+    );
+    return;
+  }
+  const project = reread.kind === "ok" ? reread.config.project : startupProject;
+  const surface: ArmNoticeSurface = {
+    ...(reread.kind === "ok" ? { accessFile: reread.config.accessFile } : {}),
+    project,
+  };
+  const now = (seam?.now ?? Date.now)();
+  const resolved = resolveArmReply(project, text, now);
+  const notify = (notice: string): void => {
+    const send = seam?.notify ?? sendArmNotice;
+    try {
+      // The send is async on the production path; message_start handlers are
+      // not, so delivery rides the microtask queue and its failure lands in
+      // the log, never on the session.
+      void Promise.resolve(send(notice, surface)).catch((err: unknown) => {
+        pi.logger.error(
+          `[omp-conductor] arm notice not delivered: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    } catch (err) {
+      pi.logger.error(
+        `[omp-conductor] arm notice not delivered: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+  if (resolved.verdict === "matched") {
+    settleInboundArmMatch(pi, resolved.match, notify);
+    return;
+  }
+  // A code past its window: the ceremony is dead, so answer the person who is
+  // clearly trying to complete it — and clear the expired record so neither
+  // this path nor the heartbeat ever notifies twice.
+  if (resolved.verdict === "expired") {
+    for (const expired of expiredArmChallenges(project, now)) {
+      notify(armExpiryNotice(expired, project));
+      clearArmTransaction(expired.key, expired.id);
+    }
+  }
 }
 
 export default function orchestratorTickExtension(
@@ -3634,8 +3894,10 @@ export default function orchestratorTickExtension(
 
   /** `configuredProject` carries {@link TickConfig.project} for the same reason
    *  {@link armReleaseGate} takes it: a recovered tick must reconstruct *this*
-   *  fleet's availability policy, not refuse to guess between two projects. */
-  const armAvailabilityGate = (configuredProject?: string): void => {
+   *  fleet's availability policy, not refuse to guess between two projects.
+   *  `cwd` is the fleet directory itself, which the arm consumer re-reads the
+   *  tick config from at reply time (#1061). */
+  const armAvailabilityGate = (configuredProject?: string, cwd?: string): void => {
     if (availabilityGateArmed) return;
     availabilityGateArmed = true;
 
@@ -3667,23 +3929,33 @@ export default function orchestratorTickExtension(
         }
         return;
       }
-      // An inbound user turn on THIS session is now an anomaly, not a
+      // An inbound user turn on THIS session is an anomaly, not a
       // conversation: operator DMs belong to the 24/7 console session, so a
-      // turn arriving here is an accidental topic post. It is recorded for one
-      // purpose only — {@link tickGuardDecision}'s preemption, which lets a
-      // human waiting on this pane cut a running tick short. Nothing is
-      // classified: the arming ceremony is two CLI steps on the host
-      // (`omp-conductor arm`, then `omp-conductor arm --reply "<message>"`),
-      // because with the console owning DMs an arming reply lands where no tick
-      // extension runs, and a classifier here would only ever have been dead
-      // code waiting to misfire.
-      if (
-        message.role === "user" &&
-        message.synthetic !== true &&
-        message.attribution !== "agent" &&
-        session.activeLocalTick !== undefined
-      ) {
-        session.activeLocalTick.humanWaiting = true;
+      // turn arriving here is an accidental topic post. Two things happen,
+      // and both are mechanisms — nothing here is left to model behaviour:
+      //
+      // 1. The arm ceremony's reply is classified against the pending
+      //    challenge records (#1061). The pre-#415 tombstone is retired: it
+      //    reasoned the reply lands "where no tick extension runs", but the
+      //    send half delivers the challenge to the project topic — this
+      //    pane's own claimed surface — so the reply lands exactly here, and
+      //    on a host with no console session the CLI's `arm --reply` step had
+      //    no owner at all. A matching code settles the ceremony
+      //    (markers written, transaction cleared) and answers with a
+      //    confirmation; a code past its window is answered with the re-run
+      //    command; a lookalike matching nothing stays inert, exactly as
+      //    #415 required.
+      // 2. {@link tickGuardDecision}'s preemption, unchanged: a person who
+      //    posts into the fleet topic by accident is still a person waiting,
+      //    and the autonomous-interrupt refusal must not fire at them.
+      if (message.role === "user" && message.synthetic !== true && message.attribution !== "agent") {
+        if (cwd !== undefined) {
+          const text = inboundMessageText(message.content);
+          if (text !== undefined) consumeInboundArmReply(pi, cwd, configuredProject, text, options.arm);
+        }
+        if (session.activeLocalTick !== undefined) {
+          session.activeLocalTick.humanWaiting = true;
+        }
       }
     });
     pi.on("agent_end", () => {
@@ -3921,7 +4193,7 @@ export default function orchestratorTickExtension(
     // invalid config names none — it cannot be trusted to.
     const configuredProject = result.kind === "ok" ? result.config.project : undefined;
     armReleaseGate(configuredProject);
-    armAvailabilityGate(configuredProject);
+    armAvailabilityGate(configuredProject, ctx.cwd);
     // The tool is already registered (extension-factory time); only the session
     // state it acts on is filled, and only once ownership is accepted below.
     // `configuredProject` isn't closed over at all — routing is re-read from
@@ -4011,7 +4283,7 @@ export default function orchestratorTickExtension(
         // not create or deliver decisions). `cwd` is for re-reading the live
         // tick config at execution, `config` for the startup-only ceiling.
         askSession = { cwd: ctx.cwd, config };
-        armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam);
+        armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam, options.arm);
         if (!guardArmed) {
           guardArmed = true;
           armTickGuard(pi, ctx, (config.budgetSeconds ?? DEFAULT_TICK_BUDGET_SECONDS) * 1000);
@@ -4033,7 +4305,7 @@ export default function orchestratorTickExtension(
     // why): a declined or unresolved session keeps `askSession` undefined and
     // the tool fails closed.
     askSession = { cwd: ctx.cwd, config };
-    armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam);
+    armTickHeartbeat(pi, ctx, config, session, toSpecTrackerSeam, options.arm);
     if (!guardArmed) {
       guardArmed = true;
       armTickGuard(pi, ctx, (config.budgetSeconds ?? DEFAULT_TICK_BUDGET_SECONDS) * 1000);

package/src/settlement.ts

@@ -25,7 +25,13 @@ import {
   analyseSettlement,
   deriveChangedLine,
 } from "./diff-flags.ts";
-import { SPINNING_CAP_CLASSES, classifyRun, normalise, type ClassifyFacts } from "./failure-class.ts";
+import {
+  SPINNING_CAP_CLASSES,
+  COMPOSE_DEPENDENCY_STARTUP_SIGNATURE,
+  classifyRun,
+  normalise,
+  type ClassifyFacts,
+} from "./failure-class.ts";
 import { GhPrMissingError } from "./tracker/github.ts";
 import { formatModelsTried, modelsTried } from "./model-fallback.ts";
 import { PR_LOOKUP_WINDOW_MS } from "./decisions.ts";
@@ -1558,6 +1564,26 @@ export async function classifyAndRecover(d: SettlementDeps): Promise<number> {
           if (firstFailure?.link !== undefined) {
             facts.failingLog = await tracker.checkLog(firstFailure.link);
           }
+          // A Compose dependency-startup failure ("docker compose up" aborted
+          // because a dependency container failed its healthcheck) is only
+          // outside the diff when the PR touched no container configuration —
+          // a PR that breaks its own `docker-compose.yml` produces this exact
+          // sentence and must still charge its attempt (#1059). So the
+          // classifier needs the PR's changed-file list, derived from the
+          // diff this settlement already knows how to fetch
+          // (`Tracker.prDiff`, the same call the settlement audit uses) —
+          // one fetch, and only for a row whose log actually carries
+          // Compose's sentence; every other row pays nothing. A diff that
+          // cannot be read or was cut short (`truncated`) stays undefined: an
+          // unknown list must never waive an attempt.
+          if (
+            facts.failingLog !== undefined &&
+            facts.failingLog.toLowerCase().includes(COMPOSE_DEPENDENCY_STARTUP_SIGNATURE)
+          ) {
+            const diff = await tracker.prDiff(run.prUrl);
+            facts.changedFiles =
+              diff === undefined || diff.truncated ? undefined : diff.files.map((f) => f.path);
+          }
         }
       }
     } catch (err) {
@@ -1990,10 +2016,14 @@ async function recoverRun(
     return;
   }
 
-  // `hold` (orphan-dirty) and `none`: recorded, nothing performed. The existing
-  // unsalvaged-WIP admission hold already fails dispatch closed until an
-  // operator acknowledges the tree, which is the only safe move when the
-  // worktree holds the only copy of real work.
+  // `observe` (awaiting-observation), `hold` (orphan-dirty) and `none`:
+  // recorded, nothing performed here. `observe`'s recovery IS the later observation —
+  // the settle sweep re-offers the blocked row until its PR resolves and settles it
+  // the way it settles `settlement-stuck`, so no action exists to perform today and
+  // `recoveredAt` stays NULL by design (#1068). The existing unsalvaged-WIP
+  // admission hold already fails dispatch closed until an operator acknowledges
+  // the tree, which is the only safe move when the worktree holds the only copy
+  // of real work.
 }
 
 /**

package/src/status-render.ts

@@ -254,12 +254,14 @@ const MECHANICAL_GROOMING_REASONS: Record<string, true> = {
 };
 
 /**
- * The to-spec refusal classes persisted as blocked rows (#772) — a result
- * that failed validation is a mechanical block, never a verdict. Mirrors the
- * failure kinds of `ToSpecFailure` in `to-spec.ts`.
+ * The to-spec refusal classes persisted as blocked rows (#772, #1064) — a
+ * result that failed validation, or a pass that produced no answer at all, is
+ * a mechanical block, never a verdict. Mirrors the failure kinds of
+ * `ToSpecFailure` in `to-spec.ts`.
  */
 const REFUSED_GROOMING_REASONS: Record<string, true> = {
   malformed: true,
+  "no-answer": true,
   "missing-source": true,
   "stale-source": true,
 };
@@ -289,10 +291,12 @@ const REFUSED_GROOMING_REASONS: Record<string, true> = {
  *    (`blocked` rows whose reason is a groomer verdict or a product-judgement
  *    label, e.g. `needs-product-decision`).
  *  - `mechanically blocked` — admission's lane/dependency holds.
- *  - `refused` — to-spec results that failed validation (`malformed`,
- *    `missing-source`, `stale-source`), told apart from the holds so an
- *    operator sees whether the runway cannot move or a result cannot be
- *    trusted.
+ *  - `refused` — to-spec passes that produced no usable verdict (`malformed`,
+ *    `no-answer`, `missing-source`, `stale-source`), told apart from the
+ *    holds so an operator sees whether the runway cannot move or a result
+ *    cannot be trusted. Each row's line names its own class (`#19 malformed`,
+ *    `#22 no-answer`), so a run of identical refusals is visible as a pattern
+ *    rather than a wall of one word.
  *  - `in-flight` — a launched batch is running (#777).
  *  - `operator-parked` — the dispatch snapshot's parked count (#507).
  *

package/src/store.ts

@@ -2973,6 +2973,17 @@ export function openStore(dbPath: string): Store {
   // "retrying next tick" is a lie and the row is stranded with a class and no
   // action. `hold` is excluded because it is *recorded only* by design — its
   // `recoveredAt` stays NULL forever, and re-offering it would spin the sweep.
+  //
+  // One deliberate exception re-enters the sweep after classification: a
+  // blocked row with a PR. It is the observation half of the
+  // `awaiting-observation` recovery (#1068) — the sweep re-reads the PR every
+  // pass, and the classifier's merged-PR branch names `settlement-stuck` the
+  // way it does for any other stuck row, so a blocked run whose PR later merges
+  // (the #1062 shape: merged at 15:02, row still `blocked`/`question`) settles
+  // instead of listing for Duty 1 triage forever. A genuine question row is
+  // re-offered too and its escalation is not repeated: the notifications ledger
+  // dedupes on the class+run summary of the stable evidence. Rows without a PR
+  // have nothing to observe and are only re-offered by the ordinary clauses.
   const selectUnclassified = db.query<RunRow, [string, number]>(
     `SELECT * FROM runs
       WHERE project = ?
@@ -2980,6 +2991,7 @@ export function openStore(dbPath: string): Store {
         AND (
           failureClass IS NULL
           OR (recoveredAt IS NULL AND recoveryAction IN ('settle', 'continue', 'requeue', 'rerun-checks'))
+          OR (state = 'blocked' AND prUrl IS NOT NULL)
         )
       ORDER BY startedAt DESC, rowid DESC
       LIMIT ?`,
@@ -3062,7 +3074,7 @@ export function openStore(dbPath: string): Store {
     `SELECT failureClass AS cls, COUNT(*) AS n FROM runs
       WHERE project = ? AND failureClass IS NOT NULL AND recoveredAt IS NULL
         AND state IN ('blocked', 'killed', 'failed', 'orphaned', 'pushed-green')
-        AND recoveryAction NOT IN ('none', 'hold')
+        AND recoveryAction NOT IN ('none', 'hold', 'observe')
       GROUP BY failureClass
       ORDER BY n DESC, failureClass ASC`,
   );
@@ -3070,7 +3082,7 @@ export function openStore(dbPath: string): Store {
     `SELECT failureClass AS cls, COUNT(*) AS n FROM runs
       WHERE project = ? AND failureClass IS NOT NULL AND recoveredAt IS NULL
         AND state IN ('blocked', 'killed', 'failed', 'orphaned', 'pushed-green')
-        AND recoveryAction IN ('none', 'hold')
+        AND recoveryAction IN ('none', 'hold', 'observe')
       GROUP BY failureClass
       ORDER BY n DESC, failureClass ASC`,
   );