omp-conductor 0.19.2 → 0.19.3

package/src/daemon.ts

@@ -38,7 +38,12 @@ import { pendingCodeGraph, probeCodeGraph, type CodeGraphHealth } from "./graph-
 import { graphHint } from "./graph.ts";
 import { hostConstraintsNotice } from "./host.ts";
 import { acquireOnceLease, healthCheck, livingDaemon, probeUnit, SYSTEMD_UNIT } from "./lifecycle.ts";
-import { requestImmediateTick, resolveTickConfigCwd, STALL_MARKER_FILE } from "./orchestrator-tick.ts";
+import {
+  readTickRequestReason,
+  requestImmediateTick,
+  resolveTickConfigCwd,
+  STALL_MARKER_FILE,
+} from "./orchestrator-tick.ts";
 import { SPEND_SAMPLE_ROWS, SPEND_SAMPLE_RUNS, runDoctor } from "./doctor.ts";
 import { judgeSpendTelemetry, type SpendTelemetryVerdict } from "./spend-telemetry.ts";
 import {
@@ -62,6 +67,7 @@ import {
   herdrPaneOmpStarts,
   openWorkerPane,
   reconcileWorkerPanes,
+  PANE_REATTEMPT_MAX,
   releaseOrphanedWorkerPane,
   releaseWorkerPane,
   reportWorkerPaneState,
@@ -1424,11 +1430,20 @@ export interface WorkerControlRegistry {
     runId: string,
     onPhase?: (phase: WorkerPausePhase) => void,
   ): WorkerControlSlot;
-  pause(project: string, issue: number): Promise<WorkerControlResult>;
+  /** `source` names who asked (board/cli/dashboard) — recorded as pause
+   *  provenance so "who paused this and when" is answerable later (#997). */
+  pause(project: string, issue: number, source: string): Promise<WorkerControlResult>;
   resume(project: string, issue: number): WorkerControlResult;
   stop(project: string, issue: number, reason: string): Promise<WorkerControlResult>;
-  /** Live runs whose phase is not `running` — what /healthz and the board show. */
-  snapshot(project: string): { issue: number; runId: string; phase: WorkerPausePhase }[];
+  /** Live runs whose phase is not `running` — what /healthz and the board
+   *  show — each carrying its pause provenance when one was recorded (#997). */
+  snapshot(project: string): {
+    issue: number;
+    runId: string;
+    phase: WorkerPausePhase;
+    source?: string;
+    pausedAtMs?: number;
+  }[];
 }
 
 /** Authoritative controls for sessions owned by this daemon process. */
@@ -1442,6 +1457,8 @@ export function createWorkerControlRegistry(): WorkerControlRegistry {
     stopError?: string;
     finished: PromiseWithResolvers<void>;
     onPhase?: (phase: WorkerPausePhase) => void;
+    /** Who asked for the live pause, and when — cleared on resume (#997). */
+    pausedBy?: { source: string; at: number };
   }
 
   const active = new Map<string, Entry>();
@@ -1476,12 +1493,13 @@ export function createWorkerControlRegistry(): WorkerControlRegistry {
         },
       };
     },
-    async pause(project, issue) {
+    async pause(project, issue, source) {
       const entry = active.get(key(project, issue));
       if (entry?.control === undefined) return { kind: "not-active" };
       try {
         await entry.control.pause();
         const phase = entry.control.phase();
+        entry.pausedBy = { source, at: Date.now() };
         entry.onPhase?.(phase);
         return { kind: "ok", runId: entry.runId, phase };
       } catch (err) {
@@ -1498,6 +1516,7 @@ export function createWorkerControlRegistry(): WorkerControlRegistry {
       try {
         entry.control.resume();
         const phase = entry.control.phase();
+        delete entry.pausedBy;
         entry.onPhase?.(phase);
         return { kind: "ok", runId: entry.runId, phase };
       } catch (err) {
@@ -1533,11 +1552,25 @@ export function createWorkerControlRegistry(): WorkerControlRegistry {
       return { kind: "stopped", runId: entry.runId, reason: entry.stopReason! };
     },
     snapshot(project) {
-      const workers: { issue: number; runId: string; phase: WorkerPausePhase }[] = [];
+      const workers: {
+        issue: number;
+        runId: string;
+        phase: WorkerPausePhase;
+        source?: string;
+        pausedAtMs?: number;
+      }[] = [];
       for (const entry of active.values()) {
         if (entry.project !== project || entry.control === undefined) continue;
         const phase = entry.control.phase();
-        if (phase !== "running") workers.push({ issue: entry.issue, runId: entry.runId, phase });
+        if (phase === "running") continue;
+        workers.push({
+          issue: entry.issue,
+          runId: entry.runId,
+          phase,
+          ...(entry.pausedBy === undefined
+            ? {}
+            : { source: entry.pausedBy.source, pausedAtMs: entry.pausedBy.at }),
+        });
       }
       return workers;
     },
@@ -2804,6 +2837,7 @@ export async function handleIssue(
       log(`#${issue} stopped by operator on attempt ${attempt}: ${result.stoppedReason}`);
     } else if (state === "blocked") {
       swapLabel(store, project.name, issue, inProgress, project.stateLabels.blocked);
+      wakeOrchestratorForBlockedRun(project.name, issue);
       await safeEscalate(d, {
         tier: 1,
         project: project.name,
@@ -3035,8 +3069,27 @@ export async function handleIssue(
  * releasing one whose run is not live; the authoritative child is never
  * signalled, and no pane is ever closed.
  */
+/**
+ * Pane re-establishment attempts spent per run, for this daemon process only
+ * (#998).
+ *
+ * Deliberately in memory rather than on the run row: a restart is exactly the
+ * event that makes another attempt worth making (Herdr came back), so a fresh
+ * process legitimately gets a fresh budget, and giving up never marks a run
+ * permanently unrepresentable. Pruned against the live set on every pass, so it
+ * cannot outgrow the fleet.
+ */
+const paneAttemptsSpent = new Map<string, number>();
+
 function reconcilePanes(d: Deps, project: string, log: (message: string) => void): void {
   const live = d.store.liveRuns(project);
+  const liveKeys = new Set(live.map((run) => `${project}\u0000${run.id}`));
+  for (const key of [...paneAttemptsSpent.keys()]) {
+    if (key.startsWith(`${project}\u0000`) && !liveKeys.has(key)) paneAttemptsSpent.delete(key);
+  }
+  const attempts = new Map(
+    live.map((run) => [run.id, paneAttemptsSpent.get(`${project}\u0000${run.id}`) ?? 0]),
+  );
   const result = reconcileWorkerPanes(
     live.map((run) => ({
       runId: run.id,
@@ -3048,6 +3101,8 @@ function reconcilePanes(d: Deps, project: string, log: (message: string) => void
       ...(run.paneLabel === undefined ? {} : { paneLabel: run.paneLabel }),
       ...(run.sessionFile === undefined ? {} : { sessionFile: run.sessionFile }),
     })),
+    {},
+    attempts,
   );
   if (!result.ok) {
     // An unreadable workspace is not evidence that anything is stale, so nothing
@@ -3068,9 +3123,33 @@ function reconcilePanes(d: Deps, project: string, log: (message: string) => void
         });
         log(`#${runIssue(live, outcome.runId)} herdr pane re-associated as ${outcome.paneId} after a restart`);
         break;
-      case "untracked":
+      case "untracked": {
         d.store.updateRun(outcome.runId, { paneId: null, paneLabel: null, paneUnavailable: outcome.reason });
-        log(`#${runIssue(live, outcome.runId)} has no herdr pane: ${outcome.reason}`);
+        if (outcome.attempted !== true) {
+          // Cost no attempt (no recorded pid): say so every pass, as before.
+          log(`#${runIssue(live, outcome.runId)} has no herdr pane: ${outcome.reason}`);
+          break;
+        }
+        // #998: a terminal refusing to split will refuse the next one too, and
+        // each retry made the pile worse — spend the whole budget at once.
+        const key = `${project}\u0000${outcome.runId}`;
+        const spent = outcome.reason.includes("pane_split_failed")
+          ? PANE_REATTEMPT_MAX
+          : (paneAttemptsSpent.get(key) ?? 0) + 1;
+        paneAttemptsSpent.set(key, spent);
+        // Once per run, at the moment the budget runs out — not once per pass.
+        // Four identical lines a minute for #986 is what made the real cause
+        // (a leaked pane per attempt) hard to see on 2026-08-23.
+        log(
+          spent >= PANE_REATTEMPT_MAX
+            ? `#${runIssue(live, outcome.runId)} has no herdr pane after ${spent} attempt(s), not retrying: ${outcome.reason}`
+            : `#${runIssue(live, outcome.runId)} has no herdr pane (attempt ${spent}/${PANE_REATTEMPT_MAX}): ${outcome.reason}`,
+        );
+        break;
+      }
+      case "attempts-exhausted":
+        // Already reported when the budget ran out; the run keeps working with
+        // no pane, and a later restart gets a fresh budget.
         break;
       case "stale-released":
         log(`released stale herdr pane ${outcome.paneId} (run ${outcome.runId || "unidentified"} is not live)`);
@@ -4128,6 +4207,7 @@ export async function handleReviewRevision(d: Deps, revision: ReviewRevisionReco
       log(`#${issue} review round ${revision.round} stopped by operator: ${result.stoppedReason}`);
     } else if (state === "blocked") {
       swapLabel(store, project.name, issue, inProgress, project.stateLabels.blocked);
+      wakeOrchestratorForBlockedRun(project.name, issue);
       await safeEscalate(d, {
         tier: 1,
         project: project.name,
@@ -5060,6 +5140,53 @@ export function wakeOrchestratorForMetConditions(
 }
 
 
+/**
+ * Wake the orchestrator because a worker stopped to ask a question (#990).
+ *
+ * `question` is the third-largest class in this ledger — 58 of 839 runs — and
+ * every one of them is a parked worker holding a slot until someone reads the
+ * question. Nothing woke the orchestrator for it: the only wake was a decision
+ * condition being met, so on a fleet with a 1800s heartbeat a tier-1 question
+ * whose answer is one comment could sit unread for half an hour.
+ *
+ * Deliberately narrow. Only the blocked path wakes: a failed run, a cap kill
+ * and a clean settle are the next scheduled tick's business, and waking on
+ * every terminal state turns the heartbeat into a busy loop — which would be a
+ * worse fleet than the one that waits.
+ *
+ * Debounced by the marker itself rather than by a counter: an unconsumed
+ * request already asks for exactly the wake this call wants, so three workers
+ * blocking in one pass write one request and the *first* question's number
+ * survives as the reason. Best effort throughout — a marker that cannot be
+ * written is logged, and the settlement it belongs to is never affected.
+ */
+export function wakeOrchestratorForBlockedRun(
+  projectName: string,
+  issue: number,
+  writeLog: (line: string) => void = log,
+): void {
+  const tickCwd = resolveTickConfigCwd(projectName);
+  if (tickCwd === undefined) {
+    writeLog(
+      `#${issue} is blocked but no tick config cwd — the question waits for the next heartbeat`,
+    );
+    return;
+  }
+  const pending = readTickRequestReason(tickCwd);
+  if (pending !== undefined) {
+    writeLog(`#${issue} is blocked; a tick request is already pending (${pending})`);
+    return;
+  }
+  const reason = `tier1-question #${issue}`;
+  if (requestImmediateTick(tickCwd, reason)) {
+    writeLog(`requested immediate tick at ${tickCwd}: ${reason}`);
+  } else {
+    writeLog(
+      `could not write tick request under ${tickCwd}; #${issue}'s question waits for the next heartbeat`,
+    );
+  }
+}
+
 /**
  * The first-tick verification for a fleet-initiated upgrade (#486).
  *
@@ -5803,8 +5930,9 @@ export interface DaemonHealthSnapshot {
   turnOverrides: TurnOverride[];
   dispatch?: DispatchSummary;
   codeGraph?: CodeGraphHealth;
-  /** Live workers in a non-running pause phase; absent/empty = nothing paused. */
-  workers?: { issue: number; runId: string; phase: WorkerPausePhase }[];
+  /** Live workers in a non-running pause phase; absent/empty = nothing paused.
+   *  `source`/`pausedAtMs` carry the pause provenance when one was recorded (#997). */
+  workers?: { issue: number; runId: string; phase: WorkerPausePhase; source?: string; pausedAtMs?: number }[];
   /**
    * The live orchestrator surface, attested by the running daemon (#832):
    * which mode this project's fleet is in, and — when the daemon hosts the
@@ -5961,8 +6089,12 @@ export async function turnLimitResponse(
 export async function workerControlResponse(
   req: Request,
   project: string,
-  store: Pick<Store, "latestRun" | "updateRun">,
+  store: Pick<Store, "latestRun" | "updateRun" | "recordMaterialEvent">,
   registry: WorkerControlRegistry,
+  /** Journal line for every accepted pause/resume — the live half of the
+   *  audit trail #997 asks for; the durable half is the material event. */
+  log: (line: string) => void = () => {},
+  now: () => number = Date.now,
 ): Promise<Response | undefined> {
   const url = new URL(req.url);
   const match = /^\/runs\/(\d+)\/(pause|resume|stop)$/.exec(url.pathname);
@@ -6002,16 +6134,44 @@ export async function workerControlResponse(
       return Response.json({ error: "reason must be at most 500 characters" }, { status: 400 });
     }
   }
+  // Who asked. The board, the CLI and the dashboard each name themselves so a
+  // pause is attributable afterwards (#997); an older caller that sends no
+  // source is recorded as such rather than guessed at.
+  const rawSource = Reflect.get(body, "source");
+  if (rawSource !== undefined && (typeof rawSource !== "string" || rawSource.trim() === "" || rawSource.trim().length > 40)) {
+    return Response.json({ error: "source must be a non-empty string of at most 40 characters when present" }, { status: 400 });
+  }
+  const source = typeof rawSource === "string" ? rawSource.trim() : "unattributed";
 
 
   const issue = Number(match[1]);
   const outcome =
     action === "pause"
-      ? await registry.pause(project, issue)
+      ? await registry.pause(project, issue, source)
       : action === "resume"
         ? registry.resume(project, issue)
         : await registry.stop(project, issue, reason!);
   if (outcome.kind === "ok") {
+    // The transition really happened — write both halves of the audit trail
+    // before answering (#997): one journal line for the live log, one durable
+    // material event the digest ledger keeps after the journal rotates. #986
+    // was parked 14 minutes by an unlogged keypress and nobody could say why.
+    const verb = action === "pause" ? "paused" : "resumed";
+    log(`#${issue} worker ${verb} via ${source} (run ${outcome.runId})`);
+    try {
+      store.recordMaterialEvent({
+        project,
+        category: "worker-control",
+        summary: `#${issue} worker ${verb} via ${source}`,
+        evidence: `run ${outcome.runId}, phase ${outcome.phase}`,
+        occurredAt: now(),
+        recordedAt: now(),
+      });
+    } catch (err) {
+      // The audit must never turn a successful transition into an error
+      // answer, but a swallowed write would be a silent audit gap — log it.
+      log(`#${issue} worker-control audit write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     return Response.json({ runId: outcome.runId, phase: outcome.phase });
   }
   if (outcome.kind === "refused") {
@@ -6089,8 +6249,10 @@ export async function workerControlResponse(
 
 export interface DaemonHttpProjectDeps {
   project: string;
-  store: Pick<Store, "latestRun" | "setTurnOverride" | "updateRun">;
+  store: Pick<Store, "latestRun" | "setTurnOverride" | "updateRun" | "recordMaterialEvent">;
   caps: () => Pick<Caps, "workerMaxTurns" | "workerMaxTurnsCeiling">;
+  /** Project-scoped journal line — the live half of the pause audit (#997). */
+  log?: (line: string) => void;
 }
 
 export interface DaemonHttpDeps {
@@ -6163,6 +6325,7 @@ export async function daemonHttpResponse(req: Request, d: DaemonHttpDeps): Promi
     selected.project,
     selected.store,
     d.workerControls,
+    selected.log,
   );
   return workerControl ?? new Response("not found\n", { status: 404 });
 }
@@ -6524,6 +6687,22 @@ export function statusSnapshotFromStore(
     spendTelemetry: judgeSpendTelemetry(
       store.recentSpendSamples?.(p.name, SPEND_SAMPLE_ROWS) ?? [],
       SPEND_SAMPLE_RUNS,
+      {
+        // Config and an already-read status only — this snapshot probes nothing
+        // at render time, which is the property the figure above depends on
+        // (#970). The declaration alone is enough to know a dollar cap cannot
+        // fire; the window name rides along when a configured plan cap has
+        // already resolved one, and `doctor` (which may probe) reads it live.
+        declaredSubscription: (p.requireOauthProviders ?? []).length > 0,
+        ...(planUsage?.window === undefined
+          ? {}
+          : {
+              allowanceWindow:
+                planUsage.window.label === undefined
+                  ? planUsage.window.id
+                  : `${planUsage.window.id} (${planUsage.window.label})`,
+            }),
+      },
     ),
     // Read, never probed: the recorded row is the whole point (#919).
     ...(() => {
@@ -7461,6 +7640,10 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
           project: runtime.d.project.name,
           store,
           caps: () => runtime.d.caps,
+          // The same project prefix the runtime's own journal lines carry, so
+          // a pause audit reads like every other daemon line (#997).
+          log: (line: string) =>
+            log(runtimes.length === 1 ? line : `[${runtime.d.project.name}] ${line}`),
         })),
         turnLimits,
         workerControls,

package/src/dashboard/controls.ts

@@ -189,7 +189,7 @@ export async function dashboardWorkerControl(
   body: unknown,
   d: ControlDeps,
 ): Promise<ControlOutcome> {
-  const payload: Record<string, unknown> = { project: d.project.name };
+  const payload: Record<string, unknown> = { project: d.project.name, source: "dashboard" };
   if (action === "stop") {
     const reason = readReason(body);
     if (reason === undefined) {

package/src/doctor.ts

@@ -64,6 +64,7 @@ import {
 import { pauseInstance } from "./pause.ts";
 import type { TelegramHealth } from "./status-render.ts";
 import {
+  claimIsLive,
   claimedTelegramTopics,
   lockPidAlive,
   pidAlive,
@@ -100,7 +101,7 @@ import {
   readTickConfig,
   type HerdrAgentList,
 } from "./orchestrator-tick.ts";
-import type { ConductorConfig, ProjectConfig, RepoTarget, RunState } from "./types.ts";
+import type { Caps, ConductorConfig, ProjectConfig, RepoTarget, RunState } from "./types.ts";
 import { DEFAULT_ARM_PROOF, type ArmProof } from "./types.ts";
 import {
   DEFAULT_DEPS as UPGRADE_DEPS,
@@ -114,7 +115,8 @@ import {
   checkTelegramFreshness,
   type TelegramFreshness,
 } from "./telegram-freshness.ts";
-import { judgeSpendTelemetry, spendTelemetryDetail } from "./spend-telemetry.ts";
+import { bindingAllowanceWindow, sharedUsageSource } from "./usage.ts";
+import { judgeSpendTelemetry, spendTelemetryDetail, type SpendBilling } from "./spend-telemetry.ts";
 
 /** One read of this host's installed surfaces: the three identities, or why
  *  they could not be read. A failed read is a finding (`warn`, "unverified"),
@@ -308,6 +310,14 @@ export interface DoctorDeps {
   /** Whether a recorded claim or dm-owner pid is live, with omp-telegram's
    *  topics.ts semantics (EPERM is dead). */
   pidAlive?: (pid: number) => boolean;
+  /** Whether one claimed topic is live — the single fact `topic-pin` and
+   *  `telegram-plumbing` both read, so they cannot disagree about a claim
+   *  (#987). Defaults to {@link claimIsLive}. */
+  claimIsLive?: (claim: { pid?: number }) => boolean;
+  /** The provider allowance window nearest its ceiling, from `omp usage --json`
+   *  — what binds a subscription-billed fleet instead of a dollar cap (#984).
+   *  `undefined` when the provider reports no comparable window. */
+  allowanceWindow?: () => Promise<string | undefined>;
   /** Whether a bot.lock owner pid is live, with omp-telegram's api.ts
    *  semantics (EPERM is live). Distinct from {@link pidAlive} because the
    *  bridge itself uses two rules. */
@@ -1096,6 +1106,62 @@ async function telegramProbe(probes: Probes, project: ProjectConfig | undefined,
   );
 }
 
+/**
+ * Is any economic control actually governing this project? (#985)
+ *
+ * Two exist, and on this fleet neither was active. `caps.planUsage` was `null`,
+ * so the allowance gate that admission already applies — it holds every routed
+ * candidate and escalates once (`admission.ts`) — was configured off. And
+ * `caps.dailySpendUsd` was a ceiling that #984 established cannot fire under
+ * subscription billing, because a subscription request carries no per-request
+ * price. So the fleet ran with no ceiling of any kind, and no surface said so:
+ * `status` reported `unmetered — no plan allowance cap configured`, which reads
+ * as a fact about the plan rather than as a missing control.
+ *
+ * This row states the gap once, per project, with the remedy that closes it.
+ * It is deliberately NOT a new gate: the gate exists and works. What was
+ * missing was anyone being told it is switched off.
+ */
+function economicGateProbe(
+  project: ProjectConfig,
+  caps: Caps,
+  subscriptionBilled: boolean,
+  allowanceWindow: string | undefined,
+): Finding {
+  const allowanceGate = caps.planUsage !== null;
+  // A dollar cap governs only if it can fire, and under subscription billing it
+  // cannot — that is #984's finding, reused here rather than re-derived.
+  const dollarGate = caps.dailySpendUsd !== null && !subscriptionBilled;
+
+  if (allowanceGate) {
+    return passFinding(
+      "economic-gate",
+      `[${project.name}] the provider allowance gate is configured (window ${caps.planUsage?.windowId ?? "?"}, ` +
+        `hold at ${String(Math.round((caps.planUsage?.maxUsedFraction ?? 0) * 100))}% used)` +
+        (dollarGate ? ` beside a $${caps.dailySpendUsd?.toFixed(2) ?? "?"} daily cap` : ""),
+    );
+  }
+  if (dollarGate) {
+    return passFinding(
+      "economic-gate",
+      `[${project.name}] the $${caps.dailySpendUsd?.toFixed(2) ?? "?"} daily spend cap governs; ` +
+        `no provider allowance cap is configured`,
+    );
+  }
+  return warnFinding(
+    "economic-gate",
+    `[${project.name}] no economic control is active: caps.planUsage is null, and ` +
+      (caps.dailySpendUsd === null
+        ? "no daily spend cap is set"
+        : `the $${caps.dailySpendUsd.toFixed(2)} daily cap cannot fire on subscription billing`) +
+      ` — admission has nothing to weigh and will keep claiming until the provider itself refuses` +
+      (allowanceWindow === undefined ? "" : `; the window that would bind is ${allowanceWindow}`),
+    allowanceWindow === undefined
+      ? "run `omp usage --json` on the fleet host and copy an allowance `id` into `caps.planUsage.windowId` (with `maxUsedFraction`), or set a `caps.dailySpendUsd` the billing model can actually spend"
+      : `set caps.planUsage to { windowId: "${allowanceWindow.split(" ")[0] ?? ""}", maxUsedFraction: 0.9 } — the gate is already wired into admission, it is simply switched off`,
+  );
+}
+
 /**
  * Spend telemetry, through the shared judgement (#970).
  *
@@ -1105,9 +1171,17 @@ async function telegramProbe(probes: Probes, project: ProjectConfig | undefined,
  * that had lost a majority of their telemetry — so partial loss, the common
  * case, was the invisible one. See `spend-telemetry.ts` for the measurements.
  */
-function spendProbe(rows: RunSpendRow[], limit: number): Finding {
-  const verdict = judgeSpendTelemetry(rows, limit);
+function spendProbe(rows: RunSpendRow[], limit: number, billing: SpendBilling = {}): Finding {
+  const verdict = judgeSpendTelemetry(rows, limit, billing);
   const detail = spendTelemetryDetail(verdict);
+  // A subscription-billed fleet's zeros are the truth, so this passes and names
+  // the constraint that does bind (#984). It still says the sentence: a reader
+  // who expected a dollar figure needs to know why there isn't one. What it
+  // must never do is warn forever with advice that cannot be acted on — there
+  // is nothing to repair, and a permanent warning is one nobody reads.
+  if (verdict.kind === "subscription") {
+    return passFinding("spend-telemetry", detail ?? "subscription-billed; no USD cap applies");
+  }
   if (detail !== undefined) {
     return warnFinding(
       "spend-telemetry",
@@ -1296,15 +1370,35 @@ function topicPinProbe(probes: Probes, p: ProjectConfig): Finding {
       `check omp-telegram's claim registry (threads.json in its state dir) is readable and the bridge is running, then re-run doctor — until then sends keep the pinned topic and degrade to the flat chat on a missing thread (#318)`,
     );
   }
-  const claims = result.claims;
+  // One liveness fact, shared with `telegram-plumbing` (#987). Before this the
+  // registry's rows were all treated as live here, so a pin aimed at a corpse
+  // read PASS while the plumbing row called the same claim dead.
+  const all = result.claims;
+  const claims = all.filter((claim) => probes.claimIsLive(claim));
+  const dead = all.filter((claim) => !probes.claimIsLive(claim));
+  // Named, never dropped: the row is the only index to the remote topic, so
+  // deleting it strands the topic instead of cleaning it up.
+  const deadNote =
+    dead.length === 0
+      ? ""
+      : ` (dead claims still recorded, and left alone: ${dead
+          .map((c) => `${c.threadId}${c.pid === undefined ? " no pid" : ` pid ${c.pid}`}`)
+          .join(", ")} — run the bridge's /cleanup to remove those topics)`;
   if (claims.length === 0) {
+    if (dead.length > 0) {
+      return warnFinding(
+        "topic-pin",
+        `[${p.name}] pinned topic ${pinned} — every claim in omp-telegram's registry is dead${deadNote}`,
+        `run /cleanup in Telegram so the bridge closes those topics and drops their rows itself, then re-run setup to re-pin escalation.telegramTopicId to a live claim — never delete rows from threads.json by hand, because the row is the only index to the remote topic (#987)`,
+      );
+    }
     return passFinding(
       "topic-pin",
       `[${p.name}] pinned topic ${pinned} — no live claims to compare (the bridge has claimed no topics yet); the pin stands`,
     );
   }
   if (claims.some((claim) => claim.threadId === pinned)) {
-    return passFinding("topic-pin", `[${p.name}] pinned topic ${pinned} is a live claim`);
+    return passFinding("topic-pin", `[${p.name}] pinned topic ${pinned} is a live claim${deadNote}`);
   }
   const match = resolveProjectClaim(claims, p.name);
   if (match.kind === "match") {
@@ -1924,7 +2018,30 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
     // reported against another's name.
     for (const p of projects) findings.push(fenceProbe(probes, p.name));
   }
-  findings.push(spendProbe(spendRows, SPEND_SAMPLE_RUNS));
+  // The billing class the spend row needs (#984). Declared only when EVERY
+  // project requires a subscription credential: on a mixed fleet the zeros of
+  // an API-key project are still a fault, and one project's declaration must
+  // not excuse another's telemetry loss.
+  const declaredSubscription =
+    projects.length > 0 && projects.every((p) => (p.requireOauthProviders ?? []).length > 0);
+  const allowanceWindow = probes.allowanceWindow === undefined ? undefined : await probes.allowanceWindow();
+  const billing = {
+    declaredSubscription,
+    ...(allowanceWindow === undefined ? {} : { allowanceWindow }),
+  };
+  findings.push(spendProbe(spendRows, SPEND_SAMPLE_RUNS, billing));
+  // Per project, because the caps are: one project's configured ceiling says
+  // nothing about another's (#985).
+  const subscriptionBilled =
+    judgeSpendTelemetry(spendRows, SPEND_SAMPLE_RUNS, billing).kind === "subscription";
+  if (cfg !== undefined) {
+    const defaults = cfg.defaults;
+    for (const p of projects) {
+      findings.push(
+        economicGateProbe(p, resolveCaps(p, defaults), subscriptionBilled, allowanceWindow),
+      );
+    }
+  }
 
   const status: ReportStatus = findings.some((f) => f.status === "fail")
     ? "fail"
@@ -2042,6 +2159,8 @@ export function defaultProbes(): Probes {
       return claimDir === cwdDir ? [cwdDir] : [cwdDir, claimDir];
     },
     pidAlive,
+    claimIsLive: (claim) => claimIsLive(claim),
+    allowanceWindow: async () => bindingAllowanceWindow(await sharedUsageSource().read()),
     lockPidAlive,
     lockFresh: (mtimeMs) => Date.now() - mtimeMs < TELEGRAM_LOCK_FRESH_MS,
     tickAgentName: (p) => {

package/src/escalate.ts

@@ -750,6 +750,37 @@ export function pidAlive(
   }
 }
 
+/**
+ * Whether one claimed topic is live — **the** liveness fact about a claim
+ * (#987).
+ *
+ * Two doctor rows used to answer this question separately: `topic-pin` treated
+ * every row in the registry as live (the reader returns rows, it never filtered
+ * them), while `telegram-plumbing` applied `pidAlive` and called the same claim
+ * `claim-dead`. One fact, two rules, opposite answers — and whichever row the
+ * reader happened to trust decided whether the fleet looked healthy. A doctor
+ * that contradicts itself is worse than a silent one, because it teaches the
+ * reader to discount its rows.
+ *
+ * A claim with no pid is not live: the bridge records a number or nothing, and
+ * `telegramPlumbingVerdict` already refuses a pidless claim as dead. `kill` is
+ * injectable for the same reason it is on {@link pidAlive}.
+ *
+ * Being dead is **not** a licence to delete the row. No Bot API call lists
+ * forum topics, so a claim row is the only index to a remote topic
+ * (`omp-telegram/src/topics.ts:149-151`): dropping it strands the topic with no
+ * supported way to remove it — 70 were stranded that way in one day, and every
+ * recovery depended on an artifact nothing guarantees. Callers report dead
+ * claims; the bridge's own `/cleanup` removes them, remote side first.
+ */
+export function claimIsLive(
+  claim: Pick<ClaimedTopic, "pid">,
+  kill?: (target: number, signal: number) => void,
+): boolean {
+  if (claim.pid === undefined) return false;
+  return kill === undefined ? pidAlive(claim.pid) : pidAlive(claim.pid, kill);
+}
+
 /**
  * Whether a bot.lock owner pid is a live process as the bridge's `api.ts`
  * judges it (`src/api.ts:pidAlive`): `EPERM` means the process exists but is
@@ -1073,6 +1104,19 @@ export type TelegramPlumbingScan = { dirs: readonly string[] };
  * stops its heartbeat while its own pid stays live (#612 ecosystem
  * correction).
  */
+/**
+ * Adapts an injected pid-liveness predicate to the `kill` seam
+ * {@link claimIsLive} owns, so the verdict can read the shared claim fact
+ * without a second pid rule and without changing its own probe shape (#987).
+ * Throwing is how `pidAlive` spells "dead", which is the contract it applies to
+ * whatever this returns.
+ */
+function killOf(alive: (pid: number) => boolean): (target: number, signal: number) => void {
+  return (target) => {
+    if (!alive(target)) throw new Error("not alive");
+  };
+}
+
 export function telegramPlumbingVerdict(
   sendTopic: number | undefined,
   scan: TelegramPlumbingScan | undefined,
@@ -1085,7 +1129,9 @@ export function telegramPlumbingVerdict(
     if (registry.kind !== "ok") return { ok: false, reason: "registry-unreadable" };
     const claim = registry.claims.find((c) => c.threadId === sendTopic);
     if (claim === undefined) return { ok: false, reason: "no-topic-claim" };
-    if (claim.pid === undefined || !alive(claim.pid)) return { ok: false, reason: "claim-dead" };
+    // The shared fact, not a second copy of the pid rule (#987): `topic-pin`
+    // reads the same predicate, so the two rows cannot disagree about a claim.
+    if (!claimIsLive(claim, killOf(alive))) return { ok: false, reason: "claim-dead" };
     if (
       scan !== undefined &&
       claim.sessionFile !== undefined &&