akm-cli 0.10.261019 → 0.10.261021

package/CHANGELOG.md

@@ -6,6 +6,52 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261021] - 2026-10-30
+
+### Added
+
+- `akm upgrade --channel latest|next` switches the CLI and installed Claude,
+  Codex and OpenCode plugins together, preserving unrelated native settings and
+  writing backups. `--check` shows channel mismatches; an older target requires
+  `--allow-downgrade` (#1285).
+
+### Changed
+
+- `akm metrics` replaces `usage.selectRate` with `usage.selectsPerSearch` and
+  adds `usage.totals.searchesWithHits`. Selects carry no source or search id, so
+  the figure is an unbounded ratio, not a conversion percentage: eight selects
+  after one search read 8.00, not 800% (#1293).
+
+### Fixed
+
+- A model call whose configured deadline is longer than five minutes is no
+  longer cut off at five minutes by Bun's socket-idle timer (#1295).
+- Workflow params that are ordinary file paths (absolute, relative, Windows,
+  with dates, digits or a UUID directory) are no longer warned about or redacted
+  as secrets; credential-named keys, known token prefixes and token-shaped path
+  segments still are (#1292).
+- `akm bundle add --writable` on a bundle installed read-only from Git makes a
+  fresh checkout instead of failing with "is not a checkout", keeping the
+  bundle's name, components, order and credential (#1296).
+- `akm health` checks every configured git bundle for tracked `env/` or
+  `secrets/` files with a remote, not only the working stash, and names the
+  bundle in each warning. A bundle whose `.gitignore` carries
+  `# akm: intentionally track env and secrets` is not reported; the warning
+  names that line as the way to acknowledge intentional tracking (#1291).
+- `akm health`'s `type-directory-disagreement` warning uses the indexer's own
+  directory rules, so `scripts/README.md` or `knowledge/example.sh` no longer
+  warn, and it checks only `akm`-adapter entries inside their component root (#1288).
+- `akm metrics` reports token usage as unknown, with the number of calls that
+  reported it, instead of zero when the provider sent none. A call reporting
+  prompt and completion tokens but no total now counts their sum in the LLM
+  usage aggregate `akm health` shares (#1294).
+- Claude plugin health uses native installation, scope and enabled metadata
+  instead of choosing the highest cached version. It reads `AKM_MIN_VERSION`
+  as well as the legacy range, and reports uncertain selections as unknown (#1286).
+- Repeated fenced identifiers contribute once per document to search content,
+  reducing repetition bias while retaining distinct code names. Existing
+  content projections and embedding inputs refresh on the next index pass (#1284).
+
 ## [0.10.261019] - 2026-10-29
 
 The first stable release of the 0.10 line, published to npm `latest`. Its

package/STABILITY.md

@@ -4,14 +4,6 @@
 **with one caveat**: while the version is 0.x, minor releases (0.x → 0.x+1)
 may include breaking changes.
 
-**0.9.x series exception.** The 0.9.x releases are a deliberate refactoring
-and clean-up series: the goal is to pay off all remaining technical debt and
-land every planned breaking change before 0.10. While that work completes,
-**0.9.x patch releases may also contain breaking changes** — each one called
-out in the CHANGELOG with a migration note. The 0.10.x series returns to bug
-fixes and tuning, and aims to restore the normal discipline of breaking
-changes only in major and minor releases.
-
 **Version floor (0.10, #1091).** 0.10 reads what 0.9.15 and later wrote: config,
 `state.db`, task sources, frozen workflow plans and scheduler rows. It does not
 convert anything older. An install on an earlier release runs `akm migrate

package/dist/assets/templates/html/metrics.html

@@ -363,17 +363,19 @@ function aggregate(rows, opts) {
 // and carry no ref, source or event type, so only the date range applies.
 function aggregateLlm(rows, f) {
   var by = { stage: Object.create(null), process: Object.create(null), engine: Object.create(null) }, daily = new Map();
-  var t = { calls: 0, tokens: 0, failures: 0, durationMs: 0 };
+  var t = { calls: 0, tokens: 0, failures: 0, durationMs: 0, usageCalls: 0 };
   rows.forEach(function (r) {
     var d = dayOf(r.day);
     if (f.from && d < f.from) return;
     if (f.to && d > f.to) return;
     var tok = tokensOf(r), calls = r.calls || 0, failed = r.outcome === 'error' ? calls : 0;
-    t.calls += calls; t.tokens += tok; t.durationMs += r.durationMs || 0; t.failures += failed;
+    // Rows from a report that predates usage coverage count as fully measured.
+    var measured = r.usageCalls != null ? r.usageCalls : calls;
+    t.calls += calls; t.tokens += tok; t.durationMs += r.durationMs || 0; t.failures += failed; t.usageCalls += measured;
     [['stage', r.stage], ['process', r.process], ['engine', r.engine]].forEach(function (p) {
       var k = p[1] || 'unattributed';
-      var e = by[p[0]][k] || (by[p[0]][k] = { name: k, calls: 0, tokens: 0, failures: 0 });
-      e.calls += calls; e.tokens += tok; e.failures += failed;
+      var e = by[p[0]][k] || (by[p[0]][k] = { name: k, calls: 0, tokens: 0, failures: 0, usageCalls: 0 });
+      e.calls += calls; e.tokens += tok; e.failures += failed; e.usageCalls += measured;
     });
     var day = daily.get(d) || { day: d, calls: 0, durationMs: 0 };
     day.calls += calls; day.durationMs += r.durationMs || 0;
@@ -621,7 +623,7 @@ function toCsv(columns, rows) {
     var agg = useRows ? aggregateLlm(LLM, { from: state.from, to: state.to }) : null;
     $('llm-hint').textContent = useRows ? 'follows the date range only' : 'window-wide aggregate (no per-call rows)';
     function fromAggregate(o) {
-      return Object.keys(o || {}).map(function (k) { return { name: k, tokens: o[k].totalTokens, calls: o[k].calls, failures: o[k].failures }; })
+      return Object.keys(o || {}).map(function (k) { return { name: k, tokens: o[k].totalTokens, calls: o[k].calls, failures: o[k].failures, usageCalls: o[k].usageCalls != null ? o[k].usageCalls : o[k].calls }; })
         .sort(function (a, b) { return b.tokens - a.tokens; });
     }
     var dims = [
@@ -633,7 +635,7 @@ function toCsv(columns, rows) {
       var list = d[1].slice(0, 15);
       if (!hasData(d[0], list.length > 0, 'No LLM calls recorded')) return;
       chart(d[0], Object.assign(barOption(list.map(function (x) { return x.name; }),
-        [{ name: 'tokens', type: 'bar', itemStyle: { color: css('--purple') }, data: list.map(function (x) { return x.tokens; }) }], true), {}));
+        [{ name: 'tokens', type: 'bar', itemStyle: { color: css('--purple') }, data: list.map(function (x) { return x.calls > 0 && x.usageCalls === 0 ? null : x.tokens; }) }], true), {}));
     });
     if (hasData('ch-llm-time', useRows && agg.daily.length > 0, 'No per-call rows in this report')) {
       var days = agg.daily.map(function (d) { return d.day; });
@@ -744,15 +746,19 @@ function toCsv(columns, rows) {
     var t = agg.totals;
     var tokens = llm ? llm.totals.tokens : DATA.llm.totalTokens;
     var calls = llm ? llm.totals.calls : DATA.llm.calls;
+    var usageCalls = llm ? llm.totals.usageCalls : (DATA.llm.usageCalls != null ? DATA.llm.usageCalls : calls);
+    // Calls whose provider sent no usage are unknown, not zero tokens.
+    var llmSub = fmtN(calls) + ' calls' + (usageCalls < calls ? ', ' + fmtN(usageCalls) + ' reported usage' : '');
     var tasks = DATA.tasks || {};
     var cards = [
       ['Searches', fmtN(t.searches), fmtN(t.curates) + ' curates', ''],
       ['Shows', fmtN(t.shows), '', ''],
-      ['Select rate', fmtPct(DATA.usage.selectRate), 'window-wide', ''],
+      ['Selects per search', DATA.usage.selectsPerSearch == null ? '—' : DATA.usage.selectsPerSearch.toFixed(2),
+        fmtN(DATA.usage.totals.selects) + ' selects / ' + fmtN(DATA.usage.totals.searchesWithHits) + ' searches with hits, window-wide, selects not source-filtered', ''],
       ['Zero-result rate', fmtPct(t.searches ? t.zeroResult / t.searches : null), fmtN(t.zeroResult) + ' searches', t.zeroResult ? 'yellow' : ''],
       ['Feedback', '<span class="pos">+' + fmtN(t.positive) + '</span> / <span class="neg">−' + fmtN(t.negative) + '</span>',
         'net ' + (t.positive - t.negative >= 0 ? '+' : '−') + Math.abs(t.positive - t.negative), ''],
-      ['LLM tokens', fmtN(tokens), fmtN(calls) + ' calls', ''],
+      ['LLM tokens', calls > 0 && usageCalls === 0 ? 'unknown' : fmtN(tokens), llmSub, usageCalls < calls ? 'yellow' : ''],
       ['Task fail rate', fmtPct(tasks.failRate), fmtN(tasks.failed) + ' of ' + fmtN(tasks.runs) + ' runs, window-wide', tasks.failed ? 'red' : '']
     ];
     $('kpis').innerHTML = cards.map(function (c) {

package/dist/assets/ui/overview.js

@@ -70,10 +70,10 @@ function metricsSection(m) {
       ${tile("Searches", fmtNum(u.totals.searches), `${fmtNum(u.totals.zeroResultSearches)} with no results`)}
       ${tile("Shows", fmtNum(u.totals.shows), `${fmtNum(u.totals.distinctAssets)} distinct assets`)}
       ${tile("Curates", fmtNum(u.totals.curates))}
-      ${tile("Select rate", fmtPct(u.selectRate), `${fmtNum(u.totals.selects)} selects`)}
+      ${tile("Selects per search", u.selectsPerSearch == null ? "—" : u.selectsPerSearch.toFixed(2), `${fmtNum(u.totals.selects)} selects / ${fmtNum(u.totals.searchesWithHits)} searches with hits`)}
       ${tile("Median search", fmtMs(u.searchMedianMs))}
       ${tile("Feedback", `+${fmtNum(m.feedback.totals.positive)} / -${fmtNum(m.feedback.totals.negative)}`, "positive / negative")}
-      ${tile("LLM calls", fmtNum(m.llm.calls), `${fmtNum(m.llm.failures)} failed, ${fmtNum(m.llm.totalTokens)} tokens`)}
+      ${tile("LLM calls", fmtNum(m.llm.calls), `${fmtNum(m.llm.failures)} failed, ${m.llm.calls > 0 && m.llm.usageCalls === 0 ? "unknown" : fmtNum(m.llm.totalTokens)} tokens`)}
       ${tile("Pending proposals", fmtNum(m.proposals.byStatus.pending ?? 0))}
       ${tile("Task runs", fmtNum(m.tasks.runs), `${fmtNum(m.tasks.failed)} failed`)}
       ${tile("Index builds", fmtNum(m.index.runs), `median ${fmtMs(m.index.medianMs)}`)}

package/dist/commands/health/llm-usage.js

@@ -21,6 +21,13 @@ function emptyLlmUsageStageAggregate() {
         failures: 0,
     };
 }
+/** True when the provider response carried any token count. Absent usage is unknown, not zero. */
+export function hasTokenUsage(record) {
+    return (record.promptTokens !== undefined ||
+        record.completionTokens !== undefined ||
+        record.totalTokens !== undefined ||
+        record.reasoningTokens !== undefined);
+}
 /** A zeroed aggregate — also the value health reports when it could not read state.db at all (#791). */
 export function emptyLlmUsageAggregate() {
     return { ...emptyLlmUsageStageAggregate(), byStage: {}, byProcess: {}, byEngine: {} };
@@ -28,7 +35,7 @@ export function emptyLlmUsageAggregate() {
 /**
  * Aggregate `llm_usage` events (#576) into a window total plus a per-stage
  * breakdown of call count, wall-time, and token usage. Token fields absent from
- * a best-effort record contribute 0. Calls with no `stage` land under
+ * a best-effort record add nothing and the call is left out of `usageCalls`. Calls with no `stage` land under
  * {@link UNATTRIBUTED_STAGE}.
  */
 export function summarizeLlmUsage(events) {
@@ -47,11 +54,18 @@ export function summarizeLlmUsage(events) {
             dimensions.push(groups[key]);
         }
         for (const target of [aggregate, ...dimensions]) {
+            target.usageCalls ??= 0;
+            target.reasoningCalls ??= 0;
             target.calls += 1;
+            if (hasTokenUsage(record))
+                target.usageCalls += 1;
+            if (record.reasoningTokens !== undefined)
+                target.reasoningCalls += 1;
             target.totalDurationMs += record.durationMs;
             target.promptTokens += record.promptTokens ?? 0;
             target.completionTokens += record.completionTokens ?? 0;
-            target.totalTokens += record.totalTokens ?? 0;
+            // A call without a total counts as prompt + completion, as the per-day metrics rows do.
+            target.totalTokens += record.totalTokens ?? (record.promptTokens ?? 0) + (record.completionTokens ?? 0);
             target.reasoningTokens += record.reasoningTokens ?? 0;
             if (record.outcome === "error")
                 target.failures += 1;

package/dist/commands/health/plugin-staleness.js

@@ -2,51 +2,11 @@
 // 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/.
 /**
- * `plugin-version` advisory for `akm health` (itlackey/akm#832).
- *
- * #828 was filed as a CLI bug — session extraction failing on 232/234 runs —
- * and took a full investigation to resolve. The actual cause: the harness
- * plugin (`akm@akm-plugins`, installed in Claude Code's plugin cache) was
- * three days stale relative to the fix, and its own `AKM_VERSION_RANGE` gate
- * had nothing to do with it — the plugin was simply running old code. Every
- * fact needed to reach that conclusion in one step was already on disk:
- *
- *   - installed plugin version: `~/.claude/plugins/cache/<marketplace>/akm/<version>/.claude-plugin/plugin.json`
- *   - the plugin's own akm-cli compatibility contract: `<pluginDir>/shared/akm-version.ts`'s `AKM_VERSION_RANGE`
- *   - the running CLI's version: `../../version.ts`'s `pkgVersion`
- *
- * Nothing correlated them, so a stale plugin was indistinguishable from a
- * broken CLI. This module closes that gap with three checks, one per
- * detected plugin:
- *
- *   1. report the installed version;
- *   2. compare it against the newest tag published to the plugin's git
- *      remote, and warn (naming the update command) when behind;
- *   3. the sharp one — check whether the *installed plugin's* declared
- *      `AKM_VERSION_RANGE` admits the *running* CLI version. When it does
- *      not, the plugin has silently disabled itself (both surfaces log
- *      `version_out_of_range` / `akm_version_mismatch` and degrade quietly)
- *      and there was previously no way to know that from the CLI side.
- *
- * Read-only: this never fetches, writes, or mutates the plugin cache or
- * marketplace clone. Check 2 is one of two deliberate exceptions to "`akm
- * health` makes no network call" (see `./health-advisories.md`; the other is
- * the `cli-version` advisory in `./version-drift.ts`, #950): a plugin's
- * local marketplace clone is not proof of what is newest upstream — the
- * incident above involved a clone that hadn't seen the fix's tag at all — so
- * the only way to ever detect drift is to ask the remote what tags exist.
- * That query is a `git ls-remote --symref` (lists refs; fetches nothing,
- * writes nothing) with a short timeout, and any failure (offline, no
- * remote, timeout) degrades to "installed version reported, no staleness
- * claim" rather than a false positive or a hang. Like `cli-version`, this
- * check is gated behind `--probe`/`--no-probe`: with probing off the remote is
- * not asked, the row reports `unknown` ("not probed") and only the local range
- * check (3) runs.
- *
- * Every collector here is best-effort and silent on missing/unreadable
- * input: no Claude plugin installed, no marketplace clone, an unreadable
- * manifest, or a malformed version range must never crash `akm health` and
- * must never produce a false "stale" or "inactive" warning.
+ * Report the installations Claude's native listing selects, not the versions
+ * left in its cache. The listing owns scope and merged enabled settings; it
+ * cannot prove what an already-running session has loaded. Ambiguous scoped
+ * installations and unavailable compatibility contracts are reported as unknown.
+ * Remote release checks remain optional under --no-probe.
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -64,7 +24,9 @@ import { openCodeConfigSpec } from "../sources/plugin-upgrade.js";
  * `AKM_CLAUDE_PROJECTS_DIR` in `../../integrations/harnesses/claude/session-log.ts`.
  */
 function claudePluginsDir() {
-    return process.env.AKM_CLAUDE_PLUGINS_DIR ?? path.join(os.homedir(), ".claude", "plugins");
+    return (process.env.AKM_CLAUDE_PLUGINS_DIR ??
+        process.env.CLAUDE_CODE_PLUGIN_CACHE_DIR ??
+        path.join(process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude"), "plugins"));
 }
 /**
  * Root of OpenCode's package cache, same override pattern as
@@ -159,74 +121,90 @@ function buildOpencodeBundledAdvisory(plugin, bundled, cliVersion) {
         evidence: bundled.spec ? { bundledVersion, cliVersion, spec: bundled.spec } : { bundledVersion, cliVersion },
     };
 }
-/**
- * Scan `<pluginsRoot>/cache/<marketplace>/akm/<version>/` for every
- * `akm` plugin cache entry, picking the highest cached version per
- * marketplace when more than one is present. Returns `[]` (never throws)
- * when the cache directory is absent, empty, or unreadable — that is the
- * ordinary "no Claude plugin installed" case, not an error.
- */
 function detectInstalledPlugins(pluginsRoot) {
-    const cacheDir = path.join(pluginsRoot, "cache");
-    let marketplaces;
+    if (!fs.existsSync(path.join(pluginsRoot, "installed_plugins.json")) &&
+        !fs.existsSync(path.join(pluginsRoot, "cache")))
+        return [];
     try {
-        marketplaces = fs.readdirSync(cacheDir);
+        const listed = spawnSync("claude", ["plugin", "list", "--json"], {
+            encoding: "utf8",
+            timeout: 30_000,
+            env: {
+                ...process.env,
+                ...(process.env.AKM_CLAUDE_PLUGINS_DIR
+                    ? { CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR ?? path.dirname(pluginsRoot) }
+                    : {}),
+                CLAUDE_CODE_PLUGIN_CACHE_DIR: pluginsRoot,
+            },
+        });
+        if (listed.status !== 0)
+            return undefined;
+        const rows = JSON.parse(listed.stdout);
+        if (!Array.isArray(rows))
+            return undefined;
+        const detected = rows.flatMap((row) => {
+            if (typeof row?.id !== "string" || !row.id.startsWith("akm@"))
+                return [];
+            const applicable = typeof row.projectPath !== "string" ||
+                path.resolve(process.cwd()) === path.resolve(row.projectPath) ||
+                path.resolve(process.cwd()).startsWith(`${path.resolve(row.projectPath)}${path.sep}`);
+            return [
+                {
+                    harness: "claude",
+                    marketplace: row.id.slice(4),
+                    pluginName: "akm",
+                    version: typeof row.folderVersion === "string"
+                        ? row.folderVersion
+                        : typeof row.version === "string"
+                            ? row.version
+                            : "unknown",
+                    pluginDir: typeof row.readFromFolder === "string"
+                        ? row.readFromFolder
+                        : typeof row.installPath === "string"
+                            ? row.installPath
+                            : "",
+                    applicable,
+                    selectionKnown: false,
+                    scope: typeof row.scope === "string" ? row.scope : "unknown",
+                    enabled: typeof row.enabled === "boolean" ? row.enabled : undefined,
+                    ...(typeof row.projectPath === "string" ? { projectPath: row.projectPath } : {}),
+                },
+            ];
+        });
+        for (const plugin of detected) {
+            const applicable = detected.filter((p) => p.marketplace === plugin.marketplace && p.applicable);
+            plugin.selectionKnown =
+                plugin.applicable &&
+                    isExactSemver(plugin.version) &&
+                    plugin.scope !== "unknown" &&
+                    plugin.pluginDir !== "" &&
+                    new Set(applicable.map((p) => `${p.version}:${p.pluginDir}`)).size === 1;
+        }
+        return detected;
     }
     catch {
-        return [];
-    }
-    const detected = [];
-    for (const marketplace of marketplaces) {
-        const pluginDir = path.join(cacheDir, marketplace, "akm");
-        let versions;
-        try {
-            versions = fs.readdirSync(pluginDir).filter(isExactSemver);
-        }
-        catch {
-            continue;
-        }
-        if (versions.length === 0)
-            continue;
-        const latest = highestVersion(versions);
-        if (!latest)
-            continue;
-        const versionDir = path.join(pluginDir, latest);
-        const manifestPath = path.join(versionDir, ".claude-plugin", "plugin.json");
-        try {
-            const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-            if (typeof manifest.version !== "string")
-                continue;
-            detected.push({
-                harness: "claude",
-                marketplace,
-                pluginName: "akm",
-                version: manifest.version,
-                pluginDir: versionDir,
-            });
-        }
-        catch {
-            // Unreadable/malformed manifest — skip this entry rather than crash.
-        }
+        return undefined;
     }
-    return detected;
 }
-/**
- * Extract `AKM_VERSION_RANGE` from the installed plugin's vendored
- * `shared/akm-version.ts`. Returns `undefined` when the file is missing,
- * unreadable, or does not contain the expected declaration — callers must
- * treat that as "compatibility unknown", never as a mismatch.
- */
-function readVersionRange(pluginDir) {
-    const versionFilePath = path.join(pluginDir, "shared", "akm-version.ts");
+/** Read the contract, never execute plugin source. A minimum admits later prereleases too. */
+function readCompatibility(pluginDir, cliVersion) {
     let text;
     try {
-        text = fs.readFileSync(versionFilePath, "utf8");
+        text = fs.readFileSync(path.join(pluginDir, "shared", "akm-version.ts"), "utf8");
     }
     catch {
-        return undefined;
+        return {};
+    }
+    const minimum = text.match(/export\s+const\s+AKM_MIN_VERSION\s*=\s*["']([^"']+)["']/)?.[1];
+    if (minimum !== undefined) {
+        if (!isExactSemver(minimum) || !isExactSemver(cliVersion))
+            return {};
+        return { versionRange: `>=${minimum}`, admitted: highestVersion([minimum, cliVersion]) === cliVersion };
     }
-    const match = text.match(/export\s+const\s+AKM_VERSION_RANGE\s*=\s*["']([^"']+)["']/);
-    return match?.[1];
+    const range = text.match(/export\s+const\s+AKM_VERSION_RANGE\s*=\s*["']([^"']+)["']/)?.[1];
+    if (!range || !isSemverRange(range) || !isExactSemver(cliVersion))
+        return {};
+    return { versionRange: range, admitted: satisfiesRange(cliVersion, range) };
 }
 const LS_REMOTE_TIMEOUT_MS = 5_000;
 /**
@@ -311,7 +289,17 @@ export function collectPluginStalenessAdvisories(options) {
     const listRemoteTags = options.listRemoteTags ?? realListRemoteTags;
     const plugins = detectInstalledPlugins(pluginsRoot);
     const probe = options.probe ?? true;
-    const results = plugins.map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, listRemoteTags, probe));
+    const results = (plugins ?? []).map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, listRemoteTags, probe));
+    if (plugins === undefined && fs.existsSync(pluginsRoot)) {
+        results.push({
+            name: "plugin-version",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "Claude plugin installation and enabled state could not be resolved with `claude plugin list --json`; cached versions do not establish the selected installation.",
+            evidence: { harness: "claude", installedVersion: null, enabled: null, admitted: null },
+        });
+    }
     const opencodeCacheRoot = options.opencodeCacheRoot ?? defaultOpencodeCacheRoot();
     for (const plugin of OPENCODE_PLUGIN_LOCATIONS) {
         for (const bundled of findBundledAkm(plugin, opencodeCacheRoot)) {
@@ -326,7 +314,9 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
     const marketplaceDir = path.join(pluginsRoot, "marketplaces", plugin.marketplace);
     let availableVersion;
     try {
-        const tags = probe && fs.existsSync(marketplaceDir) ? listRemoteTags(marketplaceDir) : undefined;
+        const tags = probe && plugin.selectionKnown && plugin.enabled !== false && fs.existsSync(marketplaceDir)
+            ? listRemoteTags(marketplaceDir)
+            : undefined;
         availableVersion = tags && tags.length > 0 ? highestVersion(tags) : undefined;
     }
     catch {
@@ -336,10 +326,20 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
         plugin.version !== availableVersion &&
         highestVersion([plugin.version, availableVersion]) === availableVersion;
     // Point 3: does the plugin's own declared range admit the running CLI?
-    const versionRange = readVersionRange(plugin.pluginDir);
-    const rangeKnown = versionRange !== undefined && isSemverRange(versionRange);
-    const admitted = rangeKnown ? satisfiesRange(cliVersion, versionRange) : undefined;
-    const messageParts = [`${pluginRef}: installed ${plugin.version}`];
+    const { versionRange, admitted } = readCompatibility(plugin.pluginDir, cliVersion);
+    const messageParts = [
+        `${pluginRef}: installed ${plugin.version} (${plugin.scope}${plugin.projectPath ? `: ${plugin.projectPath}` : ""})`,
+    ];
+    if (!plugin.applicable)
+        messageParts.push("installed for another project; not selected in this directory");
+    else if (!plugin.selectionKnown)
+        messageParts.push("effective selection unknown across native installations");
+    if (plugin.enabled === false)
+        messageParts.push("disabled in Claude settings");
+    else if (plugin.enabled === undefined)
+        messageParts.push("enabled state unknown");
+    if (admitted === undefined)
+        messageParts.push("CLI compatibility unknown");
     if (!probe)
         messageParts.push("newest tag was not probed");
     if (availableVersion !== undefined) {
@@ -347,15 +347,23 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
     }
     if (stale)
         messageParts.push(`-> claude plugin update ${pluginRef}`);
-    if (rangeKnown && admitted === false) {
-        messageParts.push(`installed plugin requires akm-cli ${versionRange}; running ${cliVersion} -> NOT ADMITTED (plugin is inactive)`);
+    if (plugin.selectionKnown && plugin.enabled === true && admitted === false) {
+        messageParts.push(`installed plugin requires akm-cli ${versionRange}; running ${cliVersion} -> NOT ADMITTED by the plugin compatibility contract`);
     }
     return {
         name: "plugin-version",
         kind: "deterministic",
         // Not probed => staleness is unknown, not "up to date"; only the local
         // range check can still warn.
-        status: stale || admitted === false ? "warn" : probe ? "pass" : "unknown",
+        status: plugin.enabled === false || !plugin.applicable
+            ? "pass"
+            : !plugin.selectionKnown || plugin.enabled === undefined
+                ? "unknown"
+                : stale || admitted === false
+                    ? "warn"
+                    : probe && availableVersion !== undefined && admitted !== undefined && plugin.enabled === true
+                        ? "pass"
+                        : "unknown",
         confidence: "high",
         message: messageParts.join(" — "),
         evidence: {
@@ -363,6 +371,12 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
             marketplace: plugin.marketplace,
             plugin: plugin.pluginName,
             installedVersion: plugin.version,
+            scope: plugin.scope,
+            applicable: plugin.applicable,
+            selectionKnown: plugin.selectionKnown,
+            projectPath: plugin.projectPath ?? null,
+            enabled: plugin.enabled ?? null,
+            installPath: plugin.pluginDir,
             availableVersion: availableVersion ?? null,
             ...(probe ? {} : { probed: false }),
             stale,

package/dist/commands/health/stash-exposure.js

@@ -9,18 +9,35 @@
  * is when secret assets are git-TRACKED **and** a remote is configured — only
  * then can a `git push` exfiltrate tokens/keys. Warn on exactly that
  * combination; stay silent on the tracked-but-no-remote opt-in so the advisory
- * catches the exposure without nagging the intentional backup.
+ * catches the exposure without nagging the intentional backup. A stash whose
+ * `.gitignore` carries the intentional-tracking marker has acknowledged the
+ * risk, so it is not warned about at all.
  */
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { STASH_GITIGNORE_TRACK_SECRETS_MARKER } from "../sources/stash-skeleton.js";
 const realGit = (stashDir, args) => {
     const result = spawnSync("git", ["-C", stashDir, ...args], { encoding: "utf8", timeout: 5_000 });
     return { ok: result.status === 0, stdout: (result.stdout ?? "").trim() };
 };
+/** True when the stash `.gitignore` carries the explicit intentional-tracking marker. */
+function hasIntentionalTrackingMarker(stashDir) {
+    try {
+        return fs.readFileSync(path.join(stashDir, ".gitignore"), "utf8").includes(STASH_GITIGNORE_TRACK_SECRETS_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Build the `stash-git-exposure` advisory, or `undefined` when there is nothing
- * to warn about (not a git repo, no tracked env/secret assets, or no remote).
+ * to warn about (tracking acknowledged by the marker, not a git repo, no
+ * tracked env/secret assets, or no remote).
  */
 export function collectStashExposureAdvisory(stashDir, git = realGit) {
+    if (hasIntentionalTrackingMarker(stashDir))
+        return undefined;
     // Not a git work tree → nothing to expose.
     if (!git(stashDir, ["rev-parse", "--is-inside-work-tree"]).ok)
         return undefined;
@@ -37,10 +54,11 @@ export function collectStashExposureAdvisory(stashDir, git = realGit) {
         kind: "deterministic",
         status: "warn",
         confidence: "high",
-        message: `${trackedFiles.length} env/secret file(s) are git-tracked AND a remote is configured — ` +
+        message: `Bundle at ${stashDir}: ${trackedFiles.length} env/secret file(s) are git-tracked AND a remote is configured — ` +
             `a 'git push' can leak tokens/keys (${preview}). ` +
             "Run 'git rm --cached' on them (a .gitignore rule alone does NOT untrack already-tracked " +
-            "files) and then add env/+secrets/ to .gitignore to prevent recurrence (akm bundle create scaffolds it).",
-        evidence: { trackedSecretFiles: trackedFiles },
+            "files) and then add env/+secrets/ to .gitignore to prevent recurrence (akm bundle create scaffolds it), " +
+            `or, to keep tracking them on purpose, add '${STASH_GITIGNORE_TRACK_SECRETS_MARKER}' to .gitignore.`,
+        evidence: { bundleRoot: stashDir, trackedSecretFiles: trackedFiles },
     };
 }