akm-cli 0.10.261012-beta → 0.10.261014-beta

package/docs/architecture/internals/health-advisories.md

@@ -1,6 +1,6 @@
 # `akm health` advisory → action map
 
-Run `akm health` (add `--json` for machine output). The authoritative result
+Run `akm health` (JSON by default; `--format text` for the table view). The authoritative result
 combines hard failures with deterministic warnings across both output
 channels:
 
@@ -19,92 +19,53 @@ changes.
 | `state-db-schema` | state.db is missing required tables. | Re-run `akm bundle create`; a fresh/older DB was opened. |
 | `state-db-round-trip` | Append/read probe against state.db failed. | Check disk/permissions on the state.db path; the store is unwritable. |
 | `state-db-integrity` | state.db failed `PRAGMA integrity_check` (which, unlike `quick_check`, also compares every index with its table), or more than half its pages are free (reclaimable by VACUUM). | Back up state.db, then run `sqlite3 -readonly state.db ".dump" \| sqlite3 state.new.db`, verify `state.new.db` passes `integrity_check`, and swap it in; the freelist warning clears on its own on the next `akm improve` retention purge, which VACUUMs state.db above the same 50% threshold. |
-| `task-log-backing` | task_history rows reference log files missing on disk. | Logs were pruned/moved out from under the DB; safe to ignore if intentional, else restore the log dir. |
+| `state-db-readable` | `state.db` is missing or cannot be read, or is behind on migrations that a read-only run must not apply. Every other check is skipped, because none of them can read it. | Check the owner and mode of the data directory (or point `AKM_DATA_DIR` / `XDG_DATA_HOME` at one you own); run any akm command that records state, such as `akm health`, to create it. |
+| `state-db-migrations` | Reports what `akm health`'s own open of `state.db` applied (`evidence.applied`, and the copy it made first in `evidence.backupPath`); `fail` only when a pending migration could not be applied. | Run `akm migrate apply` when it names a pending migration. |
+| `task-history-read` | How many `task_history` rows were read for the window (informational; it passes). | None. |
 | `active-runs` | A task run has exceeded the stale threshold (>15 min). | Inspect with `akm task history`; a lane is likely wedged — kill/re-run it. |
-| `default-engine` | The configured general default agent, SDK, or LLM engine is missing or incomplete. | Correct `defaults.engine`; SDK operation requires the `opencode` binary on PATH (the npm SDK is an HTTP client and spawns `opencode serve`), while a fallback LLM is checked only when configured. |
-| `model-map-files` | The installed or optional user `models.json` is missing, unreadable, or invalid. | Repair the installation for an installed-map failure; remove or correct the user overlay for a warning. |
-| `selected-model-aliases` | A known selected alias lacks a mapping for its selected engine. Unknown model strings remain exact pass-through identifiers. | Add the missing alias/engine entry or select an exact model ID. |
-| `default-llm-engine` | The independently configured LLM default is missing, incompatible, lacks a required credential, or (#914) its endpoint refuses the reachability probe. | Correct `defaults.llmEngine`, its connection, any symbolic credential binding, or the endpoint itself; an unreachable default is a hard `fail`. |
-| `configured-engines` | Checks every explicitly configured engine and aggregates its deterministic availability, including (#914) reachability for `kind: "llm"` engines. | Repair engines whose safe status is `warn`; no configured engines yields `unknown`. |
-| `active-improve-strategy` | An enabled process in the effective improve strategy cannot resolve its engine or required credential; evidence and the message name the resolved engine per process (#913), surfacing a strategy-level pin that shadows `defaults.llmEngine`. Derived from the same `resolveImprovePlan` credential check the real `improve` run uses (#957), so this reflects exactly what a run in this environment would skip. `warn` when some but not all enabled LLM-backed processes are unavailable; **`fail`** (#957) when EVERY enabled `capability: "llm"` process in the strategy is unavailable — the nightly run would be a total no-op, not a partial degradation. | Inspect the named unavailable process(es), then correct its process override, strategy triage engine, SDK fallback, or default LLM. A `fail` here means `akm improve --require-engines` would abort the same run outright; add that flag to the scheduled task once the credential is fixed to make future silent no-ops fail loudly instead. |
+| `connections-and-harnesses` | One table of every configured connection (endpoint, whether its key is held — a `$VAR` set in this shell, a `credentials.json` entry, or none — and whether the endpoint answers) and harness (platform, whether its binary is on `PATH`, and with a probe its `--version`), then the work that runs on them: improve, judges, agents, extract, enrich, index, embedding and curate rerank, each naming the connection or harness and the model it resolves to through the same resolver the calls use (`evidence.rows`, typed `connection`, `harness` or `process`). `warn` when a key variable is unset, an endpoint does not answer, a harness is not installed, several connections (or harnesses) are configured and none is called `default` (said once, with the fix: name one `default`), or a work row cannot resolve because of the config; `unknown` when neither a connection nor a harness is configured; otherwise `pass`. Endpoint reachability is one bounded `GET /models` and the version is the harness's own `--version`; with `--no-probe` neither runs and the message says so. | Correct the named connection, key or harness; run `akm setup` when nothing is configured. A work row whose parts run somewhere other than the row's own target lists them in `overrides`, each with the kind (connection or harness), name and model it runs on: that is a per-process pin, working as set. |
 | `task-fail-rate` | ≥5% of scheduled task runs failed in the window (exit 143/70 recurring), or a single task_id fails at/above the same threshold. (#943) For `command`-kind (agent/LLM dispatch) failures specifically, `evidence.agentFailureReasonCounts` always carries a `detail.reason` breakdown (`timeout`, `non_zero_exit`, `spawn_failed`, …), and the warn message names the dominant reason — e.g. `(timeout-dominant: 9/12 command-task failures)` — when one reason is at least half of the counted command-task failures. | Triage as a bug: `akm task doctor`, inspect failing lane logs. For a native shell/script task, exit-143 = killed/timeout, exit-70 = internal error. For a `command`-kind (agent/LLM) task, read `detail.reason` from `akm task history` instead of the exit code — `timeout` means the dispatch's own deadline (not an outer process kill) expired; `non_zero_exit`/`spawn_failed`/`aborted`/etc. name the other failure shapes. |
 | `data-dir-usage` | The data directory is more than 3× the live databases (`state.db` + `index.db` + `logs.db`), or one top-level subdirectory holds more than half of it; the message names that subdirectory with its size and share. | Look at the named subdirectory. `backups/tasks/` holds one snapshot per `akm migrate apply` run that rewrote a task file; everything under `backups/` is yours to prune. |
+| `semantic-search` | What the last `akm index` recorded about semantic search, with the index's entry and vector counts read now; no model load, no request. `pass` when every entry has a vector (local: on `onnxruntime-node`) or `semanticSearchMode` is `off`; `warn` when vectors lag entries, local embeddings ran on another runtime, or the platform has no native ONNX Runtime library (`unavailable: platform`: Alpine/musl, Intel macOS, where keyword search is the healthy state); `fail` when the last index found it `blocked` (endpoint or model download failed) or `unavailable: load` (the library is there but did not load: a missing package or addon, a `noexec` temp or cache directory), with the reason; `unknown` before the first index. A hard check, so a `fail` fails `akm health`. | `fail`: fix the reason named, then run `akm index`; the check reads the next index's record. `warn` for the platform: set `semanticSearchMode` to `off`, or `embedding.endpoint` to a remote embedding service. |
 | `stash-git-exposure` | `env/` or `secrets/` assets are git-tracked **and** a remote is set — `git push` can leak keys. | `git rm --cached` the files, add `env/`+`secrets/` to `.gitignore` (a rule alone does not untrack). |
-| `semantic-search-runtime` | Semantic search is blocked; often a configured remote embedding endpoint is down. | Restore the endpoint, or set `semanticSearchMode` to `off`, or drop `embedding.endpoint` to use the local model. |
 | `session-extraction` | (#914) Derived from the `extract_sessions_seen` ledger for the last 7 days — not `improve_runs`, which the hook-driven `akm proposal extract --session-id ...` never writes. `unknown` when nothing was recorded; `warn` when every session in the window was skipped for an infrastructure reason (`llm_unavailable`, `read_failed`, `exception`, `locked_concurrent`), naming the reason and engine; otherwise `pass` with per-outcome counts. | An `unknown` machine may be deliberately not configured for extraction, or may have stopped harvesting — check for recent sessions. A `warn` names the broken engine/reason directly. |
-| `pool-saturation` | <2% of the session pool was new — possible discovery/dedup bug. | Verify `akm proposal extract` still finds new sessions; a healthy steady state sits above 10%. |
 | `auto-accept-validation` | Proposals passed the confidence gate but failed validation (bad frontmatter, truncation). | Review the affected pending proposals via `akm proposal list`; they were held, not lost. |
-| `outcome-proxy-adequacy` | Retrieval proxy is *inverted* (corr < −0.3): popular assets are the most-needing-improvement. | Known WS-2 limitation; no live action — see plan §WS-2 / CONTEXT before tuning. |
-| `outcome-proxy-dead` | Retrieval proxy is *dead* (\|corr\| < 0.1 at n≥500): outcome_score is noise. | **Adjudicated/expected** during the minting-shutdown re-baseline (12-D1); no action. |
-| `salience-uniformity-collapse` | Gini across all positive, resolvable retrieval-salience values is below 0.08 — ranking no longer discriminates among assets with retrieval evidence. | Inspect the reported sample size and salience freshness; run `akm index` to refresh retrieval timestamps, then let the improve schedule recompute salience before tuning weights. |
-| `enrichment-lane-minting` | Enrichment lanes minted new assets above threshold (5% warn / higher = fail). | Adjudicated against the ratified minting rules; act only if the share keeps climbing post-shutdown. |
-| `improve-churn-ratio` | Accepted proposals rewrote the same few refs (ratio > 1.5) instead of covering the corpus. | Expected while coverage is low; watch the trend, do not retune on a single window. |
-| `collapse-churn-detector` | R5 detector fired collapse/churn alerts (or `unknown` = no cycle rows yet). | Inspect recent collapse/churn cycle rows and the detector's advisory output before acting. |
-| `thinking-control` | (#949) For every configured `kind: "llm"` engine with `enableThinking: false`, checks the window's recorded `llm_usage` for reasoning tokens. Passive: never issues its own completion. `unknown` when no engine sets `enableThinking: false`, or when a configured one made no calls in the window. | A `warn` names the engine that returned reasoning tokens — its endpoint, or a gateway in front of it, is not honoring the thinking-off control. Check the gateway/endpoint config; behind a gateway that drops `chat_template_kwargs` (Bifrost), set `reasoningEffort: "none"` on the engine, which such gateways pass through. |
+| `egress-endpoints` | Every remote destination in the effective config, as one informational entry: enabled registries, git and website bundles, each connection's endpoint and the embedding endpoint (credentials in a URL are masked). Silent when nothing remote is configured. | Eyeball it against what you expect; a destination you did not configure came from an `extends` base or a shared bundle. |
+| `binary-config-skew` | `config.json` carries a `configVersion` newer than this binary knows. A newer akm wrote the shared config, so this install is stale. | Upgrade this install; do not keep a stale binary against the shared config and databases. |
+| `memory-cleanup-archive` | Size of a bundle's memory-cleanup archive. `pass` for a bundle with no git history (the purge sweep never touches it); `warn` when part of a git-backed bundle's archive cannot be purged (untracked, modified or unverifiable in git). Silent when nothing needs saying. | Commit the named files so the purge sweep can remove them once they age out. |
+| `type-directory-disagreement` | An indexed asset's resolved type disagrees with the type its directory declares. Always `warn`, never a gate; each row names the `winner` signal and marks the known-good overrides (a `knowledge/` file that is a command, an `agents/` file with an `agent:` key). | Check the unexplained rows; a deliberate override reads as such. |
+| `index-state-generation` | Durable usage links in `state.db` disagree with the current searchable index generation, which an interrupted cross-database update leaves behind. | Stop concurrent writers, then run `akm index --full` to relink state to the current index. |
 | `cli-version` | (#950) Compares the installed akm-cli version against the latest GitHub release (the same source `akm upgrade` trusts). `--probe`-gated: `unknown` "not probed" with `--no-probe`; offline/rate-limited also degrades to `unknown`, never a false `warn`. | Run `akm upgrade` when a newer release is reported. An `unknown` result carries no staleness claim either way — check manually if it matters. |
-| `engine-last-used` | (#950) For every engine bound to an enabled process in the active improve strategy, checks `llm_usage` for a call in the last 30 days (independent of `--since`). `unknown` when no engine is bound, or when no improve run has been recorded (started) in that window at all (a fresh install). | A `warn` names the idle engine and the process it is bound to. Configured, reachable, and credentialed is not the same as actually used — investigate why the bound process is not invoking it (disabled downstream, misrouted, or genuinely unused). |
 | `scheduler-binary` | (#953) Reads the scheduler's recorded akm invocation for the installed tasks (the same binding `task sync`/`task doctor` already read — no crontab/launchd/schtasks text parsing) and runs it with `--version`, compared against the running CLI's version. `--probe`-gated: `unknown` "not probed" with `--no-probe`. `unknown` when no scheduled task is installed or the recorded binary cannot be executed. | A `warn` names both versions — upgrading akm through a different installer than the one active at the last `task sync` left the schedule pointed at the old binary; run `akm task sync` to rebind it. |
-| `plugin-version` / `opencode-plugin-version` | (itlackey/akm#832,) `plugin-version` reports each installed Claude Code harness plugin's version and its declared `AKM_VERSION_RANGE` admission of the running CLI. `opencode-plugin-version` does the same for the OpenCode plugin's own bundled `akm-cli` (read from its `package.json`, never executed) — it runs in-process and shares the host's databases, so its lag matters the same way. Neither is `--probe`-gated. | A `warn` names the stale/out-of-range plugin and the update command (`claude plugin update <ref>` for the Claude plugin; update the OpenCode plugin for the bundled copy). |
+| `plugin-version` / `opencode-plugin-version` | (itlackey/akm#832,) `plugin-version` reports each installed Claude Code harness plugin's version and its declared `AKM_VERSION_RANGE` admission of the running CLI. `opencode-plugin-version` does the same for the OpenCode plugin's own bundled `akm-cli` (read from its `package.json`, never executed) — it runs in-process and shares the host's databases, so its lag matters the same way. `plugin-version`'s newest-tag lookup is `--probe`-gated: with `--no-probe` its row is `unknown` ("not probed") and only the local range check still runs. `opencode-plugin-version` reads local files only and is never gated. | A `warn` names the stale/out-of-range plugin and the update command (`claude plugin update <ref>` for the Claude plugin; update the OpenCode plugin for the bundled copy). |
 
-> Adjudicated states (`outcome-proxy-dead`, `enrichment-lane-minting`)
-> are the before/after instrument for the 12-D1 minting shutdown — do not "fix" them by retuning.
-> When in doubt, prefer no action over panic-retuning (per the review-12 guard).
+## Connections, harnesses and the work on them
 
-## Engine and model advisories
+`connections-and-harnesses` is one check with one table. A connection row names the endpoint,
+whether its key is held (never the key, nor the variable that holds it) and,
+unless `--no-probe`, whether the endpoint answers; a harness row names its platform,
+whether the binary is found and, unless `--no-probe`, what `--version` printed; a work row names
+where that kind of work runs and with which model. `akm info` prints the same
+rows without contacting anything: key held and binary found only.
 
-`selected-model-aliases` warns when a known selected alias is missing the selected engine mapping.
-It checks explicit string model selections on sorted
-configured engines against the merged installed/user model map. Unknown model
-identifiers are exact pass-through values and are not reported as missing. An
-invalid model map makes this check `unknown` with generic evidence rather than
-copying parser text or authored values.
+The work rows are resolved by the resolvers the calls themselves use, so the
+table never disagrees with a call. An unreachable endpoint is a `warn` like
+every other finding here, never a `fail`.
 
-`configured-engines` covers every explicitly configured engine. It reuses the
-same availability result as the default-engine projections and reports sorted
-safe evidence containing only engine name and status. All available engines
-pass; any unavailable engine warns; no explicitly configured engines is
-`unknown`.
+Reachability is a real, bounded (3 s) probe (#914) — one `GET` against the
+endpoint's `/models` route; any HTTP response counts, so a cold local server is
+never asked to load a model — made once per distinct endpoint per invocation
+(no cross-run cache, so a stale "reachable" verdict never lingers). Pass
+`--no-probe` to skip it (offline or air-gapped hosts): the rows then carry no
+`reachable` field and the message notes that reachability was not probed.
 
-Agent checks inspect local binary availability; SDK checks inspect the
-package/binary and any configured fallback. LLM checks (a `kind: "llm"`
-runner, and an SDK runner's LLM fallback connection) additionally send a
-real, bounded (3 s timeout) reachability probe (#914) — one `GET` against
-the endpoint's `/models` route; any HTTP response counts, so a cold local
-server is never asked to load a model — to `default-llm-engine`'s and
-`configured-engines`' endpoints, one probe per distinct endpoint per
-invocation (no cross-run cache, so a stale "reachable" verdict never lingers).
-An unreachable endpoint is a hard `fail` for `default-llm-engine` (extraction
-and improve depend on it directly) and a `warn` for every other engine that
-resolves to it. Pass `--no-probe` to skip these probes entirely (offline or
-air-gapped hosts) — every affected check then reports its prior,
-credential-only verdict and notes that reachability was not probed.
+The table's evidence names endpoints so an operator can tell which connection
+was checked; it never includes credential values or the names of the variables
+that hold them, and an endpoint's embedded credentials are masked.
 
-Engine evidence names the endpoint and model of the probed connection so an
-operator can tell which connection was checked; it never includes credential
-values or provider output.
-
-(#950) When a required `$VAR`-style credential is unavailable in the health
-process's own shell, `default-llm-engine` and `configured-engines` also check
-whether any `env/` asset defines a key by the same name. When one does, the
-`warn` message and `evidence.suppliedByEnvAsset` name the env asset's ref
-(e.g. `env/lab`) and point at `akm env run env/lab -- ...` — never the
-variable name itself, which stays out of both the message and evidence (see
-`tests/health-engine-probe.test.ts`). This is the common case where the
-operator's real workflow already supplies the credential under an `env run`
-wrapper; the check still `warn`s (the credential genuinely is unavailable in
-*this* invocation's shell), just with an actionable next step instead of a
-bare "unavailable".
-
-`akm health` makes at most two network calls, both best-effort and silent on
-failure: `plugin-version`'s `git ls-remote` (unconditional, predates
-`--probe`) and `cli-version`'s GitHub-release lookup (gated behind
-`--probe`/`--no-probe`, same flag as engine reachability). See
+`akm health` makes at most two network calls besides the endpoint probe, both
+best-effort and silent on failure and both gated behind `--probe`/`--no-probe`,
+the same flag as endpoint reachability: `plugin-version`'s `git ls-remote` and `cli-version`'s
+GitHub-release lookup. See
 `src/commands/health/plugin-staleness.ts` and
 `src/commands/health/version-drift.ts` for the discipline each follows.
-
-The salience Gini guardrails are calibrated against distribution shape, not a
-top-ranked quantile: near-uniform `0.49/0.51` scores produce about `0.01`, a
-balanced `0.25/0.75` spread produces `0.25`, and one dominant score among nine
-`0.01` scores produces about `0.82`. Read-only full-observation snapshots were
-also stable inside the neutral `0.08..0.35` band: `0.2613` across 1,209 assets
-on 2026-07-12 and `0.2506` across 1,454 non-missing assets on 2026-08-17.

package/docs/architecture/internals/improve-workflow.md

@@ -63,7 +63,7 @@ flowchart TD
             REFLECT_A[appendEvent: reflect_invoked] --> REFLECT_B[lookup ref in FTS index\nread asset file content]
             REFLECT_B --> REFLECT_C[readRecentFeedback\nbuildSchemaHints for lessons]
             REFLECT_C --> REFLECT_D[buildReflectPrompt]
-            REFLECT_D --> REFLECT_E[callStageOnce on any engine kind\nllm, agent CLI or SDK\nthe reply's JSON Schema is the output schema]
+            REFLECT_D --> REFLECT_E[callStageOnce on a connection or a harness\nthe reply's JSON Schema is the output schema]
             REFLECT_E --> REFLECT_F{reply valid?\nparseSchemaReflectOutput}
             REFLECT_F -- no, first reply --> REFLECT_R[one repair turn\nshared across refine passes]
             REFLECT_R --> REFLECT_E
@@ -187,40 +187,39 @@ flowchart TD
 
 `akmReflect` is the agent-invocation subprocess. It always emits a `reflect_invoked` event at entry, regardless of success or failure.
 
-Reflect changes only an asset's `description`, `when_to_use` and title. The engine replies with those fields (each `null` when it needs no fix), and akm applies them to the asset it read: the body is kept byte for byte, apart from a `# <title>` heading and one blank line akm inserts when the body has no level-1 heading (the only body change reflect makes). A reply that changes nothing creates no proposal.
+Reflect changes only an asset's `description`, `when_to_use` and title. The model replies with those fields (each `null` when it needs no fix), and akm applies them to the asset it read: the body is kept byte for byte, apart from a `# <title>` heading and one blank line akm inserts when the body has no level-1 heading (the only body change reflect makes). A reply that changes nothing creates no proposal.
 
 **Internal steps:**
 
 1. Emit `reflect_invoked` event via `appendEvent`.
 2. Resolve asset content: look up the ref in the FTS index; read the file if found. Index miss is non-fatal. A file in the write target that is not the one a proposal writes (`<root>/<type dir>/<name>.md`, derived from the ref) is refused here as `unsupported_type`, before any model call: a skill's `references/a.md` is the ref `knowledge/skills/<name>/references/a`, and a proposal for it would create a second file (`file_outside_layout`, #1052).
-3. Resolve the selected strategy's `reflect.engine`, falling back to `defaults.llmEngine`.
+3. Resolve where reflect runs: `improve.processes.reflect`, then `improve.connection` / `improve.harness`, then the default connection (else the default harness), asking for the `fast` model unless a layer names another.
 4. Build the reflection prompt via `buildReflectPrompt` (see Prompt shape below).
 5. Dispatch the frozen `RunnerSpec` through `callStageOnce` under the
    model-work tool policy
-   ([Engines for unattended model work](../../reference/configuration.md#engines-for-unattended-model-work)).
-   The engine may be an LLM or an agent that confines the policy, and every
-   kind runs the same iteration (`runReflectIteration`). The JSON Schema of
-   the reply (`REFLECT_JSON_SCHEMA`, or the unscoped schema when no ref was
-   given) is the request's output schema: `response_format` for an LLM, the
-   shared schema instruction at the end of the prompt for an agent (`claude`
-   also gets `--output-format json`, which akm unwraps). An agent edits only
-   its own scratch directory, so it returns the proposal as its reply, as an
-   LLM does. An LLM endpoint that rejects JSON Schema gets the framed-markdown
-   contract instead.
-6. Validate the reply with `parseSchemaReflectOutput` (`parseFramedReflectOutput` for the framed contract), which strips `<think>` blocks and code fences, then requires exactly the contract's fields: `confidence` and a `frontmatterPatch` of `description`, `when_to_use` and `title` (each a non-empty single-line string, or `null` for no change), plus `ref` when no target was given. A reply that fails gets one repair turn, shared across self-refine passes: the conversation so far, and a request to reformat the reply in the contract (`reflect-output-repair.md`). A reply still invalid fails with `parse_error` and queues nothing. A failed agent or SDK dispatch is reported as it ran, with its exit code and stderr.
+   ([Where each process runs](../../reference/configuration.md#where-each-process-runs)).
+   The runner may be a connection or a harness (with its tools restricted where
+   the harness can be), and both run the same iteration (`runReflectIteration`). The JSON Schema
+   of the reply (`REFLECT_JSON_SCHEMA`, or the unscoped schema when no ref was
+   given) is the request's output schema: `response_format` for a connection, the
+   shared schema instruction at the end of the prompt for a harness. A harness
+   is run in its own scratch directory and is asked for the proposal as its
+   reply, as a connection is. An endpoint that rejects JSON Schema gets the
+   framed-markdown contract instead.
+6. Validate the reply with `parseSchemaReflectOutput` (`parseFramedReflectOutput` for the framed contract), which strips `<think>` blocks and code fences, then requires exactly the contract's fields: `confidence` and a `frontmatterPatch` of `description`, `when_to_use` and `title` (each a non-empty single-line string, or `null` for no change), plus `ref` when no target was given. A reply that fails gets one repair turn, shared across self-refine passes: the conversation so far, and a request to reformat the reply in the contract (`reflect-output-repair.md`). A reply still invalid fails with `parse_error` and queues nothing. A failed harness dispatch is reported as it ran, with its exit code and stderr.
 7. Apply the patch (`applyReflectPatch`) to the source asset: its frontmatter with the non-null `description` and `when_to_use` set, and its body unchanged. A non-null `title` becomes a `# <title>` heading and one blank line inserted at the body's first non-blank line, in the body's line ending, only when the body has no level-1 heading; otherwise it is ignored. Leading blank lines and every other body byte are kept. A source that requires a `description` and has none gets one derived from its own text when the patch gave none (#636). A patch that changes nothing (every field `null`, or equal to the source's, and no `description` to derive) is the `no_change` outcome (`reflect_skipped_noop`), as is a source with no content to patch; a result that differs only cosmetically is `reflect_skipped_cosmetic`. Neither creates a proposal.
 8. Quality gate (`processes.reflect.qualityGate`, on unless disabled): one judge call scores the revision against the source on **need**, **preservation** and **quality** ([Quality judge](../improvement.md#quality-judge)), and passes it only when every criterion scores 4 or more. A score that does not pass is refused (`quality_rejected`, no proposal) unless its mean is 3.5 or more: that is uncertain, not bad, and the proposal is deferred for a person (`judge-uncertain`, gate `quality-gate`, with the criterion `scores` and the judge's reason) and records no rejection window. A judge that times out, errors or replies unparseably gives no verdict, and the proposal is deferred for review too (`judge-error`, gate `quality-gate`). Before the judge, with the gate on or off, reflect refuses (`quality_rejected`, no proposal, no judge call; the rule is the event's `reflectDefect`) a revision that adds placeholder text (`placeholder_added`: "please confirm", "to be confirmed"; not `TODO`, `TBD` or `FIXME`), talks about its own edit (`meta_commentary_added`: "the feedback says", "this revision") or copies frontmatter into its body (`frontmatter_copied_into_body`: `sources:` or `updated:` lines outside code, a `sources` value). Each rule counts only what the revision adds to its source (`findReflectDefect`), and its wording is a list that `processes.reflect.defectFilter` replaces or, when empty, turns off ([Configuration](../../reference/configuration.md#strategies)).
 9. Write the proposal (`mintProposal`). A pass the judge passed is stamped `staged`, and the triage drain accepts it; with the gate off the proposal is minted unstamped for the drain to decide. One made with no judge configured (`no-judge-configured`) is deferred for review (gate `reflect`), and so is one whose judge gave no verdict (`judge-error`) and one in the judge's uncertain band (`judge-uncertain`). `akm proposal list` shows the reason; the drain leaves every deferral for a person.
 
 **What it writes:** one durable proposal row in `state.db`. It never writes asset files directly.
 
-**Prompt shape (`buildReflectPrompt`):** The prompt asks the engine to check the asset's `description`, `when_to_use` and title against its body and the recent feedback signals, and to return a single JSON object `{ confidence, frontmatterPatch }`, with `ref` as well when no target was given. Each patch field is a non-empty single-line string, or `null` when it needs no fix. akm applies the patch to the source it read, so a reply names neither the target nor a body. The goal sentence is the same for every asset type. When `feedback` is empty and a ref is set, the prompt says to fix only a missing or broken field and otherwise return `null` for each. The response contract (`reflect-llm-schema-contract.md`, the same for every engine kind) requires the engine to produce only the JSON object — no prose before or after. Non-empty feedback is always preceded by a caveat (`reflect-feedback-framing.md`) framing it as a signal, not a fact to insert: change a field only when it is missing or broken, or claims more than the body covers, and then only to describe what the body covers; feedback about a task the asset never claims to cover, or asking for information the asset lacks, needs no change. Feedback claims a model treated as ground truth were fabricating whole sections asserting details the asset never contained (#952), and the caveat once offered a `TODO: verify …` placeholder, which a model inserted into a memory from a feedback line reporting that `akm show` had failed; a later distill pass then built a lesson on that line (#999). Previously rejected proposals for the ref are listed with the instruction not to propose the same change again.
+**Prompt shape (`buildReflectPrompt`):** The prompt asks the model to check the asset's `description`, `when_to_use` and title against its body and the recent feedback signals, and to return a single JSON object `{ confidence, frontmatterPatch }`, with `ref` as well when no target was given. Each patch field is a non-empty single-line string, or `null` when it needs no fix. akm applies the patch to the source it read, so a reply names neither the target nor a body. The goal sentence is the same for every asset type. When `feedback` is empty and a ref is set, the prompt says to fix only a missing or broken field and otherwise return `null` for each. The response contract (`reflect-llm-schema-contract.md`, the same for a connection and a harness) requires the model to produce only the JSON object — no prose before or after. Non-empty feedback is always preceded by a caveat (`reflect-feedback-framing.md`) framing it as a signal, not a fact to insert: change a field only when it is missing or broken, or claims more than the body covers, and then only to describe what the body covers; feedback about a task the asset never claims to cover, or asking for information the asset lacks, needs no change. Feedback claims a model treated as ground truth were fabricating whole sections asserting details the asset never contained (#952), and the caveat once offered a `TODO: verify …` placeholder, which a model inserted into a memory from a feedback line reporting that `akm show` had failed; a later distill pass then built a lesson on that line (#999). Previously rejected proposals for the ref are listed with the instruction not to propose the same change again.
 
-**Asset content cap:** the asset content section is capped to keep the prompt well under OS ARG_MAX when it travels through CLI argv (agent/SDK runners always use the flat `REFLECT_CONTENT_CAP`, 12 000 chars). The direct-LLM (`kind: "llm"`) path never touches argv, so its cap is instead computed from the resolved engine's `contextLength` (chars-per-token estimate × the reserve actually used by the rest of that prompt, measured per call rather than guessed), halved (the other half is left for the model's reply), and never dropping below the flat floor. When content is truncated, a `REFLECT_TRUNCATION_MARKER` notice is appended after the visible portion (#952).
+**Asset content cap:** the asset content section is capped to keep the prompt well under OS ARG_MAX when it travels through CLI argv (a harness always uses the flat `REFLECT_CONTENT_CAP`, 12 000 chars). A connection never touches argv, so its cap is instead computed from the resolved connection's `contextLength` (chars-per-token estimate × the reserve actually used by the rest of that prompt, measured per call rather than guessed), halved (the other half is left for the model's reply), and never dropping below the flat floor. When content is truncated, a `REFLECT_TRUNCATION_MARKER` notice is appended after the visible portion (#952).
 
 ### distill (akmDistill)
 
-`akmDistill` is the bounded in-tree LLM subprocess. It never calls `runAgent`; it issues a direct HTTP chat completion through the configured LLM endpoint. Past the process gate it emits a `distill_invoked` event carrying the outcome.
+`akmDistill` is a bounded single-call subprocess: one model call through `callStage` on the resolved runner, a direct chat completion on a connection or a run on a harness, restricted where the harness can be. Past the process gate it emits a `distill_invoked` event carrying the outcome.
 
 **Internal steps:**
 
@@ -229,8 +228,8 @@ Reflect changes only an asset's `description`, `when_to_use` and title. The engi
 3. Read feedback events via `readEvents({ ref, type: "feedback" })`. Apply `excludeFeedbackFromRefs` filtering before the LLM sees the events.
 4. Memory promotion fast path: when `proposalKind` is `"auto"` or `"knowledge"` and `assessMemoryKnowledgePromotionCandidate` returns `promote: true`, create a `knowledge:` proposal immediately without an LLM call.
    - A lesson target that already exists is not regenerated: when the stash the proposal is filed in holds a file at the lesson ref (the path accepting it would write), distill returns `skipped` with `skipReason: "lesson_exists"` and a `distill_invoked` event carrying them, before any LLM call, and mints no proposal and stamps nothing on the input. The lesson ref derives from the memory's name, so a second distill of the same memory proposes the same ref, and accepting that proposal replaces the lesson; all 5 such overwrites recorded by the 2026-10-05 review were rejected. A lesson of that name in another bundle is not an overwrite. As for any `skipped` distill, the loop records the input in the improve ledger as `unchanged`.
-5. Resolve `improve.strategies.<selected>.processes.distill.engine` (falling
-   back to `defaults.llmEngine`), then issue one bounded call.
+5. Resolve where distill runs (`improve.processes.distill`, then `improve.connection` /
+   `improve.harness`, then the default), then issue one bounded call.
    - Process gate: disabled if the selected strategy's `processes.distill.enabled` is `false`.
    - Hard timeout: 600 seconds by default, overridden by the resolved invocation timeout.
    - A timeout, an error or empty output returns an `llm_failed` result: a `distill_invoked` event with that outcome, no proposal and exit 0. It is not a ledger attempt, so the ref stays eligible. A disabled process returns `config_disabled` before any event.
@@ -238,10 +237,10 @@ Reflect changes only an asset's `description`, `when_to_use` and title. The engi
    - The writer may find no lesson: it answers the word `NONE`, or, in a reply bound to the JSON schema, `decision: "none"` after a one-sentence `reason` written first. A memory that only records what was done, shipped or decided, how a system is set up, the steps of a procedure, or a rule a related asset already states has none. distill returns `skipped` with `skipReason: "nothing_reusable"` and a `distill_invoked` event carrying it (the message holds the writer's reason), mints no proposal and makes no judge call. The loop records the input in the improve ledger as `unchanged`, as for any `skipped` distill. Before this, the prompt and both schemas forced a lesson from every memory: 18 of the 19 memories distilled on 2026-10-05 recorded what was done.
 6. Strip markdown fences and `<think>` blocks from the raw LLM output.
 7. Validate: `lintLessonContent` for lesson proposals; `validateKnowledgeContent` for knowledge proposals. Failure emits `distill_invoked` with `outcome: "validation_failed"` and throws `UsageError`.
-8. Quality gate (`processes.distill.qualityGate`, on unless disabled): one judge call, on distill's engine or the gate's own (`qualityGate.engine`), scores the lesson from 1 to 5 on **reusable**, **non-redundancy** and **grounding**. It is shown what the writer was shown: the source body the lesson was generated from (frontmatter stripped, first 3000 characters), the feedback that carries a reason or a note, and the lessons, knowledge notes and skills nearest the lesson (top 3, 600 characters each).
+8. Quality gate (`processes.distill.qualityGate`, on unless disabled): one judge call, on the gate's own connection or harness (`improve.qualityGate`, else the default), scores the lesson from 1 to 5 on **reusable**, **non-redundancy** and **grounding**. It is shown what the writer was shown: the source body the lesson was generated from (frontmatter stripped, first 3000 characters), the feedback that carries a reason or a note, and the lessons, knowledge notes and skills nearest the lesson (top 3, 600 characters each).
    - **Reusable** asks for a rule an agent can use on another occasion, with the reason it holds; 1–2 for a lesson that only records what was done, shipped, decided or is pending, or how a system is set up now.
    - **Non-redundancy** asks whether the lesson is new next to the assets listed, never the source memory (a lesson that restates its source is judged on the other two criteria); 1–2 when a listed asset already states the same rule, or most of what the lesson says in broader words; 5 when none is listed.
-   - **Grounding** asks whether every cause, step, number, rule and limit in the lesson is stated by the source or its feedback; 4–5 when each is, 3 when one stretches what the source says, 1–2 when any is in neither, when the lesson drops a limit the source states, or when it is about another subject. It is not part of the mean.
+   - **Grounding** asks whether every cause, step, number, rule and limit in the lesson is stated by the source or its feedback; 4–5 when each is, 3 when one stretches what the source says, 1–2 when any is in neither, when the lesson drops a limit the source states, or when it is about another subject. It is not part of the mean, and not part of the pass test, on purpose (#1173): adding it to the pass bar was measured on replayed judged lessons (akm-eval `distill/pass-bar`, two lab models) and only moved lessons from pass to review (6 good lessons on the 35B, 2 on the 27B). A pass and a review are both queued for a person (step 9), so what a reviewer sees is unchanged, and only the reject line (2 or below) keeps a lesson from one. See `GROUNDING_CRITERION`, `LESSON_REJECT_MAX_SCORE` and `runQualityJudge` in `src/commands/improve/stage.ts`.
    - A criterion at 2 or below is `quality_rejected` whatever the mean is (the reason names the criterion: `grounding 2/5: …`). Otherwise the lesson passes when reusable and non-redundancy both score 4 or more, and a mean of those two of 2.5 or more is `review_needed`. A pass is also queued for a person (step 9), so the rejection is the only thing that keeps a lesson from a reviewer: on 2026-10-05 the old rubric (novelty, non-redundancy, and a grounding that scored 3 for a lesson that "goes beyond the source") passed 10 of the 17 bad lessons, because a lesson that adds to its memory scored as novel. The old novelty question was also the reason the judge rejected a faithful lesson of a lesson-worthy memory. A distill with no source to read (an unindexed ref distilled "from feedback signal alone") gives the judge an empty source, so its lesson is expected to be rejected.
    - `quality_rejected` writes an `improve_ledger` row for the input (30-day distill rejection window) and a `distill_invoked` event carrying `score`, the per-criterion `criteria` and the `reason`. It mints no proposal.
    - `review_needed` mints a pending proposal stamped `deferred` / `quality-gate` for a human; the triage drain leaves it alone. It is the outcome for a non-passing mean of 2.5 or more when no criterion is at 2 or below, a judge that times out, returns something unparseable or incomplete, or is missing when the lesson or promotion is judged, and a heuristic lesson-quality finding (for example an invalid `description`), which is found before the judge is called.
@@ -377,7 +376,7 @@ duplicate, subsumed and superseding retirement, review-gated.
    pending-blocked pair is skipped entirely rather than spending any of the
    budget on a pair that cannot be judged yet.
 3. **Judge:** one LLM call per pair (`src/assets/prompts/consolidate-pair.md`)
-   through the consolidate process's own engine and concurrency. It first
+   through the consolidate process's own connection or harness and concurrency. It first
    lists the durable claims each side alone holds (`onlyInA`, `onlyInB`),
    then labels the pair one of `duplicate`, `subsumed`, `supersedes`,
    `contradicts`, `overlap` or `unrelated`. Each side is shown up to 12,000
@@ -641,13 +640,15 @@ An explicit ref scope bypasses every gate. Consolidation, extract and schema rep
 
 | Process | Config path | Controls |
 |---|---|---|
-| `distill` | `improve.strategies.<name>.processes.distill` | Enables distillation and selects its engine/model/request overrides. |
-| `consolidate` | `improve.strategies.<name>.processes.consolidate` | Enables consolidation and selects its engine/model/request overrides. |
+| `distill` | `improve.strategies.<name>.processes.distill` | Enables distillation and its tuning; where it runs is `improve.processes.distill` (connection or harness, model, request overrides). |
+| `consolidate` | `improve.strategies.<name>.processes.consolidate` | Enables consolidation and its tuning; where it runs is `improve.processes.consolidate`. |
 
 Improve process selection is resolved once by `resolveImprovePlan`; the plan
 contains every process's frozen enablement, process config, and resolved runner.
-A process runs on any engine that confines the model-work tool policy; one that
-cannot is refused when the plan is built, never replaced by another engine.
+A process runs on a connection, or on a harness: one whose tools cannot be restricted
+runs unrestricted in a scratch directory, with a notice ([How akm runs a
+harness](../../reference/configuration.md#how-akm-runs-a-harness)). A process
+with no connection or harness is skipped and reported in `skippedProcesses`.
 
 ## Output shape
 

package/docs/architecture/internals/indexing.md

@@ -6,8 +6,9 @@ By default it builds the local index and keeps metadata in the index.
 Metadata is generated deterministically (`src/indexer/passes/metadata.ts`);
 the LLM metadata-enhancement pass that used to run during indexing is
 retired (0.9.17-alpha.9, see CHANGELOG). There is no top-level `llm` config
-key in 0.9 — it is retired and hard-rejected at load; per-call tuning lives
-on each named engine under `engines.<name>.*`.
+key: it is an unknown key, named once and ignored; per-call tuning lives on a
+named connection under `connections.<name>.*` (see
+[Configuration](../../reference/configuration.md#connections)).
 
 ## High-Level Flow
 
@@ -492,7 +493,6 @@ Utility scores are rebuilt from `usage_events`.
 
 When semantic search is enabled:
 
-- semantic readiness is tracked in `semantic-status.json`
 - provider fingerprints include model/dimension for remote configs, deliberately EXCLUDING the endpoint — moving the same model+dimension to a different host does not force a rebuild
 - fingerprint changes force semantic status back to pending until a rebuild
 - vector search is an exact cosine scan of `embeddings` in JavaScript; no extension is needed

package/docs/architecture/internals/storage-locations.md

@@ -282,8 +282,10 @@ Incremental indexing cache. Directory skipped if hash + mtime unchanged.
 
 Primary key: `(asset_ref, cache_variant)`.
 
-Cache miss on effective-input change or cache-variant change. See the
-[memory-inference caching rules](../0.10-process-rules.md#memory-inference).
+Cache miss on effective-input change or cache-variant change. An unchanged
+effective input is a validated hit with no LLM call (`cacheHits`); the cached value is a derived memory
+or `{ "noChange": true }`, and an unrecognised or corrupt value falls through to a
+recompute (`src/indexer/passes/memory-inference.ts`, `src/indexer/db/llm-cache.ts`).
 Stale rows removed by
 `clearStaleCacheEntries()`. The cache can also be bypassed by internal forced
 re-enrichment callers.
@@ -332,16 +334,18 @@ explicit retention policy removes them.
 
 #### Table: `workflow_runs`
 
-New starts persist durable-v4-family plan `irVersion: 5`, the sole executable
+New starts persist durable-v4-family plan `irVersion: 8`, the sole executable
 plan format. Pre-`irVersion`-5 stored
-plans are rejected rather than upgraded or replayed through another runtime.
+plans are rejected rather than upgraded or replayed through another runtime, and
+so is any earlier plan with a model step, which froze an engine where 8 freezes a
+connection or harness.
 
 | Column | Type | Notes |
 |---|---|---|
 | `id` | TEXT PRIMARY KEY | UUID v4 |
 | `workflow_ref` | TEXT NOT NULL | e.g. `workflows/review-todos` |
-| `scope_key` | TEXT | Directory hash; isolates runs per project. Gates `list`'s default filter, `akm show`'s active-run nudge, and `startWorkflowRun`'s own-scope uniqueness guard (unchanged, still per-scope) — so two DIFFERENT scopes can each hold their own active run of the same ref; starting one warns about the other rather than blocking it (#942). `akm workflow list --all-scopes` sees across scopes, and `status`/`resume`/`abandon <run-id>` already act on a run regardless of which scope started it |
-| `workflow_entry_id` | INTEGER | Optional FK into `index.db entries.id` |
+| `scope_key` | TEXT | Legacy: a directory hash written by releases before 0.10. Never written or read now (NULL on new rows); the column and its index stay so older rows load |
+| `workflow_entry_id` | INTEGER | Legacy: an `index.db entries.id` written by releases before 0.10. Never written now (NULL on new rows) |
 | `workflow_title` | TEXT NOT NULL | Human-readable title |
 | `status` | TEXT NOT NULL | `active`, `completed`, `blocked`, `failed` |
 | `params_json` | TEXT NOT NULL DEFAULT '{}' | Run parameters |
@@ -590,6 +594,33 @@ Indexes: `idx_task_logs_ts` on `ts`, `idx_task_logs_task_id` on `task_id`, `idx_
 
 ---
 
+### `$DATA/opencode-runtime/` — akm's own runtime and its OpenCode sessions
+
+The directory akm's own agent runtime keeps everything in
+(`src/integrations/harnesses/opencode/roots.ts`, `.../runtime/command.ts`). The
+runtime is a pinned OpenCode 2 binary that akm runs as a process, and these are the
+five directories it is started with as its `XDG_CONFIG_HOME`, `XDG_DATA_HOME`,
+`XDG_CACHE_HOME`, `XDG_STATE_HOME` and `TMPDIR`: `config/` (OpenCode's own, and
+`akm-plugin/`, akm's plugin), `data/` (logs, repositories, shell output, and
+`data/opencode/opencode.db`), `cache/`, `state/` and `tmp/` (the binary's own native
+pieces, which it unpacks at start). akm creates them on the first run of the
+runtime. Beside them, `prepare.lock` is held while the first run of an OpenCode
+version prepares its database, `prepared-<version>` marks that it did, and
+`keys/` (0700) holds the connection key of each running run, one 0600 file named
+for its session, removed when the run ends.
+
+`data/opencode/opencode.db` is an OpenCode database (the OpenCode 2 layout) that
+keeps the sessions of akm's own agent runtime. It is separate from the user's own
+`opencode.db` under `$XDG_DATA_HOME/opencode` (on every platform;
+`~/.local/share/opencode` by default), which keeps the runs of the `opencode`
+harness and which akm never writes. `akm proposal extract --type opencode` and
+the improve extract stage read both with SQLite alone, read-only, and skip
+sessions that are subagents or akm's own model work (on OpenCode 2, the sessions
+that ran as the `akm-model-work` agent). The binary itself is in
+`$CACHE/opencode/<version>/`.
+
+---
+
 ## JSONL Event Streams
 
 ### `$CACHE/events.jsonl` — **Replaced by `events` table in `$DATA/state.db`**
@@ -618,7 +649,7 @@ The JSONL file at `$CACHE/events.jsonl` is no longer read or written by akm.
 | `curate` | `akm curate` | `query`, `itemCount`, `itemRefs[]` |
 | `show` | `akm show` | `type`, `name` |
 | `select` | `akm show`, when a search within the last 60s returned the ref | `query`, `searchTs`, `rankPosition` |
-| `env_access` | `akm env run`, and a workflow step's frozen environment | `keys`; `secretNames` from a workflow step (names only, never values) |
+| `env_access` | `akm env run`, and a workflow step's `env:` bindings (read at each step) | `keys` (names only, never values) |
 | `secret_access` | `akm secret run` | `var` (the variable name, never the value) |
 | `promoted` | `akm proposal accept`, and drain/triage promotion | `proposalId`, `source`, `sourceRun`, `assetPath`, `eligibilitySource`; `retired: true` for a retire proposal |
 | `rejected` | `akm proposal reject` | `proposalId`, `source`, `sourceRun`, `reason` |
@@ -687,12 +718,12 @@ One line per memory belief-state transition: `{ appliedAt, ref, parentRef, fromS
 
 | Path | Contents | Retention |
 |---|---|---|
-| `$CONFIG/config.json` | User config (bundle dirs, sources, LLM endpoints, feature flags, registries). JSONC — `//` and `/* */` comments stripped at parse time. | Manual |
+| `$CONFIG/config.json` | User config (bundle dirs, sources, connections, harnesses, feature flags, registries). JSONC — `//` and `/* */` comments stripped at parse time. | Manual |
+| `$CONFIG/credentials.json` | The API keys akm holds, as `{ "connections": { "<name>": { "key", "endpoint" } }, "services": { "embedding" \| "curateRerank": { "key", "endpoint" } } }`: each key with the endpoint it was stored for. Written atomically with mode `0600` (directory `0700` when akm creates it) by `akm setup` and `akm migrate apply`; never part of `config.json`. See [Credentials](../../reference/configuration.md#credentials). | Manual |
 | `<cwd>/.akm/config.json` | Project-scoped config overrides. Walked up to filesystem root; all ancestors merged. | Manual |
 | `$CACHE/config-backups/config-<ISO-ts>.json` | Pre-save snapshot of `config.json`, written by `backupExistingConfig()` in `src/core/config/config-io.ts` before each config write. `config.latest.json` is a second copy (not a symlink) always overwritten with the newest snapshot. Dir created/chmod'd `0700`; both the timestamped file and `config.latest.json` are chmod'd `0600` (08-F4, mirroring the env-cli write-mode convention). This is the only live backup location — legacy `$DATA/config-backups/` and `$CONFIG/config-backups/` write paths have been removed. | Capped at `MAX_CONFIG_BACKUPS = 5` most-recent timestamped snapshots; `pruneOldBackups()` deletes the rest on every write |
 | `$CONFIG/akm.lock` | Legacy location. Removed in v0.8.0 — akm reads ONLY from `$DATA/akm.lock`. Run the migration script to copy this file to `$DATA/akm.lock` before upgrading. | Legacy |
 | `$DATA/akm.lock` | Installed bundle lockfile (moved from `$CONFIG`). Application-managed install state. Same format as `$CONFIG/akm.lock`. | Managed by `akm bundle add`/`akm bundle remove` |
-| `$CACHE/semantic-status.json` | Embedding provider health: `status` (pending/ready-js/ready-vec/blocked), `reason`, `providerFingerprint`, `lastCheckedAt`, `entryCount`, `embeddingCount`. Blocked status auto-expires after 24h. | Reset on `akm index --full` |
 | `$CACHE/registry-index/<slug>.json` | Removed in v0.8.0 — data now stored in `registry_index_cache` table in `$DATA/index.db`. Delete these files after running the migration script. | — |
 | `$CACHE/registry-index/skills-sh-search-<md5>.json` | Skills.sh search result cache. Fresh 15min; stale 1d. Key = MD5 of `url + query + limit`. | TTL |
 | `$STASH/.akm/consolidate-journal.json` | Legacy consolidation journal; current advisory consolidation does not read or write it. | Dead residue (itlackey/akm#889); reported by `akm migrate status`, removed by `akm migrate apply` |
@@ -773,11 +804,12 @@ adapter recognizes — `schema.md` + `pages/` is the probe) contains:
 | Path | Contents | TTL / Retention |
 |---|---|---|
 | `$CACHE/registry/<src>/<id>/<ver>/` | Downloaded bundle packages (npm tarballs + extracted trees) | No TTL |
-| `$CACHE/registry/<src>/<id>/repo/` | Git mirror working trees for git-sourced bundles | 12h fresh; 7d stale |
-| `$CACHE/registry-index/website-<sha256-16>/` | Scraped website content as knowledge markdown files + `manifest.json` freshness marker | 12h fresh; 7d stale |
+| `$CACHE/registry/<src>/<id>/repo/` | Git mirror working trees for git-sourced bundles | None; refreshed by `akm bundle update` |
+| `$CACHE/registry-index/website-<sha256-16>/` | Scraped website content as knowledge markdown files + `manifest.json` marker that the snapshot was materialized | None; re-crawled by `akm bundle update` |
 | `$CACHE/registry-build/build-<random>/` | Temp archive extraction for registry index building | Deleted in `finally` after each run |
 | `$CACHE/tasks/logs/<task-id>/` | Per-run stdout/stderr log files (`<ISO-ts>.log`) | No cleanup |
 | `$CACHE/bin/rg` | Auto-downloaded ripgrep binary | Permanent |
+| `$CACHE/opencode/<version>/opencode` | The OpenCode binary akm's own runtime runs (about 240 MB), fetched from the npm registry on its first use | Permanent; safe to delete (fetched again) |
 | `$CACHE/index/unresolved-sources/<stash>/<name>` | Synthetic placeholder path for a configured source whose content root did not resolve this run; never written to disk, only reported as a `SearchSource.path`. Moved out of `$STASH/.akm/unresolved-sources/` (itlackey/akm#890). | N/A (not a real directory) |
 
 Cache-backed bundles (`git`, `website`, `npm`) are materialised into `$CACHE`
@@ -856,8 +888,7 @@ These paths are read by `akm improve` to scan for repeated failure patterns in a
 | Path | Agent |
 |---|---|
 | `~/.claude/projects/**/*.jsonl` | Claude Code |
-| `~/.local/share/opencode/` (Linux) | OpenCode |
-| `~/Library/Application Support/opencode/` (macOS) | OpenCode |
+| `$XDG_DATA_HOME/opencode/opencode.db` (`~/.local/share/opencode/opencode.db` by default, on every platform) | OpenCode (your own install; akm's own sessions are in `$DATA/opencode-runtime/data/opencode/opencode.db`) |
 | `$CODEX_HOME/sessions/**/rollout-*.jsonl` (`~/.codex/sessions/` by default) | Codex |
 
 ---
@@ -907,11 +938,11 @@ not affect ranking, salience, real-query labels, or GRR.
 | 2 | `$DATA/state.db` | SQLite 3 (WAL) | Durable event and usage logs, proposals, task history, and workflow run state |
 | 3 | `$STASH/.akm/memory-cleanup/belief-transitions.jsonl` | JSONL | Belief state transition audit log |
 | 4 | `$CONFIG/config.json` | JSONC | User configuration |
+| 4a | `$CONFIG/credentials.json` | JSON | API keys by connection or service, each with its endpoint (0600) |
 | 5 | `<cwd>/.akm/config.json` | JSONC | Project-scoped config overrides |
 | 6 | `$CACHE/config-backups/config-<ts>.json` | JSON | Config pre-save backups (0600 files / 0700 dir; capped at 5) |
 | 7 | `$DATA/akm.lock` | JSON | Installed bundle lockfile |
 | 8 | `$DATA/akm.lock.lck` | Text (PID) | Write-lock sentinel for lockfile |
-| 9 | `$CACHE/semantic-status.json` | JSON | Embedding provider health cache |
 | 10 | `$CACHE/registry-index/skills-sh-search-<md5>.json` | JSON | Skills.sh query result cache |
 | 12 | `$DATA/state.db` (`proposals` table) | SQLite | Proposal queue; archival is a `status` change, not a separate directory |
 | 19 | `$STASH/.akm/consolidate-backup/<ts>/<name>.md` | Markdown | Legacy consolidation backups; no longer created |
@@ -932,13 +963,15 @@ not affect ranking, salience, real-query labels, or GRR.
 | 34 | User crontab | Cron text | Linux scheduled tasks |
 | 35 | Windows Task Scheduler `\akm\<id>` | XML | Windows scheduled tasks |
 | 36 | `~/.claude/projects/**/*.jsonl` | JSONL | Claude Code session logs (read-only input) |
-| 37 | `~/.local/share/opencode/` | JSONL | OpenCode session logs (read-only input) |
+| 37 | `$XDG_DATA_HOME/opencode/opencode.db` | SQLite | OpenCode session history (read-only input) |
 | 38 | `$DATA/logs.db` | SQLite 3 (WAL) | Task/run log lines (`task_logs`); observed ~1 GB on live installs; 90d age-based purge only, not size-capped |
 | 39 | `$XDG_STATE_HOME/akm-claude/` | JSONL+Markdown+text | Claude Code plugin hook state (events, memory candidates, curated prompts, logs); written by akm-plugins, not core akm; no retention policy today |
 | 40 | `$XDG_STATE_HOME/akm-opencode/` | JSONL | OpenCode plugin hook state (events, memory candidates); written by akm-plugins, not core akm; no retention policy today |
 | 41 | `$STATE/improve/eval-cases/<stash>/<slug>.md` | FM+Markdown | Improve regression eval cases |
 | 42 | `$CACHE/index/unresolved-sources/<stash>/<name>` | N/A | Synthetic unresolved-source placeholder path (never written to disk) |
 | 43 | `$CODEX_HOME/sessions/**/rollout-*.jsonl` | JSONL | Codex session logs (read-only input; `~/.codex/sessions/` by default) |
+| 44 | `$DATA/opencode-runtime/data/opencode/opencode.db` | SQLite | Sessions of akm's own agent runtime |
+| 45 | `$DATA/opencode-runtime/`, `$CACHE/opencode/` | Directories | The OpenCode process akm's runtime runs: its working directories, and the binary |
 
 ---