akm-cli 0.9.10 → 0.9.12

package/dist/core/json-schema.js

@@ -61,15 +61,9 @@ import { isRecord } from "./common.js";
  * same schema tree, so they share one bound.
  */
 const MAX_DEFINITION_DEPTH = 64;
-/** Total (schema node × value node) visits one {@link validateJsonSchemaSubset} call may make. */
-const MAX_VALIDATION_NODES = 100_000;
 export function validateJsonSchemaSubset(value, schema, options) {
     const errors = [];
-    const budget = { nodes: MAX_VALIDATION_NODES };
-    validateNode(value, schema, "$", { errors, budget, depth: 0, redactValues: options?.redactValues ?? false });
-    if (budget.nodes < 0) {
-        errors.push(`$: schema evaluation exceeded the limit of ${MAX_VALIDATION_NODES} checks and was stopped`);
-    }
+    validateNode(value, schema, "$", { errors, depth: 0, redactValues: options?.redactValues ?? false });
     return errors;
 }
 /** Human-readable list of the keywords {@link validateJsonSchemaSubset} enforces (for error messages). */
@@ -372,10 +366,6 @@ function validateNode(value, schema, path, ctx) {
         errors.push(`${path}: schema nesting exceeds the depth limit of ${MAX_DEFINITION_DEPTH}`);
         return;
     }
-    // Fail CLOSED: a truncated evaluation never returns "valid" — the counter
-    // going negative is what the wrapper turns into a top-level error.
-    if (--ctx.budget.nodes < 0)
-        return;
     const actual = typeOf(value);
     const declared = schema.type;
     if (typeof declared === "string" || Array.isArray(declared)) {

package/dist/core/maintenance-barrier.js

@@ -10,6 +10,20 @@ import { ConfigError } from "./errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "./file-lock.js";
 import { getMaintenanceBarrierPath } from "./paths.js";
 const heldBarrierContext = new AsyncLocalStorage();
+/**
+ * The barrier is meant to be held only for the short critical section that
+ * registers one lock/lease/activity — a process that still holds it past
+ * this age is wedged (crashed mid-section, deadlocked, killed without
+ * cleanup), not doing legitimate long-running work. Without an age bound, a
+ * probe only reclaims a lock whose holder PID has verifiably died; a wedged
+ * — but still-alive — holder (or a PID a container/namespace boundary
+ * reused, making `isProcessAlive` see the wrong process as live) locked
+ * every other akm invocation out of ANY maintenance registration forever,
+ * with no recovery but killing the holder by hand.  5 minutes matches the
+ * stale-lock window already used for the improve extract-session lock
+ * (`commands/improve/extract.ts`).
+ */
+const MAINTENANCE_BARRIER_STALE_AFTER_MS = 5 * 60 * 1000;
 /**
  * Serialize the short critical section that creates each long-lived AKM lock,
  * lease, or state activity. The operation keeps its own ownership record; this
@@ -23,7 +37,7 @@ export function tryAcquireMaintenanceBarrier() {
         if (ownership) {
             return () => releaseLock(ownership);
         }
-        const probe = probeLock(lockPath);
+        const probe = probeLock(lockPath, { staleAfterMs: MAINTENANCE_BARRIER_STALE_AFTER_MS });
         if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
             return undefined;
     }
@@ -33,7 +47,8 @@ export function acquireMaintenanceBarrier() {
     const release = tryAcquireMaintenanceBarrier();
     if (release)
         return release;
-    throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes.`, "INVALID_CONFIG_FILE");
+    throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes. ` +
+        `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60_000} minute(s) is reclaimed automatically on the next attempt.`, "INVALID_CONFIG_FILE");
 }
 export function withMaintenanceStartBarrier(run) {
     if (heldBarrierContext.getStore()?.active)

package/dist/core/paths.js

@@ -10,8 +10,10 @@
  */
 import os from "node:os";
 import path from "node:path";
+import { shortHash } from "./bundle-id.js";
 import { ConfigError } from "./errors.js";
 import { IS_WINDOWS } from "./platform.js";
+import { warnOnce } from "./warn.js";
 /**
  * Returns true when the current process appears to be running under
  * `bun test` (either via the BUN_TEST sentinel Bun sets on the test
@@ -257,6 +259,117 @@ export function getRegistryCacheDir() {
 export function getRegistryIndexCacheDir() {
     return path.join(getCacheDir(), "registry-index");
 }
+// ── State directory ──────────────────────────────────────────────────────────
+/**
+ * Returns the XDG state directory for akm (`~/.local/state/akm` on
+ * Linux/macOS, `%LOCALAPPDATA%\akm\state` on Windows).
+ *
+ * Per-machine runtime state that is neither durable application data
+ * (`$DATA`), a purely regenerable cache (`$CACHE`), nor state that must
+ * travel with a bundle's own content (`$STASH/.akm`; see "What May Live in
+ * $STASH/.akm" in docs/architecture/internals/storage-locations.md).
+ *
+ * Env overrides (in priority order):
+ *   AKM_STATE_DIR  — point to any directory
+ *   XDG_STATE_HOME — (Linux/macOS) override the XDG base; akm subdir is appended
+ */
+export function getStateDir(env = process.env, platform = process.platform) {
+    const override = env.AKM_STATE_DIR?.trim();
+    if (override)
+        return override;
+    if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "akm", "state");
+        const userProfile = env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "akm", "state");
+        const appData = env.APPDATA?.trim();
+        if (!appData) {
+            throw new ConfigError("Unable to determine state directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
+        }
+        return path.join(appData, "..", "Local", "akm", "state");
+    }
+    const xdgStateHome = env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome)
+        return path.join(xdgStateHome, "akm");
+    const home = env.HOME?.trim();
+    if (!home)
+        return homelessFallbackDir("akm-state");
+    return path.join(home, ".local", "state", "akm");
+}
+// ── Per-stash state under $STATE / $CACHE (itlackey/akm#890) ─────────────────
+/**
+ * Deterministic, filesystem-safe key for machine-local state that belongs to
+ * one stash but must not live under `$STASH` itself. Namespaces `$STATE`/
+ * `$CACHE` writers by the resolved absolute stash directory — the filesystem
+ * counterpart of how `state.db`'s `proposals` table keys per-stash rows by
+ * its `stash_dir` column — so two stashes on one machine never collide.
+ *
+ * Reuses {@link shortHash} (bundle-id.ts) rather than growing a second
+ * sha256-truncated-hex helper. (The other existing option,
+ * `getCurrentWorkflowScopeKey`'s `dir:v1:<sha256>` in
+ * `src/workflows/authoring/scope-key.ts`, is a state.db column value for a
+ * different subsystem — full untruncated hex plus a `dir:v1:` prefix, which
+ * is neither filesystem-safe as a directory segment on Windows (`:`) nor
+ * short, so it is not a fit here.) `shortHash` trims to 8 hex chars (32
+ * bits) — fine at its original call site because a collision only ever
+ * shortens a batch-unique slug suffix that a retry loop immediately
+ * re-disambiguates. Here there is no such retry loop, but a machine
+ * realistically has, at most, a handful to a few dozen distinct stash
+ * directories ever registered — 32 bits of digest space makes an accidental
+ * collision between two of them astronomically unlikely.
+ */
+export function getStashStateKey(stashDir) {
+    const resolved = path.resolve(stashDir).replace(/\\/g, "/");
+    const normalized = IS_WINDOWS ? resolved.toLowerCase() : resolved;
+    return shortHash(normalized);
+}
+function stashScopedDir(base, stashDir) {
+    return path.join(base, getStashStateKey(stashDir));
+}
+/**
+ * `$STATE/improve/distill-rejected/<stash>/` — lessons that failed the
+ * distill quality gate. Moved out of `$STASH/.akm/distill-rejected/`
+ * (itlackey/akm#890): nothing reads it to resolve bundle content, so it does
+ * not meet the "must travel with the content" rule.
+ */
+export function getDistillRejectedDir(stashDir) {
+    return stashScopedDir(path.join(getStateDir(), "improve", "distill-rejected"), stashDir);
+}
+/**
+ * `$STATE/improve/eval-cases/<stash>/` — regression eval cases captured from
+ * rejected distill/proposal output. Moved out of `$STASH/.akm/eval-cases/`
+ * (itlackey/akm#890).
+ */
+export function getEvalCasesDir(stashDir) {
+    return stashScopedDir(path.join(getStateDir(), "improve", "eval-cases"), stashDir);
+}
+/**
+ * `$STATE/improve/measurement/verdicts/<stash>/` — `akm-eval-proactive-verdict`
+ * reports. Moved out of `$STASH/.akm/measurement/verdicts/` (itlackey/akm#890);
+ * the pilot treatment file at `$STASH/.akm/measurement/` is manually-authored
+ * measurement input and stays put.
+ */
+export function getMeasurementVerdictsDir(stashDir) {
+    return stashScopedDir(path.join(getStateDir(), "improve", "measurement", "verdicts"), stashDir);
+}
+/**
+ * `$CACHE/index/unresolved-sources/<stash>/` — synthetic placeholder path for
+ * a configured source whose content root did not resolve this run. Never
+ * written to disk; only used as a stable, reportable `SearchSource.path`.
+ * Moved out of `$STASH/.akm/unresolved-sources/` (itlackey/akm#890).
+ */
+export function getUnresolvedSourcesDir(stashDir) {
+    return stashScopedDir(path.join(getCacheDir(), "index", "unresolved-sources"), stashDir);
+}
+/**
+ * `$STATE/locks/<stash>/` — per-stash operational lock files for the improve
+ * pipeline (e.g. `improve.lock`). Moved out of `$STASH/.akm/` (itlackey/akm#890).
+ */
+export function getStashLocksDir(stashDir) {
+    return stashScopedDir(path.join(getStateDir(), "locks"), stashDir);
+}
 // ── Scheduled-task runtime directories (logs + history) ──────────────────────
 export function getTaskLogDir() {
     return path.join(getCacheDir(), "tasks", "logs");
@@ -312,7 +425,6 @@ export function assertSafeStashDir(stashDir, env = process.env) {
     const SYSTEM_ROOTS = new Set([
         "/etc",
         "/var",
-        "/var/tmp",
         "/usr",
         "/usr/local",
         "/opt",
@@ -336,6 +448,9 @@ export function assertSafeStashDir(stashDir, env = process.env) {
     if (SYSTEM_ROOTS.has(resolved)) {
         throw new ConfigError(`Refusing stashDir at system path (${resolved}). Pick a path inside your home directory.`, "UNSAFE_STASH_DIR");
     }
+    if (resolved === "/var/tmp") {
+        warnOnce("stash-dir:var-tmp", `Stash directory is at ${resolved}, a shared scratch directory system cleanup jobs may periodically empty; using it as configured.`);
+    }
     // User home — exact match only. Subdirs (~/akm, ~/work/stash) are fine.
     // Check BOTH the env-controlled home and the OS-reported home, so the
     // refusal can't be bypassed by unsetting HOME, and so it still fires
@@ -353,27 +468,21 @@ export function assertSafeStashDir(stashDir, env = process.env) {
     catch {
         // os.homedir() can throw on misconfigured systems; ignore.
     }
-    const HIDDEN_USER_PARENTS = [
-        ".config",
-        ".local",
-        ".cache",
-        ".ssh",
-        ".gnupg",
-        ".aws",
-        ".kube",
-        ".docker",
-        "Documents",
-        "Downloads",
-        "AppData",
-    ];
+    const CREDENTIAL_USER_PARENTS = [".config", ".local", ".cache", ".ssh", ".gnupg", ".aws", ".kube", ".docker"];
+    const PLAIN_USER_DATA_PARENTS = ["Documents", "Downloads", "AppData"];
     for (const home of candidateHomes) {
         if (resolved === home) {
             throw new ConfigError(`Refusing stashDir at your home directory (${resolved}). Pick a subdirectory like ~/akm.`, "UNSAFE_STASH_DIR");
         }
-        for (const sub of HIDDEN_USER_PARENTS) {
+        for (const sub of CREDENTIAL_USER_PARENTS) {
             if (resolved === path.join(home, sub)) {
                 throw new ConfigError(`Refusing stashDir at sensitive user directory (${resolved}). Pick a subdirectory or a dedicated workspace.`, "UNSAFE_STASH_DIR");
             }
         }
+        for (const sub of PLAIN_USER_DATA_PARENTS) {
+            if (resolved === path.join(home, sub)) {
+                warnOnce(`stash-dir:plain-user-data:${sub}`, `Stash directory is at ${resolved}, your ${sub} folder; using it as configured, though it is usually a large, unrelated-content directory to index.`);
+            }
+        }
     }
 }

package/dist/core/state/migrations.js

@@ -37,6 +37,7 @@ export const STATE_MIGRATION_SAFETY_BY_ID = Object.freeze({
     "024-workflow-run-outputs": "additive",
     "025-task-history-vocabulary-backfill": "data-preserving-rebuild",
     "026-proposals-strip-legacy-fragment-refs": "data-preserving-rebuild",
+    "027-extract-sessions-seen-harness-rename": "data-preserving-rebuild",
 });
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
@@ -1149,6 +1150,33 @@ export const STATE_MIGRATIONS = [
       WHERE ref LIKE '%#%';
     `,
     },
+    // ── Migration 027 — claude-code -> claude harness rename (#915) ──
+    //
+    // The 0.9.2 rename shipped without a data migration, so rows written under
+    // the old key were invisible to every reader keyed on "claude".
+    //
+    // `extract_sessions_seen` has PRIMARY KEY (harness, session_id), so a
+    // session already recorded under "claude" (written by a run that really
+    // happened post-rename) collides with its "claude-code" counterpart on
+    // rename. `UPDATE OR IGNORE` keeps the newer "claude" row exactly as it
+    // was — the older row's outcome is superseded, not more correct — and the
+    // trailing DELETE drops that now-unreachable duplicate so the "claude-code"
+    // key space is fully empty afterwards, not just mostly-migrated.
+    //
+    // `workflow_runs.agent_harness` (migration 020) has no uniqueness
+    // constraint on that column, so a plain UPDATE is sufficient there. Both
+    // statements are kept in one migration so the rename is a single ledger
+    // event. `improve_runs.result_json` is deliberately untouched: the harness
+    // name embedded in those JSON blobs is reporting data about a past run, not
+    // a lookup key, so rewriting it would not fix anything a reader depends on.
+    {
+        id: "027-extract-sessions-seen-harness-rename",
+        up: `
+      UPDATE OR IGNORE extract_sessions_seen SET harness = 'claude' WHERE harness = 'claude-code';
+      DELETE FROM extract_sessions_seen WHERE harness = 'claude-code';
+      UPDATE workflow_runs SET agent_harness = 'claude' WHERE agent_harness = 'claude-code';
+    `,
+    },
 ];
 assertMigrationRegistry(STATE_MIGRATIONS);
 function assertStateMigrationSafetyRegistry() {

package/dist/core/state-db.js

@@ -69,9 +69,11 @@ import { sleepSync } from "../runtime.js";
 import { openDatabase } from "../storage/database.js";
 import { assertMigrationLedger } from "../storage/engines/sqlite-migrations.js";
 import { openManagedDatabase, withManagedDb } from "../storage/managed-db.js";
+import { pkgVersion } from "../version.js";
 import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
 import { getDataDir } from "./paths.js";
 import { runMigrations, STATE_MIGRATIONS } from "./state/migrations.js";
+import { warnOnce } from "./warn.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/state.db`.
@@ -370,6 +372,25 @@ function createHistoricalStateSafetyCopy(source, migrationId) {
  *     matches the value used in openDatabase() for index.db; 5 s proved too
  *     narrow when a post-inference reindex overlapped a parallel event write.
  */
+/**
+ * Tell the operator once when state.db was migrated by a newer akm than the
+ * one running. The open proceeds: every migration this binary knows is already
+ * applied, so it reads and writes the tables it knows. Commands that depend on
+ * something a later migration changed may still report less than the truth,
+ * which is why this is said out loud rather than swallowed.
+ */
+function warnNewerStateLedger(ledger) {
+    if (ledger.status !== "newer")
+        return;
+    warnOnce("state-db-newer-ledger", `[state.db] This akm (v${pkgVersion}) is older than the state database: ${ledger.detail}. ` +
+        "Continuing with the schema this version knows; upgrade akm if its output looks incomplete.");
+}
+function unversionedDatabaseHasNoTables(db) {
+    const tables = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name != ?")
+        .get("schema_migrations");
+    return !tables;
+}
 export function openStateDatabase(dbPath, options) {
     const canonicalPath = getStateDbPath();
     const resolvedPath = dbPath ?? canonicalPath;
@@ -392,6 +413,7 @@ export function openStateDatabase(dbPath, options) {
     let existingSource;
     let openedDb;
     let existingUnversionedDatabase = false;
+    let treatUnversionedAsFresh = false;
     let stateSafetyCopyCreated = false;
     try {
         fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
@@ -404,7 +426,12 @@ export function openStateDatabase(dbPath, options) {
             try {
                 preflight.exec("PRAGMA busy_timeout = 30000");
                 const ledger = assertMigrationLedger(preflight, STATE_MIGRATIONS);
+                warnNewerStateLedger(ledger);
                 existingUnversionedDatabase = ledger.migrationIds.length === 0;
+                if (existingUnversionedDatabase && unversionedDatabaseHasNoTables(preflight)) {
+                    existingUnversionedDatabase = false;
+                    treatUnversionedAsFresh = true;
+                }
                 if (existingUnversionedDatabase && !options?.allowHistoricalDestructiveStateUpgrade) {
                     throw new Error("Refusing to migrate an existing unversioned state.db during an ordinary managed open. " +
                         "Run `akm upgrade` (or `akm migrate apply`) to create a verified snapshot before migration 001 " +
@@ -421,7 +448,7 @@ export function openStateDatabase(dbPath, options) {
             pragmas: { dataDir: path.dirname(resolvedPath) },
             init: (db) => {
                 runMigrations(db, {
-                    freshDatabase: !!freshReservation,
+                    freshDatabase: !!freshReservation || treatUnversionedAsFresh,
                     existingUnversionedDatabase,
                     allowHistoricalDestructiveStateUpgrade: options?.allowHistoricalDestructiveStateUpgrade,
                     beforeExistingUnversionedStateMigration: options?.allowHistoricalDestructiveStateUpgrade

package/dist/core/write-source.js

@@ -37,7 +37,7 @@ import { existingFileMode, isWithin, resolveStashDir, writeFileAtomic } from "./
 import { bundleContentRoot, resolveConfiguredSources } from "./config/config.js";
 import { ConfigError, UsageError } from "./errors.js";
 import { sanitizeCommitMessage } from "./git-message.js";
-import { warn } from "./warn.js";
+import { warn, warnOnce } from "./warn.js";
 import { recordWrittenPath } from "./write-provenance.js";
 /**
  * Source kinds that the loader is allowed to mark `writable: true`. Anything
@@ -872,10 +872,10 @@ export function prepareWriteTargetForMutation(target, options = {}) {
     }
     const upstream = inspectGitUpstream(repoPath);
     if (upstream.behind > 0) {
-        throw new UsageError(`Writable Git target "${target.source.name}" is behind ${upstream.upstream}; run \`akm bundle update ${target.source.name}\` before writing.`, "INVALID_FLAG_VALUE");
+        warnOnce(`write-source:git-behind:${realRepoPath}`, `Writable Git target "${target.source.name}" is ${upstream.behind} commit(s) behind ${upstream.upstream}; writing anyway. Run \`akm bundle update ${target.source.name}\` to catch up.`);
     }
-    if (upstream.ahead > 0 && options.allowAhead !== true) {
-        throw new UsageError(`Writable Git target "${target.source.name}" has unpushed commits; push or reconcile them before AKM writes another commit.`, "INVALID_FLAG_VALUE");
+    if (upstream.ahead > 0) {
+        warnOnce(`write-source:git-ahead:${realRepoPath}`, `Writable Git target "${target.source.name}" has ${upstream.ahead} unpushed commit(s); writing another on top. Push or reconcile them when convenient.`);
     }
     return {
         ...target,
@@ -997,7 +997,7 @@ const WINDOWS_RESERVED_DEVICE_NAMES = new Set([
 function resolveAssetFilePath(source, ref) {
     const basename = path.posix.basename(ref.name.replaceAll("\\", "/")).replace(/\.md$/i, "").toLowerCase();
     if (basename === "index" || basename === "log") {
-        throw new UsageError(`Reserved concept name "${basename}" cannot be written.`, "INVALID_FLAG_VALUE");
+        warnOnce(`write-source:reserved-basename:${basename}`, `Concept name "${basename}" collides with a reserved word some tooling treats specially; writing it anyway.`);
     }
     // Windows resolves these names as DEVICES no matter the directory or the
     // extension, so `CON.md` is not a file — a write goes to the console and a
@@ -1005,7 +1005,7 @@ function resolveAssetFilePath(source, ref) {
     // portable: an asset authored on Linux must not become unopenable when the
     // same bundle is used on Windows.
     if (WINDOWS_RESERVED_DEVICE_NAMES.has(basename)) {
-        throw new UsageError(`Asset name "${basename}" is a reserved Windows device name and cannot be written.`, "INVALID_FLAG_VALUE");
+        warnOnce(`write-source:windows-device-name:${basename}`, `Asset name "${basename}" is a reserved Windows device name; writing it anyway, but this bundle will not be portable to Windows.`);
     }
     const typeDir = stashDirFor(ref.type);
     if (!typeDir) {

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

@@ -33,6 +33,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";
 let guardSettled = false;
 /** TEST-ONLY: re-arm the once-per-process guard between cases. */
 export function resetBundleIdentityGuardForTests() {
@@ -47,6 +48,8 @@ function indexBundlePrefixes(dbPath) {
         db = openReadonlyExistingDatabase(dbPath);
         if (!db)
             return undefined;
+        if (!isCanonicalIndexGeneration(db))
+            return undefined;
         return db
             .prepare("SELECT DISTINCT bundle_id AS b FROM entries WHERE bundle_id IS NOT NULL AND bundle_id != ''")
             .all().map((row) => row.b);

package/dist/indexer/ensure-index.js

@@ -26,6 +26,7 @@ import { classifyPathAccess } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.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 { getMeta } from "../storage/repositories/index-meta-repository.js";
 import { warnOnBundleRenameDrift } from "./bundle-identity-guard.js";
 function getIndexableFiles(root, spec) {
@@ -118,6 +119,8 @@ export function isIndexStale(stashDir) {
     let db;
     try {
         db = openExistingDatabase(dbPath);
+        if (!isCanonicalIndexGeneration(db))
+            return true;
         const entryCount = getEntryCount(db);
         if (entryCount === 0)
             return true;
@@ -164,6 +167,8 @@ function indexCanServeStash(stashDir) {
     let db;
     try {
         db = openExistingDatabase(dbPath);
+        if (!isCanonicalIndexGeneration(db))
+            return false;
         if (getEntryCount(db) === 0)
             return false;
         const storedStashDir = getMeta(db, "stashDir");

package/dist/indexer/indexer.js

@@ -1770,9 +1770,17 @@ async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase) {
                 const entry = readLookupEntry(db, id, ref.conceptId, source.path);
                 if (entry) {
                     if (owner.workflowSource) {
-                        assertIndexedWorkflowSourceIdentity(inputRef, entry.filePath, owner.workflowSource);
-                        if (entry.adapterId !== adapterId) {
-                            throw new WorkflowSourceIdentityError(inputRef, entry.filePath, owner.path);
+                        try {
+                            assertIndexedWorkflowSourceIdentity(inputRef, entry.filePath, owner.workflowSource);
+                            if (entry.adapterId !== adapterId) {
+                                throw new WorkflowSourceIdentityError(inputRef, entry.filePath, owner.path);
+                            }
+                        }
+                        catch (error) {
+                            if (!(error instanceof WorkflowSourceIdentityError))
+                                throw error;
+                            warn(`${error.message} Falling back to the physical owner.`);
+                            return { entry: null, owner, ...(indexError === undefined ? {} : { indexError }) };
                         }
                     }
                     else if (entry.adapterId !== adapterId || !indexedPathMatchesOwner(entry.filePath, owner)) {

package/dist/indexer/lookup/adapter-concept-owner.js

@@ -7,6 +7,7 @@ import { adapterForId } from "../../core/adapter/registry.js";
 import { compareCodePoints, hasErrnoCode, isWithin } from "../../core/common.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
+import { warnOnce } from "../../core/warn.js";
 import { resolveUniqueWorkflowSource, workflowNameForConceptId, } from "../../workflows/source-files.js";
 import { buildFileContext } from "../walk/file-context.js";
 const CONTENT_READ_REQUIRED = Symbol("adapter ownership probe requires content");
@@ -123,7 +124,7 @@ function claimsWithoutContent(adapter, component, owner) {
  * adapter supplies its own read placements and is probed with a byte-denying
  * FileContext so path-level abstention remains authoritative.
  */
-export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId) {
+export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId, options) {
     const adapter = adapterForId(adapterId);
     const normalized = normalizedConceptId(conceptId);
     if (!adapter || !normalized)
@@ -185,9 +186,19 @@ export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId) {
         if (claimsWithoutContent(adapter, component, candidate))
             ownersByIdentity.set(identity, candidate);
     }
-    const owners = [...ownersByIdentity.values()].filter((owner) => owner.conceptId === resolutionConceptId);
+    const owners = [...ownersByIdentity.values()]
+        .filter((owner) => owner.conceptId === resolutionConceptId)
+        .sort((left, right) => compareCodePoints(left.path, right.path));
     if (owners.length > 1) {
-        throw new AdapterConceptCollisionError(adapterId, resolutionConceptId, owners.map((owner) => path.relative(sourcePath, owner.path).replaceAll("\\", "/")));
+        if (options?.mode !== "read") {
+            throw new AdapterConceptCollisionError(adapterId, resolutionConceptId, owners.map((owner) => path.relative(sourcePath, owner.path).replaceAll("\\", "/")));
+        }
+        const [winner, ...losers] = owners;
+        warnOnce(`adapter-concept-collision:${adapterId}:${resolutionConceptId}`, `Adapter "${adapterId}" has multiple physical owners for "${resolutionConceptId}": ` +
+            `${owners.map((owner) => path.relative(sourcePath, owner.path).replaceAll("\\", "/")).join(", ")}. ` +
+            `Reading "${path.relative(sourcePath, winner.path).replaceAll("\\", "/")}" and ignoring ` +
+            `${losers.map((owner) => path.relative(sourcePath, owner.path).replaceAll("\\", "/")).join(", ")}.`);
+        return winner;
     }
     return owners[0];
 }

package/dist/indexer/passes/metadata.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { asNonEmptyString } from "../../core/common.js";
-import { isVerbose, warn, warnVerbose } from "../../core/warn.js";
+import { isVerbose, warn } from "../../core/warn.js";
 export const SCOPE_KEYS = ["user", "agent", "run", "channel"];
 // ── Quality semantics (v1 spec §4.2) ────────────────────────────────────────
 /**
@@ -835,10 +835,17 @@ export function isEnrichmentComplete(entry) {
 // ── Native Markdown search projection ──────────────────────────────────────
 /**
  * Maximum native Markdown prose carried by the low-weight `content` field.
- * Structured fields remain separate and higher-weighted; this bound prevents
- * large documents from dominating index size or embedding inputs.
+ *
+ * Raised far past any real authored document:
+ * this used to sit at 16_384 chars, tight enough that ordinary long-form
+ * skills/knowledge docs lost their tail from both FTS and the embedding
+ * input with no visible signal (the cut was reported via `warnVerbose`,
+ * silent unless `AKM_VERBOSE` was set). The remaining bound exists only to
+ * stop a truly pathological single file (a committed data dump, a decompressed
+ * log) from ballooning index size — not to shave real content — so a caller
+ * that hits it is always told, unconditionally.
  */
-export const MARKDOWN_CONTENT_MAX_CHARS = 16_384;
+export const MARKDOWN_CONTENT_MAX_CHARS = 1_000_000;
 /**
  * Locate a leading nested frontmatter block in a body: up to three blank
  * lines, then a `---` line, closed by a later `---` line. Mirrors the
@@ -1220,7 +1227,11 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
                 entry.content = contentProjection;
                 if (truncationInfo.truncated) {
                     entry.contentTruncated = true;
-                    warnVerbose(`${file}: indexed content truncated to ${MARKDOWN_CONTENT_MAX_CHARS} chars`);
+                    // Unconditional, not warnVerbose: this bound now sits far past any
+                    // real document, so tripping it means
+                    // something unusual is in the bundle and the operator should see
+                    // it without having to pass --verbose.
+                    warn(`${file}: indexed content truncated to ${MARKDOWN_CONTENT_MAX_CHARS} chars`);
                 }
             }
         }

package/dist/indexer/search/search-fields.js

@@ -1,18 +1,6 @@
 // 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/.
-/**
- * Per-field search text extraction for FTS5 indexing.
- *
- * Extracted from indexer.ts to break the circular dependency:
- *   db.ts -> indexer.ts -> db.ts
- *
- * This module imports only from metadata.ts (for the IndexDocument type),
- * so it can be safely imported by both db.ts and indexer.ts.
- */
-import { warnVerbose } from "../../core/warn.js";
-/** Structured metadata plus bounded body text supplied to embedding providers. */
-export const SEARCH_TEXT_MAX_CHARS = 8_192;
 /**
  * Return per-field search text for multi-column FTS5 indexing.
  *
@@ -90,25 +78,8 @@ export function buildSearchText(entry) {
     const structured = [fields.name, fields.description, fields.tags, fields.hints]
         .filter((field) => field.length > 0)
         .join(" ");
-    if (structured.length >= SEARCH_TEXT_MAX_CHARS) {
-        warnVerbose(`${entry.ref ?? entry.name}: search text truncated to ${SEARCH_TEXT_MAX_CHARS} chars (content dropped entirely)`);
-        return truncateUnicodeSafe(structured, SEARCH_TEXT_MAX_CHARS);
-    }
     if (!fields.content)
         return structured;
     const separator = structured ? " " : "";
-    const remaining = SEARCH_TEXT_MAX_CHARS - structured.length - separator.length;
-    if (fields.content.length > remaining) {
-        warnVerbose(`${entry.ref ?? entry.name}: search text truncated to ${SEARCH_TEXT_MAX_CHARS} chars`);
-    }
-    return `${structured}${separator}${truncateUnicodeSafe(fields.content, remaining)}`;
-}
-function truncateUnicodeSafe(text, maxChars) {
-    if (text.length <= maxChars)
-        return text;
-    let cut = text.slice(0, maxChars);
-    const lastCode = cut.charCodeAt(cut.length - 1);
-    if (lastCode >= 0xd800 && lastCode <= 0xdbff)
-        cut = cut.slice(0, -1);
-    return cut.trimEnd();
+    return `${structured}${separator}${fields.content}`;
 }

package/dist/indexer/search/search-source.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { bundleComponentConfig, bundlesToSourceEntries, getSources, loadConfig } from "../../core/config/config.js";
+import { getUnresolvedSourcesDir } from "../../core/paths.js";
 import { resolveGitContentRoot, resolveWritable } from "../../core/write-source.js";
 import { lockContentRootFor } from "../../integrations/lockfile.js";
 import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
@@ -86,14 +87,14 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
         const component = bundleComponentConfig(config.bundles?.[entry.name ?? ""]);
         const contentRoot = resolveEntryContentDir(entry);
         if (contentRoot == null) {
-            const unresolvedPath = path.join(implicitStashDir ?? process.cwd(), ".akm", "unresolved-sources", entry.name ?? entry.type);
+            const unresolvedPath = path.join(getUnresolvedSourcesDir(implicitStashDir ?? process.cwd()), entry.name ?? entry.type);
             addSource(unresolvedPath, entry.name, component?.writable ?? resolveWritable(entry), entry.type, component?.adapter, true);
             continue;
         }
         const dir = path.resolve(contentRoot, component?.root ?? ".");
         if (!isWithin(dir, contentRoot)) {
             warn(`Warning: component root "${component?.root}" escapes bundle "${entry.name}"; skipping source.`);
-            const unresolvedPath = path.join(contentRoot, ".akm", "unresolved-sources", entry.name ?? entry.type);
+            const unresolvedPath = path.join(getUnresolvedSourcesDir(contentRoot), entry.name ?? entry.type);
             addSource(unresolvedPath, entry.name, component?.writable ?? resolveWritable(entry), entry.type, component?.adapter, true);
             continue;
         }