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

package/CHANGELOG.md

@@ -6,6 +6,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.28-alpha.5] - 2026-10-08
+
+### Added
+
+- **`akm upgrade --next` installs the `@next` prerelease of akm and its OpenCode plugin.** The CLI target is
+  the `next` dist-tag of `akm-cli` when it is newer than the latest stable release, else the stable release
+  (never a downgrade); npm/Bun/pnpm installs name that exact version and binary installs take its GitHub
+  release. The OpenCode lockstep and cache refresh follow `akm-opencode@next` when the OpenCode config's
+  `plugin` list names it (akm never edits that config); with a bare `"akm-opencode"` the entry is `skipped`
+  with a message saying to set `"plugin": ["akm-opencode@next"]`, and lockstep stays on the `@latest` pin.
+  Missing, older-than-`@latest` or unpinned `@next` fails closed like the stable lockstep. Claude Code and
+  Codex are unchanged (no prerelease channel). The result gains `channel`. Works with `--check`, `--force`
+  and `-q`. See [`akm upgrade`](docs/reference/cli.md#prereleases-next).
+
+## [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

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

@@ -329,8 +329,9 @@ 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 upgrade --next                            # Follow prereleases (@next); OpenCode needs "akm-opencode@next" in its plugin list
 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/sources/plugin-upgrade.js

@@ -0,0 +1,413 @@
+// 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, stripJsonComments } 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 OPENCODE_NEXT_SPEC = `${OPENCODE_PACKAGE}@next`;
+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);
+}
+function homeDir() {
+    return process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || os.homedir();
+}
+/**
+ * Whether the user's global OpenCode config asks for `akm-opencode@next`.
+ * A bare `akm-opencode` resolves to `@latest` when OpenCode prefetches it, so
+ * only a config that names the tag can follow prereleases. The config is only
+ * read, never written; project configs are not looked at (akm does not know
+ * which project OpenCode runs in).
+ */
+export function openCodeConfigRequestsNext() {
+    const configHome = process.env.XDG_CONFIG_HOME?.trim() || path.join(homeDir(), ".config");
+    const files = [
+        process.env.OPENCODE_CONFIG?.trim(),
+        path.join(configHome, "opencode", "opencode.json"),
+        path.join(configHome, "opencode", "opencode.jsonc"),
+    ];
+    for (const file of files) {
+        if (!file)
+            continue;
+        try {
+            const config = JSON.parse(stripJsonComments(fs.readFileSync(file, "utf8")));
+            if (!Array.isArray(config.plugin))
+                continue;
+            // An entry is a spec string or a `[spec, options]` pair.
+            if (config.plugin.some((entry) => (Array.isArray(entry) ? entry[0] : entry) === OPENCODE_NEXT_SPEC))
+                return true;
+        }
+        catch {
+            // Missing or unparseable: this file does not request it.
+        }
+    }
+    return false;
+}
+/**
+ * The cached `akm-opencode` OpenCode installed on first use, or undefined when
+ * there is none. OpenCode names the folder after the spec it resolved, so a
+ * bare `akm-opencode` lands in `@latest` and `akm-opencode@next` in `@next`.
+ */
+export function detectOpenCodeCache(tag = "latest") {
+    const cacheHome = process.env.XDG_CACHE_HOME?.trim() || path.join(homeDir(), ".cache");
+    const dir = path.join(cacheHome, "opencode", "packages", `${OPENCODE_PACKAGE}@${tag}`);
+    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@<tag>` is, and which akm-cli it pins. */
+export function lookupOpenCodeLatest(tag = "latest") {
+    const spec = `${OPENCODE_PACKAGE}@${tag}`;
+    const view = runCommand(IS_WINDOWS ? "npm.cmd" : "npm", ["view", spec, "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 ${spec}` };
+    const akmCli = parsed["dependencies.akm-cli"];
+    return { version: parsed.version, akmCli: typeof akmCli === "string" ? akmCli : undefined };
+}
+/** `akm-opencode@next`, which must exist and be no older than `@latest`: a prerelease channel that trails the stable one is not a target. */
+export function lookupOpenCodeNext() {
+    const next = lookupOpenCodeLatest("next");
+    if ("error" in next)
+        return next;
+    const latest = lookupOpenCodeLatest("latest");
+    if ("error" in latest)
+        return { error: `could not compare with ${OPENCODE_PACKAGE}@latest: ${latest.error}` };
+    if (semverOrder(next.version, latest.version) < 0) {
+        return {
+            error: `${OPENCODE_NEXT_SPEC} (${next.version}) is older than ${OPENCODE_PACKAGE}@latest (${latest.version})`,
+        };
+    }
+    return next;
+}
+/** 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;
+    }
+}
+const NOT_FOLLOWING_NEXT = `--next: OpenCode resolves a bare "${OPENCODE_PACKAGE}" to @latest, so it is not updated to a prerelease; ` +
+    `set "plugin": ["${OPENCODE_NEXT_SPEC}"] in your OpenCode config to follow prereleases`;
+function upgradeOpenCode(dryRun, cache, latest, tag, notFollowingNext) {
+    if (!cache || !latest)
+        return skipped("opencode", `no cached ${OPENCODE_PACKAGE}@${tag} plugin`);
+    if ("error" in latest)
+        return failed("opencode", latest.error);
+    if (notFollowingNext)
+        return skipped("opencode", NOT_FOLLOWING_NEXT);
+    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(tag);
+    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 ───────────────────────────────────────────────────────────
+const NO_PRERELEASE_CHANNEL = "--next: no prerelease channel; the akm-plugins marketplace is followed as usual and works with any 0.9.x akm";
+/** The note `--next` adds to a harness whose plugin has no prerelease channel. */
+function withNextNote(entry) {
+    if (entry.outcome === "skipped")
+        return entry;
+    return { ...entry, message: entry.message ? `${entry.message}; ${NO_PRERELEASE_CHANNEL}` : NO_PRERELEASE_CHANNEL };
+}
+export function upgradePlugins(opts) {
+    const { cache, latest, tag, notFollowingNext } = opts.openCode;
+    const claude = upgradeClaudeCode(opts.dryRun);
+    const codex = upgradeCodex(opts.dryRun);
+    return [
+        opts.next ? withNextNote(claude) : claude,
+        opts.next ? withNextNote(codex) : codex,
+        upgradeOpenCode(opts.dryRun, cache, latest, tag, notFollowingNext),
+    ];
+}
+/**
+ * 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, tag = "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}@${tag}: ${latest.error}`
+            : `${OPENCODE_PACKAGE}@${tag} 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,
+    };
+}
+/**
+ * Which OpenCode plugin build the CLI is held to, and which cache refreshes.
+ * Under `--next` that is `akm-opencode@next`, but only when the user's OpenCode
+ * config names that tag: otherwise OpenCode keeps resolving `@latest`, so the
+ * lockstep stays against the `@latest` pin and the entry is reported as skipped.
+ */
+function resolveOpenCodeTarget(next) {
+    const followNext = next && openCodeConfigRequestsNext();
+    const tag = followNext ? "next" : "latest";
+    const cache = detectOpenCodeCache(tag);
+    const latest = cache ? (followNext ? lookupOpenCodeNext() : lookupOpenCodeLatest()) : undefined;
+    return { cache, latest, tag, notFollowingNext: next && !followNext };
+}
+/** `akm upgrade`: the CLI step (held to the OpenCode plugin's akm), then the plugins. */
+export async function runUpgrade(args, currentVersion, deps) {
+    const next = args.next === true;
+    const channel = next ? "next" : "latest";
+    const openCode = resolveOpenCodeTarget(next);
+    const check = {
+        ...applyLockstep(await deps.checkForUpdate(currentVersion, channel), openCode.latest, openCode.tag),
+        channel,
+    };
+    if (args.check) {
+        return { mode: "check", result: { ...check, plugins: upgradePlugins({ dryRun: true, next, 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
+        // (or past the prerelease that `--next` chose).
+        ...(check.lockstep?.heldBack || (next && check.latestVersion) ? { targetVersion: check.latestVersion } : {}),
+    });
+    const plugins = upgradePlugins({ dryRun: false, next, openCode });
+    const result = { ...upgraded, channel, ...(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

@@ -174,7 +174,24 @@ export function getAkmBinaryName() {
         return "akm-windows-x64.exe";
     throw new ConfigError(`Unsupported platform for binary upgrade: ${platform}/${arch}`, "UNSUPPORTED_PLATFORM");
 }
-export async function checkForUpdate(currentVersion, fetchOptions) {
+/** The `next` dist-tag of this package on the npm registry, or undefined when none is published. */
+async function lookupNextVersion(fetchOptions) {
+    const url = `https://registry.npmjs.org/-/package/${encodeURIComponent(getInstalledPackageName())}/dist-tags`;
+    const response = await fetchWithRetry(url, { headers: { accept: "application/json" } }, fetchOptions);
+    if (!response.ok) {
+        throw new Error(`Failed to check for the next prerelease: ${response.status} ${response.statusText}`);
+    }
+    const tags = JSON.parse(await readBodyWithByteCap(response, MAX_CHECKSUM_METADATA_BYTES));
+    return typeof tags.next === "string" && tags.next !== "" ? tags.next : undefined;
+}
+/**
+ * The newest release. With `channel: "next"` that includes prereleases: the
+ * `next` dist-tag when it is newer than the latest stable release, else the
+ * stable release (a prerelease older than a stable one is never a target).
+ * A binary install downloads the GitHub release tagged `v<version>`, which a
+ * prerelease has too, so the version is all the install step needs.
+ */
+export async function checkForUpdate(currentVersion, fetchOptions, channel = "latest") {
     const installMethod = detectInstallMethod();
     const url = `https://api.github.com/repos/${REPO}/releases/latest`;
     const response = await fetchWithRetry(url, { headers: githubHeaders() }, fetchOptions);
@@ -183,7 +200,12 @@ export async function checkForUpdate(currentVersion, fetchOptions) {
     }
     const release = JSON.parse(await readBodyWithByteCap(response, MAX_CHECKSUM_METADATA_BYTES));
     const latestTag = release.tag_name ?? "";
-    const latestVersion = latestTag.replace(/^v/, "");
+    let latestVersion = latestTag.replace(/^v/, "");
+    if (channel === "next") {
+        const next = await lookupNextVersion(fetchOptions);
+        if (next && (latestVersion === "" || semverOrder(latestVersion, next) < 0))
+            latestVersion = next;
+    }
     return {
         currentVersion,
         latestVersion,
@@ -237,7 +259,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 +596,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,31 +33,43 @@ 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",
             description: "Skip the post-upgrade index rebuild",
             default: false,
         },
+        next: {
+            type: "boolean",
+            description: "Install the newest prerelease (the @next npm tag) of akm and, if OpenCode's config names akm-opencode@next, of its plugin",
+            default: false,
+        },
     },
     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"], next: args.next }, pkgVersion, {
+            checkForUpdate: (version, channel) => checkForUpdate(version, undefined, channel),
+            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,12 +662,38 @@ 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}`;
     }
     if (r.updateAvailable === true) {
-        return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade' to install)`;
+        return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
     }
     if (r.updateAvailable === false && r.latestVersion) {
         return `akm v${r.currentVersion} is already the latest version`;

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

@@ -30464,12 +30464,36 @@ 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}`;
   }
   if (r.updateAvailable === true) {
-    return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade' to install)`;
+    return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
   }
   if (r.updateAvailable === false && r.latestVersion) {
     return `akm v${r.currentVersion} is already the latest version`;
@@ -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,12 +29792,36 @@ 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}`;
   }
   if (r.updateAvailable === true) {
-    return `akm v${r.currentVersion} \u2192 v${r.latestVersion} available (run 'akm upgrade' to install)`;
+    return `akm v${r.currentVersion} \u2192 v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
   }
   if (r.updateAvailable === false && r.latestVersion) {
     return `akm v${r.currentVersion} is already the latest version`;
@@ -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,133 @@ 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
+akm upgrade --next       # Install the newest prerelease (@next) instead of the latest stable release
 ```
 
 | 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 |
+| `--next` | Follow the `next` prerelease channel: install the newest prerelease of akm (and of the OpenCode plugin, see [Prereleases](#prereleases-next)). Works with `--check`, `--force` and `-q` |
 
 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.
+
+#### Prereleases (`--next`)
+
+`akm upgrade --next` means "newest available, prereleases included". The result
+carries `channel: "next"` (`"latest"` otherwise); no other field changes.
+
+- **CLI.** The target is the `next` dist-tag of `akm-cli` (read from the npm
+  registry, so it works for binary installs too) when that is newer than the
+  latest stable release; otherwise the latest stable release. It never moves
+  backwards. npm, Bun and pnpm installs run `<manager> add|install -g akm-cli@<that exact version>`;
+  standalone binaries download the GitHub release tagged `v<that version>`
+  (prereleases are GitHub releases too) and verify its checksum as usual.
+- **OpenCode.** OpenCode resolves a bare `"akm-opencode"` in its `plugin` list
+  to `@latest`, and caches `@next` in its own folder
+  (`$XDG_CACHE_HOME/opencode/packages/akm-opencode@next`). akm does not edit
+  your OpenCode config, so it can only follow `@next` when you ask for it:
+
+  ```json
+  { "plugin": ["akm-opencode@next"] }
+  ```
+
+  With that line in the global OpenCode config (`~/.config/opencode/opencode.json`
+  or `.jsonc`, or the file named by `OPENCODE_CONFIG`), lockstep and the cache
+  refresh use `akm-opencode@next` (its version and its `akm-cli` pin) instead of
+  `@latest`. If `akm-opencode@next` is missing, older than `@latest`, or its
+  `akm-cli` pin is unreadable, the CLI is held where it is and the OpenCode entry
+  is `failed`, exactly as in the stable lockstep above.
+
+  Without that line the OpenCode entry is `skipped`, its message names the line
+  to add, and lockstep stays against the `@latest` pin, so the CLI does not go
+  past what OpenCode will run.
+- **Claude Code and Codex.** Unchanged: their plugin comes from the `akm-plugins`
+  git marketplace, which has no prerelease channel and accepts any 0.9.x akm,
+  prereleases included. Their entries carry a note saying so.
+- `--check --next` reports all of this and changes nothing.
+
+#### 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.28-alpha.3",
+  "version": "0.9.28-alpha.5",
   "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": [