lua-cli 3.32.1 → 3.32.3

package/docs/api/LuaWorkflow.md

@@ -40,7 +40,7 @@ A typed code step. `inputSchema` / `outputSchema` / `resumeSchema` are zod schem
 | `onError`                                          | What the **final** failure does to the run: `'fail'` (default — the run unwinds `failed`) · `'continue'` (the run goes on; the step's result is the **continued-failure value** `{ __lua_workflow:'continued_failure', failed:true, error:{code,message}, text:'' }` — `${stepResults.<id>.text}` renders `''`, `getStepResult(id)` returns it, a `conditional` can branch on `stepResults.<id>.failed`) · `'park'` (the step parks on an exception gate for `retry-step` / `resolve-step` — see [When a step parks](../workflows/recovery.md)) |
 | `requiredConnections`                              | Connection ids that must mount before `execute` runs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `tier` / `workspace` / `jobResources` / `jobTools` | Job-tier fields — see [Workspaces and long steps](../workflows/workspaces-and-long-steps.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `execute(ctx)`                                     | `ctx`: `inputData`, `resumeData`, `getInitData()`, `getStepResult(id)`, `state`, `suspend()`, `bail()`, `bailRun()`, `once()`, `log()`, `env`, `artefacts`, `occurrenceId`, `workspace?`                                                                                                                                                                                                                                                                                                                                                        |
+| `execute(ctx)`                                     | `ctx`: `inputData`, `resumeData`, `getInitData()`, `getStepResult(id)`, `state`, `suspend()`, `bail()`, `bailRun()`, `once()` (worker tier — not on the Job tier yet, LUA-706), `log()`, `env`, `signal`, `runtime`, `artefacts`, `occurrenceId`, `lineageId`, `workspace?` (Job tier; `exec?` / `$?` with it)                                                                                                                                                                                                                                  |
 
 `ctx.suspend(payload)` parks the step for `Workflows.resume(runId, stepId, resumeData)`; on resume **`execute` re-runs from the top** with `ctx.resumeData` set.
 
@@ -54,21 +54,21 @@ Config: `name`, `description?`, `inputSchema`, `outputSchema?`, `budget?` (`maxC
 
 **The call site places.** Every builder call — `then`, `agentStep`, `specialistStep`, `toolStep`, `map`, `approval`, `waitForSignal`, `sleep`, `sleepUntil`, `foreach`, `parallel`, `branch`, `switch`, `dowhile`, `dountil`, `workflow` — appends **exactly one** entry to the chain where it is called. Containers take `StepRef`s: an inline step object, or a **string** naming an `agentStep`/`specialistStep`/`toolStep` declared elsewhere in the same chain — a string ref inside a container means "declare here, inside me" and does not append a second top-level entry. An id declared but never placed is `WORKFLOW_UNPLACED_STEP` (warning locally, error at push); referenced but never declared is `unknown-step-ref` at `.commit()`.
 
-| Verb                                                                                                    | Entry                                                                                                                                                                                                                                                                                |
-| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `.then(step, input?)`                                                                                   | Sequential step                                                                                                                                                                                                                                                                      |
-| `.agentStep(id, { agentId, prompt, outputSchema?, toolScope?, tier?, … })`                              | Agent turn (`prompt` is a `template(...)`)                                                                                                                                                                                                                                           |
-| `.specialistStep(id, { role, prompt, … })`                                                              | Ephemeral role on the owning agent (D25)                                                                                                                                                                                                                                             |
-| `.toolStep(id, { toolId, input? })`                                                                     | One tool call — `toolId` must name a `LuaTool` the compiler can see as a tool primitive (declared in its own module and exported, or registered on the agent); a tool object defined inline in the workflow file is not detected and fails `WORKFLOW_TOOL_REF_UNRESOLVED` at compile |
-| `.map(descriptors, { id })`                                                                             | Data reshaping — `id` is **required** once the workflow has ≥ 2 maps (`map-id-required`)                                                                                                                                                                                             |
-| `.parallel([...arms], { merge? })`                                                                      | Concurrent arms; a `[map, step]` pair is a legal arm (lowered to an implicit subrun)                                                                                                                                                                                                 |
-| `.switch([[predicate, armRef]...], otherwise?)` / `.branch(...)`                                        | Conditional (exclusive / inclusive)                                                                                                                                                                                                                                                  |
-| `.foreach(step, { concurrency?, maxItems?, chunk?, rateLimit? })` / `.foreach({ items })`               | Fan-out over an upstream array                                                                                                                                                                                                                                                       |
-| `.dowhile(ref, predicate, { maxIterations, intervalSeconds? })` / `.dountil(...)`                       | Loop                                                                                                                                                                                                                                                                                 |
-| `.sleep(ms)` / `.sleepUntil(template)`                                                                  | Engine-side waits — `sleepUntil` lowers to an `<id>_at` mapping + `sleepUntil{dateFrom}` (D6-r1)                                                                                                                                                                                     |
-| `.approval(id, { title, approver, timeoutHours, onTimeout, editable?, editablePaths?, itemsPath?, … })` | Human gate — see [Approvals](../workflows/approvals.md)                                                                                                                                                                                                                              |
-| `.waitForSignal(id, { signal, schema?, timeoutHours, acceptedSources? })`                               | External event via `Workflows.signal` — completes with `{ payload, source: { kind, id, principalId? }, signalId, receivedAt }`                                                                                                                                                       |
-| `.workflow(id, ref, input?, { workspace? })`                                                            | Child run the parent waits for                                                                                                                                                                                                                                                       |
+| Verb                                                                                                    | Entry                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.then(step, input?)`                                                                                   | Sequential step                                                                                                                                                                                                                                                                                                                                                                 |
+| `.agentStep(id, { agentId, prompt, outputSchema?, toolScope?, tier?, … })`                              | Agent turn (`prompt` is a `template(...)`)                                                                                                                                                                                                                                                                                                                                      |
+| `.specialistStep(id, { role, prompt, … })`                                                              | Ephemeral role on the owning agent (D25)                                                                                                                                                                                                                                                                                                                                        |
+| `.toolStep(id, { toolId, input? })`                                                                     | One tool call — `toolId` must name a `LuaTool` the compiler can see as a tool primitive (declared in its own module and exported, or registered on the agent); a tool object defined inline in the workflow file is not detected and fails `WORKFLOW_TOOL_REF_UNRESOLVED` at compile                                                                                            |
+| `.map(descriptors, { id })`                                                                             | Data reshaping — `id` is **required** once the workflow has ≥ 2 maps (`map-id-required`)                                                                                                                                                                                                                                                                                        |
+| `.parallel([...arms], { merge? })`                                                                      | Concurrent arms; a `[map, step]` pair is a legal arm (lowered to an implicit subrun)                                                                                                                                                                                                                                                                                            |
+| `.switch([[predicate, armRef]...], otherwise?)` / `.branch(...)`                                        | Conditional (exclusive / inclusive)                                                                                                                                                                                                                                                                                                                                             |
+| `.foreach(step, { concurrency?, maxItems?, chunk?, rateLimit? })` / `.foreach({ items })`               | Fan-out over an upstream array                                                                                                                                                                                                                                                                                                                                                  |
+| `.dowhile(ref, predicate, { maxIterations, intervalSeconds? })` / `.dountil(...)`                       | Loop                                                                                                                                                                                                                                                                                                                                                                            |
+| `.sleep(ms)` / `.sleepUntil(template)`                                                                  | Engine-side waits — `sleepUntil` lowers to an `<id>_at` mapping + `sleepUntil{dateFrom}` (D6-r1)                                                                                                                                                                                                                                                                                |
+| `.approval(id, { title, approver, timeoutHours, onTimeout, editable?, editablePaths?, itemsPath?, … })` | Human gate — see [Approvals](../workflows/approvals.md)                                                                                                                                                                                                                                                                                                                         |
+| `.waitForSignal(id, { signal, schema?, timeoutHours, acceptedSources? })`                               | External event via `Workflows.signal` — completes with `{ payload, source: { kind, id, principalId? }, signalId, receivedAt }`; payload keys named like a credential (`token`, `secret`, `apiKey`, `accessToken`, …) are persisted `[REDACTED]` (the `signal-reserved-key` warning says so at push / compose) — see [Reserved payload keys](Workflows.md#reserved-payload-keys) |
+| `.workflow(id, ref, input?, { workspace? })`                                                            | Child run the parent waits for                                                                                                                                                                                                                                                                                                                                                  |
 
 ### Typed predicates
 

package/docs/api/Workflows.md

@@ -69,6 +69,16 @@ Resumes a step suspended with `ctx.suspend(...)`. The loser of a resume race rec
 
 Delivers a named signal to a run waiting on `waitForSignal(name)`. `opts.dedupeKey` makes a re-send a no-op (`{ accepted: true, duplicate: true }`). Returns `{ accepted, reason?: 'source_not_accepted' | 'duplicate' | 'parked' }`. The waiting step completes with `{ payload, source: { kind, id, principalId? }, signalId, receivedAt }` — read the payload as `stepResults.<id>.payload`.
 
+#### Reserved payload keys
+
+The run ledger redacts by **key name**, not by value: a payload member whose key is one of
+
+`secret`, `token`, `password`, `passwd`, `pwd`, `passphrase`, `api_key`, `apikey`, `access_key`, `secret_key`, `private_key`, `client_secret`, `authorization`, `auth_token`, `access_token`, `id_token`, `refresh_token`, `session_key`, `credential`, `credentials`
+
+is persisted as `[REDACTED]` whatever it holds. A key matches when one of those names is a whole segment of it — segments split on `_`, `-`, `.` and spaces, case-insensitive (`token`, `user_token`, `x-token`, `Token`; the compounds also as one camelCase word: `apiKey`, `refreshToken`, `accessToken`) — while a name glued to another word (`tokens`, `tokenCount`, `accessTokenExpiry`) is not. A member whose value is an object or array is walked, not replaced whole.
+
+This is by design (a credential must never land in a run), so the placeholder is what `stepResults.<id>.payload`, the run output, `lua workflows status --steps`, exports and the chat run card show — a workflow cannot read a data field with one of these names back. Name data fields otherwise (`ticketRef`, `handle`, `code`, `verifier`). The same rule applies to every step output and suspend payload. A `waitForSignal` whose `schema` declares a property with a reserved name draws the non-blocking `signal-reserved-key` warning at push / compose (the property, the placeholder it would read as, the rename), and `lua workflows signal` warns before sending a payload that carries a reserved key (the signal is still delivered).
+
 ### Reserved members
 
 `startBatch`, `signalByKey`, `raiseBudget`, `setGoal` and `goals.{list,get,pause,resume,close}` are part of the API surface (the member list is frozen) and throw `WorkflowApiError { code: 'WORKFLOWS_API_UNAVAILABLE' }` until their server routes ship. For `startBatch`: from an agent turn, prefer the `startWorkflowRunBatch` tool (one consent card for the whole batch, D23-r5).

package/docs/workflows/approvals.md

@@ -2,20 +2,38 @@
 
 _Source of truth: workflows-spec 06 §6.4. This page is the developer summary; the spec is normative._
 
-`.approval(id, cfg)` parks the run until a person decides. The node completes with the decision as data — branchable, never an exception. A human decision completes it with
+`.approval(id, cfg)` parks the run until a person decides. The node completes with the decision as data — branchable, never an exception. The output is **one** shape everywhere — the engine, `lua workflows run --approve/--deny` offline and the shipped examples — `WorkflowApprovalOutput` (`@lua/shared-types`, LUA-751):
 
 ```typescript
 {
-  approved: boolean;
+  approved: boolean;                               // false on a denial AND on a timeout under onTimeout:'deny'
+  decision: 'approved' | 'denied' | 'timed_out';
+  text: string;                                    // the approver's note when one was left, else the decision word — `${stepResults.<id>.text}`
   note?: string;                                   // the approver's note, when one was left
   editedPayload?: unknown;                         // only when the approver edited (see below)
-  editRevision: number;                            // 0 when the payload was never edited
-  decidedBy: { id?: string; kind: string };        // who decided
+  editRevision?: number;                           // 0 when the payload was never edited; absent on a timeout
+  decidedBy?: { id?: string; kind?: string };      // who decided (the resumer's actor); absent on a timeout — the surface it came through is on the approval link / event, never here
   evidence?: string[];                             // decision artefact ids frozen with the decision
+  timedOut?: boolean; escalations?: number;        // the timeout leg (below)
+  items?: Array<{ index; itemKey?; decision; decidedBy?; payload }>;   // per-item approvals
 }
 ```
 
-A timeout that ends the chain in `'deny'` completes it with the sweep's shape instead — `{ approved: false, timedOut: true, escalations: <hops> }` (no `decidedBy`, `editRevision` or `evidence`); `'continue'` is treated as `'deny'` for approvals; `'cancel-run'` cancels the run. The original payload is not echoed back — read it from the step's own input (`stepResults`), not from the output.
+A timeout that ends the chain in `'deny'` completes it with the sweep's envelope — `{ approved: false, decision: 'timed_out', text: 'timed_out', timedOut: true, escalations: <hops> }` (no `decidedBy`, `editRevision` or `evidence`); `'continue'` is treated as `'deny'` for approvals; `'cancel-run'` cancels the run. **The original payload is not echoed back** — read it from the step's own input (`getInitData()`, `getStepResult('<id>')`, `${stepResults.<id>}`), not from the output; `editedPayload` replaces it only when the approver edited. `onDeny` defaults to `'continue'` (a denial is data — the next step runs with `{ approved: false, … }`); `onDeny: 'fail'` fails the step `approval_denied` on denials and timeouts alike.
+
+The step after an approval declares the members it reads and lets the rest ride (`.passthrough()` — the engine validates a step's input with `additionalProperties: false` otherwise):
+
+```typescript
+inputSchema: z.object({ approved: z.boolean(), editedPayload: refundRequest.optional() }).passthrough(),
+async execute({ inputData, getStepResult }) {
+  if (!inputData.approved) return { refundId: null };
+  const r = inputData.editedPayload ?? getStepResult<RefundRequest>('refundRequest');   // the edited details, else what the approver saw
+  …
+```
+
+Map the payload the approver should see ahead of the approval (`.map({ ticketId: fromInit('ticketId'), amount: fromInit('amount') }, { id: 'refundRequest' })`) when it is not the previous step's whole output: `editedPayloadSchema` describes THAT payload, and an edit is judged on the pointers that changed against it.
+
+Offline, `lua workflows run --approve <id>` completes the node with `decidedBy: { id: 'local', kind: 'user' }` (exactly the resumer's `{ id, kind }` — no `via`: the engine never writes a surface into a step output) and `editRevision: 0`; `--approve <id>=@edited.json` carries the FULL edited payload as `editedPayload` with `editRevision: 1`; `--deny <id>[=<reason>]` makes the reason the `note` (and the `text`). `packages/shared-types/src/__fixtures__/workflow-approval-output.fixture.json` is the one fixture the engine, the driver and the examples are pinned to.
 
 ## Approver specs
 
@@ -38,4 +56,4 @@ The desktop inbox and run detail carry the full card (per-item rows, edits, esca
 
 Per-item approvals (`itemsPath` / `itemApprover` / `itemTimeout`) fan one node out to one decision per item — see [Per-item approvals](./per-item-approvals.md).
 
-Offline: `--approve <id>[=@payload]` / `--deny <id>[=@reason]` pre-answer the prompt; an edited payload is checked with the same `matchesEditablePath` + `editedPayloadSchema` the server uses.
+Offline: `--approve <id>[=@payload]` / `--deny <id>[=@reason]` pre-answer the prompt; an edited payload is the FULL payload, checked the way the server checks an inline edit — only the pointers that CHANGED against the payload the approval showed must sit inside `editablePaths` (`changedPointers` + `matchesEditablePath` from `@lua/workflow-graph`), then `editedPayloadSchema`. `editable: true` with no `editablePaths` is whole-root rights — any member may change — as on the server. Because the change set is judged against the payload the approval actually showed, an edit outside `editablePaths` fails exit 2 `edit-path-not-allowed` **when the approval's turn comes**, i.e. after the steps before it have run, not before the run starts (`editedPayloadSchema` and `approval-not-editable` are still checked up-front).

package/docs/workflows/correlation-keys.md

@@ -6,6 +6,7 @@ _Source of truth: workflows-spec (P1-3 / P1-14). This page is the developer summ
 
 - `Workflows.signalByKey(nameOrId, correlationKey, name, payload?)` delivers a signal **by business key** — no runId bookkeeping in your webhook; `allowMultiple` fans out when several runs share the key.
 - `Workflows.list({ correlationKey })` / `lua workflows runs --correlation-key` find the run(s).
+- A signal payload member named like a credential (`token`, `secret`, `password`, `apiKey`, `authorization`, `credentials`, …) is persisted `[REDACTED]` by design and cannot be read back by the workflow — name data fields otherwise; the full list and the rule are under [Reserved payload keys](../api/Workflows.md#reserved-payload-keys). `lua workflows signal` warns before sending one.
 - `tags` are free-form labels (AND-ed in list filters); `replyTo: { channel, threadId }` routes the terminal reply back to the originating conversation.
 
 Offline: `--correlation-key`, `--tag`, `--reply-to <channel>:<threadId>` and `--on-behalf-of` stamp `ctx.runtime.*`; the would-be reply prints on the terminal instead of sending.

package/docs/workflows/goals.md

@@ -41,6 +41,6 @@ lua workflows goals create -i outreach \
 
 ## Errors and exit codes
 
-The usual `lua workflows` codes: 0 ok · 1 API refusal · 2 usage · 3 not found. The goal routes' refusals are printed with their hint: `GOAL_NOT_ACTIVE {status}` (only an active goal pauses, only a paused one resumes, a done/closed goal stays closed), `GOAL_CAP {cap}` (close or finish a goal first), `VALIDATION_FAILED {issues}` (each issue with its path — `goal-judge-schema-missing-done`, `goal-cadence-invalid`, `goal-objective-too-long`, `ephemeral-role-required`, …), `GOAL_MAX_RUNS_INVALID`, `WORKFLOW_NOT_ON_AGENT`.
+The usual `lua workflows` codes: 0 ok · 1 API refusal (a 4xx other than 404) · 2 usage · 3 not found · 11 unavailable (5xx / connection refused / timeout); an escaped 401 / 403 is 9 / 10 — `lua --help` prints the full table. The goal routes' refusals are printed with their hint: `GOAL_NOT_ACTIVE {status}` (only an active goal pauses, only a paused one resumes, a done/closed goal stays closed), `GOAL_CAP {cap}` (close or finish a goal first), `VALIDATION_FAILED {issues}` (each issue with its path — `goal-judge-schema-missing-done`, `goal-cadence-invalid`, `goal-objective-too-long`, `ephemeral-role-required`, …), `GOAL_MAX_RUNS_INVALID`, `WORKFLOW_NOT_ON_AGENT`.
 
-`lua workflows schedules delete` on a goal's cadence Job is refused (`goal_schedule`) — use `goals pause` / `goals close`; see [schedules.md](./schedules.md).
+`lua workflows schedules delete` on a goal's cadence Job is refused (`goal_schedule`) while the goal is active or paused — use `goals pause` / `goals close` (closing retires the Job). Once the goal is done or closed (`goals close` then answers `GOAL_NOT_ACTIVE`), a cadence Job that still lingers is removed with `schedules delete <jobId>`; see [schedules.md](./schedules.md).

package/docs/workflows/limits.md

@@ -4,6 +4,12 @@ _Source of truth: workflows-spec 10 / 16. This page is the developer summary; th
 
 Per-run: `budget.maxCredits` (over the org's `maxCreditsPerRun` default 250 ⇒ push blocker `budget-exceeds-cap` until an org admin raises it, R23), `budget.maxDurationSeconds`, `budget.maxJobSeconds`. Structural: `foreach` `maxItems` (default 256 — with `chunk:{size}` the cap bounds CHUNKS), loop `maxIterations` (default 100), nesting depth ≤ 3, `startBatch` per-item `idempotencyKey`. Push-time caps preflight reports `warnings[]` + `blockers[]`; `lua push --strict-caps` promotes warnings.
 
+## Credits
+
+`budget.maxCredits` counts agent steps, never tokens. An inline agent step settles a flat **1** credit when it completes; a `tier:'job'` attempt settles a flat **4** at its first claim (a retry is a new attempt; a seat-metered org settles 0 and is metered from the `workflow:job` usage event instead). Before dispatching an agent step the engine checks `remaining = maxCredits − spent − reserved` against the step's reserve (1 inline, 4 Job) and parks the run `suspended{gate.kind:'budget'}` — `nextAction:'raise_budget'`, `lua workflows raise-budget <runId> --credits <n>` — when it is short. So `maxCredits: 40` buys ten Job-tier attempts, and a `maxCredits` under 4 can never dispatch one.
+
+Nothing meters a Job-tier attempt's tokens against the credits while it runs. Each attempt is bounded by its own ceilings: the step wall (`timeoutSeconds`), `maxInputTokens` (input-side tokens — prompt + cache read + cache creation — default **4M**, ≈ $1–13 per attempt on a Sonnet-class model; 1M..500M), `maxMessages` (default 400) and `maxTurns`. Crossing one ends the attempt `attempt_budget_exhausted` from its last checkpoint (see [Long steps and checkpoints](long-steps-and-checkpoints.md)). Size `maxInputTokens` for what one attempt may cost and `maxCredits` for how many attempts the run may make.
+
 ## Org pacing
 
 `workflowPolicy.pacing` is an org-admin rate limit **per outbound host** shared by every run in the org. A paced step shows as `ready (pacing_deferred …)` and counts against no per-run budget except `maxDurationSeconds`. Code-step `fetch` calls are **not** paced (B26, normative) — pacing governs `tool`/`http` steps. Only `lua features` / the desktop **Workflows policy** page / R23 can change it.

package/docs/workflows/replay-local.md

@@ -15,10 +15,16 @@ Two options were on the table:
 
 Why A: the wrapper drags the whole runtime plane (`@lua/sandbox-runtime` → `@lua/shared-sandbox` polyfills, artefact/dataset contexts) into the CLI bundle otherwise; every project that can run a workflow-script replay today is a monorepo/dev checkout that already has the runtime in `node_modules`; and resolving from the **project** rather than the CLI guarantees the wrapper version matches the runner the project deploys.
 
+## Update — LUA-751: the wrapper text is bundled, the project's runtime still wins
+
+Option A left every plain `lua init` project unable to run a script offline (`lua workflows run adversarial-verify` → exit 3 `REPLAY_RUNTIME_UNAVAILABLE`: the runtime is neither a template dependency nor on npm). The fix keeps A's ordering and adds the missing fallback without option B's fork: `@lua/sandbox-runtime` now ships a **dependency-free subpath entry**, `@lua/sandbox-runtime/workflow-script-wrapper` (the replay-round source, `buildWorkflowScriptWrapper`, the protocol window), which lua-cli inlines through its usual `noExternal: [/^@lua\//]` — the same file the runner builds, versioned with the CLI release, none of the platform-API clients of the root index. The context is the `workflow-script` surface of `@lua/shared-sandbox` (`buildWorkflowScriptGlobals` + the runtime handle), i.e. what `createSandboxContext({ siteType: 'workflow-script' })` builds.
+
+`loadLocalScriptRunner(projectDir, { runtime })`: `'auto'` (default) resolves the project's `@lua/sandbox-runtime` first and falls back to the bundled wrapper; `'project'` keeps the strict behaviour (`REPLAY_RUNTIME_UNAVAILABLE`, never a silent "stable" against a different wrapper); `'bundled'` never looks. The report carries `runtime: 'project' | 'bundled'` and the printed report names it. The `journalProtocolVersion` gate applies to the bundled wrapper exactly as on the runner (`runtime_incompatible` outside its window).
+
 ## What it means for a project
 
-- Inside the monorepo (or any project that lists `@lua/sandbox-runtime` in its devDependencies): `replay --local` and `lua test workflow <script>` work as-is.
-- Elsewhere: `REPLAY_RUNTIME_UNAVAILABLE: replay --local needs @lua/sandbox-runtime resolvable from the project (…)` — add the devDependency, or run the verb from a monorepo checkout with `--project <dir>`.
+- Inside the monorepo (or any project that lists `@lua/sandbox-runtime` in its devDependencies): `replay --local` and `lua test workflow <script>` run the project's runtime — parity with the runner it deploys.
+- Elsewhere: both verbs run the wrapper bundled with the CLI; the replay report says `wrapper: bundled with this lua-cli`. A divergence found on the bundled wrapper is worth re-running from a monorepo checkout with `--project <dir>` before it is triaged as a runner NDE.
 - The graph-form `replay --local` (R4/R5 → `replayLedger`) has no runtime dependency and always works. It re-evaluates every derived row over the same ancestor context the engine used — including a `failed` ancestor under `onError:'continue'`, which binds its continued-failure value (`{ __lua_workflow:'continued_failure', failed:true, error, text:'' }`) exactly as the engine did, so a mapping over one replays stable rather than `binding_unresolved`.
 
 ## Exit matrix (script form)
@@ -26,7 +32,7 @@ Why A: the wrapper drags the whole runtime plane (`@lua/sandbox-runtime` → `@l
 | Exit | Meaning                                                                                                      |
 | ---- | ------------------------------------------------------------------------------------------------------------ |
 | 0    | stable — every async journal entry re-issued with the same `callHash`                                        |
-| 3    | runtime unavailable (`REPLAY_RUNTIME_UNAVAILABLE`) or the run/bundle could not be fetched                    |
+| 3    | the run/bundle could not be fetched (`REPLAY_RUNTIME_UNAVAILABLE` only under `{ runtime: 'project' }`)       |
 | 4    | `LEDGER_DIVERGENCE` / `JOURNAL_DIVERGENCE` — at least one `hash_mismatch` / `journal_longer_than_script` row |
 
 ## Related

package/docs/workflows/schedules.md

@@ -23,4 +23,4 @@ lua workflows view outreach                       # the "Schedules:" line + tabl
 
 Each row shows the trigger (`cron 0 9 * * 1 (Europe/London)` · `every 3600s` · `once <iso>`), the next fire, the last fire, its status (`active` · `paused` · `auto-disabled` after the PRO-726 strike limit) and the strike count.
 
-**Goal-owned schedules.** A goal's cadence is a schedule Job too; it is tagged with the goal's id (`goalId` in `--json`, the `Goal` column in the table). The CLI refuses to delete it — `schedules delete` on such a row answers `goal_schedule` (exit 1) without calling the API, the same refusal the chat tool gives — because unscheduling a goal's job is recorded as a failure of the goal, never as stopping it. Stop the goal instead: `lua workflows goals pause <goalId>` (it can come back) or `lua workflows goals close <goalId>` (final). The server refuses it too: R28 answers `409 GOAL_SCHEDULE {goalId}` for every caller (SDK, desktop, curl), and the CLI renders that with the same message. See [goals.md](./goals.md).
+**Goal-owned schedules.** A goal's cadence is a schedule Job too; it is tagged with the goal's id (`goalId` in `--json`, the `Goal` column in the table). While the goal is **active or paused** the CLI refuses to delete it — `schedules delete` on such a row answers `goal_schedule` (exit 1) without calling the API, the same refusal the chat tool gives — because unscheduling a live goal's job is recorded as a failure of the goal, never as stopping it. Stop the goal instead: `lua workflows goals pause <goalId>` (it can come back) or `lua workflows goals close <goalId>` (final; closing retires the cadence Job with it). The server refuses it too while the goal is live: R28 answers `409 GOAL_SCHEDULE {goalId}` for every caller (SDK, desktop, curl), and the CLI renders that with the same message. Once the goal has **ended** (`done` / `closed`, or its row is gone) a cadence Job that still lingers — one left behind before LUA-760, or one whose retirement did not land — is R28's to remove: `schedules delete <jobId>` goes through and retires it (the engine's sweep does the same on its own within one interval). A goal the CLI cannot read refuses (fail closed). See [goals.md](./goals.md).

package/docs/workflows/script-form.md

@@ -5,9 +5,15 @@ _Source of truth: workflows-spec 04 §4.3 (D15-r2, Cluster J B12 — WF-527, WB-
 A script workflow is a plain JavaScript ES module — no TypeScript, no `import`/`require` — that begins with `export const meta = {…}` and continues with a body run in an async context whose top-level `return` is the run output. The host API (`agent`, `tool`, `parallel`, `foreach`, `sleep`, `approval`, `waitForSignal`, `memo`, `step`, `shell`, `merge`, `log`, `phase`, …) is injected as module-scope bindings; the same file is what the composer produces (`lua workflows export`) and what a template freezes.
 
 ```js
-export const meta = { name: 'judge-panel', description: 'Three drafts, three judges, synthesize the winner',
-                      phases: [{ title: 'Draft' }, { title: 'Judge' }, { title: 'Synthesize' }] };
-const drafts = await parallel([agent('Draft, technical angle', { phase: 'Draft' }), agent('Draft, market angle', { phase: 'Draft' })]);
+export const meta = {
+  name: 'judge-panel',
+  description: 'Three drafts, three judges, synthesize the winner',
+  phases: [{ title: 'Draft' }, { title: 'Judge' }, { title: 'Synthesize' }],
+};
+const drafts = await parallel([
+  () => agent('Draft, technical angle', { phase: 'Draft' }), // thunks — `parallel` starts each arm itself (04 §4.3.2)
+  () => agent('Draft, market angle', { phase: 'Draft' }),
+]);
 const scores = await foreach(drafts, (d) => agent(`Score this draft: ${d}`, { phase: 'Judge' }));
 const picked = await step('pick-winner', () => ({ winner: drafts[scores.indexOf(Math.max(...scores))] }));
 return picked;
@@ -27,19 +33,23 @@ Run in this order — the same order lua-api re-validates on push (one implement
 
 `lua compile` discovers every `src/workflows/*.workflow.script.js` (outside the TypeScript project — never bundled) and emits `ManifestWorkflow{ form:'script', script, scriptHash, meta, journalProtocolVersion: 1, scriptSurface, roleBindings }` — the graph members are absent. `lua push` sends `{ form:'script', script, scriptHash, meta, journalProtocolVersion, roleBindings, schedule?, scheduleInput?, budget? }` and skips the bundle upload. The stored row is `WorkflowVersion{ form:'script', dynamic:false }` — identical to a composed script minus `dynamic:true`. `WORKFLOW_SCRIPT_FORM_NOT_PUSHABLE` is struck (never emitted). An org whose `workflowPolicy.composeForm` is `'graph'` refuses the push with `compose-form-forbidden`, exactly as it refuses a composed script.
 
+**The parent's form (LUA-717).** `lua push` creates a workflow the server does not have with `form` taken from the compiled definition (`POST /developer/workflows/:agentId { name, description, form:'script' }`). A workflow's form is fixed by its first version: a version whose form differs from the parent's is refused `400 WORKFLOW_FORM_MISMATCH { workflowForm, versionForm }` — rename the script, or delete the workflow (`lua workflows delete`) and push again. The one exception is an **empty** parent (no version of any kind, sandbox included), which adopts the form of its first pushed version: a lua-cli older than the LUA-717 release sent no `form` on create, so its script workflows were left as graph shells, and the first script push is what makes such a shell usable.
+
+**Script workflows are pushed from the CLI only.** Chat compose (`composeWorkflow`, `POST …/compose`) composes **graph** workflows; a `form:'script'` compose is refused `script-validation-tick-unavailable`, because the WF-323 validation tick is not bound on the production server (by design — a script is never persisted un-validated). A script that should exist on the server goes through `src/workflows/<name>.workflow.script.js` + `lua push workflow`.
+
 ## `lua test workflow <name>` on a script
 
-Runs the file through the runner's own replay wrapper (parity context) in an offline tick loop: every tick re-runs the script against the journal so far, the wrapper parks with its async intents, the driver settles each with a **fake completion** (no API call) and re-ticks until `done`/`bailed`/`failed`. Steering:
+Runs the file through the runner's own replay wrapper (parity context) in an offline tick loop: every tick re-runs the script against the journal so far, the wrapper parks with its async intents, the driver settles each with a **fake completion** (no API call) and re-ticks until `done`/`bailed`/`failed`. The wrapper is **bundled with the CLI** (LUA-751 — the dependency-free `@lua/sandbox-runtime/workflow-script-wrapper` entry over the `workflow-script` context of `@lua/shared-sandbox`, the same surface the runner builds), so a plain `lua init` project runs scripts offline; a project that lists `@lua/sandbox-runtime` in its devDependencies (a monorepo checkout) runs that copy instead. A fake `approval()` resolves the same `WorkflowApprovalOutput` the graph form's `--approve` completes with. Steering:
 
-| Flag | Effect |
-| --- | --- |
-| `--input <json|@file>` | the script's `args` (default `meta.sampleArgs ?? {}`) |
-| `--step-output <label|seq>=<json>` | the completion for the intent with that `narration.label` (an `agent()`'s `label`/`phase`) or journal seq |
-| `--max-ticks <n>` | default 64 — `SCRIPT_TICK_LIMIT` (exit 4) beyond it |
-| `--ledger-out <file>` | the local journal (`{ form:'script', journal[] }`) |
-| `--json` | the result envelope |
+| Flag                                | Effect                                                                                                    |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `--input <json\|@file>`             | the script's `args` (default `meta.sampleArgs ?? {}`)                                                     |
+| `--step-output <label\|seq>=<json>` | the completion for the intent with that `narration.label` (an `agent()`'s `label`/`phase`) or journal seq |
+| `--max-ticks <n>`                   | default 64 — `SCRIPT_TICK_LIMIT` (exit 4) beyond it                                                       |
+| `--ledger-out <file>`               | the local journal (`{ form:'script', journal[] }`)                                                        |
+| `--json`                            | the result envelope                                                                                       |
 
-Exit 0 `done`/`bailed`; 4 `failed` (`SCRIPT_THREW`, `SCRIPT_DEADLOCK` — parked with zero intents, `SCRIPT_TICK_LIMIT`); 3 when `@lua/sandbox-runtime` is not resolvable from the project (`REPLAY_RUNTIME_UNAVAILABLE`, see `replay-local.md`); 2 on flag grammar.
+Exit 0 `done`/`bailed`; 4 `failed` (`SCRIPT_THREW`, `SCRIPT_DEADLOCK` — parked with zero intents, `SCRIPT_TICK_LIMIT`); 2 on flag grammar. (Exit 3 `REPLAY_RUNTIME_UNAVAILABLE` is reserved for `replay --local --runtime project` on a project without `@lua/sandbox-runtime`, see `replay-local.md`.)
 
 ## `step(label, fn, { timeoutSeconds? })`
 

package/docs/workflows/testing-offline.md

@@ -8,25 +8,26 @@ _Source of truth: workflows-spec 03 §3.9 (WF-204/WF-225/WF-332). This page is t
 
 ## Steering flags — fully scriptable, no stdin
 
-| Flag                                                  | Effect                                                                                                                                                                            |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--input @file\|<json>`                               | Run input (validated against `inputSchema`)                                                                                                                                       |
-| `--step-output <id>=@file\|<json>` (rep.)             | Completes the row **without** running it — validated against the step's `outputSchema`. This is how a predicate over an agent output gets BOTH truth values under `--agents fake` |
-| `--approve <id>[=@payload]` · `--deny <id>[=@reason]` | Pre-answer approvals (edited payloads use the server's `matchesEditablePath` + `editedPayloadSchema`)                                                                             |
-| `--signal <name>=@file\|<json>` (rep.)                | Pre-supply `waitForSignal` payloads in order of arrival                                                                                                                           |
-| `--fixtures <dir>` / `--record <dir>`                 | Replay / record agent+tool outputs (`<stepId>.<attempt>.json`); a missing fixture is exit **5** `FIXTURE_MISSING`, never a silent fake; `--step-output` wins over a fixture       |
-| `--from-run <runId>`                                  | Seed every `completed` step from a real run (same math as repair runs); graph drift asks for `--force`                                                                            |
-| `--park <id>` (rep.)                                  | Simulate a platform-fault park of a `sideEffects:'external'` step — then `retry / skip / complete / fail`, the production verbs (see [When a step parks](./recovery.md))          |
-| `--fast-retries`                                      | Collapse retry backoff waits to 0                                                                                                                                                 |
-| `--real-time`                                         | Actually wait on `sleep`/backoff instead of fast-forwarding the virtual clock                                                                                                     |
-| `--now <iso>`                                         | Pin the virtual clock start (resolves `sleepUntil` dateFrom, business-hours deadlines)                                                                                            |
-| `--artefacts-dir <dir>`                               | Back `ctx.artefacts.*` on disk (`<dir>/<artefactId>` + `<artefactId>.meta.json`, ids `local-<n>`)                                                                                 |
-| `--env KEY=value` (rep.)                              | The local `env.template()` overlay — a missing key is exit 2 `env-template-missing`; values never reach `--ledger-out`                                                            |
-| `--step-wall <s>`                                     | Per-step wall, default 600                                                                                                                                                        |
-| `--max-foreach-items <n>`                             | Override the local foreach cap                                                                                                                                                    |
-| `--agents fake\|live`                                 | Fake stubs (default) or the dev API                                                                                                                                               |
-| `--ledger-out <file>`                                 | Write the in-memory ledger (steps, outputs, attempts, effects, events) — the input of `replay --local`                                                                            |
-| `--json`                                              | Machine-readable result envelope                                                                                                                                                  |
+| Flag                                                  | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--input @file\|<json>`                               | Run input (validated against `inputSchema`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `--step-output <id>=@file\|<json>` (rep.)             | Completes the row **without** running it — validated against the step's `outputSchema`. This is how a predicate over an agent output gets BOTH truth values under `--agents fake`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `--approve <id>[=@payload]` · `--deny <id>[=@reason]` | Pre-answer approvals — the node completes with the engine's own envelope, `WorkflowApprovalOutput` (`{ approved, decision, text, note?, editedPayload?, editRevision?, decidedBy? }`, see [Approvals](./approvals.md)); an edited payload is the FULL payload, judged like the server's inline edit (`changedPointers` against the payload the approval showed + `matchesEditablePath`, then `editedPayloadSchema`); `onDeny` defaults to `'continue'` as on the engine (LUA-751). `editable: true` with no `editablePaths` is whole-root rights (any member may change), as on the server. Because the change set is judged against the payload the approval actually showed, a change outside `editablePaths` fails exit 2 `edit-path-not-allowed` **when the approval's turn comes — after the steps before it have run** — not before the run starts; `editedPayloadSchema` is still checked up-front |
+| `--signal <name>=@file\|<json>` (rep.)                | Pre-supply `waitForSignal` payloads in order of arrival                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `--fixtures <dir>` / `--record <dir>`                 | Replay / record agent+tool outputs (`<stepId>.<attempt>.json`); a missing fixture is exit **5** `FIXTURE_MISSING`, never a silent fake; `--step-output` wins over a fixture. An agent fixture's `output` is either the `{ text, object? }` reply envelope `--record` writes (the `object` wins, else the text is parsed under the `outputSchema`) or the structured value itself, taken as-is (LUA-751) — a value that is exactly `{ text }` reads as a text reply; record it as `{ object: { text } }`                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `--from-run <runId>`                                  | Seed every `completed` step from a real run (same math as repair runs); graph drift asks for `--force`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--park <id>` (rep.)                                  | Simulate a platform-fault park of a `sideEffects:'external'` step — then `retry / skip / complete / fail`, the production verbs (see [When a step parks](./recovery.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `--fast-retries`                                      | Collapse retry backoff waits to 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `--real-time`                                         | Actually wait on `sleep`/backoff instead of fast-forwarding the virtual clock                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `--now <iso>`                                         | Pin the virtual clock start (resolves `sleepUntil` dateFrom, business-hours deadlines)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--artefacts-dir <dir>`                               | Back `ctx.artefacts.*` on disk (`<dir>/<artefactId>` + `<artefactId>.meta.json`, ids `local-<n>`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `--env KEY=value` (rep.)                              | The local `env.template()` overlay — a missing key is exit 2 `env-template-missing`; values never reach `--ledger-out`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--step-wall <s>`                                     | The cap on every step wall, default 600 — a node's own `timeoutSeconds` (or its step definition's) applies below it; a step past its wall fails `TIMEOUT` and its retry policy applies; the attempt's `ctx.signal` aborts at the wall — the driver cannot kill in-process code, so a step that ignores the signal keeps running in the background until it settles (LUA-689)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--max-foreach-items <n>`                             | Override the local foreach cap                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `--agents fake\|live`                                 | Fake stubs (default) or the dev API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--ledger-out <file>`                                 | Write the in-memory ledger (steps, outputs, attempts, effects, events) — the input of `replay --local`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--json`                                              | Machine-readable result envelope                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `--workspace <dir>`                                   | The checkout Job-tier **code** steps run in: gives them `ctx.workspace` and `ctx.exec` / `ctx.$` against that directory — the pod's allowlist (`git`, `gh`, `npm`, …, argv only, no shell) on your own PATH and git credentials. Without it a Job-tier step's `$` rejects `ExecError{code:'EXEC_UNAVAILABLE'}` naming the flag                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 ## Semantics worth knowing
 
@@ -34,7 +35,12 @@ _Source of truth: workflows-spec 03 §3.9 (WF-204/WF-225/WF-332). This page is t
 - **Retry backoff** runs on the virtual clock: `backoffSeconds · 2^(attempt-1)` capped at `maxBackoffSeconds`, printed as `[retry:<id>] backoff <n>s`.
 - **`foreach` `rateLimit`** is an in-memory token bucket — delayed starts print `[throttle:<id>] resumeAt=<iso>`; loop `intervalSeconds` prints `kind=loop_interval`.
 - **`suspend`** re-runs `execute` from the top with `resumeData` set — the documented Mastra semantics, exercised offline.
-- **`ctx.once`** settles against the in-memory effects map: a re-drive over the same ledger sends nothing twice.
+- **`ctx.once`** settles against the in-memory effects map: a re-drive over the same ledger sends nothing twice. (On the platform it is served to worker-tier steps; the Job pod does not serve `ctx.once` yet — LUA-706 — so a Job-tier step dedupes on `occurrenceId` itself.)
+- **`ctx.getInitData()`** is `null` on a run without `--input` and **`ctx.runtime`** is `{ trigger:'sdk', principalKind:'user' }` — the same shapes the pod and the worker serve, so a step that branches on them behaves offline as it does on the platform.
+- **Agent steps complete with the OBJECT, never a `{text, object}` wrapper** (LUA-751 — the engine's structured-output rule): under `--agents fake` a node with an `outputSchema` completes with a schema-shaped stub object (`{ summary: '', confidence: 0 }`), one without completes with `{ text: '[fake:<id>] …' }`; under `--agents live` / `--fixtures` the reply's `object` wins, else the single JSON value in its text is validated against the schema (`OUTPUT_SCHEMA_INVALID` names the miss). The next step's `inputData` is that value — a plain agent → code step declares `{ text: string }`.
+- **A `foreach`'s output is readable under its body id** — `fromStep('draftEmail')`, `${stepResults.draftEmail}`, `getStepResult('draftEmail')` after `.foreach(draftEmail)` are the ordered item outputs, and a container's `.join` is readable under the container id (`foreach@2`, `conditional@1`) — as the engine publishes them (LUA-639).
+- **`env.template('KEY')`** at a workflow file's module scope resolves to its placeholder when `lua workflows run` loads the artifact; the `--env KEY=value` overlay substitutes it on the graph.
+- **Script-form workflows** run on the replay wrapper bundled with the CLI (`@lua/sandbox-runtime/workflow-script-wrapper`) over the `workflow-script` parity context; a project that lists `@lua/sandbox-runtime` in its devDependencies runs that copy instead — see [Script form](./script-form.md).
 - **Not emulated offline**: the org pacing policy (no org context — `pacing_deferred` never appears locally), the runner mid-run kill (Ctrl-C is the local analogue), `backfillOnEnable`, and the `startWorkflowRunBatch` tool.
 
 ## Example
@@ -46,4 +52,12 @@ lua test workflow outreach --input @leads.json \
   --ledger-out out.json
 ```
 
-runs §3.2 (b) end to end with no prompt and no model call; `sendEmails` still runs (`ctx.once` against the effects map, so a second invocation with the same ledger sends nothing).
+runs §3.2 (b) end to end with no prompt and no model call; `sendEmails` still runs (`ctx.once` against the effects map, so a second invocation with the same ledger sends nothing) — its input is the approval's `WorkflowApprovalOutput`, the drafts come from `editedPayload` (the edit above) or `getStepResult('drafts')`.
+
+The three approval / typed-agent examples `lua init --with-examples` ships are pinned to run this way — `tests/__tests__/compile.workflow.examples-offline.test.ts`:
+
+```bash
+lua workflows run refund-approval --input '{"ticketId":"t1","amount":5,"requesterId":"u1"}' --approve approveRefund     # exit 0 (a stubbed Stripe passthrough in the test; `--step-output postRefund=…` on a machine without one)
+lua workflows run outreach --input '{"leads":[{"email":"a@b.co","name":"A"}]}' --approve reviewDrafts --step-output 'draftEmail={"to":"a@b.co","body":"hi"}' --step-output 'sendEmails={"sent":1}'
+lua workflows run research-brief --input '{"topic":"x"}' --step-output 'fetchSources={"urls":["https://a.example/1"]}'   # the fake agents take the lowConfidence arm
+```

package/docs/workflows/workspaces-and-long-steps.md

@@ -6,7 +6,7 @@ _Source of truth: workflows-spec 05 §5.17 (D19-r1/r2). This page is the develop
 
 ## Workspaces
 
-`workspace` on `createWorkflow` declares the checkout: `{ kind:'git', repo, ref, credentialsRef, sizeGb?, verify? }` or `{ kind:'empty' }`. Steps mount it with `workspace: { mount: 'rw'|'ro', isolation?: 'worktree' }` and read `ctx.workspace = { path, mount, branch }`.
+`workspace` on `createWorkflow` declares the checkout: `{ kind:'git', repo, ref, credentialsRef, sizeGb?, verify? }` or `{ kind:'empty' }`. Steps mount it with `workspace: { mount: 'rw'|'ro', isolation?: 'worktree' }` and read `ctx.workspace = { root, mount, branch, headSha, isolation, baseSha?, arm?, backend? }` — `root` is the absolute directory of the checkout (`/workspace`); `baseSha` is the commit the run's base ref resolved to at provision (`headSha` is where this step's checkout is), `arm` the worktree arm id under `isolation:'worktree'`, `backend` the volume backend — the three are present when the pod hands the run's stamps to the step and absent otherwise (an `empty` workspace, a shared mount). The pre-3.33 name `path` is served by the Job pod as a deprecated alias for one minor (it warns once per step) and then removed; new code reads `root`.
 
 `credentialsRef` is a connection id **or a key you declare under `connections: [{ key, integrationType }]`** — declare a key; it resolves against the owner agent's own connections on any agent at run time (see [Git credentials](./git-credentials.md)), so the definition never freezes a production id.
 
@@ -14,6 +14,40 @@ _Source of truth: workflows-spec 05 §5.17 (D19-r1/r2). This page is the develop
 
 **Worktree arms:** parallel arms never share a filesystem; each gets its own clone and branch and the `merge` step integrates them — put `verify` on the workspace so an agent-resolved conflict must pass your tests. `onConflict:'agent'` lets one resolver turn fix conflicts.
 
+## Commands from a code step — `ctx.exec` / `ctx.$`
+
+A Job-tier **code** step has no `child_process` — an import of it fails `lua compile` with `node-capability-unavailable` — and it builds no code from strings and compiles no WebAssembly (see the note at the end of this section). It runs commands through `ctx.exec` / `ctx.$`, which the Job pod executes on its behalf:
+
+```ts
+const runTests = createStep({
+  id: 'runTests',
+  tier: 'job',
+  workspace: { mount: 'rw' },
+  inputSchema: z.any(),
+  outputSchema: z.object({ passed: z.boolean() }),
+  async execute({ $, exec, inputData, log }) {
+    await $!.strict`npm ci`; // `.strict` throws ExecError on a non-zero exit
+    const r = await $!`npm test -- --maxWorkers=2`; // { code, stdout, stderr, durationMs, truncated, timedOut }
+    const sha = (await exec!(['git', 'rev-parse', 'HEAD'], { cwd: 'packages/app' })).stdout.trim();
+    await $!.strict`git add -- ${'CHANGELOG.md'}`; // each ${…} is ONE argument; `--` keeps a data value out of git's options
+    log(`tests ${r.code === 0 ? 'passed' : 'failed'} at ${sha}`);
+    return { passed: r.code === 0 };
+  },
+});
+```
+
+- **Argv only, never a shell.** `$` splits its literal text on whitespace (with `'…'` / `"…"` quoting) and passes every `${value}` as exactly one argument, never re-parsed — a title with spaces or a body with newlines is one argument. There is no `cd`, `&&`, `|`, glob or `$VAR`: a second command is a second call, and the cwd is the workspace root (`{ cwd: 'packages/app' }` for a directory inside it).
+- **Allowlist.** `git`, `gh`, `pnpm`, `npm`, `npx`, `node`, `yarn`, `python3`, `pytest`, `make` — bare names, resolved from the pod image's own PATH. `sh -c`, `bash`, `curl` or a path is refused before anything runs (`ExecError{code:'EXEC_REFUSED'}`, `reason` says why). **The allowlist is not the image's inventory:** today's Job image ships `git`, `gh`, `node`, `npm`, `npx` (plus `corepack`, `gitleaks`, `claude`, `curl` for the harness); `pnpm`, `yarn`, `python3`, `pytest` and `make` are on the list for the local driver and a future image but fail `EXEC_REFUSED/binary_not_found` in the pod today — run them offline, or use `npx` / `npm exec` for what npm can fetch.
+- **git rules.** The same as a coding turn's git tool: no `-C`, `--git-dir`, `--work-tree`, `--exec-path` (the repository is the workspace and the binary is the host's — use `{ cwd }`); no `-c` over what git would execute or route through (`core.hooksPath`, `core.fsmonitor`, `protocol.*`, `credential.*`, `url.*`, proxies, editors, filters); no `git config` (the commit identity and every setting a step needs come from the host); no `credential*`, `push-mirror`, `daemon`. **`git push`** is refused on an `ro` mount and with `--force` / `-f` / `--force-with-lease` / `--delete` / `--mirror` / `--prune` / `--all` / `--tags`, and every push first runs the same pre-push secret scan the harness's own push runs (05 §5.17.6) — a finding refuses it (`EXEC_REFUSED/git_push_refused`). Put `--` before positional values that come from data: `$\`git add -- ${file}\``, `$\`git log -- ${path}\``.
+- **Budget.** `timeoutMs` (default 10 min) is capped by the step's remaining wall; on expiry the command's whole process tree is killed and the call rejects `EXEC_TIMEOUT`. stdout and stderr are each kept to 1 MiB (`truncated`). One command runs at a time.
+- **Env.** The command sees a scrubbed env — no token, no `LUA_WF_*`, no cloud credential. git runs exactly as the harness's own git does: through the credential-proxy remote, hooks and other repo-configured commands off, `GIT_TERMINAL_PROMPT=0`, the run's commit identity; `gh` and the package managers run non-interactive. A step that declares `jobTools: ['gh']` gives its `gh` (and only `gh`) the sidecar's gh proxy env, exactly what a coding turn's `gh` tool gets — the proxy admits `gh pr create` / `gh pr edit` / `gh pr comment` on the pinned repository and nothing else: **no `gh pr merge`** (a merge stays with a person), no `/graphql`. `env: { NODE_ENV: 'test' }` adds variables; `PATH`, `HOME`, `GIT_*`, `GH_*`, `LUA_*`, `NODE_OPTIONS` cannot be overridden.
+- **Errors.** A non-zero exit is data (`result.code`). `exec.strict` / `$.strict` throw an `ExecError` — `name === 'ExecError'`, `code` one of `EXEC_FAILED` | `EXEC_TIMEOUT` | `EXEC_REFUSED` | `EXEC_UNAVAILABLE`, with `exitCode`, `stdout`, `stderr`. Check `name` / `code`, not `instanceof` (the pod runs a step in its own realm). `undefined` interpolated into `$` is refused, never stringified.
+- **Tier.** Worker-tier steps have neither `exec` nor `$`. Shell work with a model in the loop is a Job-tier `agentStep` (its `shell` tool, below). The command line, exit code and duration are logged to the run's job-logs; the output is not — `log()` what matters.
+
+An `ro` mount is read-only at the volume (the PVC is mounted `readOnly`): a command that writes fails `EROFS`, and `git push` is refused on it.
+
+**No code from strings, no WebAssembly — Job tier only.** Inside a Job-tier code step, `eval`, `new Function` (the `Function` constructor reached any way, `Buffer.constructor` included) and `new WebAssembly.Module` / `WebAssembly.compile` / `WebAssembly.instantiate` throw — `EvalError` / `CompileError`, surfaced as `USER_CODE_ERROR` with the reason named — because the pod runs the step with code generation off in both realms (`--disallow-code-generation-from-strings` on the child process, `codeGeneration: { strings: false, wasm: false }` on the vm context). `WebAssembly.validate` still answers (it compiles nothing). A library that builds code from strings at import time fails the same way. The worker tier has neither restriction: a step that needs either stays `tier: 'worker'`.
+
 ## Coding turns
 
 A Job-tier `agentStep` is a coding turn (Claude Code or the generic harness — see [Coding harness](./coding-harness.md)) with the `WORKFLOW_JOB_TOOLS` set (`shell`, `read`, `write`, `edit`, `glob`, `grep`, `git`, …). MCP connections mount via `toolScope.connectionIds`: your connections are mounted through a local proxy; the model never sees a token, and a tool that needs approval is refused inside the turn — hand it to a worker-tier step.
@@ -26,4 +60,4 @@ GitHub review loops: the PR body carries `<!-- lua-run:<runId> -->`; the GitHub
 
 ## Offline
 
-The local driver emulates the tier: `--workspace <dir>`, `--job-wall <s>`, worktree arms as literal `git worktree add`, `--segment-wall` for segment rehearsal. `credentialsRef` is printed and never resolved offline.
+The local driver emulates the tier: `--workspace <dir>` gives Job-tier code steps `ctx.workspace` and `ctx.exec` / `ctx.$` against that directory (the pod's allowlist, your own PATH and git credentials; without the flag a Job-tier step's `$` rejects `EXEC_UNAVAILABLE`), `--job-wall <s>` rehearses the segment wall for agent steps. `credentialsRef` is printed and never resolved offline.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.32.1",
+  "version": "3.32.3",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",
@@ -113,10 +113,11 @@
     "stripe": "^19.2.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
-    "@lua/shared-sandbox": "0.0.1",
-    "@lua/workflow-graph": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
-    "@lua/shared-types": "0.0.1"
+    "@lua/shared-types": "0.0.1",
+    "@lua/workflow-graph": "0.0.1",
+    "@lua/sandbox-runtime": "0.0.1",
+    "@lua/shared-sandbox": "0.0.1"
   },
   "scripts": {
     "clean": "rm -rf dist temp",

package/template/examples/workflows/CLAUDE.md

@@ -5,17 +5,17 @@ Worked examples from workflows-spec 03 §3.2 (the spec is normative — do not r
 it (a `.then(createStep)` placement used as a string-ref target; a `template(…)` approval title). The note says what
 changed and why; `tests/__tests__/compile.workflow.examples.test.ts` compiles every file here, so a drift cannot return.
 
-| File                                                                                              | Shows                                                                                                                                           |
-| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `research-brief.ts`                                                                               | (a) sequential + parallel research, typed predicates (`stepOf`/`gt`/`lit`), switch + otherwise                                                  |
-| `outreach.ts`                                                                                     | (b) `foreach` + editable approval + an exactly-once send (`ctx.once`), cron schedule, `concurrencyPolicy`                                       |
-| `provision-tenant.ts`                                                                             | (c) nested workflow + `sleep` + `waitForSignal`                                                                                                 |
-| `reviewed-brief.ts`                                                                               | (d) `specialistStep` — an ephemeral reviewer role on the owning agent (D25)                                                                     |
-| `refund-approval.ts`                                                                              | (e) maker-checker + four-eyes + business-hours escalation chain + a recoverable external step (`onError:'park'`)                                |
-| `ticket-to-pr.ts` + `pr-review-round.ts` + `linear-ready.trigger.ts` + `github-review.webhook.ts` | (f) the SWE headline: Job tier, worktree arms + merge, review loop over a child workflow, trigger `startWorkflow`, webhook → `Workflows.signal` |
-| `support-triage.ts`                                                                               | (g) knowledge grounding, mandatory `toolScope` on external content, dataset rows, `ctx.artefacts`                                               |
-| `adversarial-verify.workflow.script.js`                                                           | (i) script form — `step()` inline effect + a library `role:{ref}`                                                                               |
-| `vendor-invoices.ts`                                                                              | (j) per-item approvals (`itemsPath`), `env.template()` overlays, `outputVisibility`                                                             |
+| File                                                                                              | Shows                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `research-brief.ts`                                                                               | (a) sequential + parallel research, typed predicates (`stepOf`/`gt`/`lit`), switch + otherwise                                                       |
+| `outreach.ts`                                                                                     | (b) `foreach` + editable approval + an exactly-once send (`ctx.once`), cron schedule, `concurrencyPolicy`                                            |
+| `provision-tenant.ts`                                                                             | (c) nested workflow + `sleep` + `waitForSignal`                                                                                                      |
+| `reviewed-brief.ts`                                                                               | (d) `specialistStep` — an ephemeral reviewer role on the owning agent (D25)                                                                          |
+| `refund-approval.ts`                                                                              | (e) maker-checker + four-eyes + business-hours escalation chain + a recoverable external step (`onError:'park'`)                                     |
+| `ticket-to-pr.ts` + `pr-review-round.ts` + `linear-ready.trigger.ts` + `github-review.webhook.ts` | (f) the SWE headline: Job tier, worktree arms + merge, review loop over a child workflow, trigger `startWorkflow`, webhook → `Workflows.signal`      |
+| `support-triage.ts`                                                                               | (g) knowledge grounding, mandatory `toolScope` on external content, dataset rows, `ctx.artefacts`                                                    |
+| `adversarial-verify.workflow.script.js`                                                           | (i) script form — `parallel()` over thunks, a `step()` inline reduction that returns (never mutates) — runs offline on the bundled wrapper (LUA-751) |
+| `vendor-invoices.ts`                                                                              | (j) per-item approvals (`itemsPath`), `env.template()` overlays, `outputVisibility`                                                                  |
 
 Recipes:
 
@@ -25,3 +25,9 @@ Recipes:
 - Every doc rule worth repeating: _execute re-runs from the top after resume; execution is at-least-once — dedupe
   on `occurrenceId`_ (`${lineageId}:${stepId}`); an effect unique across independent runs needs your own business
   key (`refund:${ticketId}`).
+- The step after an `.approval()` receives the approval node's output — `WorkflowApprovalOutput` (`@lua/shared-types`):
+  `{ approved, decision, text, note?, editedPayload?, editRevision?, decidedBy?, timedOut?, escalations? }`, the same shape
+  on the engine and under `lua workflows run --approve/--deny` (LUA-751; `tests/__tests__/compile.workflow.examples-offline.test.ts`
+  runs `refund-approval`, `outreach` and `research-brief` offline over the shared fixture). The original payload is not
+  echoed back — `refund-approval` reads it with `getStepResult('refundRequest')` (the map ahead of its approval: the
+  payload the approver sees and edits is exactly what `editedPayloadSchema` describes), `outreach` with `getStepResult('drafts')`.