akm-cli 0.9.28-alpha.2 → 0.9.28-alpha.4

package/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.28-alpha.4] - 2026-10-08
+
+### Added
+
+- **`akm upgrade` also updates the akm plugin of each installed harness (#1007).** After the CLI step
+  it refreshes Claude Code (`claude plugin marketplace update`, then `claude plugin update`) and
+  Codex (`codex plugin marketplace upgrade`) when the `akm-plugins` marketplace is configured and the
+  plugin is installed, and replaces a stale cached `akm-opencode` (moved to the trash, then re-fetched
+  by `opencode debug config`) unless OpenCode is running, in which case it is `deferred`. It only
+  updates: a missing plugin is never installed. The result gains `plugins` (one `outcome` per harness:
+  `updated`, `current`, `skipped`, `deferred`, `failed`; under `--check`, which changes nothing,
+  `pending` for OpenCode and `unknown` for Claude Code and Codex, whose check needs a fetch) and a failed plugin exits 1. With the OpenCode plugin present the CLI moves to the akm-cli
+  that `akm-opencode@latest` pins instead of the newest release, reported under `lockstep`; if the pin
+  cannot be read the CLI is held where it is rather than moved ahead of the plugin. The
+  Containers entrypoint and the Codex hook trust entries are documented under
+  [`akm upgrade`](docs/reference/cli.md#upgrade).
+
+### Fixed
+
+- **A skill's reference file with a shell `$1` is no longer indexed as a command (#1063).** A file under
+  `skills/**` other than `SKILL.md` that showed `local var="$1"` in a code block was retyped to
+  `commands/skills/<name>/...`. A skill's folder now counts as a declared context, as `memories/` and the other typed
+  directories already did, so the file stays a skill resource (`knowledge/skills/<name>/...`). A `$1` under
+  `commands/` or in a loose file is still a command.
+
+## [0.9.28-alpha.3] - 2026-10-08
+
+### Changed
+
+- A consolidate pair-pass retire proposal now records the judge's claim lists in its `retirement` metadata as `onlyInRetired` and `onlyInSuccessor`, named by role rather than by the judge's A/B, so what the judge found only on each side survives past the run. Proposals minted before this lack both fields; no row is added for a pair akm keeps.
+
+- A distill lesson the quality gate rejects or sends to review now keeps its text: the `distill_invoked` event and the distill result carry `rejectedContent`, cut to 2000 characters (the judge prompt's cap). Before, a rejected lesson left only its score and reason. It stays local in `state.db`.
+
 ## [0.9.28-alpha.2] - 2026-10-08
 
 ### Added

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

@@ -329,8 +329,8 @@ akm bundle list                                      # List all sources
 akm lint                                      # Structural lint over the bundle; exits 0 regardless of findings
 akm lint --fix                                # Auto-fix Tier 1 issues
 akm lint --fail-on-flagged                    # Exit non-zero when summary.flagged > 0 (CI-friendly)
-akm upgrade                                   # Upgrade akm using its install method
-akm upgrade --check                           # Check for updates
+akm upgrade                                   # Upgrade akm using its install method, then update installed harness plugins
+akm upgrade --check                           # Report pending CLI and plugin updates, changing nothing
 akm help migrate 0.6.0                        # Print migration notes for a release (or: latest)
 akm help bundle                               # Print options and subcommands for one command
 akm help agents --full                        # Print this reference

package/dist/commands/improve/consolidate/pair-pass.js

@@ -637,6 +637,9 @@ async function judgeOne(ctx, candidate) {
         cosine: candidate.cosine,
         judgeLabel: verdict.relation,
         judgeReason: verdict.reason,
+        // The judge's A is the older side and B the newer (see orderByAge); record the lists by role.
+        onlyInRetired: retired === older ? verdict.onlyInA : verdict.onlyInB,
+        onlyInSuccessor: retired === older ? verdict.onlyInB : verdict.onlyInA,
         retiredContentHash: retiredHash,
         successorContentHash: successorHash,
         reason,

package/dist/commands/improve/distill.js

@@ -638,6 +638,8 @@ function rejectDistilled(run, proposalRef, content, score, reason, meta) {
         ledgerRef: run.ledgerRef,
     });
 }
+/** Longest lesson text kept on a rejection, the same cap the quality judge's prompt reads (stage.ts). */
+const REJECTED_CONTENT_MAX_CHARS = 2000;
 /**
  * Record a distill quality-gate outcome and return its envelope.
  * `quality_rejected` lands in the improve ledger under the input's key (its
@@ -673,6 +675,8 @@ export function writeQualityRejection(args) {
         }
     }
     const eligMeta = args.eligibilitySource ? { eligibilitySource: args.eligibilitySource } : {};
+    // The text the gate turned away, kept in the local event and the result so a rejection can be audited.
+    const rejectedContent = args.content.slice(0, REJECTED_CONTENT_MAX_CHARS);
     appendEvent({
         eventType: "distill_invoked",
         ref: ledgerRef,
@@ -681,6 +685,7 @@ export function writeQualityRejection(args) {
             proposalRef: args.proposalRef,
             score: args.score,
             reason: args.reason,
+            rejectedContent,
             ...meta,
             ...eligMeta,
         },
@@ -693,6 +698,7 @@ export function writeQualityRejection(args) {
         proposalRef: args.proposalRef,
         score: args.score,
         reason: args.reason,
+        rejectedContent,
         ...(proposal ? { proposalId: proposal.id, proposal } : {}),
         ...meta,
     };

package/dist/commands/sources/plugin-upgrade.js

@@ -0,0 +1,328 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The plugin half of `akm upgrade` (#1007): refresh the akm plugin of each
+ * installed agent harness, and keep the CLI in version lockstep with the
+ * OpenCode plugin. Update only: a plugin that is not installed is never
+ * installed, and a harness without one is skipped. Every external command
+ * runs with a timeout and its failure is captured on that harness's entry,
+ * so a broken harness never aborts the CLI upgrade.
+ */
+import * as childProcess from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { IS_WINDOWS } from "../../core/common.js";
+import { moveToTrash } from "../../core/trash.js";
+import { semverOrder } from "../../runtime.js";
+const MARKETPLACE = "akm-plugins";
+const PLUGIN_ID = `akm@${MARKETPLACE}`;
+const OPENCODE_PACKAGE = "akm-opencode";
+const READ_TIMEOUT_MS = 30_000;
+const REFRESH_TIMEOUT_MS = 120_000;
+const PREFETCH_TIMEOUT_MS = 180_000;
+function runCommand(command, args, timeoutMs, opts) {
+    const result = childProcess.spawnSync(command, args, {
+        encoding: "utf8",
+        env: process.env,
+        stdio: "pipe",
+        timeout: timeoutMs,
+        killSignal: "SIGKILL",
+        cwd: opts?.cwd,
+    });
+    const label = `${command} ${args.join(" ")}`;
+    if (result.error) {
+        const code = result.error.code;
+        if (code === "ETIMEDOUT")
+            return { ok: false, missing: false, error: `\`${label}\` timed out after ${timeoutMs / 1000}s` };
+        return { ok: false, missing: code === "ENOENT", error: `\`${label}\` could not run: ${result.error.message}` };
+    }
+    if (result.status !== 0) {
+        const detail = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
+        return { ok: false, missing: false, error: `\`${label}\` failed: ${detail}` };
+    }
+    return { ok: true, stdout: result.stdout ?? "" };
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function skipped(harness, message) {
+    return { harness, outcome: "skipped", message };
+}
+function failed(harness, message) {
+    return { harness, outcome: "failed", message };
+}
+/** An entry for a refresh that ran: `updated` when the installed version moved, else `current`. */
+function refreshed(harness, from, to) {
+    const moved = from !== undefined && to !== undefined && from !== to;
+    return { harness, outcome: moved ? "updated" : "current", from, to };
+}
+/** Unknown, in `--check`: knowing whether a newer build exists needs a marketplace fetch, which `--check` does not do. */
+function unknownRefresh(harness, from) {
+    return {
+        harness,
+        outcome: "unknown",
+        from,
+        message: "checking needs a fetch of the akm-plugins marketplace, which --check does not do; `akm upgrade` refreshes it",
+    };
+}
+function claudePluginVersion() {
+    const listed = runCommand("claude", ["plugin", "list", "--json"], READ_TIMEOUT_MS);
+    if (!listed.ok)
+        return { error: listed };
+    const plugins = parseJson(listed.stdout);
+    const plugin = Array.isArray(plugins) ? plugins.find((p) => p?.id === PLUGIN_ID) : undefined;
+    return { version: plugin ? String(plugin.version ?? "") : undefined };
+}
+function detectClaudeCode() {
+    const marketplaces = runCommand("claude", ["plugin", "marketplace", "list", "--json"], READ_TIMEOUT_MS);
+    if (!marketplaces.ok) {
+        return { entry: skipped("claude-code", marketplaces.missing ? "claude is not on PATH" : marketplaces.error) };
+    }
+    const list = parseJson(marketplaces.stdout);
+    if (!Array.isArray(list) || !list.some((m) => m?.name === MARKETPLACE)) {
+        return { entry: skipped("claude-code", `the ${MARKETPLACE} marketplace is not configured`) };
+    }
+    const plugin = claudePluginVersion();
+    if ("error" in plugin)
+        return { entry: skipped("claude-code", plugin.error.error) };
+    if (plugin.version === undefined)
+        return { entry: skipped("claude-code", "the akm plugin is not installed") };
+    return { version: plugin.version };
+}
+function upgradeClaudeCode(dryRun) {
+    const detected = detectClaudeCode();
+    if ("entry" in detected)
+        return detected.entry;
+    if (dryRun)
+        return unknownRefresh("claude-code", detected.version);
+    const marketplace = runCommand("claude", ["plugin", "marketplace", "update", MARKETPLACE], REFRESH_TIMEOUT_MS);
+    if (!marketplace.ok)
+        return failed("claude-code", marketplace.error);
+    const update = runCommand("claude", ["plugin", "update", PLUGIN_ID], REFRESH_TIMEOUT_MS);
+    if (!update.ok)
+        return failed("claude-code", update.error);
+    const after = claudePluginVersion();
+    return refreshed("claude-code", detected.version, "version" in after ? after.version : undefined);
+}
+// ── Codex ───────────────────────────────────────────────────────────────────
+function codexPluginVersion() {
+    const listed = runCommand("codex", ["plugin", "list", "--marketplace", MARKETPLACE, "--json"], READ_TIMEOUT_MS);
+    if (!listed.ok)
+        return { error: listed };
+    const parsed = parseJson(listed.stdout);
+    const plugin = parsed?.installed?.find((p) => p?.pluginId === PLUGIN_ID);
+    return { version: plugin ? String(plugin.version ?? "") : undefined };
+}
+function upgradeCodex(dryRun) {
+    const before = codexPluginVersion();
+    if ("error" in before)
+        return skipped("codex", before.error.missing ? "codex is not on PATH" : before.error.error);
+    if (before.version === undefined) {
+        return skipped("codex", `the akm plugin is not installed from the ${MARKETPLACE} marketplace`);
+    }
+    if (dryRun)
+        return unknownRefresh("codex", before.version);
+    // Also refreshes the installed plugin's cache, so no re-add is needed.
+    const upgrade = runCommand("codex", ["plugin", "marketplace", "upgrade", MARKETPLACE], REFRESH_TIMEOUT_MS);
+    if (!upgrade.ok)
+        return failed("codex", upgrade.error);
+    const after = codexPluginVersion();
+    return refreshed("codex", before.version, "version" in after ? after.version : undefined);
+}
+/** The cached `akm-opencode` OpenCode installed on first use, or undefined when there is none. */
+export function detectOpenCodeCache() {
+    const cacheHome = process.env.XDG_CACHE_HOME?.trim() ||
+        path.join(process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || os.homedir(), ".cache");
+    const dir = path.join(cacheHome, "opencode", "packages", `${OPENCODE_PACKAGE}@latest`);
+    if (!fs.existsSync(dir))
+        return undefined;
+    const readVersion = (file) => {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(file, "utf8"));
+            return typeof pkg.version === "string" ? pkg.version : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return { dir, version: readVersion(path.join(dir, "node_modules", OPENCODE_PACKAGE, "package.json")) };
+}
+/** What npm's `akm-opencode@latest` is, and which akm-cli it pins. */
+export function lookupOpenCodeLatest() {
+    const view = runCommand(IS_WINDOWS ? "npm.cmd" : "npm", ["view", `${OPENCODE_PACKAGE}@latest`, "version", "dependencies.akm-cli", "--json"], READ_TIMEOUT_MS);
+    if (!view.ok)
+        return { error: view.error };
+    const parsed = parseJson(view.stdout);
+    if (typeof parsed?.version !== "string")
+        return { error: "npm did not report a version for akm-opencode@latest" };
+    const akmCli = parsed["dependencies.akm-cli"];
+    return { version: parsed.version, akmCli: typeof akmCli === "string" ? akmCli : undefined };
+}
+/** Whether an OpenCode process is running (its prefetch would be replaced under it). `undefined` when that cannot be told. */
+function openCodeRunning() {
+    if (IS_WINDOWS) {
+        const tasks = runCommand("tasklist", ["/FI", "IMAGENAME eq opencode.exe", "/NH"], READ_TIMEOUT_MS);
+        return tasks.ok ? /opencode\.exe/i.test(tasks.stdout) : undefined;
+    }
+    // `-f` because a Node-wrapped opencode shows up as `node …/opencode`; the
+    // pattern needs `opencode` to be a whole path segment so `akm-opencode`
+    // in some other command's arguments does not match.
+    const pgrep = runCommand("pgrep", ["-f", "(^|/)opencode( |$)"], READ_TIMEOUT_MS);
+    if (pgrep.ok)
+        return true;
+    if (!pgrep.missing)
+        return false; // pgrep exits 1 when nothing matched
+    if (process.platform !== "linux")
+        return undefined;
+    try {
+        return fs.readdirSync("/proc").some((pid) => {
+            if (!/^\d+$/.test(pid) || Number(pid) === process.pid)
+                return false;
+            try {
+                const argv = fs.readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0");
+                return argv.slice(0, 2).some((arg) => path.basename(arg) === "opencode");
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function upgradeOpenCode(dryRun, cache, latest) {
+    if (!cache || !latest)
+        return skipped("opencode", "no cached akm-opencode plugin");
+    if ("error" in latest)
+        return failed("opencode", latest.error);
+    if (cache.version === latest.version)
+        return { harness: "opencode", outcome: "current", from: cache.version, to: latest.version };
+    const base = { harness: "opencode", from: cache.version, to: latest.version };
+    const running = openCodeRunning();
+    if (running !== false) {
+        return {
+            ...base,
+            outcome: "deferred",
+            message: running === true
+                ? "OpenCode is running; the plugin cache is replaced by a later `akm upgrade` once it has exited"
+                : "could not tell whether OpenCode is running; the plugin cache is replaced by a later `akm upgrade`",
+        };
+    }
+    if (dryRun)
+        return { ...base, outcome: "pending" };
+    // OpenCode must be runnable before the cache goes: it does the prefetch.
+    const probe = runCommand("opencode", ["--version"], READ_TIMEOUT_MS);
+    if (!probe.ok)
+        return skipped("opencode", probe.missing ? "opencode is not on PATH" : probe.error);
+    try {
+        moveToTrash(cache.dir);
+    }
+    catch (error) {
+        return failed("opencode", `could not move ${cache.dir} to the trash: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Any OpenCode command that resolves the config installs the plugin again;
+    // from a temp dir, so no project's opencode.json is read.
+    const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-opencode-prefetch-"));
+    try {
+        const prefetch = runCommand("opencode", ["debug", "config"], PREFETCH_TIMEOUT_MS, { cwd: workDir });
+        if (!prefetch.ok)
+            return failed("opencode", `${prefetch.error} (the old cache is in the trash)`);
+    }
+    finally {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    }
+    const after = detectOpenCodeCache();
+    if (!after)
+        return failed("opencode", "opencode did not re-create the plugin cache (the old cache is in the trash)");
+    return { ...base, outcome: "updated", to: after.version ?? latest.version };
+}
+// ── Orchestration ───────────────────────────────────────────────────────────
+export function upgradePlugins(opts) {
+    return [
+        upgradeClaudeCode(opts.dryRun),
+        upgradeCodex(opts.dryRun),
+        upgradeOpenCode(opts.dryRun, opts.openCode.cache, opts.openCode.latest),
+    ];
+}
+/**
+ * When the OpenCode plugin is present the CLI target is the akm-cli that
+ * `akm-opencode@latest` pins, not the newest release: the plugin runs that
+ * exact akm in-process, against databases a newer CLI may already have
+ * migrated. The CLI never moves backwards to meet the pin.
+ *
+ * It fails closed: when the plugin is present but its pin cannot be read (the
+ * npm lookup failed, or the package declares no akm-cli), the CLI is held where
+ * it is (`updateAvailable: false`, `latestVersion` = the current version) and
+ * `lockstep.reason` says why. Moving the CLI ahead of a pin nobody could read is
+ * what lockstep exists to prevent; the OpenCode entry reports the failure.
+ */
+export function applyLockstep(check, latest) {
+    if (!latest)
+        return check;
+    // Held back only when there is a release this upgrade would otherwise install.
+    const wouldInstall = semverOrder(check.currentVersion, check.latestVersion) < 0;
+    const pinned = "error" in latest ? undefined : latest.akmCli;
+    if (!pinned) {
+        const reason = "error" in latest
+            ? `could not read the akm-cli pin of ${OPENCODE_PACKAGE}@latest: ${latest.error}`
+            : `${OPENCODE_PACKAGE}@latest declares no akm-cli dependency`;
+        return {
+            ...check,
+            latestVersion: check.currentVersion,
+            updateAvailable: false,
+            lockstep: {
+                plugin: OPENCODE_PACKAGE,
+                pinnedVersion: null,
+                newestVersion: check.latestVersion,
+                heldBack: wouldInstall,
+                reason,
+            },
+        };
+    }
+    const heldBack = semverOrder(pinned, check.latestVersion) < 0 && wouldInstall;
+    const lockstep = {
+        plugin: OPENCODE_PACKAGE,
+        pinnedVersion: pinned,
+        newestVersion: check.latestVersion,
+        heldBack,
+    };
+    if (!heldBack)
+        return { ...check, lockstep };
+    return {
+        ...check,
+        latestVersion: pinned,
+        updateAvailable: semverOrder(check.currentVersion, pinned) < 0,
+        lockstep,
+    };
+}
+/** `akm upgrade`: the CLI step (held to the OpenCode plugin's akm), then the plugins. */
+export async function runUpgrade(args, currentVersion, deps) {
+    const cache = detectOpenCodeCache();
+    const latest = cache ? lookupOpenCodeLatest() : undefined;
+    const check = applyLockstep(await deps.checkForUpdate(currentVersion), latest);
+    const openCode = { cache, latest };
+    if (args.check) {
+        return { mode: "check", result: { ...check, plugins: upgradePlugins({ dryRun: true, openCode }) } };
+    }
+    const upgraded = await deps.performUpgrade(check, {
+        force: args.force,
+        skipPostUpgrade: args.skipPostUpgrade,
+        // A package manager install must name the version, or `@latest` goes past the pin.
+        ...(check.lockstep?.heldBack ? { targetVersion: check.latestVersion } : {}),
+    });
+    const plugins = upgradePlugins({ dryRun: false, openCode });
+    const result = { ...upgraded, ...(check.lockstep ? { lockstep: check.lockstep } : {}), plugins };
+    // The install may have succeeded, but an upgrade whose migration is
+    // blocked or could not run is not done, and neither is one whose plugin
+    // step failed.
+    const migrationFailed = upgraded.migration?.status === "blocked" || upgraded.migration?.status === "failed";
+    return { mode: "upgrade", result, failed: migrationFailed || plugins.some((p) => p.outcome === "failed") };
+}

package/dist/commands/sources/self-update.js

@@ -237,7 +237,7 @@ export async function performUpgrade(check, opts, dependencies) {
             migration: await runMigrationStep(runTool),
         };
     }
-    const packageManagerCommand = getPackageManagerUpgradeCommand(installMethod);
+    const packageManagerCommand = getPackageManagerUpgradeCommand(installMethod, undefined, opts?.targetVersion);
     if (packageManagerCommand) {
         return runPackageManagerUpgrade({
             packageManagerCommand,
@@ -574,8 +574,8 @@ function resolveNodePackageManagerCommand(name) {
     const adjacent = path.join(path.dirname(process.execPath), `${name}${extension}`);
     return fs.existsSync(adjacent) ? adjacent : name;
 }
-export function getPackageManagerUpgradeCommand(installMethod, packageName = getInstalledPackageName()) {
-    const pkgRef = `${packageName}@latest`;
+export function getPackageManagerUpgradeCommand(installMethod, packageName = getInstalledPackageName(), version = "latest") {
+    const pkgRef = `${packageName}@${version}`;
     if (installMethod === "bun") {
         return {
             command: "bun",

package/dist/commands/sources/sources-cli.js

@@ -33,12 +33,21 @@ import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
 import { pkgVersion } from "../../version.js";
+import { runUpgrade } from "./plugin-upgrade.js";
 import { checkForUpdate, performUpgrade } from "./self-update.js";
 import { akmClone } from "./source-clone.js";
 export const upgradeCommand = defineJsonCommand({
-    meta: { name: "upgrade", description: "Upgrade akm to the latest release" },
+    meta: {
+        name: "upgrade",
+        description: "Upgrade akm to the latest release, then update the akm plugin of each installed harness " +
+            "(Claude Code, Codex, OpenCode). With the OpenCode plugin installed, akm moves to the version that plugin pins.",
+    },
     args: {
-        check: { type: "boolean", description: "Check for updates without installing", default: false },
+        check: {
+            type: "boolean",
+            description: "Report pending updates, CLI and per-harness plugins, without changing anything",
+            default: false,
+        },
         force: { type: "boolean", description: "Force upgrade even if on latest", default: false },
         "skip-post-upgrade": {
             type: "boolean",
@@ -47,17 +56,12 @@ export const upgradeCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
-        const check = await checkForUpdate(pkgVersion);
-        if (args.check) {
-            output("upgrade", check);
+        const run = await runUpgrade({ check: args.check, force: args.force, skipPostUpgrade: args["skip-post-upgrade"] }, pkgVersion, { checkForUpdate, performUpgrade: (check, opts) => performUpgrade(check, opts) });
+        if (run.mode === "check") {
+            output("upgrade", run.result);
             return;
         }
-        const skipPostUpgrade = args["skip-post-upgrade"];
-        const result = await performUpgrade(check, { force: args.force, skipPostUpgrade });
-        // The install may have succeeded, but an upgrade whose migration is
-        // blocked or could not run is not done: exit like `akm migrate apply` does.
-        const migrationFailed = result.migration?.status === "blocked" || result.migration?.status === "failed";
-        outputWithExitCode("upgrade", result, migrationFailed ? EXIT_CODES.GENERAL : undefined);
+        outputWithExitCode("upgrade", run.result, run.failed ? EXIT_CODES.GENERAL : undefined);
     },
 });
 // `sync` body, standalone so the git-commit/push logic stays in one place.

package/dist/core/trash.js

@@ -0,0 +1,73 @@
+// 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 * as childProcess from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const TRASH_TOOL_TIMEOUT_MS = 30_000;
+function homeDir() {
+    return process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || os.homedir();
+}
+/** `[command, ...args]` trash tools tried in order on Linux; the target path is appended. */
+const LINUX_TRASH_TOOLS = [["trash-put"], ["gio", "trash"]];
+/**
+ * FreeDesktop trash without a helper tool: move `target` into
+ * `$XDG_DATA_HOME/Trash/files` and write the `.trashinfo` that lets a file
+ * manager restore it. A plain rename, so it fails (rather than copying) when
+ * the trash is on another filesystem.
+ */
+function moveToXdgTrash(target) {
+    const dataHome = process.env.XDG_DATA_HOME?.trim() || path.join(homeDir(), ".local", "share");
+    const filesDir = path.join(dataHome, "Trash", "files");
+    const infoDir = path.join(dataHome, "Trash", "info");
+    fs.mkdirSync(filesDir, { recursive: true });
+    fs.mkdirSync(infoDir, { recursive: true });
+    const base = path.basename(target);
+    let name = base;
+    for (let n = 1; fs.existsSync(path.join(filesDir, name)) || fs.existsSync(path.join(infoDir, `${name}.trashinfo`)); n++) {
+        name = `${base}.${n}`;
+    }
+    const deletedAt = new Date().toISOString().slice(0, 19);
+    fs.writeFileSync(path.join(infoDir, `${name}.trashinfo`), `[Trash Info]\nPath=${encodeURI(path.resolve(target))}\nDeletionDate=${deletedAt}\n`);
+    try {
+        fs.renameSync(target, path.join(filesDir, name));
+    }
+    catch (error) {
+        fs.unlinkSync(path.join(infoDir, `${name}.trashinfo`));
+        throw error;
+    }
+}
+/**
+ * Move `target` to the operating system's trash. Never deletes permanently:
+ * when no trash is available the target is left where it is and this throws.
+ * Linux tries `trash-put`, then `gio trash`, then the FreeDesktop trash
+ * directory; macOS moves into `~/.Trash`; Windows has no supported trash here.
+ */
+export function moveToTrash(target, tools = LINUX_TRASH_TOOLS) {
+    if (!fs.existsSync(target))
+        return;
+    if (process.platform === "win32") {
+        throw new Error("moving to the Recycle Bin is not supported on Windows; the directory was left in place");
+    }
+    if (process.platform === "darwin") {
+        const trashDir = path.join(homeDir(), ".Trash");
+        fs.mkdirSync(trashDir, { recursive: true });
+        fs.renameSync(target, path.join(trashDir, `${path.basename(target)}.${Date.now()}`));
+        return;
+    }
+    for (const [command, ...args] of tools) {
+        const result = childProcess.spawnSync(command, [...args, target], {
+            // The live environment, as the harness commands get it: Bun's default is the env the process started with.
+            env: process.env,
+            encoding: "utf8",
+            stdio: "pipe",
+            timeout: TRASH_TOOL_TIMEOUT_MS,
+        });
+        if (!result.error && result.status === 0 && !fs.existsSync(target))
+            return;
+        // A tool that is missing falls through to the next; one that ran and
+        // failed does too, because the target is still in place.
+    }
+    moveToXdgTrash(target);
+}

package/dist/indexer/walk/matchers.js

@@ -159,11 +159,12 @@ function matchDirectoryHint(dirName, ctx, specificity) {
  * True when some ancestor directory already DECLARES this file's type via
  * `DIR_TYPE_MAP` — the same walk `classifyByDirectory` performs. Derived from
  * path fields alone, so `smartMdPathCandidates` can apply it without reading
- * bytes.
+ * bytes. A skill's folder is a declared context too: a file in it is a skill
+ * resource, so a shell `$1` in one of its snippets must not retype it (#1063).
  */
 function hasDeclaredDirType(ctx) {
     if (isNestedSkillResource(ctx))
-        return false;
+        return true;
     return ctx.ancestorDirs.some((dir) => matchDirectoryHint(dir, ctx, 0) !== null);
 }
 function classifyByExtension(ctx) {

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

@@ -662,7 +662,33 @@ export function formatUpdatePlain(r) {
     }
     return lines.length > 0 ? lines.join("\n") : `update: nothing to update`;
 }
+const HARNESS_LABELS = { "claude-code": "Claude Code", codex: "Codex", opencode: "OpenCode" };
+/** The plugin lines worth printing: nothing for a plugin that is current or has no plugin to update. */
+function formatUpgradePluginLines(r) {
+    const lines = [];
+    const lockstep = r.lockstep;
+    if (lockstep?.heldBack) {
+        lines.push(lockstep.pinnedVersion
+            ? `akm is held at v${lockstep.pinnedVersion} (v${lockstep.newestVersion} is out): the OpenCode plugin pins that version`
+            : `akm is not upgraded to v${lockstep.newestVersion}: ${lockstep.reason}`);
+    }
+    const plugins = Array.isArray(r.plugins) ? r.plugins : [];
+    for (const p of plugins) {
+        if (p.outcome === "current" || p.outcome === "skipped")
+            continue;
+        const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} → v${p.to}` : "";
+        const note = p.message ? ` (${p.message})` : "";
+        lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${note}`);
+    }
+    return lines;
+}
 export function formatUpgradePlain(r) {
+    const lines = formatUpgradePluginLines(r);
+    const head = formatUpgradeHead(r);
+    const all = head === null ? lines : [head, ...lines];
+    return all.length > 0 ? all.join("\n") : null;
+}
+function formatUpgradeHead(r) {
     if (r.upgraded === true) {
         return `akm upgraded: v${r.currentVersion} → v${r.newVersion}`;
     }

package/dist/scripts/akm-migrate-node.js

@@ -30464,7 +30464,31 @@ function formatUpdatePlain(r) {
   return lines.length > 0 ? lines.join(`
 `) : `update: nothing to update`;
 }
+var HARNESS_LABELS = { "claude-code": "Claude Code", codex: "Codex", opencode: "OpenCode" };
+function formatUpgradePluginLines(r) {
+  const lines = [];
+  const lockstep = r.lockstep;
+  if (lockstep?.heldBack) {
+    lines.push(lockstep.pinnedVersion ? `akm is held at v${lockstep.pinnedVersion} (v${lockstep.newestVersion} is out): the OpenCode plugin pins that version` : `akm is not upgraded to v${lockstep.newestVersion}: ${lockstep.reason}`);
+  }
+  const plugins = Array.isArray(r.plugins) ? r.plugins : [];
+  for (const p of plugins) {
+    if (p.outcome === "current" || p.outcome === "skipped")
+      continue;
+    const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} → v${p.to}` : "";
+    const note = p.message ? ` (${p.message})` : "";
+    lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${note}`);
+  }
+  return lines;
+}
 function formatUpgradePlain(r) {
+  const lines = formatUpgradePluginLines(r);
+  const head = formatUpgradeHead(r);
+  const all = head === null ? lines : [head, ...lines];
+  return all.length > 0 ? all.join(`
+`) : null;
+}
+function formatUpgradeHead(r) {
   if (r.upgraded === true) {
     return `akm upgraded: v${r.currentVersion} → v${r.newVersion}`;
   }
@@ -40449,7 +40473,7 @@ function matchDirectoryHint(dirName, ctx, specificity) {
 }
 function hasDeclaredDirType(ctx) {
   if (isNestedSkillResource(ctx))
-    return false;
+    return true;
   return ctx.ancestorDirs.some((dir) => matchDirectoryHint(dir, ctx, 0) !== null);
 }
 function classifyByExtension(ctx) {

package/dist/scripts/akm-migrate.js

@@ -29792,7 +29792,31 @@ function formatUpdatePlain(r) {
   return lines.length > 0 ? lines.join(`
 `) : `update: nothing to update`;
 }
+var HARNESS_LABELS = { "claude-code": "Claude Code", codex: "Codex", opencode: "OpenCode" };
+function formatUpgradePluginLines(r) {
+  const lines = [];
+  const lockstep = r.lockstep;
+  if (lockstep?.heldBack) {
+    lines.push(lockstep.pinnedVersion ? `akm is held at v${lockstep.pinnedVersion} (v${lockstep.newestVersion} is out): the OpenCode plugin pins that version` : `akm is not upgraded to v${lockstep.newestVersion}: ${lockstep.reason}`);
+  }
+  const plugins = Array.isArray(r.plugins) ? r.plugins : [];
+  for (const p of plugins) {
+    if (p.outcome === "current" || p.outcome === "skipped")
+      continue;
+    const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} \u2192 v${p.to}` : "";
+    const note = p.message ? ` (${p.message})` : "";
+    lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${note}`);
+  }
+  return lines;
+}
 function formatUpgradePlain(r) {
+  const lines = formatUpgradePluginLines(r);
+  const head = formatUpgradeHead(r);
+  const all = head === null ? lines : [head, ...lines];
+  return all.length > 0 ? all.join(`
+`) : null;
+}
+function formatUpgradeHead(r) {
   if (r.upgraded === true) {
     return `akm upgraded: v${r.currentVersion} \u2192 v${r.newVersion}`;
   }
@@ -39777,7 +39801,7 @@ function matchDirectoryHint(dirName, ctx, specificity) {
 }
 function hasDeclaredDirType(ctx) {
   if (isNestedSkillResource(ctx))
-    return false;
+    return true;
   return ctx.ancestorDirs.some((dir) => matchDirectoryHint(dir, ctx, 0) !== null);
 }
 function classifyByExtension(ctx) {

package/docs/integration/bundling-akm.md

@@ -186,8 +186,13 @@ migration didn't finish is not done. This makes plain `akm upgrade` (no
 flags) a safe, idempotent container entrypoint step on every boot: on an
 already-current install with nothing pending it is a fast no-op that exits 0.
 
+After the install step it also updates the akm plugin of each agent harness
+present in the image (Claude Code, Codex, OpenCode), reported under `plugins`;
+see [`akm upgrade`](../reference/cli.md#upgrade) for the rules, the OpenCode
+version lockstep and the Codex hook-trust entries a headless image needs.
+
 **`--check`** skips the migration step entirely — it only compares versions
-and reports `updateAvailable`. Use it for a version-drift alert, not as your
+and reports `updateAvailable` (plus the pending per-harness plugin updates). Use it for a version-drift alert, not as your
 boot check.
 
 ## `akm health`

package/docs/reference/cli.md

@@ -1336,20 +1336,96 @@ computed, with a 256 MiB binary limit. Release/checksum metadata is capped at
 1 MiB; an oversized response is cancelled and the staged file is removed.
 
 ```sh
-akm upgrade              # Install a newer release if there is one, then run every pending migration
-akm upgrade --check      # Check for updates without installing (no migration step)
+akm upgrade              # Install a newer release if there is one, run every pending migration, then update the harness plugins
+akm upgrade --check      # Report pending updates, CLI and plugins, without changing anything (no migration step)
 akm upgrade --force      # Force the install even if already on latest
 ```
 
 | Flag | Description |
 | --- | --- |
-| `--check` | Check for updates without installing |
+| `--check` | Report pending updates (CLI and per-harness plugins) without changing anything |
 | `--force` | Force upgrade even if on latest version |
 | `--skip-post-upgrade` | Skip the post-upgrade index rebuild |
 
 Offline, or to migrate without a release check, run `akm migrate apply`
 directly: it is the same step.
 
+#### Harness plugins
+
+After the CLI step, `akm upgrade` updates the akm plugin of each agent harness
+it finds. It only updates: a plugin that is not installed is never installed,
+and a harness without the akm plugin is skipped. Each external command runs
+with a timeout, and a failure is recorded on that harness's entry without
+stopping the CLI upgrade.
+
+| Harness | Updated when | What runs |
+| --- | --- | --- |
+| Claude Code | `claude` is on `PATH`, the `akm-plugins` marketplace is configured and `akm@akm-plugins` is installed | `claude plugin marketplace update akm-plugins`, then `claude plugin update akm@akm-plugins` |
+| Codex | `codex` is on `PATH` and `akm@akm-plugins` is installed from the `akm-plugins` marketplace | `codex plugin marketplace upgrade akm-plugins` (this also refreshes the installed plugin cache) |
+| OpenCode | `akm-opencode` is cached at `$XDG_CACHE_HOME/opencode/packages/akm-opencode@latest` (default `~/.cache/opencode/...`) and `opencode` is on `PATH` | If npm's `akm-opencode@latest` differs from the cached version and no OpenCode process is running: the cache directory is moved to the trash (never deleted), then `opencode debug config` is run from a temporary directory to fetch the new version. While OpenCode runs the update is `deferred` to a later `akm upgrade`. |
+
+Claude Code does not update third-party marketplaces on its own (the Claude
+desktop app turns plugin updates off), and OpenCode never re-checks a cached
+plugin, so neither moves without this step. Codex refreshes its git
+marketplaces at every start.
+
+The result gains a `plugins` array, one entry per harness:
+`{ "harness": "claude-code" | "codex" | "opencode", "outcome": ..., "from"?, "to"?, "message"? }`.
+`outcome` is `updated`, `current`, `skipped`, `deferred` or `failed`; under
+`--check` it can also be `pending` or `unknown`. `--check` does not fetch the
+Claude Code or Codex marketplaces, so for them it reports `unknown` (whether a
+newer build exists needs a fetch it does not do) rather than guessing; for
+OpenCode it compares the cached version with npm, so it reports `pending` when
+an update is due. A `failed` plugin makes `akm upgrade` exit `1` (not
+`--check`). On an up-to-date machine the text output prints nothing for
+plugins.
+
+**Version lockstep.** The OpenCode plugin runs its own exact-pinned akm-cli
+in-process, so a CLI newer than the plugin's pin would run the plugin against
+databases it did not migrate. When the OpenCode plugin is present, the CLI
+target is the akm-cli that `akm-opencode@latest` depends on
+(`npm view akm-opencode@latest dependencies.akm-cli`), not the newest release.
+The result then carries `lockstep: { plugin, pinnedVersion, newestVersion, heldBack }`,
+`latestVersion` is the pinned version, the install names that exact version
+rather than `@latest`, and the text output says the CLI is held back. The CLI
+is never moved backwards to meet the pin. Claude Code and Codex have no
+in-process copy and are not part of this rule.
+
+Lockstep fails closed. When the OpenCode plugin is cached but the pin cannot
+be read (the npm lookup failed, or `akm-opencode@latest` declares no
+`akm-cli`), the CLI is not upgraded: `updateAvailable` is `false`,
+`latestVersion` is the current version, and `lockstep` is
+`{ plugin, pinnedVersion: null, newestVersion, heldBack: true, reason }`. The
+OpenCode entry is `failed` and the run exits `1`; the next `akm upgrade`
+retries.
+
+#### Containers
+
+With the plugin step, a container entrypoint needs only:
+
+```sh
+akm upgrade -q || true
+( while sleep 86400; do akm upgrade -q; done ) &   # long-running containers only
+exec "$@"
+```
+
+Codex hooks need one-time trust, and nobody can open `/hooks` in a container.
+Bake the trust entries into the image's `~/.codex/config.toml`, one per hook the
+plugin declares (today `session_start` and `user_prompt_submit`):
+
+```toml
+[hooks.state."akm@akm-plugins:plugin.json#hooks[0]:session_start:0:0"]
+trusted_hash = "sha256:<hash>"
+
+[hooks.state."akm@akm-plugins:plugin.json#hooks[0]:user_prompt_submit:0:0"]
+trusted_hash = "sha256:<hash>"
+```
+
+Copy the two `trusted_hash` values from a machine where you have trusted the
+hooks in `/hooks` (they are in that machine's `~/.codex/config.toml`). The
+hashes stay the same across plugin version bumps and change only when a hook's
+command changes, so an upgraded plugin keeps running without a prompt.
+
 Checksum verification is not optional and has no flag. If a release's
 `checksums.txt` is genuinely unreachable, the recovery hatch is the
 `AKM_UPGRADE_SKIP_CHECKSUM=1` environment variable (Internal — deliberately

package/docs/reference/data-and-telemetry.md

@@ -196,7 +196,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `reflect_completed` | Reflect phase produced a proposal | `ref` |
 | `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
 | `propose_invoked` | `akm proposal new` | `ref` |
-| `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome (`queued`, `skipped` with a `skipReason` such as `lesson_exists`, `nothing_reusable` or `conflict_noop`, `llm_failed`, `validation_failed`, `quality_rejected`, `review_needed`) |
+| `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome (`queued`, `skipped` with a `skipReason` such as `lesson_exists`, `nothing_reusable` or `conflict_noop`, `llm_failed`, `validation_failed`, `quality_rejected`, `review_needed`). A `quality_rejected` or `review_needed` event also carries `score`, `reason`, the judge's per-criterion `criteria` when it ran, and `rejectedContent`, the turned-away lesson text cut to 2000 characters (the judge prompt's cap), kept locally in `state.db` |
 | `extract_invoked` | `akm proposal extract --type <harness>` / `--auto`, or improve-stage session extraction | `outcome`, `sessionId`, `harness` |
 | `extract_triaged` | The pre-LLM extract triage gate evaluated at least one session | `evaluated`, `passed`, `triagedOut`, `sourceRun` (aggregated) |
 | `schema_repair_invoked` | The schema-repair pass inside `akm improve` (`runSchemaRepairPass`) attempts to patch missing frontmatter on an asset that failed schema validation. **There is no `akm lint --repair` flag** — `lint` has `--fix`/`--auto-fix`, unrelated to this event | `ref`, outcome |
@@ -313,6 +313,7 @@ Contents:
 - Source (which process generated it — e.g. `reflect`, `distill`)
 - Full proposal content (Markdown text)
 - Created/updated timestamps
+- For a `consolidate-pair` retire proposal, the pair judge's verdict in its `retirement` metadata: label, reason, cosine, and the claims only the retired side holds (`onlyInRetired`) and only the kept side holds (`onlyInSuccessor`), each at most 20 entries of 200 characters
 
 Beside it, the `improve_ledger` table records what each improve stage last did
 with each asset — one row per bundle, asset ref and stage: the outcome

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.28-alpha.2",
+  "version": "0.9.28-alpha.4",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [