lua-cli 3.31.0 → 3.32.2

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.31.0
+# lua-cli v3.32.2
 
-Welcome to the comprehensive API documentation for lua-cli v3.31.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.32.2. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 

package/docs/api/LuaWorkflow.md

@@ -2,29 +2,45 @@
 
 The workflow primitive: a **durable, multi-step program** you author in TypeScript, compile with `lua compile`, and push with `lua push workflow`. The engine executes the compiled graph server-side — steps survive restarts, waits hold no compute, and approvals/signals park the run until a person or a webhook answers.
 
-> **Execution model — read this first.** *`execute` re-runs from the top after resume; execution is at-least-once — dedupe on `occurrenceId`.* `occurrenceId` is `${lineageId}:${stepId}` — the same key on retry, resume, `retry-step` and a repair run; an effect that must be unique across independent runs needs your own business key (`refund:${ticketId}`). Wrap external effects in `ctx.once(key, fn)`.
+> **Execution model — read this first.** _`execute` re-runs from the top after resume; execution is at-least-once — dedupe on `occurrenceId`._ `occurrenceId` is `${lineageId}:${stepId}` — the same key on retry, resume, `retry-step` and a repair run; an effect that must be unique across independent runs needs your own business key (`refund:${ticketId}`). Wrap external effects in `ctx.once(key, fn)`.
 
 ## Import
 
 ```typescript
-import { createStep, createWorkflow, defineWorkflow, step, stepOf, eq, gt, gte, lit, template, fromInit, fromStep, fromKnowledge, rows, env } from 'lua-cli';
+import {
+  createStep,
+  createWorkflow,
+  defineWorkflow,
+  step,
+  stepOf,
+  eq,
+  gt,
+  gte,
+  lit,
+  template,
+  fromInit,
+  fromStep,
+  fromKnowledge,
+  rows,
+  env,
+} from 'lua-cli';
 ```
 
 ## `createStep(config)`
 
 A typed code step. `inputSchema` / `outputSchema` / `resumeSchema` are zod schemas; the compiler serializes them to JSON Schema.
 
-| Field | Meaning |
-|---|---|
-| `id` | Unique step id (referenced by `then`, containers, `fromStep`) |
-| `inputSchema` / `outputSchema` | zod; outputs are validated after every attempt |
-| `timeoutSeconds` | Per-attempt wall (worker tier ≤ 600; `tier:'job'` up to 86 400) |
-| `retry` | `{ maxAttempts, backoffSeconds?, backoff?: 'fixed'\|'exponential', maxBackoffSeconds? }` — waits `backoffSeconds · 2^(attempt-1)` capped at `maxBackoffSeconds` |
-| `sideEffects` | `'external'` ⇒ never auto-retried on a platform-fault reclaim — the step **parks** instead (see [When a step parks](../workflows/recovery.md)) |
-| `onError` | `'fail'` (default) · `'continue'` · `'park'` |
-| `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?` |
+| Field                                              | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                                               | Unique step id (referenced by `then`, containers, `fromStep`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `inputSchema` / `outputSchema`                     | zod; outputs are validated after every attempt                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `timeoutSeconds`                                   | Per-attempt wall (worker tier ≤ 600; `tier:'job'` up to 86 400)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `retry`                                            | `{ maxAttempts, backoffSeconds?, backoff?: 'fixed'\|'exponential', maxBackoffSeconds? }` — waits `backoffSeconds · 2^(attempt-1)` capped at `maxBackoffSeconds`                                                                                                                                                                                                                                                                                                                                                                                 |
+| `sideEffects`                                      | `'external'` ⇒ never auto-retried on a platform-fault reclaim — the step **parks** instead (see [When a step parks](../workflows/recovery.md))                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `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()` (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.
 
@@ -38,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 |
-| `.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` |
-| `.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

@@ -67,7 +67,17 @@ Resumes a step suspended with `ctx.suspend(...)`. The loser of a resume race rec
 
 ### `Workflows.signal(runId, name, payload?, opts?)`
 
-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' }`.
+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
 
@@ -107,4 +117,5 @@ lua test workflow outreach --input @leads.json \
 ## Related
 
 - `lua workflows` — list, start, runs, status, watch, attach, cancel, resume, approve, signal, replay, logs, delete — `attach` re-attaches to a running run's event stream (the same stream your chat card re-attaches to)
+- `lua workflows goals <list|get|create|pause|resume|close>` and `lua workflows schedules <list|delete>` — the operator surface for goals (R57–R62) and schedule Jobs; `lua workflows view --json` carries `schedules` (goal-owned rows tagged `goalId`) and `goals`. See [workflows/goals.md](../workflows/goals.md) and [workflows/schedules.md](../workflows/schedules.md).
 - [LuaWorkflow](./LuaWorkflow.md) — the builder primitive

package/docs/workflows/approvals.md

@@ -2,7 +2,20 @@
 
 _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 `{ approved, payload?, edited?, timedOut?, escalations? }` — branchable data, never an exception.
+`.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
+
+```typescript
+{
+  approved: boolean;
+  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
+  evidence?: string[];                             // decision artefact ids frozen with the decision
+}
+```
+
+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.
 
 ## Approver specs
 

package/docs/workflows/connections-in-coding-turns.md

@@ -4,6 +4,7 @@ _Source of truth: workflows-spec 05 §5.17.6 / 11 §11.5. This page is the devel
 
 `toolScope.connectionIds` on a Job-tier agent step mounts MCP connections into the coding turn **through a local proxy**: the model calls `tools/list` / `tools/call`; the proxy holds the token — the model never sees it.
 
+- `requiredConnections` (and `workspace.credentialsRef`) accept a declared `connections[].key` instead of an id — declare a key; it resolves against the owner agent's connections on any agent at run time (see [Git credentials](./git-credentials.md)).
 - A tool that needs approval is **refused inside the turn** (`mcp_call_denied`) — hand it to a worker-tier step where the approval card can park the run.
 - Calls are capped per segment; the cap and usage appear in the step detail.
 - Offline: connections are **not mounted** (no proxy, no token mint) — `--mcp <connectionId>=@fixture.json` stubs `tools/list` / `tools/call` from a `{ tools:[…], calls:{ [tool]: result } }` fixture; an unstubbed call returns the production `mcp_call_denied{reason:'not_in_scope'}` shape.

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/git-credentials.md

@@ -6,6 +6,27 @@ _Source of truth: workflows-spec 11 §11.5.6 / 05 §5.17.3. This page is the dev
 
 > **Never put a PAT in `env`.** Rotation or revocation of the underlying connection makes the next mint fail: the step fails `credentials_revoked{git_token_mint_failed}` and — with `onError:'park'` — enters the park/`retry-step` loop, so a re-grant resumes the run without losing work.
 
+## Declare a key; it resolves on any agent
+
+Don't freeze a connection id in source. Declare the connection once on `createWorkflow` and reference it by key:
+
+```ts
+createWorkflow({
+  name: 'ticket-pilot',
+  connections: [{ key: 'github', integrationType: 'github', required: true }],
+  workspace: { kind: 'git', repo: 'acme/app', credentialsRef: 'github' },
+  // …
+});
+```
+
+At run time the engine resolves `github` against the **owner agent's own connections** — an agent-scoped GitHub connection first, then an org-scoped one; a user's personal connection is never picked. The same definition therefore runs unchanged on a template install (where the install binding still wins), on a hand-built agent and on a duplicated agent — no "two builds of one workflow", no compile-time env var. `requiredConnections` on a step accepts declared keys the same way.
+
+- The resolution is recorded once per run as `connection.resolved {key, connectionId, scope}`; `lua workflows status <runId> --steps --json` shows it under `connections.resolved`, beside `connections.declared` (the keys the version declares) — a declared key missing from `resolved` never resolved on that run.
+- A step that fails before the key resolves carries the reason on `error` (`message`, `providerStatus`, `providerMessage` and the engine's `detail` bag — e.g. `detail.connectionId` names the ref the git mint was asked for).
+- Two connections of the same type on the agent are ambiguous — label the one to use with the key (its display name) or the step fails `credentials_unresolved` listing the candidates.
+- No connection of that type at all ⇒ `credentials_unresolved` (non-retryable, no turn billed) and a notice naming the key and the integration to connect; with `onError:'park'` the run resumes through `retry-step` once it is connected. A revoked or unhealthy connection still fails `credentials_revoked` exactly as before.
+- A literal connection id keeps working exactly as it does today. A key that is not declared — with or without a `connections` block — fails `lua compile` and `lua push` with `connection-key-undeclared`, which names the declaration to add.
+
 - `jobTools:['gh']` is what mints `GH_TOKEN` for a code step (`pull_requests:write` + `contents:write` + `issues:read`, repo-scoped). Merge is a contents write — human-only-merge orgs keep `contents:write` off the App.
-- Templates never hardcode a connection id: they use `connections[].key`, resolved at install.
+- Templates declare `connections[].key` too: an install binds the key to the installer's connection; a definition installed without a binding falls back to the run-time resolution above.
 - Offline, `credentialsRef` is printed and **not** resolved (no token mint) — `--credentials-ref-ok` suppresses the notice; the local driver uses your own git credentials.

package/docs/workflows/goals.md

@@ -0,0 +1,46 @@
+# Goals
+
+_Source of truth: workflows-spec 05 §5.20 / 09 §9.5.9. This page is the developer summary; the spec is normative._
+
+A goal runs a workflow again and again until a judge says it is done: `objective` is what "done" means, `judge` decides it after every iteration (a deterministic `predicate` over the run's `{ output, state, steps.<stepId>, iteration, runStatus }`, or a judge agent answering a JsonSchema with a boolean `done`), `cadence` is when the next iteration starts (a schedule Job the goal owns; none ⇒ the next iteration starts immediately), and `maxRuns` caps the loop. A goal is `active`, `paused` (by you, or by the platform on `budget` / `max_runs` / `strikes`), `done` (the judge said so) or `closed` (by you — final).
+
+Goals are created from chat (`setWorkflowGoal`), from the SDK (`Workflows.setGoal`) and from the CLI; the CLI is the audit surface for all of them.
+
+## Verbs
+
+```bash
+lua workflows goals list [<workflow>] [-i <workflow>] [--status active|paused|done|closed] [--limit n] [--cursor c] [--json]
+lua workflows goals get <goalId> [--json]                       # the goal card + its iteration runs with verdicts
+lua workflows goals pause <goalId>                              # R60 — the cadence stays with the goal
+lua workflows goals resume <goalId>                             # R61 — no backfill of missed fires
+lua workflows goals close <goalId> [--note <text>]              # R62 — final
+lua workflows goals create <workflow> --objective <text> --max-runs <n> [-v <semver|latest|versionId>] \
+    (--judge-predicate '<path> <op> [value]' | --judge-agent <agentId|'$self'> [--judge-role <json|@file>] --schema <json|@file>) \
+    [--cadence <cron|json|@file> …] [--timezone <tz>] [--input <json|@file>] \
+    [--budget-credits <n>] [--max-total-credits <n>] [--idempotency-key <key>]
+```
+
+`lua workflows view <workflow>` prints the workflow's goals (and its schedules); `--json` carries them under `goals` and `schedules`.
+
+### `goals create`
+
+- `--judge-predicate` is the deterministic judge: `output.signups gte 50`, `output.done truthy`, `state.phase eq "shipped"`. The value is parsed as JSON when it parses (`50` → number, `true` → boolean) and kept as a string otherwise; ops are `exists · truthy · eq · neq · gt · gte · lt · lte`. A JSON object (`{"path":…,"op":…,"value":…}`) or `@file` works too.
+- `--judge-agent` runs a judge turn instead: another agent by id, or `'$self'` — the workflow's own agent; quote it, an unquoted `$self` is expanded by the shell to an empty string (`self` is accepted as the same thing) — then `--judge-role` with the D25 `{ name, instructions, tools }` is required. `--schema` is required for an agent judge and must declare a boolean `done` at the root; the judge answers it and `done` ends the goal.
+- `--cadence` is repeatable (≤ 5): a bare cron expression (`'0 9 * * 1'`, `--timezone Europe/London` applies to it) or a JSON slot / array for `interval` (`{"type":"interval","seconds":3600}`) and `once` entries — a timezone for those goes inside the entry (`--timezone` beside JSON-only cadences is an error). `-v` pins the iteration version (a semver, `latest` or a version id — resolved like `start -v`); without it every iteration runs the active version. Without a cadence the goal runs `immediate`: each iteration starts as soon as the previous one is judged.
+- `--input` seeds every iteration's run input; `--budget-credits` is the per-run budget; `--max-total-credits` is the lineage-wide gate that pauses the goal (`budget`) when the sum of its runs reaches it.
+
+Example:
+
+```bash
+lua workflows goals create -i outreach \
+  --objective "Reach 50 trial signups from the March cohort" \
+  --judge-predicate 'output.signups gte 50' \
+  --cadence '0 9 * * 1' --timezone Europe/London \
+  --max-runs 12 --input '{"segment":"trial-march"}'
+```
+
+## 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`.
+
+`lua workflows schedules delete` on a goal's cadence Job is refused (`goal_schedule`) — use `goals pause` / `goals close`; 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/recovery.md

@@ -5,7 +5,9 @@ _Source of truth: workflows-spec 01 §1.6-r1 / 06 §6.3.5. This page is the deve
 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.
+2. **`onError:'park'`.** A final (retries exhausted, or non-retryable) failure parks instead of failing the run — for steps where an operator should decide. The row carries `park: { reason: 'onerror_park' }`, the run is `suspended` with `gate.kind: 'exception'`, and the events show `step.parked` + `run.gated`; nothing downstream is skipped. A failure that happened **before dispatch** (`binding_unresolved`, `input_schema_invalid`, `credentials_unresolved`, `credentials_revoked`, `TOOL_REF_UNRESOLVED`, `BUNDLE_UNRESOLVED`) parks the same way — but a plain `retry-step` re-renders the same input against the same definition and connections and parks again unless one of those was fixed in between; the retry response carries `detail.hint` saying so, and `resolve-step` is the way past it.
+
+If a **sibling** step fails under `onError:'fail'` while the run is parked, the run keeps the park but is marked `failing`: after `retry-step` the parked step still re-runs, and the run then terminalizes `failed` (never `completed`) once nothing is in flight.
 
 ## The three verbs
 
@@ -15,13 +17,15 @@ A parked step waits for exactly one of:
 - **`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"`.
 
+`onError:'continue'` never parks: the step is `failed` on the ledger, the run goes on, and every successor sees the step's **continued-failure value** `{ __lua_workflow:'continued_failure', failed:true, error:{code,message}, text:'' }` under `stepResults.<id>` (the default input, `${stepResults.<id>.text}` → `''`, `getStepResult(id)`, a `conditional` on `stepResults.<id>.failed`, and the parallel / foreach join entry). A `retry-step` on such a row while the run is still running re-arms it, but a successor that already consumed the value is not re-run.
+
 `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}`).
+> **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
 

package/docs/workflows/replay-local.md

@@ -8,10 +8,10 @@ _Source of truth: workflows-spec 03 §3.10, 04 §4.3.5, 05 §5.7.1, 12 §12.9.11
 
 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`. |
+| 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.
 
@@ -19,15 +19,15 @@ Why A: the wrapper drags the whole runtime plane (`@lua/sandbox-runtime` → `@l
 
 - 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.
+- 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)
 
-| 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 |
+| 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
 

package/docs/workflows/schedules.md

@@ -9,3 +9,18 @@ _Source of truth: workflows-spec 07 §7.1. This page is the developer summary; t
 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`.
+
+## From the CLI
+
+Schedules are `Job{kind:'workflow'}` rows on the agent; the CLI reads them through `GET /workflows/:agentId/schedules` and removes one through R28.
+
+```bash
+lua workflows schedules list -i outreach          # this workflow's schedule Jobs (omit -i for every workflow of the agent)
+lua workflows schedules list --json               # { success, data: { items: [{ jobId, workflowId, trigger, paused, nextRunAt, lastFiredAt?, consecutiveFailures, autoDisabled?, goalId? }] } }
+lua workflows schedules delete <jobId> [--yes]    # R28 — asks first unless --yes
+lua workflows view outreach                       # the "Schedules:" line + table; --json carries the same rows under `schedules`
+```
+
+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).

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' }),
+  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,17 +33,21 @@ 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:
 
-| 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.
 

package/docs/workflows/testing-offline.md

@@ -4,34 +4,39 @@ _Source of truth: workflows-spec 03 §3.9 (WF-204/WF-225/WF-332). This page is t
 
 `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.
 
+**No API call.** The verb compiles first, but that compile skips the server ↔ YAML sync every other `lua compile` performs — nothing is created on the agent and no run exists on the server. Only `lua push workflow` persists a definition; `lua workflows start` creates a run. The exceptions are the flags that ask for the platform: `--from-run <runId>` (reads the seed run) and `--agents live` (calls the dev API for agent steps).
+
 ## 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 (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>`                                     | 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
 
+- **`sleep(ms)`** advances the virtual clock by exactly `ms` **milliseconds** — the SDK's unit and the engine's (`.sleep(3000)` is 3 s, printed as `<id> · sleep 3000 ms (3 s) (virtual clock)`); `sleepUntil` jumps to the resolved instant. `--real-time` waits the same `ms`.
 - **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.
 - **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