akm-cli 0.9.0-beta.6 → 0.9.0-beta.9

package/dist/indexer/ensure-index.js

@@ -11,12 +11,14 @@
  * `searchLocal()` and `show.ts`, centralizing the "indexed yet?" gap handling
  * behind a single entry point.
  */
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { ASSET_SPECS, TYPE_DIRS } from "../core/asset/asset-spec.js";
-import { getDbPath } from "../core/paths.js";
+import { getDataDir, getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
-import { closeDatabase, getEntryCount, getMeta, openExistingDatabase } from "./db/db.js";
+import { closeDatabase, getEntryCount, getIndexedFilePaths, getMeta, openExistingDatabase } from "./db/db.js";
+import { acquireIndexWriterLease, handoffIndexWriterLeaseToPid } from "./index-writer-lock.js";
 function getIndexableFiles(root, spec) {
     if (!fs.existsSync(root))
         return [];
@@ -52,16 +54,34 @@ function getIndexableFiles(root, spec) {
     }
     return files;
 }
-function hasNewerIndexableFiles(stashDir, builtAt) {
-    if (!builtAt)
-        return true;
-    const builtAtMs = new Date(builtAt).getTime();
-    if (!Number.isFinite(builtAtMs))
-        return true;
+/**
+ * Whether any indexable file under `stashDir` is newer than the last build, or
+ * has never been indexed at all.
+ *
+ * Two independent signals, because neither alone is sufficient:
+ *   1. **mtime > builtAt** — catches in-place *edits* of already-indexed files.
+ *   2. **path not in `indexedPaths`** — catches *newly added* files. This is
+ *      clock-independent on purpose: a freshly-written file can have a
+ *      filesystem mtime that compares as *older* than the wall-clock `builtAt`
+ *      (the two clocks are not perfectly synchronized and `builtAt` is
+ *      millisecond-truncated), so the mtime test alone silently misses
+ *      additions made within ~a millisecond of the previous build.
+ *
+ * `getIndexableFiles` applies each asset type's own relevance filter, so
+ * non-indexed companion files (e.g. `package.json` next to a knowledge doc) are
+ * never considered and do not produce false "new file" positives.
+ */
+function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths) {
+    const builtAtMs = builtAt ? new Date(builtAt).getTime() : Number.NaN;
+    const builtAtUsable = Number.isFinite(builtAtMs);
     for (const [type, spec] of Object.entries(ASSET_SPECS)) {
         const typeRoot = path.join(stashDir, TYPE_DIRS[type] ?? spec.stashDir);
         const files = getIndexableFiles(typeRoot, spec);
         for (const file of files) {
+            if (!indexedPaths.has(file))
+                return true;
+            if (!builtAtUsable)
+                return true;
             try {
                 if (fs.statSync(file).mtimeMs > builtAtMs)
                     return true;
@@ -89,7 +109,7 @@ export function isIndexStale(stashDir) {
         if (entryCount === 0)
             return true;
         const builtAt = getMeta(db, "builtAt");
-        if (hasNewerIndexableFiles(stashDir, builtAt))
+        if (hasNewerIndexableFiles(stashDir, builtAt, getIndexedFilePaths(db)))
             return true;
         const storedStashDir = getMeta(db, "stashDir");
         if (storedStashDir !== stashDir) {
@@ -114,16 +134,84 @@ export function isIndexStale(stashDir) {
     }
 }
 /**
- * Run an incremental index when the local index is stale. Best-effort —
- * failures are logged as warnings but never thrown, so the caller can
- * proceed (and surface a proper "not in index" error if the index is
- * still unusable).
- *
- * Returns `true` if an index run was attempted.
+ * Whether the existing index can serve queries for `stashDir` *right now* —
+ * i.e. the DB file exists, the `entries` table holds rows, and those rows were
+ * built for this stash (it is the stored primary stash or appears in the
+ * stored `stashDirs` set). When this is true the index is at worst
+ * content-stale, so the `#607` background-reindex optimization is safe: the
+ * caller gets slightly-stale-but-relevant results immediately. When it is
+ * false the existing index has nothing relevant to return (no DB, no `entries`
+ * table, zero rows, or built for a different stash), so a background reindex
+ * would leave the caller empty until the next read — those cases must rebuild
+ * inline.
  */
-export async function ensureIndex(stashDir) {
-    if (!isIndexStale(stashDir))
+function indexCanServeStash(stashDir) {
+    const dbPath = getDbPath();
+    if (!fs.existsSync(dbPath))
+        return false;
+    let db;
+    try {
+        db = openExistingDatabase(dbPath);
+        if (getEntryCount(db) === 0)
+            return false;
+        const storedStashDir = getMeta(db, "stashDir");
+        if (storedStashDir === stashDir)
+            return true;
+        try {
+            const storedDirs = JSON.parse(getMeta(db, "stashDirs") ?? "[]");
+            return storedDirs.includes(stashDir);
+        }
+        catch {
+            return false;
+        }
+    }
+    catch {
+        // No `entries` table (or otherwise unreadable) — cannot serve.
         return false;
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
+/**
+ * Spawn a background `akm index` process. Non-blocking — returns immediately.
+ * Background callers share the same global index-writer lease as foreground
+ * writers, so stale-read-triggered auto-index attempts coalesce safely.
+ */
+async function spawnBackgroundReindex(_stashDir) {
+    const dataDir = getDataDir();
+    const logFile = path.join(dataDir, "logs", "index-background.log");
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    const lease = await acquireIndexWriterLease({ mode: "try", purpose: "background-reindex-spawn" });
+    if (!lease)
+        return;
+    const akmBin = process.argv[0];
+    const akmScript = process.argv[1];
+    try {
+        const child = spawn(akmBin, [akmScript, "index", "--background"], {
+            detached: true,
+            stdio: ["ignore", fs.openSync(logFile, "a"), fs.openSync(logFile, "a")],
+            env: { ...process.env },
+        });
+        if (!child.pid) {
+            lease.release();
+            return;
+        }
+        handoffIndexWriterLeaseToPid(lease, child.pid, "background-reindex");
+        try {
+            child.unref();
+        }
+        catch {
+            // ignore
+        }
+    }
+    catch (error) {
+        lease.release();
+        throw error;
+    }
+}
+async function runInlineReindex(stashDir) {
     try {
         const { akmIndex } = await import("./indexer.js");
         await akmIndex({ stashDir });
@@ -134,3 +222,50 @@ export async function ensureIndex(stashDir) {
         return true;
     }
 }
+/**
+ * Ensure the local index exists and is fresh enough for the caller's needs.
+ *
+ * Default mode is `background`, which preserves the low-latency behavior used
+ * by read paths (`search`, `show`, `feedback`): when a populated index is
+ * merely stale, spawn a detached reindex and proceed against the existing
+ * index. When the index is entirely absent (no DB / no `entries` table / zero
+ * rows) the rebuild runs inline regardless of mode, since there is nothing to
+ * proceed against.
+ *
+ * `mode: "blocking"` waits for the rebuild to finish before returning. Use
+ * this for callers like `improve` whose planning logic depends on a populated
+ * `entries` table in the same process.
+ *
+ * Returns `true` if an index run was attempted.
+ */
+export async function ensureIndex(stashDir, options = {}) {
+    if (!isIndexStale(stashDir))
+        return false;
+    // Blocking when explicitly requested, or whenever the existing index cannot
+    // serve this stash (absent DB, no `entries` table, zero rows, or built for a
+    // different stash): a background reindex returns immediately and would leave
+    // a first-time caller (search, curate, wiki, show, feedback) with empty
+    // results. Building inline is a one-off cost; a populated index for this
+    // stash that is merely content-stale still refreshes in the background.
+    if (options.mode === "blocking" || !indexCanServeStash(stashDir)) {
+        return runInlineReindex(stashDir);
+    }
+    // The background path re-invokes the akm CLI as a detached child via
+    // `process.argv[1]`. That is only the akm entrypoint when THIS process is the
+    // akm CLI itself — which the CLI startup block signals with AKM_CLI_ENTRY=1.
+    // In any other host (the in-process test runner, a library embedding akm),
+    // argv[1] points at the host (e.g. the test runner), so spawning it would
+    // launch the wrong program and orphan it. Build inline there instead — same
+    // resulting index, no detached process.
+    if (process.env.AKM_CLI_ENTRY !== "1") {
+        return runInlineReindex(stashDir);
+    }
+    try {
+        await spawnBackgroundReindex(stashDir);
+        return true;
+    }
+    catch (error) {
+        warn("Background reindex spawn failed, proceeding with existing index:", error instanceof Error ? error.message : String(error));
+        return true;
+    }
+}

package/dist/indexer/index-writer-lock.js

@@ -0,0 +1,99 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import path from "node:path";
+import { probeLock, releaseLock, releaseLockIfOwned, tryAcquireLockSync } from "../core/file-lock.js";
+import { getDbPath, getIndexWriterLockPath } from "../core/paths.js";
+const INDEX_WRITER_LOCK_STALE_AFTER_MS = 12 * 60 * 60 * 1000;
+const INDEX_WRITER_WAIT_MS = 100;
+const heldLocks = new Map();
+function buildPayload(purpose, pid = process.pid) {
+    return JSON.stringify({
+        pid,
+        purpose,
+        dbPath: getDbPath(),
+        startedAt: new Date().toISOString(),
+    });
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    throw signal.reason instanceof Error ? signal.reason : new Error("index writer wait aborted");
+}
+function releaseHeldLock(lockPath) {
+    const held = heldLocks.get(lockPath);
+    if (!held)
+        return;
+    held.depth -= 1;
+    if (held.depth > 0)
+        return;
+    heldLocks.delete(lockPath);
+    process.off("exit", held.exitHandler);
+    releaseLockIfOwned(lockPath, process.pid);
+}
+function retainHeldLock(lockPath) {
+    const existing = heldLocks.get(lockPath);
+    if (existing) {
+        existing.depth += 1;
+        return { lockPath, release: () => releaseHeldLock(lockPath) };
+    }
+    const exitHandler = () => releaseLockIfOwned(lockPath, process.pid);
+    process.on("exit", exitHandler);
+    heldLocks.set(lockPath, { depth: 1, exitHandler });
+    return { lockPath, release: () => releaseHeldLock(lockPath) };
+}
+function detachHeldLock(lockPath) {
+    const held = heldLocks.get(lockPath);
+    if (!held)
+        return;
+    heldLocks.delete(lockPath);
+    process.off("exit", held.exitHandler);
+}
+export async function acquireIndexWriterLease(options) {
+    const mode = options.mode ?? "wait";
+    const lockPath = getIndexWriterLockPath();
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    if (heldLocks.has(lockPath)) {
+        return retainHeldLock(lockPath);
+    }
+    while (true) {
+        throwIfAborted(options.signal);
+        if (tryAcquireLockSync(lockPath, buildPayload(options.purpose))) {
+            return retainHeldLock(lockPath);
+        }
+        const probe = probeLock(lockPath, { staleAfterMs: INDEX_WRITER_LOCK_STALE_AFTER_MS });
+        if (probe.state === "held" && probe.holderPid === process.pid) {
+            return retainHeldLock(lockPath);
+        }
+        if (probe.state === "stale") {
+            releaseLock(lockPath);
+            continue;
+        }
+        if (mode === "try")
+            return undefined;
+        await delay(INDEX_WRITER_WAIT_MS);
+    }
+}
+export async function withIndexWriterLease(options, run) {
+    const lease = await acquireIndexWriterLease(options);
+    if (!lease) {
+        throw new Error(`index writer lease unavailable for ${options.purpose}`);
+    }
+    try {
+        return await run();
+    }
+    finally {
+        lease.release();
+    }
+}
+export function handoffIndexWriterLeaseToPid(lease, pid, purpose) {
+    fs.writeFileSync(lease.lockPath, buildPayload(purpose, pid), "utf8");
+    detachHeldLock(lease.lockPath);
+}
+export function probeIndexWriterLease() {
+    return probeLock(getIndexWriterLockPath(), { staleAfterMs: INDEX_WRITER_LOCK_STALE_AFTER_MS });
+}

package/dist/indexer/indexer.js

@@ -12,6 +12,7 @@ import { resolveIndexPassLLM } from "../llm/index-passes.js";
 import { takeWorkflowDocument } from "../workflows/runtime/document-cache.js";
 import { clearStaleCacheEntries, closeDatabase, deleteEntriesByDir, deleteEntriesByIds, deleteEntriesByStashDir, deleteIndexDirStatesByStashDir, getAllEntriesForEmbedding, getEmbeddableEntryCount, getEmbeddingCount, getEntriesByDir, getEntryCount, getIndexDirState, getMeta, isVecAvailable, openDatabase, openExistingDatabase, rebuildFts, relinkUsageEvents, setMeta, upsertEmbedding, upsertEntry, upsertIndexDirState, upsertUtilityScore, upsertWorkflowDocument, warnIfVecMissing, } from "./db/db.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
+import { withIndexWriterLease } from "./index-writer-lock.js";
 import { applyCuratedFrontmatter, applyWikiFrontmatter, generateMetadataFlat, isEnrichmentComplete, isWorkflowSkipWarning, loadStashFile, shouldIndexStashFile, } from "./passes/metadata.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./search/semantic-status.js";
@@ -225,119 +226,121 @@ function runCleanPass(db, dryRun) {
 }
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function akmIndex(options) {
-    const stashDir = options?.stashDir || resolveStashDir();
-    const onProgress = options?.onProgress ?? (() => { });
-    const signal = options?.signal;
-    const reEnrich = options?.reEnrich === true;
-    const full = options?.full === true;
-    const clean = options?.clean === true;
-    const dryRun = options?.dryRun === true;
-    // Load config and resolve all stash sources
-    const { loadConfig } = await import("../core/config/config.js");
-    const config = loadConfig();
-    // One-time, read-only guard: warn if the writable stash still holds an
-    // un-migrated `vaults/` directory. In 0.9.0 the indexer skips `vaults/`
-    // entirely, so an unmigrated vault's `.env` data would silently never be
-    // indexed. Non-destructive — only stats, never reads/writes/deletes.
-    const { warnOnUnmigratedVaults } = await import("./usage/unmigrated-vaults-guard.js");
-    warnOnUnmigratedVaults(stashDir);
-    // Ensure git stash caches are extracted before resolving stash dirs,
-    // so their content directories exist on disk for the walker to discover.
-    const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
-    await ensureSourceCaches(config, { force: full });
-    const allSourceEntries = resolveSourceEntries(stashDir, config);
-    const allSourceDirs = allSourceEntries.map((s) => s.path);
-    const t0 = Date.now();
-    // Open database — pass embedding dimension from config if available
-    const dbPath = getDbPath();
-    const embeddingDim = config.embedding?.dimension;
-    const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
-    try {
-        // Determine incremental vs full mode
-        const prevStashDir = getMeta(db, "stashDir");
-        const prevBuiltAt = getMeta(db, "builtAt");
-        const isIncremental = !full && prevStashDir === stashDir && !!prevBuiltAt;
-        const builtAtMs = isIncremental && prevBuiltAt ? new Date(prevBuiltAt).getTime() : 0;
-        // Assemble the run context
-        const ctx = {
-            db,
-            config,
-            sources: allSourceEntries,
-            sourceDirs: allSourceDirs,
-            full,
-            reEnrich,
-            stashDir,
-            onProgress,
-            signal,
-            timing: {
-                t0,
-                tWalkStart: t0,
-                tWalkEnd: t0,
-                tLlmEnd: t0,
-                tFtsEnd: t0,
-                tEmbedEnd: t0,
-            },
-            isIncremental,
-            builtAtMs,
-            hadRemovedSources: false,
-            scannedDirs: 0,
-            skippedDirs: 0,
-            generatedCount: 0,
-            walkWarnings: [],
-            dirsNeedingLlm: [],
-            embeddingResult: null,
-            graphExtractionResult: null,
-        };
-        onProgress({
-            phase: "summary",
-            message: buildIndexSummaryMessage({
+    return withIndexWriterLease({ purpose: "akm-index", signal: options?.signal }, async () => {
+        const stashDir = options?.stashDir || resolveStashDir();
+        const onProgress = options?.onProgress ?? (() => { });
+        const signal = options?.signal;
+        const reEnrich = options?.reEnrich === true;
+        const full = options?.full === true;
+        const clean = options?.clean === true;
+        const dryRun = options?.dryRun === true;
+        // Load config and resolve all stash sources
+        const { loadConfig } = await import("../core/config/config.js");
+        const config = loadConfig();
+        // One-time, read-only guard: warn if the writable stash still holds an
+        // un-migrated `vaults/` directory. In 0.9.0 the indexer skips `vaults/`
+        // entirely, so an unmigrated vault's `.env` data would silently never be
+        // indexed. Non-destructive — only stats, never reads/writes/deletes.
+        const { warnOnUnmigratedVaults } = await import("./usage/unmigrated-vaults-guard.js");
+        warnOnUnmigratedVaults(stashDir);
+        // Ensure git stash caches are extracted before resolving stash dirs,
+        // so their content directories exist on disk for the walker to discover.
+        const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
+        await ensureSourceCaches(config, { force: full });
+        const allSourceEntries = resolveSourceEntries(stashDir, config);
+        const allSourceDirs = allSourceEntries.map((s) => s.path);
+        const t0 = Date.now();
+        // Open database — pass embedding dimension from config if available
+        const dbPath = getDbPath();
+        const embeddingDim = config.embedding?.dimension;
+        const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+        try {
+            // Determine incremental vs full mode
+            const prevStashDir = getMeta(db, "stashDir");
+            const prevBuiltAt = getMeta(db, "builtAt");
+            const isIncremental = !full && prevStashDir === stashDir && !!prevBuiltAt;
+            const builtAtMs = isIncremental && prevBuiltAt ? new Date(prevBuiltAt).getTime() : 0;
+            // Assemble the run context
+            const ctx = {
+                db,
+                config,
+                sources: allSourceEntries,
+                sourceDirs: allSourceDirs,
+                full,
+                reEnrich,
+                stashDir,
+                onProgress,
+                signal,
+                timing: {
+                    t0,
+                    tWalkStart: t0,
+                    tWalkEnd: t0,
+                    tLlmEnd: t0,
+                    tFtsEnd: t0,
+                    tEmbedEnd: t0,
+                },
+                isIncremental,
+                builtAtMs,
+                hadRemovedSources: false,
+                scannedDirs: 0,
+                skippedDirs: 0,
+                generatedCount: 0,
+                walkWarnings: [],
+                dirsNeedingLlm: [],
+                embeddingResult: null,
+                graphExtractionResult: null,
+            };
+            onProgress({
+                phase: "summary",
+                message: buildIndexSummaryMessage({
+                    mode: isIncremental ? "incremental" : "full",
+                    sourcesCount: allSourceDirs.length,
+                    semanticSearchMode: config.semanticSearchMode,
+                    embeddingProvider: getEmbeddingProvider(config.embedding),
+                    llmEnabled: !!resolveIndexPassLLM("enrichment", config),
+                    vecAvailable: isVecAvailable(db),
+                }),
+            });
+            // ── Phase sequence ───────────────────────────────────────────────────────
+            await runSourceCachePhase(ctx);
+            await runWalkPhase(ctx);
+            await runEmbeddingPhase(ctx);
+            await runFinalizePhase(ctx);
+            // ────────────────────────────────────────────────────────────────────────
+            const { _verification: verification, _totalEntries: totalEntries } = ctx;
+            const { timing } = ctx;
+            // ── Clean pass ───────────────────────────────────────────────────────────
+            // After the normal index completes, remove entries whose source files no
+            // longer exist on disk. Remote entries (empty file_path) are skipped.
+            let cleanResult;
+            if (clean) {
+                cleanResult = runCleanPass(db, dryRun);
+            }
+            // ────────────────────────────────────────────────────────────────────────
+            return {
+                stashDir,
+                totalEntries,
+                generatedMetadata: ctx.generatedCount,
+                indexPath: dbPath,
                 mode: isIncremental ? "incremental" : "full",
-                sourcesCount: allSourceDirs.length,
-                semanticSearchMode: config.semanticSearchMode,
-                embeddingProvider: getEmbeddingProvider(config.embedding),
-                llmEnabled: !!resolveIndexPassLLM("enrichment", config),
-                vecAvailable: isVecAvailable(db),
-            }),
-        });
-        // ── Phase sequence ───────────────────────────────────────────────────────
-        await runSourceCachePhase(ctx);
-        await runWalkPhase(ctx);
-        await runEmbeddingPhase(ctx);
-        await runFinalizePhase(ctx);
-        // ────────────────────────────────────────────────────────────────────────
-        const { _verification: verification, _totalEntries: totalEntries } = ctx;
-        const { timing } = ctx;
-        // ── Clean pass ───────────────────────────────────────────────────────────
-        // After the normal index completes, remove entries whose source files no
-        // longer exist on disk. Remote entries (empty file_path) are skipped.
-        let cleanResult;
-        if (clean) {
-            cleanResult = runCleanPass(db, dryRun);
+                directoriesScanned: ctx.scannedDirs,
+                directoriesSkipped: ctx.skippedDirs,
+                ...(ctx.walkWarnings.length > 0 ? { warnings: ctx.walkWarnings } : {}),
+                verification,
+                timing: {
+                    totalMs: Date.now() - timing.t0,
+                    walkMs: timing.tWalkEnd - timing.tWalkStart,
+                    llmMs: timing.tLlmEnd - timing.tWalkEnd,
+                    embedMs: timing.tEmbedEnd - timing.tLlmEnd,
+                    ftsMs: timing.tFtsEnd - timing.tEmbedEnd,
+                },
+                ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
+            };
         }
-        // ────────────────────────────────────────────────────────────────────────
-        return {
-            stashDir,
-            totalEntries,
-            generatedMetadata: ctx.generatedCount,
-            indexPath: dbPath,
-            mode: isIncremental ? "incremental" : "full",
-            directoriesScanned: ctx.scannedDirs,
-            directoriesSkipped: ctx.skippedDirs,
-            ...(ctx.walkWarnings.length > 0 ? { warnings: ctx.walkWarnings } : {}),
-            verification,
-            timing: {
-                totalMs: Date.now() - timing.t0,
-                walkMs: timing.tWalkEnd - timing.tWalkStart,
-                llmMs: timing.tLlmEnd - timing.tWalkEnd,
-                embedMs: timing.tEmbedEnd - timing.tLlmEnd,
-                ftsMs: timing.tFtsEnd - timing.tEmbedEnd,
-            },
-            ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
-        };
-    }
-    finally {
-        closeDatabase(db);
-    }
+        finally {
+            closeDatabase(db);
+        }
+    });
 }
 // ── Extracted helpers for indexing ────────────────────────────────────────────
 async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, doFullDelete = false, onProgress) {

package/dist/integrations/harnesses/claude/session-log.js

@@ -298,7 +298,7 @@ export class ClaudeCodeProvider {
                 const full = path.join(dir, entry.name);
                 if (entry.isDirectory())
                     yield* this.#walkJsonl(full);
-                else if (entry.name.endsWith(".jsonl"))
+                else if (entry.name.endsWith(".jsonl") && entry.name !== "journal.jsonl")
                     yield full;
             }
         }

package/dist/llm/client.js

@@ -119,9 +119,23 @@ function looksLikeContextOverflow(message) {
 /**
  * Decide whether a first-attempt {@link LlmCallError} is eligible for a single
  * retry. Retryable: HTTP 5xx (`provider_error` with statusCode >= 500) and
- * `network_error` whose message looks like a transient connection reset
- * (ECONNRESET / EPIPE / "fetch failed"). NOT retryable: 4xx, `rate_limited`
- * (429), `timeout`, `parse_error`, and context-overflow-classified errors.
+ * `network_error` whose message looks like a transient connection drop.
+ * NOT retryable: 4xx, `rate_limited` (429), `timeout`, `parse_error`, and
+ * context-overflow-classified errors.
+ *
+ * The connection-drop heuristic covers the substrings emitted across runtimes
+ * for a mid-flight socket close:
+ *  - `ECONNRESET` / `EPIPE` — Node/libuv socket reset codes
+ *  - `fetch failed` — undici's generic wrapper message
+ *  - `socket connection was closed` — Bun's message for a dropped connection
+ *    (e.g. "The socket connection was closed unexpectedly.")
+ *  - `terminated` / `other side closed` — undici's phrasings for the same
+ *
+ * These all describe a transient transport failure where a second attempt can
+ * legitimately succeed, which is exactly the case a single bounded retry is
+ * meant to absorb. Before this list was widened, Bun's "socket connection was
+ * closed unexpectedly" fell through unretried and surfaced as a recurring
+ * failure in the improve/reflect and capability-probe flows.
  */
 function isRetryable(err) {
     if (looksLikeContextOverflow(err.message))
@@ -131,7 +145,12 @@ function isRetryable(err) {
     }
     if (err.code === "network_error") {
         const lower = err.message.toLowerCase();
-        return lower.includes("econnreset") || lower.includes("epipe") || lower.includes("fetch failed");
+        return (lower.includes("econnreset") ||
+            lower.includes("epipe") ||
+            lower.includes("fetch failed") ||
+            lower.includes("socket connection was closed") ||
+            lower.includes("terminated") ||
+            lower.includes("other side closed"));
     }
     return false;
 }