akm-cli 0.9.2-alpha.3 → 0.9.2-alpha.5

package/STABILITY.md

@@ -58,6 +58,7 @@ enumeration of the whole `proposal` noun group.
 | `akm curate` | Stable | |
 | `akm show` | Stable | |
 | `akm workflow status` | Stable | |
+| `akm workflow plan` | Evolving | New in 0.9.2; secret-free provenance output; envelope shape may change. |
 | `akm workflow list` | Stable | |
 | `akm workflow create` | Stable | |
 | `akm workflow resume` | Stable | |
@@ -110,6 +111,7 @@ enumeration of the whole `proposal` noun group.
 | `akm task history` | Evolving | |
 | `akm task sync` | Evolving | |
 | `akm task doctor` | Evolving | |
+| `akm task explain` | Evolving | New in 0.9.2; secret-shaped values in provenance output are redacted on a best-effort heuristic basis (not a guarantee). |
 
 ## Stable
 
@@ -254,11 +256,27 @@ CHANGELOG with a migration note.
   `akm improve && akm proposal drain --promote --yes`, or a `triage` block
   with `applyMode: "promote"` in your strategy.
 - **Tasks** — `akm task` subcommand surface (`add | run | sync | doctor |
-  history`; no alias, no `list`/`remove`/`init`/`enable`/`disable`); strict
-  version-2 YAML for scheduled tasks. Prompt tasks use named engines and task
-  history metadata is versioned. Schema additions in patch releases; removals
-  only at minor. Bare `akm task` is a usage error naming the subcommands
-  (`akm task doctor` reports scheduler diagnostics).
+  history | explain`; no alias, no `list`/`remove`/`init`/`enable`/`disable`);
+  task source v4 YAML (typed `inputs:`, optional `schedule:`) is the only
+  accepted version — task v3 and task v2 sources are converted by
+  `akm migrate apply`. Command tasks use named engines and task history
+  metadata is versioned. Schema additions in patch releases; removals only at
+  minor. Bare `akm task` is a usage error naming the subcommands
+  (`akm task doctor` reports scheduler diagnostics). `akm task explain <ref>`
+  (new in 0.9.2) and `akm workflow plan <ref>` are both zero-write
+  provenance surfaces: they show what a task or workflow would do —
+  resolved target, input bindings, child expansion — without starting or
+  publishing a run. `akm workflow plan` is secret-free **by construction**
+  (the excluded data never reaches the command). `akm task explain`
+  instead **redacts** secret-shaped input values on a best-effort
+  heuristic basis — a value that doesn't match the heuristic can still
+  print unredacted.
+- **Workflow plan** — `akm workflow plan <ref>`, new in 0.9.2: zero-write
+  compile+freeze introspection (the canonical step graph, task/child
+  expansion, input bindings, and lowering notices for a workflow, without
+  starting or publishing a run). The envelope shape may still change; the
+  five long-Stable `workflow` verbs (`status`, `list`, `create`, `resume`,
+  `abandon`) and `run` are unaffected.
 - **Events / log** — `akm log` is the event-stream surface (0.9.0: the
   asset-scoped `akm history` surface, and `log`'s own `tail` subcommand, were
   both removed; `log` is now a leaf command — the former `list` surface).

package/dist/assets/hints/cli-hints-full.md

@@ -362,16 +362,21 @@ akm task sync --rebind                         # Also re-pin the scheduler's akm
 akm task doctor                                # Scheduler binding + runtime eligibility diagnosis
 akm task history                               # Recent run rows (status, timing)
 akm task run <id>                              # Run one task immediately (works when disabled)
+akm task explain <ref>                         # Read-only: declared inputs, target, schedule — spawns nothing
 akm search --type task                         # Enumerate task assets (there is no `task list`)
 ```
 
-Task files use strict task v3 (`version: 3`). To disable one, set
-`akm.enabled: false` and run `akm task sync`
-(the cron line stays, commented). To remove one, delete the YAML and run
-`akm task sync` — the scheduler entry is unbound. Per-task `akm.timeout` may
-be `null` (disable the invocation timer) or a duration/number overriding the
-selected engine invocation timeout. Preview old task-v2 conversion with
-`akm migrate apply --dry-run`.
+Task files use task source v4 (`version: 4`). There is no `akm:` options bag
+or `on:` block — every control (`schedule`, `timeout`, `engine`, `model`,
+`redact`, `maxSteps`, `maxRetries`, …) is a top-level key now. Typed
+`inputs:` declarations and a bounded `output:` schema work like a
+workflow's (`output:` replaces v3's `akm.outputSchema`). To disable one
+schedule entry, set that entry's `enabled: false` under `schedule:` and run
+`akm task sync` (the cron line stays, commented); to remove one, delete the
+YAML and run `akm task sync` — the scheduler entry is unbound. Top-level
+`timeout:` may be `null` (disable the invocation timer) or a duration/number
+overriding the selected engine invocation timeout. Preview old task-v2/v3
+conversion with `akm migrate apply --dry-run`.
 
 ## Agent Dispatch
 

package/dist/assets/tasks/core/extract.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm proposal extract --auto
-akm:
-  schedule: "*/30 * * * *"
-  enabled: true
-  description: Opt-in all-harness session extraction every 30 min
+description: Opt-in all-harness session extraction every 30 min
+schedule: "*/30 * * * *"

package/dist/assets/tasks/core/improve.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm improve
-akm:
-  schedule: "0 2 * * *"
-  enabled: true
-  description: Run improve pipeline nightly
+description: Run improve pipeline nightly
+schedule: "0 2 * * *"

package/dist/assets/tasks/core/index-refresh.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm index
-akm:
-  schedule: "0 4 * * *"
-  enabled: true
-  description: Nightly incremental index refresh
+description: Nightly incremental index refresh
+schedule: "0 4 * * *"

package/dist/assets/tasks/core/sync.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm sync
-akm:
-  schedule: "*/15 * * * *"
-  enabled: true
-  description: Sync stash changes to git remote every 15 min
+description: Sync stash changes to git remote every 15 min
+schedule: "*/15 * * * *"

package/dist/assets/tasks/core/version-check.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm upgrade --check
-akm:
-  schedule: "0 9 * * 1"
-  enabled: true
-  description: Weekly check for new akm releases
+description: Weekly check for new akm releases
+schedule: "0 9 * * 1"

package/dist/assets/tasks/improve/akm-graph-refresh-weekly.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm improve --strategy graph-refresh --skip-if-locked
-akm:
-  schedule: "10 3 * * 0"
-  enabled: true
-  description: Full-corpus graph rebuild (weekly Sunday 3:10am)
+description: Full-corpus graph rebuild (weekly Sunday 3:10am)
+schedule: "10 3 * * 0"

package/dist/assets/tasks/improve/akm-improve-catchup.yml

@@ -1,9 +1,9 @@
-version: 3
+version: 4
 run: akm improve --strategy catchup --skip-if-locked
-akm:
-  schedule: "0 4 * * *"
+description: Manual recovery — consolidation + triage drain (run on demand via `akm task run akm-improve-catchup`)
 # Manual-recovery task: ships disabled (the retired registerDefaultTasks
 # marked it enableMode: "manual"). `akm task run` works while disabled;
-# opting into the schedule is `enabled: true` + `akm task sync`.
-  enabled: false
-  description: Manual recovery — consolidation + triage drain (run on demand via `akm task run akm-improve-catchup`)
+# opting into the schedule is `schedule[].enabled: true` + `akm task sync`.
+schedule:
+  - cron: "0 4 * * *"
+    enabled: false

package/dist/assets/tasks/improve/akm-improve-consolidate.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm improve --strategy consolidate --skip-if-locked
-akm:
-  schedule: "20 */4 * * *"
-  enabled: true
-  description: Consolidation-only pass (every 4h at :20)
+description: Consolidation-only pass (every 4h at :20)
+schedule: "20 */4 * * *"

package/dist/assets/tasks/improve/akm-improve-frequent.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm improve --strategy frequent --skip-if-locked
-akm:
-  schedule: "40 * * * *"
-  enabled: true
-  description: Frequent inference pass (hourly at :40; improve-stage extract off)
+description: Frequent inference pass (hourly at :40; improve-stage extract off)
+schedule: "40 * * * *"

package/dist/assets/tasks/improve/akm-improve-nightly.yml

@@ -1,6 +1,4 @@
-version: 3
+version: 4
 run: akm improve --strategy thorough --skip-if-locked
-akm:
-  schedule: "15 2 * * *"
-  enabled: true
-  description: Full nightly quality sweep (daily 2:15am; suggested for server installs)
+description: Full nightly quality sweep (daily 2:15am; suggested for server installs)
+schedule: "15 2 * * *"

package/dist/cli/unknown-flags.js

@@ -181,7 +181,18 @@ export function assertKnownFlags(root, rawArgs) {
     const known = collectKnownArgs(root, rawArgs);
     if (!known.resolved)
         return;
-    const dynamicWorkflowParams = known.path.join(" ") === "workflow run";
+    // `workflow run`, `task run`, and `task explain` each own one deliberately
+    // dynamic namespace: long options become exact-name parameter/input flags
+    // and are checked against the frozen plan / task source's own contract
+    // before this gate would otherwise reject them (spec
+    // docs/plans/specs/p2a-task-source-v4.md §5.1 — task run's
+    // UNKNOWN_FLAG/INPUT_BINDING_INVALID must be raised from INSIDE the command
+    // body, where runWithJsonErrors renders the JSON envelope, not from this
+    // generic pre-dispatch gate; docs/plans/specs/p2b-input-bindings.md §4.5,
+    // B-55 — `task explain` reuses the identical `parseTaskInputFlags`
+    // scanner, so it needs the identical exemption).
+    const dynamicNamedFlagCommands = new Set(["workflow run", "task run", "task explain"]);
+    const dynamicWorkflowParams = dynamicNamedFlagCommands.has(known.path.join(" "));
     const selfDiagnosed = SELF_DIAGNOSED_FLAGS.get(known.path.join(" "));
     for (let i = 0; i < ownArgs.length; i += 1) {
         const token = ownArgs[i];

package/dist/cli.js

@@ -557,7 +557,14 @@ export const main = defineCommand({
     },
 });
 const MAIN_TOP_LEVEL_ARGS = main.args;
-function isTaskRunWithId(argv) {
+/**
+ * F-5 (spec docs/plans/specs/p2a-task-source-v4.md §6): exported so
+ * `akm task run`'s input-flags coverage can pin that an undeclared,
+ * per-task dynamic flag (e.g. `--scope all`) does not change this
+ * classification — it parses only `args.id` off the declared args and
+ * tolerates extra tokens (citty's non-strict `parseArgs`).
+ */
+export function isTaskRunWithId(argv) {
     const args = argv.slice(2);
     const commandIndex = findCittyTopLevelCommandIndex(args, MAIN_TOP_LEVEL_ARGS);
     const command = commandIndex >= 0 ? args[commandIndex] : undefined;

package/dist/commands/command/command-execution.js

@@ -14,6 +14,23 @@ import { prepareResolvedExecution } from "../../integrations/agent/execution-pre
 import { parseBuiltinCommandAction } from "./builtin-action.js";
 import { loadAdapterExecutionSource, } from "./execution-source-loader.js";
 import { applyPortableCommandArguments } from "./portable-template.js";
+/**
+ * F-1 (spec §5.2 point 3): resolve the ambient-first provenance stamp
+ * (matching the native arm's own `process.env.AKM_EVENT_SOURCE ?? …`) and
+ * hand it to `dispatchLoweredExecutionRequest`'s dedicated, single-purpose
+ * `eventSource` field — never through `runOptions`/`agentOptions`, which
+ * stays exactly as untrusted for overriding resolved content as it was
+ * before P1b (a caller-supplied `runOptions.env` still cannot replace frozen
+ * request data, including a scheduler-restored directory value — see
+ * `tests/integration/tasks-runner.test.ts`'s "forwards scheduled AKM
+ * directory context … without trusting task or caller overrides").
+ */
+function loweredDispatchOptions(options) {
+    const { eventSource, ...rest } = options;
+    if (eventSource === undefined)
+        return rest;
+    return { ...rest, eventSource: process.env.AKM_EVENT_SOURCE ?? eventSource };
+}
 function own(value, key) {
     return Object.hasOwn(value, key);
 }
@@ -291,13 +308,17 @@ export async function dispatchPreparedCommandInvocation(prepared, options = {})
     if (!selectedEngine) {
         throw new ConfigError(`command ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
     }
-    const result = await dispatchLoweredExecutionRequest(lowered, options);
+    const result = await dispatchLoweredExecutionRequest(lowered, loweredDispatchOptions(options));
     const consumedRefs = new Set();
     if (request.command.source)
         consumedRefs.add(request.command.source.ref);
     if (request.persona)
         consumedRefs.add(request.persona.source.ref);
-    const eventSource = resolveUsageEventSource();
+    // F-1 (spec §5.2 point 3): options.eventSource is only a FALLBACK — an
+    // ambient AKM_EVENT_SOURCE still wins (D5 clause d). Absent, this is
+    // byte-identical to the pre-P1b bare resolveUsageEventSource() call (P-07's
+    // own default is "user").
+    const eventSource = resolveUsageEventSource(process.env, options.eventSource ?? "user");
     for (const ref of consumedRefs)
         recordIndexedShowUsage(ref, eventSource);
     const announcement = fallbackAnnouncement(prepared.fallbackEngineName, selectedEngine);

package/dist/commands/health/improve-metrics.js

@@ -15,6 +15,44 @@ export function parseTaskMetadata(row) {
         ...(metadata.engine !== undefined ? { engine: metadata.engine } : {}),
     };
 }
+/**
+ * D8 read-boundary predicate (spec docs/plans/specs/p1b-model-extraction.md
+ * §5.3) for `akm health`'s `agentFailureRate`: true for a `task_history` row
+ * that represents a prepared command (agent/LLM) result, across both
+ * vocabularies. Mirrors src/tasks/run/task-history.ts's
+ * `taskHistoryRowToResult` read mapping:
+ *   - NEW rows mark themselves with metadata `targetVocab: 2` and store
+ *     `target_kind: "command"` for the agent/LLM arm.
+ *   - LEGACY rows (no marker, written before P1b's F-2 re-code) stored
+ *     `target_kind: "prompt"` for the same arm — and `"command"` for the
+ *     UNRELATED native shell/script arm, which must NOT be counted here.
+ * So an unmarked `"command"` row is a legacy shell/script run, not an
+ * agent/LLM one; a marked `"command"` row (or an unmarked `"prompt"` row) is.
+ */
+export function isAgentTaskHistoryRow(row) {
+    // Check target_kind BEFORE decoding metadata: some rows in the wild
+    // (e.g. improve-pipeline task_history rows, target_kind "improve") carry
+    // metadata_json that predates the metadataVersion:2 shape entirely, and
+    // decodeTaskHistoryMetadata throws on that — exactly like the pre-fix
+    // `target_kind === "prompt"` filter, which never called it for a row this
+    // function isn't going to count anyway. Only decode for the two target
+    // kinds this predicate can return true for.
+    if (row.target_kind !== "command" && row.target_kind !== "prompt")
+        return false;
+    // An undecodable metadata_json is by definition unmarked: pre-P1b rows can
+    // carry shapes decodeTaskHistoryMetadata rejects, and `akm health` must
+    // classify them as legacy rather than throw (round-3 review advisory).
+    let marked = false;
+    try {
+        marked = decodeTaskHistoryMetadata(row.metadata_json).targetVocab === 2;
+    }
+    catch {
+        marked = false;
+    }
+    if (row.target_kind === "command")
+        return marked;
+    return !marked;
+}
 function createUnknownImproveMetrics() {
     return {
         invoked: 0,

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

@@ -0,0 +1,219 @@
+// 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/.
+/**
+ * `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 the one deliberate exception to "`akm
+ * health` makes no network call" (see `./health-advisories.md`): 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 --tags` (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.
+ *
+ * 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.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isExactSemver, isSemverRange, maxSatisfying, satisfiesRange } from "../../registry/semver.js";
+/**
+ * Root directory holding Claude Code's plugin cache + marketplace clones.
+ * Resolved per call (not memoized) so `AKM_CLAUDE_PLUGINS_DIR` can be set
+ * after import — the override exists so tests point this at an empty
+ * fixture directory instead of the real `~/.claude/plugins`, matching
+ * `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");
+}
+/**
+ * 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;
+    try {
+        marketplaces = fs.readdirSync(cacheDir);
+    }
+    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 = maxSatisfying(versions, "*") ?? versions.sort().at(-1);
+        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 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");
+    let text;
+    try {
+        text = fs.readFileSync(versionFilePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const match = text.match(/export\s+const\s+AKM_VERSION_RANGE\s*=\s*["']([^"']+)["']/);
+    return match?.[1];
+}
+const LS_REMOTE_TIMEOUT_MS = 5_000;
+/**
+ * `git ls-remote --tags origin` against the marketplace clone's configured
+ * remote — lists refs only, fetches no objects, writes no local refs.
+ * Returns `undefined` (never throws) when the directory is not a git
+ * checkout, has no `origin` remote, or the command fails/times out (e.g.
+ * offline) — all "cannot determine availability", not "up to date".
+ */
+const realListRemoteTags = (marketplaceDir) => {
+    let result;
+    try {
+        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--tags", "origin"], {
+            encoding: "utf8",
+            timeout: LS_REMOTE_TIMEOUT_MS,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (result.status !== 0 || !result.stdout)
+        return undefined;
+    const tags = result.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.split("\t")[1])
+        .filter((ref) => typeof ref === "string" && ref.startsWith("refs/tags/"))
+        .map((ref) => ref.replace(/^refs\/tags\//, "").replace(/\^\{\}$/, ""))
+        .map((tag) => tag.replace(/^v/, ""))
+        .filter(isExactSemver);
+    return [...new Set(tags)];
+};
+/**
+ * Build one `plugin-version` advisory per detected `akm` harness plugin.
+ * Returns `[]` when no plugin is installed — the benign, common case.
+ */
+export function collectPluginStalenessAdvisories(options) {
+    const pluginsRoot = options.pluginsRoot ?? claudePluginsDir();
+    const listRemoteTags = options.listRemoteTags ?? realListRemoteTags;
+    const plugins = detectInstalledPlugins(pluginsRoot);
+    return plugins.map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, listRemoteTags));
+}
+function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags) {
+    const pluginRef = `${plugin.pluginName}@${plugin.marketplace}`;
+    // Point 2: newest available vs. installed, via the marketplace clone's remote.
+    const marketplaceDir = path.join(pluginsRoot, "marketplaces", plugin.marketplace);
+    let availableVersion;
+    try {
+        const tags = fs.existsSync(marketplaceDir) ? listRemoteTags(marketplaceDir) : undefined;
+        availableVersion = tags && tags.length > 0 ? maxSatisfying(tags, "*") : undefined;
+    }
+    catch {
+        availableVersion = undefined;
+    }
+    const stale = availableVersion !== undefined &&
+        plugin.version !== availableVersion &&
+        maxSatisfying([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}`];
+    if (availableVersion !== undefined) {
+        messageParts.push(stale ? `available ${availableVersion} (STALE)` : `available ${availableVersion} (up to date)`);
+    }
+    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)`);
+    }
+    return {
+        name: "plugin-version",
+        kind: "deterministic",
+        status: stale || admitted === false ? "warn" : "pass",
+        confidence: "high",
+        message: messageParts.join(" — "),
+        evidence: {
+            harness: plugin.harness,
+            marketplace: plugin.marketplace,
+            plugin: plugin.pluginName,
+            installedVersion: plugin.version,
+            availableVersion: availableVersion ?? null,
+            stale,
+            versionRange: versionRange ?? null,
+            cliVersion,
+            admitted: admitted ?? null,
+        },
+    };
+}