akm docs

0003 — The exec unit's child-environment allowlist and provenance

Context

src/workflows/exec/exec-unit.ts is the one place a frozen workflow spawns a shell command as a unit. A spawned child inherits none of AKM's own process safety by default — no argv-injection protection, no environment isolation, no output bound — so every one of those has to be a deliberate design choice in this one module rather than an accident of whatever child_process defaults to.

Decision

The module's invariants

Moved verbatim from exec-unit.ts's module header:

The exec unit runner — the ONE place a frozen workflow spawns a shell command as a unit. The invariants it exists to hold:

  • ARGV, NEVER A SHELL STRING. IrExecSpec.command is an argv ARRAY and the format has no shell-string spelling at all; the child is spawned directly, so ;, |, &&, $(…), backticks, > and * are inert literal argument BYTES. A workflow that wants a pipeline names the interpreter itself (["bash", "-lc", "a | b"]), visibly in frontmatter.
  • NON-BLOCKING. Everything on this path is async. A synchronous call here blocks the event loop and with it every concurrently-scheduled unit, the run's lease heartbeat, and abort handling.
  • NO LEAKED CHILDREN. runManagedSubprocess spawns DETACHED and runs a SIGTERM→SIGKILL ladder against the whole process group, so --timeout and Ctrl-C really do stop a running command and its descendants.
  • CONTAINMENT. exec.cwd is relative and ..-free by construction (parser and frozen-plan decoder), which is necessary but not sufficient: a subdirectory can be a symlink. The RESOLVED path is therefore re-checked against the RESOLVED base immediately before spawning.
  • BOUNDED SPEND. A command is arbitrary code with no resource discipline of its own, so each resource it spends on akm's behalf has a ceiling in workflows/resource-limits.ts: wall clock (DEFAULT_EXEC_TIMEOUT_MS or the authored timeout:), retained output (WORKFLOW_MAX_EXEC_OUTPUT_BYTES per pipe) and the context environment (execContextLimits, checked BEFORE the spawn so an oversized artifact yields an actionable akm error, not a bare E2BIG).
  • ALLOWLISTED ENVIRONMENT. The child does NOT inherit akm's environment: it starts EMPTY and receives exactly EXEC_DEFAULT_ENV_PASSTHROUGH plus the unit's exec.passEnv, then the resolved env: bindings, then the engine-authored AKM_* context. See childEnv.

Secrets: env values reaching this module are already resolved from env: bindings by NAME (resolveEnvBinding) — the plan never carries inline secrets and the input hash only ever carries names. The caller scrubs the outcome with redactUnitOutcome BEFORE anything is journaled, which is why this module may return raw stdout/stderr diagnostics without knowing anything about redaction.

Layering: a LEAF. Node built-ins, core/common (for isWithinAsync, the CONTAINMENT recheck above), core/spawn-env, core/subprocess, core/warn and the import-free workflows/resource-limits (plus erased types) only, so the executor can consume it without opening an import cycle.

The default allowlist and why it is an allowlist

Moved verbatim from EXEC_DEFAULT_ENV_PASSTHROUGH's doc comment and childEnv's doc comment:

The DEFAULT environment allowlist for an exec unit's child — the single definition of the EXEC list (the docs describe it, the tests assert against it, and exec.passEnv extends it per unit). The win32 process-creation names are not re-spelled here: they are spread from WIN32_SPAWN_ENV_FLOOR, which owns them.

The child starts from an EMPTY environment and receives only these names, matching how an agent harness child is already built (profile.envPassthrough → collectAllowlistedEnv) — and literally extending the same COMMON_SPAWN_ENV_PASSTHROUGH baseline those profiles start from, so the two child-spawn allowlists share one floor. Every entry earns its place by being load-bearing for ordinary commands on some supported platform: PATH (command resolution), HOME (the config/cache root essentially every toolchain reads), USER/LOGNAME (process identity for git/ssh), SHELL (tools that re-exec a login shell), LANG/LC_ALL/LC_CTYPE (text encoding — without a locale a command falls back to the C locale and mangles non-ASCII stdout, which IS this unit's artifact), TERM (some CLIs abort or emit raw escape bytes with no TERM), TZ (timestamps a command prints would otherwise silently switch to the host default), TMPDIR (POSIX scratch space), the win32 spawn floor plus APPDATA/LOCALAPPDATA/ProgramData/ProgramFiles (Windows toolchain roots not on the floor itself), and AKM_EVENT_SOURCE (provenance, never a secret: an exec unit that calls akm must record machine traffic rather than user demand, exactly as the agent passthrough list does — DRIFT-6).

Deliberately ABSENT and reachable only through exec.passEnv / env:: credentials of every kind, cloud/CI vars, and the proxy family (HTTP_PROXY & friends) — proxy URLs routinely embed credentials, which is why akm's redaction policy already treats URL-shaped passthrough values as credential-bearing.

The child's environment resolves in three layers with fixed precedence: (1) the BASE — the default allowlist plus the unit's exec.passEnv names; (2) the unit's resolved env: bindings; (3) the engine-authored AKM_* context, LAST so a workflow-supplied binding can never shadow the ids/item the engine is telling the command the truth about.

Why the default is an allowlist. Not because it stops an 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 (docs/guides/run-workflows.md, "workflow sources are executed code"). The allowlist earns its place for three narrower, real reasons: it bounds ACCIDENTAL exposure — the ambient shell of whoever ran akm workflow run (or the CI job that did) routinely carries tokens for unrelated services, and a third-party workflow step that merely prints its environment should not get them for free; it makes the environment surface EXPLICIT and REVIEWABLE — what a command can see is this constant 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 — profile.envPassthrough in integrations/agent/spawn.ts has always built agent-harness children this way, and the SAME collectAllowlistedEnv does it here, so there is one mechanism to review instead of two.

Capture and overflow semantics

Moved verbatim from runExecUnit's doc comment:

Run one exec unit and map its process outcome onto the dispatch vocabulary: non-zero exit → non_zero_exit, wall-clock expiry → timeout, cancellation → aborted, a child that never started → spawn_failed. All four are pre-existing AgentFailureReason members, so retry.on keeps working unchanged. The out-of-taxonomy exec_cwd_escape, exec_output_limit, exec_context_too_large and exec_capture_incomplete are deliberate: each is tampering, a runaway, an authoring bug, or work that ALREADY RAN — never a transient — so no retry.on value can ever re-dispatch one.

An INCOMPLETE STDOUT capture is a failure, never a partial artifact. exitCode === 0 is not on its own proof that stdout was fully read: a pipe can error, and the stream-drain timeout can fire while the command LEADER has already exited 0 because a background descendant still holds the stdout fd open. Both leave a PREFIX, and promoting it would hand the next step, the gate judge and steps.<id>.output a silently truncated artifact. So the unit fails instead, through the same shared classifier (streamCaptureFailure) the agent spawn path uses. Only STDOUT is fatal here — stderr is a diagnostic channel that never contributes to the artifact, so a stderr drain that did not finish leaves the unit's actual result intact. The stdout reason is exec_capture_incomplete, deliberately OUTSIDE the retry.on taxonomy, for the same reason journal_write_failed is: the command RAN TO COMPLETION and exited 0 — what failed is akm's record of it. A retryable reason here would let retry.on: [spawn_failed] re-dispatch byte-identical argv for a command that already deployed, already published, already migrated.

Output OVERFLOW does not fail a command that passed. Crossing WORKFLOW_MAX_EXEC_OUTPUT_BYTES is a different condition: the reader DID drain the pipe to its end, it just stopped RETAINING, so the child never blocked and its exit code is real. Overflow splits by what the unit PROMISED about its output: no declared output: schema → success, with the artifact carrying a WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER block naming both byte counts; a declared output: schema → exec_output_limit, since a truncated JSON prefix cannot parse and promoting it would corrupt every downstream reference to the typed artifact. stderr overflow never fails anything.

Consequences

Provenance