akm-cli 0.9.0-rc.2 → 0.9.0-rc.3

package/dist/commands/config-cli.js

@@ -242,11 +242,18 @@ export const configCommand = defineGroupCommand({
         migrate: defineJsonCommand({
             meta: {
                 name: "migrate",
-                description: "Diagnose whether the user config is already in the current schema. Never writes or translates config.",
+                description: "Compatibility alias for the canonical top-level migrate status/apply coordinator.",
             },
-            async run() {
+            args: {
+                config: {
+                    type: "string",
+                    description: "Path to an operator-prepared current-version config to validate and install",
+                },
+                dryRun: { type: "boolean", default: false, description: "Validate and report without changing files" },
+            },
+            async run({ args }) {
                 const { runConfigMigrate } = await import("../cli/config-migrate.js");
-                await runConfigMigrate();
+                await runConfigMigrate({ preparedConfigPath: args.config, dryRun: args.dryRun });
             },
         }),
         enable: defineJsonCommand({

package/dist/commands/feedback-cli.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
-import { parseAssetRef } from "../core/asset/asset-ref.js";
+import { parseAssetRef, refToString } from "../core/asset/asset-ref.js";
 import { assembleAsset } from "../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatter.js";
 import { writeFileAtomic } from "../core/common.js";
@@ -12,7 +12,8 @@ import { UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
-import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
+import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryById, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { countFeedbackSignals, insertUsageEvent } from "../indexer/usage/usage-events.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
@@ -156,7 +157,7 @@ export const feedbackCommand = defineJsonCommand({
         if (!ref) {
             throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skill:deploy` and either --positive or --negative.");
         }
-        parseAssetRef(ref);
+        const parsedRef = parseAssetRef(ref);
         if (args.positive && args.negative) {
             throw new UsageError("Specify either --positive or --negative, not both.");
         }
@@ -216,9 +217,19 @@ export const feedbackCommand = defineJsonCommand({
         // background reindex it spawned — now that ensureIndex is removed, holding
         // the lock only causes feedback to block for the full improve run duration.
         let utilityResult;
+        let durableRef = ref;
         const db = openExistingDatabase();
         try {
-            const entryId = findEntryIdByRef(db, ref);
+            const config = loadConfig();
+            const sources = resolveSourceEntries(undefined, config);
+            const requestedSource = parsedRef.origin
+                ? sources.find((source) => source.registryId === parsedRef.origin ||
+                    ((parsedRef.origin === "local" || parsedRef.origin === "stash") && source === sources[0]))
+                : undefined;
+            if (parsedRef.origin && !requestedSource) {
+                throw new UsageError(`Source "${parsedRef.origin}" is not configured.`, "INVALID_FLAG_VALUE");
+            }
+            const entryId = findEntryIdByRef(db, ref, requestedSource?.path);
             if (entryId === undefined) {
                 throw new UsageError(`Ref "${ref}" is not in the index. ` +
                     "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
@@ -228,9 +239,15 @@ export const feedbackCommand = defineJsonCommand({
             // For negative signals, the score is adjusted the next time `akm index`
             // runs — the signal is durable in the DB but does NOT suppress ranking
             // in search results until after reindexing.
+            const indexedEntry = getEntryById(db, entryId);
+            const source = sources.find((candidate) => candidate.path === indexedEntry?.stashDir);
+            durableRef = refToString({
+                ...parsedRef,
+                origin: parsedRef.origin ?? source?.registryId ?? "stash",
+            });
             insertUsageEvent(db, {
                 event_type: "feedback",
-                entry_ref: ref,
+                entry_ref: durableRef,
                 entry_id: entryId,
                 signal,
                 metadata: metadataStr,
@@ -253,7 +270,7 @@ export const feedbackCommand = defineJsonCommand({
         }
         appendEvent({
             eventType: "feedback",
-            ref,
+            ref: durableRef,
             metadata: metadataObj,
         });
         // F-5 / #386: When a high-utility asset crosses below the review threshold,
@@ -268,7 +285,7 @@ export const feedbackCommand = defineJsonCommand({
             try {
                 appendEvent({
                     eventType: "improve_review_needed",
-                    ref,
+                    ref: durableRef,
                     metadata: {
                         previousUtility: utilityResult.previousUtility,
                         nextUtility: utilityResult.nextUtility,

package/dist/commands/health/checks.js

@@ -6,20 +6,25 @@ import { createRequire } from "node:module";
 import { loadConfig } from "../../core/config/config.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { resolveModel } from "../../integrations/agent/model-aliases.js";
+import { resolveImprovePlan } from "../improve/improve-strategies.js";
 import { TASK_FAIL_RATE_WARN, } from "./types.js";
 const ACTIVE_RUN_WARN_MS = 15 * 60 * 1000;
-export function runDefaultEngineProbe(deps = {}) {
-    const config = deps.loadConfig?.() ?? loadConfig();
-    const engineName = config.defaults?.engine ?? config.defaults?.llmEngine;
+function credentialAvailable(credential, env) {
+    return !credential?.required || credential.names.some((name) => Boolean(env[name]?.trim()));
+}
+function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     if (!engineName) {
         return {
-            name: "default-engine",
+            name: checkName,
             kind: "deterministic",
             status: "unknown",
             confidence: "high",
-            message: "No default engine is configured.",
+            message: checkName === "default-llm-engine"
+                ? "No default LLM engine is configured."
+                : "No default engine is configured.",
         };
     }
+    const env = deps.env ?? process.env;
     const configuredEngine = config.engines?.[engineName];
     if (configuredEngine?.kind === "agent" && configuredEngine.platform === "opencode-sdk") {
         let packageAvailable = false;
@@ -36,6 +41,7 @@ export function runDefaultEngineProbe(deps = {}) {
         const binaryAvailable = (version.status ?? 1) === 0;
         const fallbackEngine = configuredEngine.llmEngine ?? config.defaults?.llmEngine;
         let fallback;
+        let fallbackCredential;
         let sdkRunner;
         const resolve = deps.resolveEngine ?? resolveEngine;
         try {
@@ -48,12 +54,15 @@ export function runDefaultEngineProbe(deps = {}) {
         }
         if (sdkRunner?.fallbackConnection) {
             fallback = { kind: "llm", connection: sdkRunner.fallbackConnection };
+            fallbackCredential = sdkRunner.fallbackCredential;
         }
         else if (fallbackEngine) {
             try {
                 const resolved = resolve(fallbackEngine, config);
-                if (resolved.kind === "llm")
+                if (resolved.kind === "llm") {
                     fallback = resolved;
+                    fallbackCredential = resolved.credential;
+                }
             }
             catch {
                 fallback = undefined;
@@ -63,14 +72,15 @@ export function runDefaultEngineProbe(deps = {}) {
             ? resolveModel(configuredEngine.model, "opencode-sdk", configuredEngine.modelAliases, config.modelAliases)
             : undefined;
         const effectiveModel = sdkRunner?.profile.model ?? configuredModel ?? fallback?.connection.model;
+        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env);
         const missing = [
             !packageAvailable ? "@opencode-ai/sdk package" : undefined,
             !binaryAvailable ? `${binary} binary` : undefined,
-            !fallback ? "fallback LLM connection" : undefined,
-            !effectiveModel ? "effective SDK model" : undefined,
+            fallbackEngine && !fallback ? "configured fallback LLM connection" : undefined,
+            !fallbackCredentialAvailable ? "required fallback credential" : undefined,
         ].filter((value) => value !== undefined);
         return {
-            name: "default-engine",
+            name: checkName,
             kind: "deterministic",
             status: missing.length === 0 ? "pass" : "warn",
             confidence: "high",
@@ -91,24 +101,29 @@ export function runDefaultEngineProbe(deps = {}) {
                 fallbackEngine: fallbackEngine ?? null,
                 fallbackEndpoint: fallback?.connection.endpoint ?? null,
                 fallbackModel: fallback?.connection.model ?? null,
+                requiredCredentialAvailable: fallbackCredentialAvailable,
             },
         };
     }
     try {
         const runner = (deps.resolveEngine ?? resolveEngine)(engineName, config);
         if (runner.kind === "llm") {
+            const requiredCredentialAvailable = credentialAvailable(runner.credential, env);
             return {
-                name: "default-engine",
+                name: checkName,
                 kind: "deterministic",
-                status: "pass",
+                status: requiredCredentialAvailable ? "pass" : "warn",
                 confidence: "high",
-                message: `LLM engine "${engineName}" is configured.`,
+                message: requiredCredentialAvailable
+                    ? `LLM engine "${engineName}" is configured.`
+                    : `LLM engine "${engineName}" is configured, but its required credential is unavailable.`,
                 evidence: {
                     engine: engineName,
                     platform: null,
                     runtimeKind: "llm",
                     model: runner.connection.model,
                     endpoint: runner.connection.endpoint,
+                    requiredCredentialAvailable,
                 },
             };
         }
@@ -118,7 +133,7 @@ export function runDefaultEngineProbe(deps = {}) {
         const version = (deps.spawnSync ?? spawnSync)(profile.bin, ["--version"], { encoding: "utf8", timeout: 5_000 });
         if ((version.status ?? 1) !== 0) {
             return {
-                name: "default-engine",
+                name: checkName,
                 kind: "deterministic",
                 status: "warn",
                 confidence: "medium",
@@ -132,7 +147,7 @@ export function runDefaultEngineProbe(deps = {}) {
             };
         }
         return {
-            name: "default-engine",
+            name: checkName,
             kind: "deterministic",
             status: "pass",
             confidence: "high",
@@ -147,7 +162,7 @@ export function runDefaultEngineProbe(deps = {}) {
     }
     catch (error) {
         return {
-            name: "default-engine",
+            name: checkName,
             kind: "deterministic",
             status: "warn",
             confidence: "high",
@@ -155,6 +170,60 @@ export function runDefaultEngineProbe(deps = {}) {
         };
     }
 }
+export function runDefaultEngineProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, deps);
+}
+export function runDefaultLlmEngineProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    return runConfiguredEngineProbe("default-llm-engine", config.defaults?.llmEngine, config, deps);
+}
+export function runActiveImproveStrategyProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    const strategyName = config.defaults?.improveStrategy ?? "default";
+    try {
+        const plan = resolveImprovePlan(strategyName, config);
+        const env = deps.env ?? process.env;
+        const unavailableProcesses = Object.entries(plan.processes).flatMap(([name, process]) => {
+            if (!process.enabled || !process.runner)
+                return [];
+            return credentialAvailable(process.runner.credential, env) ? [] : [name];
+        });
+        if (plan.triageJudgment) {
+            const judgmentCredential = plan.triageJudgment.kind === "llm"
+                ? plan.triageJudgment.credential
+                : plan.triageJudgment.kind === "sdk"
+                    ? plan.triageJudgment.fallbackCredential
+                    : undefined;
+            if (!credentialAvailable(judgmentCredential, env))
+                unavailableProcesses.push("triage.judgment");
+        }
+        return {
+            name: "active-improve-strategy",
+            kind: "deterministic",
+            status: unavailableProcesses.length === 0 ? "pass" : "warn",
+            confidence: "high",
+            message: unavailableProcesses.length === 0
+                ? `Active improve strategy "${plan.strategy.name}" has available process engines.`
+                : `Active improve strategy "${plan.strategy.name}" has unavailable required credentials for: ${unavailableProcesses.join(", ")}.`,
+            evidence: {
+                strategy: plan.strategy.name,
+                unavailableProcesses,
+            },
+        };
+    }
+    catch (error) {
+        const explicitlyConfigured = config.defaults?.improveStrategy !== undefined || Object.keys(config.improve?.strategies ?? {}).length > 0;
+        return {
+            name: "active-improve-strategy",
+            kind: "deterministic",
+            status: explicitlyConfigured ? "warn" : "unknown",
+            confidence: "high",
+            message: `Active improve strategy "${strategyName}" is unavailable: ${error instanceof Error ? error.message : String(error)}`,
+            evidence: { strategy: strategyName, unavailableProcesses: [] },
+        };
+    }
+}
 /**
  * The ordered health-check registry. ORDER IS LOAD-BEARING: `akmHealth`
  * iterates this array and appends to hardChecks/advisories in sequence, so the
@@ -236,6 +305,16 @@ export const HEALTH_CHECKS = [
         channel: "hard",
         run: () => runDefaultEngineProbe(),
     },
+    {
+        name: "default-llm-engine",
+        channel: "hard",
+        run: () => runDefaultLlmEngineProbe(),
+    },
+    {
+        name: "active-improve-strategy",
+        channel: "hard",
+        run: () => runActiveImproveStrategyProbe(),
+    },
     {
         // C2 (13-bus-factor): the cron task-failure rate was computed and rendered
         // in the HTML report but never surfaced as an advisory, so a sustained

package/dist/commands/health/surfaces.js

@@ -18,6 +18,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { MAX_CONFIG_FILE_BYTES, readTextFileWithLimit } from "../../core/common.js";
 import { CURRENT_CONFIG_VERSION } from "../../core/config/config-schema.js";
 import { compareConfigVersion } from "../../core/config/config-version.js";
 const GROUP_OTHER_BITS = 0o077;
@@ -98,7 +99,7 @@ export function collectSecretPermsAdvisory(input, platform = process.platform) {
 export function collectConfigSkewAdvisory(configPath) {
     let raw;
     try {
-        raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        raw = JSON.parse(readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file"));
     }
     catch {
         return undefined;

package/dist/commands/improve/anti-collapse.js

@@ -72,8 +72,8 @@ function distinctTokens(text) {
 }
 /**
  * A merge must strictly increase information (R5 §4.2):
- *  1. Provenance: the merged asset's `source_refs` must be a superset of the
- *     union of all participants' `source_refs` plus the participant refs
+ *  1. Provenance: the merged asset's `xrefs` must be a superset of the union of
+ *     all participants' `xrefs` plus the participant refs
  *     themselves — provenance never shrinks through a merge.
  *  2. Specificity: distinctTokens(mergedBody) ≥ minSpecificityRetention ×
  *     |union(distinctTokens(participant bodies))| — a merge that only
@@ -111,7 +111,7 @@ export function checkMergeInformationFloor(mergedBody, mergedSourceRefs, partici
     const specificityOk = specificityRetention >= minRetention;
     const reasons = [];
     if (!provenanceOk) {
-        reasons.push(`provenance shrank: merged source_refs missing ${missing.length} ref(s) (e.g. ${missing[0]})`);
+        reasons.push(`provenance shrank: merged xrefs missing ${missing.length} ref(s) (e.g. ${missing[0]})`);
     }
     if (!specificityOk) {
         reasons.push(`specificity retention ${specificityRetention.toFixed(2)} < ${minRetention} (merge genericized/shortened)`);

package/dist/commands/improve/collapse-detector.js

@@ -175,10 +175,10 @@ export function normHash(text) {
     return hash.toString(16);
 }
 /**
- * Score one canary against the live index, merge-following via `source_refs`:
- * a hit is the anchor ref itself OR any returned entry whose `source_refs`
- * frontmatter contains the anchor (ONE level — provenance dropped on a
- * second-generation merge is a miss by design; that IS the information loss).
+ * Score one canary against the live index, merge-following via canonical
+ * `xrefs`. Legacy `source_refs` remains readable for assets written before the
+ * xref cutover. A hit is the anchor ref itself OR any returned entry whose
+ * provenance contains the anchor.
  * Returns the 0-based rank of the first hit, or -1.
  */
 function scoreCanary(indexDb, canary, k) {
@@ -188,7 +188,7 @@ function scoreCanary(indexDb, canary, k) {
         const ref = makeAssetRef(r.entry.type, r.entry.name);
         if (ref === canary.anchor_ref)
             return i;
-        if (r.entry.sourceRefs?.includes(canary.anchor_ref))
+        if (r.entry.xrefs?.includes(canary.anchor_ref) || r.entry.sourceRefs?.includes(canary.anchor_ref))
             return i;
     }
     return -1;