@yeaft/webchat-agent 0.1.480 → 0.1.481

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.481",
   "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/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/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}`,
-    });
-  },
-});