@yeaft/webchat-agent 0.1.482 → 0.1.484

package/package.json

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

package/unify/conversation/migrate-messages-threadid.js

@@ -0,0 +1,116 @@
+/**
+ * migrate-messages-threadid.js — task-307 one-shot migration.
+ *
+ * For every message under <yeaftDir>/conversation/messages/ and cold/ that
+ * does NOT yet carry a `threadId:` frontmatter field, stamp it with
+ * `threadId: main`. This matches design §5 semantics: pre-Phase-2 messages
+ * predate threading and belong to the root conversation.
+ *
+ * Idempotency:
+ *   A marker file `<yeaftDir>/conversation/.migrations/messagesThreadId`
+ *   is written on successful completion. Subsequent runs observe the
+ *   marker and short-circuit with `{ ran: false }`.
+ *
+ * Safety:
+ *   - Messages that already carry a threadId are left untouched.
+ *   - If a file is unreadable / unparseable it is skipped (never rewritten).
+ *   - Write errors are swallowed so a half-successful migration can resume
+ *     on the next boot by re-running.
+ *
+ * Usage (programmatic):
+ *   import { migrateMessagesThreadId } from './migrate-messages-threadid.js';
+ *   const res = migrateMessagesThreadId('/home/me/.yeaft');
+ *   // { ran: true, migrated: 42, skipped: 3 }
+ *
+ * Usage (CLI):
+ *   node agent/unify/conversation/migrate-messages-threadid.js [yeaftDir]
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export function migrateMessagesThreadId(yeaftDir) {
+  const root = yeaftDir || join(homedir(), '.yeaft');
+  const convDir = join(root, 'conversation');
+  const markerDir = join(convDir, '.migrations');
+  const markerPath = join(markerDir, 'messagesThreadId');
+
+  if (!existsSync(convDir)) {
+    return { ran: false, reason: 'no conversation dir', migrated: 0, skipped: 0 };
+  }
+  try {
+    if (existsSync(markerPath)) {
+      return { ran: false, reason: 'already migrated', migrated: 0, skipped: 0 };
+    }
+  } catch { /* best-effort */ }
+
+  const dirs = [join(convDir, 'messages'), join(convDir, 'cold')];
+  let migrated = 0;
+  let skipped = 0;
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    let files;
+    try {
+      files = readdirSync(dir).filter(f => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      const path = join(dir, f);
+      let raw;
+      try {
+        raw = readFileSync(path, 'utf8');
+      } catch {
+        skipped += 1;
+        continue;
+      }
+      if (!raw || !raw.startsWith('---')) { skipped += 1; continue; }
+      const endIdx = raw.indexOf('\n---', 3);
+      if (endIdx === -1) { skipped += 1; continue; }
+      const frontmatter = raw.slice(4, endIdx);
+      const body = raw.slice(endIdx); // leading '\n---' ...
+      if (/^threadId:/m.test(frontmatter)) {
+        skipped += 1;
+        continue; // already has threadId
+      }
+      const newFm = frontmatter.replace(/\s*$/, '') + '\nthreadId: main';
+      const rebuilt = '---\n' + newFm.trimStart() + body;
+      try {
+        writeFileSync(path, rebuilt, { encoding: 'utf8', mode: 0o644 });
+        migrated += 1;
+      } catch {
+        skipped += 1;
+      }
+    }
+  }
+
+  try {
+    mkdirSync(markerDir, { recursive: true, mode: 0o755 });
+    writeFileSync(
+      markerPath,
+      `migrated: ${new Date().toISOString()}\ncount: ${migrated}\nskipped: ${skipped}\n`,
+      { encoding: 'utf8', mode: 0o644 },
+    );
+  } catch {
+    // Without the marker the migration will re-run; it's idempotent per-file
+    // (files already carrying threadId are skipped) so that's acceptable.
+  }
+
+  return { ran: true, migrated, skipped };
+}
+
+// CLI entry point.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  const res = migrateMessagesThreadId(dir);
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify(res, null, 2));
+}

package/unify/conversation/persist.js

@@ -56,6 +56,10 @@ function serializeMessage(msg) {
   if (msg.turnNumber != null) fm.push(`turnNumber: ${msg.turnNumber}`);
   if (msg.toolCallId) fm.push(`toolCallId: ${msg.toolCallId}`);
   if (msg.isError) fm.push(`isError: true`);
+  // task-307: every message is stamped with a threadId so multi-thread
+  // routing can filter/replay by thread without rescanning JSON blobs.
+  // Defaults to 'main' for legacy messages (see migrate-messages-threadid.js).
+  fm.push(`threadId: ${msg.threadId || 'main'}`);
 
   // Token estimate
   const content = msg.content || '';
@@ -111,10 +115,14 @@ export function parseMessage(raw) {
       case 'toolCallId': msg.toolCallId = value; break;
       case 'isError': msg.isError = value === 'true'; break;
       case 'tokens_est': msg.tokens_est = parseInt(value, 10); break;
+      case 'threadId': msg.threadId = value; break;
       // toolCalls are multi-line YAML — handled separately below
     }
   }
 
+  // task-307: legacy messages written before threadId existed default to 'main'.
+  if (!msg.threadId) msg.threadId = 'main';
+
   // Parse toolCalls if present (simplified multi-line YAML)
   if (frontmatter.includes('toolCalls:')) {
     const toolCalls = [];

package/unify/input-queue/store.js

@@ -0,0 +1,322 @@
+/**
+ * input-queue/store.js — Persistent FIFO input queue for Yeaft Unify.
+ *
+ * task-307b (Phase 2): a disk-backed queue of user inputs waiting to be
+ * routed to a thread/engine. Each entry is one JSON file at
+ *   <yeaftDir>/input-queue/<id>.json
+ * so that crashing during a routing decision never loses a queued input.
+ *
+ * Schema follows design doc §5:
+ *   {
+ *     id:         'iq-xxxxxxxx',
+ *     text:       '<the user-typed input>',
+ *     createdAt:  1234567890123,            // epoch ms
+ *     status:     'pending' | 'routing' | 'dispatched',
+ *     routedTo:   '<threadId>' | null,      // set when status === 'dispatched'
+ *     routedAt:   1234567890456 | null,
+ *     error:      '<message>' | null,       // optional — populated when a
+ *                                           //   routing attempt fails and
+ *                                           //   the entry is put back to
+ *                                           //   'pending' for retry.
+ *   }
+ *
+ * State machine:
+ *        enqueue(text)
+ *             │
+ *             ▼
+ *         pending ─────claim()─────► routing ─────markRouted()────► dispatched
+ *             ▲                        │
+ *             └──────markFailed()──────┘  (status back to pending; error field recorded)
+ *
+ *   - pending    : waiting for a dispatcher
+ *   - routing    : a dispatcher has taken responsibility; crash here means
+ *                  boot-time recovery will still see the entry and can
+ *                  re-claim it (the row is still on disk).
+ *   - dispatched : routed to a thread — the file is removed because the
+ *                  durable audit trail now lives in the messages.
+ *
+ * API (task-307b per PM):
+ *   - enqueue(text)                → entry          Create + persist pending.
+ *   - dequeue()                    → entry | null   Peek at oldest pending
+ *                                                   (non-mutating — see
+ *                                                   claim() for the mutating
+ *                                                   transition).
+ *   - claim()                      → entry | null   Oldest pending → 'routing'
+ *                                                   (atomic w.r.t. disk).
+ *   - list(status?)                → entry[]        Snapshot filtered by status.
+ *   - markRouted(id, routedTo)     → entry | null   routing → dispatched;
+ *                                                   file deleted.
+ *   - markFailed(id, err)          → entry | null   routing → pending; error
+ *                                                   recorded; kept on disk.
+ *   - peek() / get(id) / remove(id) / size() / pendingCount()
+ *
+ * Persistence:
+ *   - Writes are synchronous. The queue is a durability boundary, not a
+ *     hot path (one write per state transition).
+ *   - Permission/FS failures don't throw: they are swallowed and logged once
+ *     per process (matches ConversationStore's philosophy).
+ *   - If `yeaftDir` is omitted, the store operates purely in memory.
+ */
+
+import { randomUUID } from 'crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from 'fs';
+import { join } from 'path';
+
+/** All valid status values, per design §5. */
+export const INPUT_QUEUE_STATUSES = ['pending', 'routing', 'dispatched'];
+
+export class InputQueueStore {
+  /** @type {Map<string, object>} */
+  #entries;
+  /** @type {string|null} */
+  #dir;
+  /** @type {boolean} */
+  #persistent;
+  /** @type {boolean} */
+  #warned;
+
+  /**
+   * @param {string|null} [yeaftDir]
+   */
+  constructor(yeaftDir = null) {
+    this.#entries = new Map();
+    this.#warned = false;
+
+    if (yeaftDir) {
+      this.#dir = join(yeaftDir, 'input-queue');
+      this.#persistent = true;
+      this.#ensureDir();
+      this.#loadAll();
+    } else {
+      this.#dir = null;
+      this.#persistent = false;
+    }
+  }
+
+  get persistent() { return this.#persistent; }
+  size() { return this.#entries.size; }
+
+  pendingCount() {
+    let n = 0;
+    for (const e of this.#entries.values()) if (e.status === 'pending') n += 1;
+    return n;
+  }
+
+  /**
+   * Append a new pending entry and persist it.
+   * @param {string} text
+   * @returns {object} the entry
+   */
+  enqueue(text) {
+    if (typeof text !== 'string') throw new Error('text must be a string');
+    const id = `iq-${randomUUID().slice(0, 8)}`;
+    const entry = {
+      id,
+      text,
+      createdAt: Date.now(),
+      status: 'pending',
+      routedTo: null,
+      routedAt: null,
+      error: null,
+    };
+    this.#entries.set(id, entry);
+    this.#writeEntry(entry);
+    return entry;
+  }
+
+  /** Oldest pending entry (no state change). null if empty. */
+  peek() {
+    let oldest = null;
+    for (const e of this.#entries.values()) {
+      if (e.status !== 'pending') continue;
+      if (!oldest || e.createdAt < oldest.createdAt) oldest = e;
+    }
+    return oldest;
+  }
+
+  /**
+   * Return the oldest pending entry without mutating state. Kept as a
+   * separate method from claim() because some consumers only want to
+   * observe the head of the queue (e.g. UI preview).
+   */
+  dequeue() {
+    return this.peek();
+  }
+
+  /**
+   * Transition the oldest pending entry → 'routing' and persist. This is
+   * the real consumer-facing take: after claim() the caller must eventually
+   * call markRouted() (success) or markFailed() (→ put back as pending).
+   *
+   * @returns {object|null} the claimed entry, or null if nothing pending
+   */
+  claim() {
+    const e = this.peek();
+    if (!e) return null;
+    e.status = 'routing';
+    this.#writeEntry(e);
+    return e;
+  }
+
+  /**
+   * Mark an entry as successfully dispatched to a thread. Persists the
+   * updated state then removes the file — the authoritative record now
+   * lives in the conversation/messages log.
+   *
+   * @param {string} id
+   * @param {string} routedTo — thread id (e.g. 'main' or 'thr-xxxxxxxx')
+   * @returns {object|null}
+   */
+  markRouted(id, routedTo) {
+    const e = this.#entries.get(id);
+    if (!e) return null;
+    if (!routedTo || typeof routedTo !== 'string') throw new Error('routedTo required');
+    e.status = 'dispatched';
+    e.routedTo = routedTo;
+    e.routedAt = Date.now();
+    // Persist the transition before removing (crash-safe ordering).
+    this.#writeEntry(e);
+    this.#removeFile(id);
+    this.#entries.delete(id);
+    return e;
+  }
+
+  /**
+   * Mark a routing attempt failed. The entry returns to 'pending' so the
+   * next claim() can retry it; the error string is retained for diagnostics.
+   *
+   * @param {string} id
+   * @param {string|Error} err
+   */
+  markFailed(id, err) {
+    const e = this.#entries.get(id);
+    if (!e) return null;
+    e.status = 'pending';
+    e.error = typeof err === 'string' ? err : (err?.message || String(err));
+    this.#writeEntry(e);
+    return e;
+  }
+
+  /** Remove an entry entirely (memory + disk). */
+  remove(id) {
+    if (!this.#entries.has(id)) return false;
+    this.#entries.delete(id);
+    this.#removeFile(id);
+    return true;
+  }
+
+  /**
+   * Snapshot of all entries, optionally filtered by status. Chronological.
+   * @param {'pending'|'routing'|'dispatched'} [status]
+   */
+  list(status) {
+    let arr = [...this.#entries.values()];
+    if (status) arr = arr.filter(e => e.status === status);
+    arr.sort((a, b) => a.createdAt - b.createdAt);
+    return arr;
+  }
+
+  get(id) { return this.#entries.get(id) || null; }
+
+  // ─── Persistence internals ────────────────────────────
+
+  #ensureDir() {
+    try {
+      if (!existsSync(this.#dir)) mkdirSync(this.#dir, { recursive: true, mode: 0o755 });
+    } catch (err) {
+      this.#warn(`Cannot create input-queue dir: ${err?.code || err?.message}`);
+    }
+  }
+
+  #loadAll() {
+    if (!existsSync(this.#dir)) return;
+    let files;
+    try {
+      files = readdirSync(this.#dir);
+    } catch (err) {
+      this.#warn(`Cannot read input-queue dir: ${err?.code || err?.message}`);
+      return;
+    }
+    for (const f of files) {
+      if (!f.endsWith('.json')) continue;
+      const path = join(this.#dir, f);
+      try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.id) continue;
+        if (!INPUT_QUEUE_STATUSES.includes(parsed.status)) continue;
+        // Crash recovery: an entry left in 'routing' at startup had a
+        // dispatcher claim it right before the crash. Put it back to
+        // 'pending' so the next claim() can retry it.
+        const status = parsed.status === 'routing' ? 'pending' : parsed.status;
+        this.#entries.set(parsed.id, {
+          id: parsed.id,
+          text: typeof parsed.text === 'string' ? parsed.text : '',
+          createdAt: Number(parsed.createdAt) || Date.now(),
+          status,
+          routedTo: parsed.routedTo || null,
+          routedAt: parsed.routedAt || null,
+          error: parsed.error || null,
+        });
+      } catch {
+        // Skip corrupt file.
+      }
+    }
+  }
+
+  #writeEntry(entry) {
+    if (!this.#persistent) return;
+    const path = join(this.#dir, `${entry.id}.json`);
+    try {
+      writeFileSync(path, JSON.stringify(entry, null, 2), { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      this.#warn(`Cannot write ${entry.id}: ${err?.code || err?.message}`);
+    }
+  }
+
+  #removeFile(id) {
+    if (!this.#persistent) return;
+    const path = join(this.#dir, `${id}.json`);
+    if (!existsSync(path)) return;
+    try {
+      unlinkSync(path);
+    } catch (err) {
+      this.#warn(`Cannot remove ${id}: ${err?.code || err?.message}`);
+    }
+  }
+
+  #warn(msg) {
+    if (this.#warned) return;
+    this.#warned = true;
+    // eslint-disable-next-line no-console
+    console.warn(`[Yeaft InputQueue] ${msg}`);
+  }
+}
+
+// ─── Singleton helpers ────────────────────────────────────
+
+/** @type {InputQueueStore|null} */
+let inputQueueStore = null;
+
+export function initInputQueueStore(opts = {}) {
+  if (!inputQueueStore || opts.force) {
+    inputQueueStore = new InputQueueStore(opts.yeaftDir || null);
+  }
+  return inputQueueStore;
+}
+
+export function getInputQueueStore() {
+  if (!inputQueueStore) inputQueueStore = new InputQueueStore(null);
+  return inputQueueStore;
+}
+
+export function _resetInputQueueStoreForTests() {
+  inputQueueStore = null;
+}

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 };