akm-cli 0.9.17-alpha.8 → 0.9.17

package/dist/commands/proposal/validators/proposals.js

@@ -4,12 +4,21 @@
 /** Proposal validation and the one content repair applied before promotion. */
 import { repairTruncatedDescription } from "../../../core/text-truncation.js";
 import { splitFrontmatter } from "../../improve/reflect-noise.js";
+import { isRetireProposal } from "../proposal-types.js";
 import { runProposalValidators } from "./proposal-validators.js";
 /**
  * Validate a proposal before promotion: it must parse and carry a body, and a
  * type with a canonical validator runs it.
+ *
+ * A retire proposal (alpha.9 consolidate pair pass) writes no new content —
+ * it deletes an asset that already passed validation when IT was created —
+ * so the content-quality validators (built for new/updated bodies: a
+ * description, lesson shape, reflect size ratio, …) do not apply and are
+ * skipped entirely rather than misreading the empty body as a defect.
  */
 export function validateProposal(proposal) {
+    if (isRetireProposal(proposal))
+        return { ok: true, findings: [] };
     return runProposalValidators(proposal);
 }
 /**

package/dist/commands/read/knowledge.js

@@ -612,8 +612,9 @@ export async function writeMarkdownAsset(options) {
     // no longer trigger reindexes, so keeping the index current is the writer's
     // job. Demoted files reindex under their own containing root (usually the
     // write target itself; the working stash when writing to a --target) so
-    // `--belief current` filtering and the beliefState ranking demotion take
-    // effect without waiting for the next full index.
+    // `--belief current` filtering takes effect without waiting for the next
+    // full index. (alpha.4 removed belief weights from ranking; `--belief` is
+    // the only reader of `beliefState` today.)
     const demotedInTargetRoot = demotedByRoot.get(source.path) ?? [];
     demotedByRoot.delete(source.path);
     await indexWrittenAssets(source.path, [result.path, ...demotedInTargetRoot], { bundleId: resolved.ref.origin });

package/dist/commands/read/show.js

@@ -33,7 +33,6 @@ import { appendEvent } from "../../core/events.js";
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
 import { warn, warnOnce } from "../../core/warn.js";
-import { listRelatedPathsForFile } from "../../indexer/graph/graph-related.js";
 import { lookupBundleRef, lookupBundleRefWithResolution } from "../../indexer/indexer.js";
 import { projectMarkdownFragmentContent } from "../../indexer/passes/metadata.js";
 import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
@@ -384,19 +383,6 @@ export async function showLocal(input) {
         origin: source?.registryId ?? null,
         editable,
         ...(!editable ? { editHint: buildEditHint(canonicalRef) } : {}),
-        related: (() => {
-            try {
-                return withIndexDb((db) => {
-                    const related = listRelatedPathsForFile(sourceStashDir, assetPath, 5, db);
-                    return { total: related.length, hits: related };
-                });
-            }
-            catch (err) {
-                rethrowIfTestIsolationError(err);
-                rethrowIfDataDirUnreadable(err);
-                return { total: 0, hits: [] };
-            }
-        })(),
         ...showLinks(indexedEntry.itemRef, displayDefaultBundle),
     };
     const activeRun = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());

package/dist/commands/sources/info.js

@@ -1,30 +1,87 @@
 // 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 path from "node:path";
 import { placementTypes } from "../../core/asset/asset-placement.js";
 import { resolveStashDir } from "../../core/common.js";
-import { getSources, loadConfig } from "../../core/config/config.js";
+import { DEFAULT_CONFIG, getSources, loadConfig } from "../../core/config/config.js";
+import { ConfigError } from "../../core/errors.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
-import { getCacheDir, getConfigDir, getDataDir, getDbPath, getStateDir } from "../../core/paths.js";
+import { getCacheDir, getConfigDir, getDataDir, getDefaultStashDir, getStateDir } from "../../core/paths.js";
 import { formatRegistryUrl } from "../../core/registry-url.js";
 import { error } from "../../core/warn.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getEntryCount, getEntryCountByType } from "../../storage/repositories/index-entries-repository.js";
 import { countLinksByKind } from "../../storage/repositories/index-links-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
+import { isSqliteContentionError } from "../../storage/sqlite-transaction.js";
 import { pkgVersion } from "../../version.js";
+/**
+ * Bound for `akm info`'s diagnostic index.db read — short enough that a
+ * locked database never stalls the command, unlike the shared 30s
+ * `SQLITE_BUSY_TIMEOUT_MS` every write-capable opener uses. The opener's own
+ * layout check (`checkIndexLayout`) swallows a busy error on its one SELECT
+ * rather than surfacing it, so a genuinely locked database costs this
+ * timeout TWICE before the first real query here (`countLinksByKind`)
+ * throws for real — 750ms keeps that ~1.5s worst case well clear of the 3s
+ * bound integration tests hold this to, on a loaded CI box.
+ */
+const INFO_INDEX_BUSY_TIMEOUT_MS = 750;
 /**
  * Assemble system info describing the current capabilities, configuration,
- * and index state. Used by `akm info`.
+ * and index state. Used by `akm info`, which must behave like a help
+ * command (owner ruling): always print a report and exit 0, whatever else
+ * is happening. Every section below is read best-effort, so one failing
+ * lookup degrades only its own field(s) instead of the whole report;
+ * `infoCommand` itself (stash-cli.ts) wraps this whole call as the final
+ * backstop for anything left over — e.g. a path resolver that needs an
+ * environment variable nothing here sets, such as `HOME`.
  *
  * @param options.dbPath - Override the database path (useful for testing)
  */
 export function assembleInfo(options) {
-    const config = loadConfig();
+    let config;
+    let configError;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        config = DEFAULT_CONFIG;
+        configError = err instanceof Error ? err.message : String(err);
+    }
     // Primary stash directory + default bundle name — same resolution
     // `akm sources list` uses (R-057), so `akm info` and `akm sources list`
-    // agree on which stash is primary.
-    const stashDir = resolveStashDir();
+    // agree on which stash is primary. No bundle created yet
+    // (STASH_DIR_NOT_FOUND, the ordinary fresh-install state) reports where a
+    // fresh `akm setup`/`akm bundle create` would put it, same as "report the
+    // defaults" for a missing config — no error needed, nothing is actually
+    // wrong. A bundle that WAS configured (an env override or `bundles.*` in
+    // config) but doesn't resolve (STASH_DIR_UNREADABLE/STASH_DIR_NOT_A_DIRECTORY)
+    // is different: the fallback path is a courtesy, not a way to hide a
+    // genuine misconfiguration, so that reason is kept in `bundleDirError`.
+    let stashDir;
+    let bundleDirError;
+    try {
+        stashDir = resolveStashDir();
+    }
+    catch (err) {
+        if (!(err instanceof ConfigError) || err.code !== "STASH_DIR_NOT_FOUND") {
+            bundleDirError = err instanceof Error ? err.message : String(err);
+        }
+        // The fallback itself resolves purely from `HOME` (or its platform
+        // equivalent) and can throw the exact same way `resolveStashDir()` can
+        // (e.g. HOME entirely unset) — guarded so a blank `bundleDir` (never a
+        // throw) still always carries a reason, reusing the one above when the
+        // outer catch already set it (a configured-but-broken path takes
+        // precedence over restating "and the default isn't resolvable either").
+        try {
+            stashDir = getDefaultStashDir();
+        }
+        catch (fallbackErr) {
+            stashDir = "";
+            bundleDirError ??= fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr);
+        }
+    }
     const defaultBundle = config.defaultBundle ?? null;
     // Asset types (copy into a mutable array — `placementTypes()` returns readonly)
     const assetTypes = [...placementTypes()];
@@ -45,11 +102,29 @@ export function assembleInfo(options) {
         ...(s.url ? { url: s.url } : {}),
         ...(s.enabled !== undefined ? { enabled: s.enabled } : {}),
     }));
-    // Index stats — `options.dbPath` is a test-only override (see the param
-    // doc above); real callers fall through to the same `getDbPath()` that
-    // health and search use, so info reads the same database they do.
-    const resolvedDbPath = options?.dbPath ?? getDbPath();
-    const indexStats = readIndexStats(resolvedDbPath);
+    // Data directory. `getDataDir()` can itself throw (e.g. TEST_ISOLATION_MISSING
+    // when NODE_ENV=test leaks into a real invocation — a JS test runner's
+    // child process — with no XDG_DATA_HOME/AKM_DATA_DIR override), caught
+    // here so that failure degrades only `dataDir`/`indexStats` rather than
+    // the whole report. Always attempted, even when `options.dbPath` (a
+    // test-only override, see the param doc above) means it is not needed to
+    // resolve the index path below — `dataDir` is its own reported field.
+    let dataDir = "";
+    let dataDirError;
+    try {
+        dataDir = getDataDir();
+    }
+    catch (err) {
+        dataDirError = err instanceof Error ? err.message : String(err);
+    }
+    // Index stats. `options.dbPath` overrides the resolved path outright;
+    // otherwise it is derived from `dataDir` above, so a data dir that failed
+    // to resolve degrades index stats the same way rather than retrying (and
+    // re-throwing) `getDataDir()` a second time.
+    const resolvedDbPath = options?.dbPath ?? (dataDir ? path.join(dataDir, "index.db") : undefined);
+    const indexStats = resolvedDbPath
+        ? readIndexStats(resolvedDbPath)
+        : { entryCount: 0, byType: {}, lastBuiltAt: null, hasEmbeddings: false, unavailable: dataDirError };
     // Semantic status is read live from the index's own state, not a cached
     // verdict — a failed embed attempt at search time falls back to FTS and
     // reports that in the search response, it never disables the mode here.
@@ -63,10 +138,12 @@ export function assembleInfo(options) {
         version: pkgVersion,
         bundleDir: stashDir,
         defaultBundle,
-        dataDir: getDataDir(),
-        configDir: getConfigDir(),
-        cacheDir: getCacheDir(),
-        stateDir: getStateDir(),
+        ...(configError ? { configError } : {}),
+        ...(bundleDirError ? { bundleDirError } : {}),
+        dataDir,
+        configDir: safePath(getConfigDir),
+        cacheDir: safePath(getCacheDir),
+        stateDir: safePath(getStateDir),
         assetTypes,
         searchModes,
         semanticSearch: {
@@ -78,6 +155,15 @@ export function assembleInfo(options) {
         indexStats,
     };
 }
+/** Best-effort path resolution for a section that must degrade, not throw: an empty string in place of an exception. */
+function safePath(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return "";
+    }
+}
 function readIndexStats(resolvedPath) {
     const EMPTY = {
         entryCount: 0,
@@ -99,7 +185,15 @@ function readIndexStats(resolvedPath) {
     }
     let db;
     try {
-        db = openExistingDatabase(resolvedPath);
+        // Never writes the index — no schema or journal-mode change — and
+        // bounded to INFO_INDEX_BUSY_TIMEOUT_MS rather than the shared 30s
+        // busy_timeout every write-capable opener uses. A newer index layout is
+        // reported below rather than refused (checkIndexLayout throws); an
+        // older layout just warns and is served as-is, never migrated — both
+        // already true of this opener.
+        db = openReadonlyExistingDatabase(resolvedPath, { busyTimeoutMs: INFO_INDEX_BUSY_TIMEOUT_MS });
+        if (!db)
+            return EMPTY; // raced away (deleted) between the access check above and here
         const links = countLinksByKind(db);
         return {
             entryCount: getEntryCount(db),
@@ -115,7 +209,7 @@ function readIndexStats(resolvedPath) {
         // Routed through core/warn's `error()` (not a raw process.stderr.write)
         // so `--quiet`/`setQuiet()` actually gate this line (R-057).
         error(`[akm info] failed to read index stats from ${resolvedPath}: ${String(err)}`);
-        return EMPTY;
+        return { ...EMPTY, unavailable: describeIndexReadFailure(err) };
     }
     finally {
         if (db) {
@@ -128,3 +222,13 @@ function readIndexStats(resolvedPath) {
         }
     }
 }
+/**
+ * Reason for `indexStats.unavailable`. Contention gets its own clear
+ * wording; everything else (a too-new layout, on-disk corruption, ...) is
+ * already descriptive as the driver/opener's own message.
+ */
+function describeIndexReadFailure(err) {
+    if (isSqliteContentionError(err))
+        return "index.db is locked by another akm process";
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/commands/sources/stash-cli.js

@@ -33,6 +33,7 @@ import * as p from "../../cli/clack.js";
 import { getParsedInvocation } from "../../cli/invocation.js";
 import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
+import { placementTypes } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { isHttpUrl, resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
@@ -45,6 +46,7 @@ import { resolveWriteTarget } from "../../core/write-source.js";
 import { releaseIndexRebuildLock, tryAcquireIndexRebuildLock } from "../../indexer/index-rebuild-lock.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { getHyphenatedBoolean, getOutputMode } from "../../output/context.js";
+import { pkgVersion } from "../../version.js";
 import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
 /** Matches the high-frequency per-committed-batch progress line (#954), excluded from non-verbose JSON-mode stderr. */
@@ -83,10 +85,10 @@ export const indexCommand = defineCommand({
     async run({ args }) {
         await runWithJsonErrors(async () => {
             if (getHyphenatedBoolean(args, "enrich") || getParsedInvocation().getFlagValue("--enrich") !== undefined) {
-                throw new UsageError("`akm index --enrich` has been removed. Plain `akm index` now performs metadata enrichment by default.");
+                throw new UsageError("`akm index --enrich` has been removed. Metadata enrichment during indexing is retired; it never runs.");
             }
             if (getHyphenatedBoolean(args, "re-enrich") || getParsedInvocation().getFlagValue("--re-enrich") !== undefined) {
-                throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
+                throw new UsageError("`akm index --re-enrich` has been removed. Metadata enrichment during indexing is retired; there is nothing to re-enrich.");
             }
             // #956: opt-in, non-blocking rebuild lock — never gates a human-typed
             // `akm index` (it only warns and contends), but a scheduled/opportunistic
@@ -181,7 +183,25 @@ export const indexCommand = defineCommand({
 export const infoCommand = defineJsonCommand({
     meta: { name: "info", description: "Show system capabilities, configuration, and index stats" },
     run() {
-        const result = assembleInfo();
+        // `akm info` must behave like a help command: always exit 0 with a
+        // report. `assembleInfo()` already degrades what it reasonably can
+        // per-section; this is the final backstop for whatever it can't (e.g.
+        // every path resolver needs an environment variable, such as `HOME`,
+        // that this process genuinely does not have) — still a report, with
+        // whatever is cheap and safe enough to never itself throw.
+        let result;
+        try {
+            result = assembleInfo();
+        }
+        catch (err) {
+            result = {
+                schemaVersion: 1,
+                version: pkgVersion,
+                error: err instanceof Error ? err.message : String(err),
+                assetTypes: [...placementTypes()],
+                searchModes: ["fts"],
+            };
+        }
         output("info", result);
     },
 });

package/dist/core/bundle-rename.js

@@ -30,7 +30,6 @@ import fs from "node:fs";
 import { readLockfile, renameLockEntry } from "../integrations/lockfile.js";
 import { closeDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
 import { getFilePathsByBundle, renameEntriesBundleId } from "../storage/repositories/index-entries-repository.js";
-import { renameLlmCacheAssetRefs } from "../storage/repositories/index-llm-cache-repository.js";
 import { countProposalsForBundleRename, renameProposalsBundleRef } from "../storage/repositories/proposals-repository.js";
 import { countTaskHistoryTargetRefs, renameTaskHistoryTargetRefs, } from "../storage/repositories/task-history-repository.js";
 import { selectBackend } from "../tasks/backends/index.js";
@@ -243,18 +242,13 @@ export async function renameBundle(oldId, newId, options = {}, deps) {
     // e.g. a plain filesystem bundle).
     await renameLockEntry(oldId, newId);
     // Index: bundle_id/item_ref on every entry row (see index-entries-repository's
-    // renameEntriesBundleId docstring for why no FTS/vector rebuild is needed),
-    // and the metadata-enrichment LLM cache keyed by the same canonical
-    // item_ref — in the SAME write, so a rename can never land between the two
-    // and leave the cache stranded under the old prefix (the next `akm index`'s
-    // clearStaleCacheEntries would then delete it, forcing a full re-enrich).
+    // renameEntriesBundleId docstring for why no FTS/vector rebuild is needed).
     const readIndexDb = openReadonlyExistingDatabase(getDbPath());
     if (readIndexDb) {
         closeDatabase(readIndexDb);
         const writeIndexDb = openIndexDatabase(getDbPath());
         try {
             renameEntriesBundleId(writeIndexDb, oldId, newId);
-            renameLlmCacheAssetRefs(writeIndexDb, oldId, newId);
         }
         finally {
             closeDatabase(writeIndexDb);

package/dist/core/config/config-schema.js

@@ -60,7 +60,7 @@ export { EngineConfigSchema, EnginesSchema, LlmConnectionConfigSchema, LlmProfil
 export { ExperimentalConfigSchema } from "./schema/experimental.js";
 export { FEEDBACK_FAILURE_MODES, FeedbackConfigSchema } from "./schema/feedback.js";
 export { ImproveConfigSchema } from "./schema/improve.js";
-export { ConsolidateProcessConfigSchema, DistillProcessConfigSchema, ExtractProcessConfigSchema, GraphExtractionProcessConfigSchema, ImproveProcessConfigSchema, ImproveProfileConfigSchema, MemoryInferenceProcessConfigSchema, ProactiveMaintenanceProcessConfigSchema, ReflectProcessConfigSchema, TriageProcessConfigSchema, ValidationProcessConfigSchema, } from "./schema/improve-processes.js";
+export { ConsolidateProcessConfigSchema, DistillProcessConfigSchema, ExtractProcessConfigSchema, ImproveProcessConfigSchema, ImproveProfileConfigSchema, MemoryInferenceProcessConfigSchema, ProactiveMaintenanceProcessConfigSchema, ReflectProcessConfigSchema, TriageProcessConfigSchema, ValidationProcessConfigSchema, } from "./schema/improve-processes.js";
 export { IndexConfigSchema, IndexPassConfigSchema } from "./schema/index-config.js";
 export { OutputConfigSchema } from "./schema/output.js";
 export { CURRENT_CONFIG_VERSION, LlmInvocationOverridesSchema } from "./schema/primitives.js";
@@ -240,6 +240,13 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
     }
     const defaultStrategy = config.defaults?.improveStrategy;
     if (defaultStrategy &&
+        // graph-refresh is exempt from this eager, config-load-time check: unlike
+        // a plain typo, it is a specific, known retirement, and refusing it here
+        // would fail every command's config load (including `akm migrate apply`,
+        // the one that fixes this). `resolveImproveStrategy`
+        // (src/commands/improve/improve-strategies.ts) refuses it lazily, at
+        // improve-invocation time, with the same message either way.
+        defaultStrategy !== "graph-refresh" &&
         !BUILTIN_IMPROVE_STRATEGY_NAMES.includes(defaultStrategy) &&
         !config.improve?.strategies?.[defaultStrategy]) {
         ctx.addIssue({

package/dist/core/config/config.js

@@ -27,36 +27,6 @@ export { VALID_HARNESS_IDS } from "./config-types.js";
 // Canonical taxonomy lives in the schema/validator layer; re-exported here so
 // existing `../core/config/config` import sites keep working.
 export { FEEDBACK_FAILURE_MODES } from "./config-schema.js";
-/**
- * Default value for {@link IndexPassConfig.graphExtractionBatchSize}. Chosen
- * empirically: 4 amortises the per-call HTTP overhead 4× while keeping the
- * combined prompt size well under common 8K/16K context windows (each body is
- * sliced to ~500 chars in the graph-extract prompt builder).
- */
-const DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE = 4;
-/**
- * Approximate character budget per asset body inside a batched
- * graph-extraction prompt — used by {@link resolveBatchSize} to derive a
- * context-window ceiling when `llm.contextLength` is configured. This accounts
- * for the actual `MAX_BODY_CHARS` (500) in graph-extract.ts plus the system
- * prompt, user prompt wrapper, and expected JSON response overhead.
- */
-const GRAPH_EXTRACTION_CHARS_PER_BODY = 1500;
-/**
- * Clamp a configured batch size against the model's known context window.
- *
- * `configured` defaults to {@link DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE} when
- * `undefined`. When `contextLength` is provided, the result is the smaller of
- * `configured` and `floor(contextLength / GRAPH_EXTRACTION_CHARS_PER_BODY)`,
- * with a floor of 1 so the batched path always processes at least one body.
- */
-export function resolveBatchSize(configured, contextLength) {
-    const base = configured && configured > 0 ? configured : DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE;
-    if (!contextLength || contextLength <= 0)
-        return base;
-    const ceiling = Math.max(1, Math.floor(contextLength / GRAPH_EXTRACTION_CHARS_PER_BODY));
-    return Math.max(1, Math.min(base, ceiling));
-}
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     configVersion: "0.9.0",
@@ -210,6 +180,18 @@ function buildEffectiveConfig(liftedLocalRaw, sourcePath) {
     assertUniquePhysicalBundleRoots(finalResult.data, sourcePath);
     return finalResult.data;
 }
+/**
+ * Retired `index.<passName>` keys that still validate against the generic
+ * per-pass catchall schema (`IndexPassConfigSchema`), so `resolveSchemaAt`
+ * below never returns `undefined` for them and the walk would otherwise
+ * treat them as a live, ordinary pass. Named here so the same three
+ * guarantees apply as any other retired config key (AGENTS.md "Reading
+ * persisted data"): a config setting one keeps loading, is named once by
+ * the unknown-key warning, and is dropped only by `akm migrate apply`.
+ * Both were retired in 0.9.17-alpha.9: `index.graph` (the LLM entity-graph
+ * extraction pass) and `index.metadataEnhance` (LLM metadata enrichment).
+ */
+const RETIRED_CATCHALL_KEY_PATHS = new Set(["index.graph", "index.metadataEnhance"]);
 /**
  * Every dotted key in `raw` the schema does not know, at any depth (arrays
  * are not descended). Unknown keys are never an error: they are a typo, or a
@@ -221,7 +203,7 @@ export function unknownConfigKeyPaths(root, node = root, prefix = []) {
     const found = [];
     for (const key of Object.keys(node).sort()) {
         const keyPath = [...prefix, key];
-        if (resolveSchemaAt(keyPath, root) === undefined) {
+        if (RETIRED_CATCHALL_KEY_PATHS.has(keyPath.join(".")) || resolveSchemaAt(keyPath, root) === undefined) {
             found.push(keyPath);
             continue;
         }
@@ -695,6 +677,16 @@ export function normalizeConfigFile(configPath, options) {
         const body = withSchedulerOnDisk(configWriteBody(localRaw, current, next), next);
         for (const keyPath of unknownConfigKeyPaths(body))
             deleteConfigPath(body, keyPath);
+        // `improve.strategies["graph-refresh"]` is schema-valid (any name is a
+        // legal custom-strategy key), so it never reaches the unknown-key sweep
+        // above. It can only be a leftover override of the deleted graph-refresh
+        // built-in (0.9.17-alpha.9) — resolveImproveStrategy now refuses that
+        // name unconditionally, so the override can never apply again. Drop it
+        // the same way any other retired key is dropped: only by `akm migrate
+        // apply`, never by an ordinary write.
+        const strategies = body.improve?.strategies;
+        if (strategies && Object.hasOwn(strategies, "graph-refresh"))
+            delete strategies["graph-refresh"];
         const keys = [...new Set([...Object.keys(raw), ...Object.keys(body)])]
             .filter((key) => JSON.stringify(raw[key]) !== JSON.stringify(body[key]))
             .sort();
@@ -928,23 +920,6 @@ export function resolveSecret(value, resolveFromStore) {
         return resolved ?? "";
     });
 }
-/**
- * Read a per-pass {@link IndexPassConfig} entry from {@link IndexConfig},
- * filtering out the reserved feature-section keys so callers don't mistake
- * `metadataEnhance` for a pass.
- */
-/** Reserved well-known keys on IndexConfig that are NOT per-pass entries. */
-const INDEX_RESERVED_KEYS = new Set(["metadataEnhance"]);
-export function getIndexPassConfig(config, passName) {
-    if (!config)
-        return undefined;
-    if (INDEX_RESERVED_KEYS.has(passName))
-        return undefined;
-    const entry = config[passName];
-    if (!entry || typeof entry !== "object")
-        return undefined;
-    return entry;
-}
 // Re-export source runtime helpers — implementation lives in config-sources.ts.
 export { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundleEntryToSourceEntry, bundleKeyForContentRoot, bundlePhysicalContentRoot, bundleSourceId, bundlesToSourceEntries, installedSourceDescriptor, isBundleEnabled, parseSourceSpec, primaryBundlePath, resolveActiveConfiguredSources, resolveConfiguredSources, } from "./config-sources.js";
 /**

package/dist/core/config/engine-semantics.js

@@ -6,7 +6,6 @@ export const BUILTIN_IMPROVE_STRATEGY_NAMES = [
     "default",
     "quick",
     "thorough",
-    "graph-refresh",
     "consolidate",
     "catchup",
     "reflect-distill",
@@ -18,7 +17,6 @@ export const IMPROVE_PROCESS_ENGINE_CAPABILITIES = {
     distill: "llm",
     consolidate: "llm",
     memoryInference: "llm",
-    graphExtraction: "llm",
     extract: "llm",
     validation: "llm",
     triage: "runner",

package/dist/core/config/schema/improve-processes.js

@@ -10,13 +10,14 @@ import { IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "../engine-semantics.js";
 import { engineName, LlmInvocationOverridesSchema, nonEmptyString, positiveInt } from "./primitives.js";
 // ── Improve profile / process ──────────────────────────────────────────────
 //
-// WI-9.6 (§4.2/§10.2): each of the 9 improve processes (reflect, distill,
-// consolidate, memoryInference, graphExtraction, extract, validation, triage,
-// proactiveMaintenance) gets its OWN schema below — a shared base (engine,
-// model, llm, enabled, timeoutMs) extended with only the fields meaningful on
-// that process — replacing the prior single ImproveProcessConfigSchema reused
-// via `.optional()` for all 9 keys (which accepted, and silently ignored, any
-// field on any process). Field→process assignment is derived from each
+// WI-9.6 (§4.2/§10.2): each of the improve processes (reflect, distill,
+// consolidate, memoryInference, extract, validation, triage,
+// proactiveMaintenance — graphExtraction had one too, until the LLM
+// entity-graph it ran was retired in 0.9.17-alpha.9) gets its OWN schema
+// below — a shared base (engine, model, llm, enabled, timeoutMs) extended
+// with only the fields meaningful on that process — replacing the prior
+// single ImproveProcessConfigSchema reused via `.optional()` for all of them
+// (which accepted, and silently ignored, any field on any process). Field→process assignment is derived from each
 // field's original "only meaningful on X" doc comment, cross-checked against
 // its actual runtime consumers and the built-in strategy assets
 // (src/assets/improve-strategies/*.json).
@@ -164,12 +165,6 @@ const CONSOLIDATE_PROCESS_FIELDS = {
     // entirely (emits `pool_below_min_size`). 0 disables the guard. Default 500.
     minPoolSize: z.number().int().min(0).optional(),
     maxChunkSize: z.number().int().min(1).max(50).optional(),
-    // Narrow candidate pool to memories modified within this duration window
-    // plus their graph neighbours. Absent = full-pool sweep.
-    incrementalSince: z.string().optional(),
-    // Graph neighbours per changed memory during incremental consolidation.
-    // Default 5. Only meaningful with incrementalSince.
-    neighborsPerChanged: z.number().int().min(1).optional(),
     // Fallback p90 wall-clock time per consolidation chunk in seconds, used for
     // cold-start budget estimation when no telemetry history exists. The actual
     // p90 is derived from observed run durations once sufficient history
@@ -182,29 +177,6 @@ const MEMORY_INFERENCE_PROCESS_FIELDS = {
     minPendingCount: z.number().int().min(0).optional(),
     cls: clsField,
 };
-/**
- * GraphExtraction process fields: one strategy's graph extraction scope and
- * batching. `includeTypes` and `batchSize` override `index.graph`'s
- * `graphExtractionIncludeTypes` and `graphExtractionBatchSize`; unset, the
- * pass reads those.
- */
-const GRAPH_EXTRACTION_PROCESS_FIELDS = {
-    // #624 P2: when set, rank eligible files by utility_scores DESC and process
-    // only the top-N per run (incremental high-signal-first sweep). Unset =
-    // process all eligible (current behavior).
-    topN: positiveInt.optional(),
-    includeTypes: z.array(z.string().min(1)).min(1).optional(),
-    batchSize: positiveInt.optional(),
-    // Full-corpus scan. When true, graph extraction runs on ALL stash files
-    // instead of only files touched by actionable refs in the current run.
-    // Used by the `graph-refresh` built-in profile / a scheduled weekly task.
-    fullScan: z.boolean().optional(),
-    // R12b + R20: cap on chunks processed per asset. A body chunked beyond this
-    // is truncated to the first N chunks instead of paying for unbounded
-    // per-asset LLM calls; the coverage loss is recorded as truncatedChunks.
-    // Absent = default 8 (src/llm/graph-extract.ts DEFAULT_MAX_CHUNKS_PER_ASSET).
-    maxChunksPerAsset: positiveInt.optional(),
-};
 const EXTRACT_PROCESS_FIELDS = {
     defaultSince: z.string().min(1).optional(),
     maxTotalChars: positiveInt.optional(),
@@ -264,7 +236,6 @@ export const ImproveProcessConfigSchema = z
     ...DISTILL_PROCESS_FIELDS,
     ...CONSOLIDATE_PROCESS_FIELDS,
     ...MEMORY_INFERENCE_PROCESS_FIELDS,
-    ...GRAPH_EXTRACTION_PROCESS_FIELDS,
     ...EXTRACT_PROCESS_FIELDS,
     ...TRIAGE_PROCESS_FIELDS,
     ...PROACTIVE_MAINTENANCE_PROCESS_FIELDS,
@@ -288,10 +259,6 @@ export const ConsolidateProcessConfigSchema = z
 export const MemoryInferenceProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...MEMORY_INFERENCE_PROCESS_FIELDS })
     .passthrough();
-/** `processes.graphExtraction` — narrow per-process schema (WI-9.6). */
-export const GraphExtractionProcessConfigSchema = z
-    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...GRAPH_EXTRACTION_PROCESS_FIELDS })
-    .passthrough();
 /** `processes.extract` — narrow per-process schema (WI-9.6). */
 export const ExtractProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...EXTRACT_PROCESS_FIELDS })
@@ -306,13 +273,20 @@ export const TriageProcessConfigSchema = z
 export const ProactiveMaintenanceProcessConfigSchema = z
     .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...PROACTIVE_MAINTENANCE_PROCESS_FIELDS })
     .passthrough();
+/**
+ * Process names that once had a dedicated schema and are now gone. Setting
+ * one, even with `enabled: true`, is tolerated rather than rejected by the
+ * "unknown enabled process" check below — an old config must keep loading
+ * (AGENTS.md "Reading persisted data"). `graphExtraction`: the LLM
+ * entity-graph extraction it ran was retired in 0.9.17-alpha.9.
+ */
+const RETIRED_PROCESS_NAMES = new Set(["graphExtraction"]);
 const ImproveProfileProcessesSchema = z
     .object({
     reflect: ReflectProcessConfigSchema.optional(),
     distill: DistillProcessConfigSchema.optional(),
     consolidate: ConsolidateProcessConfigSchema.optional(),
     memoryInference: MemoryInferenceProcessConfigSchema.optional(),
-    graphExtraction: GraphExtractionProcessConfigSchema.optional(),
     extract: ExtractProcessConfigSchema.optional(),
     validation: ValidationProcessConfigSchema.optional(),
     triage: TriageProcessConfigSchema.optional(),
@@ -335,6 +309,7 @@ const ImproveProfileProcessesSchema = z
     }
     for (const [name, process] of Object.entries(val)) {
         if (!(name in IMPROVE_PROCESS_ENGINE_CAPABILITIES) &&
+            !RETIRED_PROCESS_NAMES.has(name) &&
             process !== null &&
             typeof process === "object" &&
             process.enabled === true) {