akm-cli 0.9.0 → 0.9.1-beta.2

package/README.md

@@ -1,16 +1,17 @@
 # akm -- Agent Knowledge Manager
 
-> **akm** (Agent Knowledge Manager) -- A knowledge toolkit for AI agents.
+> Give every coding agent the capabilities your team has already built.
 
 [![npm version](https://img.shields.io/npm/v/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![npm downloads](https://img.shields.io/npm/dm/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![license](https://img.shields.io/github/license/itlackey/akm)](https://github.com/itlackey/akm/blob/main/LICENSE)
 
-`akm` is a knowledge toolkit for AI agent capabilities -- scripts, skills, commands,
-agents, knowledge, instructions, memories, workflows, env files, secrets, lessons,
-tasks, sessions, and facts. It can discover and install bundles from npm, git, local
-directories, and configured registries. It works with any AI coding assistant that can run shell commands,
-including [Claude Code](https://claude.ai/code),
+**akm** is a portable capability library for AI agents. Build your agent
+library once. Use it from any shell-capable coding agent. It indexes existing
+agent assets in place, loads only what a task needs, packages capabilities
+into shareable bundles, improves the library through reviewable proposals,
+and runs durable workflows -- locally and without tying the library to one
+assistant, including [Claude Code](https://claude.ai/code),
 [OpenCode](https://opencode.ai), [Cursor](https://cursor.com), and more.
 
 ## Install
@@ -35,54 +36,33 @@ Upgrade in place with `akm upgrade`.
 
 The npm package always uses Node.js to bootstrap its cross-platform command.
 If a working [Bun](https://bun.sh) >= 1.0 is also on `PATH`, the launcher
-prefers Bun for execution; old, unusable, or absent Bun installations fall back
-to Node.js. Node.js remains required for the npm package. The standalone
+prefers Bun for execution; old, unusable, or absent Bun installations fall
+back to Node.js. Node.js remains required for the npm package. The standalone
 binaries are runtime-free.
 
-> The old `vault` asset type was removed in 0.9.0; use `env` for whole `.env`
-> groups and `secret` for standalone sensitive values.
-
 ## Quick Start
 
 ```sh
-akm setup                         # Guided setup: configure, initialize, and index
-akm task doctor                    # Verify scheduler and installed runtime
-akm bundle add github:owner/repo         # Add a bundle from GitHub
-akm search "deploy"               # Find assets across all sources
-akm show scripts/deploy.sh        # View details and run command
-```
-
-Non-interactive setup never activates schedules.
-
-## Schedule Tasks Safely
-
-```sh
-akm setup                 # Review definitions, schedules, and enabled state
-# Confirm scheduler activation only after reviewing the complete task summary.
-akm task doctor           # Verify backend, runtime, task state, and warnings
+akm setup                          # Guided setup: configure, initialize, and index
+akm bundle add github:owner/repo   # Add a bundle from GitHub
+akm index                          # Index sources into the library
+akm search "deploy"                # Find assets across all sources
+akm show scripts/deploy.sh         # View details and run command
 ```
 
-Setup shows the complete task review — both the general-purpose core
-templates and the maintainer-oriented improve cadence — before asking one
-explicit question about changing task files and the OS scheduler. Only
-confirmation prepares the definitions and syncs the scheduler. Declining, or
-running setup non-interactively, leaves both unchanged. A scheduled entry
-captures the installed akm runtime used during activation. Ordinary
-`akm task sync` preserves that runtime; after moving or replacing the
-installation, use `akm task sync --rebind` explicitly to migrate or repair
-scheduler entries, then run `akm task doctor` again.
-
-Rerunning setup preserves existing scheduler bindings. If setup changes the AKM
-storage path, or the installed runtime path changes, run
-`akm task sync --rebind` explicitly.
-
 ## Why akm?
 
-- **Works with any AI agent** -- No plugins or SDKs required. Any model that can run shell commands can use `akm`.
-- **One command to search your knowledge** -- Local assets are searched by default. Add `--from registry` or `--from all` for configured registry results; [skills.sh](https://skills.sh) participates only when enabled.
-- **Install bundles from anywhere** -- npm, GitHub, GitLab, local directories.
-- **Semantic search** -- Optional local embeddings (via Ollama or HuggingFace) for finding assets by meaning, not just keywords.
-- **Private registries** -- Host your own registry for team or enterprise use.
+- **One library for every agent** -- Use the same capability library from Claude Code, OpenCode, Cursor, Aider, Windsurf, or any assistant that can run shell commands.
+- **Load only what the task needs** -- Search or curate a shortlist, then load full content by ref. No giant startup prompt is required.
+- **Package complete capabilities** -- Install and share bundles containing skills, scripts, workflows, agents, instructions, memories, and knowledge -- not just prompt snippets.
+- **Improve through evidence, with review** -- Feedback influences retrieval and produces diffable proposals. Changes remain reviewable and target only writable bundles.
+- **Turn knowledge into repeatable work** -- Run persisted workflows with dispatch, gates, retries, budgets, and resume instead of reconstructing a process from prose every session.
+
+akm retrieves every supported capability type. It directly orchestrates
+defined execution surfaces such as workflows, agent dispatch, tasks, and
+guarded subprocess injection -- it does not blindly execute arbitrary indexed
+content merely because that content appears in search results. It
+complements MCP and assistant-native skills rather than replacing them.
 
 ## Agent Integration
 
@@ -96,32 +76,17 @@ knowledge, instructions, memories, workflows, env files, secrets, lessons, tasks
 sessions, and facts via the `akm` CLI. Use `akm -h` for details.
 ```
 
-## Install Bundles from Anywhere
-
-```sh
-akm bundle add @scope/pkg                          # npm
-akm bundle add github:owner/repo#v1.2.3            # GitHub with tag
-akm bundle add git+https://gitlab.com/org/repo     # Any git repo
-akm bundle add ./path/to/local/dir                 # Local directory
-```
-
-Manage bundles with `akm bundle list`, `akm bundle update --all`, and `akm bundle remove`.
-
-## Publish Your Own Bundle
-
-1. Organize your assets into a directory
-2. Add `"akm"` to `keywords` in `package.json`
-3. Optionally add `akm.include` in `package.json` to control what gets installed
-4. Publish to npm or push to GitHub
+Or generate it directly: `akm help agents >> AGENTS.md`
 
 ## Documentation
 
 Full docs, CLI reference, and guides are available on [GitHub](https://github.com/itlackey/akm):
 
 - [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.md)
+- [Supported Formats](https://github.com/itlackey/akm/blob/main/docs/reference/supported-formats.md)
 - [CLI Reference](https://github.com/itlackey/akm/blob/main/docs/reference/cli.md)
 - [Configuration](https://github.com/itlackey/akm/blob/main/docs/reference/configuration.md)
-- [Bundle Maker's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/stash-makers.md)
+- [Bundle Authoring Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-bundles.md)
 - [Registry](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md)
 
 ## License

package/STABILITY.md

@@ -460,8 +460,10 @@ Internal replacement for the one capability nothing else covered.
 - **0.10 — `--auto-accept` hard error.** It is currently accepted-and-warned;
   see the Improvement loop entry.
 - **0.10 — `BundleAdapter.placeNew()` wiring.** The interface declares
-  `placeNew()` as an optional capability method, and 8 of the built-in
-  adapters already implement it, but nothing in the write path calls it —
+  `placeNew()` as an optional capability method, and 9 of the 11 built-in
+  adapters already implement it (all but `okf` and `website-snapshot`;
+  `claude` and `opencode` inherit theirs from the shared tool-dir factory),
+  but nothing in the write path calls it —
   writes still resolve through AKM's native flat type→directory table.
   Placement for every existing bundle is already correct today; this is a
   deliberately sequenced routing change, not unfinished behavior. See

package/dist/cli/parse-args.js

@@ -45,8 +45,14 @@ export function parsePositiveIntFlag(raw, flagName = "--limit") {
     const trimmed = raw.trim();
     if (!trimmed)
         return undefined;
+    // Strict digits, matching parseNonNegativeIntFlag below. parseInt stops at the
+    // first non-digit, so "10x" silently became 10, "3.5" became 3, and
+    // "5 apples" became 5 — accepted rather than rejected as invalid.
+    if (!/^\d+$/.test(trimmed)) {
+        throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a positive integer.`, "INVALID_FLAG_VALUE");
+    }
     const parsed = parseInt(trimmed, 10);
-    if (Number.isNaN(parsed) || parsed <= 0) {
+    if (parsed <= 0) {
         throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a positive integer.`, "INVALID_FLAG_VALUE");
     }
     return parsed;

package/dist/commands/agent/contribute-cli.js

@@ -174,7 +174,7 @@ export const lintCommand = defineCommand({
         },
         type: {
             type: "string",
-            description: "Only lint assets of this type (e.g. workflows, tasks, memories)",
+            description: "Only lint assets of this type (e.g. workflows, tasks, memories). akm bundles only — every other adapter validates the whole bundle and warns that the flag had no effect.",
             default: undefined,
         },
     },

package/dist/commands/env/child-env.js

@@ -1,6 +1,7 @@
 // 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 { WIN32_SPAWN_ENV_FLOOR } from "../../core/spawn-env.js";
 const CLEAN_ENV_ALLOWLIST = [
     "HOME",
     "PATH",
@@ -38,6 +39,19 @@ export function buildChildEnv(parentEnv, options) {
             if (parentEnv[key] !== undefined)
                 base[key] = parentEnv[key];
         }
+        // The allowlist above is POSIX-shaped. On Windows a child started without
+        // SystemRoot/COMSPEC/PATHEXT and friends frequently cannot start at all —
+        // which is why every other spawn path in the codebase applies this floor
+        // (see spawnEnvNamesFor). `env run --clean` / `secret run --clean` did not,
+        // so clean-mode injection was unusable there. The floor is names the OS
+        // requires of any child, not user configuration, so it does not weaken what
+        // "clean" means about inherited secrets.
+        if (process.platform === "win32") {
+            for (const key of WIN32_SPAWN_ENV_FLOOR) {
+                if (parentEnv[key] !== undefined)
+                    base[key] = parentEnv[key];
+            }
+        }
     }
     for (const key of options.inherit) {
         if (parentEnv[key] !== undefined)

package/dist/commands/feedback-cli.js

@@ -12,6 +12,7 @@ import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
 import { resolveMutationTarget } from "../core/mutation-target.js";
+import { isPathAbsent } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { withStateDb } from "../core/state-db.js";
 import { warn } from "../core/warn.js";
@@ -287,7 +288,12 @@ export const feedbackCommand = defineJsonCommand({
         // background process that holds the writer lock, causing the feedback write
         // to spin-wait for the full reindex duration. If the DB is absent we give a
         // clear error below rather than silently triggering a rebuild.
-        if (!fs.existsSync(getDbPath())) {
+        // "Run 'akm index' first" is only true advice for an index that was never
+        // built. Told to someone whose index exists but is unreadable it is a lie
+        // that sends them to rebuild a file they may not have permission to touch
+        // (#791), so that case falls through to `openExistingDatabase` below, which
+        // names the path, errno, mode/owner and uid instead.
+        if (isPathAbsent(getDbPath())) {
             throw new UsageError("Index not found. Run 'akm index' first to build the index before recording feedback.", "MISSING_REQUIRED_ARGUMENT", "akm index");
         }
         // Feedback writes exactly 2 rows (usage_events + utility_score). SQLite

package/dist/commands/health/llm-usage.js

@@ -20,7 +20,8 @@ function emptyLlmUsageStageAggregate() {
         reasoningTokens: 0,
     };
 }
-function emptyLlmUsageAggregate() {
+/** A zeroed aggregate — also the value health reports when it could not read state.db at all (#791). */
+export function emptyLlmUsageAggregate() {
     return { ...emptyLlmUsageStageAggregate(), byStage: {}, byProcess: {}, byEngine: {} };
 }
 /**

package/dist/commands/health/surfaces.js

@@ -4,9 +4,8 @@
 /**
  * The remaining `surfaces` advisory group for `akm health` (meta-review 08).
  * `stash-git-exposure` (08-F1) shipped first in ./stash-exposure.ts; this
- * module adds the other three read-only checks the adjudication approved:
+ * module adds the other two read-only checks the adjudication approved:
  *
- *   - `secret-file-perms`   — env/secret/backup files not 0600, dirs not 0700 (F4)
  *   - `binary-config-skew`  — config.json written by a NEWER akm than this binary (F3)
  *   - `egress-endpoints`    — the remote-destination list, for eyeball diff (surfaces 3/9)
  *
@@ -15,77 +14,9 @@
  * the stash-exposure pattern. `egress-endpoints` is the one informational
  * (pass-status) entry: it emits whenever any remote endpoint is configured.
  */
-import fs from "node:fs";
-import path from "node:path";
 import { MAX_CONFIG_FILE_BYTES, readTextFileWithLimit } from "../../core/common.js";
 import { CURRENT_CONFIG_VERSION } from "../../core/config/config-schema.js";
 import { compareConfigVersion } from "../../core/config/config-version.js";
-const GROUP_OTHER_BITS = 0o077;
-const OFFENDER_EVIDENCE_CAP = 50;
-function modeOctal(mode) {
-    return (mode & 0o777).toString(8).padStart(3, "0");
-}
-/**
- * `secret-file-perms` (08-F4): flag env/secret/backup files that are not 0600
- * and their directories when not 0700. Scans `<stash>/env`, `<stash>/secrets`
- * and `<cache>/config-backups`; anything readable by group/other is an
- * offender. Silent when every path is tight (or none of the dirs exist).
- */
-export function collectSecretPermsAdvisory(input, platform = process.platform) {
-    if (platform === "win32")
-        return undefined;
-    const roots = [
-        path.join(input.stashDir, "env"),
-        path.join(input.stashDir, "secrets"),
-        path.join(input.cacheDir, "config-backups"),
-    ];
-    const offenders = [];
-    for (const root of roots) {
-        let stat;
-        try {
-            stat = fs.statSync(root);
-        }
-        catch {
-            continue; // absent → nothing to protect
-        }
-        if ((stat.mode & GROUP_OTHER_BITS) !== 0)
-            offenders.push(`${root}/ (${modeOctal(stat.mode)}, want 700)`);
-        let entries;
-        try {
-            entries = fs.readdirSync(root, { recursive: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            const abs = path.join(root, entry);
-            let entryStat;
-            try {
-                entryStat = fs.statSync(abs);
-            }
-            catch {
-                continue;
-            }
-            if ((entryStat.mode & GROUP_OTHER_BITS) === 0)
-                continue;
-            offenders.push(entryStat.isDirectory()
-                ? `${abs}/ (${modeOctal(entryStat.mode)}, want 700)`
-                : `${abs} (${modeOctal(entryStat.mode)}, want 600)`);
-        }
-    }
-    if (offenders.length === 0)
-        return undefined;
-    const preview = offenders.slice(0, 5).join("; ") + (offenders.length > 5 ? `; +${offenders.length - 5} more` : "");
-    return {
-        name: "secret-file-perms",
-        kind: "deterministic",
-        status: "warn",
-        confidence: "high",
-        message: `${offenders.length} env/secret/backup path(s) are readable by group/other: ${preview}. ` +
-            "Tighten with chmod 600 (files) / chmod 700 (dirs) — these hold tokens, keys, and config snapshots.",
-        evidence: { offenders: offenders.slice(0, OFFENDER_EVIDENCE_CAP) },
-    };
-}
 /**
  * `binary-config-skew` (08-F3): warn when config.json carries a configVersion
  * NEWER than (or unorderable against) this binary's CURRENT_CONFIG_VERSION —
@@ -163,14 +94,10 @@ export function collectEgressAdvisory(config) {
     };
 }
 /**
- * Aggregate the three collectors into the advisories array shape `akmHealth`
- * consumes. Order is fixed: perms → skew → egress.
+ * Aggregate the two collectors into the advisories array shape `akmHealth`
+ * consumes. Order is fixed: skew → egress.
  */
 export function collectSurfacesAdvisories(input) {
-    const results = [
-        collectSecretPermsAdvisory({ stashDir: input.stashDir, cacheDir: input.cacheDir }, input.platform ?? process.platform),
-        collectConfigSkewAdvisory(input.configPath),
-        collectEgressAdvisory(input.config),
-    ];
+    const results = [collectConfigSkewAdvisory(input.configPath), collectEgressAdvisory(input.config)];
     return results.filter((r) => r !== undefined);
 }

package/dist/commands/health.js

@@ -9,7 +9,8 @@ import { ConfigError, UsageError } from "../core/errors.js";
 import { readEvents } from "../core/events.js";
 import { listTxnJournalsTolerant, TXN_SWEEP_GRACE_MS } from "../core/fs-txn.js";
 import { openLogsDatabase } from "../core/logs-db.js";
-import { getCacheDir, getConfigPath, getDataDir, getStateDbPathInDataDir } from "../core/paths.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
+import { getConfigPath, getDataDir, getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { readSemanticStatus } from "../indexer/search/semantic-status.js";
@@ -18,7 +19,7 @@ import { queryTaskHistory } from "../storage/repositories/task-history-repositor
 import { collectImproveAdvisories } from "./health/advisories.js";
 import { HEALTH_CHECKS } from "./health/checks.js";
 import { buildImproveSkipSummary, computeWallTimeStats, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./health/improve-metrics.js";
-import { readLlmUsageAggregate } from "./health/llm-usage.js";
+import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
 import { collectStashExposureAdvisory } from "./health/stash-exposure.js";
 import { collectSurfacesAdvisories } from "./health/surfaces.js";
@@ -228,10 +229,9 @@ function gatherImproveSummaryPhase(db, stateDbPath, since, now) {
 /**
  * The three best-effort advisory groups beyond the health-check registry:
  * improve advisories, the `stash-git-exposure` probe, and the 08 surfaces
- * group (secret-file-perms, binary-config-skew, egress-endpoints). Order
- * matches emission order in the returned array. A
- * probe/filesystem failure in either try/catch must not abort the health
- * report — each group degrades to "no advisory" independently.
+ * group (binary-config-skew, egress-endpoints). Order matches emission order in
+ * the returned array. A probe/filesystem failure in either try/catch must not
+ * abort the health report — each group degrades to "no advisory" independently.
  */
 function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, options, egressConfigView) {
     const advisories = [...collectImproveAdvisories(db, stateDbPath, since, improveSummary)];
@@ -254,13 +254,11 @@ function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, optio
     catch {
         // Non-fatal — a git/probe failure must not abort the health report.
     }
-    // 08 surfaces: the remaining read-only advisory group (secret-file-perms,
-    // binary-config-skew, egress-endpoints). Best-effort — a
-    // filesystem probe failure must not abort the health report.
+    // 08 surfaces: the remaining read-only advisory group (binary-config-skew,
+    // egress-endpoints). Best-effort — a filesystem probe failure must not abort
+    // the health report.
     try {
         advisories.push(...collectSurfacesAdvisories({
-            stashDir: options.stashDir ?? resolveStashDir(),
-            cacheDir: getCacheDir(),
             configPath: getConfigPath(),
             config: egressConfigView,
         }));
@@ -328,6 +326,53 @@ function resolveWindowComparePhase(options, db, stateDbPath, now, logsDb) {
     }
     return { windowResults, deltas };
 }
+/**
+ * The health report for a state.db this process cannot read (#791).
+ *
+ * `akm health` is what an operator runs when other commands are misbehaving, so
+ * it must survive the permission problem long enough to NAME it. Previously it
+ * threw `ConfigError` (exit 78) on the state.db open, which meant the one
+ * command able to explain a data-directory permission fault died before
+ * reaching any of its advisories.
+ *
+ * Reported as a hard-channel `fail` — the run genuinely could not assess the
+ * install — with the path, errno, mode/owner and running uid in the message. It
+ * exits non-zero either way; the difference is that the operator is now told
+ * WHY instead of being handed a bare "unable to open database file".
+ */
+function unreadableStateDbReport(detail, options) {
+    return {
+        schemaVersion: 3,
+        ok: false,
+        status: "fail",
+        since: parseHealthSince(options.since),
+        hardChecks: [
+            {
+                name: "state-db-readable",
+                kind: "deterministic",
+                status: "fail",
+                confidence: "high",
+                message: `state.db exists but is not readable: ${detail}. Every other health check is skipped because ` +
+                    "none of them can read it. Check the owner and mode of the data directory, or point " +
+                    "AKM_DATA_DIR / XDG_DATA_HOME at a location this user owns.",
+                evidence: { detail },
+            },
+        ],
+        advisories: [],
+        metrics: {
+            taskFailRate: 0,
+            agentFailureRate: 0,
+            stuckActiveRuns: 0,
+            logBackingRate: 0,
+            // `null`, not 0: the round-trip probe did not run, which is not the same
+            // as it running instantly.
+            probeRoundTripMs: null,
+            llmUsage: emptyLlmUsageAggregate(),
+        },
+        improve: summarizeImproveCompleted([]),
+        sessionLogAdvisories: [],
+    };
+}
 export function akmHealth(options = {}) {
     validateAkmHealthOptions(options);
     const now = options.now ?? (() => Date.now());
@@ -336,11 +381,20 @@ export function akmHealth(options = {}) {
     const hardChecks = [];
     const advisories = [];
     const getExecutionLogCandidatesFn = options.getExecutionLogCandidatesFn ?? getExecutionLogCandidates;
+    // #791: an UNREADABLE state.db is the one failure `akm health` most needs to
+    // be able to report, because it is the command an operator runs to find out
+    // why everything else is behaving oddly. Dying here with exit 78 meant health
+    // could not diagnose that state at all — not even the checks that never touch
+    // state.db got to run. Report it as a finding instead.
     let db;
     try {
         db = openStateDatabase(stateDbPath);
     }
     catch (error) {
+        const { access, code } = classifyPathAccess(stateDbPath);
+        if (access === "inaccessible") {
+            return unreadableStateDbReport(describeInaccessiblePath(stateDbPath, code), options);
+        }
         throw new ConfigError(`Unable to open state.db: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
     }
     // logs.db backs the log-backing metric (#579). Best-effort: when it cannot

package/dist/commands/improve/distill/quality-gate.js

@@ -15,6 +15,7 @@ import { timestampForFilename } from "../../../core/common.js";
 import { appendEvent } from "../../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
 import { withStateDb } from "../../../core/state-db.js";
+import { recordWrittenPath } from "../../../core/write-provenance.js";
 import { getDefaultLlmConfig } from "../../../integrations/agent/engine-resolution.js";
 import { callStructured } from "../../../llm/structured-call.js";
 import { akmSearch } from "../../read/search.js";
@@ -247,7 +248,11 @@ export function writeQualityRejection(stash, inputRef, proposalRef, content, sco
     const rejectDir = path.join(stash, ".akm", "distill-rejected");
     fs.mkdirSync(rejectDir, { recursive: true });
     const ts = timestampForFilename();
-    fs.writeFileSync(path.join(rejectDir, `${ts}-${proposalRef.replace(/[:/\\]/g, "-")}.md`), `---\nscore: ${score}\nreason: ${reason}\noutcome: ${outcome}\n---\n\n${content}`, "utf8");
+    const rejectPath = path.join(rejectDir, `${ts}-${proposalRef.replace(/[:/\\]/g, "-")}.md`);
+    fs.writeFileSync(rejectPath, `---\nscore: ${score}\nreason: ${reason}\noutcome: ${outcome}\n---\n\n${content}`, "utf8");
+    // #652: the rejection envelope lands under the managed `.akm/` tree, which
+    // the pre-provenance sync swept up by pathspec — journal it explicitly.
+    recordWrittenPath(rejectPath);
     appendEvent({
         eventType: "distill_invoked",
         ref: inputRef,

package/dist/commands/improve/eligibility.js

@@ -8,6 +8,7 @@ import { conceptIdFromTypeName, parseRefInput, resolveRef } from "../../core/ass
 import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { readEvents } from "../../core/events.js";
+import { isPathAbsent } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { deriveInstallations } from "../../indexer/installations.js";
 import { getWritableStashDirs, resolveSourceEntries } from "../../indexer/search/search-source.js";
@@ -27,11 +28,16 @@ import { improveStateReadRefs } from "./source-identity.js";
  * yet. `openExistingDatabase` refuses to create a missing `index.db` (see
  * index-connection.ts) — for eligibility, "no index" simply means nothing is
  * eligible, exactly like the readOnly arm's `undefined`.
+ *
+ * `undefined` is reserved for a genuinely ABSENT index. The readOnly arm has
+ * refused to conflate that with an unreadable one since #791; this arm used
+ * `fs.existsSync`, so the same run reported "nothing eligible to improve" at
+ * exit 0 depending only on which branch it took. Both arms now raise.
  */
 function openEligibilityDb(readOnly) {
     if (readOnly)
         return openReadonlyExistingDatabase();
-    return fs.existsSync(getDbPath()) ? openExistingDatabase() : undefined;
+    return isPathAbsent(getDbPath()) ? undefined : openExistingDatabase();
 }
 export function resolveImproveScope(scope) {
     const trimmed = scope?.trim();

package/dist/commands/improve/eval-cases.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../../core/common.js";
+import { recordWrittenPath } from "../../core/write-provenance.js";
 export function writeEvalCase(stashDir, evalCase) {
     const evalDir = path.join(stashDir, ".akm", "eval-cases");
     fs.mkdirSync(evalDir, { recursive: true });
@@ -28,6 +29,7 @@ Use it as a regression test: future improve runs on this ref should not produce
 output that would be rejected for the same reason.
 `;
     writeFileAtomic(filePath, content);
+    recordWrittenPath(filePath);
     return filePath;
 }
 export function countEvalCases(stashDir) {