create-walle 0.10.2 → 0.10.3

package/template/wall-e/memory/hub-bridge-client.js

@@ -0,0 +1,388 @@
+'use strict';
+
+// WP-1 (docs/remote-session-hub-bridge-2026-10-30.html §5 R-10, §6.4, §8 WP-1): the Wall-E half of
+// the CTM hub-bridge lane.
+//
+//   GET  /api/hub-bridge/status -> { role, hubs, poolMembers }        (R-10's pool probe)
+//   POST /api/hub-bridge/call   <- { callerSessionId, op, args }      (`session.read`)
+//
+// Base-URL/token resolution is the SAME one every other CTM call in this package uses
+// (memory/ctm-context-client.js:12-17 + `_ctmToken`) — never a second hand-rolled client, and CTM
+// stays the authority: this module runs nothing itself.
+//
+// R-1/R-2/R-2b (design-hub-bridge-box-session-awareness-2026-10-31.html §5, §6.3, §8 WP-0): the
+// visibility gate is per SESSION, not per pool. Every `hub_*` tool is listed when this session has a
+// creator-hub record on the box CTM (`status.session.hubInstanceId`) or the CTM reports
+// `role === 'box'`; it is hidden only when CTM answers, reports another role, and reports
+// `session: null`. `poolMembers` gates NOTHING (a real box reports poolMembers: 0 while connected).
+// An unreachable or older CTM lists the tools (R-2): a call then answers the named `hub_unreachable`,
+// so the served contract stays independent of whether a CTM happens to be running (hermetic tests).
+//
+// A "visible" answer is final for the process; a "hidden" one is re-checked at most once per
+// HIDE_RECHECK_MS (R-2b), so a hub link that opens later is seen within one mesh tick.
+//
+// WP-2/WP-3: the same memoised probe feeds `boxContext()` (the "where you run" block) and, on stdio
+// only, the re-probe timer that emits notifications/tools/list_changed once hidden -> visible.
+
+// The ONE base-URL resolution (ctm-context-client.js:12-17). Reused, not re-implemented: a second
+// copy is exactly how CTM_PORT/DEV_CTM_PORT drift apart.
+const { resolveApiBaseUrl } = require('./ctm-context-client');
+
+const HUB_TOOL_PREFIX = 'hub_';
+const DEFAULT_STATUS_TIMEOUT_MS = 1500;
+const DEFAULT_DEADLINE_MS = 30000;
+// R-2b: the re-check interval equals CTM's mesh reconcile interval (coding-task-manager
+// lib/hub-bridge-mesh.js MESH_INTERVAL_MS), so a hub link that just opened is seen within one tick.
+const HIDE_RECHECK_MS = 30000;
+// R-8: the box-side deadline bounds the bridge call; the HTTP client waits a fixed 2 s longer so a
+// deadline exhaustion is reported by the BOX (`hub_unreachable`, message 'deadline') rather than by
+// a client-side abort that cannot say what happened.
+const DEADLINE_GRACE_MS = 2000;
+// R-8: exec may run 120 s on the hub; its bridge deadline is that plus the 2 s grace, so the box
+// never gives up on a command CTM is still allowed to finish (EXEC_MAX_TIMEOUT_MS + 2000).
+const EXEC_MAX_TIMEOUT_MS = 120000;
+const EXEC_DEFAULT_TIMEOUT_MS = 30000;
+const MAX_DEADLINE_MS = EXEC_MAX_TIMEOUT_MS + DEADLINE_GRACE_MS;
+// WP-3 (§6.4/§8): a hub MCP call may spawn a server and do a browser round-trip, so its bridge
+// deadline is longer than the read family's 20 s — but 25 s + the client's 2 s grace stays under the
+// stdio proxy's 30 s default (bin/walle-mcp-stdio.js, not edited).
+const MCP_DEADLINE_MS = 25000;
+
+// R-2b (WP-0): the probe memo, keyed by session id (a stdio proxy has exactly one). Each entry is
+// `{ promise, at, visible, hide, status }`; `_resetForTests()` clears the whole map. A separate map
+// holds the stdio-only re-probe timers (WP-3) so a second initialize cannot arm a second interval.
+const _memos = new Map();
+const _listChangedTimers = new Map();
+
+function _token(env) {
+  return env.CTM_TOKEN || env.WALLE_CTM_TOKEN || env.CTM_API_TOKEN;
+}
+
+async function requestJson(url, { method = 'GET', body, timeoutMs = DEFAULT_STATUS_TIMEOUT_MS, token } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1, Number(timeoutMs) || DEFAULT_STATUS_TIMEOUT_MS));
+  try {
+    const headers = { Accept: 'application/json' };
+    let payload;
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      payload = JSON.stringify(body);
+    }
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const response = await fetch(url, { method, headers, body: payload, signal: controller.signal });
+    const text = await response.text();
+    return text ? JSON.parse(text) : {};
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * `GET /api/hub-bridge/status[?session=<id>]`, or null when CTM is unreachable. Never throws.
+ * R-1: the optional `session` query asks CTM for THIS session's creator-hub record, which is the
+ * per-session fact the visibility gate reads.
+ */
+async function fetchStatus({ env = process.env, timeoutMs = DEFAULT_STATUS_TIMEOUT_MS, sessionId = '' } = {}) {
+  const baseUrl = resolveApiBaseUrl(env);
+  if (!baseUrl) return null;
+  const id = String(sessionId == null ? '' : sessionId).trim();
+  const query = id ? `?session=${encodeURIComponent(id)}` : '';
+  try {
+    return await requestJson(`${baseUrl}/api/hub-bridge/status${query}`, { timeoutMs, token: _token(env) });
+  } catch {
+    // REPORT: an unreachable or older (404) CTM answers null; R-2 then LISTS the hub_* tools (see
+    // resolveHideTools) and a call answers the named hub_unreachable instead.
+    return null;
+  }
+}
+
+/**
+ * `POST /api/hub-bridge/call`. Resolves the bridge body verbatim — `{ok:true, result}` or
+ * `{ok:false, error:{code,message}}` — and NEVER throws: a transport failure is the same named
+ * `hub_unreachable` a bridge refusal is, so the caller has exactly one error shape to handle.
+ */
+async function callHubBridge({ callerSessionId, op, args, machine, deadlineMs, env = process.env } = {}) {
+  const baseUrl = resolveApiBaseUrl(env);
+  if (!baseUrl) {
+    return { ok: false, error: { code: 'hub_unreachable', message: 'ctm_api_unavailable: CTM base URL not resolvable' } };
+  }
+  const bounded = Math.min(Math.max(1, Number(deadlineMs) || DEFAULT_DEADLINE_MS), MAX_DEADLINE_MS);
+  const wanted = String(machine == null ? '' : machine).trim();
+  try {
+    const body = await requestJson(`${baseUrl}/api/hub-bridge/call`, {
+      method: 'POST',
+      body: {
+        callerSessionId: String(callerSessionId || ''),
+        op: String(op || ''),
+        args: args === undefined ? {} : args,
+        // WP-5 (R-12): the target machine is a TOP-LEVEL field of the bridge body (an instance id or
+        // a display name) — never part of `op`'s args. Omitted entirely when unnamed, so the bridge's
+        // own default (the machine driving this session) applies.
+        ...(wanted ? { machine: wanted } : {}),
+        deadlineMs: bounded,
+      },
+      timeoutMs: bounded + DEADLINE_GRACE_MS,
+      token: _token(env),
+    });
+    if (!body || typeof body !== 'object' || typeof body.ok !== 'boolean') {
+      return { ok: false, error: { code: 'hub_unreachable', message: 'hub bridge returned an unexpected body' } };
+    }
+    return body;
+  } catch (error) {
+    return { ok: false, error: { code: 'hub_unreachable', message: String((error && error.message) || error) } };
+  }
+}
+
+/**
+ * R-1/R-2: is this session a BOX session (so every `hub_*` tool is listed)? True when CTM reports a
+ * creator-hub record for the session (`session.hubInstanceId`) or `role === 'box'`; also true for the
+ * UNKNOWN case (status null/non-object or with no `role` key, R-2), because listing is the safe
+ * failure — a call on a machine that cannot reach a hub answers the named `hub_unreachable`.
+ * `poolMembers` is never consulted.
+ */
+function isBoxSession(status) {
+  if (!status || typeof status !== 'object') return true;
+  if (!Object.prototype.hasOwnProperty.call(status, 'role')) return true;
+  const sessionHub = status.session && status.session.hubInstanceId;
+  return Boolean(sessionHub) || status.role === 'box';
+}
+
+/**
+ * R-1/R-2: `{ hide, status }` for one probe. `hide` names every `hub_*` tool iff this is NOT a box
+ * session; `status` is the raw answer (null when CTM is unreachable), so `boxContext()` can read the
+ * display names from the SAME probe. Never throws (fetchStatus already answers null on any fault).
+ */
+async function resolveHideTools({ tools = [], env = process.env, timeoutMs = DEFAULT_STATUS_TIMEOUT_MS, sessionId = '' } = {}) {
+  const status = await fetchStatus({ env, timeoutMs, sessionId });
+  if (isBoxSession(status)) return { hide: new Set(), status };
+  const hide = new Set((Array.isArray(tools) ? tools : [])
+    .map((tool) => String((tool && tool.name) || ''))
+    .filter((name) => name.startsWith(HUB_TOOL_PREFIX)));
+  return { hide, status };
+}
+
+/** The memoised probe for one session: shared in-flight probe, one per HIDE_RECHECK_MS while hidden. */
+function _probe({ sessionId = '', tools, env = process.env, now = Date.now, timeoutMs = DEFAULT_STATUS_TIMEOUT_MS } = {}) {
+  const key = String(sessionId == null ? '' : sessionId);
+  const clock = typeof now === 'function' ? now : () => now;
+  const existing = _memos.get(key);
+  if (existing) {
+    // R-2b: a visible result is FINAL; a hidden one is reused until HIDE_RECHECK_MS has passed
+    // (concurrent callers therefore share the one in-flight probe — T-7).
+    if (existing.visible || clock() - existing.at < HIDE_RECHECK_MS) return existing.promise;
+  }
+  const entry = { at: clock(), visible: false, hide: new Set(), status: null, promise: null };
+  entry.promise = resolveHideTools({ tools: tools || require('../mcp-contract').MCP_TOOLS, env, timeoutMs, sessionId: key })
+    .then(({ hide, status }) => {
+      entry.hide = hide;
+      entry.status = status;
+      entry.visible = hide.size === 0;
+      return entry;
+    })
+    .catch(() => entry); // expected: resolveHideTools never rejects; a fault lists the tools
+  _memos.set(key, entry);
+  return entry.promise;
+}
+
+/** The set of tool names to hide from tools/list for this session (R-1/R-2, memoised per R-2b). */
+function hideTools(options = {}) {
+  return _probe(options).then((entry) => entry.hide);
+}
+
+/**
+ * R-4 (WP-2): `null | { boxName, hubName, hubConnected }` read from the SAME memoised probe as
+ * `hideTools` — non-null only for a box session whose hub name CTM actually reported.
+ */
+async function boxContext(options = {}) {
+  const entry = await _probe(options);
+  const status = entry.status;
+  // R-2: isBoxSession is TRUE for the unknown case (null/no `role`), but an unknown status carries
+  // no names to put in the block, so the context is null there as well.
+  if (!status || typeof status !== 'object') return null;
+  if (!isBoxSession(status)) return null;
+  const session = status.session && status.session.hubInstanceId ? status.session : null;
+  const hubs = Array.isArray(status.hubs) ? status.hubs : [];
+  const hub = session || (hubs.length === 1 ? hubs[0] : null);
+  const hubName = String((hub && hub.hubDisplayName) || '').trim();
+  if (!hubName) return null;
+  const self = status.self && typeof status.self === 'object' ? status.self : null;
+  return {
+    boxName: String((self && (self.displayName || self.instanceId)) || '').trim(),
+    hubName,
+    hubConnected: hub.connected === undefined ? undefined : Boolean(hub.connected),
+  };
+}
+
+/** The stdio proxy's session key (R-1): the CTM session this proxy was spawned for, if any. */
+function proxySessionId(env = process.env) {
+  return String(env.CTM_SESSION_ID || '').trim();
+}
+
+function _clearListChangedWatcher(key) {
+  const entry = _listChangedTimers.get(key);
+  if (!entry) return;
+  (entry.clearIntervalFn || clearInterval)(entry.timer);
+  _listChangedTimers.delete(key);
+}
+
+/**
+ * R-6 (WP-3, stdio only): while this session's set is hidden, re-probe on ONE unref'd
+ * HIDE_RECHECK_MS timer. On hidden -> visible, write exactly one
+ * `notifications/tools/list_changed` through the proxy's own `writeMessage` and stop. It never
+ * emits visible -> hidden (a visible answer is final, so the timer is gone by then).
+ */
+function _armListChangedWatcher({ sessionId = '', env = process.env, writeMessage, now = Date.now, setIntervalFn = setInterval, clearIntervalFn = clearInterval } = {}) {
+  const key = String(sessionId == null ? '' : sessionId);
+  if (typeof writeMessage !== 'function' || _listChangedTimers.has(key)) return;
+  const timer = setIntervalFn(async () => {
+    if (!_listChangedTimers.has(key)) return; // a stale fire of a cleared interval writes nothing
+    const hide = await hideTools({ sessionId: key, env, now });
+    if (!hide || hide.size > 0) return;
+    _clearListChangedWatcher(key);
+    writeMessage({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' });
+  }, HIDE_RECHECK_MS);
+  if (typeof timer === 'object' && timer && typeof timer.unref === 'function') timer.unref();
+  _listChangedTimers.set(key, { timer, clearIntervalFn });
+}
+
+/**
+ * The proxy's initialize options (R-4/R-6): the "where you run" block from the SAME probe as the
+ * visibility gate, the listChanged capability, and — only while hidden — the re-probe timer. Kept
+ * here (not in bin/walle-mcp-stdio.js) because that file is at a frozen file-size ceiling.
+ */
+async function proxyInitializeOptions({ writeMessage, env = process.env, sessionId = proxySessionId(env), now = Date.now, setIntervalFn = setInterval, clearIntervalFn = clearInterval } = {}) {
+  const [hubContext, hide] = await Promise.all([
+    boxContext({ sessionId, env, now }),
+    hideTools({ sessionId, env, now }),
+  ]);
+  if (hide && hide.size > 0) _armListChangedWatcher({ sessionId, env, writeMessage, now, setIntervalFn, clearIntervalFn });
+  return { hubContext, listChanged: true };
+}
+
+/**
+ * The ONE helper bin/walle-mcp-stdio.js calls per control message (its own option lines are at a
+ * frozen ceiling): undefined for anything it does not own, `{hideTools}` for tools/list, and
+ * `{leadGuidance, hubContext, listChanged}` for initialize. `leadGuidance` is a lazy thunk so a
+ * tools/list never performs the daemon guidance read.
+ */
+async function controlPlaneOptions(message, { writeMessage, leadGuidance, env = process.env, sessionId = proxySessionId(env), now = Date.now, setIntervalFn = setInterval, clearIntervalFn = clearInterval } = {}) {
+  if (!message || Array.isArray(message)) return undefined;
+  if (message.method === 'initialize') {
+    const guidance = typeof leadGuidance === 'function' ? await leadGuidance() : (leadGuidance || null);
+    const init = await proxyInitializeOptions({ writeMessage, env, sessionId, now, setIntervalFn, clearIntervalFn });
+    return guidance ? { ...init, leadGuidance: guidance } : init;
+  }
+  if (message.method === 'tools/list') return { hideTools: await hideTools({ sessionId, env, now }) };
+  return undefined;
+}
+
+/** §6.4: `hub_exec`'s own timeout — default 30 s, hard max 120 s (CTM's exec ceiling). */
+function clampExecTimeoutMs(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return EXEC_DEFAULT_TIMEOUT_MS;
+  return Math.min(EXEC_MAX_TIMEOUT_MS, Math.max(1, Math.trunc(n)));
+}
+
+// tool name -> (tool args) => { op, opArgs, deadlineMs }. `session.read`'s 20 s deadline + the 2 s
+// grace stays inside the stdio proxy's 30 s default; exec's deadline outlasts CTM's own exec
+// timeout by the grace, so a command that hits it is reported by CTM (`timed_out`), never by a
+// local abort.
+//
+// WP-5 (R-12): `machine` is NOT an op arg — it is a top-level field of the bridge POST body (see
+// callHubBridge) and picks which connected hub answers. The op's args describe the WORK, the machine
+// describes the TARGET, and CTM never has to dig a routing field out of an op's payload.
+const HUB_TOOL_OPS = Object.freeze({
+  hub_session_read: (a) => ({
+    op: 'session.read',
+    opArgs: { ref: a.ref, query: a.query, max_messages: a.max_messages },
+    deadlineMs: Number(a.deadline_ms) || 20000,
+  }),
+  hub_read_file: (a) => ({
+    op: 'fs.read',
+    opArgs: { path: a.path, offset: a.offset, limit: a.limit },
+    deadlineMs: Number(a.deadline_ms) || DEFAULT_DEADLINE_MS,
+  }),
+  hub_list: (a) => ({
+    op: 'fs.list',
+    opArgs: { path: a.path, glob: a.glob },
+    deadlineMs: Number(a.deadline_ms) || DEFAULT_DEADLINE_MS,
+  }),
+  hub_exec: (a) => {
+    const timeoutMs = clampExecTimeoutMs(a.timeout_ms);
+    return {
+      op: 'exec',
+      opArgs: { command: a.command, cwd: a.cwd, timeout_ms: timeoutMs },
+      deadlineMs: timeoutMs + DEADLINE_GRACE_MS,
+    };
+  },
+  // WP-3 (§3 P-2, D-4, §6.4, §8 WP-3): drive a HUB-side browser MCP server (tier `browser`). The
+  // op names are CTM's (`mcp.list` / `mcp.call`); CTM owns the allowlist, the client lifecycle and
+  // every refusal code, and this table stays the ONE tool -> op mapping.
+  hub_mcp_list_tools: (a) => ({
+    op: 'mcp.list',
+    opArgs: { server: a.server },
+    deadlineMs: MCP_DEADLINE_MS,
+  }),
+  hub_mcp_call: (a) => ({
+    op: 'mcp.call',
+    opArgs: { server: a.server, tool: a.tool, arguments: a.arguments },
+    deadlineMs: MCP_DEADLINE_MS,
+  }),
+});
+
+/**
+ * Run one `hub_*` tool: map it to its op, call the bridge, and either return the bridge body or
+ * throw the NAMED refusal (R-7: never a local fallback). A `hub_grant_required` refusal tells the
+ * agent exactly which tier to ask the user for (R-4/R-5), and to retry once, not in a loop.
+ */
+async function runHubTool(name, args = {}, callerSessionId = '') {
+  const toOp = HUB_TOOL_OPS[name];
+  if (!toOp) throw Object.assign(new Error(`unknown hub tool: ${name}`), { code: 'unknown_hub_tool' });
+  if (!callerSessionId) {
+    throw Object.assign(
+      new Error('caller_unresolved: no caller session id — pass `session`, or run under a CTM session'),
+      { code: 'caller_unresolved' },
+    );
+  }
+  const { op, opArgs, deadlineMs } = toOp(args || {});
+  // Looked up on module.exports so a test can stub the transport (tests/hub-bridge-tool.test.js).
+  // WP-5 (R-12): the tool's `machine` rides the bridge body top-level, not the op args.
+  const bridge = await module.exports.callHubBridge({ callerSessionId, op, args: opArgs, machine: args && args.machine, deadlineMs });
+  if (!bridge.ok) {
+    const code = String((bridge.error && bridge.error.code) || 'hub_unreachable');
+    const message = String((bridge.error && bridge.error.message) || code);
+    const hint = code === 'hub_grant_required'
+      ? ` Ask the user to approve '${String((bridge.error && bridge.error.tier) || 'exec')}' for this session`
+        + ' in CTM (session toolbar or Machines page), then retry once.'
+      : '';
+    throw Object.assign(new Error(`${code}: ${message}${hint}`), { code, body: bridge });
+  }
+  return bridge;
+}
+
+function _resetForTests() {
+  _memos.clear();
+  for (const key of [..._listChangedTimers.keys()]) _clearListChangedWatcher(key);
+}
+
+module.exports = {
+  HUB_TOOL_PREFIX,
+  DEFAULT_STATUS_TIMEOUT_MS,
+  HIDE_RECHECK_MS,
+  HUB_TOOL_OPS,
+  MAX_DEADLINE_MS,
+  MCP_DEADLINE_MS,
+  callHubBridge,
+  clampExecTimeoutMs,
+  runHubTool,
+  fetchStatus,
+  isBoxSession,
+  hideTools,
+  boxContext,
+  proxySessionId,
+  proxyInitializeOptions,
+  controlPlaneOptions,
+  requestJson,
+  resolveHideTools,
+  _resetForTests,
+};

package/template/wall-e/memory/replica-origin.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// WP-5 (docs/cross-machine-session-context-2026-10-31.html §5 R-2/R-6, §8 WP-5): transcript
+// replication (shared-memory WP-5) writes a peer's items into the CTM conversation tables under a
+// synthetic ingest cursor `peer-sync:<origin instance id>:<session id>`
+// (coding-task-manager/lib/conversation-sync.js:45, :262-263). The prefix is re-typed here rather than
+// required, because that module pulls the whole CTM store graph into Wall-E. A session whose cursors
+// are ONLY such rows is a REPLICA of another machine's session: memory/ctm-session-context.js labels
+// it `replica_origin` and the pool serves it only when its owner is unreachable
+// (coding-task-manager/lib/session-context-locator.js). Kept out of ctm-session-context.js, which sits
+// at its file-size ceiling.
+const REPLICA_CURSOR_PREFIX = 'peer-sync:';
+const REPLICA_CURSOR_TABLE = 'conversation_ingest_cursor_v2';
+
+/**
+ * WP-5/R-6: the machine a replicated session came from, or '' when this machine ingested the session
+ * itself. ONE query per call (`conversation_ingest_cursor_v2` holds one row per source — thousands,
+ * not millions), then both checks in JS: the origin named by its `peer-sync:<origin>:<session>` rows,
+ * and whether ANY non-peer cursor ends in `:<session>` (which proves local ingestion, whatever else is
+ * present). '' for an unknown id, for a session with no cursor at all, and when the table is absent —
+ * today's state on every machine, where the answer is byte-identical to pre-replication behaviour.
+ */
+function createReplicaOriginLookup(db, hasTable) {
+  let sources = null;
+  const load = () => {
+    if (sources) return sources;
+    if (!hasTable(db, REPLICA_CURSOR_TABLE)) return null;
+    try {
+      sources = db.prepare(`SELECT source_id FROM ${REPLICA_CURSOR_TABLE}`).all() || [];
+    } catch {
+      /* expected: the cursor table is CTM-owned schema this module only reads — a renamed column
+         throws SQLITE_ERROR past the hasTable() guard; the session then reads as non-replica */
+      sources = [];
+    }
+    return sources;
+  };
+  return function replicaOriginOf(ids) {
+    const wanted = (Array.isArray(ids) ? ids : [ids])
+      .map((id) => String(id == null ? '' : id).trim())
+      .filter(Boolean);
+    const rows = wanted.length ? load() : null;
+    if (!rows) return '';
+    let origin = '';
+    for (const row of rows) {
+      const sourceId = String((row && row.source_id) || '');
+      const split = sourceId.lastIndexOf(':');
+      if (split <= 0) continue;
+      if (!wanted.includes(sourceId.slice(split + 1))) continue;
+      if (!sourceId.startsWith(REPLICA_CURSOR_PREFIX)) return ''; // a cursor of ours: not a replica
+      origin = sourceId.slice(REPLICA_CURSOR_PREFIX.length, split);
+    }
+    return origin;
+  };
+}
+
+module.exports = { createReplicaOriginLookup, REPLICA_CURSOR_PREFIX, REPLICA_CURSOR_TABLE };

package/template/wall-e/memory/session-pool.js

@@ -0,0 +1,135 @@
+'use strict';
+
+// WP-4 (docs/cross-machine-session-context-2026-10-31.html §5 R-7/R-8, §6.4, §8 WP-4) — the two
+// POOL legs a Wall-E tool takes when the caller session runs on a BOX driven by a hub:
+//
+//   sessionContextViaHub   (WP-3) a `walle_get_session` miss asks the hub over the bridge; the
+//                          hub's answer (with its own `location`/`searched`) becomes the result.
+//   searchSessionsAcrossPool (WP-4) `walle_search_sessions` runs the LOCAL CTM search (`scope=pool`,
+//                          so CTM itself fans out across its own pool) and, when the caller is a box
+//                          session, the hub's `session.search` op IN PARALLEL; the two lists are
+//                          merged by the ONE RRF implementation (`fusePoolResults`) and the answer
+//                          names every machine it heard from.
+//
+// Both legs share the same box test (`fetchStatus` -> `isBoxSession`) and the same bridge transport
+// (`hubBridgeClient.callHubBridge`, looked up on the module object at call time so a test can stub
+// it). This module lives beside wall-e/mcp-server.js rather than inside it: that file is under a
+// file-size ratchet and keeps only the call sites.
+
+const ctmContextClient = require('./ctm-context-client');
+const hubBridgeClient = require('./hub-bridge-client');
+const { callerLandingSessionId } = require('../lib/landing-mcp-tools');
+// R-7/D-6: the ONE reciprocal-rank-fusion implementation, shared with CTM's locator (the precedent
+// for a Wall-E -> CTM lib require is wall-e/session-files.js requiring lib/transcript-source).
+const { fusePoolResults } = require('../../coding-task-manager/lib/session-context-locator');
+
+// R-8: the same bounded bridge deadline the WP-3 context leg uses (lib/hub-bridge-client MAX_DEADLINE_MS).
+const HUB_DEADLINE_MS = 20000;
+
+/** The hub that drives this session, by display name — the `searched`/`machines` label (R-5). */
+function hubDisplayName(status) {
+  return String((((status || {}).session || ((status || {}).hubs || [])[0] || {}).hubDisplayName) || 'hub');
+}
+
+/** THIS box, as CTM reports it in the bridge status (`status.self`). */
+function selfMachine(status) {
+  const self = (status && status.self) || {};
+  return { machine_id: String(self.instanceId || ''), machine_name: String(self.displayName || '') };
+}
+
+/**
+ * R-7: the LOCAL CTM search, run with `scope=pool` so CTM fans its own pool out and merges by RRF.
+ * Never throws — a search that could not run is a named `ok:false` result, exactly like the other
+ * `safeCtm*` readers beside the tool dispatch.
+ */
+async function safeSearchLocal({ query, limit }) {
+  try {
+    return await ctmContextClient.searchSessions({ query, limit, scope: 'pool' });
+  } catch (err) {
+    return { ok: false, source: 'ctm-db', results: [], reason: err.message };
+  }
+}
+
+/**
+ * WP-3 (design §6.4, R-1/R-3): a session this machine cannot read may live on the hub that drives
+ * this box session — ONE bridge call asks it, and its answer (with `location`/`searched`) is returned;
+ * a dead hub keeps the local empty envelope and names the hub in `searched`.
+ */
+async function sessionContextViaHub(local, args, context) {
+  const callerSessionId = local && local.found === false ? callerLandingSessionId(args, context) : '';
+  if (!callerSessionId) return local;
+  const status = await hubBridgeClient.fetchStatus({ sessionId: callerSessionId });
+  if (!hubBridgeClient.isBoxSession(status)) return local;
+  const hubName = hubDisplayName(status);
+  const hub = await hubBridgeClient.callHubBridge({
+    callerSessionId, op: 'session.context', deadlineMs: HUB_DEADLINE_MS,
+    args: { ref: String(args.ref || args.session_id || args.source_id || ''), turn_limit: args.turn_limit, byte_limit: args.byte_limit, cursor: args.cursor, direction: args.direction },
+  });
+  const miss = Array.isArray(local.searched) ? local.searched : [];
+  if (!hub.ok) return { ...local, searched: [...miss, { machine_name: hubName, status: String((hub.error && hub.error.code) || 'hub_unreachable') }] };
+  const result = hub.result && typeof hub.result === 'object' ? hub.result : {};
+  return { ...result, searched: [...(Array.isArray(result.searched) ? result.searched : []), ...miss] };
+}
+
+/**
+ * R-7 (design §6.4): `walle_search_sessions`'s CTM leg. The local CTM search starts immediately
+ * (`scope=pool`); when the caller session is a BOX session, the hub's `session.search` op runs IN
+ * PARALLEL and the two ranked lists are merged by `fusePoolResults`. The local result object is the
+ * base (`ok`/`source`/`reason`/… feed the tool's `sources` block); only `results` and `machines` are
+ * replaced. Rows keep the `machine_id`/`machine_name` they were ranked with — a row that came from
+ * another box through the hub is still tagged with THAT box, never with the hub.
+ */
+async function searchSessionsAcrossPool({ query, limit, args = {}, context } = {}) {
+  const callerSessionId = callerLandingSessionId(args, context);
+  const localPromise = safeSearchLocal({ query, limit });
+  // R-2: the box test is the same probe the WP-3 context leg makes — no caller session, no probe.
+  const status = callerSessionId ? await hubBridgeClient.fetchStatus({ sessionId: callerSessionId }) : null;
+  const isBox = Boolean(callerSessionId) && hubBridgeClient.isBoxSession(status);
+  const hubPromise = isBox
+    ? hubBridgeClient.callHubBridge({
+      callerSessionId, op: 'session.search', args: { query, limit }, deadlineMs: HUB_DEADLINE_MS,
+    })
+    : null;
+  const local = await localPromise;
+  const localRows = Array.isArray(local && local.results) ? local.results : [];
+  if (!isBox) {
+    // A hub caller's CTM already fanned out (its own route merged the pool and labelled every row),
+    // so the answer is relayed as is — `machines` included when CTM sent one.
+    return { ...local, machines: Array.isArray(local && local.machines) ? local.machines : [] };
+  }
+
+  const self = selfMachine(status);
+  const hubName = hubDisplayName(status);
+  const selfEntry = { ...self, status: 'ok', count: localRows.length };
+  const lists = [{ ...self, owner: true, rows: localRows }];
+  const hub = await hubPromise;
+  let machines = [selfEntry];
+  if (!hub || hub.ok !== true) {
+    // R-7 partial results: the hub's failure is a NAMED per-machine status, never a lost local answer.
+    machines = [
+      selfEntry,
+      { machine_name: hubName, status: String((hub && hub.error && hub.error.code) || 'hub_unreachable') },
+    ];
+  } else {
+    const result = hub.result && typeof hub.result === 'object' ? hub.result : {};
+    const hubMachines = Array.isArray(result.machines) ? result.machines : [];
+    // The hub's list is the hub's own view (its self entry first); rows it carries already name the
+    // machine each came from, so the hub's id is only the fallback label for an unlabelled row.
+    const hubSelf = hubMachines[0] || {};
+    lists.push({
+      machine_id: String(hubSelf.machine_id || ''),
+      machine_name: String(hubSelf.machine_name || hubName),
+      owner: false,
+      rows: Array.isArray(result.results) ? result.results : [],
+    });
+    machines = [...hubMachines, selfEntry];
+  }
+  return { ...local, results: fusePoolResults(lists, { limit }), machines };
+}
+
+module.exports = {
+  HUB_DEADLINE_MS,
+  sessionContextViaHub,
+  searchSessionsAcrossPool,
+  safeSearchLocal,
+};

package/template/wall-e/runtime/live-capabilities.js

@@ -2,6 +2,8 @@
 
 const os = require('node:os');
 const { getSlackReadToolNames, slackReadToolsEnabled, getIMessageReadToolNames, imessageReadToolsEnabled } = require('../mcp-tool-registry');
+// WP-2 (D-8): name the exec an FDA grant must actually carry, not a fixed bundle path.
+const { fdaTargetForExec } = require('../../shared/macos-fda-target');
 
 // surface-redesign WP-5a (D-12): the `connections` record — not the presence of a
 // token file — is the authority for "is this connected?". The reader comes from
@@ -222,6 +224,9 @@ function inspectIMessage(opts = {}, warnings, errors, lane = 'chat') {
   const fs = opts.fs || require('fs');
   const reader = require('../lib/imessage/chat-db-reader');
   const dbPath = opts.imessageDbPath || reader.DEFAULT_DB_PATH;
+  // D-8: the FDA grant is charged to the exec that runs (launchd's job exec / its children),
+  // e.g. `~/.walle/notarized-node/bin/node` on a host with no Wall-E.app bundle.
+  const fdaTarget = fdaTargetForExec(opts.execPath || process.execPath, opts.fdaDeps);
   const coding = lane === 'coding';
   const readTools = coding ? getIMessageReadToolNames(env) : ['imessage_search', 'imessage_read_chat'];
   try {
@@ -248,14 +253,14 @@ function inspectIMessage(opts = {}, warnings, errors, lane = 'chat') {
     const available = connected && flagOn && lastIngestAt !== null;
     const note = platform !== 'darwin' ? 'iMessage is macOS-only'
       : !dbPresent ? 'Messages database not found at ~/Library/Messages/chat.db'
-      : !fullDiskAccess ? 'Grant Full Disk Access to the Wall-E node binary in System Settings → Privacy & Security → Full Disk Access, then restart Wall-E'
+      : !fullDiskAccess ? `Grant Full Disk Access to ${fdaTarget ? fdaTarget.path : 'the Wall-E process binary'} in System Settings → Privacy & Security → Full Disk Access, then restart Wall-E`
       : !flagOn ? 'iMessage read tools disabled in the coding lane (WALLE_MCP_IMESSAGE_READ=0)'
       : lastIngestAt === null ? 'iMessage ingest has not run yet'
       : `iMessage mirror current as of ${lastIngestAt}`;
-    return { available, connected, dbPresent, fullDiskAccess, lastIngestAt, maxRowid, readTools, writeTools: [], note };
+    return { available, connected, dbPresent, fullDiskAccess, fdaTarget, lastIngestAt, maxRowid, readTools, writeTools: [], note };
   } catch (err) {
     errors.push({ capability: 'imessage', message: err.message });
-    return { available: false, connected: false, dbPresent: false, fullDiskAccess: false, lastIngestAt: null, maxRowid: null, readTools, writeTools: [], note: err.message };
+    return { available: false, connected: false, dbPresent: false, fullDiskAccess: false, fdaTarget: null, lastIngestAt: null, maxRowid: null, readTools, writeTools: [], note: err.message };
   } // HANDLE: capability report must never throw
 }
 

package/template/wall-e/server.js

@@ -110,8 +110,10 @@ function isMcpAutoConfigDisabled() {
 
 async function autoConfigureWallEMcp() {
   if (isMcpAutoConfigDisabled()) return;
+  let failureMessage = (err) => err.message;
   try {
-    const { ensureMcpIntegrations, getMcpAutoConfigSkipReason } = require('./lib/mcp-integration');
+    const { ensureMcpIntegrations, getMcpAutoConfigSkipReason, ensureFailureMessage } = require('./lib/mcp-integration');
+    failureMessage = ensureFailureMessage;
     if (getMcpAutoConfigSkipReason(process.env)) return;
     const results = await ensureMcpIntegrations(PORT);
     const changed = results.filter(r => r.kind === 'mcp_config' && (r.action === 'added' || r.action === 'updated'));
@@ -127,7 +129,7 @@ async function autoConfigureWallEMcp() {
       console.warn(`[wall-e] Wall-E MCP auto-config skipped ${errors.length} invalid config file(s): ${errors.map(r => r.tool).join(', ')}`);
     }
   } catch (err) {
-    console.warn(`[wall-e] Wall-E MCP auto-config failed: ${err.message}`);
+    console.warn(`[wall-e] Wall-E MCP auto-config failed: ${failureMessage(err)}`);
   }
 }
 

package/template/wall-e/shared/release-schema.json

@@ -9,7 +9,7 @@
         21, 22, 23, 24, 25, 26, 27, 28, 29, 30,
         31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
         41, 42, 43, 44, 45, 46, 47, 48, 49, 50,
-        51, 52, 53, 54, 55, 56
+        51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61
       ]
     },
     "walle": {
@@ -25,7 +25,7 @@
         71, 72, 73, 74, 75, 76, 77, 78, 79, 80,
         81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96,
         97, 98, 99, 100,
-        101
+        101, 102, 103, 104, 105
       ]
     }
   }