omp-conductor 0.20.0 → 0.20.2

package/src/escalate.ts

@@ -20,11 +20,12 @@
  * those strings end up in daemon logs and, on the fallback path, in a public
  * issue comment.
  */
-import { readFileSync, statSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { availabilityOpen, interruptDisposition, type InterruptDisposition } from "./availability.ts";
+import { stateDir } from "./config.ts";
 import { heldNoticeId } from "./notices.ts";
 import type { OrchestratorHandle } from "./orchestrator.ts";
 import type { Escalation, ProjectConfig, Store, Tracker } from "./types.ts";
@@ -341,7 +342,10 @@ export function createEscalator(
           // the tick re-raises it. A *report* has no such source — it exists
           // once, in the model's head, and nothing regenerates it — which is
           // why that one needed a ledger and this one does not.
-          await sendTelegram(token, chatId, text, { topicId: resolveProjectTopicId(p) });
+          await sendTelegram(token, chatId, text, {
+            topicId: resolveProjectTopicId(p),
+            project: { name: p.name, workspaceRoot: p.workspaceRoot },
+          });
           store.markNotified(key);
           return;
         }
@@ -435,6 +439,98 @@ export function readTelegramToken(): string | undefined {
   return undefined;
 }
 
+/**
+ * One flat-chat delivery that happened only because the project's pinned
+ * topic was unreachable (#1094).
+ *
+ * The fallback is a delivery, not a success: the message reached an audience
+ * that did not ask for it while the topic the project reads stayed empty, and
+ * the only record used to be a journal `warn`. This row is what makes the
+ * mis-route visible where the operator looks: `doctor`'s topic-pin finding
+ * and the project's `status` render the rows matching the *current* pin, so
+ * re-pinning is what retires them. Nothing deletes rows — the file is bounded
+ * and a retired row simply stops matching.
+ */
+export interface TelegramMisroute {
+  /** The project whose message rode the flat chat. */
+  project: string;
+  /** The pinned `escalation.telegramTopicId` Telegram refused. */
+  staleTopicId: number;
+  /** When the flat delivery happened (epoch ms). */
+  at: number;
+}
+
+const TELEGRAM_MISROUTES_FILE = "telegram-misroutes.json";
+/** Diagnostic history, not a ledger: enough to see "again?", never unbounded. */
+const TELEGRAM_MISROUTES_MAX = 20;
+
+/**
+ * Records one flat delivery beside the conductor state. Best-effort by
+ * contract: the delivery has already happened, so a failed breadcrumb must
+ * never turn a completed escalation into a thrown one.
+ */
+export function recordTelegramMisroute(projectName: string, staleTopicId: number, at: number = Date.now()): void {
+  try {
+    const next = [
+      ...readTelegramMisroutes(),
+      { project: projectName, staleTopicId, at },
+    ].slice(-TELEGRAM_MISROUTES_MAX);
+    const path = join(stateDir(), TELEGRAM_MISROUTES_FILE);
+    mkdirSync(stateDir(), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+    renameSync(tmp, path);
+  } catch {
+    // The journal warn still named the degradation; doctor still names the
+    // stale pin. Losing the row costs history, never delivery.
+  }
+}
+
+/**
+ * Every recorded mis-route, oldest first. Unreadable or malformed state reads
+ * empty — a broken breadcrumb file must not break the diagnostics that read
+ * it, and per-row validation keeps a hand-edited entry from poisoning the
+ * render (the same rule #1089 applied to the claim registry's fields).
+ */
+export function readTelegramMisroutes(): readonly TelegramMisroute[] {
+  let raw: string;
+  let parsed: unknown;
+  try {
+    raw = readFileSync(join(stateDir(), TELEGRAM_MISROUTES_FILE), "utf8");
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const rows: TelegramMisroute[] = [];
+  for (const entry of parsed) {
+    if (entry === null || typeof entry !== "object") continue;
+    const project = Reflect.get(entry, "project");
+    const staleTopicId = Reflect.get(entry, "staleTopicId");
+    const at = Reflect.get(entry, "at");
+    if (typeof project !== "string" || project.length === 0) continue;
+    if (typeof staleTopicId !== "number" || !Number.isSafeInteger(staleTopicId)) continue;
+    if (typeof at !== "number" || !Number.isFinite(at)) continue;
+    rows.push({ project, staleTopicId, at });
+  }
+  return rows.sort((a, b) => a.at - b.at);
+}
+
+/**
+ * The one-line notice prepended to a flat fallback (#1094): a reader in the
+ * main chat must know why the message is there and which fleet sent it, not
+ * reverse-engineer it from content — and the pinned id is named so the
+ * operator can act without opening the journal. Exported because the tests
+ * assert its wording and `status`'s misroute row quotes the same condition.
+ */
+export function staleTopicNotice(topicId: number, projectName?: string): string {
+  const who = projectName === undefined ? "This project's" : `[${projectName}] its`;
+  return (
+    `${who} pinned Telegram topic (escalation.telegramTopicId=${topicId}) is stale — ` +
+    `Telegram has no such thread, so this message was delivered to the flat chat instead.`
+  );
+}
+
 /** One live omp-telegram topic claim, as much of it as conductor reads. */
 export interface ClaimedTopic {
   threadId: number;
@@ -448,6 +544,13 @@ export interface ClaimedTopic {
   pid?: number;
   /** The herdr space the claiming pane sits in, when the bridge captured one. */
   workspaceLabel?: string;
+  /**
+   * The claiming pane's working directory, when the bridge captured one. The
+   * bridge records it on every entry it writes; conductor reads it as the one
+   * discriminator it owns for telling a project's own panes apart when several
+   * sit in one herdr space (#1089).
+   */
+  cwd?: string;
   /**
    * The transcript the claiming pane actually writes, when the bridge captured
    * one. This is the *live* session file — herdr pins a restored pane to it
@@ -497,7 +600,7 @@ export function resolveProjectTopicId(project: ProjectConfig, alive?: (pid: numb
   if (claims.some((claim) => claim.threadId === pinned && claimIsLive(claim, alive === undefined ? undefined : killOf(alive)))) {
     return pinned;
   }
-  const match = claimForProject(claims, project.name, alive);
+  const match = claimForProject(claims, project.name, alive, project.workspaceRoot);
   if (match === undefined) return pinned;
   warn(
     `escalation.telegramTopicId for ${project.name} is no longer a claimed topic; ` +
@@ -535,20 +638,36 @@ export type ProjectClaim =
  * *no* live claim carries the project's space — several live claims wearing
  * the space is an ambiguity the title cannot resolve, because the titled
  * claim may be a sibling pane, not this project (#626).
+ *
+ * One same-space ambiguity conductor settles itself (#1089): it provisioned
+ * both panes from its own config, so when the caller supplies the project's
+ * orchestrator cwd — its workspace root, against the console's
+ * `<stateDir>/console/<name>` — exactly one live claimant sitting there is
+ * identification, not a guess. Neither or both matching stays the ambiguity.
  */
 export function resolveProjectClaim(
   claims: readonly ClaimedTopic[],
   projectName: string,
   alive?: (pid: number) => boolean,
+  orchestratorCwd?: string,
 ): ProjectClaim {
   // Dead claims do not vote: a closed pane's row must not turn this project's
   // one live claim into an ambiguity, and must not answer by title on its own
-  // (#987). Ambiguity among genuinely live claims is unchanged (#626).
+  // (#987). Ambiguity among genuinely live claims is narrowed by the one
+  // discriminator conductor owns (#1089), never removed (#626).
   const live = claims.filter((claim) => claimIsLive(claim, alive === undefined ? undefined : killOf(alive)));
   const bySpace = live.filter((claim) => claim.workspaceLabel === projectName);
   if (bySpace.length > 0) {
-    return bySpace.length === 1
-      ? { kind: "match", claim: bySpace[0]! }
+    if (bySpace.length === 1) return { kind: "match", claim: bySpace[0]! };
+    // Conductor provisions every same-space pane from its own config: the
+    // orchestrator pane's cwd is the project's workspace root, the console's
+    // is `<stateDir>/console/<name>` (#1089). Exactly one claimant sitting at
+    // the orchestrator cwd is identification; neither or both matching stays
+    // the coin toss #626 refuses to spin.
+    const orchestrator =
+      orchestratorCwd === undefined ? [] : bySpace.filter((claim) => claim.cwd === orchestratorCwd);
+    return orchestrator.length === 1
+      ? { kind: "match", claim: orchestrator[0]! }
       : { kind: "ambiguous", claimants: bySpace };
   }
   const byTitle = live.filter((claim) => claim.name === projectName);
@@ -571,8 +690,9 @@ export function claimForProject(
   claims: readonly ClaimedTopic[],
   projectName: string,
   alive?: (pid: number) => boolean,
+  orchestratorCwd?: string,
 ): ClaimedTopic | undefined {
-  const match = resolveProjectClaim(claims, projectName, alive);
+  const match = resolveProjectClaim(claims, projectName, alive, orchestratorCwd);
   return match.kind === "match" ? match.claim : undefined;
 }
 
@@ -595,7 +715,7 @@ export function resolveClaimedSessionFile(
 ): string | undefined {
   const result = claimedTelegramTopics();
   if (result.kind !== "ok" || result.claims.length === 0) return undefined;
-  return claimForProject(result.claims, project.name, alive)?.sessionFile;
+  return claimForProject(result.claims, project.name, alive, project.workspaceRoot)?.sessionFile;
 }
 
 /**
@@ -699,6 +819,9 @@ export function claimedTelegramTopics(stateDir?: string): ClaimedTopicsResult {
     if ("sessionFile" in entry && typeof entry.sessionFile !== "string") {
       return { kind: "unavailable", problem: `${registry}: claim "${id}" has a non-string sessionFile` };
     }
+    if ("cwd" in entry && typeof entry.cwd !== "string") {
+      return { kind: "unavailable", problem: `${registry}: claim "${id}" has a non-string cwd` };
+    }
     if ("pid" in entry && (typeof entry.pid !== "number" || !Number.isFinite(entry.pid))) {
       return { kind: "unavailable", problem: `${registry}: claim "${id}" has a non-numeric pid` };
     }
@@ -706,14 +829,17 @@ export function claimedTelegramTopics(stateDir?: string): ClaimedTopicsResult {
     let workspaceLabel: string | undefined;
     let sessionFile: string | undefined;
     let pid: number | undefined;
+    let cwd: string | 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 ("cwd" in entry && entry.cwd.trim() !== "") cwd = entry.cwd.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;
+    if (cwd !== undefined) claim.cwd = cwd;
     out.push(claim);
   }
   return { kind: "ok", claims: out };
@@ -1213,17 +1339,32 @@ function sessionWithinScan(sessionFile: string, dirs: readonly string[]): boolea
  * interleave with each other.
  *
  * Optional `topicId` pins the message to a forum topic (`message_thread_id`).
- * A definitive missing-thread reject retries once as a flat chat and warns, so
- * a deleted topic degrades instead of silently losing the page (#318). The
- * flat retry re-sends the whole split: parts already accepted went into a
- * thread Telegram has just told us is gone, so nothing is readable there that
- * a flat resend would duplicate.
+ * A definitive missing-thread reject degrades in two ordered steps (#1094):
+ * first to the project's one live claim, when `project` names who the send
+ * answers to and the registry identifies exactly one (#1089) — a resend into
+ * the project's own current topic. Only when no topic can be resolved does it
+ * retry as a flat chat, prepending a notice that names the stale pin and the
+ * project, and recording a mis-route row for doctor/status (#318's silent
+ * shape). Every degrade re-sends the whole split: parts already accepted went
+ * into a thread Telegram has just told us is gone, so nothing readable is
+ * ever duplicated.
  */
 export async function sendTelegram(
   token: string,
   chatId: string,
   text: string,
-  opts?: { topicId?: number },
+  opts?: {
+    topicId?: number;
+    /**
+     * Who this send answers to, when it rides a pinned topic (#1094): the
+     * project whose escalation, report, or challenge it carries. Only a
+     * caller that resolved `topicId` for a project passes it, and that pair
+     * is what lets a missing-thread fallback prefer the project's one live
+     * claim, label the flat delivery with the project's name, and record the
+     * mis-route where the operator looks.
+     */
+    project?: { name: string; workspaceRoot?: string };
+  },
 ): Promise<number[]> {
   const topicId =
     opts?.topicId !== undefined && Number.isFinite(opts.topicId) && Number.isSafeInteger(opts.topicId)
@@ -1244,7 +1385,38 @@ export async function sendTelegram(
     warn(
       `escalation.telegramTopicId=${topicId} is stale (${err.message}); retrying flat chat`,
     );
-    return await postTelegramParts(token, chatId, parts, undefined);
+    // #318's flat retry is the last resort, not the first (#1094). When the
+    // claim registry names exactly one live claim for this project — #1089's
+    // cwd discriminator included — the resend follows it: a page landing in
+    // the project's own current topic is not a mis-route at all. A
+    // substitution that itself fails falls through to the labelled flat send
+    // below; delivery outranks tidiness.
+    const project = opts?.project;
+    if (project !== undefined) {
+      try {
+        const registry = claimedTelegramTopics();
+        if (registry.kind === "ok") {
+          const claim = claimForProject(registry.claims, project.name, undefined, project.workspaceRoot);
+          if (claim !== undefined && claim.threadId !== topicId) {
+            warn(`following omp-telegram's live "${project.name}" claim instead of the flat chat`);
+            return await postTelegramParts(token, chatId, parts, claim.threadId);
+          }
+        }
+      } catch (subErr) {
+        warn(
+          `live-claim substitution failed (${subErr instanceof Error ? subErr.message : String(subErr)}); delivering flat`,
+        );
+      }
+    }
+    // Flat, but never silent (#1094): the delivered text names the stale pin
+    // and the project, so the wrong audience knows what it is reading, and
+    // doctor/status gain the evidence against this pin. The record is written
+    // only after the send resolves — a flat send that threw delivered
+    // nothing, and the next tick retries it as a first attempt.
+    const labelled = `${staleTopicNotice(topicId, project?.name)}\n\n${text}`;
+    const ids = await postTelegramParts(token, chatId, telegramTextParts(labelled), undefined);
+    if (project?.name !== undefined) recordTelegramMisroute(project.name, topicId);
+    return ids;
   }
 }