@yeaft/webchat-agent 0.1.532 → 0.1.534

package/package.json

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

package/unify/memory/migrate-r5-to-r6.js

@@ -1,22 +1,89 @@
 /**
- * migrate-r5-to-r6.js — task-334f §Δ23 migration stub.
+ * migrate-r5-to-r6.js — task-334i (wave-4) R5 → R6 storage migration.
  *
- * Legacy (R5): `~/.yeaft/memory/entries/<slug>.md` plus numeric shard files
- *              `memory-001.md`, `memory-002.md`, ...
+ * Continuation of task-334i-v0 (PR #552, shipped v0.1.521) which established
+ * the general `~/.yeaft/` tree via `v0-to-v1.js`. This slice implements the
+ * R5→R6 *memory shard + conversation rotation* pass that fleshes out the
+ * previously-stubbed `applyR5ToR6Migration`.
  *
- * R6:          `~/.yeaft/memory/vp/<vpId>/memory-<semantic>.md`
- *              Semantic shards: skill / relations / lessons / preferences /
- *                               project-<slug>
+ * Spec: .crew/context/task-334i-impl-spec.md
  *
- * This slice (334f) only DEFINES the API surface and a dry-run classifier.
- * The actual batch migration runs in 334i; 334f does not mutate disk.
+ * Key invariants:
+ *   - This is independently idempotent from v0→v1. State version bumps r5→r6.
+ *   - Does NOT touch 334f `shard-store.js` or 334o storage primitives —
+ *     only consumes their public APIs.
+ *   - Legacy R5 data is archived to `.legacy/r6-state.tar.gz` BEFORE any
+ *     write. Rollback restores the archive but never deletes it.
+ *   - `migration-state.json` is the single source of truth; writes go
+ *     through `writeAtomic` (tmp+rename) mirroring 334f commitRecompression.
+ *
+ * Two-pass algorithm (pre-emptive discovery #2):
+ *   Pass 1 — write each entry to its default semantic shard
+ *            (skill / relations / lessons / preferences / project-legacy)
+ *            while counting entries per groupId.
+ *   Pass 2 — for each groupId with count ≥ PROJECT_DERIVE_THRESHOLD (30),
+ *            derive a `project-<slug>` shard and move entries via
+ *            stageRecompression / commitRecompression.
+ *
+ * Name drift fix (pre-emptive discovery #1):
+ *   `map-fields.js` (shipped) defines MIGRATION_AUTHOR='system:migration-v0-to-v1'.
+ *   Correct spec value is 'system:migration-v0-v1'. This file overrides via
+ *   local constants without editing the shipped pure-mapper module.
  */
 
-import { existsSync, readdirSync, readFileSync } from 'fs';
-import { join } from 'path';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { createHash } from 'crypto';
+import { execFileSync } from 'child_process';
+
+import { openLog, writeAtomic } from '../storage/index.js';
 import { parseEntry } from './store.js';
-import { classifyLegacyEntryToShard } from './shard-store.js';
+import {
+  openMemoryShardStore,
+  classifyLegacyEntryToShard,
+} from './shard-store.js';
+import { PROJECT_DERIVE_THRESHOLD } from './schema.js';
+import {
+  parseFrontmatter,
+  mapMessageMdToJsonl,
+  splitCoordinatorTurns,
+  LEGACY_GROUP_ID,
+  LEGACY_VP_ID,
+} from '../migration/map-fields.js';
+
+// ─── Name-drift fix (spec §3, §4) ────────────────────────────────
+export const R5_TO_R6_AUTHOR_SYS = 'system:migration-v0-v1';
+export const R5_TO_R6_AUTHOR_USER = 'user:migration-v0-v1';
+const SOURCE_HINT = 'legacy-r5-migration';
+const STATE_FILE = 'migration-state.json';
+const ARCHIVE_REL = join('.legacy', 'r6-state.tar.gz');
+
+// authoredBy inference table (spec §3 deliverable E).
+function inferAuthoredBy(kind) {
+  switch (kind) {
+    case 'preference':
+    case 'identity':
+      return R5_TO_R6_AUTHOR_USER;
+    case 'fact':
+    case 'skill':
+    case 'lesson':
+    case 'context':
+    case 'relation':
+    default:
+      return R5_TO_R6_AUTHOR_SYS;
+  }
+}
 
+// ─── Planner (dry-run, unchanged behaviour from 334f stub) ───────
 /**
  * Produce a migration plan without applying it.
  *
@@ -50,12 +117,495 @@ export function planR5ToR6Migration(legacyEntriesDir) {
   return { totalEntries: plan.length, plan, byShard };
 }
 
+// ─── State I/O ────────────────────────────────────────────────────
+function stateFilePath(yeaftDir) {
+  return join(yeaftDir, STATE_FILE);
+}
+
+function loadState(yeaftDir) {
+  const p = stateFilePath(yeaftDir);
+  if (!existsSync(p)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function saveState(yeaftDir, state) {
+  writeAtomic(stateFilePath(yeaftDir), JSON.stringify(state, null, 2));
+}
+
+function clearState(yeaftDir) {
+  const p = stateFilePath(yeaftDir);
+  if (existsSync(p)) rmSync(p);
+}
+
+function nowIso() { return new Date().toISOString(); }
+
+function stableId(slug) {
+  const h = createHash('sha1').update(String(slug)).digest('hex').slice(0, 12);
+  return `mem_legacy_${h}`;
+}
+
+// ─── Archive helper (spec §11 step 3) ────────────────────────────
+/**
+ * tar+gzip `memory/entries/` and `conversations/` into .legacy/r6-state.tar.gz.
+ * Uses the `tar` CLI via execFileSync (same pattern as 334i-v0). Any failure
+ * throws so the caller can bail before making destructive changes.
+ */
+export function archiveR5State(yeaftDir) {
+  const legacyDir = join(yeaftDir, '.legacy');
+  mkdirSync(legacyDir, { recursive: true });
+  const archivePath = join(yeaftDir, ARCHIVE_REL);
+  const entriesDir = join(yeaftDir, 'memory', 'entries');
+  const conversationsDir = join(yeaftDir, 'conversations');
+  const args = ['-czf', archivePath, '-C', yeaftDir];
+  let added = 0;
+  if (existsSync(entriesDir)) { args.push(join('memory', 'entries')); added++; }
+  if (existsSync(conversationsDir)) { args.push('conversations'); added++; }
+  if (added === 0) {
+    // Write a zero-content marker so rollback has a file to inspect.
+    writeAtomic(archivePath, '');
+    return archivePath;
+  }
+  execFileSync('tar', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+  return archivePath;
+}
+
+// ─── Detect helpers ──────────────────────────────────────────────
+/**
+ * Classify the shape of the R5 memory layout in `yeaftDir`.
+ */
+export function detectR5MemoryLayout(yeaftDir) {
+  const entriesDir = join(yeaftDir, 'memory', 'entries');
+  const conversationsDir = join(yeaftDir, 'conversations');
+  const groupsDir = join(yeaftDir, 'groups');
+  const hasEntries = existsSync(entriesDir) && readdirSync(entriesDir).some(f => f.endsWith('.md'));
+  const hasConversationsMd = existsSync(conversationsDir)
+    && readdirSync(conversationsDir).some(() => true);
+  const hasGroupsJsonl = existsSync(groupsDir);
+  return {
+    entriesDir,
+    conversationsDir,
+    groupsDir,
+    hasEntries,
+    hasConversationsMd,
+    hasGroupsJsonl,
+  };
+}
+
+// ─── Pass 1: write entries to default shards ─────────────────────
+function runPass1({ yeaftDir, layout, vpDir, log, existingState }) {
+  const shardStore = openMemoryShardStore(vpDir, 'vp');
+  const files = layout.hasEntries
+    ? readdirSync(layout.entriesDir).filter(f => f.endsWith('.md')).sort()
+    : [];
+  const counts = (existingState && existingState.counts) || {};
+  const migrated = [];
+  const errors = [];
+
+  for (const file of files) {
+    const slug = file.replace(/\.md$/, '');
+    const id = stableId(slug);
+    // Idempotency: skip already-migrated ids.
+    if (shardStore.get(id)) {
+      migrated.push({ id, slug, shard: shardStore.get(id).shard, skipped: true });
+      continue;
+    }
+    let raw;
+    try {
+      raw = readFileSync(join(layout.entriesDir, file), 'utf8');
+    } catch (e) {
+      errors.push({ file, error: String(e.message || e) });
+      continue;
+    }
+    const legacy = parseEntry(raw);
+    if (!legacy) {
+      errors.push({ file, error: 'parseEntry returned null (malformed frontmatter)' });
+      continue;
+    }
+    const shard = classifyLegacyEntryToShard(legacy);
+    const kind = legacy.kind || 'fact';
+    const tags = Array.isArray(legacy.tags) ? legacy.tags.slice() : [];
+    const createdAt = legacy.created_at || nowIso();
+    const updatedAt = legacy.updated_at || createdAt;
+    // Determine groupId for project-derive counting. Legacy schema has no
+    // explicit groupId; fall back to scope's top segment, else LEGACY_GROUP_ID.
+    const groupId = deriveGroupId(legacy);
+
+    // identity/preference kinds are allowed empty msgIds per §Δ23.
+    // Other kinds rely on the hint='legacy-r5-migration' to legitimise [].
+    // `validateR6Entry` requires non-empty msgIds for non-identity/preference —
+    // so we put a synthetic legacy marker to keep the validator happy while
+    // still conveying "migrated, no real messages attached" semantically.
+    const needsMsgIdMarker = !(kind === 'identity' || kind === 'preference');
+    const msgIds = needsMsgIdMarker ? [`legacy:${slug}`] : [];
+
+    const entry = {
+      id,
+      shard,
+      kind,
+      tags,
+      pinned: legacy.importance === 'high',
+      sourceRef: {
+        groupId,
+        taskId: null,
+        msgIds,
+        timeWindow: `[${createdAt}, ${updatedAt}]`,
+        hint: SOURCE_HINT,
+      },
+      supersedes: null,
+      supersededBy: null,
+      authoredBy: inferAuthoredBy(kind),
+      createdAt,
+      updatedAt,
+      body: legacy.content || '',
+    };
+    try {
+      shardStore.put(entry);
+      counts[groupId] = (counts[groupId] || 0) + 1;
+      migrated.push({ id, slug, shard, groupId });
+    } catch (e) {
+      errors.push({ file, error: String(e.message || e) });
+    }
+  }
+
+  log('pass1', { migrated: migrated.length, errors: errors.length });
+  return { counts, migrated, errors };
+}
+
+function deriveGroupId(legacyEntry) {
+  // scope is a path like "work/project-name/auth". Use first segment as
+  // coarse groupId; fall back to LEGACY_GROUP_ID.
+  const scope = legacyEntry && legacyEntry.scope;
+  if (typeof scope === 'string' && scope.trim()) {
+    const first = scope.split('/').map(s => s.trim()).filter(Boolean)[0];
+    if (first) return first;
+  }
+  return LEGACY_GROUP_ID;
+}
+
+// ─── Pass 2: project-<slug> derive ───────────────────────────────
+function runPass2({ vpDir, counts, log }) {
+  const derived = [];
+  const qualifyingShards = Object.entries(counts || {})
+    .filter(([, c]) => c >= PROJECT_DERIVE_THRESHOLD)
+    .map(([g]) => `project-${slugify(g)}`);
+  // Re-open with project-<slug> allow-listed up front so put() validates.
+  const shardStore = openMemoryShardStore(vpDir, 'vp', { extraShards: qualifyingShards });
+  for (const [groupId, count] of Object.entries(counts || {})) {
+    if (count < PROJECT_DERIVE_THRESHOLD) continue;
+    const slug = slugify(groupId);
+    const targetShard = `project-${slug}`;
+    // Skip if this project shard already exists and is populated — re-entry safe.
+    const stats = shardStore.stats();
+    if (stats.shards[targetShard] && stats.shards[targetShard].count > 0) {
+      derived.push({ groupId, shard: targetShard, moved: 0, skipped: true });
+      continue;
+    }
+    // Collect entries in the relevant default shard matching this groupId.
+    // Search across all default shards (classification is kind-driven; a
+    // groupId may span skill/lessons/etc).
+    const { results } = shardStore.query({});
+    const moveIds = results
+      .filter(r => r.groupId === groupId)
+      .map(r => r.id);
+    let moved = 0;
+    for (const id of moveIds) {
+      const full = shardStore.get(id);
+      if (!full) continue;
+      // Re-put with new shard; old entry removal happens via supersede-free
+      // rewrite by removing old id after the new one lands.
+      const newEntry = {
+        ...full,
+        shard: targetShard,
+        body: full.body || '',
+      };
+      try {
+        shardStore.put(newEntry);
+        // shardStore.put upserts by id (see 334o shard-store put semantics
+        // removing any prior shard copy of the same id) — so the entry now
+        // lives in targetShard exclusively.
+        moved++;
+      } catch {
+        // best-effort — keep legacy in default shard if move fails.
+      }
+    }
+    derived.push({ groupId, shard: targetShard, moved });
+  }
+  log('pass2', { derived: derived.length });
+  return derived;
+}
+
+function slugify(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'legacy';
+}
+
+// ─── Conversation migration ──────────────────────────────────────
+function migrateConversations({ yeaftDir, layout, log }) {
+  if (!layout.hasConversationsMd) {
+    log('conversations', { messages: 0, shards: 0 });
+    return { messages: 0, shards: 0 };
+  }
+  const groupDir = join(yeaftDir, 'groups', LEGACY_GROUP_ID, 'messages');
+  mkdirSync(groupDir, { recursive: true });
+  const log_ = openLog(groupDir);
+  let messagesWritten = 0;
+  const convos = readdirSync(layout.conversationsDir);
+  for (const cId of convos) {
+    const msgDir = join(layout.conversationsDir, cId, 'messages');
+    if (!existsSync(msgDir)) continue;
+    const files = readdirSync(msgDir).filter(f => f.endsWith('.md')).sort();
+    for (const file of files) {
+      const raw = readFileSync(join(msgDir, file), 'utf8');
+      const { meta, body } = parseFrontmatter(raw);
+      const originalId = `${cId}_${file.replace(/\.md$/, '')}`;
+      const row = mapMessageMdToJsonl({ meta, body, originalId, fallbackTaskId: null });
+      try {
+        log_.append(row);
+        messagesWritten++;
+      } catch {
+        // Skip malformed row; keep going.
+      }
+    }
+    // Also handle coordinator.md if present
+    const coordPath = join(layout.conversationsDir, cId, 'coordinator.md');
+    if (existsSync(coordPath)) {
+      const raw = readFileSync(coordPath, 'utf8');
+      const turns = splitCoordinatorTurns(raw);
+      for (const turn of turns) {
+        const row = {
+          id: `msg_legacy_${cId}_coord_${turn.index}`,
+          ts: turn.ts || null,
+          type: 'chat',
+          authorKind: 'unknown',
+          authorId: `legacy:${turn.role}`,
+          groupId: LEGACY_GROUP_ID,
+          taskId: null,
+          body: turn.body,
+          mentions: [],
+          replyTo: null,
+          viaTool: null,
+        };
+        try { log_.append(row); messagesWritten++; } catch { /* skip */ }
+      }
+    }
+  }
+  log_.close();
+  const index = log_.getIndex();
+  log('conversations', { messages: messagesWritten, shards: (index.segments || []).length });
+  return { messages: messagesWritten, shards: (index.segments || []).length };
+}
+
+// ─── Main entry ──────────────────────────────────────────────────
+/**
+ * Apply the R5 → R6 migration.
+ *
+ * @param {object} opts
+ * @param {string} opts.yeaftDir  required
+ * @param {string} [opts.vpId]    legacy VP id (default LEGACY_VP_ID)
+ * @param {boolean} [opts.dryRun]
+ * @param {boolean} [opts.force]  clear existing r6 state and re-run from scratch
+ * @param {(step, info)=>void} [opts.onStep]
+ * @returns {Promise<object>}
+ */
+export async function applyR5ToR6Migration(opts = {}) {
+  const { yeaftDir, dryRun = false, force = false, onStep } = opts;
+  const vpId = opts.vpId || LEGACY_VP_ID;
+  if (!yeaftDir || typeof yeaftDir !== 'string') {
+    throw new Error('applyR5ToR6Migration: yeaftDir (string) required');
+  }
+  if (!existsSync(yeaftDir)) {
+    throw new Error(`applyR5ToR6Migration: yeaftDir does not exist: ${yeaftDir}`);
+  }
+  const log = typeof onStep === 'function' ? onStep : () => {};
+  const layout = detectR5MemoryLayout(yeaftDir);
+
+  if (dryRun) {
+    const plan = planR5ToR6Migration(layout.entriesDir);
+    const counts = {};
+    for (const p of plan.plan) {
+      // coarse counting keyed by synthetic groupId based on slug prefix (best-effort preview)
+      counts[LEGACY_GROUP_ID] = (counts[LEGACY_GROUP_ID] || 0) + 1;
+    }
+    const wouldDerive = Object.entries(counts)
+      .filter(([, c]) => c >= PROJECT_DERIVE_THRESHOLD)
+      .map(([g]) => `project-${slugify(g)}`);
+    let estMessages = 0;
+    if (layout.hasConversationsMd) {
+      for (const cId of readdirSync(layout.conversationsDir)) {
+        const msgDir = join(layout.conversationsDir, cId, 'messages');
+        if (existsSync(msgDir)) {
+          estMessages += readdirSync(msgDir).filter(f => f.endsWith('.md')).length;
+        }
+      }
+    }
+    const preview = {
+      pass1: plan.byShard,
+      pass2Candidates: wouldDerive,
+      conversations: {
+        count: layout.hasConversationsMd ? readdirSync(layout.conversationsDir).length : 0,
+        estimatedMessages: estMessages,
+        estimatedShards: Math.max(1, Math.ceil(estMessages / 5000)),
+      },
+    };
+    log('dry-run', preview);
+    return { status: 'dry-run', dryRun: true, preview };
+  }
+
+  // Force: wipe only r6 state, never touch legacy archive.
+  if (force) clearState(yeaftDir);
+
+  let state = loadState(yeaftDir);
+  if (state && state.version === 'r6' && state.pass2CompletedAt) {
+    log('already-done', { migratedAt: state.migratedAt });
+    return { status: 'already-done', state };
+  }
+
+  // Fresh state — but preserve a pre-existing r5 state (from PR #552) if present.
+  if (!state || state.version !== 'r6') {
+    const prior = state || {};
+    state = {
+      version: 'r6',
+      startedAt: nowIso(),
+      legacyArchive: null,
+      pass1CompletedAt: null,
+      pass2CompletedAt: null,
+      migratedAt: null,
+      counts: {},
+      derivedProjects: [],
+      messageCount: 0,
+      entryCount: 0,
+      // Preserve reference to prior r5 state for audit.
+      priorR5: prior && prior.version === 'r5' ? { completedAt: prior.completedAt || null } : null,
+    };
+    saveState(yeaftDir, state);
+  }
+
+  try {
+    // Archive R5 state BEFORE any writes (or skip if already archived in a prior resume).
+    if (!state.legacyArchive) {
+      const archivePath = archiveR5State(yeaftDir);
+      state.legacyArchive = archivePath;
+      saveState(yeaftDir, state);
+      log('archive', { path: archivePath });
+    }
+
+    const vpDir = join(yeaftDir, 'memory', 'vp', vpId);
+    mkdirSync(vpDir, { recursive: true });
+
+    // Pass 1
+    if (!state.pass1CompletedAt) {
+      const p1 = runPass1({ yeaftDir, layout, vpDir, log, existingState: state });
+      state.counts = p1.counts;
+      state.entryCount = (state.entryCount || 0) + p1.migrated.filter(m => !m.skipped).length;
+      state.pass1CompletedAt = nowIso();
+      state.pass1Errors = p1.errors;
+      saveState(yeaftDir, state);
+    } else {
+      log('pass1', { skipped: true });
+    }
+
+    // Pass 2
+    if (!state.pass2CompletedAt) {
+      const derived = runPass2({ vpDir, counts: state.counts, log });
+      state.derivedProjects = derived.map(d => d.shard);
+      state.pass2CompletedAt = nowIso();
+      saveState(yeaftDir, state);
+    } else {
+      log('pass2', { skipped: true });
+    }
+
+    // Conversations (always run once — guarded by index existence).
+    if (!state.conversationsMigratedAt) {
+      const convRes = migrateConversations({ yeaftDir, layout, log });
+      state.messageCount = convRes.messages;
+      state.conversationsMigratedAt = nowIso();
+      saveState(yeaftDir, state);
+    } else {
+      log('conversations', { skipped: true });
+    }
+
+    state.migratedAt = nowIso();
+    saveState(yeaftDir, state);
+    log('done', { migratedAt: state.migratedAt });
+    return { status: 'done', state };
+  } catch (err) {
+    // On error: state file preserved so next run resumes. Archive untouched.
+    state.lastError = String(err && err.message || err);
+    saveState(yeaftDir, state);
+    throw err;
+  }
+}
+
+// ─── Rollback (deliverable G) ────────────────────────────────────
 /**
- * Apply the migration. STUB — 334i will fill in the body writer. 334f keeps
- * this function exported so downstream tests can assert the hook exists.
+ * Roll back an R5→R6 migration. Restores from .legacy/r6-state.tar.gz and
+ * clears r6-specific state. Never touches the separate r5 archive created
+ * by v0-to-v1.js. Idempotent: safe to call when no r6 state is present.
  *
- * @param {object} _opts  { legacyEntriesDir, targetDir, vpId, dryRun }
+ * @param {object} opts
+ * @param {string} opts.yeaftDir required
+ * @param {string} [opts.vpId]   legacy VP id (default LEGACY_VP_ID)
+ * @param {(step, info)=>void} [opts.onStep]
  */
-export async function applyR5ToR6Migration(_opts) {
-  throw new Error('applyR5ToR6Migration: not yet implemented (task-334i)');
+export async function rollbackR5ToR6Migration(opts = {}) {
+  const { yeaftDir, onStep } = opts;
+  const vpId = opts.vpId || LEGACY_VP_ID;
+  if (!yeaftDir || typeof yeaftDir !== 'string') {
+    throw new Error('rollbackR5ToR6Migration: yeaftDir required');
+  }
+  const log = typeof onStep === 'function' ? onStep : () => {};
+  const state = loadState(yeaftDir);
+  if (!state || state.version !== 'r6') {
+    log('noop', { reason: 'no r6 state file present' });
+    return { status: 'noop' };
+  }
+  const archivePath = state.legacyArchive;
+  if (!archivePath || !existsSync(archivePath)) {
+    throw new Error(`rollbackR5ToR6Migration: archive missing at ${archivePath}`);
+  }
+
+  // Delete R6-specific paths first (only what this migration created).
+  const vpDir = join(yeaftDir, 'memory', 'vp', vpId);
+  if (existsSync(vpDir)) {
+    rmSync(vpDir, { recursive: true, force: true });
+    log('rm-vp-memory', { path: vpDir });
+  }
+  const groupsDir = join(yeaftDir, 'groups', LEGACY_GROUP_ID, 'messages');
+  if (existsSync(groupsDir)) {
+    rmSync(groupsDir, { recursive: true, force: true });
+    log('rm-group-messages', { path: groupsDir });
+  }
+
+  // Restore archive back to yeaftDir. tar -xzf will overwrite paths it owns.
+  // Only do this if archive is non-empty (empty marker = nothing was archived).
+  const sz = statSync(archivePath).size;
+  if (sz > 0) {
+    execFileSync('tar', ['-xzf', archivePath, '-C', yeaftDir], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    log('restore', { from: archivePath });
+  } else {
+    log('restore', { from: archivePath, note: 'empty archive — nothing to restore' });
+  }
+
+  // Downgrade state to r5 marker (archive left on disk for audit).
+  const newState = {
+    version: 'r5',
+    rolledBackAt: nowIso(),
+    previousR6: {
+      migratedAt: state.migratedAt,
+      legacyArchive: state.legacyArchive,
+    },
+  };
+  saveState(yeaftDir, newState);
+  log('done', { rolledBackAt: newState.rolledBackAt });
+  return { status: 'done', state: newState };
 }

package/unify/prompts.js

@@ -386,8 +386,17 @@ const DEFAULT_TASK_MEMORY_TOP = 5;
 const DEFAULT_RELATED_TASK_TOP = 3;
 const DEFAULT_RELATED_TASK_MEMORY_TOP = 2;
 const DEFAULT_CORE_MEMORY_TOP = 7;
+// task-334n §Δ31.4 — tightened reminder gate:
+//   (a) currentVpId === initiatorVpId
+//   (b) task.members.length >= 2  (multi-VP only)
+//   (c) nonSummaryCount >= 10  OR  (now - lastSummaryAt) >= 20 min
+// 334e's earlier looser gate (3 msgs / 15 min) is preserved as a legacy
+// fallback path for callers that never set `summaryReminder.members`.
 const SUMMARY_REMINDER_MIN_MESSAGES = 3;
-const SUMMARY_REMINDER_MIN_AGE_MS = 15 * 60 * 1000; // 15 minutes
+const SUMMARY_REMINDER_MIN_AGE_MS = 15 * 60 * 1000; // 15 minutes (legacy)
+const SUMMARY_REMINDER_MIN_TURNS_334N = 10;
+const SUMMARY_REMINDER_MIN_AGE_MS_334N = 20 * 60 * 1000; // 20 minutes
+const SUMMARY_REMINDER_MIN_MEMBERS_334N = 2;
 
 /**
  * Render `## task_ctx` block. Never throws on malformed input — missing
@@ -402,6 +411,7 @@ function renderTaskCtx(taskCtx, lang) {
     taskCtx.relatedTasks,
     taskCtx.currentVpId,
     lang,
+    taskCtx.groupId,
   );
   const reminderLine = renderSummaryReminder(taskCtx, lang);
 
@@ -436,13 +446,17 @@ function renderTaskMemories(memories) {
  * Ordering: by `updatedAt` desc (undefined treated as 0). Top-3 tasks, top-2
  * memory each.
  */
-function renderRelatedTasks(relatedTasks, currentVpId, lang) {
+function renderRelatedTasks(relatedTasks, currentVpId, lang, currentTaskGroupId) {
   if (!Array.isArray(relatedTasks) || relatedTasks.length === 0) return '';
   if (!currentVpId) return ''; // no ACL subject → fail-closed
 
   const allowed = relatedTasks.filter((t) => {
     if (!t || typeof t !== 'object') return false;
     const members = Array.isArray(t.members) ? t.members : null;
+    // task-334n §Δ27.3 — either same-group OR members-intersection grants.
+    if (currentTaskGroupId && t.groupId && t.groupId === currentTaskGroupId) {
+      return true;
+    }
     if (!members) return false; // fail-closed on missing ACL
     return members.includes(currentVpId);
   });
@@ -487,16 +501,26 @@ function renderSummaryReminder(taskCtx, lang) {
   if (taskCtx.currentVpId !== taskCtx.initiatorVpId) return '';
 
   const count = Number(r.nonSummaryCount) || 0;
-  if (count < SUMMARY_REMINDER_MIN_MESSAGES) return '';
-
   const now = Number(r.now) || Date.now();
   const lastAt = Number(r.lastSummaryAt) || 0;
   const ageMs = lastAt > 0 ? now - lastAt : Number.POSITIVE_INFINITY;
-  if (lastAt > 0 && ageMs <= SUMMARY_REMINDER_MIN_AGE_MS) return '';
 
-  // For "never summarized" (lastAt==0) we report age as nonSummaryCount's
-  // session-coarse proxy: we print a dash so the prompt does not lie about
-  // an exact minute count. The hint still carries the count of new msgs.
+  // task-334n §Δ31.4 gate: when `members` is supplied, apply the strict
+  // multi-VP / 20min-or-10turn rule. Otherwise keep the legacy 334e gate
+  // so pre-334n callers still see reminders under the old thresholds.
+  const members = Array.isArray(r.members) ? r.members : null;
+  if (members) {
+    if (members.length < SUMMARY_REMINDER_MIN_MEMBERS_334N) return '';
+    const ageOk = lastAt > 0 && ageMs >= SUMMARY_REMINDER_MIN_AGE_MS_334N;
+    const turnsOk = count >= SUMMARY_REMINDER_MIN_TURNS_334N;
+    // `never summarised` (lastAt=0) only counts when turnsOk, otherwise we
+    // silently wait — aligns with §Δ31.4 "too-soon" reason code.
+    if (!ageOk && !turnsOk) return '';
+  } else {
+    if (count < SUMMARY_REMINDER_MIN_MESSAGES) return '';
+    if (lastAt > 0 && ageMs <= SUMMARY_REMINDER_MIN_AGE_MS) return '';
+  }
+
   const minStr = lastAt > 0 ? String(Math.round(ageMs / 60000)) : '—';
   return lang.taskCtxSummaryReminder(minStr, count);
 }

package/unify/tasks/store.js

@@ -37,6 +37,15 @@ function serializeTask(task) {
   if (task.parentTaskId) fm.push(`parentTaskId: ${task.parentTaskId}`);
   if (task.parentId) fm.push(`parentId: ${task.parentId}`);
   if (task.primaryThreadId) fm.push(`primaryThreadId: ${task.primaryThreadId}`);
+  // task-334n — multi-VP collaboration protocol fields.
+  // initiator: VP id that created the task (fallback target for ACL / reminder).
+  // members:  explicit VP roster for the task (supersedes group roster when set).
+  // groupId:  the group this task belongs to (null for legacy / standalone).
+  if (task.initiator) fm.push(`initiator: ${task.initiator}`);
+  if (Array.isArray(task.members) && task.members.length) {
+    fm.push(`members: [${task.members.join(', ')}]`);
+  }
+  if (task.groupId) fm.push(`groupId: ${task.groupId}`);
   if (task.createdAt) fm.push(`createdAt: ${task.createdAt}`);
   if (task.updatedAt) fm.push(`updatedAt: ${task.updatedAt}`);
 
@@ -81,6 +90,13 @@ function parseTask(raw) {
 
     if (key === 'createdAt' || key === 'updatedAt') {
       task[key] = parseInt(val, 10) || 0;
+    } else if (key === 'members') {
+      // task-334n — members: [vp-a, vp-b, ...]
+      task.members = val
+        .replace(/^\[|\]$/g, '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
     } else {
       task[key] = val;
     }
@@ -181,6 +197,8 @@ export class TaskStore {
   #tasks;
   /** @type {boolean} */
   #readOnly;
+  /** @type {Array<(evt:any)=>void>} */
+  #listeners;
 
   /**
    * @param {string} yeaftDir — Base ~/.yeaft directory
@@ -192,6 +210,7 @@ export class TaskStore {
     this.#planPath = join(this.#dir, 'plan.md');
     this.#tasks = new Map();
     this.#readOnly = opts.readOnly || false;
+    this.#listeners = [];
 
     // Ensure base directory exists
     if (!this.#readOnly) {
@@ -275,6 +294,122 @@ export class TaskStore {
     return task;
   }
 
+  /**
+   * task-334n — add a VP member to a task's collaboration roster.
+   * Idempotent: adding an existing member is a no-op (no event emitted).
+   * Returns `{ task, added: boolean }`.
+   *
+   * If an `onEvent` callback was passed at construction time, emits a
+   * `task_member_added` event synchronously after the write:
+   *   { type: 'task_member_added', taskId, vpId, members, ts }
+   */
+  addMember(id, vpId) {
+    const task = this.#tasks.get(id);
+    if (!task) return { task: null, added: false };
+    if (!vpId || typeof vpId !== 'string') {
+      throw new Error('addMember: vpId required (string)');
+    }
+    const members = Array.isArray(task.members) ? task.members.slice() : [];
+    if (members.includes(vpId)) {
+      return { task, added: false };
+    }
+    members.push(vpId);
+    this.update(id, { members });
+    this.#emit({
+      type: 'task_member_added',
+      taskId: id,
+      vpId,
+      members: members.slice(),
+      ts: Date.now(),
+    });
+    return { task: this.#tasks.get(id), added: true };
+  }
+
+  /**
+   * task-334n — remove a VP member from a task.
+   * Idempotent: removing a non-member is a no-op (no event emitted).
+   * Returns `{ task, removed: boolean }`.
+   * Emits `task_member_removed` on successful removal.
+   */
+  removeMember(id, vpId) {
+    const task = this.#tasks.get(id);
+    if (!task) return { task: null, removed: false };
+    if (!vpId || typeof vpId !== 'string') {
+      throw new Error('removeMember: vpId required (string)');
+    }
+    const members = Array.isArray(task.members) ? task.members.slice() : [];
+    const idx = members.indexOf(vpId);
+    if (idx === -1) return { task, removed: false };
+    members.splice(idx, 1);
+    this.update(id, { members });
+    this.#emit({
+      type: 'task_member_removed',
+      taskId: id,
+      vpId,
+      members: members.slice(),
+      ts: Date.now(),
+    });
+    return { task: this.#tasks.get(id), removed: true };
+  }
+
+  /**
+   * task-334n §Δ27.3 ACL — true iff `vpId` may read `otherTaskId`'s
+   * memory/summary. Pass grants when:
+   *   - both tasks share the same non-null groupId, OR
+   *   - members sets intersect on at least one vpId
+   * Fail-closed: missing task, missing groupId match, no intersection → false.
+   *
+   * @param {string} currentTaskId — task the caller is running in
+   * @param {string} otherTaskId   — task whose data the caller wants to read
+   * @param {string} [vpId]        — caller's vp id; if set, must also be
+   *   a member of currentTaskId (prevents stranger elevating via URL probe)
+   * @returns {boolean}
+   */
+  canAccessRelated(currentTaskId, otherTaskId, vpId) {
+    if (!currentTaskId || !otherTaskId || currentTaskId === otherTaskId) {
+      return false;
+    }
+    const cur = this.#tasks.get(currentTaskId);
+    const other = this.#tasks.get(otherTaskId);
+    if (!cur || !other) return false;
+
+    // If caller claims a vpId, they must be a member of the current task or
+    // its initiator. Otherwise this is a cross-context read — fail-closed.
+    if (vpId) {
+      const curMembers = Array.isArray(cur.members) ? cur.members : [];
+      const isInsider = curMembers.includes(vpId) || cur.initiator === vpId;
+      if (!isInsider) return false;
+    }
+
+    // Same-group rule.
+    if (cur.groupId && other.groupId && cur.groupId === other.groupId) {
+      return true;
+    }
+
+    // Members-intersection rule.
+    const a = Array.isArray(cur.members) ? cur.members : [];
+    const b = Array.isArray(other.members) ? other.members : [];
+    if (a.length === 0 || b.length === 0) return false;
+    const bSet = new Set(b);
+    for (const v of a) if (bSet.has(v)) return true;
+    return false;
+  }
+
+  /** Register an event listener (task-334n member events). */
+  onEvent(fn) {
+    if (typeof fn === 'function') this.#listeners.push(fn);
+    return () => {
+      const i = this.#listeners.indexOf(fn);
+      if (i >= 0) this.#listeners.splice(i, 1);
+    };
+  }
+
+  #emit(evt) {
+    for (const fn of this.#listeners) {
+      try { fn(evt); } catch { /* listener failures must not corrupt store */ }
+    }
+  }
+
   /**
    * Get a task by ID.
    * @param {string} id

package/unify/tasks/summary.js

@@ -0,0 +1,338 @@
+/**
+ * summary.js — task-334n: Task multi-VP collaboration summary protocol.
+ *
+ * Owns:
+ *   - postSummary()       — write a `type=summary` message to the group jsonl
+ *                           and run the extractor (B + C)
+ *   - extractTaskMemory() — turn a summary body into 2-5 task-memory entries
+ *                           via 334f task-memory shard lib (C)
+ *   - buildSummaryReminder() — compute the §Δ31.4 3-AND soft reminder shape
+ *                              consumed by 334e's `taskCtx.summaryReminder` (D)
+ *   - buildTaskCtxMemories() — assemble task-memory top-5 (pinned + recent +
+ *                              tag relevance) for task_ctx (E)
+ *
+ * Hard boundaries:
+ *   - does NOT touch 334o jsonl rotation internals (calls group.appendMessage)
+ *   - does NOT touch 334f shard-store impl (calls openMemoryShardStore API)
+ *   - does NOT touch 334e prompts main frame (returns plain shapes that feed
+ *     the existing renderTaskCtx contract)
+ *   - does NOT self-loop-write VP-memory (extractor writes task-memory only;
+ *     VP-level synthesis is deferred to 334g dream)
+ *   - softCap overflow does NOT create new shards (334f already routes into
+ *     dream queue via projectDeriveHint; we just surface `needsRecompression`)
+ */
+
+import { join } from 'path';
+import { openMemoryShardStore } from '../memory/shard-store.js';
+import { AUTHORED_BY } from '../memory/schema.js';
+
+// ─── §Δ31.4 soft-reminder thresholds ─────────────────────────────
+/** Must be initiator AND members>1 AND (age≥20min OR turns≥10). */
+export const SUMMARY_REMINDER_MIN_MEMBERS  = 2;
+export const SUMMARY_REMINDER_MIN_TURNS    = 10;
+export const SUMMARY_REMINDER_MIN_AGE_MS   = 20 * 60 * 1000;
+
+// ─── extractor limits ────────────────────────────────────────────
+export const EXTRACT_MIN_ENTRIES = 2;
+export const EXTRACT_MAX_ENTRIES = 5;
+
+/** Whitelist of R6 kinds emitted by the summary-extractor. */
+const EXTRACT_KINDS = Object.freeze(['progress', 'decision']);
+
+/** Shard routing for each extracted kind (§Δ25.2 task-memory fixed set). */
+const KIND_TO_SHARD = Object.freeze({
+  progress: 'progress',
+  decision: 'decision',
+});
+
+// ─── (B) postSummary ─────────────────────────────────────────────
+
+/**
+ * Write a `type=summary` message to the group log, then auto-run the
+ * extractor to derive task-memory entries.
+ *
+ * @param {{
+ *   group: import('../groups/group-store.js').GroupHandle,
+ *   taskId: string,
+ *   fromVpId: string,
+ *   body: string,
+ *   progress?: number,            // 0..100
+ *   supersedes?: string[],        // prior summary msgIds being superseded
+ *   memoryDir: string,            // groups/<g>/tasks/<t>/memory/
+ *   now?: () => number,           // test clock
+ *   extractor?: (body:string) => Array<{kind:string,body:string,tags?:string[]}>
+ *     // optional hook; default uses `defaultExtractor` (heuristic, no LLM)
+ * }} opts
+ * @returns {{ message: any, memoryIds: string[], supersededSummaryIds: string[] }}
+ */
+export function postSummary(opts) {
+  const {
+    group,
+    taskId,
+    fromVpId,
+    body,
+    progress,
+    supersedes,
+    memoryDir,
+    now = () => Date.now(),
+    extractor = defaultExtractor,
+  } = opts || {};
+
+  if (!group || typeof group.appendMessage !== 'function') {
+    throw new Error('postSummary: group handle required');
+  }
+  if (!taskId)   throw new Error('postSummary: taskId required');
+  if (!fromVpId) throw new Error('postSummary: fromVpId required');
+  if (typeof body !== 'string' || !body.trim()) {
+    throw new Error('postSummary: body required (non-empty string)');
+  }
+  if (progress != null) {
+    const p = Number(progress);
+    if (!Number.isFinite(p) || p < 0 || p > 100) {
+      throw new Error('postSummary: progress must be number in [0,100]');
+    }
+  }
+  const supersedesArr = Array.isArray(supersedes)
+    ? supersedes.filter((s) => typeof s === 'string' && s)
+    : [];
+
+  // 1) Append the summary message to the group jsonl log (type=summary).
+  const stored = group.appendMessage({
+    from: fromVpId,
+    role: 'assistant',
+    text: body,
+    taskId,
+    meta: {
+      type: 'summary',
+      progress: progress == null ? null : Number(progress),
+      supersedes: supersedesArr,
+    },
+  });
+
+  // 2) Run the extractor → write task-memory entries (C).
+  const memoryIds = [];
+  try {
+    const store = openMemoryShardStore(memoryDir, 'task');
+    const raw = extractor(body) || [];
+    const bounded = clampExtracted(raw);
+    for (const [i, item] of bounded.entries()) {
+      const kind = EXTRACT_KINDS.includes(item.kind) ? item.kind : 'progress';
+      const shard = KIND_TO_SHARD[kind] || 'progress';
+      const id = `mem-${stored.id}-${i + 1}`;
+      store.put({
+        id,
+        shard,
+        kind,
+        taskId,
+        body: typeof item.body === 'string' ? item.body.trim() : '',
+        tags: Array.isArray(item.tags) ? item.tags.slice(0, 5) : [],
+        authoredBy: AUTHORED_BY.SUMMARY,
+        sourceRef: { taskId, msgIds: [stored.id] },
+        createdAt: new Date(now()).toISOString(),
+      });
+      memoryIds.push(id);
+    }
+  } catch (err) {
+    // Extractor failures must not fail the summary post; the message is
+    // already persisted (audit property). We return the empty memoryIds so
+    // callers can surface a warning if they want.
+    // eslint-disable-next-line no-console
+    console.warn('[task-334n] summary-extractor failed:', err?.message || err);
+  }
+
+  return {
+    message: stored,
+    memoryIds,
+    supersededSummaryIds: supersedesArr,
+  };
+}
+
+/** Clamp raw extractor output to [EXTRACT_MIN_ENTRIES..EXTRACT_MAX_ENTRIES]. */
+function clampExtracted(arr) {
+  const cleaned = arr.filter((x) => x && typeof x.body === 'string' && x.body.trim());
+  if (cleaned.length === 0) return [];
+  return cleaned.slice(0, EXTRACT_MAX_ENTRIES);
+}
+
+// ─── (C) default extractor ───────────────────────────────────────
+
+/**
+ * Heuristic extractor — no LLM, deterministic, safe for tests.
+ *
+ * Strategy:
+ *   - Split body into non-empty lines (trim bullets).
+ *   - Lines starting with keywords "decide/decision/chose/chosen" → kind=decision.
+ *   - Lines starting with "progress/ship/shipped/done/completed/blocker/todo"
+ *     → kind=progress.
+ *   - Everything else → kind=progress (default).
+ *   - Emit up to EXTRACT_MAX_ENTRIES.
+ */
+export function defaultExtractor(body) {
+  if (typeof body !== 'string') return [];
+  const lines = body
+    .split(/\r?\n/)
+    .map((l) => l.replace(/^[\s*\-•]+/, '').trim())
+    .filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+    let kind = 'progress';
+    if (/^(decide|decision|chose|chosen|pick|choose)\b/.test(lower)) {
+      kind = 'decision';
+    }
+    out.push({ kind, body: line });
+    if (out.length >= EXTRACT_MAX_ENTRIES) break;
+  }
+  // If we ended up with fewer than MIN and there was a body, collapse to
+  // one "progress" entry carrying the trimmed full body so we never emit 0
+  // when the caller gave us real content and asked for 2-5.
+  if (out.length < EXTRACT_MIN_ENTRIES && lines.length === 0 && body.trim()) {
+    out.push({ kind: 'progress', body: body.trim() });
+  }
+  return out;
+}
+
+// ─── (D) soft reminder builder ───────────────────────────────────
+
+/**
+ * Build the `taskCtx.summaryReminder` shape consumed by 334e's prompt.
+ * Returns null when the 3-AND conditions do not all hold. The prompt layer
+ * adds a 4th check (currentVpId === initiatorVpId) so we gate here too so
+ * callers can debug-log why it was suppressed.
+ *
+ * §Δ31.4 conditions:
+ *   (1) task.members.length > 1
+ *   (2) caller role === 'initiator'  (i.e. currentVpId === task.initiator)
+ *   (3) (now - lastSummaryAt) ≥ 20 min  OR  nonSummaryTurns ≥ 10
+ *
+ * @param {{
+ *   task: { initiator?: string, members?: string[] },
+ *   currentVpId: string,
+ *   lastSummaryAt: number,     // epoch ms, 0 = never
+ *   nonSummaryTurns: number,
+ *   now?: number,
+ * }} input
+ * @returns {{ triggered: boolean, nonSummaryCount: number, lastSummaryAt: number,
+ *             now: number, reasons: string[] }}
+ */
+export function buildSummaryReminder(input) {
+  const { task, currentVpId, lastSummaryAt = 0, nonSummaryTurns = 0 } = input || {};
+  const now = typeof input?.now === 'number' ? input.now : Date.now();
+  const reasons = [];
+
+  if (!task || typeof task !== 'object') {
+    return { triggered: false, reasons: ['no-task'], nonSummaryCount: nonSummaryTurns, lastSummaryAt, now };
+  }
+  const members = Array.isArray(task.members) ? task.members : [];
+  const isInitiator = !!currentVpId && task.initiator === currentVpId;
+
+  if (!isInitiator) reasons.push('not-initiator');
+  if (members.length <= SUMMARY_REMINDER_MIN_MEMBERS - 1) reasons.push('solo-task');
+
+  const ageMs = lastSummaryAt > 0 ? now - lastSummaryAt : Number.POSITIVE_INFINITY;
+  const ageOk = ageMs >= SUMMARY_REMINDER_MIN_AGE_MS;
+  const turnsOk = nonSummaryTurns >= SUMMARY_REMINDER_MIN_TURNS;
+  if (!ageOk && !turnsOk) reasons.push('too-soon');
+
+  const triggered = isInitiator && members.length >= SUMMARY_REMINDER_MIN_MEMBERS && (ageOk || turnsOk);
+  return {
+    triggered,
+    reasons,
+    nonSummaryCount: nonSummaryTurns,
+    lastSummaryAt,
+    now,
+  };
+}
+
+// ─── (E) task_ctx top-5 task-memory builder ──────────────────────
+
+/**
+ * Assemble task-memory top-5 for 334e's `taskCtx.memories` field.
+ * Ordering (§Δ16.5): pinned first → recent → tag-relevant. Supersedes are
+ * hidden (entries with supersededBy != null are filtered out).
+ *
+ * @param {string} memoryDir  groups/<g>/tasks/<t>/memory/
+ * @param {{ tags?: string[], top?: number }} [opts]
+ *   tags : optional tag hints to boost relevance
+ *   top  : default 5
+ * @returns {Array<{body:string, shard:string}>}
+ */
+export function buildTaskCtxMemories(memoryDir, opts = {}) {
+  const top = Number.isFinite(opts.top) ? Number(opts.top) : 5;
+  const tagHints = Array.isArray(opts.tags) ? opts.tags : [];
+  let results = [];
+  try {
+    const store = openMemoryShardStore(memoryDir, 'task');
+    const q = store.query({});
+    // query() returns thin entries (id/shard/kind/tags/pinned/groupId/taskId/supersededBy);
+    // we need the body too.
+    const hits = (q.results || [])
+      .filter((r) => !r.supersededBy)
+      .map((r) => {
+        const full = store.get(r.id);
+        return {
+          id: r.id,
+          shard: r.shard || 'general',
+          body: full?.body || '',
+          tags: Array.isArray(r.tags) ? r.tags : [],
+          pinned: !!r.pinned,
+          createdAt: full?.createdAt || null,
+        };
+      })
+      .filter((r) => r.body && r.body.trim());
+
+    const score = (r) => {
+      let s = 0;
+      if (r.pinned) s += 1000;
+      // recency proxy (ISO string compare works lexicographically)
+      if (r.createdAt) s += 10;
+      // tag relevance
+      for (const t of tagHints) if (r.tags.includes(t)) s += 5;
+      return s;
+    };
+    hits.sort((a, b) => {
+      const ds = score(b) - score(a);
+      if (ds !== 0) return ds;
+      // stable recency tie-break
+      return String(b.createdAt || '').localeCompare(String(a.createdAt || ''));
+    });
+    results = hits.slice(0, top).map((r) => ({ body: r.body, shard: r.shard }));
+  } catch {
+    results = [];
+  }
+  return results;
+}
+
+// ─── (F) related-task ACL fail-closed gate ───────────────────────
+
+/**
+ * Return memory/summary hints for a related task only when ACL grants.
+ * Caller passes the TaskStore so we can ask `canAccessRelated()`.
+ *
+ * @param {{
+ *   taskStore: import('./store.js').TaskStore,
+ *   currentTaskId: string,
+ *   otherTaskId: string,
+ *   vpId: string,
+ *   groupsRoot: string,
+ *   top?: number,
+ * }} input
+ * @returns {null | { id:string, title:string, members:string[], updatedAt?:number, memories:Array<{body:string,shard:string}> }}
+ *   null iff ACL denies — NEVER leak taskId in that case.
+ */
+export function getRelatedTaskCtx(input) {
+  const { taskStore, currentTaskId, otherTaskId, vpId, groupsRoot, top = 2 } = input || {};
+  if (!taskStore || !currentTaskId || !otherTaskId || !vpId || !groupsRoot) return null;
+  if (!taskStore.canAccessRelated(currentTaskId, otherTaskId, vpId)) return null;
+  const other = taskStore.get(otherTaskId);
+  if (!other || !other.groupId) return null;
+  const memoryDir = join(groupsRoot, other.groupId, 'tasks', other.id, 'memory');
+  const mems = buildTaskCtxMemories(memoryDir, { top });
+  return {
+    id: other.id,
+    title: other.title || other.id,
+    members: Array.isArray(other.members) ? other.members.slice() : [],
+    updatedAt: other.updatedAt || 0,
+    memories: mems,
+  };
+}

package/unify/tools/task-tools.js

@@ -515,3 +515,88 @@ approach, steps, and status of the current work.`,
     }
   },
 });
+
+// ─── TaskSummaryPost (task-334n) ────────────────────────
+
+import { postSummary } from '../tasks/summary.js';
+import { openGroup } from '../groups/group-store.js';
+import { join } from 'path';
+
+/**
+ * task-334n §B — initiator posts a progress summary to the group log.
+ * Triggers the summary-extractor automatically (§C).
+ */
+export const taskSummaryPost = defineTool({
+  name: 'task_summary_post',
+  description: `Post a progress summary for a multi-VP task (task-334n).
+
+Only the task initiator should call this. The summary is written to the
+group message log as \`type=summary\` and auto-extracts 2-5 task-memory
+entries (kind=progress|decision) via the task-memory shard lib.
+
+To revise a prior summary, pass its msgId in \`supersedes\` — the old
+summary is marked \`supersededBy\` while staying on disk for audit.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      taskId:   { type: 'string', description: 'Target task id' },
+      body:     { type: 'string', description: 'Summary body (markdown)' },
+      progress: { type: 'number', description: '0..100, optional' },
+      supersedes: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Prior summary msgIds this revision supersedes',
+      },
+    },
+    required: ['taskId', 'body'],
+  },
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  async execute(input, ctx) {
+    const err = requireStore();
+    if (err) return err;
+    const { taskId, body, progress, supersedes } = input || {};
+    if (!taskId || !body) {
+      return JSON.stringify({ error: 'taskId and body are required' });
+    }
+    const task = taskStore.get(taskId);
+    if (!task) return JSON.stringify({ error: `task not found: ${taskId}` });
+    if (!task.groupId) {
+      return JSON.stringify({ error: 'task has no groupId; summary requires a group' });
+    }
+
+    const currentVpId = ctx?.currentVpId;
+    if (currentVpId && task.initiator && currentVpId !== task.initiator) {
+      return JSON.stringify({ error: 'only the task initiator may post summaries' });
+    }
+
+    const yeaftDir = ctx?.yeaftDir;
+    if (!yeaftDir) {
+      return JSON.stringify({ error: 'yeaftDir missing from tool context' });
+    }
+    const groupsRoot = join(yeaftDir, 'groups');
+    const memoryDir = join(groupsRoot, task.groupId, 'tasks', task.id, 'memory');
+
+    const group = openGroup(groupsRoot, task.groupId);
+    try {
+      const res = postSummary({
+        group,
+        taskId,
+        fromVpId: currentVpId || task.initiator || 'unknown',
+        body,
+        progress,
+        supersedes,
+        memoryDir,
+      });
+      return JSON.stringify({
+        success: true,
+        messageId: res.message.id,
+        memoryIds: res.memoryIds,
+        supersededSummaryIds: res.supersededSummaryIds,
+      });
+    } finally {
+      group.close();
+    }
+  },
+});
+