Problem

CodeWhale needs a workflow authoring surface that is powerful enough for the parent agent to plan real dynamic orchestration instead of issuing ad hoc agent_open calls turn by turn. The existing WhaleFlow direction is solid at the execution boundary, but its documented authoring path is currently Starlark/YAML. If the goal is maximum agent capability and broad developer familiarity, TypeScript/JavaScript should be evaluated as the first-class workflow authoring language rather than treating it as an afterthought.

The important boundary is that JavaScript/TypeScript should author workflows, not become an unsupervised second runtime that secretly owns files, shell, network, cancellation, or provider calls. CodeWhale should compile or lower the authored workflow into typed WhaleFlow IR, then execute it through the Rust scheduler and the headless worker runtime tracked in #3096.

Evidence

• docs/VISION_NORTH_STAR.md describes WhaleFlow as Starlark/YAML -> typed Rust IR -> Rust executor, with /workflow, /whaleflow, and workflow_run as the intended product surface.
• crates/whaleflow/src/lib.rs already has typed workflow primitives: WorkflowSpec, WorkflowNode, LeafSpec, BudgetSpec, PermissionSpec, model policy, replay, and validation.
• crates/whaleflow/src/starlark_authoring.rs already compiles an authoring language into WorkflowSpec, but deliberately blocks load, import, async, await, and open. That is a good safety boundary, but it also limits expressiveness and familiar agent-authored workflow code.
• workflows/rlm_cache_change.star and workflows/issue_fix_tournament.star prove the authoring concept exists, but only through Starlark today.
• EPIC: v0.9.0 WhaleFlow branch/leaf workflow mode (tracker, replaces deleted #2667) #2981 tracks the v0.9 WhaleFlow epic; whaleflow: real async executor — replace MockWorkflowExecutor #2973 tracks the real Rust async executor; whaleflow: wire codewhale-whaleflow into tui/cli (currently zero dependents) #2974 tracks wiring WhaleFlow into TUI/CLI. None of those specifically decide the most capable authoring language contract.
• v0.8.59: Split sub-agents into a headless worker runtime with lightweight TUI projections #3096 tracks the headless worker runtime that should execute workflow leaves without making sub-agents feel like nested TUI sessions.
• AdityaVG13's closed PR feat: add WhaleFlow — declarative multi-agent workflow orchestration #2482 and open PR Feat/whaleflow cost tracking #2486 are important prior art: they attempted JSON-driven orchestration, workflow_run, scheduler/backpressure, worktree isolation, and cost tracking. Their review notes also surface issues this design must not repeat: detached tasks on abort, missing max_steps/timeout_secs schema, nondeterministic phase order, committed worktree changes dropped, same-phase depends_on_results silently empty, and cost values not actually propagated.

Proposed direction

Make TypeScript/JavaScript the first-class high-capability workflow authoring option for CodeWhale, while keeping WhaleFlow typed IR and the Rust executor as the canonical runtime boundary.

A good target shape:

• Support agent-authored .workflow.ts and/or .workflow.js files using a small CodeWhale workflow SDK: workflow, sequence, branch, agent, reduce, loopUntil, cond, budget, permissions, modelPolicy, and artifacts.
• The JS/TS code should produce a declarative WorkflowSpec or equivalent JSON IR. The Rust side validates it before launch.
• No direct workflow-script access to shell, filesystem mutation, network, provider clients, or TUI state by default. Those remain explicit worker/tool permissions in the IR.
• Keep Starlark/YAML as compatibility and low-dependency authoring routes if useful, but do not let them block a more capable JS/TS authoring path.
• Reuse v0.8.59: Split sub-agents into a headless worker runtime with lightweight TUI projections #3096's future AgentWorkerSpec / AgentWorkerEvent contract for LeafSpec execution so WhaleFlow does not create a second sub-agent scheduler.
• Integrate with whaleflow: real async executor — replace MockWorkflowExecutor #2973 and whaleflow: wire codewhale-whaleflow into tui/cli (currently zero dependents) #2974 rather than bypassing them: author -> compile/lower -> validate typed IR -> scheduler executes headless workers -> TUI/CLI render events.
• If Node is embedded or invoked, it should run as a compile/authoring step with a constrained host API, not as a long-running unsupervised process that owns cancellation or hidden side effects.

Acceptance criteria

• A design note compares Starlark, YAML, JavaScript, and TypeScript for CodeWhale workflow authoring, and explicitly chooses the default first-class path.
• The chosen path includes a TypeScript/JavaScript authoring contract or a clearly documented reason for rejecting it despite its capability advantage.
• At least one .workflow.ts or .workflow.js example can declare a multi-agent branch/reduce workflow and lower to the existing WhaleFlow WorkflowSpec shape.
• Lowered workflow specs are validated by Rust before execution, including budgets, permissions, model policy, dependency ordering, and leaf IDs.
• Workflow scripts cannot directly mutate files, run shell commands, make network calls, or call model/provider clients unless those effects are represented as explicit typed worker/tool permissions.
• Workflow leaves execute through the same headless worker contract planned in v0.8.59: Split sub-agents into a headless worker runtime with lightweight TUI projections #3096; no duplicate sub-agent runtime is introduced.
• Safety regressions observed in feat: add WhaleFlow — declarative multi-agent workflow orchestration #2482/Feat/whaleflow cost tracking #2486 are covered before live execution: abort cancels spawned work, max_steps and timeout_secs are model-visible, phase ordering is deterministic, worktree changes are not silently dropped, same-phase result dependencies are rejected or sequenced, and token/cost usage is actually propagated.
• TUI/CLI can show the authored workflow source language, compiled IR summary, queued/running/completed worker counts, cancellation state, and per-worker cost/budget status.

Verification

• cargo test -p codewhale-whaleflow --locked
• cargo test -p codewhale-whaleflow starlark --locked
• Add focused tests for the JS/TS lowering layer once introduced.
• Manual: ask CodeWhale to plan a four-agent audit workflow; it should author a workflow script, lower it to typed IR, validate it, run via the headless scheduler, and show progress without spawning a wall of opaque sub-agent cards.