@link-assistant/hive-mind 2.0.3 → 2.0.5

package/src/cleanup.os.lib.mjs

@@ -570,6 +570,12 @@ export function listActiveTaskRefsFromProc() {
  * Discover currently-running isolation session UUIDs from start-command's live
  * session managers (screen / tmux). These names are the session UUIDs.
  *
+ * @deprecated Superseded by {@link listSessionTasks}, which sources every
+ * session (active *and* finished) from the single `$ --list` catalog rather
+ * than re-deriving liveness from `screen -ls`/`tmux ls`. Retained as a
+ * documented building block (issue #1848 case study) and for callers that only
+ * want live screen/tmux UUIDs without start-command.
+ *
  * @returns {string[]}
  */
 export function listLiveSessionIds() {
@@ -597,6 +603,11 @@ export function listLiveSessionIds() {
  * Query `$ --status <uuid>` for each live session and extract task references
  * from executing sessions' command lines. Optional; reuses isolation-runner.
  *
+ * @deprecated Superseded by {@link listSessionTasks} (issue #1927 review), which
+ * reads the whole catalog from one `$ --list` call instead of N per-session
+ * `$ --status` queries and also surfaces finished sessions. Kept for the issue
+ * #1848 case study and backward compatibility.
+ *
  * @param {string[]} sessionIds
  * @returns {Promise<Array<{owner, repo, type, number}>>}
  */
@@ -650,33 +661,108 @@ export function resolvePrHeadBranch(ref) {
   return out || null;
 }
 
+/**
+ * Enumerate ALL tasks known to start-command from the single `$ --list` source
+ * (issue #1927 review): one record per GitHub issue/PR reference found in each
+ * session's command line, carrying that session's id/name/status/workspace and a
+ * `terminal` flag (whether the session has finished). Unlike
+ * {@link listActiveTaskRefsFromSessions}, this includes *completed* sessions so a
+ * stale `gh-issue-solver-*` folder can be annotated with the PR and session it
+ * once belonged to — even after the task is no longer running.
+ *
+ * This consolidates session enumeration onto start-command's own `$ --list`
+ * (which knows every session, not just the ones still alive in screen/tmux) so
+ * `/queue`, `/limits`, the monitor and cleanup all read the same `$` data.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.verbose=false]
+ * @param {boolean} [options.resolveBranches=false] - resolve PR head branches via gh
+ * @returns {Promise<Array<{owner, repo, type, number, branch: string|null, sessionId: string|null, sessionName: string|null, status: string|null, workspace: string|null, terminal: boolean, startTime: string|null}>>}
+ */
+export async function listSessionTasks(options = {}) {
+  const { verbose = false, resolveBranches = false } = options;
+  let listIsolationSessions;
+  let isTerminalSessionStatus;
+  try {
+    ({ listIsolationSessions, isTerminalSessionStatus } = await import('./isolation-runner.lib.mjs'));
+  } catch {
+    return [];
+  }
+
+  let sessions = [];
+  try {
+    sessions = await listIsolationSessions(verbose);
+  } catch {
+    return [];
+  }
+
+  // Newest session first, so when several sessions worked the same issue/PR the
+  // most recent one is the match a folder gets annotated with.
+  const sorted = [...sessions].sort((a, b) => new Date(b.startTime || 0).getTime() - new Date(a.startTime || 0).getTime());
+
+  const tasks = [];
+  for (const session of sorted) {
+    if (!session || !session.command) continue;
+    const terminal = !!(session.status && isTerminalSessionStatus(session.status));
+    for (const ref of extractTaskRefsFromCommand(session.command)) {
+      tasks.push({
+        ...ref,
+        branch: null,
+        sessionId: session.uuid || null,
+        sessionName: session.sessionName || null,
+        status: session.status || null,
+        workspace: session.workingDirectory || null,
+        terminal,
+        startTime: session.startTime || null,
+      });
+    }
+  }
+
+  if (resolveBranches) {
+    const branchCache = new Map();
+    for (const task of tasks) {
+      if (task.type !== 'pull') continue;
+      const key = `${task.owner}/${task.repo}#${task.number}`;
+      if (!branchCache.has(key)) branchCache.set(key, resolvePrHeadBranch(task));
+      task.branch = branchCache.get(key);
+    }
+  }
+
+  return tasks;
+}
+
 /**
  * Build the full active-task list, resolving PR head branches where possible.
  *
  * @param {Object} [options]
- * @param {boolean} [options.useSessions=true] - also query `$ --status`
+ * @param {boolean} [options.useSessions=true] - also consult `$ --list` sessions
  * @param {boolean} [options.resolveBranches=true] - resolve PR head branches via gh
+ * @param {Array} [options.sessionTasks] - pre-fetched `listSessionTasks()` result to reuse
  * @returns {Promise<Array<{owner, repo, type, number, branch: string|null}>>}
  */
 export async function getActiveTasks(options = {}) {
-  const { useSessions = true, resolveBranches = true } = options;
+  const { useSessions = true, resolveBranches = true, sessionTasks = null } = options;
   const refs = [...listActiveTaskRefsFromProc()];
   const seen = new Set(refs.map(r => `${r.owner}/${r.repo}#${r.number}:${r.type}`));
 
   if (useSessions) {
-    const sessionRefs = await listActiveTaskRefsFromSessions(listLiveSessionIds());
-    for (const ref of sessionRefs) {
-      const key = `${ref.owner}/${ref.repo}#${ref.number}:${ref.type}`;
+    // Active = sessions start-command still reports as non-terminal. Reuse the
+    // shared `$ --list` enumeration (optionally pre-fetched by the caller so the
+    // catalog is read only once).
+    const allSessionTasks = sessionTasks || (await listSessionTasks({ verbose: false, resolveBranches: false }));
+    for (const task of allSessionTasks) {
+      if (task.terminal) continue;
+      const key = `${task.owner}/${task.repo}#${task.number}:${task.type}`;
       if (!seen.has(key)) {
         seen.add(key);
-        refs.push(ref);
+        refs.push(task);
       }
     }
   }
 
   return refs.map(ref => {
-    let branch = null;
-    if (ref.type === 'pull' && resolveBranches) {
+    let branch = ref.branch || null;
+    if (!branch && ref.type === 'pull' && resolveBranches) {
       branch = resolvePrHeadBranch(ref);
     }
     return { ...ref, branch };

package/src/interactive-mcp-status.lib.mjs

@@ -1,21 +1,36 @@
 const PLAYWRIGHT_TOOL_PREFIX = 'mcp__playwright__';
 
-export const isUnavailableMcpStatus = status => {
+// A `pending` (or `connecting`) MCP server is still being connected/reconnected
+// in the background. It is NOT a failure: Claude Code enables Tool Search by
+// default, so MCP tools are deferred and load on demand, and Claude waits for a
+// still-connecting server before it uses one of that server's tools. See
+// https://code.claude.com/docs/en/mcp and issue #1901.
+export const isConnectingMcpStatus = status => /\b(pending|connecting)\b/i.test(String(status || ''));
+
+// Terminal/unhealthy states where the MCP client has given up (or the server is
+// turned off). Claude Code reconnects an HTTP/SSE server with exponential
+// backoff and only marks it `failed` after the attempts are exhausted; at that
+// point the server's tools never load.
+export const isFailedMcpStatus = status => {
   const normalized = String(status || '').toLowerCase();
-  return /\b(pending|disabled|failed|error|disconnected|not[-_\s]+connected|unavailable|timed[-_\s]+out)\b|(?:^|[^a-z0-9_-])timeout(?:$|[^a-z0-9_-])/.test(normalized);
+  return /\b(disabled|failed|error|disconnected|not[-_\s]+connected|unavailable|timed[-_\s]+out)\b|(?:^|[^a-z0-9_-])timeout(?:$|[^a-z0-9_-])/.test(normalized);
 };
 
+// Backwards-compatible umbrella: any non-connected status (still connecting OR
+// failed). Prefer the narrower helpers above when the connecting/failed
+// distinction matters (e.g. whether to warn a human reviewer).
+export const isUnavailableMcpStatus = status => isConnectingMcpStatus(status) || isFailedMcpStatus(status);
+
 export const hasPlaywrightMcpTools = tools => (Array.isArray(tools) ? tools : []).some(tool => String(tool || '').startsWith(PLAYWRIGHT_TOOL_PREFIX));
 
 export const formatInteractiveMcpServerStatus = server => {
   const name = server?.name || 'unknown';
   const status = String(server?.status || 'unknown').trim() || 'unknown';
-  const normalizedStatus = status.toLowerCase();
   let displayStatus = status;
 
-  if (normalizedStatus === 'pending') {
-    displayStatus = 'pending - not connected; MCP tools unavailable';
-  } else if (isUnavailableMcpStatus(status)) {
+  if (isConnectingMcpStatus(status)) {
+    displayStatus = `${status} - connecting; tools load on demand via Tool Search`;
+  } else if (isFailedMcpStatus(status)) {
     displayStatus = `${status} - MCP tools unavailable`;
   }
 
@@ -29,10 +44,16 @@ export const getInteractiveMcpDiagnostics = (mcpServers = [], tools = []) => {
   for (const server of servers) {
     const name = String(server?.name || '').toLowerCase();
     if (!name.includes('playwright')) continue;
-    if (!isUnavailableMcpStatus(server?.status)) continue;
+    // With Tool Search the deferred `mcp__playwright__*` tools are intentionally
+    // absent from system.init `tools`, so their absence is not a problem by
+    // itself. If they are already present the server is fully connected.
     if (hasPlaywrightMcpTools(tools)) continue;
+    // `pending`/`connecting` is the normal startup state — Claude waits for the
+    // server before using a browser tool — so only warn when the MCP client has
+    // actually failed to connect.
+    if (!isFailedMcpStatus(server?.status)) continue;
 
-    diagnostics.push(`⚠️ Playwright MCP server is ${server?.status || 'unknown'}, but no \`${PLAYWRIGHT_TOOL_PREFIX}*\` browser tools were exposed. Browser automation hints are disabled until the MCP client reports the server as connected.`);
+    diagnostics.push(`⚠️ Playwright MCP server is ${server?.status || 'unknown'} (failed to connect), so no \`${PLAYWRIGHT_TOOL_PREFIX}*\` browser tools are available. Browser automation stays disabled until the MCP server connects.`);
   }
 
   return diagnostics;

package/src/isolation-runner.lib.mjs

@@ -18,6 +18,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { isExecutingSessionStatus, isTerminalSessionStatus } from './session-status.lib.mjs';
 
 if (typeof use === 'undefined') {
   await ensureUseM();
@@ -25,10 +26,14 @@ if (typeof use === 'undefined') {
 
 const { $ } = await use('command-stream');
 
+// Re-export the shared status predicates so existing callers that reach them via
+// the isolation-runner module (e.g. session-monitor's `runner.isExecutingSessionStatus`)
+// keep working. The canonical definitions live in session-status.lib.mjs so the
+// killed/terminated/oom vocabulary stays consistent everywhere (issue #1927).
+export { isExecutingSessionStatus, isTerminalSessionStatus, isKilledSessionStatus } from './session-status.lib.mjs';
+
 // Valid isolation backends
 const VALID_ISOLATION_BACKENDS = ['screen', 'tmux', 'docker'];
-const RUNNING_SESSION_STATUSES = new Set(['executing', 'running']);
-const TERMINAL_SESSION_STATUSES = new Set(['executed', 'completed', 'failed', 'cancelled', 'canceled', 'error']);
 const HIVE_MIND_IMAGE_REPO = 'konard/hive-mind';
 const HIVE_MIND_DIND_IMAGE_REPO = 'konard/hive-mind-dind';
 const DEFAULT_HIVE_MIND_IMAGE_TAG = 'latest';
@@ -379,14 +384,6 @@ export function parseSessionStatusOutput(output) {
   };
 }
 
-export function isExecutingSessionStatus(status) {
-  return RUNNING_SESSION_STATUSES.has(String(status || '').toLowerCase());
-}
-
-export function isTerminalSessionStatus(status) {
-  return TERMINAL_SESSION_STATUSES.has(String(status || '').toLowerCase());
-}
-
 /**
  * Decide whether a detached-docker exit code is "unknown" (not a real result).
  *
@@ -409,6 +406,82 @@ export function shouldFallbackToScreenStatus(statusResult) {
   return !statusResult?.exists || !statusResult?.status;
 }
 
+/**
+ * Parse the footer start-command appends to every execution log when the wrapped
+ * command exits. The footer is authoritative about the terminal exit code even
+ * when `$ --status` is wrong: start-command writes it from the command's own
+ * `close`/`exited` handler, so its presence proves the command terminated.
+ *
+ * Footer shape (see start-command spawn-helpers.js):
+ *
+ *     ==================================================
+ *     Finished: 2026-06-14 19:10:49.822
+ *     Exit Code: 137
+ *
+ * Issue #1927: start-command's `enrichDetachedStatus` can flip a completed
+ * `executed/137` record back to `executing` (nulling the exit code) when a
+ * lingering shell keeps the screen session alive — so `$ --status` reports
+ * `executing` forever and the bot never notices the kill. Reading this footer
+ * lets hive-mind detect the real terminal exit regardless of that flip.
+ *
+ * @param {string} text - Log text (typically the tail of the log file)
+ * @returns {{finished: boolean, exitCode: number|null, endTime: string|null}}
+ */
+export function parseSessionExitFooter(text) {
+  if (!text) return { finished: false, exitCode: null, endTime: null };
+  // Match the LAST footer block in the text (a re-run could append more than
+  // one). Anchor on the `=` separator so command output that merely prints
+  // "Exit Code: N" mid-stream is not mistaken for the footer.
+  const re = /={10,}\s*\r?\nFinished:\s*([^\r\n]+)\r?\nExit Code:\s*(-?\d+)/g;
+  let match;
+  let last = null;
+  while ((match = re.exec(text)) !== null) last = match;
+  if (!last) return { finished: false, exitCode: null, endTime: null };
+  return { finished: true, exitCode: Number(last[2]), endTime: last[1].trim() };
+}
+
+/**
+ * Read the terminal exit code from the tail of a start-command execution log.
+ *
+ * Only the last `tailBytes` of the file are read (the footer lives at the end),
+ * so this is cheap even for multi-megabyte logs. Never throws — a missing or
+ * unreadable log yields `{ finished: false }`.
+ *
+ * @param {string} logPath
+ * @param {Object} [options]
+ * @param {Object} [options.fsImpl=fs] - Injectable fs (for tests)
+ * @param {number} [options.tailBytes=16384] - How many trailing bytes to scan
+ * @param {boolean} [options.verbose]
+ * @returns {{finished: boolean, exitCode: number|null, endTime: string|null}}
+ */
+export function readSessionExitFromLog(logPath, options = {}) {
+  const { fsImpl = fs, tailBytes = 16384, verbose = false } = options;
+  if (!logPath) return { finished: false, exitCode: null, endTime: null };
+  try {
+    const { size } = fsImpl.statSync(logPath);
+    if (!size) return { finished: false, exitCode: null, endTime: null };
+    const start = Math.max(0, size - tailBytes);
+    const length = size - start;
+    const buffer = Buffer.alloc(length);
+    const fd = fsImpl.openSync(logPath, 'r');
+    try {
+      fsImpl.readSync(fd, buffer, 0, length, start);
+    } finally {
+      fsImpl.closeSync(fd);
+    }
+    const result = parseSessionExitFooter(buffer.toString('utf8'));
+    if (verbose && result.finished) {
+      console.log(`[VERBOSE] isolation-runner: log footer for ${logPath} reports exit ${result.exitCode} (finished ${result.endTime})`);
+    }
+    return result;
+  } catch (error) {
+    if (verbose) {
+      console.log(`[VERBOSE] isolation-runner: could not read exit footer from ${logPath}: ${error.message}`);
+    }
+    return { finished: false, exitCode: null, endTime: null };
+  }
+}
+
 /**
  * Find the `$` CLI binary path
  * @returns {Promise<string|null>} Path to `$` binary or null
@@ -583,6 +656,78 @@ export async function querySessionStatus(sessionId, verbose = false) {
   }
 }
 
+/**
+ * Parse output from `$ --list --output-format json`.
+ *
+ * start-command may return a top-level array, or an object with an
+ * `executions`/`sessions` array. Each entry is normalized to the same shape used
+ * by {@link parseSessionStatusOutput} (uuid/status/exitCode/command/isolation/…).
+ * Tolerant of unknown layouts — anything unparseable yields an empty list.
+ *
+ * @param {string} output - Raw stdout from `$ --list`
+ * @returns {Array<{uuid: string|null, status: string|null, exitCode: number|null, startTime: string|null, endTime: string|null, command: string|null, isolation: string|null, workingDirectory: string|null, sessionName: string|null}>}
+ */
+export function parseSessionListOutput(output) {
+  const raw = (output || '').trim();
+  if (!raw) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  const records = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.executions) ? parsed.executions : Array.isArray(parsed?.sessions) ? parsed.sessions : parsed && typeof parsed === 'object' ? [parsed] : [];
+
+  return records
+    .map(data => {
+      if (!data || typeof data !== 'object') return null;
+      const isolationCandidate = (typeof data.isolation === 'string' && data.isolation) || (typeof data.options?.isolated === 'string' && data.options.isolated) || (typeof data.options?.isolation === 'string' && data.options.isolation) || null;
+      return {
+        uuid: data.uuid || data.session || data.sessionId || null,
+        status: typeof data.status === 'string' ? data.status.toLowerCase() : null,
+        exitCode: data.exitCode !== undefined && data.exitCode !== null ? Number(data.exitCode) : null,
+        startTime: data.startTime || null,
+        endTime: data.endTime || null,
+        command: data.command || null,
+        isolation: isolationCandidate ? isolationCandidate.toLowerCase() : null,
+        workingDirectory: data.workingDirectory || null,
+        sessionName: data.sessionName || data.options?.sessionName || null,
+      };
+    })
+    .filter(Boolean);
+}
+
+/**
+ * List all executions known to start-command via `$ --list --output-format json`.
+ *
+ * Unlike `$ --status`, the `--list` path does NOT run start-command's
+ * `enrichDetachedStatus` liveness gate, so it reports the recorded status/exit
+ * code as stored. Used by the bot's restart-resume scan to discover detached
+ * solve/hive/task sessions that were launched before the bot last started
+ * (issue #1927, requirement #2). Never throws — returns an empty list on any
+ * failure.
+ *
+ * @param {boolean} [verbose]
+ * @returns {Promise<Array<object>>} Normalized session records (see parseSessionListOutput)
+ */
+export async function listIsolationSessions(verbose = false) {
+  const binPath = await findStartCommandBinary();
+  if (!binPath) {
+    if (verbose) console.log('[VERBOSE] isolation-runner: Cannot list sessions - $ binary not found');
+    return [];
+  }
+  try {
+    const result = await $({ mirror: false })`${binPath} --list --output-format json`;
+    const stdout = result.stdout?.toString().trim() || '';
+    const sessions = parseSessionListOutput(stdout);
+    if (verbose) console.log(`[VERBOSE] isolation-runner: $ --list returned ${sessions.length} session(s)`);
+    return sessions;
+  } catch (error) {
+    if (verbose) console.log(`[VERBOSE] isolation-runner: $ --list error: ${error.message}`);
+    return [];
+  }
+}
+
 /**
  * Ask the `$` CLI to gracefully stop an isolated session by sending CTRL+C.
  *
@@ -686,6 +831,45 @@ export async function checkDockerContainerRunning(containerName, verbose = false
   }
 }
 
+/**
+ * Check whether a tmux session with the given name still exists.
+ * `tmux has-session -t <name>` exits 0 when it exists and non-zero otherwise,
+ * so command-stream throwing is treated as "not found".
+ *
+ * @param {string} sessionName
+ * @param {boolean} [verbose]
+ * @returns {Promise<boolean>}
+ */
+export async function checkTmuxSessionRunning(sessionName, verbose = false) {
+  try {
+    await $({ mirror: false })`tmux has-session -t ${sessionName}`;
+    if (verbose) console.log(`[VERBOSE] isolation-runner: tmux has-session '${sessionName}': running`);
+    return true;
+  } catch {
+    if (verbose) console.log(`[VERBOSE] isolation-runner: tmux has-session '${sessionName}': not found`);
+    return false;
+  }
+}
+
+/**
+ * Directly probe whether the backend session/container is still alive, bypassing
+ * `$ --status`. This is the cross-check used to detect a session that
+ * start-command still reports as `executing` even though its backing process is
+ * gone (issue #1927). Returns `null` for unknown backends so callers can treat
+ * an indeterminate probe as "no signal" rather than "dead".
+ *
+ * @param {string} sessionId - Session UUID (also the screen name / container name)
+ * @param {string} backend - 'screen' | 'tmux' | 'docker'
+ * @param {boolean} [verbose]
+ * @returns {Promise<boolean|null>}
+ */
+export async function checkBackendSessionAlive(sessionId, backend, verbose = false) {
+  if (backend === 'screen') return checkScreenSessionRunning(sessionId, verbose);
+  if (backend === 'tmux') return checkTmuxSessionRunning(sessionId, verbose);
+  if (backend === 'docker') return checkDockerContainerRunning(sessionId, verbose);
+  return null;
+}
+
 /**
  * Check whether an image is present in the local Docker daemon.
  *