omp-conductor 0.18.0 → 0.18.2

package/src/arm-challenge.ts

@@ -1,69 +1,154 @@
 /**
  * Authenticated pending-challenge state for the arming handshake (conductor
- * #415).
+ * #415, transaction reworked by #614, storage hardened by review of #896).
  *
  * `armTicks` (fleet.ts) sends a short-lived `FLEET-…` code to the operator and
- * proves the reply by scanning the orchestrator session transcript. That reply
- * also lands in the orchestrator as an ordinary user turn, where the model once
- * ad-libbed pairing-safety prose because it had no trusted way to recognise it.
+ * waits for the orchestrator to acknowledge it. The acknowledgement is
+ * conductor-owned state: the orchestrator's inbound user-turn adapter
+ * (orchestrator-tick.ts) writes it the moment the real reply arrives as a user
+ * turn — never the model, and never a transcript scan, so the proof no longer
+ * depends on where (or whether) a session file lives.
  *
  * This module is the bridge between the two roles without an import cycle:
  * `fleet.ts` imports `daemon.ts`, `daemon.ts` imports `orchestrator-tick.ts`,
  * so `orchestrator-tick.ts` can never import `fleet.ts`. Both already import
- * `config.ts`, so the pending-challenge record lives next to the other state
- * under `stateDir()` and both sides reach it through *this* leaf module.
+ * `config.ts`, so the state lives next to the other state under `stateDir()`
+ * and both sides reach it through *this* leaf module.
+ *
+ * The handshake keeps no shared mutable state at all — every file is named by
+ * its own key, and every deletion is id-addressed, so two processes can
+ * neither lose each other's updates nor delete each other's proofs:
+ *
+ * - `arm-challenges/<project key>.json` — one pending challenge per project:
+ *   `{ project, id, hash, sentAt, expiresAt }`. Host-owned: only `armTicks`
+ *   writes it (record before the send, settle on consumption/timeout/send
+ *   failure), always through the atomic tmp+rename write the admission ack
+ *   uses. A re-armed project overwrites its own file — pruning only its own
+ *   prior id's acknowledgement; a concurrent arm for a different project
+ *   touches a different file.
+ * - `arm-challenge-acks/<challenge id>.json` — one file per acknowledgement:
+ *   `{ challengeId, acknowledgedAt }`. The adapter's acknowledgement is a
+ *   single-file create/overwrite via rename — it never reads or rewrites
+ *   another transaction's record. Files that outlive their transaction (a
+ *   crash between the adapter's write and the host's settle) are inert by
+ *   construction and removed only by age, never by membership in any
+ *   directory snapshot (see {@link gcAgedAcks}).
  *
  * Only the sha-256 of the code is ever persisted — never the code, whose
  * plaintext appearance in the protected session transcript is already the
- * backend proof and must not leak into a durable report, an issue comment, or a
- * diagnostic line the way a new artifact could. The orchestrator classifies a
- * reply by hashing its tokens against this record, so nothing on the east side
- * of the boundary trusts a `FLEET-` prefix.
+ * backend proof and must not leak into a durable report, an issue comment, or
+ * a diagnostic line the way a new artifact could. The id is a random UUID cut
+ * with the challenge, so acknowledgement records are challenge-specific
+ * without carrying anything guessable. Neither side trusts a `FLEET-` prefix:
+ * a reply is classified by hashing its whitespace-separated tokens against
+ * the pending record, so nothing on the east side of the boundary can arm a
+ * fleet with a lookalike.
  */
 
-import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { stateDir } from "./config.ts";
 
-const ARM_CHALLENGE_FILE = "arm-challenge.json";
+const ARM_CHALLENGES_DIR = "arm-challenges";
+const ARM_ACKS_DIR = "arm-challenge-acks";
 
 interface PendingChallenge {
+  /** The project key this pending belongs to, mirrored for read-back checks. */
+  project: string;
+  /** Random transaction id, cut when this challenge was recorded. */
+  id: string;
   /** sha-256 hex of the challenge code — never the code itself. */
   hash: string;
+  /** Unix ms the challenge was recorded, just before the send. */
+  sentAt: number;
   /** Unix ms after which a matching reply is no longer an active proof. */
   expiresAt: number;
 }
 
-/** Keyed by project name; `""` is the pre-multi-project (un-named) spelling. */
-type PendingChallenges = Record<string, PendingChallenge>;
+interface ArmAcknowledgement {
+  /** The exact challenge id this record satisfies. */
+  challengeId: string;
+  /** Unix ms the inbound adapter acknowledged the reply. */
+  acknowledgedAt: number;
+}
+
+function challengesDir(): string {
+  return join(stateDir(), ARM_CHALLENGES_DIR);
+}
+
+function acksDir(): string {
+  return join(stateDir(), ARM_ACKS_DIR);
+}
 
-function challengesPath(): string {
-  return join(stateDir(), ARM_CHALLENGE_FILE);
+function ackPath(challengeId: string): string {
+  return join(acksDir(), `${challengeId}.json`);
 }
 
 function projectKey(project?: string): string {
   return project ?? "";
 }
 
-function readChallenges(): PendingChallenges {
+/**
+ * Filesystem-safe, injective encoding of a project key. Raw names that need
+ * no escaping are used verbatim; everything else (including the empty key of
+ * an unstamped config) becomes `=` plus hex bytes — `=` never appears in the
+ * raw class, so the two namespaces cannot collide.
+ */
+function encodeProjectKey(key: string): string {
+  if (/^[A-Za-z0-9._-]{1,64}$/.test(key) && key !== "." && key !== "..") return key;
+  return `=${[...Buffer.from(key, "utf8")].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function pendingPath(key: string): string {
+  return join(challengesDir(), `${encodeProjectKey(key)}.json`);
+}
+
+/**
+ * Atomic durable write, exactly like the admission ack: content lands at a
+ * unique temp path and is renamed into place, so every reader — including the
+ * one-shot inbound adapter racing the host — sees either the old file or the
+ * new one, never a mid-truncate parse.
+ */
+function writeFileAtomic(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`;
   try {
-    const parsed: unknown = JSON.parse(readFileSync(challengesPath(), "utf8"));
-    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed as PendingChallenges;
-    }
-  } catch {
-    /* absent or unreadable — no active challenge */
+    // 0600 like the other conductor state an operator never shares; the
+    // records are hashes and random ids, but there is no reason to be less
+    // careful.
+    writeFileSync(tmp, content, { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
   }
-  return {};
 }
 
-function writeChallenges(map: PendingChallenges): void {
-  const path = challengesPath();
-  mkdirSync(dirname(path), { recursive: true });
-  // 0600 like the other conductor state an operator never shares; the record is
-  // only a hash, but there is no reason to be less careful with it.
-  writeFileSync(path, `${JSON.stringify(map)}\n`, { mode: 0o600 });
+/**
+ * This project's pending challenge parsed from its own file, with every field
+ * validated. Anything absent, torn, garbage, pre-#614, or naming another
+ * project reads as none — fail closed until the host's next transaction
+ * rewrites the file wholesale.
+ */
+function readPendingFor(key: string): PendingChallenge | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(pendingPath(key), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const pending = parsed as Partial<PendingChallenge>;
+  if (
+    pending.project !== key ||
+    typeof pending.id !== "string" ||
+    typeof pending.hash !== "string" ||
+    typeof pending.expiresAt !== "number"
+  ) {
+    return undefined;
+  }
+  return pending as PendingChallenge;
 }
 
 /** sha-256 hex of the challenge code — the persisted token, never the code. */
@@ -71,42 +156,150 @@ function challengeHash(code: string): string {
   return createHash("sha256").update(code).digest("hex");
 }
 
-/** Register a new active arming challenge, replacing any prior one for the project. */
-export function recordArmChallenge(project: string | undefined, code: string, expiresAt: number): void {
-  const map = readChallenges();
-  map[projectKey(project)] = { hash: challengeHash(code), expiresAt };
-  writeChallenges(map);
+/**
+ * Acknowledgement files outliving their transaction — a crash between the
+ * adapter's write and the host's settle — are inert by construction: no
+ * waiter ever polls their id again, and ids are UUIDs, so no future
+ * transaction can collide with one. They are therefore not swept by
+ * membership (a directory listing captured before another process records is
+ * stale the moment it is taken, and acting on it deletes on-time proofs),
+ * only by age: a file older than {@link ACK_ORPHAN_GC_AFTER_MS} cannot belong
+ * to a live handshake under any configured window, so its mtime alone decides
+ * removal.
+ */
+const ACK_ORPHAN_GC_AFTER_MS = 24 * 60 * 60 * 1000;
+
+function gcAgedAcks(now: number): void {
+  let names: string[] = [];
+  try {
+    names = readdirSync(acksDir());
+  } catch {
+    return; /* no acknowledgements yet */
+  }
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const path = join(acksDir(), name);
+    try {
+      if (statSync(path).mtimeMs >= now - ACK_ORPHAN_GC_AFTER_MS) continue;
+    } catch {
+      continue; /* raced away */
+    }
+    rmSync(path, { force: true });
+  }
 }
 
-/** Drop the active challenge for a project once arming completed or timed out. */
-export function clearArmChallenge(project: string | undefined): void {
-  const map = readChallenges();
+/**
+ * Register a new active arming challenge for the project — overwriting the
+ * project's own pending file — and return the transaction id. Before the
+ * overwrite, the project's PRIOR id is read back and exactly that id's
+ * acknowledgement is pruned: project-local cleanup with no directory
+ * snapshot, so another project's handshake cannot lose its proof here no
+ * matter how the calls interleave.
+ */
+export function recordArmChallenge(
+  project: string | undefined,
+  code: string,
+  sentAt: number,
+  expiresAt: number,
+): string {
   const key = projectKey(project);
-  if (!(key in map)) return;
-  delete map[key];
-  writeChallenges(map);
+  // Read the prior record BEFORE the overwrite shadows it.
+  const prior = readPendingFor(key);
+  const id = randomUUID();
+  const record: PendingChallenge = { project: key, id, hash: challengeHash(code), sentAt, expiresAt };
+  writeFileAtomic(pendingPath(key), `${JSON.stringify(record)}\n`);
+  if (prior !== undefined) rmSync(ackPath(prior.id), { force: true });
+  gcAgedAcks(sentAt);
+  return id;
 }
 
 /**
- * Authenticated classification for the orchestrator's turn adapter: a reply is
- * an active arming proof iff the project has a non-expired pending challenge
- * and one of the reply's whitespace-separated tokens hashes to it. The code is
- * matched by hash — matching `transcriptHasUserCode`'s leniency (the code
- * appears as a token) without ever trusting a `FLEET-` prefix or exposing the
- * code to the model's other reads. An unsolicited lookalike that matches no
- * active challenge, and a reply in the wrong project, both stay inert.
+ * The inbound adapter's acknowledgement (conductor #614): classify the reply
+ * against the project's non-expired pending challenge and, on a match,
+ * atomically write the challenge-id-specific acknowledgement record the host
+ * waits on. Returns whether the reply is an active arming proof, driving the
+ * existing deterministic UX path.
  *
- * Clears nothing: the host (`armTicks`) owns clearance once its transcript
- * proof lands, so the two sides cannot race for the record.
+ * Writes only this challenge's own file — it never reads or rewrites any other
+ * record — so a wrong token, wrong project, expired challenge, or a racing
+ * host settle all fail closed without touching anyone else's handshake, and
+ * two projects acknowledging concurrently cannot clobber each other.
  */
-export function isActiveArmProof(project: string | undefined, replyText: string, now: number): boolean {
-  const pending = readChallenges()[projectKey(project)];
-  if (pending === undefined || now >= pending.expiresAt) return false;
-  const targetHash = pending.hash;
+export function acknowledgeArmReply(project: string | undefined, replyText: string, now: number): boolean {
+  const pending = readPendingFor(projectKey(project));
+  if (pending === undefined) return false;
+  if (now >= pending.expiresAt) return false;
   // Challenge codes contain no whitespace, so tokenising on whitespace never
   // splits one; empty replies simply yield no token.
+  const targetHash = pending.hash;
+  let matched = false;
   for (const token of replyText.trim().split(/\s+/)) {
-    if (token.length > 0 && challengeHash(token) === targetHash) return true;
+    if (token.length > 0 && challengeHash(token) === targetHash) {
+      matched = true;
+      break;
+    }
   }
-  return false;
+  if (!matched) return false;
+  // Keyed by the challenge id, so replays overwrite the one record the single
+  // live waiter consumes; a stale id's file can never be created here.
+  const record: ArmAcknowledgement = { challengeId: pending.id, acknowledgedAt: now };
+  writeFileAtomic(ackPath(pending.id), `${JSON.stringify(record)}\n`);
+  return true;
+}
+
+/** The acknowledgement record for one exact challenge id, or undefined. */
+export function readArmAcknowledgement(challengeId: string): ArmAcknowledgement | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(ackPath(challengeId), "utf8"));
+  } catch {
+    return undefined; /* absent, torn or garbage — not an acknowledgement */
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const ack = parsed as { challengeId?: unknown; acknowledgedAt?: unknown };
+  if (ack.challengeId !== challengeId || typeof ack.acknowledgedAt !== "number") return undefined;
+  return { challengeId, acknowledgedAt: ack.acknowledgedAt };
+}
+
+/**
+ * Settle one arm transaction — consumption, timeout, or send failure: remove
+ * the project's pending file iff it still names this transaction, and drop
+ * its acknowledgement. Deletion is id-addressed only, so another project's
+ * records are untouchable by construction, and a same-project replacement
+ * (different id) survives the stale settle.
+ */
+export function clearArmTransaction(project: string | undefined, challengeId: string): void {
+  const key = projectKey(project);
+  const pending = readPendingFor(key);
+  if (pending !== undefined && pending.id === challengeId) rmSync(pendingPath(key), { force: true });
+  rmSync(ackPath(challengeId), { force: true });
+}
+
+export interface ArmChallengeSighting {
+  /** The pending transaction's id — random, not the challenge code. */
+  id: string;
+  /** Unix ms the challenge was recorded, when the record carries it. */
+  sentAt?: number;
+  /** Unix ms the challenge expires, when the record carries it. */
+  expiresAt?: number;
+  /** Present once the inbound adapter acknowledged this challenge id. */
+  acknowledgedAt?: number;
+}
+
+/**
+ * Doctor's view of the project's open transaction, or undefined when none is
+ * recorded. An expired-but-uncleared record is reported, not hidden: it is
+ * inert (a reply past expiry is refused) but lingers until the project's next
+ * arm replaces it.
+ */
+export function observeArmChallenge(project: string | undefined): ArmChallengeSighting | undefined {
+  const pending = readPendingFor(projectKey(project));
+  if (pending === undefined || typeof pending.id !== "string") return undefined;
+  const ack = readArmAcknowledgement(pending.id);
+  return {
+    id: pending.id,
+    ...(typeof pending.sentAt === "number" ? { sentAt: pending.sentAt } : {}),
+    ...(typeof pending.expiresAt === "number" ? { expiresAt: pending.expiresAt } : {}),
+    ...(ack === undefined ? {} : { acknowledgedAt: ack.acknowledgedAt }),
+  };
 }