akm-cli 0.9.1-beta.1 → 0.9.1-beta.3

package/CHANGELOG.md

@@ -6,7 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-## [0.9.1-beta.1] - 2026-08-13
+## [0.9.1-beta.3] - 2026-08-18
+
+### Fixed
+
+- Preserve multiline frontmatter descriptions when `akm lint --fix` quotes
+  colons, recover already-malformed quoted descriptions, and report a fix only
+  when the file actually changes.
+- Skip consolidation promotion proposals whose body already exists in a live
+  knowledge asset, preventing exact-content duplicates from recurring in the
+  proposal backlog.
+- Derive utility `last_used_at` values only from real user retrieval events
+  (`search`, `show`, and `curate`) instead of stamping assets with index time.
+- Compute the salience-distribution health metric over every positive,
+  non-missing salience value rather than a top-ranked 100-row slice, and report
+  the evaluated sample size.
+
+## [0.9.1-beta.2] - 2026-08-17
 
 ### Breaking changes & migration
 
@@ -361,6 +377,23 @@ what an upgrader reads first.
 
 ### Fixed
 
+- **Upgrading Node after installing akm now explains itself.** A native binding
+  is built for the Node ABI present at install time, so upgrading Node major
+  versions afterwards leaves akm reporting a bare Node internals message —
+  *"The module … was compiled against a different Node.js version"*, or on a
+  second attempt the even less helpful *"Module did not self-register"*. akm now
+  recognises that failure and answers with the one command that fixes it
+  (`npm rebuild better-sqlite3`), names the ABI actually running, and says
+  plainly that this is not a broken install.
+
+  The diagnostic had to move to do this. It wrapped the `require`, but
+  `require("better-sqlite3")` **succeeds** against a mismatched binding — the
+  package resolves its `.node` file lazily — so the error lands at
+  `new Database(...)` and the loader's handler never saw it. The previous text
+  telling the user to look for a version mismatch "in the error below" was
+  unreachable. Found by installing the published build under Node 22 and running
+  it under Node 24.
+
 - **akm's Node fallback no longer aborts at teardown on Node 24.** On Node
   24.19.0 and later, any command that opened a database could intermittently
   die with `node::RemoveEnvironmentCleanupHook … Assertion (env) != nullptr`

package/dist/cli/parse-args.js

@@ -45,8 +45,14 @@ export function parsePositiveIntFlag(raw, flagName = "--limit") {
     const trimmed = raw.trim();
     if (!trimmed)
         return undefined;
+    // Strict digits, matching parseNonNegativeIntFlag below. parseInt stops at the
+    // first non-digit, so "10x" silently became 10, "3.5" became 3, and
+    // "5 apples" became 5 — accepted rather than rejected as invalid.
+    if (!/^\d+$/.test(trimmed)) {
+        throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a positive integer.`, "INVALID_FLAG_VALUE");
+    }
     const parsed = parseInt(trimmed, 10);
-    if (Number.isNaN(parsed) || parsed <= 0) {
+    if (parsed <= 0) {
         throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a positive integer.`, "INVALID_FLAG_VALUE");
     }
     return parsed;

package/dist/commands/env/child-env.js

@@ -1,6 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { WIN32_SPAWN_ENV_FLOOR } from "../../core/spawn-env.js";
 const CLEAN_ENV_ALLOWLIST = [
     "HOME",
     "PATH",
@@ -38,6 +39,19 @@ export function buildChildEnv(parentEnv, options) {
             if (parentEnv[key] !== undefined)
                 base[key] = parentEnv[key];
         }
+        // The allowlist above is POSIX-shaped. On Windows a child started without
+        // SystemRoot/COMSPEC/PATHEXT and friends frequently cannot start at all —
+        // which is why every other spawn path in the codebase applies this floor
+        // (see spawnEnvNamesFor). `env run --clean` / `secret run --clean` did not,
+        // so clean-mode injection was unusable there. The floor is names the OS
+        // requires of any child, not user configuration, so it does not weaken what
+        // "clean" means about inherited secrets.
+        if (process.platform === "win32") {
+            for (const key of WIN32_SPAWN_ENV_FLOOR) {
+                if (parentEnv[key] !== undefined)
+                    base[key] = parentEnv[key];
+            }
+        }
     }
     for (const key of options.inherit) {
         if (parentEnv[key] !== undefined)

package/dist/commands/health/advisories.js

@@ -53,17 +53,17 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
                 "treat outcome-derived rank contributions as noise until a real usage/outcome signal lands.",
         });
     }
-    // Salience-distribution collapse: Gini below the uniform baseline means
-    // ranking no longer discriminates between assets.
+    // Salience-distribution collapse across all assets with retrieval evidence.
     if (improveSummary.degradation?.salienceUniformityFlagged) {
+        const sampleSize = improveSummary.degradation.retrievalSalienceSampleSize;
         advisories.push({
             name: "salience-uniformity-collapse",
             status: "warn",
             kind: "deterministic",
             confidence: "high",
-            message: `Salience distribution collapsed toward uniform: top-100 retrieval_salience Gini = ` +
-                `${improveSummary.degradation.corpusCentroidDistance} < 0.08 (uniform baseline ≈ 0.1). ` +
-                "Ranking currently carries little to no discrimination between assets.",
+            message: `Salience distribution collapsed toward uniform: retrieval_salience Gini = ` +
+                `${improveSummary.degradation.corpusCentroidDistance} < 0.08 across ${sampleSize} ` +
+                "observed, resolvable assets. Ranking carries little discrimination among assets with retrieval evidence.",
         });
     }
     // Enrichment-vs-minting policy: enrichment lanes edit existing assets;

package/dist/commands/health/html-report.js

@@ -351,8 +351,8 @@ function renderActionItems(vm) {
             prio: "P2",
             cls: "warn",
             title: "Salience distribution collapsed: retrieval_salience Gini < 0.08",
-            descHtml: "The top-100 salience scores are near-uniform (uniform baseline ≈ 0.1) — " +
-                "ranking currently carries little to no discrimination between assets. " +
+            descHtml: `The ${vm.degradation.retrievalSalienceSampleSize} observed, resolvable salience scores are near-uniform — ` +
+                "ranking carries little discrimination among assets with retrieval evidence. " +
                 `Corpus diversity proxy: ${esc(String(vm.degradation.corpusCentroidDistance))}.`,
             remedy: "akm health --format json | jq '.improve.degradation'",
         });

package/dist/commands/health/metrics.js

@@ -12,11 +12,23 @@ import { withStateDb } from "../../core/state-db.js";
 import { insertEvent } from "../../storage/repositories/events-repository.js";
 import { queryImproveRuns } from "../../storage/repositories/improve-runs-repository.js";
 import { listStateProposals } from "../../storage/repositories/proposals-repository.js";
-import { getTopRetrievalSalience } from "../../storage/repositories/salience-repository.js";
+import { getObservedRetrievalSalience } from "../../storage/repositories/salience-repository.js";
 import { roundRate, toFiniteNumber } from "./improve-metrics.js";
 import { ENRICHMENT_LANES, } from "./types.js";
 /** Event type appended + read back by the state.db round-trip probe. */
 const HEALTH_PROBE_EVENT = "health_probe";
+/**
+ * Retrieval-salience Gini guardrails.
+ *
+ * These are distribution-shape thresholds, not quantiles tied to a corpus
+ * size. Synthetic anchors pinned in monitor-liveness.test.ts are ~0.01 for a
+ * near-uniform two-band distribution, 0.25 for a balanced 0.25/0.75 spread,
+ * and ~0.82 for one dominant value among nine 0.01 values. Full-observation
+ * production snapshots also sit stably in the neutral band: 0.2613 at n=1,209
+ * (2026-07-12) and 0.2506 at n=1,454 (2026-08-17, missing rows excluded).
+ */
+const SALIENCE_UNIFORMITY_GINI_THRESHOLD = 0.08;
+const SALIENCE_ENTRENCHMENT_GINI_THRESHOLD = 0.35;
 /** Synthetic sentinel ref (ref-grammar decision D-R3): a colon-free
  * `<subsystem>/_<marker>` label. `health` has no asset stash-subdir, so
  * `health/_probe` names the subsystem. */
@@ -204,38 +216,41 @@ export function computeEnrichmentMintingRollup(db, since, until) {
  * @param until - Window end (ISO-8601).
  */
 export function computeDegradationMetrics(db, since, until) {
-    // (a) Corpus diversity — salience rank distribution of the top-100 assets.
-    // We use the Gini coefficient of retrieval_salience scores as an intra-corpus
-    // diversity proxy. A Gini close to 1 = highly concentrated (entrenched top
-    // assets), Gini near 0 = flat/diverse. This is a single-snapshot metric;
-    // consecutive-run centroid distance requires cross-run history not yet stored.
+    // (a) Corpus diversity — distribution of every observed retrieval-salience
+    // value for a currently resolvable asset. Zero is the no-observation floor
+    // and is excluded: the diagnostic measures discrimination among assets that
+    // have a retrieval signal, not corpus coverage.
+    //
+    // Do not preselect by rank_score here. The old top-100 sample truncated the
+    // distribution before measuring it, producing a low Gini even when the full
+    // observed corpus had a healthy spread.
     let corpusCentroidDistance = Number.NaN;
+    let retrievalSalienceSampleSize = 0;
     let entrenchmentFlagged;
     let salienceUniformityFlagged;
     try {
         // Fail-open: the asset_salience table may not exist yet (pre-WS-1 install).
-        // getTopRetrievalSalience (storage/repositories/salience-repository.ts,
-        // #672 part 2) owns the raw SQL; this call site's try/catch is unchanged.
-        const rows = getTopRetrievalSalience(db, 100);
+        const rows = getObservedRetrievalSalience(db);
+        retrievalSalienceSampleSize = rows.length;
         if (rows.length >= 5) {
+            // The repository returns ascending values. Keep a defensive sort so the
+            // O(n log n) closed-form Gini remains correct if that contract changes.
             const vals = rows.map((r) => r.retrieval_salience).sort((a, b) => a - b);
             const n = vals.length;
-            const sumAbsDiff = vals.reduce((acc, xi, i) => {
-                return acc + vals.slice(i + 1).reduce((a, xj) => a + Math.abs(xi - xj), 0);
-            }, 0);
-            const mean = vals.reduce((a, b) => a + b, 0) / n;
-            // `sumAbsDiff` contains each unordered pair once, so the standard Gini
-            // denominator is n² × mean (the equivalent ordered-pair formula has 2n²).
-            const gini = mean > 0 ? sumAbsDiff / (n * n * mean) : 0;
+            const sum = vals.reduce((acc, value) => acc + value, 0);
+            const weightedSum = vals.reduce((acc, value, index) => acc + (index + 1) * value, 0);
+            // Closed-form Gini for sorted non-negative values. This is O(n log n)
+            // including the defensive sort; the previous pairwise implementation
+            // was O(n²) and only safe because the sample was capped at 100.
+            const gini = sum > 0 ? (2 * weightedSum) / (n * sum) - (n + 1) / n : 0;
             // Re-express as a diversity proxy in [0,1]: high gini = low diversity.
             // corpusCentroidDistance approximation: gini is "distance from uniform".
-            // Two-tailed: >0.35 flags entrenchment (robustly above the ~0.1 uniform
-            // baseline); <0.08 flags uniformity collapse — the distribution no longer
-            // discriminates between assets (live 2026-07 value 0.040 sat unflagged
-            // in this tail under the old one-tailed check).
+            // Two-tailed: high concentration flags entrenchment; very low spread
+            // flags near-uniformity. Calibration provenance is documented with the
+            // constants above and pinned by synthetic distribution tests.
             corpusCentroidDistance = roundRate(gini);
-            entrenchmentFlagged = gini > 0.35;
-            salienceUniformityFlagged = gini < 0.08;
+            entrenchmentFlagged = gini > SALIENCE_ENTRENCHMENT_GINI_THRESHOLD;
+            salienceUniformityFlagged = gini < SALIENCE_UNIFORMITY_GINI_THRESHOLD;
         }
     }
     catch {
@@ -305,6 +320,7 @@ export function computeDegradationMetrics(db, since, until) {
     }
     return {
         corpusCentroidDistance,
+        retrievalSalienceSampleSize,
         entrenchmentFlagged,
         salienceUniformityFlagged,
         mergeFidelityContradictionRate,

package/dist/commands/health/report-view-model.js

@@ -455,7 +455,7 @@ function buildSummaryRows(aggregates, trend) {
             "Corpus diversity (Gini)",
             num(degradation.corpusCentroidDistance),
             degradation.entrenchmentFlagged || degradation.salienceUniformityFlagged ? "down" : "flat",
-            "Gini coefficient of retrieval_salience for top-100 ranked assets. Two-tailed: >0.35 = entrenchment risk; <0.08 = collapsed toward uniform (ranking no longer discriminates).",
+            `Gini coefficient of positive retrieval_salience values across ${degradation.retrievalSalienceSampleSize} resolvable assets. Two-tailed: >0.35 = entrenchment risk; <0.08 = collapsed toward uniform.`,
         ], [
             "Merge fidelity contradiction rate",
             pct(degradation.mergeFidelityContradictionRate, 1),

package/dist/commands/improve/consolidate.js

@@ -286,6 +286,46 @@ function loadPendingConsolidateProposalHashes(stashDir) {
     }
     return hashes;
 }
+/**
+ * Hash the bodies of live knowledge assets once per consolidation run.
+ *
+ * Pending-proposal dedup prevents repeated queue entries, but accepted
+ * proposals leave that set. Without a live-asset guard, the next run can copy
+ * the same memory body into a new knowledge slug indefinitely. Scan the target
+ * tree directly (rather than trusting the asynchronously refreshed index) so
+ * an already-written asset suppresses recurrence immediately.
+ */
+export function loadExistingKnowledgeBodyHashes(targetRoot) {
+    const hashes = new Set();
+    const knowledgeRoot = path.join(targetRoot, "knowledge");
+    if (!fs.existsSync(knowledgeRoot))
+        return hashes;
+    const visit = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const entryPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                visit(entryPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                try {
+                    hashes.add(cacheHash(fs.readFileSync(entryPath, "utf8")));
+                }
+                catch {
+                    // An unreadable asset cannot provide reliable duplicate evidence.
+                }
+            }
+        }
+    };
+    visit(knowledgeRoot);
+    return hashes;
+}
 /** Parse a stored provenance ref and emit its canonical D-R5 display spelling. */
 function canonicalStoredXref(ref) {
     try {
@@ -976,6 +1016,7 @@ async function akmConsolidateInner(opts, config, stashDir, startMs, warnings, sh
         memoryByRef,
         promoted,
         promotedSourceRefs: new Set(),
+        existingKnowledgeBodyHashes: loadExistingKnowledgeBodyHashes(opts.writeTarget.source.path),
         promotionFailures,
         warnings,
         pushSkipReason: accounting.pushSkipReason,
@@ -1011,8 +1052,26 @@ async function akmConsolidateInner(opts, config, stashDir, startMs, warnings, sh
         },
     });
 }
+/** Reject a promotion when its body already exists in knowledge or the queue. */
+function shouldSkipPromotionBodyDuplicate(args) {
+    const { bodyHash, op, knowledgeRef, ctx } = args;
+    if (ctx.existingKnowledgeBodyHashes.has(bodyHash)) {
+        ctx.warnings.push(`Skipping promote: identical body already exists in knowledge; skipping duplicate for ${op.ref} → ${knowledgeRef}`);
+        ctx.pushSkipReason("promote", op.ref, "dedup_existing_knowledge");
+        return true;
+    }
+    const contentDupProposal = listProposals(ctx.stashDir, { status: "pending" })
+        .filter((proposal) => proposal.source === "consolidate")
+        .find((proposal) => cacheHash(proposalContent(proposal)) === bodyHash);
+    if (!contentDupProposal)
+        return false;
+    ctx.warnings.push(`Skipping promote: identical body already pending as proposal ${contentDupProposal.id} (ref: ${contentDupProposal.ref}); skipping duplicate for ${op.ref} → ${knowledgeRef}`);
+    ctx.pushSkipReason("promote", op.ref, "dedup_pending_proposal");
+    return true;
+}
 /** Execute one reconciled promotion by emitting a reviewable proposal. */
-async function emitPromotionProposal(op, ctx) {
+/** @internal Executes the real proposal-emission path for one promote operation. */
+export async function emitPromotionProposal(op, ctx) {
     const { config, stashDir, sourceRun, target, memoryByRef, warnings, pushSkipReason, promoted, promotedSourceRefs } = ctx;
     const entry = memoryByRef.get(op.ref);
     if (!entry) {
@@ -1111,15 +1170,8 @@ async function emitPromotionProposal(op, ctx) {
     // Use cacheHash (case-preserving stripped body) to match the canonical
     // hash domain used by the body-embedding cache and pending-proposal set.
     const bodyHash = cacheHash(sourceBody);
-    const allPendingConsolidateProposals = listProposals(stashDir, { status: "pending" }).filter((p) => p.source === "consolidate");
-    const contentDupProposal = allPendingConsolidateProposals.find((p) => {
-        return cacheHash(proposalContent(p)) === bodyHash;
-    });
-    if (contentDupProposal) {
-        warnings.push(`Skipping promote: identical body already pending as proposal ${contentDupProposal.id} (ref: ${contentDupProposal.ref}); skipping duplicate for ${op.ref} → ${knowledgeRef}`);
-        pushSkipReason("promote", op.ref, "dedup_pending_proposal");
+    if (shouldSkipPromotionBodyDuplicate({ bodyHash, op, knowledgeRef, ctx }))
         return;
-    }
     try {
         // Use LLM-provided description; fall back to memory's own description
         // (post-sanitization frontmatter is authoritative).

package/dist/commands/improve/eval-cases.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../../core/common.js";
+import { recordWrittenPath } from "../../core/write-provenance.js";
 export function writeEvalCase(stashDir, evalCase) {
     const evalDir = path.join(stashDir, ".akm", "eval-cases");
     fs.mkdirSync(evalDir, { recursive: true });
@@ -28,6 +29,7 @@ Use it as a regression test: future improve runs on this ref should not produce
 output that would be rejected for the same reason.
 `;
     writeFileAtomic(filePath, content);
+    recordWrittenPath(filePath);
     return filePath;
 }
 export function countEvalCases(stashDir) {

package/dist/commands/improve/memory/memory-improve.js

@@ -543,6 +543,7 @@ function appendBeliefStateTransitionLog(stashDir, transitions) {
     }))
         .join("\n");
     fs.appendFileSync(logPath, `${lines}\n`, "utf8");
+    recordWrittenPath(logPath);
     return logPath;
 }
 function priorBeliefStateForArchive(candidate) {

package/dist/commands/lint/base-linter.js

@@ -33,6 +33,7 @@
 // ----------------------------------------------------------------------------
 import fs from "node:fs";
 import path from "node:path";
+import { isScalar, parseDocument } from "yaml";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { BUNDLE_REF_RE } from "../../core/asset/asset-ref.js";
 import { spliceFrontmatterLine } from "../../core/asset/frontmatter.js";
@@ -41,26 +42,87 @@ import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { localDateStamp } from "../../core/common.js";
 import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
+/** Fold physically wrapped prose the same way a YAML plain scalar does. */
+function foldDescriptionLines(lines) {
+    let value = "";
+    let blankLines = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            blankLines++;
+            continue;
+        }
+        if (value)
+            value += blankLines > 0 ? "\n".repeat(blankLines) : " ";
+        value += trimmed;
+        blankLines = 0;
+    }
+    return value;
+}
+/**
+ * Recover a description from malformed wrapped YAML.
+ *
+ * Older producers emitted a valid quoted first physical line followed by
+ * indented prose outside the quote. The full document cannot be parsed, but
+ * the first line can still be decoded independently and the continuation can
+ * be folded without guessing at escape sequences in that first segment.
+ */
+function recoverMalformedDescription(firstSegment, continuation) {
+    const firstLine = parseDocument(`description: ${firstSegment}`);
+    const firstValue = firstLine.get("description", true);
+    const decodedFirst = firstLine.errors.length === 0 && isScalar(firstValue) && typeof firstValue.value === "string"
+        ? firstValue.value
+        : firstSegment.trim();
+    const value = foldDescriptionLines([decodedFirst, ...continuation]);
+    return value || null;
+}
+/**
+ * Quote the complete description scalar, including physical continuation
+ * lines, and verify that the replacement is valid YAML before returning it.
+ */
 function fixUnquotedColon(raw) {
+    const eol = raw.includes("\r\n") ? "\r\n" : "\n";
     const lines = raw.split(/\r?\n/);
     if (lines[0]?.trim() !== "---")
-        return raw;
+        return null;
     const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
     if (closeIdx === -1)
-        return raw;
+        return null;
     for (let i = 1; i < closeIdx; i++) {
-        const m = lines[i].match(/^(description:\s*)(.*)/);
+        const m = lines[i]?.match(/^(description:\s*)(.*)/);
         if (!m)
             continue;
-        const prefix = m[1];
-        const value = m[2].trim();
-        if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
-            (value.startsWith("'") && value.endsWith("'") && value.length >= 2))
+        const [, prefix, firstSegment] = m;
+        if (prefix === undefined || firstSegment === undefined)
             continue;
-        lines[i] = `${prefix}"${value.replace(/"/g, '\\"')}"`;
-        break;
+        let continuationEnd = i + 1;
+        while (continuationEnd < closeIdx) {
+            const continuationLine = lines[continuationEnd];
+            if (continuationLine === undefined || (!/^[ \t]/.test(continuationLine) && continuationLine.trim()))
+                break;
+            continuationEnd++;
+        }
+        const frontmatter = lines.slice(1, closeIdx).join("\n");
+        const document = parseDocument(frontmatter);
+        const description = document.get("description", true);
+        const value = document.errors.length === 0 && isScalar(description) && typeof description.value === "string"
+            ? description.value
+            : recoverMalformedDescription(firstSegment.trim(), lines.slice(i + 1, continuationEnd));
+        if (value === null)
+            return null;
+        lines.splice(i, continuationEnd - i, `${prefix}${JSON.stringify(value)}`);
+        const candidate = lines.join(eol);
+        const candidateCloseIdx = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+        const candidateDocument = parseDocument(lines.slice(1, candidateCloseIdx).join("\n"));
+        const candidateDescription = candidateDocument.get("description", true);
+        if (candidateDocument.errors.length > 0 ||
+            !isScalar(candidateDescription) ||
+            candidateDescription.value !== value) {
+            return null;
+        }
+        return candidate;
     }
-    return lines.join("\n");
+    return null;
 }
 function checkMissingUpdated(data, frontmatterText) {
     return frontmatterText !== null && !("updated" in data);
@@ -473,16 +535,27 @@ export function runBaseChecks(ctx) {
         const unquotedColonDetail = checkUnquotedDescriptionColon(ctx.frontmatter);
         if (unquotedColonDetail) {
             if (ctx.fix) {
-                currentRaw = fixUnquotedColon(currentRaw);
-                modified = true;
-                const issue = {
-                    file: ctx.relPath,
-                    issue: "unquoted-colon",
-                    detail: unquotedColonDetail,
-                    fixed: true,
-                };
-                issues.push(issue);
-                pendingFixes.push(issue);
+                const fixedRaw = fixUnquotedColon(currentRaw);
+                if (fixedRaw === null) {
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "unquoted-colon",
+                        detail: `${unquotedColonDetail} — could not construct a valid YAML replacement`,
+                        fixed: "failed",
+                    });
+                }
+                else {
+                    currentRaw = fixedRaw;
+                    modified = true;
+                    const issue = {
+                        file: ctx.relPath,
+                        issue: "unquoted-colon",
+                        detail: unquotedColonDetail,
+                        fixed: true,
+                    };
+                    issues.push(issue);
+                    pendingFixes.push(issue);
+                }
             }
             else {
                 issues.push({

package/dist/commands/lint/index.js

@@ -502,7 +502,11 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
         }
         for (const filePath of assetFiles) {
             // Skip registry-cached read-only files — --fix must not mutate them.
-            if (filePath.includes("/.cache/") || filePath.includes("/registry/"))
+            // Compare on a separator-normalized copy: on Windows these paths carry
+            // backslashes, so the forward-slash substring never matched and --fix
+            // rewrote files inside the registry cache.
+            const posixPath = filePath.replace(/\\/g, "/");
+            if (posixPath.includes("/.cache/") || posixPath.includes("/registry/"))
                 continue;
             const relPath = path.relative(stashRoot, filePath);
             let raw;

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

@@ -10,6 +10,7 @@ import { decideDangerousKeyInstall } from "../../core/activation-policy.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
+import { sanitizeString } from "../../sources/providers/provider-utils.js";
 import { akmRemove } from "./installed-stashes.js";
 import { akmAdd } from "./source-add.js";
 import { addStash } from "./source-manage.js";
@@ -180,9 +181,14 @@ export async function auditInstalledStashForDangerousKeys(opts) {
             groupedByEnv.set(f.envRef, existing);
         }
         for (const [envRef, keys] of groupedByEnv) {
-            warn(`[warn] Env "${envRef}" in stash "${stashLabel}" contains potentially dangerous keys:`);
+            // envRef and keys come from filenames and KEY names inside a downloaded or
+            // cloned bundle, i.e. attacker-controllable. Tar validation rejects NUL but
+            // not ESC/CSI, and git checkout allows them in filenames on Linux/macOS —
+            // so printing them raw let a crafted bundle rewrite this security prompt
+            // with terminal escapes right before an "Install anyway?" confirmation.
+            warn(`[warn] Env "${sanitizeString(envRef)}" in stash "${sanitizeString(stashLabel)}" contains potentially dangerous keys:`);
             for (const key of keys) {
-                warn(`  - ${key}: can hijack process execution via \`akm env run\``);
+                warn(`  - ${sanitizeString(key)}: can hijack process execution via \`akm env run\``);
             }
         }
         const confirmed = await p.confirm({

package/dist/commands/sources/migration-help.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
+import embeddedChangelog from "../../../CHANGELOG.md" with { type: "text" };
 import { getDirname } from "../../runtime.js";
 const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/CHANGELOG.md";
 const MIGRATION_DOC_URL = "https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md";
@@ -24,9 +25,13 @@ function loadChangelog() {
         }
     }
     catch {
-        // fall through to bundled notes
+        // fall through to the embedded copy
     }
-    return undefined;
+    // In the `bun build --compile` standalone binary, import.meta.url points into
+    // the virtual /$bunfs tree and every existsSync above misses, so `akm help
+    // migrate <version>` degraded to the generic "no dedicated note" message for
+    // EVERY version. Only assets imported `with { type: "text" }` are embedded.
+    return embeddedChangelog.length > 0 ? embeddedChangelog : undefined;
 }
 /**
  * Load the bundled migration note for a specific version, if one exists.
@@ -87,7 +92,11 @@ function resolveLatestVersion(changelog) {
     return undefined;
 }
 function extractChangelogSection(changelog, version) {
-    const pattern = new RegExp(`^## \\[${escapeRegexString(version)}\\][^\\n]*\\n([\\s\\S]*?)(?=^## \\[|\\Z)`, "m");
+    // `\Z` is not a JavaScript anchor — it matches a literal "Z", which truncated
+    // the section at the first capital Z in the body (and failed outright for the
+    // last entry). `$` with the `m` flag would stop at the first line end, so the
+    // end-of-input alternative has to be an explicit lookahead for the input end.
+    const pattern = new RegExp(`^## \\[${escapeRegexString(version)}\\][^\\n]*\\n([\\s\\S]*?)(?=^## \\[|$(?![\\s\\S]))`, "m");
     const match = changelog.match(pattern);
     if (!match)
         return undefined;

package/dist/commands/sources/self-update.js

@@ -10,6 +10,7 @@ import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { githubHeaders } from "../../integrations/github.js";
 import { getDirname, mainPath, semverOrder } from "../../runtime.js";
+import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
 const REPO = "itlackey/akm";
 const DEFAULT_PACKAGE_NAME = "akm-cli";
 const NODE_MODULES_SEGMENT = "/node_modules/";
@@ -474,7 +475,14 @@ function readInstalledCliVersion(akmBin) {
     return match?.[0];
 }
 function runRequiredCommand(akmBin, args, label) {
-    const result = childProcess.spawnSync(akmBin, args, {
+    // A bare "akm" is not spawnable on Windows: npm/pnpm/yarn install a global CLI
+    // as akm.cmd / akm.ps1 shims, and spawnSync without a shell does not apply
+    // PATHEXT — so the package-manager upgrade arm died with ENOENT before it ever
+    // ran. resolveAkmInvocation returns a concrete argv (launcher, runtime + main
+    // script, or a standalone binary) for however this install actually runs.
+    // An explicit path (the standalone arm passes one) is used as given.
+    const [command, ...prefixArgs] = path.isAbsolute(akmBin) ? [akmBin] : resolveAkmInvocation().argv;
+    const result = childProcess.spawnSync(command ?? akmBin, [...prefixArgs, ...args], {
         encoding: "utf8",
         env: process.env,
         stdio: "pipe",