akm-cli 0.9.15-beta.3 → 0.9.15-beta.5

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

@@ -8,6 +8,36 @@ now, retry shortly." If a script or scheduler wrapper special-cases exit 2 to
 detect a held lease, switch it to exit 75, or read the JSON envelope's `code`
 field instead.
 
+A concurrent `akm index` now also exits 75 instead of exit 78 or exit 70. A
+2026-09-10 field report found a second `akm index` (no `--skip-if-locked`)
+colliding on the short internal barrier that registers the opt-in rebuild
+lock could fail with `{"code":"INVALID_CONFIG_FILE"}` at exit 78 — a
+config-error exit that told a supervisor to stop retrying ordinary
+contention between two legitimate runs. That barrier now retries briefly
+before giving up, and a busy barrier is reclassified as `TransientError`
+code `MAINTENANCE_BARRIER_BUSY` (exit 75) instead. Contention on index.db
+itself was already reclassified from a raw `database is locked` error (exit
+70) to `TransientError` code `INDEX_DB_CONTENDED` (exit 75). Either way, the
+fix for a scheduled or opportunistic index run is the same:
+`akm index --skip-if-locked` steps aside (exit 0) instead of contending at
+all.
+
+Two more contention paths collided on the same "config error instead of
+transient" anti-pattern (#948 field follow-up, 2026-09-10). `akm improve`'s
+whole-run lock (only one `improve` runs at a time) used to fail a losing
+contender with `{"code":"INVALID_CONFIG_FILE"}` at exit 78 when no
+`--skip-if-locked` was passed — a config-error exit for ordinary contention
+between two legitimate `improve` invocations. It is now `TransientError`
+code `IMPROVE_LOCK_HELD` at exit 75, naming the current holder's pid and
+start time; `--skip-if-locked` is unchanged (still exit 0). Separately, the
+index rebuild's embedding-verification step (`[index:verify] Semantic search
+verification failed: ...`) could still surface a raw, unclassified
+`database is locked` message even though the acquisition path was already
+fixed — that message is now built through the same `INDEX_DB_CONTENDED`
+reclassification as the rest of the index path. This step does not throw, so
+it does not change `akm index`'s own exit code; only the message text
+changed.
+
 The six shipped scheduled `improve` task templates now run with
 `--require-engines`, which aborts (exit 78) before any index work when a
 process's engine or credential cannot be resolved in the task's own
@@ -17,6 +47,23 @@ already-materialized task files are not rewritten. To get the same protection
 on an existing scheduled task, add `--require-engines` to its `run:` command
 yourself, then run `akm task sync`.
 
+`--require-engines` now also runs a bounded reachability probe against each
+distinct engine endpoint (the same probe `akm health` already uses), not
+only a config/credential check. A field re-test found the flag let a run
+through to a fully dead endpoint, which then sat silent for minutes making
+no progress and no exit — the flag's exit-78 abort now catches that case up
+front, naming the unreachable engine and endpoint, before any index work.
+If a scheduled `--require-engines` run starts failing at exit 78 after
+upgrading, check that the engine's endpoint actually answers — this is the
+flag doing its documented job on a condition it previously missed, not a
+new failure mode. Separately, `--timeout-ms` and an engine's own configured
+timeout already aborted an in-flight request correctly, and SIGTERM/SIGINT
+already ended a run within its documented grace period — both confirmed,
+not changed, by this investigation. A live run now also prints one
+default-level line if it waits more than a few seconds on its first engine
+response, so a slow-but-alive run and a dead one are never indistinguishable
+from silence alone.
+
 `akm health --no-probe` now also skips the `cli-version` update check (a GitHub
 release lookup), alongside the engine-reachability checks it already skipped.
 An air-gapped or offline host's existing `--no-probe` habit now suppresses both
@@ -114,6 +161,40 @@ instead of ever failing a whole batch over one oversized document.
   set `contextLength` specifically to control request batching (not your
   Ollama server's context window), set `embedding.maxTokens` instead.
 
+**Which token knob fixed the original 8k-context overflow.** A 0.9.15-beta
+field report described documents estimated under the request budget that
+still tokenized to 8.5k-12.4k real tokens against an 8192-token endpoint,
+because the 4-chars-per-token estimator undercounts dense technical text.
+`maxInputTokens`, `maxTokens`, and `contextLength` are easy to confuse, and
+only one of them makes that overflow structurally unreachable:
+
+- `embedding.maxInputTokens` (default `512`) is the per-DOCUMENT cap. It
+  truncates a document's embedded text to its head before the document is
+  ever counted toward a request, so no single document can contribute more
+  than 512 estimated tokens. This is the fix: it makes the original
+  single-document overflow structurally unreachable, independent of the
+  other two knobs.
+- `embedding.maxTokens` (default `6000`) is the per-REQUEST budget — how
+  many already-capped documents fit in one HTTP request — plus a same-run
+  adaptive shrink on the first context-size rejection. It reduces how often
+  a request lands near an endpoint's real limit, but a request-level budget
+  alone cannot stop one oversized document from overflowing a request.
+- `embedding.contextLength` sets Ollama's `num_ctx` only. It no longer feeds
+  the request token budget the way it used to (the two fields used to share
+  this one value), and it has no effect at all against a non-Ollama
+  endpoint.
+
+The field's exact 0.9.15-beta config — `contextLength: 8192` and
+`maxTokens: 8000` — produces no 400s on 0.9.15. `maxTokens` now defaults
+lower anyway (6000), but that is not why the overflow stopped: every
+document is truncated to `maxInputTokens` (512 tokens) before it is counted
+toward any request, so the 8.5k-12.4k-token documents that used to overflow
+an 8192-token endpoint can no longer reach the request budget in the first
+place. Set `embedding.maxInputTokens` higher only if you need documents
+longer than ~2000 characters embedded in full — for a corpus with such
+documents, size `embedding.maxTokens` to still fit the worst case, or the
+overflow risk returns.
+
 `akm index --full` and an index-generation bump no longer re-embed
 unchanged content: vectors about to be discarded are salvaged and handed
 back to unchanged entries at the start of the next embedding pass instead

package/docs/reference/cli.md

@@ -285,6 +285,13 @@ long enough to exhaust the driver's retry window, the run now fails with
 exit 75 (`TransientError`, code `INDEX_DB_CONTENDED`) instead of the raw
 driver error at exit 70 — the same retry-shortly contract as
 `STATE_DB_CONTENDED`, so a scheduler can branch on it instead of alerting.
+The rebuild lock itself is registered through a brief internal barrier
+(`getMaintenanceBarrierPath()`) shared with every other akm lock/lease; two
+`akm index` runs launched close enough together to collide on that
+registration step retry briefly and then, if it is still busy, also exit 75
+(code `MAINTENANCE_BARRIER_BUSY`) rather than the config-error exit 78 a
+2026-09-10 field report found — a busy registration barrier is ordinary
+contention between two legitimate runs, never a broken config file.
 `--skip-if-locked` changes that only for the invocation that passes it: if
 the lock is already held by a live process, it skips gracefully (exit 0,
 `{ ok: true, skipped: { reason: "lock-held", pid, launcherPid, startedAt } }`
@@ -2336,6 +2343,7 @@ akm improve --require-engines          # for scheduled runs: abort (exit 78) ins
 akm improve --no-sync                  # skip the end-of-run git commit entirely (default: on for git-backed bundles)
 akm improve --sync --no-push           # commit only, skip the push after it
 akm improve --plan --strategy thorough # preview thorough's resolved engine/model routing; nothing is dispatched
+akm improve lessons/my-lesson --show-prompt --format text # print the composed reflect prompt for one asset, unwrapped; no lock/index/engine call
 akm improve report                     # LLM usage/routing report for the most recent real run
 akm improve report --run <id>          # ...for one specific improve_runs id
 akm improve report --since 7d          # ...aggregated over every real run started in the last 7 days
@@ -2354,8 +2362,9 @@ akm improve report --since 7d          # ...aggregated over every real run start
 | `--require-feedback-signal` | Only process assets with recent feedback signals |
 | `--strategy <name>` | Override the active improve strategy (a built-in or entry under `improve.strategies`) |
 | `--json-to-stdout` | Also emit the full persisted JSON result on stdout for a live run. Without this flag, stdout stays empty. Dry-runs always emit their result and are never persisted. |
-| `--skip-if-locked` | If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with "already running" (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress. |
-| `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment. Without this flag, improve degrades gracefully: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
+| `--skip-if-locked` | If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with "already running" (exit 75, `TransientError`, code `IMPROVE_LOCK_HELD` — field follow-up to #948: two legitimate `improve` invocations colliding on this lock is ordinary, retryable contention, not a broken config file). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress. |
+| `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment, OR whose endpoint fails a bounded reachability probe — the same probe `akm health`'s `default-llm-engine`/`configured-engines` checks run, once per distinct endpoint. Without this flag, improve degrades gracefully: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
+| `--show-prompt` | Print the composed reflect prompt (#952) for one asset and exit — before any lock, index write, or engine dispatch. Requires a fully-qualified asset ref as the scope (`akm improve lessons/my-lesson --show-prompt`); rejected with a type or whole-bundle scope. The default output format is JSON, which carries the prompt as a `prompt` field (escaped into one line) alongside the resolved `engine`/`engineKind`; pass `--format text` to print the prompt itself, unwrapped and readable by eye. |
 | `--sync` / `--no-sync` | Commit (and optionally push) the git-backed primary bundle when the run finishes. Default: on for git-backed bundles (per profile config). |
 | `--push` / `--no-push` | Push after the end-of-run sync commit when writable with a remote configured. `--no-push` commits only, skipping the push. Default: per profile config (`true`). `sync.push` stays outside the autonomy gate — this is a per-run opt-out, not a default change. |
 
@@ -2411,6 +2420,18 @@ on an unavailable credential either — even a strategy left with every process
 disabled this way still returns its plan, with the affected processes in
 `skippedProcesses`.
 
+`--timeout-ms` is a run-wide wall-clock budget: when it expires, the run
+cooperatively aborts any in-flight engine request (the same `AbortSignal`
+every LLM call already honors) instead of waiting out the engine's own,
+much longer, per-call timeout — the run then finishes and reports normally
+rather than hanging past its budget. SIGTERM/SIGINT/SIGHUP end a live run
+the same way, within a short bounded grace period, and the process exits
+with a stable per-signal code (`143`/`130`/`129`) rather than needing a
+`kill -9`. If a live run has waited more than a few seconds without any
+engine response at all, one default-level line ("Still waiting for the
+first engine response...") is printed so a scheduled run's log is never
+silently empty while an engine is slow or dead.
+
 For dry runs, `plannedRefs` is the effective post-limit work set, not every
 ref in the requested scope. The `plan` object preserves both views: raw scope
 size and per-gate removals, configured and effective caps, final ranked refs
@@ -2452,6 +2473,17 @@ no model or per-process notices. Neither `--dry-run` nor `--plan` probes
 engine reachability over the network — pair with `akm health --probe` (or the
 default probe-on behavior) to check whether a named engine actually answers.
 
+`--show-prompt` (#952) is the cheapest way to exercise reflect alone: it
+builds the exact prompt reflect would send for one asset — the same source
+resolution, runner selection, feedback/schema-hint/related-lesson/rejected-
+proposal gathering `akm improve`'s live reflect step uses — and prints it
+without acquiring a dispatch lease, so it never calls an engine. Add
+`--format text` (the default JSON/yaml envelope escapes the prompt into one
+line, which defeats a by-eye read) to confirm by eye that recent feedback is
+framed as an unverified report to investigate (never a fact to insert
+verbatim) and that the response contract tells the model never to emit the
+truncation marker or any content from outside the shown asset.
+
 When reinforced facts need promotion, `knowledge` is the higher-authority
 destination than `memory`. The deterministic search ranking also prefers
 `knowledge` over `memory` hits, including inferred `.derived` memories, when

package/docs/reference/configuration.md

@@ -411,6 +411,40 @@ apply when unset), for a remote endpoint (`src/llm/embedders/remote.ts`):
 | `embedding.timeoutMs` | `120000` (120s) | Per-request wall timeout — see below. |
 | `embedding.concurrency` | `1` loopback / `2` remote | In-flight request window — see below. |
 
+**Which knob fixed the field's 8k-context overflow, worked examples.** A
+0.9.15-beta field report described documents estimated under the request
+budget that still tokenized to 8.5k-12.4k real tokens against an
+8192-token endpoint, because the 4-chars-per-token estimator undercounts
+dense technical text. Three knobs changed shape between beta and this
+release; only one of them makes that overflow structurally unreachable:
+
+- `embedding.maxInputTokens: 512` — per-DOCUMENT cap, applied before
+  batching. Example: a 6,000-character API reference page is truncated to
+  its first ~2,000 characters (512 estimated tokens) before it is ever
+  counted toward a request. This is the fix for the original overflow: no
+  single document can contribute more than 512 estimated tokens to a
+  request, no matter how `maxTokens` or `contextLength` are set.
+- `embedding.maxTokens: 6000` — per-REQUEST budget: how many already-capped
+  documents' estimated tokens fit in one HTTP request. Example: with the
+  default 512-token document cap, a request packs about 11 documents before
+  this budget is reached and the request is sent; if the run's first
+  request is still rejected for exceeding the endpoint's real context
+  window, akm shrinks this budget to three quarters of its value (floored
+  at twice `maxInputTokens`) for every later request in the same run. A
+  request-level budget alone cannot stop one oversized document from
+  overflowing a request — only the per-document cap above does that.
+- `embedding.contextLength: 8192` — Ollama's `num_ctx` only, forwarded
+  verbatim on a native `/api/embed` request. It has no effect on request or
+  document sizing, and no effect at all against a non-Ollama endpoint — see
+  below for why that used not to be true.
+
+A field config of `contextLength: 8192` + `maxTokens: 8000` (the exact
+0.9.15-beta values from the original report) produces no 400s on 0.9.15:
+`maxInputTokens` (512, new this release) caps every document before it is
+counted, so the original 8.5k-12.4k-token documents that overflowed the
+8192-token endpoint can never reach the request budget in the first place —
+independent of whatever `maxTokens` or `contextLength` are set to.
+
 `embedding.timeoutMs` (positive integer, default `120000` — 120s) is the
 budget for a request at the FULL token budget (`embedding.maxTokens`); a
 local model server on a large, token-budget-bounded batch legitimately takes
@@ -480,6 +514,23 @@ taking about the same wall time as a single one against a healthy endpoint.
 | --- | --- |
 | `search.graphBoost.*` | Entity-graph relevance boost: `directBoostPerEntity`/`directBoostCap` (directly related entities), `hopBoostPerEntity`/`hopBoostCap` (multi-hop, capped at `maxHops` ≤ 3), `confidenceMode` (`blend`, the only supported value), `confidenceWeight` (0–1, default `0.2`) |
 
+### Curate rerank (#951)
+
+An optional cross-encoder rerank pass over `akm curate`'s already-selected
+candidates, via a standalone `/rerank`-style HTTP endpoint (NOT one of the
+`engines.*` `"llm"`/`"agent"` kinds). Disabled by default; a misconfigured
+endpoint, network failure, timeout, or malformed response falls back to
+curate's own ranking unchanged.
+
+| Key | Purpose |
+| --- | --- |
+| `search.curateRerank.enabled` | Turn the rerank pass on (default `false`) |
+| `search.curateRerank.endpoint` | Full URL of the reranker's rerank endpoint |
+| `search.curateRerank.model` | Model name sent to the endpoint (optional) |
+| `search.curateRerank.apiKey` | `$VAR`/`secret://<name>` credential reference (optional) |
+| `search.curateRerank.timeoutMs` | Request timeout (default `10000`) |
+| `search.curateRerank.topN` | How many of curate's ranked candidates to send (default `8`, max `50`) |
+
 ## Feedback
 
 `feedback` shapes the `akm feedback` taxonomy:

package/package.json

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

package/schemas/akm-config.json

@@ -596,6 +596,34 @@
             }
           },
           "additionalProperties": true
+        },
+        "curateRerank": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "endpoint": {
+              "type": "string"
+            },
+            "model": {
+              "type": "string",
+              "minLength": 1
+            },
+            "apiKey": {
+              "type": "string"
+            },
+            "timeoutMs": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
+            "topN": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 50
+            }
+          },
+          "additionalProperties": true
         }
       },
       "additionalProperties": true
@@ -2296,6 +2324,34 @@
                 }
               },
               "additionalProperties": true
+            },
+            "curateRerank": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "endpoint": {
+                  "type": "string"
+                },
+                "model": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "apiKey": {
+                  "type": "string"
+                },
+                "timeoutMs": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0
+                },
+                "topN": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "maximum": 50
+                }
+              },
+              "additionalProperties": true
             }
           },
           "additionalProperties": true