create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/lib/memory-sync.js

@@ -0,0 +1,565 @@
+'use strict';
+
+// WP-3 (docs/shared-memory-every-machine-2026-10-31.html §5 D-1/D-2/D-9/D-12, §6.6): the hub side
+// of the v2 brain replica in the existing star.
+//
+//   syncMemberBrainOnce(member, deps) -> { ok, member, state, pulled, pushed, error? }
+//   runBrainMemberRound(deps)          -> { ok, members: [...], pruned }
+//   memorySyncStatus()                 -> { lastRoundAt, members: [...] }
+//
+// D-1: membership is PAIRING, not `CTM_SYNC_PEERS`. The members are this host's machine-registry
+// rows with `enabled = 1` and `health === 'reachable'` (the hub owns liveness, machine-registry
+// D-4) — the same credential the probe uses reaches them (`peerHeadersFor`, the pool secret for a
+// member). D-2: only the hub dials; each round exchanges both directions with every reachable
+// member and there is no box↔box link. D-12: the member's CTM fronts its own loopback Wall-E at
+// `/api/sync/brain/v2/*`; the local leg talks to THIS host's Wall-E with the local CTM token.
+//
+// The per-member state Map (failure backoff, last verdict) is MODULE state by design, exactly like
+// machine-registry's probe bookkeeping: it describes the last round this process ran, dies with the
+// process, and a stale copy must never look like durable truth.
+
+const { boolFlag, createEnvFlags } = require('./env-flags');
+const machineRegistry = require('./machine-registry');
+const { advanceMemberJoin } = require('./memory-join');
+const conversationStore = require('./conversation-store-v2');
+const conversationSync = require('./conversation-sync');
+
+const DEFAULT_PAGE_LIMIT = 500; // D-9: one page is at most 500 clock rows
+const DEFAULT_MAX_PAGES = 20; // D-9: at most 20 pages per member per round
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_FAILURE_BACKOFF_MS = 15_000;
+const DEFAULT_FAILURE_BACKOFF_MAX_MS = 60_000;
+
+// WP-4 (§5 D-6, §6.7): the non-error join states a member can report while it is taking the hub's
+// snapshot. 'join_failed' is deliberately absent — a broken join is a fault, not progress.
+const JOIN_PROGRESS_STATES = new Set(['join_snapshot', 'join_transfer', 'join_import', 'join_done']);
+
+// The box CTM's front routes (D-12). Each forwards verbatim to the box's own Wall-E.
+const MEMBER_PATHS = Object.freeze({
+  vector: '/api/sync/brain/v2/vector',
+  changes: '/api/sync/brain/v2/changes',
+  apply: '/api/sync/brain/v2/apply',
+});
+
+// The hub's LOCAL Wall-E v2 routes (already loopback + CTM token).
+const LOCAL_PATHS = Object.freeze({
+  vector: '/api/walle/sync/v2/vector',
+  changes: '/api/walle/sync/v2/changes',
+  apply: '/api/walle/sync/v2/apply',
+  memberVector: '/api/walle/sync/v2/member-vector',
+  pruneTombstones: '/api/walle/sync/v2/prune-tombstones',
+});
+
+// WP-5 (§5 D-3, §6.8): the conversation-history front routes a member's CTM serves itself — no
+// Wall-E hop, because transcription history lives in task-manager.db.
+const CONVERSATION_PATHS = Object.freeze({
+  vector: '/api/sync/conversation/v2/vector',
+  changes: '/api/sync/conversation/v2/changes',
+  apply: '/api/sync/conversation/v2/apply',
+});
+
+// instanceId -> { attempts, nextAt, state }. Module state (see the header).
+const _memberState = new Map();
+// The one in-flight round, or null. A second call joins/reports it, never starts a second round.
+let _inFlight = null;
+let _lastRound = null;
+
+function _string(value, max = 160) {
+  if (typeof value === 'string') return value.trim().slice(0, max);
+  return value == null ? '' : String(value).trim().slice(0, max);
+}
+
+function _now(deps = {}) {
+  return typeof deps.now === 'function' ? Number(deps.now()) || Date.now() : Date.now();
+}
+
+// D-1 flag. Default ON; only '0'/'false'/'no'/'off' disables. `deps.env` is injected so a test can
+// flip it without touching process.env (H-1), and so a member Wall-E's own kill switch is honoured
+// on the local leg (503 brain_sync_disabled -> 'disabled').
+function _brainSyncEnabled(env) {
+  if (!env || env === process.env) return boolFlag('CTM_SYNC_BRAIN_ENABLED', true);
+  return createEnvFlags({ env }).boolFlag('CTM_SYNC_BRAIN_ENABLED', true);
+}
+
+function _memberUrls(member = {}) {
+  const list = (Array.isArray(member.urls) ? member.urls : []).map((u) => _string(u, 1000)).filter(Boolean);
+  if (list.length) return list;
+  const pinned = _string(member.url, 1000);
+  return pinned ? [pinned] : [];
+}
+
+function _joinUrl(base, pathname) {
+  return `${String(base).replace(/\/+$/, '')}${pathname}`;
+}
+
+// One member request, with the AbortController + unref'd timer shape machine-registry's _getJsonBox
+// uses, so a hung box can never hold the tick open past the timeout. Never throws: a transport fault
+// is reported as `{ status: 0 }` and mapped by the caller to 'unreachable'.
+async function _memberRequest(fetchImpl, url, pathname, { method = 'GET', body = null, headers = {} } = {}) {
+  const fetchFn = fetchImpl || global.fetch;
+  if (typeof fetchFn !== 'function') return { status: 0, json: null, error: 'fetch_unavailable' };
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), DEFAULT_REQUEST_TIMEOUT_MS) : null;
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  try {
+    const payload = body == null ? null : JSON.stringify(body);
+    const res = await fetchFn(_joinUrl(url, pathname), {
+      method,
+      headers: {
+        ...headers,
+        ...(payload ? { 'Content-Type': 'application/json' } : {}),
+        Accept: 'application/json',
+      },
+      ...(payload ? { body: payload } : {}),
+      signal: controller ? controller.signal : undefined,
+    });
+    let json = null;
+    try { json = await res.json(); } catch { json = null; /* expected: a non-JSON body is degraded, mapped by the caller */ }
+    return { status: Number(res && res.status) || 0, json };
+  } catch (err) {
+    return { status: 0, json: null, error: err?.message || String(err) };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// One local Wall-E call. walle.requestJson resolves { status, json } for any answer and rejects only
+// on a transport fault — the caller maps both.
+async function _walleRequest(walle, pathname, { method = 'GET', body = null } = {}) {
+  try {
+    const res = await walle.requestJson(pathname, body == null ? { method } : { method, body });
+    return { status: Number(res && res.status) || 0, json: (res && res.json) || null };
+  } catch (err) {
+    return { status: 0, json: null, error: err?.message || String(err) };
+  }
+}
+
+function _isDisabled(res) {
+  return res && res.status === 503 && res.json && res.json.error === 'brain_sync_disabled';
+}
+
+// The first URL that ANSWERS (any HTTP status) owns the rest of the exchange, so a member is never
+// half-dialled across two origins inside one round. No answer at all -> status 0 ('unreachable').
+async function _dialMember(fetchImpl, urls, pathname, options) {
+  let last = { status: 0, json: null, error: 'member_has_no_url' };
+  for (const url of urls) {
+    const res = await _memberRequest(fetchImpl, url, pathname, options);
+    if (res.status > 0) return { ...res, url };
+    last = { ...res, url };
+  }
+  return last;
+}
+
+/**
+ * One bidirectional exchange with one member (D-2, D-9). Returns a state from
+ * 'synced' | 'seed_pending' | 'disabled' | 'unreachable' | 'error', or — for a member that has
+ * never taken the hub's origin — one of lib/memory-join.js's join states ('seed_pending' |
+ * 'join_snapshot' | 'join_transfer' | 'join_import' | 'join_done' | 'join_failed').
+ *
+ * @param {{instanceId: string, urls?: string[], url?: string}} member
+ * @param {object} deps  { fetchImpl, peerHeadersFor, walle, env, now, pageLimit, maxPages,
+ *                         chunksPerTick, readChunk }
+ */
+async function syncMemberBrainOnce(member = {}, deps = {}) {
+  const fetchImpl = deps.fetchImpl || global.fetch;
+  const walle = deps.walle;
+  const env = deps.env || process.env;
+  const pageLimit = Number(deps.pageLimit) || DEFAULT_PAGE_LIMIT;
+  const maxPages = Number(deps.maxPages) || DEFAULT_MAX_PAGES;
+  const instanceId = _string(member.instanceId);
+  const base = { ok: true, member: instanceId, state: 'error', pulled: 0, pushed: 0 };
+  if (!walle || typeof walle.requestJson !== 'function') return { ...base, ok: false, error: 'walle_client_missing' };
+  if (!instanceId) return { ...base, ok: false, error: 'member_instance_required' };
+  const urls = _memberUrls(member);
+  if (!urls.length) return { ...base, ok: false, state: 'unreachable', error: 'member_has_no_url' };
+  const headers = typeof deps.peerHeadersFor === 'function' ? (deps.peerHeadersFor(instanceId) || {}) : {};
+
+  // 1. both ends' vectors.
+  const localRes = await _walleRequest(walle, LOCAL_PATHS.vector);
+  if (_isDisabled(localRes)) return { ...base, ok: false, state: 'disabled' };
+  if (localRes.status === 0 || !localRes.json) return { ...base, ok: false, state: 'unreachable', error: localRes.error || 'local_walle_unreachable' };
+  const local = localRes.json;
+  const memberRes = await _dialMember(fetchImpl, urls, MEMBER_PATHS.vector, { method: 'GET', headers });
+  if (_isDisabled(memberRes)) return { ...base, ok: false, state: 'disabled' };
+  if (memberRes.status === 0 || !memberRes.json) return { ...base, ok: false, state: 'unreachable', error: memberRes.error || 'member_unreachable' };
+  const memberUrl = memberRes.url;
+  const mv = memberRes.json;
+
+  // 2. D-9: a node whose WP-0 clock walk has not finished cannot exchange a feed. No traffic.
+  if (local.clockSeedDone !== true || mv.clockSeedDone !== true) {
+    return { ...base, ok: false, state: 'seed_pending' };
+  }
+
+  const localInstanceId = _string(local.instanceId) || _string(env.CTM_INSTANCE_ID || env.CTM_INSTANCE_TAG);
+  const localVector = (local.vector && typeof local.vector === 'object') ? { ...local.vector } : {};
+  const memberVector = (mv.vector && typeof mv.vector === 'object') ? { ...mv.vector } : {};
+
+  // 3. D-1/§6.6: a member that has never taken the hub's origin cannot exchange a feed yet —
+  // pushing its orphaned legacy rows at the hub now would flood identity conflicts. WP-4 (§5 D-6,
+  // §6.7) turns that idle 'join_required' into the join state machine: the hub ships its consistent
+  // snapshot in chunks, the member imports it, and only then does the normal feed resume.
+  if (Object.keys(localVector).length > 0 && localInstanceId && !Object.prototype.hasOwnProperty.call(memberVector, localInstanceId)) {
+    const join = await advanceMemberJoin(member, {
+      localInstanceId,
+      walle,
+      fetchImpl,
+      headers,
+      memberUrl,
+      now: deps.now,
+      chunksPerTick: deps.chunksPerTick,
+      readChunk: deps.readChunk,
+    });
+    return {
+      ...base,
+      ok: join.state === 'join_done',
+      state: join.state,
+      pulled: 0,
+      pushed: 0,
+      ...(join.detail ? { detail: join.detail } : {}),
+    };
+  }
+
+  let pulled = 0;
+  let pushed = 0;
+  let pullVector = localVector;
+  let pushVector = memberVector;
+
+  // 4. pull: member /changes -> local /apply, page by page.
+  for (let page = 0; page < maxPages; page += 1) {
+    const changes = await _memberRequest(fetchImpl, memberUrl, MEMBER_PATHS.changes, {
+      method: 'POST', headers, body: { since: pullVector, limit: pageLimit },
+    });
+    if (_isDisabled(changes)) return { ...base, ok: false, state: 'disabled' };
+    if (changes.status === 0) return { ...base, ok: false, state: 'unreachable', pulled, pushed, error: changes.error || 'member_unreachable' };
+    if (changes.status === 409) return { ...base, ok: false, state: 'seed_pending', pulled, pushed };
+    if (changes.status < 200 || changes.status >= 300 || !changes.json) {
+      return { ...base, ok: false, state: 'error', pulled, pushed, error: `member_changes_http_${changes.status}` };
+    }
+    const entries = Array.isArray(changes.json.entries) ? changes.json.entries : [];
+    if (entries.length) {
+      const applied = await _walleRequest(walle, LOCAL_PATHS.apply, { method: 'POST', body: { sourceInstanceId: instanceId, entries } });
+      if (_isDisabled(applied)) return { ...base, ok: false, state: 'disabled' };
+      if (applied.status === 0) return { ...base, ok: false, state: 'unreachable', pulled, pushed, error: 'local_walle_unreachable' };
+      if (applied.status < 200 || applied.status >= 300 || !applied.json) {
+        return { ...base, ok: false, state: 'error', pulled, pushed, error: `local_apply_http_${applied.status}` };
+      }
+      pulled += Number(applied.json.applied) || entries.length;
+      pullVector = (applied.json.vector && typeof applied.json.vector === 'object') ? applied.json.vector : pullVector;
+    }
+    if (changes.json.more !== true) break;
+  }
+
+  // 5. push: local /changes -> member /apply, page by page.
+  for (let page = 0; page < maxPages; page += 1) {
+    const changes = await _walleRequest(walle, LOCAL_PATHS.changes, { method: 'POST', body: { since: pushVector, limit: pageLimit } });
+    if (_isDisabled(changes)) return { ...base, ok: false, state: 'disabled', pulled, pushed };
+    if (changes.status === 0) return { ...base, ok: false, state: 'unreachable', pulled, pushed, error: 'local_walle_unreachable' };
+    if (changes.status === 409) return { ...base, ok: false, state: 'seed_pending', pulled, pushed };
+    if (changes.status < 200 || changes.status >= 300 || !changes.json) {
+      return { ...base, ok: false, state: 'error', pulled, pushed, error: `local_changes_http_${changes.status}` };
+    }
+    const entries = Array.isArray(changes.json.entries) ? changes.json.entries : [];
+    if (entries.length) {
+      const applied = await _memberRequest(fetchImpl, memberUrl, MEMBER_PATHS.apply, {
+        // D-5: name this node as the member's home so the member stops running derived producers.
+        method: 'POST', headers: { ...headers, 'X-CTM-Memory-Sync-Home': localInstanceId }, body: { sourceInstanceId: localInstanceId, entries },
+      });
+      if (_isDisabled(applied)) return { ...base, ok: false, state: 'disabled', pulled, pushed };
+      if (applied.status === 0) return { ...base, ok: false, state: 'unreachable', pulled, pushed, error: applied.error || 'member_unreachable' };
+      if (applied.status < 200 || applied.status >= 300 || !applied.json) {
+        return { ...base, ok: false, state: 'error', pulled, pushed, error: `member_apply_http_${applied.status}` };
+      }
+      pushed += Number(applied.json.applied) || entries.length;
+      pushVector = (applied.json.vector && typeof applied.json.vector === 'object') ? applied.json.vector : pushVector;
+    }
+    if (changes.json.more !== true) break;
+  }
+
+  // 6. tell the hub's Wall-E what the member last reported (feeds tombstone pruning).
+  const recorded = await _walleRequest(walle, LOCAL_PATHS.memberVector, {
+    method: 'POST', body: { memberInstanceId: instanceId, vector: pushVector },
+  });
+  if (_isDisabled(recorded)) return { ...base, ok: false, state: 'disabled', pulled, pushed };
+  if (recorded.status === 0) return { ...base, ok: false, state: 'unreachable', pulled, pushed, error: 'local_walle_unreachable' };
+  if (recorded.status < 200 || recorded.status >= 300) {
+    return { ...base, ok: false, state: 'error', pulled, pushed, error: `local_member_vector_http_${recorded.status}` };
+  }
+
+  return { ok: true, member: instanceId, state: 'synced', pulled, pushed };
+}
+
+// WP-5 (§5 D-3, §6.8) flag. Its own switch: the brain leg's CTM_SYNC_BRAIN_ENABLED must not take
+// transcription history down with it (and vice versa). Default ON.
+function _conversationSyncEnabled(env) {
+  if (!env || env === process.env) return boolFlag('CTM_SYNC_CONVERSATION_ENABLED', true);
+  return createEnvFlags({ env }).boolFlag('CTM_SYNC_CONVERSATION_ENABLED', true);
+}
+
+/**
+ * The raw statement interface for CTM's own store. The worker is handed the db MODULE
+ * (server.js passes `db-owner-client`), whose proxies expose `getDb()` rather than
+ * `prepare`/`exec`; a db object with no readable handle at all — a push-only worker stub — has no
+ * conversation store to exchange, so the leg is skipped rather than reported as a member error.
+ *
+ * @param {object|null} db the round's injected db module
+ * @returns {object|null} a better-sqlite3 handle, or null when this node cannot serve the feed
+ */
+function _conversationDb(db) {
+  if (!db) return null;
+  if (typeof db.prepare === 'function') return db;
+  if (typeof db.getDb === 'function') {
+    try { return db.getDb() || null; } catch { return null; /* REPORT: no readable store handle — the leg is skipped */ }
+  }
+  return null;
+}
+
+/**
+ * One bidirectional exchange of conversation-clock changes with one member (D-3 over transcription
+ * history). Runs AFTER the brain leg and independently of its verdict: the conversation feed needs
+ * no join snapshot, so a member mid-join still exchanges items. Returns
+ * { ok, state, pulled, pushed } with a state from 'synced' | 'seed_pending' | 'disabled' |
+ * 'unreachable' | 'error'.
+ *
+ * @param {{instanceId: string, urls?: string[], url?: string}} member
+ * @param {object} deps { db, fetchImpl, peerHeadersFor, env, pageLimit, maxPages }
+ */
+async function syncMemberConversationOnce(member = {}, deps = {}) {
+  const db = _conversationDb(deps.db);
+  const fetchImpl = deps.fetchImpl || global.fetch;
+  const env = deps.env || process.env;
+  const pageLimit = Number(deps.pageLimit) || DEFAULT_PAGE_LIMIT;
+  const maxPages = Number(deps.maxPages) || DEFAULT_MAX_PAGES;
+  const instanceId = _string(member.instanceId);
+  const base = { ok: true, state: 'error', pulled: 0, pushed: 0 };
+  if (!db) return { ...base, ok: false, error: 'db_required' };
+  if (!instanceId) return { ...base, ok: false, error: 'member_instance_required' };
+  const urls = _memberUrls(member);
+  if (!urls.length) return { ...base, ok: false, state: 'unreachable', error: 'member_has_no_url' };
+  const headers = typeof deps.peerHeadersFor === 'function' ? (deps.peerHeadersFor(instanceId) || {}) : {};
+
+  // 1. this node's own seed advances one bounded page per round (never at boot, §6.8).
+  try {
+    conversationStore.seedConversationClockPage(db, {});
+  } catch {
+    return { ...base, ok: false, state: 'error', error: 'conversation_seed_failed' };
+  }
+  const local = conversationSync.readConversationVector(db);
+  if (local.seedDone !== true) return { ...base, ok: true, state: 'seed_pending' };
+
+  // 2. the member's vector. Its /vector call advances the member's own seed page too.
+  const memberRes = await _dialMember(fetchImpl, urls, CONVERSATION_PATHS.vector, { method: 'GET', headers });
+  if (memberRes.status === 0 || !memberRes.json) {
+    return { ...base, ok: false, state: 'unreachable', error: memberRes.error || 'member_unreachable' };
+  }
+  if (memberRes.status < 200 || memberRes.status >= 300) {
+    return { ...base, ok: false, state: 'error', error: `member_vector_http_${memberRes.status}` };
+  }
+  const memberUrl = memberRes.url;
+  if (memberRes.json.seedDone !== true) return { ...base, ok: true, state: 'seed_pending' };
+
+  const localInstanceId = _string(local.instanceId)
+    || _string(env.CTM_INSTANCE_ID || env.CTM_INSTANCE_TAG);
+  let pullVector = (local.vector && typeof local.vector === 'object') ? { ...local.vector } : {};
+  let pushVector = (memberRes.json.vector && typeof memberRes.json.vector === 'object') ? { ...memberRes.json.vector } : {};
+
+  // 3. pull: member /changes -> local apply.
+  let pulled = 0;
+  for (let page = 0; page < maxPages; page += 1) {
+    const changes = await _memberRequest(fetchImpl, memberUrl, CONVERSATION_PATHS.changes, {
+      method: 'POST', headers, body: { since: pullVector, limit: pageLimit },
+    });
+    if (changes.status === 0) return { ...base, ok: false, state: 'unreachable', pulled, pushed: 0, error: changes.error || 'member_unreachable' };
+    if (changes.status < 200 || changes.status >= 300 || !changes.json) {
+      return { ...base, ok: false, state: 'error', pulled, pushed: 0, error: `member_changes_http_${changes.status}` };
+    }
+    const entries = Array.isArray(changes.json.entries) ? changes.json.entries : [];
+    if (entries.length) {
+      try {
+        const result = conversationSync.applyConversationChanges(db, { sourceInstanceId: instanceId, entries });
+        pulled += Number(result.applied) || 0;
+        pullVector = result.vector || pullVector;
+      } catch {
+        return { ...base, ok: false, state: 'error', pulled, pushed: 0, error: 'local_apply_failed' };
+      }
+    }
+    if (changes.json.more !== true) break;
+  }
+
+  // 4. push: local changes -> member /apply, page by page.
+  let pushed = 0;
+  for (let page = 0; page < maxPages; page += 1) {
+    const page2 = conversationSync.conversationChangesSince(db, { since: pushVector, limit: pageLimit });
+    const entries = page2.entries;
+    if (entries.length) {
+      const applied = await _memberRequest(fetchImpl, memberUrl, CONVERSATION_PATHS.apply, {
+        method: 'POST', headers, body: { sourceInstanceId: localInstanceId, entries },
+      });
+      if (applied.status === 0) return { ...base, ok: false, state: 'unreachable', pulled, pushed, error: applied.error || 'member_unreachable' };
+      if (applied.status < 200 || applied.status >= 300 || !applied.json) {
+        return { ...base, ok: false, state: 'error', pulled, pushed, error: `member_apply_http_${applied.status}` };
+      }
+      pushed += Number(applied.json.applied) || entries.length;
+      pushVector = (applied.json.vector && typeof applied.json.vector === 'object') ? applied.json.vector : pushVector;
+    }
+    if (page2.more !== true) break;
+  }
+
+  return { ...base, ok: true, state: 'synced', pulled, pushed };
+}
+
+// Exponential backoff with jitter, mirroring hosted-sync-worker's _failureDelayMs so a member that
+// just failed is not re-dialled every tick.
+function _failureDelayMs(env, attempt, options = {}) {
+  const base = Math.max(1000, Number(env.CTM_SYNC_FAILURE_BACKOFF_MS || options.failureBackoffMs || DEFAULT_FAILURE_BACKOFF_MS) || DEFAULT_FAILURE_BACKOFF_MS);
+  const max = Math.max(base, Number(env.CTM_SYNC_FAILURE_BACKOFF_MAX_MS || options.failureBackoffMaxMs || DEFAULT_FAILURE_BACKOFF_MAX_MS) || DEFAULT_FAILURE_BACKOFF_MAX_MS);
+  const exp = Math.min(max, base * Math.max(1, 2 ** Math.max(0, attempt - 1)));
+  const jitter = Math.floor(exp * 0.2 * Math.random());
+  return Math.min(max, exp + jitter);
+}
+
+function _resolveSelfInstanceId(deps = {}, env = process.env) {
+  const source = deps.selfInstanceId;
+  if (typeof source === 'function') {
+    try { return _string(source()); } catch { return ''; }
+  }
+  if (source) return _string(source);
+  return _string(env.CTM_INSTANCE_ID || env.CTM_INSTANCE_TAG || '');
+}
+
+function _candidateMembers(db, selfInstanceId) {
+  const { machines } = machineRegistry.listMachines({ db });
+  return (machines || []).filter((m) => m
+    && m.enabled
+    && m.health === 'reachable'
+    && m.instanceId
+    && m.instanceId !== selfInstanceId);
+}
+
+/**
+ * One hub round: every reachable registered member, sequentially (D-2 — only the hub dials, and a
+ * slow member must not fan out into concurrent dials). A member inside its failure-backoff window is
+ * skipped (and its last state reported) so it never delays the others. After the round, tombstones
+ * are pruned only when every member that was attempted ended 'synced'.
+ *
+ * @param {object} deps { db, fetchImpl, env, peerHeadersFor, walle, now, selfInstanceId }
+ */
+async function runBrainMemberRound(deps = {}) {
+  if (_inFlight) return { ok: true, skipped: 'in_flight', members: [], pruned: 0 };
+  const env = deps.env || process.env;
+  if (!_brainSyncEnabled(env)) {
+    return { ok: true, disabled: true, members: [], pruned: 0 };
+  }
+  _inFlight = _runRound(deps).finally(() => { _inFlight = null; });
+  return _inFlight;
+}
+
+async function _runRound(deps = {}) {
+  const env = deps.env || process.env;
+  const nowMs = _now(deps);
+  const selfInstanceId = _resolveSelfInstanceId(deps, env);
+  const walle = deps.walle || require('./walle-client');
+  const candidates = _candidateMembers(deps.db, selfInstanceId);
+  // WP-5: resolved once per round — the CTM store handle the conversation feed reads (see
+  // _conversationDb). Null means this node has no conversation store to exchange, and the leg is
+  // skipped without a per-member `conversation` verdict.
+  const conversationEnabled = _conversationSyncEnabled(env);
+  const conversationDb = conversationEnabled ? _conversationDb(deps.db) : null;
+  const members = [];
+  for (const member of candidates) {
+    const instanceId = _string(member.instanceId);
+    const prior = _memberState.get(instanceId);
+    if (prior && prior.nextAt > nowMs) {
+      members.push({ instanceId, state: prior.state || 'unreachable', pulled: 0, pushed: 0, backoff: true });
+      continue;
+    }
+    let result;
+    try {
+      result = await syncMemberBrainOnce(member, {
+        fetchImpl: deps.fetchImpl,
+        peerHeadersFor: deps.peerHeadersFor,
+        walle,
+        env,
+        now: deps.now,
+        pageLimit: deps.pageLimit,
+        maxPages: deps.maxPages,
+        // WP-4 (§5 D-6): the join state machine's own seams. Absent -> memory-join's defaults.
+        chunksPerTick: deps.chunksPerTick,
+        readChunk: deps.readChunk,
+      });
+    } catch (err) {
+      result = { ok: false, member: instanceId, state: 'error', pulled: 0, pushed: 0, error: err?.message || String(err) };
+    }
+    // WP-5 (§5 D-3, §6.8): the conversation-history leg runs AFTER the brain leg and is
+    // independent of its verdict — a member mid-join still exchanges items (no snapshot needed),
+    // and a broken conversation leg must never turn a green brain leg red.
+    let conversation = null;
+    if (conversationDb) {
+      try {
+        conversation = await syncMemberConversationOnce(member, {
+          db: conversationDb,
+          fetchImpl: deps.fetchImpl,
+          peerHeadersFor: deps.peerHeadersFor,
+          env,
+          pageLimit: deps.pageLimit,
+          maxPages: deps.maxPages,
+        });
+      } catch (err) {
+        conversation = { ok: false, state: 'error', pulled: 0, pushed: 0, error: err?.message || String(err) };
+      }
+    } else if (!conversationEnabled) {
+      conversation = { ok: true, state: 'disabled', pulled: 0, pushed: 0 };
+    }
+    members.push({
+      instanceId,
+      state: result.state,
+      pulled: result.pulled,
+      pushed: result.pushed,
+      ...(result.error ? { error: result.error } : {}),
+      ...(result.detail ? { detail: result.detail } : {}),
+      ...(conversation ? { conversation } : {}),
+    });
+    if (result.state === 'unreachable' || result.state === 'error') {
+      const attempt = ((prior && Number(prior.attempts)) || 0) + 1;
+      _memberState.set(instanceId, { attempts: attempt, nextAt: nowMs + _failureDelayMs(env, attempt, deps), state: result.state });
+    } else {
+      _memberState.delete(instanceId);
+    }
+  }
+
+  let pruned = 0;
+  if (members.length > 0 && members.every((m) => m.state === 'synced')) {
+    try {
+      const res = await _walleRequest(walle, LOCAL_PATHS.pruneTombstones, { method: 'POST', body: {} });
+      if (res.json && Number.isFinite(Number(res.json.pruned))) pruned = Number(res.json.pruned) || 0;
+    } catch {
+      pruned = 0; // REPORT: prune is best-effort; a failure leaves the tombstones and the next round retries
+    }
+  }
+
+  _lastRound = { at: new Date(nowMs).toISOString(), members };
+  // A member mid-join is not an error (it is making progress); only a broken exchange flips `ok`.
+  return { ok: members.every((m) => JOIN_PROGRESS_STATES.has(m.state) || m.state === 'synced' || m.state === 'seed_pending'), members, pruned };
+}
+
+/** Observability only (no route in this WP): the last round's verdict per member. */
+function memorySyncStatus() {
+  return {
+    lastRoundAt: _lastRound ? _lastRound.at : null,
+    members: _lastRound ? _lastRound.members : [],
+  };
+}
+
+/** Test seam: forget the per-member backoff + last round (module state survives a process). */
+function _resetMemorySyncStateForTests() {
+  _memberState.clear();
+  _lastRound = null;
+  _inFlight = null;
+}
+
+module.exports = {
+  syncMemberBrainOnce,
+  syncMemberConversationOnce,
+  runBrainMemberRound,
+  memorySyncStatus,
+  _resetMemorySyncStateForTests,
+};

package/template/coding-task-manager/lib/migrations/v56-host-samples-and-machine-pool.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// WP-1 (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §5 D-4/D-7/D-11, §6.1, §8 WP-1,
+// §9 S-3): the machine-pool schema, in one migration because every piece of it lands with the same
+// reader (lib/host-stats.js today; WP-2/WP-3 for the pairing/self tables).
+//
+//   host_samples           D-11 — the box owns its own 24 h time series (one row per 60 s tick;
+//                                 ≤1440 rows/machine). No hub-side samples table exists.
+//   machine_self           D-4 rev 2 — this machine's OWN user settings (display name, favorite,
+//                                 hidden). Exactly one row, id = 1.
+//   machine_pairing_offers D-6 — the RFC 8628-shaped code a joining member redeems. The plaintext
+//                                 code is never stored, only its hash.
+//   machines.urls_json     P-1/P-4 rev 2 — the member's dialable URLs in dial order.
+//
+// Rev 2 deliberately has NO peer_credentials table: D-7 is one shared pool secret in
+// machine-pool.json, never in the DB.
+//
+// The shape follows v55-agent-origin-backfill.js: a narrow dependency object, idempotent SQL, and
+// the version stamp LAST so a failure leaves the ladder where it was. ALTER TABLE has no
+// `IF NOT EXISTS` in SQLite, so the column add is guarded by its own PRAGMA read — which also
+// makes a re-run (a restored snapshot, a partially upgraded file) a no-op rather than an error.
+
+const TABLES_DDL = `
+  CREATE TABLE IF NOT EXISTS host_samples (
+    at INTEGER PRIMARY KEY,
+    sample_json TEXT NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS machine_self (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    display_name TEXT NOT NULL DEFAULT '',
+    favorite INTEGER NOT NULL DEFAULT 0,
+    hidden INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0
+  );
+  CREATE TABLE IF NOT EXISTS machine_pairing_offers (
+    id TEXT PRIMARY KEY,
+    code_hash TEXT NOT NULL UNIQUE,
+    created_at INTEGER NOT NULL,
+    expires_at INTEGER NOT NULL,
+    redeemed_at INTEGER,
+    redeemed_by TEXT
+  );
+`;
+
+function _tableExists(db, table) {
+  try {
+    return !!db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
+  } catch {
+    return false; // expected: a handle that cannot read sqlite_master (pre-boot) has nothing to alter
+  }
+}
+
+function _tableHasColumn(db, table, column) {
+  try {
+    return db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === column);
+  } catch {
+    return false; // expected: no such table on an old/partial database -> nothing to alter
+  }
+}
+
+function migrateToV56({ getDb, setSchemaVersion, log = console } = {}) {
+  if (typeof getDb !== 'function' || typeof setSchemaVersion !== 'function') throw new TypeError('migration dependencies are required');
+  const db = getDb();
+  db.exec(TABLES_DDL);
+  // S-3: existing databases get the column by ALTER; db.js's machines CREATE literal carries the
+  // same column for a fresh file, and the two must stay in the same ordinal position.
+  let altered = 0;
+  if (_tableExists(db, 'machines') && !_tableHasColumn(db, 'machines', 'urls_json')) {
+    db.exec("ALTER TABLE machines ADD COLUMN urls_json TEXT NOT NULL DEFAULT '[]'");
+    altered = 1;
+  }
+  setSchemaVersion(56);
+  log.log(`[db] Schema migrated to v56 (host samples + machine pool): ${altered} column(s) added`);
+}
+
+module.exports = { migrateToV56 };