create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/bin/conversation-storage-auto-migration-lib.js

@@ -15,6 +15,9 @@ const {
   bindObservedDatabaseGenerations,
 } = require('./conversation-storage-generation-evidence');
 const { inspectCompletedMarker } = require('./conversation-storage-completed-marker');
+// WP-3 (clock-free r5 R-4..R-8): walle liveness from the write-lock identity record, the
+// proven-owned daemon stop before the first walle write, and a fail-closed foreign holder.
+const { ensureWalleOwnerStopped } = require('./conversation-storage-walle-owner');
 // No-op when options.profile is absent so behaviour is byte-identical to today: this
 // module only ever calls profile.measure/measureAsync around existing calls, never adds
 // new work, so an absent profile just means the timing calls disappear.
@@ -475,7 +478,13 @@ function runAutomaticConversationMigration(options = {}) {
       }
     }
     if (!state.irreversibleAt) {
-      profile.measure('assert_databases_offline', () => _assertDatabasesOffline(specs));
+      // R-5/R-8: stop this instance's PROVEN-OWNED Wall-E before the first walle write, and
+      // probe only the databases this run will mutate -- `specs` included a live walle in a
+      // CTM-only rerun, which blocked the boot on a database it was never going to touch.
+      const walleSpecForPreflight = specs.find((spec) => spec.id === 'walle');
+      const walleOwner = walleSpecForPreflight && plannedDatabaseIds.has('walle')
+        ? ensureWalleOwnerStopped(walleSpecForPreflight.path, options.walleOwner || {}) : null;
+      profile.measure('assert_databases_offline', () => _assertDatabasesOffline(plannedSpecs()));
       const headroomDatabaseIds = new Set(plannedDatabaseIds);
       if (headroomDatabaseIds.has('ctm') && specs.some((spec) => spec.id === 'walle')) {
         headroomDatabaseIds.add('walle');
@@ -486,6 +495,7 @@ function runAutomaticConversationMigration(options = {}) {
           options,
         )),
         databaseOwnership: 'offline',
+        ...(walleOwner ? { walleOwner } : {}),
       };
       checkpoint('preflight');
       checkpoint('inventory');
@@ -654,6 +664,11 @@ function runAutomaticConversationMigration(options = {}) {
           expandWalleDependency = true;
         } finally { ctmDb.close(); walleDb.close(); }
         if (expandWalleDependency) {
+          // R-5/R-8 (still inside the !state.irreversibleAt guard above): the expansion adds
+          // walle AFTER the preflight probe, so the owner must be proven stopped here too,
+          // before rebuild_walle -- and walle alone is re-probed.
+          state.preflight.walleOwner = ensureWalleOwnerStopped(walleSpec.path, options.walleOwner || {});
+          _assertDatabasesOffline([walleSpec]);
           plannedDatabaseIds.add('walle');
           delete state.cleanBackups.walle;
           state.restartPreflight.plannedDatabaseIds = specs

package/template/coding-task-manager/bin/conversation-storage-generation-evidence.js

@@ -5,6 +5,7 @@ const Database = require('better-sqlite3');
 const migration = require('../../scripts/conversation-storage-v2-migration');
 const {
   sanitizeInspectionViolations,
+  inspectionErrorClass,
 } = require('../../shared/conversation-storage-v2-contract');
 
 // Moved from conversation-storage-auto-migration-lib.js (WP-5 un-golf/split: keeping the
@@ -170,8 +171,14 @@ function inspectCompletedMarkerSpec(spec, expectedGeneration, generationEvidence
       violations,
       ...(generationChanged ? { generationChanged: true } : {}),
     };
-  } catch {
-    return { clean: false, reasonCodes: ['inspection_failed'], violations: [] };
+  } catch (error) {
+    // REPORT: an inspection that throws still plans a rerun (RERUN_CLASS, unchanged), but the
+    // boot log now names the error class instead of an empty violation list (clock-free r6 OQ-5).
+    return {
+      clean: false,
+      reasonCodes: ['inspection_failed'],
+      violations: [{ code: 'inspection_failed', objectId: inspectionErrorClass(error), count: 1 }],
+    };
   }
 }
 

package/template/coding-task-manager/bin/conversation-storage-service-entry-lib.js

@@ -12,6 +12,7 @@ const {
   buildConversationMigrationStatus,
 } = require('../lib/conversation-storage-migration-status');
 const { rebindCompletedGenerations } = require('./conversation-storage-generation-evidence');
+const { resolveInstanceTag } = require('../lib/instance-tag');
 const { createPhaseProfile } = require('../lib/phase-profile');
 const {
   sanitizeInspectionViolations,
@@ -102,7 +103,13 @@ function buildConversationStorageServiceLog(result = {}) {
     recoveryArtifactCount: status.recoveryArtifactCount,
     cleanupPendingCount: status.cleanupPendingCount,
   };
-  const restartPreflight = _restartPreflightForServiceLog(result.restartPreflight);
+  // R-6 (clock-free r4): restartPreflight describes a migration that was PLANNED by the
+  // boot that ran it. An already_complete / generation_rebound boot (result.skipped set)
+  // only re-reads the journal, so re-emitting the recorded object would print a stale
+  // re-run plan for a boot that ran no migration -- exactly what misled r3's census.
+  const restartPreflight = result.skipped == null
+    ? _restartPreflightForServiceLog(result.restartPreflight)
+    : null;
   if (restartPreflight) summary.restartPreflight = restartPreflight;
   return summary;
 }
@@ -129,6 +136,14 @@ function resolveAutomaticConversationMigrationOptions(env = process.env, homedir
     },
     batchLimit: Number(env.CTM_CONVERSATION_MIGRATION_BATCH_ROWS) || undefined,
     batchByteLimit: Number(env.CTM_CONVERSATION_MIGRATION_BATCH_BYTES) || undefined,
+    // WP-3 (clock-free r5 R-5/R-6): the kill authority the boot migration uses to prove and
+    // stop THIS instance's Wall-E before it touches wall-e-brain.db. Same tag derivation the
+    // supervisor uses (server.js:5897), so a dev/test instance can never signal the primary's
+    // daemon. Kept out of buildConversationStorageServiceLog, which never serializes options.
+    walleOwner: {
+      configDir: ctmDataDir,
+      instanceTag: resolveInstanceTag({ env, configDir: ctmDataDir, port: parseInt(env.CTM_PORT || '3456', 10) }),
+    },
   };
 }
 

package/template/coding-task-manager/bin/conversation-storage-walle-owner.js

@@ -0,0 +1,247 @@
+'use strict';
+
+// WP-3 / R-4..R-8 of docs/clock-free-tests-followups-r5-2026-10-25.html §5.
+//
+// Liveness for the boot migration's destructive walle re-run comes from Wall-E's own
+// write-lock identity record — `<db>.write-lock`, a 1,024-byte space-padded JSON
+// `{pid,...}` that PERSISTS after release (shared/sqlite-write-lock.js:1-40,250, D-3) —
+// not from a `BEGIN IMMEDIATE` probe. Probe P1 showed that an owner which is alive with an
+// idle connection (or no connection at all) passes the transaction probe, and the purge
+// then rewrites the database under it (the 2026-07-20 column-loss incident, r4 §1.1).
+//
+// The module is synchronous on purpose: bin/ctm-service-entry.js runs this migration
+// BEFORE it requires ../server, and the stop has to finish before the first walle write.
+//
+// R-6: nothing here is ever signalled on a name match. The one pid that may receive a
+// signal is the daemon pid read from `<configDir>/walle.pid`, and only after a single
+// `ps -p <pid>` row proves it is this instance's own Wall-E (lib/walle-kill-authority.js).
+// R-7: any other live write-lock holder stays fail-closed (`conversation_migration_database_busy`),
+// which the caller maps to exit 78 exactly as before.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { processTitleCandidates } = require('../lib/process-title');
+const { isOwnedRow } = require('../lib/walle-kill-authority');
+const { intFlag } = require('../lib/env-flags');
+
+const WALLE_PID_FILE = 'walle.pid';
+const WRITE_LOCK_SUFFIX = '.write-lock';
+const PS_TIMEOUT_MS = 5000;
+const PS_MAX_BUFFER = 1024 * 1024;
+// One SIGKILL grace window after the graceful budget is spent; a killed-but-unreaped
+// process is still a live pid until the kernel reaps it.
+const SIGKILL_GRACE_MS = 1000;
+// Same budget, default and clamp as lib/walle-supervisor.js:333,389 — a Wall-E that is
+// legitimately draining inside its own WALLE_SHUTDOWN_DEADLINE_MS gets to finish.
+const CHILD_EXIT_WAIT_ENV = 'WALLE_CHILD_EXIT_WAIT_MS';
+const DEFAULT_CHILD_EXIT_WAIT_MS = 16000;
+const MIN_CHILD_EXIT_WAIT_MS = 5000;
+const MAX_CHILD_EXIT_WAIT_MS = 120000;
+const DEFAULT_LOCK_RELEASE_WAIT_MS = 2000;
+const DEFAULT_POLL_MS = 100;
+
+function _childExitWaitMs() {
+  return Math.max(MIN_CHILD_EXIT_WAIT_MS, Math.min(MAX_CHILD_EXIT_WAIT_MS,
+    intFlag(CHILD_EXIT_WAIT_ENV, DEFAULT_CHILD_EXIT_WAIT_MS)));
+}
+
+// R-4: the owner identity, read off disk. null covers ENOENT (nothing ever wrote here),
+// EISDIR and a torn read of a v2 in-place write — every one of those means "no usable
+// identity", never "throw". Shape copied from shared/sqlite-write-lock.js:250 (_readIdentity)
+// and wall-e/bin/brain-purge-legacy-ctm.js:236-245 (liveReason's first check).
+function readWriteLockOwnerPid(dbPath) {
+  let record;
+  try {
+    record = JSON.parse(fs.readFileSync(`${dbPath}${WRITE_LOCK_SUFFIX}`, 'utf8'));
+  } catch {
+    /* expected: ENOENT (no writer yet), EISDIR (a directory sits at the path) and a torn
+       read of an in-place v2 write all mean "no identity readable right now". */
+    return null;
+  }
+  const pid = Number(record?.pid);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+// R-4: only ESRCH proves the pid is gone. EPERM means the pid EXISTS but is owned by
+// another user — kill(pid,0) probes existence, not killability — so every non-ESRCH
+// error fails toward "alive" (shared/sqlite-write-lock.js:231-245).
+function pidAlive(pid, kill = process.kill) {
+  const value = Number(pid);
+  if (!Number.isFinite(value) || value <= 0) return false;
+  try {
+    kill(value, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+// A pid that has exited but has not been REAPED is still a live pid for kill(pid,0): the
+// kernel keeps a zombie's pid until its parent waits. libuv only waits when the event loop
+// runs, and this migration blocks the loop for its whole duration (see the module comment:
+// it runs before ../server is required), so a daemon this process spawned -- ppid === myPid,
+// which lib/walle-kill-authority.js:17 explicitly accepts as owned -- stays kill(pid,0)-alive
+// forever after it has exited. Measured on this host: `kill(pid,0)` says alive while
+// `ps -o stat=` says "Z" for the whole blocked window, then the pid disappears once the loop
+// turns. A zombie has exited, so it must read as gone -- otherwise the SIGTERM we just sent
+// would be reported back to the caller as "a live holder that is not this instance's Wall-E".
+// Only consulted when kill(pid,0) already says alive, so the common reparented-to-launchd
+// daemon (ppid 1, reaped by init) never pays for it.
+function _isZombiePid(pid) {
+  try {
+    const stdout = execFileSync('ps', ['-p', String(pid), '-o', 'stat='], {
+      encoding: 'utf8',
+      timeout: PS_TIMEOUT_MS,
+      maxBuffer: 4096,
+    });
+    return String(stdout).trim().startsWith('Z');
+  } catch {
+    /* expected: ps exits non-zero when the pid has no row -- it is gone, or it was reaped
+       between the two probes. Either way there is no zombie to report. */
+    return false;
+  }
+}
+
+function _readWalleDaemonPid(configDir) {
+  if (!configDir) return null;
+  try {
+    const pid = Number.parseInt(fs.readFileSync(path.join(String(configDir), WALLE_PID_FILE), 'utf8').trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    /* expected: no pid file (Wall-E never started for this config dir) or an unreadable
+       one both mean "no daemon to stop" — R-7 still fails closed on the write-lock owner. */
+    return null;
+  }
+}
+
+// The same synchronous sleep idiom the write-lock module uses (shared/sqlite-write-lock.js:226-229).
+function sleepSync(ms) {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+
+let _parsePsWithPpid = null;
+
+// Rows for ONE pid, parsed by the supervisor's own parser so ownership sees an identical
+// row shape (lib/walle-supervisor.js:166-184,205-212). Loaded lazily: the migration runs
+// before ../server boots, and the ps path is only reached when a live owner record exists.
+function _psRow(pid) {
+  if (!_parsePsWithPpid) ({ parsePsWithPpid: _parsePsWithPpid } = require('../lib/walle-supervisor'));
+  try {
+    const stdout = execFileSync('ps', ['-p', String(pid), '-o', 'pid=,ppid=,command='], {
+      encoding: 'utf8',
+      timeout: PS_TIMEOUT_MS,
+      maxBuffer: PS_MAX_BUFFER,
+    });
+    return _parsePsWithPpid(stdout);
+  } catch (error) {
+    // A non-zero exit is ps answering "no such process" -> an empty row list.
+    // Anything else (ps un-runnable, timed out) is the probe itself failing -> null, which
+    // ownership must read as "not proven owned", never as "there is no process".
+    return Number.isInteger(error?.status) ? [] : null;
+  }
+}
+
+// R-4/R-5/R-7 liveness, one predicate: gone (ESRCH) or exited-and-not-yet-reaped (zombie).
+function _hasExited(pid, ops) {
+  return !pidAlive(pid, ops.kill) || ops.zombie(pid);
+}
+
+// Poll until the pid is gone, bounded by BOTH the deadline and an iteration cap: a caller
+// that injects a `now` which does not advance must not spin this loop forever.
+function _waitForExit(pid, timeoutMs, pollMs, ops) {
+  if (_hasExited(pid, ops)) return true;
+  const budget = Math.max(0, Number(timeoutMs) || 0);
+  const poll = Math.max(1, Number(pollMs) || DEFAULT_POLL_MS);
+  const deadline = ops.now() + budget;
+  const maxIterations = Math.ceil(budget / poll) + 1;
+  for (let index = 0; index < maxIterations; index += 1) {
+    if (ops.now() >= deadline) break;
+    ops.sleep(Math.max(1, Math.min(poll, deadline - ops.now())));
+    if (_hasExited(pid, ops)) return true;
+  }
+  return _hasExited(pid, ops);
+}
+
+// R-5/R-6/R-7. Returns { stopped, pid, waitedMs, signal }; throws
+// `conversation_migration_database_busy` when a live holder survives (R-7).
+function ensureWalleOwnerStopped(walleDbPath, options = {}) {
+  const injected = options.ops || {};
+  const ops = {
+    kill: typeof injected.kill === 'function' ? injected.kill : process.kill,
+    psRow: typeof injected.psRow === 'function' ? injected.psRow : _psRow,
+    sleep: typeof injected.sleep === 'function' ? injected.sleep : sleepSync,
+    now: typeof injected.now === 'function' ? injected.now : Date.now,
+    myPid: Number.isInteger(injected.myPid) ? injected.myPid : process.pid,
+    // A caller that injects its own process table owns liveness entirely -- probing the
+    // real ps for a fake pid would be meaningless (and would fork a process per poll). The
+    // real zombie probe is only armed on the real process.kill path.
+    zombie: typeof injected.zombie === 'function' ? injected.zombie
+      : (typeof injected.kill === 'function' ? () => false : _isZombiePid),
+  };
+  const instanceTag = options.instanceTag ? String(options.instanceTag) : null;
+  const childExitWaitMs = Number.isFinite(options.childExitWaitMs)
+    ? Math.max(0, Number(options.childExitWaitMs)) : _childExitWaitMs();
+  const lockReleaseWaitMs = Number.isFinite(options.lockReleaseWaitMs)
+    ? Math.max(0, Number(options.lockReleaseWaitMs)) : DEFAULT_LOCK_RELEASE_WAIT_MS;
+  const pollMs = Number.isFinite(options.pollMs) ? Math.max(1, Number(options.pollMs)) : DEFAULT_POLL_MS;
+  const startedAt = ops.now();
+
+  const ownerPid = readWriteLockOwnerPid(walleDbPath);
+  if (ownerPid === null || ownerPid === ops.myPid || _hasExited(ownerPid, ops)) {
+    // No usable record, our own pid, or a provably dead writer: nothing to stop, and no
+    // ownership probe is even attempted.
+    return { stopped: false, pid: null, waitedMs: 0, signal: null };
+  }
+
+  let daemonPid = null;
+  let signal = null;
+  if (options.configDir && instanceTag) {
+    const candidate = _readWalleDaemonPid(options.configDir);
+    if (candidate !== null && !_hasExited(candidate, ops)) daemonPid = candidate;
+  }
+  if (daemonPid !== null) {
+    const rows = ops.psRow(daemonPid);
+    const row = (Array.isArray(rows) ? rows : []).find((entry) => Number(entry?.pid) === daemonPid) || null;
+    const owned = isOwnedRow(row, {
+      titles: new Set(processTitleCandidates('walle', instanceTag)),
+      myPid: ops.myPid,
+    });
+    if (owned) {
+      ops.kill(daemonPid, 'SIGTERM');
+      signal = 'SIGTERM';
+      if (!_waitForExit(daemonPid, childExitWaitMs, pollMs, ops)) {
+        ops.kill(daemonPid, 'SIGKILL');
+        signal = 'SIGKILL';
+        _waitForExit(daemonPid, SIGKILL_GRACE_MS, pollMs, ops);
+      }
+    }
+  }
+  // The write-lock owner may be a different pid than the daemon (a worker, or a foreign
+  // process). It gets the same short grace — the lock is released by process exit — and
+  // then fails closed below. It is never signalled unless it IS the proven daemon pid.
+  if (!_hasExited(ownerPid, ops)) _waitForExit(ownerPid, lockReleaseWaitMs, pollMs, ops);
+
+  if (!_hasExited(ownerPid, ops)) {
+    const error = new Error(
+      `database is owned by a live process that is not this instance's Wall-E: walle pid=${ownerPid}`,
+    );
+    error.code = 'conversation_migration_database_busy';
+    error.database = 'walle';
+    error.ownerPid = ownerPid;
+    throw error;
+  }
+  return {
+    stopped: signal !== null,
+    pid: daemonPid,
+    waitedMs: Math.max(0, ops.now() - startedAt),
+    signal,
+  };
+}
+
+module.exports = {
+  ensureWalleOwnerStopped,
+  pidAlive,
+  readWriteLockOwnerPid,
+};

package/template/coding-task-manager/bin/ctm-machine-pair.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+'use strict';
+
+// WP-3 (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §6.3, §9 S-23): the pairing CLI.
+//
+//   ctm-machine-pair offer [--port <n>] [--json]
+//
+// Mints a pairing offer on the LOCAL CTM (`POST /api/machine-pairing/offers`) and prints the code,
+// the expiry and the whole `ctmpair1:` pairing string, so a terminal user can pair a machine without
+// opening the Machines page.
+//
+// IT NEVER PRINTS A TOKEN. The offer response carries a CODE (a single-use, TTL-bounded, 20^8-space
+// secret) and nothing else secret; the pool token only ever travels member -> box. The response body
+// is re-projected field by field rather than echoed, so a future response field can never leak
+// through this CLI by accident.
+//
+// AUTH. The route is admin + step-up remote (lib/auth-rules.js), and a LOOPBACK request is already
+// admin-scoped with no step-up (`hasScope`/`authorize`: loopback satisfies every scope and
+// `stepUp === 'remote'` is skipped for loopback), so no cookie, bearer or device token is needed —
+// this is the same posture every other loopback drivetool has. `--port` (or `CTM_PORT`, default
+// 3456) is the only knob; the request always goes to 127.0.0.1 so it can never mint an offer on a
+// remote machine.
+//
+// argv parsing only, no prompts: this is meant to be scriptable.
+
+const http = require('node:http');
+// CTM_PORT is read through lib/env-flags.js (the one truthiness/number parser) rather than
+// `process.env` directly: bin/flag-lint.js fails a new raw read of a CTM_* flag outside that module,
+// and CTM_PORT is a genuinely shared knob (bin/dev.sh, lib/hosted-primary-runtime.js).
+const { intFlag } = require('../lib/env-flags');
+
+const DEFAULT_PORT = 3456;
+
+function parseArgs(argv) {
+  const envPort = intFlag('CTM_PORT', DEFAULT_PORT);
+  const out = { command: '', port: envPort > 0 ? envPort : DEFAULT_PORT, json: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--port' || arg === '-p') {
+      const value = Number(argv[++i]);
+      if (Number.isInteger(value) && value > 0) out.port = value;
+    } else if (arg === '--json') {
+      out.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      out.help = true;
+    } else if (!out.command) {
+      out.command = arg;
+    }
+  }
+  return out;
+}
+
+function usage(out) {
+  out.write('usage: ctm-machine-pair offer [--port <n>] [--json]\n');
+  out.write('\n');
+  out.write('  offer      mint a pairing code on the local CTM and print it\n');
+  out.write('\n');
+  out.write('  --port <n> CTM port (default: CTM_PORT, else 3456)\n');
+  out.write('  --json     print the offer as JSON instead of a human report\n');
+}
+
+/**
+ * One loopback POST. `127.0.0.1` is hard-coded on purpose: a pairing offer must never be mintable on
+ * a machine other than the one this process is on.
+ */
+function postLoopback(port, pathname, body) {
+  return new Promise((resolve, reject) => {
+    const payload = Buffer.from(JSON.stringify(body || {}));
+    const req = http.request({
+      host: '127.0.0.1',
+      port,
+      path: pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': payload.length,
+        Accept: 'application/json',
+      },
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let parsed = null;
+        try {
+          parsed = raw ? JSON.parse(raw) : null;
+        } catch {
+          parsed = null; // expected: a non-JSON error page is reported by status alone
+        }
+        resolve({ status: Number(res.statusCode) || 0, body: parsed, raw });
+      });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+function formatExpiry(expiresAt) {
+  const at = Number(expiresAt);
+  if (!Number.isFinite(at) || at <= 0) return 'unknown';
+  const seconds = Math.max(0, Math.round((at - Date.now()) / 1000));
+  return `${new Date(at).toISOString()} (in ${seconds}s)`;
+}
+
+async function main(argv, io) {
+  const out = io.out;
+  const err = io.err;
+  const args = parseArgs(argv);
+  if (args.help || !args.command) {
+    usage(args.command ? out : err);
+    return args.command ? 0 : 2;
+  }
+  if (args.command !== 'offer') {
+    err.write(`ctm-machine-pair: unknown command '${args.command}'\n`);
+    usage(err);
+    return 2;
+  }
+  let res = null;
+  try {
+    res = await postLoopback(args.port, '/api/machine-pairing/offers', {});
+  } catch (error) {
+    err.write(`ctm-machine-pair: cannot reach CTM on 127.0.0.1:${args.port} — ${error && error.message ? error.message : error}\n`);
+    return 1;
+  }
+  if (res.status !== 201 || !res.body || res.body.ok !== true) {
+    const code = (res.body && (res.body.error || res.body.code)) || `http_${res.status}`;
+    err.write(`ctm-machine-pair: offer refused — ${code}\n`);
+    if (code === 'pool_member_exists') err.write('  this machine is already in a pool; leave it first\n');
+    if (code === 'pairing_offer_limit') err.write('  three offers are already live; wait for one to expire\n');
+    if (code === 'auth_rule_missing' || code === 'unauthorized') err.write(`  is CTM running on port ${args.port}?\n`);
+    return 1;
+  }
+  // Field-by-field projection: the response is NOT echoed, so a token added to it later cannot leak.
+  const offer = {
+    code: String(res.body.code || ''),
+    expiresAt: Number(res.body.expiresAt) || 0,
+    pairingString: String(res.body.pairingString || ''),
+    candidates: Array.isArray(res.body.candidates) ? res.body.candidates.map((url) => String(url || '')) : [],
+  };
+  if (args.json) {
+    out.write(`${JSON.stringify(offer, null, 2)}\n`);
+    return 0;
+  }
+  out.write(`Pairing code:   ${offer.code}\n`);
+  out.write(`Expires:        ${formatExpiry(offer.expiresAt)}\n`);
+  if (offer.candidates.length) out.write(`Reachable at:   ${offer.candidates.join(', ')}\n`);
+  out.write(`Pairing string: ${offer.pairingString}\n`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2), { out: process.stdout, err: process.stderr })
+    .then((code) => { process.exitCode = code; })
+    .catch((error) => {
+      process.stderr.write(`ctm-machine-pair: ${error && error.stack ? error.stack : error}\n`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { parseArgs, postLoopback, main };