akm-cli 0.9.3 → 0.9.5

package/dist/core/config/config-version-shim.js

@@ -0,0 +1,101 @@
+// 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/.
+/**
+ * The `configVersion` read shim (#863).
+ *
+ * `configVersion` used to be a hard `z.literal(CURRENT_CONFIG_VERSION)` gate:
+ * every value other than the exact current string threw
+ * `UNSUPPORTED_CONFIG_VERSION` for every command, since every akm invocation
+ * loads config first. That is the same shape of break #858/#859 (proposal
+ * rows), the `task_history` `metadataVersion` gate, and the task-source v2/v3
+ * gate each caused in 0.9.x — a version gate with no read shim — except
+ * `configVersion`'s blast radius is the whole CLI rather than one subsystem.
+ *
+ * This module mirrors the in-tree template for that fix,
+ * `src/tasks/source/parse-task-source.ts`'s v2/v3 -> v4 shim: a known-old
+ * version routes through a pure, in-memory upgrade function to the current
+ * shape, with a one-line stderr deprecation warning; the result is never
+ * written back to disk (the on-disk rewrite already happens for free — every
+ * `saveConfig`/`mutateConfig` write forces `configVersion` to
+ * {@link CURRENT_CONFIG_VERSION}, so the very next `akm config set` or any
+ * other mutating command silences the warning permanently). A version that is
+ * neither current nor a known old version — including anything NEWER than
+ * current — still fails closed with `UNSUPPORTED_CONFIG_VERSION`:
+ * forward-incompatibility is a real hazard (an older binary must not guess at
+ * a newer, unknown shape) and this shim does not soften that.
+ *
+ * IMPORTANT — as of this writing, `"0.9.0"` is the only `configVersion` akm
+ * has ever shipped; there is no real prior release to shim. `"0.0.1"` below
+ * is a SYNTHETIC placeholder entry that exists solely to stand up and
+ * exercise this mechanism — the known-versions list, the dispatch table, the
+ * warn-once-and-upgrade behavior, the fail-closed behavior for anything
+ * else — before a real bump ever needs it (see
+ * `tests/integration/config-version-shim.test.ts` and the
+ * `previous-release-corpus.test.ts` fixture). When the first genuine
+ * `configVersion` bump ships, add its real old shape as its own entry the
+ * same way and delete the synthetic `"0.0.1"` entry (and this paragraph) in
+ * the same change.
+ */
+import { ConfigError } from "../errors.js";
+import { warn } from "../warn.js";
+import { CURRENT_CONFIG_VERSION } from "./schema/primitives.js";
+/**
+ * Every `configVersion` this binary can still READ, other than
+ * {@link CURRENT_CONFIG_VERSION} itself — each with an in-memory upgrade
+ * function in {@link CONFIG_VERSION_UPGRADES}. Anything not in this list (and
+ * not equal to current) fails closed.
+ */
+export const KNOWN_OLD_CONFIG_VERSIONS = ["0.0.1"];
+function isKnownOldConfigVersion(value) {
+    return typeof value === "string" && KNOWN_OLD_CONFIG_VERSIONS.includes(value);
+}
+/**
+ * SYNTHETIC 0.0.1 -> 0.9.0 upgrade (placeholder — see module doc). Per this
+ * placeholder, 0.0.1 kept the default LLM engine name at the config root as
+ * `defaultEngine`; 0.9.0 moved it under `defaults.llmEngine`. Pure function:
+ * takes the raw parsed JSON object, returns a new raw object with the 0.9.0
+ * shape. Never touches disk.
+ */
+function upgradeFrom080(raw) {
+    const { defaultEngine, defaults, ...rest } = raw;
+    if (typeof defaultEngine !== "string" || defaultEngine.length === 0) {
+        return { ...rest, ...(defaults !== undefined ? { defaults } : {}), configVersion: CURRENT_CONFIG_VERSION };
+    }
+    const existingDefaults = defaults !== null && typeof defaults === "object" ? defaults : {};
+    return {
+        ...rest,
+        configVersion: CURRENT_CONFIG_VERSION,
+        // An explicit `defaults.llmEngine` already present in the raw 0.0.1
+        // document (should never happen for a real 0.0.1 file, but a malformed
+        // one is possible) wins over the root-level field being migrated in.
+        defaults: { llmEngine: defaultEngine, ...existingDefaults },
+    };
+}
+const CONFIG_VERSION_UPGRADES = {
+    "0.0.1": upgradeFrom080,
+};
+function unsupportedConfigVersionError(rawVersion, sourcePath) {
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    const supported = [CURRENT_CONFIG_VERSION, ...KNOWN_OLD_CONFIG_VERSIONS].map((v) => `"${v}"`).join(", ");
+    return new ConfigError(`Unsupported configVersion${where}: got ${JSON.stringify(rawVersion)}, expected one of ${supported}.`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
+}
+/**
+ * Route a raw parsed config object through the version shim before schema
+ * validation. Returns a raw object whose `configVersion` is
+ * {@link CURRENT_CONFIG_VERSION} — either unchanged (already current),
+ * in-memory-upgraded (a known old version, with a one-line stderr warning),
+ * or this throws `UNSUPPORTED_CONFIG_VERSION` (unknown, newer, missing, or
+ * malformed).
+ */
+export function upgradeConfigVersion(raw, sourcePath) {
+    const version = raw.configVersion;
+    if (version === CURRENT_CONFIG_VERSION)
+        return raw;
+    if (isKnownOldConfigVersion(version)) {
+        const upgraded = CONFIG_VERSION_UPGRADES[version](raw);
+        warn(`Config${sourcePath ? ` at ${sourcePath}` : ""} uses configVersion "${version}" — auto-upgraded to ${CURRENT_CONFIG_VERSION} in memory; the next config write (e.g. \`akm config set\`) persists this and silences the warning.`);
+        return upgraded;
+    }
+    throw unsupportedConfigVersionError(version, sourcePath);
+}

package/dist/core/config/config.js

@@ -8,6 +8,7 @@ import { liftLegacyEngineExtraParams } from "../extra-params.js";
 import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "./config-io.js";
 import { AkmConfigSchema, CURRENT_CONFIG_VERSION } from "./config-schema.js";
 import { bundlesToSourceEntries } from "./config-sources.js";
+import { upgradeConfigVersion } from "./config-version-shim.js";
 import { deepMergeConfig } from "./deep-merge.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
@@ -138,14 +139,13 @@ export function acquireConfigReadFence() {
  * Parse raw config text and validate via Zod.
  * ({@link AkmConfigSchema}). Returns the merged-with-defaults AkmConfig.
  *
- * The schema accepts only the current config version and validates the
- * canonical shape before defaults are merged.
+ * The schema accepts only the current config version. A known older version
+ * is auto-upgraded in memory first (see `./config-version-shim`); anything
+ * else — including anything newer — is rejected before the canonical shape
+ * is validated.
  */
 export function parseAndValidateConfigText(text, sourcePath) {
-    const parsedRaw = parseConfigText(text, sourcePath);
-    if (parsedRaw.configVersion !== CURRENT_CONFIG_VERSION) {
-        throw new ConfigError(`Unsupported configVersion${sourcePath ? ` at ${sourcePath}` : ""}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
-    }
+    const parsedRaw = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
     // #852 (following #815): lift legacy `extraParams` keys — e.g.
     // `reasoning_effort`, a documented 0.9.1 workaround — onto the first-class
     // engine field they now shadow, before the protected-key check in

package/dist/core/improve-result.js

@@ -456,20 +456,24 @@ function validateCommon(value) {
         }
     }
 }
-/** Decode the persisted public result contract. */
-export function decodeImproveResult(input) {
-    let parsed = input;
-    if (typeof input === "string") {
-        try {
-            parsed = JSON.parse(input);
-        }
-        catch {
-            fail("not valid JSON");
-        }
-    }
-    if (!isRecord(parsed))
-        fail("root must be an object");
-    if (parsed.schemaVersion === 2) {
+/**
+ * Per-`schemaVersion` decoders for the persisted `improve_runs.result_json`
+ * contract, keyed by the literal `schemaVersion` value each accepts.
+ *
+ * #866 item 5 / read-shim policy (same shape as the version router in
+ * src/tasks/source/parse-task-source.ts, which this mirrors): every
+ * `schemaVersion` this build understands gets its own entry here, so
+ * decoding never regresses to "reject every row" the day the version bumps
+ * — it only stops accepting the ONE version that changed shape. All 1,539
+ * live rows today are v2; when a v3 shape is introduced, add a `3` entry
+ * (and, if v2 rows must keep reading under the newer runtime, keep this `2`
+ * entry as-is — every caller already skip-and-counts a decode failure, so a
+ * genuinely unreadable old row degrades to "excluded from metrics", never a
+ * crash). Do not remove the `2` entry when adding `3` unless the schema
+ * bump is known to be a strict superset callers can validate with it.
+ */
+const SCHEMA_DECODERS = {
+    2: (parsed) => {
         requireExactFields(parsed, V2_FIELDS);
         validateCommon(parsed);
         if (typeof parsed.strategy !== "string" || parsed.strategy.length === 0) {
@@ -482,6 +486,23 @@ export function decodeImproveResult(input) {
             envelope: parsed,
             strategy: parsed.strategy,
         };
+    },
+};
+/** Decode the persisted public result contract. */
+export function decodeImproveResult(input) {
+    let parsed = input;
+    if (typeof input === "string") {
+        try {
+            parsed = JSON.parse(input);
+        }
+        catch {
+            fail("not valid JSON");
+        }
     }
+    if (!isRecord(parsed))
+        fail("root must be an object");
+    const decoder = typeof parsed.schemaVersion === "number" ? SCHEMA_DECODERS[parsed.schemaVersion] : undefined;
+    if (decoder)
+        return decoder(parsed);
     fail(`unsupported schemaVersion: ${String(parsed.schemaVersion)}`);
 }

package/dist/execution/guarded-source.js

@@ -7,7 +7,6 @@ import path from "node:path";
 import { parseFrontmatter } from "../core/asset/frontmatter.js";
 import { UsageError } from "../core/errors.js";
 import { createExecutionSourceIdentity } from "./source.js";
-export const DEFAULT_GUARDED_SOURCE_MAX_BYTES = 1024 * 1024;
 function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
@@ -71,10 +70,6 @@ function captureRecord(sourcePathInput, containmentRootInput, options = {}) {
     const sourcePath = path.resolve(sourcePathInput);
     const { containmentRoot, containmentRealPath, containmentStat } = requireContainmentRoot(containmentRootInput);
     const lexicalRelative = containedRelative(containmentRoot, sourcePath, false);
-    const maxBytes = options.maxBytes ?? DEFAULT_GUARDED_SOURCE_MAX_BYTES;
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
-        throw new UsageError("Guarded source byte limit must be a non-negative safe integer.", "INVALID_FLAG_VALUE");
-    }
     const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
     let descriptor;
     try {
@@ -83,9 +78,6 @@ function captureRecord(sourcePathInput, containmentRootInput, options = {}) {
         if (!before.isFile()) {
             throw new UsageError(`${sourcePath} is not a regular guarded source file.`, "INVALID_FLAG_VALUE");
         }
-        if (before.size > BigInt(maxBytes)) {
-            throw new UsageError(`${sourcePath} exceeds the guarded source size limit (1 MiB; ${maxBytes} bytes).`, "INVALID_FLAG_VALUE");
-        }
         const bytes = fs.readFileSync(descriptor);
         const after = fs.fstatSync(descriptor, { bigint: true });
         if (!sameBigIntStat(before, after) || BigInt(bytes.byteLength) !== before.size) {
@@ -127,7 +119,6 @@ function captureRecord(sourcePathInput, containmentRootInput, options = {}) {
                 ...(options.identity ? { identity: options.identity } : {}),
             }),
             stat: numberStat(before),
-            maxBytes,
         };
     }
     catch (cause) {
@@ -402,7 +393,6 @@ export class GuardedExecutionSourceCollector {
             try {
                 current = captureRecord(record.source.sourcePath, record.source.containmentRoot, {
                     authored: record.source.authored,
-                    maxBytes: record.maxBytes,
                     ...(record.source.identity ? { identity: record.source.identity } : {}),
                 }).source;
             }

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

@@ -10,10 +10,6 @@ import { canonicalizeWorkflowName } from "../../core/recognition-util.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");
-const OWNER_SCAN_MAX_DIRECTORIES = 4_096;
-const OWNER_SCAN_MAX_FILES = 16_384;
-const OWNER_SCAN_SKIP_DIRECTORIES = new Set([".git", "node_modules", "bin", ".cache"]);
-const OWNER_SCAN_SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
 export class AdapterConceptOwnershipError extends UsageError {
 }
 export class AdapterConceptCollisionError extends AdapterConceptOwnershipError {
@@ -24,13 +20,6 @@ export class AdapterConceptCollisionError extends AdapterConceptOwnershipError {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-export class AdapterConceptScanError extends AdapterConceptOwnershipError {
-    constructor(adapterId, sourcePath, detail) {
-        super(`Adapter "${adapterId}" could not safely enumerate ${sourcePath}: ${detail}.`, "INVALID_FLAG_VALUE");
-        this.name = "AdapterConceptScanError";
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
 function normalizedConceptId(conceptId) {
     const normalized = conceptId.replaceAll("\\", "/");
     if (!normalized ||
@@ -128,79 +117,6 @@ function claimsWithoutContent(adapter, component, owner) {
         throw error;
     }
 }
-function adapterPathContext(root, authoredPath) {
-    const file = buildFileContext(root, authoredPath);
-    return {
-        absPath: file.absPath,
-        relPath: file.relPath,
-        ext: file.ext,
-        fileName: file.fileName,
-        parentDir: file.parentDir,
-        parentDirAbs: file.parentDirAbs,
-        ancestorDirs: file.ancestorDirs,
-        stashRoot: file.stashRoot,
-    };
-}
-function scanRegularAuthoredPaths(sourcePath, realRoot, adapterId) {
-    const paths = [];
-    const stack = [path.resolve(sourcePath)];
-    let directories = 0;
-    let files = 0;
-    while (stack.length > 0) {
-        const current = stack.pop();
-        if (!current)
-            continue;
-        directories++;
-        if (directories > OWNER_SCAN_MAX_DIRECTORIES) {
-            throw new AdapterConceptScanError(adapterId, sourcePath, `directory limit ${OWNER_SCAN_MAX_DIRECTORIES} exceeded`);
-        }
-        let entries;
-        try {
-            entries = fs
-                .readdirSync(current, { withFileTypes: true })
-                .sort((left, right) => comparePaths(left.name, right.name));
-        }
-        catch (error) {
-            throw new AdapterConceptScanError(adapterId, sourcePath, `cannot read ${current}: ${String(error)}`);
-        }
-        for (let index = entries.length - 1; index >= 0; index--) {
-            const entry = entries[index];
-            if (!entry)
-                continue;
-            const authoredPath = path.join(current, entry.name);
-            if (entry.isSymbolicLink())
-                continue;
-            if (entry.isDirectory()) {
-                if (OWNER_SCAN_SKIP_DIRECTORIES.has(entry.name) || entry.name.startsWith("."))
-                    continue;
-                stack.push(authoredPath);
-                continue;
-            }
-            if (!entry.isFile() || OWNER_SCAN_SKIP_FILES.has(entry.name))
-                continue;
-            files++;
-            if (files > OWNER_SCAN_MAX_FILES) {
-                throw new AdapterConceptScanError(adapterId, sourcePath, `file limit ${OWNER_SCAN_MAX_FILES} exceeded`);
-            }
-            let realPath;
-            try {
-                realPath = fs.realpathSync(authoredPath);
-            }
-            catch {
-                continue;
-            }
-            if (isWithin(realPath, realRoot))
-                paths.push(authoredPath);
-        }
-    }
-    return paths.sort(comparePaths);
-}
-function scannedReadCandidates(adapter, component, sourcePath, realRoot, conceptId) {
-    const recognizePathCandidates = adapter.recognizePathCandidates;
-    if (!recognizePathCandidates)
-        return [];
-    return scanRegularAuthoredPaths(sourcePath, realRoot, adapter.id).flatMap((authoredPath) => recognizePathCandidates(component, adapterPathContext(sourcePath, authoredPath)).flatMap((candidateConceptId) => candidateConceptId === conceptId ? [{ path: authoredPath, conceptId: candidateConceptId }] : []));
-}
 /**
  * Resolve one adapter/component's exact physical concept owner without reading
  * authored bytes. Native workflow arbitration is reused verbatim; every other
@@ -240,11 +156,12 @@ export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId) {
             ownersByIdentity.set(`${path.resolve(workflowOwner.path)}\0${resolutionConceptId}`, workflowOwner);
         }
     }
-    const directSpellings = (adapter.readCandidates?.(component, resolutionConceptId) ?? []).flatMap((candidate) => candidateSpellings(candidate, sourcePath, realRoot));
-    const spellings = [
-        ...directSpellings,
-        ...scannedReadCandidates(adapter, component, sourcePath, realRoot, resolutionConceptId),
-    ];
+    // Closed-form candidate set (#857): `readCandidates` inverts the conceptId
+    // directly into every physical spelling that could own it (no bundle walk
+    // — see each adapter's own doc comment for its candidate classes), and
+    // `candidateSpellings` adds case-only siblings via one `readdirSync` of
+    // each candidate's own parent directory.
+    const spellings = (adapter.readCandidates?.(component, resolutionConceptId) ?? []).flatMap((candidate) => candidateSpellings(candidate, sourcePath, realRoot));
     const inspected = [
         ...new Map(spellings.map((candidate) => [`${path.resolve(candidate.path)}\0${candidate.conceptId}`, candidate])).values(),
     ]

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 } from "../../core/warn.js";
+import { isVerbose, warn, warnVerbose } from "../../core/warn.js";
 export const SCOPE_KEYS = ["user", "agent", "run", "channel"];
 // ── Quality semantics (v1 spec §4.2) ────────────────────────────────────────
 /**
@@ -1119,7 +1119,7 @@ function stripMarkdownLinkDestinations(text, nesting = 0) {
  * secret/env/session bytes; that policy is enforced at the adapter metadata
  * boundary below.
  */
-export function projectMarkdownContent(body) {
+export function projectMarkdownContent(body, truncationInfo) {
     const lines = body.split(/\r?\n/);
     const innerBlock = findInnerFrontmatterBlock(lines);
     const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
@@ -1168,6 +1168,8 @@ export function projectMarkdownContent(body) {
     const text = projected.join(" ").replace(/\s+/g, " ").trim();
     if (!text)
         return undefined;
+    if (truncationInfo)
+        truncationInfo.truncated = text.length > MARKDOWN_CONTENT_MAX_CHARS;
     return truncateUnicodeSafe(text, MARKDOWN_CONTENT_MAX_CHARS);
 }
 // ── Metadata Generation ─────────────────────────────────────────────────────
@@ -1212,9 +1214,15 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
         // Native Markdown has one bounded low-weight body projection. Sensitive
         // types and raw session/checkpoint material never cross this boundary.
         if (entry.type !== "env" && entry.type !== "session" && !hasSessionMemoryMarker(parsed.data, parsed.content)) {
-            const contentProjection = projectMarkdownContent(parsed.content);
-            if (contentProjection)
+            const truncationInfo = { truncated: false };
+            const contentProjection = projectMarkdownContent(parsed.content, truncationInfo);
+            if (contentProjection) {
                 entry.content = contentProjection;
+                if (truncationInfo.truncated) {
+                    entry.contentTruncated = true;
+                    warnVerbose(`${file}: indexed content truncated to ${MARKDOWN_CONTENT_MAX_CHARS} chars`);
+                }
+            }
         }
         // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
         if (entry.type === "command") {

package/dist/indexer/scan/doc-to-entry.js

@@ -58,6 +58,8 @@ export function indexDocumentToStashEntry(doc) {
         entry.tags = doc.tags;
     if (doc.content !== undefined)
         entry.content = doc.content;
+    if (doc.contentTruncated !== undefined)
+        entry.contentTruncated = doc.contentTruncated;
     if (doc.ownsPresentation !== undefined)
         entry.ownsPresentation = doc.ownsPresentation;
     if (doc.updated !== undefined)

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

@@ -785,6 +785,10 @@ export async function buildDbHit(input) {
         ...(input.entry.beliefState ? { beliefState: input.entry.beliefState } : {}),
         ...(input.entry.currentBeliefRefs ? { currentBeliefRefs: input.entry.currentBeliefRefs } : {}),
         ...(graphHit ? { graph: { entities: graphHit.entities, relations: graphHit.relations } } : {}),
+        // Which stage of the progressive AND->OR lexical ladder produced this
+        // hit. Omitted when the hit has no FTS component (pure-semantic hybrid
+        // contribution).
+        ...(input.lexicalMatch ? { matchStage: input.lexicalMatch } : {}),
     };
     attachDbHitAttribution(hit, input);
     if (input.entry.derivedFrom) {
@@ -825,6 +829,8 @@ rankingMode, qualityBoost, confidenceBoost, utilityBoosted, graphBoost, lexicalM
     ];
     if (lexicalMatch === "relaxed")
         reasons.push("lexical recovery after strict query returned no hits");
+    if (lexicalMatch === "prefix")
+        reasons.push("prefix match after strict query returned no hits");
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const queryLower = query.toLowerCase().trim();
     const name = entry.name.toLowerCase();

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

@@ -1,6 +1,16 @@
 // 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;
 /**
@@ -80,12 +90,17 @@ 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)
+    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) {

package/dist/indexer/walk/matchers.js

@@ -270,28 +270,6 @@ function matchResultForFact(fact) {
         ...(fact.meta ? { meta: fact.meta } : {}),
     };
 }
-/**
- * Every smart-Markdown result possible from path fields alone. The actual
- * classifier above returns only facts from this shared table, so owner
- * discovery can conservatively model a byte request without reading bytes.
- */
-export function smartMdPathCandidates(ctx) {
-    if (ctx.ext !== ".md" || ctx.ancestorDirs.includes("secrets"))
-        return [];
-    const facts = isTypedDirDocFile(ctx.fileName)
-        ? [SMART_MD_FACTS.knowledge]
-        : [
-            SMART_MD_FACTS.workflow,
-            SMART_MD_FACTS.toolsAgent,
-            SMART_MD_FACTS.command,
-            SMART_MD_FACTS.modelAgent,
-            SMART_MD_FACTS.knowledge,
-        ];
-    return facts.flatMap((fact) => {
-        const result = matchResultForFact(fact);
-        return result ? [result] : [];
-    });
-}
 // ---------------------------------------------------------------------------
 // Public matchers (API unchanged)
 // ---------------------------------------------------------------------------

package/dist/output/shapes/helpers.js

@@ -275,7 +275,20 @@ export function shapeSearchHit(hit, detail) {
         // visible without forcing callers up to `--detail full`. Optional
         // `quality` (v1 spec §4.2) is also surfaced when present so callers
         // can see why a `proposed` entry showed up under `--include-proposed`.
-        const shaped = capDescription(pickFields(hit, ["type", "name", "description", "action", "score", "estimatedTokens", "warnings", "quality"]), NORMAL_DESCRIPTION_LIMIT);
+        // `matchStage` (issue #856) surfaces which stage of the progressive
+        // AND->OR lexical ladder produced the hit; cheap compact enum, worth
+        // showing without requiring `--detail full`.
+        const shaped = capDescription(pickFields(hit, [
+            "type",
+            "name",
+            "description",
+            "action",
+            "score",
+            "estimatedTokens",
+            "warnings",
+            "quality",
+            "matchStage",
+        ]), NORMAL_DESCRIPTION_LIMIT);
         if (Array.isArray(hit.keys) && hit.keys.length > 0)
             shaped.keys = hit.keys;
         return shaped;
@@ -296,6 +309,11 @@ export function shapeSearchHitForAgent(hit) {
         "score",
         "estimatedTokens",
         "keys",
+        // Issue #856: which stage of the progressive AND->OR lexical ladder
+        // produced this hit. Agents need this to gauge how much to trust a
+        // hit (a strict-AND match is stronger signal than an OR-fallback
+        // recovery match) without going to `--detail full`.
+        "matchStage",
     ]);
     if (picked.editable !== false)
         delete picked.editHint;

package/dist/output/shapes/passthrough.js

@@ -4,6 +4,15 @@
 // #484: stamp schemaVersion + shape discriminator on passthrough envelopes so
 // third-party consumers can pin a schema version and dispatch on shape uniformly.
 // Idempotent — never overwrites an existing schemaVersion or shape field.
+//
+// Builds a shallow copy rather than mutating `result` in place: several
+// command results (e.g. `akm task sync --dry-run`'s `SchedulerPlanPreview`,
+// see src/tasks/scheduler-sync-preview.ts) are deliberately `Object.freeze`d
+// by their producer as an immutability guarantee, and an in-place `obj.shape
+// = …` assignment throws ("Attempting to define property on object that is
+// not extensible") the moment it hits one. Copying tolerates both frozen and
+// mutable inputs uniformly, and `output()` never uses the result's identity
+// past this call, so a copy is safe here.
 function makeStampHandler(command) {
     return (result) => {
         if (result === null || result === undefined)
@@ -11,11 +20,13 @@ function makeStampHandler(command) {
         if (typeof result !== "object" || Array.isArray(result))
             return result;
         const obj = result;
-        if (obj.shape === undefined)
-            obj.shape = command;
-        if (obj.schemaVersion === undefined)
-            obj.schemaVersion = 1;
-        return obj;
+        if (obj.shape !== undefined && obj.schemaVersion !== undefined)
+            return obj;
+        return {
+            ...obj,
+            shape: obj.shape ?? command,
+            schemaVersion: obj.schemaVersion ?? 1,
+        };
     };
 }
 const PASSTHROUGH_COMMANDS = [
@@ -55,8 +66,10 @@ const PASSTHROUGH_COMMANDS = [
     "task-doctor",
     "task-explain",
     "task-history",
+    "task-prune",
     "task-run",
     "task-sync",
+    "task-sync-dry-run",
     "update",
     "upgrade",
     "workflow-abandon",

package/dist/output/text/command-format.js

@@ -270,6 +270,10 @@ export function formatSearchPlain(r, detail) {
         // Optional v1 spec §4.2 quality marker (e.g. "curated" / "proposed").
         if (typeof hit.quality === "string" && hit.quality)
             lines.push(`  quality: ${hit.quality}`);
+        // Issue #856: which stage of the progressive AND->OR lexical ladder
+        // produced this hit ("exact" | "prefix" | "relaxed").
+        if (typeof hit.matchStage === "string" && hit.matchStage)
+            lines.push(`  matchStage: ${hit.matchStage}`);
         // Surface optional hit-level warnings (v1 spec §4.2).
         if (Array.isArray(hit.warnings) && hit.warnings.length > 0) {
             lines.push(`  warnings: ${hit.warnings.join("; ")}`);

package/dist/registry/pinned-request-helper.js

@@ -117,8 +117,8 @@ export async function nodePinnedRequestHelperMain(readRequest, http, https, isIP
     };
     try {
         const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-        if (!Number.isInteger(nodeMajor) || nodeMajor < 24) {
-            throw new Error(`The pinned registry helper requires Node.js >= 24; found ${process.versions.node}`);
+        if (!Number.isInteger(nodeMajor) || nodeMajor < 22) {
+            throw new Error(`The pinned registry helper requires Node.js >= 22; found ${process.versions.node}`);
         }
         const { addressFamily, bodyPresent, headers, initialBody, iterator, method, pinnedAddress, timeoutMs, url } = await readRequest(isIP);
         const hostname = url.hostname.startsWith("[") && url.hostname.endsWith("]") ? url.hostname.slice(1, -1) : url.hostname;

package/dist/registry/pinned-transport.js

@@ -233,7 +233,7 @@ async function requestWithNodeHelper(url, address, prepared, init, timeoutMs, ex
 }
 function resolveNodeExecutable(override) {
     if (override === null) {
-        throw new RegistryPinnedTransportError("Pinned registry networking under Bun requires Node.js >= 24 on PATH; no Node executable is available");
+        throw new RegistryPinnedTransportError("Pinned registry networking under Bun requires Node.js >= 22 on PATH; no Node executable is available");
     }
     const candidates = override === undefined
         ? (process.env.PATH ?? "")
@@ -254,10 +254,10 @@ function resolveNodeExecutable(override) {
             return resolved;
         }
         catch {
-            // Try the next PATH entry. The helper itself enforces Node >= 24.
+            // Try the next PATH entry. The helper itself enforces Node >= 22.
         }
     }
-    throw new RegistryPinnedTransportError("Pinned registry networking under Bun requires Node.js >= 24 on PATH. Install Node.js or run akm with Node.");
+    throw new RegistryPinnedTransportError("Pinned registry networking under Bun requires Node.js >= 22 on PATH. Install Node.js or run akm with Node.");
 }
 function isSupportedNodeExecutable(executable) {
     const result = spawnSync(executable, ["--version"], {
@@ -272,14 +272,14 @@ function isSupportedNodeExecutable(executable) {
         return false;
     const match = /^v(\d+)\./.exec(result.stdout.trim());
     const major = match?.[1];
-    return major !== undefined && Number.parseInt(major, 10) >= 24;
+    return major !== undefined && Number.parseInt(major, 10) >= 22;
 }
 function assertNodeRuntimeVersion() {
     if (process.versions.bun)
         return;
     const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-    if (!Number.isInteger(major) || major < 24) {
-        throw new RegistryPinnedTransportError(`Pinned registry networking requires Node.js >= 24; found ${process.versions.node}`);
+    if (!Number.isInteger(major) || major < 22) {
+        throw new RegistryPinnedTransportError(`Pinned registry networking requires Node.js >= 22; found ${process.versions.node}`);
     }
 }
 function createHelperArtifacts(ca) {