@yeaft/webchat-agent 0.1.480 → 0.1.482

package/crew-i18n.js

@@ -133,7 +133,11 @@ ${isDevTeam ? '3' : '2'}. **任务完成** - 所有任务已完成，给出完
       // dev team
       developer: (dm) => `代码完成后，必须同时发两个 ROUTE 块分别交给审查者和测试者（缺一不可）。
 UI/交互方案不确定时找设计师确认。需求不明确时找决策者 "${dm}" 确认。
-**⚠️ 你的回复必须以 ROUTE 块结尾。不发 ROUTE = 代码无法进入审查流程。**`,
+**⚠️ 你的回复必须以 ROUTE 块结尾。不发 ROUTE = 代码无法进入审查流程。**
+
+> 🚨 **合并与发布 — Dev 严禁自打 tag**
+> 不得执行 \`git tag\` 或 push \`v*\` / \`release-*\` 到 origin，除非用户明确要求 release。
+> tag 由 PM/reviewer 在 main 分支上执行。详见 \`.crew/CLAUDE.md\` "代码合并与发布规则" 和 \`CONTRIBUTING.md\` "🚨 Tagging & Release Rules"。`,
       reviewer_dev: (dm) => `审查完成后：评分 ≥ 9分通过，ROUTE 给对应的测试者（如 rev-1 → test-1）告知审查通过、可以开始测试。评分 < 9分打回给开发者修改。
 遇到架构层面的问题找决策者 "${dm}" 讨论。
 **⚠️ 你的回复必须以 ROUTE 块结尾。不发 ROUTE = 审查结果无法传递。**`,
@@ -188,7 +192,15 @@ UI/交互方案不确定时找设计师确认。需求不明确时找决策者 "
 - **Dev 严禁自己打 tag** — tag 只能由 PM 或 reviewer 合并后打
 - **Dev 完成后必须 ROUTE 给 reviewer** — 不 ROUTE 等于没完成，消息无法传递
 - **即使是小修复（一行改动），也必须走 PR + review 流程**
-- **合并和打 tag 由 reviewer 或 PM 执行**，dev 不自己合并`,
+- **合并和打 tag 由 reviewer 或 PM 执行**，dev 不自己合并
+
+## Tagging Checklist（任何角色 tag 前必读）
+1. **分支检查**：当前分支必须是 main（\`git branch --show-current\` == \`main\`），非 main 分支一律不得 tag
+2. **Conventional commits**：commit message 使用 \`feat:\` / \`fix:\` / \`perf:\` 等规范前缀
+3. **不得自打 tag**：除非用户明确要求 release，否则 dev/reviewer/tester 角色不得执行 \`git tag\`
+4. **Tag 前确认 origin/main**：被 tag 的 commit 必须已经在 \`origin/main\` 上（\`git merge-base --is-ancestor <sha> origin/main\`）
+
+完整规则与 2026-04-17 违规案例见 \`CONTRIBUTING.md\` "🚨 Tagging & Release Rules"。`,
     taskSplitRules: '# 任务拆分原则',
     taskSplitRulesContent: `- **不相干的修改必须分给不同的 dev，产出独立的 PR**。严禁把两个不相关的 bug fix / feature 放在同一个 PR 中。
 - 即使两个改动看似相关（如同一个 bug 的两个方面），如果它们改的文件不同、逻辑独立，也应该拆成独立 task + 独立 PR。
@@ -393,7 +405,11 @@ Execute stop-losses immediately when triggered and notify the decision maker. Re
       // dev team
       developer: (dm) => `After code is complete, you must send two ROUTE blocks simultaneously to reviewer and tester (both required).
 Check with designer for UI/interaction questions. Check with decision maker "${dm}" for unclear requirements.
-**⚠️ Your reply MUST end with ROUTE blocks. Not sending a ROUTE = code cannot enter the review process.**`,
+**⚠️ Your reply MUST end with ROUTE blocks. Not sending a ROUTE = code cannot enter the review process.**
+
+> 🚨 **Merge & Release — Dev MUST NOT self-tag**
+> Do NOT run \`git tag\` or push \`v*\` / \`release-*\` to origin unless the user explicitly requested a release.
+> Tags are created by PM/reviewer on the \`main\` branch only. See \`.crew/CLAUDE.md\` "Code Merge & Release Rules" and \`CONTRIBUTING.md\` "🚨 Tagging & Release Rules" for details.`,
       reviewer_dev: (dm) => `After review: score >= 9 passes, ROUTE to the corresponding tester (e.g., rev-1 → test-1) to notify review passed and testing can begin. Score < 9: send back to developer with issues.
 Discuss architecture-level concerns with decision maker "${dm}".
 **⚠️ Your reply MUST end with a ROUTE block. Not sending a ROUTE = review results cannot be passed on.**`,
@@ -447,7 +463,15 @@ After development is complete, send two ROUTE blocks simultaneously to ${revName
 - **Dev must never create tags** — Tags can only be created by PM or reviewer after merge
 - **Dev must ROUTE to reviewer after completion** — Not ROUTEing = work not delivered, message cannot be passed
 - **Even small fixes (single-line changes) must go through PR + review workflow**
-- **Merge and tagging are done by reviewer or PM** — dev does not merge themselves`,
+- **Merge and tagging are done by reviewer or PM** — dev does not merge themselves
+
+## Tagging Checklist (required reading before any \`git tag\`)
+1. **Branch check**: current branch MUST be \`main\` (\`git branch --show-current\` == \`main\`); never tag from a feature/worktree branch
+2. **Conventional commits**: commit messages use \`feat:\` / \`fix:\` / \`perf:\` prefixes
+3. **No self-tagging**: unless the user explicitly requested a release, dev/reviewer/tester roles MUST NOT run \`git tag\`
+4. **Verify origin/main before tag**: the commit being tagged must already be on \`origin/main\` (\`git merge-base --is-ancestor <sha> origin/main\`)
+
+Full rules and the 2026-04-17 violation precedent are in \`CONTRIBUTING.md\` "🚨 Tagging & Release Rules".`,
     taskSplitRules: '# Task Split Principles',
     taskSplitRulesContent: `- **Unrelated changes must go to different devs with independent PRs**. Never put two unrelated bug fixes / features in the same PR.
 - Even if two changes seem related (e.g., two aspects of the same bug), if they modify different files and have independent logic, they should be split into independent tasks + independent PRs.

package/package.json

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

package/unify/engine.js

@@ -275,8 +275,10 @@ export class Engine {
     // task-299 Phase 1: tag persisted messages with the current thread.
     // getThreadStore() lazily seeds a default 'main' thread if not yet init'd.
     let threadId = MAIN_THREAD_ID;
+    let threadStore = null;
     try {
-      threadId = getThreadStore().currentId || MAIN_THREAD_ID;
+      threadStore = getThreadStore();
+      threadId = threadStore.currentId || MAIN_THREAD_ID;
     } catch {
       // Defensive: any store failure falls back to 'main' so persistence
       // never breaks because of thread bookkeeping.
@@ -302,6 +304,18 @@ export class Engine {
       assistantMsg.toolCalls = toolCalls;
     }
     this.#conversationStore.append(assistantMsg);
+
+    // task-299 Phase 1 cached-field update: bump thread counters twice
+    // (once for user, once for assistant). Any exception is swallowed so
+    // bookkeeping never blocks the main persist path.
+    try {
+      if (threadStore) {
+        threadStore.noteMessage(threadId);
+        threadStore.noteMessage(threadId);
+      }
+    } catch {
+      // Non-critical; counters can be rebuilt via rebuildFromMessages().
+    }
   }
 
   /**
@@ -338,7 +352,13 @@ export class Engine {
    * Yields EngineEvent objects that the caller (CLI, web) can consume
    * to render output in real-time.
    *
-   * @param {{ prompt: string, mode?: string, messages?: Array, signal?: AbortSignal }} params
+   * @param {object} params
+   * @param {string} params.prompt - The user prompt (required, non-empty).
+   * @param {'dream'} [params.mode] - Optional mode flag. Since task-297 the only
+   *   value accepted / acted on is `'dream'` (memory maintenance system prompt).
+   *   Any other value is ignored and falls through to the unified system prompt.
+   * @param {Array} [params.messages] - Prior conversation messages.
+   * @param {AbortSignal} [params.signal] - Abort signal.
    * @yields {EngineEvent}
    */
   async *query({ prompt, mode, messages = [], signal }) {

package/unify/session.js

@@ -25,6 +25,8 @@ import { createFullRegistry } from './tools/index.js';
 import { initTaskStore } from './tools/task-tools.js';
 import { initThreadStore } from './threads/store.js';
 import { Engine } from './engine.js';
+import { createThreadEngineRegistry } from './threads/engine-registry.js';
+import { MAIN_THREAD_ID } from './threads/store.js';
 import { join } from 'path';
 
 /**
@@ -166,6 +168,25 @@ export async function loadSession(options = {}) {
     yeaftDir,
   });
 
+  // task-308 Phase 2: thread-aware engine registry.
+  // Each thread gets its own EngineInstance (lazy-created) that owns its
+  // messages array and tags all events with the bound threadId. Legacy
+  // single-engine callers keep working via `session.engine`; multi-thread
+  // callers use `session.engineRegistry.ensure(threadId)`.
+  const engineRegistry = createThreadEngineRegistry({
+    adapter,
+    trace,
+    config,
+    conversationStore,
+    memoryStore,
+    toolRegistry,
+    skillManager,
+    mcpManager,
+    yeaftDir,
+  });
+  // Seed the main-thread instance so listActive() is non-empty from T=0.
+  engineRegistry.ensure(MAIN_THREAD_ID);
+
   // ─── 10. Build session ─────────────────────────────────
   const status = {
     skills: skillManager.size,
@@ -176,6 +197,11 @@ export async function loadSession(options = {}) {
 
   /** Graceful shutdown: disconnect MCP, close trace DB. */
   async function shutdown() {
+    try {
+      engineRegistry.terminateAll();
+    } catch {
+      // Best-effort cleanup
+    }
     try {
       await mcpManager.disconnectAll();
     } catch {
@@ -190,6 +216,7 @@ export async function loadSession(options = {}) {
 
   return {
     engine,
+    engineRegistry,
     adapter,
     config,
     conversationStore,

package/unify/tasks/store.js

@@ -31,7 +31,12 @@ function serializeTask(task) {
     `priority: ${task.priority || 'medium'}`,
   ];
 
+  // task-299 (Q3 rework): parentTaskId is the canonical field per design §5.
+  // parentId is kept as a legacy mirror for backward compat with any tool
+  // that still reads it; both are always in sync after migration.
+  if (task.parentTaskId) fm.push(`parentTaskId: ${task.parentTaskId}`);
   if (task.parentId) fm.push(`parentId: ${task.parentId}`);
+  if (task.primaryThreadId) fm.push(`primaryThreadId: ${task.primaryThreadId}`);
   if (task.createdAt) fm.push(`createdAt: ${task.createdAt}`);
   if (task.updatedAt) fm.push(`updatedAt: ${task.updatedAt}`);
 
@@ -92,9 +97,19 @@ function parseTask(raw) {
     task.description = body;
   }
 
-  // Normalize parentId
-  if (!task.parentId || task.parentId === 'null') {
-    task.parentId = null;
+  // Normalize parentId / parentTaskId (design §5 canonical is parentTaskId).
+  // If only legacy parentId is present, promote it to parentTaskId so
+  // anything that reads the canonical field sees a value. Null/"null"
+  // strings become real null.
+  if (!task.parentId || task.parentId === 'null') task.parentId = null;
+  if (!task.parentTaskId || task.parentTaskId === 'null') task.parentTaskId = null;
+  if (!task.parentTaskId && task.parentId) task.parentTaskId = task.parentId;
+  if (!task.parentId && task.parentTaskId) task.parentId = task.parentTaskId;
+
+  // primaryThreadId: per design §5 clarification (task-299 Q4), null means
+  // "unbound / orphan" — it does NOT implicitly equal 'main'. Keep null as null.
+  if (!task.primaryThreadId || task.primaryThreadId === 'null') {
+    task.primaryThreadId = null;
   }
 
   return task;
@@ -191,6 +206,12 @@ export class TaskStore {
 
     // Load existing tasks from disk
     this.#loadAll();
+
+    // task-299 (Q3, rework): run a one-shot backfill that promotes legacy
+    // `parentId` to the canonical `parentTaskId` field (design §5). A
+    // marker file (.migrations/parentTaskId) records completion so the
+    // migration is skipped on subsequent boots and is idempotent.
+    this.#migrateParentTaskId();
   }
 
   /** Number of tasks in the store. */
@@ -275,6 +296,30 @@ export class TaskStore {
     return results;
   }
 
+  /**
+   * Return tasks grouped as a tree. Tasks with no parent (parentTaskId == null)
+   * are "roots"; each non-root task becomes a child of its parent.
+   *
+   * Used by task-298/task-300 to render task hierarchies. Critical for the
+   * Q3 migration test: before the backfill, old tasks stored only `parentId`
+   * and `tree()` would see every task as a root.
+   *
+   * @returns {{ roots: object[], orphans: object[] }}
+   *   - roots   : tasks whose parentTaskId is null
+   *   - orphans : tasks whose parentTaskId points to an id that no longer exists
+   */
+  tree() {
+    const all = [...this.#tasks.values()];
+    const byId = new Map(all.map(t => [t.id, t]));
+    const roots = [];
+    const orphans = [];
+    for (const t of all) {
+      if (!t.parentTaskId) roots.push(t);
+      else if (!byId.has(t.parentTaskId)) orphans.push(t);
+    }
+    return { roots, orphans };
+  }
+
   /**
    * Get progress log for a task.
    * @param {string} id
@@ -391,6 +436,75 @@ export class TaskStore {
       writeFileSync(this.#indexPath, generateIndex(this.#tasks), 'utf8');
     } catch { /* */ }
   }
+
+  /**
+   * task-299 Q3 migration — one-shot backfill from legacy `parentId` to
+   * canonical `parentTaskId` (design §5).
+   *
+   * Behaviour:
+   *   - Reads .migrations/parentTaskId meta marker. If present, returns
+   *     immediately (skips). → guarantees idempotency on repeated boots.
+   *   - Otherwise: for every loaded task, if parentId is set but
+   *     parentTaskId is not, copy parentId → parentTaskId and rewrite
+   *     task.md so the new field survives future loads.
+   *   - Writes the meta marker on success. Read-only mode is a no-op.
+   *
+   * Exposed publicly as `migrateParentTaskId()` so tests can re-run it.
+   *
+   * @returns {{ ran: boolean, migratedCount: number }}
+   */
+  migrateParentTaskId() {
+    return this.#migrateParentTaskId();
+  }
+
+  #migrateParentTaskId() {
+    if (this.#readOnly) return { ran: false, migratedCount: 0 };
+
+    const markerDir = join(this.#dir, '.migrations');
+    const markerPath = join(markerDir, 'parentTaskId');
+
+    try {
+      if (existsSync(markerPath)) return { ran: false, migratedCount: 0 };
+    } catch {
+      // If existsSync throws (pathological FS), proceed cautiously — the
+      // migration itself is idempotent on per-task level.
+    }
+
+    let migratedCount = 0;
+    for (const task of this.#tasks.values()) {
+      // parseTask() already promotes parentId → parentTaskId in memory,
+      // but the on-disk YAML still lacks the canonical field for old
+      // tasks. Rewriting guarantees future loads see parentTaskId and
+      // makes the migration visible.
+      if (task.parentId && !task.__parentTaskIdWritten) {
+        // Ensure the canonical field is set (parseTask normalised this,
+        // but handle the edge case where parseTask wasn't used).
+        if (!task.parentTaskId) task.parentTaskId = task.parentId;
+        const taskDir = join(this.#dir, task.id);
+        try {
+          writeFileSync(join(taskDir, 'task.md'), serializeTask(task), 'utf8');
+          task.__parentTaskIdWritten = true;
+          migratedCount += 1;
+        } catch {
+          // Best-effort; marker is only written if the pass completes.
+        }
+      }
+    }
+
+    try {
+      mkdirSync(markerDir, { recursive: true });
+      writeFileSync(
+        markerPath,
+        `migrated: ${new Date().toISOString()}\ncount: ${migratedCount}\n`,
+        'utf8',
+      );
+    } catch {
+      // Without the marker the migration may re-run; since it's idempotent
+      // that is acceptable but not ideal. Log silently.
+    }
+
+    return { ran: true, migratedCount };
+  }
 }
 
 // Exported for testing

package/unify/threads/engine-instance.js

@@ -0,0 +1,218 @@
+/**
+ * engine-instance.js — task-308 Phase 2.
+ *
+ * An EngineInstance binds a single `threadId` to an Engine + an independent
+ * per-thread `messages` array + an independent memory scope ref. Multiple
+ * EngineInstance objects can run .query() concurrently on the same unify
+ * session without cross-contaminating state:
+ *
+ *   - The underlying Engine's query loop is a pure async generator that
+ *     takes `messages` as a parameter — it holds no mutable turn state on
+ *     `this` during a run, so concurrent generators cannot alias each
+ *     other's conversation or tool-call arrays.
+ *   - All yielded events are re-tagged with the instance's bound
+ *     `threadId` (not with the global current-thread marker from the
+ *     singleton ThreadStore), so the web-bridge can route them to the
+ *     right pane even while several threads stream simultaneously.
+ *   - `messages` is owned by the instance: user/assistant messages
+ *     appended during a query are persisted to the instance's own array,
+ *     not to a global.
+ *
+ * Memory scope: Phase 2 design doc §6 — the memory store is shared across
+ * threads (one user, one brain), but the EngineInstance carries a
+ * `memoryScope` ref that can later be used to namespace recall/query
+ * results by thread. Today the ref is the threadId itself; downstream
+ * memory adapters can opt in.
+ *
+ * Q2 decision (PM brief): all threads use session primaryModel. No
+ * per-thread model override is accepted.
+ */
+
+import { Engine } from '../engine.js';
+import { MAIN_THREAD_ID } from './store.js';
+
+export class EngineInstance {
+  /** @type {string} */
+  #threadId;
+
+  /** @type {Engine} */
+  #engine;
+
+  /** @type {Array<object>} owned per-thread conversation messages */
+  #messages;
+
+  /** @type {string} memory scope ref — today simply the threadId */
+  #memoryScope;
+
+  /** @type {boolean} */
+  #terminated = false;
+
+  /**
+   * @param {{
+   *   threadId: string,
+   *   engine: Engine,
+   *   memoryScope?: string,
+   *   initialMessages?: Array<object>,
+   * }} params
+   */
+  constructor({ threadId, engine, memoryScope, initialMessages }) {
+    if (!threadId || typeof threadId !== 'string') {
+      throw new Error('EngineInstance: threadId is required');
+    }
+    if (!engine) {
+      throw new Error('EngineInstance: engine is required');
+    }
+    this.#threadId = threadId;
+    this.#engine = engine;
+    this.#memoryScope = memoryScope || threadId;
+    this.#messages = Array.isArray(initialMessages) ? [...initialMessages] : [];
+  }
+
+  /** @returns {string} */
+  get threadId() { return this.#threadId; }
+
+  /** @returns {string} */
+  get memoryScope() { return this.#memoryScope; }
+
+  /** @returns {boolean} */
+  get terminated() { return this.#terminated; }
+
+  /** Number of messages recorded on this instance. */
+  get messageCount() { return this.#messages.length; }
+
+  /** Snapshot of the current messages array (copy, safe for callers). */
+  get messages() { return [...this.#messages]; }
+
+  /** Underlying Engine (for tool registration, trace access, etc.). */
+  get engine() { return this.#engine; }
+
+  /**
+   * Run a query on this thread's engine. Yields events tagged with this
+   * instance's bound threadId. After the run, user + assistant messages
+   * are appended to the owned messages array.
+   *
+   * @param {object} params
+   * @param {string} params.prompt
+   * @param {'dream'} [params.mode]
+   * @param {AbortSignal} [params.signal]
+   * @yields {object} EngineEvent with { ...event, threadId }
+   */
+  async *query({ prompt, mode, signal }) {
+    if (this.#terminated) {
+      yield {
+        type: 'error',
+        threadId: this.#threadId,
+        error: new Error(`EngineInstance(${this.#threadId}) has been terminated`),
+        retryable: false,
+      };
+      return;
+    }
+
+    // Snapshot of messages passed to the engine; the engine treats this
+    // as read-only (it builds its own conversation array internally).
+    const snapshot = [...this.#messages];
+    let assistantText = '';
+    const assistantToolCalls = [];
+
+    for await (const event of this.#engine.query({ prompt, mode, messages: snapshot, signal })) {
+      // Re-tag every event with the bound threadId. Non-object events
+      // (shouldn't happen — all engine events are objects) are passed
+      // through untouched.
+      const tagged = event && typeof event === 'object'
+        ? { ...event, threadId: this.#threadId }
+        : event;
+      yield tagged;
+
+      // Track assistant reply to persist after stream ends. Only tag the
+      // natural stream types — not our injected turn_start/turn_end.
+      if (event && typeof event === 'object') {
+        if (event.type === 'text_delta' && typeof event.text === 'string') {
+          assistantText += event.text;
+        } else if (event.type === 'tool_call') {
+          assistantToolCalls.push({ id: event.id, name: event.name, input: event.input });
+        }
+      }
+    }
+
+    // Append user + assistant to the owned messages array so subsequent
+    // queries on this thread carry conversational context.
+    this.#messages.push({ role: 'user', content: prompt });
+    const assistantMsg = { role: 'assistant', content: assistantText };
+    if (assistantToolCalls.length > 0) {
+      assistantMsg.toolCalls = assistantToolCalls;
+    }
+    this.#messages.push(assistantMsg);
+  }
+
+  /**
+   * Terminate this engine instance. Further .query() calls will emit an
+   * error event and return early. Does NOT tear down the underlying
+   * Engine (engines are shared across instances via composition from
+   * the registry — only the instance's per-thread state is dropped).
+   */
+  terminate() {
+    this.#terminated = true;
+    this.#messages = [];
+  }
+
+  /**
+   * Reset the owned messages array. Used by the registry for crash
+   * recovery / test cleanup. Does NOT terminate the instance.
+   * @param {Array<object>} [messages=[]]
+   */
+  resetMessages(messages = []) {
+    this.#messages = Array.isArray(messages) ? [...messages] : [];
+  }
+}
+
+/**
+ * Factory helper — builds an EngineInstance that owns a fresh Engine,
+ * sharing the given dependency bag across all threads of a session.
+ *
+ * @param {{
+ *   threadId: string,
+ *   adapter: object,
+ *   trace: object,
+ *   config: object,
+ *   conversationStore?: object,
+ *   memoryStore?: object,
+ *   toolRegistry?: object,
+ *   skillManager?: object,
+ *   mcpManager?: object,
+ *   yeaftDir?: string,
+ *   initialMessages?: Array<object>,
+ * }} deps
+ * @returns {EngineInstance}
+ */
+export function createEngineInstance(deps) {
+  const {
+    threadId,
+    adapter,
+    trace,
+    config,
+    conversationStore,
+    memoryStore,
+    toolRegistry,
+    skillManager,
+    mcpManager,
+    yeaftDir,
+    initialMessages,
+  } = deps;
+  const engine = new Engine({
+    adapter,
+    trace,
+    config,
+    conversationStore,
+    memoryStore,
+    toolRegistry,
+    skillManager,
+    mcpManager,
+    yeaftDir,
+  });
+  return new EngineInstance({
+    threadId: threadId || MAIN_THREAD_ID,
+    engine,
+    memoryScope: threadId || MAIN_THREAD_ID,
+    initialMessages,
+  });
+}

package/unify/threads/engine-registry.js

@@ -0,0 +1,192 @@
+/**
+ * engine-registry.js — task-308 Phase 2.
+ *
+ * A ThreadEngineRegistry is a per-session Map<threadId, EngineInstance>.
+ * It owns instance lifecycles:
+ *
+ *   - `get(threadId)` returns the existing instance for a thread.
+ *   - `ensure(threadId, opts)` lazily creates one via the configured
+ *     factory if it does not yet exist. This is the primary entry point
+ *     for routing a user message to the correct thread engine.
+ *   - `listActive()` enumerates non-terminated instances, useful for
+ *     the web-bridge to show "active threads" indicators.
+ *   - `terminate(threadId)` tears down a single thread engine without
+ *     disturbing the rest.
+ *   - `terminateAll()` is called on session shutdown.
+ *
+ * The registry holds no LLM/tool state itself — it delegates to the
+ * factory, which in production will be the closure over the shared
+ * session deps (adapter, trace, config, stores, tool registry, …).
+ *
+ * Concurrency note: Node's single-threaded event loop means the
+ * registry's Map mutations are race-free. Concurrent .query() calls
+ * interleave only at await points, and each EngineInstance keeps its
+ * per-turn state inside the async generator's local scope, not on
+ * `this` — so two threads can stream simultaneously without stepping
+ * on each other.
+ */
+
+import { MAIN_THREAD_ID } from './store.js';
+import { createEngineInstance } from './engine-instance.js';
+
+export class ThreadEngineRegistry {
+  /** @type {Map<string, import('./engine-instance.js').EngineInstance>} */
+  #instances;
+
+  /** @type {(threadId: string, opts?: object) => import('./engine-instance.js').EngineInstance} */
+  #factory;
+
+  /** @type {string} */
+  #currentThreadId;
+
+  /**
+   * @param {{
+   *   factory: (threadId: string, opts?: object) => import('./engine-instance.js').EngineInstance,
+   * }} params
+   */
+  constructor({ factory } = {}) {
+    if (typeof factory !== 'function') {
+      throw new Error('ThreadEngineRegistry: factory function is required');
+    }
+    this.#instances = new Map();
+    this.#factory = factory;
+    this.#currentThreadId = MAIN_THREAD_ID;
+  }
+
+  /** @returns {string} */
+  get currentThreadId() { return this.#currentThreadId; }
+
+  /** Total number of registered (including terminated) instances. */
+  get size() { return this.#instances.size; }
+
+  /**
+   * Get an existing instance for a thread. Returns null if not yet
+   * created. Does NOT lazy-create — use ensure() for that.
+   * @param {string} threadId
+   */
+  get(threadId) {
+    return this.#instances.get(threadId) || null;
+  }
+
+  /**
+   * Lazy-get-or-create an instance for a thread. If one already exists
+   * and is not terminated, it is returned; if it was terminated, a new
+   * one replaces it. Any `opts` are forwarded to the factory.
+   *
+   * @param {string} threadId
+   * @param {object} [opts]
+   * @returns {import('./engine-instance.js').EngineInstance}
+   */
+  ensure(threadId, opts) {
+    if (!threadId || typeof threadId !== 'string') {
+      throw new Error('ThreadEngineRegistry.ensure: threadId required');
+    }
+    const existing = this.#instances.get(threadId);
+    if (existing && !existing.terminated) return existing;
+    const instance = this.#factory(threadId, opts);
+    if (!instance || typeof instance.query !== 'function') {
+      throw new Error(`ThreadEngineRegistry.ensure: factory did not return an EngineInstance for ${threadId}`);
+    }
+    this.#instances.set(threadId, instance);
+    return instance;
+  }
+
+  /**
+   * Set the current thread marker. Does not lazy-create — caller must
+   * ensure() if they want an instance for an unseen thread.
+   * @param {string} threadId
+   */
+  setCurrent(threadId) {
+    if (!threadId || typeof threadId !== 'string') {
+      throw new Error('ThreadEngineRegistry.setCurrent: threadId required');
+    }
+    this.#currentThreadId = threadId;
+  }
+
+  /**
+   * List all non-terminated instances. The order is insertion order.
+   * @returns {Array<import('./engine-instance.js').EngineInstance>}
+   */
+  listActive() {
+    const out = [];
+    for (const inst of this.#instances.values()) {
+      if (!inst.terminated) out.push(inst);
+    }
+    return out;
+  }
+
+  /**
+   * All instances including terminated ones (for inspection / tests).
+   * @returns {Array<import('./engine-instance.js').EngineInstance>}
+   */
+  listAll() {
+    return [...this.#instances.values()];
+  }
+
+  /**
+   * Terminate a single thread's instance. Safe on unknown threadId.
+   * @param {string} threadId
+   * @returns {boolean} true if a live instance was terminated
+   */
+  terminate(threadId) {
+    const inst = this.#instances.get(threadId);
+    if (!inst) return false;
+    if (inst.terminated) return false;
+    inst.terminate();
+    return true;
+  }
+
+  /**
+   * Terminate all instances. Used on session shutdown.
+   * @returns {number} count terminated
+   */
+  terminateAll() {
+    let n = 0;
+    for (const inst of this.#instances.values()) {
+      if (!inst.terminated) {
+        inst.terminate();
+        n += 1;
+      }
+    }
+    return n;
+  }
+
+  /**
+   * Remove a thread's instance from the map entirely. The registry
+   * will no longer return it from listAll / listActive. Primarily used
+   * after terminate() when the caller wants a full forget.
+   * @param {string} threadId
+   * @returns {boolean}
+   */
+  delete(threadId) {
+    const inst = this.#instances.get(threadId);
+    if (!inst) return false;
+    if (!inst.terminated) inst.terminate();
+    return this.#instances.delete(threadId);
+  }
+}
+
+/**
+ * Build a registry whose factory constructs full Engine instances using
+ * a shared dependency bag. This is the production entry point used by
+ * session.js:
+ *
+ *   const registry = createThreadEngineRegistry({
+ *     adapter, trace, config, conversationStore, memoryStore,
+ *     toolRegistry, skillManager, mcpManager, yeaftDir,
+ *   });
+ *   const inst = registry.ensure(threadId);
+ *   for await (const event of inst.query({ prompt })) { ... }
+ *
+ * @param {object} deps — shared session deps (see session.js §9)
+ * @returns {ThreadEngineRegistry}
+ */
+export function createThreadEngineRegistry(deps) {
+  return new ThreadEngineRegistry({
+    factory: (threadId, opts = {}) => createEngineInstance({
+      ...deps,
+      ...opts,
+      threadId,
+    }),
+  });
+}

package/unify/threads/store.js

@@ -6,8 +6,14 @@
  * filesystem layer is merged. When task-298 merges, this module will be
  * replaced (or promoted to a shim) by a file-backed store with the same API.
  *
+ * Cached fields (task-299 rework, prev-2 suggestion):
+ *   - messageCount, lastMessageAt, archived are maintained incrementally via
+ *     noteMessage()/archive()/setStatus() so that ListThreads does NOT need
+ *     to scan every message on each call. A rebuildFromMessages(messages)
+ *     helper exists for sanity / crash-recovery reconciliation.
+ *
  * Responsibilities (Phase 1):
- *   - Maintain a map of threadId → thread metadata.
+ *   - Maintain a map of threadId → thread metadata + cached counters.
  *   - Track a "currentThreadId" marker for the engine.
  *   - Maintain attachments from threadId → taskId.
  *
@@ -20,12 +26,19 @@ import { randomUUID } from 'crypto';
 /** Default / root thread id — every fresh ThreadStore has one. */
 export const MAIN_THREAD_ID = 'main';
 
+/** Valid thread status values. Mirrors design doc §5. */
+export const THREAD_STATUSES = ['active', 'idle', 'archived'];
+
 /**
  * @typedef {Object} Thread
  * @property {string} id
  * @property {string} name
  * @property {string} [goal]
  * @property {string|null} parentThreadId
+ * @property {'active'|'idle'|'archived'} status — cached; initial 'active'
+ * @property {number} messageCount — cached counter, incremented via noteMessage
+ * @property {number|null} lastMessageAt — cached timestamp of last noted message
+ * @property {boolean} archived — convenience mirror of (status === 'archived')
  * @property {number} createdAt
  * @property {number} updatedAt
  */
@@ -45,16 +58,29 @@ export class ThreadStore {
     this.#attachments = new Map();
 
     const now = Date.now();
-    const main = {
+    this.#threads.set(MAIN_THREAD_ID, this.#newThreadRecord({
       id: MAIN_THREAD_ID,
       name: 'main',
       goal: '',
       parentThreadId: null,
       createdAt: now,
       updatedAt: now,
+    }));
+    this.#currentId = MAIN_THREAD_ID;
+  }
+
+  /** Internal: build a thread record with default cached fields. */
+  #newThreadRecord(base) {
+    return {
+      status: 'active',
+      messageCount: 0,
+      lastMessageAt: null,
+      lastActivityAt: null, // task-300 sidebar: latest of lastMessageAt/updatedAt
+      archived: false,
+      unread: 0,            // task-300 sidebar: messages since last read marker
+      preview: '',          // task-300 sidebar: short excerpt of latest content
+      ...base,
     };
-    this.#threads.set(main.id, main);
-    this.#currentId = main.id;
   }
 
   /** Get current thread id (defaults to 'main'). */
@@ -81,14 +107,14 @@ export class ThreadStore {
     }
     const id = `thr-${randomUUID().slice(0, 8)}`;
     const now = Date.now();
-    const thread = {
+    const thread = this.#newThreadRecord({
       id,
       name: name.trim(),
       goal: goal || '',
       parentThreadId: parentThreadId || null,
       createdAt: now,
       updatedAt: now,
-    };
+    });
     this.#threads.set(id, thread);
     return thread;
   }
@@ -121,6 +147,112 @@ export class ThreadStore {
     t.updatedAt = Date.now();
   }
 
+  /**
+   * Record that a message has been persisted on a thread. Increments the
+   * cached messageCount and updates lastMessageAt. Safe to call repeatedly;
+   * unknown threadIds are silently ignored (defense: bookkeeping must never
+   * block the main persist path).
+   *
+   * @param {string} threadId
+   * @param {number} [at=Date.now()]
+   */
+  noteMessage(threadId, at = Date.now(), opts = {}) {
+    const t = this.#threads.get(threadId);
+    if (!t) return;
+    t.messageCount += 1;
+    t.lastMessageAt = at;
+    t.lastActivityAt = at;
+    t.updatedAt = at;
+    // task-300 sidebar unread counter: any new message not originating from the
+    // user themselves counts as unread until markRead() is called. Callers may
+    // pass { countsAsUnread: false } (e.g. for user's own messages).
+    if (opts.countsAsUnread !== false) {
+      t.unread += 1;
+    }
+    // Short preview for sidebar hover / list (capped at 160 chars).
+    if (typeof opts.preview === 'string' && opts.preview.length > 0) {
+      const p = opts.preview.replace(/\s+/g, ' ').trim();
+      t.preview = p.length > 160 ? p.slice(0, 157) + '...' : p;
+    }
+    // Any activity bumps archived back to active.
+    if (t.status === 'archived') {
+      t.status = 'active';
+      t.archived = false;
+    }
+  }
+
+  /**
+   * Mark a thread as read — resets unread counter to 0. Safe on unknown id.
+   * @param {string} threadId
+   */
+  markRead(threadId) {
+    const t = this.#threads.get(threadId);
+    if (!t) return;
+    t.unread = 0;
+  }
+
+  /**
+   * Mark a thread archived. 'main' cannot be archived.
+   * @param {string} id
+   */
+  archive(id) {
+    const t = this.#threads.get(id);
+    if (!t) throw new Error(`thread not found: ${id}`);
+    if (id === MAIN_THREAD_ID) throw new Error('cannot archive main thread');
+    t.status = 'archived';
+    t.archived = true;
+    t.updatedAt = Date.now();
+  }
+
+  /**
+   * Set thread status explicitly. Must be one of THREAD_STATUSES.
+   * @param {string} id
+   * @param {'active'|'idle'|'archived'} status
+   */
+  setStatus(id, status) {
+    if (!THREAD_STATUSES.includes(status)) {
+      throw new Error(`invalid status: ${status}`);
+    }
+    const t = this.#threads.get(id);
+    if (!t) throw new Error(`thread not found: ${id}`);
+    if (id === MAIN_THREAD_ID && status === 'archived') {
+      throw new Error('cannot archive main thread');
+    }
+    t.status = status;
+    t.archived = status === 'archived';
+    t.updatedAt = Date.now();
+  }
+
+  /**
+   * Rebuild cached fields (messageCount/lastMessageAt) from a flat messages
+   * list. Used for crash recovery or as a sanity check in tests. Each
+   * message must have { threadId, createdAt? }; missing threadId is treated
+   * as MAIN_THREAD_ID (matches design doc §5 default).
+   *
+   * Counts per thread are reset to zero first to guarantee idempotency.
+   *
+   * @param {Array<{threadId?: string, createdAt?: number}>} messages
+   */
+  rebuildFromMessages(messages) {
+    // Reset counters
+    for (const t of this.#threads.values()) {
+      t.messageCount = 0;
+      t.lastMessageAt = null;
+      t.lastActivityAt = null;
+    }
+    for (const m of messages || []) {
+      const tid = m.threadId || MAIN_THREAD_ID;
+      const t = this.#threads.get(tid);
+      if (!t) continue;
+      t.messageCount += 1;
+      const ts = typeof m.createdAt === 'number' ? m.createdAt : Date.now();
+      if (!t.lastMessageAt || ts > t.lastMessageAt) {
+        t.lastMessageAt = ts;
+        t.lastActivityAt = ts;
+      }
+    }
+  }
+
   /**
    * Attach a task to a thread. Overwrites any existing attachment.
    * @param {string} threadId

package/unify/tools/index.js

@@ -61,8 +61,10 @@ import {
   switchThread,
   listThreads,
   attachThreadToTask,
+  spawnTask,
+  readThreadSummary,
+  readThreadRecent,
 } from './thread-tools.js';
-import { spawnTask, spawnSubtask } from './spawn-task-tools.js';
 
 // --- P2 Auxiliary tools ---
 import { jsRepl, jsReplReset } from './js-repl.js';
@@ -128,7 +130,8 @@ export const allTools = [
   listThreads,
   attachThreadToTask,
   spawnTask,
-  spawnSubtask,
+  readThreadSummary,
+  readThreadRecent,
 
   // P2 Auxiliary
   jsRepl,

package/unify/tools/thread-tools.js

@@ -1,20 +1,25 @@
 /**
  * thread-tools.js — Thread-spawning tools for Unify Engine (Phase 1).
  *
- * Phase 1 scope (task-299):
- *   - SpawnThread        — create a new thread
- *   - SwitchThread       — set the engine's currentThreadId marker
- *   - ListThreads        — list threads + current marker
- *   - AttachThreadToTask — bind a thread to an existing task
+ * Phase 1 scope (task-299 rework):
+ *   - SpawnThread         — create a new thread
+ *   - SwitchThread        — set the engine's currentThreadId marker
+ *   - ListThreads         — list threads + current marker + cached stats
+ *   - AttachThreadToTask  — bind a thread to an existing task
+ *   - SpawnTask           — create a task or subtask (parent_task_id optional)
+ *   - ReadThreadSummary   — cross-reference: summary of a thread (id/name/
+ *                           status/messageCount/lastMessageAt/task)
+ *   - ReadThreadRecent    — cross-reference: last N messages of a thread
  *
  * Phase 1 uses the in-memory ThreadStore (agent/unify/threads/store.js)
- * so these tools can ship and be tested before task-298's file-backed
- * data layer merges. The tool surface is designed to remain stable when
- * the store is replaced.
+ * and the existing ConversationStore for messages. When task-298 merges,
+ * ThreadStore becomes file-backed with the SAME API, so these tools
+ * continue to work unchanged.
  */
 
 import { defineTool } from './types.js';
-import { getThreadStore } from '../threads/store.js';
+import { randomUUID } from 'crypto';
+import { getThreadStore, MAIN_THREAD_ID } from '../threads/store.js';
 import { getTaskStore } from './task-tools.js';
 
 // ─── SpawnThread ─────────────────────────────────────────
@@ -57,6 +62,7 @@ engine to the new thread — call SwitchThread to activate it.`,
           name: t.name,
           goal: t.goal,
           parentThreadId: t.parentThreadId,
+          status: t.status,
         },
         message: `Thread created: ${t.name} (${t.id})`,
       });
@@ -107,7 +113,12 @@ thread.`,
 
 export const listThreads = defineTool({
   name: 'ListThreads',
-  description: `List all threads and the engine's current thread marker.`,
+  description: `List all threads with cached status / messageCount / lastMessageAt.
+
+Returns the data needed by the Phase 2 sidebar (task-300): each entry
+exposes id, name, goal, parentThreadId, status ('active'|'idle'|'archived'),
+messageCount, lastMessageAt, archived, attachedTaskId. Reads only cached
+fields — does not scan messages.`,
   parameters: { type: 'object', properties: {} },
   modes: ['work'],
   isConcurrencySafe: () => true,
@@ -119,6 +130,13 @@ export const listThreads = defineTool({
       name: t.name,
       goal: t.goal,
       parentThreadId: t.parentThreadId,
+      status: t.status,
+      messageCount: t.messageCount,
+      lastMessageAt: t.lastMessageAt,
+      lastActivityAt: t.lastActivityAt ?? t.lastMessageAt,
+      archived: t.archived,
+      unread: t.unread || 0,
+      preview: t.preview || '',
       attachedTaskId: store.attachedTask(t.id),
     }));
     return JSON.stringify(
@@ -159,9 +177,6 @@ the same thread.`,
     if (!task_id) return JSON.stringify({ error: 'task_id is required' });
 
     const taskStore = getTaskStore();
-    // If the task store is initialized, validate the task exists; if not
-    // initialized (e.g. Phase 1 unit tests running before session bootstrap),
-    // skip the task existence check — we still enforce thread existence.
     if (taskStore) {
       const task = taskStore.get(task_id);
       if (!task) return JSON.stringify({ error: `Task not found: ${task_id}` });
@@ -181,3 +196,175 @@ the same thread.`,
     }
   },
 });
+
+// ─── SpawnTask (merged — subtask via parent_task_id) ────
+
+/**
+ * SpawnTask replaces both the old SpawnTask and the separate SpawnSubtask:
+ * pass `parent_task_id` when you want a subtask, omit it for top-level.
+ * Per prev-1 rework note: eliminating two tools with the same effect.
+ */
+export const spawnTask = defineTool({
+  name: 'SpawnTask',
+  description: `Spawn a new task. Pass parent_task_id to create a subtask.
+
+When parent_task_id is omitted → top-level task.
+When parent_task_id is provided → subtask under that parent (parent must exist).
+This replaces the deprecated SpawnSubtask tool.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      title: { type: 'string' },
+      description: { type: 'string' },
+      priority: {
+        type: 'string',
+        enum: ['low', 'medium', 'high', 'critical'],
+      },
+      parent_task_id: {
+        type: 'string',
+        description: 'Optional parent task id; when present, a subtask is created',
+      },
+    },
+    required: ['title'],
+  },
+  modes: ['work'],
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  async execute(input) {
+    const store = getTaskStore();
+    if (!store) {
+      return JSON.stringify({ error: 'Task store not initialized. Session may still be loading.' });
+    }
+    const { title, description = '', priority = 'medium', parent_task_id } = input || {};
+    if (!title) return JSON.stringify({ error: 'title is required' });
+
+    if (parent_task_id) {
+      const parent = store.get(parent_task_id);
+      if (!parent) return JSON.stringify({ error: `Parent task not found: ${parent_task_id}` });
+    }
+
+    const id = `task-${randomUUID().slice(0, 8)}`;
+    const now = Date.now();
+    store.create({
+      id,
+      title,
+      description,
+      priority,
+      status: 'pending',
+      parentId: parent_task_id || null,
+      parentTaskId: parent_task_id || null, // design §5 canonical field; kept in sync with parentId
+      createdAt: now,
+      updatedAt: now,
+    });
+    return JSON.stringify({
+      success: true,
+      task: {
+        id,
+        title,
+        priority,
+        status: 'pending',
+        parentTaskId: parent_task_id || null,
+      },
+      message: parent_task_id
+        ? `Subtask spawned: ${title} (${id}) under ${parent_task_id}`
+        : `Task spawned: ${title} (${id})`,
+    });
+  },
+});
+
+// ─── ReadThreadSummary (cross-reference, design §6 Q5) ──
+
+export const readThreadSummary = defineTool({
+  name: 'ReadThreadSummary',
+  description: `Return a one-shot summary of a thread: id, name, goal, status,
+messageCount, lastMessageAt, parentThreadId, attachedTaskId.
+
+Use this to cross-reference work on another thread without switching.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      thread_id: { type: 'string' },
+    },
+    required: ['thread_id'],
+  },
+  modes: ['work'],
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input) {
+    const { thread_id } = input || {};
+    if (!thread_id) return JSON.stringify({ error: 'thread_id is required' });
+    const store = getThreadStore();
+    const t = store.get(thread_id);
+    if (!t) return JSON.stringify({ error: `Thread not found: ${thread_id}` });
+    return JSON.stringify(
+      {
+        id: t.id,
+        name: t.name,
+        goal: t.goal,
+        status: t.status,
+        archived: t.archived,
+        messageCount: t.messageCount,
+        lastMessageAt: t.lastMessageAt,
+        parentThreadId: t.parentThreadId,
+        attachedTaskId: store.attachedTask(t.id),
+        createdAt: t.createdAt,
+        updatedAt: t.updatedAt,
+      },
+      null,
+      2,
+    );
+  },
+});
+
+// ─── ReadThreadRecent (cross-reference, design §6 Q5) ───
+
+export const readThreadRecent = defineTool({
+  name: 'ReadThreadRecent',
+  description: `Return the last N messages on a specific thread.
+
+Requires an engine ConversationStore in context (ctx.conversationStore).
+Reads conversation history and filters by threadId. Default N=20, max 200.
+Use this to review another thread's recent activity without switching.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      thread_id: { type: 'string' },
+      limit: { type: 'number', description: 'Max messages to return (default 20, max 200)' },
+    },
+    required: ['thread_id'],
+  },
+  modes: ['work'],
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const { thread_id, limit } = input || {};
+    if (!thread_id) return JSON.stringify({ error: 'thread_id is required' });
+    const store = getThreadStore();
+    if (!store.has(thread_id)) {
+      return JSON.stringify({ error: `Thread not found: ${thread_id}` });
+    }
+    const conv = ctx?.conversationStore;
+    if (!conv || typeof conv.loadRecent !== 'function') {
+      return JSON.stringify({
+        error: 'conversation store unavailable in tool context',
+      });
+    }
+    const cap = Math.max(1, Math.min(Number(limit) || 20, 200));
+    // Over-fetch then filter by thread, so N still applies post-filter.
+    const raw = conv.loadRecent(cap * 4);
+    const filtered = raw
+      .filter(m => (m.threadId || MAIN_THREAD_ID) === thread_id)
+      .slice(-cap)
+      .map(m => ({
+        role: m.role,
+        content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+        createdAt: m.createdAt || null,
+        threadId: m.threadId || MAIN_THREAD_ID,
+      }));
+    return JSON.stringify(
+      { threadId: thread_id, count: filtered.length, messages: filtered },
+      null,
+      2,
+    );
+  },
+});

package/unify/tools/types.js

@@ -24,7 +24,9 @@
  * @property {string} description — LLM-facing description
  * @property {object} parameters — JSON Schema for input
  * @property {(input: object, ctx?: ToolContext) => Promise<string>} execute — execution function
- * @property {string[]} modes — which modes can use this tool: ['chat', 'work']
+ * @property {string[]} [modes] — @deprecated since task-297. Legacy mode filter (['chat', 'work']).
+ *   Unify no longer has mode distinction; the ToolRegistry ignores this field and exposes every
+ *   registered tool to the engine. Retained only so existing tool definitions keep loading.
  * @property {(input?: object) => boolean} [isConcurrencySafe] — can run in parallel?
  * @property {(input?: object) => boolean} [isReadOnly] — read-only operation?
  * @property {(input?: object) => boolean} [isDestructive] — destructive operation?
@@ -38,7 +40,7 @@
  *   description: string,
  *   parameters: object,
  *   execute: (input: object, ctx?: ToolContext) => Promise<string>,
- *   modes?: string[],
+ *   modes?: string[],  // @deprecated since task-297 — ignored by ToolRegistry
  *   isConcurrencySafe?: (input?: object) => boolean,
  *   isReadOnly?: (input?: object) => boolean,
  *   isDestructive?: (input?: object) => boolean,

package/unify/tools/spawn-task-tools.js

@@ -1,125 +0,0 @@
-/**
- * spawn-task-tools.js — Thin semantic-sugar wrappers over TaskCreate.
- *
- * Phase 1 of task-299: expose `SpawnTask` and `SpawnSubtask` as first-class
- * tool names so the LLM can "spawn" work items in the same vocabulary it
- * uses to spawn threads. Both delegate to the existing TaskStore (shared
- * with TaskCreate), so there is a single source of truth for task data.
- */
-
-import { defineTool } from './types.js';
-import { randomUUID } from 'crypto';
-import { getTaskStore } from './task-tools.js';
-
-function requireStore() {
-  const store = getTaskStore();
-  if (!store) return { error: 'Task store not initialized. Session may still be loading.' };
-  return { store };
-}
-
-function newTaskId() {
-  return `task-${randomUUID().slice(0, 8)}`;
-}
-
-// ─── SpawnTask ──────────────────────────────────────────
-
-export const spawnTask = defineTool({
-  name: 'SpawnTask',
-  description: `Spawn a new top-level task.
-
-Equivalent to TaskCreate without a parent. Provided as a first-class
-name so tasks and threads can be "spawned" with a uniform vocabulary.`,
-  parameters: {
-    type: 'object',
-    properties: {
-      title: { type: 'string' },
-      description: { type: 'string' },
-      priority: {
-        type: 'string',
-        enum: ['low', 'medium', 'high', 'critical'],
-      },
-    },
-    required: ['title'],
-  },
-  modes: ['work'],
-  isConcurrencySafe: () => false,
-  isReadOnly: () => false,
-  async execute(input) {
-    const got = requireStore();
-    if (got.error) return JSON.stringify({ error: got.error });
-    const { title, description = '', priority = 'medium' } = input || {};
-    if (!title) return JSON.stringify({ error: 'title is required' });
-
-    const id = newTaskId();
-    const now = Date.now();
-    got.store.create({
-      id,
-      title,
-      description,
-      priority,
-      status: 'pending',
-      parentId: null,
-      createdAt: now,
-      updatedAt: now,
-    });
-    return JSON.stringify({
-      success: true,
-      task: { id, title, priority, status: 'pending' },
-      message: `Task spawned: ${title} (${id})`,
-    });
-  },
-});
-
-// ─── SpawnSubtask ───────────────────────────────────────
-
-export const spawnSubtask = defineTool({
-  name: 'SpawnSubtask',
-  description: `Spawn a subtask under an existing parent task.
-
-Requires parent_task_id. The parent must exist. Use for breaking a
-larger task into executable pieces.`,
-  parameters: {
-    type: 'object',
-    properties: {
-      parent_task_id: { type: 'string' },
-      title: { type: 'string' },
-      description: { type: 'string' },
-      priority: {
-        type: 'string',
-        enum: ['low', 'medium', 'high', 'critical'],
-      },
-    },
-    required: ['parent_task_id', 'title'],
-  },
-  modes: ['work'],
-  isConcurrencySafe: () => false,
-  isReadOnly: () => false,
-  async execute(input) {
-    const got = requireStore();
-    if (got.error) return JSON.stringify({ error: got.error });
-    const { parent_task_id, title, description = '', priority = 'medium' } = input || {};
-    if (!parent_task_id) return JSON.stringify({ error: 'parent_task_id is required' });
-    if (!title) return JSON.stringify({ error: 'title is required' });
-
-    const parent = got.store.get(parent_task_id);
-    if (!parent) return JSON.stringify({ error: `Parent task not found: ${parent_task_id}` });
-
-    const id = newTaskId();
-    const now = Date.now();
-    got.store.create({
-      id,
-      title,
-      description: description || `Subtask of: ${parent.title}`,
-      priority,
-      status: 'pending',
-      parentId: parent_task_id,
-      createdAt: now,
-      updatedAt: now,
-    });
-    return JSON.stringify({
-      success: true,
-      task: { id, title, priority, status: 'pending', parentId: parent_task_id },
-      message: `Subtask spawned: ${title} (${id}) under ${parent_task_id}`,
-    });
-  },
-});