@yeaft/webchat-agent 0.1.532 → 0.1.533

package/package.json

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

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();
+    }
+  },
+});
+