akm-cli 0.10.261019 → 0.10.261021

package/dist/workflows/exec/param-secrets.js

@@ -38,10 +38,36 @@ function keyLooksSecret(key) {
     const lower = key.toLowerCase();
     return SECRET_KEY_HINTS.some((hint) => lower.includes(hint));
 }
+/**
+ * Unix (`/`, `./`, `../`, `~/`) or Windows (`C:\`, `\\server`) filesystem path,
+ * or a bare relative path whose last segment carries a file extension
+ * (`reports/2026-10-30/summary.md`). Base64 never contains `.`, so the
+ * extension keeps slash-bearing base64 blobs on the whole-string check.
+ */
+const PATH_LIKE = /^(\/|\.{1,2}[\\/]|~[\\/]|[A-Za-z]:[\\/]|\\\\)|^[\w.-]+[\\/][^?#]*\.[A-Za-z0-9]{1,8}$/;
+/** A canonical UUID — an ordinary run/session directory name, not a credential. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Whether one path segment or query piece looks like a credential: a known
+ * prefix, a secret-named query key (`token=...`), or a long unbroken token
+ * (hex/base64 run, or mixed case with digits).
+ */
+function segmentLooksSecret(seg) {
+    if (SECRET_VALUE_PREFIX.test(seg))
+        return true;
+    const eq = seg.indexOf("=");
+    if (eq > 0 && keyLooksSecret(seg.slice(0, eq)) && seg.length - eq > 8)
+        return true;
+    if (seg.length >= 32 && !UUID.test(seg) && /^[A-Za-z0-9+_=-]+$/.test(seg) && /\d/.test(seg) && /[a-zA-Z]/.test(seg))
+        return true;
+    return seg.length >= 20 && /^[A-Za-z0-9]+$/.test(seg) && /[a-z]/.test(seg) && /[A-Z]/.test(seg) && /\d/.test(seg);
+}
 /**
  * A string value is secret-shaped when it is long, whitespace-free, and either
  * carries a known credential prefix or has high character-class diversity /
- * base64-hex shape — an entropy proxy, not a real entropy computation.
+ * base64-hex shape — an entropy proxy, not a real entropy computation. A
+ * filesystem path is judged per segment instead, so separators, dates and
+ * digits do not count as diversity.
  */
 function valueLooksSecret(value) {
     const s = value.trim();
@@ -49,6 +75,8 @@ function valueLooksSecret(value) {
         return false;
     if (SECRET_VALUE_PREFIX.test(s))
         return true;
+    if (PATH_LIKE.test(s))
+        return s.split(/[/\\?&#]/).some(segmentLooksSecret);
     const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^A-Za-z0-9]/].filter((re) => re.test(s)).length;
     if (s.length >= 24 && classes >= 3)
         return true;

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

@@ -34,7 +34,7 @@ harness's `--version`, looks up the latest akm release on GitHub for `cli-versio
 Claude plugin is installed. With
 `--no-probe` none of these runs: the connection rows carry no `reachable` field and the
 message says reachability was not probed, and `plugin-version` reports `unknown` (its
-`AKM_VERSION_RANGE` check is local and still runs). The `plugin-version` and `cli-version`
+`AKM_MIN_VERSION` (or legacy `AKM_VERSION_RANGE`) check is local and still runs). The `plugin-version` and `cli-version`
 lookups are best-effort and silent on failure; see `src/commands/health/plugin-staleness.ts`
 and `src/commands/health/version-drift.ts`.
 
@@ -56,13 +56,13 @@ and `src/commands/health/version-drift.ts`.
 | `cli-version` | `warn`: a newer akm release exists on GitHub. `unknown`: `--no-probe`, or the release lookup failed. | Run `akm upgrade`. |
 | `scheduler-binary` | `warn`: the akm binary recorded in the scheduler reports a different version than the running CLI. `unknown`: `--no-probe`, no scheduled task installed, or the recorded binary cannot be run. | Run `akm task sync` to rebind the schedule. |
 | `index-state-generation` | `warn`: usage links in state.db point at index entries that no longer match (an index and state.db from different generations). | Stop concurrent writers and run `akm index --full`. |
-| `stash-git-exposure` | `warn`: `env/` or `secrets/` files are tracked by git in the working bundle and the bundle has a remote. Skipped when the bundle has no `.git`. | Run `git rm --cached` on the listed files and add `env/` and `secrets/` to `.gitignore`. A `.gitignore` rule alone does not untrack files. |
+| `stash-git-exposure` | `warn`, one per bundle: `env/` or `secrets/` files are tracked by git in a configured bundle (the working stash included) and that bundle has a remote. Skipped for a bundle with no `.git` at its root. | Run `git rm --cached` on the listed files and add `env/` and `secrets/` to `.gitignore`. A `.gitignore` rule alone does not untrack files. To keep tracking them on purpose, add `# akm: intentionally track env and secrets` to the stash `.gitignore`; the advisory is then not reported. |
 | `binary-config-skew` | `warn`: `config.json` has a `configVersion` newer than this binary knows. | Upgrade this install. |
 | `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. |
 | `type-directory-disagreement` | `warn`: an indexed asset's resolved type differs from the type its directory declares. Each line gives the file, both types, and the classifier signal that won (`winner`). | Review the listed files. Intended overrides (for example a `knowledge/` file containing `$ARGUMENTS`) are marked `known-good override`. |
 | `memory-cleanup-archive` | `pass` with size and file count when the working bundle has `.akm/memory-cleanup/archive` content and no git history (the purge does not run there). `warn` when a git-backed bundle has archived files the purge cannot remove (untracked, modified, or unverifiable in git). | Commit the archived files so the purge can remove them once they age out. |
 | `data-dir-usage` | `warn`: the data directory is over 1 GB and either more than 3 times the size of `state.db`, `index.db`, and `logs.db` (with their WAL and SHM files), or one top-level subdirectory holds more than half of it. The message names that subdirectory and its size. | Inspect the named subdirectory. `backups/tasks/` holds task-file snapshots written by `akm migrate apply`. |
-| `plugin-version` | One row per installed Claude Code harness plugin: its version and whether its declared `AKM_VERSION_RANGE` admits the running CLI. The newest version is read on the channel the marketplace clone follows: on the remote's default branch the newest stable tag, on any other branch (such as `next`) the release tag on that branch's head, and on a clone pinned to a tag that tag. The newest-tag lookup is `--probe`-gated: with `--no-probe` the row is `unknown` ("not probed") and only the local range check still runs. `warn`: the plugin is stale, or its range does not admit the running CLI. | Run the `claude plugin update <ref>` command in the message. |
+| `plugin-version` | One row per native `claude plugin list --json` AKM installation, with scope, enabled state and install path; cached versions are never used to choose an installation. `AKM_MIN_VERSION` takes precedence over legacy `AKM_VERSION_RANGE`. Disabled and other-project installations are inert. Missing metadata or multiple applicable paths/versions produce `unknown`, since the native list does not identify which conflicting installation a running session loaded. The newest version is read on the channel the marketplace clone follows: on the remote's default branch the newest stable tag, on any other branch (such as `next`) the release tag on that branch's head, and on a clone pinned to a tag that tag. The newest-tag lookup is `--probe`-gated: with `--no-probe` the row is `unknown` ("not probed") and only the local range check still runs. `warn`: the plugin is stale, or its range does not admit the running CLI. | Run the `claude plugin update <ref>` command in the message. |
 | `opencode-plugin-version` | The same check 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. OpenCode 1 caches each spec in its own folder, so it reads the one folder of the spec the global OpenCode config names under `plugin` (`akm-opencode`, read as `akm-opencode@latest`, or `akm-opencode@next`), and for `akm-opencode@<version>` reports the plugin as pinned with no staleness verdict; with no entry, or no folder for it, it reads `packages/akm-opencode`, and it never scans the other cached specs. It reads local files only and is never `--probe`-gated. `warn`: the bundled version differs from the running CLI. Omitted when the OpenCode plugin is not installed. | Update the OpenCode plugin. |
 | `state-db-readable` | `fail`: `state.db` cannot be read, or is missing in a read-only run (which does not create it). 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. |
 

package/docs/architecture/testing/testing-workflow.md

@@ -439,18 +439,24 @@ orchestration, checksum, and failure paths.
 
 `tests/integration/upgrade-rehearsal/` runs once per origin in
 `KNOWN_UPGRADE_ORIGINS` (`previous-release.ts`): `previous`, the highest stable
-release below the candidate's `package.json` version, and `0.9.15`, a fixed
-older release. For each origin it installs that release as a real global npm
+release below the candidate's `package.json` version; `0.9.32`, which keeps the
+full engines migration covered after `previous` advances to 0.10; and `0.9.15`,
+which covers scheduler rows installed before host-local activation was recorded.
+Each origin installs that release as a real global npm
 package (a real `npm pack` / `npm install --global` into a throwaway prefix, see
-`scripts/package-install.ts`), uses it to build a realistic home — filesystem,
+`scripts/package-install.ts`). The `previous` and `0.9.32` origins build a full
+home — filesystem,
 git (with an in-bundle symlink at its root), website, and npm bundles, scheduled
-tasks, a synced native (fake) crontab, and the 0.9 `engines` form the release
-itself writes (an llm engine with an `apiKeyFile`, an agent engine, a
-`models.json`, a command and a task source that name an engine) — then installs
+tasks, a synced native (fake) crontab, and model configuration the release
+itself writes: native connections/harnesses on 0.10+, or the full 0.9 `engines`
+form (an llm engine with an `apiKeyFile`, agent engines, a `models.json`, and a
+command and task that name an engine). The `0.9.15` origin uses a smaller home
+with one directly installed scheduled task. Each then installs
 the CANDIDATE build OVER it in the SAME prefix: an in-place swap, the same thing
 a real `npm i -g akm-cli@…` or `bun add -g` upgrade does. It then runs the
 candidate against that home (`migrate status` / `apply`, which converts the
-`engines` form, files its key and rewrites the `engine:` keys, `bundle list`,
+`engines` form, files its key and rewrites the `engine:` keys, or preserves
+native connections/harnesses, `bundle list`,
 `search` / `show`, `task sync` dry-run and real — plain, no `--rebind`, as an
 upgrading user runs it — executing the generated cron command and confirming it
 ran the candidate, `task run`, `health`, `improve --dry-run`), and finally runs a

package/docs/reference/cli.md

@@ -541,11 +541,11 @@ Result sections (`schemaVersion: 1`):
 | Field | Description |
 | --- | --- |
 | `window`, `filters` | The resolved window and the usage source counted |
-| `usage` | Search, show, curate and select totals, `selectRate` (selects over searches that returned a hit), `searchMedianMs`, a daily series, top assets, top and zero-result queries, and rows by source |
+| `usage` | Search, show, curate and select totals, `searchesWithHits` and `selectsPerSearch` (selects divided by searches that returned a hit: a plain ratio that can exceed 1, not a conversion percentage, since selects carry no source or search id), `searchMedianMs`, a daily series, top assets, top and zero-result queries, and rows by source |
 | `feedback` | Positive and negative totals, per-asset valence, per-tag counts, and the most recent negatives with their reasons |
 | `utility` | A ten-bucket histogram of `utility_scores`, the lowest and highest assets, and how many indexed entries were never used |
 | `outcomes` | The assets with the lowest `outcome_score` |
-| `llm` | `akm health`'s LLM usage aggregate (`byStage`, `byProcess`, and `byEngine`, keyed by the name of the connection or harness) |
+| `llm` | `akm health`'s LLM usage aggregate (`byStage`, `byProcess`, and `byEngine`, keyed by the name of the connection or harness). `usageCalls` and `reasoningCalls` count the calls whose provider response reported token usage; a call without it adds no tokens and the report shows `unknown`, not zero, when none reported |
 | `index`, `tasks`, `proposals`, `workflows` | Index runs and median time, task runs and fail rate, proposals by status and accept rate by source, workflow runs and tokens by model |
 | `rows` | The raw usage and LLM rows of the window; see below |
 | `notes` | Anything that limits what the numbers mean |
@@ -1537,7 +1537,9 @@ computed, with a 256 MiB binary limit. Release/checksum metadata is capped at
 akm upgrade              # Install a newer release if there is one, run every pending migration, then update the harness plugins
 akm upgrade --check      # Report pending updates, CLI and plugins, without changing anything (no migration step)
 akm upgrade --force      # Force the install even if already on latest
-akm upgrade --next       # Install the newest prerelease (@next) instead of the latest stable release
+akm upgrade --next       # Include prereleases when selecting the newest CLI release
+akm upgrade --channel next   # Switch CLI and installed harness plugins to next
+akm upgrade --channel latest # Return CLI and installed harness plugins to stable
 ```
 
 | Flag | Description |
@@ -1545,7 +1547,9 @@ akm upgrade --next       # Install the newest prerelease (@next) instead of the
 | `--check` | Report pending updates (CLI and per-harness plugins) without changing anything |
 | `--force` | Force upgrade even if on latest version |
 | `--skip-post-upgrade` | Skip the post-upgrade index rebuild |
-| `--next` | Follow the `next` prerelease channel: install the newest prerelease of akm (and of the OpenCode plugin, see the Prereleases section below). Works with `--check`, `--force` and `-q` |
+| `--channel latest\|next` | Switch the CLI and installed Claude, Codex and OpenCode plugins together; works with `--check` |
+| `--allow-downgrade` | Permit an older target version during an explicit `--channel` switch |
+| `--next` | Include prereleases when selecting the newest CLI release; retain configured harness channels (see below). Works with `--check`, `--force` and `-q` |
 
 Offline, or to migrate without a release check, run `akm migrate apply`
 directly: it is the same step.
@@ -1607,7 +1611,7 @@ target is the akm-cli that `akm-opencode@latest` depends on
 The result then carries `lockstep: { plugin, pinnedVersion, newestVersion, heldBack }`,
 `latestVersion` is the pinned version, the install names that exact version
 rather than `@latest`, and the text output says the CLI is held back. The CLI
-is never moved backwards to meet the pin. With both OpenCode plugins present
+is never moved backwards to meet the pin unless an explicit channel switch also names `--allow-downgrade`. With both OpenCode plugins present
 (`akm-opencode` and `akm-opencode-v2`), the CLI is held to the older of their
 two pins, and `lockstep.plugin` names the one that sets it. Claude Code and Codex have no
 in-process copy and are not part of this rule.
@@ -1623,7 +1627,7 @@ retries.
 #### Prereleases (`--next`)
 
 `akm upgrade --next` means "newest available, prereleases included". The result
-carries `channel: "next"` (`"latest"` otherwise); no other field changes.
+carries `channel: "next"` (`"latest"` otherwise), plus the CLI's inferred `currentChannel` and each installed plugin's configured `channel` and `channelMismatch`.
 
 - **CLI.** The target is the `next` dist-tag of `akm-cli` (read from the npm
   registry, so it works for binary installs too) when that is newer than the
@@ -1656,14 +1660,38 @@ carries `channel: "next"` (`"latest"` otherwise); no other field changes.
 - **Claude Code and Codex.** Their plugin comes from the `akm-plugins` git
   marketplace, and the channel is the ref the marketplace follows: the default
   branch is stable, the `next` branch carries prereleases. `akm upgrade` updates
-  whatever ref the marketplace follows and cannot switch it, with or without
-  `--next`. To follow prereleases, add the marketplace as `itlackey/akm-plugins@next`
-  in Claude Code (`extraKnownMarketplaces.akm-plugins.source.ref = "next"` in
-  `settings.json`), or run `codex plugin marketplace add itlackey/akm-plugins --ref next`
-  in Codex. Under `--next` their entries carry a note naming the ref followed.
+  whatever ref the marketplace follows. `--next` alone leaves that ref unchanged;
+  `--channel next` changes it. Under `--next` their entries carry a note naming
+  the ref followed.
   The plugins need akm 0.10.261001 or newer; any newer akm passes.
 - `--check --next` reports all of this and changes nothing.
 
+#### Switching channels together (`--channel`)
+
+`akm upgrade --channel next` selects the actual npm `next` CLI tag and changes
+installed harness plugins to their `next` branch or package tag.
+`--channel latest` selects stable and removes those prerelease refs. An explicit
+switch may replace a pinned plugin spec. The command checks target CLI and plugin
+versions first; if any would go backwards, repeat with `--allow-downgrade`.
+A failed CLI install or migration stops the plugin switch.
+
+Claude and Codex retain their marketplace registrations, plugin enablement,
+`pluginConfigs`, and unrelated settings. akm edits only the marketplace ref,
+then uses the native updater. Claude's installed user, project and local scopes
+are updated explicitly. OpenCode changes only the installed plugin's spec,
+retaining tuple options and JSONC comments, then refreshes the desired cache.
+Every changed config file has a sibling `.akm-channel-*.bak` backup, whose path
+appears in that harness's `backups` result. Restart the harness to load updates.
+
+`--check --channel next` shows `channel`, `targetChannel` and mismatches without
+writing settings or fetching Git marketplaces. The CLI's `currentChannel` is
+inferred from its version: prerelease means `next`, otherwise `latest`.
+A configured channel is distinct from a successful refresh: native update
+failures retain the configured target and backup paths but report `failed`.
+An installed plugin that cannot switch, including OpenCode awaiting shutdown,
+makes an explicit switch exit `1`; retry after resolving its reported cause.
+The switch is coordinated, not a transaction across independent harnesses.
+
 #### Containers
 
 With the plugin step, a container entrypoint needs only:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261019",
+  "version": "0.10.261021",
   "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": [
@@ -119,9 +119,11 @@
     "citty": "^0.2.2",
     "dotenv": "^17.4.2",
     "fast-xml-parser": "^5.10.1",
+    "jsonc-parser": "^3.3.1",
     "marked": "^18.1.1",
     "node-html-parser": "^9.0.1",
     "semver": "^7.6.0",
+    "smol-toml": "^1.9.1",
     "turndown": "^7.2.4",
     "yaml": "^2.8.4",
     "zod": "^4.6.6"