create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/remote-machine-create.js

@@ -1,5 +1,11 @@
 'use strict';
 
+// WP-13 (D-15): the canonical agent resolver, used by `remoteCreateAgentKey` below so a DECLARED
+// `agentType` is classified through the same table server.js's create path resolves the CLI with
+// (aliases such as 'deepseek-harness'/'deepseek_harness'/'claude-code' included). agent-capabilities.js
+// is a leaf module (it requires nothing), so this edge adds no cycle to the lib/** graph.
+const { normalizeAgentType } = require('./agent-capabilities');
+
 // WP-2 (docs/remote-machine-hub-sessions-2026-10-22.html §5 D-6/D-10, §6.3, §9 S-1/S-2/S-26):
 // hub-side remote create. A `create` frame that names a REGISTERED REMOTE machine is never
 // prepared locally — it is filtered through the §6.3 allowlist and forwarded to that box over a
@@ -64,8 +70,23 @@ const REMOTE_CREATE_FORWARD_ALLOWLIST = Object.freeze([
   'chatSessionId',
 ]);
 
+// WP-3 (docs/session-create-accept-then-complete-2026-11-01.html §6.3 D-3/D-4): PHASE A — dial to
+// the box's `create-accepted` (or to a final `created`/`error`). Unchanged.
 const DEFAULT_TIMEOUT_MS = 15000;
 
+// WP-3 (D-4): PHASE B — `create-accepted` to `created`. The hub must never give up before the box
+// legitimately could, so this ceiling is derived from the BOX's own bounded create phases (97.5 s,
+// §1.1 of the design doc) and is the same 120 s as the box-local create-intent lease
+// (lib/create-intent-lease.js CREATE_INTENT_LEASE_MS) and the push's BACKGROUND_CEILING_MS
+// (lib/agent-bundle/push.js). tests/remote-create-ceiling-covers-box.test.js fails if a box-side
+// bound is raised without raising this one with it.
+const CREATE_ACCEPTED_CEILING_MS = 120000;
+
+// WP-3 (D-5): an accepted create that then goes quiet is NOT a failure — the box is still starting
+// the session and the hub never cancels it (D-6). It gets its own code so the client can show a
+// warning and keep the pending create instead of a machine error.
+const MACHINE_CREATE_UNCONFIRMED = 'machine_create_unconfirmed';
+
 // WP-1 (D-2): a missing peer credential is a CONFIGURATION error, not an unreachable box. The box
 // may be perfectly reachable — the hub simply has nothing to authenticate with, and no retry can
 // change that (env is read at process start). Every hub→box lane reports this one code, so an
@@ -108,6 +129,21 @@ function _productionDeps() {
     db: require('../db-owner-client'),
     registry: require('./machine-registry'),
     parseSyncPeers: require('./hosted-sync-worker').parseSyncPeers,
+    // WP-3 §6.5: the agent-skill push (D-4/D-6). Required lazily like everything else here so a
+    // caller that only wants the pure filter never loads the bundle builder.
+    pushAgentBundle: (machine, options) => require('./agent-bundle/push').pushBundleToBox(machine, options),
+    // The plugins this hub must NOT ship to a box (WP-8 §6.5). The list is per MACHINE and lives in
+    // one hub-side JSON file (`<data dir>/agent-bundle-exclude-plugins.json`), read through
+    // lib/agent-bundle/skill-transfer.js's in-memory cache — the same reader the Machines row and the
+    // PUT route use, so the push and the UI can never disagree about what is excluded. `getDataDir()`
+    // is required lazily like everything else here: a caller that only wants the pure filter must not
+    // load the data-dir module.
+    agentBundleExcludePlugins: async (instanceId) => {
+      const skillTransfer = require('./agent-bundle/skill-transfer');
+      const dataDir = require('./data-dir').getDataDir();
+      await skillTransfer.loadExcludePlugins(dataDir);
+      return skillTransfer.excludePluginsFor(dataDir, instanceId);
+    },
     // WP-6 §8: the post-create catalog refresh (lazy: the catalog module requires THIS one).
     refreshCatalog: (machineId) => {
       try {
@@ -141,19 +177,29 @@ function filterRemoteCreateForward(msg) {
 /**
  * WP-3 (DGX Spark coding readiness §2): which coding agent — if any — a forwarded create is about.
  * The create path picks the CLI from `msg.agentType || detectAgentType(cmd)` (server.js:34024, whose
- * canonical values are exactly 'claude' | 'codex' — lib/agent-capabilities.js:19,45 and
+ * canonical values are 'claude' | 'codex' | 'dsh' — lib/agent-capabilities.js and
  * lib/create/resolve-launch-params.js:692, which also writes the matching bare `cmd` at :772/:824,
- * the same shape public/js/reviews.js:858 sends). Only those two can be signed out, so a `null`
- * (shell / gemini / walle / anything else) is never refused — the caller checks the sign-in verdict
- * for that agent only. Pure and total: any other shape reads `null`.
+ * the same shape public/js/reviews.js:858 sends; a dsh create carries `agentType:'dsh'`/`cmd:'dsh'`,
+ * public/m/app.js:13868). WP-13 (D-15) adds 'dsh': a forwarded dsh create runs the SAME handleCreate
+ * on the box, which resolves its OWN dsh binary, proxy port and route (D-11 box-side), so the hub
+ * sends nothing dsh-specific. Only claude/codex can be signed out, so a `null` (shell / gemini /
+ * walle / anything else) is never refused — the caller checks the sign-in verdict per agent, and a
+ * `'dsh'` verdict is never consulted (there is no CTM sign-in for dsh). Pure and total: any other
+ * shape reads `null`.
  */
+const DSH_AGENT_KEY = 'dsh';
+
 function remoteCreateAgentKey(payload) {
-  const agentType = _string(payload && payload.agentType, 40).toLowerCase();
-  if (agentType === 'claude' || agentType === 'codex') return agentType;
+  // The DECLARED agentType goes through the canonical normalizer — the same read the box's own
+  // create path makes of it — so an alias resolves to the agent the box will actually launch.
+  const declared = normalizeAgentType(_string(payload && payload.agentType, 40));
+  if (declared === 'claude' || declared === 'codex' || declared === DSH_AGENT_KEY) return declared;
+  // The bare `cmd` is matched EXACTLY on its basename: the create path writes that bare token, and a
+  // hub must not guess at a path/flag tokenization the box would do differently.
   const cmd = _string(payload && payload.cmd, 300);
   if (!cmd) return null;
   const base = cmd.split(/[\\/]/).pop().toLowerCase();
-  return base === 'claude' || base === 'codex' ? base : null;
+  return base === 'claude' || base === 'codex' || base === DSH_AGENT_KEY ? base : null;
 }
 
 /** The hub's own minted instance id, or '' when identity is not available yet. */
@@ -191,6 +237,42 @@ function _findMachine(machineId, deps) {
   return machines.find((row) => _string(row.instanceId, 160) === machineId) || null;
 }
 
+/**
+ * WP-13 (D-15): does the TARGET BOX say it does not have `agentKey`? This is the box's OWN
+ * available-agents answer — the same read the New Session card disables the dsh card from — and it
+ * is INJECTED (`deps.registry.agentAvailabilityFor(instanceId)`), exactly like the WP-3 sign-in read
+ * above and for the same reason: the verdict belongs to the box, and a host/test registry that does
+ * not carry the read holds NO verdict.
+ *
+ * P3 applies to the failure direction: only an explicit "the box does not have it" refuses. A
+ * missing provider, a non-object answer, a 404/shape the hub does not recognise, or an entry the
+ * block does not carry all read `false` ("no verdict") and the create is dialled exactly as before —
+ * the box's own create path is then the authority, and its failure is relayed verbatim.
+ *
+ * Accepted shapes (the hub must not care which one its registry serves):
+ *   { agents: { dsh: { available: false, path: null } } }   - `/api/models/available-agents`, verbatim
+ *   { dsh: false } | { dsh: true } | { dsh: { available: false } }
+ *
+ * @returns {boolean} true only for an explicit "this box does not have it".
+ */
+function _boxAgentMissing(d, row, agentKey) {
+  const registry = d && d.registry;
+  if (!registry || typeof registry.agentAvailabilityFor !== 'function') return false;
+  let answer = null;
+  try {
+    answer = registry.agentAvailabilityFor(_string(row && row.instanceId, 160));
+  } catch {
+    return false; // REPORT: an unreadable verdict is "no verdict", never a refusal
+  }
+  if (!answer || typeof answer !== 'object') return false;
+  const block = answer.agents && typeof answer.agents === 'object' ? answer.agents : answer;
+  const detail = block[agentKey];
+  if (detail === undefined || detail === null) return false;
+  if (typeof detail === 'boolean') return detail === false;
+  if (typeof detail === 'object') return detail.available === false;
+  return false;
+}
+
 function _parsePeerTokenMap(raw = '') {
   const value = _string(raw, 10000);
   const map = new Map();
@@ -253,13 +335,19 @@ function _ownForwardId(env, deps) {
  *        `machine_forward_loop`. The value is the sender's minted instance id (the same id the
  *        `machine` routing field uses), read through lib/instance-identity-access; it falls back to
  *        the env instance tag so a pre-boot dial still names the sender.
+ *   D-1  (docs/remote-skills-hub-peer-identity-2026-10-26.html §5 D-1/D-2) the ENV leg's peer id
+ *        falls back to the sender's minted instance id when the process env names none — a
+ *        launchd/systemd hub has no shell `HOSTNAME`, and the box keys every peer-scoped route by
+ *        this header (403 agent_bundle_peer_unidentified otherwise). An env-named id still wins.
  *
  * Returns null when NO credential is configured (then the caller reports peer_credential_missing).
  */
 function buildPeerControlHeaders(env = process.env, deps = {}) {
-  const peerId = _string(env.CTM_INSTANCE_ID || env.CTM_INSTANCE_TAG || env.HOSTNAME || '', 160);
   const forwardedBy = _ownForwardId(env, deps);
-  const envToken = _envPeerToken(env, peerId);
+  // An env-named id wins; else the minted instance id — a launchd/systemd hub has no shell HOSTNAME,
+  // and the box keys every peer-scoped route by this header (remote-skills-hub-peer-identity D-1).
+  const peerId = _string(env.CTM_INSTANCE_ID || env.CTM_INSTANCE_TAG || env.HOSTNAME || '', 160) || forwardedBy;
+  const envToken = _envPeerToken(env, peerId); // D-2: the SAME id for the map lookup
   const poolToken = _poolToken();
   // P-8: the per-target decision. A named non-member is dialled with the env bearer so a legacy
   // box keeps answering; an unnamed target keeps the pool-if-pool behaviour this function had.
@@ -397,35 +485,91 @@ function peerClientInfoFrame(hello) {
     terminalProtocol: Number((hello && hello.terminalProtocol) || appVersion.terminalProtocol || 0),
     assetEpoch: String(appVersion.assetEpoch || ''),
     surface: 'machine-hub',
+    // WP-2 (docs/relay-frame-v2-negotiation-box-session-mouse-2026-10-31.html §5 R-4, §6): the hub's
+    // peer identity is a hub viewer too, so it negotiates frame protocol v2 on its own behalf and
+    // lib/remote-machine-link.js projects each `frame-v2` down per RECEIVING hub socket (R-3).
+    terminalCapabilities: { frameContentV2: true },
   };
 }
 
+/**
+ * WP-0 (§6.3, D-8): the four dial timings, all measured from the DIAL START and `-1` for a phase
+ * that was never reached. WP-3 fills `acceptedMs` in — it is the `create-accepted` frame's offset
+ * (D-3) — and it stays `-1` for every dial whose box never accepted, which is exactly the failed
+ * phase A the line has to show.
+ */
+function _noTimings() {
+  return { connectMs: -1, helloMs: -1, acceptedMs: -1, replyMs: -1 };
+}
+
 /**
  * One short-lived forward: connect, HELLO handshake, send the filtered create, wait for the
  * box's `created` (or `error`) frame, close. Never throws — the caller turns a failure into the
  * `machine_unreachable` (or box-error) frame.
  *
- * @returns {Promise<{ok: true, frame: object}|{ok: false, code: string, error: string}>}
+ * WP-3 (§6.3 D-3..D-6): the wait is in TWO phases. Phase A (DEFAULT_TIMEOUT_MS, unchanged) runs
+ * from the dial to the box's `create-accepted` — or straight through to `created`/`error`, which is
+ * what an older box answers. A matching `create-accepted` ends phase A, calls `onAccepted` exactly
+ * once and arms phase B (CREATE_ACCEPTED_CEILING_MS). After acceptance, silence, a socket close or a
+ * socket error is `machine_create_unconfirmed` — the box owns the create from that moment and the hub
+ * never cancels it, so NOTHING is sent to the box on any phase-B exit (D-6).
+ *
+ * @param {object} options
+ * @param {string} options.machineUrl the box's registered url
+ * @param {object} options.payload the §6.3-filtered create (its `id` is the acceptance key, D-1)
+ * @param {object} options.deps the dial deps (env/registry/authHeaders/WebSocket/timers…)
+ * @param {number} [options.acceptedCeilingMs] phase B; also readable as `deps.acceptedCeilingMs`
+ * @param {null|function} [options.onAccepted] called once with the accepted frame; also `deps.onAccepted`
+ * @returns {Promise<{ok: true, frame: object, accepted: boolean, timings: object}
+ *                  |{ok: false, code: string, error: string, accepted: boolean, timings: object}>}
  */
-function sendRemoteCreate({ machineUrl, payload, deps }) {
+function sendRemoteCreate({ machineUrl, payload, deps, acceptedCeilingMs, onAccepted }) {
   return new Promise((resolve) => {
     const dial = preparePeerDial(machineUrl, deps);
-    if (!dial.ok) return resolve(dial);
+    if (!dial.ok) return resolve({ ...dial, accepted: false, timings: _noTimings() });
     const { url, headers, WebSocketImpl } = dial;
     const timeoutMs = Number(deps.timeoutMs || DEFAULT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+    // WP-3 (§6.3): phase B's ceiling and the acceptance hook. Both may ride the dial deps instead —
+    // the seam every other dial option already uses (`deps.timeoutMs`, `deps.setTimeoutFn`) — so a
+    // caller that drives this through forwardRemoteCreate passes neither of them here.
+    const ceilingMs = Number(acceptedCeilingMs || (deps && deps.acceptedCeilingMs) || CREATE_ACCEPTED_CEILING_MS) || CREATE_ACCEPTED_CEILING_MS;
+    const acceptedHook = typeof onAccepted === 'function'
+      ? onAccepted
+      : (deps && typeof deps.onAccepted === 'function' ? deps.onAccepted : null);
     const setTimeoutFn = typeof deps.setTimeoutFn === 'function' ? deps.setTimeoutFn : setTimeout;
     const clearTimeoutFn = typeof deps.clearTimeoutFn === 'function' ? deps.clearTimeoutFn : clearTimeout;
 
+    // WP-0 (§6.3): the dial clock. `dialStartedAt` is the dial's own origin and every timing below
+    // is an offset from it; a phase that never happened stays -1 (see _noTimings).
+    const dialStartedAt = Date.now();
+    let openedAt = -1;
+    let helloAt = -1;
+    let acceptedAt = -1;
+    let replyAt = -1;
+    const _since = (at) => (at < 0 ? -1 : at - dialStartedAt);
+    const timings = () => ({
+      connectMs: _since(openedAt),
+      helloMs: _since(helloAt),
+      acceptedMs: _since(acceptedAt), // WP-3 (D-3): the create-accepted offset, -1 when never accepted
+      replyMs: _since(replyAt),
+    });
+
+    // D-3/D-1: the create idempotency key this dial is for. A `create-accepted` naming any OTHER id
+    // is not this create's acceptance (one box WS endpoint serves many clients) and must not end
+    // phase A.
+    const createId = _string(payload && payload.id, 200);
+
     let socket = null;
     let timer = null;
     let settled = false;
+    let accepted = false;
     let sent = false;
     const finish = (result) => {
       if (settled) return;
       settled = true;
       if (timer) clearTimeoutFn(timer);
       try { if (socket) socket.close(); } catch { /* expected: close on an already-dead socket */ }
-      resolve(result);
+      resolve({ ...result, accepted, timings: timings() });
     };
     // Only ever after client-info (see the dial-order note above): a create sent earlier is
     // dropped by the box's protocol gate and the forward would hang until the timeout.
@@ -442,9 +586,25 @@ function sendRemoteCreate({ machineUrl, payload, deps }) {
     try {
       socket = new WebSocketImpl(url, { headers });
     } catch (error) {
-      return resolve({ ok: false, code: 'machine_unreachable', error: `connect_failed:${error?.message || error}` });
+      return resolve({ ok: false, code: 'machine_unreachable', error: `connect_failed:${error?.message || error}`, accepted: false, timings: _noTimings() });
     }
 
+    // WP-0: the connect phase is the socket's own 'open'. Nothing is SENT here (see the dial-order
+    // note below) — the listener exists only to stamp connectMs, and an implementation that never
+    // fires it leaves the phase at -1 rather than inventing a number.
+    socket.on('open', () => { if (openedAt < 0) openedAt = Date.now(); });
+
+    // WP-3 (D-4/D-6): phase B. Its expiry ends the WAIT only — the box already owns the create and
+    // runs it to completion, so nothing is sent to the box here (D-6).
+    const armPhaseB = () => {
+      timer = setTimeoutFn(() => {
+        try { socket.terminate(); } catch { /* expected: the socket is already gone */ }
+        finish({ ok: false, code: MACHINE_CREATE_UNCONFIRMED, error: 'accepted_then_timeout' });
+      }, ceilingMs);
+      if (timer && typeof timer.unref === 'function') timer.unref();
+    };
+
+    // Phase A (D-3): unchanged 15 s from the dial to the box's acceptance or its final reply.
     timer = setTimeoutFn(() => {
       try { socket.terminate(); } catch { /* expected: the socket is already gone */ }
       finish({ ok: false, code: 'machine_unreachable', error: 'timeout' });
@@ -453,6 +613,9 @@ function sendRemoteCreate({ machineUrl, payload, deps }) {
 
     // No create on 'open': the box has not said hello yet, so its protocol gate is not satisfied.
     socket.on('message', (raw) => {
+      // D-6: once this dial is settled nothing may cross to the box again — a frame arriving after
+      // the phase-B timeout (a late hello, the box's eventual `created`) is dropped, never answered.
+      if (settled) return;
       let frame = null;
       try {
         frame = JSON.parse(raw.toString());
@@ -460,21 +623,52 @@ function sendRemoteCreate({ machineUrl, payload, deps }) {
         return; // expected: a non-JSON frame (the box's binary/other lanes) is not the reply
       }
       if (!frame || typeof frame !== 'object') return;
+      // WP-0: a REPLY is any frame that settles this dial (created / box error / the box's protocol
+      // or auth verdict on the create). Timeout, socket error and close-before-reply are NOT replies,
+      // so replyMs stays -1 there.
+      const markReply = () => { if (replyAt < 0) replyAt = Date.now(); };
+      if (frame.type === 'create-accepted') {
+        // WP-3 (D-3): the box admitted the create and is starting it. Only THIS create's id counts
+        // (any other id belongs to another client on the same box endpoint) and only the first one.
+        // Phase A is cleared, the caller is told once, and phase B starts.
+        if (!createId || _string(frame.id, 200) !== createId) return;
+        if (accepted) return;
+        accepted = true;
+        acceptedAt = Date.now();
+        if (timer) clearTimeoutFn(timer);
+        timer = null;
+        if (acceptedHook) {
+          try {
+            acceptedHook(frame);
+          } catch (error) {
+            // REPORT: the caller's own bookkeeping (mirror registration + browser relay) must never
+            // break a live dial — the box is starting the session either way (D-6).
+            console.warn(`[remote-create] onAccepted failed: ${_string(error && error.message, 200) || 'unknown error'}`);
+          }
+        }
+        armPhaseB();
+        return;
+      }
       if (frame.type === 'hello') {
         // The box gates every terminal-protocol message (including 'create') behind a compatible
         // client-info, so the hub identifies itself with the epoch the box just advertised — the
         // same handshake a browser does. Both frames go out in this order on this one socket.
+        if (helloAt < 0) helloAt = Date.now();
         try {
           socket.send(JSON.stringify(peerClientInfoFrame(frame)));
         } catch { /* expected: the socket died between hello and client-info */ }
         sendCreate();
         return;
       }
-      if (frame.type === 'created') return finish({ ok: true, frame });
+      if (frame.type === 'created') {
+        markReply();
+        return finish({ ok: true, frame });
+      }
       if (frame.type === 'terminal-protocol-incompatible') {
         // The box refused the frame on protocol grounds. Fail now with the reason instead of
         // waiting out the timeout for a reply that will never come (this is the frame that made a
         // mis-ordered dial look like an unreachable box).
+        markReply();
         return finish({
           ok: false,
           code: 'machine_unreachable',
@@ -492,11 +686,13 @@ function sendRemoteCreate({ machineUrl, payload, deps }) {
         // non-fatal — treating every auth-error as fatal would break every forward.
         if (_string(frame.messageType, 40) === 'create') {
           const code = _string(frame.code, 80) || 'machine_unreachable';
+          markReply();
           return finish({ ok: false, code, error: `box_refused_create:${code}` });
         }
         return;
       }
       if (frame.type === 'error') {
+        markReply();
         return finish({
           ok: false,
           code: _string(frame.code, 80) || 'machine_unreachable',
@@ -507,14 +703,183 @@ function sendRemoteCreate({ machineUrl, payload, deps }) {
       // handshake or the box's ambient traffic on this lane and is not a reply to the create.
     });
     socket.on('error', (error) => {
+      // D-5: an error AFTER acceptance is not "unreachable" — the box already claimed the create and
+      // is still starting it, so the hub reports it as unconfirmed and keeps the session.
+      if (accepted) return finish({ ok: false, code: MACHINE_CREATE_UNCONFIRMED, error: 'accepted_then_socket_error' });
       finish({ ok: false, code: 'machine_unreachable', error: _string(error?.message || error, 300) });
     });
     socket.on('close', () => {
+      if (accepted) return finish({ ok: false, code: MACHINE_CREATE_UNCONFIRMED, error: 'accepted_then_closed' });
       finish({ ok: false, code: 'machine_unreachable', error: 'closed_before_reply' });
     });
   });
 }
 
+// ---------------------------------------------------------------------------------------------
+// WP-3 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-4/D-6, §6.5) — the hub's agent-skill
+// push at forwarded create.
+//
+// The push happens BEFORE the dial and can never change its outcome (D-6): the box's container gets
+// the hub's skills and plugins, and a hub that cannot deliver them still forwards the create exactly
+// as it did before this work package existed.
+// ---------------------------------------------------------------------------------------------
+
+/** D-9: the box os values a bundle can be built for; anything else means "do not guess". */
+const AGENT_BUNDLE_PLATFORMS = Object.freeze(['darwin', 'linux', 'win32']);
+
+/** D-6/D-9: the create-time push failures this lane names itself (push.js owns the transport ones). */
+const BUNDLE_PLATFORM_UNKNOWN = 'agent_bundle_platform_unknown';
+const BUNDLE_NO_CREDENTIAL = 'agent_bundle_push_no_credential';
+const BUNDLE_PUSH_NETWORK = 'agent_bundle_push_network';
+
+/**
+ * D-9: the platform to build for = the box's `os` from the registry's cached manifest host block.
+ * Unknown, unreadable or unlisted reads null — the caller then SKIPS the push rather than guessing a
+ * platform (a wrong guess would ship the box a skill its own CLI cannot load).
+ */
+function agentBundlePlatformFor(machineId, deps = {}) {
+  const d = _deps(deps);
+  const registry = d.registry;
+  if (!registry || typeof registry.manifestHostFor !== 'function') return null;
+  let host = null;
+  try {
+    host = registry.manifestHostFor(_string(machineId, 160));
+  } catch {
+    return null; // expected: a registry read fault means "unknown platform", never a failed create
+  }
+  const platform = _string(host && host.os, 40).toLowerCase();
+  return AGENT_BUNDLE_PLATFORMS.includes(platform) ? platform : null;
+}
+
+/**
+ * The headers the push is authenticated with: exactly the choice `preparePeerDial` makes for the
+ * dial of the same target (an injected `authHeaders` builder wins; otherwise
+ * `buildPeerControlHeaders(env, {instanceId})`), so the push and the dial can never drift onto
+ * different credentials. `null` means no credential is configured — a configuration error the caller
+ * reports as `agent_bundle_push_no_credential` (the dial reports its own `peer_credential_missing`).
+ */
+function bundlePeerHeadersFor(deps = {}, instanceId) {
+  const d = _deps(deps);
+  if (typeof d.authHeaders === 'function') {
+    try {
+      const headers = d.authHeaders();
+      return headers && typeof headers === 'object' ? headers : null;
+    } catch {
+      return null; // expected: a credential-builder fault is a missing credential, not a throw
+    }
+  }
+  return buildPeerControlHeaders(d.env || process.env, { instanceId: _string(instanceId, 160) });
+}
+
+/** The sync bookkeeping every outcome shares: the machine row's `skills` block, then the diagnostic. */
+function _recordPushOutcome(d, instanceId, result, payload, platform) {
+  const registry = d.registry;
+  if (registry && typeof registry.recordAgentBundlePush === 'function') {
+    try {
+      registry.recordAgentBundlePush(instanceId, result);
+    } catch { /* expected: a registry write fault must never fail a create (D-6) */ }
+  }
+  if (result.ok !== true && typeof d.recordSessionDiagnostic === 'function') {
+    try {
+      const details = { code: _string(result.code, 80), machine: instanceId, platform: platform || '' };
+      // WP-6 D-13: the push now says WHICH phase cost the wait and, when the push ran on without the
+      // caller (D-11), that it is still going. Both are present only when the push reported them.
+      const phase = _string(result.phase, 40);
+      if (phase) details.phase = phase;
+      if (result.continuing === true) details.continuing = true;
+      if (result.timings && typeof result.timings === 'object') details.timings = result.timings;
+      // The session id here is the FORWARDED create's id (the hub has no local session row for it —
+      // OQ-4); when the client supplied none, the machine id is the correlation we do have.
+      d.recordSessionDiagnostic(_string(payload && payload.id, 200) || instanceId, 'agent-bundle-push-failed', details);
+    } catch { /* expected: diagnostic bookkeeping must never fail a create (D-6) */ }
+  }
+  return result;
+}
+
+/**
+ * Push this hub's bundle for `row` before the dial, or `null` when there is nothing to push.
+ *
+ * SYNCHRONOUS DECISION, async only when a push actually runs: a shell create, an unknown platform and
+ * a missing credential all resolve here without yielding to the event loop, so the create's critical
+ * path has no avoidable interleaving point (and a caller driving this seam in a test can still rely on
+ * "nothing has been dialled yet" being observable synchronously).
+ *
+ * Always resolves (never throws) on the async path: a failure is recorded on the machine row and
+ * emitted as the `agent-bundle-push-failed` session diagnostic, and the caller forwards the create
+ * regardless (D-6). Only claude/codex creates push (`agentKey`), and `excludePlugins` comes from a
+ * dep so WP-8 can wire the per-machine list without touching this call site.
+ *
+ * @returns {null|Promise<object>} the push result, or null when nothing was pushed
+ */
+function pushAgentBundleForCreate(d, row, payload, agentKey) {
+  if (!agentKey) return null; // a plain shell create runs no coding CLI, so it ships no skills
+  const instanceId = _string(row && row.instanceId, 160);
+  const platform = agentBundlePlatformFor(instanceId, d);
+  const headers = platform ? bundlePeerHeadersFor(d, instanceId) : null;
+  if (!platform) {
+    // D-9: guessing a platform would ship the box a skill its own CLI cannot load. Report the skip.
+    _recordPushOutcome(d, instanceId, {
+      ok: false,
+      code: BUNDLE_PLATFORM_UNKNOWN,
+      detail: 'the machine has never reported a platform this hub can build a bundle for',
+    }, payload, '');
+    return null;
+  }
+  if (!headers) {
+    _recordPushOutcome(d, instanceId, {
+      ok: false,
+      code: BUNDLE_NO_CREDENTIAL,
+      detail: 'no peer credential is configured for this machine',
+    }, payload, platform);
+    return null;
+  }
+  const machine = { instanceId, url: _string(row.url, 1000), displayName: _string(row.displayName, 200) };
+  return (async () => {
+    // WP-8: the production exclusion dep loads its store with async fs (never a sync read on the
+    // create's main thread) and so answers a promise; a dep that answers a plain list is used as-is,
+    // without a yield, so the push still starts in the same synchronous turn as before.
+    let excludePlugins = [];
+    if (typeof d.agentBundleExcludePlugins === 'function') {
+      try {
+        const answer = d.agentBundleExcludePlugins(instanceId);
+        excludePlugins = (answer && typeof answer.then === 'function' ? await answer : answer) || [];
+      } catch {
+        excludePlugins = []; // expected: an unreadable exclude list ships every plugin, never nothing
+      }
+    }
+    const options = {
+      fetchImpl: d.fetchImpl,
+      peerHeaders: headers,
+      targetPlatform: platform,
+      excludePlugins,
+      // WP-6 D-11: the push outlives this create's wait. When it settles late — after the create has
+      // already been forwarded — its result still has to reach the row and the diagnostic, exactly
+      // once (push.js calls this only for a call that timed out AND started the push). The create
+      // itself is NEVER held for it: `_recordPushOutcome` cannot reject and the frame goes out as
+      // soon as the budgeted call resolves.
+      onLateResult: (late) => _recordPushOutcome(
+        d,
+        instanceId,
+        (late && typeof late === 'object') ? late : { ok: false, code: BUNDLE_PUSH_NETWORK, detail: 'the push returned no result' },
+        payload,
+        platform,
+      ),
+    };
+    let result;
+    try {
+      result = await d.pushAgentBundle(machine, options);
+    } catch (error) {
+      // REPORT: push.js resolves its own failures, so a THROW here is a bug in the seam — it must
+      // still not touch the create.
+      result = { ok: false, code: BUNDLE_PUSH_NETWORK, detail: _string(error && error.message, 200) || 'push failed' };
+    }
+    if (!result || typeof result !== 'object') {
+      result = { ok: false, code: BUNDLE_PUSH_NETWORK, detail: 'the push returned no result' };
+    }
+    return _recordPushOutcome(d, instanceId, result, payload, platform);
+  })();
+}
+
 function _sendFrame(ctx, frame) {
   try {
     if (ctx && ctx.ws && ctx.ws.readyState === 1 && typeof ctx.send === 'function') {
@@ -526,81 +891,242 @@ function _sendFrame(ctx, frame) {
   }
 }
 
-function _fail(ctx, code, detail) {
-  _sendFrame(ctx, {
+/**
+ * Refuse a forwarded create on the requesting browser socket (one frame, one result).
+ *
+ * WP-0 (§6.5): `machine`/`machineName` ride every refusal so it is VISIBLE. Both clients gate the
+ * machine-error toast on `/^machine_/.test(code) || !!msg.machine` (public/index.html:4467,
+ * public/m/app.js:5638), so a hub code such as `peer_credential_missing`, or any box code relayed
+ * from a forwarded create (`rate_limited`, `create_in_progress`, …), was console-only before this.
+ * `machine` is the requested instance id as a STRING — the desktop dedupes its toast key on
+ * `String(msg.machine)`. Same shape as `forwardLifecycleRequest`'s 503 body
+ * (lib/remote-machine-catalog.js). `code`/`message` are untouched.
+ *
+ * WP-3 (§6.3 S-3): the optional 6th `id` is the create's own idempotency key (D-1). It is added
+ * AFTER the machine fields and only when non-empty, so the client can match the refusal to the
+ * pending create it is holding (D-7) and an id-less caller's frame keeps its exact key set.
+ */
+function _fail(ctx, code, detail, machineId, machineName, id = '') {
+  const frame = {
     type: 'error',
     code: code || 'machine_unreachable',
     message: detail || 'The machine could not be reached.',
-  });
+    machine: _string(machineId, 200),
+    machineName: _string(machineName, 200),
+  };
+  const refusalId = _string(id, 200);
+  if (refusalId) frame.id = refusalId;
+  _sendFrame(ctx, frame);
   return { ok: false, code: code || 'machine_unreachable', error: detail || '' };
 }
 
+/**
+ * WP-0 (D-8, §6.3): the hub's ONE line per forwarded create. Keys are a FIXED set in a fixed order,
+ * and `-` is the "no value" token (`<n|-1>` for the two durations, where `-1` means the push/dial
+ * phase was never reached). The line is built for humans and greps, never parsed by code — the
+ * machine-readable form of the same facts is the frame's own `timings` and the `_fail` code.
+ *
+ * @param {{id: string, machine: string, agent: string,
+ *          outcome: 'created'|'failed'|'unconfirmed'|'refused',
+ *          code: string, pushMs: number, pushCode: string, timings: object, totalMs: number}} f
+ */
+function formatRemoteCreateLine(f) {
+  const fields = f && typeof f === 'object' ? f : {};
+  const t = fields.timings && typeof fields.timings === 'object' ? fields.timings : _noTimings();
+  const ms = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.round(n) : -1;
+  };
+  const token = (value, max) => _string(value, max) || '-';
+  return `[remote-create] id=${_string(fields.id, 200).slice(0, 8) || '-'}`
+    + ` machine=${token(fields.machine, 160)} agent=${token(fields.agent, 40)}`
+    + ` outcome=${token(fields.outcome, 40)} code=${token(fields.code, 80)}`
+    + ` pushMs=${ms(fields.pushMs)} pushCode=${token(fields.pushCode, 80)}`
+    + ` connectMs=${ms(t.connectMs)} helloMs=${ms(t.helloMs)} acceptedMs=${ms(t.acceptedMs)} replyMs=${ms(t.replyMs)}`
+    + ` totalMs=${ms(fields.totalMs)}`;
+}
+
 /**
  * Forward an already-classified remote create (S-1). On success the box's own `created` frame is
  * re-emitted to the requesting browser socket with `machine`/`machineName` added (AC-2a) and the
  * mirror registration is recorded; on failure the caller's socket gets exactly one typed `error`
  * frame and NOTHING is created locally (AC-2c).
+ *
+ * WP-0 (D-8): every exit writes exactly ONE `[remote-create]` line (see formatRemoteCreateLine).
+ * `outcome` is `created` on the box's `created`, `refused` for the hub-side refusals taken BEFORE the
+ * dial (loop guard, the machine-row verdicts, the dsh/sign-in verdicts, a missing peer credential),
+ * `failed` for everything after the dial starts (dial failures, timeouts, box error frames) and
+ * `unconfirmed` for an ACCEPTED create the hub stopped waiting for (WP-3 D-5 — the box still has it).
  */
 async function forwardRemoteCreate(ctx, msg, deps = {}) {
   const d = _deps(deps);
+  const startedAt = Date.now();
   const machineId = _string(msg && msg.machine, 160);
+  // WP-3 (§6.3 S-3): the create's own idempotency key as the client minted it (D-1). It rides every
+  // refusal frame (`_fail`'s 6th argument) so the client can match a failure to its pending create.
+  const createId = _string(msg && msg.id, 200);
+  // WP-0 bookkeeping, shared by every exit below. `_report` is the ONLY writer of the line, so a new
+  // return path cannot silently skip it: route the return through `_refuse`/`_report`.
+  let logMachine = machineId;
+  let logId = createId;
+  let pushMs = -1;
+  let pushCode = '-';
+  let dialTimings = null;
+  const _report = (result, outcome) => {
+    console.log(formatRemoteCreateLine({
+      id: logId,
+      machine: logMachine,
+      agent: remoteCreateAgentKey(msg) || '-',
+      outcome,
+      code: _string(result && result.code, 80),
+      pushMs,
+      pushCode,
+      timings: dialTimings,
+      totalMs: Date.now() - startedAt,
+    }));
+    return result;
+  };
+  /** A hub-side refusal taken before any dial — never counted as a dial failure. */
+  const _refuse = (result) => _report(result, 'refused');
   // P-3 one-hop guard. This function is reached ONLY when the create names a machine that is not
   // this instance (lib/ws/terminal-attach.js checks isRemoteMachineTarget first), so a request that
   // already carries the hop header is by definition a request to forward a forwarded create — the
   // A→B→C chain (and the A→B→A loop) P-3 forbids. Nothing is dialled and nothing is created.
   const forwardedBy = forwardedByOf(ctx);
   if (forwardedBy) {
-    return _fail(ctx, MACHINE_FORWARD_LOOP, `This create was already forwarded by ${forwardedBy}; a forwarded request is never forwarded again`);
+    return _refuse(_fail(ctx, MACHINE_FORWARD_LOOP, `This create was already forwarded by ${forwardedBy}; a forwarded request is never forwarded again`, machineId, '', createId));
   }
   const row = _findMachine(machineId, d);
-  if (!row) return _fail(ctx, 'machine_unreachable', `machine ${machineId} is not registered on this hub`);
-  if (!row.enabled) return _fail(ctx, 'machine_unreachable', `machine ${machineId} is disabled`);
-  if (!_string(row.url, 1000)) return _fail(ctx, 'machine_unreachable', `machine ${machineId} has no url`);
+  if (!row) return _refuse(_fail(ctx, 'machine_unreachable', `machine ${machineId} is not registered on this hub`, machineId, '', createId));
+  // The row is authoritative for the line's `machine` once it exists (mirrors `_fail`'s frame field).
+  logMachine = _string(row.instanceId, 160) || logMachine;
+  if (!row.enabled) return _refuse(_fail(ctx, 'machine_unreachable', `machine ${machineId} is disabled`, machineId, row.displayName, createId));
+  if (!_string(row.url, 1000)) return _refuse(_fail(ctx, 'machine_unreachable', `machine ${machineId} has no url`, machineId, row.displayName, createId));
   if (_string(row.health, 40) === 'unreachable') {
-    return _fail(ctx, 'machine_unreachable', `machine ${machineId} is unreachable`);
+    return _refuse(_fail(ctx, 'machine_unreachable', `machine ${machineId} is unreachable`, machineId, row.displayName, createId));
   }
 
   const payload = filterRemoteCreateForward(msg);
+  // WP-13 (D-15): the WP-2 `dsh_remote_pending` refusal is GONE — a forwarded dsh create runs the
+  // same handleCreate on the box, which resolves its own dsh binary, proxy port and route. The ONE
+  // remaining dsh gate is the box's own installation verdict below: CTM never installs dsh on a box
+  // (843 MB), so a hub that holds "this box has no dsh" refuses rather than dialling into a box-side
+  // PATH failure. A box with no verdict at all is dialled exactly like any other agent (P3).
+  const agentKey = remoteCreateAgentKey(payload);
+  if (agentKey === DSH_AGENT_KEY) {
+    const notInstalled = _boxAgentMissing(d, row, DSH_AGENT_KEY);
+    if (notInstalled) {
+      return _refuse(_fail(ctx, 'machine_agent_not_installed', `DeepSeek Harness is not installed on ${_string(row.displayName, 200) || row.instanceId}`, machineId, row.displayName, createId));
+    }
+  }
   // WP-3: the box judges a create only by its manifest probe, so a box that is REACHABLE but has no
   // signed-in Claude/Codex CLI would happily spawn a session that opens at a login prompt. Refuse at
   // the hub instead, naming the box and the URL that fixes it. 'unknown' (never probed, unreachable
   // probe, unreadable body) and 'signed_in' both proceed: only an explicit `signedIn:false` refuses.
-  const agentKey = remoteCreateAgentKey(payload);
-  const auth = agentKey && d.registry && typeof d.registry.agentAuthFor === 'function'
+  // 'dsh' is skipped by construction: it has no CTM sign-in (S-88), so no verdict is consulted —
+  // `agentAuthFor`'s map is `{claude, codex}` and reading `auth['dsh']` would be meaningless.
+  const auth = agentKey && agentKey !== DSH_AGENT_KEY
+    && d.registry && typeof d.registry.agentAuthFor === 'function'
     ? d.registry.agentAuthFor(row.instanceId)
     : null;
   if (auth && auth[agentKey] === 'signed_out') {
     const label = agentKey === 'codex' ? 'Codex' : 'Claude Code';
-    return _fail(ctx, 'machine_agent_signed_out', `${label} is not signed in on ${_string(row.displayName, 200) || row.instanceId} — open ${row.url} → AI Providers → Coding Agents → Sign in`);
+    return _refuse(_fail(ctx, 'machine_agent_signed_out', `${label} is not signed in on ${_string(row.displayName, 200) || row.instanceId} — open ${row.url} → AI Providers → Coding Agents → Sign in`, machineId, row.displayName, createId));
+  }
+  // WP-3 (D-4/D-6, §6.5): hand the box this hub's skills/plugins BEFORE the dial. A failure here is
+  // recorded on the machine row and emitted as a diagnostic, and the forward below runs either way —
+  // skills are a convenience, and NOTHING about this call may change the create's outcome (AC-3c:
+  // the forwarded frame is untouched by construction; the push never touches `payload`). The decision
+  // is synchronous, so a create with nothing to push (a shell create, an unknown platform, no
+  // credential) reaches the dial without yielding.
+  const bundlePush = pushAgentBundleForCreate(d, row, payload, agentKey);
+  if (bundlePush) {
+    // D-9/OQ-3: the push wait (≤10 s) used to be invisible; it is now pushMs/pushCode on the line.
+    // pushMs prefers push.js's own D-13 `timings.totalMs` (the push's account of itself) and falls
+    // back to the caller's measured wait, so a push that RAN is never reported as `-1`.
+    const pushStartedAt = Date.now();
+    const pushResult = await bundlePush;
+    pushMs = _pushMs(pushResult, Date.now() - pushStartedAt);
+    pushCode = pushResult && pushResult.ok === true ? 'ok' : _string(pushResult && pushResult.code, 80) || '-';
   }
   // The machine's DISPLAY name rides the dial deps so a credential-less refusal can name the box
   // the operator has to configure (D-2), not just "the machine".
   const result = await sendRemoteCreate({
     machineUrl: row.url,
     payload,
+    // WP-3 (§6.3 D-3): the moment the box says it ADMITTED the create (phase A ends here, D-4 arms
+    // phase B). The mirror registration is recorded and the frame is relayed to the browser with the
+    // same machine/machineName shape as the `created` relay below — so the client's pending create
+    // turns into "starting on ‹machine›" instead of waiting out the whole box-side create.
+    onAccepted: (frame) => {
+      recordMirrorSession(frame.id, row);
+      _sendFrame(ctx, {
+        ...frame,
+        machine: _string(row.instanceId, 160),
+        machineName: _string(row.displayName, 200),
+      });
+    },
     // P-8: the TARGET's instanceId rides the dial deps so the credential is chosen per machine —
     // a legacy env-token box that never joined the pool is dialled with the env bearer, not with a
     // pool secret it would 401.
     deps: { ...d, machineName: _string(row.displayName, 200), instanceId: _string(row.instanceId, 160) },
   });
-  if (!result.ok) return _fail(ctx, result.code, result.error);
+  dialTimings = result.timings || null;
+  // The box's own refusal (`rate_limited`, `create_in_progress`, `session_exists`, …) and every
+  // local dial failure reach the browser HERE: `_fail` re-emits `code`/`message` verbatim and adds
+  // the machine fields (WP-0 §6.5), so neither a hub code nor a relayed box code is console-only.
+  // A missing peer credential is the one dial-path code that is NOT a dial failure: nothing was
+  // dialled, so it reads as a hub refusal (D-2) exactly like the refusals above.
+  if (!result.ok) {
+    const failure = _fail(ctx, result.code, result.error, machineId, row.displayName, createId);
+    if (result.code === PEER_CREDENTIAL_MISSING) return _refuse(failure);
+    // WP-3 (D-5): the box ACCEPTED this create (hence the code) and then went quiet — a warning, not
+    // a failure. The box runs the create to completion (D-6), so the catalog refresh runs here too,
+    // exactly as it does on the success path: the session must appear the moment the box commits it.
+    if (result.code === MACHINE_CREATE_UNCONFIRMED) {
+      _refreshCatalog(d, row.instanceId);
+      return _report(failure, 'unconfirmed');
+    }
+    return _report(failure, 'failed');
+  }
 
   const frame = result.frame || {};
   const sessionId = _string(frame.id || payload.id, 200);
-  if (sessionId) recordMirrorSession(sessionId, row);
+  if (sessionId) {
+    logId = sessionId;
+    recordMirrorSession(sessionId, row);
+  }
   _sendFrame(ctx, {
     ...frame,
     machine: _string(row.instanceId, 160),
     machineName: _string(row.displayName, 200),
   });
-  // WP-6 §8: "right after a forwarded create" is a catalog refresh trigger — the new session must
-  // appear in the hub's merged list at once, not on the next ~15 s probe sweep. Fire-and-forget:
-  // the in-memory registration above already makes the relay work, so a catalog fault is a stale
-  // list, never a failed create.
-  if (typeof d.refreshCatalog === 'function') {
-    try { d.refreshCatalog(_string(row.instanceId, 160)); } catch { /* expected: a catalog fault never fails a create */ }
-  }
-  return { ok: true, sessionId, machineInstanceId: _string(row.instanceId, 160) };
+  _refreshCatalog(d, row.instanceId);
+  return _report({ ok: true, sessionId, machineInstanceId: _string(row.instanceId, 160) }, 'created');
+}
+
+/**
+ * WP-6 §8 / WP-3 (D-5): the fire-and-forget catalog refresh. "right after a forwarded create" is a
+ * catalog refresh trigger — the new session must appear in the hub's merged list at once, not on the
+ * next ~15 s probe sweep. Fire-and-forget: the in-memory mirror registration already makes the relay
+ * work, so a catalog fault is a stale list, never a failed create. Both the `created` outcome and the
+ * `unconfirmed` one (D-5) take it — the box owns the create in either case.
+ */
+function _refreshCatalog(d, instanceId) {
+  if (typeof d.refreshCatalog !== 'function') return;
+  try { d.refreshCatalog(_string(instanceId, 160)); } catch { /* expected: a catalog fault never fails a create */ }
+}
+
+/**
+ * WP-0 (D-9): the push's own account of how long it cost (D-13 `timings.totalMs`) when it has one,
+ * else the caller's measured wait. Never a negative number: a push that RAN is `>= 0`, and only a
+ * push that never ran is `-1` (which the call site simply does not call this for).
+ */
+function _pushMs(result, measuredMs) {
+  const total = Number(result && result.timings && result.timings.totalMs);
+  if (Number.isFinite(total) && total >= 0) return Math.round(total);
+  const measured = Number(measuredMs);
+  return Number.isFinite(measured) && measured >= 0 ? Math.round(measured) : -1;
 }
 
 /** Record (or refresh) the in-memory mirror registration for a session this hub created on a box. */
@@ -665,11 +1191,25 @@ function _resetMirrorSessionsForTests() {
 module.exports = {
   REMOTE_CREATE_FORWARD_ALLOWLIST,
   DEFAULT_TIMEOUT_MS,
+  // WP-3 (§6.3 D-3/D-4/D-5): phase B's ceiling, the code an accepted-but-silent box reports, and the
+  // shared dial prologue below. The ceiling's coverage of every box-side bound is enforced by
+  // tests/remote-create-ceiling-covers-box.test.js.
+  CREATE_ACCEPTED_CEILING_MS,
+  MACHINE_CREATE_UNCONFIRMED,
   configure,
   filterRemoteCreateForward,
   remoteCreateAgentKey,
   isRemoteMachineTarget,
   forwardRemoteCreate,
+  // WP-0 (D-8, §6.3): the hub's one-line-per-create formatter — exported so the line's fixed key
+  // set is assertable without driving a whole dial through a console capture.
+  formatRemoteCreateLine,
+  // WP-3 (docs/remote-agent-skills-bundles-2026-10-25.html §6.5): the platform reader, the peer
+  // header choice the push shares with the dial, and the push call site itself.
+  AGENT_BUNDLE_PLATFORMS,
+  agentBundlePlatformFor,
+  bundlePeerHeadersFor,
+  pushAgentBundleForCreate,
   sendRemoteCreate,
   buildPeerControlHeaders,
   // WP-1 (D-2/D-4): the missing-credential code, its operator copy, and the hub-local state.