create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/lib/lead-switch-history-mode.js

@@ -0,0 +1,110 @@
+'use strict';
+
+// WP-0/WP-1 (docs/lead-switch-never-prompted-session-2026-10-30.html §5 D-1..D-4, §6): ONE history
+// mode per transition — 'none' (this source lifetime has nothing to carry) or 'present' (today's
+// behaviour) — decided ONCE before the switch claims its transition, carried on both recipes, and
+// read back by every gate that used to re-derive (or silently assume) the answer.
+//
+// D-2, the rule that keeps this safe: 'none' is returned ONLY for a DEFINITE absence. The oracle is
+// the same off-thread resume ladder park already consults (lib/park-fresh-relaunch.js
+// `parkFindsNothingToResume`); a false answer, a thrown error, a timeout or an agent with no ladder
+// all mean 'present'. "An unreadable store is not evidence that the conversation is gone"
+// (superset-sh/superset#7144, adopted in §3 P-3), so a flaky ladder can only cost a refusal, never a
+// lost conversation. A recipe written before this change carries no `historyMode` key and reads as
+// 'present' — byte-for-byte today's path.
+
+const { extractResumeTarget } = require('./session-history');
+const { parkFindsNothingToResume } = require('./park-fresh-relaunch');
+
+const HISTORY_MODES = Object.freeze(['none', 'present']);
+// WP-2 D-6 (§5/§6): the only two spellings a source recipe's `modelOrigin` may carry.
+const MODEL_ORIGINS = Object.freeze(['observed', 'cli-default']);
+
+/**
+ * Resolve the SOURCE lifetime's history mode. NEVER throws (D-2): any error, rejection or timeout is
+ * 'present'.
+ *
+ * @param {object} input
+ * @param {'claude'|'codex'|string} input.agentType
+ * @param {string} input.ctmSessionId
+ * @param {string} input.jsonlPath        claude: the transcript path park would stat; codex: the rollout path or ''
+ * @param {string} [input.resumeId]       the source provider thread id
+ * @param {boolean} [input.resumeEvidence] true when park's own inputs already found a transcript/rollout ON DISK
+ * @param {(query: object) => Promise<{ rung?: string }>} input.resolveRung  resolveResumeRungOffThread bound to dbPath
+ * @returns {Promise<'none'|'present'>}
+ */
+async function resolveSourceHistoryMode({ agentType, ctmSessionId, jsonlPath, resumeId, resumeEvidence = false, resolveRung } = {}) {
+  try {
+    // A transcript/rollout file already on disk is proof there IS something to resume, so the ladder
+    // is never consulted for it (park short-circuits the same way, lib/park-fresh-relaunch.js).
+    if (resumeEvidence === true) return 'present';
+    const nothingToResume = await parkFindsNothingToResume({ agentType, ctmSessionId, jsonlPath, resumeId, resolveRung });
+    return nothingToResume === true ? 'none' : 'present';
+  } catch {
+    // HANDLE: D-2 — an unreadable store, a rejected ladder or a timeout is never evidence of absence,
+    // so the refusal side of every gate keeps today's behaviour.
+    return 'present';
+  }
+}
+
+/** Recipe read with the D-2 default: a missing or unknown key is 'present'. */
+function recipeHistoryMode(recipe) {
+  return recipe?.historyMode === 'none' ? 'none' : 'present';
+}
+
+/**
+ * WP-2 D-6 (§5/§6): WHERE the source lifetime's model came from — recorded, never guessed.
+ *
+ * 'cli-default' means this source never named a model of its own: the mode is 'none' (nothing was
+ * ever prompted) AND `cliDefaultModel` (captured by the runtime's `getSessionInfo`) proved an empty
+ * `session.model_id`, no `--model`/`-m`/`--model=` in the captured launch argv and no
+ * `session_lead_model` pin row. Rolling such a source back must relaunch the ORIGINAL argv and pass
+ * NO one-shot model override at all, so the CLI's own default applies by construction (D-6 rejected
+ * both substituting `cli_default` as `--model` and re-reading the CLI's config file).
+ *
+ * Everything else is 'observed' — today's meaning: the model was read from the session/argv, and a
+ * rollback passes it as the one-shot override exactly as before. A recipe written before this change
+ * carries no `cliDefaultModel`, so it reads 'observed'.
+ */
+function sourceModelOrigin(source) {
+  return recipeHistoryMode(source) === 'none' && source?.cliDefaultModel === true ? 'cli-default' : 'observed';
+}
+
+/** The value of a Claude argv's `--session-id <id>` / `--session-id=<id>`, or '' when absent. */
+function claudeSessionIdArg(args) {
+  const list = Array.isArray(args) ? args.map(String) : [];
+  for (let i = 0; i < list.length; i += 1) {
+    if (list[i] === '--session-id') return String(list[i + 1] || '');
+    if (list[i].startsWith('--session-id=')) return list[i].slice('--session-id='.length);
+  }
+  return '';
+}
+
+/**
+ * The single thread clause shared by the pre-park planner check (D-4) and authorizeLiveTargetRestore
+ * (D-3) — one definition, so the two gates can never drift apart (§7).
+ *
+ * For 'present' it is EXACTLY the historical conjunct: the plan must resume the target recipe's own
+ * provider thread. For 'none' the plan must carry no resume selector at all, and a Claude plan's own
+ * `--session-id` must name the target recipe's thread: that argv is what the fresh process is given,
+ * so it is the thread its canonical owner will report.
+ *
+ * @returns {boolean}
+ */
+function targetThreadClause({ source, target, launchPlan } = {}) {
+  const planThread = String(launchPlan?.resume?.sessionId || '');
+  const targetThread = String(target?.providerThreadId || '');
+  if (recipeHistoryMode(target) === 'present') return targetThread.length > 0 && planThread === targetThread;
+  // A 'none' target recipe is only meaningful with a 'none' SOURCE: the mode is one fact per
+  // transition, recorded twice.
+  if (recipeHistoryMode(source) !== 'none') return false;
+  if (planThread !== '') return false;
+  if (extractResumeTarget(launchPlan?.agentType, launchPlan?.args || [])) return false;
+  if (launchPlan?.agentType === 'claude') return targetThread.length > 0 && claudeSessionIdArg(launchPlan.args) === targetThread;
+  // codex: the new thread id is unknown until the thread links, so the owner check after launch
+  // binds it instead.
+  return true;
+}
+
+module.exports = { HISTORY_MODES, MODEL_ORIGINS, resolveSourceHistoryMode, recipeHistoryMode,
+  sourceModelOrigin, claudeSessionIdArg, targetThreadClause };

package/template/coding-task-manager/lib/lead-wire-agent.js

@@ -0,0 +1,7 @@
+'use strict';
+// The CLI wire a lead agent speaks to CTM's model proxy. OpenCode leads and OpenCode's routed
+// workers both use the Anthropic Messages face, so route servability is asked of 'claude'.
+// This is the ONE rule: public/js/session-model-picker.js mirrors it as `leadWireAgent` for the
+// Lead AND Delegate tabs, and tests pin the two bodies equal (docs/opencode-model-selection-round-2-shared-route-logic-2026-10-30.html §5 R-1, §6.1, §7).
+function leadWireAgent(agent) { return agent === 'opencode' ? 'claude' : agent; }
+module.exports = { leadWireAgent };

package/template/coding-task-manager/lib/legacy-draft-cancellation-recovery.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const path = require('node:path');
+const { createMediaJournalControlReader } = require('./media-journal-control-reader');
+
+function unavailable(cause) {
+  return Object.assign(new Error('Pending image cancellation recovery is unavailable', { cause }), {
+    code: 'CTM_MEDIA_JOURNAL_UNAVAILABLE',
+  });
+}
+
+// One recovery scope per logical DB handle and journal directory. No new SQL owner: the caller
+// supplies the same worker projector used by the write-behind store. Neither journal nor cursor
+// is advanced, because unrelated content must remain available to its ordinary replay owner.
+function createLegacyDraftCancellationRecovery({ getDirectory, getContext, projectEntry }) {
+  for (const callback of [getDirectory, getContext, projectEntry]) {
+    if (typeof callback !== 'function') throw new TypeError('Cancellation recovery requires callbacks');
+  }
+  let scope = null;
+  let operation = null;
+  let retired = false;
+  let closing = null;
+
+  function binding() {
+    const context = getContext();
+    const directory = getDirectory();
+    if (!context || !directory) throw new Error('Cancellation recovery has no open storage context');
+    return { context, directory: path.resolve(directory) };
+  }
+
+  function assertCurrent(owner) {
+    if (retired || owner !== scope) throw new Error('Cancellation recovery scope is retired');
+    const current = binding();
+    if (current.context !== owner.context || current.directory !== owner.directory) {
+      throw new Error('Cancellation recovery storage context changed');
+    }
+  }
+
+  async function closeReader(owner) {
+    if (!owner?.reader) return;
+    await owner.reader.close();
+    owner.reader = null; // Retain an unconfirmed resource owner on failure, not just its descriptor.
+  }
+
+  async function recover(current) {
+    await closeReader(scope);
+    const owner = scope = { ...current, reader: null, ready: false };
+    assertCurrent(owner);
+    const reader = owner.reader = createMediaJournalControlReader({
+      directory: owner.directory, assertCurrent: () => assertCurrent(owner),
+    });
+    let records;
+    let failed = false;
+    let failure;
+    try { records = await reader.read(); }
+    catch (error) { failed = true; failure = error; }
+    try { await closeReader(owner); }
+    catch (error) {
+      throw failed
+        ? new AggregateError([failure, error], 'Cancellation recovery and reader cleanup failed', { cause: failure })
+        : error;
+    }
+    if (failed) throw failure;
+    // Close every read handle BEFORE the first SQL projection. A partial projection remains
+    // idempotently retryable through applyMediaJournalEntry; it is never a completed recovery.
+    for (const { entry } of records) {
+      assertCurrent(owner);
+      const result = await projectEntry(entry, { urgent: true });
+      assertCurrent(owner);
+      if (typeof result?.cancelled !== 'boolean' || typeof result?.sessionEnded !== 'boolean'
+          || result.cancelled === result.sessionEnded) {
+        throw new TypeError('Cancellation projection did not confirm a durable cancellation or ended session');
+      }
+    }
+    assertCurrent(owner);
+    owner.ready = true;
+  }
+
+  function prepare() {
+    try {
+      if (retired) throw new Error('Cancellation recovery is closed');
+      const current = binding();
+      if (operation) return operation;
+      if (scope?.ready && scope.context === current.context && scope.directory === current.directory) {
+        return Promise.resolve();
+      }
+      operation = recover(current).catch(error => { throw unavailable(error); })
+        .finally(() => { operation = null; });
+      return operation;
+    } catch (error) {
+      return Promise.reject(unavailable(error));
+    }
+  }
+
+  function close() {
+    retired = true;
+    if (closing) return closing;
+    closing = (async () => {
+      // Already delivered operational errors are not shutdown failures. Unconfirmed handles
+      // remain owned and closeReader must still report them. No race against a timeout here.
+      if (operation) await operation.catch(() => { /* expected: admitted caller receives the failure */ });
+      await closeReader(scope);
+      scope = null;
+    })().finally(() => { closing = null; });
+    return closing;
+  }
+
+  return { prepare, close };
+}
+
+module.exports = { createLegacyDraftCancellationRecovery };

package/template/coding-task-manager/lib/lifecycle-wake-experiment.js

@@ -49,7 +49,13 @@ function readJsonFileSafe(filePath) {
 // that prompt entirely. Only a scope the USER wrote (top-level or `projects[cwd]` inside their
 // own ~/.claude.json) may ever supply a command here.
 function resolveCoreClaudeMcpServers(names, { homeDir = '', cwd = '' } = {}) {
-  const claudeJson = homeDir ? readJsonFileSafe(path.join(homeDir, '.claude.json')) : null;
+  return selectClaudeMcpServers(homeDir ? readJsonFileSafe(path.join(homeDir, '.claude.json')) : null, names, { cwd });
+}
+
+// The pure half of resolveCoreClaudeMcpServers, shared with the async DeepSeek Harness reader
+// (lib/session-create/dsh-session.js): the same two USER scopes, project scope winning. `names`
+// null selects every declared server (the 'full' profile, which dsh must materialize itself).
+function selectClaudeMcpServers(claudeJson, names, { cwd = '' } = {}) {
   const userScope = claudeJson && typeof claudeJson.mcpServers === 'object' && claudeJson.mcpServers ? claudeJson.mcpServers : {};
   const projectEntry = claudeJson && claudeJson.projects && typeof claudeJson.projects === 'object' && cwd
     ? claudeJson.projects[cwd]
@@ -57,7 +63,7 @@ function resolveCoreClaudeMcpServers(names, { homeDir = '', cwd = '' } = {}) {
   const projectScope = projectEntry && typeof projectEntry.mcpServers === 'object' && projectEntry.mcpServers ? projectEntry.mcpServers : {};
 
   const servers = {};
-  for (const name of names) {
+  for (const name of names || [...new Set([...Object.keys(userScope), ...Object.keys(projectScope)])]) {
     const def = projectScope[name] || userScope[name];
     if (def) servers[name] = def;
   }
@@ -200,6 +206,7 @@ module.exports = {
   codexMcpDisableArgs,
   resolveMcpProfile,
   normalizeMcpProfile,
+  selectClaudeMcpServers,
   MCP_PROFILES,
   MCP_PROFILE_FULL,
   MCP_PROFILE_NONE,

package/template/coding-task-manager/lib/live-defer-announce.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// WP-2 (live-defer-wake-adopted-host-death-2026-10-28.html §5 R-3/R-4/R-6/R-8): a LIVE defer
+// (the process died under an open tab) used to announce nothing to the attached clients -- only
+// `broadcastSessionList(true)`. The tab therefore kept its "current route proof" for the same
+// socket generation, so selecting it never sent a `terminal-bootstrap` and the server's deferred
+// wake never ran. The idle-park path already does it right (server.js park loop: iterate the
+// session's clients, readyState 1, sendDeferredRestoreStatus). These are the PURE helpers for
+// that announcement -- no server state, no requires, so both the adopted exit handler and the
+// session-create exit handler can share one implementation.
+
+// Which defer this exit is. WP-3a's dead-host path stamps `hostClosed: true` on the exit event it
+// synthesizes (lib/adopted-host-redial.js `_emitExitOnce`), so the evidence is the event itself --
+// never a process-liveness probe reconstructed at the defer site.
+function liveDeferSource(exitEvent) {
+  return exitEvent?.hostClosed === true ? 'host-death' : 'crash-defer';
+}
+
+// Announce the live defer to every client still attached. Returns the number of frames the caller's
+// `send` accepted; a client that has gone away (readyState !== 1) is skipped, and a `send` that
+// throws for one client must never stop the loop for the rest.
+function announceLiveDefer({ clients, send } = {}) {
+  const list = clients || [];
+  let sent = 0;
+  for (const ws of list) {
+    if (ws?.readyState !== 1) continue;
+    try {
+      send(ws);
+      sent += 1;
+    } catch { /* expected: client disconnected during lifecycle broadcast */ }
+  }
+  return sent;
+}
+
+// WP-3b (R-8): the evidence a host death carries on its exit event, normalized for the diagnostic
+// row. Booleans are strict, so an absent/undefined field reads as `false` -- never truthy garbage.
+function hostDeathEvidence(exitEvent) {
+  return {
+    reason: String(exitEvent?.reason || ''),
+    hostRetired: exitEvent?.hostRetired === true,
+    hostPidAliveAtDeclare: exitEvent?.hostPidAliveAtDeclare === true,
+  };
+}
+
+module.exports = { liveDeferSource, announceLiveDefer, hostDeathEvidence };

package/template/coding-task-manager/lib/login-tripwire.js

@@ -187,6 +187,7 @@ function armSessionLoginTripwire({ proc, env, onBlocked } = {}) {
 module.exports = {
   LOGIN_PATTERNS,
   WINDOW_CHARS,
+  stripAnsi,
   createLoginTripwire,
   attachToPty,
   armSessionLoginTripwire,

package/template/coding-task-manager/lib/machine-pairing.js

@@ -0,0 +1,238 @@
+'use strict';
+
+// WP-3 (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §6.3, D-6/D-9, §9 S-15/S-16/S-23):
+// the pairing code — the BOX side.
+//
+// A machine that wants to join a pool shows an 8-character code. The joining member posts the code
+// plus the pool token to the box's PRE-AUTH `POST /api/machine-pairing/join`; the box verifies the
+// code, burns it, and adopts the token. Rules that shape this module:
+//
+//   * §6.3 verbatim — alphabet, length, TTL, the 3-live-offer ceiling and the 5-wrong-redeem burn.
+//   * The code is a BEARER secret for one redemption. It is NEVER stored and NEVER logged: the only
+//     thing that reaches the database is `sha256(normalizeCode(code))` hex (D-6, §11 anti-goals).
+//   * `redeem` compares hashes with crypto.timingSafeEqual over EQUAL-LENGTH buffers — the digest is
+//     fixed-width, so a length mismatch is a malformed row, never a timing oracle.
+//   * Expired and already-used offers answer the SAME `pairing_code_invalid` code: a wrong code, a
+//     stale offer and a burned one must be indistinguishable to the caller, or the endpoint becomes
+//     an oracle for "was there ever an offer here".
+//
+// LEAF module: node built-ins only. Everything is injectable (`now`, `randomBytes`, `db`) so the
+// unit test never touches the real clock, the real CSPRNG or a real database (clock-free rule).
+
+const crypto = require('node:crypto');
+
+const CODE_ALPHABET = 'BCDFGHJKLMNPQRSTVWXZ'; // RFC 8628 §6.1 — no vowels, no 0/1/I/O look-alikes
+const CODE_LENGTH = 8;                        // shown (and typed) as XXXX-XXXX
+const OFFER_TTL_MS = 600_000;
+const MAX_LIVE_OFFERS = 3;
+const MAX_FAILED_REDEEMS = 5;
+
+// The container the box prints/paints once: `ctmpair1:` + base64url(JSON).
+const PAIRING_STRING_PREFIX = 'ctmpair1:';
+
+// |CODE_ALPHABET| = 20 and 256 is NOT a multiple of 20, so `byte % 20` would favour the first four
+// letters roughly 13% of the time. 240 = floor(256/20)*20 is the largest multiple of 20 that fits in
+// a byte: every byte >= 240 is discarded and re-drawn (RFC 8628 §6.1 rejection sampling).
+const REJECT_AT = Math.floor(256 / CODE_ALPHABET.length) * CODE_ALPHABET.length; // 240
+// A batch per draw, and a hard ceiling on batches so a broken/scripted `randomBytes` cannot spin
+// this loop forever — 32 batches of 16 bytes is a 1-in-10^22 tail, never a real event.
+const DRAW_BATCH = CODE_LENGTH * 2;
+const MAX_DRAW_BATCHES = 32;
+
+/**
+ * §6.3 verbatim: uppercase, then drop every character outside the alphabet. Hyphens and spaces are
+ * therefore formatting, not content — `wdjb-mjht`, `WDJB MJHT` and `WDJBMJHT` are one code.
+ */
+function normalizeCode(value) {
+  return String(value || '').toUpperCase().replace(/[^BCDFGHJKLMNPQRSTVWXZ]/g, '');
+}
+
+/** The display form the offer response carries: XXXX-XXXX (empty in => empty out). */
+function formatCode(value) {
+  const code = normalizeCode(value);
+  if (code.length !== CODE_LENGTH) return code;
+  return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+
+/** D-6: the ONLY representation of a code that is ever persisted. */
+function hashCode(value) {
+  return crypto.createHash('sha256').update(normalizeCode(value), 'utf8').digest('hex');
+}
+
+/**
+ * Constant-time hash compare over equal-length buffers. Two sha256 digests are always 64 chars, so
+ * a mismatch in length means a malformed stored row — false, never a throw and never a compare.
+ */
+function codeHashEquals(left, right) {
+  const a = Buffer.from(String(left == null ? '' : left), 'utf8');
+  const b = Buffer.from(String(right == null ? '' : right), 'utf8');
+  if (!a.length || a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+/** `XXXX-XXXX` -> a batch of random letters, rejection-sampled (no modulo bias). */
+function mintCode(randomBytes) {
+  const out = [];
+  for (let batch = 0; batch < MAX_DRAW_BATCHES && out.length < CODE_LENGTH; batch += 1) {
+    const bytes = randomBytes(DRAW_BATCH);
+    for (const byte of bytes) {
+      if (byte >= REJECT_AT) continue; // biased tail — re-draw, never fold
+      out.push(CODE_ALPHABET[byte % CODE_ALPHABET.length]);
+      if (out.length >= CODE_LENGTH) break;
+    }
+  }
+  if (out.length < CODE_LENGTH) throw new Error('machine-pairing: randomBytes did not yield an unbiased code');
+  return out.join('');
+}
+
+/**
+ * §6.3: `'ctmpair1:' + base64url(JSON{v:1,i:instanceId,n:displayName,u:candidates,c:code})`.
+ * `c` is the DISPLAY form (XXXX-XXXX); `normalizeCode` strips the hyphen on the way back in.
+ */
+function encodePairingString({ instanceId, displayName, urls, code } = {}) {
+  const payload = JSON.stringify({
+    v: 1,
+    i: String(instanceId || ''),
+    n: String(displayName || ''),
+    u: (Array.isArray(urls) ? urls : []).map((url) => String(url || '')).filter(Boolean),
+    c: String(code || ''),
+  });
+  return `${PAIRING_STRING_PREFIX}${Buffer.from(payload, 'utf8').toString('base64url')}`;
+}
+
+/**
+ * The member side of the container. Returns null for anything that is not a v1 pairing string —
+ * a hand-edited or truncated string is a 400 (`pairing_string_invalid`), never a throw.
+ */
+function decodePairingString(value) {
+  const raw = String(value == null ? '' : value).trim();
+  if (!raw.startsWith(PAIRING_STRING_PREFIX)) return null;
+  let parsed = null;
+  try {
+    parsed = JSON.parse(Buffer.from(raw.slice(PAIRING_STRING_PREFIX.length), 'base64url').toString('utf8'));
+  } catch {
+    return null; // expected: a corrupted container is a client error, not a server fault
+  }
+  if (!parsed || typeof parsed !== 'object' || parsed.v !== 1) return null;
+  const code = normalizeCode(parsed.c);
+  if (code.length !== CODE_LENGTH) return null;
+  const urls = (Array.isArray(parsed.u) ? parsed.u : [])
+    .map((url) => String(url || '').trim().replace(/\/+$/, ''))
+    .filter(Boolean);
+  const instanceId = String(parsed.i || '').trim();
+  if (!instanceId && !urls.length) return null;
+  return { version: 1, instanceId, displayName: String(parsed.n || ''), urls, code };
+}
+
+/**
+ * The box's pairing store.
+ *
+ * @param {{db: object, now?: () => number, randomBytes?: (n: number) => Buffer}} deps
+ *   `db` must expose the four DB-owner ops: listLivePairingOffers, insertPairingOffer,
+ *   markPairingOfferRedeemed, burnLivePairingOffers.
+ * @returns {{createOffer: () => Promise<object>, redeem: (code: string, options?: object) => Promise<object>,
+ *   hasLiveOffers: () => Promise<boolean>, burnAll: () => Promise<object>}}
+ */
+function createMachinePairing({ db, now = () => Date.now(), randomBytes = (n) => crypto.randomBytes(n) } = {}) {
+  if (!db || typeof db.listLivePairingOffers !== 'function') {
+    throw new TypeError('machine-pairing: db.listLivePairingOffers is required');
+  }
+  // §6.3: in memory on purpose — a restart clearing the counter is fine (the offers themselves are
+  // single-use and TTL-bounded), while persisting it would put an attacker-controlled number in the
+  // DB. Five CONSECUTIVE failures burn everything live; one success resets it.
+  let failedRedeems = 0;
+
+  function _now() {
+    return Math.trunc(Number(now()) || 0);
+  }
+
+  /**
+   * §6.3 `POST /api/machine-pairing/offers`. At most MAX_LIVE_OFFERS unspent offers exist at any
+   * moment, so a walked-away browser cannot leave an unbounded set of valid codes behind.
+   */
+  async function createOffer() {
+    const at = _now();
+    const live = await db.listLivePairingOffers({ at });
+    if (Array.isArray(live) && live.length >= MAX_LIVE_OFFERS) {
+      return { ok: false, code: 'pairing_offer_limit' };
+    }
+    const code = mintCode(randomBytes);
+    const expiresAt = at + OFFER_TTL_MS;
+    await db.insertPairingOffer({ id: crypto.randomUUID(), codeHash: hashCode(code), createdAt: at, expiresAt });
+    return { ok: true, code: formatCode(code), expiresAt };
+  }
+
+  /**
+   * §6.3 ordering: hash-compare against the live set, then burn the one that matched. `by` is the
+   * redeeming machine's instance id and is the only thing recorded — never the code.
+   *
+   * SINGLE USE IS THE UPDATE, NOT THE READ (F3). The candidate was found by reading the live set, but
+   * that read is not a claim: two joins holding the same code would both find the row and both return
+   * ok from a read-then-trust redeem. `markPairingOfferRedeemed` carries the `redeemed_at IS NULL`
+   * predicate in its WHERE clause and reports how many rows it changed, so exactly one of the two
+   * callers sees `changes === 1` and the loser is told `pairing_code_invalid` — the same answer an
+   * already-used code gets, which is what keeps the endpoint from being an oracle. A lost claim is NOT
+   * a failed guess (the caller was holding a real code), so it must not count toward the burn.
+   */
+  async function redeem(code, { by = '' } = {}) {
+    const at = _now();
+    const live = await db.listLivePairingOffers({ at });
+    const wanted = hashCode(code);
+    const offer = (Array.isArray(live) ? live : []).find((row) => codeHashEquals(row && row.codeHash, wanted));
+    if (!offer) {
+      failedRedeems += 1;
+      if (failedRedeems >= MAX_FAILED_REDEEMS) {
+        failedRedeems = 0;
+        // §6.3 AC-3c: the 5th consecutive miss burns EVERY live offer, so an attacker who is
+        // brute-forcing the 20^8 space loses the offers they were guessing against.
+        await db.burnLivePairingOffers({ at });
+      }
+      return { ok: false, code: 'pairing_code_invalid' };
+    }
+    const id = String(offer.id || '');
+    const changed = Number(await db.markPairingOfferRedeemed({
+      id,
+      at,
+      redeemedBy: String(by || '').slice(0, 200),
+    })) || 0;
+    if (changed !== 1) return { ok: false, code: 'pairing_code_invalid' };
+    // Only a claimed offer is a success, and only a success resets the consecutive-miss counter.
+    failedRedeems = 0;
+    return { ok: true, offer: { id, expiresAt: Number(offer.expiresAt) || 0 } };
+  }
+
+  /** §6.3/D-9: is this box showing a live code right now? (the identity probe's yes/no, never a code) */
+  async function hasLiveOffers() {
+    const live = await db.listLivePairingOffers({ at: _now() });
+    return Array.isArray(live) && live.length > 0;
+  }
+
+  /**
+   * F4: after a successful adopt this box belongs to somebody, so every OTHER live code must die —
+   * otherwise a second primary holding a code minted before the join could re-adopt the box and walk
+   * away with the pool secret. Also clears the failure counter: the box is no longer "unpaired".
+   */
+  async function burnAll() {
+    failedRedeems = 0;
+    return db.burnLivePairingOffers({ at: _now() });
+  }
+
+  return { createOffer, redeem, hasLiveOffers, burnAll };
+}
+
+module.exports = {
+  CODE_ALPHABET,
+  CODE_LENGTH,
+  OFFER_TTL_MS,
+  MAX_LIVE_OFFERS,
+  MAX_FAILED_REDEEMS,
+  PAIRING_STRING_PREFIX,
+  normalizeCode,
+  formatCode,
+  hashCode,
+  codeHashEquals,
+  mintCode,
+  encodePairingString,
+  decodePairingString,
+  createMachinePairing,
+};