omp-conductor 0.16.2 → 0.17.1

package/src/doctor.ts

@@ -54,16 +54,29 @@ import {
   DEFAULT_HERDR_UNIT,
   probeTelegramHealth,
   resolveHerdrSessionWithBridge,
+  resolveTickConfig,
   sessionsRoot,
   sessionDirForCwd,
   telegramStateDir,
 } from "./fleet.ts";
 import type { TelegramHealth } from "./status-render.ts";
 import {
-  claimForProject,
   claimedTelegramTopics,
+  lockPidAlive,
+  pidAlive,
+  readTelegramChannel,
+  readTelegramDmOwner,
+  readTelegramPollState,
+  resolveClaimedSessionFile,
+  resolveProjectClaim,
+  resolveProjectTopicId,
+  telegramPlumbingVerdict,
   telegramTopicsTidy,
-  type ClaimedTopic,
+  TELEGRAM_LOCK_FRESH_MS,
+  type ClaimedTopicsResult,
+  type TelegramChannelState,
+  type TelegramDmOwnerState,
+  type TelegramPollState,
 } from "./escalate.ts";
 import {
   herdrConductorPluginConfigDir,
@@ -212,10 +225,44 @@ export interface DoctorDeps {
   herdrConfig?: () => string | undefined;
   /** The live herdr-conductor plugin `config.env`, or undefined. */
   herdrEnv?: () => string | undefined;
-  /** Live omp-telegram topic claims (threads.json), for the #600 probes. */
-  claimedTopics?: () => ClaimedTopic[];
+  /** Live omp-telegram topic claims (threads.json), for the #600 probes.
+   *  `unavailable` when the registry cannot be read or does not parse — the
+   *  caller must not read that as "no claims" (#626). */
+  claimedTopics?: () => ClaimedTopicsResult;
   /** Whether the bridge's access.json runs per-session topic tidy on. */
   topicsTidy?: () => boolean;
+  /** The typed bot.lock poll-ownership read, told apart so absent/malformed
+   *  state is a #612 failure — the lock, not daemon.json, is what says whether
+   *  the bridge is actually polling. */
+  pollState?: () => TelegramPollState;
+  /** The typed dm-owner.json read — the untopiced-DM recipient a flat
+   *  challenge's reply routes through (`/telegram own`). Absent/malformed is a
+   *  named "no pinned owner", not a pass. */
+  dmOwner?: () => TelegramDmOwnerState;
+  /** The paired inbound channel state, probed exactly as armTicks probes it
+   *  (readTelegramChannel over the tick's accessFile). */
+  channelState?: (project: ProjectConfig) => TelegramChannelState;
+  /** Whether the project can ride inbound at all — a readable tick config
+   *  naming an accessFile. The tick runtime treats a missing accessFile as no
+   *  fleet bridge, so that shape is neutral, never a fault. */
+  projectArms?: (project: ProjectConfig) => boolean;
+  /** The topic id an arm challenge would send into for this project —
+   *  resolveProjectTopicId's pin-or-live-claim; undefined means flat chat. */
+  armSendTopic?: (project: ProjectConfig) => number | undefined;
+  /** The session directories arm scans for the challenge reply on this
+   *  project — tick-cwd-derived plus the live claim's own directory. */
+  armScanDirs?: (project: ProjectConfig) => readonly string[];
+  /** 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 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. */
+  lockPidAlive?: (pid: number) => boolean;
+  /** Whether a lock-file mtime is younger than LOCK_FRESH_MS — the bridge's
+   *  own liveness rule: a fresh heartbeat keeps the poll live even when the
+   *  recorded pid is gone. */
+  lockFresh?: (mtimeMs: number) => boolean;
   /** The fleet agent name the tick config of one project names, or undefined
    *  when there is no (readable) tick — the expected live herdr pane identity. */
   tickAgentName?: (project: ProjectConfig) => string | undefined;
@@ -1094,15 +1141,52 @@ function herdrAgentNameProbe(probes: Probes, p: ProjectConfig): Finding {
  * doctor fails rather than letting the fleet sit disarmed.
  */
 function armSessionDirProbe(probes: Probes, p: ProjectConfig): Finding {
-  const claims = probes.claimedTopics();
-  if (claims.length === 0) {
+  const result = probes.claimedTopics();
+  if (result.kind !== "ok") {
+    // The registry could not be read, so the claim's session file is unknown,
+    // not known-absent. Arm scans the tick-cwd directory either way, but the
+    // finding must stay diagnostic — this is exactly the shape that once made
+    // arming silently impossible, and "no claim" would certify it as fine. A
+    // missing registry is the same unknown to this probe: the bridge may never
+    // have claimed, but nothing proves the claim names no session file.
+    return warnFinding(
+      "arm-session-dir",
+      `[${p.name}] ` +
+        (result.kind === "missing"
+          ? `omp-telegram has no claim registry (threads.json in its state dir) — arm scans the tick-cwd session directory, but doctor cannot tell whether the claim names a session file elsewhere`
+          : `omp-telegram's claim registry is unreadable (${result.problem}) — arm scans the tick-cwd session directory, but doctor cannot tell whether the claim names a session file elsewhere`),
+      `check omp-telegram's claim registry (threads.json in its state dir) is readable and the bridge is running, then re-run doctor`,
+    );
+  }
+  if (result.claims.length === 0) {
     return passFinding(
       "arm-session-dir",
       `[${p.name}] no live omp-telegram claim — arm scans the tick-cwd session directory`,
     );
   }
-  const claim = claimForProject(claims, p.name);
-  if (claim === undefined || claim.sessionFile === undefined) {
+  const claims = result.claims;
+  const match = resolveProjectClaim(claims, p.name);
+  const scanDir = sessionDirForCwd(tickCwdForProject(p));
+  if (match.kind === "ambiguous") {
+    // Several live claims answer to the project, so the claim's session file
+    // cannot be told from a sibling pane's. Arm scans the tick-cwd directory
+    // either way, but certifying that fallback as the scan is the miss this
+    // probe exists to surface: the resumed transcript may live under another
+    // claim while doctor reads the fallback as the whole story (#626).
+    return warnFinding(
+      "arm-session-dir",
+      `[${p.name}] several live claims answer to this project (topics ${match.claimants.map((c) => c.threadId).join(", ")}), so the claim's session file is a coin toss — arm scans the tick-cwd session directory, but the resumed transcript may live elsewhere`,
+      `make exactly one live claim answer to this project: rename the other panes' herdr spaces or re-claim them one at a time, then re-run doctor — or start the orchestrator pane's session from the tick cwd ${scanDir}`,
+    );
+  }
+  const claim = match.kind === "match" ? match.claim : undefined;
+  if (claim === undefined) {
+    return passFinding(
+      "arm-session-dir",
+      `[${p.name}] no live omp-telegram claim answers to this project — arm scans the tick-cwd session directory`,
+    );
+  }
+  if (claim.sessionFile === undefined) {
     return passFinding(
       "arm-session-dir",
       `[${p.name}] the live claim names no session file — arm scans the tick-cwd session directory`,
@@ -1110,7 +1194,6 @@ function armSessionDirProbe(probes: Probes, p: ProjectConfig): Finding {
   }
   const root = sessionsRoot();
   const claimDir = dirname(claim.sessionFile);
-  const scanDir = sessionDirForCwd(tickCwdForProject(p));
   if (claimDir !== root && !claimDir.startsWith(join(root, sep))) {
     return failFinding(
       "arm-session-dir",
@@ -1138,43 +1221,208 @@ function armSessionDirProbe(probes: Probes, p: ProjectConfig): Finding {
  *
  * The wizard pins from the claims at setup time, but the bridge re-claims
  * topics across restarts and conductor restarts the service itself (#407), so
- * the pin drifts. On a host with `topicsTidy` on it drifts *structurally*:
- * every pane exit closes the topic, so a pinned id can never be live again.
- * There the pin is vestigial — reporting a dead id as the live destination is
- * the exact false belief this check exists to remove.
+ * the pin drifts. A stale pin is not itself a fault: {@link
+ * resolveProjectTopicId} follows the project's one unambiguous live claim in
+ * that shape (#407/#412), so routing is healthy exactly when a claim answers
+ * to the project. The pin is a fault only when no live claim can take its
+ * place — then sends keep the stale pin and degrade to the flat chat, and the
+ * fix is to re-pin. Removing the pin is never the fix: a missing pin disables
+ * substitution entirely and opts the project into flat chat (#626).
+ *
+ * A registry that cannot be read is neither proof of health nor a stale pin:
+ * the bridge may be fine and the pin live, but nothing can be verified, so the
+ * finding warns and names restoring the registry — never "the pin stands".
+ *
+ * On a host with `topicsTidy` on, a pin drifts *structurally*: every pane exit
+ * closes the topic, so no re-pin survives and the durable fix is to turn tidy
+ * off and re-pin.
  */
 function topicPinProbe(probes: Probes, p: ProjectConfig): Finding {
   const pinned = p.escalation.telegramTopicId;
   if (pinned === undefined) {
     return passFinding(
       "topic-pin",
-      `[${p.name}] no pinned topic id — sends follow the live claim or the flat chat`,
+      `[${p.name}] no pinned topic id — sends go to the flat chat (live-claim substitution only follows a stale pin)`,
+    );
+  }
+  const result = probes.claimedTopics();
+  if (result.kind !== "ok") {
+    return warnFinding(
+      "topic-pin",
+      `[${p.name}] pinned topic ${pinned} — ` +
+        (result.kind === "missing"
+          ? `omp-telegram has no claim registry (threads.json in its state dir), so doctor cannot tell whether the pin is live or a claim answers to this project`
+          : `omp-telegram's claim registry is unreadable (${result.problem}), so doctor cannot tell whether the pin is live or a claim answers to this project`),
+      `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 = probes.claimedTopics();
+  const claims = result.claims;
   if (claims.length === 0) {
     return passFinding(
       "topic-pin",
-      `[${p.name}] pinned topic ${pinned} — no live claims to compare (bridge state unreadable, or not a forum host)`,
+      `[${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`);
   }
+  const match = resolveProjectClaim(claims, p.name);
+  if (match.kind === "match") {
+    return passFinding(
+      "topic-pin",
+      `[${p.name}] pinned topic ${pinned} is not among omp-telegram's live claims, but the ` +
+        `${match.claim.workspaceLabel === p.name ? "herdr space claim" : "claim"} for this project ` +
+        `(topic ${match.claim.threadId}) is live — sends follow it, so topic routing is healthy`,
+    );
+  }
+  if (match.kind === "ambiguous") {
+    // Several live claims answer to the project, so substitution would be a
+    // coin toss and sends keep the stale pin. This is not the no-answer case:
+    // a claim IS waiting for the project, and naming the claimants tells the
+    // operator exactly which panes to disambiguate (#626).
+    return warnFinding(
+      "topic-pin",
+      `[${p.name}] pinned topic ${pinned} is not among omp-telegram's live claims, and several live claims answer to this project ` +
+        `(topics ${match.claimants.map((c) => c.threadId).join(", ")}) — substitution would be a coin toss, so sends keep the stale pin`,
+      `make exactly one live claim answer to this project: rename the other panes' herdr spaces or re-claim them one at a time, then re-run doctor — live-claim substitution follows the unique claim from there`,
+    );
+  }
   if (probes.topicsTidy()) {
     return warnFinding(
       "topic-pin",
-      `[${p.name}] pinned topic ${pinned} is not among omp-telegram's live claims, and this host runs topicsTidy — ` +
-        `the pin is vestigial and can never be live again (every pane exit closes its topic)`,
-      `remove escalation.telegramTopicId from ${p.name}'s config (sends already follow the live claim), or turn topicsTidy off`,
+      `[${p.name}] pinned topic ${pinned} is not among omp-telegram's live claims, no live claim answers ` +
+        `to this project, and this host runs topicsTidy — the pin is vestigial and can never be live again ` +
+        `(every pane exit closes its topic); sends keep the stale pin`,
+      `turn topicsTidy off, then re-run setup to re-pin escalation.telegramTopicId to a currently claimed topic`,
     );
   }
   return warnFinding(
     "topic-pin",
-    `[${p.name}] pinned topic ${pinned} is not among omp-telegram's live claims (${claims.map((c) => c.threadId).join(", ")}) — ` +
-      `sends fall back to the live claim or the flat chat`,
-    `update or remove escalation.telegramTopicId in ${p.name}'s config`,
+    `[${p.name}] pinned topic ${pinned} is not among omp-telegram's live claims (${claims.map((c) => c.threadId).join(", ")}), ` +
+      `and no live claim answers to this project — sends keep the stale pin and degrade to the flat chat`,
+    `update escalation.telegramTopicId to a currently claimed topic, or re-run setup to re-pin`,
+  );
+}
+
+/**
+ * #612/#636 check — whether omp-telegram plumbing is live, *before* the arm
+ * challenge, on the route the challenge actually rides. Read-only — the state
+ * files and liveness probes, no `getUpdates`, no transcript scan, no network.
+ * Renders the shared verdict as its own finding so a dead recipient or dead
+ * poll is immediate and named, not discovered 300 seconds into an arm
+ * challenge.
+ *
+ * Gated on the project's *real* inbound requirement, never on
+ * `escalation.telegramTopicId` (an outbound send destination, not the inbound
+ * shape) and never on `escalation.telegramChatId`, which `armTicks` ignores —
+ * it sends the challenge to the paired owner from the tick's `accessFile`.
+ * Only a project that can arm — a readable tick config naming an `accessFile`
+ * — rides inbound at all, so only that shape runs the verdict: an armed
+ * project with no chat id must still be verified, and a manually pinned
+ * outbound-only target must not fail for absent claim/poll state. The route
+ * is the forum topic the send would use (`resolveProjectTopicId` — the pin,
+ * or the live claim a stale pin substitutes) when one resolves; with no topic
+ * the challenge is unthreaded and the reply routes through the bridge's DM
+ * owner, or — after `/telegram own clear` — the polling session itself. The
+ * finding always renders, so the stable report shape and exit code are
+ * unchanged.
+ */
+function telegramPlumbingProbe(probes: Probes, p: ProjectConfig): Finding {
+  if (!probes.projectArms(p)) {
+    return passFinding(
+      "telegram-plumbing",
+      `[${p.name}] outbound-only paging — no tick accessFile to arm, so no live claim, DM owner or poll ownership is required`,
+    );
+  }
+  const verdict = telegramPlumbingVerdict(
+    probes.armSendTopic(p),
+    { dirs: probes.armScanDirs(p) },
+    {
+      channel: probes.channelState(p),
+      registry: probes.claimedTopics(),
+      poll: probes.pollState(),
+      dmOwner: probes.dmOwner(),
+      alive: probes.pidAlive,
+      lockAlive: probes.lockPidAlive,
+      fresh: probes.lockFresh,
+    },
   );
+  if (verdict.ok) {
+    const named = verdict.proof.includes("claim")
+      ? "verified live claim + live poll"
+      : verdict.proof.includes("dm-owner")
+        ? "verified live dm-owner + live poll"
+        : "verified live local poller session";
+    return passFinding(
+      "telegram-plumbing",
+      `[${p.name}] live omp-telegram plumbing: ${named} (${verdict.proof.join(" + ")})`,
+    );
+  }
+  switch (verdict.reason) {
+    case "channel-down": {
+      const channel = probes.channelState(p);
+      const reason = channel.kind === "down" ? channel.reason : "unexpected channel state";
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] the tick's accessFile does not pair an enabled bridge (${reason}) — an arm challenge could not be sent`,
+        `pair the bot (/telegram pair) and enable the bridge (/telegram on), then re-run doctor`,
+      );
+    }
+    case "registry-unreadable":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] omp-telegram's threads.json is absent, unreadable or malformed — the pinned-or-claimed topic's liveness cannot be verified`,
+        `check the bridge state dir for a valid threads.json (the bridge writes it when a forum pane claims a topic)`,
+      );
+    case "no-topic-claim":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] no live omp-telegram claim carries the topic arming would send into — the pin is stale and no live claim takes its place`,
+        `re-pin escalation.telegramTopicId to a currently claimed topic (or remove it to route the challenge flat), then re-run doctor`,
+      );
+    case "claim-dead":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] the topic's omp-telegram claim records no live pid — the pane behind it is gone`,
+        `restart the claiming pane so the bridge re-claims it with a live pid`,
+      );
+    case "claim-session-outside":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] the topic's claim names a session file outside the session directories arm scans — the challenge reply could never be seen`,
+        `resume the claiming pane's session under ${sessionsRoot()}, or from the tick cwd ${sessionDirForCwd(tickCwdForProject(p))}, then re-run doctor`,
+      );
+    case "no-dm-owner":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] no flat-chat challenge could pass: no dm-owner.json, and bot.lock names no session inside the arm scan surface — the private reply has no recipient arm can see`,
+        `pin the orchestrator session as the DM owner (/telegram own in that pane), or pin escalation.telegramTopicId so the challenge rides a claimed forum topic`,
+      );
+    case "dm-owner-dead":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] omp-telegram's dm-owner.json records no live pid — the pane that receives flat replies is gone`,
+        `restart the pane that owns dm-owner.json so the bridge re-pins it with a live pid`,
+      );
+    case "dm-owner-unrelated":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] the dm-owner.json session sits outside the arm scan surface — a flat reply would land in a transcript no challenge can read`,
+        `pin the orchestrator session as the DM owner (/telegram own in this project's pane), or pin escalation.telegramTopicId so the challenge rides a claimed forum topic`,
+      );
+    case "no-poller-state":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] omp-telegram's bot.lock is absent, unreadable or malformed — nothing owns the poll, so nothing is receiving inbound`,
+        `check the bridge state dir for a bot.lock held by a live poller (the daemon releases it on a getMe or poller failure)`,
+      );
+    case "poller-dead":
+      return failFinding(
+        "telegram-plumbing",
+        `[${p.name}] omp-telegram's bot.lock records no live owner and no fresh heartbeat — Telegram isn't being polled`,
+        `restart the omp-telegram bridge so a poller re-acquires bot.lock`,
+      );
+  }
 }
 
 /**
@@ -1375,6 +1623,9 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
     findings.push(
       passFinding("topic-pin", projectProblem === undefined ? "no project resolved — nothing to check" : `topic pin uncheckable: ${projectProblem}`),
     );
+    findings.push(
+      passFinding("telegram-plumbing", projectProblem === undefined ? "no project resolved — nothing to check" : `telegram plumbing uncheckable: ${projectProblem}`),
+    );
     findings.push(
       passFinding("omp-settings", projectProblem === undefined ? "no project resolved — nothing to check" : `omp settings overlay uncheckable: ${projectProblem}`),
     );
@@ -1384,6 +1635,7 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
       findings.push(herdrAgentNameProbe(probes, p));
       findings.push(armSessionDirProbe(probes, p));
       findings.push(topicPinProbe(probes, p));
+      findings.push(telegramPlumbingProbe(probes, p));
       findings.push(ompSettingsProbe(p, sessionRootState));
     }
   }
@@ -1450,6 +1702,42 @@ export function defaultProbes(): Probes {
     herdrEnv: defaultHerdrEnv,
     claimedTopics: () => claimedTelegramTopics(),
     topicsTidy: () => telegramTopicsTidy(),
+    pollState: () => readTelegramPollState(),
+    dmOwner: () => readTelegramDmOwner(),
+    channelState: (p) => {
+      // The exact tick accessFile armTicks probes — never the state-dir
+      // default, so a project whose tick pairs a different bridge is judged
+      // against its own file.
+      const tick = resolveTickConfig(p.name);
+      if (tick.kind !== "ok" || tick.config.accessFile === undefined) {
+        return { kind: "down", reason: "no tick accessFile" };
+      }
+      return readTelegramChannel(tick.config.accessFile);
+    },
+    projectArms: (p) => {
+      // A tick config only carries inbound when it names an accessFile: the
+      // tick runtime treats a missing one as no fleet bridge (and armTicks
+      // throws without it), so a parseable config with none is no more inbound
+      // than no config at all.
+      const tick = resolveTickConfig(p.name);
+      return tick.kind === "ok" && tick.config.accessFile !== undefined;
+    },
+    armSendTopic: (p) => resolveProjectTopicId(p),
+    armScanDirs: (p) => {
+      // The same session surface armTicks builds from the tick cwd and the
+      // live claim's file: the cwd-derived session directory, plus the claim's
+      // own directory when resume moved the transcript elsewhere (#600).
+      const cwdDir = sessionDirForCwd(tickCwdForProject(p));
+      const claimed = resolveClaimedSessionFile(p);
+      if (claimed === undefined) return [cwdDir];
+      const root = sessionsRoot();
+      const claimDir = dirname(claimed);
+      if (claimDir !== root && !claimDir.startsWith(join(root, sep))) return [cwdDir];
+      return claimDir === cwdDir ? [cwdDir] : [cwdDir, claimDir];
+    },
+    pidAlive,
+    lockPidAlive,
+    lockFresh: (mtimeMs) => Date.now() - mtimeMs < TELEGRAM_LOCK_FRESH_MS,
     tickAgentName: (p) => {
       const tick = readTickConfig(tickCwdForProject(p));
       if (tick.kind !== "ok") return undefined;