akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/workflows/parser.js

@@ -33,10 +33,12 @@
 import { LineCounter, parseDocument } from "yaml";
 import { parseFrontmatterBlock } from "../core/asset/frontmatter.js";
 import { parseMarkdownToc } from "../core/asset/markdown.js";
+import { isContainedRelativePath } from "../core/common.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
+import { checkJsonSchemaDefinition, JSON_SCHEMA_SUBSET_SUPPORTED_KEYWORDS } from "../core/json-schema.js";
 import { parseReference } from "./program/expressions.js";
 import { PROGRAM_ISOLATION_KINDS, PROGRAM_ON_ERROR, PROGRAM_PARAM_NAME_PATTERN, PROGRAM_REDUCERS, PROGRAM_RETRY_REASONS, PROGRAM_STEP_ID_PATTERN, } from "./program/schema.js";
-import { jsonBytes, utf8Bytes, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_SOURCE_BYTES, WORKFLOW_MAX_STEPS, } from "./resource-limits.js";
+import { jsonBytes, utf8Bytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXEC_ARG_BYTES, WORKFLOW_MAX_EXEC_ARGV, WORKFLOW_MAX_EXEC_CWD_LENGTH, WORKFLOW_MAX_EXEC_PASS_ENV, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_GATE_LOOPS, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_SOURCE_BYTES, WORKFLOW_MAX_STEPS, WORKFLOW_MAX_TIMEOUT_MS, } from "./resource-limits.js";
 import { WORKFLOW_SCHEMA_VERSION, } from "./schema.js";
 import { runSemanticChecks } from "./validator.js";
 /** Envelope keys every AKM markdown asset carries ($ref'd from schemas/akm-asset-envelope.json). */
@@ -59,7 +61,10 @@ const TOP_LEVEL_KEYS = [...ENVELOPE_KEYS, ...WORKFLOW_KEYS];
 const DEFAULTS_KEYS = ["engine", "model", "timeout", "on_error", "llm"];
 const BUDGET_KEYS = ["max_tokens", "max_units"];
 const STEP_KEYS = ["id", "unit", "map", "route", "inputs", "output", "gate"];
-const UNIT_KEYS = ["engine", "model", "llm", "timeout", "retry", "on_error", "output", "env", "isolation"];
+const UNIT_KEYS = ["exec", "engine", "model", "llm", "timeout", "retry", "on_error", "output", "env", "isolation"];
+const EXEC_KEYS = ["command", "cwd", "pass_env", "inherit_env"];
+/** Unit keys that name an ENGINE dispatch and therefore cannot appear beside `exec:`. */
+const UNIT_ENGINE_KEYS = ["engine", "model", "llm"];
 const MAP_KEYS = ["over", "concurrency", "reducer", "unit"];
 const ROUTE_KEYS = ["input", "when", "default"];
 const RETRY_KEYS = ["max", "on"];
@@ -422,6 +427,10 @@ function parseParams(ctx, raw) {
             ctx.err(["params", paramName], `Param "${paramName}" must be a JSON Schema object (e.g. { type: string }).`);
             continue;
         }
+        if (jsonBytes(value) > WORKFLOW_MAX_SCHEMA_BYTES) {
+            ctx.err(["params", paramName], `Param "${paramName}" schema exceeds the 256 KiB resource limit.`);
+        }
+        checkSchemaDefinition(ctx, value, ["params", paramName], `Param "${paramName}" schema`);
         params[paramName] = value;
     }
     return Object.keys(params).length > 0 ? params : undefined;
@@ -437,10 +446,9 @@ function parseDefaults(ctx, raw) {
     checkUnknownKeys(ctx, raw, path, DEFAULTS_KEYS, `"defaults"`);
     const defaults = {};
     if (raw.engine !== undefined) {
-        if (typeof raw.engine === "string" && raw.engine.trim() !== "")
-            defaults.engine = raw.engine.trim();
-        else
-            ctx.err([...path, "engine"], `"defaults.engine" must be a non-empty engine name.`);
+        const engine = parseEngineName(ctx, raw.engine, [...path, "engine"], `"defaults.engine"`);
+        if (engine !== undefined)
+            defaults.engine = engine;
     }
     if (raw.model !== undefined) {
         if (typeof raw.model === "string" && raw.model.trim() !== "")
@@ -605,11 +613,24 @@ function parseUnit(ctx, raw, path, stepLabel) {
     }
     checkUnknownKeys(ctx, raw, path, UNIT_KEYS, `${stepLabel} "unit"`);
     const unit = { source: ctx.refAt(path) };
+    if (raw.exec !== undefined) {
+        const exec = parseExec(ctx, raw.exec, [...path, "exec"], stepLabel);
+        if (exec !== undefined)
+            unit.exec = exec;
+        // An exec unit dispatches no engine call, so every engine-selection key is
+        // a contradiction rather than a harmless extra. Reported per key so the
+        // author sees exactly which line to delete.
+        for (const key of UNIT_ENGINE_KEYS) {
+            if (raw[key] === undefined)
+                continue;
+            ctx.err([...path, key], `${stepLabel} "unit" declares both "exec" and "${key}". An exec unit runs a shell command and never ` +
+                `reaches an engine, so "${key}" would have no effect — remove one of the two.`);
+        }
+    }
     if (raw.engine !== undefined) {
-        if (typeof raw.engine === "string" && raw.engine.trim() !== "")
-            unit.engine = raw.engine.trim();
-        else
-            ctx.err([...path, "engine"], `${stepLabel} "engine" must be a non-empty engine name.`);
+        const engine = parseEngineName(ctx, raw.engine, [...path, "engine"], `${stepLabel} "engine"`);
+        if (engine !== undefined)
+            unit.engine = engine;
     }
     if (raw.model !== undefined) {
         if (typeof raw.model === "string" && raw.model.trim() !== "")
@@ -634,7 +655,16 @@ function parseUnit(ctx, raw, path, stepLabel) {
         unit.output = output;
     if (raw.env !== undefined) {
         if (Array.isArray(raw.env) && raw.env.every((entry) => typeof entry === "string" && entry.trim() !== "")) {
-            unit.env = raw.env.map((entry) => entry.trim());
+            const envRefs = raw.env.map((entry) => entry.trim());
+            // Same decoder uniqueness requirement as `inputs` above: duplicates linted
+            // clean and then failed the run with an unlocated frozen-plan error.
+            const duplicate = envRefs.find((ref, i) => envRefs.indexOf(ref) !== i);
+            if (duplicate !== undefined) {
+                ctx.err([...path, "env"], `${stepLabel} "env" contains a duplicate entry: "${duplicate}".`);
+            }
+            else {
+                unit.env = envRefs;
+            }
         }
         else {
             ctx.err([...path, "env"], `${stepLabel} "env" must be a list of non-empty env asset refs.`);
@@ -645,6 +675,124 @@ function parseUnit(ctx, raw, path, stepLabel) {
         unit.isolation = isolation;
     return unit;
 }
+/**
+ * Parse `unit.exec` — the argv-array shell-command surface.
+ *
+ * Deliberately NO shell-string spelling: the child is spawned directly from
+ * this array, so shell metacharacters are inert literal bytes and the whole
+ * quoting/injection class is structurally absent. An author who wants a
+ * pipeline writes the interpreter explicitly (`["bash", "-lc", "…"]`), which
+ * keeps that decision visible in the frontmatter diff.
+ */
+function parseExec(ctx, raw, path, stepLabel) {
+    if (!isPlainRecord(raw)) {
+        ctx.err(path, `${stepLabel} "exec" must be a mapping with a "command" argv list.`);
+        return undefined;
+    }
+    checkUnknownKeys(ctx, raw, path, EXEC_KEYS, `${stepLabel} "exec"`);
+    const command = parseExecCommand(ctx, raw.command, [...path, "command"], stepLabel);
+    if (command === undefined)
+        return undefined;
+    const exec = { command };
+    const cwd = parseExecCwd(ctx, raw.cwd, [...path, "cwd"], stepLabel);
+    if (cwd !== undefined)
+        exec.cwd = cwd;
+    const passEnv = parseExecPassEnv(ctx, raw.pass_env, [...path, "pass_env"], stepLabel);
+    if (passEnv !== undefined)
+        exec.passEnv = passEnv;
+    if (raw.inherit_env !== undefined) {
+        if (typeof raw.inherit_env !== "boolean") {
+            ctx.err([...path, "inherit_env"], `${stepLabel} "exec.inherit_env" must be true or false. true gives the command akm's whole environment ` +
+                `instead of the default allowlist; omit it (or write false) to keep the allowlist.`);
+        }
+        else if (raw.inherit_env) {
+            exec.inheritEnv = true;
+        }
+    }
+    return exec;
+}
+/**
+ * `pass_env:` — extra parent-process env var NAMES the child may see on top of
+ * the default allowlist. NAMES ONLY: a value would be a plaintext secret in the
+ * frozen plan, which is exactly what `env:` bindings exist to avoid.
+ */
+function parseExecPassEnv(ctx, raw, path, stepLabel) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        ctx.err(path, `${stepLabel} "exec.pass_env" must be a non-empty list of environment variable NAMES to copy through from ` +
+            `akm's own environment, e.g. pass_env: [CARGO_HOME]. Values never appear here — use "env:" bindings for those.`);
+        return undefined;
+    }
+    if (raw.length > WORKFLOW_MAX_EXEC_PASS_ENV) {
+        ctx.err(path, `${stepLabel} "exec.pass_env" must have at most ${WORKFLOW_MAX_EXEC_PASS_ENV} entries. A command needing ` +
+            `more than that wants "inherit_env: true", which says so explicitly.`);
+        return undefined;
+    }
+    const names = [];
+    for (const [index, entry] of raw.entries()) {
+        if (typeof entry !== "string" || !WORKFLOW_ENV_VAR_NAME_PATTERN.test(entry)) {
+            ctx.err(path, `${stepLabel} "exec.pass_env[${index}]" must be an environment variable name matching ` +
+                `${WORKFLOW_ENV_VAR_NAME_PATTERN.source}.`);
+            return undefined;
+        }
+        if (names.includes(entry)) {
+            ctx.err(path, `${stepLabel} "exec.pass_env" lists "${entry}" more than once.`);
+            return undefined;
+        }
+        names.push(entry);
+    }
+    return names;
+}
+/** The argv array itself: 1..WORKFLOW_MAX_EXEC_ARGV bounded non-empty strings. */
+function parseExecCommand(ctx, raw, path, stepLabel) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        ctx.err(path, `${stepLabel} "exec" requires "command": a non-empty argv list, e.g. command: ["bun", "run", "test:unit"]. ` +
+            `A single shell string is not accepted — the command is spawned directly, never through a shell.`);
+        return undefined;
+    }
+    if (raw.length > WORKFLOW_MAX_EXEC_ARGV) {
+        ctx.err(path, `${stepLabel} "exec.command" must have at most ${WORKFLOW_MAX_EXEC_ARGV} entries.`);
+        return undefined;
+    }
+    const argv = [];
+    for (const [index, entry] of raw.entries()) {
+        if (typeof entry !== "string" || entry === "") {
+            ctx.err(path, `${stepLabel} "exec.command[${index}]" must be a non-empty string.`);
+            return undefined;
+        }
+        if (utf8Bytes(entry) > WORKFLOW_MAX_EXEC_ARG_BYTES) {
+            ctx.err(path, `${stepLabel} "exec.command[${index}]" exceeds ${WORKFLOW_MAX_EXEC_ARG_BYTES} bytes.`);
+            return undefined;
+        }
+        argv.push(entry);
+    }
+    return argv;
+}
+/**
+ * The optional relative `cwd:`. Rejected here (statically) for absolute paths
+ * and `..` segments; containment against the resolved base directory is
+ * re-checked at dispatch, so a symlinked subdirectory cannot escape either.
+ */
+function parseExecCwd(ctx, raw, path, stepLabel) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "string" || raw.trim() === "") {
+        ctx.err(path, `${stepLabel} "exec.cwd" must be a non-empty relative path inside the unit's working directory.`);
+        return undefined;
+    }
+    const value = raw.trim();
+    if (value.length > WORKFLOW_MAX_EXEC_CWD_LENGTH) {
+        ctx.err(path, `${stepLabel} "exec.cwd" exceeds ${WORKFLOW_MAX_EXEC_CWD_LENGTH} characters.`);
+        return undefined;
+    }
+    if (!isContainedRelativePath(value)) {
+        ctx.err(path, `${stepLabel} "exec.cwd" (${JSON.stringify(value)}) must be a RELATIVE path inside the unit's working ` +
+            `directory — absolute paths, Windows drive letters, "~", and ".." segments are rejected.`);
+        return undefined;
+    }
+    return value;
+}
 function parseMap(ctx, raw, path, stepLabel) {
     if (!isPlainRecord(raw)) {
         ctx.err(path, `${stepLabel} "map" must be a mapping with an "over" key.`);
@@ -661,11 +809,14 @@ function parseMap(ctx, raw, path, stepLabel) {
     }
     let concurrency;
     if (raw.concurrency !== undefined) {
-        if (typeof raw.concurrency === "number" && Number.isInteger(raw.concurrency) && raw.concurrency > 0) {
+        if (typeof raw.concurrency === "number" &&
+            Number.isInteger(raw.concurrency) &&
+            raw.concurrency > 0 &&
+            raw.concurrency <= WORKFLOW_MAX_CONCURRENCY) {
             concurrency = raw.concurrency;
         }
         else {
-            ctx.err([...path, "concurrency"], `${stepLabel} "concurrency" must be a positive integer.`);
+            ctx.err([...path, "concurrency"], `${stepLabel} "concurrency" must be an integer from 1 through ${WORKFLOW_MAX_CONCURRENCY}.`);
         }
     }
     const reducer = parseEnumField(ctx, raw.reducer, [...path, "reducer"], `${stepLabel} "reducer"`, PROGRAM_REDUCERS);
@@ -717,6 +868,13 @@ function parseRoute(ctx, raw, path, stepLabel, stepIndex, routeChecks) {
                 return;
             }
             const match = String(branch.match);
+            // The frozen-plan decoder requires every `when` key to be non-empty, so an
+            // empty match parsed and linted clean and then failed the run with an
+            // unlocated "Invalid frozen workflow plan". Reject it here, at the line.
+            if (match === "") {
+                ctx.errAtLine(matchLine, `${stepLabel} "when[${i}].match" must not be empty.`);
+                return;
+            }
             if (typeof branch.step !== "string" || branch.step.trim() === "") {
                 ctx.err([...branchPath, "step"], `${stepLabel} "when[${i}].step" must be a step id string.`);
                 return;
@@ -759,12 +917,21 @@ function parseInputs(ctx, raw, path, stepLabel) {
         ctx.err(path, `${stepLabel} "inputs" must contain at most ${WORKFLOW_MAX_INPUTS} entries.`);
     }
     const out = [];
+    // The frozen-plan decoder requires uniqueness (validateStringArray(..., true)),
+    // so duplicates parsed and linted clean and then failed the run with an
+    // unlocated "Invalid frozen workflow plan". Reject them here, on the entry.
+    const seen = new Set();
     raw.forEach((entry, i) => {
         if (typeof entry !== "string" || entry.trim() === "") {
             ctx.err([...path, i], `${stepLabel} "inputs[${i}]" must be a non-empty reference string.`);
             return;
         }
         const value = entry.trim();
+        if (seen.has(value)) {
+            ctx.err([...path, i], `${stepLabel} "inputs[${i}]" duplicates an earlier entry: "${value}".`);
+            return;
+        }
+        seen.add(value);
         checkReferenceSyntax(ctx, value, [...path, i], `${stepLabel} "inputs[${i}]"`);
         out.push(value);
     });
@@ -778,11 +945,14 @@ function parseGate(ctx, raw, path, stepLabel) {
     checkUnknownKeys(ctx, raw, path, GATE_KEYS, `${stepLabel} "gate"`);
     const gate = {};
     if (raw.max_loops !== undefined) {
-        if (typeof raw.max_loops === "number" && Number.isInteger(raw.max_loops) && raw.max_loops >= 1) {
+        if (typeof raw.max_loops === "number" &&
+            Number.isInteger(raw.max_loops) &&
+            raw.max_loops >= 1 &&
+            raw.max_loops <= WORKFLOW_MAX_GATE_LOOPS) {
             gate.maxLoops = raw.max_loops;
         }
         else {
-            ctx.err([...path, "max_loops"], `${stepLabel} "gate.max_loops" must be an integer >= 1.`);
+            ctx.err([...path, "max_loops"], `${stepLabel} "gate.max_loops" must be an integer from 1 through ${WORKFLOW_MAX_GATE_LOOPS}.`);
         }
     }
     return gate;
@@ -790,6 +960,26 @@ function parseGate(ctx, raw, path, stepLabel) {
 // ---------------------------------------------------------------------------
 // Field helpers
 // ---------------------------------------------------------------------------
+/**
+ * Engine names must already satisfy the frozen-plan grammar
+ * (`WORKFLOW_ENGINE_NAME_PATTERN`, max 63 chars) at parse time — the decoder
+ * enforces the same bound on persisted plans, and a name that only fails there
+ * surfaces as an unlocated "Invalid frozen workflow plan" at `workflow run`.
+ */
+function parseEngineName(ctx, raw, path, label) {
+    if (typeof raw !== "string" || raw.trim() === "") {
+        ctx.err(path, `${label} must be a non-empty engine name.`);
+        return undefined;
+    }
+    const name = raw.trim();
+    if (!WORKFLOW_ENGINE_NAME_PATTERN.test(name) || name.length > WORKFLOW_MAX_ENGINE_NAME_LENGTH) {
+        ctx.err(path, `${label} has an invalid engine name ${JSON.stringify(name)}. Engine names are lowercase words of letters ` +
+            `and digits separated by single dashes, starting with a letter (e.g. "code-review-llm"), at most ` +
+            `${WORKFLOW_MAX_ENGINE_NAME_LENGTH} characters.`);
+        return undefined;
+    }
+    return name;
+}
 function parseRetry(ctx, raw, path, stepLabel) {
     if (raw === undefined)
         return undefined;
@@ -799,8 +989,8 @@ function parseRetry(ctx, raw, path, stepLabel) {
     }
     checkUnknownKeys(ctx, raw, path, RETRY_KEYS, `${stepLabel} "retry"`);
     let ok = true;
-    if (!(typeof raw.max === "number" && Number.isInteger(raw.max) && raw.max >= 0)) {
-        ctx.err([...path, "max"], `${stepLabel} "retry.max" is required and must be a non-negative integer.`);
+    if (!(typeof raw.max === "number" && Number.isInteger(raw.max) && raw.max >= 0 && raw.max <= WORKFLOW_MAX_RETRIES)) {
+        ctx.err([...path, "max"], `${stepLabel} "retry.max" is required and must be an integer from 0 through ${WORKFLOW_MAX_RETRIES}.`);
         ok = false;
     }
     const on = [];
@@ -826,7 +1016,7 @@ function parseTimeoutField(ctx, raw, path, label) {
         return undefined;
     if (typeof raw === "number") {
         if (Number.isInteger(raw) && raw > 0)
-            return raw;
+            return checkTimeoutCeiling(ctx, raw, path, label, String(raw));
         ctx.err(path, `${label} has a non-positive timeout ${JSON.stringify(raw)}. ${TIMEOUT_HINT}.`);
         return undefined;
     }
@@ -849,7 +1039,20 @@ function parseTimeoutField(ctx, raw, path, label) {
         ctx.err(path, `${label} has a non-positive timeout "${raw}". Use a positive duration or "none".`);
         return undefined;
     }
-    return timeoutMs;
+    return checkTimeoutCeiling(ctx, timeoutMs, path, label, raw);
+}
+/**
+ * Timeouts freeze into `IrInvocation.timeoutMs`, whose decoder bound is
+ * `WORKFLOW_MAX_TIMEOUT_MS` (setTimeout's 32-bit signed ceiling). Enforce the
+ * same ceiling here so an oversized duration fails with a line anchor instead
+ * of an unlocated decode error at `workflow run`.
+ */
+function checkTimeoutCeiling(ctx, timeoutMs, path, label, raw) {
+    if (timeoutMs <= WORKFLOW_MAX_TIMEOUT_MS)
+        return timeoutMs;
+    ctx.err(path, `${label} has a timeout "${raw}" above the maximum of ${WORKFLOW_MAX_TIMEOUT_MS} ms (about 24.8 days). ` +
+        `Use a shorter duration or "none" for no timeout.`);
+    return undefined;
 }
 function parseEnumField(ctx, raw, path, label, allowed) {
     if (raw === undefined)
@@ -938,8 +1141,28 @@ function parseSchemaObject(ctx, raw, path, label) {
     if (jsonBytes(raw) > WORKFLOW_MAX_SCHEMA_BYTES) {
         ctx.err(path, `${label} exceeds the 256 KiB resource limit.`);
     }
+    checkSchemaDefinition(ctx, raw, path, label);
     return raw;
 }
+/**
+ * Validate an author-declared schema AS a schema (`output:` and `params`
+ * declarations). The runtime enforces only a JSON Schema subset
+ * (`core/json-schema.ts`); a typo'd `type` or a keyword the subset ignores
+ * would silently constrain nothing at run time — a gate depending on a no-op
+ * schema is worse than a loud failure here, so both are parse ERRORS.
+ */
+function checkSchemaDefinition(ctx, schema, path, label) {
+    for (const issue of checkJsonSchemaDefinition(schema)) {
+        const issuePath = [...path, ...issue.path];
+        if (issue.kind === "unsupported") {
+            ctx.err(issuePath, `${label} (at ${issue.pointer}): ${issue.message}. Supported JSON Schema keywords: ` +
+                `${JSON_SCHEMA_SUBSET_SUPPORTED_KEYWORDS}.`);
+        }
+        else {
+            ctx.err(issuePath, `${label} is not a valid JSON Schema (at ${issue.pointer}): ${issue.message}.`);
+        }
+    }
+}
 function checkReferenceSyntax(ctx, text, path, label) {
     const result = parseReference(text);
     if (!result.ok)

package/dist/workflows/program/schema.js

@@ -49,3 +49,27 @@ export const PROGRAM_STEP_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
  * identifiers (no dots/dashes).
  */
 export const PROGRAM_PARAM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The ONE structural projection of an exec spec — ONE encoding per state.
+ *
+ * Every layer that carries an exec forward derives from this: the compiled
+ * draft, the frozen plan (which layers `timeoutMs` on top), and the summary
+ * `akm workflow show` prints. Written out per layer instead, a field added to
+ * {@link ProgramExec} reaches whichever copies were remembered and silently
+ * vanishes from the rest — and nothing catches it, because every key here is
+ * optional, so an omitted spread is not a type error. What it would cost:
+ * either the frozen plan loses a field the author wrote (and the canonical
+ * hash preimage stops matching the authored intent), or `show` describes
+ * something other than what runs.
+ *
+ * The ABSENCE of both env keys is the default allowlist. The parser rejects an
+ * empty `pass_env` outright, so no layer has to distinguish absent from empty.
+ */
+export function projectExecCore(exec) {
+    return {
+        command: [...exec.command],
+        ...(exec.cwd ? { cwd: exec.cwd } : {}),
+        ...(exec.passEnv && exec.passEnv.length > 0 ? { passEnv: [...exec.passEnv] } : {}),
+        ...(exec.inheritEnv ? { inheritEnv: true } : {}),
+    };
+}

package/dist/workflows/renderer.js

@@ -6,12 +6,13 @@
  * unification). One format now: reads the frontmatter+body document via
  * `parseWorkflow` and projects the validated `WorkflowDocument` down to the
  * public `ShowResponse` shape and into search hints for the indexer,
- * including a compact per-step orchestration summary (engine/model,
- * `map.over` reference, route table) when the step declares one.
+ * including a compact per-step orchestration summary (engine/model or an exec
+ * unit's argv, `map.over` reference, route table) when the step declares one.
  */
 import { displayRef } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
 import { parseWorkflow } from "./parser.js";
+import { projectExecCore } from "./program/schema.js";
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -65,16 +66,43 @@ function projectParameters(document) {
  * compiler does (per-unit override wins), `fanOut.over` carries the raw
  * reference string, and `route` carries the explicit input + branch table.
  * Returns undefined when the step declares nothing worth summarizing.
+ *
+ * ## exec units
+ *
+ * An `exec` unit runs a shell command and names NO engine — the parser rejects
+ * `engine`/`model`/`llm` alongside `exec:`. Merging `defaults.engine` into its
+ * summary would make `show` state something untrue about what will run, so the
+ * two fields are suppressed and the argv is projected instead, under `exec`
+ * (field presence carries the dispatch kind, exactly like `fanOut`/`route`
+ * carry the step kind).
+ *
+ * `timeoutMs` still merges the defaults: an exec unit really does inherit
+ * `defaults.timeout`, so that number stays true for it.
+ *
+ * The argv is shown IN FULL, never clipped. It is authored literally in the
+ * asset — the `${{ … }}` interpolation language is gone, so nothing in it is
+ * resolved from the environment, from a secret ref, or from a prior step's
+ * output — which makes it (a) safe to display, since every byte is already
+ * visible in the workflow file `show` is rendering, and (b) pointless to clip:
+ * the whole finding this projection answers is `show` describing something
+ * other than what runs, and a truncated argv is that same bug in miniature.
+ * The parser bounds it anyway (`WORKFLOW_MAX_EXEC_ARGV` entries of
+ * `WORKFLOW_MAX_EXEC_ARG_BYTES`), and it is far smaller than the step
+ * `instructions` this same projection already carries whole.
  */
 function summarizeStepOrchestration(step, defaults) {
     const unit = step.unit ?? step.map?.unit;
-    const engine = unit?.engine ?? defaults?.engine;
-    const model = unit?.model ?? defaults?.model;
+    const exec = unit?.exec;
+    const engine = exec ? undefined : (unit?.engine ?? defaults?.engine);
+    const model = exec ? undefined : (unit?.model ?? defaults?.model);
     const timeoutMs = unit?.timeoutMs !== undefined ? unit.timeoutMs : defaults?.timeoutMs;
     const summary = {
         ...(engine !== undefined ? { engine } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        // Same projection the draft and the frozen plan use, so what `show` prints
+        // cannot drift from what runs.
+        ...(exec ? { exec: projectExecCore(exec) } : {}),
         ...(step.map
             ? {
                 fanOut: {

package/dist/workflows/resource-limits.js

@@ -14,6 +14,188 @@ export const WORKFLOW_MAX_JSON_DEPTH = 64;
 export const WORKFLOW_MAX_MAP_EXPANSION = 10_000;
 /** Max declared `inputs:` reference strings on one unit/map step. */
 export const WORKFLOW_MAX_INPUTS = 64;
+// ── Dispatch-significant bounds shared across validation layers ──────────────
+//
+// Defined ONCE here so the three enforcement layers cannot drift:
+//   1. the parser (`../parser.ts`) — line-anchored authoring-time errors,
+//   2. the published JSON Schema (`schemas/akm-workflow.json`) — mirrored
+//      `maximum`/`pattern`/`maxLength` values, pinned against these constants
+//      by `tests/integration/workflows/schema-drift.test.ts`,
+//   3. the strict frozen-plan decoder (`./ir/schema.ts`) — the corruption
+//      gate for persisted plans.
+// A bound enforced only by the decoder surfaces as a terse, unlocated
+// "Invalid frozen workflow plan" at `workflow run` — after lint and
+// `workflow create` already said the document was fine.
+/** Max per-step map fan-out concurrency (also the run-level concurrency ceiling). */
+export const WORKFLOW_MAX_CONCURRENCY = 64;
+/** Max evaluator-optimizer gate loops per step. */
+export const WORKFLOW_MAX_GATE_LOOPS = 100;
+/** Max retry attempts per unit. */
+export const WORKFLOW_MAX_RETRIES = 100;
+/** Max timeout in milliseconds (setTimeout's 32-bit signed ceiling: 2^31-1, ~24.8 days). */
+export const WORKFLOW_MAX_TIMEOUT_MS = 2 ** 31 - 1;
+/** Engine names: lowercase dash-separated runs of letters/digits, starting with a letter. */
+export const WORKFLOW_ENGINE_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+export const WORKFLOW_MAX_ENGINE_NAME_LENGTH = 63;
+// ── exec (shell) unit bounds ─────────────────────────────────────────────────
+/**
+ * Max entries in an exec unit's `command:` argv array. Generous for a real
+ * command line, small enough that a corrupted plan cannot ask the OS to spawn
+ * a megabyte of arguments.
+ */
+export const WORKFLOW_MAX_EXEC_ARGV = 64;
+/** Max UTF-8 bytes of ONE argv entry (well under every platform's ARG_MAX per-arg limit). */
+export const WORKFLOW_MAX_EXEC_ARG_BYTES = 4096;
+/** Max characters of an exec unit's relative `cwd:`. */
+export const WORKFLOW_MAX_EXEC_CWD_LENGTH = 1024;
+/**
+ * Max entries in an exec unit's `pass_env:` list.
+ *
+ * `pass_env` is the "one or two more toolchain variables" escape hatch, not a
+ * second way to spell `inherit_env:` — a workflow reaching for more than this
+ * many names wants full inheritance and should say so where a reviewer can see
+ * it.
+ */
+export const WORKFLOW_MAX_EXEC_PASS_ENV = 32;
+/**
+ * Grammar for an env var NAME in `pass_env:`. Matches the frozen-plan
+ * `envPassthrough` grammar in `ir/schema.ts` so both allowlist surfaces accept
+ * exactly the same identifiers.
+ */
+export const WORKFLOW_ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Default wall-clock timeout for an exec unit that declares no `timeout:` and
+ * inherits no document `defaults.timeout`.
+ *
+ * 10 minutes matches `DEFAULT_LLM_TIMEOUT_MS`. Unlike an agent harness (which
+ * owns its own lifetime, hence `DEFAULT_AGENT_TIMEOUT_MS === null`), a shell
+ * command has NO lifetime discipline of its own: an unbounded default would let
+ * a hung `npm install` or an interactive prompt wedge a workflow run forever.
+ * Authors who genuinely need an unbounded command write `timeout: none`.
+ */
+export const DEFAULT_EXEC_TIMEOUT_MS = 600_000;
+/**
+ * Max BYTES of ONE captured pipe an exec unit RETAINS in memory (stdout and
+ * stderr are retained separately).
+ *
+ * This is a RETENTION cap, not a permission to run. Without it the capture is
+ * bounded only by the command's exit or the wall timeout, so a command that
+ * writes continuously (`yes`, a verbose test loop) grows a string in the akm
+ * process until the host runs out of memory — and the default budget gives it
+ * ten minutes to do so. What the cap buys is a BOUND where there was none: the
+ * retained prefix is promoted into the unit's outcome text and every outcome is
+ * held until the step reduces, so the worst case is (units in the STEP × this
+ * cap) rather than unbounded — the step's width, not the in-flight width, is
+ * what sizes it, up to {@link WORKFLOW_MAX_MAP_EXPANSION}.
+ *
+ * On reaching the cap the reader switches to DRAIN-AND-DISCARD: it keeps
+ * pulling from the pipe (so the child never blocks on backpressure) and stops
+ * RETAINING. The command therefore runs to completion and its real exit code
+ * stands — a passing-but-chatty test suite is no longer failed over log volume.
+ * What overflow costs is honesty about the artifact, and that is paid two ways
+ * in `exec/exec-unit.ts`:
+ *
+ *   - no declared `output:` schema → the unit succeeds and its artifact carries
+ *     an unmistakable {@link WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER} block naming
+ *     the total and retained byte counts, so truncated text can never be
+ *     mistaken for the whole output;
+ *   - a declared `output:` schema → the unit fails `exec_output_limit`, because
+ *     validating a truncated JSON prefix is meaningless and promoting it would
+ *     corrupt every downstream reference. That is the residual failure the cap
+ *     genuinely justifies.
+ *
+ * 8 MiB is deliberately generous — 8× the whole-row evidence cap
+ * ({@link WORKFLOW_MAX_EVIDENCE_JSON_BYTES}), so any output that could survive
+ * persistence intact fits many times over, and an ordinary full test/build log
+ * is nowhere near it.
+ */
+export const WORKFLOW_MAX_EXEC_OUTPUT_BYTES = 8 * 1024 * 1024;
+/**
+ * Marker stamped on an exec artifact that was RETAINED ONLY IN PART because the
+ * command wrote past {@link WORKFLOW_MAX_EXEC_OUTPUT_BYTES}.
+ *
+ * Deliberately ugly and unique, exactly like `WORKFLOW_EVIDENCE_TRUNCATED_MARKER`
+ * (`runtime/runs.ts`) — the same idiom for the same reason: a truncated value
+ * must NEVER be mistakable for a complete one by a downstream
+ * `steps.<id>.output` reference, by a gate judge, by `akm workflow status`, or
+ * by a human reading the row. The artifact is TEXT here rather than a JSON
+ * value, so the marker is appended as a trailing block instead of replacing the
+ * value with an envelope: the retained prefix is still genuinely useful (it is
+ * the head of a real log), and the block says exactly how much is missing.
+ */
+export const WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER = "__akm_exec_output_truncated__";
+// Per-var: Win32 `SetEnvironmentVariable` caps one variable at 32 767 UTF-16
+// code units; measuring UTF-8 bytes is conservative in the right direction.
+// Total: akm's own share of the `CreateProcess` `lpEnvironment` block, which it
+// shares with the allowlist, the unit's `env:` bindings and the argv.
+const EXEC_CONTEXT_LIMITS_WIN32 = {
+    perVarBytes: 32_767,
+    totalBytes: 64_000,
+    source: "Windows caps one environment variable at 32 767 characters (SetEnvironmentVariable)",
+};
+// Per-var: 75% of Linux's `MAX_ARG_STRLEN` (32 pages = 131 072 bytes), leaving
+// margin for the name, `=`, NUL and the kernel's own accounting — the guard must
+// never reject a spawn the platform would have accepted.
+// Total: half of macOS's 256 KiB `ARG_MAX` (the tightest supported total), so
+// the other half remains for the argv, the allowlist and the `env:` bindings.
+const EXEC_CONTEXT_LIMITS_POSIX = {
+    perVarBytes: 96 * 1024,
+    totalBytes: 128 * 1024,
+    source: "Linux caps one argv/environ string at MAX_ARG_STRLEN (32 pages = 131 072 bytes) and macOS caps argv+environ at ARG_MAX (256 KiB)",
+};
+/**
+ * The `AKM_*` context ceilings for THIS platform (or an explicitly named one,
+ * which is how the tests drive both branches deterministically).
+ */
+export function execContextLimits(platform = process.platform) {
+    return platform === "win32" ? EXEC_CONTEXT_LIMITS_WIN32 : EXEC_CONTEXT_LIMITS_POSIX;
+}
+/**
+ * Max characters of the per-unit human diagnostic — the `error`/stderr text
+ * journaled on a failed unit row and rendered by `akm workflow status --units`.
+ *
+ * ONE constant for the write side (`exec/native-executor.ts`, which clips before
+ * journaling) and the read side (`runtime/runs.ts`, which clips whatever a row
+ * already holds), so a diagnostic can never be stored larger than the surface
+ * that displays it. Long enough for a real stack trace or a compiler's error
+ * block; short enough that a runaway command cannot turn the journal into its
+ * log file.
+ */
+export const WORKFLOW_UNIT_DIAGNOSTIC_CLIP = 2_000;
+/**
+ * Truncate to `max` chars with an ellipsis marker.
+ *
+ * Lives with the bounds rather than with either caller: the write side
+ * (`exec/step-work.ts`) and the read side (`runtime/runs.ts`) clip against the
+ * same constants, and `runtime/runs.ts` cannot take the helper from
+ * `exec/step-work.ts` — that module imports `runtime/runs.ts`.
+ */
+export function clip(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+// ── Persistence bounds ───────────────────────────────────────────────────────
+/**
+ * Max serialized size of one `workflow_run_steps.evidence_json` row value.
+ *
+ * The promoted step artifact (`evidence.output`) is deliberately NOT clipped
+ * when it is built — gates judge the full artifact and downstream
+ * `steps.<id>.output` references need it intact — but a `collect`
+ * reducer over a fan-out bounded only by {@link WORKFLOW_MAX_MAP_EXPANSION}
+ * (10 000 units, each contributing up to a full unit result) would otherwise
+ * write an unbounded blob into a single SQLite row. Persistence is therefore
+ * bounded here, at the write boundary, by
+ * `clipStepEvidenceForPersistence` (`runtime/runs.ts`), which replaces
+ * oversized values with an explicitly-marked truncation envelope rather than
+ * silently shortening them.
+ *
+ * 1 MiB is deliberately generous: it is 4× the per-instruction cap and half the
+ * whole-plan cap, so no realistic authored workflow reaches it, while a runaway
+ * fan-out is still bounded to something SQLite and `akm workflow status` can
+ * handle.
+ */
+export const WORKFLOW_MAX_EVIDENCE_JSON_BYTES = 1024 * 1024;
+/** Chars of the original value retained (as a marked preview) in a truncation envelope. */
+export const WORKFLOW_EVIDENCE_TRUNCATION_PREVIEW_CHARS = 1000;
 export function utf8Bytes(value) {
     return Buffer.byteLength(value, "utf8");
 }