akm-cli 0.9.11 → 0.9.13

package/CHANGELOG.md

@@ -4,6 +4,233 @@ 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.13] - 2026-09-04
+
+### Added
+
+- **A stable `results` alias on every list-returning command (#922).** `search`,
+  `curate`, `proposal list`, `bundle list`, `env list`, `secret list`,
+  `registry search`, `registry list`, `workflow list`, `task history` and
+  `log list` each keep their existing semantic key (`hits`, `items`,
+  `proposals`, …) and now also expose the same array as `results`, in every
+  shape including `--shape agent`. It is the same array, not a copy. A caller
+  reading `hits` from a `curate` response previously got nothing back and could
+  reasonably read that as "no results" — there was no error and the `summary`
+  alongside it still reported that results were selected. Commands carrying
+  several heterogeneous collections (`health`, `task doctor`) are deliberately
+  excluded.
+- **Engine and embedding credentials can resolve from the secret store
+  (#917).** `apiKey` accepts `secret://<name>` alongside `$VAR` / `${VAR}`,
+  resolved through the existing store-backed resolver. A detached SessionEnd
+  hook or a cron job — the two contexts least able to supply an environment
+  variable and most likely to need extraction — no longer requires editing the
+  login environment for a value akm already stores. Literal keys in
+  `config.json` are still refused, and an unresolvable reference fails loudly,
+  naming the reference and never the secret.
+- **`akm proposal drain` reports what failed (#921).** The envelope carries a
+  `failed[]` naming each proposal and why it was refused (stale target,
+  validation), instead of reporting `failed: 0` while the same run printed five
+  failures to stderr. `--dry-run` now applies the same stale-target check the
+  real run does, so its prediction stops disagreeing with the outcome. The
+  refusals themselves are correct and unchanged: declining to overwrite a target
+  modified since the proposal was created is the desired behaviour. `akm
+  improve`'s triage pre-pass reports the same count.
+- **Workflow step output is checked against its declared schema (#923).** A step
+  whose returned object does not match its `outputSchema` now says so, naming
+  the step and the specific problem (a missing required field, say). This is a
+  warning: the run continues and its status is unchanged, because a workflow is
+  a guide rather than a contract. Previously an author got neither enforcement
+  nor feedback — the only signal was a notice saying akm was not checking, which
+  is a different fact from whether the output matched.
+
+### Changed
+
+- **A held run lease no longer reports as database corruption (#924).** `akm
+  workflow run` surfaced raw SQLite text — `database is locked`, `database disk
+  image is malformed`, `disk I/O error` — for what was simply another
+  invocation holding the lease. `disk image is malformed` in particular reads as
+  data loss and sent one reporter through integrity checks and a WAL review
+  before finding the real cause. The lease message now appears at default
+  verbosity and carries a dedicated `RUN_LEASE_HELD` code, so a wrapper can tell
+  "retry shortly" from "you passed bad input". Genuine SQLite errors still
+  report as themselves.
+- **`akm lint` stops flagging templated output paths (#927).** A documented
+  run-time filename such as `reports/review-<timestamp>.md` is no longer
+  reported as a `stale-path` broken reference. Angle-bracket and brace
+  placeholders, `${VAR}`, date-format runs like `YYYYMMDD`, and glob characters
+  are all recognised as parameterised rather than missing. Genuinely broken
+  literal paths are still reported.
+- **The workflow level-2 heading rule is discoverable before you trip it
+  (#926).** The `workflow create` template states that `##` headings are step
+  ids and points at `###` for cross-cutting notes, and the compiler's rejection
+  now carries the remedy rather than only the diagnosis.
+
+## [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

package/STABILITY.md

@@ -219,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
@@ -439,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:
@@ -481,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/assets/workflows/workflow-template.md

@@ -16,6 +16,10 @@ steps:
 Free preamble prose describing what this workflow does. It is indexed for
 search and shown in `akm show`, but it is never dispatched to a step.
 
+Level-2 (`##`) headings below are step ids and must exactly match one
+declared in `steps:` above — for cross-cutting notes that aren't a step
+(shared context, prerequisites), use a level-3 (`###`) heading instead.
+
 ## first-step
 
 Describe what to do in this step. Refer to run parameters in plain

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.`);
     }
 }
 /**

package/dist/commands/config-cli.js

@@ -111,7 +111,10 @@ export const configCommand = defineGroupCommand({
             },
         }),
         set: defineJsonCommand({
-            meta: { name: "set", description: "Set a configuration value by key" },
+            meta: {
+                name: "set",
+                description: "Set a configuration value by key; prints the resulting config with ok: true",
+            },
             args: {
                 key: {
                     type: "positional",
@@ -124,7 +127,7 @@ export const configCommand = defineGroupCommand({
                 // writes don't pollute their host's output stream.
                 silent: {
                     type: "boolean",
-                    description: "Suppress the post-write config dump on stdout. Use from hooks and CI scripts; the write still happens and errors still print.",
+                    description: "Suppress the post-write config dump on stdout entirely (prints nothing; exit code is the status). Use from hooks and CI scripts; the write still happens and errors still print.",
                     default: false,
                 },
             },
@@ -136,12 +139,15 @@ export const configCommand = defineGroupCommand({
             },
         }),
         unset: defineJsonCommand({
-            meta: { name: "unset", description: "Unset an optional configuration key or whole embedding/engine section" },
+            meta: {
+                name: "unset",
+                description: "Unset an optional configuration key or whole embedding/engine section; prints the resulting config with ok: true",
+            },
             args: {
                 key: { type: "positional", required: true, description: "Config key to unset" },
                 silent: {
                     type: "boolean",
-                    description: "Suppress the post-write config dump on stdout.",
+                    description: "Suppress the post-write config dump on stdout entirely (prints nothing; exit code is the status).",
                     default: false,
                 },
             },

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

@@ -84,13 +84,20 @@ export function resolveEnvBinding(target, options = {}) {
     const dangerous = keys.filter(isDangerousEnvKey);
     if (dangerous.length > 0) {
         const detail = `Env "${envRef}" injects process-hijacking variable(s): ${dangerous.join(", ")}.`;
-        const decision = decideDangerousEnvInjection({ dangerousKeys: dangerous, thirdParty: Boolean(source.registryId) });
+        const decision = decideDangerousEnvInjection({
+            dangerousKeys: dangerous,
+            thirdParty: Boolean(source.registryId),
+            allowInsecure: options.allowInsecure,
+        });
         if (decision === "block") {
             throw new UsageError(`Refusing to inject env from a third-party stash. ${detail}\n` +
-                `       Review the file, then copy the values into a first-party env if you trust them.`, "INVALID_FLAG_VALUE");
+                `       Review the file, then copy the values into a first-party env if you trust them, ` +
+                `or pass --allow-insecure once you have.`, "INVALID_FLAG_VALUE");
         }
         if (decision === "warn") {
-            warn(`${detail} Injecting anyway (first-party stash).`);
+            warn(options.allowInsecure && source.registryId
+                ? `${detail} Injecting anyway (--allow-insecure).`
+                : `${detail} Injecting anyway (first-party stash).`);
         }
     }
     // Audit trail: keys only, never values.