akm-cli 0.10.261015-beta → 0.10.261017-beta

package/dist/cli.js

@@ -112,9 +112,6 @@ function applyEarlyStderrFlags(argv) {
         setVerbose(true);
     }
 }
-// resolveHelpMigrateVersionArg moved to ./cli/invocation (chunk-9 WI-9.9
-// argv-normalization fold — it re-scanned process.argv, same as
-// findCittyTopLevelCommand and parseAllFlagValues below).
 /**
  * Stderr-only human-friendly hint after a non-interactive `setup` invocation.
  * Default --format is `json`, so a CI or piped consumer sees only the JSON on
@@ -155,10 +152,9 @@ const setupCommand = defineCommand({
         description: "Interactive configuration wizard. Enables agent programs (Claude Code, Codex, OpenCode, ...), sets up a model connection and embeddings, and picks bundle sources and registries. Flags answer individual questions; --yes takes the detected default for the rest, for scripting.",
     },
     args: {
-        // R-051/S11: `setup` is a raw `defineCommand` (not `defineJsonCommand`),
-        // so it does not get `GLOBAL_OUTPUT_ARGS` for free — same gap `health`
-        // already had. Three of its four run branches call `output()`; spreading
-        // this in is a `--help` visibility fix, not a behavior change.
+        // `setup` is a raw `defineCommand` (not `defineJsonCommand`), so it does
+        // not get `GLOBAL_OUTPUT_ARGS` for free. Three of its four run branches
+        // call `output()`; spreading this in is a `--help` visibility fix.
         ...GLOBAL_OUTPUT_ARGS,
         endpoint: {
             type: "string",
@@ -285,11 +281,11 @@ const healthCommand = defineCommand({
         description: "Check akm runtime health, artifacts, and improve metrics",
     },
     args: {
-        // R-051: `health` is a raw `defineCommand` (not `defineJsonCommand`), so
-        // it does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
-        // `--output` already parsed correctly here (this command has
+        // `health` is a raw `defineCommand` (not `defineJsonCommand`), so it does
+        // not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
+        // `--output` parse correctly here regardless (this command has
         // no positional for a stray value to fall into), so this is purely a
-        // `--help` visibility / consistency fix, not a behavior change.
+        // `--help` visibility / consistency measure.
         ...GLOBAL_OUTPUT_ARGS,
         since: {
             type: "string",
@@ -389,8 +385,8 @@ const healthCommand = defineCommand({
             }
             output("health", base);
         });
-        // R-067: `emitJsonError` (src/cli/shared.ts) no longer force-exits on the
-        // error path — it sets `process.exitCode` and returns, so a `--report`
+        // `emitJsonError` (src/cli/shared.ts) does not force-exit on the error
+        // path — it sets `process.exitCode` and returns, so a `--report`
         // failure thrown AFTER `resultStatus` was already assigned (e.g. the
         // proposal-queue read above) would otherwise leave `resultStatus`
         // populated here too. Skip the status-derived exit entirely once
@@ -443,14 +439,12 @@ const completionsCommand = defineCommand({
         },
     },
     run({ args }) {
-        // R-052(b): this was a bare `run()` throwing directly, so an unsupported
-        // `--shell` value escaped straight to citty's top-level error handling
-        // instead of the standard JSON envelope — exit 1 with a raw stack trace
-        // instead of the classified exit-2 usage error every other command
-        // produces (`completions` is format-exempt, so it stays a raw
-        // `defineCommand` rather than `defineJsonCommand`, but still needs the
-        // same error-classification wrapper other bare `defineCommand`s in this
-        // file use, e.g. `help migrate` below).
+        // An unsupported `--shell` value must reach the standard JSON envelope as
+        // the classified exit-2 usage error, not escape to citty's top-level error
+        // handling as a raw stack trace (`completions` is format-exempt, so it
+        // stays a raw `defineCommand` rather than `defineJsonCommand`, but still
+        // needs the same error-classification wrapper other bare `defineCommand`s
+        // in this file use, e.g. `help migrate` below).
         return runWithJsonErrors(() => {
             if (args.shell !== "bash") {
                 throw new UsageError(`Unsupported shell: ${args.shell}. Only bash is supported.`);
@@ -678,7 +672,7 @@ const EXIT_GENERAL = EXIT_CODES.GENERAL;
 const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
 // ── Top-level driver (replaces citty's `runMain`) ───────────────────────────
 //
-// R-032: citty's own `runMain` catches EVERY error escaping `runCommand` —
+// citty's own `runMain` catches EVERY error escaping `runCommand` —
 // including its unexported `CLIError`, thrown for "Unknown command …", "No
 // command specified.", "Missing required argument/positional …", and invalid
 // enum values — and unconditionally calls `process.exit(1)`, regardless of
@@ -692,7 +686,7 @@ const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
 // of `runMain`, replicating `runMain`'s `--help` / `--version`
 // short-circuits and its CLIError → usage-banner rendering, but classifying
 // a CLIError as USAGE (2) instead of GENERAL (1). Every other error escaping
-// this boundary keeps the previous GENERAL (1) mapping — this only
+// this boundary keeps the GENERAL (1) mapping — this only
 // reclassifies the one error family citty itself throws before any of our
 // own command bodies (and their `runWithJsonErrors` / `emitJsonError`
 // classification) ever run.
@@ -762,7 +756,7 @@ function resolveCittyCommandPath(cmd, rawArgs, path = []) {
  * dropping the `akm ` root prefix every top-level command's `--help` already
  * shows. Building a synthetic parent whose `meta.name` is the full prefix
  * (`akm task`) fixes it for any depth without patching the vendored
- * dependency (S11 item 4).
+ * dependency.
  */
 function buildUsageParentForPath(path) {
     // `version` carries through too — citty's renderUsage falls back to
@@ -776,7 +770,7 @@ function buildUsageParentForPath(path) {
         },
     };
 }
-// ── Sectioned root help (S11) ────────────────────────────────────────────────
+// ── Sectioned root help ────────────────────────────────────────────────
 //
 // citty's own generated COMMANDS list is a flat, unordered dump of every
 // top-level command — fine for a handful of commands, not for the ~28 this
@@ -853,7 +847,7 @@ function renderCommandSections() {
     return HELP_SECTIONS.map(({ title, commands }) => `${title}\n${formatCommandRows(commands)}`).join("\n\n");
 }
 /**
- * Sectioned replacement for citty's root COMMANDS list (S11 item 1). Reuses
+ * Sectioned replacement for citty's root COMMANDS list. Reuses
  * `renderUsage(main)` for the banner + exit-code table (kept verbatim) +
  * USAGE line + global OPTIONS, then cuts the string before citty's own
  * "COMMANDS" heading (present because `main` has `subCommands`) and appends
@@ -938,7 +932,7 @@ function cittyCliErrorUsageCode(error) {
 }
 /**
  * Route a citty `CLIError` through the standard JSON envelope instead of
- * citty's own usage-banner + raw `console.error(message)` (S11 item 3): the
+ * citty's own usage-banner + raw `console.error(message)`: the
  * one-line diagnosis is the error's own message (e.g. "Unknown command
  * foo"), and the hint is a short pointer — with a did-you-mean suggestion
  * prepended when the unresolved token is close to a real sibling command —
@@ -962,12 +956,10 @@ export function normalizeCittyCliError(error, rawArgs) {
 }
 /**
  * The CLI's real startup sequence, extracted into a function so error paths
- * can `return` early — top-level `return` is a syntax error in an ES module,
- * and this used to rely on `emitJsonError`'s `never` return type (a
- * synchronous `process.exit`) to stop execution instead. Now that
- * `emitJsonError` (src/cli/shared.ts, R-067) only records `process.exitCode`
- * and returns, every direct call site here needs its own explicit `return;`
- * to stop the rest of startup from running after a fatal early error.
+ * can `return` early — top-level `return` is a syntax error in an ES module.
+ * `emitJsonError` (src/cli/shared.ts) only records `process.exitCode` and
+ * returns, so every direct call site here needs its own explicit `return;` to
+ * stop the rest of startup from running after a fatal early error.
  */
 export async function runCli() {
     try {
@@ -978,7 +970,7 @@ export async function runCli() {
         return;
     }
     // Mint the ParsedInvocation singleton from the (normalized) argv — the ONE
-    // place argv is parsed for the whole process (plan §10.7 / chunk-9 WI-9.9).
+    // place argv is parsed for the whole process.
     // Every out-of-cli.ts command module reads argv state through
     // `getParsedInvocation()` from here on instead of re-scanning process.argv.
     setParsedInvocation(process.argv);
@@ -1024,11 +1016,10 @@ export async function runCli() {
         return;
     }
     const commandPath = resolveCittyCommandPath(main, process.argv.slice(2));
-    // D7 — every command that renders through output() honours all six --format
+    // Every command that renders through output() honours all six --format
     // values. The declared exempt set (src/output/format-exempt.ts) does not
     // render an envelope at all, so warn rather than pretend: silently ignoring
-    // the flag is what made the old md/html behaviour so hard to discover. A
-    // warning, not an error, because the flag is harmless here and scripts that
+    // the flag makes the behaviour hard to discover. A warning, not an error, because the flag is harmless here and scripts that
     // pass --format globally to a mixed batch of commands should still work.
     const invocation = getParsedInvocation();
     if ((invocation.hasFlag("--format") || invocation.getFlagValue("--format") !== undefined) &&
@@ -1082,7 +1073,7 @@ export async function runCli() {
         if (HELP_FLAGS.some((flag) => ownArgs.includes(flag))) {
             const resolved = resolveDeepestCittyCommand(main, rawArgs);
             if (resolved === main) {
-                // Root `--help` (S11 item 1): the sectioned overview, not citty's
+                // Root `--help`: the sectioned overview, not citty's
                 // flat COMMANDS dump.
                 process.stdout.write(`${await renderSectionedRootHelp()}\n`);
             }
@@ -1097,14 +1088,14 @@ export async function runCli() {
             return;
         }
         // citty's parseArgs (strict: false) silently ignores undeclared flags, so
-        // a typo used to run the command with defaults and exit 0. Checked here, after --help and
-        // --version, so those keep working on any command.
+        // a typo would otherwise run the command with defaults and exit 0. Checked
+        // here, after --help and --version, so those keep working on any command.
         assertKnownFlags(main, rawArgs);
         await runCommand(main, { rawArgs });
     }
     catch (error) {
         if (isCittyCliError(error)) {
-            // R-032/S11: reclassify citty's own "unknown command" / "no command
+            // Reclassify citty's own "unknown command" / "no command
             // specified" / "missing required argument" family as USAGE (2) and
             // route it through the SAME JSON envelope every other command's
             // failure uses (`emitJsonError`), rather than citty's own usage-banner

package/dist/commands/feedback-cli.js

@@ -435,10 +435,11 @@ export const feedbackCommand = defineJsonCommand({
             "next search; no reindex is needed. Each recorded positive raises the asset's\n" +
             "score and each negative lowers it, the same way for every asset: the more\n" +
             "positives, the higher it ranks (5 outrank 2), and each further vote counts\n" +
-            "for a little less. The effect is small, so it reorders close matches and\n" +
-            "does not override relevance. Only feedback recorded as the user counts, not\n" +
-            "feedback from improve, task or audit runs. Feedback also moves the utility\n" +
-            "score that improve and `akm metrics` read.",
+            "for a little less. The effect is small: in keyword-only search one vote\n" +
+            "moves a hit one place, and with embeddings it breaks only near-ties. Only\n" +
+            "feedback recorded as the user counts, not feedback from improve, task or\n" +
+            "audit runs. Feedback also moves the utility score that improve and\n" +
+            "`akm metrics` read.",
     },
     args: {
         // Optional in citty so run() is invoked even when omitted; we re-validate

package/dist/commands/health/plugin-staleness.js

@@ -35,7 +35,7 @@
  * local marketplace clone is not proof of what is newest upstream — the
  * incident above involved a clone that hadn't seen the fix's tag at all — so
  * the only way to ever detect drift is to ask the remote what tags exist.
- * That query is a `git ls-remote --tags` (lists refs; fetches nothing,
+ * That query is a `git ls-remote --symref` (lists refs; fetches nothing,
  * writes nothing) with a short timeout, and any failure (offline, no
  * remote, timeout) degrades to "installed version reported, no staleness
  * claim" rather than a false positive or a hang. Like `cli-version`, this
@@ -54,7 +54,8 @@ import os from "node:os";
 import path from "node:path";
 import { OPENCODE_V1, OPENCODE_V2, readPackageVersion, } from "../../integrations/harnesses/opencode/plugin-layout.js";
 import { opencodeCacheDir } from "../../integrations/harnesses/opencode/roots.js";
-import { isExactSemver, isSemverRange, maxSatisfying, satisfiesRange } from "../../registry/semver.js";
+import { highestVersion, isExactSemver, isPrerelease, isSemverRange, satisfiesRange } from "../../registry/semver.js";
+import { openCodeConfigSpec } from "../sources/plugin-upgrade.js";
 /**
  * Root directory holding Claude Code's plugin cache + marketplace clones.
  * Resolved per call (not memoized) so `AKM_CLAUDE_PLUGINS_DIR` can be set
@@ -78,12 +79,26 @@ function defaultOpencodeCacheRoot() {
 }
 const OPENCODE_PLUGIN_LOCATIONS = [
     {
-        // OpenCode 1: <cache>/packages/akm-opencode/node_modules/akm-cli (the folder read since this check began).
+        // OpenCode 1: <cache>/packages/<spec>/node_modules/akm-cli, the one spec the global config names (#1265).
         flavor: OPENCODE_V1,
         advisory: "opencode-plugin-version",
         label: "OpenCode's",
         remedy: "update the OpenCode plugin",
-        folders: (cacheRoot) => [{ folder: path.join(cacheRoot, OPENCODE_V1.cacheFolder(OPENCODE_V1.pkg)) }],
+        folders: (cacheRoot) => {
+            // OpenCode caches each spec in its own folder, and a bare name is its `@latest`, as `akm upgrade` reads it. With
+            // no config entry, or no folder for the spec, the bare `packages/akm-opencode` is read, as this check always has.
+            const { pkg } = OPENCODE_V1;
+            const bare = { folder: path.join(cacheRoot, OPENCODE_V1.cacheFolder(pkg)) };
+            const named = openCodeConfigSpec(OPENCODE_V1)?.spec;
+            if (named === undefined)
+                return [bare];
+            const spec = named === pkg ? `${pkg}@latest` : named;
+            const folder = path.join(cacheRoot, OPENCODE_V1.cacheFolder(spec));
+            if (!fs.existsSync(folder))
+                return [bare];
+            const version = spec.slice(pkg.length + 1);
+            return [{ spec, folder, ...(isExactSemver(version) ? { pinned: version } : {}) }];
+        },
     },
     {
         // OpenCode 2: <cache>/npm/akm-opencode-v2@<spec>/<epoch-ms>/node_modules/akm-cli, newest build per spec.
@@ -110,11 +125,11 @@ const OPENCODE_PLUGIN_LOCATIONS = [
  */
 function findBundledAkm(plugin, cacheRoot) {
     const found = [];
-    for (const { spec, folder } of plugin.folders(cacheRoot)) {
+    for (const { spec, pinned, folder } of plugin.folders(cacheRoot)) {
         const nodeModules = plugin.flavor.nodeModulesDir(folder);
         const version = nodeModules && readPackageVersion(path.join(nodeModules, "akm-cli", "package.json"));
         if (version !== undefined)
-            found.push(spec ? { spec, version } : { version });
+            found.push({ ...(spec ? { spec } : {}), ...(pinned ? { pinned } : {}), version });
     }
     return found;
 }
@@ -122,6 +137,17 @@ function buildOpencodeBundledAdvisory(plugin, bundled, cliVersion) {
     const bundledVersion = bundled.version;
     const stale = bundledVersion !== cliVersion;
     const where = bundled.spec ? ` (${bundled.spec})` : "";
+    if (bundled.pinned) {
+        // The config chose this build: there is nothing to update it to, so no staleness verdict.
+        return {
+            name: plugin.advisory,
+            kind: "deterministic",
+            status: "pass",
+            confidence: "high",
+            message: `${plugin.label} plugin is pinned to v${bundled.pinned}${where}; its bundled akm-cli is v${bundledVersion}, and a pinned plugin is not compared with the running CLI v${cliVersion}.`,
+            evidence: { bundledVersion, cliVersion, spec: bundled.spec, pinnedVersion: bundled.pinned },
+        };
+    }
     return {
         name: plugin.advisory,
         kind: "deterministic",
@@ -161,7 +187,7 @@ function detectInstalledPlugins(pluginsRoot) {
         }
         if (versions.length === 0)
             continue;
-        const latest = maxSatisfying(versions, "*") ?? versions.sort().at(-1);
+        const latest = highestVersion(versions);
         if (!latest)
             continue;
         const versionDir = path.join(pluginDir, latest);
@@ -204,16 +230,31 @@ function readVersionRange(pluginDir) {
 }
 const LS_REMOTE_TIMEOUT_MS = 5_000;
 /**
- * `git ls-remote --tags origin` against the marketplace clone's configured
- * remote — lists refs only, fetches no objects, writes no local refs.
- * Returns `undefined` (never throws) when the directory is not a git
- * checkout, has no `origin` remote, or the command fails/times out (e.g.
- * offline) — all "cannot determine availability", not "up to date".
+ * `git ls-remote --symref origin` against the marketplace clone's configured remote (lists refs only, fetches no
+ * objects, writes no local refs), read for the channel the clone follows:
+ *
+ * - **The remote's default branch** (stable): every stable release tag; the newest is the highest of them.
+ * - **Any other branch** (a channel such as `next`): the release tags on that branch's head. A channel branch is
+ *   reset to each build it publishes, so its head IS the newest build of the channel, whatever semver order says
+ *   about other tags (retired build schemes can sort above current builds).
+ * - **No branch** (a marketplace added at a tag ref, which Claude Code clones detached): the release tag the clone
+ *   is pinned to. A pinned marketplace never offers anything newer, so `claude plugin update` could not act on a
+ *   newer tag elsewhere. A detached clone at an untagged commit reads like the default branch.
+ *
+ * Returns `undefined` (never throws) when the directory is not a git checkout, has no `origin` remote, or the
+ * command fails/times out (e.g. offline): all "cannot determine availability", not "up to date". A channel head
+ * with no release tag returns `[]`, which reads the same way.
  */
 const realListRemoteTags = (marketplaceDir) => {
     let result;
+    let branch;
     try {
-        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--tags", "origin"], {
+        branch =
+            spawnSync("git", ["-C", marketplaceDir, "branch", "--show-current"], {
+                encoding: "utf8",
+                timeout: LS_REMOTE_TIMEOUT_MS,
+            }).stdout?.trim() ?? "";
+        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--symref", "origin"], {
             encoding: "utf8",
             timeout: LS_REMOTE_TIMEOUT_MS,
         });
@@ -223,16 +264,39 @@ const realListRemoteTags = (marketplaceDir) => {
     }
     if (result.status !== 0 || !result.stdout)
         return undefined;
-    const tags = result.stdout
+    const refs = result.stdout
         .split("\n")
         .map((line) => line.trim())
         .filter(Boolean)
-        .map((line) => line.split("\t")[1])
-        .filter((ref) => typeof ref === "string" && ref.startsWith("refs/tags/"))
-        .map((ref) => ref.replace(/^refs\/tags\//, "").replace(/\^\{\}$/, ""))
-        .map((tag) => tag.replace(/^v/, ""))
-        .filter(isExactSemver);
-    return [...new Set(tags)];
+        .map((line) => line.split("\t"));
+    const defaultBranch = refs
+        .find(([value, name]) => name === "HEAD" && value?.startsWith("ref: refs/heads/"))?.[0]
+        ?.replace(/^ref: refs\/heads\//, "");
+    const tags = refs
+        .filter(([, name]) => typeof name === "string" && name.startsWith("refs/tags/"))
+        .map(([sha, name]) => ({
+        sha: sha,
+        version: name
+            .replace(/^refs\/tags\//, "")
+            .replace(/\^\{\}$/, "")
+            .replace(/^v/, ""),
+    }))
+        .filter((tag) => isExactSemver(tag.version));
+    const tagsAt = (sha) => [
+        ...new Set(tags.filter((tag) => tag.sha === sha).map((tag) => tag.version)),
+    ];
+    const onChannelBranch = branch !== "" && defaultBranch !== undefined && branch !== defaultBranch;
+    if (onChannelBranch)
+        return tagsAt(refs.find(([, name]) => name === `refs/heads/${branch}`)?.[0]);
+    if (branch === "") {
+        const pinned = tagsAt(spawnSync("git", ["-C", marketplaceDir, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            timeout: LS_REMOTE_TIMEOUT_MS,
+        }).stdout?.trim());
+        if (pinned.length > 0)
+            return pinned;
+    }
+    return [...new Set(tags.map((tag) => tag.version).filter((version) => !isPrerelease(version)))];
 };
 /**
  * Build one `plugin-version` advisory per detected `akm` harness plugin,
@@ -263,14 +327,14 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
     let availableVersion;
     try {
         const tags = probe && fs.existsSync(marketplaceDir) ? listRemoteTags(marketplaceDir) : undefined;
-        availableVersion = tags && tags.length > 0 ? maxSatisfying(tags, "*") : undefined;
+        availableVersion = tags && tags.length > 0 ? highestVersion(tags) : undefined;
     }
     catch {
         availableVersion = undefined;
     }
     const stale = availableVersion !== undefined &&
         plugin.version !== availableVersion &&
-        maxSatisfying([plugin.version, availableVersion], "*") === availableVersion;
+        highestVersion([plugin.version, availableVersion]) === availableVersion;
     // Point 3: does the plugin's own declared range admit the running CLI?
     const versionRange = readVersionRange(plugin.pluginDir);
     const rangeKnown = versionRange !== undefined && isSemverRange(versionRange);

package/dist/commands/health.js

@@ -72,21 +72,21 @@ function validateAkmHealthOptions(options) {
         }
     }
 }
-// ── akmHealth phase helpers (chunk-9 WI-9.5b; file-level decompose following
-// the function's natural gather/advise/check/assemble phases) ───────────────
+// ── akmHealth phase helpers (the function's natural
+// gather/advise/check/assemble phases) ──────────────────────────────────────
 /** Event type appended + read back by the state.db round-trip probe. */
 const HEALTH_PROBE_EVENT = "health_probe";
-/** Synthetic sentinel ref (ref-grammar decision D-R3): a colon-free
+/** Synthetic sentinel ref: a colon-free
  * `<subsystem>/_<marker>` label. `health` has no asset stash-subdir, so
  * `health/_probe` names the subsystem. */
 const HEALTH_PROBE_REF = "health/_probe";
 /**
  * Verify state.db can accept a write and read it back — WITHOUT leaving any
- * permanent trace (R-030). Earlier versions appended a `health_probe` event
- * on every `akm health` invocation and never removed it: a read-only health
- * check ran on a cron would grow state.db without bound (the only purge is
- * `improve`'s retention pass, which a health-only user never runs). The probe
- * row inserted here is deleted again inside the SAME connection once the
+ * permanent trace. Leaving the `health_probe` event in place after every
+ * `akm health` invocation would grow state.db without bound for a read-only
+ * health check run on a cron (the only purge is `improve`'s retention pass,
+ * which a health-only user never runs). The probe row inserted here is
+ * deleted again inside the SAME connection once the
  * round trip is confirmed, so the net effect on the `events` table is always
  * zero rows — the round trip still genuinely exercises append + read against
  * the real table, it just doesn't accumulate.
@@ -132,7 +132,7 @@ export function probeStateDbRoundTrip(stateDbPath) {
     }
 }
 /**
- * Item 7: dedupe stuck-active rows by task_id (keeping the oldest/largest age
+ * Dedupe stuck-active rows by task_id (keeping the oldest/largest age
  * per id) so the `active-runs` check can name WHICH tasks are stuck instead of
  * just a count. No pid/liveness probing — purely a projection of the rows
  * already read.
@@ -148,7 +148,7 @@ function dedupeStuckActiveTasks(rows, now) {
     return [...byTask.entries()].map(([taskId, ageMs]) => ({ taskId, ageMs }));
 }
 /**
- * Item 6: group task_history rows by task_id and return the one with the
+ * Group task_history rows by task_id and return the one with the
  * highest fail rate among tasks with at least MIN_ROWS_FOR_WORST_TASK_FAIL_RATE
  * rows in the window — surfaces a consistently-failing task that a large,
  * mostly-healthy population would otherwise hide behind the aggregate rate.
@@ -184,7 +184,7 @@ function gatherTaskHistoryPhase(db, since, stateDbPath, now, readOnly) {
     const requiredTables = ["events", "proposals", "schema_migrations", "task_history"];
     const missingTables = requiredTables.filter((name) => !tableNames.includes(name));
     const probe = readOnly ? { ok: true, durationMs: null, skipped: true } : probeStateDbRoundTrip(stateDbPath);
-    // R0: read-only, independent of the round-trip probe above — integrity_check
+    // Read-only, independent of the round-trip probe above — integrity_check
     // catches corruption a successful append/read cannot (out-of-order rowids,
     // bad index entry counts), and the freelist reading is purely informational.
     const stateDbIntegrity = runStateDbIntegrityCheck(stateDbPath);
@@ -251,7 +251,7 @@ function gatherAncillaryAdvisories(db, options, egressConfigView) {
     const indexStateMismatch = detectIndexStateGenerationMismatch(db);
     if (indexStateMismatch)
         advisories.push(indexStateMismatch);
-    // 08-F1: surface a `stash-git-exposure` advisory when env/secret assets are
+    // Surface a `stash-git-exposure` advisory when env/secret assets are
     // git-tracked AND a remote is configured (the leak moment). Best-effort.
     // Cheap guard: only shell out to git when the stash has its OWN `.git` (or a
     // test injected a fake seam), so the hot path never spawns for a non-git
@@ -295,8 +295,7 @@ function gatherAncillaryAdvisories(db, options, egressConfigView) {
     catch {
         // Non-fatal.
     }
-    // Item 4 (alpha.9 plan §5.4/§8 step 8): a bundle with no git history of its
-    // own never gets the purge sweep, so its memory-cleanup archive only ever
+    // A bundle with no git history of its own never gets the purge sweep, so its memory-cleanup archive only ever
     // grows — report its size and file count instead. Best-effort — an
     // unreadable archive must not abort the health report.
     try {
@@ -425,7 +424,7 @@ function detectIndexStateGenerationMismatch(stateDb) {
     }
 }
 /**
- * Phase 3 — window-compare mode. Resolves `--window-compare`/`--windows` into
+ * Window-compare mode. Resolves `--window-compare`/`--windows` into
  * per-window bundles and computes deltas between the earliest and latest
  * window. Top-level metrics retain the primary `--since` query.
  */
@@ -655,7 +654,7 @@ export async function akmHealth(options = {}) {
         const hardFailure = hardChecks.some((check) => check.status === "fail");
         const deterministicWarnings = [...hardChecks, ...advisories].some((check) => check.status === "warn" && check.kind === "deterministic");
         const status = hardFailure ? "fail" : deterministicWarnings ? "warn" : "pass";
-        // ── Per-run mode (Phase 2) ────────────────────────────────────────────
+        // ── Per-run mode ────────────────────────────────────────────
         const runs = options.groupBy === "run" ? perRunSummaries : undefined;
         return {
             schemaVersion: 3,

package/dist/commands/proposal/proposal-cli.js

@@ -390,7 +390,7 @@ const proposalDrainCommand = defineJsonCommand({
         },
         promote: {
             type: "boolean",
-            description: "Promote (accept) matching proposals. Default is queue mode (stage only, no writes to assets).",
+            description: "Promote (accept) matching proposals. Without it, the strategy's apply mode decides, and the default strategy's is promote (akm#1274).",
             default: false,
         },
         judgment: {

package/dist/commands/read/registry-search.js

@@ -14,8 +14,11 @@ export async function searchRegistry(query, options) {
         return { query: "", hits: [], warnings: [] };
     }
     const limit = clampLimit(options?.limit);
+    // AKM_REGISTRY_URL outranks the caller's list: `akm search` passes
+    // `config.registries`, which would otherwise shadow the override.
+    const envOverride = process.env.AKM_REGISTRY_URL?.trim() ? resolveRegistries() : undefined;
     // resolveRegistries() already filters by enabled; explicit registries are filtered here
-    const raw = options?.registries ?? resolveRegistries();
+    const raw = envOverride ?? options?.registries ?? resolveRegistries();
     const warnings = [];
     const entries = (options?.registries ? raw.filter((r) => r.enabled !== false) : raw).filter((entry) => {
         if (!hasRegistryUrlCredentials(entry.url))

package/dist/commands/read/search-cli.js

@@ -177,7 +177,7 @@ function rejectExtraShowPositionals(positionals, ref) {
     if (extra.length === 0)
         return;
     throw new UsageError(`akm show takes a single ref, but got ${extra.map((token) => `"${token}"`).join(" ")} after "${ref}". ` +
-        `Use \`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", "An unmatched #fragment lists the available slugs.");
+        `Use \`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", `Run \`akm show ${ref} --detail brief\` for the document's outline (\`toc\`, no body).`);
 }
 export const showCommand = defineJsonCommand({
     meta: {
@@ -187,7 +187,7 @@ export const showCommand = defineJsonCommand({
     args: {
         ref: {
             type: "positional",
-            description: "Asset ref ([bundle//]conceptId[#fragment]). On a markdown document `#fragment` selects one section by heading slug, and an unmatched fragment lists the available slugs. Example: `akm show knowledge/guide.md#auth`.",
+            description: "Asset ref ([bundle//]conceptId[#fragment]). On a markdown document `#fragment` selects one section by heading slug; `--detail brief` returns the outline (`toc`, each heading's slug) without the body. Example: `akm show knowledge/guide.md#auth`.",
             required: true,
         },
         filter: {

package/dist/commands/read/search.js

@@ -5,7 +5,7 @@
  * `akm search` — entry point.
  *
  * Search consults the local FTS5 index. There is one query path
- * because there is one data store. Provider fan-out is gone.
+ * because there is one data store; there is no provider fan-out.
  *
  * The orchestration here is thin: build the FTS query, optionally interleave
  * a registry search behind `--from registry|all`, and log a usage event.
@@ -214,9 +214,9 @@ function resolveEntryIds(db, hits) {
         try {
             const entryId = getEntryIdByFilePath(db, hit.path);
             if (entryId !== undefined) {
-                // F4c: persist the DURABLE fully-qualified `bundle//conceptId` spelling,
-                // derived from the resolved entry row's `item_ref` (D-R3: durable keys
-                // come from the resolved item, never raw input).
+                // Persist the DURABLE fully-qualified `bundle//conceptId` spelling,
+                // derived from the resolved entry row's `item_ref` (durable keys come
+                // from the resolved item, never raw input).
                 const itemRef = getItemRefById(db, entryId);
                 if (itemRef !== null) {
                     results.push({ entryId, ref: itemRef, hit });
@@ -254,7 +254,7 @@ function logSearchEvent(rawQuery, response, mode = "keyword", eventSource = "use
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm search invocations without relying on stdout scraping.
     const stashHits = response.hits.filter((h) => h.type !== "registry");
-    // D8: include registry hit refs so a show following a registry-only search generates a select event
+    // Include registry hit refs so a show following a registry-only search generates a select event
     const registryHitRefs = (response.registryHits ?? []).map((h) => `registry:${h.id}`);
     const allResultRefs = [...stashHits.map((h) => h.ref), ...registryHitRefs];
     appendEvent({
@@ -267,7 +267,7 @@ function logSearchEvent(rawQuery, response, mode = "keyword", eventSource = "use
         // Under contention these usage hints are skipped, not waited for.
         withIndexDb((db) => {
             const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
-            // usage_events telemetry now writes to state.db (Chunk-8 WI-8.3);
+            // usage_events telemetry writes to state.db;
             // entry_id/entry_ref are resolved from index.db above and carried across.
             const stashHitCount = response.hits.length;
             const registryHitCount = Array.isArray(response.registryHits) ? response.registryHits.length : 0;