omp-conductor 0.18.2 → 0.19.1

package/src/fleet.ts

@@ -105,10 +105,11 @@ export const PANE_HALT_FILE = ".conductor-pane-halted";
 export const DEFAULT_HERDR_UNIT = "herdr-fleet.service";
 
 /**
- * Default Herdr session name for conductor fleets. Renamed from `fleet` in
- * #320; `HERDR_SESSION` still wins when set. Legacy hosts that still run a
- * session named `fleet` are bridged for one release by
- * {@link resolveHerdrSession}.
+ * The Herdr session conductor fleets run in. `HERDR_SESSION` wins when set;
+ * this is the only other name any surface may resolve. #320 renamed it from
+ * `fleet` and shipped a one-release probe that preferred a populated legacy
+ * session; #976 removed that probe, because a name resolved two ways is a
+ * name two surfaces can disagree about — and they did, in `upgrade`.
  */
 export const DEFAULT_HERDR_SESSION = "conductor";
 
@@ -121,32 +122,13 @@ export const DEFAULT_HERDR_SESSION = "conductor";
 export const DEFAULT_FLEET_AGENT_NAME = "fleet";
 export const ARM_CHALLENGE_TIMEOUT_MS = 300_000;
 
-
-/** Pre-#320 session name. Bridged for one release when `conductor` is empty. */
-const LEGACY_HERDR_SESSION = "fleet";
-
-export const LEGACY_HERDR_SESSION_HINT =
-  'herdr session "fleet" found — rename it to "conductor" or run omp-conductor setup host to pin HERDR_SESSION=fleet (remove this bridge next minor)';
-
-let legacyHerdrSessionHintPrinted = false;
-
-function noteLegacyHerdrSession(log?: (message: string) => void): void {
-  if (legacyHerdrSessionHintPrinted) return;
-  legacyHerdrSessionHintPrinted = true;
-  if (log) log(LEGACY_HERDR_SESSION_HINT);
-  else console.warn(LEGACY_HERDR_SESSION_HINT);
-}
-
-/** Reset the once-per-process rename hint (tests). */
-export function resetLegacyHerdrSessionHintForTests(): void {
-  legacyHerdrSessionHintPrinted = false;
-}
-
 /**
- * Resolve the Herdr session name. `HERDR_SESSION` is always authoritative.
- * When unset, default to {@link DEFAULT_HERDR_SESSION}. The one-release bridge
- * that prefers a populated legacy `fleet` session lives in
- * {@link resolveHerdrSessionWithBridge} — call that at probe sites.
+ * Resolve the Herdr session name — the single resolution every surface uses.
+ * `HERDR_SESSION` is authoritative; otherwise {@link DEFAULT_HERDR_SESSION}.
+ * Never probe for an alternative name here: a session that answers is not
+ * evidence of which session this fleet is, and the probe that assumed it was
+ * is what made `upgrade` install against `fleet` and verify against
+ * `conductor` (#976).
  */
 export function resolveHerdrSession(env: NodeJS.ProcessEnv = process.env): string {
   const explicit = env["HERDR_SESSION"];
@@ -154,56 +136,6 @@ export function resolveHerdrSession(env: NodeJS.ProcessEnv = process.env): strin
   return DEFAULT_HERDR_SESSION;
 }
 
-function herdrAgentListRaw(
-  session: string,
-  bin: string,
-  env: NodeJS.ProcessEnv,
-): { ok: true; agents: HerdrAgent[] } | { ok: false } {
-  const res = spawnSync(bin, ["--session", session, "agent", "list"], {
-    encoding: "utf8",
-    timeout: 8_000,
-    env,
-  });
-  if (res.error || res.status !== 0) return { ok: false };
-  try {
-    return { ok: true, agents: parseHerdrAgentList(res.stdout ?? "") };
-  } catch {
-    return { ok: false };
-  }
-}
-
-/**
- * One-release bridge (#320): when `HERDR_SESSION` is unset, a `conductor`
- * session with no agents while a `fleet` session answers → use `fleet` and
- * print the rename hint once. Remove next minor.
- */
-export function resolveHerdrSessionWithBridge(opts: {
-  env?: NodeJS.ProcessEnv;
-  herdrBin?: string;
-  log?: (message: string) => void;
-} = {}): string {
-  const env = opts.env ?? process.env;
-  const explicit = env["HERDR_SESSION"];
-  if (explicit !== undefined && explicit.length > 0) return explicit;
-
-  const bin = opts.herdrBin ?? "herdr";
-  const primary = herdrAgentListRaw(DEFAULT_HERDR_SESSION, bin, env);
-  if (primary.ok && primary.agents.length > 0) return DEFAULT_HERDR_SESSION;
-
-  const legacy = herdrAgentListRaw(LEGACY_HERDR_SESSION, bin, env);
-  if (legacy.ok && legacy.agents.length > 0) {
-    noteLegacyHerdrSession(opts.log);
-    return LEGACY_HERDR_SESSION;
-  }
-  // conductor answered (even empty) wins over a dead legacy session.
-  if (primary.ok) return DEFAULT_HERDR_SESSION;
-  if (legacy.ok) {
-    noteLegacyHerdrSession(opts.log);
-    return LEGACY_HERDR_SESSION;
-  }
-  return DEFAULT_HERDR_SESSION;
-}
-
 export function telegramStateDir(): string {
   const override = process.env["OMP_TELEGRAM_STATE_DIR"];
   if (override !== undefined && override.length > 0) return override;
@@ -343,6 +275,14 @@ export interface ArmDeps {
   pidAlive?: (pid: number) => boolean;
   lockPidAlive?: (pid: number) => boolean;
   lockFresh?: (mtimeMs: number) => boolean;
+  /**
+   * Where the pending-proof heartbeat is written (#861). The challenge proof
+   * waits up to five minutes on a human, inside a fence that holds dispatch:
+   * without this, that wait is silent and a healthy process is indistinguishable
+   * from a dead one. Absent means no reporting — the callers that have a surface
+   * (the CLI, the wizard) pass theirs.
+   */
+  progress?: (line: string) => void;
 }
 
 export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promise<ArmResult> {
@@ -484,6 +424,14 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
       `arm: outbound sendMessage failed — NOT armed: ${err instanceof Error ? err.message : String(err)}`,
     );
   }
+  // What is being waited on, before the wait starts: the window, the chat the
+  // reply has to land in, and the fact that dispatch is held until it does
+  // (#861). One line, so a five-minute wait opens with an explanation rather
+  // than with silence.
+  deps.progress?.(
+    `arm: challenge sent to ${channel.owner}${sendTopic === undefined ? "" : ` (topic ${sendTopic})`} — ` +
+      `waiting up to ${armClock(timeoutMs)} for the reply. Dispatch stays held until it arrives.`,
+  );
 
   // Wait for the orchestrator's own acknowledgement — conductor state written
   // by the inbound user-turn adapter when the real reply lands (#614). No
@@ -553,10 +501,14 @@ export interface HaltWithPaneResult extends HaltResult {
 export function hold(
   projectName?: string,
   source: string = "hold",
-  opts: { keepTicks?: boolean } = {},
+  opts: { keepTicks?: boolean; reason?: string } = {},
 ): HoldResult {
   const wasPaused = isPaused(projectName);
-  setPaused(true, { source }, projectName);
+  // `source` is a space-free token by contract (`pauseSourceToken`) — the fence
+  // matches on it, and whitespace there makes a pause the fence cannot prove
+  // (#552). The human sentence belongs in `reason=`, which is why this is a
+  // separate field rather than something a caller concatenates into `source`.
+  setPaused(true, { source, ...(opts.reason === undefined ? {} : { reason: opts.reason }) }, projectName);
   if (opts.keepTicks === true) return { wasPaused };
   return { wasPaused, disarmed: disarmTicks(projectName) };
 }
@@ -717,6 +669,407 @@ export interface HerdrAgent {
   sessionPath?: string;
 }
 
+/**
+ * The Herdr representation of one live conductor worker (#840).
+ *
+ * ## Why this shape, and not `herdr agent start --kind omp`
+ *
+ * The authoritative worker is the `session-host` child conductor spawns itself:
+ * it holds the typed control socket, the mediated verb socket, the worktree, the
+ * transcript, the accounting and the output-schema settlement. Starting a second
+ * OMP process in a pane would look right in the workspace and be authoritative
+ * for nothing — the named silent fake of #840 — so nothing here starts an agent.
+ *
+ * Herdr already has the verb for exactly this case: an *external* supervisor
+ * reports lifecycle onto a pane it owns (`pane report-agent`,
+ * `pane report-agent-session`, `pane release-agent`). So conductor keeps the
+ * child it already spawned, and reports that child's identity and state onto a
+ * pane whose only job is display.
+ *
+ * ## What is displayed, and why that is not "a transcript-tail pane"
+ *
+ * The pane runs `omp-conductor tail <issue>`, which is the repository's existing
+ * read-only follower. The distinction #840 draws is about *authority*, not about
+ * pixels: nothing here parses that output, and no run state, settlement, turn,
+ * spend or model fact is derived from it. Identity comes from the exact child
+ * pid handed over by the spawn path, and state comes from the typed events the
+ * proxy already emits.
+ *
+ * ## Observation-only is structural, not a gate
+ *
+ * The authoritative child is spawned with `stdin: "ignore"` — there is no file
+ * descriptor for a keystroke to travel down, from a pane or anywhere else. The
+ * pane's own process is a follower whose stdin reaches only itself. So "input
+ * cannot reach OMP, change its prompt, invoke a verb, or settle the run" is a
+ * property of the process tree rather than a check that could be forgotten.
+ */
+export interface WorkerPaneIdentity {
+  project: string;
+  issue: number;
+  attempt: number;
+  /** The run row's id — the durable identity the pane is reported under. */
+  runId: string;
+  /** The exact `session-host` pid, from the spawn path's own `onSpawn`. */
+  pid: number;
+  /** The transcript the child opened, when it has already reported one. */
+  sessionFile?: string;
+}
+
+/** A tracked pane, or the explicit reason there is none. Never a silent claim. */
+export type WorkerPaneOutcome =
+  | { kind: "tracked"; paneId: string; label: string; pid: number }
+  | { kind: "unavailable"; reason: string };
+
+/** One `herdr` invocation, injected so every path is testable with no terminal. */
+export type HerdrRun = (args: readonly string[]) => { ok: boolean; stdout: string; stderr: string };
+
+export interface WorkerPaneDeps {
+  run?: HerdrRun;
+  session?: string;
+  /** The follower command the pane displays; the CLI by default. */
+  viewer?: (identity: WorkerPaneIdentity) => readonly string[];
+}
+
+/**
+ * The pane's unique, human-readable name (#840: "uniquely named").
+ *
+ * Keyed by run id rather than issue: an issue can have several attempts, and two
+ * attempts must never resolve to one pane. The issue and attempt ride along
+ * because the operator reads this label in a workspace, not a database.
+ */
+/**
+ * The external-supervisor source every conductor pane report carries.
+ *
+ * This, not the label, is what proves a pane is conductor's: it is written by
+ * `openWorkerPane` and read back by {@link listWorkerPanes}, so the two halves
+ * of reconciliation cannot come to disagree about what "ours" means.
+ */
+export const WORKER_PANE_SOURCE = "omp-conductor";
+
+export function workerPaneLabel(identity: WorkerPaneIdentity): string {
+  return `worker-${identity.project}-${identity.issue}-a${identity.attempt}-${identity.runId.slice(0, 8)}`;
+}
+
+const realHerdrRun: HerdrRun = (args) => {
+  const res = spawnSync("herdr", [...args], { encoding: "utf8", timeout: 8_000, env: process.env });
+  return {
+    ok: !res.error && res.status === 0,
+    stdout: res.stdout ?? "",
+    stderr: res.stderr ?? (res.error === undefined ? "" : String(res.error.message)),
+  };
+};
+
+/** `omp-conductor tail` — read-only by construction, and never parsed here. */
+function defaultViewer(identity: WorkerPaneIdentity): readonly string[] {
+  return ["omp-conductor", "tail", String(identity.issue), "--project", identity.project];
+}
+
+/**
+ * Create the pane, run the follower in it, and report the child's identity and
+ * initial state — or say exactly why it could not.
+ *
+ * Every step is checked, and the first failure returns `unavailable` with the
+ * reason: a partially established representation (a pane with no agent identity,
+ * say) is worse than none, because it is a pane the operator would read as a
+ * tracked worker. What this deliberately does NOT do is decide what a failure
+ * means for the launch — failing closed versus running degraded is #841's
+ * policy, and inventing it here would pre-empt it.
+ */
+export function openWorkerPane(identity: WorkerPaneIdentity, deps: WorkerPaneDeps = {}): WorkerPaneOutcome {
+  const run = deps.run ?? realHerdrRun;
+  const session = deps.session ?? resolveHerdrSession();
+  const label = workerPaneLabel(identity);
+  const base = ["--session", session, "pane"];
+
+  const split = run([...base, "split", "--direction", "down", "--ratio", "0.3"]);
+  if (!split.ok) {
+    return { kind: "unavailable", reason: `herdr pane split failed: ${firstLine(split.stderr) || "no output"}` };
+  }
+  const paneId = firstLine(split.stdout);
+  if (paneId === "") {
+    return { kind: "unavailable", reason: "herdr pane split reported no pane id" };
+  }
+
+  const named = run([...base, "rename", paneId, label]);
+  if (!named.ok) {
+    return { kind: "unavailable", reason: `herdr pane rename failed: ${firstLine(named.stderr) || "no output"}` };
+  }
+
+  // Identity before display: the pane must be attributable to this exact run
+  // before it shows anything, so a pane that appears is never a pane nobody can
+  // trace back to a worker.
+  const identified = run([
+    ...base,
+    "report-agent-session",
+    paneId,
+    "--source",
+    WORKER_PANE_SOURCE,
+    "--agent",
+    label,
+    "--agent-session-id",
+    identity.runId,
+    ...(identity.sessionFile === undefined ? [] : ["--agent-session-path", identity.sessionFile]),
+    "--session-start-source",
+    WORKER_PANE_SOURCE,
+  ]);
+  if (!identified.ok) {
+    return {
+      kind: "unavailable",
+      reason: `herdr pane report-agent-session failed: ${firstLine(identified.stderr) || "no output"}`,
+    };
+  }
+
+  const started = run([...base, "run", paneId, ...deps.viewer?.(identity) ?? defaultViewer(identity)]);
+  if (!started.ok) {
+    return { kind: "unavailable", reason: `herdr pane run failed: ${firstLine(started.stderr) || "no output"}` };
+  }
+
+  // A worker that has just spawned is working by definition. The ongoing
+  // projection of turn/pause/blocked transitions is #842's, from the same typed
+  // events — never from the pane's output.
+  const reported = reportWorkerPaneState(paneId, label, "working", { run, session });
+  if (!reported.ok) {
+    return { kind: "unavailable", reason: reported.reason };
+  }
+  return { kind: "tracked", paneId, label, pid: identity.pid };
+}
+
+/** Report one lifecycle state for a tracked pane. Monotonic `seq` is the caller's. */
+export function reportWorkerPaneState(
+  paneId: string,
+  label: string,
+  state: "working" | "idle" | "blocked" | "unknown",
+  deps: { run?: HerdrRun; session?: string; seq?: number; message?: string } = {},
+): { ok: true } | { ok: false; reason: string } {
+  const run = deps.run ?? realHerdrRun;
+  const session = deps.session ?? resolveHerdrSession();
+  const res = run([
+    "--session",
+    session,
+    "pane",
+    "report-agent",
+    paneId,
+    "--source",
+    WORKER_PANE_SOURCE,
+    "--agent",
+    label,
+    "--state",
+    state,
+    ...(deps.seq === undefined ? [] : ["--seq", String(deps.seq)]),
+    ...(deps.message === undefined ? [] : ["--message", deps.message]),
+  ]);
+  return res.ok
+    ? { ok: true }
+    : { ok: false, reason: `herdr pane report-agent failed: ${firstLine(res.stderr) || "no output"}` };
+}
+
+/**
+ * Hand lifecycle authority back when the worker is gone.
+ *
+ * Release, never close: whether a settled worker's pane is closed, kept, or
+ * retained for N settlements is #841's documented policy, and a slice that
+ * closed panes here would decide it by accident. Releasing says only "conductor
+ * no longer speaks for this agent", which is exactly what is true.
+ */
+export function releaseWorkerPane(
+  paneId: string,
+  label: string,
+  deps: { run?: HerdrRun; session?: string; seq?: number } = {},
+): { ok: true } | { ok: false; reason: string } {
+  const run = deps.run ?? realHerdrRun;
+  const session = deps.session ?? resolveHerdrSession();
+  const res = run([
+    "--session",
+    session,
+    "pane",
+    "release-agent",
+    paneId,
+    "--source",
+    WORKER_PANE_SOURCE,
+    "--agent",
+    label,
+    ...(deps.seq === undefined ? [] : ["--seq", String(deps.seq)]),
+  ]);
+  return res.ok
+    ? { ok: true }
+    : { ok: false, reason: `herdr pane release-agent failed: ${firstLine(res.stderr) || "no output"}` };
+}
+
+/**
+ * Hand back the pane a dead worker left behind (#842).
+ *
+ * Called for every run a restart reaps. The recorded pid is deliberately NOT
+ * consulted for liveness: a `session-host` child dies with the daemon that owned
+ * its verb socket, so an orphaned row's worker is gone whatever pid it carries —
+ * and pids are reused, so checking one is how a stranger's process comes to read
+ * as a live worker. A run with no recorded pane is a no-op, not a failure: it
+ * never had one to release.
+ */
+export function releaseOrphanedWorkerPane(
+  run: { paneId?: string; paneLabel?: string },
+  deps: { run?: HerdrRun; session?: string; seq?: number } = {},
+): { kind: "none" } | { kind: "released"; paneId: string } | { kind: "failed"; paneId: string; reason: string } {
+  if (run.paneId === undefined || run.paneLabel === undefined) return { kind: "none" };
+  const released = releaseWorkerPane(run.paneId, run.paneLabel, deps);
+  return released.ok
+    ? { kind: "released", paneId: run.paneId }
+    : { kind: "failed", paneId: run.paneId, reason: released.reason };
+}
+
+/**
+ * Every conductor-owned pane Herdr currently has, keyed by the run id it was
+ * reported under (#841).
+ *
+ * Read from `pane list`'s own agent-session record, never from a label pattern:
+ * the label is what a human reads, and matching on it is exactly how a stale
+ * lookalike (a renamed pane, a pane from a previous fleet) gets mistaken for a
+ * live worker. `source` proves conductor reported it; `value` is the run id.
+ */
+export function listWorkerPanes(
+  deps: { run?: HerdrRun; session?: string } = {},
+): { ok: true; panes: { paneId: string; runId: string; label?: string }[] } | { ok: false; reason: string } {
+  const run = deps.run ?? realHerdrRun;
+  const session = deps.session ?? resolveHerdrSession();
+  const res = run(["--session", session, "pane", "list"]);
+  if (!res.ok) {
+    return { ok: false, reason: `herdr pane list failed: ${firstLine(res.stderr) || "no output"}` };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(res.stdout);
+  } catch (err) {
+    return { ok: false, reason: `herdr pane list was unreadable: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  const panes = (parsed as { result?: { panes?: unknown[] } }).result?.panes;
+  if (!Array.isArray(panes)) return { ok: false, reason: "herdr pane list carried no pane array" };
+  const owned: { paneId: string; runId: string; label?: string }[] = [];
+  for (const pane of panes) {
+    const p = pane as {
+      pane_id?: unknown;
+      agent?: unknown;
+      agent_session?: { source?: unknown; value?: unknown };
+    };
+    if (typeof p.pane_id !== "string") continue;
+    if (p.agent_session?.source !== WORKER_PANE_SOURCE) continue;
+    const runId = p.agent_session.value;
+    // Ours by source but carrying no run id: an identity nobody can resolve is
+    // not an identity. Reported as a pane with an empty run id so the caller
+    // treats it as stale rather than silently ignoring it.
+    owned.push({
+      paneId: p.pane_id,
+      runId: typeof runId === "string" ? runId : "",
+      ...(typeof p.agent === "string" ? { label: p.agent } : {}),
+    });
+  }
+  return { ok: true, panes: owned };
+}
+
+/** One live worker, as the reconciler needs to see it. */
+export interface LiveWorkerPane {
+  runId: string;
+  issue: number;
+  attempt: number;
+  project: string;
+  /** The recorded session-host pid; absent when nothing ever reported one. */
+  pid?: number;
+  paneId?: string;
+  paneLabel?: string;
+  sessionFile?: string;
+}
+
+export type WorkerPaneReconciliation =
+  /** The recorded pane is still there and still carries this run — nothing done. */
+  | { kind: "intact"; runId: string; paneId: string }
+  /** Herdr lost the pane (a restart); a new one now represents the same child. */
+  | { kind: "reassociated"; runId: string; paneId: string; label: string }
+  /** No representation, and the reason. The run keeps working regardless. */
+  | { kind: "untracked"; runId: string; reason: string }
+  /** A conductor pane whose run is not live: handed back to Herdr. */
+  | { kind: "stale-released"; paneId: string; runId: string }
+  | { kind: "stale-release-failed"; paneId: string; runId: string; reason: string };
+
+/**
+ * Make Herdr's conductor-owned panes agree with the live run set (#841).
+ *
+ * Idempotent by construction: a second pass over an already-reconciled fleet
+ * returns `intact` for every live run and finds no stale panes, so repeated
+ * daemon or Herdr restarts converge rather than accumulate.
+ *
+ * Three rules, and each exists to refuse a specific way this goes wrong:
+ *
+ * - **A live run's pane is re-created, never duplicated.** Re-association is
+ *   keyed on the run id Herdr itself reports, so a pane that is still there is
+ *   left alone. Only a run whose pane Herdr no longer has gets a new one.
+ * - **Cleanup is by exact identity, never by name or age.** A pane is stale only
+ *   when the run id it carries is absent from the live set. A worker's own pane
+ *   can therefore never be released while its run is live, whatever it is called
+ *   and however old it is.
+ * - **Nothing here can stop a worker.** The only mutation is `release-agent`,
+ *   which hands lifecycle authority back to Herdr; the authoritative child is
+ *   never signalled, and its pane is never closed.
+ */
+export function reconcileWorkerPanes(
+  live: readonly LiveWorkerPane[],
+  deps: WorkerPaneDeps = {},
+): { ok: true; outcomes: WorkerPaneReconciliation[] } | { ok: false; reason: string } {
+  const listed = listWorkerPanes(deps);
+  if (!listed.ok) return { ok: false, reason: listed.reason };
+  const byRun = new Map(listed.panes.map((pane) => [pane.runId, pane]));
+  const liveIds = new Set(live.map((worker) => worker.runId));
+  const outcomes: WorkerPaneReconciliation[] = [];
+
+  for (const worker of live) {
+    const held = byRun.get(worker.runId);
+    if (held !== undefined) {
+      outcomes.push({ kind: "intact", runId: worker.runId, paneId: held.paneId });
+      continue;
+    }
+    // Herdr does not have this run's pane. Only the pid makes a replacement
+    // honest: the pane represents an exact child, so without one there is
+    // nothing to represent and inventing a pane would be the silent claim this
+    // whole surface exists to avoid.
+    if (worker.pid === undefined) {
+      outcomes.push({
+        kind: "untracked",
+        runId: worker.runId,
+        reason: "no session-host pid was ever recorded for this run",
+      });
+      continue;
+    }
+    const opened = openWorkerPane(
+      {
+        project: worker.project,
+        issue: worker.issue,
+        attempt: worker.attempt,
+        runId: worker.runId,
+        pid: worker.pid,
+        ...(worker.sessionFile === undefined ? {} : { sessionFile: worker.sessionFile }),
+      },
+      deps,
+    );
+    outcomes.push(
+      opened.kind === "tracked"
+        ? { kind: "reassociated", runId: worker.runId, paneId: opened.paneId, label: opened.label }
+        : { kind: "untracked", runId: worker.runId, reason: opened.reason },
+    );
+  }
+
+  for (const pane of listed.panes) {
+    if (liveIds.has(pane.runId)) continue;
+    const released = releaseWorkerPane(pane.paneId, pane.label ?? "", deps);
+    outcomes.push(
+      released.ok
+        ? { kind: "stale-released", paneId: pane.paneId, runId: pane.runId }
+        : { kind: "stale-release-failed", paneId: pane.paneId, runId: pane.runId, reason: released.reason },
+    );
+  }
+  return { ok: true, outcomes };
+}
+
+function firstLine(text: string): string {
+  return text.split("\n", 1)[0]?.trim() ?? "";
+}
+
 /** The kill syscall, injectable so error mapping is testable without one. */
 export type KillFn = (pid: number, sig: NodeJS.Signals | 0) => void;
 
@@ -961,9 +1314,7 @@ export async function stopConductorPane(
 
 async function herdrAgentList(deps: PaneStopDeps): Promise<HerdrAgent[]> {
   const bin = deps.herdrBin ?? "herdr";
-  const session =
-    deps.herdrSession ??
-    resolveHerdrSessionWithBridge({ env: process.env, herdrBin: bin });
+  const session = deps.herdrSession ?? resolveHerdrSession(process.env);
   const res = spawnSync(bin, ["--session", session, "agent", "list"], {
     encoding: "utf8",
     timeout: 8_000,
@@ -1064,9 +1415,7 @@ export function parseHerdrProcessInfo(stdout: string, paneId: string): ProcessIn
 
 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 session = deps.herdrSession ?? resolveHerdrSession(process.env);
   const res = spawnSync(bin, ["--session", session, "pane", "process-info", "--pane", paneId], {
     encoding: "utf8",
     timeout: 8_000,
@@ -1642,13 +1991,22 @@ function briefStatusLine(project: ProjectConfig): string | undefined {
 }
 
 /**
- * Unrecovered runs grouped by failure class (#132), or nothing when there are
- * none.
+ * Failure classes, in two blocks that mean different things (#132).
  *
  * Reported as classes rather than as row states because a row state is not an
  * issue state: the FAILED column counted four completed issues on this fleet
- * while the genuinely stuck ones were invisible (#109). A class says which of
- * those it is, and `recoveredAt` is what keeps a recovered row out of the list.
+ * while the genuinely stuck ones were invisible (#109).
+ *
+ * That defect then reappeared one level up. A single "unrecovered" list keyed on
+ * `recoveredAt IS NULL` swept in the two recorded-only actions, which never
+ * stamp it — so this fleet's status read `returned-for-revision 44`, growing by
+ * one on every review return, while every class an operator could actually act
+ * on sat at zero and invisible beneath it. A count nobody can act on, printed
+ * where the actionable ones go, is the same lie in a new column.
+ *
+ * So: `awaiting recovery` is what the sweep will pick up, and it is omitted when
+ * empty because empty is the healthy answer. `classified, no action` is the
+ * signal — review returns and holds — named as such, never as a backlog.
  */
 function failureClassBlock(projectName: string): string | undefined {
   const path = dbPath();
@@ -1656,12 +2014,23 @@ function failureClassBlock(projectName: string): string | undefined {
   let store: Store | undefined;
   try {
     store = openStore(path);
-    const counts = store.failureClassCounts(projectName);
-    if (counts.length === 0) return undefined;
-    return [
-      "failure classes (unrecovered)",
-      ...counts.map((c) => `  ${c.cls.padEnd(18)}${c.n}`),
-    ].join("\n");
+    const awaiting = store.failureClassCounts(projectName);
+    const recorded = store.recordedOnlyClassCounts(projectName);
+    if (awaiting.length === 0 && recorded.length === 0) return undefined;
+    const lines: string[] = [];
+    if (awaiting.length > 0) {
+      lines.push(
+        "failure classes (awaiting recovery)",
+        ...awaiting.map((c) => `  ${c.cls.padEnd(24)}${c.n}`),
+      );
+    }
+    if (recorded.length > 0) {
+      lines.push(
+        "failure classes (classified, no action by design)",
+        ...recorded.map((c) => `  ${c.cls.padEnd(24)}${c.n}`),
+      );
+    }
+    return lines.join("\n");
   } catch {
     return undefined;
   } finally {
@@ -1901,6 +2270,23 @@ function makeChallengeCode(): string {
   return `FLEET-${hex}`;
 }
 
+/**
+ * mm:ss for a window whose whole length is five minutes. Deliberately not
+ * `formatDownDuration`, which rounds to whole minutes because it reports
+ * hours-to-days outages: rounded to the minute, the last 30 seconds of this
+ * window would read "5m of 5m left" while the wait was nearly over, which is
+ * the exact ambiguity the progress lines exist to remove (#861).
+ */
+function armClock(ms: number): string {
+  const total = Math.max(0, Math.round(ms / 1000));
+  const minutes = Math.floor(total / 60);
+  const seconds = total % 60;
+  return minutes === 0 ? `${seconds}s` : `${minutes}m${String(seconds).padStart(2, "0")}s`;
+}
+
+/** How often the wait says it is still waiting. Six lines across the window. */
+const ARM_PROGRESS_INTERVAL_MS = 30_000;
+
 /**
  * Polls the acknowledgement record for one exact challenge id until the
  * orchestrator's inbound adapter writes it or the deadline passes (#614).
@@ -1910,6 +2296,14 @@ function makeChallengeCode(): string {
  * 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.
+ *
+ * It also *says* it is waiting (#861). Measured 2026-08-21: an arm proof sat
+ * silent for five minutes and was reported as a hung setup — the process was
+ * healthy and the operator had no way to tell. A silent five-minute wait
+ * inside a fence that holds dispatch is indistinguishable from a dead one, so
+ * the elapsed/remaining line lands every {@link ARM_PROGRESS_INTERVAL_MS}
+ * regardless of the (much shorter) poll cadence, and the terminal outcome is
+ * always printed.
  */
 async function waitForArmAcknowledgement(
   challengeId: string,
@@ -1918,10 +2312,26 @@ async function waitForArmAcknowledgement(
 ): 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;
+  const report = deps.progress;
+  const startedAt = now();
+  const deadline = startedAt + timeoutMs;
+  let nextReportAt = startedAt + ARM_PROGRESS_INTERVAL_MS;
   for (;;) {
-    if (readArmAcknowledgement(challengeId) !== undefined) return true;
-    if (now() >= deadline) return false;
+    if (readArmAcknowledgement(challengeId) !== undefined) {
+      report?.(`arm: reply acknowledged after ${armClock(now() - startedAt)} — the fleet is armed.`);
+      return true;
+    }
+    const at = now();
+    if (at >= deadline) return false;
+    if (report !== undefined && at >= nextReportAt) {
+      report(
+        `arm: still waiting for the reply — ${armClock(at - startedAt)} elapsed, ` +
+          `${armClock(deadline - at)} left. Nothing is stuck: reply in the Telegram chat with the code.`,
+      );
+      // Anchored to the clock, not to this pass, so a slow pass cannot make the
+      // cadence drift into silence.
+      while (nextReportAt <= at) nextReportAt += ARM_PROGRESS_INTERVAL_MS;
+    }
     await sleep(5_000);
   }
 }
@@ -2057,7 +2467,7 @@ function probeOmpPane(
   }
   const agentName =
     tick.kind === "ok" ? (tick.config.agentName ?? DEFAULT_FLEET_AGENT_NAME) : DEFAULT_FLEET_AGENT_NAME;
-  const session = resolveHerdrSessionWithBridge({ env: process.env });
+  const session = resolveHerdrSession(process.env);
   try {
     const res = spawnSync("herdr", ["--session", session, "agent", "list"], {
       encoding: "utf8",