lua-cli 3.29.1 → 3.31.0

package/docs/workflows/limits.md

@@ -0,0 +1,11 @@
+# Limits and caps
+
+_Source of truth: workflows-spec 10 / 16. This page is the developer summary; the spec is normative._
+
+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.
+
+## 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.
+
+Offline, the driver has no org context: a `tool`/`http` step dispatches immediately and `pacing_deferred` never appears locally. Customer-side pacing of a `foreach` (`rateLimit: { perSecond | perMinute }`) IS emulated — an in-memory token bucket printing `[throttle:<id>] resumeAt=<iso>`.

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

@@ -0,0 +1,13 @@
+# Long steps and checkpoints (Cluster I)
+
+_Source of truth: workflows-spec 05 §5.17.4 (D19-r2). This page is the developer summary; the spec is normative._
+
+A Job step may run up to **24 h** (`timeoutSeconds` ≤ 86 400). The platform runs it as **segments** of ≤ 4 h: at every 4 h boundary — and every 30 min in between — your branch is committed and pushed and the coding session is saved; the next segment resumes from that commit on the same volume with the same attempt and the same billing epoch; a code step is re-entered from the top with `LUA_WF_JOB_SEGMENT` set, so **make it idempotent on the tree**.
+
+- A step past 14 400 s requires a workspace (`long-job-requires-workspace`) — the checkpoint needs somewhere to commit.
+- **Eviction** (`JOB_EVICTED`) resumes from the last checkpoint — at most 30 min of work is redone; no attempt bump.
+- `lua workflows jobs` / `job-logs --segment <n>` read a segmented step; the timeline shows `s<n>/<total> · resumed from checkpoint`.
+
+## Rehearsing offline
+
+`--segment-wall <s>` (default 14 400) shrinks the segment wall — set it to `30` to exercise a 24 h step in a minute: the driver commits the checkpoint literally (`[lua-wf] checkpoint <stepId> s<n>`), saves the session under `<workspace>/.home/.lua-wf/`, and re-enters the step with `LUA_WF_JOB_SEGMENT` bumped. `--evict-at <stepId>=<s>` simulates an eviction; `--checkpoint-interval <s>` makes interval checkpoints visible.

package/docs/workflows/migrating-cloud-tasks.md

@@ -0,0 +1,9 @@
+# Migrating cloud tasks (jobs) to workflows
+
+_Source of truth: workflows-spec (Cluster J B9, D12-r2). This page is the developer summary; the spec is normative._
+
+`lua workflows import-job <jobName>` writes a one-step workflow file wrapping the job's `execute` (schedule + input carried over) into `src/workflows/`. It **writes a file** — it does not deploy anything.
+
+**Deactivate the agent job yourself** (D12-r2: the platform never migrates a job) — after you push and activate the workflow, run `lua jobs`-side deactivation, or both will fire.
+
+The unified read: `lua workflows list --all` / the desktop cloud-tasks view show jobs and workflows side by side so nothing is lost mid-migration.

package/docs/workflows/migrating-runs.md

@@ -0,0 +1,13 @@
+# Migrating runs between versions
+
+_Source of truth: workflows-spec (Cluster D R46/R47, D7-r2). This page is the developer summary; the spec is normative._
+
+`lua workflows migrate-runs <workflowId> --from <ver> --to <ver>` re-pins runs to a new version where compatible (`isResumeCompatible` — same seeding math as repair runs); `cancel-by-version` recalls a bad version's fleet.
+
+## Edited inputs
+
+`--resume-override <path>=<json>` patches the seeded input where the target version's schema requires it — validated against the TARGET schema before anything moves.
+
+## Running runs
+
+A **running** run is scheduled and moves at its next step boundary or park — never mid-step; after `LUA_WF_MIGRATION_DRAIN_MAX_HOURS` it is refused, not forced. Suspended/gated runs move immediately; incompatible runs are reported per-run with the incompatibility, never skipped silently.

package/docs/workflows/output-visibility.md

@@ -0,0 +1,9 @@
+# Output visibility
+
+_Source of truth: workflows-spec (Cluster K B44). This page is the developer summary; the spec is normative._
+
+`outputVisibility: { roles: [...] }` on `createWorkflow` **restricts who can READ what a workflow produced; it never restricts who can run it.** A reader outside the roles gets `restricted: true` and no `output` from `Workflows.get`/`list` — never an error.
+
+- ANDs with the org's `workflowPolicy.artefactAcl` — the narrower set wins.
+- **Owner bypass** is on by default; every bypass read leaves an audit line.
+- The ACL is hashed into `run.aclHash` at start: **changing roles affects new runs only.**

package/docs/workflows/per-item-approvals.md

@@ -0,0 +1,9 @@
+# Per-item approvals
+
+_Source of truth: workflows-spec 06 (Cluster K B20, WF-544). This page is the developer summary; the spec is normative._
+
+`itemsPath: 'invoices'` fans one approval node out to **one decision per item**; `itemApprover: { fromItem: 'approverEmail' }` routes each item to ITS approver (the parent `approver` keeps the overview card); `itemTimeout: { timeoutHours }` expires unanswered items as `expired`. The node resumes with `resumeData.items[]` (+ `approved = every item approved`) — feed approved rows to a `foreach` (see the `vendor-invoices` example).
+
+> **T50 caution:** `fromItem` trusts the payload to NAME the approver; membership + `workflows:execute` is what makes it safe — never derive the approver from external content.
+
+Offline: `--approve-item <id>=<index>:approve|deny[=@payload]` (repeatable); `--approve <id>` on an items approval is exit 2 ("per-item approval: use --approve-item"). Text channels approve/deny the whole batch only.

package/docs/workflows/private-network-sources.md

@@ -0,0 +1,12 @@
+# Private-network sources
+
+_Source of truth: workflows-spec (ICP P1-20). This page is the developer summary; the spec is normative._
+
+**The boundary:** the sandbox reaches the public internet on any port and Lua services; it does **not** reach `10/8`, `172.16/12`, `192.168/16`, `169.254/16`, `100.64/10` — a VPC database, an on-prem ERP, a peered network.
+
+**The exact error:** a step that tries gets `EGRESS_DENIED { host, ip, port }` within seconds — never a `WALL_TIMEOUT`. If you see a hang instead, you are not hitting this boundary.
+
+## The two supported patterns
+
+1. **Expose the source behind a public TLS endpoint** (or an API gateway) with an allow-list — the sandbox reaches any public host/port.
+2. **Ask for a partner carve-out** — a platform-team lua-iac PR adding your source's `/32` + port to the runner and Job NetworkPolicies (`platforms/aws/prod/INTEGRATIONS.md`; carve-outs are CI-guarded by `policy/check-partner-egress.py`). Budget lead time, and supply the exact `/32` and port.

package/docs/workflows/recovery.md

@@ -0,0 +1,28 @@
+# When a step parks
+
+_Source of truth: workflows-spec 01 §1.6-r1 / 06 §6.3.5. This page is the developer summary; the spec is normative._
+
+A **park** is the platform refusing to guess. Two things park a step:
+
+1. **`sideEffects:'external'` + a platform fault.** A worker crash, an eviction or a network partition while an external-effect step was in flight means the platform cannot know whether the effect happened (`EFFECT_IN_DOUBT`). **The platform never re-runs an external step on its own** — the step parks and the run gates `exception`.
+2. **`onError:'park'`.** A final (retries exhausted) failure parks instead of failing the run — for steps where an operator should decide.
+
+## The three verbs
+
+A parked step waits for exactly one of:
+
+- **`retry-step`** — re-runs `execute` with the **same `occurrenceId`** (`${lineageId}:${stepId}`), so every `ctx.once(key, fn)` effect that already settled returns its stored result and is never re-sent.
+- **`resolve-step`** — you supply the step's output (validated against `outputSchema`); the run continues as if the step had returned it.
+- **`skip`** — marks the row skipped; downstream bindings render `status="skipped"`.
+
+`fail` (or cancelling the run) applies the step's failure as-is. From the CLI: `lua workflows status <runId>` shows the park, `lua workflows resume` / the desktop inbox carry the verbs.
+
+## Repair runs
+
+When a whole run is beyond per-step repair, a **repair run** re-drives the graph seeded from the ledger (the §05 §5.5.4.1 seeding math — the same `seedLedgerFromRun` the CLI's `--from-run` uses): every `completed` step keeps its outputs, attempts and settled effects, and the frontier restarts at the first non-completed step. Because `occurrenceId` is stable across retry, resume, `retry-step` **and** a repair run, an external effect executes at most once per occurrence.
+
+> **The rule to remember:** *execution is at-least-once — dedupe on `occurrenceId`*; an effect that must be unique across **independent** runs needs your own business key (`refund:${ticketId}`).
+
+## Rehearsing offline
+
+`lua test workflow <name> --park <stepId>` simulates the platform-fault reclaim locally and offers the same verbs (`retry / skip / complete / fail`) on stdin — see [Testing offline](./testing-offline.md).

package/docs/workflows/replay-local.md

@@ -0,0 +1,35 @@
+# `lua workflows replay <runId> --local` — runtime packaging
+
+_Source of truth: workflows-spec 03 §3.10, 04 §4.3.5, 05 §5.7.1, 12 §12.9.11 (WF-324 / WF-332, WB-09). This page records the packaging decision for the script-form replay wrapper; the spec sections are normative._
+
+## The decision (wave 5, WB-09)
+
+`replay --local` for a **script** run re-runs the runner's own replay wrapper (`buildWorkflowScriptWrapper`, `@lua/sandbox-runtime`) against the R6 `?format=replay` bundle and diffs the re-issued `callHash`es against the server journal. `lua test workflow <name>` on a `*.workflow.script.js` file drives the same wrapper through an offline tick loop.
+
+Two options were on the table:
+
+| Option | Shape | Verdict |
+| --- | --- | --- |
+| **A — project-local runtime, resolved lazily** | `@lua/sandbox-runtime` is NOT bundled into the published CLI. The verb resolves it with `createRequire(<project>/package.json)` at call time; a miss is the typed error `REPLAY_RUNTIME_UNAVAILABLE` (exit 3), never a silent "stable". | **Chosen.** |
+| B — a published replay runtime (`@lua/workflow-replay`) | Extract the wrapper source + `createSandboxContext` into a small published package the CLI depends on. | Deferred: it would fork the wrapper text away from the runner (the §2.2 parity rule says one implementation), and the wrapper is versioned by `journalProtocolVersion` (N-1 window, 04 §4.3.5) — a second package would have to track that window. Revisit at GA if partner projects outside the monorepo need `replay --local`. |
+
+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.
+
+## 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>`.
+- The graph-form `replay --local` (R4/R5 → `replayLedger`) has no runtime dependency and always works.
+
+## Exit matrix (script form)
+
+| 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 |
+| 4 | `LEDGER_DIVERGENCE` / `JOURNAL_DIVERGENCE` — at least one `hash_mismatch` / `journal_longer_than_script` row |
+
+## Related
+
+- `docs/workflows/script-form.md` — authoring `*.workflow.script.js`, `lua push`, `lua test workflow` on a script.
+- `packages/lua-cli/src/utils/workflow-script-replay.ts` — `loadLocalScriptRunner`, `compareScriptReplay` (pure; what the tests pin).

package/docs/workflows/reply-channels.md

@@ -0,0 +1,11 @@
+# Reply channels
+
+_Source of truth: workflows-spec (Cluster K B42). This page is the developer summary; the spec is normative._
+
+A run started from a conversation carries `replyTo: { channel, threadId }`; at terminal state the platform sends the outcome back through a **`ChannelAdapter`** — a new channel is one adapter file + one registry entry.
+
+- Registered today: **whatsapp**. `sms` / `email` / `webchat` / `slack` are specified and land behind their E-10 pins; an unregistered channel fails loudly (`channel_unsupported`), never silently drops.
+- Slack `threadId` format: `<channelId>:<thread_ts>`.
+- A step may answer the customer itself mid-run (`Channels.<channel>.send` inside `ctx.once`) — the terminal reply then lands as a duplicate-safe fallback on the same thread.
+
+Offline: `--reply-to <channel>:<threadId>` prints the would-be reply on the terminal.

package/docs/workflows/retention-and-archival.md

@@ -0,0 +1,82 @@
+# Workflows — retention and archival
+
+_Source of truth: workflows-spec 02 §2.14, 03 §3.10, 11 §11.11.1 (WF-428 / WF-443, WB-01). This page is the operator-facing summary; the spec sections are normative._
+
+## Retention model
+
+| Data | Clock | Default | Org control |
+| --- | --- | --- | --- |
+| `workflow_runs` and every child row (`workflow_step_runs`, `workflow_run_events`, `workflow_run_signals`, `workflow_artefacts`) | `expiresAt = completedAt + retentionDays` stamped by the run's terminal write; children tightened to the run's stamp | 90 d (`LUA_WF_RETENTION_DAYS_DEFAULT`) | `workflowPolicy.retentionDays` (R23), **7..90**, clamp-down only |
+| Hidden `wf-` threads (agent-step + loopback threads) | `payloadsExpireAt` (else `expiresAt`) — sweep #31 `hidden-thread-gc` | same | same |
+| `workflow_migrations` rows | `finishedAt + 400 d` — never purged with a run | fixed | none |
+| Audit rows (lua-auth) | audit retention | fixed | none |
+
+**Clamp-down only.** Lowering `retentionDays` restamps every terminal row of the org whose `expiresAt` sits past `completedAt + newDays` (the R23 write flags `retentionRestampPending`; sweep #13 `ttl-stamp` lowers the run, then steps/events/signals/artefacts with a `{expiresAt:{$gt}}` guard). Raising it restamps **nothing** — an `expiresAt` already stamped is never raised, and the platform 90 d stays the ceiling (`RETENTION_OUT_OF_RANGE` 400 outside 7..90). Every change emits audit `workflow.policy.retention_changed{from, to, restampPending}`.
+
+Runs the org still needs past their retention must be **archived out** before the TTL fires — that is the `archive-runs` hop below.
+
+## `lua workflows archive-runs`
+
+Pages the agent's terminal runs (R2, `status ∈ completed|failed|cancelled|timed_out|abandoned`, oldest first), requests an export bundle per run (R50 `POST /runs/:id/export` → R51 `GET /runs/:id/export`) at `--concurrency` (default 4), and writes each bundle plus an `archive-index.ndjson` to the sink.
+
+```
+lua workflows archive-runs \
+  --agent <agentId> \
+  --since 2026-06-01 --until 2026-08-01 \
+  --sink s3://acme-workflow-archive/prod/ \
+  --connection <orgStorageConnectionId> \
+  --concurrency 4
+```
+
+- **Sinks:** `s3://` and `gs://` through an org storage connection (`--connection`); the CLI never holds cloud credentials itself. A local directory sink is accepted for dry runs.
+- **Skip rule:** a run is skipped (`skipped:'already_exported'` in the index) when `run.exportedAt ≥ run.completedAt` **and** the sink already holds the bundle whose `manifest.sha256` matches — re-running the hop is idempotent and cheap.
+- **Index:** one line per run — `{runId, status, completedAt, exportedAt, sha256, objectKey, bytes, skipped?, error?}` (`WorkflowArchiveIndexRow` in `@lua/shared-types`).
+- **Window guard:** a run whose `completedAt` is older than `retentionDays − 7 d` may be reaped mid-export; the hop refuses the whole window with `ARCHIVE_WINDOW_TOO_OLD` (exit 4) rather than produce a partial archive. Narrow `--since` or run the hop more often.
+
+### Exit matrix
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | every selected run exported or skipped |
+| 1 | ≥ 1 run failed to export — listed in the index with `error`; re-run to retry only those |
+| 3 | sink or storage connection unavailable — nothing written |
+| 4 | `ARCHIVE_WINDOW_TOO_OLD` — the window reaches past `retentionDays − 7 d` |
+
+## Weekly cron template
+
+Run the hop weekly per agent, one day inside the window guard. The CronJob manifest lives in lua-iac (`workload-cronjob-*.tf`) — this repo carries no k8s manifests. Every cronjob **must** heartbeat (repo `CLAUDE.md`): create the Betterstack heartbeat (period 7 d, grace ≈ 1 d), store its URL in Secrets Manager under `<service>/prod/heartbeat-url-wf-archive-<agent>`, and wrap the command:
+
+```yaml
+command:
+  - /bin/sh
+  - -c
+  - |
+    set +e
+    lua workflows archive-runs --agent "$AGENT_ID" --since "$(date -u -d '-14 days' +%F)" \
+      --sink "$ARCHIVE_SINK" --connection "$STORAGE_CONNECTION_ID" --concurrency 4
+    EXIT=$?
+    if [ $EXIT -eq 0 ]; then
+      curl -fsS --max-time 10 --retry 2 "$HEARTBEAT_URL" || true
+    else
+      curl -fsS --max-time 10 --retry 2 --data-urlencode "exit=$EXIT" "$HEARTBEAT_URL/fail" || true
+    fi
+    exit $EXIT
+env:
+  - name: HEARTBEAT_URL
+    valueFrom:
+      secretKeyRef:
+        name: lua-cli-archive-secrets
+        key: HEARTBEAT_URL_WF_ARCHIVE
+        optional: true
+```
+
+The three invariants: the hop's own non-zero exit propagates (`exit $EXIT`), heartbeat pings use `|| true`, and `optional: true` on the secret ref keeps staging (no heartbeat) runnable.
+
+## Related sweeps
+
+| # | name | what it does |
+| --- | --- | --- |
+| 13 | `ttl-stamp` | backstop stamp + clamp-down restamp + 400 d migration counter + orphan artefact reap |
+| 15 | `wf-thread-ttl` | 90 d backstop for hidden threads minted before `payloadsExpireAt` existed |
+| 19 | `org-purge` | offboarding / agent-delete cascade (fence → drain → done) |
+| 31 | `hidden-thread-gc` | hidden `wf-` threads past the payload clock, through the conversation scrub |

package/docs/workflows/roles.md

@@ -0,0 +1,12 @@
+# Roles — the workflow role library
+
+_Source of truth: workflows-spec (Cluster J B18, D25-r1). This page is the developer summary; the spec is normative._
+
+`lua roles` manages the owner's `workflowRoles[]` library (`list · view · save · delete`). Both forms bind a saved role:
+
+- Builder: `specialistStep(id, { role: { ref: '<roleName>' }, … })` — or an inline `{ name, instructions, tools }` role (see the `reviewed-brief` example).
+- Script form: `role: { ref: '<roleName>' }` in an `agent(...)` call — the CLI collects it into `roleBindings` with `status:'deferred'` (it never reads the library); resolution happens at push.
+
+**A library edit never changes a published version — push again.** Versions pin the resolved role bytes; `lua workflows versions` marks a version whose role source has drifted with `⚠ stale`.
+
+Role tools are a subset of the owning agent's toolset; delegation tools (`agent-*`) are never allowlistable. Offline, `--agents fake` prints `[fake:<id> as <role.name>]`; a role block under `--agents live` is a client-side approximation — the allowlist is enforced server-side only.

package/docs/workflows/schedules.md

@@ -0,0 +1,11 @@
+# Schedules
+
+_Source of truth: workflows-spec 07 §7.1. This page is the developer summary; the spec is normative._
+
+`schedule: { type:'cron', expression: '0 9 * * 1', timezone: 'Europe/London' }` on `createWorkflow` fires runs on the cron grid; `scheduleInput` is the run input. `concurrencyPolicy:'forbid'` skips a fire while a run is in flight (the skip is recorded, never queued). Manage with `lua workflows activate` / `deactivate`; `lua workflows backfill` starts missed occurrences by hand (deduplicated on `backfill:<workflowId>:<occurrenceIso>`).
+
+## Re-enabling a schedule
+
+A paused or auto-disabled schedule never replays missed fires by itself; opt in with `schedule.backfillOnEnable: { maxOccurrences }` (or `lua workflows activate --backfill` for one re-enable) and the most recent misses start as one batch, deduplicated against `lua workflows backfill` by the shared `backfill:<workflowId>:<occurrenceIso>` key, capped, and summarised in your inbox.
+
+Offline, schedules do not fire (`backfillOnEnable` is not emulated) — start runs with `lua test workflow` / `lua workflows start`.

package/docs/workflows/script-form.md

@@ -0,0 +1,50 @@
+# Script-form workflows — `src/workflows/<name>.workflow.script.js`
+
+_Source of truth: workflows-spec 04 §4.3 (D15-r2, Cluster J B12 — WF-527, WB-09 push half / WB-03 script host). This page is the developer summary; the spec is normative._
+
+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' })]);
+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;
+```
+
+## Rules the CLI checks before anything is sent
+
+Run in this order — the same order lua-api re-validates on push (one implementation, decision §2.2):
+
+1. **`meta` (04 §4.3.1)** — the FIRST statement, a pure object literal (strings/numbers/booleans/null/arrays/objects only): `name` `/^[a-z][a-z0-9-]{0,63}$/` **equal to the file stem** (`SCRIPT_META_INVALID{name-file-mismatch}`), `description` ≤ 500, optional `phases[]` (≤ 64 × `{title ≤ 80, detail? ≤ 300, model?}`), `whenToUse`, `concurrency` 1..32, `sampleArgs` (the `args` of the validation tick and of `lua test workflow`), ≤ 4 KB.
+2. **Determinism lint (04 §4.3.3)** — the banned identifier set is DERIVED from the sandbox's own lists (`WORKFLOW_SCRIPT_REMOVED_GLOBALS` + trapped timers + forbidden platform keys), plus `Date.now`, `new Date()` with no argument, `Math.random`, `eval`, `new Function`, `with`, `globalThis`, and any `import`/`export` other than `meta`. Every hit is `file:line:col — SCRIPT_NONDETERMINISM{<kind>} …`. **The closure passed to `step(label, fn)` is exempt** (its result is journaled once and memoised on replay); `fn` must be a function literal or a module-scope function (`step-fn-not-literal`), `timeoutSeconds` a literal 1..600 (`step-timeout-invalid`).
+3. **`role: { ref }`** collection — literal refs become `roleBindings[{ref, status:'deferred'}]` (the CLI never reads the role library; the server fills them at push); a non-literal `ref` is `role-ref-unknown`, `ref` mixed with inline members is `role-ref-and-inline`.
+4. **`scriptSurface`** — `{ hostCalls: {member: count}, hasExternalSideEffects }` (`tool(..., {sideEffects:'external'})`, `shell()`, `merge()`, Job-tier `agent()`), shown on the consent card instead of the text.
+5. **`scriptHash`** = `sha256-cj1:` + sha256(canonicalJson({ script, meta })).
+
+## `lua push workflow`
+
+`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.
+
+## `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:
+
+| 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.
+
+## `step(label, fn, { timeoutSeconds? })`
+
+Journals as `kind:'code'` with `callHash = hash(label, fn.toString())`; replay memoises the recorded result and never re-executes the closure; more than 64 `step()` closures in one tick is `script-step-too-many`; a throw is `SCRIPT_STEP_THREW{message}` (catchable); the wall is `SCRIPT_STEP_TIMEOUT`. Every `step()` site makes the script non-representable as a graph (`lua workflows export --form graph` → `script-not-graph-representable{inline-code}`).
+
+## Example
+
+`template/examples/workflows/adversarial-verify.workflow.script.js` — a finder/verifier loop with a `step()` reduction.

package/docs/workflows/testing-offline.md

@@ -0,0 +1,46 @@
+# Testing offline — the local reference driver
+
+_Source of truth: workflows-spec 03 §3.9 (WF-204/WF-225/WF-332). This page is the developer summary; the spec is normative._
+
+`lua test workflow <name>` (alias `lua workflows run <name>`) drives a compiled workflow **offline**: the same `compilePlan`, predicates and mappings the engine uses, code steps executed in the `lua test` sandbox, agent steps faked by default, waits fast-forwarded on a virtual clock. Exit codes: `0` completed · `2` usage/validation · `4` failed · `5` missing fixture.
+
+## 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 |
+
+## Semantics worth knowing
+
+- **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.
+- **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
+
+```bash
+lua test workflow outreach --input @leads.json \
+  --step-output draftEmail=@fixtures/draft.json \
+  --approve reviewDrafts=@edited.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).

package/docs/workflows/workspace-backends.md

@@ -0,0 +1,11 @@
+# Workspace backends — `ebs` / `efs` / `s3`
+
+_Source of truth: workflows-spec 05 §5.17 (D27). This page is the developer summary; the spec is normative._
+
+`workspace.backend`:
+
+- **`ebs`** — the default and what every org has today: one zonal volume, one clone per parallel arm, merged through your remote.
+- **`efs`** — arms get one shared checkout and a local merge (shared `mount:'ro'` arms are allowed in one `parallel`; merge without fetch).
+- **`s3`** — no volume; a prefix is synced at every checkpoint — larger workspaces, slower steps.
+
+`efs` and `s3` are **refused, not downgraded**, until the platform opens them for your org (`workspace-backend-unavailable`, gate `EXT-EFS` — see [Compliance gates](./compliance-gates.md)). The local driver prints the declared backend, always uses a local dir, and applies the `efs` validator differences so an offline run matches what an open gate would do.

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

@@ -0,0 +1,27 @@
+# Workspaces and long steps — the Job tier
+
+_Source of truth: workflows-spec 05 §5.17 (D19-r1/r2). This page is the developer summary; the spec is normative._
+
+`tier:'job'` runs a step as a **Kubernetes Job per attempt** — up to **24 h** as a chain of ≤ 4 h segments (see [Long steps and checkpoints](./long-steps-and-checkpoints.md)), with `jobResources: 'small'|'medium'|'large'`, a real filesystem and real cancel.
+
+## 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 }`.
+
+**The release-at-suspension rule:** when your run waits for a person or a signal, its volume is released: committed work is on the run branch `lua/wf-<lineageId>` on your remote; untracked files — `node_modules`, build output — are rebuilt when the next step restores the checkout.
+
+**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.
+
+## 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.
+
+GitHub review loops: the PR body carries `<!-- lua-run:<runId> -->`; the GitHub webhook routes `pull_request_review` to `Workflows.signal(runId, 'github.review', …)` — see the `ticket-to-pr` example.
+
+## Memory on the Job tier
+
+> `jobResources:'large'` (4 CPU / 8 GiB) is the ceiling. A container that exceeds its class's memory limit is OOM-killed and the step fails `job_oom_killed` — that is your fault, not a platform fault: it is not retried unless you declare `retry`, and the error's `sizeClassHint` tells you whether a bigger class exists. Test suites are the usual culprit: jest spawns a worker per CPU and `mongodb-memory-server` boots a `mongod` per test file, so run `npm test -- --maxWorkers=2` (or set `maxWorkers` in `jest.config`) inside a Job step, keep `runInBand` for suites with in-memory databases, and split a monorepo suite across `parallel` worktree arms rather than sizing up.
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.29.1",
+  "version": "3.31.0",
   "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",
@@ -21,6 +21,10 @@
     "./voice/test": {
       "types": "./dist/voice/test/index.d.ts",
       "default": "./dist/voice/test/index.js"
+    },
+    "./workflow-builder": {
+      "types": "./dist/workflow-builder.d.ts",
+      "default": "./dist/workflow-builder.js"
     }
   },
   "keywords": [
@@ -110,8 +114,9 @@
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "@lua/shared-sandbox": "0.0.1",
+    "@lua/shared-types": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
-    "@lua/shared-types": "0.0.1"
+    "@lua/workflow-graph": "0.0.1"
   },
   "scripts": {
     "clean": "rm -rf dist temp",

package/scripts/run-api-extractor.mjs

@@ -41,7 +41,7 @@ const configDir = path.join(packageRoot, 'api-extractor');
 const tempDtsDir = path.join(packageRoot, 'temp', 'dts');
 const distDir = path.join(packageRoot, 'dist');
 
-const rolledEntries = ['api-exports', 'voice-test'];
+const rolledEntries = ['api-exports', 'voice-test', 'workflow-builder'];
 
 const rawEntries = [
   { src: 'index.d.ts', dest: 'index.d.ts' },

package/template/.gitignore

@@ -19,3 +19,5 @@ node_modules/
 # OS files
 .DS_Store
 Thumbs.db
+# Workflows v1 (wave-5 gate): the script-form example IS tracked (WB-09, WF-527)
+!examples/workflows/*.workflow.script.js

package/template/examples/workflows/CLAUDE.md

@@ -0,0 +1,24 @@
+# Workflow examples
+
+Verbatim worked examples from workflows-spec 03 §3.2 (the spec is normative — do not restyle them).
+
+| 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` |
+
+Recipes:
+
+- Run any of these offline: `lua test workflow <name>` (steering flags in `docs/api/Workflows.md` → "Testing locally").
+- Give a predicate BOTH truth values under `--agents fake` with `--step-output <id>=<json>` — the fake stub alone
+  cannot reach the `gt(confidence, 0.6)` arm of `research-brief`.
+- 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}`).

package/template/examples/workflows/adversarial-verify.workflow.script.js

@@ -0,0 +1,48 @@
+// Example (i) — adversarial verify: spawn finders until two consecutive rounds add nothing
+// new, then have an independent verifier confirm each finding. Script form (04 §4.3);
+// push with `lua push workflow`, run offline with `lua test workflow adversarial-verify`.
+export const meta = {
+  name: 'adversarial-verify',
+  description: 'Find candidate issues from several angles, verify each independently, report the confirmed set',
+  phases: [{ title: 'Find' }, { title: 'Verify' }, { title: 'Report' }],
+  concurrency: 4,
+  sampleArgs: { subject: 'The attached design doc', angles: ['security', 'performance', 'clarity'] },
+};
+
+const found = new Map();
+let quietRounds = 0;
+for (let round = 1; round <= 5 && quietRounds < 2; round++) {
+  const batch = await parallel(
+    args.angles.map((angle) =>
+      agent(`Round ${round}: list concrete issues in ${args.subject} from the ${angle} angle. One per line.`, {
+        phase: 'Find',
+        label: `find-${angle}-${round}`,
+      })
+    )
+  );
+  // step(): a pure reduction journaled once — its closure may use anything, it never re-runs on replay.
+  const added = await step(`dedupe-${round}`, () => {
+    let fresh = 0;
+    for (const text of batch) {
+      for (const line of String(text).split('\n')) {
+        const key = line.trim().toLowerCase();
+        if (key && !found.has(key)) {
+          found.set(key, line.trim());
+          fresh++;
+        }
+      }
+    }
+    return fresh;
+  });
+  quietRounds = added === 0 ? quietRounds + 1 : 0;
+  log(`round ${round}: ${added} new finding(s)`);
+}
+
+const verdicts = await foreach(
+  [...found.values()],
+  (issue) =>
+    agent(`Independently verify: "${issue}". Answer CONFIRMED or REJECTED with one sentence.`, { phase: 'Verify' }),
+  { concurrency: 4 }
+);
+const confirmed = [...found.values()].filter((_, i) => String(verdicts[i]).toUpperCase().startsWith('CONFIRMED'));
+return { confirmed, rejected: found.size - confirmed.length, rounds: quietRounds };

package/template/examples/workflows/github-review.webhook.ts

@@ -0,0 +1,19 @@
+// Routes a PR review to the run named in the PR body (Workflows.signal).
+// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// src/webhooks/github-review.ts — routes a PR review to the run named in the PR body (§3.7 `Workflows.signal`; 06 §6.5.3 step 2b descends it into the waiting review-round child)
+import { LuaWebhook, Workflows } from 'lua-cli';
+
+export default new LuaWebhook({
+  name: 'github-pr-review',
+  description: 'GitHub pull_request_review → github.review signal',
+  async execute({ headers, body }) {
+    if (headers['x-github-event'] !== 'pull_request_review') return { ignored: true };
+    const runId = /<!-- lua-run:(wfr_[A-Za-z0-9_-]+) -->/.exec(body.pull_request?.body ?? '')?.[1];   // the marker `openPr` wrote (above); absent ⇒ not one of ours
+    if (!runId) return { ignored: true };
+    const state = body.review.state === 'approved' ? 'approved' : body.review.state === 'changes_requested' ? 'changes_requested' : 'commented';
+    const r = await Workflows.signal(runId, 'github.review',
+      { state, comments: [{ body: body.review.body ?? '' }] },                              // matches the wait's `schema`; inline review comments arrive on `pull_request_review_comment` and are folded the same way
+      { dedupeKey: `review:${body.review.id}` });                                            // GitHub redelivers: one signal per review id (06 §6.5)
+    return { runId, accepted: r.accepted, reason: r.reason };                               // `accepted:false, reason:'source_not_accepted'` would mean the wait's acceptedSources exclude 'webhook' — it does not (above)
+  },
+});

package/template/examples/workflows/linear-ready.trigger.ts

@@ -0,0 +1,21 @@
+// The Linear label trigger that starts ticket-to-pr (07 §7.2.1 TriggerStartWorkflow).
+// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// src/triggers/linear-ready.ts — the Linear label that starts a run (07 §7.2.1 `TriggerStartWorkflow`; LuaTrigger has no execute — filter + transform only)
+import { LuaTrigger } from 'lua-cli';
+
+export default new LuaTrigger({
+  name: 'linear-ready-for-agent',
+  description: 'Linear "issue labeled" webhook → start ticket-to-pr',
+  source: 'webhook',
+  filter: (ctx) => ctx.payload?.type === 'Issue' && ctx.payload?.action === 'update'
+    && (ctx.payload.data?.labels ?? []).some((l: { name: string }) => l.name === 'ready-for-agent'),   // any other label edit: the trigger's ordinary "filtered" verdict, no run
+  transform: (ctx) => {
+    const issue = ctx.payload.data;
+    return { startWorkflow: {
+      name: 'ticket-to-pr',
+      input: { ticketId: issue.identifier, title: issue.title, spec: issue.description ?? '', repo: 'https://github.com/acme/backend', baseRef: 'main' },
+      idempotencyKey: `linear:${issue.identifier}:ready-for-agent`,   // a redelivered webhook or a label toggled twice returns the SAME run (§3.7; 07 §7.2.3 step 2)
+      // no `notify`: a trigger start runs as the system principal, and `notify` addresses the creator only (07 §7.4.1 — inert here); the human-facing surface is the PR itself + the approval inbox
+    } };
+  },
+});