akm-cli 0.10.261012-beta → 0.10.261013-beta

package/docs/reference/env-and-secrets.md

@@ -19,6 +19,16 @@ command; use `env` or `secret`.
 | Discoverable | key *names* (not values) | name only (the whole file is the value) |
 | Injects | many vars at once (`env run`) | one var (`secret run <ref> <VAR>`) |
 
+## Addressing: the akm ref
+
+`env` and `secret` assets are addressed like every other asset, by their akm
+ref `[bundle//]conceptId`: `env/prod`, `secrets/gitea_token`,
+`team//secrets/discord_bot_token`. There is no bare-name form. `akm secret
+run gitea_token ...` and `akm env run prod -- ...` are usage errors that name
+the full ref (`secrets/<name>`, `env/<name>`). An unqualified ref resolves the
+way every unqualified ref does: the default bundle first, then installation
+priority.
+
 ## Core security guarantee
 
 Values never appear in akm's structured output. `env list` and `akm show
@@ -31,8 +41,8 @@ the child process — never through akm's own stdout, the index, or `akm
 show`.
 
 ```sh
-akm env create prod                       # create an empty .env group
-akm env create prod --from-file ./.env    # or ingest an existing .env
+akm env create env/prod                   # create an empty .env group
+akm env create env/prod --from-file ./.env  # or ingest an existing .env
 
 # akm does not manage individual keys — edit the whole file with your own editor:
 $EDITOR "$(akm env path env/prod --quiet)"
@@ -58,17 +68,51 @@ script (re-serialised single-quoted, so shell substitutions in the source
 `.env` become literal strings) — it requires `--out` and never prints values
 to stdout.
 
-An env value can be a `${secret:<name>}` token, such as
-`DISCORD_BOT_TOKEN=${secret:discord_bot_token}`. `akm env run` and a workflow
-unit's `env:` binding both replace it with the secret at `secrets/<name>` in
-the env asset's own bundle; `env export` writes the token verbatim. `<name>` is
-a path under that `secrets/` directory, so `bundle//name` inside the token is
-not a bundle qualifier. A missing secret is an error and nothing is injected.
-In a workflow, every value of a bound env asset is redacted from the run's
-output and each read records an `env_access` event, so keep non-secret ids out
-of env assets used there. See
+## The `${ref}` token
+
+Wherever akm substitutes a reference into a string it hands to a process or a
+provider, the token is `${[bundle//]conceptId}`:
+
+- an env value: `DISCORD_BOT_TOKEN=${team//secrets/discord_bot_token}`;
+- a config credential (`engines.<name>.apiKey`, `embedding.apiKey`, a git
+  bundle's `credential`): `"${secrets/openai}"`.
+
+Where the token may appear decides what it may name:
+
+- **In an env value**, any asset ref substitutes. A `secrets/...` ref stands for
+  the secret's value; any other asset ref (for example
+  `${scripts/lab/fetch.sh}`) stands for the asset's absolute path.
+- **In a config credential**, only a `secrets/...` ref is accepted. A `${...}`
+  naming any other kind of asset is rejected when the config loads.
+
+The ref is resolved with the one ref walk, so it may name any bundle and any
+asset its owner holds. A `${...}` body is a ref when it leads with a native type
+directory, qualified or not (`${secrets/x}`, `${scripts/run.sh}`,
+`${team//secrets/x}`), or when it is bundle-qualified and that bundle is
+installed (`${docs//tables/customers}`, whatever adapter owns it). `akm env
+run` and a workflow unit's `env:` binding replace the tokens in an env file's
+values; `env export` writes them verbatim. A `${...}` body that is not an akm
+ref (`${HOME}`, `${PATH//:/ }`, and shell substitution such as `${v//-/_}`
+unless a bundle named `v` is installed) is plain text: it is left untouched in an env
+value, and in a config credential a `${NAME}` that is a valid variable name is
+expanded from the process environment. A ref no bundle owns is an error and
+nothing is injected. Each read records an `env_access` event. See
 [Workflow Schema: Binding a secret to a unit](workflow-schema.md#binding-a-secret-to-a-unit).
 
+A secret's value is its file content with surrounding whitespace trimmed. That
+one read is used by `akm secret run`, env tokens, config credentials and the
+website fetchers, so a hand-written file's trailing newline never lands in an
+HTTP header.
+
+`${secret:NAME}` was the old env-value spelling, meaning the secret `NAME` in the
+env file's own bundle. akm still reads it that way, as `${<bundle>//secrets/NAME}`
+with the bundle that owns the env file, and warns once naming the env ref. The
+env file is bundle content and is not rewritten; write the full ref.
+
+`secret://name` was the config spelling of the same thing. It is retired:
+config still reads it as `${secrets/name}` and names the key once, and `akm
+migrate apply` rewrites the file.
+
 ## File modes and storage
 
 `.env` files are stored at mode 0600 under `env/` in the target bundle;
@@ -80,6 +124,12 @@ secret can carry a sibling `.sensitive` marker that excludes it from `list`
 output and from the search index entirely; the value remains usable via
 `run`.
 
+An env file or secret may be a symlink to a file anywhere else, such as a
+container's `/run/secrets/<name>`: `akm env`, `akm secret`, `${secrets/name}`
+substitution and a workflow `env:` binding follow it. A name still cannot climb
+out of `env/` or `secrets/` with `..` or an absolute path. Writes never follow
+a symlink out of the bundle.
+
 ## Write-target resolution
 
 Env/secret **mutations** (`env create`, `env remove`, `secret set`) choose
@@ -108,10 +158,11 @@ subprocess the child spawns.
 - Avoid running commands that print the environment (`env`, `printenv`,
   shell tracing, verbose diagnostics) in agent contexts unless you
   explicitly intend to expose the child environment.
-- Before spawning, injected key names are scanned for known
-  process-hijacking variables (`LD_PRELOAD`, `PATH`, `GIT_CONFIG_*`, ...): a
-  first-party bundle warns and proceeds, a third-party-sourced bundle is
-  refused.
+- Installing a bundle is the trust decision: `env run`, `secret run` and
+  workflow `env:` bindings inject what the bundle's files define, including
+  keys such as `PATH` or `LD_PRELOAD`, from any bundle, with no warning, block
+  or flag. `akm lint` still reports such keys (`dangerous-env-key`,
+  non-blocking) so an author can review their own files.
 
 ## Stability
 

package/docs/reference/registry.md

@@ -215,17 +215,12 @@ akm bundle add file:///absolute/path/to/bundle
 3. **Download and extract** -- The tarball is downloaded (or repo cloned) to a
    cache directory under `~/.cache/akm/registry/` and extracted securely
    (path traversal is rejected).
-4. **Security audit** -- Before install completes, the extracted bundle's
-   `env`/`secret` asset **key names** are checked against a denylist of
-   process-execution-hijacking variables -- dynamic-linker hooks
-   (`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, ...), `PATH`, shell/runtime startup
-   hooks (`BASH_ENV`, `PROMPT_COMMAND`, `NODE_OPTIONS`, `PYTHONSTARTUP`, ...),
-   and interactive-tool overrides (`EDITOR`, `PAGER`, `GIT_SSH_COMMAND`, ...).
-   `akm bundle add` **blocks the install** when a dangerous key is present unless
-   `--allow-dangerous-env-keys` is set (or you confirm at an interactive prompt).
-   This is a **key-name audit only** (plus the path-traversal rejection in step
-   3) -- akm does **not** scan source files, prompts, metadata, or install
-   scripts for prompt-injection phrases, shell pipes, or lifecycle hooks.
+4. **No content audit** -- Installing a bundle is the trust decision. akm does
+   **not** scan the extracted bundle's source files, prompts, metadata, env
+   files or install scripts (beyond the path-traversal rejection in step 3), and
+   `akm bundle add` never blocks or prompts over the keys an env file sets.
+   `akm lint` reports env keys that can hijack a process (`dangerous-env-key`)
+   for authors who want to review their own bundle.
 5. **Bundle root detection** -- The extracted contents are scanned for asset
    type directories (`scripts/`, `skills/`, etc.) or a `.stash/` marker. If the
    bundle nests its bundle under an `opencode/` subdirectory, that is detected

package/docs/reference/tasks.md

@@ -116,9 +116,17 @@ Script refs use this closed table; any other extension fails before dispatch:
 `run` is one non-empty shell string. It may specify `shell` from the closed host
 shell table `bash`, `sh`, `zsh`, `pwsh`, `powershell`, or `cmd`. Shell expansion
 is runtime behavior for an explicitly authored task `run`; AKM does not infer a
-shell from `uses`. `working-directory` must be a relative, contained path under
-the task's workspace root. Absolute paths, traversal, dangling links, and
-symlink escapes fail before execution.
+shell from `uses`. `working-directory` is a non-empty string, relative to the
+task's bundle root or absolute, like a workflow's `exec.cwd`. akm does not
+keep it inside the bundle or check it when the task source is parsed, so a
+symlink that resolves outside the bundle works. The task runs in
+`<bundle root>/<working-directory>` (or the absolute path as written): akm does
+not capture the directory's identity or re-check it when the task runs. A
+`uses: scripts/<file>` target may itself be a symlink to a file outside the
+bundle; the task freezes that file's bytes, not its location. The interpreter
+comes from the name the script has in the bundle, not from the file the link
+points to, so `scripts/deploy.sh` linked to `real-script.txt` runs under the
+shell.
 
 Every field that used to live under v3's `akm:` options bag is a top-level
 key in task source v4: `agent`, `engine`, `model`, `inference`, `tools`,

package/docs/reference/ui-api.md

@@ -32,7 +32,7 @@ release, and nothing outside the page should script against them. Use the CLI's
   `ORIGIN_NOT_ALLOWED`, `METHOD_NOT_ALLOWED`, `UNSUPPORTED_MEDIA_TYPE`, `BODY_TOO_LARGE`, `INVALID_JSON_ARGUMENT`,
   `NOT_FOUND`, `INTERNAL_ERROR`.
 - **Redaction.** Config values under secret-like keys (`apiKey`, `token`, `password`, `secret`, `credential`,
-  `authorization`, anything under `env` or `secrets`) are `"[redacted]"`; symbolic references (`$VAR`, `secret://name`)
+  `authorization`, anything under `env` or `secrets`) are `"[redacted]"`; symbolic references (`$VAR`, `${secrets/name}`)
   are kept. Credentials inside any URL in any response (userinfo, `token=`, `api_key=`, `sig=`, ...) are masked. Env and
   secret assets are never read; see `/api/asset`.
 - **Timestamps** are ISO 8601 UTC unless noted. Counts that cannot be computed are `null`, never `NaN`.
@@ -616,7 +616,7 @@ general config editor or command-execution endpoint.
 | `POST` route | Body and existing operation |
 | --- | --- |
 | `/api/feedback` | `{ref, signal: "positive"\|"negative", reason?, tags?: string[]}` → `akm feedback`. The ref is passed to `akm feedback` as given, which resolves it as the CLI does; tags follow existing `key:value` validation. Negative feedback requires a reason when `feedback.requireReason` is enabled. Submissions are recorded with source `user` unless the server runs with an `AKM_EVENT_SOURCE` already set (for example under an improve or task run), which wins as it does for every akm child; they retain existing ranking/utility/event effects. Feedback does not save config, so it works under a config that still holds a literal API key. No fix, supersession or model flags are exposed. |
-| `/api/bundles/add` | `{source, name?, writable?}` → `akm bundle add`, including source validation and installation audit. Existing provider restrictions apply; no dangerous-key or insecure-transport bypass is exposed. |
+| `/api/bundles/add` | `{source, name?, writable?}` → `akm bundle add`, including source validation. Existing provider restrictions apply; no insecure-transport bypass is exposed. |
 | `/api/bundles/update` | `{bundle}` → `akm bundle update -- <bundle>`. Fetches/reindexes only on explicit submission. A rare update requiring destructive confirmation remains refused; the UI does not silently pass `--yes`. |
 | `/api/bundles/remove` | `{bundle, confirm: true}` → `akm bundle remove --yes -- <bundle>`. The UI requires an inline confirmation before this call. Managed installs may be deleted; local filesystem source files remain on disk. |
 | `/api/bundles/settings` | `{bundle?, enabled?, writable?, componentWritability?: {existingComponent: boolean}, defaultBundle?, defaultWriteTarget?}` → existing schema-walking config setters inside `mutateConfig`. Only changed controls are submitted. Defaults take existing names or `""` to unset a local value; inherited values cannot be unset locally. Existing validation rejects invalid defaults, disabled targets and writable npm/website sources. |
@@ -624,7 +624,7 @@ general config editor or command-execution endpoint.
 | `/api/asset/save` | `{ref, revision, content}` → the existing shared Markdown writer with `force` and the expected raw-content hash. Only indexed writable AKM knowledge/memory documents accepted by `/api/asset/source` can be edited. The writer takes the asset-mutation lease and compares the live source with `revision` inside it, immediately before writing. While another writer holds the lease the save fails fast with `409 ASSET_MUTATION_LEASE_HELD` instead of waiting. A stale revision returns `409 ASSET_CONTENT_CHANGED` without writing; a source deleted after it was loaded is refused (`404 ASSET_NOT_FOUND`) rather than recreated. The browser keeps the draft after a rejected save. An identical save returns `unchanged: true` without rewriting, reindexing or recording an event. Changed saves retain normal writer validation, indexing and Git effects. |
 
 Configuration-affecting actions do not round-trip the redacted API configuration. Existing mutation helpers retain
-unknown/unrelated fields, local overrides and supported `$VAR`/`secret://` credential references. If the existing
+unknown/unrelated fields, local overrides and supported `$VAR`/`${ref}` credential references. If the existing
 config sanitizer would remove unrelated legacy literal credentials, a bundle add or remove, or a settings change that
 would write config, is refused with `400 INVALID_FLAG_VALUE` and the user is asked to correct those settings through
 the CLI first. A settings request that changes nothing writes nothing and is not refused. It never writes

package/docs/reference/workflow-schema.md

@@ -515,7 +515,7 @@ steps:
     unit:
       exec:
         command: ["bun", "run", "test:unit"]
-        cwd: packages/core        # optional, relative
+        cwd: packages/core        # optional: relative to the workflow's bundle root, or absolute
       timeout: "10m"
       retry: { max: 1, on: [timeout] }
 ```
@@ -554,11 +554,66 @@ Bounds: 1–64 argv entries, each a non-empty string of at most 4096 bytes.
 
 ### `cwd`
 
-Optional and **relative**. It resolves inside the unit's working directory —
-the engine invocation's working directory. Absolute paths, Windows drive
-letters, `~`, and `..` segments are rejected by the parser *and* by the
-frozen-plan decoder, and containment is re-checked against the *resolved* base
-(symlinks included) immediately before the command is spawned.
+Optional: a non-empty string, **relative or absolute**, and free to carry
+`${ref}` tokens (see [`${ref}` in argv and `cwd`](#ref-in-argv-and-cwd)). It is
+the only static check; there is no containment.
+
+An exec unit's working directory is the **root of the bundle that owns the
+workflow**. akm finds that bundle again for each step, by the run's workflow
+ref, so a `bundle update` that moves the bundle to a new revision directory
+between two steps of a running workflow is harmless: the next step runs from
+the new directory. `cwd` is joined onto that root **once**: `cwd: sub` runs in
+`<bundle>/sub`, and an absolute `cwd` replaces the root. Agent and SDK units
+get the same directory as their workspace, and so does a step's gate judge. If the workflow's bundle no longer
+resolves, the step fails with a message naming the ref; a step with a gate is
+blocked by its judge first, for `akm workflow resume`, because the judge is built
+before anything is dispatched. akm never falls back to its own working
+directory.
+
+### The exec contract
+
+What a command can rely on, in one place. The sections below give each point in
+full.
+
+| | |
+| --- | --- |
+| **Working directory** | The owner root of the run's workflow, found at each step's dispatch. `cwd` joins it once and may be absolute. |
+| **Argv** | Spawned directly, never shell-interpreted. A `${ref}` token in an entry is replaced at dispatch. |
+| **Environment** | Starts empty: the [default allowlist](#the-childs-environment-is-an-allowlist) plus `pass_env`, then the unit's `env:` bindings, then the engine's `AKM_*` [context](#context-reaching-the-command). |
+| **`${ref}` tokens** | In argv, `cwd` and env-asset values. `${secrets/name}` becomes the secret's value, any other asset ref the asset's absolute path. A ref no bundle owns fails the unit before it spawns. Prompts are not substituted. |
+| **Redaction** | Only values substituted from `secrets/` refs, engine credentials and unsafe passthrough values are scrubbed from stdout, stderr, diagnostics and the journal. Configuration, such as a URL bound through an env asset, is not. |
+
+#### What is frozen, and what is found at dispatch
+
+The frozen plan records the identities the engine itself dereferences: the
+workflow ref, each unit's `env:` refs qualified with their bundle
+(`team//env/prod`), and child workflow refs, plus the argv, `cwd` and
+`pass_env` names as authored. It records no directory or file location. The
+bundle root, the env files, the secrets and the paths behind `${ref}` tokens are
+all looked up when the unit dispatches, through the same ref lookup `akm show`
+uses. Plans frozen by earlier releases (`irVersion` 5 and 6) also carry a frozen
+`cwdIdentity` and the env asset's owner paths; they decode, those fields are
+ignored, and such a run dispatches by ref like any other.
+
+#### `${ref}` in argv and `cwd`
+
+An argv entry or `cwd` can name an asset in any bundle with the same
+`${[bundle//]conceptId}` token env assets use:
+
+```yaml
+  - id: status
+    unit:
+      env: [team//env/discord]
+      exec:
+        command: ["bun", "${homelab//scripts/lab-status/fetch-status.ts}"]
+```
+
+A `secrets/` ref gives the secret's value, trimmed of surrounding whitespace,
+and joins the redaction set; any other asset ref gives the asset's absolute
+path. Putting a secret in argv is the author's choice (it shows up in the
+process list); prefer an `env:` binding. A `${...}` body that is not an akm ref
+(`${HOME}`) is left as text. A ref no bundle owns fails the unit, naming it,
+before anything is spawned.
 
 ### The output rule
 
@@ -623,13 +678,12 @@ failure reason.
 | non-zero exit | `non_zero_exit` | yes |
 | exceeded `timeout` | `timeout` | yes |
 | run cancelled (`Ctrl-C`, `--timeout`, budget) | `aborted` | yes |
-| binary missing / working directory unusable | `spawn_failed` | yes |
+| binary missing / working directory missing | `spawn_failed` | yes |
 | **stdout** capture never completed | `exec_capture_incomplete` | **no** (the command already ran) |
 | **stderr** capture never completed | — (unit succeeds; a warning says the stderr tail may be missing) | — |
 | stdout past the retention limit, **and** the unit declares `output:` | `exec_output_limit` | **no** (deterministic) |
 | stdout past the retention limit, no `output:` schema | — (unit succeeds; artifact marked truncated) | — |
 | `AKM_*` context too large for **this platform** to spawn | `exec_context_too_large` | **no** (an authoring/data problem) |
-| `cwd` resolved outside its base | `exec_cwd_escape` | **no** (tampering, never transient) |
 
 `non_zero_exit` in `retry.on` re-runs a command that already ran, and a
 command's exit is usually deterministic, so the retry mostly repeats the
@@ -689,9 +743,10 @@ want the whole thing, have it write to a file and print the **path**:
 
 ### Context reaching the command
 
-A frozen argv is never interpolated (this format has no substitution language),
-so data reaches an exec unit as **environment**, the argv analogue of the
-context blocks a model unit gets in its prompt:
+A frozen argv never carries run data (this format has no substitution language
+for params or step output; the only substitution is a [`${ref}` token](#ref-in-argv-and-cwd)
+naming an asset), so data reaches an exec unit as **environment**, the argv
+analogue of the context blocks a model unit gets in its prompt:
 
 | Variable | Value |
 | --- | --- |
@@ -773,8 +828,8 @@ an explicit error is the smaller, more predictable surface.
 An exec unit's command does **not** inherit akm's environment. The child starts
 from an **empty** environment and is built in three layers, in this order:
 
-1. the **default allowlist** below, copied through from akm's own environment
-   (plus any names the unit adds with `pass_env:`);
+1. akm's own directories and the **default allowlist** below, copied through
+   from akm's own environment (plus any names the unit adds with `pass_env:`);
 2. the unit's resolved **`env:` bindings**;
 3. the engine-authored **`AKM_*` context** — last, so a binding can never
    shadow it.
@@ -798,6 +853,14 @@ environment is simply absent from the child):
 when akm is running in a scheduler context (cron/launchd/Task Scheduler) that
 stripped it — the same treatment an agent-harness child gets.
 
+The child also gets akm's own directories, whatever the parent found them
+through: `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` and `AKM_STATE_DIR` are
+set to the directories the akm that started it resolved (from `AKM_*_DIR`,
+`XDG_*_HOME` or the platform default), and `AKM_BUNDLE_DIR` is passed when that
+akm had one. A step that runs `akm` therefore uses the same bundle, config, data,
+cache and state, with no `pass_env:`. Naming one of these in `pass_env:` or
+binding it in `env:` overrides it.
+
 Deliberately **not** on the list: credentials of any kind, cloud/CI variables,
 and the proxy family (`HTTP_PROXY` and friends — proxy URLs routinely embed
 credentials). Reach a required value with an exact named `env:` binding, or
@@ -818,16 +881,16 @@ a committed *value*, so it cannot carry "whatever this build agent's
 `CARGO_HOME` happens to be".
 
 Values passed through this way are **not** redacted from the command's output
-the way `env:` binding values are, so never list a credential here.
+the way a secret bound through `env:` is, so never list a credential here.
 
 #### Binding a secret to a unit
 
 A unit's `env:` lists env assets by ref. A value inside an env asset can be a
-`${secret:<name>}` token, which akm replaces with a secret when the unit is
+`${ref}` token, which akm replaces with the secret's value when the unit is
 dispatched. Say the bundle `team` holds `env/discord.env`:
 
 ```sh
-DISCORD_BOT_TOKEN=${secret:discord_bot_token}
+DISCORD_BOT_TOKEN=${team//secrets/discord_bot_token}
 ```
 
 and the secret beside it, set with
@@ -843,33 +906,42 @@ env asset:
         command: ["node", "announce.mjs"]
 ```
 
-- `<name>` is read from the **env asset's own bundle's** `secrets/` directory.
-  It is a path there, not a ref: `bundle//name` inside the token is **not** a
-  bundle qualifier. `${secret:team//token}` reads `secrets/team/token` in the
-  env asset's bundle.
+- The token body is an akm ref, `[bundle//]conceptId`, resolved with the one
+  ref walk: `${team//secrets/discord_bot_token}` reads that secret from the
+  `team` bundle whichever bundle holds the env asset, and an unqualified
+  `${secrets/discord_bot_token}` resolves by the default bundle then
+  installation priority. A `secrets/...` ref gives the secret's value, trimmed
+  of surrounding whitespace; any other asset ref (`${scripts/x.sh}`) gives the
+  asset's absolute path. A `${...}` body that is not an akm ref (`${HOME}`) is
+  left as text.
 - It is the same token `akm env run` resolves. `akm env export` does not
   resolve it; it writes the token verbatim.
-- Freezing records the env ref, its key names and the secret names, never a
-  value. Values and secrets are read at dispatch. A missing secret fails the
-  step at dispatch ("frozen environment preflight failed") and nothing is
-  injected.
+- Freezing records the env ref, never a value. At each dispatch the unit's env
+  assets are read live with `resolveEnvBinding`, the same function `akm env run`
+  uses, so an edit to the env file, or to a secret, after the run started is
+  picked up by the next dispatch; there is no key-set check against the frozen
+  plan. A ref no bundle owns fails the step at dispatch ("frozen environment
+  preflight failed") and nothing is injected.
 - Each dispatch that reads the env asset records an `env_access` event with the
-  ref, key names and secret names, never values.
-- Every value from an env asset is treated as sensitive, secret or not, and is
-  redacted out of stdout, stderr and diagnostics before they are journaled. A
-  non-secret value such as a channel id would be redacted from the output too,
-  so pass it as a param or in `command:` instead.
+  ref and key names, never values.
+- Redaction covers secrets, not configuration. A value substituted from a
+  `secrets/` ref is treated as sensitive and redacted out of stdout, stderr and
+  diagnostics before they are journaled. The rest of an env asset, such as a URL
+  or a channel id, reaches the journal and the next step unredacted. A
+  credential typed straight into an env file is not redacted, so keep
+  credentials in `secrets/` and bind them with a `${secrets/name}` token.
 - `env:` needs a child process: it works on exec units and on agent and SDK
   engines. A unit on an `llm` engine that declares `env:` fails
   `env_unsupported`.
 
-#### Durable v4 (`irVersion: 5`) forbids `inherit_env`
+#### Durable v4 (`irVersion: 7`) forbids `inherit_env`
 
 Every new workflow start freezes the durable plan v4 family's current
-executable format, `irVersion: 5`. It rejects `inherit_env: true` and any other
-request for whole-process inheritance; use exact named environment bindings
-and `pass_env:` instead. Both mechanisms are dispatch-significant, keep the
-visible environment surface bounded, and form part of the unit's input hash.
+executable format (`irVersion: 7`; 5 and 6 still decode). It rejects
+`inherit_env: true` and any other request for whole-process inheritance; use
+exact named environment bindings and `pass_env:` instead. Both mechanisms are
+dispatch-significant, keep the visible environment surface bounded, and form
+part of the unit's input hash.
 
 The historical `inherit_env` spelling is unsupported.
 
@@ -941,8 +1013,9 @@ They do not widen it, and they do not narrow it:
   the ref names, the replay hash carries only the ref names, and the resolved
   values are collected and scrubbed out of stdout, stderr, and the failure
   diagnostic by the same redaction contract every other dispatch uses — before
-  anything is journaled. Never inline a secret into `command:`; argv is stored
-  verbatim in `plan_json`.
+  anything is journaled. Never inline a secret value into `command:`; argv is
+  stored as authored in `plan_json`. A `${secrets/name}` token in argv is
+  stored as the token and replaced only when the unit dispatches.
 - **Read a workflow before you run it.** `exec:` makes what a workflow will run
   explicit and auditable in one place, which is a real improvement over
   instructing a model to "run the tests" — but a bundle you do not trust is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261012-beta",
+  "version": "0.10.261013-beta",
   "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-task.json

@@ -9,8 +9,7 @@
     "maxStringUtf8Bytes": 262144,
     "maxJsonDepth": 64,
     "maxJsonNodes": 10000,
-    "canonicalRefsRequireNfc": true,
-    "workingDirectoryRequiresWorkspaceRoot": true
+    "canonicalRefsRequireNfc": true
   },
   "type": "object",
   "required": ["version"],
@@ -55,8 +54,7 @@
     "working-directory": {
       "type": "string",
       "minLength": 1,
-      "maxLength": 262144,
-      "pattern": "^(?![\\\\/])(?![A-Za-z]:[\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?!.*[\\\\/]{2})(?!.*[\\\\/]$)[^\\u0000]+$"
+      "maxLength": 262144
     },
     "schedule": {
       "oneOf": [

package/dist/commands/sources/dangerous-env-audit.js

@@ -1,134 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import fs from "node:fs";
-import path from "node:path";
-import * as p from "../../cli/clack.js";
-import { decideDangerousKeyInstall } from "../../core/activation-policy.js";
-import { ConfigError } from "../../core/errors.js";
-import { warn } from "../../core/warn.js";
-import { sanitizeString } from "../../sources/providers/provider-utils.js";
-import { scanEnvKeyNames } from "../env/env.js";
-import { isDangerousEnvKey } from "../lint/env-key-rules.js";
-let scannerOverride;
-/** TEST-ONLY. Inject a scanner fault at the audit boundary; undefined restores. */
-export function _setDangerousKeyScannerForTests(scanner) {
-    scannerOverride = scanner;
-}
-function collectEnvFilePathsRecursive(rootDir) {
-    const results = [];
-    const walk = (dir) => {
-        const entries = fs.readdirSync(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                walk(full);
-                continue;
-            }
-            if (!entry.isFile())
-                continue;
-            if (entry.name !== ".env" && !entry.name.endsWith(".env"))
-                continue;
-            results.push(full);
-        }
-    };
-    walk(rootDir);
-    return results;
-}
-function collectDangerousKeyFindings(installedStashRoot, checkEnvForDangerousKeys) {
-    const allFindings = [];
-    if (!fs.statSync(installedStashRoot).isDirectory()) {
-        throw new Error(`Expected ${installedStashRoot} to be a directory.`);
-    }
-    const dir = path.join(installedStashRoot, "env");
-    try {
-        if (!fs.statSync(dir).isDirectory()) {
-            throw new Error(`Expected ${dir} to be a directory.`);
-        }
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return allFindings;
-        throw error;
-    }
-    for (const envPath of collectEnvFilePathsRecursive(dir)) {
-        const relToEnvDir = path.relative(dir, envPath);
-        const segments = relToEnvDir.split(path.sep);
-        const lastSegment = segments[segments.length - 1] ?? "";
-        const lastSegmentBase = lastSegment.endsWith(".env") ? lastSegment.slice(0, -".env".length) : lastSegment;
-        const refSegments = [...segments.slice(0, -1), lastSegmentBase === "" ? "default" : lastSegmentBase];
-        const envRef = `env/${refSegments.join("/")}`;
-        const relPath = path.join("env", relToEnvDir);
-        for (const finding of checkEnvForDangerousKeys(envPath, relPath, envRef)) {
-            const keyMatch = finding.detail.match(/Env key `([^`]+)`/);
-            allFindings.push({ envRef, keyName: keyMatch?.[1] ?? finding.file, relPath });
-        }
-    }
-    return allFindings;
-}
-function scanStashForDangerousKeys(installedStashRoot) {
-    const scanner = scannerOverride ??
-        ((envPath, relPath) => scanEnvKeyNames(fs.readFileSync(envPath, "utf8"))
-            .filter(isDangerousEnvKey)
-            .map((key) => ({ file: relPath, detail: `Env key \`${key}\`` })));
-    return collectDangerousKeyFindings(installedStashRoot, scanner);
-}
-export async function auditStashForDangerousKeys(opts) {
-    let allFindings;
-    try {
-        allFindings = scanStashForDangerousKeys(opts.stashRoot);
-    }
-    catch (error) {
-        const rollbackWarning = await opts.rollback?.();
-        throw new ConfigError(`Dangerous environment-key audit failed for "${opts.ref}"; refusing to ${opts.operation} unverified content. ${error instanceof Error ? error.message : String(error)}${rollbackWarning ? ` ${rollbackWarning}` : ""}`, "DANGEROUS_ENV_AUDIT_FAILED");
-    }
-    const stance = decideDangerousKeyInstall({
-        findingsPresent: allFindings.length > 0,
-        allowDangerousEnvKeys: opts.allowDangerousKeys,
-    });
-    if (stance === "allow")
-        return { blocked: false, findings: allFindings };
-    if (stance === "warn-allow") {
-        for (const finding of allFindings) {
-            warn(`[dangerous-env-key] ${finding.relPath}: key \`${finding.keyName}\` in ${finding.envRef} can hijack process execution via \`akm env run\`. Proceeding because --allow-dangerous-env-keys was set.`);
-        }
-        return { blocked: false, findings: allFindings };
-    }
-    const operationTitle = opts.operation === "install" ? "Install" : "Update";
-    const operationPast = opts.operation === "install" ? "installed" : "updated";
-    let error;
-    if (opts.isTTY) {
-        const groupedByEnv = new Map();
-        for (const finding of allFindings) {
-            const existing = groupedByEnv.get(finding.envRef) ?? [];
-            existing.push(finding.keyName);
-            groupedByEnv.set(finding.envRef, existing);
-        }
-        for (const [envRef, keys] of groupedByEnv) {
-            warn(`[warn] Env "${sanitizeString(envRef)}" in stash "${sanitizeString(opts.ref)}" contains potentially dangerous keys:`);
-            for (const key of keys)
-                warn(`  - ${sanitizeString(key)}: can hijack process execution via \`akm env run\``);
-        }
-        const confirmed = await p.confirm({ message: `${operationTitle} anyway?`, initialValue: false });
-        if (!p.isCancel(confirmed) && confirmed === true)
-            return { blocked: false, findings: allFindings };
-        error = `${operationTitle} aborted: stash contains dangerous env keys. Remove the keys or re-run with --allow-dangerous-env-keys to bypass.`;
-    }
-    else {
-        const keyList = allFindings.map((finding) => `  - ${finding.keyName} (${finding.envRef})`).join("\n");
-        error = `${operationTitle} blocked: stash "${opts.ref}" contains dangerous env keys that can hijack process execution via \`akm env run\`:\n${keyList}\nRe-run with --allow-dangerous-env-keys to bypass this check after reviewing the env file.`;
-    }
-    const rollbackWarning = await opts.rollback?.();
-    if (opts.renderBlockedError !== false) {
-        console.error(JSON.stringify({
-            ok: false,
-            error,
-            code: "DANGEROUS_ENV_KEY",
-            ...(rollbackWarning ? { rollbackWarning } : {}),
-        }, null, 2));
-    }
-    if (rollbackWarning) {
-        warn(`The blocked ${opts.operation} could not be fully rolled back after content was ${operationPast}: ${rollbackWarning}`);
-    }
-    return { blocked: true, exitCode: 1, code: "DANGEROUS_ENV_KEY", error, findings: allFindings };
-}