create-walle 0.10.0 → 0.10.2

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

@@ -0,0 +1,461 @@
+'use strict';
+
+// WP-0 (remote-machine-hub-sessions-2026-10-22.html §6.1): the hub machine-registry routes.
+//
+//   GET  /api/machines              -> { machines:[{instanceId, displayName, url, urls, health,
+//                                        lastSeenAt, favorite, hidden, stats, lastUsedAt, os, arch,
+//                                        hostname, peerCredential, agents, …}], hubNetworkSuspect }
+//                                        `peerCredential` (WP-1 D-4, WP-2a D-8 rev 2) is
+//                                        'pool' | 'env' | 'missing' — a hub-local fact repeated on
+//                                        every row, never the token.
+//                                        `agents` (WP-3) is the box's last-read coding-CLI sign-in
+//                                        verdict: { claude, codex, checkedAt } with each agent
+//                                        'signed_in' | 'signed_out' | 'unknown'. The all-'unknown'
+//                                        default means "never fetched" — a hub that has not probed
+//                                        this box yet must not imply either answer.
+//   POST /api/machines              -> register { url, displayName?, walleUrl? } (one manifest
+//                                        probe IS the identity pin, D-3)
+//   POST /api/machines/pair         -> WP-3 §6.3: join a pool by redeeming the box's pairing code
+//   POST /api/machines/:id/remove   -> unregister; WP-3 §6.3 extends it to a pool member
+//
+// Unlike the lib/api/*.js extraction slices, this module is NEW surface (WP-0), so the handler
+// bodies live here rather than in server.js's legacy handleApi chain — there is no legacy branch
+// to delete, and tests-integration/api-router-parity.test.js's no-dual-dispatch rule is satisfied
+// by construction. Handlers are thin: the policy (pin/mismatch/probe) is lib/machine-registry.js,
+// the SQL is db.js's owner zone, and the pairing codec/verifier is lib/machine-pairing.js.
+//
+// Auth is NOT evaluated here: lib/auth-rules.js carries the rows (loopbackOnly + admin, modeled on
+// 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 { registerApiRoutes } = require('../api-router');
+const machinePairing = require('../machine-pairing');
+
+// §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.
+const PAIR_PROBE_TIMEOUT_MS = 5_000;
+// §6.3: roster pushes and rotation calls are best-effort against a possibly-dead member. Ten seconds
+// matches lib/remote-machine-proxy.js's DEFAULT_TIMEOUT_MS, the proxy's own box budget.
+const PAIR_PUSH_TIMEOUT_MS = 10_000;
+
+let _deps = null;
+
+function configure({
+  db,
+  registry,
+  pool,
+  readJsonRequestBody,
+  sendJsonResponse,
+  ready = null,
+  fetchImpl = null,
+} = {}) {
+  _deps = { db, registry, pool, readJsonRequestBody, sendJsonResponse, ready, fetchImpl };
+}
+
+/**
+ * The boot read's promise (server.js `_machinePoolReady`) — pair/remove MUTATE the pool. Accepts
+ * either the promise itself or a thunk returning it: server.js configures this cluster (and its
+ * `machines` route group) BEFORE the pool block is evaluated, so the value can only be read lazily.
+ */
+function ready() {
+  const source = _deps && _deps.ready;
+  if (typeof source === 'function') return Promise.resolve(source());
+  return source || Promise.resolve();
+}
+
+function _send(res, status, payload) {
+  if (_deps && typeof _deps.sendJsonResponse === 'function') return _deps.sendJsonResponse(res, status, payload);
+  const body = JSON.stringify(payload || {});
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+/** This machine's own minted id — '' rather than a throw before boot has primed identity. */
+function _instanceId() {
+  try {
+    const identity = require('../instance-identity-access').getInstanceIdentity({ required: false });
+    return (identity && identity.instanceId) || '';
+  } catch {
+    return ''; // expected: instance identity is not ready yet (early boot / pre-initDb)
+  }
+}
+
+/** The pool store — the singleton by default, or whatever the injected thunk returns (see ready()). */
+function _pool() {
+  const source = _deps && _deps.pool;
+  if (typeof source === 'function') return source();
+  return source || require('../machine-pool').getMachinePool();
+}
+
+/**
+ * WP-2a D-8: the credential this member dials ONE target with (pool for a pool member, env
+ * otherwise). Used for OPERATING calls — the P-5/P-6 roster push and rotate — where the target is a
+ * machine this pool already holds. The identity PROBE and the JOIN hand-off deliberately do NOT use
+ * it: neither carries an Authorization header (see `_probeInstanceId` and step 5 below), because the
+ * box being paired has not issued this member anything to authenticate with.
+ */
+function _peerHeadersFor(instanceId) {
+  try {
+    return require('../remote-machine-create').buildPeerControlHeaders(process.env, { instanceId }) || {};
+  } catch {
+    return {}; // expected: no credential configured — the call goes out anonymous and is refused
+  }
+}
+
+/**
+ * One JSON round trip with a deadline. `AbortSignal.timeout(ms)` is the codebase's sanctioned
+ * non-timer deadline (lib/api/setup.js:168,190,209; lib/api/painted-rows.js:28; lib/oauth-proxy-
+ * supervisor.js) — this file therefore adds NO `setTimeout` site for the stabilization lint to own.
+ */
+function _fetchJson(url, { method = 'GET', headers = {}, body = null, timeoutMs = PAIR_PUSH_TIMEOUT_MS } = {}) {
+  const fetchFn = (_deps && _deps.fetchImpl) || global.fetch;
+  if (typeof fetchFn !== 'function') return Promise.resolve({ ok: false, status: 0, body: null });
+  const signal = typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+    ? AbortSignal.timeout(timeoutMs)
+    : undefined;
+  return fetchFn(url, {
+    method,
+    headers: {
+      Accept: 'application/json',
+      ...(body === null ? {} : { 'Content-Type': 'application/json' }),
+      ...headers,
+    },
+    body: body === null ? undefined : JSON.stringify(body),
+    signal,
+  }).then(async (res) => {
+    let parsed = null;
+    try {
+      parsed = await res.json();
+    } catch {
+      parsed = null; // expected: a non-JSON body is reported by status alone, never as a transport fault
+    }
+    return { ok: !!res.ok, status: Number(res.status) || 0, body: parsed };
+  }).catch(() => ({ ok: false, status: 0, body: null }));
+}
+
+/** The identity answer's instance id — the same three shapes lib/machine-registry.js accepts. */
+function _manifestInstanceId(body) {
+  const manifest = (body && (body.manifest || body.instance)) || body || {};
+  return String(
+    manifest.instanceId || manifest.instance_id || manifest.id
+    || (body && (body.instanceId || body.instance_id)) || '',
+  ).trim();
+}
+
+/**
+ * §6.3 step 2 (D-9): the identity probe, aimed at the box's PRE-AUTH `GET /api/machine-pairing/
+ * identity`. Reachable-and-matching / reachable-but-different / unreachable are three DIFFERENT
+ * answers — collapsing them is what makes a mis-pasted pairing string silently pair the wrong
+ * machine — and the identity comparison itself stays with the caller.
+ *
+ * WHY NOT /api/sync/manifest. That route is `sync`-scoped (lib/auth-rules.js), and a machine that has
+ * not paired yet holds no credential of this box at all: on a real LAN the probe would 401 and the
+ * pair would die as `machine_unreachable` before it began. The pairing routes are dispatched with
+ * phase 'api-cloudflare', BEFORE the auth wall, precisely so an unauthenticated member can ask this.
+ *
+ * NO AUTHORIZATION HEADER, on purpose. The box is not a pool member yet, so D-8 would offer the
+ * shared pool secret here — a secret handed to an address that came out of a pasted pairing string or
+ * a typed field, for a call that cannot be verified by the receiver anyway. The probe asks a
+ * BOOLEAN question ("is a code showing here") and needs no credential to do it.
+ */
+async function _probeInstanceId(url) {
+  const res = await _fetchJson(`${url}/api/machine-pairing/identity`, {
+    headers: {},
+    timeoutMs: PAIR_PROBE_TIMEOUT_MS,
+  });
+  if (!res.ok) return { ok: false };
+  const instanceId = _manifestInstanceId(res.body);
+  if (!instanceId) return { ok: false };
+  return { ok: true, instanceId };
+}
+
+/**
+ * P-1: this machine's roster as the wire carries it — every OTHER POOL MEMBER row plus SELF (last),
+ * each `{instanceId, urls}`.
+ *
+ * F2: ONE implementation, owned by lib/api/machine-pool.js (the module that owns the pool store) and
+ * consumed here. The local copy this file used to carry mapped EVERY machine row, so a legacy
+ * env-token row (P-8: a machine this hub dials with CTM_SYNC_PEER_TOKEN, never a pool member) was
+ * pushed to a newly paired box as a FELLOW MEMBER of a pool it had not joined — the box would then
+ * dial it with the pool bearer and be refused.
+ */
+function _rosterMembers() {
+  return require('./machine-pool').rosterMembers();
+}
+
+/**
+ * P-4 dial order, for one POST: try every URL the target advertises, in order, and stop at the first
+ * one that ANSWERS. A transport failure (status 0) moves on to the next URL; an HTTP answer — even a
+ * refusal — ends the attempt, because a second URL that answers differently is a different machine.
+ */
+async function _postToTarget(target, pathname, body, headers) {
+  const urls = (Array.isArray(target.urls) && target.urls.length ? target.urls : [String(target.url || '')])
+    .map((url) => String(url || '').trim().replace(/\/+$/, ''))
+    .filter(Boolean);
+  for (const base of urls) {
+    const res = await _fetchJson(`${base}${pathname}`, { method: 'POST', body, headers: headers || {} });
+    if (res.ok) return true;
+    if (res.status) return false;
+  }
+  return false;
+}
+
+async function handleMachinesList(req, res) {
+  const registry = _deps && _deps.registry;
+  const { machines, hubNetworkSuspect } = registry.listMachines({ db: _deps && _deps.db });
+  // 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
+  // never read into this response — only which class is in play.
+  const peerCredentialFor = require('../remote-machine-create').peerCredentialState;
+  // 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;
+  _send(res, 200, {
+    machines: machines.map((machine) => ({
+      instanceId: machine.instanceId,
+      displayName: machine.displayName,
+      url: machine.url,
+      walleUrl: machine.walleUrl,
+      enabled: machine.enabled,
+      health: machine.health,
+      healthDetail: machine.healthDetail,
+      lastSeenAt: machine.lastSeenAt,
+      pickerState: machine.pickerState,
+      visible: machine.visible,
+      // WP-2 (P-1/P-4): the dial list, in dial order — the roster's urls, `url` first when the roster
+      // is empty. The picker and the Machines page dial/render these; `url` stays the row's cached
+      // working address.
+      urls: Array.isArray(machine.urls) ? machine.urls : [],
+      // WP-2 (D-4 rev 2): machine-owned settings, read from the box's own manifest by the sweep.
+      // `favorite` is the picker star and is NEVER the identity pin (that word is reserved).
+      favorite: machine.favorite ? 1 : 0,
+      hidden: machine.hidden ? 1 : 0,
+      // WP-2 (D-12/D-16): the box's own host sample + the hub-clock stamp of the read (null = never
+      // read), and the newest session create on that machine (0 = none). Readers label staleness.
+      stats: machine.stats || null,
+      lastUsedAt: Number(machine.lastUsedAt) || 0,
+      os: machine.os || '',
+      arch: machine.arch || '',
+      hostname: machine.hostname || '',
+      peerCredential: peerCredentialFor(process.env, { instanceId: machine.instanceId }),
+      agents: (agentAuthFor ? agentAuthFor.call(registry, machine.instanceId) : null)
+        || { claude: 'unknown', codex: 'unknown', checkedAt: 0 },
+    })),
+    hubNetworkSuspect,
+  });
+}
+
+async function handleMachinesCreate(req, res) {
+  let body = {};
+  try {
+    body = await _deps.readJsonRequestBody(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const result = await _deps.registry.registerMachine({
+    url: body && (body.url || body.baseUrl || body.base_url),
+    displayName: body && (body.displayName || body.display_name || body.name),
+    walleUrl: body && (body.walleUrl || body.walle_url),
+  }, {
+    db: _deps.db,
+    // The hub's peer credential on the identity probe, so a box behind a relay or tunnel answers.
+    // P-8: the builder is PER TARGET in WP-2a, but the box's instance id is not known until the
+    // probe answers — so registration uses the no-target form, which is exactly today's behaviour
+    // (pool-if-pool, else the env bearer).
+    peerHeadersFor: () => require('../remote-machine-create').buildPeerControlHeaders(process.env) || {},
+  });
+  if (!result.ok) {
+    // machine_unreachable / machine_identity_mismatch / machine_manifest_invalid / machine_url_required
+    const status = result.code === 'machine_identity_mismatch' ? 409 : 502;
+    return _send(res, status, { ok: false, error: result.code, detail: result.error || '' });
+  }
+  return _send(res, 200, { ok: true, machine: result.machine });
+}
+
+/**
+ * WP-3 §6.3 — the MEMBER side of pairing. Steps 1-7 in the doc's order, with the doc's verbatim
+ * error codes. The token minted here is handed to the box ONCE and never echoed, logged or stored
+ * anywhere except lib/machine-pool.js's 0600 file.
+ */
+async function handleMachinesPair(req, res) {
+  let body = {};
+  try {
+    body = await _deps.readJsonRequestBody(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  // 1. parse — a `ctmpair1:` container, or the `code` + `url` pair the UI's manual form collects.
+  const parsed = machinePairing.decodePairingString(body && body.pairingString);
+  const code = parsed ? parsed.code : machinePairing.normalizeCode(body && body.code);
+  const claimedId = parsed ? parsed.instanceId : '';
+  const candidates = [];
+  if (parsed) candidates.push(...parsed.urls);
+  if (body && body.url) candidates.push(String(body.url).trim().replace(/\/+$/, ''));
+  const seen = new Set();
+  const dialOrder = candidates.filter((url) => {
+    if (!url || seen.has(url)) return false;
+    seen.add(url);
+    return true;
+  });
+  if (code.length !== machinePairing.CODE_LENGTH || !dialOrder.length) {
+    return _send(res, 400, { ok: false, error: 'pairing_string_invalid' });
+  }
+
+  // 2. identity-probe the candidates until one names the id the pairing string claimed.
+  let boxUrl = '';
+  let boxInstanceId = '';
+  let mismatched = '';
+  for (const candidate of dialOrder) {
+    const probe = await _probeInstanceId(candidate);
+    if (!probe.ok) continue;
+    if (claimedId && probe.instanceId !== claimedId) {
+      mismatched = probe.instanceId;
+      continue;
+    }
+    boxUrl = candidate;
+    boxInstanceId = probe.instanceId;
+    break;
+  }
+  if (!boxUrl) {
+    return mismatched
+      ? _send(res, 409, { ok: false, error: 'machine_identity_mismatch', detail: `manifest ${mismatched} != ${claimedId}` })
+      : _send(res, 502, { ok: false, error: 'machine_unreachable' });
+  }
+
+  await ready();
+  const pool = _pool();
+  const selfId = _instanceId();
+  // 3. mint the pool if this member has none yet (§6.3 — the first pairing creates the shared secret).
+  const token = await pool.ensurePool();
+  // 4. bump the roster, then build the membership set the box will store: every POOL MEMBER we
+  //    already hold, plus the box itself (P-1's roster already carries SELF last). The box stores
+  //    this MINUS itself (P-8). F2: the set comes from lib/api/machine-pool.js's `rosterMembers()`,
+  //    so a legacy env-token row — a registry row that is NOT a pool member — is never advertised to
+  //    the new box as one of its peers.
+  const version = await pool.bumpRoster(selfId);
+  const members = [
+    ..._rosterMembers().filter((member) => member.instanceId !== boxInstanceId),
+    { instanceId: boxInstanceId, urls: [boxUrl] },
+  ];
+
+  // 5. hand the token to the box. The response is the box's own identity + dial list; its error
+  //    codes are relayed VERBATIM (§6.3) so the UI can say exactly what happened.
+  //
+  //    F1: NO Authorization header. The join is the PRE-AUTH act that establishes this member's
+  //    credential on that box, so there is nothing meaningful to present — and everything D-8 could
+  //    pick here (the pool secret, or a legacy env bearer) is a secret sent to an unverified address
+  //    for a call the box cannot authenticate either way. The pool secret is proven by the CODE and
+  //    by the body's `token`, which is what the box adopts.
+  const join = await _fetchJson(`${boxUrl}/api/machine-pairing/join`, {
+    method: 'POST',
+    headers: {},
+    body: { code: machinePairing.formatCode(code), token, version, members, primary: { instanceId: selfId } },
+  });
+  if (!join.ok) {
+    const relayed = String((join.body && join.body.error) || '');
+    if (relayed === 'pairing_code_invalid') return _send(res, 410, { ok: false, error: 'pairing_code_invalid' });
+    if (relayed === 'rate_limited') return _send(res, 429, { ok: false, error: 'rate_limited' });
+    if (relayed === 'pool_member_exists') return _send(res, 409, { ok: false, error: 'pool_member_exists' });
+    if (relayed === 'pool_token_invalid') return _send(res, 400, { ok: false, error: 'pool_token_invalid' });
+    return _send(res, 502, { ok: false, error: 'machine_unreachable', detail: relayed || `http_${join.status}` });
+  }
+
+  // 6. record the box locally. `url` is the address we just PROVED reachable (the probe's winner) and
+  //    it leads the dial list; the box's own advertised URLs follow as fallbacks (P-4). A row whose
+  //    first URL is a LAN address this member cannot reach would leave the new member unusable.
+  const advertised = Array.isArray(join.body && join.body.urls) ? join.body.urls.map((url) => String(url || '')) : [];
+  const boxUrls = [boxUrl, ...advertised.filter((url) => url && url !== boxUrl)];
+  await _deps.db.upsertMachineRow({
+    instanceId: boxInstanceId,
+    displayName: String((join.body && join.body.displayName) || '').slice(0, 200),
+    url: boxUrl,
+    urls: boxUrls,
+  });
+  await pool.addMember(boxInstanceId);
+  if (_deps.registry && typeof _deps.registry.noteRegistryChanged === 'function') _deps.registry.noteRegistryChanged();
+
+  // 7. P-5: push the roster to every OTHER member, best-effort. The box is skipped — it was just
+  //    handed the same set (and the same version) inside the join request. A failure is not an error
+  //    here: the next sweep pull (lib/machine-registry.js) converges the same state.
+  const roster = _rosterMembers();
+  const targets = roster.filter((member) => member.instanceId !== selfId && member.instanceId !== boxInstanceId);
+  const pushed = [];
+  const unreachable = [];
+  for (const target of targets) {
+    const ok = await _postToTarget(target, '/api/pool/roster', { version, members: roster }, _peerHeadersFor(target.instanceId));
+    if (ok) pushed.push(target.instanceId);
+    else unreachable.push(target.instanceId);
+  }
+  return _send(res, 201, { ok: true, machine: { instanceId: boxInstanceId, url: boxUrl, urls: boxUrls }, pushed, unreachable });
+}
+
+/**
+ * §6.3: unregister a machine. A POOL member also rotates: the removed machine holds the shared
+ * secret, so nothing but a new one keeps it out. A legacy env-token row (P-8) holds no pool secret
+ * and keeps the plain delete.
+ */
+async function handleMachineRemove(req, res, url, params) {
+  const instanceId = decodeURIComponent((params && (params['1'] || params.id)) || '');
+  if (!instanceId) return _send(res, 400, { ok: false, error: 'machine_id_required' });
+  const pool = _pool();
+  const rows = _deps.db.listMachineRows() || [];
+  if (!pool.hasPool() || !pool.isMember(instanceId)) {
+    // WP-2: the machine writes are DB-owner mutations (db.js's DB_OWNER_MUTATION_ACTIONS), so the
+    // handle here is the owner-client Proxy and this call is a PROMISE. Await it before computing
+    // `removed` — a synchronous read of the result would report "0 removed" for every real delete.
+    const removed = await _deps.db.deleteMachineRow(instanceId);
+    if (_deps.registry && typeof _deps.registry.noteRegistryChanged === 'function') _deps.registry.noteRegistryChanged();
+    return _send(res, 200, { ok: true, removed: Number(removed) || 0 });
+  }
+  await ready();
+  const selfId = _instanceId();
+  // P-6: capture the OLD credential headers BEFORE rotate(). Every remaining member still holds the
+  // old secret, so it is the only credential that can authenticate the rotation itself.
+  const oldHeaders = new Map();
+  for (const row of rows) {
+    if (row.instanceId && row.instanceId !== instanceId) oldHeaders.set(row.instanceId, _peerHeadersFor(row.instanceId));
+  }
+  const removed = await _deps.db.deleteMachineRow(instanceId);
+  await pool.removeMember(instanceId);
+  const version = await pool.bumpRoster(selfId);
+  const roster = _rosterMembers();
+  const targets = roster.filter((member) => member.instanceId !== selfId);
+  // P-5 first: the remaining members learn the new membership set while the old secret still works.
+  for (const target of targets) {
+    await _postToTarget(target, '/api/pool/roster', { version, members: roster }, oldHeaders.get(target.instanceId));
+  }
+  // P-6: then the secret itself changes, and each reachable member is told (with the OLD credential).
+  const newToken = await pool.rotate();
+  const rotated = [];
+  const unreachable = [];
+  for (const target of targets) {
+    const ok = await _postToTarget(target, '/api/pool/rotate', { token: newToken }, oldHeaders.get(target.instanceId));
+    if (ok) rotated.push(target.instanceId);
+    else unreachable.push(target.instanceId);
+  }
+  if (_deps.registry && typeof _deps.registry.noteRegistryChanged === 'function') _deps.registry.noteRegistryChanged();
+  // §6.3/AC-3d: `unreachable` members are the ones the UI warns about — they still hold the OLD
+  // secret and must re-pair (the old one stops being accepted after lib/machine-pool.js's 10 min
+  // rotation grace, ROTATION_GRACE_MS).
+  return _send(res, 200, { ok: true, removed: Number(removed) || 0, rotated, unreachable });
+}
+
+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) },
+  ]);
+}
+
+module.exports = {
+  configure,
+  register,
+  ready,
+  handleMachinesList,
+  handleMachinesCreate,
+  handleMachinesPair,
+  handleMachineRemove,
+};

package/template/coding-task-manager/lib/api/misc-ops.js

@@ -32,9 +32,19 @@
 // rounds out the DISPATCH-ONLY additions.
 
 const { registerApiRoutes } = require('../api-router');
+const remoteMachineProxy = require('../remote-machine-proxy');
 
 let _deps = null;
 
+// Remote machine hub WP-4 (§6.5): a picker request naming another machine (?machine= or
+// X-CTM-Machine) is answered from that box; every other request is the unchanged local handler.
+function _machineRouted(route, local) {
+  return (req, res, url) => (remoteMachineProxy.isMachineRouted(req, url)
+    ? remoteMachineProxy.maybeProxyMachineRequest(req, res, url, { route })
+      .then((handled) => (handled ? undefined : local(req, res, url)))
+    : local(req, res, url));
+}
+
 function configure({
   apiCtmCoopJobsStatus,
   apiCtmSessionRowsStatus,
@@ -59,6 +69,7 @@ function configure({
   apiDeleteHook,
   apiRestartCtm,
   restartGuardSnapshot,
+  proxyPreflight,
   wss,
   clientBuildDiagnosticDetails,
   attachedSessionIds,
@@ -93,6 +104,7 @@ function configure({
     apiDeleteHook,
     apiRestartCtm,
     restartGuardSnapshot,
+    proxyPreflight,
     wss,
     clientBuildDiagnosticDetails,
     attachedSessionIds,
@@ -213,9 +225,12 @@ async function handleConversationDebtRedrive(req, res, url) {
 
 function register() {
   registerApiRoutes('restart', [
-    { method: 'GET', path: '/api/restart/ctm/preflight', handler: (req, res) => {
+    { method: 'GET', path: '/api/restart/ctm/preflight', handler: async (req, res) => {
+      // WP-3 D-10 (model-proxy-survives-ctm-restart): the model-proxy verdict is a live probe of the
+      // proxy's record and /_health, so it is awaited here and injected into the otherwise-sync snapshot.
+      const proxy = await _deps.proxyPreflight();
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, preflight: _deps.restartGuardSnapshot().preflight }));
+      res.end(JSON.stringify({ ok: true, preflight: _deps.restartGuardSnapshot(Date.now(), { proxy }).preflight }));
     } },
   ]);
   registerApiRoutes('misc-ops', [
@@ -248,9 +263,9 @@ function register() {
       handler: (req, res, url) => handleWorkspaceSessionsDelete(req, res, url),
     },
     { method: 'DELETE', prefix: '/api/workspaces/', handler: (req, res, url) => handleWorkspaceDelete(req, res, url) },
-    { method: 'GET', path: '/api/projects', handler: (req, res) => _deps.apiGetProjects(req, res) },
-    { method: 'GET', path: '/api/path-suggest', handler: (req, res, url) => _deps.apiPathSuggest(req, res, url) },
-    { method: 'POST', path: '/api/path-status', handler: (req, res) => _deps.apiPathStatus(req, res) },
+    { method: 'GET', path: '/api/projects', handler: _machineRouted('GET /api/projects', (req, res) => _deps.apiGetProjects(req, res)) },
+    { method: 'GET', path: '/api/path-suggest', handler: _machineRouted('GET /api/path-suggest', (req, res, url) => _deps.apiPathSuggest(req, res, url)) },
+    { method: 'POST', path: '/api/path-status', handler: _machineRouted('POST /api/path-status', (req, res) => _deps.apiPathStatus(req, res)) },
     { method: 'GET', path: '/api/rules', handler: (req, res, url) => _deps.apiGetRules(req, res, url) },
     { method: 'PUT', path: '/api/rules', handler: (req, res) => _deps.apiPutRules(req, res) },
     { method: 'GET', path: '/api/rules/list', handler: (req, res) => _deps.apiListRules(req, res) },

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

@@ -2,21 +2,24 @@
 
 // Round-3 WP-5 T3 group 5 (design doc §5 D-1/D-3/D-8, §8 WP-5, §9.5 S-42):
 // small NEW module for the coding-CLI provider OAuth login broker cluster --
-// GET /api/providers/login-state and POST /api/providers/:id/login. This is
+// GET /api/providers/login-state, POST /api/providers/:id/login and
+// POST /api/providers/:id/login/code. This is
 // a distinct "providers" concept from lib/api/setup.js's LLM-provider
 // API-key setup (setup/providers, setup/save-provider, etc.): providerLoginBroker
 // tracks OAuth login flows for coding-agent CLIs (claude/codex/gemini), not
 // API-key-based model providers, so it gets its own module rather than
-// extending setup.js. DISPATCH-ONLY: both routes call providerLoginBroker
-// methods directly, no server.js function bodies to move.
+// extending setup.js. DISPATCH-ONLY: every route calls a providerLoginBroker
+// method directly, no server.js function bodies to move.
 //
-// The POST route carries a regex (`/^\/api\/providers\/([^/]+)\/login$/`)
+// The POST routes carry a regex (`/^\/api\/providers\/([^/]+)\/login$/` and
+// `/^\/api\/providers\/([^/]+)\/login\/code$/`)
 // the legacy chain's own scanner never counted (the `[^/]` character class
 // breaks bin/generate-route-golden.js's REGEX_RE, so this spec never showed
 // up in lint/route-golden.json's chain -- see lib/api/sessions.js's group-5
 // header for the same gap on /api/sessions/:id/interrupt etc.).
 
 const { registerApiRoutes } = require('../api-router');
+const remoteMachineProxy = require('../remote-machine-proxy');
 
 let _deps = null;
 
@@ -24,6 +27,24 @@ function configure({ providerLoginBroker, readJsonRequestBody } = {}) {
   _deps = { providerLoginBroker, readJsonRequestBody };
 }
 
+// WP-3 (remote-agent-sign-in-from-hub-browser-2026-10-25.html §5 D-7/D-9, §6): a sign-in request
+// that names ANOTHER machine (`?machine=` / `X-CTM-Machine`) is answered from that box over the
+// peer-bearer leg — the wrapper shape lib/api/misc-ops.js:41 uses. A request naming no machine
+// (or THIS instance) is the unchanged local handler, byte for byte.
+//
+// Unlike misc-ops' routes (all exact paths), two of these are regex routes, so the wrapper
+// forwards the router's `params` (api-router.js:136) as well: dropping it would read `params['1']`
+// off undefined. `...args` keeps the local call identical to a directly-registered handler.
+function _machineRouted(route, local) {
+  return (...args) => {
+    const [req, res, url] = args;
+    return remoteMachineProxy.isMachineRouted(req, url)
+      ? remoteMachineProxy.maybeProxyMachineRequest(req, res, url, { route })
+        .then((handled) => (handled ? undefined : local(...args)))
+      : local(...args);
+  };
+}
+
 // WP-0: getState() now awaits the CLI account probe (lib/coding-agent-auth), so both
 // handlers are async — the api-router awaits handler promises before falling through.
 async function handleProvidersLoginState(req, res) {
@@ -52,13 +73,39 @@ async function handleProviderLogin(req, res, providerIdRaw) {
   res.end(JSON.stringify(result));
 }
 
+// WP-1 (D-4/D-5/D-6): the code-return route. Body shaping only — the broker owns every
+// validation (open flow, live tab, `codeEntry === 'paste'`, normalisation, state match) and
+// the single PTY write, so this handler never decides anything about a code. An unreadable or
+// oversized body simply arrives as `code: ''`, which the broker refuses as `code_format_invalid`.
+async function handleProviderLoginCode(req, res, providerIdRaw) {
+  const providerId = decodeURIComponent(providerIdRaw || '');
+  let body = {};
+  if (_deps.readJsonRequestBody) {
+    try {
+      body = (await _deps.readJsonRequestBody(req, { limitBytes: 16 * 1024 })) || {};
+    } catch (error) {
+      // HANDLE: an unreadable/oversized body is not a 500 — the missing code is the refusal.
+      body = {};
+    }
+  }
+  const code = body && typeof body === 'object' && typeof body.code === 'string' ? body.code : '';
+  const result = await _deps.providerLoginBroker.submitCode(providerId, { code });
+  res.writeHead(result.status || 500, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(result));
+}
+
 function register() {
   registerApiRoutes('providers', [
-    { method: 'GET', path: '/api/providers/login-state', handler: (req, res) => handleProvidersLoginState(req, res) },
+    { method: 'GET', path: '/api/providers/login-state', handler: _machineRouted('GET /api/providers/login-state', (req, res) => handleProvidersLoginState(req, res)) },
     {
       method: 'POST',
       regex: /^\/api\/providers\/([^/]+)\/login$/,
-      handler: (req, res, url, params) => handleProviderLogin(req, res, params['1']),
+      handler: _machineRouted('POST /api/providers/:id/login', (req, res, url, params) => handleProviderLogin(req, res, params['1'])),
+    },
+    {
+      method: 'POST',
+      regex: /^\/api\/providers\/([^/]+)\/login\/code$/,
+      handler: _machineRouted('POST /api/providers/:id/login/code', (req, res, url, params) => handleProviderLoginCode(req, res, params['1'])),
     },
   ]);
 }

package/template/coding-task-manager/lib/api/resume-from-store.js

@@ -56,6 +56,31 @@ async function handleResumeFromStore(req, res, deps = _deps) {
   const cwd = _firstText(ctm.cwd, ctm.project_path, agent.project_path, body.cwd);
   if (!cwd) return send(res, 409, { error: 'no_cwd', message: 'No working directory is known for this session.' });
 
+  // D-5 (session-exit-close-truth §5): the rebuild is proven safe, never assumed. Ask the resume
+  // ladder -- exactly as the resume-rung route does -- whether the original transcript is still on
+  // this machine, and refuse the lossy reconstruction when it is. Only the ladder's refusal to
+  // answer (a throw) refuses too; an unrecognized rung is not evidence of an intact transcript.
+  try {
+    const resolve = deps.resolveResumeRung || resolveResumeRungOffThread;
+    const ladder = await resolve({ ..._ladderInput(identity, ctm.id, provider), dbPath: deps.getDbPath(), trashRoot: deps.trashRoot });
+    const rung = String((ladder && ladder.rung) || '');
+    if ((rung === 'native' && ladder.offerStoreFirst !== true) || rung === 'restore' || rung === 'trash') {
+      return send(res, 409, {
+        error: 'native_transcript_available',
+        rung,
+        message: 'The original transcript is still on this machine. Resume the session instead.',
+      });
+    }
+  } catch (error) {
+    // HANDLE: the ladder could not answer (read pool down, probes failed). Refuse rather than
+    // reconstruct on a guess; the card's "Check again" re-asks.
+    console.error('[resume-from-store] rung check failed:', String((error && error.message) || error));
+    return send(res, 409, {
+      error: 'rung_unknown',
+      message: 'CTM could not check whether the original transcript still exists. Try again.',
+    });
+  }
+
   try {
     const build = deps.buildResumeContext || buildResumeContextOffThread;
     const plan = await build({ dbPath: deps.getDbPath(), ctmSessionId: ctm.id });