@link-assistant/hive-mind 2.16.0 → 2.17.0

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

@@ -0,0 +1,263 @@
+/**
+ * `$ --resume` / `$ --resume-all` wrappers (start-command >= 0.33.0).
+ *
+ * Issue #2189 reported that a killed working session was only ever *offered*
+ * for resume, and that when Hive Mind did resume one it had to start a fresh
+ * isolated run — the container the work had happened in, with its clone, its
+ * build cache and its half-finished branch, was thrown away. The missing
+ * capability was filed upstream as link-foundation/start#162 and delivered in
+ * `start-command@0.33.0`:
+ *
+ *   - `$ --resume <id> -- <command>` re-enters an existing execution. For a
+ *     stopped docker session it commits the container filesystem and runs the
+ *     new command in a container derived from that snapshot, so the workspace
+ *     survives. The execution UUID is preserved, so `--status`, `--list` and
+ *     `--upload-log` keep addressing one logical session across restarts.
+ *   - `$ --resume-all` re-attaches a completion watcher to every execution
+ *     still marked running and reconciles the ones that ended unsupervised. It
+ *     never restarts work silently.
+ *
+ * Both are additive: a Hive Mind talking to an older `$` gets a clean
+ * `unsupported` result and the caller falls back to its previous behaviour.
+ * Neither wrapper throws.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2189
+ * @see https://github.com/link-foundation/start/issues/162
+ */
+
+import { describeChildExit } from './child-exit.lib.mjs';
+import { findStartCommandBinary, getCommandStreamDollar, START_COMMAND_MISSING_ERROR } from './start-command-cli.lib.mjs';
+
+/** Strategies `$ --resume` can pick, mirroring upstream `ResumeMode`. */
+export const RESUME_MODES = Object.freeze({
+  DOCKER_START: 'docker-start',
+  DOCKER_SNAPSHOT: 'docker-snapshot',
+  RELAUNCH: 'relaunch',
+});
+
+/** Outcomes `$ --resume-all` reports per execution, mirroring `ResumeAllAction`. */
+export const RESUME_ALL_ACTIONS = Object.freeze({
+  REATTACHED: 'reattached',
+  RUNNING: 'running',
+  RECONCILED: 'reconciled',
+  UNKNOWN: 'unknown',
+});
+
+/**
+ * Does this `$` failure mean the verb does not exist yet?
+ *
+ * An older binary rejects the flag while parsing, long before it looks at the
+ * store. Distinguishing that from a real refusal ("session is still running")
+ * is what lets the caller degrade gracefully instead of reporting a bug.
+ *
+ * @param {string} message - stderr/message from the failed invocation
+ * @returns {boolean}
+ */
+export function isUnsupportedStartCommandVerb(message) {
+  const text = String(message || '').toLowerCase();
+  // 0.32.1 answers `$ --resume-all` with `Error: Unknown wrapper option:
+  // --resume-all` (verified against the pinned pre-0.33.0 binary), and other
+  // argument parsers word it differently; match the family, not one string.
+  return /unknown (\w+ )?(option|argument|flag)|unrecognized option|invalid option|no such option/.test(text);
+}
+
+/**
+ * Parse the `executionResume` block `$ --resume --output-format json` prints.
+ *
+ * Tolerates links notation too (`executionResume` followed by indented
+ * `key value` pairs), because an operator's `$` may default to it.
+ *
+ * @param {string} output - Raw stdout
+ * @returns {{uuid: string|null, mode: string|null, backend: string|null, sessionName: string|null, previousSessionName: string|null, snapshotImage: string|null, command: string|null, message: string|null}}
+ */
+export function parseExecutionResumeOutput(output) {
+  const empty = { uuid: null, mode: null, backend: null, sessionName: null, previousSessionName: null, snapshotImage: null, command: null, message: null };
+  const raw = (output || '').trim();
+  if (!raw) return empty;
+  const str = value => (typeof value === 'string' && value.trim() ? value.trim() : null);
+  try {
+    const parsed = JSON.parse(raw);
+    const data = Array.isArray(parsed) ? parsed[0] : parsed;
+    return {
+      uuid: str(data?.uuid),
+      mode: str(data?.mode),
+      backend: str(data?.backend),
+      sessionName: str(data?.sessionName),
+      previousSessionName: str(data?.previousSessionName),
+      snapshotImage: str(data?.snapshotImage),
+      command: str(data?.command),
+      message: str(data?.message),
+    };
+  } catch {
+    // Links notation — fall through.
+  }
+  // Links notation indents `key value`; `--output-format text` prints
+  // `Label:   value`. The optional colon covers both with one expression.
+  const readField = name => {
+    const match = raw.match(new RegExp(`^\\s*${name}\\s*:?\\s+"?([^"\\n]+)"?\\s*$`, 'mi'));
+    return str(match?.[1]);
+  };
+  return {
+    uuid: readField('uuid'),
+    mode: readField('mode') || readField('Resume Mode'),
+    backend: readField('backend'),
+    sessionName: readField('sessionName') || readField('Session Name'),
+    previousSessionName: readField('previousSessionName'),
+    snapshotImage: readField('snapshotImage'),
+    command: readField('command'),
+    message: readField('message'),
+  };
+}
+
+/**
+ * Parse the `executionResumeAll` block `$ --resume-all --output-format json`
+ * prints. Anything unparseable yields an empty list rather than a throw — a
+ * startup reconciliation must never be able to stop the bot from starting.
+ *
+ * @param {string} output - Raw stdout
+ * @returns {Array<{uuid: string|null, backend: string|null, sessionName: string|null, state: string|null, action: string|null, exitCode: number|null, message: string|null}>}
+ */
+export function parseExecutionResumeAllOutput(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 : [];
+  const str = value => (typeof value === 'string' && value.trim() ? value.trim() : null);
+  return records
+    .map(entry => {
+      if (!entry || typeof entry !== 'object') return null;
+      const exitCode = entry.exitCode === null || entry.exitCode === undefined ? null : Number(entry.exitCode);
+      return {
+        uuid: str(entry.uuid),
+        backend: str(entry.backend),
+        sessionName: str(entry.sessionName),
+        state: str(entry.state),
+        action: str(entry.action),
+        exitCode: Number.isFinite(exitCode) ? exitCode : null,
+        message: str(entry.message),
+      };
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Normalize what `command-stream`'s `$` hands back for one invocation.
+ *
+ * `$` does *not* throw on a non-zero exit — it resolves with `code` set (checked
+ * against command-stream in experiments/issue-2189-start-command-resume.mjs).
+ * Reading only the resolved value would therefore report every refusal
+ * ("session is still running", "no execution found", "unknown wrapper option")
+ * as a successful resume. Both shapes are folded into one verdict here.
+ *
+ * @param {object|null} result - Resolved value from `$`
+ * @param {*} [error] - Rejection from `$`, when it threw instead
+ * @returns {{ok: boolean, stdout: string, message: string|null, unsupported: boolean}}
+ */
+function interpretStartCommandResult(result, error = null) {
+  const source = error || result || {};
+  const stdout = source.stdout?.toString?.().trim() || '';
+  const stderr = source.stderr?.toString?.().trim() || '';
+  const code = error ? (Number.isFinite(source.code) ? source.code : 1) : Number.isFinite(source.code) ? source.code : 0;
+  if (!error && code === 0) return { ok: true, stdout, message: null, unsupported: false };
+  // describeChildExit is the repository's single vocabulary for "how a child
+  // ended" (issue #2135); command-stream has already normalized a signalled
+  // exit to 128+signum by this point, so the code is all there is to say.
+  const message = stderr || source.message || describeChildExit({ command: 'start-command', code });
+  return { ok: false, stdout, message, unsupported: isUnsupportedStartCommandVerb(`${message}\n${stdout}`) };
+}
+
+/**
+ * Re-enter an existing execution via `$ --resume <identifier> [-- <command>]`.
+ *
+ * With a `command`, a stopped docker session is snapshotted and the command runs
+ * against that snapshot, so the work already on disk is preserved — this is the
+ * "re-enter the same container" half of issue #2189. Without one, the stored
+ * command is re-run in place.
+ *
+ * The command is passed as a single argument after `--`, exactly like the launch
+ * path does: start-command 0.33.0 preserves argv boundaries and runs a lone
+ * argument verbatim as a shell script, so no quoting is lost.
+ *
+ * @param {string} identifier - Execution UUID or session name
+ * @param {Object} [options]
+ * @param {string|null} [options.command] - Command to run against the resumed session
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<{success: boolean, unsupported: boolean, uuid: string|null, mode: string|null, backend: string|null, sessionName: string|null, previousSessionName: string|null, snapshotImage: string|null, message: string|null, output: string, error: string|null}>}
+ */
+export async function resumeIsolatedSession(identifier, { command = null, verbose = false } = {}) {
+  const base = { success: false, unsupported: false, uuid: null, mode: null, backend: null, sessionName: null, previousSessionName: null, snapshotImage: null, message: null, output: '', error: null };
+  if (!identifier) return { ...base, error: 'No execution identifier was given to resume.' };
+
+  const binPath = await findStartCommandBinary();
+  if (!binPath) {
+    if (verbose) console.log('[VERBOSE] isolation-runner: cannot resume - $ binary not found');
+    return { ...base, unsupported: true, error: START_COMMAND_MISSING_ERROR };
+  }
+
+  try {
+    const $ = await getCommandStreamDollar();
+    const raw = command ? await $({ mirror: false })`${binPath} --resume ${identifier} --output-format json -- ${command}` : await $({ mirror: false })`${binPath} --resume ${identifier} --output-format json`;
+    const { ok, stdout, message, unsupported } = interpretStartCommandResult(raw);
+    if (!ok) {
+      if (verbose) console.log(`[VERBOSE] isolation-runner: $ --resume ${identifier} refused${unsupported ? ' (verb not supported by this $ build)' : ''}: ${message}`);
+      return { ...base, unsupported, output: stdout, error: message };
+    }
+    const parsed = parseExecutionResumeOutput(stdout);
+    if (verbose) {
+      console.log(`[VERBOSE] isolation-runner: $ --resume ${identifier} → mode=${parsed.mode || '(unknown)'} session=${parsed.sessionName || '(unknown)'} uuid=${parsed.uuid || '(unknown)'}`);
+    }
+    return { ...base, ...parsed, success: true, output: stdout };
+  } catch (error) {
+    const { stdout, message, unsupported } = interpretStartCommandResult(null, error);
+    if (verbose) console.log(`[VERBOSE] isolation-runner: $ --resume ${identifier} failed${unsupported ? ' (verb not supported by this $ build)' : ''}: ${message}`);
+    return { ...base, unsupported, output: stdout, error: message };
+  }
+}
+
+/**
+ * Reconcile every execution still marked running via `$ --resume-all`.
+ *
+ * Run at bot startup: the detached-docker completion watchers are children of
+ * the process that launched them, so a bot restart leaves every running
+ * container unsupervised — its exit would never be written to the log footer,
+ * which is one of the ways issue #2189's session stayed in limbo. `--resume-all`
+ * re-attaches a watcher to what is alive and finalizes what died meanwhile. It
+ * starts no work on its own.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<{success: boolean, unsupported: boolean, executions: Array<Object>, output: string, error: string|null}>}
+ */
+export async function resumeAllIsolationSessions({ verbose = false } = {}) {
+  const base = { success: false, unsupported: false, executions: [], output: '', error: null };
+  const binPath = await findStartCommandBinary();
+  if (!binPath) {
+    if (verbose) console.log('[VERBOSE] isolation-runner: cannot run $ --resume-all - $ binary not found');
+    return { ...base, unsupported: true, error: START_COMMAND_MISSING_ERROR };
+  }
+
+  try {
+    const $ = await getCommandStreamDollar();
+    const raw = await $({ mirror: false })`${binPath} --resume-all --output-format json`;
+    const { ok, stdout, message, unsupported } = interpretStartCommandResult(raw);
+    if (!ok) {
+      if (verbose) console.log(`[VERBOSE] isolation-runner: $ --resume-all refused${unsupported ? ' (verb not supported by this $ build)' : ''}: ${message}`);
+      return { ...base, unsupported, output: stdout, error: message };
+    }
+    const executions = parseExecutionResumeAllOutput(stdout);
+    if (verbose) {
+      const summary = executions.map(entry => `${entry.action}:${entry.sessionName || entry.uuid}`).join(', ') || '(none)';
+      console.log(`[VERBOSE] isolation-runner: $ --resume-all reconciled ${executions.length} execution(s): ${summary}`);
+    }
+    return { ...base, success: true, executions, output: stdout };
+  } catch (error) {
+    const { stdout, message, unsupported } = interpretStartCommandResult(null, error);
+    if (verbose) console.log(`[VERBOSE] isolation-runner: $ --resume-all failed${unsupported ? ' (verb not supported by this $ build)' : ''}: ${message}`);
+    return { ...base, unsupported, output: stdout, error: message };
+  }
+}

package/src/pull-request-changes.lib.mjs

@@ -106,7 +106,7 @@ const measureDiff = diff => {
     section = null;
   };
 
-  for (let start = 0; start < diff.length; ) {
+  for (let start = 0; start < diff.length;) {
     let end = diff.indexOf('\n', start);
     if (end === -1) end = diff.length;
     const line = diff.slice(start, end);

package/src/session-kill-diagnostics.lib.mjs

@@ -54,6 +54,16 @@ export const KILL_DIAGNOSTICS_LOG_BYTES = 1024 * 1024;
  */
 export const HEAP_EXHAUSTED_PERCENT = 90;
 
+/**
+ * Prefix start-command 0.33.0 puts on every `exitReason` that reports memory
+ * exhaustion, whatever the mechanism — `memory-exhaustion (v8-heap-limit)`,
+ * `memory-exhaustion (kernel-oom-killer)`, `memory-exhaustion (go-runtime)`,
+ * `memory-exhaustion (allocation-failure)`. Matching the prefix rather than the
+ * exact strings means a new upstream mechanism is classified correctly without
+ * a Hive Mind release. See link-foundation/start#164 and #165.
+ */
+export const UPSTREAM_MEMORY_EXHAUSTION_PREFIX = 'memory-exhaustion';
+
 /** Disk is considered full at or above this used percentage… */
 export const DISK_FULL_USED_PERCENT = 95;
 /** …or below this much free space, whichever triggers first. */
@@ -268,9 +278,12 @@ function describeDisk(disk, timestamp) {
  * @param {number|null} [params.exitCode]
  * @param {Object|null} [params.system] - collectSystemKillDiagnostics() result
  * @param {boolean} [params.stopRequestedByUser] - The operator asked for the stop
+ * @param {boolean|null} [params.reportedMemoryExhausted] - `$ --status` `memoryExhausted` (start-command >= 0.33.0)
+ * @param {string|null} [params.reportedMemoryExhaustedReason] - `$ --status` `memoryExhaustedReason` (the evidence line)
+ * @param {string|null} [params.reportedExitReason] - `$ --status` `exitReason` hint, e.g. `memory-exhaustion (v8-heap-limit)`
  * @returns {{cause: string, summary: string, evidence: string[], memory: Object|null, disk: Object|null, victims: Array}}
  */
-export function describeKillCause({ logText = null, resourceMarkers = null, oomKilled = false, exitCode = null, system = null, stopRequestedByUser = false } = {}) {
+export function describeKillCause({ logText = null, resourceMarkers = null, oomKilled = false, exitCode = null, system = null, stopRequestedByUser = false, reportedMemoryExhausted = null, reportedMemoryExhaustedReason = null, reportedExitReason = null } = {}) {
   const parsed = resourceMarkers || (logText ? parseResourceMarkers(logText) : { markers: [], byPhase: {} });
   const memoryMarker = selectLastMemoryResourceMarker(parsed);
   const heapMarker = selectLastHeapResourceMarker(parsed);
@@ -310,6 +323,30 @@ export function describeKillCause({ logText = null, resourceMarkers = null, oomK
     evidence.push(`the ${fatalMemoryMarker.runtime} runtime aborted on its own heap limit: \`${fatalMemoryMarker.line}\` (a self-abort is invisible to \`docker inspect\` and to cgroup OOM counters)`);
   }
 
+  // Issue #2189 also went upstream: start-command 0.33.0 (link-foundation/start
+  // #164, #165) performs the same tail scan inside `$` and reports it as
+  // `memoryExhausted` / `memoryExhaustedReason` / `exitReason`. Consuming it
+  // catches the case our own scan cannot: the fatal line scrolled out of the
+  // bounded window we read, but `$` saw it when the command exited. The local
+  // scan stays as defense in depth — these fields are absent on an older `$`.
+  const reportedExitReasonText = typeof reportedExitReason === 'string' && reportedExitReason.trim() ? reportedExitReason.trim() : null;
+  const reportedMemoryExhaustion = abnormalExit && (reportedMemoryExhausted === true || (reportedExitReasonText !== null && reportedExitReasonText.startsWith(UPSTREAM_MEMORY_EXHAUSTION_PREFIX)));
+  // `memory-exhaustion (v8-heap-limit)` → `v8-heap-limit`: the prefix is already
+  // said in words by the surrounding sentence, so only the mechanism is new.
+  const reportedMechanism =
+    reportedMemoryExhaustion && reportedExitReasonText
+      ? reportedExitReasonText
+          .slice(UPSTREAM_MEMORY_EXHAUSTION_PREFIX.length)
+          .trim()
+          .replace(/^\((.*)\)$/, '$1') || null
+      : null;
+  if (reportedMemoryExhaustion) {
+    const detail = reportedMemoryExhaustedReason ? `: \`${reportedMemoryExhaustedReason}\`` : '';
+    evidence.push(`\`$ --status\` reports memory exhaustion${reportedMechanism ? ` (\`${reportedMechanism}\`)` : ''}${detail}`);
+  } else if (reportedExitReasonText && abnormalExit) {
+    evidence.push(`\`$ --status\` reports \`exitReason = ${reportedExitReasonText}\``);
+  }
+
   const ratio = memoryRatio(memory);
   const memoryExhausted = ratio !== null && ratio <= MEMORY_EXHAUSTED_AVAILABLE_RATIO;
   // A heap already at the limit is only evidence of a kill when the session
@@ -322,7 +359,7 @@ export function describeKillCause({ logText = null, resourceMarkers = null, oomK
   let cause = KILL_CAUSE_UNKNOWN;
   if (stopRequestedByUser) {
     cause = KILL_CAUSE_FORCED_KILL;
-  } else if (victims.length > 0 || (cgroupOomKills !== null && cgroupOomKills > 0) || oomKilled || memoryExhausted || fatalMemoryMarker || heapExhausted) {
+  } else if (victims.length > 0 || (cgroupOomKills !== null && cgroupOomKills > 0) || oomKilled || memoryExhausted || fatalMemoryMarker || heapExhausted || reportedMemoryExhaustion) {
     cause = KILL_CAUSE_OUT_OF_MEMORY;
   } else if (diskFull) {
     cause = KILL_CAUSE_DISK_FULL;
@@ -340,6 +377,11 @@ export function describeKillCause({ logText = null, resourceMarkers = null, oomK
     // Same shape as the fatal-marker case, but reconstructed from telemetry when
     // the fatal line itself was lost (truncated tail, killed before flushing).
     summary = `out of memory — the runtime's own heap was exhausted: ${heapLine}${memoryLine ? ` (host memory was fine: ${memoryLine})` : ''}`;
+  } else if (cause === KILL_CAUSE_OUT_OF_MEMORY && reportedMemoryExhaustion && victims.length === 0 && !oomKilled && !(cgroupOomKills > 0) && !memoryExhausted) {
+    // Only `$` saw the evidence (our bounded window missed the fatal line).
+    // Quote what it saw rather than falling back to the host-memory phrasing,
+    // which would again read as a contradiction on a healthy machine.
+    summary = `out of memory — start-command reported memory exhaustion${reportedMechanism ? ` (${reportedMechanism})` : ''}${reportedMemoryExhaustedReason ? `: \`${reportedMemoryExhaustedReason}\`` : ''}${memoryLine ? ` (host memory was fine: ${memoryLine})` : ''}`;
   } else if (cause === KILL_CAUSE_OUT_OF_MEMORY) {
     const victim = victims.length > 0 ? `, kernel OOM killer terminated \`${victims[victims.length - 1].comm || 'unknown'}\` (pid ${victims[victims.length - 1].pid ?? '?'})` : '';
     summary = `out of memory${memoryLine ? ` — ${memoryLine}` : ''}${victim}`;
@@ -352,7 +394,7 @@ export function describeKillCause({ logText = null, resourceMarkers = null, oomK
     summary = 'unknown — no resource marker, cgroup counter or kernel OOM report was available';
   }
 
-  return { cause, summary, evidence, memory, heap: heapMemory, heapUsedPercent, disk, victims, fatalMemoryMarker };
+  return { cause, summary, evidence, memory, heap: heapMemory, heapUsedPercent, disk, victims, fatalMemoryMarker, reportedMemoryExhaustion, reportedExitReason: reportedExitReasonText };
 }
 
 /**
@@ -429,7 +471,7 @@ export function formatKillResumeSection({ sessionId = null, attempt = null, maxA
  * @param {Object} [options]
  * @returns {Promise<{section: string, diagnosis: Object|null}>}
  */
-export async function buildKillDiagnosticsSection(logPath, { verbose = false, readFile = fsPromises.readFile, maxLogBytes = KILL_DIAGNOSTICS_LOG_BYTES, oomKilled = false, exitCode = null, stopRequestedByUser = false, locale = null, collectSystem = collectSystemKillDiagnostics } = {}) {
+export async function buildKillDiagnosticsSection(logPath, { verbose = false, readFile = fsPromises.readFile, maxLogBytes = KILL_DIAGNOSTICS_LOG_BYTES, oomKilled = false, exitCode = null, stopRequestedByUser = false, locale = null, collectSystem = collectSystemKillDiagnostics, reportedMemoryExhausted = null, reportedMemoryExhaustedReason = null, reportedExitReason = null } = {}) {
   try {
     let logText = '';
     if (logPath) {
@@ -441,7 +483,7 @@ export async function buildKillDiagnosticsSection(logPath, { verbose = false, re
       logText = await readLogTextBounded(logPath, { readFile, maxBytes: maxLogBytes, verbose });
     }
     const system = await collectSystem({ verbose });
-    const diagnosis = describeKillCause({ logText, oomKilled, exitCode, system, stopRequestedByUser });
+    const diagnosis = describeKillCause({ logText, oomKilled, exitCode, system, stopRequestedByUser, reportedMemoryExhausted, reportedMemoryExhaustedReason, reportedExitReason });
     if (verbose) console.log(`[VERBOSE] kill-diagnostics: cause=${diagnosis.cause} — ${diagnosis.summary}`);
     return { section: formatKillDiagnosticsSection(diagnosis, { locale }), diagnosis };
   } catch (error) {

package/src/session-kill-resume.in-place.lib.mjs

@@ -0,0 +1,136 @@
+/**
+ * Re-enter the *same* container when recovering a killed session (issue #2189).
+ *
+ * The incident behind #2189 ended with a session that was killed 10 minutes
+ * after the AI tool had already finished its work. Recovery, when it finally
+ * happened, threw that container away: a fresh isolated run re-cloned the
+ * repository, re-installed everything and re-did work that was sitting on disk.
+ * The issue asks for the opposite — "ideally re-entering the same `$` session
+ * id / container".
+ *
+ * `start-command@0.33.0` (upstream link-foundation/start#162, filed from this
+ * very issue) makes that possible: `$ --resume <id> -- <command>` commits the
+ * stopped container's filesystem and runs the recovery command in a container
+ * derived from that snapshot, keeping the original execution UUID and log.
+ *
+ * Not every session may take that path, and the two exceptions are deliberate:
+ *
+ * - **Formal AI tasks** (issue #2146) reach their sidecar over an *internal*
+ *   Docker network that Hive Mind attaches with `docker network connect` after
+ *   the container is created. `$` knows nothing about that network, so a
+ *   resumed container would come up without it and the task would silently talk
+ *   to nothing. #2146 requires Formal AI to fail closed, so these fall back to
+ *   the normal launch path, which re-acquires the sidecar lease properly.
+ * - **`--use-router` tasks** are attached to the router network the same way,
+ *   with a freshly minted token, and have the same problem.
+ *
+ * Everything else — the overwhelming majority, and every session in the
+ * original incident — resumes in place.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2189
+ * @see https://github.com/link-foundation/start/issues/162
+ * @see https://github.com/link-assistant/hive-mind/issues/2146
+ */
+
+import { isFormalAiTask } from './formal-ai-sidecar.lib.mjs';
+import { hasUseRouterFlag } from './router-isolation.lib.mjs';
+import { RESUME_MODES } from './isolation-runner.resume.lib.mjs';
+
+/** Why a killed session cannot be re-entered in place. Reported, never thrown. */
+export const IN_PLACE_SKIP_REASONS = Object.freeze({
+  NOT_DOCKER: 'not-docker',
+  NO_IDENTIFIER: 'no-identifier',
+  FORMAL_AI_TASK: 'formal-ai-task',
+  ROUTER_TASK: 'router-task',
+  NO_RESUME_SUPPORT: 'no-resume-support',
+  CONTAINER_GONE: 'container-gone',
+  UNSUPPORTED: 'resume-unsupported',
+  REFUSED: 'resume-refused',
+  ERROR: 'resume-error',
+});
+
+/**
+ * Decide — purely, from persisted facts — whether a killed session is a
+ * candidate for a same-container resume.
+ *
+ * Kept separate from the Docker probe below so the policy is testable without a
+ * daemon, and so a caller can report precisely *why* a session was relaunched
+ * from scratch instead of resumed.
+ *
+ * @param {Object} options
+ * @param {string} options.sessionName - The killed session's name (= container name)
+ * @param {Object} options.sessionInfo - Persisted session info
+ * @returns {{eligible: boolean, reason: string, identifier: string|null, containerName: string|null}}
+ */
+export function planSameContainerResume({ sessionName = null, sessionInfo = {} } = {}) {
+  const containerName = sessionInfo?.sessionId || sessionName || null;
+  const identifier = sessionInfo?.executionUuid || containerName || null;
+  const base = { eligible: false, identifier, containerName };
+
+  if (sessionInfo?.isolationBackend !== 'docker') {
+    // screen/tmux sessions have no filesystem to preserve: their work happens
+    // on the host, which a fresh run already sees.
+    return { ...base, reason: IN_PLACE_SKIP_REASONS.NOT_DOCKER };
+  }
+  if (!identifier) return { ...base, reason: IN_PLACE_SKIP_REASONS.NO_IDENTIFIER };
+
+  const args = Array.isArray(sessionInfo?.args) ? sessionInfo.args : [];
+  if (isFormalAiTask({ args, model: sessionInfo?.model || null })) {
+    return { ...base, reason: IN_PLACE_SKIP_REASONS.FORMAL_AI_TASK };
+  }
+  if (hasUseRouterFlag(args)) return { ...base, reason: IN_PLACE_SKIP_REASONS.ROUTER_TASK };
+
+  return { ...base, eligible: true, reason: 'ready' };
+}
+
+/**
+ * Attempt the same-container resume. Never throws, and never leaves work
+ * running that it does not report: the caller may only fall back to a fresh
+ * launch when `resumed` is false.
+ *
+ * @param {Object} options
+ * @param {string} options.sessionName - The killed session's name
+ * @param {Object} options.sessionInfo - Persisted session info
+ * @param {Object} options.plan - Result of planKillRecovery() (needs `command.display`)
+ * @param {Object} options.runner - Isolation runner module
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<{resumed: boolean, reason: string, sessionId: string|null, executionUuid: string|null, mode: string|null, snapshotImage: string|null}>}
+ */
+export async function resumeKilledSessionInPlace({ sessionName, sessionInfo, plan, runner, verbose = false } = {}) {
+  const decision = planSameContainerResume({ sessionName, sessionInfo });
+  const miss = reason => ({ resumed: false, reason, sessionId: null, executionUuid: decision.identifier, mode: null, snapshotImage: null });
+  if (!decision.eligible) return miss(decision.reason);
+  if (typeof runner?.resumeIsolatedSession !== 'function' || typeof runner?.checkDockerContainerExists !== 'function') {
+    return miss(IN_PLACE_SKIP_REASONS.NO_RESUME_SUPPORT);
+  }
+
+  // A container that no longer exists has nothing left to re-enter; `$` would
+  // fall back to a full relaunch, which is what the caller does anyway — but
+  // through the path that also re-acquires leases.
+  const exists = await runner.checkDockerContainerExists(decision.containerName, verbose);
+  if (!exists) return miss(IN_PLACE_SKIP_REASONS.CONTAINER_GONE);
+
+  const result = await runner.resumeIsolatedSession(decision.identifier, { command: plan?.command?.display || null, verbose });
+  if (!result?.success) {
+    const reason = result?.unsupported ? IN_PLACE_SKIP_REASONS.UNSUPPORTED : IN_PLACE_SKIP_REASONS.REFUSED;
+    if (verbose) console.log(`[VERBOSE] In-place resume of ${sessionName} was not possible (${reason}): ${result?.error || 'no reason given'}`);
+    return miss(reason);
+  }
+
+  // `docker-snapshot` names the new container `<session>-resume-<attempt>`; the
+  // old name stays addressable through upstream's `sessionNameHistory`, but the
+  // *new* one is what `$ --status` reports on now, so that is what the monitor
+  // has to track. A resume that somehow reports the old name (a `docker-start`
+  // race, say) is tracked under the execution UUID instead, which upstream
+  // resolves just as well and cannot collide with the dying session's entry.
+  const returnedName = result.sessionName && result.sessionName !== sessionName ? result.sessionName : null;
+  const sessionId = returnedName || decision.identifier;
+  return {
+    resumed: true,
+    reason: result.mode === RESUME_MODES.DOCKER_SNAPSHOT ? 'resumed-in-place' : `resumed-${result.mode || 'unknown'}`,
+    sessionId,
+    executionUuid: result.uuid || decision.identifier,
+    mode: result.mode || null,
+    snapshotImage: result.snapshotImage || null,
+  };
+}

package/src/session-kill-resume.lib.mjs

@@ -24,6 +24,7 @@ import { readLastSessionIdFromLog, planKilledSessionResume } from './session-res
 import { resolveOnSessionKillPolicy, resolveSessionKillResumeAttempts, shouldResumeKilledSession, ON_SESSION_KILL_RESUME } from './session-kill-policy.lib.mjs';
 import { argvFromSessionArgs } from './session-monitor.kill-sections.lib.mjs';
 import { formatKillResumeSection } from './session-kill-diagnostics.lib.mjs';
+import { resumeKilledSessionInPlace } from './session-kill-resume.in-place.lib.mjs';
 
 /** Field recording how many automatic recovery sessions this session produced. */
 export const KILL_RESUME_ATTEMPTS_FIELD = 'killRecoveryAttempts';
@@ -65,9 +66,18 @@ export function planKillRecovery({ sessionInfo = {}, logPath = null, killed = fa
 /**
  * Start the recovery working session decided by {@link planKillRecovery}.
  *
- * The new session is launched through the same isolation runner the original
- * used and is tracked like any other session, so it reports its own completion
- * (and, if it is killed too, its own diagnosis) through the normal path.
+ * Two ways in, in order of preference:
+ *
+ *   1. **Same container** (issue #2189) — `$ --resume` re-enters the killed
+ *      session's own filesystem, so the clone, the caches and the half-finished
+ *      branch survive. See `./session-kill-resume.in-place.lib.mjs` for the
+ *      cases that are deliberately excluded.
+ *   2. **A fresh isolated run** — the original behaviour, used whenever (1) is
+ *      not available or refuses. Correct, just more expensive.
+ *
+ * Either way the new session is tracked like any other, so it reports its own
+ * completion (and, if it is killed too, its own diagnosis) through the normal
+ * path.
  *
  * @param {Object} options
  * @param {string} options.sessionName - The killed session's name
@@ -77,10 +87,10 @@ export function planKillRecovery({ sessionInfo = {}, logPath = null, killed = fa
  * @param {Function} options.trackSession - Tracker for the new session
  * @param {Function} [options.persistSnapshot] - Persist the attempt counter
  * @param {boolean} [options.verbose]
- * @returns {Promise<{resumed: boolean, reason: string, sessionId: string|null, display: string|null}>}
+ * @returns {Promise<{resumed: boolean, reason: string, sessionId: string|null, display: string|null, inPlace: boolean}>}
  */
 export async function startKillRecoverySession({ sessionName, sessionInfo, plan, runner, trackSession, persistSnapshot = null, verbose = false } = {}) {
-  const fail = reason => ({ resumed: false, reason, sessionId: null, display: plan?.command?.display || null });
+  const fail = reason => ({ resumed: false, reason, sessionId: null, display: plan?.command?.display || null, inPlace: false });
   if (!plan?.shouldResume || !plan.command) return fail(plan?.reason || 'no-plan');
   if (!runner || typeof runner.executeWithIsolation !== 'function' || typeof runner.generateSessionId !== 'function') return fail('no-isolation-runner');
   if (typeof trackSession !== 'function') return fail('no-tracker');
@@ -88,10 +98,20 @@ export async function startKillRecoverySession({ sessionName, sessionInfo, plan,
   if (!backend) return fail('no-isolation-backend');
 
   try {
-    const newSessionId = runner.generateSessionId();
-    const tool = sessionInfo?.tool || 'claude';
-    const result = await runner.executeWithIsolation(sessionInfo?.command || 'solve', plan.command.args, { backend, sessionId: newSessionId, tool, verbose });
-    if (!result?.success) return fail('start-failed');
+    // Preferred path: re-enter the container the work already happened in.
+    const inPlace = await resumeKilledSessionInPlace({ sessionName, sessionInfo, plan, runner, verbose });
+    let newSessionId = inPlace.sessionId;
+    let executionUuid = inPlace.executionUuid;
+    let containerFilesystemStartBytes = null;
+
+    if (!inPlace.resumed) {
+      newSessionId = runner.generateSessionId();
+      const tool = sessionInfo?.tool || 'claude';
+      const result = await runner.executeWithIsolation(sessionInfo?.command || 'solve', plan.command.args, { backend, sessionId: newSessionId, tool, verbose });
+      if (!result?.success) return fail('start-failed');
+      executionUuid = result.executionUuid || null;
+      containerFilesystemStartBytes = Number.isFinite(result.containerFilesystemStartBytes) ? result.containerFilesystemStartBytes : null;
+    }
 
     trackSession(
       newSessionId,
@@ -105,9 +125,15 @@ export async function startKillRecoverySession({ sessionName, sessionInfo, plan,
         [KILL_RESUME_ATTEMPTS_FIELD]: plan.attempt,
         killRecoveryResumed: true,
         killRecoveryOfSession: sessionName,
+        // A resumed execution keeps its UUID; a fresh launch gets a new one, and
+        // inheriting the dead session's would make `$ --status` answer about the
+        // wrong execution until the monitor happened to correct it.
+        executionUuid,
+        killRecoveryInPlace: inPlace.resumed,
+        killRecoveryResumeMode: inPlace.mode || null,
         oomEventObservedAt: undefined,
         dockerBackendGoneFirstSeenAt: undefined,
-        containerFilesystemStartBytes: Number.isFinite(result.containerFilesystemStartBytes) ? result.containerFilesystemStartBytes : null,
+        containerFilesystemStartBytes,
       },
       verbose
     );
@@ -122,9 +148,10 @@ export async function startKillRecoverySession({ sessionName, sessionInfo, plan,
     }
 
     if (verbose) {
-      console.log(`[VERBOSE] Session ${sessionName} was killed; started recovery session ${newSessionId} (attempt ${plan.attempt}/${plan.maxAttempts}): ${plan.command.display}`);
+      const how = inPlace.resumed ? `resumed in place (${inPlace.mode || 'unknown mode'})` : `started fresh (in-place resume skipped: ${inPlace.reason})`;
+      console.log(`[VERBOSE] Session ${sessionName} was killed; recovery session ${newSessionId} ${how} (attempt ${plan.attempt}/${plan.maxAttempts}): ${plan.command.display}`);
     }
-    return { resumed: true, reason: 'started', sessionId: newSessionId, display: plan.command.display };
+    return { resumed: true, reason: inPlace.resumed ? inPlace.reason : 'started', sessionId: newSessionId, display: plan.command.display, inPlace: inPlace.resumed };
   } catch (error) {
     if (verbose) {
       console.log(`[VERBOSE] Could not start recovery session for ${sessionName}: ${error?.message || error}`);
@@ -138,7 +165,7 @@ export async function startKillRecoverySession({ sessionName, sessionInfo, plan,
  * Never throws — a failed recovery must still leave a correct kill report.
  *
  * @param {Object} options - See planKillRecovery() and startKillRecoverySession()
- * @returns {Promise<{resumed: boolean, reason: string, policy: string, sessionId: string|null, display: string|null, attempt: number, maxAttempts: number}>}
+ * @returns {Promise<{resumed: boolean, reason: string, policy: string, sessionId: string|null, display: string|null, attempt: number, maxAttempts: number, inPlace: boolean}>}
  */
 export async function recoverKilledSession({ sessionName, sessionInfo, logPath = null, killed = false, env = process.env, runner = null, trackSession = null, persistSnapshot = null, verbose = false, readLastSessionId = readLastSessionIdFromLog } = {}) {
   let plan;
@@ -146,15 +173,15 @@ export async function recoverKilledSession({ sessionName, sessionInfo, logPath =
     plan = planKillRecovery({ sessionInfo, logPath, killed, env, verbose, readLastSessionId });
   } catch (error) {
     if (verbose) console.log(`[VERBOSE] Could not plan kill recovery for ${sessionName}: ${error?.message || error}`);
-    return { resumed: false, reason: 'plan-error', policy: ON_SESSION_KILL_RESUME, sessionId: null, display: null, attempt: 0, maxAttempts: 0 };
+    return { resumed: false, reason: 'plan-error', policy: ON_SESSION_KILL_RESUME, sessionId: null, display: null, attempt: 0, maxAttempts: 0, inPlace: false };
   }
 
   if (!plan.shouldResume) {
-    return { resumed: false, reason: plan.reason, policy: plan.policy, sessionId: null, display: plan.command?.display || null, attempt: plan.attempt, maxAttempts: plan.maxAttempts };
+    return { resumed: false, reason: plan.reason, policy: plan.policy, sessionId: null, display: plan.command?.display || null, attempt: plan.attempt, maxAttempts: plan.maxAttempts, inPlace: false };
   }
 
   const started = await startKillRecoverySession({ sessionName, sessionInfo, plan, runner, trackSession, persistSnapshot, verbose });
-  return { resumed: started.resumed, reason: started.reason, policy: plan.policy, sessionId: started.sessionId, display: started.display, attempt: plan.attempt, maxAttempts: plan.maxAttempts };
+  return { resumed: started.resumed, reason: started.reason, policy: plan.policy, sessionId: started.sessionId, display: started.display, attempt: plan.attempt, maxAttempts: plan.maxAttempts, inPlace: started.inPlace === true };
 }
 
 /**