Workflows: Starlark scripts orchestrate child agent chats, engine half (stacked on #708)

[katulevskiy]

Stacked on #708 (goal mode, which is stacked on #707). Until those merge, this PR's diff also contains their commits; review git log goal-mode..workflows-engine (24 commits).

Summary

Dynamic workflows, the engine half. The agent writes a Starlark script that orchestrates many child agent chats (phases, parallel fan-out, typed results, shell gates, reports, artifacts). The user approves it, the engine runs it in the background with a journal, resume and throttling, and the result is delivered to the parent chat. State, events, RPCs and MCP tools are designed for the workflow card and run pane (next PR), mobile, and saved workflows.

This PR adds no card UI: the transcript shows approval, started/completed/stopped marker rows and the result message only.

Screenshots

Captured from the real desktop app against the mock harness (ZERON_MOCK_WORKFLOW=1; the child agents are scripted, not real models). The approval prompt is the stock question UI, and the dedicated dialog comes in the card PR.

Approval: phases, agents, literal commands, limits, script

Running

Completed, and the result delivered to the parent chat

Stopped by a provider error (resumable)

Design

• zeron-workflow (new, pure crate): Starlark runtime (starlark pinned, pure Rust: blake3 uses its pure feature so aarch64 needs no C compiler), static analysis with path:line:col diagnostics producing a WorkflowGraph, and an idempotent pure reducer. No tokio. Wire and state types live in zeron-proto so clients never link the interpreter (checked: no starlark under zeron-mobile, zeron-client, zeron-doc).
• Language: scripts define main(args). Hermetic (no clock, random, env or IO beyond the API), no while, no recursion, so scripts always terminate. agent()/.ask() return handles dispatched immediately; .result() joins; failures are values (ok/error), not exceptions. run(cmd, args) needs a literal command (shown at approval and re-checked at run time). Also phase, pmap, files/git read-only queries, report, artifact.*, and schema.* helpers for typed results.
• Replay: host effects are journaled by (call site, ordinal), so a re-run answers from the journal; resume pins the script hash and checks input hashes.
• Ask layer extended (from Goal mode: /goal keeps a chat working until a verifier chat confirms (stacked on #707) #708): persistent actors (hidden child chats reused across asks) and an actor-only escalate tool. A workflow may mix harnesses per actor.
• Scheduler: per-actor FIFO, a global cap, a per-model gate moved by an AIMD governor, provider-fault redrive with backoff, deterministic provider errors stop the run (resumable), stall notice, budgets.
• State and sync: event-sourced run state projected into meta.workflowRuns (one small Loro map entry per run/actor/node, host-only writer, coalesced to one write per 250 ms). Full results stay in a device-local JSONL journal. Measured on a 200-node, 20-actor run with instant agents: 1805 events, 6 doc writes, ~107 KB of deltas.
• Approval: an ordinary input question on the live turn carrying the graph in an additive meta field. Scripts with problems are rejected before anything is created.
• Delivery: exactly one machine-origin result message in the parent chat through the normal queue. Goals defer verification while a workflow of that chat runs.
• MCP: workflow_guide, start_workflow, get_workflow_run, list_workflow_runs, stop_workflow_run, resume_workflow_run, resolve_workflow_question; actor-only submit_result and escalate. The authoring guide (docs/workflow-guide.md) is embedded and its worked example is executed in a test.
• Security: hermetic interpreter, literal commands, user approval by default, cwd confinement, safe-alphabet ids, escaped untrusted text, children never widen permissions.
• Prompt text adapted from ZCode (Apache-2.0); attribution in THIRD_PARTY_NOTICES.md. Details: docs/workflows.md.

Testing

• zeron-workflow 60 (reducer, analysis, runtime limits and determinism, the guide's example against a fake host), zeron-proto 74, zeron-mcp 36, zeron-doc workflow tests.
• zeron-engine: lib 429; workflows 20 (scheduling, journal/resume, approval, delivery, restart, budgets, escalation, goal deferral, artifacts); workflow_e2e 2 (real child chats and the real approval question); ask_child 16; goal_mode 15.
• cargo check --workspace --all-targets passes; cargo check -p zeron-workflow --target aarch64-unknown-linux-musl passes; clippy clean with -D warnings on the new crate.

Known limitations / deviations

• agent(isolate="worktree") is not built; parallel writers share the workspace (documented, with guidance in the authoring guide).
• start_workflow blocks until the user answers; a harness that times out the tool call (e.g. Codex's default) denies the run. Documented.
• A resume creates a new run (resumedFrom) that replays the old journal.
• Escalation waits poll (at most ~45 s per call).

Not verified

• Windows, macOS, iOS and Android builds (only the aarch64-musl check of the new crates was run).
• A run with a real model and real child harnesses (Claude/Codex): the demo uses scripted agents.
• Pre-existing, unrelated failure: m5_repos_diffs_terminals::diff_capture_tracked_untracked_and_checksum fails on the base branch too.

[katulevskiy]

Force-pushed: rebased the stack onto current main (80b946b, v0.2.101). CI was failing on the stacked PRs because the merged Cargo.lock had zeron-workflow at 0.2.100 while the workspace is now 0.2.101, so every --locked job stopped at once. The lockfile now differs from main only by our own packages. Also adapted to upstream's new zeron-voice crate and SettingsSection::Voice (lock and shell conflicts), and the dictation test helper for the new UserInputQuestion.meta field. Verified locally with --locked: zeron-workflow 60, workflows 20, workflow_e2e 2, goal_mode 16, ask_child 16.