@twinsearth/w2m-dsh-plugin 2.0.8 → 2.0.9

package/lib/client.js

@@ -501,6 +501,11 @@ const PLUGIN_UPDATE_ROUTE = '/api/w2m/plugin-update';
   '.w2mChat_emoji{padding:2px 4px;border:0;background:transparent;font-size:16px;line-height:1;cursor:pointer}',
   '.w2mFleetStatus{display:flex;gap:16px;align-items:center;justify-content:center;width:100%;padding:2px 12px;font-size:11px;opacity:.8;white-space:nowrap}',
   '.w2mFleetStatusItem{white-space:nowrap}',
+  '.w2mRelayItem{display:inline-flex;align-items:center;gap:4px}',
+  '.w2mRelayDot{width:8px;height:8px;border-radius:50%;display:inline-block;background:var(--dsw-alias-state-idle-primary)}',
+  '.w2mRelayDot[data-state="green"]{background:var(--dsw-alias-state-success-primary)}',
+  '.w2mRelayDot[data-state="yellow"]{background:var(--dsw-alias-state-warn-primary)}',
+  '.w2mRelayDot[data-state="red"]{background:var(--dsw-alias-state-danger-primary)}',
     '.w2mSearchToggle{height:26px;width:26px;border:0;border-radius:6px;background:transparent;color:inherit;font-size:14px;cursor:pointer}',
   '.w2mSearchToggle:hover{background:rgba(127,127,127,.14)}',
   '.w2mSearchBox{display:flex;align-items:center;gap:4px;padding:2px 4px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-background-secondary)}',
@@ -2080,12 +2085,33 @@ function TargetSelect({ sessionId, locked: _locked, t }) {
         return () => { alive = false; clearInterval(timer); };
       }, []);
       const fleet = snapshot?.fleet ?? null;
-      const server = snapshot?.server ?? null;
+      const relays = snapshot?.relays ?? null;
+      const server = relays?.server ?? null;
       const fleetText = fleet && Number.isFinite(fleet.online) && Number.isFinite(fleet.total) ? fleet.online + '/' + fleet.total : '—';
       const serverText = server && Number.isFinite(server.devices_online) && Number.isFinite(server.devices_total) ? server.devices_online + '/' + server.devices_total : '—';
-      return h('div', { className: 'w2mFleetStatus', title: '编队与服务器在线数量' }, [
+      const relayItems = Array.isArray(relays?.shown) ? relays.shown.slice(0, 3) : [];
+      const relayLabel = (index) => (['主', '备1', '备2'][index] ?? ('备' + index));
+      const relayDot = (relay) => {
+        if (relay?.ok !== true) return 'red';
+        if (Number.isFinite(relay.rtt_ms) && relay.rtt_ms > 500) return 'yellow';
+        return 'green';
+      };
+      const relayTitle = (relay) => {
+        if (relay?.ok !== true) return (relay?.url ?? 'relay') + '：离线' + (relay?.error ? '（' + relay.error + '）' : '');
+        return (relay?.url ?? 'relay') + '：在线，' + (Number.isFinite(relay?.rtt_ms) ? relay.rtt_ms + 'ms' : '延迟未知');
+      };
+      return h('div', { className: 'w2mFleetStatus', title: '编队、全服与 Relay 在线状态' }, [
         h('span', { key: 'f', className: 'w2mFleetStatusItem' }, '本编队在线 ' + fleetText),
-        h('span', { key: 's', className: 'w2mFleetStatusItem' }, '全部机器在线 ' + serverText),
+        h('span', { key: 's', className: 'w2mFleetStatusItem' }, '全服机器在线 ' + serverText),
+        h('span', { key: 'r', className: 'w2mFleetStatusItem' }, [
+          h('span', { key: 'label' }, '在线Relay '),
+          ...(relayItems.length === 0
+            ? [h('span', { key: 'none' }, '—')]
+            : relayItems.map((relay, index) => h('span', { key: 'relay-' + index, className: 'w2mRelayItem', title: relayTitle(relay) }, [
+                h('span', { key: 'dot', className: 'w2mRelayDot', 'data-state': relayDot(relay) }),
+                h('span', { key: 'name' }, relayLabel(index)),
+              ]))),
+        ]),
       ]);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "type": "module",
   "exports": {
@@ -48,7 +48,9 @@
     "SECURITY.md",
     "CONTRIBUTING.md",
     ".claude-plugin",
-    "codex"
+    "codex",
+    "TEST-PLAN-JOINT-FLEET-2.0.8.md",
+    "TEST-CASES-JOINT-FLEET-2.0.8.md"
   ],
   "engines": {
     "node": ">=20.19.0"
@@ -64,7 +66,7 @@
     "pack": "node scripts/pack.mjs",
     "reachability": "node scripts/reachability-check.mjs",
     "reachability:classify": "node scripts/reachability-classify.mjs",
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs test/maintenance.test.mjs test/maintenance-ferry.test.mjs test/grant.test.mjs test/grant-gate.test.mjs test/worktree.test.mjs test/patch-artifact.test.mjs test/merge-queue.test.mjs test/m3-workflow.test.mjs test/project-room.test.mjs test/project-attribution.test.mjs test/project-locks.test.mjs test/project-reviews.test.mjs test/project-notifications.test.mjs test/blob-sessions.test.mjs test/outbox.test.mjs test/reliability-metrics.test.mjs test/evidence.test.mjs test/grant-issue.test.mjs test/project-refs.test.mjs test/exec-capability.test.mjs test/secondary-link.test.mjs test/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.test.mjs test/relay-failover.test.mjs test/npm-update.test.mjs test/agent-start-nonblocking.test.mjs test/fleet-chat-capture.test.mjs test/capture-route.test.mjs test/update-resolver.test.mjs test/agent-identity-safe.test.mjs test/re-pair-stale-token.test.mjs test/gpw-folder-policy.test.mjs test/gpw-activation.test.mjs test/gpw-hardening.test.mjs test/gpw-tamper-gate.test.mjs test/gpw-persistence.test.mjs test/gpw-colors.test.mjs test/gpw-recent-fold.test.mjs test/gpw-auto-approve.test.mjs test/joint-dev-dispatch.test.mjs test/joint-dev-loop.test.mjs test/joint-dev-audit.test.mjs test/joint-dev-redline.test.mjs test/relay-redline-guard.test.mjs test/relay-p0-projection.test.mjs test/guarded-dispatch.test.mjs test/p0-single-matcher.test.mjs test/path-policy.test.mjs test/path-policy-fs.test.mjs test/gpw-inheritance-table.test.mjs test/gpw-policy-adapter.test.mjs test/target-policy.test.mjs test/relay-redline-audit.test.mjs test/relay-repair-ledger.test.mjs test/relay-purge-blobs.test.mjs test/relay-scrub.test.mjs test/joint-dev-plan-store.test.mjs test/relay-basepath-blobs.test.mjs test/operator-token.test.mjs test/relay-health-capabilities.test.mjs test/joint-relay-dispatch.test.mjs test/operator-token-route.test.mjs test/relay-scrub-task-projection.test.mjs test/operator-key-approval.test.mjs test/relay-offer-journal.test.mjs test/joint-r5-wiring.test.mjs test/p1-hardening.test.mjs test/joint-merge-engine.test.mjs test/artifact-ref-dir-sink.test.mjs test/chat-sticker-guard.test.mjs test/relay-task-progress.test.mjs test/gpw-modes.test.mjs test/joint-cli.test.mjs test/joint-command-hash.test.mjs test/joint-dispatch-audit.test.mjs test/tools-cancel-auth.test.mjs test/fleet-mirror.test.mjs test/sink-git-ssh.test.mjs test/agent-sse-watchdog.test.mjs test/version-gate.test.mjs test/joint-merge-cli.test.mjs test/joint-progress.test.mjs test/project-room-truncation.test.mjs test/chat-crypto-aad.test.mjs test/agent-artifact-delivery.test.mjs test/dataplane-sink-route.test.mjs test/artifact-sink-e2e.test.mjs test/project-room-persistence.test.mjs test/project-room-disk-persistence.test.mjs test/project-stream-route.test.mjs test/chat-v2-gate.test.mjs test/xiangqi.test.mjs test/xfer-foundation.test.mjs test/xfer-ferry.test.mjs test/xfer-publish.test.mjs test/xfer-want-block.test.mjs test/p2p-cipher-diag.test.mjs test/chacha-fallback.test.mjs test/fleet-binding.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs test/maintenance.test.mjs test/maintenance-ferry.test.mjs test/grant.test.mjs test/grant-gate.test.mjs test/worktree.test.mjs test/patch-artifact.test.mjs test/merge-queue.test.mjs test/m3-workflow.test.mjs test/project-room.test.mjs test/project-attribution.test.mjs test/project-locks.test.mjs test/project-reviews.test.mjs test/project-notifications.test.mjs test/blob-sessions.test.mjs test/outbox.test.mjs test/reliability-metrics.test.mjs test/evidence.test.mjs test/grant-issue.test.mjs test/project-refs.test.mjs test/exec-capability.test.mjs test/secondary-link.test.mjs test/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.test.mjs test/relay-failover.test.mjs test/npm-update.test.mjs test/agent-start-nonblocking.test.mjs test/fleet-chat-capture.test.mjs test/capture-route.test.mjs test/update-resolver.test.mjs test/agent-identity-safe.test.mjs test/re-pair-stale-token.test.mjs test/gpw-folder-policy.test.mjs test/gpw-activation.test.mjs test/gpw-hardening.test.mjs test/gpw-tamper-gate.test.mjs test/gpw-persistence.test.mjs test/gpw-colors.test.mjs test/gpw-recent-fold.test.mjs test/gpw-auto-approve.test.mjs test/joint-dev-dispatch.test.mjs test/joint-dev-loop.test.mjs test/joint-dev-audit.test.mjs test/joint-dev-redline.test.mjs test/relay-redline-guard.test.mjs test/relay-p0-projection.test.mjs test/guarded-dispatch.test.mjs test/p0-single-matcher.test.mjs test/path-policy.test.mjs test/path-policy-fs.test.mjs test/gpw-inheritance-table.test.mjs test/gpw-policy-adapter.test.mjs test/target-policy.test.mjs test/relay-redline-audit.test.mjs test/relay-repair-ledger.test.mjs test/relay-purge-blobs.test.mjs test/relay-scrub.test.mjs test/joint-dev-plan-store.test.mjs test/relay-basepath-blobs.test.mjs test/operator-token.test.mjs test/relay-health-capabilities.test.mjs test/joint-relay-dispatch.test.mjs test/operator-token-route.test.mjs test/relay-scrub-task-projection.test.mjs test/operator-key-approval.test.mjs test/relay-offer-journal.test.mjs test/joint-r5-wiring.test.mjs test/p1-hardening.test.mjs test/joint-merge-engine.test.mjs test/artifact-ref-dir-sink.test.mjs test/chat-sticker-guard.test.mjs test/relay-task-progress.test.mjs test/gpw-modes.test.mjs test/joint-cli.test.mjs test/joint-command-hash.test.mjs test/joint-dispatch-audit.test.mjs test/tools-cancel-auth.test.mjs test/fleet-mirror.test.mjs test/sink-git-ssh.test.mjs test/agent-sse-watchdog.test.mjs test/version-gate.test.mjs test/joint-merge-cli.test.mjs test/joint-progress.test.mjs test/project-room-truncation.test.mjs test/chat-crypto-aad.test.mjs test/agent-artifact-delivery.test.mjs test/dataplane-sink-route.test.mjs test/artifact-sink-e2e.test.mjs test/project-room-persistence.test.mjs test/project-room-disk-persistence.test.mjs test/project-stream-route.test.mjs test/chat-v2-gate.test.mjs test/xiangqi.test.mjs test/xfer-foundation.test.mjs test/xfer-ferry.test.mjs test/xfer-publish.test.mjs test/xfer-want-block.test.mjs test/p2p-cipher-diag.test.mjs test/chacha-fallback.test.mjs test/fleet-binding.test.mjs test/xfer-channel.test.mjs test/p2p-race.test.mjs test/path-scheduler.test.mjs test/transport.test.mjs test/iroh-sidecar.test.mjs test/discovery.test.mjs test/p2p-rtt.test.mjs test/artifact-ref-v3.test.mjs test/xfer-recovery.test.mjs test/xfer-router.test.mjs",
     "test:acceptance-doc": "node --test --test-force-exit test/acceptance-doc.test.mjs",
     "test:account-identity": "node --test --test-force-exit test/account-identity.test.mjs",
     "test:account-join": "node --test --test-force-exit test/account-join.test.mjs",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/agent/agent.mjs

@@ -69,6 +69,7 @@ import {
   readExecCapability,
 } from '../util/exec-capability.mjs';
 import { CRYPTO_REASON, DEVICE_KEY_FILE, DeviceKey, PeerKeyStore, deriveSigningKey } from './crypto.mjs';
+import { createXferFrameRouter } from './transfer/router.mjs';
 import { DEFAULT_P2P_MODE, P2P_DEFAULTS, P2PNode, normalizeP2PMode, normalizeP2PPort } from './p2p-node.mjs';
 import { punchSession, reverseDialSession } from './p2p.mjs';
 import { createSigner } from '../signing.mjs';
@@ -1142,6 +1143,8 @@ export function createAgent(options) {
    * @type {PeerKeyStore}
    */
   const peerKeys = new PeerKeyStore();
+  /** P0-a: xfer.* frames arriving on a P2P channel are routed here, not to task dispatch. */
+  const xferRouter = createXferFrameRouter();
   /**
    * What each task's direct channel actually was, for the result envelope.
    *
@@ -3959,6 +3962,10 @@ let attemptAttached = false;
    */
   function handleP2PMessage(event) {
     const payload = parseP2PFrame(event.payload);
+    if (payload !== null && typeof payload.type === 'string' && payload.type.startsWith('xfer.')) {
+      xferRouter.handle(payload, { channel: event.channel });
+      return;
+    }
     if (payload === null) {
       log('warn', 'ignoring non-JSON frame on a P2P channel', {
         peer: event.peer ?? null,

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;
+}