akm-cli 0.9.28-alpha.1 → 0.9.28-alpha.10

package/CHANGELOG.md

@@ -6,6 +6,182 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.28-alpha.10] - 2026-10-08
+
+### Fixed
+
+- **An `opencode-sdk` dispatch no longer hangs when OpenCode asks for a permission (#1104).** The runner never
+  answered permission requests, so a tool call that needed one (OpenCode's default `external_directory: ask`,
+  e.g. reading the plugin's `/tmp/akm-opencode/curated/<session>.md`) stayed `running` until the dispatch
+  timed out. The runner now rejects each request of its session, and of the sub-sessions it spawns, exactly as
+  a non-interactive `opencode run` does ("auto-rejecting"), so the model gets a refusal it can work around;
+  each request is recorded in the dispatch's `stderr`, and the event subscription is closed when the dispatch
+  ends. Grant access in the agent's `permission` config to allow it instead.
+
+## [0.9.28-alpha.9] - 2026-10-08
+
+### Fixed
+
+- **The `opencode-sdk` server receives `OPENCODE_API_KEY` and `OPENCODE_CONFIG`.** It was started with only the
+  common baseline and the XDG names, so a provider that reads its key from the environment (OpenCode Go) failed
+  with `UnknownError: Unexpected server error` where `opencode run` worked. The `opencode` CLI profile and the
+  SDK server now share one list of OpenCode names; a different key value starts another server.
+
+- **`akm upgrade --next` no longer fails OpenCode as "older than `@latest`" (#1089).** akm-plugins' stable
+  versions concatenate a timestamp into the patch (`0.9.27202610072331`), so by semver every prerelease build
+  (`0.9.28-alpha.8.202610081938`) sorted below stable and `akm-opencode@next` was always rejected. `@next` is
+  now judged by the `akm-cli` it pins against the one `@latest` pins; plugin versions are only compared for
+  equality (is the cache already this build?).
+
+## [0.9.28-alpha.8] - 2026-10-08
+
+### Fixed
+
+- **`opencode-sdk` runs keep their OpenCode session (#1100).** The SDK runner deleted the session after every
+  dispatch, so a workflow, task or `akm agent` run left no transcript in OpenCode's history to debug or to learn
+  from, unlike `opencode run`. The session is now kept; a dispatch akm gives up on (timeout or abort) is still
+  aborted on the server so it stops calling the model. The OpenCode session id is on the `akm agent` / command
+  result as `sessionId` and in the task log line, as workflow steps already carried it.
+
+## [0.9.28-alpha.7] - 2026-10-08
+
+### Added
+
+- **An agent engine can name a default `agent`.** `engines.<name>.agent` (`opencode`, `opencode-sdk`, `claude`)
+  is the native agent the engine runs when a request names none, so an `opencode-sdk` engine, which takes no
+  `args`, can run e.g. `akm-workflow` for workflows and tasks. A request's own agent wins, a persona is kept,
+  and model work keeps its confined agent. See [Configuration](docs/reference/configuration.md) (#1049).
+
+### Changed
+
+- **Stability tiers for 0.10's stabilization work.** Experimental: the built-in
+  improve strategies other than `default` and `consolidate` (`quick`,
+  `reflect-distill`, `thorough`, `catchup`), the proactive-maintenance and
+  high-salience lanes, and session extraction (`akm proposal extract`).
+  Evolving and now listed: `akm command run` and `akm models`; every agent
+  harness (the `opencode` CLI path, `copilot`, `pi`, `gemini`, `aider`,
+  `amazonq`, `openhands` included) and the `okf`, `llm-wiki` and
+  `generic-files` adapters are named Evolving. `akm upgrade`'s plugin step and
+  `--next` are targeted to become Stable before the 0.9 series ends.
+
+- **Workflows are Experimental.** The `akm workflow` commands (`run`, `status`,
+  `list`, `create`, `resume`, `abandon`, `plan`), the workflow asset format and
+  the engine move to Experimental in STABILITY.md and the help text, for the rest
+  of 0.9 and all of 0.10, which stabilizes the feature and then promotes it or
+  removes it. Nothing changes in how they run.
+
+### Fixed
+
+- **Consolidate's pair pass no longer retires a knowledge note in favour of a memory (#1092).** Knowledge is the
+  reviewed form and a memory is raw capture, often the very memory the note was promoted from, yet a `duplicate`,
+  `supersedes` or `subsumed` verdict could retire `knowledge/...` for `memories/...` (a `.derived` memory counts as a
+  memory). When the verdict would do that and the judge lists no claim held only by the memory, the memory is retired
+  in favour of the note instead, through the same guards and staging as any memory retirement; when the memory holds
+  a claim of its own, nothing is minted and the pair is counted as a no-action verdict. A memory is still retired in
+  favour of a knowledge note, and knowledge against knowledge is unchanged.
+
+## [0.9.28-alpha.6] - 2026-10-08
+
+### Fixed
+
+- **The #1063 fix now reaches files that have not changed (#1063).** An incremental `akm index` skips a
+  directory whose files are unchanged, so a reference file already filed as a command stayed
+  `commands/skills/<name>/...` until `akm index --full`. The `akm` adapter's version, which is part of each
+  directory's freshness, is bumped, so the next `akm index` after upgrading re-files those rows once (about 18
+  entries in a 18,000-entry library) and drops their old refs. Reading every directory once makes that run slower
+  (about 27 s against 2 s on that library) and re-embeds the entries whose embedding hash was written by an older
+  release (about 8,000 of them); later runs cost what they did before.
+
+## [0.9.28-alpha.5] - 2026-10-08
+
+### Added
+
+- **`akm upgrade --next` installs the `@next` prerelease of akm and its OpenCode plugin.** The CLI target is
+  the `next` dist-tag of `akm-cli` when it is newer than the latest stable release, else the stable release
+  (never a downgrade); npm/Bun/pnpm installs name that exact version and binary installs take its GitHub
+  release. The OpenCode lockstep and cache refresh follow `akm-opencode@next` when the OpenCode config's
+  `plugin` list names it (akm never edits that config); with a bare `"akm-opencode"` the entry is `skipped`
+  with a message saying to set `"plugin": ["akm-opencode@next"]`, and lockstep stays on the `@latest` pin.
+  Missing, older-than-`@latest` or unpinned `@next` fails closed like the stable lockstep. Claude Code and
+  Codex are unchanged (no prerelease channel). The result gains `channel`. Works with `--check`, `--force`
+  and `-q`. See [`akm upgrade`](docs/reference/cli.md#prereleases-next).
+
+## [0.9.28-alpha.4] - 2026-10-08
+
+### Added
+
+- **`akm upgrade` also updates the akm plugin of each installed harness (#1007).** After the CLI step
+  it refreshes Claude Code (`claude plugin marketplace update`, then `claude plugin update`) and
+  Codex (`codex plugin marketplace upgrade`) when the `akm-plugins` marketplace is configured and the
+  plugin is installed, and replaces a stale cached `akm-opencode` (moved to the trash, then re-fetched
+  by `opencode debug config`) unless OpenCode is running, in which case it is `deferred`. It only
+  updates: a missing plugin is never installed. The result gains `plugins` (one `outcome` per harness:
+  `updated`, `current`, `skipped`, `deferred`, `failed`; under `--check`, which changes nothing,
+  `pending` for OpenCode and `unknown` for Claude Code and Codex, whose check needs a fetch) and a failed plugin exits 1. With the OpenCode plugin present the CLI moves to the akm-cli
+  that `akm-opencode@latest` pins instead of the newest release, reported under `lockstep`; if the pin
+  cannot be read the CLI is held where it is rather than moved ahead of the plugin. The
+  Containers entrypoint and the Codex hook trust entries are documented under
+  [`akm upgrade`](docs/reference/cli.md#upgrade).
+
+### Fixed
+
+- **A skill's reference file with a shell `$1` is no longer indexed as a command (#1063).** A file under
+  `skills/**` other than `SKILL.md` that showed `local var="$1"` in a code block was retyped to
+  `commands/skills/<name>/...`. A skill's folder now counts as a declared context, as `memories/` and the other typed
+  directories already did, so the file stays a skill resource (`knowledge/skills/<name>/...`). A `$1` under
+  `commands/` or in a loose file is still a command.
+
+## [0.9.28-alpha.3] - 2026-10-08
+
+### Changed
+
+- A consolidate pair-pass retire proposal now records the judge's claim lists in its `retirement` metadata as `onlyInRetired` and `onlyInSuccessor`, named by role rather than by the judge's A/B, so what the judge found only on each side survives past the run. Proposals minted before this lack both fields; no row is added for a pair akm keeps.
+
+- A distill lesson the quality gate rejects or sends to review now keeps its text: the `distill_invoked` event and the distill result carry `rejectedContent`, cut to 2000 characters (the judge prompt's cap). Before, a rejected lesson left only its score and reason. It stays local in `state.db`.
+
+## [0.9.28-alpha.2] - 2026-10-08
+
+### Added
+
+- **`akm metrics` (experimental) reports what akm has recorded, in every `--format`.** One
+  read-only command covers asset usage (searches, shows, curates, selects, the
+  queries that returned nothing), feedback with its reasons and tags, utility
+  and outcome scores, LLM tokens, latency, task runs,
+  proposals and workflow token spend. `--since` (default `30d`) sets the window start; the window ends now, counts
+  `user`-source usage and keeps the top 20 of every ranked list. The
+  window rows (usage rows as recorded, LLM calls summed per day, engine, model, process and stage) ride along with
+  `--format html` and `--detail full`. A window
+  longer than a store's retention says so in `notes`.
+
+- **`akm metrics` renders as text and Markdown.** `--format text` prints aligned
+  Usage, Feedback, Utility, LLM, Index, Tasks, Proposals and Workflows sections
+  with top-N tables (cut to 5 at `--detail brief`); `--format md` prints one
+  heading per section with GFM tables.
+
+- **`akm metrics --format html` writes a self-contained dashboard.** The page
+  carries the window's raw rows, so you can filter by date, bundle, source and
+  event type, sort the tables, open an asset to see its timeline, queries and
+  feedback, and download any table as CSV, all in the browser. Charts load
+  ECharts from the same CDN tag as `akm health --report`. A page keeps the most
+  recent 50,000 usage rows and says so when it cuts older ones.
+
+### Changed
+
+- **LLM usage is recorded for every command.** `akm index`, curate, workflow,
+  agent dispatch and `akm command run` now persist their `llm_usage` events
+  like `improve` and `proposal drain` already did; before, a call made outside
+  those two was dropped. An improve run still keeps its own sink and the
+  process-wide one resumes when it ends.
+
+- Search latency is recorded in the search summary usage row (`totalMs`, plus `rankMs` and `embedMs` when present), and every `akm index` run appends an `index_completed` event with its phase timings.
+
+### Fixed
+
+- **Usage-event retention no longer deletes a day early.** The purge on `akm index`
+  compared the space-separated `created_at` against an ISO cutoff, so every row on
+  the cutoff's date was removed up to 24 hours before its 90 days were up. Both
+  sides are now normalized before the comparison.
+
 ## [0.9.28-alpha.1] - 2026-10-08
 
 ### Fixed

package/STABILITY.md

@@ -46,6 +46,7 @@ enumeration of the whole `proposal` noun group.
 | `akm setup` | Stable | |
 | `akm index` | Stable | |
 | `akm health` | Evolving | Exit codes are Evolving; report *content* and rendered `md`/`html` layout are Experimental — do not script against report layout. |
+| `akm metrics` | Experimental | New in 0.9.28. Report content, JSON shape and the `html` dashboard may change. |
 | `akm info` | Stable | |
 | `akm bundle create` | Stable | |
 | `akm bundle add` | Stable | |
@@ -53,17 +54,17 @@ enumeration of the whole `proposal` noun group.
 | `akm bundle show` | Evolving | See note above. |
 | `akm bundle remove` | Stable | |
 | `akm bundle update` | Stable | |
-| `akm upgrade` | Evolving | |
+| `akm upgrade` | Evolving | The plugin step and `--next` (0.9.28) are being verified on real hosts to become Stable before the 0.9 series ends. |
 | `akm search` | Stable | |
 | `akm curate` | Stable | |
 | `akm show` | Stable | |
-| `akm workflow status` | Stable | `--all-scopes` added in 0.9.15 (#942), additive. |
-| `akm workflow plan` | Evolving | New in 0.9.2; secret-free provenance output; envelope shape may change. |
-| `akm workflow list` | Stable | `--all-scopes` and a top-level `scopeKey` envelope field added in 0.9.15 (#942), both additive. |
-| `akm workflow create` | Stable | |
-| `akm workflow resume` | Stable | |
-| `akm workflow abandon` | Stable | |
-| `akm workflow run` | Stable | Canonical start/resume/execute command. |
+| `akm workflow status` | Experimental | `--all-scopes` added in 0.9.15 (#942), additive. |
+| `akm workflow plan` | Experimental | New in 0.9.2; secret-free provenance output; envelope shape may change. |
+| `akm workflow list` | Experimental | `--all-scopes` and a top-level `scopeKey` envelope field added in 0.9.15 (#942), both additive. |
+| `akm workflow create` | Experimental | |
+| `akm workflow resume` | Experimental | |
+| `akm workflow abandon` | Experimental | |
+| `akm workflow run` | Experimental | Canonical start/resume/execute command. |
 | `akm remember` | Stable | |
 | `akm import` | Stable | |
 | `akm sync` | Stable | |
@@ -82,6 +83,8 @@ enumeration of the whole `proposal` noun group.
 | `akm feedback` | Stable | |
 | `akm log` | Evolving | |
 | `akm agent` | Evolving | |
+| `akm command run` | Evolving | Runs stored command templates through the same agent dispatch as `akm agent`. |
+| `akm models` | Evolving | `list` and `copy-defaults` for model intent aliases. |
 | `akm lint` | Evolving | |
 | `akm improve` | Evolving | Review-first by default; mutating lanes require `experimental.improveAutonomy` — see below. |
 | `akm proposal list` | Stable | See reconciliation note above. |
@@ -92,7 +95,7 @@ enumeration of the whole `proposal` noun group.
 | `akm proposal reopen` | Evolving | New in 0.9.19; undoes a rejection. |
 | `akm proposal revert` | Evolving | |
 | `akm proposal drain` | Evolving | |
-| `akm proposal extract` | Evolving | Former top-level `akm extract`. |
+| `akm proposal extract` | Experimental | Former top-level `akm extract`. Session extraction quality is still being measured (0.10, #1094). |
 | `akm proposal new` | Evolving | Former top-level `akm propose`. |
 | `akm help` | Stable | |
 | `akm help agents` | Stable | |
@@ -290,9 +293,8 @@ CHANGELOG with a migration note.
 - **Workflow plan** — `akm workflow plan <ref>`, new in 0.9.2: zero-write
   compile+freeze introspection (the canonical step graph, task/child
   expansion, input bindings, and lowering notices for a workflow, without
-  starting or publishing a run). The envelope shape may still change; the
-  five long-Stable `workflow` verbs (`status`, `list`, `create`, `resume`,
-  `abandon`) and `run` are unaffected.
+  starting or publishing a run). The envelope shape may still change. Like every
+  `workflow` verb it is Experimental from 0.9.28 (see Experimental below).
 - **Events / log** — `akm log` is the event-stream surface (0.9.0: the
   asset-scoped `akm history` surface, and `log`'s own `tail` subcommand, were
   both removed; `log` is now a leaf command — the former `list` surface).
@@ -301,7 +303,8 @@ CHANGELOG with a migration note.
   commands/agents, knowledge, YAML workflows, tasks, env/secret files, scripts,
   OKF and LLM-wiki knowledge bases). Config is keyed by `bundles` and
   `defaultBundle`. The adapter set, bundle-recognition rules, and the
-  `bundles` config shape may still shift. Bundles are inspected through
+  `bundles` config shape may still shift; the `okf`, `llm-wiki` and
+  `generic-files` adapters in particular are Evolving. Bundles are inspected through
   `akm bundle list` / `akm bundle show <name>` and enumerated through
   `akm search "bundle//"`. (An earlier `akm bundle items` noun group was
   removed in 0.9.0 as duplicative of `akm search`; the current `akm bundle`
@@ -317,9 +320,15 @@ CHANGELOG with a migration note.
   `log.md` / `raw/` / `pages/` and its ingest flow); wiki pages are addressed
   as ordinary concepts inside their bundle. Adapter behavior and page
   conventions are still iterating.
-- **Agent dispatch** — `akm agent` subcommand. Supported backends: `claude`,
-  `opencode`, `opencode-sdk`, `codex`, `copilot`, `pi`, `gemini`, `aider`,
-  `amazonq`, `openhands`. The set will grow.
+- **Agent dispatch** — `akm agent` and `akm command run`. Supported backends:
+  `claude`, `opencode-sdk` (the primary OpenCode interface), `codex`, and the
+  `opencode` CLI path, `copilot`, `pi`, `gemini`, `aider`, `amazonq`,
+  `openhands`. Every harness is Evolving: the harness implementation is being
+  reworked so harnesses are easy to add, remove and update (0.10), and the
+  `opencode` CLI dispatch path is a deprecation candidate once `opencode-sdk`
+  covers it. The set will grow.
+- **Model aliases** — `akm models list|copy-defaults` and the intent-alias
+  defaults they expose.
 - **Proposal queue** — quality classifications (`accepted`, `pending`,
   `proposed`, `rejected`, `archived`) are stable; the JSON shape of a
   proposal record may add fields.
@@ -329,7 +338,9 @@ CHANGELOG with a migration note.
   lives outside the CLI, in `scripts/build-registry-index.ts`.
 - **Upgrade** — `akm upgrade`. Checksum verification is not optional; the
   recovery hatch is the `AKM_UPGRADE_SKIP_CHECKSUM` environment variable
-  (Internal), not a flag.
+  (Internal), not a flag. The harness plugin step and `--next` (new in 0.9.28)
+  are targeted to become Stable before the 0.9 series ends, once verified on
+  real hosts.
 - **Lint** — `akm lint`. The rule set and finding shapes iterate; the
   `--fail-on-flagged` CI contract and the exit codes are stable.
 - **Health** — `akm health` and its exit codes (0 pass / 4 warn / 1 fail) are
@@ -341,6 +352,15 @@ CHANGELOG with a migration note.
 Subject to change without notice within minor releases. Not yet recommended
 for scripted use.
 
+- **Workflows** — the whole `akm workflow` surface (`run`, `status`, `list`,
+  `create`, `resume`, `abandon`, `plan`), the workflow asset format and the
+  workflow engine are Experimental from 0.9.28 and throughout 0.10. The 0.10
+  series stabilizes the feature and trims what is not useful, then either
+  promotes it out of Experimental or removes it if stabilization does not
+  produce a quality feature.
+- **`akm metrics`** — new in 0.9.28. What it reports, its JSON shape and the
+  `--format html` dashboard may change in any release; do not script against
+  them.
 - **`lesson` asset type** — schema (`when_to_use`, `description`) is
   stable, but lesson-distillation triggers and ranking are tuning targets.
 - **`--shape agent` and `--shape summary`** — the output-projection axis
@@ -357,6 +377,13 @@ for scripted use.
 - **Memory belief-state transitions** — `captureMode`, `beliefState`,
   contradiction edges, and the consolidate journal are observable but
   the algorithm that writes them is tuning across patch releases.
+- **Improve built-in strategies and lanes** — the built-in strategies other
+  than `default` and `consolidate` (`quick`, `reflect-distill`, `thorough`,
+  `catchup`) and the proactive-maintenance and high-salience lanes. 0.10
+  measures each and keeps, folds or removes it (#1094).
+- **Session extraction** — `akm proposal extract` and the `extract` process:
+  what it extracts, its quality gates and its output may change while 0.10
+  measures it (#1094).
 - **Improve tuning config** — `improve.strategies.*.processes.*` (per-process
   engines, limits, gates, and the anti-collapse / CLS / fidelity knobs) and
   the `index.*` per-pass config. The 0.9.x series is explicitly still settling

package/dist/assets/hints/cli-hints-full.md

@@ -329,8 +329,9 @@ akm bundle list                                      # List all sources
 akm lint                                      # Structural lint over the bundle; exits 0 regardless of findings
 akm lint --fix                                # Auto-fix Tier 1 issues
 akm lint --fail-on-flagged                    # Exit non-zero when summary.flagged > 0 (CI-friendly)
-akm upgrade                                   # Upgrade akm using its install method
-akm upgrade --check                           # Check for updates
+akm upgrade                                   # Upgrade akm using its install method, then update installed harness plugins
+akm upgrade --check                           # Report pending CLI and plugin updates, changing nothing
+akm upgrade --next                            # Follow prereleases (@next); OpenCode needs "akm-opencode@next" in its plugin list
 akm help migrate 0.6.0                        # Print migration notes for a release (or: latest)
 akm help bundle                               # Print options and subcommands for one command
 akm help agents --full                        # Print this reference
@@ -416,6 +417,9 @@ akm agent --model sonnet --prompt "..."         # Model override (aliases or exa
 akm info                                       # Capabilities, bundle dir, index stats, semantic-search status
 akm health                                     # Runtime diagnostics; exit 0 ok / 4 warn / 1 fail
 akm health --report                            # Adds accept-rate metrics
+akm metrics                                    # Usage, feedback, utility, LLM tokens, tasks, workflows (last 30d, read-only)
+akm metrics --since 7d                         # Narrow the window
+akm metrics --format html --output metrics.html # Self-contained dashboard with the window's rows (filter, sort, export CSV)
 akm log                                        # Append-only event stream (mutations, feedback, indexing)
 akm log --ref <ref>                            # One asset's event trail
 akm log --since @offset:<id>                   # Durable row-id cursor — poll this to follow the stream

package/dist/assets/hints/cli-hints-short.md

@@ -47,6 +47,7 @@ akm clone <ref>                               # Copy an asset to the working bun
 akm sync                                      # Commit (and push if writable remote) changes in the primary bundle (--no-push to commit only)
 akm improve --no-sync                         # Run improve without the end-of-run auto-commit
 akm improve --no-push                         # Auto-commit but skip push for this run
+akm metrics --since 7d                        # What was searched, shown and rated, and which assets went unused (--format html: dashboard)
 akm search "<query>" --from registry          # Search all registries (registry search was folded into search)
 ```