@twinsearth/w2m-dsh-plugin 2.0.8 → 2.0.10

package/src/agent/discovery.mjs

@@ -0,0 +1,81 @@
+/**
+ * W3 discovery seam: providers only produce candidate addresses.
+ *
+ * Current order is relay -> mDNS -> DHT. A candidate is never an authorisation:
+ * the dial path still verifies the peer's static key and the task identity.
+ * Adding a DHT sidecar later means implementing the same `discover(machineId)`
+ * shape; it does not change the transport or the relay.
+ */
+
+export const DISCOVERY_SOURCE = Object.freeze({
+  RELAY: 'relay',
+  MDNS: 'mdns',
+  DHT: 'dht',
+});
+
+/** Order used only to break duplicate-address ties, not to trust a source. */
+const SOURCE_RANK = Object.freeze({
+  [DISCOVERY_SOURCE.RELAY]: 0,
+  [DISCOVERY_SOURCE.MDNS]: 1,
+  [DISCOVERY_SOURCE.DHT]: 2,
+});
+
+const usable = (candidate) => candidate !== null
+  && typeof candidate === 'object'
+  && typeof candidate.address === 'string'
+  && candidate.address !== ''
+  && candidate.address !== '0.0.0.0'
+  && candidate.address !== '::'
+  && Number.isInteger(candidate.port)
+  && candidate.port > 0
+  && candidate.port <= 65535;
+
+/**
+ * Merge candidates from every provider, deduplicating by address:port.
+ * The first source in rank order wins the label; the address itself is kept
+ * once. No provider can inject a non-address payload into this list.
+ */
+export function mergeCandidates(lists, { limit = 8 } = {}) {
+  const merged = [];
+  const seen = new Set();
+  const sorted = [...lists].sort((a, b) => (SOURCE_RANK[a.source] ?? 9) - (SOURCE_RANK[b.source] ?? 9));
+  for (const list of sorted) {
+    for (const candidate of Array.isArray(list.candidates) ? list.candidates : []) {
+      if (!usable(candidate)) continue;
+      const key = candidate.address + ':' + candidate.port;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      merged.push({ address: candidate.address, port: candidate.port, source: list.source ?? candidate.source ?? 'unknown' });
+      if (merged.length >= limit) return merged;
+    }
+  }
+  return merged;
+}
+
+/** Relay discovery, built on the existing authenticated /v1/peer route. */
+export function createRelayDiscovery({ getJson } = {}) {
+  if (typeof getJson !== 'function') return { ok: false, code: 'DISCOVERY_NO_GET_JSON' };
+  return {
+    ok: true,
+    source: DISCOVERY_SOURCE.RELAY,
+    async discover(machineId) {
+      if (typeof machineId !== 'string' || machineId === '') return { ok: false, code: 'DISCOVERY_BAD_MACHINE_ID', candidates: [] };
+      const answer = await getJson('/v1/peer/' + encodeURIComponent(machineId));
+      if (answer?.ok !== true || answer?.status === 404) return { ok: false, code: 'DISCOVERY_RELAY_MISS', candidates: [] };
+      const candidates = Array.isArray(answer?.json?.peer?.candidates) ? answer.json.peer.candidates : [];
+      return { ok: true, source: DISCOVERY_SOURCE.RELAY, candidates, staticKey: answer?.json?.peer?.static_key ?? null };
+    },
+  };
+}
+
+/**
+ * A provider for tests and for an injected mDNS implementation. It carries no
+ * network logic, so the caller decides how candidates were observed.
+ */
+export function createStaticDiscovery({ source, candidates = [] } = {}) {
+  return {
+    ok: true,
+    source: source ?? 'static',
+    async discover() { return { ok: true, source: source ?? 'static', candidates: candidates.slice() }; },
+  };
+}

package/src/agent/iroh-sidecar.mjs

@@ -0,0 +1,149 @@
+/**
+ * W1 spike: iroh sidecar transport (JSON over length-prefixed stdio).
+ *
+ * The real binary is intentionally not bundled or auto-downloaded: the sidecar
+ * command/args come from configuration and are verified by the caller. This
+ * module owns only the process lifecycle and the frame contract, so a fake
+ * sidecar can exercise every failure path in CI without Rust or a TLS relay.
+ *
+ * Wire (parent -> child and child -> parent): 4-byte big-endian length + UTF-8 JSON.
+ *   { id, method, params }            request
+ *   { id, result } / { id, error }    response
+ *   { type: 'ready' }                 child is listening
+ *   { type: 'message', peer, data }   inbound payload (base64)
+ *   { type: 'status', paths, ... }    diagnostics
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+
+export const IROH_TRANSPORT = 'iroh-v1';
+export const IROH_CODE = Object.freeze({
+  START_FAILED: 'IROH_SIDECAR_START_FAILED',
+  TIMEOUT: 'IROH_TIMEOUT',
+  EXITED: 'IROH_SIDECAR_EXITED',
+  CLOSED: 'IROH_CLOSED',
+  BAD_FRAME: 'IROH_BAD_FRAME',
+});
+
+function encode(value) {
+  const body = Buffer.from(JSON.stringify(value), 'utf8');
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(body.length);
+  return Buffer.concat([header, body]);
+}
+
+export function createIrohSidecarTransport({ command, args = [], env = {}, timeoutMs = 2500, spawnImpl = nodeSpawn } = {}) {
+  if (typeof command !== 'string' || command === '') {
+    return { ok: false, code: IROH_CODE.START_FAILED, detail: 'iroh sidecar command is required' };
+  }
+  const handlers = new Set();
+  const pending = new Map();
+  let child = null;
+  let buffer = Buffer.alloc(0);
+  let nextId = 1;
+  let ready = null;
+  let closed = false;
+  let lastStatus = { paths: [] };
+
+  const failPending = (code, detail) => {
+    for (const [id, entry] of pending) {
+      clearTimeout(entry.timer);
+      entry.reject(Object.assign(new Error(detail ?? code), { code }));
+      pending.delete(id);
+    }
+  };
+
+  const onFrame = (message) => {
+    if (message?.type === 'ready') { ready?.(); ready = null; return; }
+    if (message?.type === 'message') {
+      const payload = Buffer.from(String(message.data ?? ''), 'base64');
+      for (const handler of handlers) handler({ peer: message.peer ?? null, payload });
+      return;
+    }
+    if (message?.type === 'status') { lastStatus = { paths: Array.isArray(message.paths) ? message.paths : [] }; return; }
+    if (typeof message?.id === 'number' && pending.has(message.id)) {
+      const entry = pending.get(message.id);
+      clearTimeout(entry.timer);
+      pending.delete(message.id);
+      if (message.error) entry.reject(Object.assign(new Error(String(message.error.message ?? message.error)), { code: message.error.code ?? IROH_CODE.EXITED }));
+      else entry.resolve(message.result ?? null);
+    }
+  };
+
+  const onData = (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length >= 4) {
+      const length = buffer.readUInt32BE(0);
+      if (buffer.length < 4 + length) return;
+      const body = buffer.subarray(4, 4 + length);
+      buffer = buffer.subarray(4 + length);
+      try { onFrame(JSON.parse(body.toString('utf8'))); } catch { /* a bad frame is dropped, not fatal */ }
+    }
+  };
+
+  const rpc = (method, params = {}) => new Promise((resolve, reject) => {
+    if (closed || child === null) { reject(Object.assign(new Error(IROH_CODE.CLOSED), { code: IROH_CODE.CLOSED })); return; }
+    const id = nextId;
+    nextId += 1;
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(Object.assign(new Error(IROH_CODE.TIMEOUT), { code: IROH_CODE.TIMEOUT }));
+    }, timeoutMs);
+    timer.unref?.();
+    pending.set(id, { resolve, reject, timer });
+    child.stdin.write(encode({ id, method, params }));
+  });
+
+  const transport = {
+    name: IROH_TRANSPORT,
+    async start() {
+      return new Promise((resolve) => {
+        try {
+          child = spawnImpl(command, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env: { ...process.env, ...env } });
+        } catch (error) {
+          resolve({ ok: false, code: IROH_CODE.START_FAILED, detail: error instanceof Error ? error.message : String(error) });
+          return;
+        }
+        const timer = setTimeout(() => { resolve({ ok: false, code: IROH_CODE.START_FAILED, detail: IROH_CODE.TIMEOUT }); }, timeoutMs);
+        ready = () => { clearTimeout(timer); resolve({ ok: true, name: IROH_TRANSPORT }); };
+        child.stdout.on('data', onData);
+        child.stderr.on('data', () => {});
+        child.on('exit', () => {
+          closed = true;
+          clearTimeout(timer);
+          failPending(IROH_CODE.EXITED, 'iroh sidecar exited');
+          if (ready !== null) { ready = null; resolve({ ok: false, code: IROH_CODE.START_FAILED, detail: 'sidecar exited before ready' }); }
+        });
+        child.on('error', (error) => {
+          closed = true;
+          clearTimeout(timer);
+          resolve({ ok: false, code: IROH_CODE.START_FAILED, detail: error.message });
+        });
+      });
+    },
+    async send(peer, payload) {
+      if (closed || child === null) return { ok: false, code: IROH_CODE.CLOSED };
+      try {
+        await rpc('send', { peer, data: Buffer.from(payload).toString('base64') });
+        return { ok: true, peer };
+      } catch (error) {
+        return { ok: false, code: error.code ?? IROH_CODE.EXITED, detail: error.message };
+      }
+    },
+    onMessage(handler) {
+      if (typeof handler !== 'function') return () => {};
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    paths() { return lastStatus.paths.map((path) => ({ ...path, transport: IROH_TRANSPORT })); },
+    diagnostics() { return { name: IROH_TRANSPORT, closed, pending: pending.size, paths: lastStatus.paths.length }; },
+    async stop() {
+      if (closed) return { ok: true };
+      closed = true;
+      failPending(IROH_CODE.CLOSED, 'transport stopped');
+      try { child?.stdin.end(); child?.kill(); } catch { /* already gone */ }
+      child = null;
+      return { ok: true };
+    },
+  };
+  return { ok: true, transport };
+}

package/src/agent/p2p-node.mjs

@@ -1232,7 +1232,7 @@ export class P2PNode extends EventEmitter {
      * that publishes no key is genuinely an older build and `PLAINTEXT_PEER` is honest; a peer that
      * publishes one we had not learned is *our* gap, and after this it is not a gap at all.
      */
-    let peerKey = this.peerKeys.get(machineId);
+    let peerKey = typeof options.peerKey === 'string' && options.peerKey !== '' ? options.peerKey : this.peerKeys.get(machineId);
     if (peerKey === null && announcedStaticKey !== null) {
       this.peerKeys.set(machineId, announcedStaticKey, 'relay');
       peerKey = announcedStaticKey;
@@ -1497,6 +1497,16 @@ export class P2PNode extends EventEmitter {
    * @param {import('./p2p.mjs').P2PChannel} channel
    * @param {{from:string|null, session:number}} details
    */
+  /** Close and forget a cached channel so a fresh dial can arm a new handshake. */
+  dropChannel(session) {
+    const channel = this.channels.get(session);
+    if (channel === undefined) return false;
+    this.channels.delete(session);
+    this.claimed.delete(session);
+    try { channel.close('replaced-by-rehandshake', { silent: true }); } catch { /* already gone */ }
+    return true;
+  }
+
   adoptChannel(channel, details) {
     const previous = this.channels.get(details.session);
     if (previous !== undefined && previous !== channel) {

package/src/agent/p2p-race.mjs

@@ -0,0 +1,105 @@
+/**
+ * Multi-transport race: capability negotiation + first-usable-path wins.
+ *
+ * The control plane never waits for this. A dispatch goes through the relay
+ * immediately; this race only decides which data-channel carries results.
+ * There is deliberately no relay fallback here: if every transport loses, the
+ * caller gets ALL_TRANSPORTS_FAILED and the task result stays on the control
+ * plane, which is a different (and already-working) path.
+ */
+
+export const TRANSPORT_PRIORITY = Object.freeze(['iroh', 'udp']);
+
+/**
+ * Intersect the local and remote capability lists.
+ * A peer that declares nothing is an older build and gets the UDP path only.
+ *
+ * @param {{local?: string[], remote?: string[]|null, priority?: string[]}} input
+ * @returns {string[]} ordered transport names both ends can attempt
+ */
+export function negotiateTransports({ local = ['udp'], remote = null, priority = TRANSPORT_PRIORITY } = {}) {
+  const localSet = new Set(local.filter((name) => typeof name === 'string'));
+  const remoteSet = remote === null ? new Set(['udp']) : new Set(remote.filter((name) => typeof name === 'string'));
+  return priority.filter((name) => localSet.has(name) && remoteSet.has(name));
+}
+
+/**
+ * Run every candidate's start() concurrently and resolve with the first channel.
+ * The losers are aborted as soon as a winner exists (or the total budget expires).
+ *
+ * @param {{
+ *   candidates: Array<{name: string, timeoutMs?: number, start: (ctx: {signal: AbortSignal}) => Promise<any>}>,
+ *   budgetMs?: number,
+ *   now?: () => number,
+ * }} input
+ * @returns {Promise<{ok: true, name: string, channel: any, attempts: object[], elapsedMs: number}
+ *   | {ok: false, code: 'ALL_TRANSPORTS_FAILED'|'NO_TRANSPORTS', attempts: object[], elapsedMs: number}>}
+ */
+export async function raceTransports({ candidates, budgetMs = 3000, now = Date.now } = {}) {
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    return { ok: false, code: 'NO_TRANSPORTS', attempts: [], elapsedMs: 0 };
+  }
+  const startedAt = now();
+  const attempts = [];
+  const controllers = new Map();
+  let settled = false;
+  let resolveRace = null;
+  const race = new Promise((resolve) => { resolveRace = resolve; });
+
+  const finish = (result) => {
+    if (settled) return;
+    settled = true;
+    for (const [name, controller] of controllers.entries()) {
+      if (result.ok === true && result.name === name) continue; // the winner keeps its channel
+      controller.abort();
+    }
+    resolveRace({ ...result, elapsedMs: now() - startedAt });
+  };
+
+  const budgetTimer = setTimeout(() => {
+    finish({ ok: false, code: 'ALL_TRANSPORTS_FAILED', attempts });
+  }, budgetMs);
+  budgetTimer.unref?.();
+
+  for (const candidate of candidates) {
+    if (typeof candidate?.start !== 'function') continue;
+    const controller = new AbortController();
+    controllers.set(candidate.name, controller);
+    const record = { name: candidate.name, ok: false, code: null, elapsedMs: null };
+    attempts.push(record);
+    const started = now();
+    const timer = setTimeout(() => {
+      record.code = 'TRANSPORT_TIMEOUT';
+      record.elapsedMs = now() - started;
+      controller.abort();
+      if (attempts.every((attempt) => attempt.elapsedMs !== null) && attempts.every((attempt) => attempt.ok !== true)) {
+        finish({ ok: false, code: 'ALL_TRANSPORTS_FAILED', attempts });
+      }
+    }, Number.isFinite(candidate.timeoutMs) ? candidate.timeoutMs : budgetMs);
+    timer.unref?.();
+    Promise.resolve()
+      .then(() => candidate.start({ signal: controller.signal }))
+      .then((channel) => {
+        clearTimeout(timer);
+        if (settled) return;
+        record.ok = true;
+        record.elapsedMs = now() - started;
+        finish({ ok: true, name: candidate.name, channel, attempts });
+      })
+      .catch((error) => {
+        clearTimeout(timer);
+        if (settled) return;
+        record.code = error?.code ?? 'TRANSPORT_FAILED';
+        record.message = error instanceof Error ? error.message : String(error);
+        record.elapsedMs = now() - started;
+        if (attempts.every((attempt) => attempt.ok !== true && attempt.elapsedMs !== null)) {
+          finish({ ok: false, code: 'ALL_TRANSPORTS_FAILED', attempts });
+        }
+      });
+  }
+
+  const result = await race;
+  clearTimeout(budgetTimer);
+  if (result.ok !== true) return result;
+  return result;
+}

package/src/agent/p2p.mjs

@@ -114,6 +114,42 @@ export const DEFAULT_WINDOW = 32;
 export const DEFAULT_RTO_MS = 300;
 export const MAX_RTO_MS = 3000;
 
+/**
+ * RFC 6298 RTT estimator. The old channel used a constant 300 ms RTO, which is
+ * wrong on both a LAN (too slow) and a lossy WAN (too fast). This keeps SRTT and
+ * RTTVAR and clamps the result; callers still apply per-attempt exponential
+ * backoff on top.
+ */
+export class RttEstimator {
+  constructor({ initialRtoMs = DEFAULT_RTO_MS, minRtoMs = 100, maxRtoMs = MAX_RTO_MS } = {}) {
+    this.srtt = null;
+    this.rttvar = null;
+    this.minRtoMs = minRtoMs;
+    this.maxRtoMs = maxRtoMs;
+    this.rtoMs = Math.min(maxRtoMs, Math.max(minRtoMs, initialRtoMs));
+  }
+
+  sample(rttMs) {
+    if (!Number.isFinite(rttMs) || rttMs < 0) return this.rtoMs;
+    if (this.srtt === null) {
+      this.srtt = rttMs;
+      this.rttvar = rttMs / 2;
+    } else {
+      this.rttvar = 0.75 * this.rttvar + 0.25 * Math.abs(this.srtt - rttMs);
+      this.srtt = 0.875 * this.srtt + 0.125 * rttMs;
+    }
+    this.rtoMs = Math.min(this.maxRtoMs, Math.max(this.minRtoMs, this.srtt + 4 * this.rttvar));
+    return this.rtoMs;
+  }
+
+  reset() {
+    this.srtt = null;
+    this.rttvar = null;
+    this.rtoMs = Math.min(this.maxRtoMs, Math.max(this.minRtoMs, DEFAULT_RTO_MS));
+  }
+}
+
+
 /** Retransmits per fragment before the message is declared undeliverable. */
 export const DEFAULT_MAX_ATTEMPTS = 8;
 
@@ -985,9 +1021,14 @@ export class P2PChannel extends EventEmitter {
     this.session = options.session;
     this.tuning = {
       window: options.tuning?.window ?? DEFAULT_WINDOW,
+      maxWindow: options.tuning?.maxWindow ?? 256,
       rtoMs: options.tuning?.rtoMs ?? DEFAULT_RTO_MS,
       maxAttempts: options.tuning?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
     };
+    /** Adaptive send window: starts at the tuning value, grows on completed messages. */
+    this.window = this.tuning.window;
+    /** RTT/RTO measured from ACK arrival, instead of the fixed 300 ms default. */
+    this.rtt = new RttEstimator({ initialRtoMs: this.tuning.rtoMs, maxRtoMs: MAX_RTO_MS });
 
     const crypto = options.crypto ?? null;
     /** @type {CryptoSession|null} */
@@ -1150,11 +1191,25 @@ export class P2PChannel extends EventEmitter {
     const entry = this.outgoing.get(messageId);
     if (!entry) return;
     entry.acked.add(index);
+    entry.inFlight.delete(index);
+    // Karn: a fragment that was retransmitted has an ambiguous RTT, so only the
+    // first transmission is sampled.
+    if (entry.sentAt.has(index) && !entry.retransmitted.has(index)) {
+      this.rtt.sample(Date.now() - entry.sentAt.get(index));
+      entry.sentAt.delete(index);
+    }
     if (entry.acked.size === entry.fragments.length) {
       this.outgoing.delete(messageId);
       clearTimeout(entry.timer);
+      // A completed message is the only honest RTT-free signal that the path holds more
+      // than the previous window: grow conservatively, and halve on a retransmit timeout.
+      this.window = Math.min(this.tuning.maxWindow, this.window + Math.max(1, Math.floor(this.window / 8)));
       entry.resolve();
+      return;
     }
+    // ACK-driven progress: the next window leaves as soon as a slot frees, instead of
+    // waiting for the RTO timer (the 0.12 MiB/s ceiling).
+    if (entry.pump !== null) entry.pump();
   }
 
   /**
@@ -1207,6 +1262,10 @@ export class P2PChannel extends EventEmitter {
       const entry = {
         fragments,
         acked: new Set(),
+        inFlight: new Set(),
+        sentAt: new Map(),
+        retransmitted: new Set(),
+        pump: null,
         resolve,
         reject,
         attempts: new Map(),
@@ -1215,45 +1274,73 @@ export class P2PChannel extends EventEmitter {
 
       const pump = () => {
         if (this.closed) return;
-        const pending = [];
-        for (let i = 0; i < fragments.length; i += 1) {
-          if (entry.acked.has(i)) continue;
-          pending.push(i);
-          if (pending.length >= this.tuning.window) break;
-        }
-        if (pending.length === 0) return;
-
-        for (const index of pending) {
-          const attempt = (entry.attempts.get(index) ?? 0) + 1;
-          entry.attempts.set(index, attempt);
+        // Send only what the current window has room for. inFlight is the honest
+        // count of fragments the peer has not acknowledged yet; re-sending those
+        // is the timer's job, not pump's.
+        let budget = Math.max(1, this.window - entry.inFlight.size);
+        for (let i = 0; i < fragments.length && budget > 0; i += 1) {
+          if (entry.acked.has(i) || entry.inFlight.has(i)) continue;
+          const attempt = (entry.attempts.get(i) ?? 0) + 1;
+          entry.attempts.set(i, attempt);
           if (attempt > this.tuning.maxAttempts) {
             this.outgoing.delete(messageId);
+            clearTimeout(entry.timer);
+            this.window = Math.max(8, Math.floor(this.window / 2));
             reject(
               new Error(
-                `P2P_FRAGMENT_UNACKED: fragment ${index}/${fragments.length} of message ${messageId} ` +
+                `P2P_FRAGMENT_UNACKED: fragment ${i}/${fragments.length} of message ${messageId} ` +
                   `after ${this.tuning.maxAttempts} attempts`,
               ),
             );
             return;
           }
-          const body = Buffer.alloc(12 + fragments[index].length);
+          entry.inFlight.add(i);
+          if (!entry.sentAt.has(i)) entry.sentAt.set(i, Date.now());
+          budget -= 1;
+          const body = Buffer.alloc(12 + fragments[i].length);
           body.writeUInt32BE(messageId, 0);
-          body.writeUInt32BE(index, 4);
+          body.writeUInt32BE(i, 4);
           body.writeUInt32BE(fragments.length, 8);
-          fragments[index].copy(body, 12);
+          fragments[i].copy(body, 12);
           this.sendFrame(KIND.DATA, body);
         }
 
-        const worst = Math.max(...pending.map((i) => entry.attempts.get(i) ?? 1));
-        const delay = Math.min(this.tuning.rtoMs * 2 ** (worst - 1), MAX_RTO_MS);
+        if (entry.inFlight.size === 0) return;
+        const worst = Math.max(...[...entry.inFlight].map((i) => entry.attempts.get(i) ?? 1));
+        const delay = Math.min(this.rtt.rtoMs * 2 ** (worst - 1), MAX_RTO_MS);
         // One timer per message, not one per channel: a shared field means a second
         // concurrent send silently cancels the first one's retransmission schedule.
         clearTimeout(entry.timer);
         entry.timer = setTimeout(() => {
-          if (this.outgoing.has(messageId)) pump();
+          if (!this.outgoing.has(messageId)) return;
+          // Retransmit the fragments that are still unacknowledged, then schedule again.
+          for (const i of entry.inFlight) {
+            entry.retransmitted.add(i);
+            const attempt = (entry.attempts.get(i) ?? 0) + 1;
+            entry.attempts.set(i, attempt);
+            if (attempt > this.tuning.maxAttempts) {
+              this.outgoing.delete(messageId);
+              this.window = Math.max(8, Math.floor(this.window / 2));
+              reject(
+                new Error(
+                  `P2P_FRAGMENT_UNACKED: fragment ${i}/${fragments.length} of message ${messageId} ` +
+                    `after ${this.tuning.maxAttempts} attempts`,
+                ),
+              );
+              return;
+            }
+            const body = Buffer.alloc(12 + fragments[i].length);
+            body.writeUInt32BE(messageId, 0);
+            body.writeUInt32BE(i, 4);
+            body.writeUInt32BE(fragments.length, 8);
+            fragments[i].copy(body, 12);
+            this.sendFrame(KIND.DATA, body);
+          }
+          pump();
         }, delay);
         entry.timer.unref?.();
       };
+      entry.pump = pump;
 
       pump();
     });

package/src/agent/path-scheduler.mjs

@@ -0,0 +1,106 @@
+/**
+ * PathScheduler: score candidate paths, and switch only on sustained evidence.
+ *
+ * This is deliberately pure policy: no sockets, no timers beyond the overlap
+ * deadline it reports. The caller opens the challenger, keeps the old path for
+ * `keepUntilMs` (make-before-break), then closes it.
+ */
+
+export const PATH_KIND = Object.freeze({
+  IROH_DIRECT: 'iroh-direct',
+  UDP_DIRECT: 'udp-direct',
+  LIBP2P: 'libp2p',
+  IROH_RELAY: 'iroh-relay',
+  CONTROL_PLANE: 'control-plane',
+});
+
+/** Higher is better. The type weight dominates; latency and loss refine it. */
+export const PATH_WEIGHT = Object.freeze({
+  [PATH_KIND.IROH_DIRECT]: 5,
+  [PATH_KIND.UDP_DIRECT]: 4,
+  [PATH_KIND.LIBP2P]: 3,
+  [PATH_KIND.IROH_RELAY]: 2,
+  [PATH_KIND.CONTROL_PLANE]: 1,
+});
+
+export const SCHEDULER_CODE = Object.freeze({
+  OK: 'PATH_OK',
+  NOT_ENCRYPTED: 'PATH_NOT_ENCRYPTED',
+  NO_CANDIDATES: 'PATH_NO_CANDIDATES',
+  SWITCH_PENDING: 'PATH_SWITCH_PENDING',
+  ALL_FAILED: 'ALL_TRANSPORTS_FAILED',
+});
+
+/**
+ * @param {{kind: string, encrypted: boolean, firstFrameRttMs: number, lossRate: number}} path
+ * @returns {number} score; encrypted paths outrank plaintext by a wide margin
+ */
+export function scorePath({ kind, encrypted, firstFrameRttMs = 0, lossRate = 0 }) {
+  const weight = PATH_WEIGHT[kind] ?? 0;
+  if (encrypted !== true) return -1;
+  if (!Number.isFinite(weight) || weight <= 0) return -1;
+  const rtt = Number.isFinite(firstFrameRttMs) ? Math.max(0, firstFrameRttMs) : 1000;
+  const loss = Number.isFinite(lossRate) ? Math.min(1, Math.max(0, lossRate)) : 1;
+  return weight * 1000 - rtt - loss * 2000;
+}
+
+/**
+ * A path switch is allowed only when:
+ *   - the challenger is encrypted;
+ *   - two consecutive samples beat the current path by > 20%;
+ *   - the challenger's kind is at least as preferred as the current one
+ *     (no switching down to a relay while a direct path is healthy).
+ */
+export class PathScheduler {
+  constructor({ overlapMs = 5000, improvement = 1.2, requiredSamples = 2, now = Date.now } = {}) {
+    this.overlapMs = overlapMs;
+    this.improvement = improvement;
+    this.requiredSamples = requiredSamples;
+    this.now = now;
+    this.current = null;
+    this.challenger = null;
+    this.leading = 0;
+    this.lastPlan = null;
+  }
+
+  setCurrent(path) {
+    this.current = path;
+    this.challenger = null;
+    this.leading = 0;
+    return this.current;
+  }
+
+  /** Record one challenger sample; returns a switch plan or null. */
+  observe(path) {
+    if (path?.encrypted !== true) return null;
+    const challengerScore = scorePath(path);
+    const currentScore = this.current === null ? Number.NEGATIVE_INFINITY : scorePath(this.current);
+    if (currentScore === Number.NEGATIVE_INFINITY) {
+      this.current = path;
+      return { switch: false, reason: 'first-path', path };
+    }
+    const sameChallenger = this.challenger !== null && this.challenger.id === path.id;
+    if (challengerScore > currentScore * this.improvement) {
+      this.challenger = path;
+      this.leading = sameChallenger ? this.leading + 1 : 1;
+      if (this.leading < this.requiredSamples) return null;
+      if ((PATH_WEIGHT[path.kind] ?? 0) < (PATH_WEIGHT[this.current.kind] ?? 0)) return null;
+      const plan = { switch: true, from: this.current, to: path, keepUntilMs: this.now() + this.overlapMs, reason: 'better-path' };
+      this.lastPlan = plan;
+      this.current = path;
+      this.challenger = null;
+      this.leading = 0;
+      return plan;
+    }
+    this.challenger = path;
+    this.leading = 0;
+    return null;
+  }
+
+  /** Close the loser only after the overlap window has elapsed. */
+  breakOld(plan, atMs = this.now()) {
+    if (plan?.switch !== true) return { ok: false, code: SCHEDULER_CODE.NOT_ENCRYPTED };
+    if (atMs < plan.keepUntilMs) return { ok: false, code: SCHEDULER_CODE.SWITCH_PENDING, closeAtMs: plan.keepUntilMs };
+    return { ok: true, close: plan.from };
+  }
+}