omp-conductor 0.19.7 → 0.20.1

package/src/fleet.ts

@@ -27,8 +27,10 @@ import { findProject, loadConfig, resolveArmProof, stateDir } from "./config.ts"
 import {
   clearArmTransaction,
   FLEET_ARM_KEY,
-  readArmAcknowledgement,
   recordArmChallenge,
+  resolveArmReply,
+  type ArmReplyVerdict,
+  type ArmTarget,
 } from "./arm-challenge.ts";
 import {
   claimedTelegramTopics,
@@ -101,6 +103,7 @@ import {
   resolveArmState,
   TICK_CONFIG_FILE,
   tickConfigMatchesProject,
+  writeArmedMarker,
   type ArmState,
   type TickConfig,
   type TickConfigResult,
@@ -283,19 +286,54 @@ export function disarmTicks(projectName?: string): { path: string; wasArmed: boo
   return { path, wasArmed };
 }
 
-export interface ArmResult {
-  path: string;
-  alreadyArmed: boolean;
-  owner: string;
-  /** The challenge code that proved arming, present only for `challenge` proof. */
-  challenge?: string;
+/** One project whose arm marker was written. */
+export interface ArmedProject {
   /**
-   * Which proof armed the fleet (#613): `challenge` for the authenticated
-   * round-trip, `claim-only` for the live-plumbing verdict with no send.
+   * The configured project name, absent only for a legacy unstamped
+   * single-project fleet.
    */
+  project?: string;
+  path: string;
+  alreadyArmed: boolean;
+}
+
+/** Markers written without any reply: the `claim-only` policy proof (#613). */
+export interface ArmMarkersWritten {
+  outcome: "armed";
   proof: ArmProof;
+  owner: string;
+  armed: ArmedProject[];
+}
+
+/**
+ * A challenge filed and sent, with nothing armed yet.
+ *
+ * Arming used to block here for up to five minutes on an in-session
+ * acknowledgement. Nothing waits now: the reply is consumed mechanically by
+ * the session whose topic the challenge went to (the orchestrator pane,
+ * #1061), or by `omp-conductor arm --reply` on a console host whose DM the
+ * operator answered in. This is the send half's receipt.
+ */
+export interface ArmChallengeSent {
+  outcome: "challenge-sent";
+  /** Always `challenge`: `claim-only` never sends, so it never reaches here. */
+  proof: "challenge";
+  /** The chat the challenge went to, recorded with the transaction. */
+  owner: string;
+  /** The pending transaction the reply must prove. */
+  challengeId: string;
+  /** Unix ms after which the code stops being a proof. */
+  expiresAt: number;
+  /** mm:ss the code stays good for — the same clock the message quotes. */
+  validFor: string;
+  /** Exactly what a matching reply will arm, as recorded with the challenge. */
+  targets: ArmTarget[];
+  /** The verbatim command that completes the ceremony, copy-pasteable as-is. */
+  followUp: string;
 }
 
+export type ArmResult = ArmMarkersWritten | ArmChallengeSent;
+
 export interface ArmDeps {
   sendChallenge?: (token: string, owner: string, text: string, topicId?: number) => Promise<void>;
   /**
@@ -307,7 +345,7 @@ export interface ArmDeps {
    */
   claimedSessionFile?: () => string | undefined;
   now?: () => number;
-  sleep?: (ms: number) => Promise<void>;
+  /** How long a sent code stays a proof. */
   timeoutMs?: number;
   /**
    * Liveness seams for the claim-only verdict (#613), with omp-telegram's own
@@ -321,11 +359,10 @@ export interface ArmDeps {
   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.
+   * Where the ceremony's one-line narration goes. Nothing waits any more, so
+   * this is no longer a liveness heartbeat (#861) — it is the send receipt and
+   * the follow-up instruction, for a surface that prints as it goes. Absent
+   * means no reporting.
    */
   progress?: (line: string) => void;
 }
@@ -367,30 +404,28 @@ 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.
+  // The handshake state key must be exactly what the reply step recomputes
+  // from this same tick config: 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, or the reply
+  // would look for the challenge under a key nothing recorded.
   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
+  // cannot name the project fails safe to `challenge` — the authenticated
   // round-trip — so a missing or unreadable config never silently weakens the
   // gate.
   let proof: ArmProof = DEFAULT_ARM_PROOF;
   try {
     proof = resolveArmProof(findProject(loadConfig(), named));
   } catch {
-    /* no project config — keep today's challenge behaviour */
+    /* no project config — keep the challenge behaviour */
   }
 
   // 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).
+  // challenge proof never reads it: its proof is conductor state, so where (or
+  // whether) a transcript lives is no longer part of arming (#614).
   const claimed =
     deps.claimedSessionFile !== undefined
       ? deps.claimedSessionFile()
@@ -409,17 +444,12 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
   }
 
   const path = tick.config.armedFile;
-  // The gate as the heartbeat reads it, so "replaced previous marker" is not a
-  // lie about a fleet the shared marker was arming, and so the write below knows
-  // whether it is superseding that marker.
-  const arm = resolveArmState(path, named);
-  const alreadyArmed = arm.armed;
 
   if (proof === "claim-only") {
     // The human-intent gate is declared satisfied by policy, so #612's shared
     // verdict is the whole proof: the same state reads and the same liveness
     // rules the doctor's "telegram-plumbing" finding applies, on the route a
-    // challenge would have ridden. No Telegram send, no transcript wait, no
+    // challenge would have ridden. No Telegram send, no reply step, no
     // pending-challenge record. A failed fact refuses arming by name — never
     // a silent pass from file existence, and never a marker.
     const scan = armVerdictScanDirs(tick.cwd, claimed);
@@ -442,13 +472,23 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
           `NOT armed; no marker was written`,
       );
     }
+    // The gate as the heartbeat reads it, so "replaced previous marker" is not
+    // a lie about a fleet the shared marker was arming, and so the write knows
+    // whether it is superseding that marker.
+    const arm = resolveArmState(path, named);
     writeArmedMarker(path, channel.owner, arm);
-    return { path, alreadyArmed, owner: channel.owner, proof };
+    return {
+      outcome: "armed",
+      proof,
+      owner: channel.owner,
+      armed: [{ ...(named === undefined ? {} : { project: named }), path, alreadyArmed: arm.armed }],
+    };
   }
 
   const send = deps.sendChallenge ?? sendTelegramMessage;
   const timeoutMs = deps.timeoutMs ?? ARM_CHALLENGE_TIMEOUT_MS;
   const code = makeChallengeCode();
+  const followUp = armReplyCommand(projectName);
   // Self-describing (#991): with two live challenges in one chat the operator
   // was working out which was which from message order, and nothing said how
   // long a code stayed good — so the safe move was to scroll for the newest,
@@ -457,15 +497,18 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
     `Fleet arming check${named === undefined ? "" : ` — project ${named}`}. ` +
     `Reply to this chat with exactly:\n${code}\n` +
     `Valid for ${armClock(timeoutMs)}. ` +
-    `Nothing will be dispatched until that reply is seen in the orchestrator session.`;
+    `Nothing is dispatched until that reply is verified.`;
   const sentAt = (deps.now ?? Date.now)();
-  // 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);
+  // Recorded BEFORE the send, so a reply that beats this process's own return
+  // still finds an active challenge — and so a send that fails has a
+  // transaction to settle rather than a code loose in a chat (#415). The record
+  // carries what the reply will arm: the config could change before the
+  // operator answers, and arming anything but what the challenge named would
+  // arm a fleet nobody was asked about.
+  const challengeId = recordArmChallenge(stateKey, code, sentAt, sentAt + timeoutMs, {
+    targets: [{ ...(named === undefined ? {} : { project: named }), armedFile: path }],
+    owner: channel.owner,
+  });
   try {
     await send(token, channel.owner, text, sendTopic);
   } catch (err) {
@@ -476,50 +519,33 @@ 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.`,
+      `valid for ${armClock(timeoutMs)}. Nothing is armed yet: run ${followUp}`,
   );
-
-  // 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 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` +
-        `  * did you reply in the DM with the bot, not another chat?\n`,
-    );
-  }
-
-  writeArmedMarker(path, channel.owner, arm);
-  // 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 };
+  return {
+    outcome: "challenge-sent",
+    proof: "challenge",
+    owner: channel.owner,
+    challengeId,
+    expiresAt: sentAt + timeoutMs,
+    validFor: armClock(timeoutMs),
+    targets: [{ ...(named === undefined ? {} : { project: named }), armedFile: path }],
+    followUp,
+  };
 }
 
-export interface FleetArmResult {
-  /** Every project this ceremony armed, in configuration order. */
-  armed: { project: string; path: string; alreadyArmed: boolean }[];
-  owner: string;
-  /** The transaction the single reply proved. */
-  challengeId: string;
+/**
+ * The second half of the ceremony, verbatim. Printed by every surface that
+ * issues a challenge, and quoted in the refusals, because an agent reading a
+ * console pane has to be able to paste it without composing anything: the
+ * operator's message is the only variable.
+ */
+function armReplyCommand(projectName?: string): string {
+  return (
+    `omp-conductor arm --reply "<the operator's reply, verbatim>"` +
+    `${projectName === undefined ? "" : ` --project ${projectName}`}`
+  );
 }
 
 /**
@@ -527,10 +553,9 @@ export interface FleetArmResult {
  *
  * Arming was per project: a two-project fleet meant two sequential handshakes
  * with two codes in one chat, though nothing about the fleet's state differed
- * between them. This sends **one** challenge and arms every configured project
- * from the single matching reply — which is a fleet-wide pending record, not a
- * loop that sends N challenges and waits for N replies. That loop is the
- * current friction with one command wrapped around it.
+ * between them. This sends **one** challenge whose single matching reply arms
+ * every configured project — one fleet-wide pending record, not a loop that
+ * sends N challenges and collects N replies.
  *
  * Every project is validated before anything is sent, so a fleet whose second
  * project has no `armedFile` refuses the ceremony instead of arming the first
@@ -541,11 +566,15 @@ export interface FleetArmResult {
  * authenticated round-trip is strictly stronger than the plumbing verdict that
  * policy would have accepted, so satisfying the weaker gate with the stronger
  * proof cannot weaken it.
+ *
+ * Like {@link armTicks}, this returns as soon as the challenge is filed and
+ * sent: the reply settles it mechanically on the orchestrator pane's own
+ * topic, or through `omp-conductor arm --reply` from the console.
  */
 export async function armFleet(
   projectNames: readonly string[],
   deps: ArmDeps = {},
-): Promise<FleetArmResult> {
+): Promise<ArmChallengeSent> {
   if (projectNames.length === 0) throw new Error("arm: no projects are configured");
 
   // Resolve and validate every project first. Nothing is sent and no marker is
@@ -596,8 +625,8 @@ export async function armFleet(
 
   // The first project that resolves a live topic carries the ceremony, and the
   // message says so: a fleet-wide question still has to land somewhere an
-  // operator is reading, and every session's adapter can acknowledge it because
-  // the pending record is fleet-wide rather than topic-scoped.
+  // operator is reading, and the reply step reaches the record from any project
+  // because it is fleet-wide rather than topic-scoped.
   let sendTopic: number | undefined;
   for (const target of targets) {
     try {
@@ -612,14 +641,28 @@ export async function armFleet(
   const timeoutMs = deps.timeoutMs ?? ARM_CHALLENGE_TIMEOUT_MS;
   const code = makeChallengeCode();
   const names = targets.map((t) => t.project).join(", ");
+  // No `--project`: the reply resolves the fleet record, which is the one this
+  // ceremony wrote. Naming a project here would be a narrower command than the
+  // challenge the operator answered.
+  const followUp = armReplyCommand();
   const text =
     `Fleet arming check — ${String(targets.length)} project(s): ${names}. ` +
     `Reply to this chat with exactly:\n${code}\n` +
     `Valid for ${armClock(timeoutMs)}, and one reply arms all of them. ` +
-    `Nothing will be dispatched until that reply is seen in the orchestrator session.`;
+    `Nothing is dispatched until that reply is verified.`;
 
   const sentAt = (deps.now ?? Date.now)();
-  const challengeId = recordArmChallenge(FLEET_ARM_KEY, code, sentAt, sentAt + timeoutMs);
+  // The record carries every project the message named, so the reply arms
+  // exactly the fleet the operator was asked about — not whatever the config
+  // says minutes later.
+  const armTargets: ArmTarget[] = targets.map((target) => ({
+    project: target.project,
+    armedFile: target.armedFile,
+  }));
+  const challengeId = recordArmChallenge(FLEET_ARM_KEY, code, sentAt, sentAt + timeoutMs, {
+    targets: armTargets,
+    owner: channel.owner,
+  });
   try {
     await send(token, channel.owner, text, sendTopic);
   } catch (err) {
@@ -630,31 +673,171 @@ export async function armFleet(
   }
   deps.progress?.(
     `arm: one challenge sent to ${channel.owner}${sendTopic === undefined ? "" : ` (topic ${sendTopic})`} for ${names} — ` +
-      `waiting up to ${armClock(timeoutMs)} for the reply. Dispatch stays held until it arrives.`,
+      `valid for ${armClock(timeoutMs)}. Nothing is armed yet: run ${followUp}`,
   );
+  return {
+    outcome: "challenge-sent",
+    proof: "challenge",
+    owner: channel.owner,
+    challengeId,
+    expiresAt: sentAt + timeoutMs,
+    validFor: armClock(timeoutMs),
+    targets: armTargets,
+    followUp,
+  };
+}
 
-  if (!(await waitForArmAcknowledgement(challengeId, timeoutMs, deps))) {
-    clearArmTransaction(FLEET_ARM_KEY, challengeId);
-    throw new Error(
-      `arm: the fleet challenge was never acknowledged in time — NOTHING armed.\n` +
-        `No acknowledgement for challenge ${challengeId} arrived, so no project's marker was written.\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` +
-        `  * did you reply in the chat the challenge names, not another one?\n`,
-    );
-  }
+/** What a reply that armed nothing was, and what to do about it. */
+export interface ArmReplyRefused {
+  outcome: "refused";
+  /** Never `matched`: a match is the armed outcome. */
+  verdict: Exclude<ArmReplyVerdict, "matched">;
+  /** One operator-facing sentence naming the verdict and the next move. */
+  message: string;
+}
+
+export interface ArmReplyAccepted {
+  outcome: "armed";
+  /** The chat the proved challenge was sent to — the marker's `owner=`. */
+  owner: string;
+  /** The transaction the reply proved and this call settled. */
+  challengeId: string;
+  /** Every project the challenge recorded, now armed. */
+  armed: ArmedProject[];
+}
+
+export type ArmReplyResult = ArmReplyAccepted | ArmReplyRefused;
 
-  // Proven once, applied to every project. Markers are written after the proof,
-  // so a refused ceremony leaves the fleet exactly as it was.
+/**
+ * The verification half of the ceremony: classify the operator's verbatim
+ * message and, on a match, arm exactly the projects the challenge recorded.
+ *
+ * This is the host CLI half, and it is one of two consumers of the same
+ * durable record: the orchestrator session's inbound path settles a reply
+ * sent to the project topic mechanically (#1061), while this command remains
+ * the console's route for a reply that landed in the operator DM. No session
+ * waits for anything: the challenge is durable state, so the halves are
+ * ordinary commands that can run minutes apart in different processes.
+ *
+ * The security properties are the send half's, unchanged. Only the project's
+ * own record and the fleet record are read (no other project's ceremony can be
+ * revealed or consumed), an expired record is never a proof, and a marker is
+ * written only for a `matched` verdict — every other verdict returns a refusal
+ * having written nothing.
+ */
+export function armReply(
+  replyText: string,
+  projectName?: string,
+  deps: Pick<ArmDeps, "now"> = {},
+): ArmReplyResult {
+  const tick = resolveTickConfig(projectName);
+  if (tick.kind === "invalid") {
+    // Every derivation below would come from this file. A config that does not
+    // parse cannot be trusted to name a state key or a marker.
+    throw new Error(`tick config invalid at ${tick.path}: ${tick.problem}`);
+  }
+  // An absent config is not fatal here, which is the difference between the two
+  // halves: a fleet ceremony's record carries its own targets, and on a
+  // multi-project host the search roots for an unnamed project resolve no
+  // config at all (the fleet cwds each carry their own). Refusing here would
+  // make `arm --reply` unusable for exactly the ceremony that needs it most.
+  const config = tick.kind === "ok" ? tick.config : undefined;
+  // The same derivation the send half used, from the same file: the state key
+  // is TickConfig.project (undefined for a legacy unstamped config), never the
+  // CLI argument, or the reply would look under a key nothing recorded.
+  const stateKey = config?.project;
+  const now = (deps.now ?? Date.now)();
+  const resolved = resolveArmReply(stateKey, replyText, now);
+  if (resolved.verdict !== "matched") {
+    return {
+      outcome: "refused",
+      verdict: resolved.verdict,
+      message: armRefusalText(resolved.verdict, projectName),
+    };
+  }
+  const match = resolved.match;
+  // Recorded targets are the contract. A record written before targets existed
+  // (one release of overlap) can only be read as naming the project it is keyed
+  // under — or, for the fleet record, the project this command was given, since
+  // re-deriving the fleet from today's config could arm a project the operator
+  // was never asked about.
+  const targets: ArmTarget[] = match.targets ?? [legacyArmTarget(config, projectName)];
+  // The owner the challenge was actually sent to. Only a pre-targets record
+  // lacks it, and then the paired channel is the only other honest source.
+  const owner = match.owner ?? pairedChannelOwner(config?.accessFile);
   const armed = targets.map((target) => {
     const state = resolveArmState(target.armedFile, target.project);
-    writeArmedMarker(target.armedFile, channel.owner, state);
-    return { project: target.project, path: target.armedFile, alreadyArmed: state.armed };
+    writeArmedMarker(target.armedFile, owner, state);
+    return {
+      ...(target.project === undefined ? {} : { project: target.project }),
+      path: target.armedFile,
+      alreadyArmed: state.armed,
+    };
   });
-  clearArmTransaction(FLEET_ARM_KEY, challengeId);
-  return { armed, owner: channel.owner, challengeId };
+  // Settled by id against the key that matched, so a replayed reply cannot arm
+  // a second time and a newer replacement's record is never removed.
+  clearArmTransaction(match.key, match.id);
+  return { outcome: "armed", owner, challengeId: match.id, armed };
+}
+
+/**
+ * What a pre-targets pending record arms. The tick config that resolved the
+ * state key also names this project's marker, which is exactly what the send
+ * half would have recorded. Without such a config there is nothing to fall back
+ * to, and guessing a marker path is not an option — a challenge from before the
+ * upgrade is simply re-run.
+ */
+function legacyArmTarget(config: TickConfig | undefined, projectName?: string): ArmTarget {
+  const named = config?.project ?? projectName;
+  if (config?.armedFile === undefined) {
+    throw new Error(
+      `arm: the pending challenge names no targets and no readable ${TICK_CONFIG_FILE} names an armedFile — ` +
+        `nothing to arm; re-run \`omp-conductor arm\` for a challenge that records its own targets`,
+    );
+  }
+  return { ...(named === undefined ? {} : { project: named }), armedFile: config.armedFile };
+}
+
+/** The paired owner, for the one record shape that does not carry its own. */
+function pairedChannelOwner(accessFile: string | undefined): string {
+  if (accessFile === undefined) {
+    throw new Error(`${TICK_CONFIG_FILE} has no accessFile — the challenge's owner cannot be established`);
+  }
+  const channel = readPairedChannel(accessFile);
+  if (channel.kind === "down") {
+    throw new Error(
+      `escalation channel is not up (${accessFile}): ${channel.reason} — ` +
+        `this challenge predates owner recording, so the marker cannot name whom it armed`,
+    );
+  }
+  return channel.owner;
+}
+
+/**
+ * Each non-matching verdict in the operator's words, with the next move. A
+ * silent no-op was the old failure mode: the operator could not tell a wrong
+ * code from an expired one from a command that never looked.
+ */
+function armRefusalText(verdict: Exclude<ArmReplyVerdict, "matched">, projectName?: string): string {
+  const reissue = `omp-conductor arm${projectName === undefined ? "" : ` --project ${projectName}`}`;
+  switch (verdict) {
+    case "expired":
+      return (
+        `arm: that code belongs to a challenge whose window has closed — NOT armed, no marker written. ` +
+        `An expired code is never a proof: send a fresh challenge with \`${reissue}\` and verify that one.`
+      );
+    case "unknown":
+      return (
+        `arm: that message carries an arming code, but no live challenge here matches it — NOT armed, ` +
+        `no marker written. Only this project's own challenge and the fleet ceremony are ever consulted. ` +
+        `Send a challenge with \`${reissue}\` and reply to that one.`
+      );
+    case "none":
+      return (
+        `arm: that message contains no arming code at all — NOT armed, no marker written. ` +
+        `Pass the operator's reply verbatim, including the FLEET-… code; if none was sent, run \`${reissue}\` first.`
+      );
+  }
 }
 
 export interface HoldResult {
@@ -3361,11 +3544,11 @@ function makeChallengeCode(): string {
 }
 
 /**
- * mm:ss for a window whose whole length is five minutes. Deliberately not
+ * mm:ss for the window a challenge code stays good for. 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).
+ * hours-to-days outages: rounded to the minute, a code with 30 seconds left
+ * would read "5m", which is the exact ambiguity these lines exist to remove
+ * (#861).
  */
 function armClock(ms: number): string {
   const total = Math.max(0, Math.round(ms / 1000));
@@ -3374,70 +3557,6 @@ function armClock(ms: number): string {
   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).
- *
- * 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.
- *
- * 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,
-  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 report = deps.progress;
-  const startedAt = now();
-  const deadline = startedAt + timeoutMs;
-  let nextReportAt = startedAt + ARM_PROGRESS_INTERVAL_MS;
-  for (;;) {
-    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);
-  }
-}
-
-/**
- * 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
- * honours — a project that just armed must not leave the bare marker around to
- * re-arm future fleets through `disarm` (#316).
- */
-function writeArmedMarker(path: string, owner: string, arm: ArmState): void {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `armed ${new Date().toISOString()} owner=${owner}\n`, { mode: 0o600 });
-  if (arm.legacy === "honoured") rmSync(legacyArmedMarkerPath(), { force: true });
-}
-
 /**
  * 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