omp-conductor 0.16.2 → 0.17.1

package/src/escalate.ts

@@ -20,9 +20,9 @@
  * those strings end up in daemon logs and, on the fallback path, in a public
  * issue comment.
  */
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 import { availabilityOpen, interruptDisposition, type InterruptDisposition } from "./availability.ts";
 import { heldNoticeId } from "./notices.ts";
@@ -434,6 +434,12 @@ export interface ClaimedTopic {
   threadId: number;
   /** The bridge's own title for the claim. */
   name: string;
+  /**
+   * The claiming pane's process id, when the bridge captured one. omp-telegram
+   * treats a claim as live only while this pid is alive; a claim that captured
+   * no pid is indistinguishable from a dead one for liveness purposes.
+   */
+  pid?: number;
   /** The herdr space the claiming pane sits in, when the bridge captured one. */
   workspaceLabel?: string;
   /**
@@ -458,7 +464,7 @@ export interface ClaimedTopic {
  * The operator's pin still wins whenever it is live. Only a pin that is
  * *provably* absent from the current claims is replaced, and only by the claim
  * this project can be identified with — so a deliberately separate alerts topic
- * is never hijacked by the pane's own thread. Unreadable bridge state changes
+ * is never hijacked by the pane's own thread. Unavailable bridge state changes
  * nothing, and #318's stale-topic retry remains the last line of defence.
  *
  * Identity is read from the herdr space first, and only then from the claim's
@@ -474,8 +480,9 @@ export interface ClaimedTopic {
 export function resolveProjectTopicId(project: ProjectConfig): number | undefined {
   const pinned = project.escalation.telegramTopicId;
   if (pinned === undefined) return undefined;
-  const claims = claimedTelegramTopics();
-  if (claims.length === 0) return pinned;
+  const result = claimedTelegramTopics();
+  if (result.kind !== "ok" || result.claims.length === 0) return pinned;
+  const claims = result.claims;
   if (claims.some((claim) => claim.threadId === pinned)) return pinned;
   const match = claimForProject(claims, project.name);
   if (match === undefined) return pinned;
@@ -488,15 +495,64 @@ export function resolveProjectTopicId(project: ProjectConfig): number | undefine
 }
 
 /**
- * The one claim answering to a project's identity — herdr space first, title
- * second — or nothing when none or several do (#412).
+ * The one claim answering to this project — or the reason there is none.
+ *
+ * `kind: "match"` is the unique claim a substitution can follow. `ambiguous`
+ * is the multi-answer case: several claims wearing the project's space (or,
+ * when no claim wears a space at all, several wearing its title) means the
+ * bridge cannot say which pane belongs to this project. A caller that must
+ * not certify a guess — doctor's arm probe, which would have to pick a
+ * session file — needs this spelled out, not collapsed into "none".
+ */
+export type ProjectClaim =
+  | { readonly kind: "match"; readonly claim: ClaimedTopic }
+  | { readonly kind: "none" }
+  | { readonly kind: "ambiguous"; readonly claimants: readonly ClaimedTopic[] };
+
+/**
+ * How the live claims answer to a project, identity spellings in order:
+ * unique herdr space, then unique title.
+ *
+ * Ambiguity is not a coin toss: paging the wrong project's topic is worse
+ * than the flat-chat degrade #318 already handles, and scanning the wrong
+ * pane's session misses the reply entirely. The title is a fallback for
+ * bridges that never captured a space, so it runs only when *no* claim
+ * carries the project's space — several claims wearing the space is an
+ * ambiguity the title cannot resolve, because the titled claim may be a
+ * sibling pane, not this project (#626).
+ */
+export function resolveProjectClaim(
+  claims: readonly ClaimedTopic[],
+  projectName: string,
+): ProjectClaim {
+  const bySpace = claims.filter((claim) => claim.workspaceLabel === projectName);
+  if (bySpace.length > 0) {
+    return bySpace.length === 1
+      ? { kind: "match", claim: bySpace[0]! }
+      : { kind: "ambiguous", claimants: bySpace };
+  }
+  const byTitle = claims.filter((claim) => claim.name === projectName);
+  if (byTitle.length === 0) return { kind: "none" };
+  return byTitle.length === 1
+    ? { kind: "match", claim: byTitle[0]! }
+    : { kind: "ambiguous", claimants: byTitle };
+}
+
+/**
+ * The unique live claim answering to a project, if exactly one does.
+ *
+ * `undefined` covers both "no claim answers" and "several answer" — {@link
+ * resolveProjectClaim} is the one that tells them apart. Callers that may
+ * only fall back (a substitution keeps the pin, a session dir falls back to
+ * the tick cwd) read that as "nothing to follow"; callers that must not
+ * certify a guess need the richer outcome.
  */
 export function claimForProject(
   claims: readonly ClaimedTopic[],
   projectName: string,
 ): ClaimedTopic | undefined {
-  const bySpace = soleClaim(claims, (claim) => claim.workspaceLabel === projectName);
-  return bySpace ?? soleClaim(claims, (claim) => claim.name === projectName);
+  const match = resolveProjectClaim(claims, projectName);
+  return match.kind === "match" ? match.claim : undefined;
 }
 
 /**
@@ -513,79 +569,130 @@ export function claimForProject(
  * directory, which is the honest answer for a host that predates claims.
  */
 export function resolveClaimedSessionFile(project: ProjectConfig): string | undefined {
-  const claims = claimedTelegramTopics();
-  if (claims.length === 0) return undefined;
-  return claimForProject(claims, project.name)?.sessionFile;
+  const result = claimedTelegramTopics();
+  if (result.kind !== "ok" || result.claims.length === 0) return undefined;
+  return claimForProject(result.claims, project.name)?.sessionFile;
 }
 
 /**
- * The one claim answering to `predicate`, or nothing when none or several do.
- *
- * Ambiguity is not a coin toss: two claims wearing the same identity means the
- * bridge cannot say which pane belongs to this project, and paging the wrong
- * project's topic is worse than the flat-chat degrade #318 already handles.
+ * omp-telegram's canonical thread-id key spelling: a plain positive decimal
+ * integer ("4001"). `Number(id)` alone would coerce `""`, whitespace, `"0"`,
+ * `"01"`, `"1e2"` or `"0x10"` into integers the bridge never wrote — and a
+ * thread id the bridge never wrote is a malformed registry, not a readable
+ * topic (#626).
  */
-function soleClaim(
-  claims: readonly ClaimedTopic[],
-  predicate: (claim: ClaimedTopic) => boolean,
-): ClaimedTopic | undefined {
-  const hits = claims.filter(predicate);
-  return hits.length === 1 ? hits[0] : undefined;
+function parseClaimedTopicId(id: string): number | undefined {
+  if (!/^[1-9][0-9]*$/.test(id)) return undefined;
+  const parsed = Number(id);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
 }
 
+/**
+ * What omp-telegram's live claim registry says, or why it could not be read.
+ *
+ * `kind: "unavailable"` carries the failure instead of collapsing it to an
+ * empty list, so a caller that must tell "no claims" from "cannot tell" — the
+ * #626 doctor check — can stay fail-closed. `kind: "missing"` is the one
+ * absence that is not an operator error: a bridge that has never run a forum
+ * pane has no file at all, exactly as a missing token is not one. Callers that
+ * must not certify a route keep both non-`ok` kinds diagnostic; the setup
+ * wizard is allowed to keep the missing-file silence (#318) while surfacing a
+ * present-but-broken registry.
+ */
+export type ClaimedTopicsResult =
+  | { kind: "ok"; claims: readonly ClaimedTopic[] }
+  | { kind: "missing" }
+  | { kind: "unavailable"; problem: string };
+
 /**
  * omp-telegram's live topic claims, from
  * `{ threads: { "<threadId>": { name, workspaceLabel } } }`. Borrowed exactly as
- * the token is, and tolerant of every shape it might not be — a bridge that has
- * never run a forum pane has no file at all.
+ * the token is. A registry that cannot be read or does not parse as the bridge
+ * shape is `unavailable` with a human reason, never a silent empty list — the
+ * empty list is reserved for a registry that really carries no claims. A single
+ * malformed claim member makes the whole registry `unavailable`: a partial list
+ * would let doctor certify a route it never verified (#626). A registry that
+ * does not exist is `missing`, not an empty list: the bridge may simply never
+ * have claimed, and the caller decides whether that is silence or signal.
  *
  * `stateDir` is passed by the setup wizard, which has already probed for the
  * bridge; send-time callers let it resolve the same way the token does.
  */
-export function claimedTelegramTopics(stateDir?: string): ClaimedTopic[] {
+export function claimedTelegramTopics(stateDir?: string): ClaimedTopicsResult {
   const override = stateDir?.trim() ?? process.env.OMP_TELEGRAM_STATE_DIR?.trim();
   const dir = override ? override : join(homedir(), ".omp", "agent", "telegram");
+  const registry = join(dir, "threads.json");
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(join(dir, "threads.json"), "utf8"));
-  } catch {
-    return [];
+    raw = JSON.parse(readFileSync(registry, "utf8"));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { kind: "missing" };
+    return {
+      kind: "unavailable",
+      problem: `cannot read ${registry}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw) || !("threads" in raw)) {
+    return {
+      kind: "unavailable",
+      problem: `${registry} is not a { threads: { "<threadId>": { name, workspaceLabel } } } registry`,
+    };
   }
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw) || !("threads" in raw)) return [];
   const threads = raw.threads;
-  if (typeof threads !== "object" || threads === null || Array.isArray(threads)) return [];
+  if (typeof threads !== "object" || threads === null || Array.isArray(threads)) {
+    return {
+      kind: "unavailable",
+      problem: `${registry}: "threads" is not a map of claims`,
+    };
+  }
   const out: ClaimedTopic[] = [];
   for (const [id, entry] of Object.entries(threads)) {
-    const threadId = Number(id);
-    if (!Number.isFinite(threadId) || !Number.isSafeInteger(threadId)) continue;
+    const threadId = parseClaimedTopicId(id);
+    if (threadId === undefined) {
+      return {
+        kind: "unavailable",
+        problem: `${registry}: claim "${id}" is not a thread id`,
+      };
+    }
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      return {
+        kind: "unavailable",
+        problem: `${registry}: claim "${id}" is not a { name, workspaceLabel } claim`,
+      };
+    }
+    // A claim member is only as good as its strings: a non-string field means
+    // the registry is not the shape the bridge writes, and coercing it would
+    // let doctor certify a route it never verified (#626). Same for the pid —
+    // the bridge records a number or nothing, so any other spelling fails the
+    // registry instead of being dressed up as a live owner. Empty strings are
+    // the bridge's own spelling for an absent field, so they stay readable.
+    if ("name" in entry && typeof entry.name !== "string") {
+      return { kind: "unavailable", problem: `${registry}: claim "${id}" has a non-string name` };
+    }
+    if ("workspaceLabel" in entry && typeof entry.workspaceLabel !== "string") {
+      return { kind: "unavailable", problem: `${registry}: claim "${id}" has a non-string workspaceLabel` };
+    }
+    if ("sessionFile" in entry && typeof entry.sessionFile !== "string") {
+      return { kind: "unavailable", problem: `${registry}: claim "${id}" has a non-string sessionFile` };
+    }
+    if ("pid" in entry && (typeof entry.pid !== "number" || !Number.isFinite(entry.pid))) {
+      return { kind: "unavailable", problem: `${registry}: claim "${id}" has a non-numeric pid` };
+    }
     let name = id;
     let workspaceLabel: string | undefined;
     let sessionFile: string | undefined;
-    if (typeof entry === "object" && entry !== null) {
-      if ("name" in entry) {
-        const candidate = entry.name;
-        if (typeof candidate === "string" && candidate.trim() !== "") name = candidate.trim();
-      }
-      if ("workspaceLabel" in entry) {
-        const candidate = entry.workspaceLabel;
-        if (typeof candidate === "string" && candidate.trim() !== "") workspaceLabel = candidate.trim();
-      }
-      if ("sessionFile" in entry) {
-        const candidate = entry.sessionFile;
-        if (typeof candidate === "string" && candidate.trim() !== "") sessionFile = candidate.trim();
-      }
-    }
-    out.push(
-      workspaceLabel === undefined && sessionFile === undefined
-        ? { threadId, name }
-        : workspaceLabel === undefined
-          ? { threadId, name, sessionFile }
-          : sessionFile === undefined
-            ? { threadId, name, workspaceLabel }
-            : { threadId, name, workspaceLabel, sessionFile },
-    );
+    let pid: number | undefined;
+    if ("name" in entry && entry.name.trim() !== "") name = entry.name.trim();
+    if ("workspaceLabel" in entry && entry.workspaceLabel.trim() !== "") workspaceLabel = entry.workspaceLabel.trim();
+    if ("sessionFile" in entry && entry.sessionFile.trim() !== "") sessionFile = entry.sessionFile.trim();
+    if ("pid" in entry) pid = entry.pid;
+    const claim: ClaimedTopic = { threadId, name };
+    if (workspaceLabel !== undefined) claim.workspaceLabel = workspaceLabel;
+    if (sessionFile !== undefined) claim.sessionFile = sessionFile;
+    if (pid !== undefined) claim.pid = pid;
+    out.push(claim);
   }
-  return out;
+  return { kind: "ok", claims: out };
 }
 
 /**
@@ -611,6 +718,402 @@ export function telegramTopicsTidy(stateDirPath?: string): boolean {
   }
 }
 
+/**
+ * Whether a pid is a live process as `topics.ts` judges a claim
+ * (`src/topics.ts:isAlive`): `process.kill(pid, 0)` throws `ESRCH` for a gone
+ * process, and **any** other error — including `EPERM`, which means the
+ * process exists but is owned by another uid — is dead here. The bridge
+ * declines a claim it cannot prove is alive, so conductor must too; a claim
+ * the bridge would treat as dead is never dressed up as a live recipient.
+ *
+ * `kill` is injectable so a test can deterministically throw `EPERM` without
+ * owning another uid's process. Distinct from {@link lockPidAlive}, which
+ * applies `api.ts`'s opposite rule to the poll lock.
+ */
+export function pidAlive(
+  pid: number,
+  kill: (target: number, signal: number) => void = (target, signal) => {
+    process.kill(target, signal);
+  },
+): boolean {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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
+ * owned by another uid, which is *live* — the bridge reads its own lock with
+ * this rule (`acquireLock`), so a lock owner is judged differently from a
+ * topic claim or the DM owner (see {@link pidAlive}).
+ */
+export function lockPidAlive(
+  pid: number,
+  kill: (target: number, signal: number) => void = (target, signal) => {
+    process.kill(target, signal);
+  },
+): boolean {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * The omp-telegram bridge's single-poller lock cadence, ported from
+ * `src/api.ts` (`LOCK_HEARTBEAT_MS`): the elected poller refreshes `bot.lock`'s
+ * mtime on this interval while it polls.
+ */
+export const TELEGRAM_LOCK_HEARTBEAT_MS = 15_000;
+
+/**
+ * A `bot.lock` whose mtime is younger than this is live regardless of its
+ * recorded pid, ported from `src/api.ts` (`LOCK_FRESH_MS`). This is the
+ * contract that makes daemon-pid liveness insufficient: on a `getMe` or poller
+ * failure the daemon releases `bot.lock`, stops its heartbeat and sleeps while
+ * its own pid and `daemon.json` remain live — so only the lock (or its absence)
+ * says whether anything is actually polling.
+ */
+export const TELEGRAM_LOCK_FRESH_MS = 45_000;
+
+/** The owner record omp-telegram writes into `bot.lock`. */
+export interface TelegramLockOwner {
+  pid: number;
+  startedAt: number;
+  nonce?: string;
+  name?: string;
+  sessionId?: string;
+  sessionFile?: string;
+}
+
+/**
+ * Outcome of reading the bridge's `bot.lock`, told apart so absent or
+ * malformed state is a named failure, never a silent "no poller" (#612).
+ */
+export type TelegramPollState =
+  | { kind: "ok"; owner: TelegramLockOwner; mtimeMs: number }
+  | { kind: "unreadable" };
+
+/**
+ * Parse a `bot.lock` owner record, mirroring omp-telegram's own
+ * `parseLockOwner` (`src/api.ts`) exactly: the first line is the owning pid,
+ * read with `Number.parseInt(firstLine, 10)` — a positive decimal only, so
+ * `0x10` parses to 0 and is no owner rather than becoming 16, and PID 1 is a
+ * valid owner (the bridge excludes only `pid <= 0`). A legacy bare-pid lock
+ * is still an owner (`{ pid, startedAt: 0 }`); a v2 record whose JSON object
+ * repeats the first-line pid is returned whole — carrying the poller's
+ * session identity — and a malformed v2 record falls back to the first-line
+ * pid exactly as the bridge does.
+ */
+function parseTelegramLockOwner(content: string): TelegramLockOwner | undefined {
+  const trimmed = content.trim();
+  if (trimmed === "") return undefined;
+  const newline = trimmed.indexOf("\n");
+  const firstLine = newline === -1 ? trimmed : trimmed.slice(0, newline);
+  const pid = Number.parseInt(firstLine, 10) || 0;
+  if (pid <= 0) return undefined;
+  if (newline !== -1) {
+    try {
+      const owner: unknown = JSON.parse(trimmed.slice(newline + 1));
+      if (typeof owner === "object" && owner !== null && !Array.isArray(owner)) {
+        const record = owner as { readonly pid?: unknown };
+        if (record.pid === pid) return owner as TelegramLockOwner;
+      }
+    } catch {
+      // Malformed v2 record — fall back to the first-line pid, as the bridge does.
+    }
+  }
+  return { pid, startedAt: 0 };
+}
+
+/**
+ * The omp-telegram bridge's poll ownership, from the same state dir as
+ * `threads.json` (`bot.lock`). `unreadable` when the file is absent,
+ * unreadable or not a valid owner record — a bridge that is not polling holds
+ * no lock, and a malformed record is a named failure, never a pass. The
+ * `mtimeMs` is the file's own mtime, so the caller can apply the bridge's
+ * freshness rule (a heartbeat younger than {@link TELEGRAM_LOCK_FRESH_MS} is
+ * live even when the recorded pid is gone).
+ */
+export function readTelegramPollState(stateDir?: string): TelegramPollState {
+  const override = stateDir?.trim() ?? process.env.OMP_TELEGRAM_STATE_DIR?.trim();
+  const dir = override ? override : join(homedir(), ".omp", "agent", "telegram");
+  const lockPath = join(dir, "bot.lock");
+  let mtimeMs: number;
+  let raw: string;
+  try {
+    mtimeMs = statSync(lockPath).mtimeMs;
+    raw = readFileSync(lockPath, "utf8");
+  } catch {
+    return { kind: "unreadable" };
+  }
+  const owner = parseTelegramLockOwner(raw);
+  if (owner === undefined) return { kind: "unreadable" };
+  return { kind: "ok", owner, mtimeMs };
+}
+
+/**
+ * The live untopiced-DM recipient omp-telegram pins (`dm-owner.json`), as much
+ * as conductor reads. The bridge routes an *unthreaded* private reply to
+ * whatever session owns this file — never to a project-matched
+ * `threads.json` claim, which is the forum route's owner (`src/bridge.ts`).
+ */
+export interface TelegramDmOwner {
+  pid: number;
+  name?: string;
+  sessionId?: string;
+  sessionFile?: string;
+  workspaceLabel?: string;
+}
+
+/**
+ * Outcome of reading the bridge's `dm-owner.json`. Mirrors omp-telegram's own
+ * `loadDmOwner` (`src/topics.ts`): the record is a live `ThreadEntry`, so a
+ * `pid` that is not a finite number — an absent file, or a malformed record —
+ * is no owner at all. Absent and unreadable are deliberately one state: for
+ * the flat route both mean the private reply has no pinned recipient, which
+ * is a named failure, never a silent pass.
+ */
+export type TelegramDmOwnerState =
+  | { kind: "ok"; owner: TelegramDmOwner }
+  | { kind: "unreadable" };
+
+/**
+ * The bridge's untopiced-DM recipient, from the same state dir as
+ * `threads.json` (`dm-owner.json`).
+ */
+export function readTelegramDmOwner(stateDir?: string): TelegramDmOwnerState {
+  const override = stateDir?.trim() ?? process.env.OMP_TELEGRAM_STATE_DIR?.trim();
+  const dir = override ? override : join(homedir(), ".omp", "agent", "telegram");
+  let raw: string;
+  try {
+    raw = readFileSync(join(dir, "dm-owner.json"), "utf8");
+  } catch {
+    return { kind: "unreadable" };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { kind: "unreadable" };
+  }
+  const record = parsed as { readonly [key: string]: unknown };
+  const pid = record["pid"];
+  if (typeof pid !== "number" || !Number.isFinite(pid)) return { kind: "unreadable" };
+  const owner: TelegramDmOwner = { pid };
+  for (const key of ["name", "sessionId", "sessionFile", "workspaceLabel"] as const) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") owner[key] = value.trim();
+  }
+  return { kind: "ok", owner };
+}
+
+/**
+ * The paired inbound channel as the tick defines it, probed exactly the way
+ * `armTicks` probes it (the access file must parse, the bridge must be
+ * enabled and `allowFrom` must hold exactly one paired owner). Anything else
+ * — a missing or unreadable file, a disabled bridge, a missing or foreign
+ * pair — is down with the arm's own reason.
+ */
+export type TelegramChannelState =
+  | { kind: "up"; owner: string }
+  | { kind: "down"; reason: string };
+
+/**
+ * The paired inbound channel verdict, byte-identical to the one `armTicks`
+ * reads through its own `readPairedChannel` (fleet.ts keeps that one private;
+ * this port lives with the other bridge-state readers so `doctor` and the arm
+ * challenge can never disagree): the access file parses, the bridge is
+ * enabled and `allowFrom` holds exactly one paired owner id. Every failure
+ * reason is the arm's own, so a doctor finding and the arm's refusal name the
+ * same fact.
+ */
+export function readTelegramChannel(path: string): TelegramChannelState {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { kind: "down", reason: "unreadable or missing access.json" };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { kind: "down", reason: "access.json is not an object" };
+  }
+  const access = parsed as { readonly [key: string]: unknown };
+  if (access["enabled"] !== true) return { kind: "down", reason: "bridge disabled (enabled !== true)" };
+  const allowFrom = access["allowFrom"];
+  if (!Array.isArray(allowFrom) || allowFrom.length !== 1) {
+    return { kind: "down", reason: "allowFrom must hold exactly one paired owner id" };
+  }
+  const owner = allowFrom[0];
+  if (typeof owner !== "string" && typeof owner !== "number") {
+    return { kind: "down", reason: "paired owner id is not a string or number" };
+  }
+  return { kind: "up", owner: String(owner) };
+}
+
+/** A fact a live-plumbing verdict verified; a pass names which kinds it proved. */
+export type TelegramPlumbingProof = "claim" | "dm-owner" | "poller";
+
+/**
+ * The bounded reasons a live-plumbing verdict fails, each naming the fact that
+ * failed. Forum-route failures name the topic claim the challenge would send
+ * into; flat-route failures name the reply's recipient. An unreadable or
+ * malformed state is always its own named failure — never folded into "no
+ * claim"/"no owner", which would read as a pass.
+ */
+export type TelegramPlumbingFailureReason =
+  | "channel-down"
+  | "registry-unreadable"
+  | "no-topic-claim"
+  | "claim-dead"
+  | "claim-session-outside"
+  | "no-dm-owner"
+  | "dm-owner-dead"
+  | "dm-owner-unrelated"
+  | "no-poller-state"
+  | "poller-dead";
+
+/**
+ * The liveness-checked verdict on omp-telegram plumbing, reusable by `arm`,
+ * `doctor` and recovery. A pass names the proof kinds only — never a chat or
+ * topic identifier, which are exactly the values that leak from log lines.
+ */
+export type TelegramPlumbingVerdict =
+  | { ok: true; proof: readonly TelegramPlumbingProof[] }
+  | { ok: false; reason: TelegramPlumbingFailureReason };
+
+/** Pure-code wiring so a test injects live/dead pids and freshness without touching the host. */
+export interface TelegramPlumbingProbe {
+  /**
+   * The typed claim-registry read. Consulted only on the forum route — a flat
+   * challenge never reads a claim. Any non-`ok` kind is a named failure.
+   */
+  registry: ClaimedTopicsResult;
+  /** The typed `bot.lock` poll-ownership read — absent/malformed is a named failure. */
+  poll: TelegramPollState;
+  /**
+   * The typed `dm-owner.json` read — the untopiced-DM recipient a flat
+   * challenge's reply routes through. Consulted only on the flat route.
+   */
+  dmOwner: TelegramDmOwnerState;
+  /**
+   * The paired inbound channel state, exactly as `armTicks` reads it. Down is
+   * a named failure on both routes: the arm challenge sends to the paired
+   * owner, so no channel means no challenge can go out at all.
+   */
+  channel: TelegramChannelState;
+  /**
+   * Whether a recorded claim or dm-owner pid is a live process, with `topics.ts`
+   * semantics (`src/topics.ts:isAlive`): `EPERM` is dead. Distinct from
+   * {@link lockPidAlive} — the bridge itself uses two rules.
+   */
+  alive: (pid: number) => boolean;
+  /**
+   * Whether a recorded bot.lock owner pid is a live process, with `api.ts`
+   * semantics (`src/api.ts:pidAlive`): `EPERM` means the process exists but is
+   * owned by another uid, so it is *live*. The bridge reads its own lock with
+   * this rule (`acquireLock`), so a lock owner is judged differently from a
+   * topic claim or the DM owner.
+   */
+  lockAlive: (pid: number) => boolean;
+  /**
+   * Whether a lock-file mtime is younger than {@link TELEGRAM_LOCK_FRESH_MS} —
+   * the bridge treats a fresh heartbeat as live even when the recorded pid is
+   * gone (its own `acquireLock` liveness rule).
+   */
+  fresh: (mtimeMs: number) => boolean;
+}
+
+/**
+ * The session surface the arm waiter actually scans for the challenge reply:
+ * {@link armTicks} polls every `.jsonl` transcript *directly inside* these
+ * directories — the tick-cwd-derived session directory plus, when the
+ * project's claim names a session file elsewhere, that file's directory. The
+ * recipient of the reply (a claim's, the DM owner's, or the local poll
+ * owner's session file) must land in this set, or the reply can never satisfy
+ * the challenge even though inbound works.
+ */
+export type TelegramPlumbingScan = { dirs: readonly string[] };
+
+/**
+ * Whether Telegram plumbing is live *now*, without the 300-second challenge and
+ * without any network call, on the route {@link armTicks} actually sends on.
+ *
+ * The paired inbound channel must be up on both routes. Forum route (a
+ * send-time topic was resolved): the claim for that *exact* topic must be
+ * live — never an unrelated project-name match, which is what lets a live
+ * sibling claim false-pass a stale pin — and its session identity must land
+ * inside the scan surface or the reply can never be seen. Flat route (no
+ * topic): the challenge is unthreaded and the reply routes through the DM
+ * owner, so the pinned owner must be live and inside the scan surface; with
+ * no pinned owner (`/telegram own clear`) the bridge delivers locally in the
+ * polling session, so the lock's v2 owner record must carry a session
+ * identity inside the scan surface — a daemon-only or unrelated owner is not a
+ * recipient. On both routes the bridge's poll ownership must be live too:
+ * `bot.lock` holds a valid owner whose pid is alive, or whose heartbeat is
+ * fresh. Any unreadable or malformed state is a deterministic typed failure
+ * naming the failed fact — never a pass. Poll liveness deliberately follows
+ * the lock, not `daemon.json`: on a fatal the daemon releases `bot.lock` and
+ * stops its heartbeat while its own pid stays live (#612 ecosystem
+ * correction).
+ */
+export function telegramPlumbingVerdict(
+  sendTopic: number | undefined,
+  scan: TelegramPlumbingScan,
+  probe: TelegramPlumbingProbe,
+): TelegramPlumbingVerdict {
+  const { registry, poll, dmOwner, channel, alive, lockAlive, fresh } = probe;
+  if (channel.kind === "down") return { ok: false, reason: "channel-down" };
+  let recipient: TelegramPlumbingProof;
+  if (sendTopic !== undefined) {
+    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" };
+    if (claim.sessionFile !== undefined && !sessionWithinScan(claim.sessionFile, scan.dirs)) {
+      return { ok: false, reason: "claim-session-outside" };
+    }
+    recipient = "claim";
+  } else {
+    if (dmOwner.kind === "ok") {
+      if (dmOwner.owner.pid === undefined || !alive(dmOwner.owner.pid)) return { ok: false, reason: "dm-owner-dead" };
+      if (dmOwner.owner.sessionFile === undefined || !sessionWithinScan(dmOwner.owner.sessionFile, scan.dirs)) {
+        return { ok: false, reason: "dm-owner-unrelated" };
+      }
+      recipient = "dm-owner";
+    } else {
+      // No pinned DM owner — after `/telegram own clear` the bridge delivers
+      // local replies in the polling session itself, so the lock's v2 owner
+      // record must name that session. A daemon-only or unrelated owner is no
+      // recipient: the reply would land in a transcript arm never scans.
+      if (poll.kind !== "ok") return { ok: false, reason: "no-dm-owner" };
+      if (poll.owner.sessionFile === undefined || !sessionWithinScan(poll.owner.sessionFile, scan.dirs)) {
+        return { ok: false, reason: "no-dm-owner" };
+      }
+      recipient = "poller";
+    }
+  }
+  if (poll.kind !== "ok") return { ok: false, reason: "no-poller-state" };
+  if (!lockAlive(poll.owner.pid) && !fresh(poll.mtimeMs)) return { ok: false, reason: "poller-dead" };
+  // When the poller's own session is the flat recipient, the live lock is the
+  // whole proof — the recipient and the poll are one fact, not two kinds.
+  return { ok: true, proof: recipient === "poller" ? ["poller"] : [recipient, "poller"] };
+}
+
+/** Whether a session file sits directly inside one of the arm scan directories. */
+function sessionWithinScan(sessionFile: string, dirs: readonly string[]): boolean {
+  return dirs.includes(dirname(sessionFile));
+}
+
 /**
  * The one Telegram send in this package. Exported so the report outbox (#123)
  * reuses it rather than forking it: the response handling below is load-bearing