create-walle 0.10.1 → 0.10.3

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

@@ -0,0 +1,721 @@
+'use strict';
+
+// WP-1/WP-3 (docs/remote-session-hub-bridge-2026-10-30.html §5 R-3/R-12, §6.4, §8 WP-1/WP-3;
+// docs/cross-machine-session-context-2026-10-31.html §5 R-3/R-5/R-8, §6.3, §8 WP-3): the HUB-side
+// READ ops a box asks for over the WP-0 lane (lib/hub-bridge.js `handleRequest`).
+//
+//   session.context  resolve ONE session id ANYWHERE in the pool and answer with it — the hub order
+//                    of lib/session-context-locator.js (local -> directory owner -> parallel probe),
+//                    minus the calling machine, which already read locally.
+//   session.read     the same resolution, projected for a reader (R-9): role/at/kind/text only.
+//
+// R-3: the resolver is lib/session-context-locator.js; its LOCAL leg is INJECTED
+// (`deps.readSessionContext`) and in production is the SAME off-thread read-pool runner
+// `/api/ctm/session-memory/context` uses, so a full session-context read (multiple FTS/LIKE scans +
+// a JSON.parse of matched conversations) never runs on the hub's main loop for a remote caller.
+// R-12: an optional `machine` target is ACCEPTED AND IGNORED here — target selection is WP-5's.
+//
+// Every refusal is a NAMED code (`session_ref_invalid`, `session_on_caller`, `session_not_found`,
+// `session_read_unavailable`) carried on the thrown error's `code`, which lib/hub-bridge.js maps into
+// the error frame. The old `session_on_other_machine` is GONE (WP-3): a session that lives on another
+// machine is now forwarded to, not refused.
+
+// The SAME identity parser the search box uses (a hub link's `#session=<id>` / `review=<id>` / bare
+// uuid), so a ref that the UI accepts is a ref this op accepts — including URL-encoded variants.
+const SessionSearchUtils = require('../public/js/session-search-utils');
+
+const childProcess = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULT_MAX_MESSAGES = 40;
+const MAX_MESSAGES = 200;
+// WP-3 (§6.3, R-8): the byte ceiling a session read asks the resolver for — HALF the bridge lane's
+// own 1 MiB RESULT_MAX_BYTES (lib/hub-bridge.js), so an answer can never be truncated in flight.
+const SESSION_CONTEXT_BYTE_LIMIT = 512 * 1024;
+// WP-4 (§6.3): the pool-search args a box may ask for. `limit` is the RESULT-ROW budget the hub
+// merges into; the deadline bounds the off-thread read the hub runs on the caller's behalf.
+const SESSION_SEARCH_DEFAULT_LIMIT = 10;
+const SESSION_SEARCH_MAX_LIMIT = 50;
+const SESSION_SEARCH_TIMEOUT_MS = 20000;
+
+// WP-2 (docs/remote-session-hub-bridge-2026-10-30.html §5 R-4/R-8, §6.4, §8 WP-2): the host ops a
+// GRANTED box session asks the hub to run — `fs.read`, `fs.list` (tier `read`) and `exec` (tier
+// `exec`). R-8 bounds them the same way the lane bounds everything: <= 1 MiB of file, <= 2000
+// directory entries, <= 16 KiB of command, <= 256 KiB of each output stream, <= 120 s of wall clock.
+// Deliberately NO command denylist (design anti-goal): the boundary is the user's GRANT, not a
+// string filter.
+const FS_READ_CAP_BYTES = 1024 * 1024;
+const FS_READ_DEFAULT_LIMIT = 2000;
+const FS_READ_MAX_LIMIT = 2000;
+const FS_LIST_MAX_ENTRIES = 2000;
+const EXEC_MAX_COMMAND_BYTES = 16 * 1024;
+const EXEC_DEFAULT_TIMEOUT_MS = 30000;
+const EXEC_MAX_TIMEOUT_MS = 120000;
+const EXEC_OUTPUT_CAP_BYTES = 256 * 1024;
+const EXEC_KILL_GRACE_MS = 1000;
+// A box-requested command runs as the hub USER, not as the hub's CTM: CTM's own runtime env (the
+// peer token, the Wall-E bearer, CTM_PORT/CTM_DATA_DIR that would make a nested `ctm`/`land` call
+// speak as this server) is not handed to it. The user's login shell (`-lc`) still sets up PATH etc.
+const EXEC_ENV_DROP_RE = /^(CTM_|WALLE_|WALL_E_)/;
+
+/** process.env minus CTM's own runtime keys (EXEC_ENV_DROP_RE). Pure. */
+function execChildEnv(parentEnv = process.env) {
+  const out = {};
+  for (const [key, value] of Object.entries(parentEnv || {})) {
+    if (!EXEC_ENV_DROP_RE.test(key)) out[key] = value;
+  }
+  return out;
+}
+
+/** Clamp a possibly-junk numeric arg into [min, max] with `fallback` for a non-number. */
+function clampInt(value, fallback, min, max) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(n)));
+}
+
+/** `*` / `?` name glob -> predicate, or null for "match everything". Deliberately not a path glob. */
+function compileNameGlob(glob) {
+  const raw = String(glob == null ? '' : glob);
+  if (!raw) return null;
+  const escaped = raw.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.');
+  const re = new RegExp(`^${escaped}$`);
+  return (name) => re.test(name);
+}
+
+/** dirent -> the wire's three-value type, then its size (lstat for a link, so a dangling one still works). */
+async function _entrySize(fullPath, dirent) {
+  try {
+    const stat = dirent.isSymbolicLink() ? await fs.promises.lstat(fullPath) : await fs.promises.stat(fullPath);
+    return Number(stat.size) || 0;
+  } catch {
+    // REPORT via 0: an entry that vanished or is unreadable between readdir and stat keeps its row.
+    return 0;
+  }
+}
+
+
+/** A refusal as the lane speaks it: the code rides the error, never the message. */
+function _namedError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+/**
+ * Clamp `max_messages`: default 40, hard max 200 (§6.4). A missing/blank/non-numeric value is the
+ * default; a numeric value is truncated to a whole number and pinned into [1, 200].
+ */
+function clampMaxMessages(value) {
+  if (value === undefined || value === null || value === '') return DEFAULT_MAX_MESSAGES;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return DEFAULT_MAX_MESSAGES;
+  return Math.min(MAX_MESSAGES, Math.max(1, Math.trunc(n)));
+}
+
+/**
+ * The byte count of a message whose payload was NOT persisted (an over-cap envelope carries
+ * `payload.raw_bytes` — wall-e/memory/session-context-page.js `oversizedEnvelope`; the paged/
+ * grouped variants carry `raw_bytes_at_least`). 0 when the envelope has neither, so the box
+ * always reads a number.
+ */
+function omittedByteCount(message) {
+  const payload = message && typeof message.payload === 'object' && message.payload ? message.payload : {};
+  for (const key of ['raw_bytes', 'raw_bytes_at_least']) {
+    const raw = payload[key];
+    if (raw === undefined || raw === null) continue;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return Math.trunc(n);
+  }
+  const direct = Number(message && message.bytes);
+  return Number.isFinite(direct) && direct >= 0 ? Math.trunc(direct) : 0;
+}
+
+/**
+ * The message projection the box gets (R-9): role/time/kind/text, nothing else crosses the lane.
+ * Two deliberate drops:
+ *   - `kind: 'reasoning_hidden'` rows are stored with EMPTY text by design (a hidden/encrypted
+ *     reasoning placeholder — conversation-store-v2 admits `text: ''` only for this kind), so
+ *     every one of them was a `text: ''` row crowding the caller's message budget.
+ *   - a row whose content was not persisted (the over-cap envelope: no string `content`, an
+ *     `omitted: true` marker, and a byte count) is reported as `{ omitted: true, bytes }` rather
+ *     than an empty `text`. It stays in the projection (it IS a real turn) but says so.
+ * `max_messages` counts KEPT messages, so hidden rows never consume the budget.
+ */
+function projectMessages(context, { query, maxMessages }) {
+  const raw = Array.isArray(context && context.messages) ? context.messages : [];
+  const needle = String(query || '').trim().toLowerCase();
+  const kept = [];
+  for (const message of raw) {
+    if (!message || typeof message !== 'object') continue;
+    if (message.kind === 'reasoning_hidden') continue; // stored empty by design; never projected
+    const role = String(message.role || '');
+    const at = message.timestamp || message.created_at || '';
+    const kind = typeof message.kind === 'string' ? message.kind : '';
+    const omitted = message.omitted === true || typeof message.content !== 'string';
+    if (needle) {
+      // A row with no persisted text cannot contain the needle — same outcome the old
+      // `text.toLowerCase().includes(needle)` had for it, without claiming it is empty content.
+      if (omitted) continue;
+      if (!message.content.toLowerCase().includes(needle)) continue;
+    }
+    kept.push(omitted
+      ? { role, at, kind, omitted: true, bytes: omittedByteCount(message) }
+      : { role, at, kind, text: message.content });
+  }
+  // Newest LAST (orderMessages already sorts ascending; the slice keeps the tail = the newest).
+  const dropped = Math.max(0, kept.length - maxMessages);
+  return {
+    messages: kept.slice(kept.length - Math.min(kept.length, maxMessages)),
+    truncated: dropped > 0
+      || Boolean(context && context.has_more)
+      || Boolean(context && context.truncated_reason),
+  };
+}
+
+/**
+ * R-1 (§6.3): `args.ref` -> the session id, or the named refusal the lane speaks. The parser is the
+ * SAME one the search box uses (a hub link's `#session=<id>` / `review=<id>` / bare uuid), so a ref
+ * the UI accepts is a ref this op accepts.
+ */
+function parseSessionRef(ref) {
+  const parsed = SessionSearchUtils.parseSessionIdentityQuery(typeof ref === 'string' ? ref : '');
+  const sessionId = parsed.sessionIds.length ? parsed.sessionIds[0] : '';
+  if (!sessionId) {
+    throw _namedError('session_ref_invalid', 'ref must name a session id (a bare id, review=<id>, or a URL containing one)');
+  }
+  return sessionId;
+}
+
+/** The frame's caller machine (lib/hub-bridge.js `callCtx.machineInstanceId`), '' when unknown. */
+function callerMachineId(callCtx) {
+  return String((callCtx && callCtx.machineInstanceId) || '');
+}
+
+/**
+ * WP-3 (§6.3): is `sessionId` owned by the CALLING machine, per the directory? The caller already
+ * read locally, so a hub round-trip would only mirror its own miss back at it. An ownership resolver
+ * fault is REPORTED as "not the caller" — the resolver below then names its own outcome.
+ */
+function ownerIsCaller(sessionId, deps, caller) {
+  if (!caller) return false;
+  try {
+    const located = require('./session-context-locator').locateSessionOwner(sessionId, deps);
+    return located.owner === 'machine' && String(located.machine.instanceId || '') === caller;
+  } catch {
+    return false; // REPORT: the directory could not speak -> never claim the caller owns it
+  }
+}
+
+/** A reader that could not run is a NAMED refusal, never "no such session" (AC-1b). */
+function readLocalThrough(readSessionContext, args) {
+  return Promise.resolve(readSessionContext(args)).then((local) => {
+    if (local && typeof local === 'object' && local.ok === false) {
+      throw _namedError(
+        'session_read_unavailable',
+        `the hub session reader failed for ${args.session_id}: ${local.reason || 'unknown'}`,
+      );
+    }
+    return local;
+  });
+}
+
+/**
+ * The ONE resolver call both session ops make (R-3/R-5): the hub order with the caller's machine
+ * excluded from the probe, read locally through the injected reader. Resolves to the context body +
+ * `location`, a `found:false` + `searched` miss, or `null` when the local read was deferred.
+ * `deps` rides through to lib/session-context-locator.js, so a host (or a test) can inject
+ * `forward` / `machineRows` / `localIdentity` alongside the reader.
+ */
+function resolveSession(sessionId, args, callCtx, deps) {
+  const readSessionContext = deps.readSessionContext;
+  if (typeof readSessionContext !== 'function') {
+    throw _namedError('session_read_unavailable', 'no session reader is configured on this hub');
+  }
+  return require('./session-context-locator').readSessionContextAnywhere(
+    {
+      args: {
+        session_id: sessionId,
+        turn_limit: args.turn_limit,
+        byte_limit: clampInt(args.byte_limit, SESSION_CONTEXT_BYTE_LIMIT, 1024, SESSION_CONTEXT_BYTE_LIMIT),
+        cursor: args.cursor,
+        direction: args.direction,
+        format: 'messages',
+        projection: 'envelope',
+        scope: 'pool',
+      },
+      excludeMachineId: callerMachineId(callCtx),
+    },
+    { ...deps, readLocal: (localArgs) => readLocalThrough(readSessionContext, localArgs) },
+  );
+}
+
+/** A null resolver result is "the reader never answered" — never "no such session" (AC-1b). */
+function assertResolverAnswered(result, sessionId) {
+  if (result == null) {
+    throw _namedError('session_read_unavailable', `the hub session reader did not answer for ${sessionId}`);
+  }
+  return result;
+}
+
+/** R-5: a caller that owns the ref gets its own machine named back, never a wasted probe. */
+function callerMissEnvelope(caller) {
+  return {
+    ok: true, found: false, sessions: [], messages: [], searched: [{ machine_id: caller, machine_name: '', status: 'caller' }],
+  };
+}
+
+/**
+ * WP-3 (§6.3): `session.context` — resolve ONE session id anywhere in the pool and answer with the
+ * resolver's body (`location`, or `found:false` + `searched`).
+ */
+function createSessionContextOp(deps = {}) {
+  return {
+    tier: 'none',
+    run: async (rawArgs, callCtx = {}) => {
+      const args = rawArgs && typeof rawArgs === 'object' ? rawArgs : {};
+      const sessionId = parseSessionRef(args.ref);
+      const caller = callerMachineId(callCtx);
+      if (ownerIsCaller(sessionId, deps, caller)) return callerMissEnvelope(caller);
+      return assertResolverAnswered(await resolveSession(sessionId, args, callCtx, deps), sessionId);
+    },
+  };
+}
+
+/**
+ * WP-3 (§6.3/R-9): `session.read` — the SAME resolver, projected for a reader: role/at/kind/text
+ * only, `machine` = the machine that answered (`location.machine_name`). A not-found-anywhere read
+ * names every `searched` machine in its message.
+ */
+function createSessionReadOp(deps = {}) {
+  return {
+    tier: 'none',
+    // `args.machine` (R-12) is deliberately unread: WP-5 owns cross-machine targeting.
+    // `callCtx` is the frame context lib/hub-bridge.js passes as the SECOND argument
+    // ({ machineInstanceId, callerSessionId, … }).
+    run: async (rawArgs, callCtx = {}) => {
+      const args = rawArgs && typeof rawArgs === 'object' ? rawArgs : {};
+      const sessionId = parseSessionRef(args.ref);
+      const caller = callerMachineId(callCtx);
+      // The caller IS that machine: the row is on the caller's own disk, so a hub round-trip is the
+      // wrong tool — name that outcome instead.
+      if (ownerIsCaller(sessionId, deps, caller)) {
+        throw _namedError('session_on_caller', `session ${sessionId} lives on the calling machine; read it locally with walle_get_session`);
+      }
+      const context = assertResolverAnswered(await resolveSession(sessionId, args, callCtx, deps), sessionId);
+      const sessions = Array.isArray(context.sessions) ? context.sessions : [];
+      if (!sessions.length) throw _namedError('session_not_found', _notFoundMessage(sessionId, context));
+      const summary = sessions[0] || {};
+      const projected = projectMessages(context, { query: args.query, maxMessages: clampMaxMessages(args.max_messages) });
+      return {
+        session: {
+          id: String(summary.ctm_session_id || summary.session_id || sessionId),
+          title: String(summary.title || ''),
+          agent: String(summary.provider || ''),
+          cwd: String(summary.cwd || ''),
+          machine: String((context.location && context.location.machine_name) || ''),
+        },
+        messages: projected.messages,
+        truncated: projected.truncated,
+      };
+    },
+  };
+}
+
+/** R-5: a miss names every machine that was asked and what each answered. */
+function _notFoundMessage(sessionId, context) {
+  const searched = Array.isArray(context && context.searched) ? context.searched : [];
+  const named = searched
+    .map((entry) => `${String(entry.machine_name || entry.machine_id || 'unknown')} (${String(entry.status || '')})`)
+    .join(', ');
+  return `no session ${sessionId} on ${named || 'any machine in this pool'}`;
+}
+
+/**
+ * WP-4 (§6.3): `session.search` — R-7 pool search, asked by a box over the lane. The hub runs its OWN
+ * search (local + one `scope=local` GET per dialable member) and answers the RRF-merged rows with a
+ * per-machine `machines` list. `excludeMachineId` is the CALLER's machine: it already searched
+ * locally, so the hub never dials it back.
+ */
+function createSessionSearchOp(deps = {}) {
+  return {
+    tier: 'none',
+    run: async (rawArgs, callCtx = {}) => {
+      const args = rawArgs && typeof rawArgs === 'object' ? rawArgs : {};
+      const searchSessions = typeof deps.searchSessions === 'function' ? deps.searchSessions : defaultSearchSessions;
+      const result = await require('./session-context-locator').searchSessionsAnywhere(
+        {
+          query: String(args.query == null ? '' : args.query),
+          limit: clampInt(args.limit, SESSION_SEARCH_DEFAULT_LIMIT, 1, SESSION_SEARCH_MAX_LIMIT),
+          excludeMachineId: callerMachineId(callCtx),
+          scope: 'pool',
+        },
+        { ...deps, searchLocal: (localArgs) => readSearchThrough(searchSessions, localArgs) },
+      );
+      // A searcher that never answered is a NAMED refusal, never "nothing matched" (AC-1b idiom).
+      if (result == null) throw _namedError('session_search_unavailable', 'the hub session search did not answer');
+      return result;
+    },
+  };
+}
+
+/**
+ * R-7 production search leg: the SAME off-thread read-pool op `/api/ctm/session-memory/search`
+ * runs (server.js `_runCtmSessionMemoryOffThread('ctmSessionMemorySearch', …)`), reached through the
+ * process-wide active read pool. server.js is file-size frozen and injects only
+ * `readSessionContext`, so this default is resolved LAZILY here — the heavy search never runs on the
+ * hub's main loop for a remote caller, and requiring this module from a unit test never wires it.
+ */
+function defaultSearchSessions(args = {}) {
+  let dbPath = '';
+  try {
+    dbPath = String(require('../db').getDbPath() || '');
+  } catch {
+    // REPORT: no DB bound yet (or an unusable module) -> the pool op answers its own named failure.
+    dbPath = '';
+  }
+  return require('./read-pool-client').requestOnActiveReadPool(
+    'ctmSessionMemorySearch',
+    { dbPath, args },
+    { timeoutMs: SESSION_SEARCH_TIMEOUT_MS },
+  );
+}
+
+/** A searcher that could not run is a NAMED refusal, never "nothing matched" (AC-1b). */
+function readSearchThrough(searchSessions, args) {
+  return Promise.resolve(searchSessions(args)).then((local) => {
+    if (local && typeof local === 'object' && local.ok === false && local.reason) {
+      throw _namedError(
+        'session_search_unavailable',
+        `the hub session search failed for "${args.query}": ${local.reason}`,
+      );
+    }
+    return local;
+  });
+}
+
+/**
+ * Register the WP-1/WP-3/WP-4 read ops (`session.context`, `session.read`, `session.search`) on a hub
+ * bridge (lib/hub-bridge.js). `deps.readSessionContext(args)` is required; `deps.getMirrorSessionMachine(id)`
+ * and the other locator deps are optional and default to the locator's own production wiring.
+ * `deps.searchSessions(args)` is optional too: omitted, the op reads through the active off-thread
+ * read pool (`defaultSearchSessions`).
+ */
+function registerSessionOps(hubBridge, deps = {}) {
+  if (!hubBridge || typeof hubBridge.registerOp !== 'function') {
+    throw new TypeError('registerSessionOps: hubBridge.registerOp must be a function');
+  }
+  hubBridge.registerOp('session.context', createSessionContextOp(deps));
+  hubBridge.registerOp('session.read', createSessionReadOp(deps));
+  hubBridge.registerOp('session.search', createSessionSearchOp(deps));
+  return hubBridge;
+}
+
+/**
+ * WP-2 (§6.4): `fs.read` — read ONE file on the hub the caller was granted `read` for.
+ * Args `{ path (absolute), offset? (0-based first line), limit? (lines, default/max 2000) }`.
+ * Returns `{ path, lines, total_lines, truncated }`. A path that is not absolute, or is a directory,
+ * is a NAMED refusal; a file over 1 MiB is read to the cap and reported `truncated: true`.
+ */
+function createFsReadOp(deps = {}) {
+  const fsPromises = deps.fsPromises || fs.promises;
+  return {
+    tier: 'read',
+    run: async (rawArgs) => {
+      const args = rawArgs && typeof rawArgs === 'object' ? rawArgs : {};
+      const target = typeof args.path === 'string' ? args.path : '';
+      if (!target) throw _namedError('path_required', 'path is required');
+      if (!path.isAbsolute(target)) throw _namedError('path_not_absolute', `path must be absolute: ${target}`);
+      let stat = null;
+      try {
+        stat = await fsPromises.stat(target);
+      } catch {
+        throw _namedError('path_not_found', `no such file: ${target}`);
+      }
+      if (stat.isDirectory()) throw _namedError('path_is_directory', `path is a directory, not a file: ${target}`);
+
+      const offset = clampInt(args.offset, 0, 0, Number.MAX_SAFE_INTEGER);
+      const limit = clampInt(args.limit, FS_READ_DEFAULT_LIMIT, 1, FS_READ_MAX_LIMIT);
+      const bytes = Math.max(0, Math.min(Number(stat.size) || 0, FS_READ_CAP_BYTES));
+      const buffer = Buffer.alloc(bytes);
+      if (bytes > 0) {
+        const handle = await fsPromises.open(target, 'r');
+        try {
+          await handle.read(buffer, 0, bytes, 0);
+        } finally {
+          try { await handle.close(); } catch { /* expected: the handle is released with the process */ }
+        }
+      }
+      const fileTruncated = (Number(stat.size) || 0) > FS_READ_CAP_BYTES;
+      const lines = buffer.toString('utf8').split('\n');
+      // A capped read ends mid-line as often as not: drop the trailing fragment rather than return a
+      // half-line, and let `truncated` carry the truth.
+      if (fileTruncated && lines.length) lines.pop();
+      const total = lines.length;
+      const sliced = lines.slice(offset, offset + limit);
+      return {
+        path: target,
+        lines: sliced,
+        total_lines: total,
+        truncated: fileTruncated || offset + sliced.length < total,
+      };
+    },
+  };
+}
+
+/**
+ * WP-2 (§6.4): `fs.list` — list ONE directory on the hub (tier `read`). Args `{ path, glob? }`; the
+ * glob is a simple `*`/`?` match on the entry NAME (never a path glob). At most 2000 entries.
+ */
+function createFsListOp(deps = {}) {
+  const fsPromises = deps.fsPromises || fs.promises;
+  return {
+    tier: 'read',
+    run: async (rawArgs) => {
+      const args = rawArgs && typeof rawArgs === 'object' ? rawArgs : {};
+      const target = typeof args.path === 'string' ? args.path : '';
+      if (!target) throw _namedError('path_required', 'path is required');
+      if (!path.isAbsolute(target)) throw _namedError('path_not_absolute', `path must be absolute: ${target}`);
+      let stat = null;
+      try {
+        stat = await fsPromises.stat(target);
+      } catch {
+        throw _namedError('path_not_found', `no such directory: ${target}`);
+      }
+      if (!stat.isDirectory()) throw _namedError('path_not_a_directory', `path is not a directory: ${target}`);
+
+      const matches = compileNameGlob(args.glob);
+      const dirents = await fsPromises.readdir(target, { withFileTypes: true });
+      const entries = [];
+      let truncated = false;
+      for (const dirent of dirents) {
+        if (matches && !matches(dirent.name)) continue;
+        if (entries.length >= FS_LIST_MAX_ENTRIES) {
+          truncated = true;
+          break;
+        }
+        const type = dirent.isDirectory() ? 'dir' : dirent.isSymbolicLink() ? 'link' : 'file';
+        entries.push({ name: dirent.name, type, size: await _entrySize(path.join(target, dirent.name), dirent) });
+      }
+      return { path: target, entries, truncated };
+    },
+  };
+}
+
+/**
+ * WP-2 (§6.4): `exec` — run a command on the hub as the hub user (tier `exec`).
+ * Args `{ command (<= 16 KiB), cwd? (absolute; default the hub user's home), timeout_ms? (default
+ * 30000, max 120000) }`. The child gets its OWN PROCESS GROUP (`detached: true`); at the deadline the
+ * whole group is SIGTERMed and, 1 s later, SIGKILLed. Returns
+ * `{ exit_code, signal, stdout, stderr, timed_out, truncated, ms }`. Uses spawn's async API — the hub
+ * main loop is never blocked.
+ */
+function createExecOp(deps = {}) {
+  const spawnFn = deps.spawn || childProcess.spawn;
+  const platform = deps.platform || process.platform;
+  const homedir = deps.homedir || os.homedir;
+  const now = deps.now || (() => Date.now());
+  const killFn = deps.kill || ((pid, signal) => process.kill(pid, signal));
+  const fsPromises = deps.fsPromises || fs.promises;
+  const parentEnv = deps.env || process.env;
+  const shell = platform === 'darwin' ? '/bin/zsh' : '/bin/bash';
+
+  return {
+    tier: 'exec',
+    run: async (rawArgs) => {
+      const args = rawArgs && typeof rawArgs === 'object' ? rawArgs : {};
+      const command = typeof args.command === 'string' ? args.command : '';
+      if (!command.trim()) throw _namedError('exec_failed', 'command is required');
+      if (Buffer.byteLength(command, 'utf8') > EXEC_MAX_COMMAND_BYTES) {
+        throw _namedError('args_too_large', `command exceeds ${EXEC_MAX_COMMAND_BYTES} bytes`);
+      }
+      const cwd = args.cwd === undefined || args.cwd === null || args.cwd === '' ? homedir() : String(args.cwd);
+      if (!path.isAbsolute(cwd)) throw _namedError('cwd_not_absolute', `cwd must be absolute: ${cwd}`);
+      let cwdStat = null;
+      try {
+        cwdStat = await fsPromises.stat(cwd);
+      } catch {
+        throw _namedError('cwd_not_found', `cwd does not exist: ${cwd}`);
+      }
+      if (!cwdStat.isDirectory()) throw _namedError('cwd_not_a_directory', `cwd is not a directory: ${cwd}`);
+      const timeoutMs = clampInt(args.timeout_ms, EXEC_DEFAULT_TIMEOUT_MS, 1, EXEC_MAX_TIMEOUT_MS);
+      const startedAt = now();
+
+      return await new Promise((resolve, reject) => {
+        let child = null;
+        try {
+          child = spawnFn(shell, ['-lc', command], {
+            cwd,
+            env: execChildEnv(parentEnv),
+            // R-8: its OWN process group, so the deadline can take out a whole pipeline, not just zsh.
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        } catch (error) {
+          reject(_namedError('exec_failed', `could not start ${shell}: ${String((error && error.message) || error)}`));
+          return;
+        }
+
+        const collected = { stdout: '', stderr: '', outBytes: 0, errBytes: 0, truncated: false };
+        const onChunk = (streamName, chunk) => {
+          const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+          const bytesField = streamName === 'stdout' ? 'outBytes' : 'errBytes';
+          const left = EXEC_OUTPUT_CAP_BYTES - collected[bytesField];
+          if (left <= 0) {
+            collected.truncated = true;
+            return;
+          }
+          if (Buffer.byteLength(text, 'utf8') > left) {
+            collected.truncated = true;
+            collected[streamName] += Buffer.from(text, 'utf8').subarray(0, left).toString('utf8');
+            collected[bytesField] = EXEC_OUTPUT_CAP_BYTES;
+            return;
+          }
+          collected[streamName] += text;
+          collected[bytesField] += Buffer.byteLength(text, 'utf8');
+        };
+        if (child.stdout) child.stdout.on('data', (chunk) => onChunk('stdout', chunk));
+        if (child.stderr) child.stderr.on('data', (chunk) => onChunk('stderr', chunk));
+
+        let timedOut = false;
+        let sigkillTimer = null;
+        const timer = setTimeout(() => {
+          timedOut = true;
+          try {
+            killFn(-child.pid, 'SIGTERM');
+          } catch {
+            // expected: the group is already gone (the command finished inside the same tick).
+          }
+          sigkillTimer = setTimeout(() => {
+            try {
+              killFn(-child.pid, 'SIGKILL');
+            } catch {
+              // expected: SIGTERM already reaped the group.
+            }
+          }, EXEC_KILL_GRACE_MS);
+          if (sigkillTimer && typeof sigkillTimer.unref === 'function') sigkillTimer.unref();
+        }, timeoutMs);
+
+        child.on('error', (error) => {
+          clearTimeout(timer);
+          if (sigkillTimer) clearTimeout(sigkillTimer);
+          reject(_namedError('exec_failed', String((error && error.message) || error)));
+        });
+        // `close` (not `exit`) so both pipes are fully flushed before the result is assembled.
+        child.on('close', (code, signal) => {
+          clearTimeout(timer);
+          if (sigkillTimer) clearTimeout(sigkillTimer);
+          resolve({
+            exit_code: code === null || code === undefined ? null : Number(code),
+            signal: signal || null,
+            stdout: collected.stdout,
+            stderr: collected.stderr,
+            timed_out: timedOut,
+            truncated: collected.truncated,
+            ms: Math.max(0, now() - startedAt),
+          });
+        });
+      });
+    },
+  };
+}
+
+/**
+ * WP-3 (docs/remote-session-hub-bridge-2026-10-30.html §3 P-2, D-4/D-7, §5 R-4, §6.4, §8 WP-3):
+ * `mcp.list` — the tool list of one HUB-side MCP server (tier `browser`). Args `{ server }`.
+ * The server allowlist and the client lifecycle live in lib/hub-bridge-mcp.js; this op is the lane's
+ * thin adapter, so a caller can never name a server that module does not allow.
+ */
+function createMcpListOp(deps = {}) {
+  const mcp = deps.mcp || require('./hub-bridge-mcp');
+  return {
+    tier: 'browser',
+    run: async (rawArgs) => {
+      const args = rawArgs && typeof rawArgs === 'object' ? rawArgs : {};
+      const server = typeof args.server === 'string' ? args.server : '';
+      const tools = await mcp.listTools(server);
+      return { server, tools };
+    },
+  };
+}
+
+/**
+ * WP-3 (§6.4): `mcp.call` — run one tool on one HUB-side MCP server (tier `browser`).
+ * Args `{ server, tool, arguments? }`. The result is the MCP result `{ content, isError }` (with
+ * `truncated: true` when the 1 MiB ceiling trimmed it) — the box sees what the hub's client saw.
+ */
+function createMcpCallOp(deps = {}) {
+  const mcp = deps.mcp || require('./hub-bridge-mcp');
+  return {
+    tier: 'browser',
+    run: async (rawArgs) => {
+      const args = rawArgs && typeof rawArgs === 'object' ? rawArgs : {};
+      const server = typeof args.server === 'string' ? args.server : '';
+      const tool = typeof args.tool === 'string' ? args.tool : '';
+      if (!tool) throw _namedError('mcp_tool_required', 'tool is required');
+      return mcp.callTool(server, tool, args.arguments);
+    },
+  };
+}
+
+/**
+ * Register the WP-3 MCP ops (`mcp.list`, `mcp.call`) on a hub bridge (lib/hub-bridge.js). Both are
+ * tier `browser` — R-4's separate tier, which neither an `exec` nor a `read` grant satisfies.
+ */
+function registerMcpOps(hubBridge, deps = {}) {
+  if (!hubBridge || typeof hubBridge.registerOp !== 'function') {
+    throw new TypeError('registerMcpOps: hubBridge.registerOp must be a function');
+  }
+  hubBridge.registerOp('mcp.list', createMcpListOp(deps));
+  hubBridge.registerOp('mcp.call', createMcpCallOp(deps));
+  return hubBridge;
+}
+
+/**
+ * Register the WP-2 host ops (`fs.read`, `fs.list`, `exec`) on a hub bridge (lib/hub-bridge.js).
+ * Kept separate from `registerSessionOps` so a host that only serves session reads (a box, WP-1)
+ * never advertises exec-capable ops it has no intent to run.
+ */
+function registerHostOps(hubBridge, deps = {}) {
+  if (!hubBridge || typeof hubBridge.registerOp !== 'function') {
+    throw new TypeError('registerHostOps: hubBridge.registerOp must be a function');
+  }
+  hubBridge.registerOp('fs.read', createFsReadOp(deps));
+  hubBridge.registerOp('fs.list', createFsListOp(deps));
+  hubBridge.registerOp('exec', createExecOp(deps));
+  return hubBridge;
+}
+
+module.exports = {
+  DEFAULT_MAX_MESSAGES,
+  MAX_MESSAGES,
+  FS_READ_CAP_BYTES,
+  FS_READ_DEFAULT_LIMIT,
+  FS_READ_MAX_LIMIT,
+  FS_LIST_MAX_ENTRIES,
+  EXEC_MAX_COMMAND_BYTES,
+  EXEC_DEFAULT_TIMEOUT_MS,
+  EXEC_MAX_TIMEOUT_MS,
+  EXEC_OUTPUT_CAP_BYTES,
+  EXEC_KILL_GRACE_MS,
+  SESSION_CONTEXT_BYTE_LIMIT,
+  SESSION_SEARCH_DEFAULT_LIMIT,
+  SESSION_SEARCH_MAX_LIMIT,
+  SESSION_SEARCH_TIMEOUT_MS,
+  clampInt,
+  clampMaxMessages,
+  compileNameGlob,
+  execChildEnv,
+  projectMessages,
+  createSessionContextOp,
+  createSessionReadOp,
+  createSessionSearchOp,
+  createFsReadOp,
+  createFsListOp,
+  createExecOp,
+  createMcpListOp,
+  createMcpCallOp,
+  registerSessionOps,
+  registerHostOps,
+  registerMcpOps,
+};