akm-cli 0.8.6 → 0.8.14

package/dist/indexer/indexer.js

@@ -3,20 +3,20 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { SCRIPT_EXTENSIONS } from "../core/asset-spec";
-import { isHttpUrl, resolveStashDir, toErrorMessage } from "../core/common";
-import { concurrentMap } from "../core/concurrent";
-import { getDbPath } from "../core/paths";
-import { isVerbose, warn, warnVerbose } from "../core/warn";
-import { resolveIndexPassLLM } from "../llm/index-passes";
-import { takeWorkflowDocument } from "../workflows/document-cache";
-import { clearStaleCacheEntries, closeDatabase, deleteEntriesByDir, deleteEntriesByIds, deleteEntriesByStashDir, deleteIndexDirStatesByStashDir, getAllEntriesForEmbedding, getEmbeddingCount, getEntriesByDir, getEntryCount, getIndexDirState, getMeta, isVecAvailable, openDatabase, openExistingDatabase, rebuildFts, relinkUsageEvents, setMeta, upsertEmbedding, upsertEntry, upsertIndexDirState, upsertUtilityScore, upsertWorkflowDocument, warnIfVecMissing, } from "./db";
-import { deleteStoredGraph } from "./graph-db";
-import { applyCuratedFrontmatter, applyWikiFrontmatter, generateMetadataFlat, isEnrichmentComplete, isWorkflowSkipWarning, loadStashFile, shouldIndexStashFile, } from "./metadata";
-import { buildSearchText } from "./search-fields";
-import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./semantic-status";
-import { ensureUsageEventsSchema, purgeOldUsageEvents } from "./usage-events";
-import { walkStashFlat } from "./walker";
+import { SCRIPT_EXTENSIONS } from "../core/asset/asset-spec.js";
+import { isHttpUrl, resolveStashDir, toErrorMessage } from "../core/common.js";
+import { concurrentMap } from "../core/concurrent.js";
+import { getDbPath } from "../core/paths.js";
+import { isVerbose, warn, warnVerbose } from "../core/warn.js";
+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 { 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";
+import { ensureUsageEventsSchema, purgeOldUsageEvents } from "./usage/usage-events.js";
+import { walkStashFlat } from "./walk/walker.js";
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
@@ -177,7 +177,8 @@ async function runFinalizePhase(ctx) {
     setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
     warnIfVecMissing(db);
     const totalEntries = getEntryCount(db);
-    const verification = verifyIndexState(db, config, totalEntries, embeddingResult);
+    const semanticEntryCount = getEmbeddableEntryCount(db);
+    const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
     if (config.semanticSearchMode === "off") {
         clearSemanticStatus();
     }
@@ -232,11 +233,17 @@ export async function akmIndex(options) {
     const clean = options?.clean === true;
     const dryRun = options?.dryRun === true;
     // Load config and resolve all stash sources
-    const { loadConfig } = await import("../core/config.js");
+    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-source.js");
+    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);
@@ -995,11 +1002,11 @@ function getSemanticSearchLabel(semanticSearchMode, embeddingProvider, vecAvaila
         return "disabled";
     return `${embeddingProvider} embeddings, ${vecAvailable ? "sqlite-vec" : "JS fallback"}`;
 }
-function verifyIndexState(db, config, totalEntries, embeddingResult) {
+function verifyIndexState(db, config, embeddableEntries, embeddingResult) {
     const embeddingCount = getEmbeddingCount(db);
     const vecAvailable = isVecAvailable(db);
     const embeddingProvider = getEmbeddingProvider(config.embedding);
-    if (totalEntries === 0) {
+    if (embeddableEntries === 0) {
         return {
             ok: true,
             message: "Index ready. No assets were found yet.",
@@ -1007,7 +1014,7 @@ function verifyIndexState(db, config, totalEntries, embeddingResult) {
             semanticSearchMode: config.semanticSearchMode,
             semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
             embeddingProvider,
-            entryCount: totalEntries,
+            entryCount: embeddableEntries,
             embeddingCount,
             vecAvailable,
         };
@@ -1020,20 +1027,20 @@ function verifyIndexState(db, config, totalEntries, embeddingResult) {
             semanticSearchMode: config.semanticSearchMode,
             semanticStatus: "disabled",
             embeddingProvider,
-            entryCount: totalEntries,
+            entryCount: embeddableEntries,
             embeddingCount,
             vecAvailable,
         };
     }
-    if (embeddingCount >= totalEntries) {
+    if (embeddingCount >= embeddableEntries) {
         return {
             ok: true,
-            message: `Semantic search ready (${embeddingCount}/${totalEntries} embeddings, ${vecAvailable ? "sqlite-vec active" : "JS fallback active"}).`,
+            message: `Semantic search ready (${embeddingCount}/${embeddableEntries} embeddings, ${vecAvailable ? "sqlite-vec active" : "JS fallback active"}).`,
             semanticSearchEnabled: true,
             semanticSearchMode: config.semanticSearchMode,
             semanticStatus: vecAvailable ? "ready-vec" : "ready-js",
             embeddingProvider,
-            entryCount: totalEntries,
+            entryCount: embeddableEntries,
             embeddingCount,
             vecAvailable,
         };
@@ -1041,7 +1048,7 @@ function verifyIndexState(db, config, totalEntries, embeddingResult) {
     return {
         ok: false,
         message: embeddingResult.message ??
-            `Semantic search verification failed (${embeddingCount}/${totalEntries} embeddings available).`,
+            `Semantic search verification failed (${embeddingCount}/${embeddableEntries} embeddings available).`,
         guidance: embeddingProvider === "remote"
             ? "Check your embedding endpoint and credentials, then retry `akm index --full --verbose`."
             : "Retry `akm index --full --verbose`. If it still fails, confirm local model downloads are permitted and see docs/configuration.md for local embedding dependency setup.",
@@ -1049,7 +1056,7 @@ function verifyIndexState(db, config, totalEntries, embeddingResult) {
         semanticSearchMode: config.semanticSearchMode,
         semanticStatus: "blocked",
         embeddingProvider,
-        entryCount: totalEntries,
+        entryCount: embeddableEntries,
         embeddingCount,
         vecAvailable,
     };
@@ -1075,8 +1082,8 @@ function resolveIndexedFiles(dirPath, files, stash) {
     return resolved.size > 0 ? [...resolved] : files;
 }
 async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db, entryKeys, reEnrich, akmConfig, onEntryDone) {
-    const { enhanceMetadata } = await import("../llm/metadata-enhance");
-    const { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } = await import("./db.js");
+    const { enhanceMetadata } = await import("../llm/metadata-enhance.js");
+    const { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } = await import("./db/db.js");
     const results = await concurrentMap(stash.entries, async (entry, idx) => {
         if (signal?.aborted)
             return entry;
@@ -1233,8 +1240,8 @@ function mergeLegacyEntry(entry, legacyEntries) {
  * `NotFoundError` with their own messaging.
  */
 export async function lookup(ref) {
-    const { loadConfig } = await import("../core/config.js");
-    const { resolveSourceEntries } = await import("./search-source.js");
+    const { loadConfig } = await import("../core/config/config.js");
+    const { resolveSourceEntries } = await import("./search/search-source.js");
     const config = loadConfig();
     const sources = resolveSourceEntries(undefined, config);
     if (sources.length === 0)

package/dist/indexer/init.js

@@ -0,0 +1,54 @@
+// 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/.
+/**
+ * Explicit composition root for the indexer's built-in registrations.
+ *
+ * Historically two independent lazy gates (`ensureBuiltinsRegistered` in
+ * `walk/file-context.ts` and `ensureBuiltinMetadataContributorsRegistered` in
+ * `passes/metadata-contributors.ts`) each registered a different built-in set
+ * on first use. That implicit, order-dependent wiring is the M1/M2 finding in
+ * `docs/technical/code-health-brittleness-audit.md`.
+ *
+ * `initIndexer()` folds both into a single deterministic, idempotent entry
+ * point. It registers, exactly once:
+ *
+ *  1. Built-in matchers   — `registerBuiltinMatchers()` (`walk/matchers.ts`).
+ *  2. Built-in renderers  — `registerBuiltinRenderers()` (`output/renderers.ts`).
+ *  3. Metadata contributors — top-level registration side-effects that run when
+ *     `output/renderers.ts` and `workflows/renderer.ts` are imported.
+ *
+ * Importing `output/renderers.ts` satisfies both (2) and the renderer-owned
+ * metadata contributors; `workflows/renderer.ts` is imported explicitly for the
+ * workflow contributor (it is already transitively pulled in by renderers, but
+ * the explicit import preserves the original gate's import set and keeps the
+ * wiring self-documenting).
+ *
+ * Timing is preserved: this stays a *lazy* gate. It is awaited from the same
+ * accessor call sites the old gates were awaited from, so no startup work is
+ * forced eagerly. The shared promise makes concurrent and repeat calls safe —
+ * the registrations run at most once per process.
+ */
+let initPromise;
+/**
+ * Idempotently register every built-in indexer contributor (matchers,
+ * renderers, and metadata contributors).
+ *
+ * Safe to call repeatedly and concurrently: the registration work runs at most
+ * once; subsequent calls await the same resolved promise.
+ */
+export function initIndexer() {
+    if (!initPromise) {
+        initPromise = (async () => {
+            const { registerBuiltinMatchers } = await import("./walk/matchers.js");
+            // Importing renderers registers the built-in metadata contributors as a
+            // load-time side-effect and exposes registerBuiltinRenderers().
+            const { registerBuiltinRenderers } = await import("../output/renderers.js");
+            // Imported for the workflow metadata contributor's load-time side-effect.
+            await import("../workflows/renderer.js");
+            registerBuiltinMatchers();
+            registerBuiltinRenderers();
+        })();
+    }
+    return initPromise;
+}

package/dist/indexer/manifest.js

@@ -11,16 +11,16 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { makeAssetRef } from "../core/asset-ref";
-import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
-import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
-import { getDbPath } from "../core/paths";
-import { warn } from "../core/warn";
-import { closeDatabase, getAllEntries, getEntryCount, getMeta, openExistingDatabase } from "./db";
-import { generateMetadataFlat, loadStashFile } from "./metadata";
-import { resolveSourceEntries } from "./search-source";
-import { walkStashFlat } from "./walker";
+import { makeAssetRef } from "../core/asset/asset-ref.js";
+import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset/asset-spec.js";
+import { resolveStashDir } from "../core/common.js";
+import { loadConfig } from "../core/config/config.js";
+import { getDbPath } from "../core/paths.js";
+import { warn } from "../core/warn.js";
+import { closeDatabase, getAllEntries, getEntryCount, getMeta, openExistingDatabase } from "./db/db.js";
+import { generateMetadataFlat, loadStashFile } from "./passes/metadata.js";
+import { resolveSourceEntries } from "./search/search-source.js";
+import { walkStashFlat } from "./walk/walker.js";
 const MAX_DESCRIPTION_LENGTH = 80;
 /**
  * Truncate a description string to a maximum length, appending "..." if truncated.

package/dist/indexer/{memory-inference.js → passes/memory-inference.js}

@@ -1,19 +1,52 @@
 // 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/.
+/**
+ * Memory inference pass for `akm index` (#201).
+ *
+ * Detects memories pending inference, asks the configured LLM to compress each
+ * into one higher-signal derived memory, and writes the result back as a new
+ * memory file with frontmatter `inferred: true` + a `source:` backref to the
+ * parent memory.
+ *
+ * Pending predicate (see {@link isPendingMemory}):
+ *   - File lives under `<stashRoot>/memories/` and ends in `.md`.
+ *   - Frontmatter does NOT have `inferenceProcessed: true` (parent already split).
+ *   - Frontmatter does NOT have `inferred: true` (this is itself a child fact).
+ *
+ * Idempotency: after a successful split the parent's frontmatter is rewritten
+ * with `inferenceProcessed: true`. A subsequent `akm index` therefore skips
+ * the parent without re-running the LLM.
+ *
+ * Disabling — two orthogonal gates:
+ *   1. `profiles.improve.default.processes.memoryInference.enabled = false`
+ *      blocks the pass at the feature-flag layer (no network call may ever
+ *      issue). Historically the v1 spec §14 gate, superseded by the 0.8.0
+ *      profile shape.
+ *   2. `index.memory.llm = false` (or no resolvable LLM profile) opts the
+ *      pass out at the per-pass layer (#208).
+ *   A pass runs iff both layers allow it. Existing inferred children are
+ *   NEVER deleted — the user keeps what was already produced.
+ *
+ * Locked v1 contract:
+ *   - LLM access is exclusively via `resolveIndexPassLLM("memory", config)`.
+ *   - All child memory writes go through `writeAssetToSource` in
+ *     `src/core/write-source.ts`. The parent's frontmatter rewrite is an
+ *     explicit narrow exception — see {@link markParentProcessed}.
+ */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset-ref";
-import { assembleAsset } from "../core/asset-serialize";
-import { concurrentMap } from "../core/concurrent";
-import { parseFrontmatter, parseFrontmatterBlock } from "../core/frontmatter";
-import { warn } from "../core/warn";
-import { writeAssetToSource } from "../core/write-source";
-import { isProcessEnabled } from "../llm/feature-gate";
-import { resolveIndexPassLLM } from "../llm/index-passes";
-import * as memoryInfer from "../llm/memory-infer";
-import { withLlmCache } from "./llm-cache";
-import { walkMarkdownFiles } from "./walker";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { assembleAsset } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
+import { concurrentMap } from "../../core/concurrent.js";
+import { warn } from "../../core/warn.js";
+import { writeAssetToSource } from "../../core/write-source.js";
+import { isProcessEnabled } from "../../llm/feature-gate.js";
+import { resolveIndexPassLLM } from "../../llm/index-passes.js";
+import * as memoryInfer from "../../llm/memory-infer.js";
+import { withLlmCache } from "../db/llm-cache.js";
+import { walkMarkdownFiles } from "../walk/walker.js";
 /**
  * Frontmatter keys this pass cares about. Constants so a future rename only
  * needs to touch one site.
@@ -37,17 +70,24 @@ const FM_CAPTURE_MODE = "captureMode";
  * Both must allow the call for the pass to run. Either set to `false`
  * short-circuits to a no-op result.
  */
-export async function runMemoryInferencePass(config, sources, signal, db, reEnrich, onProgress, options = {}) {
+export async function runMemoryInferencePass(ctx) {
+    const { config, sources, signal, db, reEnrich, onProgress, options = {} } = ctx;
     const result = {
         considered: 0,
         cacheHits: 0,
+        retryAttempts: 0,
         splitParents: 0,
         writtenFacts: 0,
         skippedNoFacts: 0,
         skippedChildExists: 0,
         skippedAborted: 0,
         unaccounted: 0,
+        htmlErrorCount: 0,
     };
+    // Mutable sink threaded into compressMemoryToDerivedMemory so the per-call
+    // HTML-error categorization (which is otherwise swallowed inside the feature
+    // gate) bubbles up into the pass result.
+    const inferTelemetry = {};
     // Gate 1 — feature gate via isProcessEnabled, which reads the 0.8.0 path
     // (profiles.improve.default.processes.memoryInference.enabled). Defaults to
     // enabled when the key is absent.
@@ -79,6 +119,26 @@ export async function runMemoryInferencePass(config, sources, signal, db, reEnri
         // 2026-05-26).
         if (signal?.aborted)
             return { aborted: true };
+        // Pre-check (#588): when `<parent>.derived.md` is already on disk the
+        // inference is by definition complete — the parent only looks pending
+        // because `markParentProcessed` never ran (process killed between the
+        // child write and the mark) or the child was created externally (e.g.
+        // consolidation). Skip the LLM/cache call entirely and mark the parent
+        // so it never re-pends. Before this check, production measurements
+        // showed ~55% of the pass's LLM budget re-deriving such parents only to
+        // discover the existing child after the fact.
+        if (fs.existsSync(derivedChildPath(record))) {
+            markParentProcessed(record);
+            return {
+                skipped: false,
+                splitParent: false,
+                written: 0,
+                fromCache: false,
+                retryAttempts: 0,
+                childExists: true,
+                precheck: true,
+            };
+        }
         // Incremental cache: skip LLM call when body hash is unchanged and
         // --re-enrich was not requested. The cache ref is the absolute file path.
         const validate = (raw) => {
@@ -103,31 +163,58 @@ export async function runMemoryInferencePass(config, sources, signal, db, reEnri
         // the hit count separately so the operational yield rate
         // (writtenFacts / freshAttempts) is interpretable as the cache warms.
         let fromCache = false;
+        // Count single bounded retries for transient LLM failures on this
+        // candidate. Bumped via the `onRetryAttempt` callback threaded into
+        // `chatCompletion`; surfaced as `retryAttempts` telemetry, never as a
+        // failure for the same call.
+        let retryAttempts = 0;
+        const onRetryAttempt = () => {
+            retryAttempts += 1;
+        };
         const derived = db
             ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, () => memoryInfer.compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
                 warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
-            }), validate, undefined, "", {
+            }, inferTelemetry, onRetryAttempt), validate, undefined, "", {
                 onCacheHit: () => {
                     fromCache = true;
                 },
             })
             : await memoryInfer.compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
                 warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
-            });
+            }, inferTelemetry, onRetryAttempt);
         if (!derived) {
-            return { skipped: true, fromCache };
+            return { skipped: true, fromCache, retryAttempts };
         }
-        const written = await writeDerivedMemory(record, derived);
-        if (written > 0) {
+        const writeOutcome = await writeDerivedMemory(record, derived);
+        if (writeOutcome.written > 0) {
             markParentProcessed(record);
-            return { skipped: false, splitParent: true, written, fromCache };
+            return { skipped: false, splitParent: true, written: writeOutcome.written, fromCache, retryAttempts };
         }
         // LLM produced a valid derived draft but no file was written — either
-        // because `<parent>.derived.md` already exists on disk or
-        // `writeAssetToSource` threw. Categorise as `childExists` so the
-        // attempt is accounted for in health metrics rather than vanishing
-        // into the freshAttempts denominator.
-        return { skipped: false, splitParent: false, written: 0, fromCache, childExists: true };
+        // because `<parent>.derived.md` appeared on disk after the pre-check
+        // above (a rare mid-flight race) or `writeAssetToSource` threw.
+        // Categorise as `childExists` so the consumed attempt is accounted for
+        // in health metrics rather than vanishing into the freshAttempts
+        // denominator.
+        //
+        // When the child exists the inference is, by definition, complete — so
+        // mark the parent processed here too (#550), otherwise
+        // `isPendingMemory()` re-queues the same parent every run. A genuine
+        // write *failure* (`writeAssetToSource` threw) must NOT mark the parent
+        // — it should be retried next run — so we key off the explicit
+        // `childExists` outcome rather than the conflated `written === 0`.
+        if (writeOutcome.childExists) {
+            markParentProcessed(record);
+        }
+        return {
+            skipped: false,
+            splitParent: false,
+            written: 0,
+            fromCache,
+            retryAttempts,
+            childExists: true,
+            precheck: false,
+        };
     }, 
     // Default concurrency of 4 for cloud APIs. Set `llm.concurrency: 1`
     // in config.json for local model servers (LM Studio, Ollama).
@@ -151,6 +238,9 @@ export async function runMemoryInferencePass(config, sources, signal, db, reEnri
         if (res.fromCache) {
             result.cacheHits += 1;
         }
+        if ("retryAttempts" in res) {
+            result.retryAttempts += res.retryAttempts;
+        }
         if (res.skipped) {
             result.skippedNoFacts += 1;
             // Intentionally NOT marked processed — a transient LLM failure should
@@ -161,11 +251,16 @@ export async function runMemoryInferencePass(config, sources, signal, db, reEnri
             result.writtenFacts += res.written;
         }
         else if ("childExists" in res && res.childExists) {
-            // LLM call was consumed but the derived file already existed (or the
-            // write threw). Track separately so this category is observable in
-            // health output and stops bleeding into the freshAttempts denominator.
+            // Derived child already on disk. Track separately so this category is
+            // observable in health output and stops bleeding into the
+            // freshAttempts denominator. Pre-check skips (#588) are the routine
+            // self-healing path — no LLM attempt was consumed and the parent has
+            // been marked processed — so only the rare post-LLM case (mid-flight
+            // race or write failure) warrants a per-ref warning.
             result.skippedChildExists += 1;
-            warn(`memory inference: derived child for ${pending[i]?.ref ?? "<unknown>"} already existed or write failed; counted as skippedChildExists`);
+            if (!res.precheck) {
+                warn(`memory inference: derived child for ${pending[i]?.ref ?? "<unknown>"} already existed or write failed; counted as skippedChildExists`);
+            }
         }
         else {
             // The per-record state machine should cover every outcome. A hit here
@@ -183,6 +278,7 @@ export async function runMemoryInferencePass(config, sources, signal, db, reEnri
             currentRef: pending[i]?.ref,
         });
     }
+    result.htmlErrorCount = inferTelemetry.htmlErrorCount ?? 0;
     return result;
 }
 // ── Pending detection ───────────────────────────────────────────────────────
@@ -260,7 +356,14 @@ function toMemoryName(memoriesDir, filePath) {
     // user has organised under memories/.
     return rel.replace(/\\/g, "/").replace(/\.md$/i, "");
 }
-// ── Writing derived memories + marking parent ───────────────────────────────
+/**
+ * Absolute path of the derived child for a parent memory. Single source of
+ * truth for the `<parent>.derived.md` naming convention — used both by the
+ * pre-LLM existence check (#588) and the write path.
+ */
+function derivedChildPath(parent) {
+    return path.join(parent.stashRoot, "memories", `${parent.name}.derived.md`);
+}
 async function writeDerivedMemory(parent, derived) {
     const writeTarget = {
         kind: "filesystem",
@@ -275,19 +378,24 @@ async function writeDerivedMemory(parent, derived) {
     };
     const childName = `${parent.name}.derived`;
     const childRefStr = `memory:${childName}`;
-    const childPath = path.join(parent.stashRoot, "memories", `${childName}.md`);
-    if (fs.existsSync(childPath)) {
-        return 0;
+    if (fs.existsSync(derivedChildPath(parent))) {
+        // The derived child appeared on disk after the caller's pre-check (#588)
+        // — a rare mid-flight race. Report `childExists` so the caller marks the
+        // parent processed (#550) instead of re-queueing it forever.
+        return { written: 0, childExists: true };
     }
     try {
         const content = renderDerivedMemory(parent, derived);
         const childRef = parseAssetRef(childRefStr);
         await writeAssetToSource(writeTarget, writeConfig, childRef, content);
-        return 1;
+        return { written: 1, childExists: false };
     }
     catch (err) {
         warn(`memory inference: failed to write derived memory ${childName}: ${err instanceof Error ? err.message : String(err)}`);
-        return 0;
+        // A genuine write failure — the parent must remain pending so it is
+        // retried on the next run. `childExists: false` keeps it from being
+        // marked processed.
+        return { written: 0, childExists: false };
     }
 }
 function renderDerivedMemory(parent, derived) {

package/dist/indexer/{metadata-contributors.js → passes/metadata-contributors.js}

@@ -2,15 +2,17 @@
 // 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/.
 const contributors = [];
-let builtinsPromise;
+/**
+ * Ensure that all built-in indexer contributors are registered.
+ *
+ * Delegates to the single `initIndexer()` composition root (see
+ * `src/indexer/init.ts`). Imported dynamically to keep this a lazy gate and to
+ * avoid a static import cycle (init -> renderers -> metadata-contributors).
+ * Called on first use of getMetadataContributors; idempotent.
+ */
 async function ensureBuiltinMetadataContributorsRegistered() {
-    if (!builtinsPromise) {
-        builtinsPromise = (async () => {
-            await import("../output/renderers.js");
-            await import("../workflows/renderer.js");
-        })();
-    }
-    return builtinsPromise;
+    const { initIndexer } = await import("../init.js");
+    await initIndexer();
 }
 export function registerMetadataContributor(contributor) {
     contributors.push(contributor);

package/dist/indexer/{metadata.js → passes/metadata.js}

@@ -3,12 +3,12 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { deriveCanonicalAssetName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, } from "../core/asset-spec";
-import { asNonEmptyString, isAssetType, writeFileAtomic } from "../core/common";
-import { parseFrontmatter } from "../core/frontmatter";
-import { isVerbose, warn } from "../core/warn";
-import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
-import { applyMetadataContributors } from "./metadata-contributors";
+import { deriveCanonicalAssetName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, } from "../../core/asset/asset-spec.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { asNonEmptyString, isAssetType, writeFileAtomic } from "../../core/common.js";
+import { isVerbose, warn } from "../../core/warn.js";
+import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../walk/file-context.js";
+import { applyMetadataContributors } from "./metadata-contributors.js";
 export const SCOPE_KEYS = ["user", "agent", "run", "channel"];
 // ── Load / Write ────────────────────────────────────────────────────────────
 const STASH_FILENAME = ".stash.json";
@@ -480,18 +480,15 @@ export function shouldIndexStashFile(stashRoot, file, options) {
     const segments = relPath.split(/[\\/]+/).filter(Boolean);
     if (segments.length === 0)
         return true;
-    // Skip env / vault .env files that have a sibling .sensitive marker file.
-    if ((segments[0] === "env" || segments[0] === "vaults") &&
-        (file.endsWith(".env") || path.basename(file) === ".env")) {
+    // Skip env .env files that have a sibling .sensitive marker file.
+    if (segments[0] === "env" && (file.endsWith(".env") || path.basename(file) === ".env")) {
         const markerPath = file.replace(/\.env$/, ".sensitive");
         if (fs.existsSync(markerPath))
             return false;
     }
-    // Deprecation: once a stash has migrated to the `env/` directory, the legacy
-    // `vaults/` copy is frozen. Skip indexing it so the same keys are not
-    // double-surfaced under both `vault:` and `env:`. (Pre-migration stashes
-    // with no `env/` dir still index `vaults/` normally.)
-    if (segments[0] === "vaults" && fs.existsSync(path.join(stashRoot, "env"))) {
+    // The legacy `vaults/` directory (frozen copy left by the 0.8 migration) is
+    // never indexed — the `vault` asset type was removed in 0.9.0.
+    if (segments[0] === "vaults") {
         return false;
     }
     // Skip secret files that are themselves a `.sensitive` marker, or that have a
@@ -853,11 +850,10 @@ async function buildEntryFromFile(file, assetType, canonicalName, dirPath, pkgMe
         }
     }
     // Extract @param from script files.
-    // Env / vault files (.env) and secret files (whole-file secrets) are
-    // deliberately excluded — their contents are secrets and must never be
-    // parsed for @param or any other metadata that could embed a value into the
-    // entry.
-    if (ext !== ".md" && assetType !== "env" && assetType !== "vault" && assetType !== "secret") {
+    // Env files (.env) and secret files (whole-file secrets) are deliberately
+    // excluded — their contents are secrets and must never be parsed for @param
+    // or any other metadata that could embed a value into the entry.
+    if (ext !== ".md" && assetType !== "env" && assetType !== "secret") {
         const content = ctx.content();
         const scriptParams = extractScriptParameters(file, content);
         if (scriptParams)