akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/lint/index.js

@@ -5,9 +5,16 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 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 { adapterForId } from "../../core/adapter/registry.js";
+import { createValidateContext } from "../../core/adapter/validate-context.js";
+import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { conceptIdForStashFile, displayRefForConceptId } from "../../core/asset/resolve-ref.js";
+import { deriveBundleIds } from "../../core/bundle-id.js";
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { runBaseChecks } from "./base-linter.js";
 import { checkEnvForDangerousKeys } from "./env-key-rules.js";
@@ -39,21 +46,164 @@ 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;
 }
+// ── Non-akm adapter dispatch (real `adapter.validate()`, not a re-implementation) ──
+//
+// akm 0.9.0 lint/adapter-dispatch wiring: `akm lint` used to special-case
+// exactly one non-akm adapter (`okf`, via a hand-rolled `missing-type`-only
+// `lintOkfBundle` re-implementation this change deletes) and silently route
+// every OTHER non-akm bundle (llm-wiki, dotenv, claude, opencode,
+// agent-skills, website-snapshot, generic-files, akm-task, akm-workflow)
+// through the AKM-shaped STASH_SUBDIRS sweep — the wrong linter for the wrong
+// format, and the reason those adapters' own `validate()` checks (OKF's
+// `missing-ref`; llm-wiki's `uncited-raw`/`missing-description`/`broken-xref`/
+// `broken-source`) were unreachable dead code. Every bundle is now linted by
+// its OWN configured/detected adapter's `validate()` — the single definition
+// of that format's rules, shared with the (now also wired, advisory-only)
+// change-transaction pre-commit gate in `commands/proposal/repository.ts`.
+// This is intentionally the ONLY branch this module adds: the `akm` sweep
+// below is completely untouched (pinned by the goldens/test suite —
+// CRITICAL: akm findings/`--fix` must not move).
+/**
+ * Case-insensitive SUFFIX match against an adapter's declared `extensions`
+ * hint. Deliberately NOT `path.extname()`: Node's `extname(".env")` is `""`
+ * (a leading-dot-only basename has no "extension" by that definition), which
+ * would silently skip every bare `env/.env` file — exactly the shape
+ * `dotenvAdapter`'s own `classify()` (and the akm adapter's env recognition)
+ * match by plain `endsWith`, not `path.extname`. A suffix match is also a
+ * strict superset of the `path.extname` behavior for a normal `name.ext`
+ * file, so nothing that matched before stops matching.
+ */
+function matchesAdapterExtension(fileName, extensions) {
+    const lower = fileName.toLowerCase();
+    return extensions.some((candidate) => lower.endsWith(candidate.toLowerCase()));
+}
+/** Walk the whole bundle tree, collecting every file whose extension the adapter recognizes (skip `.git`, symlinks, cache/registry copies). */
+function collectAdapterFiles(root, extensions) {
+    if (!fs.existsSync(root))
+        return [];
+    const results = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === ".git" || entry.isSymbolicLink())
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile() && matchesAdapterExtension(entry.name, extensions)) {
+                // Compare PATH SEGMENTS, not raw substrings: `path.join` yields `\` on
+                // Windows so a `"/.cache/"` substring test never matches there, and a
+                // substring test would also skip a legitimately-named `registry` file.
+                const segments = path.relative(root, full).split(/[\\/]/);
+                if (segments.includes(".cache") || segments.includes("registry"))
+                    continue;
+                results.push(full);
+            }
+        }
+    };
+    walk(root);
+    return results;
+}
+/**
+ * Every closed {@link LintIssueType} member a current adapter `validate()` can
+ * legitimately emit. Anything outside this set folds onto `"adapter-diagnostic"`
+ * (see `types.ts`'s doc comment on that member) rather than being dropped.
+ */
+const KNOWN_ADAPTER_ISSUE_TYPES = new Set([
+    "unquoted-colon",
+    "missing-updated",
+    "stale-path",
+    "missing-ref",
+    "missing-type",
+    "missing-name-or-type",
+    "missing-skill-md",
+    "dangerous-env-key",
+    "uncited-raw",
+    "missing-description",
+    "broken-xref",
+    "broken-source",
+]);
+/** Map one adapter {@link Diagnostic} onto a {@link LintIssue} — see `types.ts`'s `"adapter-diagnostic"` doc comment for the open→closed reconciliation. */
+export function diagnosticToLintIssue(diag) {
+    if (KNOWN_ADAPTER_ISSUE_TYPES.has(diag.issue)) {
+        return { file: diag.file, issue: diag.issue, detail: diag.detail, fixed: diag.fixed };
+    }
+    return { file: diag.file, issue: "adapter-diagnostic", detail: `[${diag.issue}] ${diag.detail}`, fixed: diag.fixed };
+}
+/**
+ * Lint a bundle through its OWN adapter's `validate()` (spec §12.1): the
+ * adapter never writes, so every finding lands in `flagged` — `fixed` is
+ * always `false`/`"failed"` for a non-akm bundle regardless of `--fix`
+ * (the CLI option is silently a no-op here, exactly as it already was for
+ * `okf` before this change).
+ */
+async function lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cfg, options) {
+    const adapter = adapterForId(adapterId);
+    // Defensive fallback (shouldn't happen via `detectAdapterId`/a valid config
+    // — both only ever name a registered built-in): an unregistered adapter id
+    // falls back to the akm-shaped sweep, the same default `akm lint` has
+    // always applied to a bundle it can't otherwise place.
+    if (!adapter)
+        return lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options);
+    const files = collectAdapterFiles(stashRoot, adapter.extensions);
+    const changes = files.map((filePath) => ({
+        path: path.relative(stashRoot, filePath).replace(/\\/g, "/"),
+        op: "update",
+    }));
+    const ids = deriveBundleIds(sources);
+    const sourceIndex = sources.findIndex((s) => path.resolve(s.path) === path.resolve(stashRoot));
+    const componentId = sourceIndex >= 0 ? ids[sourceIndex] : stashRoot;
+    const ctx = createValidateContext({ root: stashRoot, extraRoots: extraStashRoots });
+    const diagnostics = await adapter.validate({ id: componentId, adapter: adapterId, root: stashRoot, writable: true }, changes, ctx);
+    const flagged = diagnostics.map(diagnosticToLintIssue);
+    // The cross-bundle env dangerous-key sweep (see `runEnvDangerousKeyPass`'s
+    // doc comment) ran for every non-akm adapter via the STASH_SUBDIRS
+    // fallthrough this dispatch replaces — EXCEPT `okf`, which the old code
+    // special-cased out before ever reaching that pass. Preserve both halves of
+    // that history exactly: skip only for `okf`. Some adapters (`dotenv`) ALSO
+    // find the same `dangerous-env-key` findings natively through their own
+    // `validate()` (reusing the same `dangerousEnvKeyDiagnostics` rule) — dedupe
+    // by `(file, issue, detail)` so a bundle covered both ways reports each
+    // finding once, not twice.
+    if (adapterId !== "okf") {
+        const seen = new Set(flagged.map(lintIssueDedupeKey));
+        for (const issue of runEnvDangerousKeyPass(stashRoot, extraStashRoots, sources, cfg)) {
+            const key = lintIssueDedupeKey(issue);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            flagged.push(issue);
+        }
+    }
+    return { ok: true, fixed: [], flagged, summary: { fixed: 0, flagged: flagged.length } };
+}
+function lintIssueDedupeKey(issue) {
+    return `${issue.file} ${issue.issue} ${issue.detail}`;
+}
 function collectEnvFiles(dir) {
     const results = [];
     try {
@@ -70,6 +220,45 @@ function collectEnvFiles(dir) {
     }
     return results;
 }
+/**
+ * Scan every `env/`/`secrets/` `.env` file across `[stashRoot, ...extraStashRoots]`
+ * for keys that are known to enable process-execution hijacking. This is a
+ * cross-bundle SECURITY sweep, not per-adapter validation — it has always run
+ * regardless of which format family a given root's OWN files are (verbatim
+ * extraction of the pass `lintAkmSweep` still runs inline; kept byte-identical
+ * there per the CRITICAL akm-path constraint, and reused here for the
+ * non-akm dispatch path so a non-akm PRIMARY bundle keeps the exact
+ * cross-bundle coverage it already had — the pass previously reached every
+ * non-akm adapter's bundle via the accidental STASH_SUBDIRS fallthrough this
+ * change replaces with real dispatch).
+ */
+function runEnvDangerousKeyPass(stashRoot, extraStashRoots, sources, cfg) {
+    const flagged = [];
+    const envRoots = [stashRoot, ...extraStashRoots];
+    const bundleIdByRoot = new Map(sources.map((source) => [path.resolve(source.path), source.registryId]));
+    for (const root of envRoots) {
+        const bundleId = bundleIdByRoot.get(path.resolve(root));
+        // `env` assets live under `env/`, whole-file `secret` assets under
+        // `secrets/`. `displayRefForConceptId` owns the short-default /
+        // qualified-secondary `Ref:` spelling `akm show` emits — the old
+        // hand-built `env:<base>` colon grammar is rejected by the 0.9.0 ref
+        // parser, which dead-ended a user copying the ref off a security finding.
+        for (const assetType of ["env", "secret"]) {
+            const dir = path.join(root, stashDirFor(assetType));
+            if (!fs.existsSync(dir))
+                continue;
+            for (const envPath of collectEnvFiles(dir)) {
+                const conceptId = conceptIdForStashFile(assetType, root, envPath);
+                const ref = displayRefForConceptId(conceptId, bundleId, cfg.defaultBundle);
+                const relPath = path.relative(root, envPath);
+                for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
+                    flagged.push(issue);
+                }
+            }
+        }
+    }
+    return flagged;
+}
 /** True when the issue represents a file deletion that was successfully applied. */
 function isFileDeletion(issue) {
     return issue.fixed === true && (issue.issue === "orphaned-stub" || issue.issue === "placeholder-stub");
@@ -99,7 +288,7 @@ export function lintSkillDirectory(subdirPath, stashRoot) {
 function appendMemoryStubIssue(ctx, issues) {
     if (!memoryOrphanStubApplies(ctx.data, ctx.body))
         return;
-    const derivedPath = `${ctx.filePath.replace(/\.md$/, "")}.derived.md`;
+    const derivedPath = `${ctx.filePath.replace(/\.md$/i, "")}.derived.md`;
     if (fs.existsSync(derivedPath))
         return;
     if (ctx.fix) {
@@ -187,24 +376,26 @@ export function lintAssetFile(ctx, subdir) {
     return issues;
 }
 // ── Main ──────────────────────────────────────────────────────────────────────
-export function akmLint(options = {}) {
-    // 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();
-    // 0.9.0 (spec §10.1): the primary stash is the defaultBundle's path.
-    const stashRoot = options.dir ?? primaryBundlePath(cfg) ?? resolveStashDir();
-    const extraStashRoots = resolveSourceEntries(stashRoot, cfg)
-        .map((s) => s.path)
-        .filter((p) => p !== stashRoot && fs.existsSync(p));
-    const fix = options.fix ?? false;
+/**
+ * The `akm`-adapter sweep: STASH_SUBDIRS walk + per-file `lintAssetFile` +
+ * the env dangerous-key pass. UNTOUCHED by the adapter-dispatch wiring above
+ * (CRITICAL CONSTRAINT — the overwhelming majority of real bundles use `akm`,
+ * and its findings / `--fix` behavior / exact `LintIssueType` codes are
+ * pinned by goldens + a large test suite). Only reached when the resolved
+ * adapter id is `"akm"` (or, defensively, an unregistered adapter id —
+ * see {@link lintViaAdapter}'s fallback).
+ */
+function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
+    const fix = 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);
+        // 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.
@@ -224,7 +415,7 @@ export function akmLint(options = {}) {
                 }
             }
         }
-        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;
@@ -278,31 +469,7 @@ export function akmLint(options = {}) {
     // Scan every `.env` file under <stashRoot>/env/ across all stash roots for
     // keys that are known to enable process-execution hijacking. Warn-only —
     // findings go into `flagged`, never `fixed`.
-    const envRoots = [stashRoot, ...extraStashRoots];
-    for (const root of envRoots) {
-        // The `env` assets live under `env/` (ref prefix `env:`); whole-file
-        // `secret` assets live under `secrets/` (canonical ref prefix `secret:`,
-        // singular). Map the scan directory to its canonical ref prefix so the
-        // finding's `Ref:` field matches what `akm show`/`akm secret` accept.
-        for (const { scanSubdir, refPrefix } of [
-            { scanSubdir: "env", refPrefix: "env" },
-            { scanSubdir: "secrets", refPrefix: "secret" },
-        ]) {
-            const dir = path.join(root, scanSubdir);
-            if (!fs.existsSync(dir))
-                continue;
-            for (const envPath of collectEnvFiles(dir)) {
-                const baseName = path.basename(envPath, ".env");
-                // A dotfile literally named `.env` has an empty baseName — use the full
-                // basename so it doesn't collide with `default.env` → refPrefix:default.
-                const ref = baseName === "" ? `${refPrefix}:.env` : `${refPrefix}:${baseName}`;
-                const relPath = path.relative(root, envPath);
-                for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
-                    flagged.push(issue);
-                }
-            }
-        }
-    }
+    flagged.push(...runEnvDangerousKeyPass(stashRoot, extraStashRoots, sources, cfg));
     // `ok` reflects whether the lint run completed successfully — NOT whether
     // it found anything. Findings are surfaced via `summary.flagged`; the CLI
     // gates its exit code on `--fail-on-flagged`. Conflating "issues exist"
@@ -319,3 +486,42 @@ export function akmLint(options = {}) {
         summary: { fixed: fixed.length, flagged: flagged.length },
     };
 }
+/**
+ * Lint the resolved bundle at `options.dir` (default: the primary bundle).
+ * Dispatches to the bundle's OWN adapter: the `akm` sweep for `"akm"`
+ * (unchanged), or {@link lintViaAdapter} — a real `adapter.validate()` call —
+ * for every other configured/detected adapter id (OKF, llm-wiki, dotenv,
+ * claude, opencode, agent-skills, website-snapshot, generic-files, akm-task,
+ * akm-workflow). `async` because `BundleAdapter.validate()` is async by
+ * interface contract (`core/adapter/bundle-adapter.ts`); every existing
+ * caller already runs inside an async context (`commands/agent/contribute-cli.ts`,
+ * `commands/improve/preparation.ts`) or is a test that can `await` it.
+ */
+export async function akmLint(options = {}) {
+    // Fail closed on a mistyped invocation (§24.2 "Lint" release gate): a
+    // nonexistent --dir used to walk nothing and report a clean
+    // `ok:true, flagged:0`, silently passing scripted --fail-on-flagged gates.
+    if (options.dir !== undefined && !fs.statSync(options.dir, { throwIfNoEntry: false })?.isDirectory()) {
+        throw new UsageError(`lint: --dir "${options.dir}" is not a directory.`, "INVALID_FLAG_VALUE");
+    }
+    // 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();
+    // 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);
+    const extraStashRoots = sources.map((s) => s.path).filter((p) => p !== stashRoot && fs.existsSync(p));
+    if (adapterId !== "akm")
+        return lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cfg, options);
+    // Same fail-closed rule for --type on the akm sweep: an unknown value used
+    // to filter the walk to ZERO directories — a false-clean result on the
+    // classic singular/plural typo ("workflow" for "workflows"). Non-akm
+    // adapters keep their own type vocabularies (see lintViaAdapter).
+    if (options.typeFilter && !STASH_SUBDIRS.includes(options.typeFilter)) {
+        throw new UsageError(`lint: unknown --type "${options.typeFilter}". Valid types: ${STASH_SUBDIRS.join(", ")}.`, "INVALID_FLAG_VALUE");
+    }
+    return lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options);
+}

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

@@ -2,21 +2,27 @@
 // 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 { parseRefInput } from "../core/asset/resolve-ref.js";
+import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
+import { loadConfig } from "../core/config/config.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 +36,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 +49,35 @@ function validateRef(ref) {
     if (!trimmed) {
         throw new UsageError("--ref cannot be empty.", "INVALID_FLAG_VALUE");
     }
-    parseRefInput(trimmed);
+    const parsed = parseBundleRef(trimmed);
+    // Deliberately shallow qualification: a bare conceptId is assumed to mean
+    // the default bundle, without the full priority-walk `resolveRef` performs —
+    // event refs are recorded fully qualified, so the default is the only
+    // spelling a short --ref can usefully mean here.
+    return makeBundleRef(parsed.bundle ?? loadConfig().defaultBundle, 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 +86,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

@@ -1,36 +1,116 @@
 // 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 { UsageError } from "../core/errors.js";
+import { defineGroupCommand, defineJsonCommand, output } 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",
 };
+/**
+ * Split the standalone `akm-migrate` tool's captured stdout into its
+ * progress-event lines (if any — `apply` prints one JSON line per completed
+ * sub-step, e.g. content migration / proposal-ref repair) and its final
+ * result line. `status` and `apply --dry-run` never print progress, so
+ * `progress` is empty for them; `apply` may print zero or more.
+ *
+ * Each `console.log` call in the child produces exactly one `\n`-terminated
+ * line, so splitting on `\n` and dropping the trailing empty entry from the
+ * final newline recovers exactly the lines it printed, in order.
+ */
+function splitToolStdout(stdout) {
+    const lines = stdout.split("\n");
+    if (lines.length > 0 && lines.at(-1) === "")
+        lines.pop();
+    if (lines.length === 0)
+        return { progress: [] };
+    return { progress: lines.slice(0, -1), resultLine: lines.at(-1) };
+}
+/**
+ * Runs the standalone `akm-migrate` tool and renders its result through the
+ * normal `--format` pipeline (D7) instead of a fixed JSON passthrough.
+ *
+ * The child's progress-event lines (if any) are not part of the result
+ * envelope — they print as-is, in order, regardless of `--format`, the same
+ * way `apply` always printed them before this change. Only the final result
+ * line — always a well-formed `MigrationPlan` JSON object — is parsed and
+ * handed to `output()`, so `text`/`md`/`html`/`yaml` render a real
+ * (registered or generic) rendering of it instead of silently staying JSON.
+ * `--format json` (the default) is therefore the only format whose BYTES can
+ * change here (pretty-printed via `output()` instead of the child's compact
+ * `JSON.stringify`) — every value stays identical, which is what the
+ * migration-lifecycle integration tests assert via `JSON.parse`.
+ */
+async function runMigrateSubcommand(command, args) {
+    const result = await runMigrationTool(args);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    const { progress, resultLine } = splitToolStdout(result.stdout);
+    for (const line of progress)
+        console.log(line);
+    if (resultLine !== undefined) {
+        try {
+            output(command, JSON.parse(resultLine));
+        }
+        catch {
+            // The child is expected to always print one well-formed JSON result
+            // line; if it somehow didn't, don't lose the line, just don't reshape it.
+            console.log(resultLine);
+        }
+    }
+    // R-067: `process.exitCode = …; return;` (not `process.exit()`) so the
+    // command's normal cleanup (`disposeDispatchResources()` in `runCommand`,
+    // src/cli.ts) still runs before the process exits with the child's status.
+    if (result.status !== 0) {
+        process.exitCode = result.status;
+        return;
+    }
+}
 export const migrateCommand = defineGroupCommand({
+    // S11 originally hid this from `--help`/completions as an internal,
+    // self-update-only surface. That made it undiscoverable even though the
+    // 0.9.0 upgrade instructions tell users to run it first (`akm migrate
+    // status`, `akm migrate apply`) — the one command those instructions
+    // depend on was invisible. Listed in the SYSTEM section of HELP_SECTIONS
+    // (src/cli.ts) and in shell completions now; `akm migrate status`/`apply`
+    // always executed regardless of `hidden`.
     meta: { name: "migrate", 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 },
-            async run({ args }) {
-                const { runMigrationStatus } = await import("../cli/config-migrate.js");
-                await runMigrationStatus({ preparedConfigPath: args.config });
+            run({ args }) {
+                return runMigrateSubcommand("migrate-status", ["status", ...(args.config ? ["--config", args.config] : [])]);
             },
         }),
         apply: defineJsonCommand({
             meta: { name: "apply", description: "Create a verified backup and atomically apply pending migrations" },
             args: {
                 config: configArg,
-                dryRun: { type: "boolean", default: false, description: "Run the same eligibility checks without mutation" },
+                // 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.",
+                },
             },
-            async run({ args }) {
-                const { runMigrationApply } = await import("../cli/config-migrate.js");
-                await runMigrationApply({ preparedConfigPath: args.config, dryRun: args.dryRun });
+            run({ args }) {
+                return runMigrateSubcommand("migrate-apply", [
+                    "apply",
+                    ...(args.config ? ["--config", args.config] : []),
+                    ...(args.dryRun ? ["--dry-run"] : []),
+                ]);
             },
         }),
     },
-    defaultRun() {
-        throw new UsageError("Choose `migrate status` or `migrate apply`.", "MISSING_REQUIRED_ARGUMENT");
-    },
+    // 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,46 @@
+// 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(process.versions.bun ? "../scripts/akm-migrate.js" : "../scripts/akm-migrate-node.js", import.meta.url)),
+        ...(process.versions.bun ? [fileURLToPath(new URL("../../scripts/akm-migrate.ts", import.meta.url))] : []),
+    ];
+    return candidates.find((candidate) => fs.existsSync(candidate));
+}
+/**
+ * Spawns the standalone `akm-migrate` tool and returns its captured exit
+ * status plus stdout/stderr — never writes them itself. `migrate-cli.ts`'s
+ * `status`/`apply` commands use this to reshape the child's final JSON result
+ * line through the normal `--format` pipeline (D7) while any earlier
+ * progress-event lines the child printed still go through verbatim.
+ */
+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 result = spawnSync(process.execPath, 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", "Reinstall akm-cli, or use a runtime-free standalone release binary.");
+    }
+    return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}