akm-cli 0.9.0-beta.3 → 0.9.0-beta.30

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/indexer/passes/memory-inference.js

@@ -425,10 +425,17 @@ function markParentProcessed(parent) {
         warn(`memory inference: failed to re-read parent ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return;
     }
-    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
     const block = parseFrontmatterBlock(raw);
-    const body = block?.content ?? raw;
-    const next = assembleAsset(updatedFm, body);
+    if (!block) {
+        // Cannot safely rewrite malformed frontmatter — skip marking so the memory
+        // is retried on the next run once the frontmatter is repaired. Writing with
+        // `body = raw` would wrap the entire file (including the bad frontmatter)
+        // in a new block, producing a duplicate-frontmatter corruption.
+        warn(`memory inference: skipping markParentProcessed for ${parent.filePath} — could not parse frontmatter block`);
+        return;
+    }
+    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
+    const next = assembleAsset(updatedFm, block.content);
     try {
         fs.writeFileSync(parent.filePath, next, "utf8");
     }

package/dist/indexer/passes/staleness-detect.js

@@ -44,6 +44,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import stalenessDetectSystemPrompt from "../../assets/prompts/staleness-detect-system.md" with { type: "text" };
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
 import { concurrentMap } from "../../core/concurrent.js";
@@ -319,11 +320,7 @@ function pickSimilar(candidate, all) {
     return scored.slice(0, TOP_K_SIMILAR).map((s) => s.snap);
 }
 // ── LLM dispatch ────────────────────────────────────────────────────────────
-const SYSTEM_PROMPT = "You are a belief-state classifier for a memory store. Given a candidate memory and a list of more-recent similar memories from the same store, decide whether the candidate is still current or has been superseded.\n\n" +
-    "Respond on the first line with exactly YES or NO.\n" +
-    "If YES, the second line MUST be of the form `SUPERSEDED_BY: <ref>` where <ref> is the exact ref of the superseding memory from the list provided. Do NOT invent refs.\n" +
-    "If NO, do not include any additional lines.\n" +
-    "No prose, no preamble, no markdown.";
+const SYSTEM_PROMPT = stalenessDetectSystemPrompt;
 async function askValidator(connection, candidate, allMemories, signal, timeoutMs) {
     const similar = pickSimilar(candidate, allMemories);
     if (similar.length === 0) {

package/dist/indexer/search/db-search.js

@@ -65,6 +65,7 @@ export async function searchLocal(input) {
     const includeProposed = input.includeProposed === true;
     const beliefFilter = input.beliefFilter ?? "all";
     const restrictToSources = input.restrictToSources === true;
+    const includeExcludedTypes = input.includeExcludedTypes === true;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
@@ -114,7 +115,7 @@ export async function searchLocal(input) {
                 mode: "keyword",
             };
         }
-        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources);
+        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes);
         return {
             hits,
             tip: hits.length === 0
@@ -131,14 +132,19 @@ export async function searchLocal(input) {
     }
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false, includeExcludedTypes = false) {
     const hasSearchableTokens = query.length > 0 && sanitizeFtsQuery(query).length > 0;
+    // #627 — resolve the default type-exclusion policy. It applies ONLY on the
+    // untyped ('any') path and only when the caller did not opt back in via
+    // `includeExcludedTypes`. When the config key is ABSENT a built-in default of
+    // ['session'] is applied; an explicit empty list disables exclusion.
+    const defaultExcludes = searchType === "any" && !includeExcludedTypes ? (config.search?.defaultExcludeTypes ?? ["session"]) : [];
     // Empty queries — including ones that sanitize down to no searchable FTS
     // tokens such as "." — should enumerate matching entries instead of
     // returning an empty result set from FTS.
     if (!hasSearchableTokens) {
         const typeFilter = searchType === "any" ? undefined : searchType;
-        const allEntries = getAllEntries(db, typeFilter);
+        const allEntries = getAllEntries(db, typeFilter, defaultExcludes);
         // Deduplicate by file path — multiple entries can share the same file
         const seenFilePaths = new Set();
         const uniqueEntries = allEntries.filter((ie) => {
@@ -187,7 +193,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const typeFilter = searchType === "any" ? undefined : searchType;
     const tEmbed0 = Date.now();
     const embeddingPromise = tryVecScores(db, query, limit * 3, config);
-    const ftsResults = searchFts(db, query, limit * 3, typeFilter);
+    const ftsResults = searchFts(db, query, limit * 3, typeFilter, defaultExcludes);
     const embeddingScores = await embeddingPromise;
     const embedMs = Date.now() - tEmbed0;
     const tRank0 = Date.now();
@@ -208,6 +214,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         embedScoreMap,
         getEntryById: (id) => getEntryById(db, id) ?? undefined,
         typeFilter,
+        // #627 — also exclude default-hidden types from the vector-only branch so a
+        // session asset that is a top-k vector neighbor (but not an FTS match) does
+        // not leak into default ('any') results. defaultExcludes is already []
+        // unless this is the untyped path without includeExcludedTypes.
+        excludeTypes: defaultExcludes,
     });
     // ── Scoring Phase ──────────────────────────────────────────────────────
     // Apply boosts as multiplicative factors (all boosts in a single phase

package/dist/indexer/search/ranking-contributors.js

@@ -9,6 +9,9 @@ const TYPE_BOOST = {
     agent: 0.3,
     script: 0.2,
     knowledge: 0.22,
+    // Facts are authoritative, durable declarations about the stash — rank them
+    // alongside knowledge so they surface reliably when relevant.
+    fact: 0.22,
     memory: -0.02,
 };
 const MAX_BOOST_SUM = 3.0;
@@ -206,6 +209,24 @@ const lessonStrengthContributor = {
         return Math.min(0.3, 0.06 * strength);
     },
 };
+/**
+ * Pinned-fact boost.
+ *
+ * Facts marked `pinned: true` form the small always-injected "core context"
+ * (see docs/design/fact-asset-type.md). The fact metadata contributor records
+ * a `pinned` search hint; here we give those facts a modest additive boost so
+ * the core outranks ordinary facts on otherwise-equal queries. Capped small so
+ * it cannot overpower an exact-name match.
+ */
+const pinnedFactRankingContributor = {
+    name: "pinned-fact-ranking",
+    appliesTo(item) {
+        return item.entry.type === "fact" && (item.entry.searchHints?.includes("pinned") ?? false);
+    },
+    adjust() {
+        return 0.15;
+    },
+};
 /**
  * Blend ratio for scoped vs. global utility signals.
  *
@@ -310,6 +331,7 @@ export const defaultRankingContributors = [
     graphRankingContributor,
     captureModeRankingContributor,
     lessonStrengthContributor,
+    pinnedFactRankingContributor,
     projectContextRankingContributor,
 ];
 export const defaultUtilityRankingContributors = [utilityRankingContributor];

package/dist/indexer/search/ranking.js

@@ -20,6 +20,7 @@ export function normalizeFtsScores(results) {
 export function combineSearchScores(options) {
     const FTS_WEIGHT = 0.7;
     const VEC_WEIGHT = 0.3;
+    const excludeTypeSet = options.excludeTypes && options.excludeTypes.length > 0 ? new Set(options.excludeTypes) : null;
     const scored = [];
     const seenIds = new Set();
     for (const [id, { score: ftsScore, result }] of options.ftsScoreMap) {
@@ -42,6 +43,9 @@ export function combineSearchScores(options) {
             continue;
         if (options.typeFilter && found.entry.type !== options.typeFilter)
             continue;
+        // #627 — drop vector-only neighbors whose type is excluded on the default path.
+        if (excludeTypeSet?.has(found.entry.type))
+            continue;
         scored.push({
             id,
             entry: found.entry,

package/dist/indexer/walk/matchers.js

@@ -78,6 +78,15 @@ const DIR_TYPE_MAP = [
         type: "session",
         test: (ext) => ext === ".md",
     },
+    {
+        // Durable stash-level facts live under `facts/<category>/<name>.md`.
+        // classifyByDirectory walks every ancestor dir, so nested category
+        // subdirs still match. Without this entry a fact file would fall through
+        // to classifyBySmartMd and be mistyped as `knowledge`.
+        dir: "facts",
+        type: "fact",
+        test: (ext) => ext === ".md",
+    },
 ];
 const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
 // Files that should never be treated as the typed asset for the surrounding

package/dist/integrations/agent/prompts.js

@@ -43,6 +43,7 @@ const TYPE_HINTS = {
     script: "script assets are executable text files. Include a shebang and minimal usage comment.",
     env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>` (the safe path — values never reach stdout/your context); do NOT run `akm env export` and read its output, as that prints values. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
+    fact: "fact assets are durable stash-level facts (personal/team/project details, coding conventions, stash-meta). Frontmatter SHOULD include `description` and a `category` (personal|team|project|convention|meta); set `pinned: true` only for the small always-injected core. Keep each fact short, high-signal, and self-contained — it is durable context, not an episodic note.",
 };
 function hintForType(type) {
     return TYPE_HINTS[type] ?? `assets of type "${type}" — produce sensible markdown with optional frontmatter.`;

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

@@ -107,6 +107,16 @@ export class ClaudeCodeProvider {
     isAvailable() {
         return fs.existsSync(claudeProjectsDir());
     }
+    /**
+     * Directory holding Claude Code's per-project session JSONL files
+     * (`~/.claude/projects`, honoring `AKM_CLAUDE_PROJECTS_DIR`). Returns `[]`
+     * when the directory does not exist on this machine. See {@link
+     * SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const dir = claudeProjectsDir();
+        return fs.existsSync(dir) ? [dir] : [];
+    }
     *readEvents(input) {
         try {
             for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {
@@ -298,7 +308,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/integrations/harnesses/opencode/session-log.js

@@ -26,6 +26,15 @@ export class OpenCodeProvider {
     isAvailable() {
         return fs.existsSync(this.#baseDir);
     }
+    /**
+     * Directory holding opencode's per-project session metadata files
+     * (`<base>/storage/session`). Returns `[]` when it does not exist on this
+     * machine. See {@link SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const sessionRoot = path.join(this.#baseDir, "storage", "session");
+        return fs.existsSync(sessionRoot) ? [sessionRoot] : [];
+    }
     *readEvents(input) {
         // Legacy behavior: stream raw log lines from the top-level dir and `log/`
         // subdirectory. Kept to keep `getExecutionLogCandidates` working without

package/dist/integrations/session-logs/index.js

@@ -28,6 +28,22 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
+/**
+ * Map each available harness to its `{ harnessName, roots }` watch target,
+ * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
+ * result). This is the one stable entry point the watcher uses so it never
+ * reaches into providers directly.
+ */
+export function getWatchTargets() {
+    const targets = [];
+    for (const harness of getAvailableHarnesses()) {
+        const roots = harness.watchRoots?.() ?? [];
+        if (roots.length === 0)
+            continue;
+        targets.push({ harnessName: harness.name, roots });
+    }
+    return targets;
+}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)

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;
 }

package/dist/llm/embedder.js

@@ -2,7 +2,7 @@
 // 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 { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache.js";
-import { isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
+import { DEFAULT_LOCAL_MODEL, isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
@@ -52,7 +52,8 @@ export async function embed(text, embeddingConfig, signal) {
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
- * Falls back to sequential embedding for the local transformer pipeline.
+ * Uses the LocalEmbedder.embedBatch path for the local transformer pipeline,
+ * which processes texts in chunks of 32 for genuine batched inference.
  */
 export async function embedBatch(texts, embeddingConfig, signal) {
     if (texts.length === 0)
@@ -60,8 +61,13 @@ export async function embedBatch(texts, embeddingConfig, signal) {
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         return new RemoteEmbedder(embeddingConfig).embedBatch(texts, signal);
     }
-    // Local transformer: process sequentially (pipeline handles one at a time)
+    // Local transformer: use the batched path (chunks of 32 via LocalEmbedder).
+    // When a localModel override is set we cannot share the singleton (which uses
+    // the default model), so fall back to per-text embedWithModel in that case.
     const localModel = embeddingConfig?.localModel;
+    if (!localModel) {
+        return getLocalEmbedder().embedBatch(texts, signal);
+    }
     const results = [];
     for (const text of texts) {
         if (signal?.aborted) {
@@ -77,6 +83,24 @@ export async function embedBatch(texts, embeddingConfig, signal) {
 // facade and its `@huggingface/transformers` import chain. Re-export
 // preserves the existing public API.
 export { cosineSimilarity } from "./embedders/types.js";
+// ── Model ID resolution ─────────────────────────────────────────────────────
+/**
+ * Derive a stable string identifier for the embedding model in use.
+ * This is the `model_id` stored in `body_embeddings` (and used for the
+ * drop-all-on-mismatch purge when the model changes).
+ *
+ * Rules:
+ *   - Remote endpoint: use `config.model` (the API-level model name).
+ *   - Local transformers: use `config.localModel ?? DEFAULT_LOCAL_MODEL`.
+ *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
+ */
+export function resolveEmbeddingModelId(embeddingConfig) {
+    if (!embeddingConfig)
+        return DEFAULT_LOCAL_MODEL;
+    if (hasRemoteEndpoint(embeddingConfig))
+        return embeddingConfig.model ?? "remote";
+    return embeddingConfig.localModel ?? DEFAULT_LOCAL_MODEL;
+}
 // ── Availability check ──────────────────────────────────────────────────────
 /**
  * Check whether embedding is available with a detailed reason on failure.