@yeaft/webchat-agent 0.1.483 → 0.1.485

package/package.json

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

package/unify/session.js

@@ -125,9 +125,9 @@ export async function loadSession(options = {}) {
   initTaskStore(yeaftDir, { readOnly: config._readOnly || false });
 
   // ─── 5b. Initialize thread store (task-299 Phase 1) ────
-  //         In-memory only for Phase 1; replaced by a file-backed store
-  //         when task-298's data layer merges.
-  initThreadStore();
+  //         task-307a: now file-backed under ~/.yeaft/threads/. Passing the
+  //         yeaftDir switches on disk persistence; read-only mode is honoured.
+  initThreadStore(yeaftDir, { readOnly: config._readOnly || false, force: true });
 
   // ─── 6. Load skills ────────────────────────────────────
   let skillManager;

package/unify/threads/store.js

@@ -1,26 +1,49 @@
 /**
- * store.js — In-memory ThreadStore for Yeaft Unify (Phase 1 mock).
+ * store.js — File-backed ThreadStore for Yeaft Unify (task-307a).
  *
- * Phase 1 intentionally keeps the implementation in-memory only: it lets the
- * thread/task spawn tools ship and be tested before task-298's real
- * 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.
+ * Promotes the Phase-1 in-memory stub to persist threads under
+ * `~/.yeaft/threads/` so conversation structure survives agent restarts.
+ * API is backward compatible with the task-299 canonical surface — callers
+ * that used the in-memory version keep working without change, but a new
+ * optional `yeaftDir` argument (to the constructor / `initThreadStore`)
+ * switches persistence on.
  *
- * 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.
+ * On-disk layout:
+ *   ~/.yeaft/threads/
+ *     index.md                — Auto-generated overview (current thread id
+ *                               + attachments table + thread summary list).
+ *     {threadId}.md           — One markdown file per thread. YAML
+ *                               frontmatter holds every cached field, the
+ *                               body is the short preview.
  *
- * Responsibilities (Phase 1):
- *   - Maintain a map of threadId → thread metadata + cached counters.
- *   - Track a "currentThreadId" marker for the engine.
- *   - Maintain attachments from threadId → taskId.
+ * Write semantics:
+ *   - Every mutation schedules a debounced flush (8 ms) of the set of dirty
+ *     thread files and, when something changed, the index. A synchronous
+ *     `flush()` is exposed for tests and graceful shutdown.
+ *   - On construction we load any existing `{id}.md` files and rebuild the
+ *     in-memory map + attachments, so round-trips are a simple "close /
+ *     reopen".
+ *   - Read-only mode (e.g. when `~/.yeaft/` is not writable) silently skips
+ *     all filesystem writes — in-memory behaviour is preserved.
  *
- * A single "main" thread is created on construction so that pre-spawn
- * messages have a valid threadId to carry.
+ * Cached fields (task-299 contract, preserved verbatim):
+ *   messageCount / lastMessageAt / lastActivityAt / archived / unread /
+ *   preview. These all persist to the YAML frontmatter so ListThreads never
+ *   needs to scan messages after a restart.
+ *
+ * A single "main" thread is always present after init — either loaded from
+ * disk or synthesised as a fresh record when the directory is empty.
  */
 
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
 import { randomUUID } from 'crypto';
 
 /** Default / root thread id — every fresh ThreadStore has one. */
@@ -29,16 +52,170 @@ export const MAIN_THREAD_ID = 'main';
 /** Valid thread status values. Mirrors design doc §5. */
 export const THREAD_STATUSES = ['active', 'idle', 'archived'];
 
+/** Debounce window for grouped disk writes. Kept short so tests don't hang. */
+const FLUSH_DEBOUNCE_MS = 8;
+
+// ─── YAML (de)serialisation ──────────────────────────────────────────────
+
+/**
+ * Serialise a thread record to Markdown with YAML frontmatter.
+ *
+ * Only scalar / boolean / number / null frontmatter values are emitted.
+ * Strings that span multiple lines or contain leading whitespace get folded
+ * into a single-line value (threads' free-text goes in the body).
+ *
+ * @param {object} t
+ * @returns {string}
+ */
+function serializeThread(t) {
+  const fm = [
+    '---',
+    `id: ${t.id}`,
+    `name: ${escapeScalar(t.name)}`,
+    `goal: ${escapeScalar(t.goal || '')}`,
+    `parentThreadId: ${t.parentThreadId == null ? 'null' : t.parentThreadId}`,
+    `status: ${t.status}`,
+    `archived: ${t.archived ? 'true' : 'false'}`,
+    `messageCount: ${t.messageCount | 0}`,
+    `lastMessageAt: ${t.lastMessageAt == null ? 'null' : t.lastMessageAt}`,
+    `lastActivityAt: ${t.lastActivityAt == null ? 'null' : t.lastActivityAt}`,
+    `unread: ${t.unread | 0}`,
+    `createdAt: ${t.createdAt}`,
+    `updatedAt: ${t.updatedAt}`,
+    '---',
+    '',
+  ];
+  // Body is the preview (wrapped so the file remains human-readable).
+  if (t.preview) fm.push(t.preview);
+  return fm.join('\n') + '\n';
+}
+
+function escapeScalar(v) {
+  if (v == null) return '';
+  // Keep on one physical line; any embedded newline becomes a space so YAML
+  // stays flat.
+  return String(v).replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Parse the markdown-with-frontmatter produced by `serializeThread`. Returns
+ * null when the file is malformed; callers should skip it silently so one
+ * corrupt thread file never blocks recovery of the rest.
+ *
+ * @param {string} raw
+ * @returns {object|null}
+ */
+function parseThread(raw) {
+  if (!raw || !raw.startsWith('---')) return null;
+  const end = raw.indexOf('\n---', 3);
+  if (end === -1) return null;
+  const fm = raw.slice(3, end).trim();
+  const body = raw.slice(end + 4).replace(/^\n/, '').trimEnd();
+  const record = {};
+  for (const line of fm.split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const rawVal = line.slice(idx + 1).trim();
+    if (!key) continue;
+    if (rawVal === 'null' || rawVal === '') {
+      record[key] = null;
+    } else if (rawVal === 'true' || rawVal === 'false') {
+      record[key] = rawVal === 'true';
+    } else if (/^-?\d+$/.test(rawVal)) {
+      record[key] = parseInt(rawVal, 10);
+    } else {
+      record[key] = rawVal;
+    }
+  }
+  if (!record.id || !record.name) return null;
+  // Default to safe values if the file pre-dates a field.
+  if (!THREAD_STATUSES.includes(record.status)) record.status = 'active';
+  record.archived = record.status === 'archived';
+  record.messageCount = Number.isFinite(record.messageCount) ? record.messageCount : 0;
+  record.unread = Number.isFinite(record.unread) ? record.unread : 0;
+  record.preview = body;
+  record.lastActivityAt = record.lastActivityAt ?? record.lastMessageAt ?? null;
+  return record;
+}
+
+/**
+ * Generate `index.md` — a human-readable roll-up of all threads in the
+ * store, the current thread marker, and attachments. Parsers should NOT
+ * depend on this file; it exists for human inspection and crash-triage.
+ */
+function generateIndex(threads, currentId, attachments) {
+  const now = new Date().toISOString();
+  const lines = [
+    '---',
+    `currentId: ${currentId}`,
+    `totalThreads: ${threads.size}`,
+    `lastUpdated: ${now}`,
+    '---',
+    '# Thread Index',
+    '',
+    '| ID | Name | Status | Messages | Last Activity |',
+    '|----|------|--------|----------|---------------|',
+  ];
+  for (const t of threads.values()) {
+    const stamp = t.lastActivityAt
+      ? new Date(t.lastActivityAt).toISOString().slice(0, 19).replace('T', ' ')
+      : '-';
+    lines.push(`| ${t.id} | ${t.name} | ${t.status} | ${t.messageCount} | ${stamp} |`);
+  }
+  if (attachments.size > 0) {
+    lines.push('');
+    lines.push('## Attachments');
+    lines.push('');
+    lines.push('| Thread | Task |');
+    lines.push('|--------|------|');
+    for (const [threadId, taskId] of attachments.entries()) {
+      lines.push(`| ${threadId} | ${taskId} |`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Serialise the attachments map to a stable JSON payload (array form so key
+ * order is preserved on reload). Stored separately from `index.md` so the
+ * human-readable index stays cosmetic.
+ */
+function serializeAttachments(attachments) {
+  return JSON.stringify(
+    [...attachments.entries()].map(([threadId, taskId]) => ({ threadId, taskId })),
+    null,
+    2,
+  ) + '\n';
+}
+
+function parseAttachments(raw) {
+  try {
+    const arr = JSON.parse(raw);
+    if (!Array.isArray(arr)) return [];
+    return arr.filter(
+      (e) => e && typeof e.threadId === 'string' && typeof e.taskId === 'string',
+    );
+  } catch {
+    return [];
+  }
+}
+
+// ─── ThreadStore class ───────────────────────────────────────────────────
+
 /**
  * @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 {'active'|'idle'|'archived'} status
+ * @property {number} messageCount
+ * @property {number|null} lastMessageAt
+ * @property {number|null} lastActivityAt
+ * @property {boolean} archived
+ * @property {number} unread
+ * @property {string} preview
  * @property {number} createdAt
  * @property {number} updatedAt
  */
@@ -46,53 +223,243 @@ export const THREAD_STATUSES = ['active', 'idle', 'archived'];
 export class ThreadStore {
   /** @type {Map<string, Thread>} */
   #threads;
-
   /** @type {string} */
   #currentId;
-
   /** @type {Map<string, string>} threadId → taskId */
   #attachments;
 
-  constructor() {
+  /** @type {string|null} */
+  #dir;
+  /** @type {string|null} */
+  #indexPath;
+  /** @type {string|null} */
+  #attachmentsPath;
+  /** @type {boolean} */
+  #readOnly;
+  /** @type {Set<string>} dirty thread ids pending flush */
+  #dirtyThreads;
+  /** @type {boolean} */
+  #dirtyIndex;
+  /** @type {boolean} */
+  #dirtyAttachments;
+  /** @type {any} NodeJS.Timeout */
+  #flushTimer;
+
+  /**
+   * @param {string} [yeaftDir] — Base ~/.yeaft directory. Omit for in-memory mode.
+   * @param {{ readOnly?: boolean }} [opts]
+   */
+  constructor(yeaftDir, opts = {}) {
     this.#threads = new Map();
     this.#attachments = new Map();
-
-    const now = Date.now();
-    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;
+    this.#dirtyThreads = new Set();
+    this.#dirtyIndex = false;
+    this.#dirtyAttachments = false;
+    this.#flushTimer = null;
+
+    this.#readOnly = !!opts.readOnly;
+    if (yeaftDir) {
+      this.#dir = join(yeaftDir, 'threads');
+      this.#indexPath = join(this.#dir, 'index.md');
+      this.#attachmentsPath = join(this.#dir, 'attachments.json');
+      if (!this.#readOnly) {
+        try {
+          if (!existsSync(this.#dir)) mkdirSync(this.#dir, { recursive: true });
+        } catch {
+          this.#readOnly = true;
+        }
+      }
+      this.#loadAll();
+    } else {
+      this.#dir = null;
+      this.#indexPath = null;
+      this.#attachmentsPath = null;
+    }
+
+    // Ensure the main thread is always present.
+    if (!this.#threads.has(MAIN_THREAD_ID)) {
+      const now = Date.now();
+      this.#threads.set(
+        MAIN_THREAD_ID,
+        this.#newThreadRecord({
+          id: MAIN_THREAD_ID,
+          name: 'main',
+          goal: '',
+          parentThreadId: null,
+          createdAt: now,
+          updatedAt: now,
+        }),
+      );
+      this.#markDirty(MAIN_THREAD_ID);
+    }
+
+    // If the on-disk currentId is unknown, fall back to main.
+    if (!this.#threads.has(this.#currentId)) {
+      this.#currentId = MAIN_THREAD_ID;
+    }
   }
 
-  /** Internal: build a thread record with default cached fields. */
+  /** 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
+      lastActivityAt: null,
       archived: false,
-      unread: 0,            // task-300 sidebar: messages since last read marker
-      preview: '',          // task-300 sidebar: short excerpt of latest content
+      unread: 0,
+      preview: '',
       ...base,
     };
   }
 
-  /** Get current thread id (defaults to 'main'). */
-  get currentId() {
-    return this.#currentId;
+  // ─── load / persist ────────────────────────────────────────────────
+
+  /** Load all thread files + attachments from disk into memory. */
+  #loadAll() {
+    if (!this.#dir || !existsSync(this.#dir)) return;
+    let entries;
+    try {
+      entries = readdirSync(this.#dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      if (entry.name === 'index.md') continue;
+      const id = entry.name.slice(0, -3);
+      try {
+        const raw = readFileSync(join(this.#dir, entry.name), 'utf8');
+        const parsed = parseThread(raw);
+        if (parsed && parsed.id === id) {
+          this.#threads.set(id, parsed);
+        }
+      } catch {
+        // Skip corrupt files silently.
+      }
+    }
+    // Attachments side-car.
+    try {
+      if (this.#attachmentsPath && existsSync(this.#attachmentsPath)) {
+        const raw = readFileSync(this.#attachmentsPath, 'utf8');
+        for (const { threadId, taskId } of parseAttachments(raw)) {
+          if (this.#threads.has(threadId)) {
+            this.#attachments.set(threadId, taskId);
+          }
+        }
+      }
+    } catch {
+      // Skip silently.
+    }
+    // Try to recover currentId from index.md frontmatter.
+    try {
+      if (this.#indexPath && existsSync(this.#indexPath)) {
+        const raw = readFileSync(this.#indexPath, 'utf8');
+        const m = raw.match(/^currentId:\s*(\S+)/m);
+        if (m && this.#threads.has(m[1])) {
+          this.#currentId = m[1];
+        }
+      }
+    } catch {
+      // Ignore — fall back to main on miss.
+    }
+  }
+
+  #markDirty(threadId) {
+    if (!this.#dir || this.#readOnly) return;
+    this.#dirtyThreads.add(threadId);
+    this.#dirtyIndex = true;
+    this.#scheduleFlush();
   }
 
-  /** Total thread count (including 'main'). */
-  get size() {
-    return this.#threads.size;
+  #markAttachmentsDirty() {
+    if (!this.#dir || this.#readOnly) return;
+    this.#dirtyAttachments = true;
+    this.#dirtyIndex = true;
+    this.#scheduleFlush();
+  }
+
+  #scheduleFlush() {
+    if (this.#flushTimer || typeof setTimeout !== 'function') return;
+    this.#flushTimer = setTimeout(() => {
+      this.#flushTimer = null;
+      this.flush();
+    }, FLUSH_DEBOUNCE_MS);
+    // Do not hold the process open for a pending flush — if the Node loop
+    // has nothing else to do, the store still makes it through shutdown
+    // via explicit flush() or process exit handlers.
+    if (this.#flushTimer && typeof this.#flushTimer.unref === 'function') {
+      this.#flushTimer.unref();
+    }
+  }
+
+  /**
+   * Write any pending dirty state to disk immediately. Safe to call on an
+   * in-memory or read-only store (it becomes a no-op). Returns the number of
+   * files written.
+   */
+  flush() {
+    if (!this.#dir || this.#readOnly) {
+      this.#dirtyThreads.clear();
+      this.#dirtyIndex = false;
+      this.#dirtyAttachments = false;
+      return 0;
+    }
+    let written = 0;
+    for (const id of this.#dirtyThreads) {
+      const t = this.#threads.get(id);
+      if (!t) {
+        // Deleted thread → remove the file if present.
+        try {
+          const p = join(this.#dir, `${id}.md`);
+          if (existsSync(p)) {
+            unlinkSync(p);
+            written += 1;
+          }
+        } catch {
+          // ignore
+        }
+        continue;
+      }
+      try {
+        writeFileSync(join(this.#dir, `${id}.md`), serializeThread(t), 'utf8');
+        written += 1;
+      } catch {
+        // Best-effort
+      }
+    }
+    this.#dirtyThreads.clear();
+    if (this.#dirtyAttachments) {
+      try {
+        writeFileSync(this.#attachmentsPath, serializeAttachments(this.#attachments), 'utf8');
+      } catch {
+        // ignore
+      }
+      this.#dirtyAttachments = false;
+    }
+    if (this.#dirtyIndex) {
+      try {
+        writeFileSync(this.#indexPath, generateIndex(this.#threads, this.#currentId, this.#attachments), 'utf8');
+      } catch {
+        // ignore
+      }
+      this.#dirtyIndex = false;
+    }
+    return written;
   }
 
+  // ─── Query API (unchanged) ─────────────────────────────────────────
+
+  get currentId() { return this.#currentId; }
+  get size() { return this.#threads.size; }
+
+  get(id) { return this.#threads.get(id) || null; }
+  list() { return [...this.#threads.values()]; }
+  has(id) { return this.#threads.has(id); }
+
+  // ─── Mutation API (all calls schedule a debounced flush) ───────────
+
   /**
    * Create a new thread.
    * @param {{ name: string, goal?: string, parentThreadId?: string }} spec
@@ -116,28 +483,11 @@ export class ThreadStore {
       updatedAt: now,
     });
     this.#threads.set(id, thread);
+    this.#markDirty(id);
     return thread;
   }
 
-  /** @param {string} id */
-  get(id) {
-    return this.#threads.get(id) || null;
-  }
-
-  /** @returns {Thread[]} */
-  list() {
-    return [...this.#threads.values()];
-  }
-
-  /** @param {string} id */
-  has(id) {
-    return this.#threads.has(id);
-  }
-
-  /**
-   * Set the current thread marker. Throws if unknown.
-   * @param {string} id
-   */
+  /** Set the current thread marker. Throws if unknown. */
   switch(id) {
     if (!this.#threads.has(id)) {
       throw new Error(`thread not found: ${id}`);
@@ -145,16 +495,13 @@ export class ThreadStore {
     this.#currentId = id;
     const t = this.#threads.get(id);
     t.updatedAt = Date.now();
+    this.#markDirty(id);
   }
 
   /**
    * 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()]
+   * unknown threadIds are silently ignored.
    */
   noteMessage(threadId, at = Date.now(), opts = {}) {
     const t = this.#threads.get(threadId);
@@ -163,38 +510,29 @@ export class ThreadStore {
     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;
     }
+    this.#markDirty(threadId);
   }
 
-  /**
-   * Mark a thread as read — resets unread counter to 0. Safe on unknown id.
-   * @param {string} threadId
-   */
+  /** Mark a thread as read — resets unread counter to 0. */
   markRead(threadId) {
     const t = this.#threads.get(threadId);
     if (!t) return;
+    if (t.unread === 0) return;
     t.unread = 0;
+    this.#markDirty(threadId);
   }
 
-  /**
-   * 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}`);
@@ -202,13 +540,9 @@ export class ThreadStore {
     t.status = 'archived';
     t.archived = true;
     t.updatedAt = Date.now();
+    this.#markDirty(id);
   }
 
-  /**
-   * 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}`);
@@ -221,24 +555,19 @@ export class ThreadStore {
     t.status = status;
     t.archived = status === 'archived';
     t.updatedAt = Date.now();
+    this.#markDirty(id);
   }
 
   /**
    * 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
+   * list. Used for crash recovery or as a sanity check in tests.
    */
   rebuildFromMessages(messages) {
-    // Reset counters
     for (const t of this.#threads.values()) {
       t.messageCount = 0;
       t.lastMessageAt = null;
       t.lastActivityAt = null;
+      this.#markDirty(t.id);
     }
     for (const m of messages || []) {
       const tid = m.threadId || MAIN_THREAD_ID;
@@ -250,14 +579,10 @@ export class ThreadStore {
         t.lastMessageAt = ts;
         t.lastActivityAt = ts;
       }
+      this.#markDirty(tid);
     }
   }
 
-  /**
-   * Attach a task to a thread. Overwrites any existing attachment.
-   * @param {string} threadId
-   * @param {string} taskId
-   */
   attachTask(threadId, taskId) {
     if (!this.#threads.has(threadId)) {
       throw new Error(`thread not found: ${threadId}`);
@@ -266,35 +591,46 @@ export class ThreadStore {
       throw new Error('taskId is required');
     }
     this.#attachments.set(threadId, taskId);
+    this.#markAttachmentsDirty();
   }
 
-  /**
-   * Get the taskId attached to a thread, if any.
-   * @param {string} threadId
-   * @returns {string|null}
-   */
   attachedTask(threadId) {
     return this.#attachments.get(threadId) || null;
   }
 
-  /** @returns {Array<{ threadId: string, taskId: string }>} */
   listAttachments() {
     return [...this.#attachments.entries()].map(([threadId, taskId]) => ({ threadId, taskId }));
   }
 }
 
+// ─── Singleton helpers ───────────────────────────────────────────────────
+
 /** @type {ThreadStore|null} */
 let threadStore = null;
 
 /**
- * Initialize the thread store. Safe to call multiple times — subsequent calls
+ * Initialise the thread store. Safe to call multiple times — subsequent calls
  * replace the store only if `force` is true (primarily for tests).
- * @param {{ force?: boolean }} [opts]
+ *
+ * Accepts either `initThreadStore()` (legacy, in-memory) or
+ * `initThreadStore(yeaftDir, opts)` (persistent). Legacy callers keep working.
+ *
+ * @param {string|{ force?: boolean }} [yeaftDirOrOpts]
+ * @param {{ force?: boolean, readOnly?: boolean }} [opts]
  * @returns {ThreadStore}
  */
-export function initThreadStore(opts = {}) {
-  if (!threadStore || opts.force) {
-    threadStore = new ThreadStore();
+export function initThreadStore(yeaftDirOrOpts, opts = {}) {
+  let yeaftDir;
+  let mergedOpts;
+  if (typeof yeaftDirOrOpts === 'string') {
+    yeaftDir = yeaftDirOrOpts;
+    mergedOpts = opts || {};
+  } else {
+    yeaftDir = undefined;
+    mergedOpts = yeaftDirOrOpts || {};
+  }
+  if (!threadStore || mergedOpts.force) {
+    threadStore = new ThreadStore(yeaftDir, mergedOpts);
   }
   return threadStore;
 }
@@ -309,5 +645,11 @@ export function getThreadStore() {
 
 /** Test-only reset helper. */
 export function _resetThreadStoreForTests() {
+  if (threadStore && typeof threadStore.flush === 'function') {
+    try { threadStore.flush(); } catch { /* ignore */ }
+  }
   threadStore = null;
 }
+
+// Exported for tests.
+export { serializeThread as _serializeThread, parseThread as _parseThread };

package/unify/web-bridge.js

@@ -16,6 +16,7 @@
 import { loadSession } from './session.js';
 import { sendToServer } from '../connection/buffer.js';
 import ctx from '../context.js';
+import { getThreadStore } from './threads/store.js';
 
 /** @type {import('./session.js').Session | null} */
 let session = null;
@@ -72,6 +73,49 @@ function sendUnifyEvent(event) {
   });
 }
 
+/**
+ * task-301 Part 2: push the full thread list snapshot to the web client.
+ * Called after any ThreadStore-mutating tool completes and at turn_end so
+ * the sidebar V2 always shows a fresh picture. Cheap — ThreadStore keeps
+ * cached counters so list() is O(n) over a small n.
+ */
+function sendThreadListUpdate() {
+  try {
+    const store = getThreadStore();
+    const threads = store.list().map(t => ({
+      id: t.id,
+      name: t.name,
+      goal: t.goal || '',
+      parentThreadId: t.parentThreadId || null,
+      status: t.status,
+      archived: !!t.archived,
+      messageCount: t.messageCount || 0,
+      lastMessageAt: t.lastMessageAt || null,
+      lastActivityAt: t.lastActivityAt || t.lastMessageAt || t.updatedAt || null,
+      unread: t.unread || 0,
+      preview: t.preview || '',
+      createdAt: t.createdAt,
+      updatedAt: t.updatedAt,
+      // `running` — the thread whose id equals the store's currentId is
+      // considered the active/running track. The UI uses this for the
+      // green halo in the Active group.
+      running: t.id === store.currentId,
+    }));
+    sendUnifyEvent({ type: 'thread_list_updated', threads, currentThreadId: store.currentId });
+  } catch (err) {
+    // Best-effort; sidebar update must never block the main query path.
+    console.warn('[Unify] sendThreadListUpdate failed:', err?.message || err);
+  }
+}
+
+/** Tool names that mutate ThreadStore. After any of these we push an update. */
+const THREAD_MUTATING_TOOLS = new Set([
+  'SpawnThread',
+  'SwitchThread',
+  'ArchiveThread',
+  'AttachThreadToTask',
+]);
+
 /**
  * Handle a unify_chat message from the web UI.
  *
@@ -118,6 +162,9 @@ export async function handleUnifyChat(msg) {
         mcpServers: session.status.mcpServers,
         tools: session.status.tools,
       });
+      // task-301 Part 2: initial thread snapshot so sidebar V2 renders
+      // the real 'main' thread (and any restored threads) right away.
+      sendThreadListUpdate();
     }
 
     // ─── Cancel any in-flight query ──
@@ -214,6 +261,11 @@ export async function handleUnifyChat(msg) {
             }],
             threadId: event.threadId,
           });
+          // task-301 Part 2: if this tool mutates ThreadStore, push a
+          // fresh snapshot to the sidebar immediately.
+          if (THREAD_MUTATING_TOOLS.has(event.name)) {
+            sendThreadListUpdate();
+          }
           break;
 
         // ── Turn boundaries ──
@@ -476,6 +528,8 @@ export async function handleUnifyLoadHistory(msg) {
       mcpServers: session.status.mcpServers,
       tools: session.status.tools,
     });
+    // task-301 Part 2: initial thread snapshot for history-load session.
+    sendThreadListUpdate();
   }
 
   const limit = msg.limit || 50;
@@ -548,6 +602,8 @@ export async function resetUnifySession() {
       mcpServers: session.status.mcpServers,
       tools: session.status.tools,
     });
+    // task-301 Part 2: re-push thread snapshot after session reset.
+    sendThreadListUpdate();
   } catch (err) {
     console.error('[Unify] Failed to re-initialize session after reset:', err.message);
   }