lua-cli 3.31.0 → 3.32.2

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

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

package/package.json

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

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,79 @@
 // 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, log }) {
+    // `ctx.$` (LUA-682) runs an allow-listed binary in the checkout — argv only, no shell — with git's remote on the
+    // credential proxy: no token in this container (05 §5.17.3). `child_process` is NOT available to a code step
+    // (`lua compile` refuses it: node-capability-unavailable); a coding turn's `shell` tool is the other way to run
+    // commands. The harness pushes the branch at the checkpoint / terminal; this step reports what it pushed.
+    const sha = (await $!.strict`git rev-parse HEAD`).stdout.trim();
+    log(`pushed ${sha} on ${workspace!.branch ?? 'the run branch'}`);
     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();

package/template/examples/workflows/provision-tenant.ts

@@ -1,18 +1,35 @@
 // Nested workflow + sleep + signal.
-// Verbatim from workflows-spec 03 §3.2 (c) (WF-215 / WF-223 — the spec is normative).
+// From workflows-spec 03 §3.2 (c) (WF-215 / WF-223 — the spec is normative). LUA-635: the switch arms are the
+// createStep objects themselves — a STRING arm names an agentStep / specialistStep / toolStep / map / workflow
+// declaration elsewhere in the chain (03 §3.2.0); `.then(createStep({ id }))` places a step, it never declares one.
 import { z } from 'zod';
 import { createStep, createWorkflow, step, eq, lit, fromInit } from 'lua-cli';
 
+const finalize = createStep({
+  id: 'finalize',
+  inputSchema: z.any(),
+  outputSchema: z.object({ ready: z.boolean() }),
+  execute: async () => ({ ready: true }),
+});
+const rollback = createStep({
+  id: 'rollback',
+  inputSchema: z.any(),
+  outputSchema: z.object({ ready: z.boolean() }),
+  execute: async () => ({ ready: false }),
+});
+
 export const provision = createWorkflow({
   name: 'provision-tenant',
   inputSchema: z.object({ tenantId: z.string() }),
   outputSchema: z.object({ ready: z.boolean() }),
 })
-  .workflow('createResources', 'research-brief', { topic: fromInit('tenantId') })  // nested by name (same agent) or LuaWorkflow ref
-  .sleep(5 * 60 * 1000)                                                             // engine-side; holds no compute
-  .waitForSignal('vendorReady', { signal: 'vendor.ready', schema: z.object({ ok: z.boolean() }),
-    timeoutHours: 72, acceptedSources: ['webhook', 'api'] })
-  .switch([[eq(step('vendorReady').path('ok'), lit(true)), 'finalize']], 'rollback')
-  .then(createStep({ id: 'finalize', inputSchema: z.any(), outputSchema: z.object({ ready: z.boolean() }), execute: async () => ({ ready: true }) }))
-  .then(createStep({ id: 'rollback', inputSchema: z.any(), outputSchema: z.object({ ready: z.boolean() }), execute: async () => ({ ready: false }) }))
+  .workflow('createResources', 'research-brief', { topic: fromInit('tenantId') }) // nested by name (same agent) or LuaWorkflow ref
+  .sleep(5 * 60 * 1000) // engine-side; holds no compute
+  .waitForSignal('vendorReady', {
+    signal: 'vendor.ready',
+    schema: z.object({ ok: z.boolean() }),
+    timeoutHours: 72,
+    acceptedSources: ['webhook', 'api'],
+  })
+  .switch([[eq(step('vendorReady').path('ok'), lit(true)), finalize]], rollback) // inline code steps; the last entry is a conditional, so the taken arm's output is the run output
   .commit();

package/template/examples/workflows/refund-approval.ts

@@ -5,19 +5,26 @@ import { createStep, createWorkflow, template, Integrations } from 'lua-cli';
 
 const postRefund = createStep({
   id: 'postRefund',
-  inputSchema: z.object({ approved: z.boolean(), editedPayload: z.object({ ticketId: z.string(), amount: z.number() }).optional(),
-                          input: z.object({ ticketId: z.string(), amount: z.number() }) }),   // the approval node's output shape (04 §4.2.3)
+  inputSchema: z.object({
+    approved: z.boolean(),
+    editedPayload: z.object({ ticketId: z.string(), amount: z.number() }).optional(),
+    input: z.object({ ticketId: z.string(), amount: z.number() }),
+  }), // the approval node's output shape (04 §4.2.3)
   outputSchema: z.object({ refundId: z.string().nullable() }),
-  sideEffects: 'external',                                  // a platform-fault reclaim PARKS this step (never auto-retried); the run gates `exception` (§06 §6.3.5)
-  onError: 'park',                                          // a final customer-fault failure parks too — the operator retries / skips / supplies the refundId / fails it
-  requiredConnections: ['stripe'],                          // unmountable ⇒ failed{credentials_revoked, reason:'required_connection_unmountable'} → parked via onError:'park' (§11 §11.5.5)
+  sideEffects: 'external', // a platform-fault reclaim PARKS this step (never auto-retried); the run gates `exception` (§06 §6.3.5)
+  onError: 'park', // a final customer-fault failure parks too — the operator retries / skips / supplies the refundId / fails it
+  requiredConnections: ['stripe'], // the declared key below — resolved on the owner agent at run time (LUA-623); no connection of that type ⇒ failed{credentials_unresolved}, unmountable ⇒ failed{credentials_revoked, reason:'required_connection_unmountable'} → parked via onError:'park' (§11 §11.5.5)
   async execute({ inputData, occurrenceId }) {
     if (!inputData.approved) return { refundId: null };
     const r = inputData.editedPayload ?? inputData.input;
     // `occurrenceId` is `${lineageId}:${stepId}`: the same key on retry-step, on resume and on a REPAIR RUN — the refund collapses to one (§06 §6.3.3 (e)).
     // A key that must hold across INDEPENDENT runs (two runs for the same ticket) is the caller's: `refund:${r.ticketId}` (§06 §6.3.3 (f)).
-    const res = await Integrations.passthrough('stripe', { method: 'POST', path: '/v1/refunds',
-      headers: { 'Idempotency-Key': `refund:${r.ticketId}` }, body: { charge: r.ticketId, amount: r.amount } });
+    const res = await Integrations.passthrough('stripe', {
+      method: 'POST',
+      path: '/v1/refunds',
+      headers: { 'Idempotency-Key': `refund:${r.ticketId}` },
+      body: { charge: r.ticketId, amount: r.amount },
+    });
     return { refundId: res.body.id };
   },
 });
@@ -26,18 +33,24 @@ export const refund = createWorkflow({
   name: 'refund-approval',
   inputSchema: z.object({ ticketId: z.string(), amount: z.number(), requesterId: z.string() }),
   outputSchema: z.object({ refundId: z.string().nullable() }),
-  budget: { maxDurationSeconds: 14 * 24 * 3600 },          // long enough for two business-hours escalation hops (the compiler warns `deadline-clamped` otherwise)
+  budget: { maxDurationSeconds: 14 * 24 * 3600 }, // long enough for two business-hours escalation hops (the compiler warns `deadline-clamped` otherwise)
+  connections: [{ key: 'stripe', integrationType: 'stripe', required: true }], // the Stripe connection the refund step acts through, declared once by key — never a frozen connection id (LUA-623)
 })
   .approval('approveRefund', {
-    title: 'Refund request', details: template('Refund ${initData.amount} for ticket ${initData.ticketId}'),
-    approver: { role: 'support-lead' },                      // org role, template-portable; `{users:[…]}` / `{group:'finance'}` are org data (§13 §13.3.3)
-    excludeInitiator: true,                                  // the requester who started the run can never approve it (maker-checker)
-    fourEyes: { edit: { role: 'support-lead' }, approve: { role: 'finance-controller' } },   // whoever edits the amount cannot be the one who approves it
-    timeoutHours: 8, businessHours: { tz: 'Europe/London', calendar: 'mon-fri' },            // 8 business hours, then…
-    onTimeout: [{ escalateTo: { role: 'finance-controller' }, timeoutHours: 16 },              // …hop 1: finance, 16 business hours, then…
-                { escalateTo: 'org-admins', timeoutHours: 24 },                                // …hop 2: org admins, then…
-                'deny'],                                                                        // …the node completes {approved:false, timedOut:true, escalations:2} — branchable data (§06 §6.4.11)
-    editable: true, editablePaths: ['amount'],               // the approver may lower the amount; the approve call echoes the fingerprint of the revision it saw (§06 §6.4.9)
+    title: 'Refund request',
+    details: template('Refund ${initData.amount} for ticket ${initData.ticketId}'),
+    approver: { role: 'support-lead' }, // org role, template-portable; `{users:[…]}` / `{group:'finance'}` are org data (§13 §13.3.3)
+    excludeInitiator: true, // the requester who started the run can never approve it (maker-checker)
+    fourEyes: { edit: { role: 'support-lead' }, approve: { role: 'finance-controller' } }, // whoever edits the amount cannot be the one who approves it
+    timeoutHours: 8,
+    businessHours: { tz: 'Europe/London', calendar: 'mon-fri' }, // 8 business hours, then…
+    onTimeout: [
+      { escalateTo: { role: 'finance-controller' }, timeoutHours: 16 }, // …hop 1: finance, 16 business hours, then…
+      { escalateTo: 'org-admins', timeoutHours: 24 }, // …hop 2: org admins, then…
+      'deny',
+    ], // …the node completes {approved:false, timedOut:true, escalations:2} — branchable data (§06 §6.4.11)
+    editable: true,
+    editablePaths: ['amount'], // the approver may lower the amount; the approve call echoes the fingerprint of the revision it saw (§06 §6.4.9)
     editedPayloadSchema: z.object({ ticketId: z.string(), amount: z.number().positive().max(500) }),
   })
   .then(postRefund)

package/template/examples/workflows/support-triage.ts

@@ -1,44 +1,81 @@
 // Support triage from a customer channel — knowledge grounding, toolScope, dataset ref, ctx.artefacts.
-// Verbatim from workflows-spec 03 §3.2 (g) (WF-215 / WF-223 — the spec is normative).
-import { createWorkflow, createStep, fromInit, fromKnowledge, rows, template, stepOf, gt, lit } from 'lua-cli';
+// From workflows-spec 03 §3.2 (g) (WF-215 / WF-223 — the spec is normative). LUA-635: the listing's `.conditional([{ when, branch }])`
+// is not in the builder (03 §3.1 has `switch` / `branch` over `[predicate, StepRef]` arms) and it named an approval as an arm, which
+// v1 forbids (approvals are top-level only) — the gate is a `switch` whose confident arm is (e)'s `refund-approval` as a child run.
+// (The listing's `template(…)` approval title was the other drift: the grammar is `title: string`, bindings ride `details`.)
+import {
+  createWorkflow,
+  createStep,
+  fromInit,
+  fromStep,
+  fromKnowledge,
+  rows,
+  template,
+  stepOf,
+  gt,
+  lit,
+} from 'lua-cli';
 import { z } from 'zod';
 
-const pullHistory = createStep({                                       // array-typed output ⇒ oversize (> 8 MB) becomes a `{__datasetRef}` (NDJSON on CDN), never OUTPUT_TOO_LARGE
-  id: 'pullHistory', inputSchema: z.object({ customerId: z.string() }),
+const pullHistory = createStep({
+  // array-typed output ⇒ oversize (> 8 MB) becomes a `{__datasetRef}` (NDJSON on CDN), never OUTPUT_TOO_LARGE
+  id: 'pullHistory',
+  inputSchema: z.object({ customerId: z.string() }),
   outputSchema: z.object({ orders: z.array(z.object({ id: z.string(), total: z.number(), status: z.string() })) }),
   execute: async (ctx) => {
     const orders = await Orders.list({ customerId: ctx.inputData.customerId, limit: 50_000 });
     const csv = ['id,total,status', ...orders.map((o) => `${o.id},${o.total},${o.status}`)].join('\n');
-    const { artefactId } = await ctx.artefacts.put('orders.csv', csv, {                    // P1-8: journaled in script form; ≤ 50 per step
-      contentType: 'text/csv', kind: 'dataset', datasetSchema: { type: 'object', properties: { id: { type: 'string' }, total: { type: 'number' }, status: { type: 'string' } } } });
+    const { artefactId } = await ctx.artefacts.put('orders.csv', csv, {
+      // P1-8: journaled in script form; ≤ 50 per step
+      contentType: 'text/csv',
+      kind: 'dataset',
+      datasetSchema: {
+        type: 'object',
+        properties: { id: { type: 'string' }, total: { type: 'number' }, status: { type: 'string' } },
+      },
+    });
     ctx.log(`orders.csv → ${artefactId}`);
     return { orders };
   },
 });
 
-const classifyOut = z.object({ intent: z.enum(['refund', 'status', 'other']), confidence: z.number(), orderId: z.string().optional() });
+const classifyOut = z.object({
+  intent: z.enum(['refund', 'status', 'other']),
+  confidence: z.number(),
+  orderId: z.string().optional(),
+  amount: z.number().optional(),
+}); // `amount`: the order total a confident refund carries into (e)
 
 export default createWorkflow({
-  name: 'support-triage', inputSchema: z.object({ ticketId: z.string(), customerId: z.string(), message: z.string() }),
+  name: 'support-triage',
+  inputSchema: z.object({ ticketId: z.string(), customerId: z.string(), message: z.string() }),
 })
   .then(pullHistory)
-  .map({
-    refund: fromKnowledge({ source: 'org-docs', query: 'refund policy', maxChars: 4000, topK: 3 }),   // rendered at S2 with a provenance header per chunk
-    recent: rows('pullHistory', 'orders', { offset: 0, limit: 20 }),                                  // paged rows; the bare ref would be the {__datasetRef} object
-  }, { id: 'classifyInputs' })
+  .map(
+    {
+      refund: fromKnowledge({ source: 'org-docs', query: 'refund policy', maxChars: 4000, topK: 3 }), // rendered at S2 with a provenance header per chunk
+      recent: rows('pullHistory', 'orders', { offset: 0, limit: 20 }), // paged rows; the bare ref would be the {__datasetRef} object
+    },
+    { id: 'classifyInputs' }
+  )
   .agentStep('classify', {
     agentId: 'support-agent',
     // `${initData.message}` is customer-channel content and `refund` is a {knowledge} binding: this step is EXTERNAL-CONTENT — `toolScope` is mandatory.
-    prompt: template('Ticket ${initData.ticketId}: ${initData.message}\n\nRefund policy:\n${stepResults.classifyInputs.refund}\n\nRecent orders (first page):\n${stepResults.classifyInputs.recent}'),
-    toolScope: {},                                                          // `{}` = no tools; `defaultToolScopeMode:'deny'` would imply this when absent
+    prompt: template(
+      'Ticket ${initData.ticketId}: ${initData.message}\n\nRefund policy:\n${stepResults.classifyInputs.refund}\n\nRecent orders (first page):\n${stepResults.classifyInputs.recent}'
+    ),
+    toolScope: {}, // `{}` = no tools; `defaultToolScopeMode:'deny'` would imply this when absent
     outputSchema: classifyOut,
   })
-  .approval('refundGate', { title: template('Refund ${stepResults.classify.orderId}?'), approver: 'org-admins',   // NOT 'creator': `approver-is-run-principal` on a customer-channel workflow
-    details: template('${stepResults.classify.intent} @ ${stepResults.classify.confidence}'), timeoutHours: 24,
-    onTimeout: [{ escalateTo: 'org-admins', timeoutHours: 24 }, 'deny'] })                              // approvers re-resolved at suspend AND decision (§06 §6.11); the card previews `orders.csv` (name/size/rowCount + an R32 link)
-  .conditional([
-    { when: gt(stepOf<typeof classifyOut>('classify').path('confidence'), lit(0.8)), branch: 'refundGate' },
-    { when: lit(true), branch: 'handoff' },
-  ])
-  .agentStep('handoff', { agentId: 'support-agent', prompt: template('Summarise ${initData.message} for a human agent.'), toolScope: {} })
+  .switch([[gt(stepOf<typeof classifyOut>('classify').path('confidence'), lit(0.8)), 'refundGate']], 'handoff') // a confident refund goes to the gate, anything else to a human. An approval is TOP-LEVEL only (03 §3.1), so the gated one is a child run whose approval sits at its own top level — the same shape as a wait inside a loop (03 §3.2 (f))
+  .workflow('refundGate', 'refund-approval', {
+    ticketId: fromInit('ticketId'),
+    amount: fromStep('classify', 'amount'),
+    requesterId: fromInit('customerId'),
+  }) // (e)'s maker-checker run, nested by name on the same agent; declared here, placed inside the switch arm by the string ref above. Its approver is a role, NOT 'creator': `approver-is-run-principal` on a customer-channel workflow
+  .agentStep('handoff', {
+    agentId: 'support-agent',
+    prompt: template('Summarise ${initData.message} for a human agent.'),
+    toolScope: {},
+  }) // the switch's `otherwise`
   .commit();