akm-cli 0.9.30 → 0.9.32

package/CHANGELOG.md

@@ -6,6 +6,46 @@ 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`
+engines, `akm improve --require-engines` probes send API keys, and the npm package's docs links resolve.
+
+### Fixed
+
+- **`akm improve --require-engines` sends each engine's API key with its probe.** The probe used the engine's
+  connection as resolved, where the key is still a symbolic reference that a dispatch reads only when it sends a
+  request, so every keyed endpoint (OpenAI, a gateway that enforces auth) answered 401 and the run stopped with
+  "engine completion path is not reachable". The probe now builds the connection as a dispatch does; a required key
+  that is missing is reported as that engine's failure.
+- **OpenAI's reasoning models (gpt-5.x) work as `llm` engines.** They answer 400 to any `temperature` but the
+  default and to `max_tokens`, so every akm model call failed on them. Like the existing fallback for the
+  thinking-control fields, a 400 that names `temperature` is retried once without it, and one that asks for
+  `max_completion_tokens` is retried with the cap under that name; the connection keeps the working shape for
+  the rest of the process.
+- **Every relative link in the npm package's docs resolves again.** #1118 made `docs/README.md`,
+  `docs/migration/README.md` and `docs/reference/cli.md` link by relative path to guides and pages the package did
+  not ship. npm always ships a folder's `README.md`, so those links were dead for npm users. The package now ships
+  the user-facing `docs/` folders (`agents`, `architecture`, `guides`, `integration`, `maintainers`, `migration`,
+  `posts`, `reference`), `docs/product-surface.md`, the one plan they link to, and `ROADMAP.md`. `docs/plans` stays
+  out. The link check skips link syntax inside code, which is an example, not a link.
+- **Concurrent `akm config set` runs no longer lose each other's changes.** A lock file was created empty and its
+  owner's PID written a moment later; a process that looked in that gap read no PID, took the live lock for an
+  abandoned one and removed it, so two writers ran at once and one change was lost. A lock now appears with its
+  owner's PID already in it. Every akm lock file (config, index writer, scheduler, `akm.lock`, run, extract, secret)
+  is created this way.
+
 ## [0.9.30] - 2026-10-09
 
 A patch release: `akm upgrade` acts only on the `akm-opencode` spec OpenCode's config names.

package/README.md

@@ -55,7 +55,7 @@ akm show scripts/deploy.sh         # View details and run command
 - **One library for every agent** -- Use the same capability library from Claude Code, OpenCode, Cursor, Aider, Windsurf, or any assistant that can run shell commands.
 - **Load only what the task needs** -- Search or curate a shortlist, then load full content by ref. No giant startup prompt is required.
 - **Package complete capabilities** -- Install and share bundles containing skills, scripts, workflows, agents, instructions, memories, and knowledge -- not just prompt snippets.
-- **Improve through evidence, with review** -- Feedback influences retrieval and produces diffable proposals. Changes remain reviewable and target only writable bundles.
+- **Improve through evidence, with review** -- Feedback re-ranks assets right away. A negative report can carry an exact text fix, and `akm improve` repairs metadata; every edit lands as a diffable proposal you accept, reject or revert, and only writable bundles are changed.
 - **Turn knowledge into repeatable work** -- Run persisted workflows with dispatch, gates, retries, budgets, and resume instead of reconstructing a process from prose every session.
 
 akm retrieves every supported capability type. It directly orchestrates
@@ -80,16 +80,16 @@ Or generate it directly: `akm help agents >> AGENTS.md`
 
 ## Documentation
 
-Full docs, CLI reference, and guides are available on [GitHub](https://github.com/itlackey/akm):
+Full docs, CLI reference, and guides are at **[akm.fwdslsh.dev](https://akm.fwdslsh.dev/)**:
 
-- [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.md)
-- [Supported Formats](https://github.com/itlackey/akm/blob/main/docs/reference/supported-formats.md)
-- [CLI Reference](https://github.com/itlackey/akm/blob/main/docs/reference/cli.md)
-- [Task v3 Reference](https://github.com/itlackey/akm/blob/main/docs/reference/tasks.md)
-- [0.9.2 Migration Guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.9.1-to-v0.9.2.md)
-- [Configuration](https://github.com/itlackey/akm/blob/main/docs/reference/configuration.md)
-- [Bundle Authoring Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-bundles.md)
-- [Registry](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md)
+- [Getting Started](https://akm.fwdslsh.dev/docs/guides/getting-started/)
+- [Supported Formats](https://akm.fwdslsh.dev/docs/reference/supported-formats/)
+- [CLI Reference](https://akm.fwdslsh.dev/docs/reference/cli/)
+- [Task v3 Reference](https://akm.fwdslsh.dev/docs/reference/tasks/)
+- [0.9.2 Migration Guide](https://akm.fwdslsh.dev/docs/migration/v0.9.1-to-v0.9.2/)
+- [Configuration](https://akm.fwdslsh.dev/docs/reference/configuration/)
+- [Bundle Authoring Guide](https://akm.fwdslsh.dev/docs/guides/author-bundles/)
+- [Registry](https://akm.fwdslsh.dev/docs/reference/registry/)
 
 ## License
 

package/ROADMAP.md

@@ -0,0 +1,112 @@
+# Roadmap
+
+This page outlines the high-level focus for the next two releases.
+
+It is intentionally directional rather than exhaustive. Detailed command,
+schema, and migration behavior still lives in the release notes, the
+migration guides, and [STABILITY.md](STABILITY.md), which classifies
+today's public contract by surface. The internal design specs behind the
+0.9.0 architecture consolidation live under
+[`docs/architecture/specs/`](docs/architecture/specs/).
+
+## 0.8 Foundation
+
+Release `0.8.0` already established much of the product shape that `0.9` and
+`1.0` build on.
+
+- The CLI and config surface were substantially redesigned.
+- `akm improve` became the main self-improvement and maintenance entry point.
+- Task assets, proposal workflows, health reporting, and agent command-building
+  all landed as first-class capabilities.
+- Storage, indexing, graph extraction, and migration paths were tightened to
+  support the v1 contract freeze.
+
+That means the next two releases are less about inventing a new direction and
+more about hardening, simplifying, and freezing what `0.8.0` put in place.
+
+## 0.9
+
+Release `0.9` is the architecture-consolidation release ahead of the `1.0`
+contract freeze. It replaces the flat asset-type registry with a
+**bundle / adapter** model and settles the durable contracts `1.0` will freeze.
+
+- **One canonical ref grammar.** Refs are `[bundle//]conceptId` — a
+  subdir-qualified concept id such as `skills/code-review` or `memories/vpn-note`
+  — replacing the pre-`0.9` `type:name` spelling. Durable state stores the
+  fully-qualified form; the short bundle-omitted form is input sugar. This is a
+  deliberate, one-time break, taken pre-`1.0` while it is still cheap.
+- **Format-neutral bundles.** Installed sources are bundles, each recognized by
+  a built-in adapter (Agent Skills, Claude/OpenCode commands and agents,
+  knowledge, YAML workflows, tasks, env/secret files, scripts, OKF and LLM-wiki
+  knowledge bases) instead of a closed asset-type list.
+- **Storage consolidation.** The durable databases collapse from four to three
+  (`state.db` / `index.db` / a separate `logs.db`); config migrates from the
+  flat `stashDir` / `sources` / `installed` keys to `bundles` / `defaultBundle`.
+  The one-time cutover is journaled and crash-resumable via `akm migrate apply`,
+  with a verified backup taken first.
+- **Debt paydown.** The improve / proposal / workflow internals are decomposed
+  onto one file-change transaction model and an ambient run context, the
+  deprecated `0.8` CLI aliases are removed, and the `vault` asset type is
+  retired in favor of `env` / `secret`.
+
+In short: `0.9` reduces ambiguity, pays down pre-`1.0` debt, and arrives at a
+small, durable core ready for the `1.0` freeze.
+
+### The 0.9.x series
+
+`0.9.x` is a series of refactoring and clean-up releases. The intent is to
+have **all technical debt paid off and all planned breaking changes handled
+before the 0.10.x series begins**. To get there quickly, 0.9.x patch releases
+may include breaking changes (see [STABILITY.md](STABILITY.md)); every
+break ships with a CHANGELOG migration note.
+
+Alongside the bug fixes and compatibility improvements, `0.9.x` also focuses
+on **tuning the improve processes** — reflect, distill, consolidate, memory
+inference, graph extraction, and proactive maintenance — and **settling the
+final design of those features** so the `0.10.0` release starts from a
+finished improve surface rather than one still being reshaped.
+
+## 0.10
+
+The `0.10.x` series is focused on **bug fixes and tuning** on top of the
+debt-free 0.9 core — no new architecture. With the clean-up done, 0.10.x
+attempts to return to the normal semver discipline: breaking changes only in
+major and minor releases, never in patches.
+
+## 0.X
+
+There may be other minor releases between 0.10.x and 1.0.0. The goal is to minimize the number of minor releases after 0.10.x, and they will only be used for addressing breaking changes that are justifiable before the 1.0.0 release.
+
+## 1.0
+
+Release `1.0` is focused on freezing the public contract and shipping the first
+stable ecosystem layer around that core.
+
+- Freeze the supported source model, the `[bundle//]conceptId` ref format,
+  search behavior, and write-target rules — the surfaces
+  [STABILITY.md](STABILITY.md)'s own 1.0 contract-freeze section
+  already names — and settle the surfaces it currently classifies as
+  Evolving or Experimental.
+- Carry the `0.8` agent and improvement workflow forward as a stable,
+  documented product surface rather than a collection of pre-release features.
+- Ship an official akm SDK for building integrations against the stable v1
+  contract instead of reverse-engineering CLI behavior.
+- Ship in-process akm plugins for Claude Code and OpenCode, built on that SDK,
+  so those tools can integrate more deeply without changing the CLI-first core
+  model that akm itself relies on.
+- Keep the CLI as the canonical foundation so the SDK and plugin story extends
+  the existing system rather than forking it into separate integration models.
+
+In short: `1.0` is where akm stops being only a strong CLI and becomes a stable
+platform for both direct use and deeper tool integration.
+
+## Scope Notes
+
+- The CLI remains the foundation in both releases.
+- `0.9` prioritizes hardening over expansion.
+- `1.0` adds the SDK and in-process plugin story on top of a frozen core, not
+  instead of it.
+- The roadmap assumes the `0.8.0` redesign is the baseline; later releases are
+  about stabilizing and extending that baseline, not replacing it.
+- Specific features may move between releases as implementation and testing
+  shake out, but the themes above are the intended direction.

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/commands/improve/improve-cli.js

@@ -16,7 +16,8 @@ import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { defaultWhich } from "../../integrations/agent/detect.js";
-import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
+import { collectEngineCredentialValues, materializeLlmConnection, } from "../../integrations/agent/engine-resolution.js";
+import { llmUseFromRunner, sdkFallbackUseFromRunner } from "../../integrations/agent/runner.js";
 import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
 import { deliverRendered } from "../../output/html-render.js";
@@ -81,18 +82,36 @@ function collectRequiredEngineTargets(plan) {
     const runners = Object.entries(plan.processes)
         .flatMap(([processName, process]) => (process.runner ? [[processName, process.runner]] : []))
         .concat(plan.triageJudgment ? [["triage.judgment", plan.triageJudgment]] : []);
-    return runners.map(([processName, runner]) => ({
-        process: processName,
-        engine: runner.engine,
-        ...(runner.kind === "llm" ? { connection: probeConnection(runner) } : { bin: runner.profile.bin }),
-        ...(runner.kind === "sdk" && runner.fallbackConnection
-            ? { connection: probeConnection({ connection: runner.fallbackConnection, timeoutMs: runner.fallbackTimeoutMs }) }
-            : {}),
-    }));
+    return runners.map(([processName, runner]) => {
+        // The runner's own timeout, else the connection's (sdkFallbackUseFromRunner already does this).
+        const use = runner.kind === "llm"
+            ? {
+                ...llmUseFromRunner(runner),
+                timeoutMs: runner.timeoutMs !== undefined ? runner.timeoutMs : (runner.connection.timeoutMs ?? null),
+            }
+            : runner.kind === "sdk"
+                ? sdkFallbackUseFromRunner(runner)
+                : undefined;
+        return {
+            process: processName,
+            engine: runner.engine,
+            ...(runner.kind === "llm" ? {} : { bin: runner.profile.bin }),
+            ...(use ? probeConnection(use) : {}),
+        };
+    });
 }
-/** The resolved engine keeps its request timeout beside the connection (the runtime merges it in); the probe needs it on the connection. */
-function probeConnection(runner) {
-    return runner.timeoutMs !== undefined ? { ...runner.connection, timeoutMs: runner.timeoutMs } : runner.connection;
+/**
+ * The connection the probe sends, built as a dispatch builds it: the runner
+ * keeps its credential symbolic, so the key is read and injected here, or the
+ * probe would go out without one.
+ */
+function probeConnection(use) {
+    try {
+        return { connection: materializeLlmConnection(use) };
+    }
+    catch (err) {
+        return { connection: use.connection, error: err instanceof Error ? err.message : String(err) };
+    }
 }
 /**
  * The bound on `--require-engines`' probe: the connection's own request
@@ -133,6 +152,8 @@ export async function assertRequiredEnginesReachable(plan, probeReachable = (con
         }
         if (!target.connection)
             return { ...target, reach: { reachable: true }, latencyMs: 0 };
+        if (target.error)
+            return { ...target, reach: { reachable: false, error: target.error }, latencyMs: 0 };
         return { ...target, ...(await probeConnectionOnce(target.connection)) };
     }));
     const unreachable = probed.filter((item) => !item.reach.reachable);

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/core/file-lock.js

@@ -51,14 +51,23 @@ function releaseLockRaw(lockPath) {
 }
 /** Create the lock file atomically; `undefined` when another holder already has it. */
 export function tryAcquireLockSync(lockPath, payload) {
+    // Write the payload under a private name, then hard-link it into place: the
+    // link is the exclusive step and the lock never exists without its payload.
+    // A `wx` write creates the file empty and fills it in afterwards; a contender
+    // probing in that gap reads no pid, calls the live lock stale and reclaims it.
+    const tmpPath = `${lockPath}.tmp-${process.pid}-${randomUUID()}`;
+    fs.writeFileSync(tmpPath, payload, { flag: "wx" });
     try {
-        fs.writeFileSync(lockPath, payload, { flag: "wx" });
+        fs.linkSync(tmpPath, lockPath);
     }
     catch (err) {
         if (err.code === "EEXIST")
             return undefined;
         throw err;
     }
+    finally {
+        releaseLockRaw(tmpPath);
+    }
     let snapshot;
     try {
         snapshot = readLockSnapshot(lockPath);

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/llm/client.js

@@ -227,6 +227,12 @@ const jsonSchemaUnsupportedConnections = new Set();
  * `enable_thinking`): a strict hosted API answers 400 `Unknown parameter`.
  */
 const thinkingControlRejectedConnections = new Set();
+/**
+ * And for OpenAI's reasoning models: they answer 400 to any `temperature` but
+ * the default, and to `max_tokens`, naming `max_completion_tokens` instead.
+ */
+const temperatureRejectedConnections = new Set();
+const maxCompletionTokensConnections = new Set();
 function connectionKey(config) {
     return `${config.endpoint}|${config.model}`;
 }
@@ -234,6 +240,8 @@ function connectionKey(config) {
 export function _resetEndpointSupportTrackersForTests() {
     jsonSchemaUnsupportedConnections.clear();
     thinkingControlRejectedConnections.clear();
+    temperatureRejectedConnections.clear();
+    maxCompletionTokensConnections.clear();
 }
 /**
  * Whether this connection has already been proven, this process, not to
@@ -263,6 +271,10 @@ function isRejectedRequest(err) {
 }
 /** A strict API names the field it does not know: `Unknown parameter: 'chat_template_kwargs'.` */
 const THINKING_FIELD_NAMED = /chat_template_kwargs|enable_thinking/;
+/** `Unsupported value: 'temperature' does not support 0 with this model. Only the default (1) value is supported.` */
+const TEMPERATURE_NAMED = /'temperature'/;
+/** `Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.` */
+const MAX_TOKENS_REPLACED = /max_completion_tokens/;
 /**
  * A single chat-completion attempt: one HTTP request/response cycle, with an
  * inline fallback-once when a schema was requested and the provider 4xx's
@@ -275,7 +287,10 @@ const THINKING_FIELD_NAMED = /chat_template_kwargs|enable_thinking/;
  *
  * The thinking-control fields get the same treatment (#1045): a 4xx that
  * names `chat_template_kwargs` or `enable_thinking` is answered by one retry
- * without them, which may in turn fall back without the schema.
+ * without them, which may in turn fall back without the schema. A 4xx that
+ * names `temperature`, or asks for `max_completion_tokens`, is answered the
+ * same way: the connection stops sending `temperature`, or sends the token cap
+ * as `max_completion_tokens`, for the rest of the process.
  */
 async function chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking = (options?.enableThinking ?? config.enableThinking) !== undefined &&
     !isThinkingControlKnownRejected(config)) {
@@ -286,6 +301,17 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs, inclu
     catch (err) {
         if (!isRejectedRequest(err))
             throw err;
+        const key = connectionKey(config);
+        if (TEMPERATURE_NAMED.test(err.message) && !temperatureRejectedConnections.has(key)) {
+            warnVerbose(`[akm] LLM rejected temperature (${err.statusCode}); retrying once without it: ${err.message}`);
+            temperatureRejectedConnections.add(key);
+            return chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking);
+        }
+        if (MAX_TOKENS_REPLACED.test(err.message) && !maxCompletionTokensConnections.has(key)) {
+            warnVerbose(`[akm] LLM rejected max_tokens (${err.statusCode}); retrying once with max_completion_tokens: ${err.message}`);
+            maxCompletionTokensConnections.add(key);
+            return chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking);
+        }
         if (includeThinking && THINKING_FIELD_NAMED.test(err.message)) {
             warnVerbose(`[akm] LLM rejected chat_template_kwargs/enable_thinking (${err.statusCode}); retrying once without them: ${err.message}`);
             const fallback = await chatCompletionAttempt(config, messages, options, timeoutMs, false);
@@ -344,11 +370,15 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
         ? {}
         : { chat_template_kwargs: { enable_thinking: resolvedEnableThinking }, enable_thinking: resolvedEnableThinking };
     const reasoningEffortParams = config.reasoningEffort === undefined ? {} : { reasoning_effort: config.reasoningEffort };
+    const key = connectionKey(config);
+    const maxTokensField = maxCompletionTokensConnections.has(key) ? "max_completion_tokens" : "max_tokens";
     const requestBody = JSON.stringify({
         model: config.model,
         messages,
-        temperature: options?.temperature ?? config.temperature ?? 0.3,
-        ...(resolvedMaxTokens !== undefined ? { max_tokens: resolvedMaxTokens } : {}),
+        ...(temperatureRejectedConnections.has(key)
+            ? {}
+            : { temperature: options?.temperature ?? config.temperature ?? 0.3 }),
+        ...(resolvedMaxTokens !== undefined ? { [maxTokensField]: resolvedMaxTokens } : {}),
         ...config.extraParams,
         ...responseFormat,
         ...thinkingParams,

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.",
@@ -36842,12 +36843,16 @@ function releaseLockRaw(lockPath) {
   } catch {}
 }
 function tryAcquireLockSync(lockPath, payload) {
+  const tmpPath = `${lockPath}.tmp-${process.pid}-${randomUUID()}`;
+  fs7.writeFileSync(tmpPath, payload, { flag: "wx" });
   try {
-    fs7.writeFileSync(lockPath, payload, { flag: "wx" });
+    fs7.linkSync(tmpPath, lockPath);
   } catch (err) {
     if (err.code === "EEXIST")
       return;
     throw err;
+  } finally {
+    releaseLockRaw(tmpPath);
   }
   let snapshot;
   try {

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.",
@@ -36170,12 +36171,16 @@ function releaseLockRaw(lockPath) {
   } catch {}
 }
 function tryAcquireLockSync(lockPath, payload) {
+  const tmpPath = `${lockPath}.tmp-${process.pid}-${randomUUID()}`;
+  fs7.writeFileSync(tmpPath, payload, { flag: "wx" });
   try {
-    fs7.writeFileSync(lockPath, payload, { flag: "wx" });
+    fs7.linkSync(tmpPath, lockPath);
   } catch (err) {
     if (err.code === "EEXIST")
       return;
     throw err;
+  } finally {
+    releaseLockRaw(tmpPath);
   }
   let snapshot;
   try {