omp-conductor 0.16.0 → 0.16.1

package/src/depends-on.ts

@@ -1,34 +1,50 @@
 /**
- * The `Depends-on:` declaration parser (epic #321, slice #419).
+ * The `Depends-on:` declaration parser (epic #321, slices #419/#420).
  *
- * A candidate issue can declare same-repo prerequisites it must not be
- * dispatched before: `Depends-on: #123` (repeatable, one or more per line).
- * Admission reads every referenced issue's live tracker state and holds the
- * candidate while any prerequisite is open, so a worker is never sent at work
- * whose base is not yet merged.
+ * A candidate issue can declare prerequisites it must not be dispatched
+ * before: `Depends-on: #123` (a same-repo issue) or `Depends-on:
+ * owner/repo#123` (an issue in a routed repository), repeatable one or more
+ * per line. Admission reads every referenced issue's live tracker state and
+ * holds the candidate while any prerequisite is open, so a worker is never
+ * sent at work whose base is not yet merged.
  *
  * The parser is deliberately small and strict, the two halves of the contract:
  * the *marker* is matched case-insensitively (so `DEPENDS-ON`, `Depends-On`,
- * `depends-on` all declare), while the *references* are strict bare issue
- * numbers (`#123`). A marker line that carries no strict reference — an empty
- * `Depends-on:`, or a bare non-numeric `Depends-on: #abc` — is never a usable
- * prerequisite, so it is reported as `malformed` for the grooming flag rather
- * than guessed at, and the declaration it belongs to is ignored.
+ * `depends-on` all declare), while the *references* are strict — a bare issue
+ * number (`#123`) or a qualifying `owner/repo#123` with exactly two path
+ * segments glued to the number. A marker line that carries no strict
+ * reference — an empty `Depends-on:`, a bare non-numeric `Depends-on: #abc`,
+ * or a slashed-but-unqualified form that is not `owner/repo#n` — is never a
+ * usable prerequisite, so it is reported as `malformed` for the grooming flag
+ * rather than guessed at, and the declaration it belongs to is ignored.
  *
- * Cross-repo references (a qualifying `owner/repo#n` or `repo#n` form) and
- * graph cycles are later slices (#420/#421) and are deliberately out of scope
- * here: only plain `#<n>` same-repo forms are resolved.
+ * Graph cycles are a later slice (#421) and stay out of scope here.
  */
 
 export interface DependsOnDecl {
-  /** Referenced prerequisite issue numbers, deduplicated, first-seen order. */
+  /** Referenced same-repo prerequisite issue numbers, deduplicated,
+   *  first-seen order. */
   readonly refs: readonly number[];
-  /** Marker-bearing lines that carried no strict `#<n>` reference (e.g.
+  /** Referenced cross-repo prerequisites (`owner/repo#n`), deduplicated,
+   *  first-seen order. Admission resolves these against the fleet's routed
+   *  repositories, never against the candidate's own repo (#420). */
+  readonly crossRefs: readonly DependsOnCrossRef[];
+  /** Marker-bearing lines that carried no strict reference (e.g.
    *  `Depends-on: #abc`). Bounded to what the body actually said, for the
    *  grooming flag's detail. */
   readonly malformed: readonly string[];
 }
 
+/**
+ * A strict cross-repo reference. `repo` is the canonical `owner/repo` spelling
+ * from the body, untouched, so admission can match it by identity against the
+ * fleet's routed repositories rather than by guess.
+ */
+export interface DependsOnCrossRef {
+  readonly repo: string;
+  readonly issue: number;
+}
+
 /**
  * How a line is spelled: `depends-on`/`depends on`, optional whitespace, then
  * a `:` or `=` separator. The marker is matched case-insensitively; the value
@@ -38,13 +54,29 @@ export interface DependsOnDecl {
  */
 const MARKER = /^depends[-\s]?on\s*[:=]\s*(.*)$/i;
 
-/** A strict reference is a bare `#` followed by digits — no repo qualifier,
- *  no words. Everything else is not a prerequisite this slice resolves. */
-const REF = /#(\d+)/g;
+/** A strict same-repo reference is a bare `#` followed by digits — no repo
+ *  qualifier, no words. The negative lookbehind means a `#<n>` glued to a
+ *  word (e.g. `web#7` or `issue#5`) is not a bare reference: without the
+ *  `owner/` segment it is neither a valid cross-repo ref nor a valid
+ *  same-repo one, so it is flagged malformed rather than silently resolved in
+ *  the candidate's own repo. */
+const REF = /(?<![A-Za-z0-9._/-])#(\d+)/g;
+
+/**
+ * A strict cross-repo reference is `owner/repo#<n>` — exactly two path
+ * segments (each a GitHub owner/repository charset run) glued to a bare issue
+ * number, no whitespace. Scanned before {@link REF} and blanked out of the
+ * value, so the trailing `#<n>` is never re-read as a *same-repo* reference:
+ * the whole point of the qualified form is that it names a different
+ * repository, and resolving it in the candidate's own repo is the #420 fake.
+ */
+const CROSS_REF = /([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*)#(\d+)/g;
 
 export function parseDependsOn(body: string): DependsOnDecl {
   const refs: number[] = [];
   const seen = new Set<number>();
+  const crossRefs: DependsOnCrossRef[] = [];
+  const seenCross = new Set<string>();
   const malformed: string[] = [];
   for (const raw of body.split("\n")) {
     const line = raw.trim();
@@ -52,22 +84,39 @@ export function parseDependsOn(body: string): DependsOnDecl {
     const match = MARKER.exec(line);
     if (match === null) continue;
     const value = match[1] ?? "";
+
+    // Cross-repo references first, blanked out of the value so their `#<n>`
+    // cannot also be collected as a same-repo reference below.
+    let lineHadRef = false;
+    const masked = value.replace(CROSS_REF, (whole, owner, name, number) => {
+      const repo = `${owner}/${name}`;
+      const n = Number(number);
+      if (Number.isSafeInteger(n) && !seenCross.has(`${repo}#${n}`)) {
+        seenCross.add(`${repo}#${n}`);
+        crossRefs.push({ repo, issue: n });
+      }
+      lineHadRef = true;
+      return " ".repeat(whole.length);
+    });
+
     REF.lastIndex = 0;
-    const found = [...value.matchAll(REF)];
-    if (found.length === 0) {
-      // A marker line with no strict reference is a malformed declaration:
-      // never crash, never silently claim — the declaration is ignored and
-      // surfaced for grooming.
-      malformed.push(line);
-      continue;
-    }
+    const found = [...masked.matchAll(REF)];
     for (const group of found) {
       const n = Number(group[1]!);
       if (Number.isSafeInteger(n) && !seen.has(n)) {
         seen.add(n);
         refs.push(n);
       }
+      lineHadRef = true;
+    }
+
+    if (!lineHadRef) {
+      // A marker line with no strict reference — same-repo or cross-repo — is
+      // a malformed declaration: never crash, never silently claim — the
+      // declaration is ignored and surfaced for grooming.
+      malformed.push(line);
+      continue;
     }
   }
-  return { refs, malformed };
+  return { refs, crossRefs, malformed };
 }

package/src/doctor.ts

@@ -35,7 +35,7 @@ import {
 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import type { Stats } from "node:fs";
 import { Database } from "bun:sqlite";
 import { stringify } from "yaml";
@@ -54,9 +54,17 @@ import {
   DEFAULT_HERDR_UNIT,
   probeTelegramHealth,
   resolveHerdrSessionWithBridge,
+  sessionsRoot,
+  sessionDirForCwd,
   telegramStateDir,
 } from "./fleet.ts";
 import type { TelegramHealth } from "./status-render.ts";
+import {
+  claimForProject,
+  claimedTelegramTopics,
+  telegramTopicsTidy,
+  type ClaimedTopic,
+} from "./escalate.ts";
 import {
   herdrConductorPluginConfigDir,
   planHostRuntime,
@@ -204,6 +212,10 @@ 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[];
+  /** Whether the bridge's access.json runs per-session topic tidy on. */
+  topicsTidy?: () => 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;
@@ -1068,6 +1080,103 @@ function herdrAgentNameProbe(probes: Probes, p: ProjectConfig): Finding {
   );
 }
 
+/**
+ * #600 check — the orchestrator's claimed session file vs the directory arm
+ * scans.
+ *
+ * A pane resumed from a session created elsewhere keeps the original transcript
+ * path (herdr pins the pane to it), so the claimed file can live outside the
+ * session directory the tick cwd implies. arm follows the claim, so the
+ * mismatch alone is handled — but it is exactly the shape of host that once
+ * made arming silently impossible, and an operator reading transcript paths
+ * should not have to rediscover it. A claimed file *outside the session tree*
+ * is worse: arm refuses to arm there (the reply could never be seen), so
+ * doctor fails rather than letting the fleet sit disarmed.
+ */
+function armSessionDirProbe(probes: Probes, p: ProjectConfig): Finding {
+  const claims = probes.claimedTopics();
+  if (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) {
+    return passFinding(
+      "arm-session-dir",
+      `[${p.name}] the live claim names no session file — arm scans the tick-cwd session directory`,
+    );
+  }
+  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",
+      `[${p.name}] the orchestrator's claimed session file ${claim.sessionFile} is outside the session tree arm scans (${root}) — ` +
+        `arm cannot arm while the reply can only land there`,
+      `start the orchestrator pane's session under ${root}, or from the tick cwd ${scanDir}`,
+    );
+  }
+  if (claimDir !== scanDir) {
+    return warnFinding(
+      "arm-session-dir",
+      `[${p.name}] the orchestrator's claimed session file ${claim.sessionFile} lives in ${claimDir}, not the tick-cwd session directory ${scanDir} — ` +
+        `arm follows the claim, so arming works, but this is the resumed-pane shape #600 names`,
+      `optional tidy-up: start the pane's session from the tick cwd so transcript and cwd agree again`,
+    );
+  }
+  return passFinding(
+    "arm-session-dir",
+    `[${p.name}] the orchestrator's claimed session file is inside the session directory arm scans`,
+  );
+}
+
+/**
+ * #600 check — a pinned escalation.telegramTopicId that no live claim carries.
+ *
+ * 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.
+ */
+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`,
+    );
+  }
+  const claims = probes.claimedTopics();
+  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)`,
+    );
+  }
+  if (claims.some((claim) => claim.threadId === pinned)) {
+    return passFinding("topic-pin", `[${p.name}] pinned topic ${pinned} is a live claim`);
+  }
+  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`,
+    );
+  }
+  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`,
+  );
+}
+
 /**
  * #541 check 2 — `[session] resume_agents_on_restore` on the live herdr config.
  *
@@ -1260,6 +1369,12 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
     findings.push(
       passFinding("herdr-agent-name", projectProblem === undefined ? "no project resolved — nothing to check" : `agent name uncheckable: ${projectProblem}`),
     );
+    findings.push(
+      passFinding("arm-session-dir", projectProblem === undefined ? "no project resolved — nothing to check" : `arm session dir uncheckable: ${projectProblem}`),
+    );
+    findings.push(
+      passFinding("topic-pin", projectProblem === undefined ? "no project resolved — nothing to check" : `topic pin uncheckable: ${projectProblem}`),
+    );
     findings.push(
       passFinding("omp-settings", projectProblem === undefined ? "no project resolved — nothing to check" : `omp settings overlay uncheckable: ${projectProblem}`),
     );
@@ -1267,6 +1382,8 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
     for (const p of projects) {
       findings.push(await labelProbe(probes, p));
       findings.push(herdrAgentNameProbe(probes, p));
+      findings.push(armSessionDirProbe(probes, p));
+      findings.push(topicPinProbe(probes, p));
       findings.push(ompSettingsProbe(p, sessionRootState));
     }
   }
@@ -1331,6 +1448,8 @@ export function defaultProbes(): Probes {
     herdrSession: () => resolveHerdrSessionWithBridge(),
     herdrConfig: defaultHerdrConfig,
     herdrEnv: defaultHerdrEnv,
+    claimedTopics: () => claimedTelegramTopics(),
+    topicsTidy: () => telegramTopicsTidy(),
     tickAgentName: (p) => {
       const tick = readTickConfig(tickCwdForProject(p));
       if (tick.kind !== "ok") return undefined;

package/src/escalate.ts

@@ -436,6 +436,13 @@ export interface ClaimedTopic {
   name: string;
   /** The herdr space the claiming pane sits in, when the bridge captured one. */
   workspaceLabel?: 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
+   * (`omp --resume=<that path>`) — so it can sit in a different session
+   * directory than the pane's cwd implies (#600).
+   */
+  sessionFile?: string;
 }
 
 /**
@@ -470,17 +477,47 @@ export function resolveProjectTopicId(project: ProjectConfig): number | undefine
   const claims = claimedTelegramTopics();
   if (claims.length === 0) return pinned;
   if (claims.some((claim) => claim.threadId === pinned)) return pinned;
-  const bySpace = soleClaim(claims, (claim) => claim.workspaceLabel === project.name);
-  const match = bySpace ?? soleClaim(claims, (claim) => claim.name === project.name);
+  const match = claimForProject(claims, project.name);
   if (match === undefined) return pinned;
   warn(
     `escalation.telegramTopicId for ${project.name} is no longer a claimed topic; ` +
       `following omp-telegram's current "${project.name}" ` +
-      `${bySpace === undefined ? "claim" : "herdr space claim"} instead`,
+      `${match.workspaceLabel === project.name ? "herdr space claim" : "claim"} instead`,
   );
   return match.threadId;
 }
 
+/**
+ * The one claim answering to a project's identity — herdr space first, title
+ * second — or nothing when none or several do (#412).
+ */
+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);
+}
+
+/**
+ * The transcript this project's live omp-telegram claim names — where the
+ * orchestrator pane's reply actually lands.
+ *
+ * `arm` derives its scan directory from the tick cwd, but a pane resumed from
+ * a session created elsewhere keeps the original transcript path (herdr pins
+ * the pane to it), so the cwd-derived directory is the one place the reply is
+ * guaranteed *not* to be (#600). The claim's `sessionFile` is the live answer;
+ * identity resolves exactly as {@link resolveProjectTopicId}'s substitution
+ * does, via {@link claimForProject}. Absent when the bridge has no claim or
+ * the claim names no file — the caller then falls back to the cwd-derived
+ * 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;
+}
+
 /**
  * The one claim answering to `predicate`, or nothing when none or several do.
  *
@@ -523,6 +560,7 @@ export function claimedTelegramTopics(stateDir?: string): ClaimedTopic[] {
     if (!Number.isFinite(threadId) || !Number.isSafeInteger(threadId)) continue;
     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;
@@ -532,12 +570,47 @@ export function claimedTelegramTopics(stateDir?: string): ClaimedTopic[] {
         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 ? { threadId, name } : { threadId, name, workspaceLabel });
+    out.push(
+      workspaceLabel === undefined && sessionFile === undefined
+        ? { threadId, name }
+        : workspaceLabel === undefined
+          ? { threadId, name, sessionFile }
+          : sessionFile === undefined
+            ? { threadId, name, workspaceLabel }
+            : { threadId, name, workspaceLabel, sessionFile },
+    );
   }
   return out;
 }
 
+/**
+ * Whether the paired bridge runs with per-session topic tidy on (access.json
+ * `topicsTidy: true` — `/telegram topics tidy on`).
+ *
+ * On a tidy host every pane exit closes (forum) or deletes (DM) its own topic,
+ * so a pinned `escalation.telegramTopicId` is structurally stale: it can never
+ * be among the live claims again, and treating it as a live pin is the false
+ * belief #600 names. The bridge's own setting is read here so `doctor` can say
+ * "vestigial" rather than "moved once".
+ */
+export function telegramTopicsTidy(stateDirPath?: string): boolean {
+  const override = stateDirPath?.trim() ?? process.env.OMP_TELEGRAM_STATE_DIR?.trim();
+  const dir = override ? override : join(homedir(), ".omp", "agent", "telegram");
+  try {
+    const parsed = JSON.parse(readFileSync(join(dir, "access.json"), "utf8")) as {
+      readonly topicsTidy?: unknown;
+    };
+    return parsed.topicsTidy === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 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