lua-cli 3.31.0 → 3.32.2

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,16 +28,26 @@ 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;
+    /**
+     * Per-ATTEMPT ceilings for a tier:'job' step (LUA-636): `maxTurns` bounds one harness query; these bound the whole
+     * 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 4M — LUA-708: the per-attempt
+     * cost bound, since `budget.maxCredits` counts attempts, not tokens).
+     */
+    maxMessages?: number;
+    maxInputTokens?: number;
 }
 
 export declare interface AgentToolScope {
@@ -58,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` */
@@ -80,13 +92,21 @@ declare interface BuiltWorkflow {
     steps: Record<string, LuaWorkflowStep<any, any, any>>;
     warnings: LuaWorkflowBuildWarning[];
     envTemplateKeys: string[];
+    /** `.workflow(id, ref, …, { workspace })` targets; `workspace:'inherit'` marks an inherit child — the compiler defers `workspace-not-declared` for it (03 §3.1). */
     nestedRefs: Array<{
         id: string;
         name: string;
+        workspace?: 'inherit';
     }>;
 }
 
-/** 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>;
@@ -249,29 +269,44 @@ export declare class LuaWorkflow {
     getBuildWarnings(): LuaWorkflowBuildWarning[];
     /** Every `env.template(KEY)` placeholder key the graph carries (sorted, deduped) — `ManifestWorkflow.envTemplateKeys`. */
     getEnvTemplateKeys(): string[];
-    /** `.workflow(id, ref)` targets by name — `ManifestWorkflow.workflowRefs`. */
+    /** `.workflow(id, ref)` targets by name — `ManifestWorkflow.workflowRefs`; `workspace:'inherit'` marks the inherit children the compiler defers `workspace-not-declared` for. */
     getNestedWorkflowRefs(): Array<{
         id: string;
         name: string;
+        workspace?: 'inherit';
     }>;
     /** Pure: no I/O, no env, no time. Called by the compiler in the VM tier and by `lua test`. */
     __serializeGraph(): SerializedWorkflowGraph;
 }
 
-export declare type LuaWorkflowBuildCode = 'duplicate-step-id' | 'unknown-step-ref' | 'map-id-required' | 'closure-predicate' | 'closure-binding' | 'timeout-out-of-range' | 'timeout-exceeds-tier' | 'job-timeout-exceeds-cap' | 'long-job-requires-workspace' | 'workspace-requires-job-tier' | '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';
+export declare type LuaWorkflowBuildCode = 'duplicate-step-id' | 'unknown-step-ref' | 'map-id-required' | 'closure-predicate' | 'closure-binding' | 'timeout-out-of-range' | 'timeout-exceeds-tier' | 'job-timeout-exceeds-cap' | 'long-job-requires-workspace' | 'workspace-requires-job-tier'
+/**
+* @deprecated LUA-635 — the builder no longer throws it: a mount with no envelope `workspace` is the SHARED validator's
+* 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'
+/**
+* @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;
@@ -294,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 */
-    workflow(id: string, ref: LuaWorkflow | string, input?: LuaMapConfig, opts?: {
-        workspace?: 'inherit';
-    }): 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?: NestedWorkflowOptions): this;
     commit(): LuaWorkflow;
 }
 
@@ -327,12 +361,19 @@ 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` counts agent steps, never tokens (LUA-708): 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). 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 — so `maxCredits: 40` buys ten Job-tier attempts, and a value under 4 never dispatches one. Each
+     * 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?: {
@@ -344,6 +385,13 @@ export declare interface LuaWorkflowConfig {
     /** NEVER set by hand — the compiler derives it from the source file. */
     form?: 'graph' | 'script';
     workspace?: WorkspaceSpec;
+    /**
+     * Declared connection keys. `workspace.credentialsRef` and a step's `requiredConnections` may name a
+     * `key` instead of a connection id; the engine resolves it against the owner agent's own connections
+     * at run time (agent-scoped first, then org-scoped — never a user's), so the same definition runs on
+     * a template install, a hand-built agent and a duplicate without a frozen id.
+     */
+    connections?: WorkflowConnectionDeclaration[];
 }
 
 export declare interface LuaWorkflowStep<TIn extends ZodType = ZodType, TOut extends ZodType = ZodType, TResume extends ZodType = ZodType> {
@@ -358,16 +406,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;
@@ -379,6 +427,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;
@@ -394,15 +454,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;
@@ -421,7 +476,7 @@ export declare interface SpecialistStepOptions {
     toolScope?: AgentToolScope;
     timeoutSeconds?: number;
     retry?: RetryPolicy;
-    onError?: 'fail' | 'continue' | 'park';
+    onError?: WorkflowOnError;
     requiredConnections?: string[];
 }
 
@@ -513,8 +568,8 @@ export declare interface ToolStepOptions {
     input?: LuaMapConfig;
     timeoutSeconds?: number;
     retry?: RetryPolicy;
-    sideEffects?: 'none' | 'external';
-    onError?: 'fail' | 'continue' | 'park';
+    sideEffects?: WorkflowSideEffects;
+    onError?: WorkflowOnError;
     requiredConnections?: string[];
 }
 
@@ -529,16 +584,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;
 } | {
@@ -582,6 +663,37 @@ export declare interface WorkflowBusinessHours {
     };
 }
 
+/** 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`, …) 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;
@@ -601,7 +713,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';
 
@@ -610,14 +726,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;
@@ -641,7 +775,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: {
@@ -660,17 +798,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: {
@@ -705,7 +891,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;
@@ -721,10 +912,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 {
@@ -743,6 +950,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 = {
@@ -759,6 +968,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;
 };