From 8ca6e5111fd2710cf56da1acb1dfd0bc986da2c8 Mon Sep 17 00:00:00 2001
From: Bhavik Agarwal <agarwalbhavik2001@gmail.com>
Date: Wed, 16 Sep 2026 16:55:39 +0530
Subject: [PATCH 1/2] feat: add agent-agnostic dynamic workflows

---
 README.md                                     |    2 +
 docs/dynamic-workflows-implementation-plan.md |  998 ++++++++++++
 docs/dynamic-workflows.md                     |   79 +
 examples/workflows/bounded-repair.js          |   20 +
 examples/workflows/isolated-migrations.js     |    8 +
 examples/workflows/nested-synthesis.js        |    8 +
 examples/workflows/review-and-verify.js       |   11 +
 package.json                                  |    7 +-
 pnpm-lock.yaml                                |   64 +-
 schema/v1/devspace.schema.json                |  179 +++
 skills/workflows/SKILL.md                     |   59 +
 src/cli.ts                                    |   10 +
 src/config-schema.ts                          |    2 +
 src/config.ts                                 |    3 +
 src/db/migrations.ts                          |  158 +-
 src/db/schema.ts                              |  161 +-
 src/local-agent-acp.test.ts                   |   49 +-
 src/local-agent-acp.ts                        |  129 +-
 src/local-agent-adapters.test.ts              |   23 +
 src/local-agent-cancellation.test.ts          |  137 ++
 src/local-agent-catalog.ts                    |    1 +
 src/local-agent-claude.test.ts                |   49 +
 src/local-agent-claude.ts                     |  155 +-
 src/local-agent-client.ts                     |   38 +-
 src/local-agent-codex.test.ts                 |   81 +-
 src/local-agent-codex.ts                      |  188 ++-
 src/local-agent-daemon-lifecycle.ts           |    2 +-
 src/local-agent-daemon-main.ts                |   86 +-
 src/local-agent-daemon-protocol.ts            |    8 +
 src/local-agent-daemon.test.ts                |    6 +-
 src/local-agent-daemon.ts                     |   28 +-
 src/local-agent-manager.ts                    |  349 +++-
 src/local-agent-opencode.test.ts              |   95 +-
 src/local-agent-opencode.ts                   |  152 +-
 src/local-agent-pi.test.ts                    |   39 +
 src/local-agent-pi.ts                         |  143 +-
 src/local-agent-presentation.ts               |    4 +-
 src/local-agent-profiles.test.ts              |    2 +
 src/local-agent-profiles.ts                   |   14 +
 src/local-agent-runtime-pool.ts               |    8 +-
 src/local-agent-runtime.test.ts               |   22 +-
 src/local-agent-runtime.ts                    |   97 ++
 src/local-agent-store.ts                      |  118 +-
 src/oauth-store.test.ts                       |    3 +
 src/server.test.ts                            |   15 +
 src/server.ts                                 |   26 +-
 src/skills.ts                                 |   63 +-
 src/test-support/config.test.ts               |    2 +
 src/workflow-cli.ts                           |  133 ++
 src/workflow-config.ts                        |   49 +
 src/workflow-daemon.test.ts                   |   43 +
 src/workflow-manager.test.ts                  |  464 ++++++
 src/workflow-manager.ts                       | 1432 +++++++++++++++++
 src/workflow-protocol.ts                      |   74 +
 src/workflow-registry.test.ts                 |   55 +
 src/workflow-registry.ts                      |  231 +++
 src/workflow-runtime.test.ts                  |  339 ++++
 src/workflow-runtime.ts                       |  412 +++++
 src/workflow-schema.test.ts                   |   68 +
 src/workflow-schema.ts                        |  170 ++
 src/workflow-script.test.ts                   |   41 +
 src/workflow-script.ts                        |  187 +++
 src/workflow-security.test.ts                 |   35 +
 src/workflow-store.test.ts                    |   48 +
 src/workflow-store.ts                         |  693 ++++++++
 src/workflow-tools.test.ts                    |   60 +
 src/workflow-tools.ts                         |   59 +
 src/workflow-types.ts                         |  178 ++
 src/workflow-worker.ts                        |  662 ++++++++
 test/workflow-cli-smoke.test.ts               |  103 ++
 70 files changed, 9217 insertions(+), 220 deletions(-)
 create mode 100644 docs/dynamic-workflows-implementation-plan.md
 create mode 100644 docs/dynamic-workflows.md
 create mode 100644 examples/workflows/bounded-repair.js
 create mode 100644 examples/workflows/isolated-migrations.js
 create mode 100644 examples/workflows/nested-synthesis.js
 create mode 100644 examples/workflows/review-and-verify.js
 create mode 100644 skills/workflows/SKILL.md
 create mode 100644 src/local-agent-cancellation.test.ts
 create mode 100644 src/workflow-cli.ts
 create mode 100644 src/workflow-config.ts
 create mode 100644 src/workflow-daemon.test.ts
 create mode 100644 src/workflow-manager.test.ts
 create mode 100644 src/workflow-manager.ts
 create mode 100644 src/workflow-protocol.ts
 create mode 100644 src/workflow-registry.test.ts
 create mode 100644 src/workflow-registry.ts
 create mode 100644 src/workflow-runtime.test.ts
 create mode 100644 src/workflow-runtime.ts
 create mode 100644 src/workflow-schema.test.ts
 create mode 100644 src/workflow-schema.ts
 create mode 100644 src/workflow-script.test.ts
 create mode 100644 src/workflow-script.ts
 create mode 100644 src/workflow-security.test.ts
 create mode 100644 src/workflow-store.test.ts
 create mode 100644 src/workflow-store.ts
 create mode 100644 src/workflow-tools.test.ts
 create mode 100644 src/workflow-tools.ts
 create mode 100644 src/workflow-types.ts
 create mode 100644 src/workflow-worker.ts
 create mode 100644 test/workflow-cli-smoke.test.ts

diff --git a/README.md b/README.md
index d307e707f..c14b99d0a 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ DevSpace is a self-hosted MCP server that lets ChatGPT read, edit, search, and r
 
 The same `/mcp` endpoint serves the 2026-07-28 per-request protocol and automatically supports older 2025-era clients through stateless compatibility handling. There is no protocol mode to configure.
 
+[Dynamic workflows](docs/dynamic-workflows.md) let a host write JavaScript to coordinate configured subagents in parallel, run pipelines, validate structured results, and inspect or control durable runs.
+
 ## Sponsors and Special Thanks
 <!-- 
 
diff --git a/docs/dynamic-workflows-implementation-plan.md b/docs/dynamic-workflows-implementation-plan.md
new file mode 100644
index 000000000..c06e52b1c
--- /dev/null
+++ b/docs/dynamic-workflows-implementation-plan.md
@@ -0,0 +1,998 @@
+# Dynamic workflows: implementation plan
+
+Status: design contract, 2026-09-16. See [the usage guide](dynamic-workflows.md) and the executable schemas/tests for current implementation behavior. This document records the design and acceptance criteria.
+
+## 1. Scope and decisions
+
+Implement every script primitive described in the supplied Claude dynamic-workflow reference: `agent`, `parallel`, `pipeline`, `phase`, `log`, `args`, `budget`, and nested `workflow`. Include the supporting launch, discovery, persistence, inspection, pause, stop, individual-agent restart, editable replay, structured output, worktree, and progress contracts. These are milestones of one complete feature, not optional primitives to defer indefinitely.
+
+Keep orchestration in plain JavaScript and agent execution in DevSpace's existing manager and adapters. The host authors or selects the script and interprets its final result. DevSpace executes the program, enforces authority and resource limits, and makes every child invocation inspectable.
+
+Preserve Claude-shaped script names and syntax. `agentType` resolves a DevSpace profile or built-in provider; it does not mean a Claude-only subagent registry. Model and effort strings remain provider-specific. Default models come from DevSpace configuration and profiles, not an assumption about the remote host's model.
+
+Compatibility means the portable script contract and workflow behavior. Anthropic account billing, slash-menu presentation, keyword highlighting, private cloud infrastructure, and access to a host's authenticated tools cannot be implemented universally by a local MCP server. Expose equivalent capabilities through DevSpace's own execution and presentation boundaries. Do not claim a harness capability that its adapter cannot establish.
+
+The official docs confirm the main script surface and lifecycle. The supplied gist also specifies `budget`, nested `workflow`, and detailed combinator semantics. Treat that union as the requested DevSpace contract, version it as `devspace-workflow/v1`, and maintain a conformance suite. Exact equivalence to undocumented Anthropic internals is not asserted. [Official workflows](https://code.claude.com/docs/en/workflows), [supplied reference](https://gist.github.com/Waishnav/38801adec1580aa689426ba075490670).
+
+## 2. Existing foundation and integration points
+
+The current model-facing route is workspace shell → `devspace agents` → `LocalAgentClient` → private daemon → `LocalAgentManager` → `LocalAgentRuntimePool` → driver. MCP workspace opening publishes agent discovery and instructions; it does not currently register a complete agent-management tool family.
+
+Reuse:
+
+- `src/local-agent-manager.ts`: target resolution, logical agents, turn lifecycle, scoped lookup, wait.
+- `src/local-agent-store.ts`: durable agents and turns, typed errors, continuation identity.
+- `src/local-agent-runtime.ts` and provider adapters: harness-specific invocation.
+- `src/local-agent-daemon*.ts`: one execution owner per state directory, authenticated local IPC.
+- `src/workspaces.ts`, `src/workspace-store.ts`, `src/git-worktrees.ts`: workspace identity and managed worktrees.
+- `src/db/*`: SQLite, migrations, permissions, transactions.
+- `src/local-agent-profiles.ts` and `src/local-agent-targets.ts`: existing profiles and provider defaults.
+
+Required extensions:
+
+- Individual turn cancellation, structured output, usage, optional progress and permission events.
+- Persist effective write authority and resolved invocation settings; a continuation cannot accidentally regain the default `allowed` authority.
+- Add a shared admission scheduler. The runtime pool is a resource cache, not a concurrency limiter.
+- Associate workflow steps with exact logical agents and turns.
+- Count live/paused workflows during daemon idle shutdown and configuration replacement.
+- Resolve stored managed workspaces using their validated managed root and source ownership. Do not force their path through checkout-only allowed roots, and do not bypass containment.
+
+## 3. Architecture
+
+```text
+MCP host / local CLI
+        │
+        ▼
+Workflow service in existing daemon ─── SQLite run/step/event/usage records
+        │                                   ▲
+        ├── registry + source validation     │
+        ├── lifecycle + replay driver ───────┘
+        ├── bounded interpreter worker
+        │       └── QuickJS guest: JS + eight primitives
+        └── validated agent bridge
+                └── shared scheduler
+                        └── LocalAgentManager
+                                └── current harness drivers
+```
+
+One interpreter worker per active root run; nested scripts use separately bounded workers admitted through a shared nested-execution limiter. They share the root controller, workflow journal, agent admission limits, and token budget. Each guest has its own heap and CPU ceilings. Parked runs without live interpreter state recover through their journal. No second daemon, broker, distributed leases, graph DSL, or orchestration model is needed.
+
+Use ordinary QuickJS with deferred promises. The bridge returns guest promises immediately and resolves them when daemon operations complete. Explicitly pump pending jobs in bounded batches after each delivery. Configure guest heap/stack limits and an interrupt handler. A worker watchdog provides an independent termination mechanism. [QuickJS documentation](https://github.com/justjake/quickjs-emscripten).
+
+QuickJS is the guest-code boundary; a Node worker is for responsiveness and termination, not an OS security sandbox. Do not evaluate guest source with Node `eval`, `Function`, or `vm`. The worker wrapper, parser, and validator are trusted application code and must also have bounded inputs and watchdogs.
+
+## 4. Common data and naming
+
+The declarations below describe public contracts; scripts themselves are JavaScript, not TypeScript.
+
+```ts
+type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+type JsonObject = { [key: string]: JsonValue };
+type JsonSchema = JsonObject | boolean;
+type RunId = string;   // generated wf_... opaque identifier
+type StepId = string;  // generated wfs_... opaque identifier
+
+interface WorkflowError {
+  code: string;
+  message: string;
+  layer: "script" | "workflow" | "workspace" | "adapter" | "provider";
+  retryable: boolean;
+  runId?: RunId;
+  stepId?: StepId;
+  agentId?: string;
+  provider?: string;
+  location?: { line: number; column: number };
+}
+```
+
+JSON numbers must be finite. Reject cycles, BigInt, functions, symbols, accessors, and unsupported objects at crossings that require JSON. Do not silently turn `NaN` into `null`, drop undefined properties, execute getters or user `toJSON`, or stringify errors as `{}`. Top-level `return;` is normalized to JSON `null` and recorded as an omitted result; absent launch `args` remains guest `undefined`.
+
+Use camelCase in scripts, daemon records, and TypeScript. MCP outer parameters follow the existing `workspace_id` convention. MCP source selection uses `script_path` and `resume_from_run_id`; internal requests use `scriptPath` and `resumeFromRunId`. Generate transport validation from one schema definition and test what `tools/list` actually exposes.
+
+For direct local CLI use without an injected workspace ID, resolve/register the current checkout in the workspace store and allocate a stable workspace identity before creating a run. Preserve the distinction between local-user authority and remote MCP allowed-root authority in the authenticated service context. A guest or remote request cannot obtain local-user authority by omitting an ID.
+
+### Configuration schema
+
+```ts
+interface WorkflowsConfig {
+  enabled: boolean;
+  instructions: "on-demand" | "preload";
+  defaultAgentType?: string;
+  maxConcurrentAgents: number;
+  maxConcurrentRuns: number;
+  maxAgentsPerRun: number;
+  maxAttemptsPerRun: number;
+  defaultOutputTokenBudget?: number;
+  maxOutputTokenBudget?: number;
+  requireWorktreesForConcurrentWrites: boolean;
+  maxUsageLimitWaits: number;
+  maxUsageLimitWaitMs: number;
+  limits: {
+    scriptBytes: number; argsBytes: number; promptBytes: number;
+    schemaBytes: number; schemaDepth: number;
+    agentResultBytes: number; runResultBytes: number;
+    guestHeapBytes: number; guestStackBytes: number;
+    guestSliceMs: number; guestTotalCpuMs: number; runActiveMs: number;
+    logMessageBytes: number; logTotalBytes: number; eventsPerRun: number;
+  };
+}
+```
+
+Use strict Zod objects, positive safe integers with implementation maximums, and defaults from the limits table. Persist the effective configuration per run. Script metadata cannot override these values. Configuration changes affect new work; disabling execution prevents new dispatches, while lowering a limit does not retroactively erase running attempts or recorded results.
+
+Add optional `writeMode` to user-owned agent profiles and their schema, interpreted only as a restriction on inherited run authority. Effective authority is the intersection of host/workspace policy, operator configuration, run snapshot, and profile restriction. Do not interpret prose such as 'read-only reviewer' as a permission setting. A profile cannot broaden authority by naming `full_access`.
+
+## 5. Script format and metadata
+
+```js
+export const meta = {
+  name: 'review-changes',
+  description: 'Review changed files and independently verify findings',
+  whenToUse: 'When a change needs review across many files',
+  phases: [
+    { title: 'Review', detail: 'Find possible defects' },
+    { title: 'Verify', detail: 'Check the evidence' },
+  ],
+}
+
+// Ordinary JavaScript, with top-level await and return.
+const results = await pipeline(args.files, file => agent(`Review ${file}`))
+return results
+```
+
+```ts
+interface WorkflowMeta {
+  name: string;        // 1..128 characters; kebab-case local name
+  description: string; // 1..2,000 characters
+  whenToUse?: string;  // up to 2,000 characters
+  phases?: Array<{
+    title: string;     // 1..200 characters, unique within this metadata block
+    detail?: string;  // up to 2,000 characters
+    model?: string;   // opaque provider model identifier
+  }>;
+}
+```
+
+Parser rules:
+
+1. Permit comments and whitespace before the first statement.
+2. Require that statement to be a single `export const meta = { ... }` declaration.
+3. Decode its AST as literal data: object, array, string, finite numeric, boolean, and null literals only. Reject calls, identifiers as values, computed keys, spreads, getters, methods, regex literals, duplicate keys, and interpolated templates.
+4. Permit ordinary property-name syntax such as `name:`. Reject prototype-sensitive metadata keys rather than assigning them into ordinary objects.
+5. Validate the decoded metadata and reject other module exports and all import declarations/expressions.
+6. Remove only the metadata statement by AST offsets, preserving newlines; wrap the body in an async function inside QuickJS. Map runtime errors back to original source lines.
+7. Keep `meta` available as frozen data in the guest if the body references it.
+
+Use TypeScript AST with a pinned ECMAScript grammar compatible with the chosen QuickJS build, module parsing, top-level return enabled, and location tracking. Do not split source with regex or execute metadata to discover it. [TypeScript AST parser](https://github.com/acornjs/acorn).
+
+The guest has normal JS collections, promises, expressions, and control flow. It has no `process`, `require`, host filesystem/network functions, subprocesses, timers, module loader, credentials, or daemon client. Deny dynamic imports both during source validation and at the interpreter loader boundary. Code constructed inside the guest cannot gain a host loader.
+
+Make nondeterministic clock/random APIs unavailable: `Date.now()`, zero-argument Date construction, Date-as-function, `Math.random()`, and equivalent exposed entropy sources. Allow explicit fixed dates. Pin timezone/locale-dependent behavior or reject locale-dependent operations; do not let replay depend on the machine's current timezone. Freeze protected intrinsic methods so scripts cannot restore prohibited APIs. Input timestamps and seeds belong in `args`.
+
+## 6. Full primitive contracts
+
+### 6.1 `agent(prompt, options)`
+
+```ts
+interface AgentOptions {
+  label?: string;                  // 1..200 characters
+  phase?: string;                  // 1..200 characters
+  schema?: JsonSchema;
+  model?: string;                  // nonempty opaque provider value
+  effort?: string;                 // nonempty opaque provider value
+  isolation?: "worktree";
+  agentType?: string;              // DevSpace profile or provider target
+}
+
+declare function agent(
+  prompt: string,
+  options?: AgentOptions,
+): Promise<string | JsonValue | null>;
+```
+
+Prompt must contain non-whitespace text and remain within the configured byte bound. Options are strict: unknown fields fail validation. Copy and validate options when invoked; later mutations must not change a queued request.
+
+Semantics:
+
+- Every call creates a fresh logical DevSpace agent. Structured-output correction continues that agent; it does not create an unrelated worker.
+- Resolve to final text without `schema`, validated JSON with `schema`, or `null` for a skipped, individually stopped, policy-blocked, or terminally failed agent. The journal retains the distinct outcome and original safe error.
+- Invalid options, unavailable target/configuration, invalid schema, and exhausted schema correction reject with a typed error. Combinators convert task-level rejection to a null slot as specified below.
+- A run-level stop or interpreter failure cannot be neutralized by catching an agent rejection: the daemon independently closes admission and terminates/parks the run.
+- The worker receives the self-contained task plus selected profile and resolved workspace instructions. It does not inherit an unavailable parent transcript.
+- Authority is inherited from the run and can only be narrowed. Script options cannot request `full_access`, add roots, or inject environment variables.
+- The return value stays compact. IDs, tool events, usage, worktree references, and raw provider diagnostics are inspectable through step details.
+
+Agent target precedence: call `agentType` → launch `agentType` → configured workflow default. If unresolved, fail clearly. Existing profile resolution precedes raw provider lookup. No arbitrary choice of the first installed provider.
+
+Model precedence: call `model` → matching phase metadata `model` → launch `model` → selected profile `model` → provider default. Effort: call → launch → profile → provider default. An incompatible model/effort is an explicit error; never silently translate another provider's naming or substitute a different provider. Freeze effective values in the step record. A phase's model matters only when the call has not provided its own model.
+
+### 6.2 `parallel(tasks)`
+
+```ts
+declare function parallel<T>(
+  tasks: Array<() => T | Promise<T>>,
+): Promise<Array<T | null>>;
+```
+
+Validate the full input before invoking any thunk. Require a dense array of functions, length 0..4,096. Call thunks in input order, launch their work concurrently, await every settlement, and preserve input order in results. Synchronous throws and rejected task promises yield `null` at that position. Successful `false`, `0`, empty string, and `null` values are preserved.
+
+Empty input resolves to `[]`. Invalid input rejects; the statement that the combinator swallows failures applies to valid task execution, not its own argument validation or root termination. Record task failures with combinator index and source location. A failure must remain visible even if the script filters nulls.
+
+The helper never owns a scheduler slot. Each underlying agent does. Nested `parallel` calls use the same root admission limits.
+
+### 6.3 `pipeline(items, ...stages)`
+
+```ts
+type PipelineStage = (
+  previous: unknown,
+  originalItem: unknown,
+  index: number,
+) => unknown | Promise<unknown>;
+
+declare function pipeline(
+  items: unknown[],
+  ...stages: PipelineStage[]
+): Promise<unknown[]>;
+```
+
+Require a dense items array of length 0..4,096 and at least one callable stage. Validate everything before invoking a stage. For item `items[i]`, call stage 1 with `(items[i], items[i], i)` and later stages with `(previousResult, items[i], i)`.
+
+Different items advance independently. There is no barrier between stages. Results retain original item ordering; intermediate arrays are not implicitly flattened. Pure transformations are allowed and consume no agent slot. A thrown/rejected stage makes that item's final slot `null` and skips its remaining stages.
+
+A successfully returned `null` is an ordinary stage value and is passed onward; only a failure skips the chain. This distinction must be tested because `agent()` can resolve to `null`. Authors who want to stop on null explicitly branch in their next stage.
+
+`originalItem` is the original JS reference inside the guest. It is not automatically cloned per stage. Guest state sharing remains ordinary JavaScript, with concurrency pitfalls documented.
+
+### 6.4 `phase(title)`
+
+```ts
+declare function phase(title: string): void;
+```
+
+Validate 1..200 characters. Set the default phase for subsequent calls in the current script context and emit a phase event. It introduces no barrier, transaction, worktree, or budget scope. Match metadata titles exactly; unknown titles create dynamic groups.
+
+Capture the phase at agent invocation, not at queue dispatch. Per-call `options.phase` wins. Concurrent callbacks share this script-local default; use explicit phases in those callbacks. Nested workflows have their own phase default, so child code cannot overwrite the parent's default.
+
+### 6.5 `log(message)`
+
+```ts
+declare function log(message: string): void;
+```
+
+Emit a bounded structured progress event with run/child context and timestamp supplied by the daemon. Strings only; at most 8 KiB each by default. No implicit console dumping or provider-secret serialization. Preserve order within a script. Limit total log bytes and event count; report an explicit quota event rather than silently dropping messages.
+
+Replay must not duplicate previous user-visible log events. A replay view links to original events; genuinely new execution appends new events.
+
+### 6.6 `args`
+
+```ts
+declare const args: JsonValue | undefined;
+```
+
+Absent input becomes `undefined`; explicit JSON null remains null. Objects/arrays arrive as objects/arrays, never double-encoded JSON strings. Clone the persisted launch arguments into each script context. Scripts may mutate their local copy, but cannot mutate the durable launch record or another context. Nested calls receive only their explicit arguments.
+
+### 6.7 `budget`
+
+```ts
+declare const budget: {
+  readonly total: number | null;
+  spent(): number;
+  remaining(): number; // Infinity only inside JS when total is null
+};
+```
+
+Unit: provider-reported output tokens, with adapter definitions stating whether reasoning tokens are already included. Input/cache counts are separately observable and are not added to `spent()`. Do not derive output usage from final text length.
+
+Root run, nested workflows, structured-output corrections, retries, and individual restarts share one ledger. Replay cache hits add no new usage. A resume lineage retains prior real spending; editing the script is not a budget reset.
+
+`spent()` reads the latest accounted usage delivered to the interpreter. `remaining()` is `max(0, total - spent)` or Infinity when unlimited. Return getters are synchronous, so their observations must be journaled for deterministic replay. The daemon performs authoritative admission checks even if the interpreter has a slightly older snapshot.
+
+Check budget at invocation and again before dispatch. Once accounted spending reaches the limit, no further provider attempts start, including queued work. Already-running attempts can finish and overshoot. This is a dispatch budget, not a guaranteed maximum bill. Do not market it as one.
+
+Unknown usage cannot be represented as zero. If any executed target cannot provide reliable usage, `spent()`/`remaining()` throw `USAGE_UNAVAILABLE`; `total` remains readable. A finite-budget run rejects an unmetered target before dispatch. Unlimited runs can use that target, with usage marked incomplete in status. A failed attempt with unknown incurred usage similarly makes the ledger incomplete and blocks further finite-budget dispatch until reconciled.
+
+Host-session budget sharing is optional integration, not assumed MCP functionality. The public launch surface exposes only `outputTokenBudget`. A trusted host adapter may internally bind multiple root runs to one ledger and report external host usage with deduplication IDs; guest scripts cannot create these reports. Without that integration, budget scope is the root workflow lineage, explicitly reported in status.
+
+### 6.8 `workflow(reference, childArgs)`
+
+```ts
+declare function workflow(
+  reference: string | { scriptPath: string },
+  childArgs?: JsonValue,
+): Promise<JsonValue>;
+```
+
+String resolves a registered workflow name. Object is strict and contains only `scriptPath`. Resolve paths relative to the parent script's source directory when it has one, otherwise its workspace root; then apply the same approved-root and registry rules as launch.
+
+Root depth is 0; child depth is 1. Calling `workflow` from a child fails with `NESTING_LIMIT`. Child script, metadata, arguments, and source hash are persisted as an invocation record. Child execution shares root concurrency, total agent/attempt counters, budget, stop signal, deadline, and maximum authority. It cannot raise any limit.
+
+Use a separate guest context so top-level variables and default phases do not collide. Represent child phases under a child group in progress. The parent awaits the child's JSON return value. Resolution, syntax, and runtime failures reject the nested call and remain inspectable. Child invocations themselves have a root-wide count cap so a loop over zero-agent children cannot evade resource bounds.
+
+## 7. Launch and management schemas
+
+### 7.1 Launch
+
+```ts
+interface RunWorkflowInput {
+  workspace_id: string;
+  script?: string;
+  name?: string;
+  scriptPath?: string;
+  args?: JsonValue;
+  resumeFromRunId?: RunId;
+  agentType?: string;
+  model?: string;
+  effort?: string;
+  outputTokenBudget?: number; // positive safe integer
+}
+
+interface RunWorkflowReceipt {
+  runId: RunId;
+  status: "running";
+  workflowName: string;
+  scriptPath: string;       // readable editable copy; running snapshot is immutable
+  transcriptDir: string;    // authorized export directory, not raw stateDir access
+  revision: number;
+  resumedFromRunId?: RunId;
+  warnings?: Array<{ code: string; message: string }>;
+}
+```
+
+At least one source is required. Preserve reference source precedence: `scriptPath` > `name` > `script`. If several are supplied, expose which was selected in diagnostics; never merge them. Keep title/description exclusively in `meta`; do not introduce ignored duplicate fields.
+
+Validate all transport fields, source bounds, source paths, metadata, syntax, baseline target, permissions, and resume eligibility before returning a receipt. A syntax error is a failed launch, not a success-shaped background task. Dynamic call-specific targets/schemas are validated when invoked.
+
+Create the durable run before starting its interpreter. Return after acceptance, never wait for the script's final result. Do not return daemon endpoint, credentials, provider session IDs, or internal worker routing.
+
+CLI `run <script-path>` and `run --name <name>` map to the same service. Accept JSON arguments via a file or stdin to avoid shell-quoting mistakes. CLI uses current-workspace resolution and supplies a validated internal scope; MCP callers must supply `workspace_id`.
+
+### 7.2 Read and control
+
+```ts
+type WorkflowState =
+  | "starting" | "running" | "pausing" | "paused"
+  | "waiting_for_permission" | "waiting_for_usage"
+  | "stopping" | "stopped" | "completed" | "failed"
+  | "recovery_required";
+
+interface WorkflowRef { workspace_id: string; runId: RunId }
+
+interface GetWorkflowInput extends WorkflowRef {
+  afterRevision?: number;
+  stepId?: StepId; // request one detailed child; default is compact summary
+}
+
+interface WaitWorkflowInput extends WorkflowRef {
+  afterRevision?: number;
+  timeoutMs?: number; // 0..60,000; default 30,000
+}
+
+type ControlWorkflowInput = WorkflowRef & (
+  | { action: "pause" | "resume" | "stop" }
+  | { action: "stop_agent" | "restart_agent"; stepId: StepId }
+);
+
+interface ListWorkflowsInput {
+  workspace_id: string;
+  kind: "definitions" | "runs";
+  cursor?: string;
+  limit?: number; // 1..100, default 20
+}
+
+interface SaveWorkflowInput extends WorkflowRef {
+  name: string;
+  location: "project" | "user";
+  replace?: boolean; // false by default; explicit conflict handling
+}
+```
+
+MCP names: `run_workflow`, `get_workflow`, `wait_workflow`, `control_workflow`, `list_workflows`, `save_workflow`. Register identical contracts across this checkout's actual `claude` and `codex` tool modes; do not invent extra modes from historical documentation. Tools disappear when workflows are disabled. Continue supporting the equivalent CLI through existing workspace shell tools.
+
+`wait_workflow` returns on terminal state, attention-required state, a newer revision, or timeout. Without `afterRevision`, capture the current revision on entry. It never cancels execution when the connection closes. Notifications are optional hints; durable read/wait is the source of truth. A host reconnect can always retrieve results.
+
+### 7.3 Status output
+
+```ts
+interface WorkflowSnapshot {
+  runId: RunId;
+  workflowName: string;
+  state: WorkflowState;
+  revision: number;
+  counts: {
+    requested: number; queued: number; running: number;
+    completed: number; failed: number; stopped: number; cached: number;
+  };
+  usage: {
+    outputTokens: number | null;
+    knownOutputTokens: number;
+    complete: boolean;
+    budgetTotal: number | null;
+    remaining: number | null; // null if unlimited or unknown; never wire Infinity
+    scope: "workflow_lineage" | "host_session";
+  };
+  phases: Array<{
+    id: string; title: string; parentId?: string;
+    running: number; completed: number; failed: number;
+  }>;
+  result?: JsonValue;
+  resultArtifact?: { id: string; path: string; bytes: number };
+  error?: WorkflowError;
+  pauseReason?: string;
+  nextEligibleAt?: string;
+  partial: boolean;
+  warnings: Array<{ code: string; message: string }>;
+  events?: WorkflowEvent[];
+  nextCursor?: string;
+}
+```
+
+`completed` means the script returned, not that every child succeeded. Set `partial` when any child failed/stopped or unresolved coverage was reported. Return both summary counters and the script result so filtering cannot hide failed execution. Large results are persisted intact and exposed as artifacts rather than silently truncated.
+
+### 7.4 Step and event details
+
+```ts
+type StepState =
+  | "queued" | "starting" | "running" | "waiting_for_permission"
+  | "waiting_for_usage" | "completed" | "failed" | "stopped"
+  | "cached" | "uncertain";
+
+interface WorkflowStepSnapshot {
+  id: StepId;
+  runId: RunId;
+  parentStepId?: StepId;
+  kind: "agent" | "workflow";
+  state: StepState;
+  callSequence: number;
+  phase?: string;
+  label?: string;
+  agentId?: string;
+  agentType?: string;
+  provider?: string;
+  model?: string;
+  effort?: string;
+  workspaceId: string;
+  prompt?: string; // detailed scoped response only
+  attempts: number;
+  output?: JsonValue;
+  outputArtifact?: { id: string; path: string; bytes: number };
+  error?: WorkflowError;
+  cachedFromStepId?: StepId;
+  worktree?: { workspaceId: string; path: string; baseSha: string; changed: boolean };
+}
+
+type WorkflowEvent = {
+  runId: RunId;
+  sequence: number;
+  timestamp: string;
+  stepId?: StepId;
+} & (
+  | { type: "run_state"; state: WorkflowState; reason?: string }
+  | { type: "step_state"; state: StepState; attemptId?: string }
+  | { type: "phase"; title: string; parentGroupId?: string }
+  | { type: "log"; message: string }
+  | { type: "usage"; attemptId: string; outputTokens: number; complete: boolean }
+  | { type: "tool"; toolCallId: string; name: string; state: "started" | "completed" | "failed"; summary?: string }
+  | { type: "warning"; code: string; message: string }
+  | { type: "error"; error: WorkflowError }
+  | { type: "result"; artifactId?: string }
+);
+```
+
+Internal replay records additionally carry request/delivery IDs and budget observations; public events omit routing internals. Bound tool summaries and keep full inputs/outputs in protected detail artifacts. A `final_only` adapter exposes its final step result without manufacturing intermediate tool events.
+
+Permission events use an internal `PermissionRequest` containing a request ID, exact step/attempt identity, safe action description, and allowed decisions. Resolution requires an authenticated user-approval channel bound to that request, not an arbitrary script response or a free-form 'approved' string. A headless host without that channel receives an actionable waiting/failure state; configured operator policy may already authorize the action.
+
+Function-taking combinators are guest JavaScript APIs, not JSON-RPC schemas: validate their callable arguments inside the guest. Only data crossing the bridge receives JSON Schema/Zod transport validation. Publish declaration files and examples for script authoring alongside generated MCP JSON schemas.
+
+## 8. Structured-output execution
+
+Use a real JSON Schema validator. Support Draft 7 and 2020-12 with distinct validator instances, defaulting to 2020-12 if `$schema` is omitted. Document the supported dialects and annotation policy. Local `$ref` within the submitted schema is supported; disable network/file schema loading and arbitrary custom keywords. No coercion, inserted defaults, or additional-property removal.
+
+Ajv is the proposed implementation. Its documentation explicitly treats untrusted schemas as a resource risk. Compile and validate in a disposable validation worker with byte/depth limits, an independent time limit, bounded cache, and memory limits, never synchronously on the daemon's event loop. [Ajv security](https://ajv.js.org/security.html).
+
+Do not confuse schema validity with satisfiability. Add only provably sound contradiction checks: for example, a required object key that is neither declared nor admitted by any pattern when `additionalProperties: false` at that same schema node. Also check obvious impossible bounds. Do not reject valid `allOf`/conditional/recursive schemas using a naive global heuristic.
+
+Dispatch algorithm:
+
+1. Compile and validate the schema before starting this agent.
+2. Resolve adapter capabilities for the actual target/model.
+3. Ask the adapter for native structured output if it supports this schema dialect/subset; otherwise instruct the agent to return JSON and validate centrally.
+4. Validate native output too. For text fallback, parse either the entire response as JSON or one complete JSON-fenced response; never extract an arbitrary brace-delimited substring from prose.
+5. On mismatch, continue the same agent with bounded validation errors and a request to format its existing result. Up to five total output attempts by default, including the initial answer.
+6. Correction turns use no tools when supported; otherwise enforce read-only tools through the adapter. If neither can be enforced, fail instead of allowing a formatting retry to repeat mutations.
+7. Every correction is a separate durable turn/attempt, consumes actual budget, and remains part of one workflow step.
+8. On exhaustion reject with `SCHEMA_VALIDATION_FAILED`, retaining the last bounded validation error and raw-output artifact.
+
+Successful schema output may itself be JSON null; the step status distinguishes that from a failed-agent null return.
+
+## 9. Scheduling, limits, and completion ownership
+
+Place admission above `LocalAgentManager.begin` and below all workflow bridges. Use a daemon-global ceiling and per-root ceiling; optionally constrain a provider where its runtime needs a smaller limit. Schedule eligible root queues fairly. A paused root cannot occupy the head of the global queue indefinitely.
+
+Proposed defaults, to be verified with load tests:
+
+| Bound | Default |
+|---|---:|
+| Active agent turns per root | `max(1, min(16, availableParallelism() - 2))` |
+| Active agent turns across daemon | 16 |
+| Agent invocations per root execution | 1,000, shared with nested scripts |
+| Provider turns/attempts per root execution | 5,000, including repair/restart |
+| Items per combinator | 4,096 |
+| Nested depth | 1 |
+| Nested invocations per root | 1,000 |
+| Active interpreter roots | 4 |
+| Script source | 256 KiB |
+| Launch arguments / individual agent prompt | 1 MiB each |
+| Schema size / structural depth | 128 KiB / 64 |
+| Individual structured result | 4 MiB |
+| Root final result | 16 MiB |
+| Guest heap per root | 64 MiB |
+| Guest stack per context | 1 MiB |
+| Continuous guest execution slice | 1 second watchdog ceiling |
+| Cumulative guest execution | 30 seconds, excluding provider wait |
+| Wall time | 6 hours of active elapsed run time |
+| Logs | 8 KiB/message, 1 MiB/root |
+| Durable events | 100,000/root; terminal transition has reserved capacity |
+| Structured-output attempts | 5 total |
+
+These are DevSpace resource-policy proposals, not claims about exact Anthropic constants. Time suspended for a deliberate pause or rate-limit wait is separately tracked and bounded by a retention/wait policy. Limit overrides belong in trusted configuration, not in arbitrary script metadata. Caller-supplied budgets can narrow configured ceilings but cannot enlarge them.
+
+Count invocations at validated call admission, before awaiting provider startup. Count cache hits in logical invocation counts, but not in active slots or new usage. Retry/restart cannot reset attempt caps. A new run created by explicit resume has a new execution counter and retained lineage spending; retain lifetime audit totals separately.
+
+The daemon rechecks current enablement and scope before every live dispatch. Profile content used by a run is frozen at resolution for consistency; disabling a provider remains effective immediately at the admission boundary.
+
+Unawaited work is still owned by the run. When the body returns, enter an internal settling phase and wait for all accepted child operations; no workflow may report terminal completion while owned agents still run. On a body exception or hard deadline, stop admission and cancel owned work before finalizing. `Promise.race` does not implicitly abandon or cancel losing agents.
+
+Limit failures reject subsequent calls and set an authoritative admission-closed reason. Script code may catch an agent-count or budget failure and return a partial report, but cannot reopen admission. Infinite loops are stopped by interpreter limits independently of agent limits.
+
+## 10. Agent-adapter contract
+
+Extend existing types instead of replacing the agent system:
+
+```ts
+interface AgentCapabilities {
+  cancellation: "turn" | "dedicated_process" | "unsupported";
+  structuredOutput: "native" | "validated_text";
+  usage: "streaming" | "final" | "unavailable";
+  correctionAuthority: "no_tools" | "read_only" | "unsupported";
+  permissionRequests: "interactive" | "preconfigured";
+  progress: "tools_and_text" | "text" | "final_only";
+}
+
+interface AgentUsageUpdate {
+  attemptId: string;
+  sequence: number;
+  outputTokens: number; // cumulative within this attempt, not a delta
+  inputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  reasoningTokens?: number; // informational; do not double-add
+  final: boolean;
+}
+
+interface AgentRunControl {
+  signal: AbortSignal; // per turn, not shared runtime
+}
+
+// Add to LocalAgentRunInput:
+//   outputSchema?: JsonSchema
+//   attemptId: string
+//   toolPolicy?: "normal" | "read_only" | "none"
+// Add to result:
+//   structuredOutput?: JsonValue
+//   usage?: AgentUsageUpdate
+// Add to callbacks:
+//   onUsage?, onProgress?, onPermissionRequest?
+// Pass AgentRunControl separately to runtime.run().
+```
+
+Capabilities are resolved by adapter/version/model where necessary. They are operational checks, not knobs the host model must manage. Profiles stay the model's primary choice.
+
+Implementation targets by adapter (verify exact installed protocol fields before coding):
+
+| Harness | Cancellation work | Output/accounting work |
+|---|---|---|
+| Codex app-server | Address interruption to the specific thread and turn | Consume supported output-schema and usage events; retain thread ID |
+| Claude SDK | Interrupt the specific query/turn | Native structured output/result usage where exposed |
+| OpenCode SDK | Abort the specific server-side session; aborting HTTP alone is insufficient | Consume structured result/token fields from session messages |
+| Pi SDK | Abort the particular AgentSession | Validate final text or a configured structured tool result; aggregate model usage |
+| Cursor ACP | Session-scoped protocol cancellation | Capability negotiation; JSON fallback; explicit usage support check |
+| Copilot ACP | Session-scoped protocol cancellation | Same common ACP contract, independent capability tests |
+| Grok ACP | Session-scoped protocol cancellation | Preserve existing Grok model/effort mapping; probe actual usage support |
+
+These are adapter implementation requirements, not a claim that all current adapters already expose every field. If a provider lacks reliable per-session cancellation, use a runtime dedicated to that workflow agent so it can be stopped without affecting siblings. If even that cannot establish remote termination, keep the step unresolved/recovery-required and prevent replacement dispatch until reconciled. Never claim that disconnecting a client proves a remote turn stopped.
+
+Add `LocalAgentManager.stop(agentId, turnId, scope)` and a matching authenticated IPC method. Stop the captured turn; a delayed cancellation must never stop a newer continuation. Persist terminal completion versus cancellation with a compare-and-set winner.
+
+Keep provider-native nested-agent spawning from bypassing DevSpace limits: disable it for workflow children where supported. Otherwise count/observe descendants if the protocol exposes them and report the limitation; a strict bounded-fleet configuration must reject targets that can autonomously spawn unaccounted descendants. This applies to shell-mediated reentry too: cooperative provenance can enforce DevSpace calls, but unrestricted shell is not a sandbox and cannot guarantee containment of arbitrary external agent launches.
+
+## 11. Persistence and transaction boundaries
+
+Reuse the existing SQLite database. Add migrations after the current version 8. Share the daemon's database handle between agent and workflow stores where a transaction spans both; separate connections cannot provide one atomic unit of work.
+
+Logical table definitions (all IDs and foreign keys scoped and validated by the service):
+
+```text
+workflow_runs
+  id TEXT PRIMARY KEY
+  workspace_id TEXT NOT NULL
+  workspace_root TEXT NOT NULL
+  lineage_id TEXT NOT NULL
+  budget_id TEXT NOT NULL
+  resumed_from_run_id TEXT NULL
+  state TEXT NOT NULL
+  meta_json TEXT NOT NULL
+  script_source TEXT NOT NULL
+  script_hash TEXT NOT NULL
+  source_path TEXT NULL
+  args_present INTEGER NOT NULL
+  args_json TEXT NULL
+  defaults_json TEXT NOT NULL
+  policy_json TEXT NOT NULL
+  runtime_version TEXT NOT NULL
+  revision INTEGER NOT NULL
+  execution_generation INTEGER NOT NULL
+  result_json TEXT NULL
+  result_artifact_id TEXT NULL
+  error_json TEXT NULL
+  pause_reason TEXT NULL
+  next_eligible_at TEXT NULL
+  created_at / updated_at / finished_at TEXT
+
+workflow_steps
+  id TEXT PRIMARY KEY
+  run_id TEXT NOT NULL REFERENCES workflow_runs(id)
+  parent_step_id TEXT NULL REFERENCES workflow_steps(id)
+  kind TEXT NOT NULL                    -- agent | workflow
+  call_sequence INTEGER NOT NULL        -- root-wide monotonic order
+  logical_path TEXT NOT NULL            -- child/combinator diagnostic identity
+  request_hash TEXT NOT NULL
+  request_json TEXT NOT NULL            -- effective frozen request
+  phase TEXT NULL
+  label TEXT NULL
+  status TEXT NOT NULL
+  agent_id TEXT NULL
+  workspace_id TEXT NOT NULL
+  cached_from_step_id TEXT NULL
+  output_json TEXT NULL
+  error_json TEXT NULL
+  delivery_sequence INTEGER NULL
+  created_at / updated_at / finished_at TEXT
+  UNIQUE(run_id, call_sequence)
+
+workflow_attempts
+  id TEXT PRIMARY KEY
+  step_id TEXT NOT NULL REFERENCES workflow_steps(id)
+  attempt_number INTEGER NOT NULL
+  agent_id TEXT NOT NULL
+  agent_turn_id INTEGER NOT NULL
+  reason TEXT NOT NULL                  -- initial | schema_repair | restart | retry
+  state TEXT NOT NULL
+  usage_sequence INTEGER NOT NULL DEFAULT 0
+  output_tokens INTEGER NULL
+  usage_complete INTEGER NOT NULL DEFAULT 0
+  error_json TEXT NULL
+  UNIQUE(step_id, attempt_number)
+  UNIQUE(agent_turn_id)
+
+workflow_events
+  run_id TEXT NOT NULL REFERENCES workflow_runs(id)
+  sequence INTEGER NOT NULL
+  step_id TEXT NULL
+  type TEXT NOT NULL
+  payload_json TEXT NOT NULL
+  created_at TEXT NOT NULL
+  PRIMARY KEY(run_id, sequence)
+
+workflow_budgets
+  id TEXT PRIMARY KEY                    -- root lineage or trusted host scope
+  total_output_tokens INTEGER NULL
+  known_output_tokens INTEGER NOT NULL
+  usage_complete INTEGER NOT NULL
+  revision INTEGER NOT NULL
+```
+
+Add budget ID linkage to runs and usage rows for trusted external reports only if host-session accounting is implemented. Within workflow-only accounting, attempts are the deduplication source of truth. Store provider session identity in the existing agent table, not in every workflow record.
+
+Use foreign keys, CHECK constraints for enum states/nonnegative counts, unique sequence constraints, and indices on `(workspace_id, updated_at)`, `(run_id, status)`, and `(step_id, attempt_number)`. The exact state enums are shared with validation code. Add workflow association/effective authority fields to existing agent turns where needed.
+
+Atomic boundaries:
+
+1. Launch: run snapshot + initial event.
+2. Dispatch preparation: queued step + logical agent + initial turn + attempt association. Persist before contacting a provider.
+3. Provider identity callback: save continuation ID before further work, preserving the current awaited callback pattern.
+4. Attempt completion: agent turn outcome + attempt status + usage delta + step outcome + event + revision. Commit before delivering a guest promise result.
+5. Replay hit: new step links to old immutable output; no provider dispatch or usage increment.
+6. Control action: change generation/state + control event before signalling running code.
+
+Do not hold a database transaction across an await or provider call. Provider dispatch cannot be atomically committed with local SQLite. On the crash window after sending work but before recording its remote identity, mark the attempt uncertain; do not automatically resend it. No exactly-once side-effect claim.
+
+JSONL journals and agent transcripts are exports from canonical records, not a second mutable source of truth. Export by append sequence with rebuild support. Keep state-directory permissions private. If stronger power-loss durability is required, use a workflow database policy that changes SQLite synchronous settings deliberately and test it; the current `NORMAL` setting should not be described as a guarantee against every power-loss window.
+
+## 12. Interpreter/daemon bridge
+
+The interpreter receives a validated launch snapshot and an opaque run binding. It never receives the daemon authentication token. Bind all IPC messages to the worker instance and execution generation; reject late messages after stop/restart.
+
+```ts
+type GuestRequest = {
+  requestId: number;
+  generation: number;
+} & (
+  | { op: "agent"; prompt: string; options: AgentOptions }
+  | { op: "workflow"; reference: string | { scriptPath: string }; argsPresent: boolean; args?: JsonValue }
+  | { op: "phase"; title: string }
+  | { op: "log"; message: string }
+  | { op: "budget_read"; getter: "spent" | "remaining"; observationIndex: number }
+);
+
+type GuestReply = {
+  requestId: number;
+  generation: number;
+  deliverySequence: number;
+  budgetSnapshot: { total: number | null; knownSpent: number; complete: boolean };
+} & (
+  | { ok: true; value: JsonValue }
+  | { ok: false; error: WorkflowError }
+);
+```
+
+`budget_read` records an observation of the worker's already-delivered budget snapshot; it does not block synchronously waiting for the daemon. During replay, feed recorded observations to synchronous getters. Phase/log messages are buffered in order with bounded memory and persisted before any subsequent provider dispatch or terminal acknowledgement.
+
+The bridge validates message shape, byte size, sequence, generation, and policy again. Guest references are copied as data, not passed as host objects. Adapter results/errors are explicitly serialized. Message traffic is bounded; a script cannot queue unlimited unresolved RPC requests.
+
+Dispose guest value handles, pending deferred promises, contexts, and worker resources on every exit. Pump jobs with an instruction/time budget, including microtasks recursively spawning more microtasks. A never-settling promise with no outstanding accepted operations produces a stalled-script diagnostic; a total deadline remains the final bound.
+
+## 13. Editable replay and recovery
+
+The replay contract is explicit reuse of prior recorded observations, not proof that the working tree or external world has stayed unchanged.
+
+Each valid agent request gets a root-wide sequence before dispatch. Its hash covers prompt, supplied options including label/phase, effective profile content hash, provider, model, effort, output schema, effective authority, workspace identity, requested isolation/base snapshot, and relevant runtime contract version. Canonicalize object keys but preserve array order. Exclude credentials and ephemeral runtime handles.
+
+Do not include the whole new script hash in every call hash: changing only final aggregation should still reuse earlier calls. Keep script hashes in run/invocation records for provenance. Snapshot nested source and arguments; an edited nested body can replay matching internal calls, but cannot simply return the old whole-child output without inspecting its changed script. A nested boundary matches reference, child arguments, and inherited execution context; its source hash is provenance rather than an automatic whole-subtree cache key. Always execute the newly selected child body through the replay driver and compare its internal calls.
+
+Resume procedure:
+
+1. Resolve and authorize the source run in the same stored workspace scope. Require compatible runtime contract and existing journal.
+2. Reject if source agents may still be active. Obtain a serialized claim preventing simultaneous resumes of the same source generation.
+3. Create a new run with new source/args and a link to the prior run. Omitted resume args inherit prior args including presence/absence; explicit args replace them. Retain policy ceilings and spending lineage; authority never expands implicitly.
+4. Re-execute the new script in a fresh guest context. Match its requested calls against the prior successful prefix. Known failed/stopped/uncertain requests establish the earliest non-reusable boundary.
+5. Return saved results only for completed, matching calls before that boundary. At the first mismatch/new/failed call, switch permanently to live execution for the remainder. Do not opportunistically reuse later steps.
+6. Preserve the original outputs and errors. Record every replayed step's origin.
+
+Concurrency makes a prompt-only journal insufficient. Record request order, guest-visible promise-delivery order, rejection delivery, nested invocation boundaries, and budget getter observations. During replay, a driver releases cached completions in the recorded relative order when their requests exist. Run guest microtasks between deliveries as originally observed. Do not instantly resolve every cached promise: that can change `Promise.race`, pipeline fan-out order, and subsequent prompts.
+
+If edited code requests a different call, diverge explicitly. If replay is unable to satisfy a required recorded dependency and cannot safely establish divergence, return `REPLAY_DIVERGED` with location rather than hanging. Once live execution starts, continue pending reusable completions consistently, then record the new live schedule. Build specific conformance tests for overlapping pipelines and failures before implementing broad replay claims.
+
+Record workspace HEAD, mode, isolation snapshot, and a change summary at start/end. Report observed workspace changes on resume, but acknowledge that external files, ignored files, network state, and arbitrary shell effects cannot be fully fingerprinted. Callers needing fresh observations start a new run. Resume does not restore an entire filesystem or undo side effects.
+
+Daemon crash recovery first reconciles provider attempts. If a provider can establish a turn completed, recover its result. If still running, attach/observe or cancel through its supported API. If identity or status is uncertain, use `recovery_required`; never interpret that as permission to launch a duplicate writer. Runtime versions that cannot reattach must establish termination before replay.
+
+Persist completed steps so new MCP connections and daemon restarts can recover them. This extends scope beyond a host's transient conversation session without pretending to reproduce Anthropic cloud VM infrastructure.
+
+## 14. Lifecycle and controls
+
+```text
+starting → running → completed
+                  → pausing → paused → running
+                  → waiting_for_permission → running
+                  → waiting_for_usage → running
+                  → stopping → stopped
+                  → failed
+crash/uncertain provider state → recovery_required → explicit reconciliation/replay
+```
+
+Pause means stop admitting new provider attempts and stop delivering new guest completions. Active agents may finish; persist their results. Transition to paused after active owned turns settle. This is a safe boundary pause, not an assertion that every harness can suspend a model mid-generation. Resume continues the same live run when its interpreter exists; a parked/crashed interpreter uses recorded replay after reconciliation.
+
+Stop means close admission, reject queued work, signal every active child, terminate guest execution, and await cancellation acknowledgements. Remain `stopping` while any owned work is unconfirmed. Repeated stop is idempotent and may resend cancellation; it never expands to an unrelated shared runtime.
+
+Individual stop resolves that agent's promise to null, records a stopped step, and lets siblings continue. Individual restart is permitted only before the current step's result has been delivered to the script: cancel its captured attempt, wait for confirmed settlement, then start a fresh agent attempt for that same frozen task and keep the original guest promise pending. After delivery, reject restart with `STEP_ALREADY_DELIVERED`; use workflow replay to recompute dependent code. Charge every restart and keep an attempt history. Existing worktree edits remain visible; a restart does not silently reset or delete them.
+
+On uncaught script failure, record the original error first, stop children, and finish failed after cleanup. Cleanup errors are secondary diagnostics. On body success with failures swallowed by combinators, finish completed with `partial: true` and failure counts.
+
+At terminal state, export results and a compact completion event. Hosts may render a widget or consume plain structured output. No UI refresh or notification is required for correctness.
+
+## 15. Worktree isolation and write authority
+
+`isolation: 'worktree'` creates a managed child workspace using existing worktree code. Store root ownership, source workspace, base SHA, and created workspace ID on the step. Validate canonical containment and registered ownership on every operation.
+
+Existing creation uses a commit and records that the source was dirty; it does not copy all uncommitted work. The full workflow feature needs an explicit policy: support a committed base by default and an opt-in working-tree snapshot selected at launch through trusted workspace setup. Snapshot tracked changes and only approved untracked files using existing recovery facilities where applicable; never sweep ignored credentials/dependencies into it. Report which base was used.
+
+Several calls with no isolation can intentionally share a workspace, matching normal agent behavior. Expose authority and worktree guidance in authoring instructions; do not claim that a 'read-only' prompt is enforcement. Shared writable execution carries ordinary concurrent-edit risk. An administrator can require worktrees for concurrent writers. Enforce that requirement before dispatch.
+
+For sequential steps that must operate on one isolated result, use one pre-opened worktree as the root workspace. Independent `isolation: 'worktree'` calls create independent children; verification does not magically inspect a previous child's edits. Pass its artifact context through a deliberate integration workflow or run validation inside the same agent task.
+
+Retain changed child worktrees and expose them as inspectable artifacts/review checkpoints. Remove unchanged children only after all agents settle and no resume/reference retention requires them. Never auto-merge, auto-commit, force-reset, or delete changes. Worktrees isolate Git working copies; they do not sandbox shell authority.
+
+## 16. Discovery, saved scripts, authoring, and presentation
+
+Discover `.devspace/workflows/*.js` from the workspace directory toward its repository root, `~/.devspace/workflows/*.js`, and configured package roots. Nearest project definition wins, then personal, then packaged; namespace packaged definitions (`package:name`) to avoid collisions. List conflicts and invalid definitions diagnostically. Parse metadata without running scripts.
+
+Saved-script writes use atomic replace, canonical containment, symlink checks, and explicit overwrite semantics. Update the saved script's literal name when saving under a new name through an AST-backed edit. Running snapshots remain immutable regardless of edits to saved/editable copies. Reload discovers new definitions without restarting agent work.
+
+Use a workspace-scoped artifact/export directory for `scriptPath`, transcripts, and journals returned to a remote host. Do not broaden allowed roots to expose the entire private state directory. Authorize export reads by run ownership and existing artifact mechanisms. Authoring tools can edit the run's public copy; replay snapshots it again.
+
+Add a `workflows` skill with the complete API reference, null/failure semantics, budget meaning, phase concurrency guidance, isolation examples, and authoring patterns. Keep `open_workspace` discovery concise and preload/on-demand behavior consistent with the existing subagent skill mechanism. The authoring skill is a separate package task and must follow the skill-creator instructions when implemented.
+
+Ship reusable examples for review→verify, bounded repair loops, nested synthesis, and isolated migrations. Include a deep-research recipe when a configured target has actual web-search capability; do not assume the parent host's web tools or interactive MCP credentials are available to a child harness.
+
+Render the same stored phase/step tree in a CLI view and optional existing workspace widget: state, queued/running/completed counts, usage completeness, elapsed time, logs, individual step details, errors, and worktree artifacts. Show replayed versus newly executed work. Show partial coverage explicitly. Plain CLI/JSON and MCP output remain complete when widgets are off.
+
+Explicit user requests and configured standing authorization govern workflow launches. This user's request authorizes designing the feature, not implementing a universal always-on keyword detector. Do not parse `ultracode` out of repository text, tool output, or a child's prompt as authorization. Host adapters may supply trusted user-origin/standing-policy context; DevSpace's launch handler applies existing authority independently of script claims.
+
+## 17. Rate limits, permissions, and prompt caching
+
+Normalize provider failures without erasing the original safe reason. A rate-limit error can include `retryAfterMs`/`resetAt` and whether reissuing the request is safe. Missing metadata is unknown, not permission to infer a wait duration from arbitrary text.
+
+For a finite known reset within configured wait bounds, park the affected attempt and stop new root dispatches. Persist a `waiting_for_usage` state. Allow already-running siblings to settle. At reset, recheck cancellation, enablement, budget, authority, and attempt identity before retry. No retry of an ambiguous possibly-active turn. Bound wait count/duration (proposed two waits and 24 hours maximum per wait). Unsupported or longer waits become actionable failures, not infinite sleeps.
+
+Provider permission requests enter a typed waiting state. Use existing host/user interaction capabilities where supported; do not invent an approval response from elapsed time. Preconfigured noninteractive adapters must reject or report a required action when approval cannot be delivered. Transport disconnect does not auto-approve.
+
+Prompt caching remains an adapter optimization. When a harness exposes a reliable prefix identity and first-response event, it may stagger matching starts for at most five seconds; bypass the stagger otherwise. Do not fabricate shared caches across models/providers or stall all fan-out behind a missing event. Accounting reports actual provider cache usage when present. This optimization must not alter logical call order or correctness.
+
+## 18. Error taxonomy
+
+Reuse the project's typed Result and tagged-error convention at service/IPC boundaries. Convert to ordinary guest Error objects with enumerable safe `code`, `layer`, and step context. Keep provider/internal causes in protected diagnostics.
+
+| Category | Codes to define |
+|---|---|
+| Source/registry | `WORKFLOW_NOT_FOUND`, `WORKFLOW_SOURCE_INVALID`, `WORKFLOW_SYNTAX_ERROR`, `WORKFLOW_META_INVALID` |
+| Scope/policy | `WORKSPACE_MISMATCH`, `WORKSPACE_NOT_ALLOWED`, `WORKFLOW_DISABLED`, `AGENT_TARGET_UNAVAILABLE` |
+| Schema | `SCHEMA_INVALID`, `SCHEMA_UNSUPPORTED`, `SCHEMA_VALIDATION_FAILED`, `SCHEMA_VALIDATION_TIMEOUT` |
+| Resource | `AGENT_LIMIT`, `ATTEMPT_LIMIT`, `ITEM_LIMIT`, `NESTING_LIMIT`, `OUTPUT_LIMIT`, `LOG_LIMIT`, `SCRIPT_CPU_LIMIT`, `SCRIPT_MEMORY_LIMIT`, `WORKFLOW_TIMEOUT` |
+| Budget | `BUDGET_EXHAUSTED`, `USAGE_UNAVAILABLE`, `BUDGET_SCOPE_MISMATCH` |
+| Lifecycle | `WORKFLOW_STOPPED`, `WORKFLOW_BUSY`, `STEP_ALREADY_DELIVERED`, `CANCELLATION_UNCONFIRMED` |
+| Replay | `NOTHING_TO_RESUME`, `RESUME_SCOPE_MISMATCH`, `RESUME_RUNTIME_INCOMPATIBLE`, `REPLAY_DIVERGED`, `RECOVERY_REQUIRED` |
+| Provider | Preserve existing structured provider codes; add rate-limit metadata where available |
+
+`retryable` describes the failed operation, not blanket permission to repeat arbitrary side effects. Separately track uncertain execution. Null script results retain full typed outcome in step records.
+
+## 19. Implementation sequence and file map
+
+### Milestone A — contracts and agent prerequisites
+
+- Add primitive/transport/config/state schemas and golden host-facing schema tests.
+- Add effective-authority persistence, per-turn AbortSignal cancellation, usage callbacks, output-schema support, and capability resolution to existing local-agent files.
+- Preserve ordinary `agents run/continue/show/wait` behavior.
+- Establish shared store transactions and workflow association fields.
+- Test all seven providers through protocol/SDK doubles; live capability checks are separate.
+
+### Milestone B — parser and guest runtime
+
+- `src/workflow-script.ts`: metadata AST parsing, source diagnostics, script wrapping.
+- `src/workflow-runtime.ts` and `src/workflow-worker.ts`: QuickJS lifecycle, eight guest bindings, bounded bridge.
+- `src/workflow-schema.ts`: transport/metadata validation and structured-output validator integration.
+- Exercise JS, promise, isolation, quota, and disposal behavior without any model calls.
+
+### Milestone C — durable service and scheduler
+
+- `src/workflow-manager.ts`: lifecycle, scheduling, root/child ownership, control actions.
+- `src/workflow-store.ts`, DB schema/migrations: runs, steps, attempts, events, budgets.
+- Extend existing daemon/client/protocol with workflow methods; do not create parallel authentication/lifecycle machinery.
+- Preserve typed errors and safe daemon shutdown/configuration replacement with active workflows.
+
+### Milestone D — full agent execution behavior
+
+- Structured JSON validation/correction, finite/incomplete budgets, live usage.
+- Worktree child ownership, retained results, rate-limit waits, permission requests.
+- Phase/log/progress events and nested workflows sharing all root limits.
+- Root settling and child cancellation on every failure path.
+
+### Milestone E — replay and crash recovery
+
+- Request hashes, promise-delivery journal, synchronous observation replay.
+- Prefix reuse with edited scripts, nested invocation replay, recovery reconciliation.
+- Atomic ownership and concurrent-resume exclusion.
+- Fault injection at every dispatch/completion boundary.
+
+### Milestone F — public integration
+
+- `src/workflow-registry.ts`: definitions, resolution, save, reload.
+- `src/workflow-tools.ts`: shared MCP registration for existing tool modes.
+- CLI subcommands, authoring skill, `open_workspace` discovery, artifact export.
+- Optional workspace widget using existing UI infrastructure.
+- Package the worker entry, WASM assets, runtime dependencies, docs, and examples.
+
+### Milestone G — conformance and real-path verification
+
+- Run the full matrix below and document provider/version limitations.
+- Inspect final MCP schemas through a real host.
+- Run the packaged worker/WASM path as well as source execution.
+- Verify CLI↔MCP reconnection to the same run, widgets on/off, and managed worktrees.
+
+`workflow-manager.ts` can keep a small private scheduler initially. Split it only when its state machine materially obscures lifecycle logic; do not introduce a pluggable scheduler or execution-backend interface with one implementation.
+
+Proposed new runtime dependencies: `quickjs-emscripten` for isolated JS, `acorn` for real source parsing, and `ajv` for JSON Schema validation. Reuse existing Zod, SQLite, Result, and artifact facilities. None are installed by this planning task. The workspace has no provisioned `node_modules`; implementation verification requires the environment owner to make the chosen dependencies available under the standing no-install/no-refresh instruction. Do not work around that instruction with another package manager or runtime downloads.
+
+## 20. Required checks and release gates
+
+Use the repository's existing `node:assert`/tsx test style. These are behavioral checks, not a new testing framework.
+
+| Area | Minimum meaningful checks |
+|---|---|
+| Metadata | literal parsing, comments, escaped strings, malformed syntax, no metadata execution, source line accuracy |
+| Agent | each target, default precedence, text/JSON/null distinctions, profile snapshots, preserved provider failures |
+| Parallel | ordered outputs, concurrency, synchronous throw, rejection, empty input, invalid input before effects |
+| Pipeline | fast item advances while slow item remains in first stage; original/index arguments; no implicit flatten; failure skips; successful null passes |
+| Phase/log | explicit phase wins, queued calls retain phase, child defaults isolated, log quota and replay deduplication |
+| Args | absent versus null, JSON types, mutation does not alter persisted input, output rejects non-JSON data |
+| Budget | nested sharing, cumulative usage dedup, no double charge on replay, finite-budget target rejection, queued dispatch recheck, incomplete failure usage |
+| Nested workflow | name/path resolution, own context, one-level limit, root cancellation, no independent caps |
+| Scheduling | global/root caps, root fairness, retry accounting, nested fan-out cannot deadlock, runaway native Promise loops remain bounded |
+| Structured output | supported dialects, local refs, native/fallback paths, corrections cannot write, max attempts, validator watchdog, no remote fetching |
+| Stop/restart | cancel one child without killing shared runtime; queued stop; stale turn ID; completion race; no replacement before confirmed stop |
+| Pause/waits | active calls settle, queued calls stay queued, callbacks held, disconnect does not cancel/approve, persisted rate-limit wait |
+| Replay | unchanged script, aggregation-only edit, early insertion, failure prefix, native Promise.race, reordered completions, budget branches, nested edit |
+| Crash | before/after dispatch, identity callback, before/after result commit, delivery lost, daemon restart with active provider, competing resume requests |
+| Scope | cross-workspace lookup, symlink swaps, managed-worktree roots, narrowed authority after resume, no arbitrary script roots |
+| Worktree | committed/dirty base disclosure, changed work retained, unchanged cleanup, no auto-merge, verification uses correct workspace |
+| Isolation | no Node/env/network/import escape through bridge; CPU/microtask/memory limits; handles released; oversized request/output rejection |
+| Exposure | actual tools/list schemas, enabled/disabled modes, plain output, artifact permissions, widget rendered controls |
+| Packaging | built worker resolves WASM from installed package location; CLI/MCP share daemon state; no dependence on development-only imports |
+
+Run the user's local `pnpm` exactly, without `CI=true`, install, or dependency refresh. Use focused checks while implementing, then `pnpm typecheck` and `pnpm test` once meaningful changes are complete. Package smoke verification must use already-provisioned dependencies; do not run an installation-based smoke script that violates the no-install constraint. If full installed-package verification cannot be performed, label the narrower packed/source check explicitly.
+
+The feature is complete only when all eight primitives, management/replay behavior, and the supported-provider capability matrix pass. Missing provider usage must remain an explicit capability limitation, not a reason to delete `budget`; missing UI notifications must remain a host integration limitation, not a reason to make results inaccessible.
+
+## 21. End-to-end example
+
+```js
+export const meta = {
+  name: 'review-and-verify',
+  description: 'Review files and verify each finding with a separate agent',
+  phases: [
+    { title: 'Review', detail: 'Find actionable defects' },
+    { title: 'Verify', detail: 'Check findings against the code' },
+  ],
+}
+
+const FINDINGS = {
+  type: 'object',
+  properties: {
+    findings: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['findings'],
+  additionalProperties: false,
+}
+
+const VERDICT = {
+  type: 'object',
+  properties: {
+    confirmed: { type: 'boolean' },
+    evidence: { type: 'string' },
+  },
+  required: ['confirmed', 'evidence'],
+  additionalProperties: false,
+}
+
+log(`Reviewing ${args.files.length} files`)
+
+const rows = await pipeline(
+  args.files,
+  file => agent(`Read-only: review ${file} for correctness defects.`, {
+    agentType: args.reviewer,
+    phase: 'Review',
+    label: file,
+    schema: FINDINGS,
+  }),
+  async (review, file) => {
+    if (review === null) return { file, status: 'review_failed' }
+    const verdicts = await parallel(review.findings.map(finding => async () => {
+      const verdict = await agent(
+        `Read-only: independently verify this finding in ${file}: ${finding}`,
+        {
+          agentType: args.verifier,
+          phase: 'Verify',
+          label: file,
+          schema: VERDICT,
+        },
+      )
+      return { finding, verdict } // null verdict means unverified
+    }))
+    return { file, status: 'reviewed', verdicts }
+  },
+)
+
+return { rows } // runtime separately reports failed steps and partial coverage
+```
+
+The read-only text explains intent; enforcement comes from the run/profile authority. `args.reviewer` and `args.verifier` can resolve different harnesses without changing this program. A follow-up saved synthesis workflow can consume this JSON through `workflow('summarize-review', { rows })`; it shares the same budget and counters.
diff --git a/docs/dynamic-workflows.md b/docs/dynamic-workflows.md
new file mode 100644
index 000000000..f90827a10
--- /dev/null
+++ b/docs/dynamic-workflows.md
@@ -0,0 +1,79 @@
+# Dynamic workflows
+
+DevSpace executes JavaScript that coordinates its configured subagents. The script contract includes `agent`, `parallel`, `pipeline`, `phase`, `log`, `args`, `budget`, and nested `workflow`. The same script can select different agent profiles or providers without changing its orchestration logic.
+
+Enable workflows in your DevSpace `config.jsonc`, alongside the subagent providers you already use:
+
+```jsonc
+{
+  "workflows": {
+    "enabled": true,
+    "defaultAgentType": "reviewer",
+    "maxConcurrentAgents": 16,
+    "maxConcurrentRuns": 4
+  }
+}
+```
+
+`reviewer` must be an existing configured profile. Run `devspace agents targets` to discover usable profiles and providers. Restart the MCP server after changing tool availability; an active execution daemon keeps its original configuration until its work finishes.
+
+Save this example as `.devspace/workflows/review.js`:
+
+```javascript
+export const meta = {
+  name: "review",
+  description: "Review project areas and summarize findings",
+  phases: [{ title: "Review" }, { title: "Summarize" }]
+};
+phase("Review");
+const findings = await parallel(args.areas.map(area => () =>
+  agent(`Review ${area}; identify concrete defects and include file references.`, {
+    label: area,
+    schema: {
+      type: "object",
+      properties: { findings: { type: "array", items: { type: "string" } } },
+      required: ["findings"],
+      additionalProperties: false
+    }
+  })
+));
+phase("Summarize");
+log("Reviews finished");
+return await agent(`Summarize these review results, noting failed branches: ${JSON.stringify(findings)}`);
+```
+
+Pass `{"areas":["src/server.ts","src/workspaces.ts"]}` in `input.json`:
+
+```bash
+devspace workflows run .devspace/workflows/review.js --args-file input.json
+devspace workflows wait <run-id> --timeout 30
+devspace workflows show <run-id>
+devspace workflows save <run-id> --name review --location project
+devspace workflows ls --definitions
+```
+
+The local CLI registers the current project as a workspace; it must be within configured allowed roots. MCP hosts use the existing `workspace_id`. When enabled, both tool modes expose `run_workflow`, `get_workflow`, `wait_workflow`, `control_workflow`, `list_workflows`, and `save_workflow`. Outer MCP fields use snake_case (`run_id`, `script_path`, `agent_type`, `after_revision`); script options and JSON argument keys retain their original casing.
+
+Optional `workflows.packageRoots` registers directories of packaged workflow definitions. Relative roots resolve from the DevSpace configuration directory; package definitions are addressed as `package:name`. Project definitions take precedence over personal definitions.
+
+The [bundled workflow skill](../skills/workflows/SKILL.md) documents all primitive signatures and lifecycle operations. It is published through workspace skill discovery, or preloaded with `workflows.instructions: "preload"`. The [configuration schema](../schema/v1/devspace.schema.json) contains resource limits and defaults.
+
+## Execution and recovery
+
+Runs execute in the existing local agent daemon and survive host disconnection. SQLite records run state, agent steps, attempts, events, results, and reported usage. Large event histories expose `eventsTruncated` and `nextEventRevision`; pass that cursor as `after_revision` to retrieve the next page. Completed runs export `journal.jsonl` and `result.json` under their workspace transcript directory. Results over 64 KiB return a preview and `resultArtifact`; step details use `outputArtifact`. These paths remain within the owning workspace. JavaScript runs in a bounded QuickJS guest in a worker. It has no Node, filesystem, network, or module-import capability; project access occurs through configured agents. This guest boundary does not sandbox shell commands run by agents.
+
+Use `pause`, `resume`, and `stop` through `control_workflow` or the CLI. Individual `stop_agent` and `restart_agent` operations require a step ID. Pause gates new work and result delivery; it does not interrupt an agent already working. Stop does not undo edits. Provider cancellation must be acknowledged before a replacement turn is allowed; uncertain cancellation requires attention. Headless provider permission requests are recorded and declined; the workflow never manufactures approval.
+
+Replay launches a new run using `resume_from_run_id` (CLI `--resume-from`). Matching recorded results can be reused, and divergence is reported. A replay is not a transaction rollback: an undelivered attempt may already have changed files. After a daemon crash, uncertain attempts are marked for recovery rather than automatically repeating side effects.
+
+`isolation: "worktree"` creates a managed worktree for an agent. Inspect its changes before integration; DevSpace does not automatically merge them. A profile can restrict its write authority with `writeMode: read_only`, and continuation preserves that restriction. Final worktree status includes whether files or commits changed. Worktrees remain under the existing managed-worktree retention and pruning policy.
+
+## Provider behavior
+
+The core workflow protocol stays independent of provider SDKs. Workflow turns disable native delegation where the harness supports it, and DevSpace CLI reentry checks inherited workflow provenance. These are cooperative execution controls: unrestricted shell commands can still launch external programs. ACP has no generic way to disable provider-internal delegation, so its fleet size cannot be strictly bounded beyond the calls DevSpace observes. Adapters translate cancellation, continuation, structured results, progress, and usage. Codex and Claude support native structured-output requests; other adapters use validated JSON text. Validation errors are visible and bounded.
+
+Output-token budgets depend on reported provider usage. They are admission limits: concurrent in-flight requests can overshoot. A provider without reliable usage cannot satisfy a required budget. Missing usage is not treated as zero. Model names, supported effort values, authentication, and provider billing remain specific to each configured harness.
+
+The compatibility target is the portable scripting and lifecycle behavior in the [Claude workflow documentation](https://code.claude.com/docs/en/workflows) and [supplied reference](https://gist.github.com/Waishnav/38801adec1580aa689426ba075490670). Host slash menus, Anthropic account billing, and private cloud infrastructure are outside the local MCP execution layer.
+
+Runnable authoring examples are in [examples/workflows](../examples/workflows): review and verification, a bounded repair loop, isolated migrations, and nested synthesis. Copy definitions into `.devspace/workflows` to discover them by name, and select a configured agent at launch. Nested synthesis expects the review definition to be saved first. Research tasks use the same primitives when the chosen agent actually has search tools.
diff --git a/examples/workflows/bounded-repair.js b/examples/workflows/bounded-repair.js
new file mode 100644
index 000000000..3772fcff3
--- /dev/null
+++ b/examples/workflows/bounded-repair.js
@@ -0,0 +1,20 @@
+export const meta = {
+  name: "bounded-repair",
+  description: "Attempt a repair at most three times, verifying after each attempt"
+};
+let feedback = args.task;
+for (let attempt = 1; attempt <= 3; attempt++) {
+  phase(`Repair ${attempt}`);
+  await agent(`Implement the following repair in this workspace: ${feedback}`);
+  phase(`Verify ${attempt}`);
+  const result = await agent(`Verify the requested task: ${args.task}. Run the relevant checks.`, {
+    schema: {
+      type: "object",
+      properties: { passed: { type: "boolean" }, feedback: { type: "string" } },
+      required: ["passed", "feedback"], additionalProperties: false
+    }
+  });
+  if (result.passed) return result;
+  feedback = result.feedback;
+}
+return { passed: false, feedback };
diff --git a/examples/workflows/isolated-migrations.js b/examples/workflows/isolated-migrations.js
new file mode 100644
index 000000000..7a68451e4
--- /dev/null
+++ b/examples/workflows/isolated-migrations.js
@@ -0,0 +1,8 @@
+export const meta = {
+  name: "isolated-migrations",
+  description: "Implement independent migration candidates in separate worktrees"
+};
+return await parallel(args.candidates.map(candidate => () => agent(
+  `Implement and test this migration candidate: ${candidate}. Report tests and changed paths.`,
+  { label: candidate, isolation: "worktree" }
+)));
diff --git a/examples/workflows/nested-synthesis.js b/examples/workflows/nested-synthesis.js
new file mode 100644
index 000000000..a1f3aeab1
--- /dev/null
+++ b/examples/workflows/nested-synthesis.js
@@ -0,0 +1,8 @@
+export const meta = {
+  name: "nested-synthesis",
+  description: "Run a saved review workflow for each group, then synthesize results"
+};
+const results = await parallel(args.groups.map(group => () =>
+  workflow("review-and-verify", { areas: group })
+));
+return await agent(`Synthesize these verified group reviews, preserving failed coverage: ${JSON.stringify(results)}`);
diff --git a/examples/workflows/review-and-verify.js b/examples/workflows/review-and-verify.js
new file mode 100644
index 000000000..ef60fccbd
--- /dev/null
+++ b/examples/workflows/review-and-verify.js
@@ -0,0 +1,11 @@
+export const meta = {
+  name: "review-and-verify",
+  description: "Review independent project areas and verify the combined findings",
+  phases: [{ title: "Review" }, { title: "Verify" }]
+};
+phase("Review");
+const reviews = await parallel(args.areas.map(area => () =>
+  agent(`Review ${area}. Return actionable findings with file references. Do not modify files.`, { label: area })
+));
+phase("Verify");
+return await agent(`Verify these findings against the current workspace and report which are confirmed: ${JSON.stringify(reviews)}`);
diff --git a/package.json b/package.json
index fa39fb46c..b84fbbbc3 100644
--- a/package.json
+++ b/package.json
@@ -42,7 +42,8 @@
     "start": "node dist/cli.js serve",
     "test": "tsx --test --test-concurrency=1 \"src/**/*.test.ts\"",
     "test:package-install": "tsx --test --test-concurrency=1 \"test/package-install-smoke.test.ts\"",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:workflows-package": "tsx --test test/workflow-cli-smoke.test.ts"
   },
   "keywords": [],
   "author": "",
@@ -59,6 +60,7 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "@opencode-ai/sdk": "1.17.13",
     "@pierre/diffs": "^1.3.6",
+    "ajv": "^8.20.0",
     "better-result": "^2.10.0",
     "better-sqlite3": "^12.10.0",
     "cross-spawn": "^7.0.6",
@@ -68,9 +70,11 @@
     "jsonc-parser": "^3.3.1",
     "koffi": "^3.1.2",
     "lucide": "^1.24.0",
+    "quickjs-emscripten": "^0.32.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "semver": "^7.8.4",
+    "typescript": "^6.0.3",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
@@ -83,7 +87,6 @@
     "@types/semver": "^7.7.1",
     "@vitejs/plugin-react": "^6.0.2",
     "tsx": "^4.22.3",
-    "typescript": "^6.0.3",
     "vite": "^8.0.14"
   },
   "overrides": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 92ca7f368..658155127 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -41,6 +41,9 @@ importers:
       '@pierre/diffs':
         specifier: ^1.3.6
         version: 1.3.6(@shikijs/themes@3.23.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      ajv:
+        specifier: ^8.20.0
+        version: 8.20.0
       better-result:
         specifier: ^2.10.0
         version: 2.10.0
@@ -68,6 +71,9 @@ importers:
       lucide:
         specifier: ^1.24.0
         version: 1.24.0
+      quickjs-emscripten:
+        specifier: ^0.32.0
+        version: 0.32.0
       react:
         specifier: ^19.2.6
         version: 19.2.6
@@ -77,6 +83,9 @@ importers:
       semver:
         specifier: ^7.8.4
         version: 7.8.4
+      typescript:
+        specifier: ^6.0.3
+        version: 6.0.3
       yaml:
         specifier: ^2.9.0
         version: 2.9.0
@@ -108,9 +117,6 @@ importers:
       tsx:
         specifier: ^4.22.3
         version: 4.22.3
-      typescript:
-        specifier: ^6.0.3
-        version: 6.0.3
       vite:
         specifier: ^8.0.14
         version: 8.0.16(@types/node@25.9.1)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.3)(yaml@2.9.0)
@@ -509,6 +515,21 @@ packages:
     peerDependencies:
       hono: ^4
 
+  '@jitl/quickjs-ffi-types@0.32.0':
+    resolution: {integrity: sha512-v9T+GQpmk43VDJ7d72sf0Nexhk+ArvtUihW27dy7lqAl0zBObFKtSBBIm5RBjwIhE8VwsPPm9PNuvPvNqLWUEg==}
+
+  '@jitl/quickjs-wasmfile-debug-asyncify@0.32.0':
+    resolution: {integrity: sha512-EX8zbXwGqCgAE764M+qvkHtyXDi/FUoMBea0JnES7vCM3P7a2+EOZOjGv85wtZ2sJhI1oJ+nekmqpOODFDY+hw==}
+
+  '@jitl/quickjs-wasmfile-debug-sync@0.32.0':
+    resolution: {integrity: sha512-LeYWrPGC1uNCTBWvibo3ZLJj0CSVNYUXvJpXMCmuQ5Sap2cCACc3uvGvYV4homHHBAzfw5akoTqMMS4YFRtw+Q==}
+
+  '@jitl/quickjs-wasmfile-release-asyncify@0.32.0':
+    resolution: {integrity: sha512-3oSwPfja12ICz4aIblB58cuY8JlEq5Txt8Cut4VLo+LH47QN+mzCnSgnbB03hWzg1LBcc+VyyI9UOag7a1NF+Q==}
+
+  '@jitl/quickjs-wasmfile-release-sync@0.32.0':
+    resolution: {integrity: sha512-BKNDI/TPBfGlLNGYpLrhcDGXmIk4xHm4MRAisOBnOzpXVn9HZWsfmMAc9WMBrAHjvvds6HOikKeaOBKdPdpVrg==}
+
   '@koromix/koffi-android-arm64@3.2.1':
     resolution: {integrity: sha512-1pJQ4jnZlUJduK9u9DC5CGy3aOgDUPvIXpNb6syV3+Dh5Q/ugezAIGCqvY+w+1mgXsve0pd0NVvJRjdZNHQ6MA==}
     cpu: [arm64]
@@ -1873,6 +1894,13 @@ packages:
     resolution: {integrity: sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==}
     engines: {node: '>=0.6'}
 
+  quickjs-emscripten-core@0.32.0:
+    resolution: {integrity: sha512-QFnPfjFey8EqknSrSxe1hZrf1/8z7/6s1QzGOmKo6++02r7QRRX7ZoyNaZh7JuVjWsVW87KnQrbZqnHkOAzUyg==}
+
+  quickjs-emscripten@0.32.0:
+    resolution: {integrity: sha512-So0Sqw869y/S2oE3Nuc0uT3Dhqgvsj8FSrwBdsuTosVsG8ME5/OcudU1GxsrIFdFABgy17GHnTVO9TYV/bLQcA==}
+    engines: {node: '>=16.0.0'}
+
   range-parser@1.2.1:
     resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==}
     engines: {node: '>= 0.6'}
@@ -2673,6 +2701,24 @@ snapshots:
     dependencies:
       hono: 4.12.25
 
+  '@jitl/quickjs-ffi-types@0.32.0': {}
+
+  '@jitl/quickjs-wasmfile-debug-asyncify@0.32.0':
+    dependencies:
+      '@jitl/quickjs-ffi-types': 0.32.0
+
+  '@jitl/quickjs-wasmfile-debug-sync@0.32.0':
+    dependencies:
+      '@jitl/quickjs-ffi-types': 0.32.0
+
+  '@jitl/quickjs-wasmfile-release-asyncify@0.32.0':
+    dependencies:
+      '@jitl/quickjs-ffi-types': 0.32.0
+
+  '@jitl/quickjs-wasmfile-release-sync@0.32.0':
+    dependencies:
+      '@jitl/quickjs-ffi-types': 0.32.0
+
   '@koromix/koffi-android-arm64@3.2.1':
     optional: true
 
@@ -3878,6 +3924,18 @@ snapshots:
     dependencies:
       side-channel: 1.1.0
 
+  quickjs-emscripten-core@0.32.0:
+    dependencies:
+      '@jitl/quickjs-ffi-types': 0.32.0
+
+  quickjs-emscripten@0.32.0:
+    dependencies:
+      '@jitl/quickjs-wasmfile-debug-asyncify': 0.32.0
+      '@jitl/quickjs-wasmfile-debug-sync': 0.32.0
+      '@jitl/quickjs-wasmfile-release-asyncify': 0.32.0
+      '@jitl/quickjs-wasmfile-release-sync': 0.32.0
+      quickjs-emscripten-core: 0.32.0
+
   range-parser@1.2.1: {}
 
   raw-body@3.0.2:
diff --git a/schema/v1/devspace.schema.json b/schema/v1/devspace.schema.json
index cf9ce8f84..cbcd77fc3 100644
--- a/schema/v1/devspace.schema.json
+++ b/schema/v1/devspace.schema.json
@@ -155,6 +155,185 @@
       },
       "additionalProperties": false
     },
+    "workflows": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "instructions": {
+          "default": "on-demand",
+          "type": "string",
+          "enum": [
+            "on-demand",
+            "preload"
+          ]
+        },
+        "defaultAgentType": {
+          "type": "string",
+          "minLength": 1
+        },
+        "packageRoots": {
+          "default": [],
+          "maxItems": 100,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "maxConcurrentAgents": {
+          "default": 16,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 256
+        },
+        "maxConcurrentRuns": {
+          "default": 4,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 32
+        },
+        "maxAgentsPerRun": {
+          "default": 1000,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 10000
+        },
+        "maxAttemptsPerRun": {
+          "default": 5000,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 50000
+        },
+        "defaultOutputTokenBudget": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "maxOutputTokenBudget": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "requireWorktreesForConcurrentWrites": {
+          "default": false,
+          "type": "boolean"
+        },
+        "maxUsageLimitWaits": {
+          "default": 2,
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10
+        },
+        "maxUsageLimitWaitMs": {
+          "default": 86400000,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 86400000
+        },
+        "limits": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "scriptBytes": {
+              "default": 262144,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "argsBytes": {
+              "default": 1048576,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "promptBytes": {
+              "default": 1048576,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "schemaBytes": {
+              "default": 131072,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "schemaDepth": {
+              "default": 64,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 256
+            },
+            "agentResultBytes": {
+              "default": 4194304,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "runResultBytes": {
+              "default": 16777216,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "guestHeapBytes": {
+              "default": 67108864,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "guestStackBytes": {
+              "default": 1048576,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "guestSliceMs": {
+              "default": 1000,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "guestTotalCpuMs": {
+              "default": 30000,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "runActiveMs": {
+              "default": 21600000,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "logMessageBytes": {
+              "default": 8192,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "logTotalBytes": {
+              "default": 1048576,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            },
+            "eventsPerRun": {
+              "default": 100000,
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 2147483647
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "subagents": {
       "default": {
         "enabled": false,
diff --git a/skills/workflows/SKILL.md b/skills/workflows/SKILL.md
new file mode 100644
index 000000000..1fe9a7723
--- /dev/null
+++ b/skills/workflows/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: workflows
+description: Write and run JavaScript workflows that coordinate multiple DevSpace subagents, including parallel tasks, pipelines, structured results, and reusable saved scripts.
+---
+
+# DevSpace dynamic workflows
+
+Use a workflow when JavaScript branching, iteration, or coordinating several bounded agents helps complete the task. Discover configured targets with `devspace agents targets`; use their names as `agentType`. The host owns orchestration and can inspect or control each run.
+
+Scripts begin with literal metadata. The remaining body supports top-level await and return:
+
+```javascript
+export const meta = {
+  name: "parallel-review",
+  description: "Review independent areas and synthesize findings",
+  phases: [{ title: "Review" }, { title: "Synthesize" }]
+};
+phase("Review");
+const reviews = await parallel(args.areas.map(area => () =>
+  agent(`Review ${area}. Return concrete findings with file references.`, {
+    agentType: "reviewer", label: area
+  })
+));
+phase("Synthesize");
+return await agent(`Combine these findings: ${JSON.stringify(reviews)}`);
+```
+
+Supply self-contained prompts: workers do not inherit the host conversation. Agent targets, model names, and supported effort settings come from DevSpace configuration. Do not invent provider-specific identifiers.
+
+## Script primitives
+
+- `await agent(prompt, options?)` starts a fresh logical agent and returns final text. With `options.schema`, it returns validated JSON. Options: `label`, `phase`, `schema` (JSON Schema), `model`, `effort`, `isolation: "worktree"`, `agentType`. A skipped, stopped, policy-blocked, or terminally failed agent resolves to `null`; its distinct outcome remains visible in step details.
+- `await parallel([() => task(), ...])` runs tasks concurrently, preserves order, and returns `null` for a failed branch. Inspect failures before synthesis.
+- `await pipeline(items, stage1, stage2, ...)` runs each item through the stages; different items overlap. A failed item becomes `null` and skips later stages. A stage that successfully returns `null` still passes that value to the next stage.
+- `phase(title)` labels subsequent work. `log(message)` records progress.
+- `args` is the JSON value supplied at launch. It is `undefined` when omitted; explicit `null` remains null.
+- `budget.total` is the output-token limit or `null`. `budget.spent()` and `budget.remaining()` use reported usage. Unlimited remaining is `Infinity`. An unavailable usage report raises an error rather than reporting zero. In-flight calls may overshoot a token limit.
+- `await workflow("saved-name", childArgs?)` or `await workflow({scriptPath: ".devspace/workflows/review.js"}, childArgs?)` invokes one nested workflow level in a separate script context. The child receives only explicitly supplied arguments; omitted child arguments become `undefined`, while explicit `null` remains null.
+
+The script environment has JavaScript built-ins and these primitives, without Node, filesystem, network, timers, or module imports. Agents perform project work through their configured tools. Shell commands used by agents still run with local-user authority. Workflow workers must return further delegation needs to their owning script; their inherited CLI context blocks extra DevSpace agent launches. ACP cannot guarantee that its provider will disable internal delegation. Use worktree isolation for independent changes that should not share a checkout; changes remain available for inspection and are not automatically merged.
+
+## Launch and observe
+
+Use `run_workflow` with the existing `workspace_id` and a `script`, workspace-relative `script_path`, or saved `name`. When more than one is supplied, `script_path` takes precedence over `name`, then `script`; diagnostics report the selected source. Optional launch settings are `args`, `agent_type`, `model`, `effort`, `output_token_budget`. The receipt contains the run ID. Use `get_workflow` or `wait_workflow` with `run_id`; pass `after_revision` to wait for fresh progress. Disconnection or wait timeout does not cancel work. If `eventsTruncated` is true, use `get_workflow` with `after_revision: nextEventRevision` to retrieve the next event page; use `revision` when waiting for new state.
+
+CLI equivalents:
+
+```bash
+devspace workflows run .devspace/workflows/review.js --args-file input.json
+devspace workflows show <run-id>
+devspace workflows wait <run-id> --timeout 30
+devspace workflows ls --definitions
+```
+
+`control_workflow` accepts `pause`, `resume`, `stop`, `stop_agent`, `restart_agent`; individual controls require `step_id`. Pause holds new launches and result delivery while running agents finish. Restart only applies before a result reaches the script. Stopping requests cancellation; it does not undo edits or provider charges.
+
+To replay a prior run, launch its source with `resume_from_run_id`. Matching delivered results are reused. Script branches and arguments must match the recorded history; replay can reject divergence. Undelivered side effects may have occurred, so inspect their workspace before retrying.
+
+`save_workflow` saves a run's source under a kebab-case `name` in `location: "project"` or `"user"`. Use `replace: true` only when replacing that saved definition is intended. Project definitions live in `.devspace/workflows`; personal definitions live in the DevSpace configuration directory's `workflows` folder.
diff --git a/src/cli.ts b/src/cli.ts
index 3037f65e8..304e871c3 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -56,6 +56,7 @@ import { readReviewRef } from "./review-checkpoints.js";
 import { shutdownHttpServer } from "./server-shutdown.js";
 import { logEvent } from "./logger.js";
 import { pruneStaleManagedWorktrees } from "./worktree-prune.js";
+import { runWorkflowsCommand } from "./workflow-cli.js";
 
 type Command =
   | "serve"
@@ -64,6 +65,7 @@ type Command =
   | "config"
   | "worktrees"
   | "agents"
+  | "workflows"
   | "show-changes"
   | "help"
   | "version";
@@ -96,6 +98,9 @@ async function main(argv: string[]): Promise<void> {
     case "agents":
       await runAgentsCommand(args);
       return;
+    case "workflows":
+      await runWorkflowsCommand(args);
+      return;
     case "show-changes":
       await runShowChanges(args);
       return;
@@ -116,6 +121,7 @@ function normalizeCommand(command: string | undefined): Command {
     || command === "config"
     || command === "worktrees"
     || command === "agents"
+    || command === "workflows"
     || command === "show-changes"
   ) return command;
   if (command === "help" || command === "--help" || command === "-h") return "help";
@@ -498,6 +504,7 @@ function printHelp(): void {
       "  devspace agents show <id> [--json]",
       "  devspace agents wait <id>... [--timeout <seconds>] [--json]",
       "  devspace agents daemon <status|stop|logs>",
+      "  devspace workflows --help  Run and control JavaScript agent workflows",
       "  devspace -v, --version   Print the installed version",
       "",
       "For temporary tunnels:",
@@ -526,6 +533,9 @@ async function runShowChanges(args: string[]): Promise<void> {
 
 async function runAgentsCommand(args: string[]): Promise<void> {
   const [subcommand, ...rest] = args;
+  if (process.env.DEVSPACE_WORKFLOW_RUN_ID && (subcommand === "run" || subcommand === "continue")) {
+    throw new Error("Workflow workers cannot launch extra agents through the CLI. Return the task to the owning workflow.");
+  }
   const { args: commandArgs, json } = extractJsonOption(rest);
   switch (subcommand) {
     case "ls":
diff --git a/src/config-schema.ts b/src/config-schema.ts
index 95141fbd9..408b737b1 100644
--- a/src/config-schema.ts
+++ b/src/config-schema.ts
@@ -1,5 +1,6 @@
 import * as z from "zod/v4";
 import { subagentsConfigSchema } from "./local-agent-config.js";
+import { workflowsConfigSchema } from "./workflow-config.js";
 
 export const DEVSPACE_CONFIG_VERSION = 1 as const;
 export const DEVSPACE_CONFIG_SCHEMA_URL =
@@ -78,6 +79,7 @@ export const devspaceConfigSchema = z.object({
   ui: uiConfigSchema,
   artifacts: artifactsConfigSchema,
   skills: skillsConfigSchema,
+  workflows: workflowsConfigSchema,
   subagents: subagentsConfigSchema.default({
     enabled: false,
     instructions: "on-demand",
diff --git a/src/config.ts b/src/config.ts
index 34fcdfc25..f3c390f3f 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -5,6 +5,7 @@ import type { LoggingConfig } from "./logger.js";
 import type { OAuthConfig } from "./oauth-provider.js";
 import { devspaceAgentsDir, devspaceSkillsDir, loadDevspaceFiles } from "./user-config.js";
 import type { SubagentsConfig } from "./local-agent-config.js";
+import type { WorkflowsConfig } from "./workflow-config.js";
 
 export type { ToolMode } from "./config-schema.js";
 
@@ -27,6 +28,7 @@ export interface ServerConfig {
   devspaceSkillsDir: string;
   devspaceAgentsDir: string;
   subagents: SubagentsConfig;
+  workflows?: WorkflowsConfig;
   agentDir: string;
   logging: LoggingConfig;
 }
@@ -76,6 +78,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
     devspaceSkillsDir: devspaceSkillsDir(env),
     devspaceAgentsDir: devspaceAgentsDir(env),
     subagents: stored.subagents,
+    workflows: stored.workflows,
     agentDir: normalizePath(stored.skills.agentDir),
     logging: {
       ...stored.logging,
diff --git a/src/db/migrations.ts b/src/db/migrations.ts
index 8bb1f7e4f..b11a6a709 100644
--- a/src/db/migrations.ts
+++ b/src/db/migrations.ts
@@ -47,6 +47,21 @@ const migrations: Migration[] = [
     name: "local-agent-turns",
     up: migrateLocalAgentTurns,
   },
+  {
+    version: 9,
+    name: "dynamic-workflows",
+    up: migrateDynamicWorkflows,
+  },
+  {
+    version: 10,
+    name: "workflow-agent-authority",
+    up: migrateWorkflowAgentAuthority,
+  },
+  {
+    version: 11,
+    name: "local-agent-retry-metadata",
+    up: migrateLocalAgentRetryMetadata,
+  },
 ];
 
 export function migrateDatabase(sqlite: Database.Database): void {
@@ -289,9 +304,150 @@ function migrateLocalAgentTurns(sqlite: Database.Database): void {
   `);
 }
 
+function migrateDynamicWorkflows(sqlite: Database.Database): void {
+  sqlite.exec(`
+    create table workflow_budgets (
+      id text primary key,
+      total_output_tokens integer check (total_output_tokens is null or total_output_tokens > 0),
+      known_output_tokens integer not null default 0 check (known_output_tokens >= 0),
+      usage_complete integer not null default 1 check (usage_complete in (0, 1)),
+      revision integer not null default 0 check (revision >= 0)
+    );
+
+    create table workflow_runs (
+      id text primary key,
+      workspace_id text not null,
+      workspace_root text not null,
+      lineage_id text not null,
+      budget_id text not null references workflow_budgets(id),
+      resumed_from_run_id text references workflow_runs(id),
+      state text not null check (state in (
+        'starting', 'running', 'pausing', 'paused', 'waiting_for_permission',
+        'waiting_for_usage', 'stopping', 'stopped', 'completed', 'failed',
+        'recovery_required'
+      )),
+      meta_json text not null,
+      script_source text not null,
+      script_hash text not null,
+      source_path text,
+      args_present integer not null check (args_present in (0, 1)),
+      args_json text,
+      defaults_json text not null,
+      policy_json text not null,
+      runtime_version text not null,
+      revision integer not null default 0 check (revision >= 0),
+      execution_generation integer not null default 1 check (execution_generation > 0),
+      result_json text,
+      result_artifact_id text,
+      error_json text,
+      pause_reason text,
+      next_eligible_at text,
+      created_at text not null,
+      updated_at text not null,
+      finished_at text
+    );
+
+    create index workflow_runs_workspace_idx on workflow_runs(workspace_id, updated_at desc);
+    create index workflow_runs_state_idx on workflow_runs(state, updated_at desc);
+    create index workflow_runs_lineage_idx on workflow_runs(lineage_id, created_at);
+
+    create table workflow_steps (
+      id text primary key,
+      run_id text not null references workflow_runs(id) on delete cascade,
+      parent_step_id text references workflow_steps(id),
+      kind text not null check (kind in ('agent', 'workflow')),
+      call_sequence integer not null check (call_sequence > 0),
+      logical_path text not null,
+      request_hash text not null,
+      request_json text not null,
+      phase text,
+      label text,
+      status text not null check (status in (
+        'queued', 'starting', 'running', 'waiting_for_permission',
+        'waiting_for_usage', 'completed', 'failed', 'stopped', 'cached', 'uncertain'
+      )),
+      agent_id text,
+      workspace_id text not null,
+      cached_from_step_id text references workflow_steps(id),
+      output_json text,
+      error_json text,
+      delivery_sequence integer check (delivery_sequence is null or delivery_sequence > 0),
+      worktree_json text,
+      created_at text not null,
+      updated_at text not null,
+      finished_at text,
+      unique(run_id, call_sequence)
+    );
+
+    create index workflow_steps_run_status_idx on workflow_steps(run_id, status);
+    create index workflow_steps_parent_idx on workflow_steps(parent_step_id);
+
+    create table workflow_attempts (
+      id text primary key,
+      step_id text not null references workflow_steps(id) on delete cascade,
+      attempt_number integer not null check (attempt_number > 0),
+      agent_id text not null,
+      agent_turn_id integer not null unique,
+      reason text not null check (reason in ('initial', 'schema_repair', 'restart', 'retry')),
+      state text not null check (state in (
+        'queued', 'starting', 'running', 'waiting_for_permission',
+        'waiting_for_usage', 'completed', 'failed', 'stopped', 'uncertain'
+      )),
+      usage_sequence integer not null default 0 check (usage_sequence >= 0),
+      output_tokens integer check (output_tokens is null or output_tokens >= 0),
+      usage_complete integer not null default 0 check (usage_complete in (0, 1)),
+      error_json text,
+      created_at text not null,
+      updated_at text not null,
+      finished_at text,
+      unique(step_id, attempt_number)
+    );
+
+    create table workflow_events (
+      run_id text not null references workflow_runs(id) on delete cascade,
+      sequence integer not null check (sequence > 0),
+      step_id text references workflow_steps(id),
+      type text not null,
+      payload_json text not null,
+      created_at text not null,
+      primary key(run_id, sequence)
+    );
+
+    create table workflow_resume_claims (
+      source_run_id text primary key references workflow_runs(id) on delete cascade,
+      source_generation integer not null,
+      resumed_by_run_id text not null unique references workflow_runs(id) on delete cascade,
+      created_at text not null
+    );
+  `);
+}
+
+function migrateWorkflowAgentAuthority(sqlite: Database.Database): void {
+  addColumnIfMissing(sqlite, "local_agent_sessions", "write_mode", "text not null default 'allowed'");
+  addColumnIfMissing(sqlite, "local_agent_turns", "write_mode", "text not null default 'allowed'");
+  addColumnIfMissing(sqlite, "local_agent_turns", "model", "text");
+  addColumnIfMissing(sqlite, "local_agent_turns", "effort", "text");
+  addColumnIfMissing(sqlite, "local_agent_turns", "attempt_id", "text");
+  addColumnIfMissing(sqlite, "local_agent_turns", "workflow_run_id", "text");
+  addColumnIfMissing(sqlite, "local_agent_turns", "workflow_step_id", "text");
+  addColumnIfMissing(sqlite, "local_agent_turns", "workflow_attempt_id", "text");
+  sqlite.exec(`
+    create index if not exists local_agent_turns_workflow_run_idx
+      on local_agent_turns(workflow_run_id, id);
+    create index if not exists local_agent_turns_workflow_step_idx
+      on local_agent_turns(workflow_step_id, id);
+  `);
+}
+
+function migrateLocalAgentRetryMetadata(sqlite: Database.Database): void {
+  addColumnIfMissing(sqlite, "local_agent_turns", "retry_after_ms", "integer");
+  addColumnIfMissing(sqlite, "local_agent_turns", "reset_at", "text");
+  addColumnIfMissing(sqlite, "local_agent_turns", "execution_uncertain", "text");
+}
+
 function addColumnIfMissing(
   sqlite: Database.Database,
-  table: "workspace_sessions" | "local_agent_sessions",
+  table: "workspace_sessions" | "local_agent_sessions" | "local_agent_turns",
   column: string,
   definition: string,
 ): void {
diff --git a/src/db/schema.ts b/src/db/schema.ts
index 77b234368..0497d5be2 100644
--- a/src/db/schema.ts
+++ b/src/db/schema.ts
@@ -1,4 +1,4 @@
-import { index, integer, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { index, integer, primaryKey, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
 
 export const workspaceSessions = sqliteTable(
   "workspace_sessions",
@@ -101,6 +101,7 @@ export const localAgentSessions = sqliteTable(
     provider: text("provider").notNull(),
     model: text("model"),
     effort: text("effort"),
+    writeMode: text("write_mode").notNull().default("allowed"),
     providerSessionId: text("provider_session_id"),
     status: text("status").notNull(),
     latestResponse: text("latest_response"),
@@ -117,6 +118,152 @@ export const localAgentSessions = sqliteTable(
   ],
 );
 
+export const localAgentTurns = sqliteTable(
+  "local_agent_turns",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    agentId: text("agent_id").notNull().references(() => localAgentSessions.id, { onDelete: "cascade" }),
+    prompt: text("prompt").notNull(),
+    status: text("status").notNull(),
+    response: text("response"),
+    error: text("error"),
+    errorCode: text("error_code"),
+    errorRetryable: text("error_retryable"),
+    writeMode: text("write_mode").notNull().default("allowed"),
+    model: text("model"),
+    effort: text("effort"),
+    attemptId: text("attempt_id"),
+    workflowRunId: text("workflow_run_id"),
+    workflowStepId: text("workflow_step_id"),
+    workflowAttemptId: text("workflow_attempt_id"),
+    retryAfterMs: integer("retry_after_ms"),
+    resetAt: text("reset_at"),
+    executionUncertain: text("execution_uncertain"),
+    createdAt: text("created_at").notNull(),
+    completedAt: text("completed_at"),
+  },
+  (table) => [
+    index("local_agent_turns_agent_id_idx").on(table.agentId, table.id),
+    index("local_agent_turns_status_idx").on(table.status),
+    index("local_agent_turns_workflow_run_idx").on(table.workflowRunId, table.id),
+    index("local_agent_turns_workflow_step_idx").on(table.workflowStepId, table.id),
+  ],
+);
+
+export const workflowBudgets = sqliteTable("workflow_budgets", {
+  id: text("id").primaryKey(),
+  totalOutputTokens: integer("total_output_tokens"),
+  knownOutputTokens: integer("known_output_tokens").notNull().default(0),
+  usageComplete: integer("usage_complete", { mode: "boolean" }).notNull().default(true),
+  revision: integer("revision").notNull().default(0),
+});
+
+export const workflowRuns = sqliteTable(
+  "workflow_runs",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id").notNull(),
+    workspaceRoot: text("workspace_root").notNull(),
+    lineageId: text("lineage_id").notNull(),
+    budgetId: text("budget_id").notNull().references(() => workflowBudgets.id),
+    resumedFromRunId: text("resumed_from_run_id"),
+    state: text("state").notNull(),
+    metaJson: text("meta_json").notNull(),
+    scriptSource: text("script_source").notNull(),
+    scriptHash: text("script_hash").notNull(),
+    sourcePath: text("source_path"),
+    argsPresent: integer("args_present", { mode: "boolean" }).notNull(),
+    argsJson: text("args_json"),
+    defaultsJson: text("defaults_json").notNull(),
+    policyJson: text("policy_json").notNull(),
+    runtimeVersion: text("runtime_version").notNull(),
+    revision: integer("revision").notNull().default(0),
+    executionGeneration: integer("execution_generation").notNull().default(1),
+    resultJson: text("result_json"),
+    resultArtifactId: text("result_artifact_id"),
+    errorJson: text("error_json"),
+    pauseReason: text("pause_reason"),
+    nextEligibleAt: text("next_eligible_at"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+    finishedAt: text("finished_at"),
+  },
+  (table) => [
+    index("workflow_runs_workspace_idx").on(table.workspaceId, table.updatedAt),
+    index("workflow_runs_state_idx").on(table.state, table.updatedAt),
+    index("workflow_runs_lineage_idx").on(table.lineageId, table.createdAt),
+  ],
+);
+
+export const workflowSteps = sqliteTable(
+  "workflow_steps",
+  {
+    id: text("id").primaryKey(),
+    runId: text("run_id").notNull().references(() => workflowRuns.id, { onDelete: "cascade" }),
+    parentStepId: text("parent_step_id"),
+    kind: text("kind").notNull(),
+    callSequence: integer("call_sequence").notNull(),
+    logicalPath: text("logical_path").notNull(),
+    requestHash: text("request_hash").notNull(),
+    requestJson: text("request_json").notNull(),
+    phase: text("phase"),
+    label: text("label"),
+    status: text("status").notNull(),
+    agentId: text("agent_id"),
+    workspaceId: text("workspace_id").notNull(),
+    cachedFromStepId: text("cached_from_step_id"),
+    outputJson: text("output_json"),
+    errorJson: text("error_json"),
+    deliverySequence: integer("delivery_sequence"),
+    worktreeJson: text("worktree_json"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+    finishedAt: text("finished_at"),
+  },
+  (table) => [
+    uniqueIndex("workflow_steps_run_call_idx").on(table.runId, table.callSequence),
+    index("workflow_steps_run_status_idx").on(table.runId, table.status),
+    index("workflow_steps_parent_idx").on(table.parentStepId),
+  ],
+);
+
+export const workflowAttempts = sqliteTable(
+  "workflow_attempts",
+  {
+    id: text("id").primaryKey(),
+    stepId: text("step_id").notNull().references(() => workflowSteps.id, { onDelete: "cascade" }),
+    attemptNumber: integer("attempt_number").notNull(),
+    agentId: text("agent_id").notNull(),
+    agentTurnId: integer("agent_turn_id").notNull(),
+    reason: text("reason").notNull(),
+    state: text("state").notNull(),
+    usageSequence: integer("usage_sequence").notNull().default(0),
+    outputTokens: integer("output_tokens"),
+    usageComplete: integer("usage_complete", { mode: "boolean" }).notNull().default(false),
+    errorJson: text("error_json"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+    finishedAt: text("finished_at"),
+  },
+  (table) => [
+    uniqueIndex("workflow_attempts_step_number_idx").on(table.stepId, table.attemptNumber),
+    uniqueIndex("workflow_attempts_turn_idx").on(table.agentTurnId),
+  ],
+);
+
+export const workflowEvents = sqliteTable(
+  "workflow_events",
+  {
+    runId: text("run_id").notNull().references(() => workflowRuns.id, { onDelete: "cascade" }),
+    sequence: integer("sequence").notNull(),
+    stepId: text("step_id"),
+    type: text("type").notNull(),
+    payloadJson: text("payload_json").notNull(),
+    createdAt: text("created_at").notNull(),
+  },
+  (table) => [primaryKey({ columns: [table.runId, table.sequence] })],
+);
+
 export type WorkspaceSessionRow = typeof workspaceSessions.$inferSelect;
 export type NewWorkspaceSessionRow = typeof workspaceSessions.$inferInsert;
 export type LoadedAgentFileRow = typeof loadedAgentFiles.$inferSelect;
@@ -125,3 +272,15 @@ export type WorkspaceConversationBindingRow = typeof workspaceConversationBindin
 export type NewWorkspaceConversationBindingRow = typeof workspaceConversationBindings.$inferInsert;
 export type LocalAgentSessionRow = typeof localAgentSessions.$inferSelect;
 export type NewLocalAgentSessionRow = typeof localAgentSessions.$inferInsert;
+export type LocalAgentTurnRow = typeof localAgentTurns.$inferSelect;
+export type NewLocalAgentTurnRow = typeof localAgentTurns.$inferInsert;
+export type WorkflowRunRow = typeof workflowRuns.$inferSelect;
+export type NewWorkflowRunRow = typeof workflowRuns.$inferInsert;
+export type WorkflowStepRow = typeof workflowSteps.$inferSelect;
+export type NewWorkflowStepRow = typeof workflowSteps.$inferInsert;
+export type WorkflowAttemptRow = typeof workflowAttempts.$inferSelect;
+export type NewWorkflowAttemptRow = typeof workflowAttempts.$inferInsert;
+export type WorkflowEventRow = typeof workflowEvents.$inferSelect;
+export type NewWorkflowEventRow = typeof workflowEvents.$inferInsert;
+export type WorkflowBudgetRow = typeof workflowBudgets.$inferSelect;
+export type NewWorkflowBudgetRow = typeof workflowBudgets.$inferInsert;
diff --git a/src/local-agent-acp.test.ts b/src/local-agent-acp.test.ts
index 7a5222261..4ab1765ea 100644
--- a/src/local-agent-acp.test.ts
+++ b/src/local-agent-acp.test.ts
@@ -14,6 +14,8 @@ import { GrokPromptCompletionRegistry } from "./local-agent-grok.js";
 
 const requests: Array<{ method: string; params?: unknown }> = [];
 const queues = new Map<string, { values: unknown[] }>();
+let cancelCount = 0;
+let settleHeldPrompt: (() => void) | undefined;
 const connection = {
   agent: {
     async request(method: string, params?: unknown): Promise<unknown> {
@@ -36,6 +38,11 @@ const connection = {
         return { sessionId };
       }
       if (method === "session/prompt") {
+        const prompt = (params as { prompt?: Array<{ text?: string }> }).prompt?.[0]?.text;
+        if (prompt === "hold") {
+          await new Promise<void>((resolve) => { settleHeldPrompt = resolve; });
+          return { stopReason: "cancelled" };
+        }
         const queue = queues.get(input?.sessionId ?? "");
         queue?.values.push({
           update: {
@@ -43,16 +50,31 @@ const connection = {
             content: { type: "text", text: "ACP response" },
           },
         });
-        return { stopReason: "end_turn" };
+        return {
+          stopReason: "end_turn",
+          usage: {
+            totalTokens: 15,
+            inputTokens: 3,
+            outputTokens: 5,
+            thoughtTokens: 4,
+            cachedReadTokens: 1,
+            cachedWriteTokens: 2,
+          },
+        };
       }
       return {};
     },
+    async cancel() {
+      cancelCount += 1;
+      settleHeldPrompt?.();
+    },
   },
   close() {},
   closed: new Promise<void>(() => undefined),
 };
 
 const sessionIds: string[] = [];
+const usageUpdates: unknown[] = [];
 const runtime = new AcpRuntime({
   provider: "cursor",
   command: "cursor-agent",
@@ -68,8 +90,10 @@ const firstResult = await runtime.run({
   model: "model-a",
   effort: "high",
   writeMode: "read_only",
+  attemptId: "attempt_acp_1",
 }, {
   onSessionId: (sessionId) => { sessionIds.push(sessionId); },
+  onUsage: (usage) => { usageUpdates.push(usage); },
 });
 assert.equal(firstResult.isOk(), true);
 if (firstResult.isErr()) throw firstResult.error;
@@ -91,6 +115,16 @@ const warm = warmResult.value;
 assert.equal(first.providerSessionId, "cursor_session_1");
 assert.equal(warm.finalResponse, "ACP response");
 assert.deepEqual(sessionIds, ["cursor_session_1", "cursor_session_1"]);
+assert.deepEqual(usageUpdates, [{
+  attemptId: "attempt_acp_1",
+  sequence: 1,
+  inputTokens: 3,
+  outputTokens: 5,
+  cacheReadTokens: 1,
+  cacheWriteTokens: 2,
+  reasoningTokens: 4,
+  final: true,
+}]);
 assert.equal(requests.filter(({ method }) => method === "session/new").length, 1);
 assert.equal(requests.filter(({ method }) => method === "session/resume").length, 0);
 assert.equal(requests.filter(({ method }) => method === "session/set_config_option").length, 4);
@@ -99,6 +133,19 @@ assert.equal(
   false,
 );
 
+const acpAbort = new AbortController();
+const held = runtime.run({
+  prompt: "hold",
+  workspaceRoot: "/tmp/project",
+  providerSessionId: first.providerSessionId ?? undefined,
+}, undefined, { signal: acpAbort.signal });
+await new Promise<void>((resolve) => setImmediate(resolve));
+acpAbort.abort();
+const cancelled = await held;
+assert.equal(cancelled.isErr(), true);
+if (cancelled.isErr()) assert.equal(cancelled.error.code, "PROVIDER_CANCELLED");
+assert.equal(cancelCount, 1);
+
 await runtime.releaseSession("cursor_session_1");
 assert.equal(queues.has("cursor_session_1"), false);
 assert.equal(requests.filter(({ method }) => method === "session/close").length, 1);
diff --git a/src/local-agent-acp.ts b/src/local-agent-acp.ts
index 078391ea9..af9109584 100644
--- a/src/local-agent-acp.ts
+++ b/src/local-agent-acp.ts
@@ -18,14 +18,18 @@ import {
   resolveGrokEffort,
   resolveGrokModelId,
 } from "./local-agent-grok.js";
-import type {
-  LocalAgentDriver,
-  LocalAgentRunCallbacks,
-  LocalAgentRunInput,
-  LocalAgentRunResult,
-  LocalAgentRuntime,
-  LocalAgentRuntimeContext,
-  LocalAgentWriteMode,
+import {
+  localAgentWorkflowEnvironment,
+  type LocalAgentDriver,
+  type LocalAgentProgressUpdate,
+  type LocalAgentRunCallbacks,
+  type LocalAgentRunControl,
+  type LocalAgentRunInput,
+  type LocalAgentRunResult,
+  type LocalAgentRuntime,
+  type LocalAgentRuntimeContext,
+  type LocalAgentUsageUpdate,
+  type LocalAgentWriteMode,
 } from "./local-agent-runtime.js";
 import { resolveExecutableCommand } from "./local-agent-command.js";
 
@@ -49,6 +53,7 @@ const ACP_COMMANDS: Record<AcpProvider, [string, ...string[]]> = {
 interface AcpConnectionLike {
   agent: {
     request(method: string, params?: unknown): Promise<unknown>;
+    cancel?(params: { sessionId: string }): Promise<void>;
   };
   close(error?: unknown): void;
   closed: Promise<void>;
@@ -123,7 +128,11 @@ export class AcpRuntime implements LocalAgentRuntime {
     });
   }
 
-  async run(input: LocalAgentRunInput, callbacks?: LocalAgentRunCallbacks) {
+  async run(
+    input: LocalAgentRunInput,
+    callbacks?: LocalAgentRunCallbacks,
+    control?: LocalAgentRunControl,
+  ) {
     return captureAgentProviderResult({
       provider: this.provider,
       operation: "run",
@@ -137,6 +146,7 @@ export class AcpRuntime implements LocalAgentRuntime {
             message: `${this.provider} ACP runtime is not running.`,
           });
         }
+        if (control?.signal.aborted) throw new DOMException("Aborted", "AbortError");
         const sessionId = await this.openSession(input, callbacks);
         if (this.activeSessions.has(sessionId)) {
           throw new TypeError(`${this.provider} ACP session ${sessionId} already has an active turn.`);
@@ -161,20 +171,39 @@ export class AcpRuntime implements LocalAgentRuntime {
           : undefined;
         try {
           queue.values.length = 0;
+          const cancel = () => {
+            const cancellation = this.connection.agent.cancel
+              ? this.connection.agent.cancel({ sessionId })
+              : this.connection.agent.request("session/cancel", { sessionId }).then(() => undefined);
+            void cancellation.catch(() => undefined);
+          };
+          control?.signal.addEventListener("abort", cancel, { once: true });
           const standardResponse = this.connection.agent.request("session/prompt", {
             sessionId,
             prompt: [{ type: "text", text: input.prompt }],
             ...(promptId ? { _meta: { promptId, requestId: promptId } } : {}),
           });
-          const response = completion
-            ? await Promise.race([standardResponse, completion])
-            : await standardResponse;
+          let response: unknown;
+          try {
+            response = completion
+              ? await Promise.race([standardResponse, completion])
+              : await standardResponse;
+          } finally {
+            control?.signal.removeEventListener("abort", cancel);
+          }
           if (completion && isGrokPromptCompletion(response)) {
             await yieldToAcpQueue();
           } else if (promptId) {
             this.grokCompletionRegistry?.markCompleted(sessionId, promptId);
           }
           const updates = queue.values.splice(0);
+          if (readString(response, "stopReason") === "cancelled") {
+            throw new DOMException("Aborted", "AbortError");
+          }
+          for (const update of updates) {
+            const progress = acpProgress(update);
+            if (progress) await callbacks?.onProgress?.(progress);
+          }
           const finalResponse = extractAcpText(updates);
           if (!finalResponse) {
             throw new AgentProviderProtocolError({
@@ -186,11 +215,14 @@ export class AcpRuntime implements LocalAgentRuntime {
               message: `${this.provider} ACP did not return a final assistant response.`,
             });
           }
+          const usage = acpUsage(input, response);
+          if (usage) await callbacks?.onUsage?.(usage);
           return {
             provider: this.provider,
             providerSessionId: sessionId,
             finalResponse,
             items: updates,
+            ...(usage ? { usage } : {}),
           };
         } finally {
           if (promptId) this.grokCompletionRegistry?.remove(sessionId, promptId);
@@ -236,7 +268,7 @@ export class AcpRuntime implements LocalAgentRuntime {
   private async openSession(input: LocalAgentRunInput, callbacks?: LocalAgentRunCallbacks): Promise<string> {
     if (input.providerSessionId) {
       if (this.liveSessions.has(input.providerSessionId)) {
-        this.sessionWriteModes.set(input.providerSessionId, input.writeMode ?? "allowed");
+        this.sessionWriteModes.set(input.providerSessionId, effectiveWriteMode(input));
         await callbacks?.onSessionId?.(input.providerSessionId);
         await this.configureSession(
           input.providerSessionId,
@@ -264,7 +296,7 @@ export class AcpRuntime implements LocalAgentRuntime {
       this.cacheSessionMetadata(input.providerSessionId, response);
       this.queues.set(input.providerSessionId, { values: [] });
       this.liveSessions.add(input.providerSessionId);
-      this.sessionWriteModes.set(input.providerSessionId, input.writeMode ?? "allowed");
+      this.sessionWriteModes.set(input.providerSessionId, effectiveWriteMode(input));
       await callbacks?.onSessionId?.(input.providerSessionId);
       await this.configureSession(input.providerSessionId, input, response, false);
       return input.providerSessionId;
@@ -289,7 +321,7 @@ export class AcpRuntime implements LocalAgentRuntime {
     this.cacheSessionMetadata(sessionId, response);
     this.queues.set(sessionId, { values: [] });
     this.liveSessions.add(sessionId);
-    this.sessionWriteModes.set(sessionId, input.writeMode ?? "allowed");
+    this.sessionWriteModes.set(sessionId, effectiveWriteMode(input));
     await callbacks?.onSessionId?.(sessionId);
     await this.configureSession(sessionId, input, response, true);
     return sessionId;
@@ -427,7 +459,19 @@ export class AcpLocalAgentDriver implements LocalAgentDriver {
   runtimeKey(context: LocalAgentRuntimeContext): string {
     const command = this.resolveCommand() ?? ACP_COMMANDS[this.provider][0];
     const writeMode = context.writeMode ?? "allowed";
-    return `acp:${this.provider}:${command}:${writeMode}:${resolve(context.workspaceRoot)}`;
+    return `acp:${this.provider}:${command}:${writeMode}:${resolve(context.workspaceRoot)}`
+      + (context.workflowRunId ? `:workflow:${context.workflowRunId}` : "");
+  }
+
+  capabilities() {
+    return {
+      cancellation: "turn",
+      structuredOutput: "validated_text",
+      usage: "unavailable",
+      correctionAuthority: "read_only",
+      permissionRequests: "preconfigured",
+      progress: "tools_and_text",
+    } as const;
   }
 
   async createRuntime(context: LocalAgentRuntimeContext) {
@@ -450,7 +494,7 @@ export class AcpLocalAgentDriver implements LocalAgentDriver {
         const args = acpCommandArgs(this.provider, context, this.env);
         const child = spawn(command, args, {
           cwd: resolve(context.workspaceRoot),
-          env: this.env,
+          env: localAgentWorkflowEnvironment(this.env, context),
           stdio: ["pipe", "pipe", "pipe"],
           detached: process.platform !== "win32",
           windowsHide: true,
@@ -790,6 +834,57 @@ function extractAcpText(updates: unknown[]): string {
     .trim();
 }
 
+function effectiveWriteMode(input: LocalAgentRunInput): LocalAgentWriteMode {
+  return input.toolPolicy === "read_only" || input.toolPolicy === "none"
+    ? "read_only"
+    : input.writeMode ?? "allowed";
+}
+
+function acpUsage(
+  input: LocalAgentRunInput,
+  response: unknown,
+): LocalAgentUsageUpdate | undefined {
+  const usage = asRecord(asRecord(response)?.usage);
+  if (!usage) return undefined;
+  const outputTokens = finiteNonnegative(usage.outputTokens);
+  if (outputTokens === undefined) return undefined;
+  return {
+    attemptId: input.attemptId ?? "untracked",
+    sequence: 1,
+    inputTokens: finiteNonnegative(usage.inputTokens),
+    outputTokens,
+    cacheReadTokens: finiteNonnegative(usage.cachedReadTokens),
+    cacheWriteTokens: finiteNonnegative(usage.cachedWriteTokens),
+    reasoningTokens: finiteNonnegative(usage.thoughtTokens),
+    final: true,
+  };
+}
+
+function acpProgress(value: unknown): LocalAgentProgressUpdate | undefined {
+  const update = asRecord(asRecord(value)?.update);
+  const kind = directString(update?.sessionUpdate);
+  if (kind === "agent_message_chunk") {
+    const content = asRecord(update?.content);
+    const text = content?.type === "text" ? directString(content.text) : undefined;
+    return text ? { type: "text", text: text.slice(0, 8 * 1024) } : undefined;
+  }
+  if (kind !== "tool_call" && kind !== "tool_call_update") return undefined;
+  const toolCall = asRecord(update?.toolCall) ?? update;
+  const toolName = directString(toolCall?.title) ?? directString(toolCall?.kind) ?? "tool";
+  const status = directString(toolCall?.status);
+  return {
+    type: "tool",
+    toolName,
+    status: status === "completed" || status === "failed"
+      ? "completed"
+      : kind === "tool_call" ? "started" : "updated",
+  };
+}
+
+function finiteNonnegative(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
 function isGrokPromptCompletion(value: unknown): boolean {
   const record = asRecord(value);
   return typeof record?.sessionId === "string";
diff --git a/src/local-agent-adapters.test.ts b/src/local-agent-adapters.test.ts
index 395072a1d..c61cfb5b5 100644
--- a/src/local-agent-adapters.test.ts
+++ b/src/local-agent-adapters.test.ts
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { delimiter } from "node:path";
 import {
   claudeCommandEnvironment,
+  createLocalAgentDrivers,
   extractOpenCodeFinalResponse,
   extractPiFinalResponse,
   extractPiProviderError,
@@ -9,6 +10,28 @@ import {
   resolveAcpEffortConfigUpdate,
 } from "./local-agent-adapters.js";
 import { removeDevspaceNodeModulesBinFromPath } from "./local-agent-path.js";
+import { localAgentCapabilities } from "./local-agent-runtime.js";
+
+const capabilityMatrix = Object.fromEntries(createLocalAgentDrivers({ env: {} }).map((driver) => [
+  driver.provider,
+  localAgentCapabilities(driver, {
+    agentId: `agt_${driver.provider}`,
+    provider: driver.provider,
+    workspaceRoot: "/tmp/project",
+  }, { prompt: "inspect", workspaceRoot: "/tmp/project" }),
+]));
+assert.equal(capabilityMatrix.codex?.structuredOutput, "native");
+assert.equal(capabilityMatrix.codex?.usage, "streaming");
+assert.equal(capabilityMatrix.claude?.structuredOutput, "native");
+assert.equal(capabilityMatrix.claude?.usage, "final");
+for (const provider of ["opencode", "pi"] as const) {
+  assert.equal(capabilityMatrix[provider]?.structuredOutput, "validated_text");
+  assert.equal(capabilityMatrix[provider]?.usage, "final");
+}
+for (const provider of ["cursor", "copilot", "grok"] as const) {
+  assert.equal(capabilityMatrix[provider]?.cancellation, "turn");
+  assert.equal(capabilityMatrix[provider]?.usage, "unavailable");
+}
 assert.deepEqual(
   resolveAcpModelConfigUpdate({
     sessionId: "session_model_1",
diff --git a/src/local-agent-cancellation.test.ts b/src/local-agent-cancellation.test.ts
new file mode 100644
index 000000000..1bf21875f
--- /dev/null
+++ b/src/local-agent-cancellation.test.ts
@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { Result, type Result as BetterResult } from "better-result";
+import {
+  AgentProviderCancelledError,
+  AgentProviderExecutionError,
+  type AgentProviderError,
+} from "./local-agent-errors.js";
+import { LocalAgentManager } from "./local-agent-manager.js";
+import type { LocalAgentProfile } from "./local-agent-profiles.js";
+import {
+  type LocalAgentDriver,
+  type LocalAgentRunInput,
+  type LocalAgentRunResult,
+  type LocalAgentRuntime,
+} from "./local-agent-runtime.js";
+import { LocalAgentRuntimePool } from "./local-agent-runtime-pool.js";
+import { LocalAgentStore } from "./local-agent-store.js";
+
+type Outcome = "success" | "failure" | "cancelled";
+
+class ControlledRuntime implements LocalAgentRuntime {
+  readonly provider = "codex" as const;
+  started = false;
+  input?: LocalAgentRunInput;
+  private releaseRun: (() => void) | undefined;
+
+  constructor(private readonly outcome: Outcome) {}
+
+  async run(input: LocalAgentRunInput): Promise<BetterResult<LocalAgentRunResult, AgentProviderError>> {
+    this.started = true;
+    this.input = input;
+    await new Promise<void>((resolve) => { this.releaseRun = resolve; });
+    if (this.outcome === "failure") {
+      return Result.err(new AgentProviderExecutionError({
+        code: "PROVIDER_EXECUTION_ERROR", provider: "codex", operation: "run",
+        retryable: false, message: "provider failed after cancellation request",
+      }));
+    }
+    if (this.outcome === "cancelled") {
+      return Result.err(new AgentProviderCancelledError({
+        code: "PROVIDER_CANCELLED", provider: "codex", operation: "run",
+        retryable: false, message: "provider confirmed cancellation",
+      }));
+    }
+    return Result.ok({
+      provider: "codex", providerSessionId: "thread_late",
+      finalResponse: `late:${input.prompt}`, items: [],
+    });
+  }
+
+  release(): void { this.releaseRun?.(); }
+  releaseSession(): Promise<void> { return Promise.resolve(); }
+  close(): Promise<void> { this.release(); return Promise.resolve(); }
+  isAlive(): boolean { return true; }
+}
+
+for (const expected of [
+  { outcome: "success", status: "completed" },
+  { outcome: "failure", status: "failed" },
+  { outcome: "cancelled", status: "stopped" },
+] as const) {
+  test(`stop fences the exact turn until the provider settles as ${expected.status}`, async () => {
+    const root = await mkdtemp(join(tmpdir(), "devspace-agent-cancel-test-"));
+    const store = new LocalAgentStore(join(root, "state"));
+    let runtime: ControlledRuntime | undefined;
+    const driver: LocalAgentDriver = {
+      provider: "codex",
+      runtimeKey: (context) => context.agentId,
+      createRuntime: async () => {
+        runtime = new ControlledRuntime(expected.outcome);
+        return Result.ok(runtime);
+      },
+    };
+    const profile: LocalAgentProfile = {
+      name: "reviewer", description: "Test reviewer", provider: "codex",
+      filePath: join(root, "reviewer.md"), body: "Review only.", disabled: false,
+    };
+    const manager = new LocalAgentManager({
+      store, drivers: [driver], pool: new LocalAgentRuntimePool(),
+      loadProfiles: async () => [profile], allowedRoots: [root],
+      subagents: {
+        enabled: true, instructions: "on-demand",
+        providers: [{ id: "codex", enabled: true }],
+      },
+    });
+
+    try {
+      const started = unwrap(await manager.startTurn({
+        target: "reviewer", prompt: "hold", workspaceId: "ws_test", workspaceRoot: root,
+        workflowRunId: "wfr_1", workflowStepId: "wfs_1", workflowAttemptId: "wfa_1",
+      }));
+      await waitFor(() => runtime?.started === true);
+      assert.equal(runtime?.input?.workflowRunId, "wfr_1");
+      assert.equal(runtime?.input?.workflowStepId, "wfs_1");
+      assert.equal(runtime?.input?.workflowAttemptId, "wfa_1");
+      let stopSettled = false;
+      const stopping = manager.stop(started.agent.id, started.turn.id, {
+        workspaceId: "ws_test", workspaceRoot: root,
+      }).then((result) => { stopSettled = true; return result; });
+
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      assert.equal(stopSettled, false, "stop must wait for provider acknowledgement");
+      const conflict = await manager.continue(started.agent.id, "next", {}, {
+        workspaceId: "ws_test", workspaceRoot: root,
+      });
+      assert.equal(conflict.isErr(), true, "the session remains fenced while cancellation is unconfirmed");
+      if (conflict.isErr()) assert.equal(conflict.error.code, "AGENT_CONFLICT");
+
+      runtime?.release();
+      const stopped = unwrap(await stopping);
+      assert.equal(stopped.status, expected.status);
+      if (expected.outcome === "success") assert.match(stopped.response ?? "", /late:/);
+      if (expected.outcome === "failure") assert.equal(stopped.errorCode, "PROVIDER_EXECUTION_ERROR");
+      if (expected.outcome === "cancelled") assert.equal(stopped.errorCode, "AGENT_STOPPED");
+    } finally {
+      await manager.close();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+}
+
+function unwrap<T, E>(result: BetterResult<T, E>): T {
+  if (result.isErr()) throw result.error;
+  return result.value;
+}
+
+async function waitFor(check: () => boolean): Promise<void> {
+  const deadline = Date.now() + 2_000;
+  while (!check()) {
+    if (Date.now() >= deadline) throw new Error("Timed out waiting for condition.");
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
diff --git a/src/local-agent-catalog.ts b/src/local-agent-catalog.ts
index c19904ba2..63468198f 100644
--- a/src/local-agent-catalog.ts
+++ b/src/local-agent-catalog.ts
@@ -68,6 +68,7 @@ export function buildLocalAgentCatalog(
           provider: profile.provider,
           model: profile.model ?? provider.model,
           effort: profile.effort ?? provider.effort,
+          writeMode: profile.writeMode,
         };
       }),
   };
diff --git a/src/local-agent-claude.test.ts b/src/local-agent-claude.test.ts
index 14e364005..9c94aa21f 100644
--- a/src/local-agent-claude.test.ts
+++ b/src/local-agent-claude.test.ts
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import {
   ClaudeLocalAgentDriver,
   claudeAuthoritySettings,
+  claudeQueryOptions,
   type ClaudeQueryLike,
   type ClaudeUserMessage,
 } from "./local-agent-claude.js";
@@ -33,6 +34,13 @@ class FakeClaudeQuery implements ClaudeQueryLike, AsyncIterator<unknown> {
         type: "result",
         session_id: "claude_session_1",
         result: `response:${next.value.message.content}`,
+        usage: {
+          input_tokens: 3,
+          output_tokens: 5,
+          cache_read_input_tokens: 1,
+          cache_creation_input_tokens: 2,
+        },
+        ...(next.value.message.content === "structured" ? { structured_output: { ok: true } } : {}),
       },
     };
   }
@@ -88,14 +96,17 @@ assert.equal(runtimeResult.isOk(), true);
 if (runtimeResult.isErr()) throw runtimeResult.error;
 const runtime = runtimeResult.value;
 const sessionIds: string[] = [];
+const usageUpdates: unknown[] = [];
 const firstResult = await runtime.run({
   prompt: "first",
   workspaceRoot: "/tmp/project",
   model: "sonnet",
   effort: "high",
   writeMode: "read_only",
+  attemptId: "attempt_claude_1",
 }, {
   onSessionId: (sessionId) => { sessionIds.push(sessionId); },
+  onUsage: (usage) => { usageUpdates.push(usage); },
 });
 assert.equal(firstResult.isOk(), true);
 if (firstResult.isErr()) throw firstResult.error;
@@ -125,6 +136,17 @@ assert.equal(lastOptions?.permissionMode, "dontAsk");
 assert.equal(lastOptions?.allowDangerouslySkipPermissions, undefined);
 assert.deepEqual(lastOptions?.allowedTools, ["Read(/**)", "Edit(/**)", "Bash"]);
 assert.equal(lastOptions?.pathToClaudeCodeExecutable, undefined);
+const workflowOptions = claudeQueryOptions(context, {
+  prompt: "workflow", workspaceRoot: "/tmp/project", workflowRunId: "wfr_1",
+  workflowStepId: "wfs_1", workflowAttemptId: "wfa_1",
+}, { PATH: "/usr/bin" });
+assert.deepEqual(workflowOptions.disallowedTools, ["Agent", "Task"]);
+assert.deepEqual(workflowOptions.env, {
+  PATH: "/usr/bin",
+  DEVSPACE_WORKFLOW_RUN_ID: "wfr_1",
+  DEVSPACE_WORKFLOW_STEP_ID: "wfs_1",
+  DEVSPACE_WORKFLOW_ATTEMPT_ID: "wfa_1",
+});
 const initialSandbox = lastOptions?.sandbox as Record<string, unknown>;
 assert.equal(initialSandbox.enabled, true);
 assert.equal(initialSandbox.failIfUnavailable, true);
@@ -154,6 +176,15 @@ assert.deepEqual((fullSettings.sandbox as Record<string, unknown>), {
   allowUnsandboxedCommands: true,
 });
 assert.deepEqual(sessionIds, ["claude_session_1"]);
+assert.deepEqual(usageUpdates, [{
+  attemptId: "attempt_claude_1",
+  sequence: 1,
+  inputTokens: 3,
+  outputTokens: 5,
+  cacheReadTokens: 1,
+  cacheWriteTokens: 2,
+  final: true,
+}]);
 assert.deepEqual(query?.permissionModes, ["dontAsk", "dontAsk", "bypassPermissions"]);
 assert.equal(query?.flagSettings.length, 3);
 assert.equal(query?.flagSettings[0]?.alwaysThinkingEnabled, true);
@@ -176,6 +207,24 @@ await runtime.close();
 await runtime.close();
 assert.equal(query?.closeCount, 1);
 
+const structuredContext = { ...context, outputSchema: { type: "object" } } as const;
+const structuredRuntime = await driver.createRuntime(structuredContext);
+assert.equal(structuredRuntime.isOk(), true);
+assert.deepEqual(lastOptions?.outputFormat, {
+  type: "json_schema",
+  schema: { type: "object" },
+});
+if (structuredRuntime.isErr()) throw structuredRuntime.error;
+const structuredResult = await structuredRuntime.value.run({
+  prompt: "structured",
+  workspaceRoot: "/tmp/project",
+  outputSchema: { type: "object" },
+});
+assert.equal(structuredResult.isOk(), true);
+if (structuredResult.isErr()) throw structuredResult.error;
+assert.deepEqual(structuredResult.value.structuredOutput, { ok: true });
+await structuredRuntime.value.close();
+
 const coldRuntime = await driver.createRuntime({ ...context, providerSessionId: "cold_session" });
 assert.equal(coldRuntime.isOk(), true);
 assert.equal(lastOptions?.resume, "cold_session");
diff --git a/src/local-agent-claude.ts b/src/local-agent-claude.ts
index a639f2f46..82184036e 100644
--- a/src/local-agent-claude.ts
+++ b/src/local-agent-claude.ts
@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import {
   AgentProviderExecutionError,
   AgentProviderProtocolError,
@@ -6,16 +7,19 @@ import {
   isProgrammerDefect,
 } from "./local-agent-errors.js";
 import type { LocalAgentProvider } from "./local-agent-profiles.js";
-import type {
-  LocalAgentDriver,
-  LocalAgentRunCallbacks,
-  LocalAgentRunInput,
-  LocalAgentRunResult,
-  LocalAgentRuntime,
-  LocalAgentRuntimeContext,
-  LocalAgentWriteMode,
+import {
+  localAgentWorkflowEnvironment,
+  type LocalAgentDriver,
+  type LocalAgentProgressUpdate,
+  type LocalAgentRunCallbacks,
+  type LocalAgentRunControl,
+  type LocalAgentRunInput,
+  type LocalAgentRunResult,
+  type LocalAgentRuntime,
+  type LocalAgentRuntimeContext,
+  type LocalAgentUsageUpdate,
+  type LocalAgentWriteMode,
 } from "./local-agent-runtime.js";
-
 type ClaudePermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk" | "auto";
 
 const CLAUDE_WORKSPACE_ALLOWED_TOOLS = [
@@ -28,6 +32,7 @@ const CLAUDE_WORKSPACE_ALLOWED_TOOLS = [
 
 export interface ClaudeQueryLike extends AsyncIterable<unknown> {
   close(): void;
+  interrupt?(): Promise<void>;
   setPermissionMode(mode: ClaudePermissionMode): Promise<void>;
   applyFlagSettings(settings: Record<string, unknown>): Promise<void>;
   setModel?(model?: string): Promise<void>;
@@ -92,7 +97,11 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
     this.iterator = query[Symbol.asyncIterator]();
   }
 
-  async run(input: LocalAgentRunInput, callbacks?: LocalAgentRunCallbacks) {
+  async run(
+    input: LocalAgentRunInput,
+    callbacks?: LocalAgentRunCallbacks,
+    control?: LocalAgentRunControl,
+  ) {
     return captureAgentProviderResult({
       provider: "claude",
       operation: "run",
@@ -107,7 +116,8 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
           });
         }
         if (this.providerSessionId) await callbacks?.onSessionId?.(this.providerSessionId);
-        const flagSettings = claudeAuthoritySettings(input.workspaceRoot, input.writeMode);
+        const effectiveWriteMode = input.toolPolicy === "read_only" ? "read_only" : input.writeMode;
+        const flagSettings = claudeAuthoritySettings(input.workspaceRoot, effectiveWriteMode);
         if (input.effort) {
           Object.assign(flagSettings, {
             alwaysThinkingEnabled: true,
@@ -115,7 +125,7 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
           });
         }
         await this.query.applyFlagSettings(flagSettings);
-        await this.query.setPermissionMode(claudePermissionMode(input.writeMode));
+        await this.query.setPermissionMode(claudePermissionMode(effectiveWriteMode));
         if (input.model && this.query.setModel) await this.query.setModel(input.model);
         this.inputQueue.push({
           type: "user",
@@ -123,12 +133,24 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
           parent_tool_use_id: null,
         });
 
+        let cancellation: Promise<boolean> | undefined;
+        const abort = () => {
+          cancellation ??= this.query.interrupt
+            ? this.query.interrupt().then(() => true, () => false)
+            : Promise.resolve(false);
+        };
+        if (control?.signal.aborted) throw new DOMException("Aborted", "AbortError");
+        control?.signal.addEventListener("abort", abort, { once: true });
         const items: unknown[] = [];
-        for (;;) {
+        try {
+          for (;;) {
           let next: IteratorResult<unknown>;
           try {
             next = await this.iterator.next();
           } catch (error) {
+            if (control?.signal.aborted && await cancellation) {
+              throw new DOMException("Aborted", "AbortError");
+            }
             this.alive = false;
             if (isProgrammerDefect(error)) throw error;
             throw new AgentProviderUnavailableError({
@@ -140,6 +162,9 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
               message: "Claude query stream failed.",
             });
           }
+          if (control?.signal.aborted && await cancellation) {
+            throw new DOMException("Aborted", "AbortError");
+          }
           if (next.done) {
             this.alive = false;
             throw new AgentProviderProtocolError({
@@ -153,6 +178,8 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
           const message = next.value;
           items.push(message);
           const record = asRecord(message);
+          const progress = claudeProgress(record);
+          if (progress) await callbacks?.onProgress?.(progress);
           if (typeof record?.session_id === "string") {
             const previousSessionId = this.providerSessionId;
             this.providerSessionId = record.session_id;
@@ -174,7 +201,8 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
             });
           }
           const finalResponse = typeof record.result === "string" ? record.result.trim() : "";
-          if (!finalResponse) {
+          const structuredOutput = jsonValue(record.structured_output);
+          if (!finalResponse && structuredOutput === undefined) {
             throw new AgentProviderProtocolError({
               code: "PROVIDER_PROTOCOL_ERROR",
               provider: "claude",
@@ -183,12 +211,19 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
               message: "Claude did not return a final assistant response.",
             });
           }
+          const usage = claudeUsage(input, record);
+          if (usage) await callbacks?.onUsage?.(usage);
           return {
             provider: this.provider,
             providerSessionId: this.providerSessionId ?? null,
             finalResponse,
             items,
+            ...(structuredOutput === undefined ? {} : { structuredOutput }),
+            ...(usage ? { usage } : {}),
           };
+          }
+        } finally {
+          control?.signal.removeEventListener("abort", abort);
         }
       },
     });
@@ -222,7 +257,25 @@ export class ClaudeLocalAgentDriver implements LocalAgentDriver {
 
   runtimeKey(context: LocalAgentRuntimeContext): string {
     const authority = context.writeMode === "full_access" ? "full_access" : "restricted";
-    return `claude:${context.agentId}:${authority}`;
+    const schema = context.outputSchema
+      ? createHash("sha256").update(JSON.stringify(context.outputSchema)).digest("hex").slice(0, 12)
+      : undefined;
+    const specialization = context.toolPolicy || schema
+      ? `:${context.toolPolicy ?? "normal"}:${schema ?? "text"}`
+      : "";
+    const workflow = context.workflowRunId ? `:workflow:${context.workflowRunId}` : "";
+    return `claude:${context.agentId}:${authority}${specialization}${workflow}`;
+  }
+
+  capabilities() {
+    return {
+      cancellation: "turn",
+      structuredOutput: "native",
+      usage: "final",
+      correctionAuthority: "no_tools",
+      permissionRequests: "preconfigured",
+      progress: "tools_and_text",
+    } as const;
   }
 
   async createRuntime(context: LocalAgentRuntimeContext) {
@@ -239,6 +292,8 @@ export class ClaudeLocalAgentDriver implements LocalAgentDriver {
           writeMode: context.writeMode,
           model: context.model,
           effort: context.effort,
+          outputSchema: context.outputSchema,
+          toolPolicy: context.toolPolicy,
         };
         const query = await this.factory({
           context,
@@ -274,17 +329,21 @@ export function claudeQueryOptions(
     cwd: input.workspaceRoot,
     ...(input.model ? { model: input.model } : {}),
     ...(input.effort ? { thinking: { type: "adaptive" }, effort: input.effort } : {}),
+    ...(input.outputSchema ? { outputFormat: { type: "json_schema", schema: input.outputSchema } } : {}),
     ...(context.providerSessionId ? { resume: context.providerSessionId } : {}),
     permissionMode,
     // Restricted runtimes stay warm across read_only/allowed turns. Keep the
     // workspace capabilities static and narrow individual turns with deny rules.
-    ...(input.writeMode === "full_access"
+    ...(input.toolPolicy === "none"
+      ? { allowedTools: [] }
+      : input.writeMode === "full_access"
       ? {}
       : { allowedTools: [...CLAUDE_WORKSPACE_ALLOWED_TOOLS] }),
+    ...(input.workflowRunId ? { disallowedTools: ["Agent", "Task"] } : {}),
     sandbox: authority.sandbox,
     settings: authority.settings,
     ...(input.writeMode === "full_access" ? { allowDangerouslySkipPermissions: true } : {}),
-    env: claudeCommandEnvironment(env),
+    env: localAgentWorkflowEnvironment(claudeCommandEnvironment(env), input),
     ...(executable ? { pathToClaudeCodeExecutable: executable } : {}),
   };
 }
@@ -385,3 +444,65 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
     ? value as Record<string, unknown>
     : undefined;
 }
+
+function claudeUsage(
+  input: LocalAgentRunInput,
+  result: Record<string, unknown>,
+): LocalAgentUsageUpdate | undefined {
+  const usage = asRecord(result.usage);
+  if (!usage) return undefined;
+  const outputTokens = finiteNonnegative(usage.output_tokens);
+  if (outputTokens === undefined) return undefined;
+  return {
+    attemptId: input.attemptId ?? "untracked",
+    sequence: 1,
+    inputTokens: finiteNonnegative(usage.input_tokens),
+    outputTokens,
+    cacheReadTokens: finiteNonnegative(usage.cache_read_input_tokens),
+    cacheWriteTokens: finiteNonnegative(usage.cache_creation_input_tokens),
+    final: true,
+  };
+}
+
+function claudeProgress(message: Record<string, unknown> | undefined): LocalAgentProgressUpdate | undefined {
+  if (message?.type !== "stream_event") return undefined;
+  const event = asRecord(message.event);
+  if (event?.type === "content_block_start") {
+    const block = asRecord(event.content_block);
+    if (block?.type === "tool_use" && typeof block.name === "string") {
+      return { type: "tool", toolName: block.name, status: "started" };
+    }
+  }
+  if (event?.type === "content_block_delta") {
+    const delta = asRecord(event.delta);
+    if (delta?.type === "text_delta" && typeof delta.text === "string" && delta.text) {
+      return { type: "text", text: delta.text.slice(0, 8 * 1024) };
+    }
+  }
+  return undefined;
+}
+
+function jsonValue(value: unknown): LocalAgentRunResult["structuredOutput"] | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (Array.isArray(value)) {
+    const result = value.map(jsonValue);
+    return result.some((entry, index) => entry === undefined && value[index] !== undefined)
+      ? undefined
+      : result as LocalAgentRunResult["structuredOutput"];
+  }
+  const record = asRecord(value);
+  if (!record || Object.getPrototypeOf(value) !== Object.prototype) return undefined;
+  const result: Record<string, Exclude<LocalAgentRunResult["structuredOutput"], undefined>> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    const parsed = jsonValue(entry);
+    if (parsed === undefined) return undefined;
+    result[key] = parsed;
+  }
+  return result;
+}
+
+function finiteNonnegative(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
diff --git a/src/local-agent-client.ts b/src/local-agent-client.ts
index 5aa5bce35..5e373c1bb 100644
--- a/src/local-agent-client.ts
+++ b/src/local-agent-client.ts
@@ -35,7 +35,8 @@ import {
   type LocalAgentDaemonResponse,
   type LocalAgentDaemonStatus,
 } from "./local-agent-daemon-protocol.js";
-import { localAgentProviderConfigRevision } from "./local-agent-config.js";
+import { executionConfigRevision } from "./workflow-config.js";
+import { decodeWorkflowReply, type WorkflowRequest, type WorkflowReply } from "./workflow-protocol.js";
 import {
   LOCAL_AGENT_DAEMON_PROTOCOL_VERSION,
   ensureLocalAgentDaemonSecret,
@@ -107,6 +108,21 @@ export class LocalAgentClient {
     return this.start(input);
   }
 
+  async workflow(input: WorkflowRequest): Promise<WorkflowReply> {
+    const timeout = input.operation === "wait"
+      ? (input.input.timeoutMs ?? 30_000) + this.requestTimeoutMs
+      : this.requestTimeoutMs;
+    const result = await this.request("workflow.request", input, timeout);
+    if (result.isErr()) return { ok: false, error: {
+      code: result.error.code, message: result.error.message, retryable: result.error.retryable,
+    } };
+    const decoded = decodeValue(result.value, "workflow.request", decodeWorkflowReply);
+    if (decoded.isErr()) return { ok: false, error: {
+      code: decoded.error.code, message: decoded.error.message, retryable: decoded.error.retryable,
+    } };
+    return decoded.value;
+  }
+
   async start(
     input: StartLocalAgentInput,
   ): Promise<BetterResult<LocalAgentRecord, AgentStartError | AgentDaemonError>> {
@@ -272,7 +288,7 @@ export class LocalAgentClient {
     const decoded = decodeValue(response.value.result, "hello", decodeDaemonHello);
     if (decoded.isErr()) return decoded;
     if (!decoded.value.configMatches) {
-      if (allowStaleBusyConfig && decoded.value.status.activeTurns > 0) {
+      if (allowStaleBusyConfig && (decoded.value.status.activeTurns > 0 || (decoded.value.status.activeWorkflows ?? 0) > 0)) {
         return Result.ok(decoded.value.status);
       }
       return this.replaceIdleChangedDaemon(authToken.value, decoded.value.status);
@@ -288,11 +304,11 @@ export class LocalAgentClient {
       code: "DAEMON_CONFIG_CHANGED",
       operation: "startup",
       retryable: true,
-      message: status.activeTurns > 0
-        ? "The local agent daemon is running active turns with an older provider configuration. Retry after they finish."
+      message: status.activeTurns > 0 || (status.activeWorkflows ?? 0) > 0
+        ? "The local agent daemon is running active turns or workflows with an older execution configuration. Retry after they finish."
         : "The local agent daemon is using an older provider configuration.",
     });
-    if (status.activeTurns > 0) return Result.err(changed);
+    if (status.activeTurns > 0 || (status.activeWorkflows ?? 0) > 0) return Result.err(changed);
     return this.stopIdleDaemon(authToken, LOCAL_AGENT_DAEMON_PROTOCOL_VERSION, status, changed);
   }
 
@@ -312,7 +328,7 @@ export class LocalAgentClient {
     if (statusResponse.isErr() || !statusResponse.value.ok) return Result.err(mismatch);
     const status = decodeValue(statusResponse.value.result, "hello", decodeDaemonStatus);
     if (status.isErr()) return status;
-    if (status.value.activeTurns > 0) {
+    if (status.value.activeTurns > 0 || (status.value.activeWorkflows ?? 0) > 0) {
       return Result.err(new AgentDaemonProtocolMismatchError({
         code: "DAEMON_PROTOCOL_MISMATCH",
         operation: "startup",
@@ -388,7 +404,9 @@ export class LocalAgentClient {
     params: Extract<LocalAgentDaemonRequest, { method: M }>['params'],
     timeoutMs: number | null = this.requestTimeoutMs,
   ): Promise<BetterResult<unknown, RequestError<M>>> {
-    const ready = await (isObservationRequest(method)
+    const observation = isObservationRequest(method) || (method === "workflow.request"
+      && ["get", "wait", "list", "control"].includes((params as WorkflowRequest).operation));
+    const ready = await (observation
       ? this.ensureReadyForObservation()
       : this.ensureReady());
     if (ready.isErr()) return ready as BetterResult<unknown, RequestError<M>>;
@@ -496,12 +514,13 @@ function isObservationRequest(
 }
 
 export function createLocalAgentClient(
-  config: Pick<ServerConfig, "configDir" | "stateDir" | "subagents">,
+  config: Pick<ServerConfig, "configDir" | "stateDir" | "subagents" | "workflows">
+    & Partial<Pick<ServerConfig, "allowedRoots" | "worktreeRoot">>,
 ): LocalAgentClient {
   return new LocalAgentClient({
     configDir: config.configDir,
     stateDir: config.stateDir,
-    configRevision: localAgentProviderConfigRevision(config.subagents),
+    configRevision: executionConfigRevision(config),
   });
 }
 
@@ -701,6 +720,7 @@ function isRequestError(
     case "daemon.status":
     case "daemon.stop":
     case "daemon.logs":
+    case "workflow.request":
       return false;
   }
 }
diff --git a/src/local-agent-codex.test.ts b/src/local-agent-codex.test.ts
index ee115e54d..091ea7e5e 100644
--- a/src/local-agent-codex.test.ts
+++ b/src/local-agent-codex.test.ts
@@ -45,6 +45,7 @@ if (process.platform !== "win32") {
   await writeFile(command, `#!/usr/bin/env node
 import readline from "node:readline";
 let turn = 0;
+const active = new Map();
 const output = (value) => process.stdout.write(JSON.stringify(value) + "\\n");
 readline.createInterface({ input: process.stdin }).on("line", (line) => {
   const message = JSON.parse(line);
@@ -64,6 +65,8 @@ readline.createInterface({ input: process.stdin }).on("line", (line) => {
     turn += 1;
     const turnId = "turn_" + turn;
     output({ id: message.id, result: { turn: { id: turnId } } });
+    active.set(turnId, { threadId: message.params.threadId, prompt: message.params.input[0].text });
+    if (message.params.input[0].text === "hold" || message.params.input[0].text === "ignore interrupt") return;
     setImmediate(() => {
       if (message.params.input[0].text === "fail") {
         output({ method: "turn/completed", params: { threadId: message.params.threadId, turn: { id: turnId, status: "failed", error: { message: "fake failure" } } } });
@@ -75,10 +78,28 @@ readline.createInterface({ input: process.stdin }).on("line", (line) => {
       }
       const item = { type: "agentMessage", text: message.params.input[0].text === "policy"
         ? JSON.stringify(message.params.sandboxPolicy)
+        : message.params.input[0].text === "structured"
+          ? JSON.stringify({ ok: true })
         : "fake response " + turn };
       output({ method: "item/completed", params: { threadId: message.params.threadId, turnId, item } });
+      output({ method: "thread/tokenUsage/updated", params: { threadId: message.params.threadId, turnId, tokenUsage: { last: { inputTokens: 3, outputTokens: 5, cachedInputTokens: 1, cacheWriteInputTokens: 2, reasoningOutputTokens: 4 } } } });
       output({ method: "turn/completed", params: { threadId: message.params.threadId, turn: { id: turnId, status: "completed", items: [item] } } });
+      active.delete(turnId);
     });
+    return;
+  }
+  if (message.method === "turn/interrupt") {
+    output({ id: message.id, result: {} });
+    const current = active.get(message.params.turnId);
+    const threadId = current?.threadId;
+    if (current?.prompt === "ignore interrupt") {
+      const item = { type: "agentMessage", text: "late success" };
+      output({ method: "turn/completed", params: { threadId, turn: { id: message.params.turnId, status: "completed", items: [item] } } });
+      active.delete(message.params.turnId);
+      return;
+    }
+    output({ method: "turn/completed", params: { threadId, turn: { id: message.params.turnId, status: "interrupted", items: [] } } });
+    active.delete(message.params.turnId);
   }
 });
 `, { mode: 0o700 });
@@ -88,13 +109,18 @@ readline.createInterface({ input: process.stdin }).on("line", (line) => {
   try {
     await runtime.initialize();
     let callbackSessionId: string | undefined;
+    const usageUpdates: unknown[] = [];
     const firstResult = await runtime.run({
       prompt: "first",
       workspaceRoot: "/tmp/project",
       writeMode: "read_only",
       model: "gpt-5.4",
       effort: "high",
-    }, { onSessionId: (id) => { callbackSessionId = id; } });
+      attemptId: "attempt_codex_1",
+    }, {
+      onSessionId: (id) => { callbackSessionId = id; },
+      onUsage: (usage) => { usageUpdates.push(usage); },
+    });
     assert.equal(firstResult.isOk(), true);
     if (firstResult.isErr()) throw firstResult.error;
     const first = firstResult.value;
@@ -109,6 +135,16 @@ readline.createInterface({ input: process.stdin }).on("line", (line) => {
     assert.equal(first.providerSessionId, "thread_new");
     assert.equal(callbackSessionId, "thread_new");
     assert.equal(first.finalResponse, "fake response 1");
+    assert.deepEqual(usageUpdates.at(-1), {
+      attemptId: "attempt_codex_1",
+      sequence: 2,
+      inputTokens: 3,
+      outputTokens: 5,
+      cacheReadTokens: 1,
+      cacheWriteTokens: 2,
+      reasoningTokens: 4,
+      final: true,
+    });
     assert.equal(resumed.providerSessionId, "thread_new");
     assert.equal(resumed.finalResponse, "fake response 2");
     const failed = await runtime.run({
@@ -144,6 +180,49 @@ readline.createInterface({ input: process.stdin }).on("line", (line) => {
     assert.equal(policy.isOk(), true);
     if (policy.isErr()) throw policy.error;
     assert.deepEqual(JSON.parse(policy.value.finalResponse), { type: "workspaceWrite", networkAccess: true });
+    const correctionPolicy = await runtime.run({
+      prompt: "policy",
+      workspaceRoot: "/tmp/project",
+      writeMode: "full_access",
+      toolPolicy: "read_only",
+      providerSessionId: first.providerSessionId ?? undefined,
+    });
+    assert.equal(correctionPolicy.isOk(), true);
+    if (correctionPolicy.isErr()) throw correctionPolicy.error;
+    assert.deepEqual(JSON.parse(correctionPolicy.value.finalResponse), { type: "readOnly" });
+    const structured = await runtime.run({
+      prompt: "structured",
+      workspaceRoot: "/tmp/project",
+      providerSessionId: first.providerSessionId ?? undefined,
+      outputSchema: { type: "object" },
+    });
+    assert.equal(structured.isOk(), true);
+    if (structured.isErr()) throw structured.error;
+    assert.deepEqual(structured.value.structuredOutput, { ok: true });
+
+    const controller = new AbortController();
+    const held = runtime.run({
+      prompt: "hold",
+      workspaceRoot: "/tmp/project",
+      providerSessionId: first.providerSessionId ?? undefined,
+    }, undefined, { signal: controller.signal });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    controller.abort();
+    const cancelled = await held;
+    assert.equal(cancelled.isErr(), true);
+    if (cancelled.isErr()) assert.equal(cancelled.error.code, "PROVIDER_CANCELLED");
+    const ignoredController = new AbortController();
+    const ignored = runtime.run({
+      prompt: "ignore interrupt",
+      workspaceRoot: "/tmp/project",
+      providerSessionId: first.providerSessionId ?? undefined,
+    }, undefined, { signal: ignoredController.signal });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    ignoredController.abort();
+    const lateSuccess = await ignored;
+    assert.equal(lateSuccess.isOk(), true, "an abort signal alone must not overwrite the provider's terminal result");
+    if (lateSuccess.isErr()) throw lateSuccess.error;
+    assert.equal(lateSuccess.value.finalResponse, "late success");
     await runtime.releaseSession("thread_new");
   } finally {
     await runtime.close();
diff --git a/src/local-agent-codex.ts b/src/local-agent-codex.ts
index fe3161ec8..b1bbb0941 100644
--- a/src/local-agent-codex.ts
+++ b/src/local-agent-codex.ts
@@ -11,14 +11,18 @@ import {
 import { removeDevspaceNodeModulesBinFromPath } from "./local-agent-path.js";
 import { terminateProcessTree } from "./process-platform.js";
 import { DEVSPACE_VERSION } from "./version.js";
-import type {
-  LocalAgentDriver,
-  LocalAgentRunCallbacks,
-  LocalAgentRunInput,
-  LocalAgentRunResult,
-  LocalAgentRuntime,
-  LocalAgentRuntimeContext,
-  LocalAgentWriteMode,
+import {
+  localAgentWorkflowEnvironment,
+  type LocalAgentDriver,
+  type LocalAgentProgressUpdate,
+  type LocalAgentRunCallbacks,
+  type LocalAgentRunControl,
+  type LocalAgentRunInput,
+  type LocalAgentRunResult,
+  type LocalAgentRuntime,
+  type LocalAgentRuntimeContext,
+  type LocalAgentUsageUpdate,
+  type LocalAgentWriteMode,
 } from "./local-agent-runtime.js";
 
 export interface ResolvedCodexCommand {
@@ -76,6 +80,7 @@ export function parseCodexVersion(output: string | undefined): string | undefine
 
 export interface CodexAppServerRuntimeOptions {
   command: string;
+  args?: string[];
   env: NodeJS.ProcessEnv;
   version?: string;
 }
@@ -88,7 +93,7 @@ export class CodexAppServerRuntime implements LocalAgentRuntime {
   private closePromise?: Promise<void>;
 
   constructor(private readonly options: CodexAppServerRuntimeOptions) {
-    this.child = spawn(options.command, ["app-server"], {
+    this.child = spawn(options.command, options.args ?? ["app-server"], {
       env: options.env,
       stdio: ["pipe", "pipe", "pipe"],
       detached: process.platform !== "win32",
@@ -116,7 +121,11 @@ export class CodexAppServerRuntime implements LocalAgentRuntime {
     this.rpc.notify("initialized");
   }
 
-  async run(input: LocalAgentRunInput, callbacks?: LocalAgentRunCallbacks) {
+  async run(
+    input: LocalAgentRunInput,
+    callbacks?: LocalAgentRunCallbacks,
+    control?: LocalAgentRunControl,
+  ) {
     return captureAgentProviderResult({
       provider: this.provider,
       operation: "run",
@@ -147,8 +156,26 @@ export class CodexAppServerRuntime implements LocalAgentRuntime {
         }
 
         await callbacks?.onSessionId?.(threadId);
-        const completed = await this.rpc.runTurn(threadId, turnParams(input, threadId));
+        let usageSequence = 0;
+        let latestUsage: LocalAgentUsageUpdate | undefined;
+        const completed = await this.rpc.runTurn(
+          threadId,
+          turnParams(input, threadId),
+          control?.signal,
+          async (event) => {
+            const progress = codexProgress(event);
+            if (progress) await callbacks?.onProgress?.(progress);
+            const usage = codexUsage(input, event, ++usageSequence, false);
+            if (usage) {
+              latestUsage = usage;
+              await callbacks?.onUsage?.(usage);
+            } else {
+              usageSequence -= 1;
+            }
+          },
+        );
         const parsed = parseCompletedTurn(completed.event.params, completed.items);
+        if (parsed.cancelled) throw new DOMException("Aborted", "AbortError");
         if (parsed.failure) {
           throw new AgentProviderExecutionError({
             code: "PROVIDER_EXECUTION_ERROR",
@@ -169,11 +196,16 @@ export class CodexAppServerRuntime implements LocalAgentRuntime {
             message: "Codex did not return a final assistant response.",
           });
         }
+        const usage = latestUsage ? { ...latestUsage, sequence: usageSequence + 1, final: true } : undefined;
+        if (usage) await callbacks?.onUsage?.(usage);
+        const structuredOutput = input.outputSchema ? parseJsonValue(parsed.finalResponse) : undefined;
         return {
           provider: this.provider,
           providerSessionId: threadId,
           finalResponse: parsed.finalResponse.trim(),
           items: parsed.items,
+          ...(structuredOutput === undefined ? {} : { structuredOutput }),
+          ...(usage ? { usage } : {}),
         };
       },
     });
@@ -240,14 +272,25 @@ export class CodexLocalAgentDriver implements LocalAgentDriver {
     private readonly commandResolver: CodexCommandResolver = resolveCodexCommand,
   ) {}
 
-  runtimeKey(_context: LocalAgentRuntimeContext): string {
+  runtimeKey(context: LocalAgentRuntimeContext): string {
     const command = this.resolveCommand();
     const executable = command?.executable ?? this.env.CODEX_COMMAND ?? "codex";
     const codexHome = resolve(this.env.CODEX_HOME ?? join(homedir(), ".codex"));
-    return `codex:${executable}:${codexHome}`;
+    return `codex:${executable}:${codexHome}${context.workflowRunId ? `:workflow:${context.workflowRunId}` : ""}`;
   }
 
-  async createRuntime(_context: LocalAgentRuntimeContext) {
+  capabilities() {
+    return {
+      cancellation: "turn",
+      structuredOutput: "native",
+      usage: "streaming",
+      correctionAuthority: "read_only",
+      permissionRequests: "preconfigured",
+      progress: "tools_and_text",
+    } as const;
+  }
+
+  async createRuntime(context: LocalAgentRuntimeContext) {
     return captureAgentProviderResult({
       provider: this.provider,
       operation: "create_runtime",
@@ -273,7 +316,10 @@ export class CodexLocalAgentDriver implements LocalAgentDriver {
         }
         const runtime = new CodexAppServerRuntime({
           command: command.executable,
-          env: codexCommandEnvironment(this.env),
+          ...(context.workflowRunId
+            ? { args: ["app-server", "--disable", "multi_agent", "--disable", "multi_agent_v2"] }
+            : {}),
+          env: localAgentWorkflowEnvironment(codexCommandEnvironment(this.env), context),
           version: command.version,
         });
         try {
@@ -320,6 +366,8 @@ interface CodexTurnAccumulator {
   threadId: string;
   turnId?: string;
   items: unknown[];
+  events: Promise<void>;
+  onEvent?: (event: CodexEvent) => void | Promise<void>;
   completed?: CodexEvent;
   resolve: (result: CodexTurnResult) => void;
   reject: (error: Error) => void;
@@ -360,7 +408,12 @@ class CodexAppServerRpc {
     this.write({ method, ...(params === undefined ? {} : { params }) });
   }
 
-  async runTurn(threadId: string, params: unknown): Promise<CodexTurnResult> {
+  async runTurn(
+    threadId: string,
+    params: unknown,
+    signal?: AbortSignal,
+    onEvent?: (event: CodexEvent) => void | Promise<void>,
+  ): Promise<CodexTurnResult> {
     if (this.fatalError) throw this.fatalError;
     if (this.turns.has(threadId)) throw new Error(`Codex thread ${threadId} already has an active turn.`);
     let resolveTurn!: (result: CodexTurnResult) => void;
@@ -372,16 +425,28 @@ class CodexAppServerRpc {
     const turn: CodexTurnAccumulator = {
       threadId,
       items: [],
+      events: Promise.resolve(),
+      onEvent,
       resolve: resolveTurn,
       reject: rejectTurn,
     };
     this.turns.set(threadId, turn);
+    const interrupt = () => {
+      if (!turn.turnId) return;
+      void this.request("turn/interrupt", { threadId, turnId: turn.turnId }).catch(() => undefined);
+    };
+    signal?.addEventListener("abort", interrupt, { once: true });
     try {
       const response = await this.request("turn/start", params);
       turn.turnId = readString(asRecord(response)?.turn, "id");
-      if (turn.completed) return { event: turn.completed, items: turn.items };
+      if (signal?.aborted) interrupt();
+      if (turn.completed) {
+        await turn.events;
+        return { event: turn.completed, items: turn.items };
+      }
       return await completion;
     } finally {
+      signal?.removeEventListener("abort", interrupt);
       if (this.turns.get(threadId) === turn) this.turns.delete(threadId);
     }
   }
@@ -430,6 +495,7 @@ class CodexAppServerRpc {
     const event = { method, params: message.params };
     const turn = this.findTurn(event);
     if (!turn) return;
+    if (turn.onEvent) turn.events = turn.events.then(() => turn.onEvent?.(event));
     const params = asRecord(event.params);
     if (params?.item !== undefined) {
       turn.items.push(params.item);
@@ -437,7 +503,10 @@ class CodexAppServerRpc {
     }
     if (event.method !== "turn/completed" || !turnMatchesEvent(turn, event)) return;
     turn.completed = event;
-    turn.resolve({ event, items: turn.items.slice() });
+    void turn.events.then(
+      () => turn.resolve({ event, items: turn.items.slice() }),
+      (error) => turn.reject(error instanceof Error ? error : new Error(String(error))),
+    );
   }
 
   private findTurn(event: CodexEvent): CodexTurnAccumulator | undefined {
@@ -453,23 +522,30 @@ class CodexAppServerRpc {
 }
 
 function threadParams(input: LocalAgentRunInput): Record<string, unknown> {
+  const writeMode = input.toolPolicy === "read_only" || input.toolPolicy === "none"
+    ? "read_only"
+    : input.writeMode;
   return {
     ...(input.providerSessionId ? { threadId: input.providerSessionId } : {}),
     cwd: input.workspaceRoot,
     approvalPolicy: "never",
-    sandbox: sandboxFor(input.writeMode),
+    sandbox: sandboxFor(writeMode),
     ...(input.model ? { model: input.model } : {}),
   };
 }
 
 function turnParams(input: LocalAgentRunInput, threadId: string): Record<string, unknown> {
+  const writeMode = input.toolPolicy === "read_only" || input.toolPolicy === "none"
+    ? "read_only"
+    : input.writeMode;
   return {
     threadId,
     input: [{ type: "text", text: input.prompt }],
     approvalPolicy: "never",
-    sandboxPolicy: sandboxPolicyFor(input.writeMode),
+    sandboxPolicy: sandboxPolicyFor(writeMode),
     ...(input.model ? { model: input.model } : {}),
     ...(input.effort ? { effort: input.effort } : {}),
+    ...(input.outputSchema ? { outputSchema: input.outputSchema } : {}),
   };
 }
 
@@ -495,6 +571,7 @@ function parseCompletedTurn(params: unknown, items: unknown[]): {
   finalResponse: string;
   items: unknown[];
   failure?: string;
+  cancelled?: boolean;
 } {
   const turn = asRecord(asRecord(params)?.turn);
   const completedItems = (Array.isArray(turn?.items) ? turn.items : items).slice(-MAX_TURN_ITEMS);
@@ -512,7 +589,7 @@ function parseCompletedTurn(params: unknown, items: unknown[]): {
   const failure = status === "failed"
     ? directString(error?.message) ?? "Codex turn failed."
     : undefined;
-  return { finalResponse, items: completedItems, failure };
+  return { finalResponse, items: completedItems, failure, cancelled: status === "interrupted" || status === "cancelled" };
 }
 
 export function codexAppServerError(message: string, version?: string, stderr?: string): Error {
@@ -550,6 +627,75 @@ function turnMatchesEvent(turn: CodexTurnAccumulator, event: CodexEvent): boolea
   return eventThreadId === turn.threadId || Boolean(turn.turnId && eventTurnId === turn.turnId);
 }
 
+function codexUsage(
+  input: LocalAgentRunInput,
+  event: CodexEvent,
+  sequence: number,
+  final: boolean,
+): LocalAgentUsageUpdate | undefined {
+  if (event.method !== "thread/tokenUsage/updated") return undefined;
+  const params = asRecord(event.params);
+  const tokenUsage = asRecord(params?.tokenUsage ?? params?.token_usage);
+  const usage = asRecord(tokenUsage?.last);
+  if (!usage) return undefined;
+  const outputTokens = readCount(usage, "outputTokens", "output_tokens");
+  if (outputTokens === undefined) return undefined;
+  return {
+    attemptId: input.attemptId ?? "untracked",
+    sequence,
+    inputTokens: readCount(usage, "inputTokens", "input_tokens"),
+    outputTokens,
+    cacheReadTokens: readCount(usage, "cachedInputTokens", "cached_input_tokens"),
+    cacheWriteTokens: readCount(usage, "cacheWriteInputTokens", "cache_write_input_tokens"),
+    reasoningTokens: readCount(usage, "reasoningOutputTokens", "reasoning_output_tokens"),
+    final,
+  };
+}
+
+function codexProgress(event: CodexEvent): LocalAgentProgressUpdate | undefined {
+  const params = asRecord(event.params);
+  const item = asRecord(params?.item);
+  if (event.method === "item/started" || event.method === "item/updated" || event.method === "item/completed") {
+    const type = directString(item?.type);
+    if (type === "agentMessage" || type === "agent_message") {
+      const text = directString(item?.text);
+      return text ? { type: "text", text: text.slice(0, 8 * 1024), final: event.method === "item/completed" } : undefined;
+    }
+    return {
+      type: "tool",
+      toolName: type ?? "tool",
+      status: event.method === "item/started" ? "started" : event.method === "item/completed" ? "completed" : "updated",
+    };
+  }
+  if (event.method === "item/agentMessage/delta") {
+    const delta = directString(params?.delta);
+    return delta ? { type: "text", text: delta.slice(0, 8 * 1024) } : undefined;
+  }
+  return undefined;
+}
+
+function parseJsonValue(text: string): LocalAgentRunResult["structuredOutput"] | undefined {
+  try {
+    const value: unknown = JSON.parse(text);
+    return isJsonValue(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isJsonValue(value: unknown): value is Exclude<LocalAgentRunResult["structuredOutput"], undefined> {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isJsonValue);
+  const record = asRecord(value);
+  return Boolean(record && Object.getPrototypeOf(value) === Object.prototype && Object.values(record).every(isJsonValue));
+}
+
+function readCount(record: Record<string, unknown>, camel: string, snake: string): number | undefined {
+  const value = record[camel] ?? record[snake];
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
 function asRecord(value: unknown): Record<string, unknown> | undefined {
   return value !== null && typeof value === "object" && !Array.isArray(value)
     ? value as Record<string, unknown>
diff --git a/src/local-agent-daemon-lifecycle.ts b/src/local-agent-daemon-lifecycle.ts
index 5ac32b93b..82573c779 100644
--- a/src/local-agent-daemon-lifecycle.ts
+++ b/src/local-agent-daemon-lifecycle.ts
@@ -12,7 +12,7 @@ import {
 } from "node:fs";
 import { join, resolve } from "node:path";
 
-export const LOCAL_AGENT_DAEMON_PROTOCOL_VERSION = 5;
+export const LOCAL_AGENT_DAEMON_PROTOCOL_VERSION = 6;
 export const LOCAL_AGENT_DAEMON_SOCKET_NAME = "agentd.sock";
 export const LOCAL_AGENT_DAEMON_PID_NAME = "agentd.pid";
 export const LOCAL_AGENT_DAEMON_LOCK_NAME = "agentd.lock";
diff --git a/src/local-agent-daemon-main.ts b/src/local-agent-daemon-main.ts
index 51a9fc477..5199a3df0 100644
--- a/src/local-agent-daemon-main.ts
+++ b/src/local-agent-daemon-main.ts
@@ -10,7 +10,18 @@ import {
 import { LocalAgentManager } from "./local-agent-manager.js";
 import { LocalAgentRuntimePool } from "./local-agent-runtime-pool.js";
 import { LocalAgentStore } from "./local-agent-store.js";
-import { localAgentProviderConfigRevision } from "./local-agent-config.js";
+import { executionConfigRevision } from "./workflow-config.js";
+import { createWorkflowManager } from "./workflow-manager.js";
+import { openDatabase } from "./db/client.js";
+import { WorkflowStore } from "./workflow-store.js";
+import { WorkflowRegistry } from "./workflow-registry.js";
+import { SqliteWorkspaceStore } from "./workspace-store.js";
+import { WorkspaceRegistry } from "./workspaces.js";
+import { join, resolve } from "node:path";
+import { realpathSync } from "node:fs";
+import { assertAllowedPath, expandHomePath } from "./roots.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 
 const config = loadConfig();
 const DEFAULT_DAEMON_SHUTDOWN_TIMEOUT_MS = 10_000;
@@ -20,26 +31,91 @@ const log = (
   event: string,
   fields: Record<string, unknown>,
 ) => writeLocalAgentDaemonLog(paths, level, event, fields);
-const store = new LocalAgentStore(paths.stateDir);
+const database = openDatabase(paths.stateDir);
+const store = new LocalAgentStore(database);
+const workspaceStore = new SqliteWorkspaceStore(config.stateDir);
+const workspaces = new WorkspaceRegistry(config, workspaceStore);
 const manager = new LocalAgentManager({
   store,
   drivers: createLocalAgentDrivers({ subagents: config.subagents }),
   pool: new LocalAgentRuntimePool({ logger: log }),
-  loadProfiles: (workspaceRoot) => loadLocalAgentProfiles(config, workspaceRoot, { includeDisabled: true }),
+  loadProfiles: (workspaceRoot, workspaceId) => {
+    const session = workspaceId ? workspaceStore.getSession(workspaceId) : undefined;
+    const profileRoot = session?.mode === "worktree" && session.managed && session.sourceRoot
+      ? session.sourceRoot : workspaceRoot;
+    return loadLocalAgentProfiles(config, profileRoot, { includeDisabled: true });
+  },
   agentDir: config.agentDir,
   allowedRoots: config.allowedRoots,
+  validateWorkspaceScope: (scope) => {
+    if (!scope.workspaceId) return scope.workspaceRoot;
+    const session = workspaceStore.getSession(scope.workspaceId);
+    if (!session || session.status !== "active" || resolve(session.root) !== resolve(scope.workspaceRoot)) {
+      throw new Error("Workspace identity is unavailable or does not match its root.");
+    }
+    const canonicalAllowed = (path: string, roots: string[]) => {
+      assertAllowedPath(path, roots);
+      const canonicalRoots = roots.flatMap((root) => {
+        try { return [realpathSync(root)]; }
+        catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+          throw error;
+        }
+      });
+      return assertAllowedPath(realpathSync(path), canonicalRoots);
+    };
+    if (session.mode === "worktree") {
+      if (!session.managed || !session.sourceRoot) throw new Error("Managed workspace source is unavailable.");
+      canonicalAllowed(session.sourceRoot, config.allowedRoots);
+      canonicalAllowed(session.root, [config.worktreeRoot]);
+    } else canonicalAllowed(session.root, config.allowedRoots);
+    return session.root;
+  },
   logger: log,
   subagents: config.subagents,
 });
+const workflows = config.workflows?.enabled ? createWorkflowManager({
+  stateDir: config.stateDir, agents: manager, agentStore: store, config: config.workflows,
+  store: new WorkflowStore(database),
+  registry: new WorkflowRegistry({
+    userRoot: join(config.configDir, "workflows"), allowedRoots: config.allowedRoots,
+    packageRoots: config.workflows.packageRoots.map((path) => resolve(config.configDir, expandHomePath(path))),
+    scriptBytes: config.workflows.limits.scriptBytes,
+  }),
+  validateScope: async (scope) => {
+    const workspace = await workspaces.getWorkspace(scope.workspaceId);
+    if (workspace.root !== scope.workspaceRoot) throw new Error("WORKSPACE_NOT_ALLOWED: Workspace root does not match its stored identity.");
+    return { workspaceId: workspace.id, workspaceRoot: workspace.root };
+  },
+  inspectWorktree: async ({ scope, worktree }) => {
+    const workspace = await workspaces.getWorkspace(scope.workspaceId);
+    if (workspace.root !== scope.workspaceRoot) throw new Error("Managed workspace identity changed.");
+    const [status, head] = await Promise.all([
+      promisify(execFile)("git", ["status", "--porcelain=v1", "--untracked-files=normal"], { cwd: workspace.root }),
+      promisify(execFile)("git", ["rev-parse", "HEAD"], { cwd: workspace.root }),
+    ]);
+    return { changed: Boolean(status.stdout.trim()) || head.stdout.trim() !== worktree.baseSha };
+  },
+  createWorktree: async ({ scope }) => {
+    const source = await workspaces.getWorkspace(scope.workspaceId);
+    const baseRef = source.mode === "worktree"
+      ? (await promisify(execFile)("git", ["rev-parse", "HEAD"], { cwd: source.root })).stdout.trim()
+      : undefined;
+    const { workspace } = await workspaces.openWorkspace({ path: source.sourceRoot ?? source.root, mode: "worktree", baseRef });
+    return { workspaceId: workspace.id, workspaceRoot: workspace.root, baseSha: workspace.worktree!.baseSha };
+  },
+}) : undefined;
 const daemon = new LocalAgentDaemon({
   stateDir: paths.stateDir,
   manager,
-  configRevision: localAgentProviderConfigRevision(config.subagents),
+  workflows,
+  configRevision: executionConfigRevision(config),
   onLockAcquired: () => {
     const reconciled = manager.reconcileActiveRuns();
     if (reconciled.isErr()) throw reconciled.error;
+    workflows?.reconcileActiveRuns();
   },
-  onClosed: () => { if (!shuttingDown) process.exit(0); },
+  onClosed: () => { workspaceStore.close(); database.close(); if (!shuttingDown) process.exit(0); },
   idleShutdownMs: parseIdleShutdownMs(process.env.DEVSPACE_AGENTD_IDLE_TIMEOUT_MS),
 });
 
diff --git a/src/local-agent-daemon-protocol.ts b/src/local-agent-daemon-protocol.ts
index 21aeb6806..f229ddcdf 100644
--- a/src/local-agent-daemon-protocol.ts
+++ b/src/local-agent-daemon-protocol.ts
@@ -9,6 +9,7 @@ import type {
   StartLocalAgentInput,
 } from "./local-agent-manager.js";
 import type { LocalAgentWriteMode } from "./local-agent-runtime.js";
+import { decodeWorkflowRequest, type WorkflowRequest } from "./workflow-protocol.js";
 import { LOCAL_AGENT_DAEMON_PROTOCOL_VERSION } from "./local-agent-daemon-lifecycle.js";
 
 export type LocalAgentDaemonMethod =
@@ -18,11 +19,13 @@ export type LocalAgentDaemonMethod =
   | "agent.get"
   | "agent.list"
   | "agent.wait"
+  | "workflow.request"
   | "daemon.status"
   | "daemon.stop"
   | "daemon.logs";
 
 export type LocalAgentDaemonRequest =
+  | AgentDaemonRequestBase<"workflow.request", WorkflowRequest>
   | (AgentDaemonRequestBase<"hello", Record<string, never>> & { configRevision?: string })
   | AgentDaemonRequestBase<"agent.start", StartLocalAgentInput>
   | AgentDaemonRequestBase<"agent.continue", { id: string; prompt: string; scope: LocalAgentWorkspaceScope; overrides?: RunOverrides }>
@@ -55,6 +58,7 @@ export interface LocalAgentDaemonStatus {
   endpoint: string;
   startedAt: string;
   activeTurns: number;
+  activeWorkflows?: number;
   runtimeCount: number;
   clientConnections: number;
 }
@@ -106,6 +110,8 @@ export function decodeLocalAgentDaemonRequest(value: unknown): LocalAgentDaemonR
   const params = record?.params;
 
   switch (method) {
+    case "workflow.request":
+      return { requestId, protocolVersion, authToken, method, params: decodeWorkflowRequest(params) };
     case "hello":
       return {
         requestId,
@@ -221,6 +227,7 @@ export function decodeAgentRecord(value: unknown): LocalAgentRecord {
     provider: requiredString(record?.provider, "provider"),
     model: optionalString(record?.model),
     effort: optionalString(record?.effort),
+    writeMode: decodeWriteMode(record?.writeMode),
     providerSessionId: optionalString(record?.providerSessionId),
     status,
     latestResponse: typeof record?.latestResponse === "string" ? record.latestResponse : undefined,
@@ -284,6 +291,7 @@ export function decodeDaemonStatus(value: unknown): LocalAgentDaemonStatus {
     endpoint: requiredString(record?.endpoint, "endpoint"),
     startedAt: requiredString(record?.startedAt, "startedAt"),
     activeTurns: requiredInteger(record?.activeTurns, "activeTurns"),
+    ...(record?.activeWorkflows === undefined ? {} : { activeWorkflows: requiredInteger(record.activeWorkflows, "activeWorkflows") }),
     runtimeCount: requiredInteger(record?.runtimeCount, "runtimeCount"),
     clientConnections: requiredInteger(record?.clientConnections, "clientConnections"),
   };
diff --git a/src/local-agent-daemon.test.ts b/src/local-agent-daemon.test.ts
index 88722dafa..0a4c75734 100644
--- a/src/local-agent-daemon.test.ts
+++ b/src/local-agent-daemon.test.ts
@@ -665,7 +665,7 @@ const socketDaemon = new LocalAgentDaemon({
   stateDir: socketStateDir,
   configRevision: CONFIG_REVISION,
   manager: socketManager,
-  requestReadTimeoutMs: 30,
+  requestReadTimeoutMs: 500,
   shutdownTimeoutMs: 100,
   idleShutdownMs: 60_000,
 });
@@ -716,7 +716,7 @@ try {
   assert.equal(malformed.ok, false);
   if (!malformed.ok) assert.equal(malformed.error.code, "DAEMON_INVALID_REQUEST");
 
-  const oversized = await sendRawRequest(socketDaemon.paths.endpoint, "x".repeat(512 * 1024 + 1));
+  const oversized = await sendRawRequest(socketDaemon.paths.endpoint, "x".repeat(2 * 1024 * 1024 + 1));
   assert.equal(oversized.ok, false);
   if (!oversized.ok) assert.equal(oversized.error.code, "DAEMON_INVALID_REQUEST");
 
@@ -747,6 +747,8 @@ async function sendRawRequest(
 ): Promise<RawDaemonResponse> {
   const socket = createConnection(endpoint);
   socket.setEncoding("utf8");
+  // A rejected oversized write can finish with EPIPE after the response arrives.
+  socket.on("error", () => {});
   const connected = onceSocket(socket, "connect");
   let buffer = "";
   const response = new Promise<RawDaemonResponse>((resolveResponse, rejectResponse) => {
diff --git a/src/local-agent-daemon.ts b/src/local-agent-daemon.ts
index aac96e9d9..feea3a2f9 100644
--- a/src/local-agent-daemon.ts
+++ b/src/local-agent-daemon.ts
@@ -43,8 +43,9 @@ import type {
   StartLocalAgentInput,
 } from "./local-agent-manager.js";
 import type { LocalAgentRecord, LocalAgentWorkspaceScope } from "./local-agent-store.js";
+import type { WorkflowReply, WorkflowRequest } from "./workflow-protocol.js";
 
-const MAX_REQUEST_BYTES = 512 * 1024;
+const MAX_REQUEST_BYTES = 2 * 1024 * 1024;
 const DEFAULT_DAEMON_IDLE_SHUTDOWN_MS = 30_000;
 const DEFAULT_IDLE_CHECK_INTERVAL_MS = 1_000;
 const DEFAULT_REQUEST_READ_TIMEOUT_MS = 5_000;
@@ -70,6 +71,11 @@ export interface LocalAgentDaemonManager {
 export interface LocalAgentDaemonOptions {
   stateDir: string;
   manager: LocalAgentDaemonManager;
+  workflows?: {
+    request(input: WorkflowRequest): Promise<WorkflowReply>;
+    readonly activeRunCount: number;
+    close(): Promise<void>;
+  };
   configRevision: string;
   idleShutdownMs?: number;
   idleCheckIntervalMs?: number;
@@ -84,6 +90,7 @@ export interface LocalAgentDaemonOptions {
 export class LocalAgentDaemon {
   readonly paths: LocalAgentDaemonPaths;
   private readonly manager: LocalAgentDaemonManager;
+  private readonly workflows?: LocalAgentDaemonOptions["workflows"];
   private readonly configRevision: string;
   private readonly lock: LocalAgentDaemonLock;
   private readonly idleShutdownMs: number;
@@ -108,6 +115,7 @@ export class LocalAgentDaemon {
   constructor(options: LocalAgentDaemonOptions) {
     this.paths = options.paths ?? localAgentDaemonPaths(options.stateDir);
     this.manager = options.manager;
+    this.workflows = options.workflows;
     this.configRevision = options.configRevision;
     this.lock = new LocalAgentDaemonLock(this.paths);
     this.idleShutdownMs = options.idleShutdownMs ?? DEFAULT_DAEMON_IDLE_SHUTDOWN_MS;
@@ -178,6 +186,7 @@ export class LocalAgentDaemon {
       endpoint: this.paths.endpoint,
       startedAt: this.startedAt,
       activeTurns: this.manager.activeTurnCount,
+      activeWorkflows: this.workflows?.activeRunCount ?? 0,
       runtimeCount: this.manager.runtimeCount,
       clientConnections: this.sockets.size,
     };
@@ -192,13 +201,17 @@ export class LocalAgentDaemon {
     this.closePromise = (async () => {
       writeLocalAgentDaemonLog(this.paths, "info", "daemon_stopping", {
         activeTurns: this.manager.activeTurnCount,
+        activeWorkflows: this.workflows?.activeRunCount ?? 0,
         runtimeCount: this.manager.runtimeCount,
       });
       for (const socket of this.sockets) socket.destroy();
       this.sockets.clear();
       const [serverResult, managerResult] = await Promise.allSettled([
         withTimeout(closeServer(this.server), this.shutdownTimeoutMs, "daemon socket shutdown"),
-        withTimeout(this.manager.close(), this.shutdownTimeoutMs, "daemon manager shutdown"),
+        withTimeout((async () => {
+          await this.workflows?.close();
+          await this.manager.close();
+        })(), this.shutdownTimeoutMs, "daemon manager shutdown"),
       ]);
       if (serverResult.status === "rejected") {
         writeLocalAgentDaemonLog(this.paths, "warn", "daemon_socket_close_failed", {
@@ -314,6 +327,13 @@ export class LocalAgentDaemon {
     }
 
     switch (request.method) {
+      case "workflow.request":
+        if (!this.workflows) return { ok: false, error: {
+          code: "WORKFLOW_DISABLED", message: "Dynamic workflows are disabled.", retryable: false,
+        } } satisfies WorkflowReply;
+        this.activeTurnRequests += 1;
+        try { return await this.workflows.request(request.params); }
+        finally { this.activeTurnRequests -= 1; }
       case "hello":
         return {
           status: this.status(),
@@ -344,7 +364,7 @@ export class LocalAgentDaemon {
       case "daemon.stop":
         if (request.params.ifIdle) {
           this.accepting = false;
-          if (this.activeTurnRequests > 0 || this.manager.activeTurnCount > 0) {
+          if (this.activeTurnRequests > 0 || this.manager.activeTurnCount > 0 || (this.workflows?.activeRunCount ?? 0) > 0) {
             this.accepting = true;
             throw new AgentDaemonUnavailableError({
               code: "DAEMON_UNAVAILABLE",
@@ -391,7 +411,7 @@ export class LocalAgentDaemon {
 
   private async maintainIdle(): Promise<void> {
     await this.manager.evictIdle(this.now());
-    if (this.stopping || this.manager.activeTurnCount > 0 || this.manager.runtimeCount > 0 || this.sockets.size > 0) {
+    if (this.stopping || this.manager.activeTurnCount > 0 || this.manager.runtimeCount > 0 || this.sockets.size > 0 || (this.workflows?.activeRunCount ?? 0) > 0) {
       this.idleSince = undefined;
       return;
     }
diff --git a/src/local-agent-manager.ts b/src/local-agent-manager.ts
index 30fe1e1f4..1eade1253 100644
--- a/src/local-agent-manager.ts
+++ b/src/local-agent-manager.ts
@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { createHash } from "node:crypto";
 import { Result, type Result as BetterResult } from "better-result";
 import {
   AgentConflictError,
@@ -18,16 +19,21 @@ import {
   resolveLocalAgentTarget,
 } from "./local-agent-targets.js";
 import {
+  type BegunLocalAgentTurn,
   type LocalAgentRecord,
   type LocalAgentStore,
   type LocalAgentTurnRecord,
   type LocalAgentWorkspaceScope,
 } from "./local-agent-store.js";
 import {
+  localAgentCapabilities,
+  type LocalAgentCapabilities,
   type LocalAgentDriver,
+  type LocalAgentJsonSchema,
   type LocalAgentRunCallbacks,
   type LocalAgentRunInput,
   type LocalAgentRuntimeContext,
+  type LocalAgentToolPolicy,
   type LocalAgentWriteMode,
 } from "./local-agent-runtime.js";
 import { LocalAgentRuntimePool } from "./local-agent-runtime-pool.js";
@@ -45,12 +51,26 @@ export interface StartLocalAgentInput {
   model?: string;
   effort?: string;
   writeMode?: LocalAgentWriteMode;
+  attemptId?: string;
+  outputSchema?: LocalAgentJsonSchema;
+  toolPolicy?: LocalAgentToolPolicy;
+  workflowRunId?: string;
+  workflowStepId?: string;
+  workflowAttemptId?: string;
+  expectedProfileHash?: string;
 }
 
 export interface RunOverrides {
   model?: string;
   effort?: string;
   writeMode?: LocalAgentWriteMode;
+  attemptId?: string;
+  outputSchema?: LocalAgentJsonSchema;
+  toolPolicy?: LocalAgentToolPolicy;
+  workflowRunId?: string;
+  workflowStepId?: string;
+  workflowAttemptId?: string;
+  expectedProfileHash?: string;
 }
 
 export interface LocalAgentManagerLogger {
@@ -61,9 +81,10 @@ export interface LocalAgentManagerOptions {
   store: LocalAgentStore;
   drivers: readonly LocalAgentDriver[];
   pool: LocalAgentRuntimePool;
-  loadProfiles: (workspaceRoot: string) => Promise<LocalAgentProfile[]>;
+  loadProfiles: (workspaceRoot: string, workspaceId?: string) => Promise<LocalAgentProfile[]>;
   agentDir?: string;
   allowedRoots?: readonly string[];
+  validateWorkspaceScope?: (scope: LocalAgentWorkspaceScope, operation: string) => string;
   logger?: LocalAgentManagerLogger;
   subagents: SubagentsConfig;
 }
@@ -83,6 +104,25 @@ export type LocalAgentWaitResult =
 interface ActiveLocalAgentTurn {
   turnId: number;
   completion: Promise<void>;
+  abort: AbortController;
+}
+
+export interface StartedLocalAgentTurn extends BegunLocalAgentTurn {
+  capabilities: LocalAgentCapabilities;
+}
+
+export interface LocalAgentTurnCallbacks extends LocalAgentRunCallbacks {
+  onPrepared?: (turn: BegunLocalAgentTurn) => void;
+}
+
+export interface LocalAgentInvocationResolution {
+  target: string;
+  provider: LocalAgentProvider;
+  model?: string;
+  effort?: string;
+  writeMode: LocalAgentWriteMode;
+  profileHash: string;
+  capabilities: LocalAgentCapabilities;
 }
 
 /**
@@ -94,9 +134,10 @@ export class LocalAgentManager {
   private readonly store: LocalAgentStore;
   private readonly drivers = new Map<LocalAgentProvider, LocalAgentDriver>();
   private readonly pool: LocalAgentRuntimePool;
-  private readonly loadProfiles: (workspaceRoot: string) => Promise<LocalAgentProfile[]>;
+  private readonly loadProfiles: LocalAgentManagerOptions["loadProfiles"];
   private readonly agentDir?: string;
   private readonly allowedRoots?: readonly string[];
+  private readonly validateWorkspaceScope?: LocalAgentManagerOptions["validateWorkspaceScope"];
   private readonly logger?: LocalAgentManagerLogger;
   private readonly subagents: SubagentsConfig;
   private readonly activeTurns = new Map<string, ActiveLocalAgentTurn>();
@@ -110,6 +151,7 @@ export class LocalAgentManager {
     this.loadProfiles = options.loadProfiles;
     this.agentDir = options.agentDir;
     this.allowedRoots = options.allowedRoots;
+    this.validateWorkspaceScope = options.validateWorkspaceScope;
     this.logger = options.logger;
     this.subagents = options.subagents;
   }
@@ -118,7 +160,74 @@ export class LocalAgentManager {
     return this.store.reconcileActiveRunsResult(message);
   }
 
+  async capabilities(
+    input: Pick<StartLocalAgentInput, "target" | "workspaceRoot" | "workspaceId" | "model" | "effort" | "writeMode" | "outputSchema" | "toolPolicy">,
+  ): Promise<BetterResult<LocalAgentCapabilities, AgentStartError>> {
+    const authorized = this.authorizeWorkspace(input.workspaceRoot, input.workspaceId, "capabilities");
+    if (authorized.isErr()) return authorized;
+    const profiles = await this.loadProfilesResult(authorized.value, input.target, input.workspaceId);
+    if (profiles.isErr()) return profiles;
+    const target = resolveLocalAgentTarget(input.target, profiles.value, input.model, input.effort, this.subagents.providers);
+    if (!target) return Result.err(new AgentTargetError({
+      code: "UNKNOWN_TARGET", target: input.target, retryable: false,
+      message: `Unknown subagent profile or provider: ${input.target}.`,
+    }));
+    const enabled = this.providerEnabledResult(target.provider, target.name, "capabilities");
+    if (enabled.isErr()) return enabled;
+    const driver = this.driverResult(target.provider, "capabilities");
+    if (driver.isErr()) return driver;
+    const context: LocalAgentRuntimeContext = {
+      agentId: "capability_probe", provider: driver.value.provider, workspaceRoot: authorized.value,
+      writeMode: input.writeMode, model: target.model, effort: target.effort,
+      outputSchema: input.outputSchema, toolPolicy: input.toolPolicy, agentDir: this.agentDir,
+    };
+    return Result.ok(localAgentCapabilities(driver.value, context, {
+      prompt: "capability probe", workspaceRoot: authorized.value, model: target.model,
+      effort: target.effort, outputSchema: input.outputSchema, toolPolicy: input.toolPolicy,
+    }));
+  }
+
+  async resolveInvocation(
+    input: Pick<StartLocalAgentInput, "target" | "workspaceRoot" | "workspaceId" | "model" | "effort" | "writeMode" | "outputSchema" | "toolPolicy">,
+  ): Promise<BetterResult<LocalAgentInvocationResolution, AgentStartError>> {
+    const authorized = this.authorizeWorkspace(input.workspaceRoot, input.workspaceId, "resolve");
+    if (authorized.isErr()) return authorized;
+    const profiles = await this.loadProfilesResult(authorized.value, input.target, input.workspaceId);
+    if (profiles.isErr()) return profiles;
+    const target = resolveLocalAgentTarget(input.target, profiles.value, input.model, input.effort, this.subagents.providers);
+    if (!target) return Result.err(new AgentTargetError({ code: "UNKNOWN_TARGET", target: input.target,
+      retryable: false, message: `Unknown subagent profile or provider: ${input.target}.` }));
+    const enabled = this.providerEnabledResult(target.provider, target.name, "resolve");
+    if (enabled.isErr()) return enabled;
+    const driver = this.driverResult(target.provider, "resolve");
+    if (driver.isErr()) return driver;
+    const writeMode = narrowerWriteMode(input.writeMode ?? "allowed",
+      target.kind === "profile" ? target.profile.writeMode ?? "allowed" : "allowed");
+    const context: LocalAgentRuntimeContext = { agentId: "capability_probe", provider: target.provider,
+      workspaceRoot: authorized.value, writeMode, model: target.model, effort: target.effort,
+      outputSchema: input.outputSchema, toolPolicy: input.toolPolicy, agentDir: this.agentDir };
+    return Result.ok({
+      target: target.name,
+      provider: target.provider,
+      model: target.model,
+      effort: target.effort,
+      writeMode,
+      profileHash: profileHash(target),
+      capabilities: localAgentCapabilities(driver.value, context, { prompt: "capability probe",
+        workspaceRoot: authorized.value, model: target.model, effort: target.effort,
+        outputSchema: input.outputSchema, toolPolicy: input.toolPolicy }),
+    });
+  }
+
   async start(input: StartLocalAgentInput): Promise<BetterResult<LocalAgentRecord, AgentStartError>> {
+    const started = await this.startTurn(input);
+    return started.isErr() ? started : Result.ok(started.value.agent);
+  }
+
+  async startTurn(
+    input: StartLocalAgentInput,
+    callbacks: LocalAgentTurnCallbacks = {},
+  ): Promise<BetterResult<StartedLocalAgentTurn, AgentStartError>> {
     const manager = this;
     return Result.gen(async function* () {
       yield* manager.acceptingResult("start");
@@ -127,7 +236,7 @@ export class LocalAgentManager {
         input.workspaceId,
         "start",
       );
-      const profiles = yield* Result.await(manager.loadProfilesResult(workspaceRoot, input.target));
+      const profiles = yield* Result.await(manager.loadProfilesResult(workspaceRoot, input.target, input.workspaceId));
       const target = resolveLocalAgentTarget(
         input.target,
         profiles,
@@ -143,6 +252,11 @@ export class LocalAgentManager {
           message: `Unknown subagent profile or provider: ${input.target}.`,
         }));
       }
+      if (input.expectedProfileHash && input.expectedProfileHash !== profileHash(target)) {
+        return Result.err(new AgentTargetError({ code: "TARGET_RESOLUTION_FAILED", target: target.name,
+          provider: target.provider, operation: "start", retryable: true,
+          message: `Subagent profile changed after workflow admission: ${target.name}.` }));
+      }
       if (target.kind === "profile" && target.profile.disabled) {
         return Result.err(new AgentTargetError({
           code: "PROVIDER_DISABLED",
@@ -153,7 +267,10 @@ export class LocalAgentManager {
         }));
       }
       yield* manager.providerEnabledResult(target.provider, target.name, "start");
-      yield* manager.driverResult(target.provider, "start");
+      const driver = yield* manager.driverResult(target.provider, "start");
+      const writeMode = narrowerWriteMode(input.writeMode ?? "allowed", target.kind === "profile"
+        ? target.profile.writeMode ?? "allowed"
+        : "allowed");
       const record = yield* manager.store.createResult({
         workspaceId: input.workspaceId,
         workspaceRoot,
@@ -161,12 +278,19 @@ export class LocalAgentManager {
         provider: target.provider,
         model: target.model,
         effort: target.effort,
+        writeMode,
       });
-      return manager.begin(record, input.prompt, {
+      return manager.beginTurn(record, input.prompt, {
         model: target.model,
         effort: target.effort,
-        writeMode: input.writeMode,
-      }, input.workspaceId);
+        writeMode,
+        attemptId: input.attemptId,
+        outputSchema: input.outputSchema,
+        toolPolicy: input.toolPolicy,
+        workflowRunId: input.workflowRunId,
+        workflowStepId: input.workflowStepId,
+        workflowAttemptId: input.workflowAttemptId,
+      }, input.workspaceId, callbacks, driver);
     });
   }
 
@@ -176,17 +300,37 @@ export class LocalAgentManager {
     overrides: RunOverrides = {},
     scope: LocalAgentWorkspaceScope,
   ): Promise<BetterResult<LocalAgentRecord, AgentContinueError>> {
+    const continued = await this.continueTurn(agentId, prompt, overrides, scope);
+    return continued.isErr() ? continued : Result.ok(continued.value.agent);
+  }
+
+  async continueTurn(
+    agentId: string,
+    prompt: string,
+    overrides: RunOverrides = {},
+    scope: LocalAgentWorkspaceScope,
+    callbacks: LocalAgentTurnCallbacks = {},
+  ): Promise<BetterResult<StartedLocalAgentTurn, AgentContinueError>> {
     const manager = this;
     return Result.gen(async function* () {
       yield* manager.acceptingResult("continue", agentId);
       const record = yield* manager.store.getByIdResult(agentId);
       if (!record) return Result.err(agentNotFound(agentId));
       yield* manager.agentWorkspaceResult(record, scope, "continue");
-      const profiles = yield* Result.await(manager.loadProfilesResult(record.workspaceRoot, record.profileName));
-      yield* manager.profileForRecordResult(record, profiles);
+      const profiles = yield* Result.await(manager.loadProfilesResult(record.workspaceRoot, record.profileName, record.workspaceId));
+      const profile = yield* manager.profileForRecordResult(record, profiles);
+      if (overrides.expectedProfileHash && overrides.expectedProfileHash !== recordProfileHash(record, profile)) {
+        return Result.err(new AgentTargetError({ code: "TARGET_RESOLUTION_FAILED", target: record.profileName,
+          provider: isLocalAgentProvider(record.provider) ? record.provider : undefined,
+          operation: "continue", retryable: true,
+          message: `Subagent profile changed after workflow admission: ${record.profileName}.` }));
+      }
       yield* manager.providerEnabledResult(record.provider, record.profileName, "continue");
-      yield* manager.driverResult(record.provider, "continue", agentId);
-      return manager.begin(record, prompt, overrides, scope.workspaceId);
+      const driver = yield* manager.driverResult(record.provider, "continue", agentId);
+      return manager.beginTurn(record, prompt, {
+        ...overrides,
+        writeMode: narrowerWriteMode(record.writeMode ?? "allowed", overrides.writeMode ?? record.writeMode ?? "allowed"),
+      }, scope.workspaceId, callbacks, driver);
     });
   }
 
@@ -259,6 +403,33 @@ export class LocalAgentManager {
     return Result.ok(results);
   }
 
+  async stop(
+    agentId: string,
+    turnId: number,
+    scope: LocalAgentWorkspaceScope,
+  ): Promise<BetterResult<LocalAgentTurnRecord, AgentWaitError>> {
+    const agent = this.get(agentId, scope);
+    if (agent.isErr()) return agent;
+    const stored = this.store.getTurnByIdResult(turnId);
+    if (stored.isErr()) return stored;
+    if (!stored.value || stored.value.agentId !== agentId) return Result.err(agentNotFound(agentId));
+    if (stored.value.status !== "running") return Result.ok(stored.value);
+    const active = this.activeTurns.get(agentId);
+    if (!active || active.turnId !== turnId) {
+      return Result.err(new AgentStoreError(
+        "stop",
+        new Error(`Turn ${turnId} is not active.`),
+        `Running turn state is unavailable for subagent ${agentId}.`,
+      ));
+    }
+    active.abort.abort(new Error("Agent turn stopped."));
+    await active.completion.catch(() => undefined);
+    const finished = this.store.getTurnByIdResult(turnId);
+    if (finished.isErr()) return finished;
+    if (!finished.value) return Result.err(agentNotFound(agentId));
+    return Result.ok(finished.value);
+  }
+
   async close(): Promise<void> {
     if (this.closePromise) return this.closePromise;
     this.accepting = false;
@@ -290,12 +461,14 @@ export class LocalAgentManager {
     await this.pool.evictIdle(now);
   }
 
-  private begin(
+  private beginTurn(
     record: LocalAgentRecord,
     prompt: string,
     overrides: RunOverrides,
     workspaceId?: string,
-  ): BetterResult<LocalAgentRecord, AgentConflictError | AgentStoreError> {
+    callbacks: LocalAgentTurnCallbacks = {},
+    driver?: LocalAgentDriver,
+  ): BetterResult<StartedLocalAgentTurn, AgentConflictError | AgentStoreError> {
     if (this.activeTurns.has(record.id)) {
       return Result.err(new AgentConflictError({
         code: "AGENT_CONFLICT",
@@ -310,16 +483,49 @@ export class LocalAgentManager {
       prompt,
       model: overrides.model ?? record.model,
       effort: overrides.effort ?? record.effort,
-    });
+      writeMode: overrides.writeMode ?? record.writeMode ?? "allowed",
+      attemptId: overrides.attemptId,
+      workflowRunId: overrides.workflowRunId,
+      workflowStepId: overrides.workflowStepId,
+      workflowAttemptId: overrides.workflowAttemptId,
+    }, callbacks.onPrepared);
     if (begun.isErr()) return begun;
+    const abort = new AbortController();
     // Defer invocation until after the tracking entry is visible. This keeps
     // cleanup correct even if runTurn later gains a synchronous completion path.
-    const turn = Promise.resolve().then(() => (
-      this.runTurn(begun.value.agent, begun.value.turn.id, prompt, overrides, workspaceId)
-    ));
-    this.activeTurns.set(record.id, { turnId: begun.value.turn.id, completion: turn });
+    const turn = new Promise<void>((resolveTurn, rejectTurn) => {
+      setImmediate(() => {
+        void this.runTurn(
+          begun.value.agent, begun.value.turn.id, prompt, overrides, workspaceId,
+          { ...callbacks, onPrepared: undefined } as LocalAgentRunCallbacks, abort.signal,
+        ).then(resolveTurn, rejectTurn);
+      });
+    });
+    this.activeTurns.set(record.id, { turnId: begun.value.turn.id, completion: turn, abort });
     void turn.catch(() => undefined);
-    return Result.ok(begun.value.agent);
+    const resolvedDriver = driver ?? this.drivers.get(record.provider as LocalAgentProvider);
+    const capabilities = resolvedDriver ? localAgentCapabilities(resolvedDriver, {
+      agentId: record.id,
+      provider: resolvedDriver.provider,
+      workspaceRoot: record.workspaceRoot,
+      providerSessionId: record.providerSessionId,
+      writeMode: overrides.writeMode,
+      model: overrides.model ?? record.model,
+      effort: overrides.effort ?? record.effort,
+      outputSchema: overrides.outputSchema,
+      toolPolicy: overrides.toolPolicy,
+      workflowRunId: overrides.workflowRunId,
+      workflowStepId: overrides.workflowStepId,
+      workflowAttemptId: overrides.workflowAttemptId,
+      agentDir: this.agentDir,
+    }, {
+      prompt,
+      workspaceRoot: record.workspaceRoot,
+      attemptId: overrides.attemptId,
+      outputSchema: overrides.outputSchema,
+      toolPolicy: overrides.toolPolicy,
+    }) : unavailableCapabilities();
+    return Result.ok({ ...begun.value, capabilities });
   }
 
   private async runTurn(
@@ -328,6 +534,8 @@ export class LocalAgentManager {
     prompt: string,
     overrides: RunOverrides,
     workspaceId?: string,
+    inputCallbacks: LocalAgentRunCallbacks = {},
+    signal?: AbortSignal,
   ): Promise<void> {
     const startedAt = Date.now();
     this.log("info", "agent_run_started", {
@@ -345,7 +553,7 @@ export class LocalAgentManager {
       const authorizedRecord = workspaceRoot === record.workspaceRoot
         ? record
         : { ...record, workspaceRoot };
-      const profiles = await this.loadProfilesResult(workspaceRoot, record.profileName);
+      const profiles = await this.loadProfilesResult(workspaceRoot, record.profileName, workspaceId);
       if (profiles.isErr()) {
         this.persistRunError(record, turnId, profiles.error, startedAt);
         return;
@@ -373,19 +581,36 @@ export class LocalAgentManager {
         writeMode: input.value.writeMode,
         model: input.value.model,
         effort: input.value.effort,
+        outputSchema: input.value.outputSchema,
+        toolPolicy: input.value.toolPolicy,
+        workflowRunId: input.value.workflowRunId,
+        workflowStepId: input.value.workflowStepId,
+        workflowAttemptId: input.value.workflowAttemptId,
         agentDir: this.agentDir,
       };
       const callbacks: LocalAgentRunCallbacks = {
-        onSessionId: (providerSessionId) => {
+        ...inputCallbacks,
+        onSessionId: async (providerSessionId) => {
           const current = this.store.getByIdResult(record.id);
           if (current.isErr()) throw current.error;
-          if (!current.value || current.value.providerSessionId === providerSessionId) return;
-          const updated = this.store.updateResult(record.id, { providerSessionId });
-          if (updated.isErr()) throw updated.error;
+          if (current.value && current.value.providerSessionId !== providerSessionId) {
+            const updated = this.store.updateResult(record.id, { providerSessionId });
+            if (updated.isErr()) throw updated.error;
+          }
+          await inputCallbacks.onSessionId?.(providerSessionId);
         },
       };
-      const result = await this.pool.run(driver.value, context, input.value, callbacks);
+      const result = await this.pool.run(driver.value, context, input.value, callbacks, signal ? { signal } : undefined);
       if (result.isErr()) {
+        if (signal?.aborted && result.error.code === "PROVIDER_CANCELLED") {
+          this.store.finishTurnResult(record.id, turnId, {
+            status: "stopped",
+            error: "Agent turn stopped.",
+            errorCode: "AGENT_STOPPED",
+            errorRetryable: false,
+          });
+          return;
+        }
         this.persistRunError(record, turnId, result.error, startedAt);
         return;
       }
@@ -396,7 +621,9 @@ export class LocalAgentManager {
       const updated = this.store.finishTurnResult(record.id, turnId, {
         providerSessionId: runResult.providerSessionId ?? current.value.providerSessionId,
         status: "completed",
-        response: runResult.finalResponse,
+        response: runResult.structuredOutput === undefined
+          ? runResult.finalResponse
+          : JSON.stringify(runResult.structuredOutput),
       });
       if (updated.isErr()) throw updated.error;
       this.log("info", "agent_run_completed", {
@@ -442,6 +669,9 @@ export class LocalAgentManager {
       error: error.message,
       errorCode: error.code,
       errorRetryable: error.retryable,
+      retryAfterMs: numericField(error, "retryAfterMs"),
+      resetAt: stringField(error, "resetAt"),
+      executionUncertain: booleanField(error, "executionUncertain"),
     });
     this.log("error", "agent_run_failed", {
       provider: record.provider,
@@ -477,11 +707,20 @@ export class LocalAgentManager {
       prompt: fullPrompt,
       workspaceRoot: record.workspaceRoot,
       providerSessionId: record.providerSessionId,
-      writeMode: overrides.writeMode ?? "allowed",
+      writeMode: narrowerWriteMode(
+        record.writeMode ?? "allowed",
+        narrowerWriteMode(profile?.writeMode ?? "allowed", overrides.writeMode ?? record.writeMode ?? "allowed"),
+      ),
       model: record.model ?? profile?.model,
       effort: record.effort ?? profile?.effort,
       modelOverrideRequested: overrides.model !== undefined,
       effortOverrideRequested: overrides.effort !== undefined,
+      attemptId: overrides.attemptId,
+      outputSchema: overrides.outputSchema,
+      toolPolicy: overrides.toolPolicy,
+      workflowRunId: overrides.workflowRunId,
+      workflowStepId: overrides.workflowStepId,
+      workflowAttemptId: overrides.workflowAttemptId,
     });
   }
 
@@ -577,6 +816,16 @@ export class LocalAgentManager {
     operation: string,
   ): BetterResult<string, AgentScopeError> {
     const normalized = resolve(workspaceRoot);
+    if (workspaceId && this.validateWorkspaceScope) {
+      try {
+        return Result.ok(resolve(this.validateWorkspaceScope({ workspaceId, workspaceRoot: normalized }, operation)));
+      } catch (cause) {
+        return Result.err(new AgentScopeError({
+          code: "WORKSPACE_NOT_ALLOWED", operation, retryable: false, cause,
+          message: "Workspace root does not match its stored workspace identity.",
+        }));
+      }
+    }
     if (!workspaceId || !this.allowedRoots) return Result.ok(normalized);
     try {
       return Result.ok(assertAllowedPath(normalized, [...this.allowedRoots]));
@@ -615,9 +864,10 @@ export class LocalAgentManager {
   private async loadProfilesResult(
     workspaceRoot: string,
     target: string,
+    workspaceId?: string,
   ): Promise<BetterResult<LocalAgentProfile[], AgentTargetError>> {
     try {
-      return Result.ok(await this.loadProfiles(workspaceRoot));
+      return Result.ok(await this.loadProfiles(workspaceRoot, workspaceId));
     } catch (cause) {
       if (isProgrammerDefect(cause)) throw cause;
       return Result.err(new AgentTargetError({
@@ -647,6 +897,49 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function narrowerWriteMode(left: LocalAgentWriteMode, right: LocalAgentWriteMode): LocalAgentWriteMode {
+  const rank: Record<LocalAgentWriteMode, number> = { read_only: 0, allowed: 1, full_access: 2 };
+  return rank[left] <= rank[right] ? left : right;
+}
+
+function unavailableCapabilities(): LocalAgentCapabilities {
+  return {
+    cancellation: "unsupported",
+    structuredOutput: "validated_text",
+    usage: "unavailable",
+    correctionAuthority: "unsupported",
+    permissionRequests: "preconfigured",
+    progress: "final_only",
+  };
+}
+
+function numericField(value: object, key: string): number | undefined {
+  const field = (value as Record<string, unknown>)[key];
+  return typeof field === "number" && Number.isFinite(field) && field >= 0 ? field : undefined;
+}
+
+function stringField(value: object, key: string): string | undefined {
+  const field = (value as Record<string, unknown>)[key];
+  return typeof field === "string" ? field : undefined;
+}
+
+function booleanField(value: object, key: string): boolean | undefined {
+  const field = (value as Record<string, unknown>)[key];
+  return typeof field === "boolean" ? field : undefined;
+}
+
+function profileHash(target: NonNullable<ReturnType<typeof resolveLocalAgentTarget>>): string {
+  return createHash("sha256").update(JSON.stringify(target.kind === "profile" ? target.profile : {
+    name: target.name, provider: target.provider, model: target.model, effort: target.effort,
+  })).digest("hex");
+}
+
+function recordProfileHash(record: LocalAgentRecord, profile: LocalAgentProfile | undefined): string {
+  return createHash("sha256").update(JSON.stringify(profile ?? {
+    name: record.profileName, provider: record.provider, model: record.model, effort: record.effort,
+  })).digest("hex");
+}
+
 function safeCauseType(cause: unknown): string | undefined {
   if (cause instanceof Error) return cause.name;
   if (cause && typeof cause === "object" && "error" in cause) {
diff --git a/src/local-agent-opencode.test.ts b/src/local-agent-opencode.test.ts
index 69c358004..16e7d13a6 100644
--- a/src/local-agent-opencode.test.ts
+++ b/src/local-agent-opencode.test.ts
@@ -16,6 +16,7 @@ import { LocalAgentRuntimePool } from "./local-agent-runtime-pool.js";
 let sessionNumber = 0;
 const createInputs: unknown[] = [];
 const promptInputs: unknown[] = [];
+const abortInputs: unknown[] = [];
 let healthAvailable = true;
 const client = {
   global: {
@@ -33,13 +34,27 @@ const client = {
     async prompt(input: unknown) {
       promptInputs.push(input);
       const sessionId = (input as { sessionID: string }).sessionID;
+      if ((input as { parts?: Array<{ text?: string }> }).parts?.[0]?.text === "rate limited") {
+        return { data: { info: { role: "assistant", error: {
+          name: "APIError",
+          data: { message: "quota reached", statusCode: 429, isRetryable: true,
+            responseHeaders: { "Retry-After": "2" } },
+        } }, parts: [] } };
+      }
       return {
         data: {
-          info: { role: "assistant" },
+          info: {
+            role: "assistant",
+            tokens: { input: 3, output: 5, reasoning: 4, cache: { read: 1, write: 2 } },
+          },
           parts: [{ type: "text", text: `response:${sessionId}` }],
         },
       };
     },
+    async abort(input: unknown) {
+      abortInputs.push(input);
+      return { data: true };
+    },
   },
 } as unknown as OpencodeClientLike;
 let factoryCalls = 0;
@@ -55,6 +70,7 @@ const factory: OpencodeFactory = async (_context, env) => {
 };
 const driver = new OpencodeLocalAgentDriver(factory, { HARNESS_ENV: "opencode" });
 const pool = new LocalAgentRuntimePool();
+const usageUpdates: unknown[] = [];
 
 const first = await pool.run(driver, {
   agentId: "agt_one",
@@ -65,6 +81,9 @@ const first = await pool.run(driver, {
     workspaceRoot: "/tmp/project",
     model: "anthropic/sonnet",
     effort: "high",
+    attemptId: "attempt_opencode_1",
+  }, {
+    onUsage: (usage) => { usageUpdates.push(usage); },
   });
 const second = await pool.run(driver, {
   agentId: "agt_two",
@@ -79,6 +98,16 @@ assert.equal(factoryCalls, 1, "OpenCode agents share one server runtime");
 assert.equal(factoryEnv?.HARNESS_ENV, "opencode");
 assert.equal(first.isOk(), true);
 assert.equal(second.isOk(), true);
+assert.deepEqual(usageUpdates, [{
+  attemptId: "attempt_opencode_1",
+  sequence: 1,
+  inputTokens: 3,
+  outputTokens: 5,
+  reasoningTokens: 4,
+  cacheReadTokens: 1,
+  cacheWriteTokens: 2,
+  final: true,
+}]);
 
 if (process.platform !== "win32") {
   const commandRoot = await mkdtemp(join(tmpdir(), "devspace-opencode-env-"));
@@ -198,6 +227,46 @@ assert.deepEqual(promptInputs[2], {
   variant: "low",
 });
 
+const workflow = await pool.run(driver, {
+  agentId: "agt_workflow",
+  provider: "opencode",
+  workspaceRoot: "/tmp/project",
+  workflowRunId: "wfr_1",
+  workflowStepId: "wfs_1",
+  workflowAttemptId: "wfa_1",
+}, {
+  prompt: "bounded workflow turn",
+  workspaceRoot: "/tmp/project",
+  workflowRunId: "wfr_1",
+  workflowStepId: "wfs_1",
+  workflowAttemptId: "wfa_1",
+});
+assert.equal(workflow.isOk(), true);
+assert.equal(factoryCalls, 2, "workflow turns use a provenance-scoped OpenCode server");
+assert.equal(factoryEnv?.HARNESS_ENV, "opencode");
+assert.deepEqual(promptInputs[3], {
+  sessionID: "session_3",
+  directory: "/tmp/project",
+  parts: [{ type: "text", text: "bounded workflow turn" }],
+  agent: "devspace_allowed",
+  tools: { task: false },
+});
+
+const rateLimited = await pool.run(driver, {
+  agentId: "agt_one", provider: "opencode", workspaceRoot: "/tmp/project",
+}, {
+  prompt: "rate limited", workspaceRoot: "/tmp/project",
+  providerSessionId: firstRecord.providerSessionId ?? undefined,
+});
+assert.equal(rateLimited.isErr(), true);
+if (rateLimited.isErr()) {
+  assert.equal(rateLimited.error.retryAfterMs, 2_000);
+  assert.equal(rateLimited.error.executionUncertain, false);
+  assert.equal(typeof rateLimited.error.resetAt, "string");
+}
+
+let timeoutAbortCount = 0;
+let rejectOpenCodePrompt: ((error: Error) => void) | undefined;
 const timeoutClient = {
   global: {
     async health() { return { data: { healthy: true } }; },
@@ -206,9 +275,15 @@ const timeoutClient = {
     async create() { return { data: { id: "session_timeout" } }; },
     async prompt(_input: unknown, options?: { signal?: AbortSignal }) {
       return new Promise<never>((_resolve, reject) => {
+        rejectOpenCodePrompt = reject;
         options?.signal?.addEventListener("abort", () => reject(new DOMException("Aborted", "AbortError")), { once: true });
       });
     },
+    async abort() {
+      timeoutAbortCount += 1;
+      rejectOpenCodePrompt?.(new Error("server stopped the prompt"));
+      return { data: true };
+    },
   },
 } as unknown as OpencodeClientLike;
 const timeoutRuntime = new OpencodeRuntime(timeoutClient, { close: () => undefined }, 5);
@@ -223,9 +298,25 @@ if (timedOutPrompt.isErr()) {
   assert.match(timedOutPrompt.error.message, /provider timeout/);
 }
 await timeoutRuntime.close();
+assert.equal(timeoutAbortCount, 1, "provider timeout aborts the server-side OpenCode session");
+
+const cancellableRuntime = new OpencodeRuntime(timeoutClient, { close: () => undefined }, 60_000);
+const opencodeAbort = new AbortController();
+const cancelledPrompt = cancellableRuntime.run({
+  prompt: "cancel me",
+  workspaceRoot: "/tmp/project",
+}, undefined, { signal: opencodeAbort.signal });
+await new Promise<void>((resolve) => setImmediate(resolve));
+opencodeAbort.abort();
+const cancelledResult = await cancelledPrompt;
+assert.equal(cancelledResult.isErr(), true);
+if (cancelledResult.isErr()) assert.equal(cancelledResult.error.code, "PROVIDER_CANCELLED");
+assert.equal(timeoutAbortCount, 2);
+await cancellableRuntime.close();
 
 assert.equal(opencodeAgentFor("read_only"), "devspace_read_only");
 assert.equal(opencodeAgentFor("full_access"), "devspace_full_access");
+assert.equal(opencodeAgentFor("allowed", "none"), "devspace_no_tools");
 assert.deepEqual(opencodePermissionFor("allowed"), {
   read: "allow",
   edit: "allow",
@@ -346,4 +437,4 @@ await recoveringPool.close();
 
 await pool.close();
 await pool.close();
-assert.equal(closeCalls, 1, "shared OpenCode server closes once");
+assert.equal(closeCalls, 2, "the direct and workflow-scoped OpenCode servers each close once");
diff --git a/src/local-agent-opencode.ts b/src/local-agent-opencode.ts
index d9980aba2..e42692f75 100644
--- a/src/local-agent-opencode.ts
+++ b/src/local-agent-opencode.ts
@@ -10,13 +10,16 @@ import {
   AgentProviderUnavailableError,
   captureAgentProviderResult,
 } from "./local-agent-errors.js";
-import type {
-  LocalAgentDriver,
-  LocalAgentRunCallbacks,
-  LocalAgentRunInput,
-  LocalAgentRunResult,
-  LocalAgentRuntime,
-  LocalAgentRuntimeContext,
+import {
+  localAgentWorkflowEnvironment,
+  type LocalAgentDriver,
+  type LocalAgentRunCallbacks,
+  type LocalAgentRunControl,
+  type LocalAgentRunInput,
+  type LocalAgentRunResult,
+  type LocalAgentRuntime,
+  type LocalAgentRuntimeContext,
+  type LocalAgentUsageUpdate,
 } from "./local-agent-runtime.js";
 import { terminateProcessTree } from "./process-platform.js";
 
@@ -58,7 +61,11 @@ export class OpencodeRuntime implements LocalAgentRuntime {
     private readonly promptTimeoutMs = OPENCODE_PROMPT_TIMEOUT_MS,
   ) {}
 
-  async run(input: LocalAgentRunInput, callbacks?: LocalAgentRunCallbacks) {
+  async run(
+    input: LocalAgentRunInput,
+    callbacks?: LocalAgentRunCallbacks,
+    control?: LocalAgentRunControl,
+  ) {
     return captureAgentProviderResult({
       provider: this.provider,
       operation: "run",
@@ -76,14 +83,20 @@ export class OpencodeRuntime implements LocalAgentRuntime {
           await assertOpencodeHealthy(this.client);
           const sessionId = input.providerSessionId ?? await createOpencodeSession(this.client, input);
           await callbacks?.onSessionId?.(sessionId);
-          const promptResult = await this.prompt(sessionId, input);
+          const promptResult = await this.prompt(sessionId, input, control?.signal);
           assertOpenCodePromptSucceeded(promptResult);
           const finalResponse = requireFinalResponse(extractOpenCodeFinalResponse(promptResult));
+          const usage = opencodeUsage(input, promptResult);
+          if (usage) await callbacks?.onUsage?.(usage);
+          await callbacks?.onProgress?.({ type: "text", text: finalResponse.slice(0, 8 * 1024), final: true });
+          const structuredOutput = opencodeStructuredOutput(promptResult);
           return {
             provider: this.provider,
             providerSessionId: sessionId,
             finalResponse,
             items: [promptResult],
+            ...(structuredOutput === undefined ? {} : { structuredOutput }),
+            ...(usage ? { usage } : {}),
           };
         } catch (error) {
           if (isOpenCodeTransportFailure(error)) {
@@ -120,17 +133,38 @@ export class OpencodeRuntime implements LocalAgentRuntime {
     this.server.close();
   }
 
-  private async prompt(sessionId: string, input: LocalAgentRunInput): Promise<unknown> {
+  private async prompt(
+    sessionId: string,
+    input: LocalAgentRunInput,
+    signal?: AbortSignal,
+  ): Promise<unknown> {
     const controller = new AbortController();
     this.promptControllers.add(controller);
     let timedOut = false;
+    let cancelled = false;
+    let cancellation: Promise<boolean> | undefined;
+    const cancel = () => {
+      cancelled = true;
+      cancellation ??= this.client.session.abort({
+        sessionID: sessionId,
+        directory: input.workspaceRoot,
+      }, { throwOnError: true }).then(() => true, () => false);
+    };
+    if (signal?.aborted) cancel();
+    else signal?.addEventListener("abort", cancel, { once: true });
     const timer = setTimeout(() => {
       timedOut = true;
+      cancel();
       controller.abort();
     }, this.promptTimeoutMs);
     try {
-      return await promptOpencodeSession(this.client, sessionId, input, controller.signal);
+      const result = await promptOpencodeSession(this.client, sessionId, input, controller.signal);
+      if (cancelled && !timedOut && await cancellation) {
+        throw new DOMException("Aborted", "AbortError");
+      }
+      return result;
     } catch (error) {
+      if (cancelled && !timedOut && await cancellation) throw new DOMException("Aborted", "AbortError");
       if (!timedOut) throw error;
       throw new AgentProviderProtocolError({
         code: "PROVIDER_PROTOCOL_ERROR",
@@ -142,6 +176,7 @@ export class OpencodeRuntime implements LocalAgentRuntime {
       });
     } finally {
       clearTimeout(timer);
+      signal?.removeEventListener("abort", cancel);
       this.promptControllers.delete(controller);
     }
   }
@@ -156,8 +191,19 @@ export class OpencodeLocalAgentDriver implements LocalAgentDriver {
     private readonly env: NodeJS.ProcessEnv = process.env,
   ) {}
 
-  runtimeKey(_context: LocalAgentRuntimeContext): string {
-    return "opencode:default";
+  runtimeKey(context: LocalAgentRuntimeContext): string {
+    return context.workflowRunId ? `opencode:workflow:${context.workflowRunId}` : "opencode:default";
+  }
+
+  capabilities() {
+    return {
+      cancellation: "turn",
+      structuredOutput: "validated_text",
+      usage: "final",
+      correctionAuthority: "no_tools",
+      permissionRequests: "preconfigured",
+      progress: "final_only",
+    } as const;
   }
 
   async createRuntime(context: LocalAgentRuntimeContext) {
@@ -174,7 +220,7 @@ export class OpencodeLocalAgentDriver implements LocalAgentDriver {
 }
 
 async function defaultOpencodeFactory(
-  _context?: LocalAgentRuntimeContext,
+  context?: LocalAgentRuntimeContext,
   env: NodeJS.ProcessEnv = process.env,
 ): Promise<{ client: OpencodeClientLike; server: OpencodeServerLike }> {
   const { createOpencodeClient } = await import("@opencode-ai/sdk/v2");
@@ -183,9 +229,10 @@ async function defaultOpencodeFactory(
       devspace_read_only: opencodeAgentConfig("read_only"),
       devspace_allowed: opencodeAgentConfig("allowed"),
       devspace_full_access: opencodeAgentConfig("full_access"),
+      devspace_no_tools: opencodeAgentConfig("read_only"),
     },
   };
-  const server = await startOpencodeServer(env, config);
+  const server = await startOpencodeServer(localAgentWorkflowEnvironment(env, context ?? {}), config);
   return {
     client: createOpencodeClient({ baseUrl: server.url }),
     server,
@@ -323,7 +370,12 @@ async function createOpencodeSession(
   return requireSessionId(result.data);
 }
 
-export function opencodeAgentFor(writeMode: LocalAgentRunInput["writeMode"]): string {
+export function opencodeAgentFor(
+  writeMode: LocalAgentRunInput["writeMode"],
+  toolPolicy: LocalAgentRunInput["toolPolicy"] = "normal",
+): string {
+  if (toolPolicy === "none") return "devspace_no_tools";
+  if (toolPolicy === "read_only") return "devspace_read_only";
   switch (writeMode) {
     case "read_only": return "devspace_read_only";
     case "full_access": return "devspace_full_access";
@@ -394,7 +446,13 @@ async function promptOpencodeSession(
     sessionID: sessionId,
     directory: input.workspaceRoot,
     parts: [{ type: "text", text: input.prompt }],
-    agent: opencodeAgentFor(input.writeMode),
+    agent: opencodeAgentFor(input.writeMode, input.toolPolicy),
+    ...(input.toolPolicy === "none"
+      ? { tools: {
+          read: false, edit: false, write: false, glob: false, grep: false,
+          list: false, bash: false, task: false, webfetch: false,
+        } }
+      : input.workflowRunId ? { tools: { task: false } } : {}),
     ...(model ? { model } : {}),
     ...(input.effort ? { variant: input.effort } : {}),
   }, { throwOnError: true, signal });
@@ -427,6 +485,7 @@ function assertOpenCodePromptSucceeded(value: unknown): void {
   const error = asRecord(info?.error);
   if (!error) return;
   const data = asRecord(error.data);
+  const rateLimit = openCodeRateLimit(error, data);
   const message = typeof data?.message === "string"
     ? data.message
     : typeof error.message === "string"
@@ -439,11 +498,29 @@ function assertOpenCodePromptSucceeded(value: unknown): void {
     provider: "opencode",
     operation: "prompt",
     retryable: data?.isRetryable === true,
+    ...(rateLimit ?? {}),
+    executionUncertain: false,
     cause: error,
     message,
   });
 }
 
+function openCodeRateLimit(
+  error: Record<string, unknown>,
+  data: Record<string, unknown> | undefined,
+): { retryAfterMs: number; resetAt: string } | undefined {
+  if (error.name !== "APIError" || data?.statusCode !== 429) return undefined;
+  const headers = asRecord(data.responseHeaders);
+  const retryAfter = Object.entries(headers ?? {}).find(([name]) => name.toLowerCase() === "retry-after")?.[1];
+  if (typeof retryAfter !== "string" || !/^\d+$/.test(retryAfter.trim())) return undefined;
+  const seconds = Number(retryAfter.trim());
+  if (!Number.isSafeInteger(seconds) || seconds < 0 || seconds > Math.floor(Number.MAX_SAFE_INTEGER / 1_000)) {
+    return undefined;
+  }
+  const retryAfterMs = seconds * 1_000;
+  return { retryAfterMs, resetAt: new Date(Date.now() + retryAfterMs).toISOString() };
+}
+
 export function extractOpenCodeFinalResponse(value: unknown): string {
   const root = unwrapProviderPayload(value);
   const messages = Array.isArray(root) ? root : readArray(root, "messages");
@@ -451,6 +528,47 @@ export function extractOpenCodeFinalResponse(value: unknown): string {
   return extractOpenCodeAssistantMessageText(root);
 }
 
+function opencodeUsage(
+  input: LocalAgentRunInput,
+  value: unknown,
+): LocalAgentUsageUpdate | undefined {
+  const root = asRecord(unwrapProviderPayload(value));
+  const info = asRecord(root?.info) ?? root;
+  const tokens = asRecord(info?.tokens);
+  if (!tokens) return undefined;
+  const cache = asRecord(tokens.cache);
+  const outputTokens = finiteNonnegative(tokens.output);
+  if (outputTokens === undefined) return undefined;
+  return {
+    attemptId: input.attemptId ?? "untracked",
+    sequence: 1,
+    inputTokens: finiteNonnegative(tokens.input),
+    outputTokens,
+    reasoningTokens: finiteNonnegative(tokens.reasoning),
+    cacheReadTokens: finiteNonnegative(cache?.read),
+    cacheWriteTokens: finiteNonnegative(cache?.write),
+    final: true,
+  };
+}
+
+function opencodeStructuredOutput(value: unknown): LocalAgentRunResult["structuredOutput"] | undefined {
+  const root = asRecord(unwrapProviderPayload(value));
+  const structured = asRecord(root?.info)?.structured;
+  return isJsonValue(structured) ? structured : undefined;
+}
+
+function isJsonValue(value: unknown): value is Exclude<LocalAgentRunResult["structuredOutput"], undefined> {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isJsonValue);
+  const record = asRecord(value);
+  return Boolean(record && Object.getPrototypeOf(value) === Object.prototype && Object.values(record).every(isJsonValue));
+}
+
+function finiteNonnegative(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
 function extractLastOpenCodeAssistantMessageText(messages: unknown[]): string {
   for (let index = messages.length - 1; index >= 0; index -= 1) {
     const message = asRecord(messages[index]);
diff --git a/src/local-agent-pi.test.ts b/src/local-agent-pi.test.ts
index df111666c..c42d7c79e 100644
--- a/src/local-agent-pi.test.ts
+++ b/src/local-agent-pi.test.ts
@@ -18,16 +18,25 @@ class FakePiSession implements PiSessionLike {
   effort?: unknown;
   activeTools: string[] = [];
   toolHistory: string[][] = [];
+  abortCount = 0;
+  private releaseHold?: () => void;
 
   async prompt(text: string): Promise<void> {
+    if (text === "hold") await new Promise<void>((resolve) => { this.releaseHold = resolve; });
     const message = {
       role: "assistant",
       content: [{ type: "text", text: `response:${text}` }],
+      usage: { input: 3, output: 5, cacheRead: 1, cacheWrite: 2 },
     };
     this.messages.push(message);
     for (const listener of this.listeners) listener({ type: "agent_end" } as AgentSessionEvent);
   }
 
+  async abort(): Promise<void> {
+    this.abortCount += 1;
+    this.releaseHold?.();
+  }
+
   subscribe(listener: AgentSessionEventListener): () => void {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
@@ -69,6 +78,7 @@ const context: LocalAgentRuntimeContext = {
   workspaceRoot: "/tmp/project",
 };
 const sessionIds: string[] = [];
+const usageUpdates: unknown[] = [];
 
 const first = await pool.run(driver, context, {
   prompt: "first",
@@ -76,8 +86,10 @@ const first = await pool.run(driver, context, {
   model: "provider/model",
   effort: "high",
   writeMode: "read_only",
+  attemptId: "attempt_pi_1",
 }, {
   onSessionId: (sessionId) => { sessionIds.push(sessionId); },
+  onUsage: (usage) => { usageUpdates.push(usage); },
 });
 assert.equal(factoryEnv?.HARNESS_ENV, "pi");
 const second = await pool.run(driver, context, {
@@ -105,6 +117,15 @@ assert.equal(second.value.finalResponse, "response:second");
 assert.deepEqual(sessions[0]?.model, { id: "model" });
 assert.equal(sessions[0]?.effort, "high");
 assert.deepEqual(sessionIds, ["pi_session_1"]);
+assert.deepEqual(usageUpdates, [{
+  attemptId: "attempt_pi_1",
+  sequence: 1,
+  inputTokens: 3,
+  outputTokens: 5,
+  cacheReadTokens: 1,
+  cacheWriteTokens: 2,
+  final: true,
+}]);
 assert.deepEqual(sessions[0]?.activeTools, ["read", "grep", "find", "ls"]);
 assert.deepEqual(sessions[0]?.toolHistory, [
   ["read", "grep", "find", "ls"],
@@ -134,6 +155,24 @@ assert.equal(contexts[1]?.providerSessionId, "pi_session_1");
 assert.deepEqual(sessions[1]?.activeTools, ["read", "grep", "find", "ls", "edit", "write", "bash"]);
 await pool.close();
 
+const cancellationSession = new FakePiSession();
+const cancellationDriver = new PiLocalAgentDriver(async () => cancellationSession);
+const cancellationRuntime = await cancellationDriver.createRuntime(context);
+assert.equal(cancellationRuntime.isOk(), true);
+if (cancellationRuntime.isErr()) throw cancellationRuntime.error;
+const turnAbort = new AbortController();
+const cancelledTurn = cancellationRuntime.value.run({
+  prompt: "hold",
+  workspaceRoot: "/tmp/project",
+}, undefined, { signal: turnAbort.signal });
+await new Promise<void>((resolve) => setImmediate(resolve));
+turnAbort.abort();
+const cancelledResult = await cancelledTurn;
+assert.equal(cancelledResult.isErr(), true);
+if (cancelledResult.isErr()) assert.equal(cancelledResult.error.code, "PROVIDER_CANCELLED");
+assert.equal(cancellationSession.abortCount, 1);
+await cancellationRuntime.value.close();
+
 const missingModelSession = new FakePiSession();
 Object.defineProperty(missingModelSession, "modelRegistry", { value: { find: () => undefined } });
 const missingModelDriver = new PiLocalAgentDriver(async () => missingModelSession);
diff --git a/src/local-agent-pi.ts b/src/local-agent-pi.ts
index bfb85cb3a..27263b3a9 100644
--- a/src/local-agent-pi.ts
+++ b/src/local-agent-pi.ts
@@ -6,13 +6,17 @@ import {
   AgentProviderUnavailableError,
   captureAgentProviderResult,
 } from "./local-agent-errors.js";
-import type {
-  LocalAgentDriver,
-  LocalAgentRunCallbacks,
-  LocalAgentRunInput,
-  LocalAgentRunResult,
-  LocalAgentRuntime,
-  LocalAgentRuntimeContext,
+import {
+  localAgentWorkflowEnvironment,
+  type LocalAgentDriver,
+  type LocalAgentProgressUpdate,
+  type LocalAgentRunCallbacks,
+  type LocalAgentRunControl,
+  type LocalAgentRunInput,
+  type LocalAgentRunResult,
+  type LocalAgentRuntime,
+  type LocalAgentRuntimeContext,
+  type LocalAgentUsageUpdate,
 } from "./local-agent-runtime.js";
 import {
   createPiSandboxExtension,
@@ -38,7 +42,7 @@ export type PiSessionLike = Pick<
   | "setModel"
   | "setThinkingLevel"
   | "dispose"
->;
+> & { abort?: () => Promise<void> };
 
 export type PiSessionFactory = (
   context: LocalAgentRuntimeContext,
@@ -53,6 +57,8 @@ export class PiSessionRuntime implements LocalAgentRuntime {
   private closed = false;
   private collectingEvents = false;
   private events: unknown[] = [];
+  private onProgress?: LocalAgentRunCallbacks["onProgress"];
+  private progress = Promise.resolve();
 
   constructor(
     private readonly session: PiSessionLike,
@@ -61,10 +67,19 @@ export class PiSessionRuntime implements LocalAgentRuntime {
       if (!this.collectingEvents) return;
       if (this.events.length >= MAX_PI_EVENTS) this.events.shift();
       this.events.push(event);
+      const update = piProgress(event);
+      const callback = this.onProgress;
+      if (update && callback) {
+        this.progress = this.progress.then(() => callback(update));
+      }
     });
   }
 
-  async run(input: LocalAgentRunInput, callbacks?: LocalAgentRunCallbacks) {
+  async run(
+    input: LocalAgentRunInput,
+    callbacks?: LocalAgentRunCallbacks,
+    control?: LocalAgentRunControl,
+  ) {
     return captureAgentProviderResult({
       provider: this.provider,
       operation: "run",
@@ -83,10 +98,33 @@ export class PiSessionRuntime implements LocalAgentRuntime {
         this.events = [];
         const messageStart = this.session.messages.length;
         this.collectingEvents = true;
+        this.onProgress = callbacks?.onProgress;
+        this.progress = Promise.resolve();
+        let cancellation: Promise<boolean> | undefined;
+        const abort = () => {
+          cancellation ??= this.session.abort
+            ? this.session.abort().then(() => true, () => false)
+            : Promise.resolve(false);
+        };
+        if (control?.signal.aborted) throw new DOMException("Aborted", "AbortError");
+        control?.signal.addEventListener("abort", abort, { once: true });
         try {
-          await this.session.prompt(input.prompt);
+          try {
+            await this.session.prompt(input.prompt);
+          } catch (error) {
+            if (control?.signal.aborted && await cancellation) {
+              throw new DOMException("Aborted", "AbortError");
+            }
+            throw error;
+          }
         } finally {
+          control?.signal.removeEventListener("abort", abort);
           this.collectingEvents = false;
+          this.onProgress = undefined;
+        }
+        await this.progress;
+        if (control?.signal.aborted && await cancellation) {
+          throw new DOMException("Aborted", "AbortError");
         }
         const currentMessages = this.session.messages.slice(messageStart);
         const finalResponse = extractPiFinalResponse({ messages: currentMessages });
@@ -110,11 +148,14 @@ export class PiSessionRuntime implements LocalAgentRuntime {
             message: "Pi did not return a final assistant response.",
           });
         }
+        const usage = piUsage(input, currentMessages);
+        if (usage) await callbacks?.onUsage?.(usage);
         return {
           provider: this.provider,
           providerSessionId: this.session.sessionId,
           finalResponse,
           items: [...this.events, ...currentMessages],
+          ...(usage ? { usage } : {}),
         };
       },
     });
@@ -142,7 +183,9 @@ export class PiSessionRuntime implements LocalAgentRuntime {
 
   private async applyOverrides(input: LocalAgentRunInput): Promise<void> {
     await updatePiSandboxSession(this.session, input.workspaceRoot, input.writeMode ?? "allowed");
-    this.session.setActiveToolsByName([...piToolsForWriteMode(input.writeMode)]);
+    this.session.setActiveToolsByName(input.toolPolicy === "none"
+      ? []
+      : [...piToolsForWriteMode(input.toolPolicy === "read_only" ? "read_only" : input.writeMode)]);
     if (input.model) {
       const model = resolvePiModel(this.session.modelRegistry, input.model);
       if (!model) {
@@ -172,7 +215,18 @@ export class PiLocalAgentDriver implements LocalAgentDriver {
   ) {}
 
   runtimeKey(context: LocalAgentRuntimeContext): string {
-    return `pi:${context.agentId}`;
+    return `pi:${context.agentId}${context.workflowRunId ? `:workflow:${context.workflowRunId}` : ""}`;
+  }
+
+  capabilities() {
+    return {
+      cancellation: "turn",
+      structuredOutput: "validated_text",
+      usage: "final",
+      correctionAuthority: "no_tools",
+      permissionRequests: "preconfigured",
+      progress: "tools_and_text",
+    } as const;
   }
 
   async createRuntime(context: LocalAgentRuntimeContext) {
@@ -188,6 +242,8 @@ export class PiLocalAgentDriver implements LocalAgentDriver {
           writeMode: context.writeMode,
           model: context.model,
           effort: context.effort,
+          outputSchema: context.outputSchema,
+          toolPolicy: context.toolPolicy,
         };
         const session = await this.factory(context, input, this.env);
         return new PiSessionRuntime(session);
@@ -231,7 +287,11 @@ async function defaultPiSessionFactory(
   const resourceLoader = new DefaultResourceLoader({
     cwd: input.workspaceRoot,
     agentDir,
-    extensionFactories: [createPiSandboxExtension(input.workspaceRoot, modeRef, env)],
+    extensionFactories: [createPiSandboxExtension(
+      input.workspaceRoot,
+      modeRef,
+      localAgentWorkflowEnvironment(env, input),
+    )],
   });
   let session: PiSessionLike | undefined;
   try {
@@ -250,7 +310,9 @@ async function defaultPiSessionFactory(
     });
     session = result.session;
     await registerPiSandboxSession(session, input.workspaceRoot, modeRef, input.writeMode ?? "allowed");
-    session.setActiveToolsByName([...piToolsForWriteMode(input.writeMode)]);
+    session.setActiveToolsByName(input.toolPolicy === "none"
+      ? []
+      : [...piToolsForWriteMode(input.toolPolicy === "read_only" ? "read_only" : input.writeMode)]);
     return session;
   } catch (error) {
     if (session) {
@@ -369,6 +431,59 @@ export function extractPiProviderError(value: unknown): string {
   return typeof error === "string" ? error.trim() : "";
 }
 
+function piUsage(
+  input: LocalAgentRunInput,
+  messages: readonly unknown[],
+): LocalAgentUsageUpdate | undefined {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
+  let found = false;
+  for (const message of messages) {
+    const usage = asRecord(asRecord(message)?.usage);
+    if (!usage) continue;
+    const output = finiteNonnegative(usage.output);
+    if (output === undefined) continue;
+    found = true;
+    inputTokens += finiteNonnegative(usage.input) ?? 0;
+    outputTokens += output;
+    cacheReadTokens += finiteNonnegative(usage.cacheRead) ?? 0;
+    cacheWriteTokens += finiteNonnegative(usage.cacheWrite) ?? 0;
+  }
+  return found ? {
+    attemptId: input.attemptId ?? "untracked",
+    sequence: 1,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    final: true,
+  } : undefined;
+}
+
+function piProgress(value: unknown): LocalAgentProgressUpdate | undefined {
+  const event = asRecord(value);
+  if (!event) return undefined;
+  const type = event?.type;
+  if (type === "tool_execution_start" || type === "tool_execution_update" || type === "tool_execution_end") {
+    const toolName = typeof event.toolName === "string" ? event.toolName : "tool";
+    return {
+      type: "tool",
+      toolName,
+      status: type === "tool_execution_start" ? "started" : type === "tool_execution_end" ? "completed" : "updated",
+    };
+  }
+  if (type !== "message_update" && type !== "message_end") return undefined;
+  const message = asRecord(event.message);
+  const text = extractPiFinalResponse([message]);
+  return text ? { type: "text", text, ...(type === "message_end" ? { final: true } : {}) } : undefined;
+}
+
+function finiteNonnegative(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
 function unwrapProviderPayload(value: unknown): unknown {
   const record = asRecord(value);
   return record ? record.data ?? record.result ?? value : value;
diff --git a/src/local-agent-presentation.ts b/src/local-agent-presentation.ts
index f5ff569ec..2bfca3fd4 100644
--- a/src/local-agent-presentation.ts
+++ b/src/local-agent-presentation.ts
@@ -15,6 +15,7 @@ export type AgentTargetOutput =
       kind: "profile";
       provider: string;
       description: string;
+      writeMode?: "allowed" | "read_only" | "full_access";
       model?: string;
       effort?: string;
     };
@@ -67,6 +68,7 @@ export function presentAgentTargetCatalog(catalog: LocalAgentCatalog): AgentTarg
         kind: "profile",
         provider: profile.provider,
         description: profile.description,
+        ...(profile.writeMode ? { writeMode: profile.writeMode } : {}),
         ...(profile.model ? { model: profile.model } : {}),
         ...(profile.effort ? { effort: profile.effort } : {}),
       })),
@@ -110,7 +112,7 @@ export function formatAgentTargetCatalog(catalog: AgentTargetCatalogOutput): str
     if (target.kind === "provider") {
       return `<provider name="${escapeXmlAttribute(target.name)}"${settings}/>`;
     }
-    return `<profile name="${escapeXmlAttribute(target.name)}" provider="${escapeXmlAttribute(target.provider)}"${settings}>${escapeXmlText(target.description)}</profile>`;
+    return `<profile name="${escapeXmlAttribute(target.name)}" provider="${escapeXmlAttribute(target.provider)}"${xmlAttributes({ write_mode: target.writeMode })}${settings}>${escapeXmlText(target.description)}</profile>`;
   }).join("\n");
 }
 
diff --git a/src/local-agent-profiles.test.ts b/src/local-agent-profiles.test.ts
index 8a7d57db1..07eba4427 100644
--- a/src/local-agent-profiles.test.ts
+++ b/src/local-agent-profiles.test.ts
@@ -37,6 +37,7 @@ try {
       "provider: claude",
       "model: sonnet",
       "effort: high",
+      "writeMode: read_only",
       "---",
       "",
       "Project body.",
@@ -70,6 +71,7 @@ try {
   assert.equal(profiles[0]?.provider, "claude");
   assert.equal(profiles[0]?.model, "sonnet");
   assert.equal(profiles[0]?.effort, "high");
+  assert.equal(profiles[0]?.writeMode, "read_only");
   assert.equal(profiles[0]?.body, "Project body.");
   await writeFile(
     join(workspaceRoot, ".devspace", "agents", "custom.md"),
diff --git a/src/local-agent-profiles.ts b/src/local-agent-profiles.ts
index ad99a225c..d6804f544 100644
--- a/src/local-agent-profiles.ts
+++ b/src/local-agent-profiles.ts
@@ -3,6 +3,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { ServerConfig } from "./config.js";
+import type { LocalAgentWriteMode } from "./local-agent-runtime.js";
 
 export type LocalAgentProvider = "codex" | "claude" | "opencode" | "pi" | "cursor" | "copilot" | "grok";
 
@@ -22,6 +23,7 @@ export interface LocalAgentProfile {
   provider: LocalAgentProvider;
   model?: string;
   effort?: string;
+  writeMode?: LocalAgentWriteMode;
   filePath: string;
   body: string;
   disabled: boolean;
@@ -33,6 +35,7 @@ export interface LocalAgentProfileSummary {
   provider: LocalAgentProvider;
   model?: string;
   effort?: string;
+  writeMode?: LocalAgentWriteMode;
 }
 
 interface ParsedFrontmatter {
@@ -148,12 +151,23 @@ function profileFromFrontmatter(
     provider,
     model: readString(frontmatter, "model"),
     effort: readString(frontmatter, "effort"),
+    writeMode: readWriteMode(frontmatter, filePath),
     filePath,
     body,
     disabled: frontmatter.disabled === true,
   };
 }
 
+function readWriteMode(
+  frontmatter: Record<string, unknown>,
+  filePath: string,
+): LocalAgentWriteMode | undefined {
+  const value = readString(frontmatter, "writeMode");
+  if (!value) return undefined;
+  if (value === "read_only" || value === "allowed" || value === "full_access") return value;
+  throw new Error(`Subagent profile writeMode must be read_only, allowed, or full_access: ${filePath}`);
+}
+
 function readProvider(frontmatter: Record<string, unknown>, filePath: string): LocalAgentProvider {
   const provider = readString(frontmatter, "provider");
   if (!provider) {
diff --git a/src/local-agent-runtime-pool.ts b/src/local-agent-runtime-pool.ts
index a03150240..13c0dcc95 100644
--- a/src/local-agent-runtime-pool.ts
+++ b/src/local-agent-runtime-pool.ts
@@ -9,6 +9,7 @@ import type {
   LocalAgentRunCallbacks,
   LocalAgentRunInput,
   LocalAgentRunResult,
+  LocalAgentRunControl,
   LocalAgentRuntime,
   LocalAgentRuntimeContext,
 } from "./local-agent-runtime.js";
@@ -76,6 +77,7 @@ export class LocalAgentRuntimePool {
     context: LocalAgentRuntimeContext,
     input: LocalAgentRunInput,
     inputCallbacks?: LocalAgentRunCallbacks,
+    control?: LocalAgentRunControl,
   ): Promise<BetterResult<LocalAgentRunResult, AgentProviderError>> {
     if (this.closing) return Result.err(poolClosedError(driver, context));
 
@@ -129,12 +131,16 @@ export class LocalAgentRuntimePool {
         if (reservationError) throw reservationError;
         await inputCallbacks?.onSessionId?.(providerSessionId);
       },
+      onUsage: (usage) => inputCallbacks?.onUsage?.(usage),
+      onProgress: (progress) => inputCallbacks?.onProgress?.(progress),
+      onPermissionRequest: (request) => inputCallbacks?.onPermissionRequest?.(request)
+        ?? { outcome: "cancelled" },
     };
     const startedAt = this.now();
     try {
       const inputReservationError = await reserveSession(input.providerSessionId ?? "");
       if (inputReservationError) return Result.err(inputReservationError);
-      const result = await runtime.run(input, callbacks);
+      const result = await runtime.run(input, callbacks, control);
       if (result.isErr()) {
         if (!runtime.isAlive()) {
           try {
diff --git a/src/local-agent-runtime.test.ts b/src/local-agent-runtime.test.ts
index da2364005..9a35fa634 100644
--- a/src/local-agent-runtime.test.ts
+++ b/src/local-agent-runtime.test.ts
@@ -7,12 +7,13 @@ import {
   type AgentProviderError,
 } from "./local-agent-errors.js";
 import { LocalAgentRuntimePool } from "./local-agent-runtime-pool.js";
-import type {
-  LocalAgentDriver,
-  LocalAgentRunInput,
-  LocalAgentRunResult,
-  LocalAgentRuntime,
-  LocalAgentRuntimeContext,
+import {
+  localAgentWorkflowEnvironment,
+  type LocalAgentDriver,
+  type LocalAgentRunInput,
+  type LocalAgentRunResult,
+  type LocalAgentRuntime,
+  type LocalAgentRuntimeContext,
 } from "./local-agent-runtime.js";
 
 const context: LocalAgentRuntimeContext = {
@@ -22,6 +23,15 @@ const context: LocalAgentRuntimeContext = {
 };
 const input: LocalAgentRunInput = { prompt: "inspect", workspaceRoot: "/tmp/project" };
 
+assert.deepEqual(localAgentWorkflowEnvironment({ PATH: "/bin" }, {
+  workflowRunId: "wfr_1", workflowStepId: "wfs_1", workflowAttemptId: "wfa_1",
+}), {
+  PATH: "/bin",
+  DEVSPACE_WORKFLOW_RUN_ID: "wfr_1",
+  DEVSPACE_WORKFLOW_STEP_ID: "wfs_1",
+  DEVSPACE_WORKFLOW_ATTEMPT_ID: "wfa_1",
+});
+
 for (const [code, retryable] of [["ENOENT", false], ["ECONNREFUSED", true], ["ENOTFOUND", true]] as const) {
   const classified = await captureAgentProviderResult({
     provider: "codex",
diff --git a/src/local-agent-runtime.ts b/src/local-agent-runtime.ts
index ecc40f545..3c74fdd71 100644
--- a/src/local-agent-runtime.ts
+++ b/src/local-agent-runtime.ts
@@ -3,6 +3,55 @@ import type { AgentProviderError } from "./local-agent-errors.js";
 import type { LocalAgentProvider } from "./local-agent-profiles.js";
 
 export type LocalAgentWriteMode = "read_only" | "allowed" | "full_access";
+export type LocalAgentToolPolicy = "normal" | "read_only" | "none";
+
+export type LocalAgentJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly LocalAgentJsonValue[]
+  | { readonly [key: string]: LocalAgentJsonValue };
+
+export type LocalAgentJsonSchema = Record<string, LocalAgentJsonValue>;
+
+export interface LocalAgentCapabilities {
+  cancellation: "turn" | "dedicated_process" | "unsupported";
+  structuredOutput: "native" | "validated_text";
+  usage: "streaming" | "final" | "unavailable";
+  correctionAuthority: "no_tools" | "read_only" | "unsupported";
+  permissionRequests: "interactive" | "preconfigured";
+  progress: "tools_and_text" | "text" | "final_only";
+}
+
+export interface LocalAgentUsageUpdate {
+  attemptId: string;
+  sequence: number;
+  outputTokens: number;
+  inputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  reasoningTokens?: number;
+  final: boolean;
+}
+
+export type LocalAgentProgressUpdate =
+  | { type: "text"; text: string; final?: boolean }
+  | { type: "tool"; toolName: string; status: "started" | "updated" | "completed"; summary?: string };
+
+export interface LocalAgentPermissionRequest {
+  requestId: string;
+  description: string;
+  options: readonly { id: string; label: string; kind: string }[];
+}
+
+export type LocalAgentPermissionDecision =
+  | { outcome: "selected"; optionId: string }
+  | { outcome: "cancelled" };
+
+export interface LocalAgentRunControl {
+  signal: AbortSignal;
+}
 
 export interface LocalAgentRunInput {
   prompt: string;
@@ -13,6 +62,12 @@ export interface LocalAgentRunInput {
   effort?: string;
   modelOverrideRequested?: boolean;
   effortOverrideRequested?: boolean;
+  attemptId?: string;
+  outputSchema?: LocalAgentJsonSchema;
+  toolPolicy?: LocalAgentToolPolicy;
+  workflowRunId?: string;
+  workflowStepId?: string;
+  workflowAttemptId?: string;
 }
 
 export interface LocalAgentRunResult {
@@ -20,6 +75,8 @@ export interface LocalAgentRunResult {
   providerSessionId: string | null;
   finalResponse: string;
   items: unknown[];
+  structuredOutput?: LocalAgentJsonValue;
+  usage?: LocalAgentUsageUpdate;
 }
 
 export interface LocalAgentRunCallbacks {
@@ -29,6 +86,11 @@ export interface LocalAgentRunCallbacks {
    * could otherwise fail and lose that identity.
    */
   onSessionId?: (providerSessionId: string) => void | Promise<void>;
+  onUsage?: (usage: LocalAgentUsageUpdate) => void | Promise<void>;
+  onProgress?: (progress: LocalAgentProgressUpdate) => void | Promise<void>;
+  onPermissionRequest?: (
+    request: LocalAgentPermissionRequest,
+  ) => LocalAgentPermissionDecision | Promise<LocalAgentPermissionDecision>;
 }
 
 export interface LocalAgentRuntimeContext {
@@ -39,6 +101,11 @@ export interface LocalAgentRuntimeContext {
   writeMode?: LocalAgentWriteMode;
   model?: string;
   effort?: string;
+  outputSchema?: LocalAgentJsonSchema;
+  toolPolicy?: LocalAgentToolPolicy;
+  workflowRunId?: string;
+  workflowStepId?: string;
+  workflowAttemptId?: string;
   agentDir?: string;
 }
 
@@ -52,6 +119,7 @@ export interface LocalAgentRuntime {
   run(
     input: LocalAgentRunInput,
     callbacks?: LocalAgentRunCallbacks,
+    control?: LocalAgentRunControl,
   ): Promise<Result<LocalAgentRunResult, AgentProviderError>>;
   releaseSession(providerSessionId: string): Promise<void>;
   close(): Promise<void>;
@@ -62,5 +130,34 @@ export interface LocalAgentDriver {
   readonly provider: LocalAgentProvider;
   runtimeKey(context: LocalAgentRuntimeContext): string;
   createRuntime(context: LocalAgentRuntimeContext): Promise<Result<LocalAgentRuntime, AgentProviderError>>;
+  capabilities?(context: LocalAgentRuntimeContext, input: LocalAgentRunInput): LocalAgentCapabilities;
   readonly idleTimeoutMs?: number;
 }
+
+export function localAgentCapabilities(
+  driver: LocalAgentDriver,
+  context: LocalAgentRuntimeContext,
+  input: LocalAgentRunInput,
+): LocalAgentCapabilities {
+  return driver.capabilities?.(context, input) ?? {
+    cancellation: "unsupported",
+    structuredOutput: "validated_text",
+    usage: "unavailable",
+    correctionAuthority: "unsupported",
+    permissionRequests: "preconfigured",
+    progress: "final_only",
+  };
+}
+
+export function localAgentWorkflowEnvironment(
+  env: NodeJS.ProcessEnv,
+  provenance: Pick<LocalAgentRuntimeContext, "workflowRunId" | "workflowStepId" | "workflowAttemptId">,
+): NodeJS.ProcessEnv {
+  if (!provenance.workflowRunId) return env;
+  return {
+    ...env,
+    DEVSPACE_WORKFLOW_RUN_ID: provenance.workflowRunId,
+    ...(provenance.workflowStepId ? { DEVSPACE_WORKFLOW_STEP_ID: provenance.workflowStepId } : {}),
+    ...(provenance.workflowAttemptId ? { DEVSPACE_WORKFLOW_ATTEMPT_ID: provenance.workflowAttemptId } : {}),
+  };
+}
diff --git a/src/local-agent-store.ts b/src/local-agent-store.ts
index 3aab64da6..6812b38fd 100644
--- a/src/local-agent-store.ts
+++ b/src/local-agent-store.ts
@@ -6,6 +6,7 @@ import { AgentStoreError, isProgrammerDefect } from "./local-agent-errors.js";
 
 export type LocalAgentStatus = "starting" | "running" | "idle" | "error" | "stopped";
 export type LocalAgentTurnStatus = "running" | "completed" | "failed" | "stopped";
+export type PersistedLocalAgentWriteMode = "allowed" | "read_only" | "full_access";
 
 export interface LocalAgentRecord {
   id: string;
@@ -15,6 +16,7 @@ export interface LocalAgentRecord {
   provider: string;
   model?: string;
   effort?: string;
+  writeMode?: PersistedLocalAgentWriteMode;
   providerSessionId?: string;
   status: LocalAgentStatus;
   latestResponse?: string;
@@ -32,6 +34,7 @@ export interface CreateLocalAgentRecordInput {
   provider: string;
   model?: string;
   effort?: string;
+  writeMode?: PersistedLocalAgentWriteMode;
 }
 
 export interface LocalAgentTurnRecord {
@@ -43,6 +46,16 @@ export interface LocalAgentTurnRecord {
   error?: string;
   errorCode?: string;
   errorRetryable?: boolean;
+  writeMode?: PersistedLocalAgentWriteMode;
+  model?: string;
+  effort?: string;
+  attemptId?: string;
+  workflowRunId?: string;
+  workflowStepId?: string;
+  workflowAttemptId?: string;
+  retryAfterMs?: number;
+  resetAt?: string;
+  executionUncertain?: boolean;
   createdAt: string;
   completedAt?: string;
 }
@@ -51,11 +64,16 @@ export interface BeginLocalAgentTurnInput {
   prompt: string;
   model?: string;
   effort?: string;
+  writeMode?: PersistedLocalAgentWriteMode;
+  attemptId?: string;
+  workflowRunId?: string;
+  workflowStepId?: string;
+  workflowAttemptId?: string;
 }
 
 export type FinishLocalAgentTurnInput =
   | { status: "completed"; response?: string; providerSessionId?: string }
-  | { status: "failed"; error: string; errorCode: string; errorRetryable: boolean }
+  | { status: "failed"; error: string; errorCode: string; errorRetryable: boolean; retryAfterMs?: number; resetAt?: string; executionUncertain?: boolean }
   | { status: "stopped"; error?: string; errorCode?: string; errorRetryable?: boolean };
 
 export interface BegunLocalAgentTurn {
@@ -81,6 +99,7 @@ interface LocalAgentRow {
   provider: string;
   model: string | null;
   effort: string | null;
+  write_mode: string;
   provider_session_id: string | null;
   status: string;
   latest_response: string | null;
@@ -100,15 +119,27 @@ interface LocalAgentTurnRow {
   error: string | null;
   error_code: string | null;
   error_retryable: string | null;
+  write_mode: string;
+  model: string | null;
+  effort: string | null;
+  attempt_id: string | null;
+  workflow_run_id: string | null;
+  workflow_step_id: string | null;
+  workflow_attempt_id: string | null;
+  retry_after_ms: number | null;
+  reset_at: string | null;
+  execution_uncertain: string | null;
   created_at: string;
   completed_at: string | null;
 }
 
 export class LocalAgentStore {
   private readonly database: DatabaseHandle;
+  private readonly ownsDatabase: boolean;
 
-  constructor(stateDir: string) {
-    this.database = openDatabase(stateDir);
+  constructor(stateDirOrDatabase: string | DatabaseHandle) {
+    this.database = typeof stateDirOrDatabase === "string" ? openDatabase(stateDirOrDatabase) : stateDirOrDatabase;
+    this.ownsDatabase = typeof stateDirOrDatabase === "string";
   }
 
   list(scope: LocalAgentListScope = {}): LocalAgentRecord[] {
@@ -160,6 +191,7 @@ export class LocalAgentStore {
       provider: input.provider,
       model: input.model,
       effort: input.effort,
+      writeMode: input.writeMode ?? "allowed",
       status: "starting",
       createdAt: now,
       updatedAt: now,
@@ -175,10 +207,11 @@ export class LocalAgentStore {
           provider,
           model,
           effort,
+          write_mode,
           status,
           created_at,
           updated_at
-        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       )
       .run(
         record.id,
@@ -188,6 +221,7 @@ export class LocalAgentStore {
         record.provider,
         record.model ?? null,
         record.effort ?? null,
+        record.writeMode ?? "allowed",
         record.status,
         record.createdAt,
         record.updatedAt,
@@ -242,6 +276,7 @@ export class LocalAgentStore {
           provider = ?,
           model = ?,
           effort = ?,
+          write_mode = ?,
           provider_session_id = ?,
           status = ?,
           latest_response = ?,
@@ -258,6 +293,7 @@ export class LocalAgentStore {
         updated.provider,
         updated.model ?? null,
         updated.effort ?? null,
+        updated.writeMode ?? "allowed",
         updated.providerSessionId ?? null,
         updated.status,
         updated.latestResponse ?? null,
@@ -278,7 +314,11 @@ export class LocalAgentStore {
     return storeResult("update", () => this.update(id, patch));
   }
 
-  beginTurn(agentId: string, input: BeginLocalAgentTurnInput): BegunLocalAgentTurn {
+  beginTurn(
+    agentId: string,
+    input: BeginLocalAgentTurnInput,
+    onPrepared?: (turn: BegunLocalAgentTurn) => void,
+  ): BegunLocalAgentTurn {
     return this.database.sqlite.transaction(() => {
       const current = this.getById(agentId);
       if (!current) throw new Error(`Unknown subagent id: ${agentId}`);
@@ -300,21 +340,42 @@ export class LocalAgentStore {
             agent_id,
             prompt,
             status,
+            write_mode,
+            model,
+            effort,
+            attempt_id,
+            workflow_run_id,
+            workflow_step_id,
+            workflow_attempt_id,
             created_at
-          ) values (?, ?, 'running', ?)`,
+          ) values (?, ?, 'running', ?, ?, ?, ?, ?, ?, ?, ?)`,
         )
-        .run(agentId, input.prompt, agent.updatedAt);
+        .run(
+          agentId,
+          input.prompt,
+          input.writeMode ?? current.writeMode ?? "allowed",
+          input.model ?? current.model ?? null,
+          input.effort ?? current.effort ?? null,
+          input.attemptId ?? null,
+          input.workflowRunId ?? null,
+          input.workflowStepId ?? null,
+          input.workflowAttemptId ?? null,
+          agent.updatedAt,
+        );
       const turn = this.getTurnById(Number(result.lastInsertRowid));
       if (!turn) throw new Error(`Unable to load the new turn for subagent ${agentId}.`);
-      return { agent, turn };
+      const begun = { agent, turn };
+      onPrepared?.(begun);
+      return begun;
     }).immediate();
   }
 
   beginTurnResult(
     agentId: string,
     input: BeginLocalAgentTurnInput,
+    onPrepared?: (turn: BegunLocalAgentTurn) => void,
   ): BetterResult<BegunLocalAgentTurn, AgentStoreError> {
-    return storeResult("begin_turn", () => this.beginTurn(agentId, input));
+    return storeResult("begin_turn", () => this.beginTurn(agentId, input, onPrepared));
   }
 
   finishTurn(
@@ -327,14 +388,12 @@ export class LocalAgentStore {
       if (!turn || turn.agentId !== agentId) {
         throw new Error(`Unknown turn ${turnId} for subagent ${agentId}.`);
       }
-      if (turn.status !== "running") {
-        throw new Error(`Turn ${turnId} for subagent ${agentId} is already ${turn.status}.`);
-      }
       const currentAgent = this.getById(agentId);
       if (!currentAgent) throw new Error(`Unknown subagent id: ${agentId}`);
+      if (turn.status !== "running") return currentAgent;
 
       const completedAt = new Date().toISOString();
-      this.database.sqlite
+      const won = this.database.sqlite
         .prepare(
           `update local_agent_turns set
             status = ?,
@@ -342,8 +401,11 @@ export class LocalAgentStore {
             error = ?,
             error_code = ?,
             error_retryable = ?,
+            retry_after_ms = ?,
+            reset_at = ?,
+            execution_uncertain = ?,
             completed_at = ?
-           where id = ? and agent_id = ?`,
+           where id = ? and agent_id = ? and status = 'running'`,
         )
         .run(
           completion.status,
@@ -353,10 +415,15 @@ export class LocalAgentStore {
           completion.status === "completed" || completion.errorRetryable === undefined
             ? null
             : String(completion.errorRetryable),
+          completion.status === "failed" ? completion.retryAfterMs ?? null : null,
+          completion.status === "failed" ? completion.resetAt ?? null : null,
+          completion.status === "failed" && completion.executionUncertain !== undefined
+            ? String(completion.executionUncertain) : null,
           completedAt,
           turnId,
           agentId,
         );
+      if (won.changes === 0) return requiredAgent(this.getById(agentId), agentId);
 
       if (completion.status === "completed") {
         return this.update(agentId, {
@@ -448,7 +515,7 @@ export class LocalAgentStore {
   }
 
   close(): void {
-    this.database.close();
+    if (this.ownsDatabase) this.database.close();
   }
 
 }
@@ -466,6 +533,7 @@ function rowToLocalAgentRecord(row: LocalAgentRow): LocalAgentRecord {
     provider: row.provider,
     model: row.model ?? undefined,
     effort: row.effort ?? undefined,
+    writeMode: readWriteMode(row.write_mode),
     providerSessionId: row.provider_session_id ?? undefined,
     status: readStatus(row.status),
     latestResponse: row.latest_response ?? undefined,
@@ -477,6 +545,11 @@ function rowToLocalAgentRecord(row: LocalAgentRow): LocalAgentRecord {
   };
 }
 
+function readWriteMode(value: string): PersistedLocalAgentWriteMode {
+  if (value === "allowed" || value === "read_only" || value === "full_access") return value;
+  throw new Error(`Invalid stored local agent write mode: ${value}`);
+}
+
 function rowToLocalAgentTurnRecord(row: LocalAgentTurnRow): LocalAgentTurnRecord {
   return {
     id: row.id,
@@ -487,6 +560,16 @@ function rowToLocalAgentTurnRecord(row: LocalAgentTurnRow): LocalAgentTurnRecord
     error: row.error ?? undefined,
     errorCode: row.error_code ?? undefined,
     errorRetryable: readOptionalBoolean(row.error_retryable),
+    writeMode: readWriteMode(row.write_mode),
+    model: row.model ?? undefined,
+    effort: row.effort ?? undefined,
+    attemptId: row.attempt_id ?? undefined,
+    workflowRunId: row.workflow_run_id ?? undefined,
+    workflowStepId: row.workflow_step_id ?? undefined,
+    workflowAttemptId: row.workflow_attempt_id ?? undefined,
+    retryAfterMs: row.retry_after_ms ?? undefined,
+    resetAt: row.reset_at ?? undefined,
+    executionUncertain: readOptionalBoolean(row.execution_uncertain),
     createdAt: row.created_at,
     completedAt: row.completed_at ?? undefined,
   };
@@ -526,3 +609,8 @@ function readStatus(status: string): LocalAgentStatus {
   }
   return "error";
 }
+
+function requiredAgent(record: LocalAgentRecord | undefined, agentId: string): LocalAgentRecord {
+  if (!record) throw new Error(`Unknown subagent id: ${agentId}`);
+  return record;
+}
diff --git a/src/oauth-store.test.ts b/src/oauth-store.test.ts
index 90a8ade25..5a574d18b 100644
--- a/src/oauth-store.test.ts
+++ b/src/oauth-store.test.ts
@@ -52,6 +52,9 @@ async function testDatabaseConfiguration(stateDir: string): Promise<void> {
       { version: 6, name: "local-agent-effort-rename" },
       { version: 7, name: "workspace-recovery-state" },
       { version: 8, name: "local-agent-turns" },
+      { version: 9, name: "dynamic-workflows" },
+      { version: 10, name: "workflow-agent-authority" },
+      { version: 11, name: "local-agent-retry-metadata" },
     ]);
   } finally {
     database.close();
diff --git a/src/server.test.ts b/src/server.test.ts
index 59bcc5d37..417533de6 100644
--- a/src/server.test.ts
+++ b/src/server.test.ts
@@ -17,6 +17,7 @@ import { ProcessSessionManager } from "./process-sessions.js";
 import { createMcpServer, createServer } from "./server.js";
 import { SqliteWorkspaceStore } from "./workspace-store.js";
 import { WorkspaceRegistry } from "./workspaces.js";
+import { defaultWorkflowsConfig, type WorkflowsConfig } from "./workflow-config.js";
 import { writeTestDevspaceConfig } from "./test-support/config.test.js";
 
 const execFileAsync = promisify(execFile);
@@ -49,6 +50,18 @@ test("tool modes expose the expected host-facing tool surface", async (t) => {
   }
 });
 
+test("enabled workflows are discoverable in both tool modes and can preload instructions", async (t) => {
+  for (const toolMode of ["claude", "codex"] as const) {
+    const context = await fixture(t, { toolMode, uiEnabled: false,
+      workflows: { ...defaultWorkflowsConfig(), enabled: true, instructions: "preload" } });
+    const tools = (await context.client.listTools()).tools;
+    assert.ok(tools.some(({ name }) => name === "run_workflow"));
+    const opened = structuredContent(await callOpen(context.client, context.project, `workflow-${toolMode}`));
+    assert.match(String(opened.instruction), /Dynamic workflow instructions/);
+    assert.match(String(opened.instruction), /parallel/);
+  }
+});
+
 test("model-facing tool schemas use snake_case recursively", async (t) => {
   for (const toolMode of ["claude", "codex"] as const) {
     await t.test(toolMode, async (nested) => {
@@ -720,6 +733,7 @@ async function fixture(
     git?: boolean;
     localAgentProviders?: LocalAgentProviderAvailability[] | (() => LocalAgentProviderAvailability[]);
     subagents?: SubagentsConfig;
+    workflows?: WorkflowsConfig;
     toolMode?: ToolMode;
     uiEnabled?: boolean;
   } = {},
@@ -758,6 +772,7 @@ async function fixture(
     server: { port: 1 },
     workspaces: { allowedRoots: [root], worktreeRoot: join(root, ".worktrees") },
     skills: { agentDir },
+    workflows: options.workflows,
     subagents: {
       enabled: options.localAgentProviders !== undefined,
       instructions: "on-demand",
diff --git a/src/server.ts b/src/server.ts
index 0a2792f3f..fe57b0b83 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -4,6 +4,7 @@ import { access, realpath } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { registerWorkflowTools } from "./workflow-tools.js";
 import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { resourceUrlFromServerUrl } from "@modelcontextprotocol/sdk/shared/auth-utils.js";
@@ -176,6 +177,7 @@ const workspaceAgentsFileOutputSchema = z.object({
 });
 
 const workspaceLocalAgentOutputSchema = z.object({
+  write_mode: z.enum(["read_only", "allowed", "full_access"]).optional(),
   name: z.string(),
   description: z.string(),
   provider: z.string(),
@@ -461,9 +463,14 @@ function registerMcpSurface(
       const preloadedSubagentInstructions = preloadSubagents && subagentsSkill
         ? readFileSync(subagentsSkill.filePath, "utf8")
         : undefined;
+      const preloadWorkflows = config.workflows?.enabled && config.workflows.instructions === "preload";
+      const workflowsSkill = workspace.skills.find((skill) => skill.name === "workflows");
+      const preloadedWorkflowInstructions = preloadWorkflows && workflowsSkill
+        ? readFileSync(workflowsSkill.filePath, "utf8") : undefined;
       const cardSkills = workspace.skills
         .filter((skill) => !skill.disableModelInvocation)
         .filter((skill) => !(preloadSubagents && skill.name === "subagents"))
+        .filter((skill) => !(preloadWorkflows && skill.name === "workflows"))
         .map((skill) => ({
           name: skill.name,
           description: skill.description,
@@ -482,7 +489,9 @@ function registerMcpSurface(
           effort: provider.effort,
           note: provider.note,
         }));
-      const cardAgents = agentCatalog.profiles;
+      const cardAgents = agentCatalog.profiles.map(({ writeMode, ...profile }) => ({
+        ...profile, ...(writeMode ? { write_mode: writeMode } : {}),
+      }));
       const cardAgentsFiles = agentsFiles.map((file) => ({
         path: formatAgentsPath(file.path, workspace.root),
         content: file.content,
@@ -507,13 +516,12 @@ function registerMcpSurface(
         : workspace.mode === "worktree"
           ? "Use this workspace_id for subsequent work in this isolated worktree. Keep reusing it while working in this worktree. Follow the project instructions, nested instruction files, skills, agent profiles, and diagnostics returned for it."
           : cardInstruction;
-      const instruction = preloadedSubagentInstructions && includeBootstrapContext
-        ? [
-            workspaceInstruction,
-            "Subagent workflow instructions:",
-            preloadedSubagentInstructions,
-          ].join("\n\n")
-        : workspaceInstruction;
+      const instruction = [workspaceInstruction,
+        ...(includeBootstrapContext && preloadedSubagentInstructions
+          ? ["Subagent workflow instructions:", preloadedSubagentInstructions] : []),
+        ...(includeBootstrapContext && preloadedWorkflowInstructions
+          ? ["Dynamic workflow instructions:", preloadedWorkflowInstructions] : []),
+      ].join("\n\n");
       const resultContent: ToolContent[] = [
         {
           type: "text" as const,
@@ -697,6 +705,8 @@ function registerMcpSurface(
     processSessions,
   });
 
+  registerWorkflowTools({ server: registrationTarget, config, workspaces });
+
   registerAppTool(
     registrationTarget,
     "show_changes",
diff --git a/src/skills.ts b/src/skills.ts
index 8f67d8e07..b5c6bb808 100644
--- a/src/skills.ts
+++ b/src/skills.ts
@@ -29,20 +29,15 @@ export interface SkillReadResolution {
   skill: Skill;
 }
 
-const SUBAGENTS_SKILL_NAME = "subagents";
-const SUBAGENTS_SKILL = join(SUBAGENTS_SKILL_NAME, "SKILL.md");
+const MANAGED_SKILLS = ["subagents", "workflows"] as const;
 
 function bundledSkillsDir(): string {
   return fileURLToPath(new URL("../skills", import.meta.url));
 }
 
-function bundledSubagentsSkillPath(): string {
-  return join(bundledSkillsDir(), SUBAGENTS_SKILL);
-}
-
-function syncManagedSubagentsSkill(config: ServerConfig): string {
-  const sourcePath = bundledSubagentsSkillPath();
-  const targetPath = join(config.devspaceSkillsDir, SUBAGENTS_SKILL);
+function syncManagedSkill(config: ServerConfig, name: string): string {
+  const sourcePath = join(bundledSkillsDir(), name, "SKILL.md");
+  const targetPath = join(config.devspaceSkillsDir, name, "SKILL.md");
   const source = readFileSync(sourcePath, "utf8");
 
   if (existsSync(targetPath)) {
@@ -51,7 +46,7 @@ function syncManagedSubagentsSkill(config: ServerConfig): string {
       return targetPath;
     }
     if (stat.isDirectory()) {
-      throw new Error(`Managed subagents skill path is a directory: ${targetPath}`);
+      throw new Error(`Managed ${name} skill path is a directory: ${targetPath}`);
     }
   }
 
@@ -96,42 +91,24 @@ function resolveSkillPath(path: string, cwd: string): string {
 export function loadWorkspaceSkills(config: ServerConfig, cwd: string): LoadedSkills {
   if (!config.skillsEnabled) return { skills: [], diagnostics: [] };
 
-  if (config.subagents.enabled) {
-    syncManagedSubagentsSkill(config);
-  }
-
+  const enabled = MANAGED_SKILLS.filter((name) => name === "subagents"
+    ? config.subagents.enabled : config.workflows?.enabled);
+  for (const name of enabled) syncManagedSkill(config, name);
   const result = loadSkills({
-    cwd,
-    agentDir: config.agentDir,
-    skillPaths: effectiveSkillPaths(config, cwd),
-    includeDefaults: false,
+    cwd, agentDir: config.agentDir,
+    skillPaths: effectiveSkillPaths(config, cwd), includeDefaults: false,
+  });
+  const managedNames = new Set<string>(MANAGED_SKILLS);
+  const managed = enabled.map((name) => {
+    const skill = loadSkillsFromDir({ dir: join(config.devspaceSkillsDir, name), source: "devspace" })
+      .skills.find((skill) => skill.name === name);
+    if (!skill) throw new Error(`Managed ${name} skill could not be loaded.`);
+    return skill;
   });
-
-  const withoutSubagents = withoutSubagentsSkill(result);
-  if (!config.subagents.enabled) return withoutSubagents;
-
-  const managedDir = dirname(join(config.devspaceSkillsDir, SUBAGENTS_SKILL));
-  const managed = loadSkillsFromDir({
-    dir: managedDir,
-    source: "devspace",
-  }).skills.find((skill) => skill.name === SUBAGENTS_SKILL_NAME);
-  if (!managed) {
-    throw new Error("Managed subagents skill could not be loaded.");
-  }
-
-  return {
-    skills: [...withoutSubagents.skills, managed],
-    diagnostics: withoutSubagents.diagnostics,
-  };
-}
-
-function withoutSubagentsSkill(result: LoadSkillsResult): LoadedSkills {
   return {
-    skills: result.skills.filter((skill) => skill.name !== SUBAGENTS_SKILL_NAME),
-    diagnostics: result.diagnostics.filter((diagnostic) => {
-      const collision = diagnostic.collision;
-      return !(collision?.resourceType === "skill" && collision.name === SUBAGENTS_SKILL_NAME);
-    }),
+    skills: [...result.skills.filter((skill) => !managedNames.has(skill.name)), ...managed],
+    diagnostics: result.diagnostics.filter(({ collision }) =>
+      !(collision?.resourceType === "skill" && managedNames.has(collision.name))),
   };
 }
 
diff --git a/src/test-support/config.test.ts b/src/test-support/config.test.ts
index 2c97bc4e8..44d731628 100644
--- a/src/test-support/config.test.ts
+++ b/src/test-support/config.test.ts
@@ -13,6 +13,7 @@ type SectionOverrides = {
   artifacts?: Partial<DevspaceConfig["artifacts"]>;
   skills?: Partial<DevspaceConfig["skills"]>;
   subagents?: DevspaceConfig["subagents"];
+  workflows?: DevspaceConfig["workflows"];
   logging?: Partial<DevspaceConfig["logging"]>;
   oauth?: Partial<DevspaceConfig["oauth"]>;
 };
@@ -33,6 +34,7 @@ export function writeTestDevspaceConfig(
     artifacts: { ...defaults.artifacts, ...overrides.artifacts },
     skills: { ...defaults.skills, ...overrides.skills },
     subagents: overrides.subagents ?? defaults.subagents,
+    workflows: overrides.workflows ?? defaults.workflows,
     logging: { ...defaults.logging, ...overrides.logging },
     oauth: { ...defaults.oauth, ...overrides.oauth },
   }, env);
diff --git a/src/workflow-cli.ts b/src/workflow-cli.ts
new file mode 100644
index 000000000..c1a3e577e
--- /dev/null
+++ b/src/workflow-cli.ts
@@ -0,0 +1,133 @@
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { loadConfig } from "./config.js";
+import { resolveCliWorkspaceContext } from "./cli-workspace.js";
+import { createLocalAgentClient } from "./local-agent-client.js";
+import { SqliteWorkspaceStore } from "./workspace-store.js";
+import { WorkspaceRegistry } from "./workspaces.js";
+import { decodeWorkflowRequest, type WorkflowOperation } from "./workflow-protocol.js";
+
+export const WORKFLOW_CLI_HELP = [
+  "devspace workflows run <script.js> [--args-file input.json] [--agent <profile-or-provider>]",
+  "devspace workflows run --name <saved-name> [--args-file input.json]",
+  "devspace workflows run <script.js> --resume-from <run-id>",
+  "devspace workflows show <run-id> [--step <step-id>] [--after-revision <revision>]",
+  "devspace workflows wait <run-id> [--timeout <seconds>] [--after-revision <revision>]",
+  "devspace workflows <pause|resume|stop> <run-id>",
+  "devspace workflows <stop-agent|restart-agent> <run-id> --step <step-id>",
+  "devspace workflows ls [--definitions] [--cursor <cursor>] [--limit <count>]",
+  "devspace workflows save <run-id> --name <name> [--location project|user] [--replace]",
+  "Run options: --model <model> --effort <effort> --budget <output-tokens>",
+  "All commands accept --json. Script path '-' reads source from stdin.",
+].join("\n");
+
+export function parseWorkflowCli(args: string[]): { operation: WorkflowOperation; input: Record<string, unknown>; json: boolean } {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+    json: { type: "boolean" }, name: { type: "string" }, "args-file": { type: "string" },
+    agent: { type: "string" }, model: { type: "string" }, effort: { type: "string" },
+    budget: { type: "string" }, "resume-from": { type: "string" }, step: { type: "string" },
+    timeout: { type: "string" }, "after-revision": { type: "string" },
+    cursor: { type: "string" }, limit: { type: "string" },
+    definitions: { type: "boolean" }, location: { type: "string" }, replace: { type: "boolean" },
+  } });
+  const [command, target, ...extra] = positionals;
+  if (extra.length) throw new Error("Unexpected workflow arguments.\n" + WORKFLOW_CLI_HELP);
+  const flags: Record<string, string[]> = {
+    run: ["name", "args-file", "agent", "model", "effort", "budget", "resume-from"],
+    show: ["step", "after-revision"], wait: ["timeout", "after-revision"], pause: [], resume: [], stop: [],
+    "stop-agent": ["step"], "restart-agent": ["step"], ls: ["definitions", "cursor", "limit"],
+    save: ["name", "location", "replace"],
+  };
+  for (const key of Object.keys(values)) {
+    if (key !== "json" && !flags[command ?? ""]?.includes(key)) {
+      throw new Error(`--${key} is not valid for workflows ${command ?? ""}.`);
+    }
+  }
+  const number = (value: string | undefined) => value === undefined ? undefined : Number(value);
+  let operation: WorkflowOperation;
+  let input: Record<string, unknown>;
+  switch (command) {
+    case "run":
+      operation = "run";
+      input = { scriptPath: target, name: values.name, agentType: values.agent, model: values.model,
+        effort: values.effort, outputTokenBudget: number(values.budget), resumeFromRunId: values["resume-from"] };
+      break;
+    case "show":
+      operation = "get"; input = { runId: target, stepId: values.step, afterRevision: number(values["after-revision"]) }; break;
+    case "wait":
+      operation = "wait"; input = { runId: target, timeoutMs: values.timeout === undefined ? undefined : Number(values.timeout) * 1000,
+        afterRevision: number(values["after-revision"]) }; break;
+    case "pause": case "resume": case "stop": case "stop-agent": case "restart-agent":
+      operation = "control"; input = { runId: target, action: command.replaceAll("-", "_"), stepId: values.step }; break;
+    case "ls":
+      if (target) throw new Error("workflows ls does not accept a run ID.");
+      operation = "list"; input = { kind: values.definitions ? "definitions" : "runs", cursor: values.cursor, limit: number(values.limit) }; break;
+    case "save":
+      operation = "save"; input = { runId: target, name: values.name, location: values.location ?? "project", replace: values.replace }; break;
+    default: throw new Error(WORKFLOW_CLI_HELP);
+  }
+  if (values["args-file"] !== undefined) {
+    if (operation !== "run") throw new Error("--args-file is only valid for workflows run.");
+    input.argsFile = values["args-file"];
+  }
+  return { operation, input: Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined)), json: values.json ?? false };
+}
+
+export async function runWorkflowsCommand(args: string[]): Promise<void> {
+  try { await executeWorkflowsCommand(args); }
+  catch (error) {
+    if (!args.includes("--json")) throw error;
+    console.error(JSON.stringify({ error: {
+      code: "WORKFLOW_COMMAND_ERROR", message: error instanceof Error ? error.message : String(error), retryable: false,
+    } }));
+    process.exitCode = 1;
+  }
+}
+
+async function executeWorkflowsCommand(args: string[]): Promise<void> {
+  if (args.length === 0 || args.includes("--help") || args[0] === "help") {
+    console.log(WORKFLOW_CLI_HELP);
+    return;
+  }
+  const parsed = parseWorkflowCli(args);
+  if (process.env.DEVSPACE_WORKFLOW_RUN_ID && (parsed.operation === "run" || parsed.operation === "control")) {
+    throw new Error("Workflow workers cannot launch or control workflows through the CLI. Return the task to the owning workflow.");
+  }
+  const input = parsed.input;
+  if (input.argsFile !== undefined) {
+    const path = String(input.argsFile);
+    if (path === "-" && input.scriptPath === "-") throw new Error("Script and arguments cannot both read stdin.");
+    input.args = JSON.parse(path === "-" ? await readStdin() : await readFile(path, "utf8"));
+    delete input.argsFile;
+  }
+  if (input.scriptPath === "-") { input.script = await readStdin(); delete input.scriptPath; }
+  const config = loadConfig();
+  const current = resolveCliWorkspaceContext(config.allowedRoots);
+  const store = new SqliteWorkspaceStore(config.stateDir);
+  try {
+    const registry = new WorkspaceRegistry(config, store);
+    const workspace = current.workspaceId
+      ? await registry.getWorkspace(current.workspaceId)
+      : (await registry.openWorkspace({ path: current.workspaceRoot }, {
+          conversationScopeId: `local-workflow-cli:${current.workspaceRoot}`,
+        })).workspace;
+    const request = decodeWorkflowRequest({ operation: parsed.operation, input,
+      scope: { workspaceId: workspace.id, workspaceRoot: workspace.root } });
+    const result = await createLocalAgentClient(config).workflow(request);
+    if (!result.ok) {
+      console.error(JSON.stringify(result.error, null, parsed.json ? undefined : 2));
+      process.exitCode = 1;
+      return;
+    }
+    console.log(JSON.stringify(result.result, null, parsed.json ? undefined : 2));
+  } finally { store.close(); }
+}
+
+async function readStdin(): Promise<string> {
+  let result = "";
+  for await (const chunk of process.stdin) {
+    result += chunk.toString();
+    if (Buffer.byteLength(result) > 1024 * 1024) throw new Error("Workflow stdin exceeds 1 MiB.");
+  }
+  return result;
+}
diff --git a/src/workflow-config.ts b/src/workflow-config.ts
new file mode 100644
index 000000000..65b75c33b
--- /dev/null
+++ b/src/workflow-config.ts
@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import * as z from "zod/v4";
+import { localAgentProviderConfigRevision, type SubagentsConfig } from "./local-agent-config.js";
+
+const positive = (fallback: number, maximum = 2_147_483_647) =>
+  z.number().int().positive().max(maximum).default(fallback);
+
+export const workflowsConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  instructions: z.enum(["on-demand", "preload"]).default("on-demand"),
+  defaultAgentType: z.string().trim().min(1).optional(),
+  packageRoots: z.array(z.string().trim().min(1)).max(100).default([]),
+  maxConcurrentAgents: positive(16, 256),
+  maxConcurrentRuns: positive(4, 32),
+  maxAgentsPerRun: positive(1_000, 10_000),
+  maxAttemptsPerRun: positive(5_000, 50_000),
+  defaultOutputTokenBudget: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+  maxOutputTokenBudget: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+  requireWorktreesForConcurrentWrites: z.boolean().default(false),
+  maxUsageLimitWaits: z.number().int().min(0).max(10).default(2),
+  maxUsageLimitWaitMs: positive(86_400_000, 86_400_000),
+  limits: z.object({
+    scriptBytes: positive(256 * 1024),
+    argsBytes: positive(1024 * 1024),
+    promptBytes: positive(1024 * 1024),
+    schemaBytes: positive(128 * 1024),
+    schemaDepth: positive(64, 256),
+    agentResultBytes: positive(4 * 1024 * 1024),
+    runResultBytes: positive(16 * 1024 * 1024),
+    guestHeapBytes: positive(64 * 1024 * 1024),
+    guestStackBytes: positive(1024 * 1024),
+    guestSliceMs: positive(1_000),
+    guestTotalCpuMs: positive(30_000),
+    runActiveMs: positive(6 * 60 * 60 * 1_000),
+    logMessageBytes: positive(8 * 1024),
+    logTotalBytes: positive(1024 * 1024),
+    eventsPerRun: positive(100_000),
+  }).strict().prefault({}),
+}).strict().prefault({});
+
+export type WorkflowsConfig = z.output<typeof workflowsConfigSchema>;
+export const defaultWorkflowsConfig = (): WorkflowsConfig => workflowsConfigSchema.parse({});
+
+/** Workflow policy changes must not reuse a daemon with stale execution authority. */
+export function executionConfigRevision(config: { subagents: SubagentsConfig; workflows?: WorkflowsConfig; allowedRoots?: readonly string[]; worktreeRoot?: string }): string {
+  const agents = localAgentProviderConfigRevision(config.subagents);
+  if (!config.workflows) return agents;
+  return createHash("sha256").update(JSON.stringify([agents, config.workflows, config.allowedRoots, config.worktreeRoot])).digest("hex");
+}
diff --git a/src/workflow-daemon.test.ts b/src/workflow-daemon.test.ts
new file mode 100644
index 000000000..220f2f668
--- /dev/null
+++ b/src/workflow-daemon.test.ts
@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { LocalAgentClient } from "./local-agent-client.js";
+import { LocalAgentDaemon, type LocalAgentDaemonManager } from "./local-agent-daemon.js";
+import type { WorkflowReply } from "./workflow-protocol.js";
+
+test("workflow daemon transport preserves active runs and allows observation after config changes", async (t) => {
+  const stateDir = await mkdtemp(join(tmpdir(), "devspace-workflow-daemon-"));
+  let activeRuns = 1;
+  let closed = false;
+  const manager = {
+    activeTurnCount: 0, runtimeCount: 0, evictIdle: async () => {}, close: async () => {},
+  } as LocalAgentDaemonManager;
+  const daemon = new LocalAgentDaemon({ stateDir, configRevision: "old", manager, idleShutdownMs: 60_000,
+    workflows: {
+      get activeRunCount() { return activeRuns; },
+      request: async ({ operation }): Promise<WorkflowReply> => {
+        if (operation === "control") { activeRuns = 0; return { ok: true, result: { status: "stopped" } }; }
+        return { ok: true, result: { status: "running", runId: "r" } };
+      },
+      close: async () => { closed = true; },
+    },
+  });
+  t.after(async () => { await daemon.close(); await rm(stateDir, { recursive: true, force: true }); });
+  await daemon.start();
+  let spawned = false;
+  const changedConfig = new LocalAgentClient({ stateDir, configRevision: "new", requestTimeoutMs: 1000,
+    spawnDaemon: () => { spawned = true; } });
+  const scope = { workspaceId: "w", workspaceRoot: stateDir };
+  const running = await changedConfig.workflow({ operation: "get", scope, input: { runId: "r" } });
+  assert.equal(running.ok, true, JSON.stringify(running));
+  assert.equal(spawned, false);
+  const launch = await changedConfig.workflow({ operation: "run", scope, input: { script: "source" } });
+  assert.equal(launch.ok, false, "a changed configuration must not replace a daemon with active workflows");
+  assert.equal(spawned, false);
+  assert.equal(closed, false);
+  const stopped = await changedConfig.workflow({ operation: "control", scope, input: { runId: "r", action: "stop" } });
+  assert.equal(stopped.ok, true);
+  assert.equal(activeRuns, 0);
+});
diff --git a/src/workflow-manager.test.ts b/src/workflow-manager.test.ts
new file mode 100644
index 000000000..f6acd01f0
--- /dev/null
+++ b/src/workflow-manager.test.ts
@@ -0,0 +1,464 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { Result, type Result as BetterResult } from "better-result";
+import { defaultWorkflowsConfig } from "./workflow-config.js";
+import { openDatabase } from "./db/client.js";
+import { LocalAgentManager } from "./local-agent-manager.js";
+import { AgentProviderCancelledError, AgentProviderExecutionError, type AgentProviderError } from "./local-agent-errors.js";
+import type { LocalAgentProfile } from "./local-agent-profiles.js";
+import type {
+  LocalAgentCapabilities,
+  LocalAgentDriver,
+  LocalAgentRunCallbacks,
+  LocalAgentRunControl,
+  LocalAgentRunInput,
+  LocalAgentRunResult,
+  LocalAgentRuntime,
+} from "./local-agent-runtime.js";
+import { LocalAgentRuntimePool } from "./local-agent-runtime-pool.js";
+import { LocalAgentStore } from "./local-agent-store.js";
+import type { SubagentsConfig } from "./local-agent-config.js";
+import { createWorkflowManager } from "./workflow-manager.js";
+import type { WorkflowReply, WorkflowRequest, WorkflowScope } from "./workflow-protocol.js";
+import { WorkflowStore } from "./workflow-store.js";
+
+const root = await mkdtemp(join(tmpdir(), "devspace-workflow-manager-"));
+const stateDir = join(root, "state");
+const scope: WorkflowScope = { workspaceId: "ws_test", workspaceRoot: root };
+const database = openDatabase(stateDir);
+const agentStore = new LocalAgentStore(database);
+const calls: LocalAgentRunInput[] = [];
+const promptCalls = new Map<string, number>();
+const capabilities: LocalAgentCapabilities = {
+  cancellation: "turn", structuredOutput: "validated_text", usage: "final",
+  correctionAuthority: "no_tools", permissionRequests: "preconfigured", progress: "text",
+};
+
+class FakeRuntime implements LocalAgentRuntime {
+  readonly provider = "codex" as const;
+  async run(
+    input: LocalAgentRunInput,
+    callbacks?: LocalAgentRunCallbacks,
+    control?: LocalAgentRunControl,
+  ): Promise<BetterResult<LocalAgentRunResult, AgentProviderError>> {
+    calls.push(input);
+    promptCalls.set(input.prompt, (promptCalls.get(input.prompt) ?? 0) + 1);
+    if (control?.signal.aborted) throw control.signal.reason;
+    if (input.prompt === "hold" || input.prompt === "hold-stop" || input.prompt.startsWith("hold-failure-")
+      || (input.prompt === "hold-restart" && promptCalls.get(input.prompt) === 1)) {
+      await new Promise<void>((resolveAbort) => control?.signal.addEventListener("abort", () => resolveAbort(), { once: true }));
+      return Result.err(new AgentProviderCancelledError({ code: "PROVIDER_CANCELLED", provider: "codex",
+        operation: "run", retryable: false, message: "cancelled" }));
+    }
+    if (input.prompt === "rate-once" && promptCalls.get(input.prompt) === 1) {
+      return Result.err(new AgentProviderExecutionError({ code: "PROVIDER_EXECUTION_ERROR", provider: "codex",
+        operation: "run", retryable: true, message: "limited", retryAfterMs: 500, executionUncertain: false }));
+    }
+    if (input.prompt === "slow" || input.prompt === "slow-restart") await delay(30);
+    await callbacks?.onSessionId?.(`session_${input.attemptId}`);
+    await callbacks?.onProgress?.({ type: "text", text: "working" });
+    const finalResponse = input.prompt.startsWith("Return only corrected JSON")
+      ? JSON.stringify({ ok: true })
+      : input.outputSchema ? "not json" : input.prompt === "large-output" ? "x".repeat(70_000)
+        : input.prompt === "slow-restart"
+        ? `done:${input.prompt}:${promptCalls.get(input.prompt)}` : `done:${input.prompt}`;
+    await callbacks?.onUsage?.({ attemptId: input.attemptId!, sequence: 1, outputTokens: 3, final: true });
+    return Result.ok({ provider: "codex", providerSessionId: `session_${input.attemptId}`,
+      finalResponse, items: [], usage: { attemptId: input.attemptId!, sequence: 1, outputTokens: 3, final: true } });
+  }
+  releaseSession(): Promise<void> { return Promise.resolve(); }
+  close(): Promise<void> { return Promise.resolve(); }
+  isAlive(): boolean { return true; }
+}
+
+const driver: LocalAgentDriver = {
+  provider: "codex",
+  runtimeKey: ({ agentId }) => agentId,
+  createRuntime: async () => Result.ok(new FakeRuntime()),
+  capabilities: () => capabilities,
+};
+const profile: LocalAgentProfile = {
+  name: "reviewer", description: "Reviewer", provider: "codex",
+  filePath: join(root, "reviewer.md"), body: "", disabled: false, writeMode: "read_only",
+};
+const subagents: SubagentsConfig = {
+  enabled: true, instructions: "on-demand", providers: [{ id: "codex", enabled: true }],
+};
+const agents = new LocalAgentManager({
+  store: agentStore, drivers: [driver], pool: new LocalAgentRuntimePool(),
+  loadProfiles: async () => [profile], subagents,
+  validateWorkspaceScope: ({ workspaceRoot }) => workspaceRoot,
+});
+const workflowStore = new WorkflowStore(database);
+let worktrees = 0;
+const workflowsConfig = { ...defaultWorkflowsConfig(), enabled: true, defaultAgentType: "reviewer", maxConcurrentRuns: 1 };
+const manager = createWorkflowManager({
+  stateDir, agents, agentStore, store: workflowStore,
+  config: workflowsConfig,
+  validateScope: async (candidate) => {
+    assert.deepEqual(candidate, scope);
+    return candidate;
+  },
+  createWorktree: async () => ({
+    workspaceId: `ws_worktree_${++worktrees}`, workspaceRoot: root, baseSha: "abc123",
+  }),
+  inspectWorktree: async () => ({ changed: true }),
+});
+
+try {
+  const invalidGrammar = await manager.request({ operation: "run", scope, input: { script: `
+export const meta = { name: 'invalid-grammar', description: 'QuickJS grammar preflight' }
+using value = null
+return value` } });
+  assert.equal(invalidGrammar.ok, false);
+  if (!invalidGrammar.ok) assert.equal(invalidGrammar.error.code, "WORKFLOW_SYNTAX_ERROR");
+  assert.equal(workflowStore.listRuns(scope.workspaceId, 10).length, 0,
+    "QuickJS grammar failures reject before a durable run is created");
+
+  const first = await run(`
+export const meta = { name: 'structured', description: 'Structured retry' }
+return await agent('inspect', { schema: {
+  type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'], additionalProperties: false,
+} })`);
+  const firstSnapshot = await terminal(first.runId);
+  assert.equal(firstSnapshot.state, "completed", JSON.stringify(firstSnapshot));
+  assert.deepEqual(firstSnapshot.result, { ok: true });
+  assert.equal(firstSnapshot.usage.knownOutputTokens, 6);
+  const firstSteps = workflowStore.listSteps(first.runId);
+  assert.equal(firstSteps.length, 1);
+  assert.equal(workflowStore.listAttempts(firstSteps[0]!.id).length, 2);
+  assert(firstSteps[0]!.deliverySequence);
+  const exportDir = join(root, ".devspace", "workflows", "runs", first.runId);
+  assert.equal(JSON.parse(await readFile(join(exportDir, "result.json"), "utf8")).ok, true);
+  assert.match(await readFile(join(exportDir, "journal.jsonl"), "utf8"), /"type":"run_state"/);
+
+  const callCount = calls.length;
+  const resumed = await run(`
+export const meta = { name: 'structured', description: 'Structured retry' }
+const value = await agent('inspect', { schema: {
+  type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'], additionalProperties: false,
+} })
+return { value }`, { resumeFromRunId: first.runId });
+  const resumedSnapshot = await terminal(resumed.runId);
+  assert.equal(resumedSnapshot.state, "completed");
+  assert.deepEqual(resumedSnapshot.result, { value: { ok: true } });
+  assert.equal(calls.length, callCount, "matching replay does not dispatch a provider turn");
+  assert.equal(workflowStore.listSteps(resumed.runId)[0]?.state, "cached");
+
+  const logged = await run(`
+export const meta = { name: 'logged', description: 'Replay logs' }
+phase('Review')
+log('same log')
+return await agent('logged')`);
+  assert.equal((await terminal(logged.runId)).result, "done:logged");
+  const loggedCallCount = calls.length;
+  const loggedReplay = await run(`
+export const meta = { name: 'logged', description: 'Replay logs' }
+phase('Review')
+log('same log')
+return await agent('logged')`, { resumeFromRunId: logged.runId });
+  const loggedReplaySnapshot = await terminal(loggedReplay.runId);
+  assert.equal(loggedReplaySnapshot.resumedFromRunId, logged.runId);
+  assert.equal(loggedReplaySnapshot.events.some((event: any) => event.type === "log" || event.type === "phase"), false,
+    "matching replay events link to the source run instead of duplicating user-visible logs");
+  assert.equal(calls.length, loggedCallCount);
+  const changedLog = await run(`
+export const meta = { name: 'logged', description: 'Replay logs' }
+phase('Review')
+log('new log')
+return await agent('logged')`, { resumeFromRunId: loggedReplay.runId });
+  assert.equal((await terminal(changedLog.runId)).state, "completed");
+  assert.equal(workflowStore.listEvents(changedLog.runId).some((event) =>
+    event.type === "log" && event.payload.message === "new log"), true);
+  assert.equal(calls.length, loggedCallCount + 1, "a new replay log establishes the live boundary");
+
+  const observedBudget = await run(`
+export const meta = { name: 'budgeted', description: 'Budget observations' }
+const before = budget.spent()
+await agent('budgeted')
+return [before, budget.spent()]`);
+  assert.deepEqual((await terminal(observedBudget.runId)).result, [0, 3]);
+  const budgetCallCount = calls.length;
+  const editedBudget = await run(`
+export const meta = { name: 'budgeted', description: 'Budget observations' }
+await agent('budgeted')
+return budget.spent()`, { resumeFromRunId: observedBudget.runId });
+  assert.equal((await terminal(editedBudget.runId)).result, 3,
+    "removing an earlier getter diverges to the current budget instead of shifting old observations");
+  assert.equal(calls.length, budgetCallCount, "budget-observation divergence can still reuse the preceding matching call");
+
+  const raced = await run(`
+export const meta = { name: 'race', description: 'Replay delivery order' }
+return await parallel([() => agent('slow'), () => agent('fast')])`);
+  assert.deepEqual((await terminal(raced.runId)).result, ["done:slow", "done:fast"]);
+  const racedCallCount = calls.length;
+  const diverged = await run(`
+export const meta = { name: 'race', description: 'Replay delivery order' }
+return await parallel([() => agent('slow'), () => agent('changed')])`, { resumeFromRunId: raced.runId });
+  assert.deepEqual((await terminal(diverged.runId)).result, ["done:slow", "done:changed"]);
+  assert.equal(calls.length, racedCallCount + 1, "a missing recorded delivery switches to live without hanging cached siblings");
+
+  const promiseRace = await run(`
+export const meta = { name: 'promise-race', description: 'Promise race replay' }
+return await Promise.race([agent('slow'), agent('fast')])`);
+  const promiseRaceWinner = (await terminal(promiseRace.runId)).result;
+  assert(["done:slow", "done:fast"].includes(promiseRaceWinner));
+  const promiseRaceCallCount = calls.length;
+  const promiseRaceReplay = await run(`
+export const meta = { name: 'promise-race', description: 'Promise race replay' }
+return await Promise.race([agent('slow'), agent('fast')])`, { resumeFromRunId: promiseRace.runId });
+  assert.equal((await terminal(promiseRaceReplay.runId)).result, promiseRaceWinner,
+    "cached promises are released in their recorded delivery order");
+  assert.equal(calls.length, promiseRaceCallCount, "promise race replay does not dispatch providers");
+
+  const definitions = join(root, ".devspace", "workflows");
+  await mkdir(definitions, { recursive: true });
+  await writeFile(join(definitions, "child.js"), `
+export const meta = { name: 'child', description: 'Nested child' }
+return await agent('nested')`);
+  const nested = await run(`
+export const meta = { name: 'parent', description: 'Nested parent' }
+return await workflow('child')`);
+  const nestedSnapshot = await terminal(nested.runId);
+  assert.equal(nestedSnapshot.state, "completed", JSON.stringify(nestedSnapshot));
+  assert.equal(nestedSnapshot.result, "done:nested");
+  const nestedSteps = workflowStore.listSteps(nested.runId);
+  assert.deepEqual(nestedSteps.map((step) => step.kind), ["workflow", "agent"]);
+  assert.equal(new Set(nestedSteps.map((step) => step.deliverySequence)).size, 2,
+    "nested and root deliveries share one sequence");
+  const nestedCallCount = calls.length;
+  const nestedReplay = await run(`
+export const meta = { name: 'parent', description: 'Nested parent' }
+return await workflow('child')`, { resumeFromRunId: nested.runId });
+  assert.equal((await terminal(nestedReplay.runId)).result, "done:nested");
+  assert.equal(calls.length, nestedCallCount, "nested replay executes the child body but reuses matching internal calls");
+
+  await writeFile(join(definitions, "queued-child.js"), `
+export const meta = { name: 'queued-child', description: 'Nested queue child' }
+return await agent(args.prompt)`);
+  const nestedQueueCallCount = calls.length;
+  const queuedNested = await run(`
+export const meta = { name: 'queued-parent', description: 'Nested queue parent' }
+return await parallel([
+  () => workflow('queued-child', { prompt: 'hold' }),
+  () => workflow('queued-child', { prompt: 'hold' }),
+])`);
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const steps = workflowStore.listSteps(queuedNested.runId);
+    if (steps.filter((step) => step.kind === "workflow").length === 2
+      && steps.some((step) => step.kind === "agent" && step.state === "running")) break;
+    await delay(5);
+  }
+  assert.equal(calls.length, nestedQueueCallCount + 1, "only the child holding the nested slot dispatches an agent");
+  const queuedStop = await manager.request({ operation: "control", scope,
+    input: { runId: queuedNested.runId, action: "stop" } });
+  assert.equal(queuedStop.ok, true);
+  assert.equal((await terminal(queuedNested.runId)).state, "stopped");
+  assert.equal(calls.length, nestedQueueCallCount + 1, "an aborted queued child never starts after the slot is released");
+
+  const isolated = await run(`
+export const meta = { name: 'isolated', description: 'Isolated agent' }
+return await agent('isolated', { isolation: 'worktree' })`);
+  assert.equal((await terminal(isolated.runId)).state, "completed");
+  assert.equal(worktrees, 1);
+  assert.equal(workflowStore.listSteps(isolated.runId)[0]?.worktree?.baseSha, "abc123");
+  assert.equal(workflowStore.listSteps(isolated.runId)[0]?.worktree?.changed, true);
+  assert.equal((await terminal(isolated.runId)).worktrees[0].changed, true);
+
+  const large = await run(`
+export const meta = { name: 'large', description: 'Artifact-backed result' }
+return await agent('large-output')`);
+  const largeSnapshot = await terminal(large.runId);
+  assert.equal(largeSnapshot.result, undefined);
+  assert.match(largeSnapshot.resultPreview, /truncated/);
+  assert.equal(JSON.parse(await readFile(largeSnapshot.resultArtifact.path, "utf8")).length, 70_000);
+  const largeStep = workflowStore.listSteps(large.runId)[0]!;
+  const largeDetail = success(await manager.request({ operation: "get", scope,
+    input: { runId: large.runId, stepId: largeStep.id } })) as any;
+  assert.equal(largeDetail.output, undefined);
+  assert.equal(JSON.parse(await readFile(largeDetail.outputArtifact.path, "utf8")).length, 70_000);
+
+  const restarted = await run(`
+export const meta = { name: 'restarted', description: 'Restarted agent' }
+return await agent('hold-restart')`);
+  for (let attempt = 0; attempt < 100 && workflowStore.listSteps(restarted.runId)[0]?.state !== "running"; attempt++) {
+    await delay(5);
+  }
+  const restartStep = workflowStore.listSteps(restarted.runId)[0]!;
+  const restartReply = await manager.request({ operation: "control", scope,
+    input: { runId: restarted.runId, action: "restart_agent", stepId: restartStep.id } });
+  assert.equal(restartReply.ok, true);
+  assert.equal((await terminal(restarted.runId)).result, "done:hold-restart");
+  assert.equal(workflowStore.listAttempts(restartStep.id).length, 2);
+
+  const paused = await run(`
+export const meta = { name: 'paused', description: 'Paused scheduling' }
+const first = await agent('slow')
+return [first, await agent('after-pause')]`);
+  for (let attempt = 0; attempt < 100 && !calls.some((call) => call.workflowRunId === paused.runId); attempt++) {
+    await delay(2);
+  }
+  assert.equal((await manager.request({ operation: "control", scope,
+    input: { runId: paused.runId, action: "pause" } })).ok, true);
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const snapshot = success(await manager.request({ operation: "get", scope, input: { runId: paused.runId } })) as any;
+    if (snapshot.state === "paused") break;
+    await delay(5);
+  }
+  assert.equal(calls.some((call) => call.workflowRunId === paused.runId && call.prompt === "after-pause"), false);
+  assert.equal((await manager.request({ operation: "control", scope,
+    input: { runId: paused.runId, action: "resume" } })).ok, true);
+  assert.deepEqual((await terminal(paused.runId)).result, ["done:slow", "done:after-pause"]);
+
+  const defaultActiveMs = workflowsConfig.limits.runActiveMs;
+  workflowsConfig.limits.runActiveMs = 50;
+  const clockPaused = await run(`
+export const meta = { name: 'clock-paused', description: 'Paused active-time clock' }
+return await agent('after-clock-pause')`);
+  assert.equal((await manager.request({ operation: "control", scope,
+    input: { runId: clockPaused.runId, action: "pause" } })).ok, true);
+  await delay(80);
+  const parkedSnapshot = success(await manager.request({ operation: "get", scope,
+    input: { runId: clockPaused.runId } })) as any;
+  assert.equal(parkedSnapshot.state, "paused", "parked pause time does not consume active-time budget");
+  assert.equal((await manager.request({ operation: "control", scope,
+    input: { runId: clockPaused.runId, action: "resume" } })).ok, true);
+  assert.equal((await terminal(clockPaused.runId)).result, "done:after-clock-pause");
+  workflowsConfig.limits.runActiveMs = defaultActiveMs;
+
+  const heldRestart = await run(`
+export const meta = { name: 'held-restart', description: 'Restart before delivery' }
+return await agent('slow-restart')`);
+  for (let attempt = 0; attempt < 100 && !calls.some((call) => call.workflowRunId === heldRestart.runId); attempt++) {
+    await delay(2);
+  }
+  assert.equal((await manager.request({ operation: "control", scope,
+    input: { runId: heldRestart.runId, action: "pause" } })).ok, true);
+  let heldStep;
+  for (let attempt = 0; attempt < 100; attempt++) {
+    heldStep = workflowStore.listSteps(heldRestart.runId)[0];
+    if (heldStep?.state === "completed") break;
+    await delay(5);
+  }
+  assert.equal(heldStep?.state, "completed");
+  assert.equal((await manager.request({ operation: "control", scope,
+    input: { runId: heldRestart.runId, action: "restart_agent", stepId: heldStep!.id } })).ok, true);
+  assert.equal((await manager.request({ operation: "control", scope,
+    input: { runId: heldRestart.runId, action: "resume" } })).ok, true);
+  assert.equal((await terminal(heldRestart.runId)).result, "done:slow-restart:2");
+  assert.equal(workflowStore.listAttempts(heldStep!.id).length, 2);
+
+  const budgeted = await run(`
+export const meta = { name: 'budgeted', description: 'Finite budget' }
+await agent('budget-one')
+return await agent('budget-two')`, { outputTokenBudget: 3 });
+  const budgetSnapshot = await terminal(budgeted.runId);
+  assert.equal(budgetSnapshot.state, "failed");
+  assert.equal(budgetSnapshot.error.code, "BUDGET_EXHAUSTED");
+  assert.equal(calls.some((call) => call.workflowRunId === budgeted.runId && call.prompt === "budget-two"), false);
+
+  workflowsConfig.limits.runActiveMs = 100;
+  const rateLimited = await run(`
+export const meta = { name: 'rate-limited', description: 'Provider usage gate' }
+return await agent('rate-once')`);
+  let sawUsageGate = false;
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const snapshot = success(await manager.request({ operation: "get", scope, input: { runId: rateLimited.runId } })) as any;
+    if (snapshot.state === "waiting_for_usage" && snapshot.nextEligibleAt) { sawUsageGate = true; break; }
+    await delay(2);
+  }
+  assert.equal(sawUsageGate, true, "recognized provider reset metadata persists a bounded usage gate");
+  assert.equal((await terminal(rateLimited.runId)).result, "done:rate-once");
+  assert.equal(promptCalls.get("rate-once"), 2);
+  workflowsConfig.limits.runActiveMs = defaultActiveMs;
+
+  workflowsConfig.maxAttemptsPerRun = 1;
+  const capped = await run(`
+export const meta = { name: 'capped', description: 'Atomic attempt cap' }
+return await parallel([() => agent('cap-one'), () => agent('cap-two')])`);
+  const cappedSnapshot = await terminal(capped.runId);
+  workflowsConfig.maxAttemptsPerRun = defaultWorkflowsConfig().maxAttemptsPerRun;
+  assert.equal(cappedSnapshot.state, "completed");
+  assert.equal(cappedSnapshot.partial, true);
+  assert.equal(workflowStore.countAttempts(capped.runId), 1);
+  assert.equal(calls.filter((call) => call.workflowRunId === capped.runId).length, 1,
+    "the attempt cap is rechecked before provider dispatch");
+
+  const failedRoot = await run(`
+export const meta = { name: 'failed-root', description: 'Root admission closes on failure' }
+for (let index = 0; index < 20; index++) agent('hold-failure-' + index)
+throw new Error('root failed')`);
+  assert.equal((await terminal(failedRoot.runId)).state, "failed");
+  const failedDispatches = calls.filter((call) => call.workflowRunId === failedRoot.runId).length;
+  await delay(50);
+  assert.equal(calls.filter((call) => call.workflowRunId === failedRoot.runId).length, failedDispatches,
+    "root failure closes queued provider admission");
+  assert.equal(agentStore.list().some((agent) => agent.status === "running"), false);
+
+  const stopped = await run(`
+export const meta = { name: 'stopped', description: 'Stopped run' }
+return await agent('hold-stop')`);
+  for (let attempt = 0; attempt < 100 && workflowStore.listSteps(stopped.runId)[0]?.state !== "running"; attempt++) {
+    await delay(5);
+  }
+  const stopReply = await manager.request({ operation: "control", scope,
+    input: { runId: stopped.runId, action: "stop" } });
+  assert.equal(stopReply.ok, true);
+  assert.equal((await terminal(stopped.runId)).state, "stopped");
+  assert.equal(agentStore.list().some((agent) => agent.status === "running"), false);
+
+  const crossScope = await manager.request({ operation: "get",
+    scope: { workspaceId: "other", workspaceRoot: root }, input: { runId: first.runId } });
+  assert.equal(crossScope.ok, false);
+
+  const recovering = workflowStore.createRun({ workspaceId: scope.workspaceId, workspaceRoot: root,
+    meta: { name: "recovering", description: "known live turn" }, scriptSource: "", scriptHash: "x",
+    argsPresent: false, defaults: {}, policy: {}, runtimeVersion: "devspace-workflow/v1" });
+  const recoveringStep = workflowStore.createStep({ runId: recovering.id, kind: "agent", logicalPath: "0:1",
+    requestHash: "recovering", request: { prompt: "recovering" }, workspaceId: scope.workspaceId });
+  const recoveringAgent = agentStore.create({ workspaceId: scope.workspaceId, workspaceRoot: root,
+    profileName: "reviewer", provider: "codex", writeMode: "read_only" });
+  const recoveringTurn = agentStore.beginTurn(recoveringAgent.id, { prompt: "recovering", writeMode: "read_only" }).turn;
+  const recoveringAttempt = workflowStore.createAttempt({ stepId: recoveringStep.id,
+    agentId: recoveringAgent.id, agentTurnId: recoveringTurn.id, reason: "initial" });
+  workflowStore.transitionAttempt(recoveringAttempt.id, "running");
+  workflowStore.markActiveAttemptsUncertain();
+  const blockedResume = await manager.request({ operation: "run", scope, input: { resumeFromRunId: recovering.id,
+    script: `export const meta = { name: 'recovering', description: 'known live turn' }\nreturn null` } });
+  assert.equal(blockedResume.ok, false);
+  if (!blockedResume.ok) assert.equal(blockedResume.error.code, "WORKFLOW_BUSY");
+
+  const stale = workflowStore.createRun({ workspaceId: scope.workspaceId, workspaceRoot: root,
+    meta: { name: "stale", description: "stale" }, scriptSource: "", scriptHash: "x",
+    argsPresent: false, defaults: {}, policy: {}, runtimeVersion: "devspace-workflow/v1" });
+  assert.equal(manager.reconcileActiveRuns(), 1);
+  assert.equal(workflowStore.getRun(stale.id)?.state, "recovery_required");
+} finally {
+  await manager.close();
+  await agents.close();
+  database.close();
+  await rm(root, { recursive: true, force: true });
+}
+
+async function run(script: string, extra: { resumeFromRunId?: string; outputTokenBudget?: number } = {}) {
+  const reply = await manager.request({ operation: "run", scope, input: { script, ...extra } });
+  return success(reply) as { runId: string };
+}
+
+async function terminal(runId: string): Promise<any> {
+  for (let attempt = 0; attempt < 200; attempt++) {
+    const reply = await manager.request({ operation: "get", scope, input: { runId } });
+    const snapshot = success(reply) as any;
+    if (["completed", "failed", "stopped", "recovery_required"].includes(snapshot.state)) return snapshot;
+    await delay(10);
+  }
+  throw new Error(`Workflow ${runId} did not finish.`);
+}
+
+function success(reply: WorkflowReply): unknown {
+  if (!reply.ok) throw new Error(`${reply.error.code}: ${reply.error.message}`);
+  return reply.result;
+}
diff --git a/src/workflow-manager.ts b/src/workflow-manager.ts
new file mode 100644
index 000000000..fd9e0122d
--- /dev/null
+++ b/src/workflow-manager.ts
@@ -0,0 +1,1432 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolvePathInsideCanonicalRoot } from "./roots.js";
+import type { WorkflowsConfig } from "./workflow-config.js";
+import type { LocalAgentInvocationResolution, LocalAgentManager } from "./local-agent-manager.js";
+import type { LocalAgentStore, LocalAgentTurnRecord } from "./local-agent-store.js";
+import { parseWorkflowScript } from "./workflow-script.js";
+import { parseStructuredOutput, validateJsonSchema, validateStructuredOutput } from "./workflow-schema.js";
+import { executeWorkflowScript, preflightWorkflowScript } from "./workflow-runtime.js";
+import type {
+  AgentOptions,
+  JsonObject,
+  JsonValue,
+  ParsedWorkflowScript,
+  WorkflowAgentRequest,
+  WorkflowBridgeContext,
+  WorkflowBridgeReply,
+  WorkflowBudgetSnapshot,
+  WorkflowNestedRequest,
+  WorkflowRuntimeEvent,
+  WorkflowRuntimeLimits,
+} from "./workflow-types.js";
+import type { WorkflowReply, WorkflowRequest, WorkflowScope } from "./workflow-protocol.js";
+import { WorkflowRegistry } from "./workflow-registry.js";
+import {
+  WorkflowStore,
+  type WorkflowError,
+  type WorkflowRunRecord,
+  type WorkflowState,
+  type WorkflowStepRecord,
+} from "./workflow-store.js";
+
+const RUNTIME_VERSION = "devspace-workflow/v1";
+const ATTENTION_STATES = new Set<WorkflowState>(["paused", "waiting_for_permission", "waiting_for_usage", "recovery_required"]);
+const TERMINAL_STATES = new Set<WorkflowState>(["completed", "failed", "stopped", "recovery_required"]);
+
+export interface WorkflowWorktree {
+  workspaceId: string;
+  workspaceRoot: string;
+  baseSha: string;
+  changed?: boolean;
+}
+
+export interface WorkflowManagerOptions {
+  stateDir: string;
+  agents: LocalAgentManager;
+  agentStore: LocalAgentStore;
+  config: WorkflowsConfig;
+  store?: WorkflowStore;
+  registry?: WorkflowRegistry;
+  validateScope: (scope: WorkflowScope) => Promise<WorkflowScope>;
+  createWorktree?: (input: { runId: string; stepId: string; scope: WorkflowScope }) => Promise<WorkflowWorktree>;
+  inspectWorktree?: (input: {
+    runId: string; stepId: string; scope: WorkflowScope; worktree: WorkflowWorktree;
+  }) => Promise<{ changed: boolean }>;
+}
+
+export interface RunWorkflowReceipt {
+  runId: string;
+  status: "running";
+  workflowName: string;
+  scriptPath: string;
+  transcriptDir: string;
+  revision: number;
+  resumedFromRunId?: string;
+  warnings?: Array<{ code: string; message: string }>;
+}
+
+interface ActiveRun {
+  runId: string;
+  controller: AbortController;
+  promise: Promise<void>;
+  pauseRequested: boolean;
+  pauseWaiters: Set<() => void>;
+  activeAttempts: number;
+  stepsByRequest: Map<string, string>;
+  liveSteps: Map<string, LiveStep>;
+  replay?: {
+    prefix: WorkflowStepRecord[];
+    index: number;
+    live: boolean;
+    deliveryOrder: WorkflowStepRecord[];
+    deliveryIndex: number;
+    waiting: Map<string, () => void>;
+    priorByNewStep: Map<string, string>;
+  };
+  cancellation?: Promise<boolean>;
+  deliverySequence: number;
+  eventCount: number;
+  logBytes: number;
+  usageNotBefore: number;
+  stopRequested: boolean;
+  activeClock: ActiveTimeClock;
+  waitingUsageAttempts: number;
+}
+
+interface LiveStep {
+  step: WorkflowStepRecord;
+  request: WorkflowAgentRequest;
+  scope: WorkflowScope;
+  turn?: LocalAgentTurnRecord;
+  stopRequested: boolean;
+  restartRequested: boolean;
+  delivered: boolean;
+}
+
+interface RuntimeContext {
+  run: WorkflowRunRecord;
+  active: ActiveRun;
+  script: ParsedWorkflowScript;
+  scope: WorkflowScope;
+  depth: 0 | 1;
+  parentStepId?: string;
+  replayParentStepId?: string;
+}
+
+type ReplayState = NonNullable<ActiveRun["replay"]>;
+
+export class WorkflowManager {
+  private readonly agents: LocalAgentManager;
+  private readonly agentStore: LocalAgentStore;
+  private readonly config: WorkflowsConfig;
+  private readonly store: WorkflowStore;
+  private readonly registry: WorkflowRegistry;
+  private readonly createWorktree?: WorkflowManagerOptions["createWorktree"];
+  private readonly inspectWorktree?: WorkflowManagerOptions["inspectWorktree"];
+  private readonly validateScope: WorkflowManagerOptions["validateScope"];
+  private readonly scheduler: FairScheduler;
+  private readonly nestedScheduler: AbortableSemaphore;
+  private readonly active = new Map<string, ActiveRun>();
+  private readonly revisionWaiters = new Map<string, Set<() => void>>();
+  private closing = false;
+  private pendingLaunches = 0;
+
+  constructor(options: WorkflowManagerOptions) {
+    this.agents = options.agents;
+    this.agentStore = options.agentStore;
+    this.config = options.config;
+    this.store = options.store ?? new WorkflowStore(options.stateDir);
+    this.registry = options.registry ?? new WorkflowRegistry({ scriptBytes: options.config.limits.scriptBytes });
+    this.createWorktree = options.createWorktree;
+    this.inspectWorktree = options.inspectWorktree;
+    this.validateScope = options.validateScope;
+    this.scheduler = new FairScheduler(options.config.maxConcurrentAgents);
+    this.nestedScheduler = new AbortableSemaphore(options.config.maxConcurrentRuns);
+  }
+
+  get activeRunCount(): number { return this.active.size; }
+
+  reconcileActiveRuns(): number {
+    return this.store.markActiveAttemptsUncertain();
+  }
+
+  async request(request: WorkflowRequest): Promise<WorkflowReply> {
+    try {
+      const result = await this.dispatch(request);
+      return { ok: true, result };
+    } catch (error) {
+      const workflowError = toWorkflowError(error);
+      return { ok: false, error: workflowError };
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.closing) return;
+    this.closing = true;
+    for (const run of this.active.values()) {
+      run.stopRequested = true;
+      run.controller.abort(new Error("Workflow daemon is closing."));
+      this.scheduler.cancelRun(run.runId);
+    }
+    await Promise.allSettled([...this.active.values()].map((run) => run.promise));
+    this.store.close();
+  }
+
+  private async dispatch(request: WorkflowRequest): Promise<unknown> {
+    const scope = await this.validateScope(request.scope);
+    switch (request.operation) {
+      case "run": return this.launch(scope, request.input);
+      case "get": return this.get(scope, request.input.runId, request.input.afterRevision, request.input.stepId);
+      case "wait": return this.wait(scope, request.input.runId, request.input.afterRevision, request.input.timeoutMs);
+      case "control": return this.control(scope, request.input);
+      case "list": return this.list(scope, request.input);
+      case "save": return this.save(scope, request.input);
+    }
+  }
+
+  async launch(
+    scope: WorkflowScope,
+    input: Extract<WorkflowRequest, { operation: "run" }>["input"],
+  ): Promise<RunWorkflowReceipt> {
+    if (!this.config.enabled || this.closing) throw workflowFailure("WORKFLOW_DISABLED", "Dynamic workflows are disabled.");
+    const executingRuns = [...this.active.keys()].filter((runId) => {
+      const state = this.store.getRun(runId)?.state;
+      return state !== undefined && !TERMINAL_STATES.has(state);
+    }).length;
+    if (executingRuns + this.pendingLaunches >= this.config.maxConcurrentRuns) {
+      throw workflowFailure("WORKFLOW_BUSY", "The workflow run limit is active.", true);
+    }
+    this.pendingLaunches += 1;
+    try {
+    const source = await this.resolveSource(scope, input);
+    await preflightWorkflowScript(source.parsed, { limits: runtimeLimits(this.config) });
+    const budget = input.outputTokenBudget ?? this.config.defaultOutputTokenBudget;
+    if (budget && this.config.maxOutputTokenBudget && budget > this.config.maxOutputTokenBudget) {
+      throw workflowFailure("BUDGET_EXHAUSTED", "The requested output-token budget exceeds the configured maximum.");
+    }
+    const sourceRun = input.resumeFromRunId ? this.requireRun(scope, input.resumeFromRunId) : undefined;
+    if (sourceRun?.state === "recovery_required") {
+      const hasKnownLiveTurn = this.store.listAttemptsForRun(sourceRun.id)
+        .some((attempt) => this.agentStore.getTurnById(attempt.agentTurnId)?.status === "running");
+      if (hasKnownLiveTurn) throw workflowFailure("WORKFLOW_BUSY",
+        "The source workflow still has a live provider turn; recover or stop it before resuming.", true);
+    }
+    const defaults = compactJson({
+      ...(sourceRun?.defaults ?? {}),
+      agentType: input.agentType ?? stringValue(sourceRun?.defaults.agentType),
+      model: input.model ?? stringValue(sourceRun?.defaults.model),
+      effort: input.effort ?? stringValue(sourceRun?.defaults.effort),
+    });
+    const argsPresent = Object.hasOwn(input, "args") ? true : sourceRun?.argsPresent ?? false;
+    const args = Object.hasOwn(input, "args") ? input.args : sourceRun?.args;
+    const policy = sourceRun?.policy ?? policySnapshot(this.config);
+    const runId = id("wf");
+    const create = {
+      id: runId,
+      workspaceId: scope.workspaceId,
+      workspaceRoot: scope.workspaceRoot,
+      meta: source.parsed.meta as unknown as JsonObject,
+      scriptSource: source.parsed.source,
+      scriptHash: hash(source.parsed.source),
+      sourcePath: source.path,
+      argsPresent,
+      args,
+      defaults,
+      policy,
+      runtimeVersion: RUNTIME_VERSION,
+      outputTokenBudget: budget,
+    };
+    const canonicalRoot = await realpath(scope.workspaceRoot);
+    const transcriptDir = await resolvePathInsideCanonicalRoot(
+      join(".devspace", "workflows", "runs", runId), scope.workspaceRoot, scope.workspaceRoot, canonicalRoot,
+    );
+    await mkdir(transcriptDir, { recursive: true, mode: 0o700 });
+    const editableScriptPath = await resolvePathInsideCanonicalRoot(
+      join(transcriptDir, "workflow.js"), canonicalRoot, canonicalRoot, canonicalRoot,
+    );
+    await writeFile(editableScriptPath, source.parsed.source, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    const run = input.resumeFromRunId
+      ? this.store.createResumedRun({ ...create, sourceRunId: input.resumeFromRunId })
+      : this.store.createRun(create);
+    await this.writeExport(run, "journal.jsonl", "");
+    const active = this.start(run, source.parsed, scope);
+    this.active.set(run.id, active);
+    return {
+      runId: run.id,
+      status: "running",
+      workflowName: source.parsed.meta.name,
+      scriptPath: editableScriptPath,
+      transcriptDir,
+      revision: run.revision,
+      resumedFromRunId: input.resumeFromRunId,
+    };
+    } finally {
+      this.pendingLaunches -= 1;
+    }
+  }
+
+  async get(scope: WorkflowScope, runId: string, afterRevision = 0, stepId?: string): Promise<unknown> {
+    const run = this.requireRun(scope, runId);
+    if (stepId) {
+      const step = this.store.getStep(stepId);
+      if (!step || step.runId !== runId) throw workflowFailure("WORKFLOW_NOT_FOUND", `Unknown workflow step: ${stepId}`);
+      const attempts = this.store.listAttempts(step.id);
+      if (step.output !== undefined && jsonByteLength(step.output) > 64 * 1024) {
+        const outputArtifact = await this.exportStepOutput(run, step);
+        const { output: _output, ...summary } = step;
+        return { ...summary, outputPreview: jsonPreview(step.output), outputArtifact, attempts };
+      }
+      return { ...step, attempts };
+    }
+    return this.snapshot(run, afterRevision);
+  }
+
+  async wait(scope: WorkflowScope, runId: string, afterRevision?: number, timeoutMs = 30_000): Promise<unknown> {
+    let run = this.requireRun(scope, runId);
+    const baseline = afterRevision ?? run.revision;
+    if (!TERMINAL_STATES.has(run.state) && !ATTENTION_STATES.has(run.state) && run.revision <= baseline && timeoutMs > 0) {
+      await new Promise<void>((resolveWait) => {
+        const waiters = this.revisionWaiters.get(runId) ?? new Set();
+        const done = () => { clearTimeout(timer); waiters.delete(done); resolveWait(); };
+        const timer = setTimeout(done, timeoutMs);
+        waiters.add(done);
+        this.revisionWaiters.set(runId, waiters);
+      });
+      run = this.requireRun(scope, runId);
+    }
+    return this.snapshot(run, baseline);
+  }
+
+  async control(
+    scope: WorkflowScope,
+    input: Extract<WorkflowRequest, { operation: "control" }>["input"],
+  ): Promise<unknown> {
+    const run = this.requireRun(scope, input.runId);
+    const active = this.active.get(run.id);
+    if (!active) {
+      if (input.action === "stop" && TERMINAL_STATES.has(run.state)) return this.snapshot(run);
+      throw workflowFailure("WORKFLOW_BUSY", `Workflow ${run.id} is not live.`);
+    }
+    if (input.action === "pause") {
+      if (!active.pauseRequested) {
+        active.pauseRequested = true;
+        this.refreshActiveClock(active);
+        this.changeRun(run.id, active.activeAttempts ? "pausing" : "paused", "Paused by user.");
+      }
+    } else if (input.action === "resume") {
+      active.pauseRequested = false;
+      this.refreshActiveClock(active);
+      this.changeRun(run.id, "running");
+      for (const resume of active.pauseWaiters) resume();
+      active.pauseWaiters.clear();
+      this.scheduler.wake();
+    } else if (input.action === "stop") {
+      this.changeRun(run.id, "stopping", "Stopped by user.");
+      active.stopRequested = true;
+      active.controller.abort(new Error("Workflow stopped."));
+      this.scheduler.cancelRun(run.id);
+      active.cancellation ??= this.cancelOwned(active);
+      const confirmed = await active.cancellation;
+      if (!confirmed) this.changeRun(run.id, "recovery_required", "Cancellation could not be confirmed.",
+        undefined, false, workflowFailure("CANCELLATION_UNCONFIRMED", "One or more agent turns may still be active."));
+    } else {
+      const live = input.stepId ? active.liveSteps.get(input.stepId) : undefined;
+      if (!live || live.step.kind !== "agent") {
+        const stored = input.stepId ? this.store.getStep(input.stepId) : undefined;
+        if (input.action === "restart_agent" && stored?.runId === run.id && stored.deliverySequence) {
+          throw workflowFailure("STEP_ALREADY_DELIVERED", "The step result was already delivered to the script.");
+        }
+        throw workflowFailure("WORKFLOW_NOT_FOUND", `Unknown live agent step: ${input.stepId}`);
+      }
+      if (input.action === "restart_agent" && live.delivered) {
+        throw workflowFailure("STEP_ALREADY_DELIVERED", "The step result was already delivered to the script.");
+      }
+      live.restartRequested = input.action === "restart_agent";
+      live.stopRequested = input.action === "stop_agent";
+      if (live.turn) {
+        const stopped = await this.agents.stop(live.turn.agentId, live.turn.id, live.scope);
+        if (stopped.isErr()) throw stopped.error;
+      }
+    }
+    return this.snapshot(this.requireRun(scope, run.id));
+  }
+
+  async list(scope: WorkflowScope, input: Extract<WorkflowRequest, { operation: "list" }>["input"]): Promise<unknown> {
+    const limit = input.limit ?? 20;
+    if (input.kind === "definitions") {
+      const discovered = await this.registry.discover(scope.workspaceRoot);
+      const definitions = discovered.definitions.sort((left, right) => left.name.localeCompare(right.name));
+      const offset = input.cursor ? Number.parseInt(Buffer.from(input.cursor, "base64url").toString("utf8"), 10) : 0;
+      if (!Number.isSafeInteger(offset) || offset < 0) throw workflowFailure("WORKFLOW_SOURCE_INVALID", "Invalid workflow cursor.");
+      const page = definitions.slice(offset, offset + limit);
+      return { definitions: page.map(({ source, parsed, ...item }) => item),
+        invalid: discovered.invalid, conflicts: discovered.conflicts,
+        nextCursor: offset + limit < definitions.length ? Buffer.from(String(offset + limit)).toString("base64url") : undefined };
+    }
+    const before = decodeCursor(input.cursor);
+    const runs = this.store.listRuns(scope.workspaceId, limit + 1, before);
+    const page = runs.slice(0, limit);
+    return { runs: await Promise.all(page.map((run) => this.snapshot(run))),
+      nextCursor: runs.length > limit ? encodeCursor(page.at(-1)!) : undefined };
+  }
+
+  async save(scope: WorkflowScope, input: Extract<WorkflowRequest, { operation: "save" }>["input"]): Promise<unknown> {
+    const run = this.requireRun(scope, input.runId);
+    const saved = await this.registry.save({ workspaceRoot: scope.workspaceRoot, source: run.scriptSource,
+      name: input.name, location: input.location, replace: input.replace });
+    return { name: saved.name, sourcePath: saved.sourcePath, origin: saved.origin, meta: saved.meta };
+  }
+
+  private start(run: WorkflowRunRecord, script: ParsedWorkflowScript, scope: WorkflowScope): ActiveRun {
+    const controller = new AbortController();
+    const activeClock = new ActiveTimeClock(
+      this.config.limits.runActiveMs,
+      this.config.limits.runActiveMs
+        + this.config.maxUsageLimitWaitMs * this.config.maxUsageLimitWaits
+        + 7 * 24 * 60 * 60 * 1_000,
+    );
+    const active: ActiveRun = {
+      runId: run.id, controller, promise: Promise.resolve(), pauseRequested: false,
+      pauseWaiters: new Set(), activeAttempts: 0, stepsByRequest: new Map(), liveSteps: new Map(),
+      deliverySequence: 0,
+      eventCount: 0,
+      logBytes: 0,
+      usageNotBefore: 0,
+      stopRequested: false,
+      activeClock,
+      waitingUsageAttempts: 0,
+      replay: run.resumedFromRunId ? replayState(this.store.findReplayPrefix(run.resumedFromRunId)) : undefined,
+    };
+    active.promise = this.execute({ run, active, script, scope, depth: 0 })
+      .then(async (result) => {
+        if (controller.signal.aborted) {
+          active.cancellation ??= this.cancelOwned(active);
+          if (await active.cancellation) this.changeRun(run.id, "stopped", "Stopped by user.");
+        } else {
+          if (result.partial) this.store.appendEvent(run.id, "warning", {
+            code: "PARTIAL_EXECUTION", message: "One or more workflow tasks failed or were stopped.",
+          });
+          this.changeRun(run.id, "completed", undefined, result.result, result.omittedResult);
+        }
+        await this.exportRunArtifacts(this.store.getRun(run.id)!).catch((error) => {
+          this.store.appendEvent(run.id, "warning", { code: "ARTIFACT_EXPORT_FAILED", message: errorMessage(error) });
+        });
+      })
+      .catch(async (error) => {
+        const failure = toWorkflowError(error, run.id);
+        const stoppedByControl = active.stopRequested;
+        if (!controller.signal.aborted) controller.abort(error);
+        this.scheduler.cancelRun(run.id);
+        active.cancellation ??= this.cancelOwned(active);
+        const confirmed = await active.cancellation;
+        if (!confirmed) this.changeRun(run.id, "recovery_required", "Cancellation could not be confirmed.", undefined, false,
+          workflowFailure("CANCELLATION_UNCONFIRMED", "One or more agent turns may still be active."));
+        else this.changeRun(run.id, stoppedByControl ? "stopped" : "failed", failure.message, undefined, false, failure);
+        await this.exportRunArtifacts(this.store.getRun(run.id)!).catch((exportError) => {
+          this.store.appendEvent(run.id, "warning", { code: "ARTIFACT_EXPORT_FAILED", message: errorMessage(exportError) });
+        });
+      })
+      .finally(() => { activeClock.dispose(); this.active.delete(run.id); this.notify(run.id); });
+    this.changeRun(run.id, "running");
+    return active;
+  }
+
+  private execute(context: RuntimeContext) {
+    const budget = this.budget(context.run);
+    return executeWorkflowScript({
+      script: context.script,
+      argsPresent: context.run.argsPresent,
+      args: context.run.args,
+      generation: context.run.executionGeneration,
+      depth: context.depth,
+      budget,
+      limits: runtimeLimits(this.config),
+      signal: context.active.controller.signal,
+      replay: context.run.resumedFromRunId ? {
+        events: this.store.listEvents(context.run.resumedFromRunId, 0, 100_000)
+          .filter((event) => (event.type === "phase" || event.type === "log")
+            && event.stepId === context.replayParentStepId)
+          .map((event) => event.type === "phase"
+            ? { type: "phase" as const, title: String(event.payload.title) }
+            : { type: "log" as const, message: String(event.payload.message) }),
+        budgetObservations: this.store.listEvents(context.run.resumedFromRunId, 0, 100_000)
+          .filter((event) => event.type === "budget_observation"
+            && event.stepId === context.replayParentStepId)
+          .map((event) => ({
+            getter: event.payload.getter as "spent" | "remaining",
+            value: event.payload.value as number | "Infinity",
+            location: event.payload.location as { line: number; column: number } | undefined,
+          })),
+      } : undefined,
+      callbacks: {
+        agent: (request, bridge) => this.agent(context, request, bridge),
+        workflow: (request, bridge) => this.nested(context, request, bridge),
+        event: (event) => this.runtimeEvent(context, event),
+        control: () => this.pauseGate(context.active),
+        budget: () => this.budget(context.run),
+        nextDeliverySequence: () => ++context.active.deliverySequence,
+        waitForActiveTimeout: (_timeoutMs, signal) => context.active.activeClock.wait(signal),
+      },
+    });
+  }
+
+  private async agent(
+    context: RuntimeContext,
+    request: WorkflowAgentRequest,
+    bridge: WorkflowBridgeContext,
+  ): Promise<WorkflowBridgeReply> {
+    const run = this.store.getRun(context.run.id)!;
+    const defaults = run.defaults as { agentType?: JsonValue; model?: JsonValue; effort?: JsonValue };
+    const target = request.options.agentType ?? stringValue(defaults.agentType) ?? this.config.defaultAgentType;
+    if (!target) throw workflowFailure("AGENT_TARGET_UNAVAILABLE", "No workflow agent target is configured.");
+    const requested = { ...request.options, agentType: target,
+      model: request.options.model ?? phaseModel(context.script, request.phase) ?? stringValue(defaults.model),
+      effort: request.options.effort ?? stringValue(defaults.effort) };
+    const resolved = await this.agents.resolveInvocation({ target, workspaceRoot: context.scope.workspaceRoot,
+      workspaceId: context.scope.workspaceId, model: requested.model, effort: requested.effort,
+      outputSchema: typeof requested.schema === "object" ? requested.schema : undefined });
+    if (resolved.isErr()) throw resolved.error;
+    if (context.active.controller.signal.aborted) throw context.active.controller.signal.reason;
+    const effective = { ...requested, agentType: resolved.value.target, model: resolved.value.model,
+      effort: resolved.value.effort };
+    const requestObject = { prompt: request.prompt, options: effective,
+      phase: request.options.phase ?? request.phase ?? null,
+      invocation: { provider: resolved.value.provider, profileHash: resolved.value.profileHash,
+        writeMode: resolved.value.writeMode } } as unknown as JsonObject;
+    const requestHash = hash(canonicalJson({ ...requestObject, workspaceId: context.scope.workspaceId, runtimeVersion: RUNTIME_VERSION }));
+    const replay = context.active.replay;
+    if (replay && !replay.live) {
+      const prior = replay.prefix[replay.index];
+      if (prior?.requestHash === requestHash && prior.output !== undefined && prior.deliverySequence !== undefined) {
+        replay.index += 1;
+        const cached = this.store.createStep({ runId: run.id, parentStepId: context.parentStepId, kind: "agent",
+          logicalPath: `${context.depth}:${bridge.requestId}`, requestHash, request: requestObject,
+          phase: request.options.phase ?? request.phase, label: request.options.label, workspaceId: context.scope.workspaceId,
+          cachedFromStepId: prior.id, output: prior.output });
+        context.active.stepsByRequest.set(requestKey(context, bridge.requestId), cached.id);
+        replay.priorByNewStep.set(cached.id, prior.id);
+        this.notify(run.id);
+        await waitForReplayDelivery(replay, prior.id);
+        return { value: prior.output, budget: this.budget(run), replayed: !replay.live };
+      }
+      divergeReplay(replay);
+    }
+    if (this.store.countSteps(run.id).requested >= this.config.maxAgentsPerRun) {
+      throw workflowFailure("AGENT_LIMIT", "The workflow agent limit was reached.");
+    }
+    const step = this.store.createStep({ runId: run.id, parentStepId: context.parentStepId, kind: "agent",
+      logicalPath: `${context.depth}:${bridge.requestId}`, requestHash, request: requestObject,
+      phase: request.options.phase ?? request.phase, label: request.options.label, workspaceId: context.scope.workspaceId });
+    context.active.stepsByRequest.set(requestKey(context, bridge.requestId), step.id);
+    const live: LiveStep = { step, request, scope: context.scope, stopRequested: false, restartRequested: false, delivered: false };
+    context.active.liveSteps.set(step.id, live);
+    try {
+      await this.pauseGate(context.active);
+      await this.usageGate(context);
+      let value = await this.scheduler.schedule(run.id, () => this.runAgent(context, live, effective, resolved.value));
+      for (;;) {
+        await this.pauseGate(context.active);
+        if (live.stopRequested) {
+          this.store.transitionStep(live.step.id, "stopped");
+          value = null;
+          break;
+        }
+        if (!live.restartRequested) break;
+        this.store.transitionStep(live.step.id, "queued");
+        value = await this.scheduler.schedule(run.id, () => this.runAgent(context, live, effective, resolved.value));
+      }
+      return { value, budget: this.budget(run) };
+    } finally {
+      this.notify(run.id);
+    }
+  }
+
+  private async runAgent(
+    context: RuntimeContext,
+    live: LiveStep,
+    options: AgentOptions,
+    resolution: LocalAgentInvocationResolution,
+  ): Promise<JsonValue> {
+    if (live.stopRequested || context.active.controller.signal.aborted) {
+      this.store.transitionStep(live.step.id, "stopped");
+      return null;
+    }
+    await this.pauseGate(context.active);
+    let scope = context.scope;
+    let createdWorktree: WorkflowWorktree | undefined;
+    if (options.isolation === "worktree") {
+      if (!this.createWorktree) throw workflowFailure("WORKSPACE_NOT_ALLOWED", "Worktree isolation is unavailable.");
+      const worktree = await this.createWorktree({ runId: context.run.id, stepId: live.step.id, scope });
+      createdWorktree = worktree;
+      scope = { workspaceId: worktree.workspaceId, workspaceRoot: worktree.workspaceRoot };
+      live.scope = scope;
+      this.store.transitionStep(live.step.id, "starting", { worktree: {
+        workspaceId: worktree.workspaceId, path: worktree.workspaceRoot, baseSha: worktree.baseSha,
+        changed: worktree.changed ?? false,
+      } });
+    }
+    const budget = this.store.getBudget(context.run.budgetId);
+    if (budget.totalOutputTokens !== null && (!budget.usageComplete || budget.knownOutputTokens >= budget.totalOutputTokens)) {
+      throw workflowFailure(budget.usageComplete ? "BUDGET_EXHAUSTED" : "USAGE_UNAVAILABLE", "No further metered attempts may be dispatched.");
+    }
+    if (options.schema !== undefined) {
+      await validateJsonSchema(options.schema, {
+        maxBytes: this.config.limits.schemaBytes,
+        maxDepth: this.config.limits.schemaDepth,
+      });
+    }
+    if (context.active.controller.signal.aborted) throw context.active.controller.signal.reason;
+    const capabilities = resolution.capabilities;
+    if (budget.totalOutputTokens !== null && capabilities.usage === "unavailable") {
+      throw workflowFailure("USAGE_UNAVAILABLE", "This agent target cannot provide reliable output-token usage.");
+    }
+    context.active.activeAttempts += 1;
+    this.refreshActiveClock(context.active);
+    try {
+      let agentId = live.restartRequested && live.turn ? live.turn.agentId : undefined;
+      let schemaAttempts = 0;
+      let restarting = agentId !== undefined;
+      if (restarting) live.restartRequested = false;
+      let retrying = false;
+      let usageWaits = 0;
+      for (let attemptIndex = 1; attemptIndex <= this.config.maxAttemptsPerRun; attemptIndex++) {
+        await this.usageGate(context);
+        if (context.active.controller.signal.aborted) throw context.active.controller.signal.reason;
+        const currentBudget = this.store.getBudget(context.run.budgetId);
+        if (this.store.countAttempts(context.run.id) >= this.config.maxAttemptsPerRun) {
+          throw workflowFailure("ATTEMPT_LIMIT", "The workflow attempt limit was reached.");
+        }
+        if (currentBudget.totalOutputTokens !== null
+          && (!currentBudget.usageComplete || currentBudget.knownOutputTokens >= currentBudget.totalOutputTokens)) {
+          throw workflowFailure(currentBudget.usageComplete ? "BUDGET_EXHAUSTED" : "USAGE_UNAVAILABLE",
+            "No further metered attempts may be dispatched.");
+        }
+        const workflowAttemptId = id("wfa");
+        const attemptReason = restarting ? "restart" as const
+          : retrying ? "retry" as const
+          : attemptIndex === 1 ? "initial" as const : "schema_repair" as const;
+        let usageSequence = 0;
+        let finalUsage = false;
+        const usage = async (update: { sequence: number; outputTokens: number; final: boolean }) => {
+          usageSequence = Math.max(usageSequence, update.sequence);
+          finalUsage ||= update.final;
+          this.store.recordUsage({ attemptId: workflowAttemptId, sequence: update.sequence,
+            outputTokens: update.outputTokens, complete: update.final });
+          this.recordExternalEvent(context, "usage", { attemptId: workflowAttemptId,
+            outputTokens: update.outputTokens, complete: update.final }, live.step.id);
+          this.notify(context.run.id);
+        };
+        const callbacks = {
+          onUsage: usage,
+          onPrepared: (begun: { agent: { id: string }; turn: { id: number } }) => {
+            if (context.active.controller.signal.aborted) throw context.active.controller.signal.reason;
+            if (live.stopRequested) throw workflowFailure("WORKFLOW_STOPPED", "Workflow agent stopped.");
+            if (this.store.countAttempts(context.run.id) >= this.config.maxAttemptsPerRun) {
+              throw workflowFailure("ATTEMPT_LIMIT", "The workflow attempt limit was reached.");
+            }
+            const admissionBudget = this.store.getBudget(context.run.budgetId);
+            if (admissionBudget.totalOutputTokens !== null
+              && (!admissionBudget.usageComplete
+                || admissionBudget.knownOutputTokens >= admissionBudget.totalOutputTokens)) {
+              throw workflowFailure(admissionBudget.usageComplete ? "BUDGET_EXHAUSTED" : "USAGE_UNAVAILABLE",
+                "No further metered attempts may be dispatched.");
+            }
+            const preparedAgent = this.agentStore.getById(begun.agent.id);
+            if (this.config.requireWorktreesForConcurrentWrites && options.isolation !== "worktree") {
+              if (!preparedAgent) throw workflowFailure("WORKSPACE_NOT_ALLOWED", "Agent authority could not be verified.");
+              const existingWriter = preparedAgent.writeMode !== "read_only"
+                && this.agentStore.list({ workspaceId: scope.workspaceId, workspaceRoot: scope.workspaceRoot })
+                  .some((agent) => agent.id !== begun.agent.id
+                    && ["starting", "running"].includes(agent.status)
+                    && agent.writeMode !== "read_only");
+              if (existingWriter) throw workflowFailure("WORKSPACE_NOT_ALLOWED",
+                "Concurrent writable workflow agents require worktree isolation.");
+            }
+            this.store.createAttempt({ id: workflowAttemptId, stepId: live.step.id,
+              agentId: begun.agent.id, agentTurnId: begun.turn.id,
+              reason: attemptReason });
+            this.store.transitionAttempt(workflowAttemptId, "running");
+          },
+          onProgress: async (progress: { type: "text" | "tool"; text?: string; toolName?: string; status?: string; summary?: string }) => {
+            this.recordExternalEvent(context, progress.type === "tool" ? "tool" : "progress", {
+              ...(progress.text ? { text: boundedText(progress.text, this.config.limits.logMessageBytes) } : {}),
+              ...(progress.toolName ? { name: progress.toolName } : {}),
+              ...(progress.status ? { state: progress.status } : {}),
+              ...(progress.summary ? { summary: boundedText(progress.summary, this.config.limits.logMessageBytes) } : {}),
+            }, live.step.id);
+            this.notify(context.run.id);
+          },
+          onPermissionRequest: async (permission: { requestId: string; description: string; options: readonly { id: string; label: string; kind: string }[] }) => {
+            this.store.transitionStep(live.step.id, "waiting_for_permission");
+            this.changeRun(context.run.id, "waiting_for_permission", permission.description);
+            this.recordExternalEvent(context, "permission", {
+              requestId: permission.requestId,
+              description: boundedText(permission.description, this.config.limits.logMessageBytes),
+              options: permission.options as unknown as JsonValue,
+            }, live.step.id);
+            this.notify(context.run.id);
+            return { outcome: "cancelled" as const };
+          },
+        };
+        const start = agentId
+          ? await this.agents.continueTurn(agentId,
+              attemptReason === "retry" || attemptReason === "restart"
+                ? live.request.prompt : schemaRepairPrompt(options.schema), {
+              attemptId: workflowAttemptId, outputSchema: options.schema && typeof options.schema === "object" ? options.schema : undefined,
+              expectedProfileHash: resolution.profileHash,
+              toolPolicy: attemptReason === "retry" || attemptReason === "restart" ? "normal"
+                : capabilities.correctionAuthority === "no_tools" ? "none" : "read_only",
+              workflowRunId: context.run.id, workflowStepId: live.step.id, workflowAttemptId,
+            }, scope, callbacks)
+          : await this.agents.startTurn({ target: options.agentType!, prompt: live.request.prompt,
+              workspaceRoot: scope.workspaceRoot, workspaceId: scope.workspaceId, model: options.model,
+              effort: options.effort, attemptId: workflowAttemptId,
+              writeMode: resolution.writeMode,
+              expectedProfileHash: resolution.profileHash,
+              outputSchema: options.schema && typeof options.schema === "object" ? options.schema : undefined,
+              workflowRunId: context.run.id, workflowStepId: live.step.id, workflowAttemptId,
+            }, callbacks);
+        if (start.isErr()) {
+          if (live.stopRequested || context.active.controller.signal.aborted) {
+            this.store.transitionStep(live.step.id, "stopped");
+            if (live.stopRequested && !context.active.controller.signal.aborted) return null;
+          } else this.store.transitionStep(live.step.id, "failed", { error: toWorkflowError(start.error, context.run.id, live.step.id) });
+          throw start.error;
+        }
+        restarting = false;
+        retrying = false;
+        agentId = start.value.agent.id;
+        live.turn = start.value.turn;
+        this.store.transitionStep(live.step.id, "running", { agentId });
+        if (live.stopRequested || context.active.controller.signal.aborted) {
+          const stopped = await this.agents.stop(live.turn.agentId, live.turn.id, scope);
+          if (stopped.isErr()) throw stopped.error;
+          this.store.finishAttemptAndStep(workflowAttemptId, "stopped", "stopped");
+          if (context.active.controller.signal.aborted) throw context.active.controller.signal.reason;
+          return null;
+        }
+        const waited = await this.agents.wait([agentId], scope, undefined, context.active.controller.signal);
+        if (waited.isErr()) throw waited.error;
+        const turn = this.agentStore.getTurnById(live.turn.id);
+        if (!turn) throw workflowFailure("RECOVERY_REQUIRED", "The agent turn record is missing.");
+        if (turn.status === "stopped") {
+          if (!finalUsage && capabilities.usage !== "unavailable") this.store.recordUsage({
+            attemptId: workflowAttemptId, sequence: usageSequence + 1, outputTokens: undefined, complete: false,
+          });
+          this.store.transitionAttempt(workflowAttemptId, "stopped");
+          if (live.restartRequested) { live.restartRequested = false; restarting = true; continue; }
+          this.store.finishAttemptAndStep(workflowAttemptId, "stopped", "stopped");
+          return null;
+        }
+        if (turn.status !== "completed") {
+          if (turn.retryAfterMs !== undefined && turn.executionUncertain !== true
+            && usageSequence === 0
+            && usageWaits < this.config.maxUsageLimitWaits
+            && turn.retryAfterMs <= this.config.maxUsageLimitWaitMs) {
+            this.store.recordUsage({ attemptId: workflowAttemptId, sequence: 1, outputTokens: 0, complete: true });
+            usageWaits += 1;
+            this.store.transitionAttempt(workflowAttemptId, "waiting_for_usage");
+            this.store.transitionStep(live.step.id, "waiting_for_usage");
+            const nextEligibleAt = Date.now() + turn.retryAfterMs;
+            if (nextEligibleAt > context.active.usageNotBefore) {
+              context.active.usageNotBefore = nextEligibleAt;
+              this.store.setNextEligibleAt(context.run.id, new Date(nextEligibleAt).toISOString());
+            }
+            this.changeRun(context.run.id, "waiting_for_usage", "Waiting for the provider usage limit to reset.");
+            await this.usageGate(context);
+            this.store.transitionAttempt(workflowAttemptId, "failed", workflowFailure(
+              turn.errorCode ?? "PROVIDER_EXECUTION_ERROR", turn.error ?? "Provider usage limit reached.", true,
+            ));
+            this.store.transitionStep(live.step.id, "queued");
+            retrying = true;
+            continue;
+          }
+          if (!finalUsage && capabilities.usage !== "unavailable") this.store.recordUsage({
+            attemptId: workflowAttemptId, sequence: usageSequence + 1, outputTokens: undefined, complete: false,
+          });
+          const error = workflowFailure(turn.errorCode ?? "PROVIDER_EXECUTION_ERROR", turn.error ?? "Agent execution failed.", turn.errorRetryable ?? false);
+          this.store.finishAttemptAndStep(workflowAttemptId, "failed", "failed", { error });
+          return null;
+        }
+        if (!finalUsage && capabilities.usage !== "unavailable") this.store.recordUsage({
+          attemptId: workflowAttemptId, sequence: usageSequence + 1, outputTokens: undefined, complete: false,
+        });
+        this.store.transitionAttempt(workflowAttemptId, "completed");
+        const text = turn.response ?? "";
+        if (options.schema === undefined) {
+          this.store.finishAttemptAndStep(workflowAttemptId, "completed", "completed", { output: text });
+          return text;
+        }
+        let parsed: JsonValue;
+        try { parsed = parseStructuredOutput(text); }
+        catch { parsed = text; }
+        const validation = await validateStructuredOutput(options.schema, parsed, {
+          maxBytes: this.config.limits.schemaBytes,
+          maxDepth: this.config.limits.schemaDepth,
+        });
+        if (validation.valid && validation.value !== undefined) {
+          this.store.finishAttemptAndStep(workflowAttemptId, "completed", "completed", { output: validation.value });
+          return validation.value;
+        }
+        schemaAttempts += 1;
+        if (schemaAttempts >= 5) break;
+        if (capabilities.correctionAuthority === "unsupported") break;
+      }
+      const error = workflowFailure("SCHEMA_VALIDATION_FAILED", "Agent output did not match the requested schema.");
+      this.store.transitionStep(live.step.id, "failed", { error });
+      throw error;
+    } finally {
+      context.active.activeAttempts -= 1;
+      this.refreshActiveClock(context.active);
+      if (createdWorktree && this.inspectWorktree) {
+        try {
+          const inspection = await this.inspectWorktree({ runId: context.run.id, stepId: live.step.id,
+            scope, worktree: createdWorktree });
+          this.store.updateStepWorktree(live.step.id, {
+            workspaceId: createdWorktree.workspaceId, path: createdWorktree.workspaceRoot,
+            baseSha: createdWorktree.baseSha, changed: inspection.changed,
+          });
+        } catch (error) {
+          this.store.updateStepWorktree(live.step.id, {
+            workspaceId: createdWorktree.workspaceId, path: createdWorktree.workspaceRoot,
+            baseSha: createdWorktree.baseSha, changed: true,
+          });
+          this.store.appendEvent(context.run.id, "warning", {
+            code: "WORKTREE_INSPECTION_FAILED", message: errorMessage(error),
+          }, live.step.id);
+        }
+      }
+      if (context.active.pauseRequested && context.active.activeAttempts === 0) this.changeRun(context.run.id, "paused", "Paused by user.");
+    }
+  }
+
+  private async nested(context: RuntimeContext, request: WorkflowNestedRequest, bridge: WorkflowBridgeContext): Promise<WorkflowBridgeReply> {
+    if (context.depth >= 1) throw workflowFailure("NESTING_LIMIT", "Nested workflows are limited to one child level.");
+    const definition = typeof request.reference === "string"
+      ? await this.registry.resolveName(context.scope.workspaceRoot, request.reference)
+      : await this.registry.resolvePath(context.scope.workspaceRoot, request.reference.scriptPath,
+          context.run.sourcePath ? dirname(context.run.sourcePath) : context.scope.workspaceRoot);
+    await preflightWorkflowScript(definition.parsed, { limits: runtimeLimits(this.config) });
+    const requestObject = { reference: request.reference as JsonValue, argsPresent: request.argsPresent,
+      args: request.args ?? null, phase: request.phase ?? null } as unknown as JsonObject;
+    const requestHash = hash(canonicalJson(requestObject));
+    const replay = context.active.replay;
+    let prior: WorkflowStepRecord | undefined;
+    if (replay && !replay.live) {
+      const candidate = replay.prefix[replay.index];
+      if (candidate?.kind === "workflow" && candidate.requestHash === requestHash
+        && candidate.deliverySequence !== undefined) {
+        prior = candidate;
+        replay.index += 1;
+      } else divergeReplay(replay);
+    }
+    const step = this.store.createStep({ runId: context.run.id, parentStepId: context.parentStepId, kind: "workflow",
+      logicalPath: `${context.depth}:${bridge.requestId}`, requestHash, request: requestObject,
+      phase: request.phase, label: definition.meta.name, workspaceId: context.scope.workspaceId });
+    context.active.stepsByRequest.set(requestKey(context, bridge.requestId), step.id);
+    this.store.transitionStep(step.id, "running");
+    const childRun: WorkflowRunRecord = { ...context.run, argsPresent: request.argsPresent, args: request.args,
+      scriptSource: definition.source, scriptHash: definition.sourceHash, sourcePath: definition.sourcePath,
+      meta: definition.meta as unknown as JsonObject };
+    try {
+      const release = await this.nestedScheduler.acquire(context.active.controller.signal);
+      try {
+      const result = await this.execute({ run: childRun, active: context.active, script: definition.parsed,
+        scope: context.scope, depth: 1, parentStepId: step.id, replayParentStepId: prior?.id });
+      this.store.transitionStep(step.id, "completed", { output: result.result });
+      if (prior && replay) {
+        replay.priorByNewStep.set(step.id, prior.id);
+        await waitForReplayDelivery(replay, prior.id);
+      }
+      return { value: result.result, budget: this.budget(context.run), replayed: prior !== undefined && !replay?.live };
+      } finally { release(); }
+    } catch (error) {
+      this.store.transitionStep(step.id, "failed", { error: toWorkflowError(error, context.run.id, step.id) });
+      throw error;
+    }
+  }
+
+  private runtimeEvent(context: RuntimeContext, event: WorkflowRuntimeEvent): void {
+    context.active.eventCount += 1;
+    if (context.active.eventCount > this.config.limits.eventsPerRun) {
+      throw workflowFailure("LOG_LIMIT", "The workflow event limit was reached.");
+    }
+    if (event.type === "log") {
+      context.active.logBytes += Buffer.byteLength(event.message, "utf8");
+      if (context.active.logBytes > this.config.limits.logTotalBytes) {
+        throw workflowFailure("LOG_LIMIT", "The workflow log limit was reached.");
+      }
+    }
+    if ((event.type === "phase" || event.type === "log") && event.replayed) {
+      this.store.appendEvent(context.run.id, event.type, event as unknown as JsonObject, context.parentStepId);
+      this.notify(context.run.id);
+      return;
+    }
+    if (event.type === "replay_diverged") {
+      if (context.active.replay) divergeReplay(context.active.replay);
+      this.store.appendEvent(context.run.id, event.type, event as unknown as JsonObject, context.parentStepId);
+    } else if (event.type === "delivery") {
+      const stepId = context.active.stepsByRequest.get(requestKey(context, event.requestId));
+      if (stepId) {
+        this.store.recordDelivery(stepId, event.deliverySequence);
+        const live = context.active.liveSteps.get(stepId);
+        if (live) {
+          live.delivered = true;
+          context.active.liveSteps.delete(stepId);
+        }
+        const replay = context.active.replay;
+        const priorId = replay?.priorByNewStep.get(stepId);
+        if (replay && priorId === replay.deliveryOrder[replay.deliveryIndex]?.id) {
+          replay.deliveryIndex += 1;
+          replay.priorByNewStep.delete(stepId);
+          pumpReplayDelivery(replay);
+        }
+      }
+    } else {
+      if (event.type === "budget_observation" && !event.replayed && context.active.replay) {
+        divergeReplay(context.active.replay);
+      }
+      const payload = event.type === "phase"
+        ? { type: event.type, title: event.title }
+        : event.type === "log"
+          ? { type: event.type, message: event.message }
+          : event;
+      this.store.appendEvent(context.run.id, event.type, payload as unknown as JsonObject, context.parentStepId);
+    }
+    this.notify(context.run.id);
+  }
+
+  private recordExternalEvent(context: RuntimeContext, type: string, payload: JsonObject, stepId?: string): void {
+    context.active.eventCount += 1;
+    if (context.active.eventCount > this.config.limits.eventsPerRun) {
+      throw workflowFailure("LOG_LIMIT", "The workflow event limit was reached.");
+    }
+    const textBytes = [payload.text, payload.summary, payload.description]
+      .reduce<number>((total, value) => total + (typeof value === "string" ? Buffer.byteLength(value, "utf8") : 0), 0);
+    context.active.logBytes += textBytes;
+    if (context.active.logBytes > this.config.limits.logTotalBytes) {
+      throw workflowFailure("LOG_LIMIT", "The workflow log limit was reached.");
+    }
+    this.store.appendEvent(context.run.id, type, payload, stepId);
+  }
+
+  private pauseGate(active: ActiveRun): Promise<void> {
+    if (active.controller.signal.aborted) return Promise.reject(active.controller.signal.reason);
+    if (!active.pauseRequested) return Promise.resolve();
+    return new Promise((resolvePause, rejectPause) => {
+      const done = () => {
+        active.controller.signal.removeEventListener("abort", abort);
+        active.pauseWaiters.delete(done);
+        resolvePause();
+      };
+      const abort = () => {
+        active.pauseWaiters.delete(done);
+        rejectPause(active.controller.signal.reason);
+      };
+      active.controller.signal.addEventListener("abort", abort, { once: true });
+      active.pauseWaiters.add(done);
+    });
+  }
+
+  private async usageGate(context: RuntimeContext): Promise<void> {
+    let waiting = false;
+    try {
+      while (context.active.usageNotBefore > Date.now()) {
+        if (!waiting) {
+          waiting = true;
+          context.active.waitingUsageAttempts += 1;
+          this.refreshActiveClock(context.active);
+        }
+        await abortableDelay(context.active.usageNotBefore - Date.now(), context.active.controller.signal);
+      }
+    } finally {
+      if (waiting) {
+        context.active.waitingUsageAttempts -= 1;
+        this.refreshActiveClock(context.active);
+      }
+    }
+    if (context.active.usageNotBefore !== 0) {
+      context.active.usageNotBefore = 0;
+      this.store.setNextEligibleAt(context.run.id);
+      const run = this.store.getRun(context.run.id);
+      if (run?.state === "waiting_for_usage") {
+        this.changeRun(context.run.id, context.active.pauseRequested ? "paused" : "running",
+          context.active.pauseRequested ? "Paused by user." : undefined);
+      }
+    }
+  }
+
+  private refreshActiveClock(active: ActiveRun): void {
+    const parkedForPause = active.pauseRequested && active.activeAttempts === 0;
+    const parkedForUsage = active.activeAttempts > 0
+      && active.waitingUsageAttempts === active.activeAttempts;
+    active.activeClock.setSuspended(parkedForPause || parkedForUsage);
+  }
+
+  private async cancelOwned(active: ActiveRun): Promise<boolean> {
+    const turns = [...active.liveSteps.values()].filter((step) => step.turn && !step.delivered);
+    if (!turns.length) return true;
+    const cancellation = Promise.all(turns.map(async (step) => {
+      const turn = step.turn!;
+      const stopped = await this.agents.stop(turn.agentId, turn.id, step.scope);
+      if (stopped.isErr()) return false;
+      return stopped.value.status === "stopped"
+        || stopped.value.status === "completed"
+        || stopped.value.status === "failed";
+    })).then((settled) => settled.every(Boolean));
+    return new Promise((resolveCancellation) => {
+      const timer = setTimeout(() => resolveCancellation(false), 10_000);
+      timer.unref();
+      void cancellation.then((confirmed) => {
+        clearTimeout(timer);
+        resolveCancellation(confirmed);
+      });
+    });
+  }
+
+  private budget(run: WorkflowRunRecord): WorkflowBudgetSnapshot {
+    const budget = this.store.getBudget(run.budgetId);
+    return { total: budget.totalOutputTokens, knownSpent: budget.knownOutputTokens, complete: budget.usageComplete };
+  }
+
+  private async exportRunArtifacts(run: WorkflowRunRecord): Promise<{
+    journal: { id: string; path: string; bytes: number };
+    result?: { id: string; path: string; bytes: number };
+  }> {
+    const events = [];
+    let after = 0;
+    while (events.length < this.config.limits.eventsPerRun) {
+      const page = this.store.listEvents(run.id, after,
+        Math.min(1_000, this.config.limits.eventsPerRun - events.length));
+      if (!page.length) break;
+      events.push(...page);
+      after = page.at(-1)!.sequence;
+      if (page.length < 1_000) break;
+    }
+    const lines = events.map((event) => JSON.stringify(event));
+    if (after < run.revision) lines.push(JSON.stringify({ runId: run.id, sequence: after,
+      type: "export_truncated", payload: { limit: this.config.limits.eventsPerRun } }));
+    const journalText = lines.join("\n") + (lines.length ? "\n" : "");
+    const journal = await this.writeExport(run, "journal.jsonl", journalText);
+    if (run.result === undefined) return { journal };
+    const result = await this.writeExport(run, "result.json", `${JSON.stringify(run.result)}\n`);
+    this.store.setResultArtifactId(run.id, result.id);
+    return { journal, result };
+  }
+
+  private async exportStepOutput(run: WorkflowRunRecord, step: WorkflowStepRecord): Promise<{
+    id: string; path: string; bytes: number;
+  } | undefined> {
+    if (step.output === undefined) return undefined;
+    return this.writeExport(run, `step-${step.id}.json`, `${JSON.stringify(step.output)}\n`);
+  }
+
+  private async writeExport(
+    run: WorkflowRunRecord, filename: string, contents: string,
+  ): Promise<{ id: string; path: string; bytes: number }> {
+    const canonicalRoot = await realpath(run.workspaceRoot);
+    const directory = await resolvePathInsideCanonicalRoot(
+      join(".devspace", "workflows", "runs", run.id), run.workspaceRoot, run.workspaceRoot, canonicalRoot,
+    );
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = await resolvePathInsideCanonicalRoot(join(directory, filename), canonicalRoot, canonicalRoot, canonicalRoot);
+    await writeFile(path, contents, { encoding: "utf8", mode: 0o600 });
+    return { id: `workflow:${run.id}:${filename}`, path, bytes: Buffer.byteLength(contents, "utf8") };
+  }
+
+  private async snapshot(run: WorkflowRunRecord, afterRevision = 0): Promise<JsonObject> {
+    const counts = this.store.countSteps(run.id);
+    const budget = this.store.getBudget(run.budgetId);
+    const steps = this.store.listStepSummaries(run.id);
+    const journalEvents = this.store.listEvents(run.id, afterRevision, 1_000);
+    const events = journalEvents.filter((event) => event.payload.replayed !== true);
+    const eventsThroughRevision = journalEvents.at(-1)?.sequence ?? Math.min(afterRevision, run.revision);
+    const eventsTruncated = eventsThroughRevision < run.revision;
+    let exports: Awaited<ReturnType<WorkflowManager["exportRunArtifacts"]>> | undefined;
+    let exportWarning: JsonObject | undefined;
+    if (TERMINAL_STATES.has(run.state)) {
+      try { exports = await this.exportRunArtifacts(run); }
+      catch (error) { exportWarning = { code: "ARTIFACT_EXPORT_FAILED", message: errorMessage(error) }; }
+    }
+    const largeResult = run.result !== undefined && jsonByteLength(run.result) > 64 * 1024;
+    const phases = new Map<string, { id: string; title: string; running: number; completed: number; failed: number }>();
+    for (const step of steps) {
+      if (!step.phase) continue;
+      const phase = phases.get(step.phase) ?? { id: hash(step.phase).slice(0, 12), title: step.phase, running: 0, completed: 0, failed: 0 };
+      if (["queued", "starting", "running", "waiting_for_permission", "waiting_for_usage"].includes(step.state)) phase.running++;
+      else if (["completed", "cached"].includes(step.state)) phase.completed++;
+      else phase.failed++;
+      phases.set(step.phase, phase);
+    }
+    return compactJson({
+      runId: run.id,
+      workflowName: stringValue(run.meta.name) ?? "workflow",
+      resumedFromRunId: run.resumedFromRunId,
+      state: run.state,
+      revision: run.revision,
+      nextEventRevision: eventsThroughRevision,
+      eventsTruncated,
+      counts,
+      usage: {
+        outputTokens: budget.usageComplete ? budget.knownOutputTokens : null,
+        knownOutputTokens: budget.knownOutputTokens,
+        complete: budget.usageComplete,
+        budgetTotal: budget.totalOutputTokens,
+        remaining: budget.totalOutputTokens === null || !budget.usageComplete
+          ? null : Math.max(0, budget.totalOutputTokens - budget.knownOutputTokens),
+        scope: "workflow_lineage",
+      },
+      phases: [...phases.values()],
+      result: largeResult ? undefined : run.result,
+      resultPreview: largeResult ? jsonPreview(run.result!) : undefined,
+      resultArtifact: largeResult ? exports?.result : undefined,
+      error: run.error,
+      pauseReason: run.pauseReason,
+      nextEligibleAt: run.nextEligibleAt,
+      partial: counts.failed + counts.stopped > 0
+        || this.store.hasPartialExecution(run.id),
+      warnings: exportWarning ? [exportWarning] : [],
+      worktrees: steps.filter((step) => step.worktree).map((step) => ({
+        stepId: step.id, label: step.label, state: step.state, workspaceId: step.workspaceId,
+        ...(step.worktree ?? {}),
+      })),
+      transcript: exports ? { directory: dirname(exports.journal.path), journal: exports.journal } : undefined,
+      events,
+    } as unknown as JsonObject);
+  }
+
+  private changeRun(
+    runId: string, state: WorkflowState, reason?: string, result?: JsonValue,
+    omittedResult?: boolean, error?: WorkflowError,
+  ): void {
+    const run = this.store.getRun(runId);
+    if (!run || (TERMINAL_STATES.has(run.state) && run.state === state)) return;
+    this.store.transitionRun(runId, state, { reason, error, ...(result !== undefined ? { result } : {}), omittedResult });
+    this.notify(runId);
+  }
+
+  private notify(runId: string): void {
+    for (const notify of this.revisionWaiters.get(runId) ?? []) notify();
+    this.revisionWaiters.delete(runId);
+  }
+
+  private requireRun(scope: WorkflowScope, runId: string): WorkflowRunRecord {
+    const run = this.store.getRun(runId);
+    if (!run) throw workflowFailure("WORKFLOW_NOT_FOUND", `Unknown workflow run: ${runId}`);
+    if (run.workspaceId !== scope.workspaceId || run.workspaceRoot !== scope.workspaceRoot) {
+      throw workflowFailure("WORKSPACE_MISMATCH", "The workflow belongs to another workspace.");
+    }
+    return run;
+  }
+
+  private async resolveSource(
+    scope: WorkflowScope,
+    input: Extract<WorkflowRequest, { operation: "run" }>["input"],
+  ): Promise<{ parsed: ParsedWorkflowScript; path?: string }> {
+    if (input.scriptPath) {
+      const definition = await this.registry.resolvePath(scope.workspaceRoot, input.scriptPath);
+      return { parsed: definition.parsed, path: definition.sourcePath };
+    }
+    if (input.name) {
+      const definition = await this.registry.resolveName(scope.workspaceRoot, input.name);
+      return { parsed: definition.parsed, path: definition.sourcePath };
+    }
+    if (!input.script) throw workflowFailure("WORKFLOW_SOURCE_INVALID", "A workflow source is required.");
+    return { parsed: parseWorkflowScript(input.script, { maxBytes: this.config.limits.scriptBytes }) };
+  }
+}
+
+export function createWorkflowManager(options: WorkflowManagerOptions): WorkflowManager {
+  return new WorkflowManager(options);
+}
+
+class ActiveTimeClock {
+  private remainingMs: number;
+  private activeSince = performance.now();
+  private activeTimer?: ReturnType<typeof setTimeout>;
+  private readonly hardTimer: ReturnType<typeof setTimeout>;
+  private suspended = false;
+  private expired = false;
+  private readonly waiters = new Set<() => void>();
+
+  constructor(activeLimitMs: number, hardLimitMs: number) {
+    this.remainingMs = activeLimitMs;
+    this.hardTimer = setTimeout(() => this.expire(), Math.min(hardLimitMs, 2_147_483_647));
+    this.hardTimer.unref();
+    this.arm();
+  }
+
+  setSuspended(suspended: boolean): void {
+    if (this.expired || suspended === this.suspended) return;
+    if (suspended) {
+      this.remainingMs -= performance.now() - this.activeSince;
+      if (this.activeTimer) clearTimeout(this.activeTimer);
+      this.activeTimer = undefined;
+      this.suspended = true;
+    } else {
+      this.suspended = false;
+      this.activeSince = performance.now();
+      this.arm();
+    }
+  }
+
+  wait(signal: AbortSignal): Promise<void> {
+    if (this.expired) return Promise.resolve();
+    if (signal.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolveWait, rejectWait) => {
+      const done = () => {
+        signal.removeEventListener("abort", abort);
+        this.waiters.delete(done);
+        resolveWait();
+      };
+      const abort = () => {
+        this.waiters.delete(done);
+        rejectWait(signal.reason);
+      };
+      signal.addEventListener("abort", abort, { once: true });
+      this.waiters.add(done);
+    });
+  }
+
+  dispose(): void {
+    if (this.activeTimer) clearTimeout(this.activeTimer);
+    clearTimeout(this.hardTimer);
+    this.waiters.clear();
+  }
+
+  private arm(): void {
+    if (this.expired || this.suspended) return;
+    if (this.remainingMs <= 0) {
+      this.expire();
+      return;
+    }
+    this.activeTimer = setTimeout(() => this.expire(), this.remainingMs);
+    this.activeTimer.unref();
+  }
+
+  private expire(): void {
+    if (this.expired) return;
+    if (!this.suspended) this.remainingMs -= performance.now() - this.activeSince;
+    this.expired = true;
+    if (this.activeTimer) clearTimeout(this.activeTimer);
+    clearTimeout(this.hardTimer);
+    for (const resolveWait of this.waiters) resolveWait();
+    this.waiters.clear();
+  }
+}
+
+class FairScheduler {
+  private readonly queues = new Map<string, Array<{ run: () => Promise<JsonValue>; resolve: (value: JsonValue) => void; reject: (error: unknown) => void }>>();
+  private order: string[] = [];
+  private cursor = 0;
+  private active = 0;
+
+  constructor(private readonly limit: number) {}
+
+  schedule(runId: string, run: () => Promise<JsonValue>): Promise<JsonValue> {
+    return new Promise((resolveTask, rejectTask) => {
+      const queue = this.queues.get(runId) ?? [];
+      queue.push({ run, resolve: resolveTask, reject: rejectTask });
+      this.queues.set(runId, queue);
+      if (!this.order.includes(runId)) this.order.push(runId);
+      this.drain();
+    });
+  }
+
+  cancelRun(runId: string): void {
+    const queue = this.queues.get(runId) ?? [];
+    for (const item of queue) item.reject(workflowFailure("WORKFLOW_STOPPED", "Workflow stopped."));
+    this.queues.delete(runId);
+    this.order = this.order.filter((id) => id !== runId);
+  }
+
+  wake(): void { this.drain(); }
+
+  private drain(): void {
+    while (this.active < this.limit && this.order.length) {
+      if (this.cursor >= this.order.length) this.cursor = 0;
+      const runId = this.order[this.cursor]!;
+      const queue = this.queues.get(runId);
+      const item = queue?.shift();
+      if (!item) {
+        this.queues.delete(runId);
+        this.order.splice(this.cursor, 1);
+        continue;
+      }
+      this.cursor = (this.cursor + 1) % this.order.length;
+      if (!queue?.length) {
+        this.queues.delete(runId);
+        this.order = this.order.filter((id) => id !== runId);
+        if (this.cursor >= this.order.length) this.cursor = 0;
+      }
+      this.active++;
+      void item.run().then(item.resolve, item.reject).finally(() => { this.active--; this.drain(); });
+    }
+  }
+}
+
+class AbortableSemaphore {
+  private active = 0;
+  private readonly waiting: Array<{
+    signal: AbortSignal;
+    resolve: (release: () => void) => void;
+    reject: (error: unknown) => void;
+  }> = [];
+
+  constructor(private readonly limit: number) {}
+
+  acquire(signal: AbortSignal): Promise<() => void> {
+    if (signal.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolveAcquire, rejectAcquire) => {
+      const entry = { signal, resolve: resolveAcquire, reject: rejectAcquire };
+      const abort = () => {
+        const index = this.waiting.indexOf(entry);
+        if (index >= 0) this.waiting.splice(index, 1);
+        rejectAcquire(signal.reason);
+      };
+      signal.addEventListener("abort", abort, { once: true });
+      entry.resolve = (release) => {
+        signal.removeEventListener("abort", abort);
+        resolveAcquire(release);
+      };
+      this.waiting.push(entry);
+      this.drain();
+    });
+  }
+
+  private drain(): void {
+    while (this.active < this.limit && this.waiting.length) {
+      const entry = this.waiting.shift()!;
+      if (entry.signal.aborted) { entry.reject(entry.signal.reason); continue; }
+      this.active += 1;
+      let released = false;
+      entry.resolve(() => {
+        if (released) return;
+        released = true;
+        this.active -= 1;
+        this.drain();
+      });
+    }
+  }
+}
+
+function runtimeLimits(config: WorkflowsConfig): Partial<WorkflowRuntimeLimits> {
+  return { ...config.limits, maxAgents: config.maxAgentsPerRun, maxAttempts: config.maxAttemptsPerRun };
+}
+
+function replayState(prefix: WorkflowStepRecord[]): ReplayState {
+  return {
+    prefix,
+    index: 0,
+    live: false,
+    deliveryOrder: prefix.filter((step) => step.deliverySequence !== undefined)
+      .sort((left, right) => left.deliverySequence! - right.deliverySequence!),
+    deliveryIndex: 0,
+    waiting: new Map(),
+    priorByNewStep: new Map(),
+  };
+}
+
+function waitForReplayDelivery(replay: ReplayState, priorStepId: string): Promise<void> {
+  if (replay.live) return Promise.resolve();
+  return new Promise((resolveDelivery) => {
+    replay.waiting.set(priorStepId, resolveDelivery);
+    pumpReplayDelivery(replay);
+  });
+}
+
+function divergeReplay(replay: ReplayState): void {
+  replay.live = true;
+  for (const step of replay.deliveryOrder.slice(replay.deliveryIndex)) replay.waiting.get(step.id)?.();
+  replay.waiting.clear();
+  replay.priorByNewStep.clear();
+}
+
+function pumpReplayDelivery(replay: ReplayState): void {
+  const next = replay.deliveryOrder[replay.deliveryIndex];
+  if (!next) return;
+  replay.waiting.get(next.id)?.();
+  replay.waiting.delete(next.id);
+}
+
+function requestKey(context: RuntimeContext, requestId: number): string {
+  return `${context.depth}:${context.parentStepId ?? "root"}:${requestId}`;
+}
+
+function policySnapshot(config: WorkflowsConfig): JsonObject {
+  return JSON.parse(JSON.stringify(config)) as JsonObject;
+}
+
+function phaseModel(script: ParsedWorkflowScript, phase?: string): string | undefined {
+  return phase ? script.meta.phases?.find((item) => item.title === phase)?.model : undefined;
+}
+
+function schemaRepairPrompt(schema: unknown): string {
+  return `Return only corrected JSON matching this schema. Do not repeat tools or other work.\n${JSON.stringify(schema)}`;
+}
+
+function abortableDelay(milliseconds: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise((resolveDelay, rejectDelay) => {
+    const timer = setTimeout(done, milliseconds);
+    const abort = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); rejectDelay(signal.reason); };
+    function done() { signal.removeEventListener("abort", abort); resolveDelay(); }
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+function stringValue(value: JsonValue | undefined): string | undefined { return typeof value === "string" ? value : undefined; }
+function errorMessage(error: unknown): string { return error instanceof Error ? error.message : String(error); }
+function jsonByteLength(value: JsonValue): number { return Buffer.byteLength(JSON.stringify(value), "utf8"); }
+function jsonPreview(value: JsonValue): string { return boundedText(JSON.stringify(value), 4 * 1024); }
+function boundedText(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+  const marker = "…[truncated]";
+  const markerBytes = Buffer.byteLength(marker, "utf8");
+  if (maxBytes <= markerBytes) return Buffer.from(marker).subarray(0, maxBytes).toString("utf8").replace(/�$/u, "");
+  const prefix = Buffer.from(value).subarray(0, maxBytes - markerBytes).toString("utf8").replace(/�$/u, "");
+  return `${prefix}${marker}`;
+}
+function hash(value: string): string { return createHash("sha256").update(value).digest("hex"); }
+function id(prefix: string): string { return `${prefix}_${randomUUID().replaceAll("-", "").slice(0, 16)}`; }
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.entries(value as Record<string, unknown>)
+    .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+
+function compactJson(value: Record<string, unknown>): JsonObject {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined)) as JsonObject;
+}
+
+function workflowFailure(code: string, message: string, retryable = false): WorkflowError {
+  return { code, message, layer: "workflow", retryable };
+}
+
+function toWorkflowError(error: unknown, runId?: string, stepId?: string): WorkflowError {
+  if (error && typeof error === "object" && "code" in error && "message" in error) {
+    const input = error as { code: unknown; message: unknown; layer?: unknown; retryable?: unknown; provider?: unknown; agentId?: unknown };
+    return compactJson({ code: String(input.code), message: String(input.message),
+      layer: typeof input.layer === "string" ? input.layer : "workflow", retryable: input.retryable === true,
+      runId, stepId, provider: input.provider, agentId: input.agentId }) as unknown as WorkflowError;
+  }
+  return { code: "WORKFLOW_FAILED", message: error instanceof Error ? error.message : String(error),
+    layer: "workflow", retryable: false, runId, stepId };
+}
+
+function encodeCursor(run: WorkflowRunRecord): string {
+  return Buffer.from(JSON.stringify({ updatedAt: run.updatedAt, id: run.id })).toString("base64url");
+}
+
+function decodeCursor(cursor?: string): { updatedAt: string; id: string } | undefined {
+  if (!cursor) return undefined;
+  try {
+    const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as { updatedAt?: unknown; id?: unknown };
+    if (typeof value.updatedAt !== "string" || typeof value.id !== "string") throw new Error();
+    return { updatedAt: value.updatedAt, id: value.id };
+  } catch { throw workflowFailure("WORKFLOW_SOURCE_INVALID", "Invalid workflow cursor."); }
+}
diff --git a/src/workflow-protocol.ts b/src/workflow-protocol.ts
new file mode 100644
index 000000000..3ee2ac406
--- /dev/null
+++ b/src/workflow-protocol.ts
@@ -0,0 +1,74 @@
+import * as z from "zod/v4";
+
+const id = z.string().trim().min(1).max(256);
+const optionalText = z.string().trim().min(1).max(2_000).optional();
+const runId = { runId: id };
+const cursor = { cursor: id.optional(), limit: z.number().int().min(1).max(100).optional() };
+
+export const workflowInputs = {
+  run: z.object({
+    script: z.string().min(1).max(256 * 1024).optional(),
+    name: optionalText,
+    scriptPath: optionalText,
+    args: z.json().optional(),
+    resumeFromRunId: id.optional(),
+    agentType: optionalText,
+    model: optionalText,
+    effort: optionalText,
+    outputTokenBudget: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+  }).strict(),
+  get: z.object({ ...runId, afterRevision: z.number().int().nonnegative().optional(), stepId: id.optional() }).strict(),
+  wait: z.object({ ...runId, afterRevision: z.number().int().nonnegative().optional(), timeoutMs: z.number().int().min(0).max(60_000).optional() }).strict(),
+  control: z.object({ ...runId, action: z.enum(["pause", "resume", "stop", "stop_agent", "restart_agent"]), stepId: id.optional() }).strict(),
+  list: z.object({ kind: z.enum(["definitions", "runs"]).default("runs"), ...cursor }).strict(),
+  save: z.object({ ...runId, name: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).max(128), location: z.enum(["project", "user"]), replace: z.boolean().optional() }).strict(),
+};
+
+export type WorkflowOperation = keyof typeof workflowInputs;
+export interface WorkflowScope { workspaceId: string; workspaceRoot: string }
+export type WorkflowRequest = {
+  [K in WorkflowOperation]: {
+    operation: K;
+    scope: WorkflowScope;
+    input: z.output<(typeof workflowInputs)[K]>;
+  }
+}[WorkflowOperation];
+
+const envelope = z.object({
+  operation: z.enum(["run", "get", "wait", "control", "list", "save"]),
+  scope: z.object({ workspaceId: id, workspaceRoot: z.string().min(1).max(8_192) }).strict(),
+  input: z.unknown(),
+}).strict();
+
+export function decodeWorkflowRequest(value: unknown): WorkflowRequest {
+  const request = envelope.parse(value);
+  const input = workflowInputs[request.operation].parse(request.input);
+  if (request.operation === "run") {
+    const run = input as z.output<typeof workflowInputs.run>;
+    if (!run.script && !run.scriptPath && !run.name) throw new Error("Provide script, scriptPath, or name.");
+  }
+  if (request.operation === "control") {
+    const control = input as z.output<typeof workflowInputs.control>;
+    const individual = control.action === "stop_agent" || control.action === "restart_agent";
+    if (individual !== Boolean(control.stepId)) throw new Error("stepId is required only for individual agent controls.");
+  }
+  return { ...request, input } as WorkflowRequest;
+}
+
+export interface WorkflowFailure {
+  code: string; message: string; retryable: boolean; layer?: string;
+  runId?: string; stepId?: string; agentId?: string; provider?: string;
+  location?: { line: number; column: number };
+}
+export type WorkflowReply = { ok: true; result: unknown } | { ok: false; error: WorkflowFailure };
+
+export function decodeWorkflowReply(value: unknown): WorkflowReply {
+  return z.discriminatedUnion("ok", [
+    z.object({ ok: z.literal(true), result: z.unknown() }).strict(),
+    z.object({ ok: z.literal(false), error: z.object({
+      code: z.string(), message: z.string(), retryable: z.boolean(), layer: z.string().optional(),
+      runId: z.string().optional(), stepId: z.string().optional(), agentId: z.string().optional(), provider: z.string().optional(),
+      location: z.object({ line: z.number(), column: z.number() }).strict().optional(),
+    }).strict() }).strict(),
+  ]).parse(value);
+}
diff --git a/src/workflow-registry.test.ts b/src/workflow-registry.test.ts
new file mode 100644
index 000000000..a9e8e9574
--- /dev/null
+++ b/src/workflow-registry.test.ts
@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, readFile, realpath, rm, symlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { WorkflowRegistry } from "./workflow-registry.js";
+
+const source = (name: string) => `export const meta = {name: '${name}', description: 'Example'}; return null;`;
+
+test("workflow registry preserves project boundaries, validates metadata, and atomically saves names", async (t) => {
+  const temporary = await mkdtemp(join(tmpdir(), "workflow-registry-"));
+  const root = await realpath(temporary);
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const project = join(root, "project");
+  const outside = join(root, "outside");
+  const user = join(root, "personal");
+  await mkdir(join(project, ".devspace", "workflows"), { recursive: true });
+  await mkdir(outside); await mkdir(user);
+  await writeFile(join(user, "review.js"), source("review"));
+  await writeFile(join(project, ".devspace", "workflows", "review.js"), source("review"));
+  await writeFile(join(project, ".devspace", "workflows", "invalid.js"), "throw new Error('must not execute')");
+  const registry = new WorkflowRegistry({ userRoot: user });
+  const found = await registry.discover(project);
+  assert.equal(found.definitions[0]?.origin, "project");
+  assert.equal(found.conflicts.length, 1);
+  assert.equal(found.invalid.length, 1);
+  const saves = await Promise.allSettled([1, 2].map(() => registry.save({
+    workspaceRoot: project, source: source("original"), name: "saved", location: "project",
+  })));
+  assert.equal(saves.filter(({ status }) => status === "fulfilled").length, 1);
+  assert.match(await readFile(join(project, ".devspace", "workflows", "saved.js"), "utf8"), /name: "saved"/);
+  await assert.rejects(registry.resolvePath(project, join(outside, "x.js")), /WORKSPACE_NOT_ALLOWED/);
+  await writeFile(join(outside, "escape.js"), source("escape"));
+  await symlink(join(outside, "escape.js"), join(project, "escape.js"));
+  await assert.rejects(registry.resolvePath(project, "escape.js"), /WORKSPACE_NOT_ALLOWED/);
+  const small = new WorkflowRegistry({ userRoot: user, scriptBytes: 20 });
+  await assert.rejects(small.resolvePath(project, ".devspace/workflows/review.js"), /size limit/);
+  await mkdir(join(root, ".devspace", "workflows"), { recursive: true });
+  await writeFile(join(root, ".devspace", "workflows", "outside.js"), source("outside"));
+  assert.equal((await registry.discover(project)).definitions.some(({ name }) => name === "outside"), false);
+});
+
+test("workflow discovery rejects an escaping project definition directory", async (t) => {
+  const root = await realpath(await mkdtemp(join(tmpdir(), "workflow-registry-link-")));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const project = join(root, "project");
+  const outside = join(root, "outside");
+  await mkdir(join(project, ".devspace"), { recursive: true });
+  await mkdir(outside);
+  await writeFile(join(outside, "escape.js"), source("escape"));
+  await symlink(outside, join(project, ".devspace", "workflows"));
+  const result = await new WorkflowRegistry({ userRoot: join(root, "personal") }).discover(project);
+  assert.deepEqual(result.definitions, []);
+  assert.match(result.invalid[0]?.message ?? "", /symbolic link/);
+});
diff --git a/src/workflow-registry.ts b/src/workflow-registry.ts
new file mode 100644
index 000000000..5786bf7cb
--- /dev/null
+++ b/src/workflow-registry.ts
@@ -0,0 +1,231 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, open, link, lstat, mkdir, readdir, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+import { parseWorkflowScript, renameWorkflowMeta } from "./workflow-script.js";
+import type { ParsedWorkflowScript, WorkflowMeta } from "./workflow-types.js";
+
+export type WorkflowDefinitionOrigin = "project" | "user" | "package";
+
+export interface WorkflowDefinition {
+  name: string;
+  sourcePath: string;
+  sourceHash: string;
+  origin: WorkflowDefinitionOrigin;
+  namespace?: string;
+  meta: WorkflowMeta;
+  source: string;
+  parsed: ParsedWorkflowScript;
+}
+
+export interface InvalidWorkflowDefinition {
+  sourcePath: string;
+  origin: WorkflowDefinitionOrigin;
+  message: string;
+}
+
+export interface WorkflowDiscoveryResult {
+  definitions: WorkflowDefinition[];
+  invalid: InvalidWorkflowDefinition[];
+  conflicts: Array<{ name: string; selectedPath: string; ignoredPath: string }>;
+}
+
+export interface WorkflowRegistryOptions {
+  userRoot?: string;
+  packageRoots?: readonly string[];
+  scriptBytes?: number;
+  allowedRoots?: readonly string[];
+}
+
+/** Discovers source files without executing them. Nearest project definition wins. */
+export class WorkflowRegistry {
+  private readonly userRoot: string;
+  private readonly packageRoots: readonly string[];
+  private readonly scriptBytes: number;
+  private readonly allowedRoots?: readonly string[];
+
+  constructor(options: WorkflowRegistryOptions = {}) {
+    this.userRoot = resolve(options.userRoot ?? join(homedir(), ".devspace", "workflows"));
+    this.packageRoots = options.packageRoots?.map((root) => resolve(root)) ?? [];
+    this.scriptBytes = options.scriptBytes ?? 256 * 1024;
+    this.allowedRoots = options.allowedRoots;
+  }
+
+  async discover(workspaceRoot: string): Promise<WorkflowDiscoveryResult> {
+    const roots: Array<{ path: string; origin: WorkflowDefinitionOrigin; namespace?: string }> = [];
+    for (const projectRoot of await projectWorkflowRoots(workspaceRoot, this.allowedRoots)) {
+      roots.push({ path: projectRoot, origin: "project" });
+    }
+    roots.push({ path: this.userRoot, origin: "user" });
+    for (const packageRoot of this.packageRoots) {
+      roots.push({ path: packageRoot, origin: "package", namespace: packageNamespace(packageRoot) });
+    }
+
+    const definitions = new Map<string, WorkflowDefinition>();
+    const invalid: InvalidWorkflowDefinition[] = [];
+    const conflicts: WorkflowDiscoveryResult["conflicts"] = [];
+    for (const root of roots) {
+      if (root.origin === "project") {
+        try {
+          const [project, directory] = await Promise.all([realpath(dirname(dirname(root.path))), realpath(root.path)]);
+          if (!isWithin(project, directory)) throw new Error("Workflow directory leaves its project through a symbolic link.");
+        } catch (error) {
+          if (!isMissing(error)) invalid.push({ sourcePath: root.path, origin: root.origin, message: errorMessage(error) });
+          continue;
+        }
+      }
+      for (const sourcePath of await javascriptFiles(root.path)) {
+        try {
+          const source = await readAuthorizedFile(root.path, sourcePath, this.scriptBytes);
+          const parsed = parseWorkflowScript(source, { filename: sourcePath, maxBytes: this.scriptBytes });
+          const publicName = root.namespace ? `${root.namespace}:${parsed.meta.name}` : parsed.meta.name;
+          const definition: WorkflowDefinition = {
+            name: publicName,
+            sourcePath,
+            sourceHash: createHash("sha256").update(source).digest("hex"),
+            origin: root.origin,
+            namespace: root.namespace,
+            meta: parsed.meta,
+            source,
+            parsed,
+          };
+          const existing = definitions.get(publicName);
+          if (existing) conflicts.push({ name: publicName, selectedPath: existing.sourcePath, ignoredPath: sourcePath });
+          else definitions.set(publicName, definition);
+        } catch (error) {
+          invalid.push({ sourcePath, origin: root.origin, message: errorMessage(error) });
+        }
+      }
+    }
+    return { definitions: [...definitions.values()], invalid, conflicts };
+  }
+
+  async resolveName(workspaceRoot: string, name: string): Promise<WorkflowDefinition> {
+    const discovered = await this.discover(workspaceRoot);
+    const definition = discovered.definitions.find((item) => item.name === name);
+    if (!definition) throw new Error(`WORKFLOW_NOT_FOUND: ${name}`);
+    return definition;
+  }
+
+  async resolvePath(workspaceRoot: string, sourcePath: string, relativeTo?: string): Promise<WorkflowDefinition> {
+    const absolute = resolve(relativeTo ?? workspaceRoot, sourcePath);
+    const discovered = await this.discover(workspaceRoot);
+    const registered = discovered.definitions.find((item) => item.sourcePath === absolute);
+    if (registered) return registered;
+    if (!isWithin(workspaceRoot, absolute)) throw new Error("WORKSPACE_NOT_ALLOWED");
+    const source = await readAuthorizedFile(workspaceRoot, absolute, this.scriptBytes);
+    const parsed = parseWorkflowScript(source, { filename: absolute, maxBytes: this.scriptBytes });
+    return {
+      name: parsed.meta.name,
+      sourcePath: absolute,
+      sourceHash: createHash("sha256").update(source).digest("hex"),
+      origin: "project",
+      meta: parsed.meta,
+      source,
+      parsed,
+    };
+  }
+
+  async save(input: {
+    workspaceRoot: string;
+    source: string;
+    name: string;
+    location: "project" | "user";
+    replace?: boolean;
+  }): Promise<WorkflowDefinition> {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(input.name)) throw new Error("WORKFLOW_META_INVALID");
+    const parsed = parseWorkflowScript(input.source, { maxBytes: this.scriptBytes });
+    const source = parsed.meta.name === input.name
+      ? input.source
+      : renameWorkflowMeta(input.source, input.name);
+    const root = input.location === "project"
+      ? join(await realpath(input.workspaceRoot), ".devspace", "workflows")
+      : this.userRoot;
+    await ensureWritableRoot(root);
+    const path = join(root, `${input.name}.js`);
+    if (!input.replace && await exists(path)) throw new Error(`Workflow already exists: ${input.name}`);
+    if (await exists(path) && (await lstat(path)).isSymbolicLink()) throw new Error("Refusing to replace a symbolic link.");
+    const temporary = join(root, `.${input.name}.${randomUUID()}.tmp`);
+    await writeFile(temporary, source, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    try {
+      if (input.replace) await rename(temporary, path);
+      else {
+        await link(temporary, path);
+        await unlink(temporary);
+      }
+    } finally {
+      await unlink(temporary).catch(() => undefined);
+    }
+    return this.resolvePath(input.workspaceRoot, path);
+  }
+}
+
+async function projectWorkflowRoots(workspaceRoot: string, allowedRoots: readonly string[] = [workspaceRoot]): Promise<string[]> {
+  const roots: string[] = [];
+  let current = resolve(workspaceRoot);
+  while (true) {
+    roots.push(join(current, ".devspace", "workflows"));
+    if (await exists(join(current, ".git"))) return roots;
+    const parent = dirname(current);
+    if (parent === current || !allowedRoots.some((root) => isWithin(root, parent))) break;
+    current = parent;
+  }
+  return [join(resolve(workspaceRoot), ".devspace", "workflows")];
+}
+
+async function javascriptFiles(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".js"))
+      .map((entry) => join(root, entry.name)).sort();
+  } catch (error) {
+    if (isMissing(error)) return [];
+    throw error;
+  }
+}
+
+async function readAuthorizedFile(root: string, path: string, maxBytes: number): Promise<string> {
+  const [realRoot, realPath] = await Promise.all([realpath(root), realpath(path)]);
+  if (!isWithin(realRoot, realPath)) throw new Error("WORKSPACE_NOT_ALLOWED");
+  const handle = await open(realPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > maxBytes) throw new Error("Workflow script exceeds the source size limit or is not a file.");
+    const bytes = Buffer.alloc(maxBytes + 1);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, null);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    if (offset > maxBytes) throw new Error("Workflow script exceeds the source size limit.");
+    return bytes.subarray(0, offset).toString("utf8");
+  } finally { await handle.close(); }
+}
+
+async function ensureWritableRoot(root: string): Promise<void> {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const resolved = await realpath(root);
+  if (resolved !== resolve(root)) throw new Error("Workflow directory contains a symbolic link.");
+  await access(resolved, constants.W_OK);
+}
+
+function isWithin(root: string, path: string): boolean {
+  const child = relative(resolve(root), resolve(path));
+  return child === "" || (!child.startsWith("..") && !isAbsolute(child));
+}
+
+function packageNamespace(root: string): string {
+  return dirname(root).split(/[\\/]/).filter(Boolean).at(-1) ?? "package";
+}
+
+async function exists(path: string): Promise<boolean> {
+  try { await access(path); return true; } catch { return false; }
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+function errorMessage(error: unknown): string { return error instanceof Error ? error.message : String(error); }
diff --git a/src/workflow-runtime.test.ts b/src/workflow-runtime.test.ts
new file mode 100644
index 000000000..5eea9a918
--- /dev/null
+++ b/src/workflow-runtime.test.ts
@@ -0,0 +1,339 @@
+import assert from "node:assert/strict";
+import { setTimeout as delay } from "node:timers/promises";
+import { executeWorkflowScript, preflightWorkflowScript, WorkflowRuntimeError } from "./workflow-runtime.js";
+import { parseWorkflowScript } from "./workflow-script.js";
+import type {
+  JsonValue,
+  WorkflowAgentRequest,
+  WorkflowRuntimeCallbacks,
+  WorkflowRuntimeEvent,
+} from "./workflow-types.js";
+
+function script(body: string) {
+  return parseWorkflowScript(`export const meta = { name: 'test', description: 'Runtime test' }\n${body}`);
+}
+
+async function run(
+  body: string,
+  callbacks: Partial<WorkflowRuntimeCallbacks> = {},
+  options: { argsPresent?: boolean; args?: JsonValue; limits?: Parameters<typeof executeWorkflowScript>[0]["limits"] } = {},
+) {
+  const events: WorkflowRuntimeEvent[] = [];
+  const defaults: WorkflowRuntimeCallbacks = {
+    agent: async ({ prompt }) => ({ value: prompt }),
+    workflow: async ({ args }) => ({ value: args ?? null }),
+    event: (event) => { events.push(event); },
+    budget: () => ({ total: 10, knownSpent: 3, complete: true }),
+  };
+  const result = await executeWorkflowScript({
+    script: script(body),
+    argsPresent: options.argsPresent ?? false,
+    args: options.args,
+    generation: 1,
+    depth: 0,
+    budget: { total: 10, knownSpent: 0, complete: true },
+    limits: options.limits,
+    signal: new AbortController().signal,
+    callbacks: { ...defaults, ...callbacks, event: async (event) => {
+      events.push(event);
+      await callbacks.event?.(event);
+    } },
+  });
+  return { result, events };
+}
+
+{
+  const seen: WorkflowAgentRequest[] = [];
+  const starts: string[] = [];
+  const { result, events } = await run(`
+phase('Review')
+const mutable = { label: 'before' }
+const first = agent('slow', mutable)
+mutable.label = 'after'
+const parallelRows = await parallel([
+  () => first,
+  () => agent('fast', { phase: 'Explicit' }),
+  () => { throw new Error('boom') },
+])
+const rows = await pipeline(
+  [1, 2],
+  value => agent('stage1:' + value),
+  (previous, original, index) => [previous, original, index],
+)
+const child = await workflow('child', { x: args.x })
+log('finished')
+return { parallelRows, rows, child, spent: budget.spent(), remaining: budget.remaining() }
+`, {
+    agent: async (request) => {
+      seen.push(request);
+      starts.push(request.prompt);
+      if (request.prompt === "slow" || request.prompt === "stage1:1") await delay(30);
+      else await delay(1);
+      return { value: request.prompt, budget: { total: 10, knownSpent: 3, complete: true }, replayed: request.prompt === "fast" };
+    },
+  }, { argsPresent: true, args: { x: 7 } });
+
+  assert.deepEqual(result.result, {
+    parallelRows: ["slow", "fast", null],
+    rows: [["stage1:1", 1, 0], ["stage1:2", 2, 1]],
+    child: { x: 7 },
+    spent: 3,
+    remaining: 7,
+  });
+  assert.equal(result.partial, true);
+  assert.equal(seen.find(({ prompt }) => prompt === "slow")?.options.label, "before");
+  assert.equal(seen.find(({ prompt }) => prompt === "slow")?.phase, "Review");
+  assert.equal(seen.find(({ prompt }) => prompt === "slow")?.location?.line, 5);
+  assert.equal(seen.find(({ prompt }) => prompt === "fast")?.phase, "Explicit");
+  assert(starts.indexOf("stage1:2") < starts.indexOf("stage1:1") + 2, "pipeline items start independently");
+  assert(events.some((event) => event.type === "combinator_error" && event.index === 2));
+  assert(events.some((event) => event.type === "log" && event.message === "finished"));
+  assert(events.some((event) => event.type === "delivery" && event.replayed));
+  assert.equal(events.filter((event) => event.type === "budget_observation").length, 2);
+}
+
+{
+  const result = await executeWorkflowScript({
+    script: script(`await agent('live'); return budget.spent()`),
+    argsPresent: false,
+    generation: 5,
+    depth: 0,
+    budget: { total: 100, knownSpent: 0, complete: true },
+    replay: { budgetObservations: [{ getter: "spent", value: 4 }] },
+    signal: new AbortController().signal,
+    callbacks: {
+      agent: async () => ({ value: "new", budget: { total: 100, knownSpent: 9, complete: true } }),
+      workflow: async () => ({ value: null }),
+      event: () => undefined,
+    },
+  });
+  assert.equal(result.result, 9, "a live delivery ends replayed budget observations");
+}
+
+{
+  const absent = await run(`return typeof args`);
+  assert.equal(absent.result.result, "undefined");
+  const explicitNull = await run(`return args`, {}, { argsPresent: true, args: null });
+  assert.equal(explicitNull.result.result, null);
+  const omitted = await run(`return;`);
+  assert.equal(omitted.result.result, null);
+  assert.equal(omitted.result.omittedResult, true);
+}
+
+{
+  const restricted = await run(`
+const blocked = []
+for (const operation of [() => Date.now(), () => new Date(), () => new Date(2020, 1), () => Math.random()]) {
+  try { operation() } catch { blocked.push(true) }
+}
+return { process: typeof process, require: typeof require, blocked }
+`);
+  assert.deepEqual(restricted.result.result, {
+    process: "undefined",
+    require: "undefined",
+    blocked: [true, true, true, true],
+  });
+  const utc = await run(`return [new Date('2020-01-01T00:00:00.000Z').toISOString(), Date.UTC(2020, 0, 1)]`);
+  assert.deepEqual(utc.result.result, ["2020-01-01T00:00:00.000Z", 1577836800000]);
+  const constructors = await run(`return [
+    Function('return typeof process')(),
+    ({}).constructor.constructor('return typeof require')(),
+    Function('return typeof globalThis.process')(),
+  ]`);
+  assert.deepEqual(constructors.result.result, ["undefined", "undefined", "undefined"]);
+  const protectedIntrinsics = await run(`
+const blocked = []
+for (const mutate of [
+  () => { Array.prototype.toJSON = () => ['forged'] },
+  () => { Promise.all = () => Promise.resolve(['forged']) },
+  () => { Object.getOwnPropertyDescriptors = () => ({}) },
+]) {
+  try { mutate() } catch { blocked.push(true) }
+}
+return { blocked, normal: await Promise.all([[1, 2]]) }
+`);
+  assert.deepEqual(protectedIntrinsics.result.result, { blocked: [true, true, true], normal: [[1, 2]] });
+}
+
+{
+  let calls = 0;
+  const invalidOptions = await run(`
+const value = await agent('x', { unknown: true }).catch(error => error.code)
+return value
+`, { agent: async () => { calls += 1; return { value: null }; } });
+  assert.equal(calls, 0);
+  assert.equal(invalidOptions.result.partial, true);
+}
+
+await assert.rejects(
+  run(`while (true) {}` , {}, { limits: { guestSliceMs: 10, guestTotalCpuMs: 20 } }),
+  (error: unknown) => error instanceof WorkflowRuntimeError && error.code === "SCRIPT_CPU_LIMIT",
+);
+
+await preflightWorkflowScript(script(`while (true) {}`), { timeoutMs: 1_000 });
+await assert.rejects(
+  preflightWorkflowScript(script(`using value = null\nreturn value`)),
+  (error: unknown) => error instanceof WorkflowRuntimeError && error.code === "WORKFLOW_SYNTAX_ERROR",
+);
+
+{
+  let releaseDeadline!: () => void;
+  const deadline = new Promise<void>((resolve) => { releaseDeadline = resolve; });
+  const result = await executeWorkflowScript({
+    script: script(`await agent('parked'); return 'resumed'`), argsPresent: false,
+    generation: 6, depth: 0, budget: { total: null, knownSpent: 0, complete: true },
+    limits: { runActiveMs: 10 }, signal: new AbortController().signal,
+    callbacks: {
+      agent: async () => { await delay(30); return { value: null }; },
+      workflow: async () => ({ value: null }), event: () => undefined,
+      waitForActiveTimeout: () => deadline,
+    },
+  });
+  releaseDeadline();
+  assert.equal(result.result, "resumed", "the manager clock replaces the worker's wall-clock timeout");
+}
+
+await assert.rejects(executeWorkflowScript({
+  script: script(`await agent('timeout'); return null`), argsPresent: false,
+  generation: 7, depth: 0, budget: { total: null, knownSpent: 0, complete: true },
+  limits: { runActiveMs: 20 }, signal: new AbortController().signal,
+  callbacks: {
+    agent: async (_request, context) => await new Promise((_resolve, reject) => {
+      context.signal.addEventListener("abort", () => reject(context.signal.reason), { once: true });
+    }),
+    workflow: async () => ({ value: null }), event: () => undefined,
+  },
+}), (error: unknown) => error instanceof WorkflowRuntimeError && error.code === "WORKFLOW_TIMEOUT");
+await assert.rejects(
+  run(`const spin = () => Promise.resolve().then(spin); spin(); await new Promise(() => {})`, {}, {
+    limits: { guestSliceMs: 10, guestTotalCpuMs: 20 },
+  }),
+  (error: unknown) => error instanceof WorkflowRuntimeError && error.code === "SCRIPT_CPU_LIMIT",
+);
+await assert.rejects(run(`await new Promise(() => {})`), /stalled with no outstanding operations/);
+await assert.rejects(
+  run(`\nthrow new Error('located')`),
+  (error: unknown) => error instanceof WorkflowRuntimeError && error.location?.line === 3,
+);
+
+await assert.rejects(
+  run(`const value = {}; Object.defineProperty(value, 'secret', { get() { throw new Error('getter ran') } }); return value`),
+  /accessors/,
+);
+await assert.rejects(
+  run(`const value = {}; value.self = value; return value`),
+  /cycles/,
+);
+
+{
+  let getterCalled = false;
+  const args = Object.defineProperty({}, "secret", {
+    enumerable: true,
+    get() { getterCalled = true; return "no"; },
+  });
+  await assert.rejects(executeWorkflowScript({
+    script: script(`return args`), argsPresent: true, args: args as JsonValue,
+    generation: 3, depth: 0, budget: { total: null, knownSpent: 0, complete: true },
+    signal: new AbortController().signal,
+    callbacks: {
+      agent: async () => ({ value: null }), workflow: async () => ({ value: null }), event: () => undefined,
+    },
+  }), /accessors/);
+  assert.equal(getterCalled, false);
+}
+
+{
+  const controller = new AbortController();
+  const execution = executeWorkflowScript({
+    script: script(`await agent('wait'); return null`), argsPresent: false,
+    generation: 4, depth: 0, budget: { total: null, knownSpent: 0, complete: true },
+    signal: controller.signal,
+    callbacks: {
+      agent: async (_request, context) => await new Promise((_resolve, reject) => {
+        context.signal.addEventListener("abort", () => reject(context.signal.reason), { once: true });
+      }),
+      workflow: async () => ({ value: null }), event: () => undefined,
+    },
+  });
+  await delay(10);
+  controller.abort();
+  await assert.rejects(execution, (error: unknown) =>
+    error instanceof WorkflowRuntimeError && error.code === "WORKFLOW_STOPPED");
+}
+
+{
+  let childFinished = false;
+  const started = performance.now();
+  const drained = await run(`agent('fire-and-forget'); return 'body-done'`, {
+    agent: async () => {
+      await delay(30);
+      childFinished = true;
+      return { value: "child-done" };
+    },
+  });
+  assert.equal(drained.result.result, "body-done");
+  assert.equal(childFinished, true);
+  assert(performance.now() - started >= 25);
+}
+
+{
+  const reviews = new Map<string, JsonValue>([
+    ["Review a.ts", { findings: ["bad branch"] }],
+    ["Review b.ts", { findings: [] }],
+    ["Verify bad branch in a.ts", { confirmed: true, evidence: "line 4" }],
+  ]);
+  const example = await run(`
+const FINDINGS = { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'], additionalProperties: false }
+const VERDICT = { type: 'object', properties: { confirmed: { type: 'boolean' }, evidence: { type: 'string' } }, required: ['confirmed', 'evidence'], additionalProperties: false }
+const rows = await pipeline(
+  args.files,
+  file => agent('Review ' + file, { phase: 'Review', label: file, schema: FINDINGS }),
+  async (review, file) => {
+    if (review === null) return { file, status: 'review_failed' }
+    const verdicts = await parallel(review.findings.map(finding => () =>
+      agent('Verify ' + finding + ' in ' + file, { phase: 'Verify', label: file, schema: VERDICT })
+        .then(verdict => ({ finding, verdict }))
+    ))
+    return { file, status: 'reviewed', verdicts }
+  },
+)
+return { rows }
+`, {
+    agent: async ({ prompt, options }) => {
+      assert(options.schema);
+      return { value: reviews.get(prompt) ?? null };
+    },
+  }, { argsPresent: true, args: { files: ["a.ts", "b.ts"] } });
+  assert.deepEqual(example.result.result, { rows: [
+    { file: "a.ts", status: "reviewed", verdicts: [{ finding: "bad branch", verdict: { confirmed: true, evidence: "line 4" } }] },
+    { file: "b.ts", status: "reviewed", verdicts: [] },
+  ] });
+}
+
+await assert.rejects(
+  run(`log('12345'); return null`, {}, { limits: { logMessageBytes: 4 } }),
+  (error: unknown) => error instanceof WorkflowRuntimeError && error.code === "LOG_LIMIT",
+);
+
+{
+  const events: WorkflowRuntimeEvent[] = [];
+  const result = await executeWorkflowScript({
+    script: script(`return [budget.spent(), budget.remaining()]`),
+    argsPresent: false,
+    generation: 2,
+    depth: 0,
+    budget: { total: 100, knownSpent: 99, complete: true },
+    replay: { budgetObservations: [
+      { getter: "spent", value: 4 },
+      { getter: "remaining", value: 6 },
+    ] },
+    signal: new AbortController().signal,
+    callbacks: {
+      agent: async () => ({ value: null }),
+      workflow: async () => ({ value: null }),
+      event: (event) => { events.push(event); },
+    },
+  });
+  assert.deepEqual(result.result, [4, 6]);
+  assert.equal(events.filter((event) => event.type === "budget_observation").length, 2);
+}
diff --git a/src/workflow-runtime.ts b/src/workflow-runtime.ts
new file mode 100644
index 000000000..7e1a58551
--- /dev/null
+++ b/src/workflow-runtime.ts
@@ -0,0 +1,412 @@
+import { Worker } from "node:worker_threads";
+import {
+  agentOptionsSchema,
+  assertJsonValue,
+  jsonByteLength,
+  validateSchemaBounds,
+  workflowWorkerUrl,
+} from "./workflow-schema.js";
+import type {
+  JsonValue,
+  WorkflowAgentRequest,
+  WorkflowBudgetSnapshot,
+  WorkflowBridgeContext,
+  WorkflowBridgeReply,
+  WorkflowError,
+  WorkflowNestedRequest,
+  ParsedWorkflowScript,
+  WorkflowRuntimeEvent,
+  WorkflowRuntimeInput,
+  WorkflowRuntimeLimits,
+  WorkflowRuntimeResult,
+} from "./workflow-types.js";
+import { DEFAULT_WORKFLOW_RUNTIME_LIMITS } from "./workflow-types.js";
+
+export class WorkflowRuntimeError extends Error implements WorkflowError {
+  readonly code: string;
+  readonly layer: WorkflowError["layer"];
+  readonly retryable: boolean;
+  readonly location?: WorkflowError["location"];
+
+  constructor(error: WorkflowError) {
+    super(error.message);
+    this.name = "WorkflowRuntimeError";
+    this.code = error.code;
+    this.layer = error.layer;
+    this.retryable = error.retryable;
+    this.location = error.location;
+  }
+}
+
+export async function preflightWorkflowScript(
+  script: ParsedWorkflowScript,
+  options: { limits?: Partial<WorkflowRuntimeLimits>; timeoutMs?: number } = {},
+): Promise<void> {
+  const limits = runtimeLimits(options.limits);
+  const worker = new Worker(workflowWorkerUrl(), {
+    workerData: { kind: "compile", body: script.body, filename: script.filename, limits },
+    resourceLimits: {
+      maxOldGenerationSizeMb: Math.max(16, Math.ceil(limits.guestHeapBytes / (1024 * 1024)) + 16),
+      stackSizeMb: Math.max(1, Math.ceil(limits.guestStackBytes / (1024 * 1024))),
+    },
+  });
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const finish = (operation: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      operation();
+      void worker.terminate();
+    };
+    const timer = setTimeout(() => finish(() => reject(runtimeError(
+      "SCRIPT_CPU_LIMIT", "Workflow syntax preflight timed out.",
+    ))), options.timeoutMs ?? Math.min(5_000, Math.max(2_000, limits.guestSliceMs * 2)));
+    worker.once("message", (message: Record<string, unknown>) => {
+      if (message.type === "compiled") finish(resolve);
+      else if (message.type === "failed") finish(() => reject(new WorkflowRuntimeError(normalizeError(message.error))));
+    });
+    worker.once("error", (error) => finish(() => reject(toRuntimeError(error))));
+    worker.once("exit", (code) => {
+      if (!settled) finish(() => reject(runtimeError("WORKFLOW_FAILED", `Workflow preflight worker exited with code ${code}.`)));
+    });
+  });
+}
+
+export async function executeWorkflowScript(input: WorkflowRuntimeInput): Promise<WorkflowRuntimeResult> {
+  const limits = runtimeLimits(input.limits);
+  validateInput(input, limits);
+  if (input.signal.aborted) throw runtimeError("WORKFLOW_STOPPED", "Workflow stopped.");
+
+  const controller = new AbortController();
+  const abort = () => controller.abort(runtimeError("WORKFLOW_STOPPED", "Workflow stopped."));
+  input.signal.addEventListener("abort", abort, { once: true });
+
+  const worker = new Worker(workflowWorkerUrl(), {
+    workerData: {
+      kind: "runtime",
+      body: input.script.body,
+      filename: input.script.filename,
+      meta: input.script.meta,
+      argsPresent: input.argsPresent,
+      args: input.args,
+      generation: input.generation,
+      depth: input.depth,
+      budget: input.budget,
+      replay: input.replay,
+      limits,
+    },
+    resourceLimits: {
+      maxOldGenerationSizeMb: Math.max(16, Math.ceil(limits.guestHeapBytes / (1024 * 1024)) + 16),
+      stackSizeMb: Math.max(1, Math.ceil(limits.guestStackBytes / (1024 * 1024))),
+    },
+  });
+
+  let settled = false;
+  let resultReceived = false;
+  let partial = false;
+  let deliverySequence = 0;
+  let eventChain = Promise.resolve();
+  const requests = new Set<Promise<void>>();
+
+  const stopWorker = (): void => {
+    worker.postMessage({ type: "abort", generation: input.generation });
+    void worker.terminate();
+  };
+  controller.signal.addEventListener("abort", stopWorker, { once: true });
+
+  let fallbackDeadline: ReturnType<typeof setTimeout> | undefined;
+  const deadline = input.callbacks.waitForActiveTimeout
+    ? input.callbacks.waitForActiveTimeout(limits.runActiveMs, controller.signal)
+    : new Promise<void>((resolveDeadline) => {
+      fallbackDeadline = setTimeout(resolveDeadline, limits.runActiveMs);
+    });
+  void deadline.then(
+    () => controller.abort(runtimeError("WORKFLOW_TIMEOUT", "Workflow active-time limit exceeded.")),
+    (error) => { if (!controller.signal.aborted) controller.abort(error); },
+  );
+
+  try {
+    return await new Promise<WorkflowRuntimeResult>((resolve, reject) => {
+      const fail = (error: unknown): void => {
+        if (settled) return;
+        settled = true;
+        controller.abort(error);
+        reject(error instanceof WorkflowRuntimeError ? error : toRuntimeError(error));
+      };
+
+      controller.signal.addEventListener("abort", () => {
+        fail(controller.signal.reason ?? runtimeError("WORKFLOW_STOPPED", "Workflow stopped."));
+      }, { once: true });
+
+      worker.on("message", (message: Record<string, unknown>) => {
+        if (settled || (message.generation !== undefined && message.generation !== input.generation)) return;
+        if (message.type === "event") {
+          eventChain = eventChain.then(() => input.callbacks.event(message.event as WorkflowRuntimeEvent));
+          eventChain.catch(fail);
+          return;
+        }
+        if (message.type === "request") {
+          const operation = handleRequest(message).catch(fail).finally(() => requests.delete(operation));
+          requests.add(operation);
+          return;
+        }
+        if (message.type === "failed") {
+          partial = true;
+          fail(new WorkflowRuntimeError(normalizeError(message.error)));
+          return;
+        }
+        if (message.type === "result") {
+          resultReceived = true;
+          void Promise.all([eventChain, ...requests]).then(() => {
+            if (settled) return;
+            try {
+              const result = message.result;
+              assertJsonValue(result, "Workflow result");
+              if (jsonByteLength(result) > limits.runResultBytes) {
+                fail(runtimeError("OUTPUT_LIMIT", "Workflow result exceeds the configured size limit."));
+                return;
+              }
+              settled = true;
+              resolve({
+                result,
+                omittedResult: message.omittedResult === true,
+                partial: partial || message.partial === true,
+              });
+            } catch (error) {
+              fail(error);
+            }
+          }, fail);
+        }
+      });
+      worker.once("error", fail);
+      worker.once("exit", (code) => {
+        if (!settled && !resultReceived) {
+          fail(runtimeError("WORKFLOW_FAILED", `Workflow worker exited before returning a result (code ${code}).`));
+        }
+      });
+
+      async function handleRequest(message: Record<string, unknown>): Promise<void> {
+        await eventChain;
+        await input.callbacks.control?.("before_request");
+        if (controller.signal.aborted) throw controller.signal.reason;
+
+        const requestId = requiredSafeInteger(message.requestId, "requestId");
+        const context: WorkflowBridgeContext = { generation: input.generation, requestId, signal: controller.signal };
+        let reply: WorkflowBridgeReply;
+        try {
+          if (message.op === "agent") {
+            reply = await input.callbacks.agent(parseAgentRequest(message, limits), context);
+          } else if (message.op === "workflow") {
+            reply = await input.callbacks.workflow(parseNestedRequest(message, limits), context);
+          } else {
+            throw runtimeError("WORKFLOW_SOURCE_INVALID", "Unknown workflow bridge operation.");
+          }
+          validateReply(reply, limits);
+        } catch (error) {
+          partial = true;
+          await input.callbacks.control?.("before_delivery");
+          const sequence = nextDeliverySequence();
+          await input.callbacks.event({ type: "delivery", requestId, deliverySequence: sequence, replayed: false });
+          worker.postMessage({
+            type: "reply",
+            generation: input.generation,
+            requestId,
+            ok: false,
+            error: normalizeError(error),
+            budget: latestBudget(input),
+            replayed: false,
+          });
+          return;
+        }
+
+        await input.callbacks.control?.("before_delivery");
+        if (controller.signal.aborted) throw controller.signal.reason;
+        const sequence = nextDeliverySequence();
+        await input.callbacks.event({
+          type: "delivery",
+          requestId,
+          deliverySequence: sequence,
+          replayed: reply.replayed === true,
+        });
+        worker.postMessage({
+          type: "reply",
+          generation: input.generation,
+          requestId,
+          ok: true,
+          valueJson: JSON.stringify(reply.value),
+          budget: reply.budget ?? latestBudget(input),
+          replayed: reply.replayed === true,
+        });
+      }
+
+      function nextDeliverySequence(): number {
+        const sequence = input.callbacks.nextDeliverySequence?.() ?? ++deliverySequence;
+        if (!Number.isSafeInteger(sequence) || sequence <= 0) {
+          throw runtimeError("WORKFLOW_FAILED", "Invalid workflow delivery sequence.");
+        }
+        return sequence;
+      }
+    });
+  } finally {
+    if (fallbackDeadline) clearTimeout(fallbackDeadline);
+    if (!controller.signal.aborted) controller.abort();
+    input.signal.removeEventListener("abort", abort);
+    controller.signal.removeEventListener("abort", stopWorker);
+    if (!settled) void worker.terminate();
+    else await worker.terminate().catch(() => undefined);
+  }
+}
+
+function parseAgentRequest(message: Record<string, unknown>, limits: WorkflowRuntimeLimits): WorkflowAgentRequest {
+  const payload = parsePayload(message.payload, limits.promptBytes + limits.schemaBytes + 16 * 1024);
+  const prompt = payload.prompt;
+  if (typeof prompt !== "string" || !prompt.trim()) {
+    throw runtimeError("WORKFLOW_SOURCE_INVALID", "Agent prompt must contain non-whitespace text.");
+  }
+  if (Buffer.byteLength(prompt, "utf8") > limits.promptBytes) {
+    throw runtimeError("OUTPUT_LIMIT", "Agent prompt exceeds the configured size limit.");
+  }
+  const options = agentOptionsSchema.parse(payload.options ?? {});
+  if (options.schema !== undefined) validateSchemaBounds(options.schema, limits.schemaBytes, limits.schemaDepth);
+  const inheritedPhase = typeof payload.phase === "string" ? payload.phase : undefined;
+  if (inheritedPhase !== undefined && (inheritedPhase.length < 1 || inheritedPhase.length > 200)) {
+    throw runtimeError("WORKFLOW_SOURCE_INVALID", "Agent phase is invalid.");
+  }
+  return { prompt, options, phase: options.phase ?? inheritedPhase, location: parseLocation(message.location) };
+}
+
+function parseNestedRequest(message: Record<string, unknown>, limits: WorkflowRuntimeLimits): WorkflowNestedRequest {
+  const payload = parsePayload(message.payload, limits.argsBytes + 16 * 1024);
+  const reference = payload.reference;
+  if (typeof reference !== "string") {
+    if (!reference || typeof reference !== "object" || Array.isArray(reference)
+      || Object.keys(reference).length !== 1 || typeof (reference as Record<string, unknown>).scriptPath !== "string"
+      || !(reference as Record<string, string>).scriptPath.trim()
+      || (reference as Record<string, string>).scriptPath.length > 8_192) {
+      throw runtimeError("WORKFLOW_SOURCE_INVALID", "Nested workflow reference is invalid.");
+    }
+  } else if (!reference.trim()) {
+    throw runtimeError("WORKFLOW_SOURCE_INVALID", "Nested workflow name cannot be empty.");
+  }
+  const argsPresent = payload.argsPresent === true;
+  let args: JsonValue | undefined;
+  if (argsPresent) {
+    assertJsonValue(payload.args, "Nested workflow arguments");
+    args = payload.args;
+    if (jsonByteLength(args) > limits.argsBytes) {
+      throw runtimeError("OUTPUT_LIMIT", "Nested workflow arguments exceed the configured size limit.");
+    }
+  }
+  const phase = typeof payload.phase === "string" ? payload.phase : undefined;
+  if (phase !== undefined && (phase.length < 1 || phase.length > 200)) {
+    throw runtimeError("WORKFLOW_SOURCE_INVALID", "Nested workflow phase is invalid.");
+  }
+  return {
+    reference: reference as string | { scriptPath: string },
+    argsPresent,
+    args,
+    phase,
+    location: parseLocation(message.location),
+  };
+}
+
+function parseLocation(value: unknown): { line: number; column: number } | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object") throw runtimeError("WORKFLOW_SOURCE_INVALID", "Workflow source location is invalid.");
+  const location = value as Record<string, unknown>;
+  if (!Number.isSafeInteger(location.line) || (location.line as number) < 1
+    || !Number.isSafeInteger(location.column) || (location.column as number) < 1) {
+    throw runtimeError("WORKFLOW_SOURCE_INVALID", "Workflow source location is invalid.");
+  }
+  return { line: location.line as number, column: location.column as number };
+}
+
+function parsePayload(value: unknown, maxBytes: number): Record<string, unknown> {
+  if (typeof value !== "string") throw runtimeError("WORKFLOW_SOURCE_INVALID", "Workflow bridge payload is invalid.");
+  if (Buffer.byteLength(value, "utf8") > maxBytes) {
+    throw runtimeError("OUTPUT_LIMIT", "Workflow bridge payload exceeds the configured size limit.");
+  }
+  const parsed: unknown = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw runtimeError("WORKFLOW_SOURCE_INVALID", "Workflow bridge payload is invalid.");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function validateReply(reply: WorkflowBridgeReply, limits: WorkflowRuntimeLimits): void {
+  if (!reply || typeof reply !== "object" || !Object.hasOwn(reply, "value")) {
+    throw runtimeError("WORKFLOW_FAILED", "Workflow bridge returned an invalid reply.");
+  }
+  assertJsonValue(reply.value, "Workflow bridge result");
+  if (jsonByteLength(reply.value) > limits.agentResultBytes) {
+    throw runtimeError("OUTPUT_LIMIT", "Workflow bridge result exceeds the configured size limit.");
+  }
+  if (reply.budget) validateBudget(reply.budget);
+}
+
+function validateInput(input: WorkflowRuntimeInput, limits: WorkflowRuntimeLimits): void {
+  if (!Number.isSafeInteger(input.generation) || input.generation < 0) throw new TypeError("generation must be a nonnegative safe integer.");
+  validateBudget(input.budget);
+  if (input.argsPresent) {
+    assertJsonValue(input.args, "Workflow arguments");
+    if (jsonByteLength(input.args) > limits.argsBytes) throw runtimeError("OUTPUT_LIMIT", "Workflow arguments exceed the configured size limit.");
+  }
+}
+
+function runtimeLimits(overrides: WorkflowRuntimeInput["limits"]): WorkflowRuntimeLimits {
+  const limits = { ...DEFAULT_WORKFLOW_RUNTIME_LIMITS, ...overrides };
+  for (const [name, value] of Object.entries(limits)) {
+    if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer.`);
+  }
+  return limits;
+}
+
+function validateBudget(budget: WorkflowBudgetSnapshot): void {
+  if ((budget.total !== null && (!Number.isSafeInteger(budget.total) || budget.total <= 0))
+    || !Number.isSafeInteger(budget.knownSpent) || budget.knownSpent < 0
+    || typeof budget.complete !== "boolean") {
+    throw new TypeError("Invalid workflow budget snapshot.");
+  }
+}
+
+function latestBudget(input: WorkflowRuntimeInput): WorkflowBudgetSnapshot {
+  const budget = input.callbacks.budget?.() ?? input.budget;
+  validateBudget(budget);
+  return budget;
+}
+
+function normalizeError(error: unknown): WorkflowError {
+  if (error instanceof WorkflowRuntimeError) return error;
+  if (error && typeof error === "object") {
+    const candidate = error as Partial<WorkflowError>;
+    if (typeof candidate.code === "string" && typeof candidate.message === "string") {
+      return {
+        code: candidate.code,
+        message: candidate.message,
+        layer: candidate.layer ?? "workflow",
+        retryable: candidate.retryable ?? false,
+        location: candidate.location,
+      };
+    }
+  }
+  return {
+    code: "WORKFLOW_FAILED",
+    message: error instanceof Error ? error.message : String(error),
+    layer: "workflow",
+    retryable: false,
+  };
+}
+
+function toRuntimeError(error: unknown): WorkflowRuntimeError {
+  return new WorkflowRuntimeError(normalizeError(error));
+}
+
+function runtimeError(code: string, message: string): WorkflowRuntimeError {
+  return new WorkflowRuntimeError({ code, message, layer: "workflow", retryable: false });
+}
+
+function requiredSafeInteger(value: unknown, name: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) throw new TypeError(`${name} is invalid.`);
+  return value as number;
+}
diff --git a/src/workflow-schema.test.ts b/src/workflow-schema.test.ts
new file mode 100644
index 000000000..7f4c87f34
--- /dev/null
+++ b/src/workflow-schema.test.ts
@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import {
+  assertJsonValue,
+  parseStructuredOutput,
+  validateSchemaBounds,
+  validateJsonSchema,
+  validateStructuredOutput,
+  workflowWorkerUrl,
+} from "./workflow-schema.js";
+import type { JsonSchema } from "./workflow-types.js";
+
+let getterCalled = false;
+const accessor = Object.defineProperty({}, "secret", {
+  enumerable: true,
+  get() { getterCalled = true; return "bad"; },
+});
+assert.throws(() => assertJsonValue(accessor), /accessors/);
+assert.equal(getterCalled, false);
+
+const cyclic: Record<string, unknown> = {};
+cyclic.self = cyclic;
+assert.throws(() => assertJsonValue(cyclic), /cycles/);
+assert.throws(() => assertJsonValue([, 1]), /dense/);
+assert.throws(() => assertJsonValue({ value: Number.NaN }), /finite/);
+
+assert.deepEqual(parseStructuredOutput('{"ok":true}'), { ok: true });
+assert.deepEqual(parseStructuredOutput('```json\n{"ok":true}\n```'), { ok: true });
+assert.throws(() => parseStructuredOutput('result: {"ok":true}'));
+assert.throws(() => validateSchemaBounds({ properties: { deep: { properties: {} } } }, 1_000, 2));
+assert.equal(workflowWorkerUrl("file:///source/workflow-schema.ts").href, "file:///source/workflow-worker.ts");
+assert.equal(workflowWorkerUrl("file:///dist/workflow-schema.js").href, "file:///dist/workflow-worker.js");
+
+const schema: JsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $defs: { row: { type: "object", properties: { ok: { type: "boolean" } }, required: ["ok"] } },
+  $ref: "#/$defs/row",
+};
+assert.equal((await validateStructuredOutput(schema, { ok: true })).valid, true);
+await validateJsonSchema(schema);
+await assert.rejects(validateJsonSchema({ type: "not-a-json-schema-type" }), /must be equal to one of the allowed values/i);
+const invalid = await validateStructuredOutput(schema, { ok: "yes" });
+assert.equal(invalid.valid, false);
+assert(invalid.errors?.length);
+assert.equal((await validateStructuredOutput({
+  $schema: "http://json-schema.org/draft-07/schema#",
+  type: "array",
+  items: { type: "integer" },
+}, [1, 2])).valid, true);
+
+await assert.rejects(
+  validateStructuredOutput({ $ref: "https://example.com/schema.json" }, {}),
+  /can't resolve reference|resolve reference/i,
+);
+await assert.rejects(
+  validateStructuredOutput({
+    type: "object",
+    required: ["missing"],
+    properties: {},
+    additionalProperties: false,
+  }, {}),
+  /Required property 'missing'/,
+);
+
+let deepSchema: JsonSchema = { type: "string" };
+for (let depth = 0; depth < 65; depth++) deepSchema = { allOf: [deepSchema] };
+await assert.rejects(validateStructuredOutput(deepSchema, "ok"), /exceeds depth 64/);
+assert.equal((await validateStructuredOutput(deepSchema, "ok", { maxDepth: 140 })).valid, true,
+  "structured validation honors the configured schema depth used at compile time");
diff --git a/src/workflow-schema.ts b/src/workflow-schema.ts
new file mode 100644
index 000000000..4e5bc8235
--- /dev/null
+++ b/src/workflow-schema.ts
@@ -0,0 +1,170 @@
+import { Worker } from "node:worker_threads";
+import * as z from "zod/v4";
+import type {
+  AgentOptions,
+  JsonSchema,
+  JsonValue,
+  StructuredOutputValidation,
+  WorkflowMeta,
+} from "./workflow-types.js";
+
+const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() => z.union([
+  z.null(),
+  z.boolean(),
+  z.number().finite(),
+  z.string(),
+  z.array(jsonValueSchema),
+  z.record(z.string(), jsonValueSchema),
+]));
+
+export const workflowMetaSchema = z.object({
+  name: z.string().min(1).max(128).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+  description: z.string().min(1).max(2_000),
+  whenToUse: z.string().max(2_000).optional(),
+  phases: z.array(z.object({
+    title: z.string().min(1).max(200),
+    detail: z.string().max(2_000).optional(),
+    model: z.string().trim().min(1).optional(),
+  }).strict()).refine(
+    (phases) => new Set(phases.map(({ title }) => title)).size === phases.length,
+    "Phase titles must be unique.",
+  ).optional(),
+}).strict();
+
+export const agentOptionsSchema = z.object({
+  label: z.string().min(1).max(200).optional(),
+  phase: z.string().min(1).max(200).optional(),
+  schema: jsonValueSchema.refine((value): value is JsonSchema => typeof value === "boolean"
+    || (value !== null && !Array.isArray(value) && typeof value === "object"), "Expected a JSON Schema object or boolean.").optional(),
+  model: z.string().trim().min(1).optional(),
+  effort: z.string().trim().min(1).optional(),
+  isolation: z.literal("worktree").optional(),
+  agentType: z.string().trim().min(1).optional(),
+}).strict();
+
+export function validateWorkflowMeta(value: unknown): WorkflowMeta {
+  return workflowMetaSchema.parse(value);
+}
+
+export function validateAgentOptions(value: unknown): AgentOptions {
+  assertJsonValue(value, "Agent options");
+  return agentOptionsSchema.parse(value);
+}
+
+export function assertJsonValue(value: unknown, label = "value"): asserts value is JsonValue {
+  const seen = new Set<object>();
+  const visit = (item: unknown): void => {
+    if (item === null || typeof item === "string" || typeof item === "boolean") return;
+    if (typeof item === "number") {
+      if (Number.isFinite(item)) return;
+      throw new TypeError(`${label} must contain finite numbers.`);
+    }
+    if (typeof item !== "object") throw new TypeError(`${label} must be JSON data.`);
+    if (seen.has(item)) throw new TypeError(`${label} cannot contain cycles.`);
+    seen.add(item);
+    const array = Array.isArray(item);
+    const prototype = Object.getPrototypeOf(item) as unknown;
+    if (prototype !== null && prototype !== (array ? Array.prototype : Object.prototype)) {
+      throw new TypeError(`${label} contains an unsupported object.`);
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(item);
+    const keys = Reflect.ownKeys(descriptors);
+    if (keys.some((key) => typeof key === "symbol")) throw new TypeError(`${label} cannot contain symbols.`);
+    if (array) {
+      if (keys.some((key) => key !== "length" && !/^(0|[1-9]\d*)$/.test(String(key)))) {
+        throw new TypeError(`${label} arrays cannot have custom properties.`);
+      }
+      for (let index = 0; index < item.length; index += 1) {
+        const descriptor = descriptors[index];
+        if (!descriptor || !("value" in descriptor)) throw new TypeError(`${label} arrays must be dense data properties.`);
+        visit(descriptor.value);
+      }
+    } else {
+      for (const key of keys as string[]) {
+        if (["__proto__", "prototype", "constructor"].includes(key)) {
+          throw new TypeError(`${label} contains a prototype-sensitive key.`);
+        }
+        const descriptor = descriptors[key]!;
+        if (!("value" in descriptor)) throw new TypeError(`${label} cannot contain accessors.`);
+        visit(descriptor.value);
+      }
+    }
+    seen.delete(item);
+  };
+  visit(value);
+}
+
+export function jsonByteLength(value: JsonValue): number {
+  return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+
+export function jsonDepth(value: JsonValue): number {
+  if (value === null || typeof value !== "object") return 0;
+  const values = Array.isArray(value) ? value : Object.values(value);
+  return values.length === 0 ? 1 : 1 + Math.max(...values.map(jsonDepth));
+}
+
+export function validateSchemaBounds(schema: JsonSchema, maxBytes: number, maxDepth: number): void {
+  assertJsonValue(schema, "JSON Schema");
+  if (jsonByteLength(schema) > maxBytes) throw new Error(`Schema exceeds ${maxBytes} bytes.`);
+  if (jsonDepth(schema) > maxDepth) throw new Error(`Schema exceeds depth ${maxDepth}.`);
+}
+
+export function parseStructuredOutput(text: string): JsonValue {
+  const trimmed = text.trim();
+  const fenced = /^```json\s*\n([\s\S]*?)\n```$/i.exec(trimmed);
+  const source = fenced?.[1] ?? trimmed;
+  const value: unknown = JSON.parse(source);
+  assertJsonValue(value, "Structured output");
+  return value;
+}
+
+export async function validateStructuredOutput(
+  schema: JsonSchema,
+  value: JsonValue,
+  options: { timeoutMs?: number; maxOldGenerationSizeMb?: number; maxBytes?: number; maxDepth?: number } = {},
+): Promise<StructuredOutputValidation> {
+  validateSchemaBounds(schema, options.maxBytes ?? 128 * 1024, options.maxDepth ?? 64);
+  assertJsonValue(value, "Structured output");
+  return runSchemaWorker({ schema, value }, options);
+}
+
+export async function validateJsonSchema(
+  schema: JsonSchema,
+  options: { timeoutMs?: number; maxOldGenerationSizeMb?: number; maxBytes?: number; maxDepth?: number } = {},
+): Promise<void> {
+  validateSchemaBounds(schema, options.maxBytes ?? 128 * 1024, options.maxDepth ?? 64);
+  const result = await runSchemaWorker({ schema, compileOnly: true }, options);
+  if (!result.valid) throw Object.assign(new Error("JSON Schema compilation failed."), { code: "SCHEMA_INVALID" });
+}
+
+async function runSchemaWorker(
+  workerData: { schema: JsonSchema; value?: JsonValue; compileOnly?: boolean },
+  options: { timeoutMs?: number; maxOldGenerationSizeMb?: number },
+): Promise<StructuredOutputValidation> {
+  const worker = new Worker(workflowWorkerUrl(), {
+    workerData: { kind: "schema", ...workerData },
+    resourceLimits: { maxOldGenerationSizeMb: options.maxOldGenerationSizeMb ?? 32 },
+  });
+  const timeoutMs = options.timeoutMs ?? 2_000;
+  return await new Promise<StructuredOutputValidation>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      void worker.terminate();
+      reject(Object.assign(new Error("Schema validation timed out."), { code: "SCHEMA_VALIDATION_TIMEOUT" }));
+    }, timeoutMs);
+    worker.once("message", (message: StructuredOutputValidation & { error?: string; code?: string }) => {
+      clearTimeout(timer);
+      void worker.terminate();
+      if (message.error) reject(Object.assign(new Error(message.error), { code: message.code ?? "SCHEMA_INVALID" }));
+      else resolve(message);
+    });
+    worker.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+export function workflowWorkerUrl(moduleUrl = import.meta.url): URL {
+  return new URL(moduleUrl.endsWith(".ts") ? "./workflow-worker.ts" : "./workflow-worker.js", moduleUrl);
+}
diff --git a/src/workflow-script.test.ts b/src/workflow-script.test.ts
new file mode 100644
index 000000000..ef91bc731
--- /dev/null
+++ b/src/workflow-script.test.ts
@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { parseWorkflowScript, renameWorkflowMeta, WorkflowScriptError } from "./workflow-script.js";
+
+const valid = `// leading comment
+export const meta = {
+  name: 'review-code',
+  description: "Review\\ncode",
+  phases: [{ title: 'Review', detail: 'Inspect changes' }],
+}
+return args
+`;
+const parsed = parseWorkflowScript(valid);
+assert.equal(parsed.meta.name, "review-code");
+assert.equal(parsed.meta.description, "Review\ncode");
+assert.equal(parsed.body.split("\n").length, valid.split("\n").length);
+assert.match(parsed.body, /return args/);
+assert.doesNotMatch(parsed.body, /export const meta/);
+
+const renamed = renameWorkflowMeta(valid, "verify-code");
+assert.equal(parseWorkflowScript(renamed).meta.name, "verify-code");
+assert.match(renamed, /description: "Review\\ncode"/);
+
+for (const source of [
+  `export const meta = makeMeta()\nreturn null`,
+  `export const meta = {name:'x', name:'y', description:'d'}\nreturn null`,
+  `export const meta = {['name']:'x', description:'d'}\nreturn null`,
+  `export const meta = {name:'x', description:'d', __proto__: null}\nreturn null`,
+  `export const meta = {name:'x', description:'d'}\nexport const other = 1`,
+  `export const meta = {name:'x', description:'d'}\nawait import('./x.js')`,
+]) {
+  assert.throws(() => parseWorkflowScript(source), WorkflowScriptError);
+}
+
+try {
+  parseWorkflowScript(`export const meta = { name: 'x', description: }`);
+  assert.fail("expected syntax error");
+} catch (error) {
+  assert(error instanceof WorkflowScriptError);
+  assert.equal(error.code, "WORKFLOW_SYNTAX_ERROR");
+  assert.equal(error.location?.line, 1);
+}
diff --git a/src/workflow-script.ts b/src/workflow-script.ts
new file mode 100644
index 000000000..ab93523a5
--- /dev/null
+++ b/src/workflow-script.ts
@@ -0,0 +1,187 @@
+import ts from "typescript";
+import { validateWorkflowMeta } from "./workflow-schema.js";
+import type { JsonValue, ParsedWorkflowScript, WorkflowLocation } from "./workflow-types.js";
+
+const FORBIDDEN_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+export class WorkflowScriptError extends Error {
+  readonly code: "WORKFLOW_SOURCE_INVALID" | "WORKFLOW_SYNTAX_ERROR" | "WORKFLOW_META_INVALID";
+  readonly location?: WorkflowLocation;
+
+  constructor(code: WorkflowScriptError["code"], message: string, location?: WorkflowLocation) {
+    super(message);
+    this.name = "WorkflowScriptError";
+    this.code = code;
+    this.location = location;
+  }
+}
+
+export function parseWorkflowScript(
+  source: string,
+  options: { filename?: string; maxBytes?: number } = {},
+): ParsedWorkflowScript {
+  const filename = options.filename ?? "workflow.js";
+  const sourceBytes = Buffer.byteLength(source, "utf8");
+  if (sourceBytes > (options.maxBytes ?? 256 * 1024)) {
+    throw new WorkflowScriptError("WORKFLOW_SOURCE_INVALID", "Workflow script exceeds the source size limit.");
+  }
+
+  const file = ts.createSourceFile(filename, source, ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS);
+  const parseDiagnostics = (file as ts.SourceFile & { parseDiagnostics?: readonly ts.Diagnostic[] }).parseDiagnostics ?? [];
+  const diagnostic = parseDiagnostics[0];
+  if (diagnostic) {
+    const start = diagnostic.start ?? 0;
+    throw new WorkflowScriptError(
+      "WORKFLOW_SYNTAX_ERROR",
+      ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+      locationAt(file, start),
+    );
+  }
+
+  const first = file.statements[0];
+  if (!first || !ts.isVariableStatement(first)
+    || !hasModifier(first, ts.SyntaxKind.ExportKeyword)
+    || !hasModifier(first, ts.SyntaxKind.ConstKeyword)
+    || first.declarationList.declarations.length !== 1) {
+    throw metaError(file, first, "The first statement must be `export const meta = { ... }`.");
+  }
+  const declaration = first.declarationList.declarations[0]!;
+  if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "meta" || !declaration.initializer) {
+    throw metaError(file, declaration, "The first statement must declare `meta`.");
+  }
+
+  let decoded: JsonValue;
+  try {
+    decoded = decodeLiteral(file, declaration.initializer);
+  } catch (error) {
+    if (error instanceof WorkflowScriptError) throw error;
+    throw metaError(file, declaration.initializer, error instanceof Error ? error.message : String(error));
+  }
+
+  let meta;
+  try {
+    meta = validateWorkflowMeta(decoded);
+  } catch (error) {
+    throw metaError(file, declaration.initializer, error instanceof Error ? error.message : String(error));
+  }
+
+  for (const statement of file.statements.slice(1)) {
+    if (ts.isImportDeclaration(statement) || ts.isImportEqualsDeclaration(statement)
+      || ts.isExportAssignment(statement) || hasModifier(statement, ts.SyntaxKind.ExportKeyword)) {
+      throw new WorkflowScriptError(
+        "WORKFLOW_SOURCE_INVALID",
+        "Workflow scripts cannot contain imports or additional exports.",
+        locationAt(file, statement.getStart(file)),
+      );
+    }
+  }
+  visit(file, (node) => {
+    if (node.kind === ts.SyntaxKind.ImportKeyword || ts.isImportTypeNode(node)) {
+      throw new WorkflowScriptError(
+        "WORKFLOW_SOURCE_INVALID",
+        "Workflow scripts cannot import modules.",
+        locationAt(file, node.getStart(file)),
+      );
+    }
+  });
+
+  return {
+    source,
+    body: blankRange(source, first.getStart(file), first.end),
+    meta,
+    filename,
+    sourceBytes,
+  };
+}
+
+export function renameWorkflowMeta(source: string, newName: string, filename = "workflow.js"): string {
+  parseWorkflowScript(source, { filename });
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(newName) || newName.length > 128) {
+    throw new WorkflowScriptError("WORKFLOW_META_INVALID", "Workflow name must be a 1..128 character kebab-case name.");
+  }
+  const file = ts.createSourceFile(filename, source, ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS);
+  const statement = file.statements[0] as ts.VariableStatement;
+  const initializer = statement.declarationList.declarations[0]!.initializer as ts.ObjectLiteralExpression;
+  const property = initializer.properties.find((candidate) =>
+    ts.isPropertyAssignment(candidate) && propertyName(file, candidate.name) === "name");
+  if (!property || !ts.isPropertyAssignment(property)) {
+    throw new WorkflowScriptError("WORKFLOW_META_INVALID", "Workflow metadata must contain a name property.");
+  }
+  const renamed = source.slice(0, property.initializer.getStart(file))
+    + JSON.stringify(newName)
+    + source.slice(property.initializer.end);
+  parseWorkflowScript(renamed, { filename });
+  return renamed;
+}
+
+function decodeLiteral(file: ts.SourceFile, node: ts.Expression): JsonValue {
+  if (ts.isParenthesizedExpression(node)) return decodeLiteral(file, node.expression);
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  if (ts.isNumericLiteral(node)) {
+    const value = Number(node.text);
+    if (!Number.isFinite(value)) throw metaError(file, node, "Metadata numbers must be finite.");
+    return value;
+  }
+  if (ts.isPrefixUnaryExpression(node)
+    && (node.operator === ts.SyntaxKind.MinusToken || node.operator === ts.SyntaxKind.PlusToken)
+    && ts.isNumericLiteral(node.operand)) {
+    const value = Number(`${node.operator === ts.SyntaxKind.MinusToken ? "-" : ""}${node.operand.text}`);
+    if (!Number.isFinite(value)) throw metaError(file, node, "Metadata numbers must be finite.");
+    return value;
+  }
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isArrayLiteralExpression(node)) {
+    if (node.elements.some(ts.isSpreadElement)) throw metaError(file, node, "Metadata arrays cannot contain spreads.");
+    return node.elements.map((element) => decodeLiteral(file, element as ts.Expression));
+  }
+  if (ts.isObjectLiteralExpression(node)) {
+    const object: Record<string, JsonValue> = Object.create(null) as Record<string, JsonValue>;
+    for (const property of node.properties) {
+      if (!ts.isPropertyAssignment(property)) {
+        throw metaError(file, property, "Metadata objects can contain property assignments only.");
+      }
+      const key = propertyName(file, property.name);
+      if (FORBIDDEN_KEYS.has(key)) throw metaError(file, property.name, `Metadata key '${key}' is forbidden.`);
+      if (Object.hasOwn(object, key)) throw metaError(file, property.name, `Duplicate metadata key '${key}'.`);
+      object[key] = decodeLiteral(file, property.initializer);
+    }
+    return object;
+  }
+  throw metaError(file, node, "Metadata must contain literal JSON-compatible values only.");
+}
+
+function propertyName(file: ts.SourceFile, name: ts.PropertyName): string {
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+  throw metaError(file, name, "Computed metadata keys are not allowed.");
+}
+
+function hasModifier(node: ts.Node, kind: ts.SyntaxKind): boolean {
+  if (kind === ts.SyntaxKind.ConstKeyword && ts.isVariableStatement(node)) {
+    return (node.declarationList.flags & ts.NodeFlags.Const) !== 0;
+  }
+  return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) ?? false);
+}
+
+function visit(node: ts.Node, callback: (node: ts.Node) => void): void {
+  callback(node);
+  node.forEachChild((child) => visit(child, callback));
+}
+
+function blankRange(source: string, start: number, end: number): string {
+  return source.slice(0, start) + source.slice(start, end).replace(/[^\r\n]/g, " ") + source.slice(end);
+}
+
+function locationAt(file: ts.SourceFile, offset: number): WorkflowLocation {
+  const location = file.getLineAndCharacterOfPosition(offset);
+  return { line: location.line + 1, column: location.character + 1 };
+}
+
+function metaError(file: ts.SourceFile, node: ts.Node | undefined, message: string): WorkflowScriptError {
+  return new WorkflowScriptError(
+    "WORKFLOW_META_INVALID",
+    message,
+    node ? locationAt(file, node.getStart(file)) : undefined,
+  );
+}
diff --git a/src/workflow-security.test.ts b/src/workflow-security.test.ts
new file mode 100644
index 000000000..5cb250097
--- /dev/null
+++ b/src/workflow-security.test.ts
@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readdir, realpath, rm, symlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { openDatabase } from "./db/client.js";
+import { defaultWorkflowsConfig } from "./workflow-config.js";
+import { createWorkflowManager } from "./workflow-manager.js";
+import { LocalAgentStore } from "./local-agent-store.js";
+import type { LocalAgentManager } from "./local-agent-manager.js";
+import { WorkflowStore } from "./workflow-store.js";
+
+test("inline workflow launch cannot write its artifact through an escaping .devspace symlink", async (t) => {
+  const root = await realpath(await mkdtemp(join(tmpdir(), "workflow-security-")));
+  const project = join(root, "project");
+  const outside = join(root, "outside");
+  await mkdir(project); await mkdir(outside);
+  await symlink(outside, join(project, ".devspace"));
+  const database = openDatabase(join(root, "state"));
+  const agentStore = new LocalAgentStore(database);
+  const manager = createWorkflowManager({
+    stateDir: join(root, "state"), agentStore, store: new WorkflowStore(database),
+    agents: {} as LocalAgentManager,
+    config: { ...defaultWorkflowsConfig(), enabled: true },
+    validateScope: async (scope) => {
+      assert.deepEqual(scope, { workspaceId: "ws-test", workspaceRoot: project }); return scope;
+    },
+  });
+  t.after(async () => { await manager.close(); database.close(); await rm(root, { recursive: true, force: true }); });
+  const result = await manager.request({ operation: "run", scope: { workspaceId: "ws-test", workspaceRoot: project },
+    input: { script: 'export const meta = {name: "escape", description: "Test"}; return null;' } });
+  assert.equal(result.ok, false);
+  assert.deepEqual(await readdir(outside), []);
+  assert.equal(manager.activeRunCount, 0);
+});
diff --git a/src/workflow-store.test.ts b/src/workflow-store.test.ts
new file mode 100644
index 000000000..2a02a5a02
--- /dev/null
+++ b/src/workflow-store.test.ts
@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { WorkflowStore } from "./workflow-store.js";
+
+const root = await mkdtemp(join(tmpdir(), "devspace-workflow-store-"));
+const store = new WorkflowStore(root);
+
+try {
+  const run = store.createRun({
+    workspaceId: "ws", workspaceRoot: root, meta: { name: "store", description: "Store test" },
+    scriptSource: "return null", scriptHash: "hash", argsPresent: false, defaults: {}, policy: {},
+    runtimeVersion: "devspace-workflow/v1", outputTokenBudget: 10,
+  });
+  const step = store.createStep({ runId: run.id, kind: "agent", logicalPath: "0:1",
+    requestHash: "request", request: { prompt: "test" }, workspaceId: "ws" });
+  const attempt = store.createAttempt({ stepId: step.id, agentId: "agt", agentTurnId: 42, reason: "initial" });
+
+  assert.equal(store.recordUsage({ attemptId: attempt.id, sequence: 1, outputTokens: 2, complete: false }).knownOutputTokens, 2);
+  assert.equal(store.recordUsage({ attemptId: attempt.id, sequence: 1, outputTokens: 99, complete: true }).knownOutputTokens, 2,
+    "duplicate provider usage sequence is ignored");
+  const budget = store.recordUsage({ attemptId: attempt.id, sequence: 2, outputTokens: 5, complete: true });
+  assert.equal(budget.knownOutputTokens, 5, "cumulative provider usage is charged by delta");
+  assert.equal(budget.usageComplete, true);
+
+  store.finishAttemptAndStep(attempt.id, "completed", "completed", { output: "done" });
+  store.recordDelivery(step.id, 1);
+  store.transitionRun(run.id, "completed", { result: "done" });
+  const resumed = store.createResumedRun({
+    workspaceId: "ws", workspaceRoot: root, sourceRunId: run.id,
+    meta: run.meta, scriptSource: run.scriptSource, scriptHash: run.scriptHash,
+    argsPresent: false, defaults: {}, policy: {}, runtimeVersion: run.runtimeVersion,
+  });
+  assert.equal(resumed.budgetId, run.budgetId);
+  assert.equal(store.getBudget(resumed.budgetId).knownOutputTokens, 5);
+  assert.throws(() => store.createResumedRun({
+    workspaceId: "ws", workspaceRoot: root, sourceRunId: run.id,
+    meta: run.meta, scriptSource: run.scriptSource, scriptHash: run.scriptHash,
+    argsPresent: false, defaults: {}, policy: {}, runtimeVersion: run.runtimeVersion,
+  }), /unique/i, "one source generation cannot be resumed concurrently twice");
+
+  assert.equal(store.markActiveAttemptsUncertain(), 1);
+  assert.equal(store.getRun(resumed.id)?.state, "recovery_required");
+} finally {
+  store.close();
+  await rm(root, { recursive: true, force: true });
+}
diff --git a/src/workflow-store.ts b/src/workflow-store.ts
new file mode 100644
index 000000000..5ba842c56
--- /dev/null
+++ b/src/workflow-store.ts
@@ -0,0 +1,693 @@
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import type Database from "better-sqlite3";
+import { openDatabase, type DatabaseHandle } from "./db/client.js";
+
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export interface JsonObject { [key: string]: JsonValue }
+
+export type WorkflowState =
+  | "starting" | "running" | "pausing" | "paused"
+  | "waiting_for_permission" | "waiting_for_usage"
+  | "stopping" | "stopped" | "completed" | "failed"
+  | "recovery_required";
+
+export type WorkflowStepState =
+  | "queued" | "starting" | "running" | "waiting_for_permission"
+  | "waiting_for_usage" | "completed" | "failed" | "stopped"
+  | "cached" | "uncertain";
+
+export interface WorkflowError {
+  code: string;
+  message: string;
+  layer: "script" | "workflow" | "workspace" | "adapter" | "provider";
+  retryable: boolean;
+  runId?: string;
+  stepId?: string;
+  agentId?: string;
+  provider?: string;
+  location?: { line: number; column: number };
+}
+
+export interface WorkflowRunRecord {
+  id: string;
+  workspaceId: string;
+  workspaceRoot: string;
+  lineageId: string;
+  budgetId: string;
+  resumedFromRunId?: string;
+  state: WorkflowState;
+  meta: JsonObject;
+  scriptSource: string;
+  scriptHash: string;
+  sourcePath?: string;
+  argsPresent: boolean;
+  args?: JsonValue;
+  defaults: JsonObject;
+  policy: JsonObject;
+  runtimeVersion: string;
+  revision: number;
+  executionGeneration: number;
+  result?: JsonValue;
+  resultArtifactId?: string;
+  error?: WorkflowError;
+  pauseReason?: string;
+  nextEligibleAt?: string;
+  createdAt: string;
+  updatedAt: string;
+  finishedAt?: string;
+}
+
+export interface WorkflowBudgetRecord {
+  id: string;
+  totalOutputTokens: number | null;
+  knownOutputTokens: number;
+  usageComplete: boolean;
+  revision: number;
+}
+
+export interface WorkflowStepRecord {
+  id: string;
+  runId: string;
+  parentStepId?: string;
+  kind: "agent" | "workflow";
+  callSequence: number;
+  logicalPath: string;
+  requestHash: string;
+  request: JsonObject;
+  phase?: string;
+  label?: string;
+  state: WorkflowStepState;
+  agentId?: string;
+  workspaceId: string;
+  cachedFromStepId?: string;
+  output?: JsonValue;
+  error?: WorkflowError;
+  deliverySequence?: number;
+  worktree?: JsonObject;
+  createdAt: string;
+  updatedAt: string;
+  finishedAt?: string;
+}
+
+export interface WorkflowStepSummary {
+  id: string;
+  kind: "agent" | "workflow";
+  label?: string;
+  workspaceId: string;
+  phase?: string;
+  state: WorkflowStepState;
+  worktree?: JsonObject;
+}
+
+export type WorkflowAttemptState = Exclude<WorkflowStepState, "cached">;
+export type WorkflowAttemptReason = "initial" | "schema_repair" | "restart" | "retry";
+
+export interface WorkflowAttemptRecord {
+  id: string;
+  stepId: string;
+  attemptNumber: number;
+  agentId: string;
+  agentTurnId: number;
+  reason: WorkflowAttemptReason;
+  state: WorkflowAttemptState;
+  usageSequence: number;
+  outputTokens?: number;
+  usageComplete: boolean;
+  error?: WorkflowError;
+  createdAt: string;
+  updatedAt: string;
+  finishedAt?: string;
+}
+
+export interface WorkflowEventRecord {
+  runId: string;
+  sequence: number;
+  stepId?: string;
+  type: string;
+  payload: JsonObject;
+  createdAt: string;
+}
+
+export interface CreateWorkflowRunInput {
+  id?: string;
+  workspaceId: string;
+  workspaceRoot: string;
+  meta: JsonObject;
+  scriptSource: string;
+  scriptHash: string;
+  sourcePath?: string;
+  argsPresent: boolean;
+  args?: JsonValue;
+  defaults: JsonObject;
+  policy: JsonObject;
+  runtimeVersion: string;
+  outputTokenBudget?: number;
+}
+
+export interface CreateWorkflowStepInput {
+  id?: string;
+  runId: string;
+  parentStepId?: string;
+  kind: "agent" | "workflow";
+  logicalPath: string;
+  requestHash: string;
+  request: JsonObject;
+  phase?: string;
+  label?: string;
+  workspaceId: string;
+  cachedFromStepId?: string;
+  output?: JsonValue;
+  worktree?: JsonObject;
+}
+
+interface RunRow {
+  id: string; workspace_id: string; workspace_root: string; lineage_id: string; budget_id: string;
+  resumed_from_run_id: string | null; state: string; meta_json: string; script_source: string;
+  script_hash: string; source_path: string | null; args_present: number; args_json: string | null;
+  defaults_json: string; policy_json: string; runtime_version: string; revision: number;
+  execution_generation: number; result_json: string | null; result_artifact_id: string | null;
+  error_json: string | null; pause_reason: string | null; next_eligible_at: string | null;
+  created_at: string; updated_at: string; finished_at: string | null;
+}
+
+interface StepRow {
+  id: string; run_id: string; parent_step_id: string | null; kind: string; call_sequence: number;
+  logical_path: string; request_hash: string; request_json: string; phase: string | null;
+  label: string | null; status: string; agent_id: string | null; workspace_id: string;
+  cached_from_step_id: string | null; output_json: string | null; error_json: string | null;
+  delivery_sequence: number | null; worktree_json: string | null; created_at: string;
+  updated_at: string; finished_at: string | null;
+}
+
+interface AttemptRow {
+  id: string; step_id: string; attempt_number: number; agent_id: string; agent_turn_id: number;
+  reason: string; state: string; usage_sequence: number; output_tokens: number | null;
+  usage_complete: number; error_json: string | null; created_at: string; updated_at: string;
+  finished_at: string | null;
+}
+
+interface EventRow {
+  run_id: string; sequence: number; step_id: string | null; type: string;
+  payload_json: string; created_at: string;
+}
+
+/** Canonical workflow journal. Every guest-visible delivery is persisted here first. */
+export class WorkflowStore {
+  private readonly database: DatabaseHandle;
+  private readonly ownsDatabase: boolean;
+
+  constructor(stateDirOrDatabase: string | DatabaseHandle) {
+    this.database = typeof stateDirOrDatabase === "string" ? openDatabase(stateDirOrDatabase) : stateDirOrDatabase;
+    this.ownsDatabase = typeof stateDirOrDatabase === "string";
+  }
+
+  close(): void {
+    if (this.ownsDatabase) this.database.close();
+  }
+
+  createRun(input: CreateWorkflowRunInput): WorkflowRunRecord {
+    const id = input.id ?? workflowId("wf");
+    const budgetId = workflowId("wfb");
+    const now = new Date().toISOString();
+    this.database.sqlite.transaction(() => {
+      this.database.sqlite.prepare(
+        "insert into workflow_budgets (id, total_output_tokens, known_output_tokens, usage_complete, revision) values (?, ?, 0, 1, 0)",
+      ).run(budgetId, input.outputTokenBudget ?? null);
+      this.insertRun({ ...input, id }, {
+        lineageId: id,
+        budgetId,
+        state: "starting",
+        executionGeneration: 1,
+        now,
+      });
+      this.insertEvent(id, 1, undefined, "run_state", { state: "starting" }, now);
+    }).immediate();
+    return required(this.getRun(id), `Created workflow run ${id} disappeared.`);
+  }
+
+  createResumedRun(input: CreateWorkflowRunInput & { sourceRunId: string }): WorkflowRunRecord {
+    const id = input.id ?? workflowId("wf");
+    const now = new Date().toISOString();
+    this.database.sqlite.transaction(() => {
+      const source = required(this.getRun(input.sourceRunId), `Unknown workflow run: ${input.sourceRunId}`);
+      if (source.workspaceId !== input.workspaceId || source.workspaceRoot !== resolve(input.workspaceRoot)) {
+        throw new Error("RESUME_SCOPE_MISMATCH");
+      }
+      if (!isTerminal(source.state)) throw new Error("WORKFLOW_BUSY");
+      if (source.runtimeVersion !== input.runtimeVersion) throw new Error("RESUME_RUNTIME_INCOMPATIBLE");
+      this.insertRun({ ...input, id }, {
+        lineageId: source.lineageId,
+        budgetId: source.budgetId,
+        resumedFromRunId: source.id,
+        state: "starting",
+        executionGeneration: source.executionGeneration + 1,
+        now,
+      });
+      this.database.sqlite.prepare(
+        "insert into workflow_resume_claims (source_run_id, source_generation, resumed_by_run_id, created_at) values (?, ?, ?, ?)",
+      ).run(source.id, source.executionGeneration, id, now);
+      this.insertEvent(id, 1, undefined, "run_state", { state: "starting", resumedFromRunId: source.id }, now);
+    }).immediate();
+    return required(this.getRun(id), `Created workflow run ${id} disappeared.`);
+  }
+
+  private insertRun(
+    input: CreateWorkflowRunInput & { id: string },
+    derived: {
+      lineageId: string; budgetId: string; resumedFromRunId?: string; state: WorkflowState;
+      executionGeneration: number; now: string;
+    },
+  ): void {
+    this.database.sqlite.prepare(`insert into workflow_runs (
+      id, workspace_id, workspace_root, lineage_id, budget_id, resumed_from_run_id, state,
+      meta_json, script_source, script_hash, source_path, args_present, args_json, defaults_json,
+      policy_json, runtime_version, revision, execution_generation, created_at, updated_at
+    ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?)`)
+      .run(
+        input.id, input.workspaceId, resolve(input.workspaceRoot), derived.lineageId, derived.budgetId,
+        derived.resumedFromRunId ?? null, derived.state, json(input.meta), input.scriptSource,
+        input.scriptHash, input.sourcePath ?? null, Number(input.argsPresent),
+        input.argsPresent ? json(input.args ?? null) : null, json(input.defaults), json(input.policy),
+        input.runtimeVersion, derived.executionGeneration, derived.now, derived.now,
+      );
+  }
+
+  getRun(id: string): WorkflowRunRecord | undefined {
+    const row = this.database.sqlite.prepare("select * from workflow_runs where id = ?").get(id) as RunRow | undefined;
+    return row ? runFromRow(row) : undefined;
+  }
+
+  getRunForWorkspace(id: string, workspaceId: string): WorkflowRunRecord | undefined {
+    const run = this.getRun(id);
+    return run?.workspaceId === workspaceId ? run : undefined;
+  }
+
+  listRuns(workspaceId: string, limit = 20, before?: { updatedAt: string; id: string }): WorkflowRunRecord[] {
+    const rows = before
+      ? this.database.sqlite.prepare(`select * from workflow_runs where workspace_id = ?
+          and (updated_at < ? or (updated_at = ? and id < ?))
+          order by updated_at desc, id desc limit ?`)
+        .all(workspaceId, before.updatedAt, before.updatedAt, before.id, limit)
+      : this.database.sqlite.prepare(
+        "select * from workflow_runs where workspace_id = ? order by updated_at desc, id desc limit ?",
+      ).all(workspaceId, limit);
+    return (rows as RunRow[]).map(runFromRow);
+  }
+
+  listLiveRuns(): WorkflowRunRecord[] {
+    return (this.database.sqlite.prepare(`select * from workflow_runs where state not in
+      ('completed', 'failed', 'stopped', 'recovery_required') order by created_at`).all() as RunRow[])
+      .map(runFromRow);
+  }
+
+  transitionRun(
+    runId: string,
+    state: WorkflowState,
+    options: { expected?: readonly WorkflowState[]; reason?: string; error?: WorkflowError; result?: JsonValue; omittedResult?: boolean } = {},
+  ): WorkflowRunRecord {
+    return this.database.sqlite.transaction(() => {
+      const run = required(this.getRun(runId), `Unknown workflow run: ${runId}`);
+      if (options.expected && !options.expected.includes(run.state)) throw new Error("WORKFLOW_BUSY");
+      const now = new Date().toISOString();
+      const terminal = isTerminal(state);
+      const resultJson = Object.hasOwn(options, "result") ? json(options.result ?? null) : null;
+      const revision = run.revision + 1;
+      this.database.sqlite.prepare(`update workflow_runs set state = ?, revision = ?, updated_at = ?,
+        finished_at = ?, result_json = coalesce(?, result_json), error_json = coalesce(?, error_json),
+        pause_reason = ? where id = ?`)
+        .run(state, revision, now, terminal ? now : null, resultJson,
+          options.error ? json(options.error) : null, state === "paused" ? options.reason ?? null : null, runId);
+      this.insertEvent(runId, revision, undefined, "run_state", {
+        state,
+        ...(options.reason ? { reason: options.reason } : {}),
+        ...(options.omittedResult ? { omittedResult: true } : {}),
+      }, now);
+      return required(this.getRun(runId), `Workflow run ${runId} disappeared.`);
+    }).immediate();
+  }
+
+  appendEvent(runId: string, type: string, payload: JsonObject, stepId?: string): WorkflowEventRecord {
+    return this.database.sqlite.transaction(() => {
+      const run = required(this.getRun(runId), `Unknown workflow run: ${runId}`);
+      const sequence = run.revision + 1;
+      const now = new Date().toISOString();
+      this.database.sqlite.prepare("update workflow_runs set revision = ?, updated_at = ? where id = ?")
+        .run(sequence, now, runId);
+      this.insertEvent(runId, sequence, stepId, type, payload, now);
+      return { runId, sequence, stepId, type, payload, createdAt: now };
+    }).immediate();
+  }
+
+  setNextEligibleAt(runId: string, nextEligibleAt?: string): void {
+    this.database.sqlite.transaction(() => {
+      const run = required(this.getRun(runId), `Unknown workflow run: ${runId}`);
+      const sequence = run.revision + 1;
+      const now = new Date().toISOString();
+      this.database.sqlite.prepare(`update workflow_runs set next_eligible_at = ?, revision = ?, updated_at = ?
+        where id = ?`).run(nextEligibleAt ?? null, sequence, now, runId);
+      this.insertEvent(runId, sequence, undefined, "usage_gate",
+        nextEligibleAt ? { nextEligibleAt } : { cleared: true }, now);
+    }).immediate();
+  }
+
+  private insertEvent(
+    runId: string, sequence: number, stepId: string | undefined, type: string, payload: JsonObject, now: string,
+  ): void {
+    this.database.sqlite.prepare(
+      "insert into workflow_events (run_id, sequence, step_id, type, payload_json, created_at) values (?, ?, ?, ?, ?, ?)",
+    ).run(runId, sequence, stepId ?? null, type, json(payload), now);
+  }
+
+  listEvents(runId: string, afterSequence = 0, limit = 1_000): WorkflowEventRecord[] {
+    return (this.database.sqlite.prepare(
+      "select * from workflow_events where run_id = ? and sequence > ? order by sequence limit ?",
+    ).all(runId, afterSequence, limit) as EventRow[]).map(eventFromRow);
+  }
+
+  hasPartialExecution(runId: string): boolean {
+    return Boolean(this.database.sqlite.prepare(`select 1 from workflow_events
+      where run_id = ? and (type = 'combinator_error'
+        or (type = 'warning' and json_extract(payload_json, '$.code') = 'PARTIAL_EXECUTION'))
+      limit 1`).get(runId));
+  }
+
+  createStep(input: CreateWorkflowStepInput): WorkflowStepRecord {
+    return this.database.sqlite.transaction(() => {
+      const run = required(this.getRun(input.runId), `Unknown workflow run: ${input.runId}`);
+      const stepId = input.id ?? workflowId("wfs");
+      const callSequence = (this.database.sqlite.prepare(
+        "select coalesce(max(call_sequence), 0) + 1 as value from workflow_steps where run_id = ?",
+      ).get(input.runId) as { value: number }).value;
+      const state: WorkflowStepState = input.cachedFromStepId ? "cached" : "queued";
+      const now = new Date().toISOString();
+      this.database.sqlite.prepare(`insert into workflow_steps (
+        id, run_id, parent_step_id, kind, call_sequence, logical_path, request_hash, request_json,
+        phase, label, status, workspace_id, cached_from_step_id, output_json, worktree_json,
+        created_at, updated_at, finished_at
+      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(stepId, input.runId, input.parentStepId ?? null, input.kind, callSequence,
+          input.logicalPath, input.requestHash, json(input.request), input.phase ?? null,
+          input.label ?? null, state, input.workspaceId, input.cachedFromStepId ?? null,
+          Object.hasOwn(input, "output") ? json(input.output ?? null) : null,
+          input.worktree ? json(input.worktree) : null, now, now, state === "cached" ? now : null);
+      const revision = run.revision + 1;
+      this.database.sqlite.prepare("update workflow_runs set revision = ?, updated_at = ? where id = ?")
+        .run(revision, now, input.runId);
+      this.insertEvent(input.runId, revision, stepId, "step_state", { state }, now);
+      return required(this.getStep(stepId), `Created workflow step ${stepId} disappeared.`);
+    }).immediate();
+  }
+
+  getStep(id: string): WorkflowStepRecord | undefined {
+    const row = this.database.sqlite.prepare("select * from workflow_steps where id = ?").get(id) as StepRow | undefined;
+    return row ? stepFromRow(row) : undefined;
+  }
+
+  listSteps(runId: string): WorkflowStepRecord[] {
+    return (this.database.sqlite.prepare(
+      "select * from workflow_steps where run_id = ? order by call_sequence",
+    ).all(runId) as StepRow[]).map(stepFromRow);
+  }
+
+  listStepSummaries(runId: string): WorkflowStepSummary[] {
+    return (this.database.sqlite.prepare(
+      `select id, kind, label, workspace_id, phase, status, worktree_json
+        from workflow_steps where run_id = ? order by call_sequence`,
+    ).all(runId) as Array<{ id: string; kind: string; label: string | null; workspace_id: string;
+      phase: string | null; status: string; worktree_json: string | null }>).map((row) => ({
+      id: row.id,
+      kind: row.kind as "agent" | "workflow",
+      ...(row.label ? { label: row.label } : {}),
+      workspaceId: row.workspace_id,
+      ...(row.phase ? { phase: row.phase } : {}),
+      state: row.status as WorkflowStepState,
+      ...(row.worktree_json ? { worktree: parse(row.worktree_json) as JsonObject } : {}),
+    }));
+  }
+
+  updateStepWorktree(stepId: string, worktree: JsonObject): void {
+    this.database.sqlite.transaction(() => {
+      const step = required(this.getStep(stepId), `Unknown workflow step: ${stepId}`);
+      const run = required(this.getRun(step.runId), `Unknown workflow run: ${step.runId}`);
+      const sequence = run.revision + 1;
+      const now = new Date().toISOString();
+      this.database.sqlite.prepare(
+        "update workflow_steps set worktree_json = ?, updated_at = ? where id = ?",
+      ).run(json(worktree), now, stepId);
+      this.database.sqlite.prepare("update workflow_runs set revision = ?, updated_at = ? where id = ?")
+        .run(sequence, now, run.id);
+      this.insertEvent(run.id, sequence, stepId, "worktree", worktree, now);
+    }).immediate();
+  }
+
+  setResultArtifactId(runId: string, artifactId: string): void {
+    this.database.sqlite.prepare(
+      "update workflow_runs set result_artifact_id = ? where id = ? and result_artifact_id is null",
+    ).run(artifactId, runId);
+  }
+
+  findReplayPrefix(sourceRunId: string): WorkflowStepRecord[] {
+    const rows = this.listSteps(sourceRunId);
+    const boundary = rows.findIndex((step) => !["completed", "cached"].includes(step.state));
+    return boundary < 0 ? rows : rows.slice(0, boundary);
+  }
+
+  transitionStep(
+    stepId: string,
+    state: WorkflowStepState,
+    patch: { agentId?: string; output?: JsonValue; error?: WorkflowError; deliverySequence?: number; worktree?: JsonObject } = {},
+  ): WorkflowStepRecord {
+    return this.database.sqlite.transaction(() => {
+      const step = required(this.getStep(stepId), `Unknown workflow step: ${stepId}`);
+      const run = required(this.getRun(step.runId), `Unknown workflow run: ${step.runId}`);
+      const now = new Date().toISOString();
+      const terminal = isStepTerminal(state);
+      this.database.sqlite.prepare(`update workflow_steps set status = ?, agent_id = coalesce(?, agent_id),
+        output_json = coalesce(?, output_json), error_json = coalesce(?, error_json),
+        delivery_sequence = coalesce(?, delivery_sequence), worktree_json = coalesce(?, worktree_json),
+        updated_at = ?, finished_at = ? where id = ?`)
+        .run(state, patch.agentId ?? null,
+          Object.hasOwn(patch, "output") ? json(patch.output ?? null) : null,
+          patch.error ? json(patch.error) : null, patch.deliverySequence ?? null,
+          patch.worktree ? json(patch.worktree) : null, now, terminal ? now : null, stepId);
+      const revision = run.revision + 1;
+      this.database.sqlite.prepare("update workflow_runs set revision = ?, updated_at = ? where id = ?")
+        .run(revision, now, run.id);
+      this.insertEvent(run.id, revision, stepId, "step_state", { state }, now);
+      return required(this.getStep(stepId), `Workflow step ${stepId} disappeared.`);
+    }).immediate();
+  }
+
+  recordDelivery(stepId: string, deliverySequence: number): WorkflowStepRecord {
+    this.database.sqlite.prepare(
+      "update workflow_steps set delivery_sequence = ?, updated_at = ? where id = ? and delivery_sequence is null",
+    ).run(deliverySequence, new Date().toISOString(), stepId);
+    return required(this.getStep(stepId), `Unknown workflow step: ${stepId}`);
+  }
+
+  createAttempt(input: {
+    id?: string; stepId: string; agentId: string; agentTurnId: number; reason: WorkflowAttemptReason;
+  }): WorkflowAttemptRecord {
+    const attemptId = input.id ?? workflowId("wfa");
+    const now = new Date().toISOString();
+    const attemptNumber = (this.database.sqlite.prepare(
+      "select coalesce(max(attempt_number), 0) + 1 as value from workflow_attempts where step_id = ?",
+    ).get(input.stepId) as { value: number }).value;
+    this.database.sqlite.prepare(`insert into workflow_attempts (
+      id, step_id, attempt_number, agent_id, agent_turn_id, reason, state, created_at, updated_at
+    ) values (?, ?, ?, ?, ?, ?, 'starting', ?, ?)`)
+      .run(attemptId, input.stepId, attemptNumber, input.agentId, input.agentTurnId, input.reason, now, now);
+    return required(this.getAttempt(attemptId), `Created workflow attempt ${attemptId} disappeared.`);
+  }
+
+  getAttempt(id: string): WorkflowAttemptRecord | undefined {
+    const row = this.database.sqlite.prepare("select * from workflow_attempts where id = ?").get(id) as AttemptRow | undefined;
+    return row ? attemptFromRow(row) : undefined;
+  }
+
+  listAttempts(stepId: string): WorkflowAttemptRecord[] {
+    return (this.database.sqlite.prepare(
+      "select * from workflow_attempts where step_id = ? order by attempt_number",
+    ).all(stepId) as AttemptRow[]).map(attemptFromRow);
+  }
+
+  listAttemptsForRun(runId: string): WorkflowAttemptRecord[] {
+    return (this.database.sqlite.prepare(`select a.* from workflow_attempts a
+      join workflow_steps s on s.id = a.step_id where s.run_id = ?
+      order by s.call_sequence, a.attempt_number`).all(runId) as AttemptRow[]).map(attemptFromRow);
+  }
+
+  countAttempts(runId: string): number {
+    return (this.database.sqlite.prepare(`select count(*) as count from workflow_attempts a
+      join workflow_steps s on s.id = a.step_id where s.run_id = ?`).get(runId) as { count: number }).count;
+  }
+
+  transitionAttempt(id: string, state: WorkflowAttemptState, error?: WorkflowError): WorkflowAttemptRecord {
+    const now = new Date().toISOString();
+    this.database.sqlite.prepare(`update workflow_attempts set state = ?, error_json = coalesce(?, error_json),
+      updated_at = ?, finished_at = ? where id = ?`)
+      .run(state, error ? json(error) : null, now, isAttemptTerminal(state) ? now : null, id);
+    return required(this.getAttempt(id), `Unknown workflow attempt: ${id}`);
+  }
+
+  finishAttemptAndStep(
+    attemptId: string,
+    attemptState: Extract<WorkflowAttemptState, "completed" | "failed" | "stopped" | "uncertain">,
+    stepState: Extract<WorkflowStepState, "completed" | "failed" | "stopped" | "uncertain">,
+    patch: { output?: JsonValue; error?: WorkflowError } = {},
+  ): WorkflowStepRecord {
+    return this.database.sqlite.transaction(() => {
+      const attempt = this.transitionAttempt(attemptId, attemptState, patch.error);
+      return this.transitionStep(attempt.stepId, stepState, patch);
+    }).immediate();
+  }
+
+  recordUsage(input: {
+    attemptId: string; sequence: number; outputTokens?: number; complete: boolean;
+  }): WorkflowBudgetRecord {
+    return this.database.sqlite.transaction(() => {
+      const attempt = required(this.getAttempt(input.attemptId), `Unknown workflow attempt: ${input.attemptId}`);
+      const step = required(this.getStep(attempt.stepId), `Unknown workflow step: ${attempt.stepId}`);
+      const run = required(this.getRun(step.runId), `Unknown workflow run: ${step.runId}`);
+      if (input.sequence <= attempt.usageSequence) return this.getBudget(run.budgetId);
+      const previous = attempt.outputTokens ?? 0;
+      const next = input.outputTokens;
+      if (next !== undefined && next < previous) throw new Error("Usage output tokens cannot decrease.");
+      this.database.sqlite.prepare(`update workflow_attempts set usage_sequence = ?, output_tokens = ?,
+        usage_complete = ?, updated_at = ? where id = ?`)
+        .run(input.sequence, next ?? null, Number(input.complete), new Date().toISOString(), input.attemptId);
+      this.database.sqlite.prepare(`update workflow_budgets set
+        known_output_tokens = known_output_tokens + ?,
+        usage_complete = usage_complete and ?, revision = revision + 1 where id = ?`)
+        .run(next === undefined ? 0 : next - previous, Number(next !== undefined), run.budgetId);
+      return this.getBudget(run.budgetId);
+    }).immediate();
+  }
+
+  getBudget(id: string): WorkflowBudgetRecord {
+    const row = required(this.database.sqlite.prepare("select * from workflow_budgets where id = ?").get(id) as {
+      id: string; total_output_tokens: number | null; known_output_tokens: number;
+      usage_complete: number; revision: number;
+    } | undefined, `Unknown workflow budget: ${id}`);
+    return {
+      id: row.id,
+      totalOutputTokens: row.total_output_tokens,
+      knownOutputTokens: row.known_output_tokens,
+      usageComplete: Boolean(row.usage_complete),
+      revision: row.revision,
+    };
+  }
+
+  markActiveAttemptsUncertain(message = "Daemon restarted while the provider attempt was active."): number {
+    return this.database.sqlite.transaction(() => {
+      const liveRunIds = (this.database.sqlite.prepare(`select id from workflow_runs where state not in
+        ('completed', 'failed', 'stopped', 'recovery_required')`).all() as Array<{ id: string }>).map((row) => row.id);
+      const active = this.database.sqlite.prepare(`select a.id, s.id as step_id, s.run_id
+        from workflow_attempts a join workflow_steps s on s.id = a.step_id
+        where a.state in ('queued', 'starting', 'running', 'waiting_for_permission', 'waiting_for_usage')`)
+        .all() as Array<{ id: string; step_id: string; run_id: string }>;
+      for (const item of active) {
+        const error: WorkflowError = { code: "RECOVERY_REQUIRED", message, layer: "workflow", retryable: false };
+        this.database.sqlite.prepare(
+          "update workflow_attempts set state = 'uncertain', error_json = ?, updated_at = ? where id = ?",
+        ).run(json(error), new Date().toISOString(), item.id);
+        this.database.sqlite.prepare(
+          "update workflow_steps set status = 'uncertain', error_json = ?, updated_at = ? where id = ?",
+        ).run(json(error), new Date().toISOString(), item.step_id);
+      }
+      for (const runId of liveRunIds) {
+        const error: WorkflowError = { code: "RECOVERY_REQUIRED", message, layer: "workflow", retryable: false };
+        this.transitionRun(runId, "recovery_required", { error });
+      }
+      return liveRunIds.length;
+    }).immediate();
+  }
+
+  countSteps(runId: string): Record<"requested" | "queued" | "running" | "completed" | "failed" | "stopped" | "cached", number> {
+    const counts = { requested: 0, queued: 0, running: 0, completed: 0, failed: 0, stopped: 0, cached: 0 };
+    const rows = this.database.sqlite.prepare(
+      "select status, count(*) as count from workflow_steps where run_id = ? group by status",
+    ).all(runId) as Array<{ status: WorkflowStepState; count: number }>;
+    for (const row of rows) {
+      counts.requested += row.count;
+      if (row.status in counts) counts[row.status as keyof typeof counts] += row.count;
+      else if (["starting", "running", "waiting_for_permission", "waiting_for_usage"].includes(row.status)) counts.running += row.count;
+      else if (row.status === "uncertain") counts.failed += row.count;
+    }
+    return counts;
+  }
+}
+
+function runFromRow(row: RunRow): WorkflowRunRecord {
+  return compact({
+    id: row.id, workspaceId: row.workspace_id, workspaceRoot: row.workspace_root,
+    lineageId: row.lineage_id, budgetId: row.budget_id,
+    resumedFromRunId: row.resumed_from_run_id ?? undefined, state: row.state as WorkflowState,
+    meta: parse(row.meta_json), scriptSource: row.script_source, scriptHash: row.script_hash,
+    sourcePath: row.source_path ?? undefined, argsPresent: Boolean(row.args_present),
+    args: row.args_present ? parse(row.args_json!) : undefined, defaults: parse(row.defaults_json),
+    policy: parse(row.policy_json), runtimeVersion: row.runtime_version, revision: row.revision,
+    executionGeneration: row.execution_generation,
+    result: row.result_json === null ? undefined : parse(row.result_json),
+    resultArtifactId: row.result_artifact_id ?? undefined,
+    error: row.error_json === null ? undefined : parse(row.error_json),
+    pauseReason: row.pause_reason ?? undefined, nextEligibleAt: row.next_eligible_at ?? undefined,
+    createdAt: row.created_at, updatedAt: row.updated_at, finishedAt: row.finished_at ?? undefined,
+  }) as unknown as WorkflowRunRecord;
+}
+
+function stepFromRow(row: StepRow): WorkflowStepRecord {
+  return compact({
+    id: row.id, runId: row.run_id, parentStepId: row.parent_step_id ?? undefined,
+    kind: row.kind as "agent" | "workflow", callSequence: row.call_sequence,
+    logicalPath: row.logical_path, requestHash: row.request_hash, request: parse(row.request_json),
+    phase: row.phase ?? undefined, label: row.label ?? undefined, state: row.status as WorkflowStepState,
+    agentId: row.agent_id ?? undefined, workspaceId: row.workspace_id,
+    cachedFromStepId: row.cached_from_step_id ?? undefined,
+    output: row.output_json === null ? undefined : parse(row.output_json),
+    error: row.error_json === null ? undefined : parse(row.error_json),
+    deliverySequence: row.delivery_sequence ?? undefined,
+    worktree: row.worktree_json === null ? undefined : parse(row.worktree_json),
+    createdAt: row.created_at, updatedAt: row.updated_at, finishedAt: row.finished_at ?? undefined,
+  }) as unknown as WorkflowStepRecord;
+}
+
+function attemptFromRow(row: AttemptRow): WorkflowAttemptRecord {
+  return compact({
+    id: row.id, stepId: row.step_id, attemptNumber: row.attempt_number, agentId: row.agent_id,
+    agentTurnId: row.agent_turn_id, reason: row.reason as WorkflowAttemptReason,
+    state: row.state as WorkflowAttemptState, usageSequence: row.usage_sequence,
+    outputTokens: row.output_tokens ?? undefined, usageComplete: Boolean(row.usage_complete),
+    error: row.error_json === null ? undefined : parse(row.error_json), createdAt: row.created_at,
+    updatedAt: row.updated_at, finishedAt: row.finished_at ?? undefined,
+  }) as unknown as WorkflowAttemptRecord;
+}
+
+function eventFromRow(row: EventRow): WorkflowEventRecord {
+  return compact({ runId: row.run_id, sequence: row.sequence, stepId: row.step_id ?? undefined,
+    type: row.type, payload: parse(row.payload_json), createdAt: row.created_at }) as unknown as WorkflowEventRecord;
+}
+
+function isTerminal(state: WorkflowState): boolean {
+  return ["completed", "failed", "stopped", "recovery_required"].includes(state);
+}
+
+function isStepTerminal(state: WorkflowStepState): boolean {
+  return ["completed", "failed", "stopped", "cached", "uncertain"].includes(state);
+}
+
+function isAttemptTerminal(state: WorkflowAttemptState): boolean {
+  return ["completed", "failed", "stopped", "uncertain"].includes(state);
+}
+
+function workflowId(prefix: string): string {
+  return `${prefix}_${randomUUID().replaceAll("-", "").slice(0, 16)}`;
+}
+
+function json(value: unknown): string { return JSON.stringify(value); }
+function parse(value: string): any { return JSON.parse(value); }
+function required<T>(value: T | undefined, message: string): T { if (value === undefined) throw new Error(message); return value; }
+function compact(value: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
diff --git a/src/workflow-tools.test.ts b/src/workflow-tools.test.ts
new file mode 100644
index 000000000..ce83fc0d3
--- /dev/null
+++ b/src/workflow-tools.test.ts
@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "./config.js";
+import type { WorkspaceRegistry } from "./workspaces.js";
+import { defaultWorkflowsConfig } from "./workflow-config.js";
+import { parseWorkflowCli } from "./workflow-cli.js";
+import { decodeWorkflowReply, decodeWorkflowRequest, type WorkflowRequest } from "./workflow-protocol.js";
+import { registerWorkflowTools } from "./workflow-tools.js";
+
+test("workflow MCP tools publish snake_case schemas and preserve arbitrary JSON argument keys", async (t) => {
+  const server = new McpServer({ name: "workflow-test", version: "1" });
+  const client = new Client({ name: "workflow-test-client", version: "1" });
+  const requests: WorkflowRequest[] = [];
+  registerWorkflowTools({
+    server,
+    config: { workflows: { ...defaultWorkflowsConfig(), enabled: true } } as ServerConfig,
+    workspaces: { getWorkspace: async (id: string) => {
+      assert.equal(id, "ws-test"); return { root: "/approved/project" };
+    } } as WorkspaceRegistry,
+    request: async (input) => { requests.push(input); return { ok: true, result: { runId: "run-test" } }; },
+  });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+  t.after(async () => { await client.close(); await server.close(); });
+  const { tools } = await client.listTools();
+  assert.deepEqual(tools.map(({ name }) => name).sort(), ["control_workflow", "get_workflow", "list_workflows", "run_workflow", "save_workflow", "wait_workflow"]);
+  for (const tool of tools) {
+    assert.ok(Object.keys(tool.inputSchema.properties ?? {}).every((key) => /^[a-z][a-z0-9_]*$/.test(key)));
+  }
+  const result = await client.callTool({ name: "run_workflow", arguments: {
+    workspace_id: "ws-test", script: "source", agent_type: "reviewer", args: { fileName: "example.ts" },
+  } });
+  assert.equal(result.isError, undefined);
+  assert.deepEqual(requests[0], { operation: "run", scope: { workspaceId: "ws-test", workspaceRoot: "/approved/project" },
+    input: { script: "source", agentType: "reviewer", args: { fileName: "example.ts" } } });
+  const invalid = await client.callTool({ name: "control_workflow", arguments: {
+    workspace_id: "ws-test", run_id: "run-test", action: "restart_agent",
+  } });
+  assert.equal(invalid.isError, true);
+  assert.equal(requests.length, 1);
+});
+
+test("workflow protocol and CLI reject invalid controls and ignored flags", () => {
+  const failure = { ok: false, error: { code: "WORKFLOW_FAILED", message: "Provider failed", retryable: false,
+    layer: "provider", runId: "run", stepId: "step", agentId: "agent", provider: "example", location: { line: 3, column: 2 } } };
+  assert.deepEqual(decodeWorkflowReply(failure), failure);
+  const scope = { workspaceId: "w", workspaceRoot: "/project" };
+  assert.throws(() => decodeWorkflowRequest({ operation: "run", scope, input: {} }), /Provide/);
+  assert.throws(() => decodeWorkflowRequest({ operation: "control", scope,
+    input: { runId: "r", action: "stop", stepId: "s" } }), /stepId/);
+  assert.throws(() => parseWorkflowCli(["show", "r", "--budget", "2"]), /not valid/);
+  assert.throws(() => parseWorkflowCli(["run", "a.js", "extra"]), /Unexpected/);
+  const parsed = parseWorkflowCli(["wait", "r", "--timeout", "2", "--after-revision", "3", "--json"]);
+  assert.deepEqual(parsed, { operation: "wait", input: { runId: "r", timeoutMs: 2000, afterRevision: 3 }, json: true });
+  assert.throws(() => decodeWorkflowRequest({ operation: "wait", scope, input: { runId: "r", timeoutMs: NaN } }));
+});
diff --git a/src/workflow-tools.ts b/src/workflow-tools.ts
new file mode 100644
index 000000000..90366b6fc
--- /dev/null
+++ b/src/workflow-tools.ts
@@ -0,0 +1,59 @@
+import * as z from "zod/v4";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "./config.js";
+import type { WorkspaceRegistry } from "./workspaces.js";
+import { createLocalAgentClient } from "./local-agent-client.js";
+import { decodeWorkflowRequest, workflowInputs, type WorkflowOperation, type WorkflowReply, type WorkflowRequest } from "./workflow-protocol.js";
+
+const publicKey = (key: string) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+const descriptions: Record<WorkflowOperation, string> = {
+  run: "Run a JavaScript workflow that coordinates configured subagents in this workspace. Supply script, script_path, or a saved name. Returns a run ID immediately; use wait_workflow for the result. Read the workflows skill for script primitives. Use resume_from_run_id to replay a stopped prior run.",
+  get: "Inspect a workflow's status and result, or one step's details. Reuse the workspace and run ID returned at launch.",
+  wait: "Wait for workflow progress, completion, or required attention. Pass the last revision to wait for a change. A timeout or disconnected wait does not cancel the workflow.",
+  control: "Pause, resume, or stop a workflow. Supply step_id only to stop or restart an individual agent; restart is allowed before its result has been delivered.",
+  list: "List saved workflow definitions or previous runs in this workspace.",
+  save: "Save a workflow's script as a reusable project or personal definition. Existing names require explicit replace=true.",
+};
+
+export function registerWorkflowTools(options: {
+  server: Pick<McpServer, "registerTool">;
+  config: ServerConfig;
+  workspaces: WorkspaceRegistry;
+  request?: (request: WorkflowRequest) => Promise<WorkflowReply>;
+}): void {
+  if (!options.config.workflows?.enabled) return;
+  const request = options.request ?? ((input) => createLocalAgentClient(options.config).workflow(input));
+  for (const operation of Object.keys(workflowInputs) as WorkflowOperation[]) {
+    const schema = z.object({
+      workspace_id: z.string().min(1).describe("Reuse the current workspace_id."),
+      ...Object.fromEntries(Object.entries(workflowInputs[operation].shape).map(([key, schema]) => [publicKey(key), schema])),
+    }).strict();
+    options.server.registerTool(`${operation}_workflow${operation === "list" ? "s" : ""}`, {
+      description: descriptions[operation],
+      inputSchema: schema,
+      annotations: {
+        readOnlyHint: operation === "get" || operation === "wait" || operation === "list",
+        destructiveHint: operation === "run" || operation === "control",
+        openWorldHint: operation === "run",
+      },
+    }, async (value) => {
+      try {
+        const { workspace_id: workspaceId, ...publicInput } = value;
+        const input = Object.fromEntries(Object.keys(workflowInputs[operation].shape)
+          .filter((key) => Object.hasOwn(publicInput, publicKey(key)))
+          .map((key) => [key, (publicInput as Record<string, unknown>)[publicKey(key)]]));
+        const workspace = await options.workspaces.getWorkspace(workspaceId);
+        const reply = await request(decodeWorkflowRequest({
+          operation, scope: { workspaceId, workspaceRoot: workspace.root }, input,
+        }));
+        return {
+          ...(reply.ok ? {} : { isError: true }),
+          content: [{ type: "text" as const, text: JSON.stringify(reply.ok ? reply.result : reply.error) }],
+          structuredContent: reply.ok ? { result: reply.result } : { error: reply.error },
+        };
+      } catch (error) {
+        return { isError: true, content: [{ type: "text" as const, text: error instanceof Error ? error.message : "Invalid workflow request." }] };
+      }
+    });
+  }
+}
diff --git a/src/workflow-types.ts b/src/workflow-types.ts
new file mode 100644
index 000000000..c28e7fe03
--- /dev/null
+++ b/src/workflow-types.ts
@@ -0,0 +1,178 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export type JsonObject = { [key: string]: JsonValue };
+export type JsonSchema = JsonObject | boolean;
+
+export interface WorkflowMeta {
+  name: string;
+  description: string;
+  whenToUse?: string;
+  phases?: Array<{ title: string; detail?: string; model?: string }>;
+}
+
+export interface AgentOptions {
+  label?: string;
+  phase?: string;
+  schema?: JsonSchema;
+  model?: string;
+  effort?: string;
+  isolation?: "worktree";
+  agentType?: string;
+}
+
+export interface WorkflowLocation {
+  line: number;
+  column: number;
+}
+
+export interface WorkflowError {
+  code: string;
+  message: string;
+  layer: "script" | "workflow" | "workspace" | "adapter" | "provider";
+  retryable: boolean;
+  runId?: string;
+  stepId?: string;
+  agentId?: string;
+  provider?: string;
+  location?: WorkflowLocation;
+}
+
+export interface ParsedWorkflowScript {
+  source: string;
+  body: string;
+  meta: WorkflowMeta;
+  filename: string;
+  sourceBytes: number;
+}
+
+export interface WorkflowBudgetSnapshot {
+  total: number | null;
+  knownSpent: number;
+  complete: boolean;
+}
+
+export interface WorkflowRuntimeLimits {
+  argsBytes: number;
+  promptBytes: number;
+  schemaBytes: number;
+  schemaDepth: number;
+  agentResultBytes: number;
+  runResultBytes: number;
+  guestHeapBytes: number;
+  guestStackBytes: number;
+  guestSliceMs: number;
+  guestTotalCpuMs: number;
+  runActiveMs: number;
+  logMessageBytes: number;
+  logTotalBytes: number;
+  eventsPerRun: number;
+  maxAgents: number;
+  maxAttempts: number;
+  maxNestedWorkflows: number;
+  maxPendingRequests: number;
+  maxCombinatorItems: number;
+}
+
+export const DEFAULT_WORKFLOW_RUNTIME_LIMITS: WorkflowRuntimeLimits = {
+  argsBytes: 1024 * 1024,
+  promptBytes: 1024 * 1024,
+  schemaBytes: 128 * 1024,
+  schemaDepth: 64,
+  agentResultBytes: 4 * 1024 * 1024,
+  runResultBytes: 16 * 1024 * 1024,
+  guestHeapBytes: 64 * 1024 * 1024,
+  guestStackBytes: 1024 * 1024,
+  guestSliceMs: 1_000,
+  guestTotalCpuMs: 30_000,
+  runActiveMs: 6 * 60 * 60 * 1_000,
+  logMessageBytes: 8 * 1024,
+  logTotalBytes: 1024 * 1024,
+  eventsPerRun: 100_000,
+  maxAgents: 1_000,
+  maxAttempts: 5_000,
+  maxNestedWorkflows: 1_000,
+  maxPendingRequests: 4_096,
+  maxCombinatorItems: 4_096,
+};
+
+export interface WorkflowBridgeContext {
+  generation: number;
+  requestId: number;
+  signal: AbortSignal;
+}
+
+export interface WorkflowAgentRequest {
+  prompt: string;
+  options: AgentOptions;
+  phase?: string;
+  location?: WorkflowLocation;
+}
+
+export interface WorkflowNestedRequest {
+  reference: string | { scriptPath: string };
+  argsPresent: boolean;
+  args?: JsonValue;
+  phase?: string;
+  location?: WorkflowLocation;
+}
+
+export type WorkflowRuntimeEvent =
+  | { type: "phase"; title: string; replayed: boolean }
+  | { type: "log"; message: string; replayed: boolean }
+  | { type: "combinator_error"; combinator: "parallel" | "pipeline"; index: number; error: WorkflowError }
+  | { type: "budget_observation"; getter: "spent" | "remaining"; observationIndex: number;
+      value: number | "Infinity"; location?: WorkflowLocation; replayed: boolean }
+  | { type: "replay_diverged"; reason: string }
+  | { type: "delivery"; requestId: number; deliverySequence: number; replayed: boolean };
+
+export interface WorkflowBridgeReply {
+  value: JsonValue;
+  budget?: WorkflowBudgetSnapshot;
+  replayed?: boolean;
+}
+
+export interface WorkflowRuntimeCallbacks {
+  agent(request: WorkflowAgentRequest, context: WorkflowBridgeContext): Promise<WorkflowBridgeReply>;
+  workflow(request: WorkflowNestedRequest, context: WorkflowBridgeContext): Promise<WorkflowBridgeReply>;
+  event(event: WorkflowRuntimeEvent): void | Promise<void>;
+  control?(point: "before_request" | "before_delivery"): Promise<void>;
+  budget?(): WorkflowBudgetSnapshot;
+  nextDeliverySequence?(): number;
+  waitForActiveTimeout?(timeoutMs: number, signal: AbortSignal): Promise<void>;
+}
+
+export interface WorkflowRuntimeInput {
+  script: ParsedWorkflowScript;
+  argsPresent: boolean;
+  args?: JsonValue;
+  generation: number;
+  depth: 0 | 1;
+  budget: WorkflowBudgetSnapshot;
+  limits?: Partial<WorkflowRuntimeLimits>;
+  signal: AbortSignal;
+  callbacks: WorkflowRuntimeCallbacks;
+  replay?: WorkflowReplayInput;
+}
+
+export interface WorkflowReplayInput {
+  events?: Array<
+    | { type: "phase"; title: string }
+    | { type: "log"; message: string }
+  >;
+  budgetObservations?: Array<{
+    getter: "spent" | "remaining";
+    value: number | "Infinity";
+    location?: WorkflowLocation;
+  }>;
+}
+
+export interface WorkflowRuntimeResult {
+  result: JsonValue;
+  omittedResult: boolean;
+  partial: boolean;
+}
+
+export interface StructuredOutputValidation {
+  valid: boolean;
+  value?: JsonValue;
+  errors?: string[];
+}
diff --git a/src/workflow-worker.ts b/src/workflow-worker.ts
new file mode 100644
index 000000000..741bdf565
--- /dev/null
+++ b/src/workflow-worker.ts
@@ -0,0 +1,662 @@
+import { isMainThread, parentPort, workerData } from "node:worker_threads";
+import { Ajv } from "ajv";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { getQuickJS, type QuickJSContext, type QuickJSDeferredPromise, type QuickJSRuntime } from "quickjs-emscripten";
+import type {
+  JsonSchema,
+  JsonValue,
+  WorkflowBudgetSnapshot,
+  WorkflowError,
+  WorkflowRuntimeEvent,
+  WorkflowRuntimeLimits,
+  WorkflowReplayInput,
+} from "./workflow-types.js";
+
+interface RuntimeWorkerData {
+  kind: "runtime";
+  body: string;
+  filename: string;
+  meta: JsonValue;
+  argsPresent: boolean;
+  args?: JsonValue;
+  generation: number;
+  depth: 0 | 1;
+  budget: WorkflowBudgetSnapshot;
+  replay?: WorkflowReplayInput;
+  limits: WorkflowRuntimeLimits;
+}
+
+interface SchemaWorkerData {
+  kind: "schema";
+  schema: JsonSchema;
+  value?: JsonValue;
+  compileOnly?: boolean;
+}
+
+interface CompileWorkerData {
+  kind: "compile";
+  body: string;
+  filename: string;
+  limits: WorkflowRuntimeLimits;
+}
+
+type WorkerInput = RuntimeWorkerData | SchemaWorkerData | CompileWorkerData;
+
+if (!isMainThread && parentPort) {
+  const input = workerData as WorkerInput;
+  if (input.kind === "schema") runSchemaValidation(input);
+  else if (input.kind === "compile") runCompileValidation(input);
+  else void runRuntime(input).catch((error) => {
+    parentPort?.postMessage({ type: "failed", error: safeError(error) });
+  });
+}
+
+function runCompileValidation(input: CompileWorkerData): void {
+  let runtime: QuickJSRuntime | undefined;
+  let context: QuickJSContext | undefined;
+  try {
+    void getQuickJS().then((QuickJS) => {
+      const started = performance.now();
+      runtime = QuickJS.newRuntime();
+      runtime.setMemoryLimit(input.limits.guestHeapBytes);
+      runtime.setMaxStackSize(input.limits.guestStackBytes);
+      runtime.removeModuleLoader();
+      runtime.setInterruptHandler(() => performance.now() - started > input.limits.guestSliceMs);
+      context = runtime.newContext();
+      const source = prelude({
+        kind: "runtime",
+        body: input.body,
+        filename: input.filename,
+        meta: { name: "preflight", description: "preflight" },
+        argsPresent: false,
+        generation: 0,
+        depth: 0,
+        budget: { total: null, knownSpent: 0, complete: true },
+        limits: input.limits,
+      });
+      const bodyMarkerOffset = source.indexOf("/*__DEVSPACE_WORKFLOW_BODY__*/");
+      const sourceLineOffset = source.slice(0, bodyMarkerOffset).split(/\r\n|\r|\n/).length;
+      const result = context.evalCode(source, input.filename, { type: "global", compileOnly: true });
+      if (result.error) {
+        const dumped = context.dump(result.error) as unknown;
+        result.error.dispose();
+        const error = guestError(dumped, sourceLineOffset, input.filename);
+        throw error.code === "WORKFLOW_FAILED" ? { ...error, code: "WORKFLOW_SYNTAX_ERROR" } : error;
+      }
+      result.value.dispose();
+      parentPort?.postMessage({ type: "compiled" });
+      context.dispose();
+      runtime.dispose();
+      context = undefined;
+      runtime = undefined;
+    }).catch((error) => {
+      context?.dispose();
+      runtime?.dispose();
+      parentPort?.postMessage({ type: "failed", error: safeError(error) });
+    });
+  } catch (error) {
+    context?.dispose();
+    runtime?.dispose();
+    parentPort?.postMessage({ type: "failed", error: safeError(error) });
+  }
+}
+
+function runSchemaValidation(input: SchemaWorkerData): void {
+  try {
+    assertSchemaIsPossible(input.schema);
+    const dialect = typeof input.schema === "object" && input.schema !== null
+      ? input.schema.$schema
+      : undefined;
+    const draft7 = dialect === "http://json-schema.org/draft-07/schema#"
+      || dialect === "https://json-schema.org/draft-07/schema";
+    const draft2020 = dialect === undefined || dialect === "https://json-schema.org/draft/2020-12/schema"
+      || dialect === "https://json-schema.org/draft/2020-12/schema#";
+    if (!draft7 && !draft2020) {
+      throw Object.assign(new Error(`Unsupported JSON Schema dialect: ${String(dialect)}`), {
+        code: "SCHEMA_UNSUPPORTED",
+      });
+    }
+    const ajv = draft7
+      ? new Ajv({ strict: true, allErrors: false })
+      : new Ajv2020({ strict: true, allErrors: false });
+    const validate = ajv.compile(input.schema);
+    if (input.compileOnly) {
+      parentPort?.postMessage({ valid: true });
+      return;
+    }
+    const valid = validate(input.value);
+    parentPort?.postMessage({
+      valid,
+      value: valid ? input.value : undefined,
+      errors: valid ? undefined : (validate.errors ?? []).slice(0, 20).map((error: { instancePath: string; message?: string }) =>
+        `${error.instancePath || "/"} ${error.message ?? "is invalid"}`),
+    });
+  } catch (error) {
+    parentPort?.postMessage({
+      error: error instanceof Error ? error.message : String(error),
+      code: error && typeof error === "object" && "code" in error ? String(error.code) : "SCHEMA_INVALID",
+    });
+  }
+}
+
+function assertSchemaIsPossible(schema: JsonSchema): void {
+  if (schema === true || schema === false) return;
+  const visit = (node: JsonValue): void => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+      return;
+    }
+    for (const [minimum, maximum] of [["minimum", "maximum"], ["minLength", "maxLength"], ["minItems", "maxItems"], ["minProperties", "maxProperties"]]) {
+      const low = node[minimum];
+      const high = node[maximum];
+      if (typeof low === "number" && typeof high === "number" && low > high) {
+        throw new Error(`${minimum} cannot exceed ${maximum}.`);
+      }
+    }
+    if (node.additionalProperties === false && Array.isArray(node.required)) {
+      const properties = node.properties && typeof node.properties === "object" && !Array.isArray(node.properties)
+        ? node.properties
+        : {};
+      const patterns = node.patternProperties && typeof node.patternProperties === "object" && !Array.isArray(node.patternProperties)
+        ? Object.keys(node.patternProperties)
+        : [];
+      for (const required of node.required) {
+        if (typeof required === "string" && !Object.hasOwn(properties, required)
+          && !patterns.some((pattern) => new RegExp(pattern, "u").test(required))) {
+          throw new Error(`Required property '${required}' is forbidden by additionalProperties: false.`);
+        }
+      }
+    }
+    for (const value of Object.values(node)) visit(value);
+  };
+  visit(schema);
+}
+
+async function runRuntime(input: RuntimeWorkerData): Promise<void> {
+  const QuickJS = await getQuickJS();
+  const runtime = QuickJS.newRuntime();
+  runtime.setMemoryLimit(input.limits.guestHeapBytes);
+  runtime.setMaxStackSize(input.limits.guestStackBytes);
+  runtime.removeModuleLoader();
+
+  let sliceStarted = 0;
+  let totalCpuMs = 0;
+  runtime.setInterruptHandler(() => {
+    const elapsed = performance.now() - sliceStarted;
+    return elapsed > input.limits.guestSliceMs || totalCpuMs + elapsed > input.limits.guestTotalCpuMs;
+  });
+
+  const context = runtime.newContext();
+  const runtimeSource = prelude(input);
+  const bodyMarkerOffset = runtimeSource.indexOf("/*__DEVSPACE_WORKFLOW_BODY__*/");
+  const sourceLineOffset = runtimeSource.slice(0, bodyMarkerOffset).split(/\r\n|\r|\n/).length;
+  const pending = new Map<number, QuickJSDeferredPromise>();
+  let nextRequestId = 1;
+  let pendingResult: { result: JsonValue; omittedResult: boolean; partial: boolean } | undefined;
+  let partial = false;
+  let phase: string | undefined;
+  let agentCount = 0;
+  let workflowCount = 0;
+  let logBytes = 0;
+  let eventCount = 0;
+  let replayEventIndex = 0;
+  let budget = input.budget;
+  let observationIndex = 0;
+  let replayActive = input.replay !== undefined;
+  let stopped = false;
+
+  const postEvent = (event: WorkflowRuntimeEvent): void => {
+    eventCount += 1;
+    if (eventCount > input.limits.eventsPerRun) throw workflowError("LOG_LIMIT", "Workflow event quota exceeded.");
+    parentPort?.postMessage({ type: "event", generation: input.generation, event });
+  };
+
+  const postReplayableEvent = (event: { type: "phase"; title: string } | { type: "log"; message: string }): void => {
+    const replayed = replayActive ? input.replay?.events?.[replayEventIndex] : undefined;
+    const matches = event.type === "phase"
+      ? replayed?.type === "phase" && replayed.title === event.title
+      : replayed?.type === "log" && replayed.message === event.message;
+    if (matches) {
+      replayEventIndex += 1;
+      postEvent({ ...event, replayed: true });
+      return;
+    }
+    if (replayActive) {
+      replayActive = false;
+      postEvent({ type: "replay_diverged", reason: `${event.type} event changed.` });
+    }
+    postEvent({ ...event, replayed: false });
+  };
+
+  const expose = (name: string, fn: Parameters<QuickJSContext["newFunction"]>[1]): void => {
+    const handle = context.newFunction(name, fn);
+    context.defineProp(context.global, name, {
+      value: handle,
+      configurable: false,
+      enumerable: false,
+    });
+    handle.dispose();
+  };
+
+  expose("__hostAgent", (payloadHandle, stackHandle) => {
+    if (agentCount >= input.limits.maxAgents) throw workflowError("AGENT_LIMIT", "Workflow agent invocation limit exceeded.");
+    agentCount += 1;
+    return request("agent", context.getString(payloadHandle), locationFromStack(context.getString(stackHandle)));
+  });
+  expose("__hostWorkflow", (payloadHandle, stackHandle) => {
+    if (input.depth >= 1) throw workflowError("NESTING_LIMIT", "Nested workflows may not invoke another workflow.");
+    if (workflowCount >= input.limits.maxNestedWorkflows) {
+      throw workflowError("AGENT_LIMIT", "Nested workflow invocation limit exceeded.");
+    }
+    workflowCount += 1;
+    return request("workflow", context.getString(payloadHandle), locationFromStack(context.getString(stackHandle)));
+  });
+  expose("__hostPhase", (titleHandle) => {
+    phase = context.getString(titleHandle);
+    if (phase.length < 1 || phase.length > 200) {
+      throw workflowError("WORKFLOW_SOURCE_INVALID", "Workflow phase is invalid.");
+    }
+    postReplayableEvent({ type: "phase", title: phase });
+  });
+  expose("__hostLog", (messageHandle) => {
+    const message = context.getString(messageHandle);
+    const bytes = Buffer.byteLength(message, "utf8");
+    if (bytes > input.limits.logMessageBytes || logBytes + bytes > input.limits.logTotalBytes) {
+      throw workflowError("LOG_LIMIT", "Workflow log quota exceeded.");
+    }
+    logBytes += bytes;
+    postReplayableEvent({ type: "log", message });
+  });
+  expose("__hostCombinatorError", (kindHandle, indexHandle, errorHandle, stackHandle) => {
+    partial = true;
+    const combinator = context.getString(kindHandle);
+    const index = context.getNumber(indexHandle);
+    const message = context.getString(errorHandle).slice(0, 2_000);
+    if ((combinator !== "parallel" && combinator !== "pipeline")
+      || !Number.isSafeInteger(index) || index < 0 || index >= input.limits.maxCombinatorItems) {
+      throw workflowError("WORKFLOW_SOURCE_INVALID", "Invalid combinator failure event.");
+    }
+    postEvent({
+      type: "combinator_error",
+      combinator,
+      index,
+      error: {
+        code: "TASK_FAILED",
+        message,
+        layer: "script",
+        retryable: false,
+        location: locationFromStack(context.getString(stackHandle)),
+      },
+    });
+  });
+  expose("__hostBudgetRead", (getterHandle, stackHandle) => {
+    const getter = context.getString(getterHandle) as "spent" | "remaining";
+    if (getter !== "spent" && getter !== "remaining") {
+      throw workflowError("WORKFLOW_SOURCE_INVALID", "Unknown budget getter.");
+    }
+    const location = locationFromStack(context.getString(stackHandle));
+    const replayed = replayActive ? input.replay?.budgetObservations?.[observationIndex] : undefined;
+    const replayMatches = replayed?.getter === getter
+      && (replayed.location === undefined || sameLocation(replayed.location, location));
+    if (replayActive && !replayMatches) {
+      replayActive = false;
+      if (!budget.complete) postEvent({ type: "replay_diverged", reason: "Budget observation changed." });
+    }
+    if (!replayMatches && !budget.complete) throw workflowError("USAGE_UNAVAILABLE", "Provider output-token usage is unavailable.");
+    const value = replayMatches
+      ? replayed.value === "Infinity" ? Number.POSITIVE_INFINITY : replayed.value
+      : getter === "spent"
+        ? budget.knownSpent
+        : budget.total === null ? Number.POSITIVE_INFINITY : Math.max(0, budget.total - budget.knownSpent);
+    postEvent({
+      type: "budget_observation",
+      getter,
+      observationIndex: observationIndex++,
+      value: Number.isFinite(value) ? value : "Infinity",
+      location,
+      replayed: replayMatches,
+    });
+    return context.newNumber(value);
+  });
+
+  function request(op: "agent" | "workflow", payload: string, location?: { line: number; column: number }) {
+    if (pending.size >= input.limits.maxPendingRequests) {
+      throw workflowError("AGENT_LIMIT", "Too many unresolved workflow requests.");
+    }
+    const requestId = nextRequestId++;
+    const deferred = context.newPromise();
+    pending.set(requestId, deferred);
+    parentPort?.postMessage({
+      type: "request",
+      op,
+      requestId,
+      generation: input.generation,
+      payload,
+      phase,
+      location,
+    });
+    return deferred.handle;
+  }
+
+  function locationFromStack(stack: string): { line: number; column: number } | undefined {
+    return errorLocation(stack, sourceLineOffset, input.filename);
+  }
+
+  const onMessage = (message: Record<string, unknown>): void => {
+    if (message.generation !== input.generation) return;
+    if (message.type === "abort") {
+      stopped = true;
+      for (const deferred of pending.values()) rejectDeferred(deferred, workflowError("WORKFLOW_STOPPED", "Workflow stopped."));
+      pending.clear();
+      pump(runtime);
+      finish();
+      return;
+    }
+    if (message.type !== "reply" || typeof message.requestId !== "number") return;
+    const deferred = pending.get(message.requestId);
+    if (!deferred) return;
+    pending.delete(message.requestId);
+    if (message.replayed !== true) replayActive = false;
+    if (isBudget(message.budget)) budget = message.budget;
+    if (message.ok) {
+      const value = parseJsonHandle(context, String(message.valueJson));
+      deferred.resolve(value);
+      value.dispose();
+    } else {
+      partial = true;
+      rejectDeferred(deferred, isWorkflowError(message.error) ? message.error : workflowError("WORKFLOW_FAILED", "Workflow request failed."));
+    }
+    deferred.dispose();
+    pump(runtime);
+    readResult();
+    finish();
+  };
+  parentPort?.on("message", onMessage);
+
+  try {
+    evaluate(context, runtime, runtimeSource, input.filename);
+    readResult();
+    finish();
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+
+  function readResult(): void {
+    if (pendingResult || stopped) return;
+    const handle = context.getProp(context.global, "__workflowResult");
+    const state = context.getPromiseState(handle);
+    handle.dispose();
+    if (state.type === "pending") return;
+    if (state.type === "rejected") {
+      const error = context.dump(state.error) as unknown;
+      state.error.dispose();
+      throw guestError(error, sourceLineOffset, input.filename);
+    }
+    const raw = context.dump(state.value) as { valueJson: string; omittedResult: boolean };
+    state.value.dispose();
+    pendingResult = { result: JSON.parse(raw.valueJson) as JsonValue, omittedResult: raw.omittedResult, partial };
+  }
+
+  function finish(): void {
+    if (stopped) {
+      cleanup();
+      parentPort?.postMessage({ type: "failed", error: workflowError("WORKFLOW_STOPPED", "Workflow stopped.") });
+      return;
+    }
+    if (!pendingResult) {
+      if (pending.size === 0) throw workflowError("WORKFLOW_FAILED", "Workflow script stalled with no outstanding operations.");
+      return;
+    }
+    if (pending.size > 0) return;
+    const result = { ...pendingResult, partial: pendingResult.partial || partial };
+    cleanup();
+    parentPort?.postMessage({ type: "result", generation: input.generation, ...result });
+  }
+
+  function cleanup(): void {
+    parentPort?.off("message", onMessage);
+    for (const deferred of pending.values()) deferred.dispose();
+    pending.clear();
+    context.dispose();
+    runtime.dispose();
+  }
+
+  function evaluate(vm: QuickJSContext, qjsRuntime: QuickJSRuntime, code: string, filename: string): void {
+    sliceStarted = performance.now();
+    const result = vm.evalCode(code, filename, { type: "global" });
+    totalCpuMs += performance.now() - sliceStarted;
+    if (result.error) {
+      const dumped = vm.dump(result.error) as unknown;
+      result.error.dispose();
+      throw guestError(dumped, sourceLineOffset, input.filename);
+    }
+    result.value.dispose();
+    pump(qjsRuntime);
+  }
+
+  function pump(qjsRuntime: QuickJSRuntime): void {
+    while (qjsRuntime.hasPendingJob()) {
+      sliceStarted = performance.now();
+      const result = qjsRuntime.executePendingJobs(1_000);
+      totalCpuMs += performance.now() - sliceStarted;
+      if (result.error) {
+        const dumped = result.error.context.dump(result.error) as unknown;
+        result.error.dispose();
+        throw guestError(dumped, sourceLineOffset, input.filename);
+      }
+      if (totalCpuMs >= input.limits.guestTotalCpuMs) {
+        throw workflowError("SCRIPT_CPU_LIMIT", "Workflow CPU limit exceeded.");
+      }
+    }
+  }
+}
+
+function prelude(input: RuntimeWorkerData): string {
+  const metaJson = JSON.stringify(input.meta);
+  const argsExpression = input.argsPresent ? `JSON.parse(${JSON.stringify(JSON.stringify(input.args))})` : "undefined";
+  return `
+"use strict";
+const __descriptors = Object.getOwnPropertyDescriptors;
+const __keys = Reflect.ownKeys;
+const __getPrototypeOf = Object.getPrototypeOf;
+const __isArray = Array.isArray;
+const __isFinite = Number.isFinite;
+const __stringify = JSON.stringify;
+const __parse = JSON.parse;
+const __WeakSet = WeakSet;
+const __objectPrototype = Object.prototype;
+const __arrayPrototype = Array.prototype;
+function __encode(value) {
+  const seen = new __WeakSet();
+  function walk(item) {
+    if (item === null || typeof item === "string" || typeof item === "boolean") return item;
+    if (typeof item === "number") { if (!__isFinite(item)) throw new TypeError("JSON numbers must be finite"); return item; }
+    if (typeof item !== "object") throw new TypeError("Value is not JSON data");
+    if (seen.has(item)) throw new TypeError("JSON data cannot contain cycles");
+    seen.add(item);
+    const isArray = __isArray(item);
+    const proto = __getPrototypeOf(item);
+    if (proto !== (isArray ? __arrayPrototype : __objectPrototype) && proto !== null) throw new TypeError("Unsupported JSON object");
+    const descriptors = __descriptors(item);
+    const keys = __keys(descriptors);
+    if (keys.some(key => typeof key === "symbol")) throw new TypeError("JSON data cannot contain symbols");
+    if (isArray) {
+      if (keys.some(key => key !== "length" && !/^(0|[1-9]\\d*)$/.test(key))) throw new TypeError("Arrays cannot have custom properties");
+      const result = [];
+      for (let index = 0; index < item.length; index++) {
+        const descriptor = descriptors[index];
+        if (!descriptor || !("value" in descriptor)) throw new TypeError("Arrays must be dense data properties");
+        result.push(walk(descriptor.value));
+      }
+      return result;
+    }
+    const result = Object.create(null);
+    for (const key of keys) {
+      const descriptor = descriptors[key];
+      if (!("value" in descriptor)) throw new TypeError("JSON data cannot contain accessors");
+      if (key === "__proto__" || key === "prototype" || key === "constructor") throw new TypeError("Prototype-sensitive keys are forbidden");
+      result[key] = walk(descriptor.value);
+    }
+    return result;
+  }
+  return __stringify(walk(value));
+}
+function __clone(value) { return value === undefined ? undefined : __parse(__encode(value)); }
+function __deepFreeze(value) { if (value && typeof value === "object") { for (const child of Object.values(value)) __deepFreeze(child); Object.freeze(value); } return value; }
+function __assertString(value, name, min, max) {
+  if (typeof value !== "string" || value.length < min || value.length > max) throw new TypeError(name + " is invalid");
+}
+function __errorMessage(error) { try { return typeof error?.message === "string" ? error.message.slice(0, 2000) : String(error).slice(0, 2000); } catch { return "Task failed"; } }
+let __phase;
+const meta = __deepFreeze(__parse(${JSON.stringify(metaJson)}));
+const args = ${argsExpression.replace("JSON.parse", "__parse")};
+function phase(title) { __assertString(title, "phase title", 1, 200); __phase = title; __hostPhase(title); }
+function log(message) { if (typeof message !== "string") throw new TypeError("log message must be a string"); __hostLog(message); }
+function agent(prompt, options = {}) {
+  if (typeof prompt !== "string" || !prompt.trim()) throw new TypeError("agent prompt must contain text");
+  const request = { prompt, options: __clone(options) };
+  if (__phase !== undefined) request.phase = __phase;
+  return __hostAgent(__encode(request), new Error().stack);
+}
+function workflow(reference, childArgs) {
+  if (!(typeof reference === "string" && reference) && !(reference && typeof reference === "object")) throw new TypeError("workflow reference is invalid");
+  const request = { reference: __clone(reference), argsPresent: arguments.length > 1, args: arguments.length > 1 ? __clone(childArgs) : null };
+  if (__phase !== undefined) request.phase = __phase;
+  return __hostWorkflow(__encode(request), new Error().stack);
+}
+async function parallel(tasks) {
+  if (!Array.isArray(tasks) || tasks.length > ${input.limits.maxCombinatorItems} || Object.keys(tasks).length !== tasks.length || tasks.some(task => typeof task !== "function")) throw new TypeError("parallel expects a dense array of functions");
+  return Promise.all(tasks.map((task, index) => Promise.resolve().then(task).catch(error => { __hostCombinatorError("parallel", index, __errorMessage(error), error?.stack ?? new Error().stack); return null; })));
+}
+async function pipeline(items, ...stages) {
+  if (!Array.isArray(items) || items.length > ${input.limits.maxCombinatorItems} || Object.keys(items).length !== items.length) throw new TypeError("pipeline expects a dense items array");
+  if (!stages.length || stages.some(stage => typeof stage !== "function")) throw new TypeError("pipeline expects at least one callable stage");
+  return Promise.all(items.map(async (original, index) => {
+    let previous = original;
+    try { for (const stage of stages) previous = await stage(previous, original, index); return previous; }
+    catch (error) { __hostCombinatorError("pipeline", index, __errorMessage(error), error?.stack ?? new Error().stack); return null; }
+  }));
+}
+const budget = Object.freeze({ total: ${input.budget.total === null ? "null" : input.budget.total}, spent: () => __hostBudgetRead("spent", new Error().stack), remaining: () => __hostBudgetRead("remaining", new Error().stack) });
+const __NativeDate = Date;
+class __SafeDate extends __NativeDate {
+  constructor(...values) {
+    if (!values.length) throw new TypeError("Current time is unavailable");
+    if (values.length > 1) throw new TypeError("Local-time date construction is unavailable; use Date.UTC");
+    super(...values);
+  }
+  static now() { throw new TypeError("Current time is unavailable"); }
+  static parse(value) {
+    if (typeof value !== "string" || !/^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{3})?Z$/.test(value)) throw new TypeError("Only ISO UTC date parsing is available");
+    return __NativeDate.parse(value);
+  }
+}
+Object.defineProperty(globalThis, "Date", { value: Object.freeze(__SafeDate), writable: false, configurable: false });
+Object.defineProperty(Math, "random", { value() { throw new TypeError("Randomness is unavailable"); }, writable: false, configurable: false });
+Object.freeze(Math);
+Object.freeze(JSON);
+Object.freeze(Reflect);
+for (const intrinsic of [
+  Object.prototype, Object, Array.prototype, Array, Promise.prototype, Promise,
+  WeakSet.prototype, WeakSet, Number.prototype, Number, String.prototype, String,
+  Boolean.prototype, Boolean, RegExp.prototype, RegExp,
+]) Object.freeze(intrinsic);
+for (const name of [
+  "getDate", "getDay", "getFullYear", "getHours", "getMilliseconds", "getMinutes", "getMonth", "getSeconds", "getTimezoneOffset",
+  "setDate", "setFullYear", "setHours", "setMilliseconds", "setMinutes", "setMonth", "setSeconds",
+  "toDateString", "toString", "toTimeString", "toLocaleString", "toLocaleDateString", "toLocaleTimeString",
+]) if (name in __NativeDate.prototype) Object.defineProperty(__NativeDate.prototype, name, { value() { throw new TypeError("Local-time and locale-dependent dates are unavailable"); }, writable: false, configurable: false });
+Object.freeze(__NativeDate.prototype);
+globalThis.__workflowResult = (async () => {
+/*__DEVSPACE_WORKFLOW_BODY__*/
+${input.body}
+})().then(value => ({ valueJson: __encode(value === undefined ? null : value), omittedResult: value === undefined }));
+`;
+}
+
+function parseJsonHandle(context: QuickJSContext, json: string) {
+  const result = context.evalCode(`JSON.parse(${JSON.stringify(json)})`);
+  if (result.error) {
+    const dumped = context.dump(result.error) as unknown;
+    result.error.dispose();
+    throw guestError(dumped);
+  }
+  return result.value;
+}
+
+function rejectDeferred(deferred: QuickJSDeferredPromise, error: WorkflowError): void {
+  const context = deferred.context;
+  const handle = context.newError(error.message);
+  const code = context.newString(error.code);
+  const layer = context.newString(error.layer);
+  context.setProp(handle, "code", code);
+  context.setProp(handle, "layer", layer);
+  context.setProp(handle, "retryable", error.retryable ? context.true : context.false);
+  code.dispose();
+  layer.dispose();
+  deferred.reject(handle);
+  handle.dispose();
+}
+
+function workflowError(code: string, message: string): WorkflowError {
+  return { code, message, layer: "script", retryable: false };
+}
+
+function safeError(error: unknown): WorkflowError {
+  if (isWorkflowError(error)) return error;
+  return workflowError("WORKFLOW_FAILED", error instanceof Error ? error.message : String(error));
+}
+
+function guestError(value: unknown, sourceLineOffset = 0, filename?: string): WorkflowError {
+  if (value && typeof value === "object") {
+    const error = value as Record<string, unknown>;
+    const message = typeof error.message === "string" ? error.message : "Workflow script failed.";
+    const knownCode = message.includes("log quota") ? "LOG_LIMIT"
+      : message.includes("invocation limit") || message.includes("unresolved workflow requests") ? "AGENT_LIMIT"
+      : message.includes("usage is unavailable") ? "USAGE_UNAVAILABLE"
+      : message.includes("interrupted") ? "SCRIPT_CPU_LIMIT"
+      : undefined;
+    const location = errorLocation(typeof error.stack === "string" ? error.stack : "", sourceLineOffset, filename);
+    return {
+      code: typeof error.code === "string" ? error.code : knownCode ?? "WORKFLOW_FAILED",
+      message,
+      layer: "script",
+      retryable: false,
+      ...(location ? { location } : {}),
+    };
+  }
+  return workflowError("WORKFLOW_FAILED", String(value));
+}
+
+function errorLocation(stack: string, sourceLineOffset: number, filename?: string): { line: number; column: number } | undefined {
+  for (const match of stack.matchAll(/(?:^|\n)\s*at\s+(?:.*?\s+\()?([^()\s]+):(\d+):(\d+)\)?/g)) {
+    if (filename && match[1] !== filename && !match[1]?.endsWith(`/${filename}`)) continue;
+    const line = Number(match[2]) - sourceLineOffset;
+    const column = Number(match[3]);
+    if (line > 0 && Number.isSafeInteger(column) && column > 0) return { line, column };
+  }
+  return undefined;
+}
+
+function isWorkflowError(value: unknown): value is WorkflowError {
+  if (!value || typeof value !== "object") return false;
+  const error = value as Partial<WorkflowError>;
+  return typeof error.code === "string" && typeof error.message === "string"
+    && typeof error.layer === "string" && typeof error.retryable === "boolean";
+}
+
+function isBudget(value: unknown): value is WorkflowBudgetSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const budget = value as Partial<WorkflowBudgetSnapshot>;
+  return (budget.total === null || typeof budget.total === "number")
+    && typeof budget.knownSpent === "number" && typeof budget.complete === "boolean";
+}
+
+function sameLocation(
+  left: { line: number; column: number },
+  right: { line: number; column: number } | undefined,
+): boolean {
+  return right !== undefined && left.line === right.line && left.column === right.column;
+}
diff --git a/test/workflow-cli-smoke.test.ts b/test/workflow-cli-smoke.test.ts
new file mode 100644
index 000000000..d07446fa6
--- /dev/null
+++ b/test/workflow-cli-smoke.test.ts
@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, mkdir, writeFile, readFile, realpath, rm, access } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import test from "node:test";
+import { defaultDevspaceConfig } from "../src/config-schema.js";
+import { writeDevspaceConfig } from "../src/user-config.js";
+
+const execute = promisify(execFile);
+// Run after compiling dist. No installation and no live provider credentials are needed.
+test("compiled CLI coordinates a real daemon, adapter process, managed worktree, and persisted replay", { skip: process.platform === "win32" }, async () => {
+  const root = await realpath(await mkdtemp("/tmp/devspace-workflow-package-"));
+  const project = join(root, "project");
+  const configDir = join(root, "config");
+  await mkdir(project);
+  const command = join(root, "fake-codex.mjs");
+  await writeFile(command, `#!/usr/bin/env node
+import readline from 'node:readline';
+if (process.argv.includes('--version')) { console.log('codex-cli 9.8.7'); process.exit(0); }
+const send = value => process.stdout.write(JSON.stringify(value) + '\\n');
+const threads = new Map(); let sequence = 0;
+readline.createInterface({input: process.stdin}).on('line', line => {
+  const m = JSON.parse(line);
+  if (m.method === 'initialize') return send({id:m.id,result:{userAgent:'fake'}});
+  if (m.method === 'thread/start' || m.method === 'thread/resume') {
+    const id = m.params.threadId || 'thread_' + ++sequence; threads.set(id, m.params);
+    return send({id:m.id,result:{thread:{id}}});
+  }
+  if (m.method === 'turn/start') {
+    const id = 'turn_' + ++sequence, threadId = m.params.threadId;
+    send({id:m.id,result:{turn:{id}}});
+    const item = {type:'agentMessage',text:JSON.stringify({cwd:threads.get(threadId).cwd,
+      sandbox:m.params.sandboxPolicy.type, provenance:process.env.DEVSPACE_WORKFLOW_RUN_ID})};
+    setImmediate(() => {
+      send({method:'item/completed',params:{threadId,turnId:id,item}});
+      send({method:'thread/tokenUsage/updated',params:{threadId,turnId:id,tokenUsage:{last:{inputTokens:1,outputTokens:2}}}});
+      send({method:'turn/completed',params:{threadId,turn:{id,status:'completed',items:[item]}}});
+    }); return;
+  }
+  if (m.id !== undefined) send({id:m.id,result:{}});
+});
+`, { mode: 0o700 });
+  const git = (args: string[]) => execute("git", args, { cwd: project });
+  await git(["init"]);
+  await writeFile(join(project, "README.md"), "fixture\n");
+  await git(["add", "README.md"]);
+  await git(["-c", "user.name=DevSpace Test", "-c", "user.email=test@example.com", "commit", "-m", "fixture"]);
+  await mkdir(join(project, ".devspace", "agents"), { recursive: true });
+  await writeFile(join(project, ".devspace", "agents", "local-reviewer.md"),
+    "---\nname: local-reviewer\ndescription: Untracked project profile\nprovider: codex\nwriteMode: read_only\n---\nInspect the project.\n");
+  await writeFile(join(project, "workflow.js"), `export const meta = {name:'package-smoke',description:'Packaged adapter path'};
+return await agent('inspect', {isolation:'worktree',schema:{type:'object'}});`);
+  const config = defaultDevspaceConfig();
+  config.workspaces.allowedRoots = [project];
+  config.workspaces.worktreeRoot = join(root, "worktrees");
+  config.storage.stateDir = join(root, "state");
+  config.subagents = { enabled: true, instructions: "on-demand", providers: [{id:"codex", enabled:true, command}] };
+  config.workflows.enabled = true; config.workflows.defaultAgentType = "local-reviewer";
+  writeDevspaceConfig(config, {DEVSPACE_CONFIG_DIR: configDir});
+  const env: NodeJS.ProcessEnv = {...process.env, DEVSPACE_CONFIG_DIR: configDir, DEVSPACE_OAUTH_OWNER_TOKEN:"package-test-owner-token", DEVSPACE_AGENTD_IDLE_TIMEOUT_MS:"60000"};
+  delete env.DEVSPACE_WORKFLOW_RUN_ID;
+  const cli = resolve("dist/cli.js");
+  await access(cli);
+  const run = async (args: string[]) => JSON.parse((await execute(process.execPath, [cli, ...args, "--json"], {
+    cwd:project, env, timeout:15000, maxBuffer:4*1024*1024,
+  })).stdout);
+  try {
+    const receipt = await run(["workflows", "run", "workflow.js"]);
+    let snapshot: any;
+    for (let index=0; index<20; index++) {
+      snapshot = await run(["workflows", "wait", receipt.runId, "--timeout", "1"]);
+      if (["completed","failed","stopped","recovery_required"].includes(snapshot.state)) break;
+    }
+    assert.equal(snapshot.state, "completed", JSON.stringify(snapshot));
+    assert.equal(snapshot.result.sandbox, "readOnly");
+    assert.equal(snapshot.result.provenance, receipt.runId);
+    assert.ok(snapshot.result.cwd.startsWith(config.workspaces.worktreeRoot));
+    assert.notEqual(snapshot.result.cwd, project);
+    assert.equal(snapshot.worktrees[0].path, snapshot.result.cwd);
+    assert.equal(snapshot.worktrees[0].changed, false);
+    assert.equal(snapshot.usage.knownOutputTokens, 2);
+    await access(receipt.scriptPath);
+    await access(join(receipt.transcriptDir, "journal.jsonl"));
+    await access(join(receipt.transcriptDir, "result.json"));
+    const saved = await run(["workflows","save",receipt.runId,"--name","saved-smoke"]);
+    await access(saved.sourcePath);
+    const resumed = await run(["workflows","run","workflow.js","--resume-from",receipt.runId]);
+    const replay = await run(["workflows","wait",resumed.runId,"--timeout","2"]);
+    assert.equal(replay.state,"completed",JSON.stringify(replay));
+    assert.equal(replay.counts.cached,1);
+    assert.equal(replay.usage.knownOutputTokens,2);
+    await writeFile(join(project, "large.js"), "export const meta = {name:'large',description:'Large result'}; return 'x'.repeat(70000);");
+    const large = await run(["workflows", "run", "large.js"]);
+    const largeResult = await run(["workflows", "wait", large.runId, "--timeout", "2"]);
+    assert.equal(largeResult.state, "completed");
+    assert.equal(largeResult.result, undefined);
+    assert.equal(JSON.parse(await readFile(largeResult.resultArtifact.path, "utf8")).length, 70000);
+  } finally {
+    await run(["agents","daemon","stop"]).catch(() => undefined);
+    await rm(root,{recursive:true,force:true});
+  }
+});

From ca916b0980dfdf3bfb83d67494525110a2ee665c Mon Sep 17 00:00:00 2001
From: Bhavik Agarwal <agarwalbhavik2001@gmail.com>
Date: Wed, 16 Sep 2026 17:28:40 +0530
Subject: [PATCH 2/2] fix: address dynamic workflow review feedback

---
 examples/workflows/bounded-repair.js |   4 +-
 src/local-agent-acp.test.ts          | 119 +++++++++++++++++++++++++++
 src/local-agent-acp.ts               |  29 +++++--
 src/local-agent-claude.test.ts       |  16 +++-
 src/local-agent-claude.ts            |  15 ++--
 src/local-agent-client.ts            |  11 ++-
 src/local-agent-codex.test.ts        |  22 ++++-
 src/local-agent-codex.ts             |   1 +
 src/local-agent-opencode.test.ts     |  48 ++++++++++-
 src/local-agent-opencode.ts          |  37 +++++++--
 src/local-agent-profiles.test.ts     |  13 +++
 src/local-agent-profiles.ts          |   7 +-
 src/local-agent-runtime.test.ts      |  10 +++
 src/local-agent-runtime.ts           |   9 +-
 src/local-agent-store.ts             |   2 +-
 src/server.test.ts                   |   4 +
 src/server.ts                        |   4 +-
 src/skills.test.ts                   |  29 +++++++
 src/skills.ts                        |   5 +-
 src/workflow-daemon.test.ts          |   8 ++
 src/workflow-manager.test.ts         |  23 +++++-
 src/workflow-manager.ts              |  55 +++++++++++--
 src/workflow-script.test.ts          |   3 +
 src/workflow-script.ts               |  22 ++++-
 test/workflow-cli-smoke.test.ts      |   3 +-
 25 files changed, 448 insertions(+), 51 deletions(-)

diff --git a/examples/workflows/bounded-repair.js b/examples/workflows/bounded-repair.js
index 3772fcff3..588374559 100644
--- a/examples/workflows/bounded-repair.js
+++ b/examples/workflows/bounded-repair.js
@@ -14,7 +14,7 @@ for (let attempt = 1; attempt <= 3; attempt++) {
       required: ["passed", "feedback"], additionalProperties: false
     }
   });
-  if (result.passed) return result;
-  feedback = result.feedback;
+  if (result?.passed) return result;
+  feedback = result?.feedback ?? feedback;
 }
 return { passed: false, feedback };
diff --git a/src/local-agent-acp.test.ts b/src/local-agent-acp.test.ts
index 4ab1765ea..e206e5b2a 100644
--- a/src/local-agent-acp.test.ts
+++ b/src/local-agent-acp.test.ts
@@ -301,6 +301,125 @@ if (completedOverlappingTurn.isErr()) throw completedOverlappingTurn.error;
 assert.equal(completedOverlappingTurn.value.finalResponse, "overlap response");
 await overlapRuntime.close();
 
+const liveQueues = new Map<string, { values: unknown[]; onValue?: (value: unknown) => void }>();
+let finishLivePrompt!: () => void;
+const livePromptGate = new Promise<void>((resolve) => { finishLivePrompt = resolve; });
+let progressDelivered!: () => void;
+const liveProgress = new Promise<void>((resolve) => { progressDelivered = resolve; });
+const liveConnection = {
+  agent: {
+    async request(method: string, params?: unknown): Promise<unknown> {
+      const sessionId = (params as { sessionId?: string } | undefined)?.sessionId ?? "live_session";
+      if (method === "session/new") {
+        liveQueues.set(sessionId, { values: [] });
+        return { sessionId };
+      }
+      if (method === "session/prompt") {
+        const update = { update: { sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text: "live response" } } };
+        const queue = liveQueues.get(sessionId)!;
+        queue.values.push(update);
+        queue.onValue?.(update);
+        await livePromptGate;
+        return { stopReason: "end_turn" };
+      }
+      return {};
+    },
+  },
+  close() {},
+  closed: new Promise<void>(() => undefined),
+};
+const liveRuntime = new AcpRuntime({
+  provider: "cursor", command: "cursor-agent", args: ["acp"], env: {}, queues: liveQueues,
+}, liveConnection);
+let livePromptSettled = false;
+const liveRun = liveRuntime.run({ prompt: "live", workspaceRoot: "/tmp/project" }, {
+  onProgress: () => { progressDelivered(); },
+}).then((result) => { livePromptSettled = true; return result; });
+await liveProgress;
+assert.equal(livePromptSettled, false, "ACP progress is delivered before the prompt completes");
+finishLivePrompt();
+assert.equal((await liveRun).isOk(), true);
+await liveRuntime.close();
+
+const fencedQueues = new Map<string, { values: unknown[]; onValue?: (value: unknown) => void }>();
+let finishFencedPrompt!: () => void;
+let finishFencedCancel!: () => void;
+let fencedPromptEntered!: () => void;
+const fencedPromptGate = new Promise<void>((resolve) => { finishFencedPrompt = resolve; });
+const fencedCancelGate = new Promise<void>((resolve) => { finishFencedCancel = resolve; });
+const fencedPromptStarted = new Promise<void>((resolve) => { fencedPromptEntered = resolve; });
+const fencedConnection = {
+  agent: {
+    async request(method: string, params?: unknown): Promise<unknown> {
+      const sessionId = (params as { sessionId?: string } | undefined)?.sessionId ?? "fenced_session";
+      if (method === "session/new") {
+        fencedQueues.set(sessionId, { values: [] });
+        return { sessionId };
+      }
+      if (method === "session/prompt") {
+        fencedPromptEntered();
+        await fencedPromptGate;
+        return { stopReason: "cancelled" };
+      }
+      return {};
+    },
+    async cancel() { await fencedCancelGate; },
+  },
+  close() {},
+  closed: new Promise<void>(() => undefined),
+};
+const fencedRuntime = new AcpRuntime({
+  provider: "cursor", command: "cursor-agent", args: ["acp"], env: {}, queues: fencedQueues,
+}, fencedConnection);
+const fencedAbort = new AbortController();
+let fencedSessionId: string | undefined;
+const fencedRun = fencedRuntime.run({ prompt: "first", workspaceRoot: "/tmp/project" }, {
+  onSessionId: (sessionId) => { fencedSessionId = sessionId; },
+}, { signal: fencedAbort.signal });
+await fencedPromptStarted;
+fencedAbort.abort();
+finishFencedPrompt();
+await new Promise<void>((resolve) => setImmediate(resolve));
+await assert.rejects(fencedRuntime.run({
+  prompt: "second", workspaceRoot: "/tmp/project", providerSessionId: fencedSessionId,
+}), /already has an active turn/);
+finishFencedCancel();
+assert.equal((await fencedRun).isErr(), true);
+await fencedRuntime.close();
+
+let finishOpeningSession!: () => void;
+let openingSessionEntered!: () => void;
+const openingSessionGate = new Promise<void>((resolve) => { finishOpeningSession = resolve; });
+const openingSessionStarted = new Promise<void>((resolve) => { openingSessionEntered = resolve; });
+let promptAfterAbort = 0;
+const setupAbortRuntime = new AcpRuntime({
+  provider: "cursor", command: "cursor-agent", args: ["acp"], env: {},
+}, {
+  agent: {
+    async request(method: string): Promise<unknown> {
+      if (method === "session/new") {
+        openingSessionEntered();
+        await openingSessionGate;
+        return { sessionId: "setup_abort_session" };
+      }
+      if (method === "session/prompt") promptAfterAbort += 1;
+      return {};
+    },
+  },
+  close() {},
+  closed: new Promise<void>(() => undefined),
+});
+const setupAbort = new AbortController();
+const setupAbortRun = setupAbortRuntime.run({ prompt: "never submit", workspaceRoot: "/tmp/project" },
+  undefined, { signal: setupAbort.signal });
+await openingSessionStarted;
+setupAbort.abort();
+finishOpeningSession();
+assert.equal((await setupAbortRun).isErr(), true);
+assert.equal(promptAfterAbort, 0);
+await setupAbortRuntime.close();
+
 const cachedContext = {
   agentId: "agt_acp",
   provider: "cursor" as const,
diff --git a/src/local-agent-acp.ts b/src/local-agent-acp.ts
index af9109584..cbfdae3dc 100644
--- a/src/local-agent-acp.ts
+++ b/src/local-agent-acp.ts
@@ -67,6 +67,7 @@ interface AcpCapabilities {
 
 interface AcpSessionQueue {
   values: unknown[];
+  onValue?: (value: unknown) => void;
 }
 
 export interface AcpRuntimeOptions {
@@ -148,6 +149,7 @@ export class AcpRuntime implements LocalAgentRuntime {
         }
         if (control?.signal.aborted) throw new DOMException("Aborted", "AbortError");
         const sessionId = await this.openSession(input, callbacks);
+        if (control?.signal.aborted) throw new DOMException("Aborted", "AbortError");
         if (this.activeSessions.has(sessionId)) {
           throw new TypeError(`${this.provider} ACP session ${sessionId} already has an active turn.`);
         }
@@ -171,13 +173,29 @@ export class AcpRuntime implements LocalAgentRuntime {
           : undefined;
         try {
           queue.values.length = 0;
+          let progressFailure: unknown;
+          let progressCallbacks = Promise.resolve();
+          queue.onValue = (update) => {
+            const progress = acpProgress(update);
+            if (!progress) return;
+            progressCallbacks = progressCallbacks.then(async () => {
+              if (progressFailure !== undefined) return;
+              try { await callbacks?.onProgress?.(progress); }
+              catch (error) { progressFailure = error; }
+            });
+          };
+          let cancellation: Promise<void> | undefined;
           const cancel = () => {
-            const cancellation = this.connection.agent.cancel
+            cancellation ??= this.connection.agent.cancel
               ? this.connection.agent.cancel({ sessionId })
               : this.connection.agent.request("session/cancel", { sessionId }).then(() => undefined);
             void cancellation.catch(() => undefined);
           };
           control?.signal.addEventListener("abort", cancel, { once: true });
+          if (control?.signal.aborted) {
+            control.signal.removeEventListener("abort", cancel);
+            throw new DOMException("Aborted", "AbortError");
+          }
           const standardResponse = this.connection.agent.request("session/prompt", {
             sessionId,
             prompt: [{ type: "text", text: input.prompt }],
@@ -190,6 +208,7 @@ export class AcpRuntime implements LocalAgentRuntime {
               : await standardResponse;
           } finally {
             control?.signal.removeEventListener("abort", cancel);
+            if (cancellation) await cancellation.catch(() => undefined);
           }
           if (completion && isGrokPromptCompletion(response)) {
             await yieldToAcpQueue();
@@ -197,13 +216,11 @@ export class AcpRuntime implements LocalAgentRuntime {
             this.grokCompletionRegistry?.markCompleted(sessionId, promptId);
           }
           const updates = queue.values.splice(0);
+          await progressCallbacks;
+          if (progressFailure !== undefined) throw progressFailure;
           if (readString(response, "stopReason") === "cancelled") {
             throw new DOMException("Aborted", "AbortError");
           }
-          for (const update of updates) {
-            const progress = acpProgress(update);
-            if (progress) await callbacks?.onProgress?.(progress);
-          }
           const finalResponse = extractAcpText(updates);
           if (!finalResponse) {
             throw new AgentProviderProtocolError({
@@ -225,6 +242,7 @@ export class AcpRuntime implements LocalAgentRuntime {
             ...(usage ? { usage } : {}),
           };
         } finally {
+          queue.onValue = undefined;
           if (promptId) this.grokCompletionRegistry?.remove(sessionId, promptId);
           this.activeSessions.delete(sessionId);
         }
@@ -903,6 +921,7 @@ function hasAcpConfigOptions(value: unknown): boolean {
 function appendAcpQueueValue(queue: AcpSessionQueue, value: unknown): void {
   if (queue.values.length >= MAX_ACP_QUEUE_ITEMS) queue.values.shift();
   queue.values.push(value);
+  queue.onValue?.(value);
 }
 
 function appendTail(current: string, chunk: string, maxBytes: number): string {
diff --git a/src/local-agent-claude.test.ts b/src/local-agent-claude.test.ts
index 9c94aa21f..0645dd38c 100644
--- a/src/local-agent-claude.test.ts
+++ b/src/local-agent-claude.test.ts
@@ -127,6 +127,18 @@ const third = await runtime.run({
   writeMode: "full_access",
 });
 assert.equal(third.isOk(), true);
+const preAborted = new AbortController();
+preAborted.abort();
+const rejectedBeforeSubmission = await runtime.run({
+  prompt: "cancelled-before-submission",
+  workspaceRoot: "/tmp/project",
+}, undefined, { signal: preAborted.signal });
+assert.equal(rejectedBeforeSubmission.isErr(), true);
+if (rejectedBeforeSubmission.isErr()) assert.equal(rejectedBeforeSubmission.error.code, "PROVIDER_CANCELLED");
+const afterRejectedSubmission = await runtime.run({ prompt: "after-cancel", workspaceRoot: "/tmp/project" });
+assert.equal(afterRejectedSubmission.isOk(), true);
+if (afterRejectedSubmission.isErr()) throw afterRejectedSubmission.error;
+assert.equal(afterRejectedSubmission.value.finalResponse, "response:after-cancel");
 assert.equal(factoryCalls, 1, "successive turns reuse one Claude query");
 assert.equal(first.providerSessionId, "claude_session_1");
 assert.equal(second.finalResponse, "response:second");
@@ -185,8 +197,8 @@ assert.deepEqual(usageUpdates, [{
   cacheWriteTokens: 2,
   final: true,
 }]);
-assert.deepEqual(query?.permissionModes, ["dontAsk", "dontAsk", "bypassPermissions"]);
-assert.equal(query?.flagSettings.length, 3);
+assert.deepEqual(query?.permissionModes, ["dontAsk", "dontAsk", "bypassPermissions", "dontAsk", "dontAsk"]);
+assert.equal(query?.flagSettings.length, 5);
 assert.equal(query?.flagSettings[0]?.alwaysThinkingEnabled, true);
 assert.equal(query?.flagSettings[0]?.effortLevel, "high");
 assert.equal(
diff --git a/src/local-agent-claude.ts b/src/local-agent-claude.ts
index 82184036e..b1a8e4712 100644
--- a/src/local-agent-claude.ts
+++ b/src/local-agent-claude.ts
@@ -127,12 +127,6 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
         await this.query.applyFlagSettings(flagSettings);
         await this.query.setPermissionMode(claudePermissionMode(effectiveWriteMode));
         if (input.model && this.query.setModel) await this.query.setModel(input.model);
-        this.inputQueue.push({
-          type: "user",
-          message: { role: "user", content: input.prompt },
-          parent_tool_use_id: null,
-        });
-
         let cancellation: Promise<boolean> | undefined;
         const abort = () => {
           cancellation ??= this.query.interrupt
@@ -141,6 +135,15 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
         };
         if (control?.signal.aborted) throw new DOMException("Aborted", "AbortError");
         control?.signal.addEventListener("abort", abort, { once: true });
+        if (control?.signal.aborted) {
+          control.signal.removeEventListener("abort", abort);
+          throw new DOMException("Aborted", "AbortError");
+        }
+        this.inputQueue.push({
+          type: "user",
+          message: { role: "user", content: input.prompt },
+          parent_tool_use_id: null,
+        });
         const items: unknown[] = [];
         try {
           for (;;) {
diff --git a/src/local-agent-client.ts b/src/local-agent-client.ts
index 5e373c1bb..4a08b6b01 100644
--- a/src/local-agent-client.ts
+++ b/src/local-agent-client.ts
@@ -334,7 +334,7 @@ export class LocalAgentClient {
         operation: "startup",
         retryable: true,
         cause: mismatch,
-        message: "An older local agent daemon is still running active turns. Retry after they finish.",
+        message: "An older local agent daemon is still running active turns or workflows. Retry after they finish.",
       }));
     }
 
@@ -404,8 +404,13 @@ export class LocalAgentClient {
     params: Extract<LocalAgentDaemonRequest, { method: M }>['params'],
     timeoutMs: number | null = this.requestTimeoutMs,
   ): Promise<BetterResult<unknown, RequestError<M>>> {
-    const observation = isObservationRequest(method) || (method === "workflow.request"
-      && ["get", "wait", "list", "control"].includes((params as WorkflowRequest).operation));
+    const workflowRequest = method === "workflow.request" ? params as WorkflowRequest : undefined;
+    const observation = isObservationRequest(method)
+      || workflowRequest?.operation === "get"
+      || workflowRequest?.operation === "wait"
+      || workflowRequest?.operation === "list"
+      || (workflowRequest?.operation === "control"
+        && ["pause", "stop", "stop_agent"].includes(workflowRequest.input.action));
     const ready = await (observation
       ? this.ensureReadyForObservation()
       : this.ensureReady());
diff --git a/src/local-agent-codex.test.ts b/src/local-agent-codex.test.ts
index 091ea7e5e..0d658c30f 100644
--- a/src/local-agent-codex.test.ts
+++ b/src/local-agent-codex.test.ts
@@ -66,7 +66,11 @@ readline.createInterface({ input: process.stdin }).on("line", (line) => {
     const turnId = "turn_" + turn;
     output({ id: message.id, result: { turn: { id: turnId } } });
     active.set(turnId, { threadId: message.params.threadId, prompt: message.params.input[0].text });
-    if (message.params.input[0].text === "hold" || message.params.input[0].text === "ignore interrupt") return;
+    if (message.params.input[0].text === "ignore interrupt") {
+      output({ method: "item/started", params: { threadId: message.params.threadId, turnId, item: { type: "commandExecution" } } });
+      return;
+    }
+    if (message.params.input[0].text === "hold") return;
     setImmediate(() => {
       if (message.params.input[0].text === "fail") {
         output({ method: "turn/completed", params: { threadId: message.params.threadId, turn: { id: turnId, status: "failed", error: { message: "fake failure" } } } });
@@ -108,6 +112,14 @@ readline.createInterface({ input: process.stdin }).on("line", (line) => {
   const runtime = new CodexAppServerRuntime({ command, env: process.env });
   try {
     await runtime.initialize();
+    const preAborted = new AbortController();
+    preAborted.abort();
+    const rejectedBeforeTurn = await runtime.run({
+      prompt: "cancelled-before-turn",
+      workspaceRoot: "/tmp/project",
+    }, undefined, { signal: preAborted.signal });
+    assert.equal(rejectedBeforeTurn.isErr(), true);
+    if (rejectedBeforeTurn.isErr()) assert.equal(rejectedBeforeTurn.error.code, "PROVIDER_CANCELLED");
     let callbackSessionId: string | undefined;
     const usageUpdates: unknown[] = [];
     const firstResult = await runtime.run({
@@ -212,16 +224,18 @@ readline.createInterface({ input: process.stdin }).on("line", (line) => {
     assert.equal(cancelled.isErr(), true);
     if (cancelled.isErr()) assert.equal(cancelled.error.code, "PROVIDER_CANCELLED");
     const ignoredController = new AbortController();
+    let ignoredTurnStarted!: () => void;
+    const ignoredTurnStart = new Promise<void>((resolve) => { ignoredTurnStarted = resolve; });
     const ignored = runtime.run({
       prompt: "ignore interrupt",
       workspaceRoot: "/tmp/project",
       providerSessionId: first.providerSessionId ?? undefined,
-    }, undefined, { signal: ignoredController.signal });
-    await new Promise<void>((resolve) => setImmediate(resolve));
+    }, { onProgress: () => { ignoredTurnStarted(); } }, { signal: ignoredController.signal });
+    await ignoredTurnStart;
     ignoredController.abort();
     const lateSuccess = await ignored;
-    assert.equal(lateSuccess.isOk(), true, "an abort signal alone must not overwrite the provider's terminal result");
     if (lateSuccess.isErr()) throw lateSuccess.error;
+    assert.equal(lateSuccess.isOk(), true, "an abort signal alone must not overwrite the provider's terminal result");
     assert.equal(lateSuccess.value.finalResponse, "late success");
     await runtime.releaseSession("thread_new");
   } finally {
diff --git a/src/local-agent-codex.ts b/src/local-agent-codex.ts
index b1bbb0941..a8fc75b3e 100644
--- a/src/local-agent-codex.ts
+++ b/src/local-agent-codex.ts
@@ -415,6 +415,7 @@ class CodexAppServerRpc {
     onEvent?: (event: CodexEvent) => void | Promise<void>,
   ): Promise<CodexTurnResult> {
     if (this.fatalError) throw this.fatalError;
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
     if (this.turns.has(threadId)) throw new Error(`Codex thread ${threadId} already has an active turn.`);
     let resolveTurn!: (result: CodexTurnResult) => void;
     let rejectTurn!: (error: Error) => void;
diff --git a/src/local-agent-opencode.test.ts b/src/local-agent-opencode.test.ts
index 16e7d13a6..af19c1ff5 100644
--- a/src/local-agent-opencode.test.ts
+++ b/src/local-agent-opencode.test.ts
@@ -266,7 +266,10 @@ if (rateLimited.isErr()) {
 }
 
 let timeoutAbortCount = 0;
+let timeoutPromptCount = 0;
 let rejectOpenCodePrompt: ((error: Error) => void) | undefined;
+let fenceTimeoutAbort = false;
+let finishTimeoutAbort: (() => void) | undefined;
 const timeoutClient = {
   global: {
     async health() { return { data: { healthy: true } }; },
@@ -274,6 +277,7 @@ const timeoutClient = {
   session: {
     async create() { return { data: { id: "session_timeout" } }; },
     async prompt(_input: unknown, options?: { signal?: AbortSignal }) {
+      timeoutPromptCount += 1;
       return new Promise<never>((_resolve, reject) => {
         rejectOpenCodePrompt = reject;
         options?.signal?.addEventListener("abort", () => reject(new DOMException("Aborted", "AbortError")), { once: true });
@@ -281,16 +285,34 @@ const timeoutClient = {
     },
     async abort() {
       timeoutAbortCount += 1;
+      if (fenceTimeoutAbort) await new Promise<void>((resolve) => { finishTimeoutAbort = resolve; });
       rejectOpenCodePrompt?.(new Error("server stopped the prompt"));
       return { data: true };
     },
   },
 } as unknown as OpencodeClientLike;
+const preAbortedRuntime = new OpencodeRuntime(timeoutClient, { close: () => undefined }, 60_000);
+const preAborted = new AbortController();
+preAborted.abort();
+const rejectedBeforePrompt = await preAbortedRuntime.run({
+  prompt: "do not submit", workspaceRoot: "/tmp/project",
+}, undefined, { signal: preAborted.signal });
+assert.equal(rejectedBeforePrompt.isErr(), true);
+assert.equal(timeoutPromptCount, 0);
+await preAbortedRuntime.close();
+
 const timeoutRuntime = new OpencodeRuntime(timeoutClient, { close: () => undefined }, 5);
-const timedOutPrompt = await timeoutRuntime.run({
+fenceTimeoutAbort = true;
+let timeoutSettled = false;
+const timedOutPromptPromise = timeoutRuntime.run({
   prompt: "never finishes",
   workspaceRoot: "/tmp/project",
-});
+}).then((result) => { timeoutSettled = true; return result; });
+await new Promise<void>((resolve) => setTimeout(resolve, 15));
+assert.equal(timeoutSettled, false, "timeout remains fenced until server-side cancellation settles");
+finishTimeoutAbort?.();
+fenceTimeoutAbort = false;
+const timedOutPrompt = await timedOutPromptPromise;
 assert.equal(timedOutPrompt.isErr(), true);
 if (timedOutPrompt.isErr()) {
   assert.equal(timedOutPrompt.error.code, "PROVIDER_PROTOCOL_ERROR");
@@ -314,6 +336,28 @@ if (cancelledResult.isErr()) assert.equal(cancelledResult.error.code, "PROVIDER_
 assert.equal(timeoutAbortCount, 2);
 await cancellableRuntime.close();
 
+const uncertainClient = {
+  global: { async health() { return { data: { healthy: true } }; } },
+  session: {
+    async create() { return { data: { id: "session_uncertain" } }; },
+    async prompt(_input: unknown, options?: { signal?: AbortSignal }) {
+      return new Promise<never>((_resolve, reject) => {
+        options?.signal?.addEventListener("abort", () => reject(new DOMException("Aborted", "AbortError")), { once: true });
+      });
+    },
+    async abort() { throw new Error("cancellation failed"); },
+  },
+} as unknown as OpencodeClientLike;
+const uncertainRuntime = new OpencodeRuntime(uncertainClient, { close: () => undefined }, 5);
+const uncertainTimeout = await uncertainRuntime.run({ prompt: "uncertain", workspaceRoot: "/tmp/project" });
+assert.equal(uncertainTimeout.isErr(), true);
+if (uncertainTimeout.isErr()) {
+  assert.equal(uncertainTimeout.error.retryable, false);
+  assert.equal(uncertainTimeout.error.executionUncertain, true);
+}
+assert.equal(uncertainRuntime.isAlive(), false);
+await uncertainRuntime.close();
+
 assert.equal(opencodeAgentFor("read_only"), "devspace_read_only");
 assert.equal(opencodeAgentFor("full_access"), "devspace_full_access");
 assert.equal(opencodeAgentFor("allowed", "none"), "devspace_no_tools");
diff --git a/src/local-agent-opencode.ts b/src/local-agent-opencode.ts
index e42692f75..d2e6bc831 100644
--- a/src/local-agent-opencode.ts
+++ b/src/local-agent-opencode.ts
@@ -138,6 +138,7 @@ export class OpencodeRuntime implements LocalAgentRuntime {
     input: LocalAgentRunInput,
     signal?: AbortSignal,
   ): Promise<unknown> {
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
     const controller = new AbortController();
     this.promptControllers.add(controller);
     let timedOut = false;
@@ -150,27 +151,39 @@ export class OpencodeRuntime implements LocalAgentRuntime {
         directory: input.workspaceRoot,
       }, { throwOnError: true }).then(() => true, () => false);
     };
-    if (signal?.aborted) cancel();
-    else signal?.addEventListener("abort", cancel, { once: true });
+    signal?.addEventListener("abort", cancel, { once: true });
     const timer = setTimeout(() => {
       timedOut = true;
       cancel();
       controller.abort();
     }, this.promptTimeoutMs);
     try {
+      if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
       const result = await promptOpencodeSession(this.client, sessionId, input, controller.signal);
-      if (cancelled && !timedOut && await cancellation) {
-        throw new DOMException("Aborted", "AbortError");
+      if (timedOut) throw new DOMException("Timed out", "TimeoutError");
+      if (cancelled) {
+        const confirmed = await cancellation;
+        if (confirmed) throw new DOMException("Aborted", "AbortError");
+        this.alive = false;
+        throw uncertainOpenCodeCancellation(result);
       }
       return result;
     } catch (error) {
-      if (cancelled && !timedOut && await cancellation) throw new DOMException("Aborted", "AbortError");
+      if (cancelled && !timedOut) {
+        const confirmed = await cancellation;
+        if (confirmed) throw new DOMException("Aborted", "AbortError");
+        this.alive = false;
+        throw uncertainOpenCodeCancellation(error);
+      }
       if (!timedOut) throw error;
+      const confirmed = await cancellation;
+      if (!confirmed) this.alive = false;
       throw new AgentProviderProtocolError({
         code: "PROVIDER_PROTOCOL_ERROR",
         provider: "opencode",
         operation: "prompt",
-        retryable: true,
+        retryable: confirmed === true,
+        executionUncertain: confirmed !== true,
         cause: error,
         message: "OpenCode did not finish the prompt before the provider timeout.",
       });
@@ -182,6 +195,18 @@ export class OpencodeRuntime implements LocalAgentRuntime {
   }
 }
 
+function uncertainOpenCodeCancellation(cause: unknown): AgentProviderProtocolError {
+  return new AgentProviderProtocolError({
+    code: "PROVIDER_PROTOCOL_ERROR",
+    provider: "opencode",
+    operation: "prompt",
+    retryable: false,
+    executionUncertain: true,
+    cause,
+    message: "OpenCode cancellation could not be confirmed.",
+  });
+}
+
 export class OpencodeLocalAgentDriver implements LocalAgentDriver {
   readonly provider = "opencode" as const;
   readonly idleTimeoutMs = 5 * 60_000;
diff --git a/src/local-agent-profiles.test.ts b/src/local-agent-profiles.test.ts
index 07eba4427..a15137e85 100644
--- a/src/local-agent-profiles.test.ts
+++ b/src/local-agent-profiles.test.ts
@@ -73,6 +73,19 @@ try {
   assert.equal(profiles[0]?.effort, "high");
   assert.equal(profiles[0]?.writeMode, "read_only");
   assert.equal(profiles[0]?.body, "Project body.");
+  for (const [name, value] of [
+    ["boolean", "true"],
+    ["number", "1"],
+    ["object", "{ mode: read_only }"],
+    ["array", "[read_only]"],
+  ]) {
+    await writeFile(
+      join(workspaceRoot, ".devspace", "agents", `invalid-write-mode-${name}.md`),
+      `---\nname: invalid-${name}\ndescription: Invalid write mode.\nprovider: codex\nwriteMode: ${value}\n---\nBody.\n`,
+    );
+  }
+  const profilesWithoutInvalidWriteModes = await loadLocalAgentProfiles(enabledConfig, workspaceRoot);
+  assert.deepEqual(profilesWithoutInvalidWriteModes.map((profile) => profile.name), ["reviewer"]);
   await writeFile(
     join(workspaceRoot, ".devspace", "agents", "custom.md"),
     [
diff --git a/src/local-agent-profiles.ts b/src/local-agent-profiles.ts
index d6804f544..b2c51fff2 100644
--- a/src/local-agent-profiles.ts
+++ b/src/local-agent-profiles.ts
@@ -162,7 +162,12 @@ function readWriteMode(
   frontmatter: Record<string, unknown>,
   filePath: string,
 ): LocalAgentWriteMode | undefined {
-  const value = readString(frontmatter, "writeMode");
+  const raw = frontmatter.writeMode;
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "string") {
+    throw new Error(`Subagent profile writeMode must be a string: ${filePath}`);
+  }
+  const value = raw.trim();
   if (!value) return undefined;
   if (value === "read_only" || value === "allowed" || value === "full_access") return value;
   throw new Error(`Subagent profile writeMode must be read_only, allowed, or full_access: ${filePath}`);
diff --git a/src/local-agent-runtime.test.ts b/src/local-agent-runtime.test.ts
index 9a35fa634..f63bc319f 100644
--- a/src/local-agent-runtime.test.ts
+++ b/src/local-agent-runtime.test.ts
@@ -31,6 +31,16 @@ assert.deepEqual(localAgentWorkflowEnvironment({ PATH: "/bin" }, {
   DEVSPACE_WORKFLOW_STEP_ID: "wfs_1",
   DEVSPACE_WORKFLOW_ATTEMPT_ID: "wfa_1",
 });
+assert.deepEqual(localAgentWorkflowEnvironment({
+  PATH: "/bin",
+  DEVSPACE_WORKFLOW_RUN_ID: "stale-run",
+  DEVSPACE_WORKFLOW_STEP_ID: "stale-step",
+  DEVSPACE_WORKFLOW_ATTEMPT_ID: "stale-attempt",
+}, {}), { PATH: "/bin" });
+assert.deepEqual(localAgentWorkflowEnvironment({
+  DEVSPACE_WORKFLOW_RUN_ID: "stale-run",
+  DEVSPACE_WORKFLOW_STEP_ID: "stale-step",
+}, { workflowRunId: "current-run" }), { DEVSPACE_WORKFLOW_RUN_ID: "current-run" });
 
 for (const [code, retryable] of [["ENOENT", false], ["ECONNREFUSED", true], ["ENOTFOUND", true]] as const) {
   const classified = await captureAgentProviderResult({
diff --git a/src/local-agent-runtime.ts b/src/local-agent-runtime.ts
index 3c74fdd71..49125dd15 100644
--- a/src/local-agent-runtime.ts
+++ b/src/local-agent-runtime.ts
@@ -153,10 +153,13 @@ export function localAgentWorkflowEnvironment(
   env: NodeJS.ProcessEnv,
   provenance: Pick<LocalAgentRuntimeContext, "workflowRunId" | "workflowStepId" | "workflowAttemptId">,
 ): NodeJS.ProcessEnv {
-  if (!provenance.workflowRunId) return env;
+  const sanitized = { ...env };
+  delete sanitized.DEVSPACE_WORKFLOW_RUN_ID;
+  delete sanitized.DEVSPACE_WORKFLOW_STEP_ID;
+  delete sanitized.DEVSPACE_WORKFLOW_ATTEMPT_ID;
   return {
-    ...env,
-    DEVSPACE_WORKFLOW_RUN_ID: provenance.workflowRunId,
+    ...sanitized,
+    ...(provenance.workflowRunId ? { DEVSPACE_WORKFLOW_RUN_ID: provenance.workflowRunId } : {}),
     ...(provenance.workflowStepId ? { DEVSPACE_WORKFLOW_STEP_ID: provenance.workflowStepId } : {}),
     ...(provenance.workflowAttemptId ? { DEVSPACE_WORKFLOW_ATTEMPT_ID: provenance.workflowAttemptId } : {}),
   };
diff --git a/src/local-agent-store.ts b/src/local-agent-store.ts
index 6812b38fd..d900458d2 100644
--- a/src/local-agent-store.ts
+++ b/src/local-agent-store.ts
@@ -493,7 +493,7 @@ export class LocalAgentStore {
         .prepare(
           `update local_agent_turns
            set status = 'failed', error = ?, error_code = 'DAEMON_UNAVAILABLE',
-               error_retryable = 'true', completed_at = ?
+               error_retryable = 'true', execution_uncertain = 'true', completed_at = ?
            where status = 'running'`,
         )
         .run(message, now);
diff --git a/src/server.test.ts b/src/server.test.ts
index 417533de6..129c4f918 100644
--- a/src/server.test.ts
+++ b/src/server.test.ts
@@ -364,6 +364,9 @@ test("open_workspace keeps lifecycle flags out of model output and preserves com
     providerNote,
   );
   assert.ok(Array.isArray(firstStructured.agents));
+  const firstText = (first.content as Array<{ type: string; text?: string }>)
+    .find((item) => item.type === "text");
+  assert.match(firstText?.text ?? "", /reviewer \(codex, write_mode read_only\)/);
   assert.ok(Array.isArray(firstStructured.skill_diagnostics));
   assert.equal("workspaceReused" in firstStructured, false);
   assert.equal("includeBootstrapContext" in firstStructured, false);
@@ -752,6 +755,7 @@ async function fixture(
     "name: reviewer",
     "description: Reviews project changes.",
     "provider: codex",
+    "writeMode: read_only",
     "---",
     "Review changes.",
   ].join("\n"));
diff --git a/src/server.ts b/src/server.ts
index fe57b0b83..e12338e03 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -145,10 +145,12 @@ function formatVisibleAgent(agent: {
   provider: string;
   model?: string;
   effort?: string;
+  write_mode?: "read_only" | "allowed" | "full_access";
 }): string {
   const model = agent.model ? `, model ${agent.model}` : "";
   const effort = agent.effort ? `, effort ${agent.effort}` : "";
-  return `${agent.name} (${agent.provider}${model}${effort})`;
+  const writeMode = agent.write_mode ? `, write_mode ${agent.write_mode}` : "";
+  return `${agent.name} (${agent.provider}${model}${effort}${writeMode})`;
 }
 
 function formatAvailableAgentProvider(provider: {
diff --git a/src/skills.test.ts b/src/skills.test.ts
index 357c417db..b6df8627c 100644
--- a/src/skills.test.ts
+++ b/src/skills.test.ts
@@ -33,9 +33,11 @@ try {
   await mkdir(join(projectRoot, ".pi", "skills", "project-skill"), { recursive: true });
   await mkdir(join(agentDir, "skills", "global-skill"), { recursive: true });
   await mkdir(join(agentDir, "skills", "subagents"), { recursive: true });
+  await mkdir(join(agentDir, "skills", "workflows"), { recursive: true });
   await mkdir(join(explicitSkills, "duplicate"), { recursive: true });
   await mkdir(join(explicitSkills, "disabled"), { recursive: true });
   await mkdir(join(explicitSkills, "subagents"), { recursive: true });
+  await mkdir(join(explicitSkills, "workflows"), { recursive: true });
   await mkdir(join(devspaceSkills, "devspace-local-skill"), { recursive: true });
 
   await writeFile(
@@ -148,6 +150,28 @@ try {
       "# Subagent Delegation Duplicate",
     ].join("\n"),
   );
+  await writeFile(
+    join(agentDir, "skills", "workflows", "SKILL.md"),
+    [
+      "---",
+      "name: workflows",
+      "description: User workflow skill winner.",
+      "---",
+      "",
+      "# User Workflows",
+    ].join("\n"),
+  );
+  await writeFile(
+    join(explicitSkills, "workflows", "SKILL.md"),
+    [
+      "---",
+      "name: workflows",
+      "description: User workflow skill loser.",
+      "---",
+      "",
+      "# Duplicate User Workflows",
+    ].join("\n"),
+  );
   await writeFile(
     join(explicitSkills, "disabled", "SKILL.md"),
     [
@@ -185,6 +209,7 @@ try {
   assert.equal(loaded.skills.some((skill) => skill.name === "project-skill"), false);
   assert.equal(loaded.skills.some((skill) => skill.name === "devspace-local-skill"), true);
   assert.equal(loaded.skills.some((skill) => skill.name === "subagents"), false);
+  assert.equal(loaded.skills.some((skill) => skill.name === "workflows"), true);
   assert.equal(loaded.skills.filter((skill) => skill.name === "duplicate-skill").length, 1);
   assert.equal(loaded.skills.some((skill) => skill.name === "hidden-skill"), true);
   assert.equal(loaded.diagnostics.some((diagnostic) => diagnostic.type === "collision"), true);
@@ -194,6 +219,10 @@ try {
     ),
     false,
   );
+  assert.equal(
+    loaded.diagnostics.some((diagnostic) => diagnostic.collision?.name === "workflows"),
+    true,
+  );
 
   await mkdir(join(devspaceSkills, "subagents"), { recursive: true });
   await writeFile(
diff --git a/src/skills.ts b/src/skills.ts
index b5c6bb808..afed9adac 100644
--- a/src/skills.ts
+++ b/src/skills.ts
@@ -98,7 +98,10 @@ export function loadWorkspaceSkills(config: ServerConfig, cwd: string): LoadedSk
     cwd, agentDir: config.agentDir,
     skillPaths: effectiveSkillPaths(config, cwd), includeDefaults: false,
   });
-  const managedNames = new Set<string>(MANAGED_SKILLS);
+  const managedNames = new Set<string>([
+    "subagents",
+    ...(config.workflows?.enabled ? ["workflows"] : []),
+  ]);
   const managed = enabled.map((name) => {
     const skill = loadSkillsFromDir({ dir: join(config.devspaceSkillsDir, name), source: "devspace" })
       .skills.find((skill) => skill.name === name);
diff --git a/src/workflow-daemon.test.ts b/src/workflow-daemon.test.ts
index 220f2f668..90724265a 100644
--- a/src/workflow-daemon.test.ts
+++ b/src/workflow-daemon.test.ts
@@ -37,6 +37,14 @@ test("workflow daemon transport preserves active runs and allows observation aft
   assert.equal(launch.ok, false, "a changed configuration must not replace a daemon with active workflows");
   assert.equal(spawned, false);
   assert.equal(closed, false);
+  const resumed = await changedConfig.workflow({ operation: "control", scope,
+    input: { runId: "r", action: "resume" } });
+  assert.equal(resumed.ok, false, "resume must use a daemon with the current execution configuration");
+  assert.equal(activeRuns, 1);
+  const restarted = await changedConfig.workflow({ operation: "control", scope,
+    input: { runId: "r", action: "restart_agent", stepId: "step-1" } });
+  assert.equal(restarted.ok, false, "agent restart must use a daemon with the current execution configuration");
+  assert.equal(activeRuns, 1);
   const stopped = await changedConfig.workflow({ operation: "control", scope, input: { runId: "r", action: "stop" } });
   assert.equal(stopped.ok, true);
   assert.equal(activeRuns, 0);
diff --git a/src/workflow-manager.test.ts b/src/workflow-manager.test.ts
index f6acd01f0..b93c82cbf 100644
--- a/src/workflow-manager.test.ts
+++ b/src/workflow-manager.test.ts
@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -23,6 +23,7 @@ import { LocalAgentStore } from "./local-agent-store.js";
 import type { SubagentsConfig } from "./local-agent-config.js";
 import { createWorkflowManager } from "./workflow-manager.js";
 import type { WorkflowReply, WorkflowRequest, WorkflowScope } from "./workflow-protocol.js";
+import { WorkflowRegistry } from "./workflow-registry.js";
 import { WorkflowStore } from "./workflow-store.js";
 
 const root = await mkdtemp(join(tmpdir(), "devspace-workflow-manager-"));
@@ -93,11 +94,20 @@ const agents = new LocalAgentManager({
   validateWorkspaceScope: ({ workspaceRoot }) => workspaceRoot,
 });
 const workflowStore = new WorkflowStore(database);
+class CountingWorkflowRegistry extends WorkflowRegistry {
+  discoveries = 0;
+  override async discover(workspaceRoot: string) {
+    this.discoveries += 1;
+    return super.discover(workspaceRoot);
+  }
+}
+const workflowRegistry = new CountingWorkflowRegistry();
 let worktrees = 0;
 const workflowsConfig = { ...defaultWorkflowsConfig(), enabled: true, defaultAgentType: "reviewer", maxConcurrentRuns: 1 };
 const manager = createWorkflowManager({
   stateDir, agents, agentStore, store: workflowStore,
   config: workflowsConfig,
+  registry: workflowRegistry,
   validateScope: async (candidate) => {
     assert.deepEqual(candidate, scope);
     return candidate;
@@ -134,6 +144,11 @@ return await agent('inspect', { schema: {
   const exportDir = join(root, ".devspace", "workflows", "runs", first.runId);
   assert.equal(JSON.parse(await readFile(join(exportDir, "result.json"), "utf8")).ok, true);
   assert.match(await readFile(join(exportDir, "journal.jsonl"), "utf8"), /"type":"run_state"/);
+  const journalMtime = (await stat(join(exportDir, "journal.jsonl"))).mtimeMs;
+  await delay(20);
+  assert.equal((await manager.request({ operation: "get", scope, input: { runId: first.runId } })).ok, true);
+  assert.equal((await stat(join(exportDir, "journal.jsonl"))).mtimeMs, journalMtime,
+    "terminal observations reuse the exported journal");
 
   const callCount = calls.length;
   const resumed = await run(`
@@ -240,6 +255,7 @@ return await workflow('child')`, { resumeFromRunId: nested.runId });
 export const meta = { name: 'queued-child', description: 'Nested queue child' }
 return await agent(args.prompt)`);
   const nestedQueueCallCount = calls.length;
+  const nestedQueueDiscoveries = workflowRegistry.discoveries;
   const queuedNested = await run(`
 export const meta = { name: 'queued-parent', description: 'Nested queue parent' }
 return await parallel([
@@ -253,6 +269,8 @@ return await parallel([
     await delay(5);
   }
   assert.equal(calls.length, nestedQueueCallCount + 1, "only the child holding the nested slot dispatches an agent");
+  assert.equal(workflowRegistry.discoveries, nestedQueueDiscoveries + 1,
+    "parallel nested name lookups share one discovery snapshot per run");
   const queuedStop = await manager.request({ operation: "control", scope,
     input: { runId: queuedNested.runId, action: "stop" } });
   assert.equal(queuedStop.ok, true);
@@ -426,6 +444,9 @@ return await agent('hold-stop')`);
     agentId: recoveringAgent.id, agentTurnId: recoveringTurn.id, reason: "initial" });
   workflowStore.transitionAttempt(recoveringAttempt.id, "running");
   workflowStore.markActiveAttemptsUncertain();
+  agentStore.reconcileActiveRuns();
+  assert.equal(agentStore.getTurnById(recoveringTurn.id)?.status, "failed");
+  assert.equal(agentStore.getTurnById(recoveringTurn.id)?.executionUncertain, true);
   const blockedResume = await manager.request({ operation: "run", scope, input: { resumeFromRunId: recovering.id,
     script: `export const meta = { name: 'recovering', description: 'known live turn' }\nreturn null` } });
   assert.equal(blockedResume.ok, false);
diff --git a/src/workflow-manager.ts b/src/workflow-manager.ts
index fd9e0122d..a969cb5fd 100644
--- a/src/workflow-manager.ts
+++ b/src/workflow-manager.ts
@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, realpath, writeFile } from "node:fs/promises";
+import { mkdir, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { resolvePathInsideCanonicalRoot } from "./roots.js";
 import type { WorkflowsConfig } from "./workflow-config.js";
@@ -22,7 +22,7 @@ import type {
   WorkflowRuntimeLimits,
 } from "./workflow-types.js";
 import type { WorkflowReply, WorkflowRequest, WorkflowScope } from "./workflow-protocol.js";
-import { WorkflowRegistry } from "./workflow-registry.js";
+import { WorkflowRegistry, type WorkflowDiscoveryResult } from "./workflow-registry.js";
 import {
   WorkflowStore,
   type WorkflowError,
@@ -93,6 +93,7 @@ interface ActiveRun {
   stopRequested: boolean;
   activeClock: ActiveTimeClock;
   waitingUsageAttempts: number;
+  workflowDiscovery?: Promise<WorkflowDiscoveryResult>;
 }
 
 interface LiveStep {
@@ -208,10 +209,13 @@ export class WorkflowManager {
     }
     const sourceRun = input.resumeFromRunId ? this.requireRun(scope, input.resumeFromRunId) : undefined;
     if (sourceRun?.state === "recovery_required") {
-      const hasKnownLiveTurn = this.store.listAttemptsForRun(sourceRun.id)
-        .some((attempt) => this.agentStore.getTurnById(attempt.agentTurnId)?.status === "running");
-      if (hasKnownLiveTurn) throw workflowFailure("WORKFLOW_BUSY",
-        "The source workflow still has a live provider turn; recover or stop it before resuming.", true);
+      const hasUnconfirmedTurn = this.store.listAttemptsForRun(sourceRun.id)
+        .some((attempt) => {
+          const turn = this.agentStore.getTurnById(attempt.agentTurnId);
+          return turn?.status === "running" || turn?.executionUncertain === true;
+        });
+      if (hasUnconfirmedTurn) throw workflowFailure("WORKFLOW_BUSY",
+        "The source workflow has a provider turn whose termination is unconfirmed; reconcile it before resuming.", true);
     }
     const defaults = compactJson({
       ...(sourceRun?.defaults ?? {}),
@@ -805,7 +809,7 @@ export class WorkflowManager {
   private async nested(context: RuntimeContext, request: WorkflowNestedRequest, bridge: WorkflowBridgeContext): Promise<WorkflowBridgeReply> {
     if (context.depth >= 1) throw workflowFailure("NESTING_LIMIT", "Nested workflows are limited to one child level.");
     const definition = typeof request.reference === "string"
-      ? await this.registry.resolveName(context.scope.workspaceRoot, request.reference)
+      ? await this.resolveNestedName(context, request.reference)
       : await this.registry.resolvePath(context.scope.workspaceRoot, request.reference.scriptPath,
           context.run.sourcePath ? dirname(context.run.sourcePath) : context.scope.workspaceRoot);
     await preflightWorkflowScript(definition.parsed, { limits: runtimeLimits(this.config) });
@@ -848,6 +852,13 @@ export class WorkflowManager {
     }
   }
 
+  private async resolveNestedName(context: RuntimeContext, name: string) {
+    context.active.workflowDiscovery ??= this.registry.discover(context.scope.workspaceRoot);
+    const definition = (await context.active.workflowDiscovery).definitions.find((item) => item.name === name);
+    if (!definition) throw new Error(`WORKFLOW_NOT_FOUND: ${name}`);
+    return definition;
+  }
+
   private runtimeEvent(context: RuntimeContext, event: WorkflowRuntimeEvent): void {
     context.active.eventCount += 1;
     if (context.active.eventCount > this.config.limits.eventsPerRun) {
@@ -1010,7 +1021,10 @@ export class WorkflowManager {
       type: "export_truncated", payload: { limit: this.config.limits.eventsPerRun } }));
     const journalText = lines.join("\n") + (lines.length ? "\n" : "");
     const journal = await this.writeExport(run, "journal.jsonl", journalText);
-    if (run.result === undefined) return { journal };
+    if (run.result === undefined) {
+      this.store.setResultArtifactId(run.id, journal.id);
+      return { journal };
+    }
     const result = await this.writeExport(run, "result.json", `${JSON.stringify(run.result)}\n`);
     this.store.setResultArtifactId(run.id, result.id);
     return { journal, result };
@@ -1047,7 +1061,9 @@ export class WorkflowManager {
     let exports: Awaited<ReturnType<WorkflowManager["exportRunArtifacts"]>> | undefined;
     let exportWarning: JsonObject | undefined;
     if (TERMINAL_STATES.has(run.state)) {
-      try { exports = await this.exportRunArtifacts(run); }
+      try { exports = run.resultArtifactId
+        ? await this.existingRunArtifacts(run)
+        : await this.exportRunArtifacts(run); }
       catch (error) { exportWarning = { code: "ARTIFACT_EXPORT_FAILED", message: errorMessage(error) }; }
     }
     const largeResult = run.result !== undefined && jsonByteLength(run.result) > 64 * 1024;
@@ -1097,6 +1113,27 @@ export class WorkflowManager {
     } as unknown as JsonObject);
   }
 
+  private async existingRunArtifacts(run: WorkflowRunRecord): Promise<{
+    journal: { id: string; path: string; bytes: number };
+    result?: { id: string; path: string; bytes: number };
+  }> {
+    const journal = await this.exportReference(run, "journal.jsonl");
+    const result = run.result === undefined ? undefined : await this.exportReference(run, "result.json");
+    return { journal, ...(result ? { result } : {}) };
+  }
+
+  private async exportReference(run: WorkflowRunRecord, filename: string): Promise<{
+    id: string; path: string; bytes: number;
+  }> {
+    const canonicalRoot = await realpath(run.workspaceRoot);
+    const path = await resolvePathInsideCanonicalRoot(
+      join(".devspace", "workflows", "runs", run.id, filename),
+      canonicalRoot, canonicalRoot, canonicalRoot,
+    );
+    const { size } = await stat(path);
+    return { id: `workflow:${run.id}:${filename}`, path, bytes: size };
+  }
+
   private changeRun(
     runId: string, state: WorkflowState, reason?: string, result?: JsonValue,
     omittedResult?: boolean, error?: WorkflowError,
diff --git a/src/workflow-script.test.ts b/src/workflow-script.test.ts
index ef91bc731..a805f7754 100644
--- a/src/workflow-script.test.ts
+++ b/src/workflow-script.test.ts
@@ -19,6 +19,9 @@ assert.doesNotMatch(parsed.body, /export const meta/);
 const renamed = renameWorkflowMeta(valid, "verify-code");
 assert.equal(parseWorkflowScript(renamed).meta.name, "verify-code");
 assert.match(renamed, /description: "Review\\ncode"/);
+const parenthesized = `export const meta = ({ name: 'old-name', description: 'Parenthesized' })\nreturn null`;
+const renamedParenthesized = renameWorkflowMeta(parenthesized, "new-name");
+assert.equal(parseWorkflowScript(renamedParenthesized).meta.name, "new-name");
 
 for (const source of [
   `export const meta = makeMeta()\nreturn null`,
diff --git a/src/workflow-script.ts b/src/workflow-script.ts
index ab93523a5..7fe73df4b 100644
--- a/src/workflow-script.ts
+++ b/src/workflow-script.ts
@@ -27,8 +27,20 @@ export function parseWorkflowScript(
   }
 
   const file = ts.createSourceFile(filename, source, ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS);
-  const parseDiagnostics = (file as ts.SourceFile & { parseDiagnostics?: readonly ts.Diagnostic[] }).parseDiagnostics ?? [];
-  const diagnostic = parseDiagnostics[0];
+  const compilerOptions: ts.CompilerOptions = {
+    allowJs: true,
+    noEmit: true,
+    noLib: true,
+    noResolve: true,
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+  };
+  const host = ts.createCompilerHost(compilerOptions);
+  host.getSourceFile = (requested) => requested === filename ? file : undefined;
+  host.fileExists = (requested) => requested === filename;
+  host.readFile = (requested) => requested === filename ? source : undefined;
+  host.writeFile = () => undefined;
+  const diagnostic = ts.createProgram([filename], compilerOptions, host).getSyntacticDiagnostics(file)[0];
   if (diagnostic) {
     const start = diagnostic.start ?? 0;
     throw new WorkflowScriptError(
@@ -101,7 +113,11 @@ export function renameWorkflowMeta(source: string, newName: string, filename = "
   }
   const file = ts.createSourceFile(filename, source, ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS);
   const statement = file.statements[0] as ts.VariableStatement;
-  const initializer = statement.declarationList.declarations[0]!.initializer as ts.ObjectLiteralExpression;
+  let initializer = statement.declarationList.declarations[0]!.initializer!;
+  while (ts.isParenthesizedExpression(initializer)) initializer = initializer.expression;
+  if (!ts.isObjectLiteralExpression(initializer)) {
+    throw new WorkflowScriptError("WORKFLOW_META_INVALID", "Workflow metadata must be an object literal.");
+  }
   const property = initializer.properties.find((candidate) =>
     ts.isPropertyAssignment(candidate) && propertyName(file, candidate.name) === "name");
   if (!property || !ts.isPropertyAssignment(property)) {
diff --git a/test/workflow-cli-smoke.test.ts b/test/workflow-cli-smoke.test.ts
index d07446fa6..ccebb673f 100644
--- a/test/workflow-cli-smoke.test.ts
+++ b/test/workflow-cli-smoke.test.ts
@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
 import { mkdtemp, mkdir, writeFile, readFile, realpath, rm, access } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import test from "node:test";
@@ -10,7 +11,7 @@ import { writeDevspaceConfig } from "../src/user-config.js";
 const execute = promisify(execFile);
 // Run after compiling dist. No installation and no live provider credentials are needed.
 test("compiled CLI coordinates a real daemon, adapter process, managed worktree, and persisted replay", { skip: process.platform === "win32" }, async () => {
-  const root = await realpath(await mkdtemp("/tmp/devspace-workflow-package-"));
+  const root = await realpath(await mkdtemp(join(tmpdir(), "devspace-workflow-package-")));
   const project = join(root, "project");
   const configDir = join(root, "config");
   await mkdir(project);