akm-cli 0.9.2 → 0.9.4

package/dist/core/adapter/recognize-match.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher, smartMdPathCandidates, } from "../../indexer/walk/matchers.js";
+import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher } from "../../indexer/walk/matchers.js";
 /**
  * The four builtin matchers, in registration order. The array index IS the
  * registration index `runMatchers` uses for tie-breaking. (The `wiki` matcher
@@ -46,22 +46,3 @@ export function recognizeMatch(file) {
     }
     return winningMatch(hits);
 }
-/**
- * Every AKM matcher winner possible from path fields alone. The three
- * path-only matchers run exactly as production does; each possible result of
- * the shared smart-Markdown fact table is then arbitrated at its real index.
- */
-export function recognizePathCandidateMatches(file) {
-    const fileContext = file;
-    const pathHits = [extensionMatcher, directoryMatcher, parentDirHintMatcher].flatMap((matcher, index) => {
-        const result = matcher(fileContext);
-        return result ? [{ result, index }] : [];
-    });
-    const smartCandidates = smartMdPathCandidates(file);
-    const variants = smartCandidates.length > 0 ? smartCandidates : [undefined];
-    const winners = variants.flatMap((smart) => {
-        const winner = winningMatch(smart ? [...pathHits, { result: smart, index: 3 }] : [...pathHits]);
-        return winner ? [winner] : [];
-    });
-    return [...new Map(winners.map((winner) => [`${winner.type}\0${winner.renderer}`, winner])).values()];
-}

package/dist/core/asset/asset-placement.js

@@ -151,10 +151,10 @@ const BUILTIN_PLACEMENT_SPECS = {
         isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".yml",
         toCanonicalName: (typeRoot, filePath) => {
             const rel = toPosix(path.relative(typeRoot, filePath));
-            return rel.endsWith(".yml") ? rel.slice(0, -4) : rel;
+            return rel.toLowerCase().endsWith(".yml") ? rel.slice(0, -4) : rel;
         },
         toAssetPath: (typeRoot, name) => {
-            const withExt = name.endsWith(".yml") ? name : `${name}.yml`;
+            const withExt = name.toLowerCase().endsWith(".yml") ? name : `${name}.yml`;
             return path.join(typeRoot, withExt);
         },
     },
@@ -241,3 +241,22 @@ export function assetPathForName(assetType, typeRoot, name) {
         throw new Error(`Unknown asset type: "${assetType}"`);
     return spec.toAssetPath(typeRoot, name);
 }
+/**
+ * Every physical path spelling that could own `name`, closed-form (#857).
+ * `toAssetPath` is a function, so it can only pick ONE spelling — but `env`'s
+ * "default" alias is genuinely dual-owned: both `<dir>/.env` and
+ * `<dir>/default.env` derive the same canonical name (`toCanonicalName`
+ * above), so a physical-owner lookup must consider both without reading
+ * either file. Every other placement type has exactly one inverse spelling.
+ */
+export function assetPathCandidatesForName(assetType, typeRoot, name) {
+    const primary = assetPathForName(assetType, typeRoot, name);
+    if (assetType !== "env")
+        return [primary];
+    const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;
+    if (base === undefined)
+        return [primary];
+    const dotForm = path.join(typeRoot, base, ".env");
+    const namedForm = path.join(typeRoot, base, "default.env");
+    return [...new Set([primary, dotForm, namedForm])];
+}

package/dist/core/common.js

@@ -5,7 +5,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "./errors.js";
-import { getConfigPath, getDefaultStashDir } from "./paths.js";
+import { getConfigPath, getDefaultStashDir, getRegistryCacheDir, getRegistryIndexCacheDir } from "./paths.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 // Moved to the platform leaf so paths.ts can use it without a common↔paths
 // cycle (chunk-8 WI-8.6, DoD 11); re-exported here for the existing surface.
@@ -382,6 +382,26 @@ export function isContainedRelativePath(value) {
 export function isWithin(candidate, root) {
     return isContainedResolvedPath(safeRealpath(candidate), safeRealpath(root));
 }
+/**
+ * True when `filePath` sits inside akm's OWN resolved registry-cache
+ * directories (`<cache>/registry`, `<cache>/registry-index` —
+ * {@link getRegistryCacheDir}/{@link getRegistryIndexCacheDir}), the
+ * read-only installed-source/registry-index copies that lint (and `--fix`)
+ * must never touch.
+ *
+ * This is the single source of truth for that exclusion — it replaces what
+ * used to be three independent unanchored substring checks
+ * (`posixPath.includes("/.cache/") || posixPath.includes("/registry/")`).
+ * That check matched ANY path merely containing the literal text `.cache` or
+ * `registry` anywhere in it — a normal XDG `~/.cache/...` user bundle, or a
+ * CI workspace checked out under a `.cache`-named directory, tripped it and
+ * silently got zero lint findings. Using {@link isWithin} (realpath +
+ * containment, not a string search) fixes that while still excluding the
+ * real cache content the check was meant to skip.
+ */
+export function isAkmRegistryCachePath(filePath) {
+    return isWithin(filePath, getRegistryCacheDir()) || isWithin(filePath, getRegistryIndexCacheDir());
+}
 /**
  * {@link isWithin} for callers that must not block the event loop (e.g. the
  * workflow exec dispatch path, which runs once per fan-out unit). Same

package/dist/core/config/config.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../errors.js";
+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";
@@ -141,14 +142,29 @@ export function acquireConfigReadFence() {
  * canonical shape before defaults are merged.
  */
 export function parseAndValidateConfigText(text, sourcePath) {
-    const raw = parseConfigText(text, sourcePath);
-    if (raw.configVersion !== CURRENT_CONFIG_VERSION) {
+    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.");
     }
+    // #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
+    // `ExtraParamsSchema` gets a chance to hard-reject them. In-memory only;
+    // never written back to the file.
+    const { config: raw, lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    if (conflicts.length > 0) {
+        const lines = conflicts
+            .map((c) => `  - engines.${c.engine}.extraParams.${c.key} (${JSON.stringify(c.extraParamsValue)}) conflicts with engines.${c.engine}.${c.field} (${JSON.stringify(c.fieldValue)})`)
+            .join("\n");
+        throw new ConfigError(`Invalid config${where}: extraParams and the first-class field disagree:\n${lines}\n\nEach extraParams key above has a first-class equivalent and akm will not guess which value you meant — remove the extraParams entry once the field carries the value you want.`, "INVALID_CONFIG_FILE");
+    }
+    if (lifted.length > 0) {
+        warn(`Config${where} uses deprecated extraParams keys with first-class equivalents; treating them as the first-class fields for this run (not written back to the file):\n  - ${lifted.join("\n  - ")}`);
+    }
     const parsed = AkmConfigSchema.safeParse(raw);
     if (!parsed.success) {
         const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
-        const where = sourcePath ? ` at ${sourcePath}` : "";
         throw new ConfigError(`Invalid config${where}:\n${lines}`, "INVALID_CONFIG_FILE");
     }
     const merged = deepMergeConfig(DEFAULT_CONFIG, parsed.data);

package/dist/core/extra-params.js

@@ -25,6 +25,46 @@ export const EXTRA_PARAMS_CREDENTIAL_KEYS = [
 ];
 const PROTECTED_TOP_LEVEL_KEYS = new Set(EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS);
 const CREDENTIAL_KEYS = new Set(EXTRA_PARAMS_CREDENTIAL_KEYS);
+// ── Protected-key remedies (#852) ───────────────────────────────────────────
+//
+// `EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS` rightly stops a provider extra from
+// shadowing an AKM-managed field, but naming the rule without naming the fix
+// leaves the reader stuck (#852). Every protected key gets a one-line remedy
+// baked into its issue message; keys with a genuine scalar first-class field
+// are also eligible for the automatic config-load lift below.
+/** normalizeExtraParamKey(key) -> the first-class engine field it shadows. */
+const LEGACY_EXTRA_PARAMS_FIELD = {
+    model: "model",
+    temperature: "temperature",
+    maxtokens: "maxTokens",
+    enablethinking: "enableThinking",
+    reasoningeffort: "reasoningEffort",
+};
+/**
+ * Subset of {@link LEGACY_EXTRA_PARAMS_FIELD} that {@link liftLegacyEngineExtraParams}
+ * will move onto the first-class field automatically. `model` is deliberately
+ * excluded: unlike the others it was never a "no first-class field yet"
+ * workaround (`model` has always been required on an LLM engine), so a
+ * mismatch is far more likely a genuine mistake than a stale 0.9.1 config —
+ * it stays a hard rejection rather than being silently reinterpreted.
+ */
+const LIFTABLE_EXTRA_PARAMS_KEYS = new Set(["temperature", "maxtokens", "enablethinking", "reasoningeffort"]);
+/** Remedies for protected keys with no scalar first-class field to lift onto. */
+const EXTRA_PARAMS_NO_FIELD_REMEDY = {
+    messages: "AKM builds the request messages internally — remove it from extraParams",
+    responseformat: "AKM controls the response format internally — remove it from extraParams",
+    stream: "AKM controls streaming internally — remove it from extraParams",
+    streamoptions: "AKM controls streaming internally — remove it from extraParams",
+    chattemplatekwargs: "set engines.<name>.enableThinking instead of chat_template_kwargs.enable_thinking",
+};
+function protectedKeyRemedy(normalized) {
+    const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
+    if (field) {
+        const note = normalized === "reasoningeffort" ? " (moved to a first-class field in 0.9.2)" : "";
+        return `set engines.<name>.${field} instead${note}`;
+    }
+    return EXTRA_PARAMS_NO_FIELD_REMEDY[normalized];
+}
 export function normalizeExtraParamKey(key) {
     return key.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
@@ -57,7 +97,11 @@ export function validateExtraParams(value) {
         for (const [key, child] of Object.entries(entry)) {
             const normalized = normalizeExtraParamKey(key);
             if (path.length === 0 && PROTECTED_TOP_LEVEL_KEYS.has(normalized)) {
-                issues.push({ path: [key], message: `${key} is protected by AKM` });
+                const remedy = protectedKeyRemedy(normalized);
+                issues.push({
+                    path: [key],
+                    message: remedy ? `${key} is protected by AKM — ${remedy}.` : `${key} is protected by AKM`,
+                });
             }
             if (CREDENTIAL_KEYS.has(normalized)) {
                 issues.push({ path: [...path, key], message: `${key} cannot carry credentials` });
@@ -72,3 +116,73 @@ export function formatExtraParamsIssue(label, issue) {
     const suffix = issue.path.map((part) => (typeof part === "number" ? `[${part}]` : `.${part}`)).join("");
     return `${label}${suffix} ${issue.message}`;
 }
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Lift legacy `extraParams` keys onto their first-class engine field before
+ * schema validation runs, so a 0.9.1-shaped config using (e.g.)
+ * `extraParams.reasoning_effort` keeps loading now that `reasoningEffort` is
+ * a first-class — and therefore protected — field (#852, following #815).
+ *
+ * In-memory only: this never rewrites the config file. Callers should warn
+ * using the returned `lifted` descriptions so the user knows to update the
+ * file by hand, and reject using `conflicts` rather than silently preferring
+ * either value.
+ */
+export function liftLegacyEngineExtraParams(raw) {
+    const lifted = [];
+    const conflicts = [];
+    const rawEngines = raw.engines;
+    if (!isPlainObject(rawEngines)) {
+        return { config: raw, lifted, conflicts };
+    }
+    const engines = {};
+    let anyEngineChanged = false;
+    for (const [name, engineValue] of Object.entries(rawEngines)) {
+        if (!isPlainObject(engineValue) || !isPlainObject(engineValue.extraParams)) {
+            engines[name] = engineValue;
+            continue;
+        }
+        const engine = { ...engineValue };
+        const extraParams = { ...engineValue.extraParams };
+        let engineChanged = false;
+        for (const [rawKey, value] of Object.entries(engineValue.extraParams)) {
+            const normalized = normalizeExtraParamKey(rawKey);
+            if (!LIFTABLE_EXTRA_PARAMS_KEYS.has(normalized))
+                continue;
+            const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
+            if (!field)
+                continue;
+            const existing = engine[field];
+            if (existing !== undefined && existing !== value) {
+                conflicts.push({ engine: name, key: rawKey, field, extraParamsValue: value, fieldValue: existing });
+                continue;
+            }
+            delete extraParams[rawKey];
+            engineChanged = true;
+            if (existing === value) {
+                lifted.push(`engines.${name}.extraParams.${rawKey} is redundant — engines.${name}.${field} is already set to the same value; dropped the extraParams entry`);
+                continue;
+            }
+            engine[field] = value;
+            lifted.push(`engines.${name}.extraParams.${rawKey} -> engines.${name}.${field}`);
+        }
+        if (!engineChanged) {
+            engines[name] = engineValue;
+            continue;
+        }
+        anyEngineChanged = true;
+        if (Object.keys(extraParams).length > 0) {
+            engine.extraParams = extraParams;
+        }
+        else {
+            delete engine.extraParams;
+        }
+        engines[name] = engine;
+    }
+    if (!anyEngineChanged) {
+        return { config: raw, lifted, conflicts };
+    }
+    return { config: { ...raw, engines }, lifted, conflicts };
+}

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/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/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

@@ -57,6 +57,7 @@ const PASSTHROUGH_COMMANDS = [
     "task-history",
     "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) {