@twinsearth/w2m-dsh-plugin 0.5.2 → 0.5.4

package/src/plugin/tools.mjs

@@ -74,6 +74,10 @@ import {
 // 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';
+// v0.6.0: the device keypair and the offer's key distribution (`docs/P2P-CRYPTO.md` §4). Imported
+// rather than reimplemented: the dispatcher and the executor have to derive the *same* keys, and two
+// implementations of a handshake are two chances to disagree about it.
+import { DeviceKey } from '../agent/crypto.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
@@ -81,6 +85,18 @@ import { parseServer } from '../agent/stun.mjs';
 // the dedupe key exists to prevent.
 import { SHELL_ID_DIRECT, computeCommandHash, computeDedupeKey } from '../relay/state.mjs';
 import { createAutoUpdater, findProfileDir, resolveCurrentVersion } from './auto-update.mjs';
+// v0.6.1: the session's chosen target machine, and the two browser routes the composer control
+// reads it through. Imported rather than inlined because the control and `w2m_run` must agree on
+// what "selected" means, and a second copy of that rule is a second chance to disagree.
+import {
+  createLocalIdentity,
+  defaultSelectionStore,
+  dispatchSelectionFields,
+  readFleet,
+  registerTargetRoutes,
+  sessionKeyFor,
+  TARGET_ROUTE_PATH,
+} from './fleet-target.mjs';
 import { loadSharedConfig, describeSharedConfig } from './shared-config.mjs';
 import { DEFAULT_DAILY_TIMES, DEFAULT_TIME_ZONE } from './schedule.mjs';
 
@@ -115,7 +131,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.5.2';
+const PLUGIN_VERSION = '0.5.4';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -1077,9 +1093,27 @@ function createP2PTransport(cfg) {
  * 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.
  *
+ * v0.6.0 adds one more key to the same block, and it is the whole of the key distribution problem:
+ *
+ *   `static_keys: { [machine_id]: base64(x25519 public key) }`
+ *
+ * WHY A MAP RATHER THAN ONE KEY
+ *
+ * The executor needs the *dispatcher's* key before it can dial back, and the dispatcher needs the
+ * *executor's* key before it can push — and at dispatch time the relay has not yet said which
+ * machines the task went to (`leases` come back in the same response that creates it). So the block
+ * carries this machine's own key, which is known before the request is written, and
+ * {@link offerP2PFor} adds the target's once the lease names it. Reading the field is therefore
+ * "look up the machine you are about to talk to", never "assume the only entry is the peer" — a
+ * machine that receives an offer for a fleet of three has three entries and uses one.
+ *
+ * What that buys, in the document's own terms: no `[Peer]` block for anyone to fill in. A machine
+ * learns the keys of exactly the peers it has been asked to talk to, from the offer that asked it.
+ *
  * @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}>}}
+ * @returns {{mode: string, punch?: string, candidates?: Array<{address:string, port:number}>,
+ *   static_keys?: Record<string, string>}}
  */
 function buildP2POfferBlock(cfg, runtime) {
   const block = { mode: cfg.p2pMode };
@@ -1096,6 +1130,14 @@ function buildP2POfferBlock(cfg, runtime) {
   if (Array.isArray(candidates) && candidates.length > 0) {
     block.candidates = candidates.map((candidate) => ({ address: candidate.address, port: candidate.port }));
   }
+  // This machine's own static public key. Absent (not null) when there is none, so the wire stays
+  // byte-identical to v0.5.x for a machine that has no key — an additive change has to be absent to
+  // be additive.
+  const own = runtime?.encryption?.public_key;
+  const machineId = runtime?.machineId;
+  if (typeof own === 'string' && own !== '' && typeof machineId === 'string' && machineId !== '') {
+    block.static_keys = { [machineId]: own };
+  }
   return block;
 }
 
@@ -1108,16 +1150,25 @@ function buildP2POfferBlock(cfg, runtime) {
  * 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.
  *
+ * v0.6.0 adds the *target's* key to `static_keys` when the caller supplies one, which is the half of
+ * the distribution the published block could not carry: the dispatcher learns the executor's key from
+ * the relay's peer record and hands it over in the frame addressed to that machine.
+ *
  * @param {unknown} published The block from {@link buildP2POfferBlock}, or whatever the caller sent.
- * @param {{taskId: string, machineId: string}} identity
+ * @param {{taskId: string, machineId: string, peerKey?: string|null}} identity
  * @returns {object|null}
  */
-function offerP2PFor(published, { taskId, machineId }) {
+function offerP2PFor(published, { taskId, machineId, peerKey = null }) {
   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;
+  if (typeof peerKey === 'string' && peerKey !== '') {
+    const keys = block.static_keys !== null && typeof block.static_keys === 'object' ? { ...block.static_keys } : {};
+    keys[machineId] = peerKey;
+    block.static_keys = keys;
+  }
   return block;
 }
 
@@ -1142,9 +1193,11 @@ function offerP2PFor(published, { taskId, machineId }) {
  * @param {object} options.lease
  * @param {object} options.payload The validated `POST /v1/task` body this plugin sent.
  * @param {string|null} options.originMachineId
+ * @param {string|null} [options.peerKey] The target's static public key (v0.6.0), added to the
+ *   frame's `p2p.static_keys` under that machine's id.
  * @returns {{frame: object|null, skipped: string|null}}
  */
-function buildOfferFrame({ taskId, lease, payload, originMachineId }) {
+function buildOfferFrame({ taskId, lease, payload, originMachineId, peerKey = null }) {
   const machineId = typeof lease?.machine_id === 'string' && lease.machine_id !== '' ? lease.machine_id : null;
   if (machineId === null) return { frame: null, skipped: 'the relay returned a lease with no machine_id' };
 
@@ -1183,7 +1236,7 @@ function buildOfferFrame({ taskId, lease, payload, originMachineId }) {
       requirements: payload.requirements,
       compare_policy: payload.compare_policy,
       origin_machine_id: originMachineId,
-      p2p: offerP2PFor(payload.p2p, { taskId, machineId }),
+      p2p: offerP2PFor(payload.p2p, { taskId, machineId, peerKey }),
     },
     skipped: null,
   };
@@ -1201,19 +1254,55 @@ function buildOfferFrame({ taskId, lease, payload, originMachineId }) {
  *
  * @param {P2PNode} node
  * @param {object} frame
- * @returns {Promise<{ok: boolean, error: string|null, session: number|null, reused: boolean}>}
+ * @param {{peerKey?: string|null, peerKeys?: object|null}} [crypto]
+ *   `peerKey` is the target's static public key, published in this very frame
+ *   (`frame.p2p.static_keys[machine_id]`) so the executor can dial back; it is handed to `dial()` as
+ *   well because the *dispatcher* is the initiator here and needs the executor's key to handshake.
+ *   `peerKeys` is the node's own store, taught the same key so the accept side can verify the
+ *   executor's handshake later without a second relay lookup.
+ * @returns {Promise<{ok: boolean, error: string|null, session: number|null, reused: boolean,
+ *   encrypted: boolean, encryption_reason: string|null}>}
  */
-async function pushOffer(node, frame) {
+async function pushOffer(node, frame, crypto = {}) {
   const session = Number.isInteger(frame?.p2p?.session) && frame.p2p.session > 0 ? frame.p2p.session : undefined;
+  const peerKey = typeof crypto.peerKey === 'string' && crypto.peerKey !== '' ? crypto.peerKey : null;
+  if (peerKey !== null && crypto.peerKeys !== null && crypto.peerKeys !== undefined) {
+    // Recorded before the dial: the executor's handshake answer arrives on the same socket, and the
+    // `accept()` loop that has to verify it runs on this node. A key learned only from the relay's
+    // answer would be a second lookup racing that datagram.
+    crypto.peerKeys.set(frame.machine_id, peerKey, 'relay');
+  }
+  // The dial's own options, built here rather than inline because the *presence* of `crypto` is the
+  // decision: `P2PNode.dial` arms a handshake only when this dispatcher holds a key for that peer, and
+  // a peer with no published key is dialled exactly as v0.5.x dialled it — plaintext, recorded, and
+  // never a failure. That is §4's fallback clause applied to the push: a fleet must never lose a
+  // machine to a security upgrade. It is not a silent downgrade, because the peer never offered a key
+  // to downgrade *from*; a peer whose key we hold and whose handshake fails produces `ok: false` and
+  // no channel at all.
+  const dialOptions = session === undefined ? {} : { session };
   try {
-    const dialled = await node.dial(frame.machine_id, session === undefined ? {} : { session });
+    const dialled = await node.dial(frame.machine_id, dialOptions);
     if (!dialled.ok) {
-      return { ok: false, error: dialled.error ?? 'P2P_DIAL_FAILED', session: dialled.session ?? null, reused: false };
+      return {
+        ok: false,
+        error: dialled.error ?? 'P2P_DIAL_FAILED',
+        session: dialled.session ?? null,
+        reused: false,
+        encrypted: false,
+        encryption_reason: dialled.encryption_reason ?? null,
+      };
     }
     const channel = dialled.channel;
     try {
       await channel.send(JSON.stringify(frame));
-      return { ok: true, error: null, session: dialled.session ?? null, reused: dialled.reused === true };
+      return {
+        ok: true,
+        error: null,
+        session: dialled.session ?? null,
+        reused: dialled.reused === true,
+        encrypted: channel?.encryption?.encrypted === true,
+        encryption_reason: channel?.encryption?.reason ?? null,
+      };
     } 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.
@@ -1225,6 +1314,8 @@ async function pushOffer(node, frame) {
       error: `P2P_PUSH_THREW: ${error instanceof Error ? error.message : String(error)}`,
       session: session ?? null,
       reused: false,
+      encrypted: false,
+      encryption_reason: null,
     };
   }
 }
@@ -1238,11 +1329,19 @@ async function pushOffer(node, frame) {
  * were never handed the command, and sending them an offer would be asking them to run work the
  * relay decided they must not run.
  *
+ * v0.6.0: each target's static key is fetched from the relay's peer record before the push, which is
+ * the one moment the dispatcher learns the key of a machine it did not already know. It is fetched
+ * **here** rather than sourced from the stored `p2p` block because the block is written *before* the
+ * relay decides which machines the task goes to — the offer that carries the key is the one addressed
+ * to the machine that key belongs to. A missing key is not an error: the push proceeds and the
+ * executor records `P2P_CRYPTO_NO_KEY` for its plaintext channel, which is the documented outcome for
+ * a peer that never announced.
+ *
  * @param {P2PNode} node
  * @param {object} options
  * @returns {Promise<Array<object>>} One entry per lease considered, in lease order.
  */
-async function pushOffers(node, { taskId, leases, payload, originMachineId }) {
+async function pushOffers(node, { taskId, leases, payload, originMachineId, getJson = null }) {
   const out = [];
   for (const lease of leases) {
     const machineId = typeof lease?.machine_id === 'string' && lease.machine_id !== '' ? lease.machine_id : null;
@@ -1259,12 +1358,13 @@ async function pushOffers(node, { taskId, leases, payload, originMachineId }) {
       });
       continue;
     }
-    const built = buildOfferFrame({ taskId, lease, payload, originMachineId });
+    const peerKey = await readPeerStaticKey(getJson, machineId);
+    const built = buildOfferFrame({ taskId, lease, payload, originMachineId, peerKey });
     if (built.frame === null) {
       out.push({ machine_id: machineId, ok: false, error: built.skipped });
       continue;
     }
-    const result = await pushOffer(node, built.frame);
+    const result = await pushOffer(node, built.frame, { peerKey, peerKeys: node?.peerKeys ?? null });
     out.push({
       machine_id: machineId,
       ok: result.ok,
@@ -1277,11 +1377,42 @@ async function pushOffers(node, { taskId, leases, payload, originMachineId }) {
       // 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,
+      // v0.6.0: whether the offer actually travelled sealed, and why not when it did not. Reported
+      // per machine because it is a per-machine fact: one peer can be encrypted and the next one a
+      // v0.5.x build in the same dispatch.
+      encrypted: result.encrypted === true,
+      ...(result.encryption_reason === null || result.encryption_reason === undefined
+        ? {}
+        : { encryption_reason: result.encryption_reason }),
+      ...(peerKey === null ? {} : { static_key: 'published' }),
     });
   }
   return out;
 }
 
+/**
+ * Read one machine's static public key from the relay's peer record, or explain why not.
+ *
+ * Never throws and never fails a dispatch: a relay that answers 404 (the peer never announced, or its
+ * announcement expired between the task and the push) leaves this machine unencrypted for that peer
+ * and says so, which is precisely §4's "a fleet must never lose a machine because a security upgrade
+ * could not complete".
+ *
+ * @param {((path: string) => Promise<object>)|null} getJson
+ * @param {string} machineId
+ * @returns {Promise<string|null>}
+ */
+async function readPeerStaticKey(getJson, machineId) {
+  if (typeof getJson !== 'function') return null;
+  try {
+    const answer = await getJson(`/v1/peer/${encodeURIComponent(machineId)}`);
+    const key = answer?.json?.peer?.static_key;
+    return typeof key === 'string' && key !== '' ? key : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Build the object the tools reach the direct path through, and register its effect disposer.
  *
@@ -1381,6 +1512,40 @@ function createP2PRuntime(ctx, cfg, block = {}) {
   return runtime;
 }
 
+/**
+ * Read the dispatcher's own static keypair, or explain why there is none (v0.6.0).
+ *
+ * The key lives beside `device.json`, which is the one directory this plugin already knows how to
+ * find (§ the note on `readDevice`): a `stateDir` when the operator set one, otherwise the
+ * `DSH_HOME/xclient` default. Generating it here is the same "generated the first time a machine
+ * pairs" rule the agent follows, and the two processes read the *same file*, so a machine that both
+ * dispatches and executes has one identity on the direct path rather than two.
+ *
+ * Never throws. A caller cannot fix an unreadable key file from a tool call, and a dispatch that
+ * refused because a *security upgrade* could not complete would be exactly the fleet-losing failure
+ * §4 forbids — so the failure becomes a reason string, the node runs without a key, and every offer
+ * this machine publishes is plainly labelled as having none.
+ *
+ * @param {object|null} injected Test seam: a `DeviceKey`, or null to use the file.
+ * @param {string|null} deviceFile Absolute path of `device.json`, or null when unknown.
+ * @returns {{key: object|null, error: string|null}}
+ */
+function loadDeviceKey(injected, deviceFile) {
+  if (injected !== null && injected !== undefined) return { key: injected, error: null };
+  if (typeof deviceFile !== 'string' || deviceFile === '') {
+    return { key: null, error: 'P2P_CRYPTO_NO_KEY: device.json was not located, so device.key has no directory' };
+  }
+  try {
+    const loaded = DeviceKey.load({ dir: path.dirname(deviceFile) });
+    return { key: loaded.key, error: null };
+  } catch (error) {
+    return {
+      key: null,
+      error: `P2P_CRYPTO_KEY_UNREADABLE: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
 /**
  * Read the identity, build the node, and start it.
  *
@@ -1406,6 +1571,19 @@ async function initP2P(ctx, cfg, runtime, block) {
     return runtime.start;
   }
 
+  // v0.6.0: the dispatcher's own static keypair, beside device.json. A failure here is *not* fatal
+  // and must not stop the node: a machine with an unreadable key file is still a working W2M machine
+  // whose tasks travel over the relay, which is the same rule every other crypto failure follows.
+  // What it must not do is pretend: the key stays null, `runtime.encryption.reason` names the
+  // failure, and every offer this machine publishes says no keys.
+  const keyLoad = loadDeviceKey(block.deviceKey ?? null, identity.path);
+  runtime.deviceKey = keyLoad.key;
+  runtime.encryption = {
+    enabled: keyLoad.key !== null,
+    public_key: keyLoad.key === null ? null : keyLoad.key.publicKeyBase64,
+    error: keyLoad.error,
+  };
+
   const transport = createP2PTransport(cfg);
   // `ctx.effect` owns the node when the host provides it, and the fallback is the same ownership
   // with a shorter lifetime: a host that provides no effect (an older Cordis, or a bare test
@@ -1418,6 +1596,7 @@ async function initP2P(ctx, cfg, runtime, block) {
     getJson: transport.getJson,
     stunServers: cfg.stunServers,
     log: (line) => ctx?.logger?.info?.(`w2m ${line}`),
+    ...(keyLoad.key === null ? {} : { deviceKey: keyLoad.key }),
     ...block,
   });
 
@@ -1604,6 +1783,22 @@ async function readP2PStatus(cfg, runtime, peersAnnounced = null) {
     punches_in: status?.punches_in ?? 0,
     dial_failures: status?.dial_failures ?? 0,
     transport: p2pTransportFacts(runtime.node),
+    // v0.6.0: the crypto facts, named one by one rather than mirrored wholesale. `enabled` is about
+    // *this* machine's key; `encrypted_channels` and `plaintext_channels` are about the channels it
+    // has actually made, and they can both be non-zero on a mixed fleet. `error` is the reason there
+    // is no key when there is none — a reader has to be able to tell "this build has no crypto" from
+    // "the key file is unreadable" without reading a log.
+    encryption: {
+      enabled: runtime.encryption?.enabled === true,
+      public_key: runtime.encryption?.public_key ?? null,
+      error: runtime.encryption?.error ?? null,
+      peers_known: status?.encryption?.peers_known ?? 0,
+      handshakes: status?.encryption?.handshakes ?? 0,
+      encrypted_channels: status?.encryption?.encrypted_channels ?? 0,
+      plaintext_channels: status?.encryption?.plaintext_channels ?? 0,
+      refused: status?.encryption?.refused ?? 0,
+      refusals: Array.isArray(status?.encryption?.refusals) ? status.encryption.refusals : [],
+    },
     inbox: {
       dir: runtime.inboxDir,
       depth: inboxDepth,
@@ -2662,6 +2857,32 @@ export async function apply(ctx, config = {}) {
   // still has to dispatch, and `w2m_status` is where the failure is reported.
   const p2p = createP2PRuntime(ctx, cfg, config.p2pBlock);
 
+  /**
+   * This machine's fleet identity, read once per successful resolution.
+   *
+   * The memoization rule lives in {@link createLocalIdentity} so the route half and the tool half
+   * cannot disagree about when a missing identity becomes a stale one.
+   */
+  const localIdentity = createLocalIdentity(async () => {
+    const device = await readDevice({ stateDir: cfg.stateDir });
+    return { machine_id: device.machine_id, machine_name: device.machine_name, machineName: cfg.machineName };
+  });
+
+  // v0.6.1: the two browser routes behind the composer's target control. Additive and optional: a
+  // host without `connection.fetch` still gets every tool, and `w2m_status` reports the absence —
+  // which is the honest place for it, since a host that has no Connection at all is simply not a web
+  // composition and does not need a warning on every headless run.
+  const targetRoutes = registerTargetRoutes(ctx, {
+    cfg: () => cfg,
+    store: defaultSelectionStore,
+    localIdentity,
+    request,
+    resolveToken,
+  });
+  if (targetRoutes.unexpected) {
+    ctx.logger?.warn?.(`w2m: the composer target control is inactive — ${targetRoutes.reason}`);
+  }
+
   /** Text output: rendered as JSON, because every one of these tools answers with a structure. */
   const jsonOutput = {
     schema: { type: 'string' },
@@ -2689,48 +2910,61 @@ export async function apply(ctx, config = {}) {
       throwIfAborted(exec?.signal);
       const base = requireRabbit(cfg);
       const token = await resolveToken(cfg);
-      const result = await request({
+
+      // The read itself, the liveness rule, and "this machine has no identity yet" all come from
+      // the same helper the composer control uses, so the list a model reads and the list an
+      // operator clicks can never disagree about who is online.
+      const identity = await localIdentity();
+      const fleet = await readFleet({
         rabbitUrl: base,
         token,
+        localMachineId: identity.machine_id,
         signal: exec?.signal,
-        pathname: '/v1/devices',
+        request,
       });
-      if (!result.ok) {
-        throw new W2MError('W2M_RABBIT_REFUSED', `W2M_RABBIT_REFUSED: the Rabbit refused GET /v1/devices with HTTP ${result.status}${result.error ? ` (${result.error.code}: ${result.error.message})` : ''}; ${result.status === 401 ? 'this machine is not paired, or its device_token is stal - pair the agent again' : 'check the Rabbit log for the reason it gave'}`, {
-          hint: result.status === 401
-            ? 'this machine is not paired, or its device_token is stale; pair the agent again'
-            : 'check the Rabbit log for the reason it gave',
-        });
+      if (!fleet.ok) {
+        // The typed error is rebuilt here, from the helper's report, so the code, message and hint a
+        // caller sees are the same three it saw before this read moved into `fleet-target.mjs`: the
+        // remediation travels in `hint`, never in the message.
+        const unauthorized = fleet.status === 401;
+        throw new W2MError(
+          unauthorized ? 'W2M_RABBIT_REFUSED' : 'W2M_UNREACHABLE',
+          fleet.status === 0
+            ? `${fleet.error}`
+            : `${fleet.error}; ${unauthorized ? 'this machine is not paired, or its device_token is stale - pair the agent again' : 'check the Rabbit log for the reason it gave'}`,
+          {
+            hint: fleet.hint ?? (unauthorized
+              ? 'this machine is not paired, or its device_token is stale; pair the agent again'
+              : 'check the Rabbit log for the reason it gave'),
+          },
+        );
       }
 
       // `GET /v1/devices` answers `{protocol_version, rabbit_time, devices:[...]}`. Each entry is a
       // device recor - the Rabbit's own lease bookkeeping is on the task, not her - so a device
-      // is described by identity and capabilities, and "online" is the honest default for a device
-      // the Rabbit still lists.
-      const machines = Array.isArray(result.json?.devices)
-        ? result.json.devices
-        : (Array.isArray(result.json?.machines) ? result.json.machines : []);
+      // is described by identity and capabilities, and the relay's own `state` is the honest
+      // default for a device it still lists.
       const includeStale = args?.include_stale === true;
-      const listed = machines.filter((machine) => includeStale || String(machine?.state ?? 'online') !== 'expired');
+      const listed = fleet.records.filter((machine) => includeStale || String(machine?.state ?? 'online') !== 'expired');
 
       return JSON.stringify(
         {
           ok: true,
           protocol_version: PROTOCOL_VERSION,
-          rabbit_time: result.json?.rabbit_time ?? null,
+          rabbit_time: fleet.rabbit_time,
           count: listed.length,
           devices: listed.map((machine) => ({
             machine_id: machine?.machine_id ?? null,
             name: machine?.machine_name ?? machine?.name ?? null,
-            os: machine?.platform?.os ?? null,
-            os_version: machine?.platform?.os_version ?? null,
-            arch: machine?.platform?.arch ?? null,
-            shell: machine?.platform?.shell ?? null,
+            os: machine?.platform?.os ?? machine?.os ?? null,
+            os_version: machine?.platform?.os_version ?? machine?.os_version ?? null,
+            arch: machine?.platform?.arch ?? machine?.arch ?? null,
+            shell: machine?.platform?.shell ?? machine?.shell ?? null,
             caps: machine?.caps ?? null,
             last_seen: machine?.last_seen ?? machine?.last_seen_at ?? null,
             state: machine?.state ?? 'online',
           })),
-          excluded_stale: includeStale ? 0 : machines.length - listed.length,
+          excluded_stale: includeStale ? 0 : fleet.records.length - listed.length,
           note:
             'a listed device has paired and is being tracked; it can still refuse the next command ' +
             'at the capability gate, which w2m_wait reports per machine as `refused`',
@@ -2754,7 +2988,10 @@ export async function apply(ctx, config = {}) {
       'Anchors (base_commit, base_tree) are computed here from this machine\'s working tree so ' +
       'the peers can be checked against them. Under the default p2pMode the offer is also pushed ' +
       'over the direct path, best effort: `direct_pushes` names every attempt, and the relay\'s ' +
-      'own offer remains the delivery when a push fails.',
+      'own offer remains the delivery when a push fails. ' +
+      'A machine selected in the composer for this session narrows the dispatch to that machine; ' +
+      'an explicit `executor_machine_id` always wins over it, and the answer\'s `selection` says ' +
+      'which of the two routed the task.',
     parameters: {
       command_argv: {
         type: 'array',
@@ -2977,6 +3214,34 @@ export async function apply(ctx, config = {}) {
         );
       }
 
+      // -------------------------------------------------------------------------------------------
+      // v0.6.1: the session's chosen target, when the caller named no machine of its own.
+      // -------------------------------------------------------------------------------------------
+      //
+      // The composer control writes a selection into this process, keyed by session; here is where
+      // it becomes real. Read before the payload literal so the routing facts and the answer agree.
+      //
+      // The precedence rule is the whole contract, and it is one line: **the caller's own fields
+      // always win**. `executor_machine_id` is checked below, and `target_machines` is never a tool
+      // argument — so a caller that named a machine (which, for this tool, means
+      // `executor_machine_id` under broadcast) is untouched, and a caller that named none inherits
+      // the selection. Nothing already published changes meaning: the selection only fills fields
+      // that were absent, and the relay has accepted both of them since v0.3.3/v0.4.1.
+      const sessionKey = sessionKeyFor(exec);
+      const selection = defaultSelectionStore.get(sessionKey);
+      const routedBy = dispatchSelectionFields(selection, mode);
+      // broadcast reads the executor field; everything else reads `target_machines`. The relay
+      // ignores the field a mode does not read, and the two are never both set by a selection.
+      const selectionFields = mode === 'broadcast' && executorMachineId !== null
+        ? { fields: {}, applied_as: null }
+        : routedBy.fields;
+      // Whether the selection actually routed THIS task. Reported in the answer, because it is the
+      // one thing an operator cannot recover afterwards: the payload is not in the transcript, and
+      // the same command run twice can legitimately take two different routes.
+      const selectionAppliedAs = mode === 'broadcast' && executorMachineId !== null
+        ? null
+        : routedBy.applied_as;
+
       // Plugin-side allow-list check: only when one is configured. See checkAllowedCommand.
       //
       // **Every** stage is checked, not just the first. Checking only `command_argv` would let a
@@ -3073,6 +3338,10 @@ export async function apply(ctx, config = {}) {
         // Only sent for broadcast; the relay ignores it otherwise, and the validation above already
         // refused the combination, so this cannot silently mean nothing.
         ...(executorMachineId !== null ? { executor_machine_id: executorMachineId } : {}),
+        // v0.6.1: the elected machine, when the caller did not name one and a mode that reads it is
+        // in play. Spread after the caller's own field above so the caller always wins even if a
+        // future edit makes both possible.
+        ...selectionFields,
         // Only for pipeline. The relay ignores `stages` under the other modes and the validation
         // above refuses the combination, so this can never silently mean nothing.
         ...(mode === 'pipeline' && stagesPayload !== null ? { stages: stagesPayload } : {}),
@@ -3096,15 +3365,22 @@ export async function apply(ctx, config = {}) {
         // OPERATOR_REQUIRED gets its own guidance: it is the one refusal whose fix is a client-side
         // setting rather than something on the relay.
         const operatorRequired = result.error?.code === 'OPERATOR_REQUIRED' || result.status === 401;
+        // v0.6.1: when a task was elected to one machine, NO_ONLINE_DEVICE is the *machine* being
+        // unreachable, not the fleet being empty -- and the two have different fixes. Saying so is
+        // the difference between "start an agent" and "the machine you picked went away".
+        const selectedName = selection?.machine_name ?? selection?.machine_id ?? null;
+        const selectedMissing = result.error?.code === 'NO_ONLINE_DEVICE' && selectionAppliedAs !== null;
         throw new W2MError(
           'W2M_RABBIT_REFUSED',
-          `W2M_RABBIT_REFUSED: the Rabbit refused POST /v1/task with HTTP ${result.status}${result.error ? ` (${result.error.code}: ${result.error.message})` : ''}; ${operatorRequired ? 'this relay requires the operator token to dispatch tasks and the one sent was not accepted - set `operatorToken` (or `W2M_OPERATOR_TOKEN`) to the value the relay printed at startup; a device token cannot dispatch tasks' : result.error?.code === 'NO_ONLINE_DEVICE' ? 'no machine is currently streaming - start the agent on each machine, then w2m_devices shows who is online' : 'check the Rabbit log for the reason it gave'}`,
+          `W2M_RABBIT_REFUSED: the Rabbit refused POST /v1/task with HTTP ${result.status}${result.error ? ` (${result.error.code}: ${result.error.message})` : ''}; ${operatorRequired ? 'this relay requires the operator token to dispatch tasks and the one sent was not accepted - set `operatorToken` (or `W2M_OPERATOR_TOKEN`) to the value the relay printed at startup; a device token cannot dispatch tasks' : selectedMissing ? `this session's selected machine (${selectedName}) is not among the machines the relay currently holds, so a task narrowed to it has no target - pick another machine in the composer, or clear the selection` : result.error?.code === 'NO_ONLINE_DEVICE' ? 'no machine is currently streaming - start the agent on each machine, then w2m_devices shows who is online' : 'check the Rabbit log for the reason it gave'}`,
           {
             hint: operatorRequired
               ? 'set `operatorToken` (or `W2M_OPERATOR_TOKEN`) to the value the relay printed at startup, or read it from `<state>/operator-token.txt`'
-              : result.error?.code === 'NO_ONLINE_DEVICE'
-                ? 'no machine is currently streaming; start the agent on each machine (w2m_devices shows who is online)'
-                : 'check the Rabbit log for the reason it gave',
+              : selectedMissing
+                ? `the selected target was sent as ${selectionAppliedAs}=${selection?.machine_id ?? ''}; clear the composer selection to dispatch to the whole fleet again`
+                : result.error?.code === 'NO_ONLINE_DEVICE'
+                  ? 'no machine is currently streaming; start the agent on each machine (w2m_devices shows who is online)'
+                  : 'check the Rabbit log for the reason it gave',
           },
         );
       }
@@ -3140,6 +3416,9 @@ export async function apply(ctx, config = {}) {
             leases: Array.isArray(result.json?.leases) ? result.json.leases : [],
             payload,
             originMachineId,
+            // v0.6.0: where each target's static public key is read from, so the offer addressed to a
+            // machine can carry the key that machine needs to authenticate the dispatcher's handshake.
+            getJson: p2p.node?.getJson ?? null,
           });
           directPushes = {
             ...directPushes,
@@ -3184,6 +3463,19 @@ export async function apply(ctx, config = {}) {
           // v0.4.0: what the direct path tried, per machine. `mode` is repeated here rather than left
           // to `w2m_status` so one dispatch's answer is self-contained.
           direct_pushes: directPushes,
+          // v0.6.1: whether this dispatch was narrowed to the composer's selected machine, and to
+          // which one. Published because a dispatch that ran somewhere other than where the operator
+          // pointed is the one failure this feature could hide, and a caller that cannot see the
+          // routing cannot report it.
+          selection: selection === null
+            ? { applied: false, field: null, machine_id: null, machine_name: null, session: sessionKey }
+            : {
+                applied: selectionAppliedAs !== null,
+                field: selectionAppliedAs,
+                machine_id: selection.machine_id,
+                machine_name: selection.machine_name,
+                session: sessionKey,
+              },
           note: anchors.base_tree === null
             ? 'this machine\'s working tree could not be fingerprinted, so peers have no anchor to match and the aggregate will be unverifiable'
             : 'peers are checked against base_commit + base_tree + command_hash',
@@ -3592,6 +3884,23 @@ export async function apply(ctx, config = {}) {
             fingerprint_algo: 'git-temp-index-tree/v1',
             error: anchors.error,
           },
+          /**
+           * v0.6.1: the composer's target control and the selections it holds.
+           *
+           * Reported here because "the control is not in my composer" has exactly two causes — the
+           * host has no fetch-route registry, or the browser half is not loaded — and this is the
+           * one call that can tell them apart from the host side. The selections themselves are
+           * counts, not contents: which session picked which machine is the operator's business and
+           * nothing the model needs.
+           */
+          target_selection: {
+            route: TARGET_ROUTE_PATH,
+            attached: targetRoutes.mounted,
+            detail: targetRoutes.mounted
+              ? 'the composer control reads and writes its selection through this route'
+              : targetRoutes.reason,
+            sessions_with_a_target: defaultSelectionStore.list().length,
+          },
           notes: statusNotes(relay, rtt, cfg, p2pStatus),
         },
         null,