akm 0.9.15 — release plan

Status: in progress 2026-09-09. Branch: release/0.9.15 (work lands via claude/0-9-15-milestone-h9huwi). Scope: the sixteen issues on the 0.9.15 milestone (#942–#957), all filed from a 2026-09-08/09 review of five akm instances. Implementation is done by Sonnet agents, one batch per git worktree; every batch diff is reviewed by the coordinator before it reaches the release branch. Nothing is pushed unreviewed.

1. What the review found, from the top

Every issue in the milestone is one of three shapes:

1. akm did the wrong thing silently. A credential form the schema accepts crashes engine dispatch (#953); an improve run with every LLM process skipped exits 0 and looks normal (#957); state.db contention surfaces as a raw driver string and exit 70 (#948); two scopes each believe a workflow ref has no active run (#942); an index rebuild that dies mid-way starts from zero because the fingerprint is only written on success (#955/#956).
2. akm already had the data and threw it away. Per-process engine/model routing is computed on every run and never shown (#947); per-call LLM usage is persisted and never cross-tabbed per run (#944); health knows which process an engine is bound to but not whether it was ever used (#950).
3. A performance or ergonomics gap with an existing precedent to copy. Embeddings are batched per request but committed once at the very end of the whole pass (#954); the thinking switch is lowered by provider name (#949); task list, show env, scheduler log growth, path discovery (#951); reflect treats feedback as fact and leaks its truncation marker (#952); a timed-out command task should be a counted failure (#943); fleet config is copied by hand (#945/#946).

The default is subtraction and reuse: every batch brief names the existing helper to extend, and every guard added has to pass AGENTS.md's three tests.

2. Decisions the coordinator made (and why)

3. Batches

Priority for merging: B, A, D, E first (correctness and reliability), then C, G, F.

4. Working agreement

• One Sonnet agent per issue, in the batch's worktree, with the issue text, the reader's code map and the coordinator's brief. Tests first. Commits are frequent and small. No agent pushes.
• Each issue diff is reviewed adversarially by a second Sonnet agent (defects, complexity, SOLID/DRY, tests that a null implementation would pass, docs); confirmed findings go back for a fix, at most two rounds.
• Each batch ends with a gate: biome, tsc, bun run lint, bun run test:unit, bun run test:integration in the worktree.
• The coordinator reads every batch diff before it is merged into the release branch, resolves conflicts between batches, and pushes. CHANGELOG entries are written as fragments under docs/plans/0.9.15/changelog/ and assembled at closeout, then the fragment directory is deleted.
• Closeout: CHANGELOG section, docs/migration/release-notes/0.9.15.md (+ README index line), package.json bump, ./tests/release-check.sh --skip-docker, push.

5. Outcome (2026-09-09)

• #954 — the originally proposed configurable embedding.concurrency was superseded by the dev-team field review before it shipped: the in-flight window shipped fixed at 1 request (loopback) / 2 requests (remote), not a config knob, with request size — embedding.batchSize and embedding.maxTokens/ contextLength — as the throughput lever instead. The 0.9.15-beta.1 field test then surfaced two further problems: the per-batch-commit claim did not hold for akm bundle update (its coordinator ran the embedding phase inside its own outer transaction, so per-batch commits nested as unobservable SAVEPOINTs), and a multi-slot local server (llama.cpp --parallel N, vLLM) was left idle by the fixed concurrency. #954 (before the stable 0.9.15) fixes both: a drift guard makes the ambient-transaction case a loud failure instead of a silent one, akm bundle update now runs the shared embedding pass on its own connection after its own commit, and embedding.concurrency (bounded 1-16) reverses the "no knob" call above, opt-in only for a server that genuinely serves parallel slots. #954 also makes embedding.timeoutMs configurable (default 120s, replacing a fixed 30s that cut off a slow local batch), adds a 3-consecutive-failure circuit breaker so a dead endpoint fails fast instead of grinding for hours, and surfaces provider/progress failures at the default log level instead of --verbose-only.
• #956 — the originally planned 30 s/10-minute interactive-vs-batch lease split was dropped: remember/import never take the asset-mutation lease in the first place (they write the asset file directly), so the premise for a shorter interactive-writer bound was wrong. The pre-existing sync lease wait (withAssetMutationLeaseSync) keeps its unchanged 10-minute bound but now prints a notice every 15 s naming the holder. Separately, the write-path index upsert skips — and reports as success — rather than waiting, whenever the new rebuild lock is held during a live rebuild.
• #957 — a workflow agent working #947 hit a pre-existing #957 regression (--dry-run's all-disabled guard threw when every process was credential-unavailable, even though a dry run never dispatches), filed GitHub issue #958 against it, and left the characterization test .skip-ped per AGENTS.md's explicit-skip-with-linked-issue rule so the #947 batch could land green. The coordinator reversed that deferral: the regression is fixed in this release (--dry-run/--plan never abort on an unavailable credential; the preview reads the resolved engine/model/ context-length metadata a credential-unavailable process still carries via EngineUnavailableProcess's engine/model/contextLength fields), the characterization test is restored with updated assertions, and #958 can be closed by its owner as fixed.
• #948 — RUN_LEASE_HELD and the new STATE_DB_CONTENDED both exit 75 (EX_TEMPFAIL), not 2, per the field review — schedulers read exit 2 as "fix the command line," not "retry shortly."
• #949 — both thinking-control wire forms (chat_template_kwargs .enable_thinking and bare enable_thinking) are sent only when enableThinking resolves to a value, whether from the engine's own config or a calling process's per-call override — not gated on provider any more. reasoning_effort is sent whenever it is set on the engine, unconditionally.
• #955 — vector identity is keyed on the endpoint's reported response model plus the observed vector width (not a config string or /models hash), and the fingerprint-rename canary re-embeds a cosine-similarity sample before any rebuild. A field-review addendum refined the verdict rule: a sample whose canary re-embed failed is excluded from the median rather than scored as zero, and when half or fewer of the sampled entries verify, the outcome is unverifiable rather than trusting a too-thin sample either way.
• #955 — pulled forward from a later milestone on 2026-09-09, alongside #954 (both land via the same "embed" worktree/ batch, #954 first). Embedding salvage across full rebuilds and index- generation bumps: vectors about to be discarded wholesale are copied into a transient embedding_salvage table (keyed by sha256(search_text) plus the fingerprint they were generated under) in the same transaction as the discard, and the next embedding pass hands them back to unchanged entries before any provider call — so the 0.9.14 v22→v23 bump's multi-hour re-embed does not recur on akm index --full or a future generation bump. --reembed and a canary "rebuild" verdict still purge everything; a canary "keep" verdict relabels leftover salvage to the new fingerprint string instead of discarding it.

Batches (all merged)

Deferred / open

• #951 — a rerank engine kind is deferred to its own issue; this release only removed the false --rerank documentation claims.
• #952 — the issue's confidence-gate claim does not match the code that shipped; documented in the reflect batch's coordinator brief rather than re-litigated here.
• #943 — the issue's original premise (timeout/killed command tasks not counted as failures) was not reproduced; static reading found the underlying failure propagation was already correct. The fix that shipped is the task-fail-rate health evidence/keys line (agentFailureReasonCounts and the "timeout-dominant" suffix), pinning that contract with a regression test instead of leaving it implicit.