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

package/dist/core/git-message.js

@@ -0,0 +1,59 @@
+// 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/.
+/**
+ * Leaf util for sanitizing git commit messages.
+ *
+ * Split out of `core/write-source.ts` so that `sources/providers/git-stash.ts`
+ * (which `core/write-source.ts` imports `getCachePaths`/`listGitChangedPaths`/
+ * `parseGitRepoUrl`/`saveGitStash` from, via the `sources/providers/git`
+ * barrel, by value) does not need to import back into `write-source.ts` just
+ * for this helper — that back-edge was a 3-file static-graph cycle
+ * (write-source.ts → git.ts → git-stash.ts → write-source.ts; chunk 9 WI-9.8
+ * KILL 6 sever). Callers import `sanitizeCommitMessage` directly so
+ * the dependency graph stays acyclic.
+ */
+/**
+ * Maximum length of a sanitized git commit message. Git itself imposes no
+ * fixed limit, but message strings come from refs and `--message` flags that
+ * can be supplied by users or upstream config. A 4096-char clamp keeps audit
+ * trails readable and prevents pathological payloads from bloating the log
+ * stream a downstream consumer parses.
+ */
+const COMMIT_MESSAGE_MAX_LENGTH = 4096;
+/**
+ * Sanitize a string before passing it as `git commit -m <message>`.
+ *
+ * Defenses, in order:
+ *   1. Strip NUL bytes (`\0`) — git rejects them anyway, but we never want
+ *      them in argv.
+ *   2. Replace any CR/LF (`\r`, `\n`) and other ASCII control chars with a
+ *      single space. This collapses newline-injection attempts that would
+ *      otherwise turn a single-line commit subject into a forged trailer
+ *      block.
+ *   3. Collapse runs of whitespace into a single space and trim.
+ *   4. Clamp to {@link COMMIT_MESSAGE_MAX_LENGTH} characters.
+ *
+ * If the result is empty after sanitization the caller should substitute a
+ * default — this helper returns `""` rather than throwing because not every
+ * callsite has a sensible "invalid input" exit code, and "empty" is a
+ * recoverable signal.
+ */
+export function sanitizeCommitMessage(input) {
+    if (typeof input !== "string")
+        return "";
+    // 1. Strip NULs outright.
+    let out = input.replace(/\0/g, "");
+    // 2. Replace CR/LF + other C0 control characters (0x00-0x1F, 0x7F) with a
+    //    space. Tab (0x09) is included intentionally — commit subjects should
+    //    be a single visual line.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional sanitization
+    out = out.replace(/[\x00-\x1F\x7F]/g, " ");
+    // 3. Collapse whitespace runs and trim.
+    out = out.replace(/\s+/g, " ").trim();
+    // 4. Clamp length.
+    if (out.length > COMMIT_MESSAGE_MAX_LENGTH) {
+        out = out.slice(0, COMMIT_MESSAGE_MAX_LENGTH).trimEnd();
+    }
+    return out;
+}

package/dist/core/improve-result.js

@@ -0,0 +1,167 @@
+// 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/.
+const COMMON_FIELDS = [
+    "schemaVersion",
+    "ok",
+    "scope",
+    "dryRun",
+    "skipped",
+    "guidance",
+    "memorySummary",
+    "memoryCleanup",
+    "cyclesRun",
+    "plannedRefs",
+    "actions",
+    "distillSkipped",
+    "validationFailures",
+    "schemaRepairs",
+    "consolidation",
+    "extract",
+    "lintSummary",
+    "memoryIndexHealth",
+    "coverageGaps",
+    "evalCasesWritten",
+    "deadUrls",
+    "reflectsWithErrorContext",
+    "memoryInference",
+    "graphExtraction",
+    "memoryInferenceDurationMs",
+    "graphExtractionDurationMs",
+    "orphansPurged",
+    "proposalsExpired",
+    "reflectCooldownActions",
+    "reflectSkippedActions",
+    "reflectGuardRejectedActions",
+    "gateAutoAcceptedCount",
+    "gateAutoAcceptFailedCount",
+    "triage",
+    "proactiveMaintenance",
+    "cycleMetrics",
+    "runId",
+    "sync",
+    "terminated",
+];
+const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]);
+function fail(message) {
+    throw new Error(`invalid improve-result envelope: ${message}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireExactFields(value, allowed) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        fail(`unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.sort().join(", ")}`);
+}
+function validateCommon(value) {
+    if (typeof value.ok !== "boolean")
+        fail("ok must be a boolean");
+    if (typeof value.dryRun !== "boolean")
+        fail("dryRun must be a boolean");
+    if (!Array.isArray(value.plannedRefs))
+        fail("plannedRefs must be an array");
+    if (!isRecord(value.scope))
+        fail("scope must be an object");
+    requireExactFields(value.scope, new Set(["mode", "value"]));
+    if (value.scope.mode !== "all" && value.scope.mode !== "type" && value.scope.mode !== "ref") {
+        fail('scope.mode must be "all", "type", or "ref"');
+    }
+    if (value.scope.value !== undefined && typeof value.scope.value !== "string") {
+        fail("scope.value must be a string when present");
+    }
+    if (!isRecord(value.memorySummary))
+        fail("memorySummary must be an object");
+    requireExactFields(value.memorySummary, new Set(["eligible", "derived"]));
+    if (typeof value.memorySummary.eligible !== "number" || typeof value.memorySummary.derived !== "number") {
+        fail("memorySummary.eligible and memorySummary.derived must be numbers");
+    }
+    for (const field of [
+        "actions",
+        "validationFailures",
+        "schemaRepairs",
+        "extract",
+        "coverageGaps",
+        "deadUrls",
+    ]) {
+        if (value[field] !== undefined && !Array.isArray(value[field]))
+            fail(`${field} must be an array`);
+    }
+    for (const field of [
+        "cyclesRun",
+        "evalCasesWritten",
+        "reflectsWithErrorContext",
+        "memoryInferenceDurationMs",
+        "graphExtractionDurationMs",
+        "orphansPurged",
+        "proposalsExpired",
+        "reflectCooldownActions",
+        "reflectSkippedActions",
+        "reflectGuardRejectedActions",
+        "gateAutoAcceptedCount",
+        "gateAutoAcceptFailedCount",
+    ]) {
+        if (value[field] !== undefined && typeof value[field] !== "number")
+            fail(`${field} must be a number`);
+    }
+    for (const field of ["guidance", "runId"]) {
+        if (value[field] !== undefined && typeof value[field] !== "string")
+            fail(`${field} must be a string`);
+    }
+    for (const field of [
+        "skipped",
+        "memoryCleanup",
+        "distillSkipped",
+        "consolidation",
+        "lintSummary",
+        "memoryIndexHealth",
+        "memoryInference",
+        "graphExtraction",
+        "triage",
+        "proactiveMaintenance",
+        "cycleMetrics",
+        "sync",
+        "terminated",
+    ]) {
+        if (value[field] !== undefined && !isRecord(value[field]))
+            fail(`${field} must be an object`);
+    }
+    if (isRecord(value.terminated)) {
+        requireExactFields(value.terminated, new Set(["reason", "at", "errorMessage"]));
+        if (typeof value.terminated.reason !== "string" || typeof value.terminated.at !== "string") {
+            fail("terminated.reason and terminated.at must be strings");
+        }
+        if (value.terminated.errorMessage !== undefined && typeof value.terminated.errorMessage !== "string") {
+            fail("terminated.errorMessage must be a string when present");
+        }
+    }
+}
+/** Decode the persisted public result contract. */
+export function decodeImproveResult(input) {
+    let parsed = input;
+    if (typeof input === "string") {
+        try {
+            parsed = JSON.parse(input);
+        }
+        catch {
+            fail("not valid JSON");
+        }
+    }
+    if (!isRecord(parsed))
+        fail("root must be an object");
+    if (parsed.schemaVersion === 2) {
+        requireExactFields(parsed, V2_FIELDS);
+        validateCommon(parsed);
+        if (typeof parsed.strategy !== "string" || parsed.strategy.length === 0) {
+            fail("strategy must be a non-empty string");
+        }
+        if (parsed.strategyFilteredRefs !== undefined && !Array.isArray(parsed.strategyFilteredRefs)) {
+            fail("strategyFilteredRefs must be an array");
+        }
+        return {
+            envelope: parsed,
+            strategy: parsed.strategy,
+        };
+    }
+    fail(`unsupported schemaVersion: ${String(parsed.schemaVersion)}`);
+}

package/dist/core/lesson-lint.js

@@ -13,9 +13,7 @@
  *
  * Lint produces structured findings rather than throwing so callers can
  * batch-validate (e.g. `akm proposal accept` over a queue) and surface every
- * violation in a single pass. A strict wrapper (`assertLessonValid`) throws
- * a `UsageError` for call sites that want a fail-fast contract — most
- * notably the proposal-accept path described in v1 spec §13.1.
+ * violation in a single pass.
  *
  * The lint is intentionally side-effect free and does not import the indexer
  * or filesystem walker; it operates on a single file path + raw string. This
@@ -24,7 +22,6 @@
  */
 import fs from "node:fs";
 import { parseFrontmatter } from "./asset/frontmatter.js";
-import { UsageError } from "./errors.js";
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
@@ -74,16 +71,3 @@ export function lintLessonFile(filePath) {
     const raw = fs.readFileSync(filePath, "utf8");
     return lintLessonContent(raw, filePath);
 }
-/**
- * Strict variant: throws a `UsageError` if any finding is present. The thrown
- * error carries the full set of findings on its message and a hint pointing
- * at v1 spec §13. The first finding's `field` becomes the error's primary
- * field for callers that want to highlight the first violation.
- */
-export function assertLessonValid(filePath) {
-    const report = lintLessonFile(filePath);
-    if (report.findings.length === 0)
-        return;
-    const message = report.findings.map((f) => f.message).join("\n");
-    throw new UsageError(message, "MISSING_REQUIRED_ARGUMENT", "Lessons require non-empty `description` and `when_to_use` frontmatter fields. See v1 spec §13.");
-}

package/dist/core/logs-db.js

@@ -9,7 +9,7 @@
  * The strategic direction (stop scattering data across files/folders) means
  * every NEW log consumer queries this database; the per-run text file written
  * by the task runner is retained only as a transitional tail for humans —
- * see docs/technical/logs-audit.md for the full producer audit.
+ * per the #579 logs audit of every producer.
  *
  * ## Why a separate database from state.db
  *

package/dist/core/maintenance-barrier.js

@@ -0,0 +1,135 @@
+// 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 { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "./file-lock.js";
+import { getMaintenanceBarrierPath } from "./paths.js";
+const heldBarrierContext = new AsyncLocalStorage();
+/**
+ * Serialize restore with the short critical section that creates every
+ * long-lived AKM lock or workflow lease. The long operation keeps its own
+ * lock/lease; this barrier is released immediately after acquisition.
+ */
+export function tryAcquireMaintenanceBarrier() {
+    const lockPath = getMaintenanceBarrierPath();
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: "maintenance-start" }));
+        if (ownership) {
+            return () => releaseLock(ownership);
+        }
+        const probe = probeLock(lockPath);
+        if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
+            return undefined;
+    }
+    return undefined;
+}
+export function acquireMaintenanceBarrier() {
+    const release = tryAcquireMaintenanceBarrier();
+    if (release)
+        return release;
+    throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes.`, "INVALID_CONFIG_FILE");
+}
+export function withMaintenanceStartBarrier(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const release = acquireMaintenanceBarrier();
+    const ownership = { active: true };
+    try {
+        return heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
+/** Run while holding the start barrier, or return undefined when it is busy. */
+export function tryWithMaintenanceStartBarrier(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const release = tryAcquireMaintenanceBarrier();
+    if (!release)
+        return undefined;
+    const ownership = { active: true };
+    try {
+        return heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
+async function acquireMaintenanceBarrierAsync() {
+    const deadline = Date.now() + 5_000;
+    while (true) {
+        const release = tryAcquireMaintenanceBarrier();
+        if (release)
+            return release;
+        if (Date.now() >= deadline)
+            return acquireMaintenanceBarrier();
+        await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+}
+export async function withMaintenanceStartBarrierAsync(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const release = await acquireMaintenanceBarrierAsync();
+    const ownership = { active: true };
+    try {
+        return await heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
+function withMaintenanceStartBarrierSyncWait(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const deadline = Date.now() + 5_000;
+    let release = tryAcquireMaintenanceBarrier();
+    while (!release && Date.now() < deadline) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+        release = tryAcquireMaintenanceBarrier();
+    }
+    if (!release)
+        release = acquireMaintenanceBarrier();
+    const ownership = { active: true };
+    try {
+        return heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
+/** Register a long-lived operation atomically with restore's blocker scan. */
+export async function acquireMaintenanceActivity(name) {
+    return withMaintenanceStartBarrierAsync(async () => {
+        const directory = path.join(path.dirname(getMaintenanceBarrierPath()), "maintenance-activities");
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const lockPath = path.join(directory, `${name}-${process.pid}-${randomUUID()}.lock`);
+        const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: name }));
+        if (!ownership) {
+            throw new ConfigError(`Could not register AKM maintenance activity at ${lockPath}.`, "INVALID_CONFIG_FILE");
+        }
+        return () => releaseLock(ownership);
+    });
+}
+/** Synchronous activity registration for synchronous database handle lifetimes. */
+export function acquireMaintenanceActivitySync(name) {
+    return withMaintenanceStartBarrierSyncWait(() => {
+        const directory = path.join(path.dirname(getMaintenanceBarrierPath()), "maintenance-activities");
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const lockPath = path.join(directory, `${name}-${process.pid}-${randomUUID()}.lock`);
+        const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: name }));
+        if (!ownership) {
+            throw new ConfigError(`Could not register AKM maintenance activity at ${lockPath}.`, "INVALID_CONFIG_FILE");
+        }
+        return () => releaseLock(ownership);
+    });
+}

package/dist/core/migration-operation.js

@@ -0,0 +1,44 @@
+// 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 crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+import { getConfigPath, getDataDir } from "./paths.js";
+let afterPendingCheckHook;
+/** TEST-ONLY: run once after a clear pending-operation check. */
+export function _setAfterPendingOperationCheckHookForTests(hook) {
+    afterPendingCheckHook = hook;
+}
+function installationId() {
+    return crypto
+        .createHash("sha256")
+        .update(path.resolve(path.dirname(getConfigPath())))
+        .update("\0")
+        .update(path.resolve(getDataDir()))
+        .digest("hex")
+        .slice(0, 24);
+}
+export function getMigrationOperationRoot() {
+    return path.join(getDataDir(), "backups", "migrations", installationId());
+}
+export function getMigrationRestoreJournalPath() {
+    return path.join(getMigrationOperationRoot(), "restore-active.json");
+}
+export function getMigrationApplyJournalPath() {
+    return path.join(getMigrationOperationRoot(), "apply-active.json");
+}
+export function assertNoPendingMigrationOperation() {
+    for (const [kind, journalPath] of [
+        ["restore", getMigrationRestoreJournalPath()],
+        ["migration apply", getMigrationApplyJournalPath()],
+    ]) {
+        if (fs.existsSync(journalPath)) {
+            throw new ConfigError(`AKM ${kind} recovery is pending at ${journalPath}; refusing canonical config/database access until recovery completes.`, "INVALID_CONFIG_FILE");
+        }
+    }
+    const hook = afterPendingCheckHook;
+    afterPendingCheckHook = undefined;
+    hook?.();
+}

package/dist/core/mutation-target.js

@@ -0,0 +1,78 @@
+// 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 path from "node:path";
+import { deriveInstallations } from "../indexer/installations.js";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
+import { displayRef } from "./asset/resolve-ref.js";
+import { UsageError } from "./errors.js";
+import { prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, } from "./write-source.js";
+function canonicalSources(config) {
+    const sources = resolveSourceEntries(undefined, config);
+    const installations = deriveInstallations(sources);
+    return sources.flatMap((source, index) => {
+        const bundleId = installations[index]?.id;
+        return bundleId ? [{ bundleId, source }] : [];
+    });
+}
+function targetForCanonicalSource(config, canonical, options) {
+    const target = canonical.source.registryId
+        ? resolveWriteTarget(config, canonical.source.registryId, options)
+        : resolveWorkingStashTarget(config, options);
+    if (path.resolve(target.source.path) !== path.resolve(canonical.source.path)) {
+        throw new UsageError(`Bundle "${canonical.bundleId}" no longer resolves to its indexed source root.`);
+    }
+    return target;
+}
+/** Resolve the canonical bundle id currently assigned to a write target. */
+export function canonicalBundleIdForTarget(config, target) {
+    return (canonicalSources(config).find((candidate) => path.resolve(candidate.source.path) === path.resolve(target.source.path))?.bundleId ?? target.source.name);
+}
+/** Resolve a canonical bundle qualifier to its writable target without preparing a Git boundary. */
+export function resolveBundleWriteTarget(config, bundleId, options = {}) {
+    const canonical = canonicalSources(config).find((candidate) => candidate.bundleId === bundleId);
+    if (!canonical) {
+        throw new UsageError(`Bundle "${bundleId}" is not configured.`, "INVALID_FLAG_VALUE");
+    }
+    const target = targetForCanonicalSource(config, canonical, options);
+    return { ...target, source: { ...target.source, name: canonical.bundleId } };
+}
+function resolveExplicitMutationTarget(config, explicitTarget, options) {
+    try {
+        return resolveWriteTarget(config, explicitTarget, options);
+    }
+    catch (error) {
+        try {
+            return resolveBundleWriteTarget(config, explicitTarget, options);
+        }
+        catch {
+            throw error;
+        }
+    }
+}
+/** Reconcile a qualified mutation ref with `--target`, then resolve the write destination. */
+export function resolveMutationTarget(config, ref, explicitTarget, options = {}) {
+    const writeOptions = { requireWritable: options.requireWritable };
+    const qualifiedTarget = ref.origin ? resolveBundleWriteTarget(config, ref.origin, writeOptions) : undefined;
+    const explicitResolved = explicitTarget
+        ? resolveExplicitMutationTarget(config, explicitTarget, writeOptions)
+        : undefined;
+    if (qualifiedTarget &&
+        explicitResolved &&
+        path.resolve(qualifiedTarget.source.path) !== path.resolve(explicitResolved.source.path)) {
+        throw new UsageError(`Qualified ref bundle "${ref.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or select the same bundle.`);
+    }
+    let target = qualifiedTarget ?? explicitResolved ?? resolveWriteTarget(config, undefined, writeOptions);
+    const bundleId = ref.origin ?? canonicalBundleIdForTarget(config, target);
+    target = prepareWriteTargetForMutation({ ...target, source: { ...target.source, name: bundleId } }, { allowedAdapters: options.allowedAdapters });
+    const stableRef = { ...ref, origin: bundleId };
+    const defaultBundle = defaultBundleForTarget(config);
+    return {
+        target,
+        ref: stableRef,
+        displayRef: displayRef({ type: stableRef.type, name: stableRef.name, bundleId: stableRef.origin }, defaultBundle),
+    };
+}
+export function defaultBundleForTarget(config) {
+    return config.defaultBundle;
+}

package/dist/core/paths.js

@@ -10,8 +10,8 @@
  */
 import os from "node:os";
 import path from "node:path";
-import { IS_WINDOWS } from "./common.js";
 import { ConfigError } from "./errors.js";
+import { IS_WINDOWS } from "./platform.js";
 /**
  * Returns true when the current process appears to be running under
  * `bun test` (either via the BUN_TEST sentinel Bun sets on the test
@@ -30,10 +30,10 @@ function isUnderBunTest(env) {
  * Returns true when the given path is in a directory family the OS may
  * reap (or that the user has clearly designated as a sandbox by virtue
  * of placing it under `/tmp` or a macOS per-user temp dir). Used to
- * decide whether `AKM_STASH_DIR=$tmpdir` should also isolate config +
+ * decide whether `AKM_BUNDLE_DIR=$tmpdir` should also isolate config +
  * cache writes (so a test harness's `akm setup --yes --dir .` cannot
  * silently clobber the user's `~/.config/akm/config.json`). See
- * `docs/technical/incidents/2026-05-23-setup-clobbers-user-config.md`
+ * the 2026-05-23 setup-clobbers-user-config incident
  * for the incident that motivated this.
  *
  * Both `/var/folders/*` and `/private/var/folders/*` are matched because
@@ -67,7 +67,7 @@ export function getConfigDir(env = process.env, platform = process.platform) {
         return override;
     // Explicit XDG override wins next — tests and operators that pre-arrange
     // an isolated config dir via XDG_CONFIG_HOME (or %APPDATA% on Windows)
-    // must be honored as set, so the AKM_STASH_DIR transient-isolation rule
+    // must be honored as set, so the AKM_BUNDLE_DIR transient-isolation rule
     // below does not silently move config away from where they pointed it.
     if (platform === "win32") {
         const appData = env.APPDATA?.trim();
@@ -79,16 +79,16 @@ export function getConfigDir(env = process.env, platform = process.platform) {
         if (xdgConfigHome)
             return path.join(xdgConfigHome, "akm");
     }
-    // Isolation safety: when AKM_STASH_DIR points at a transient/sandbox path
+    // Isolation safety: when AKM_BUNDLE_DIR points at a transient/sandbox path
     // (/tmp, /var/tmp, /private/var/folders) AND no explicit config dir
-    // override is set, route config writes into `${AKM_STASH_DIR}/.akm`
+    // override is set, route config writes into `${AKM_BUNDLE_DIR}/.akm`
     // instead of the user's host ~/.config/akm. This prevents the documented
     // isolation pattern
-    //   AKM_DATA_DIR=/tmp/x AKM_STASH_DIR=/tmp/x akm setup --yes --dir .
+    //   AKM_DATA_DIR=/tmp/x AKM_BUNDLE_DIR=/tmp/x akm setup --yes --dir .
     // from silently clobbering the host config. See
-    // docs/technical/incidents/2026-05-23-setup-clobbers-user-config.md for the incident.
-    // Daily users with a persistent AKM_STASH_DIR=~/my-stash are unaffected.
-    const stashOverride = env.AKM_STASH_DIR?.trim();
+    // the 2026-05-23 setup-clobbers-user-config incident.
+    // Daily users with a persistent AKM_BUNDLE_DIR=~/my-stash are unaffected.
+    const stashOverride = env.AKM_BUNDLE_DIR?.trim();
     if (stashOverride && isTransientStashPath(stashOverride)) {
         return path.join(stashOverride, ".akm");
     }
@@ -122,7 +122,7 @@ export function getCacheDir(env = process.env) {
     // Explicit XDG/platform overrides win before the transient-stash isolation
     // rule below — tests and operators that pre-arrange XDG_CACHE_HOME (or
     // %LOCALAPPDATA% / %USERPROFILE% / %APPDATA% on Windows) must be honored
-    // as set, so the AKM_STASH_DIR transient rule does not silently move cache
+    // as set, so the AKM_BUNDLE_DIR transient rule does not silently move cache
     // writes away from where they pointed them.
     if (IS_WINDOWS) {
         const localAppData = env.LOCALAPPDATA?.trim();
@@ -145,12 +145,12 @@ export function getCacheDir(env = process.env) {
         if (xdgCacheHome)
             return path.join(xdgCacheHome, "akm");
     }
-    // Isolation safety (mirrors getConfigDir): when AKM_STASH_DIR points at a
+    // Isolation safety (mirrors getConfigDir): when AKM_BUNDLE_DIR points at a
     // transient path AND no explicit cache override is set, route cache writes
-    // into `${AKM_STASH_DIR}/.akm/cache` so that config backups, registry-index
+    // into `${AKM_BUNDLE_DIR}/.akm/cache` so that config backups, registry-index
     // cache, and other regenerable artifacts do not pollute the user's host
     // ~/.cache/akm directory.
-    const stashOverride = env.AKM_STASH_DIR?.trim();
+    const stashOverride = env.AKM_BUNDLE_DIR?.trim();
     if (stashOverride && isTransientStashPath(stashOverride)) {
         return path.join(stashOverride, ".akm", "cache");
     }
@@ -184,7 +184,7 @@ export function getDataDir(env = process.env, platform = process.platform) {
     // user's real $XDG_DATA_HOME / ~/.local/share/akm under any condition.
     // Any test that needs a data dir must point it at a mktemp-d directory
     // via XDG_DATA_HOME (or AKM_DATA_DIR). The previous carve-out that only
-    // fired when AKM_STASH_DIR was set was a loophole: tests calling
+    // fired when AKM_BUNDLE_DIR was set was a loophole: tests calling
     // openDatabase() or getDbPath() without overriding any env var silently
     // wrote into ~/.local/share/akm/index.db (observed: 4,183-row
     // registry-cache pollution). Item 5 of the 0.8.x critical-review plan.
@@ -218,16 +218,16 @@ export function getDbPath(env = process.env) {
 export function getIndexWriterLockPath() {
     return path.join(getDataDir(), "index.db.write.lock");
 }
-export function getWorkflowDbPath() {
-    return path.join(getDataDir(), "workflow.db");
+export function getMaintenanceBarrierPath() {
+    return path.join(getDataDir(), "maintenance.barrier.lock");
 }
 /** Path to the state.db file in $DATA. */
 export function getStateDbPathInDataDir() {
     return path.join(getDataDir(), "state.db");
 }
-/** Path for the task history directory in $DATA. */
-export function getTaskHistoryStateDir() {
-    return path.join(getDataDir(), "tasks", "history");
+/** Content-addressed scheduler runtime descriptors. */
+export function getTaskContextDir(env = process.env) {
+    return path.join(getDataDir(env), "tasks", "context");
 }
 /** Path to the akm.lock file in $DATA. */
 export function getLockfilePath() {
@@ -246,9 +246,6 @@ export function getRegistryCacheDir() {
 export function getRegistryIndexCacheDir() {
     return path.join(getCacheDir(), "registry-index");
 }
-export function getBinDir() {
-    return path.join(getCacheDir(), "bin");
-}
 // ── Scheduled-task runtime directories (logs + history) ──────────────────────
 export function getTaskLogDir() {
     return path.join(getCacheDir(), "tasks", "logs");
@@ -258,7 +255,7 @@ export function getTaskHistoryDir() {
 }
 // ── Default stash directory ──────────────────────────────────────────────────
 export function getDefaultStashDir(env = process.env) {
-    const override = env.AKM_STASH_DIR?.trim();
+    const override = env.AKM_BUNDLE_DIR?.trim();
     if (override)
         return override;
     if (IS_WINDOWS) {
@@ -269,7 +266,7 @@ export function getDefaultStashDir(env = process.env) {
     }
     const home = env.HOME?.trim();
     if (!home) {
-        throw new ConfigError("Unable to determine default stash directory. Set HOME.", "STASH_DIR_NOT_FOUND");
+        throw new ConfigError("Unable to determine default bundle directory. Set HOME.", "STASH_DIR_NOT_FOUND");
     }
     return path.join(home, "akm");
 }