@yeaft/webchat-agent 0.1.592 → 0.1.594

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.592",
+  "version": "0.1.594",
   "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/prompts.js

@@ -163,6 +163,8 @@ const RAW_TEMPLATES = {
   // buildRouterPrompt callers will simply omit the section.
   harnessWorkerShape: readTemplate('harness/worker-shape.md', { required: false }),
   harnessRouterShape: readTemplate('harness/router-shape.md', { required: false }),
+  // Phase 3b — coordinator harness rule for inter-VP forwarding.
+  harnessRouterHandoff: readTemplate('harness/router-handoff.md', { required: false }),
 };
 
 /**
@@ -768,6 +770,39 @@ export function buildWorkerPrompt(params = {}) {
   return parts.join('\n\n');
 }
 
+/**
+ * Render the previous turn's router plan as a `## prior_plan` block, so
+ * the router can decide whether to extend it or start fresh
+ * (DESIGN.md §9.15). Returns '' when there is no prior plan to render.
+ *
+ * @param {object|null|undefined} priorPlan
+ * @param {'en'|'zh'} [language='en']
+ * @returns {string}
+ */
+export function renderPriorPlan(priorPlan, language = 'en') {
+  if (!priorPlan || typeof priorPlan !== 'object') return '';
+  const header = language === 'zh' ? '## 上一轮 plan' : '## prior_plan';
+  const lines = [];
+  if (priorPlan.vpId) lines.push(`vpId: ${priorPlan.vpId}`);
+  const fq = priorPlan.forwardQuery;
+  if (fq && (fq.userOriginal || fq.intent)) {
+    if (fq.intent) lines.push(`intent: ${fq.intent}`);
+    if (fq.userOriginal) lines.push(`userOriginal: ${fq.userOriginal}`);
+  }
+  const pre = priorPlan.preselect;
+  if (pre) {
+    if (Array.isArray(pre.memoryPaths) && pre.memoryPaths.length) {
+      lines.push(`memoryPaths: ${pre.memoryPaths.join(', ')}`);
+    }
+    if (Array.isArray(pre.taskIds) && pre.taskIds.length) {
+      lines.push(`taskIds: ${pre.taskIds.join(', ')}`);
+    }
+  }
+  if (priorPlan.thinking) lines.push(`thinking: ${priorPlan.thinking}`);
+  if (!lines.length) return '';
+  return `${header}\n${lines.join('\n')}`;
+}
+
 /**
  * Router prompt entry point (DESIGN.md Phase 1).
  *
@@ -780,12 +815,13 @@ export function buildWorkerPrompt(params = {}) {
  *   language?: 'en'|'zh',
  *   summaries?: {user?: string, group?: string, vp?: string},
  *   routerContext?: string,
+ *   priorPlan?: object|null,
  *   includeShape?: boolean,
  * }} params
  * @returns {string}
  */
 export function buildRouterPrompt(params = {}) {
-  const { language = 'en', summaries, routerContext, includeShape = true } = params;
+  const { language = 'en', summaries, routerContext, priorPlan, includeShape = true } = params;
   const parts = [];
 
   if (includeShape) {
@@ -796,6 +832,9 @@ export function buildRouterPrompt(params = {}) {
   const summaryBlock = renderLayerASummaries(summaries, language);
   if (summaryBlock) parts.push(summaryBlock);
 
+  const priorBlock = renderPriorPlan(priorPlan, language);
+  if (priorBlock) parts.push(priorBlock);
+
   if (typeof routerContext === 'string' && routerContext.trim()) {
     parts.push(routerContext.trim());
   }

package/unify/router/continuity.js

@@ -0,0 +1,108 @@
+/**
+ * router/continuity.js — DESIGN.md §9.15 priorPlan carry-back.
+ *
+ * Phase 3b scope:
+ *   - `attachRouterPlan(message, plan)` — write the plan as `_meta.routerPlan`
+ *     on the assistant message that produced it.
+ *   - `extractPriorPlan(messages, vpId)` — find the most recent assistant
+ *     message belonging to the given VP and return its `_meta.routerPlan`.
+ *   - `stripMetaForWire(messages)` — drop `_meta` before sending to the LLM
+ *     (it's bookkeeping, never model-visible).
+ *
+ * The skip-router heuristic (§9.15 #1) is intentionally NOT implemented in
+ * Phase 3b — DESIGN.md §8 line 391 says "do NOT ship the skip-router
+ * heuristic yet". We just plumb the metadata; the dispatcher can decide.
+ *
+ * Per-VP attribution: an assistant message belongs to a VP when its
+ * `_meta.routerPlan.vpId` matches; we never guess from content. First turn
+ * of a fresh group has no priorPlan — that is the expected cold-start.
+ */
+
+/** @typedef {{
+ *   vpId: string,
+ *   forwardQuery?: { userOriginal?: string, intent?: string },
+ *   preselect?: { memoryPaths?: string[], taskIds?: string[] },
+ *   thinking?: 'high'|'max'|null,
+ *   thinkingReason?: string,
+ * }} RouterPlanLike
+ */
+
+/**
+ * Attach a router plan to an assistant message. Mutates `message` in place
+ * and returns it. We mutate (rather than clone) because the caller is the
+ * engine appending to its own `conversationMessages` array — cloning would
+ * just discard the work.
+ *
+ * Tool messages do not carry plans (no plan attached to a tool result).
+ *
+ * @param {object} message
+ * @param {RouterPlanLike|null|undefined} plan
+ * @returns {object}
+ */
+export function attachRouterPlan(message, plan) {
+  if (!message || typeof message !== 'object') return message;
+  if (message.role !== 'assistant') return message;
+  if (!plan || typeof plan !== 'object' || !plan.vpId) return message;
+  message._meta = message._meta || {};
+  message._meta.routerPlan = {
+    vpId: plan.vpId,
+    forwardQuery: plan.forwardQuery
+      ? {
+        userOriginal: plan.forwardQuery.userOriginal || '',
+        intent: plan.forwardQuery.intent || '',
+      } : undefined,
+    preselect: plan.preselect
+      ? {
+        memoryPaths: Array.isArray(plan.preselect.memoryPaths)
+          ? [...plan.preselect.memoryPaths] : [],
+        taskIds: Array.isArray(plan.preselect.taskIds)
+          ? [...plan.preselect.taskIds] : [],
+      } : undefined,
+    thinking: plan.thinking ?? null,
+    thinkingReason: plan.thinkingReason || '',
+  };
+  return message;
+}
+
+/**
+ * Walk `messages` from the end, return the most recent assistant message's
+ * `_meta.routerPlan` whose `vpId` matches. Returns null if none found —
+ * that's a cold start, not an error.
+ *
+ * @param {object[]} messages
+ * @param {string} vpId
+ * @returns {RouterPlanLike | null}
+ */
+export function extractPriorPlan(messages, vpId) {
+  if (!Array.isArray(messages) || !vpId) return null;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const m = messages[i];
+    if (!m || m.role !== 'assistant') continue;
+    const plan = m._meta && m._meta.routerPlan;
+    if (plan && plan.vpId === vpId) return plan;
+  }
+  return null;
+}
+
+/**
+ * Return a copy of the messages array with `_meta` stripped from every
+ * message. The serialisers (anthropic/openai-responses) read this; it is
+ * NEVER part of the wire payload. Cheap because we only shallow-clone the
+ * messages that actually have `_meta`.
+ *
+ * @param {object[]} messages
+ * @returns {object[]}
+ */
+export function stripMetaForWire(messages) {
+  if (!Array.isArray(messages)) return messages;
+  let mutated = false;
+  const out = messages.map(m => {
+    if (m && typeof m === 'object' && '_meta' in m) {
+      mutated = true;
+      const { _meta, ...rest } = m;
+      return rest;
+    }
+    return m;
+  });
+  return mutated ? out : messages;
+}

package/unify/router/thinking.js

@@ -0,0 +1,78 @@
+/**
+ * router/thinking.js — DESIGN.md §9.16 thinking-mode precedence chain.
+ *
+ * Resolves the final `thinking` value the engine should pass to the
+ * adapter, given the four signal sources:
+ *
+ *   1. UI override     (highest)  — submitOptions / topbar selector
+ *   2. Router plan     —           — per-plan thinking field
+ *   3. VP default      —           — vp/<id>/role.md frontmatter
+ *   4. Global default  (lowest)    — config.thinking.default
+ *
+ * Allowed values: `'high' | 'max' | null`. (`null` ⇒ adapter drops the
+ * field; provider-specific normalisation happens at the adapter via
+ * `models.js#normalizeEffort`.)
+ *
+ * Continuity rule (§9.16): when no UI override is in force AND the router
+ * did not change its recommendation versus the prior plan, keep the prior
+ * plan's value. Anthropic prompt cache keys include the thinking field;
+ * unstable values cause prefix re-encoding every turn.
+ *
+ * The `allowRouterEscalate: false` config gate hard-blocks the router
+ * from bumping below→`max`. UI overrides bypass that gate (they're the
+ * user's direct intent, not a heuristic).
+ */
+
+const ALLOWED = new Set([null, 'high', 'max']);
+
+/**
+ * @param {*} v
+ * @returns {'high'|'max'|null}
+ */
+function clean(v) {
+  if (v === undefined) return null;
+  return ALLOWED.has(v) ? v : null;
+}
+
+/**
+ * @param {{
+ *   uiOverride?: 'high'|'max'|null,
+ *   routerPlan?: 'high'|'max'|null,
+ *   priorPlan?: 'high'|'max'|null,
+ *   vpDefault?: 'high'|'max'|null,
+ *   globalDefault?: 'high'|'max'|null,
+ *   allowRouterEscalate?: boolean,
+ * }} signals
+ * @returns {{ value: 'high'|'max'|null, source: 'ui'|'router'|'prior'|'vp'|'global'|'default' }}
+ */
+export function resolveThinking(signals = {}) {
+  const ui = clean(signals.uiOverride);
+  if (ui) return { value: ui, source: 'ui' };
+
+  const router = clean(signals.routerPlan);
+  const prior = clean(signals.priorPlan);
+  const vp = clean(signals.vpDefault);
+  const global_ = clean(signals.globalDefault);
+  const escalateOk = signals.allowRouterEscalate !== false;
+
+  // Continuity: if router agrees with prior or is silent, prefer prior to
+  // keep the cache key stable.
+  if (router && prior && router === prior) {
+    return { value: prior, source: 'prior' };
+  }
+
+  if (router) {
+    // allowRouterEscalate=false hard-blocks router from emitting 'max'
+    // when the baseline is 'high'.
+    const baseline = prior || vp || global_ || 'high';
+    if (!escalateOk && router === 'max' && baseline !== 'max') {
+      return { value: baseline, source: prior ? 'prior' : (vp ? 'vp' : 'global') };
+    }
+    return { value: router, source: 'router' };
+  }
+
+  if (prior) return { value: prior, source: 'prior' };
+  if (vp) return { value: vp, source: 'vp' };
+  if (global_) return { value: global_, source: 'global' };
+  return { value: 'high', source: 'default' };
+}

package/unify/router/vp-planner.js

@@ -0,0 +1,341 @@
+/**
+ * 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 };
+}
+
+/**
+ * Parallel fan-out runner (Phase 3.5). Calls `runOne(plan, index)` for each
+ * plan concurrently, with optional `concurrency` cap. Results are returned
+ * in input order regardless of completion order. Errors from `runOne` are
+ * caught per-plan and DO NOT abort siblings (DESIGN.md §9.1 — concurrent
+ * VP turns must be independent).
+ *
+ * NOTE: parallel mode loses the `prior[]` channel that the sequential
+ * runner provides. Callers that need plan N to read plan N-1's output must
+ * use `runPlansSequential`. The dispatcher chooses based on whether the
+ * plans share a `targetTaskId` (parallel-safe) or pipeline data
+ * (sequential-only).
+ *
+ * @param {VpPlan[]} plans
+ * @param {(plan: VpPlan, index: number) => Promise<*>} runOne
+ * @param {{ groupMemberIds?: string[], concurrency?: number }} [opts]
+ * @returns {Promise<{ results: any[], errors: Array<{ index: number, error: Error }> }>}
+ */
+export async function runPlansParallel(plans, runOne, opts = {}) {
+  if (!Array.isArray(plans)) throw new Error('runPlansParallel: plans array required');
+  if (typeof runOne !== 'function') throw new Error('runPlansParallel: runOne fn required');
+  const memberSet = Array.isArray(opts.groupMemberIds)
+    ? new Set(opts.groupMemberIds) : null;
+  const concurrency = Number.isFinite(opts.concurrency) && opts.concurrency > 0
+    ? Math.floor(opts.concurrency) : Infinity;
+
+  const results = new Array(plans.length);
+  const errors = [];
+  let nextIdx = 0;
+
+  const runSlot = async () => {
+    // Workers pull tasks from a shared queue index — preserves backpressure
+    // when concurrency < plans.length without per-task scheduling overhead.
+    while (true) {
+      const i = nextIdx;
+      nextIdx += 1;
+      if (i >= plans.length) return;
+      const plan = plans[i];
+      if (memberSet && !memberSet.has(plan.vpId)) {
+        results[i] = { index: i, vpId: plan.vpId, skipped: 'not_member' };
+        continue;
+      }
+      try {
+        results[i] = await runOne(plan, i);
+      } catch (err) {
+        errors.push({ index: i, error: err });
+        results[i] = { index: i, vpId: plan.vpId, error: err };
+      }
+    }
+  };
+
+  const workerCount = Math.min(plans.length, concurrency);
+  const workers = [];
+  for (let w = 0; w < workerCount; w += 1) workers.push(runSlot());
+  await Promise.all(workers);
+
+  return { results, errors };
+}

package/unify/templates/harness/router-handoff.md

@@ -0,0 +1,34 @@
+<!-- lang:en -->
+# Harness — Router Handoff
+
+If, while drafting your reply, you realise you are the wrong VP for this
+turn, hand off instead of guessing. Call `route_forward(targetVpId, reason)`
+with a short, actionable reason. The next turn becomes the receiving VP's
+turn with your reason as the inbound envelope — they act with no other
+context from you.
+
+Use this when:
+
+- The user's question is outside your expertise and another VP in the
+  group clearly owns it.
+- Your read of the situation is "this is comms not kernel" / "this is
+  legal not engineering" — name the boundary.
+
+Do NOT use this to dodge hard questions you legitimately own. The router
+already picked you; only forward when the topic genuinely belongs to
+someone else.
+<!-- lang:zh -->
+# Harness — Router 转交
+
+如果你在起草回复时发现本轮应该由其他 VP 来回答，请直接转交，而不是
+强答。调用 `route_forward(targetVpId, reason)` 并给出简短可操作的原因。
+下一轮变为目标 VP 的回合，你给的 reason 即为他们看到的入站信封——他
+们不会读到你的其他上下文。
+
+适用场景：
+
+- 用户的问题超出你的专业范围，群里另一个 VP 显然更合适。
+- 你判断「这是沟通不是内核」/「这是法务不是工程」——说出边界。
+
+不要用它来回避你确实该回答的问题。Router 既然选了你，只有当话题
+确实属于他人时才转交。