@twinsearth/w2m-dsh-plugin 0.6.2 → 0.8.0

package/src/relay/state.mjs

@@ -1,2011 +1,2233 @@
-/**
- * W2M Rabbit relay — in-memory state machine.
- *
- * Contract: E:\DS\_work\w2m\PROTOCOL.md (protocol_version = 1, frozen).
- * This module is intentionally PURE LOGIC:
- *   - no network, no filesystem, no timers
- *   - time is injectable via `now()` (required for lease-expiry unit tests)
- *   - randomness is injectable for deterministic tests
- *
- * Persistence: none. All state is in-memory and is lost on restart (v0.0.1 scope);
- * there is intentionally no snapshot/serialization hook yet.
- */
-
-import { createHash, randomBytes } from 'node:crypto';
-
-export const PROTOCOL_VERSION = 1;
-
-/**
- * PROTOCOL §1 table + §7 code table, plus the two v0.1.2 additions:
- * `OPERATOR_REQUIRED` (§5.2 → 401) and `RATE_LIMITED` (§6 → 429).
- * A code missing from this map silently degrades to HTTP 500 via
- * `ProtocolError`, which keeps the right error code but lies about the status.
- */
-export const ERROR_STATUS = Object.freeze({
-  UNAUTHORIZED: 401,
-  BAD_REQUEST: 400,
-  NOT_FOUND: 404,
-  PAIRING_INVALID: 400,
-  PAIRING_EXPIRED: 400,
-  TASK_EXISTS: 409,
-  FRAME_TOO_LARGE: 413,
-  NO_ONLINE_DEVICE: 503,
-  INTERNAL: 500,
-  OPERATOR_REQUIRED: 401, // v0.1.2 §5.2
-  RATE_LIMITED: 429,      // v0.1.2 §6
-
-  /* v0.3.0 §9 request signing. Every client-side signature failure is a 401.
-   * `SIGNING_NOT_CONFIGURED` is deliberately NOT 401: the relay was started with
-   * `--require-signature` but no secret, so the fault is the relay's own
-   * configuration. Reporting that as 401 would send every operator to debug the
-   * client -- the one side that is not broken. 500 rather than 503 because
-   * retrying never fixes a missing configuration, so nothing should be invited to
-   * retry. */
-  SIGNATURE_REQUIRED: 401,
-  SIGNATURE_INCOMPLETE: 401,
-  SIGNATURE_MISMATCH: 401,
-  SIGNATURE_BAD_TIMESTAMP: 401,
-  SIGNATURE_BAD_NONCE: 401,
-  SIGNATURE_EXPIRED: 401,
-  SIGNATURE_REPLAY: 401,
-  SIGNING_NOT_CONFIGURED: 500,
-});
-
-/** §5.1 required envelope fields — missing any one means `unverifiable`. */
-export const REQUIRED_ENVELOPE_FIELDS = Object.freeze([
-  'envelope_version', 'task_id', 'attempt', 'dedupe_key', 'machine_id', 'machine_name',
-  'platform', 'caps', 'index', 'index_total', 'mode', 'cwd_rel', 'base_commit', 'base_tree',
-  'pre_tree_fingerprint', 'post_tree_fingerprint', 'fingerprint_algo', 'fingerprint_error',
-  'head_commit', 'dirty_before', 'command_argv', 'command_hash', 'shell_id',
-  'started_at', 'ended_at', 'duration_ms', 'exit_code', 'status', 'refusal_reason',
-  'stdout_sha256', 'stdout_bytes', 'stderr_sha256', 'stderr_bytes', 'warnings',
-  'envelope_sha256',
-]);
-
-/** §5.3 comparable fields — the ONLY fields that take part in consistency judgement. */
-export const COMPARABLE_FIELDS = Object.freeze([
-  'task_id', 'index', 'index_total', 'mode', 'cwd_rel', 'base_commit', 'base_tree',
-  'pre_tree_fingerprint', 'fingerprint_algo', 'fingerprint_error', 'head_commit',
-  'command_hash', 'shell_id', 'exit_code', 'status', 'refusal_reason',
-  'stdout_sha256', 'stdout_bytes', 'stdout_normalized_sha256',
-  'stderr_sha256', 'artifacts', 'diff_numstat', 'tests', 'semantic_counts', 'warnings',
-]);
-
-/** §5.1 status enum. */
-export const RESULT_STATUSES = Object.freeze([
-  'ok', 'nonzero_exit', 'timeout', 'crashed', 'refused', 'unverifiable',
-]);
-
-export const FAILURE_STATUSES = Object.freeze(['nonzero_exit', 'timeout', 'crashed']);
-
-/** §4.3 phase enum. */
-export const LEASE_PHASES = Object.freeze(['preparing', 'running', 'finalizing']);
-
-/** Lease states that can still be expired / renewed. */
-export const ACTIVE_LEASE_STATES = Object.freeze(['queued', 'offered', 'running']);
-
-export const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000; // §4.3: agent heartbeats every 10s
-export const DEFAULT_MISSED_HEARTBEATS = 2;          // §4.3: 2 missed cycles = 20s
-export const DEFAULT_LEASE_GRACE_MS = 30_000;        // §4.3: + grace 30s
-/**
- * v0.4.0: the bounded hold on the relay's own offer when a dispatcher is pushing it directly.
- *
- * Sized against what it has to cover: one punch round trip (measured 15-370 ms on the reference
- * networks), the frame's delivery, and the executor's first heartbeat POST — all on a host that may
- * be busy. 1.2 s was the first guess and it was too tight: measured on a 1-vCPU shared host, two
- * agent tests saw the relay's copy overtake the direct one, which for `p2pMode: direct` means a
- * refusal of an offer that was about to arrive. 3 s covers a slow host with room to spare.
- *
- * The cost is honest and bounded: a punch that fails delays the relay's copy by up to this much,
- * once per task. Nothing else waits on it.
- */
-export const DEFAULT_P2P_OFFER_GRACE_MS = 3_000;
-export const DEFAULT_PAIRING_TTL_MS = 24 * 60 * 60 * 1000; // §2.2: 24h
-export const DEFAULT_EVENT_BUFFER_SIZE = 1000;       // §requirement: keep last 1000 events
-export const MAX_FRAME_BYTES = 64 * 1024;            // 64 KiB single frame
-export const SHELL_ID_DIRECT = 'direct-exec';        // §5.1: v0.0.1 only direct exec
-/** v0.3.0: RTT sanity ceiling — anything above 24h is treated as a broken value. */
-export const MAX_RTT_MS = 24 * 60 * 60 * 1000;
-/** v0.3.0: an RTT measurement older than this is reported as stale.
- *  Must stay comfortably ABOVE the idle-heartbeat interval (60s): at 1x the value
- *  would flip stale just before every refresh and flap, which would make
- *  `rtt_stale === false` useless as a "trust this number" predicate. 3x gives two
- *  consecutive missed idle heartbeats of margin. See PROTOCOL-v0.3.0.md §7. */
-export const DEFAULT_RTT_STALE_MS = 180_000;
-/** v0.3.0: recommended cadence for an agent with no lease (reference for the agent side). */
-export const DEFAULT_IDLE_HEARTBEAT_MS = 60_000;
-export const ENVELOPE_VERSION = '1.0';
-export const FINGERPRINT_ALGO = 'git-temp-index-tree/v1';
-
-/* ------------------------------------------------------------------ */
-/* Errors                                                              */
-/* ------------------------------------------------------------------ */
-
-export class ProtocolError extends Error {
-  constructor(code, message, detail = {}) {
-    super(message);
-    this.name = 'ProtocolError';
-    this.code = code;
-    this.detail = detail;
-    this.status = ERROR_STATUS[code] ?? 500;
-  }
-  toBody() {
-    return { error: { code: this.code, message: this.message, detail: this.detail } };
-  }
-}
-
-/* ------------------------------------------------------------------ */
-/* Small pure helpers                                                  */
-/* ------------------------------------------------------------------ */
-
-export function sha256Hex(input) {
-  return createHash('sha256').update(input).digest('hex');
-}
-
-/** RFC 8785-ish canonical JSON (JCS): sorted keys, no whitespace. */
-export function jcs(value) {
-  if (value === null) return 'null';
-  const t = typeof value;
-  if (t === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
-  if (t === 'boolean') return value ? 'true' : 'false';
-  if (t === 'string') return JSON.stringify(value);
-  if (t === 'undefined' || t === 'function' || t === 'symbol') return 'null';
-  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined ? 'null' : jcs(v))).join(',')}]`;
-  if (t === 'object') {
-    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
-    return `{${keys.map((k) => `${JSON.stringify(k)}:${jcs(value[k])}`).join(',')}}`;
-  }
-  return JSON.stringify(String(value));
-}
-
-/**
- * Upper bound on the stages a `pipeline` may contain.
- *
- * Each stage is another command run on someone else's machine, so an unbounded list is an unbounded
- * amount of work created by one request. The limit is generous for the intended use (build, test,
- * package) and exists so the failure is a clear refusal rather than a fleet-wide surprise.
- */
-export const MAX_PIPELINE_STAGES = 16;
-
-/**
- * v0.4.0: upper bound on `POST /v1/task`'s `origin_machine_id`.
- *
- * A machine id is an identifier, not a payload: 128 characters is far beyond any id this system
- * mints, and the ceiling is what stops the field from becoming an unbounded free-text channel into
- * every offer frame the relay emits.
- */
-export const MAX_ORIGIN_MACHINE_ID_LENGTH = 128;
-
-/**
- * v0.4.0: the P2P modes a task may be dispatched under (§1 of the frozen v0.4.0 contract).
- *
- * Mirrored here rather than imported from `src/agent/p2p-node.mjs`: the relay is a standalone
- * process that must not depend on agent code, and a mode list is three strings. A value outside
- * this list is a configuration error, never a silent fall back to the default.
- */
-export const P2P_MODES = Object.freeze(['auto', 'direct', 'relay']);
-
-/**
- * v0.4.0: how a result travelled — the direct P2P channel or the relay.
- *
- * A **transport is not a result**: how an envelope arrived must never take part in the consistency
- * judgement (§5 of the contract), or two machines that produced byte-identical output would be
- * reported `divergent` merely because one of them punched a hole. Hence: not required, not
- * comparable, and absent on every v0.3.9 envelope.
- */
-export const TRANSPORT_VALUES = Object.freeze(['p2p', 'relay']);
-
-/** §4.4 helper: command_hash = sha256(JCS(argv)+"|"+shell_id+"|"+cwd_rel). */
-export function computeCommandHash(commandArgv, shellId = SHELL_ID_DIRECT, cwdRel = '.') {
-  return sha256Hex(`${jcs(commandArgv)}|${shellId}|${cwdRel}`);
-}
-
-/**
- * `command_hash` for a whole pipeline.
- *
- * The hash must bind **every** stage, not just the first. Bound to stage 0 alone, two pipelines that
- * differ after the first stage would carry the same hash -- so an envelope produced by the wrong
- * chain would still verify, and making "the machine ran what I asked" checkable is the entire point
- * of this field. Each stage's cwd participates for the same reason.
- *
- * The `|pipeline` suffix means this can never collide with a single-command hash: the two hash over
- * different shapes, and that difference is deliberate rather than incidental.
- */
-export function computePipelineCommandHash(stages, shellId = SHELL_ID_DIRECT) {
-  const canonical = stages.map((s) => ({
-    command_argv: s.command_argv,
-    cwd_rel: s.cwd_rel ?? '.',
-    continue_on_failure: s.continue_on_failure === true,
-  }));
-  return sha256Hex(`${jcs(canonical)}|${shellId}|pipeline`);
-}
-
-/** §4.4: dedupe_key = sha256(task_id + "|" + index + "|" + command_hash + "|" + base_tree). */
-export function computeDedupeKey(taskId, index, commandHash, baseTree) {
-  return sha256Hex(`${taskId}|${index}|${commandHash}|${baseTree}`);
-}
-
-/** Epoch ms -> RFC3339 UTC, second precision (matches the PROTOCOL examples). */
-export function rfc3339(ms) {
-  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
-}
-
-export function isRfc3339(value) {
-  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(value);
-}
-
-export function deepEqual(a, b) {
-  return jcs(a === undefined ? null : a) === jcs(b === undefined ? null : b);
-}
-
-function normalizeNow(now) {
-  if (typeof now !== 'function') return () => Date.now();
-  return () => {
-    const v = now();
-    if (typeof v === 'number') return v;
-    if (v instanceof Date) return v.getTime();
-    return Date.parse(v);
-  };
-}
-
-/* ------------------------------------------------------------------ */
-/* ULID                                                                */
-/* ------------------------------------------------------------------ */
-
-const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
-
-function encodeBig(value, len) {
-  let out = '';
-  let v = value;
-  for (let i = 0; i < len; i += 1) {
-    out = CROCKFORD[Number(v & 31n)] + out;
-    v >>= 5n;
-  }
-  return out;
-}
-
-export function createIdFactory() {
-  let lastMs = -1;
-  let lastRand = 0n;
-  return function nextId(nowMs = Date.now()) {
-    const bytes = randomBytes(10);
-    let rand = 0n;
-    for (const b of bytes) rand = (rand << 8n) | BigInt(b);
-    if (nowMs === lastMs) rand = (lastRand + 1n) & ((1n << 80n) - 1n);
-    lastMs = nowMs;
-    lastRand = rand;
-    return encodeBig(BigInt(nowMs), 10) + encodeBig(rand, 16);
-  };
-}
-
-export function ulid(nowMs = Date.now()) {
-  return createIdFactory()(nowMs);
-}
-
-/* ------------------------------------------------------------------ */
-/* Version / capability gate (§6.1)                                    */
-/* ------------------------------------------------------------------ */
-
-function parseVersion(text) {
-  if (typeof text !== 'string') return null;
-  const m = text.trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.(\d+))?/);
-  if (!m) return null;
-  return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0), Number(m[4] ?? 0)];
-}
-
-function cmpVersion(a, b) {
-  for (let i = 0; i < 4; i += 1) {
-    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
-  }
-  return 0;
-}
-
-/**
- * Minimal semver-range check used by the §6.1 capability gate.
- * Supports bare versions and comma/space separated `>= > <= < = ==` conjunctions.
- * Unparseable ranges are treated as NOT satisfied (never silently pass).
- */
-export function satisfiesRange(version, range) {
-  const v = parseVersion(version);
-  if (v === null) return false;
-  if (typeof range !== 'string') return false;
-  const parts = range.split(/[\s,]+/).filter(Boolean);
-  if (parts.length === 0) return false;
-  for (const part of parts) {
-    const m = part.match(/^(>=|<=|==|=|>|<)?\s*(.+)$/);
-    if (!m) return false;
-    const op = m[1] ?? '=';
-    const target = parseVersion(m[2]);
-    if (target === null) return false;
-    const c = cmpVersion(v, target);
-    if (op === '>=' && c < 0) return false;
-    if (op === '<=' && c > 0) return false;
-    if (op === '>' && c <= 0) return false;
-    if (op === '<' && c >= 0) return false;
-    if ((op === '=' || op === '==') && c !== 0) return false;
-  }
-  return true;
-}
-
-function machineWritable(caps) {
-  if (!caps || typeof caps !== 'object') return false;
-  if (caps.write === false || caps.writable === false || caps.write_allowed === false) return false;
-  if (caps.read_only === true || caps.readonly === true || caps.ro_mount === true) return false;
-  return true;
-}
-
-/**
- * §6.1 capability gate, evaluated per machine BEFORE dispatch.
- * @returns {null | {status:'refused', refusal_reason:string, detail:object}}
- */
-export function gateMachine(task, machine) {
-  const caps = machine?.caps ?? {};
-  const req = task.requirements ?? {};
-
-  if (req.platform && Array.isArray(req.platform) && req.platform.length > 0) {
-    const os = String(machine?.platform?.os ?? '').toLowerCase();
-    if (!req.platform.map((p) => String(p).toLowerCase()).includes(os)) {
-      return { status: 'refused', refusal_reason: 'PLATFORM_MISMATCH', detail: { os, want: req.platform } };
-    }
-  }
-
-  const toolchain = req.toolchain ?? {};
-  for (const [tool, range] of Object.entries(toolchain)) {
-    const declared = caps[tool];
-    if (declared === null || declared === undefined || declared === '') {
-      return {
-        status: 'refused',
-        refusal_reason: `MISSING_${String(tool).toUpperCase()}`,
-        detail: { tool, want: range, have: declared ?? null },
-      };
-    }
-    if (typeof range === 'string' && !satisfiesRange(declared, range)) {
-      return {
-        status: 'refused',
-        refusal_reason: `MISSING_${String(tool).toUpperCase()}`,
-        detail: { tool, want: range, have: declared },
-      };
-    }
-  }
-
-  if (task.write === true && !machineWritable(caps)) {
-    return { status: 'refused', refusal_reason: 'READ_ONLY_MACHINE', detail: { caps } };
-  }
-
-  return null;
-}
-
-/* ------------------------------------------------------------------ */
-/* RabbitState                                                         */
-/* ------------------------------------------------------------------ */
-
-const INSTANCE_SEP = '\u0000';
-
-export class RabbitState {
-  constructor(options = {}) {
-    this._now = normalizeNow(options.now);
-    this._idFactory = options.idFactory ?? createIdFactory();
-    this._randomToken = options.tokenFactory ?? (() => randomBytes(24).toString('hex'));
-    this._randomChars = options.randomChars
-      ?? ((n) => { const a = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'; const b = randomBytes(n); let s = ''; for (let i = 0; i < n; i += 1) s += a[b[i] % a.length]; return s; });
-
-    this.protocolVersion = PROTOCOL_VERSION;
-    this.eventBufferSize = options.eventBufferSize ?? DEFAULT_EVENT_BUFFER_SIZE;
-    this.pairingTtlMs = options.pairingTtlMs ?? DEFAULT_PAIRING_TTL_MS;
-    /** When true one code stays valid for its whole TTL instead of rotating. */
-    this.pairingCodeReusable = options.pairingCodeReusable === true;
-    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
-    this.missedHeartbeats = options.missedHeartbeats ?? DEFAULT_MISSED_HEARTBEATS;
-    this.leaseGraceMs = options.leaseGraceMs ?? DEFAULT_LEASE_GRACE_MS;
-    /**
-     * v0.4.0: how long the relay holds its own offer back when the dispatcher says it will push the
-     * offer over the direct path (`origin_machine_id` + `p2p.mode`).
-     *
-     * Without this, the direct path could never win: the relay's offer goes out over an SSE stream
-     * that is already open, while a punch costs at least one round trip, so the relay copy would
-     * arrive first essentially always and `transport` would read `relay` even on a network where
-     * the punch succeeded. Measured on loopback, and it is exactly what the first version of this
-     * release did.
-     *
-     * The hold is bounded and self-healing: the executor renews its lease (a heartbeat) the moment
-     * it starts work on the direct copy, which moves the lease out of `queued`, and the deferred
-     * offer is then dropped. If the punch fails, nothing renews the lease and the relay offers
-     * normally once the grace expires -- so a failed punch costs this much latency and nothing else.
-     */
-    this.p2pOfferGraceMs = Number.isFinite(options.p2pOfferGraceMs) && options.p2pOfferGraceMs >= 0
-      ? options.p2pOfferGraceMs
-      : DEFAULT_P2P_OFFER_GRACE_MS;
-    /** Deferred offers, keyed `task_id:machine_id`, so they can be cleared on close(). */
-    this._pendingOffers = new Map();
-    /** v0.3.0: age beyond which a reported RTT is flagged stale. */
-    this.rttStaleMs = Number.isFinite(options.rttStaleMs) ? options.rttStaleMs : DEFAULT_RTT_STALE_MS;
-
-    this.startedAtMs = this._now();
-    /** v0.1.2 §8.3: random per-process id; a change tells clients the relay restarted. */
-    this.relayId = options.relayId ?? randomBytes(8).toString('hex');
-    /** v0.1.2 §7: optional injected Persistence instance (state.mjs never touches fs itself). */
-    this._persist = options.persistence ?? null;
-    /** True while replaying a ledger — suppresses event emission and re-persistence. */
-    this._restoring = false;
-    /** Ledger entries that could not be replayed. */
-    this.replayWarnings = [];
-    this.seq = 0;
-    /** @type {{seq:number,event:object,target:string|null}[]} ring buffer, last N events */
-    this.buffer = [];
-    this.devices = new Map();      // machine_id -> device
-    this.tokens = new Map();       // device_token -> machine_id
-    this.tasks = new Map();        // task_id -> task
-    this.results = new Map();      // instanceKey -> {envelope, machine_id, received_at_ms, ...}
-    this.pairingCodes = new Map(); // code -> {code, created_at_ms, expires_at_ms, used}
-    this._listeners = new Set();
-  }
-
-  /* ---------------- clock / ids ---------------- */
-
-  nowMs() { return this._now(); }
-  nowIso() { return rfc3339(this.nowMs()); }
-  nextId() { return this._idFactory(this.nowMs()); }
-  newToken() { return this._randomToken(); }
-
-  /** §4.3 lease window = 2 missed heartbeats (20s) + grace (30s) = 50s. */
-  leaseWindowMs() { return this.heartbeatIntervalMs * this.missedHeartbeats + this.leaseGraceMs; }
-
-  /* ---------------- persistence hooks (v0.1.2 §7) ---------------- */
-
-  /** Inject/replace the persistence backend (also used by tests). */
-  setPersistence(persistence) { this._persist = persistence ?? null; return this._persist; }
-
-  /** Snapshot the device table; failures must never break the request path. */
-  _saveDevices() {
-    if (this._restoring || !this._persist) return false;
-    try {
-      return this._persist.saveDevices(this.devices);
-    } catch (err) {
-      this._persist.warn?.('devices.json', `snapshot failed: ${err.message}`);
-      return false;
-    }
-  }
-
-  /** Append one ledger entry; failures must never break the request path. */
-  _ledger(entry) {
-    if (this._restoring || !this._persist) return false;
-    try {
-      const appended = this._persist.append(entry);
-      // v0.6.2: a successful append is what clears a degraded relay, so the outcome has to be
-      // reported back rather than assumed -- otherwise the state could only ever be entered.
-      if (appended) this._persist.noteAppendSuccess?.();
-      return appended;
-    } catch (err) {
-      // Recorded as a state, not merely as a line: this is the one relay failure that keeps serving,
-      // and so the one that is invisible from every other angle (v0.6.2).
-      if (typeof this._persist.noteAppendFailure === 'function') this._persist.noteAppendFailure(err.message);
-      else this._persist.warn?.('ledger.jsonl', `append failed: ${err.message}`);
-      return false;
-    }
-  }
-
-  _ledgerLease(task, lease) {
-    this._ledger({ type: 'lease.changed', task_id: task.task_id, machine_id: lease.machine_id, lease: { ...lease } });
-  }
-
-  /**
-   * v0.1.2 §7 startup recovery: rebuild the device table, token index, tasks,
-   * leases and the result/dedupe index from a devices snapshot + ledger replay.
-   * Never emits events and never writes back what it just read.
-   */
-  restore({ devices = {}, ledger = [] } = {}) {
-    this._restoring = true;
-    try {
-      for (const [machineId, d] of Object.entries(devices)) {
-        if (!d || typeof d !== 'object') continue;
-        const pairedAt = Date.parse(d.paired_at ?? '');
-        const device = {
-          machine_id: machineId,
-          machine_name: typeof d.machine_name === 'string' && d.machine_name ? d.machine_name : machineId,
-          platform: d.platform ?? {},
-          caps: d.caps ?? {},
-          user_id: d.user_id ?? null,
-          device_token: typeof d.device_token === 'string' ? d.device_token : null,
-          paired_at_ms: Number.isFinite(pairedAt) ? pairedAt : this.nowMs(),
-          re_paired: d.re_paired === true,
-          last_seen_at_ms: this.nowMs(),
-          // a snapshot proves the device exists, not that it is connected
-          online: false,
-          streams: 0,
-          // v0.3.0: RTT is volatile and is NEVER restored. Even if a snapshot on
-          // disk happens to carry `rtt_ms`, it is dropped here: after a restart the
-          // relay genuinely does not know the latency any more, and reporting a
-          // pre-restart number as current would be a lie that no reader can detect.
-          rtt_ms: null,
-          rtt_at_ms: null,
-          last_heartbeat_at_ms: null,
-          stream_connects: 0,
-        };
-        this.devices.set(machineId, device);
-        if (device.device_token) this.tokens.set(device.device_token, machineId);
-      }
-
-      let revivedTasks = 0;
-      for (const entry of ledger) {
-        try {
-          if (this._applyLedgerEntry(entry) === true) revivedTasks += 1;
-        } catch (err) {
-          this.replayWarnings.push({ type: entry?.type ?? '<unknown>', message: err.message });
-        }
-      }
-      return { revived_devices: this.devices.size, revived_tasks: revivedTasks };
-    } finally {
-      this._restoring = false;
-    }
-  }
-
-  /** @returns {boolean} true when a new task was created. */
-  _applyLedgerEntry(entry) {
-    if (!entry || typeof entry.type !== 'string') return false;
-    switch (entry.type) {
-      case 'task.created': {
-        const t = entry.task;
-        if (!t || typeof t.task_id !== 'string') return false;
-        const createdAt = Number.isFinite(t.created_at_ms) ? t.created_at_ms : Date.parse(entry.ts ?? '');
-        const task = {
-          task_id: t.task_id,
-          mode: t.mode ?? 'replicate',
-          command_argv: t.command_argv ?? [],
-          cwd_rel: t.cwd_rel ?? '.',
-          index_total: t.index_total ?? 1,
-          timeout_ms: t.timeout_ms ?? 300_000,
-          write: t.write === true,
-          write_scope: t.write_scope ?? [],
-          require_exclusive_write: t.require_exclusive_write === true,
-          base_commit: t.base_commit ?? null,
-          base_tree: t.base_tree ?? null,
-          requirements: t.requirements ?? {},
-          compare_policy: t.compare_policy ?? {},
-          halt: t.halt ?? 'never',
-          created_by: t.created_by ?? null,
-          created_at_ms: Number.isFinite(createdAt) ? createdAt : this.nowMs(),
-          command_hash: t.command_hash ?? null,
-          attempt: t.attempt ?? 1,
-          leases: new Map(),
-          cancelled: false,
-          cancel_reason: null,
-          degraded: t.degraded ?? null,
-          deadline_ms: t.deadline_ms ?? 0,
-          // v0.4.0 routing metadata. Read defensively: a ledger written by v0.3.9 has neither key,
-          // and a replayed task with `null` for both is exactly a v0.3.9 task.
-          origin_machine_id: t.origin_machine_id ?? null,
-          p2p: t.p2p ?? null,
-          result_seqs: [],
-        };
-        for (const lease of entry.leases ?? []) {
-          if (lease && typeof lease.machine_id === 'string') task.leases.set(lease.machine_id, { ...lease });
-        }
-        this.tasks.set(task.task_id, task);
-        return true;
-      }
-      case 'lease.changed': {
-        const task = this.tasks.get(entry.task_id);
-        const lease = task?.leases.get(entry.machine_id);
-        if (!lease) return false;
-        Object.assign(lease, entry.lease ?? {});
-        return false;
-      }
-      case 'result.stored': {
-        const record = entry.result;
-        if (!record || typeof record.instance_key !== 'string') return false;
-        this.results.set(record.instance_key, { ...record });
-        const task = this.tasks.get(record.envelope?.task_id);
-        if (task && Number.isInteger(record.seq)) task.result_seqs.push(record.seq);
-        return false;
-      }
-      case 'task.cancelled': {
-        const task = this.tasks.get(entry.task_id);
-        if (task) {
-          task.cancelled = true;
-          task.cancel_reason = entry.reason ?? null;
-        }
-        return false;
-      }
-      default:
-        return false; // unknown entry type: forward compatible, ignored
-    }
-  }
-
-  /* ---------------- events (§3) ---------------- */
-
-  nextSeq() { this.seq += 1; return this.seq; }
-
-  /** Reserve a seq WITHOUT buffering (used for the per-connection `ready` frame). */
-  reserveSeq() { return this.nextSeq(); }
-
-  onEvent(listener) {
-    this._listeners.add(listener);
-    return () => this._listeners.delete(listener);
-  }
-
-  /**
-   * Emit an event: allocates the next global seq, buffers it (ring of N) and
-   * notifies subscribers. `target` is the machine_id the event is addressed to
-   * (null = broadcast). The target is NOT serialized except as `machine_id`.
-   */
-  emit(type, fields = {}, opts = {}) {
-    const target = opts.target ?? null;
-    const seq = this.nextSeq();
-    const event = {
-      type,
-      seq,
-      rabbit_time: this.nowIso(),
-      ...(target ? { machine_id: target } : {}),
-      ...fields,
-    };
-    const entry = { seq, event, target };
-    this.buffer.push(entry);
-    if (this.buffer.length > this.eventBufferSize) {
-      this.buffer.splice(0, this.buffer.length - this.eventBufferSize);
-    }
-    for (const listener of this._listeners) {
-      try { listener(entry); } catch { /* subscriber errors must never break state */ }
-    }
-    return event;
-  }
-
-  oldestBufferedSeq() { return this.buffer.length ? this.buffer[0].seq : this.seq + 1; }
-  /**
-   * Highest seq present in the replay ring (0 when empty).
-   *
-   * Deliberately different from `lastSeq()`: `ready` frames allocate seq numbers
-   * without being buffered, so `lastSeq()` can run ahead of anything a client can
-   * actually replay. Diagnostics that describe the REPLAY WINDOW must use this one.
-   */
-  lastBufferedSeq() { return this.buffer.length ? this.buffer[this.buffer.length - 1].seq : 0; }
-  lastSeq() { return this.seq; }
-
-  /** Replay entries with seq >= from (used by GET /v1/stream?seq=|Last-Event-ID). */
-  replayEntries(from) {
-    return this.buffer.filter((e) => e.seq >= from);
-  }
-
-  eventsSince(from) { return this.replayEntries(from).map((e) => e.event); }
-
-  /* ---------------- pairing (§2) ---------------- */
-
-  createPairingCode({ ttlMs = this.pairingTtlMs } = {}) {
-    let code;
-    do { code = `PAIR-${this._randomChars(8)}`; } while (this.pairingCodes.has(code));
-    const now = this.nowMs();
-    this.pairingCodes.set(code, { code, created_at_ms: now, expires_at_ms: now + ttlMs, used: false });
-    return code;
-  }
-
-  /** Revoke every outstanding code and mint a new one. */
-  rotatePairingCode(opts) {
-    for (const rec of this.pairingCodes.values()) rec.used = true;
-    return this.createPairingCode(opts);
-  }
-
-  /**
-   * Register an externally supplied code (`--pairing-code <c>`).
-   *
-   * v0.1.2 BUG-1: assigning the code to `relay.pairingCode` without registering it
-   * advertised a code that `/v1/pair` then rejected with PAIRING_INVALID, so every
-   * documented scripted-onboarding flow failed. "Which code do we use" and "is the
-   * code registered" are two different questions; this answers the second.
-   */
-  registerPairingCode(code, { ttlMs = this.pairingTtlMs } = {}) {
-    if (typeof code !== 'string' || code.trim() === '') {
-      throw new ProtocolError('BAD_REQUEST', 'pairing code must be a non-empty string', { pairing_code: code });
-    }
-    const value = code.trim();
-    const now = this.nowMs();
-    this.pairingCodes.set(value, { code: value, created_at_ms: now, expires_at_ms: now + ttlMs, used: false });
-    return value;
-  }
-
-  /** §2.2 step 3: validate a one-time code. */
-  validatePairingCode(code) {
-    if (typeof code !== 'string' || code.length === 0) {
-      throw new ProtocolError('PAIRING_INVALID', 'pairing_code is required');
-    }
-    const rec = this.pairingCodes.get(code);
-    if (!rec) throw new ProtocolError('PAIRING_INVALID', 'unknown pairing code', { pairing_code: code });
-    if (rec.used) throw new ProtocolError('PAIRING_INVALID', 'pairing code already used', { pairing_code: code });
-    if (this.nowMs() >= rec.expires_at_ms) {
-      throw new ProtocolError('PAIRING_EXPIRED', 'pairing code expired', { pairing_code: code, expired_at: rfc3339(rec.expires_at_ms) });
-    }
-    return rec;
-  }
-
-  /** §2.2: exchange a one-time code for a device_token. §1: idempotent. */
-  pair(request = {}) {
-    const rec = this.validatePairingCode(request.pairing_code);
-    const machineId = request.machine_id;
-    if (typeof machineId !== 'string' || machineId.length === 0) {
-      throw new ProtocolError('BAD_REQUEST', 'machine_id is required');
-    }
-    const now = this.nowMs();
-    const token = this.newToken();
-    const existing = this.devices.get(machineId);
-    if (existing?.device_token) this.tokens.delete(existing.device_token);
-
-    const device = {
-      machine_id: machineId,
-      machine_name: typeof request.machine_name === 'string' && request.machine_name
-        ? request.machine_name : machineId.slice(0, 12),
-      platform: request.platform ?? {},
-      caps: request.caps ?? {},
-      user_id: request.user_id ?? null,
-      device_token: token,
-      paired_at_ms: now,
-      re_paired: Boolean(existing),
-      last_seen_at_ms: now,
-      online: true,
-      streams: existing?.streams ?? 0,
-      // v0.3.0 RTT: starts unknown. `null` is "never measured"; 0 would mean "instant".
-      rtt_ms: null,
-      rtt_at_ms: null,
-      last_heartbeat_at_ms: null,
-      stream_connects: existing?.stream_connects ?? 0,
-    };
-    this.devices.set(machineId, device);
-    this.tokens.set(token, machineId);
-    rec.used = true;
-
-    // A group has more than one machine, and a single-use code would leave the
-    // operator unable to pair the second one without restarting the relay. So
-    // consuming a code immediately mints the next one and announces it: the
-    // operator pairs machine A, sees a fresh code, and pairs machine B with it.
-    // `pairingCodeReusable` keeps one code alive for the whole window instead,
-    // for scripted onboarding where nobody is watching stdout.
-    let nextCode = null;
-    const reusable = this.pairingCodeReusable === true;
-    if (reusable) {
-      rec.used = false;
-    } else {
-      nextCode = this.rotatePairingCode();
-    }
-
-    this.emit('peer.hello', {
-      machine_id: machineId,
-      machine_name: device.machine_name,
-      platform: device.platform,
-    });
-
-    if (nextCode) {
-      this.emit('notice', {
-        level: 'info',
-        code: 'PAIRING_CODE_ROTATED',
-        message: 'pairing code consumed; a new one is available',
-        pairing_code: nextCode,
-      });
-    }
-
-    // §7: a device change is snapshotted immediately.
-    this._saveDevices();
-    this._ledger({
-      type: 'device.paired',
-      machine_id: machineId,
-      machine_name: device.machine_name,
-      re_paired: device.re_paired,
-    });
-
-    return {
-      device_token: token,
-      protocol_version: PROTOCOL_VERSION,
-      rabbit_time: rfc3339(now),
-      ...(nextCode ? { next_pairing_code: nextCode } : {}),
-    };
-  }
-
-  /** @returns {object|null} device for a bearer token. */
-  authenticate(token) {
-    if (typeof token !== 'string' || token.length === 0) return null;
-    const machineId = this.tokens.get(token);
-    if (!machineId) return null;
-    return this.devices.get(machineId) ?? null;
-  }
-
-  touchDevice(machineId, { online = true } = {}) {
-    const device = this.devices.get(machineId);
-    if (!device) return null;
-    device.last_seen_at_ms = this.nowMs();
-    if (online) device.online = true;
-    return device;
-  }
-
-  setOnline(machineId, online, reason = null) {
-    const device = this.devices.get(machineId);
-    if (!device) return null;
-    if (device.online === online) return device;
-    device.online = online;
-    if (online) {
-      this.touchDevice(machineId);
-      this.emit('peer.hello', {
-        machine_id: machineId,
-        machine_name: device.machine_name,
-        platform: device.platform,
-      });
-    } else {
-      this.emit('peer.bye', { machine_id: machineId, reason: reason ?? 'stream_closed' });
-    }
-    return device;
-  }
-
-  /* ---------------- RTT (v0.3.0 §R) ---------------- */
-
-  /**
-   * Validate an inbound `rtt_ms`.
-   *
-   * The contract is deliberately liberal: a MISSING or INVALID value must never
-   * reject the heartbeat and must never clobber a previously known good value.
-   * RTT is a diagnostic; it must not be able to break lease renewal.
-   *
-   * Sanity ceiling: anything above `MAX_RTT_MS` (24h) is treated as invalid. A
-   * single garbage value would otherwise poison the fleet aggregate.
-   */
-  static normalizeRtt(value) {
-    if (value === undefined) return { provided: false, valid: false };
-    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
-      return { provided: true, valid: false };
-    }
-    if (value > MAX_RTT_MS) return { provided: true, valid: false };
-    return { provided: true, valid: true, value };
-  }
-
-  /**
-   * RTT is a VOLATILE diagnostic: it is intentionally NOT written to
-   * `devices.json` and NOT replayed from the ledger, so a restarted relay reports
-   * `rtt_ms: null` until a machine heartbeats again. A persisted value would be
-   * indistinguishable from a fresh one and would let the relay claim knowledge it
-   * lost when the process died.
-   */
-  rttStaleAfterMs() { return this.rttStaleMs; }
-
-  /**
-   * v0.3.0: absorb the optional `rtt_ms` carried by a heartbeat.
-   *
-   * Deliberately liberal, because RTT is a diagnostic and must never be able to
-   * break lease renewal:
-   *   - the field is optional; a v0.2.3 agent never sends it
-   *   - a MISSING or INVALID value is IGNORED, keeping the previous value, and the
-   *     heartbeat still succeeds
-   *   - unknown extra fields are ignored entirely (forward compatibility)
-   *
-   * `last_heartbeat_at` advances on EVERY accepted heartbeat, with or without a
-   * usable RTT: it answers "is the machine alive", while `rtt_at` answers "when
-   * was this number measured". Keeping them separate is what lets a reader tell a
-   * genuinely slow machine from one that is simply gone.
-   */
-  recordHeartbeatMetrics(machineId, input = {}, nowMs = this.nowMs()) {
-    const device = this.devices.get(machineId);
-    if (!device) return null;
-    device.last_heartbeat_at_ms = nowMs;
-    const rtt = RabbitState.normalizeRtt(input.rtt_ms);
-    if (rtt.valid) {
-      device.rtt_ms = rtt.value;
-      device.rtt_at_ms = nowMs;
-    }
-    return device;
-  }
-
-  /** True when there is no value, or the value is older than the staleness window. */
-  isRttStale(device, nowMs = this.nowMs()) {
-    if (!device || device.rtt_ms === null || device.rtt_ms === undefined) return true;
-    if (device.rtt_at_ms === null || device.rtt_at_ms === undefined) return true;
-    return nowMs - device.rtt_at_ms > this.rttStaleMs;
-  }
-
-  /** How old the RTT measurement is, in ms; null when there is none. */
-  rttAgeMs(device, nowMs = this.nowMs()) {
-    if (!device || device.rtt_at_ms === null || device.rtt_at_ms === undefined) return null;
-    return Math.max(0, nowMs - device.rtt_at_ms);
-  }
-
-  /** Record that a machine attached a stream (a reconnect is any attach after the first). */
-  noteStreamConnect(machineId) {
-    const device = this.devices.get(machineId);
-    if (!device) return null;
-    device.stream_connects = (device.stream_connects ?? 0) + 1;
-    return device.stream_connects;
-  }
-
-  /**
-   * v0.3.0 aggregate for `/healthz`.
-   *
-   * Only FRESH measurements count. A machine that has been gone for a day must not
-   * drag min/max/avg around, and with no fresh data every numeric field is null --
-   * never 0, which would read as "instantaneous".
-   */
-  rttSummary(nowMs = this.nowMs()) {
-    const fresh = [];
-    let stale = 0;
-    let unknown = 0;
-    for (const device of this.devices.values()) {
-      if (device.rtt_ms === null || device.rtt_ms === undefined) { unknown += 1; continue; }
-      if (this.isRttStale(device, nowMs)) { stale += 1; continue; }
-      fresh.push(device.rtt_ms);
-    }
-    if (fresh.length === 0) {
-      return {
-        machines_reporting: 0,
-        min_ms: null,
-        max_ms: null,
-        avg_ms: null,
-        machines_stale: stale,
-        machines_unknown: unknown,
-      };
-    }
-    const sum = fresh.reduce((a, b) => a + b, 0);
-    return {
-      machines_reporting: fresh.length,
-      min_ms: Math.min(...fresh),
-      max_ms: Math.max(...fresh),
-      avg_ms: Math.round((sum / fresh.length) * 10) / 10,
-      machines_stale: stale,
-      machines_unknown: unknown,
-    };
-  }
-
-  /**
-   * v0.3.0 single-machine status view.
-   *
-   * `last_heartbeat_at` and `rtt_at` answer different questions, and the gap
-   * between them is the whole point: a machine can be heartbeating (alive) while
-   * its RTT number is old (a v0.2.3 agent that never sends `rtt_ms`), and a
-   * machine can be gone while a plausible-looking RTT is still on file.
-   */
-  deviceStatus(machineId, nowMs = this.nowMs()) {
-    const device = this.devices.get(machineId);
-    if (!device) return null;
-    const rttAt = device.rtt_at_ms ?? null;
-    const lastHeartbeat = device.last_heartbeat_at_ms ?? null;
-    return {
-      machine_id: device.machine_id,
-      machine_name: device.machine_name,
-      relay_id: this.relayId,
-      connected: (device.streams ?? 0) > 0,
-      streams: device.streams ?? 0,
-      online: device.online === true,
-      rtt_ms: device.rtt_ms ?? null,
-      rtt_at: rttAt === null ? null : rfc3339(rttAt),
-      rtt_age_ms: this.rttAgeMs(device, nowMs),
-      rtt_stale: this.isRttStale(device, nowMs),
-      last_heartbeat_at: lastHeartbeat === null ? null : rfc3339(lastHeartbeat),
-      last_seen_at: device.last_seen_at_ms === null || device.last_seen_at_ms === undefined
-        ? null : rfc3339(device.last_seen_at_ms),
-      reconnect_attempts: Math.max(0, (device.stream_connects ?? 0) - 1),
-      stream_connects: device.stream_connects ?? 0,
-      paired_at: device.paired_at_ms === null || device.paired_at_ms === undefined
-        ? null : rfc3339(device.paired_at_ms),
-      platform: device.platform,
-      caps: device.caps,
-      user_id: device.user_id ?? null,
-      now: rfc3339(nowMs),
-    };
-  }
-
-  /** Public device view — never leaks device_token. */
-  publicDevice(device) {
-    return {
-      machine_id: device.machine_id,
-      machine_name: device.machine_name,
-      platform: device.platform,
-      caps: device.caps,
-      user_id: device.user_id,
-      online: device.online,
-      streams: device.streams,
-      paired_at: rfc3339(device.paired_at_ms),
-      last_seen_at: rfc3339(device.last_seen_at_ms),
-      // v0.3.0: `null` means "never measured", which is NOT the same as 0ms.
-      rtt_ms: device.rtt_ms ?? null,
-      rtt_at: device.rtt_at_ms === null || device.rtt_at_ms === undefined ? null : rfc3339(device.rtt_at_ms),
-      rtt_age_ms: this.rttAgeMs(device),
-      rtt_stale: this.isRttStale(device),
-      last_heartbeat_at: device.last_heartbeat_at_ms === null || device.last_heartbeat_at_ms === undefined
-        ? null : rfc3339(device.last_heartbeat_at_ms),
-      reconnect_attempts: Math.max(0, (device.stream_connects ?? 0) - 1),
-    };
-  }
-
-  listDevices() { return [...this.devices.values()].map((d) => this.publicDevice(d)); }
-
-  /* ---------------- tasks (§4) ---------------- */
-
-  /**
-   * v0.4.0: validate the routing metadata a `POST /v1/task` body may carry.
-   *
-   * A machine, not a mode, is `origin_machine_id`: where the task was typed (`device.json`), so an
-   * offer can carry that fact to the machine that has to run it. `p2p.mode` is the dispatcher's
-   * resolved mode for this particular task — the plugin may be configured `direct` while a
-   * scheduled run is `relay`.
-   *
-   * Validation is deliberately shallow and strictly typed, in the house style of this file: a
-   * missing value is the v0.3.9 shape and stays valid, while a present-but-wrong value is refused
-   * by name. Accepting a non-string here would put a number into `origin_machine_id` and only fail
-   * later, on a machine that cannot tell a bad field from a bad relay.
-   *
-   * @returns {{origin_machine_id:string|null, p2p:{mode:string}|null}}
-   */
-  static validateTaskRouting(input = {}) {
-    let originMachineId = null;
-    if (input.origin_machine_id !== undefined && input.origin_machine_id !== null) {
-      if (typeof input.origin_machine_id !== 'string'
-        || input.origin_machine_id.length === 0
-        || input.origin_machine_id.length > MAX_ORIGIN_MACHINE_ID_LENGTH) {
-        throw new ProtocolError(
-          'BAD_REQUEST',
-          `origin_machine_id must be a non-empty string of at most ${MAX_ORIGIN_MACHINE_ID_LENGTH} characters`,
-          { origin_machine_id: input.origin_machine_id },
-        );
-      }
-      originMachineId = input.origin_machine_id;
-    }
-
-    let p2p = null;
-    if (input.p2p !== undefined && input.p2p !== null) {
-      if (typeof input.p2p !== 'object' || Array.isArray(input.p2p)) {
-        throw new ProtocolError('BAD_REQUEST', 'p2p must be an object with a `mode` field', { p2p: input.p2p });
-      }
-      if (!P2P_MODES.includes(input.p2p.mode)) {
-        throw new ProtocolError(
-          'BAD_REQUEST',
-          `p2p.mode must be one of ${P2P_MODES.join('|')}`,
-          { 'p2p.mode': input.p2p.mode ?? null },
-        );
-      }
-      // Copied rather than referenced: the recorded task must not be mutable through the request
-      // body the caller still holds.
-      p2p = { ...input.p2p };
-    }
-
-    return { origin_machine_id: originMachineId, p2p };
-  }
-
-  /**
-   * v0.4.0 §5.2: validate the optional transport fields of a result envelope.
-   *
-   * Same reasoning as `validateTaskRouting`: `transport` is an enum and `p2p` is an opaque object,
-   * so anything else is refused by name at the door. Both fields stay OUT of
-   * `REQUIRED_ENVELOPE_FIELDS` (a missing one is a v0.3.9 envelope, not an incomplete one) and out
-   * of `COMPARABLE_FIELDS` (a path is not a result).
-   */
-  static validateTransportFields(envelope = {}) {
-    if (envelope.transport !== undefined && envelope.transport !== null) {
-      if (!TRANSPORT_VALUES.includes(envelope.transport)) {
-        throw new ProtocolError(
-          'BAD_REQUEST',
-          `transport must be one of ${TRANSPORT_VALUES.join('|')}`,
-          { transport: envelope.transport },
-        );
-      }
-    }
-    if (envelope.p2p !== undefined && envelope.p2p !== null
-      && (typeof envelope.p2p !== 'object' || Array.isArray(envelope.p2p))) {
-      throw new ProtocolError('BAD_REQUEST', 'p2p must be an object', { p2p: envelope.p2p });
-    }
-  }
-
-  /**
-   * §4.1 POST /v1/task.
-   * Machine selection is not specified by the PROTOCOL; we implement:
-   *   - `target_machines` (optional explicit list), else every paired device
-   *   - capability gate §6.1 per machine (failures become `refused` leases)
-   *   - index assignment: replicate -> 0, split -> round-robin modulo index_total
-   */
-  createTask(input = {}) {
-    // v0.4.0: refused BEFORE the task literal is built and before any offer is emitted, so a bad
-    // value cannot leave a half-created task behind. `POST /v1/task` is all-or-nothing.
-    const routing = RabbitState.validateTaskRouting(input);
-
-    const mode = input.mode ?? 'replicate';
-    if (mode !== 'replicate' && mode !== 'split' && mode !== 'broadcast' && mode !== 'pipeline' && mode !== 'compose') {
-      throw new ProtocolError(
-        'BAD_REQUEST',
-        'mode must be replicate|split|broadcast|pipeline|compose',
-        { mode },
-      );
-    }
-    /**
-     * v0.3.3 `pipeline`: the whole chain runs on each machine, stage after stage.
-     *
-     * The semantics were chosen against the alternative (fan out stage 1, converge its outputs into
-     * stage 2) because that one has no well-defined input: on a fleet, stage 1 produces n different
-     * outputs, and "feed them all to stage 2" does not say in what order, or whether stage 2 then
-     * runs once or n times. Worse, two machines finishing in a different order would produce
-     * different stage-2 inputs, so one task_id would no longer describe one reproducible execution --
-     * which is the property the rest of this system is built on. See docs/PIPELINE-DESIGN.md.
-     *
-     * So: a pipeline is `replicate` applied to a sequence. Every machine runs the whole chain, there
-     * is no cross-machine data flow, and nothing new can be silently dropped in transit.
-     */
-    const rawStages = Array.isArray(input.stages) ? input.stages : null;
-    const isPipeline = mode === 'pipeline';
-    if (isPipeline) {
-      if (rawStages === null || rawStages.length === 0) {
-        throw new ProtocolError('BAD_REQUEST', 'mode=pipeline requires a non-empty `stages` array', {
-          stages: rawStages === null ? null : rawStages.length,
-        });
-      }
-      if (rawStages.length > MAX_PIPELINE_STAGES) {
-        throw new ProtocolError('BAD_REQUEST', `stages must have at most ${MAX_PIPELINE_STAGES} entries`, {
-          stages: rawStages.length,
-        });
-      }
-      rawStages.forEach((stage, i) => {
-        const argv = stage?.command_argv;
-        if (!Array.isArray(argv) || argv.length === 0 || argv.some((a) => typeof a !== 'string')) {
-          throw new ProtocolError('BAD_REQUEST', `stages[${i}].command_argv must be a non-empty string[]`, { index: i });
-        }
-      });
-      // A chain is one execution on one machine; sharding it would mean each machine ran a chain of
-      // its own slice, which is a different feature and not what the caller asked for.
-      if (Number.isInteger(input.index_total) && input.index_total !== 1) {
-        throw new ProtocolError('BAD_REQUEST', 'mode=pipeline runs the whole chain per machine, so index_total must be 1', {
-          index_total: input.index_total,
-        });
-      }
-    } else if (rawStages !== null) {
-      // Refused rather than ignored: the caller believes they described a sequence, and running only
-      // `command_argv` would silently drop every stage after the first.
-      throw new ProtocolError('BAD_REQUEST', '`stages` is only valid with mode=pipeline', { mode, stages: rawStages.length });
-    }
-
-    /**
-     * Normalized stage list. For every mode there is at least one stage, so downstream code has a
-     * single shape to reason about and `pipeline` is not a special case at the execution layer.
-     */
-    const stages = isPipeline
-      ? rawStages.map((s, i) => ({
-        index: i,
-        command_argv: [...s.command_argv],
-        cwd_rel: typeof s.cwd_rel === 'string' && s.cwd_rel ? s.cwd_rel : (typeof input.cwd_rel === 'string' && input.cwd_rel ? input.cwd_rel : '.'),
-        timeout_ms: Number.isInteger(s.timeout_ms) ? s.timeout_ms : null,
-        continue_on_failure: s.continue_on_failure === true,
-      }))
-      : null;
-
-    const commandArgv = isPipeline ? [...rawStages[0].command_argv] : input.command_argv;
-    if (!Array.isArray(commandArgv) || commandArgv.length === 0 || commandArgv.some((a) => typeof a !== 'string')) {
-      throw new ProtocolError('BAD_REQUEST', 'command_argv must be a non-empty string[]');
-    }
-    const indexTotal = Number.isInteger(input.index_total) ? input.index_total : 1;
-    if (indexTotal < 1) throw new ProtocolError('BAD_REQUEST', 'index_total must be >= 1');
-
-    const halt = input.halt ?? 'never';
-    if (halt !== 'never' && halt !== 'now') throw new ProtocolError('BAD_REQUEST', 'halt must be never|now', { halt });
-
-    const taskId = input.task_id ?? this.nextId();
-    if (this.tasks.has(taskId)) {
-      throw new ProtocolError('TASK_EXISTS', 'task_id already exists', { task_id: taskId });
-    }
-
-    const now = this.nowMs();
-    const cwdRel = typeof input.cwd_rel === 'string' && input.cwd_rel ? input.cwd_rel : '.';
-    const baseTree = input.base_tree ?? null;
-    const commandHash = input.command_hash ?? (isPipeline
-      ? computePipelineCommandHash(stages, SHELL_ID_DIRECT)
-      : computeCommandHash(commandArgv, SHELL_ID_DIRECT, cwdRel));
-    const timeoutMs = Number.isInteger(input.timeout_ms) ? input.timeout_ms : 300_000;
-
-    // v0.3.3 `broadcast`: one machine runs the command, every other machine is told the outcome.
-    //
-    // The executor choice is deterministic rather than random. A random leader makes a task
-    // impossible to reproduce from its own record -- the same task id would run somewhere else on a
-    // retry -- and this project's whole value rests on being able to say exactly where something ran.
-    // The first target in the relay's own device order is stable for a given device table.
-    //
-    // Observers get a lease so they are tracked and notified, but their lease is `observing`, which
-    // every aggregation step treats as "did not run". That distinction is the point: a machine that
-    // never executed anything agreeing with a result would be a fabrication, and it is exactly the
-    // fabrication this mode could most easily produce.
-    //
-    // Resolved before the task literal because the literal records it. (`targets` is computed below,
-    // so the executor is re-validated against it after that.)
-    const targetIds = Array.isArray(input.target_machines) && input.target_machines.length > 0
-      ? input.target_machines
-      : [...this.devices.keys()];
-    const executorMachineId = mode === 'broadcast'
-      ? (typeof input.executor_machine_id === 'string' && input.executor_machine_id !== ''
-        ? input.executor_machine_id
-        : targetIds[0] ?? null)
-      : null;
-
-    const task = {
-      task_id: taskId,
-      mode,
-      command_argv: commandArgv,
-      cwd_rel: cwdRel,
-      index_total: indexTotal,
-      timeout_ms: timeoutMs,
-      write: input.write === true,
-      write_scope: input.write_scope ?? [],
-      require_exclusive_write: input.require_exclusive_write === true,
-      base_commit: input.base_commit ?? null,
-      base_tree: baseTree,
-      requirements: input.requirements ?? {},
-      compare_policy: input.compare_policy ?? {},
-      halt,
-      created_by: input.created_by ?? null,
-      created_at_ms: now,
-      command_hash: commandHash,
-      attempt: 1,
-      leases: new Map(),
-      cancelled: false,
-      cancel_reason: null,
-      degraded: null,
-      deadline_ms: now + timeoutMs,
-      result_seqs: [],
-      /** v0.3.3: which machine actually executes under `broadcast`; null for the other modes. */
-      executor_machine_id: executorMachineId,
-      /**
-       * v0.3.3: the normalized stage list for `pipeline`, or null.
-       *
-       * Sent to the machine in the offer so it can run the whole chain. Kept on the task as well so
-       * a report can say how many stages were supposed to run even when the machine crashed before
-       * reporting any of them.
-       */
-      stages,
-      /**
-       * v0.4.0: where the task came from and under which P2P mode it was dispatched, or null.
-       *
-       * Kept on the task (not just passed to `emitOffer`) because an offer is emitted more than
-       * once: `redeliverPendingOffers` re-states unclaimed work on every reconnect and
-       * `_takeover` re-offers a freed index. A machine that reconnects must see the same routing
-       * facts as the machine that was connected at dispatch time, or the direct-push half of the
-       * feature would work exactly once and then quietly stop.
-       */
-      origin_machine_id: routing.origin_machine_id,
-      p2p: routing.p2p,
-    };
-
-    const all = [...this.devices.values()];
-    const targets = Array.isArray(input.target_machines) && input.target_machines.length > 0
-      ? all.filter((d) => input.target_machines.includes(d.machine_id))
-      : all;
-
-    // v0.3.3 `broadcast`: validated here, where `targets` is known. The executor id itself was
-    // resolved before the task literal because the literal records it.
-    if (mode === 'broadcast' && executorMachineId !== null && !targets.some((d) => d.machine_id === executorMachineId)) {
-      throw new ProtocolError('BAD_REQUEST', 'executor_machine_id is not among the target machines', {
-        executor_machine_id: executorMachineId,
-        targets: targets.map((d) => d.machine_id),
-      });
-    }
-
-    if (targets.length === 0) {
-      throw new ProtocolError('NO_ONLINE_DEVICE', 'no paired device available for this task', {
-        known_devices: all.length,
-      });
-    }
-
-    const dedupeKeyBase = computeDedupeKey(taskId, 0, commandHash, baseTree);
-    if (typeof dedupeKeyBase !== 'string' || dedupeKeyBase.length !== 64) {
-      throw new ProtocolError('INTERNAL', 'failed to compute dedupe_key');
-    }
-    let lastSeq = this.seq;
-    targets.forEach((device, i) => {
-      const index = mode === 'replicate' ? 0 : i % indexTotal;
-      const observing = mode === 'broadcast' && device.machine_id !== executorMachineId;
-      const lease = {
-        machine_id: device.machine_id,
-        machine_name: device.machine_name,
-        index,
-        attempt: 1,
-        // `observing` is a lease state, not an outcome: the machine holds a place in this task and
-        // will be told what happened, but it was never handed the command. `gateMachine` below is
-        // skipped for it because refusing to do work you were never asked to do is not a refusal.
-        state: observing ? 'observing' : 'queued',
-        refusal_reason: null,
-        refusal_detail: null,
-        dedupe_key: computeDedupeKey(taskId, index, commandHash, baseTree),
-        last_heartbeat_ms: now,
-        claimed_at_ms: now,
-        lease_until_ms: now + this.leaseWindowMs(),
-        phase: null,
-        progress: null,
-        offered_seq: null,
-        expired_at_ms: null,
-        finished_at_ms: null,
-        heartbeat_count: 0,
-      };
-      if (observing) {
-        // No capability gate and no offer: the machine is not being asked to run anything, so there
-        // is nothing to refuse and nothing to hand out. It is recorded so the task can tell it the
-        // outcome afterwards.
-        task.leases.set(device.machine_id, lease);
-        return;
-      }
-      const gate = gateMachine(task, device);
-      if (gate) {
-        lease.state = 'refused';
-        lease.refusal_reason = gate.refusal_reason;
-        lease.refusal_detail = gate.detail;
-        task.leases.set(device.machine_id, lease);
-        this.emit('notice', {
-          level: 'warn',
-          code: 'CAPABILITY_REFUSED',
-          message: `${device.machine_id} refused: ${gate.refusal_reason}`,
-          task_id: taskId,
-        });
-        return;
-      }
-      task.leases.set(device.machine_id, lease);
-      const grace = this._p2pOfferGraceMs(task);
-      if (grace > 0) {
-        // v0.4.0: the dispatcher is pushing this offer over the direct path right now. Hold the
-        // relay's copy for `grace` ms so the direct one can win; see `p2pOfferGraceMs`.
-        this._scheduleOffer(task, lease, grace);
-      } else {
-        const event = this.emitOffer(task, lease);
-        lastSeq = event.seq;
-      }
-    });
-
-    this.tasks.set(taskId, task);
-
-    this._ledger({
-      type: 'task.created',
-      task: {
-        task_id: task.task_id,
-        mode: task.mode,
-        command_argv: task.command_argv,
-        cwd_rel: task.cwd_rel,
-        index_total: task.index_total,
-        timeout_ms: task.timeout_ms,
-        write: task.write,
-        write_scope: task.write_scope,
-        require_exclusive_write: task.require_exclusive_write,
-        base_commit: task.base_commit,
-        base_tree: task.base_tree,
-        requirements: task.requirements,
-        compare_policy: task.compare_policy,
-        halt: task.halt,
-        created_by: task.created_by,
-        created_at_ms: task.created_at_ms,
-        command_hash: task.command_hash,
-        attempt: task.attempt,
-        deadline_ms: task.deadline_ms,
-        // v0.4.0: routing metadata, so a restarted relay re-offers with the same facts.
-        origin_machine_id: task.origin_machine_id ?? null,
-        p2p: task.p2p ?? null,
-      },
-      leases: [...task.leases.values()].map((l) => ({ ...l })),
-    });
-
-    const refusedOnly = [...task.leases.values()].every((l) => l.state === 'refused');
-    if (refusedOnly) {
-      // §6.3 Step 0 territory: a task nobody may execute is still a valid, reportable task.
-      this.emit('notice', {
-        level: 'warn',
-        code: 'NO_ONLINE_DEVICE',
-        message: 'every candidate machine refused the capability gate',
-        task_id: taskId,
-      });
-    }
-
-    return {
-      task_id: taskId,
-      leases: [...task.leases.values()].map((l) => ({
-        machine_id: l.machine_id,
-        index: l.index,
-        state: l.state,
-        // v0.4.0: the dispatcher pushes an offer over the direct path, and the executor dedupes it
-        // against the relay's copy by (task_id, attempt, dedupe_key). Without this field the
-        // dispatcher has to reproduce the §4.4 formula locally, which works for a single-command
-        // task and cannot work for a pipeline one -- the key covers the relay's normalised stage
-        // list. Publishing it makes the pushed copy recognisably the same work item, which is what
-        // keeps the direct path from turning exactly-once into at-least-twice.
-        dedupe_key: l.dedupe_key ?? null,
-        attempt: l.attempt,
-        ...(l.refusal_reason ? { refusal_reason: l.refusal_reason } : {}),
-      })),
-      seq: lastSeq,
-    };
-  }
-
-  /**
-   * v0.4.0: should the relay hold its offer back for this task?
-   *
-   * Only when the dispatcher said two things: that it is a machine (`origin_machine_id`), and that
-   * the direct path is in play (`p2p.mode` of `auto` or `direct`). A `relay` mode or a v0.3.9
-   * dispatcher gets the old behaviour exactly, which is why this predicate is the only gate on the
-   * change and every pre-existing test still sees an immediate offer.
-   *
-   * @param {object} task
-   * @returns {number} milliseconds to hold, or 0 for "offer now"
-   */
-  _p2pOfferGraceMs(task) {
-    if (this.p2pOfferGraceMs <= 0) return 0;
-    const origin = task?.origin_machine_id;
-    if (typeof origin !== 'string' || origin === '') return 0;
-    const mode = task?.p2p?.mode;
-    if (mode !== 'auto' && mode !== 'direct') return 0;
-    return this.p2pOfferGraceMs;
-  }
-
-  /**
-   * v0.4.0: emit `lease`'s offer after `delayMs`, unless the direct path got there first.
-   *
-   * "Got there first" is one fact and it is already tracked: the executor renews the lease
-   * (`POST /v1/heartbeat`) as its first act on any offer it accepts, and a renewal moves the lease
-   * out of `queued`. So the check is the lease's own state — no new message, no new endpoint, and
-   * nothing the executor has to know about.
-   *
-   * The timer is `unref()`ed: a relay with nothing else to do must still be able to exit, and a
-   * pending offer is not a reason to keep a process alive.
-   */
-  _scheduleOffer(task, lease, delayMs) {
-    const key = `${task.task_id}:${lease.machine_id}`;
-    const timer = setTimeout(() => {
-      this._pendingOffers.delete(key);
-      // A lease that was re-created (takeover) or swept is not this one any more.
-      if (task.leases.get(lease.machine_id) !== lease) return;
-      if (lease.state !== 'queued') return; // the direct copy won; nothing to fall back to
-      if (this.isLeaseExpired(lease, this.nowMs())) return; // the sweep owns it now
-      this.emitOffer(task, lease);
-    }, delayMs);
-    timer.unref?.();
-    this._pendingOffers.set(key, timer);
-  }
-
-  /** Drop every deferred offer. Called by the relay's own teardown path. */
-  clearPendingOffers() {
-    for (const timer of this._pendingOffers.values()) clearTimeout(timer);
-    this._pendingOffers.clear();
-  }
-
-  emitOffer(task, lease) {
-    const event = this.emit('task.offer', {
-      task_id: task.task_id,
-      attempt: lease.attempt,
-      mode: task.mode,
-      index: lease.index,
-      index_total: task.index_total,
-      command_argv: task.command_argv,
-      // v0.3.3: present only for `pipeline`, and only then does the machine run a chain. Omitted
-      // entirely otherwise, so an offer for a single-command task is byte-identical to before --
-      // which is what keeps a v0.2.3 agent working against this relay.
-      ...(task.stages ? { stages: task.stages } : {}),
-      /**
-       * v0.4.0: always present, `null` when the caller supplied nothing.
-       *
-       * Deliberately NOT conditional (unlike `stages` above, which is omitted so a single-command
-       * offer stays byte-identical for an old agent): the contract fixes the shape of these two as
-       * `string|null` and `{mode}|null`, and `null` is the honest value for "the dispatcher did not
-       * say" — which is exactly the v0.3.9 case. They are additive keys in an event whose consumers
-       * already ignore unknown fields.
-       */
-      origin_machine_id: task.origin_machine_id ?? null,
-      p2p: task.p2p ?? null,
-      cwd_rel: task.cwd_rel,
-      write: task.write,
-      timeout_ms: task.timeout_ms,
-      base_commit: task.base_commit,
-      base_tree: task.base_tree,
-      requirements: task.requirements,
-      compare_policy: task.compare_policy,
-      dedupe_key: lease.dedupe_key,
-      deadline: rfc3339(task.deadline_ms),
-    }, { target: lease.machine_id });
-    lease.state = 'offered';
-    lease.offered_seq = event.seq;
-    lease.last_heartbeat_ms = this.nowMs();
-    lease.lease_until_ms = lease.last_heartbeat_ms + this.leaseWindowMs();
-    return event;
-  }
-
-  getTask(taskId) { return this.tasks.get(taskId) ?? null; }
-
-  requireTask(taskId) {
-    const task = this.tasks.get(taskId);
-    if (!task) throw new ProtocolError('NOT_FOUND', 'unknown task_id', { task_id: taskId });
-    return task;
-  }
-
-  /**
-   * Re-offer the work a machine was handed but has not yet started (v0.1.2 §8.6).
-   *
-   * WHY THIS EXISTS
-   *
-   * An offer is a point-in-time event on a stream. `createTask` publishes
-   * `task.offer` once, and if the target machine's stream happens to be down at
-   * that instant -- the ordinary situation after a relay restart, a tunnel drop,
-   * or any cross-network interruption -- the event is simply gone. The lease sits
-   * in `offered` until the sweep expires it, the task never runs, and the
-   * operator sees a timeout with no explanation. Measured: the machine is back
-   * online with a live stream within milliseconds, and still receives nothing.
-   *
-   * So the relay re-states unclaimed work when a machine connects. This is safe
-   * because the state it acts on is durable: the lease the offer refers to is
-   * still in the ledger.
-   *
-   * WHY ONLY `offered` AND `queued`
-   *
-   * `running` is deliberately excluded, and that exclusion is the whole safety
-   * argument. A running lease means a machine has already STARTED the command --
-   * it acknowledged the offer and is heartbeating. Re-offering it would make that
-   * machine execute the work a second time, so the fix for a lost offer would
-   * introduce the one failure this project is built to avoid: two machines, or
-   * one machine twice, running the same side-effecting command.
-   *
-   * A machine that dies mid-run therefore does not get its work back here; that
-   * path stays with the sweep, which expires the lease and hands the index to
-   * another machine with `attempt + 1`.
-   *
-   * Re-emitted offers are new events and are replayed like any other, so a client
-   * that reconnects repeatedly can see the same offer more than once. That is
-   * intentional: the agent already de-duplicates by `task_id` (it ignores an
-   * offer whose task is queued or running), and an at-least-once offer with a
-   * client-side dedupe is strictly better than an at-most-once offer that is
-   * silently dropped.
-   *
-   * @param {string} machineId
-   * @returns {{count: number, task_ids: string[]}}
-   */
-  redeliverPendingOffers(machineId) {
-    const taskIds = [];
-    const now = this.nowMs();
-
-    for (const task of this.tasks.values()) {
-      if (task.cancelled === true) continue;
-      const lease = task.leases.get(machineId);
-      if (!lease) continue;
-      // Only work the machine has not begun. See the note above: `running` is
-      // excluded on purpose, not by omission.
-      if (lease.state !== 'offered' && lease.state !== 'queued') continue;
-      // Do not resurrect a lease the sweep has already written off; the takeover
-      // path owns that decision.
-      if (this.isLeaseExpired(lease, now)) continue;
-
-      this.emitOffer(task, lease);
-      taskIds.push(task.task_id);
-    }
-
-    return { count: taskIds.length, task_ids: taskIds };
-  }
-
-  listTasks({ limit = 50 } = {}) {
-    const n = Number.isInteger(limit) && limit > 0 ? limit : 50;
-    return [...this.tasks.values()]
-      .sort((a, b) => b.created_at_ms - a.created_at_ms)
-      .slice(0, n)
-      .map((t) => this.taskSummary(t));
-  }
-
-  taskSummary(task) {
-    return {
-      task_id: task.task_id,
-      mode: task.mode,
-      created_at: rfc3339(task.created_at_ms),
-      created_by: task.created_by,
-      index_total: task.index_total,
-      cancelled: task.cancelled,
-      degraded: task.degraded,
-      leases: [...task.leases.values()].map((l) => l.machine_id),
-      lease_states: Object.fromEntries([...task.leases.values()].map((l) => [l.machine_id, l.state])),
-    };
-  }
-
-  cancelTask(taskId, reason = 'cancelled_by_operator') {
-    const task = this.requireTask(taskId);
-    if (task.cancelled) return task;
-    task.cancelled = true;
-    task.cancel_reason = reason;
-    for (const lease of task.leases.values()) {
-      if (ACTIVE_LEASE_STATES.includes(lease.state)) lease.state = 'cancelled';
-    }
-    this.emit('task.cancel', { task_id: taskId, reason });
-    this._ledger({ type: 'task.cancelled', task_id: taskId, reason });
-    return task;
-  }
-
-  /* ---------------- leases / heartbeat (§4.3) ---------------- */
-
-  /** Shared `phase`/`progress` validation for both heartbeat modes. */
-  _validatePhaseProgress(input) {
-    if (input.phase !== undefined && input.phase !== null && !LEASE_PHASES.includes(input.phase)) {
-      throw new ProtocolError('BAD_REQUEST', 'phase must be preparing|running|finalizing', { phase: input.phase });
-    }
-    if (input.progress !== undefined && input.progress !== null
-      && (typeof input.progress !== 'number' || input.progress < 0 || input.progress > 1)) {
-      throw new ProtocolError('BAD_REQUEST', 'progress must be a number in [0,1]', { progress: input.progress });
-    }
-  }
-
-  /**
-   * v0.3.0 IDLE (diagnostic) heartbeat — an agent with no lease keeps its latency
-   * and liveness visible to other machines.
-   *
-   * This path deliberately NEVER looks at `this.tasks`. That is the whole safety
-   * argument, and it is structural rather than a matter of remembering a rule: an
-   * idle heartbeat cannot renew, resurrect or otherwise touch a lease because it
-   * never obtains one. Without that, an idle ping from a machine whose lease had
-   * expired would flip `expired` back to `running` and manufacture a live task out
-   * of nothing -- a fake "the work is still being done" signal, which is the most
-   * dangerous lie this relay can tell.
-   */
-  diagnosticHeartbeat(input = {}) {
-    const machineId = typeof input.machine_id === 'string' && input.machine_id !== ''
-      ? input.machine_id : null;
-    if (machineId === null) {
-      throw new ProtocolError('BAD_REQUEST', 'machine_id is required', {});
-    }
-    if (!this.devices.has(machineId)) {
-      throw new ProtocolError('NOT_FOUND', 'unknown machine_id', { machine_id: machineId });
-    }
-    this._validatePhaseProgress(input);
-
-    const device = this.touchDevice(machineId);
-    this.recordHeartbeatMetrics(machineId, input);
-    return {
-      // No lease is involved, and the response says so instead of inventing one.
-      lease_until: null,
-      cancel: false,
-      diagnostic: true,
-      machine_id: machineId,
-      rtt_ms: device?.rtt_ms ?? null,
-    };
-  }
-
-  /**
-   * §4.3 POST /v1/heartbeat — renews the lease using SERVER time only.
-   *
-   * Two modes since v0.3.0:
-   *   - `task_id` present            -> LEASE heartbeat (unchanged §4.3 behaviour)
-   *   - `diagnostic: true`, no task  -> IDLE heartbeat (diagnostics only, no lease)
-   *   - neither                      -> 400. A heartbeat that silently renewed
-   *     nothing would let an agent whose `task_id` went missing stop renewing while
-   *     believing it was fine, ending in a falsely `expired` task. §0 forbids
-   *     silent degradation, so this is loud.
-   *
-   * @returns {{lease_until:string|null, cancel:boolean, phase?:string, progress?:number, diagnostic?:boolean}}
-   */
-  heartbeat(input = {}) {
-    const hasTask = typeof input.task_id === 'string' && input.task_id !== '';
-    if (!hasTask) {
-      if (input.diagnostic !== true) {
-        throw new ProtocolError('BAD_REQUEST',
-          'a heartbeat must carry task_id (lease renewal) or diagnostic:true (idle diagnostics); '
-          + 'refusing to treat a missing task_id as a no-op renewal', {
-            received_keys: Object.keys(input).sort(),
-          });
-      }
-      return this.diagnosticHeartbeat(input);
-    }
-    if (input.diagnostic === true) {
-      // task_id wins: a heartbeat that names a task IS a lease heartbeat.
-      // (documented; the flag is simply redundant here)
-    }
-    return this.leaseHeartbeat(input);
-  }
-
-  leaseHeartbeat(input = {}) {
-    const task = this.requireTask(input.task_id);
-    const lease = task.leases.get(input.machine_id);
-    if (!lease) {
-      throw new ProtocolError('NOT_FOUND', 'no lease for this machine on this task', {
-        task_id: input.task_id, machine_id: input.machine_id,
-      });
-    }
-    this._validatePhaseProgress(input);
-
-    const now = this.nowMs();
-    this.touchDevice(input.machine_id);
-    this.recordHeartbeatMetrics(input.machine_id, input, now);
-
-    if (task.cancelled) {
-      return { lease_until: rfc3339(lease.lease_until_ms), cancel: true, reason: task.cancel_reason };
-    }
-
-    // §4.3: once halt=now has handed this index to another attempt, the old owner
-    // must stop — a late heartbeat from the expired machine is not a valid re-claim.
-    if (lease.state === 'expired' && task.attempt > lease.attempt) {
-      return { lease_until: rfc3339(lease.lease_until_ms), cancel: true, reason: 'LEASE_EXPIRED_TAKEN_OVER' };
-    }
-
-    const stateBefore = lease.state;
-    lease.last_heartbeat_ms = now;
-    lease.lease_until_ms = now + this.leaseWindowMs();
-    lease.heartbeat_count += 1;
-    if (input.phase !== undefined && input.phase !== null) lease.phase = input.phase;
-    if (input.progress !== undefined && input.progress !== null) lease.progress = input.progress;
-    if (Number.isInteger(input.attempt) && input.attempt >= 1) lease.attempt = input.attempt;
-    if (lease.state === 'queued' || lease.state === 'offered') lease.state = 'running';
-    // A live heartbeat is stronger evidence than a timer: with halt=never nobody took
-    // the work away, so the late-but-alive agent re-claims its own lease.
-    if (lease.state === 'expired') { lease.state = 'running'; lease.expired_at_ms = null; }
-
-    // §7 ledger records lease STATE changes, not every 10s heartbeat.
-    if (lease.state !== stateBefore) this._ledgerLease(task, lease);
-
-    return { lease_until: rfc3339(lease.lease_until_ms), cancel: false, phase: lease.phase, progress: lease.progress };
-  }
-
-  /** §4.3: expiry is decided by Rabbit's clock only. */
-  isLeaseExpired(lease, nowMs = this.nowMs()) {
-    if (!ACTIVE_LEASE_STATES.includes(lease.state)) return false;
-    return nowMs >= lease.lease_until_ms;
-  }
-
-  /**
-   * §4.3 expiry sweep.
-   *  - halt=never → book-keeping only, task is marked `partial`
-   *  - halt=now   → notify remaining machines immediately that they may take over
-   */
-  sweepExpired(nowMs = this.nowMs()) {
-    const expired = [];
-    for (const task of this.tasks.values()) {
-      if (task.cancelled) continue;
-      let changed = false;
-      for (const lease of task.leases.values()) {
-        if (!this.isLeaseExpired(lease, nowMs)) continue;
-        lease.state = 'expired';
-        lease.expired_at_ms = nowMs;
-        changed = true;
-        expired.push({ task, lease });
-        this._ledgerLease(task, lease);
-        this.emit('notice', {
-          level: 'warn',
-          code: 'LEASE_EXPIRED',
-          message: `lease expired: machine=${lease.machine_id} task=${task.task_id} attempt=${lease.attempt}`,
-          task_id: task.task_id,
-          machine_id: lease.machine_id,
-        });
-        if (task.halt === 'now') {
-          task.attempt += 1;
-          this._takeover(task, lease, nowMs);
-        }
-      }
-      if (changed) task.degraded = 'partial';
-    }
-    return expired;
-  }
-
-  /**
-   * §4.3 `halt=now`: "立即通知其他机器可接管".
-   *
-   * v0.0.1's PROTOCOL defines no per-index lease reassignment, so takeover is
-   * implemented as: re-offer the freed `index` (attempt+1) to every live machine
-   * that is idle — no lease yet, or a lease still queued/offered — and broadcast a
-   * notice. Machines already `running` are never re-offered, to avoid double
-   * execution of the same index.
-   */
-  _takeover(task, expiredLease, nowMs = this.nowMs()) {
-    const candidates = [];
-    for (const device of this.devices.values()) {
-      if (device.machine_id === expiredLease.machine_id) continue;
-      const lease = task.leases.get(device.machine_id);
-      if (lease && !['queued', 'offered'].includes(lease.state)) continue;
-      if (!lease && gateMachine(task, device)) continue;
-      candidates.push({ device, lease: lease ?? null });
-    }
-
-    for (const { device, lease } of candidates) {
-      const target = lease ?? {
-        machine_id: device.machine_id,
-        machine_name: device.machine_name,
-        index: expiredLease.index,
-        attempt: task.attempt,
-        state: 'queued',
-        refusal_reason: null,
-        refusal_detail: null,
-        dedupe_key: null,
-        last_heartbeat_ms: nowMs,
-        claimed_at_ms: nowMs,
-        lease_until_ms: nowMs + this.leaseWindowMs(),
-        phase: null,
-        progress: null,
-        offered_seq: null,
-        expired_at_ms: null,
-        finished_at_ms: null,
-        heartbeat_count: 0,
-      };
-      target.index = expiredLease.index;
-      target.attempt = task.attempt;
-      target.dedupe_key = computeDedupeKey(task.task_id, target.index, task.command_hash, task.base_tree);
-      task.leases.set(device.machine_id, target);
-      this.emitOffer(task, target);
-      this._ledgerLease(task, target);
-    }
-
-    this.emit('notice', {
-      level: 'info',
-      code: candidates.length > 0 ? 'LEASE_TAKEOVER' : 'LEASE_TAKEOVER_UNAVAILABLE',
-      message: candidates.length > 0
-        ? `task ${task.task_id} index ${expiredLease.index} re-offered at attempt ${task.attempt} to: `
-          + candidates.map((c) => c.device.machine_id).join(',')
-        : `task ${task.task_id} index ${expiredLease.index} has no idle machine to take over`,
-      task_id: task.task_id,
-    });
-    return candidates.map((c) => c.device.machine_id);
-  }
-
-  /* ---------------- results (§5) ---------------- */
-
-  static instanceKey(machineId, dedupeKey, attempt) {
-    return `${machineId}${INSTANCE_SEP}${dedupeKey}${INSTANCE_SEP}${attempt}`;
-  }
-
-  /**
-   * §5 result envelope validation.
-   * Missing §5.1 required fields do NOT reject the frame — they make the result
-   * `unverifiable` (§5.1 "缺一即 unverifiable").
-   */
-  static validateEnvelope(envelope) {
-    const missing = [];
-    if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) {
-      return { missing: [...REQUIRED_ENVELOPE_FIELDS], malformed: true };
-    }
-    for (const field of REQUIRED_ENVELOPE_FIELDS) {
-      if (!(field in envelope) || envelope[field] === undefined) missing.push(field);
-    }
-    const problems = [];
-    if ('status' in envelope && !RESULT_STATUSES.includes(envelope.status)) {
-      problems.push(`status must be one of ${RESULT_STATUSES.join('|')}`);
-    }
-    if (envelope.status === 'refused' && !envelope.refusal_reason) {
-      problems.push('refusal_reason is required when status=refused');
-    }
-    if ('warnings' in envelope && !Array.isArray(envelope.warnings)) problems.push('warnings must be string[]');
-    return { missing, problems };
-  }
-
-  /**
-   * §1 idempotent POST /v1/result.
-   *
-   * NOTE (contract ambiguity, see report): §4.4 `dedupe_key` deliberately excludes
-   * `machine_id`/`attempt`, but §6.3 aggregates results from *several* machines in
-   * replicate mode — they all share one dedupe_key. Deduping purely on dedupe_key
-   * would silently drop every machine's result but the first. We therefore key the
-   * idempotency check on (machine_id, dedupe_key, attempt): an identical redelivery
-   * is `deduped:true`, distinct machines/attempts are all recorded.
-   */
-  submitResult(envelope = {}) {
-    const { missing, problems, malformed } = RabbitState.validateEnvelope(envelope);
-    if (malformed) throw new ProtocolError('BAD_REQUEST', 'result must be a JSON object');
-
-    /**
-     * v0.4.0: `transport` / `p2p` are OPTIONAL envelope fields, and they are validated as values
-     * rather than added to the §5.1 required set. A v0.3.9 agent sends neither and must keep
-     * working unchanged; an agent that sends `transport: 'satellite'` is refused by name instead of
-     * storing a value the report would then show as a path that does not exist.
-     */
-    RabbitState.validateTransportFields(envelope);
-
-    const taskId = envelope.task_id;
-    if (typeof taskId !== 'string' || taskId.length === 0) {
-      throw new ProtocolError('BAD_REQUEST', 'task_id is required');
-    }
-    const task = this.tasks.get(taskId);
-    if (!task) throw new ProtocolError('NOT_FOUND', 'unknown task_id', { task_id: taskId });
-
-    const machineId = typeof envelope.machine_id === 'string' ? envelope.machine_id : null;
-    const dedupeKey = typeof envelope.dedupe_key === 'string' && envelope.dedupe_key
-      ? envelope.dedupe_key : null;
-    const attempt = Number.isInteger(envelope.attempt) && envelope.attempt >= 1 ? envelope.attempt : 1;
-
-    if (dedupeKey === null) {
-      // Cannot dedupe without a key; still record it, as unverifiable.
-      missing.push('dedupe_key');
-    }
-    const instanceKey = RabbitState.instanceKey(machineId ?? '<unknown>', dedupeKey ?? '<none>', attempt);
-
-    // §4.4 sanity check against the lease this machine actually holds. Booked as a
-    // problem instead of a hard rejection so a buggy client cannot lose its result.
-    const leaseForMachine = machineId ? task.leases.get(machineId) : null;
-    if (leaseForMachine?.dedupe_key && dedupeKey && leaseForMachine.dedupe_key !== dedupeKey) {
-      problems.push('dedupe_key does not match the §4.4 formula for this lease');
-    }
-
-    if (this.results.has(instanceKey)) {
-      const prior = this.results.get(instanceKey);
-      return { deduped: true, task_id: taskId, dedupe_key: dedupeKey, seq: prior.seq };
-    }
-
-    const now = this.nowMs();
-    let envelopeShaOk = null;
-    if (typeof envelope.envelope_sha256 === 'string') {
-      const { envelope_sha256: _drop, ...rest } = envelope;
-      envelopeShaOk = sha256Hex(jcs(rest)) === envelope.envelope_sha256;
-    }
-
-    const record = {
-      envelope,
-      machine_id: machineId,
-      dedupe_key: dedupeKey,
-      attempt,
-      instance_key: instanceKey,
-      received_at_ms: now,
-      validation: {
-        missing: [...new Set(missing)],
-        problems,
-        envelope_sha256_ok: envelopeShaOk,
-      },
-    };
-
-    const effectiveStatus = record.validation.missing.length > 0 ? 'unverifiable' : envelope.status;
-
-    const seq = this.nextSeq();
-    record.seq = seq;
-    record.effective_status = effectiveStatus;
-    this.results.set(instanceKey, record);
-
-    if (machineId) {
-      const lease = task.leases.get(machineId);
-      if (lease) {
-        lease.state = effectiveStatus === 'refused' ? 'refused' : 'done';
-        if (effectiveStatus === 'refused' && !lease.refusal_reason) {
-          lease.refusal_reason = envelope.refusal_reason ?? 'REFUSED';
-        }
-        lease.finished_at_ms = now;
-        lease.attempt = attempt;
-      }
-      this.touchDevice(machineId);
-    }
-    task.result_seqs.push(seq);
-
-    this.emit('task.result', {
-      task_id: taskId,
-      dedupe_key: dedupeKey,
-      attempt,
-      index: envelope.index ?? null,
-      status: effectiveStatus,
-      machine_id: machineId,
-      deduped: false,
-      validation_errors: record.validation.missing,
-    });
-
-    // §7: results go into the ledger so the dedupe index survives a restart.
-    this._ledger({ type: 'result.stored', task_id: taskId, machine_id: machineId, result: record });
-    if (machineId) {
-      const changed = task.leases.get(machineId);
-      if (changed) this._ledgerLease(task, changed);
-    }
-
-    return { deduped: false, task_id: taskId, dedupe_key: dedupeKey, seq, _instanceKey: instanceKey };
-  }
-
-  /** All recorded results for a task, keyed by machine_id (later attempts win). */
-  taskResults(taskId) {
-    const task = this.tasks.get(taskId);
-    if (!task) return new Map();
-    const out = new Map();
-    for (const rec of this.results.values()) {
-      if (rec.envelope.task_id !== taskId) continue;
-      const prev = out.get(rec.machine_id);
-      if (!prev || rec.received_at_ms >= prev.received_at_ms) out.set(rec.machine_id, rec);
-    }
-    return out;
-  }
-
-  /** Global dedupe book-keeping: dedupe_key -> instances seen. */
-  dedupeReport() {
-    const out = {};
-    for (const rec of this.results.values()) {
-      if (!rec.dedupe_key) continue;
-      out[rec.dedupe_key] = out[rec.dedupe_key] ?? [];
-      out[rec.dedupe_key].push({
-        machine_id: rec.machine_id,
-        attempt: rec.attempt,
-        received_at: rfc3339(rec.received_at_ms),
-      });
-    }
-    return out;
-  }
-
-  /* ---------------- serialization ---------------- */
-
-  stats() {
-    return {
-      protocol_version: PROTOCOL_VERSION,
-      seq: this.seq,
-      buffered_events: this.buffer.length,
-      devices: this.devices.size,
-      tasks: this.tasks.size,
-      results: this.results.size,
-      pairing_codes: [...this.pairingCodes.values()].filter((c) => !c.used && this.nowMs() < c.expires_at_ms).length,
-      uptime_ms: this.nowMs() - this.startedAtMs,
-    };
-  }
-}
-
-export default RabbitState;
+/**
+ * W2M Rabbit relay — in-memory state machine.
+ *
+ * Contract: E:\DS\_work\w2m\PROTOCOL.md (protocol_version = 1, frozen).
+ * This module is intentionally PURE LOGIC:
+ *   - no network, no filesystem, no timers
+ *   - time is injectable via `now()` (required for lease-expiry unit tests)
+ *   - randomness is injectable for deterministic tests
+ *
+ * Persistence: none. All state is in-memory and is lost on restart (v0.0.1 scope);
+ * there is intentionally no snapshot/serialization hook yet.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+
+// v0.7.7: fleet scoping. Imported rather than inlined so the rule has one home with its own
+// exhaustive tests — three lines inside this object would be untestable without a live relay.
+import { targetsFor } from '../chatops/fleet-wiring.mjs';
+import { fleetForPairingCode, deviceFleetFields } from '../chatops/fleet-wiring.mjs';
+
+export const PROTOCOL_VERSION = 1;
+
+/**
+ * PROTOCOL §1 table + §7 code table, plus the two v0.1.2 additions:
+ * `OPERATOR_REQUIRED` (§5.2 → 401) and `RATE_LIMITED` (§6 → 429).
+ * A code missing from this map silently degrades to HTTP 500 via
+ * `ProtocolError`, which keeps the right error code but lies about the status.
+ */
+export const ERROR_STATUS = Object.freeze({
+  UNAUTHORIZED: 401,
+  BAD_REQUEST: 400,
+  NOT_FOUND: 404,
+  PAIRING_INVALID: 400,
+  PAIRING_EXPIRED: 400,
+  TASK_EXISTS: 409,
+  FRAME_TOO_LARGE: 413,
+  NO_ONLINE_DEVICE: 503,
+  INTERNAL: 500,
+  OPERATOR_REQUIRED: 401, // v0.1.2 §5.2
+  RATE_LIMITED: 429,      // v0.1.2 §6
+
+  /* v0.3.0 §9 request signing. Every client-side signature failure is a 401.
+   * `SIGNING_NOT_CONFIGURED` is deliberately NOT 401: the relay was started with
+   * `--require-signature` but no secret, so the fault is the relay's own
+   * configuration. Reporting that as 401 would send every operator to debug the
+   * client -- the one side that is not broken. 500 rather than 503 because
+   * retrying never fixes a missing configuration, so nothing should be invited to
+   * retry. */
+  SIGNATURE_REQUIRED: 401,
+  SIGNATURE_INCOMPLETE: 401,
+  SIGNATURE_MISMATCH: 401,
+  SIGNATURE_BAD_TIMESTAMP: 401,
+  SIGNATURE_BAD_NONCE: 401,
+  SIGNATURE_EXPIRED: 401,
+  SIGNATURE_REPLAY: 401,
+  SIGNING_NOT_CONFIGURED: 500,
+});
+
+/** §5.1 required envelope fields — missing any one means `unverifiable`. */
+export const REQUIRED_ENVELOPE_FIELDS = Object.freeze([
+  'envelope_version', 'task_id', 'attempt', 'dedupe_key', 'machine_id', 'machine_name',
+  'platform', 'caps', 'index', 'index_total', 'mode', 'cwd_rel', 'base_commit', 'base_tree',
+  'pre_tree_fingerprint', 'post_tree_fingerprint', 'fingerprint_algo', 'fingerprint_error',
+  'head_commit', 'dirty_before', 'command_argv', 'command_hash', 'shell_id',
+  'started_at', 'ended_at', 'duration_ms', 'exit_code', 'status', 'refusal_reason',
+  'stdout_sha256', 'stdout_bytes', 'stderr_sha256', 'stderr_bytes', 'warnings',
+  'envelope_sha256',
+]);
+
+/** §5.3 comparable fields — the ONLY fields that take part in consistency judgement. */
+export const COMPARABLE_FIELDS = Object.freeze([
+  'task_id', 'index', 'index_total', 'mode', 'cwd_rel', 'base_commit', 'base_tree',
+  'pre_tree_fingerprint', 'fingerprint_algo', 'fingerprint_error', 'head_commit',
+  'command_hash', 'shell_id', 'exit_code', 'status', 'refusal_reason',
+  'stdout_sha256', 'stdout_bytes', 'stdout_normalized_sha256',
+  'stderr_sha256', 'artifacts', 'diff_numstat', 'tests', 'semantic_counts', 'warnings',
+]);
+
+/** §5.1 status enum. */
+export const RESULT_STATUSES = Object.freeze([
+  'ok', 'nonzero_exit', 'timeout', 'crashed', 'refused', 'unverifiable',
+]);
+
+export const FAILURE_STATUSES = Object.freeze(['nonzero_exit', 'timeout', 'crashed']);
+
+/** §4.3 phase enum. */
+export const LEASE_PHASES = Object.freeze(['preparing', 'running', 'finalizing']);
+
+/** Lease states that can still be expired / renewed. */
+export const ACTIVE_LEASE_STATES = Object.freeze(['queued', 'offered', 'running']);
+
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000; // §4.3: agent heartbeats every 10s
+export const DEFAULT_MISSED_HEARTBEATS = 2;          // §4.3: 2 missed cycles = 20s
+export const DEFAULT_LEASE_GRACE_MS = 30_000;        // §4.3: + grace 30s
+/**
+ * v0.4.0: the bounded hold on the relay's own offer when a dispatcher is pushing it directly.
+ *
+ * Sized against what it has to cover: one punch round trip (measured 15-370 ms on the reference
+ * networks), the frame's delivery, and the executor's first heartbeat POST — all on a host that may
+ * be busy. 1.2 s was the first guess and it was too tight: measured on a 1-vCPU shared host, two
+ * agent tests saw the relay's copy overtake the direct one, which for `p2pMode: direct` means a
+ * refusal of an offer that was about to arrive. 3 s covers a slow host with room to spare.
+ *
+ * The cost is honest and bounded: a punch that fails delays the relay's copy by up to this much,
+ * once per task. Nothing else waits on it.
+ */
+export const DEFAULT_P2P_OFFER_GRACE_MS = 3_000;
+export const DEFAULT_PAIRING_TTL_MS = 24 * 60 * 60 * 1000; // §2.2: 24h
+export const DEFAULT_EVENT_BUFFER_SIZE = 1000;       // §requirement: keep last 1000 events
+export const MAX_FRAME_BYTES = 64 * 1024;            // 64 KiB single frame
+export const SHELL_ID_DIRECT = 'direct-exec';        // §5.1: v0.0.1 only direct exec
+/** v0.3.0: RTT sanity ceiling — anything above 24h is treated as a broken value. */
+export const MAX_RTT_MS = 24 * 60 * 60 * 1000;
+/** v0.3.0: an RTT measurement older than this is reported as stale.
+ *  Must stay comfortably ABOVE the idle-heartbeat interval (60s): at 1x the value
+ *  would flip stale just before every refresh and flap, which would make
+ *  `rtt_stale === false` useless as a "trust this number" predicate. 3x gives two
+ *  consecutive missed idle heartbeats of margin. See PROTOCOL-v0.3.0.md §7. */
+export const DEFAULT_RTT_STALE_MS = 180_000;
+/** v0.3.0: recommended cadence for an agent with no lease (reference for the agent side). */
+export const DEFAULT_IDLE_HEARTBEAT_MS = 60_000;
+export const ENVELOPE_VERSION = '1.0';
+export const FINGERPRINT_ALGO = 'git-temp-index-tree/v1';
+
+/* ------------------------------------------------------------------ */
+/* Errors                                                              */
+/* ------------------------------------------------------------------ */
+
+export class ProtocolError extends Error {
+  constructor(code, message, detail = {}) {
+    super(message);
+    this.name = 'ProtocolError';
+    this.code = code;
+    this.detail = detail;
+    this.status = ERROR_STATUS[code] ?? 500;
+  }
+  toBody() {
+    return { error: { code: this.code, message: this.message, detail: this.detail } };
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Small pure helpers                                                  */
+/* ------------------------------------------------------------------ */
+
+export function sha256Hex(input) {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+/** RFC 8785-ish canonical JSON (JCS): sorted keys, no whitespace. */
+export function jcs(value) {
+  if (value === null) return 'null';
+  const t = typeof value;
+  if (t === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
+  if (t === 'boolean') return value ? 'true' : 'false';
+  if (t === 'string') return JSON.stringify(value);
+  if (t === 'undefined' || t === 'function' || t === 'symbol') return 'null';
+  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined ? 'null' : jcs(v))).join(',')}]`;
+  if (t === 'object') {
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${jcs(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(String(value));
+}
+
+/**
+ * Upper bound on the stages a `pipeline` may contain.
+ *
+ * Each stage is another command run on someone else's machine, so an unbounded list is an unbounded
+ * amount of work created by one request. The limit is generous for the intended use (build, test,
+ * package) and exists so the failure is a clear refusal rather than a fleet-wide surprise.
+ */
+export const MAX_PIPELINE_STAGES = 16;
+
+/**
+ * v0.4.0: upper bound on `POST /v1/task`'s `origin_machine_id`.
+ *
+ * A machine id is an identifier, not a payload: 128 characters is far beyond any id this system
+ * mints, and the ceiling is what stops the field from becoming an unbounded free-text channel into
+ * every offer frame the relay emits.
+ */
+export const MAX_ORIGIN_MACHINE_ID_LENGTH = 128;
+
+/**
+ * v0.4.0: the P2P modes a task may be dispatched under (§1 of the frozen v0.4.0 contract).
+ *
+ * Mirrored here rather than imported from `src/agent/p2p-node.mjs`: the relay is a standalone
+ * process that must not depend on agent code, and a mode list is three strings. A value outside
+ * this list is a configuration error, never a silent fall back to the default.
+ */
+export const P2P_MODES = Object.freeze(['auto', 'direct', 'relay']);
+
+/**
+ * v0.4.0: how a result travelled — the direct P2P channel or the relay.
+ *
+ * A **transport is not a result**: how an envelope arrived must never take part in the consistency
+ * judgement (§5 of the contract), or two machines that produced byte-identical output would be
+ * reported `divergent` merely because one of them punched a hole. Hence: not required, not
+ * comparable, and absent on every v0.3.9 envelope.
+ */
+export const TRANSPORT_VALUES = Object.freeze(['p2p', 'relay']);
+
+/** §4.4 helper: command_hash = sha256(JCS(argv)+"|"+shell_id+"|"+cwd_rel). */
+export function computeCommandHash(commandArgv, shellId = SHELL_ID_DIRECT, cwdRel = '.') {
+  return sha256Hex(`${jcs(commandArgv)}|${shellId}|${cwdRel}`);
+}
+
+/**
+ * `command_hash` for a whole pipeline.
+ *
+ * The hash must bind **every** stage, not just the first. Bound to stage 0 alone, two pipelines that
+ * differ after the first stage would carry the same hash -- so an envelope produced by the wrong
+ * chain would still verify, and making "the machine ran what I asked" checkable is the entire point
+ * of this field. Each stage's cwd participates for the same reason.
+ *
+ * The `|pipeline` suffix means this can never collide with a single-command hash: the two hash over
+ * different shapes, and that difference is deliberate rather than incidental.
+ */
+export function computePipelineCommandHash(stages, shellId = SHELL_ID_DIRECT) {
+  const canonical = stages.map((s) => ({
+    command_argv: s.command_argv,
+    cwd_rel: s.cwd_rel ?? '.',
+    continue_on_failure: s.continue_on_failure === true,
+  }));
+  return sha256Hex(`${jcs(canonical)}|${shellId}|pipeline`);
+}
+
+/** §4.4: dedupe_key = sha256(task_id + "|" + index + "|" + command_hash + "|" + base_tree). */
+export function computeDedupeKey(taskId, index, commandHash, baseTree) {
+  return sha256Hex(`${taskId}|${index}|${commandHash}|${baseTree}`);
+}
+
+/** Epoch ms -> RFC3339 UTC, second precision (matches the PROTOCOL examples). */
+export function rfc3339(ms) {
+  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+export function isRfc3339(value) {
+  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(value);
+}
+
+export function deepEqual(a, b) {
+  return jcs(a === undefined ? null : a) === jcs(b === undefined ? null : b);
+}
+
+function normalizeNow(now) {
+  if (typeof now !== 'function') return () => Date.now();
+  return () => {
+    const v = now();
+    if (typeof v === 'number') return v;
+    if (v instanceof Date) return v.getTime();
+    return Date.parse(v);
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* ULID                                                                */
+/* ------------------------------------------------------------------ */
+
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+function encodeBig(value, len) {
+  let out = '';
+  let v = value;
+  for (let i = 0; i < len; i += 1) {
+    out = CROCKFORD[Number(v & 31n)] + out;
+    v >>= 5n;
+  }
+  return out;
+}
+
+export function createIdFactory() {
+  let lastMs = -1;
+  let lastRand = 0n;
+  return function nextId(nowMs = Date.now()) {
+    const bytes = randomBytes(10);
+    let rand = 0n;
+    for (const b of bytes) rand = (rand << 8n) | BigInt(b);
+    if (nowMs === lastMs) rand = (lastRand + 1n) & ((1n << 80n) - 1n);
+    lastMs = nowMs;
+    lastRand = rand;
+    return encodeBig(BigInt(nowMs), 10) + encodeBig(rand, 16);
+  };
+}
+
+export function ulid(nowMs = Date.now()) {
+  return createIdFactory()(nowMs);
+}
+
+/* ------------------------------------------------------------------ */
+/* Version / capability gate (§6.1)                                    */
+/* ------------------------------------------------------------------ */
+
+function parseVersion(text) {
+  if (typeof text !== 'string') return null;
+  const m = text.trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0), Number(m[4] ?? 0)];
+}
+
+function cmpVersion(a, b) {
+  for (let i = 0; i < 4; i += 1) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Minimal semver-range check used by the §6.1 capability gate.
+ * Supports bare versions and comma/space separated `>= > <= < = ==` conjunctions.
+ * Unparseable ranges are treated as NOT satisfied (never silently pass).
+ */
+export function satisfiesRange(version, range) {
+  const v = parseVersion(version);
+  if (v === null) return false;
+  if (typeof range !== 'string') return false;
+  const parts = range.split(/[\s,]+/).filter(Boolean);
+  if (parts.length === 0) return false;
+  for (const part of parts) {
+    const m = part.match(/^(>=|<=|==|=|>|<)?\s*(.+)$/);
+    if (!m) return false;
+    const op = m[1] ?? '=';
+    const target = parseVersion(m[2]);
+    if (target === null) return false;
+    const c = cmpVersion(v, target);
+    if (op === '>=' && c < 0) return false;
+    if (op === '<=' && c > 0) return false;
+    if (op === '>' && c <= 0) return false;
+    if (op === '<' && c >= 0) return false;
+    if ((op === '=' || op === '==') && c !== 0) return false;
+  }
+  return true;
+}
+
+function machineWritable(caps) {
+  if (!caps || typeof caps !== 'object') return false;
+  if (caps.write === false || caps.writable === false || caps.write_allowed === false) return false;
+  if (caps.read_only === true || caps.readonly === true || caps.ro_mount === true) return false;
+  return true;
+}
+
+/**
+ * §6.1 capability gate, evaluated per machine BEFORE dispatch.
+ * @returns {null | {status:'refused', refusal_reason:string, detail:object}}
+ */
+export function gateMachine(task, machine) {
+  const caps = machine?.caps ?? {};
+  const req = task.requirements ?? {};
+
+  if (req.platform && Array.isArray(req.platform) && req.platform.length > 0) {
+    const os = String(machine?.platform?.os ?? '').toLowerCase();
+    if (!req.platform.map((p) => String(p).toLowerCase()).includes(os)) {
+      return { status: 'refused', refusal_reason: 'PLATFORM_MISMATCH', detail: { os, want: req.platform } };
+    }
+  }
+
+  const toolchain = req.toolchain ?? {};
+  for (const [tool, range] of Object.entries(toolchain)) {
+    const declared = caps[tool];
+    if (declared === null || declared === undefined || declared === '') {
+      return {
+        status: 'refused',
+        refusal_reason: `MISSING_${String(tool).toUpperCase()}`,
+        detail: { tool, want: range, have: declared ?? null },
+      };
+    }
+    if (typeof range === 'string' && !satisfiesRange(declared, range)) {
+      return {
+        status: 'refused',
+        refusal_reason: `MISSING_${String(tool).toUpperCase()}`,
+        detail: { tool, want: range, have: declared },
+      };
+    }
+  }
+
+  if (task.write === true && !machineWritable(caps)) {
+    return { status: 'refused', refusal_reason: 'READ_ONLY_MACHINE', detail: { caps } };
+  }
+
+  return null;
+}
+
+/* ------------------------------------------------------------------ */
+/* RabbitState                                                         */
+/* ------------------------------------------------------------------ */
+
+const INSTANCE_SEP = '\u0000';
+
+export class RabbitState {
+  constructor(options = {}) {
+    this._now = normalizeNow(options.now);
+    this._idFactory = options.idFactory ?? createIdFactory();
+    this._randomToken = options.tokenFactory ?? (() => randomBytes(24).toString('hex'));
+    this._randomChars = options.randomChars
+      ?? ((n) => { const a = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'; const b = randomBytes(n); let s = ''; for (let i = 0; i < n; i += 1) s += a[b[i] % a.length]; return s; });
+
+    this.protocolVersion = PROTOCOL_VERSION;
+    this.eventBufferSize = options.eventBufferSize ?? DEFAULT_EVENT_BUFFER_SIZE;
+    /**
+     * v0.7.7: the fleet this relay serves, or null for a relay that serves every device.
+     *
+     * **Null is the migration-safe default and is what the shared relay runs today.** With it,
+     * task targeting behaves exactly as it did before this release, so deploying cannot be an
+     * outage. Set it (via `--fleet <id>` or `fleetId`) and the relay becomes scoped: a device
+     * with a `fleet_id` reaches only its own fleet, and a device with none reaches nothing.
+     *
+     * This is the relay's *own* fleet, not a device's. A device carries its own `fleet_id`, which
+     * the relay wrote at pairing time from the pairing code.
+     */
+    this.fleetId = typeof options.fleetId === 'string' && options.fleetId !== '' ? options.fleetId : null;
+    this.pairingTtlMs = options.pairingTtlMs ?? DEFAULT_PAIRING_TTL_MS;
+    /** When true one code stays valid for its whole TTL instead of rotating. */
+    this.pairingCodeReusable = options.pairingCodeReusable === true;
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.missedHeartbeats = options.missedHeartbeats ?? DEFAULT_MISSED_HEARTBEATS;
+    this.leaseGraceMs = options.leaseGraceMs ?? DEFAULT_LEASE_GRACE_MS;
+    /**
+     * v0.4.0: how long the relay holds its own offer back when the dispatcher says it will push the
+     * offer over the direct path (`origin_machine_id` + `p2p.mode`).
+     *
+     * Without this, the direct path could never win: the relay's offer goes out over an SSE stream
+     * that is already open, while a punch costs at least one round trip, so the relay copy would
+     * arrive first essentially always and `transport` would read `relay` even on a network where
+     * the punch succeeded. Measured on loopback, and it is exactly what the first version of this
+     * release did.
+     *
+     * The hold is bounded and self-healing: the executor renews its lease (a heartbeat) the moment
+     * it starts work on the direct copy, which moves the lease out of `queued`, and the deferred
+     * offer is then dropped. If the punch fails, nothing renews the lease and the relay offers
+     * normally once the grace expires -- so a failed punch costs this much latency and nothing else.
+     */
+    this.p2pOfferGraceMs = Number.isFinite(options.p2pOfferGraceMs) && options.p2pOfferGraceMs >= 0
+      ? options.p2pOfferGraceMs
+      : DEFAULT_P2P_OFFER_GRACE_MS;
+    /** Deferred offers, keyed `task_id:machine_id`, so they can be cleared on close(). */
+    this._pendingOffers = new Map();
+    /** v0.3.0: age beyond which a reported RTT is flagged stale. */
+    this.rttStaleMs = Number.isFinite(options.rttStaleMs) ? options.rttStaleMs : DEFAULT_RTT_STALE_MS;
+
+    this.startedAtMs = this._now();
+    /** v0.1.2 §8.3: random per-process id; a change tells clients the relay restarted. */
+    this.relayId = options.relayId ?? randomBytes(8).toString('hex');
+    /** v0.1.2 §7: optional injected Persistence instance (state.mjs never touches fs itself). */
+    this._persist = options.persistence ?? null;
+    /** True while replaying a ledger — suppresses event emission and re-persistence. */
+    this._restoring = false;
+    /** Ledger entries that could not be replayed. */
+    this.replayWarnings = [];
+    this.seq = 0;
+    /** @type {{seq:number,event:object,target:string|null}[]} ring buffer, last N events */
+    this.buffer = [];
+    this.devices = new Map();      // machine_id -> device
+    this.tokens = new Map();       // device_token -> machine_id
+    this.tasks = new Map();        // task_id -> task
+    this.results = new Map();      // instanceKey -> {envelope, machine_id, received_at_ms, ...}
+    this.pairingCodes = new Map(); // code -> {code, created_at_ms, expires_at_ms, used}
+    this._listeners = new Set();
+  }
+
+  /* ---------------- clock / ids ---------------- */
+
+  nowMs() { return this._now(); }
+  nowIso() { return rfc3339(this.nowMs()); }
+  nextId() { return this._idFactory(this.nowMs()); }
+  newToken() { return this._randomToken(); }
+
+  /** §4.3 lease window = 2 missed heartbeats (20s) + grace (30s) = 50s. */
+  leaseWindowMs() { return this.heartbeatIntervalMs * this.missedHeartbeats + this.leaseGraceMs; }
+
+  /* ---------------- persistence hooks (v0.1.2 §7) ---------------- */
+
+  /** Inject/replace the persistence backend (also used by tests). */
+  setPersistence(persistence) { this._persist = persistence ?? null; return this._persist; }
+
+  /** Snapshot the device table; failures must never break the request path. */
+  _saveDevices() {
+    if (this._restoring || !this._persist) return false;
+    try {
+      return this._persist.saveDevices(this.devices);
+    } catch (err) {
+      this._persist.warn?.('devices.json', `snapshot failed: ${err.message}`);
+      return false;
+    }
+  }
+
+  /** Append one ledger entry; failures must never break the request path. */
+  _ledger(entry) {
+    if (this._restoring || !this._persist) return false;
+    try {
+      const appended = this._persist.append(entry);
+      // v0.6.2: a successful append is what clears a degraded relay, so the outcome has to be
+      // reported back rather than assumed -- otherwise the state could only ever be entered.
+      if (appended) this._persist.noteAppendSuccess?.();
+      return appended;
+    } catch (err) {
+      // Recorded as a state, not merely as a line: this is the one relay failure that keeps serving,
+      // and so the one that is invisible from every other angle (v0.6.2).
+      if (typeof this._persist.noteAppendFailure === 'function') this._persist.noteAppendFailure(err.message);
+      else this._persist.warn?.('ledger.jsonl', `append failed: ${err.message}`);
+      return false;
+    }
+  }
+
+  _ledgerLease(task, lease) {
+    this._ledger({ type: 'lease.changed', task_id: task.task_id, machine_id: lease.machine_id, lease: { ...lease } });
+  }
+
+  /**
+   * v0.1.2 §7 startup recovery: rebuild the device table, token index, tasks,
+   * leases and the result/dedupe index from a devices snapshot + ledger replay.
+   * Never emits events and never writes back what it just read.
+   */
+  restore({ devices = {}, ledger = [] } = {}) {
+    this._restoring = true;
+    try {
+      for (const [machineId, d] of Object.entries(devices)) {
+        if (!d || typeof d !== 'object') continue;
+        const pairedAt = Date.parse(d.paired_at ?? '');
+        const device = {
+          machine_id: machineId,
+          machine_name: typeof d.machine_name === 'string' && d.machine_name ? d.machine_name : machineId,
+          platform: d.platform ?? {},
+          caps: d.caps ?? {},
+          user_id: d.user_id ?? null,
+          device_token: typeof d.device_token === 'string' ? d.device_token : null,
+          paired_at_ms: Number.isFinite(pairedAt) ? pairedAt : this.nowMs(),
+          re_paired: d.re_paired === true,
+          last_seen_at_ms: this.nowMs(),
+          // a snapshot proves the device exists, not that it is connected
+          online: false,
+          streams: 0,
+          // v0.3.0: RTT is volatile and is NEVER restored. Even if a snapshot on
+          // disk happens to carry `rtt_ms`, it is dropped here: after a restart the
+          // relay genuinely does not know the latency any more, and reporting a
+          // pre-restart number as current would be a lie that no reader can detect.
+          rtt_ms: null,
+          rtt_at_ms: null,
+          last_heartbeat_at_ms: null,
+          stream_connects: 0,
+        };
+        this.devices.set(machineId, device);
+        if (device.device_token) this.tokens.set(device.device_token, machineId);
+      }
+
+      let revivedTasks = 0;
+      for (const entry of ledger) {
+        try {
+          if (this._applyLedgerEntry(entry) === true) revivedTasks += 1;
+        } catch (err) {
+          this.replayWarnings.push({ type: entry?.type ?? '<unknown>', message: err.message });
+        }
+      }
+      return { revived_devices: this.devices.size, revived_tasks: revivedTasks };
+    } finally {
+      this._restoring = false;
+    }
+  }
+
+  /** @returns {boolean} true when a new task was created. */
+  _applyLedgerEntry(entry) {
+    if (!entry || typeof entry.type !== 'string') return false;
+    switch (entry.type) {
+      case 'task.created': {
+        const t = entry.task;
+        if (!t || typeof t.task_id !== 'string') return false;
+        const createdAt = Number.isFinite(t.created_at_ms) ? t.created_at_ms : Date.parse(entry.ts ?? '');
+        const task = {
+          task_id: t.task_id,
+          mode: t.mode ?? 'replicate',
+          command_argv: t.command_argv ?? [],
+          cwd_rel: t.cwd_rel ?? '.',
+          index_total: t.index_total ?? 1,
+          timeout_ms: t.timeout_ms ?? 300_000,
+          write: t.write === true,
+          write_scope: t.write_scope ?? [],
+          require_exclusive_write: t.require_exclusive_write === true,
+          base_commit: t.base_commit ?? null,
+          base_tree: t.base_tree ?? null,
+          requirements: t.requirements ?? {},
+          compare_policy: t.compare_policy ?? {},
+          halt: t.halt ?? 'never',
+          created_by: t.created_by ?? null,
+          created_at_ms: Number.isFinite(createdAt) ? createdAt : this.nowMs(),
+          command_hash: t.command_hash ?? null,
+          attempt: t.attempt ?? 1,
+          leases: new Map(),
+          cancelled: false,
+          cancel_reason: null,
+          degraded: t.degraded ?? null,
+          deadline_ms: t.deadline_ms ?? 0,
+          // v0.4.0 routing metadata. Read defensively: a ledger written by v0.3.9 has neither key,
+          // and a replayed task with `null` for both is exactly a v0.3.9 task.
+          origin_machine_id: t.origin_machine_id ?? null,
+          p2p: t.p2p ?? null,
+          result_seqs: [],
+        };
+        for (const lease of entry.leases ?? []) {
+          if (lease && typeof lease.machine_id === 'string') task.leases.set(lease.machine_id, { ...lease });
+        }
+        this.tasks.set(task.task_id, task);
+        return true;
+      }
+      case 'lease.changed': {
+        const task = this.tasks.get(entry.task_id);
+        const lease = task?.leases.get(entry.machine_id);
+        if (!lease) return false;
+        Object.assign(lease, entry.lease ?? {});
+        return false;
+      }
+      case 'result.stored': {
+        const record = entry.result;
+        if (!record || typeof record.instance_key !== 'string') return false;
+        this.results.set(record.instance_key, { ...record });
+        const task = this.tasks.get(record.envelope?.task_id);
+        if (task && Number.isInteger(record.seq)) task.result_seqs.push(record.seq);
+        return false;
+      }
+      case 'task.cancelled': {
+        const task = this.tasks.get(entry.task_id);
+        if (task) {
+          task.cancelled = true;
+          task.cancel_reason = entry.reason ?? null;
+        }
+        return false;
+      }
+      default:
+        return false; // unknown entry type: forward compatible, ignored
+    }
+  }
+
+  /* ---------------- events (§3) ---------------- */
+
+  nextSeq() { this.seq += 1; return this.seq; }
+
+  /** Reserve a seq WITHOUT buffering (used for the per-connection `ready` frame). */
+  reserveSeq() { return this.nextSeq(); }
+
+  onEvent(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  /**
+   * Emit an event: allocates the next global seq, buffers it (ring of N) and
+   * notifies subscribers. `target` is the machine_id the event is addressed to
+   * (null = broadcast). The target is NOT serialized except as `machine_id`.
+   */
+  emit(type, fields = {}, opts = {}) {
+    const target = opts.target ?? null;
+    const seq = this.nextSeq();
+    const event = {
+      type,
+      seq,
+      rabbit_time: this.nowIso(),
+      ...(target ? { machine_id: target } : {}),
+      ...fields,
+    };
+    const entry = { seq, event, target };
+    this.buffer.push(entry);
+    if (this.buffer.length > this.eventBufferSize) {
+      this.buffer.splice(0, this.buffer.length - this.eventBufferSize);
+    }
+    for (const listener of this._listeners) {
+      try { listener(entry); } catch { /* subscriber errors must never break state */ }
+    }
+    return event;
+  }
+
+  oldestBufferedSeq() { return this.buffer.length ? this.buffer[0].seq : this.seq + 1; }
+  /**
+   * Highest seq present in the replay ring (0 when empty).
+   *
+   * Deliberately different from `lastSeq()`: `ready` frames allocate seq numbers
+   * without being buffered, so `lastSeq()` can run ahead of anything a client can
+   * actually replay. Diagnostics that describe the REPLAY WINDOW must use this one.
+   */
+  lastBufferedSeq() { return this.buffer.length ? this.buffer[this.buffer.length - 1].seq : 0; }
+  lastSeq() { return this.seq; }
+
+  /** Replay entries with seq >= from (used by GET /v1/stream?seq=|Last-Event-ID). */
+  replayEntries(from) {
+    return this.buffer.filter((e) => e.seq >= from);
+  }
+
+  eventsSince(from) { return this.replayEntries(from).map((e) => e.event); }
+
+  /* ---------------- pairing (§2) ---------------- */
+
+    /**
+     * Mint a pairing code.
+     *
+     * **v0.7.7: the code carries the relay's fleet.** This is the link that makes the scheme work,
+     * and it is easy to leave out: `pair()` reads the fleet *from the code*, so a code with no
+     * fleet pairs a device into no fleet -- and a device in no fleet reaches nothing on a scoped
+     * relay. `--fleet X` would then have had no effect on anything, silently.
+     *
+     * Defaulting to `this.fleetId` rather than requiring the caller to pass it means there is no
+     * path that mints a fleetless code on a scoped relay. An explicit `fleetId` overrides, which
+     * is what a relay serving several fleets would need.
+     */
+    createPairingCode({ ttlMs = this.pairingTtlMs, fleetId = this.fleetId } = {}) {
+      let code;
+      do { code = `PAIR-${this._randomChars(8)}`; } while (this.pairingCodes.has(code));
+      const now = this.nowMs();
+      this.pairingCodes.set(code, {
+        code,
+        created_at_ms: now,
+        expires_at_ms: now + ttlMs,
+        used: false,
+        // Present as an explicit key even when null, so a code dump shows whether a fleet was
+        // attached rather than leaving it to be inferred from an absent field.
+        fleet_id: typeof fleetId === 'string' && fleetId !== '' ? fleetId : null,
+      });
+      return code;
+    }
+
+  /** Revoke every outstanding code and mint a new one. */
+  rotatePairingCode(opts) {
+    for (const rec of this.pairingCodes.values()) rec.used = true;
+    return this.createPairingCode(opts);
+  }
+
+  /**
+   * Register an externally supplied code (`--pairing-code <c>`).
+   *
+   * v0.1.2 BUG-1: assigning the code to `relay.pairingCode` without registering it
+   * advertised a code that `/v1/pair` then rejected with PAIRING_INVALID, so every
+   * documented scripted-onboarding flow failed. "Which code do we use" and "is the
+   * code registered" are two different questions; this answers the second.
+   */
+  registerPairingCode(code, { ttlMs = this.pairingTtlMs } = {}) {
+    if (typeof code !== 'string' || code.trim() === '') {
+      throw new ProtocolError('BAD_REQUEST', 'pairing code must be a non-empty string', { pairing_code: code });
+    }
+    const value = code.trim();
+    const now = this.nowMs();
+    this.pairingCodes.set(value, { code: value, created_at_ms: now, expires_at_ms: now + ttlMs, used: false });
+    return value;
+  }
+
+  /** §2.2 step 3: validate a one-time code. */
+  validatePairingCode(code) {
+    if (typeof code !== 'string' || code.length === 0) {
+      throw new ProtocolError('PAIRING_INVALID', 'pairing_code is required');
+    }
+    const rec = this.pairingCodes.get(code);
+    if (!rec) throw new ProtocolError('PAIRING_INVALID', 'unknown pairing code', { pairing_code: code });
+    if (rec.used) throw new ProtocolError('PAIRING_INVALID', 'pairing code already used', { pairing_code: code });
+    if (this.nowMs() >= rec.expires_at_ms) {
+      throw new ProtocolError('PAIRING_EXPIRED', 'pairing code expired', { pairing_code: code, expired_at: rfc3339(rec.expires_at_ms) });
+    }
+    return rec;
+  }
+
+  /** §2.2: exchange a one-time code for a device_token. §1: idempotent. */
+  pair(request = {}) {
+    const rec = this.validatePairingCode(request.pairing_code);
+    const machineId = request.machine_id;
+    if (typeof machineId !== 'string' || machineId.length === 0) {
+      throw new ProtocolError('BAD_REQUEST', 'machine_id is required');
+    }
+    const now = this.nowMs();
+    const token = this.newToken();
+    const existing = this.devices.get(machineId);
+    if (existing?.device_token) this.tokens.delete(existing.device_token);
+
+    const device = {
+      machine_id: machineId,
+      machine_name: typeof request.machine_name === 'string' && request.machine_name
+        ? request.machine_name : machineId.slice(0, 12),
+      platform: request.platform ?? {},
+      caps: request.caps ?? {},
+      user_id: request.user_id ?? null,
+        // v0.7.7: which fleet this device belongs to, and where that fact came from.
+        //
+        // **The fleet comes from the pairing code, not from the request.** A device that could
+        // name its own fleet would join any fleet, and every signature would faithfully attest
+        // to it. `deviceFleetFields` is the single place that binding is made, and it records
+        // its provenance so a fleet that arrived from a request is visible as such in
+        // `devices.json` rather than looking identical to one that came from a code.
+        ...deviceFleetFields({ codeRecord: rec, requestedFleet: null }),
+        /**
+         * v0.7.10: the device's Ed25519 public key, if it offered one.
+         *
+         * A public key is not a secret, so storing it costs nothing and it is the whole basis of
+         * per-device verification: the relay can then check a signature only *this* machine could
+         * have made, rather than a shared secret every machine holds.
+         *
+         * Not validated here, deliberately. A malformed key fails at verification with a named
+         * reason, while rejecting a pairing over it would lock out every existing device the
+         * moment this field was added -- and devices that send no key keep working, with
+         * `public_key: null` meaning "signs with the shared secret or not at all".
+         */
+        public_key: typeof request.public_key === 'string' && request.public_key !== '' ? request.public_key : null,
+      device_token: token,
+      paired_at_ms: now,
+      re_paired: Boolean(existing),
+      last_seen_at_ms: now,
+      online: true,
+      streams: existing?.streams ?? 0,
+      // v0.3.0 RTT: starts unknown. `null` is "never measured"; 0 would mean "instant".
+      rtt_ms: null,
+      rtt_at_ms: null,
+      last_heartbeat_at_ms: null,
+      stream_connects: existing?.stream_connects ?? 0,
+    };
+    this.devices.set(machineId, device);
+    this.tokens.set(token, machineId);
+    rec.used = true;
+
+    // A group has more than one machine, and a single-use code would leave the
+    // operator unable to pair the second one without restarting the relay. So
+    // consuming a code immediately mints the next one and announces it: the
+    // operator pairs machine A, sees a fresh code, and pairs machine B with it.
+    // `pairingCodeReusable` keeps one code alive for the whole window instead,
+    // for scripted onboarding where nobody is watching stdout.
+    let nextCode = null;
+    const reusable = this.pairingCodeReusable === true;
+    if (reusable) {
+      rec.used = false;
+    } else {
+      nextCode = this.rotatePairingCode();
+    }
+
+    this.emit('peer.hello', {
+      machine_id: machineId,
+      machine_name: device.machine_name,
+      platform: device.platform,
+    });
+
+    if (nextCode) {
+      this.emit('notice', {
+        level: 'info',
+        code: 'PAIRING_CODE_ROTATED',
+        message: 'pairing code consumed; a new one is available',
+        pairing_code: nextCode,
+      });
+    }
+
+    // §7: a device change is snapshotted immediately.
+    this._saveDevices();
+    this._ledger({
+      type: 'device.paired',
+      machine_id: machineId,
+      machine_name: device.machine_name,
+      re_paired: device.re_paired,
+    });
+
+    return {
+      device_token: token,
+      protocol_version: PROTOCOL_VERSION,
+      rabbit_time: rfc3339(now),
+      ...(nextCode ? { next_pairing_code: nextCode } : {}),
+    };
+  }
+
+  /** @returns {object|null} device for a bearer token. */
+  authenticate(token) {
+    if (typeof token !== 'string' || token.length === 0) return null;
+    const machineId = this.tokens.get(token);
+    if (!machineId) return null;
+    return this.devices.get(machineId) ?? null;
+  }
+
+  touchDevice(machineId, { online = true } = {}) {
+    const device = this.devices.get(machineId);
+    if (!device) return null;
+    device.last_seen_at_ms = this.nowMs();
+    if (online) device.online = true;
+    return device;
+  }
+
+  setOnline(machineId, online, reason = null) {
+    const device = this.devices.get(machineId);
+    if (!device) return null;
+    if (device.online === online) return device;
+    device.online = online;
+    if (online) {
+      this.touchDevice(machineId);
+      this.emit('peer.hello', {
+        machine_id: machineId,
+        machine_name: device.machine_name,
+        platform: device.platform,
+      });
+    } else {
+      this.emit('peer.bye', { machine_id: machineId, reason: reason ?? 'stream_closed' });
+    }
+    return device;
+  }
+
+  /* ---------------- RTT (v0.3.0 §R) ---------------- */
+
+  /**
+   * Validate an inbound `rtt_ms`.
+   *
+   * The contract is deliberately liberal: a MISSING or INVALID value must never
+   * reject the heartbeat and must never clobber a previously known good value.
+   * RTT is a diagnostic; it must not be able to break lease renewal.
+   *
+   * Sanity ceiling: anything above `MAX_RTT_MS` (24h) is treated as invalid. A
+   * single garbage value would otherwise poison the fleet aggregate.
+   */
+  static normalizeRtt(value) {
+    if (value === undefined) return { provided: false, valid: false };
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+      return { provided: true, valid: false };
+    }
+    if (value > MAX_RTT_MS) return { provided: true, valid: false };
+    return { provided: true, valid: true, value };
+  }
+
+  /**
+   * RTT is a VOLATILE diagnostic: it is intentionally NOT written to
+   * `devices.json` and NOT replayed from the ledger, so a restarted relay reports
+   * `rtt_ms: null` until a machine heartbeats again. A persisted value would be
+   * indistinguishable from a fresh one and would let the relay claim knowledge it
+   * lost when the process died.
+   */
+  rttStaleAfterMs() { return this.rttStaleMs; }
+
+  /**
+   * v0.3.0: absorb the optional `rtt_ms` carried by a heartbeat.
+   *
+   * Deliberately liberal, because RTT is a diagnostic and must never be able to
+   * break lease renewal:
+   *   - the field is optional; a v0.2.3 agent never sends it
+   *   - a MISSING or INVALID value is IGNORED, keeping the previous value, and the
+   *     heartbeat still succeeds
+   *   - unknown extra fields are ignored entirely (forward compatibility)
+   *
+   * `last_heartbeat_at` advances on EVERY accepted heartbeat, with or without a
+   * usable RTT: it answers "is the machine alive", while `rtt_at` answers "when
+   * was this number measured". Keeping them separate is what lets a reader tell a
+   * genuinely slow machine from one that is simply gone.
+   */
+  recordHeartbeatMetrics(machineId, input = {}, nowMs = this.nowMs()) {
+    const device = this.devices.get(machineId);
+    if (!device) return null;
+    device.last_heartbeat_at_ms = nowMs;
+    const rtt = RabbitState.normalizeRtt(input.rtt_ms);
+    if (rtt.valid) {
+      device.rtt_ms = rtt.value;
+      device.rtt_at_ms = nowMs;
+    }
+    return device;
+  }
+
+  /** True when there is no value, or the value is older than the staleness window. */
+  isRttStale(device, nowMs = this.nowMs()) {
+    if (!device || device.rtt_ms === null || device.rtt_ms === undefined) return true;
+    if (device.rtt_at_ms === null || device.rtt_at_ms === undefined) return true;
+    return nowMs - device.rtt_at_ms > this.rttStaleMs;
+  }
+
+  /** How old the RTT measurement is, in ms; null when there is none. */
+  rttAgeMs(device, nowMs = this.nowMs()) {
+    if (!device || device.rtt_at_ms === null || device.rtt_at_ms === undefined) return null;
+    return Math.max(0, nowMs - device.rtt_at_ms);
+  }
+
+  /** Record that a machine attached a stream (a reconnect is any attach after the first). */
+  noteStreamConnect(machineId) {
+    const device = this.devices.get(machineId);
+    if (!device) return null;
+    device.stream_connects = (device.stream_connects ?? 0) + 1;
+    return device.stream_connects;
+  }
+
+  /**
+   * v0.3.0 aggregate for `/healthz`.
+   *
+   * Only FRESH measurements count. A machine that has been gone for a day must not
+   * drag min/max/avg around, and with no fresh data every numeric field is null --
+   * never 0, which would read as "instantaneous".
+   */
+  rttSummary(nowMs = this.nowMs()) {
+    const fresh = [];
+    let stale = 0;
+    let unknown = 0;
+    for (const device of this.devices.values()) {
+      if (device.rtt_ms === null || device.rtt_ms === undefined) { unknown += 1; continue; }
+      if (this.isRttStale(device, nowMs)) { stale += 1; continue; }
+      fresh.push(device.rtt_ms);
+    }
+    if (fresh.length === 0) {
+      return {
+        machines_reporting: 0,
+        min_ms: null,
+        max_ms: null,
+        avg_ms: null,
+        machines_stale: stale,
+        machines_unknown: unknown,
+      };
+    }
+    const sum = fresh.reduce((a, b) => a + b, 0);
+    return {
+      machines_reporting: fresh.length,
+      min_ms: Math.min(...fresh),
+      max_ms: Math.max(...fresh),
+      avg_ms: Math.round((sum / fresh.length) * 10) / 10,
+      machines_stale: stale,
+      machines_unknown: unknown,
+    };
+  }
+
+  /**
+   * v0.3.0 single-machine status view.
+   *
+   * `last_heartbeat_at` and `rtt_at` answer different questions, and the gap
+   * between them is the whole point: a machine can be heartbeating (alive) while
+   * its RTT number is old (a v0.2.3 agent that never sends `rtt_ms`), and a
+   * machine can be gone while a plausible-looking RTT is still on file.
+   */
+  deviceStatus(machineId, nowMs = this.nowMs()) {
+    const device = this.devices.get(machineId);
+    if (!device) return null;
+    const rttAt = device.rtt_at_ms ?? null;
+    const lastHeartbeat = device.last_heartbeat_at_ms ?? null;
+    return {
+      machine_id: device.machine_id,
+      machine_name: device.machine_name,
+      relay_id: this.relayId,
+      connected: (device.streams ?? 0) > 0,
+      streams: device.streams ?? 0,
+      online: device.online === true,
+      rtt_ms: device.rtt_ms ?? null,
+      rtt_at: rttAt === null ? null : rfc3339(rttAt),
+      rtt_age_ms: this.rttAgeMs(device, nowMs),
+      rtt_stale: this.isRttStale(device, nowMs),
+      last_heartbeat_at: lastHeartbeat === null ? null : rfc3339(lastHeartbeat),
+      last_seen_at: device.last_seen_at_ms === null || device.last_seen_at_ms === undefined
+        ? null : rfc3339(device.last_seen_at_ms),
+      reconnect_attempts: Math.max(0, (device.stream_connects ?? 0) - 1),
+      stream_connects: device.stream_connects ?? 0,
+      paired_at: device.paired_at_ms === null || device.paired_at_ms === undefined
+        ? null : rfc3339(device.paired_at_ms),
+      platform: device.platform,
+      caps: device.caps,
+      user_id: device.user_id ?? null,
+      now: rfc3339(nowMs),
+    };
+  }
+
+  /** Public device view — never leaks device_token. */
+  publicDevice(device) {
+    return {
+      machine_id: device.machine_id,
+      machine_name: device.machine_name,
+      platform: device.platform,
+      caps: device.caps,
+      user_id: device.user_id,
+        /**
+         * v0.7.7: the fleet this device belongs to, and where the fact came from.
+         *
+         * **Carried in the public shape on purpose, and it has to be**, because `devices.json`
+         * is written from this shape -- a fleet that lived only on the in-memory record would
+         * vanish on the next restart, which is precisely when an operator is looking at it. A
+         * first version omitted these and the live test caught the fleet disappearing from
+         * `listDevices()`.
+         *
+         * Safe to expose: `fleet_id` is a truncated hash of the account id, not the account id,
+         * and devices on one relay can already enumerate each other. Narrowing `/v1/devices` to
+         * a device's own fleet is a further step, recorded as such rather than implied.
+         */
+        fleet_id: device.fleet_id ?? null,
+        fleet_source: device.fleet_source ?? null,
+        // v0.7.10: a boolean rather than the key itself. The key is not a secret, but a device
+        // list is read by every device, and there is no reason to hand every machine every other
+        // machine's key when the verification happens relay-side.
+        public_key_present: typeof device.public_key === 'string' && device.public_key !== '',
+      online: device.online,
+      streams: device.streams,
+      paired_at: rfc3339(device.paired_at_ms),
+      last_seen_at: rfc3339(device.last_seen_at_ms),
+      // v0.3.0: `null` means "never measured", which is NOT the same as 0ms.
+      rtt_ms: device.rtt_ms ?? null,
+      rtt_at: device.rtt_at_ms === null || device.rtt_at_ms === undefined ? null : rfc3339(device.rtt_at_ms),
+      rtt_age_ms: this.rttAgeMs(device),
+      rtt_stale: this.isRttStale(device),
+      last_heartbeat_at: device.last_heartbeat_at_ms === null || device.last_heartbeat_at_ms === undefined
+        ? null : rfc3339(device.last_heartbeat_at_ms),
+      reconnect_attempts: Math.max(0, (device.stream_connects ?? 0) - 1),
+    };
+  }
+
+  listDevices() { return [...this.devices.values()].map((d) => this.publicDevice(d)); }
+
+  /* ---------------- tasks (§4) ---------------- */
+
+  /**
+   * v0.4.0: validate the routing metadata a `POST /v1/task` body may carry.
+   *
+   * A machine, not a mode, is `origin_machine_id`: where the task was typed (`device.json`), so an
+   * offer can carry that fact to the machine that has to run it. `p2p.mode` is the dispatcher's
+   * resolved mode for this particular task — the plugin may be configured `direct` while a
+   * scheduled run is `relay`.
+   *
+   * Validation is deliberately shallow and strictly typed, in the house style of this file: a
+   * missing value is the v0.3.9 shape and stays valid, while a present-but-wrong value is refused
+   * by name. Accepting a non-string here would put a number into `origin_machine_id` and only fail
+   * later, on a machine that cannot tell a bad field from a bad relay.
+   *
+   * @returns {{origin_machine_id:string|null, p2p:{mode:string}|null}}
+   */
+  static validateTaskRouting(input = {}) {
+    let originMachineId = null;
+    if (input.origin_machine_id !== undefined && input.origin_machine_id !== null) {
+      if (typeof input.origin_machine_id !== 'string'
+        || input.origin_machine_id.length === 0
+        || input.origin_machine_id.length > MAX_ORIGIN_MACHINE_ID_LENGTH) {
+        throw new ProtocolError(
+          'BAD_REQUEST',
+          `origin_machine_id must be a non-empty string of at most ${MAX_ORIGIN_MACHINE_ID_LENGTH} characters`,
+          { origin_machine_id: input.origin_machine_id },
+        );
+      }
+      originMachineId = input.origin_machine_id;
+    }
+
+    let p2p = null;
+    if (input.p2p !== undefined && input.p2p !== null) {
+      if (typeof input.p2p !== 'object' || Array.isArray(input.p2p)) {
+        throw new ProtocolError('BAD_REQUEST', 'p2p must be an object with a `mode` field', { p2p: input.p2p });
+      }
+      if (!P2P_MODES.includes(input.p2p.mode)) {
+        throw new ProtocolError(
+          'BAD_REQUEST',
+          `p2p.mode must be one of ${P2P_MODES.join('|')}`,
+          { 'p2p.mode': input.p2p.mode ?? null },
+        );
+      }
+      // Copied rather than referenced: the recorded task must not be mutable through the request
+      // body the caller still holds.
+      p2p = { ...input.p2p };
+    }
+
+    return { origin_machine_id: originMachineId, p2p };
+  }
+
+  /**
+   * v0.4.0 §5.2: validate the optional transport fields of a result envelope.
+   *
+   * Same reasoning as `validateTaskRouting`: `transport` is an enum and `p2p` is an opaque object,
+   * so anything else is refused by name at the door. Both fields stay OUT of
+   * `REQUIRED_ENVELOPE_FIELDS` (a missing one is a v0.3.9 envelope, not an incomplete one) and out
+   * of `COMPARABLE_FIELDS` (a path is not a result).
+   */
+  static validateTransportFields(envelope = {}) {
+    if (envelope.transport !== undefined && envelope.transport !== null) {
+      if (!TRANSPORT_VALUES.includes(envelope.transport)) {
+        throw new ProtocolError(
+          'BAD_REQUEST',
+          `transport must be one of ${TRANSPORT_VALUES.join('|')}`,
+          { transport: envelope.transport },
+        );
+      }
+    }
+    if (envelope.p2p !== undefined && envelope.p2p !== null
+      && (typeof envelope.p2p !== 'object' || Array.isArray(envelope.p2p))) {
+      throw new ProtocolError('BAD_REQUEST', 'p2p must be an object', { p2p: envelope.p2p });
+    }
+  }
+
+  /**
+   * §4.1 POST /v1/task.
+   * Machine selection is not specified by the PROTOCOL; we implement:
+   *   - `target_machines` (optional explicit list), else every paired device
+   *   - capability gate §6.1 per machine (failures become `refused` leases)
+   *   - index assignment: replicate -> 0, split -> round-robin modulo index_total
+   */
+  createTask(input = {}) {
+    // v0.4.0: refused BEFORE the task literal is built and before any offer is emitted, so a bad
+    // value cannot leave a half-created task behind. `POST /v1/task` is all-or-nothing.
+    const routing = RabbitState.validateTaskRouting(input);
+
+    const mode = input.mode ?? 'replicate';
+    if (mode !== 'replicate' && mode !== 'split' && mode !== 'broadcast' && mode !== 'pipeline' && mode !== 'compose') {
+      throw new ProtocolError(
+        'BAD_REQUEST',
+        'mode must be replicate|split|broadcast|pipeline|compose',
+        { mode },
+      );
+    }
+    /**
+     * v0.3.3 `pipeline`: the whole chain runs on each machine, stage after stage.
+     *
+     * The semantics were chosen against the alternative (fan out stage 1, converge its outputs into
+     * stage 2) because that one has no well-defined input: on a fleet, stage 1 produces n different
+     * outputs, and "feed them all to stage 2" does not say in what order, or whether stage 2 then
+     * runs once or n times. Worse, two machines finishing in a different order would produce
+     * different stage-2 inputs, so one task_id would no longer describe one reproducible execution --
+     * which is the property the rest of this system is built on. See docs/PIPELINE-DESIGN.md.
+     *
+     * So: a pipeline is `replicate` applied to a sequence. Every machine runs the whole chain, there
+     * is no cross-machine data flow, and nothing new can be silently dropped in transit.
+     */
+    const rawStages = Array.isArray(input.stages) ? input.stages : null;
+    const isPipeline = mode === 'pipeline';
+    if (isPipeline) {
+      if (rawStages === null || rawStages.length === 0) {
+        throw new ProtocolError('BAD_REQUEST', 'mode=pipeline requires a non-empty `stages` array', {
+          stages: rawStages === null ? null : rawStages.length,
+        });
+      }
+      if (rawStages.length > MAX_PIPELINE_STAGES) {
+        throw new ProtocolError('BAD_REQUEST', `stages must have at most ${MAX_PIPELINE_STAGES} entries`, {
+          stages: rawStages.length,
+        });
+      }
+      rawStages.forEach((stage, i) => {
+        const argv = stage?.command_argv;
+        if (!Array.isArray(argv) || argv.length === 0 || argv.some((a) => typeof a !== 'string')) {
+          throw new ProtocolError('BAD_REQUEST', `stages[${i}].command_argv must be a non-empty string[]`, { index: i });
+        }
+      });
+      // A chain is one execution on one machine; sharding it would mean each machine ran a chain of
+      // its own slice, which is a different feature and not what the caller asked for.
+      if (Number.isInteger(input.index_total) && input.index_total !== 1) {
+        throw new ProtocolError('BAD_REQUEST', 'mode=pipeline runs the whole chain per machine, so index_total must be 1', {
+          index_total: input.index_total,
+        });
+      }
+    } else if (rawStages !== null) {
+      // Refused rather than ignored: the caller believes they described a sequence, and running only
+      // `command_argv` would silently drop every stage after the first.
+      throw new ProtocolError('BAD_REQUEST', '`stages` is only valid with mode=pipeline', { mode, stages: rawStages.length });
+    }
+
+    /**
+     * Normalized stage list. For every mode there is at least one stage, so downstream code has a
+     * single shape to reason about and `pipeline` is not a special case at the execution layer.
+     */
+    const stages = isPipeline
+      ? rawStages.map((s, i) => ({
+        index: i,
+        command_argv: [...s.command_argv],
+        cwd_rel: typeof s.cwd_rel === 'string' && s.cwd_rel ? s.cwd_rel : (typeof input.cwd_rel === 'string' && input.cwd_rel ? input.cwd_rel : '.'),
+        timeout_ms: Number.isInteger(s.timeout_ms) ? s.timeout_ms : null,
+        continue_on_failure: s.continue_on_failure === true,
+      }))
+      : null;
+
+    const commandArgv = isPipeline ? [...rawStages[0].command_argv] : input.command_argv;
+    if (!Array.isArray(commandArgv) || commandArgv.length === 0 || commandArgv.some((a) => typeof a !== 'string')) {
+      throw new ProtocolError('BAD_REQUEST', 'command_argv must be a non-empty string[]');
+    }
+    const indexTotal = Number.isInteger(input.index_total) ? input.index_total : 1;
+    if (indexTotal < 1) throw new ProtocolError('BAD_REQUEST', 'index_total must be >= 1');
+
+    const halt = input.halt ?? 'never';
+    if (halt !== 'never' && halt !== 'now') throw new ProtocolError('BAD_REQUEST', 'halt must be never|now', { halt });
+
+    const taskId = input.task_id ?? this.nextId();
+    if (this.tasks.has(taskId)) {
+      throw new ProtocolError('TASK_EXISTS', 'task_id already exists', { task_id: taskId });
+    }
+
+    const now = this.nowMs();
+    const cwdRel = typeof input.cwd_rel === 'string' && input.cwd_rel ? input.cwd_rel : '.';
+    const baseTree = input.base_tree ?? null;
+    const commandHash = input.command_hash ?? (isPipeline
+      ? computePipelineCommandHash(stages, SHELL_ID_DIRECT)
+      : computeCommandHash(commandArgv, SHELL_ID_DIRECT, cwdRel));
+    const timeoutMs = Number.isInteger(input.timeout_ms) ? input.timeout_ms : 300_000;
+
+    // v0.3.3 `broadcast`: one machine runs the command, every other machine is told the outcome.
+    //
+    // The executor choice is deterministic rather than random. A random leader makes a task
+    // impossible to reproduce from its own record -- the same task id would run somewhere else on a
+    // retry -- and this project's whole value rests on being able to say exactly where something ran.
+    // The first target in the relay's own device order is stable for a given device table.
+    //
+    // Observers get a lease so they are tracked and notified, but their lease is `observing`, which
+    // every aggregation step treats as "did not run". That distinction is the point: a machine that
+    // never executed anything agreeing with a result would be a fabrication, and it is exactly the
+    // fabrication this mode could most easily produce.
+    //
+    // Resolved before the task literal because the literal records it. (`targets` is computed below,
+    // so the executor is re-validated against it after that.)
+    const targetIds = Array.isArray(input.target_machines) && input.target_machines.length > 0
+      ? input.target_machines
+      : [...this.devices.keys()];
+    const executorMachineId = mode === 'broadcast'
+      ? (typeof input.executor_machine_id === 'string' && input.executor_machine_id !== ''
+        ? input.executor_machine_id
+        : targetIds[0] ?? null)
+      : null;
+
+    const task = {
+      task_id: taskId,
+      mode,
+      command_argv: commandArgv,
+      cwd_rel: cwdRel,
+      index_total: indexTotal,
+      timeout_ms: timeoutMs,
+      write: input.write === true,
+      write_scope: input.write_scope ?? [],
+      require_exclusive_write: input.require_exclusive_write === true,
+      base_commit: input.base_commit ?? null,
+      base_tree: baseTree,
+      requirements: input.requirements ?? {},
+      compare_policy: input.compare_policy ?? {},
+      halt,
+      created_by: input.created_by ?? null,
+      created_at_ms: now,
+      command_hash: commandHash,
+      attempt: 1,
+      leases: new Map(),
+      cancelled: false,
+      cancel_reason: null,
+      degraded: null,
+      deadline_ms: now + timeoutMs,
+      result_seqs: [],
+      /** v0.3.3: which machine actually executes under `broadcast`; null for the other modes. */
+      executor_machine_id: executorMachineId,
+      /**
+       * v0.3.3: the normalized stage list for `pipeline`, or null.
+       *
+       * Sent to the machine in the offer so it can run the whole chain. Kept on the task as well so
+       * a report can say how many stages were supposed to run even when the machine crashed before
+       * reporting any of them.
+       */
+      stages,
+      /**
+       * v0.4.0: where the task came from and under which P2P mode it was dispatched, or null.
+       *
+       * Kept on the task (not just passed to `emitOffer`) because an offer is emitted more than
+       * once: `redeliverPendingOffers` re-states unclaimed work on every reconnect and
+       * `_takeover` re-offers a freed index. A machine that reconnects must see the same routing
+       * facts as the machine that was connected at dispatch time, or the direct-push half of the
+       * feature would work exactly once and then quietly stop.
+       */
+      origin_machine_id: routing.origin_machine_id,
+      p2p: routing.p2p,
+    };
+
+    /**
+     * Fleet scoping (v0.7.7).
+     *
+     * This replaces `targets = [...this.devices.values()]`, which reached **every device on the
+     * relay** with no filter — the finding that accounts were not isolated. The rule now lives in
+     * `fleet-wiring.mjs` so it is one function with its own exhaustive tests rather than three
+     * lines inside a two-thousand-line object.
+     *
+     * ## The migration is deliberate, and so is its limit
+     *
+     * The shared relay holds four devices that paired before fleets existed, and none of them has
+     * a `fleet_id`. `targetsFor` therefore has two modes: a relay with no fleet configured keeps
+     * exactly the old behaviour, and a relay that *is* scoped refuses a fleetless requester rather
+     * than handing it the run of the fleet. So deploying this cannot be an outage, and scoping it
+     * cannot be a silent grant.
+     *
+     * ## What this does NOT do, stated here rather than discovered later
+     *
+     * `POST /v1/task` authenticates with the **operator token**, and `authorizeTaskDispatch`
+     * returns `{ role: 'operator', machine_id: null }` for it — there is no device, so there is no
+     * fleet to scope by. Every device that authenticates with a **device token** gets full
+     * isolation from this change; an operator-token dispatch remains relay-wide, because the
+     * operator token *is* the relay-wide credential by design.
+     *
+     * `input.created_by` is the one device identity a task carries, and it is used when present:
+     * a task submitted on behalf of a machine is scoped to that machine's fleet.
+     */
+    const requester =
+      (typeof input.created_by === 'string' && this.devices.get(input.created_by)) ||
+      (typeof input.requester_machine_id === 'string' && this.devices.get(input.requester_machine_id)) ||
+      null;
+
+    /**
+     * An operator-token dispatch, on a relay that has been scoped, acts **within that scope**.
+     *
+     * A first version passed `requester: null` and let it be refused -- which broke every
+     * operator dispatch on a scoped relay, and broke it in the least useful way: the operator had
+     * just configured the fleet, and configuring it made them unable to dispatch at all.
+     *
+     * The reasoning for the fix: the relay's own `fleetId` *is* an admin's statement about which
+     * fleet this relay serves. An operator dispatch therefore has an unambiguous scope, and
+     * refusing it would be refusing the case that was explicitly asked for.
+     *
+     * What stays genuinely ambiguous is an operator dispatch on a relay holding **several** fleets
+     * with no fleet of its own -- there is no way to tell which was meant, so `targetsFor` refuses
+     * that rather than guessing.
+     */
+    const scopedRequester =
+      requester ??
+      (this.fleetId === null ? null : { machine_id: null, fleet_id: this.fleetId, fleet_source: 'relay_scope' });
+
+    const scoped = targetsFor({
+      devices: [...this.devices.values()],
+      requester: scopedRequester,
+      targetMachines: input.target_machines,
+      relayFleetId: this.fleetId ?? null,
+      // The existing code did not filter offline devices at selection time -- it offered to them and
+      // let the lease expire. Keeping that here avoids changing two behaviours at once, and the
+      // lease expiry is what `handoff.mjs` is for.
+      requireOnline: false,
+    });
+    if (!scoped.ok) {
+      /**
+       * `NO_ONLINE_DEVICE`, not a new code.
+       *
+       * A first version invented `NO_ELIGIBLE_DEVICE`, which broke the one relay test that pins
+       * this contract — and worse, it would have broken **callers**: `chatops/fleet.mjs` reads
+       * `NO_ONLINE_DEVICE` to produce *"start an agent on each machine"*, and a code it has never
+       * seen falls through to a generic refusal. The protocol's code table is part of the
+       * protocol, and adding a member to it is a decision for a protocol revision, not for a
+       * wiring change.
+       *
+       * What *is* new is why nothing was eligible, and that belongs in `detail`, where a caller
+       * can read it without a new code entering the table.
+       */
+      throw new ProtocolError('NO_ONLINE_DEVICE', scoped.text, {
+        reason: scoped.reason,
+        legacy: scoped.legacy,
+        fleet_scoped: scoped.legacy === false,
+        hint:
+          scoped.reason === 'requester_has_no_fleet'
+            ? 'this relay is bound to a fleet and the requesting device is in none; pair it with a code issued for that fleet'
+            : scoped.reason === 'target_outside_fleet'
+              ? 'the named target is not in this fleet'
+              : 'check that at least one device in this fleet is paired and streaming',
+      });
+    }
+    const targets = scoped.targets;
+    if (scoped.legacy) {
+      // Logged at debug so an operator reading logs during a migration can see which rule applied.
+      // "N targets" alone does not say whether isolation is on, and that is the question being asked.
+      this.log?.('debug', 'task targets selected without a fleet (legacy path)', {
+        task_candidates: targets.length,
+        relay_fleet_id: this.fleetId ?? null,
+      });
+    }
+
+    // v0.3.3 `broadcast`: validated here, where `targets` is known. The executor id itself was
+    // resolved before the task literal because the literal records it.
+    if (mode === 'broadcast' && executorMachineId !== null && !targets.some((d) => d.machine_id === executorMachineId)) {
+      throw new ProtocolError('BAD_REQUEST', 'executor_machine_id is not among the target machines', {
+        executor_machine_id: executorMachineId,
+        targets: targets.map((d) => d.machine_id),
+      });
+    }
+
+    if (targets.length === 0) {
+      throw new ProtocolError('NO_ONLINE_DEVICE', 'no paired device available for this task', {
+        known_devices: all.length,
+      });
+    }
+
+    const dedupeKeyBase = computeDedupeKey(taskId, 0, commandHash, baseTree);
+    if (typeof dedupeKeyBase !== 'string' || dedupeKeyBase.length !== 64) {
+      throw new ProtocolError('INTERNAL', 'failed to compute dedupe_key');
+    }
+    let lastSeq = this.seq;
+    targets.forEach((device, i) => {
+      const index = mode === 'replicate' ? 0 : i % indexTotal;
+      const observing = mode === 'broadcast' && device.machine_id !== executorMachineId;
+      const lease = {
+        machine_id: device.machine_id,
+        machine_name: device.machine_name,
+        index,
+        attempt: 1,
+        // `observing` is a lease state, not an outcome: the machine holds a place in this task and
+        // will be told what happened, but it was never handed the command. `gateMachine` below is
+        // skipped for it because refusing to do work you were never asked to do is not a refusal.
+        state: observing ? 'observing' : 'queued',
+        refusal_reason: null,
+        refusal_detail: null,
+        dedupe_key: computeDedupeKey(taskId, index, commandHash, baseTree),
+        last_heartbeat_ms: now,
+        claimed_at_ms: now,
+        lease_until_ms: now + this.leaseWindowMs(),
+        phase: null,
+        progress: null,
+        offered_seq: null,
+        expired_at_ms: null,
+        finished_at_ms: null,
+        heartbeat_count: 0,
+      };
+      if (observing) {
+        // No capability gate and no offer: the machine is not being asked to run anything, so there
+        // is nothing to refuse and nothing to hand out. It is recorded so the task can tell it the
+        // outcome afterwards.
+        task.leases.set(device.machine_id, lease);
+        return;
+      }
+      const gate = gateMachine(task, device);
+      if (gate) {
+        lease.state = 'refused';
+        lease.refusal_reason = gate.refusal_reason;
+        lease.refusal_detail = gate.detail;
+        task.leases.set(device.machine_id, lease);
+        this.emit('notice', {
+          level: 'warn',
+          code: 'CAPABILITY_REFUSED',
+          message: `${device.machine_id} refused: ${gate.refusal_reason}`,
+          task_id: taskId,
+        });
+        return;
+      }
+      task.leases.set(device.machine_id, lease);
+      const grace = this._p2pOfferGraceMs(task);
+      if (grace > 0) {
+        // v0.4.0: the dispatcher is pushing this offer over the direct path right now. Hold the
+        // relay's copy for `grace` ms so the direct one can win; see `p2pOfferGraceMs`.
+        this._scheduleOffer(task, lease, grace);
+      } else {
+        const event = this.emitOffer(task, lease);
+        lastSeq = event.seq;
+      }
+    });
+
+    this.tasks.set(taskId, task);
+
+    this._ledger({
+      type: 'task.created',
+      task: {
+        task_id: task.task_id,
+        mode: task.mode,
+        command_argv: task.command_argv,
+        cwd_rel: task.cwd_rel,
+        index_total: task.index_total,
+        timeout_ms: task.timeout_ms,
+        write: task.write,
+        write_scope: task.write_scope,
+        require_exclusive_write: task.require_exclusive_write,
+        base_commit: task.base_commit,
+        base_tree: task.base_tree,
+        requirements: task.requirements,
+        compare_policy: task.compare_policy,
+        halt: task.halt,
+        created_by: task.created_by,
+        created_at_ms: task.created_at_ms,
+        command_hash: task.command_hash,
+        attempt: task.attempt,
+        deadline_ms: task.deadline_ms,
+        // v0.4.0: routing metadata, so a restarted relay re-offers with the same facts.
+        origin_machine_id: task.origin_machine_id ?? null,
+        p2p: task.p2p ?? null,
+      },
+      leases: [...task.leases.values()].map((l) => ({ ...l })),
+    });
+
+    const refusedOnly = [...task.leases.values()].every((l) => l.state === 'refused');
+    if (refusedOnly) {
+      // §6.3 Step 0 territory: a task nobody may execute is still a valid, reportable task.
+      this.emit('notice', {
+        level: 'warn',
+        code: 'NO_ONLINE_DEVICE',
+        message: 'every candidate machine refused the capability gate',
+        task_id: taskId,
+      });
+    }
+
+    return {
+      task_id: taskId,
+      leases: [...task.leases.values()].map((l) => ({
+        machine_id: l.machine_id,
+        index: l.index,
+        state: l.state,
+        // v0.4.0: the dispatcher pushes an offer over the direct path, and the executor dedupes it
+        // against the relay's copy by (task_id, attempt, dedupe_key). Without this field the
+        // dispatcher has to reproduce the §4.4 formula locally, which works for a single-command
+        // task and cannot work for a pipeline one -- the key covers the relay's normalised stage
+        // list. Publishing it makes the pushed copy recognisably the same work item, which is what
+        // keeps the direct path from turning exactly-once into at-least-twice.
+        dedupe_key: l.dedupe_key ?? null,
+        attempt: l.attempt,
+        ...(l.refusal_reason ? { refusal_reason: l.refusal_reason } : {}),
+      })),
+      seq: lastSeq,
+    };
+  }
+
+  /**
+   * v0.4.0: should the relay hold its offer back for this task?
+   *
+   * Only when the dispatcher said two things: that it is a machine (`origin_machine_id`), and that
+   * the direct path is in play (`p2p.mode` of `auto` or `direct`). A `relay` mode or a v0.3.9
+   * dispatcher gets the old behaviour exactly, which is why this predicate is the only gate on the
+   * change and every pre-existing test still sees an immediate offer.
+   *
+   * @param {object} task
+   * @returns {number} milliseconds to hold, or 0 for "offer now"
+   */
+  _p2pOfferGraceMs(task) {
+    if (this.p2pOfferGraceMs <= 0) return 0;
+    const origin = task?.origin_machine_id;
+    if (typeof origin !== 'string' || origin === '') return 0;
+    const mode = task?.p2p?.mode;
+    if (mode !== 'auto' && mode !== 'direct') return 0;
+    return this.p2pOfferGraceMs;
+  }
+
+  /**
+   * v0.4.0: emit `lease`'s offer after `delayMs`, unless the direct path got there first.
+   *
+   * "Got there first" is one fact and it is already tracked: the executor renews the lease
+   * (`POST /v1/heartbeat`) as its first act on any offer it accepts, and a renewal moves the lease
+   * out of `queued`. So the check is the lease's own state — no new message, no new endpoint, and
+   * nothing the executor has to know about.
+   *
+   * The timer is `unref()`ed: a relay with nothing else to do must still be able to exit, and a
+   * pending offer is not a reason to keep a process alive.
+   */
+  _scheduleOffer(task, lease, delayMs) {
+    const key = `${task.task_id}:${lease.machine_id}`;
+    const timer = setTimeout(() => {
+      this._pendingOffers.delete(key);
+      // A lease that was re-created (takeover) or swept is not this one any more.
+      if (task.leases.get(lease.machine_id) !== lease) return;
+      if (lease.state !== 'queued') return; // the direct copy won; nothing to fall back to
+      if (this.isLeaseExpired(lease, this.nowMs())) return; // the sweep owns it now
+      this.emitOffer(task, lease);
+    }, delayMs);
+    timer.unref?.();
+    this._pendingOffers.set(key, timer);
+  }
+
+  /** Drop every deferred offer. Called by the relay's own teardown path. */
+  clearPendingOffers() {
+    for (const timer of this._pendingOffers.values()) clearTimeout(timer);
+    this._pendingOffers.clear();
+  }
+
+  emitOffer(task, lease) {
+    const event = this.emit('task.offer', {
+      task_id: task.task_id,
+      attempt: lease.attempt,
+      mode: task.mode,
+      index: lease.index,
+      index_total: task.index_total,
+      command_argv: task.command_argv,
+      // v0.3.3: present only for `pipeline`, and only then does the machine run a chain. Omitted
+      // entirely otherwise, so an offer for a single-command task is byte-identical to before --
+      // which is what keeps a v0.2.3 agent working against this relay.
+      ...(task.stages ? { stages: task.stages } : {}),
+      /**
+       * v0.4.0: always present, `null` when the caller supplied nothing.
+       *
+       * Deliberately NOT conditional (unlike `stages` above, which is omitted so a single-command
+       * offer stays byte-identical for an old agent): the contract fixes the shape of these two as
+       * `string|null` and `{mode}|null`, and `null` is the honest value for "the dispatcher did not
+       * say" — which is exactly the v0.3.9 case. They are additive keys in an event whose consumers
+       * already ignore unknown fields.
+       */
+      origin_machine_id: task.origin_machine_id ?? null,
+      p2p: task.p2p ?? null,
+      cwd_rel: task.cwd_rel,
+      write: task.write,
+      timeout_ms: task.timeout_ms,
+      base_commit: task.base_commit,
+      base_tree: task.base_tree,
+      requirements: task.requirements,
+      compare_policy: task.compare_policy,
+      dedupe_key: lease.dedupe_key,
+      deadline: rfc3339(task.deadline_ms),
+    }, { target: lease.machine_id });
+    lease.state = 'offered';
+    lease.offered_seq = event.seq;
+    lease.last_heartbeat_ms = this.nowMs();
+    lease.lease_until_ms = lease.last_heartbeat_ms + this.leaseWindowMs();
+    return event;
+  }
+
+  getTask(taskId) { return this.tasks.get(taskId) ?? null; }
+
+  requireTask(taskId) {
+    const task = this.tasks.get(taskId);
+    if (!task) throw new ProtocolError('NOT_FOUND', 'unknown task_id', { task_id: taskId });
+    return task;
+  }
+
+  /**
+   * Re-offer the work a machine was handed but has not yet started (v0.1.2 §8.6).
+   *
+   * WHY THIS EXISTS
+   *
+   * An offer is a point-in-time event on a stream. `createTask` publishes
+   * `task.offer` once, and if the target machine's stream happens to be down at
+   * that instant -- the ordinary situation after a relay restart, a tunnel drop,
+   * or any cross-network interruption -- the event is simply gone. The lease sits
+   * in `offered` until the sweep expires it, the task never runs, and the
+   * operator sees a timeout with no explanation. Measured: the machine is back
+   * online with a live stream within milliseconds, and still receives nothing.
+   *
+   * So the relay re-states unclaimed work when a machine connects. This is safe
+   * because the state it acts on is durable: the lease the offer refers to is
+   * still in the ledger.
+   *
+   * WHY ONLY `offered` AND `queued`
+   *
+   * `running` is deliberately excluded, and that exclusion is the whole safety
+   * argument. A running lease means a machine has already STARTED the command --
+   * it acknowledged the offer and is heartbeating. Re-offering it would make that
+   * machine execute the work a second time, so the fix for a lost offer would
+   * introduce the one failure this project is built to avoid: two machines, or
+   * one machine twice, running the same side-effecting command.
+   *
+   * A machine that dies mid-run therefore does not get its work back here; that
+   * path stays with the sweep, which expires the lease and hands the index to
+   * another machine with `attempt + 1`.
+   *
+   * Re-emitted offers are new events and are replayed like any other, so a client
+   * that reconnects repeatedly can see the same offer more than once. That is
+   * intentional: the agent already de-duplicates by `task_id` (it ignores an
+   * offer whose task is queued or running), and an at-least-once offer with a
+   * client-side dedupe is strictly better than an at-most-once offer that is
+   * silently dropped.
+   *
+   * @param {string} machineId
+   * @returns {{count: number, task_ids: string[]}}
+   */
+  redeliverPendingOffers(machineId) {
+    const taskIds = [];
+    const now = this.nowMs();
+
+    for (const task of this.tasks.values()) {
+      if (task.cancelled === true) continue;
+      const lease = task.leases.get(machineId);
+      if (!lease) continue;
+      // Only work the machine has not begun. See the note above: `running` is
+      // excluded on purpose, not by omission.
+      if (lease.state !== 'offered' && lease.state !== 'queued') continue;
+      // Do not resurrect a lease the sweep has already written off; the takeover
+      // path owns that decision.
+      if (this.isLeaseExpired(lease, now)) continue;
+
+      this.emitOffer(task, lease);
+      taskIds.push(task.task_id);
+    }
+
+    return { count: taskIds.length, task_ids: taskIds };
+  }
+
+  listTasks({ limit = 50 } = {}) {
+    const n = Number.isInteger(limit) && limit > 0 ? limit : 50;
+    return [...this.tasks.values()]
+      .sort((a, b) => b.created_at_ms - a.created_at_ms)
+      .slice(0, n)
+      .map((t) => this.taskSummary(t));
+  }
+
+  taskSummary(task) {
+    return {
+      task_id: task.task_id,
+      mode: task.mode,
+      created_at: rfc3339(task.created_at_ms),
+      created_by: task.created_by,
+      index_total: task.index_total,
+      cancelled: task.cancelled,
+      degraded: task.degraded,
+      leases: [...task.leases.values()].map((l) => l.machine_id),
+      lease_states: Object.fromEntries([...task.leases.values()].map((l) => [l.machine_id, l.state])),
+    };
+  }
+
+  cancelTask(taskId, reason = 'cancelled_by_operator') {
+    const task = this.requireTask(taskId);
+    if (task.cancelled) return task;
+    task.cancelled = true;
+    task.cancel_reason = reason;
+    for (const lease of task.leases.values()) {
+      if (ACTIVE_LEASE_STATES.includes(lease.state)) lease.state = 'cancelled';
+    }
+    this.emit('task.cancel', { task_id: taskId, reason });
+    this._ledger({ type: 'task.cancelled', task_id: taskId, reason });
+    return task;
+  }
+
+  /* ---------------- leases / heartbeat (§4.3) ---------------- */
+
+  /** Shared `phase`/`progress` validation for both heartbeat modes. */
+  _validatePhaseProgress(input) {
+    if (input.phase !== undefined && input.phase !== null && !LEASE_PHASES.includes(input.phase)) {
+      throw new ProtocolError('BAD_REQUEST', 'phase must be preparing|running|finalizing', { phase: input.phase });
+    }
+    if (input.progress !== undefined && input.progress !== null
+      && (typeof input.progress !== 'number' || input.progress < 0 || input.progress > 1)) {
+      throw new ProtocolError('BAD_REQUEST', 'progress must be a number in [0,1]', { progress: input.progress });
+    }
+  }
+
+  /**
+   * v0.3.0 IDLE (diagnostic) heartbeat — an agent with no lease keeps its latency
+   * and liveness visible to other machines.
+   *
+   * This path deliberately NEVER looks at `this.tasks`. That is the whole safety
+   * argument, and it is structural rather than a matter of remembering a rule: an
+   * idle heartbeat cannot renew, resurrect or otherwise touch a lease because it
+   * never obtains one. Without that, an idle ping from a machine whose lease had
+   * expired would flip `expired` back to `running` and manufacture a live task out
+   * of nothing -- a fake "the work is still being done" signal, which is the most
+   * dangerous lie this relay can tell.
+   */
+  diagnosticHeartbeat(input = {}) {
+    const machineId = typeof input.machine_id === 'string' && input.machine_id !== ''
+      ? input.machine_id : null;
+    if (machineId === null) {
+      throw new ProtocolError('BAD_REQUEST', 'machine_id is required', {});
+    }
+    if (!this.devices.has(machineId)) {
+      throw new ProtocolError('NOT_FOUND', 'unknown machine_id', { machine_id: machineId });
+    }
+    this._validatePhaseProgress(input);
+
+    const device = this.touchDevice(machineId);
+    this.recordHeartbeatMetrics(machineId, input);
+    return {
+      // No lease is involved, and the response says so instead of inventing one.
+      lease_until: null,
+      cancel: false,
+      diagnostic: true,
+      machine_id: machineId,
+      rtt_ms: device?.rtt_ms ?? null,
+    };
+  }
+
+  /**
+   * §4.3 POST /v1/heartbeat — renews the lease using SERVER time only.
+   *
+   * Two modes since v0.3.0:
+   *   - `task_id` present            -> LEASE heartbeat (unchanged §4.3 behaviour)
+   *   - `diagnostic: true`, no task  -> IDLE heartbeat (diagnostics only, no lease)
+   *   - neither                      -> 400. A heartbeat that silently renewed
+   *     nothing would let an agent whose `task_id` went missing stop renewing while
+   *     believing it was fine, ending in a falsely `expired` task. §0 forbids
+   *     silent degradation, so this is loud.
+   *
+   * @returns {{lease_until:string|null, cancel:boolean, phase?:string, progress?:number, diagnostic?:boolean}}
+   */
+  heartbeat(input = {}) {
+    const hasTask = typeof input.task_id === 'string' && input.task_id !== '';
+    if (!hasTask) {
+      if (input.diagnostic !== true) {
+        throw new ProtocolError('BAD_REQUEST',
+          'a heartbeat must carry task_id (lease renewal) or diagnostic:true (idle diagnostics); '
+          + 'refusing to treat a missing task_id as a no-op renewal', {
+            received_keys: Object.keys(input).sort(),
+          });
+      }
+      return this.diagnosticHeartbeat(input);
+    }
+    if (input.diagnostic === true) {
+      // task_id wins: a heartbeat that names a task IS a lease heartbeat.
+      // (documented; the flag is simply redundant here)
+    }
+    return this.leaseHeartbeat(input);
+  }
+
+  leaseHeartbeat(input = {}) {
+    const task = this.requireTask(input.task_id);
+    const lease = task.leases.get(input.machine_id);
+    if (!lease) {
+      throw new ProtocolError('NOT_FOUND', 'no lease for this machine on this task', {
+        task_id: input.task_id, machine_id: input.machine_id,
+      });
+    }
+    this._validatePhaseProgress(input);
+
+    const now = this.nowMs();
+    this.touchDevice(input.machine_id);
+    this.recordHeartbeatMetrics(input.machine_id, input, now);
+
+    if (task.cancelled) {
+      return { lease_until: rfc3339(lease.lease_until_ms), cancel: true, reason: task.cancel_reason };
+    }
+
+    // §4.3: once halt=now has handed this index to another attempt, the old owner
+    // must stop — a late heartbeat from the expired machine is not a valid re-claim.
+    if (lease.state === 'expired' && task.attempt > lease.attempt) {
+      return { lease_until: rfc3339(lease.lease_until_ms), cancel: true, reason: 'LEASE_EXPIRED_TAKEN_OVER' };
+    }
+
+    const stateBefore = lease.state;
+    lease.last_heartbeat_ms = now;
+    lease.lease_until_ms = now + this.leaseWindowMs();
+    lease.heartbeat_count += 1;
+    if (input.phase !== undefined && input.phase !== null) lease.phase = input.phase;
+    if (input.progress !== undefined && input.progress !== null) lease.progress = input.progress;
+    if (Number.isInteger(input.attempt) && input.attempt >= 1) lease.attempt = input.attempt;
+    if (lease.state === 'queued' || lease.state === 'offered') lease.state = 'running';
+    // A live heartbeat is stronger evidence than a timer: with halt=never nobody took
+    // the work away, so the late-but-alive agent re-claims its own lease.
+    if (lease.state === 'expired') { lease.state = 'running'; lease.expired_at_ms = null; }
+
+    // §7 ledger records lease STATE changes, not every 10s heartbeat.
+    if (lease.state !== stateBefore) this._ledgerLease(task, lease);
+
+    return { lease_until: rfc3339(lease.lease_until_ms), cancel: false, phase: lease.phase, progress: lease.progress };
+  }
+
+  /** §4.3: expiry is decided by Rabbit's clock only. */
+  isLeaseExpired(lease, nowMs = this.nowMs()) {
+    if (!ACTIVE_LEASE_STATES.includes(lease.state)) return false;
+    return nowMs >= lease.lease_until_ms;
+  }
+
+  /**
+   * §4.3 expiry sweep.
+   *  - halt=never → book-keeping only, task is marked `partial`
+   *  - halt=now   → notify remaining machines immediately that they may take over
+   */
+  sweepExpired(nowMs = this.nowMs()) {
+    const expired = [];
+    for (const task of this.tasks.values()) {
+      if (task.cancelled) continue;
+      let changed = false;
+      for (const lease of task.leases.values()) {
+        if (!this.isLeaseExpired(lease, nowMs)) continue;
+        lease.state = 'expired';
+        lease.expired_at_ms = nowMs;
+        changed = true;
+        expired.push({ task, lease });
+        this._ledgerLease(task, lease);
+        this.emit('notice', {
+          level: 'warn',
+          code: 'LEASE_EXPIRED',
+          message: `lease expired: machine=${lease.machine_id} task=${task.task_id} attempt=${lease.attempt}`,
+          task_id: task.task_id,
+          machine_id: lease.machine_id,
+        });
+        if (task.halt === 'now') {
+          task.attempt += 1;
+          this._takeover(task, lease, nowMs);
+        }
+      }
+      if (changed) task.degraded = 'partial';
+    }
+    return expired;
+  }
+
+  /**
+   * §4.3 `halt=now`: "立即通知其他机器可接管".
+   *
+   * v0.0.1's PROTOCOL defines no per-index lease reassignment, so takeover is
+   * implemented as: re-offer the freed `index` (attempt+1) to every live machine
+   * that is idle — no lease yet, or a lease still queued/offered — and broadcast a
+   * notice. Machines already `running` are never re-offered, to avoid double
+   * execution of the same index.
+   */
+  _takeover(task, expiredLease, nowMs = this.nowMs()) {
+    /**
+     * v0.7.8: the two safety guards this path was missing.
+     *
+     * `_takeover` already existed and is invoked on `halt=now`, so hand-off was not absent — but it
+     * would re-offer a dead machine's index to **every idle device the relay holds**, with no fleet
+     * filter and no consideration of whether the task writes. Both are reachable defects:
+     *
+     *   1. **A device in another account could be handed the work.** On a relay serving several
+     *      fleets, `this.devices` includes all of them, so a takeover crossed accounts — which is
+     *      the isolation this release series is about, broken in the one path that is easy to miss
+     *      because it only runs when something has already gone wrong.
+     *   2. **A writing task could be run a second time.** Hand-off makes execution at-least-once,
+     *      which is harmless for `node --test` and is a duplicated write for anything else. The
+     *      design forbids automatic hand-off for writing tasks until a fencing token exists.
+     *
+     * The re-offer shape itself is unchanged: PROTOCOL v0.0.1 defines no per-index lease
+     * reassignment, so takeover is expressed as a re-offer to idle machines. Narrowing that to a
+     * single successor is a protocol revision, not a wiring change, and is not made here.
+     */
+    if (task.write === true) {
+      this.emit('notice', {
+        level: 'warn',
+        code: 'LEASE_TAKEOVER_REFUSED',
+        message:
+          `task ${task.task_id} index ${expiredLease.index} is a writing task, so no machine takes it over: `
+          + 'a second run could apply the same change twice, and the caller cannot tell from the verdict',
+        task_id: task.task_id,
+        reason: 'write_not_idempotent',
+      });
+      return [];
+    }
+
+    const requesterFleet = this.fleetId ?? null;
+
+    const candidates = [];
+    for (const device of this.devices.values()) {
+      if (device.machine_id === expiredLease.machine_id) continue;
+      /**
+       * Fleet membership, when the relay is scoped.
+       *
+       * A device with its own `fleet_id` must match. A device with none cannot take over on a
+       * scoped relay, because there is no fleet to match it against — the same rule `targetsFor`
+       * applies to dispatch, kept identical here so the two paths cannot disagree.
+       */
+      if (requesterFleet !== null) {
+        const deviceFleet = typeof device.fleet_id === 'string' && device.fleet_id !== '' ? device.fleet_id : null;
+        if (deviceFleet !== requesterFleet) {
+          this.log?.('debug', 'takeover candidate skipped: not in this fleet', {
+            task_id: task.task_id,
+            machine_id: device.machine_id,
+            device_fleet: deviceFleet,
+            relay_fleet: requesterFleet,
+          });
+          continue;
+        }
+      }
+      const lease = task.leases.get(device.machine_id);
+      if (lease && !['queued', 'offered'].includes(lease.state)) continue;
+      if (!lease && gateMachine(task, device)) continue;
+      candidates.push({ device, lease: lease ?? null });
+    }
+
+    for (const { device, lease } of candidates) {
+      const target = lease ?? {
+        machine_id: device.machine_id,
+        machine_name: device.machine_name,
+        index: expiredLease.index,
+        attempt: task.attempt,
+        state: 'queued',
+        refusal_reason: null,
+        refusal_detail: null,
+        dedupe_key: null,
+        last_heartbeat_ms: nowMs,
+        claimed_at_ms: nowMs,
+        lease_until_ms: nowMs + this.leaseWindowMs(),
+        phase: null,
+        progress: null,
+        offered_seq: null,
+        expired_at_ms: null,
+        finished_at_ms: null,
+        heartbeat_count: 0,
+      };
+      target.index = expiredLease.index;
+      target.attempt = task.attempt;
+      target.dedupe_key = computeDedupeKey(task.task_id, target.index, task.command_hash, task.base_tree);
+      task.leases.set(device.machine_id, target);
+      this.emitOffer(task, target);
+      this._ledgerLease(task, target);
+    }
+
+    this.emit('notice', {
+      level: 'info',
+      code: candidates.length > 0 ? 'LEASE_TAKEOVER' : 'LEASE_TAKEOVER_UNAVAILABLE',
+      message: candidates.length > 0
+        ? `task ${task.task_id} index ${expiredLease.index} re-offered at attempt ${task.attempt} to: `
+          + candidates.map((c) => c.device.machine_id).join(',')
+        : `task ${task.task_id} index ${expiredLease.index} has no idle machine to take over`,
+      task_id: task.task_id,
+    });
+    return candidates.map((c) => c.device.machine_id);
+  }
+
+  /* ---------------- results (§5) ---------------- */
+
+  static instanceKey(machineId, dedupeKey, attempt) {
+    return `${machineId}${INSTANCE_SEP}${dedupeKey}${INSTANCE_SEP}${attempt}`;
+  }
+
+  /**
+   * §5 result envelope validation.
+   * Missing §5.1 required fields do NOT reject the frame — they make the result
+   * `unverifiable` (§5.1 "缺一即 unverifiable").
+   */
+  static validateEnvelope(envelope) {
+    const missing = [];
+    if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) {
+      return { missing: [...REQUIRED_ENVELOPE_FIELDS], malformed: true };
+    }
+    for (const field of REQUIRED_ENVELOPE_FIELDS) {
+      if (!(field in envelope) || envelope[field] === undefined) missing.push(field);
+    }
+    const problems = [];
+    if ('status' in envelope && !RESULT_STATUSES.includes(envelope.status)) {
+      problems.push(`status must be one of ${RESULT_STATUSES.join('|')}`);
+    }
+    if (envelope.status === 'refused' && !envelope.refusal_reason) {
+      problems.push('refusal_reason is required when status=refused');
+    }
+    if ('warnings' in envelope && !Array.isArray(envelope.warnings)) problems.push('warnings must be string[]');
+    return { missing, problems };
+  }
+
+  /**
+   * §1 idempotent POST /v1/result.
+   *
+   * NOTE (contract ambiguity, see report): §4.4 `dedupe_key` deliberately excludes
+   * `machine_id`/`attempt`, but §6.3 aggregates results from *several* machines in
+   * replicate mode — they all share one dedupe_key. Deduping purely on dedupe_key
+   * would silently drop every machine's result but the first. We therefore key the
+   * idempotency check on (machine_id, dedupe_key, attempt): an identical redelivery
+   * is `deduped:true`, distinct machines/attempts are all recorded.
+   */
+  submitResult(envelope = {}) {
+    const { missing, problems, malformed } = RabbitState.validateEnvelope(envelope);
+    if (malformed) throw new ProtocolError('BAD_REQUEST', 'result must be a JSON object');
+
+    /**
+     * v0.4.0: `transport` / `p2p` are OPTIONAL envelope fields, and they are validated as values
+     * rather than added to the §5.1 required set. A v0.3.9 agent sends neither and must keep
+     * working unchanged; an agent that sends `transport: 'satellite'` is refused by name instead of
+     * storing a value the report would then show as a path that does not exist.
+     */
+    RabbitState.validateTransportFields(envelope);
+
+    const taskId = envelope.task_id;
+    if (typeof taskId !== 'string' || taskId.length === 0) {
+      throw new ProtocolError('BAD_REQUEST', 'task_id is required');
+    }
+    const task = this.tasks.get(taskId);
+    if (!task) throw new ProtocolError('NOT_FOUND', 'unknown task_id', { task_id: taskId });
+
+    const machineId = typeof envelope.machine_id === 'string' ? envelope.machine_id : null;
+    const dedupeKey = typeof envelope.dedupe_key === 'string' && envelope.dedupe_key
+      ? envelope.dedupe_key : null;
+    const attempt = Number.isInteger(envelope.attempt) && envelope.attempt >= 1 ? envelope.attempt : 1;
+
+    if (dedupeKey === null) {
+      // Cannot dedupe without a key; still record it, as unverifiable.
+      missing.push('dedupe_key');
+    }
+    const instanceKey = RabbitState.instanceKey(machineId ?? '<unknown>', dedupeKey ?? '<none>', attempt);
+
+    // §4.4 sanity check against the lease this machine actually holds. Booked as a
+    // problem instead of a hard rejection so a buggy client cannot lose its result.
+    const leaseForMachine = machineId ? task.leases.get(machineId) : null;
+    if (leaseForMachine?.dedupe_key && dedupeKey && leaseForMachine.dedupe_key !== dedupeKey) {
+      problems.push('dedupe_key does not match the §4.4 formula for this lease');
+    }
+
+    if (this.results.has(instanceKey)) {
+      const prior = this.results.get(instanceKey);
+      return { deduped: true, task_id: taskId, dedupe_key: dedupeKey, seq: prior.seq };
+    }
+
+    const now = this.nowMs();
+    let envelopeShaOk = null;
+    if (typeof envelope.envelope_sha256 === 'string') {
+      const { envelope_sha256: _drop, ...rest } = envelope;
+      envelopeShaOk = sha256Hex(jcs(rest)) === envelope.envelope_sha256;
+    }
+
+    const record = {
+      envelope,
+      machine_id: machineId,
+      dedupe_key: dedupeKey,
+      attempt,
+      instance_key: instanceKey,
+      received_at_ms: now,
+      validation: {
+        missing: [...new Set(missing)],
+        problems,
+        envelope_sha256_ok: envelopeShaOk,
+      },
+    };
+
+    const effectiveStatus = record.validation.missing.length > 0 ? 'unverifiable' : envelope.status;
+
+    const seq = this.nextSeq();
+    record.seq = seq;
+    record.effective_status = effectiveStatus;
+    this.results.set(instanceKey, record);
+
+    if (machineId) {
+      const lease = task.leases.get(machineId);
+      if (lease) {
+        lease.state = effectiveStatus === 'refused' ? 'refused' : 'done';
+        if (effectiveStatus === 'refused' && !lease.refusal_reason) {
+          lease.refusal_reason = envelope.refusal_reason ?? 'REFUSED';
+        }
+        lease.finished_at_ms = now;
+        lease.attempt = attempt;
+      }
+      this.touchDevice(machineId);
+    }
+    task.result_seqs.push(seq);
+
+    this.emit('task.result', {
+      task_id: taskId,
+      dedupe_key: dedupeKey,
+      attempt,
+      index: envelope.index ?? null,
+      status: effectiveStatus,
+      machine_id: machineId,
+      deduped: false,
+      validation_errors: record.validation.missing,
+    });
+
+    // §7: results go into the ledger so the dedupe index survives a restart.
+    this._ledger({ type: 'result.stored', task_id: taskId, machine_id: machineId, result: record });
+    if (machineId) {
+      const changed = task.leases.get(machineId);
+      if (changed) this._ledgerLease(task, changed);
+    }
+
+    return { deduped: false, task_id: taskId, dedupe_key: dedupeKey, seq, _instanceKey: instanceKey };
+  }
+
+  /** All recorded results for a task, keyed by machine_id (later attempts win). */
+  taskResults(taskId) {
+    const task = this.tasks.get(taskId);
+    if (!task) return new Map();
+    const out = new Map();
+    for (const rec of this.results.values()) {
+      if (rec.envelope.task_id !== taskId) continue;
+      const prev = out.get(rec.machine_id);
+      if (!prev || rec.received_at_ms >= prev.received_at_ms) out.set(rec.machine_id, rec);
+    }
+    return out;
+  }
+
+  /** Global dedupe book-keeping: dedupe_key -> instances seen. */
+  dedupeReport() {
+    const out = {};
+    for (const rec of this.results.values()) {
+      if (!rec.dedupe_key) continue;
+      out[rec.dedupe_key] = out[rec.dedupe_key] ?? [];
+      out[rec.dedupe_key].push({
+        machine_id: rec.machine_id,
+        attempt: rec.attempt,
+        received_at: rfc3339(rec.received_at_ms),
+      });
+    }
+    return out;
+  }
+
+  /* ---------------- serialization ---------------- */
+
+  stats() {
+    return {
+      protocol_version: PROTOCOL_VERSION,
+      seq: this.seq,
+      buffered_events: this.buffer.length,
+      devices: this.devices.size,
+      tasks: this.tasks.size,
+      results: this.results.size,
+      pairing_codes: [...this.pairingCodes.values()].filter((c) => !c.used && this.nowMs() < c.expires_at_ms).length,
+      uptime_ms: this.nowMs() - this.startedAtMs,
+    };
+  }
+}
+
+export default RabbitState;