@link-assistant/hive-mind 2.16.0 → 2.18.0

package/src/agent.lib.mjs

@@ -349,32 +349,14 @@ export const mapModelToId = model => {
   return agentModels[model] || model;
 };
 
-export const MIN_AGENT_LIVE_INPUT_VERSION = '0.24.1';
+// The Agent CLI version floors live in their own module (issue #2198: this
+// file crossed the 1350-line warning threshold). `validateAgentConnection`
+// below reads them directly, and they are re-exported so importers of
+// `agent.lib.mjs` -- tests/test-codex-support.mjs and
+// tests/test-issue-2186-agent-snapshot-leak.mjs among them -- do not move.
+import { MIN_AGENT_LIVE_INPUT_VERSION, MIN_AGENT_FORMAL_AI_VERSION, MIN_AGENT_SNAPSHOT_HYGIENE_VERSION, getAgentCliVersion } from './agent.version-gates.lib.mjs';
 
-export const getAgentCliVersion = versionOutput => {
-  return semver.clean(versionOutput) || semver.coerce(versionOutput)?.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);
-};
+export { MIN_AGENT_LIVE_INPUT_VERSION, MIN_AGENT_FORMAL_AI_VERSION, MIN_AGENT_SNAPSHOT_HYGIENE_VERSION, getAgentCliVersion, agentCliSupportsLiveInput, agentCliFailsClosedOnModelMismatch, agentCliPrunesOrphanSnapshots } from './agent.version-gates.lib.mjs';
 
 // Function to validate Agent connection
 export const validateAgentConnection = async (model = defaultModels.agent, options = {}) => {
@@ -411,6 +393,24 @@ export const validateAgentConnection = async (model = defaultModels.agent, optio
         }
       }
 
+      if (!agentVersion || !semver.gte(agentVersion, MIN_AGENT_SNAPSHOT_HYGIENE_VERSION)) {
+        await log(`❌ Hive Mind requires @link-assistant/agent >= ${MIN_AGENT_SNAPSHOT_HYGIENE_VERSION}`, { level: 'error' });
+        await log('   Older releases write a full, standalone copy of the repository into', { level: 'error' });
+        await log('   ~/.local/share/link-assistant-agent/snapshot/ per project and never reclaim it', { level: 'error' });
+        await log('   (link-assistant/agent#298): issue #2186 lost 31 GB to 115 orphaned stores in one task.', { level: 'error' });
+        if (agentVersion) {
+          await log(`   Installed Agent CLI version: ${agentVersion}`, { level: 'error' });
+        } else {
+          await log('   Could not determine the installed Agent CLI version.', { level: 'error' });
+        }
+        await log('   Update with: bun install -g @link-assistant/agent@latest', { level: 'error' });
+        return false;
+      }
+
+      // The two capability gates below are subsumed by the floor above while it
+      // stays the highest of the three. They are kept because each states an
+      // independent contract with its own diagnosis, and any one of the floors
+      // can move on its own.
       if (requireLiveInput && (!agentVersion || !semver.gte(agentVersion, MIN_AGENT_LIVE_INPUT_VERSION))) {
         await log(`❌ Agent live stream-json input requires @link-assistant/agent >= ${MIN_AGENT_LIVE_INPUT_VERSION}`, { level: 'error' });
         if (agentVersion) {

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/github-url-parser.lib.mjs

@@ -1,8 +1,37 @@
 import { reportError } from './sentry.lib.mjs';
+import { describeHiddenCharacters, repairGitHubPathParts, repairGitHubUrlText, revealHiddenCharacters, traceUrlRecovery } from './github-url-recovery.lib.mjs';
+
+/**
+ * Attach the issue #2194 recovery diagnostics to a parse result.
+ *
+ * `original` is always present so a caller can show the user what they actually
+ * sent; `hidden`/`revealed` only appear when there was something invisible to
+ * reveal, keeping the common result small.
+ *
+ * @param {Object} result - The result object to annotate (mutated and returned).
+ * @param {string} original - The URL exactly as it was passed in.
+ * @param {Array<{code: string, message: string, notable: boolean}>} repairs
+ * @param {Array<{escape: string, name: string}>} hidden
+ * @returns {Object} The same result object.
+ */
+function withRecoveryDiagnostics(result, original, repairs, hidden) {
+  result.original = original;
+  result.repairs = repairs;
+  result.recovered = repairs.length > 0;
+  if (hidden.length > 0) {
+    result.hidden = hidden;
+    result.revealed = revealHiddenCharacters(original);
+  }
+  return result;
+}
 
 /**
  * Universal GitHub URL parser that handles various formats
  * @param {string} url - The GitHub URL to parse
+ * @param {Object} [options] - Parsing options
+ * @param {boolean} [options.recover=true] - Repair recoverable damage (invisible
+ *   Unicode, wrappers, look-alike punctuation, `/pulls/30` for `/pull/30`, …)
+ *   before parsing. Pass `false` to see the URL exactly as it was typed.
  * @returns {Object} Parsed URL information including:
  *   - valid: boolean indicating if the URL is valid
  *   - normalized: the normalized URL (https://github.com/...), query/fragment kept
@@ -13,22 +42,41 @@ import { reportError } from './sentry.lib.mjs';
  *   - number: issue/PR number (if applicable)
  *   - path: additional path components
  *   - error: error message if invalid
+ *   - original: the URL exactly as it was passed in
+ *   - repairs: the list of repairs recovery had to apply (issue #2194)
+ *   - recovered: true when at least one repair was applied
+ *   - hidden/revealed: codepoint diagnostics, present only when the input carried
+ *     invisible or look-alike characters
  */
-export function parseGitHubUrl(url) {
+export function parseGitHubUrl(url, options = {}) {
   if (!url || typeof url !== 'string') {
     return {
       valid: false,
       error: 'Invalid input: URL must be a non-empty string',
     };
   }
+  const { recover = true } = options;
+  // Issue #2194: a URL that renders correctly on screen can still be broken —
+  // `…/pulls/30` previews as a healthy page, a zero-width space is unprintable by
+  // definition. Repair what can be repaired first, and keep a record of it, so the
+  // user is told what was interpreted instead of being told "invalid URL".
+  const hidden = describeHiddenCharacters(url);
+  let repairs = [];
   // Trim whitespace and remove trailing slashes
   let normalizedUrl = url.trim().replace(/\/+$/, '');
+  if (recover) {
+    const repaired = repairGitHubUrlText(normalizedUrl);
+    repairs = repaired.repairs;
+    if (repaired.rejection) {
+      traceUrlRecovery('rejected', { original: url, error: repaired.rejection, repairs, hidden });
+      return withRecoveryDiagnostics({ valid: false, error: repaired.rejection }, url, repairs, hidden);
+    }
+    normalizedUrl = repaired.text.replace(/\/+$/, '');
+    if (repairs.length > 0) traceUrlRecovery('repaired-text', { original: url, repaired: normalizedUrl, repairs, hidden });
+  }
   // Check if this looks like a valid GitHub-related input Reject clearly invalid inputs (spaces in the URL, special chars at the start, etc.)
   if (/\s/.test(normalizedUrl) || /^[!@#$%^&*()[\]{}|\\:;"'<>,?`~]/.test(normalizedUrl)) {
-    return {
-      valid: false,
-      error: 'Invalid GitHub URL format',
-    };
+    return withRecoveryDiagnostics({ valid: false, error: 'Invalid GitHub URL format' }, url, repairs, hidden);
   }
   // Handle protocol normalization
   if (!normalizedUrl.startsWith('http://') && !normalizedUrl.startsWith('https://')) {
@@ -40,10 +88,7 @@ export function parseGitHubUrl(url) {
       normalizedUrl = 'https://github.com/' + normalizedUrl;
     } else {
       // Has github.com somewhere but not at the start - likely malformed
-      return {
-        valid: false,
-        error: 'Invalid GitHub URL format',
-      };
+      return withRecoveryDiagnostics({ valid: false, error: 'Invalid GitHub URL format' }, url, repairs, hidden);
     }
   }
   // Convert http to https
@@ -56,11 +101,16 @@ export function parseGitHubUrl(url) {
     // Generate suggested URL by replacing backslashes with forward slashes
     const suggestedUrl = urlBeforeQueryAndHash.replace(/\\/g, '/');
     const urlAfterPath = normalizedUrl.substring(urlBeforeQueryAndHash.length);
-    return {
-      valid: false,
-      error: 'Invalid character in URL: backslash (\\) is not allowed in URL paths',
-      suggestion: suggestedUrl + urlAfterPath,
-    };
+    return withRecoveryDiagnostics(
+      {
+        valid: false,
+        error: 'Invalid character in URL: backslash (\\) is not allowed in URL paths',
+        suggestion: suggestedUrl + urlAfterPath,
+      },
+      url,
+      repairs,
+      hidden
+    );
   }
   // Parse the URL
   let urlObj;
@@ -74,17 +124,11 @@ export function parseGitHubUrl(url) {
         url: normalizedUrl,
       });
     }
-    return {
-      valid: false,
-      error: 'Invalid URL format',
-    };
+    return withRecoveryDiagnostics({ valid: false, error: 'Invalid URL format' }, url, repairs, hidden);
   }
   // Ensure it's a GitHub URL
   if (urlObj.hostname !== 'github.com' && urlObj.hostname !== 'www.github.com') {
-    return {
-      valid: false,
-      error: 'Not a GitHub URL',
-    };
+    return withRecoveryDiagnostics({ valid: false, error: 'Not a GitHub URL' }, url, repairs, hidden);
   }
   // Normalize hostname
   if (urlObj.hostname === 'www.github.com') {
@@ -92,7 +136,19 @@ export function parseGitHubUrl(url) {
     urlObj = new globalThis.URL(normalizedUrl);
   }
   // Parse the pathname
-  const pathParts = urlObj.pathname.split('/').filter(p => p);
+  let pathParts = urlObj.pathname.split('/').filter(p => p);
+  // Issue #2194: `/owner/repo/pulls/30` carries every byte needed to address pull
+  // request 30 — restore it rather than reporting the pull request list page.
+  if (recover) {
+    const pathRepair = repairGitHubPathParts(pathParts);
+    if (pathRepair.repairs.length > 0) {
+      repairs = repairs.concat(pathRepair.repairs);
+      pathParts = pathRepair.parts;
+      urlObj.pathname = `/${pathParts.join('/')}`;
+      normalizedUrl = urlObj.toString().replace(/\/+$/, '');
+      traceUrlRecovery('repaired-path', { original: url, repaired: normalizedUrl, repairs, hidden });
+    }
+  }
   // Handle different GitHub URL patterns
   const result = {
     valid: true,
@@ -108,6 +164,7 @@ export function parseGitHubUrl(url) {
     protocol: 'https',
     path: urlObj.pathname,
   };
+  withRecoveryDiagnostics(result, url, repairs, hidden);
   // No path - just github.com
   if (pathParts.length === 0) {
     result.type = 'home';