lua-cli 3.31.0 → 3.32.1

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.31.0
+# lua-cli v3.32.1
 
-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.1. 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()`, `log()`, `env`, `artefacts`, `occurrenceId`, `workspace?`                                                                                                                                                                                                                                                                                                                                                        |
 
 `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 }`                                                                                                                                                       |
+| `.workflow(id, ref, input?, { workspace? })`                                                            | Child run the parent waits for                                                                                                                                                                                                                                                       |
 
 ### Typed predicates
 

package/docs/api/Workflows.md

@@ -67,7 +67,7 @@ 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 members
 
@@ -107,4 +107,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/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/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/testing-offline.md

@@ -4,30 +4,33 @@ _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>`                                     | 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
 
+- **`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.

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

@@ -8,6 +8,8 @@ _Source of truth: workflows-spec 05 §5.17 (D19-r1/r2). This page is the develop
 
 `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 }`.
 
+`credentialsRef` is a connection id **or a key you declare under `connections: [{ key, integrationType }]`** — declare a key; it resolves against the owner agent's own connections on any agent at run time (see [Git credentials](./git-credentials.md)), so the definition never freezes a production id.
+
 **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.31.0",
+  "version": "3.32.1",
   "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",
@@ -114,9 +114,9 @@
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "@lua/shared-sandbox": "0.0.1",
-    "@lua/shared-types": "0.0.1",
+    "@lua/workflow-graph": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
-    "@lua/workflow-graph": "0.0.1"
+    "@lua/shared-types": "0.0.1"
   },
   "scripts": {
     "clean": "rm -rf dist temp",

package/template/examples/workflows/CLAUDE.md

@@ -1,24 +1,27 @@
 # Workflow examples
 
-Verbatim worked examples from workflows-spec 03 §3.2 (the spec is normative — do not restyle them).
+Worked examples from workflows-spec 03 §3.2 (the spec is normative — do not restyle them). A file whose header carries a
+`LUA-635:` note departs from the spec's listing on purpose: the compiler is what ships, and the listing was wrong against
+it (a `.then(createStep)` placement used as a string-ref target; a `template(…)` approval title). The note says what
+changed and why; `tests/__tests__/compile.workflow.examples.test.ts` compiles every file here, so a drift cannot return.
 
-| File | Shows |
-|---|---|
-| `research-brief.ts` | (a) sequential + parallel research, typed predicates (`stepOf`/`gt`/`lit`), switch + otherwise |
-| `outreach.ts` | (b) `foreach` + editable approval + an exactly-once send (`ctx.once`), cron schedule, `concurrencyPolicy` |
-| `provision-tenant.ts` | (c) nested workflow + `sleep` + `waitForSignal` |
-| `reviewed-brief.ts` | (d) `specialistStep` — an ephemeral reviewer role on the owning agent (D25) |
-| `refund-approval.ts` | (e) maker-checker + four-eyes + business-hours escalation chain + a recoverable external step (`onError:'park'`) |
+| 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` |
+| `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
+- 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/pr-review-round.ts

@@ -1,38 +1,75 @@
 // One review iteration; runs as a child of ticket-to-pr with the SAME workspace.
-// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// From workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative). LUA-635: a switch arm is ONE step and a
+// string arm names an agentStep / specialistStep / toolStep / map / workflow declaration (03 §3.2.0) — the listing's
+// `otherwise: 'done'` over a later `.then(createStep({ id: 'done' }))` was a goto the placement rule never had.
 // src/workflows/pr-review-round.ts — one review iteration; runs as a child of ticket-to-pr with the SAME workspace
 import { z } from 'zod';
 import { createStep, createWorkflow, step, eq, lit, template } from 'lua-cli';
 
 const pushFix = createStep({
   id: 'pushFix',
-  inputSchema: z.any(), outputSchema: z.object({ headSha: z.string() }),
-  tier: 'job', workspace: { mount: 'rw' }, timeoutSeconds: 600,
-  async execute({ workspace }) {                                  // git runs through the credential proxy — no token in this container (05 §5.17.3)
-    const sha = (await $`git -C ${workspace!.path} rev-parse HEAD`).stdout.trim();   // `$` = the Job image's shell helper (`@lua/coding-harness/shell`); a plain child_process spawn works too — the Job site has no REQUIRE_BLOCKLIST for `child_process`
+  inputSchema: z.any(),
+  outputSchema: z.object({ headSha: z.string() }),
+  tier: 'job',
+  workspace: { mount: 'rw' },
+  timeoutSeconds: 600,
+  async execute({ workspace }) {
+    // git runs through the credential proxy — no token in this container (05 §5.17.3)
+    const sha = (await $`git -C ${workspace!.path} rev-parse HEAD`).stdout.trim(); // `$` = the Job image's shell helper (`@lua/coding-harness/shell`); a plain child_process spawn works too — the Job site has no REQUIRE_BLOCKLIST for `child_process`
     return { headSha: sha };
   },
 });
 
+const changesRequested = eq(step('review').path('payload.state'), lit('changes_requested'));
+
 export const prReviewRound = createWorkflow({
   name: 'pr-review-round',
   inputSchema: z.object({ prNumber: z.number(), repo: z.string() }),
-  outputSchema: z.object({ state: z.enum(['approved', 'changes_requested', 'timed_out']), round: z.number().optional() }),
+  outputSchema: z.object({
+    state: z.enum(['approved', 'changes_requested', 'timed_out']),
+    round: z.number().optional(),
+  }),
 })
-  .waitForSignal('review', { signal: 'github.review', timeoutHours: 168,           // delivered by the GitHub webhook (§3.7) — to the PARENT run; the engine descends it into this child (06 §6.5.3 step 2b)
-    schema: z.object({ state: z.enum(['approved', 'changes_requested', 'commented']), comments: z.array(z.object({ path: z.string().optional(), body: z.string() })) }),
-    acceptedSources: ['webhook'], onTimeout: 'continue' })
-  .switch([[eq(step('review').path('payload.state'), lit('changes_requested')), 'addressReview']], 'done')
-  .agentStep('addressReview', {                                                   // a CODING TURN: Claude Code headless with git/gh/shell/edit on the mounted checkout (05 §5.17.6)
-    agentId: 'swe-implementer', tier: 'job', workspace: { mount: 'rw' }, timeoutSeconds: 7200, jobResources: 'medium',
-    prompt: template('Address every review comment in ${stepResults.review.payload.comments} on the current branch. Run the relevant tests. Commit with a message that references the comment you addressed. Do not force-push.'),
-    toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] },   // no `gh`: the push + PR update is the next code step
+  .waitForSignal('review', {
+    signal: 'github.review',
+    timeoutHours: 168, // delivered by the GitHub webhook (§3.7) — to the PARENT run; the engine descends it into this child (06 §6.5.3 step 2b)
+    schema: z.object({
+      state: z.enum(['approved', 'changes_requested', 'commented']),
+      comments: z.array(z.object({ path: z.string().optional(), body: z.string() })),
+    }),
+    acceptedSources: ['webhook'],
+    onTimeout: 'continue',
+  })
+  .switch([[changesRequested, 'addressReview']]) // no `otherwise`: approved / commented / timed out falls through to `done`
+  .agentStep('addressReview', {
+    // a CODING TURN: Claude Code headless with git/gh/shell/edit on the mounted checkout (05 §5.17.6)
+    agentId: 'swe-implementer',
+    tier: 'job',
+    workspace: { mount: 'rw' },
+    timeoutSeconds: 7200,
+    jobResources: 'medium',
+    prompt: template(
+      'Address every review comment in ${stepResults.review.payload.comments} on the current branch. Run the relevant tests. Commit with a message that references the comment you addressed. Do not force-push.'
+    ),
+    toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] }, // no `gh`: the push + PR update is the next code step
     outputSchema: z.object({ summary: z.string() }),
   })
-  .then(pushFix)
-  .then(createStep({ id: 'done', inputSchema: z.any(), outputSchema: z.object({ state: z.enum(['approved', 'changes_requested', 'timed_out']) }),
-    async execute({ getStepResult }) {
-      const r = getStepResult<{ received: boolean; timedOut?: boolean; payload?: { state: string } }>('review');
-      return { state: r?.received ? (r.payload!.state === 'changes_requested' ? 'changes_requested' : 'approved') : 'timed_out' };
-    } }))
+  .switch([[changesRequested, pushFix]]) // the fix path's second step — same predicate, an inline createStep as the arm
+  .then(
+    createStep({
+      id: 'done',
+      inputSchema: z.any(),
+      outputSchema: z.object({ state: z.enum(['approved', 'changes_requested', 'timed_out']) }),
+      async execute({ getStepResult }) {
+        const r = getStepResult<{ received: boolean; timedOut?: boolean; payload?: { state: string } }>('review');
+        return {
+          state: r?.received
+            ? r.payload!.state === 'changes_requested'
+              ? 'changes_requested'
+              : 'approved'
+            : 'timed_out',
+        };
+      },
+    })
+  )
   .commit();