akm-cli 0.9.10 → 0.9.12

package/CHANGELOG.md

@@ -4,6 +4,232 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.12] - 2026-09-03
+
+### Added
+
+- **`akm health` probes LLM engine reachability (#914).** `default-llm-engine`
+  and `configured-engines` now send one bounded `GET` to the endpoint's
+  `/models` route (3 s timeout, one probe per distinct endpoint per
+  invocation, no cross-run cache) instead of only checking that a credential is
+  present. Any HTTP response counts as reachable, so a cold local server is
+  never asked to load a model just to be checked. An unreachable default LLM engine is a hard `fail` naming the
+  connection error; an unreachable non-default engine is a `warn`. Pass
+  `--no-probe` on an offline or air-gapped host to keep the credential-only
+  verdict; the message then says reachability was not probed.
+- **`akm proposal extract` reports the engine it resolved (#913).** The
+  envelope carries `engine` and `engineKind` (`llm`, `sdk`, or `agent`), every
+  `sessions[]` entry carries `engine`, and the `extract_sessions_seen` ledger
+  metadata records it, so "which engine did that run actually use" is one
+  field instead of config archaeology. `akm health`'s `active-improve-strategy`
+  check names the engine each improve process resolved to, which makes a
+  strategy-level `engine` pin that shadows `defaults.llmEngine` visible.
+- **`akm workflow run <ref>` says when it resumes, and `--new` starts fresh
+  (#919).** Resolving a ref to an already-active run in the current scope is
+  unchanged, but the `workflow-run` envelope now carries `resumed: true` and
+  the text output leads with `resuming existing run <id> for <ref>; pass --new
+  to start a fresh run`. `--new` starts a second run and leaves the active one
+  untouched. `status`, `abandon`, `resume`, and `run <id>` all accept a unique
+  run-id prefix of eight or more characters.
+
+### Changed
+
+- **A run that skipped every session for an infrastructure reason is visible
+  in the extract envelope (#912).** `warnings[]` gains one aggregate line per
+  infrastructure skip reason (`llm_unavailable`, `read_failed`, `exception`,
+  `locked_concurrent`), for example `25 of 25 sessions skipped: llm_unavailable
+  (engine "default")`, and a `skipReasons` count map is present whenever
+  `sessionsSkipped > 0`. `ok` keeps meaning "the command ran" and the exit code
+  does not change; that meaning is now written down on the type.
+- **`akm health`'s `session-extraction` check reads the extraction ledger
+  (#914).** It used to read only `improve_runs`, which the hook-driven
+  `akm proposal extract --session-id` never writes, so a plugin-driven machine
+  reported "not active" as `pass` forever. It now derives its verdict from the
+  last seven days of `extract_sessions_seen`: `unknown` when nothing was
+  recorded, `warn` naming the reason and engine when every session was skipped
+  or failed for an infrastructure reason (`llm_unavailable`, `read_failed`,
+  `exception`, `locked_concurrent`), otherwise `pass` with per-outcome counts.
+- **Every passthrough success envelope carries `ok: true` (#918).**
+  `akm config set` and `akm config unset` printed the resulting config with no
+  `ok` field while their failure envelope had `ok: false`, so a caller
+  branching on `.ok` read success as failure. The shared passthrough stamp now
+  adds `ok: true` when a result has no `ok` of its own; commands whose exit
+  code grades the outcome (`task sync`, `task sync --dry-run`, `task prune`,
+  `workflow run`, `upgrade`, and the `migrate` subcommands) set `ok` and the
+  exit code from the same value, so the two cannot disagree. `--silent` still
+  prints nothing.
+- **The unsupported-plan error names the real situation (#919).** A frozen
+  workflow plan with an `irVersion` above the current one no longer reports
+  "pre-irVersion-5 ... after the 0.9.2 upgrade"; it says the plan was probably
+  written by a newer akm. The reported `irVersion 111` did not reproduce
+  against this tree (the column is only ever written as `5` and no path
+  rewrites it on a source edit); a regression test pins that editing a
+  workflow source leaves its in-flight run executable.
+
+### Fixed
+
+- **`akm proposal accept` no longer rewrites your content.** Two "repairs" ran
+  before validation: one deleted every body line matching `description:` or
+  `when_to_use:`, the other deleted every `---` in a body that had
+  frontmatter. Both fired inside fenced code blocks, so any asset documenting
+  frontmatter — a note about akm, Claude Code skills, Jekyll, Hugo — was
+  silently gutted on accept, and the rewritten bytes were saved back over the
+  original in the proposals database. Nothing was printed. Both repairs are
+  gone; the truncated-description repair, which only ever rewrote a
+  frontmatter value, stays.
+- **Prose-quality findings no longer block `proposal accept`.** A description
+  that read like a heading, an odd number of backticks, or a reflect revision
+  outside the size ratio refused the promotion and told the user to "fix the
+  proposal payload and try again" — but there is no `akm proposal edit` and
+  `accept` has no `--force`, so the only way out was hand-editing the
+  proposals database. These findings are now reported as warnings on a
+  command a human typed. Structural defects that genuinely cannot be written
+  (empty content, an unparseable ref, malformed frontmatter, a broken
+  workflow shape) still block.
+- **akm no longer refuses to open a state database migrated by a newer akm.**
+  Two akm versions sharing one data directory is a supported deployment — a
+  bundled CLI beside a newer global install — and the old binary was bricked
+  for every command that touches `state.db`, not degraded. It protected
+  nothing: an older binary's entire migration registry is already applied, so
+  it has no pending migration to run. It now opens, warns once naming the
+  migrations it does not know, and reads and writes the tables it knows. A
+  ledger that genuinely diverges (a migration this akm has was never applied
+  and something else was applied in its place) is still refused.
+- **`akm agent --prompt` no longer rejects prose that looks like a template.**
+  A prompt was validated as if it were a portable command template, so any
+  prompt containing `}}` from compact JSON, a `$VAR`, a `${...}`, a `$(...)`
+  shell snippet, an `@path`, or a `` !` `` was rejected with "unsupported
+  portable template construct" before the agent started. akm substitutes
+  nothing into a prompt, so it is now sent verbatim. The template language is
+  unchanged for stored command files, which are templates.
+
+- **The 0.9.2 `claude-code` -> `claude` harness rename left the ledgers split
+  (#915).** State migration `027-extract-sessions-seen-harness-rename` moves
+  `extract_sessions_seen` and `workflow_runs.agent_harness` rows off the old
+  key, keeping a session already recorded under `claude` as the authoritative
+  row, and empties the old key space. `PERSISTED_HARNESS_IDS` in the harness
+  registry is now pinned by a test so the next rename cannot ship without a
+  migration. Scripts querying the ledger by `claude-code` will find it empty
+  after upgrade; see the 0.9.1 -> 0.9.2 migration guide.
+
+### Changed — refusals that now degrade
+
+A repo-wide audit reviewed every defensive refusal in the codebase against
+three tests: has it demonstrably helped a real user, does its failure mode cost
+less than the hazard it guards, and is the hazard already gated behind a
+deliberate human command. Refusals that failed those tests were removed or
+downgraded to a warning, in that order of preference. Machinery that prevents
+data loss or corruption — atomic writes, backups, write-path validation, path
+containment — was explicitly out of scope and is unchanged.
+
+The user-visible effect is that akm stops aborting on conditions it can
+survive. Highlights:
+
+- **Config load no longer bricks every command over one bad key.** Retired
+  vocabulary (`profiles`, `llm`, `agent`, `features`, `stashes`,
+  `modelAliases`, `bindings`, top-level `writable`) warns and passes through,
+  and the pre-`bundles` `stashDir`/`sources[]`/`installed[]` shape folds into
+  the current shape in memory. An unknown `config set` key warns and stores.
+- **A newer or unfamiliar state.db migration ledger no longer refuses to
+  open.** A ledger carrying migrations this binary does not know warns once and
+  degrades; only a genuinely inconsistent ledger still aborts. This is what let
+  a bundled older akm keep working against a newer host's data directory.
+  A `plan_ir_version` of NULL (a row predating the column) decodes normally.
+- **Free text is no longer validated as code.** `akm agent` accepts prompts
+  containing `{{`/`}}`; inline workflow `akm/command` content and portable
+  command templates accept `$HOME`, `@file`, `${...}` and the rest as the prose
+  they are. Only `$ARGUMENTS[N]`, which merely looks like the one placeholder
+  akm expands, still warns.
+- **Version skew stops being treated as corruption.** A newer index is left
+  alone rather than wiped, a stale indexed workflow identity falls back, and
+  frozen-plan spine drift from a formatting change between releases warns
+  instead of marking every in-flight run corrupt.
+- **Deliberate commands stop being second-guessed.** `--since` bypasses
+  `extract`'s per-run cap the way `--force` already did; `workflow create
+  --force` no longer also demands `--reset`; scheduler writes, `setup --dir`
+  and `bundle create --dir` under transient paths warn instead of refusing.
+- **Symlinks are followed on read paths** (task sources, `models.json`, stash
+  meta, `akm.include` entries) with realpath containment doing the actual
+  safety work, rather than being refused outright.
+- **Blocks that had no escape hatch got one, or got removed.** `env run` gained
+  `--allow-insecure` for the third-party dangerous-key block that previously
+  had no bypass; `registry add` accepts a credentialed URL with a warning that
+  redacts the credential; promotion lint findings on `proposal accept` report
+  instead of blocking, since there is no `proposal edit` and no `accept
+  --force` to work around them.
+- **Limits that bounded nothing real were deleted.** Workflow plan and embedded
+  child-plan byte caps, step-evidence tombstoning, search-text truncation, and
+  the JSON-schema node budget are gone; the akm.lock acquisition budget went
+  from 300 ms to ~30 s with backoff and a "waiting for another akm process"
+  notice.
+- **A cron line too long for vixie-cron now spills into a wrapper script**
+  instead of refusing the install. The length limit stays, because a truncated
+  cron line would execute a partial command.
+
+Guards that passed the three tests were kept and documented, including the
+registry-URL credential inspection limit, the third-party dangerous-key block
+itself, `MAX_SCHTASKS_TRIGGERS`, and every path-containment check.
+
+## [0.9.11] - 2026-09-03
+
+### Added
+
+- **`akm task validate <path>` reports what `akm task sync` would say about one
+  task file (#907).** It parses a single file by filesystem path, without a
+  bundle, a concept ref, or a configured engine, and reports `valid`,
+  `converts` (a v2/v3 source the migrator converts deterministically),
+  `blocked` (needs a human decision), `invalid`, or `not-a-task`, with the
+  reason sync would give. It runs the same two gates sync runs before
+  installing a schedule, the defaults-applied schedule input contract and
+  the cron dialect check, which are now shared with `compileTaskSources` so
+  the two commands cannot drift. Exit 0 for valid/converts, 1 for the rest,
+  2 for a missing or unreadable path. `resolved` on success is the compiled
+  task shape (id, version, target, inputs, schedule), never an
+  execution-lowered plan.
+- **`engines.<name>.apiKeyFile` supplies an LLM engine credential from a file
+  (#905).** A host that refuses secrets in the process environment can point
+  an engine at a path instead of a `$VAR` reference: `~` expands, one
+  trailing newline is trimmed, the file is read only at dispatch, and a
+  missing or empty file is a config error naming the engine and path but
+  never the value. Setting both `apiKey` and `apiKeyFile` is rejected;
+  setting neither still falls through to the implicit
+  `AKM_ENGINE_<NAME>_API_KEY` convention. The value is redacted from
+  dispatch output the same way an env-backed credential is, and `akm health`
+  checks the file is present and non-empty.
+
+### Changed
+
+- **`akm improve`'s machine-local writers moved out of `$STASH/.akm` into
+  `$STATE` and `$CACHE` (#890).** `distill-rejected/`, `eval-cases/`,
+  `measurement/verdicts/`, the synthetic `unresolved-sources/` placeholder,
+  and the improve-pipeline lock files never met the "must travel with the
+  content" rule; they now live under `$STATE/improve/…/<stash>/`,
+  `$CACHE/index/unresolved-sources/<stash>/`, and `$STATE/locks/<stash>/`,
+  namespaced by a short hash of the resolved stash path. `akm migrate
+  status` and `apply` gain a relocation step that covers the default stash
+  and every other filesystem-backed bundle (remote sources are skipped
+  without a network call), moves files by rename or copy-then-delete, and
+  deletes an old lock only when the same staleness check `akm improve` uses
+  says its holder is dead; a live lock is left in place and reported. The
+  step is idempotent and `--dry-run` moves nothing. Scripts that read the
+  old paths should switch to the new locations named in
+  `docs/architecture/internals/storage-locations.md`.
+
+### Fixed
+
+- **The dead-link check states its coverage and no longer lies about it
+  (#892).** `akm improve`'s post-loop check scanned at most ten knowledge
+  refs and fired every HEAD request at once with no timeout. It now scans
+  every actionable ref, checks at a bounded concurrency, bounds each request
+  at five seconds and reports a timeout as a dead entry, and counts a DNS or
+  connection failure as skipped rather than as dead or as fine. The result
+  carries `checked`, `total`, and `skipped`, threaded into the improve
+  result, the `improve_completed` event, and `akm health`'s improve summary.
+  The other constants the issue names (`MAX_URLS`, the per-entry slice,
+  `MAX_BODY_CHARS`, the duplicated `MAX_CONTENT_CHARS`) were already removed
+  in 0.9.8, and the curate score floors only decide whether a second search
+  pass runs; they never filter returned results.
+
 ## [0.9.10] - 2026-09-02
 
 ### Fixed

package/STABILITY.md

@@ -112,6 +112,7 @@ enumeration of the whole `proposal` noun group.
 | `akm task sync` | Evolving | |
 | `akm task doctor` | Evolving | |
 | `akm task explain` | Evolving | New in 0.9.2; secret-shaped values in provenance output are redacted on a best-effort heuristic basis (not a guarantee). |
+| `akm task validate` | Evolving | New in 0.9.11; read-only, and the only `task` subcommand that takes a bare filesystem path instead of a ref — the file need not belong to any configured bundle. |
 
 ## Stable
 
@@ -218,6 +219,10 @@ enumeration of the whole `proposal` noun group.
   | `4` | Health warning (`akm health` only) |
   | `70` | Internal / unclassified |
   | `78` | Configuration error |
+
+  **From 0.9.12**, every success envelope produced by the passthrough stamp
+  (`config`, `clone`, `models`, `task-*`, `workflow-*`, `registry-*`, …) also
+  carries `ok: true`; a command that already computes its own `ok` keeps it.
 - **Install scripts** — `install.sh` and `install.ps1` URLs; the `--prefix`
   / `AKM_INSTALL_DIR` environment override.
 - **Runtime** — the npm package requires Node.js >= 22 as its bootstrap and
@@ -256,21 +261,28 @@ CHANGELOG with a migration note.
   `akm improve && akm proposal drain --promote --yes`, or a `triage` block
   with `applyMode: "promote"` in your strategy.
 - **Tasks** — `akm task` subcommand surface (`add | run | sync | doctor |
-  history | explain`; no alias, no `list`/`remove`/`init`/`enable`/`disable`);
-  task source v4 YAML (typed `inputs:`, optional `schedule:`) is the only
-  accepted version — task v3 and task v2 sources are converted by
-  `akm migrate apply`. Command tasks use named engines and task history
-  metadata is versioned. Schema additions in patch releases; removals only at
-  minor. Bare `akm task` is a usage error naming the subcommands
-  (`akm task doctor` reports scheduler diagnostics). `akm task explain <ref>`
-  (new in 0.9.2) and `akm workflow plan <ref>` are both zero-write
-  provenance surfaces: they show what a task or workflow would do —
-  resolved target, input bindings, child expansion — without starting or
-  publishing a run. `akm workflow plan` is secret-free **by construction**
-  (the excluded data never reaches the command). `akm task explain`
-  instead **redacts** secret-shaped input values on a best-effort
+  history | explain | validate`; no alias, no
+  `list`/`remove`/`init`/`enable`/`disable`); task source v4 YAML (typed
+  `inputs:`, optional `schedule:`) is the only accepted version — task v3 and
+  task v2 sources are converted by `akm migrate apply`. Command tasks use
+  named engines and task history metadata is versioned. Schema additions in
+  patch releases; removals only at minor. Bare `akm task` is a usage error
+  naming the subcommands (`akm task doctor` reports scheduler diagnostics).
+  `akm task explain <ref>` (new in 0.9.2) and `akm workflow plan <ref>` are
+  both zero-write provenance surfaces: they show what a task or workflow
+  would do — resolved target, input bindings, child expansion — without
+  starting or publishing a run. `akm workflow plan` is secret-free **by
+  construction** (the excluded data never reaches the command). `akm task
+  explain` instead **redacts** secret-shaped input values on a best-effort
   heuristic basis — a value that doesn't match the heuristic can still
-  print unredacted.
+  print unredacted. `akm task validate <path>` (new in 0.9.11) is the same
+  kind of zero-write introspection as `explain`, but takes a bare filesystem
+  path rather than a bundle-qualified ref — it reports whether that ONE file
+  would parse cleanly (`valid`), auto-convert from task v2/v3 (`converts`),
+  need a human decision the deterministic migrator can't make (`blocked`),
+  fail schema validation (`invalid`), or isn't a task source at all
+  (`not-a-task`) — exactly the diagnostic `akm task sync` would produce for
+  it, before the file is ever wired into a bundle or the scheduler.
 - **Workflow plan** — `akm workflow plan <ref>`, new in 0.9.2: zero-write
   compile+freeze introspection (the canonical step graph, task/child
   expansion, input bindings, and lowering notices for a workflow, without
@@ -431,7 +443,6 @@ on them.
 | `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode (network filesystems) |
 | `AKM_BIN` | Absolute `akm` path for scheduler registration |
 | `AKM_INSTALL_DIR` | Install-script prefix |
-| `AKM_FORCE_SETUP_TMP_STASH` | Documented escape hatch for intentional temp-directory bundles |
 | `AKM_UPGRADE_SKIP_CHECKSUM` | Recovery hatch for a broken upgrade checksum |
 
 **Internal** — no compatibility guarantee, may vanish without notice:
@@ -473,6 +484,8 @@ lives in this repo). **D3** shipped too, in the end: `akm mv` was removed in
 0.9.0 (see the Renames bullet above), with `scripts/rekey-asset-ref.ts` as the
 Internal replacement for the one capability nothing else covered.
 
+- **0.10 — `config set`/`config unset` may drop the config dump** in favor of
+  a compact `{ok, shape, key}` result; `akm config list` remains the full read.
 - **0.10 — migration extraction.** The migration machinery leaves the CLI for
   a separately published `akm-migrate` package (see Internal above).
 - **0.10 — `--auto-accept` hard error.** It is currently accepted-and-warned;

package/dist/assets/hints/cli-hints-full.md

@@ -414,7 +414,7 @@ Result-envelope commands accept `--format`, `--detail`, and `--shape` flags:
 - `--detail full` — includes scores, paths, timing, debug info
 - `--shape human` (default) — standard projection
 - `--shape agent` — agent-optimized output: strips non-actionable fields
-- `--shape summary` — metadata only (no content/template/prompt), under 200 tokens; only valid on `akm show`
+- `--shape summary` — metadata only (no content/template/prompt), under 200 tokens; only `akm show` has a dedicated summary projection — elsewhere it falls back to `agent` with a warning
 
 Run `akm help <command>` or `akm <command> -h` for per-command help. Run
 `akm --help` for the sectioned command overview.

package/dist/assets/improve-strategies/consolidate.json

@@ -3,7 +3,7 @@
   "processes": {
     "reflect": { "enabled": false },
     "distill": { "enabled": false },
-    "consolidate": { "enabled": true, "allowedTypes": ["memory"], "maxChunkSize": 25, "minPoolSize": 500 },
+    "consolidate": { "enabled": true, "allowedTypes": ["memory"], "maxChunkSize": 25 },
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },

package/dist/assets/improve-strategies/default.json

@@ -7,7 +7,7 @@
       "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"]
     },
     "distill": { "enabled": true, "allowedTypes": ["memory"], "requirePlannedRefs": true },
-    "consolidate": { "enabled": true, "allowedTypes": ["memory"], "minPoolSize": 500 },
+    "consolidate": { "enabled": true, "allowedTypes": ["memory"] },
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": true },
     "extract": { "enabled": false, "triage": { "enabled": true, "minScore": 2 } },

package/dist/assets/improve-strategies/thorough.json

@@ -13,8 +13,7 @@
     },
     "consolidate": {
       "enabled": true,
-      "allowedTypes": ["memory"],
-      "minPoolSize": 500
+      "allowedTypes": ["memory"]
     },
     "memoryInference": {
       "enabled": true

package/dist/cli/shared.js

@@ -150,13 +150,14 @@ export const GLOBAL_OUTPUT_ARGS = {
     // R-050(c): single-sourced with the root command's own `--shape` help
     // (`main.args.shape` in src/cli.ts, which spreads this object) so the
     // caveat is visible from every leaf's own `--help`, not only the top-level
-    // one. `summary` outside `show` is a hard usage error (exit 2,
-    // INVALID_SHAPE_VALUE), enforced at startup in src/cli.ts before any
-    // command body runs.
+    // one. `summary` outside `show` falls back to `agent` with a warning
+    // (shapeForCommand in src/output/shapes.ts) — `--shape` is a global flag,
+    // so a script that passes it to a mixed batch of commands still works.
     shape: {
         type: "string",
         description: "Output projection: human|agent|summary (global flag). 'agent' trims to agent-essential fields; " +
-            "'summary' is only valid on 'akm show' (a usage error, exit 2, everywhere else). Default: human.",
+            "'summary' only has a dedicated projection on 'akm show' — elsewhere it falls back to 'agent' with a " +
+            "warning. Default: human.",
     },
     output: {
         type: "string",
@@ -269,6 +270,17 @@ export function defineGroupCommand(def) {
  * document is written to that file instead of stdout (jsonl excepted — it is
  * a line-streaming protocol and always goes to stdout).
  */
+/**
+ * Emit a result whose success is graded by an exit code. `ok` on the envelope
+ * and `process.exitCode` are set from the same value here, so the two cannot
+ * disagree (#918); `exitCode` undefined or 0 means success.
+ */
+export function outputWithExitCode(command, result, exitCode) {
+    const failed = exitCode !== undefined && exitCode !== EXIT_CODES.SUCCESS;
+    output(command, { ...result, ok: !failed });
+    if (failed)
+        process.exitCode = exitCode;
+}
 export function output(command, result) {
     const mode = getOutputMode();
     const shaped = shapeForCommand(command, result, mode.detail, mode.shape);

package/dist/cli.js

@@ -57,7 +57,7 @@ process.on("uncaughtException", (err) => {
 });
 import fs from "node:fs";
 import { defineCommand, parseArgs, renderUsage, runCommand, showUsage } from "citty";
-import { findCittyTopLevelCommand, findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
+import { findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
 import { retiredCommandHint } from "./cli/retired-commands.js";
 import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "./cli/shared.js";
 import { assertKnownFlags, closestMatch } from "./cli/unknown-flags.js";
@@ -284,6 +284,18 @@ const healthCommand = defineCommand({
             description: "Fetch the full report dataset: per-run rows, trend deltas vs the prior window, and the pending proposal queue. Renders as the rich report under --format md/html and as complete data under any other format.",
             default: false,
         },
+        // #914: citty strips any `--no-X` argument and treats it as negating `X`
+        // (see `parseArgs` in citty's dist), regardless of whether an arg literally
+        // named "no-X" is declared — declaring "no-probe" directly would silently
+        // never populate `args["no-probe"]` and the flag would do nothing. Declare
+        // the positive flag instead; `--no-probe` is citty's automatic negation of
+        // it (rendered in `--help` via `negativeDescription`).
+        probe: {
+            type: "boolean",
+            default: true,
+            description: "Probe default-llm-engine / configured-engines reachability (on by default).",
+            negativeDescription: "Skip the reachability probes (for an offline or air-gapped host).",
+        },
     },
     async run({ args }) {
         let resultStatus;
@@ -316,11 +328,12 @@ const healthCommand = defineCommand({
             const sinceIsDuration = args.since !== undefined && parseDuration(args.since, DURATION_UNITS) !== null;
             const implicitCompare = explicitWindows ? undefined : ((sinceIsDuration ? args.since : undefined) ?? "24h");
             const windowCompare = report ? (args["window-compare"] ?? implicitCompare) : args["window-compare"];
-            const base = akmHealth({
+            const base = await akmHealth({
                 since: args.since,
                 groupBy: report ? "run" : groupBy,
                 windowCompare,
                 windows,
+                probe: args.probe !== false,
             });
             const reportCompare = windowCompare ??
                 (explicitWindows
@@ -945,18 +958,7 @@ async function runCli() {
         emitJsonError(error);
         return;
     }
-    // `--shape summary` is only meaningful on `akm show`. Reject it up front for
-    // every other command so a write command (e.g. `akm proposal accept …`)
-    // fails fast BEFORE performing its mutation, rather than throwing at
-    // output-shaping time after the side effect has already happened. The
-    // shape-registry gate in shapeForCommand() remains as defense-in-depth (and
-    // covers the in-process test harness, which skips this startup block).
     const commandPath = resolveCittyCommandPath(main, process.argv.slice(2));
-    const topLevelCommand = commandPath[0] ?? findCittyTopLevelCommand(process.argv.slice(2), MAIN_TOP_LEVEL_ARGS);
-    if (getOutputMode().shape === "summary" && topLevelCommand !== "show") {
-        emitJsonError(new UsageError("'--shape summary' is only valid on 'akm show'.", "INVALID_SHAPE_VALUE"));
-        return;
-    }
     // D7 — every command that renders through output() honours all six --format
     // values. The declared exempt set (src/output/format-exempt.ts) does not
     // render an envelope at all, so warn rather than pretend: silently ignoring

package/dist/commands/agent/agent-dispatch.js

@@ -32,10 +32,18 @@ function rejectInvalidAgentRef(agentRef) {
         return;
     throw new UsageError(`agent expects an agent asset ref under agents/...; received ${JSON.stringify(agentRef)}.`, "INVALID_FLAG_VALUE");
 }
+/**
+ * Dispatch a `--prompt` / `--prompt-stdin` task through the canonical command
+ * path. The prompt is a person's free text, not a template: it is sent to the
+ * agent verbatim (`inlineContentMode: "literal"`), so prose containing `}}`
+ * from compact JSON, a `$VAR`, a shell snippet, or an `@path` reaches the
+ * agent instead of being rejected as an unsupported template construct.
+ */
 async function delegateCanonicalCommand(options, seams, action) {
     const execute = seams.executeCommand ?? executeCommandInvocation;
     const result = await execute({
         action,
+        inlineContentMode: "literal",
         config: options.agentConfig,
         current: canonicalCurrent(options),
     });

package/dist/commands/command/execution-source-loader.js

@@ -10,6 +10,7 @@ import { isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { bundleComponentConfig, bundlesToSourceEntries } from "../../core/config/config-sources.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { warnOnce } from "../../core/warn.js";
 import { lookupBundleRef } from "../../indexer/indexer.js";
 import { deriveInstallations } from "../../indexer/installations.js";
 import { resolveEntryContentDir, resolveSourceEntries } from "../../indexer/search/search-source.js";
@@ -66,10 +67,10 @@ function implicitComponentForEntry(entry, config, realRoot) {
             continue;
         const canonicalRoot = realDirectory(component.root, `Canonical implicit source root for ${entry.bundleId}`);
         if (canonicalRoot !== realRoot) {
-            throw new ConfigError(`Canonical implicit source root drift for ${JSON.stringify(entry.itemRef)}; the indexed root no longer matches the working bundle source.`, "INVALID_CONFIG_FILE", "Run `akm index --full` after changing AKM_BUNDLE_DIR or the default bundle directory.");
+            warnOnce(`execution-source-root-drift:${entry.itemRef}`, `[command] Indexed root for ${JSON.stringify(entry.itemRef)} no longer matches the working bundle source; re-resolving from live config. Run \`akm index --full\` to refresh it.`);
         }
         if (component.adapter !== entry.adapterId) {
-            throw new ConfigError(`Implicit adapter drift for ${JSON.stringify(entry.itemRef)}: the index records ${JSON.stringify(entry.adapterId)} but the canonical working source selects ${JSON.stringify(component.adapter)}.`, "INVALID_CONFIG_FILE", "Run `akm index --full` after changing the working source adapter.");
+            warnOnce(`execution-source-adapter-drift:${entry.itemRef}`, `[command] Indexed adapter ${JSON.stringify(entry.adapterId)} for ${JSON.stringify(entry.itemRef)} no longer matches the working source's adapter ${JSON.stringify(component.adapter)}; re-resolving from live config. Run \`akm index --full\` to refresh it.`);
         }
         return Object.freeze({
             id: installation.id,
@@ -91,31 +92,33 @@ function componentForEntry(entry, config, realRoot) {
     const component = bundleComponentConfig(configured);
     const configuredAdapter = component?.adapter;
     if (configuredAdapter && configuredAdapter !== entry.adapterId) {
-        throw new ConfigError(`Configured adapter drift for ${JSON.stringify(entry.itemRef)}: the index records ${JSON.stringify(entry.adapterId)} but the bundle config selects ${JSON.stringify(configuredAdapter)}.`, "INVALID_CONFIG_FILE", "Run `akm index --full` after changing a bundle adapter.");
+        warnOnce(`execution-source-adapter-drift:${entry.itemRef}`, `[command] Indexed adapter ${JSON.stringify(entry.adapterId)} for ${JSON.stringify(entry.itemRef)} no longer matches the bundle config's adapter ${JSON.stringify(configuredAdapter)}; re-resolving from live config. Run \`akm index --full\` to refresh it.`);
     }
     const configuredSource = bundlesToSourceEntries(config)?.find((source) => source.name === entry.bundleId);
     const configuredContentRoot = configuredSource ? resolveEntryContentDir(configuredSource) : undefined;
     if (!configuredSource || !configuredContentRoot) {
-        throw new ConfigError(`Configured source for ${JSON.stringify(entry.itemRef)} no longer resolves to materialized content.`, "INVALID_CONFIG_FILE", "Restore or update the bundle, then run `akm index --full` before dispatching this asset.");
+        warnOnce(`execution-source-unresolved:${entry.itemRef}`, `[command] Configured source for ${JSON.stringify(entry.itemRef)} no longer resolves to materialized content; dispatching from the indexed location instead. Run \`akm index --full\` after restoring or updating the bundle.`);
     }
-    const lexicalSourceRoot = path.resolve(configuredContentRoot);
-    const lexicalConfiguredRoot = path.resolve(configuredContentRoot, component?.root ?? ".");
-    if (!isLexicallyWithin(lexicalConfiguredRoot, lexicalSourceRoot)) {
-        throw new ConfigError(`Configured component root for ${JSON.stringify(entry.itemRef)} resolves outside its materialized bundle source.`, "INVALID_CONFIG_FILE", "Keep component roots inside their owning bundle source, then run `akm index --full`.");
-    }
-    const configuredSourceRoot = realDirectory(lexicalSourceRoot, `Configured source root for ${entry.bundleId}`);
-    let configuredRoot;
-    try {
-        configuredRoot = realDirectory(lexicalConfiguredRoot, `Configured component root for ${entry.bundleId}`);
-    }
-    catch {
-        throw new ConfigError(`Configured ${JSON.stringify(configuredSource.type)} source for ${JSON.stringify(entry.itemRef)} is not materialized at its current component root.`, "INVALID_CONFIG_FILE", "Restore or update the bundle, then run `akm index --full` before dispatching this asset.");
-    }
-    if (!isWithin(configuredRoot, configuredSourceRoot)) {
-        throw new ConfigError(`Configured component root for ${JSON.stringify(entry.itemRef)} resolves outside its materialized bundle source.`, "INVALID_CONFIG_FILE", "Remove the escaping symlink or component path, then run `akm index --full`.");
-    }
-    if (configuredRoot !== realRoot) {
-        throw new ConfigError(`Configured source or component root drift for ${JSON.stringify(entry.itemRef)}; the indexed root no longer matches the ${JSON.stringify(configuredSource.type)} bundle source.`, "INVALID_CONFIG_FILE", "Run `akm index --full` after changing a bundle source or component root.");
+    else {
+        const lexicalSourceRoot = path.resolve(configuredContentRoot);
+        const lexicalConfiguredRoot = path.resolve(configuredContentRoot, component?.root ?? ".");
+        if (!isLexicallyWithin(lexicalConfiguredRoot, lexicalSourceRoot)) {
+            throw new ConfigError(`Configured component root for ${JSON.stringify(entry.itemRef)} resolves outside its materialized bundle source.`, "INVALID_CONFIG_FILE", "Keep component roots inside their owning bundle source, then run `akm index --full`.");
+        }
+        const configuredSourceRoot = realDirectory(lexicalSourceRoot, `Configured source root for ${entry.bundleId}`);
+        let configuredRoot;
+        try {
+            configuredRoot = realDirectory(lexicalConfiguredRoot, `Configured component root for ${entry.bundleId}`);
+        }
+        catch {
+            throw new ConfigError(`Configured ${JSON.stringify(configuredSource.type)} source for ${JSON.stringify(entry.itemRef)} is not materialized at its current component root.`, "INVALID_CONFIG_FILE", "Restore or update the bundle, then run `akm index --full` before dispatching this asset.");
+        }
+        if (!isWithin(configuredRoot, configuredSourceRoot)) {
+            throw new ConfigError(`Configured component root for ${JSON.stringify(entry.itemRef)} resolves outside its materialized bundle source.`, "INVALID_CONFIG_FILE", "Remove the escaping symlink or component path, then run `akm index --full`.");
+        }
+        if (configuredRoot !== realRoot) {
+            warnOnce(`execution-source-root-drift:${entry.itemRef}`, `[command] Indexed root for ${JSON.stringify(entry.itemRef)} no longer matches the ${JSON.stringify(configuredSource.type)} bundle source; re-resolving from live config. Run \`akm index --full\` to refresh it.`);
+        }
     }
     const writable = component?.writable ?? configured.writable ?? configured.path !== undefined;
     return Object.freeze({

package/dist/commands/command/portable-template.js

@@ -1,22 +1,9 @@
 // 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 { UsageError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
 export const PORTABLE_ARGUMENTS_PLACEHOLDER = "$ARGUMENTS";
-const UNSUPPORTED_TEMPLATE_CONSTRUCTS = Object.freeze([
-    { label: "$ARGUMENTS[N]", pattern: /\$ARGUMENTS\s*\[/u },
-    { label: "```! ... ```", pattern: /(?:^|\r?\n)[\t ]*```!/u },
-    { label: "!`...`", pattern: /!`/u },
-    { label: "@file", pattern: /(?<![A-Za-z0-9._%+-])@(?:\.{0,2}\/)?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*/u },
-    { label: "$" + "{...}", pattern: /\$\{/u },
-    { label: "$(...)", pattern: /\$\(/u },
-    { label: "$N", pattern: /\$\d/u },
-    { label: "$NAME", pattern: /\$[A-Za-z_][A-Za-z0-9_]*/u },
-    { label: "{{...}}", pattern: /\{\{|\}\}/u },
-]);
-function unsupportedTemplate(source, label) {
-    return new UsageError(`Command ${JSON.stringify(source)} uses unsupported portable template construct ${label}.`, "INVALID_FLAG_VALUE", `AKM command execution supports only the literal ${PORTABLE_ARGUMENTS_PLACEHOLDER} placeholder. Invoke native-only templates through their owning tool instead.`);
-}
+const INDEXED_ARGUMENTS_PATTERN = /\$ARGUMENTS\s*\[/u;
 /**
  * Validate the deliberately small portable command-template language.
  *
@@ -28,17 +15,8 @@ export function validatePortableCommandTemplate(template, source) {
         throw new TypeError("command template must be a string");
     if (typeof source !== "string" || source.length === 0)
         throw new TypeError("command source must be a string");
-    // Check native extensions of the portable spelling before masking the one
-    // supported token. AKM never interprets indexed native placeholders.
-    const indexedArguments = UNSUPPORTED_TEMPLATE_CONSTRUCTS[0];
-    if (indexedArguments?.pattern.test(template))
-        throw unsupportedTemplate(source, indexedArguments.label);
-    // Mask only the exact portable token. Everything else remains visible to the
-    // unsupported-construct detectors, including `$ARGUMENTS_SUFFIX`.
-    const portableMasked = template.replace(/\$ARGUMENTS(?![A-Za-z0-9_])/gu, "");
-    for (const construct of UNSUPPORTED_TEMPLATE_CONSTRUCTS.slice(1)) {
-        if (construct.pattern.test(portableMasked))
-            throw unsupportedTemplate(source, construct.label);
+    if (INDEXED_ARGUMENTS_PATTERN.test(template)) {
+        warn(`Command ${JSON.stringify(source)} uses "$ARGUMENTS[N]", which akm does not support. Only the literal $ARGUMENTS placeholder is expanded; the indexed form is left as-is.`);
     }
 }
 /**