akm-cli 0.9.15-beta.5 → 0.9.16-alpha.1

package/CHANGELOG.md

@@ -4,7 +4,151 @@ 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.5] - 2026-09-10
+## [Unreleased]
+
+## [0.9.16-alpha.1] - 2026-09-11
+
+### Added
+
+- **`akm index status`.** A cheap, read-only snapshot of `index.db`'s
+  current state — files tracked, entries, distinct units, how many have a
+  vector for the active embedding identity (and therefore the embedding
+  queue's remaining depth), the active identity itself, and the last
+  reconcile/build times — with no writes. Mirrors `akm info`'s
+  absent/inaccessible handling: a missing index reads as the ordinary
+  first-run state, an unreadable one is reported, never silently presented
+  as empty.
+- **A credential diagnostic on the embedding queue.** Before the first
+  provider request `akm index`'s drain makes, one default-level line names
+  the embedding endpoint, model, and the credential's SOURCE (never the
+  resolved value) whenever a remote endpoint is configured — so a field run
+  can compare it against what the gateway actually saw (#953).
+
+### Changed
+
+- **`akm index` is redesigned end to end
+  (`docs/plans/index-redesign.md`).** The old walk/clean/embed/finalize
+  phase pipeline, per-directory fingerprint cache, and duplicated storage
+  (entry text held three times, every vector held twice plus a salvage
+  copy) are replaced by two steps: reconcile, then drain. Reconcile
+  (`src/indexer/reconcile.ts`) stat-walks every configured root against a
+  `files` cache, hashing and re-parsing only what actually changed, and
+  derives content-addressed units — one "card" unit per entry
+  (name/description/tags/hints) and one "fragment" unit per Markdown
+  section — into a single text table (`unit_texts`/`units_fts`). Drain
+  (`src/indexer/drain.ts`) treats embedding as a queue, not a phase: the
+  pending set is exactly the unit hashes with no vector under the active
+  embedding identity, packed against the provider's own probed context
+  window and slot count, written into a single vector table
+  (`units`/`units_vec`) keyed by `(unit_hash, identity)`. An unchanged file
+  or unit is never re-derived or re-embedded again — not on a rename, not
+  on `akm index --full`, not on a future generation bump — because
+  everything is keyed by content hash and observed provider identity, never
+  by a row id or a config string.
+- **Every write path indexes what it just wrote, inline.** `remember`,
+  `import`, extract's session-asset capture, `source clone`, and proposal
+  accept each reconcile and drain exactly the paths/units they touched, in
+  the same call as the write, with no lock probe and no background reindex
+  spawn.
+- **Search is one query over `units`**, scoring lexical evidence by BM25
+  magnitude through the calibrated transform the repository already had and
+  combining it with semantic distance on the proven 0.7/0.3 split. Reciprocal
+  rank fusion was tried first and measured worse than the path it replaced
+  (0.918 against 0.933 on the `curate-golden` fixture, unchanged by splitting
+  or weighting the lists), because a rank cannot tell a strong match from a
+  weak one; the shipped scoring measures 0.936 with no banned-above-required
+  hits. The semantic-only `minScore` floor is gone, type filters now apply in
+  SQL before the candidate cap, and the exact/prefix/relaxed ladder tops up to
+  the candidate budget instead of stopping at the first non-empty tier. The
+  tier a hit came from is also ranking evidence: a unit matching every query
+  token outranks one matching a subset, because the calibrated BM25 transform
+  compresses even a sixfold magnitude difference into a few thousandths — far
+  less than any single ranking contributor — so tier decides across tiers and
+  magnitude decides within one.
+- **`akm index --full`** no longer drops anything first: it forces every
+  walked file to be re-parsed (skipping the unchanged-file shortcut) but
+  updates each file's existing row in place, keeping its id, vectors, and
+  learned utility scores. **`akm index --reembed`** now means "drop the
+  active embedding identity's vectors, then re-embed every unit from
+  scratch."
+- **`akm index --skip-if-locked` is deprecated and does nothing.** Index
+  runs no longer take a rebuild lock — every write is a short, idempotent,
+  content-addressed transaction, so two concurrent runs converge instead of
+  contending. Passing the flag prints one deprecation warning; kept only so
+  an existing script does not fail on an unknown flag.
+- **The derived `index.db` generation changes from v23 to v24.** The first
+  read (or explicit `akm index`) after upgrade re-derives `entries` and
+  every unit from files, and embeds the full corpus once against the
+  configured provider, since the new unit vector store does not carry
+  forward the superseded per-entry vector tables. See the [0.9.16 migration
+  note](docs/migration/release-notes/0.9.16.md) for the cost, stated
+  plainly.
+
+### Removed
+
+- **The index phase pipeline, directory-fingerprint staleness cache, the
+  index rebuild lock, and the index-path use of the maintenance barrier** —
+  roughly 4,800 lines across the files that implemented the old index core,
+  replaced by the reconcile/drain design above (`docs/plans/index-redesign.md`).
+- **`entries_fts`, `entry_fragments_fts`, the legacy per-entry `embeddings`
+  materializer (`materialize-embeddings.ts`), and `embedding_salvage`** —
+  superseded by the single `unit_texts`/`units_fts` and `units`/`units_vec`
+  tables, which never need a salvage-before-discard step because they are
+  content-addressed and never wholesale-discarded.
+- **`akm index --enrich`, `--re-enrich`, `--clean`, and `--dry-run`.**
+  Plain `akm index` now always performs metadata enrichment when an engine
+  is configured, and every run already removes stale entries as part of
+  reconcile — the work these flags used to separately opt into. All four
+  now fail with a `UsageError` naming the replacement, instead of silently
+  doing nothing or being silently accepted.
+- **Config keys `embedding.maxInputTokens`, `embedding.maxTokens`,
+  `embedding.batchSize`, `embedding.contextLength`, and
+  `search.minScore`.** Embedding request packing is sourced from the
+  provider's own probed limits (unchanged from 0.9.15 packing, applied to
+  units instead of whole entries); the fused score has no comparable 0–1
+  threshold to tune. A config that still sets any of them loads without
+  error and is simply ignored.
+- **The `"ready-js"` semantic-search status.** Named a pure-JS
+  cosine-similarity fallback for when `sqlite-vec` was unavailable; the new
+  unit vector store has no BLOB-table fallback to fall back to, so nothing
+  produces that value any more.
+
+### Fixed
+
+- **Two akm processes starting at the same moment against a database neither
+  has created yet no longer fail.** `state.db` and `index.db` each had a
+  first-open race. `index.db` created `entries` about twenty statements
+  before it stamped the generation, so a second opener read
+  entries-without-a-generation as a stale index and dropped the table out
+  from under the first process, which then exited 70 with `no such table:
+  entries` — measured at 8 of 440 racing child processes. `state.db` read its
+  migration ledger and its "does this file have any other tables" check as
+  two separate statements, so a sibling's bootstrap committing between them
+  looked exactly like a legacy unversioned database and was refused outright
+  — 2 of 1200 racing trials. Both initializations are now single atomic
+  units, measured at zero failures in 840 and 1200 trials respectively, idle
+  and under load. Only a genuinely contended run still fails, as
+  `INDEX_DB_CONTENDED`/`STATE_DB_CONTENDED` at exit 75, the documented
+  retry-shortly contract. An already-initialized database takes the same
+  unlocked path it always did.
+- **`akm show <memory>` no longer fails when that memory has an inferred
+  `.derived` twin.** It exited 2 with `RESOURCE_ALREADY_EXISTS` ("multiple
+  physical owners"), so once `akm improve` derived a memory — its ordinary
+  output — the base ref stopped being usable, and the read path that did not
+  fail served the twin's content instead of the memory's. `.derived` is a
+  provenance marker on the same identity and the placement layer always
+  declared that the plain file wins; the physical-owner lookup now honours
+  that instead of discarding it. Genuinely ambiguous cases, including two
+  case-only spellings of one name and `env`'s co-equal `.env`/`default.env`
+  pair, still fail loudly and unchanged. Present since before 0.9.15.
+- **A derived memory no longer outranks the memory it was derived from.** A
+  twin's own filename contributed a `derived` tag that minted a synthetic
+  alias, and the machine-written `source:` provenance backref was folded into
+  search hints, together handing the twin a flat 0.42 of ranking credit for
+  bookkeeping no author wrote — enough to beat a memory whose description
+  matched the query verbatim. Neither field earns ranking credit any more.
+
+## [0.9.15] - 2026-09-10
 
 ### Added
 

package/dist/assets/tasks/core/index-refresh.yml

@@ -1,4 +1,4 @@
 version: 4
-run: akm index --skip-if-locked
+run: akm index
 description: Nightly incremental index refresh
 schedule: "0 4 * * *"

package/dist/cli/retired-commands.js

@@ -104,6 +104,8 @@ export function retiredCommandHint(parentPath, attempted) {
  */
 const RETIRED_FLAG_HINTS = {
     "index --background": "`--background` was removed in 0.9 — the flag never actually backgrounded; use `--quiet`.",
+    "index --clean": "`--clean` was removed in the index redesign — every `akm index` run now removes stale entries as part of reconcile, the same work `--clean` used to opt into.",
+    "index --dry-run": "`--dry-run` was removed in the index redesign along with `--clean`, the only flag it ever modified.",
     "setup --detect-only": "`--detect-only` was removed in 0.9 — environment detection runs inside `akm setup`; `akm info` reports the configured capabilities.",
     "setup --reset-recommended": "`--reset-recommended` was removed in 0.9 — `akm setup` now offers to apply recommended defaults interactively.",
     "proposal extract --watch": "`--watch` was removed in 0.9 — schedule `akm proposal extract --auto` as a task instead.",

package/dist/cli/unknown-flags.js

@@ -30,6 +30,28 @@ import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray, } fro
 import { retiredFlagHint } from "./retired-commands.js";
 /** Flags citty implements itself, which no command declares. */
 const IMPLICIT_FLAGS = ["help", "h", "version", "v"];
+/**
+ * Keys `GLOBAL_OUTPUT_ARGS` (cli/shared.ts) contributes. Every leaf AND every
+ * group re-declares these so citty's parser consumes their values (see that
+ * constant's own doc) — so their mere presence in a group's own `args` never
+ * means the group has a real business use for its own flags; only a key
+ * beyond this set does. Duplicated here (not imported) to avoid coupling this
+ * shared scanner to `cli/shared.ts`'s own dependency surface; keep in sync if
+ * `GLOBAL_OUTPUT_ARGS` gains or loses a key.
+ */
+const GLOBAL_OUTPUT_ARG_KEYS = new Set(["format", "detail", "shape", "output", "quiet", "verbose"]);
+/**
+ * Whether a group declares any flag of its own beyond the global output
+ * scaffold — i.e. whether its bare invocation (no subcommand token) runs a
+ * REAL default body that reads those flags (`akm index`'s `full`/`reembed`),
+ * as opposed to the canonical bare-group usage error every other group falls
+ * through to (`defineGroupCommand`, cli/shared.ts) — a `UsageError` either
+ * way, whose own declared args (if any) exist only so `--help` documents them,
+ * never so a body reads them.
+ */
+function hasOwnBusinessArgs(cmd) {
+    return Object.keys(cmd.args ?? {}).some((key) => !GLOBAL_OUTPUT_ARG_KEYS.has(key));
+}
 /**
  * Retired flags whose commands still diagnose them THEMSELVES, with a message
  * that names the replacement ("`--scope` was removed, use `--filter`",
@@ -102,9 +124,20 @@ function collectKnownArgs(root, rawArgs) {
             break;
         const idx = findCittyTopLevelCommandIndex(args, (cmd.args ?? {}));
         const token = idx >= 0 ? args[idx] : undefined;
-        // A group with no subcommand token: citty reports "no command specified".
-        if (token === undefined)
-            return { names, valueFlags, booleanFlags, displayNames, path, resolved: false };
+        // A group with no subcommand token: citty always calls the group's own
+        // `run` regardless (a `defineGroupCommand` group's `run` is never
+        // undefined — see its doc in cli/shared.ts). For most groups that `run`
+        // is the canonical bare-group usage error, and its own declared args (if
+        // any) exist only for `--help`, so a flag meant for the subcommand the
+        // caller forgot to type must not be misreported as "unknown" — stand
+        // down, exactly as before. `akm index` is the one group with a REAL
+        // default body that reads its own flags (`full`/`reembed`), so `akm index
+        // --background` must still be rejected even though `index` also carries a
+        // real subcommand (`status`) — `hasOwnBusinessArgs` is what tells the two
+        // apart.
+        if (token === undefined) {
+            return { names, valueFlags, booleanFlags, displayNames, path, resolved: hasOwnBusinessArgs(cmd) };
+        }
         const sub = subCommands[token];
         // An unrecognized token: citty reports the unknown command, which is the
         // real problem — its flags are beside the point.

package/dist/commands/improve/collapse-detector.js

@@ -36,10 +36,10 @@ import { getImproveProcessConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { withStateDb } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
+import { searchEntriesLexical } from "../../indexer/search/db-search.js";
 import { deactivateCanarySet, getActiveCanaries, getCanariesBySetId, insertCanaries, insertCycleMetrics, listActiveCanarySetIds, queryRecentCycleMetrics, } from "../../storage/repositories/canaries-repository.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
-import { searchFts } from "../../storage/repositories/index-fts-repository.js";
 import { computeBigramDiversity, DEFAULT_MAX_GENERATION } from "./anti-collapse.js";
 import { getAllRankScores } from "./salience.js";
 // ── Defaults (mirrored in config-schema.ts ImproveCollapseDetectorSchema) ────
@@ -189,7 +189,7 @@ export function normHash(text) {
  * Returns the 0-based rank of the first hit, or -1.
  */
 function scoreCanary(indexDb, canary, k) {
-    const results = searchFts(indexDb, canary.query, k);
+    const results = searchEntriesLexical(indexDb, canary.query, k);
     const anchorConceptId = canaryConceptId(canary.anchor_ref);
     for (let i = 0; i < Math.min(results.length, k); i++) {
         const r = results[i];

package/dist/commands/improve/consolidate.js

@@ -24,7 +24,7 @@ import { callStructured, preflightStructuredLlmRunner } from "../../llm/structur
 import { getBodyEmbeddings, upsertBodyEmbeddings } from "../../storage/repositories/embeddings-repository.js";
 import { closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { findEntryIdByRef, getAllEntries, getEntryById } from "../../storage/repositories/index-entries-repository.js";
-import { getNeighborsByEntryId } from "../../storage/repositories/index-vec-repository.js";
+import { getNeighborsByEntryId } from "../../storage/repositories/units-repository.js";
 import { isProposalSkipped, listProposals, listProposalsReadOnly, proposalContent, } from "../proposal/repository.js";
 import { hasSupersededStatus, validateProposalFrontmatter } from "../proposal/validators/proposal-quality-validators.js";
 import { DEFAULT_RANDOM_CLUSTER_FRACTION } from "./anti-collapse.js";
@@ -1394,9 +1394,11 @@ export function narrowToIncrementalCandidates(memories, since, warnings, neighbo
             const id = findEntryIdByRef(db, conceptIdFromTypeName("memory", m.name));
             if (id === undefined)
                 continue;
-            for (const hit of getNeighborsByEntryId(db, id, neighborsPerChanged + 1)) {
-                if (hit.id === id)
-                    continue;
+            // index-redesign-contract.md B5f item 4 — `getNeighborsByEntryId`
+            // (units-repository.ts) already excludes the querying entry itself, so
+            // `neighborsPerChanged` genuinely OTHER neighbours are requested
+            // directly (no `+ 1` for self, no self-filter here).
+            for (const hit of getNeighborsByEntryId(db, id, neighborsPerChanged)) {
                 const entry = getEntryById(db, hit.id);
                 if (!entry)
                     continue;

package/dist/commands/improve/improve-cli.js

@@ -249,7 +249,7 @@ export const improveCommand = defineCommand({
         },
         "skip-if-locked": {
             type: "boolean",
-            description: "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.",
+            description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 75). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
             default: false,
         },
         "require-engines": {

package/dist/commands/proposal/repository.js

@@ -1027,10 +1027,19 @@ async function finalizeProposalTransaction(txn, target, proposal, ctx) {
     }
     let accepted = getProposal(p.stashDir, p.proposalId, ctx);
     if (txn.journal.phase === "proposal-persisted") {
-        if (!(await indexWrittenAssets(txn.journal.root, [p.assetPath], { bundleId: target.source.name }))) {
-            throw new Error(`Proposal ${p.proposalId} index finalization failed.`);
+        if (await indexWrittenAssets(txn.journal.root, [p.assetPath], { bundleId: target.source.name })) {
+            advanceTxn(txn, "index-finalized");
+        }
+        else {
+            // `indexWrittenAssets`'s contract (index-written-assets.ts): `false`
+            // means the asset write already stands, but the index itself needs a
+            // manual `akm index` — warn and continue, the same as `source clone`
+            // treats the same return, instead of failing the whole accept/revert.
+            // Leave the phase at "proposal-persisted" (do not advance) so a later
+            // recovery of this journal retries the index update rather than
+            // skipping it as already done.
+            warn(`${p.operation === "accept" ? "Accept" : "Revert"} of ${p.ref} succeeded, but its index update failed; run \`akm index\` to refresh it.`);
         }
-        advanceTxn(txn, "index-finalized");
     }
     if (txn.journal.phase === "index-finalized") {
         accepted = getProposal(p.stashDir, p.proposalId, ctx);

package/dist/commands/read/curate.js

@@ -25,8 +25,6 @@ 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";
@@ -147,7 +145,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 = await maybeRerankCuratedStashHits(query, selected.selected);
+    const selectedStashHits = 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.
@@ -171,10 +169,16 @@ export async function curateSearchResults(query, result, limit, selectedType, ev
 /**
  * Pack a curate result's stash hits into a single token-budgeted blob:
  * resolve each hit's content via the SAME path `akm show` uses
- * (`akmShowUnified` — this also means a `ref#fragment` hit packs just the
- * matched section), then greedily accumulate hits, in the ranking order
- * `curateSearchResults` already produced, until the next hit would exceed
- * `budgetTokens`.
+ * (`akmShowUnified`, called with `item.selectedRef ?? item.ref` — this also
+ * means a hit whose search match was a Markdown fragment packs just the
+ * matched section, not the whole entry `item.ref` now always addresses; see
+ * index-redesign-contract.md B5f item 1), then greedily accumulate hits, in
+ * the ranking order `curateSearchResults` already produced, until the next
+ * hit would exceed `budgetTokens`. Each packed item's `ref` is that SAME
+ * fetched ref (`item.selectedRef ?? item.ref`), mirroring
+ * `enrichCuratedStashHit`'s own `contentRef` convention — labelling a packed
+ * fragment with the bare entry ref would let a later `akm show <ref>` return
+ * a different, larger document than what was actually packed and budgeted.
  *
  * Registry hits are never packed — only `CuratedStashItem`s (locked
  * contract, AGENTS.md: registry results stay separate/opt-in).
@@ -188,9 +192,17 @@ export async function packCuratedHits(result, budgetTokens) {
     const packed = [];
     let used = 0;
     for (const item of stashItems) {
+        // item 4 — record the ref actually FETCHED (`contentRef`), mirroring
+        // `enrichCuratedStashHit`'s own convention: `item.ref` is now always the
+        // bare entry ref, but a body-only match's content came from the
+        // fragment-qualified `selectedRef`. Recording `item.ref` here labelled a
+        // packed fragment with the whole entry's ref, so a consumer that later
+        // ran `akm show <that ref>` got a different, larger document than what
+        // was actually packed and budgeted.
+        const contentRef = item.selectedRef ?? item.ref;
         let shown;
         try {
-            shown = await akmShowUnified({ ref: item.ref, skipLogging: true });
+            shown = await akmShowUnified({ ref: contentRef, skipLogging: true });
         }
         catch {
             continue;
@@ -198,7 +210,7 @@ export async function packCuratedHits(result, budgetTokens) {
         const content = shown.content ?? shown.template ?? shown.prompt ?? "";
         const tokens = estimateTokenCount(content);
         if (used + tokens <= budgetTokens) {
-            packed.push({ ref: item.ref, tokens, content });
+            packed.push({ ref: contentRef, tokens, content });
             used += tokens;
             continue;
         }
@@ -206,7 +218,7 @@ export async function packCuratedHits(result, budgetTokens) {
             const remaining = budgetTokens - used;
             if (remaining > 0) {
                 const truncated = content.slice(0, remaining * 4);
-                packed.push({ ref: item.ref, tokens: estimateTokenCount(truncated), content: truncated });
+                packed.push({ ref: contentRef, tokens: estimateTokenCount(truncated), content: truncated });
                 used += estimateTokenCount(truncated);
             }
         }
@@ -215,9 +227,15 @@ export async function packCuratedHits(result, budgetTokens) {
     return { query: result.query, budget: budgetTokens, tokens: used, items: packed };
 }
 async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs, eventSource) {
+    // index-redesign-contract.md B5f item 1 — `hit.ref` is always the bare entry
+    // ref now; `contentRef` is the fragment-qualified ref when the search match
+    // was a Markdown fragment (`hit.selectedRef`), so the preview/description
+    // resolved below and the curated item's own `followUp` still land on the
+    // matched section instead of regressing to the whole entry.
+    const contentRef = hit.selectedRef ?? hit.ref;
     let shown;
     try {
-        shown = await akmShowUnified({ ref: hit.ref, eventSource, skipLogging: true });
+        shown = await akmShowUnified({ ref: contentRef, eventSource, skipLogging: true });
     }
     catch {
         shown = undefined;
@@ -235,10 +253,13 @@ async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs, even
         type: shown?.type ?? hit.type,
         name: shown?.name ?? hit.name,
         ref: hit.ref,
+        ...(hit.selectedRef ? { selectedRef: hit.selectedRef } : {}),
         path: shown?.path ?? hit.path,
         editable: shown?.editable ?? hit.editable ?? false,
         ...((shown?.editable ?? hit.editable ?? false) === false
-            ? { editHint: shown?.editHint ?? hit.editHint ?? `This asset is read-only. Inspect it with: akm show ${hit.ref}` }
+            ? {
+                editHint: shown?.editHint ?? hit.editHint ?? `This asset is read-only. Inspect it with: akm show ${hit.ref}`,
+            }
             : {}),
         ...(description ? { description } : {}),
         ...(preview ? { preview } : {}),
@@ -246,7 +267,7 @@ async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs, even
         ...(shown?.parameters?.length ? { parameters: shown.parameters } : {}),
         ...(shown?.run ? { run: shown.run } : {}),
         ...(mergedSupportRefs.length > 0 ? { supportRefs: mergedSupportRefs } : {}),
-        followUp: `akm show ${hit.ref}`,
+        followUp: `akm show ${contentRef}`,
         reason: buildCuratedReason(query, shown?.type ?? hit.type),
         ...(hit.score !== undefined ? { score: hit.score } : {}),
     };
@@ -596,37 +617,6 @@ 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/commands/read/search.js

@@ -17,6 +17,8 @@ import { appendEvent } from "../../core/events.js";
 import { resolveReadSources } from "../../indexer/read-preflight.js";
 import { searchLocal } from "../../indexer/search/db-search.js";
 import { getSearchHitAttribution, usageEventAttributionMetadata, } from "../../indexer/search/search-attribution.js";
+import { tryLlmFeature } from "../../llm/feature-gate.js";
+import { rerankDocuments } from "../../llm/rerank-client.js";
 import { getEntryIdByFilePath, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
 // Eagerly import source providers to trigger self-registration before the
 // indexer or path-resolution code runs.
@@ -111,11 +113,21 @@ export async function akmSearch(input) {
             disableProjectContext: input.disableProjectContext === true,
             disableScopedUtility: input.disableScopedUtility === true,
         });
+    // #951 (moved from curate in 0.9.16 — the pass was always meant for
+    // search). Applied ONCE here, to LOCAL hits only, before the source
+    // branches below divide the same `localResult.hits` between the "local"
+    // and "all" responses — so both get the rerank and neither double-applies
+    // it. `localResult` is `undefined` for `source === "registry"`, so a
+    // registry-only search never reaches this call and never pays for the
+    // reranker's HTTP request; registry hits are never reranked (registry
+    // results staying separate from stash hits is a locked contract,
+    // AGENTS.md).
+    const rerankedLocalHits = localResult ? await maybeRerankSearchHits(query, localResult.hits, config) : undefined;
     const registryResult = source === "local"
         ? undefined
         : await searchRegistry(query, { limit, includeAssets: input.assets === true, registries: config.registries });
     if (source === "local") {
-        const localHits = localResult?.hits ?? [];
+        const localHits = rerankedLocalHits ?? [];
         const hasResults = localHits.length > 0;
         const response = {
             schemaVersion: 1,
@@ -161,7 +173,7 @@ export async function akmSearch(input) {
         return response;
     }
     // source === "all"
-    const allStashHits = (localResult?.hits ?? []).slice(0, limit);
+    const allStashHits = (rerankedLocalHits ?? []).slice(0, limit);
     const warnings = [...(localResult?.warnings ?? []), ...(registryResult?.warnings ?? [])];
     const hasResults = allStashHits.length > 0 || registryHits.length > 0;
     const response = {
@@ -182,6 +194,42 @@ export async function akmSearch(input) {
 function usageSearchMode(mode) {
     return mode === "semantic" ? "semantic" : "keyword";
 }
+/** Default number of `searchLocal`'s already-ranked LOCAL hits sent to the reranker when `search.rerank.topN` isn't set. */
+const DEFAULT_SEARCH_RERANK_TOP_N = 8;
+/**
+ * Optional cross-encoder rerank pass over `akm search`'s already-ranked LOCAL
+ * hits (#951, moved from `akm curate` in 0.9.16 — the pass was always meant
+ * for search). Disabled by default (`search.rerank.enabled` is falsy) and,
+ * when enabled, best-effort: any failure (misconfigured endpoint, network
+ * error, timeout, malformed response, an out-of-range or duplicate index in
+ * the response) falls back to `searchLocal`'s own ranking unchanged — a
+ * reranker outage must never turn into a search failure.
+ *
+ * Only the top `topN` (default {@link DEFAULT_SEARCH_RERANK_TOP_N}) hits are
+ * sent (bounded request size); anything past that keeps its original
+ * position appended after the reranked prefix. The reranker changes ARRAY
+ * ORDER only — each hit's own `score` is left untouched as the retrieval
+ * score (see docs/reference/cli.md and docs/reference/configuration.md for
+ * why: `SearchHit.score` is a locked `[0,1]` contract downstream consumers
+ * compare and threshold on, while ordering is the field a rerank-aware
+ * consumer reads).
+ */
+async function maybeRerankSearchHits(query, hits, config) {
+    if (hits.length <= 1)
+        return hits;
+    const rerankConfig = config.search?.rerank;
+    return tryLlmFeature("search_rerank", config, async () => {
+        const topN = rerankConfig?.topN ?? DEFAULT_SEARCH_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 maybeLogSearchEvent(input, query, response, mode) {
     if (input.skipLogging)
         return;

package/dist/commands/sources/index-status.js

@@ -0,0 +1,99 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm index status` — a cheap, read-only snapshot of `index.db`'s current
+ * state: files tracked, entries, unit coverage for the active embedding
+ * identity, and the last reconcile time. Mirrors `assembleInfo`'s
+ * absent/inaccessible handling (`src/commands/sources/info.ts`) so a missing
+ * index reads as the ordinary first-run state and an unreadable one is
+ * reported, never silently presented as empty (#791).
+ */
+import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
+import { getDbPath } from "../../core/paths.js";
+import { error } from "../../core/warn.js";
+import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { getEntryCount } from "../../storage/repositories/index-entries-repository.js";
+import { getMeta } from "../../storage/repositories/index-meta-repository.js";
+function emptyStatus(indexPath) {
+    return {
+        indexPath,
+        files: 0,
+        entries: 0,
+        units: { total: 0, withVector: 0, pending: 0 },
+        activeIdentity: null,
+        lastReconcileAt: null,
+        builtAt: null,
+    };
+}
+function readUnitsStatus(db, identity) {
+    // Mirrors `drainEmbeddingQueue`'s own candidate set (`selectAllUnitHashes`,
+    // src/indexer/drain.ts) — `unit_texts`, not `entry_units` — so a stale/
+    // orphaned unit_texts row is counted here exactly as it will be by the
+    // next drain, instead of understating the backlog. (Reconcile prunes the
+    // hashes each write itself replaced, and sweeps the whole table at the end
+    // of a full run, so orphans are bounded — but "bounded" is not "none", and
+    // this count must match the drain either way.)
+    const total = db.prepare("SELECT COUNT(DISTINCT unit_hash) AS n FROM unit_texts").get().n;
+    const withVector = identity
+        ? db
+            .prepare("SELECT COUNT(DISTINCT ut.unit_hash) AS n FROM unit_texts ut " +
+            "JOIN units u ON u.unit_hash = ut.unit_hash AND u.identity = ?")
+            .get(identity).n
+        : 0;
+    return { total, withVector, pending: Math.max(0, total - withVector) };
+}
+/**
+ * Assemble `akm index status`'s envelope.
+ *
+ * @param options.dbPath - Override the database path (useful for testing)
+ */
+export function assembleIndexStatus(options) {
+    const resolvedDbPath = options?.dbPath ?? getDbPath();
+    const empty = emptyStatus(resolvedDbPath);
+    // "Absent" is the ordinary first-run state; "inaccessible" is a fault that
+    // must not present as an empty index (#791).
+    const { access, code } = classifyPathAccess(resolvedDbPath);
+    if (access === "absent")
+        return empty;
+    if (access === "inaccessible") {
+        const detail = describeInaccessiblePath(resolvedDbPath, code);
+        error(`[akm index status] index database is not readable: ${detail}`);
+        return { ...empty, unreadable: detail };
+    }
+    let db;
+    try {
+        db = openExistingDatabase(resolvedDbPath);
+        const files = db.prepare("SELECT COUNT(*) AS n FROM files").get().n;
+        const identity = getMeta(db, "embeddingIdentity") ?? null;
+        return {
+            indexPath: resolvedDbPath,
+            files,
+            entries: getEntryCount(db),
+            units: readUnitsStatus(db, identity),
+            activeIdentity: identity,
+            lastReconcileAt: getMeta(db, "lastReconcileAt") ?? null,
+            builtAt: getMeta(db, "builtAt") ?? null,
+        };
+    }
+    catch (err) {
+        const detail = String(err instanceof Error ? err.message : err);
+        error(`[akm index status] failed to read index status from ${resolvedDbPath}: ${detail}`);
+        // A path that classified as accessible can still fail to open as a
+        // database (corrupt content, a truncated file, an ABI mismatch) — that
+        // is exactly the "unreadable, not silently empty" case #791 exists for,
+        // just discovered a step later than the access-classification check
+        // above rather than by it.
+        return { ...empty, unreadable: detail };
+    }
+    finally {
+        if (db) {
+            try {
+                closeDatabase(db);
+            }
+            catch {
+                // Best-effort close; the read already happened.
+            }
+        }
+    }
+}