create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/api/machines.js

@@ -28,8 +28,17 @@
 // the /api/setup/* rules), and a route with no rule is 403 auth_rule_missing by design — so the
 // rule rows and these registrations must land together.
 
+const os = require('os');
 const { registerApiRoutes } = require('../api-router');
 const machinePairing = require('../machine-pairing');
+// WP-8 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-12/D-13, §6.5): the hub end of the
+// one-skill exchange — import a box skill into this hub, retire the box copy, and per-machine plugin
+// exclusions. Policy is in the lib; this module owns the dial and the request body.
+const skillTransfer = require('../agent-bundle/skill-transfer');
+// WP-1 (docs/remote-box-model-access-2026-10-26.html §6.1, §5.3 D-2/D-3/D-9): the box's own
+// reachability answer — "which of the routes configured on THIS machine can this machine reach".
+// A leaf module (http/https only), so it adds no cycle to this one.
+const modelAvailability = require('../model-availability');
 
 // §6.3: the identity probe is a reachability check, not a data fetch — it must not hold a request
 // open on a box that is merely slow to answer.
@@ -48,8 +57,43 @@ function configure({
   sendJsonResponse,
   ready = null,
   fetchImpl = null,
+  // WP-8: the hub's own data dir (import backups + the exclusion file) and the hub user's home (the
+  // installed skill root). Both injected, so a route test never reads the real hub home/data dir.
+  dataDir = null,
+  hubHomeDir = null,
+  hubEnv = null,
+  now = null,
+  // WP-1 (§6.1): the availability handler's three seams. All optional — production reads the
+  // loopback Wall-E client, the coding-agent-auth probe and the real clock.
+  walleClient = null,
+  probe = null,
+  probeLoginState = null,
+  delegateDefaults = null,
 } = {}) {
-  _deps = { db, registry, pool, readJsonRequestBody, sendJsonResponse, ready, fetchImpl };
+  _deps = {
+    db, registry, pool, readJsonRequestBody, sendJsonResponse, ready, fetchImpl, dataDir, hubHomeDir, hubEnv, now,
+    walleClient, probe, probeLoginState, delegateDefaults,
+  };
+}
+
+/** The hub data dir (the exclusion store + import backups live under it). */
+function _dataDir() {
+  if (_deps && _deps.dataDir) return _deps.dataDir;
+  return require('../data-dir').getDataDir();
+}
+
+/** The hub user's home and env — the two inputs the installed skill root is resolved from. */
+function _hubHomeDir() {
+  return (_deps && _deps.hubHomeDir) || os.homedir();
+}
+
+function _hubEnv() {
+  return (_deps && _deps.hubEnv) || process.env;
+}
+
+/** An injected clock, so a test controls the retire/backup directory stamps. */
+function _now() {
+  return typeof (_deps && _deps.now) === 'function' ? Number(_deps.now()) || 0 : Date.now();
 }
 
 /**
@@ -202,7 +246,22 @@ async function _postToTarget(target, pathname, body, headers) {
 
 async function handleMachinesList(req, res) {
   const registry = _deps && _deps.registry;
-  const { machines, hubNetworkSuspect } = registry.listMachines({ db: _deps && _deps.db });
+  // WP-8 (§6.5): the row's `skills` block also carries this machine's plugin exclusions. The provider
+  // is injected here — the registry module never reads a data dir — and it reads the one hub-side file
+  // (cached in memory by lib/agent-bundle/skill-transfer.js).
+  try {
+    await skillTransfer.loadExcludePlugins(_dataDir());
+  } catch {
+    /* expected: an unreadable exclusion file is "nothing excluded", never a failed list */
+  }
+  const excludePluginsFor = (instanceId) => {
+    try {
+      return skillTransfer.excludePluginsFor(_dataDir(), instanceId);
+    } catch {
+      return []; // expected: an unreadable exclusion file is "nothing excluded", never a failed list
+    }
+  };
+  const { machines, hubNetworkSuspect } = registry.listMachines({ db: _deps && _deps.db, excludePluginsFor });
   // WP-1 (D-4) / P-8: which credential this hub will actually dial THIS row with — computed per row
   // from the row's instanceId, because a pool hub sends the pool secret only to pool members and the
   // env bearer to a legacy box that never joined (see peerCredentialState). The token itself is
@@ -211,6 +270,15 @@ async function handleMachinesList(req, res) {
   // WP-3: the box's coding-CLI sign-in truth the probe sweep last read. Guarded by typeof so a test
   // registry that only carries listMachines still serves rows (they just read 'unknown').
   const agentAuthFor = registry && typeof registry.agentAuthFor === 'function' ? registry.agentAuthFor : null;
+  // WP-13b (D-15): the box's own available-agents presence (`{ dsh: { available } }`), the read the
+  // probe sweep keeps. Guarded the same way: a test registry that only carries listMachines serves
+  // rows whose presence is null ("unknown"), never a fabricated verdict.
+  const agentAvailabilityFor = registry && typeof registry.agentAvailabilityFor === 'function' ? registry.agentAvailabilityFor : null;
+  // WP-0 (docs/fleet-auto-update-pooled-machines-2026-10-26.html §6, S-3): the hub's own fleet
+  // target — its local refs/heads/main (D-1: local main IS the fleet target). Memoized in
+  // lib/fleet-update.js, so a list of N boxes costs one `git` read every 15 s, and a hub without a
+  // readable main answers '' (never an error page for an informational field).
+  const fleetTarget = await require('../fleet-update').readHubTarget();
   _send(res, 200, {
     machines: machines.map((machine) => ({
       instanceId: machine.instanceId,
@@ -220,6 +288,9 @@ async function handleMachinesList(req, res) {
       enabled: machine.enabled,
       health: machine.health,
       healthDetail: machine.healthDetail,
+      // WP-3 rev 3 (docs/off-lan-hub-to-box-access-2026-10-31.html §13.6 D-17): why an unreachable
+      // box cannot be dialled from here ('no_away_path' / 'away_path_down'), or null.
+      awayReason: machine.awayReason || null,
       lastSeenAt: machine.lastSeenAt,
       pickerState: machine.pickerState,
       visible: machine.visible,
@@ -238,11 +309,38 @@ async function handleMachinesList(req, res) {
       os: machine.os || '',
       arch: machine.arch || '',
       hostname: machine.hostname || '',
+      // WP-0 (S-3): the build the box published in its own manifest (null = this hub has never read
+      // one). `build.sha` is the version truth the Machines card compares against `fleetTarget`.
+      build: machine.build || null,
+      // WP-2 (docs/fleet-auto-update-pooled-machines-2026-10-26.html §8 WP-2, S-3): this box's last
+      // fleet decision — `{ target, reason, behind, inFlight, lastVerdict }`, or null before the
+      // reconciler's first pass (never a fabricated "current"). A pure read of the last plan + the
+      // cached hub state: no I/O and no git, because this is evaluated once per row per list.
+      fleet: require('../fleet-hub').fleetRowFor(machine.instanceId),
       peerCredential: peerCredentialFor(process.env, { instanceId: machine.instanceId }),
       agents: (agentAuthFor ? agentAuthFor.call(registry, machine.instanceId) : null)
         || { claude: 'unknown', codex: 'unknown', checkedAt: 0 },
+      // WP-13b (D-15): whether THIS box has the DeepSeek Harness, as the hub last read it from the
+      // box's own available-agents answer. `{ dsh: true }` = the box has it, `{ dsh: false }` = it
+      // said it does not, `{ dsh: null }` = this hub has no verdict (P3 "Unknown != Dead"): the
+      // New Session card disables the dsh card only on an explicit false.
+      agentPresence: (() => {
+        const verdict = agentAvailabilityFor ? agentAvailabilityFor.call(registry, machine.instanceId) : null;
+        const available = verdict && verdict.dsh ? verdict.dsh.available : undefined;
+        return { dsh: typeof available === 'boolean' ? available : null };
+      })(),
+      // WP-3 (remote agent skills §6.5): the last bundle push to this box — sentTreeHash/pushError —
+      // plus the WP-7 classification of its own skills and the WP-8 plugin exclusions.
+      skills: machine.skills || null,
+      // WP-1 (remote box model access §6.2): the box's OWN model-availability block, read on the
+      // existing probe tick — null = never read, or a box older than WP-1 (404). Exposed exactly
+      // like `skills`: the registry owns the read, this module only serves the row.
+      models: machine.models || null,
     })),
     hubNetworkSuspect,
+    // WP-0 (S-3): the hub's own fleet target (local refs/heads/main), '' when this hub has no
+    // readable main. Top level because it is one fact about the hub, not about any one box.
+    fleetTarget,
   });
 }
 
@@ -441,12 +539,593 @@ async function handleMachineRemove(req, res, url, params) {
   return _send(res, 200, { ok: true, removed: Number(removed) || 0, rotated, unreachable });
 }
 
+/* ------------------------------------------------------------------------------------------------
+ * WP-8 (§6.5): the hub end of the one-skill exchange, and per-machine plugin exclusions.
+ * ---------------------------------------------------------------------------------------------- */
+
+/** One machine row by instance id, in the same shape lib/machine-registry.js's view reads. */
+function _machineRow(instanceId) {
+  const rows = (_deps && _deps.db && _deps.db.listMachineRows()) || [];
+  const wanted = String(instanceId || '');
+  return rows.find((row) => String((row && (row.instanceId || row.instance_id)) || '') === wanted) || null;
+}
+
+/** P-4 dial order for a row: the roster `urls`, else the single pinned `url`. */
+function _dialUrlsFor(row) {
+  const list = (Array.isArray(row && row.urls) ? row.urls : [])
+    .map((url) => String(url || '').trim().replace(/\/+$/, ''))
+    .filter(Boolean);
+  if (list.length) return list;
+  const pinned = String((row && row.url) || '').trim().replace(/\/+$/, '');
+  return pinned ? [pinned] : [];
+}
+
+/**
+ * One request to a box, in the P-4 order: try every advertised URL and stop at the first one that
+ * ANSWERS (a transport failure moves on; an HTTP answer — even a refusal — ends the attempt, because a
+ * second URL that answers differently is a different machine). The credential is THIS hub's, per
+ * target (`_peerHeadersFor`), and no answer is ever followed to a second address.
+ *
+ * @returns {Promise<{ok: boolean, status: number, body: object|null}>}
+ */
+async function _callBox(instanceId, pathname, { method = 'GET', body = null } = {}) {
+  const row = _machineRow(instanceId);
+  const headers = _peerHeadersFor(instanceId);
+  for (const base of _dialUrlsFor(row)) {
+    const res = await _fetchJson(`${base}${pathname}`, { method, body, headers });
+    if (res.status) return res;
+  }
+  return { ok: false, status: 0, body: null };
+}
+
+/**
+ * This hub's credential state for a box — `missing` means there is nothing to dial WITH, which is a
+ * 409 the user can act on, not a 502 "the box is down".
+ */
+function _credentialMissing(instanceId) {
+  try {
+    return require('../remote-machine-create').peerCredentialState(process.env, { instanceId }) === 'missing';
+  } catch {
+    return false; // expected: a credential-probe fault is not proof the credential is absent
+  }
+}
+
+/** Every WP-8 failure path: the transfer's own typed status, else a 500 in the module's shape. */
+function _skillFail(res, error) {
+  if (error instanceof skillTransfer.AgentSkillError) {
+    const payload = { ok: false, error: error.code };
+    if (error.detail) payload.detail = error.detail;
+    return _send(res, error.status, payload);
+  }
+  if (_deps && _deps.errorSink && typeof _deps.errorSink.report === 'function') {
+    _deps.errorSink.report('machines:skills', error);
+  }
+  return _send(res, 500, { ok: false, error: 'internal_error' });
+}
+
+/** §6.5 step 7: an import/retire moved the hub's own tree, so both caches are now stale. */
+function _invalidateSkillsCaches(instanceId) {
+  const registry = _deps && _deps.registry;
+  if (!registry) return;
+  if (typeof registry.invalidateHubItemCache === 'function') registry.invalidateHubItemCache();
+  if (typeof registry.markAgentSkillsStale === 'function') registry.markAgentSkillsStale(instanceId);
+}
+
+/** The transports the transfer lib calls — built here so the lib owns policy and this module owns the socket. */
+function _boxTransports(instanceId) {
+  return {
+    fetchExport: ({ agent, name }) => _callBox(
+      instanceId,
+      `/api/agent-skills/export?agent=${encodeURIComponent(agent)}&name=${encodeURIComponent(name)}`,
+      { method: 'GET' },
+    ),
+    retire: ({ agent, name, expectHash }) => _callBox(instanceId, '/api/agent-skills/retire', {
+      method: 'POST',
+      body: { agent, name, expectHash },
+    }),
+  };
+}
+
+/**
+ * WP-8 §6.5: `POST /api/machines/:instanceId/skills/import { agent, name, expectBoxHash }`.
+ *
+ * The bytes come off the box, are verified against the hash the user reviewed (AC-8c), and are written
+ * into the hub's own skill root with a backup first (AC-8b, P-5) — and only then is the box asked to
+ * retire its shadowing copy (D-13). A retire failure never undoes the import; it is reported.
+ */
+async function handleMachineSkillsImport(req, res, url, params) {
+  const instanceId = decodeURIComponent((params && (params['1'] || params.id)) || '');
+  if (!_machineRow(instanceId)) return _send(res, 404, { ok: false, error: 'machine_not_found' });
+  if (_credentialMissing(instanceId)) return _send(res, 409, { ok: false, error: 'agent_skill_no_credential' });
+  let body = {};
+  try {
+    body = await _deps.readJsonRequestBody(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const fields = body && !Array.isArray(body) ? body : {};
+  try {
+    const result = await skillTransfer.importBoxSkillToHub({
+      agent: fields.agent,
+      name: fields.name,
+      expectBoxHash: fields.expectBoxHash,
+      dataDir: _dataDir(),
+      hubHomeDir: _hubHomeDir(),
+      hubEnv: _hubEnv(),
+      now: _now(),
+      ..._boxTransports(instanceId),
+    });
+    _invalidateSkillsCaches(instanceId);
+    return _send(res, 200, { ok: true, ...result });
+  } catch (error) {
+    return _skillFail(res, error);
+  }
+}
+
+/**
+ * WP-8 §6.5: `POST /api/machines/:instanceId/skills/retire { agent, name, expectBoxHash }` — "use the
+ * laptop's copy" (or a redundant `same` copy): the box's folder moves aside and NOTHING is written here.
+ */
+async function handleMachineSkillsRetire(req, res, url, params) {
+  const instanceId = decodeURIComponent((params && (params['1'] || params.id)) || '');
+  if (!_machineRow(instanceId)) return _send(res, 404, { ok: false, error: 'machine_not_found' });
+  if (_credentialMissing(instanceId)) return _send(res, 409, { ok: false, error: 'agent_skill_no_credential' });
+  let body = {};
+  try {
+    body = await _deps.readJsonRequestBody(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const fields = body && !Array.isArray(body) ? body : {};
+  try {
+    const result = await skillTransfer.retireBoxSkillFromHub({
+      agent: fields.agent,
+      name: fields.name,
+      expectBoxHash: fields.expectBoxHash,
+      retire: _boxTransports(instanceId).retire,
+    });
+    _invalidateSkillsCaches(instanceId);
+    return _send(res, 200, { ok: true, ...result });
+  } catch (error) {
+    return _skillFail(res, error);
+  }
+}
+
+/**
+ * WP-9 (§9 S-9, AC-9b): `GET /api/machines/:instanceId/skills/preview?agent=&name=` — the Review
+ * dialog's DIFF SOURCE. The browser cannot call the box's own `GET /api/agent-skills/export`
+ * (peer-bearer auth), so this route relays one read: the box's copy through the SAME fetch +
+ * verification the import leg runs, and the hub's own copy (or null) beside it.
+ *
+ * ORDER, and why it differs from the two write legs: the machine is resolved, then the REF is
+ * validated (400), and only then is the credential asked for. A malformed `agent`/`name` never dials
+ * anything, so its answer must not depend on whether this hub happens to hold a credential for that
+ * box — the write legs read the credential first only because their body is the transfer itself.
+ */
+async function handleMachineSkillsPreview(req, res, url, params) {
+  const instanceId = decodeURIComponent((params && (params['1'] || params.id)) || '');
+  const search = (url && typeof url.searchParams === 'object' && url.searchParams) ? url.searchParams : null;
+  const agent = String((search && search.get('agent')) || '').trim();
+  const name = String((search && search.get('name')) || '').trim();
+  if (!_machineRow(instanceId)) return _send(res, 404, { ok: false, error: 'machine_not_found' });
+  try {
+    skillTransfer.validateSkillRef(agent, name);
+  } catch {
+    // expected: a bad agent/name is a 400 — the module's own code is reused so the two agree
+    return _send(res, 400, { ok: false, error: 'agent_skill_invalid' });
+  }
+  if (_credentialMissing(instanceId)) return _send(res, 409, { ok: false, error: 'agent_skill_no_credential' });
+  try {
+    const preview = await skillTransfer.previewBoxSkill({
+      agent,
+      name,
+      hubHomeDir: _hubHomeDir(),
+      hubEnv: _hubEnv(),
+      fetchExport: _boxTransports(instanceId).fetchExport,
+    });
+    return _send(res, 200, { ok: true, ...preview });
+  } catch (error) {
+    return _skillFail(res, error);
+  }
+}
+
+/**
+ * WP-8 §6.5: `PUT /api/machines/:instanceId/skills/exclude-plugins { plugins: [ids] }` — replace one
+ * machine's plugin exclusion list (one hub-side JSON file; a DB column is out of scope for this WP).
+ */
+async function handleMachineSkillsExcludePlugins(req, res, url, params) {
+  const instanceId = decodeURIComponent((params && (params['1'] || params.id)) || '');
+  if (!_machineRow(instanceId)) return _send(res, 404, { ok: false, error: 'machine_not_found' });
+  let body = {};
+  try {
+    body = await _deps.readJsonRequestBody(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const plugins = body && !Array.isArray(body) ? body.plugins : undefined;
+  try {
+    const stored = await skillTransfer.setExcludePlugins(_dataDir(), instanceId, plugins);
+    const registry = _deps && _deps.registry;
+    if (registry && typeof registry.noteRegistryChanged === 'function') registry.noteRegistryChanged();
+    return _send(res, 200, { ok: true, excludePlugins: stored });
+  } catch (error) {
+    return _skillFail(res, error);
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// WP-1 (docs/remote-box-model-access-2026-10-26.html §6.1, §5.1 R-2/R-3, §5.3 D-2/D-3/D-9):
+// `GET /api/models/availability` — THIS machine's answer about its OWN route rows.
+//
+// The hub never infers a box's models from its own rows (R-2); it asks the box, and the box answers
+// from its own Wall-E table with an unauthenticated reachability probe (R-3). Auth is the
+// `admin` + peerControl READ row in lib/auth-rules.js — the caller is the paired hub's peer bearer.
+// ---------------------------------------------------------------------------------------------
+
+/** The box's own coding-CLI sign-in truth — the SAME source `GET /api/providers/login-state` serves. */
+async function _nativeLoginState() {
+  if (_deps && typeof _deps.probeLoginState === 'function') return _deps.probeLoginState();
+  try {
+    const accounts = await require('../coding-agent-auth').probeAll();
+    const signedIn = (entry) => !!(entry && entry.signedIn === true);
+    return {
+      claude: { signedIn: signedIn(accounts && accounts['claude-code']) },
+      codex: { signedIn: signedIn(accounts && accounts.codex) },
+    };
+  } catch {
+    // expected: a CLI that cannot be probed is "we cannot say signed in" — never a 500 on a read
+    return { claude: { signedIn: false }, codex: { signedIn: false } };
+  }
+}
+
+/** The box's own `default:claude` / `default:codex` picks, from its own Wall-E over loopback. */
+async function _delegateDefaults() {
+  if (_deps && typeof _deps.delegateDefaults === 'function') return _deps.delegateDefaults();
+  try {
+    const response = await require('../walle-client').requestJson('/api/wall-e/internal/delegate-defaults');
+    const body = response && response.json;
+    return body && Array.isArray(body.defaults) ? body.defaults : [];
+  } catch {
+    // expected: Wall-E unreachable — the route rows are still a useful answer, with no defaults
+    return [];
+  }
+}
+
+async function handleModelsAvailability(req, res, url) {
+  const refresh = !!(url && url.searchParams && url.searchParams.get('refresh') === '1');
+  const callerKey = String((req && req.ctmAuth && req.ctmAuth.peerInstanceId) || 'local');
+  try {
+    const body = await modelAvailability.buildAvailability({
+      walleClient: (_deps && _deps.walleClient) || require('../walle-client'),
+      loginState: await _nativeLoginState(),
+      delegatePrefs: await _delegateDefaults(),
+      probe: _deps && _deps.probe,
+      refresh,
+      callerKey,
+      instanceId: _instanceId(),
+      now: _deps && typeof _deps.now === 'function' ? _deps.now : undefined,
+    });
+    return _send(res, 200, body);
+  } catch (error) {
+    // HANDLE: a constant reply, like the rest of this module's failures. The only errors that reach
+    // here are the box-local Wall-E read and the probe, and neither message may be echoed back —
+    // `availability_failed` is the whole answer (the hub's probe tick records its own verdict).
+    void error;
+    return _send(res, 500, { ok: false, code: 'availability_failed' });
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// WP-4 (§6.4): `POST /api/models/remove` — the BOX end of "Remove from <box>", and
+// `POST /api/machines/:instanceId/models/remove` — the HUB end that dials it.
+//
+// The direction is the point: the hub never writes a box's route rows (R-2), so removal is asked of
+// the box that owns them and only the box's own Wall-E deletes. Both halves validate with the SAME
+// `modelAvailability.normalizeRouteIds`, so a malformed body is one 400 with one message wherever it
+// is caught; the ids are the only thing that crosses the wire in either direction.
+// ---------------------------------------------------------------------------------------------
+
+/** Read the request body, or null when it is not parseable JSON. Shared by the box and hub legs. */
+async function _readObjectBody(req) {
+  let body = null;
+  try {
+    body = await _deps.readJsonRequestBody(req);
+  } catch {
+    return null; // expected: an unreadable body is the caller's 400, never a 500
+  }
+  return body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+}
+
+/**
+ * The box's own 400 for a bad `routeIds` — the same shape on both legs, so a client parses one code.
+ * The message is a fixed sentence about the SHAPE only; it never echoes the caller's value.
+ */
+function _invalidRouteIds(res, message) {
+  return _send(res, 400, { ok: false, code: 'invalid_request', message: String(message || 'routeIds is invalid') });
+}
+
+/** §6.4: the BOX end — remove ids from THIS machine's own Wall-E rows. */
+async function handleModelsRemove(req, res) {
+  const fields = await _readObjectBody(req);
+  if (fields === null) return _invalidRouteIds(res, 'the request body must be JSON');
+  const normalized = modelAvailability.normalizeRouteIds(fields.routeIds);
+  if (!normalized.ok) return _invalidRouteIds(res, normalized.message);
+  try {
+    const result = await modelAvailability.removeRoutes({
+      walleClient: (_deps && _deps.walleClient) || require('../walle-client'),
+      routeIds: normalized.ids,
+    });
+    return _send(res, 200, { ok: true, removed: result.removed, missing: result.missing });
+  } catch (error) {
+    if (error && error.code === 'walle_unavailable') return _send(res, 502, { ok: false, code: 'walle_unavailable' });
+    // REPORT + HANDLE: a constant reply, like the rest of this module's failures — the message of an
+    // unclassified fault is never echoed back (it could only describe this box's own storage).
+    if (_deps && _deps.errorSink && typeof _deps.errorSink.report === 'function') _deps.errorSink.report('machines:models-remove', error);
+    return _send(res, 500, { ok: false, code: 'remove_failed' });
+  }
+}
+
+/**
+ * The hub's named refusal — the same body every machine forward writes, naming the machine so the
+ * card can say WHICH box failed. `status` is 503 for a box that never answered (the dial failed) and
+ * 502 for one that answered nothing usable (the module's own spelling for that refusal, as in the
+ * pair route above).
+ */
+function _machineUnreachable(res, instanceId, machineName, status = 503) {
+  const label = String(machineName || instanceId || 'the machine');
+  return _send(res, status, {
+    ok: false, code: 'machine_unreachable', error: `Machine ${label} is unreachable`,
+    machine: String(instanceId || ''), machineName: String(machineName || ''),
+  });
+}
+
+/**
+ * §6.4: the HUB end — validate here (400), then dial the box ONCE with this hub's own credential for
+ * that machine (409 when there is none to dial with, exactly like the skills legs) and relay the
+ * box's status + body VERBATIM, so the client parses the box's answer as it parses a local one. A box
+ * that does not answer is the named 503 `machine_unreachable`.
+ *
+ * A successful 2xx answer that names `removed` ids also forgets those ids in the hub's cached models
+ * block for that machine (lib/machine-registry.js) — the cache is a read of the box's rows and would
+ * otherwise keep showing a row the box just deleted until its next 60 s tick.
+ */
+async function handleMachineModelsRemove(req, res, url, params) {
+  const instanceId = decodeURIComponent((params && (params['1'] || params.id)) || '');
+  const row = _machineRow(instanceId);
+  if (!row) return _send(res, 404, { ok: false, error: 'machine_not_found' });
+  if (_credentialMissing(instanceId)) return _send(res, 409, { ok: false, error: 'agent_skill_no_credential' });
+  const fields = await _readObjectBody(req);
+  if (fields === null) return _invalidRouteIds(res, 'the request body must be JSON');
+  const normalized = modelAvailability.normalizeRouteIds(fields.routeIds);
+  if (!normalized.ok) return _invalidRouteIds(res, normalized.message);
+  const answer = await _callBox(instanceId, '/api/models/remove', { method: 'POST', body: { routeIds: normalized.ids } });
+  if (!answer || !answer.status) return _machineUnreachable(res, instanceId, row.displayName);
+  const body = answer.body && typeof answer.body === 'object' ? answer.body : null;
+  // An answer with no JSON object is not an answer this client can parse — the same refusal, one
+  // status up, never a 2xx carrying nothing.
+  if (!body) return _machineUnreachable(res, instanceId, row.displayName, 502);
+  if (answer.status >= 200 && answer.status < 300 && Array.isArray(body.removed) && body.removed.length) {
+    // REPORT-free by design: a cache that cannot be updated is not a failure of the box's own
+    // answer, which is relayed below regardless.
+    try {
+      require('../machine-registry').forgetMachineModelRoutes(instanceId, body.removed);
+    } catch { /* expected: an unwired/legacy registry — the box's answer still stands */ }
+  }
+  return _send(res, answer.status, body);
+}
+
+// ---------------------------------------------------------------------------------------------
+// WP-5 (§5.1 R-5/R-6, §6.4): "Use on <box>" — copy ONE hub route (with its credential) onto a box,
+// on an explicit request, and the BOX end that performs the write.
+//
+//   HUB GET  /api/machines/:instanceId/models/copyable -> the hub's rows this box lacks
+//   HUB POST /api/machines/:instanceId/models/copy     -> read the row (key included) over loopback,
+//                                                        hand it to the box, relay the box's answer
+//   BOX POST /api/models/import                        -> validate the row, write it to this box's
+//                                                        own Wall-E
+//
+// R-5/R-6: per-route and user-initiated, never a bulk export and never a sync. The key exists only
+// inside the hub's in-memory request to the box (`_dialBoxImport`), is never logged and never
+// returned, and both answers carry `{ ok, routeId }` and nothing else.
+// ---------------------------------------------------------------------------------------------
+
+/** This process's loopback Wall-E client — the injected seam in tests, the real one in production. */
+function _walle() {
+  return (_deps && _deps.walleClient) || require('../walle-client');
+}
+
+/** The hub's cached §6.2 block for one box, or null when it has never been read (pre-WP-1 box). */
+function _modelsBlockFor(instanceId) {
+  const registry = _deps && _deps.registry;
+  if (!registry || typeof registry.modelsFor !== 'function') return null;
+  return registry.modelsFor(instanceId) || null;
+}
+
+/** The box's own route rows as its last availability read saw them — never null, [] when unknown. */
+function _boxRouteRows(instanceId) {
+  const block = _modelsBlockFor(instanceId);
+  return block && Array.isArray(block.routes) ? block.routes : [];
+}
+
+/** §6.4: does the box's last read say it cannot reach this origin? An unprobed origin is NOT a no. */
+function _originUnreachableOn(instanceId, origin) {
+  if (!origin) return false;
+  return _boxRouteRows(instanceId).some(
+    (row) => row && row.origin === origin && (row.reach === 'unreachable' || row.reach === 'no_server'),
+  );
+}
+
+/** The row's default model string, when the hub's provider list carries one — else ''. */
+function _routeModelOf(row) {
+  for (const field of ['model', 'default_model']) {
+    if (row && typeof row[field] === 'string' && row[field].trim()) return row[field].trim();
+  }
+  return '';
+}
+
+/** §6.4: the HUB's "what could this box use" list. A read: no step-up ceremony, no local write. */
+async function handleMachineModelsCopyable(req, res, url, params) {
+  const instanceId = decodeURIComponent((params && (params['1'] || params.id)) || '');
+  const row = _machineRow(instanceId);
+  if (!row) return _send(res, 404, { ok: false, error: 'machine_not_found' });
+  if (_credentialMissing(instanceId)) return _send(res, 409, { ok: false, error: 'agent_skill_no_credential' });
+  // No block: the hub has never read this box's routes (a pre-WP-1 box, or its first tick has not
+  // run). It cannot say which of its rows the box already has, so it offers NOTHING rather than a
+  // list it cannot qualify — the card shows "not read yet" and no copy button (§6.4).
+  if (!_modelsBlockFor(instanceId)) return _send(res, 200, { ok: true, routes: [] });
+  let hubRows = null;
+  try {
+    hubRows = await modelAvailability.readOwnProviderRows({ walleClient: _walle() });
+  } catch (error) {
+    // HANDLE: the hub cannot read ITS OWN route table — a constant reply, like this module's other
+    // unclassified failures (the row's key is not involved in this read at all).
+    if (_deps && _deps.errorSink && typeof _deps.errorSink.report === 'function') _deps.errorSink.report('machines:models-copyable', error);
+    return _send(res, 502, { ok: false, code: 'walle_unavailable' });
+  }
+  const boxRoutes = _boxRouteRows(instanceId);
+  const onBox = new Set(boxRoutes.map((entry) => entry && entry.id).filter(Boolean));
+  const unreachable = new Set(
+    boxRoutes
+      .filter((entry) => entry && (entry.reach === 'unreachable' || entry.reach === 'no_server'))
+      .map((entry) => entry.origin)
+      .filter(Boolean),
+  );
+  const routes = [];
+  for (const hubRow of hubRows) {
+    const id = String((hubRow && hubRow.id) == null ? '' : hubRow.id);
+    if (!id || onBox.has(id)) continue;
+    if (hubRow.enabled === 0 || hubRow.enabled === false) continue;
+    // The box's raw upsert carries no auth method (it always lands as the default api_key), so a
+    // route that signs in any other way would arrive as a DIFFERENT route. Not offered, not copied.
+    if (!_copyableAuthMethod(hubRow.auth_method)) continue;
+    const origin = modelAvailability.rowOrigin(hubRow);
+    // "the box says that ORIGIN is out of reach" — an origin the box has not probed yet is KEPT
+    // (D-9: one probe per origin per 10 min, so "no verdict" is the normal state of a fresh origin).
+    if (origin && unreachable.has(origin)) continue;
+    routes.push({
+      id,
+      type: String((hubRow.type == null) ? '' : hubRow.type),
+      name: String((hubRow.name == null) ? '' : hubRow.name),
+      origin: origin || null,
+      model: _routeModelOf(hubRow),
+    });
+  }
+  return _send(res, 200, { ok: true, routes });
+}
+
+/** §6.4/R-5: the ONE credential-carrying read — scoped so the reference dies with the dial. */
+/** A route a box can recreate: no auth method recorded, or the default `api_key` (case-insensitive). */
+function _copyableAuthMethod(value) {
+  const method = String(value == null ? '' : value).trim().toLowerCase();
+  return method === '' || method === 'api_key';
+}
+
+async function _dialBoxImport(instanceId, routeId) {
+  const exported = await modelAvailability.exportOwnRoute({ walleClient: _walle(), routeId });
+  if (!exported) return { ok: false, status: 0, body: null, missing: true };
+  if (!_copyableAuthMethod(exported.row && exported.row.auth_method)) {
+    return { ok: false, status: 0, body: null, missing: false, unsupported: true };
+  }
+  const answer = await _callBox(instanceId, '/api/models/import', { method: 'POST', body: { row: exported.row } });
+  return { ...(answer || { ok: false, status: 0, body: null }), missing: false };
+}
+
+/**
+ * §6.4: the HUB end of "Use on <box>". The order is the remove leg's — 404 machine → 409 credential
+ * → validate the body (400) — then the three refusals that belong to THIS act: no such hub route
+ * (404 route_not_found), a stale client (`origin_changed`), and a box whose own last read says the
+ * route's origin is out of reach (`route_unreachable_on_machine`, dialled nothing at all — the whole
+ * point of checking the cache first is that the user learns the route would be dead on that box
+ * before a credential is moved to it).
+ */
+async function handleMachineModelsCopy(req, res, url, params) {
+  const instanceId = decodeURIComponent((params && (params['1'] || params.id)) || '');
+  const row = _machineRow(instanceId);
+  if (!row) return _send(res, 404, { ok: false, error: 'machine_not_found' });
+  if (_credentialMissing(instanceId)) return _send(res, 409, { ok: false, error: 'agent_skill_no_credential' });
+  const fields = await _readObjectBody(req);
+  if (fields === null) return _send(res, 400, { ok: false, code: 'invalid_request', message: 'the request body must be JSON' });
+  const normalized = modelAvailability.normalizeCopyRequest(fields);
+  if (!normalized.ok) return _send(res, 400, { ok: false, code: 'invalid_request', message: normalized.message });
+  let hubRows = null;
+  try {
+    hubRows = await modelAvailability.readOwnProviderRows({ walleClient: _walle() });
+  } catch (error) {
+    if (_deps && _deps.errorSink && typeof _deps.errorSink.report === 'function') _deps.errorSink.report('machines:models-copy', error);
+    return _send(res, 502, { ok: false, code: 'walle_unavailable' });
+  }
+  const hubRow = hubRows.find((entry) => String((entry && entry.id) == null ? '' : entry.id) === normalized.routeId) || null;
+  if (!hubRow) return _send(res, 404, { ok: false, code: 'route_not_found' });
+  const origin = modelAvailability.rowOrigin(hubRow);
+  if (String(origin || '') !== normalized.expectOrigin) return _send(res, 409, { ok: false, code: 'origin_changed' });
+  if (_originUnreachableOn(instanceId, origin)) return _send(res, 409, { ok: false, code: 'route_unreachable_on_machine' });
+  const answer = await _dialBoxImport(instanceId, normalized.routeId);
+  if (answer.missing) return _send(res, 404, { ok: false, code: 'route_not_found' });
+  if (answer.unsupported) return _send(res, 409, { ok: false, code: 'auth_method_not_supported' });
+  if (!answer.status) return _machineUnreachable(res, instanceId, row.displayName);
+  const body = answer.body && typeof answer.body === 'object' ? answer.body : null;
+  // An answer with no JSON object is not an answer this client can parse — the same refusal, one
+  // status up, never a 2xx carrying nothing.
+  if (!body) return _machineUnreachable(res, instanceId, row.displayName, 502);
+  if (answer.status >= 200 && answer.status < 300) {
+    // REPORT-free by design (as in the remove leg): a cache that cannot be updated is not a failure
+    // of the box's own answer. The box now has one MORE row, so the stamp is zeroed — the block
+    // stays readable until the next tick re-reads the box's truth.
+    try {
+      require('../machine-registry').markMachineModelsStale(instanceId);
+    } catch { /* expected: an unwired/legacy registry — the box's answer still stands */ }
+  }
+  return _send(res, answer.status, body);
+}
+
+/** §6.4: the BOX end — validate the row here, then write it to THIS machine's own Wall-E. */
+async function handleModelsImport(req, res) {
+  const fields = await _readObjectBody(req);
+  if (fields === null) return _send(res, 400, { ok: false, code: 'invalid_request', message: 'the request body must be JSON' });
+  const normalized = modelAvailability.normalizeImportRow(fields.row);
+  if (!normalized.ok) return _send(res, 400, { ok: false, code: 'invalid_request', message: normalized.message });
+  try {
+    const result = await modelAvailability.importRoute({ walleClient: _walle(), row: normalized.row });
+    return _send(res, 200, { ok: true, routeId: result.routeId });
+  } catch (error) {
+    if (error && error.code === 'walle_unavailable') return _send(res, 502, { ok: false, code: 'walle_unavailable' });
+    // REPORT + HANDLE: a constant reply, like the rest of this module's failures — the message of an
+    // unclassified fault is never echoed back, and the row (which carries a key) is never part of it.
+    if (_deps && _deps.errorSink && typeof _deps.errorSink.report === 'function') _deps.errorSink.report('machines:models-import', error);
+    return _send(res, 500, { ok: false, code: 'import_failed' });
+  }
+}
+
 function register() {
   registerApiRoutes('machines', [
     { method: 'GET', path: '/api/machines', handler: (req, res) => handleMachinesList(req, res) },
     { method: 'POST', path: '/api/machines', handler: (req, res) => handleMachinesCreate(req, res) },
     { method: 'POST', path: '/api/machines/pair', handler: (req, res) => handleMachinesPair(req, res) },
     { method: 'POST', regex: /^\/api\/machines\/([^/]+)\/remove$/, handler: (req, res, url, params) => handleMachineRemove(req, res, url, params) },
+    // WP-8 (§6.5): the one-skill exchange. The regexes are byte-identical to lib/auth-rules.js's rows
+    // on purpose — routing and auth must agree on what "this route" is, or a malformed id would be
+    // answered by the auth wall with a different code than the handler's own 404.
+    { method: 'POST', regex: /^\/api\/machines\/([^/]+)\/skills\/import$/, handler: (req, res, url, params) => handleMachineSkillsImport(req, res, url, params) },
+    { method: 'POST', regex: /^\/api\/machines\/([^/]+)\/skills\/retire$/, handler: (req, res, url, params) => handleMachineSkillsRetire(req, res, url, params) },
+    // WP-9 (§9 S-9): the diff source — a READ, so it is the one skills row that is neither a step-up
+    // nor a mutation (lib/auth-rules.js carries the matching row, byte-identical regex).
+    { method: 'GET', regex: /^\/api\/machines\/([^/]+)\/skills\/preview$/, handler: (req, res, url, params) => handleMachineSkillsPreview(req, res, url, params) },
+    { method: 'PUT', regex: /^\/api\/machines\/([^/]+)\/skills\/exclude-plugins$/, handler: (req, res, url, params) => handleMachineSkillsExcludePlugins(req, res, url, params) },
+    // WP-1 (§6.1): the BOX side of the model-availability read — registered beside the machine-self
+    // and agent-skills peer reads because it is the same kind of surface (a route the paired hub
+    // dials with the peer bearer, lib/auth-rules.js carrying the matching peerControl row).
+    { method: 'GET', path: '/api/models/availability', handler: (req, res, url) => handleModelsAvailability(req, res, url) },
+    // WP-4 (§6.4): the BOX end of "Remove from <box>" — this machine's own rows, removed through its
+    // own Wall-E. Auth is the peer-control mutation row in lib/auth-rules.js (the paired hub's bearer).
+    { method: 'POST', path: '/api/models/remove', handler: (req, res, url) => handleModelsRemove(req, res, url) },
+    // WP-5 (§6.4, R-5/R-6): the BOX end of "Use on <box>" — this machine writes ONE route the hub
+    // exported into its own Wall-E. Auth is the peer-control mutation row in lib/auth-rules.js.
+    { method: 'POST', path: '/api/models/import', handler: (req, res, url) => handleModelsImport(req, res, url) },
+    // §6.4: the HUB ends — dial the box above with this hub's credential for it. Same regex spelling
+    // as the skills rows: routing and auth must agree on what "this route" is.
+    { method: 'POST', regex: /^\/api\/machines\/([^/]+)\/models\/remove$/, handler: (req, res, url, params) => handleMachineModelsRemove(req, res, url, params) },
+    { method: 'GET', regex: /^\/api\/machines\/([^/]+)\/models\/copyable$/, handler: (req, res, url, params) => handleMachineModelsCopyable(req, res, url, params) },
+    { method: 'POST', regex: /^\/api\/machines\/([^/]+)\/models\/copy$/, handler: (req, res, url, params) => handleMachineModelsCopy(req, res, url, params) },
   ]);
 }
 
@@ -458,4 +1137,14 @@ module.exports = {
   handleMachinesCreate,
   handleMachinesPair,
   handleMachineRemove,
+  handleMachineSkillsImport,
+  handleMachineSkillsRetire,
+  handleMachineSkillsPreview,
+  handleMachineSkillsExcludePlugins,
+  handleModelsAvailability,
+  handleModelsRemove,
+  handleMachineModelsRemove,
+  handleModelsImport,
+  handleMachineModelsCopyable,
+  handleMachineModelsCopy,
 };