@twinsearth/w2m-dsh-plugin 0.4.8 → 0.5.0

package/src/agent/p2p-node.mjs

@@ -252,6 +252,16 @@ export const P2P_DEFAULTS = Object.freeze({
   refreshMs: 20_000,
   punchTimeoutMs: 5_000,
   acceptTimeoutMs: 5_000,
+  /**
+   * How long an executor may spend dialling a dispatcher it did not punch first.
+   *
+   * Deliberately longer than `punchTimeoutMs`. A punch between two peers that both expected it
+   * succeeds in one round trip or not at all; a *reverse* dial is racing the other end's own
+   * punch attempt and a NAT filter that only opens once the other side's packet has arrived, so
+   * it needs room for several HELLO rounds. 8 s is the window the v0.4.x contract states, and it
+   * is bounded on purpose: the relay copy of an offer and of a result is never held behind it.
+   */
+  reverseDialTimeoutMs: 8_000,
   maxCandidates: 8,
 });
 
@@ -945,13 +955,23 @@ export class P2PNode extends EventEmitter {
    *   initiator has to pick one, and a caller with a task id should pass one derived
    *   from it so two concurrent tasks do not share a session.
    * @param {number} [options.timeoutMs] Punch deadline; default `tuning.punchTimeoutMs`.
+   * @param {Array<{address:string, port:number}>} [options.candidates] Addresses to punch
+   *   at, used **instead of** asking the relay. This is how an executor dials a dispatcher
+   *   whose candidates travelled inside the offer (`p2p.candidates`): the offer is evidence
+   *   the dispatcher itself produced moments ago, and a relay lookup would be a second,
+   *   slower opinion about the same machine — one that answers 404 for a dispatcher whose
+   *   announcement has already expired. The list is validated here exactly like the relay's
+   *   answer is, so an offer cannot smuggle in a wildcard address or a zero port.
    * @param {number} [options.acceptTimeoutMs] Accepted for interface symmetry with
    *   {@link accept} and unused here: the initiator waits for the HELLO_ACK, which is
    *   the punch itself, and never waits to be accepted.
    * @returns {Promise<{ok:boolean, channel:import('./p2p.mjs').P2PChannel|null,
    *   peer:{address:string,port:number}|null, session:number, error:string|null,
-   *   attempts:number, rttMs:number|null, peersAnnounced:number}>} `peersAnnounced` is
-   *   how many candidate addresses the relay held for that machine.
+   *   attempts:number, rttMs:number|null, peersAnnounced:number, reused:boolean}>}
+   *   `peersAnnounced` is how many candidate addresses the caller (or the relay) held for
+   *   that machine; `reused` says the session already had a live channel and no punch was
+   *   needed, which is what keeps a simultaneous punch from producing two channels for one
+   *   session — and therefore two deliveries of every message.
    */
   async dial(machineId, options = {}) {
     const empty = {
@@ -963,6 +983,7 @@ export class P2PNode extends EventEmitter {
       attempts: 0,
       rttMs: null,
       peersAnnounced: 0,
+      reused: false,
     };
 
     if (!this.isEnabled()) {
@@ -974,9 +995,6 @@ export class P2PNode extends EventEmitter {
     if (typeof machineId !== 'string' || machineId === '') {
       return { ...empty, error: "P2P_BAD_MACHINE_ID: dial() needs the peer's machine id" };
     }
-    if (typeof this.getJson !== 'function') {
-      return { ...empty, error: "P2P_NO_GET_JSON: dial() needs getJson to read the peer's candidates" };
-    }
 
     let session = options.session;
     if (session === undefined) {
@@ -997,25 +1015,44 @@ export class P2PNode extends EventEmitter {
       return { ...empty, session, error, ...extra };
     };
 
-    let lookup = null;
-    try {
-      lookup = await this.getJson(`/v1/peer/${encodeURIComponent(machineId)}`);
-    } catch (error) {
-      return fail(`P2P_LOOKUP_FAILED: ${messageOf(error)}`);
-    }
-    if (this.socket !== socket || !this.started) {
-      return { ...empty, session, error: 'P2P_NODE_NOT_RUNNING: the node closed while dialling' };
-    }
-    if (lookup?.ok !== true) {
-      if (lookup?.status === 404) {
-        // A 404 is the relay saying "this machine has not announced" — an ordinary state
-        // (the peer may be relay-only, or between refreshes), and it has its own code.
-        return fail(`P2P_NO_CANDIDATES: the relay holds no live announcement for ${machineId}`);
+    // "One session, one channel" is enforced where a simultaneous punch actually collides: after the
+    // punch resolves, against whatever the accept loop claimed while it was in flight (see
+    // `claimedMeanwhile` below and `adoptChannel`). There is deliberately no cheap pre-check here: a
+    // caller that dials a session this node already holds is still punching, the far end
+    // re-acknowledges it, and that contract is what the re-ack case in `test/p2p-node.test.mjs` pins
+    // down. Suppressing the punch would change it to save one datagram.
+
+    // `options.candidates` present and non-empty means "punch at these" -- an empty array is the same
+    // statement as the field being absent ("nobody told me where"), and falls through to the relay.
+    const fromOffer = Array.isArray(options.candidates) && options.candidates.length > 0;
+
+    let announced = [];
+    if (fromOffer) {
+      announced = options.candidates;
+    } else {
+      if (typeof this.getJson !== 'function') {
+        return { ...empty, error: "P2P_NO_GET_JSON: dial() needs getJson to read the peer's candidates" };
+      }
+      let lookup = null;
+      try {
+        lookup = await this.getJson(`/v1/peer/${encodeURIComponent(machineId)}`);
+      } catch (error) {
+        return fail(`P2P_LOOKUP_FAILED: ${messageOf(error)}`);
       }
-      return fail(`P2P_LOOKUP_FAILED: ${describeLookupFailure(lookup)}`);
+      if (this.socket !== socket || !this.started) {
+        return { ...empty, session, error: 'P2P_NODE_NOT_RUNNING: the node closed while dialling' };
+      }
+      if (lookup?.ok !== true) {
+        if (lookup?.status === 404) {
+          // A 404 is the relay saying "this machine has not announced" — an ordinary state
+          // (the peer may be relay-only, or between refreshes), and it has its own code.
+          return fail(`P2P_NO_CANDIDATES: the relay holds no live announcement for ${machineId}`);
+        }
+        return fail(`P2P_LOOKUP_FAILED: ${describeLookupFailure(lookup)}`);
+      }
+      announced = Array.isArray(lookup.json?.peer?.candidates) ? lookup.json.peer.candidates : [];
     }
 
-    const announced = Array.isArray(lookup.json?.peer?.candidates) ? lookup.json.peer.candidates : [];
     const remote = [];
     for (const candidate of announced) {
       const usable = usableCandidate(candidate);
@@ -1025,7 +1062,15 @@ export class P2PNode extends EventEmitter {
       if (remote.length >= this.tuning.maxCandidates) break;
     }
     if (remote.length === 0) {
-      return fail(`P2P_NO_CANDIDATES: ${machineId} announced no usable address`);
+      // `peersAnnounced` still counts what was offered, not what survived validation: a caller
+      // reading "the punch failed" needs to see that there *was* a list, and that every entry in it
+      // was unusable -- a wildcard address, a zero port -- rather than that nobody had an address.
+      return fail(
+        fromOffer
+          ? `P2P_NO_CANDIDATES: the offer's candidate list for ${machineId} held no usable address`
+          : `P2P_NO_CANDIDATES: ${machineId} announced no usable address`,
+        { peersAnnounced: announced.length },
+      );
     }
 
     let outcome = null;
@@ -1055,6 +1100,31 @@ export class P2PNode extends EventEmitter {
     }
 
     this.punchesOut += 1;
+    // The accept loop may have claimed this session while the punch was in flight — the far end
+    // dialled us at the same moment we dialled it, which is the whole point of a simultaneous
+    // punch. Its channel is the better one: its peer is the address the far end's packet actually
+    // came from, while ours is the address that end merely *announced*. Keep the observed one.
+    const claimedMeanwhile = this.channels.get(session);
+    if (claimedMeanwhile !== undefined && claimedMeanwhile !== outcome.channel) {
+      try {
+        // Silent: this is a duplicate local view of a live session, not the end of one. A BYE here
+        // would close the peer's channel for the session the survivor is about to use.
+        outcome.channel.close('session-claimed', { silent: true });
+      } catch {
+        /* the path is already gone */
+      }
+      return {
+        ok: true,
+        channel: claimedMeanwhile,
+        peer: { ...claimedMeanwhile.peer },
+        session,
+        error: null,
+        attempts: outcome.punch.attempts,
+        rttMs: outcome.punch.rttMs,
+        peersAnnounced: announced.length,
+        reused: true,
+      };
+    }
     this.adoptChannel(outcome.channel, { from: machineId, session: outcome.channel.session });
     return {
       ok: true,
@@ -1065,6 +1135,7 @@ export class P2PNode extends EventEmitter {
       attempts: outcome.punch.attempts,
       rttMs: outcome.punch.rttMs,
       peersAnnounced: announced.length,
+      reused: false,
     };
   }
 
@@ -1072,6 +1143,14 @@ export class P2PNode extends EventEmitter {
    * Wire one channel into the node: deliver its payloads as `'message'` events, claim
    * its session, and drop the claim when it closes.
    *
+   * **One session, one channel — enforced here, not assumed.** The map is keyed by session and a
+   * second channel for a session already in it is *closed*, because `P2PChannel` filters incoming
+   * datagrams by session alone: two live channels on one session would each assemble and deliver
+   * every message of that session, so the caller would see each payload twice and `result_path`
+   * would be decided by whichever listener was registered last. A simultaneous punch makes that
+   * the normal case rather than a corner case, since both ends' HELLOs arrive while both are still
+   * dialling. See `dial()`, which returns the surviving channel rather than the one it just opened.
+   *
    * The claim is released on close on purpose. `claimed` means "this session has a live
    * channel"; a broken path has to be re-punchable with the same session, and holding
    * the claim after the channel is gone would silently refuse the peer's retry.
@@ -1080,6 +1159,20 @@ export class P2PNode extends EventEmitter {
    * @param {{from:string|null, session:number}} details
    */
   adoptChannel(channel, details) {
+    const previous = this.channels.get(details.session);
+    if (previous !== undefined && previous !== channel) {
+      // Closed *before* the claim is taken: the old channel's own `'close'` handler deletes the
+      // session from `claimed`, and running it after the new claim would drop a claim that is
+      // still live -- which is the state that lets a peer open a second channel on this session.
+      this.channels.delete(details.session);
+      try {
+        // Silent, for the same reason as the duplicate in `dial()`: the session is not over, it is
+        // being represented by a better channel, and a BYE would close the peer's view of it.
+        previous.close('session-replaced', { silent: true });
+      } catch {
+        /* the path is already gone; that is the state this replacement produces */
+      }
+    }
     this.channels.set(details.session, channel);
     this.claimed.add(details.session);
     channel.on('message', (payload) => {
@@ -1093,7 +1186,9 @@ export class P2PNode extends EventEmitter {
     });
     channel.on('close', () => {
       if (this.channels.get(details.session) === channel) this.channels.delete(details.session);
-      this.claimed.delete(details.session);
+      // The claim belongs to whichever channel currently holds the session, so a *replaced*
+      // channel's close must not drop a claim its replacement depends on.
+      if (this.channels.get(details.session) === undefined) this.claimed.delete(details.session);
     });
     // P2PChannel documents an `'error'` event. Listening is not optional bookkeeping:
     // an unhandled `'error'` emit would throw, and the whole point of this node is that

package/src/agent/p2p.mjs

@@ -22,6 +22,15 @@
  *     address the peer's packets will come from. `punch()` reports failure with the
  *     attempts it made, and the caller falls back to the relay -- explicitly, never
  *     silently.
+ *   * **Both ends may send, and one of them usually should not have to.** A peer behind
+ *     a CGNAT can send all it likes and still never be heard: its own outbound HELLO opens
+ *     its mapping, but the *other* end's filter stays shut until something of its own has
+ *     gone the other way. That is why `punch()` and `accept()` are not alternatives: an
+ *     executor that normally only accepts can also dial the dispatcher with the session the
+ *     offer published (see {@link punchSession}), and the two outbound packets together open
+ *     a path that neither alone could. Both ends use the address the *other's* packet came
+ *     from -- the observed `rinfo` -- rather than the address that was announced, which is
+ *     the one property that makes a symmetric NAT survivable at all.
  *
  * Framing (all integers big-endian):
  *
@@ -123,6 +132,105 @@ export function deriveSession(...parts) {
   return value === 0 ? 1 : value;
 }
 
+/**
+ * Derivation labels, named once so `deriveSession` is never called with a hand-typed
+ * string on one side and a different one on the other.
+ *
+ * The label is part of the hash: two peers that disagreed about it would compute
+ * different session ids for the same punch, discard each other's HELLO, and report a
+ * timeout that looks exactly like a NAT problem. That is the most expensive possible
+ * misdiagnosis, which is why the strings live next to `deriveSession` rather than at
+ * the two call sites.
+ */
+export const PUNCH_SESSION_LABEL = 'w2m-p2p-punch';
+export const REVERSE_DIAL_SESSION_LABEL = 'w2m-p2p-reverse';
+
+/** Longest accepted punch id, so a hostile offer cannot make either end hash a novel. */
+export const MAX_PUNCH_ID_LENGTH = 64;
+
+/**
+ * Is `value` a usable punch id?
+ *
+ * A punch id is what a dispatcher publishes through the relay so the executor can join the
+ * *same* session; it is deliberately not the session itself. One dispatcher leases one task
+ * to several machines at once, and a single shared session id would make the second machine's
+ * HELLO look like a re-acknowledgement of the first machine's live channel -- two peers on one
+ * session, and a result delivered to the wrong address. The published id is therefore an
+ * *input* to {@link punchSession}, which mixes in the machine id and yields a session that is
+ * unique per (dispatch, task, machine) while still being computable by both ends without a
+ * second round trip.
+ *
+ * Both shapes a JSON hop can carry are accepted: a hex string (what {@link mintPunchId}
+ * produces) and a positive integer (what a caller that treats the id as a number would write).
+ * Numbers are bounded to 32 bits so `deriveSession`'s string form of them is stable.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isPunchId(value) {
+  if (typeof value === 'number') return Number.isInteger(value) && value > 0 && value <= 0xffffffff;
+  return typeof value === 'string' && value !== '' && value.length <= MAX_PUNCH_ID_LENGTH;
+}
+
+/**
+ * Mint a punch id for one dispatch.
+ *
+ * Random rather than derived: the session id ends up as the only thing that identifies a
+ * channel's frames (`P2PChannel.onDatagram` discards anything carrying another session), so
+ * a value an off-path observer could predict would be a value an off-path observer could
+ * inject with. Eight random bytes is the cheapest size that makes guessing hopeless.
+ *
+ * @returns {string} 16 lower-case hex characters.
+ */
+export function mintPunchId() {
+  return randomBytes(8).toString('hex');
+}
+
+/**
+ * The session a dispatcher punches with, derived from the punch id it published.
+ *
+ * Deterministic on purpose, and identical on both ends: the dispatcher knows the punch id, the
+ * task id and the peer's machine id from the lease; the executor knows the first two from the
+ * offer and the third because it is its own id. No extra round trip, and the executor's HELLO
+ * carries the very session the dispatcher's in-flight punch is filtering for -- which is what
+ * makes the two halves one punch instead of two punches that time out against each other.
+ *
+ * @param {object} options
+ * @param {unknown} options.punch The published punch id; see {@link isPunchId}.
+ * @param {unknown} options.taskId
+ * @param {unknown} options.machineId The *executor's* machine id, not the dispatcher's.
+ * @returns {number|null} `null` when the inputs cannot produce one, so a caller can fall back
+ *   to its own id instead of punching at a session the far end is not using.
+ */
+export function punchSession({ punch, taskId, machineId } = {}) {
+  if (!isPunchId(punch)) return null;
+  if (typeof taskId !== 'string' || taskId === '') return null;
+  if (typeof machineId !== 'string' || machineId === '') return null;
+  return deriveSession(PUNCH_SESSION_LABEL, punch, taskId, machineId);
+}
+
+/**
+ * The session an executor uses when the offer named where to dial but no session to join.
+ *
+ * This is the compatibility path: a dispatcher that publishes its candidates without a punch
+ * id (or an older one that publishes nothing at all, where the caller never gets here). The
+ * executor picks the id, and the dispatcher's `accept()` adopts whatever the HELLO carries --
+ * that asymmetry is exactly what `allowSessionAdoption` exists for, and it is why a dial can
+ * still be attempted against a peer that never named a session.
+ *
+ * @param {object} options
+ * @param {unknown} options.originMachineId The dispatcher's machine id, from the offer.
+ * @param {unknown} options.taskId
+ * @param {unknown} options.machineId The executor's own machine id.
+ * @returns {number|null}
+ */
+export function reverseDialSession({ originMachineId, taskId, machineId } = {}) {
+  if (typeof originMachineId !== 'string' || originMachineId === '') return null;
+  if (typeof taskId !== 'string' || taskId === '') return null;
+  if (typeof machineId !== 'string' || machineId === '') return null;
+  return deriveSession(REVERSE_DIAL_SESSION_LABEL, originMachineId, taskId, machineId);
+}
+
 /**
  * Try to open a bidirectional path to one of `remote`'s candidate addresses.
  *
@@ -444,9 +552,36 @@ export class P2PChannel extends EventEmitter {
     });
   }
 
-  /** Stop the channel. The socket is NOT closed: the caller owns it. */
-  close(reason = 'closed') {
+  /**
+   * Stop the channel. The socket is NOT closed: the caller owns it.
+   *
+   * @param {string} [reason] Reported on the `'close'` event and in the rejection of every pending
+   *   send.
+   * @param {{silent?: boolean}} [options] `silent: true` drops this channel **without telling the
+   *   peer**, which is what discarding a *duplicate local view* of a live session requires. A punch
+   *   can produce two channel objects for one session (both ends dialled, and the accept loop answered
+   *   while the punch was still in flight); keeping the observed-address one and closing the other is
+   *   right, but a BYE there would tell the peer a session that is very much alive was over, and would
+   *   tear down the channel the survivor is about to use.
+   */
+  close(reason = 'closed', options = {}) {
     if (this.closed) return;
+    // The BYE goes out BEFORE `closed` is set, and that ordering is the whole fix. `sendFrame`
+    // refuses to send once the channel is closed -- a guard that is right for retransmissions and was
+    // silently wrong for the goodbye: with `closed` set first, the BYE below could never leave, so the
+    // peer was never told the path was over and kept writing into a channel nothing was listening on.
+    // Measured, on the path this release is about: a dispatcher's `pushOffer` closes the channel it
+    // pushed the offer over, and without the BYE the executor's side still looked live for the whole
+    // task, so its result was sent into that dead channel and only fell back to the relay after eight
+    // unacknowledged fragments (`P2P_FRAGMENT_UNACKED`) -- the "result came back relay" half of the
+    // failure, with no reverse dial attempted because a channel appeared to exist.
+    if (reason !== 'peer-closed' && options.silent !== true) {
+      try {
+        this.sendFrame(KIND.BYE, Buffer.alloc(0));
+      } catch {
+        /* the path is already gone */
+      }
+    }
     this.closed = true;
     this.socket.removeListener('message', this.onDatagram);
     for (const entry of this.outgoing.values()) {
@@ -455,13 +590,6 @@ export class P2PChannel extends EventEmitter {
     }
     this.outgoing.clear();
     this.incoming.clear();
-    if (reason !== 'peer-closed') {
-      try {
-        this.sendFrame(KIND.BYE, Buffer.alloc(0));
-      } catch {
-        /* the path is already gone */
-      }
-    }
     this.emit('close', reason);
   }
 }

package/src/plugin/tools.mjs

@@ -69,6 +69,11 @@ import {
   normalizeP2PMode,
   stunServersWithShared,
 } from '../agent/p2p-node.mjs';
+// The punch identity both ends have to agree on (v0.4.x). Imported from the transport that will use
+// it, never re-derived here: the session is the only thing that tells one punch's frames from
+// another's, so a second implementation of the formula that drifted by one input would make every
+// reverse dial time out while both ends insisted they were sending.
+import { mintPunchId, punchSession } from '../agent/p2p.mjs';
 import { parseServer } from '../agent/stun.mjs';
 // The result-deduplication identity the relay mints. Imported rather than re-implemented: the value
 // is compared byte for byte by the executor, so a second copy of the formula that drifted by one
@@ -110,7 +115,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.4.8';
+const PLUGIN_VERSION = '0.5.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -1041,6 +1046,81 @@ function createP2PTransport(cfg) {
   };
 }
 
+/**
+ * The `p2p` block a dispatch publishes through the relay, and what it is for.
+ *
+ * WHAT THE EXECUTOR CANNOT DO WITHOUT IT
+ *
+ * A dispatcher behind a symmetric NAT (CGNAT, in practice) can send all it likes and still be heard
+ * by nobody: its outbound HELLO opens its own mapping, but the peer's filter stays shut until
+ * *something of the peer's* has gone the other way. So the executor has to dial first — and to dial
+ * it needs two things the offer itself can carry: where the dispatcher says it is, and which punch
+ * to join. Without them the executor has only the relay lookup, which is a second opinion about the
+ * same machine that answers 404 for a dispatcher whose announcement has just expired.
+ *
+ * WHY A PUNCH ID RATHER THAN A SESSION ID
+ *
+ * The session id cannot be known when this request is written: one dispatch leases one task to
+ * several machines, and the relay decides which — in the same request that mints the task id. A
+ * single session shared by those machines would be a defect, not a simplification: on the
+ * dispatcher's own node the second machine's HELLO would look like a re-acknowledgement of the
+ * first machine's live channel, so one of them would have its result delivered to the other's
+ * address. The block therefore publishes a per-dispatch *punch id*, and both ends derive the same
+ * per-machine session from it (`punchSession` in `src/agent/p2p.mjs`): the dispatcher from the
+ * lease, the executor from the offer plus its own machine id. The pushed frame — which is addressed
+ * to one machine, so the value *is* known — carries the derived `session` as well.
+ *
+ * COMPATIBILITY
+ *
+ * Both keys are additions *inside* an object the relay already treats as opaque (`validateTaskRouting`
+ * checks `p2p` is an object with a valid `mode` and copies the rest verbatim), and both a v0.4.x
+ * relay and a v0.4.x agent ignore keys they do not read. `relay` mode publishes `{mode}` alone: there
+ * is no punch, and saying so is better than publishing a stale one.
+ *
+ * @param {ReturnType<typeof readConfig>} cfg
+ * @param {object} runtime The P2P runtime handle from {@link createP2PRuntime}.
+ * @returns {{mode: string, punch?: string, candidates?: Array<{address:string, port:number}>}}
+ */
+function buildP2POfferBlock(cfg, runtime) {
+  const block = { mode: cfg.p2pMode };
+  if (cfg.p2pMode === 'relay') return block;
+  // Minted here, before the task exists, because it has to travel in the request that *creates* the
+  // task: the relay republishes the stored block to the executor, and there is no way to amend it
+  // afterwards.
+  block.punch = mintPunchId();
+  // Announced candidates, when the node has already announced. Not waited for: `start()` kicks the
+  // first announce off rather than awaiting the STUN sweep, and a dispatch delayed by four STUN
+  // servers would trade a fast path for a slower one. Absent means "ask the relay", which is exactly
+  // what the executor does when the field is missing.
+  const candidates = runtime?.node?.status?.candidates;
+  if (Array.isArray(candidates) && candidates.length > 0) {
+    block.candidates = candidates.map((candidate) => ({ address: candidate.address, port: candidate.port }));
+  }
+  return block;
+}
+
+/**
+ * One machine's copy of the `p2p` block: everything published, plus the session for *this* machine.
+ *
+ * The added `session` is what makes the push and a reverse dial one punch rather than two: an
+ * executor that received the offer over a channel may still have to dial back (the dispatcher closes
+ * the channel it pushed over, immediately after the push), and a dial carrying a session the
+ * dispatcher is not filtering for would be answered by its `accept()` at best — a second session,
+ * a second channel, and two live sessions for one task where one would do.
+ *
+ * @param {unknown} published The block from {@link buildP2POfferBlock}, or whatever the caller sent.
+ * @param {{taskId: string, machineId: string}} identity
+ * @returns {object|null}
+ */
+function offerP2PFor(published, { taskId, machineId }) {
+  if (published === null || published === undefined) return null;
+  if (typeof published !== 'object' || Array.isArray(published)) return null;
+  const block = { ...published };
+  const session = punchSession({ punch: block.punch, taskId, machineId });
+  if (session !== null) block.session = session;
+  return block;
+}
+
 /**
  * Mint the offer frame the executor needs, from the lease the relay just issued.
  *
@@ -1103,7 +1183,7 @@ function buildOfferFrame({ taskId, lease, payload, originMachineId }) {
       requirements: payload.requirements,
       compare_policy: payload.compare_policy,
       origin_machine_id: originMachineId,
-      p2p: payload.p2p ?? null,
+      p2p: offerP2PFor(payload.p2p, { taskId, machineId }),
     },
     skipped: null,
   };
@@ -1112,25 +1192,40 @@ function buildOfferFrame({ taskId, lease, payload, originMachineId }) {
 /**
  * Push one offer over the direct path. Best effort by construction: nothing here throws.
  *
+ * The session comes from the frame's own `p2p.session` — minted per machine by
+ * {@link offerP2PFor} from the punch id the relay is publishing for this same task. Dialling with a
+ * session of the node's own invention would leave the two ends on two sessions, and an executor
+ * whose reverse dial happened to arrive first would open a *second* channel beside this one instead of
+ * the same one. `reused` in the answer is the honest report of the case where the executor's dial got
+ * there first and this push therefore travelled over the channel that dial opened.
+ *
  * @param {P2PNode} node
  * @param {object} frame
- * @returns {Promise<{ok: boolean, error: string|null}>}
+ * @returns {Promise<{ok: boolean, error: string|null, session: number|null, reused: boolean}>}
  */
 async function pushOffer(node, frame) {
+  const session = Number.isInteger(frame?.p2p?.session) && frame.p2p.session > 0 ? frame.p2p.session : undefined;
   try {
-    const dialled = await node.dial(frame.machine_id);
-    if (!dialled.ok) return { ok: false, error: dialled.error ?? 'P2P_DIAL_FAILED' };
+    const dialled = await node.dial(frame.machine_id, session === undefined ? {} : { session });
+    if (!dialled.ok) {
+      return { ok: false, error: dialled.error ?? 'P2P_DIAL_FAILED', session: dialled.session ?? null, reused: false };
+    }
     const channel = dialled.channel;
     try {
       await channel.send(JSON.stringify(frame));
-      return { ok: true, error: null };
+      return { ok: true, error: null, session: dialled.session ?? null, reused: dialled.reused === true };
     } finally {
       // The offer is one frame over a reliable channel: holding the channel open would keep a NAT
       // mapping alive for a conversation that is over, and the result comes back the responder's way.
       channel.close('offer-sent');
     }
   } catch (error) {
-    return { ok: false, error: `P2P_PUSH_THREW: ${error instanceof Error ? error.message : String(error)}` };
+    return {
+      ok: false,
+      error: `P2P_PUSH_THREW: ${error instanceof Error ? error.message : String(error)}`,
+      session: session ?? null,
+      reused: false,
+    };
   }
 }
 
@@ -1175,6 +1270,13 @@ async function pushOffers(node, { taskId, leases, payload, originMachineId }) {
       ok: result.ok,
       error: result.error,
       dedupe_key: built.frame.dedupe_key === null ? null : 'relay-formula',
+      // The session this push and the executor's reverse dial meet on, so a machine's own
+      // `p2p.session` in the ledger can be matched to the dispatcher's attempt without reading two
+      // logs side by side. `null` when there was nothing to punch over (a v0.4.x-shaped frame).
+      session: result.session,
+      // True when the executor's dial got there first and this push travelled over the channel that
+      // dial opened — a two-way punch that worked, reported as such rather than as a plain push.
+      reused: result.reused === true,
     });
   }
   return out;
@@ -2942,6 +3044,14 @@ export async function apply(ctx, config = {}) {
       const originMachineId =
         typeof p2p.machineId === 'string' && p2p.machineId !== '' ? p2p.machineId : null;
 
+      /**
+       * v0.4.x: the punch this dispatch will use, published with the task so the executor can join
+       * the same session instead of waiting to be reached. See {@link buildP2POfferBlock} for why the
+       * block carries a punch id rather than the session itself, and why `relay` mode publishes
+       * `{mode}` alone.
+       */
+      const p2pOffer = buildP2POfferBlock(cfg, p2p);
+
       const payload = {
         mode,
         // Under pipeline the relay derives this from stage 0; sending the caller's value when there is
@@ -2970,7 +3080,7 @@ export async function apply(ctx, config = {}) {
         // which path the dispatcher expected to use — and so the executor in `direct` mode knows it
         // must refuse an offer that did not arrive over the direct path.
         ...(originMachineId !== null ? { origin_machine_id: originMachineId } : {}),
-        p2p: { mode: cfg.p2pMode },
+        p2p: p2pOffer,
       };
 
       const result = await request({
@@ -3012,7 +3122,17 @@ export async function apply(ctx, config = {}) {
        * `relay` mode and a machine with no direct path both report `attempted: 0`, which is the
        * honest answer ("there was nothing to push over") rather than an empty object.
        */
-      let directPushes = { mode: cfg.p2pMode, attempted: 0, delivered: 0, failed: 0, pushes: [] };
+      let directPushes = {
+        mode: cfg.p2pMode,
+        // The punch this dispatch published and dialled with. Repeated here so one dispatch's answer
+        // is self-contained: an operator correlating it with a machine's `p2p.session` or with the
+        // machine's own log has the value in hand without a second call.
+        punch: p2pOffer.punch ?? null,
+        attempted: 0,
+        delivered: 0,
+        failed: 0,
+        pushes: [],
+      };
       if (cfg.p2pMode !== 'relay' && p2p.node !== null && p2p.start?.ok === true) {
         try {
           const pushes = await pushOffers(p2p.node, {
@@ -3022,21 +3142,22 @@ export async function apply(ctx, config = {}) {
             originMachineId,
           });
           directPushes = {
-            mode: cfg.p2pMode,
+            ...directPushes,
             attempted: pushes.length,
             delivered: pushes.filter((entry) => entry.ok).length,
             failed: pushes.filter((entry) => !entry.ok).length,
             pushes,
+            // How many of the machines that were reached were reached over a channel *this* machine
+            // did not open — the executor dialled first, and the push landed on that path. Zero on a
+            // fleet where only the dispatcher initiates, which is what makes the two-way punch
+            // visible in one dispatch's own answer instead of only in the ledger.
+            reused_channels: pushes.filter((entry) => entry.reused === true).length,
           };
         } catch (error) {
           // `pushOffers` is written not to throw; this is here so a future edit cannot turn a
           // best-effort optimisation into a failed dispatch.
           directPushes = {
-            mode: cfg.p2pMode,
-            attempted: 0,
-            delivered: 0,
-            failed: 0,
-            pushes: [],
+            ...directPushes,
             error: `P2P_PUSH_FAILED: ${error instanceof Error ? error.message : String(error)}`,
           };
         }