akm-cli 0.9.11 → 0.9.12

package/dist/core/improve-types.js

@@ -49,6 +49,23 @@ export function classifyImproveAction(mode) {
             return assertNever(mode);
     }
 }
+/**
+ * #912 — skip reasons that mean infrastructure failed to run the extraction,
+ * not that a session was legitimately uninteresting. `already_extracted`,
+ * `too_short`, and `triaged_out` are the ledger and pre-filter doing their
+ * job and are deliberately excluded; `malformed_model_output` already gets
+ * its own per-session forwarding into the envelope's `warnings[]` and is
+ * excluded here to avoid double-reporting the same failure two ways.
+ *
+ * Typed against `ExtractedSessionResult["skipReason"]` so a future reason
+ * cannot be added to one union without a compiler error surfacing here.
+ */
+export const EXTRACT_INFRASTRUCTURE_SKIP_REASONS = [
+    "llm_unavailable",
+    "read_failed",
+    "exception",
+    "locked_concurrent",
+];
 /** Upper bound on retained sample refs PER reason in {@link DistillSkippedAggregate}. */
 export const DISTILL_SKIPPED_SAMPLE_CAP_PER_REASON = 3;
 /**

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

@@ -13,6 +13,7 @@ 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
@@ -424,7 +425,6 @@ export function assertSafeStashDir(stashDir, env = process.env) {
     const SYSTEM_ROOTS = new Set([
         "/etc",
         "/var",
-        "/var/tmp",
         "/usr",
         "/usr/local",
         "/opt",
@@ -448,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
@@ -465,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/integrations/agent/engine-resolution.js

@@ -8,6 +8,7 @@ import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { ConfigError } from "../../core/errors.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
 import { collectSensitiveValues } from "../../core/redaction.js";
+import { warn } from "../../core/warn.js";
 import { getHarness } from "../harnesses/index.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
 import { getBuiltinAgentProfile } from "./profiles.js";
@@ -205,7 +206,20 @@ export function resolveLlmEngineUse(config, layers, options = {}) {
     }
     const engine = resolveEngineConfig(name, config);
     if (engine.kind !== "llm") {
-        throw new ConfigError(`Engine "${name}" is not an LLM engine.`, "INVALID_CONFIG_FILE");
+        const defaults = ownValue(config, "defaults");
+        const fallbackName = ownValue(engine, "llmEngine") ?? (defaults ? ownValue(defaults, "llmEngine") : undefined);
+        const fallbackEngine = fallbackName ? resolveEngineConfig(fallbackName, config) : undefined;
+        if (!fallbackEngine || fallbackEngine.kind !== "llm") {
+            if (options.optional)
+                return undefined;
+            throw new ConfigError(fallbackName
+                ? `Engine "${name}" is not an LLM engine, and its llmEngine fallback "${fallbackName}" is not one either.`
+                : `Engine "${name}" is not an LLM engine, and has no llmEngine fallback configured.`, "INVALID_CONFIG_FILE");
+        }
+        warn(`[akm] Engine "${name}" is an agent engine, not an LLM engine; using its llmEngine "${fallbackName}" instead.`);
+        return options.optional
+            ? resolveLlmEngineUse(config, [{ engine: fallbackName }], { optional: true })
+            : resolveLlmEngineUse(config, [{ engine: fallbackName }]);
     }
     let connection = rawLlmConnection(engine);
     for (const layer of layers) {

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

@@ -9,6 +9,7 @@ import { writeFileAtomic } from "../../core/common.js";
 import { ENGINE_NAME_PATTERN_SOURCE } from "../../core/config/engine-semantics.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { getConfigDir } from "../../core/paths.js";
+import { warnOnce } from "../../core/warn.js";
 import { cloneExecutionJsonObject } from "../../execution/json.js";
 /**
  * Installed and operator-owned model intent aliases (#802 / WP2).
@@ -218,10 +219,16 @@ export function resolveModelMapAlias(input, engine, map) {
     const profile = ownValue(tier, selectedEngine);
     if (profile !== undefined)
         return selectionFromProfile(input, profile);
-    if (tier !== undefined) {
-        throw new ConfigError(`Known alias ${JSON.stringify(input)} has no model mapping for selected engine ${JSON.stringify(engine)}.`, "INVALID_CONFIG_FILE", `Add $.aliases.${alias}.${engine} to models.json.`);
+    const knownAliasUnmappedForEngine = tier !== undefined;
+    if (knownAliasUnmappedForEngine) {
+        warnOnce(`model-map-alias-no-engine-mapping:${alias}:${selectedEngine}`, `[akm] Model alias ${JSON.stringify(input)} has no mapping for engine ${JSON.stringify(engine)}; using ${JSON.stringify(input)} as the literal model name. Add $.aliases.${alias}.${engine} to models.json to map it.`);
     }
-    return Object.freeze({ input, interpretation: "exact", model: input });
+    return Object.freeze({
+        input,
+        interpretation: "exact",
+        model: input,
+        ...(knownAliasUnmappedForEngine ? { unmappedForEngine: true } : {}),
+    });
 }
 export function userModelMapPath(env = process.env) {
     return path.join(getConfigDir(env), "models.json");
@@ -235,25 +242,24 @@ function modelMapFileError(label, filePath, action) {
  * absence; dangling links and every non-regular type are configuration errors.
  */
 function readModelMapFile(filePath, label, optional) {
-    let linkStat;
+    let targetStat;
     try {
-        linkStat = fs.lstatSync(filePath);
+        targetStat = fs.statSync(filePath);
     }
     catch (error) {
         if (optional && error?.code === "ENOENT")
             return undefined;
         throw modelMapFileError(label, filePath, optional ? "inspected" : "found");
     }
-    if (!linkStat.isFile()) {
-        throw new ConfigError(`Unable to read ${label.toLowerCase()} because it is not a readable regular file: ${filePath}.`, "INVALID_CONFIG_FILE", "Move the symlink or non-regular target aside, or replace it with a readable regular models.json file.");
+    if (!targetStat.isFile()) {
+        throw new ConfigError(`Unable to read ${label.toLowerCase()} because it is not a readable regular file: ${filePath}.`, "INVALID_CONFIG_FILE", "Replace it with a readable regular models.json file, or a symlink to one.");
     }
-    const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
     const nonblock = process.platform !== "win32" && typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0;
     let fd;
     try {
-        fd = fs.openSync(filePath, fs.constants.O_RDONLY | noFollow | nonblock);
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY | nonblock);
         const openedStat = fs.fstatSync(fd);
-        if (!sameFileIdentity(linkStat, openedStat)) {
+        if (!sameFileIdentity(targetStat, openedStat)) {
             throw new ConfigError(`${label} changed while it was being opened: ${filePath}.`, "INVALID_CONFIG_FILE", "Retry after ensuring no other process is replacing models.json.");
         }
         const text = fs.readFileSync(fd, "utf8");

package/dist/integrations/agent/prompts.js

@@ -315,9 +315,18 @@ export function buildReflectPrompt(input) {
     // asset content into shorter prose, drops concrete structure, or strips
     // load-bearing frontmatter. Loud and explicit so small models follow.
     //
-    // maxOutputChars is hoisted so the return value can include it for callers
-    // on the LLM path that want to set a hard max_tokens cap on the request.
-    let maxOutputChars;
+    // Guard-audit finding 15: this used to also hand back a maxOutputChars
+    // value so an LLM-path caller could convert it into a hard `max_tokens`
+    // cap on the API request. llm/client.ts's own doc comment (and
+    // commands/improve/reflect.ts's recorded history of responses actually
+    // getting cut off) is explicit that a character-derived max_tokens causes
+    // silent truncation — a real model's output is measured in tokens, not
+    // characters, and the ratio between the two varies enough that any fixed
+    // conversion either truncates legitimate output or provides no real cap at
+    // all. The size policy below is already enforced twice more (the prompt
+    // rules the model reads, and the post-processor's own size check), so nothing
+    // is lost by not adding a THIRD, byte-derived enforcement point that can
+    // only ever cut a response off early, never usefully re-check it.
     if (input.ref && input.assetContent?.trim()) {
         // Strip frontmatter to get source body length — mirrors checkReflectSize which
         // compares body-only lengths. Inline regex avoids importing parseFrontmatter.
@@ -332,8 +341,6 @@ export function buildReflectPrompt(input) {
         const showCharBounds = sourceBodyLen >= 200;
         const minChars = Math.max(Math.round(0.5 * sourceBodyLen), 150);
         const maxChars = Math.min(Math.max(Math.round(2.5 * sourceBodyLen), 2500), 25000);
-        if (showCharBounds)
-            maxOutputChars = maxChars;
         sections.push([
             "## Content preservation rules (MUST follow)",
             "1. PRESERVE ALL concrete content: code blocks, fenced snippets, CLI commands, numbered/bulleted checklists, tables, YAML/JSON examples, file paths, configuration keys, environment variable names, and CSS/HTML selectors. These are load-bearing — do NOT replace them with prose summaries.",
@@ -353,7 +360,7 @@ export function buildReflectPrompt(input) {
         sections.push(`IMPORTANT: The JSON "ref" field is REQUIRED. It MUST be exactly: "${input.ref}"`);
     }
     sections.push(reflectResponseContract(input));
-    return { prompt: sections.join("\n\n"), ...(maxOutputChars !== undefined ? { maxOutputChars } : {}) };
+    return { prompt: sections.join("\n\n") };
 }
 /**
  * Build the prompt for `akm propose <type> <name> --task ...`. Asks the