akm-cli 0.9.7 → 0.9.8-beta.1

package/dist/core/adapter/adapters/tool-dir-shared.js

@@ -49,21 +49,15 @@
 import path from "node:path";
 import { createAdapterExtensions, } from "../../../execution/source.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { toPosix } from "../../common.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
 import { skillDirectoryDiagnostics } from "./akm-lint.js";
-import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
-/** OKF reserved structural files (D-R6) — excluded at every depth, case-insensitive. */
-const RESERVED_FILES = new Set(["index.md", "log.md"]);
-/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
-const MAX_CONTENT_CHARS = 100_000;
+import { hashContent, nonEmptyString, RESERVED_FILES, readTags, runBaseValidateChecks } from "./shared.js";
 /** The canonical (plural) subdir spellings writes normalize to (open-question-6). */
 const CANONICAL_COMMAND_DIR = "commands";
 const CANONICAL_AGENT_DIR = "agents";
 const CANONICAL_SKILL_DIR = "skills";
 const SKILL_MANIFEST = "SKILL.md";
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
 function isReserved(base) {
     return RESERVED_FILES.has(base.toLowerCase());
 }
@@ -122,7 +116,7 @@ export function recognizeToolDir(layout, c, file) {
         adapterId: layout.adapterId,
         type: cls.type,
         name,
-        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+        content: body,
     };
     if (cls.type === "instruction")
         doc.ownsPresentation = true;

package/dist/core/adapter/adapters/website-snapshot-adapter.js

@@ -28,6 +28,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../asset/frontmatter.js";
+import { toPosix } from "../../common.js";
 import { hashContent, nonEmptyString, runBaseValidateChecks } from "./shared.js";
 /** A snapshot bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
@@ -37,11 +38,6 @@ const PAGES_PREFIX = "stash/knowledge/";
 const MANIFEST_FILE = "manifest.json";
 /** The tag the snapshot writer stamps on every crawled page. */
 const WEBSITE_TAG = "website";
-/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
-const MAX_CONTENT_CHARS = 100_000;
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
 function parseSnapshotFrontmatter(raw) {
     const out = { tags: [] };
     const block = parseFrontmatterBlock(raw);
@@ -98,7 +94,7 @@ function recognize(c, file) {
         ownsPresentation: true,
         type: "website",
         name,
-        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+        content: body,
     };
     if (fm.description !== undefined)
         doc.description = fm.description;

package/dist/core/adapter/validate-context.js

@@ -48,9 +48,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { assetPathForName, stashDirFor } from "../asset/asset-placement.js";
 import { typeNameFromConceptId } from "../asset/resolve-ref.js";
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
+import { toPosix } from "../common.js";
 /** Build the overlay map, keyed by POSIX path relative to `root`. */
 function buildOverlay(root, changes) {
     const overlay = new Map();

package/dist/core/asset/asset-placement.js

@@ -25,10 +25,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { toPosix } from "../common.js";
 import { DERIVED_SUFFIX, SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
-function toPosix(input) {
-    return input.replace(/\\/g, "/");
-}
 const workflowSpec = {
     isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
     toCanonicalName: (typeRoot, filePath) => {

package/dist/core/asset/frontmatter.js

@@ -323,6 +323,102 @@ export function removeFrontmatterListValues(raw, key, values) {
     }
     return changed ? out.join("\n") : null;
 }
+/**
+ * Rewrite specific VALUES in one frontmatter list key to new spellings,
+ * preserving every other byte — the rename counterpart to
+ * {@link removeFrontmatterListValues}, used by `akm lint --fix` to migrate
+ * retired `type:slug` xref values (`xrefs:`/`supersededBy:`/`contradictedBy:`)
+ * to their conceptId form once resolution confirms the rewritten spelling
+ * still points at a real asset.
+ *
+ * Handles the same three spellings a belief channel appears in: a block
+ * sequence, an inline flow, and a bare scalar. `replacements` maps an
+ * unquoted OLD value to its NEW value; a value not present in the map is left
+ * untouched byte-for-byte (including any quoting it had).
+ *
+ * Returns the rewritten source, or `null` when `raw` has no well-formed
+ * frontmatter block or nothing matched, so the caller can leave the file
+ * untouched. Deliberately source-preserving, like its sibling.
+ */
+export function rewriteFrontmatterListValue(raw, key, replacements) {
+    if (replacements.size === 0)
+        return null;
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return null;
+    const out = [];
+    let changed = false;
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (index === 0 || index >= closeIdx) {
+            out.push(line);
+            index += 1;
+            continue;
+        }
+        const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (kv === null || kv[1] !== key) {
+            out.push(line);
+            index += 1;
+            continue;
+        }
+        const rest = kv[2].trim();
+        // Inline flow: xrefs: [a, b]
+        const flow = rest.match(/^\[(.*)\]$/);
+        if (flow !== null) {
+            const items = flow[1].split(",").map((item) => item.trim());
+            const nextItems = items.map((item) => {
+                if (!item)
+                    return item;
+                const replacement = replacements.get(unquote(item));
+                if (replacement === undefined)
+                    return item;
+                changed = true;
+                return replacement;
+            });
+            out.push(items.length > 0 && items[0] !== "" ? `${kv[1]}: [${nextItems.join(", ")}]` : line);
+            index += 1;
+            continue;
+        }
+        // Bare scalar: xrefs: a
+        if (rest !== "") {
+            const replacement = replacements.get(unquote(rest));
+            if (replacement === undefined) {
+                out.push(line);
+            }
+            else {
+                changed = true;
+                out.push(`${kv[1]}: ${replacement}`);
+            }
+            index += 1;
+            continue;
+        }
+        // Block sequence: the key line, then `  - value` items.
+        out.push(line);
+        let cursor = index + 1;
+        while (cursor < closeIdx) {
+            const itemLine = lines[cursor];
+            const itemMatch = itemLine.match(/^(\s*-\s*)(.*)$/);
+            if (itemMatch === null)
+                break;
+            const [, prefix, value] = itemMatch;
+            const replacement = replacements.get(unquote(value));
+            if (replacement === undefined) {
+                out.push(itemLine);
+            }
+            else {
+                changed = true;
+                out.push(`${prefix}${replacement}`);
+            }
+            cursor += 1;
+        }
+        index = cursor;
+    }
+    return changed ? out.join("\n") : null;
+}
 /**
  * Parse a YAML scalar value (string, boolean, or number).
  *

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-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,7 @@ 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",
 });
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
@@ -1079,6 +1080,53 @@ 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;
+    `,
+    },
 ];
 assertMigrationRegistry(STATE_MIGRATIONS);
 function assertStateMigrationSafetyRegistry() {
@@ -1117,7 +1165,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 +1196,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/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");
 }