akm-cli 0.10.261020-beta → 0.10.261021

package/CHANGELOG.md

@@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-## [0.10.261020] - 2026-10-29
+## [0.10.261021] - 2026-10-30
 
 ### Added
 
@@ -15,8 +15,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   writing backups. `--check` shows channel mismatches; an older target requires
   `--allow-downgrade` (#1285).
 
+### Changed
+
+- `akm metrics` replaces `usage.selectRate` with `usage.selectsPerSearch` and
+  adds `usage.totals.searchesWithHits`. Selects carry no source or search id, so
+  the figure is an unbounded ratio, not a conversion percentage: eight selects
+  after one search read 8.00, not 800% (#1293).
+
 ### Fixed
 
+- A model call whose configured deadline is longer than five minutes is no
+  longer cut off at five minutes by Bun's socket-idle timer (#1295).
+- Workflow params that are ordinary file paths (absolute, relative, Windows,
+  with dates, digits or a UUID directory) are no longer warned about or redacted
+  as secrets; credential-named keys, known token prefixes and token-shaped path
+  segments still are (#1292).
+- `akm bundle add --writable` on a bundle installed read-only from Git makes a
+  fresh checkout instead of failing with "is not a checkout", keeping the
+  bundle's name, components, order and credential (#1296).
+- `akm health` checks every configured git bundle for tracked `env/` or
+  `secrets/` files with a remote, not only the working stash, and names the
+  bundle in each warning. A bundle whose `.gitignore` carries
+  `# akm: intentionally track env and secrets` is not reported; the warning
+  names that line as the way to acknowledge intentional tracking (#1291).
+- `akm health`'s `type-directory-disagreement` warning uses the indexer's own
+  directory rules, so `scripts/README.md` or `knowledge/example.sh` no longer
+  warn, and it checks only `akm`-adapter entries inside their component root (#1288).
+- `akm metrics` reports token usage as unknown, with the number of calls that
+  reported it, instead of zero when the provider sent none. A call reporting
+  prompt and completion tokens but no total now counts their sum in the LLM
+  usage aggregate `akm health` shares (#1294).
 - Claude plugin health uses native installation, scope and enabled metadata
   instead of choosing the highest cached version. It reads `AKM_MIN_VERSION`
   as well as the legacy range, and reports uncertain selections as unknown (#1286).

package/STABILITY.md

@@ -4,14 +4,6 @@
 **with one caveat**: while the version is 0.x, minor releases (0.x → 0.x+1)
 may include breaking changes.
 
-**0.9.x series exception.** The 0.9.x releases are a deliberate refactoring
-and clean-up series: the goal is to pay off all remaining technical debt and
-land every planned breaking change before 0.10. While that work completes,
-**0.9.x patch releases may also contain breaking changes** — each one called
-out in the CHANGELOG with a migration note. The 0.10.x series returns to bug
-fixes and tuning, and aims to restore the normal discipline of breaking
-changes only in major and minor releases.
-
 **Version floor (0.10, #1091).** 0.10 reads what 0.9.15 and later wrote: config,
 `state.db`, task sources, frozen workflow plans and scheduler rows. It does not
 convert anything older. An install on an earlier release runs `akm migrate

package/dist/assets/templates/html/metrics.html

@@ -363,17 +363,19 @@ function aggregate(rows, opts) {
 // and carry no ref, source or event type, so only the date range applies.
 function aggregateLlm(rows, f) {
   var by = { stage: Object.create(null), process: Object.create(null), engine: Object.create(null) }, daily = new Map();
-  var t = { calls: 0, tokens: 0, failures: 0, durationMs: 0 };
+  var t = { calls: 0, tokens: 0, failures: 0, durationMs: 0, usageCalls: 0 };
   rows.forEach(function (r) {
     var d = dayOf(r.day);
     if (f.from && d < f.from) return;
     if (f.to && d > f.to) return;
     var tok = tokensOf(r), calls = r.calls || 0, failed = r.outcome === 'error' ? calls : 0;
-    t.calls += calls; t.tokens += tok; t.durationMs += r.durationMs || 0; t.failures += failed;
+    // Rows from a report that predates usage coverage count as fully measured.
+    var measured = r.usageCalls != null ? r.usageCalls : calls;
+    t.calls += calls; t.tokens += tok; t.durationMs += r.durationMs || 0; t.failures += failed; t.usageCalls += measured;
     [['stage', r.stage], ['process', r.process], ['engine', r.engine]].forEach(function (p) {
       var k = p[1] || 'unattributed';
-      var e = by[p[0]][k] || (by[p[0]][k] = { name: k, calls: 0, tokens: 0, failures: 0 });
-      e.calls += calls; e.tokens += tok; e.failures += failed;
+      var e = by[p[0]][k] || (by[p[0]][k] = { name: k, calls: 0, tokens: 0, failures: 0, usageCalls: 0 });
+      e.calls += calls; e.tokens += tok; e.failures += failed; e.usageCalls += measured;
     });
     var day = daily.get(d) || { day: d, calls: 0, durationMs: 0 };
     day.calls += calls; day.durationMs += r.durationMs || 0;
@@ -621,7 +623,7 @@ function toCsv(columns, rows) {
     var agg = useRows ? aggregateLlm(LLM, { from: state.from, to: state.to }) : null;
     $('llm-hint').textContent = useRows ? 'follows the date range only' : 'window-wide aggregate (no per-call rows)';
     function fromAggregate(o) {
-      return Object.keys(o || {}).map(function (k) { return { name: k, tokens: o[k].totalTokens, calls: o[k].calls, failures: o[k].failures }; })
+      return Object.keys(o || {}).map(function (k) { return { name: k, tokens: o[k].totalTokens, calls: o[k].calls, failures: o[k].failures, usageCalls: o[k].usageCalls != null ? o[k].usageCalls : o[k].calls }; })
         .sort(function (a, b) { return b.tokens - a.tokens; });
     }
     var dims = [
@@ -633,7 +635,7 @@ function toCsv(columns, rows) {
       var list = d[1].slice(0, 15);
       if (!hasData(d[0], list.length > 0, 'No LLM calls recorded')) return;
       chart(d[0], Object.assign(barOption(list.map(function (x) { return x.name; }),
-        [{ name: 'tokens', type: 'bar', itemStyle: { color: css('--purple') }, data: list.map(function (x) { return x.tokens; }) }], true), {}));
+        [{ name: 'tokens', type: 'bar', itemStyle: { color: css('--purple') }, data: list.map(function (x) { return x.calls > 0 && x.usageCalls === 0 ? null : x.tokens; }) }], true), {}));
     });
     if (hasData('ch-llm-time', useRows && agg.daily.length > 0, 'No per-call rows in this report')) {
       var days = agg.daily.map(function (d) { return d.day; });
@@ -744,15 +746,19 @@ function toCsv(columns, rows) {
     var t = agg.totals;
     var tokens = llm ? llm.totals.tokens : DATA.llm.totalTokens;
     var calls = llm ? llm.totals.calls : DATA.llm.calls;
+    var usageCalls = llm ? llm.totals.usageCalls : (DATA.llm.usageCalls != null ? DATA.llm.usageCalls : calls);
+    // Calls whose provider sent no usage are unknown, not zero tokens.
+    var llmSub = fmtN(calls) + ' calls' + (usageCalls < calls ? ', ' + fmtN(usageCalls) + ' reported usage' : '');
     var tasks = DATA.tasks || {};
     var cards = [
       ['Searches', fmtN(t.searches), fmtN(t.curates) + ' curates', ''],
       ['Shows', fmtN(t.shows), '', ''],
-      ['Select rate', fmtPct(DATA.usage.selectRate), 'window-wide', ''],
+      ['Selects per search', DATA.usage.selectsPerSearch == null ? '—' : DATA.usage.selectsPerSearch.toFixed(2),
+        fmtN(DATA.usage.totals.selects) + ' selects / ' + fmtN(DATA.usage.totals.searchesWithHits) + ' searches with hits, window-wide, selects not source-filtered', ''],
       ['Zero-result rate', fmtPct(t.searches ? t.zeroResult / t.searches : null), fmtN(t.zeroResult) + ' searches', t.zeroResult ? 'yellow' : ''],
       ['Feedback', '<span class="pos">+' + fmtN(t.positive) + '</span> / <span class="neg">−' + fmtN(t.negative) + '</span>',
         'net ' + (t.positive - t.negative >= 0 ? '+' : '−') + Math.abs(t.positive - t.negative), ''],
-      ['LLM tokens', fmtN(tokens), fmtN(calls) + ' calls', ''],
+      ['LLM tokens', calls > 0 && usageCalls === 0 ? 'unknown' : fmtN(tokens), llmSub, usageCalls < calls ? 'yellow' : ''],
       ['Task fail rate', fmtPct(tasks.failRate), fmtN(tasks.failed) + ' of ' + fmtN(tasks.runs) + ' runs, window-wide', tasks.failed ? 'red' : '']
     ];
     $('kpis').innerHTML = cards.map(function (c) {

package/dist/assets/ui/overview.js

@@ -70,10 +70,10 @@ function metricsSection(m) {
       ${tile("Searches", fmtNum(u.totals.searches), `${fmtNum(u.totals.zeroResultSearches)} with no results`)}
       ${tile("Shows", fmtNum(u.totals.shows), `${fmtNum(u.totals.distinctAssets)} distinct assets`)}
       ${tile("Curates", fmtNum(u.totals.curates))}
-      ${tile("Select rate", fmtPct(u.selectRate), `${fmtNum(u.totals.selects)} selects`)}
+      ${tile("Selects per search", u.selectsPerSearch == null ? "—" : u.selectsPerSearch.toFixed(2), `${fmtNum(u.totals.selects)} selects / ${fmtNum(u.totals.searchesWithHits)} searches with hits`)}
       ${tile("Median search", fmtMs(u.searchMedianMs))}
       ${tile("Feedback", `+${fmtNum(m.feedback.totals.positive)} / -${fmtNum(m.feedback.totals.negative)}`, "positive / negative")}
-      ${tile("LLM calls", fmtNum(m.llm.calls), `${fmtNum(m.llm.failures)} failed, ${fmtNum(m.llm.totalTokens)} tokens`)}
+      ${tile("LLM calls", fmtNum(m.llm.calls), `${fmtNum(m.llm.failures)} failed, ${m.llm.calls > 0 && m.llm.usageCalls === 0 ? "unknown" : fmtNum(m.llm.totalTokens)} tokens`)}
       ${tile("Pending proposals", fmtNum(m.proposals.byStatus.pending ?? 0))}
       ${tile("Task runs", fmtNum(m.tasks.runs), `${fmtNum(m.tasks.failed)} failed`)}
       ${tile("Index builds", fmtNum(m.index.runs), `median ${fmtMs(m.index.medianMs)}`)}

package/dist/commands/health/llm-usage.js

@@ -21,6 +21,13 @@ function emptyLlmUsageStageAggregate() {
         failures: 0,
     };
 }
+/** True when the provider response carried any token count. Absent usage is unknown, not zero. */
+export function hasTokenUsage(record) {
+    return (record.promptTokens !== undefined ||
+        record.completionTokens !== undefined ||
+        record.totalTokens !== undefined ||
+        record.reasoningTokens !== undefined);
+}
 /** A zeroed aggregate — also the value health reports when it could not read state.db at all (#791). */
 export function emptyLlmUsageAggregate() {
     return { ...emptyLlmUsageStageAggregate(), byStage: {}, byProcess: {}, byEngine: {} };
@@ -28,7 +35,7 @@ export function emptyLlmUsageAggregate() {
 /**
  * Aggregate `llm_usage` events (#576) into a window total plus a per-stage
  * breakdown of call count, wall-time, and token usage. Token fields absent from
- * a best-effort record contribute 0. Calls with no `stage` land under
+ * a best-effort record add nothing and the call is left out of `usageCalls`. Calls with no `stage` land under
  * {@link UNATTRIBUTED_STAGE}.
  */
 export function summarizeLlmUsage(events) {
@@ -47,11 +54,18 @@ export function summarizeLlmUsage(events) {
             dimensions.push(groups[key]);
         }
         for (const target of [aggregate, ...dimensions]) {
+            target.usageCalls ??= 0;
+            target.reasoningCalls ??= 0;
             target.calls += 1;
+            if (hasTokenUsage(record))
+                target.usageCalls += 1;
+            if (record.reasoningTokens !== undefined)
+                target.reasoningCalls += 1;
             target.totalDurationMs += record.durationMs;
             target.promptTokens += record.promptTokens ?? 0;
             target.completionTokens += record.completionTokens ?? 0;
-            target.totalTokens += record.totalTokens ?? 0;
+            // A call without a total counts as prompt + completion, as the per-day metrics rows do.
+            target.totalTokens += record.totalTokens ?? (record.promptTokens ?? 0) + (record.completionTokens ?? 0);
             target.reasoningTokens += record.reasoningTokens ?? 0;
             if (record.outcome === "error")
                 target.failures += 1;

package/dist/commands/health/stash-exposure.js

@@ -9,18 +9,35 @@
  * is when secret assets are git-TRACKED **and** a remote is configured — only
  * then can a `git push` exfiltrate tokens/keys. Warn on exactly that
  * combination; stay silent on the tracked-but-no-remote opt-in so the advisory
- * catches the exposure without nagging the intentional backup.
+ * catches the exposure without nagging the intentional backup. A stash whose
+ * `.gitignore` carries the intentional-tracking marker has acknowledged the
+ * risk, so it is not warned about at all.
  */
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { STASH_GITIGNORE_TRACK_SECRETS_MARKER } from "../sources/stash-skeleton.js";
 const realGit = (stashDir, args) => {
     const result = spawnSync("git", ["-C", stashDir, ...args], { encoding: "utf8", timeout: 5_000 });
     return { ok: result.status === 0, stdout: (result.stdout ?? "").trim() };
 };
+/** True when the stash `.gitignore` carries the explicit intentional-tracking marker. */
+function hasIntentionalTrackingMarker(stashDir) {
+    try {
+        return fs.readFileSync(path.join(stashDir, ".gitignore"), "utf8").includes(STASH_GITIGNORE_TRACK_SECRETS_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Build the `stash-git-exposure` advisory, or `undefined` when there is nothing
- * to warn about (not a git repo, no tracked env/secret assets, or no remote).
+ * to warn about (tracking acknowledged by the marker, not a git repo, no
+ * tracked env/secret assets, or no remote).
  */
 export function collectStashExposureAdvisory(stashDir, git = realGit) {
+    if (hasIntentionalTrackingMarker(stashDir))
+        return undefined;
     // Not a git work tree → nothing to expose.
     if (!git(stashDir, ["rev-parse", "--is-inside-work-tree"]).ok)
         return undefined;
@@ -37,10 +54,11 @@ export function collectStashExposureAdvisory(stashDir, git = realGit) {
         kind: "deterministic",
         status: "warn",
         confidence: "high",
-        message: `${trackedFiles.length} env/secret file(s) are git-tracked AND a remote is configured — ` +
+        message: `Bundle at ${stashDir}: ${trackedFiles.length} env/secret file(s) are git-tracked AND a remote is configured — ` +
             `a 'git push' can leak tokens/keys (${preview}). ` +
             "Run 'git rm --cached' on them (a .gitignore rule alone does NOT untrack already-tracked " +
-            "files) and then add env/+secrets/ to .gitignore to prevent recurrence (akm bundle create scaffolds it).",
-        evidence: { trackedSecretFiles: trackedFiles },
+            "files) and then add env/+secrets/ to .gitignore to prevent recurrence (akm bundle create scaffolds it), " +
+            `or, to keep tracking them on purpose, add '${STASH_GITIGNORE_TRACK_SECRETS_MARKER}' to .gitignore.`,
+        evidence: { bundleRoot: stashDir, trackedSecretFiles: trackedFiles },
     };
 }

package/dist/commands/health/type-directory-check.js

@@ -22,28 +22,21 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { buildFileContext } from "../../indexer/walk/file-context.js";
+import { declaredTypeForPath } from "../../indexer/walk/matchers.js";
 /**
- * Directory → declared-type map, mirroring `DIR_TYPE_MAP` in
- * `src/indexer/walk/matchers.ts` minus its per-directory extension test —
- * this check only needs "which type does this directory declare", not which
- * extensions it accepts. Keep in sync if `DIR_TYPE_MAP` gains, renames, or
- * removes a directory.
+ * The type the entry's location declares under the `akm` stash rules, derived
+ * with the indexer's own directory predicates (see `declaredTypeForPath`).
+ * Other adapters, and paths outside the component root, declare nothing.
  */
-const DECLARED_DIR_TYPES = {
-    memories: "memory",
-    knowledge: "knowledge",
-    commands: "command",
-    agents: "agent",
-    workflows: "workflow",
-    facts: "fact",
-    lessons: "lesson",
-    sessions: "session",
-    instructions: "instruction",
-    scripts: "script",
-    env: "env",
-    secrets: "secret",
-    tasks: "task",
-};
+function declaredTypeFor(entry) {
+    if (entry.adapterId !== "akm" || !entry.root)
+        return undefined;
+    const rel = path.relative(entry.root, entry.filePath);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return undefined;
+    return declaredTypeForPath(buildFileContext(entry.root, entry.filePath));
+}
 const realReadFile = (absPath) => {
     try {
         return fs.readFileSync(absPath, "utf8");
@@ -52,31 +45,6 @@ const realReadFile = (absPath) => {
         return undefined;
     }
 };
-/**
- * The type a file's directory declares, mirroring the `classifyByDirectory` /
- * `classifyByParentDirHint` precedence in matchers.ts: the immediate parent
- * directory wins when it is itself typed (parentDirHint, specificity 15);
- * otherwise the outermost typed ancestor wins (directoryMatcher, specificity
- * 10, which walks root-to-leaf and returns on the first hit).
- */
-function declaredTypeForPath(absPath) {
-    const segments = path
-        .dirname(absPath)
-        .split(path.sep)
-        .filter((seg) => seg.length > 0);
-    const immediateParent = segments.at(-1);
-    if (immediateParent) {
-        const parentType = DECLARED_DIR_TYPES[immediateParent];
-        if (parentType)
-            return { dir: immediateParent, type: parentType };
-    }
-    for (const seg of segments) {
-        const type = DECLARED_DIR_TYPES[seg];
-        if (type)
-            return { dir: seg, type };
-    }
-    return undefined;
-}
 /**
  * Best-effort explanation for why `classifyBySmartMd` (matchers.ts) would
  * have produced `resolvedType` for this content, in the SAME precedence
@@ -110,7 +78,7 @@ function explainOverride(resolvedType, content) {
 }
 /**
  * Compare every indexed entry's resolved type against the type its
- * directory declares (see {@link DECLARED_DIR_TYPES}), and return one
+ * directory declares (see {@link declaredTypeFor}), and return one
  * {@link TypeDirectoryDisagreement} per mismatch, sorted by path. Entries
  * outside any declared-type directory are not checked — this is only the
  * "directory declares type" invariant.
@@ -118,15 +86,15 @@ function explainOverride(resolvedType, content) {
 export function collectTypeDirectoryDisagreements(entries, readFile = realReadFile) {
     const disagreements = [];
     for (const entry of entries) {
-        const declared = declaredTypeForPath(entry.filePath);
-        if (!declared || declared.type === entry.type)
+        const declared = declaredTypeFor(entry);
+        if (!declared || declared === entry.type)
             continue;
         const content = readFile(entry.filePath);
         const explanation = content === undefined ? undefined : explainOverride(entry.type, content);
         disagreements.push({
             path: entry.filePath,
             resolved: entry.type,
-            expected: declared.type,
+            expected: declared,
             winner: explanation?.winner ?? "unknown",
             knownGoodOverride: explanation?.knownGoodOverride ?? false,
         });

package/dist/commands/health.js

@@ -10,6 +10,7 @@ import { classifyPathAccess, describeInaccessiblePath } from "../core/path-acces
 import { getConfigPath, getDataDir, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, listPendingStateMigrations, openStateDatabaseWithReport, withStateDb, } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { probeLlmEndpoint } from "../llm/client.js";
 import { openDatabase } from "../storage/database.js";
 import { insertEvent } from "../storage/repositories/events-repository.js";
@@ -251,24 +252,36 @@ function gatherAncillaryAdvisories(db, options, egressConfigView) {
     const indexStateMismatch = detectIndexStateGenerationMismatch(db);
     if (indexStateMismatch)
         advisories.push(indexStateMismatch);
-    // 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
-    // stash — the common unit-test case. Trade-off: a stash manually pointed at a
-    // bare subdirectory of a parent git repo (no `.git` of its own) is not
-    // checked. akm-init always creates `.git` at the stash root, so any
-    // akm-initialised stash is covered; this only skips hand-pointed nested ones.
+    // Surface a `stash-git-exposure` advisory for each bundle whose env/secret
+    // assets are git-tracked AND that has a remote (the leak moment). Every
+    // configured bundle is checked, not just the working stash; each honours the
+    // intentional-tracking marker in its own `.gitignore`. Best-effort.
+    // Cheap guard: only shell out to git for a bundle root with its OWN `.git`
+    // (or when a test injected a fake seam), so the hot path never spawns for
+    // non-git bundles. Trade-off: a bundle pointed at a bare subdirectory of a
+    // parent git repo (no `.git` of its own) is not checked; akm-init and
+    // writable git installs put `.git` at the bundle root.
+    let exposureRoots = [];
     try {
         const exposureStashDir = options.stashDir ?? resolveStashDir();
-        if (options.stashExposureGit || fs.existsSync(path.join(exposureStashDir, ".git"))) {
-            const stashExposure = collectStashExposureAdvisory(exposureStashDir, options.stashExposureGit);
-            if (stashExposure)
-                advisories.push(stashExposure);
-        }
+        exposureRoots = [exposureStashDir];
+        exposureRoots = resolveSourceEntries(exposureStashDir).map((source) => source.path);
     }
     catch {
-        // Non-fatal — a git/probe failure must not abort the health report.
+        // An unreadable working stash skips the advisory; an unreadable bundle
+        // config still checks the working stash. Neither aborts the report.
+    }
+    for (const root of new Set(exposureRoots.map((dir) => path.resolve(dir)))) {
+        try {
+            if (options.stashExposureGit || fs.existsSync(path.join(root, ".git"))) {
+                const stashExposure = collectStashExposureAdvisory(root, options.stashExposureGit);
+                if (stashExposure)
+                    advisories.push(stashExposure);
+            }
+        }
+        catch {
+            // Non-fatal — a git/probe failure must not abort the health report.
+        }
     }
     // 08 surfaces: the remaining read-only advisory group (binary-config-skew,
     // egress-endpoints). Best-effort — a filesystem probe failure must not abort
@@ -346,7 +359,24 @@ function detectTypeDirectoryDisagreements(stashRoot) {
         indexDb = openReadonlyExistingDatabase(getDbPath());
         if (!indexDb)
             return undefined;
-        const entries = getAllEntries(indexDb).map((entry) => ({ filePath: entry.filePath, type: entry.type }));
+        // Directory intent is read only from inside the component root that owns the entry.
+        // Both spellings of each root: indexed paths may be realpaths (a symlinked
+        // stash, macOS /var -> /private/var) while config holds the configured path.
+        const roots = resolveSourceEntries(stashRoot).flatMap((source) => {
+            const resolved = path.resolve(source.path);
+            try {
+                return [resolved, fs.realpathSync.native(resolved)];
+            }
+            catch {
+                return [resolved];
+            }
+        });
+        const entries = getAllEntries(indexDb).map((entry) => ({
+            filePath: entry.filePath,
+            type: entry.type,
+            adapterId: entry.adapterId,
+            root: roots.filter((root) => entry.filePath.startsWith(root + path.sep)).sort((a, b) => b.length - a.length)[0] ?? "",
+        }));
         return buildTypeDirectoryAdvisory(entries, undefined, (absPath) => absPath.startsWith(stashRoot) ? path.relative(stashRoot, absPath) : absPath);
     }
     catch {

package/dist/commands/metrics/collect.js

@@ -4,6 +4,7 @@
 import { decodeLlmUsageRecord } from "../../llm/usage-telemetry.js";
 import { decodeTaskHistoryMetadata } from "../../storage/repositories/task-history-repository.js";
 import { computeWallTimeStats } from "../health/improve-metrics.js";
+import { hasTokenUsage } from "../health/llm-usage.js";
 import { computeValenceScore } from "../improve/feedback-valence.js";
 const DAY_MS = 86_400_000;
 /** Utility is a score in [0, 1], reported in ten equal buckets. */
@@ -111,6 +112,8 @@ export function llmRowsFromEvents(events) {
                 completionTokens: 0,
                 totalTokens: 0,
                 reasoningTokens: 0,
+                usageCalls: 0,
+                reasoningCalls: 0,
             };
             rows.set(key, row);
         }
@@ -121,6 +124,10 @@ export function llmRowsFromEvents(events) {
         // A call without a total counts as prompt + completion, as the dashboard did per call.
         row.totalTokens += record.totalTokens ?? (record.promptTokens ?? 0) + (record.completionTokens ?? 0);
         row.reasoningTokens += record.reasoningTokens ?? 0;
+        if (hasTokenUsage(record))
+            row.usageCalls += 1;
+        if (record.reasoningTokens !== undefined)
+            row.reasoningCalls += 1;
     }
     return [...rows.values()];
 }
@@ -260,10 +267,11 @@ function buildUsage(input, rows) {
             curates,
             selects: input.selects.length,
             zeroResultSearches,
+            searchesWithHits,
             distinctAssets: assets.size,
             distinctQueries: queries.size,
         },
-        selectRate: searchesWithHits > 0 ? input.selects.length / searchesWithHits : null,
+        selectsPerSearch: searchesWithHits > 0 ? input.selects.length / searchesWithHits : null,
         searchMedianMs: median(searchMs),
         daily: [...days.values()].sort((a, b) => a.day.localeCompare(b.day)),
         topAssets: [...assets.values()]

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

@@ -131,7 +131,7 @@ export async function akmMetrics(options = {}) {
     if (index.note)
         notes.push(index.note);
     const filter = { sinceIso, untilIso, source: SOURCE };
-    notes.push("Selects come from the events stream, which records no source, so they are counted for every source.");
+    notes.push("Selects come from the events stream, which records no source or search id, so they are counted for every source and selects per search is a ratio, not a conversion rate.");
     const input = {
         window: { since: sinceIso, until: untilIso },
         source: SOURCE,

package/dist/commands/metrics/report-view.js

@@ -20,18 +20,27 @@ function sourceFacts(counts) {
     const entries = Object.entries(counts);
     return entries.length === 0 ? "-" : entries.map(([k, v]) => `${k}=${v}`).join(" ");
 }
+/** A token sum, or `unknown` when calls were made and none reported usage (never a measured zero). */
+function tokens(n, a) {
+    return a.calls > 0 && a.usageCalls === 0 ? "unknown" : int(n);
+}
+/** `reported/calls`; `-` for an aggregate that carries no coverage. */
+function usageCoverage(a) {
+    return a.usageCalls === undefined ? "-" : `${a.usageCalls}/${a.calls}`;
+}
 function llmRows(group) {
     return Object.entries(group).map(([name, a]) => [
         name,
         int(a.calls),
         int(a.failures),
-        int(a.promptTokens),
-        int(a.completionTokens),
-        int(a.totalTokens),
+        tokens(a.promptTokens, a),
+        tokens(a.completionTokens, a),
+        tokens(a.totalTokens, a),
+        usageCoverage(a),
         ms(a.totalDurationMs),
     ]);
 }
-const LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "time"];
+const LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "calls with usage", "time"];
 export function buildMetricsView(r, detail) {
     const brief = detail === "brief";
     const cut = (items) => (brief ? items.slice(0, BRIEF_LIST_LIMIT) : items);
@@ -45,7 +54,8 @@ export function buildMetricsView(r, detail) {
                 ["shows", int(usage.totals.shows)],
                 ["curates", int(usage.totals.curates)],
                 ["selects", int(usage.totals.selects)],
-                ["select rate", pct(usage.selectRate)],
+                ["searches with hits", int(usage.totals.searchesWithHits)],
+                ["selects per search with hits", fixed(usage.selectsPerSearch, 2)],
                 [
                     "zero-result searches",
                     `${usage.totals.zeroResultSearches} (${pct(searches === 0 ? null : usage.totals.zeroResultSearches / searches)})`,
@@ -154,10 +164,11 @@ export function buildMetricsView(r, detail) {
             facts: [
                 ["calls", int(llm.calls)],
                 ["failed", int(llm.failures)],
-                ["prompt tokens", int(llm.promptTokens)],
-                ["completion tokens", int(llm.completionTokens)],
-                ["reasoning tokens", int(llm.reasoningTokens)],
-                ["total tokens", int(llm.totalTokens)],
+                ["calls with token usage", usageCoverage(llm)],
+                ["prompt tokens", tokens(llm.promptTokens, llm)],
+                ["completion tokens", tokens(llm.completionTokens, llm)],
+                ["reasoning tokens", llm.calls > 0 && llm.reasoningCalls === 0 ? "unknown" : tokens(llm.reasoningTokens, llm)],
+                ["total tokens", tokens(llm.totalTokens, llm)],
                 ["time", ms(llm.totalDurationMs)],
             ],
             tables: [

package/dist/commands/sources/source-add.js

@@ -219,7 +219,9 @@ async function addRegistryStash(ref, stashDir, explicitName, writable, position
         : [];
     const synced = await syncFromRef(ref, {
         writable: effectiveWritable,
-        ...(effectiveWritable && priorLock?.localRoot ? { writableRoot: priorLock.localRoot } : {}),
+        // Reuse a checkout only when the install is already writable; promoting a
+        // read-only snapshot (#1296) materializes a fresh checkout instead.
+        ...(existingWritable && priorLock?.localRoot ? { writableRoot: priorLock.localRoot } : {}),
         ...(requiredRoots.length > 0 ? { writableRequiredRoots: requiredRoots } : {}),
         ...(credentialRef
             ? { credential: resolveSecret(credentialRef, storeSecretResolver.resolveSecret) }
@@ -253,8 +255,10 @@ async function addRegistryStash(ref, stashDir, explicitName, writable, position
         localRoot: synced.contentDir,
         installedAt: synced.syncedAt,
     });
-    // Clean up the old materialized root on re-install (moved cache).
-    if (!effectiveWritable && priorLocalRoot && path.resolve(priorLocalRoot) !== path.resolve(synced.contentDir)) {
+    // Clean up the old materialized root on re-install (moved cache). A writable
+    // checkout may hold local work and is never removed; a read-only snapshot
+    // (including one just promoted to writable, #1296) is.
+    if (!existingWritable && priorLocalRoot && path.resolve(priorLocalRoot) !== path.resolve(synced.contentDir)) {
         try {
             fs.rmSync(priorLocalRoot, { recursive: true, force: true });
         }

package/dist/core/common.js

@@ -495,7 +495,10 @@ export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
     try {
         if (controller.signal.aborted)
             throw controller.signal.reason ?? new Error(`Request aborted: ${url}`);
-        return await fetch(url, { ...opts, signal: controller.signal });
+        // `timeout: false` turns off Bun's independent five-minute socket-idle timer,
+        // which would otherwise cut a longer AKM deadline short. The AbortController
+        // signal (deadline + caller cancel) remains the only bound on the request.
+        return await fetch(url, { ...opts, signal: controller.signal, timeout: false });
     }
     catch (err) {
         if (err instanceof DOMException && err.name === "AbortError") {

package/dist/indexer/walk/matchers.js

@@ -194,6 +194,16 @@ function classifyByParentDirHint(ctx) {
     }
     return matchDirectoryHint(parentDir, ctx, 15);
 }
+/**
+ * The type a file's location declares, from the same directory rules the
+ * indexer applies: parent-directory hint (specificity 15) over the outermost
+ * typed ancestor (10), each honouring the rule's extension predicate, the
+ * `README.md` documentation exception and nested skill resources. `undefined`
+ * when no directory rule claims the file. Path fields only; no bytes are read.
+ */
+export function declaredTypeForPath(ctx) {
+    return (classifyByParentDirHint(ctx) ?? classifyByDirectory(ctx))?.type;
+}
 function classifyBySmartMd(ctx) {
     if (ctx.ext !== ".md")
         return null;

package/dist/scripts/akm-migrate-node.js

@@ -37171,12 +37171,24 @@ function keyLooksSecret(key) {
   const lower = key.toLowerCase();
   return SECRET_KEY_HINTS.some((hint) => lower.includes(hint));
 }
+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);
+}
 function valueLooksSecret(value) {
   const s = value.trim();
   if (s.length < 20 || /\s/.test(s))
     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;
@@ -37218,7 +37230,7 @@ function walkSecretShaped(params, hit) {
   for (const [k, v] of Object.entries(params))
     walk(v, k, k);
 }
-var SECRET_KEY_HINTS, SECRET_VALUE_PREFIX, MOVE_TO_ENV;
+var SECRET_KEY_HINTS, SECRET_VALUE_PREFIX, PATH_LIKE, UUID, MOVE_TO_ENV;
 var init_param_secrets = __esm(() => {
   SECRET_KEY_HINTS = [
     "secret",
@@ -37239,6 +37251,8 @@ var init_param_secrets = __esm(() => {
     "client_secret"
   ];
   SECRET_VALUE_PREFIX = /^(sk-|rk-|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|xox[baprs]-|AKIA|ASIA|AIza|ya29\.|-----BEGIN)/;
+  PATH_LIKE = /^(\/|\.{1,2}[\\/]|~[\\/]|[A-Za-z]:[\\/]|\\\\)|^[\w.-]+[\\/][^?#]*\.[A-Za-z0-9]{1,8}$/;
+  UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
   MOVE_TO_ENV = "Workflow params are copied verbatim into every native unit execution context and returned in `akm workflow run` and " + "`akm workflow status` output — move secrets to an env binding (`env:` ref), whose value native execution resolves " + "only at dispatch instead of storing it as a run param.";
 });
 
@@ -41924,10 +41938,10 @@ var init_marked_esm = __esm(() => {
 
 // src/core/asset/markdown-link-targets.ts
 function markdownLinkTargets(body, references) {
-  const tokens = markdown.lexer(body);
+  const tokens2 = markdown.lexer(body);
   const definitions = new Map;
   if (references) {
-    markdown.walkTokens(tokens, (token) => {
+    markdown.walkTokens(tokens2, (token) => {
       if (token.type !== "def")
         return;
       const definition = /^\s*\[([^\]]+)\]:\s*(\S+)/.exec(token.raw);
@@ -41936,7 +41950,7 @@ function markdownLinkTargets(body, references) {
     });
   }
   const targets = [];
-  markdown.walkTokens(tokens, (token) => {
+  markdown.walkTokens(tokens2, (token) => {
     if (token.type !== "link" && token.type !== "image")
       return;
     const inline = /^!?\[[\s\S]*\]\(/.test(token.raw);
@@ -62450,7 +62464,7 @@ var require_HTMLParser = __commonJS((exports, module) => {
       }
     }
     htmlparser.testTokenizer = function(input2, initialState, lastStartTag, charbychar) {
-      var tokens = [];
+      var tokens2 = [];
       switch (initialState) {
         case "PCDATA state":
           tokenizer = data_state;
@@ -62472,16 +62486,16 @@ var require_HTMLParser = __commonJS((exports, module) => {
         flushText();
         switch (t) {
           case 1:
-            if (tokens.length > 0 && tokens[tokens.length - 1][0] === "Character") {
-              tokens[tokens.length - 1][1] += value;
+            if (tokens2.length > 0 && tokens2[tokens2.length - 1][0] === "Character") {
+              tokens2[tokens2.length - 1][1] += value;
             } else
-              tokens.push(["Character", value]);
+              tokens2.push(["Character", value]);
             break;
           case 4:
-            tokens.push(["Comment", value]);
+            tokens2.push(["Comment", value]);
             break;
           case 5:
-            tokens.push([
+            tokens2.push([
               "DOCTYPE",
               value,
               arg3 === undefined ? null : arg3,
@@ -62502,10 +62516,10 @@ var require_HTMLParser = __commonJS((exports, module) => {
             var token = ["StartTag", value, attrs];
             if (arg4)
               token.push(true);
-            tokens.push(token);
+            tokens2.push(token);
             break;
           case 3:
-            tokens.push(["EndTag", value]);
+            tokens2.push(["EndTag", value]);
             break;
           case -1:
             break;
@@ -62519,7 +62533,7 @@ var require_HTMLParser = __commonJS((exports, module) => {
         }
         this.parse("", true);
       }
-      return tokens;
+      return tokens2;
     };
     return htmlparser;
   }
@@ -68893,18 +68907,25 @@ function sourceFacts(counts) {
   const entries = Object.entries(counts);
   return entries.length === 0 ? "-" : entries.map(([k, v]) => `${k}=${v}`).join(" ");
 }
+function tokens(n, a) {
+  return a.calls > 0 && a.usageCalls === 0 ? "unknown" : int(n);
+}
+function usageCoverage(a) {
+  return a.usageCalls === undefined ? "-" : `${a.usageCalls}/${a.calls}`;
+}
 function llmRows(group) {
   return Object.entries(group).map(([name, a]) => [
     name,
     int(a.calls),
     int(a.failures),
-    int(a.promptTokens),
-    int(a.completionTokens),
-    int(a.totalTokens),
+    tokens(a.promptTokens, a),
+    tokens(a.completionTokens, a),
+    tokens(a.totalTokens, a),
+    usageCoverage(a),
     ms(a.totalDurationMs)
   ]);
 }
-var LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "time"];
+var LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "calls with usage", "time"];
 function buildMetricsView(r, detail) {
   const brief = detail === "brief";
   const cut = (items) => brief ? items.slice(0, BRIEF_LIST_LIMIT) : items;
@@ -68918,7 +68939,8 @@ function buildMetricsView(r, detail) {
         ["shows", int(usage.totals.shows)],
         ["curates", int(usage.totals.curates)],
         ["selects", int(usage.totals.selects)],
-        ["select rate", pct(usage.selectRate)],
+        ["searches with hits", int(usage.totals.searchesWithHits)],
+        ["selects per search with hits", fixed(usage.selectsPerSearch, 2)],
         [
           "zero-result searches",
           `${usage.totals.zeroResultSearches} (${pct(searches === 0 ? null : usage.totals.zeroResultSearches / searches)})`
@@ -69025,10 +69047,11 @@ function buildMetricsView(r, detail) {
       facts: [
         ["calls", int(llm.calls)],
         ["failed", int(llm.failures)],
-        ["prompt tokens", int(llm.promptTokens)],
-        ["completion tokens", int(llm.completionTokens)],
-        ["reasoning tokens", int(llm.reasoningTokens)],
-        ["total tokens", int(llm.totalTokens)],
+        ["calls with token usage", usageCoverage(llm)],
+        ["prompt tokens", tokens(llm.promptTokens, llm)],
+        ["completion tokens", tokens(llm.completionTokens, llm)],
+        ["reasoning tokens", llm.calls > 0 && llm.reasoningCalls === 0 ? "unknown" : tokens(llm.reasoningTokens, llm)],
+        ["total tokens", tokens(llm.totalTokens, llm)],
         ["time", ms(llm.totalDurationMs)]
       ],
       tables: [
@@ -72919,15 +72942,15 @@ var SHELL_ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
 function shellStableV2Executable(executable) {
   return executable === "akm" || executable.includes("/");
 }
-function skipEnvAssignmentPrefix(tokens) {
-  if (tokens[0] !== "env")
-    return { tokens, envWrapped: false };
+function skipEnvAssignmentPrefix(tokens2) {
+  if (tokens2[0] !== "env")
+    return { tokens: tokens2, envWrapped: false };
   let index = 1;
-  while (index < tokens.length && SHELL_ASSIGNMENT_WORD.test(tokens[index]))
+  while (index < tokens2.length && SHELL_ASSIGNMENT_WORD.test(tokens2[index]))
     index += 1;
-  if (index >= tokens.length)
-    return { tokens, envWrapped: false };
-  return { tokens: tokens.slice(index), envWrapped: true };
+  if (index >= tokens2.length)
+    return { tokens: tokens2, envWrapped: false };
+  return { tokens: tokens2.slice(index), envWrapped: true };
 }
 var KNOWN_PROMPT_REF_FAMILIES = new Set([
   "agents",
@@ -73359,16 +73382,16 @@ function migratedObject(data) {
     const command = exactString(data.command, "command", true).trim();
     if (/['"\\]/.test(command))
       return "shell-quoting-changes-v2-whitespace-split-semantics";
-    const tokens = command.split(/\s+/).filter(Boolean);
-    if (tokens.length === 0 || tokens.some((token) => !SAFE_V2_COMMAND_TOKEN.test(token))) {
+    const tokens2 = command.split(/\s+/).filter(Boolean);
+    if (tokens2.length === 0 || tokens2.some((token) => !SAFE_V2_COMMAND_TOKEN.test(token))) {
       return "shell-operators-change-v2-literal-argv-semantics";
     }
-    const { tokens: targetTokens, envWrapped } = skipEnvAssignmentPrefix(tokens);
+    const { tokens: targetTokens, envWrapped } = skipEnvAssignmentPrefix(tokens2);
     const executable = targetTokens[0];
     if (SHELL_ASSIGNMENT_WORD.test(executable) || !envWrapped && !shellStableV2Executable(executable)) {
       return "shell-command-resolution-changes-v2-literal-argv-semantics";
     }
-    output2.run = tokens.join(" ");
+    output2.run = tokens2.join(" ");
     addSharedNonPromptOverrides(data, akm);
   }
   output2.akm = akm;

package/dist/scripts/akm-migrate.js

@@ -37170,12 +37170,24 @@ function keyLooksSecret(key) {
   const lower = key.toLowerCase();
   return SECRET_KEY_HINTS.some((hint) => lower.includes(hint));
 }
+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);
+}
 function valueLooksSecret(value) {
   const s = value.trim();
   if (s.length < 20 || /\s/.test(s))
     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;
@@ -37217,7 +37229,7 @@ function walkSecretShaped(params, hit) {
   for (const [k, v] of Object.entries(params))
     walk(v, k, k);
 }
-var SECRET_KEY_HINTS, SECRET_VALUE_PREFIX, MOVE_TO_ENV;
+var SECRET_KEY_HINTS, SECRET_VALUE_PREFIX, PATH_LIKE, UUID, MOVE_TO_ENV;
 var init_param_secrets = __esm(() => {
   SECRET_KEY_HINTS = [
     "secret",
@@ -37238,6 +37250,8 @@ var init_param_secrets = __esm(() => {
     "client_secret"
   ];
   SECRET_VALUE_PREFIX = /^(sk-|rk-|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|xox[baprs]-|AKIA|ASIA|AIza|ya29\.|-----BEGIN)/;
+  PATH_LIKE = /^(\/|\.{1,2}[\\/]|~[\\/]|[A-Za-z]:[\\/]|\\\\)|^[\w.-]+[\\/][^?#]*\.[A-Za-z0-9]{1,8}$/;
+  UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
   MOVE_TO_ENV = "Workflow params are copied verbatim into every native unit execution context and returned in `akm workflow run` and " + "`akm workflow status` output \u2014 move secrets to an env binding (`env:` ref), whose value native execution resolves " + "only at dispatch instead of storing it as a run param.";
 });
 
@@ -41923,10 +41937,10 @@ var init_marked_esm = __esm(() => {
 
 // src/core/asset/markdown-link-targets.ts
 function markdownLinkTargets(body, references) {
-  const tokens = markdown.lexer(body);
+  const tokens2 = markdown.lexer(body);
   const definitions = new Map;
   if (references) {
-    markdown.walkTokens(tokens, (token) => {
+    markdown.walkTokens(tokens2, (token) => {
       if (token.type !== "def")
         return;
       const definition = /^\s*\[([^\]]+)\]:\s*(\S+)/.exec(token.raw);
@@ -41935,7 +41949,7 @@ function markdownLinkTargets(body, references) {
     });
   }
   const targets = [];
-  markdown.walkTokens(tokens, (token) => {
+  markdown.walkTokens(tokens2, (token) => {
     if (token.type !== "link" && token.type !== "image")
       return;
     const inline = /^!?\[[\s\S]*\]\(/.test(token.raw);
@@ -62449,7 +62463,7 @@ var require_HTMLParser = __commonJS((exports, module) => {
       }
     }
     htmlparser.testTokenizer = function(input2, initialState, lastStartTag, charbychar) {
-      var tokens = [];
+      var tokens2 = [];
       switch (initialState) {
         case "PCDATA state":
           tokenizer = data_state;
@@ -62471,16 +62485,16 @@ var require_HTMLParser = __commonJS((exports, module) => {
         flushText();
         switch (t) {
           case 1:
-            if (tokens.length > 0 && tokens[tokens.length - 1][0] === "Character") {
-              tokens[tokens.length - 1][1] += value;
+            if (tokens2.length > 0 && tokens2[tokens2.length - 1][0] === "Character") {
+              tokens2[tokens2.length - 1][1] += value;
             } else
-              tokens.push(["Character", value]);
+              tokens2.push(["Character", value]);
             break;
           case 4:
-            tokens.push(["Comment", value]);
+            tokens2.push(["Comment", value]);
             break;
           case 5:
-            tokens.push([
+            tokens2.push([
               "DOCTYPE",
               value,
               arg3 === undefined ? null : arg3,
@@ -62501,10 +62515,10 @@ var require_HTMLParser = __commonJS((exports, module) => {
             var token = ["StartTag", value, attrs];
             if (arg4)
               token.push(true);
-            tokens.push(token);
+            tokens2.push(token);
             break;
           case 3:
-            tokens.push(["EndTag", value]);
+            tokens2.push(["EndTag", value]);
             break;
           case -1:
             break;
@@ -62518,7 +62532,7 @@ var require_HTMLParser = __commonJS((exports, module) => {
         }
         this.parse("", true);
       }
-      return tokens;
+      return tokens2;
     };
     return htmlparser;
   }
@@ -68891,18 +68905,25 @@ function sourceFacts(counts) {
   const entries = Object.entries(counts);
   return entries.length === 0 ? "-" : entries.map(([k, v]) => `${k}=${v}`).join(" ");
 }
+function tokens(n, a) {
+  return a.calls > 0 && a.usageCalls === 0 ? "unknown" : int(n);
+}
+function usageCoverage(a) {
+  return a.usageCalls === undefined ? "-" : `${a.usageCalls}/${a.calls}`;
+}
 function llmRows(group) {
   return Object.entries(group).map(([name, a]) => [
     name,
     int(a.calls),
     int(a.failures),
-    int(a.promptTokens),
-    int(a.completionTokens),
-    int(a.totalTokens),
+    tokens(a.promptTokens, a),
+    tokens(a.completionTokens, a),
+    tokens(a.totalTokens, a),
+    usageCoverage(a),
     ms(a.totalDurationMs)
   ]);
 }
-var LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "time"];
+var LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "calls with usage", "time"];
 function buildMetricsView(r, detail) {
   const brief = detail === "brief";
   const cut = (items) => brief ? items.slice(0, BRIEF_LIST_LIMIT) : items;
@@ -68916,7 +68937,8 @@ function buildMetricsView(r, detail) {
         ["shows", int(usage.totals.shows)],
         ["curates", int(usage.totals.curates)],
         ["selects", int(usage.totals.selects)],
-        ["select rate", pct(usage.selectRate)],
+        ["searches with hits", int(usage.totals.searchesWithHits)],
+        ["selects per search with hits", fixed(usage.selectsPerSearch, 2)],
         [
           "zero-result searches",
           `${usage.totals.zeroResultSearches} (${pct(searches === 0 ? null : usage.totals.zeroResultSearches / searches)})`
@@ -69023,10 +69045,11 @@ function buildMetricsView(r, detail) {
       facts: [
         ["calls", int(llm.calls)],
         ["failed", int(llm.failures)],
-        ["prompt tokens", int(llm.promptTokens)],
-        ["completion tokens", int(llm.completionTokens)],
-        ["reasoning tokens", int(llm.reasoningTokens)],
-        ["total tokens", int(llm.totalTokens)],
+        ["calls with token usage", usageCoverage(llm)],
+        ["prompt tokens", tokens(llm.promptTokens, llm)],
+        ["completion tokens", tokens(llm.completionTokens, llm)],
+        ["reasoning tokens", llm.calls > 0 && llm.reasoningCalls === 0 ? "unknown" : tokens(llm.reasoningTokens, llm)],
+        ["total tokens", tokens(llm.totalTokens, llm)],
         ["time", ms(llm.totalDurationMs)]
       ],
       tables: [
@@ -72882,15 +72905,15 @@ var SHELL_ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
 function shellStableV2Executable(executable) {
   return executable === "akm" || executable.includes("/");
 }
-function skipEnvAssignmentPrefix(tokens) {
-  if (tokens[0] !== "env")
-    return { tokens, envWrapped: false };
+function skipEnvAssignmentPrefix(tokens2) {
+  if (tokens2[0] !== "env")
+    return { tokens: tokens2, envWrapped: false };
   let index = 1;
-  while (index < tokens.length && SHELL_ASSIGNMENT_WORD.test(tokens[index]))
+  while (index < tokens2.length && SHELL_ASSIGNMENT_WORD.test(tokens2[index]))
     index += 1;
-  if (index >= tokens.length)
-    return { tokens, envWrapped: false };
-  return { tokens: tokens.slice(index), envWrapped: true };
+  if (index >= tokens2.length)
+    return { tokens: tokens2, envWrapped: false };
+  return { tokens: tokens2.slice(index), envWrapped: true };
 }
 var KNOWN_PROMPT_REF_FAMILIES = new Set([
   "agents",
@@ -73322,16 +73345,16 @@ function migratedObject(data) {
     const command = exactString(data.command, "command", true).trim();
     if (/['"\\]/.test(command))
       return "shell-quoting-changes-v2-whitespace-split-semantics";
-    const tokens = command.split(/\s+/).filter(Boolean);
-    if (tokens.length === 0 || tokens.some((token) => !SAFE_V2_COMMAND_TOKEN.test(token))) {
+    const tokens2 = command.split(/\s+/).filter(Boolean);
+    if (tokens2.length === 0 || tokens2.some((token) => !SAFE_V2_COMMAND_TOKEN.test(token))) {
       return "shell-operators-change-v2-literal-argv-semantics";
     }
-    const { tokens: targetTokens, envWrapped } = skipEnvAssignmentPrefix(tokens);
+    const { tokens: targetTokens, envWrapped } = skipEnvAssignmentPrefix(tokens2);
     const executable = targetTokens[0];
     if (SHELL_ASSIGNMENT_WORD.test(executable) || !envWrapped && !shellStableV2Executable(executable)) {
       return "shell-command-resolution-changes-v2-literal-argv-semantics";
     }
-    output2.run = tokens.join(" ");
+    output2.run = tokens2.join(" ");
     addSharedNonPromptOverrides(data, akm);
   }
   output2.akm = akm;

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

@@ -56,7 +56,7 @@ 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`. |

package/docs/migration/release-notes/README.md

@@ -7,7 +7,6 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
-- [0.10.261020](0.10.261020.md) — Coordinated beta/stable channel switching, native Claude health, and automatic search-projection refresh.
 - [0.10.261019](0.10.261019.md) — The 0.10 series: 0.9.15 version floor, merged CLI spellings, `default`/`consolidate` strategies only, OpenCode 2, feedback-scaled ranking, and `0.10.YYMMNN` versions.
 - [0.9.19](0.9.19.md) — Bundle-scoped improve planning, proposal reopen, and consolidate/distill guardrails.
 - [0.9.17](0.9.17.md) — Retire proposals, declared links replacing the LLM entity graph, and scoped improve planning.

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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261020-beta",
+  "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": [

package/docs/migration/release-notes/0.10.261020.md

@@ -1,22 +0,0 @@
-# akm v0.10.261020 migration notes
-
-This beta fixes Claude plugin health reporting, adds coordinated channel
-switching, and reduces repeated fenced identifiers in search content.
-
-The next index pass refreshes existing content projections and changed embedding
-inputs automatically. No manual database or configuration migration is required
-when upgrading from 0.10.261019.
-
-After installing this beta, `akm upgrade --channel next` switches the CLI and
-installed Claude, Codex and OpenCode plugins together. The existing `--next`
-flag keeps its prior behavior. To return to stable, use
-`akm upgrade --channel latest`; if the target version is older, add
-`--allow-downgrade`. Changed settings receive backups, and the command reports
-any harness that could not finish switching. Restart the harness after updates.
-
-Claude health now uses native installation metadata. It reports conflicting or
-incomplete installation selections as unknown instead of choosing a cached
-version. This can change a previous warning without changing the installation.
-
-If upgrading from 0.9, first follow the
-[0.9 to 0.10 migration guide](../v0.9-to-v0.10.md).