@yeaft/webchat-agent 0.1.592 → 0.1.593

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.592",
+  "version": "0.1.593",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/memory/scope-tree.js

@@ -0,0 +1,520 @@
+/**
+ * memory/scope-tree.js — DESIGN.md Phase 2 (scoped memory tree).
+ *
+ * Implements the path-keyed scope tree described in DESIGN.md §2:
+ *
+ *   ~/.yeaft/memory/
+ *     user/
+ *       summary.md          — paragraph synopsis (Layer A)
+ *       index.md            — markdown table, path-keyed
+ *       entries/<yyyy-mm-dd>-<slug>.md
+ *     groups/<groupId>/    — same shape
+ *     vp/<vpId>/           — same shape
+ *     tasks/<taskId>/      — same shape, plus archive/
+ *
+ * This module is concerned ONLY with on-disk shape + atomic writes. It does
+ * NOT do any LLM work (extraction, summarisation, dream maintenance) — those
+ * are higher layers (compact-orchestrator, dream).
+ *
+ * Atomicity contract:
+ *   - Every write goes via `.tmp` + rename to avoid torn reads. A reader
+ *     mid-rename sees either the old or the new file, never half of either.
+ *   - `createEntry()` opens with `O_EXCL` so concurrent producers cannot
+ *     clobber a slug collision; the second writer surfaces `slug_exists`.
+ *   - `index.md` is rewritten in full (markdown table). Partial-row append
+ *     would leave a torn header on crash; the whole file is small enough
+ *     that full rewrite + atomic rename is fine.
+ *
+ * Concurrency rules (DESIGN.md §9.1):
+ *   - Two workers writing different entries to the same scope are safe —
+ *     they write to different files, then each updates index.md via the
+ *     atomic rename. Last writer wins for the index; both entries are
+ *     present on disk regardless.
+ *   - `summary.md` written via the same atomic rename. Workers reading it
+ *     mid-write see either the previous or the next paragraph.
+ *
+ * Path discipline:
+ *   - All scope paths returned by helpers are filesystem-relative paths
+ *     ROOTED at the memory dir, e.g. `groups/eng/entries/2026-04-21-foo.md`.
+ *     This matches DESIGN.md §1.2.1 — paths self-document.
+ */
+
+import {
+  promises as fsp,
+  existsSync,
+  mkdirSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+/** Default memory root. Tests override via `opts.root`. */
+export const DEFAULT_MEMORY_ROOT = join(homedir(), '.yeaft', 'memory');
+
+/** @typedef {'user'|'group'|'vp'|'task'} ScopeKind */
+/** @typedef {{kind: ScopeKind, id?: string}} Scope */
+
+/**
+ * Compute the scope's path segment relative to the memory root.
+ * `user/`, `groups/<id>/`, `vp/<id>/`, `tasks/<id>/`.
+ *
+ * @param {Scope} scope
+ * @returns {string}
+ */
+export function scopeDir(scope) {
+  if (!scope || typeof scope !== 'object') {
+    throw new Error('scopeDir: scope is required');
+  }
+  switch (scope.kind) {
+    case 'user':
+      return 'user';
+    case 'group':
+      if (!scope.id) throw new Error('scopeDir: group scope requires id');
+      return `groups/${scope.id}`;
+    case 'vp':
+      if (!scope.id) throw new Error('scopeDir: vp scope requires id');
+      return `vp/${scope.id}`;
+    case 'task':
+      if (!scope.id) throw new Error('scopeDir: task scope requires id');
+      return `tasks/${scope.id}`;
+    default:
+      throw new Error(`scopeDir: unknown kind ${JSON.stringify(scope.kind)}`);
+  }
+}
+
+/**
+ * Atomic write: temp-file + rename. Creates parent directories on demand.
+ * The rename is atomic on POSIX filesystems for paths on the same mount.
+ *
+ * @param {string} absPath
+ * @param {string} content
+ */
+async function atomicWrite(absPath, content) {
+  await fsp.mkdir(dirname(absPath), { recursive: true });
+  const tmp = `${absPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+  await fsp.writeFile(tmp, content, 'utf8');
+  await fsp.rename(tmp, absPath);
+}
+
+/**
+ * Slugify a free-form title for use in a filename. Lowercase, ASCII letters
+ * + digits + dash. Empty / pathological input returns `entry`.
+ *
+ * @param {string} title
+ * @returns {string}
+ */
+export function slugify(title) {
+  const raw = (title || '')
+    .toString()
+    .toLowerCase()
+    .normalize('NFKD')
+    // eslint-disable-next-line no-misleading-character-class
+    .replace(/[̀-ͯ]/g, '') // strip combining marks
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+  return raw || 'entry';
+}
+
+/**
+ * Format a Date as `yyyy-mm-dd` in UTC. Used in entry filenames.
+ *
+ * @param {Date} [d=new Date()]
+ * @returns {string}
+ */
+export function isoDate(d = new Date()) {
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * Compute the canonical entry path for a (scope, title, date) triple.
+ *
+ * @param {Scope} scope
+ * @param {string} title
+ * @param {Date} [date]
+ * @returns {string} relative to memory root
+ */
+export function entryPathFor(scope, title, date) {
+  return `${scopeDir(scope)}/entries/${isoDate(date)}-${slugify(title)}.md`;
+}
+
+// ─── frontmatter ───────────────────────────────────────────────
+
+/**
+ * Render YAML-ish frontmatter. Keys in deterministic order; string values
+ * are JSON-stringified to handle quotes / newlines safely; arrays render as
+ * `key: [a, b]`. Unknown values are skipped.
+ *
+ * @param {Record<string,*>} fm
+ * @returns {string}
+ */
+function renderFrontmatter(fm) {
+  if (!fm || typeof fm !== 'object') return '';
+  const order = ['title', 'kind', 'tags', 'source', 'createdAt', 'updatedAt'];
+  const seen = new Set();
+  const lines = ['---'];
+  for (const key of order) {
+    if (!(key in fm)) continue;
+    seen.add(key);
+    lines.push(renderFmLine(key, fm[key]));
+  }
+  for (const key of Object.keys(fm)) {
+    if (seen.has(key)) continue;
+    lines.push(renderFmLine(key, fm[key]));
+  }
+  lines.push('---');
+  return lines.filter(Boolean).join('\n');
+}
+
+function renderFmLine(key, value) {
+  if (value === null || value === undefined) return '';
+  if (Array.isArray(value)) {
+    const items = value.map(v => (typeof v === 'string' ? v : JSON.stringify(v)));
+    return `${key}: [${items.join(', ')}]`;
+  }
+  if (typeof value === 'string') {
+    // Quote when it contains anything non-trivial.
+    if (/^[\w\-./:]+$/.test(value)) return `${key}: ${value}`;
+    return `${key}: ${JSON.stringify(value)}`;
+  }
+  return `${key}: ${JSON.stringify(value)}`;
+}
+
+/**
+ * Parse the frontmatter block from a markdown body. Returns `{frontmatter,
+ * body}`; missing frontmatter ⇒ `frontmatter = {}` and `body` is the input.
+ * Best-effort parser — accepts the lines this module emits and a few common
+ * variants. Does NOT pull in a YAML dep.
+ *
+ * @param {string} content
+ * @returns {{ frontmatter: Record<string,*>, body: string }}
+ */
+export function parseEntry(content) {
+  if (typeof content !== 'string' || !content.startsWith('---')) {
+    return { frontmatter: {}, body: content || '' };
+  }
+  const end = content.indexOf('\n---', 4);
+  if (end === -1) return { frontmatter: {}, body: content };
+  const fmText = content.slice(4, end).trim();
+  const body = content.slice(end + 4).replace(/^\n+/, '');
+  const fm = {};
+  for (const rawLine of fmText.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const m = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    if (!m) continue;
+    const [, key, rest] = m;
+    fm[key] = parseFmValue(rest);
+  }
+  return { frontmatter: fm, body };
+}
+
+function parseFmValue(rest) {
+  if (rest === '') return '';
+  if (rest.startsWith('[') && rest.endsWith(']')) {
+    const inner = rest.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(',').map(s => {
+      const t = s.trim();
+      if (t.startsWith('"') && t.endsWith('"')) {
+        try { return JSON.parse(t); } catch { return t; }
+      }
+      return t;
+    });
+  }
+  if (rest.startsWith('"') && rest.endsWith('"')) {
+    try { return JSON.parse(rest); } catch { return rest.slice(1, -1); }
+  }
+  return rest;
+}
+
+// ─── entries ───────────────────────────────────────────────────
+
+/**
+ * Create a new entry under (scope, title). Fails with `slug_exists` if the
+ * computed path already exists. Returns the relative path written.
+ *
+ * @param {{
+ *   scope: Scope,
+ *   title: string,
+ *   body: string,
+ *   tags?: string[],
+ *   kind?: string,
+ *   source?: string,
+ *   date?: Date,
+ *   root?: string,
+ * }} args
+ * @returns {Promise<{ path: string, abs: string }>}
+ */
+export async function createEntry(args) {
+  const { scope, title, body, tags, kind, source, date, root = DEFAULT_MEMORY_ROOT } = args;
+  if (!title || typeof title !== 'string') throw new Error('createEntry: title required');
+  if (typeof body !== 'string') throw new Error('createEntry: body required (string)');
+  const rel = entryPathFor(scope, title, date);
+  const abs = join(root, rel);
+  await fsp.mkdir(dirname(abs), { recursive: true });
+  const fm = renderFrontmatter({
+    title,
+    kind: kind || 'note',
+    tags: Array.isArray(tags) && tags.length ? tags : undefined,
+    source: source || undefined,
+    createdAt: isoDate(date),
+    updatedAt: isoDate(date),
+  });
+  const content = `${fm}\n\n${body.trim()}\n`;
+  // O_EXCL — fail loudly on slug collision (DESIGN.md §9.1 atomicity).
+  let handle;
+  try {
+    handle = await fsp.open(abs, 'wx');
+  } catch (err) {
+    if (err && err.code === 'EEXIST') {
+      const e = new Error('slug_exists');
+      e.code = 'slug_exists';
+      e.path = rel;
+      throw e;
+    }
+    throw err;
+  }
+  try {
+    await handle.writeFile(content, 'utf8');
+  } finally {
+    await handle.close();
+  }
+  return { path: rel, abs };
+}
+
+/**
+ * Read an entry by its relative path; returns `null` if missing. Throws
+ * `acl_blocked` when the caller's `currentVpId` is given and the path is
+ * `vp/<other>/...` — the only hard ACL boundary.
+ *
+ * @param {string} relPath
+ * @param {{ root?: string, currentVpId?: string }} [opts]
+ * @returns {Promise<{ frontmatter: Record<string,*>, body: string, path: string } | null>}
+ */
+export async function readEntry(relPath, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT, currentVpId } = opts;
+  if (!relPath || typeof relPath !== 'string') throw new Error('readEntry: relPath required');
+  if (currentVpId && isVpForeign(relPath, currentVpId)) {
+    const e = new Error('acl_blocked');
+    e.code = 'acl_blocked';
+    e.path = relPath;
+    throw e;
+  }
+  const abs = join(root, relPath);
+  let raw;
+  try {
+    raw = await fsp.readFile(abs, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const { frontmatter, body } = parseEntry(raw);
+  return { frontmatter, body: body.replace(/\n+$/, ''), path: relPath };
+}
+
+/**
+ * @returns {boolean} true iff `relPath` is `vp/<other>/...` (other ≠ currentVpId).
+ */
+export function isVpForeign(relPath, currentVpId) {
+  if (!relPath || !currentVpId) return false;
+  const m = /^vp\/([^/]+)\//.exec(relPath);
+  if (!m) return false;
+  return m[1] !== currentVpId;
+}
+
+// ─── index.md ──────────────────────────────────────────────────
+
+/**
+ * Index row schema. `path` is the canonical, scope-rooted relative path.
+ * `updated` is YYYY-MM-DD UTC. `tags` is a comma-joined string for the
+ * markdown column; arrays are accepted as input and normalised.
+ *
+ * @typedef {{
+ *   path: string,
+ *   title: string,
+ *   tags?: string | string[],
+ *   kind?: string,
+ *   updated?: string,
+ * }} IndexRow
+ */
+
+/**
+ * Render the markdown table for `index.md` in a scope. Reverse-chronological
+ * — newest `updated` first — matching DESIGN.md §9.3 ("append on top").
+ *
+ * @param {Scope} scope
+ * @param {IndexRow[]} rows
+ * @returns {string}
+ */
+export function renderIndex(scope, rows) {
+  const dir = scopeDir(scope);
+  const sorted = [...(rows || [])].sort((a, b) => {
+    const ax = (b.updated || '').localeCompare(a.updated || '');
+    return ax !== 0 ? ax : (a.path || '').localeCompare(b.path || '');
+  });
+  const lines = [
+    `# index — ${dir}`,
+    '',
+    '| path | title | tags | kind | updated |',
+    '| ---- | ----- | ---- | ---- | ------- |',
+  ];
+  for (const r of sorted) {
+    const path = (r.path || '').replace(/\|/g, '\\|');
+    const title = (r.title || '').replace(/\|/g, '\\|');
+    const tags = Array.isArray(r.tags) ? r.tags.join(',') : (r.tags || '');
+    const kind = r.kind || '';
+    const updated = r.updated || '';
+    lines.push(`| ${path} | ${title} | ${tags} | ${kind} | ${updated} |`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Parse `index.md` markdown table back into an array of rows. Tolerates
+ * extra whitespace, missing optional columns, and the index header line.
+ * Unknown / malformed lines are skipped silently.
+ *
+ * @param {string} content
+ * @returns {IndexRow[]}
+ */
+export function parseIndex(content) {
+  if (typeof content !== 'string' || !content) return [];
+  const out = [];
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line.startsWith('|')) continue;
+    if (/^\|\s*-+/.test(line)) continue; // separator row
+    const cols = line.split('|').slice(1, -1).map(s => s.trim());
+    if (cols.length < 2) continue;
+    const [path, title, tags = '', kind = '', updated = ''] = cols;
+    if (!path || path === 'path') continue; // header row
+    out.push({
+      path,
+      title,
+      tags: tags ? tags.split(',').map(s => s.trim()).filter(Boolean) : [],
+      kind: kind || undefined,
+      updated: updated || undefined,
+    });
+  }
+  return out;
+}
+
+/**
+ * Read `index.md` for a scope and return the parsed rows. Missing index
+ * returns `[]` (cold-start scope).
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string }} [opts]
+ * @returns {Promise<IndexRow[]>}
+ */
+export async function readIndex(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const abs = join(root, scopeDir(scope), 'index.md');
+  let raw;
+  try { raw = await fsp.readFile(abs, 'utf8'); }
+  catch (err) {
+    if (err && err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return parseIndex(raw);
+}
+
+/**
+ * Atomically rewrite `index.md` for a scope.
+ *
+ * @param {Scope} scope
+ * @param {IndexRow[]} rows
+ * @param {{ root?: string }} [opts]
+ */
+export async function writeIndex(scope, rows, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const abs = join(root, scopeDir(scope), 'index.md');
+  await atomicWrite(abs, renderIndex(scope, rows));
+}
+
+/**
+ * Upsert a single row keyed by `path`. Existing row with the same path is
+ * replaced; otherwise the row is prepended (kept in reverse-chronological
+ * order via `renderIndex`'s sort). Returns the updated row list.
+ *
+ * @param {Scope} scope
+ * @param {IndexRow} row
+ * @param {{ root?: string }} [opts]
+ * @returns {Promise<IndexRow[]>}
+ */
+export async function upsertIndexRow(scope, row, opts = {}) {
+  if (!row || !row.path) throw new Error('upsertIndexRow: row.path required');
+  const rows = await readIndex(scope, opts);
+  const filtered = rows.filter(r => r.path !== row.path);
+  filtered.unshift(row);
+  await writeIndex(scope, filtered, opts);
+  return filtered;
+}
+
+/**
+ * Cap the rows surfaced to the router (DESIGN.md §9.3). Reverse-chrono;
+ * default K = 200. Caller passes the merged set; we trim and return.
+ *
+ * @param {IndexRow[]} rows
+ * @param {number} [k=200]
+ * @returns {IndexRow[]}
+ */
+export function capIndexRows(rows, k = 200) {
+  if (!Array.isArray(rows)) return [];
+  if (rows.length <= k) return rows.slice();
+  return rows.slice(0, k);
+}
+
+// ─── summary.md ────────────────────────────────────────────────
+
+/**
+ * Read the scope's `summary.md`. Empty / missing → ''.
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function readSummary(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const abs = join(root, scopeDir(scope), 'summary.md');
+  try { return (await fsp.readFile(abs, 'utf8')).trim(); }
+  catch (err) {
+    if (err && err.code === 'ENOENT') return '';
+    throw err;
+  }
+}
+
+/**
+ * Atomically rewrite the scope's `summary.md`. The body is trimmed; empty
+ * input writes an empty file (callers that wanted "delete summary" can use
+ * `fs.unlink` directly — we don't surface that here).
+ *
+ * @param {Scope} scope
+ * @param {string} body
+ * @param {{ root?: string }} [opts]
+ */
+export async function writeSummary(scope, body, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const abs = join(root, scopeDir(scope), 'summary.md');
+  await atomicWrite(abs, `${(body || '').trim()}\n`);
+}
+
+// ─── ensure scope on disk ──────────────────────────────────────
+
+/**
+ * Best-effort: ensure the scope's directory and an empty `entries/` exist.
+ * Idempotent. Use at boot or on first write to avoid ENOENT cascades.
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string }} [opts]
+ */
+export function ensureScopeSync(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const dir = join(root, scopeDir(scope));
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const entries = join(dir, 'entries');
+  if (!existsSync(entries)) mkdirSync(entries, { recursive: true });
+}

package/unify/router/vp-planner.js

@@ -0,0 +1,282 @@
+/**
+ * router/vp-planner.js — DESIGN.md Phase 3a (router per-VP plans).
+ *
+ * The legacy `intent-classifier.js` decides "which thread continues this
+ * turn" — single-VP, single-plan. The multi-VP redesign (DESIGN.md §1.2.1)
+ * generalises that into a `plans[]` array: one plan per VP that should act
+ * this turn, in execution order. This module is the per-VP planner.
+ *
+ * Phase 3a scope: schema + validation + sequential fan-out runner. The LLM
+ * call itself is wired in Phase 3b along with `priorPlan` continuity. Until
+ * then, callers either (a) construct plans directly from override paths, or
+ * (b) wrap the legacy single-plan classifier and call `wrapLegacyDecision`.
+ *
+ * Non-goals here:
+ *   - parallel fan-out (Phase 3.5).
+ *   - thinking-mode resolution (handled at the dispatcher level alongside
+ *     the UI > Router > VP > Global precedence chain — DESIGN.md §9.16).
+ *   - `priorPlan` skip-router heuristic (Phase 3b).
+ *
+ * Shape contract (DESIGN.md §1.2.1):
+ *
+ *   {
+ *     action: 'continue' | 'switch_vp' | 'fork_task' | 'join_task' |
+ *             'broadcast' | 'noop',
+ *     targetTaskId: string | null,
+ *     plans: [
+ *       {
+ *         vpId: string,
+ *         forwardQuery: { userOriginal: string, intent: string },
+ *         preselect: { memoryPaths: string[], taskIds: string[] },
+ *         thinking: 'high' | 'max' | null,
+ *         thinkingReason: string,
+ *       }
+ *     ],
+ *     reason: string,
+ *   }
+ */
+
+import { isVpForeign } from '../memory/scope-tree.js';
+
+/** @typedef {{ userOriginal: string, intent: string }} ForwardQuery */
+/** @typedef {{ memoryPaths: string[], taskIds: string[] }} Preselect */
+/** @typedef {{
+ *    vpId: string,
+ *    forwardQuery: ForwardQuery,
+ *    preselect: Preselect,
+ *    thinking: 'high'|'max'|null,
+ *    thinkingReason: string,
+ *  }} VpPlan
+ */
+/** @typedef {{
+ *    action: 'continue'|'switch_vp'|'fork_task'|'join_task'|'broadcast'|'noop',
+ *    targetTaskId: string | null,
+ *    plans: VpPlan[],
+ *    reason: string,
+ *  }} RouterDecisionV2
+ */
+
+const ALLOWED_ACTIONS = new Set([
+  'continue', 'switch_vp', 'fork_task', 'join_task', 'broadcast', 'noop',
+]);
+
+const ALLOWED_THINKING = new Set([null, 'high', 'max']);
+
+/**
+ * Validate + canonicalise a router decision. Throws on truly malformed
+ * input (we want loud failures during Phase 3 wiring), but tolerates
+ * missing optional fields by filling defaults.
+ *
+ * @param {*} raw
+ * @returns {RouterDecisionV2}
+ */
+export function validateDecision(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('validateDecision: decision must be an object');
+  }
+  const action = ALLOWED_ACTIONS.has(raw.action) ? raw.action : 'continue';
+  const targetTaskId = (typeof raw.targetTaskId === 'string' && raw.targetTaskId)
+    ? raw.targetTaskId : null;
+  if (!Array.isArray(raw.plans)) {
+    throw new Error('validateDecision: plans must be an array');
+  }
+  const plans = raw.plans.map(validatePlan);
+  const reason = typeof raw.reason === 'string' ? raw.reason : '';
+  return { action, targetTaskId, plans, reason };
+}
+
+/**
+ * @param {*} raw
+ * @returns {VpPlan}
+ */
+export function validatePlan(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('validatePlan: plan must be an object');
+  }
+  if (typeof raw.vpId !== 'string' || !raw.vpId) {
+    throw new Error('validatePlan: vpId required');
+  }
+  const fq = raw.forwardQuery && typeof raw.forwardQuery === 'object'
+    ? raw.forwardQuery : {};
+  const userOriginal = typeof fq.userOriginal === 'string' ? fq.userOriginal : '';
+  const intent = typeof fq.intent === 'string' ? fq.intent : '';
+  const pre = raw.preselect && typeof raw.preselect === 'object'
+    ? raw.preselect : {};
+  const memoryPaths = Array.isArray(pre.memoryPaths)
+    ? pre.memoryPaths.filter(p => typeof p === 'string' && p)
+    : [];
+  const taskIds = Array.isArray(pre.taskIds)
+    ? pre.taskIds.filter(t => typeof t === 'string' && t)
+    : [];
+  const thinkingRaw = raw.thinking === undefined ? null : raw.thinking;
+  const thinking = ALLOWED_THINKING.has(thinkingRaw) ? thinkingRaw : null;
+  const thinkingReason = typeof raw.thinkingReason === 'string'
+    ? raw.thinkingReason : '';
+  return {
+    vpId: raw.vpId,
+    forwardQuery: { userOriginal, intent },
+    preselect: { memoryPaths, taskIds },
+    thinking,
+    thinkingReason,
+  };
+}
+
+/**
+ * Strip `vp/<other>/` paths from a plan's `preselect.memoryPaths`. The
+ * planner runs BEFORE the worker so this is the right place to enforce
+ * the cross-VP private-memory hard block (DESIGN.md §2.2). Returns a new
+ * plan; original is not mutated.
+ *
+ * @param {VpPlan} plan
+ * @returns {VpPlan}
+ */
+export function stripForeignVpPaths(plan) {
+  if (!plan) return plan;
+  const own = plan.vpId;
+  const filtered = plan.preselect.memoryPaths.filter(p => !isVpForeign(p, own));
+  if (filtered.length === plan.preselect.memoryPaths.length) return plan;
+  return {
+    ...plan,
+    preselect: { ...plan.preselect, memoryPaths: filtered },
+  };
+}
+
+/**
+ * Produce a default single-plan decision for "explicit @vp" or "no router
+ * needed" paths. The dispatcher uses this when it has decided not to call
+ * the LLM router (DESIGN.md §1.2.1 scenario A — explicit @vp; or §9.15
+ * priorPlan skip).
+ *
+ * @param {{
+ *   vpId: string,
+ *   userOriginal: string,
+ *   intent?: string,
+ *   memoryPaths?: string[],
+ *   taskIds?: string[],
+ *   targetTaskId?: string | null,
+ *   thinking?: 'high'|'max'|null,
+ *   thinkingReason?: string,
+ *   action?: RouterDecisionV2['action'],
+ *   reason?: string,
+ * }} args
+ * @returns {RouterDecisionV2}
+ */
+export function buildDirectDecision(args) {
+  const {
+    vpId, userOriginal, intent = '',
+    memoryPaths = [], taskIds = [],
+    targetTaskId = null,
+    thinking = null, thinkingReason = '',
+    action = 'continue', reason = 'direct',
+  } = args || {};
+  if (!vpId) throw new Error('buildDirectDecision: vpId required');
+  return validateDecision({
+    action,
+    targetTaskId,
+    plans: [{
+      vpId,
+      forwardQuery: { userOriginal, intent },
+      preselect: { memoryPaths, taskIds },
+      thinking,
+      thinkingReason,
+    }],
+    reason,
+  });
+}
+
+/**
+ * Translate a legacy `intent-classifier` single-thread decision (action +
+ * targetThreadId) into the V2 plans schema. We treat the old `targetThreadId`
+ * as the `vpId` because — in the multi-VP redesign — every "thread" is a VP
+ * (groups are sessions, see DESIGN.md §0.1). Callers that still produce
+ * legacy decisions can pipe them through this until Phase 3b.
+ *
+ * Mapping:
+ *   continue / switch → continue / switch_vp (single-VP plan)
+ *   fork              → fork_task   (single-VP plan)
+ *   anything else     → continue
+ *
+ * @param {{
+ *   action?: string,
+ *   targetThreadId?: string,
+ *   reason?: string,
+ *   source?: string,
+ * }} legacy
+ * @param {string} userOriginal
+ * @returns {RouterDecisionV2}
+ */
+export function wrapLegacyDecision(legacy, userOriginal = '') {
+  if (!legacy || typeof legacy !== 'object') {
+    return validateDecision({ action: 'noop', targetTaskId: null, plans: [], reason: '' });
+  }
+  const vpId = typeof legacy.targetThreadId === 'string' ? legacy.targetThreadId : '';
+  if (!vpId) {
+    return validateDecision({ action: 'noop', targetTaskId: null, plans: [], reason: legacy.reason || '' });
+  }
+  let action = 'continue';
+  if (legacy.action === 'switch') action = 'switch_vp';
+  else if (legacy.action === 'fork') action = 'fork_task';
+  else if (legacy.action === 'continue') action = 'continue';
+  return validateDecision({
+    action,
+    targetTaskId: null,
+    reason: legacy.reason || '',
+    plans: [{
+      vpId,
+      forwardQuery: { userOriginal, intent: '' },
+      preselect: { memoryPaths: [], taskIds: [] },
+      thinking: null,
+      thinkingReason: '',
+    }],
+  });
+}
+
+/**
+ * Sequential fan-out runner. Calls `runOne(plan, index, prior)` for each
+ * plan in order, awaiting each before starting the next. The previous
+ * plans' results are passed via `prior` so a later plan can read what an
+ * earlier plan emitted (DESIGN.md §1.2.1 — "ordering is load bearing").
+ *
+ * Plans whose `vpId` is missing from `groupMemberIds` (when the caller
+ * supplies that whitelist) are skipped with a logged `skipped:not_member`
+ * entry — never silently routed to a non-member.
+ *
+ * Errors from `runOne` are caught, recorded, and the loop continues; the
+ * report holds whatever each plan produced. The dispatcher decides whether
+ * to surface or retry.
+ *
+ * @param {VpPlan[]} plans
+ * @param {(plan: VpPlan, index: number, prior: any[]) => Promise<*>} runOne
+ * @param {{ groupMemberIds?: string[] }} [opts]
+ * @returns {Promise<{ results: any[], errors: Array<{ index: number, error: Error }> }>}
+ */
+export async function runPlansSequential(plans, runOne, opts = {}) {
+  if (!Array.isArray(plans)) throw new Error('runPlansSequential: plans array required');
+  if (typeof runOne !== 'function') throw new Error('runPlansSequential: runOne fn required');
+  const memberSet = Array.isArray(opts.groupMemberIds)
+    ? new Set(opts.groupMemberIds) : null;
+  const results = [];
+  const errors = [];
+  const prior = [];
+  for (let i = 0; i < plans.length; i += 1) {
+    const plan = plans[i];
+    if (memberSet && !memberSet.has(plan.vpId)) {
+      const skip = { index: i, vpId: plan.vpId, skipped: 'not_member' };
+      results.push(skip);
+      prior.push(skip);
+      continue;
+    }
+    try {
+      const out = await runOne(plan, i, prior);
+      results.push(out);
+      prior.push(out);
+    } catch (err) {
+      errors.push({ index: i, error: err });
+      // Insert a sentinel into prior so a later plan can see "the previous
+      // VP errored" rather than nothing — useful when a fallback VP is
+      // queued behind a primary.
+      prior.push({ index: i, vpId: plan.vpId, error: err });
+    }
+  }
+  return { results, errors };
+}