create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/lib/process-title.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const CTM_PROCESS_NAME = 'Coding Task Manager';
+const WALLE_PROCESS_NAME = 'Wall-E';
+
+function normalizeInstanceTag(tag) {
+  const text = String(tag || 'primary').trim();
+  return text || 'primary';
+}
+
+function legacyProcessTitle(kind, tag = 'primary') {
+  const normalized = normalizeInstanceTag(tag);
+  return `${kind === 'walle' ? 'walle' : 'ctm'}-${normalized}`;
+}
+
+function processTitle(kind, tag = 'primary') {
+  const normalized = normalizeInstanceTag(tag);
+  const base = kind === 'walle' ? WALLE_PROCESS_NAME : CTM_PROCESS_NAME;
+  return normalized === 'primary' ? base : `${base} ${normalized}`;
+}
+
+function processTitleCandidates(kind, tag = 'primary') {
+  const current = processTitle(kind, tag);
+  const legacy = legacyProcessTitle(kind, tag);
+  return current === legacy ? [current] : [current, legacy];
+}
+
+module.exports = {
+  CTM_PROCESS_NAME,
+  WALLE_PROCESS_NAME,
+  legacyProcessTitle,
+  normalizeInstanceTag,
+  processTitle,
+  processTitleCandidates,
+};

package/template/claude-task-manager/lib/prompt-executions-query.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Shared query for /api/prompt-executions, used by BOTH the main-thread handler
+// (api-prompts.js handleListExecutions) and the read-pool worker
+// (read-pool-worker.js 'listPromptExecutions' op) so the two can never diverge —
+// parity by construction. The .all() can return up to 10000 rows each carrying a
+// large message_text, which a CPU profile showed blocking the main event loop
+// ~3.9s on the request path; the worker runs the exact same SQL off-thread.
+function queryPromptExecutions(conn, opts = {}) {
+  const limit = Math.max(1, Math.min(parseInt(opts.limit, 10) || 50, 10000));
+  const order = String(opts.order || 'desc').toLowerCase() === 'asc' ? 'ASC' : 'DESC';
+  const role = opts.role || null;
+  const project = opts.project || null;
+  const after = opts.after || null;
+  let sql = 'SELECT * FROM prompt_executions WHERE 1=1';
+  const params = [];
+  if (role) { sql += ' AND role = ?'; params.push(role); }
+  if (project) { sql += ' AND project_path LIKE ?'; params.push('%' + project + '%'); }
+  if (after) { sql += ' AND executed_at > ?'; params.push(after); }
+  sql += ` ORDER BY executed_at ${order}, session_id ASC, message_index ASC LIMIT ?`;
+  params.push(limit);
+  return conn.prepare(sql).all(...params);
+}
+
+module.exports = { queryPromptExecutions };

package/template/claude-task-manager/lib/prompt-index-disk-cache.js

@@ -0,0 +1,44 @@
+'use strict';
+
+// Pure data-shaping for the persisted prompt-index cache (prompt-index-cache.json). The fs I/O,
+// the write throttle, and the live in-memory Map stay in server.js; this module is the testable
+// serialize/deserialize core. Phase 2a: a cold RESTART used to evict the in-memory prompt-index,
+// so every post-restart first-load of apiSessionPrompts paid the ~1.6s compute. Persisting + seeding
+// the last-good indexes lets the storm fallback serve a warm list instead of stormEmpty/_deferred.
+
+// Pick the most-recently-remembered N entries (Map iteration order = insertion order; remember()
+// re-inserts on each refresh, so the tail is hottest) and drop pathologically large indexes (keeps
+// the file small + the cold-boot read fast). Returns the on-disk `indexes` object.
+function buildPromptIndexSnapshot(entries, { max = 40, maxPrompts = 2000 } = {}) {
+  const list = Array.isArray(entries) ? entries : [];
+  const tail = list.slice(Math.max(0, list.length - Math.max(1, max)));
+  const indexes = {};
+  for (const [sid, r] of tail) {
+    if (!sid || !r || !Array.isArray(r.messages)) continue;
+    if (r.messages.length > maxPrompts) continue;
+    indexes[sid] = { messages: r.messages, summary: r.summary || null };
+  }
+  return indexes;
+}
+
+// Parse a persisted file's JSON text into [{ sid, value }] ready to seed the live Map. Returns []
+// on any malformed/empty input — this is a best-effort cache and must never throw into the boot path.
+function parsePromptIndexSnapshot(jsonText) {
+  try {
+    const parsed = JSON.parse(jsonText);
+    const indexes = parsed && parsed.indexes && typeof parsed.indexes === 'object' ? parsed.indexes : null;
+    if (!indexes) return [];
+    const out = [];
+    for (const sid of Object.keys(indexes)) {
+      const r = indexes[sid];
+      if (r && Array.isArray(r.messages)) {
+        out.push({ sid, value: { messages: r.messages, summary: r.summary || null } });
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+module.exports = { buildPromptIndexSnapshot, parsePromptIndexSnapshot };

package/template/claude-task-manager/lib/prompt-intent.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// AI accuracy backstop for "what is this terminal frame?" — a prompt-INTENT classifier
+// (approval / choice / none) that the server consults ONLY when the structural detectors
+// conflict (assessAmbiguity), deduped per frame (frameFingerprint), with a pure hold
+// decision (resolveIntentDecision) the server drives. The LLM call itself is
+// classifyPromptIntent (added in Task 2). Pure parts here so they unit-test without I/O.
+
+const { evaluateWaitState, _fnv1a } = require('./wait-state');
+const terminalChoice = require('./terminal-choice');
+const { callBackgroundLlm } = require('./background-llm');
+let approvalAgent = null;
+try { approvalAgent = require('../approval-agent'); } catch { approvalAgent = null; }
+
+// Stable per-frame key shared by the reconcile and approver paths so a frame is
+// classified ONCE regardless of which sees it first. Hash of the cleaned tail.
+function frameFingerprint(viewportText) {
+  const s = String(viewportText || '').replace(/[ \t]+$/gm, '');
+  return 'intent:' + _fnv1a(s.slice(-600));
+}
+
+// First token of a real shell command. A parsed "command" whose head isn't a plausible
+// binary/builtin (or that reads like prose) signals a low-confidence parse.
+const _COMMAND_HEAD_RE = /^[\w][\w.\/-]*$/; // \w = [A-Za-z0-9_] — allow digit-leading binaries (1password, 2to3)
+function _titleLooksLikeCommand(title) {
+  const t = String(title || '').trim();
+  if (!t) return false;
+  // Prose markers a one-line command would not contain (sentence punctuation + filler).
+  if (/[.?!]\s/.test(t) || /\b(but|and|the|allow-list|permission)\b/i.test(t)) return false;
+  const head = t.split(/\s+/)[0] || '';
+  return _COMMAND_HEAD_RE.test(head);
+}
+
+// Pure ambiguity assessment over a settled frame. Returns { ambiguous, reasons }.
+// ambiguous:true ONLY when structural signals conflict / are low-confidence — a
+// confident frame returns false and the AI is never called.
+function assessAmbiguity({ providerId, viewportText } = {}) {
+  const text = String(viewportText || '');
+  const reasons = [];
+  if (!text.trim()) return { ambiguous: false, reasons };
+
+  const ws = evaluateWaitState({ providerId, viewportText: text });
+  const liveApproval = !!(approvalAgent && typeof approvalAgent.isLiveApprovalPrompt === 'function'
+    && approvalAgent.isLiveApprovalPrompt(text));
+
+  // 1) Approver gate matched a live prompt, but the canonical evaluator sees no widget
+  //    (none/input) — a shape one detector recognizes and the other does not.
+  if (liveApproval && (ws.kind === 'none' || ws.kind === 'input')) {
+    reasons.push('approver-live-but-evaluator-' + ws.kind);
+  }
+
+  // 2) Parsed an approval context whose derived title does not look like a command
+  //    (Unknown tool or scraped prose) — low-confidence parse.
+  if (approvalAgent && typeof approvalAgent.parseApprovalContext === 'function') {
+    let ctx = null;
+    try { ctx = approvalAgent.parseApprovalContext(text, providerId); } catch { ctx = null; }
+    if (ctx) {
+      let title = '';
+      try { title = (approvalAgent.escalationCommandParts(ctx).title) || ''; } catch { title = ''; }
+      if (ctx.toolName === 'Unknown' || !_titleLooksLikeCommand(title)) reasons.push('low-confidence-parse');
+    }
+  }
+
+  // 3) A numbered menu with NON-yes/no options while an approval-style question is on
+  //    screen — the approval<->choice tie (AskUserQuestion that reads like a prompt).
+  let menu = null;
+  try { menu = terminalChoice.extractTerminalChoice(text); } catch { menu = null; }
+  if (menu && Array.isArray(menu.options) && menu.options.length >= 2) {
+    const first = String((menu.options[0] && menu.options[0].label) || '').trim();
+    const firstYesNo = /^(yes|no|allow|deny|approve|reject|proceed|cancel|accept)\b/i.test(first);
+    const askApproval = /\bdo you want to\b/i.test(text) || /\?\s*$/m.test(text);
+    if (!firstYesNo && askApproval) reasons.push('nonyesno-menu-with-approval-question');
+  }
+
+  return { ambiguous: reasons.length > 0, reasons };
+}
+
+const INTENT_SYSTEM = `You classify what an AI coding CLI's terminal screen is currently asking for. Reply with ONLY JSON: {"intent":"approval"|"choice"|"none","reason":"<=1 sentence"}.
+
+Definitions:
+- "approval": the CLI is asking PERMISSION to run a TOOL or SHELL COMMAND it proposed (e.g. "Do you want to proceed?" with Yes/No, an edit/command confirmation). Acting on it means pressing yes/approve.
+- "choice": the AGENT is asking the USER to answer a question or pick among several non-yes/no options (e.g. an AskUserQuestion menu: "Which approach?" 1/2/3/4). There is nothing to auto-approve; the user must choose.
+- "none": no live interactive prompt — the agent is working/thinking, or the screen is prose/output.
+
+When unsure between "approval" and "choice", answer "choice" — never treat a user-facing question as an approval.`;
+
+const INTENT_TIMEOUT_MS = 5000;
+
+// Async LLM classification. Returns { intent:'approval'|'choice'|'none'|'unknown',
+// reason, durationMs, error? }. ANY failure (disabled provider, timeout, bad JSON,
+// bad value) -> intent:'unknown' so the caller falls back to the structural verdict.
+async function classifyPromptIntent(viewportText, { reasons, goal, cwd } = {}, { callModel, timeoutMs } = {}) {
+  const started = Date.now();
+  const call = callModel || callBackgroundLlm;
+  const screen = String(viewportText || '').replace(/[ \t]+$/gm, '').slice(-1600);
+  const ctxLine = (goal || cwd)
+    ? `Session goal: ${String(goal || '').slice(0, 200)}\nCwd: ${String(cwd || '').slice(0, 200)}\n`
+    : '';
+  const why = Array.isArray(reasons) && reasons.length ? `Detectors disagreed: ${reasons.join(', ')}.\n` : '';
+  const prompt = `${ctxLine}${why}Terminal screen (bottom of viewport):\n"""\n${screen}\n"""\n\nReturn ONLY: {"intent":"approval|choice|none","reason":"..."}`;
+
+  let response;
+  try {
+    response = await call(prompt, { system: INTENT_SYSTEM, maxTokens: 120, temperature: 0, timeoutMs: timeoutMs || INTENT_TIMEOUT_MS });
+  } catch (e) {
+    return { intent: 'unknown', reason: '', error: e.reason || e.message || String(e), durationMs: Date.now() - started };
+  }
+  const text = (response && (response.text ?? response)) || '';
+  const match = String(text).match(/\{[\s\S]*\}/);
+  if (!match) return { intent: 'unknown', reason: '', error: 'no JSON in response', durationMs: Date.now() - started };
+  let parsed;
+  try { parsed = JSON.parse(match[0]); } catch (e) { return { intent: 'unknown', reason: '', error: `parse: ${e.message}`, durationMs: Date.now() - started }; }
+  const intent = ['approval', 'choice', 'none'].includes(parsed.intent) ? parsed.intent : 'unknown';
+  const reason = typeof parsed.reason === 'string' ? parsed.reason.slice(0, 200) : '';
+  if (intent === 'unknown') return { intent, reason, error: 'bad intent value', durationMs: Date.now() - started };
+  return { intent, reason, durationMs: Date.now() - started };
+}
+
+// Pure decision the server drives for the brief hold. Inputs are the current cache /
+// pending entries for the session plus the frame fp and clock. Output tells the server
+// what to do this tick. (cachedIntent === null means a prior classification fell back.)
+function resolveIntentDecision({ cachedFp, cachedIntent, pendingFp, pendingDeadline, fp, now, holdMs } = {}) {
+  if (cachedFp === fp) {
+    return cachedIntent ? { action: 'use', intent: cachedIntent } : { action: 'fallback' };
+  }
+  if (pendingFp === fp) {
+    return now < pendingDeadline ? { action: 'hold' } : { action: 'fallback' };
+  }
+  return { action: 'start', deadline: now + (holdMs || INTENT_TIMEOUT_MS) };
+}
+
+module.exports = { frameFingerprint, assessAmbiguity, classifyPromptIntent, resolveIntentDecision, _titleLooksLikeCommand, INTENT_TIMEOUT_MS };

package/template/claude-task-manager/lib/provider-user-context.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// Provider CLIs sometimes persist operational context as `role=user` so it is
+// available to the model. These rows are not human-authored prompts and should
+// not be projected into CTM timelines, prompt history, or message search.
+const PROVIDER_GENERATED_USER_CONTEXT_PATTERNS = [
+  /^<environment_context>/i,
+  /^<permissions instructions>/i,
+  /^<collaboration_mode>/i,
+  /^<skills_instructions>/i,
+  /^<plugins_instructions>/i,
+  /^<task-notification>/i,
+  /^<skill>\s*<name>/i,
+  /^# AGENTS\.md instructions for\b/i,
+  /^Base directory for this skill:\s+/i,
+  /^This session is being continued from a previous conversation\b/i,
+  /^Continue from where you left off\b/i,
+  /^Compacted\b/i,
+  /^\[Image:\s*source:\s*(?:"[^"]+"|'[^']+'|[^\]]+)\]$/i,
+  /^\[Image:\s*original\s+\d+(?:\.\d+)?x\d+(?:\.\d+)?,\s*displayed at\s+\d+(?:\.\d+)?x\d+(?:\.\d+)?\.\s*Multiply coordinates by\s+[0-9.]+\s+to map to original image\.?\]$/i,
+  /^\[Request interrupted by user(?: for tool use)?\]$/i,
+];
+
+function isProviderGeneratedUserContextText(text) {
+  const cleaned = String(text || '').trim();
+  if (!cleaned) return false;
+  if (/^<turn_aborted>\s*[\s\S]*?<\/turn_aborted>\s*$/i.test(cleaned)) return true;
+  return PROVIDER_GENERATED_USER_CONTEXT_PATTERNS.some((pattern) => pattern.test(cleaned));
+}
+
+module.exports = {
+  PROVIDER_GENERATED_USER_CONTEXT_PATTERNS,
+  isProviderGeneratedUserContextText,
+};

package/template/claude-task-manager/lib/read-pool-client.js

@@ -0,0 +1,313 @@
+'use strict';
+
+// Client for the read/parse worker pool (workers/read-pool-worker.js).
+//
+// A small fixed pool of DB-free workers that absorb the CPU/IO-heavy *read*
+// work (JSONL parse, batch fs.stat) that otherwise blocks the main event loop.
+// Unlike the serial db-owner worker, this is a POOL: requests dispatch to the
+// least-busy worker so concurrent Conversation-tab loads + scan jobs run in
+// parallel instead of head-of-line blocking each other.
+//
+// Each worker processes its own queue serially (one op at a time), which is why
+// "least in-flight" is the right load metric. Mirrors the message protocol and
+// robustness (timeouts, fatal/exit handling, reject-all) of
+// lib/db-owner-worker-client.js.
+
+const os = require('node:os');
+const path = require('node:path');
+const { Worker } = require('node:worker_threads');
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30 * 1000;
+const DEFAULT_CLOSE_TIMEOUT_MS = 5 * 1000;
+const MIN_POOL_SIZE = 3;
+// Raised 8→12: the cores-2 default wants 14 on a 16-core box but was capped at 8, needlessly
+// throttling heavy-op concurrency (parse / prompt-index / getAllSessionsData all contend). 12
+// leaves ~4 cores for the main loop + db-owner worker. Each worker is a thread + a read-only WAL
+// connection (WAL allows many readers); smaller boxes still clamp to cores-2. CTM_READ_POOL_SIZE
+// overrides up to this cap.
+const MAX_POOL_SIZE = 12;
+
+// Ops whose cost scales with transcript/blob size (seconds, not bounded ms) and
+// can monopolize a worker during the cold-boot restore storm. They share the pool
+// with latency-sensitive bounded reads (getAllSessionsData, listRichWorktrees,
+// autoTitleCandidates, statFiles, …). If a heavy op occupies EVERY worker, those
+// small reads queue behind a 10–30s parse, hit their request timeout, and fall
+// back to the MAIN THREAD — which is exactly the [offthread-read:*] "falling back
+// to main" cascade + 28s event-loop freeze seen at boot. We cap concurrent heavy
+// ops below the pool size so ≥1 worker is always free for the light reads.
+const HEAVY_OPS = new Set([
+  'parseSessionFiles',
+  'parseConversationBlob',
+  'computeUserPromptIndex',
+  'loadCursorConversation',
+  'sessionIntegrityDetect', // ~60s full-corpus scan on cold Dropbox
+  'auditRelink',            // restore-path relink audit: full scan + per-agent cold-JSONL reads
+]);
+// Keep this many workers out of heavy reach so light reads never head-of-line
+// block behind a heavy parse. Clamped so tiny pools still allow ≥1 heavy op.
+const RESERVED_LIGHT_WORKERS = 2;
+
+function _durationMs(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.max(0, Math.trunc(n)) : fallback;
+}
+
+// Core-aware default. A fixed 3 starved the pool during the 20-session restore storm:
+// getAllSessionsData + the prompt-index compute + parseSessionFiles all contend on the same
+// workers, so the small latency-sensitive reads timed out (5s) and fell back to a main-thread
+// build/compute — the early-boot freezes the event-loop budget surfaced. On a 16-core box
+// 3 of 16 cores is a needless bottleneck. Scale to cores-2 (capped at MAX) so the boot
+// concurrency has room; CTM_READ_POOL_SIZE still overrides.
+function _coreAwareDefaultPoolSize() {
+  let cores = 0;
+  try { cores = (typeof os.availableParallelism === 'function' ? os.availableParallelism() : os.cpus().length) || 0; } catch {}
+  return Math.min(MAX_POOL_SIZE, Math.max(MIN_POOL_SIZE, cores - 2));
+}
+
+function _resolvePoolSize(requested) {
+  const raw = requested ?? process.env.CTM_READ_POOL_SIZE;
+  const n = Number(raw);
+  if (Number.isFinite(n) && n >= 1) return Math.min(MAX_POOL_SIZE, Math.trunc(n));
+  return _coreAwareDefaultPoolSize();
+}
+
+// One worker_thread + its in-flight bookkeeping. Lazily (re)spawned on first use
+// and respawned transparently after a crash so a single bad parse can't take the
+// pool down permanently.
+class _PoolWorker {
+  constructor(opts) {
+    this.workerPath = opts.workerPath;
+    this.logger = opts.logger || console;
+    this.worker = null;
+    this.ready = false;
+    this.startPromise = null;
+    this.pending = new Map(); // requestId -> { resolve, reject, timer }
+    this.nextRequestId = 1;
+    this.heavyInFlight = 0; // heavy ops currently running on THIS worker
+  }
+
+  get inFlight() { return this.pending.size; }
+
+  start() {
+    if (this.ready) return Promise.resolve(this);
+    if (this.startPromise) return this.startPromise;
+    this.startPromise = new Promise((resolve, reject) => {
+      const worker = new Worker(this.workerPath, { env: { ...process.env } });
+      this.worker = worker;
+
+      const failStart = (err) => {
+        if (this.ready) return;
+        this.startPromise = null;
+        this.worker = null;
+        try { worker.terminate(); } catch {}
+        reject(err instanceof Error ? err : new Error(String(err || 'read-pool worker failed to start')));
+      };
+
+      worker.on('message', (msg) => {
+        if (!msg || typeof msg !== 'object') return;
+        if (msg.type === 'ready') { this.ready = true; resolve(this); return; }
+        if (msg.type === 'response') { this._finish(msg.requestId, msg.error, msg.result); return; }
+        if (msg.type === 'fatal') {
+          const err = new Error(msg.message || 'read-pool worker fatal error');
+          if (!this.ready) failStart(err);
+          this._rejectAll(err);
+          return;
+        }
+        // 'status' / 'closed' are advisory for the pool — nothing to track.
+      });
+      worker.on('error', (err) => {
+        if (!this.ready) failStart(err);
+        this._rejectAll(err);
+      });
+      worker.on('exit', (code) => {
+        const wasReady = this.ready;
+        this.ready = false;
+        this.worker = null;
+        this.startPromise = null;
+        const err = new Error(`read-pool worker exited with code ${code}`);
+        if (!wasReady) failStart(err);
+        // Reject in-flight so callers fail fast and fall back to the main thread;
+        // a fresh worker is spawned on the next request.
+        if (code !== 0) this._rejectAll(err);
+        else this._rejectAll(new Error('read-pool worker closed'));
+      });
+    });
+    return this.startPromise;
+  }
+
+  async request(op, payload, timeoutMs) {
+    await this.start();
+    if (!this.worker) throw new Error('read-pool worker is not running');
+    const requestId = this.nextRequestId++;
+    return await new Promise((resolve, reject) => {
+      let timer = null;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          this.pending.delete(requestId);
+          reject(new Error(`read-pool request timed out: ${op}`));
+        }, timeoutMs);
+        if (typeof timer.unref === 'function') timer.unref();
+      }
+      this.pending.set(requestId, { resolve, reject, timer });
+      try {
+        this.worker.postMessage({ type: 'request', requestId, op, payload });
+      } catch (err) {
+        this._finish(requestId, err);
+      }
+    });
+  }
+
+  _finish(requestId, error, result) {
+    const p = this.pending.get(requestId);
+    if (!p) return;
+    this.pending.delete(requestId);
+    if (p.timer) clearTimeout(p.timer);
+    if (error) {
+      const err = error instanceof Error ? error : new Error(String(error.message || error || 'read-pool request failed'));
+      if (error.code) err.code = error.code;
+      p.reject(err);
+    } else {
+      p.resolve(result);
+    }
+  }
+
+  _rejectAll(err) {
+    const all = Array.from(this.pending.values());
+    this.pending.clear();
+    for (const p of all) { if (p.timer) clearTimeout(p.timer); p.reject(err); }
+  }
+
+  async close(timeoutMs) {
+    const worker = this.worker;
+    if (!worker) { this._rejectAll(new Error('read-pool worker closed')); return; }
+    await new Promise((resolve) => {
+      let done = false;
+      const finish = () => { if (done) return; done = true; resolve(); };
+      let timer = null;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => { worker.terminate().finally(finish); }, timeoutMs);
+        if (typeof timer.unref === 'function') timer.unref();
+      }
+      const onMessage = (msg) => {
+        if (msg?.type !== 'closed') return;
+        if (timer) clearTimeout(timer);
+        worker.off('message', onMessage);
+        finish();
+      };
+      worker.on('message', onMessage);
+      try { worker.postMessage({ type: 'close' }); }
+      catch { if (timer) clearTimeout(timer); worker.off('message', onMessage); worker.terminate().finally(finish); }
+    });
+    this.ready = false;
+    this.worker = null;
+    this._rejectAll(new Error('read-pool worker closed'));
+  }
+}
+
+class CtmReadPoolClient {
+  constructor(options = {}) {
+    this.workerPath = options.workerPath || path.resolve(__dirname, '..', 'workers', 'read-pool-worker.js');
+    this.size = _resolvePoolSize(options.size);
+    this.requestTimeoutMs = _durationMs(options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+    this.closeTimeoutMs = _durationMs(options.closeTimeoutMs, DEFAULT_CLOSE_TIMEOUT_MS);
+    this.logger = options.logger || console;
+    this._closed = false;
+    this._workers = [];
+    for (let i = 0; i < this.size; i++) {
+      this._workers.push(new _PoolWorker({ workerPath: this.workerPath, logger: this.logger }));
+    }
+    // Heavy-op admission control: reserve a couple of workers for latency-sensitive
+    // light reads so a heavy parse can't occupy the whole pool (see HEAVY_OPS note).
+    this._maxHeavy = Math.max(1, this.size - Math.min(RESERVED_LIGHT_WORKERS, this.size - 1));
+    this._heavyInFlight = 0;        // heavy ops running across the whole pool
+    this._heavyWaiters = [];        // FIFO of resolvers waiting for a heavy slot
+  }
+
+  _acquireHeavySlot() {
+    if (this._heavyInFlight < this._maxHeavy) {
+      this._heavyInFlight++;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => this._heavyWaiters.push(resolve));
+  }
+
+  _releaseHeavySlot() {
+    const next = this._heavyWaiters.shift();
+    // Hand the slot directly to the next waiter (count is conserved); otherwise free it.
+    if (next) next();
+    else this._heavyInFlight = Math.max(0, this._heavyInFlight - 1);
+  }
+
+  async start() {
+    if (this._closed) throw new Error('read pool is closed');
+    await Promise.all(this._workers.map((w) => w.start()));
+    return this;
+  }
+
+  _leastBusy() {
+    let best = this._workers[0];
+    for (const w of this._workers) {
+      if (w.inFlight < best.inFlight) best = w;
+    }
+    return best;
+  }
+
+  // Pick a worker for a request. Light reads prefer a worker with NO heavy op in
+  // flight (the reserved capacity), so they never wait behind a multi-second parse;
+  // among eligible workers, least-in-flight wins. Heavy ops just take least-busy.
+  _pickWorker(heavy) {
+    if (!heavy) {
+      let best = null;
+      for (const w of this._workers) {
+        if (w.heavyInFlight > 0) continue;
+        if (!best || w.inFlight < best.inFlight) best = w;
+      }
+      if (best) return best;
+    }
+    return this._leastBusy();
+  }
+
+  async request(op, payload = {}, options = {}) {
+    if (this._closed) throw new Error('read pool is closed');
+    if (!op) throw new Error('read pool request requires op');
+    const timeoutMs = _durationMs(options.timeoutMs, this.requestTimeoutMs);
+    const heavy = options.heavy ?? HEAVY_OPS.has(op);
+    if (!heavy) return await this._pickWorker(false).request(op, payload, timeoutMs);
+
+    // Heavy op: wait for an admission slot, then dispatch to the least-busy worker.
+    await this._acquireHeavySlot();
+    const worker = this._pickWorker(true);
+    worker.heavyInFlight++;
+    try {
+      return await worker.request(op, payload, timeoutMs);
+    } finally {
+      worker.heavyInFlight = Math.max(0, worker.heavyInFlight - 1);
+      this._releaseHeavySlot();
+    }
+  }
+
+  getStatus() {
+    return {
+      size: this.size,
+      closed: this._closed,
+      maxHeavy: this._maxHeavy,
+      heavyInFlight: this._heavyInFlight,
+      heavyWaiting: this._heavyWaiters.length,
+      workers: this._workers.map((w) => ({ ready: w.ready, inFlight: w.inFlight, heavyInFlight: w.heavyInFlight })),
+      inFlight: this._workers.reduce((s, w) => s + w.inFlight, 0),
+    };
+  }
+
+  async close() {
+    if (this._closed) return { ok: true, alreadyClosed: true };
+    this._closed = true;
+    await Promise.all(this._workers.map((w) => w.close(this.closeTimeoutMs).catch(() => {})));
+    return { ok: true };
+  }
+}
+
+function createReadPoolClient(options = {}) {
+  return new CtmReadPoolClient(options);
+}
+
+module.exports = { CtmReadPoolClient, createReadPoolClient };

package/template/claude-task-manager/lib/readpool-breaker.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// Generic circuit breaker for off-thread read-pool calls (getAllSessionsData, the prompt
+// index compute, message/timeline parse, ...). At early boot a worker's read-only
+// connection can't attach to the WAL shared-memory until a writer is established + the DB
+// settles, so the request times out. Without a breaker, every off-thread call in that
+// window waits the full timeout and then falls back to a cold main-thread build.
+//
+// After `degradeAfter` consecutive failures the breaker OPENS for `cooldownMs`; while open,
+// the caller SKIPS the off-thread attempt (serving cache/SWR) rather than timing out into a
+// main build. One success CLOSES it (half-open: the first attempt after the cooldown probes
+// the pool again). Pure + injectable clock for testing.
+
+function createReadPoolBreaker({ degradeAfter = 2, cooldownMs = 30000 } = {}) {
+  const _degradeAfter = Math.max(1, Number(degradeAfter) || 1);
+  const _cooldownMs = Math.max(0, Number(cooldownMs) || 0);
+  let failures = 0;
+  let openUntil = 0;
+  return {
+    isOpen(now) { return Number(now) < openUntil; },
+    recordFailure(now) {
+      failures += 1;
+      if (failures >= _degradeAfter) openUntil = Number(now) + _cooldownMs;
+      return { failures, openUntil };
+    },
+    recordSuccess() { failures = 0; openUntil = 0; },
+    getState() { return { failures, openUntil, degradeAfter: _degradeAfter, cooldownMs: _cooldownMs }; },
+  };
+}
+
+module.exports = { createReadPoolBreaker };

package/template/claude-task-manager/lib/recent-sessions-breaker.js

@@ -0,0 +1,12 @@
+'use strict';
+
+// Back-compat re-export. The circuit breaker is now the generic lib/readpool-breaker.js
+// (shared by getAllSessionsData, the prompt-index compute, and future off-thread reads).
+// `createRecentSessionsBreaker` remains as an alias so existing imports keep working.
+
+const { createReadPoolBreaker } = require('./readpool-breaker');
+
+module.exports = {
+  createReadPoolBreaker,
+  createRecentSessionsBreaker: createReadPoolBreaker,
+};