@yemi33/minions 0.1.2187 → 0.1.2189

package/dashboard.js

@@ -8130,25 +8130,69 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     let _docAbort = null;
     let _docStreamEnded = false;
     let _docHeartbeatTimer = null;
+    // W-mpetru71000re5de — per-stream backpressure clock + approximate queued
+    // bytes, mirroring writeCcEvent so a runtime error frame can't be swallowed
+    // forever behind a stuck consumer (the "spins endlessly" failure mode).
+    // _docBpStartedAt timestamps the first write that returned false (reset on
+    // 'drain'); _docQueuedBytes accumulates bytes pushed past res.writable's
+    // highWaterMark. The heartbeat tick force-closes the stream once the clock
+    // exceeds SSE_STUCK_KILL_MS, which fires req.on('close') → abort + cleanup
+    // so the client's reader gets `done` and renders a real error instead of
+    // spinning. Doc-chat has no reconnect-replay, so we only shed intermediate
+    // frames (chunk/tool/progress/heartbeat) — terminal `done` and `error`
+    // frames are NEVER shed so the final answer / typed error always lands.
+    let _docBpStartedAt = null;
+    let _docQueuedBytes = 0;
+    try {
+      res.on('drain', () => { _docBpStartedAt = null; _docQueuedBytes = 0; });
+    } catch { /* listener registration is best-effort */ }
     const writeDocEvent = (payload) => {
-      // TODO(W-mpetru71000re5de): doc-chat SSE has the same unbounded-queue
-      // failure mode as CC's writeCcEvent — res.write() returning false from
-      // backpressure silently queues bytes in Node's WritableState.buffered[].
-      // Out of scope for this fix (task is scoped to CC only). When this is
-      // addressed, mirror the SSE_MAX_QUEUE_BYTES shed + SSE_STUCK_KILL_MS
-      // heartbeat force-close pattern from the writeCcEvent closure
-      // (dashboard.js, search for SSE_MAX_QUEUE_BYTES).
+      const type = payload && payload.type;
+      const isTerminal = type === 'done' || type === 'error';
+      const _logFail = (reason) => {
+        try {
+          shared.log('warn', `[doc-sse-fail] ${JSON.stringify({ doc: docKey || 'unknown', type, reason, destroyed: !!res.destroyed, writableEnded: !!res.writableEnded, streamEnded: _docStreamEnded })}`);
+        } catch { /* telemetry is best-effort */ }
+      };
+      if (res.destroyed || res.writableEnded) {
+        _logFail(res.destroyed ? 'res-destroyed' : 'res-writable-ended');
+        return false;
+      }
+      let wire;
       try {
-        const type = payload && payload.type;
-        // W-mpmwxni2000c25c7-d — mirror the writeCcEvent change so doc-chat
-        // also emits `event: error` for terminal errors. Same back-compat:
-        // the JSON still carries `type: 'error'` for data-line parsers.
+        // W-mpmwxni2000c25c7-d — terminal error frames go out as `event: error`
+        // so SSE consumers using addEventListener('error', …) can target them.
+        // The JSON payload still carries `type: 'error'` for the data-line
+        // parser in modal-qa.js.
         const eventLine = (type === 'error') ? 'event: error\n' : '';
-        res.write(eventLine + 'data: ' + JSON.stringify(payload) + '\n\n');
-        return true;
+        wire = eventLine + 'data: ' + JSON.stringify(payload) + '\n\n';
       } catch {
+        _logFail('json-serialize-failed');
         return false;
       }
+      // Shed intermediate frames once the queue exceeds the cap, but ALWAYS
+      // attempt terminal frames — the `done` frame carries the full final
+      // answer and the `error` frame is the whole point of this fix.
+      if (!isTerminal && _docQueuedBytes > SSE_MAX_QUEUE_BYTES) {
+        try {
+          shared.log('warn', `[doc-sse-shed] doc=${docKey || 'unknown'} type=${type} queuedBytes=${_docQueuedBytes} wireBytes=${wire.length}`);
+        } catch { /* telemetry is best-effort */ }
+        return true;
+      }
+      let writeOk;
+      try { writeOk = res.write(wire); }
+      catch { _logFail('res-write-threw'); return false; }
+      if (writeOk === false) {
+        // Backpressure — the write is still queued. Start (or extend) the
+        // backpressure clock so the heartbeat tick can force-close a stuck
+        // stream, and accumulate approximate queued bytes for the shed gate.
+        if (_docBpStartedAt == null) _docBpStartedAt = Date.now();
+        _docQueuedBytes += wire.length;
+        try {
+          shared.log('warn', `[doc-sse-backpressure] doc=${docKey || 'unknown'} type=${type} bytes=${wire.length} queuedBytes=${_docQueuedBytes} bpMs=${Date.now() - _docBpStartedAt}`);
+        } catch { /* telemetry is best-effort */ }
+      }
+      return true;
     };
     const stopDocHeartbeat = () => {
       if (_docHeartbeatTimer) {
@@ -8196,6 +8240,20 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           stopDocHeartbeat();
           return;
         }
+        // W-mpetru71000re5de — force-close streams stuck on backpressure.
+        // res.destroy() fires req.on('close'), which runs the teardown path
+        // below (stop heartbeat → drop the in-flight guard → abort the LLM),
+        // so a runtime that finished (or errored) but whose frame can't reach
+        // a wedged consumer no longer leaves the client spinning forever.
+        if (_docBpStartedAt && Date.now() - _docBpStartedAt > SSE_STUCK_KILL_MS) {
+          const stuckMs = Date.now() - _docBpStartedAt;
+          try {
+            shared.log('warn', `[doc-sse-stuck-close] doc=${docKey || 'unknown'} stuckMs=${stuckMs} queuedBytes=${_docQueuedBytes}`);
+          } catch { /* telemetry is best-effort */ }
+          stopDocHeartbeat();
+          try { res.destroy(); } catch { /* swallow — req.on('close') will still fire */ }
+          return;
+        }
         if (!writeDocEvent({ type: 'heartbeat' })) stopDocHeartbeat();
       }, CC_STREAM_HEARTBEAT_MS);
 
@@ -8256,12 +8314,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           llm.trackEngineError('doc-chat', errCode);
           const isHardFailure = !partial && !(finalize && finalize.edited);
           if (isHardFailure) {
-            const errPayload = {
+            // Route through writeDocEvent so the terminal error frame inherits
+            // the destroyed/ended guards and is never shed under backpressure.
+            writeDocEvent({
+              type: 'error',
               message: ccError.typedMessage || ccError.errorMessage || 'Document chat failed',
               code: errCode,
               retriable: ccError.retriable !== false,
-            };
-            try { res.write(`event: error\ndata: ${JSON.stringify(errPayload)}\n\n`); } catch {}
+            });
           }
         }
         const { answer: finalAnswer, ...donePayload } = payload;
@@ -13500,13 +13560,28 @@ if (require.main === module) {
     // (engine/shared.js#openUrlInBrowser) now owns the env-var check and
     // emits a debug-level SUPPRESSED log entry so we can prove the kill-
     // switch is firing.
-    const result = shared.openUrlInBrowser(`http://localhost:${PORT}`, {
-      reason: 'dashboard-self-open',
-      callerHint: 'dashboard.js:13124',
-    });
-    if (!result.ok && !result.suppressed) {
-      console.log(`  Could not auto-open browser: ${result.error}`);
-      console.log(`  Please open http://localhost:${PORT} manually.`);
+    //
+    // W-mqef-dashboard-tty — only self-open for an interactive human run
+    // (`node dashboard.js` in a terminal). The CLI spawns the dashboard
+    // DETACHED + non-TTY with MINIONS_NO_AUTO_OPEN=1 and orchestrates the open
+    // itself, so it never relied on this branch. But the dashboard integration
+    // tests — and any agent running `npm test` — spawn dashboard.js with piped
+    // stdio and NO env guard, so this fired for real on every test run, popping
+    // a browser tab to a random localhost port that the test then tore down
+    // (blank window on the operator's desktop). stdout.isTTY is false for every
+    // programmatic spawn (tests, agents, CI, the detached CLI dashboard) and
+    // true only for a real terminal session, so it's the correct discriminator.
+    if (process.stdout.isTTY) {
+      const result = shared.openUrlInBrowser(`http://localhost:${PORT}`, {
+        reason: 'dashboard-self-open',
+        callerHint: 'dashboard.js:13124',
+      });
+      if (!result.ok && !result.suppressed) {
+        console.log(`  Could not auto-open browser: ${result.error}`);
+        console.log(`  Please open http://localhost:${PORT} manually.`);
+      }
+    } else {
+      console.log(`  Open http://localhost:${PORT} in your browser.`);
     }
 
     // Warm the CC runtime binary cache off the request path so the first CC /

package/docs/worktree-lifecycle.md

@@ -142,6 +142,24 @@ EPERM/EBUSY stragglers that the dispatch-end GC couldn't reap and sweeps
 the `git worktree list` registry for OUT-of-root entries the in-root
 scanner is blind to.
 
+### Ownership marker — out-of-root GC only touches engine worktrees (W-mqecdoot)
+
+A project repo's `git worktree list` includes EVERY worktree registered
+against it — including ones a developer created by hand
+(`git worktree add /tmp/my-work <branch>`) for their own work. The
+out-of-root sweep used to evict any such entry that wasn't pinned to a
+live dispatch / pool / managed-spawn, **deleting human worktrees
+mid-edit**. The fix: the engine stamps a `.minions-worktree` ownership
+marker (`shared.WORKTREE_OWNER_MARKER`) into every worktree it creates
+(`shared.writeWorktreeOwnerMarker`, called right after `git worktree add`
+in `engine.js#runWorktreeAdd`). `pruneOrphanWorktreesFromGitRegistry`
+now requires `shared.hasWorktreeOwnerMarker(path)` before evicting an
+out-of-root worktree — **no marker → foreign → kept and never
+escalated** (fail-open: leak a dir rather than nuke unpushed work). The
+trailing `git worktree prune --expire=now` (drops registry entries whose
+dirs are already gone) still runs regardless of ownership. The marker is
+gitignored so it never shows up in any worktree's `git status`.
+
 ## Holder identification + opt-in auto-reap (W-mq6f2fe0000557fa)
 
 Orphan-sweep escalations also run `shared.findProcessesWithCwdInside(wt)`

package/engine/shared.js

@@ -7790,6 +7790,49 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
   }
 }
 
+// W-mqecdoot — engine worktree ownership marker. The out-of-root worktree GC
+// (worktree-gc.pruneOrphanWorktreesFromGitRegistry) reaps worktrees registered
+// in a project's git that live OUTSIDE the configured worktreeRoot. Without a
+// positive ownership signal it cannot tell an engine-created orphan from a
+// worktree a human developer created by hand (`git worktree add /tmp/foo …`)
+// for their own work — and was deleting the latter mid-edit. We stamp this
+// marker into every worktree the engine creates so the GC can require proof of
+// ownership before removal; a worktree with NO marker is treated as foreign
+// and left untouched (fail-open: leak a dir rather than nuke someone's work).
+const WORKTREE_OWNER_MARKER = '.minions-worktree';
+
+// Best-effort stamp dropped right after a successful `git worktree add`. Never
+// throws — a missing marker only costs us the ability to auto-GC that dir.
+function writeWorktreeOwnerMarker(worktreePath, info = {}) {
+  if (!worktreePath) return false;
+  try {
+    const target = path.join(path.resolve(worktreePath), WORKTREE_OWNER_MARKER);
+    const payload = {
+      engine: true,
+      createdAt: new Date().toISOString(),
+      pid: process.pid,
+      ...info,
+    };
+    fs.writeFileSync(target, JSON.stringify(payload, null, 2) + '\n');
+    return true;
+  } catch (e) {
+    log('debug', `writeWorktreeOwnerMarker: could not stamp ${worktreePath}: ${e.message}`);
+    return false;
+  }
+}
+
+// True only when the worktree carries the engine ownership marker. Fail-closed
+// (returns false) on any read error so an unreadable dir is treated as foreign
+// and kept, never blindly removed.
+function hasWorktreeOwnerMarker(worktreePath) {
+  if (!worktreePath) return false;
+  try {
+    return fs.existsSync(path.join(path.resolve(worktreePath), WORKTREE_OWNER_MARKER));
+  } catch {
+    return false;
+  }
+}
+
 function slugify(text, maxLen = 50) {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, maxLen);
 }
@@ -8195,6 +8238,9 @@ module.exports = {
   listProcessReachable,
   removeWorktree,
   isWorktreePathLive,
+  WORKTREE_OWNER_MARKER,
+  writeWorktreeOwnerMarker,
+  hasWorktreeOwnerMarker,
   _normalizeWorktreePath, // exported for testing
   _writeWorktreeSkipLiveInboxNote, // exported for testing
   _retryFsOp, // exported for testing (W-mq5o6bvy000x7191)

package/engine/worktree-gc.js

@@ -771,6 +771,14 @@ function pruneOrphanWorktreesFromGitRegistry(opts) {
   const _parseWorktreePorcelain = typeof opts.parseWorktreePorcelain === 'function'
     ? opts.parseWorktreePorcelain
     : shared.parseWorktreePorcelain;
+  // W-mqecdoot — positive ownership gate. An out-of-root worktree is only
+  // engine-managed if it carries the ownership marker we stamp at creation
+  // (shared.writeWorktreeOwnerMarker). Worktrees a human created by hand
+  // (`git worktree add /tmp/foo …`) have no marker and must be left alone —
+  // this sweep was deleting them mid-edit.
+  const _hasOwnerMarker = typeof opts.hasOwnerMarker === 'function'
+    ? opts.hasOwnerMarker
+    : shared.hasWorktreeOwnerMarker;
 
   // Branches of active/pending dispatches (with and without `refs/heads/`
   // normalization). Matched case-insensitively to mirror git's behavior on
@@ -875,6 +883,21 @@ function pruneOrphanWorktreesFromGitRegistry(opts) {
         if (anchored) { projStats.kept++; result.kept++; continue; }
       }
 
+      // W-mqecdoot — ownership gate. Only ever evict a worktree the engine
+      // positively created (carries the ownership marker stamped at
+      // `git worktree add` time). No marker → it's a human's hand-made worktree
+      // (or a pre-marker legacy dir); KEEP it and do NOT escalate. The
+      // `git worktree prune --expire=now` below still drops registry entries
+      // whose dirs are already gone, which is safe regardless of ownership.
+      let owned = false;
+      try { owned = !!_hasOwnerMarker(wtAbs); }
+      catch (_e) { owned = false; }
+      if (!owned) {
+        projStats.kept++; result.kept++;
+        log('debug', `worktree-gc: keeping out-of-root ${wtAbs} — no engine ownership marker (foreign/hand-made worktree)`);
+        continue;
+      }
+
       // Slow-cadence gate for already-escalated stuck paths
       const slowRetryMs = (opts.config?.engine?.worktreeStuckSlowRetryMs)
         ?? shared.ENGINE_DEFAULTS.worktreeStuckSlowRetryMs

package/engine.js

@@ -916,6 +916,10 @@ async function runWorktreeAdd(rootDir, worktreePath, addArgs, gitOpts, worktreeC
         log('warn', `Retrying git worktree add (attempt ${attempt + 1}/${retries + 1}) for ${path.basename(worktreePath)}`);
       }
       await shared.shellSafeGit(['worktree', 'add', worktreePath, ...addArgs], { ...gitOpts, cwd: rootDir });
+      // W-mqecdoot — stamp the engine ownership marker so the out-of-root
+      // worktree GC can distinguish a worktree we created from one a human
+      // developer made by hand. Best-effort; never blocks the spawn.
+      shared.writeWorktreeOwnerMarker(worktreePath, { rootDir });
       return;
     } catch (err) {
       lastErr = err;
@@ -3302,6 +3306,14 @@ async function spawnAgent(dispatchItem, config) {
   // them unconditionally regardless of repo host.
   childEnv.GIT_TERMINAL_PROMPT = '0';
   childEnv.GCM_INTERACTIVE = 'never';
+  // W-mqef-dashboard-tty — agents run headless and must never pop a browser on
+  // the operator's desktop. Stamp the suppression env so anything an agent runs
+  // that funnels through shared.openUrlInBrowser — notably the dashboard a
+  // `npm test` run boots — inherits the guard. The engine's own process env did
+  // NOT carry this flag, so agent-spawned dashboards were self-opening to a
+  // random localhost port (blank window). Belt-and-suspenders with dashboard.js's
+  // stdout.isTTY gate.
+  childEnv.MINIONS_NO_AUTO_OPEN = '1';
 
   if (getRepoHost(project) === 'ado') {
     // Inject cached ADO token so ADO agents skip re-authentication (#998).
@@ -3752,6 +3764,9 @@ async function spawnAgent(dispatchItem, config) {
       // credential dialogs on `git push` against stale PATs.
       childEnv.GIT_TERMINAL_PROMPT = '0';
       childEnv.GCM_INTERACTIVE = 'never';
+      // W-mqef-dashboard-tty — same browser-popup suppression on steering resume
+      // (see the initial spawn site). Agents must never auto-open a browser.
+      childEnv.MINIONS_NO_AUTO_OPEN = '1';
       if (getRepoHost(project) === 'ado') {
         // Inject cached ADO token for steering session too (#998)
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2187",
+  "version": "0.1.2189",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"