akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/workflows/exec/exec-unit.js

@@ -2,21 +2,12 @@
 // 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/.
 /**
- * The `exec` unit runner — the ONE place a frozen workflow spawns a shell
- * command as a unit: argv-only (never a shell string), non-blocking,
- * detached with a SIGTERM→SIGKILL ladder against the whole process group,
- * cwd-contained by a resolved-path recheck, resource-bounded (timeout,
- * output bytes, context size), and allowlisted-environment (see
- * {@link childEnv}). `env` values reaching this module are already resolved
- * from `env:` bindings by NAME — the caller scrubs the outcome with
- * `redactUnitOutcome` before anything is journaled. A LEAF module by
- * layering (Node built-ins, `core/spawn-env`, `core/subprocess`, `core/warn`,
- * the import-free `workflows/resource-limits` only).
- *
- * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md
- * for the full per-invariant design history.
- *
- * @module workflows/exec/exec-unit
+ * The `exec` unit runner — the one place a frozen workflow spawns a command:
+ * argv-only, detached with a SIGTERM→SIGKILL ladder against the process group,
+ * cwd-contained by a resolved-path recheck, bounded (timeout, output bytes,
+ * context size), with an allowlisted environment ({@link childEnv}). The
+ * caller redacts the outcome before anything is journaled.
+ * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -26,30 +17,16 @@ import { runManagedSubprocess, streamCaptureFailure, } from "../../core/subproce
 import { warn } from "../../core/warn.js";
 import { execContextLimits, utf8Bytes, WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER, WORKFLOW_MAX_EXEC_OUTPUT_BYTES, WORKFLOW_UNIT_DIAGNOSTIC_CLIP, } from "../resource-limits.js";
 /**
- * Max characters of a failed command's stderr retained in the unit's `error`
- * diagnostic.
- *
- * Deliberately BELOW {@link WORKFLOW_UNIT_DIAGNOSTIC_CLIP}: the composed
- * diagnostic reads `<what happened>. stderr (last N chars): <tail>`, and the
- * journal clips that COMPOSED string head-first. Reserving 500 characters for
- * the prefix keeps the whole stderr tail — the part that actually says why the
- * command failed — inside the journaled and displayed diagnostic, instead of
- * losing its final few hundred characters to the outer clip.
+ * Max characters of a failed command's stderr tail kept in its diagnostic —
+ * below {@link WORKFLOW_UNIT_DIAGNOSTIC_CLIP} so the journal's head-first clip
+ * of the composed message never cuts the tail.
  */
 const EXEC_STDERR_DIAGNOSTIC_CLIP = WORKFLOW_UNIT_DIAGNOSTIC_CLIP - 500;
 /**
- * The DEFAULT environment allowlist for an exec unit's child — the single
- * definition of the EXEC list; `exec.passEnv` extends it per unit. Extends
- * {@link COMMON_SPAWN_ENV_PASSTHROUGH} (the same baseline agent-harness
- * children use) plus POSIX/Windows names load-bearing for ordinary commands
- * (PATH, HOME, USER/LOGNAME, SHELL, locale, TERM, TZ, TMPDIR, the
- * {@link WIN32_SPAWN_ENV_FLOOR}, Windows toolchain roots) and
- * `AKM_EVENT_SOURCE` (provenance, DRIFT-6). Deliberately ABSENT and reachable
- * only through `exec.passEnv` / `env:`: credentials, cloud/CI vars, and the
- * proxy family.
- *
- * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md
- * for the per-entry rationale and why the default is an allowlist at all.
+ * The default environment allowlist for an exec unit's child (`exec.passEnv`
+ * extends it): the agent-harness baseline plus names ordinary commands need
+ * and `AKM_EVENT_SOURCE`. Credentials, cloud/CI vars, and proxies reach a
+ * child only through `pass_env` or `env:`.
  */
 export const EXEC_DEFAULT_ENV_PASSTHROUGH = [
     // PATH, HOME, USER, LANG, LC_ALL, TERM, TMPDIR, AKM_EVENT_SOURCE
@@ -70,21 +47,11 @@ export const EXEC_DEFAULT_ENV_PASSTHROUGH = [
     "ProgramFiles",
 ];
 /**
- * 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 pre-existing
- * `AgentFailureReason` members, so `retry.on` keeps working). 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 always a failure, never a partial artifact;
- * output OVERFLOW past {@link WORKFLOW_MAX_EXEC_OUTPUT_BYTES} does not fail a
- * command that otherwise passed unless the unit declared an `output:` schema
- * (a truncated JSON prefix cannot parse).
- *
- * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md
- * for the full capture/overflow reasoning.
+ * Run one exec unit and map its outcome onto the dispatch vocabulary
+ * (`non_zero_exit`, `timeout`, `aborted`, `spawn_failed` — retryable). The
+ * `exec_*` reasons (cwd escape, output limit, context too large, incomplete
+ * capture) are deliberately outside `retry.on`. Output overflow fails only a
+ * unit that declared an `output:` schema.
  */
 export async function runExecUnit(input) {
     const cwd = await resolveExecCwd(input);
@@ -98,11 +65,7 @@ export async function runExecUnit(input) {
         cwd: cwd.path,
         env: childEnv(input.exec, input.env, input.context, input.eventSource),
         timeoutMs: input.timeoutMs,
-        // stdout IS this unit's artifact, so RETENTION is BOUNDED: an unbounded
-        // capture is memory the akm process spends on a command's behalf with no
-        // ceiling at all until it exits or the (default 10-minute) budget expires.
-        // The cap discards past the bound rather than killing — the command's own
-        // outcome is not akm's memory problem to solve.
+        // stdout is the artifact; retention is bounded (discarding past the cap, never killing).
         maxOutputBytes: WORKFLOW_MAX_EXEC_OUTPUT_BYTES,
         ...(input.signal ? { signal: input.signal } : {}),
         ...(input.spawnFn ? { spawnFn: input.spawnFn } : {}),
@@ -172,21 +135,10 @@ export async function runExecUnit(input) {
     if (result.stdoutRead.overflowed && input.hasOutputSchema) {
         return outputLimitFailure(input, display, result);
     }
-    // The promoted artifact is STDOUT. Trailing newlines are stripped, exactly
-    // like shell command substitution `$(…)`, so a one-line command's artifact is
-    // the value an author expects rather than the value plus a `\n`. stderr is a
-    // diagnostic channel only and never contributes to the artifact. When stdout
-    // overflowed, `stdout` already carries the truncation marker (which is
-    // deliberately the LAST thing in the artifact, so it survives the strip).
+    // The artifact is stdout with trailing newlines stripped, like `$(…)`; stderr is diagnostic only.
     return { ok: true, text: stripTrailingNewlines(stdout) };
 }
-/**
- * A drain report with nothing wrong in it, passed as the OTHER pipe so
- * {@link streamCaptureFailure} classifies exactly one of them.
- *
- * The classifier stays shared with the agent path — what a failed drain means
- * must not drift — while each caller decides which pipes are fatal for IT.
- */
+/** A clean drain report, passed as the other pipe so {@link streamCaptureFailure} classifies one. */
 const DRAINED_CLEAN = {
     text: "",
     timedOut: false,
@@ -194,14 +146,7 @@ const DRAINED_CLEAN = {
     bytesRead: 0,
     retainedBytes: 0,
 };
-/**
- * Report a stderr drain that did not finish on an otherwise successful unit.
- *
- * Warn-only by construction: the artifact is stdout, which was captured whole,
- * so there is nothing wrong with the unit's RESULT — only with how much of its
- * log tail akm holds. A dispatch result has no channel for a non-fatal note, so
- * the operator surface is the warn stream.
- */
+/** Warn about an unfinished stderr drain on an otherwise successful unit (its stdout artifact is whole). */
 function reportStderrCaptureFailure(input, display, result) {
     const stderrFailure = streamCaptureFailure(DRAINED_CLEAN, result.stderrRead);
     if (!stderrFailure)
@@ -216,14 +161,7 @@ function truncationNote(read) {
     return (`the command wrote ${read.bytesRead} bytes to stdout and only the first ${read.retainedBytes} were retained ` +
         `(the ${WORKFLOW_MAX_EXEC_OUTPUT_BYTES}-byte per-pipe capture limit)`);
 }
-/**
- * The captured stdout, with an unmistakable truncation block appended when the
- * retention cap discarded part of it.
- *
- * Truncated data must never be mistakable for complete data. The block names
- * both byte counts, so a reader can see exactly how much is missing rather
- * than inferring it from a suspiciously round length.
- */
+/** The captured stdout, with a truncation block naming both byte counts when the cap discarded some. */
 function markTruncatedStdout(result) {
     const read = result.stdoutRead;
     if (!read.overflowed)
@@ -235,17 +173,7 @@ function markTruncatedStdout(result) {
         `so its exit code is real, but THIS TEXT IS INCOMPLETE and must not be treated as the command's whole output. ` +
         `Have the command write bulk output to a file and print the path, or quiet it down.`);
 }
-/**
- * The output-cap failure for a unit that declared an `output:` schema —
- * deliberately UNMISTAKABLE.
- *
- * `text` is emptied rather than carrying the partial capture: for a failed unit
- * `text` is only a diagnostic (the durable evidence graph keeps a failure's
- * `failureReason` alone), and handing back several megabytes of a runaway
- * command's output as "the text" would just move the memory problem one layer
- * up. The byte counts go in the message instead, so the operator can see how far
- * past the cap the command ran.
- */
+/** The output-cap failure for a unit with an `output:` schema: no partial text, byte counts in the message. */
 function outputLimitFailure(input, display, result) {
     return {
         ok: false,
@@ -259,31 +187,9 @@ function outputLimitFailure(input, display, result) {
     };
 }
 /**
- * Refuse to spawn when the engine-authored `AKM_*` context would not fit in the
- * child's environment ON THIS PLATFORM.
- *
- * A workflow artifact has no bound comparable to an OS environment entry, so a
- * perfectly legitimate declared input can serialize into an `AKM_INPUTS` far
- * past what `execve` accepts. Left unchecked that surfaces as a bare `E2BIG`
- * from the spawn syscall — reported as `spawn_failed` with a message about
- * "argument list too long" that names neither the variable nor the artifact
- * that produced it. Checking here converts it into a located, actionable
- * failure BEFORE process creation is attempted.
- *
- * ## The ceiling is the CURRENT platform's, never the smallest one
- *
- * That translation is this check's ONLY job, which fixes its bound exactly: the
- * limits come from {@link execContextLimits} for the platform the run is on. A
- * guard that applied Windows' 32 767-character ceiling on Linux would fail
- * spawns the kernel would happily have accepted — inventing a failure instead of
- * explaining an inevitable one, which is a tripwire and not a guard. Workflows
- * that must also run on Windows should stay under the smaller bound; that is
- * documented guidance (`docs/reference/workflow-schema.md`), not something a
- * Linux host enforces.
- *
- * Only the engine-authored context is measured. The unit's `env:` bindings are
- * authored values a human wrote and sized; this is the surface where the SIZE
- * is data-dependent and therefore surprising.
+ * Name the `AKM_*` variable that would not fit in the child's environment on
+ * this platform ({@link execContextLimits}), instead of a bare E2BIG from the
+ * spawn. Only the engine-authored context is measured.
  */
 function checkExecContextSize(input) {
     const limits = execContextLimits(input.platform ?? process.platform);
@@ -315,12 +221,8 @@ function contextTooLarge(input, what, names, limits) {
 }
 /**
  * Resolve `exec.cwd` inside `baseDir` and prove containment against the
- * RESOLVED base (symlinks included). The syntactic checks the parser and the
- * decoder already ran are necessary but not sufficient: `reports` can be a
- * symlink to `/etc`, and only a realpath comparison catches that.
- *
- * Async on purpose: this runs once per unit — up to 10 000 times for one map
- * step — on the dispatch path that must never block (see the module note).
+ * resolved base (a symlinked `reports` could point at `/etc`). Async: it runs
+ * per unit on the dispatch path.
  */
 async function resolveExecCwd(input) {
     const base = path.resolve(input.baseDir);
@@ -351,22 +253,13 @@ async function isExistingDirectory(candidate) {
     }
 }
 /**
- * The child's environment, in three layers with fixed precedence: (1) the
- * BASE — {@link EXEC_DEFAULT_ENV_PASSTHROUGH} 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.
- *
- * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md
- * for why the default is an allowlist rather than full inheritance.
+ * The child's environment, in precedence order: the allowlist plus
+ * `exec.passEnv`; the resolved `env:` bindings; then the engine's `AKM_*`
+ * context, last so a binding cannot shadow it.
  */
 function childEnv(exec, bindings, context, eventSource) {
     const env = collectAllowlistedEnv(execAllowlist(exec));
-    // F-1 (spec §5.2 point 2): applied to the allowlisted BASE only when the
-    // ambient passthrough above left the name absent — an ambient
-    // AKM_EVENT_SOURCE already collected into `env` still wins, and this runs
-    // strictly BEFORE the bindings/context overlays below, so an authored
-    // `env:` binding (or the engine-authored context) still wins too.
+    // Only when absent from the base, and before the overlays, so ambient and authored values win.
     if (eventSource !== undefined && env.AKM_EVENT_SOURCE === undefined) {
         env.AKM_EVENT_SOURCE = eventSource;
     }

package/dist/workflows/exec/frozen-judge.js

@@ -2,41 +2,11 @@
 // 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/.
 /**
- * The gate judge built from the workflow's frozen current execution target.
- *
- * Two contracts this module owns, both of which the rest of the engine already
- * enforces for ordinary units and neither of which the judge may opt out of:
- *
- *  1. **Redaction.** A judge response IS journaled — `journalGateEvaluationFinish`
- *     (exec/step-work.ts) writes the parsed verdict into the gate row's
- *     `result_json`, and a judge failure's message becomes the blocked step's
- *     notes. So the judge outcome goes through the SAME scrub every unit outcome
- *     goes through: {@link collectWorkflowDispatchSensitiveValues} +
- *     {@link withDispatchRedaction} (exec/dispatch-redaction.ts). Nothing about
- *     a judge call reaches durable state before that scrub. Agent and direct-LLM
- *     judges share one prepared/lowered dispatch request; the manual completion
- *     path uses the same config-free dispatcher without opening an executor
- *     import cycle.
- *
- *  2. **Identity.** The dispatch request carries the REAL run/step and the gate's
- *     real node/unit ids — the same ids `journalGateEvaluationStart/Finish` write
- *     (`<stepId>.gate` / `<stepId>.gate:l<loop>`) — so per-dispatch telemetry and
- *     harness-side correlation describe the same thing the gate row describes.
- *     The identity is threaded in from the caller that writes the row
- *     ({@link SummaryJudge}'s `identity` argument); it is never synthesized here.
- *
- * A judge dispatch carries NO `env` bindings: the normalized gate target has
- * no environment key, so there is nothing authored to thread — and a step's
- * unit environment is scoped to the WORK,
- * not to the verifier. Redaction is unaffected: the sensitive-value set below
- * still covers the judge engine's credential and unsafe passthrough values.
- * Lowering notices are live execution metadata: units expose a typed result,
- * while judges retain their public string contract and emit only the common
- * lowerer's prompt/body-free notice projection through `warn()`. Current
- * result/evidence journal writers intentionally exclude these diagnostics;
- * this boundary makes no claim about future persistence ownership.
- *
- * @module workflows/exec/frozen-judge
+ * The gate judge built from the step's frozen judge target. Its outcome is
+ * journaled (the gate row, or a blocked step's notes), so it goes through the
+ * same dispatch redaction as every unit; its dispatch carries the real
+ * run/step and gate unit ids the gate row records. A judge carries no `env:`
+ * bindings (a step's environment belongs to the work, not the verifier).
  */
 import { warn } from "../../core/warn.js";
 import { collectWorkflowDispatchSensitiveValues, withDispatchRedaction } from "./dispatch-redaction.js";
@@ -45,13 +15,7 @@ import { dispatchWorkflowExecution, prepareWorkflowExecution, } from "./unit-dis
 export function gateNodeId(stepId) {
     return `${stepId}.gate`;
 }
-/**
- * Identity for one judge dispatch: the journaling caller's exact row identity
- * when it supplied one, else the owning run/step with the gate's node id as the
- * unit id. Either way the request names the REAL run — never a synthetic
- * `"gate"` placeholder, which made every judge dispatch indistinguishable from
- * every other one.
- */
+/** Identity for one judge dispatch: the caller's row identity, else the run/step with the gate node id. */
 function dispatchIdentity(owner, identity) {
     return identity ?? { ...owner, unitId: gateNodeId(owner.stepId) };
 }
@@ -67,23 +31,7 @@ function warnLoweringNotices(...groups) {
         }
     }
 }
-/**
- * Build a gate judge from the normalized frozen target without consulting live
- * config.
- *
- * `eventSource` (P1b spec §5.2 point 2, gap closed — code review): the task
- * runner's resolved provenance event source, threaded through exactly like
- * `executeStepSubgraph`'s units so a workflow-task run's judge dispatch is not
- * the one dispatch left silently unstamped. Spread onto the built
- * {@link UnitDispatchRequest} the same way every other optional field here is
- * — `undefined` for the manual `akm workflow step complete` judge
- * (`runtime/runs.ts`, which passes no 5th argument) and for `akm workflow run`
- * (no task context), so both stay byte-identical. When present, it flows
- * through the same `forwardedDispatchEventSource` precedence gate every other
- * "command"-kind dispatch uses (`unit-dispatch.ts`): the module doc above
- * already establishes a judge request never carries an authored `env:`
- * binding, so the gate always forwards it here.
- */
+/** Build a gate judge from the frozen target without consulting live config; `eventSource` stamps it like a unit. */
 export function frozenSummaryJudge(target, signal, dispatcher, owner, eventSource) {
     if (!target)
         return null;