chainlesschain 0.162.162 → 0.162.164

package/src/lib/lsp/__tests__/lsp-manager.test.js

@@ -257,6 +257,64 @@ describe("crash-loop restart guard", () => {
     expect(lastClient).not.toBe(quarantined);
     await mgr.disposeAll();
   });
+
+  describe("exponential restart backoff (opt-in)", () => {
+    it("computes exponential backoff per crash, capped, and 0 when disabled", () => {
+      const on = new LSPManager({
+        restartBackoffBaseMs: 1000,
+        restartBackoffMaxMs: 8000,
+      });
+      expect(on._restartBackoffMs(0)).toBe(0); // first start — no wait
+      expect(on._restartBackoffMs(1)).toBe(1000);
+      expect(on._restartBackoffMs(2)).toBe(2000);
+      expect(on._restartBackoffMs(3)).toBe(4000);
+      expect(on._restartBackoffMs(4)).toBe(8000);
+      expect(on._restartBackoffMs(5)).toBe(8000); // capped
+      // Disabled by default → always 0 (byte-identical immediate respawn).
+      const off = new LSPManager();
+      expect(off.restartBackoffBaseMs).toBe(0);
+      expect(off._restartBackoffMs(2)).toBe(0);
+    });
+
+    it("degrades (backing off) during the cooldown, then re-spawns once it elapses", async () => {
+      let t = 1000;
+      const mgr = new LSPManager({
+        maxRestarts: 5,
+        restartWindowMs: 60000,
+        restartBackoffBaseMs: 1000,
+        restartBackoffMaxMs: 8000,
+        now: () => t,
+      });
+      await mgr.ensureFor("/proj/src/a.ts"); // spawn #1
+      const first = lastClient;
+      crash(first); // 1 crash at t=1000
+      // Same tick → within the 1st-crash backoff (1000ms) → degrade, no respawn.
+      const backingOff = await mgr.ensureFor("/proj/src/a.ts");
+      expect(backingOff.unavailable).toBe(true);
+      expect(backingOff.backoff).toBe(true);
+      expect(backingOff.quarantined).toBeUndefined();
+      expect(backingOff.retryInMs).toBe(1000);
+      expect(lastClient).toBe(first); // did NOT spawn during cooldown
+      // Advance past the cooldown → a fresh spawn is allowed.
+      t += 1000;
+      const ready = await mgr.ensureFor("/proj/src/a.ts");
+      expect(ready.unavailable).toBeUndefined();
+      expect(lastClient).not.toBe(first);
+      await mgr.disposeAll();
+    });
+
+    it("does NOT back off by default — respawns a crashed server on the next request", async () => {
+      const mgr = new LSPManager({ maxRestarts: 3, now: () => 5000 });
+      await mgr.ensureFor("/proj/src/a.ts");
+      const first = lastClient;
+      crash(first);
+      // Same tick, backoff disabled → immediate fresh spawn (prior behaviour).
+      const ready = await mgr.ensureFor("/proj/src/a.ts");
+      expect(ready.unavailable).toBeUndefined();
+      expect(lastClient).not.toBe(first);
+      await mgr.disposeAll();
+    });
+  });
 });
 
 describe("diagnostics", () => {

package/src/lib/lsp/lsp-manager.js

@@ -33,6 +33,14 @@ export class LSPManager {
    * @param {number} [opts.restartWindowMs] sliding window for the crash count.
    *   A server that stays healthy for this long has its crash history pruned and
    *   can restart fresh. Default 30000.
+   * @param {number} [opts.restartBackoffBaseMs] exponential backoff BETWEEN
+   *   restart attempts: after the Nth recent crash the (N+1)th re-spawn waits
+   *   `base·2^(N-1)` (capped by `restartBackoffMaxMs`) before it is allowed,
+   *   spreading out a fast startup-crash loop instead of bursting `maxRestarts`
+   *   spawns back-to-back. Default 0 = OFF (byte-identical to the prior
+   *   immediate-respawn behaviour); opt-in pending evaluation.
+   * @param {number} [opts.restartBackoffMaxMs] cap for the exponential backoff.
+   *   Default 8000.
    * @param {() => number} [opts.now] injected clock (deterministic crash-loop tests)
    */
   constructor(opts = {}) {
@@ -65,6 +73,19 @@ export class LSPManager {
     this.restartWindowMs = Number.isFinite(opts.restartWindowMs)
       ? opts.restartWindowMs
       : 30000;
+    // Exponential backoff BETWEEN restart attempts (distinct from the quarantine
+    // cap above). Without it, a server that crashes on startup is re-spawned on
+    // the very next request — bursting `maxRestarts` spawns back-to-back in
+    // milliseconds before quarantine. When enabled, the (N+1)th spawn after N
+    // recent crashes waits `base·2^(N-1)` (capped), so a fast crash loop can't
+    // storm the process table. Default 0 = OFF → byte-identical to the prior
+    // immediate-respawn behaviour (opt-in pending evaluation).
+    this.restartBackoffBaseMs = Number.isFinite(opts.restartBackoffBaseMs)
+      ? Math.max(0, opts.restartBackoffBaseMs)
+      : 0;
+    this.restartBackoffMaxMs = Number.isFinite(opts.restartBackoffMaxMs)
+      ? opts.restartBackoffMaxMs
+      : 8000;
     this._now = typeof opts.now === "function" ? opts.now : () => Date.now();
     /** key → array of recent crash timestamps (survives entry re-spawn) */
     this._crashLog = new Map();
@@ -80,6 +101,18 @@ export class LSPManager {
     return pruned;
   }
 
+  /**
+   * Minimum delay before the next restart attempt given `crashCount` recent
+   * crashes: exponential `base·2^(crashCount-1)`, capped at `restartBackoffMaxMs`.
+   * Returns 0 when backoff is disabled (base 0) or `crashCount <= 0` (a first
+   * start). Deterministic (no jitter) so crash-loop tests stay reproducible.
+   */
+  _restartBackoffMs(crashCount) {
+    if (this.restartBackoffBaseMs <= 0 || crashCount <= 0) return 0;
+    const exp = this.restartBackoffBaseMs * 2 ** (crashCount - 1);
+    return Math.min(exp, this.restartBackoffMaxMs);
+  }
+
   /**
    * Ensure a server is running for `filePath` and the file is open. Returns
    * `{ client, uri, languageId }`, or `{ unavailable: true, reason }` when no
@@ -125,6 +158,29 @@ export class LSPManager {
           quarantined: true,
         };
       }
+      // Under the quarantine cap but recently crashed: when backoff is enabled,
+      // space out the re-spawn exponentially so a fast startup-crash loop doesn't
+      // storm the process table. The caller degrades to text search until the
+      // cooldown elapses — a transient state, distinct from quarantine.
+      if (crashes.length > 0) {
+        const backoffMs = this._restartBackoffMs(crashes.length);
+        if (backoffMs > 0) {
+          const lastCrash = crashes[crashes.length - 1];
+          const sinceLast = this._now() - lastCrash;
+          if (sinceLast < backoffMs) {
+            const retryInMs = backoffMs - sinceLast;
+            return {
+              unavailable: true,
+              reason:
+                `${resolved.id} restarting after a crash — backing off ` +
+                `~${Math.max(0, Math.round(retryInMs / 1000))}s ` +
+                `(attempt ${crashes.length + 1}/${this.maxRestarts})`,
+              backoff: true,
+              retryInMs,
+            };
+          }
+        }
+      }
       entry = await this._getOrStartServer(key, resolved, projectRoot);
     }
 

package/src/lib/monitor-event.js

@@ -0,0 +1,290 @@
+/**
+ * Monitor event envelope + delivery guards (P1 daemon Event Runtime —
+ * CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12 §"守护进程事件运行时闭环").
+ *
+ * A Monitor watches a source (command stdout, file change, URL body, …) and
+ * "fires" when its condition matches. Before that firing reaches the agent as a
+ * turn it needs the same delivery guarantees Claude Code gives scheduled/event
+ * tasks:
+ *
+ *   - **event_id** — a *deterministic* identity (no RNG) derived from the
+ *     monitor id + the observation, so the same observation across a daemon
+ *     restart hashes to the same id and can be de-duplicated.
+ *   - **dedup window** — a time+count bounded set of recently-seen ids so a
+ *     monitor that matches every poll does not re-fire the identical event.
+ *   - **size cap** — oversized payloads are truncated (with a flag) so a
+ *     runaway command output cannot blow up a turn / the audit log.
+ *   - **backpressure** — a bounded queue that drops (and counts) events rather
+ *     than growing without limit when the agent is slower than the source.
+ *   - **authority** — a monitor event is an internal SYSTEM event: it tops out
+ *     at `steer` (agent-authority.js) and can NEVER answer a permission gate.
+ *
+ * Pure + dependency-light (node:crypto + agent-authority.js) so any monitor
+ * firing seam — daemon runtime, `cc agenda run`, a future in-process runtime —
+ * can share exactly one implementation of these invariants.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  ORIGIN,
+  authorityForOrigin,
+  canApprove,
+  describeAuthorityChain,
+} from "./agent-authority.js";
+
+/** Default per-event payload cap (64 KiB) — matches the schedule store's audit budget. */
+export const DEFAULT_MAX_EVENT_BYTES = 64 * 1024;
+
+/** Default dedup window: an id seen within 5 minutes (or the last 1000 ids) is a repeat. */
+export const DEFAULT_DEDUP_WINDOW_MS = 5 * 60 * 1000;
+export const DEFAULT_DEDUP_MAX_ENTRIES = 1000;
+
+/** Default bounded queue depth before backpressure drops kick in. */
+export const DEFAULT_QUEUE_MAX_SIZE = 256;
+
+/**
+ * A stable string form of an observation so structurally-equal observations
+ * hash identically and any real change hashes differently. Mirrors
+ * agent-authority's `normalizeToolArgs` intent (key-order independent).
+ */
+function stablePayload(payload) {
+  return stableStringify(payload === undefined ? null : payload);
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value === undefined ? null : value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const keys = Object.keys(value).sort();
+  return (
+    "{" +
+    keys
+      .map((k) => JSON.stringify(k) + ":" + stableStringify(value[k]))
+      .join(",") +
+    "}"
+  );
+}
+
+/**
+ * Deterministic event id for a monitor observation. Same `(monitorId, payload)`
+ * → same id, forever, with no RNG — so a daemon restart re-observing the same
+ * thing is recognised as a repeat instead of re-firing.
+ */
+export function monitorEventId(monitorId, payload) {
+  const h = createHash("sha256");
+  h.update("cc-monitor-event-v1\n");
+  h.update(String(monitorId ?? "") + "\n");
+  h.update(stablePayload(payload) + "\n");
+  return "ev_" + h.digest("hex").slice(0, 24);
+}
+
+/**
+ * Cap a payload's serialized size. Returns `{ value, truncated, bytes }`.
+ * Strings are truncated by UTF-8 byte length; non-strings are JSON-serialized,
+ * and if the JSON is over budget the *serialized string* is truncated and
+ * returned (so the event still carries a bounded, human-readable snippet rather
+ * than an unbounded object).
+ */
+export function capEventPayload(payload, maxBytes = DEFAULT_MAX_EVENT_BYTES) {
+  const limit = Math.max(0, Number(maxBytes) || 0);
+  const asString =
+    typeof payload === "string" ? payload : safeJsonStringify(payload);
+  const bytes = Buffer.byteLength(asString, "utf8");
+  if (limit === 0 || bytes <= limit) {
+    return { value: payload, truncated: false, bytes };
+  }
+  const truncated = truncateUtf8(asString, limit);
+  return {
+    value: truncated,
+    truncated: true,
+    bytes: Buffer.byteLength(truncated, "utf8"),
+  };
+}
+
+function safeJsonStringify(value) {
+  try {
+    return JSON.stringify(value === undefined ? null : value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Truncate a string to at most `maxBytes` UTF-8 bytes without splitting a code point. */
+function truncateUtf8(str, maxBytes) {
+  const buf = Buffer.from(str, "utf8");
+  if (buf.length <= maxBytes) return str;
+  let end = maxBytes;
+  // Back off if we would land in the middle of a multi-byte sequence.
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  return buf.toString("utf8", 0, end);
+}
+
+/**
+ * The unforgeable authority envelope for a monitor firing. A monitor event is
+ * an internal SYSTEM observation: it may add a turn (`steer`) but can NEVER
+ * answer a permission gate — matching the channel/hook ceiling. `origin` is set
+ * here by WHAT produced the event (a monitor), never read from its content.
+ *
+ * Returns `{ event_id, monitorId, origin, authority, canApprove, provenance,
+ * at, truncated?, source? }` — a caller merges its own observation fields in.
+ */
+export function monitorEventEnvelope(
+  monitorId,
+  payload,
+  { at = null, source = null, maxBytes = DEFAULT_MAX_EVENT_BYTES } = {},
+) {
+  const capped = capEventPayload(payload, maxBytes);
+  const envelope = {
+    origin: ORIGIN.SYSTEM,
+    principalId: monitorId != null ? String(monitorId) : null,
+    correlationId: source != null ? String(source) : null,
+  };
+  return {
+    event_id: monitorEventId(monitorId, payload),
+    monitorId: monitorId != null ? String(monitorId) : null,
+    source: source != null ? String(source) : null,
+    at: at != null ? Number(at) : null,
+    payload: capped.value,
+    truncated: capped.truncated,
+    origin: envelope.origin,
+    authority: authorityForOrigin(ORIGIN.SYSTEM, envelope), // always "steer"
+    canApprove: canApprove(envelope), // always false
+    provenance: describeAuthorityChain(envelope),
+  };
+}
+
+/**
+ * A time + count bounded set of recently-seen event ids. `shouldEmit(id, now)`
+ * records the id and returns `true` only when it is NOT a repeat within the
+ * window — so a monitor matching every poll fires the identical event once.
+ * Eviction is by age (older than `windowMs`) and by count (`maxEntries`, oldest
+ * first), both bounded so memory never grows without limit.
+ */
+export class DedupWindow {
+  constructor({
+    windowMs = DEFAULT_DEDUP_WINDOW_MS,
+    maxEntries = DEFAULT_DEDUP_MAX_ENTRIES,
+  } = {}) {
+    this._windowMs = Math.max(0, Number(windowMs) || 0);
+    this._maxEntries = Math.max(1, Number(maxEntries) || 1);
+    // Insertion-ordered id → lastSeen epoch-ms (Map preserves insertion order).
+    this._seen = new Map();
+  }
+
+  /**
+   * Drop entries older than the window relative to `now`. A full sweep (no
+   * early break): refreshing an id updates its timestamp but keeps its Map
+   * position, so timestamps are NOT monotonic in iteration order and an early
+   * break could skip a genuinely-expired later entry — which would then wrongly
+   * suppress its legitimate re-emit. The map is bounded by `maxEntries`, so a
+   * full pass is cheap and strictly correct.
+   */
+  _evictExpired(now) {
+    if (this._windowMs === 0) return;
+    const cutoff = now - this._windowMs;
+    for (const [id, ts] of this._seen) {
+      if (ts <= cutoff) this._seen.delete(id);
+    }
+  }
+
+  /** Enforce the count cap by evicting the oldest entries. */
+  _evictOverflow() {
+    while (this._seen.size > this._maxEntries) {
+      const oldest = this._seen.keys().next().value;
+      this._seen.delete(oldest);
+    }
+  }
+
+  /**
+   * True if `eventId` is new within the window (and records it); false if it is
+   * a repeat (refreshes its timestamp so a steady stream keeps it suppressed).
+   */
+  shouldEmit(eventId, now = 0) {
+    const nowMs = Number(now) || 0;
+    this._evictExpired(nowMs);
+    if (this._seen.has(eventId)) {
+      // Refresh recency without changing insertion order semantics for eviction.
+      this._seen.set(eventId, nowMs);
+      return false;
+    }
+    this._seen.set(eventId, nowMs);
+    this._evictOverflow();
+    return true;
+  }
+
+  /** Number of live (un-evicted) ids currently tracked. */
+  get size() {
+    return this._seen.size;
+  }
+
+  /** Forget everything (e.g. on monitor removal). */
+  clear() {
+    this._seen.clear();
+  }
+}
+
+/**
+ * A bounded event queue providing backpressure: once full, a `push` drops an
+ * event rather than growing the queue, and counts what it dropped so the loss
+ * is observable (and auditable) instead of silent.
+ *
+ *   - `dropPolicy: "oldest"` (default) — evict the head to admit the newcomer
+ *     (keep the freshest signal; good for state monitors).
+ *   - `dropPolicy: "newest"` — reject the newcomer (preserve order; good when
+ *     the first observations matter most).
+ */
+export class BoundedEventQueue {
+  constructor({
+    maxSize = DEFAULT_QUEUE_MAX_SIZE,
+    dropPolicy = "oldest",
+  } = {}) {
+    this._maxSize = Math.max(1, Number(maxSize) || 1);
+    this._dropPolicy = dropPolicy === "newest" ? "newest" : "oldest";
+    this._items = [];
+    this._dropped = 0;
+  }
+
+  /**
+   * Push an event. Returns `{ accepted, dropped }` where `dropped` is the event
+   * evicted/rejected to stay within bounds (or null when nothing was dropped).
+   */
+  push(event) {
+    if (this._items.length < this._maxSize) {
+      this._items.push(event);
+      return { accepted: true, dropped: null };
+    }
+    if (this._dropPolicy === "newest") {
+      this._dropped++;
+      return { accepted: false, dropped: event };
+    }
+    // oldest: evict head, admit newcomer.
+    const dropped = this._items.shift();
+    this._items.push(event);
+    this._dropped++;
+    return { accepted: true, dropped };
+  }
+
+  /** Remove and return the next event, or undefined when empty. */
+  shift() {
+    return this._items.shift();
+  }
+
+  /** Remove and return every queued event, oldest first. */
+  drain() {
+    const out = this._items;
+    this._items = [];
+    return out;
+  }
+
+  get size() {
+    return this._items.length;
+  }
+
+  /** Total events dropped due to backpressure since construction. */
+  get dropped() {
+    return this._dropped;
+  }
+}

package/src/lib/operation-fingerprint.js

@@ -93,3 +93,220 @@ export function approvalFingerprintOk(pending, resolved) {
   if (!pending) return true; // nothing to bind against (legacy pending ask)
   return fingerprintsMatch(pending, resolved);
 }
+
+// ── §8.2 cross-device operation fingerprint ──────────────────────────────────
+//
+// The fingerprint above binds tool + params only. IDE gap §8.2 requires a
+// CROSS-DEVICE identity that also covers target environment, workspace, session,
+// policy VERSION and a validity window, plus a fail-closed resolver: offline
+// replay, multi-card concurrency, timeout and duplicate submission must all be
+// rejected. The functions below add that richer tuple WITHOUT changing the
+// legacy fingerprint (existing devices/tests keep working).
+//
+// Two layers of identity:
+//   - the LOGICAL key  = tool + params + env + workspace + session + policyVersion
+//     (what the human is approving). Any change here invalidates an old approval.
+//   - the FINGERPRINT  = the logical key PLUS the validity window, so a card
+//     re-issued with a fresh window is a distinct fingerprint (an old card can
+//     never be replayed) while still mapping to the same logical operation.
+
+/**
+ * The logical-operation key preimage: everything the human is authorizing,
+ * EXCLUDING the validity window. Two asks with this equal are the same
+ * operation (so re-issuing one supersedes the other). Deterministic.
+ * @param {object} desc
+ */
+export function operationDescriptorKey(desc = {}) {
+  return canonicalize({
+    tool: desc.toolName ?? desc.tool ?? null,
+    params: desc.params !== undefined ? desc.params : (desc.detail ?? null),
+    targetEnv: desc.targetEnv ?? null,
+    workspace: desc.workspace ?? null,
+    session: desc.session ?? null,
+    policyVersion: desc.policyVersion ?? null,
+  });
+}
+
+function intOrNull(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * The full §8.2 cross-device fingerprint: the logical key plus the validity
+ * window `[notBefore, notAfter]`. Prefixed `opf_` (40 hex) so it is never
+ * confused with the 32-hex legacy fingerprint in a log or on the wire.
+ *
+ * @param {object} desc
+ * @param {string} [desc.toolName]
+ * @param {*}      [desc.params]
+ * @param {string} [desc.targetEnv]     e.g. local / wsl / ssh:host / container
+ * @param {string} [desc.workspace]
+ * @param {string} [desc.session]
+ * @param {string} [desc.policyVersion] a REAL policy version, not a rule label
+ * @param {number} [desc.notBefore]     ms epoch the approval becomes valid
+ * @param {number} [desc.notAfter]      ms epoch the approval expires
+ * @returns {string} `opf_` + 40 lowercase hex
+ */
+export function computeOperationFingerprint(desc = {}) {
+  const preimage =
+    "cc-operation-fingerprint-v2\n" +
+    operationDescriptorKey(desc) +
+    "\n" +
+    canonicalize({
+      notBefore: intOrNull(desc.notBefore),
+      notAfter: intOrNull(desc.notAfter),
+    });
+  return (
+    "opf_" +
+    createHash("sha256").update(preimage, "utf8").digest("hex").slice(0, 40)
+  );
+}
+
+/**
+ * A short, human-verifiable id for the approval card — the operator eyeballs it
+ * on the device against the terminal to confirm they answer the SAME card. Two
+ * groups of 4 uppercase hex from the fingerprint (never the secret params).
+ * @param {string} fingerprint
+ * @returns {string} e.g. "A1B2-C3D4"
+ */
+export function shortOperationId(fingerprint) {
+  const hex = String(fingerprint || "").replace(/^opf_/, "");
+  const s = (hex.slice(0, 8) || "00000000").toUpperCase();
+  return `${s.slice(0, 4)}-${s.slice(4, 8)}`;
+}
+
+/**
+ * A readable, SECRET-FREE one-line summary for the approval card. It NEVER
+ * echoes param VALUES (a shell command / token could be secret) — only the
+ * tool, the param key names (or an opaque marker), and the target coordinates.
+ * @param {object} desc
+ * @returns {string}
+ */
+export function summarizeOperation(desc = {}) {
+  const tool = String(desc.toolName ?? desc.tool ?? "operation");
+  let paramHint = "";
+  const p = desc.params;
+  if (p && typeof p === "object" && !Array.isArray(p)) {
+    const keys = Object.keys(p).sort();
+    paramHint = keys.length ? `(${keys.join(", ")})` : "()";
+  } else if (p !== undefined && p !== null && p !== "") {
+    paramHint = "(…)"; // opaque scalar/string/array — do not reveal the value
+  }
+  const coords = [];
+  if (desc.workspace) coords.push(`ws:${desc.workspace}`);
+  if (desc.targetEnv) coords.push(`env:${desc.targetEnv}`);
+  if (desc.session) coords.push(`sess:${desc.session}`);
+  if (desc.policyVersion) coords.push(`pol:${desc.policyVersion}`);
+  return `${tool}${paramHint}${coords.length ? " · " + coords.join(" · ") : ""}`;
+}
+
+/**
+ * Fail-closed verdict for resolving one pending approval. Every rejection is
+ * named so the audit log records WHY. Ordering matters: a missing input or a
+ * superseded/duplicate card is rejected before the fingerprint compare so a
+ * stale card can never settle a gate.
+ *
+ * @param {object} pending      {fingerprint, notBefore?, notAfter?, resolved?, supersededBy?}
+ * @param {object} resolution   {fingerprint}
+ * @param {object} [opts]
+ * @param {number} [opts.now]   ms epoch (injected clock; required for window checks)
+ * @returns {{ok:boolean, reason:(string|null)}}
+ */
+export function resolveOperationApproval(pending, resolution, opts = {}) {
+  if (!pending || typeof pending !== "object")
+    return { ok: false, reason: "no-pending" };
+  if (!resolution || typeof resolution !== "object")
+    return { ok: false, reason: "no-resolution" };
+  if (pending.resolved) return { ok: false, reason: "duplicate" };
+  if (pending.supersededBy != null) return { ok: false, reason: "superseded" };
+
+  if (!fingerprintsMatch(pending.fingerprint, resolution.fingerprint)) {
+    return { ok: false, reason: "fingerprint-mismatch" };
+  }
+
+  const now = intOrNull(opts.now);
+  const nb = intOrNull(pending.notBefore);
+  const na = intOrNull(pending.notAfter);
+  if (nb != null || na != null) {
+    if (now == null) return { ok: false, reason: "no-clock" }; // can't prove validity → closed
+    if (nb != null && now < nb) return { ok: false, reason: "not-yet-valid" };
+    if (na != null && now > na) return { ok: false, reason: "expired" };
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * In-memory registry that enforces the §8.2 cross-device guarantees for a set
+ * of live approval cards: single-winner across concurrent cards for one logical
+ * operation (multi-card), at-most-once (duplicate submission), and validity
+ * window (timeout / not-yet-valid). Pure aside from an injected `clock` — no
+ * fs/RNG — so it is fully unit-testable and serializable alongside a session.
+ */
+export class OperationApprovalRegistry {
+  constructor({ clock } = {}) {
+    this._byFingerprint = new Map(); // fingerprint -> pending record
+    this._activeByLogicalKey = new Map(); // logical key -> active fingerprint
+    this._clock = typeof clock === "function" ? clock : null;
+  }
+
+  _now() {
+    return this._clock ? intOrNull(this._clock()) : null;
+  }
+
+  /**
+   * Issue a card for an operation. Any still-unresolved card for the SAME
+   * logical operation is superseded (single-winner) so only this newest card
+   * can resolve.
+   * @returns {{fingerprint:string, shortId:string, summary:string}}
+   */
+  issue(desc = {}) {
+    const fingerprint = computeOperationFingerprint(desc);
+    const logicalKey = operationDescriptorKey(desc);
+
+    const priorFp = this._activeByLogicalKey.get(logicalKey);
+    if (priorFp && priorFp !== fingerprint) {
+      const prior = this._byFingerprint.get(priorFp);
+      if (prior && !prior.resolved) prior.supersededBy = fingerprint;
+    }
+
+    this._byFingerprint.set(fingerprint, {
+      fingerprint,
+      logicalKey,
+      notBefore: intOrNull(desc.notBefore),
+      notAfter: intOrNull(desc.notAfter),
+      resolved: false,
+      supersededBy: null,
+    });
+    this._activeByLogicalKey.set(logicalKey, fingerprint);
+
+    return {
+      fingerprint,
+      shortId: shortOperationId(fingerprint),
+      summary: summarizeOperation(desc),
+    };
+  }
+
+  /**
+   * Resolve a card by fingerprint. Fails closed (with a named reason) on an
+   * unknown, superseded, duplicate, mismatched, not-yet-valid or expired card.
+   * On success the card is marked resolved so a replay is a `duplicate`.
+   * @param {string} fingerprint
+   * @param {object} [opts]  {now?} overrides the injected clock
+   * @returns {{ok:boolean, reason:(string|null)}}
+   */
+  resolve(fingerprint, opts = {}) {
+    const pending = this._byFingerprint.get(fingerprint);
+    if (!pending) return { ok: false, reason: "unknown" };
+    const now = opts.now !== undefined ? intOrNull(opts.now) : this._now();
+    const verdict = resolveOperationApproval(pending, { fingerprint }, { now });
+    if (verdict.ok) pending.resolved = true;
+    return verdict;
+  }
+
+  /** A read-only view of a pending card (or null). */
+  get(fingerprint) {
+    const p = this._byFingerprint.get(fingerprint);
+    return p ? { ...p } : null;
+  }
+}