akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/execution/source.js

@@ -1,102 +1,38 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { bundleRefToString, isBundleSlug, parseBundleRef } from "../core/asset/asset-ref.js";
-import { cloneExecutionJson, cloneExecutionJsonObject, } from "./json.js";
-import { assertSnapshotKeys, snapshotStrictRecord } from "./record.js";
+import { cloneExecutionJson, cloneExecutionJsonObject } from "./json.js";
 export const EXECUTION_SOURCE_SCHEMA_VERSION = 1;
 /** Current internal adapter identifiers are lowercase kebab-case registry keys. */
 export const EXECUTION_ADAPTER_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const CONTROL_OR_LINE_SEPARATOR_PATTERN = /[\p{Cc}\p{Zl}\p{Zp}]/u;
-const FORMAT_CHARACTER_PATTERN = /\p{Cf}/u;
-const WINDOWS_DRIVE_PREFIX_PATTERN = /^[A-Za-z]:/;
-const RESERVED_EXTENSION_OWNERS = new Set(["__proto__", "constructor", "prototype", "tostring"]);
-const renderedSourceBrand = Symbol("akm.adapter-rendered-execution-source");
-const renderedSourceInstances = new WeakSet();
 function requireRecord(value, path) {
-    return snapshotStrictRecord(value, path);
-}
-function assertOnlyKeys(value, allowed, path) {
-    assertSnapshotKeys(value, allowed, path);
-}
-function validateExtensionOwner(owner) {
-    const normalized = owner.toLowerCase();
-    if (!EXECUTION_ADAPTER_ID_PATTERN.test(owner) || RESERVED_EXTENSION_OWNERS.has(normalized)) {
-        throw new TypeError(`extension owner must be a canonical, non-reserved adapter identifier: ${owner}`);
-    }
-}
-function frozenNullPrototypeMap(entries) {
-    const out = Object.create(null);
-    for (const [key, value] of entries) {
-        Object.defineProperty(out, key, { value, enumerable: true, configurable: false, writable: false });
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`${path} must be an object`);
     }
-    return Object.freeze(out);
-}
-function cloneExtensionEntry(value, index) {
-    const path = `extension entry ${index}`;
-    const cloned = cloneExecutionJson(value, path);
-    if (!Array.isArray(cloned) || cloned.length !== 2) {
-        throw new TypeError(`${path} must be a two-element [owner, values] array`);
-    }
-    const [owner, values] = cloned;
-    if (typeof owner !== "string")
-        throw new TypeError(`${path} owner must be a string`);
-    if (values === null || Array.isArray(values) || typeof values !== "object") {
-        throw new TypeError(`${path} values must be a JSON object`);
-    }
-    return [owner, values];
+    return value;
 }
 export function createAdapterExtensions(first, second, ...rest) {
-    const rawEntries = typeof first === "string"
+    const entries = typeof first === "string"
         ? [[first, second]]
         : [first, ...(second === undefined ? [] : [second]), ...rest];
-    const seen = new Set();
-    const cloned = [];
-    for (const [index, rawEntry] of rawEntries.entries()) {
-        const [owner, values] = cloneExtensionEntry(rawEntry, index);
-        validateExtensionOwner(owner);
-        if (seen.has(owner))
-            throw new TypeError(`duplicate extension owner: ${owner}`);
-        seen.add(owner);
-        cloned.push([owner, cloneExecutionJsonObject(values, `extensions.${owner}`)]);
-    }
-    return frozenNullPrototypeMap(cloned);
+    const out = {};
+    for (const [owner, values] of entries)
+        out[owner] = cloneExecutionJsonObject(values, `extensions.${owner}`);
+    return Object.freeze(out);
 }
 export function cloneAdapterExtensions(value, path) {
-    const record = requireRecord(value, path);
-    const entries = Object.entries(record).map(([owner, fields]) => [owner, cloneExecutionJsonObject(fields, `${path}.${owner}`)]);
-    const [first, ...rest] = entries;
-    return first ? createAdapterExtensions(first, ...rest) : frozenNullPrototypeMap([]);
-}
-function requireCanonicalString(value, path) {
-    if (typeof value !== "string" ||
-        value.length === 0 ||
-        !isWellFormedUnicode(value) ||
-        value.normalize("NFC") !== value) {
-        throw new TypeError(`${path} must be a non-empty NFC string`);
-    }
-    if (hasUnsafeIdentityCharacter(value)) {
-        throw new TypeError(`${path} must not contain Unicode control or dangerous format characters`);
+    const out = {};
+    for (const [owner, fields] of Object.entries(requireRecord(value, path))) {
+        out[owner] = cloneExecutionJsonObject(fields, `${path}.${owner}`);
     }
-    return value;
+    return Object.freeze(out);
 }
-/**
- * Validate a selector/layer identifier that may cross the durable execution
- * boundary. Keep this shared with the cascade planner so resume cannot admit a
- * selector the live planner would reject.
- */
+/** A selector or layer identifier that may cross the durable execution boundary. */
 export function requireStableExecutionSelector(value, path) {
-    let selector;
-    try {
-        selector = requireCanonicalString(value, path);
+    if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
+        throw new TypeError(`${path} must be a non-empty stable identifier`);
     }
-    catch (cause) {
-        throw new TypeError(`${path} must be a non-empty stable NFC identifier`, { cause });
-    }
-    if (selector.length > 512 || selector.trim() !== selector) {
-        throw new TypeError(`${path} must be a non-empty stable NFC identifier`);
-    }
-    return selector;
+    return value;
 }
 export function isPortableExecutionAgentSelector(value) {
     return /^(?:[^/]+\/\/)?agents\/[^/]/.test(value);
@@ -104,118 +40,61 @@ export function isPortableExecutionAgentSelector(value) {
 export function executionPersonaMatchesSelector(selector, personaRef) {
     return selector.includes("//") ? selector === personaRef : personaRef.endsWith(`//${selector}`);
 }
-function hasUnsafeIdentityCharacter(value) {
-    for (const character of value) {
-        if (CONTROL_OR_LINE_SEPARATOR_PATTERN.test(character))
-            return true;
-        // Join controls are meaningful in emoji and several writing systems. All
-        // other format controls are rejected because they can conceal identity.
-        if (FORMAT_CHARACTER_PATTERN.test(character) && character !== "\u200C" && character !== "\u200D")
-            return true;
-    }
-    return false;
-}
-function isWellFormedUnicode(value) {
-    for (let index = 0; index < value.length; index += 1) {
-        const code = value.charCodeAt(index);
-        if (code >= 0xd800 && code <= 0xdbff) {
-            const next = value.charCodeAt(index + 1);
-            if (!(next >= 0xdc00 && next <= 0xdfff))
-                return false;
-            index += 1;
-        }
-        else if (code >= 0xdc00 && code <= 0xdfff) {
-            return false;
-        }
-    }
-    return true;
-}
-function validateCanonicalIdentity(input, path) {
-    assertOnlyKeys(input, ["ref", "bundle", "adapter", "file", "hash"], path);
-    const ref = requireCanonicalString(input.ref, `${path}.ref`);
-    const bundle = requireCanonicalString(input.bundle, `${path}.bundle`);
-    const adapter = requireCanonicalString(input.adapter, `${path}.adapter`);
-    const file = requireCanonicalString(input.file, `${path}.file`);
-    const hash = requireCanonicalString(input.hash, `${path}.hash`);
-    let parsed;
-    try {
-        parsed = parseBundleRef(ref);
-    }
-    catch (cause) {
-        throw new TypeError(`${path}.ref is not a canonical bundle ref`, { cause });
-    }
-    if (parsed.bundle === undefined ||
-        parsed.bundle !== bundle ||
-        parsed.fragment !== undefined ||
-        !isBundleSlug(bundle) ||
-        bundleRefToString(parsed) !== ref) {
-        throw new TypeError(`${path}.ref must round-trip as the same fully-qualified bundle ref without a fragment`);
-    }
-    if (!EXECUTION_ADAPTER_ID_PATTERN.test(adapter)) {
-        throw new TypeError(`${path}.adapter must use the current lowercase kebab-case adapter identifier grammar`);
-    }
-    const segments = file.split("/");
-    if (file.startsWith("/") ||
-        WINDOWS_DRIVE_PREFIX_PATTERN.test(file) ||
-        file.includes("\\") ||
-        segments.some((segment) => !segment || segment === "." || segment === "..")) {
-        throw new TypeError(`${path}.file must be a normalized relative POSIX path`);
+const IDENTITY_KEYS = ["ref", "bundle", "adapter", "file", "hash"];
+function identityFrom(value, path) {
+    const record = requireRecord(value, path);
+    const out = {};
+    for (const key of IDENTITY_KEYS) {
+        const field = record[key];
+        if (typeof field !== "string" || field.length === 0)
+            throw new TypeError(`${path}.${key} must be a non-empty string`);
+        out[key] = field;
     }
-    if (!/^[a-f0-9]{64}$/.test(hash))
-        throw new TypeError(`${path}.hash must be a SHA-256 hex digest`);
-    return { ref, bundle, adapter, file, hash };
+    return Object.freeze(out);
 }
-/** Validate, clone, and freeze an identity produced by an adapter renderer. */
+/** Copy and freeze an identity produced by an adapter renderer. */
 export function createExecutionSourceIdentity(input) {
-    return Object.freeze(validateCanonicalIdentity(requireRecord(input, "execution source identity"), "execution source identity"));
+    return identityFrom(input, "execution source identity");
 }
-/** Validate and freeze a source identity read back from a frozen request. */
+/** Read a source identity back from a frozen request. */
 export function decodeExecutionSourceIdentity(value, path = "execution source identity") {
-    return Object.freeze(validateCanonicalIdentity(requireRecord(value, path), path));
+    return identityFrom(value, path);
 }
+/** Type-check the common frontmatter defaults; unknown keys are ignored. */
 export function cloneUnresolvedExecutionDefaults(input, path = "execution source defaults") {
     const record = requireRecord(input, path);
-    assertOnlyKeys(record, [
-        "agent",
-        "engine",
-        "model",
-        "inference",
-        "outputSchema",
-        "tools",
-        "timeout",
-        "workspace",
-        "environment",
-        "runtime",
-    ], path);
-    const json = { ...cloneExecutionJsonObject(record, path) };
+    const present = (key) => Object.hasOwn(record, key) && record[key] !== undefined;
+    const out = {};
     for (const key of ["agent", "engine", "model", "workspace"]) {
-        const value = json[key];
-        if (value !== undefined && value !== null && typeof value !== "string") {
+        if (!present(key))
+            continue;
+        const value = record[key];
+        if (value !== null && typeof value !== "string")
             throw new TypeError(`${path}.${key} must be a string or null`);
-        }
+        out[key] = value;
     }
-    const timeout = json.timeout;
-    if (timeout !== undefined && timeout !== null && typeof timeout !== "string" && typeof timeout !== "number") {
-        throw new TypeError(`${path}.timeout must be a string, number, or null`);
+    if (present("timeout")) {
+        const timeout = record.timeout;
+        if (timeout !== null && typeof timeout !== "string" && typeof timeout !== "number") {
+            throw new TypeError(`${path}.timeout must be a string, number, or null`);
+        }
+        out.timeout = timeout;
     }
     for (const key of ["inference", "outputSchema", "runtime"]) {
-        const value = json[key];
-        if (value !== undefined && value !== null && (Array.isArray(value) || typeof value !== "object")) {
-            throw new TypeError(`${path}.${key} must be an object or null`);
-        }
+        if (!present(key))
+            continue;
+        out[key] = record[key] === null ? null : cloneExecutionJsonObject(record[key], `${path}.${key}`);
     }
-    const environment = json.environment;
-    if (environment !== undefined && environment !== null) {
-        if (Array.isArray(environment) || typeof environment !== "object") {
-            throw new TypeError(`${path}.environment must be an object or null`);
-        }
-        if (Object.values(environment).some((value) => typeof value !== "string")) {
+    if (present("environment")) {
+        const environment = record.environment === null ? null : cloneExecutionJsonObject(record.environment, `${path}.environment`);
+        if (environment !== null && Object.values(environment).some((value) => typeof value !== "string")) {
             throw new TypeError(`${path}.environment values must be strings`);
         }
+        out.environment = environment;
     }
-    if (Object.hasOwn(json, "tools"))
-        json.tools = cloneToolSelection(json.tools, `${path}.tools`);
-    return Object.freeze(json);
+    if (present("tools"))
+        out.tools = cloneToolSelection(record.tools, `${path}.tools`);
+    return Object.freeze(out);
 }
 export function cloneToolSelection(value, path = "tools") {
     if (value === null || typeof value === "string")
@@ -229,92 +108,19 @@ export function cloneToolSelection(value, path = "tools") {
     return cloneExecutionJsonObject(cloned, path);
 }
 export function createAdapterRenderedExecutionSource(input) {
-    const record = requireRecord(input, "adapter-rendered execution source");
-    assertOnlyKeys(record, ["kind", "content", "identity", "defaults", "extensions"], "adapter-rendered execution source");
-    const kind = record.kind;
-    const content = record.content;
+    const { kind, content } = input;
     if (kind !== "command" && kind !== "persona")
         throw new TypeError("execution source kind is invalid");
     if (typeof content !== "string")
         throw new TypeError("execution source content must be a string");
-    const defaults = Object.hasOwn(record, "defaults") ? record.defaults : {};
-    if (defaults === undefined) {
-        throw new TypeError("execution source defaults must be omitted or be an object");
-    }
-    const source = {
+    return Object.freeze({
         schemaVersion: EXECUTION_SOURCE_SCHEMA_VERSION,
         kind,
         content,
-        defaults: cloneUnresolvedExecutionDefaults(defaults),
-        identity: createExecutionSourceIdentity(record.identity),
-    };
-    if (Object.hasOwn(record, "extensions")) {
-        source.extensions = cloneAdapterExtensions(record.extensions, "execution source extensions");
-    }
-    Object.defineProperty(source, renderedSourceBrand, { value: true, enumerable: false });
-    const frozen = Object.freeze(source);
-    renderedSourceInstances.add(frozen);
-    return frozen;
-}
-function isAdapterRenderedSource(value, kind) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    if (!renderedSourceInstances.has(value))
-        return false;
-    if (Object.getPrototypeOf(value) !== Object.prototype || !Object.isFrozen(value))
-        return false;
-    if (!Object.hasOwn(value, renderedSourceBrand))
-        return false;
-    const required = new Set(["schemaVersion", "kind", "content", "defaults", "identity"]);
-    const optional = new Set(["extensions"]);
-    for (const key of Reflect.ownKeys(value)) {
-        if (key === renderedSourceBrand)
-            continue;
-        if (typeof key !== "string" || (!required.delete(key) && !optional.has(key)))
-            return false;
-        const descriptor = Object.getOwnPropertyDescriptor(value, key);
-        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
-            return false;
-    }
-    if (required.size > 0)
-        return false;
-    const brand = Object.getOwnPropertyDescriptor(value, renderedSourceBrand);
-    const source = value;
-    if (brand?.value !== true ||
-        brand.enumerable !== false ||
-        brand.configurable !== false ||
-        brand.writable !== false ||
-        source.schemaVersion !== EXECUTION_SOURCE_SCHEMA_VERSION ||
-        source.kind !== kind ||
-        typeof source.content !== "string" ||
-        typeof source.defaults !== "object" ||
-        source.defaults === null ||
-        !Object.isFrozen(source.defaults) ||
-        typeof source.identity !== "object" ||
-        source.identity === null ||
-        Object.getPrototypeOf(source.identity) !== Object.prototype ||
-        !Object.isFrozen(source.identity)) {
-        return false;
-    }
-    if (Object.hasOwn(source, "extensions")) {
-        if (typeof source.extensions !== "object" ||
-            source.extensions === null ||
-            Object.getPrototypeOf(source.extensions) !== null ||
-            !Object.isFrozen(source.extensions)) {
-            return false;
-        }
-    }
-    try {
-        decodeExecutionSourceIdentity(source.identity);
-    }
-    catch {
-        return false;
-    }
-    return true;
-}
-export function isAdapterRenderedCommandSource(value) {
-    return isAdapterRenderedSource(value, "command");
-}
-export function isAdapterRenderedPersonaSource(value) {
-    return isAdapterRenderedSource(value, "persona");
+        defaults: cloneUnresolvedExecutionDefaults(input.defaults ?? {}),
+        identity: createExecutionSourceIdentity(input.identity),
+        ...(input.extensions
+            ? { extensions: cloneAdapterExtensions(input.extensions, "execution source extensions") }
+            : {}),
+    });
 }

package/dist/execution/target-ref.js

@@ -23,7 +23,7 @@
  * Explicit non-goals (binding, spec §4.1): no GitHub locator grammar, no
  * `akm/command` builtin special case, no resolution, no filesystem access, no
  * guessing. Callers layer builtin detection on top (see
- * `classifyWorkflowSourceUses` in src/workflows/source-ir/uses.ts).
+ * `classifyWorkflowStepUses` in src/workflows/source-semantics.ts).
  */
 import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
 import { UsageError } from "../core/errors.js";

package/dist/indexer/bundle-identity-guard.js

@@ -34,7 +34,7 @@ import { rethrowIfTestIsolationError } from "../core/errors.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
-import { isCanonicalIndexGeneration } from "../storage/repositories/index-entry-schema.js";
+import { hasCurrentEntriesTable } from "../storage/repositories/index-entry-schema.js";
 let guardSettled = false;
 /** TEST-ONLY: re-arm the once-per-process guard between cases. */
 export function resetBundleIdentityGuardForTests() {
@@ -49,7 +49,7 @@ function indexedBundlePaths(dbPath) {
         db = openReadonlyExistingDatabase(dbPath);
         if (!db)
             return undefined;
-        if (!isCanonicalIndexGeneration(db))
+        if (!hasCurrentEntriesTable(db))
             return undefined;
         return db
             .prepare("SELECT DISTINCT bundle_id AS bundleId, file_path AS filePath FROM entries " +

package/dist/indexer/db/llm-cache.js

@@ -27,10 +27,10 @@ import { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry, } from "../../s
  *                          already hashed the body (e.g. to reuse it elsewhere)
  *                          should pass this to avoid the redundant work.
  * @param cacheVariant  - Namespace token for the cache row so different passes'
- *                        rows do not collide (e.g. memory-inference vs graph).
+ *                        rows do not collide (e.g. memory-inference vs metadata-enhance).
  * @param hooks         - Optional event sink for telemetry (see {@link WithLlmCacheHooks}).
  */
-export async function withLlmCache(db, cacheKey, body, reEnrich, llmFn, validate, precomputedHash, cacheVariant = "", hooks) {
+export async function withLlmCache(db, cacheKey, body, reEnrich, llmFn, validate, precomputedHash, cacheVariant, hooks) {
     const bodyHash = precomputedHash ?? computeBodyHash(body);
     if (!reEnrich) {
         const cacheHit = bestEffort(() => {

package/dist/indexer/ensure-index.js

@@ -21,12 +21,15 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { hashContent } from "../core/adapter/adapters/shared.js";
 import { placementSpecList } from "../core/asset/asset-placement.js";
+import { ConfigError } from "../core/errors.js";
 import { classifyPathAccess } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
+import { warnVerbose } from "../core/warn.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
-import { getEntryCount, getIndexedFilePaths } from "../storage/repositories/index-entries-repository.js";
-import { isCanonicalIndexGeneration } from "../storage/repositories/index-entry-schema.js";
+import { getEntryCount, getIndexedFileHashes, getIndexedFilePaths, } from "../storage/repositories/index-entries-repository.js";
+import { hasCurrentEntriesTable } from "../storage/repositories/index-entry-schema.js";
 import { getMeta } from "../storage/repositories/index-meta-repository.js";
 import { warnOnBundleRenameDrift } from "./bundle-identity-guard.js";
 function getIndexableFiles(root, spec) {
@@ -77,11 +80,20 @@ function getIndexableFiles(root, spec) {
  *      millisecond-truncated), so the mtime test alone silently misses
  *      additions made within ~a millisecond of the previous build.
  *
+ * A file whose mtime is newer than `builtAt` is NOT automatically stale
+ * (R6): `indexWrittenAssets` upserts a fresh `content_hash` without bumping
+ * `builtAt`, so a file `ensureIndex` itself just incrementally re-indexed
+ * (for example a proposal triage just promoted into `knowledge/`) would
+ * otherwise keep tripping this check on every subsequent call, forcing the
+ * full rescan the write-path fast path exists to avoid. Only files newer
+ * than `builtAt` are hashed here, so this stays cheap — the common case is
+ * zero or a handful of such files.
+ *
  * `getIndexableFiles` applies each asset type's own relevance filter, so
  * non-indexed companion files (e.g. `package.json` next to a knowledge doc) are
  * never considered and do not produce false "new file" positives.
  */
-function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths) {
+function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths, indexedHashes) {
     const builtAtMs = builtAt ? new Date(builtAt).getTime() : Number.NaN;
     const builtAtUsable = Number.isFinite(builtAtMs);
     for (const spec of placementSpecList()) {
@@ -92,62 +104,42 @@ function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths) {
                 return true;
             if (!builtAtUsable)
                 return true;
+            let mtimeMs;
             try {
-                if (fs.statSync(file).mtimeMs > builtAtMs)
-                    return true;
+                mtimeMs = fs.statSync(file).mtimeMs;
             }
             catch {
                 return true;
             }
+            if (mtimeMs <= builtAtMs)
+                continue;
+            // Newer than the last full build — only stale if its current content
+            // actually differs from what is indexed. No stored hash means the row
+            // predates content-hash tracking, so fall back to the conservative
+            // mtime-stale answer.
+            const indexedHash = indexedHashes.get(file);
+            if (indexedHash === undefined)
+                return true;
+            let currentHash;
+            try {
+                currentHash = hashContent(fs.readFileSync(file, "utf8"));
+            }
+            catch {
+                return true;
+            }
+            if (currentHash !== indexedHash)
+                return true;
         }
     }
     return false;
 }
 /**
  * Check whether the local index is stale relative to the given stash directory.
- * Returns `true` when the index is missing, empty, or was built against a
- * different primary stash dir.
+ * Returns `true` when the index is missing, empty, was built against a
+ * different primary stash dir, or an indexable file is newer than it.
  */
 export function isIndexStale(stashDir) {
-    const dbPath = getDbPath();
-    // Raises on an index we cannot READ rather than calling it stale — "stale"
-    // sends us into an inline reindex that will fail anyway, and whose failure is
-    // reported as the misleading "proceeding with existing index" (#791).
-    assertIndexPathReadable(dbPath);
-    if (classifyPathAccess(dbPath).access === "absent")
-        return true;
-    let db;
-    try {
-        db = openExistingDatabase(dbPath);
-        if (!isCanonicalIndexGeneration(db))
-            return true;
-        const entryCount = getEntryCount(db);
-        if (entryCount === 0)
-            return true;
-        const builtAt = getMeta(db, "builtAt");
-        if (hasNewerIndexableFiles(stashDir, builtAt, getIndexedFilePaths(db)))
-            return true;
-        const storedStashDir = getMeta(db, "stashDir");
-        if (storedStashDir !== stashDir) {
-            // Check if the incoming stashDir appears in the stored stashDirs array
-            try {
-                const storedDirs = JSON.parse(getMeta(db, "stashDirs") ?? "[]");
-                if (!storedDirs.includes(stashDir))
-                    return true;
-            }
-            catch {
-                return true;
-            }
-        }
-        return false;
-    }
-    catch {
-        return true;
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
+    return !indexCanServeStash(stashDir, { requireFresh: true });
 }
 /**
  * Whether the existing index can serve queries for `stashDir` *right now* —
@@ -157,20 +149,27 @@ export function isIndexStale(stashDir) {
  * content-stale, so read paths serve it as-is. When it is false the existing
  * index has nothing relevant to return (no DB, no `entries` table, zero rows,
  * or built for a different stash), so those cases must rebuild inline.
+ * `requireFresh` also demands that no indexable file is newer than the index.
  */
-function indexCanServeStash(stashDir) {
-    // Same rule as isIndexStale: unreadable is an error, not "cannot serve" (#791).
+function indexCanServeStash(stashDir, options = {}) {
     const dbPath = getDbPath();
+    // Raises on an index we cannot READ rather than calling it unusable — that
+    // sends us into an inline reindex that will fail anyway, and whose failure
+    // is reported as the misleading "proceeding with existing index" (#791).
     assertIndexPathReadable(dbPath);
     if (classifyPathAccess(dbPath).access === "absent")
         return false;
     let db;
     try {
         db = openExistingDatabase(dbPath);
-        if (!isCanonicalIndexGeneration(db))
+        if (!hasCurrentEntriesTable(db))
             return false;
         if (getEntryCount(db) === 0)
             return false;
+        if (options.requireFresh &&
+            hasNewerIndexableFiles(stashDir, getMeta(db, "builtAt"), getIndexedFilePaths(db), getIndexedFileHashes(db))) {
+            return false;
+        }
         const storedStashDir = getMeta(db, "stashDir");
         if (storedStashDir === stashDir)
             return true;
@@ -182,7 +181,10 @@ function indexCanServeStash(stashDir) {
             return false;
         }
     }
-    catch {
+    catch (error) {
+        // A newer layout's refusal names the remedy; a rebuild would refuse too.
+        if (error instanceof ConfigError)
+            throw error;
         // No `entries` table (or otherwise unreadable) — cannot serve.
         return false;
     }
@@ -191,16 +193,6 @@ function indexCanServeStash(stashDir) {
             closeDatabase(db);
     }
 }
-async function runInlineReindex(stashDir, options = {}) {
-    const { akmIndex } = await import("./indexer.js");
-    await akmIndex({
-        stashDir,
-        implicit: true,
-        ...(options.signal ? { signal: options.signal } : {}),
-        ...(options.hydrateSources === false ? { hydrateSources: false } : {}),
-    });
-    return true;
-}
 /**
  * Ensure the local index exists and can serve the caller.
  *
@@ -221,20 +213,32 @@ export async function ensureIndex(stashDir, options = {}) {
     // §11.5: warn (once) if the configured bundle ids drifted from the persisted
     // index prefixes (hand-renamed bundle key) BEFORE any rebuild could re-mint.
     warnOnBundleRenameDrift();
-    if (options.mode === "blocking") {
-        // Blocking callers (improve's planning preflight) are a sanctioned
-        // materialization point — hydrate cache-backed sources as usual.
-        if (!isIndexStale(stashDir))
-            return false;
-        return runInlineReindex(stashDir, { ...(options.signal ? { signal: options.signal } : {}) });
-    }
-    // Background = the READ path (`show` auto-index): query time must never clone/
-    // pull/fetch (spec §14.3 / D11). Build from already-materialized content only;
-    // absent source caches are skipped with a warning, not fetched.
-    if (indexCanServeStash(stashDir))
+    const blocking = options.mode === "blocking";
+    if (indexCanServeStash(stashDir, { requireFresh: blocking }))
         return false;
-    return runInlineReindex(stashDir, {
+    const { akmIndex } = await import("./indexer.js");
+    const startedMs = Date.now();
+    const response = await akmIndex({
+        stashDir,
+        implicit: true,
         ...(options.signal ? { signal: options.signal } : {}),
-        hydrateSources: false,
+        // Blocking callers (improve's planning preflight) are a sanctioned
+        // materialization point and hydrate cache-backed sources as usual. The
+        // background READ path (`show` auto-index) must never clone/pull/fetch at
+        // query time (spec §14.3 / D11): it builds from already-materialized
+        // content, and absent source caches are skipped with a warning.
+        ...(blocking ? {} : { hydrateSources: false }),
     });
+    // R6: the implicit reindex's cost was previously discarded entirely
+    // (`await akmIndex(...)` and nothing else), making a 27-minute blocking
+    // rebuild invisible to both the operator and the improve result. Fall back
+    // to a wall-clock measurement when the response carries no `timing` block.
+    const durationMs = response.timing?.totalMs ?? Date.now() - startedMs;
+    const timing = response.timing;
+    warnVerbose(`[ensure-index] implicit reindex completed in ${durationMs}ms` +
+        (timing
+            ? ` (walk=${timing.walkMs}ms llm=${timing.llmMs}ms embed=${timing.embedMs}ms finalize=${timing.finalizeMs}ms)`
+            : ""));
+    options.onReindexTiming?.({ durationMs, timing });
+    return true;
 }