akm-cli 0.10.261012-beta → 0.10.261014-beta

package/docs/reference/workflow-schema.md

@@ -51,9 +51,9 @@ steps:
 The step needs a `## investigate` body section like any other step (it is
 documentation for a human; the child's own steps carry the instructions).
 
-- `workflow` names the child. A workflow unit reaches no engine and the child
-  carries its own environment, so `exec`, `engine`, `model`, `llm` and `env`
-  beside `workflow` are lint errors. `workflow` is not allowed inside
+- `workflow` names the child. A workflow unit runs no model of its own and the
+  child carries its own environment, so `exec`, `connection`, `harness`, `model`,
+  `llm` and `env` beside `workflow` are lint errors. `workflow` is not allowed inside
   `map.unit`.
 - `with:` binds the child's declared `params:` (a workflow has no `inputs:`).
   Each value is a literal (validated against the param's declared type at
@@ -159,12 +159,14 @@ families) plus the orchestration keys:
 - `params` — name → `{ type, description, default }` (JSON-Schema-typed, unlike a bare
   description string). A param the run does not supply takes its `default:`; an explicit
   value wins. Params are never required.
-- `defaults` — run-level dispatch defaults (`engine`, `model`, `llm`,
-  `timeout`, `on_error`), overridable per unit. `llm:` tuning reaches an engine
-  of any kind, and a document-level `llm:` reaches EVERY step. An LLM engine
-  sends it; an agent engine reports it as an `untranslated-field` notice on that
-  step (see
-  [Inference on an agent engine](configuration.md#inference-on-an-agent-engine)).
+- `defaults` — run-level dispatch defaults (`connection`, `harness`, `model`,
+  `llm`, `timeout`, `on_error`), overridable per unit. A step with neither runs
+  on the default harness, else akm's own runtime over the default connection.
+  `llm:` tuning (`temperature`, `max_tokens`, `enable_thinking`,
+  `reasoning_effort`) reaches every step, and a document-level `llm:` reaches
+  EVERY step. A connection and akm's own runtime send it; a harness reports it as
+  an `untranslated-field` notice on that step (see
+  [Settings a call asks for](configuration.md#settings-a-call-asks-for)).
   There is no per-step opt-out (`llm: {}` is a no-op and `llm: null` is a parse
   error), so in a mixed document put `llm:` on the `unit:` of each step it is
   meant for instead of in `defaults:`.
@@ -174,8 +176,8 @@ families) plus the orchestration keys:
   (`[A-Za-z_][A-Za-z0-9_-]*` — no dots) and **at most one** of `unit` or `map`.
   A step with neither is **still a unit step** — bare
   `- id: validate` is the complete minimal declaration. `unit:` is the
-  optional dispatch-override bag (`exec`, `engine`, `model`, `llm`, `timeout`,
-  `retry`, `on_error`, `output`, `env`; see
+  optional dispatch-override bag (`exec`, `connection`, `harness`, `model`,
+  `llm`, `timeout`, `retry`, `on_error`, `output`, `env`; see
   [Exec (shell) units](#exec-shell-units) and
   [Failure policy](#failure-policy)). Dispatch settings live under `unit:`
   (`map.unit:` on a map step), not on the step itself; `unit.output` types
@@ -267,7 +269,7 @@ type: workflow
 description: Review changed files and give an overall verdict
 params:
   changed_files: { type: array, description: Files to review }
-defaults: { engine: reviewer, model: balanced, timeout: 10m, on_error: fail }
+defaults: { harness: claude, model: balanced, timeout: 10m, on_error: fail }
 budget: { max_units: 40, max_tokens: 200000 }
 steps:
   - id: discover
@@ -278,8 +280,8 @@ steps:
       over: steps.discover.output.files
       concurrency: 8
       unit:
-        engine: reviewer
-        model: deep
+        harness: claude
+        model: reasoning
         timeout: 5m
         retry: { max: 1, on: [timeout, llm_rate_limit] }
         on_error: continue
@@ -491,20 +493,20 @@ fail later at `akm workflow run`:
 | `map.concurrency` | 1 – 64 |
 | `retry.max` | 0 – 100 |
 | `timeout` | ≤ 2147483647 ms (~24.8 days), or `none` |
-| `engine` names | `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`, ≤ 63 chars |
+| `connection` and `harness` names | `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`, ≤ 63 chars |
 
 `timeout` is resolved **once, at freeze time**, and the frozen value is what
-dispatch applies — there is no separate engine-side ceiling on top of it. The
+dispatch applies — there is no separate ceiling on top of it. The
 first of these that is set wins: the unit's `timeout`, then the document's
-`defaults.timeout`, then `engines.<name>.timeoutMs`, then the engine-kind
-default — **10m for `kind: llm` engines, and none for agent engines**, which
-manage their own process lifetime. Writing `timeout: none` is an explicit opt
+`defaults.timeout`, then the selected connection's or harness's `timeoutMs`,
+then the default — **none for agent work, whether it runs on a harness or on
+akm's runtime over a connection, and 10m for model work**. Writing `timeout: none` is an explicit opt
 out and leaves the unit genuinely unbounded; nothing later re-imposes a cap.
 
 ## Exec (shell) units
 
 A step whose `unit:` block declares `exec:` runs a **shell command** instead of
-dispatching to an engine. Deterministic work — running the test suite, building,
+dispatching a model. Deterministic work — running the test suite, building,
 linting, copying a file, invoking a script — is a command, not a prompt, and
 paying for an LLM or agent dispatch to get it done buys nondeterminism, latency,
 and tokens in exchange for nothing.
@@ -515,15 +517,15 @@ 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] }
 ```
 
-An exec unit names **no engine**. It carries no `engine`, `model`, or `llm` (the
-parser rejects those alongside `exec:`), it consumes no tokens, and a workflow
-made only of exec steps freezes and runs on an install with no engine configured
-at all. Everything else about a unit still applies unchanged: `timeout`, `retry`,
+An exec unit names **no connection or harness**. It carries no `connection`,
+`harness`, `model`, or `llm` (the parser rejects those alongside `exec:`), it
+consumes no tokens, and a workflow made only of exec steps freezes and runs on an
+install with no connection or harness configured at all. Everything else about a unit still applies unchanged: `timeout`, `retry`,
 `on_error`, `output`, `env`, `map` fan-out and its concurrency, the
 unit journal, budget accounting, and replay/reuse.
 
@@ -554,11 +556,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** | [akm's own](#the-childs-environment), with the directories this akm resolved set over it, 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 akm knows are secret are scrubbed from stdout, stderr, diagnostics and the journal: values substituted from `secrets/` refs, secret-shaped run params, connection keys, and the values of credential-named variables the command inherited from akm's environment (names such as `*_API_KEY`, `*_TOKEN`, `*_SECRET` and `*_PASSWORD`, eight characters or more). Configuration, such as a URL bound through an env asset or an ordinary inherited variable, 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 +680,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
@@ -642,8 +698,10 @@ is exactly what makes a `test` step a **gate**. With `on_error: continue` the
 failure is recorded in the step's evidence and the completion gate decides.
 
 On timeout or cancellation the child's whole **process group** gets a
-SIGTERM→SIGKILL ladder, so a command that spawned its own children does not
-leave them orphaned.
+SIGINT→SIGTERM→SIGKILL ladder (each signal after a grace period of 5 seconds, for
+a command still running), so a command that spawned its own children does not
+leave them orphaned. Windows has no process group; there the first signal ends
+the command itself.
 
 ### Output limits
 
@@ -689,9 +747,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 |
 | --- | --- |
@@ -724,7 +783,7 @@ Where those numbers come from:
 - **macOS** has no per-string cap; its binding constraint is `ARG_MAX`
   (262 144 bytes) over `argv` + `environ` *combined*. The 128 KiB total keeps
   akm's own contribution to half of that, leaving the rest for the argv, the
-  environment allowlist and your `env:` bindings.
+  rest of the environment and your `env:` bindings.
 - **Windows** caps a single user-defined environment variable at 32 767
   characters (`SetEnvironmentVariable`), and the environment block has limits of
   the same order.
@@ -768,42 +827,32 @@ command would have to handle both shapes, and the spill file would have to be
 placed and cleaned up. A stable contract plus
 an explicit error is the smaller, more predictable surface.
 
-### The child's environment is an allowlist
+### The child's environment
 
-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:
+An exec unit's command inherits the environment akm runs in, as a command typed in
+your shell would, and nothing is filtered out of it: `PATH`, `HOME`, locale and
+toolchain variables, and any credential or proxy setting of the process that ran
+`akm workflow run` reach the command. It 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 environment, with the directories this akm resolved set over it;
 2. the unit's resolved **`env:` bindings**;
 3. the engine-authored **`AKM_*` context** — last, so a binding can never
    shadow it.
 
-The default allowlist is exactly these names (a name absent from akm's own
-environment is simply absent from the child):
+The directories are `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` and
+`AKM_STATE_DIR`, set to the ones the akm that started the command resolved (from
+`AKM_*_DIR`, `XDG_*_HOME` or the platform default), and `AKM_BUNDLE_DIR` when that
+akm had one. A step that runs `akm` therefore uses the same bundle, config, data,
+cache and state. Binding one of them in `env:` overrides it. When a scheduled
+task runs the workflow, `AKM_EVENT_SOURCE` is set (when the environment has
+none), so a command that calls `akm` records machine traffic, not user demand; a
+direct `akm workflow run` leaves it as it found it.
 
-| Group | Names | Why |
-| --- | --- | --- |
-| Command resolution | `PATH` | without it only an absolute `command[0]` can be spawned |
-| Home | `HOME` | the config/cache root git, npm, bun, cargo and ssh all read |
-| Identity | `USER`, `LOGNAME`, `SHELL` | read by git/ssh and by tools that re-exec a login shell |
-| Locale | `LANG`, `LC_ALL`, `LC_CTYPE` | without a locale, non-ASCII stdout — *which is this unit's artifact* — gets mangled |
-| Terminal / clock | `TERM`, `TZ` | some CLIs abort with no `TERM`; `TZ` keeps printed timestamps stable |
-| Scratch space | `TMPDIR`, `TEMP`, `TMP` | POSIX and Windows temp roots |
-| Windows essentials | `SystemRoot`, `SystemDrive`, `WINDIR`, `COMSPEC`, `PATHEXT` | Windows **process creation itself** fails with an empty environment; `PATHEXT` is what makes `bun.exe`/`bun.cmd` resolvable at all |
-| Windows home/config | `USERPROFILE`, `HOMEDRIVE`, `HOMEPATH`, `APPDATA`, `LOCALAPPDATA`, `ProgramData`, `ProgramFiles` | the Windows analogues of `HOME` and the machine-wide install roots toolchain shims resolve against |
-| akm provenance | `AKM_EVENT_SOURCE` | a command that calls `akm` records machine traffic, not user demand |
-
-`PATH` is additionally supplemented with well-known user binary directories
-when akm is running in a scheduler context (cron/launchd/Task Scheduler) that
-stripped it — the same treatment an agent-harness child gets.
-
-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
-name a non-secret per-machine variable with `pass_env:`.
-
-#### `pass_env:` — widen the allowlist by name
+Reach a fixed value or a secret with an exact named `env:` binding; what is
+redacted from what the command prints is in the Redaction row of [the exec
+contract](#the-exec-contract).
+
+#### `pass_env:` — frozen, and it selects nothing
 
 ```yaml
     unit:
@@ -812,22 +861,20 @@ name a non-secret per-machine variable with `pass_env:`.
         pass_env: [CARGO_HOME, SCCACHE_DIR]
 ```
 
-Names only, 1–32 of them, matching `^[A-Za-z_][A-Za-z0-9_]*$`. Use it for a
-**per-machine** variable an `env:` binding cannot express — an env asset stores
-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.
+`pass_env:` was the list of variable names an earlier release copied into a child
+that started empty. A workflow that has it keeps loading, and the names are kept
+in the frozen plan and in the unit's input hash, but they select nothing now: the
+command already has the environment. Names only, matching
+`^[A-Za-z_][A-Za-z0-9_]*$`.
 
 #### 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 +890,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.
-- `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`
+  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 every unit that
+  runs an agent, whether on a harness or on akm's own runtime. A model call that
+  runs no agent cannot take a per-unit environment and fails `env_unsupported`.
+
+#### Durable v4 (`irVersion: 8`) 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: 8`; a plan frozen earlier decodes when it holds no
+model step). It rejects
+`inherit_env: true`, which is not needed: the command inherits akm's
+environment. Exact named `env:` bindings are dispatch-significant and form part
+of the unit's input hash.
 
 The historical `inherit_env` spelling is unsupported.
 
@@ -877,8 +933,8 @@ The historical `inherit_env` spelling is unsupported.
 
 `akm show <workflow> --format json` summarizes each step under
 `steps[].orchestration`. For an exec step that summary carries an `exec` object
-and **no `engine`/`model`** — an exec unit names no engine, so reporting the
-workflow's `defaults.engine` there would describe a dispatch that never
+and **no `engine`/`model`** — an exec unit runs on no connection or harness, so
+reporting the workflow's `defaults` there would describe a dispatch that never
 happens. Field presence is the discriminator, the same way `fanOut` marks a
 `map` step:
 
@@ -906,8 +962,8 @@ happens. Field presence is the discriminator, the same way `fanOut` marks a
   step's output. Every byte is already visible in the workflow file (and stored
   verbatim in `plan_json`) — which is also why you never inline a secret there.
 - `cwd` and `passEnv` appear only when the unit declares them. `passEnv` is a
-  list of variable **names**; no value is ever projected. New v4 plans never
-  carry `inheritEnv`.
+  list of variable **names** that select nothing; no value is ever projected. New
+  v4 plans never carry `inheritEnv`.
 - `timeoutMs` is still reported, because an exec unit really does inherit
   `defaults.timeout` — that number is true for it.
 
@@ -920,29 +976,21 @@ Exec units sit inside the existing workflow trust model — see
 [Security: workflow sources are executed code](https://github.com/itlackey/akm/blob/main/docs/guides/run-workflows.md#security-workflow-sources-are-executed-code).
 They do not widen it, and they do not narrow it:
 
-- **The child's environment is an allowlist, not an inheritance.** Be clear
-  about what that does and does not buy. It does *not* stop a determined
-  attacker: a command that runs at all can read the same credentials off disk
-  that the environment would have handed it, and a workflow source is executed
-  code either way. What it does buy is real but narrower — it bounds
-  **accidental** exposure (the shell or CI job that invoked `akm` routinely
-  exports tokens for unrelated services, and a third-party step that merely
-  prints its environment, or a tool that ships one in a crash report, should
-  not get them for free), it makes the environment surface **explicit and
-  reviewable** (this list plus lines in the frontmatter diff, rather than
-  "whatever the invoking shell happened to export"), and it **matches the
-  convention akm already applies to spawned children** — agent-harness children
-  have always been built from `envPassthrough` this way, and exec units now use
-  the same mechanism rather than a second one. Operators who need a harder
-  boundary still scope the *akm process* (dedicated account, ephemeral working
+- **The child inherits akm's environment.** The command runs with your
+  environment, as if you had typed it in your shell, so a credential the shell or
+  CI job exported reaches it, and a value it inherited is not redacted from what
+  it prints. That is the same trust a workflow source already has: a command that
+  runs at all can read the same credentials off disk. Operators who need a
+  boundary scope the *akm process* (dedicated account, ephemeral working
   directory, external network/filesystem policy); that is the boundary that
   actually holds.
 - **Secrets come from `env:` bindings by name.** The frozen plan carries only
   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
@@ -989,18 +1037,16 @@ Raising one never raises the others:
 | --- | --- | --- |
 | `map.concurrency` | the step | `workflow.defaultMapConcurrency`, else **4** |
 | `execution.maxConcurrency` | `workflow.maxConcurrency` config | CPU-derived `min(16, max(1, cores − 2))` |
-| the selected LLM engine's concurrency | `engines.<name>.concurrency` | **1** for a loopback endpoint, **4** for a remote one |
+| the selected connection's concurrency | `connections.<name>.concurrency` | **1** for a loopback endpoint, **4** for a remote one |
 | the host CPU safety cap | nothing — reapplied at dispatch | `min(16, max(1, cores − 2))` |
 
-The engine limit is per **endpoint kind** on purpose. A local model server (LM
+The connection limit is per **endpoint kind** on purpose. A local model server (LM
 Studio, Ollama) has one loaded model, and concurrent inference makes it reload
 and return HTTP 500 — a hard failure, so loopback endpoints stay at 1 and a
 `map` against a local model is still effectively serial unless you raise
-`engines.<name>.concurrency` yourself. Remote providers fail softly (a
+`connections.<name>.concurrency` yourself. Remote providers fail softly (a
 retryable 429), and four concurrent completions is well inside any hosted
-provider's entry tier. Agent engines carry no concurrency limit of their own —
-except an `opencode-sdk` engine that sets `llmEngine`, which inherits that
-fallback engine's limit.
+provider's entry tier. A harness carries no concurrency limit of its own.
 
 #### What counts as a loopback endpoint
 
@@ -1022,15 +1068,15 @@ exactly as single-model as one on `127.0.0.1`.
 re-serializes the dotted form to the hex one before the check ever sees it. A
 mapped public address such as `[::ffff:8.8.8.8]` still reads as remote. The
 deprecated IPv4-compatible form `[::127.0.0.1]` is not recognized; if you use
-it, set `engines.<name>.concurrency: 1`.
+it, set `connections.<name>.concurrency: 1`.
 
 The check is **purely syntactic — it never resolves a name.** A frozen plan has
 to come out the same on your laptop, on CI, and on a machine with no network at
 all, and a DNS lookup would make the frozen width depend on what a resolver
 happened to answer. So a *name* that resolves to loopback (a hosts-file alias,
 `host.docker.internal`, an internal DNS record) is treated as **remote**; point
-the engine at the address itself, or set `engines.<name>.concurrency: 1`
-explicitly. In the other direction the classification is deliberately
+the connection's endpoint at the address itself, or set
+`connections.<name>.concurrency: 1` explicitly. In the other direction the classification is deliberately
 conservative: an endpoint akm cannot parse at all is treated as loopback, since
 freezing 4 for a config it does not understand is the failure worth avoiding.
 
@@ -1104,17 +1150,17 @@ verdict that cannot change. So a step whose unit is `exec:` still has its
 artifact judged and can still be failed by the verdict; a rejection simply lands
 on the first evaluation, carrying the same missing criteria and feedback the
 one-shot case does. `gate.max_loops` on such a step is capped at 1 rather than
-rejected, and an engine step's declared `max_loops` is untouched. This is the
+rejected, and a model step's declared `max_loops` is untouched. This is the
 same reasoning that makes an exec unit's `output:` schema miss fail without a
 corrective re-dispatch.
 
 **Fail-closed verification.** With no non-empty `### gate` rubric, no
-verification runs. When a rubric is present, the workflow requires
-`workflow.judgeEngine` to name a configured LLM or agent engine before the
-plan can be frozen — see
+verification runs. When a rubric is present, the workflow requires a
+connection or a harness to judge it before the plan can be frozen: the judge
+runs where model work runs (the default connection, else the default harness; see
+[Where each process runs](configuration.md#where-each-process-runs)) — see
 [Author's Guide: Troubleshooting](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#troubleshooting)
-if that engine isn't configured yet. That verifier invocation is frozen into
-the run.
+if neither is configured yet. That verifier invocation is frozen into the run.
 
 Only a well-formed `complete: true` verdict advances a criteria-bearing step.
 A missing verifier, dispatch failure, or malformed result rejects the gate
@@ -1131,33 +1177,32 @@ across resumes**, not just the current invocation. Hitting a ceiling aborts
 the step's still-pending dispatches and fails the step with a
 `budget exceeded (<which> ceiling)` summary — budget exhaustion is a hard
 stop that ignores `on_error: continue`. Because the plan is frozen, raising a
-budget means starting a new run.
+budget means starting a new run. Only units that run on akm's own runtime
+report token usage; a unit on a harness or a direct model call reports none
+and adds nothing to `max_tokens`.
 
 ## Model references
 
 Reference semantic aliases in `model:` fields instead of exact model ids so a
-workflow stays harness-agnostic. Aliases are defined only in the installed and
-optional user `models.json` files:
+workflow stays portable across machines. The standard aliases are `fast`,
+`balanced` and `reasoning`; each connection and harness says which of its models
+answers them (`connections.<name>.models`, `harnesses.<name>.models`; Claude Code
+ships a map of its own):
 
-```jsonc
-{
-  "version": 1,
-  "aliases": {
-    "fast": { "claude": "claude-haiku-4-5", "opencode": "opencode/claude-haiku-4-5" },
-    "balanced": { "claude": "claude-sonnet-4-6", "opencode": "opencode/claude-sonnet-4-6" },
-    "reasoning": { "claude": "claude-opus-4-7", "opencode": "opencode/claude-opus-4-7" }
-  }
-}
+```yaml
+defaults: { model: balanced }
+steps:
+  - id: review
+    unit:
+      model: reasoning
 ```
 
-Resolution checks the selected engine name or canonical harness column. A
-known alias without that column fails rather than guessing a provider model;
-an unknown string is treated as an exact model selector. A column may itself
-be an `engine`-backed indirection (0.9.15) rather than a literal model string
-— see [Model-map files](configuration.md#model-map-files) — so a step naming
-`model: fast` also benefits from whatever engine-backed mapping the operator
-configured for the selected engine, with no workflow-authored change. See the [Author's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#choosing-engines-and-models)
-for guidance on which tier to pick per step.
+Resolution looks the alias up on the connection or harness the step runs on. A
+string that is not an alias is an exact model name and is used as written. An
+alias the connection does not map answers with that connection's first model; a
+harness with no model for it passes none and uses its own default. See
+[Aliases](configuration.md#aliases) for the full rules and the author's guide
+for [which tier to pick per step](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#choosing-where-a-step-runs-and-which-model).
 
 ## See also
 

package/docs/reference/workflows.md

@@ -11,9 +11,7 @@ interruption without replaying completed units.
 
 Workflows are one of the execution surfaces AKM directly orchestrates: AKM
 retrieves every supported capability type, but a workflow's declared steps —
-not arbitrary indexed content — are what actually gets dispatched. See
-[Architecture: Core Principles](https://github.com/itlackey/akm/blob/main/docs/architecture/akm-core-principles.md) for
-that boundary.
+not arbitrary indexed content — are what actually gets dispatched.
 
 This page is a short map. The full contract now lives across four pages,
 split by what you're doing:
@@ -24,8 +22,8 @@ split by what you're doing:
   someone else's bundle.
 - **[Author's Guide: Writing Workflows](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md)** —
   writing and testing a workflow definition: choosing a source format, the Markdown structure, a
-  minimal complete example, common authoring mistakes, choosing engines and
-  models, and engine-selection troubleshooting.
+  minimal complete example, common authoring mistakes, choosing where a step
+  runs and which model, and troubleshooting a missing harness or connection.
 - **[Workflow Schema](../reference/workflow-schema.md)** — the exhaustive,
   authoritative reference: every frontmatter key, the bare-reference grammar,
   failure policy, gates, and budget ceilings, with exact syntax.
@@ -41,7 +39,7 @@ For task- or schedule-driven workflow runs — an `akm task` bound to
 
 Markdown `.md` is the one workflow source format; it preserves AKM's full prose,
 gates, maps, typed artifacts, and exec vocabulary. New starts resolve source
-owners and executable targets, then freeze durable plan `irVersion` 5. A
+owners and executable targets, then freeze durable plan `irVersion` 8. A
 stored plan is read back as it is: one frozen at another `irVersion` that
 still decodes runs, and one this akm cannot decode is abandoned by
 `akm workflow run` with a message naming how to start a new run. See