akm-cli 0.10.261002-beta → 0.10.261004-beta

package/CHANGELOG.md

@@ -6,6 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261004] - 2026-10-13
+
+### Fixed
+
+- **`akm feedback` fails when it cannot record the feedback** (also in 0.9.32). When `state.db` was read-only to the
+  process, as it is inside an agent sandbox that only allows writes in the workspace, the feedback row was silently
+  dropped and the command still printed `"ok": true`. It now fails with a `DATA_DIR_NOT_WRITABLE` config error (exit
+  78) and records nothing. Add akm's data directory to the sandbox's writable paths.
+
+## [0.10.261003] - 2026-10-12
+
+### Fixed
+
+- **`akm upgrade` now keeps the OpenCode 2 plugin (`akm-opencode-v2`) current.** Three things stopped it:
+  `--next` refused with "pins akm-cli ... older than the ... that @latest pins" because npm's `latest` for
+  `akm-opencode-v2` is a retired daily alpha whose 8-digit pin sorts above every monthly build (and the lockstep
+  reported that as "could not read the akm-cli pin"); `--next` now follows the `next` tag and no longer compares it with
+  `@latest`, for OpenCode 1 as well. The refresh trashed the cache and deferred whenever an OpenCode process ran, which
+  on a host with a standing `opencode serve` was always. It now runs OpenCode 2's own `opencode plugin update <spec>`,
+  which installs the new build beside the old one for the running service to pick up at its next restart, so it is
+  neither trashed nor deferred. OpenCode 1 is unchanged.
+
+- **`akm upgrade --next` no longer says the Claude Code and Codex plugins have "no prerelease channel" and work "with
+  any 0.9.x akm".** akm-plugins now has a `next` branch for prereleases, and the plugins require akm 0.10.261001 or
+  newer. The `--next` note now names the ref the `akm-plugins` marketplace follows (read from `claude plugin marketplace
+  list` and Codex's `config.toml`) and, when it is the stable default branch, how to switch to `next`. `akm upgrade`
+  still only updates the ref the marketplace follows.
+
 ## [0.10.261002] - 2026-10-12
 
 ### Fixed

package/dist/commands/feedback-cli.js

@@ -13,17 +13,17 @@ import { parseFrontmatter, parseFrontmatterBlock, spliceFrontmatterLine } from "
 import { conceptIdFromTypeName, parseRefInput, typeNameFromConceptId } from "../core/asset/resolve-ref.js";
 import { isWithin, resolveStashDir, safeRealpath, writeFileAtomic } from "../core/common.js";
 import { loadConfig } from "../core/config/config.js";
-import { NotFoundError, UsageError } from "../core/errors.js";
+import { ConfigError, NotFoundError, UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
 import { resolveMutationTarget } from "../core/mutation-target.js";
 import { isPathAbsent } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
-import { withStateDb } from "../core/state-db.js";
+import { getStateDbPath, withStateDb } from "../core/state-db.js";
 import { warn } from "../core/warn.js";
 import { withWriteTargetMutation } from "../core/write-source.js";
 import { recomputeUtilityScores } from "../indexer/indexer.js";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
-import { insertUsageEvent, resolveUsageEventSource } from "../indexer/usage/usage-events.js";
+import { insertUsageEventStrict, resolveUsageEventSource } from "../indexer/usage/usage-events.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { findEntryIdByRef, getEntryFilePathById, getItemRefById, } from "../storage/repositories/index-entries-repository.js";
@@ -161,20 +161,28 @@ const UTILITY_REVIEW_THRESHOLD = 0.5;
  * boosting its own picks. This is by design and must not be removed. The
  * utility score is read by improve and metrics only; its update is best-effort
  * and its failure never fails the feedback record or changes the ranking effect.
+ * A failed usage-event write fails the command (DATA_DIR_NOT_WRITABLE).
  */
 function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadataStr) {
     let utilityResult;
     let rankingSkippedReason;
     const eventSource = resolveUsageEventSource();
     withStateDb((stateDb) => {
-        insertUsageEvent(stateDb, {
-            event_type: "feedback",
-            entry_ref: durableEntryRef,
-            entry_id: entryId,
-            signal,
-            metadata: metadataStr,
-            source: eventSource,
-        });
+        // The usage event IS the feedback record, so a failed write fails the command
+        // instead of reporting ok while nothing was stored.
+        try {
+            insertUsageEventStrict(stateDb, {
+                event_type: "feedback",
+                entry_ref: durableEntryRef,
+                entry_id: entryId,
+                signal,
+                metadata: metadataStr,
+                source: eventSource,
+            });
+        }
+        catch (err) {
+            throw new ConfigError(`Feedback was not recorded: could not write ${getStateDbPath()} (${err instanceof Error ? err.message : String(err)}).`, "DATA_DIR_NOT_WRITABLE");
+        }
         if (eventSource !== "user") {
             rankingSkippedReason =
                 `feedback source is "${eventSource}", not "user" — it does not count toward search ranking, which counts ` +

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

@@ -88,22 +88,26 @@ function detectClaudeCode() {
         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)) {
+    const marketplace = Array.isArray(list) ? list.find((m) => m?.name === MARKETPLACE) : undefined;
+    if (!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 };
+    return { version: plugin.version, ref: typeof marketplace.ref === "string" ? marketplace.ref : undefined };
 }
-function upgradeClaudeCode(dryRun) {
+function upgradeClaudeCode(dryRun, next) {
     const detected = detectClaudeCode();
     if ("entry" in detected)
         return detected.entry;
+    const entry = refreshClaudeCode(dryRun, detected.version);
+    return next ? withChannelNote(entry, detected.ref, "re-add the marketplace as `itlackey/akm-plugins@next`") : entry;
+}
+function refreshClaudeCode(dryRun, from) {
     if (dryRun)
-        return unknownRefresh("claude-code", detected.version);
+        return unknownRefresh("claude-code", from);
     const marketplace = runCommand("claude", ["plugin", "marketplace", "update", MARKETPLACE], REFRESH_TIMEOUT_MS);
     if (!marketplace.ok)
         return failed("claude-code", marketplace.error);
@@ -111,7 +115,7 @@ function upgradeClaudeCode(dryRun) {
     if (!update.ok)
         return failed("claude-code", update.error);
     const after = claudePluginVersion();
-    return refreshed("claude-code", detected.version, "version" in after ? after.version : undefined);
+    return refreshed("claude-code", from, "version" in after ? after.version : undefined);
 }
 // ── Codex ───────────────────────────────────────────────────────────────────
 function codexPluginVersion() {
@@ -122,21 +126,39 @@ function codexPluginVersion() {
     const plugin = parsed?.installed?.find((p) => p?.pluginId === PLUGIN_ID);
     return { version: plugin ? String(plugin.version ?? "") : undefined };
 }
-function upgradeCodex(dryRun) {
+/** The ref `[marketplaces.akm-plugins]` follows in Codex's config.toml; undefined when it names none (the default branch). */
+function codexMarketplaceRef() {
+    try {
+        const home = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+        const config = fs.readFileSync(path.join(home, "config.toml"), "utf8");
+        const section = config.split(/^\[/m).find((part) => part.startsWith(`marketplaces.${MARKETPLACE}]`));
+        return section?.match(/^ref\s*=\s*"([^"]+)"/m)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+function upgradeCodex(dryRun, next) {
     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`);
     }
+    const entry = refreshCodex(dryRun, before.version);
+    return next
+        ? withChannelNote(entry, codexMarketplaceRef(), "run `codex plugin marketplace add itlackey/akm-plugins --ref next`")
+        : entry;
+}
+function refreshCodex(dryRun, from) {
     if (dryRun)
-        return unknownRefresh("codex", before.version);
+        return unknownRefresh("codex", from);
     // 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);
+    return refreshed("codex", from, "version" in after ? after.version : undefined);
 }
 // ── OpenCode ────────────────────────────────────────────────────────────────
 const nextSpec = (flavor) => `${flavor.pkg}@next`;
@@ -225,39 +247,6 @@ export function lookupOpenCodeLatest(tag, flavor) {
     const akmCli = parsed["dependencies.akm-cli"];
     return { version: parsed.version, akmCli: typeof akmCli === "string" ? akmCli : undefined };
 }
-/**
- * `<pkg>@next`, which must exist and pin an akm-cli no older than the one
- * `@latest` pins: a prerelease channel that trails the stable one is not a target.
- *
- * The two builds are compared by their akm-cli pins, never by their own
- * versions. akm-plugins' stable versions are `<akm_version><yyyymmddhhmm>`
- * concatenated into the PATCH (`0.9.27202610072331`), while prereleases are
- * `<akm_version>.<ts>` (`0.9.28-alpha.8.202610081938`), so by semver every
- * prerelease sorts below the stable build and the comparison means nothing
- * (#1089). For the same reason plugin versions are only ever tested for
- * equality (is the cache already this build?), never ordered.
- */
-export function lookupOpenCodeNext(flavor) {
-    const next = lookupOpenCodeLatest("next", flavor);
-    if ("error" in next)
-        return next;
-    const latest = lookupOpenCodeLatest("latest", flavor);
-    if ("error" in latest)
-        return { error: `could not compare with ${flavor.pkg}@latest: ${latest.error}` };
-    // No pin on @next: returned as is, and the lockstep holds the CLI and says why.
-    if (!next.akmCli)
-        return next;
-    if (!latest.akmCli) {
-        return { error: `could not compare with ${flavor.pkg}@latest: it declares no akm-cli dependency` };
-    }
-    if (semverOrder(next.akmCli, latest.akmCli) < 0) {
-        return {
-            error: `${nextSpec(flavor)} (${next.version}) pins akm-cli ${next.akmCli}, older than the ` +
-                `${latest.akmCli} that ${flavor.pkg}@latest (${latest.version}) pins`,
-        };
-    }
-    return next;
-}
 const CONTAINER_CGROUP = /docker|containerd|podman|libpod|lxc/;
 /**
  * Whether the process could use this host's OpenCode cache. A process in another mount namespace (a container's
@@ -338,20 +327,24 @@ function upgradeOpenCode(dryRun, target) {
     if (cache.version === latest.version)
         return { harness, outcome: "current", from: cache.version, to: latest.version };
     const base = { harness, 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`",
-        };
+    // OpenCode 1's refresh replaces the cache the running OpenCode is using, so it waits for the exit.
+    // OpenCode 2's `plugin update` installs beside the old build, which a running service keeps using until it restarts.
+    if (flavor.replacesCache) {
+        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, and only the major
-    // that owns this plugin's cache can re-create it. akm never installs or replaces the binary.
+    // OpenCode must be runnable before anything changes: only the major that owns this plugin's cache can
+    // refresh it. akm never installs or replaces the binary.
     // OpenCode 2 may sit beside an OpenCode 1 `opencode` as `opencode2`; OpenCode 1 is only ever `opencode`.
     const bin = flavor.major === 2 ? resolveOpencodeBin() : OPENCODE_SDK_SERVER_BIN;
     const detected = detectOpencodeMajor(bin);
@@ -362,43 +355,55 @@ function upgradeOpenCode(dryRun, target) {
     // refresh needs a command only OpenCode 2 has, so it must be sure.
     if (major === undefined ? flavor.major === 2 : major !== flavor.major) {
         return skipped(harness, `\`${bin}\` on PATH is ${major === undefined ? "of an unknown version" : `OpenCode ${major}`}, ` +
-            `not OpenCode ${flavor.major}, so it cannot re-create the ${flavor.pkg} cache; the cache is left alone`);
-    }
-    try {
-        moveToTrash(cache.dir);
+            `not OpenCode ${flavor.major}, so it cannot refresh the ${flavor.pkg} cache; the cache is left alone`);
     }
-    catch (error) {
-        return failed(harness, `could not move ${cache.dir} to the trash: ${error instanceof Error ? error.message : String(error)}`);
+    if (flavor.replacesCache) {
+        try {
+            moveToTrash(cache.dir);
+        }
+        catch (error) {
+            return failed(harness, `could not move ${cache.dir} to the trash: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
+    const trashed = flavor.replacesCache ? " (the old cache is in the trash)" : "";
     // 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(bin, flavor.prefetch(target.spec), PREFETCH_TIMEOUT_MS, { cwd: workDir });
-        if (!prefetch.ok)
-            return failed(harness, `${prefetch.error} (the old cache is in the trash)`);
+        let refresh = runCommand(bin, flavor.refresh(target.spec), PREFETCH_TIMEOUT_MS, { cwd: workDir });
+        // OpenCode 2 starts its background service for this command and answers "Plugin is not configured" until
+        // that service has loaded the plugins, so the first command after the service was down fails. Ask again.
+        for (let retry = 0; !refresh.ok && flavor.major === 2 && retry < 2 && /not configured/.test(refresh.error); retry++) {
+            refresh = runCommand(bin, flavor.refresh(target.spec), PREFETCH_TIMEOUT_MS, { cwd: workDir });
+        }
+        if (!refresh.ok)
+            return failed(harness, `${refresh.error}${trashed}`);
     }
     finally {
         fs.rmSync(workDir, { recursive: true, force: true });
     }
     const after = detectOpenCodeCache(tag, flavor);
     if (!after)
-        return failed(harness, "opencode did not re-create the plugin cache (the old cache is in the trash)");
+        return failed(harness, `opencode did not re-create the plugin cache${trashed}`);
     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) {
+/**
+ * The note `--next` adds to a marketplace harness. The channel is the ref the marketplace follows (`next` is the
+ * prerelease branch, the default branch is stable); akm only updates that ref and cannot switch it.
+ */
+function withChannelNote(entry, ref, howToSwitch) {
     if (entry.outcome === "skipped")
         return entry;
-    return { ...entry, message: entry.message ? `${entry.message}; ${NO_PRERELEASE_CHANNEL}` : NO_PRERELEASE_CHANNEL };
+    const note = ref === "next"
+        ? `--next: the ${MARKETPLACE} marketplace follows ref next, the prerelease channel`
+        : `--next: the ${MARKETPLACE} marketplace follows ${ref ? `ref ${ref}` : "the default branch (stable)"}, ` +
+            `not the prerelease channel; akm upgrade cannot switch it, ${howToSwitch} to follow prereleases`;
+    return { ...entry, message: entry.message ? `${entry.message}; ${note}` : note };
 }
 export function upgradePlugins(opts) {
-    const claude = upgradeClaudeCode(opts.dryRun);
-    const codex = upgradeCodex(opts.dryRun);
     return [
-        opts.next ? withNextNote(claude) : claude,
-        opts.next ? withNextNote(codex) : codex,
+        upgradeClaudeCode(opts.dryRun, opts.next),
+        upgradeCodex(opts.dryRun, opts.next),
         ...opts.openCode.map((target) => upgradeOpenCode(opts.dryRun, target)),
     ];
 }
@@ -500,7 +505,7 @@ function resolveOpenCodeTarget(next, flavor, configured) {
         return leftAlone(otherSpecNote(flavor, spec));
     const tag = followNext ? "next" : "latest";
     const cache = detectOpenCodeCache(tag, flavor);
-    const latest = cache ? (followNext ? lookupOpenCodeNext(flavor) : lookupOpenCodeLatest("latest", flavor)) : undefined;
+    const latest = cache ? lookupOpenCodeLatest(tag, flavor) : undefined;
     return { flavor, cache, latest, tag, spec, notFollowingNext: next && !followNext };
 }
 /**

package/dist/core/errors.js

@@ -10,6 +10,7 @@ const CONFIG_HINTS = {
     STASH_DIR_NOT_A_DIRECTORY: "The configured default bundle path exists but isn't a directory. Update it to point at a folder.",
     STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update the default bundle path.",
     DATA_DIR_UNREADABLE: "The data directory is not readable by the user running akm. Check its owner and mode, or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns.",
+    DATA_DIR_NOT_WRITABLE: "Nothing was recorded. Make the akm data directory writable for this process (for an agent sandbox, add it to the writable paths), or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user can write, then retry.",
     INDEX_SCHEMA_INCOMPATIBLE: "Run `akm index --full` to rebuild the derived index from the currently materialized sources.",
     LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
     TEST_ISOLATION_MISSING: "Under bun test, when AKM_BUNDLE_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",

package/dist/indexer/usage/usage-events.js

@@ -55,14 +55,18 @@ export function ensureUsageEventsSchema(db) {
  */
 export function insertUsageEvent(db, event) {
     try {
-        db.prepare(`INSERT INTO usage_events (event_type, query, entry_id, entry_ref, signal, metadata, source)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`).run(event.event_type, event.query ?? null, event.entry_id ?? null, event.entry_ref ?? null, event.signal ?? null, event.metadata ?? null, event.source ?? "unknown");
+        insertUsageEventStrict(db, event);
     }
     catch (error) {
         rethrowIfTestIsolationError(error);
         /* fire-and-forget: silently ignore errors */
     }
 }
+/** Insert a usage event and let a failed write throw, for callers whose record is the event itself. */
+export function insertUsageEventStrict(db, event) {
+    db.prepare(`INSERT INTO usage_events (event_type, query, entry_id, entry_ref, signal, metadata, source)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(event.event_type, event.query ?? null, event.entry_id ?? null, event.entry_ref ?? null, event.signal ?? null, event.metadata ?? null, event.source ?? "unknown");
+}
 // ── Query ────────────────────────────────────────────────────────────────────
 /**
  * User feedback counts for many assets at once, keyed by durable `entry_ref`.

package/dist/integrations/harnesses/opencode/plugin-layout.js

@@ -48,7 +48,8 @@ export const OPENCODE_V1 = {
     cacheFolder: (spec) => path.join("packages", spec),
     nodeModulesDir: (folder) => path.join(folder, "node_modules"),
     // Any OpenCode command that resolves the config installs the plugin again.
-    prefetch: () => ["debug", "config"],
+    refresh: () => ["debug", "config"],
+    replacesCache: true,
 };
 export const OPENCODE_V2 = {
     harness: "opencode-v2",
@@ -63,6 +64,8 @@ export const OPENCODE_V2 = {
         const build = newestBuildDir(folder);
         return build ? path.join(build, "node_modules") : undefined;
     },
-    // `debug config` does not resolve plugins in OpenCode 2; `plugin add` of a configured spec only reinstalls it.
-    prefetch: (spec) => ["plugin", "add", spec],
+    // `plugin update <spec>` (the spec as the config names it) installs the new build into a fresh
+    // `<epoch-ms>` folder and leaves the old ones; the running service stays on the old build until it restarts.
+    refresh: (spec) => ["plugin", "update", spec],
+    replacesCache: false,
 };

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

@@ -25658,6 +25658,7 @@ var CONFIG_HINTS = {
   STASH_DIR_NOT_A_DIRECTORY: "The configured default bundle path exists but isn't a directory. Update it to point at a folder.",
   STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update the default bundle path.",
   DATA_DIR_UNREADABLE: "The data directory is not readable by the user running akm. Check its owner and mode, or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns.",
+  DATA_DIR_NOT_WRITABLE: "Nothing was recorded. Make the akm data directory writable for this process (for an agent sandbox, add it to the writable paths), or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user can write, then retry.",
   INDEX_SCHEMA_INCOMPATIBLE: "Run `akm index --full` to rebuild the derived index from the currently materialized sources.",
   LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
   TEST_ISOLATION_MISSING: "Under bun test, when AKM_BUNDLE_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",

package/dist/scripts/akm-migrate.js

@@ -24986,6 +24986,7 @@ var CONFIG_HINTS = {
   STASH_DIR_NOT_A_DIRECTORY: "The configured default bundle path exists but isn't a directory. Update it to point at a folder.",
   STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update the default bundle path.",
   DATA_DIR_UNREADABLE: "The data directory is not readable by the user running akm. Check its owner and mode, or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns.",
+  DATA_DIR_NOT_WRITABLE: "Nothing was recorded. Make the akm data directory writable for this process (for an agent sandbox, add it to the writable paths), or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user can write, then retry.",
   INDEX_SCHEMA_INCOMPATIBLE: "Run `akm index --full` to rebuild the derived index from the currently materialized sources.",
   LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
   TEST_ISOLATION_MISSING: "Under bun test, when AKM_BUNDLE_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",

package/docs/migration/release-notes/0.10.0.md

@@ -155,10 +155,12 @@ Other breaking changes:
 
 - `akm-opencode` is for OpenCode 1. `akm-opencode-v2` is for OpenCode 2. Each
   pins one exact `akm-cli`, and `akm upgrade` holds the CLI to the pin.
-- OpenCode caches the plugin spec it resolved and does not re-check it. A new
+- OpenCode 1 caches the plugin spec it resolved and does not re-check it. A new
   build is picked up only after the plugin's cache folder is cleared. `akm
   upgrade` does this for `@latest` (or `@next`) when no OpenCode process runs.
-  A spec pinned in your OpenCode config is left alone.
+  For OpenCode 2 it runs `opencode plugin update` instead, even while OpenCode
+  runs; the new build loads at the next restart. A spec pinned in your OpenCode
+  config is left alone.
 - OpenCode 1 asks before reading or writing outside the project directory.
   OpenCode 2 does not unless its config says `ask`, so akm's rejection of a
   permission request only happens there once you add the rule. akm changes no

package/docs/migration/v0.9-to-v0.10.md

@@ -407,12 +407,16 @@ run. For OpenCode 2, run `opencode plugin add akm-opencode-v2`.
   it holds the CLI to the older pin. It never moves the CLI backwards. If it
   cannot read the pin it leaves the CLI alone and exits 1. `akm health` warns
   when a plugin's bundled `akm-cli` differs from the running CLI.
-- **OpenCode caches the plugin spec it resolved, and never re-checks it.** A new
-  plugin build is not picked up until its cache folder is cleared. `akm upgrade`
-  does this for `@latest` (and `@next` with `--next`) when no OpenCode process
-  is running: it moves the folder to the trash, then re-fetches (`opencode debug
-  config` for OpenCode 1, `opencode plugin add akm-opencode-v2` for OpenCode 2).
-  If your config pins another spec, such as `akm-opencode@0.9.30`, `akm upgrade`
+- **OpenCode 1 caches the plugin spec it resolved, and never re-checks it.** A
+  new plugin build is not picked up until its cache folder is cleared. `akm
+  upgrade` does this for `@latest` (and `@next` with `--next`) when no OpenCode
+  process is running: it moves the folder to the trash, then re-fetches
+  (`opencode debug config`). **OpenCode 2** has an updater: `akm upgrade` runs
+  `opencode plugin update akm-opencode-v2` (with the spec your config names)
+  even while OpenCode runs; the running service keeps the old build until it
+  restarts. (`opencode plugin list` and `check` print "No plugins found" until
+  the service has loaded plugins after a restart, and `plugin update` leaves the
+  old build folders behind.) If your config pins another spec, such as `akm-opencode@0.9.30`, `akm upgrade`
   leaves it alone: change the spec, quit OpenCode, move that cache folder aside
   and start OpenCode again.
 - **OpenCode 2 permission defaults.** akm rejects every OpenCode permission
@@ -430,7 +434,12 @@ run. For OpenCode 2, run `opencode plugin add akm-opencode-v2`.
   driven as OpenCode 2 with a warning.
 - **Claude Code and Codex plugins** come from the `akm-plugins` marketplace and
   are updated by `akm upgrade`. Use the 0.10 plugin set with 0.10 (it passes
-  `--detail agent`; see itlackey/akm-plugins#133).
+  `--detail agent`; see itlackey/akm-plugins#133); the plugins require akm
+  0.10.261001 or newer. The marketplace's default branch is stable and its
+  `next` branch carries prereleases: add it as `itlackey/akm-plugins@next` in
+  Claude Code, or `codex plugin marketplace add itlackey/akm-plugins --ref next`
+  in Codex. `akm upgrade` updates whichever ref the marketplace follows and
+  cannot switch it.
 - **Other callers.** Anything of yours that passes `--shape agent` (benchmark
   runners, hooks) needs `--detail agent` and akm 0.10 together. akm-eval's
   retrieval, skillret and longmemeval benchmarks are the known ones

package/docs/reference/cli.md

@@ -1341,7 +1341,7 @@ stopping the CLI upgrade.
 | 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 1 | `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`. |
-| OpenCode 2 | `akm-opencode-v2` is named under `"plugins"` in the global OpenCode config (`opencode.json` or `.jsonc`) and cached at `$XDG_CACHE_HOME/opencode/npm/akm-opencode-v2@latest/<build>/`, and the `opencode` on `PATH` is OpenCode 2 | Same rule as OpenCode 1, with `akm-opencode-v2`: the cache folder is moved to the trash, then `opencode plugin add akm-opencode-v2` is run from a temporary directory (for a spec the config already names it only re-installs the cache; it does not touch the config). Listed only on a host that has the plugin, so an OpenCode 1 host reports exactly what it did before. |
+| OpenCode 2 | `akm-opencode-v2` is named under `"plugins"` in the global OpenCode config (`opencode.json` or `.jsonc`) and cached at `$XDG_CACHE_HOME/opencode/npm/akm-opencode-v2@latest/<build>/`, and the `opencode` on `PATH` is OpenCode 2 | If npm's `akm-opencode-v2@latest` differs from the cached version (the newest `<build>` folder): `opencode plugin update <spec>` is run from a temporary directory, with the spec as the config names it. OpenCode 2 installs the new build into a fresh `<build>` folder and the running service keeps the old one until it restarts, so nothing is moved to the trash and the update is not deferred while OpenCode runs. Listed only on a host that has the plugin, so an OpenCode 1 host reports exactly what it did before. |
 
 The two OpenCode plugins never touch each other: `akm-opencode` is only looked
 for in OpenCode 1's cache and `plugin` key, `akm-opencode-v2` only in OpenCode
@@ -1349,11 +1349,17 @@ for in OpenCode 1's cache and `plugin` key, `akm-opencode-v2` only in OpenCode
 --version` and skips the plugin when the `opencode` on `PATH` is the other
 major, since only the matching major can re-create that cache; akm never
 installs or replaces `opencode`. A spec that appears only under the legacy
-`plugin` key for OpenCode 2 is skipped with a note (`opencode plugin add`
-would write a `plugins` entry). Which OpenCode major akm itself drives is
+`plugin` key for OpenCode 2 is skipped with a note (move it to `plugins`). Which OpenCode major akm itself drives is
 [detected from the engine's binary](configuration.md#engines), independent of this
 step.
 
+OpenCode 2 has its own updater, `opencode plugin check` and `opencode plugin update`,
+which akm uses for `akm-opencode-v2`. Two things to know when you run them by
+hand: `plugin list` and `plugin check` print "No plugins found" until the
+OpenCode service has loaded its plugins after a restart, and `plugin update`
+leaves the old `<build>` folders under the cache folder (the newest one is the
+one in use).
+
 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
@@ -1414,9 +1420,8 @@ carries `channel: "next"` (`"latest"` otherwise); no other field changes.
   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, pins an older `akm-cli` than
-  `@latest` does, 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.
+  `@latest`. If `akm-opencode@next` is missing 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.
 
   OpenCode 2's `akm-opencode-v2` follows the same rule with its own spec:
   `{ "plugins": ["akm-opencode-v2@next"] }`, cached under
@@ -1425,9 +1430,15 @@ carries `channel: "next"` (`"latest"` otherwise); no other field changes.
   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.
+- **Claude Code and Codex.** Their plugin comes from the `akm-plugins` git
+  marketplace, and the channel is the ref the marketplace follows: the default
+  branch is stable, the `next` branch carries prereleases. `akm upgrade` updates
+  whatever ref the marketplace follows and cannot switch it, with or without
+  `--next`. To follow prereleases, add the marketplace as `itlackey/akm-plugins@next`
+  in Claude Code (`extraKnownMarketplaces.akm-plugins.source.ref = "next"` in
+  `settings.json`), or run `codex plugin marketplace add itlackey/akm-plugins --ref next`
+  in Codex. Under `--next` their entries carry a note naming the ref followed.
+  The plugins need akm 0.10.261001 or newer; any newer akm passes.
 - `--check --next` reports all of this and changes nothing.
 
 #### Containers

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

@@ -79,6 +79,12 @@ mode and owner, and the uid you are running as. They do **not** report an empty
 index. `akm health` stays runnable in that state and reports it as a failing
 `state-db-readable` check, so it remains the command to reach for.
 
+If akm can read this directory but **cannot write** it — an agent sandbox that
+only allows writes inside the workspace, for instance — `akm feedback` fails with
+a `DATA_DIR_NOT_WRITABLE` config error (exit 78) and records nothing, instead of
+reporting success for feedback it could not store. Add the data directory to the
+sandbox's writable paths.
+
 > **0.9.1 note.** A pre-release build briefly chmodded this directory to `0700`
 > and the databases to `0600` on every open. That was reverted: it silently
 > changed the permissions of directories akm did not create, which broke installs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261002-beta",
+  "version": "0.10.261004-beta",
   "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": [