akm-cli 0.9.10 → 0.9.11

package/dist/tasks/scheduler-sync.js

@@ -323,27 +323,9 @@ async function compileTaskSources(input, collector, out, failures) {
             });
             const document = projectTaskSourceV4(parsed.v4);
             const qualifiedRef = makeBundleRef(input.bundleName, conceptId);
-            // P2b Lane B (spec docs/plans/specs/p2b-input-bindings.md §4.4, rows
-            // B-50/F-B2): validate each v4 schedule entry's inputs against the
-            // task's OWN declared contract WITH DEFAULTS APPLIED — the same
-            // applyInputDefaults + validateInputs pair akm task run uses
-            // (src/tasks/run/load-task.ts). parseTaskSource's own parse-time check
-            // (task-source-v4.ts's parseScheduleEntry) already rejects an
-            // unknown/malformed entry against the RAW supplied values; this is a
-            // deliberate second, independent gate over the DEFAULTED view — the
-            // exact set of values the compiled invocation below actually delivers
-            // — so a violation fails HERE, recorded as a task failure at sync,
-            // rather than surfacing for the first time when the scheduler fires
-            // the compiled invocation.
-            const contract = parsed.v4.inputs ?? {};
-            for (const scheduleEntry of parsed.v4.schedule) {
-                const defaultedInputs = applyInputDefaults(contract, { ...scheduleEntry.inputs });
-                const errors = validateInputs(contract, defaultedInputs);
-                if (errors.length > 0) {
-                    throw new UsageError(`Task ${JSON.stringify(qualifiedRef)} schedule[${scheduleEntry.ordinal}].inputs does not satisfy ` +
-                        `its declared inputs once defaults are applied: ${errors.join("; ")}`, "TASK_SOURCE_INVALID");
-                }
-            }
+            // See assertTaskScheduleInputsSatisfyContract's own docblock (below in
+            // this file) for why this second, defaults-applied gate exists.
+            assertTaskScheduleInputsSatisfyContract(parsed.v4, qualifiedRef);
             await prepareTaskV3Execution(document, {
                 taskId: id,
                 taskRef: qualifiedRef,
@@ -380,16 +362,60 @@ async function compileTaskSources(input, collector, out, failures) {
                     inputs: schedule.inputs,
                 })),
             });
-            for (const binding of sourceBindings) {
-                parseSchedule(binding.cron, input.backend);
-                out.push(binding);
-            }
+            assertTaskScheduleCronValid(parsed.v4, input.backend);
+            out.push(...sourceBindings);
         }
         catch (cause) {
             failures.push(taskFailure(sourcePath, qualifiedRefForFailure, cause));
         }
     }
 }
+/**
+ * P2b Lane B (spec §4.4, rows B-50/F-B2): validate every v4 `schedule:`
+ * entry's `inputs` against the task's OWN declared contract WITH DEFAULTS
+ * APPLIED — the same `applyInputDefaults` + `validateInputs` pair
+ * `akm task run` uses (`src/tasks/run/load-task.ts`). `parseTaskSource`'s
+ * own parse-time check (`task-source-v4.ts`'s `parseScheduleEntry`) already
+ * rejects an unknown/malformed entry against the RAW supplied values; this
+ * is a deliberate second, independent gate over the DEFAULTED view — the
+ * exact set of values a compiled invocation actually delivers — so a
+ * violation fails HERE, recorded as a task failure at sync, rather than
+ * surfacing for the first time when the scheduler fires the invocation.
+ *
+ * Extracted so `akm task validate` can run the IDENTICAL gate
+ * over a bare file path without a second, potentially-diverging copy of
+ * this check. `refLabel` is only the text embedded in the thrown message —
+ * `compileTaskSources` passes its bundle-qualified ref; `akm task validate`,
+ * which never resolves a bundle for a bare file, passes the file path.
+ */
+export function assertTaskScheduleInputsSatisfyContract(v4, refLabel) {
+    const contract = v4.inputs ?? {};
+    for (const scheduleEntry of v4.schedule) {
+        const defaultedInputs = applyInputDefaults(contract, { ...scheduleEntry.inputs });
+        const errors = validateInputs(contract, defaultedInputs);
+        if (errors.length > 0) {
+            throw new UsageError(`Task ${JSON.stringify(refLabel)} schedule[${scheduleEntry.ordinal}].inputs does not satisfy ` +
+                `its declared inputs once defaults are applied: ${errors.join("; ")}`, "TASK_SOURCE_INVALID");
+        }
+    }
+}
+/**
+ * Validate every v4 `schedule:` entry's `cron` against the active scheduler
+ * backend's dialect (`parseSchedule`, `./schedule.ts`) — cron is the most
+ * permissive of the three backends, so a task authored on Linux can carry a
+ * cron expression launchd/schtasks cannot translate; `compileTaskSources`
+ * re-checks against the LOCAL backend on every sync rather than trusting
+ * whatever backend the file was authored against.
+ *
+ * Extracted alongside {@link assertTaskScheduleInputsSatisfyContract}
+ * so `akm task validate` shares this exact gate instead of a second copy
+ * that could silently drift from what `akm task sync` actually enforces.
+ */
+export function assertTaskScheduleCronValid(v4, backend) {
+    for (const scheduleEntry of v4.schedule) {
+        parseSchedule(scheduleEntry.cron, backend);
+    }
+}
 async function compileWorkflowSources(input, collector, out, evidence, failures) {
     if (input.adapterId !== "akm" && input.adapterId !== "akm-workflow")
         return;

package/dist/workflows/exec/dispatch-redaction.js

@@ -15,21 +15,23 @@
  * @module workflows/exec/dispatch-redaction
  */
 import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
+import { lookupApiKeyFileValue } from "../../integrations/agent/engine-resolution.js";
 /**
  * Every exact value that must never survive into the journal from ONE frozen
  * dispatch: the resolved `env` bindings injected into the child, the selected
- * engine's (and its SDK fallback's) credential env values, and any
- * `envPassthrough` value the redaction policy does not consider safe to expose.
+ * engine's (and its SDK fallback's) credential — an env value, or a
+ * file-backed one (#905) — and any `envPassthrough` value the redaction
+ * policy does not consider safe to expose.
  *
  * Shared by the unit path and the gate-judge path. There is deliberately ONE
  * collector: a second, parallel implementation is exactly how a dispatch path
  * silently loses the scrub.
  *
- * The credential values are read from `process.env` AT CALL TIME, so a caller
- * must collect no earlier than the dispatch whose outcome it scrubs. A snapshot
- * taken when the dispatch was merely *planned* can predate a credential the
- * dispatch then resolves live, leaving the exact value it must remove out of
- * the set.
+ * The credential values are read from `process.env` (or disk, for a file-
+ * backed one) AT CALL TIME, so a caller must collect no earlier than the
+ * dispatch whose outcome it scrubs. A snapshot taken when the dispatch was
+ * merely *planned* can predate a credential the dispatch then resolves live,
+ * leaving the exact value it must remove out of the set.
  */
 export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
     const values = new Set([...Object.values(env ?? {}), ...(dispatch.sensitiveValues ?? [])]);
@@ -42,6 +44,13 @@ export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
                 if (value)
                     values.add(value);
             }
+            // #905: file-backed credential — best-effort read, never throws, so a
+            // broken apiKeyFile is reported by the real dispatch, not this collector.
+            if (runner.apiKeyFile) {
+                const value = lookupApiKeyFileValue(runner.apiKeyFile);
+                if (value)
+                    values.add(value);
+            }
             return;
         }
         for (const name of runner.profile.envPassthrough ?? []) {
@@ -55,6 +64,11 @@ export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
                 if (value)
                     values.add(value);
             }
+            if (runner.fallbackApiKeyFile) {
+                const value = lookupApiKeyFileValue(runner.fallbackApiKeyFile);
+                if (value)
+                    values.add(value);
+            }
         }
     };
     addCredential(dispatch.runner);

package/docs/integration/bundling-akm.md

@@ -259,7 +259,7 @@ rather than rely on `$HOME`-derived defaults (names verified against
 | `AKM_CONFIG_DIR` | `config.json`'s directory. |
 | `AKM_DATA_DIR` | Durable, non-regenerable data: **`index.db` and `state.db` live here.** This is the directory a migration snapshot's safety copy sits beside. |
 | `AKM_CACHE_DIR` | Regenerable cache: registry downloads, config backups, task logs. Safe to discard between image builds (not between boots of the same running install). |
-| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory used for scheduled-task invocation context and companion-plugin hook state (Claude Code / OpenCode hook logs). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
+| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory. Holds scheduled-task invocation context, companion-plugin hook state (Claude Code / OpenCode hook logs), and, per stash, `akm improve`'s machine-local writers (`improve/distill-rejected/`, `improve/eval-cases/`, `improve/measurement/verdicts/`) and whole-run lock (`locks/`) — see [Storage locations](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/storage-locations.md). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
 
 Set all five to paths that persist across container restarts (a mounted
 volume), or `akm migrate apply` will see an empty `state.db` on every boot

package/docs/migration/v0.8-to-v0.9.md

@@ -112,6 +112,38 @@ IR and freeze the durable plan v4 family's executable `irVersion: 5` format.
 That is the only executable stored plan. Do not copy an old workflow database
 expecting old runs to resume; start new runs from current authored sources.
 
+## Storage relocations within the 0.9.x line
+
+0.9.11 (itlackey/akm#890) moves five machine-local `akm improve` writers out
+of `$STASH/.akm` — where they never belonged, per the "must travel with the
+content" rule in [Storage locations](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/storage-locations.md)
+— into `$STATE`/`$CACHE`, namespaced per stash so two stashes on one machine
+never collide:
+
+| Old path | New path |
+|---|---|
+| `$STASH/.akm/distill-rejected/` | `$STATE/improve/distill-rejected/<stash>/` |
+| `$STASH/.akm/eval-cases/` | `$STATE/improve/eval-cases/<stash>/` |
+| `$STASH/.akm/measurement/verdicts/` | `$STATE/improve/measurement/verdicts/<stash>/` |
+| `$STASH/.akm/unresolved-sources/` | `$CACHE/index/unresolved-sources/<stash>/` |
+| `$STASH/.akm/improve.lock` (+ `.improve.lock.operations.sensitive`) | `$STATE/locks/<stash>/improve.lock` (+ `.improve.lock.operations.sensitive`) |
+
+Any script that reads the old paths directly — `scripts/akm-eval/src/proactive-verdict.ts`
+(verdicts), `scripts/akm-eval/README.md`'s eval-cases note, or a custom
+snapshot/backup tool — must read the new ones instead; the pilot treatment
+file at `$STASH/.akm/measurement/` (sibling to `verdicts/`) is unaffected, it
+was never a writer output. `akm migrate status`/`apply [--dry-run]` covers
+every configured LOCAL bundle (the default stash first, then every other
+filesystem-backed bundle — a `git`/`website`/`npm` bundle is cache-backed,
+never touched), and reports and relocates any files still sitting at the old
+paths (same-filesystem rename, or copy-then-delete across filesystems). A
+lock file is only ever deleted once the same staleness check `akm improve`
+itself uses says its holder is dead; a lock a live run still holds (or one
+this process cannot read) is left in place and reported instead. The whole
+step is idempotent — a second run reports nothing pending.
+`$STASH/.akm/memory-cleanup/` did not move; it is the one confirmed exception
+to the rule (see Storage locations, above).
+
 ## Recovery
 
 If the new setup is wrong, stop AKM, move the new current directories aside,

package/docs/reference/cli.md

@@ -2457,10 +2457,10 @@ shell commands. It manages on-disk task definitions under
 (cron / launchd / schtasks). Task source v4 YAML (`version: 4`) is the only
 executable source contract this release accepts; `akm task add` writes v4 —
 see the canonical [Tasks reference](tasks.md). The
-group is `add | run | explain | sync | doctor | history | prune` — there is
-no `list` or `remove`; use `akm search --type task` / `akm show tasks/<id>`
-to inspect, and edit the file + `akm task sync` to change or remove a
-schedule.
+group is `add | run | explain | validate | sync | doctor | history | prune`
+— there is no `list` or `remove`; use `akm search --type task` /
+`akm show tasks/<id>` to inspect, and edit the file + `akm task sync` to
+change or remove a schedule.
 
 ```sh
 akm search --type task                      # List tasks (cross-bundle)
@@ -2472,6 +2472,7 @@ akm task add nightly --schedule "@daily" --command "akm improve" --disabled  # r
 akm task add nightly --schedule "@daily" --command "akm improve" --force    # overwrite an existing task id
 akm task run <id>                           # Execute now (what the scheduler calls)
 akm task explain <ref>                      # Read-only: declared inputs, target, schedule — spawns nothing
+akm task validate <path>                    # Read-only: parse one task file by path, report sync's diagnostic
 akm task history [<id>] [--id <id>] [--limit <n>]  # Recent runs from state.db (positional id == --id)
 akm task sync                               # Reconcile on-disk YAML with scheduler
 akm task sync --dry-run                     # Preview the reconcile — zero scheduler writes
@@ -2494,6 +2495,30 @@ it never spawns anything, writes history, or touches the scheduler. A
 secret-shaped value prints as `<redacted>`. See
 [`akm task explain`](tasks.md#akm-task-explain).
 
+`akm task validate <path>` parses ONE task file by filesystem path — not a
+concept ref or id, and the file need not live in any configured bundle —
+and reports the same diagnostic `akm task sync` would produce for it,
+INCLUDING sync's own cron-dialect check and its per-schedule-entry
+input-contract check (so a file `sync` would reject can never be reported
+`valid`/`converts` here): `{ok, path, sourceVersion, outcome, reason?,
+resolved?}` where `outcome` is `valid` (parses as task source v4 directly
+and passes both sync checks), `converts` (task v2/v3 that the deterministic
+migrator converts in memory and which then also passes both sync checks),
+`blocked` (task v2/v3 the migrator itself cannot convert — needs a human
+decision), `invalid` (the YAML doesn't parse, or the document fails schema
+validation, or it parsed but fails one of the two sync checks), or
+`not-a-task` (the YAML parses but never declares a `version:` field — not
+shaped like a task source). `resolved` is the compiled task shape
+`akm task sync` itself would build a scheduler binding from — id, the
+compiled schema version, resolved `uses`/`run` target, declared `inputs`
+contract, and `schedule` bindings — present only on `valid`/`converts`.
+Unlike `akm task explain`, it never runs execution lowering: a command-kind
+task validates the same whether or not the local config has an engine
+configured. Exits 0 for `valid`/`converts`, 1 for
+`blocked`/`invalid`/`not-a-task`, 2 for a missing or unreadable path.
+**Read-only**: it never touches the scheduler and never requires the file to
+be indexed or wired into a bundle.
+
 `akm task run` is what cron / launchd / schtasks invoke at the scheduled
 time. Each run is recorded as a row in the durable `task_history` table
 (`state.db`), surfaced by `akm task history` — **not** by `akm log`; there is
@@ -2539,7 +2564,8 @@ the AKM storage path or installed runtime path therefore requires an explicit
 operates on the primary/default bundle. `add`, `history`, `sync`, `run`, and
 `explain` all accept `--bundle <bundle>` to schedule, reconcile, or inspect
 tasks that live in another configured bundle (`doctor` reports scheduler-wide
-state and takes no `--bundle`):
+state and takes no `--bundle`; `validate` takes a bare filesystem path
+instead of a ref, so it has no bundle to target either):
 
 ```sh
 akm task add nightly --schedule "@daily" --command "akm improve" --bundle team-bundle

package/docs/reference/configuration.md

@@ -217,7 +217,8 @@ and is never rescued by that fallback.
 Index passes select engines through `index.defaults.engine` or
 `index.<pass>.engine`. Per-pass `model`, `timeoutMs`, and `llm` fields are
 invocation overrides; `enabled: false` disables that pass. Connection fields
-such as `endpoint`, `provider`, and `apiKey` belong only on named engines.
+such as `endpoint`, `provider`, `apiKey`, and `apiKeyFile` belong only on
+named engines.
 
 `workflow.maxConcurrency` is the native workflow engine ceiling. An explicit
 value is clamped to `1..64`. When absent, AKM derives the cap once from the CPU
@@ -494,7 +495,7 @@ generic walker.
 | `AKM_BUNDLE_DIR` | Override the bundle directory |
 | `AKM_DATA_DIR` | Override the data directory — `index.db`, durable `state.db`, and `akm.lock` (or set `XDG_DATA_HOME`) |
 | `AKM_CACHE_DIR` | Override the cache directory — regenerable caches (or set `XDG_CACHE_HOME`) |
-| `AKM_STATE_DIR` | Override the state directory — task-scheduler invocation state (or set `XDG_STATE_HOME`) |
+| `AKM_STATE_DIR` | Override the state directory — task-scheduler invocation state, and (per stash) `akm improve`'s machine-local writers and whole-run lock (or set `XDG_STATE_HOME`) |
 | `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE` |
 | `AKM_VERBOSE` | Truthy value enables the same diagnostics as `--verbose` |
 | `AKM_DEBUG` | `1` prints a stack trace on unexpected internal errors |
@@ -503,6 +504,15 @@ For an engine named `fast`, its fallback variable is
 `AKM_ENGINE_FAST_API_KEY`. An explicit `apiKey` symbolic reference is
 authoritative and does not fall through to another variable.
 
+`engines.<name>.apiKeyFile` is a file-backed alternative to `apiKey`, for a
+host that refuses to put secrets in the process environment (a container
+runtime's mounted secret, for example). It is a plain filesystem path — `~`
+expands to the home directory — read at dispatch time and trimmed of one
+trailing newline; the raw path is safe to keep in `config.json` since it is
+not itself a secret. Setting both `apiKey` and `apiKeyFile` on the same
+engine is rejected. A missing, unreadable, or empty file fails the call
+closed, naming the engine and path but never the file's content.
+
 Use `AKM_SQLITE_JOURNAL_MODE=DELETE` or `TRUNCATE` when WAL is unavailable,
 such as on some NFS/SMB mounts. With the default `WAL` setting, AKM detects a
 network filesystem for the data directory and falls back to `DELETE`.

package/docs/reference/data-and-telemetry.md

@@ -16,7 +16,7 @@ AKM adds no network destinations of its own. The requests it *does* make all go
 2. **Registry metadata and bundle packages** from sources you explicitly configure (GitHub, npm, git remotes, websites) — those hosts receive the fetch/clone/crawl requests, and website sources receive requests for the pages you crawl.
 3. **`akm upgrade`** — fetches the latest release from GitHub releases (GitHub sees the request).
 4. **`akm setup`** — a single DNS lookup for `github.com` to decide whether to skip network-dependent steps (Ollama detection, remote embedding probes) when offline. No HTTP request is made by this probe; if it succeeds, akm proceeds with the network-dependent steps you already configured.
-5. **`akm improve` dead-link checks** — a full-scope improve run (the default for a bare `akm improve`) sends best-effort `HEAD` requests (following redirects, with a short timeout and a hard cap on URL count) to URLs found in the bodies of the knowledge assets it is improving, to flag dead links. The hosts of those URLs see a `HEAD` request; no asset content is sent. Keep URLs you don't want probed out of knowledge-asset bodies, or run improve with an explicit narrower scope.
+5. **`akm improve` dead-link checks** — a full-scope improve run (the default for a bare `akm improve`) sends best-effort `HEAD` requests (following redirects, with a short per-request timeout, checked at a bounded concurrency rather than all at once) to every URL found in the bodies of the knowledge assets it is improving, to flag dead links. The hosts of those URLs see a `HEAD` request; no asset content is sent. Keep URLs you don't want probed out of knowledge-asset bodies, or run improve with an explicit narrower scope.
 
 In every case the receiving endpoint is one you configured or invoked; the data leaving your machine is the data you directed AKM to send there.
 

package/docs/reference/tasks.md

@@ -385,6 +385,14 @@ for full before/after examples and recovery guidance.
 - `akm task explain <ref>` prints a task's declared inputs, resolved target,
   effective execution settings, and schedule bindings without running
   anything — see [`akm task explain`](#akm-task-explain) above.
+- `akm task validate <path>` parses one task file by filesystem path (the
+  file need not live in a configured bundle) and reports the same
+  `valid`/`converts`/`blocked`/`invalid`/`not-a-task` diagnostic
+  `akm task sync` would produce for it — including sync's own cron-dialect
+  check and its per-schedule-entry input-contract check — without touching
+  the scheduler and without requiring a configured engine, even for a
+  command-kind task. The envelope's own `sourceVersion` field names the
+  file's originally declared schema version (2, 3, or 4).
 - `akm task add` writes a task source v4 document and installs it after
   validation. `--params` renders typed `inputs:` declarations instead of a
   `with:` bag; `--schedule` is required on every invocation, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.10",
+  "version": "0.9.11",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [

package/schemas/akm-config.json

@@ -34,6 +34,10 @@
                 "type": "string",
                 "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*$|^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
               },
+              "apiKeyFile": {
+                "type": "string",
+                "minLength": 1
+              },
               "temperature": {
                 "type": "number"
               },
@@ -1719,6 +1723,10 @@
                     "type": "string",
                     "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*$|^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
                   },
+                  "apiKeyFile": {
+                    "type": "string",
+                    "minLength": 1
+                  },
                   "temperature": {
                     "type": "number"
                   },