akm-cli 0.9.0 → 0.9.1-beta.1

package/dist/core/abort-deadline.js

@@ -0,0 +1,28 @@
+// 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/.
+export function armAbortDeadline(controller, options) {
+    const { timeoutMs, reason } = options;
+    if (timeoutMs === null || timeoutMs === undefined) {
+        return { disarm: () => { }, timedOut: () => false };
+    }
+    const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
+    const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;
+    let fired = false;
+    let timer = setTimeoutImpl(() => {
+        timer = undefined;
+        fired = true;
+        controller.abort(new Error(reason));
+    }, timeoutMs);
+    // A pending deadline must never be the reason the process stays alive.
+    timer?.unref?.();
+    return {
+        disarm: () => {
+            if (timer !== undefined) {
+                clearTimeoutImpl(timer);
+                timer = undefined;
+            }
+        },
+        timedOut: () => fired,
+    };
+}

package/dist/core/adapter/adapters/agent-skills-adapter.js

@@ -27,10 +27,13 @@
  *   - `skill-description-too-long` — description must be 1-1024 chars.
  *   - `missing-skill-md` — a package dir with no SKILL.md (edge case; git cannot
  *     commit an empty dir, so it is covered by a directory-level check, not a
- *     fixture).
+ *     fixture). Implemented by {@link missingManifestDiagnostics}, which scans
+ *     the component root through `ValidateContext.list` — the change-set loop
+ *     cannot reach it, because a change is always a file and a manifest-less
+ *     package contributes no SKILL.md change (issue #774).
  *
- * Only `missing-skill-md` is coded elsewhere today; the two field codes are
- * APPROVED-BUT-NOT-YET-CODED and are implemented here. Base checks are NOT run:
+ * The two field codes are APPROVED-BUT-NOT-YET-CODED elsewhere and are
+ * implemented here. Base checks are NOT run:
  * a SKILL.md carries no `updated` field, so `missing-updated` would fire on
  * every conformant skill and contradict the lint golden.
  *
@@ -127,6 +130,63 @@ function skillFieldDiagnostics(relPath, dirName, data) {
     }
     return diagnostics;
 }
+/**
+ * How deep below a candidate package directory the manifest probe looks. Agent
+ * Skills packages sit at the component root (`<name>/SKILL.md`), occasionally
+ * one group level down (`<group>/<name>/SKILL.md`) — this bound keeps a deep
+ * resource tree (a package's `reference/`, `assets/`, …) from turning the lint
+ * sweep into a full recursive walk.
+ */
+const MAX_PACKAGE_PROBE_DEPTH = 3;
+/** True when `SKILL.md` exists at `dir` or anywhere within {@link MAX_PACKAGE_PROBE_DEPTH} below it. */
+async function subtreeHasManifest(dir, entries, ctx, depth) {
+    if (entries.includes(SKILL_MANIFEST))
+        return true;
+    if (depth >= MAX_PACKAGE_PROBE_DEPTH)
+        return false;
+    for (const entry of entries) {
+        const child = `${dir}/${entry}`;
+        // `list` on a FILE yields `[]` (the read throws and is swallowed), so an
+        // empty listing is the "not a directory worth descending" signal — no
+        // separate stat is available on ValidateContext, and none is needed.
+        const childEntries = await ctx.list(child);
+        if (childEntries.length === 0)
+            continue;
+        if (await subtreeHasManifest(child, childEntries, ctx, depth + 1))
+            return true;
+    }
+    return false;
+}
+/**
+ * The directory-level `missing-skill-md` check (issue #774).
+ *
+ * `validate` walks CHANGES, and a change is always a file — so a package
+ * directory carrying resources but no manifest contributes nothing the
+ * change-loop can see, and the check the spec (§4.5) and the lint golden's
+ * `missingSkillMd` edge case both name was unreachable. This scans the
+ * component root through {@link ValidateContext.list} instead, so the case is
+ * actually reported.
+ *
+ * Deliberately TOP-LEVEL only: a package's own resource dirs
+ * (`pdf-processing/reference/`) are part of the item, not candidate packages,
+ * and flagging them would turn every conformant bundle red. A top-level dir
+ * that holds a manifest ANYWHERE beneath it is a grouping dir, not a broken
+ * package, so it is left alone too.
+ */
+async function missingManifestDiagnostics(ctx) {
+    const diagnostics = [];
+    for (const name of await ctx.list(".")) {
+        if (name.startsWith("."))
+            continue; // .git, .github, … are not skill packages
+        const entries = await ctx.list(name);
+        if (entries.length === 0)
+            continue; // a root file (README.md), or an untrackable empty dir
+        if (await subtreeHasManifest(name, entries, ctx, 1))
+            continue;
+        diagnostics.push({ file: name, issue: "missing-skill-md", detail: `no SKILL.md in ${name}/`, fixed: false });
+    }
+    return diagnostics;
+}
 async function validate(_c, changes, ctx) {
     const diagnostics = [];
     const seenDirs = new Set();
@@ -142,10 +202,12 @@ async function validate(_c, changes, ctx) {
         if (seenDirs.has(pkg.conceptId))
             continue;
         seenDirs.add(pkg.conceptId);
-        // missing-skill-md is unreachable here (the change IS a SKILL.md); the empty-dir
-        // case is served by {@link directorySkillDiagnostics} for callers that scan dirs.
+        // `missing-skill-md` cannot fire here — the change IS a SKILL.md. The
+        // manifest-less package case is served by {@link missingManifestDiagnostics}
+        // below, which scans directories rather than changes.
         diagnostics.push(...skillFieldDiagnostics(toPosix(change.path), pkg.dirName, parseFrontmatter(raw).data));
     }
+    diagnostics.push(...(await missingManifestDiagnostics(ctx)));
     return diagnostics;
 }
 export const agentSkillsAdapter = {

package/dist/core/adapter/adapters/akm-adapter.js

@@ -80,8 +80,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
 import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, } from "../../../indexer/passes/metadata.js";
+import { parseTaskYaml, taskYamlParseDetail } from "../../../tasks/schema.js";
 import { assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { recognizeMatch } from "../recognize-match.js";
@@ -380,16 +380,19 @@ async function validate(c, changes, ctx) {
         // everything else → `parseFrontmatter`.
         let parsed;
         if (type === "task") {
-            let data = {};
-            try {
-                const doc = parseYaml(raw);
-                if (doc && typeof doc === "object" && !Array.isArray(doc))
-                    data = doc;
+            const task = parseTaskYaml(raw);
+            // A parse failure is its OWN finding: every task rule short-circuits on
+            // an empty mapping, so collapsing "unparseable" onto `{}` made a broken
+            // task file validate clean (issue #760). Mirrors the CLI sweep.
+            if (!task.ok) {
+                diagnostics.push({
+                    file: change.path,
+                    issue: "invalid-task-yaml",
+                    detail: taskYamlParseDetail(task.error),
+                    fixed: false,
+                });
             }
-            catch {
-                data = {};
-            }
-            parsed = { data, content: raw, frontmatter: null };
+            parsed = { data: task.data, content: raw, frontmatter: null };
         }
         else {
             const p = parseFrontmatter(raw);

package/dist/core/adapter/adapters/akm-lint.js

@@ -187,20 +187,29 @@ export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
     return diagnostics;
 }
 // ── skill directory check (SkillLinter.lintDirectory) ────────────────────────
+/** The akm-native skill placement dir — the default gate for {@link skillDirectoryDiagnostics}. */
+const AKM_SKILL_DIRS = new Set(["skills"]);
 /**
  * Reproduce `SkillLinter.lintDirectory` (`skill-linter.ts:31-45`) in the
- * change-set model: for a change under `skills/<name>/…`, emit `missing-skill-md`
- * when `skills/<name>/SKILL.md` is absent from the overlay. `seen` dedups so a
- * dir with multiple changed files reports once (matching the per-subdir call).
- * `file`/`detail` mirror the live check exactly (relDir + `no SKILL.md in <relDir>/`).
+ * change-set model: for a change under `<skillDir>/<name>/…`, emit
+ * `missing-skill-md` when `<skillDir>/<name>/SKILL.md` is absent from the
+ * overlay. `seen` dedups so a dir with multiple changed files reports once
+ * (matching the per-subdir call). `file`/`detail` mirror the live check exactly
+ * (relDir + `no SKILL.md in <relDir>/`).
+ *
+ * `skillDirs` defaults to the akm-native `skills/` placement dir. The tool-dir
+ * adapters pass their OWN accepted spellings, because opencode also accepts the
+ * singular `skill/` alias on read (`opencode-adapter.ts` LAYOUT) — with the
+ * gate hardcoded to `"skills"`, an identical manifest-less package went flagged
+ * under `skills/` and unflagged under `skill/` (issue #774).
  */
-export async function skillDirectoryDiagnostics(relPath, seen, ctx) {
+export async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs = AKM_SKILL_DIRS) {
     const segments = relPath
         .replace(/\\/g, "/")
         .split("/")
         .filter((s) => s.length > 0);
-    if (segments.length < 3 || segments[0] !== "skills")
-        return []; // must be skills/<name>/<file…>
+    if (segments.length < 3 || !skillDirs.has(segments[0]))
+        return []; // must be <skillDir>/<name>/<file…>
     const skillDir = `${segments[0]}/${segments[1]}`;
     if (seen.has(skillDir))
         return [];
@@ -300,51 +309,94 @@ export function matchWorkflowPlaceholder(body) {
 }
 /**
  * WorkflowLinter's `invalid-workflow-structure` check (`workflow-linter.ts:48-77`):
- * parse and compile through the unified workflow frontend, surfacing every
- * structural or semantic error and skipping the read-only `/.cache/`+`/registry/`
- * cached copies. Shared with the live linter;
- * `parsePath` is the path handed to `parseWorkflow` (the adapter passes the
- * change relPath, the CLI passes the absolute filePath — matching each caller's
- * legacy behavior). NEVER writes.
+ * the ERROR half of {@link workflowFrontendDiagnostics}, for callers that only
+ * ever surface fatal findings — the read-only adapter `validate` path and
+ * `akm migrate`'s stale-workflow probe. A caller that ALSO surfaces the
+ * advisories must call {@link workflowFrontendDiagnostics} once instead of
+ * pairing this with a second view. NEVER writes.
  */
 export function workflowStructureDiagnostics(relPath, raw, parsePath) {
+    return workflowFrontendDiagnostics(relPath, raw, parsePath).errors;
+}
+/**
+ * The `Diagnostic.line` fragment for a line-anchored workflow finding. Every
+ * `WorkflowError` carries a 1-indexed `line`; this used to be DROPPED here, so
+ * an author linting a 300-line workflow got a message with no location while
+ * the same error rendered as `path:line — message` on the `workflow create`
+ * path. Spread (`...lineOf(err)`) rather than assigned, so a nonsense line
+ * never materializes the optional key on a whole-file finding.
+ */
+function lineOf(err) {
+    return typeof err.line === "number" && Number.isFinite(err.line) && err.line > 0 ? { line: err.line } : {};
+}
+/**
+ * ONE parse+compile of a workflow through the unified frontend, returning both
+ * halves of what it produces: fatal `invalid-workflow-structure` findings, and
+ * `compileWorkflowPlan`'s non-fatal `workflow-warning` advisories (a step with
+ * no `output:` schema, a reference to an undeclared param). The read-only
+ * `/.cache/` + `/registry/` cached copies are skipped, and nothing is written.
+ *
+ * `parsePath` is the path handed to `parseWorkflow` (the adapter passes the
+ * change relPath, the CLI passes the absolute filePath — matching each
+ * caller's legacy behavior).
+ *
+ * A caller that surfaces BOTH halves must call this once and route the result
+ * itself. The frontend is expensive — instruction bodies reach
+ * `WORKFLOW_MAX_INSTRUCTION_BYTES` — so asking for each half through its own
+ * view parses and compiles every workflow in the stash twice.
+ */
+export function workflowFrontendDiagnostics(relPath, raw, parsePath) {
+    const none = { errors: [], warnings: [] };
     if (parsePath.includes("/.cache/") || parsePath.includes("/registry/"))
-        return [];
-    const diagnostics = [];
+        return none;
+    const errors = [];
+    const warnings = [];
     try {
         const result = parseWorkflow(raw, { path: parsePath });
         if (!result.ok) {
             for (const err of result.errors ?? []) {
-                diagnostics.push({
+                errors.push({
                     file: relPath,
                     issue: "invalid-workflow-structure",
                     detail: err.message ?? String(err),
                     fixed: false,
+                    ...lineOf(err),
                 });
             }
-            return diagnostics;
+            return { errors, warnings };
         }
         const compiled = compileWorkflowPlan(result.document, path.basename(parsePath, path.extname(parsePath)));
         if (!compiled.ok) {
             for (const err of compiled.errors) {
-                diagnostics.push({
+                errors.push({
                     file: relPath,
                     issue: "invalid-workflow-structure",
                     detail: err.message,
                     fixed: false,
+                    ...lineOf(err),
                 });
             }
+            return { errors, warnings };
+        }
+        for (const warning of compiled.warnings) {
+            warnings.push({
+                file: relPath,
+                issue: "workflow-warning",
+                detail: warning.message,
+                fixed: false,
+                ...lineOf(warning),
+            });
         }
     }
     catch (e) {
-        diagnostics.push({
+        errors.push({
             file: relPath,
             issue: "invalid-workflow-structure",
             detail: `workflow parser error: ${e instanceof Error ? e.message : String(e)}`,
             fixed: false,
         });
     }
-    return diagnostics;
+    return { errors, warnings };
 }
 /**
  * WorkflowLinter extra checks (`workflow-linter.ts:22-79`), READ-ONLY:

package/dist/core/adapter/adapters/akm-task-adapter.js

@@ -10,6 +10,10 @@
  * invalid task (e.g. two targets) is still RECOGNIZED; the `invalid-task-yaml`
  * violation surfaces only in `validate`.
  *
+ * `.yaml` is the one extension `validate` inspects but `recognize` refuses: it
+ * is not a task spelling (nothing indexes or schedules it), so it is reported
+ * as `invalid-task-yaml` rather than silently skipped (issue #760).
+ *
  * ── validate (spec §6 task validation column) ──
  *
  * A task must declare `version: 2`, a `schedule`, and EXACTLY ONE target
@@ -26,13 +30,12 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { taskFieldProblems } from "../../../tasks/schema.js";
+import { parseTaskYaml, TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskFieldProblems, taskYamlParseDetail, } from "../../../tasks/schema.js";
 import { hashContent } from "./shared.js";
 /** A native task bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
 /** The task YAML extension (spec §6 task row). */
-const TASK_EXT = ".yml";
+const TASK_EXT = TASK_EXTENSION;
 /** The mutually-exclusive task target keys (exactly one required). */
 const TARGET_KEYS = ["prompt", "workflow", "command"];
 /** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
@@ -59,18 +62,6 @@ function recognize(c, file) {
         content: raw.length > MAX_CONTENT_CHARS ? raw.slice(0, MAX_CONTENT_CHARS) : raw,
     };
 }
-/** Parse a task YAML into a plain record (tolerant: malformed / non-mapping → {}). */
-function parseTaskYaml(raw) {
-    try {
-        const doc = parseYaml(raw);
-        if (doc && typeof doc === "object" && !Array.isArray(doc))
-            return doc;
-    }
-    catch {
-        // malformed YAML
-    }
-    return {};
-}
 /**
  * The native `invalid-task-yaml` check: the shared field rules
  * ({@link taskFieldProblems} — see its doc for the lint-vs-parser
@@ -99,16 +90,46 @@ async function validate(_c, changes, ctx) {
         const raw = change.after ?? (await ctx.readFile(change.path));
         if (typeof raw !== "string")
             continue;
-        if (path.extname(change.path).toLowerCase() !== TASK_EXT)
+        const ext = path.extname(change.path).toLowerCase();
+        // `.yaml` is NOT a task extension — the file never indexes and never runs.
+        // It is validated here purely so the near miss is REPORTED rather than
+        // skipped the way every other extension is (issue #760).
+        if (ext !== TASK_EXT && ext !== TASK_NEAR_MISS_EXTENSION)
             continue;
-        diagnostics.push(...taskDiagnostics(toPosix(change.path), parseTaskYaml(raw)));
+        const relPath = toPosix(change.path);
+        if (ext === TASK_NEAR_MISS_EXTENSION) {
+            diagnostics.push({
+                file: relPath,
+                issue: "invalid-task-yaml",
+                detail: taskExtensionDetail(relPath),
+                fixed: false,
+            });
+        }
+        const parsed = parseTaskYaml(raw);
+        if (!parsed.ok) {
+            // Distinguish "unparseable" from "empty": `taskDiagnostics` returns []
+            // for an empty mapping, so collapsing a parse failure onto `{}` made a
+            // broken task file lint clean.
+            diagnostics.push({
+                file: relPath,
+                issue: "invalid-task-yaml",
+                detail: taskYamlParseDetail(parsed.error),
+                fixed: false,
+            });
+            continue;
+        }
+        diagnostics.push(...taskDiagnostics(relPath, parsed.data));
     }
     return diagnostics;
 }
 export const akmTaskAdapter = {
     id: "akm-task",
     version: "0.9.0",
-    extensions: [TASK_EXT],
+    // `.yaml` is listed as a COLLECTION hint only — `recognize` still gates on
+    // `.yml`, so a `.yaml` file is never indexed as a task. Listing it is what
+    // routes the near-miss file into `validate`, where it is reported instead of
+    // silently skipped (issue #760).
+    extensions: [TASK_EXT, TASK_NEAR_MISS_EXTENSION],
     recognize,
     validate,
     /** A task places to `<conceptId>.yml`; an already-suffixed conceptId is idempotent. */
@@ -143,7 +164,7 @@ export const akmTaskAdapter = {
             catch {
                 continue;
             }
-            const data = parseTaskYaml(raw);
+            const { data } = parseTaskYaml(raw);
             if (typeof data.schedule === "string" && data.schedule.trim() !== "")
                 return true;
         }

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

@@ -185,9 +185,11 @@ export async function validateToolDir(layout, c, changes, ctx) {
             continue;
         const relPath = toPosix(change.path);
         // The one coded skill check (missing-skill-md) fires on ANY change under a
-        // `skills/<name>/…` package (self-gated + deduped), even a bundled resource —
-        // mirrors the akm adapter's per-change SkillLinter.lintDirectory pass.
-        diagnostics.push(...(await skillDirectoryDiagnostics(relPath, seenSkillDirs, ctx)));
+        // `<skillDir>/<name>/…` package (self-gated + deduped), even a bundled
+        // resource — mirrors the akm adapter's per-change SkillLinter.lintDirectory
+        // pass. `layout.skillDirs` is passed so opencode's singular `skill/` alias
+        // is checked identically to `skills/` (issue #774).
+        diagnostics.push(...(await skillDirectoryDiagnostics(relPath, seenSkillDirs, ctx, layout.skillDirs)));
         const cls = classify(change.path, layout);
         if (cls === null)
             continue;

package/dist/core/asset/frontmatter.js

@@ -10,6 +10,7 @@
  */
 import fs from "node:fs";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { recordWrittenPath } from "../write-provenance.js";
 import { assembleAsset, serializeFrontmatter } from "./asset-serialize.js";
 /**
  * Parse YAML frontmatter from a Markdown (or similar) string.
@@ -143,6 +144,9 @@ export function mutateFrontmatter(filePath, mutator) {
         ? `---\n${serializeFrontmatter(nextFrontmatter)}\n---\n${parsed.content}`
         : assembleAsset(nextFrontmatter, parsed.content);
     fs.writeFileSync(filePath, next, "utf8");
+    // #652: in-place frontmatter stamps (belief state, contradiction markers,
+    // salience) are real asset mutations — journal them for the run's sync.
+    recordWrittenPath(filePath);
     return true;
 }
 export function parseFrontmatterBlock(raw) {

package/dist/core/common.js

@@ -292,13 +292,49 @@ export function hasErrnoCode(error, code) {
         return false;
     return error.code === code;
 }
+/**
+ * True when `value` is a RELATIVE path that cannot leave its base directory:
+ * no absolute form (POSIX `/`, Windows `\` or a `C:` drive prefix), no `~`
+ * home expansion, and no `..` segment under either separator.
+ *
+ * This is the SYNTACTIC half of containment — cheap, string-only, usable at
+ * authoring time before any directory exists. It is deliberately paired with
+ * (never a substitute for) {@link isWithin}, which resolves symlinks against a
+ * real base at use time. Workflow `exec` units run both: the parser and the
+ * frozen-plan decoder reject uncontained spellings, and the executor re-checks
+ * the resolved path before spawning.
+ */
+export function isContainedRelativePath(value) {
+    if (value === "" || value.startsWith("/") || value.startsWith("\\") || value.startsWith("~"))
+        return false;
+    if (/^[A-Za-z]:/.test(value))
+        return false;
+    return !value.split(/[/\\]+/).includes("..");
+}
 export function isWithin(candidate, root) {
-    const resolvedRoot = safeRealpath(root);
-    const resolvedCandidate = safeRealpath(candidate);
-    const normalizedRoot = normalizeFsPathForComparison(resolvedRoot);
-    const normalizedCandidate = normalizeFsPathForComparison(resolvedCandidate);
-    const rel = path.relative(normalizedRoot, normalizedCandidate);
-    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    return isContainedResolvedPath(safeRealpath(candidate), safeRealpath(root));
+}
+/**
+ * {@link isWithin} for callers that must not block the event loop (e.g. the
+ * workflow exec dispatch path, which runs once per fan-out unit). Same
+ * comparison, same normalization, same nearest-existing-ancestor fallback —
+ * only the realpath syscalls are awaited.
+ */
+export async function isWithinAsync(candidate, root) {
+    return isContainedResolvedPath(await safeRealpathAsync(candidate), await safeRealpathAsync(root));
+}
+/** The containment comparison shared by {@link isWithin} and {@link isWithinAsync}. */
+function isContainedResolvedPath(resolvedCandidate, resolvedRoot) {
+    const rel = path.relative(normalizeFsPathForComparison(resolvedRoot), normalizeFsPathForComparison(resolvedCandidate));
+    if (rel === "")
+        return true;
+    if (path.isAbsolute(rel))
+        return false;
+    // Compare the first SEGMENT, not a string prefix: `..data` and `...v2` are
+    // legal directory names, and only a leading `..` segment means the candidate
+    // climbed out of the root. Both separators, because `path.relative` answers
+    // in the host's spelling while callers may hold either.
+    return rel.split(/[/\\]+/)[0] !== "..";
 }
 /**
  * Resolve symlinks on `p`, walking up to the closest existing ancestor when
@@ -335,6 +371,30 @@ export function safeRealpath(p) {
         }
     }
 }
+/** {@link safeRealpath}'s async twin — awaited syscalls, identical walk-up. */
+export async function safeRealpathAsync(p) {
+    const resolved = path.resolve(p);
+    try {
+        return await fs.promises.realpath(resolved);
+    }
+    catch {
+        const suffix = [];
+        let current = resolved;
+        for (;;) {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return resolved;
+            suffix.unshift(path.basename(current));
+            current = parent;
+            try {
+                return path.join(await fs.promises.realpath(current), ...suffix);
+            }
+            catch {
+                // parent also doesn't exist; keep walking up
+            }
+        }
+    }
+}
 function normalizeFsPathForComparison(value) {
     return process.platform === "win32" ? value.toLowerCase() : value;
 }

package/dist/core/concurrent.js

@@ -1,6 +1,32 @@
 // 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/.
+/**
+ * Serialize `fn` behind every task previously enqueued under `key`: an
+ * in-process keyed promise chain (Bun is single-threaded, so this is a
+ * sufficient — and free — admission control for per-key mutual exclusion).
+ *
+ * `chains` is the caller's own module-state map, so independent subsystems
+ * (the unit-writer's per-database write queue, the worktree module's per-repo
+ * git lock) never share chains. A failed task rejects its OWN caller but
+ * never wedges the chain, and a drained tail deletes its map entry so a
+ * long-lived process does not retain one settled promise per key it ever
+ * touched.
+ */
+export function serializeByKey(chains, key, fn) {
+    const tail = chains.get(key) ?? Promise.resolve();
+    const run = tail.then(() => fn());
+    // Keep the chain alive regardless of individual outcomes.
+    const settled = run.then(() => undefined, () => undefined);
+    chains.set(key, settled);
+    // If another task was enqueued in the meantime the map now holds ITS tail,
+    // and this check leaves it alone.
+    void settled.then(() => {
+        if (chains.get(key) === settled)
+            chains.delete(key);
+    });
+    return run;
+}
 /**
  * Maps over items concurrently with a pool size limit.
  * Uses Promise.allSettled semantics — one failure does not cancel others.
@@ -11,6 +37,12 @@
  * preempt those too). Unclaimed items stay `undefined` in the result,
  * indistinguishable from individual failures by design: callers already
  * treat `undefined` as "no result".
+ *
+ * A thrown `fn` is SWALLOWED (its slot stays `undefined`) — a caller that
+ * must report failure detail, or distinguish "threw" from "never claimed",
+ * catches inside `fn` and returns an explicit outcome value instead. This is
+ * the OPPOSITE of {@link serializeByKey} above, whose failures reject their
+ * own caller.
  */
 export async function concurrentMap(items, fn, concurrency = 1, opts) {
     const results = new Array(items.length).fill(undefined);

package/dist/core/config/schema/workflow.js

@@ -19,10 +19,21 @@ import { engineName, positiveInt } from "./primitives.js";
  *     `[1, WORKFLOW_MAX_CONCURRENCY_CEILING]` (64). Values above the ceiling
  *     are clamped, not rejected, so a config shared across machines with wildly
  *     different core counts never hard-fails validation.
+ *
+ * `defaultMapConcurrency` is the width a `map` step freezes when it declares no
+ * `concurrency:` of its own:
+ *   - UNSET  → `DEFAULT_MAP_CONCURRENCY` (4) from
+ *     `src/workflows/concurrency-policy.ts`.
+ *   - SET    → the explicit positive integer, CLAMPED to `[1, 64]`. Setting it
+ *     to `1` restores the pre-0.9.1 serial-by-default fan-out for every
+ *     workflow on this install. It is a floor for authoring only: it never
+ *     raises a step above `maxConcurrency`, the engine's concurrency, or the
+ *     host CPU cap, and it never overrides an authored `map.concurrency`.
  */
 export const WorkflowConfigSchema = z
     .object({
     maxConcurrency: positiveInt.optional(),
+    defaultMapConcurrency: positiveInt.optional(),
     /** Named LLM or agent engine frozen into every criteria-bearing gate. */
     judgeEngine: engineName.optional(),
 })

package/dist/core/errors.js

@@ -9,6 +9,7 @@ const CONFIG_HINTS = {
     STASH_DIR_NOT_FOUND: "Run `akm setup` to create and configure your bundle, or configure a defaultBundle path.",
     STASH_DIR_NOT_A_DIRECTORY: "The configured default bundle path exists but isn't a directory. Update it to point at a folder.",
     STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update the default bundle path.",
+    DATA_DIR_UNREADABLE: "The data directory is not readable by the user running akm. Check its owner and mode, or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns.",
     EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
     LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
     TEST_ISOLATION_MISSING: "Under bun test, when AKM_BUNDLE_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
@@ -131,3 +132,27 @@ export function rethrowIfTestIsolationError(err) {
         throw err;
     }
 }
+/**
+ * Unreadable-data-dir guard helper — the #791 sibling of the test-isolation
+ * pair above, and it exists for the same reason.
+ *
+ * `DATA_DIR_UNREADABLE` says "this path is there and I am not allowed to read
+ * it". It is raised by `assertIndexPathReadable` and friends precisely so a
+ * permission fault stops being indistinguishable from "nothing indexed yet".
+ * That distinction is destroyed again the moment a best-effort `catch` around
+ * the open collapses it into the same `null`/`[]`/`0` the absent case returns —
+ * which is how `akm search` came to answer "No search index available. Run
+ * 'akm index'" at exit 0 for a populated index sitting right there on disk.
+ *
+ * Call `rethrowIfDataDirUnreadable(err)` from any catch block that returns a
+ * fallback value after touching a data-dir path. Absent stays absent; a fault
+ * the operator has to fix keeps travelling.
+ */
+export function isDataDirUnreadableError(err) {
+    return err instanceof ConfigError && err.code === "DATA_DIR_UNREADABLE";
+}
+export function rethrowIfDataDirUnreadable(err) {
+    if (isDataDirUnreadableError(err)) {
+        throw err;
+    }
+}