@yemi33/minions 0.1.1985 → 0.1.1987

package/bin/minions.js

@@ -27,6 +27,7 @@
  *   minions kill                     Kill active agents and reset to pending
  *   minions complete <dispatch-id>   Mark a dispatch completed
  *   minions config set-cli <R> [--model M]  Persist default runtime/model
+ *   minions bridge <subcmd>          Constellation bridge: status|health|enable|disable
  *   minions plan <file|text> [proj]  Run a plan
  *   minions mcp-sync                 Sync MCP servers from ~/.claude.json
  *   minions nuke --confirm           Factory reset runtime state/config
@@ -681,7 +682,7 @@ const engineCmds = new Set([
   'start', 'stop', 'status', 'pause', 'resume',
   'queue', 'sources', 'discover', 'dispatch',
   'spawn', 'work', 'cleanup', 'mcp-sync', 'plan',
-  'kill', 'complete', 'config', 'pr',
+  'kill', 'complete', 'config', 'pr', 'bridge',
 ]);
 
 if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
@@ -714,6 +715,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     minions complete <dispatch-id>   Manually mark a dispatch as completed
     minions config set-cli <R> [--model M]
                                       Persist default runtime/model without starting
+    minions bridge <subcmd>          Constellation bridge: status|health|enable|disable
     minions mcp-sync                 Sync MCP servers from ~/.claude.json
     minions cleanup                  Clean temp files, worktrees, zombies
     minions pr comment <repo> <n>    Post a marker-prepended PR comment via gh

package/dashboard/js/qa.js

@@ -0,0 +1,53 @@
+// dashboard/js/qa.js — QA tab wiring (W-mpd5ewhj000oc5c5).
+//
+// The QA tab is the canonical home for long-running test/validation surfaces.
+// Phase 1 (this WI) mounts the managed-spawn + keep-processes panels into the
+// QA page using the shared mount API on render-managed.js + render-other.js.
+// The Engine page keeps its own mount registered eagerly inside those modules
+// so dual-render works (engine.html and qa.html show the same data, fed by
+// the same poll loop in refresh.js — no extra fetches, no extra SSE streams).
+//
+// SSE log streaming is lazy: openManagedLog() opens a single EventSource on
+// user click and closeManagedLog() aborts it. The modal is a singleton, so
+// opening from either tab doesn't multiply connections (cf. render-managed.js
+// "single-stream invariant").
+//
+// Out of scope: actual runbook dispatch wiring. The placeholder card with the
+// disabled "+ New runbook" button is the only UX hook for the next phase.
+
+(function () {
+  function _registerQaMounts() {
+    if (typeof mountManagedProcessesPanel === 'function') {
+      mountManagedProcessesPanel({
+        contentId: 'qa-managed-processes-content',
+        countId: 'qa-managed-processes-count',
+      });
+    }
+    if (typeof mountKeepProcessesPanel === 'function') {
+      mountKeepProcessesPanel({
+        contentId: 'qa-keep-processes-content',
+        countId: 'qa-keep-processes-count',
+      });
+    }
+  }
+
+  // The page fragment is in the DOM at script-load time (all .page divs are
+  // assembled into layout.html at build), so registering immediately is safe.
+  // The mount API is no-op when the QA fragment is missing (defensive).
+  _registerQaMounts();
+
+  // Close any open managed-log SSE stream when the user navigates away from a
+  // page that triggered it — the modal otherwise floats over the new page and
+  // the EventSource keeps streaming. Hooks into the existing switchPage()
+  // function from state.js without changing its signature.
+  if (typeof switchPage === 'function' && !switchPage.__qaWrapped) {
+    const _origSwitchPage = switchPage;
+    window.switchPage = function (page, pushState) {
+      try { if (typeof closeManagedLog === 'function') closeManagedLog(); } catch {}
+      return _origSwitchPage(page, pushState);
+    };
+    window.switchPage.__qaWrapped = true;
+  }
+
+  window.MinionsQA = { _registerQaMounts };
+})();

package/dashboard/js/refresh.js

@@ -103,11 +103,13 @@ function _processStatusUpdate(data) {
   prunePrdRequeueState(window._lastWorkItems);
   if (_changed('engineLog', data.engineLog)) renderEngineLog(data.engineLog || []);
   if (_changed('metrics', data.metrics)) renderMetrics(data.metrics || {});
-  // keep_processes panel only relevant when on engine page; cheap call (one fetch)
+  // keep_processes panel renders on every page where its mount is in the DOM
+  // (Engine page + QA page — W-mpd5ewhj000oc5c5). Cheap call (one fetch); the
+  // renderer iterates all registered mounts and skips when none are present.
   if (typeof renderKeepProcesses === 'function') {
     try { renderKeepProcesses(); } catch {}
   }
-  // managed-processes panel — same engine-page-only pattern, ETag-gated so
+  // managed-processes panel — same mount-point pattern, ETag-gated so
   // unchanged ticks return 304 with no body (P-6e2a8b13).
   if (typeof renderManagedProcesses === 'function') {
     try { renderManagedProcesses(); } catch {}

package/dashboard/js/render-managed.js

@@ -21,6 +21,30 @@ let _managedProcessesEtag = null;
 let _managedProcessesLastItems = null;
 let _managedLogES = null;
 
+// Mount-point registry (W-mpd5ewhj000oc5c5 — QA tab dual-render).
+// Each mount = { contentId, countId } pointing at a DOM container to populate.
+// Both the Engine page and the QA page register their own mount, and
+// renderManagedProcesses() writes to every mount that's currently in the DOM.
+// The Engine page mount is registered eagerly here so the existing engine.html
+// behavior keeps working without an explicit mount call.
+const _managedMounts = [
+  { contentId: 'managed-processes-content', countId: 'managed-processes-count' },
+];
+
+function mountManagedProcessesPanel(opts) {
+  if (!opts || !opts.contentId) return;
+  for (const m of _managedMounts) {
+    if (m.contentId === opts.contentId) return; // already registered
+  }
+  _managedMounts.push({ contentId: opts.contentId, countId: opts.countId || null });
+}
+
+function unmountManagedProcessesPanel(contentId) {
+  for (let i = _managedMounts.length - 1; i >= 0; i--) {
+    if (_managedMounts[i].contentId === contentId) _managedMounts.splice(i, 1);
+  }
+}
+
 function _fmtAgo(ms) {
   if (!ms || ms < 0) return '0s';
   const s = Math.floor(ms / 1000);
@@ -85,9 +109,12 @@ function _renderManagedTable(items) {
 }
 
 async function renderManagedProcesses() {
-  const root = document.getElementById('managed-processes-content');
-  const countEl = document.getElementById('managed-processes-count');
-  if (!root) return;
+  // Resolve every registered mount that's currently in the DOM (Engine page +
+  // QA page when present). Skip the fetch entirely when nothing's mounted.
+  const liveMounts = _managedMounts
+    .map(m => ({ ...m, root: document.getElementById(m.contentId), countEl: m.countId ? document.getElementById(m.countId) : null }))
+    .filter(m => m.root);
+  if (!liveMounts.length) return;
   let items;
   let fetchErr = null;
   try {
@@ -112,14 +139,15 @@ async function renderManagedProcesses() {
     fetchErr = e;
   }
   let html;
+  let countText;
   if (fetchErr) {
-    if (countEl) countEl.textContent = '?';
+    countText = '?';
     html = '<span style="color:var(--red)">Failed to load: ' + escHtml(fetchErr.message) + '</span>';
   } else if (!items || !items.length) {
-    if (countEl) countEl.textContent = '0';
+    countText = '0';
     html = '<p class="empty">No managed processes. Agents declare them via <code>agents/&lt;id&gt;/managed-spawn.json</code>.</p>';
   } else {
-    if (countEl) countEl.textContent = String(items.length);
+    countText = String(items.length);
     // Group by owner_project (empty/missing groups under "(unassigned)").
     const groups = {};
     for (const s of items) {
@@ -140,9 +168,13 @@ async function renderManagedProcesses() {
   }
   // DocumentFragment instead of innerHTML — keeps the file out of the
   // dynamic-innerHTML regression gate (cf. render-other.js renderKeepProcesses).
-  const range = document.createRange();
-  const frag = range.createContextualFragment(html);
-  root.replaceChildren(frag);
+  // Build the fragment once per mount (DocumentFragment nodes get adopted on
+  // first append so each mount needs its own copy).
+  for (const m of liveMounts) {
+    if (m.countEl) m.countEl.textContent = countText;
+    const frag = document.createRange().createContextualFragment(html);
+    m.root.replaceChildren(frag);
+  }
 }
 
 async function killManagedSpec(name) {
@@ -268,4 +300,6 @@ window.MinionsManagedProcesses = {
   restartManagedSpec,
   openManagedLog,
   closeManagedLog,
+  mountManagedProcessesPanel,
+  unmountManagedProcessesPanel,
 };

package/dashboard/js/render-other.js

@@ -488,12 +488,38 @@ window.MinionsOther = { renderProjects, optimisticallyAddProject, projectChipRem
 // Polls /api/keep-processes every refresh (engine page only) and renders a
 // table of active agents/<id>/keep-pids.json declarations with one-click
 // "Kill PID" buttons that hit POST /api/keep-processes/kill.
+//
+// Mount-point registry (W-mpd5ewhj000oc5c5 — QA tab dual-render). Both the
+// Engine page and the QA page register a mount; renderKeepProcesses() writes
+// to every mount that's currently in the DOM. The Engine page mount is
+// registered eagerly so the existing engine.html behavior is unchanged.
+const _keepProcessesMounts = [
+  { contentId: 'keep-processes-content', countId: 'keep-processes-count' },
+];
+
+function mountKeepProcessesPanel(opts) {
+  if (!opts || !opts.contentId) return;
+  for (const m of _keepProcessesMounts) {
+    if (m.contentId === opts.contentId) return;
+  }
+  _keepProcessesMounts.push({ contentId: opts.contentId, countId: opts.countId || null });
+}
+
+function unmountKeepProcessesPanel(contentId) {
+  for (let i = _keepProcessesMounts.length - 1; i >= 0; i--) {
+    if (_keepProcessesMounts[i].contentId === contentId) _keepProcessesMounts.splice(i, 1);
+  }
+}
 
 async function renderKeepProcesses() {
-  const root = document.getElementById('keep-processes-content');
-  const countEl = document.getElementById('keep-processes-count');
-  if (!root) return;
+  // Resolve every registered mount currently in the DOM (Engine + QA pages).
+  // Skip the fetch entirely when nothing is mounted.
+  const liveMounts = _keepProcessesMounts
+    .map(m => ({ ...m, root: document.getElementById(m.contentId), countEl: m.countId ? document.getElementById(m.countId) : null }))
+    .filter(m => m.root);
+  if (!liveMounts.length) return;
   let html;
+  let countText;
   let items;
   let fetchErr = null;
   try {
@@ -504,13 +530,13 @@ async function renderKeepProcesses() {
     fetchErr = e;
   }
   if (fetchErr) {
-    if (countEl) countEl.textContent = '?';
+    countText = '?';
     html = '<span style="color:var(--red)">Failed to load: ' + escHtml(fetchErr.message) + '</span>';
   } else if (!items.length) {
-    if (countEl) countEl.textContent = '0';
+    countText = '0';
     html = '<p class="empty">No agents have left processes running. Set <code>meta.keep_processes: true</code> on a work item to enable.</p>';
   } else {
-    if (countEl) countEl.textContent = String(items.length);
+    countText = String(items.length);
     html = items.map(function (it) {
       if (!it.valid) {
         return '<div style="border:1px solid var(--border);border-radius:4px;padding:8px;margin-bottom:8px;background:var(--surface2)">' +
@@ -548,10 +574,14 @@ async function renderKeepProcesses() {
   // Use DocumentFragment instead of innerHTML assignment to keep this
   // function out of the dynamic-innerHTML regression gate (see
   // test/unit.test.js DYNAMIC_INNERHTML_BASELINE). All embedded
-  // user-controlled fields above are wrapped in escHtml().
-  const range = document.createRange();
-  const frag = range.createContextualFragment(html);
-  root.replaceChildren(frag);
+  // user-controlled fields above are wrapped in escHtml(). Build the
+  // fragment once per mount (DocumentFragment nodes get adopted on first
+  // append so each mount needs its own copy).
+  for (const m of liveMounts) {
+    if (m.countEl) m.countEl.textContent = countText;
+    const frag = document.createRange().createContextualFragment(html);
+    m.root.replaceChildren(frag);
+  }
 }
 
 async function killKeepPid(agentId, pid) {
@@ -573,5 +603,5 @@ async function killKeepPid(agentId, pid) {
   renderKeepProcesses();
 }
 
-window.MinionsKeepProcesses = { renderKeepProcesses, killKeepPid };
+window.MinionsKeepProcesses = { renderKeepProcesses, killKeepPid, mountKeepProcessesPanel, unmountKeepProcessesPanel };
 

package/dashboard/layout.html

@@ -69,6 +69,7 @@
     <a class="sidebar-link" data-page="work" href="/work">Work Items <span class="sidebar-count" id="sidebar-wi"></span></a>
     <a class="sidebar-link" data-page="plans" href="/plans">Plans & PRD</a>
     <a class="sidebar-link" data-page="prs" href="/prs">Pull Requests <span class="sidebar-count" id="sidebar-pr"></span></a>
+    <a class="sidebar-link" data-page="qa" href="/qa" title="QA — live processes + validation runbooks (managed-spawn + keep-processes)">QA</a>
     <a class="sidebar-link" data-page="inbox" href="/inbox">Notes & KB</a>
     <a class="sidebar-link" data-page="tools" href="/tools">Skills & MCP</a>
     <a class="sidebar-link" data-page="schedule" href="/schedule" title="Cron-based recurring tasks (single task per schedule)">Schedules</a>

package/dashboard/pages/qa.html

@@ -0,0 +1,23 @@
+      <section>
+        <h2>Live Processes <span style="font-size:10px;color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0">canonical home for managed instances + agent-left processes (W-mpd5ewhj000oc5c5)</span></h2>
+        <p class="empty" style="margin:4px 0 12px 0">The QA tab is the foundation for human-driven and agent-driven validation against running managed instances. Phase 1 surfaces the live process inventory; runbook dispatch lands in a follow-up WI.</p>
+      </section>
+      <section id="qa-managed-processes-section">
+        <h2>Managed Processes <span class="count" id="qa-managed-processes-count">0</span>
+          <span style="font-size:10px;color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0">engine-managed long-running services (P-6e2a8b13 — managed-spawn primitive)</span>
+        </h2>
+        <div id="qa-managed-processes-content"><p class="empty">No managed processes. Agents declare them via <code>agents/&lt;id&gt;/managed-spawn.json</code>.</p></div>
+      </section>
+      <section id="qa-keep-processes-section">
+        <h2>Keep-Processes <span class="count" id="qa-keep-processes-count">0</span>
+          <span style="font-size:10px;color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0">processes left running by agents (W-mp68q6ke0010de68 — opt-in keep_processes flag)</span>
+        </h2>
+        <div id="qa-keep-processes-content"><p class="empty">No agents have left processes running. Set <code>meta.keep_processes: true</code> on a work item to enable.</p></div>
+      </section>
+      <section id="qa-runbooks-section">
+        <h2>Validation Runbooks <span style="font-size:10px;color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0">human or agent-driven smoke / E2E flows against the live instances above</span></h2>
+        <div style="border:1px dashed var(--border);border-radius:6px;padding:16px;background:var(--surface2);text-align:center">
+          <p class="empty" style="margin:0 0 12px 0">Validation runbooks will live here. Coming soon: dispatch a human or agent to validate a running instance.</p>
+          <button id="qa-new-runbook-btn" disabled title="Coming soon — runbook schema lands in the next WI" style="padding:6px 14px;background:var(--surface);color:var(--muted);border:1px solid var(--border);border-radius:4px;cursor:not-allowed;font-size:12px">+ New runbook</button>
+        </div>
+      </section>

package/dashboard-build.js

@@ -20,7 +20,7 @@ function buildDashboardHtml() {
   const layout = safeRead(layoutPath);
   const css = safeRead(path.join(dashDir, 'styles.css'));
 
-  const pages = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'engine'];
+  const pages = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'qa', 'engine'];
   let pageHtml = '';
   for (const p of pages) {
     const content = safeRead(path.join(dashDir, 'pages', p + '.html'));
@@ -34,7 +34,7 @@ function buildDashboardHtml() {
     'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
     'render-other', 'render-managed', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
     'command-parser', 'command-input', 'command-center', 'command-history',
-    'modal', 'modal-qa', 'settings', 'refresh'
+    'modal', 'modal-qa', 'settings', 'qa', 'refresh'
   ];
   let jsHtml = '';
   for (const f of jsFiles) {

package/dashboard.js

@@ -95,6 +95,21 @@ function reloadConfig() {
 }
 ensureConfiguredProjectStateFiles();
 
+// Pre-warm git-status cache for every configured project so the first
+// /api/status after dashboard boot already has branch/dirty data — without
+// blocking the event loop on the per-project git shell-outs. Fire-and-forget,
+// boot-only: re-warming on every reloadConfig() would spawn 4× git probes on
+// every 10s status-poll cache miss. Project add/remove handlers explicitly
+// invoke this when the project list actually changes.
+function warmProjectGitStatusCache() {
+  for (const p of PROJECTS) {
+    if (p && p.localPath) {
+      try { queries.warmProjectGitStatus(p.localPath); } catch { /* swallow — warming is opportunistic */ }
+    }
+  }
+}
+warmProjectGitStatusCache();
+
 function resolveScheduleProjectValue(project, projects = PROJECTS) {
   if (project === undefined) return { project: undefined };
   const target = shared.resolveConfiguredProject(project, projects);
@@ -860,7 +875,7 @@ function buildDashboardHtml() {
   // Assemble page fragments. Each wrapper gets a `.page-toast` inline slot at
   // the top — showToast('cmd-toast', …) auto-routes here when a page is active,
   // so feedback lands near the action instead of the floating top-right toast.
-  const pages = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'engine'];
+  const pages = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'qa', 'engine'];
   const pageToast = '      <div class="cmd-toast cmd-toast-inline page-toast" style="margin:6px 16px"></div>\n';
   let pageHtml = '';
   for (const p of pages) {
@@ -876,7 +891,7 @@ function buildDashboardHtml() {
     'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
     'render-other', 'render-managed', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
     'command-parser', 'command-input', 'command-center', 'command-history',
-    'modal', 'modal-qa', 'settings', 'refresh'
+    'modal', 'modal-qa', 'settings', 'qa', 'refresh'
   ];
   let jsHtml = '';
   for (const f of jsFiles) {
@@ -1581,6 +1596,8 @@ const CC_CALL_TIMEOUT_MS = 60 * 60 * 1000; // 1 hour — long-running CC orchest
 const CC_INFLIGHT_TIMEOUT_MS = 2 * 60 * 1000; // 2 minutes — auto-release if request hangs
 const CC_LOCK_WAIT_MS = 200; // grace period for previous handler's finally to release lock
 const CC_STREAM_HEARTBEAT_MS = 15000; // keep streaming responses alive across proxies/restart races
+const CC_STREAM_STALL_THRESHOLD_MS = 3000; // log [cc-stall] when heartbeat fires >3s late (event-loop blocked)
+const CC_LOG_ERROR_MAX_LEN = 80; // truncate exception messages in [cc-stream] log lines
 const CC_STREAM_REATTACH_GRACE_MS = 60000; // keep CC job alive briefly after disconnect so the UI can reattach
 const CC_STREAM_DONE_RETENTION_MS = 30000; // retain final payload briefly so reconnect can still receive it
 const CC_LIVE_STREAM_MAX_AGE_MS = shared.ENGINE_DEFAULTS.ccLiveStreamMaxAgeMs;
@@ -1704,6 +1721,32 @@ function _ccTabIsInFlight(tabId) {
   return true;
 }
 
+// Emits exactly one structured log line per CC SSE stream termination, so
+// "Failed to fetch" reports can be matched to a server-side reason (restart,
+// abort, timeout, rate-limit, write-failed, stall, ...). Idempotent via the
+// telemetry object's `_logged` flag — first call wins, subsequent calls no-op.
+function _logCcStreamEnd(telemetry, reason, extra) {
+  if (!telemetry || telemetry._logged) return;
+  telemetry._logged = true;
+  const durationMs = telemetry.startedAt ? (Date.now() - telemetry.startedAt) : 0;
+  const parts = [
+    `tab=${telemetry.tabId || 'unknown'}`,
+    `session=${telemetry.sessionId || 'none'}`,
+    `reason=${reason || 'unknown'}`,
+    `duration=${durationMs}ms`,
+    `chunks=${telemetry.chunks || 0}`,
+    `tools=${telemetry.tools || 0}`,
+    `bytes=${telemetry.bytes || 0}`,
+  ];
+  if (extra && typeof extra === 'object') {
+    for (const [k, v] of Object.entries(extra)) {
+      if (v === undefined || v === null) continue;
+      parts.push(`${k}=${v}`);
+    }
+  }
+  console.log(`[cc-stream] ${parts.join(' ')}`);
+}
+
 // _ccPromptHash computed after CC_STATIC_SYSTEM_PROMPT is defined (see below)
 
 function ccSessionValid() {
@@ -6268,6 +6311,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       });
       if (duplicate) return jsonReply(res, 400, { error: 'Project already linked at ' + target });
       reloadConfig(); // Update in-memory project list immediately
+      warmProjectGitStatusCache(); // Probe the new project's git status in the background
       // includeSlow: PROJECTS lives in the slow-state cache (60s TTL); without
       // flushing it, /api/status keeps returning the previous project list for
       // up to a minute after the add. Matches handleProjectsRemove's behavior.
@@ -6713,6 +6757,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   }
 
   async function handleCommandCenterStream(req, res) {
+    // Per-stream telemetry — _logCcStreamEnd is idempotent so callers don't
+    // need to coordinate. Augmented by writeCcEvent (chunks, bytes) and the
+    // heartbeat stall detector below.
+    const _ccTelemetry = { startedAt: Date.now(), tabId: null, sessionId: null, chunks: 0, tools: 0, bytes: 0, _logged: false, _stallLogged: false };
     // SSE Origin gate (belt-and-suspenders: the top-level dispatcher has
     // already rejected disallowed origins on POST, but validate again here
     // before res.writeHead(200, text/event-stream) so any future refactor
@@ -6723,16 +6771,29 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       res.statusCode = 403;
       res.setHeader('Content-Type', 'application/json');
       res.end(JSON.stringify({ error: 'Origin not allowed' }));
+      _logCcStreamEnd(_ccTelemetry, 'origin-rejected', { origin: _origin });
+      return;
+    }
+    if (checkRateLimit('command-center', 10)) {
+      res.statusCode = 429; res.end('Rate limited');
+      _logCcStreamEnd(_ccTelemetry, 'rate-limited-pre-stream');
       return;
     }
-    if (checkRateLimit('command-center', 10)) { res.statusCode = 429; res.end('Rate limited'); return; }
     let tabId;
     let _ccStreamAbort = null;
     let _ccStreamEnded = false;
     let _ccHeartbeatTimer = null;
+    let _ccLastHeartbeatAt = Date.now();
     const writeCcEvent = (payload) => {
       try {
-        res.write('data: ' + JSON.stringify(payload) + '\n\n');
+        const wire = 'data: ' + JSON.stringify(payload) + '\n\n';
+        res.write(wire);
+        if (payload && payload.type === 'chunk') {
+          _ccTelemetry.chunks++;
+          _ccTelemetry.bytes += Buffer.byteLength(String(payload.text || ''), 'utf8');
+        } else if (payload && payload.type === 'tool') {
+          _ccTelemetry.tools++;
+        }
         return true;
       } catch {
         return false;
@@ -6744,29 +6805,66 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         _ccHeartbeatTimer = null;
       }
     };
+    // Event-loop-stall detector — piggybacks on the heartbeat interval.
+    // setInterval timers fire late when the loop is blocked; if the gap
+    // between fires exceeds HEARTBEAT_MS + STALL_THRESHOLD_MS, the loop was
+    // stuck (sync I/O, large JSON.parse, shelled-out command, ...). Log once
+    // per stream to avoid spamming.
+    const _checkStall = () => {
+      const now = Date.now();
+      const expected = _ccLastHeartbeatAt + CC_STREAM_HEARTBEAT_MS;
+      const drift = now - expected;
+      _ccLastHeartbeatAt = now;
+      if (drift > CC_STREAM_STALL_THRESHOLD_MS && !_ccTelemetry._stallLogged) {
+        _ccTelemetry._stallLogged = true;
+        console.warn(`[cc-stall] tab=${_ccTelemetry.tabId || 'unknown'} drift=${drift}ms heartbeatExpected=${CC_STREAM_HEARTBEAT_MS}ms — event loop blocked`);
+      }
+    };
+    // Start the heartbeat + stall-detector interval. Both SSE paths (reconnect
+    // and normal stream) used to duplicate this block; factor it out so the
+    // stall check and write-failure log-line stay in one place.
+    const _startCcHeartbeat = (writeFailedReason) => {
+      _ccLastHeartbeatAt = Date.now();
+      _ccHeartbeatTimer = setInterval(() => {
+        if (_ccStreamEnded) {
+          stopCcHeartbeat();
+          return;
+        }
+        _checkStall();
+        if (!writeCcEvent({ type: 'heartbeat' })) {
+          stopCcHeartbeat();
+          if (writeFailedReason) _logCcStreamEnd(_ccTelemetry, writeFailedReason);
+        }
+      }, CC_STREAM_HEARTBEAT_MS);
+    };
     const finishMissingRuntime = (result, liveState) => {
       const text = result.text || result.stderr || 'Minions runtime is not installed or configured.';
       liveState.donePayload = { type: 'done', text, actions: [], sessionId: null, missingRuntime: true };
       if (liveState.writer) liveState.writer(liveState.donePayload);
       if (liveState.endResponse) liveState.endResponse();
       _scheduleCcLiveCleanup(tabId);
+      _logCcStreamEnd(_ccTelemetry, 'missing-runtime');
     };
     try {
       const body = await readBody(req);
-      if (!body.message && !body.reconnect) { res.statusCode = 400; res.end('message required'); return; }
+      if (!body.message && !body.reconnect) {
+        res.statusCode = 400; res.end('message required');
+        _logCcStreamEnd(_ccTelemetry, 'bad-request');
+        return;
+      }
       tabId = body.tabId || 'default';
+      _ccTelemetry.tabId = tabId;
+      _ccTelemetry.sessionId = body.sessionId || null;
       if (body.reconnect) {
         const live = _getCcLiveStream(tabId);
-        if (!live) { res.statusCode = 409; res.end('No live command-center response to reconnect'); return; }
+        if (!live) {
+          res.statusCode = 409; res.end('No live command-center response to reconnect');
+          _logCcStreamEnd(_ccTelemetry, 'reconnect-not-found');
+          return;
+        }
         res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
         writeCcEvent({ type: 'heartbeat' });
-        _ccHeartbeatTimer = setInterval(() => {
-          if (_ccStreamEnded) {
-            stopCcHeartbeat();
-            return;
-          }
-          if (!writeCcEvent({ type: 'heartbeat' })) stopCcHeartbeat();
-        }, CC_STREAM_HEARTBEAT_MS);
+        _startCcHeartbeat();
         let reconnectDone;
         const reconnectDonePromise = new Promise(resolve => { reconnectDone = resolve; });
         _attachCcLiveStream(tabId, writeCcEvent, () => {
@@ -6774,6 +6872,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           _ccStreamEnded = true;
           stopCcHeartbeat();
           try { res.end(); } catch {}
+          _logCcStreamEnd(_ccTelemetry, 'reconnect-attached-done');
           reconnectDone();
         });
         req.on('close', () => {
@@ -6781,6 +6880,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           stopCcHeartbeat();
           _detachCcLiveStream(tabId, writeCcEvent);
           _scheduleCcLiveAbort(tabId);
+          _logCcStreamEnd(_ccTelemetry, 'reconnect-client-disconnect');
           reconnectDone();
         });
         for (const tool of live.tools || []) {
@@ -6793,6 +6893,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           stopCcHeartbeat();
           try { res.end(); } catch {}
           _scheduleCcLiveCleanup(tabId);
+          _logCcStreamEnd(_ccTelemetry, 'reconnect-replayed-done');
           return;
         }
         await reconnectDonePromise;
@@ -6804,7 +6905,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         if (prevAbort) { prevAbort(); }
         await new Promise(r => setTimeout(r, CC_LOCK_WAIT_MS)); // let previous finally run and release the lock
         if (_ccTabIsInFlight(tabId)) {
-          res.statusCode = 429; res.end('This tab is already processing'); return;
+          res.statusCode = 429; res.end('This tab is already processing');
+          _logCcStreamEnd(_ccTelemetry, 'tabid-collision');
+          return;
         }
       }
       ccInFlightTabs.set(tabId, Date.now());
@@ -6818,13 +6921,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
       res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
       writeCcEvent({ type: 'heartbeat' }); // flush headers quickly and keep intermediaries from idling out
-      _ccHeartbeatTimer = setInterval(() => {
-        if (_ccStreamEnded) {
-          stopCcHeartbeat();
-          return;
-        }
-        if (!writeCcEvent({ type: 'heartbeat' })) stopCcHeartbeat();
-      }, CC_STREAM_HEARTBEAT_MS);
+      _startCcHeartbeat('heartbeat-write-failed');
       // Kill LLM process immediately if client disconnects mid-stream.
       // Keep the LLM alive briefly after disconnect so the UI can reattach to the same in-flight turn.
       req.on('close', () => {
@@ -6832,6 +6929,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           stopCcHeartbeat();
           _detachCcLiveStream(tabId, writeCcEvent);
           _scheduleCcLiveAbort(tabId);
+          _logCcStreamEnd(_ccTelemetry, 'client-disconnect');
         }
       });
 
@@ -6955,7 +7053,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           return;
         }
         if (!result.text) {
-          if (req.destroyed) { _ccStreamEnded = true; return; } // client already gone — nothing to send
+          if (req.destroyed) {
+            _ccStreamEnded = true;
+            _logCcStreamEnd(_ccTelemetry, 'llm-empty-client-gone', { code: result.code });
+            return;
+          }
           const debugInfo = result.code !== 0 ? `(exit code ${result.code})` : '(empty response)';
           const stderrTail = (result.stderr || '').trim().split('\n').filter(Boolean).slice(-3).join(' | ');
           console.error(`[CC-stream] Failed: code=${result.code}, stderr=${(result.stderr || '').slice(0, 500)}, stdout_tail=${(result.raw || '').slice(-500)}`);
@@ -6964,6 +7066,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           if (liveState.writer) liveState.writer(liveState.donePayload);
           if (liveState.endResponse) liveState.endResponse();
           _scheduleCcLiveCleanup(tabId);
+          _logCcStreamEnd(_ccTelemetry, 'llm-failed-fallback-sent', { code: result.code });
           return;
         }
 
@@ -7013,6 +7116,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
         if (liveState.endResponse) liveState.endResponse();
         _scheduleCcLiveCleanup(tabId);
+        _ccTelemetry.sessionId = responseSessionId || _ccTelemetry.sessionId;
+        _logCcStreamEnd(_ccTelemetry, 'done', { actions: actions.length });
       } finally {
         stopCcHeartbeat();
         _releaseCCTab(tabId);
@@ -7026,9 +7131,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         res.statusCode = e.statusCode || 500;
         res.setHeader('Content-Type', 'application/json');
         try { res.end(JSON.stringify({ error: e.message })); } catch {}
+        _logCcStreamEnd(_ccTelemetry, 'error-pre-stream', { error: (e && e.message ? e.message.slice(0, CC_LOG_ERROR_MAX_LEN) : 'unknown') });
       } else {
         writeCcEvent({ type: 'error', error: e.message });
         _ccStreamEnded = true; try { res.end(); } catch {}
+        _logCcStreamEnd(_ccTelemetry, 'error-mid-stream', { error: (e && e.message ? e.message.slice(0, CC_LOG_ERROR_MAX_LEN) : 'unknown') });
       }
     }
   }
@@ -8520,8 +8627,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } },
     { method: 'GET', path: '/api/agent-output', desc: 'Read agent output log file', params: 'file', handler: async (req, res) => {
       const file = new URL(req.url, 'http://localhost').searchParams.get('file');
-      if (!file || file.includes('..') || file.includes('\0') || !file.startsWith('agents/')) return jsonReply(res, 400, { error: 'invalid file' });
-      const content = safeRead(path.join(MINIONS_DIR, file));
+      let safePath;
+      try { safePath = shared.sanitizePath(file, MINIONS_DIR); }
+      catch { return jsonReply(res, 400, { error: 'invalid path' }); }
+      const agentsDir = path.join(MINIONS_DIR, 'agents');
+      if (!safePath.startsWith(agentsDir + path.sep)) return jsonReply(res, 400, { error: 'path must be within agents/' });
+      const content = safeRead(safePath);
       if (content === null) return jsonReply(res, 404, { error: 'not found' });
       res.setHeader('Content-Type', 'text/plain; charset=utf-8');
       res.setHeader('Cache-Control', 'no-cache');