create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/api/agent-bundles.js

@@ -0,0 +1,436 @@
+'use strict';
+
+// WP-2 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-1/D-2/D-5, §6.2, §6.3): the BOX-side
+// bundle ingress — the three routes a hub calls with its peer bearer to hand this machine the skills
+// and plugins it must run a forwarded session with.
+//
+//   POST /api/agent-bundles/missing          { blobs: [hex…] }  -> 200 { missing }
+//   POST /api/agent-bundles/blobs            { blobs: [{hash, data(base64)}] }
+//                                                              -> 200 { stored, present }   (WP-4/§6.2, D-6)
+//   PUT  /api/agent-bundles/blobs/<hex>      raw bytes          -> 201 { stored:true } | 200 { stored:false }
+//   PUT  /api/agent-bundles/manifests/<treeHash>  JSON         -> 201 { treeHash, materialized:true }
+//                                                              | 200 { treeHash, materialized:false }
+//   GET  /api/agent-skills/inventory         the hub's read   -> 200 { platform, checkedAt, roots,
+//                                                              skills, base }   (WP-7/§6.2, D-11)
+//   GET  /api/agent-skills/export            ?agent&name      -> 200 { agent, name, itemHash, files }
+//   POST /api/agent-skills/retire            { agent, name, expectHash } -> 200 { retiredTo }
+//                                                              (WP-8/§6.2, D-12/D-13)
+//
+// Storage and verification are lib/agent-bundle/store.js's (blob re-hash, manifest tree-hash check,
+// materialization); this module owns only the wire: body limits, the status table, and the peer
+// identity read.
+//
+// Like lib/api/host-stats.js and lib/api/machines.js (and unlike the lib/api/*.js extraction slices)
+// this is NEW surface: the handler bodies live here, 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. Auth is NOT evaluated here: lib/auth-rules.js carries the three `admin` +
+// `peerControl: true` rows, and a route with no rule is 403 auth_rule_missing by design — so the rule
+// rows and these registrations must land together.
+//
+// IDENTITY: every route refuses a caller with no authenticated peer identity (403
+// `agent_bundle_peer_unidentified`) before it reads a body. The peer is `req.ctmAuth.peerInstanceId`
+// (the same read server.js's sync routes use) — never a field from the request — so a bundle can
+// only ever be written under the identity that actually authenticated.
+const os = require('os');
+const { registerApiRoutes } = require('../api-router');
+const store = require('../agent-bundle/store');
+// WP-5 (docs/remote-agent-skills-bundles-2026-10-25.html §8 WP-5 row): a manifest PUT that
+// MATERIALIZED a tree is one of exactly two moments the box store grows, so it is one of exactly
+// two moments a sweep is scheduled (the other is boot, in server.js). Event-driven, never a timer.
+const bundleGc = require('../agent-bundle/gc');
+// WP-6 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-14, §8 WP-6 row): the same PUT is also
+// the moment the box's `$HOME/.agents/skills` copies are brought in line with the tree it just
+// pointed at — on EVERY successful PUT, because the hub pointer moves on a re-PUT too.
+const bundleCodexInstall = require('../agent-bundle/codex-install');
+// WP-7 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-11, §6.2): the RETURN path — the box
+// reports the skills it already holds so the hub can classify them instead of copying anything.
+const bundleInventory = require('../agent-bundle/inventory');
+// WP-8 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-12/D-13, §6.2): the ONE-SKILL
+// exchange — `export` ships one box item's bytes to the hub, `retire` MOVES that item aside on the box
+// when the hub now owns the copy. Policy lives in the lib; this module owns only the wire.
+const skillTransfer = require('../agent-bundle/skill-transfer');
+const { MAX_ENTRIES } = require('../agent-bundle/build');
+
+const { AgentBundleError } = store;
+
+// §6.2 body limits. MAX_ENTRIES mirrors build.js: the hub cannot produce a longer list, so the box
+// answers the same way it would to an unparseable body rather than reading unbounded input.
+const MAX_MISSING_BODY_BYTES = 1024 * 1024;
+// WP-4/§6.2/D-6: the batch body is JSON + base64, so it is capped at its own limit rather than
+// MAX_BLOB_BYTES. A 4 MiB raw batch (D-7) base64-grows to ~5.4 MiB, under this cap.
+const MAX_BATCH_BODY_BYTES = 8 * 1024 * 1024;
+const MAX_BLOB_BYTES = 25 * 1024 * 1024;
+const MAX_MANIFEST_BODY_BYTES = 4 * 1024 * 1024;
+
+const ROUTE_MISSING = 'POST /api/agent-bundles/missing';
+const ROUTE_BLOB_BATCH = 'POST /api/agent-bundles/blobs';
+const ROUTE_BLOB = 'PUT /api/agent-bundles/blobs/:sha256';
+const ROUTE_MANIFEST = 'PUT /api/agent-bundles/manifests/:treeHash';
+const ROUTE_INVENTORY = 'GET /api/agent-skills/inventory';
+const ROUTE_SKILL_EXPORT = 'GET /api/agent-skills/export';
+const ROUTE_SKILL_RETIRE = 'POST /api/agent-skills/retire';
+
+// One table: the store's error codes are the wire's codes (D-5 wording), and nothing else maps to a
+// 4xx. An unrecognized error is a 500 `internal_error`, server.js's own global shape.
+const STATUS_BY_CODE = {
+  agent_bundle_path_invalid: 422,
+  agent_bundle_blob_hash_mismatch: 422,
+  agent_bundle_tree_hash_mismatch: 422,
+  agent_bundle_blobs_missing: 409,
+  agent_bundle_peer_unidentified: 403,
+};
+
+let _deps = null;
+
+function configure({
+  dataDir,
+  // WP-8: the box user's home, injected rather than `os.homedir()`-at-call-site so a route test can
+  // point the export/retire legs at a temp HOME. In production it is the process home, which the
+  // spawner already sets to the box user's.
+  homeDir = null,
+  readJsonRequestBody,
+  sendJsonResponse,
+  errorSink = null,
+  // WP-5: both are injected rather than required at call time so the route test can observe the
+  // trigger without a timer, a flag, or a spy on the store.
+  scheduleGc = null, // (dataDir, deps) => Promise<result>; defaults to the real single-flight sweep
+  sessionExists = null, // (ctmSessionId) => Promise<boolean>; server.js wires the box's DB read
+  // WP-6: same seam shape as scheduleGc — the route test observes the trigger without a timer.
+  scheduleCodexInstall = null, // (dataDir, deps) => Promise<result>; defaults to the real single-flight run
+  // WP-3 (agent-bundle-darwin-readonly-rename-2026-10-27.html §16 D-8 T1): the hub pointer for this
+  // peer just moved (or a tree materialized), so any live session still running the OLD tree is now
+  // drifted. Injected, never required at call time — the module stays wire-only and testable.
+  onBundlePointerMoved = null, // (peerInstanceId) => void
+} = {}) {
+  _deps = { dataDir, homeDir, readJsonRequestBody, sendJsonResponse, errorSink, scheduleGc, sessionExists, scheduleCodexInstall, onBundlePointerMoved };
+}
+
+/** The box user's home, for the WP-8 export/retire legs. */
+function _homeDir() {
+  if (_deps && _deps.homeDir) return _deps.homeDir;
+  return os.homedir();
+}
+
+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);
+}
+
+function _dataDir() {
+  if (_deps && _deps.dataDir) return _deps.dataDir;
+  return require('../data-dir').getDataDir();
+}
+
+/** The authenticated hub, or '' — the same read server.js:52696 does for its sync routes. */
+function _peerInstanceId(req) {
+  return String((req && req.ctmAuth && req.ctmAuth.peerInstanceId) || '').trim();
+}
+
+function _payloadTooLarge(res) {
+  return _send(res, 413, { error: 'payload_too_large', code: 'PAYLOAD_TOO_LARGE' });
+}
+
+/**
+ * WP-5: fire-and-forget sweep after the response is out. The scheduler is single-flight and never
+ * rejects, so `void` here cannot produce an unhandled rejection; a sweep fault reaches the error sink
+ * through the `report` this passes in.
+ */
+function _scheduleGc() {
+  const schedule = (_deps && _deps.scheduleGc) || bundleGc.scheduleCollectGarbage;
+  const report = (error) => {
+    if (_deps && _deps.errorSink && typeof _deps.errorSink.report === 'function') {
+      _deps.errorSink.report('agent-bundle-gc', error);
+    }
+  };
+  schedule(_dataDir(), { sessionExists: (_deps && _deps.sessionExists) || null, report });
+}
+
+/**
+ * WP-6/D-14: fire-and-forget Codex install after the response is out — the box's `$HOME/.agents/skills`
+ * copies are brought in line with the tree this PUT just pointed at. The scheduler is single-flight and
+ * never rejects, so `void` here cannot produce an unhandled rejection; a fault reaches the error sink
+ * through the `report` this passes in. The hub identity is the AUTHENTICATED one, never a body field.
+ */
+function _scheduleCodexInstall(hubPeerId) {
+  const schedule = (_deps && _deps.scheduleCodexInstall) || bundleCodexInstall.scheduleBundleCodexInstall;
+  const report = (error) => {
+    if (_deps && _deps.errorSink && typeof _deps.errorSink.report === 'function') {
+      _deps.errorSink.report('agent-bundle-codex-install', error);
+    }
+  };
+  schedule(_dataDir(), { hubPeerId, report });
+}
+
+/**
+ * WP-3/D-8 T1: tell the server the hub pointer just moved, so it can reconcile bundle drift for the
+ * sessions that are still running an older tree. Void by construction — the reconciler is
+ * single-flight and reports its own faults through `errorSink`; a manifest PUT never waits on it.
+ */
+function _onBundlePointerMoved(hubPeerId) {
+  if (_deps && typeof _deps.onBundlePointerMoved === 'function') _deps.onBundlePointerMoved(hubPeerId);
+}
+
+/**
+ * The bounded raw-body reader. api-prompts.js:684 has the same shape for image uploads but does not
+ * export it, and its 499/abort bookkeeping is image-specific; this is the ~20-line subset the blob
+ * PUT needs (accumulate to a hard cap, reject with the tagged 413 the readers share).
+ */
+function _readRawBody(req, limit) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+    req.on('data', (chunk) => {
+      if (settled) return;
+      size += chunk.length;
+      if (size > limit) {
+        const error = new Error('Body too large');
+        error.code = 'PAYLOAD_TOO_LARGE';
+        error.error = 'payload_too_large';
+        error.status = 413;
+        fail(error);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (settled) return;
+      settled = true;
+      resolve(Buffer.concat(chunks));
+    });
+    req.on('aborted', () => {
+      const error = new Error('Client aborted agent-bundle upload');
+      error.code = 'CTM_UPLOAD_ABORTED';
+      error.status = 499;
+      fail(error);
+    });
+    req.on('error', fail);
+  });
+}
+
+/** Every route's failure path: store codes → their status, an over-cap body → 413, else 500. */
+function _fail(res, error, route) {
+  if (error instanceof AgentBundleError) {
+    const status = STATUS_BY_CODE[error.code] || 500;
+    const payload = { code: error.code };
+    if (Array.isArray(error.missing)) payload.missing = error.missing;
+    return _send(res, status, payload);
+  }
+  // WP-8: the skill transfer's own typed failure already carries its wire status (404/409/413/422/502),
+  // so the box's answer and the hub's relay of it are the same shape for the same fault.
+  if (error instanceof skillTransfer.AgentSkillError) {
+    const payload = { code: error.code };
+    if (error.detail) payload.detail = error.detail;
+    return _send(res, error.status, payload);
+  }
+  const code = String((error && error.code) || '');
+  const message = String((error && error.message) || '');
+  if (code === 'PAYLOAD_TOO_LARGE' || message === 'request_body_too_large') return _payloadTooLarge(res);
+  if (code === 'CTM_UPLOAD_ABORTED') return _send(res, 499, { error: 'client_aborted' });
+  if (_deps && _deps.errorSink && typeof _deps.errorSink.report === 'function') {
+    // REPORT: an unexpected failure is a real fault, not a client mistake — surface it before the 500.
+    _deps.errorSink.report(`agent-bundles:${route}`, error);
+  }
+  return _send(res, 500, { error: 'internal_error' });
+}
+
+async function handleMissing(req, res) {
+  const peerInstanceId = _peerInstanceId(req);
+  if (!peerInstanceId) return _send(res, 403, { code: 'agent_bundle_peer_unidentified' });
+  try {
+    const body = await _deps.readJsonRequestBody(req, { limitBytes: MAX_MISSING_BODY_BYTES });
+    const blobs = body && !Array.isArray(body) ? body.blobs : null;
+    if (!Array.isArray(blobs)) return _send(res, 400, { error: 'invalid_body' });
+    if (blobs.length > MAX_ENTRIES) return _payloadTooLarge(res);
+    return _send(res, 200, { missing: await store.missingBlobs(_dataDir(), blobs) });
+  } catch (error) {
+    return _fail(res, error, ROUTE_MISSING);
+  }
+}
+
+async function handleBlobPut(req, res, url, params) {
+  const peerInstanceId = _peerInstanceId(req);
+  if (!peerInstanceId) return _send(res, 403, { code: 'agent_bundle_peer_unidentified' });
+  try {
+    const hex = String((params && params['1']) || '');
+    const body = await _readRawBody(req, MAX_BLOB_BYTES);
+    const result = await store.putBlob(_dataDir(), hex, body);
+    return _send(res, result.stored ? 201 : 200, { stored: result.stored });
+  } catch (error) {
+    return _fail(res, error, ROUTE_BLOB);
+  }
+}
+
+/**
+ * WP-4/§6.2/D-6 (docs/remote-skills-hub-peer-identity-2026-10-26.html rev 2): the BATCH blob leg —
+ * many blobs in one request, so a first push costs a constant number of requests instead of one per
+ * blob (the box's `peer` rate bucket is per-hub and shared with the live relay; §1.3). Body:
+ * `{ blobs: [{ hash: <64 hex>, data: <base64> }] }`, at most MAX_BATCH_BODY_BYTES of JSON and
+ * MAX_ENTRIES items. Items go through the SAME `store.putBlob` (re-hash + atomic write) IN ORDER, so
+ * a bad hash is the store's own 422 and an already-present blob is left untouched. Content-addressed,
+ * so a stop mid-list is exactly a partial per-blob run. Same identity rule as the per-blob PUT: the
+ * peer refusal comes first, before the body is read.
+ */
+async function handleBlobBatch(req, res) {
+  const peerInstanceId = _peerInstanceId(req);
+  if (!peerInstanceId) return _send(res, 403, { code: 'agent_bundle_peer_unidentified' });
+  try {
+    const body = await _deps.readJsonRequestBody(req, { limitBytes: MAX_BATCH_BODY_BYTES });
+    const blobs = body && !Array.isArray(body) ? body.blobs : null;
+    if (!Array.isArray(blobs)) return _send(res, 400, { error: 'invalid_body' });
+    if (blobs.length > MAX_ENTRIES) return _payloadTooLarge(res);
+    let stored = 0;
+    let present = 0;
+    for (const item of blobs) {
+      const hash = item && typeof item.hash === 'string' ? item.hash : '';
+      const data = item && typeof item.data === 'string' ? item.data : null;
+      if (data === null) return _send(res, 400, { error: 'invalid_body' });
+      // A bad hash (or bytes that do not match it) is the store's own code; it stops the batch, and
+      // every item already written stays — content-addressed, so that is a partial per-blob run.
+      const result = await store.putBlob(_dataDir(), hash, Buffer.from(data, 'base64'));
+      if (result.stored) stored += 1; else present += 1;
+    }
+    return _send(res, 200, { stored, present });
+  } catch (error) {
+    return _fail(res, error, ROUTE_BLOB_BATCH);
+  }
+}
+
+async function handleManifestPut(req, res, url, params) {
+  const peerInstanceId = _peerInstanceId(req);
+  if (!peerInstanceId) return _send(res, 403, { code: 'agent_bundle_peer_unidentified' });
+  try {
+    const treeHash = String((params && params['1']) || '');
+    const manifest = await _deps.readJsonRequestBody(req, { limitBytes: MAX_MANIFEST_BODY_BYTES });
+    const result = await store.putManifest(_dataDir(), treeHash, manifest, { peerInstanceId });
+    _send(res, result.materialized ? 201 : 200, {
+      treeHash: result.treeHash,
+      materialized: result.materialized,
+    });
+    // WP-6/D-14: on EVERY successful PUT — the hub pointer moves on a re-PUT too, and re-applying an
+    // unchanged tree is a cheap `noop` sweep. The install resolves the tree through the hub pointer
+    // this PUT just wrote, and the GC keeps a hub-pointer tree (gc.js's `_referencedTrees` reads
+    // `hubs/*.json`), so scheduling the sweep for a re-PUT cannot delete what the install needs.
+    void _scheduleCodexInstall(peerInstanceId);
+    // WP-3/D-8 T1: on EVERY 2xx PUT — the pointer moves on a re-PUT too, so a live session on the
+    // old tree is drifted either way. Distinct from the GC below, which only a NEW tree can feed.
+    void _onBundlePointerMoved(peerInstanceId);
+    // Only a NEW tree can have added blobs/trees worth sweeping: a re-PUT changed nothing on disk.
+    if (result.materialized) void _scheduleGc();
+    return undefined;
+  } catch (error) {
+    return _fail(res, error, ROUTE_MANIFEST);
+  }
+}
+
+/**
+ * WP-7/§6.2/AC-7a: `GET /api/agent-skills/inventory` — the box's own skill truth for the CALLING hub.
+ *
+ * Read-only and side-effect free: it enumerates the box user's skill roots and hashes them, and it
+ * never writes anything (D-1: the bundle only ever lives under the box's data dir). The peer check
+ * comes first, exactly like the three ingress routes, so an unidentified caller cannot even learn the
+ * shape of this machine's skill roots.
+ *
+ * The `base` in the answer is the tree THIS hub last handed the box (`store.currentHubTree` keyed by
+ * the AUTHENTICATED peer id), which is what makes classification survive a hub restart — the hub's
+ * own push bookkeeping is in-process only.
+ */
+async function handleSkillsInventory(req, res) {
+  const peerInstanceId = _peerInstanceId(req);
+  if (!peerInstanceId) return _send(res, 403, { code: 'agent_bundle_peer_unidentified' });
+  try {
+    const inventory = await bundleInventory.readBoxInventory({ dataDir: _dataDir(), peerInstanceId });
+    return _send(res, 200, inventory);
+  } catch (error) {
+    return _fail(res, error, ROUTE_INVENTORY);
+  }
+}
+
+/**
+ * WP-8/§6.2: `GET /api/agent-skills/export?agent=claude|codex&name=<name>` — the bytes of ONE box item.
+ *
+ * A `ctm-managed` copy (the managed-skill installer's own `delegate`) is a 404, never a 409: this
+ * release's copy is simply not an item that can be proposed for import, and "not found" keeps the hub
+ * from ever rendering it as one. The ref is validated first (a name that could escape a root is a 422
+ * before any path is built), then the item is located exactly as the WP-7 inventory locates it.
+ */
+async function handleSkillExport(req, res, url) {
+  const peerInstanceId = _peerInstanceId(req);
+  if (!peerInstanceId) return _send(res, 403, { code: 'agent_bundle_peer_unidentified' });
+  try {
+    const agent = url && url.searchParams ? url.searchParams.get('agent') : '';
+    const name = url && url.searchParams ? url.searchParams.get('name') : '';
+    const exported = await skillTransfer.exportBoxSkill({ agent, name, homeDir: _homeDir(), env: process.env });
+    return _send(res, 200, exported);
+  } catch (error) {
+    return _fail(res, error, ROUTE_SKILL_EXPORT);
+  }
+}
+
+/**
+ * WP-8/§6.5: `POST /api/agent-skills/retire { agent, name, expectHash }` — D-13's "moves, never
+ * deletes". The box re-hashes the copy NOW and refuses one that changed since review, then MOVES it
+ * under `<data dir>/agent-bundles/retired/`. Both failures are the human's to see, so both carry a code.
+ */
+async function handleSkillRetire(req, res) {
+  const peerInstanceId = _peerInstanceId(req);
+  if (!peerInstanceId) return _send(res, 403, { code: 'agent_bundle_peer_unidentified' });
+  try {
+    const body = await _deps.readJsonRequestBody(req, { limitBytes: MAX_MISSING_BODY_BYTES });
+    const ref = body && !Array.isArray(body) ? body : {};
+    const result = await skillTransfer.retireBoxSkill({
+      agent: ref.agent,
+      name: ref.name,
+      expectHash: ref.expectHash,
+      dataDir: _dataDir(),
+      homeDir: _homeDir(),
+      env: process.env,
+    });
+    return _send(res, 200, result);
+  } catch (error) {
+    return _fail(res, error, ROUTE_SKILL_RETIRE);
+  }
+}
+
+function register() {
+  registerApiRoutes('agent-bundles', [
+    { method: 'POST', path: '/api/agent-bundles/missing', handler: handleMissing },
+    // WP-4/§6.2/D-6: the batch leg, so a first push is a constant number of requests. Same auth row
+    // tuple as the per-blob PUT (lib/auth-rules.js), same peer-identity refusal first.
+    { method: 'POST', path: '/api/agent-bundles/blobs', handler: handleBlobBatch },
+    // The regex is byte-identical to lib/auth-rules.js's blob row on purpose: routing and auth must
+    // agree on what "this route" is, or a malformed hash would be answered by the auth wall with a
+    // different code than the handler's own 422.
+    { method: 'PUT', regex: /^\/api\/agent-bundles\/blobs\/([0-9a-f]{64})$/, handler: handleBlobPut },
+    // `[^/]+` (not a hash pattern): the tree hash is URL-encoded in the URL, and store.js decodes
+    // and validates it into the one canonical `sha256:<hex>` form — a bad one is its 422, not a 404.
+    { method: 'PUT', regex: /^\/api\/agent-bundles\/manifests\/([^/]+)$/, handler: handleManifestPut },
+    // WP-7/§6.2: the return path. Same identity rule as the three above (an unauthenticated caller is
+    // 403 agent_bundle_peer_unidentified), same group; the base it reports is the caller's own.
+    { method: 'GET', path: '/api/agent-skills/inventory', handler: handleSkillsInventory },
+    // WP-8/§6.2: the one-skill exchange. `export` is a GET with query ref fields (a name is not
+    // path-safe in general); `retire` is a POST whose only body field that matters is the reviewed
+    // hash — the box identity is the authenticated peer, never a field, exactly as above.
+    { method: 'GET', path: '/api/agent-skills/export', handler: handleSkillExport },
+    { method: 'POST', path: '/api/agent-skills/retire', handler: handleSkillRetire },
+  ]);
+}
+
+module.exports = {
+  configure,
+  register,
+  handleMissing,
+  handleBlobBatch,
+  handleBlobPut,
+  handleManifestPut,
+  handleSkillsInventory,
+  handleSkillExport,
+  handleSkillRetire,
+};

package/template/coding-task-manager/lib/api/backup-retention.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// Backup retention setting (design: docs/backup-retention-days-setting-2026-10-31.html §6/WP-1).
+// GET  /api/storage/backup-retention  -> the effective value, where it came from, and the
+//                                        backup names the next prune will remove.
+// PUT  /api/storage/backup-retention  -> validate + persist `backup_retention_days`.
+//
+// Neither handler deletes anything: pruning still runs only at the end of a successful backup
+// (db.js cleanOldBackups). A PUT just changes the number the next prune reads.
+
+const { registerApiRoutes } = require('../api-router');
+const backupRetention = require('../../../shared/backup-retention');
+
+let _deps = null;
+
+function configure(deps = {}) {
+  _deps = deps;
+}
+
+async function _statusPayload() {
+  const db = _deps.db;
+  const retentionDays = db.getBackupRetentionDays();
+  let source = 'default';
+  try {
+    // Production main thread: the published control snapshot (direct sync DB reads are refused
+    // in the request zone). Tests and worker-local callers fall back to db.getSetting.
+    const read = typeof _deps.getSetting === 'function' ? _deps.getSetting : db.getSetting.bind(db);
+    const stored = await read(backupRetention.BACKUP_RETENTION_SETTING_KEY, null);
+    if (stored !== null && stored !== undefined) source = 'settings';
+  } catch (e) {
+    // A read failure must never break the page: report and answer with the default source.
+    console.error('[api] Backup retention setting read failed:', e.message);
+    source = 'default';
+  }
+  const expiring = backupRetention
+    .selectExpiredBackups(await db.listBackupsAsync(), retentionDays)
+    .map((b) => b.name);
+  return {
+    retention_days: retentionDays,
+    default_retention_days: backupRetention.DEFAULT_BACKUP_RETENTION_DAYS,
+    min: backupRetention.MIN_BACKUP_RETENTION_DAYS,
+    max: backupRetention.MAX_BACKUP_RETENTION_DAYS,
+    source,
+    expiring,
+  };
+}
+
+async function handleGet(req, res) {
+  void req;
+  _deps.sendJsonResponse(res, 200, await _statusPayload());
+}
+
+async function handlePut(req, res) {
+  let body;
+  try {
+    body = await _deps.readBody(req);
+  } catch {
+    // Malformed JSON, empty body, or an over-limit body: nothing is written.
+    _deps.sendJsonResponse(res, 400, { error: 'invalid_body' });
+    return;
+  }
+  const parsed = backupRetention.parseRetentionDaysInput(body && body.retention_days);
+  if (!parsed.ok) {
+    _deps.sendJsonResponse(res, 400, {
+      error: parsed.error,
+      min: parsed.min,
+      max: parsed.max,
+    });
+    return;
+  }
+  _deps.db.setBackupRetentionDays(parsed.days);
+  await _deps.db.setSetting(backupRetention.BACKUP_RETENTION_SETTING_KEY, parsed.days);
+  _deps.sendJsonResponse(res, 200, await _statusPayload());
+}
+
+function register() {
+  registerApiRoutes('backup-retention', [
+    { method: 'GET', path: '/api/storage/backup-retention', handler: handleGet },
+    { method: 'PUT', path: '/api/storage/backup-retention', handler: handlePut },
+  ]);
+}
+
+module.exports = { configure, handleGet, handlePut, register };

package/template/coding-task-manager/lib/api/conversation-sync-routes.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// WP-5 (docs/shared-memory-every-machine-2026-10-31.html §5 D-3, D-12, §6.8): the CTM-served
+// conversation-history feed. Unlike the brain/v2 family (lib/api/memory-sync-routes.js), these
+// three routes are NOT proxies: transcription history lives in CTM's own task-manager.db, so the
+// hub speaks to a member's CTM directly and no Wall-E hop is involved.
+//
+//   GET  /api/sync/conversation/v2/vector  -> { ok, instanceId, vector, seedDone }
+//   POST /api/sync/conversation/v2/changes { since, limit } -> { ok, entries, more, seedDone }
+//   POST /api/sync/conversation/v2/apply   { sourceInstanceId, entries } -> { ok, applied, skipped, vector }
+//
+// Auth is NOT evaluated here — lib/auth-rules.js carries the three rows (scope `sync`, no step-up,
+// NOT peerControl: the pool credential the hub already dials `/api/sync/brain/v2/*` with authorizes
+// them), and a route with no rule is 403 auth_rule_missing by design, so the rule rows and these
+// registrations land together. A body over the 8 MiB cap is 413 before any DB work.
+//
+// The clock seed (D-3 / §6.8) is driven from here rather than at boot: each `/vector` and
+// `/changes` call advances THIS node's seed by one bounded page, so a member with pre-existing
+// history finishes seeding over the first few hub ticks and boot stays free of the work.
+//
+// WP-3 (docs/join-sync-followups-2-2026-11-01.html §5 R-10/R-11, §8 WP-3): that seed page, the
+// store DDL and every read/write below run in the DB-OWNER WORKER, never on this thread. Each
+// handler awaits one closed owner action through the injected `runMutation`
+// (`runMutation -> server.js _runCtmDbWorkerOp('runDbMutation', …) -> db.js
+// DB_OWNER_MUTATION_ACTIONS -> lib/conversation-sync.js owner*`). Doing this work here is what
+// made every member's /vector answer 500: the main-thread request-zone guard refuses a main-DB
+// op inside a request (lib/main-db-census.js, CTM_MAIN_DB_REQUEST_FORBIDDEN). The three reply
+// shapes are unchanged (R-11) — only where the work runs changed.
+
+const { registerApiRoutes } = require('../api-router');
+
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+const BODY_TOO_LARGE = 'request_body_too_large';
+const OWNER_UNAVAILABLE = 'conversation_sync_owner_unavailable';
+
+let _deps = null;
+
+function configure({ dbModule, readJsonRequestBody, sendJsonResponse, seedPageLimit, runMutation } = {}) {
+  _deps = { dbModule, readJsonRequestBody, sendJsonResponse, seedPageLimit, runMutation };
+}
+
+// The one seam to the DB-owner worker. Unconfigured (or configured with a non-function) means the
+// feed cannot run at all, so every route answers 503 rather than doing the work in-zone.
+function _ownerRun() {
+  const run = _deps && _deps.runMutation;
+  return typeof run === 'function' ? run : null;
+}
+
+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);
+}
+
+async function _readBody(req) {
+  const reader = _deps && _deps.readJsonRequestBody;
+  if (typeof reader !== 'function') return { ok: true, body: undefined };
+  try {
+    return { ok: true, body: await reader(req, { limitBytes: MAX_BODY_BYTES }) };
+  } catch (err) {
+    return { ok: false, tooLarge: !!(err && err.message === BODY_TOO_LARGE) };
+  }
+}
+
+async function _handleVector(req, res) {
+  const run = _ownerRun();
+  if (!run) return _send(res, 503, { ok: false, error: OWNER_UNAVAILABLE });
+  try {
+    const vector = await run('conversationSyncVector', [{ seedPageLimit: _deps.seedPageLimit }]);
+    return _send(res, 200, { ok: true, ...vector });
+  } catch (err) {
+    return _send(res, 500, { ok: false, error: 'conversation_vector_failed', detail: String(err?.message || err).slice(0, 200) });
+  }
+}
+
+async function _handleChanges(req, res) {
+  const run = _ownerRun();
+  if (!run) return _send(res, 503, { ok: false, error: OWNER_UNAVAILABLE });
+  const read = await _readBody(req);
+  if (!read.ok) return _send(res, 413, { ok: false, error: 'payload_too_large' });
+  const body = (read.body && typeof read.body === 'object') ? read.body : {};
+  try {
+    const page = await run('conversationSyncChanges', [{
+      since: body.since,
+      limit: body.limit,
+      seedPageLimit: _deps.seedPageLimit,
+    }]);
+    return _send(res, 200, { ok: true, entries: page.entries, more: page.more, seedDone: page.seedDone });
+  } catch (err) {
+    return _send(res, 500, { ok: false, error: 'conversation_changes_failed', detail: String(err?.message || err).slice(0, 200) });
+  }
+}
+
+async function _handleApply(req, res) {
+  const run = _ownerRun();
+  if (!run) return _send(res, 503, { ok: false, error: OWNER_UNAVAILABLE });
+  const read = await _readBody(req);
+  if (!read.ok) return _send(res, 413, { ok: false, error: 'payload_too_large' });
+  const body = (read.body && typeof read.body === 'object') ? read.body : {};
+  const sourceInstanceId = String(body.sourceInstanceId || '').trim();
+  if (!sourceInstanceId) return _send(res, 400, { ok: false, error: 'source_instance_required' });
+  try {
+    const result = await run('conversationSyncApply', [{
+      sourceInstanceId,
+      entries: Array.isArray(body.entries) ? body.entries : [],
+    }]);
+    return _send(res, 200, { ok: true, applied: result.applied, skipped: result.skipped, vector: result.vector });
+  } catch (err) {
+    const code = err && err.code;
+    if (code === 'CONVERSATION_SYNC_ENTRIES_TOO_LARGE') return _send(res, 413, { ok: false, error: 'too_many_entries' });
+    return _send(res, 500, { ok: false, error: 'conversation_apply_failed', detail: String(err?.message || err).slice(0, 200) });
+  }
+}
+
+function register() {
+  registerApiRoutes('conversation-sync', [
+    { method: 'GET', path: '/api/sync/conversation/v2/vector', handler: (req, res, url) => _handleVector(req, res, url) },
+    { method: 'POST', path: '/api/sync/conversation/v2/changes', handler: (req, res, url) => _handleChanges(req, res, url) },
+    { method: 'POST', path: '/api/sync/conversation/v2/apply', handler: (req, res, url) => _handleApply(req, res, url) },
+  ]);
+}
+
+module.exports = { configure, register };