lua-cli 3.32.1 → 3.32.3

package/dist/api-exports.d.ts

@@ -18,7 +18,16 @@ import { SerializedWorkflowGraph } from '@lua/workflow-graph';
 import { TemplateBinding } from '@lua/workflow-graph';
 import { TypedRef } from '@lua/workflow-graph';
 import { UserContent } from 'ai';
+import { WorkflowExecFn as WorkflowExec } from '@lua/shared-types/workflow-exec';
+import { WorkflowExecBinary } from '@lua/shared-types/workflow-exec';
+import { WorkflowExecError } from '@lua/shared-types/workflow-exec';
+import { WorkflowExecErrorCode } from '@lua/shared-types/workflow-exec';
+import { WorkflowExecOptions } from '@lua/shared-types/workflow-exec';
+import { WorkflowExecRefusalReason } from '@lua/shared-types/workflow-exec';
+import { WorkflowExecOutcome as WorkflowExecResult } from '@lua/shared-types/workflow-exec';
 import { WorkflowGraphEntry } from '@lua/workflow-graph';
+import { WorkflowShellFn as WorkflowShell } from '@lua/shared-types/workflow-exec';
+import { WorkflowShellValue } from '@lua/shared-types/workflow-exec';
 import { z } from 'zod';
 import { ZodType } from 'zod';
 
@@ -180,6 +189,34 @@ declare interface AgentInvocationInput {
     };
 }
 
+/**
+ * LUA-724 (PR 7) — the billed turn's pricing inputs, exactly as chat's settlement event carries
+ * them (`chat.service.trackLlmInferenceUsage`): the model that ACTUALLY served the turn (the
+ * resolver's code, not the caller's pin), the de-paged `contextInputTokens` (largest single
+ * step's prompt — never the whole-turn sum), the tool-call COUNT, and whether the turn ran on
+ * the org's own key. `chargedCredits` echoes the gate's answer (true ⇒ the legacy pool deducted
+ * in real time; false ⇒ seat org / free turn — settlement meters it).
+ *
+ * Stamped by the serving pod ONLY on internal-auth turns that carry a billing `operationId`
+ * (the workflow agent-step loopback), as the enumerable `luaMeter` top-level field of the
+ * generate envelope — never on a Bearer turn, so the public wire is byte-identical. The
+ * workflow executor prices the step's `run.budget.spent` from it with `priceModelCall`.
+ */
+declare interface AgentInvocationMeter {
+    model?: string;
+    contextInputTokens?: number;
+    /** Tool-call COUNT (`toolNames.length`) — the tier's tool signal. */
+    toolsFired?: number;
+    /**
+     * The tool names fired, one entry per call (repeats kept), exactly as the usage event's
+     * `toolNames` — settlement intersects them with the pricing config's `docProcessingToolNames`
+     * to force the heavy tier (`hasDocProcessingTool`), so the workflow price must see them too.
+     */
+    toolNames?: string[];
+    byok?: boolean;
+    chargedCredits?: boolean;
+}
+
 declare interface AgentInvocationOutput {
     /** Final response text (post-processor-modified, if applicable). */
     text: string;
@@ -202,6 +239,12 @@ declare interface AgentInvocationOutput {
     };
     /** Names of tools invoked during generation. */
     toolsUsed?: string[];
+    /**
+     * LUA-724 (PR 7) — the turn's pricing inputs (see `AgentInvocationMeter`). Present only when
+     * the serving pod stamped `luaMeter` (an `operationId`-bearing internal-auth turn); absent
+     * otherwise — legacy outputs are byte-identical.
+     */
+    meter?: AgentInvocationMeter;
     /** Trusted effects emitted by Lua-owned tool wrappers. This is intentionally
      *  a small aggregate, not raw tool output: unattended task receipts use it
      *  to report what happened without trusting model-authored prose. */
@@ -307,13 +350,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;
@@ -322,7 +365,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;
@@ -553,7 +597,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` */
@@ -909,11 +953,14 @@ declare interface BuiltWorkflow {
     }>;
 }
 
-/** R11 — `CancelRunVerdict` (PRO-979 vocabulary). */
+/** R11 — `CancelRunVerdict` (PRO-979 vocabulary; §9.5.2 — a terminal run answers `state:'terminal'`, never an error). */
 declare interface CancelRunVerdict {
     status: WorkflowRunStatus;
     nextAction: string;
     forceAvailableAt?: string;
+    cancelRequested?: boolean;
+    state?: 'running' | 'cancellation_requested' | 'abandoned' | 'terminal';
+    transitioned?: boolean;
 }
 
 /**
@@ -1310,7 +1357,13 @@ export declare interface ChatHistoryMessage {
  */
 export declare type ChatMessage = TextMessage | ImageMessage | FileMessage;
 
-/** 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];
 
 /**
@@ -3882,13 +3935,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     }, {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
@@ -3903,13 +3956,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -3923,12 +3976,12 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     }, {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     }>]>;
     stt: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"inference">;
@@ -3948,13 +4001,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     }, {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
@@ -3969,13 +4022,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -3989,12 +4042,12 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     }, {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     }>]>>;
     tts: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"inference">;
@@ -4014,13 +4067,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     }, {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
@@ -4035,13 +4088,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -4055,12 +4108,12 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     }, {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     }>]>>;
     vad: z.ZodOptional<z.ZodString>;
     vadOptions: z.ZodOptional<z.ZodObject<{
@@ -4222,49 +4275,49 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     vad?: string;
     stt?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     volume?: number;
     llm?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     tts?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -4316,49 +4369,49 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     vad?: string;
     stt?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     volume?: number;
     llm?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     tts?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -4410,49 +4463,49 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     vad?: string;
     stt?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     volume?: number;
     llm?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     tts?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -4504,49 +4557,49 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     vad?: string;
     stt?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     volume?: number;
     llm?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     tts?: {
         voice?: string;
-        options?: Record<string, unknown>;
         kind?: "inference";
+        options?: Record<string, unknown>;
         model?: string;
     } | {
         provider?: "deepgram" | "elevenlabs";
-        options?: Record<string, unknown>;
         kind?: "plugin";
+        options?: Record<string, unknown>;
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
         provider?: "google" | "xai" | "openai";
-        options?: Record<string, unknown>;
         kind?: "realtime";
+        options?: Record<string, unknown>;
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -4935,20 +4988,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;
@@ -4971,12 +5032,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;
 }
 
@@ -5004,12 +5064,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?: {
@@ -5042,16 +5113,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;
@@ -5174,6 +5245,18 @@ declare type Message = TextMessage_2 | ImageMessage_2 | FileMessage_2;
 
 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;
@@ -6076,6 +6159,11 @@ declare interface RequestOverrides {
     timeoutMs?: number;
 }
 
+/**
+ * R12 — `ResumeStepResult` (§9.5.3): the loser of a resume race gets the recorded outcome, never a 4xx. LUA-738
+ * (desktop #1018): `recorded.by` is the spec's `WorkflowActorRef` — lua-api projects lua-core's `{ kind, id }` onto
+ * it (`system:timed_out` for the timeout sweep, `system:<id>` with `source:'webhook'` for a webhook caller).
+ */
 declare type ResumeStepResult = {
     resumed: true;
     runStatus: WorkflowRunStatus;
@@ -6085,22 +6173,18 @@ declare type ResumeStepResult = {
     recorded: {
         at: number;
         by?: {
-            kind: string;
-            id?: string;
+            subjectType: string;
+            subjectId: string;
+            source: string;
         };
     };
     runStatus: WorkflowRunStatus;
 };
 
-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;
@@ -6191,7 +6275,7 @@ export declare interface SpecialistStepOptions {
     toolScope?: AgentToolScope;
     timeoutSeconds?: number;
     retry?: RetryPolicy;
-    onError?: 'fail' | 'continue' | 'park';
+    onError?: WorkflowOnError;
     requiredConnections?: string[];
 }
 
@@ -6202,12 +6286,23 @@ declare interface SseFrame {
     data: unknown;
 }
 
-/** R8 — 202 `{ runId, status:'queued'|'gated', watchHint, idempotentReplay? }`, or 200 the run detail when `waitSeconds` elapsed on a terminal/suspended run. */
+/**
+ * R8 — 202 `{ runId, status:'queued'|'gated', watchHint }`, 200 `{ …, idempotentReplay:true, deduplicated:true,
+ * workflowId, workflowName, startedAt }` on an Idempotency-Key replay (LUA-739: the EXISTING run's identity,
+ * real status and real start — no run was created), or 200 the run detail when `waitSeconds` elapsed on a
+ * terminal/suspended run.
+ */
 declare interface StartWorkflowRunResult {
     runId: string;
     status: WorkflowRunStatus;
     watchHint?: string;
     idempotentReplay?: boolean;
+    /** `true` ⇒ no run was created — `workflowId` / `workflowName` / `startedAt` / `status` are the existing holder's. */
+    deduplicated?: boolean;
+    workflowId?: string;
+    workflowName?: string;
+    /** ISO — the existing run's creation time. */
+    startedAt?: string;
     output?: unknown;
 }
 
@@ -6446,8 +6541,8 @@ export declare interface ToolStepOptions {
     input?: LuaMapConfig;
     timeoutSeconds?: number;
     retry?: RetryPolicy;
-    sideEffects?: 'none' | 'external';
-    onError?: 'fail' | 'continue' | 'park';
+    sideEffects?: WorkflowSideEffects;
+    onError?: WorkflowOnError;
     requiredConnections?: string[];
 }
 
@@ -6903,7 +6998,7 @@ 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'>;
@@ -7032,6 +7127,32 @@ declare interface WhatsAppTemplateUrlButton {
     example?: string | string[];
 }
 
+/** `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"];
+
+/** 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;
 } | {
@@ -7075,15 +7196,51 @@ 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 { WorkflowExec }
+
+export { WorkflowExecBinary }
+
+export { WorkflowExecError }
+
+export { WorkflowExecErrorCode }
+
+export { WorkflowExecOptions }
+
+export { WorkflowExecRefusalReason }
+
+export { WorkflowExecResult }
+
 export declare interface WorkflowFourEyes {
     edit: WorkflowApproverSpec;
     approve: WorkflowApproverSpec;
@@ -7103,7 +7260,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';
 
@@ -7112,12 +7273,26 @@ 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;
+}
+
 /**
  * Matches WorkflowRunDto (R4 `fields:'summary'` — outputs are never inlined here).
  * The wire names the run `runId` (shared-types `WorkflowRunSummary`); `id` is the pre-R4 spelling some
@@ -7142,8 +7317,24 @@ declare interface WorkflowRun {
         reason?: string;
         since?: string;
     };
+    /**
+     * The pending / audited cancel request (`runCancelView`): who asked and when; `wall` when it was the run wall's
+     * own (LUA-686); LUA-704: `forcedBy` / `forcedAt` / `forceReason` on a forced terminal (`abandoned`, or
+     * `timed_out` when the wall's request was forced) — the run's own reason is the terminal's.
+     */
+    cancel?: {
+        requestedAt: number;
+        requestedBy: string;
+        forceAvailableAt: number;
+        wall?: boolean;
+        forcedAt?: number;
+        forcedBy?: string;
+        forceReason?: string;
+    };
     failureReason?: string;
     restricted?: boolean;
+    /** R4 `fields:'full'` only (§9.3.1): the caller may not read this run's payloads — `output` / step outputs are withheld. */
+    outputsHidden?: 'read-outputs' | 'cloud-task';
     /** LUA-623: the keys the run's version declares, and what each resolved to on its agent (`connection.resolved` rows). */
     connections?: {
         declared: Array<{
@@ -7165,6 +7356,39 @@ declare interface WorkflowRun {
     outputPreview?: string;
     /** LUA-643: every shape says whether a result exists; `--steps` (`fields:'full'`) serves it. */
     hasOutput?: boolean;
+    /**
+     * §08 §8.1 `usage` — the settled spend and, LUA-724 (PR 8), how it was metered: `metering` `'flat'` (1 credit per
+     * inline agent step, 4 per Job-tier attempt — every run while `LUA_WORKFLOWS_METERING_V2` is off) or `'priced'`
+     * (charged like chat: a credit per model call on the legacy plan, `tier × model multiplier` actions on a seat
+     * plan — then `engine` names the plan and `actionsUsed` carries a seat run's actions).
+     */
+    usage?: {
+        creditsUsed?: number;
+        actionsEstimate?: number;
+        actionsUsed?: number;
+        metering?: 'flat' | 'priced';
+        engine?: 'legacy' | 'seat';
+        steps?: number;
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    /**
+     * R4: the run's caps and settled spend. `maxCredits` and `remaining` are both absent on an uncapped run (`0` = unset);
+     * `remaining` is the engine's pre-dispatch subtraction (priced actions and claimed-step holds count), floored at 0.
+     */
+    budget?: {
+        maxCredits?: number;
+        maxSteps?: number;
+        maxDurationSeconds?: number;
+        unit?: 'credits' | 'actions';
+        spent?: {
+            credits?: number;
+            actionsEstimate?: number;
+            steps?: number;
+        };
+        reserved?: number;
+        remaining?: number;
+    };
     createdAt: string;
     startedAt?: string;
     completedAt?: string;
@@ -7307,6 +7531,14 @@ export declare interface WorkflowsApi {
     };
 }
 
+export { WorkflowShell }
+
+export { WorkflowShellValue }
+
+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;
@@ -7330,7 +7562,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: {
@@ -7349,17 +7585,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?: WorkflowExec;
+    /**
+     * 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.
+     */
+    $?: WorkflowShell;
     /** The run artefact store (P1-8). */
     artefacts: {
         put(name: string, data: Uint8Array | string | ReadableStream, opts: {
@@ -7394,7 +7678,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;
@@ -7410,10 +7699,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 {
@@ -7432,6 +7737,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 = {
@@ -7448,6 +7755,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;
 };