akm-cli 0.9.7 → 0.9.8-beta.2

package/dist/core/common.js

@@ -277,8 +277,14 @@ function isValidDirectory(dir) {
     try {
         return fs.statSync(dir).isDirectory();
     }
-    catch {
-        return false;
+    catch (error) {
+        // Genuinely absent — the caller's "not found" fallback applies. Any other
+        // stat failure (e.g. EACCES) is not "doesn't exist"; treating it as such
+        // produced the wrong message ("Run akm bundle create") for a directory
+        // that exists but cannot be read.
+        if (hasErrnoCode(error, "ENOENT"))
+            return false;
+        throw new ConfigError(`Unable to read bundle directory at "${dir}".`, "STASH_DIR_UNREADABLE");
     }
 }
 /**
@@ -356,6 +362,10 @@ function readStashDirFromConfig() {
 export function toPosix(input) {
     return input.replace(/\\/g, "/");
 }
+/** Locale-independent code-point ordering — a stable `Array.prototype.sort` comparator for strings (paths, names, ids). */
+export function compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
 export function hasErrnoCode(error, code) {
     if (typeof error !== "object" || error === null || !("code" in error))
         return false;
@@ -873,7 +883,61 @@ export function asNonEmptyString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+// ── env-file assignment scanning ─────────────────────────────────────────────
+/** Matches a `KEY=value` assignment line, capturing only the key. */
+export const ENV_ASSIGN_LINE_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/** Scan lines and return KEY names in file order, without duplicates. */
+export function scanEnvKeyNames(text) {
+    const keys = [];
+    const seen = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const m = line.match(ENV_ASSIGN_LINE_RE);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (!key)
+            continue;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
+/** True when `value` contains no lone/unpaired UTF-16 surrogate (every surrogate is part of a valid pair). */
+export function wellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return false;
+    }
+    return true;
+}
 // ── Generic data utilities ───────────────────────────────────────────────────
+/**
+ * Narrow an unknown value to a plain-ish record: an `object` that is neither
+ * `null` nor an `Array`. Does not distinguish a literal `{}` from a `Date`,
+ * `Map`, or class instance — callers that need that distinction use a
+ * stricter predicate instead.
+ */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** `JSON.parse` that returns `undefined` instead of throwing. */
+export function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Coerce an unknown value to a filtered, trimmed string array.
  * Non-strings and empty/whitespace-only entries are dropped.

package/dist/core/config/config-io.js

@@ -115,17 +115,30 @@ export function backupExistingConfig(configPath, now = new Date()) {
     return { timestamped, latest };
 }
 function pruneOldBackups(backupDir) {
+    pruneToNewest(backupDir, MAX_CONFIG_BACKUPS, (entry) => entry.isFile() && isTimestampedConfigBackup(entry.name));
+}
+function isTimestampedConfigBackup(name) {
+    return name.startsWith("config-") && name.endsWith(".json") && name !== "config.latest.json";
+}
+/**
+ * Keep the `keep` most-recently-modified entries of `dir` that `select`
+ * admits and remove the rest. Best-effort: an unreadable dir is a no-op, an
+ * unreadable entry sorts oldest (pruned first), and a failed removal is
+ * retried by the next call. Shared by the config backups above and the task
+ * migration snapshots (#897).
+ */
+export function pruneToNewest(dir, keep, select) {
     let entries;
     try {
-        entries = fs.readdirSync(backupDir);
+        entries = fs.readdirSync(dir, { withFileTypes: true });
     }
     catch {
         return;
     }
-    const timestamped = entries
-        .filter((n) => n.startsWith("config-") && n.endsWith(".json") && n !== "config.latest.json")
-        .map((name) => {
-        const full = path.join(backupDir, name);
+    const candidates = entries
+        .filter(select)
+        .map((entry) => {
+        const full = path.join(dir, entry.name);
         let mtime = 0;
         try {
             mtime = fs.statSync(full).mtimeMs;
@@ -136,12 +149,12 @@ function pruneOldBackups(backupDir) {
         return { path: full, mtime };
     })
         .sort((a, b) => b.mtime - a.mtime);
-    for (const stale of timestamped.slice(MAX_CONFIG_BACKUPS)) {
+    for (const stale of candidates.slice(keep)) {
         try {
-            fs.unlinkSync(stale.path);
+            fs.rmSync(stale.path, { recursive: true, force: true });
         }
         catch {
-            // Best-effort prune; next save will retry.
+            // Best-effort prune; the next call will retry.
         }
     }
 }

package/dist/core/config/config-walker.js

@@ -21,6 +21,7 @@
  *   - z.record(...)        → JSON-parse value, validate
  */
 import { z } from "zod";
+import { isRecord } from "../common.js";
 import { UsageError } from "../errors.js";
 import { AkmConfigBaseSchema, EngineConfigSchema, listTopLevelConfigKeys } from "./config-schema.js";
 import { deepMergeConfig } from "./deep-merge.js";
@@ -110,7 +111,7 @@ function resolveSchemaAt(path, config, raw) {
             // Cannot descend into a non-object schema.
             return undefined;
         }
-        existing = isPlainObject(existing) ? existing[segment] : undefined;
+        existing = isRecord(existing) ? existing[segment] : undefined;
     }
     // Preserve leaf refinements/transforms for validation. Traversal unwraps at
     // the start of each loop iteration, while coercion unwraps independently.
@@ -130,7 +131,7 @@ function selectUnionObjectOption(candidates, segment, existing, raw) {
         if (requested)
             return requested;
     }
-    if (isPlainObject(existing)) {
+    if (isRecord(existing)) {
         const selected = options.find((option) => Object.entries(option.shape).some(([key, field]) => key in existing && unwrap(field) instanceof z.ZodLiteral && field.safeParse(existing[key]).success));
         if (selected)
             return segment in selected.shape ? selected : undefined;
@@ -197,9 +198,7 @@ export function configSet(config, dotted, raw) {
     // Merge a JSON object patch with the existing value before that current
     // schema transform,
     // otherwise the synthesized default can overwrite an explicit false.
-    const candidate = judgmentObjectPath && isPlainObject(value)
-        ? deepMergeConfig(isPlainObject(existing) ? existing : {}, value)
-        : value;
+    const candidate = judgmentObjectPath && isRecord(value) ? deepMergeConfig(isRecord(existing) ? existing : {}, value) : value;
     // Validate the coerced value against the leaf schema. This catches enum
     // mismatches, out-of-range numbers, schema-level shape errors (writable
     // npm/website sources via .superRefine, strict-mode unknown keys in nested
@@ -220,7 +219,7 @@ export function configSet(config, dotted, raw) {
             .join("\n");
         throw new UsageError(`Invalid value for ${dotted}:\n${lines}`, "INVALID_FLAG_VALUE");
     }
-    const next = setPath(config, path, isPlainObject(existing) && isPlainObject(parsed.data) ? deepMergeConfig(existing, parsed.data) : parsed.data);
+    const next = setPath(config, path, isRecord(existing) && isRecord(parsed.data) ? deepMergeConfig(existing, parsed.data) : parsed.data);
     // Targeted invariant: defaultWriteTarget must point at a configured bundle
     // (#464.a). Whole-config validation happens at save time; this check fires
     // at set time so the user sees the typo immediately.
@@ -277,7 +276,7 @@ function rejectApiKeyPath(path, dotted) {
 function parseObjectPatch(raw, key) {
     try {
         const value = JSON.parse(raw);
-        if (!isPlainObject(value))
+        if (!isRecord(value))
             throw new Error("expected an object");
         return value;
     }
@@ -285,9 +284,6 @@ function parseObjectPatch(raw, key) {
         throw new UsageError(`Invalid JSON object for ${key}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_JSON_CONFIG_VALUE");
     }
 }
-function isPlainObject(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function recipeForApiKey(path, _dotted) {
     if (path[0] === "embedding")
         return "AKM_EMBED_API_KEY";

package/dist/core/config/config.js

@@ -146,13 +146,16 @@ export function acquireConfigReadFence() {
  */
 export function parseAndValidateConfigText(text, sourcePath) {
     const parsedRaw = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
-    // #852 (following #815): lift legacy `extraParams` keys — e.g.
-    // `reasoning_effort`, a documented 0.9.1 workaround — onto the first-class
-    // engine field they now shadow, before the protected-key check in
-    // `ExtraParamsSchema` gets a chance to hard-reject them. In-memory only;
-    // never written back to the file.
-    const { config: raw, lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
+    // #852 (following #815): a config still using legacy `extraParams` keys —
+    // e.g. `reasoning_effort`, a documented 0.9.1 workaround — needs to be
+    // rewritten onto the first-class engine field they now shadow. This used
+    // to happen silently, in memory, on every load; that ran forever and never
+    // converged. The lift itself is now `akm migrate apply`'s job (see
+    // src/commands/migrate/config-extra-params.ts) and persists to disk, so a
+    // config that has not been migrated yet fails closed here instead of
+    // silently drifting from what's on disk.
     const where = sourcePath ? ` at ${sourcePath}` : "";
+    const { lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
     if (conflicts.length > 0) {
         const lines = conflicts
             .map((c) => `  - engines.${c.engine}.extraParams.${c.key} (${JSON.stringify(c.extraParamsValue)}) conflicts with engines.${c.engine}.${c.field} (${JSON.stringify(c.fieldValue)})`)
@@ -160,9 +163,9 @@ export function parseAndValidateConfigText(text, sourcePath) {
         throw new ConfigError(`Invalid config${where}: extraParams and the first-class field disagree:\n${lines}\n\nEach extraParams key above has a first-class equivalent and akm will not guess which value you meant — remove the extraParams entry once the field carries the value you want.`, "INVALID_CONFIG_FILE");
     }
     if (lifted.length > 0) {
-        warn(`Config${where} uses deprecated extraParams keys with first-class equivalents; treating them as the first-class fields for this run (not written back to the file):\n  - ${lifted.join("\n  - ")}`);
+        throw new ConfigError(`Config${where} uses deprecated extraParams keys with first-class equivalents:\n  - ${lifted.join("\n  - ")}\n\nRun \`akm migrate apply\` to rewrite the config file, or move the values onto the first-class fields yourself.`, "INVALID_CONFIG_FILE");
     }
-    const parsed = AkmConfigSchema.safeParse(raw);
+    const parsed = AkmConfigSchema.safeParse(parsedRaw);
     if (!parsed.success) {
         const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
         throw new ConfigError(`Invalid config${where}:\n${lines}`, "INVALID_CONFIG_FILE");

package/dist/core/extra-params.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 { isRecord } from "./common.js";
 export const EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS = [
     "model",
     "messages",
@@ -116,31 +117,34 @@ export function formatExtraParamsIssue(label, issue) {
     const suffix = issue.path.map((part) => (typeof part === "number" ? `[${part}]` : `.${part}`)).join("");
     return `${label}${suffix} ${issue.message}`;
 }
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /**
- * Lift legacy `extraParams` keys onto their first-class engine field before
- * schema validation runs, so a 0.9.1-shaped config using (e.g.)
- * `extraParams.reasoning_effort` keeps loading now that `reasoningEffort` is
- * a first-class — and therefore protected — field (#852, following #815).
+ * Compute the legacy `extraParams` -> first-class-field lift for a raw
+ * parsed config object: a 0.9.1-shaped config using (e.g.)
+ * `extraParams.reasoning_effort` now needs `reasoningEffort` set instead,
+ * since that field became first-class — and therefore protected — in 0.9.2
+ * (#852, following #815).
  *
- * In-memory only: this never rewrites the config file. Callers should warn
- * using the returned `lifted` descriptions so the user knows to update the
- * file by hand, and reject using `conflicts` rather than silently preferring
- * either value.
+ * Pure: never touches the filesystem. Two callers use this differently:
+ * `akm migrate apply` (src/commands/migrate/config-extra-params.ts) uses the
+ * returned `config` to persist the rewrite to disk, once; `parseAndValidateConfigText`
+ * (src/core/config/config.ts) calls this only to detect whether a lift is
+ * needed and discards `config` — an unmigrated config fails closed there
+ * with a pointer to `akm migrate apply` rather than silently drifting from
+ * what's on disk. `conflicts` (an extraParams key and its first-class field
+ * set to different values) is a genuine authoring error in both callers and
+ * is never auto-resolved.
  */
 export function liftLegacyEngineExtraParams(raw) {
     const lifted = [];
     const conflicts = [];
     const rawEngines = raw.engines;
-    if (!isPlainObject(rawEngines)) {
+    if (!isRecord(rawEngines)) {
         return { config: raw, lifted, conflicts };
     }
     const engines = {};
     let anyEngineChanged = false;
     for (const [name, engineValue] of Object.entries(rawEngines)) {
-        if (!isPlainObject(engineValue) || !isPlainObject(engineValue.extraParams)) {
+        if (!isRecord(engineValue) || !isRecord(engineValue.extraParams)) {
             engines[name] = engineValue;
             continue;
         }

package/dist/core/improve-result.js

@@ -2,6 +2,7 @@
 // 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 { cloneExecutionJsonObject } from "../execution/json.js";
+import { isRecord } from "./common.js";
 const COMMON_FIELDS = [
     "schemaVersion",
     "ok",
@@ -50,9 +51,6 @@ const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]
 function fail(message) {
     throw new Error(`invalid improve-result envelope: ${message}`);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function requireExactFields(value, allowed) {
     const unknown = Object.keys(value).filter((key) => !allowed.has(key));
     if (unknown.length > 0)

package/dist/core/json-schema.js

@@ -53,6 +53,7 @@
  * exactly that for `output:` and `params` schemas). It deliberately does NOT
  * change {@link validateJsonSchemaSubset}'s permissive evaluation semantics.
  */
+import { isRecord } from "./common.js";
 /**
  * Deepest schema nesting either walk descends into — {@link
  * validateJsonSchemaSubset} evaluating a value, and {@link
@@ -168,9 +169,6 @@ function pointerFor(path) {
 function pushIssue(issues, path, keyword, kind, message) {
     issues.push({ path: [...path], pointer: pointerFor(path), keyword, kind, message });
 }
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /** Values the runtime's reference-equality `enum` check can enforce correctly. */
 function isSupportedEnumValue(value) {
     return (value === null ||
@@ -228,7 +226,7 @@ function checkDefinitionNode(schema, path, issues, depth) {
             continue;
         }
         branches.forEach((branch, index) => {
-            if (isPlainObject(branch)) {
+            if (isRecord(branch)) {
                 checkDefinitionNode(branch, [...path, keyword, index], issues, depth + 1);
             }
             else {
@@ -237,7 +235,7 @@ function checkDefinitionNode(schema, path, issues, depth) {
         });
     }
     if (schema.not !== undefined) {
-        if (isPlainObject(schema.not)) {
+        if (isRecord(schema.not)) {
             checkDefinitionNode(schema.not, [...path, "not"], issues, depth + 1);
         }
         else {
@@ -250,12 +248,12 @@ function checkDefinitionNode(schema, path, issues, depth) {
         }
     }
     if (schema.properties !== undefined) {
-        if (!isPlainObject(schema.properties)) {
+        if (!isRecord(schema.properties)) {
             pushIssue(issues, [...path, "properties"], "properties", "malformed", `"properties" must be an object mapping property names to schemas`);
         }
         else {
             for (const [key, propSchema] of Object.entries(schema.properties)) {
-                if (isPlainObject(propSchema)) {
+                if (isRecord(propSchema)) {
                     checkDefinitionNode(propSchema, [...path, "properties", key], issues, depth + 1);
                 }
                 else {
@@ -265,7 +263,7 @@ function checkDefinitionNode(schema, path, issues, depth) {
         }
     }
     if (schema.items !== undefined) {
-        if (isPlainObject(schema.items)) {
+        if (isRecord(schema.items)) {
             checkDefinitionNode(schema.items, [...path, "items"], issues, depth + 1);
         }
         else if (Array.isArray(schema.items)) {
@@ -276,7 +274,7 @@ function checkDefinitionNode(schema, path, issues, depth) {
         }
     }
     if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") {
-        if (isPlainObject(schema.additionalProperties)) {
+        if (isRecord(schema.additionalProperties)) {
             pushIssue(issues, [...path, "additionalProperties"], "additionalProperties", "unsupported", `schema-form "additionalProperties" is not enforced by the workflow schema subset — only "additionalProperties: false" is`);
         }
         else {
@@ -329,7 +327,7 @@ function combinatorBranches(schema, keyword) {
     const raw = schema[keyword];
     if (!Array.isArray(raw))
         return [];
-    return raw.filter(isPlainObject);
+    return raw.filter(isRecord);
 }
 /** First error of each failing branch, truncated — enough to act on without dumping every branch. */
 function summarizeBranchFailures(failures) {
@@ -364,7 +362,7 @@ function validateCombinators(value, schema, path, ctx) {
         }
     }
     const not = schema.not;
-    if (isPlainObject(not) && branchErrors(value, not, path, ctx).length === 0) {
+    if (isRecord(not) && branchErrors(value, not, path, ctx).length === 0) {
         ctx.errors.push(`${path}: value must not match the "not" schema`);
     }
 }

package/dist/core/state/migrations.js

@@ -35,6 +35,8 @@ export const STATE_MIGRATION_SAFETY_BY_ID = Object.freeze({
     "022-workflow-unit-attempts": "additive",
     "023-child-workflow-runs": "additive",
     "024-workflow-run-outputs": "additive",
+    "025-task-history-vocabulary-backfill": "data-preserving-rebuild",
+    "026-proposals-strip-legacy-fragment-refs": "data-preserving-rebuild",
 });
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
@@ -1079,6 +1081,74 @@ export const STATE_MIGRATIONS = [
       ALTER TABLE workflow_runs ADD COLUMN outputs_json TEXT;
     `,
     },
+    // ── Migration 025 — task_history D8 result-vocabulary backfill ─────────────
+    //
+    // The D8 re-code (docs/architecture/decisions/0005-task-result-vocabulary-
+    // and-legacy-read-mapping.md) renamed the written `target_kind` vocabulary
+    // and marked every new row with `targetVocab: 2` in `metadata_json`, but
+    // left every row written before it in the OLD vocabulary forever, pushing
+    // the "which generation is this row" decision onto three separate read
+    // sites (src/tasks/run/task-history.ts, src/commands/health/
+    // improve-metrics.ts, src/commands/health/windows.ts). That is exactly the
+    // shape `docs/plans/specs/p4-deletions-closeout.md` row B-51 ratified
+    // keeping "forever" — SUPERSEDED here: `task_history` is DB-owned data, the
+    // remap is deterministic and total, so it belongs in a one-time migration,
+    // not three permanently-recurring read-side shims.
+    //
+    // The remap, applied only to rows with no `targetVocab` marker yet (a
+    // NULL/absent `$.targetVocab` in the JSON column — already-marked or
+    // malformed metadata_json is left untouched; malformed rows are a
+    // pre-existing, unrelated skip-and-warn concern at read time):
+    //   - target_kind 'prompt'  -> 'command' (the prepared command/agent-LLM
+    //     arm; D8 renamed its written label, this backfills the old one)
+    //   - target_kind 'command' -> 'shell'   (the legacy native shell/script
+    //     arm's shared old label; D8 split it into 'shell'/'script', and only
+    //     'shell' is reconstructable — the old vocabulary never distinguished
+    //     script from shell, matching the read mapping this migration retires)
+    // Only 'prompt' and legacy 'command' rows actually change meaning between
+    // vocabularies (see the read mapping this migration retires); every other
+    // target_kind ('workflow', NULL, or anything else) already reads
+    // identically in both, so it is left alone — including its metadata_json,
+    // since no reader consults `targetVocab` once the shim is deleted.
+    {
+        id: "025-task-history-vocabulary-backfill",
+        up: `
+      UPDATE task_history
+      SET target_kind = 'command',
+          metadata_json = json_set(metadata_json, '$.targetVocab', 2)
+      WHERE target_kind = 'prompt'
+        AND json_valid(metadata_json)
+        AND json_extract(metadata_json, '$.targetVocab') IS NULL;
+
+      UPDATE task_history
+      SET target_kind = 'shell',
+          metadata_json = json_set(metadata_json, '$.targetVocab', 2)
+      WHERE target_kind = 'command'
+        AND json_valid(metadata_json)
+        AND json_extract(metadata_json, '$.targetVocab') IS NULL;
+    `,
+    },
+    // ── Migration 026 — strip the retired proposal-ref export fragment (#898) ──
+    //
+    // Older releases could write a proposal `ref` carrying the export-fragment
+    // selector (`[bundle//]conceptId#fragment`, see src/core/asset/asset-ref.ts).
+    // `currentProposalRef` (proposals-repository.ts) now rejects any fragment, so
+    // those rows failed to parse on every read and could not be listed, repaired,
+    // or deleted through the CLI. Every surface that still reads an archived row
+    // is concept-scoped, so the fragment carries nothing they use.
+    //
+    // `#` is legal in a ref only as the fragment separator, so truncating at the
+    // first `#` is exactly the split `parseBundleRef` performs. `ref` has no
+    // UNIQUE constraint, and no writer ever produced an empty concept id, so
+    // every legacy row normalizes without a drop path.
+    {
+        id: "026-proposals-strip-legacy-fragment-refs",
+        up: `
+      UPDATE proposals
+      SET ref = substr(ref, 1, instr(ref, '#') - 1)
+      WHERE ref LIKE '%#%';
+    `,
+    },
 ];
 assertMigrationRegistry(STATE_MIGRATIONS);
 function assertStateMigrationSafetyRegistry() {
@@ -1117,7 +1187,8 @@ export function runMigrations(db, options) {
         }
         if (!options.allowHistoricalDestructiveStateUpgrade) {
             throw new Error("Refusing to migrate an existing unversioned state.db during an ordinary managed open. " +
-                "Run `akm upgrade --force` to snapshot it before migration 001.");
+                "Run `akm upgrade --force` to snapshot it before migration 001, " +
+                "or `akm upgrade --state-only` where akm cannot reinstall itself (container/global install).");
         }
         const ledger = assertMigrationLedger(lockedDb, STATE_MIGRATIONS);
         if (ledger.migrationIds.length !== 0) {
@@ -1147,7 +1218,8 @@ export function runMigrations(db, options) {
             assertMigrationLedger(lockedDb, STATE_MIGRATIONS);
             if (!options?.allowHistoricalDestructiveStateUpgrade) {
                 throw new Error(`Refusing to apply historical destructive state migration ${migration.id} during an ordinary managed open. ` +
-                    "Run `akm upgrade --force` to create a sibling state.db safety copy and apply it deliberately.");
+                    "Run `akm upgrade --force` to create a sibling state.db safety copy and apply it deliberately, " +
+                    "or `akm upgrade --state-only` where akm cannot reinstall itself (container/global install).");
             }
             if (!options.beforeHistoricalDestructiveMigration) {
                 throw new Error(`Historical destructive state migration ${migration.id} requires a verified safety-copy hook.`);

package/dist/core/state-db.js

@@ -407,7 +407,8 @@ export function openStateDatabase(dbPath, options) {
                 existingUnversionedDatabase = ledger.migrationIds.length === 0;
                 if (existingUnversionedDatabase && !options?.allowHistoricalDestructiveStateUpgrade) {
                     throw new Error("Refusing to migrate an existing unversioned state.db during an ordinary managed open. " +
-                        "Run `akm upgrade --force` to create a verified snapshot before migration 001.");
+                        "Run `akm upgrade --force` to create a verified snapshot before migration 001, " +
+                        "or `akm upgrade --state-only` where akm cannot reinstall itself (container/global install).");
                 }
             }
             finally {

package/dist/core/warn.js

@@ -122,6 +122,21 @@ export function warn(...args) {
         console.warn(...args);
     }
 }
+const warnedOnceKeys = new Set();
+/**
+ * `warn()` at most once per process for a given `key`. For diagnostics that
+ * would otherwise repeat on every read of the same bad row or value.
+ */
+export function warnOnce(key, ...args) {
+    if (warnedOnceKeys.has(key))
+        return;
+    warnedOnceKeys.add(key);
+    warn(...args);
+}
+/** TEST-ONLY. Forget every `warnOnce` key so a test can re-trigger a warning. */
+export function _resetWarnOnceForTests() {
+    warnedOnceKeys.clear();
+}
 /**
  * Emit an error to stderr unless --quiet is active.
  * Always written to the log file if one is active.

package/dist/execution/executable-identity.js

@@ -4,6 +4,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { isRecord } from "../core/common.js";
 import { UsageError } from "../core/errors.js";
 export function freezeExecutableIdentity(requested, options = {}) {
     const absolutePath = resolveExecutable(requested, options.cwd ?? process.cwd(), options.path ?? process.env.PATH ?? "");
@@ -96,9 +97,6 @@ function resolveExecutable(requested, cwd, pathValue) {
     }
     throw new UsageError(`Executable ${JSON.stringify(requested)} was not found.`, "INVALID_FLAG_VALUE");
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function invalid(label) {
     return new UsageError(`Frozen ${label} identity is invalid.`, "INVALID_FLAG_VALUE");
 }

package/dist/execution/guarded-source.js

@@ -5,17 +5,12 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter } from "../core/asset/frontmatter.js";
+import { compareCodePoints, toPosix } from "../core/common.js";
 import { UsageError } from "../core/errors.js";
 import { createExecutionSourceIdentity } from "./source.js";
 function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
-function toPosix(value) {
-    return value.replaceAll("\\", "/");
-}
-function compareCodePoints(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}
 function physicalIdentity(realPath, stat) {
     return stat.ino === 0n ? `path:${realPath}` : `inode:${stat.dev}:${stat.ino}`;
 }

package/dist/indexer/bundle-identity-guard.js

@@ -29,6 +29,7 @@
  */
 import fs from "node:fs";
 import { loadConfig } from "../core/config/config.js";
+import { rethrowIfTestIsolationError } from "../core/errors.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
@@ -50,7 +51,11 @@ function indexBundlePrefixes(dbPath) {
             .prepare("SELECT DISTINCT bundle_id AS b FROM entries WHERE bundle_id IS NOT NULL AND bundle_id != ''")
             .all().map((row) => row.b);
     }
-    catch {
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        // Best-effort startup diagnostic: a locked/corrupted index just means this
+        // pass skips the drift check (retried on the next command) rather than
+        // blocking every command on a heuristic warning.
         return undefined;
     }
     finally {