omp-conductor 0.20.0 → 0.20.2

package/src/diff-flags.ts

@@ -37,7 +37,7 @@
  * repository.
  */
 
-import type { FileLane, PrDiff, PrDiffFile, SettlementFlag } from "./types.ts";
+import type { FileLane, PrDiff, PrDiffFile, SettlementFlag, SettlementFlagKind } from "./types.ts";
 
 // ------------------------------------------------------------------ diff parse
 
@@ -438,20 +438,125 @@ const ASSERTION =
   /^(?:await\s+)?(?:expect|assert|assert_[a-z_]+|assertEquals?|assertTrue|assertFalse|assertThat|assertRaises|assertRaisesRegex|self\.assert[A-Za-z]*|should|chai\.|t\.(?:Error|Fatal)f?|require\.[A-Z][A-Za-z]*|Expect)\s*[.(]/;
 
 /**
- * A named timeout and its value. Only a *raised* one is a finding — a brand-new
- * timeout on a new test is not a weakening — so the value is compared against
- * the same key on the pre-image side and silence is the answer whenever the key
- * appears on only one side.
+ * A named timeout and its value, but only on the test runner's own timeout
+ * surface ({@link onRunnerSurface}) — a matching key handed to the code under
+ * test is a domain parameter, not a runner deadline (#1062). Only a *raised*
+ * one is a finding — a brand-new timeout on a new test is not a weakening — so
+ * the value is compared against the same key on the pre-image side and silence
+ * is the answer whenever the key appears on only one side.
  */
 const TIMEOUT =
-  /\b(timeout|timeoutMs|timeout_ms|timeoutSeconds|deadline|maxDuration|wallClock(?:Ms)?|setTimeout|jest\.setTimeout|retries)\b\s*[:=(]\s*(\d[\d_]*)/gi;
+  /\b(timeout|timeoutMs|timeout_ms|timeoutSeconds|deadline|maxDuration|wallClock(?:Ms)?|setTimeout|jest\.setTimeout|retries)\b\s*([:=(])\s*(\d[\d_]*)/gi;
+
+/** Identifiers that name the test runner itself when a timeout-shaped key is
+ *  called on or passed to them. `t` is the test context (vitest, node:test, a
+ *  Go `*testing.T` helper); `pytest` names the Python runner module. */
+const RUNNER_BINDINGS: Record<string, true> = {
+  test: true,
+  it: true,
+  describe: true,
+  context: true,
+  suite: true,
+  bench: true,
+  jest: true,
+  t: true,
+  pytest: true,
+};
+
+/**
+ * Whether a {@link TIMEOUT} match sits on the runner's own timeout surface of
+ * its line, as opposed to an argument handed to the code under test.
+ *
+ * The audit sees hunks, not files, so the judgement is structural on the
+ * changed line alone, and anything it cannot vouch for stays silent: a flag is
+ * advisory, and a false positive costs the trust in every flag after it
+ * (measured: #614/#896 read a raised `timeoutMs` passed to `arm(...)` — the
+ * challenge window of the code under test — as a weakened test).
+ *
+ * Two positions qualify, both on the runner's own call:
+ *
+ * - the key is called on the runner — `jest.setTimeout(...)`,
+ *   `t.timeout(...)`, `test.setTimeout(...)`, `pytest.mark.timeout(...)` —
+ *   the dotted receiver before the key starts with a runner binding;
+ * - the key is a property of an object literal that is a direct argument of a
+ *   runner call — the trailing per-test configuration: `test("x", fn, {
+ *   timeout: 45_000 })`, `test.use({ retries: 3 })`,
+ *   `describe.configure({ retries: 3 })`.
+ *
+ * Everything else is the code under test: `await arm({ timeoutMs: 60_000 })`,
+ * `const opts = { timeout: 45000 }`, `server.setTimeout(30_000)`. A shape
+ * whose decisive frame is on another line — `}, { timeout: 45000 });` after a
+ * multi-line `test(` — cannot be vouched for from the line alone and also
+ * stays silent.
+ */
+function onRunnerSurface(code: string, match: RegExpMatchArray): boolean {
+  const key = match[1]?.toLowerCase() ?? "";
+  if (RUNNER_BINDINGS[key.split(".")[0] ?? ""] === true) return true;
+
+  const before = code.slice(0, match.index);
+  // The dotted receiver the key is called on: `t.timeout(5000)` reads `t.`,
+  // `pytest.mark.timeout(500)` reads `pytest.mark.`. No receiver — a bare
+  // `timeout: 5000` property — falls through to the config-object rule.
+  let at = before.length - 1;
+  while (at >= 0 && /[A-Za-z0-9_$.]/.test(before[at] ?? "")) at--;
+  const receiver = before.slice(at + 1).replace(/\.$/, "").split(".")[0];
+  if (RUNNER_BINDINGS[receiver ?? ""] === true) return true;
+
+  // A property key (`key: value`) needs the object around it to be the
+  // runner's own configuration; a `key = value` assignment or a bare
+  // `key(5000)` call on the line is never that.
+  if (match[2] !== ":") return false;
+  return inRunnerConfigObject(before);
+}
+
+type RunnerFrame = { kind: "call"; base: string | undefined } | { kind: "obj" };
+
+/** Whether the key sits in an object literal that is a direct argument of a
+ *  call on a runner binding — the trailing per-test configuration:
+ *  `test("x", fn, { timeout: 45_000 })`, `test.use({ retries: 3 })`,
+ *  `describe.configure({ retries: 3 })`. The frames are walked over the line
+ *  prefix only, with strings already stripped by {@link splitCode}, so the
+ *  object's nesting inside the call — a direct argument versus a property of
+ *  a nested object or of the callback's own body — decides the verdict. */
+function inRunnerConfigObject(before: string): boolean {
+  const frames: RunnerFrame[] = [];
+  for (let at = 0; at < before.length; at++) {
+    const ch = before[at];
+    if (ch === "(") {
+      // The dotted name the call was opened on, if any: `test.use(` reads
+      // `test.use`. No name — an arrow's parameter list, or a call on a
+      // previous call's result — means the object below it is not a runner
+      // surface.
+      let end = at;
+      while (end > 0 && /[A-Za-z0-9_$.]/.test(before[end - 1] ?? "")) end--;
+      const chain = before.slice(end, at);
+      frames.push({
+        kind: "call",
+        base: chain.length > 0 && !chain.endsWith(".") ? chain : undefined,
+      });
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
+      frames.push({ kind: "obj" });
+      continue;
+    }
+    if (ch === ")" || ch === "}" || ch === "]") frames.pop();
+  }
+  const object = frames.at(-1);
+  if (object?.kind !== "obj") return false;
+  const enclosing = frames.at(-2);
+  if (enclosing?.kind !== "call") return false;
+  const firstSegment = enclosing.base?.split(".")[0];
+  return firstSegment !== undefined && RUNNER_BINDINGS[firstSegment] === true;
+}
 
 function timeouts(text: string): { key: string; value: number }[] {
   const found: { key: string; value: number }[] = [];
   for (const match of text.matchAll(TIMEOUT)) {
     const key = match[1]?.toLowerCase();
-    const raw = match[2]?.replaceAll("_", "");
+    const raw = match[3]?.replaceAll("_", "");
     if (key === undefined || raw === undefined) continue;
+    if (!onRunnerSurface(text, match)) continue;
     const value = Number(raw);
     if (Number.isSafeInteger(value)) found.push({ key, value });
   }
@@ -552,21 +657,24 @@ export const UNREADABLE_TREE_FLAG: SettlementFlag = {
 
 /**
  * Whether a diff path counts as inside the declared lane: an explicitly
- * declared path, or the co-located test of one — `foo.ts` vouches for
- * `foo.test.ts`, which is the "obviously intended" case. Other test shapes
- * (`.spec.ts`, pytest's `test_` prefix) are not vouched for: the rule is the
- * shape the fleet actually uses, and a lane that wants a differently-shaped
- * sibling declares it. Deliberately one-directional: a lane that declares a
- * *test* file does not vouch for its source, because declaring the test alone
- * is a narrower promise and widening it silently is exactly what this flag
- * exists to name. A containing directory never vouches for its contents
- * either — the lane grammar names files, and a lane that means "everything
- * under `src/`" fails open exactly as an undeclared one would if it cannot
- * name them.
+ * declared path, the co-located test of one, or a descendant of a declared
+ * directory (#1091) — admission's grammar accepts a trailing-`/` entry
+ * ("everything under `src/`"), so settlement honours the same contract rather
+ * than narrowing it back to exact files. The co-located allowance is the
+ * "obviously intended" case: `foo.ts` vouches for `foo.test.ts`. Other test
+ * shapes (`.spec.ts`, pytest's `test_` prefix) are not vouched for: the rule
+ * is the shape the fleet actually uses, and a lane that wants a
+ * differently-shaped sibling declares it. Deliberately one-directional: a lane
+ * that declares a *test* file does not vouch for its source, because declaring
+ * the test alone is a narrower promise and widening it silently is exactly
+ * what this flag exists to name. The directory rule keeps its trailing-slash
+ * boundary explicit: the entry already carries the separator, so `foo/`
+ * covers `foo/bar.ts` at any depth and can never vouch for `foobar/x.ts`.
  */
 function withinLane(path: string, declared: readonly string[]): boolean {
   if (declared.includes(path)) return true;
   for (const d of declared) {
+    if (d.endsWith("/") && path.startsWith(d)) return true;
     if (coLocatedTest(d) === path) return true;
   }
   return false;
@@ -588,11 +696,22 @@ function coLocatedTest(declared: string): string | undefined {
  * The lane is the effective declaration admission resolved at dispatch —
  * `effectiveLane(body, comments)`, so a pre-dispatch comment beats an older
  * body declaration — and the flag uses that resolved snapshot, never a re-parse
- * of the body. The finding names every delivered file outside it, which is the
+ * of the body. Each finding names the delivered files outside it, which is the
  * part a reviewer is worst placed to notice: the diff's own file list is the
  * only surface that shows the escape, and reading PR file lists by hand is
  * exactly what nothing else in the loop does.
  *
+ * An escape splits into up to two findings because it is up to two different
+ * events (#1096): an undeclared production module is scope escaping into code,
+ * while an undeclared test file is usually coverage arriving beside the
+ * behaviour it pins — the #1064/#1080 shape, required work the declaration
+ * could not have named. Naming the class on each finding keeps the second
+ * readable as what it usually is without letting it disguise the first. The
+ * declared source's own `.test` twin is admitted by {@link withinLane}, so
+ * the obvious case raises nothing — and the rule stays one-directional, so a
+ * lane declaring only the test still names its source when the worker edits
+ * it.
+ *
  * Fail-open, like admission: an issue with no lane declaration has nothing to
  * escape, so no flag — a flag on every undeclared run would be noise within a
  * day, worse than no flag. Advisory like every other flag here: a widened lane
@@ -605,11 +724,23 @@ function detectLaneEscape(audit: SettlementAudit, flags: SettlementFlag[]): void
     .map((f) => f.path)
     .filter((path) => !withinLane(path, lane.files));
   if (outside.length === 0) return;
-  flags.push({
-    kind: "lane-escape",
-    file: "(lane)",
-    detail: `PR diff touches files outside the declared file lane: ${outside.join(", ")}`,
-  });
+  // Production first: the rarer, heavier event leads the report block.
+  const production = outside.filter((path) => !isTestPath(path));
+  const otherTests = outside.filter((path) => isTestPath(path));
+  if (production.length > 0) {
+    flags.push({
+      kind: "lane-escape",
+      file: "(lane)",
+      detail: `PR diff touches production files outside the declared file lane: ${production.join(", ")}`,
+    });
+  }
+  if (otherTests.length > 0) {
+    flags.push({
+      kind: "lane-escape",
+      file: "(lane)",
+      detail: `PR diff touches unrelated test files outside the declared file lane: ${otherTests.join(", ")}`,
+    });
+  }
 }
 
 function detectWeakening(audit: SettlementAudit, flags: SettlementFlag[]): void {
@@ -1124,6 +1255,21 @@ const RENDERED_FLAGS = 20;
 
 const HEADING = "settlement audit";
 
+/**
+ * The kinds that mean coverage got weaker — the quiet signals the audit
+ * exists to deliver, and the family mining.ts mines. Presentation keeps them
+ * ahead of everything else and lane escapes last (#1096): a check that fires
+ * on half of all merges gets skimmed, and a skimmed finding must not sit
+ * between the reviewer and these. Kept in step with `WEAKENING_KINDS` in
+ * mining.ts, which is the same four kinds spelled for mining.
+ */
+const TEST_INTEGRITY_KINDS: Partial<Record<SettlementFlagKind, true>> = {
+  "test-file-deleted": true,
+  "test-disabled": true,
+  "assertions-removed": true,
+  "test-timeout-raised": true,
+};
+
 /**
  * The flag block appended to a settlement report, or no lines at all.
  *
@@ -1148,7 +1294,17 @@ export function formatSettlementFlags(
     `${HEADING}: ${flags.length} advisory flag(s) — the run's state is unchanged by them` +
       (diff.truncated ? ", and the PR diff was too large to read in full" : ""),
   ];
-  for (const flag of flags.slice(0, RENDERED_FLAGS)) {
+  // Presentation order is structural, not incidental: test-integrity flags
+  // first, then everything else, lane escapes last (#1096). The analyser
+  // emits them in roughly this order already, but this surface also renders
+  // stored rows and post-settlement appends, whose order nobody chose.
+  const rank = (flag: SettlementFlag): number =>
+    TEST_INTEGRITY_KINDS[flag.kind] === true ? 0 : flag.kind === "lane-escape" ? 2 : 1;
+  const ordered = flags
+    .map((flag, index) => ({ flag, index }))
+    .sort((a, b) => rank(a.flag) - rank(b.flag) || a.index - b.index)
+    .map((entry) => entry.flag);
+  for (const flag of ordered.slice(0, RENDERED_FLAGS)) {
     if (flag.kind === "pr-adopted") {
       lines.push(`  ${flag.kind} — ${flag.detail}`);
       continue;
@@ -1165,10 +1321,30 @@ export function formatSettlementFlags(
 }
 
 /** The one-line form for `omp-conductor status`, where a flagged run has to be
- *  visible long after its escalation was delivered and deduplicated. */
+ *  visible long after its escalation was delivered and deduplicated. Lane
+ *  escapes are presented apart from the test-integrity family (#1096), so the
+ *  noisy check cannot bury the quiet one in one comma join. */
 export function settlementFlagSummary(flags: readonly SettlementFlag[] | undefined): string | undefined {
   if (flags === undefined || flags.length === 0) return undefined;
-  const kinds = [...new Set(flags.map((f) => f.kind))].join(", ");
+  const integrity = new Set<SettlementFlagKind>();
+  const lane = new Set<SettlementFlagKind>();
+  const rest = new Set<SettlementFlagKind>();
+  for (const { kind } of flags) {
+    if (TEST_INTEGRITY_KINDS[kind] === true) integrity.add(kind);
+    else if (kind === "lane-escape") lane.add(kind);
+    else rest.add(kind);
+  }
+  const segments: { label?: string; kinds: SettlementFlagKind[] }[] = [];
+  if (integrity.size > 0) segments.push({ label: "test-integrity", kinds: [...integrity] });
+  if (rest.size > 0) segments.push({ kinds: [...rest] });
+  if (lane.size > 0) segments.push({ label: "lane", kinds: [...lane] });
+  // One family alone reads exactly as before — a label with nothing to
+  // separate is furniture.
+  const parts = segments.map((segment) =>
+    segments.length > 1 && segment.label !== undefined
+      ? `${segment.label}: ${segment.kinds.join(", ")}`
+      : segment.kinds.join(", "),
+  );
   const loud = flags.some((f) => f.unattributed === true) ? ", some unattributed" : "";
-  return `${HEADING}: ${flags.length} flag(s) — ${kinds}${loud}`;
+  return `${HEADING}: ${flags.length} flag(s) — ${parts.join("; ")}${loud}`;
 }

package/src/doctor.ts

@@ -71,6 +71,7 @@ import {
   killOf,
   readTelegramChannel,
   readTelegramDmOwner,
+  readTelegramMisroutes,
   readTelegramPollState,
   resolveClaimedSessionFile,
   resolveProjectClaim,
@@ -82,6 +83,7 @@ import {
   type TelegramChannelState,
   type TelegramDmOwnerState,
   type TelegramPollState,
+  type TelegramMisroute,
 } from "./escalate.ts";
 import {
   herdrConductorPluginConfigDir,
@@ -286,6 +288,11 @@ export interface DoctorDeps {
    *  `unavailable` when the registry cannot be read or does not parse — the
    *  caller must not read that as "no claims" (#626). */
   claimedTopics?: () => ClaimedTopicsResult;
+  /** Recorded flat-chat deliveries this project's stale pin already caused
+   *  (#1094), read from conductor state. The topic-pin row renders them as
+   *  observed evidence until the pin is repaired — rows match the *current*
+   *  pin id, so re-pinning is what retires them. */
+  topicMisroutes?: () => readonly TelegramMisroute[];
   /** 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
@@ -1345,8 +1352,8 @@ function armAckProbe(probes: Probes, p: ProjectConfig): Finding {
   if (sighting.expiresAt !== undefined && now >= sighting.expiresAt) {
     return warnFinding(
       "arm-ack",
-      `[${p.name}] an arming challenge from ${window} expired without being settled — it is inert (replies past expiry are refused), but it lingers until this project's next arm replaces it`,
-      `no action needed; the next \`arm\` for this project settles it — re-run doctor afterwards to confirm`,
+      `[${p.name}] an arming challenge from ${window} expired without being settled — it is inert (replies past expiry are refused); the fleet session notifies the operator and clears it once its notice goes out, or the next arm replaces it`,
+      `the code is dead — no reply to it can arm. Re-run the ceremony: \`omp-conductor arm --project ${p.name}\``,
     );
   }
   if (sighting.acknowledgedAt !== undefined) {
@@ -1390,14 +1397,24 @@ function topicPinProbe(probes: Probes, p: ProjectConfig): Finding {
       `[${p.name}] no pinned topic id — sends go to the flat chat (live-claim substitution only follows a stale pin)`,
     );
   }
+  // #1094: sends that already rode the flat chat because of THIS pin turn the
+  // warnings below from hypothetical into observed. Rows are keyed to the pin
+  // id, so re-pinning retires them — nothing deletes them.
+  const misroutes = probes.topicMisroutes().filter(
+    (row) => row.project === p.name && row.staleTopicId === pinned,
+  );
+  const misrouteNote =
+    misroutes.length === 0
+      ? ""
+      : ` It has happened: ${misroutes.length} send(s) were delivered to the flat chat because of this pin, last at ${new Date(misroutes[misroutes.length - 1]!.at).toISOString()}`;
   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`),
+          ? `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${misrouteNote}`
+          : `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${misrouteNote}`),
       `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)`,
     );
   }
@@ -1423,7 +1440,7 @@ function topicPinProbe(probes: Probes, p: ProjectConfig): Finding {
     if (dead.length > 0) {
       return warnFinding(
         "topic-pin",
-        `[${p.name}] pinned topic ${pinned} — every claim in omp-telegram's registry is dead${deadNote}`,
+        `[${p.name}] pinned topic ${pinned} — every claim in omp-telegram's registry is dead${deadNote}${misrouteNote}`,
         `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)`,
       );
     }
@@ -1437,7 +1454,7 @@ function topicPinProbe(probes: Probes, p: ProjectConfig): Finding {
   if (claims.some((claim) => claim.threadId === pinned)) {
     return passFinding("topic-pin", `[${p.name}] pinned topic ${pinned} is a live claim${deadNote}`);
   }
-  const match = resolveProjectClaim(claims, p.name, probes.pidAlive);
+  const match = resolveProjectClaim(claims, p.name, probes.pidAlive, p.workspaceRoot);
   if (match.kind === "match") {
     return passFinding(
       "topic-pin",
@@ -1454,7 +1471,7 @@ function topicPinProbe(probes: Probes, p: ProjectConfig): Finding {
     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`,
+        `(topics ${match.claimants.map((c) => c.threadId).join(", ")}) — substitution would be a coin toss, so sends keep the stale pin${misrouteNote}`,
       `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`,
     );
   }
@@ -1463,14 +1480,14 @@ function topicPinProbe(probes: Probes, p: ProjectConfig): Finding {
       "topic-pin",
       `[${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`,
+        `(every pane exit closes its topic); sends keep the stale pin${misrouteNote}`,
       `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(", ")}), ` +
-      `and no live claim answers to this project — sends keep the stale pin and degrade to the flat chat`,
+      `and no live claim answers to this project — sends keep the stale pin and degrade to the flat chat${misrouteNote}`,
     `update escalation.telegramTopicId to a currently claimed topic, or re-run setup to re-pin`,
   );
 }
@@ -2163,6 +2180,7 @@ export function defaultProbes(): Probes {
     herdrConfig: defaultHerdrConfig,
     herdrEnv: defaultHerdrEnv,
     claimedTopics: () => claimedTelegramTopics(),
+    topicMisroutes: () => readTelegramMisroutes(),
     topicsTidy: () => telegramTopicsTidy(),
     pollState: () => readTelegramPollState(),
     dmOwner: () => readTelegramDmOwner(),