@yeaft/webchat-agent 0.1.486 → 0.1.488

package/package.json

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

package/unify/cli.js

@@ -37,7 +37,6 @@ import { consolidate } from './memory/consolidate.js';
 
 function parseArgs(argv) {
   const args = {
-    mode: 'chat',
     debug: false,
     interactive: false,
     verbose: false,
@@ -57,10 +56,6 @@ function parseArgs(argv) {
   while (i < rest.length) {
     const arg = rest[i];
     switch (arg) {
-      case '-m':
-      case '--mode':
-        args.mode = rest[++i] || 'chat';
-        break;
       case '-d':
       case '--debug':
         args.debug = true;
@@ -176,7 +171,7 @@ function handleTraceQuery(args, config) {
 // ─── Dry-run handler ───────────────────────────────────────────
 
 function handleDryRun(args, config) {
-  const systemPrompt = buildSystemPrompt({ language: config.language, mode: args.mode });
+  const systemPrompt = buildSystemPrompt({ language: config.language });
   const messages = [];
 
   if (args.prompt) {
@@ -188,7 +183,6 @@ function handleDryRun(args, config) {
   console.log('--- Config ---');
   console.log(`  Model:    ${config.model}`);
   console.log(`  Adapter:  ${config.adapter || 'auto'}`);
-  console.log(`  Mode:     ${args.mode}`);
   console.log(`  Debug:    ${config.debug}`);
   console.log();
   console.log('--- System Prompt ---');
@@ -218,7 +212,6 @@ async function runREPL(config, args) {
   });
 
   const { engine, conversationStore, memoryStore, trace, skillManager, mcpManager, toolRegistry } = session;
-  let currentMode = args.mode;
 
   // Load persisted conversation as initial messages
   let conversationMessages = conversationStore.loadRecent(50).map(m => ({
@@ -232,7 +225,7 @@ async function runREPL(config, args) {
   const coldCount = conversationStore.countCold();
   const memStats = memoryStore.stats();
 
-  console.log(`Yeaft Unify REPL (model: ${session.config.model}, mode: ${currentMode})`);
+  console.log(`Yeaft Unify REPL (model: ${session.config.model})`);
   console.log(`Conversation: ${hotCount} hot, ${coldCount} cold | Memory: ${memStats.entryCount} entries`);
   console.log(`Tools: ${session.status.tools} | Skills: ${session.status.skills}`);
   if (session.status.mcpServers.length > 0) {
@@ -247,7 +240,7 @@ async function runREPL(config, args) {
   const rl = createInterface({
     input: process.stdin,
     output: process.stdout,
-    prompt: `yeaft:${currentMode}> `,
+    prompt: `yeaft> `,
   });
 
   rl.prompt();
@@ -265,7 +258,6 @@ async function runREPL(config, args) {
       switch (cmd) {
         case 'help':
           console.log('Commands:');
-          console.log('  /mode <chat|work|dream>  — Switch mode');
           console.log('  /debug                   — Toggle debug mode');
           console.log('  /trace <stats|recent>    — Query debug trace');
           console.log('  /memory [add|clear|stats] — Memory management');
@@ -285,16 +277,6 @@ async function runREPL(config, args) {
           console.log('  /quit                    — Exit');
           break;
 
-        case 'mode':
-          if (cmdArgs[0]) {
-            currentMode = cmdArgs[0];
-            rl.setPrompt(`yeaft:${currentMode}> `);
-            console.log(`Mode switched to: ${currentMode}`);
-          } else {
-            console.log(`Current mode: ${currentMode}`);
-          }
-          break;
-
         case 'debug':
           session.config.debug = !session.config.debug;
           console.log(`Debug mode: ${session.config.debug ? 'ON' : 'OFF'}`);
@@ -433,10 +415,9 @@ async function runREPL(config, args) {
         case 'context':
           console.log(`Context info:`);
           console.log(`  Model: ${session.config.model}`);
-          console.log(`  Mode: ${currentMode}`);
           console.log(`  Language: ${session.config.language}`);
           console.log(`  Max context: ${session.config.maxContextTokens} tokens`);
-          console.log(`  System prompt: ${buildSystemPrompt({ language: session.config.language, mode: currentMode }).length} chars`);
+          console.log(`  System prompt: ${buildSystemPrompt({ language: session.config.language }).length} chars`);
           console.log(`  Hot messages: ${conversationStore.countHot()}`);
           console.log(`  Hot tokens: ${conversationStore.hotTokens()}`);
           console.log(`  Cold messages: ${conversationStore.countCold()}`);
@@ -446,13 +427,12 @@ async function runREPL(config, args) {
           break;
 
         case 'dry-run':
-          handleDryRun({ ...args, mode: currentMode, prompt: cmdArgs.join(' ') || null }, session.config);
+          handleDryRun({ ...args, prompt: cmdArgs.join(' ') || null }, session.config);
           break;
 
         case 'stats': {
           const s = trace.stats();
           console.log(`Session stats:`);
-          console.log(`  Mode: ${currentMode}`);
           console.log(`  Debug: ${session.config.debug}`);
           console.log(`  Turns: ${s.turnCount}`);
           console.log(`  Tools: ${s.toolCount}`);
@@ -607,7 +587,6 @@ async function runREPL(config, args) {
 
       for await (const event of engine.query({
         prompt: input,
-        mode: currentMode,
         messages: conversationMessages,
       })) {
         switch (event.type) {
@@ -709,7 +688,6 @@ async function runOnce(config, args) {
 
     for await (const event of engine.query({
       prompt: args.prompt,
-      mode: args.mode,
       messages: priorMessages,
     })) {
       switch (event.type) {
@@ -819,7 +797,6 @@ async function main() {
   console.log('  node cli.js --trace search "keyword"  — Search traces');
   console.log();
   console.log('Options:');
-  console.log('  -m, --mode <mode>     Mode: chat, work, dream (default: chat)');
   console.log('  -d, --debug           Enable debug tracing');
   console.log('  -i, --interactive     Start REPL');
   console.log('  -v, --verbose         Verbose output');

package/unify/engine.js

@@ -167,18 +167,17 @@ export class Engine {
   /**
    * Build the system prompt with memory, compact summary, and skill content.
    *
-   * @param {string} mode
    * @param {{ profile?: string, entries?: object[] }} [memory]
    * @param {string} [compactSummary]
    * @param {string} [prompt] — user prompt (for skill relevance matching)
    * @param {string} [memoryInjection] — task-287: prebuilt memory block (index + prefs + project)
    * @returns {string}
    */
-  #buildSystemPrompt(mode, memory, compactSummary, prompt, memoryInjection) {
+  #buildSystemPrompt(memory, compactSummary, prompt, memoryInjection) {
     // Get relevant skill content if SkillManager is wired
     let skillContent = '';
     if (this.#skillManager && prompt) {
-      skillContent = this.#skillManager.getRelevantPromptContent(prompt, mode);
+      skillContent = this.#skillManager.getRelevantPromptContent(prompt);
     }
 
     // Get tool names from the appropriate source
@@ -188,7 +187,6 @@ export class Engine {
 
     return buildSystemPrompt({
       language: this.#config.language || 'en',
-      mode,
       toolNames,
       memory,
       memoryInjection,
@@ -201,10 +199,9 @@ export class Engine {
    * Build the full tool context for Phase 5 tools.
    *
    * @param {AbortSignal} [signal]
-   * @param {string} [mode]
    * @returns {object}
    */
-  #buildToolContext(signal, mode) {
+  #buildToolContext(signal) {
     return {
       signal,
       yeaftDir: this.#yeaftDir,
@@ -215,7 +212,6 @@ export class Engine {
       conversationStore: this.#conversationStore,
       adapter: this.#adapter,
       config: this.#config,
-      mode,
     };
   }
 
@@ -265,10 +261,9 @@ export class Engine {
    *
    * @param {string} userContent
    * @param {string} assistantContent
-   * @param {string} mode
    * @param {object[]} [toolCalls]
    */
-  #persistMessages(userContent, assistantContent, mode, toolCalls) {
+  #persistMessages(userContent, assistantContent, toolCalls) {
     if (!this.#conversationStore) return;
     if (this.#config._readOnly) return;
 
@@ -288,7 +283,6 @@ export class Engine {
     this.#conversationStore.append({
       role: 'user',
       content: userContent,
-      mode,
       threadId,
     });
 
@@ -296,7 +290,6 @@ export class Engine {
     const assistantMsg = {
       role: 'assistant',
       content: assistantContent,
-      mode,
       model: this.#config.model,
       threadId,
     };
@@ -354,14 +347,11 @@ export class Engine {
    *
    * @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 }) {
+  async *query({ prompt, messages = [], signal }) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -394,7 +384,7 @@ export class Engine {
     }
 
     const compactSummary = this.#getCompactSummary();
-    const systemPrompt = this.#buildSystemPrompt(mode, undefined, compactSummary, prompt, memoryInjection);
+    const systemPrompt = this.#buildSystemPrompt(undefined, compactSummary, prompt, memoryInjection);
 
     // Build conversation: existing messages + new user message
     const conversationMessages = [
@@ -423,7 +413,6 @@ export class Engine {
 
       const turnId = this.#trace.startTurn({
         traceId: this.#traceId,
-        mode,
         turnNumber,
       });
 
@@ -590,7 +579,6 @@ export class Engine {
           // but receives both configs — messages are persisted with primary model name
           const hookResult = await runStopHooks({
             yeaftDir: this.#yeaftDir,
-            mode,
             conversationStore: this.#conversationStore,
             memoryStore: this.#memoryStore,
             adapter: this.#adapter,
@@ -608,7 +596,7 @@ export class Engine {
           }
         } else {
           // Legacy path (no yeaftDir → use old behavior)
-          this.#persistMessages(prompt, fullResponseText, mode, assistantMsg.toolCalls);
+          this.#persistMessages(prompt, fullResponseText, assistantMsg.toolCalls);
 
           const consolidated = await this.#maybeConsolidate();
           if (consolidated && consolidated.archivedCount > 0) {
@@ -620,7 +608,7 @@ export class Engine {
       }
 
       // Execute tool calls and feed results back
-      const toolCtx = this.#buildToolContext(signal, mode);
+      const toolCtx = this.#buildToolContext(signal);
 
       for (const tc of toolCalls) {
         const toolStartTime = Date.now();

package/unify/eval/cases/tool-use.js

@@ -242,7 +242,6 @@ export const toolUseCases = [
     suite: 'tools',
     description: 'Model should read a file then modify it (sequential tools)',
     prompt: 'Read src/index.js and add a health check endpoint at /health',
-    mode: 'work',
     registryTools: allTools,
     criteria: [
       noError,
@@ -268,9 +267,8 @@ export const toolUseCases = [
   {
     id: 'tool-multi-bash-workflow',
     suite: 'tools',
-    description: 'Model should run git status and npm test in work mode',
+    description: 'Model should run git status and npm test',
     prompt: 'Check the git status and run the tests',
-    mode: 'work',
     registryTools: allTools,
     criteria: [
       noError,
@@ -290,25 +288,6 @@ export const toolUseCases = [
     ],
   },
 
-  // ─── Mode Awareness ───────────────────────────────────
-
-  {
-    id: 'tool-mode-chat-no-write',
-    suite: 'tools',
-    description: 'In chat mode, write_file should not be available (work-only tool)',
-    prompt: 'Write "hello" to a file called greeting.txt',
-    mode: 'chat',
-    registryTools: allTools,
-    criteria: [
-      noError,
-      toolNotCalled('write_file', {
-        weight: 10,
-        id: 'no-write-in-chat',
-        description: 'write_file is work-only and should not be called in chat mode',
-      }),
-    ],
-  },
-
   // ─── Error Handling ───────────────────────────────────
 
   {

package/unify/pipeline/dispatcher.js

@@ -0,0 +1,373 @@
+/**
+ * pipeline/dispatcher.js — task-310 Phase 2 integration.
+ *
+ * Composes the three Phase-2 building blocks into a single linear pipeline:
+ *
+ *     unify_chat input
+ *            │
+ *            ▼
+ *    ┌──────────────┐   (task-307b)
+ *    │ InputQueue   │   persistent FIFO of pending user inputs
+ *    └──────┬───────┘
+ *           │ claim()                (transition pending → routing)
+ *           ▼
+ *    ┌──────────────┐   (task-309)
+ *    │ IntentClass. │   explicit @prefix / override / LLM / fallback
+ *    └──────┬───────┘
+ *           │ { action, targetThreadId, source, reason }
+ *           ▼
+ *    ┌──────────────┐   (task-308)
+ *    │ EngineReg.   │   ensure(threadId) → EngineInstance
+ *    └──────┬───────┘
+ *           │ inst.query({ prompt })
+ *           ▼
+ *    ┌──────────────┐
+ *    │ Engine events│   text_delta / tool_call / tool_end / …
+ *    └──────┬───────┘
+ *           │ each event tagged { ...ev, threadId } by EngineInstance
+ *           ▼
+ *      web-bridge forwards to `unify_output`
+ *
+ * ### Responsibilities
+ *
+ * This module OWNS the pipeline's control-flow decisions:
+ *
+ *   - `submit(input)` — enqueue + return the queue entry, non-streaming.
+ *     The caller either invokes `drain()` to actually dispatch, or lets a
+ *     future background worker pick it up. (We go with the simple "drain
+ *     on submit" default because the web-bridge is the sole producer and
+ *     cannot afford a stuck pending entry.)
+ *
+ *   - `dispatch(entry)` async-generator — runs one entry through router +
+ *     engine. Yields a stream of bridge events:
+ *
+ *       { type: 'input_queue_updated', pending, routing, … }
+ *       { type: 'routing_decision', entryId, action, targetThreadId, source, reason }
+ *       { type: 'thread_list_updated', threads, currentThreadId }  (on fork)
+ *       { type: 'engine_event', threadId, event }     // raw Engine event
+ *       { type: 'error', error: Error, retryable }
+ *
+ *     The web-bridge translates `engine_event`s into claude_output (the
+ *     existing code path) and forwards the pipeline-level events as
+ *     `unify_output.event`.
+ *
+ *   - `drain()` — convenience: claim + dispatch repeatedly until the queue
+ *     is empty. Web-bridge calls this after every submit().
+ *
+ * ### What this module does NOT own
+ *
+ *   - Persistence of messages (Engine / EngineInstance).
+ *   - ThreadStore mutations beyond incrementing currentId on 'switch' /
+ *     creating a fork thread on 'fork'.
+ *   - WebSocket framing (web-bridge does that).
+ *   - Abort semantics — each caller wraps `dispatch()` with its own
+ *     AbortController / signal (we forward it to EngineInstance.query).
+ *
+ * ### Concurrent reflow (spec point 5)
+ *
+ * Node's single-thread event loop means two concurrent `dispatch()` calls
+ * interleave at await points. Every yielded `engine_event` carries a
+ * `threadId` (EngineInstance re-tags), so the web-bridge can render events
+ * into the correct UI bubble. The dispatcher itself holds NO per-turn
+ * state on `this` — all state lives in the async generator's closure, so
+ * two pipelines can be in-flight at the same time without aliasing.
+ */
+
+import { MAIN_THREAD_ID } from '../threads/store.js';
+import { getTaskStore } from '../tools/task-tools.js';
+
+/**
+ * Per-entry transient metadata (messageId, override) lives here — a
+ * WeakMap keyed by the queue entry object so it is NEVER persisted to
+ * disk by InputQueueStore.#writeEntry. Entries are GC'd together with
+ * the entry once the queue drops the strong reference.
+ * @type {WeakMap<object, {messageId?: string, override?: {threadId: string}}>}
+ */
+const transientMeta = new WeakMap();
+
+/**
+ * @typedef {'continue'|'interrupt'|'fork'|'switch'} RouterAction
+ *
+ * @typedef {Object} SubmitOptions
+ * @property {string} [messageId]   — optional stable id for override()
+ * @property {{ threadId: string }} [override] — UI-side `@thread-name` hint
+ *   or user correction: skip router, go straight to `switch`/`continue`
+ *   targeting the given threadId.
+ *
+ * @typedef {Object} DispatcherDeps
+ * @property {import('../input-queue/store.js').InputQueueStore} inputQueue
+ * @property {import('../router/intent-classifier.js').IntentClassifier} router
+ * @property {import('../threads/engine-registry.js').ThreadEngineRegistry} engineRegistry
+ * @property {import('../threads/store.js').ThreadStore} threadStore
+ * @property {object} [trace]
+ */
+
+export class Dispatcher {
+  /** @type {DispatcherDeps} */
+  #deps;
+
+  constructor(deps) {
+    const { inputQueue, router, engineRegistry, threadStore } = deps || {};
+    if (!inputQueue || typeof inputQueue.enqueue !== 'function') {
+      throw new Error('Dispatcher: inputQueue is required');
+    }
+    if (!router || typeof router.classify !== 'function') {
+      throw new Error('Dispatcher: router is required');
+    }
+    if (!engineRegistry || typeof engineRegistry.ensure !== 'function') {
+      throw new Error('Dispatcher: engineRegistry is required');
+    }
+    if (!threadStore || typeof threadStore.list !== 'function') {
+      throw new Error('Dispatcher: threadStore is required');
+    }
+    this.#deps = deps;
+  }
+
+  /** Snapshot of queue counters for the UI, post-mutation. */
+  #queueSnapshot() {
+    const { inputQueue } = this.#deps;
+    const entries = inputQueue.list();
+    const counts = { pending: 0, routing: 0, dispatched: 0 };
+    for (const e of entries) {
+      if (counts[e.status] !== undefined) counts[e.status] += 1;
+    }
+    return {
+      type: 'input_queue_updated',
+      total: entries.length,
+      pending: counts.pending,
+      routing: counts.routing,
+      dispatched: counts.dispatched,
+      head: entries[0] ? { id: entries[0].id, status: entries[0].status, text: entries[0].text.slice(0, 80) } : null,
+    };
+  }
+
+  /**
+   * Enqueue a user input. Does NOT dispatch — caller invokes `drain()` or
+   * `dispatch(entry)` next. Separated so callers can atomically observe
+   * the `input_queue_updated` snapshot before the first router call fires.
+   *
+   * @param {string} text
+   * @param {SubmitOptions} [opts]
+   * @returns {{ entry: object, snapshot: object }}
+   */
+  submit(text, opts = {}) {
+    if (typeof text !== 'string' || !text.trim()) {
+      throw new Error('Dispatcher.submit: text required');
+    }
+    const { inputQueue } = this.#deps;
+    const entry = inputQueue.enqueue(text);
+    // Transient metadata lives in a WeakMap keyed by the entry — it is
+    // intentionally off the entry object itself so InputQueueStore's
+    // JSON.stringify write path does NOT leak `_messageId`/`_override`
+    // to disk. The WeakMap entry is dropped when the queue releases the
+    // entry reference (after markRouted removes it from memory).
+    transientMeta.set(entry, {
+      messageId: opts.messageId || undefined,
+      override: opts.override || undefined,
+    });
+    const snapshot = this.#queueSnapshot();
+    return { entry, snapshot };
+  }
+
+  /**
+   * Drain the queue: claim → dispatch in a loop until empty.
+   * Yields the union of every `dispatch()`'s events, interleaved naturally.
+   *
+   * @param {{ signal?: AbortSignal }} [opts]
+   * @yields {object} bridge events
+   */
+  async *drain(opts = {}) {
+    const { inputQueue } = this.#deps;
+    while (true) {
+      const head = inputQueue.peek();
+      if (!head) return;
+      if (head.status !== 'pending') return; // another dispatcher holds it
+      for await (const ev of this.dispatch(head, opts)) yield ev;
+    }
+  }
+
+  /**
+   * Dispatch one queue entry through router + engine. Transitions the
+   * entry: pending → routing (on claim) → dispatched (on success) or back
+   * to pending (on router exception, which is already guarded inside the
+   * classifier — so in practice this branch is very rare).
+   *
+   * @param {object} entry — from inputQueue.peek() or inputQueue.enqueue()
+   * @param {{ signal?: AbortSignal }} [opts]
+   * @yields {object} bridge events
+   */
+  async *dispatch(entry, opts = {}) {
+    const { inputQueue, router, engineRegistry, threadStore } = this.#deps;
+    const { signal } = opts;
+
+    // ── Step 1: claim (pending → routing) ──
+    // Note: we assume the caller already found `entry` as the head. A
+    // concurrent dispatcher would have claimed it first; we check for that.
+    let claimed = entry;
+    if (entry.status === 'pending') {
+      claimed = inputQueue.claim();
+      if (!claimed || claimed.id !== entry.id) {
+        // Another worker took it. Treat as a no-op success.
+        yield this.#queueSnapshot();
+        return;
+      }
+    }
+    yield this.#queueSnapshot();
+
+    // ── Step 2: gather router context ──
+    const currentThreadId = threadStore.currentId || MAIN_THREAD_ID;
+    const allThreads = threadStore.list().map(t => ({
+      id: t.id, name: t.name, goal: t.goal, status: t.status,
+    }));
+    const pendingTasks = this.#listPendingTasks();
+
+    // ── Step 3: classify (explicit override > classifier) ──
+    /** @type {import('../router/intent-classifier.js').RouterDecision} */
+    let decision;
+    const meta = transientMeta.get(entry) || {};
+    const ov = meta.override;
+    if (ov && typeof ov.threadId === 'string' && ov.threadId) {
+      const known = allThreads.some(t => t.id === ov.threadId) || ov.threadId === currentThreadId;
+      if (known) {
+        const action = ov.threadId === currentThreadId ? 'continue' : 'switch';
+        decision = {
+          action,
+          targetThreadId: ov.threadId,
+          reason: 'ui_override',
+          source: 'override',
+        };
+      }
+    }
+    if (!decision) {
+      try {
+        decision = await router.classify({
+          userMessage: claimed.text,
+          currentThreadId,
+          allThreads,
+          pendingTasks,
+          messageId: meta.messageId || undefined,
+        });
+      } catch (err) {
+        // Classifier is wrapped in its own try/catch already; reaching here
+        // means a truly unexpected failure. Degrade to continue.
+        decision = {
+          action: 'continue',
+          targetThreadId: currentThreadId,
+          reason: `dispatcher_classify_exception: ${err.message}`,
+          source: 'fallback',
+        };
+      }
+    }
+
+    yield {
+      type: 'routing_decision',
+      entryId: claimed.id,
+      action: decision.action,
+      targetThreadId: decision.targetThreadId,
+      source: decision.source || 'llm',
+      reason: decision.reason || '',
+    };
+
+    // ── Step 4: resolve target thread (fork may create a new one) ──
+    let targetThreadId = decision.targetThreadId;
+    if (decision.action === 'fork') {
+      const parentId = decision.targetThreadId || currentThreadId;
+      const forked = this.#spawnForkedThread(parentId, claimed.text);
+      if (forked) {
+        targetThreadId = forked.id;
+        yield this.#threadListSnapshot();
+      }
+    } else if (decision.action === 'switch') {
+      // Move the ThreadStore cursor so subsequent tool-originated events
+      // see the right thread for persistence hooks. Guard: not every
+      // ThreadStore implementation exposes has() (e.g. historic mocks).
+      const hasFn = typeof threadStore.has === 'function' ? (id) => threadStore.has(id) : () => true;
+      if (hasFn(targetThreadId)) {
+        try { threadStore.switch(targetThreadId); } catch { /* ignore */ }
+      }
+    }
+
+    // ── Step 5: dispatch to EngineInstance ──
+    let instance;
+    try {
+      instance = engineRegistry.ensure(targetThreadId);
+    } catch (err) {
+      inputQueue.markFailed(claimed.id, err);
+      yield this.#queueSnapshot();
+      yield { type: 'error', error: err, retryable: false };
+      return;
+    }
+
+    try {
+      for await (const event of instance.query({ prompt: claimed.text, signal })) {
+        yield { type: 'engine_event', threadId: targetThreadId, event };
+      }
+      inputQueue.markRouted(claimed.id, targetThreadId);
+      yield this.#queueSnapshot();
+    } catch (err) {
+      inputQueue.markFailed(claimed.id, err);
+      yield this.#queueSnapshot();
+      yield { type: 'error', error: err, retryable: true };
+    }
+  }
+
+  // ──────────────────────────────────────────────────────────────
+
+  #threadListSnapshot() {
+    const { threadStore } = this.#deps;
+    const threads = threadStore.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,
+    }));
+    return {
+      type: 'thread_list_updated',
+      threads,
+      currentThreadId: threadStore.currentId,
+    };
+  }
+
+  #spawnForkedThread(parentId, promptText) {
+    const { threadStore } = this.#deps;
+    if (!threadStore.create) return null;
+    // Short label from first non-empty line, capped at 40 chars.
+    const firstLine = (promptText || '').split(/\r?\n/).find(l => l.trim()) || 'fork';
+    const name = firstLine.trim().slice(0, 40);
+    try {
+      return threadStore.create({ name, parentThreadId: parentId });
+    } catch {
+      return null;
+    }
+  }
+
+  #listPendingTasks() {
+    // Best-effort: the TaskStore is a singleton initialised in loadSession().
+    // If the store isn't available (e.g. unit tests without a session) we
+    // just return []. Never let a TaskStore exception break routing.
+    try {
+      const store = getTaskStore();
+      if (!store || typeof store.list !== 'function') return [];
+      const pending = store.list({ status: 'pending' }) || [];
+      return pending.map(t => ({
+        id: t.id,
+        title: t.title || '',
+        threadId: t.threadId || null,
+      }));
+    } catch { /* ignore */ }
+    return [];
+  }
+}
+
+/**
+ * Build a Dispatcher from session-level deps.
+ * @param {DispatcherDeps} deps
+ * @returns {Dispatcher}
+ */
+export function createDispatcher(deps) {
+  return new Dispatcher(deps);
+}