cc-viewer 1.8.4 → 1.8.7

package/server/lib/launch-config.js

@@ -39,6 +39,37 @@ export function withDefaultThinkingDisplay(args) {
   return hasFlag ? args : [...args, '--thinking-display', 'summarized'];
 }
 
+// Tokens after a literal `--` are prompt text for claude — any flag appended there is
+// silently swallowed as part of the prompt. cc-viewer's injected flags (system-prompt
+// file args, `--thinking-display`) must therefore land in the user-flag region BEFORE
+// the first literal `--`. Both spawn links (PTY pty-manager / headless runProxyCommand)
+// share this helper so the byte order stays consistent and neither path re-introduces
+// the "flag landed after `--`" misplacement.
+//
+// Pure function — never mutates the input. Two steps:
+//   1. splice `injections` in just before the first literal `--` (or at the end when absent);
+//   2. relocate any `--thinking-display <value>` pair that ended up at/after `--`
+//      (it is appended at the very end by withDefaultThinkingDisplay) to just before `--`.
+// User-supplied `--thinking-display` written before `--` is left untouched.
+export function insertBeforeDashDash(args, injections = []) {
+  if (!Array.isArray(args)) return args;
+  const out = [...args];
+  const dd = () => out.indexOf('--');
+  if (injections.length) {
+    const at = dd();
+    out.splice(at === -1 ? out.length : at, 0, ...injections);
+  }
+  const live = dd();
+  if (live !== -1) {
+    const tdIdx = out.indexOf('--thinking-display', live);
+    if (tdIdx !== -1) {
+      const pair = out.splice(tdIdx, 2); // ['--thinking-display', value]
+      out.splice(out.indexOf('--'), 0, ...pair);
+    }
+  }
+  return out;
+}
+
 // Parse continuation flags from claude args: -c/--continue, -r/--resume (value as the
 // next token or in = form), --fork-session. Returns null for non-continuation launches;
 // picker=true means a valueless -r (interactive picker — target unknowable at spawn).

package/server/lib/search-worker.js

@@ -0,0 +1,214 @@
+// Search worker — runs the pure-node fallback engine OFF the server's event loop.
+//
+// Why: the node engine does per-file sync fs (lstat/realpath/stat/read up to 1MB) plus a JS
+// RegExp over every line. On the main loop that pins the whole server (in Electron each tab's
+// server is a forked process, so a scan would freeze its SSE/WS/PTY traffic). Inside a
+// worker the sync calls only block the worker's own loop — harmless.
+//
+// Protocol (one job per Worker instance; the parent terminates on completion/abort):
+//   in : workerData { root, query, caseSensitive, wholeWord, regex, includeGlobs, excludeGlobs,
+//                     maxResults, maxMatchesPerFile, maxFileSize, nodeTimeBudgetMs }
+//   out: parentPort.postMessage({ type: 'done', results, truncated, filesScanned })
+//        parentPort.postMessage({ type: 'error', error: 'invalid_regex' | 'search_failed' })
+//
+// Environment note: this file is imported by node --test in the parent process for direct
+// runNodeScan unit coverage, so everything executes lazily inside the `if (parentPort)` guard.
+import { isMainThread, parentPort, workerData } from 'node:worker_threads';
+import { readFileSync, readdirSync, lstatSync, statSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+import { isReadAllowed } from './file-access-policy.js';
+import {
+  buildQueryRegExp, looksCatastrophic, globToRegExp,
+  isHidden, hasIgnoredSegment, normRel, isBinary, IGNORED_NAMES, DEFAULTS,
+} from './code-search.js';
+
+// Kill a hung `git ls-files` (index.lock contention, slow/NFS mount). Unrelated to the scan
+// time budget.
+const GIT_LS_FILES_TIMEOUT_MS = 8000;
+
+// Yield cadence: every FILE_YIELD_INTERVAL candidates AND every BYTE_YIELD_BUDGET bytes read,
+// whichever comes first — a few 1MB files must not starve the worker's own loop between the
+// 64-file ticks (the budget keeps postMessage/terminate latency low).
+const FILE_YIELD_INTERVAL = 64;
+const BYTE_YIELD_BUDGET = 4 * 1024 * 1024;
+
+function makeGlobFilter(includeGlobs, excludeGlobs) {
+  // Parity with rg: a '!'-prefixed entry in the include field is a negation (exclude),
+  // mirroring rg's `-g !glob`. globToRegExp strips the leading '!'.
+  const inc = [];
+  const exc = [];
+  for (const g of includeGlobs || []) { if (!g) continue; (g.startsWith('!') ? exc : inc).push(globToRegExp(g)); }
+  for (const g of excludeGlobs || []) { if (!g) continue; exc.push(globToRegExp(g)); }
+  return (relPath) => {
+    if (inc.length && !inc.some((r) => r.test(relPath))) return false;
+    if (exc.some((r) => r.test(relPath))) return false;
+    return true;
+  };
+}
+
+function createGrouper(maxResults, maxMatchesPerFile) {
+  const byFile = new Map();
+  let total = 0;
+  let capped = false; // a per-file or global cap dropped some matches
+  return {
+    /** @returns {boolean} true if still under the global cap, false once maxResults is hit */
+    add(file, match) {
+      if (total >= maxResults) { capped = true; return false; }
+      let entry = byFile.get(file);
+      if (!entry) { entry = []; byFile.set(file, entry); }
+      if (entry.length >= maxMatchesPerFile) { capped = true; return true; }
+      entry.push(match);
+      total++;
+      return total < maxResults;
+    },
+    get total() { return total; },
+    get capped() { return capped; },
+    results() {
+      return [...byFile.entries()].map(([file, matches]) => ({ file, matches }));
+    },
+  };
+}
+
+function gitListFiles(root) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'],
+        { cwd: root, windowsHide: true });
+    } catch { resolve(null); return; }
+    let out = '';
+    const decoder = new StringDecoder('utf8');
+    // Bound a hung git (index.lock contention, slow/NFS mount) so the scan always resolves.
+    const timer = setTimeout(() => { try { child.kill(); } catch { /* gone */ } }, GIT_LS_FILES_TIMEOUT_MS);
+    child.stdout.on('data', (d) => { out += decoder.write(d); });
+    child.stdout.on('error', () => {});
+    child.on('error', () => { clearTimeout(timer); resolve(null); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      out += decoder.end();
+      if (code !== 0) { resolve(null); return; }
+      resolve(out.split('\0').filter(Boolean));
+    });
+  });
+}
+
+function walkDir(root) {
+  const out = [];
+  const stack = [''];
+  while (stack.length) {
+    const rel = stack.pop();
+    let entries;
+    try { entries = readdirSync(rel ? join(root, rel) : root, { withFileTypes: true }); }
+    catch { continue; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || IGNORED_NAMES.has(e.name)) continue;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isSymbolicLink()) continue; // don't follow symlinks (parity + safety)
+      if (e.isDirectory()) stack.push(childRel);
+      else if (e.isFile()) out.push(childRel);
+    }
+  }
+  return out;
+}
+
+/**
+ * The full node-engine scan (former nodeSearch body, semantics unchanged).
+ * No AbortSignal input: cancellation is the parent terminating the worker. The cooperative
+ * time-budget/cap exits are unchanged from the in-process implementation.
+ * Exported for direct unit coverage (node --test runs this file with isMainThread=true).
+ */
+export async function runNodeScan(opts) {
+  // Catastrophic-backtracking guard applies ONLY to the JS-backtracking node engine (ripgrep's
+  // engine is linear and safe), so it lives here rather than gating the rg path too.
+  if (opts.regex && looksCatastrophic(opts.query)) {
+    return { results: [], truncated: false, filesScanned: 0, error: 'invalid_regex' };
+  }
+  let queryRe;
+  try {
+    queryRe = buildQueryRegExp(opts);
+  } catch {
+    return { results: [], truncated: false, filesScanned: 0, error: 'invalid_regex' };
+  }
+  const maxResults = opts.maxResults ?? DEFAULTS.maxResults;
+  const maxPerFile = opts.maxMatchesPerFile ?? DEFAULTS.maxMatchesPerFile;
+  const maxFileSize = opts.maxFileSize ?? DEFAULTS.maxFileSize;
+  const timeBudget = opts.nodeTimeBudgetMs ?? DEFAULTS.nodeTimeBudgetMs;
+  const started = Date.now();
+
+  let candidates = await gitListFiles(opts.root);
+  if (candidates == null) candidates = walkDir(opts.root);
+  candidates = candidates.map(normRel).filter((p) => !isHidden(p) && !hasIgnoredSegment(p));
+
+  const passesGlob = makeGlobFilter(opts.includeGlobs, opts.excludeGlobs);
+  const grouper = createGrouper(maxResults, maxPerFile);
+  const scanned = new Set();
+  let truncated = false;
+  let processed = 0;
+  let bytesSinceYield = 0;
+
+  for (const rel of candidates) {
+    if (Date.now() - started > timeBudget) { truncated = true; break; }
+    // Yield to the worker's own event loop periodically so a large scan stays responsive to a
+    // terminate() and a candidate list in the tens of thousands doesn't monopolize the loop.
+    if ((processed++ % FILE_YIELD_INTERVAL) === 0 || bytesSinceYield >= BYTE_YIELD_BUDGET) {
+      bytesSinceYield = 0;
+      await new Promise((r) => setImmediate(r));
+    }
+    if (!passesGlob(rel)) continue;
+
+    const full = join(opts.root, rel);
+    let lst;
+    try { lst = lstatSync(full); } catch { continue; }
+    if (lst.isSymbolicLink()) continue; // never follow symlinks
+
+    let real;
+    try { real = realpathSync(full); } catch { continue; }
+    const policy = isReadAllowed(real);
+    if (!policy.ok) continue;
+
+    let st;
+    try { st = statSync(real); } catch { continue; }
+    if (!st.isFile() || st.size > maxFileSize) continue;
+
+    let raw;
+    try { raw = readFileSync(real); } catch { continue; }
+    bytesSinceYield += raw.length;
+    if (isBinary(raw)) continue;
+
+    scanned.add(rel);
+    const lines = raw.toString('utf8').split(/\r?\n/);
+    let stop = false;
+    for (let i = 0; i < lines.length && !stop; i++) {
+      const text = lines[i];
+      if (!text || text.length > DEFAULTS.maxLineLength) continue; // skip empty / pathological long lines
+      queryRe.lastIndex = 0;
+      const submatches = [];
+      let m;
+      while ((m = queryRe.exec(text)) !== null) {
+        const start = m.index;
+        const end = m.index + m[0].length;
+        if (end > start) submatches.push({ start, end });
+        if (m.index === queryRe.lastIndex) queryRe.lastIndex++; // zero-width guard
+        if (submatches.length >= 1000) break; // pathological single-line match count
+      }
+      if (submatches.length) {
+        const ok = grouper.add(rel, { line: i + 1, text: text.slice(0, DEFAULTS.maxLineLength), submatches });
+        if (!ok) { truncated = true; stop = true; }
+      }
+    }
+    if (stop) break;
+  }
+  return { results: grouper.results(), truncated: truncated || grouper.capped, filesScanned: scanned.size };
+}
+
+// ─── worker entry (skipped under node --test in the parent process) ───
+if (!isMainThread && parentPort) {
+  runNodeScan(workerData || {})
+    .then((r) => {
+      if (r.error) parentPort.postMessage({ type: 'error', error: r.error });
+      else parentPort.postMessage({ type: 'done', results: r.results, truncated: r.truncated, filesScanned: r.filesScanned });
+    })
+    .catch(() => parentPort.postMessage({ type: 'error', error: 'search_failed' }));
+}

package/server/lib/session-start-bridge.js

@@ -60,17 +60,21 @@ let sessionId = null;
 let transcriptPath = null;
 let source = null;
 let cwd = null;
+let agentId = null;
 try {
   const parsed = JSON.parse(stdinData);
   sessionId = parsed?.session_id || null;
   transcriptPath = parsed?.transcript_path || null;
   source = parsed?.source || null;
   cwd = parsed?.cwd || null;
+  // Present only when the hook fires from within a subagent/teammate process;
+  // the server uses it to skip session-boundary resets for shared state.
+  agentId = parsed?.agent_id || null;
 } catch { /* fine — the server tolerates missing fields */ }
 debug(`payload source=${source} session_id=${sessionId} transcript=${transcriptPath}`);
 
 const internalToken = process.env.CCVIEWER_INTERNAL_TOKEN || '';
-const body = JSON.stringify({ source, sessionId, transcriptPath, cwd, ts: Date.now() });
+const body = JSON.stringify({ source, sessionId, transcriptPath, cwd, agentId, ts: Date.now() });
 const reqOpts = {
   hostname: '127.0.0.1',
   port: parseInt(port, 10),

package/server/lib/task-bridge.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * task-bridge.js — hook bridge for Claude Code's task-checklist events.
+ *
+ * Feeds the GUI task-progress HUD: forwards every task mutation to cc-viewer's
+ * /api/task-event, where server/lib/task-state.js maintains the checklist and
+ * broadcasts it over SSE (`task_update`).
+ *
+ * Hook config in ~/.claude/settings.json (injected by ensure-hooks.js, tagged
+ * `# cc-viewer-managed`):
+ *   "hooks": {
+ *     "TaskCreated":  [{ "hooks": [{ "type": "command", "command": "... task-bridge.js ..." }] }],
+ *     "TaskCompleted":[{ "hooks": [{ "type": "command", "command": "... task-bridge.js ..." }] }],
+ *     "PostToolUse":  [{ "matcher": "TaskUpdate", "hooks": [{ "type": "command", ... }] }]
+ *   }
+ *
+ * Payload shapes (CC 2.1.x):
+ *   TaskCreated/TaskCompleted: { hook_event_name, session_id, transcript_path,
+ *     cwd, task_id, task_subject, task_description?, teammate_name?, agent_id? }
+ *   PostToolUse(TaskUpdate):   { hook_event_name: "PostToolUse", session_id, ...,
+ *     tool_name: "TaskUpdate", tool_input: { taskId, status?, owner?,
+ *     subject?, description?, activeForm? } }
+ *
+ * Output contract (same as session-start-bridge.js): NOTHING on stdout —
+ * PostToolUse interprets stdout starting with "{" as decision JSON, and any
+ * stray bytes pollute the hook chain. Optional stderr only when
+ * CCVIEWER_DEBUG=1. ALWAYS exit 0: exit code 2 on TaskCreated/TaskCompleted
+ * rolls back task creation / prevents completion, so a failed notify must
+ * never surface as a non-zero exit.
+ */
+
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+
+const debug = (msg) => {
+  if (process.env.CCVIEWER_DEBUG === '1') {
+    try { process.stderr.write(`[task-bridge] ${msg}\n`); } catch { /* ignore */ }
+  }
+};
+
+const port = process.env.CCVIEWER_PORT;
+const rawProtocol = process.env.CCVIEWER_PROTOCOL;
+const isHttps = rawProtocol === 'https';
+const httpClient = isHttps ? https : http;
+
+// cc-viewer not running — exit silently (stdout must stay clean, see header).
+if (!port) {
+  debug('CCVIEWER_PORT unset — exit silently');
+  process.exit(0);
+}
+
+// Drain stdin best-effort; capped to 64 KB to defang malformed huge payloads.
+let stdinData = '';
+try {
+  const buf = readFileSync(0);
+  stdinData = (buf.length > 64 * 1024 ? buf.slice(0, 64 * 1024) : buf).toString('utf-8');
+} catch { /* stdin may not be piped — fine, still notify */ }
+
+let parsed = null;
+try {
+  parsed = JSON.parse(stdinData);
+} catch { /* fine — the server tolerates missing fields */ }
+
+// Normalize to one canonical camelCase envelope regardless of hook event.
+// TaskCreated/TaskCompleted carry snake_case task fields at the top level;
+// PostToolUse carries a camelCase tool_input. Read both aliases defensively.
+const hookEventName = parsed?.hook_event_name || null;
+const toolInput = (parsed?.tool_input && typeof parsed.tool_input === 'object') ? parsed.tool_input : {};
+const body = JSON.stringify({
+  hookEventName,
+  toolName: parsed?.tool_name || null,
+  sessionId: parsed?.session_id || null,
+  transcriptPath: parsed?.transcript_path || null,
+  cwd: parsed?.cwd || null,
+  teammateName: parsed?.teammate_name || null,
+  agentId: parsed?.agent_id || null,
+  taskId: parsed?.task_id ?? toolInput.taskId ?? null,
+  taskSubject: parsed?.task_subject ?? toolInput.subject ?? null,
+  taskDescription: parsed?.task_description ?? toolInput.description ?? null,
+  status: toolInput.status ?? null,
+  owner: toolInput.owner ?? null,
+  activeForm: toolInput.activeForm ?? null,
+  ts: Date.now(),
+});
+debug(`payload event=${hookEventName} tool=${parsed?.tool_name} taskId=${parsed?.task_id ?? toolInput.taskId}`);
+
+const internalToken = process.env.CCVIEWER_INTERNAL_TOKEN || '';
+const reqOpts = {
+  hostname: '127.0.0.1',
+  port: parseInt(port, 10),
+  path: '/api/task-event',
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(body),
+    // Same anti-spoof header as the other bridges: matched against the
+    // server's per-startup INTERNAL_TOKEN, env-leaked only to the claude child.
+    ...(internalToken ? { 'X-CCViewer-Internal': internalToken } : {}),
+  },
+  // Keep the timeout snappy so a stale cc-viewer never blocks the Claude Code
+  // hook chain for a noticeable beat.
+  timeout: 500,
+};
+if (isHttps) {
+  // Loopback HTTPS is typically self-signed; validation would reject.
+  reqOpts.rejectUnauthorized = false;
+}
+
+let exited = false;
+const finish = (reason) => {
+  if (exited) return;
+  exited = true;
+  if (reason) debug(reason);
+  process.exit(0);
+};
+
+let req;
+try {
+  req = httpClient.request(reqOpts, (res) => {
+    res.resume();
+    res.on('end', () => finish(`POST done (status=${res.statusCode})`));
+  });
+  req.on('error', (err) => finish(`POST error: ${err?.message}`));
+  req.on('timeout', () => { try { req.destroy(); } catch { /* ignore */ } finish('POST timeout'); });
+  // Wrap the synchronous write/end so an immediate EPIPE never bubbles into
+  // Claude Code's transcript (same defensive shape as the other bridges).
+  try {
+    req.write(body);
+    req.end();
+  } catch (err) {
+    finish(`req.write threw: ${err?.message}`);
+  }
+} catch (err) {
+  finish(`request() threw: ${err?.message}`);
+}

package/server/lib/task-state.js

@@ -0,0 +1,150 @@
+/**
+ * task-state.js — in-memory reducer for the Claude Code task checklist.
+ *
+ * Maintains the single shared checklist of the session this cc-viewer process
+ * hosts (fed by task-bridge.js via POST /api/task-event → deps.onTaskEvent).
+ * The checklist is deliberately ONE map, not per-session: the main agent and
+ * its teammates share the same task list in Claude Code, and each cc-viewer
+ * server process only receives hooks from its own claude child tree
+ * (CCVIEWER_PORT is injected per child). Cross-session leftovers are cleared
+ * by resetTasks() on session boundaries (startup/clear from the MAIN agent —
+ * see server.js onTaskSessionBoundary, which skips subagent events via
+ * agentId).
+ *
+ * L1-lib: pure module, Node builtins only, no imports.
+ */
+
+/** @type {string|null} last seen main session id (SSE tagging only) */
+let _sessionId = null;
+/** @type {Map<string, object>} insertion order = stable display order */
+const _tasks = new Map();
+
+const VALID_STATUSES = new Set(['pending', 'in_progress', 'completed', 'deleted']);
+
+function _touch(task) {
+  task.updatedAt = Date.now();
+  return task;
+}
+
+/**
+ * Apply one normalized task event (the camelCase envelope task-bridge.js
+ * POSTs). Unknown/malformed payloads are ignored.
+ * @param {object} payload
+ */
+export function applyTaskEvent(payload) {
+  if (!payload || typeof payload !== 'object') return;
+  const { hookEventName } = payload;
+  const taskId = payload.taskId != null ? String(payload.taskId) : null;
+  // Validate BEFORE touching the session tag: a malformed/unknown event must
+  // not move the shouldResetTasks comparison base.
+  if (!taskId) return;
+  if (payload.sessionId && !payload.agentId) _sessionId = payload.sessionId;
+
+  if (hookEventName === 'TaskCreated') {
+    const existing = _tasks.get(taskId);
+    if (existing) {
+      // Idempotent re-fire: keep the current status, refresh the text fields
+      // and the teammate attribution (same field set as TaskCompleted).
+      if (payload.taskSubject != null) existing.subject = payload.taskSubject;
+      if (payload.taskDescription != null) existing.description = payload.taskDescription;
+      if (payload.teammateName != null) existing.teammateName = payload.teammateName;
+      _touch(existing);
+      return;
+    }
+    _tasks.set(taskId, _touch({
+      taskId,
+      subject: payload.taskSubject ?? null,
+      description: payload.taskDescription ?? null,
+      activeForm: null,
+      status: 'pending',
+      owner: null,
+      teammateName: payload.teammateName ?? null,
+      agentId: payload.agentId ?? null,
+      createdAt: Date.now(),
+    }));
+    return;
+  }
+
+  if (hookEventName === 'TaskCompleted') {
+    const existing = _tasks.get(taskId) || _stub(taskId, payload);
+    if (!_tasks.has(taskId)) _tasks.set(taskId, existing);
+    existing.status = 'completed';
+    if (payload.taskSubject != null) existing.subject = payload.taskSubject;
+    if (payload.taskDescription != null) existing.description = payload.taskDescription;
+    if (payload.teammateName != null) existing.teammateName = payload.teammateName;
+    _touch(existing);
+    return;
+  }
+
+  if (hookEventName === 'PostToolUse' && payload.toolName === 'TaskUpdate') {
+    const status = VALID_STATUSES.has(payload.status) ? payload.status : null;
+    if (status === 'deleted') {
+      _tasks.delete(taskId);
+      return;
+    }
+    const existing = _tasks.get(taskId) || _stub(taskId, payload);
+    if (!_tasks.has(taskId)) _tasks.set(taskId, existing);
+    // Patch only the fields present in the event; a TaskUpdate may carry any
+    // subset (status flips, renames, owner claims). Re-opening a completed
+    // task (completed → in_progress → pending) is valid and passed through.
+    if (status) existing.status = status;
+    if (payload.taskSubject != null) existing.subject = payload.taskSubject;
+    if (payload.taskDescription != null) existing.description = payload.taskDescription;
+    if (payload.activeForm != null) existing.activeForm = payload.activeForm;
+    if (payload.owner != null) existing.owner = payload.owner;
+    if (payload.teammateName != null) existing.teammateName = payload.teammateName;
+    if (payload.agentId != null) existing.agentId = payload.agentId;
+    _touch(existing);
+    return;
+  }
+  // Unknown events (e.g. future Task* hooks) are ignored by design.
+}
+
+// Stub entry for updates that reference a task created before cc-viewer (or
+// the hook chain) started watching — the frontend renders a placeholder.
+function _stub(taskId, payload) {
+  return _touch({
+    taskId,
+    subject: payload.taskSubject ?? null,
+    description: payload.taskDescription ?? null,
+    activeForm: payload.activeForm ?? null,
+    status: 'pending',
+    owner: payload.owner ?? null,
+    teammateName: payload.teammateName ?? null,
+    agentId: payload.agentId ?? null,
+    createdAt: Date.now(),
+  });
+}
+
+/** Clear the whole checklist (session boundary: startup/clear by main agent). */
+export function resetTasks() {
+  _tasks.clear();
+  _sessionId = null;
+}
+
+/**
+ * Session-boundary gate (pure, unit-tested): the shared checklist resets on
+ * main-agent startup/clear, and on resume/fork to a DIFFERENT session (an
+ * in-terminal /resume switches conversations — old tasks must not mix into
+ * the resumed one; resuming the SAME session keeps the list). Subagent/
+ * teammate processes inherit CCVIEWER_PORT and fire their own SessionStart
+ * 'startup' events — those are identified by payload.agentId and must NOT
+ * wipe the shared list.
+ */
+export function shouldResetTasks(payload, currentSessionId) {
+  const { source, agentId, sessionId } = payload || {};
+  if (agentId) return false;
+  if (source === 'startup' || source === 'clear') return true;
+  if ((source === 'resume' || source === 'fork') && sessionId && sessionId !== currentSessionId) return true;
+  return false;
+}
+
+/** Full-snapshot view for SSE broadcast; insertion order preserved. */
+export function getTaskSnapshot() {
+  return { sessionId: _sessionId, tasks: [..._tasks.values()] };
+}
+
+/** Test hook: restore pristine module state. */
+export function __resetForTests() {
+  resetTasks();
+}

package/server/pty-manager.js

@@ -12,7 +12,7 @@ import { mergeSettingsIntoArgs } from './lib/settings-merge.js';
 import { MODEL_PROMPT_DIR } from './lib/model-system-prompts.js';
 // Launch-time system-prompt/thinking-display pipeline lives in lib/launch-config.js
 // (shared with the SDK link). Re-exported here for existing consumers/tests.
-import { withDefaultThinkingDisplay, resolveLaunchSystemPrompt } from './lib/launch-config.js';
+import { withDefaultThinkingDisplay, resolveLaunchSystemPrompt, insertBeforeDashDash } from './lib/launch-config.js';
 export { withDefaultThinkingDisplay } from './lib/launch-config.js';
 import { t, tFor } from './i18n.js';
 
@@ -437,7 +437,13 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
     console.warn('[CC Viewer] system prompt build/render failed, launching without injected prompt:', err?.message || err);
     sysPrompt = { args: [], loaded: [], model: null, entries: [] };
   }
-  const launchArgs = sysPrompt.args.length ? [...finalExtraArgs, ...sysPrompt.args] : finalExtraArgs;
+  // Inject the system-prompt args before a literal `--` (tokens after it are prompt text
+  // and would swallow a flag), and relocate `--thinking-display` out of the prompt region
+  // too. Shared with the headless run link via launch-config.js so both spawn paths keep
+  // the same byte order.
+  const launchArgs = sysPrompt.args.length || finalExtraArgs.includes('--thinking-display')
+    ? insertBeforeDashDash(finalExtraArgs, sysPrompt.args)
+    : finalExtraArgs;
 
   let command = claudePath;
   let args = ['--settings', settingsJson, ...launchArgs];

package/server/routes/events.js

@@ -90,6 +90,54 @@ function sessionStartNotify(req, res, parsedUrl, isLocal, deps) {
     }
     try { deps.onSessionStartNotify(payload); }
     catch (err) { reportSwallowed('session-start-notify.dispatch', err); }
+    // Task-checklist boundary: reset on main-agent startup/clear, skipped for
+    // subagent events (payload.agentId). Separate deps callback so it is never
+    // swallowed by markSessionStart's source early-return.
+    try { deps.onTaskSessionBoundary?.(payload); }
+    catch (err) { reportSwallowed('task-session-boundary', err); }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true }));
+  });
+}
+
+// Task-event hook notify (task-bridge.js): TaskCreated / TaskCompleted /
+// PostToolUse(TaskUpdate) → the task-checklist reducer. Same security shape
+// as sessionStartNotify (loopback-only + internal token + 16KB cap); the
+// state update + debounced SSE broadcast live behind deps.onTaskEvent
+// (server.js → lib/task-state.js).
+function taskEventNotify(req, res, parsedUrl, isLocal, deps) {
+  if (!isLocal) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Loopback only' }));
+    return;
+  }
+  if (req.headers['x-ccviewer-internal'] !== deps.INTERNAL_TOKEN) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Invalid bridge token' }));
+    return;
+  }
+  let body = '';
+  let truncated = false;
+  req.on('data', chunk => {
+    body += chunk;
+    if (body.length > 16384) { truncated = true; req.destroy(); }
+  });
+  req.on('end', () => {
+    if (truncated) {
+      console.warn('[task-event] body exceeded 16KB cap — request destroyed');
+      return; // socket already closed by destroy()
+    }
+    let payload = {};
+    let badJson = false;
+    try { payload = body ? JSON.parse(body) : {}; }
+    catch { badJson = true; console.warn('[task-event] malformed JSON body'); }
+    if (badJson) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'malformed JSON body' }));
+      return;
+    }
+    try { deps.onTaskEvent?.(payload); }
+    catch (err) { reportSwallowed('task-event.dispatch', err); }
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ ok: true }));
   });
@@ -362,6 +410,13 @@ async function events(req, res, parsedUrl, isLocal, deps) {
   // 这样 watcher 的 sendToClients 不会在 load 阶段向该客户端推送 live entry。
   deps.clients.push(res);
 
+  // 任务清单快照补推：内存态不在冷加载数据里，页面刷新/重连后横条要等下一次
+  // 任务事件才恢复 —— 连接建立即推一份当前快照（空列表也推，清掉客户端残留）。
+  try {
+    const snap = deps.getTaskSnapshot?.();
+    if (snap) sseWrite(res, `event: task_update\ndata: ${JSON.stringify({ sessionId: snap.sessionId, tasks: snap.tasks, ts: Date.now() })}\n\n`);
+  } catch (err) { reportSwallowed('sse.task_update.snapshot', err); }
+
   // req.on('close') 在某些异常断连时不一定立即触发；res 端 close/error 兜底保证
   // 不会在 clients 数组里留下幽灵 res，防止 sendToClients 后续写入触发慢泄漏。
   const removeFromClients = () => {
@@ -402,6 +457,7 @@ async function requests(req, res) {
 export const eventsRoutes = [
   { method: 'POST', match: 'exact', path: '/api/turn-end-notify', handler: turnEndNotify },
   { method: 'POST', match: 'exact', path: '/api/session-start-notify', handler: sessionStartNotify },
+  { method: 'POST', match: 'exact', path: '/api/task-event', handler: taskEventNotify },
   { method: 'GET', match: 'exact', path: '/events', handler: events },
   { method: 'GET', match: 'exact', path: '/api/requests', handler: requests },
 ];