create-walle 0.10.2 → 0.10.3

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

@@ -0,0 +1,118 @@
+'use strict';
+
+// WP-0/WP-1 (docs/fleet-auto-update-pooled-machines-2026-10-26.html §6, §8 WP-0/WP-1, §9 S-4/S-6):
+// the fleet route cluster.
+//
+//   GET  /api/fleet/status                     (read, peerControl)  -> { ok, ...readFleetStatus() }
+//   POST /api/fleet/bundle?to=<40-hex sha>     (admin, peerControl) -> 202 | 400 | 409 | 413
+//
+// This is the BOX side of the fleet: a hub asks each member "what is your checkout?" and decides
+// eligibility from the answer (channel git + branch main + clean tree, per the lead's 2026-10-26
+// decision — there is no `autoUpdate` setting), then PUSHES the fast-forward bundle it built
+// (`git bundle create - <boxHead>..<target>`) as the raw body of the bundle route (D-3). The box
+// verifies, parks it in `refs/fleet/incoming`, and hands the apply to the detached helper — the hub
+// never runs a command on the box (D-4).
+//
+// Same shape as lib/api/machine-pool.js and lib/api/machines.js: NEW surface, so there is no legacy
+// handleApi branch to delete and tests-integration/api-router-parity.test.js's no-dual-dispatch rule
+// is satisfied by construction. The auth rows live in lib/auth-rules.js (`read` + peerControl on the
+// status GET, `admin` + peerControl on the bundle POST — NOT loopbackOnly, because a hub on another
+// machine reaches them over the peer bearer).
+
+const path = require('node:path');
+const { registerApiRoutes } = require('../api-router');
+const fleetUpdate = require('../fleet-update');
+const originFollower = require('../fleet-origin-follower');
+const { createResolverTick } = require('../fleet-resolver-tick');
+const { loadTargetLandingConfig } = require('../landing/config');
+
+// The repo root that contains `coding-task-manager/` — `lib/api/` is three levels below it.
+const DEFAULT_REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+let _deps = null;
+// WP-3 (docs/fleet-origin-main-sync-skill-2026-10-31.html §5 R-8, §6.5): the CTM origin follower's
+// handle, so a re-configure (dev reload, tests) stops the previous timer instead of stacking one.
+let _follower = null;
+
+function configure({ repoRoot = DEFAULT_REPO_ROOT, dataDir = '', port = null, runningSha = '', sessions = () => [], guardSnapshot = null, sendJsonResponse, resolverEffects = null } = {}) {
+  _deps = { repoRoot, dataDir, port, runningSha, sessions, guardSnapshot, sendJsonResponse };
+  // R-8: this box pulls origin itself. The follower no-ops on a dev instance, on a repository with no
+  // `landing.publish`, and on a checkout that is not on `main` (see lib/fleet-origin-follower.js), so
+  // arming it here is safe for every boot. A throw here would take the whole server down over an
+  // optional background timer, so it is reported and dropped.
+  if (_follower && typeof _follower.stop === 'function') _follower.stop();
+  // §13.4 R-R1/R-R7 (WP-8): when server.js hands over the resolver effects, arm the follower's
+  // per-tick resolver hooks from the TARGET tree's normalized `landing.publish`. The config is read
+  // exactly the way the follower reads it; a repository that cannot be read (or has no publish block)
+  // simply gets a follower with no resolver — never a boot failure.
+  let resolverTick = null;
+  if (resolverEffects) {
+    try {
+      const config = loadTargetLandingConfig(repoRoot);
+      if (config && config.publish) {
+        resolverTick = createResolverTick({ repoRoot, publish: config.publish, deps: resolverEffects });
+      }
+    } catch (error) {
+      // REPORT: the resolver half is optional; the follower and the routes below are not.
+      console.warn(`[fleet] resolver tick not wired: ${(error && error.message) || error}`);
+    }
+  }
+  try {
+    _follower = originFollower.start({ repoRoot, dataDir, port, resolverTick });
+  } catch (error) {
+    // REPORT: the follower is optional; the fleet routes below are not. Never fail boot for it.
+    console.warn(`[fleet] origin follower not started: ${(error && error.message) || error}`);
+  }
+}
+
+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);
+}
+
+/** The current session list, from the SAME source /api/instance/update-gate feeds the guard. */
+function _sessions() {
+  const source = _deps && _deps.sessions;
+  if (typeof source !== 'function') return [];
+  const value = source();
+  return value ? Array.from(value) : [];
+}
+
+async function handleFleetStatus(req, res) {
+  const status = await fleetUpdate.readFleetStatus({
+    repoRoot: (_deps && _deps.repoRoot) || DEFAULT_REPO_ROOT,
+    dataDir: (_deps && _deps.dataDir) || '',
+    runningSha: (_deps && _deps.runningSha) || '',
+    sessions: _sessions(),
+    guardSnapshot: (_deps && _deps.guardSnapshot) || null,
+  });
+  return _send(res, 200, { ok: true, ...status });
+}
+
+/** POST /api/fleet/bundle?to=<40-hex sha> — the hub's push leg; the body IS the git bundle (D-3). */
+async function handleFleetBundle(req, res) {
+  const url = new URL(req.url, 'http://localhost');
+  const result = await fleetUpdate.acceptFleetBundle(req, {
+    to: String(url.searchParams.get('to') || ''),
+    repoRoot: (_deps && _deps.repoRoot) || DEFAULT_REPO_ROOT,
+    dataDir: (_deps && _deps.dataDir) || require('../data-dir').getDataDir(),
+    port: (_deps && _deps.port) || null,
+  });
+  return _send(res, result.status, result.body);
+}
+
+function register() {
+  registerApiRoutes('fleet', [
+    { method: 'GET', path: '/api/fleet/status', handler: (req, res) => handleFleetStatus(req, res) },
+    { method: 'POST', path: '/api/fleet/bundle', handler: (req, res) => handleFleetBundle(req, res) },
+  ]);
+}
+
+module.exports = {
+  configure,
+  register,
+  handleFleetBundle,
+  handleFleetStatus,
+};

package/template/coding-task-manager/lib/api/hub-bridge.js

@@ -0,0 +1,243 @@
+'use strict';
+
+// WP-0/WP-2 (docs/remote-session-hub-bridge-2026-10-30.html §6.2, §8 WP-0/WP-2): the HTTP surface of
+// the hub-bridge lane.
+//
+//   BOX side (loopback only, WP-0):
+//     GET  /api/hub-bridge/status[?session=<ctmSessionId>]
+//          -> { role:'box'|'none', hubs:[{hubInstanceId,hubDisplayName,connected}], poolMembers,
+//               self:{instanceId,displayName}, session?:{hubInstanceId,hubDisplayName,connected}|null }
+//     POST /api/hub-bridge/call    body { callerSessionId, op, args, deadlineMs? } -> 200 { ok, result|error }
+//
+//   HUB side (user principal only, WP-2 — lib/auth-rules.js rows are `admin` + stepUp 'remote' and
+//   deliberately carry NO peerControl, so the box's peer bearer can never mint a grant, R-4):
+//     GET    /api/hub-bridge/grants              -> { grants, pending }   (Grant rows carry scope/always)
+//     POST   /api/hub-bridge/grants              body { machineId, callerSessionId, tier, ttlSec?, always? }
+//                                                callerSessionId is a uuid — or '*' for every session of
+//                                                that machine (D-1/D-3); always:true is durable (D-4).
+//     DELETE /api/hub-bridge/grants              body { machineId, callerSessionId, tier? }
+//     POST   /api/hub-bridge/pending/:id/deny
+//     GET    /api/hub-bridge/trust               -> the R-11 trust file (incl. its durable `grants`)
+//     PUT    /api/hub-bridge/trust               body { default?, machines? }  (never writes `grants`)
+//     GET    /api/hub-bridge/audit?machineId=&limit=  -> { entries }   (R-9, digest only)
+//
+// A BRIDGE error on status/call is DATA with HTTP 200 (the design says so explicitly); only a
+// malformed JSON body is a 400. The hub-side admin routes answer 400 for a bad body and 200 otherwise.
+//
+// Same configure()/register() shape as lib/api/machine-pool.js; the handler bodies live in
+// lib/hub-bridge-box.js's singleton (box side) and lib/hub-bridge-access.js's singleton (hub side).
+
+const { registerApiRoutes } = require('../api-router');
+
+let _deps = null;
+
+function configure({ status, call, readJsonRequestBody, sendJsonResponse, access, reconcile } = {}) {
+  _deps = { status, call, readJsonRequestBody, sendJsonResponse, access, reconcile };
+}
+
+/** The access/trust/grant store (lib/hub-bridge-access.js), injected at boot or lazily required. */
+function _access() {
+  if (_deps && _deps.access) return _deps.access;
+  return require('../hub-bridge-access');
+}
+
+function _send(res, statusCode, payload) {
+  if (_deps && typeof _deps.sendJsonResponse === 'function') return _deps.sendJsonResponse(res, statusCode, payload);
+  const body = JSON.stringify(payload || {});
+  res.writeHead(statusCode, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+function _readJson(req) {
+  if (_deps && typeof _deps.readJsonRequestBody === 'function') return _deps.readJsonRequestBody(req);
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8');
+      if (!raw) return resolve({});
+      try {
+        resolve(JSON.parse(raw));
+      } catch {
+        reject(new Error('invalid_json'));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+/** Read a JSON body, or null when it is malformed (the caller answers 400). */
+async function _body(req) {
+  try {
+    const parsed = await _readJson(req);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return null;
+  }
+}
+
+function _badRequest(res, code, message) {
+  return _send(res, 400, { ok: false, error: { code, message } });
+}
+
+/** Map a named refusal thrown by lib/hub-bridge-access.js onto an HTTP status. */
+function _accessFailure(res, error) {
+  const code = String((error && error.code) || 'hub_bridge_error');
+  const status = code === 'trust_value_invalid' || code === 'grant_invalid' ? 400 : 500;
+  return _send(res, status, { ok: false, error: { code, message: String((error && error.message) || code) } });
+}
+
+/**
+ * R-5 (§6.1): the box status. An optional `?session=<ctmSessionId>` asks "is THIS session's creator
+ * hub connected" — the box resolves the record and matches it against its live links. A missing/blank
+ * query passes nothing through, so the body carries no `session` key at all (a reader tells "no
+ * question" from "no record" by its presence). Never a 4xx for a bad id.
+ */
+async function handleStatus(req, res, url) {
+  const session = String(url?.searchParams?.get('session') || '').trim();
+  const status = _deps && typeof _deps.status === 'function'
+    ? await _deps.status(session ? { session } : {})
+    : { role: 'none', hubs: [] };
+  return _send(res, 200, status);
+}
+
+async function handleCall(req, res) {
+  const body = await _body(req);
+  if (body === null) {
+    return _send(res, 400, { ok: false, error: { code: 'invalid_json', message: 'request body is not valid JSON' } });
+  }
+  const result = typeof _deps?.call === 'function'
+    ? await _deps.call({
+      callerSessionId: body.callerSessionId,
+      op: body.op,
+      args: body.args,
+      // WP-5 (R-12): the target machine rides the body TOP-LEVEL (an instance id or a display name),
+      // never inside `op`'s args — the op args are the machine's business, not the router's.
+      machine: body.machine,
+      deadlineMs: body.deadlineMs,
+    })
+    : { ok: false, error: { code: 'hub_unreachable', message: 'bridge_not_wired' } };
+  return _send(res, 200, result);
+}
+
+async function handleListGrants(req, res, url) {
+  const access = _access();
+  const machineId = String(url?.searchParams?.get('machineId') || '');
+  return _send(res, 200, {
+    grants: access.listGrants(),
+    pending: access.listPending(machineId ? { machineId } : {}),
+  });
+}
+
+async function handleCreateGrant(req, res) {
+  const body = await _body(req);
+  if (body === null) return _badRequest(res, 'invalid_json', 'request body is not valid JSON');
+  try {
+    // D-1/D-4: `always === true` is the durable answer; anything else is the in-memory hour grant.
+    // `callerSessionId` may be '*' (every session of the machine). Both are async writes now.
+    const grant = await _access().grantGrants({
+      machineId: body.machineId,
+      callerSessionId: body.callerSessionId,
+      tier: body.tier,
+      ttlSec: body.ttlSec,
+      always: body.always === true,
+    });
+    return _send(res, 200, { ok: true, grant });
+  } catch (error) {
+    return _accessFailure(res, error);
+  }
+}
+
+async function handleRevokeGrant(req, res) {
+  const body = await _body(req);
+  if (body === null) return _badRequest(res, 'invalid_json', 'request body is not valid JSON');
+  // D-4: drops the in-memory TTL rows AND the durable rows; the trust file is rewritten only when a
+  // durable row was actually removed.
+  const removed = await _access().revokeGrants({
+    machineId: body.machineId,
+    callerSessionId: body.callerSessionId,
+    tier: body.tier,
+  });
+  return _send(res, 200, { ok: true, removed });
+}
+
+async function handleDenyPending(req, res, url, params) {
+  const id = String((params && params.id) || '');
+  const denied = _access().denyPending(id);
+  if (!denied) return _send(res, 404, { ok: false, error: { code: 'pending_not_found', message: `no pending request ${id}` } });
+  return _send(res, 200, { ok: true, denied: true });
+}
+
+async function handleGetTrust(req, res) {
+  return _send(res, 200, _access().readTrust());
+}
+
+/**
+ * WP-5 (R-12): a successful trust write is the moment the mesh's desired set can change, so the mesh
+ * reconciles at once instead of waiting up to 30 s for its tick. Best-effort by construction: the
+ * trust file is already written and answered, and a mesh fault must never turn that into a 500.
+ */
+function _reconcileMesh() {
+  const reconcile = _deps && _deps.reconcile;
+  if (typeof reconcile !== 'function') return;
+  try {
+    const pending = reconcile();
+    if (pending && typeof pending.catch === 'function') {
+      pending.catch(() => {
+        // REPORT (console only): reconcile never rejects by contract; a rejection is a mesh bug, not
+        // a trust-write failure, and the trust response has already been sent.
+        console.warn('[hub-bridge] mesh reconcile after trust write failed');
+      });
+    }
+  } catch (error) {
+    console.warn(`[hub-bridge] mesh reconcile after trust write failed: ${error?.message || error}`);
+  }
+}
+
+async function handlePutTrust(req, res) {
+  const body = await _body(req);
+  if (body === null) return _badRequest(res, 'invalid_json', 'request body is not valid JSON');
+  try {
+    const written = await _access().writeTrust({ default: body.default, machines: body.machines });
+    _reconcileMesh();
+    return _send(res, 200, written);
+  } catch (error) {
+    return _accessFailure(res, error);
+  }
+}
+
+async function handleAudit(req, res, url) {
+  const machineId = String(url?.searchParams?.get('machineId') || '');
+  const limit = Number(url?.searchParams?.get('limit')) || undefined;
+  return _send(res, 200, { entries: await _access().recentAudit({ machineId, limit }) });
+}
+
+function register() {
+  registerApiRoutes('hub-bridge', [
+    { method: 'GET', path: '/api/hub-bridge/status', handler: (req, res, url) => handleStatus(req, res, url) },
+    { method: 'POST', path: '/api/hub-bridge/call', handler: (req, res) => handleCall(req, res) },
+    // WP-2 (R-4/R-5/R-11/R-9): the hub-side admin surface. All user-principal only (auth-rules rows
+    // carry NO peerControl), so a box's peer bearer can neither read nor mint a grant.
+    { method: 'GET', path: '/api/hub-bridge/grants', handler: (req, res, url) => handleListGrants(req, res, url) },
+    { method: 'POST', path: '/api/hub-bridge/grants', handler: (req, res) => handleCreateGrant(req, res) },
+    { method: 'DELETE', path: '/api/hub-bridge/grants', handler: (req, res) => handleRevokeGrant(req, res) },
+    { method: 'POST', regex: /^\/api\/hub-bridge\/pending\/(?<id>[^/]+)\/deny$/, handler: (req, res, url, params) => handleDenyPending(req, res, url, params) },
+    { method: 'GET', path: '/api/hub-bridge/trust', handler: (req, res) => handleGetTrust(req, res) },
+    { method: 'PUT', path: '/api/hub-bridge/trust', handler: (req, res) => handlePutTrust(req, res) },
+    { method: 'GET', path: '/api/hub-bridge/audit', handler: (req, res, url) => handleAudit(req, res, url) },
+  ]);
+}
+
+module.exports = {
+  configure,
+  register,
+  handleStatus,
+  handleCall,
+  handleListGrants,
+  handleCreateGrant,
+  handleRevokeGrant,
+  handleDenyPending,
+  handleGetTrust,
+  handlePutTrust,
+  handleAudit,
+};

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

@@ -89,12 +89,19 @@ function workerNoticeBody(route, payload, res, verdict) {
   const nudge = isStop
     ? workerNotices.stopNudge(leadId, { backgroundTasks: payload.background_tasks, sessionCrons: payload.session_crons })
     : null;
-  if (!drained.notices.length && !nudge) return undefined;
+  // R4 (WP-1): the receiver's per-task quiet notices for this Stop, in the order it rendered them.
+  const bgNudges = isStop && verdict && Array.isArray(verdict.backgroundNudges) ? verdict.backgroundNudges : [];
+  if (!drained.notices.length && !nudge && !bgNudges.length) return undefined;
   // §7: one session_diagnostics row per nudge, so the RC-1 census can count leads that were held.
   if (nudge && typeof _deps.recordSessionDiagnostic === 'function') {
     try { _deps.recordSessionDiagnostic(leadId, 'lead-stop-nudge', { workers: nudge.workers, background_running: false }); }
     catch (err) { console.error('[worker-notices] lead-stop-nudge diagnostic failed:', err && err.message); }
   }
+  // §7 (WP-1): the same census row for the quiet-background ask, so M1/M2 can count it.
+  if (bgNudges.length && typeof _deps.recordSessionDiagnostic === 'function') {
+    try { _deps.recordSessionDiagnostic(leadId, 'background-quiet-nudge', { ids: bgNudges.map((n) => n.id), count: bgNudges.length }); }
+    catch (err) { console.error('[worker-notices] background-quiet-nudge diagnostic failed:', err && err.message); }
+  }
   if (drained.notices.length) {
     if (res && typeof res.once === 'function') {
       res.once('finish', () => drained.commit());
@@ -105,6 +112,7 @@ function workerNoticeBody(route, payload, res, verdict) {
   const notices = drained.notices.map((n) => ({ receipt_id: n.receipt_id, text: n.text }));
   // A nudge is not a receipt-backed notice, so it carries no receipt_id.
   if (nudge) notices.push({ receipt_id: null, text: nudge.text });
+  for (const n of bgNudges) notices.push({ receipt_id: null, text: n.text });
   return { notices };
 }