akm-cli 0.9.31 → 0.9.32

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.32] - 2026-10-13
+
+A patch release: `akm feedback` no longer reports success for feedback it could not store.
+
+### Fixed
+
+- **`akm feedback` fails when it cannot record the feedback.** 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, so an agent knows its feedback was lost. Add akm's data directory to the sandbox's writable paths.
+
 ## [0.9.31] - 2026-10-09
 
 A patch release: concurrent config writes no longer lose a change, OpenAI's reasoning models work as `llm`

package/dist/commands/feedback-cli.js

@@ -13,16 +13,16 @@ 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 { resolveSourceEntries } from "../indexer/search/search-source.js";
-import { countFeedbackSignals, insertUsageEvent, resolveUsageEventSource } from "../indexer/usage/usage-events.js";
+import { countFeedbackSignals, 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";
@@ -157,8 +157,9 @@ function buildLessonStrengthUpdate(rawBytes, feedbackRef) {
  * `task`, `audit`, `unknown`) — an anti-self-reinforcement guard that stops an
  * agent or automated pipeline from boosting its own picks. This is by design
  * and must not be removed; R-034 only asks that the skip be surfaced to the
- * caller rather than passing silently. Best-effort: a utility-update failure
- * never fails the feedback record.
+ * caller rather than passing silently. A failed usage-event write fails the
+ * command (DATA_DIR_NOT_WRITABLE); a utility-update failure never fails the
+ * feedback record.
  */
 function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadataStr) {
     let utilityResult;
@@ -166,14 +167,21 @@ function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadata
     let rankingUpdateSkippedReason;
     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") {
             rankingUpdateSkippedReason =
                 `feedback source is "${eventSource}", not "user" — ranking updates only apply to user-attributed ` +

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

@@ -54,14 +54,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 ────────────────────────────────────────────────────────────────────
 /**
  * Aggregate positive/negative feedback counts for a single entry.

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

@@ -25664,6 +25664,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

@@ -24992,6 +24992,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/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.9.31",
+  "version": "0.9.32",
   "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": [