@link-assistant/hive-mind 2.16.0 → 2.17.0

package/src/agent.version-gates.lib.mjs

@@ -0,0 +1,73 @@
+/**
+ * Version floors for the Agent CLI, and the predicates that read them.
+ *
+ * Each floor is the first Agent release in which a behaviour Hive Mind depends
+ * on actually holds; below it the CLI does something subtly wrong rather than
+ * failing, so the caller refuses to start instead of trusting the result. The
+ * comments on each constant record which upstream issue moved the floor.
+ *
+ * Extracted from `src/agent.lib.mjs` when issue #2186 pushed that file past the
+ * 1350-line warning threshold enforced by `scripts/check-file-line-limits.sh`.
+ * `agent.lib.mjs` re-exports every name here, so importers are unaffected.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2198
+ */
+
+import semver from 'semver';
+
+export const MIN_AGENT_LIVE_INPUT_VERSION = '0.24.1';
+
+export const getAgentCliVersion = versionOutput => {
+  // `agent --version` can come back as `undefined` when the probe times out or
+  // the binary writes nothing to stdout, and `semver.clean(undefined)` throws.
+  // The floors below must answer "unknown", not blow up, so the caller reports
+  // the missing version instead of a `TypeError`.
+  const text = versionOutput == null ? '' : String(versionOutput);
+  return semver.clean(text) || semver.coerce(text)?.version || null;
+};
+
+export const agentCliSupportsLiveInput = versionOutput => {
+  const version = getAgentCliVersion(versionOutput);
+  return !!version && semver.gte(version, MIN_AGENT_LIVE_INPUT_VERSION);
+};
+
+/**
+ * Agent only fails closed on a `--model` argv it cannot parse from js-0.25.8
+ * onwards (link-assistant/agent#293, fixed by PR #294): earlier releases logged
+ * a CRITICAL record and then answered with their *default* model. Issue #2146
+ * requires Formal AI to be the only model a task can reach, and a guard that
+ * reads the CRITICAL record can only stop the run after Agent has already
+ * decided, so a Formal AI task refuses to start below this release.
+ */
+export const MIN_AGENT_FORMAL_AI_VERSION = '0.25.8';
+
+/** True when this Agent CLI aborts instead of silently picking another model. */
+export const agentCliFailsClosedOnModelMismatch = versionOutput => {
+  const version = getAgentCliVersion(versionOutput);
+  return !!version && semver.gte(version, MIN_AGENT_FORMAL_AI_VERSION);
+};
+
+/**
+ * Agent keeps a rollback snapshot per project under
+ * `$XDG_DATA_HOME/link-assistant-agent/snapshot/<project id>`, and that project
+ * id is the worktree's *root commit*. Before js-0.26.1 the store was a
+ * standalone object database — no `objects/info/alternates` — and nothing ever
+ * removed it, so any harness that runs the agent inside a throwaway `git init`
+ * checkout minted a brand-new full copy of the repository per invocation and
+ * never reclaimed one. Issue #2186 measured 115 orphaned stores / 31 GB in a
+ * single 9.5 h task (~5 GB/h, every recorded worktree already deleted) while
+ * every Hive Mind disk check — the 10 GB pre-flight gate, `disk-guard`,
+ * `hive-cleanup` — reported a healthy workspace, because all of them only look
+ * at `/tmp`. link-assistant/agent#298 (PR #300, shipped in 0.26.1) shares the
+ * repository's objects through `objects/info/alternates` and prunes projects
+ * whose recorded worktree no longer exists, which is what makes an unattended
+ * multi-hour run bounded. Older releases are refused rather than left to fill
+ * the disk.
+ */
+export const MIN_AGENT_SNAPSHOT_HYGIENE_VERSION = '0.26.1';
+
+/** True when this Agent CLI shares snapshot objects and prunes dead projects. */
+export const agentCliPrunesOrphanSnapshots = versionOutput => {
+  const version = getAgentCliVersion(versionOutput);
+  return !!version && semver.gte(version, MIN_AGENT_SNAPSHOT_HYGIENE_VERSION);
+};

package/src/bot-lifecycle.lib.mjs

@@ -83,6 +83,52 @@ export function createHeartbeat({ logger, getActiveSessionCount, intervalMs = DE
   };
 }
 
+/**
+ * Reconcile the isolation backend's own view of still-running executions.
+ *
+ * Issue #2189: the detached-docker completion watchers are children of the
+ * process that launched them, so a bot restart leaves every running container
+ * unsupervised — its exit is never written to the log footer, which is one of
+ * the ways the reported session stayed in limbo. `$ --resume-all`
+ * (start-command >= 0.33.0) re-attaches a watcher to what is still alive and
+ * finalizes what died meanwhile; it starts no work on its own.
+ *
+ * Run *before* the durable store is replayed so the first monitor tick reads
+ * settled state rather than racing upstream's reconciliation. An older `$`
+ * without the verb, or no isolation at all, is a no-op — never an error.
+ *
+ * @returns {Promise<{attempted: boolean, reconciled: number, reattached: number, running: number, unsupported: boolean, error: string|null}>}
+ */
+async function reconcileIsolationExecutions({ reconcileIsolationSessions, verbose, logger, consoleImpl }) {
+  const idle = { attempted: false, reconciled: 0, reattached: 0, running: 0, unsupported: false, error: null };
+  if (typeof reconcileIsolationSessions !== 'function') return idle;
+  try {
+    const result = await reconcileIsolationSessions({ verbose });
+    const executions = Array.isArray(result?.executions) ? result.executions : [];
+    const count = action => executions.filter(entry => entry?.action === action).length;
+    const summary = {
+      attempted: true,
+      reconciled: count('reconciled'),
+      reattached: count('reattached'),
+      running: count('running'),
+      unsupported: result?.unsupported === true,
+      error: result?.success === false && result?.unsupported !== true ? result?.error || 'unknown error' : null,
+    };
+    if (summary.reconciled > 0 || summary.reattached > 0) {
+      consoleImpl.log(`♻️  Reconciled ${executions.length} isolated execution(s) with the isolation backend (${summary.reattached} re-attached, ${summary.reconciled} finalized after running unsupervised)`);
+    } else if (verbose) {
+      consoleImpl.log(`[VERBOSE] resume-all: ${summary.unsupported ? 'this `$` build has no --resume-all; skipped' : `${executions.length} execution(s), nothing to re-attach`}`);
+    }
+    logger?.event?.('isolation_executions_reconciled', summary);
+    return summary;
+  } catch (error) {
+    // Startup reconciliation is best effort by construction: it must never be
+    // able to stop the bot from coming up.
+    consoleImpl.error(`[telegram-bot] Could not reconcile isolated executions: ${error?.message || error}`);
+    return { ...idle, attempted: true, error: error?.message || String(error) };
+  }
+}
+
 /**
  * Resume sessions left tracked by a previous run (requirements #2/#4).
  *
@@ -92,9 +138,14 @@ export function createHeartbeat({ logger, getActiveSessionCount, intervalMs = DE
  * `sessions_resumed` event either way and never throws: a resume failure must
  * not stop the bot from coming up.
  *
- * @returns {Promise<{ resumed: any[], skipped: any[], error?: Error }>}
+ * Issue #2189 added the step before it: `reconcileIsolationSessions`
+ * (`$ --resume-all`) settles the isolation backend's own record of what is
+ * still running, so the replayed sessions are matched against the truth.
+ *
+ * @returns {Promise<{ resumed: any[], skipped: any[], reconciliation: object, error?: Error }>}
  */
-export async function resumeSessionsOnLaunch({ resumeTrackedSessions, botStartTime, verbose = false, logger, consoleImpl = console } = {}) {
+export async function resumeSessionsOnLaunch({ resumeTrackedSessions, reconcileIsolationSessions = null, botStartTime, verbose = false, logger, consoleImpl = console } = {}) {
+  const reconciliation = await reconcileIsolationExecutions({ reconcileIsolationSessions, verbose, logger, consoleImpl });
   try {
     const { resumed, skipped } = await resumeTrackedSessions({ botStartTime, verbose });
     if (resumed.length > 0) {
@@ -105,11 +156,11 @@ export async function resumeSessionsOnLaunch({ resumeTrackedSessions, botStartTi
       skipped: skipped.length,
       sessions: resumed.map(r => r.sessionName),
     });
-    return { resumed, skipped };
+    return { resumed, skipped, reconciliation };
   } catch (error) {
     consoleImpl.error(`[telegram-bot] Failed to resume tracked sessions: ${error.message}`);
     logger.error('Failed to resume tracked sessions', { error: error.message });
-    return { resumed: [], skipped: [], error };
+    return { resumed: [], skipped: [], reconciliation, error };
   }
 }
 

package/src/cleanup.mjs

@@ -39,6 +39,7 @@ import { isConfirmationYes, readConfirmationLine } from './confirmation.lib.mjs'
 import { classifyEntries, summarize, formatBytes, describeReason, buildActiveMatchers, DEFAULT_PROTECTED_NAMES, formatEntryContext, formatTaskSummary, DEFAULT_DOCKER_ISOLATION_CLEANUP_MODE, describeDockerIsolationReason, formatDockerIsolationContainerSummary, normalizeDockerIsolationCleanupMode, planDockerIsolationCleanup } from './cleanup.lib.mjs';
 import { getTempRoot, listTempEntries, getPathSize, readFolderGitInfo, listProcessHeldPaths, getActiveTasks, listSessionTasks, removePath, runSystemCleanup, collectProcessDebugReport, signalOrphanedAgentTrees, listDockerIsolationContainers, removeDockerContainer } from './cleanup.os.lib.mjs';
 import { formatProcessDebugReport } from './process-debug.lib.mjs';
+import { classifyAgentSnapshotStores, describeAgentSnapshotReason, getAgentDataHome } from './agent-snapshot-store.lib.mjs';
 import { setupStdioLogInterceptor } from './lib.mjs';
 import { sanitizeCredentialText } from './credential-sanitization-core.lib.mjs';
 
@@ -138,6 +139,11 @@ System / Ubuntu cleanup (opt-in):
   --system                    Shorthand for --apt --journal --npm
   --sudo                      Prefix package-manager commands with sudo
 
+Agent state cleanup (issue #2186):
+  --no-agent-snapshots        Do not reclaim orphaned @link-assistant/agent
+                              snapshot stores under
+                              $XDG_DATA_HOME/link-assistant-agent/snapshot/
+
 Docker isolation cleanup:
   --docker-isolation[=<mode>] Clean task containers named by session UUID
                               [default: ${DEFAULT_DOCKER_ISOLATION_CLEANUP_MODE}]
@@ -173,6 +179,7 @@ const options = {
   journal: hasFlag('--journal', '--system'),
   docker: hasFlag('--docker'),
   dockerIsolationMode: parseDockerIsolationMode(),
+  agentSnapshots: !hasFlag('--no-agent-snapshots'),
   npm: hasFlag('--npm', '--system'),
   sudo: hasFlag('--sudo'),
 };
@@ -371,18 +378,48 @@ async function main() {
     }
   }
 
-  await log(`\n📊 Summary: keep ${totals.keepCount} (${formatBytes(totals.keepBytes)}), remove ${totals.removeCount} (${formatBytes(totals.removeBytes)}), docker keep ${dockerIsolationPlan.keep.length}, docker remove ${dockerIsolationPlan.remove.length}`);
+  // Issue #2186: agent's snapshot stores live in the home directory, outside the
+  // tmp root everything above scans, and each one is a full copy of a
+  // repository. A store is only listed for removal when the worktree its project
+  // record points at is gone, so this can never disturb a live checkout.
+  let agentSnapshotPlan = { orphaned: [], keep: [] };
+  if (!options.agentSnapshots) {
+    await log('\n🗄️  Agent snapshot stores: disabled (--no-agent-snapshots)');
+  } else {
+    const agentDataHome = getAgentDataHome();
+    agentSnapshotPlan = await classifyAgentSnapshotStores({ dataHome: agentDataHome });
+    for (const item of [...agentSnapshotPlan.keep, ...agentSnapshotPlan.orphaned]) item.size = getPathSize(item.path);
+    const orphanBytes = agentSnapshotPlan.orphaned.reduce((total, item) => total + (item.size || 0), 0);
+    await log(`\n🗄️  Agent snapshot stores (${path.join(agentDataHome, 'snapshot')}):`);
+    if (agentSnapshotPlan.keep.length === 0 && agentSnapshotPlan.orphaned.length === 0) {
+      await log('   (none)');
+    } else {
+      await log('   KEPT:');
+      if (agentSnapshotPlan.keep.length === 0) await log('      (none)');
+      for (const item of agentSnapshotPlan.keep.sort((a, b) => (b.size || 0) - (a.size || 0))) {
+        await log(`      ${formatBytes(item.size).padStart(7)}  ${item.path}  — ${describeAgentSnapshotReason(item.reason)}${item.worktree ? ` (${item.worktree})` : ''}`);
+      }
+      await log(`   ${options.dryRun ? 'WOULD REMOVE' : 'TO REMOVE'} (${formatBytes(orphanBytes)}):`);
+      if (agentSnapshotPlan.orphaned.length === 0) await log('      (none)');
+      for (const item of agentSnapshotPlan.orphaned.sort((a, b) => (b.size || 0) - (a.size || 0))) {
+        await log(`      ${formatBytes(item.size).padStart(7)}  ${item.path}  — ${describeAgentSnapshotReason(item.reason)}${item.worktree ? ` (${item.worktree})` : ''}`);
+      }
+    }
+  }
+
+  await log(`\n📊 Summary: keep ${totals.keepCount} (${formatBytes(totals.keepBytes)}), remove ${totals.removeCount} (${formatBytes(totals.removeBytes)}), docker keep ${dockerIsolationPlan.keep.length}, docker remove ${dockerIsolationPlan.remove.length}, agent snapshots remove ${agentSnapshotPlan.orphaned.length}`);
 
   // 7. Execute deletion (unless dry-run).
   const hasTempRemovals = classified.remove.length > 0;
   const hasDockerRemovals = dockerIsolationPlan.remove.length > 0;
+  const hasAgentSnapshotRemovals = agentSnapshotPlan.orphaned.length > 0;
   if (options.dryRun) {
     await log('\n✅ Dry run complete. Re-run without --dry-run to delete.');
-  } else if (!hasTempRemovals && !hasDockerRemovals) {
+  } else if (!hasTempRemovals && !hasDockerRemovals && !hasAgentSnapshotRemovals) {
     await log('\n✅ Nothing to delete.');
   } else {
     if (!options.force) {
-      console.log(`\n⚠️  This will permanently delete ${classified.remove.length} entries (${formatBytes(totals.removeBytes)}) and remove ${dockerIsolationPlan.remove.length} Docker isolation containers.`);
+      console.log(`\n⚠️  This will permanently delete ${classified.remove.length} entries (${formatBytes(totals.removeBytes)}), ${agentSnapshotPlan.orphaned.length} orphaned agent snapshot stores and remove ${dockerIsolationPlan.remove.length} Docker isolation containers.`);
       console.log('Type "yes" to confirm, or Ctrl+C to cancel:');
       let answer;
       try {
@@ -414,6 +451,23 @@ async function main() {
       await log(`\n✅ Deleted ${deleted} entries${failed ? `, ${failed} failed` : ''}.`);
     }
 
+    if (hasAgentSnapshotRemovals) {
+      await log('\n🗄️  Removing orphaned agent snapshot stores...');
+      let deleted = 0;
+      let failed = 0;
+      for (const item of agentSnapshotPlan.orphaned) {
+        const ok = removePath(item.path);
+        if (ok) {
+          deleted++;
+          await vlog(`   removed ${item.path}`);
+        } else {
+          failed++;
+          await log(`   ⚠️  failed to remove ${item.path}`, { level: 'warn' });
+        }
+      }
+      await log(`\n✅ Deleted ${deleted} orphaned agent snapshot stores${failed ? `, ${failed} failed` : ''}.`);
+    }
+
     if (hasDockerRemovals) {
       await log('\n🐳 Removing Docker isolation containers...');
       let removed = 0;

package/src/disk-guard.lib.mjs

@@ -27,6 +27,8 @@ import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
+import { DEFAULT_AGENT_SNAPSHOT_MIN_IDLE_MS, getAgentDataHome, reclaimAgentSnapshotStores } from './agent-snapshot-store.lib.mjs';
+
 const execFileAsync = promisify(execFile);
 
 /**
@@ -224,8 +226,12 @@ export const reclaimSolverWorkspaces = async ({ requiredMB = 0, tmpRoot = DEFAUL
  *
  * An unreadable `df` never blocks work: the guard is an optimisation over solve's own pre-flight
  * check, not a replacement for it.
+ *
+ * Issue #2186 added a second source of reclaimable space: orphaned
+ * `@link-assistant/agent` snapshot stores in the home directory, which no `/tmp`-scoped check
+ * could see. Pass `agentDataHome: null` to opt out.
  */
-export const ensureDiskSpaceForWorker = async ({ requiredMB = 10240, tmpRoot = DEFAULT_TMP_ROOT, protectedPaths = new Set(), minIdleMs = DEFAULT_MIN_IDLE_MS, maxWaitMs = 0, pollIntervalMs = 30000, log = async () => {}, now = Date.now, sleep = defaultSleep, getFreeMB = getFreeDiskSpaceMB, fileSystem = fsPromises, procRoot = '/proc', remove = defaultRemove } = {}) => {
+export const ensureDiskSpaceForWorker = async ({ requiredMB = 10240, tmpRoot = DEFAULT_TMP_ROOT, protectedPaths = new Set(), minIdleMs = DEFAULT_MIN_IDLE_MS, maxWaitMs = 0, pollIntervalMs = 30000, log = async () => {}, now = Date.now, sleep = defaultSleep, getFreeMB = getFreeDiskSpaceMB, fileSystem = fsPromises, procRoot = '/proc', remove = defaultRemove, agentDataHome = getAgentDataHome(), agentSnapshotMinIdleMs = DEFAULT_AGENT_SNAPSHOT_MIN_IDLE_MS } = {}) => {
   const startedAt = now();
   const reclaimed = [];
   let freeMB = await getFreeMB(tmpRoot);
@@ -239,6 +245,20 @@ export const ensureDiskSpaceForWorker = async ({ requiredMB = 10240, tmpRoot = D
   }
   await log(`   💾 Low disk space: ${freeMB}MB free, ${requiredMB}MB required — reclaiming idle solver workspaces before starting work`, { level: 'warning' });
   for (;;) {
+    // Issue #2186: orphaned agent snapshot stores are pure garbage — their
+    // worktree is gone, so nothing can be restored from them — while a solver
+    // workspace may still be wanted for debugging. Reclaim them first, and note
+    // that they live in the home directory, which every check here used to be
+    // blind to.
+    if (agentDataHome) {
+      const agentResult = await reclaimAgentSnapshotStores({ dataHome: agentDataHome, minIdleMs: agentSnapshotMinIdleMs, stopWhenFreeMB: requiredMB, getFreeMB: () => getFreeMB(tmpRoot), now, log, fileSystem, remove });
+      reclaimed.push(...agentResult.removed);
+      if (agentResult.freeMB !== null && agentResult.freeMB !== undefined) freeMB = agentResult.freeMB;
+      if (freeMB >= requiredMB) {
+        await log(`   ✅ Disk space recovered: ${freeMB}MB free after reclaiming ${agentResult.removed.length} orphaned agent snapshot store(s)`);
+        return { ok: true, freeMB, reason: 'reclaimed', reclaimed, waitedMs: now() - startedAt };
+      }
+    }
     const result = await reclaimSolverWorkspaces({ requiredMB, tmpRoot, protectedPaths, minIdleMs, now, log, fileSystem, procRoot, getFreeMB, remove });
     reclaimed.push(...result.removed);
     if (result.freeMB !== null && result.freeMB !== undefined) freeMB = result.freeMB;

package/src/formal-ai-version.lib.mjs

@@ -29,13 +29,17 @@ export const FORMAL_AI_MEMORY_CONTRACT_MINIMUM_VERSION = '0.336.0';
  * PR #2147 this is the *initial* pin only: once the container is running,
  * `src/formal-ai-updater.lib.mjs` replaces it with the newest published image
  * while no Formal AI task holds a lease. 0.339.0 restored `cargo install
- * formal-ai --locked` on stock Rust images (formal-ai#988) and 0.339.1 routes
- * command execution through the published command-stream component; the
- * memory-contract sources (`src/cli_memory.rs`, `src/server.rs`,
- * `src/shared_memory.rs`) are byte-identical to 0.337.0 and
- * `src/memory/upgrade.rs` only adds an explicit advisory-lock release.
+ * formal-ai --locked` on stock Rust images (formal-ai#988) and 0.339.1 routed
+ * command execution through the published command-stream component. 0.345.0 is
+ * the current release and is a safe bootstrap for the same reason 0.339.1 was:
+ * its Cargo.lock still carries no `openssl-sys`, so the builder stage keeps
+ * building on a stock `rust:slim` image, and the four memory-contract sources
+ * (`src/cli_memory.rs`, `src/server.rs`, `src/shared_memory.rs`,
+ * `src/memory/upgrade.rs`) are byte-identical to 0.339.1 — 0.340.0-0.345.0 only
+ * change reasoning data, benchmarks and unrelated handlers. Verified by
+ * diffing the published crates; see docs/case-studies/issue-2186.
  */
-export const FORMAL_AI_BOOTSTRAP_VERSION = '0.339.1';
+export const FORMAL_AI_BOOTSTRAP_VERSION = '0.345.0';
 
 export const parseFormalAiVersion = stdout => {
   const line = String(stdout || '')

package/src/instrument.mjs

@@ -1,17 +1,6 @@
 // Lazy-load config only when needed to avoid loading use-m at module initialization
 // This prevents network fetches that can hang during --help or --version
-import { sanitizeCredentialText } from './credential-sanitization-core.lib.mjs';
-
-const sanitizeEventValue = (value, seen = new WeakSet()) => {
-  if (typeof value === 'string') return sanitizeCredentialText(value);
-  if (!value || typeof value !== 'object') return value;
-  if (seen.has(value)) return value;
-  seen.add(value);
-  for (const [key, item] of Object.entries(value)) {
-    value[key] = sanitizeEventValue(item, seen);
-  }
-  return value;
-};
+import { sanitizeSentryLog, sanitizeSentryValue } from './instrument.sanitize.lib.mjs';
 
 // Check if Sentry should be disabled
 const shouldDisableSentry = () => {
@@ -78,7 +67,9 @@ if (!shouldDisableSentry()) {
       environment: process.env.NODE_ENV || 'production',
       release: `hive-mind@${process.env.npm_package_version || version.default}`,
 
-      // Send structured logs to Sentry
+      // Send structured logs to Sentry. Stated explicitly even though Sentry
+      // 10.71 made it the default, so the setting stays a decision rather than
+      // whatever the SDK happens to default to next.
       enableLogs: true,
 
       // Tracing
@@ -98,7 +89,7 @@ if (!shouldDisableSentry()) {
 
       // Before send hook to filter out sensitive data
       beforeSend(event) {
-        sanitizeEventValue(event);
+        sanitizeSentryValue(event);
 
         // Filter out sensitive environment variables
         if (event.contexts && event.contexts.runtime && event.contexts.runtime.env) {
@@ -123,6 +114,13 @@ if (!shouldDisableSentry()) {
         return event;
       },
 
+      // Structured logs never pass through beforeSend, so they get the same
+      // masking here — otherwise a token printed by `Sentry.logger.*` would
+      // leave the process verbatim.
+      beforeSendLog(log) {
+        return sanitizeSentryLog(log);
+      },
+
       // Integration specific options
       ignoreErrors: [
         // Ignore specific errors that are expected or not relevant

package/src/instrument.sanitize.lib.mjs

@@ -0,0 +1,52 @@
+/**
+ * Credential sanitization for everything Hive Mind hands to Sentry.
+ *
+ * `src/instrument.mjs` has always masked credentials in *events* (`beforeSend`).
+ * Structured logs are a second, separate pipeline: `enableLogs` sends
+ * `Sentry.logger.*` records straight to the transport, and `beforeSend` is never
+ * called for them. Sentry 10.71 made `enableLogs` the default, so any consumer
+ * that has not opted out now ships that pipeline whether it meant to or not —
+ * which is why the same masking is applied through `beforeSendLog` here.
+ *
+ * Both hooks share one walker so a token can never be masked in one surface and
+ * printed verbatim in the other.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2189
+ */
+
+import { sanitizeCredentialText } from './credential-sanitization-core.lib.mjs';
+
+/**
+ * Recursively mask credentials in a Sentry payload, in place.
+ *
+ * Mutates rather than clones on purpose: Sentry hands us the object it is about
+ * to serialize, and a copy would leave the original untouched. Cycles are
+ * tracked so a self-referencing payload cannot spin forever — the same class of
+ * unbounded work this issue is about.
+ *
+ * @param {*} value - Any part of a Sentry event or log record
+ * @param {WeakSet} [seen] - Cycle guard, supplied by the recursion
+ * @returns {*} The same value with every string masked
+ */
+export const sanitizeSentryValue = (value, seen = new WeakSet()) => {
+  if (typeof value === 'string') return sanitizeCredentialText(value);
+  if (!value || typeof value !== 'object') return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  for (const [key, item] of Object.entries(value)) {
+    value[key] = sanitizeSentryValue(item, seen);
+  }
+  return value;
+};
+
+/**
+ * `beforeSendLog` hook: mask credentials in a structured log record.
+ *
+ * Returns the record (never `null`) so sanitization only ever changes the
+ * content of a log, never whether it is delivered — dropping logs silently
+ * would recreate the blind spot described in Finding F5.
+ *
+ * @param {Object} log - The log record Sentry is about to send
+ * @returns {Object} The same record, masked
+ */
+export const sanitizeSentryLog = log => sanitizeSentryValue(log);

package/src/isolation-runner.lib.mjs

@@ -1,4 +1,3 @@
-import { ensureUseM } from './use-m-bootstrap.lib.mjs';
 /**
  * Isolation Runner for Telegram bot
  *
@@ -30,30 +29,22 @@ import { buildRouterGitConfigEntries, buildRouterTaskEnv, getRouterSuppressedCre
 import { acquireRouterForTask, attachRouterTaskContainer, registerFormalAiWithRouter, releaseRouterForTask } from './router-task-isolation.lib.mjs';
 import { buildGitConfigEnv, GIT_PUSH_GUARD_CONTAINER_DIR, GIT_PUSH_GUARD_ESCAPE_ENV, hasForcePushOptIn, installGitPushGuard } from './git-push-guard.lib.mjs';
 export { getDockerIsolationImage, resolveDockerIsolationImageTag } from './hive-mind-image.lib.mjs';
-let commandStreamDollarPromise = null;
-async function getCommandStreamDollar() {
-  if (!commandStreamDollarPromise) {
-    commandStreamDollarPromise = (async () => {
-      if (typeof globalThis.use === 'undefined') {
-        await ensureUseM();
-      }
-      const { $ } = await globalThis.use('command-stream');
-      return $;
-    })();
-  }
-  try {
-    return await commandStreamDollarPromise;
-  } catch (error) {
-    commandStreamDollarPromise = null;
-    throw error;
-  }
-}
 // 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';
 // Issue #2175: the `$` output parsers live in their own module to keep this file
 // under the 1350-line warning threshold. Re-exported so importers are unaffected.
 import { isUnknownDockerExitCode, parseSessionExitFooter, parseSessionListOutput, parseSessionStatusOutput, parseStartCommandExecutionUuid, readSessionExitFromLog, shouldFallbackToScreenStatus } from './isolation-runner.parsers.lib.mjs';
 export { isUnknownDockerExitCode, parseSessionExitFooter, parseSessionListOutput, parseSessionStatusOutput, parseStartCommandExecutionUuid, readSessionExitFromLog, shouldFallbackToScreenStatus };
+// Issue #2189: the `$` loader and PATH lookup live in their own module so the
+// resume/attach wrappers can use them without importing this runner (a cycle).
+import { findStartCommandBinary, getCommandStreamDollar } from './start-command-cli.lib.mjs';
+export { findStartCommandBinary };
+// Issue #2189: `$ --resume` / `$ --resume-all`, added in start-command 0.33.0
+// (link-foundation/start#162). Re-exported so callers keep reaching every
+// isolation verb through this module.
+import { resumeAllIsolationSessions, resumeIsolatedSession } from './isolation-runner.resume.lib.mjs';
+export { resumeAllIsolationSessions, resumeIsolatedSession };
+export { parseExecutionResumeAllOutput, parseExecutionResumeOutput, RESUME_ALL_ACTIONS, RESUME_MODES } from './isolation-runner.resume.lib.mjs';
 // Valid isolation backends
 const VALID_ISOLATION_BACKENDS = ['screen', 'tmux', 'docker'];
 const DOCKER_CONTAINER_HOME = '/home/box';
@@ -311,20 +302,6 @@ async function runStartCommand(binPath, startCommandArgs) {
 export function generateSessionId() {
   return crypto.randomUUID();
 }
-/**
- * Find the `$` CLI binary path
- * @returns {Promise<string|null>} Path to `$` binary or null
- */
-async function findStartCommandBinary() {
-  try {
-    const $ = await getCommandStreamDollar();
-    const result = await $({ mirror: false })`which $`;
-    const path = result.stdout?.toString().trim() || '';
-    return path || null;
-  } catch {
-    return null;
-  }
-}
 /**
  * Verbose post-launch diagnostics for a native docker-isolated session.
  *
@@ -611,6 +588,21 @@ export async function stopIsolatedSession(sessionId, verbose = false) {
         console.log(`[VERBOSE] isolation-runner: $ --stop ${sessionId} stderr: ${stderr.substring(0, 300)}`);
       }
     }
+    // Issue #2189: `command-stream`'s `$` resolves — it does not throw — when the
+    // child exits non-zero, so the catch below never sees a refusal. `$ --stop`
+    // answers `Error: No execution found with UUID or session name: …` on stderr
+    // with exit code 1; without this check every such refusal was reported to the
+    // operator as a successful stop, and a session nobody stopped looked handled.
+    const code = Number.isFinite(result.code) ? result.code : 0;
+    if (code !== 0) {
+      // describeChildExit rather than an interpolated code: issue #2135 made it
+      // the single vocabulary for "how a child ended", so a `$` that was
+      // signalled reads the same way here as everywhere else. command-stream
+      // normalizes a signalled exit to 128+signum before we see it
+      // (node_modules/command-stream/src/$.process-runner-stream-kill.mjs:194),
+      // so there is no separate signal to pass.
+      return { success: false, output: stdout, error: stderr.trim() || describeChildExit({ command: '`$ --stop`', code }) };
+    }
     return { success: true, output: stdout || stderr, error: null };
   } catch (error) {
     const stderr = error?.stderr?.toString?.() || '';
@@ -679,6 +671,37 @@ export async function checkDockerContainerRunning(containerName, verbose = false
     return false;
   }
 }
+/**
+ * Check whether the Docker container backing a session still exists at all —
+ * running or stopped.
+ *
+ * Issue #2189 requirement R2: a killed session should be re-entered rather than
+ * restarted from scratch, and `$ --resume` can only do that while the container
+ * is still there. `checkDockerContainerRunning` answers a different question (a
+ * stopped container is "not running" but is exactly the one worth resuming), so
+ * the state is read instead of the running flag.
+ *
+ * @param {string} containerName - Container name (the session UUID)
+ * @param {boolean} [verbose] - Enable verbose logging
+ * @returns {Promise<boolean>} True when `docker inspect` finds the container
+ */
+export async function checkDockerContainerExists(containerName, verbose = false) {
+  if (!containerName) return false;
+  try {
+    const $ = await getCommandStreamDollar();
+    const result = await $({ mirror: false })`docker inspect -f ${'{{.State.Status}}'} ${containerName}`;
+    const code = Number.isFinite(result.code) ? result.code : 0;
+    const state = (result.stdout?.toString() || '').trim();
+    const exists = code === 0 && state !== '';
+    if (verbose) {
+      console.log(`[VERBOSE] isolation-runner: docker inspect state for '${containerName}': ${exists ? state : 'no such container'}`);
+    }
+    return exists;
+  } catch {
+    // `docker inspect` exits non-zero when no such container exists.
+    return false;
+  }
+}
 export function parseDockerContainerWritableLayerSizeOutput(output) {
   const text = String(output || '').trim();
   if (!text) return null;

package/src/isolation-runner.parsers.lib.mjs

@@ -73,13 +73,22 @@ export function parseStartCommandExecutionUuid(output) {
  * `--output-format json` is supported, or human-readable key/value text.
  * Keep the parser tolerant so completion monitoring survives either format.
  *
+ * start-command 0.33.0 (link-foundation/start#164, #165) added three additive
+ * hint fields to a finished record: `exitReason` (e.g.
+ * `memory-exhaustion (v8-heap-limit)` or `signal (SIGSEGV)`),
+ * `memoryExhausted` and `memoryExhaustedReason` (the log line carrying the
+ * evidence). They are hints, never verdicts — upstream never lets them change
+ * `status`, `exitCode` or `oomKilled` — and they are absent on older `$`
+ * binaries, so they are parsed as nullable and every consumer keeps its own
+ * log-marker classification as defense in depth (issue #2189).
+ *
  * @param {string} output - Raw stdout from `$ --status`
- * @returns {{exists: boolean, uuid: string|null, status: string|null, exitCode: number|null, startTime: string|null, endTime: string|null, currentTime: string|null, logPath: string|null, command: string|null, isolation: string|null, workingDirectory: string|null, sessionName: string|null, processIds: Object, raw: string}}
+ * @returns {{exists: boolean, uuid: string|null, status: string|null, exitCode: number|null, startTime: string|null, endTime: string|null, currentTime: string|null, logPath: string|null, command: string|null, isolation: string|null, workingDirectory: string|null, sessionName: string|null, processIds: Object, oomKilled: boolean|null, exitReason: string|null, memoryExhausted: boolean|null, memoryExhaustedReason: string|null, raw: string}}
  */
 export function parseSessionStatusOutput(output) {
   const raw = (output || '').trim();
   if (!raw) {
-    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, logPath: null, command: null, isolation: null, workingDirectory: null, sessionName: null, processIds: {}, oomKilled: null, raw: '' };
+    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, logPath: null, command: null, isolation: null, workingDirectory: null, sessionName: null, processIds: {}, oomKilled: null, exitReason: null, memoryExhausted: null, memoryExhaustedReason: null, raw: '' };
   }
   const normalizeBooleanField = value => {
     if (typeof value === 'boolean') return value;
@@ -112,6 +121,9 @@ export function parseSessionStatusOutput(output) {
       sessionName: data?.sessionName || data?.options?.sessionName || null,
       processIds,
       oomKilled: normalizeBooleanField(data?.oomKilled ?? data?.OOMKilled ?? data?.options?.oomKilled ?? data?.state?.oomKilled ?? data?.State?.OOMKilled),
+      exitReason: typeof data?.exitReason === 'string' && data.exitReason.trim() ? data.exitReason.trim() : null,
+      memoryExhausted: normalizeBooleanField(data?.memoryExhausted),
+      memoryExhaustedReason: typeof data?.memoryExhaustedReason === 'string' && data.memoryExhaustedReason.trim() ? data.memoryExhaustedReason.trim() : null,
       raw,
     };
   } catch {
@@ -123,7 +135,11 @@ export function parseSessionStatusOutput(output) {
       .find(line => line.trim() && !line.includes(' '))
       ?.trim() || null;
   const readField = name => {
-    const match = raw.match(new RegExp(`^\\s*${name}\\s+"?([^"\\n]+)"?\\s*$`, 'mi'));
+    // Links notation separates key and value with whitespace (`  exitReason x`);
+    // `--output-format text` uses a padded colon (`Exit Reason:       x`). Accept
+    // both — the colon is optional, so every existing camelCase lookup is
+    // unchanged and the text labels (which contain a space) become readable too.
+    const match = raw.match(new RegExp(`^\\s*${name}\\s*:?\\s+"?([^"\\n]+)"?\\s*$`, 'mi'));
     return match ? match[1].trim() : null;
   };
   const readBooleanField = name => normalizeBooleanField(readField(name));
@@ -154,6 +170,12 @@ export function parseSessionStatusOutput(output) {
     sessionName: readField('sessionName'),
     processIds,
     oomKilled: readBooleanField('oomKilled'),
+    // `--output-format text` labels the same three fields `Exit Reason:`,
+    // `Memory Exhausted:` and `Memory Evidence:`; links notation uses the camelCase
+    // keys. Accept both so the parser does not depend on the output format.
+    exitReason: readField('exitReason') || readField('Exit Reason'),
+    memoryExhausted: readBooleanField('memoryExhausted') ?? readBooleanField('Memory Exhausted'),
+    memoryExhaustedReason: readField('memoryExhaustedReason') || readField('Memory Evidence'),
     raw,
   };
 }
@@ -286,6 +308,10 @@ export function parseSessionListOutput(output) {
         isolation: isolationCandidate ? isolationCandidate.toLowerCase() : null,
         workingDirectory: data.workingDirectory || null,
         sessionName: data.sessionName || data.options?.sessionName || null,
+        // Additive 0.33.0 hints (link-foundation/start#164, #165); null on older `$`.
+        exitReason: typeof data.exitReason === 'string' && data.exitReason.trim() ? data.exitReason.trim() : null,
+        memoryExhausted: typeof data.memoryExhausted === 'boolean' ? data.memoryExhausted : null,
+        memoryExhaustedReason: typeof data.memoryExhaustedReason === 'string' && data.memoryExhaustedReason.trim() ? data.memoryExhaustedReason.trim() : null,
       };
     })
     .filter(Boolean);