akm-cli 0.9.8-beta.1 → 0.9.8-beta.3

package/CHANGELOG.md

@@ -4,6 +4,105 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.8-beta.3] - 2026-09-02
+
+### Fixed
+
+- **The incremental index no longer misses an edit whose timestamp did not move
+  forward.** The per-directory freshness check summarised a directory as its
+  file-name set plus the single newest mtime, which lost two kinds of change.
+  An edit to any file other than the newest one landed below that maximum and
+  was invisible even though its own mtime changed — so a restore, checkout, or
+  archive extraction that stamped a plausible older date left stale content in
+  the index. And because mtime is writable by ordinary tooling (`touch -r`,
+  `rsync --times`, `cp -p`), an edit with a restored timestamp was invisible
+  outright. The directory is now digested per file over
+  `(basename, size, mtime, ctime)` at nanosecond resolution. It is the same one
+  `stat` call per file, so the incremental fast path costs what it did before.
+  Both gaps predate 0.9.8 and applied to every earlier release.
+
+  Trade-off worth knowing: `ctime` also moves on metadata-only changes such as
+  `chmod`, and after copying a tree, so those now cost one extra rescan. That
+  direction is deliberate — extra work, never stale content. Existing indexes
+  rescan once as the digest changes shape, then return to the fast path.
+
+- **`akm migrate apply` can now clear a legacy `extraParams` config.** A config
+  still carrying a liftable key such as `extraParams.temperature` fails config
+  load closed, and that error names `akm migrate apply` as the fix — but the
+  migrate command resolved the stash directory and ran the task migrator, both
+  of which load config, so it died on the very error it exists to clear. An
+  operator hitting this had no reachable way forward. The config lift now runs
+  before anything that loads config, and `akm migrate status` reports the
+  pending lift as its blocker instead of re-raising the same error. A genuine
+  conflict, where an `extraParams` key and its first-class field disagree, still
+  hard-rejects and names both values rather than guessing.
+
+- **`akm health` no longer warns about disk usage on a fresh install.** The
+  `data-dir-usage` advisory added earlier in 0.9.8 counted SQLite's `-wal` and
+  `-shm` sidecars toward the data directory's total but not toward the live
+  databases they belong to. On an untouched install the write-ahead log is most
+  of the directory, so the very first `akm health` reported a ~126x ratio and
+  exited `warn` with no user data present. Sidecars now count as part of their
+  database, and the advisory stays quiet below 1 GB, where a ratio says nothing
+  useful about disk pressure.
+
+## [0.9.8-beta.2] - 2026-09-02
+
+> **Adds state migration `026-proposals-strip-legacy-fragment-refs`.** The
+> one-way caveat below applies to it as well: once this build opens
+> `state.db`, 0.9.8-beta.1 and earlier refuse it with `unknown migration ID
+> 026-proposals-strip-legacy-fragment-refs`.
+
+### Added
+
+- **`akm health` reports data-dir disk usage** (#896). A `data-dir-usage`
+  advisory sums the data directory with a stat-only walk and warns when it is
+  more than 3× the three live databases (state.db, index.db, logs.db) or when
+  one top-level subdirectory holds more than half of it, naming that
+  subdirectory with its size and share (for example `backups/ is 70G (94% of
+  data dir)`). The walk stops after 100,000 entries and says so. Silent when
+  nothing looks wrong.
+
+### Fixed
+
+- **`akm task sync` no longer spawns `npm root --global` on every call** (#901).
+  The npm-global-root probe behind `resolveAkmInvocation` is memoized for the
+  process, so a `task sync --rebind` cycle spawns npm at most once instead of
+  twice, and an installation that loops it every minute stops accumulating an
+  npm debug log per spawn.
+- **A blocked v2 task now says how to convert it** (#902, #899). The
+  `argv-array-has-no-portable-shell-string` blocker printed by `akm migrate`
+  and the `TASK_SCHEMA_VERSION_UNSUPPORTED` read error now state that manual
+  conversion is required and name the rewrite (`command:` argv array →
+  `run:` string plus `shell:`). The full v2 → v4 field mapping is documented in
+  `docs/migration/v0.9.1-to-v0.9.2.md`.
+- **Legacy `#fragment` proposal rows are repaired instead of warned about
+  forever** (#898). State migration 026 strips the retired export-fragment
+  selector from `proposals.ref` in place so the rows parse again, and an
+  unparseable proposal row now warns once per process instead of once per
+  read (`akm health --report` read the table seven times).
+
+- **A no-op incremental `akm index` no longer costs minutes of CPU** (#900).
+  Two causes: the per-directory freshness check ran two full scans of the
+  `entries` table for every directory (O(directories × entries)), and every
+  file was read, hashed, and parsed before the freshness check decided the
+  directory was unchanged. The directory lookup now uses the existing
+  `file_path` index, and a stat-based gate over each directory's walked file
+  set skips unchanged directories before any file is read. On a synthetic
+  800-directory, 4,000-entry corpus a no-op pass fell from ~37 s to under 1 s
+  of CPU with identical entries and search results. The persisted directory
+  fingerprint now covers every walked file and `index_dir_state` gains a
+  `row_count` column; an existing index.db drains each directory once more
+  after upgrading, then takes the fast path.
+
+- **Task-migration snapshots are capped at the five most recent** (#897).
+  `akm migrate apply` writes one snapshot directory per run under
+  `backups/task-v3` and `backups/task-v4` and never pruned them; each apply
+  now keeps the five newest and removes the rest, the same policy config
+  backups already use. Nothing in the current code writes the legacy
+  `backups/migrations`, `manual`, `releases`, or `operations` directories,
+  so they are left alone; the new health advisory is what surfaces them.
+
 ## [0.9.8-beta.1] - 2026-09-01
 
 A cleanup and stabilization release: deletion of machinery that policed the
@@ -11,10 +110,45 @@ codebase's shape rather than its behaviour, and — because auditing for that
 machinery meant reading the code closely — a run of real defects it had been
 sitting on top of.
 
+> **Upgrading is one-way for `state.db`.** This release adds migration
+> `025-task-history-vocabulary-backfill`. Once any 0.9.8 command opens
+> `state.db`, the ledger contains an ID that 0.9.7 does not know, and 0.9.7
+> refuses to open it: `Refusing to open a database with a newer migration
+> ledger: unknown migration ID 025-task-history-vocabulary-backfill`.
+>
+> The refusal is deliberate — an older binary must not write a database whose
+> schema it cannot reason about — but the practical effect is that
+> **downgrading to 0.9.7 requires restoring a `state.db` backup.** Commands
+> that only read the derived index (`akm info`, `akm search`) keep working on
+> 0.9.7; everything that touches `state.db` (`akm health`, `akm task`,
+> `akm improve`, proposals) does not.
+>
+> Snapshot `state.db` before upgrading if you may need to go back:
+>
+> ```sh
+> akm info --format json    # confirm your data dir
+> sqlite3 "$DATA_DIR/state.db" "VACUUM INTO '''state.db.pre-0.9.8.bak'''"
+> ```
+
 Two security holes, two search-correctness bugs, a locale-dependent hash, a
 deletion shield that failed open, and sixteen places that answered a failure
 with a confident wrong answer instead of an error.
 
+### Changed
+
+- **`akm workflow plan` returns JSON by default**, like every other command
+  (#903). It was the one verb whose unmarked default was a human summary. That
+  exception cost a bespoke branch which could not reliably distinguish "no
+  format named" from "`--format json` named globally before the subcommand" —
+  citty parses each command level against its own argv, so the leaf read
+  `undefined` in both cases. Working around that meant reading the invocation
+  singleton, folding in a persisted `output.format`, and finally leaving a
+  resolved `"json"` on the text branch because it was indistinguishable from
+  "nothing configured" — which meant an explicit `--format json` silently did
+  nothing for anyone whose config already resolved to json. Deleted, along with
+  ~60 lines of comment justifying it. `--format text` still renders the same
+  summary through the same formatter; it is simply no longer the default.
+
 ### Fixed
 
 - **Historical state migrations are reachable where akm cannot reinstall

package/dist/commands/health/data-dir-usage.js

@@ -0,0 +1,182 @@
+// 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/.
+/**
+ * `data-dir-usage` advisory for `akm health` (#896).
+ *
+ * A real environment's `$XDG_DATA_HOME/akm` grew to 74 GB with none of the
+ * ~20 health checks saying a word about disk. 70 of the 74 GB turned out to
+ * be `backups/` (unpruned migration snapshots, see #897); the live working
+ * set (state.db + index.db + logs.db) was ~4.2 GB. Naming the largest
+ * top-level contributor and its share of the total is most of the value —
+ * `backups/ is 70G (94% of data dir)` is self-diagnosing where "akm health
+ * says nothing" is not.
+ *
+ * Best-effort and read-only: a plain recursive `fs` stat walk over the data
+ * dir, no `du` shell-out. Silent (returns `undefined`) whenever nothing
+ * looks wrong, matching the stash-exposure/type-directory-check house
+ * pattern — this is not a "always show a pass line" check.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Warn when the data dir's total size is more than this many times the
+ * combined size of the three live databases (state.db + index.db +
+ * logs.db). Chosen so a healthy install (backups roughly comparable to the
+ * live working set) stays quiet, while an order-of-magnitude blowup like
+ * the 74 GB/4.2 GB (~17x) incident trips it.
+ */
+const DATA_DIR_BLOAT_RATIO_THRESHOLD = 3;
+/**
+ * Warn when a single top-level subdirectory accounts for more than this
+ * percentage of the data dir's total size — the "one thing ate the disk"
+ * signal (94% for `backups/` in the incident).
+ */
+const DOMINANT_SUBDIR_PERCENT_THRESHOLD = 50;
+/**
+ * Cap on the number of filesystem entries the recursive size walk will
+ * `stat`. A 70 GB tree of a few thousand backup copies is cheap to walk
+ * (stat-only), but a data dir polluted with hundreds of thousands of small
+ * files (task logs, npm logs) must not make `akm health` slow. Past this
+ * cap the walk stops descending further and the advisory says its size
+ * figures are a lower bound.
+ */
+const MAX_WALK_ENTRIES = 100_000;
+/**
+ * Below this the data dir is not worth an opinion. The advisory exists for
+ * disk blowups (74 GB in the incident); on a small directory a ratio is
+ * arithmetic noise, and akm's own housekeeping can dominate it outright.
+ */
+const MIN_TOTAL_BYTES_TO_REPORT = 1_000_000_000;
+const LIVE_DB_FILES = ["state.db", "index.db", "logs.db"];
+/**
+ * SQLite writes `-wal` and `-shm` beside each database. They are part of the
+ * live working set, not overhead sitting next to it, so they must count as
+ * live: on a fresh install the WAL is most of the data dir, and leaving it
+ * out of the denominator made an empty install report a ~126x ratio.
+ */
+function liveDbBytesFor(name, sizes) {
+    return ((sizes.get(name)?.bytes ?? 0) + (sizes.get(`${name}-wal`)?.bytes ?? 0) + (sizes.get(`${name}-shm`)?.bytes ?? 0));
+}
+/**
+ * Recursively sum file sizes under `root` (stat-only, symlinks not
+ * followed so a cyclic or huge-target symlink can't blow up the walk).
+ * `budget` is a shared mutable counter across the whole tree so the
+ * `MAX_WALK_ENTRIES` cap applies to the walk as a whole, not per-branch.
+ */
+function sizeOfPath(root, budget) {
+    let stat;
+    try {
+        stat = fs.lstatSync(root);
+    }
+    catch {
+        return { bytes: 0, truncated: false };
+    }
+    if (stat.isSymbolicLink())
+        return { bytes: 0, truncated: false };
+    if (!stat.isDirectory())
+        return { bytes: stat.size, truncated: false };
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return { bytes: 0, truncated: false };
+    }
+    let bytes = 0;
+    let truncated = false;
+    for (const entry of entries) {
+        if (budget.remaining <= 0) {
+            truncated = true;
+            break;
+        }
+        budget.remaining--;
+        const sub = sizeOfPath(path.join(root, entry.name), budget);
+        bytes += sub.bytes;
+        if (sub.truncated)
+            truncated = true;
+    }
+    return { bytes, truncated };
+}
+/** `1610612736` -> `"1.5G"`. Values under 10 in a unit keep one decimal; 10+ round to an integer. */
+function formatBytes(bytes) {
+    const units = ["B", "K", "M", "G", "T"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    const rendered = unit === 0 ? String(Math.round(value)) : value < 10 ? value.toFixed(1) : String(Math.round(value));
+    return `${rendered}${units[unit]}`;
+}
+/**
+ * Build the `data-dir-usage` advisory, or `undefined` when the data dir is
+ * missing/empty/unreadable or its size looks unremarkable (neither
+ * threshold trips). `dataDir` is the caller-resolved `getDataDir()` path —
+ * this module never resolves paths or reads env itself.
+ */
+export function collectDataDirUsageAdvisory(dataDir) {
+    let topEntries;
+    try {
+        topEntries = fs.readdirSync(dataDir, { withFileTypes: true });
+    }
+    catch {
+        return undefined; // no data dir yet — nothing to report.
+    }
+    const budget = { remaining: MAX_WALK_ENTRIES };
+    let totalBytes = 0;
+    let truncated = false;
+    const sizes = new Map();
+    for (const entry of topEntries) {
+        const size = sizeOfPath(path.join(dataDir, entry.name), budget);
+        totalBytes += size.bytes;
+        if (size.truncated)
+            truncated = true;
+        sizes.set(entry.name, { bytes: size.bytes, isDirectory: entry.isDirectory() });
+    }
+    if (totalBytes === 0)
+        return undefined;
+    const subdirs = [...sizes]
+        .filter(([, size]) => size.isDirectory)
+        .map(([name, size]) => ({ name, bytes: size.bytes, percent: (size.bytes / totalBytes) * 100 }))
+        .sort((a, b) => b.bytes - a.bytes);
+    const largest = subdirs[0];
+    const liveDbBreakdown = Object.fromEntries(LIVE_DB_FILES.map((f) => [f, liveDbBytesFor(f, sizes)]));
+    const liveDbBytes = Object.values(liveDbBreakdown).reduce((a, b) => a + b, 0);
+    const ratio = liveDbBytes > 0 ? totalBytes / liveDbBytes : undefined;
+    if (totalBytes < MIN_TOTAL_BYTES_TO_REPORT)
+        return undefined;
+    const bloatWarn = ratio !== undefined && ratio > DATA_DIR_BLOAT_RATIO_THRESHOLD;
+    const dominantWarn = largest !== undefined && largest.percent > DOMINANT_SUBDIR_PERCENT_THRESHOLD;
+    if (!bloatWarn && !dominantWarn)
+        return undefined;
+    const parts = [`data dir is ${formatBytes(totalBytes)} at ${dataDir}`];
+    if (largest) {
+        parts.push(`${largest.name}/ is ${formatBytes(largest.bytes)} (${Math.round(largest.percent)}% of data dir)`);
+    }
+    if (ratio !== undefined) {
+        parts.push(`live databases (${LIVE_DB_FILES.join("+")}) total ${formatBytes(liveDbBytes)}, ~${ratio.toFixed(1)}x smaller`);
+    }
+    if (truncated) {
+        parts.push(`size figures are a lower bound — the walk stopped after ${MAX_WALK_ENTRIES} entries`);
+    }
+    const message = `${parts.join("; ")}.`;
+    return {
+        name: "data-dir-usage",
+        kind: "deterministic",
+        status: "warn",
+        confidence: "medium",
+        message,
+        evidence: {
+            dataDir,
+            totalBytes,
+            liveDbBytes,
+            liveDbBreakdown,
+            largestSubdir: largest,
+            ratio,
+            walkBounded: truncated,
+            maxWalkEntries: MAX_WALK_ENTRIES,
+        },
+    };
+}

package/dist/commands/health.js

@@ -9,7 +9,7 @@ import { ConfigError, UsageError } from "../core/errors.js";
 import { readEvents } from "../core/events.js";
 import { openLogsDatabase } from "../core/logs-db.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
-import { getConfigPath, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
+import { getConfigPath, getDataDir, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
@@ -18,6 +18,7 @@ import { queryTaskHistory } from "../storage/repositories/task-history-repositor
 import { pkgVersion } from "../version.js";
 import { collectImproveAdvisories } from "./health/advisories.js";
 import { HEALTH_CHECKS, runHealthEngineProbes } from "./health/checks.js";
+import { collectDataDirUsageAdvisory } from "./health/data-dir-usage.js";
 import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./health/improve-metrics.js";
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
@@ -197,9 +198,10 @@ function gatherImproveSummaryPhase(db, stateDbPath, since, now) {
     return { improveSummary, perRunSummaries };
 }
 /**
- * The four best-effort advisory groups beyond the health-check registry:
- * improve advisories, the `stash-git-exposure` probe, the 08 surfaces group
- * (binary-config-skew, egress-endpoints), and `plugin-version` (itlackey/akm#832).
+ * The best-effort advisory groups beyond the health-check registry: improve
+ * advisories, the `stash-git-exposure` probe, the 08 surfaces group
+ * (binary-config-skew, egress-endpoints), `type-directory-disagreement`
+ * (#831), `data-dir-usage` (#896), and `plugin-version` (itlackey/akm#832).
  * Order matches emission order in the returned array. A probe/filesystem
  * failure in any try/catch must not abort the health report — each group
  * degrades to "no advisory" independently.
@@ -251,6 +253,19 @@ function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, optio
     catch {
         // Non-fatal.
     }
+    // #896: report the data dir's total size and its largest top-level
+    // subdirectory, so a disk-usage blowup (e.g. unpruned migration snapshot
+    // backups, #897) is self-diagnosing instead of requiring `du` archaeology.
+    // Best-effort — an unreadable/missing data dir must not abort the health
+    // report.
+    try {
+        const dataDirUsage = collectDataDirUsageAdvisory(getDataDir());
+        if (dataDirUsage)
+            advisories.push(dataDirUsage);
+    }
+    catch {
+        // Non-fatal.
+    }
     // itlackey/akm#832: report installed Claude Code harness plugin version(s)
     // and warn when stale or when the plugin's own akm-cli version range no
     // longer admits this CLI. Best-effort — no plugin installed, an unreadable

package/dist/commands/migrate-cli.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { resolveStashDir } from "../core/common.js";
+import { resetConfigCache } from "../core/config/config.js";
 import { ConfigError } from "../core/errors.js";
 import { getConfigPath } from "../core/paths.js";
 import { applyConfigExtraParamsLift, findConfigExtraParamsLift } from "./migrate/config-extra-params.js";
@@ -94,6 +95,29 @@ export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runT
     // No configured bundle means there is no stash to scan — an empty domain,
     // not an error — so migrate still works before `akm bundle create`. Any
     // OTHER ConfigError propagates.
+    const configPath = getConfigPath();
+    const applyResidue = command === "migrate-apply" && !genOneArgs.includes("--dry-run");
+    // The config lift runs BEFORE anything that loads config. A config still
+    // carrying legacy extraParams keys fails `loadConfig` closed, and the error
+    // it fails with names `akm migrate apply` as the remedy -- but both
+    // `resolveStashDir` below and the task migrator itself load config, so that
+    // remedy could never reach the lift that fixes it. Applying it first is what
+    // makes the advice true. `resetConfigCache` so every load below sees the
+    // rewritten file rather than the rejected one.
+    const configExtraParams = applyResidue
+        ? applyConfigExtraParamsLift(configPath)
+        : { pending: findConfigExtraParamsLift(configPath) };
+    if (applyResidue && configExtraParams.applied)
+        resetConfigCache();
+    // status and --dry-run cannot rewrite the file, so a pending lift still
+    // blocks every config load below. Report it as the blocker rather than
+    // letting the operator hit the same circular error again.
+    const pendingLift = applyResidue ? undefined : configExtraParams.pending;
+    if (pendingLift && pendingLift.lifted.length > 0) {
+        output(command, { status: "blocked", blockers: pendingLift.lifted, configExtraParams });
+        process.exitCode = EXIT_CODES.GENERAL;
+        return;
+    }
     let stashDir;
     try {
         stashDir = resolveStashDir();
@@ -102,8 +126,6 @@ export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runT
         if (!(error instanceof ConfigError) || error.code !== "STASH_DIR_NOT_FOUND")
             throw error;
     }
-    const configPath = getConfigPath();
-    const applyResidue = command === "migrate-apply" && !genOneArgs.includes("--dry-run");
     const first = await callMigrateTool(genOneArgs, runTool);
     if (first.status !== EXIT_CODES.SUCCESS && first.status !== EXIT_CODES.GENERAL) {
         process.exitCode = first.status;
@@ -133,9 +155,6 @@ export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runT
                 ? { recovered: await recoverStaleTxns(stashDir) }
                 : { pending: findStaleTxnEntries(stashDir) },
         };
-    const configExtraParams = applyResidue
-        ? applyConfigExtraParamsLift(configPath)
-        : { pending: findConfigExtraParamsLift(configPath) };
     output(command, { ...combined, ...stashSections, configExtraParams });
     if (combined.status === "blocked")
         process.exitCode = EXIT_CODES.GENERAL;

package/dist/commands/workflow-cli.js

@@ -7,18 +7,12 @@
  * `create --print` emits Markdown; execution accepts peer `.md` and
  * GitHub-shaped `.yml` workflow sources. Validate with `akm lint --type workflows`.
  */
-import { getParsedInvocation } from "../cli/invocation.js";
 import { getStringArg } from "../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
-import { getOutputMode } from "../output/context.js";
-import { renderGenericText } from "../output/generic-render.js";
-import { deliverRendered } from "../output/html-render.js";
-import { shapeForCommand } from "../output/shapes.js";
-import { formatPlain } from "../output/text.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
 import { abandonWorkflowRun, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
@@ -319,61 +313,17 @@ const workflowPlanCommand = defineJsonCommand({
     },
     async run({ args }) {
         const result = await akmWorkflowPlan(args.ref);
-        // B-46/B-57: `akm workflow plan` is read-only introspection whose UNMARKED
-        // default is a human summary — `--format json` (B-N9) is the opt-in for
-        // the full structure, the mirror image of every other verb's json-by-
-        // default (DEFAULT_CONFIG.output.format).
-        //
-        // Detecting "the caller named no format at all" MUST NOT read
-        // `args.format` (code-review round 4, finding 3 / Review log R3):
-        // citty's one-parse rule (GLOBAL_OUTPUT_ARGS's own doc comment, "no
-        // command body may read these args") isn't just style here — reading it
-        // is actively wrong. citty parses each command level against only that
-        // level's own remaining argv, so a GLOBAL, pre-subcommand `--format json`
-        // (e.g. `akm --format json workflow plan <ref>`) is consumed by the ROOT
-        // command's own declared `format` arg before the `workflow`/`plan`
-        // subcommand tokens are even resolved — this LEAF's `args.format` reads
-        // `undefined` in exactly that case too, indistinguishable from "no
-        // format was named anywhere". Reproduced live: that invocation printed
-        // the human TEXT summary at exit 0 even though `getOutputMode().format`
-        // was already `"json"` (the control, `akm --format json workflow list`,
-        // correctly emitted JSON — only this leaf's own arg-read was wrong).
-        // Detect it instead off the process-wide invocation singleton
-        // (`getParsedInvocation`, src/cli/invocation.ts) — the same canonical,
-        // position-independent argv parse `src/cli.ts` mints ONCE at startup
-        // (`setParsedInvocation`, immediately before `initOutputMode` builds the
-        // `getOutputMode()` singleton from that identical argv), so this agrees
-        // with `getOutputMode()` regardless of where `--format` appeared. A bare
-        // `process.argv` read is reserved for `src/cli.ts`/`cli/invocation.ts`
-        // themselves (`lint-process-argv.ts`); every other module reads through
-        // this singleton instead. When explicit, this defers to the normal
-        // `output()` path (json/yaml/text/md/html/jsonl, `--output <path>`)
-        // unchanged; when absent, it reproduces `output()`'s OWN "text" branch
-        // verbatim (same shape/detail projection, same registered-formatter-or-
-        // generic-fallback, same `--output <path>` handling) without touching
-        // the shared dispatcher other commands rely on.
-        //
-        // "No format named anywhere" also has to check the RESOLVED mode, not
-        // just argv: `getOutputMode().format` already folds a persisted
-        // `output.format` config default in ahead of the hardcoded "json"
-        // fallback (`resolveOutputMode`, src/output/context.ts — argv ?? config
-        // default ?? "json"). A user who has configured e.g. `output.format:
-        // "yaml"` gets yaml from every other command with no `--format` on the
-        // line; `workflow plan` must honor that too instead of forcing its
-        // human-text branch over a real persisted default. A resolved format of
-        // exactly "json" is deliberately left on the text branch below: it's
-        // indistinguishable from "nothing configured" (DEFAULT_CONFIG.output.format
-        // is also "json" — OutputConfigSchema's `format` carries no independent
-        // zod default, so the merge is the only source), and collapsing that case
-        // onto the JSON envelope would erase the documented unmarked-default text
-        // summary for the overwhelmingly common "user configured nothing" case.
-        const mode = getOutputMode();
-        if (getParsedInvocation().getFlagValue("--format") === undefined && mode.format === "json") {
-            const shaped = shapeForCommand("workflow-plan", result, mode.detail, mode.shape);
-            const plain = formatPlain("workflow-plan", shaped, mode.detail);
-            deliverRendered(plain ?? renderGenericText("workflow-plan", shaped), mode.outputPath);
-            return;
-        }
+        // json-by-default, like every other verb (#903). This used to default to
+        // the human summary, which cost ~60 lines of branch: `args.format` cannot
+        // detect "no format named" (citty parses per level, so a global
+        // pre-subcommand `--format json` is eaten by the ROOT command and the leaf
+        // reads undefined), so it had to route through `getParsedInvocation()`,
+        // then fold in a persisted `output.format`, and then still leave a
+        // resolved "json" on the text branch because that is indistinguishable
+        // from "nothing configured". The last compromise meant an explicit
+        // `--format json` silently did nothing for anyone whose config already
+        // resolved to json. `--format text` still renders the summary through the
+        // registered formatter; it is just no longer the unmarked default.
         output("workflow-plan", result);
     },
 });

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

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

package/dist/core/state/migrations.js

@@ -36,6 +36,7 @@ export const STATE_MIGRATION_SAFETY_BY_ID = Object.freeze({
     "023-child-workflow-runs": "additive",
     "024-workflow-run-outputs": "additive",
     "025-task-history-vocabulary-backfill": "data-preserving-rebuild",
+    "026-proposals-strip-legacy-fragment-refs": "data-preserving-rebuild",
 });
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
@@ -1127,6 +1128,27 @@ export const STATE_MIGRATIONS = [
         AND json_extract(metadata_json, '$.targetVocab') IS NULL;
     `,
     },
+    // ── Migration 026 — strip the retired proposal-ref export fragment (#898) ──
+    //
+    // Older releases could write a proposal `ref` carrying the export-fragment
+    // selector (`[bundle//]conceptId#fragment`, see src/core/asset/asset-ref.ts).
+    // `currentProposalRef` (proposals-repository.ts) now rejects any fragment, so
+    // those rows failed to parse on every read and could not be listed, repaired,
+    // or deleted through the CLI. Every surface that still reads an archived row
+    // is concept-scoped, so the fragment carries nothing they use.
+    //
+    // `#` is legal in a ref only as the fragment separator, so truncating at the
+    // first `#` is exactly the split `parseBundleRef` performs. `ref` has no
+    // UNIQUE constraint, and no writer ever produced an empty concept id, so
+    // every legacy row normalizes without a drop path.
+    {
+        id: "026-proposals-strip-legacy-fragment-refs",
+        up: `
+      UPDATE proposals
+      SET ref = substr(ref, 1, instr(ref, '#') - 1)
+      WHERE ref LIKE '%#%';
+    `,
+    },
 ];
 assertMigrationRegistry(STATE_MIGRATIONS);
 function assertStateMigrationSafetyRegistry() {

package/dist/core/warn.js

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