omp-conductor 0.19.1 → 0.19.3

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 &&