@yeaft/webchat-agent 0.1.791 → 0.1.794

package/package.json

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

package/unify/config.js

@@ -42,6 +42,11 @@ const DEFAULTS = {
   // plumb the knob through so the UI can set it).
   unifyMaxConcurrentThreads: 6,
   unifyAutoArchiveIdleDays: 30,
+  // CLAUDE.md / AGENTS.md project-doc cap, in bytes. Mirrors Codex's
+  // `project_doc_max_bytes`. 0 disables the feature (no project-doc
+  // block is injected). Hand-edited values are NOT clamped — we let
+  // power users opt into larger docs at their own context-window risk.
+  projectDocMaxBytes: 32 * 1024,
 };
 
 // ─── config.json reader ─────────────────────────────────────────
@@ -215,6 +220,10 @@ function loadLegacyConfig(dir, overrides) {
     maxOutputTokens: overrides.maxOutputTokens ?? fileConfig.maxOutputTokens ?? DEFAULTS.maxOutputTokens,
     messageTokenBudget: overrides.messageTokenBudget ?? (env.YEAFT_MESSAGE_TOKEN_BUDGET ? parseInt(env.YEAFT_MESSAGE_TOKEN_BUDGET, 10) : null) ?? fileConfig.messageTokenBudget ?? DEFAULTS.messageTokenBudget,
     maxContinueTurns: overrides.maxContinueTurns ?? fileConfig.maxContinueTurns ?? DEFAULTS.maxContinueTurns,
+    // CLAUDE.md / AGENTS.md project-doc cap, in bytes. Legacy config
+    // has no field for this, so it always lands on the default unless
+    // explicitly overridden via CLI.
+    projectDocMaxBytes: overrides.projectDocMaxBytes ?? fileConfig.projectDocMaxBytes ?? DEFAULTS.projectDocMaxBytes,
     // task-318: legacy path never had the `unify` section — defaults.
     unify: normaliseUnifySection(null),
     providers: null,
@@ -309,6 +318,11 @@ export function loadConfig(overrides = {}) {
     messageTokenBudget: overrides.messageTokenBudget ?? jsonConfig.messageTokenBudget ?? DEFAULTS.messageTokenBudget,
     maxContinueTurns: overrides.maxContinueTurns ?? jsonConfig.maxContinueTurns ?? DEFAULTS.maxContinueTurns,
 
+    // CLAUDE.md / AGENTS.md project-doc cap, in bytes. Set to 0 to
+    // disable the feature entirely. Read from `projectDocMaxBytes` in
+    // ~/.yeaft/config.json or threaded through CLI overrides.
+    projectDocMaxBytes: overrides.projectDocMaxBytes ?? jsonConfig.projectDocMaxBytes ?? DEFAULTS.projectDocMaxBytes,
+
     // task-318: Unify runtime caps. `unify` is a nested section so we
     // don't pollute the flat config namespace used by chat/crew code.
     unify: normaliseUnifySection(jsonConfig.unify),

package/unify/engine.js

@@ -21,6 +21,7 @@ import { randomUUID } from 'crypto';
 import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
 import { LLMContextError, LLMAbortError } from './llm/adapter.js';
 import { runMemoryPreflow, buildRelevantScopes } from './groups/pre-flow.js';
+import { readProjectDoc, pickProjectDocFile, DEFAULT_PROJECT_DOC_MAX_BYTES } from './groups/project-doc.js';
 import { shouldConsolidate, partitionMessages } from './memory/consolidate.js';
 import { runCompact as runCompactOrchestrator } from './compact/orchestrator.js';
 import { evaluateCompactTriggers } from './compact/triggers.js';
@@ -323,6 +324,18 @@ export class Engine {
   /** @type {string|null} */
   #abortReason = null;
 
+  /**
+   * Per-engine cache of the resolved CLAUDE.md / AGENTS.md project doc.
+   * Shape: `{ workDir, path, mtimeMs, text } | null`. A non-null record
+   * means "for THIS workDir, the file at `path` with this `mtimeMs`
+   * resolved to `text`" — when the next turn's stat returns the same
+   * `(path, mtimeMs)` tuple, we skip the read entirely. mtime changes
+   * (or a different picked file, e.g. user added AGENTS.md) invalidate
+   * automatically because the `path`/`mtimeMs` comparison fails.
+   * @type {{ workDir: string, path: string, mtimeMs: number, text: string }|null}
+   */
+  #projectDocCache = null;
+
   /**
    * @param {{
    *   adapter: import('./llm/adapter.js').LLMAdapter,
@@ -685,10 +698,11 @@ export class Engine {
    * @param {object} [args.vpPersona]
    * @param {object} [args.activeScope] — DESIGN-PROMPT §3 ④ structured scope summary
    * @param {string} [args.groupAnnouncement]
+   * @param {string} [args.projectDoc] — resolved CLAUDE.md / AGENTS.md text (already truncated)
    * @param {object} [args.taskCtx] — legacy task-context sub-block (optional)
    * @returns {string}
    */
-  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, groupAnnouncement, taskCtx } = {}) {
+  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, groupAnnouncement, projectDoc, taskCtx } = {}) {
     // Get relevant skill content if SkillManager is wired
     let skillContent = '';
     if (this.#skillManager && prompt) {
@@ -708,6 +722,7 @@ export class Engine {
       vpPersona,
       activeScope,
       groupAnnouncement,
+      projectDoc,
       taskCtx,
       // Worker-shape harness is descriptive metadata for human inspection;
       // production prompts skip it to save tokens. Re-enable via env when
@@ -716,6 +731,76 @@ export class Engine {
     });
   }
 
+  /**
+   * Resolve the CLAUDE.md / AGENTS.md project doc text for the current
+   * group's working directory. mtime-cached on the engine so we only
+   * re-read the file when the user actually edited it.
+   *
+   * Cache strategy:
+   *   1. Cheap path: `pickProjectDocFile` (two stats, no read).
+   *   2. If the picked `(path, mtimeMs)` matches the cache → return
+   *      cached text. No disk read, no UTF-8 decode, no truncation work.
+   *   3. Cache miss → call `readProjectDoc` (bounded `readSync` into a
+   *      pre-sized buffer), refresh the cache, return the fresh text.
+   *
+   * Returns '' when:
+   *   - workDir is empty / not a string
+   *   - config.projectDocMaxBytes === 0 (feature disabled)
+   *   - neither CLAUDE.md nor AGENTS.md exists in workDir
+   *   - the picked file is empty after trim
+   *
+   * @param {string|undefined} workDir
+   * @returns {string}
+   */
+  #getProjectDocBlock(workDir) {
+    if (typeof workDir !== 'string' || !workDir.trim()) {
+      this.#projectDocCache = null;
+      return '';
+    }
+    const maxBytes = Number.isFinite(this.#config?.projectDocMaxBytes)
+      ? this.#config.projectDocMaxBytes
+      : DEFAULT_PROJECT_DOC_MAX_BYTES;
+    if (maxBytes === 0) {
+      this.#projectDocCache = null;
+      return '';
+    }
+
+    // Step 1 — stat-only check. Cheap (two `statSync` calls) and lets
+    // us short-circuit the read when the file hasn't moved.
+    const picked = pickProjectDocFile(workDir);
+    if (!picked) {
+      this.#projectDocCache = null;
+      return '';
+    }
+
+    // Step 2 — cache hit? Same workDir, same picked file, same mtime
+    // ⇒ the previously decoded text is still authoritative. Skip the
+    // file read entirely.
+    const cache = this.#projectDocCache;
+    if (
+      cache
+      && cache.workDir === workDir
+      && cache.path === picked.path
+      && cache.mtimeMs === picked.mtimeMs
+    ) {
+      return cache.text;
+    }
+
+    // Step 3 — cache miss. Read + decode, then refresh the cache.
+    const doc = readProjectDoc(workDir, { maxBytes });
+    if (!doc) {
+      this.#projectDocCache = null;
+      return '';
+    }
+    this.#projectDocCache = {
+      workDir,
+      path: doc.path,
+      mtimeMs: doc.mtimeMs,
+      text: doc.text,
+    };
+    return doc.text;
+  }
+
   /**
    * Build the full tool context for Phase 5 tools.
    *
@@ -1037,7 +1122,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, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null } = {}) {
+  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -1096,7 +1181,7 @@ export class Engine {
     const runSignal = abortCtrl.signal;
 
     try {
-      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted, getCurrentTodos, setCurrentTodos });
+      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, workDir, userAlreadyPersisted, getCurrentTodos, setCurrentTodos });
     } finally {
       if (signal) {
         try { signal.removeEventListener('abort', onExternalAbort); } catch { /* ignore */ }
@@ -1114,7 +1199,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, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null }) {
+  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null }) {
 
     // ─── Pre-query: FTS5 Memory Recall + AMS snapshot ─────
     // Memory has a SINGLE render outlet now (DESIGN-PROMPT §3 ③):
@@ -1183,12 +1268,15 @@ export class Engine {
       envelope: inboundEnvelope || null,
     };
 
+    const projectDoc = this.#getProjectDocBlock(workDir);
+
     const systemPrompt = this.#buildSystemPrompt({
       prompt,
       memoryInjection,
       vpPersona,
       activeScope,
       groupAnnouncement,
+      projectDoc,
     });
 
     // ─── Compact summary as messages-array head (DESIGN-PROMPT §4.3) ─

package/unify/groups/project-doc.js

@@ -0,0 +1,148 @@
+/**
+ * project-doc.js — Read CLAUDE.md / AGENTS.md from a group's workDir.
+ *
+ * Per-group, the user may park a project-level instructions file in the
+ * group's configured `workDir`. This module is the stateless reader for
+ * those files. The Engine owns the cache (per session, per VP) so that
+ * mtime-driven invalidation can happen without a singleton cache.
+ *
+ * File-selection rule (matches user spec):
+ *   • If both `CLAUDE.md` and `AGENTS.md` exist, the one with the newer
+ *     mtime wins. Tie → CLAUDE.md (deterministic; this is the project's
+ *     own convention).
+ *   • If only one exists, pick it.
+ *   • If neither exists, return null. Caller skips the prompt block.
+ *
+ * Why two filenames? CLAUDE.md is this project's convention; AGENTS.md
+ * is the cross-tool convention adopted by Codex / OpenAI Codex CLI. Both
+ * carry the same kind of payload — long-form project instructions — and
+ * we want users coming from either ecosystem to "just work".
+ *
+ * Size cap. We read up to `maxBytes` and truncate larger files with a
+ * console warning. Default cap is 32 KB (`DEFAULT_PROJECT_DOC_MAX_BYTES`),
+ * mirroring Codex's `project_doc_max_bytes`. Setting the cap to 0 in the
+ * engine config disables the feature entirely (the caller short-circuits
+ * before reaching this module).
+ *
+ * NO module-level cache. The engine holds the cache so a mtime change
+ * between sessions doesn't ride along into a fresh engine instance, and
+ * tests can construct two engines without interfering with each other.
+ */
+
+import { statSync, openSync, readSync, closeSync } from 'fs';
+import { join } from 'path';
+
+/** Filenames probed in `workDir`, in tie-break order (first wins on tie). */
+export const PROJECT_DOC_FILENAMES = ['CLAUDE.md', 'AGENTS.md'];
+
+/** Default max bytes pulled into the prompt block. Matches Codex. */
+export const DEFAULT_PROJECT_DOC_MAX_BYTES = 32 * 1024;
+
+/**
+ * Stat both candidate filenames in `workDir` and return whichever has the
+ * newer mtime, or null when neither exists / workDir is unusable.
+ *
+ * Pure stat — does NOT read file contents. Returns a lightweight stat
+ * record so the caller can compare against a cached `mtimeMs` before
+ * deciding to re-read.
+ *
+ * @param {string} workDir
+ * @returns {{ path: string, mtimeMs: number } | null}
+ */
+export function pickProjectDocFile(workDir) {
+  if (typeof workDir !== 'string' || !workDir.trim()) return null;
+  try {
+    const dirStat = statSync(workDir);
+    if (!dirStat.isDirectory()) return null;
+  } catch {
+    // Non-existent / permission-denied / not a path we can stat.
+    return null;
+  }
+
+  let best = null;
+  for (const name of PROJECT_DOC_FILENAMES) {
+    const path = join(workDir, name);
+    let s;
+    try {
+      s = statSync(path);
+    } catch {
+      // Missing or unreadable; try the next candidate.
+      continue;
+    }
+    if (!s.isFile()) continue;
+    // Strict-greater so ties favor the order in PROJECT_DOC_FILENAMES.
+    if (!best || s.mtimeMs > best.mtimeMs) {
+      best = { path, mtimeMs: s.mtimeMs };
+    }
+  }
+  return best;
+}
+
+/**
+ * Read the picked project-doc file. Returns null when nothing is
+ * eligible (no workDir, no file, empty contents after trim).
+ *
+ * Bounded I/O. We allocate `maxBytes + 1` bytes and `readSync` once —
+ * never letting a runaway file balloon the agent's heap. The extra
+ * byte tells us whether the file was actually larger (so we know to
+ * warn about truncation).
+ *
+ * Codepoint-safe truncation. When we cut mid-byte inside a multi-byte
+ * UTF-8 sequence (very likely for `zh-CN` docs), we walk back to the
+ * last codepoint boundary before decoding, so the model sees clean
+ * text instead of a trailing `U+FFFD` replacement character.
+ *
+ * @param {string} workDir
+ * @param {{ maxBytes?: number }} [opts]
+ * @returns {{ path: string, mtimeMs: number, text: string } | null}
+ */
+export function readProjectDoc(workDir, opts = {}) {
+  const maxBytes = Number.isFinite(opts.maxBytes) && opts.maxBytes >= 0
+    ? opts.maxBytes
+    : DEFAULT_PROJECT_DOC_MAX_BYTES;
+  if (maxBytes === 0) return null;
+
+  const picked = pickProjectDocFile(workDir);
+  if (!picked) return null;
+
+  // Allocate one extra byte so a `bytesRead === maxBytes + 1` tells us
+  // there's more content beyond the cap — i.e. the file was truncated.
+  const cap = maxBytes + 1;
+  const buffer = Buffer.allocUnsafe(cap);
+  let fd;
+  let bytesRead = 0;
+  try {
+    fd = openSync(picked.path, 'r');
+    bytesRead = readSync(fd, buffer, 0, cap, 0);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* ignore */ }
+    }
+  }
+
+  let useBytes = bytesRead;
+  const truncated = bytesRead > maxBytes;
+  if (truncated) {
+    useBytes = maxBytes;
+    // Walk back into the buffer until the cut isn't sitting in the
+    // middle of a multi-byte UTF-8 sequence. Each continuation byte
+    // matches the pattern `10xxxxxx` (0x80–0xBF). We scan back at most
+    // 3 bytes — UTF-8 codepoints are ≤ 4 bytes total.
+    let scan = 0;
+    while (scan < 3 && useBytes > 0 && (buffer[useBytes] & 0xC0) === 0x80) {
+      useBytes -= 1;
+      scan += 1;
+    }
+  }
+
+  const text = buffer.toString('utf8', 0, useBytes).trim();
+  if (truncated) {
+    console.warn(
+      `[unify/project-doc] ${picked.path} exceeds ${maxBytes} bytes — truncated.`,
+    );
+  }
+  if (!text) return null;
+  return { path: picked.path, mtimeMs: picked.mtimeMs, text };
+}

package/unify/prompts.js

@@ -195,6 +195,12 @@ const PROMPTS = {
     // DESIGN-PROMPT §3 ④ — Active Scope header
     activeScopeHeader: '## active_scope',
     groupAnnouncementHeader: '[Group Announcement]',
+    // Project-doc (CLAUDE.md / AGENTS.md) header + one-liner intro. Both
+    // filenames are recognized: CLAUDE.md is this project's convention,
+    // AGENTS.md is the cross-tool convention (Codex / OpenAI Codex CLI).
+    projectDocHeader: '[Project Doc]',
+    projectDocIntro:
+      'The user keeps project-level instructions and context in `CLAUDE.md` or `AGENTS.md` at the group\'s working directory. Treat the content below as authoritative project context — coding conventions, task guidance, workflow rules, etc.',
     vpPersonaIntro: (name, role) =>
       `You ARE **${name}**${role ? ` (${role})` : ''}. Speak in the first person as ${name}; do not refer to yourself as "Yeaft" or as a generic AI assistant. The text below is your identity, expertise, and decision style.`,
   },
@@ -206,6 +212,10 @@ const PROMPTS = {
     // DESIGN-PROMPT §3 ④ — Active Scope header
     activeScopeHeader: '## active_scope',
     groupAnnouncementHeader: '[群组公告]',
+    // 项目文档块：CLAUDE.md / AGENTS.md（与 Codex 通用命名兼容）。
+    projectDocHeader: '[项目文档]',
+    projectDocIntro:
+      '用户把项目级的说明和上下文记录在群组工作目录下的 `CLAUDE.md` 或 `AGENTS.md` 中。下面的内容是权威的项目上下文 —— 编码规范、任务指导、工作流约定等，请遵循它来工作。',
     vpPersonaIntro: (name, role) =>
       `你就是 **${name}**${role ? `（${role}）` : ''}。请以 ${name} 的第一人称发言；不要自称 "Yeaft" 或泛指的 AI 助手。下面的文字是你的身份、专业方向与判断风格。`,
   },
@@ -271,6 +281,7 @@ export function normalizePromptLanguage(language) {
  *   activeScope?: object,
  *   vpPersona?: object,
  *   groupAnnouncement?: string,
+ *   projectDoc?: string,
  * }} params
  * @returns {string}
  */
@@ -283,6 +294,7 @@ export function buildSystemPrompt({
   activeScope,
   vpPersona,
   groupAnnouncement = '',
+  projectDoc = '',
 } = {}) {
   // Normalize app locales like `zh-CN` to prompt dictionary/template keys.
   const effectiveLang = normalizePromptLanguage(language);
@@ -310,6 +322,21 @@ export function buildSystemPrompt({
     }
   }
 
+  // ─── 1.4  Project Doc (CLAUDE.md / AGENTS.md from group workDir) ───
+  // The group's working-directory may contain a project-level
+  // instructions file. The engine resolves "newest of CLAUDE.md vs
+  // AGENTS.md by mtime" and threads the resulting text through here.
+  // Empty/whitespace = no block emitted. Sits ABOVE the announcement
+  // because user-authored project files are higher signal than the
+  // group-level announcement (which is typically a short rule).
+  const docText = (typeof projectDoc === 'string') ? projectDoc.trim() : '';
+  if (docText) {
+    const docHeader = lang.projectDocHeader || '[Project Doc]';
+    const docIntro = lang.projectDocIntro || '';
+    const introLine = docIntro ? `${docIntro}\n\n` : '';
+    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
   // near the top of the system prompt — before tools, memory, mode-specific

package/unify/vp/seed-defaults.js

@@ -31,6 +31,7 @@ import { existsSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { join } from 'path';
 import { createVp, VpCrudError } from './vp-crud.js';
 import { DEFAULT_VP_LIB_DIR } from './vp-store.js';
+import { STOCK_VP_IDS } from './stock-ids.js';
 
 /**
  * The 33 default VPs. Each entry is a valid `createVp` payload.
@@ -855,6 +856,33 @@ Bad for: requests that require pretending to be a licensed professional, bypassi
   },
 ]);
 
+/**
+ * Self-check: every seed persona's vpId must appear in STOCK_VP_IDS, and
+ * vice versa. The two lists live in separate modules to break a circular
+ * import (see stock-ids.js header), so the only thing keeping them in
+ * sync is this load-time assertion. If you add a new seed VP and forget
+ * to add its id to stock-ids.js#STOCK_VP_ID_LIST (or vice versa), the
+ * agent will refuse to start with a clear error.
+ */
+const _seedIds = new Set(DEFAULT_VPS.map(v => v.vpId));
+{
+  const missingInStockIds = [];
+  for (const id of _seedIds) {
+    if (!STOCK_VP_IDS.has(id)) missingInStockIds.push(id);
+  }
+  const missingInSeeds = [];
+  for (const id of STOCK_VP_IDS) {
+    if (!_seedIds.has(id)) missingInSeeds.push(id);
+  }
+  if (missingInStockIds.length || missingInSeeds.length) {
+    throw new Error(
+      '[seed-defaults] DEFAULT_VPS / STOCK_VP_IDS mismatch — '
+      + `add to stock-ids.js: [${missingInStockIds.join(', ')}]; `
+      + `add to DEFAULT_VPS: [${missingInSeeds.join(', ')}]`,
+    );
+  }
+}
+
 /**
  * True iff `libDir` exists and contains at least one subdirectory that
  * looks like a VP entry (has a `role.md` file). A stray empty directory

package/unify/vp/stock-ids.js

@@ -0,0 +1,53 @@
+/**
+ * stock-ids.js — single source of truth for "is this vpId a stock seed VP?".
+ *
+ * Owns the canonical list of seed vpIds and exposes `STOCK_VP_IDS` (a Set
+ * for O(1) lookup) plus `isStockVpId(vpId)`.
+ *
+ * Why this lives in its own tiny module instead of in seed-defaults.js:
+ *   `seed-defaults.js` imports `createVp / VpCrudError` from `vp-crud.js`,
+ *   so if `vp-crud.js` were to import `STOCK_VP_IDS` from `seed-defaults`
+ *   directly, the module graph would be circular (vp-crud → seed-defaults
+ *   → vp-crud). The cycle "works" today only because every consumer reads
+ *   STOCK_VP_IDS inside a function body (live binding), but a future
+ *   refactor that moves the check to module top level — say, to validate
+ *   input on import — would crash with `STOCK_VP_IDS is undefined`. Moving
+ *   the Set into a leaf module with zero inbound deps from elsewhere in
+ *   the package breaks the cycle for good.
+ *
+ * Authoritative-vs-derived: this file is the SOURCE OF TRUTH for stock
+ * ids. seed-defaults.js asserts at module load that every entry in
+ * DEFAULT_VPS appears here, and vice versa — see the self-check at the
+ * bottom of seed-defaults.js. So adding a new seed VP only requires
+ * adding both the persona object *and* its id here (two-file change,
+ * caught by the assertion if you forget either).
+ */
+
+const STOCK_VP_ID_LIST = Object.freeze([
+  // engineering
+  'steve', 'linus', 'martin', 'dieter', 'ada', 'grace', 'alice', 'ken',
+  'margaret', 'shannon', 'alan', 'norman',
+  // philosophy / psychology
+  'kongzi', 'socrates', 'nietzsche', 'kahneman', 'jung',
+  // strategy / business
+  'sunzi', 'clausewitz', 'simaqian', 'harari',
+  'buffett', 'munger', 'dalio', 'bezos', 'drucker',
+  // arts / culture
+  'luxun', 'sudongpo', 'borges', 'einstein', 'kubrick', 'miyazaki',
+  // assistant
+  'omni',
+]);
+
+/** @type {ReadonlySet<string>} */
+export const STOCK_VP_IDS = new Set(STOCK_VP_ID_LIST);
+
+/**
+ * True iff `vpId` is a stock seed VP that ships with the agent.
+ * Pure function of the string — undefined / non-string input returns false.
+ *
+ * @param {unknown} vpId
+ * @returns {boolean}
+ */
+export function isStockVpId(vpId) {
+  return typeof vpId === 'string' && STOCK_VP_IDS.has(vpId);
+}

package/unify/vp/vp-bridge.js

@@ -23,6 +23,7 @@
 
 import { defaultRegistry } from './registry.js';
 import { VpLoader } from './vp-loader.js';
+import { STOCK_VP_IDS } from './stock-ids.js';
 
 /** Process-singleton VpLoader; lazily started on first subscribe. */
 let _loaderStarted = false;
@@ -175,8 +176,8 @@ function ensureLoader(registry = defaultRegistry) {
  * Serialise a VP (entity layer shape) to the wire-format the web layer
  * expects (spec §2.1). Pure; no IO.
  *
- * @param {{id:string,name:string,role:string,traits?:string[],modelHint?:string,personaHash?:string}} vp
- * @returns {{vpId:string,displayName:string,subtitle:string,role:string,traits:string[],modelHint:?string,personaHash:?string}}
+ * @param {{id:string,name:string,role:string,nameZh?:string,aliases?:string[],traits?:string[],modelHint?:string,personaHash?:string}} vp
+ * @returns {{vpId:string,displayName:string,displayNameZh:string,aliases:string[],subtitle:string,role:string,traits:string[],modelHint:?string,personaHash:?string,isStock:boolean}}
  */
 export function serializeVpForWire(vp) {
   return {
@@ -191,6 +192,13 @@ export function serializeVpForWire(vp) {
     traits: Array.isArray(vp.traits) ? vp.traits.slice() : [],
     modelHint: vp.modelHint ?? null,
     personaHash: vp.personaHash ?? null,
+    // task-vp-customize: mark seed VPs so the frontend can disable
+    // Edit/Delete and surface a "Stock" badge. Pure id check — see
+    // stock-ids.js#STOCK_VP_IDS for the contract. `Set.has(undefined)`
+    // is fine, but we still coerce to plain boolean so the wire field
+    // is strictly `true | false` (never `undefined`) and downstream
+    // `!!` reads can collapse cleanly.
+    isStock: STOCK_VP_IDS.has(vp.id) === true,
   };
 }
 

package/unify/vp/vp-crud.js

@@ -14,6 +14,7 @@
  * Error codes returned to the caller (wire-visible):
  *   'duplicate'      — vpId already exists (on create)
  *   'not_found'      — vpId does not exist on disk (on update/delete)
+ *   'stock_readonly' — vpId is one of the seed/stock VPs (mutation refused)
  *   <reason from validateVpId> — invalid shape
  */
 
@@ -24,6 +25,7 @@ import { validateVpId } from '../groups/ids.js';
 import { DEFAULT_VP_LIB_DIR, parseRoleMd } from './vp-store.js';
 import { seedSummaryIfMissingSync, removeScopeDirSync } from '../memory/store-v2.js';
 import { VP_STUB_MARKER } from '../memory/seed-backfill.js';
+import { STOCK_VP_IDS } from './stock-ids.js';
 
 /**
  * Default memory root used when callers don't pass `options.memoryRoot`.
@@ -34,13 +36,6 @@ import { VP_STUB_MARKER } from '../memory/seed-backfill.js';
  */
 const DEFAULT_MEMORY_ROOT = join(homedir(), '.yeaft', 'memory');
 
-/**
- * Build the seed summary body for a freshly-created VP. Pulled into a
- * helper so tests can pin the exact format.
- *
- * @param {object} payload  same shape as createVp
- * @returns {string}
- */
 /**
  * Build the seed body for a freshly-created VP's `<root>/vp/<id>/summary.md`.
  *
@@ -218,6 +213,11 @@ export function updateVp(payload, options = {}) {
   const v = validateVpId(vpId);
   if (!v.ok) throw new VpCrudError(v.reason, vpId);
 
+  // Stock VPs ship with the agent and are immutable from the CRUD path.
+  // The UI also disables Edit/Delete on these, but a misbehaving WS client
+  // could bypass the UI — refuse here so the file on disk stays canonical.
+  if (STOCK_VP_IDS.has(vpId)) throw new VpCrudError('stock_readonly', vpId);
+
   const dir = vpDirFor(libDir, vpId);
   if (!existsSync(dir) || !existsSync(vpRolePathFor(libDir, vpId))) {
     throw new VpCrudError('not_found', vpId);
@@ -249,6 +249,10 @@ export function deleteVp(vpId, options = {}) {
   if (!vpId || typeof vpId !== 'string' || vpId.includes('/') || vpId.includes('\\') || vpId === '..' || vpId === '.') {
     throw new VpCrudError('illegal_character', vpId);
   }
+  // Stock VPs ship with the agent. Refuse the delete server-side so a
+  // misbehaving WS client cannot wipe `~/.yeaft/virtual-persons/steve/`
+  // even if the UI's delete button is missing or disabled.
+  if (STOCK_VP_IDS.has(vpId)) throw new VpCrudError('stock_readonly', vpId);
   const dir = vpDirFor(libDir, vpId);
   if (!existsSync(dir)) {
     throw new VpCrudError('not_found', vpId);
@@ -298,5 +302,11 @@ export function readVp(vpId, options = {}) {
     modelHint,
     persona: body,
     planInstruction: typeof meta.planInstruction === 'string' ? String(meta.planInstruction) : '',
+    // Echo the authoritative stock flag on the read response so the UI's
+    // detail view doesn't have to trust the (potentially stale) list
+    // snapshot it was launched from. Defence-in-depth: same Set, two
+    // call sites; if either disagrees, the agent guard in updateVp /
+    // deleteVp is still the final word.
+    isStock: STOCK_VP_IDS.has(id) === true,
   };
 }

package/unify/web-bridge.js

@@ -1988,6 +1988,13 @@ export function buildVpQueryOpts({ vpId, groupCoordinator, groupId, envelope })
   if (groupMeta && typeof groupMeta.announcement === 'string') {
     out.groupAnnouncement = groupMeta.announcement;
   }
+  // Surface the group'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).
+  if (groupMeta && typeof groupMeta.workDir === 'string' && groupMeta.workDir.trim()) {
+    out.workDir = groupMeta.workDir.trim();
+  }
   try {
     const vp = readVp(resolvedVpId);
     if (vp) {