lua-cli 3.32.1 → 3.32.3

package/dist/workflow-builder.d.ts

@@ -12,7 +12,9 @@ import { PathOrLiteral } from '@lua/workflow-graph';
 import { SerializedWorkflowGraph } from '@lua/workflow-graph';
 import { TemplateBinding } from '@lua/workflow-graph';
 import { TypedRef } from '@lua/workflow-graph';
+import type { WorkflowExecFn } from '@lua/shared-types/workflow-exec';
 import { WorkflowGraphEntry } from '@lua/workflow-graph';
+import type { WorkflowShellFn } from '@lua/shared-types/workflow-exec';
 import type { z } from 'zod';
 import { ZodType } from 'zod';
 
@@ -26,13 +28,13 @@ export declare interface AgentStepOptions {
     };
     timeoutSeconds?: number;
     retry?: RetryPolicy;
-    onError?: 'fail' | 'continue' | 'park';
+    onError?: WorkflowOnError;
     requiredConnections?: string[];
     /** static-only persona override (§11 S3) */
     systemPrompt?: string;
-    tier?: 'job';
+    tier?: WorkflowTier;
     workspace?: WorkflowStepWorkspace;
-    jobResources?: 'small' | 'medium' | 'large';
+    jobResources?: WorkflowJobResources;
     harness?: WorkflowJobHarness;
     /** Coding-turn cap for a tier:'job' step (1..500); absent ⇒ the platform default. A monorepo change needs more than the default. */
     maxTurns?: number;
@@ -41,7 +43,8 @@ export declare interface AgentStepOptions {
      * attempt (every pass and resumed segment). Crossing one checkpoints the workspace and ends the attempt
      * `attempt_budget_exhausted` — retryable, so the step's `retry` policy continues from that tree with a fresh
      * session. `maxMessages` counts harness messages (one per content block; 1..5000, default 400),
-     * `maxInputTokens` the attempt's input-side tokens (prompt + cache; 1M..500M, default 30M).
+     * `maxInputTokens` the attempt's input-side tokens (prompt + cache; 1M..500M, default 4M — LUA-708: the per-attempt
+     * cost bound, since `budget.maxCredits` counts attempts, not tokens).
      */
     maxMessages?: number;
     maxInputTokens?: number;
@@ -67,7 +70,7 @@ export declare interface ApprovalOptions {
     /** 'deny' (default) | 'cancel-run' | 'fail' | a chain of ≤ 3 hops ending in one terminal member */
     onTimeout?: WorkflowSuspendTimeoutChain;
     /** default 'continue' (denial is data unless 'fail') */
-    onDeny?: 'fail' | 'continue';
+    onDeny?: WorkflowApprovalOnDeny;
     businessHours?: WorkflowBusinessHours;
     editable?: boolean;
     /** grammar: `drafts`, `drafts[*]`, `drafts[*].body`, `drafts[3].body`, `summary.title` */
@@ -97,7 +100,13 @@ declare interface BuiltWorkflow {
     }>;
 }
 
-/** A container arm: a `StepRef`, or (B14 — lands with WF-509) the two-element chain `[mapConfig, stepRef]`. */
+/**
+ * A container arm: a `StepRef` — a `createStep` object, or a string naming an entry declared elsewhere in the chain
+ * (`agentStep` / `specialistStep` / `toolStep` / `workflow`, and since LUA-684 `approval` / `waitForSignal`, so an
+ * approval can run concurrently with another row) — or (B14 — lands with WF-509) the two-element chain
+ * `[mapConfig, stepRef]`. A HITL arm takes the previous output as its payload, so it never heads a `[map, step]`
+ * chain, and a `loop` body cannot be one until the engine proves it (`node-type-unsupported-in-container`).
+ */
 export declare type ContainerArm = StepRef | [LuaMapConfig, StepRef];
 
 export declare function createStep<TIn extends ZodType, TOut extends ZodType, TResume extends ZodType = ZodType>(s: LuaWorkflowStep<TIn, TOut, TResume>): LuaWorkflowStep<TIn, TOut, TResume>;
@@ -276,20 +285,28 @@ export declare type LuaWorkflowBuildCode = 'duplicate-step-id' | 'unknown-step-r
 * verdict (deferred for an inherit child, 03 §3.1 table). Kept for one minor so a consumer switching on the union still
 * compiles; removed in the next.
 */
-| 'workspace-not-declared' | 'workspace-inherit-without-parent-workspace' | 'workspace-inherit-conflict' | 'harness-requires-job-tier' | 'max-turns-requires-job-tier' | 'max-turns-invalid' | 'cap-exceeded' | 'chunk-size-invalid' | 'rate-limit-invalid' | 'backoff-invalid' | 'loop-interval-out-of-range' | 'mapping-placement' | 'container-arm-empty' | 'approval-inside-container' | 'empty-graph' | 'ephemeral-role-too-long' | 'role-ref-and-inline' | 'approver-excludes-only-candidate' | 'four-eyes-requires-editable' | 'escalation-chain-not-terminal' | 'escalation-chain-too-long' | 'editable-path-invalid' | 'env-template-secret-key' | 'invalid-envelope' | 'invalid-step' | 'invalid-step-id' | 'invalid-workflow-name' | 'schedule-input-required' | 'schedule-input-invalid' | 'hitl-duration-defaulted' | 'WORKFLOW_UNPLACED_STEP';
+| 'workspace-not-declared' | 'workspace-inherit-without-parent-workspace' | 'workspace-inherit-conflict' | 'harness-requires-job-tier' | 'max-turns-requires-job-tier' | 'max-turns-invalid' | 'cap-exceeded' | 'chunk-size-invalid' | 'rate-limit-invalid' | 'backoff-invalid' | 'loop-interval-out-of-range' | 'mapping-placement' | 'container-arm-empty'
+/**
+* @deprecated LUA-684 — the builder no longer throws it: an `approval` / `waitForSignal` IS a container arm
+* (`parallel(['approve', …])`). Where the engine cannot run one — a `loop` body, the step of a `[map, step]`
+* chain — the code is `node-type-unsupported-in-container`. Kept for one minor so a consumer switching on the
+* union still compiles; removed in the next.
+*/
+| 'approval-inside-container' | 'node-type-unsupported-in-container' | 'empty-graph' | 'ephemeral-role-too-long' | 'role-ref-and-inline' | 'approver-excludes-only-candidate' | 'four-eyes-requires-editable' | 'escalation-chain-not-terminal' | 'escalation-chain-too-long' | 'editable-path-invalid' | 'env-template-secret-key' | 'invalid-envelope' | 'invalid-step' | 'invalid-step-id' | 'invalid-workflow-name' | 'schedule-input-required' | 'schedule-input-invalid' | 'hitl-duration-defaulted' | 'WORKFLOW_UNPLACED_STEP';
 
 export declare interface LuaWorkflowBuilder {
     then(step: StepRef): this;
-    /** 2..16 arms; output = { [stepId]: output } */
+    /** 2..16 arms; output = { [stepId]: output }. An `approval` / `waitForSignal` arm (by id) parks beside its siblings. */
     parallel(steps: ContainerArm[], opts?: {
         merge?: WorkflowMergePolicy;
     }): this;
-    /** all-true arms run (Mastra); exclusive:true ≡ switch() */
+    /** all-true arms run (Mastra); exclusive:true ≡ switch(). An arm may name a declared `approval` / `waitForSignal`. */
     branch(arms: Array<[LuaPredicate, StepRef]>, opts?: {
         exclusive?: boolean;
     }): this;
     /** first true arm only ⇒ conditional{ exclusive:true, otherwise } */
     switch(arms: Array<[LuaPredicate, StepRef]>, otherwise?: StepRef): this;
+    /** one body run per item; an `approval` / `waitForSignal` body (by id) is one approval / wait per item */
     foreach(step: ContainerArm, opts?: ForeachOptions): this;
     dowhile(step: ContainerArm, predicate: LuaPredicate, opts?: LoopOptions): this;
     dountil(step: ContainerArm, predicate: LuaPredicate, opts?: LoopOptions): this;
@@ -312,12 +329,11 @@ export declare interface LuaWorkflowBuilder {
     /** D25 ephemeral specialist: runs AS THE OWNING AGENT (`agentId:'$self'`) with an additive role block. */
     specialistStep(id: string, opts: SpecialistStepOptions): this;
     toolStep(id: string, tool: LuaTool<any>, opts?: ToolStepOptions): this;
+    /** a declaration like `agentStep` (LUA-684): placed where called unless a container claims the id — `parallel(['approve', …])` */
     approval(id: string, opts: ApprovalOptions): this;
     waitForSignal(id: string, opts: WaitForSignalOptions): this;
     /** nested run; depth ≤ 3 — declares `id`, so a container may place it by string ref (03 §3.2.0) */
-    workflow(id: string, ref: LuaWorkflow | string, input?: LuaMapConfig, opts?: {
-        workspace?: 'inherit';
-    }): this;
+    workflow(id: string, ref: LuaWorkflow | string, input?: LuaMapConfig, opts?: NestedWorkflowOptions): this;
     commit(): LuaWorkflow;
 }
 
@@ -345,12 +361,23 @@ export declare interface LuaWorkflowConfig {
     concurrencyPolicy?: 'allow' | 'forbid';
     /** Who may READ this workflow's run outputs beyond `workflows:read-outputs` holders (B44). Envelope member outside `graphHash`. */
     outputVisibility?: WorkflowOutputVisibility;
-    /** `maxDurationSeconds` default 604 800; 2 592 000 when the graph contains an approval / waitForSignal / suspend-capable step (P1-4). */
-    budget?: {
-        maxCredits?: number;
-        maxSteps?: number;
-        maxDurationSeconds?: number;
-    };
+    /**
+     * `maxDurationSeconds` default 604 800; 2 592 000 when the graph contains an approval / waitForSignal / suspend-capable
+     * step (P1-4). The three members the SDK forwards, spelled by the ONE definition budget (`WorkflowDefinitionBudget`).
+     *
+     * `maxCredits` never meters tokens (LUA-708). Flat metering (every run while `LUA_WORKFLOWS_METERING_V2` is off):
+     * an inline agent step settles a flat 1 credit when it completes, a `tier:'job'` attempt a flat 4 at its first
+     * claim (a retry is a new attempt) — so `maxCredits: 40` buys ten Job-tier attempts, and a value under 4 never
+     * dispatches one. Priced metering (LUA-724, the flag on): an inline agent step settles what chat charged for the
+     * turn — one credit per model call on the legacy plan, `tier × model multiplier` actions on a seat plan (then the
+     * cap is compared in actions) — and `lua workflows status` says which mode a run used (`usage.metering`). Either
+     * way the run parks on a budget gate (`nextAction:'raise_budget'`, `lua workflows raise-budget`) when what remains
+     * is under the next agent step's reserve. Each Job-tier attempt then runs to its own wall (`timeoutSeconds`),
+     * `maxInputTokens` (default 4M ≈ $1–13 on a Sonnet-class model), `maxMessages` and `maxTurns`; nothing meters its
+     * tokens against the credits mid-attempt. Size `maxInputTokens` for what one attempt may cost and `maxCredits`
+     * for how many attempts the run may make.
+     */
+    budget?: Pick<WorkflowDefinitionBudget, 'maxCredits' | 'maxSteps' | 'maxDurationSeconds'>;
     /** verbatim LuaJob union (D12) → Job{kind:'workflow'} on publish */
     schedule?: JobSchedule;
     backfillOnEnable?: {
@@ -383,16 +410,16 @@ export declare interface LuaWorkflowStep<TIn extends ZodType = ZodType, TOut ext
     /** 1..600 (D19); default 300 — on `tier:'job'` 1..86 400, default 3600. */
     timeoutSeconds?: number;
     /** Run this step as a k8s Job (hours tier). Implied by `workspace`. */
-    tier?: 'job';
+    tier?: WorkflowTier;
     workspace?: WorkflowStepWorkspace;
-    jobResources?: 'small' | 'medium' | 'large';
+    jobResources?: WorkflowJobResources;
     jobTools?: WorkflowJobToolId[];
     /** default { maxAttempts: 1 } */
     retry?: RetryPolicy;
     /** default 'none'; 'external' ⇒ park on platform-fault reclaim. */
-    sideEffects?: 'none' | 'external';
+    sideEffects?: WorkflowSideEffects;
     /** What the FINAL failure of this step does to the run (default 'fail'). */
-    onError?: 'fail' | 'continue' | 'park';
+    onError?: WorkflowOnError;
     requiredConnections?: string[];
     /** Deadline for a `ctx.suspend()` suspension; default 168, max 720. */
     resumeTimeoutHours?: number;
@@ -404,6 +431,18 @@ export { MapDescriptor }
 
 export declare const ne: <T>(l: TypedRef<T>, r: TypedRef<T> | Literal<T>) => LuaPredicate;
 
+/** `.workflow(id, ref, input?, opts?)` — a nested run (a `subrun` row). */
+export declare interface NestedWorkflowOptions {
+    /** Mount the PARENT's run workspace in the child (05 §5.17.5; LUA-650) — the parent must declare one. */
+    workspace?: 'inherit';
+    /**
+     * LUA-669 (#2446): the same policy a code / agent / tool step carries — the row re-arms when the child run ends
+     * `failed` or `timed_out` on its own (a child the parent side ended — cancelled, abandoned — is never retried),
+     * behind the WF-222 backoff, and every attempt starts a FRESH child run. Default `{ maxAttempts: 1 }`.
+     */
+    retry?: RetryPolicy;
+}
+
 export declare const not: (arg: LuaPredicate) => LuaPredicate;
 
 export declare const notExists: (ref: TypedRef<unknown>) => LuaPredicate;
@@ -419,15 +458,10 @@ export declare type PathValue<T, P extends string> = P extends `${infer H}.${inf
 
 export declare type ReplyChannel = 'whatsapp' | 'sms' | 'email' | 'webchat' | 'slack';
 
-export declare interface RetryPolicy {
-    maxAttempts: number;
-    /** delay before attempt 2 (default 0 = immediate) */
-    backoffSeconds?: number;
-    /** 'fixed' (default) | 'exponential' — an engine timer, never a sleep inside the step VM (P1-10). */
-    backoff?: 'fixed' | 'exponential';
-    /** default 3600; only meaningful with 'exponential' (`backoff-invalid` otherwise). */
-    maxBackoffSeconds?: number;
-}
+/** The ONE retry shape (`@lua/shared-types` `WorkflowRetryPolicy`): `maxAttempts` ≥ 1; `backoffSeconds` (default 0 =
+ *  immediate) — an engine timer, never a sleep inside the step VM (P1-10); `backoff` 'fixed' (default) | 'exponential';
+ *  `maxBackoffSeconds` (default 3600) only meaningful with 'exponential' (`backoff-invalid` otherwise). */
+export declare type RetryPolicy = WorkflowRetryPolicy;
 
 export declare const rows: (s: LuaWorkflowStep<any, any, any> | string, path: string, page: {
     offset: number;
@@ -446,7 +480,7 @@ export declare interface SpecialistStepOptions {
     toolScope?: AgentToolScope;
     timeoutSeconds?: number;
     retry?: RetryPolicy;
-    onError?: 'fail' | 'continue' | 'park';
+    onError?: WorkflowOnError;
     requiredConnections?: string[];
 }
 
@@ -538,8 +572,8 @@ export declare interface ToolStepOptions {
     input?: LuaMapConfig;
     timeoutSeconds?: number;
     retry?: RetryPolicy;
-    sideEffects?: 'none' | 'external';
-    onError?: 'fail' | 'continue' | 'park';
+    sideEffects?: WorkflowSideEffects;
+    onError?: WorkflowOnError;
     requiredConnections?: string[];
 }
 
@@ -554,16 +588,42 @@ export declare interface WaitForSignalOptions {
     schema?: ZodType;
     timeoutHours?: number | TemplateBinding;
     /** default 'fail'; 'continue' ⇒ output {received:false,timedOut:true} */
-    onTimeout?: 'fail' | 'continue';
+    onTimeout?: WorkflowSignalOnTimeout;
     businessHours?: WorkflowBusinessHours;
     /** default ['webhook','api','user'] */
     acceptedSources?: Array<'webhook' | 'api' | 'user' | 'agent'>;
 }
 
+/** `approval.onDeny` (§6.4.11 deny-as-data): `'fail'` fails the step on a denial; default `'continue'`. */
+declare const WORKFLOW_APPROVAL_ON_DENY: readonly ["fail", "continue"];
+
 export declare const WORKFLOW_DEFAULT_MAX_DURATION_SECONDS = 604800;
 
 export declare const WORKFLOW_HITL_MAX_DURATION_SECONDS = 2592000;
 
+/** D19-r2 (B22; 05 §5.17.6 Harness row) — both behind one `CodingHarness { run(turn) }`. */
+declare const WORKFLOW_JOB_HARNESSES: readonly ["claude-code", "generic"];
+
+/** `jobResources` (05 §5.17): the Job-tier pod size class. Default `'small'` at spawn. */
+declare const WORKFLOW_JOB_RESOURCES: readonly ["small", "medium", "large"];
+
+/** What the FINAL failure of a step does to the run: `'park'` → the §06 §6.3.5 exception gate. Default `'fail'`. */
+declare const WORKFLOW_ON_ERROR: readonly ["fail", "continue", "park"];
+
+/** `backoff` absent ⇒ `'fixed'`; `'exponential'` = backoffSeconds·2^(attempt−1) capped at `maxBackoffSeconds`. */
+declare const WORKFLOW_RETRY_BACKOFFS: readonly ["fixed", "exponential"];
+
+/** `sideEffects` (03 §3.1): `'external'` ⇒ park on platform-fault reclaim instead of retrying. Default `'none'`. */
+declare const WORKFLOW_SIDE_EFFECTS: readonly ["none", "external"];
+
+/** `waitForSignal.onTimeout`: default `'fail'`; `'continue'` ⇒ output `{received:false, timedOut:true}`. */
+declare const WORKFLOW_SIGNAL_ON_TIMEOUT: readonly ["fail", "continue"];
+
+/** The only tier a node may DECLARE (`tier:'job'`, implied by `workspace`); the worker tier is the absence. */
+declare const WORKFLOW_TIERS: readonly ["job"];
+
+declare type WorkflowApprovalOnDeny = (typeof WORKFLOW_APPROVAL_ON_DENY)[number];
+
 export declare type WorkflowApproverSpec = 'creator' | 'org-admins' | {
     users: string[] | TemplateBinding;
 } | {
@@ -607,15 +667,37 @@ export declare interface WorkflowBusinessHours {
     };
 }
 
-declare interface WorkflowConnectionDeclaration {
+/** The ONE `connections[]` declaration shape (`@lua/shared-types`): `key` /^[a-z][a-z0-9_-]{0,63}$/ unique per workflow,
+ *  `integrationType` the catalog type (`'github'`, `'linear'`, …), optional `required` / `description`. */
+declare type WorkflowConnectionDeclaration = WorkflowConnectionDeclaration_2;
+
+declare interface WorkflowConnectionDeclaration_2 {
     /** /^[a-z][a-z0-9_-]{0,63}$/ — unique per workflow. */
     key: string;
-    /** Catalog integration type (`'github'`, `'linear'`, …). */
+    /** Catalog integration type (`github`, `linear`, …) the key resolves within. */
     integrationType: string;
     required?: boolean;
     description?: string;
 }
 
+/** The declared budget (10 §10.7.1) — every member optional on the DEFINITION; the server resolves
+ *  `maxDurationSeconds` onto the version (`WorkflowVersion.budget`) and the run. */
+declare interface WorkflowDefinitionBudget {
+    /**
+     * The run's credit ceiling — it counts agent steps, never tokens (LUA-708). An inline agent step settles a flat
+     * 1 credit when it completes; a `tier:'job'` attempt settles a flat 4 at its first claim (a retry is a new
+     * attempt). The engine parks the run on a budget gate (`nextAction:'raise_budget'`) when what remains is under
+     * the next agent step's reserve, so `maxCredits: 40` is ten Job-tier attempts and a value under 4 never
+     * dispatches one. A Job-tier attempt's own spend is bounded by its wall / `maxInputTokens` / `maxMessages`.
+     */
+    maxCredits?: number;
+    maxSteps?: number;
+    /** Job-tier seconds across the run (05 §5.17). */
+    maxJobSeconds?: number;
+    /** default 604 800; 2 592 000 when the graph contains an approval / waitForSignal / suspend-capable step (P1-4). */
+    maxDurationSeconds?: number;
+}
+
 export declare interface WorkflowFourEyes {
     edit: WorkflowApproverSpec;
     approve: WorkflowApproverSpec;
@@ -635,7 +717,11 @@ export declare interface WorkflowGoalEnvelope {
     initialState?: Record<string, unknown>;
 }
 
-export declare type WorkflowJobHarness = 'claude-code' | 'generic';
+export declare type WorkflowJobHarness = WorkflowJobHarness_2;
+
+declare type WorkflowJobHarness_2 = (typeof WORKFLOW_JOB_HARNESSES)[number];
+
+declare type WorkflowJobResources = (typeof WORKFLOW_JOB_RESOURCES)[number];
 
 export declare type WorkflowJobToolId = 'shell' | 'read' | 'write' | 'edit' | 'glob' | 'grep' | 'git' | 'gh' | 'fetch';
 
@@ -644,14 +730,32 @@ export declare interface WorkflowMergePolicy {
     onConflict: 'fail' | 'agent';
 }
 
+declare type WorkflowOnError = (typeof WORKFLOW_ON_ERROR)[number];
+
 export declare interface WorkflowOutputVisibility {
     roles: string[];
     users?: string[];
     ownerBypass?: boolean;
 }
 
+declare type WorkflowRetryBackoff = (typeof WORKFLOW_RETRY_BACKOFFS)[number];
+
+declare interface WorkflowRetryPolicy {
+    maxAttempts: number;
+    /** delay before attempt 2 (default 0 = immediate) — an engine timer, never a sleep inside the step VM (P1-10). */
+    backoffSeconds?: number;
+    /** `'fixed'` (default) | `'exponential'` */
+    backoff?: WorkflowRetryBackoff;
+    /** default 3600; only meaningful with `'exponential'` (`backoff-invalid` otherwise). */
+    maxBackoffSeconds?: number;
+}
+
 export declare type WorkflowRunTrigger = 'chat' | 'sdk' | 'api' | 'schedule' | 'webhook' | 'template' | 'workflow' | 'device';
 
+declare type WorkflowSideEffects = (typeof WORKFLOW_SIDE_EFFECTS)[number];
+
+declare type WorkflowSignalOnTimeout = (typeof WORKFLOW_SIGNAL_ON_TIMEOUT)[number];
+
 export declare interface WorkflowSpecialistRole {
     name: string;
     instructions: string;
@@ -675,7 +779,11 @@ export declare interface WorkflowStepContext<TIn = unknown, TResume = unknown, T
     /** What the prior invocation passed to `suspend()`. */
     suspendData?: unknown;
     getInitData<T = unknown>(): T;
-    /** Output of an UPSTREAM step. Throws `WorkflowStepResultError{ code:'STEP_RESULT_NOT_ANCESTOR' }` for a non-ancestor. */
+    /**
+     * Output of an UPSTREAM step. Throws `WorkflowStepResultError` — `code:'STEP_RESULT_NOT_ANCESTOR'` for a
+     * non-ancestor (or unknown) id, `'STEP_RESULT_TOO_LARGE'` / `'STEP_RESULT_OFFLOADED'` for an output the claim
+     * could not carry (see the error's doc for `bytes` / `reason`) — never `undefined`, never a raw ref object.
+     */
     getStepResult<T = unknown>(stepId: string): T;
     /** Run-scoped KV, ledger-backed, ≤ 64KB total. `set` is durable when the step terminalizes. */
     state: {
@@ -694,17 +802,65 @@ export declare interface WorkflowStepContext<TIn = unknown, TResume = unknown, T
     signal: AbortSignal;
     /** Sub-agent env, exactly as jobs receive it. */
     env: Record<string, string>;
-    /** EXACTLY-ONCE effect keyed on `{occurrenceId, key}` (P1-18). Claim → run `fn` → settle. */
+    /**
+     * EXACTLY-ONCE effect keyed on `{occurrenceId, key}` (P1-18). Claim → run `fn` → settle. Served on every tier:
+     * worker-tier steps and the offline driver, and (LUA-722) Job-tier code steps — the pod relays the claim / settle
+     * under its own attempt token, so the key is scoped to the step's run / row / attempt server-side. A replayed key
+     * (a retried attempt, a repair run) returns the settled result without running `fn`; a key a previous attempt
+     * claimed and never settled throws `EFFECT_IN_DOUBT` (fail closed — `fn` never runs on an unknown claim state).
+     * The result is JSON-serialised on settle, exactly like a step output: a `Date` replays as its ISO string, a
+     * `BigInt` (or a cycle) fails the settle — `EFFECT_SETTLE_FAILED`, the key stays claimed — and a result over the
+     * platform's cap (32 KB) is `EFFECT_SETTLE_FAILED` naming `EFFECT_RESULT_TOO_LARGE`. Calling `once` again for the
+     * same key while its `fn` is still running (re-entrantly) throws `EFFECT_KEY_INVALID` at once.
+     */
     once<T>(key: string, fn: () => Promise<T>): Promise<T>;
-    /** Job-tier steps only: the mounted run workspace. */
+    /**
+     * Job-tier steps only: the mounted run workspace, exactly as the Job pod hands it to `execute` (`ctx.workspace` in
+     * `packages/lua-workflow-job/src/code-step.ts`): `root` is the absolute directory of the checkout (`/workspace`),
+     * `branch` the run branch it is on, `headSha` the commit it was restored at, `mount` this step's declared mount,
+     * `isolation` whether the step got its own worktree. LUA-679: the name is `root` — the 3.32.1 type and both
+     * `lua init` examples said `path`, the pod never served it, and a copied definition died `ENOENT /workspace/undefined`.
+     */
     workspace?: {
-        path: string;
+        root: string;
         mount: 'rw' | 'ro';
         branch?: string;
+        headSha?: string;
+        isolation?: 'shared' | 'worktree';
+        /**
+         * @deprecated LUA-679 — read `root`. The Job pod serves `path` as an alias (a getter that returns `root` and warns
+         * once per step) for one minor after 3.32 and then removes it; it never appears on `Object.keys(ctx.workspace)`.
+         */
+        readonly path?: string;
+        /**
+         * The run workspace's stamps, served when the pod hands them to the step (LUA-706): `baseSha` is the commit the
+         * run's base ref resolved to at provision (a git workspace — `headSha` is where THIS step's checkout is), `arm`
+         * the worktree arm id when the step runs in its own worktree (`isolation:'worktree'`), `backend` the volume
+         * backend. Absent on an `empty` workspace, a shared-mount step, or a pod that predates them.
+         */
         baseSha?: string;
         arm?: string;
         backend?: WorkflowWorkspaceBackend;
     };
+    /**
+     * Job-tier steps only (LUA-682): run one of `WORKFLOW_EXEC_BINARIES` (`git`, `gh`, `pnpm`, `npm`, `npx`, `node`,
+     * `yarn`, `python3`, `pytest`, `make`) in the workspace — `exec(['git', 'status'], { cwd?, timeoutMs?, env? })`.
+     * Argv only, never a shell: no `&&`, pipes, globs or `$VAR`; `cwd` must stay inside the workspace; the timeout
+     * (default 10 min) is capped by the step's remaining wall; stdout / stderr are kept to 1 MiB each (`truncated`);
+     * one command at a time. A non-zero exit is RETURNED (`result.code`) — `exec.strict` throws `WorkflowExecError`.
+     * The Job pod spawns the command itself with a scrubbed env (no token, no `LUA_WF_*`; git goes through the
+     * credential proxy exactly as the coding turn's does); `child_process` is not available to a code step and fails
+     * `lua compile` with `node-capability-unavailable`. Worker-tier steps have neither `exec` nor `$`. Offline,
+     * `lua workflows run --workspace <dir>` provides both with the same allowlist against your own PATH.
+     */
+    exec?: WorkflowExecFn;
+    /**
+     * Job-tier steps only (LUA-682): `exec` as a tagged template — `$\`gh pr create --title ${title} --body ${body}\``.
+     * Literal text splits on whitespace (with `'…'` / `"…"` quoting); every `${value}` is exactly ONE argument, never
+     * re-parsed (a title with spaces, a body with newlines); an array spreads into one argument per item; `undefined`
+     * is refused rather than stringified. `$.strict` throws on a non-zero exit.
+     */
+    $?: WorkflowShellFn;
     /** The run artefact store (P1-8). */
     artefacts: {
         put(name: string, data: Uint8Array | string | ReadableStream, opts: {
@@ -739,7 +895,12 @@ export declare interface WorkflowStepContext<TIn = unknown, TResume = unknown, T
         }>;
         list(): Promise<WorkflowArtefactMeta[]>;
     };
-    /** Stamped by the executor for observability; read-only. */
+    /**
+     * Stamped by the executor for observability; read-only (frozen). Served on both tiers from the run's stamps
+     * (LUA-706): `trigger` / `principalKind`, plus `parentRunId` / `traceparent` / `correlationKey` / `tags` /
+     * `replyTo` when the run carries them; `agentVersion` is not stamped today. A run created before the stamps
+     * existed reads `{}`. Offline, `lua workflows run` serves `{ trigger:'sdk', principalKind:'user' }`.
+     */
     runtime: {
         trigger: WorkflowRunTrigger;
         parentRunId?: string;
@@ -755,10 +916,26 @@ export declare interface WorkflowStepContext<TIn = unknown, TResume = unknown, T
     };
 }
 
-/** Thrown by `ctx.getStepResult` for a non-ancestor / unknown id — never `undefined` (03 §3.1). */
+/**
+ * Thrown by `ctx.getStepResult` — never `undefined`, never a raw ref object (03 §3.1). Check `err.code`, never
+ * `instanceof` (a step runs in its own realm on every tier):
+ *  - `STEP_RESULT_NOT_ANCESTOR` — `stepId` is not an upstream step of this one (or is unknown);
+ *  - `STEP_RESULT_TOO_LARGE` — the ancestor's output could not ride the claim beside its siblings (the 4 MiB
+ *    `stepResults` wire budget, dropped largest-first); `bytes` is its serialized size;
+ *  - `STEP_RESULT_OFFLOADED` — the ledger holds the output offloaded (> 256 KB) and the claim could not carry it
+ *    hydrated; `bytes` is its size, `reason` why: `over_wire_cap` (it would break the budget), `hydrate_timeout`
+ *    (the per-claim hydration deadline passed), or the control plane's code (`CDN_REF_MISSING`, `CDN_REF_CORRUPT`,
+ *    `CDN_REF_FOREIGN`, …).
+ * For the last two, bind the value through the step's input instead, or read it via `ctx.artefacts` /
+ * `ctx.datasets`. The offline driver (`lua workflows execute`) only ever throws the first.
+ */
 export declare interface WorkflowStepResultError extends Error {
-    code: 'STEP_RESULT_NOT_ANCESTOR';
+    code: 'STEP_RESULT_NOT_ANCESTOR' | 'STEP_RESULT_TOO_LARGE' | 'STEP_RESULT_OFFLOADED';
     stepId: string;
+    /** `STEP_RESULT_TOO_LARGE` / `STEP_RESULT_OFFLOADED`: the output's serialized size. */
+    bytes?: number;
+    /** `STEP_RESULT_OFFLOADED`: why the claim could not carry it. */
+    reason?: string;
 }
 
 export declare interface WorkflowStepWorkspace {
@@ -777,6 +954,8 @@ export declare type WorkflowSuspendTimeoutChainMember = 'deny' | 'cancel-run' |
     timeoutHours: number;
 };
 
+declare type WorkflowTier = (typeof WORKFLOW_TIERS)[number];
+
 export declare type WorkflowWorkspaceBackend = 'ebs' | 'efs' | 's3';
 
 export declare type WorkspaceSpec = {
@@ -793,6 +972,10 @@ export declare type WorkspaceSpec = {
     kind: 'empty';
     sizeGb?: number;
     ttlHours?: number;
+    /**
+     * Keep the volume after the run completes: held until `ttlHours` (24 h when undeclared), then expired. A kept
+     * volume holds one of the organisation's workspace slots (`maxWorkspacesPerOrg`, 10 by default) until then.
+     */
     keepArtefacts?: boolean;
     backend?: WorkflowWorkspaceBackend;
 };