akm-cli 0.9.15-beta.4 → 0.9.15-beta.5

package/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.9.15-beta.4] - 2026-09-10
+## [0.9.15-beta.5] - 2026-09-10
 
 ### Added
 
@@ -159,6 +159,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   (#951).** These are akm's resolved data/config/cache/state directories, so a
   script can read `akm info --format json | jq -r .dataDir` instead of hardcoding
   a path that differs between a host install and a container.
+- **A real `curate_rerank` implementation: `search.curateRerank`, a cross-
+  encoder rerank pass over `akm curate`'s already-selected candidates (#951).**
+  `curate_rerank` was a dead `llm.features.*` key removed in 0.8.0 with no wire
+  call ever implemented under it. `search.curateRerank.{enabled, endpoint,
+  model, apiKey, timeoutMs, topN}` configures a standalone `/rerank`-style
+  endpoint (`src/llm/rerank-client.ts`, `POST {model, query, documents}` →
+  `{results: [{index, relevance_score}]}`); when enabled, curate sends its top
+  `topN` (default 8) already-ranked candidates and reorders them by the
+  endpoint's scores. Disabled by default, and best-effort like every other
+  bounded LLM feature: a misconfigured endpoint, network failure, timeout, or
+  malformed response falls back to curate's own ranking unchanged rather than
+  failing the command. Deliberately its own config arm rather than a third
+  `engines` kind alongside `"llm"`/`"agent"` — that union's kinds are
+  load-bearing through execution-lowering, runner dispatch, and the harness
+  model map, none of which a reranker touches.
+- **Per-run task log files are purged past the retention window (#951).**
+  `tasks/logs/<taskId>/<timestamp>.log` (the per-run human-readable tail;
+  `logs.db` is the durable, already-purged record) had file separation but no
+  cleanup, so old run files accumulated forever. `akm improve`'s existing
+  retention pass now also deletes `.log` files under `getTaskLogDir()` older
+  than the same `improve.eventRetentionDays` window (default 90d, `0` disables
+  it) it already uses for `task_logs`/events/`improve_runs` — bounded to that
+  one directory, one level of `<taskId>` subdirectories, `.log` files only.
+  Path-agnostic bundled scripts and the `akm show env/<name>`/`akm task list`
+  items from the same review were previously confirmed shipped and are
+  unchanged here.
 - **`akm index --reembed` forces a full re-embed (#955).** Bypasses the
   compatibility check above entirely and purges + regenerates every stored
   embedding, for the rare case where the check's verdict should not be trusted. A
@@ -477,6 +503,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **An alias-level `engine` binding in `models.json` is honoured on every
+  platform column (#946).** The per-platform nested form
+  (`"fast": {"opencode": {"engine": "local-fast"}}`) already worked, but the
+  flat shorthand from this issue's own acceptance criteria
+  (`"fast": {"engine": "local-fast"}`) did not: `parseModelMapLayer` treated
+  every key under an alias as a platform-column name, so `engine` was parsed
+  as a fourth platform holding the model string, the three real columns kept
+  their hardcoded cloud defaults, and `akm agent --model fast` silently
+  dispatched to a cloud model instead of the configured local engine. The
+  flat `model`/`inference`/`engine` keys are now a wildcard default merged
+  onto every column, a same-alias per-platform entry still overrides it, and
+  an alias naming an unknown engine fails with a `ConfigError` rather than
+  falling back.
+- **Two `improve` runs colliding on the lock is transient, not a broken
+  config (#948).** The lock-held path threw a `ConfigError`, surfacing as
+  exit 78 (`INVALID_CONFIG_FILE`) and telling a supervisor to stop retrying
+  an ordinary collision. It is now a `TransientError`/`IMPROVE_LOCK_HELD` at
+  exit 75, matching the `MAINTENANCE_BARRIER_BUSY`/`INDEX_DB_CONTENDED`
+  treatment the index rebuild lock already had.
+- **The embedding path no longer leaks a raw `database is locked` (#956).**
+  `reclassifyIndexDbContention` moved out of `indexer.ts` into a shared
+  module and `materialize-embeddings.ts`'s embedding-generation catch now
+  routes through it, so contention produces the same "index database is
+  busy" wording as every other path instead of the raw driver string.
+  Control flow is unchanged: this was always non-fatal.
+
 - **Starting a workflow ref that already has an active run in a different scope
   now warns instead of silently duplicating it (#942).** `akm workflow run
   <ref>`'s per-scope concurrency guard is unchanged by design — two unrelated

package/dist/commands/improve/locks.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 path from "node:path";
-import { ConfigError } from "../../core/errors.js";
+import { TransientError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { releaseLock } from "../../core/file-lock.js";
 import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../../core/maintenance-barrier.js";
@@ -65,7 +65,14 @@ function tryAcquireImproveLockUnlocked(lockPath, skipIfLocked, onRecovered) {
         warn(`[improve] another improve run holds the lock (PID ${pid}, started ${startedAt}); skipping (--skip-if-locked)`);
         return { state: "skipped" };
     }
-    throw new ConfigError(`akm improve is already running (PID ${pid}, started ${startedAt}). Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
+    // #948 field follow-up: two legitimate `improve` invocations colliding on
+    // this lock is ordinary, retryable contention — not a broken config file.
+    // A `ConfigError` here surfaced as exit 78 (INVALID_CONFIG_FILE) and told
+    // a supervisor to stop retrying a normal lock collision. Reclassified to
+    // `TransientError`/`IMPROVE_LOCK_HELD` (exit 75), mirroring the
+    // `MAINTENANCE_BARRIER_BUSY`/`INDEX_DB_CONTENDED` treatment #956 already
+    // applied to the index rebuild lock and the maintenance-start barrier.
+    throw new TransientError(`akm improve is already running (PID ${pid}, started ${startedAt}). Delete ${lockPath} to force.`, "IMPROVE_LOCK_HELD");
 }
 export function releaseImproveLock(ownership) {
     releaseLock(ownership);

package/dist/commands/improve/loop-stages.js

@@ -9,7 +9,7 @@ import { DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE, loadConfig } from "../../core/conf
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { openLogsDatabase, purgeOldTaskLogs } from "../../core/logs-db.js";
-import { getDbPath } from "../../core/paths.js";
+import { getDbPath, getTaskLogDir } from "../../core/paths.js";
 import { withStateDb } from "../../core/state-db.js";
 import { info } from "../../core/warn.js";
 import { DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES, runGraphExtractionPass, } from "../../indexer/graph/graph-extraction.js";
@@ -25,6 +25,7 @@ import { closeDatabase, openIndexDatabase } from "../../storage/repositories/ind
 import { getEntryByRef } from "../../storage/repositories/index-entries-repository.js";
 import { clearAssetOutcomeMissing, countAssetOutcomeMissing, deleteAssetOutcomeMissingBefore, listAssetOutcomeMissingState, stampAssetOutcomeMissing, } from "../../storage/repositories/outcome-repository.js";
 import { clearAssetSalienceMissing, countAssetSalienceMissing, deleteAssetSalienceMissingBefore, listAssetSalienceMissingState, stampAssetSalienceMissing, } from "../../storage/repositories/salience-repository.js";
+import { purgeOldTaskLogFiles } from "../../tasks/run/task-log.js";
 import { expireStaleProposals, listProposals, purgeOrphanProposals } from "../proposal/repository.js";
 import { checkDeadUrls } from "../url-checker.js";
 import { DEFAULT_RETENTION_DAYS as CYCLE_METRICS_RETENTION_DAYS, runCollapseDetector } from "./collapse-detector.js";
@@ -1124,6 +1125,25 @@ export function runRetentionPurgePass(ctx) {
                 }
             }
         }
+        // Per-run flat log files under getTaskLogDir() (#951): logs.db above is
+        // the durable record and already retention-purged, so the transitional
+        // `<taskId>/<timestamp>.log` tail files can be deleted on the same
+        // window without losing anything. A separate try/catch — a filesystem
+        // problem here must not block the DB purges above.
+        try {
+            const taskLogFilesPurged = purgeOldTaskLogFiles(undefined, retentionDays);
+            if (taskLogFilesPurged > 0) {
+                info(`[improve] task log files purge: ${taskLogFilesPurged} file(s) older than ${retentionDays}d removed from ${getTaskLogDir()}`);
+            }
+            appendEvent({
+                eventType: "task_log_files_purged",
+                ref: "task_log_files/_purge",
+                metadata: { purgedCount: taskLogFilesPurged, retentionDays },
+            }, eventsCtx);
+        }
+        catch (err) {
+            warnings.push(`task log files purge failed: ${errMessage(err)}`);
+        }
     }
     return { warnings };
 }

package/dist/commands/models-cli.js

@@ -4,7 +4,7 @@
 import { isDeepStrictEqual } from "node:util";
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { loadConfig } from "../core/config/config.js";
-import { copyDefaultModelMap, loadModelMapLayers, mergedModelMapProfiles, mergeModelMapLayers, } from "../integrations/agent/model-map.js";
+import { copyDefaultModelMap, loadModelMapLayers, mergedModelMapProfiles, mergeModelMapLayers, WILDCARD_ENGINE_KEY, } from "../integrations/agent/model-map.js";
 /**
  * Compute the effective alias table (#946): every (alias, column) pair from
  * the fully resolved map, labeled with where its value came from.
@@ -25,6 +25,11 @@ function modelsListRows() {
     const rows = [];
     for (const [alias, columns] of Object.entries(resolved.aliases)) {
         for (const [column, profile] of Object.entries(columns)) {
+            // The wildcard default (#946) is an alias-wide fallback, not a real
+            // platform column an operator would dispatch to; report it folded into
+            // the real per-platform rows above instead of as its own row.
+            if (column === WILDCARD_ENGINE_KEY)
+                continue;
             const raw = rawProfiles[alias]?.[column];
             const via = raw?.engine !== undefined ? "engine" : "literal";
             const defaultProfile = defaultsOnly.aliases[alias]?.[column];

package/dist/commands/read/curate.js

@@ -25,6 +25,8 @@ import { copySearchHitAttribution, getSearchHitAttribution, usageEventAttributio
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { estimateTokenCount } from "../../llm/embedders/remote.js";
+import { tryLlmFeature } from "../../llm/feature-gate.js";
+import { rerankDocuments } from "../../llm/rerank-client.js";
 import { truncateDescription } from "../../output/shapes/helpers.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 import { findEntryIdByRef, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
@@ -145,7 +147,7 @@ export async function curateSearchResults(query, result, limit, selectedType, ev
     // fixtures) with a `SearchResponse` that was never type-filtered.
     const stashHits = selectedType && selectedType !== "any" ? allStashHits.filter((hit) => hit.type === selectedType) : allStashHits;
     const selected = selectCuratedStashHits(query, stashHits, limit);
-    const selectedStashHits = selected.selected;
+    const selectedStashHits = await maybeRerankCuratedStashHits(query, selected.selected);
     const supportRefsByRef = selected.supportRefsByRef;
     // F4/R-019: respect `--limit` for registry fill instead of hard-capping it
     // at a bare literal 2 — the remaining slots after stash hits ARE the cap.
@@ -594,6 +596,37 @@ function appendCurateSupportRef(supportRefsByRef, ownerRef, supportRef) {
         return;
     supportRefsByRef.set(ownerRef, [...existing, supportRef]);
 }
+/** Default number of `selectCuratedStashHits` candidates sent to the reranker when `search.curateRerank.topN` isn't set. */
+const DEFAULT_CURATE_RERANK_TOP_N = 8;
+/**
+ * Optional cross-encoder rerank pass over curate's already-selected, already-
+ * ranked candidates (#951). Disabled by default (`search.curateRerank.enabled`
+ * is falsy) and, when enabled, best-effort: any failure (misconfigured
+ * endpoint, network error, timeout, malformed response) falls back to
+ * `selectCuratedStashHits`'s own ranking unchanged — a reranker outage must
+ * never turn into a curate failure.
+ *
+ * Only the top `topN` (default {@link DEFAULT_CURATE_RERANK_TOP_N}) already-
+ * selected hits are sent (bounded request size); anything past that keeps its
+ * original position appended after the reranked prefix.
+ */
+async function maybeRerankCuratedStashHits(query, hits) {
+    if (hits.length <= 1)
+        return hits;
+    const config = loadConfig();
+    const rerankConfig = config.search?.curateRerank;
+    return tryLlmFeature("curate_rerank", config, async () => {
+        const topN = rerankConfig?.topN ?? DEFAULT_CURATE_RERANK_TOP_N;
+        const head = hits.slice(0, topN);
+        const tail = hits.slice(topN);
+        const documents = head.map((hit) => [hit.name, hit.description].filter(Boolean).join(" — "));
+        const ranked = await rerankDocuments(rerankConfig ?? {}, query, documents);
+        const rerankedHead = ranked
+            .map(({ index }) => head[index])
+            .filter((hit) => hit !== undefined);
+        return [...rerankedHead, ...tail];
+    }, hits, { timeoutMs: rerankConfig?.timeoutMs ?? null });
+}
 function selectCuratedStashHits(query, hits, limit) {
     const intent = parseCurateIntent(query);
     const collapsed = collapseCurateFamilies(query, hits);

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

@@ -6,7 +6,7 @@
  * former `config-schema.ts` monolith — no behavior change.
  */
 import { z } from "zod";
-import { nonEmptyString, nonNegativeNumber, positiveInt } from "./primitives.js";
+import { httpUrl, nonEmptyString, nonNegativeNumber, positiveInt, symbolicOrWarnApiKey } from "./primitives.js";
 // ── Search ──────────────────────────────────────────────────────────────────
 const SearchGraphBoostSchema = z
     .object({
@@ -22,10 +22,41 @@ const SearchGraphBoostSchema = z
     confidenceWeight: z.number().finite().min(0).max(1).default(0.2).optional(),
 })
     .passthrough();
+/**
+ * `search.curateRerank` (#951) — an optional cross-encoder rerank pass over
+ * `akm curate`'s already-selected candidates.
+ *
+ * Deliberately its own small config arm rather than a third member of the
+ * `engines` map (`EngineConfigSchema` in ./engines.ts): that union's "llm" /
+ * "agent" kinds are load-bearing all the way through execution-lowering,
+ * runner dispatch, and the harness model map (100+ call sites narrow on
+ * `engine.kind`). A reranker is neither — it never dispatches an agent or
+ * lowers to a chat-completions call — so folding it into that union would
+ * force every one of those call sites to account for a kind they can't do
+ * anything with. `endpoint` + `model` (+ optional `apiKey`) is the same
+ * connection shape as an LLM engine without inheriting that machinery.
+ *
+ * `curate_rerank` was removed as a dead `llm.features.*` key in 0.8.0 (no
+ * implementation ever sent a request); this is a new, real implementation,
+ * disabled by default.
+ */
+export const CurateRerankConfigSchema = z
+    .object({
+    enabled: z.boolean().optional(),
+    /** Full URL of the reranker's rerank endpoint, e.g. `http://host:port/rerank`. */
+    endpoint: httpUrl.optional(),
+    model: nonEmptyString.optional(),
+    apiKey: symbolicOrWarnApiKey("search.curateRerank.apiKey").optional(),
+    timeoutMs: positiveInt.optional(),
+    /** How many of curate's already-ranked candidates to send to the reranker. Default 8. */
+    topN: positiveInt.max(50).optional(),
+})
+    .passthrough();
 export const SearchConfigSchema = z
     .object({
     minScore: nonNegativeNumber.optional(),
     defaultExcludeTypes: z.array(nonEmptyString).optional(),
     graphBoost: SearchGraphBoostSchema.optional(),
+    curateRerank: CurateRerankConfigSchema.optional(),
 })
     .passthrough();

package/dist/core/errors.js

@@ -84,6 +84,7 @@ const TRANSIENT_HINTS = {
     STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
     INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs.",
     MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs.",
+    IMPROVE_LOCK_HELD: "Another akm improve run holds the whole-run lock right now. Wait for it to finish and retry, or pass --skip-if-locked on scheduled runs.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {

package/dist/indexer/index-db-contention.js

@@ -0,0 +1,56 @@
+// 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/.
+/**
+ * Shared index.db contention reclassification (field follow-up to #956).
+ *
+ * Extracted out of `indexer.ts` so both `akmIndex`'s outer catch AND
+ * `generateEmbeddingsForDb`'s own catch (`materialize-embeddings.ts`) can
+ * reuse the ONE classifier instead of each building a raw
+ * `Semantic search verification failed: <driver message>` string. Living in
+ * its own module (rather than one importing the other) avoids the import
+ * cycle `indexer.ts` <-> `materialize-embeddings.ts` would otherwise form.
+ */
+import { AkmError, TransientError } from "../core/errors.js";
+import { probeLock } from "../core/file-lock.js";
+import { formatLockHolderPid } from "../core/run-lock.js";
+import { isSqliteContentionError } from "../core/state-db.js";
+import { indexRebuildLockPath } from "./index-rebuild-lock.js";
+/**
+ * Read-only description of the rebuild lock's current holder, appended to a
+ * reclassified index.db contention message when known (field follow-up to
+ * #956). `probeLock` only inspects the sentinel — it never acquires or
+ * mutates it — so this is safe to call from inside an error path.
+ */
+function describeIndexRebuildLockHolder() {
+    const probe = probeLock(indexRebuildLockPath());
+    if (probe.state !== "held")
+        return "";
+    return ` The rebuild lock is currently held by pid ${formatLockHolderPid({
+        pid: probe.holderPid,
+        launcherPid: probe.launcherPid ?? null,
+    })}.`;
+}
+/**
+ * Reclassify a contention-shaped error escaping the walk, index, or
+ * embedding phase into a retryable-shortly `TransientError` (field
+ * follow-up to #956, dev-team field review 2026-09-10): a concurrent writer
+ * (another `akm index`, a source-update embedding pass, the per-command
+ * background reindex) can make index.db busy, and the raw SQLite driver
+ * error ("database is locked") used to escape as exit 70
+ * (internal/unclassified) instead of the "retry shortly" contract exit 75
+ * gives a scheduler to branch on — mirroring `STATE_DB_CONTENDED`'s
+ * precedent for state.db (`core/state-db.ts`). Reuses the ONE shared
+ * classifier, `isSqliteContentionError`, rather than a second one. An error
+ * that is already a classified akm error (e.g. a `STATE_DB_CONTENDED`
+ * TransientError from an inner state.db write) is never re-wrapped — only a
+ * raw, unclassified error matching the shared contention shape is
+ * reclassified. Every other error is rethrown unchanged.
+ */
+export function reclassifyIndexDbContention(error) {
+    if (error instanceof AkmError || !isSqliteContentionError(error))
+        return error;
+    const contended = new TransientError(`akm's index database is busy (another akm process is writing it); retry shortly.${describeIndexRebuildLockHolder()}`, "INDEX_DB_CONTENDED");
+    contended.cause = error;
+    return contended;
+}

package/dist/indexer/indexer.js

@@ -7,14 +7,12 @@ import { detectAdapterId } from "../core/adapter/detect-adapter.js";
 import { adapterForId } from "../core/adapter/registry.js";
 import { isHttpUrl, toErrorMessage } from "../core/common.js";
 import { concurrentMap } from "../core/concurrent.js";
-import { AkmError, ConfigError, TransientError } from "../core/errors.js";
-import { probeLock } from "../core/file-lock.js";
+import { ConfigError } from "../core/errors.js";
 import { defaultConcurrencyForEndpoint } from "../core/loopback.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
-import { formatLockHolderPid } from "../core/run-lock.js";
-import { isSqliteContentionError, withStateDb } from "../core/state-db.js";
+import { withStateDb } from "../core/state-db.js";
 import { isVerbose, warn, warnOnce, warnVerbose } from "../core/warn.js";
 import { disposeLoweredExecutionDispatchLease, } from "../integrations/agent/execution-lowering.js";
 import { isLlmFeatureEnabled } from "../llm/feature-gate.js";
@@ -30,7 +28,7 @@ import { upsertUtilityScore } from "../storage/repositories/index-utility-reposi
 import { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
-import { indexRebuildLockPath } from "./index-rebuild-lock.js";
+import { reclassifyIndexDbContention } from "./index-db-contention.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
@@ -374,44 +372,13 @@ let akmIndexOverride;
 export function _setAkmIndexForTests(fake) {
     akmIndexOverride = fake;
 }
-/**
- * Read-only description of the rebuild lock's current holder, appended to a
- * reclassified index.db contention message when known (field follow-up to
- * #956). `probeLock` only inspects the sentinel — it never acquires or
- * mutates it — so this is safe to call from inside an error path.
- */
-function describeIndexRebuildLockHolder() {
-    const probe = probeLock(indexRebuildLockPath());
-    if (probe.state !== "held")
-        return "";
-    return ` The rebuild lock is currently held by pid ${formatLockHolderPid({
-        pid: probe.holderPid,
-        launcherPid: probe.launcherPid ?? null,
-    })}.`;
-}
-/**
- * Reclassify a contention-shaped error escaping the walk, index, or
- * embedding phase into a retryable-shortly `TransientError` (field
- * follow-up to #956, dev-team field review 2026-09-10): a concurrent writer
- * (another `akm index`, a source-update embedding pass, the per-command
- * background reindex) can make index.db busy, and the raw SQLite driver
- * error ("database is locked") used to escape as exit 70
- * (internal/unclassified) instead of the "retry shortly" contract exit 75
- * gives a scheduler to branch on — mirroring `STATE_DB_CONTENDED`'s
- * precedent for state.db (`core/state-db.ts`). Reuses the ONE shared
- * classifier, `isSqliteContentionError`, rather than a second one. An error
- * that is already a classified akm error (e.g. a `STATE_DB_CONTENDED`
- * TransientError from an inner state.db write) is never re-wrapped — only a
- * raw, unclassified error matching the shared contention shape is
- * reclassified. Every other error is rethrown unchanged.
- */
-export function reclassifyIndexDbContention(error) {
-    if (error instanceof AkmError || !isSqliteContentionError(error))
-        return error;
-    const contended = new TransientError(`akm's index database is busy (another akm process is writing it); retry shortly.${describeIndexRebuildLockHolder()}`, "INDEX_DB_CONTENDED");
-    contended.cause = error;
-    return contended;
-}
+// Moved to its own module (field follow-up to #956) so
+// `generateEmbeddingsForDb` (materialize-embeddings.ts) can reuse the same
+// classifier without an indexer.ts <-> materialize-embeddings.ts import
+// cycle. Re-exported here for back-compat with existing call sites/tests
+// that import it from `./indexer`. See index-db-contention.ts for the full
+// rationale.
+export { reclassifyIndexDbContention };
 export async function akmIndex(options) {
     try {
         const override = akmIndexOverride;

package/dist/indexer/materialize-embeddings.js

@@ -12,6 +12,7 @@ import { purgeEmbeddingSalvage, relabelEmbeddingSalvageFingerprint, reuseSalvage
 import { getEmbeddableEntryCount } from "../storage/repositories/index-entries-repository.js";
 import { deleteMeta, getMeta, setMeta } from "../storage/repositories/index-meta-repository.js";
 import { getAllEntriesForEmbedding, getEmbeddingCount, isVecFastPathComplete, isVecFastPathReady, purgeEmbeddings, sampleEmbeddedEntriesForCanary, setVecFastPathReady, upsertEmbedding, } from "../storage/repositories/index-vec-repository.js";
+import { reclassifyIndexDbContention } from "./index-db-contention.js";
 /** Identifies the embedding provider+model+dimension a stored vector was generated with. */
 export function deriveSemanticProviderFingerprint(embedding) {
     if (isDeterministicEmbedEnabled()) {
@@ -732,7 +733,20 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
         }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        // Field follow-up to #956 (dev-team field review 2026-09-10): a
+        // contention-shaped error (another akm process writing index.db right
+        // now) used to escape this catch as a raw driver string ("database is
+        // locked"), reaching this user-facing message unclassified even though
+        // the acquisition-time path (`akmIndex`'s outer catch) already
+        // reclassifies the same shape into `TransientError("INDEX_DB_CONTENDED")`.
+        // Reuses that ONE shared classifier rather than a second one — see
+        // `index-db-contention.ts`. This catch stays non-fatal (a caller sees
+        // `success: false` and a message, never a thrown error): the run
+        // continues through the remaining index phases exactly as it did
+        // before, only the message is now classified when the error is
+        // contention-shaped.
+        const reclassified = reclassifyIndexDbContention(error);
+        const message = reclassified instanceof Error ? reclassified.message : String(reclassified);
         warn("Embedding generation failed, continuing without:", message);
         onProgress({ phase: "embeddings", message: `Embedding generation failed: ${message}` });
         return {

package/dist/integrations/agent/model-map.js

@@ -26,6 +26,18 @@ let standaloneInstalledModelMapText;
 const ENGINE_KEY_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
 const ALIAS_KEY_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const RESERVED_MAP_KEYS = new Set(["__proto__", "constructor", "prototype", "tostring"]);
+/**
+ * A profile's own field names (#946). When one of these appears directly
+ * under an alias — e.g. `"fast": { "engine": "local-fast" }` — it is not a
+ * per-platform column named `model`/`inference`/`engine`; it is a wildcard
+ * default profile applied to every platform column of that alias, exactly
+ * the flat shorthand the original proposal asked for. A nested per-platform
+ * entry in the same alias (`"fast": { "claude": { ... } }`) still overrides
+ * the wildcard for that one column, so both forms compose.
+ */
+const PROFILE_FIELD_KEYS = new Set(["model", "inference", "engine"]);
+/** Internal key the wildcard default profile is stored under (never user-writable directly). */
+export const WILDCARD_ENGINE_KEY = "*";
 function assertSafeMapKey(key, source, jsonPath) {
     if (RESERVED_MAP_KEYS.has(key.toLowerCase())) {
         invalid(source, jsonPath, "reserved prototype-like key is not allowed");
@@ -137,7 +149,18 @@ export function parseModelMapLayer(text, source) {
         }
         const engines = [];
         const enginesSeen = new Map();
-        for (const [rawEngine, rawProfile] of Object.entries(engineRecord)) {
+        const wildcardFields = {};
+        const platformEntries = [];
+        for (const [rawKey, rawValue] of Object.entries(engineRecord)) {
+            if (PROFILE_FIELD_KEYS.has(rawKey))
+                wildcardFields[rawKey] = rawValue;
+            else
+                platformEntries.push([rawKey, rawValue]);
+        }
+        if (Object.keys(wildcardFields).length > 0) {
+            engines.push([WILDCARD_ENGINE_KEY, parseProfileLayer(wildcardFields, source, `$.aliases.${rawAlias}`)]);
+        }
+        for (const [rawEngine, rawProfile] of platformEntries) {
             const engine = rawEngine.toLowerCase();
             assertSafeMapKey(engine, source, `$.aliases.${rawAlias}.${rawEngine}`);
             if (!ENGINE_KEY_PATTERN.test(engine)) {
@@ -238,6 +261,18 @@ function mergeRawProfileLayers(installed, user) {
     const apply = (layer) => {
         for (const [alias, layerEngines] of Object.entries(layer.aliases)) {
             const mergedEngines = aliases.get(alias) ?? new Map();
+            const wildcard = ownValue(layerEngines, WILDCARD_ENGINE_KEY);
+            if (wildcard !== undefined) {
+                // This layer's wildcard default (#946) overlays every platform column
+                // already accumulated from earlier layers, before this layer's own
+                // explicit per-platform entries (applied below) get a chance to
+                // override it for their one column.
+                for (const [engineKey, profile] of mergedEngines) {
+                    if (engineKey === WILDCARD_ENGINE_KEY)
+                        continue;
+                    mergedEngines.set(engineKey, mergeProfiles(profile, wildcard));
+                }
+            }
             for (const [engineKey, profile] of Object.entries(layerEngines)) {
                 mergedEngines.set(engineKey, mergeProfiles(mergedEngines.get(engineKey), profile));
             }
@@ -316,7 +351,9 @@ export function resolveModelMapAlias(input, engine, map) {
     const alias = input.toLowerCase();
     const selectedEngine = engine.toLowerCase();
     const tier = ownValue(map.aliases, alias);
-    const profile = ownValue(tier, selectedEngine);
+    // A specific platform column always wins; the alias-level wildcard default
+    // (#946) is only a fallback for a column no layer ever set explicitly.
+    const profile = ownValue(tier, selectedEngine) ?? ownValue(tier, WILDCARD_ENGINE_KEY);
     if (profile !== undefined)
         return selectionFromProfile(input, profile);
     const knownAliasUnmappedForEngine = tier !== undefined;

package/dist/llm/feature-gate.js

@@ -9,6 +9,10 @@ const FEATURE_LOCATION = {
     memory_inference: (cfg) => cfg.index?.memory?.enabled ?? true,
     graph_extraction: (cfg) => cfg.index?.graph?.enabled ?? true,
     metadata_enhance: (cfg) => cfg.index?.metadataEnhance?.enabled ?? false,
+    // #951: a real implementation of the dead `curate_rerank` key removed in
+    // 0.8.0. Off by default — it requires a `search.curateRerank.endpoint` a
+    // caller must explicitly configure.
+    curate_rerank: (cfg) => Boolean(cfg.search?.curateRerank?.enabled),
     // Always on at the LLM-wrapper level. Enablement is decided ONCE at the
     // extract entry point (`akmExtract`): the `extract.enabled` process toggle
     // gates extract as a STAGE of `akm improve` (the active improve strategy, per

package/dist/llm/rerank-client.js

@@ -0,0 +1,113 @@
+// 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/.
+/**
+ * HTTP client for a standalone cross-encoder rerank endpoint (#951).
+ *
+ * `curate_rerank` was a dead `llm.features.*` key removed in 0.8.0 — no wire
+ * call was ever implemented under it. This is the first real implementation:
+ * a small, dedicated client (NOT routed through `llm/client.ts`'s chat-
+ * completions transport, since a reranker speaks a different, much smaller
+ * contract) for the request/response shape a TEI/Cohere-style `/rerank`
+ * endpoint accepts:
+ *
+ *   POST <endpoint>
+ *   { "model": "<name>", "query": "<text>", "documents": ["<text>", ...] }
+ *
+ *   200 OK
+ *   { "results": [ { "index": 0, "relevance_score": 0.83 }, ... ] }
+ *
+ * `results` need not be sorted or complete — {@link rerankDocuments} sorts by
+ * `relevance_score` descending and callers treat a missing index as
+ * "unscored" (kept in its original relative position, after every scored
+ * document). Deliberately independent of `EngineConfigSchema`'s "llm"/"agent"
+ * kinds — see the comment on `CurateRerankConfigSchema` in
+ * `core/config/schema/search.ts` for why.
+ */
+import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
+import { resolveSecret } from "../core/config/config.js";
+import { isApiKeyReference } from "../core/config/schema/primitives.js";
+import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
+import { resolveSecretFromStore } from "../sources/snapshot-fetchers/secret-seam.js";
+const DEFAULT_RERANK_TIMEOUT_MS = 10_000;
+export class RerankCallError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "RerankCallError";
+        this.code = code;
+    }
+}
+/**
+ * Call a configured rerank endpoint and return documents ordered by
+ * relevance to `query`, most relevant first. Any document the endpoint
+ * didn't return a score for keeps its original relative order, appended
+ * after every scored document (never dropped).
+ *
+ * Throws {@link RerankCallError} on any transport/parse failure — callers
+ * that want a graceful fallback should use `tryLlmFeature("curate_rerank", ...)`
+ * (`llm/feature-gate.ts`), matching every other bounded in-tree LLM/rerank
+ * call site.
+ */
+export async function rerankDocuments(config, query, documents) {
+    if (!config.endpoint) {
+        throw new RerankCallError("search.curateRerank.endpoint is not configured.", "provider_error");
+    }
+    if (documents.length === 0)
+        return [];
+    const resolvedKey = config.apiKey && isApiKeyReference(config.apiKey)
+        ? resolveSecret(config.apiKey, resolveSecretFromStore)
+        : config.apiKey;
+    const headers = { "Content-Type": "application/json" };
+    if (resolvedKey)
+        headers.Authorization = `Bearer ${resolvedKey}`;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_RERANK_TIMEOUT_MS;
+    const requestBody = JSON.stringify({
+        ...(config.model ? { model: config.model } : {}),
+        query,
+        documents,
+    });
+    let response;
+    try {
+        response = await fetchWithTimeout(config.endpoint, { method: "POST", headers, body: requestBody }, timeoutMs);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("timed out")) {
+            throw new RerankCallError(`Rerank request timed out after ${timeoutMs}ms`, "timeout");
+        }
+        throw new RerankCallError(`Rerank network error: ${msg}`, "network_error");
+    }
+    if (!response.ok) {
+        const rawBody = await readBodyWithByteCap(response).catch(() => "");
+        const safeBody = redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : []);
+        throw new RerankCallError(`Rerank request failed (${response.status}) ${config.endpoint}: ${safeBody}`, "provider_error");
+    }
+    const rawBody = await readBodyWithByteCap(response);
+    let json;
+    try {
+        json = JSON.parse(rawBody);
+    }
+    catch {
+        throw new RerankCallError(`Rerank response was not valid JSON ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error");
+    }
+    if (!Array.isArray(json.results)) {
+        throw new RerankCallError(`Rerank response from ${config.endpoint} has no "results" array.`, "parse_error");
+    }
+    const scored = new Map();
+    for (const entry of json.results) {
+        if (typeof entry.index !== "number")
+            continue;
+        const score = typeof entry.relevance_score === "number" ? entry.relevance_score : entry.score;
+        if (typeof score === "number")
+            scored.set(entry.index, score);
+    }
+    const rankedScored = [...scored.entries()]
+        .map(([index, score]) => ({ index, score }))
+        .sort((a, b) => b.score - a.score);
+    const unscored = documents
+        .map((_, index) => index)
+        .filter((index) => !scored.has(index))
+        .map((index) => ({ index, score: Number.NEGATIVE_INFINITY }));
+    return [...rankedScored, ...unscored];
+}

package/dist/scripts/akm-migrate-node.js

@@ -7072,7 +7072,8 @@ var init_errors = __esm(() => {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
     STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
     INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs.",
-    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs."
+    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs.",
+    IMPROVE_LOCK_HELD: "Another akm improve run holds the whole-run lock right now. Wait for it to finish and retry, or pass --skip-if-locked on scheduled runs."
   };
   NOT_FOUND_HINTS = {
     ASSET_NOT_FOUND: "Run `akm search <query>` or `akm index` to refresh the index.",
@@ -76378,10 +76379,19 @@ var SearchGraphBoostSchema = exports_external.object({
   confidenceMode: exports_external.enum(["blend"]).default("blend").optional(),
   confidenceWeight: exports_external.number().finite().min(0).max(1).default(0.2).optional()
 }).passthrough();
+var CurateRerankConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().optional(),
+  endpoint: httpUrl.optional(),
+  model: nonEmptyString.optional(),
+  apiKey: symbolicOrWarnApiKey("search.curateRerank.apiKey").optional(),
+  timeoutMs: positiveInt.optional(),
+  topN: positiveInt.max(50).optional()
+}).passthrough();
 var SearchConfigSchema = exports_external.object({
   minScore: nonNegativeNumber.optional(),
   defaultExcludeTypes: exports_external.array(nonEmptyString).optional(),
-  graphBoost: SearchGraphBoostSchema.optional()
+  graphBoost: SearchGraphBoostSchema.optional(),
+  curateRerank: CurateRerankConfigSchema.optional()
 }).passthrough();
 
 // src/core/config/schema/setup.ts
@@ -93483,6 +93493,7 @@ init_warn();
 var MODEL_MAP_VERSION = 1;
 var ENGINE_KEY_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
 var RESERVED_MAP_KEYS = new Set(["__proto__", "constructor", "prototype", "tostring"]);
+var PROFILE_FIELD_KEYS = new Set(["model", "inference", "engine"]);
 
 // src/integrations/harnesses/opencode-sdk/sdk-runner.ts
 var _servers = new Map;
@@ -97472,6 +97483,34 @@ async function embedBatch(texts, embeddingConfig, signal, onSkip, onBatch) {
   return results;
 }
 
+// src/indexer/index-db-contention.ts
+init_errors();
+
+// src/indexer/index-rebuild-lock.ts
+init_paths();
+init_warn();
+function indexRebuildLockPath() {
+  return getIndexRebuildLockPath();
+}
+
+// src/indexer/index-db-contention.ts
+function describeIndexRebuildLockHolder() {
+  const probe = probeLock(indexRebuildLockPath());
+  if (probe.state !== "held")
+    return "";
+  return ` The rebuild lock is currently held by pid ${formatLockHolderPid({
+    pid: probe.holderPid,
+    launcherPid: probe.launcherPid ?? null
+  })}.`;
+}
+function reclassifyIndexDbContention(error2) {
+  if (error2 instanceof AkmError || !isSqliteContentionError(error2))
+    return error2;
+  const contended = new TransientError(`akm's index database is busy (another akm process is writing it); retry shortly.${describeIndexRebuildLockHolder()}`, "INDEX_DB_CONTENDED");
+  contended.cause = error2;
+  return contended;
+}
+
 // src/indexer/materialize-embeddings.ts
 function deriveSemanticProviderFingerprint(embedding) {
   if (isDeterministicEmbedEnabled()) {
@@ -97882,7 +97921,8 @@ ${listed}${more}` });
         clearInterval(heartbeatTimer);
     }
   } catch (error2) {
-    const message = error2 instanceof Error ? error2.message : String(error2);
+    const reclassified = reclassifyIndexDbContention(error2);
+    const message = reclassified instanceof Error ? reclassified.message : String(reclassified);
     warn("Embedding generation failed, continuing without:", message);
     onProgress({ phase: "embeddings", message: `Embedding generation failed: ${message}` });
     return {

package/dist/scripts/akm-migrate.js

@@ -7071,7 +7071,8 @@ var init_errors = __esm(() => {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
     STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
     INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs.",
-    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs."
+    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs.",
+    IMPROVE_LOCK_HELD: "Another akm improve run holds the whole-run lock right now. Wait for it to finish and retry, or pass --skip-if-locked on scheduled runs."
   };
   NOT_FOUND_HINTS = {
     ASSET_NOT_FOUND: "Run `akm search <query>` or `akm index` to refresh the index.",
@@ -75706,10 +75707,19 @@ var SearchGraphBoostSchema = exports_external.object({
   confidenceMode: exports_external.enum(["blend"]).default("blend").optional(),
   confidenceWeight: exports_external.number().finite().min(0).max(1).default(0.2).optional()
 }).passthrough();
+var CurateRerankConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().optional(),
+  endpoint: httpUrl.optional(),
+  model: nonEmptyString.optional(),
+  apiKey: symbolicOrWarnApiKey("search.curateRerank.apiKey").optional(),
+  timeoutMs: positiveInt.optional(),
+  topN: positiveInt.max(50).optional()
+}).passthrough();
 var SearchConfigSchema = exports_external.object({
   minScore: nonNegativeNumber.optional(),
   defaultExcludeTypes: exports_external.array(nonEmptyString).optional(),
-  graphBoost: SearchGraphBoostSchema.optional()
+  graphBoost: SearchGraphBoostSchema.optional(),
+  curateRerank: CurateRerankConfigSchema.optional()
 }).passthrough();
 
 // src/core/config/schema/setup.ts
@@ -93478,6 +93488,7 @@ init_warn();
 var MODEL_MAP_VERSION = 1;
 var ENGINE_KEY_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
 var RESERVED_MAP_KEYS = new Set(["__proto__", "constructor", "prototype", "tostring"]);
+var PROFILE_FIELD_KEYS = new Set(["model", "inference", "engine"]);
 
 // src/integrations/harnesses/opencode-sdk/sdk-runner.ts
 var _servers = new Map;
@@ -97428,6 +97439,34 @@ async function embedBatch(texts, embeddingConfig, signal, onSkip, onBatch) {
   return results;
 }
 
+// src/indexer/index-db-contention.ts
+init_errors();
+
+// src/indexer/index-rebuild-lock.ts
+init_paths();
+init_warn();
+function indexRebuildLockPath() {
+  return getIndexRebuildLockPath();
+}
+
+// src/indexer/index-db-contention.ts
+function describeIndexRebuildLockHolder() {
+  const probe = probeLock(indexRebuildLockPath());
+  if (probe.state !== "held")
+    return "";
+  return ` The rebuild lock is currently held by pid ${formatLockHolderPid({
+    pid: probe.holderPid,
+    launcherPid: probe.launcherPid ?? null
+  })}.`;
+}
+function reclassifyIndexDbContention(error2) {
+  if (error2 instanceof AkmError || !isSqliteContentionError(error2))
+    return error2;
+  const contended = new TransientError(`akm's index database is busy (another akm process is writing it); retry shortly.${describeIndexRebuildLockHolder()}`, "INDEX_DB_CONTENDED");
+  contended.cause = error2;
+  return contended;
+}
+
 // src/indexer/materialize-embeddings.ts
 function deriveSemanticProviderFingerprint(embedding) {
   if (isDeterministicEmbedEnabled()) {
@@ -97838,7 +97877,8 @@ ${listed}${more}` });
         clearInterval(heartbeatTimer);
     }
   } catch (error2) {
-    const message = error2 instanceof Error ? error2.message : String(error2);
+    const reclassified = reclassifyIndexDbContention(error2);
+    const message = reclassified instanceof Error ? reclassified.message : String(reclassified);
     warn("Embedding generation failed, continuing without:", message);
     onProgress({ phase: "embeddings", message: `Embedding generation failed: ${message}` });
     return {

package/dist/tasks/run/task-log.js

@@ -36,6 +36,65 @@ export function resolveTaskLogPath(logDir, taskId, startedAtIso) {
         return "";
     }
 }
+/**
+ * Delete per-run flat log files (`<logDir>/<taskId>/<timestamp>.log`) older
+ * than `retentionDays` (#951). These files are a transitional human-readable
+ * tail only — the durable record lives in logs.db, already purged by
+ * {@link purgeOldTaskLogs} in ../../core/logs-db — so deleting an old file
+ * here loses nothing that isn't already retained (and separately purged)
+ * there.
+ *
+ * Bounded by construction: only ever reads/deletes inside `logDir` (defaults
+ * to {@link getTaskLogDir}), one level of `<taskId>` subdirectories, `.log`
+ * files only. A missing/unreadable directory is a no-op, not an error —
+ * mirrors the best-effort contract the rest of this module holds for log
+ * persistence.
+ */
+export function purgeOldTaskLogFiles(logDir, retentionDays = 90) {
+    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
+        return 0;
+    const dir = logDir ?? getTaskLogDir();
+    const cutoffMs = Date.now() - retentionDays * 86_400_000;
+    let deleted = 0;
+    let taskDirs;
+    try {
+        taskDirs = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        return 0;
+    }
+    for (const taskDirEntry of taskDirs) {
+        if (!taskDirEntry.isDirectory())
+            continue;
+        const taskDirPath = path.join(dir, taskDirEntry.name);
+        let logFiles;
+        try {
+            logFiles = fs.readdirSync(taskDirPath, { withFileTypes: true });
+        }
+        catch (error) {
+            rethrowIfTestIsolationError(error);
+            continue;
+        }
+        for (const logFile of logFiles) {
+            if (!logFile.isFile() || !logFile.name.endsWith(".log"))
+                continue;
+            const logFilePath = path.join(taskDirPath, logFile.name);
+            try {
+                const stat = fs.statSync(logFilePath);
+                if (stat.mtimeMs < cutoffMs) {
+                    fs.unlinkSync(logFilePath);
+                    deleted++;
+                }
+            }
+            catch (error) {
+                rethrowIfTestIsolationError(error);
+                // Best-effort: a file that vanished or can't be stat'd/removed is skipped.
+            }
+        }
+    }
+    return deleted;
+}
 /**
  * Redact logs.db rows against the SAME contiguous text the file sink sees.
  *

package/docs/migration/release-notes/0.9.15.md

@@ -22,6 +22,22 @@ fix for a scheduled or opportunistic index run is the same:
 `akm index --skip-if-locked` steps aside (exit 0) instead of contending at
 all.
 
+Two more contention paths collided on the same "config error instead of
+transient" anti-pattern (#948 field follow-up, 2026-09-10). `akm improve`'s
+whole-run lock (only one `improve` runs at a time) used to fail a losing
+contender with `{"code":"INVALID_CONFIG_FILE"}` at exit 78 when no
+`--skip-if-locked` was passed — a config-error exit for ordinary contention
+between two legitimate `improve` invocations. It is now `TransientError`
+code `IMPROVE_LOCK_HELD` at exit 75, naming the current holder's pid and
+start time; `--skip-if-locked` is unchanged (still exit 0). Separately, the
+index rebuild's embedding-verification step (`[index:verify] Semantic search
+verification failed: ...`) could still surface a raw, unclassified
+`database is locked` message even though the acquisition path was already
+fixed — that message is now built through the same `INDEX_DB_CONTENDED`
+reclassification as the rest of the index path. This step does not throw, so
+it does not change `akm index`'s own exit code; only the message text
+changed.
+
 The six shipped scheduled `improve` task templates now run with
 `--require-engines`, which aborts (exit 78) before any index work when a
 process's engine or credential cannot be resolved in the task's own

package/docs/reference/cli.md

@@ -2362,7 +2362,7 @@ akm improve report --since 7d          # ...aggregated over every real run start
 | `--require-feedback-signal` | Only process assets with recent feedback signals |
 | `--strategy <name>` | Override the active improve strategy (a built-in or entry under `improve.strategies`) |
 | `--json-to-stdout` | Also emit the full persisted JSON result on stdout for a live run. Without this flag, stdout stays empty. Dry-runs always emit their result and are never persisted. |
-| `--skip-if-locked` | If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with "already running" (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress. |
+| `--skip-if-locked` | If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with "already running" (exit 75, `TransientError`, code `IMPROVE_LOCK_HELD` — field follow-up to #948: two legitimate `improve` invocations colliding on this lock is ordinary, retryable contention, not a broken config file). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress. |
 | `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment, OR whose endpoint fails a bounded reachability probe — the same probe `akm health`'s `default-llm-engine`/`configured-engines` checks run, once per distinct endpoint. Without this flag, improve degrades gracefully: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
 | `--show-prompt` | Print the composed reflect prompt (#952) for one asset and exit — before any lock, index write, or engine dispatch. Requires a fully-qualified asset ref as the scope (`akm improve lessons/my-lesson --show-prompt`); rejected with a type or whole-bundle scope. The default output format is JSON, which carries the prompt as a `prompt` field (escaped into one line) alongside the resolved `engine`/`engineKind`; pass `--format text` to print the prompt itself, unwrapped and readable by eye. |
 | `--sync` / `--no-sync` | Commit (and optionally push) the git-backed primary bundle when the run finishes. Default: on for git-backed bundles (per profile config). |

package/docs/reference/configuration.md

@@ -514,6 +514,23 @@ taking about the same wall time as a single one against a healthy endpoint.
 | --- | --- |
 | `search.graphBoost.*` | Entity-graph relevance boost: `directBoostPerEntity`/`directBoostCap` (directly related entities), `hopBoostPerEntity`/`hopBoostCap` (multi-hop, capped at `maxHops` ≤ 3), `confidenceMode` (`blend`, the only supported value), `confidenceWeight` (0–1, default `0.2`) |
 
+### Curate rerank (#951)
+
+An optional cross-encoder rerank pass over `akm curate`'s already-selected
+candidates, via a standalone `/rerank`-style HTTP endpoint (NOT one of the
+`engines.*` `"llm"`/`"agent"` kinds). Disabled by default; a misconfigured
+endpoint, network failure, timeout, or malformed response falls back to
+curate's own ranking unchanged.
+
+| Key | Purpose |
+| --- | --- |
+| `search.curateRerank.enabled` | Turn the rerank pass on (default `false`) |
+| `search.curateRerank.endpoint` | Full URL of the reranker's rerank endpoint |
+| `search.curateRerank.model` | Model name sent to the endpoint (optional) |
+| `search.curateRerank.apiKey` | `$VAR`/`secret://<name>` credential reference (optional) |
+| `search.curateRerank.timeoutMs` | Request timeout (default `10000`) |
+| `search.curateRerank.topN` | How many of curate's ranked candidates to send (default `8`, max `50`) |
+
 ## Feedback
 
 `feedback` shapes the `akm feedback` taxonomy:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.15-beta.4",
+  "version": "0.9.15-beta.5",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [

package/schemas/akm-config.json

@@ -596,6 +596,34 @@
             }
           },
           "additionalProperties": true
+        },
+        "curateRerank": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "endpoint": {
+              "type": "string"
+            },
+            "model": {
+              "type": "string",
+              "minLength": 1
+            },
+            "apiKey": {
+              "type": "string"
+            },
+            "timeoutMs": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
+            "topN": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 50
+            }
+          },
+          "additionalProperties": true
         }
       },
       "additionalProperties": true
@@ -2296,6 +2324,34 @@
                 }
               },
               "additionalProperties": true
+            },
+            "curateRerank": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "endpoint": {
+                  "type": "string"
+                },
+                "model": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "apiKey": {
+                  "type": "string"
+                },
+                "timeoutMs": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0
+                },
+                "topN": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "maximum": 50
+                }
+              },
+              "additionalProperties": true
             }
           },
           "additionalProperties": true