omp-conductor 0.18.0 → 0.18.2

package/src/fleet.ts

@@ -15,20 +15,16 @@
 
 import { spawnSync } from "node:child_process";
 import {
-  createReadStream,
   existsSync,
   mkdirSync,
-  readdirSync,
   readFileSync,
   rmSync,
-  statSync,
   writeFileSync,
 } from "node:fs";
-import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { dirname, join, sep } from "node:path";
 import { findProject, loadConfig, resolveArmProof, stateDir } from "./config.ts";
-import { clearArmChallenge, recordArmChallenge } from "./arm-challenge.ts";
+import { clearArmTransaction, readArmAcknowledgement, recordArmChallenge } from "./arm-challenge.ts";
 import {
   claimedTelegramTopics,
   lockPidAlive,
@@ -50,8 +46,24 @@ import { inspectBriefLayout } from "./brief-upgrade.ts";
 import { dbPath, openStore } from "./store.ts";
 import { renderBriefForProject } from "./setup.ts";
 import { DEFAULT_ARM_PROOF, type ArmProof, type DaemonStop, type ProjectConfig, type Store } from "./types.ts";
-import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
+import { DEFAULT_DEPS, probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
 import { isPaused, setPaused, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
+// The drain surface belongs beside hold/releaseHold on the operator surface:
+// the record is daemon state (implemented next to the pause sentinel), but the
+// later CLI and release #484 children import from here, exactly where they find
+// every other fleet control.
+export {
+  cancelDrain,
+  consumeDrain,
+  createDrain,
+  drainPath,
+  readDrain,
+  type CreateDrainOptions,
+  type DrainProblem,
+  type DrainRecord,
+  type DrainStatus,
+  type DrainVerdict,
+} from "./daemon.ts";
 import {
   healthCheck,
   isAlive,
@@ -59,11 +71,13 @@ import {
   probeUnit,
   runSystemctl,
   stopDaemon,
+  type HealthCheckResult,
   type StopResult,
 } from "./lifecycle.ts";
 import type { WorkerPausePhase } from "./worker.ts";
 import {
   formatFleetStatus,
+  formatGroomingStatus,
   type DaemonProjectHealth,
   type DispatchLayer,
   type FleetDaemonProbe,
@@ -311,19 +325,10 @@ export interface ArmDeps {
    * The orchestrator session file the live omp-telegram claim names for this
    * project, or undefined when there is no (readable) claim. The default
    * resolves the claim the same way the send does; tests inject a fixture.
-   * Absent → arm watches the cwd-derived session directory, the pre-claim
-   * behaviour.
+   * Claim-only feeds it to the plumbing verdict's session-identity checks;
+   * the challenge proof never reads a transcript, so it ignores the claim.
    */
   claimedSessionFile?: () => string | undefined;
-  /**
-   * Waits for the challenge to appear as a user turn somewhere under the scan
-   * directories. The waiter owns transcript discovery — not the caller —
-   * because the reply may land in a session that starts *after* the send, so a
-   * path resolved before the challenge went out can be the wrong file by the
-   * time the operator answers (#142), and because the claimed session file can
-   * sit in a different directory than the tick cwd implies (#600).
-   */
-  waitForUserTurn?: (dirs: readonly string[], code: string, sentAt: number, timeoutMs: number) => Promise<boolean>;
   now?: () => number;
   sleep?: (ms: number) => Promise<void>;
   timeoutMs?: number;
@@ -377,6 +382,13 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
   // one pane that can ask. The challenge names which one, or the operator is
   // answering a question they cannot attribute.
   const named = tick.config.project ?? projectName;
+  // The handshake state key must be exactly what the orchestrator's inbound
+  // adapter computes: TickConfig.project, undefined for a legacy unstamped
+  // config. `named` may fall back to the CLI argument for the challenge text
+  // and config lookups; the state key must not — the adapter has no CLI
+  // argument to fall back to, and a mismatched key would make arming wait on
+  // an acknowledgement that can never be written.
+  const stateKey = tick.config.project;
 
   // The arming proof is a declared per-project policy (#613). A config that
   // cannot name the project fails safe to `challenge` — today's authenticated
@@ -389,15 +401,11 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
     /* no project config — keep today's challenge behaviour */
   }
 
-  // Resolve the orchestrator's live session file *before* the challenge goes
-  // out — the same claim the send follows (#600). A pane resumed from a
-  // session created elsewhere (herdr pins it to the original transcript)
-  // writes a session file outside the directory the tick cwd implies, and a
-  // cwd-derived scan would poll the one place the reply is guaranteed not to
-  // be. A claim outside the session tree arm scans can never be answered, so
-  // that is a stop, not five minutes of polling. (Claim-only resolves the
-  // claim too — the verdict checks the same session identity — but names the
-  // refusal itself rather than throwing the transcript wording.)
+  // The orchestrator's live session file per omp-telegram's claim (#600) —
+  // input to the claim-only verdict's session-identity checks below. The
+  // challenge proof never reads it: its acknowledgement is conductor state,
+  // so where (or whether) a transcript lives is no longer part of arming
+  // (#614).
   const claimed = deps.claimedSessionFile !== undefined ? deps.claimedSessionFile() : claimedOrchestratorSessionFile(named);
 
   // Prefer the project's live forum topic so arm challenges land where
@@ -450,17 +458,6 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
     return { path, alreadyArmed, owner: channel.owner, proof };
   }
 
-  // The transcript proof needs a session tree to poll. The claim-only verdict
-  // needs no such thing — it reads session identity from omp-telegram's own
-  // state — so this stop stays on the challenge path only.
-  const dirs = armSessionScanDirs(tick.cwd, claimed);
-  if (dirs.every((d) => !existsSync(d))) {
-    throw new Error(
-      `no orchestrator session directory under ${dirs.join(" or ")} — ` +
-        `the inbound proof is read from a user turn in a transcript there. Start the pane orchestrator, let it settle, then arm again`,
-    );
-  }
-
   const code = makeChallengeCode();
   const text =
     `Fleet arming check${named === undefined ? "" : ` — project ${named}`}. ` +
@@ -469,54 +466,38 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
 
   const send = deps.sendChallenge ?? sendTelegramMessage;
   const timeoutMs = deps.timeoutMs ?? ARM_CHALLENGE_TIMEOUT_MS;
-  // Read before the send, not after: a transcript untouched since this instant
-  // cannot contain the reply, and that is what the waiter filters on.
   const sentAt = (deps.now ?? Date.now)();
-  // The orchestrator must be able to classify the reply as an *active* arming
-  // proof for as long as this handshake is live, so the authenticated record
-  // (hash + expiry, never the code) is written before the challenge goes out
-  // and cleared the moment this end settles (#415).
-  recordArmChallenge(named, code, sentAt + timeoutMs);
+  // The orchestrator's inbound adapter can only acknowledge an *active*
+  // challenge, so the authenticated pending record (hash + expiry, never the
+  // code) is written before the challenge goes out and settled the moment
+  // this end finishes (#415). The returned id pins the wait below: an
+  // acknowledgement can only ever name the currently-pending id, so replacing
+  // a challenge makes every prior acknowledgement inert.
+  const challengeId = recordArmChallenge(stateKey, code, sentAt, sentAt + timeoutMs);
   try {
     await send(token, channel.owner, text, sendTopic);
   } catch (err) {
-    // The challenge never went out, so it must not linger as a classifiable
-    // proof either.
-    clearArmChallenge(named);
+    // The challenge never went out, so its transaction must not linger as a
+    // classifiable proof either.
+    clearArmTransaction(stateKey, challengeId);
     throw new Error(
       `arm: outbound sendMessage failed — NOT armed: ${err instanceof Error ? err.message : String(err)}`,
     );
   }
 
-  const injected = deps.waitForUserTurn;
-  const scan: SessionScan = injected
-    ? { seen: await injected(dirs, code, sentAt, timeoutMs), scanned: [], ignored: [] }
-    : await waitForChallengeInSessions(dirs, code, sentAt, timeoutMs, deps);
-  if (!scan.seen) {
-    // The proof missed its window: a lookalike reply must not stay classifiable
-    // after arming gave up, so the record is cleared before the failure lands.
-    clearArmChallenge(named);
-    // The claimed session file is named before the bridge/token/chat block: a
-    // rotation under the window is visible from this error alone, and on the
-    // host this guard exists for the claimed file is the one that held the
-    // answer (#600).
-    const listing = [
-      ...(claimed === undefined
-        ? []
-        : [
-            `claimed orchestrator session file: ${claimed}` +
-              (dirs.includes(dirname(claimed))
-                ? " (watched)"
-                : ` (NOT under any watched dir — a reply there can never be seen)`),
-          ]),
-      `session dir: ${dirs.join(", ")}`,
-      ...scan.scanned.map((f) => `  watched: ${f}`),
-      ...scan.ignored.map((f) => `  ignored (stale, last written before the challenge): ${f}`),
-    ].join("\n");
+  // Wait for the orchestrator's own acknowledgement — conductor state written
+  // by the inbound user-turn adapter when the real reply lands (#614). No
+  // transcript is read: the proof no longer depends on where (or whether) a
+  // session file lives, which is exactly the discovery that mis-fired on the
+  // host three times (#614). A wrong-project or lookalike reply writes no
+  // acknowledgement, so the window simply runs out fail-closed.
+  if (!(await waitForArmAcknowledgement(challengeId, timeoutMs, deps))) {
+    clearArmTransaction(stateKey, challengeId);
     throw new Error(
-      `arm: the challenge never arrived as a user turn in time — NOT armed.\n` +
-        listing +
-        `\nInbound Telegram is not reaching the omp session. Check, in order:\n` +
+      `arm: the challenge was never acknowledged in time — NOT armed.\n` +
+        `The orchestrator's inbound adapter acknowledges the reply when it lands as a user turn; ` +
+        `no acknowledgement for challenge ${challengeId} arrived.\n` +
+        `Inbound Telegram is not reaching the omp session. Check, in order:\n` +
         `  * is the bridge polling?      attach and run: /telegram status\n` +
         `  * is another process holding this bot token? Telegram allows exactly one\n` +
         `    getUpdates consumer and rejects the second with HTTP 409.\n` +
@@ -525,10 +506,11 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
   }
 
   writeArmedMarker(path, channel.owner, arm);
-  // The transcript proof landed and this project is armed: the record has done
-  // its job. A stale record would also keep a later unsolicited lookalike alive
-  // longer than the fresh challenge it was cut for.
-  clearArmChallenge(named);
+  // The acknowledgement landed and this project is armed: settling clears this
+  // transaction's pending record and acknowledgement — never a newer
+  // replacement's — so a later unsolicited lookalike stays inert past this
+  // handshake.
+  clearArmTransaction(stateKey, challengeId);
   return { path, alreadyArmed, owner: channel.owner, challenge: code, proof };
 }
 
@@ -1053,21 +1035,15 @@ export function parseHerdrAgentList(rawOutput: string): HerdrAgent[] {
   return out;
 }
 
-async function herdrOmpForegroundPids(paneId: string, deps: PaneStopDeps): Promise<number[]> {
-  const bin = deps.herdrBin ?? "herdr";
-  const session =
-    deps.herdrSession ??
-    resolveHerdrSessionWithBridge({ env: process.env, herdrBin: bin });
-  const res = spawnSync(bin, ["--session", session, "pane", "process-info", "--pane", paneId], {
-    encoding: "utf8",
-    timeout: 8_000,
-    env: process.env,
-  });
-  if (res.error) throw res.error;
-  if (res.status !== 0) {
-    throw new Error((res.stderr ?? res.stdout ?? `process-info exit ${String(res.status)}`).trim());
-  }
-  const raw = (res.stdout ?? "").trim();
+/**
+ * The `process_info` document out of `herdr pane process-info` output
+ * (#832): every caller that maps the fleet pane's live omp processes starts
+ * from this schema, whether the output carries herdr's CLI `result` envelope
+ * or the bare document. Throws when the output cannot be read; the caller
+ * decides what an unreadable answer means.
+ */
+export function parseHerdrProcessInfo(stdout: string, paneId: string): ProcessInfo {
+  const raw = stdout.trim();
   if (raw.length === 0) {
     throw new Error(`herdr pane process-info printed nothing for ${paneId}`);
   }
@@ -1083,10 +1059,27 @@ async function herdrOmpForegroundPids(paneId: string, deps: PaneStopDeps): Promi
   if (info === undefined) {
     throw new Error(`herdr pane process-info has no process_info for ${paneId} — unrecognized schema`);
   }
-  return ompPidsFromProcessInfo(info);
+  return info;
 }
 
-interface ProcessInfo {
+async function herdrOmpForegroundPids(paneId: string, deps: PaneStopDeps): Promise<number[]> {
+  const bin = deps.herdrBin ?? "herdr";
+  const session =
+    deps.herdrSession ??
+    resolveHerdrSessionWithBridge({ env: process.env, herdrBin: bin });
+  const res = spawnSync(bin, ["--session", session, "pane", "process-info", "--pane", paneId], {
+    encoding: "utf8",
+    timeout: 8_000,
+    env: process.env,
+  });
+  if (res.error) throw res.error;
+  if (res.status !== 0) {
+    throw new Error((res.stderr ?? res.stdout ?? `process-info exit ${String(res.status)}`).trim());
+  }
+  return ompPidsFromProcessInfo(parseHerdrProcessInfo(res.stdout ?? "", paneId));
+}
+
+export interface ProcessInfo {
   shell_pid?: number;
   foreground_processes?: ForegroundProc[];
 }
@@ -1121,6 +1114,85 @@ function isOmpProcess(proc: ForegroundProc): boolean {
   return false;
 }
 
+/**
+ * The omp processes the fleet pane claims, resolved to their start times
+ * (#832), or why they could not be read. Structurally identical to
+ * upgrade-verify's `PaneOmpProbe` — the upgrade engine and the post-restart
+ * verifier pass this straight into the pure verdicts, and the type is
+ * repeated here because the verifier leaf must not import this module (fleet
+ * reaches the daemon, which reaches the verifier).
+ */
+export type PaneProbeResult = { starts: readonly number[] } | { problem: string };
+
+/**
+ * Every omp process the fleet pane currently claims by herdr, resolved to
+ * its start time (#832): the pane is where an *external* orchestrator
+ * session lives, and the only fact that proves it reloaded is the live
+ * process's own start — a pane process still running from before the install
+ * began loaded the pre-upgrade extension. Every unreadable answer is a
+ * `problem`: absence of evidence is never a reload.
+ *
+ * `run` is the injected command runner (the upgrade's scripted seam, the
+ * daemon's `runCommand`), and `startTime` resolves one pid to its start —
+ * the /proc read lives with the verifier's other live-process facts.
+ */
+export async function herdrPaneOmpStarts(
+  run: (
+    command: string,
+    args: readonly string[],
+  ) => Promise<{ code: number; stdout: string; stderr: string }>,
+  session: string,
+  startTime: (pid: number) => number | undefined,
+): Promise<PaneProbeResult> {
+  const agents = await run("herdr", ["--session", session, "agent", "list"]);
+  if (agents.code !== 0) {
+    return {
+      problem:
+        `herdr agent list failed: ${agents.stderr.trim() || agents.stdout.trim() || `exit ${agents.code}`}`,
+    };
+  }
+  let parsed: HerdrAgent[];
+  try {
+    parsed = parseHerdrAgentList(agents.stdout);
+  } catch (err) {
+    return { problem: err instanceof Error ? err.message : String(err) };
+  }
+  const starts: number[] = [];
+  for (const agent of parsed) {
+    // A name without a live omp claim is a leftover label, not a pane process.
+    if (agent.agent === undefined) continue;
+    const info = await run("herdr", [
+      "--session",
+      session,
+      "pane",
+      "process-info",
+      "--pane",
+      agent.paneId,
+    ]);
+    if (info.code !== 0) {
+      return {
+        problem:
+          `herdr pane process-info for ${agent.paneId} failed: ` +
+          `${info.stderr.trim() || info.stdout.trim() || `exit ${info.code}`}`,
+      };
+    }
+    let pids: number[];
+    try {
+      pids = ompPidsFromProcessInfo(parseHerdrProcessInfo(info.stdout, agent.paneId));
+    } catch (err) {
+      return { problem: err instanceof Error ? err.message : String(err) };
+    }
+    for (const pid of pids) {
+      const startedAt = startTime(pid);
+      if (startedAt === undefined) {
+        return { problem: `cannot read the start time of pane process ${pid} — reload unproven` };
+      }
+      starts.push(startedAt);
+    }
+  }
+  return { starts };
+}
+
 /**
  * The project a bare read means, when the config leaves no doubt.
  *
@@ -1355,7 +1427,7 @@ export function workerPhasesFromHealthz(
  */
 export function classifyDaemonProjectHealth(
   record: { project?: string } | undefined,
-  health: { ok: boolean; body?: string } | undefined,
+  health: HealthCheckResult | undefined,
   project: string,
 ): DaemonProjectHealth {
   if (record === undefined) return { kind: "stopped" };
@@ -1365,7 +1437,13 @@ export function classifyDaemonProjectHealth(
   if (record.project !== undefined && record.project !== project) {
     return { kind: "other-project", serves: record.project };
   }
-  if (health?.ok !== true) return { kind: "unreachable" };
+  // #685: a timed-out probe is a probe outcome, never a death verdict — the
+  // pid is up but wedged, so it must not read as `not running`. Only a
+  // refusal or other failure (nothing listening, a torn answer) stays
+  // `unreachable`.
+  if (health?.ok !== true) {
+    return health?.failure === "timeout" ? { kind: "unresponsive" } : { kind: "unreachable" };
+  }
   try {
     const payload = JSON.parse(health.body ?? "null") as unknown;
     if (payload === null || typeof payload !== "object") {
@@ -1415,6 +1493,9 @@ export type FleetStatusReport = StatusSnapshot & {
   failureClasses: string | undefined;
   workerPhases: { issue: number; phase: WorkerPausePhase }[];
   intake: string | undefined;
+  /** The project-scoped durable to-spec grooming lifecycle as status lines
+   *  (#809), or nothing when there is nothing to report. */
+  grooming: string | undefined;
   lastStop: DaemonStop | undefined;
   siblings: { project: string; live: number }[];
 };
@@ -1455,7 +1536,12 @@ export async function collectFleetStatus(projectName?: string): Promise<FleetSta
         };
   const healthBody = projectHealth.kind === "ok" ? rawHealth?.body : undefined;
   const cached = codeGraphFromHealthz(healthBody, project.name);
-  const codeGraph = cached ?? (await probeCodeGraph(project));
+  // The runtime half of the code-graph finding (#726): the probe reads the
+  // store-backed per-run observations, so "observed" is always grounded in
+  // dispatched runs, never in the daemon's own process or in mcp.json. The
+  // store stays scoped to the same try/finally as the other reads so a
+  // throwing probe cannot leak its handle.
+  const store = openStore(dbPath());
   const workerPhases = [...workerPhasesFromHealthz(healthBody, project.name)].map(
     ([issue, phase]) => ({ issue, phase }),
   );
@@ -1464,16 +1550,32 @@ export async function collectFleetStatus(projectName?: string): Promise<FleetSta
   // and rendered identically from either project: the daemon_stops table is
   // deliberately not partitioned by project, because the daemon serves every
   // project and the uninvolved one must see who stopped it too.
-  const store = openStore(dbPath());
+  let codeGraph: CodeGraphHealth;
   let lastStop: DaemonStop | undefined;
   let siblings: { project: string; live: number }[] = [];
+  let grooming: string | undefined;
   try {
+    codeGraph =
+      cached ??
+      (await probeCodeGraph(project, {
+        ...DEFAULT_DEPS,
+        graphToolsObservations: () => store.graphToolsObservationCounts(project.name),
+      }));
     lastStop = store.latestDaemonStop();
     // Shared-daemon visibility (#545): every configured project other than the
     // one being viewed, with its live-run count.
     siblings = loadConfig()
       .projects.filter((p) => p.name !== project.name)
       .map((p) => ({ project: p.name, live: store.liveRuns(p.name).length }));
+    // The durable to-spec grooming lifecycle (#809): project-scoped verdict
+    // rows from the store, plus the dispatch snapshot's routed/parked counts —
+    // no tracker read, no second cache, no evidence parsing. Rendered only
+    // when it has something to say.
+    grooming = formatGroomingStatus({
+      records: store.groomingVerdicts(project.name),
+      routed: snapshot.dispatch?.routed ?? 0,
+      parked: snapshot.dispatch?.parked ?? 0,
+    });
   } finally {
     store.close();
   }
@@ -1491,6 +1593,7 @@ export async function collectFleetStatus(projectName?: string): Promise<FleetSta
     failureClasses: failureClassBlock(project.name),
     workerPhases,
     intake: intakeStatusLine(project.name),
+    grooming,
     lastStop,
     siblings,
   };
@@ -1511,6 +1614,7 @@ export function renderFleetStatusReport(report: FleetStatusReport): string {
     report.intake,
     report.lastStop,
     report.siblings,
+    report.grooming,
   );
 }
 
@@ -1768,7 +1872,7 @@ export function sessionDirForCwd(cwd: string): string {
   return join(home, ".omp", "agent", "sessions", slug.replaceAll("/", "-"));
 }
 
-/** The session tree arm scans: every transcript under it, whatever the cwd slug. */
+/** The omp session tree the claim-only verdict judges session identity against. */
 export function sessionsRoot(): string {
   return join(homedir(), ".omp", "agent", "sessions");
 }
@@ -1777,8 +1881,9 @@ export function sessionsRoot(): string {
  * The orchestrator session file omp-telegram's live claim names for this
  * project — the transcript a resumed/restored pane actually writes, which can
  * live in a different session directory than the tick cwd implies (#600).
- * Never throws: no claim, or an unreadable config, means undefined and arm
- * falls back to the cwd-derived directory.
+ * Never throws: no claim, or an unreadable config, means undefined. Only the
+ * claim-only verdict consumes this — the challenge proof reads conductor
+ * state, not transcripts (#614).
  */
 function claimedOrchestratorSessionFile(named: string | undefined): string | undefined {
   if (named === undefined) return undefined;
@@ -1789,35 +1894,6 @@ function claimedOrchestratorSessionFile(named: string | undefined): string | und
   }
 }
 
-/**
- * The session directories `arm` watches for the reply — the cwd-derived one
- * plus, when the live claim's file lives elsewhere, that file's directory.
- *
- * The cwd-derived directory is where a *fresh* session started from the tick
- * cwd writes; the claimed file's directory is where the *restored* pane keeps
- * writing (herdr pins it to the original transcript). Watching both covers a
- * resumed session, a rotated one, and a session that starts after the send.
- *
- * A claim outside the session tree is a stop, not a slower failure: arm polls
- * only transcripts under {@link sessionsRoot}, so a claimed file elsewhere can
- * never satisfy the challenge, and five minutes of polling cannot discover a
- * file that is not in the search set. The throw names both paths.
- */
-function armSessionScanDirs(cwd: string, claimed: string | undefined): string[] {
-  const cwdDir = sessionDirForCwd(cwd);
-  if (claimed === undefined) return [cwdDir];
-  const root = sessionsRoot();
-  const claimDir = dirname(claimed);
-  if (claimDir !== root && !claimDir.startsWith(join(root, sep))) {
-    throw new Error(
-      `arm: the orchestrator's claimed session file ${claimed} is outside the session tree arm scans (${root}) — ` +
-        `no transcript there can satisfy the challenge. Resume the pane under ${root}, or start it from ${cwd}; ` +
-        `arm would otherwise poll ${cwdDir} until the timer runs out`,
-    );
-  }
-  return claimDir === cwdDir ? [cwdDir] : [cwdDir, claimDir];
-}
-
 function makeChallengeCode(): string {
   const bytes = new Uint8Array(4);
   crypto.getRandomValues(bytes);
@@ -1825,6 +1901,31 @@ function makeChallengeCode(): string {
   return `FLEET-${hex}`;
 }
 
+/**
+ * Polls the acknowledgement record for one exact challenge id until the
+ * orchestrator's inbound adapter writes it or the deadline passes (#614).
+ *
+ * The state is a small JSON file re-read every pass, never snapshotted: the
+ * acknowledgement may land at any point in the window, written by the live
+ * orchestrator process. Only a record naming this exact id satisfies the
+ * wait — an acknowledgement cut for a replaced challenge is inert here by
+ * construction, and no transcript anywhere is opened.
+ */
+async function waitForArmAcknowledgement(
+  challengeId: string,
+  timeoutMs: number,
+  deps: ArmDeps,
+): Promise<boolean> {
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const deadline = now() + timeoutMs;
+  for (;;) {
+    if (readArmAcknowledgement(challengeId) !== undefined) return true;
+    if (now() >= deadline) return false;
+    await sleep(5_000);
+  }
+}
+
 /**
  * The one armed-marker write both proofs share: same content, same mode, and
  * the same restamp of the pre-per-project shared marker the heartbeat still
@@ -1838,12 +1939,12 @@ function writeArmedMarker(path: string, owner: string, arm: ArmState): void {
 }
 
 /**
- * The verdict's view of the session surface: the same dirs a challenge would
- * watch, minus the transcript throw. An outside-tree claim is not a reason to
- * stop here — the claim-only verdict names that failure itself
- * (`claim-session-outside` / `dm-owner-unrelated`) with the same session
- * identity rules, so the refusal carries the fact, not an early transcript
- * wording.
+ * The session surface the claim-only verdict judges: the tick-cwd-derived
+ * session directory plus, when the live claim's file lives elsewhere in the
+ * tree, that file's directory (#600). An outside-tree claim is not a reason
+ * to stop here — the verdict names that failure itself
+ * (`claim-session-outside` / `dm-owner-unrelated`), so the refusal carries
+ * the fact.
  */
 function armVerdictScanDirs(cwd: string, claimed: string | undefined): string[] {
   const cwdDir = sessionDirForCwd(cwd);
@@ -1897,108 +1998,6 @@ async function sendTelegramMessage(
   await sendTelegram(token, owner, text, { topicId });
 }
 
-interface SessionScan {
-  seen: boolean;
-  /** `name (mtime <iso>)` for every transcript the last pass actually parsed. */
-  scanned: string[];
-  /** Same shape, for the ones skipped as written before the challenge. */
-  ignored: string[];
-}
-
-/**
- * Polls the session directories — re-read on every pass, never snapshotted —
- * until the challenge shows up as a user turn or the deadline passes.
- *
- * Discovery lives here because the reply can land in a transcript that does not
- * exist yet when the challenge is sent: a rotated session, or the first one of
- * a pane started right after arming (#142). And the scan set can be two
- * directories when the live claim's session file lives outside the tick-cwd
- * directory: the restored pane keeps writing the claimed file, so its
- * directory is watched alongside the cwd-derived one (#600).
- *
- * Files untouched since just before the send are named, not parsed: an append
- * bumps mtime, so a transcript older than the challenge cannot hold the reply,
- * and skipping it keeps a large stale session out of every 5 s pass. A missing
- * directory is not an error — it can vanish under a rotation and reappear.
- */
-async function waitForChallengeInSessions(
-  dirs: readonly string[],
-  code: string,
-  sentAt: number,
-  timeoutMs: number,
-  deps: ArmDeps,
-): Promise<SessionScan> {
-  const now = deps.now ?? Date.now;
-  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
-  const deadline = now() + timeoutMs;
-  for (;;) {
-    const scanned: string[] = [];
-    const ignored: string[] = [];
-    for (const dir of dirs) {
-      let names: string[] = [];
-      try {
-        names = readdirSync(dir);
-      } catch {
-        /* the directory can go away under a rotation; the next pass re-reads it */
-      }
-      for (const name of names.sort()) {
-        if (!name.endsWith(".jsonl")) continue;
-        const path = join(dir, name);
-        let mtimeMs: number;
-        try {
-          mtimeMs = statSync(path).mtimeMs;
-        } catch {
-          continue; /* race */
-        }
-        const label = `${name} (mtime ${new Date(mtimeMs).toISOString()})`;
-        if (mtimeMs < sentAt - 1_000) {
-          ignored.push(label);
-          continue;
-        }
-        scanned.push(label);
-        if (await transcriptHasUserCode(path, code)) return { seen: true, scanned, ignored };
-      }
-    }
-    if (now() >= deadline) return { seen: false, scanned, ignored };
-    await sleep(5_000);
-  }
-}
-
-export async function transcriptHasUserCode(path: string, code: string): Promise<boolean> {
-  if (!existsSync(path)) return false;
-  const rl = createInterface({ input: createReadStream(path, { encoding: "utf8" }), crlfDelay: Infinity });
-  try {
-    for await (const line of rl) {
-      if (line.length === 0) continue;
-      let row: unknown;
-      try {
-        row = JSON.parse(line);
-      } catch {
-        continue;
-      }
-      if (row === null || typeof row !== "object") continue;
-      const rec = row as { readonly [key: string]: unknown };
-      if (rec["type"] !== "message") continue;
-      const message = rec["message"];
-      if (message === null || typeof message !== "object") continue;
-      const msg = message as { readonly [key: string]: unknown };
-      if (msg["role"] !== "user") continue;
-      const content = msg["content"];
-      if (!Array.isArray(content)) continue;
-      for (const part of content) {
-        if (part === null || typeof part !== "object") continue;
-        const p = part as { readonly [key: string]: unknown };
-        if (p["type"] === "text" && typeof p["text"] === "string" && p["text"].includes(code)) {
-          return true;
-        }
-      }
-    }
-  } finally {
-    rl.close();
-  }
-  return false;
-}
-
 // ---------------------------------------------------------------------------
 // probes
 // ---------------------------------------------------------------------------