akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/lint/env-key-rules.js

@@ -2,32 +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/.
 /**
- * Vault security lint rules — flags known-dangerous environment variable names.
+ * Environment security lint rules — flags known-dangerous variable names.
  *
- * These env var names, when present as vault keys, indicate the vault can be
+ * These env var names, when present in an environment file, indicate the file can be
  * used to hijack process execution via loader injection, path override, or
  * shell/runtime startup hooks.  The lint pass emits a warning-level finding;
- * it does NOT block vault load or `akm vault setKey`.
+ * it does NOT block local environment edits.
  *
  * Enforcement scope:
- *   - `akm lint` reports findings as `dangerous-vault-key` (non-blocking warn).
- *   - `akm add` BLOCKS install unless `--allow-insecure` is set (or, on TTY,
+ *   - `akm lint` reports findings as `dangerous-env-key` (non-blocking warn).
+ *   - `akm bundle add` BLOCKS install unless `--allow-insecure` is set (or, on TTY,
  *     the user explicitly confirms at the prompt).
- *   - `akm vault setKey` does NOT consult this list — by design, the operator
- *     owns their own vault and may legitimately store any key locally.  The
- *     gate exists only for third-party stash installation.
+ *   - Local env writes do NOT consult this list — by design, the operator may
+ *     legitimately store any key locally. The gate exists only for third-party
+ *     stash installation.
  *
  * False-positive tradeoff:
  *   A handful of keys (EDITOR, VISUAL, PAGER) are included because they are
  *   invoked by many interactive tools and are a documented RCE vector when
- *   sourced from untrusted vaults.  They will also flag on benign vaults
+ *   sourced from untrusted environments. They will also flag on benign files
  *   where the operator legitimately wants to set their editor — accept the
  *   FP and bypass with `--allow-insecure` after review.
  */
 import fs from "node:fs";
 import { listKeys } from "../env/env.js";
 // ── Dangerous key set ─────────────────────────────────────────────────────────
-export const DANGEROUS_VAULT_KEYS = new Set([
+export const DANGEROUS_ENV_KEYS = new Set([
     // Dynamic linker hijacking (Linux glibc ld.so)
     "LD_PRELOAD", // forces shared library injection
     "LD_LIBRARY_PATH", // overrides library search path
@@ -89,7 +89,7 @@ export const DANGEROUS_VAULT_KEYS = new Set([
  * prefixed with `BASH_FUNC_`.  Listing every concrete name is impossible; we
  * test against this pattern set in addition to the literal `Set`.
  */
-export const DANGEROUS_VAULT_KEY_PATTERNS = [
+export const DANGEROUS_ENV_KEY_PATTERNS = [
     {
         // CVE-2014-6271 (Shellshock) — bash imports exported functions named
         // `BASH_FUNC_<name>%%` and parses their bodies, enabling RCE.
@@ -103,13 +103,13 @@ export const DANGEROUS_VAULT_KEY_PATTERNS = [
 ];
 /**
  * Returns `true` if the given key name is dangerous — either by literal match
- * against `DANGEROUS_VAULT_KEYS` or by matching any entry in
- * `DANGEROUS_VAULT_KEY_PATTERNS`.
+ * against `DANGEROUS_ENV_KEYS` or by matching any entry in
+ * `DANGEROUS_ENV_KEY_PATTERNS`.
  */
-export function isDangerousVaultKey(key) {
-    if (DANGEROUS_VAULT_KEYS.has(key))
+export function isDangerousEnvKey(key) {
+    if (DANGEROUS_ENV_KEYS.has(key))
         return true;
-    for (const { pattern } of DANGEROUS_VAULT_KEY_PATTERNS) {
+    for (const { pattern } of DANGEROUS_ENV_KEY_PATTERNS) {
         if (pattern.test(key))
             return true;
     }
@@ -117,27 +117,26 @@ export function isDangerousVaultKey(key) {
 }
 // ── Checker ───────────────────────────────────────────────────────────────────
 /**
- * Inspect a vault `.env` file and return a lint finding for every key whose
- * name appears in `DANGEROUS_VAULT_KEYS` or matches a pattern in
- * `DANGEROUS_VAULT_KEY_PATTERNS`.
+ * Inspect an `.env` file and return a lint finding for every key whose name
+ * appears in `DANGEROUS_ENV_KEYS` or matches `DANGEROUS_ENV_KEY_PATTERNS`.
  *
- * @param vaultPath  Absolute path to the `.env` file.
+ * @param envPath    Absolute path to the `.env` file.
  * @param relPath    Stash-relative path used as the `file` field in findings
- *                   (e.g. `"vaults/prod.env"`).
- * @param vaultRef   Human-readable vault ref (e.g. `"vault:prod"`) shown in
+ *                   (e.g. `"env/prod.env"`).
+ * @param envRef     Human-readable env ref (e.g. `"env/prod"`) shown in
  *                   the finding message.
  */
 /** Suppression comment token checked case-insensitively on the preceding non-empty line. */
-const SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-vault-key";
+const SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-env-key";
 /**
- * Returns the set of keys suppressed by an inline `# akm-lint-ok: dangerous-vault-key`
+ * Returns the set of keys suppressed by an inline `# akm-lint-ok: dangerous-env-key`
  * comment on the line immediately preceding the key assignment in the `.env` file.
  */
-function collectSuppressedKeys(vaultPath) {
+function collectSuppressedKeys(envPath) {
     const suppressed = new Set();
     let raw;
     try {
-        raw = fs.readFileSync(vaultPath, "utf8");
+        raw = fs.readFileSync(envPath, "utf8");
     }
     catch {
         return suppressed;
@@ -156,36 +155,21 @@ function collectSuppressedKeys(vaultPath) {
     }
     return suppressed;
 }
-export function checkVaultForDangerousKeys(vaultPath, relPath, vaultRef) {
-    const { keys } = listKeys(vaultPath);
-    const suppressed = collectSuppressedKeys(vaultPath);
+export function checkEnvForDangerousKeys(envPath, relPath, envRef) {
+    const { keys } = listKeys(envPath);
+    const suppressed = collectSuppressedKeys(envPath);
     const issues = [];
     for (const key of keys) {
-        if (!isDangerousVaultKey(key))
+        if (!isDangerousEnvKey(key))
             continue;
         if (suppressed.has(key))
             continue;
         issues.push({
             file: relPath,
-            issue: "dangerous-vault-key",
-            detail: `Env key \`${key}\` can be used to hijack process execution when injected via \`akm env run\`. Ref: ${vaultRef}. Review this file before running \`akm env run\` commands against untrusted stashes. (suppress with: ${SUPPRESSION_COMMENT} on previous line)`,
+            issue: "dangerous-env-key",
+            detail: `Env key \`${key}\` can be used to hijack process execution when injected via \`akm env run\`. Ref: ${envRef}. Review this file before running \`akm env run\` commands against untrusted stashes. (suppress with: ${SUPPRESSION_COMMENT} on previous line)`,
             fixed: false,
         });
     }
     return issues;
 }
-// ── Env-neutral aliases ───────────────────────────────────────────────────────
-//
-// These primitives guard *environment variable injection*, which is shared by
-// the `env` asset type, whole-file `secret` injection, and the `akm add`
-// supply-chain gate. The original `*Vault*` names are retained above for
-// backward compatibility (and stable lint output) through the 0.8.x
-// deprecation window; new call sites should prefer the env-neutral names.
-/** Env-neutral alias of {@link DANGEROUS_VAULT_KEYS}. */
-export const DANGEROUS_ENV_KEYS = DANGEROUS_VAULT_KEYS;
-/** Env-neutral alias of {@link DANGEROUS_VAULT_KEY_PATTERNS}. */
-export const DANGEROUS_ENV_KEY_PATTERNS = DANGEROUS_VAULT_KEY_PATTERNS;
-/** Env-neutral alias of {@link isDangerousVaultKey}. */
-export const isDangerousEnvKey = isDangerousVaultKey;
-/** Env-neutral alias of {@link checkVaultForDangerousKeys}. */
-export const checkEnvForDangerousKeys = checkVaultForDangerousKeys;

package/dist/commands/lint/index.js

@@ -4,12 +4,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
-import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { factDiagnostics, matchWorkflowPlaceholder, memoryOrphanStubApplies, nameOrTypeDiagnostics, ORPHANED_STUB_DETAIL, taskDiagnostics, workflowStructureDiagnostics, } from "../../core/adapter/adapters/akm-lint.js";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
 import { resolveStashDir } from "../../core/common.js";
-import { loadConfig } from "../../core/config/config.js";
+import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { runBaseChecks } from "./base-linter.js";
 import { checkEnvForDangerousKeys } from "./env-key-rules.js";
-import { getLinterForType } from "./registry.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 const STASH_SUBDIRS = [
     "agents",
@@ -38,21 +40,57 @@ function collectYamlFiles(dir) {
     }
     return results;
 }
-function collectMarkdownFiles(dir) {
+function collectMarkdownFiles(dir, caseInsensitive = false) {
     if (!fs.existsSync(dir))
         return [];
     const results = [];
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === ".git" || entry.isSymbolicLink())
+            continue;
         const full = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            results.push(...collectMarkdownFiles(full));
+            results.push(...collectMarkdownFiles(full, caseInsensitive));
         }
-        else if (entry.isFile() && entry.name.endsWith(".md")) {
+        else if (entry.isFile() && (caseInsensitive ? entry.name.toLowerCase() : entry.name).endsWith(".md")) {
             results.push(full);
         }
     }
     return results;
 }
+function lintOkfBundle(stashRoot) {
+    const flagged = [];
+    for (const filePath of collectMarkdownFiles(stashRoot, true)) {
+        const basename = path.basename(filePath).toLowerCase();
+        if (basename === "index.md" || basename === "log.md")
+            continue;
+        const relPath = path.relative(stashRoot, filePath);
+        let validMappingWithType = false;
+        try {
+            const block = parseFrontmatterBlock(fs.readFileSync(filePath, "utf8"));
+            if (block) {
+                const data = parseYaml(block.frontmatter);
+                validMappingWithType =
+                    typeof data === "object" &&
+                        data !== null &&
+                        !Array.isArray(data) &&
+                        typeof data.type === "string" &&
+                        data.type.trim().length > 0;
+            }
+        }
+        catch {
+            validMappingWithType = false;
+        }
+        if (!validMappingWithType) {
+            flagged.push({
+                file: relPath,
+                issue: "missing-type",
+                detail: "OKF concepts require parseable mapping frontmatter with a non-empty type.",
+                fixed: false,
+            });
+        }
+    }
+    return { ok: true, fixed: [], flagged, summary: { fixed: 0, flagged: flagged.length } };
+}
 function collectEnvFiles(dir) {
     const results = [];
     try {
@@ -73,45 +111,162 @@ function collectEnvFiles(dir) {
 function isFileDeletion(issue) {
     return issue.fixed === true && (issue.issue === "orphaned-stub" || issue.issue === "placeholder-stub");
 }
+// ── Per-file lint dispatch (was registry.ts + the 9 per-type linter classes) ──
+//
+// akm 0.9.0 chunk-3 (plan §12): the 9 `BaseLinter` subclasses + `LINTER_MAP`/
+// `getLinterForType` are gone. The format-generic checks are the shared
+// `runBaseChecks` (`./base-linter`); the per-`type` RULES are the `akm`
+// adapter's `validate` surface (`core/adapter/adapters/akm-lint.ts`), imported
+// here so both the read-only adapter and this fix-capable CLI sweep share ONE
+// definition of each finding. The adapter never writes; the delete-fix for the
+// two stub types is applied HERE (a core/CLI concern), reproducing the old
+// MemoryLinter/WorkflowLinter `--fix` behavior byte-for-byte.
+/**
+ * Reproduce `SkillLinter.lintDirectory`: a skill subdirectory with no
+ * `SKILL.md` is flagged `missing-skill-md` (never auto-fixable). Exported for
+ * the lint-parity golden (`tests/integration/goldens-lint-output.test.ts`).
+ */
+export function lintSkillDirectory(subdirPath, stashRoot) {
+    if (fs.existsSync(path.join(subdirPath, "SKILL.md")))
+        return [];
+    const relDir = path.relative(stashRoot, subdirPath);
+    return [{ file: relDir, issue: "missing-skill-md", detail: `no SKILL.md in ${relDir}/`, fixed: false }];
+}
+/** MemoryLinter's `orphaned-stub` check WITH its `--fix` delete (memory-linter.ts:19-65). */
+function appendMemoryStubIssue(ctx, issues) {
+    if (!memoryOrphanStubApplies(ctx.data, ctx.body))
+        return;
+    const derivedPath = `${ctx.filePath.replace(/\.md$/i, "")}.derived.md`;
+    if (fs.existsSync(derivedPath))
+        return;
+    if (ctx.fix) {
+        try {
+            fs.unlinkSync(ctx.filePath);
+            issues.push({ file: ctx.relPath, issue: "orphaned-stub", detail: "deleted orphaned stub", fixed: true });
+        }
+        catch (e) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "orphaned-stub",
+                detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
+                fixed: "failed",
+            });
+        }
+        return;
+    }
+    issues.push({ file: ctx.relPath, issue: "orphaned-stub", detail: ORPHANED_STUB_DETAIL, fixed: false });
+}
+/** WorkflowLinter's `placeholder-stub` (WITH `--fix` delete) + `invalid-workflow-structure` (workflow-linter.ts:22-79). */
+function appendWorkflowIssues(ctx, issues) {
+    const placeholder = matchWorkflowPlaceholder(ctx.body);
+    if (placeholder) {
+        if (ctx.fix) {
+            try {
+                fs.unlinkSync(ctx.filePath);
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "placeholder-stub",
+                    detail: `deleted: found "${placeholder}"`,
+                    fixed: true,
+                });
+            }
+            catch (e) {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "placeholder-stub",
+                    detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
+                    fixed: "failed",
+                });
+            }
+            return; // WorkflowLinter returns before the structure check once a stub is fixed.
+        }
+        issues.push({
+            file: ctx.relPath,
+            issue: "placeholder-stub",
+            detail: `placeholder text: "${placeholder}"`,
+            fixed: false,
+        });
+    }
+    // NB: the CLI passes the ABSOLUTE filePath to parseWorkflow (matching the old
+    // WorkflowLinter), whereas the adapter passes the change relPath.
+    issues.push(...workflowStructureDiagnostics(ctx.relPath, ctx.raw, ctx.filePath));
+}
+/**
+ * Lint ONE asset file: the shared base checks, then the winning stash subdir's
+ * per-`type` extra rules. Replaces `getLinterForType(subdir).lint(ctx)`.
+ * `--fix` mutations (frontmatter rewrites inside `runBaseChecks`; stub deletes
+ * here) are applied when `ctx.fix` is set.
+ */
+export function lintAssetFile(ctx, subdir) {
+    const issues = runBaseChecks(ctx);
+    switch (subdir) {
+        case "agents":
+            issues.push(...nameOrTypeDiagnostics(ctx.relPath, ctx.data, ctx.frontmatter, ["agent"]));
+            break;
+        case "commands":
+            issues.push(...nameOrTypeDiagnostics(ctx.relPath, ctx.data, ctx.frontmatter, ["command"]));
+            break;
+        case "facts":
+            issues.push(...factDiagnostics(ctx.relPath, ctx.data));
+            break;
+        case "tasks":
+            issues.push(...taskDiagnostics(ctx.relPath, ctx.data));
+            break;
+        case "memories":
+            appendMemoryStubIssue(ctx, issues);
+            break;
+        case "workflows":
+            appendWorkflowIssues(ctx, issues);
+            break;
+        // knowledge / lessons / skills: base checks only (skill directory-level
+        // `missing-skill-md` runs separately, per-subdir, in the sweep loop).
+    }
+    return issues;
+}
 // ── Main ──────────────────────────────────────────────────────────────────────
 export function akmLint(options = {}) {
-    const stashRoot = options.dir ?? options.config?.stashDir ?? resolveStashDir();
     // Collect secondary stash roots from configured filesystem sources so that
     // cross-stash refs (e.g. referencing assets in dimm-city/agent-stash) are
     // not falsely flagged as missing-ref.
     const cfg = options.config ?? loadConfig();
-    const extraStashRoots = resolveSourceEntries(stashRoot, cfg)
-        .map((s) => s.path)
-        .filter((p) => p !== stashRoot && fs.existsSync(p));
-    const fix = options.fix ?? false;
+    // 0.9.0 (spec §10.1): the primary stash is the defaultBundle's path.
+    const stashRoot = options.dir ?? primaryBundlePath(cfg) ?? resolveStashDir();
+    const sources = resolveSourceEntries(stashRoot, cfg);
+    const configuredAdapter = sources.find((source) => path.resolve(source.path) === path.resolve(stashRoot))?.adapterId;
+    const adapterId = configuredAdapter ?? detectAdapterId(stashRoot);
+    if (adapterId === "okf")
+        return lintOkfBundle(stashRoot);
+    const extraStashRoots = sources.map((s) => s.path).filter((p) => p !== stashRoot && fs.existsSync(p));
+    const fix = adapterId === "akm" && options.fix === true;
     const fixed = [];
     const flagged = [];
     const dirsToScan = options.typeFilter ? STASH_SUBDIRS.filter((d) => d === options.typeFilter) : STASH_SUBDIRS;
     for (const subdir of dirsToScan) {
         const dirPath = path.join(stashRoot, subdir);
-        // Tasks are .yml files; everything else is .md
-        const files = subdir === "tasks" ? collectYamlFiles(dirPath) : collectMarkdownFiles(dirPath);
-        const linter = getLinterForType(subdir);
-        // If the linter supports directory-level checks, run them for each direct
-        // subdirectory once before the per-file loop.
-        if (typeof linter.lintDirectory === "function" && fs.existsSync(dirPath)) {
+        // Tasks are .yml files; everything else (including workflows, one
+        // markdown format now) is .md
+        const files = subdir === "tasks" ? collectYamlFiles(dirPath) : collectMarkdownFiles(dirPath, true);
+        const assetFiles = subdir === "workflows" ? files.filter((file) => path.basename(file).toLowerCase() !== "readme.md") : files;
+        // Directory-level check: skills require a SKILL.md entry point (was
+        // SkillLinter.lintDirectory). Run once per direct subdirectory before the
+        // per-file loop.
+        if (subdir === "skills" && fs.existsSync(dirPath)) {
             for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
-                if (entry.isDirectory()) {
-                    const subdirIssues = linter.lintDirectory(path.join(dirPath, entry.name), stashRoot);
-                    for (const issue of subdirIssues) {
-                        // Tristate-safe: only `true` counts as fixed; `false` and "failed"
-                        // are both flagged.
-                        if (issue.fixed === true) {
-                            fixed.push(issue);
-                        }
-                        else {
-                            flagged.push(issue);
-                        }
+                if (!entry.isDirectory())
+                    continue;
+                for (const issue of lintSkillDirectory(path.join(dirPath, entry.name), stashRoot)) {
+                    // Tristate-safe: only `true` counts as fixed; `false` and "failed"
+                    // are both flagged.
+                    if (issue.fixed === true) {
+                        fixed.push(issue);
+                    }
+                    else {
+                        flagged.push(issue);
                     }
                 }
             }
         }
-        for (const filePath of files) {
+        for (const filePath of assetFiles) {
             // Skip registry-cached read-only files — --fix must not mutate them.
             if (filePath.includes("/.cache/") || filePath.includes("/registry/"))
                 continue;
@@ -142,7 +297,7 @@ export function akmLint(options = {}) {
             else {
                 ({ data, content: body, frontmatter } = parseFrontmatter(raw));
             }
-            const issues = linter.lint({ filePath, relPath, raw, data, body, frontmatter, fix, stashRoot, extraStashRoots });
+            const issues = lintAssetFile({ filePath, relPath, raw, data, body, frontmatter, fix, stashRoot, extraStashRoots }, subdir);
             let fileDeleted = false;
             for (const issue of issues) {
                 if (isFileDeletion(issue)) {

package/dist/commands/{events.js → log.js}

@@ -2,21 +2,26 @@
 // 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/.
 /**
- * `akm events list` and `akm events tail` (#204).
+ * Programmatic event listing behind `akm log` (#204).
  *
- * Programmatic surface — the CLI dispatcher in `src/cli.ts` registers two
- * verbs that delegate here. Both return JSON envelopes shaped by
+ * Programmatic surface — the CLI dispatcher in `src/cli.ts` registers the
+ * `log` leaf command that delegates here. Returns a JSON envelope shaped by
  * `src/output/shapes.ts` so the output flows through the same shape and
  * text-renderer pipeline as the rest of the CLI (no silent
  * `JSON.stringify` fallback).
+ *
+ * 0.9.0 CLI overhaul (S3): `akmEventsTail` (and the `log tail` command it
+ * backed) was dropped — a foreground polling daemon in a one-shot CLI. The
+ * lower-level `tailEvents` poller it wrapped (src/core/events.ts) had no
+ * other caller and was removed with it.
  */
-import { parseAssetRef } from "../core/asset/asset-ref.js";
+import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
 import { UsageError } from "../core/errors.js";
-import { readEvents, tailEvents } from "../core/events.js";
+import { readEvents } from "../core/events.js";
 import { parseSinceToIso } from "../core/time.js";
 /**
- * Parse `--since` accepting either a byte-offset cursor (`@offset:<int>`) for
- * cross-process resumption, or a timestamp / epoch-ms (the existing form).
+ * Parse `--since` accepting either an opaque row cursor (`@offset:<int>`) for
+ * cross-process resumption, or a timestamp / epoch-ms.
  * Returns one of `{ sinceOffset }` or `{ since }`.
  */
 function parseSinceFlag(since) {
@@ -30,7 +35,7 @@ function parseSinceFlag(since) {
         const raw = trimmed.slice("@offset:".length);
         const value = Number.parseInt(raw, 10);
         if (Number.isNaN(value) || value < 0) {
-            throw new UsageError(`Invalid --since byte offset: "${since}". Expected @offset:<non-negative integer>.`, "INVALID_FLAG_VALUE");
+            throw new UsageError(`Invalid --since offset: "${since}". Expected @offset:<non-negative integer>.`, "INVALID_FLAG_VALUE");
         }
         return { sinceOffset: value };
     }
@@ -43,19 +48,31 @@ function validateRef(ref) {
     if (!trimmed) {
         throw new UsageError("--ref cannot be empty.", "INVALID_FLAG_VALUE");
     }
-    parseAssetRef(trimmed);
+    const parsed = parseBundleRef(trimmed);
+    return makeBundleRef(parsed.bundle, parsed.conceptId);
+}
+function validateRunId(run) {
+    if (run === undefined)
+        return undefined;
+    const trimmed = run.trim();
+    if (!trimmed) {
+        throw new UsageError("--run cannot be empty.", "INVALID_FLAG_VALUE");
+    }
     return trimmed;
 }
 export function akmEventsList(options = {}) {
     const ref = validateRef(options.ref);
+    const run = validateRunId(options.run);
     const parsed = parseSinceFlag(options.since);
     const result = readEvents({
         since: parsed.since,
         sinceOffset: parsed.sinceOffset,
         type: options.type,
         ref,
+        runId: run,
         excludeTags: options.excludeTags,
         includeTags: options.includeTags,
+        limit: options.limit,
     }, options.ctx);
     return {
         schemaVersion: 1,
@@ -64,36 +81,9 @@ export function akmEventsList(options = {}) {
         ...(options.type !== undefined ? { type: options.type } : {}),
         ...(parsed.since !== undefined ? { since: parsed.since } : {}),
         ...(parsed.sinceOffset !== undefined ? { sinceOffset: parsed.sinceOffset } : {}),
+        ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(run !== undefined ? { run } : {}),
         nextOffset: result.nextOffset,
         events: result.events,
     };
 }
-export async function akmEventsTail(options = {}) {
-    const ref = validateRef(options.ref);
-    const parsed = parseSinceFlag(options.since);
-    const tailOptions = {
-        since: parsed.since,
-        sinceOffset: parsed.sinceOffset,
-        type: options.type,
-        ref,
-        intervalMs: options.intervalMs,
-        maxDurationMs: options.maxDurationMs,
-        maxEvents: options.maxEvents,
-        signal: options.signal,
-        onEvent: options.onEvent,
-        excludeTags: options.excludeTags,
-        includeTags: options.includeTags,
-    };
-    const result = await tailEvents(tailOptions, options.ctx);
-    return {
-        schemaVersion: 1,
-        totalCount: result.events.length,
-        ...(ref !== undefined ? { ref } : {}),
-        ...(options.type !== undefined ? { type: options.type } : {}),
-        ...(parsed.since !== undefined ? { since: parsed.since } : {}),
-        ...(parsed.sinceOffset !== undefined ? { sinceOffset: parsed.sinceOffset } : {}),
-        nextOffset: result.nextOffset,
-        events: result.events,
-        reason: result.reason,
-    };
-}

package/dist/commands/migrate-cli.js

@@ -0,0 +1,54 @@
+// 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 { defineGroupCommand, defineJsonCommand } from "../cli/shared.js";
+import { runMigrationTool } from "./migration-tool.js";
+const configArg = {
+    type: "string",
+    description: "Complete operator-prepared current config; optional when the active config is current",
+};
+export const migrateCommand = defineGroupCommand({
+    // Hidden from `--help` and the completions walker (S11): this is the
+    // self-update contract's internal command, not a surface end users
+    // discover by browsing help. `akm migrate status`/`apply` still execute
+    // normally — `hidden` only affects listing.
+    meta: { name: "migrate", hidden: true, description: "Inspect or apply config and durable database migrations" },
+    subCommands: {
+        status: defineJsonCommand({
+            meta: { name: "status", description: "Read-only cross-artifact migration eligibility check" },
+            args: { config: configArg },
+            run({ args }) {
+                return runMigrationTool(["status", ...(args.config ? ["--config", args.config] : [])]);
+            },
+        }),
+        apply: defineJsonCommand({
+            meta: { name: "apply", description: "Create a verified backup and atomically apply pending migrations" },
+            args: {
+                config: configArg,
+                // R-062: canonical spelling is kebab-case, matching every other
+                // multi-word flag in the CLI. `--dryRun` (the pre-rename spelling)
+                // is kept as an explicit, documented alias — citty registers BOTH
+                // the camelCase and kebab-case spelling of any declared flag name
+                // automatically, so this is a rename, not a breaking change: both
+                // spellings already worked, and both keep working.
+                "dry-run": {
+                    type: "boolean",
+                    alias: "dryRun",
+                    default: false,
+                    description: "Run the same eligibility checks without mutation. Alias: --dryRun.",
+                },
+            },
+            run({ args }) {
+                return runMigrationTool([
+                    "apply",
+                    ...(args.config ? ["--config", args.config] : []),
+                    ...(args.dryRun ? ["--dry-run"] : []),
+                ]);
+            },
+        }),
+    },
+    // No `defaultRun`: bare `akm migrate` is a usage error (exit 2). This group
+    // already threw its own hand-rolled UsageError; it now shares the canonical
+    // one from `defineGroupCommand` so the message and hint match every other
+    // group — owner ruling 12.
+});

package/dist/commands/migration-tool.js

@@ -0,0 +1,55 @@
+// 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 { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { NotFoundError } from "../core/errors.js";
+function migrationEntryPoint() {
+    const candidates = [
+        fileURLToPath(new URL("../../scripts/akm-migrate.ts", import.meta.url)),
+        fileURLToPath(new URL("../scripts/akm-migrate.js", import.meta.url)),
+    ];
+    return candidates.find((candidate) => fs.existsSync(candidate));
+}
+export async function runMigrationTool(args) {
+    const entry = migrationEntryPoint();
+    if (!entry && process.env.AKM_MIGRATE_ENTRY === "1") {
+        // Re-exec loop guard: we ARE the marked child, yet no migrator entry
+        // resolved and the standalone wrapper did not intercept the marker — this
+        // binary was compiled without `scripts/akm-standalone.ts`.
+        throw new NotFoundError("This binary was built without the embedded akm-migrate tool.", "FILE_NOT_FOUND", "Rebuild from scripts/akm-standalone.ts, or run akm-migrate from a source/npm install.");
+    }
+    // Compiled standalone: no scripts/ tree exists on disk (`import.meta.url`
+    // resolves inside the binary's virtual filesystem), so the documented
+    // `./akm-<ver> migrate status/apply` path used to dead-end with
+    // FILE_NOT_FOUND. Release binaries are compiled from
+    // `scripts/akm-standalone.ts`, which embeds the migrator and dispatches to
+    // it when `AKM_MIGRATE_ENTRY=1` — so re-exec ourselves with the marker.
+    // (src must not import scripts/: the dist build's tsc has `rootDir: src`.)
+    const runtime = process.versions.bun ? process.execPath : "bun";
+    const result = spawnSync(runtime, entry ? [entry, ...args] : [...args], {
+        encoding: "utf8",
+        env: entry ? process.env : { ...process.env, AKM_MIGRATE_ENTRY: "1" },
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    if (result.error) {
+        throw new NotFoundError(`Cannot start the standalone akm-migrate tool: ${result.error.message}`, "FILE_NOT_FOUND", "Install Bun, then run akm-migrate directly.");
+    }
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    // R-067: was `process.exit(result.status ?? 1)` on the failure branch,
+    // which terminates the process synchronously and skips the `finally {
+    // await disposeDispatchResources(); }` cleanup in src/cli.ts's
+    // `runCommand`. The success path (status === 0) was already fine — it
+    // just returns and the process exits 0 naturally. Setting
+    // `process.exitCode` and returning still propagates the child's exact
+    // non-zero status once the event loop drains, but lets cleanup run first —
+    // same pattern `emitJsonError` (src/cli/shared.ts) already established.
+    if (result.status !== 0) {
+        process.exitCode = result.status ?? 1;
+        return;
+    }
+}