akm-cli 0.9.0 → 0.9.1-beta.1

package/dist/commands/lint/index.js

@@ -3,8 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { factDiagnostics, matchWorkflowPlaceholder, memoryOrphanStubApplies, nameOrTypeDiagnostics, ORPHANED_STUB_DETAIL, taskDiagnostics, workflowStructureDiagnostics, } from "../../core/adapter/adapters/akm-lint.js";
+import { factDiagnostics, matchWorkflowPlaceholder, memoryOrphanStubApplies, nameOrTypeDiagnostics, ORPHANED_STUB_DETAIL, taskDiagnostics, workflowFrontendDiagnostics, } from "../../core/adapter/adapters/akm-lint.js";
 import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { adapterForId } from "../../core/adapter/registry.js";
 import { createValidateContext } from "../../core/adapter/validate-context.js";
@@ -15,9 +14,12 @@ import { deriveBundleIds } from "../../core/bundle-id.js";
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { parseTaskYaml, TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskYamlParseDetail, } from "../../tasks/schema.js";
 import { runBaseChecks } from "./base-linter.js";
 import { checkEnvForDangerousKeys } from "./env-key-rules.js";
+import { isAdvisoryLintIssue } from "./types.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 const STASH_SUBDIRS = [
     "agents",
@@ -31,21 +33,34 @@ const STASH_SUBDIRS = [
     "facts",
 ];
 // ── Helpers ───────────────────────────────────────────────────────────────────
-function collectYamlFiles(dir) {
+/**
+ * Every task-shaped file under `tasks/`: the recognized `.yml` spelling AND the
+ * `.yaml` near-miss. A `.yaml` file is not a runnable task — it is invisible to
+ * the indexer's `tasks` matcher — but collecting it here is what lets the sweep
+ * SAY so (`invalid-task-yaml`, see {@link taskExtensionDetail}) instead of
+ * walking past it and reporting a clean scan (issue #760).
+ */
+function collectTaskFiles(dir) {
     if (!fs.existsSync(dir))
         return [];
     const results = [];
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
         const full = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            results.push(...collectYamlFiles(full));
+            results.push(...collectTaskFiles(full));
         }
-        else if (entry.isFile() && entry.name.endsWith(".yml")) {
+        else if (entry.isFile() && (isTaskFileName(entry.name) || isNearMissTaskFileName(entry.name))) {
             results.push(full);
         }
     }
     return results;
 }
+function isTaskFileName(fileName) {
+    return fileName.toLowerCase().endsWith(TASK_EXTENSION);
+}
+function isNearMissTaskFileName(fileName) {
+    return fileName.toLowerCase().endsWith(TASK_NEAR_MISS_EXTENSION);
+}
 function collectMarkdownFiles(dir, caseInsensitive = false) {
     if (!fs.existsSync(dir))
         return [];
@@ -141,18 +156,32 @@ const KNOWN_ADAPTER_ISSUE_TYPES = new Set([
     "missing-type",
     "missing-name-or-type",
     "missing-skill-md",
+    // The `akm-task` adapter's own code. Now reachable from `akm lint` for a
+    // malformed or misnamed task file (issue #760); without it here, a genuine
+    // task finding would arrive folded onto `adapter-diagnostic`.
+    "invalid-task-yaml",
     "dangerous-env-key",
     "uncited-raw",
     "missing-description",
     "broken-xref",
     "broken-source",
+    "workflow-warning",
 ]);
 /** Map one adapter {@link Diagnostic} onto a {@link LintIssue} — see `types.ts`'s `"adapter-diagnostic"` doc comment for the open→closed reconciliation. */
 export function diagnosticToLintIssue(diag) {
+    // `line` is optional on both shapes: carry it only when the adapter set one,
+    // so whole-file findings keep their exact existing serialization.
+    const location = typeof diag.line === "number" ? { line: diag.line } : {};
     if (KNOWN_ADAPTER_ISSUE_TYPES.has(diag.issue)) {
-        return { file: diag.file, issue: diag.issue, detail: diag.detail, fixed: diag.fixed };
+        return { file: diag.file, issue: diag.issue, detail: diag.detail, fixed: diag.fixed, ...location };
     }
-    return { file: diag.file, issue: "adapter-diagnostic", detail: `[${diag.issue}] ${diag.detail}`, fixed: diag.fixed };
+    return {
+        file: diag.file,
+        issue: "adapter-diagnostic",
+        detail: `[${diag.issue}] ${diag.detail}`,
+        fixed: diag.fixed,
+        ...location,
+    };
 }
 /**
  * Lint a bundle through its OWN adapter's `validate()` (spec §12.1): the
@@ -169,6 +198,17 @@ async function lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cf
     // always applied to a bundle it can't otherwise place.
     if (!adapter)
         return lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options);
+    // `--type` names an AKM stash subdir; every other adapter has its own type
+    // vocabulary and `validate()` sees the whole bundle regardless. That is not a
+    // correctness problem (full-bundle validation is a superset of the requested
+    // scope), but a user narrowing a run deserves to hear the flag did nothing
+    // rather than infer it from identical output (issue #762). Warn, don't throw:
+    // a hard error would break scripts passing one `--type` across mixed-adapter
+    // bundle sets.
+    if (options.typeFilter) {
+        warn(`Warning: lint --type "${options.typeFilter}" is not supported for the "${adapterId}" adapter — ` +
+            "type scoping applies to akm bundles only; the whole bundle was validated.");
+    }
     const files = collectAdapterFiles(stashRoot, adapter.extensions);
     const changes = files.map((filePath) => ({
         path: path.relative(stashRoot, filePath).replace(/\\/g, "/"),
@@ -179,7 +219,13 @@ async function lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cf
     const componentId = sourceIndex >= 0 ? ids[sourceIndex] : stashRoot;
     const ctx = createValidateContext({ root: stashRoot, extraRoots: extraStashRoots });
     const diagnostics = await adapter.validate({ id: componentId, adapter: adapterId, root: stashRoot, writable: true }, changes, ctx);
-    const flagged = diagnostics.map(diagnosticToLintIssue);
+    const mapped = diagnostics.map(diagnosticToLintIssue);
+    // Advisory diagnostics travel in their own channel — never `flagged`, so a
+    // `--fail-on-flagged` gate is not tripped by a non-fatal warning. Classified
+    // by the shared `ADVISORY_LINT_ISSUES` set rather than a code spelled out
+    // here, so this and the sweep below can never disagree about a code.
+    const warnings = mapped.filter(isAdvisoryLintIssue);
+    const flagged = mapped.filter((issue) => !isAdvisoryLintIssue(issue));
     // The cross-bundle env dangerous-key sweep (see `runEnvDangerousKeyPass`'s
     // doc comment) ran for every non-akm adapter via the STASH_SUBDIRS
     // fallthrough this dispatch replaces — EXCEPT `okf`, which the old code
@@ -199,7 +245,13 @@ async function lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cf
             flagged.push(issue);
         }
     }
-    return { ok: true, fixed: [], flagged, summary: { fixed: 0, flagged: flagged.length } };
+    return {
+        ok: true,
+        fixed: [],
+        flagged,
+        warnings,
+        summary: { fixed: 0, flagged: flagged.length, warnings: warnings.length },
+    };
 }
 function lintIssueDedupeKey(issue) {
     return `${issue.file} ${issue.issue} ${issue.detail}`;
@@ -259,6 +311,29 @@ function runEnvDangerousKeyPass(stashRoot, extraStashRoots, sources, cfg) {
     }
     return flagged;
 }
+/**
+ * Refuse `--fix` against a bundle the config marks `writable: false`, BEFORE
+ * the sweep touches a single file (issue #761).
+ *
+ * Every other mutating command routes through `core/write-source.ts`'s
+ * `ensureWritable`/`resolveWritable` pair; `akm lint --fix` writes and deletes
+ * directly and never consulted the flag, so it happily rewrote frontmatter in a
+ * bundle explicitly configured read-only. `SearchSource.writable` is already the
+ * EFFECTIVE policy (`resolveWritable` applied — see `resolveSourceEntries`), so
+ * this reads the same answer the write path would, without a second resolver.
+ *
+ * A root that is not a configured source at all (an ad-hoc `--dir`) carries no
+ * policy and stays fixable, exactly as today.
+ */
+function assertFixTargetWritable(stashRoot, sources) {
+    const target = sources.find((source) => path.resolve(source.path) === path.resolve(stashRoot));
+    if (target?.writable !== false)
+        return;
+    // Same error kind and code `write-source.ts#ensureWritable` raises for the
+    // identical refusal, so a scripted caller classifies both the same way.
+    throw new UsageError(`lint --fix: bundle "${stashRoot}" is configured \`writable: false\`; refusing to modify it. ` +
+        "Run `akm lint` without --fix to report findings, or set `writable: true` on the bundle.", "INVALID_FLAG_VALUE");
+}
 /** True when the issue represents a file deletion that was successfully applied. */
 function isFileDeletion(issue) {
     return issue.fixed === true && (issue.issue === "orphaned-stub" || issue.issue === "placeholder-stub");
@@ -308,46 +383,53 @@ function appendMemoryStubIssue(ctx, issues) {
     }
     issues.push({ file: ctx.relPath, issue: "orphaned-stub", detail: ORPHANED_STUB_DETAIL, fixed: false });
 }
-/** WorkflowLinter's `placeholder-stub` (WITH `--fix` delete) + `invalid-workflow-structure` (workflow-linter.ts:22-79). */
-function appendWorkflowIssues(ctx, issues) {
+/**
+ * WorkflowLinter's `placeholder-stub` check WITH its `--fix` delete
+ * (workflow-linter.ts:22-79). Its sibling `invalid-workflow-structure` check is
+ * deliberately NOT here: parse+compile is a single pass shared with the
+ * advisory channel, so {@link lintAkmSweep} runs it once per file and routes
+ * both halves.
+ */
+function appendWorkflowStubIssue(ctx, issues) {
     const placeholder = matchWorkflowPlaceholder(ctx.body);
-    if (placeholder) {
-        if (ctx.fix) {
-            try {
-                fs.unlinkSync(ctx.filePath);
-                issues.push({
-                    file: ctx.relPath,
-                    issue: "placeholder-stub",
-                    detail: `deleted: found "${placeholder}"`,
-                    fixed: true,
-                });
-            }
-            catch (e) {
-                issues.push({
-                    file: ctx.relPath,
-                    issue: "placeholder-stub",
-                    detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
-                    fixed: "failed",
-                });
-            }
-            return; // WorkflowLinter returns before the structure check once a stub is fixed.
+    if (!placeholder)
+        return;
+    if (ctx.fix) {
+        try {
+            fs.unlinkSync(ctx.filePath);
+            issues.push({
+                file: ctx.relPath,
+                issue: "placeholder-stub",
+                detail: `deleted: found "${placeholder}"`,
+                fixed: true,
+            });
         }
-        issues.push({
-            file: ctx.relPath,
-            issue: "placeholder-stub",
-            detail: `placeholder text: "${placeholder}"`,
-            fixed: false,
-        });
+        catch (e) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "placeholder-stub",
+                detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
+                fixed: "failed",
+            });
+        }
+        return;
     }
-    // NB: the CLI passes the ABSOLUTE filePath to parseWorkflow (matching the old
-    // WorkflowLinter), whereas the adapter passes the change relPath.
-    issues.push(...workflowStructureDiagnostics(ctx.relPath, ctx.raw, ctx.filePath));
+    issues.push({
+        file: ctx.relPath,
+        issue: "placeholder-stub",
+        detail: `placeholder text: "${placeholder}"`,
+        fixed: false,
+    });
 }
 /**
  * Lint ONE asset file: the shared base checks, then the winning stash subdir's
  * per-`type` extra rules. Replaces `getLinterForType(subdir).lint(ctx)`.
  * `--fix` mutations (frontmatter rewrites inside `runBaseChecks`; stub deletes
  * here) are applied when `ctx.fix` is set.
+ *
+ * The workflow parse/compile frontend is NOT one of these rules — it is one
+ * pass feeding two channels, so {@link lintAkmSweep} owns it (see
+ * {@link appendWorkflowStubIssue}).
  */
 export function lintAssetFile(ctx, subdir) {
     const issues = runBaseChecks(ctx);
@@ -368,7 +450,7 @@ export function lintAssetFile(ctx, subdir) {
             appendMemoryStubIssue(ctx, issues);
             break;
         case "workflows":
-            appendWorkflowIssues(ctx, issues);
+            appendWorkflowStubIssue(ctx, issues);
             break;
         // knowledge / lessons / skills: base checks only (skill directory-level
         // `missing-skill-md` runs separately, per-subdir, in the sweep loop).
@@ -387,14 +469,17 @@ export function lintAssetFile(ctx, subdir) {
  */
 function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
     const fix = options.fix === true;
+    if (fix)
+        assertFixTargetWritable(stashRoot, sources);
     const fixed = [];
     const flagged = [];
+    const warnings = [];
     const dirsToScan = options.typeFilter ? STASH_SUBDIRS.filter((d) => d === options.typeFilter) : STASH_SUBDIRS;
     for (const subdir of dirsToScan) {
         const dirPath = path.join(stashRoot, subdir);
         // Tasks are .yml files; everything else (including workflows, one
         // markdown format now) is .md
-        const files = subdir === "tasks" ? collectYamlFiles(dirPath) : collectMarkdownFiles(dirPath, true);
+        const files = subdir === "tasks" ? collectTaskFiles(dirPath) : collectMarkdownFiles(dirPath, true);
         const assetFiles = subdir === "workflows" ? files.filter((file) => path.basename(file).toLowerCase() !== "readme.md") : files;
         // Directory-level check: skills require a SKILL.md entry point (was
         // SkillLinter.lintDirectory). Run once per direct subdirectory before the
@@ -430,15 +515,32 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             let data;
             let body;
             let frontmatter;
+            // File-identity findings the per-type rules cannot produce: they describe
+            // the FILE (its extension, whether it parsed at all), not its fields.
+            const fileIssues = [];
             if (subdir === "tasks") {
                 // Task files are pure YAML — parseFrontmatter returns empty data for them.
-                try {
-                    const parsed = parseYaml(raw);
-                    data =
-                        parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+                const parsed = parseTaskYaml(raw);
+                data = parsed.data;
+                if (!parsed.ok) {
+                    // A parse failure used to fall through as `data = {}`, and every task
+                    // rule short-circuits on an empty mapping — so an unparseable task
+                    // file reported a CLEAN scan. Report the parse failure itself
+                    // (issue #760).
+                    fileIssues.push({
+                        file: relPath,
+                        issue: "invalid-task-yaml",
+                        detail: taskYamlParseDetail(parsed.error),
+                        fixed: false,
+                    });
                 }
-                catch {
-                    data = {};
+                if (isNearMissTaskFileName(relPath)) {
+                    fileIssues.push({
+                        file: relPath,
+                        issue: "invalid-task-yaml",
+                        detail: taskExtensionDetail(relPath),
+                        fixed: false,
+                    });
                 }
                 body = raw;
                 frontmatter = null;
@@ -446,13 +548,40 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             else {
                 ({ data, content: body, frontmatter } = parseFrontmatter(raw));
             }
-            const issues = lintAssetFile({ filePath, relPath, raw, data, body, frontmatter, fix, stashRoot, extraStashRoots }, subdir);
+            // One file's checks — including its `--fix` mutations — must never abort
+            // the sweep: an uncaught throw here left the caller with an exception and
+            // no record of which earlier files had ALREADY been rewritten on disk
+            // (issue #761). A failure is reported per-file, in-band, and the sweep
+            // continues so the rest of the bundle is still linted.
+            let issues;
+            try {
+                issues = [
+                    ...fileIssues,
+                    ...lintAssetFile({ filePath, relPath, raw, data, body, frontmatter, fix, stashRoot, extraStashRoots }, subdir),
+                ];
+            }
+            catch (e) {
+                flagged.push(...fileIssues, {
+                    file: relPath,
+                    issue: "lint-failed",
+                    detail: `lint ${fix ? "--fix " : ""}failed for this file: ${e instanceof Error ? e.message : String(e)}`,
+                    fixed: fix ? "failed" : false,
+                });
+                continue;
+            }
             let fileDeleted = false;
             for (const issue of issues) {
                 if (isFileDeletion(issue)) {
                     fileDeleted = true;
                     fixed.push(issue);
                 }
+                else if (isAdvisoryLintIssue(issue)) {
+                    // `lintAssetFile` returns errors only today, so this branch is
+                    // reached by no current producer — it is here so that an advisory
+                    // added to a per-type check later cannot silently become a
+                    // `--fail-on-flagged` failure, the way the unclassified default does.
+                    warnings.push(issue);
+                }
                 else if (issue.fixed === true) {
                     fixed.push(issue);
                 }
@@ -463,6 +592,26 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             }
             if (fileDeleted)
                 continue; // file is gone — skip any remaining checks
+            // The workflow frontend is ONE parse+compile whose output feeds BOTH
+            // channels, so it runs here — once per file — rather than inside
+            // `lintAssetFile`, which is an errors-only surface (pinned by the lint
+            // golden). Which channel a finding lands in is decided by
+            // `ADVISORY_LINT_ISSUES`, never by which half of the pass produced it, so
+            // a future compile-warning kind carrying a fatal code cannot slip past
+            // `--fail-on-flagged`.
+            // NB: the CLI passes the ABSOLUTE filePath to parseWorkflow (matching the
+            // old WorkflowLinter), whereas the adapter passes the change relPath.
+            if (subdir === "workflows") {
+                const frontend = workflowFrontendDiagnostics(relPath, raw, filePath);
+                for (const finding of [...frontend.errors, ...frontend.warnings]) {
+                    if (isAdvisoryLintIssue(finding)) {
+                        warnings.push(finding);
+                    }
+                    else {
+                        flagged.push(finding);
+                    }
+                }
+            }
         }
     }
     // ── Env dangerous-key pass ─────────────────────────────────────────────────
@@ -483,7 +632,8 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
         ok: true,
         fixed,
         flagged,
-        summary: { fixed: fixed.length, flagged: flagged.length },
+        warnings,
+        summary: { fixed: fixed.length, flagged: flagged.length, warnings: warnings.length },
     };
 }
 /**

package/dist/commands/lint/types.js

@@ -1,4 +1,25 @@
 // 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 {};
+/**
+ * The issue codes that are ADVISORY: surfaced in lint output but never routed
+ * into `flagged`, so `--fail-on-flagged` cannot fail a run over one.
+ *
+ * ONE home for that decision. EVERY routing point consults it — the adapter
+ * path (`lint/index.ts#lintViaAdapter`), the sweep's per-file loop, and the
+ * sweep's workflow-frontend pass — so a new advisory code cannot be classified
+ * correctly in one place and land in `flagged` (exit 1) in another; a finding
+ * is never filed by which producer emitted it. A future advisory belongs in
+ * BOTH this set and {@link LintIssueType}: an unrecognized code is folded onto
+ * `adapter-diagnostic` at the adapter boundary, which is deliberately NOT
+ * advisory, so a code missing from the union cannot be routed by this set.
+ *
+ * Advisory-ness is deliberately NOT a field on {@link LintIssue}: issues are
+ * serialized verbatim by `--format json`, and a new key on every advisory
+ * would change every consumer's output to restate what `issue` already says.
+ */
+export const ADVISORY_LINT_ISSUES = new Set(["workflow-warning"]);
+/** True when `issue` belongs to the advisory channel — see {@link ADVISORY_LINT_ISSUES}. */
+export function isAdvisoryLintIssue(issue) {
+    return ADVISORY_LINT_ISSUES.has(issue.issue);
+}

package/dist/commands/proposal/repository.js

@@ -54,6 +54,7 @@ import { _setTxnMutationHookForTests, advanceTxn, beginTxn, canonicalTxnRoot, cl
 import { canonicalBundleIdForTarget, resolveBundleWriteTarget } from "../../core/mutation-target.js";
 import { withImmediateTransaction, withStateDb } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
+import { recordWrittenPath } from "../../core/write-provenance.js";
 import { assertAkmAssetWrite, assertWriteTargetPathsClean, captureGitPublication, captureWriteTargetPathSnapshot, prepareWriteTargetForMutation, publishWriteTargetTransaction, resolveWriteTarget, } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
@@ -901,6 +902,9 @@ function rollbackPreparedProposalTransaction(txn) {
         if (p.originalHash === null) {
             if (currentHash === p.publishedHash && sameProposalFile(p.assetPath, p.publishPath)) {
                 fs.unlinkSync(p.assetPath);
+                // #652: un-publishing is a mutation of this run's own write — journal
+                // it so the sync stages the FINAL state of a written-then-reverted path.
+                recordWrittenPath(p.assetPath);
             }
             else if (currentHash !== null) {
                 throw new Error(`Cannot roll back proposal transaction: target was created externally.`);
@@ -912,8 +916,10 @@ function rollbackPreparedProposalTransaction(txn) {
         cleanupProposalPublication(p);
         return;
     }
-    if (currentHash === p.publishedHash)
+    if (currentHash === p.publishedHash) {
         fs.unlinkSync(p.assetPath);
+        recordWrittenPath(p.assetPath);
+    }
     else if (currentHash !== null && currentHash !== p.originalHash) {
         throw new Error(`Cannot roll back proposal transaction: ${p.assetPath} diverged.`);
     }
@@ -922,6 +928,9 @@ function rollbackPreparedProposalTransaction(txn) {
             throw new Error(`Cannot restore proposal backup: ${p.assetPath} is occupied.`);
         }
         fs.linkSync(p.displacedPath, p.assetPath);
+        // #652: restoring the displaced original still leaves the path in a state
+        // this run produced; journal it so the final on-disk bytes are staged.
+        recordWrittenPath(p.assetPath);
     }
     cleanupProposalPublication(p);
 }
@@ -1023,6 +1032,10 @@ function persistProposalEvent(txn, proposal, ctx) {
 async function finalizeProposalTransaction(txn, target, proposal, ctx) {
     const p = txn.journal.payload;
     validatePublishedProposal(p);
+    // #652: finalizing an `asset-published` transaction that a CRASHED earlier
+    // run left behind is this run adopting that write — journal the asset so the
+    // adopting run's auto-sync commits it instead of leaving it stranded.
+    recordWrittenPath(p.assetPath);
     cleanupProposalPublication(p);
     if (txn.journal.phase === "asset-published") {
         const commitRoot = target.source.repoPath ?? target.source.path;
@@ -1343,6 +1356,9 @@ function publishProposalAsset(txn, target) {
             }
         }
         fs.linkSync(p.publishPath, p.assetPath);
+        // #652: the accepted-proposal (and revert) target is the run's headline
+        // write — journal it the instant the asset lands, before the txn advances.
+        recordWrittenPath(p.assetPath);
         fsyncTxnDir(path.dirname(p.assetPath));
         const snapshot = captureWriteTargetPathSnapshot(target, p.assetPath);
         if (snapshot)

package/dist/commands/sources/info.js

@@ -1,10 +1,10 @@
 // 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 fs from "node:fs";
 import { placementTypes } from "../../core/asset/asset-placement.js";
 import { resolveStashDir } from "../../core/common.js";
 import { getSources, loadConfig } from "../../core/config/config.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { error } from "../../core/warn.js";
 import { getEffectiveSemanticStatus, readSemanticStatus } from "../../indexer/search/semantic-status.js";
@@ -83,8 +83,18 @@ function readIndexStats(resolvedPath) {
         hasEmbeddings: false,
         vecAvailable: false,
     };
-    if (!fs.existsSync(resolvedPath))
+    // "Absent" is the ordinary first-run state; "inaccessible" is a fault that
+    // must not present as an empty index (#791). `akm info` is the command an
+    // operator reaches for to DIAGNOSE this, so it reports rather than throws —
+    // but it says so explicitly instead of returning zeros that look healthy.
+    const { access, code } = classifyPathAccess(resolvedPath);
+    if (access === "absent")
         return EMPTY;
+    if (access === "inaccessible") {
+        const detail = describeInaccessiblePath(resolvedPath, code);
+        error(`[akm info] index database is not readable: ${detail}`);
+        return { ...EMPTY, unreadable: detail };
+    }
     let db;
     try {
         db = openExistingDatabase(resolvedPath);

package/dist/commands/sources/installed-stashes.js

@@ -18,6 +18,7 @@ import path from "node:path";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { getSources, loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { isPathAbsent } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
@@ -125,7 +126,11 @@ function describeLock(entry) {
 function readBundleCounts() {
     const counts = new Map();
     const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
+    // An empty map renders as `itemCount: 0` for every bundle — indistinguishable
+    // from "these bundles really are empty". Only a never-built index gets to say
+    // that silently; an unreadable one falls through to the opener and is
+    // reported by the `warn` in the catch below (#791).
+    if (isPathAbsent(dbPath))
         return counts;
     let db;
     try {

package/dist/commands/tasks/tasks.js

@@ -40,8 +40,12 @@ export async function akmTasksAdd(input, deps = {}) {
     if (targetCount !== 1) {
         throw new UsageError("Pass exactly one of --workflow <ref>, --prompt <asset-ref|./file.md|text>, or --command <shell-command>.", "INVALID_FLAG_VALUE");
     }
-    if (input.workflow && (input.engine !== undefined || input.model !== undefined || input.timeoutMs !== undefined)) {
-        throw new UsageError("Workflow tasks accept only --params; engine, model, and timeout are prompt-task fields.", "INVALID_FLAG_VALUE");
+    // `--timeout-ms` IS valid on a workflow task: it is the whole-run bound the
+    // task runner turns into an abort signal (issue 11), the same one
+    // `akm workflow run --timeout` applies interactively. Engine and model stay
+    // prompt-only — a workflow's engines come from its frozen plan.
+    if (input.workflow && (input.engine !== undefined || input.model !== undefined)) {
+        throw new UsageError("Workflow tasks accept --params and --timeout-ms; engine and model are prompt-task fields.", "INVALID_FLAG_VALUE");
     }
     if (hasCommand && (input.engine !== undefined || input.model !== undefined)) {
         throw new UsageError("Command tasks accept --timeout-ms but not --engine or --model.", "INVALID_FLAG_VALUE");
@@ -597,6 +601,8 @@ function renderTaskYaml(input) {
         if (input.params) {
             obj.params = parseJsonObjectArg(input.params);
         }
+        if (input.timeoutMs !== undefined)
+            obj.timeoutMs = input.timeoutMs;
     }
     else if (input.prompt) {
         obj.prompt = input.prompt;

package/dist/commands/workflow-cli.js

@@ -9,6 +9,7 @@
  */
 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";
@@ -152,7 +153,6 @@ const workflowRunCommand = defineJsonCommand({
         const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0, WORKFLOW_MAX_RETRIES);
         const timeoutMs = parseWorkflowTimeout(getStringArg(args, "timeout"));
         const controller = new AbortController();
-        let timedOut = false;
         let signalExitCode;
         const interrupt = (signal) => {
             signalExitCode = signal === "SIGINT" ? 130 : 143;
@@ -162,13 +162,12 @@ const workflowRunCommand = defineJsonCommand({
         const onSigterm = () => interrupt("SIGTERM");
         process.once("SIGINT", onSigint);
         process.once("SIGTERM", onSigterm);
-        const timer = timeoutMs === undefined
-            ? undefined
-            : setTimeout(() => {
-                timedOut = true;
-                controller.abort(new Error(`Workflow run timed out after ${timeoutMs}ms.`));
-            }, timeoutMs);
-        timer?.unref?.();
+        // The same deadline a scheduled workflow task arms (`tasks/runner.ts`),
+        // sharing this controller with the signal handlers above.
+        const deadline = armAbortDeadline(controller, {
+            timeoutMs,
+            reason: `Workflow run timed out after ${timeoutMs}ms.`,
+        });
         try {
             const result = await runWorkflowSteps({
                 target: args.target,
@@ -177,15 +176,22 @@ const workflowRunCommand = defineJsonCommand({
                 ...(maxRetries !== undefined ? { maxRetries } : {}),
                 signal: controller.signal,
             });
+            // The abort is observed between steps, so a deadline landing in the run's
+            // final bookkeeping fires on a run that then finishes. Reporting that as
+            // timed out would send an operator to resume a run with nothing left to
+            // resume — `tasks/runner.ts` suppresses the same case.
+            const timedOut = deadline.timedOut() && result.run.status !== "completed";
             const rendered = { ...result, ...(timedOut ? { timedOut: true } : {}) };
             output("workflow-run", rendered);
-            if (result.run.status === "failed" || result.gateRejection || result.aborted) {
+            // `blocked` is a stopped, unverified run — a verification-judge failure
+            // leaves it there for `akm workflow resume` — so it must not exit 0 and
+            // read as success to a script (it maps to 1 for scheduled tasks too).
+            if (result.run.status === "failed" || result.run.status === "blocked" || result.gateRejection || result.aborted) {
                 process.exitCode = signalExitCode ?? EXIT_CODES.GENERAL;
             }
         }
         finally {
-            if (timer)
-                clearTimeout(timer);
+            deadline.disarm();
             process.off("SIGINT", onSigint);
             process.off("SIGTERM", onSigterm);
         }