akm-cli 0.9.7 → 0.9.8-beta.2

package/dist/commands/lint/index.js

@@ -11,14 +11,13 @@ import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdForStashFile, displayRefForConceptId } from "../../core/asset/resolve-ref.js";
 import { deriveBundleIds } from "../../core/bundle-id.js";
-import { isAkmRegistryCachePath, resolveStashDir } from "../../core/common.js";
+import { compareCodePoints, isAkmRegistryCachePath, resolveStashDir } from "../../core/common.js";
 import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail } from "../../tasks/source-v3.js";
 import { resolveWorkflowSourceDomains } from "../../workflows/source-files.js";
-import { compareWorkflowSourceCodePoints } from "../../workflows/source-ir/compare.js";
 import { runBaseChecks } from "./base-linter.js";
 import { checkEnvForDangerousKeys } from "./env-key-rules.js";
 import { isAdvisoryLintIssue } from "./types.js";
@@ -87,7 +86,7 @@ function collectWorkflowFiles(dir) {
     const results = [];
     for (const entry of fs
         .readdirSync(dir, { withFileTypes: true })
-        .sort((left, right) => compareWorkflowSourceCodePoints(left.name, right.name))) {
+        .sort((left, right) => compareCodePoints(left.name, right.name))) {
         if (entry.name === ".git")
             continue;
         const full = path.join(dir, entry.name);
@@ -103,7 +102,7 @@ function collectWorkflowFiles(dir) {
         if (extension === ".md" || extension === ".yml")
             results.push(full);
     }
-    return results.sort(compareWorkflowSourceCodePoints);
+    return results.sort(compareCodePoints);
 }
 /**
  * Resolve the already-enumerated candidates through the same workflow-source
@@ -131,7 +130,7 @@ function resolveWorkflowLintOwnership(stashRoot, files) {
             fixed: false,
         });
     }
-    return { files: ownedFiles.sort(compareWorkflowSourceCodePoints), issues };
+    return { files: ownedFiles.sort(compareCodePoints), issues };
 }
 // ── Non-akm adapter dispatch (real `adapter.validate()`, not a re-implementation) ──
 //

package/dist/commands/migrate/config-extra-params.js

@@ -0,0 +1,61 @@
+// 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/.
+/**
+ * Legacy `extraParams` -> first-class-field lift (#852, following #815), as
+ * an `akm migrate` concern.
+ *
+ * This used to run silently, in memory, on every config load
+ * (`liftLegacyEngineExtraParams` called from `parseAndValidateConfigText`)
+ * and never wrote the result back — so the lift, and its warning, recurred
+ * forever. config.json is akm-owned plain JSON; the lift is deterministic
+ * and total, so — like the dead-residue cleanup in `./dead-residue.ts` —
+ * it belongs in `akm migrate`, run once, persisted. `parseAndValidateConfigText`
+ * now fails closed on an unmigrated config instead of lifting it.
+ */
+import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, writeConfigAtomic, } from "../../core/config/config-io.js";
+import { liftLegacyEngineExtraParams } from "../../core/extra-params.js";
+function readRawConfig(configPath) {
+    const text = readConfigText(configPath);
+    if (text === undefined)
+        return undefined;
+    return parseConfigText(text, configPath);
+}
+/**
+ * Read-only: what `akm migrate apply` would lift (or flag as conflicting) in
+ * `config.json`'s `extraParams`. Never touches disk. Returns an empty plan
+ * when the config file does not exist.
+ */
+export function findConfigExtraParamsLift(configPath) {
+    const raw = readRawConfig(configPath);
+    if (!raw)
+        return { lifted: [], conflicts: [] };
+    const { lifted, conflicts } = liftLegacyEngineExtraParams(raw);
+    return { lifted, conflicts };
+}
+/**
+ * Persist the legacy extraParams -> first-class field lift to `config.json`,
+ * once. Best-effort like `removeDeadResidue`: a genuine conflict (extraParams
+ * and the first-class field set to different values) is left untouched here
+ * — `parseAndValidateConfigText` already hard-rejects that config at every
+ * load with the exact mismatch, so a second, weaker error here would only be
+ * noise — and is reported back via `conflicts` instead.
+ */
+export function applyConfigExtraParamsLift(configPath) {
+    const raw = readRawConfig(configPath);
+    if (!raw)
+        return { applied: false, lifted: [], conflicts: [] };
+    const { config, lifted, conflicts } = liftLegacyEngineExtraParams(raw);
+    if (conflicts.length > 0 || lifted.length === 0) {
+        return { applied: false, lifted, conflicts };
+    }
+    const release = acquireConfigLock();
+    try {
+        backupExistingConfig(configPath);
+        writeConfigAtomic(configPath, config);
+    }
+    finally {
+        release();
+    }
+    return { applied: true, lifted, conflicts: [] };
+}

package/dist/commands/migrate/dead-residue.js

@@ -0,0 +1,113 @@
+/**
+ * Dead pre-0.9.0 `$STASH/.akm` residue: superseded filesystem layouts with no
+ * live reader or writer anywhere in src/ (each verified by grep before being
+ * listed — see #889 for the audit). The largest, `.akm/proposals/`, was
+ * replaced by the `proposals` table in state.db in 0.9.0 and measured 135 MB
+ * on a real bundle.
+ *
+ * This lives under `migrate/` because removing a superseded layout IS
+ * migration — the tail end of the moves that created these paths' replacements.
+ * It was first shipped as a bolted-on `akm health --clean-dead-residue` flag
+ * plus a health advisory; that was the wrong shape (a special-purpose switch
+ * apologizing for migrations that did not finish their own job) and was
+ * removed. `akm migrate status` reports what is here; `akm migrate apply`
+ * removes it, exactly as it applies every other pending migration.
+ */
+import fs from "node:fs";
+import path from "node:path";
+const DEAD_RESIDUE_PATHS = [
+    { name: "proposals", reason: "superseded by the `proposals` table in $DATA/state.db (0.9.0)" },
+    { prefix: "runs.archived-", reason: "orphaned archive of a directory that no longer exists" },
+    {
+        name: "archive",
+        reason: "legacy consolidation archive; current prune writes .akm/memory-cleanup/archive/ instead",
+    },
+    { name: "graph.json", reason: "superseded by the graph_* tables in $DATA/index.db" },
+    { name: "consolidate-journal.json", reason: "legacy consolidation journal; unused" },
+    { name: "proposals.db", reason: "empty legacy database file" },
+    { name: "mv-transactions", reason: "legacy fs-txn journal location; unused" },
+];
+function dirSizeBytes(target) {
+    let total = 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(target, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const entryPath = path.join(target, entry.name);
+        if (entry.isDirectory()) {
+            total += dirSizeBytes(entryPath);
+        }
+        else if (entry.isFile()) {
+            try {
+                total += fs.statSync(entryPath).size;
+            }
+            catch {
+                // Skip files that vanish or are inaccessible between readdir and stat.
+            }
+        }
+    }
+    return total;
+}
+function sizeOf(target) {
+    const st = fs.statSync(target);
+    return st.isDirectory() ? dirSizeBytes(target) : st.size;
+}
+/**
+ * Find every Tier-1 dead-residue path that actually exists under
+ * `$STASH/.akm`, with its computed size. Read-only — never deletes.
+ */
+export function findDeadResidueEntries(stashDir) {
+    const akmDir = path.join(stashDir, ".akm");
+    let names;
+    try {
+        names = fs.readdirSync(akmDir);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const spec of DEAD_RESIDUE_PATHS) {
+        const matches = spec.name !== undefined ? [spec.name] : names.filter((n) => n.startsWith(spec.prefix ?? "\0"));
+        for (const name of matches) {
+            if (!names.includes(name))
+                continue;
+            const absolutePath = path.join(akmDir, name);
+            let sizeBytes;
+            try {
+                sizeBytes = sizeOf(absolutePath);
+            }
+            catch {
+                continue; // vanished between readdir and stat
+            }
+            found.push({ relativePath: path.join(".akm", name), absolutePath, sizeBytes, reason: spec.reason });
+        }
+    }
+    return found;
+}
+/**
+ * Delete every Tier-1 dead-residue path found under `$STASH/.akm`. Only
+ * invoked when the caller has explicitly opted in (`akm health
+ * --clean-dead-residue`) — never as a side effect of a plain `akm health`
+ * read. Best-effort per-path: one failure does not abort the rest.
+ */
+export function removeDeadResidue(stashDir) {
+    const entries = findDeadResidueEntries(stashDir);
+    return entries.map((entry) => {
+        try {
+            fs.rmSync(entry.absolutePath, { recursive: true, force: true });
+            return { relativePath: entry.relativePath, sizeBytes: entry.sizeBytes, removed: true };
+        }
+        catch (error) {
+            return {
+                relativePath: entry.relativePath,
+                sizeBytes: entry.sizeBytes,
+                removed: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    });
+}

package/dist/commands/migrate/stale-txn.js

@@ -0,0 +1,49 @@
+// 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/.
+/**
+ * Stale durable-transaction journals (`$DATA/txn/<rootNs24>/<id>/journal.json`,
+ * see `core/fs-txn.ts`) that never got recovered — a crash mid-transaction
+ * left a journal on disk with no process left to finish or roll it back.
+ * `akm health` used to only report these and point at a troubleshooting doc
+ * (issue: an advisory that tells the user to go read docs instead of the
+ * tool recovering its own interrupted state). Recovery IS a migration
+ * concern like dead `.akm/` residue: `akm migrate status` names what is
+ * here for the stash root, `akm migrate apply` recovers it, exactly like
+ * `dead-residue.ts`.
+ *
+ * Recovery goes through {@link recoverTxnsForRoot}, which requires every
+ * live kind's registrar to be IMPORTED first so its handler is registered
+ * (see fs-txn.ts's module docs). `proposal/repository.ts` registers the
+ * `proposal`/`proposal-reject` kinds specifically so "ANY recovery entry
+ * point ... can finish or roll back an interrupted proposal mutation for a
+ * root it touches" (its own comment on the registration) — this module is
+ * exactly that kind of entry point.
+ */
+import { canonicalTxnRoot, listTxnJournalsTolerant, recoverTxnsForRoot } from "../../core/fs-txn.js";
+// Side-effect import: registers the `proposal`/`proposal-reject` txn kinds
+// so recovery below can roll them forward/back for the stash root.
+import "../proposal/repository.js";
+/**
+ * Find every durable-transaction journal bound to `stashDir`'s namespace.
+ * Read-only, tolerant of a corrupt journal (counted, not thrown on) — mirrors
+ * `findDeadResidueEntries`'s read-only/never-mutates contract.
+ */
+export function findStaleTxnEntries(stashDir) {
+    const root = canonicalTxnRoot(stashDir);
+    const { matches } = listTxnJournalsTolerant((j) => canonicalTxnRoot(j.root) === root);
+    return matches.map(({ journal }) => journalToEntry(journal));
+}
+function journalToEntry(journal) {
+    return { transactionId: journal.transactionId, kind: journal.kind, phase: journal.phase, root: journal.root };
+}
+/**
+ * Recover every durable transaction bound to `stashDir`'s namespace: roll
+ * back journals before their kind's commit point, roll forward the rest.
+ * The counterpart to {@link findStaleTxnEntries}, invoked only from `akm
+ * migrate apply`.
+ */
+export async function recoverStaleTxns(stashDir) {
+    const recovered = await recoverTxnsForRoot(stashDir);
+    return recovered.map(journalToEntry);
+}

package/dist/commands/migrate-cli.js

@@ -2,6 +2,12 @@
 // 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 { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
+import { resolveStashDir } from "../core/common.js";
+import { ConfigError } from "../core/errors.js";
+import { getConfigPath } from "../core/paths.js";
+import { applyConfigExtraParamsLift, findConfigExtraParamsLift } from "./migrate/config-extra-params.js";
+import { findDeadResidueEntries, removeDeadResidue } from "./migrate/dead-residue.js";
+import { findStaleTxnEntries, recoverStaleTxns } from "./migrate/stale-txn.js";
 import { runMigrationTool } from "./migration-tool.js";
 async function callMigrateTool(args, runTool) {
     const result = await runTool(args);
@@ -79,6 +85,25 @@ export function resolveGenerationStatus(call, label) {
  * got to look at a stable tree in that case.
  */
 export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runTool = runMigrationTool) {
+    // Superseded pre-0.9.0 .akm layouts are a migration concern like any other:
+    // status names them, apply removes them. (First shipped as a bolted-on
+    // `health --clean-dead-residue` flag; folded here where it belongs.) The
+    // legacy extraParams -> first-class-field config lift (#852) is the same
+    // shape: status names it, apply persists it once instead of the old
+    // permanent silent lift on every config load.
+    // No configured bundle means there is no stash to scan — an empty domain,
+    // not an error — so migrate still works before `akm bundle create`. Any
+    // OTHER ConfigError propagates.
+    let stashDir;
+    try {
+        stashDir = resolveStashDir();
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError) || error.code !== "STASH_DIR_NOT_FOUND")
+            throw error;
+    }
+    const configPath = getConfigPath();
+    const applyResidue = command === "migrate-apply" && !genOneArgs.includes("--dry-run");
     const first = await callMigrateTool(genOneArgs, runTool);
     if (first.status !== EXIT_CODES.SUCCESS && first.status !== EXIT_CODES.GENERAL) {
         process.exitCode = first.status;
@@ -95,7 +120,23 @@ export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runT
         return;
     }
     const combined = combineMigrationPlans(first, second);
-    output(command, combined);
+    // The stash-scoped sections need a bundle to scan; no configured bundle is
+    // an empty domain, not an error, so migrate still works before
+    // `akm bundle create`. The config lift is config-scoped and always runs.
+    const stashSections = stashDir === undefined
+        ? {}
+        : {
+            deadResidue: applyResidue
+                ? { removed: removeDeadResidue(stashDir) }
+                : { pending: findDeadResidueEntries(stashDir) },
+            staleTxns: applyResidue
+                ? { recovered: await recoverStaleTxns(stashDir) }
+                : { pending: findStaleTxnEntries(stashDir) },
+        };
+    const configExtraParams = applyResidue
+        ? applyConfigExtraParamsLift(configPath)
+        : { pending: findConfigExtraParamsLift(configPath) };
+    output(command, { ...combined, ...stashSections, configExtraParams });
     if (combined.status === "blocked")
         process.exitCode = EXIT_CODES.GENERAL;
 }

package/dist/commands/proposal/proposal.js

@@ -15,7 +15,7 @@ import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
-import { createProposal, diffProposal, isProposalSkipped, listProposals, preflightProposalPromotion, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, revertProposal, } from "./repository.js";
+import { diffProposal, listProposals, preflightProposalPromotion, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, revertProposal, } from "./repository.js";
 import { validateProposal } from "./validators/proposals.js";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
@@ -131,26 +131,6 @@ export function akmProposalDiff(options) {
         ...(diff.targetPath ? { targetPath: diff.targetPath } : {}),
     };
 }
-export function akmProposalCreate(options) {
-    const queue = resolveProposalQueue(options.stashDir, options.queue, options.config);
-    const stash = queue.stashDir;
-    const target = options.target ?? (queue.target ? { source: queue.target.source.name, root: queue.target.source.path } : undefined);
-    // Manual proposal creation (via `akm proposal create`) always bypasses
-    // dedup/cooldown guards — the operator is explicitly requesting a proposal.
-    const result = createProposal(stash, {
-        ref: options.ref,
-        source: options.source,
-        ...(target !== undefined ? { target } : {}),
-        ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
-        payload: options.payload,
-        force: true,
-    }, options.ctx);
-    if (isProposalSkipped(result)) {
-        // Should never happen with force:true — defensive only.
-        throw new Error(`Unexpected proposal skip: ${result.message}`);
-    }
-    return { schemaVersion: 1, ok: true, proposal: result };
-}
 /**
  * Restore an accepted proposal's prior content from the backup captured at
  * promotion time (Advantage D6c / Phase 6C).

package/dist/commands/proposal/repository.js

@@ -563,9 +563,6 @@ export function listProposalsReadOnly(stashDir, options = {}, ctx) {
             }
         });
     }
-    catch {
-        return [];
-    }
     finally {
         db?.close();
     }
@@ -1013,7 +1010,6 @@ async function finalizeProposalTransaction(txn, target, proposal, ctx) {
             paths: [commitPath],
             snapshots: p.gitSnapshots ?? {},
             onCommitRecorded: (commit) => {
-                // biome-ignore lint/style/noNonNullAssertion: publishWriteTargetTransaction throws when absent
                 const publication = p.gitPublication;
                 if (publication.commit !== commit) {
                     publication.commit = commit;

package/dist/commands/proposal/validators/proposal-quality-validators.js

@@ -190,12 +190,6 @@ export function hasHotCaptureMode(frontmatter) {
     return frontmatter?.captureMode === "hot";
 }
 // ── Consolidate merge size gate ──────────────────────────────────────────────
-/**
- * Ratio lower-bound for merged body vs. the larger source body.
- * Lower than reflect (0.5) because deduplication is expected — two memories
- * with 80-90% overlap legitimately compress to well under 50% of the larger.
- */
-export const MERGE_SHRINK_RATIO_MIN = 0.3;
 // ── Reflect size gate ────────────────────────────────────────────────────────
 /** Ratio lower-bound: proposed body must be at least this fraction of source. */
 export const REFLECT_SHRINK_RATIO_MIN = 0.5;

package/dist/commands/read/curate.js

@@ -52,7 +52,9 @@ export const CURATE_SEARCH_LIMIT_MULTIPLIER = 4;
 export const MIN_CURATE_SEARCH_LIMIT = 12;
 const DEFAULT_CURATE_LIMIT = 4;
 const CURATE_CLOSE_SCORE_BAND = 0.12;
-const CURATE_TAIL_SCORE_FLOOR = 0.35;
+// Used by `shouldRunCurateFallback` to judge whether the initial search
+// already returned strong results (a different purpose from ranking/keeping
+// hits — see that function for its own rationale).
 const CURATE_RELATIVE_SCORE_FLOOR = 0.7;
 const CURATE_FALLBACK_TOP_SCORE_THRESHOLD = 0.8;
 const CURATE_FALLBACK_STRONG_SCORE_FLOOR = 0.35;
@@ -577,11 +579,6 @@ function compareCurateHits(a, b) {
         return rawDiff;
     return a.originalIndex - b.originalIndex;
 }
-function passesCurateScoreFloor(hit, leaderScore) {
-    if (leaderScore === undefined)
-        return true;
-    return hit.rawScore >= Math.max(CURATE_TAIL_SCORE_FLOOR, leaderScore * CURATE_RELATIVE_SCORE_FLOOR);
-}
 function isNarrowReferenceFamilyQuery(query, family) {
     if (!family || family.role !== "reference")
         return false;
@@ -602,19 +599,8 @@ function selectCuratedStashHits(query, hits, limit) {
     const ranked = collapsed.hits
         .map(({ hit, originalIndex }) => annotateCurateHit(query, hit, originalIndex, intent))
         .sort(compareCurateHits);
-    const selected = [];
     const supportRefsByRef = collapsed.supportRefsByRef;
-    let leaderScore;
-    for (const candidate of ranked) {
-        if (!passesCurateScoreFloor(candidate, leaderScore))
-            continue;
-        selected.push(candidate);
-        if (leaderScore === undefined)
-            leaderScore = candidate.rawScore;
-        if (selected.length >= limit)
-            break;
-    }
-    return { selected: selected.map((entry) => entry.hit), supportRefsByRef };
+    return { selected: ranked.slice(0, limit).map((entry) => entry.hit), supportRefsByRef };
 }
 function collapseCurateFamilies(query, hits) {
     const passthrough = [];

package/dist/commands/read/show.js

@@ -27,7 +27,7 @@ import { displayRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString, isWithin } from "../../core/common.js";
 import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
-import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
+import { NotFoundError, rethrowIfDataDirUnreadable, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
@@ -292,6 +292,7 @@ export async function showLocal(input) {
             }
             catch (err) {
                 rethrowIfTestIsolationError(err);
+                rethrowIfDataDirUnreadable(err);
                 return { total: 0, hits: [] };
             }
         })(),

package/dist/commands/sources/installed-stashes.js

@@ -47,7 +47,11 @@ function canonicalJson(value) {
     if (value && typeof value === "object") {
         const entries = Object.entries(value)
             .filter(([, entry]) => entry !== undefined)
-            .sort(([left], [right]) => left.localeCompare(right));
+            // Codepoint order, NOT localeCompare: this string feeds sha256Hex for the
+            // bundle-audit generation, and localeCompare is ICU/locale-dependent — the
+            // same object could hash differently on two machines. Matches the other
+            // canonicalJson implementations (workflows/ir/plan-hash.ts).
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
         return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
     }
     return JSON.stringify(value);

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

@@ -333,7 +333,7 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
             ok: false,
             skipped: opts.skip,
             message: `Upgrade completed, but the state schema was not prepared (${detail}). ` +
-                "Preserve state.db and run `akm upgrade --force` before other AKM commands.",
+                "Preserve state.db and run `akm upgrade --state-only` before other AKM commands (the binary is already current).",
         };
     }
     const stateNote = stateUpgrade.safetyCopyPath ? ` Historical state safety copy: ${stateUpgrade.safetyCopyPath}.` : "";
@@ -520,3 +520,40 @@ export function getPackageManagerUpgradeCommand(installMethod, packageName = get
     }
     return undefined;
 }
+/**
+ * Apply pending historical destructive state.db migrations WITHOUT installing a
+ * new akm — the body of `akm upgrade --state-only`.
+ *
+ * Migrations flagged `historical-destructive` are refused during an ordinary
+ * managed open: they need a verified sibling safety copy taken under the
+ * migration writer lock, and that is deliberate, so an unattended `akm index`
+ * can never quietly drop operator state.
+ *
+ * The bug this fixes is not the guard but its reachability (#895). The only
+ * code path that set `allowHistoricalDestructiveStateUpgrade` ran as a
+ * POST-INSTALL step of a real upgrade, so it sat behind an npm install. Where
+ * akm is installed globally by an image and the runtime user is unprivileged,
+ * that install fails EACCES and throws long before the migration is reached —
+ * leaving the documented remedy impossible to run and `akm index --full`
+ * permanently blocked. Nothing about the migration itself needs the network,
+ * root, or a new binary; it is local, offline, and already verified.
+ *
+ * The safety copy is NOT skipped here. This changes only who may ask for the
+ * migration, never what it does.
+ */
+export function upgradeStateOnly(currentVersion, dependencies) {
+    const upgradeState = dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase;
+    const result = upgradeState();
+    return {
+        currentVersion,
+        newVersion: currentVersion,
+        upgraded: false,
+        installMethod: detectInstallMethod(),
+        message: result.upgraded
+            ? `Applied pending state.db migrations. Safety copy: ${result.safetyCopyPath}`
+            : "state.db is already current; no migration was needed",
+        stateUpgrade: result.safetyCopyPath
+            ? { applied: result.upgraded, safetyCopyPath: result.safetyCopyPath }
+            : { applied: result.upgraded },
+    };
+}

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

@@ -33,7 +33,7 @@ import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
 import { pkgVersion } from "../../version.js";
-import { checkForUpdate, performUpgrade } from "./self-update.js";
+import { checkForUpdate, performUpgrade, upgradeStateOnly } from "./self-update.js";
 import { akmClone } from "./source-clone.js";
 export const upgradeCommand = defineJsonCommand({
     meta: { name: "upgrade", description: "Upgrade akm to the latest release" },
@@ -45,8 +45,24 @@ export const upgradeCommand = defineJsonCommand({
             description: "Skip the post-upgrade index rebuild",
             default: false,
         },
+        "state-only": {
+            type: "boolean",
+            description: "Apply pending state.db migrations without installing a new akm",
+            default: false,
+        },
     },
     async run({ args }) {
+        // Applying a historical destructive state migration used to be reachable
+        // ONLY as a post-install step of a real upgrade, so an install akm cannot
+        // rewrite -- a global npm install owned by root, an image that ships the
+        // CLI -- had no route to it at all: the npm step fails EACCES and throws
+        // long before the migration runs (#895). The migration is a local,
+        // offline, already-verified operation; it does not need the network or a
+        // new binary, and coupling it to one was the bug.
+        if (args["state-only"]) {
+            output("upgrade", upgradeStateOnly(pkgVersion));
+            return;
+        }
         const check = await checkForUpdate(pkgVersion);
         if (args.check) {
             output("upgrade", check);

package/dist/commands/tasks/tasks.js

@@ -875,14 +875,6 @@ function warnIneligibleRebind(runtime, explicitRebind, warnings) {
         return;
     warnings.push(`--rebind bound scheduled tasks to an ineligible ${runtime.kind ?? "unknown"} invocation (${runtime.binding.join(" ")}); scheduled runs will invoke a mutable, unproven binary. Install akm via \`npm install --global akm-cli\` or a standalone release, then re-run \`akm task sync --rebind\`.`);
 }
-export function prepareSchedulerRuntime(explicitRebind, operation, deps = {}) {
-    const invocation = (deps.resolveInvocation ?? resolveAkmInvocation)();
-    if (!invocation.eligible && !explicitRebind) {
-        throw new UsageError(`Refusing to ${operation} from an ineligible ${invocation.kind ?? "unknown"} invocation (${invocation.argv.join(" ")}).`, "INVALID_FLAG_VALUE", "npm-global ownership could not be verified. Run `npm install --global akm-cli` and use that launcher, use a standalone installation, or explicitly repeat the operation with --rebind.");
-    }
-    const contextPath = (deps.writeDescriptor ?? writeSchedulerContextDescriptor)(schedulerContextDescriptor());
-    return { binding: invocation.argv, contextPath, eligible: invocation.eligible, kind: invocation.kind };
-}
 function groupInstalledBindings(entries, invocation) {
     const groups = new Map();
     for (const entry of entries) {

package/dist/commands/url-checker.js

@@ -2,40 +2,32 @@
 // 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/.
 const URL_RE = /https?:\/\/[^\s"'<>)\]]+/g;
-const TIMEOUT_MS = 5000;
-const MAX_URLS = 20;
+/**
+ * Check every URL in `entries` and report the ones that are dead.
+ *
+ * No cap, no per-entry slice, no ceiling option. There used to be a
+ * `MAX_URLS = 20` plus an undocumented `slice(0, 3)` per entry, so this
+ * examined at most twenty links in a bundle holding thousands and reported
+ * success. The first attempt at fixing that kept the cap and layered a
+ * coverage report, a warning, and an override on top — a constraint plus more
+ * code to explain the constraint. Both are gone. It checks what you asked it
+ * to check.
+ *
+ * A request that fails, times out, or cannot resolve surfaces as a `DeadUrl`
+ * rather than being swallowed, so a network problem is visible instead of
+ * looking like a clean bill of health.
+ */
 export async function checkDeadUrls(_stashDir, entries) {
-    const urlsToCheck = [];
-    for (const entry of entries) {
-        if (urlsToCheck.length >= MAX_URLS)
-            break;
-        const matches = entry.body.match(URL_RE) ?? [];
-        for (const url of matches.slice(0, 3)) {
-            urlsToCheck.push({ ref: entry.ref, url });
-            if (urlsToCheck.length >= MAX_URLS)
-                break;
-        }
-    }
+    const urlsToCheck = entries.flatMap((entry) => (entry.body.match(URL_RE) ?? []).map((url) => ({ ref: entry.ref, url })));
     const results = [];
     await Promise.allSettled(urlsToCheck.map(async ({ ref, url }) => {
         try {
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
-            const res = await fetch(url, {
-                method: "HEAD",
-                signal: controller.signal,
-                redirect: "follow",
-            });
-            clearTimeout(timer);
-            if (res.status >= 400) {
+            const res = await fetch(url, { method: "HEAD", redirect: "follow" });
+            if (res.status >= 400)
                 results.push({ ref, url, status: res.status });
-            }
         }
-        catch (e) {
-            if (e.name === "AbortError") {
-                results.push({ ref, url, status: "timeout" });
-            }
-            // network errors (ENOTFOUND etc.) — skip, don't report as dead
+        catch {
+            results.push({ ref, url, status: "error" });
         }
     }));
     return results;