@yeaft/webchat-agent 0.1.954 → 0.1.956

package/package.json

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

package/yeaft/engine.js

@@ -1339,7 +1339,7 @@ export class Engine {
    *   string-prompt shape (no regression for existing callers).
    * @yields {EngineEvent}
    */
-  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, vpPlan, sessionAnnouncement, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, threadId = MAIN_THREAD_ID, drainPendingUserMessages = null, collabToolPolicy = null } = {}) {
+  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, vpPlan, sessionAnnouncement, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, threadId = MAIN_THREAD_ID, drainPendingUserMessages = null, collabToolPolicy = null } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -1402,7 +1402,7 @@ export class Engine {
 
     try {
       this.#currentThreadId = threadId || MAIN_THREAD_ID;
-      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, vpPlan, sessionAnnouncement, workDir, userAlreadyPersisted, getCurrentTodos, setCurrentTodos, threadId: this.#currentThreadId, drainPendingUserMessages, collabToolPolicy: effectiveCollabToolPolicy });
+      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, vpPlan, sessionAnnouncement, workDir, userAlreadyPersisted, getCurrentTodos, setCurrentTodos, threadId: this.#currentThreadId, drainPendingUserMessages, collabToolPolicy: effectiveCollabToolPolicy });
     } finally {
       if (signal) {
         try { signal.removeEventListener('abort', onExternalAbort); } catch { /* ignore */ }
@@ -1422,7 +1422,7 @@ export class Engine {
    * in a try/finally without indenting the whole loop.
    * @private
    */
-  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, vpPlan, sessionAnnouncement, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, threadId = MAIN_THREAD_ID, drainPendingUserMessages = null, collabToolPolicy = null }) {
+  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, vpPlan, sessionAnnouncement, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, threadId = MAIN_THREAD_ID, drainPendingUserMessages = null, collabToolPolicy = null }) {
 
     const effectiveCollabToolPolicy = collabToolPolicy === COLLAB_TOOL_POLICY.SINGLE_VP || collabToolPolicy === COLLAB_TOOL_POLICY.MULTI_VP
       ? collabToolPolicy
@@ -1511,12 +1511,13 @@ export class Engine {
       : [];
 
     // ─── Active Scope (DESIGN-PROMPT §3 ④) ──────────────────────
-    // Structured per-turn scope summary: group + vp + envelope routing
+    // Structured per-turn scope summary: session + vp + members + envelope routing
     // info. Long-form scope content lives in AMS — this block carries
     // only IDs + tiny labels. (Feature scope retired 2026-05-13.)
     const activeScope = {
       sessionId: sessionId || '',
       vpId: ownVpIdForAms || '',
+      members: Array.isArray(sessionMembers) ? sessionMembers : [],
       envelope: inboundEnvelope || null,
     };
 

package/yeaft/prompts.js

@@ -9,12 +9,12 @@
  *
  * Concept layering (DESIGN-PROMPT §3):
  *   ① Identity      — VP persona body (or Yeaft fallback)
- *   ② Rules         — group announcement, date, mode template, tools,
+ *   ② Rules         — session announcement, date, mode template, tools,
  *                     tool-guidance, skills, common rules
  *   ③ Memory        — single block produced upstream by the AMS render
  *                     outlet and threaded through here as `memoryInjection`
  *   ④ Active Scope  — structured per-turn scope summary
- *                     (group / vp / envelope IDs)
+ *                     (session / vp / members / envelope IDs)
  *
  * The compact summary, user_profile, and core_memory blocks that used to
  * live inside the system prompt are GONE. Compact summary is now part of
@@ -256,11 +256,11 @@ export function normalizePromptLanguage(language) {
  *
  * Prompt structure (DESIGN-PROMPT §3):
  *   ① Identity      — Core identity (persona or Yeaft fallback)
- *   ② Rules         — Group announcement, date, mode, tools, guidance, skills
+ *   ② Rules         — Session announcement, date, mode, tools, guidance, skills
  *   ③ Memory        — Single block produced by the AMS render outlet
  *                     (callers pass it as `memoryInjection`).
  *   ④ Active Scope  — Structured per-turn scope summary
- *                     (group / vp / envelope IDs).
+ *                     (session / vp / members / envelope IDs).
  *   (The previous standalone user_profile / core_memory blocks are
  *    gone — those signals now arrive through AMS Resident. Task
  *    context (`taskCtx`) was wired into Active Scope by task-334e
@@ -270,6 +270,7 @@ export function normalizePromptLanguage(language) {
  *   @param {object} [activeScope] — structured scope summary for this turn
  *   @param {string} [activeScope.sessionId]
  *   @param {string} [activeScope.vpId]
+ *   @param {string[]} [activeScope.members]          current session roster
  *   @param {object} [activeScope.envelope]          inbound routing info (sender, intent)
  *
  * @param {{
@@ -337,8 +338,8 @@ export function buildSystemPrompt({
     parts.push(`${docHeader}\n${introLine}${docText}`);
   }
 
-  // ─── 1.5  Group Announcement (CLAUDE.md-style shared prefix) ───
-  // When a group has set an announcement, every VP in the group sees it
+  // ─── 1.5  Session Announcement (CLAUDE.md-style shared prefix) ───
+  // When a session has set an announcement, every VP in the session sees it
   // near the top of the system prompt — before tools, memory, mode-specific
   // instructions. Empty/whitespace = no block emitted.
   const annText = (typeof sessionAnnouncement === 'string') ? sessionAnnouncement.trim() : '';
@@ -482,9 +483,10 @@ function hasCjk(text) {
  *
  * Schema:
  *   ## active_scope
- *   group:   <sessionId>               (omitted when missing)
- *   vp:      <vpId>                  (omitted when missing)
- *   envelope: from=<sender> intent=<intent>   (omitted when no envelope)
+ *   session: <sessionId>                    (omitted when missing)
+ *   vp:      <vpId>                         (omitted when missing)
+ *   members: <vpId>, <vpId>                 (omitted when missing)
+ *   envelope: from=<sender> intent=<intent> (omitted when no envelope)
  *
  * Returns '' when the input has no useful field — we don't emit an empty
  * header. (`featureId`/`featureTitle` fields were removed 2026-05-13 along
@@ -493,6 +495,7 @@ function hasCjk(text) {
  * @param {object} [activeScope]
  * @param {string} [activeScope.sessionId]
  * @param {string} [activeScope.vpId]
+ * @param {string[]} [activeScope.members]  current session roster
  * @param {object} [activeScope.envelope]   inbound routing summary
  * @param {object} lang
  * @returns {string}
@@ -501,16 +504,19 @@ function renderActiveScope(activeScope, lang) {
   if (!activeScope || typeof activeScope !== 'object') return '';
 
   const lines = [];
-  const group = typeof activeScope.sessionId === 'string' && activeScope.sessionId.trim()
+  const session = typeof activeScope.sessionId === 'string' && activeScope.sessionId.trim()
     ? activeScope.sessionId.trim()
     : '';
-  if (group) lines.push(`group: ${group}`);
+  if (session) lines.push(`session: ${session}`);
 
   const vp = typeof activeScope.vpId === 'string' && activeScope.vpId.trim()
     ? activeScope.vpId.trim()
     : '';
   if (vp) lines.push(`vp: ${vp}`);
 
+  const membersLine = renderSessionMembersLine(activeScope.members);
+  if (membersLine) lines.push(`members: ${membersLine}`);
+
   const envLine = renderEnvelopeLine(activeScope.envelope);
   if (envLine) lines.push(`envelope: ${envLine}`);
 
@@ -519,6 +525,21 @@ function renderActiveScope(activeScope, lang) {
   return `${lang.activeScopeHeader}\n${lines.join('\n')}`;
 }
 
+
+function renderSessionMembersLine(members) {
+  if (!Array.isArray(members)) return '';
+  const clean = [];
+  const seen = new Set();
+  for (const member of members) {
+    if (typeof member !== 'string') continue;
+    const id = member.trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    clean.push(id);
+  }
+  return clean.join(', ');
+}
+
 /**
  * Render a one-line envelope summary. Pulls the small set of routing
  * fields we surface to the LLM (sender, intent, originating user) and

package/yeaft/routing/router.js

@@ -56,6 +56,7 @@ export function createRouter(deps = {}) {
    *   taskId?: string|null,
    *   inboundEnvelope?: any,   // the envelope the sender is currently handling
    *                             // (drives causedBy chain & loop guard)
+   *   sourceThreadId?: string|null, // sender-side thread that should own the visible forward row
    * }} args
    * @param {{ taskMembers?: string[] }} [opts]  — forwarded to coordinator.ingest
    * @returns {{
@@ -148,6 +149,9 @@ export function createRouter(deps = {}) {
           senderVpId: from,
           reason: args.reason || null,
           causedBy: chain,
+          sourceThreadId: typeof args.sourceThreadId === 'string' && args.sourceThreadId.trim()
+            ? args.sourceThreadId.trim()
+            : null,
         },
       },
       opts,

package/yeaft/sessions/session-config.js

@@ -1,7 +1,7 @@
 /**
- * group-config.js — Per-group selected model state.
+ * session-config.js — Per-session selected model override state.
  *
- * Each group may carry its header-selected model in `config.json` at
+ * Each session may carry its header-selected model override in `config.json` at
  *   ~/.yeaft/sessions/<sessionId>/config.json
  *
  * v1 schema (intentionally tiny — extend via additive keys only):
@@ -9,7 +9,7 @@
  *     "model": "my-proxy/claude-sonnet-4-20250514"   // optional
  *   }
  *
- * Missing file → empty object. Missing field → fall back to user-level
+ * Missing file or `{}` → no session-level override. Missing field → fall back to user-level
  * config (`~/.yeaft/config.json` via loadConfig()). Resolution is a
  * shallow overlay for send-time effective config.
  *
@@ -25,7 +25,7 @@ import { sessionsRoot, resolveSessionYeaftDir } from './session-crud.js';
 
 const CONFIG_FILE = 'config.json';
 
-/** Whitelist of persisted group model-state fields. Reject everything else. */
+/** Whitelist of persisted session model-override fields. Reject everything else. */
 const ALLOWED_KEYS = new Set(['model']);
 
 export class SessionConfigError extends Error {
@@ -37,18 +37,18 @@ export class SessionConfigError extends Error {
 }
 
 /**
- * Resolve the on-disk path for a group's config.json. Honours the
- * per-group workDir registry so groups bound to a project directory
- * keep their config alongside the group meta.
+ * Resolve the on-disk path for a session's config.json. Honours the
+ * per-session workDir registry so sessions bound to a project directory
+ * keep their config alongside the session metadata.
  */
 export function sessionConfigPath(yeaftDir, sessionId) {
   if (!yeaftDir) return null;
-  const groupYeaftDir = resolveSessionYeaftDir(yeaftDir, sessionId);
-  return join(sessionsRoot(groupYeaftDir), sessionId, CONFIG_FILE);
+  const sessionYeaftDir = resolveSessionYeaftDir(yeaftDir, sessionId);
+  return join(sessionsRoot(sessionYeaftDir), sessionId, CONFIG_FILE);
 }
 
 /**
- * Read a group's config.json. Returns `{}` when the file is missing or
+ * Read a session's config.json. Returns `{}` when the file is missing or
  * corrupt — callers fall back to user-level defaults via
  * `resolveSessionConfig`. We never auto-write on read.
  *

package/yeaft/sessions/session-crud.js

@@ -12,7 +12,7 @@
  * Plus the D1 bootstrap helper:
  *   ensureDefaultSessionIfEmpty(yeaftDir, {libDir}) — if NO session exists on
  *   disk, seed `session_default` with roster = every VP in the library, and
- *   defaultVpId = alphabetically first vpId. No-op when ≥1 group present.
+ *   defaultVpId = alphabetically first vpId. No-op when ≥1 session present.
  *
  * Hard constraints (PM):
  *   (a) We don't touch 334o storage primitives (storage/index.js) — we call
@@ -202,13 +202,15 @@ export function scanWorkdirSessions(workDir) {
  * Register `(sessionId, workDir)` in the central registry so the next
  * `snapshotSessions()` includes this session.
  *
- * Validates that `<workDir>/.yeaft/sessions/<sessionId>/group.json` exists
- * and is parseable. Throws:
+ * Validates that `<workDir>/.yeaft/sessions/<sessionId>/session.json`
+ * exists and is parseable, with legacy `group.json` as a read fallback.
+ * Throws:
  *  - `not_found`   — the session dir is not on disk at this workdir
- *  - `corrupt_meta` — the dir exists but `group.json` is missing / unreadable
- *                    / can't be parsed. Surfaced as a distinct code so the
- *                    UI can tell the user "the file is broken" instead of
- *                    "you picked the wrong workdir" (review finding I1).
+ *  - `corrupt_meta` — the dir exists but session metadata is missing /
+ *                    unreadable / can't be parsed. Surfaced as a distinct
+ *                    code so the UI can tell the user "the file is broken"
+ *                    instead of "you picked the wrong workdir" (review
+ *                    finding I1).
  *
  * Idempotent: if the same `(sessionId, workDir)` is already registered,
  * we still rewrite the entry (with the normalized path) and return the
@@ -227,7 +229,7 @@ export function restoreSessionToRegistry(defaultYeaftDir, sessionId, workDir) {
   const dir = join(sessionsRoot(groupYeaftDir), sessionId);
   if (!existsSync(dir)) throw new SessionCrudError('not_found', sessionId);
   const meta = loadSessionMeta(dir);
-  if (!meta) throw new SessionCrudError('corrupt_meta', sessionId, `group.json missing or unreadable at ${dir}`);
+  if (!meta) throw new SessionCrudError('corrupt_meta', sessionId, `session metadata missing or unreadable at ${dir} (expected session.json or legacy group.json)`);
   registerSessionWorkDir(defaultYeaftDir, sessionId, normalized);
   return { ...meta, workDir: normalized };
 }
@@ -344,11 +346,12 @@ export function createSessionFromSpec(yeaftDir, spec, options = {}) {
   handle.close();
   if (normalizedWorkDir) registerSessionWorkDir(yeaftDir, id, normalizedWorkDir);
 
-  // Per-group config (v1: model only). We always create an empty
-  // config.json so the file's presence signals "owned by this group" and
-  // hand-editing tools can find a stub. Initial overrides from the
-  // wizard spec (currently just `config.model`) are persisted here so
-  // the engine cache picks them up on the very first turn.
+  // Per-session config (v1: model only). We always create an empty
+  // config.json so hand-editing tools can find a session-level override
+  // stub. An empty object means "no session override; use global config".
+  // Initial overrides from the wizard spec (currently just `config.model`)
+  // are persisted here so the engine cache picks them up on the very first
+  // turn.
   try {
     ensureSessionConfigFile(yeaftDir, id);
     if (spec && spec.config && typeof spec.config === 'object') {

package/yeaft/sessions/session-store.js

@@ -1,17 +1,19 @@
 /**
- * group-store.js — Per-group persistent store for task-334b.
+ * session-store.js — Per-session persistent store for task-334b.
  *
  * Layout (see architecture §2):
- *   ~/.yeaft/sessions/<group-id>/
- *     group.json          # { id, name, roster: [vpId...], defaultVpId, createdAt }
+ *   ~/.yeaft/sessions/<session-id>/
+ *     session.json        # { id, name, roster: [vpId...], defaultVpId, createdAt }
  *     messages/           # JSONL size-rotation log (334o openLog)
  *       000001.jsonl
  *       index.json
  *     tasks/              # populated by 334n — reserved here
  *     vps/                # populated by 334c RoleInstance runtime — reserved here
  *
- * This module owns only the group.json + messages/ log. Roster mutation
- * logic lives in roster.js so coordinator and group-store both compose it.
+ * This module owns only the session.json + messages/ log. Roster mutation
+ * logic lives in roster.js so coordinator and session-store both compose it.
+ * Legacy `group.json` is read as a compatibility alias for sessions created
+ * before the storage terminology was fixed; new writes are always session.json.
  *
  * Hard constraint: the store does not parse @-mentions, does not dispatch,
  * and has no knowledge of VP/RoleInstance. It is pure persistence over 334o.
@@ -28,15 +30,16 @@ import { join } from 'path';
 import { writeAtomic, openLog } from '../storage/index.js';
 import { nextMsgId, isReservedVpId, ReservedVpIdError, validateVpId, InvalidVpIdError } from './ids.js';
 
-const GROUP_FILE = 'group.json';
+export const SESSION_META_FILE = 'session.json';
+export const LEGACY_GROUP_META_FILE = 'group.json';
 const MESSAGES_DIR = 'messages';
 
 /**
- * Load (or create) the directory for a single group.
+ * Load (or create) the directory for a single session.
  *
- * @param {string} sessionsRoot  e.g. `${yeaftDir}/groups`
+ * @param {string} sessionsRoot  e.g. `${yeaftDir}/sessions`
  * @param {string} sessionId
- * @returns {GroupHandle}
+ * @returns {SessionHandle}
  */
 export function openSession(sessionsRoot, sessionId) {
   if (!sessionId || typeof sessionId !== 'string') {
@@ -47,7 +50,7 @@ export function openSession(sessionsRoot, sessionId) {
 
   let meta = loadSessionMeta(dir);
   if (!meta) {
-    // Fresh group — caller must call initGroup() next; we return a handle
+    // Fresh session — caller must call createSession() next; we return a handle
     // with meta=null so createSession() can write the initial file.
   }
 
@@ -60,14 +63,14 @@ export function openSession(sessionsRoot, sessionId) {
     id: sessionId,
     /** Return current meta (reads fresh from memory after last save). */
     getMeta() { return meta ? structuredClone(meta) : null; },
-    /** Overwrite group.json atomically. */
+    /** Overwrite session.json atomically. */
     saveMeta(next) {
       validateMeta(next);
       meta = next;
-      writeAtomic(join(dir, GROUP_FILE), JSON.stringify(meta, null, 2));
+      writeAtomic(join(dir, SESSION_META_FILE), JSON.stringify(meta, null, 2));
     },
     /**
-     * Append a message to the group log. Assigns an id if absent.
+     * Append a message to the session log. Assigns an id if absent.
      * Returns the stored record (with id + ts).
      *
      * Structural invariant: NO field on `record` may start with `_`.
@@ -113,14 +116,14 @@ export function openSession(sessionsRoot, sessionId) {
 }
 
 /**
- * Create a fresh group on disk. Fails if group.json already exists.
- * @returns {GroupHandle}
+ * Create a fresh session on disk. Fails if session metadata already exists.
+ * @returns {SessionHandle}
  */
 export function createSession(sessionsRoot, spec) {
   if (!spec || !spec.id) throw new Error('createSession: spec.id required');
   const h = openSession(sessionsRoot, spec.id);
   if (h.getMeta()) {
-    throw new Error(`group ${spec.id} already exists`);
+    throw new Error(`session ${spec.id} already exists`);
   }
   const roster = Array.isArray(spec.roster) ? spec.roster.slice() : [];
   for (const v of roster) {
@@ -146,15 +149,19 @@ export function createSession(sessionsRoot, spec) {
   return h;
 }
 
-/** Non-destructive load — returns null if group.json is missing/corrupt. */
+/**
+ * Non-destructive load — returns null if session metadata is missing/corrupt.
+ * Reads canonical session.json first, then legacy group.json for disk
+ * compatibility. Callers that later save the handle will write session.json.
+ */
 export function loadSessionMeta(dir) {
-  const path = join(dir, GROUP_FILE);
-  if (!existsSync(path)) return null;
+  const path = resolveSessionMetaPath(dir);
+  if (!path) return null;
   try {
     const raw = readFileSync(path, 'utf8');
     const parsed = JSON.parse(raw);
     validateMeta(parsed);
-    // Legacy groups created before optional fields were added are
+    // Legacy sessions created before optional fields were added are
     // forward-compat: missing fields read back as safe empty strings.
     if (typeof parsed.announcement !== 'string') parsed.announcement = '';
     if (typeof parsed.workDir !== 'string') parsed.workDir = '';
@@ -164,7 +171,7 @@ export function loadSessionMeta(dir) {
   }
 }
 
-/** List every group directory under `sessionsRoot`. */
+/** List every session directory under `sessionsRoot`. */
 export function listSessions(sessionsRoot) {
   if (!existsSync(sessionsRoot)) return [];
   const out = [];
@@ -182,25 +189,25 @@ export function listSessions(sessionsRoot) {
 }
 
 function validateMeta(meta) {
-  if (!meta || typeof meta !== 'object') throw new Error('group.json must be object');
-  if (!meta.id || typeof meta.id !== 'string') throw new Error('group.id required');
-  if (!Array.isArray(meta.roster)) throw new Error('group.roster must be array');
+  if (!meta || typeof meta !== 'object') throw new Error('session.json must be object');
+  if (!meta.id || typeof meta.id !== 'string') throw new Error('session.id required');
+  if (!Array.isArray(meta.roster)) throw new Error('session.roster must be array');
   for (const v of meta.roster) {
-    if (typeof v !== 'string') throw new Error('group.roster must be string[]');
+    if (typeof v !== 'string') throw new Error('session.roster must be string[]');
   }
   if (meta.defaultVpId != null && typeof meta.defaultVpId !== 'string') {
-    throw new Error('group.defaultVpId must be string|null');
+    throw new Error('session.defaultVpId must be string|null');
   }
   if (meta.announcement != null && typeof meta.announcement !== 'string') {
-    throw new Error('group.announcement must be string');
+    throw new Error('session.announcement must be string');
   }
   if (meta.workDir != null && typeof meta.workDir !== 'string') {
-    throw new Error('group.workDir must be string');
+    throw new Error('session.workDir must be string');
   }
 }
 
 /**
- * @typedef {Object} GroupHandle
+ * @typedef {Object} SessionHandle
  * @property {string} dir
  * @property {string} id
  * @property {() => any} getMeta
@@ -210,3 +217,11 @@ function validateMeta(meta) {
  * @property {(first:string,last:string)=>Generator<any>} readMessageRange
  * @property {() => void} close
  */
+
+function resolveSessionMetaPath(dir) {
+  const canonical = join(dir, SESSION_META_FILE);
+  if (existsSync(canonical)) return canonical;
+  const legacy = join(dir, LEGACY_GROUP_META_FILE);
+  if (existsSync(legacy)) return legacy;
+  return null;
+}

package/yeaft/tools/route-forward.js

@@ -95,6 +95,7 @@ Returns JSON: { ok, dispatched?, error?, detail? }.`,
         reason: reason || null,
         taskId: ctx.taskId ?? null,
         inboundEnvelope: ctx.inboundEnvelope ?? null,
+        sourceThreadId: ctx.threadId ?? null,
       },
       { taskMembers: ctx.taskMembers },
     );

package/yeaft/web-bridge.js

@@ -356,6 +356,18 @@ function buildVpPromptPayload(vpId, envelope) {
   return { text, prompt, promptParts };
 }
 
+export function visibleInboundThreadId(envelope, fallbackThreadId = 'main') {
+  const meta = envelope?.msg?.meta || {};
+  if (
+    meta.injectedBy === 'route_forward'
+    && typeof meta.sourceThreadId === 'string'
+    && meta.sourceThreadId.trim()
+  ) {
+    return meta.sourceThreadId.trim();
+  }
+  return fallbackThreadId || 'main';
+}
+
 function threadSnapshotForClassifier(thread) {
   return {
     threadId: thread.threadId,
@@ -833,6 +845,13 @@ export function __testGetVpThreads(sessionId, vpId) {
   }));
 }
 
+/** Test-only: seed a VP thread without starting its engine driver. */
+export function __testSeedVpThread({ sessionId, vpId, threadId, title = 'test thread', status = 'queued' }) {
+  const thread = getOrCreateVpThread({ sessionId, vpId, threadId, title });
+  thread.status = status;
+  return thread.threadId;
+}
+
 /** Test-only: wait for thread classification/routing spawned by a msg id. */
 export async function __testWaitForRoutePromises(msgId) {
   await waitForRoutePromises(msgId);
@@ -1016,7 +1035,7 @@ async function routeEnvelopeToVpThread(sessionId, vpId, envelope) {
       msgId: envelope?.msg?.id,
       text,
       sessionId,
-      threadId: thread.threadId,
+      threadId: visibleInboundThreadId(envelope, thread.threadId),
       role: envelope?.msg?.meta?.injectedBy === 'route_forward' ? 'assistant' : 'user',
       speakerVpId: envelope?.msg?.meta?.senderVpId || envelope?.msg?.from || null,
       attachments: Array.isArray(envelope?.msg?.meta?.attachments) ? envelope.msg.meta.attachments : [],
@@ -1109,7 +1128,7 @@ function ensureDriverRunning(sessionId, vpId, threadId = 'main') {
             msgId: envMsgId,
             text,
             sessionId,
-            threadId: thread.threadId,
+            threadId: visibleInboundThreadId(envelope, thread.threadId),
             role: isForward ? 'assistant' : 'user',
             speakerVpId: senderVpId,
             attachments: Array.isArray(meta.attachments) ? meta.attachments : [],
@@ -2619,10 +2638,10 @@ function resolveCollabToolPolicy(sessionMeta) {
 }
 
 export function buildVpQueryOpts({ vpId, sessionCoordinator, sessionId, envelope, threadId = 'main' }) {
-  // Read the group meta once and reuse for both defaultVpId fallback and
-  // announcement injection. Each .getMeta() reload reads + parses the
-  // group.json file, so calling it twice per turn is wasteful — and
-  // (more importantly) opens a window where a concurrent group edit
+  // Read the session meta once and reuse for defaultVpId fallback,
+  // announcement injection, and roster prompt context. Calling getMeta()
+  // twice per turn is wasteful — and (more importantly) opens a window
+  // where a concurrent session edit
   // could land between the two reads, giving the engine a defaultVpId
   // from one snapshot and an announcement from a newer one.
   let sessionMeta = null;
@@ -2660,13 +2679,18 @@ export function buildVpQueryOpts({ vpId, sessionCoordinator, sessionId, envelope
   }
   const collabToolPolicy = resolveCollabToolPolicy(sessionMeta);
   if (collabToolPolicy) out.collabToolPolicy = collabToolPolicy;
-  // task-334-group-editor: surface the group announcement to the engine so
+  if (sessionMeta && Array.isArray(sessionMeta.roster)) {
+    out.sessionMembers = sessionMeta.roster
+      .filter(v => typeof v === 'string' && v.trim())
+      .map(v => v.trim());
+  }
+  // task-334-session-editor: surface the session announcement to the engine so
   // buildWorkerPrompt can inject it as a CLAUDE.md-style shared prefix.
   // Empty/missing reads as '' and prompts.js skips the section.
   if (sessionMeta && typeof sessionMeta.announcement === 'string') {
     out.sessionAnnouncement = sessionMeta.announcement;
   }
-  // Surface the group's configured working directory so the engine can
+  // Surface the session's configured working directory so the engine can
   // resolve CLAUDE.md / AGENTS.md at that path and inject it as a
   // [Project Doc] block above the announcement. Groups with no workDir
   // skip the block silently (matches the announcement contract).