What would you like to be added?

Port the Dynamic Workflows feature (announced by Anthropic in Claude Code 2.1.160) to qwen-code as a third tier of multi-agent execution, complementary to the existing /swarm tool (#3433) and the in-progress Agent Team (#2886).

What a dynamic workflow is

A model-authored JavaScript script that runs in a sandbox and orchestrates many subagents through a small set of primitives. The model writes the script on-the-fly for the user's request; the runtime sandboxes it; subagents fan out through the existing headless-agent path; one aggregated result returns to the main conversation.

The full API surface (all confirmed against upstream's published /deep-research workflow script and binary strings):

// Required first statement of every script
export const meta = {
  name: string,
  description: string,
  whenToUse?: string,
  phases?: Array<{ title: string, detail?: string, model?: string }>,
}

// Injected globals
phase(title: string): void
parallel(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>
pipeline<T>(items: T[], ...stages: Array<(prev, item: T, idx: number) => Promise<any>>): Promise<any[]>
agent(prompt: string, opts?: {
  label?: string, phase?: string, schema?: object,
  model?: string, isolation?: 'worktree' | 'remote', agentType?: string,
}): Promise<any>
log(message: string): void
workflow(nameOrRef: string | { scriptPath: string }, args?: any): Promise<any>

args: any
budget: { total: number | null, spent(): number, remaining(): number }

// Stubbed (throw) to guarantee resume determinism
Date.now(), new Date(), Math.random()

Concrete example from Anthropic's shipped /deep-research workflow:

phase('Scope')
const scope = await agent('Decompose this research question into 5 search angles...', { schema: SCOPE_SCHEMA })

const searchResults = await pipeline(
  scope.angles,
  angle => agent(SEARCH_PROMPT(angle), { phase: 'Search', schema: SEARCH_SCHEMA }),
  searchResult => parallel(novelUrls(searchResult).map(src => () =>
    agent(FETCH_PROMPT(src), { phase: 'Fetch', schema: EXTRACT_SCHEMA }))),
)

phase('Verify')
const voted = await parallel(rankedClaims.map(claim => () =>
  parallel(Array.from({ length: 3 }, (_, v) => () =>
    agent(VERIFY_PROMPT(claim, v), { phase: 'Verify', schema: VERDICT_SCHEMA })))
    .then(verdicts => ({ ...claim, survives: verdicts.filter(v => v.refuted).length < 2 }))))

phase('Synthesize')
const report = await agent('Merge confirmed claims; write report...', { schema: REPORT_SCHEMA })
return { question, ...report }

Triggers

Four invocation paths matching upstream:

1. Keyword in prompt — including the word workflow in a single-turn user prompt opts that turn into a workflow.
2. /effort ultracode (session-only mode) — once enabled, the model auto-spawns workflows for substantive turns until session ends.
3. Saved slash command — workflow scripts at .qwen/workflows/ (project) or ~/.qwen/workflows/ (user) are surfaced as slash commands (the /deep-research invocation style).
4. Direct Workflow tool call by the model with inline script or name.

Hard caps (verbatim from upstream)

• Concurrent agents: min(16, os.cpus().length - 2) per workflow
• Total agent calls: 1000 per workflow lifetime
• Schema-mismatch nudges: 2 in-conversation nudges per agent (binary line 307789 — error message reads "subagent completed without calling StructuredOutput (after 2 in-conversation nudges)"). Distinct from the stall-retry counter VOK = 5 which fires on no-progress agents, not schema validation failures.
• Single nesting level for workflow() (workflow inside a child workflow throws)
• Same-session resume only (in initial scope; cross-session is a v1.5 candidate, see decisions below)

Why is this needed?

What dynamic workflow does that swarm and Agent Team don't

Dynamic workflow is strictly additive:

• Keep /swarm for the simple "fan out 5 tasks, aggregate" case where a script is overkill.
• Keep Agent Team for persistent peer-to-peer collaboration with mailboxes.
• Add Workflow for the rich multi-phase orchestration case — matching upstream's Agent + Workflow coexistence.

Use cases this unlocks

• Adversarial verification (deep-research-style 3-vote claim refutation against schema-validated claims)
• Map-reduce with typed outputs (extract findings as JSON objects, not freeform text)
• Multi-stage pipelines without per-stage barriers (item A in stage 3 while item B is still in stage 1 — dramatically reduces wall-clock for long fan-outs)
• Resumable long runs (pause/restart without re-burning the agents that already completed)
• Cost-bounded loops (while (budget.remaining() > 50_000) { spawn more verifiers })

Why the infrastructure cost is small

The implementation reuses most of what qwen-code already ships:

The only genuinely new subsystem is a node:vm-based JS sandbox (~150–250 LOC) that injects the documented globals and stubs Date.now / Math.random for resume determinism. Everything else is wiring.

Additional context

Local design artifacts

A full design pass has been completed against upstream @anthropic-ai/[email protected], with the API surface live-verified against the actual /deep-research workflow script captured from ~/.claude/projects/<session>/workflows/scripts/ plus binary strings cross-check. The following artifacts will be committed alongside the implementation PR:

• Main design doc (788 lines): .qwen/design/dynamic-workflow-alignment-claude-code-2.1.160.md — per-axis upstream findings, qwen-code fit matrix (11 subsystems), gap analysis, phased plan, risks
• Live-probe delta (~280 lines): .qwen/design/dynamic-workflow-alignment-claude-code-2.1.160-liveprobe-delta.md — API surface confirmation, with binary line citations and /deep-research source code references
• E2E test plan (812 lines): .qwen/e2e-tests/dynamic-workflow-alignment.md — per-phase scenarios with stub-server harness

Every API signature in the design is Confirmed against either Anthropic's published /deep-research workflow source or the binary's literal tool-description constant.

Phased implementation plan

Each phase is independently shippable behind a feature gate:

Decisions needed before P1 (qwen-specific divergences from upstream)

These need maintainer sign-off because they leak into settings shape, env var names, and UI surface:

1. JS sandbox choice: node:vm (zero dep, weak isolation; matches upstream's defense-in-depth posture, since the script has no fs/shell surface by design) vs isolated-vm (strong V8-level isolate, but adds a native dep that breaks the "pure JS, single npm install" property and requires prebuilt binaries for all platforms). Recommendation: node:vm for v1, escalate to isolated-vm only if a hostile-script threat model emerges.

2. Keyword trigger default: upstream sets workflowKeywordTriggerEnabled = true. qwen-code users skew cost-sensitive across DashScope / OpenAI-compatible providers. Recommendation: default false on qwen-code, require explicit opt-in via settings. Diverges from upstream.

3. Per-run token ceiling: upstream has only agent-count caps (16 concurrent / 1000 total) — no programmable token limit. Recommendation: add a qwen-only QWEN_CODE_MAX_TOKENS_PER_WORKFLOW env var, default unset, as a safety net. Diverges from upstream.

4. Saved-workflows directory: .qwen/workflows/ + ~/.qwen/workflows/ (matches qwen convention) vs .claude/workflows/ + ~/.claude/workflows/ (matches upstream literal paths and aids portability of shared workflows across tools). Recommendation: .qwen/ paths; copy-pasted upstream workflows need a path adjustment.

5. Cross-session resume: upstream is strictly same-session only. qwen-code already ships cross-session background-agent resume (Add background agent resume and continuation #3739, 1068 LOC). Recommendation: ship same-session in v1 to match upstream, extend to cross-session in v1.5 as a qwen-only improvement.

6. Ultracode persistence semantics: upstream's ultracode: true is session-only (does not persist across sessions). qwen-code's settings layer has no "session-only key" concept today. Recommendation: match upstream — require re-toggle per session, document it.

Risks

1. JS sandbox security — node:vm is not a true security boundary. Mitigated by the fact that the script has no fs/shell surface by design (only spawned agents do I/O); we enforce this by not injecting process / require / fs / child_process into the context. Escalation path to isolated-vm if a real attacker model emerges. Workflow scripts are model-authored, not arbitrary user input.

2. Token cost amplification — 16× concurrency × deep nesting × shared plan billing can burn quota fast. Mitigated by agent-count caps (16 / 1000), optional QWEN_CODE_MAX_TOKENS_PER_WORKFLOW ceiling, one-time consent banner via skipWorkflowUsageWarning setting, and the keyword-trigger default flip.

3. Subagent state leakage — subagents share Config / ToolRegistry. Concurrent agents could leak through mutable per-call state in custom MCP servers. Mitigated by auditing Config for mutable per-call state and recommending isolation: 'worktree' for workflows that mutate files concurrently.

Known P1 limitations (deferred to later phases)

Surfaced during PR #4732 R7 review by @DragonnZhang; documented here so they don't get re-raised in subsequent rounds:

1. In-script async microtask leak after wall-clock timeout — once an in-script async loop (e.g., (async () => { while(true) await 0 })()) starts inside the node:vm context, the wall-clock Promise.race rejects user-side but the microtask loop continues consuming host microtasks. node:vm provides no mechanism to halt async execution once started. Mitigated by the 30-min default cap (QWEN_CODE_MAX_WORKFLOW_SECONDS) and the opt-in feature gate. Proper fix: migrate the sandbox to worker_threads isolation in a future phase, where worker termination drops all in-flight microtasks.

2. No memory cap on the vm context — node:vm does not enforce a memory limit, so a script like const a=[]; while(true) a.push(new ArrayBuffer(1e8)) can OOM the host process. Operator mitigation: --max-old-space-size flag on the parent Node process. Same proper fix as (1): worker_threads isolation gives the worker its own heap with a resourceLimits.maxOldGenerationSizeMb cap.

Both are acceptable for P1 given the opt-in gate, ask permission level, and 30-min wall-clock backstop — but should be addressed alongside any future phase that loosens the gating (e.g., P7 keyword trigger / ultracode session-mode would broaden the activation surface and make stricter sandbox isolation more important).

Relation to existing features (not replaced)

• /swarm (feat(core): add dynamic swarm worker tool #3433) — keep as-is. Targets the "fan out N tasks, aggregate" case where a workflow script is overkill.
• Agent Team (feat: add Agent Team experimental feature for parallel sub-agent coordination #2886, in progress) — keep as-is. Targets persistent peer-to-peer collaboration with mailboxes and shared task boards.
• Background task framework (Issue Background task management: roadmap and next steps #3634) — workflow becomes the 5th kind consumer (agent / shell / monitor / dream / workflow), no framework change.

Related upstream ports (coordinate with)

• feat(agents): support declarative agent definitions via frontmatter files #4821 — Declarative agent definitions (.qwen/agents/<name>.md frontmatter). The workflow's agent(prompt, { agentType }) option resolves agentType against the same registry that feat(agents): support declarative agent definitions via frontmatter files #4821 builds. Joint design surface:
  • name (feat(agents): support declarative agent definitions via frontmatter files #4821 frontmatter) ↔ agentType (workflow opts) — the same string key
  • tools / disallowedTools / model / effort / permissionMode from the agent definition compose with workflow's default subagent config. P1's hardcoded disallowedTools: [SEND_MESSAGE, EXIT_PLAN_MODE] becomes the floor that agent-level definitions extend (union), not replace
  • isolation: 'worktree' at the agent-definition level is the default; opts.isolation at the workflow call site overrides per-call
  • Workflow P1–P2 ship without feat(agents): support declarative agent definitions via frontmatter files #4821 (sequential / parallel / pipeline only use the built-in workflow subagent). agentType support lands in P3, gated on feat(agents): support declarative agent definitions via frontmatter files #4821's registry being available (or graceful fallback when the named type doesn't resolve)
  • Workflow and feat(agents): support declarative agent definitions via frontmatter files #4821 are independently shippable; their joint surface is reviewed once before P3 lands

Upstream references

• Announcement: https://claude.com/blog/introducing-dynamic-workflows-in-claude-code
• Reverse-engineered against: @anthropic-ai/[email protected] binary + on-disk generated workflow scripts at ~/.claude/projects/<session>/workflows/scripts/

Acceptance criteria

• Workflow tool registered when an enableWorkflows setting is on; disabled by default in v1 — P1 feat(core): Workflow tool P1 — minimal node:vm sandbox + sequential agent() (#4721) #4732
• Model can call Workflow({ script, args }) and the script runs in a node:vm sandbox with the documented globals — P1 feat(core): Workflow tool P1 — minimal node:vm sandbox + sequential agent() (#4721) #4732
• phase(), agent(), log() work sequentially (P1) — P1 feat(core): Workflow tool P1 — minimal node:vm sandbox + sequential agent() (#4721) #4732
• parallel() / pipeline() run concurrently with cap enforcement and errors-as-data null semantics (P2) — P2 feat(core): Workflow P2 — parallel() + pipeline() concurrent fan-out (#4721) #4947
• agent({ schema }) returns validated objects, retries on mismatch, returns null on skip (P3)
• agent({ agentType }) resolves against the declarative-agents registry (feat(agents): support declarative agent definitions via frontmatter files #4821) when present; falls back to the built-in workflow subagent prompt when agentType is unset or doesn't resolve (P3)
• /workflows slash command lists active and completed runs; pill shows workflow count (P4)
• budget.total / spent() / remaining() reflect output-token usage; hard ceiling throws WorkflowBudgetExceededError (P5)
• Resume via resumeFromRunId returns cached prefix instantly; first edited or new agent() runs live (P6)
• Existing /swarm and Agent Team features remain unchanged; no regression in their test suites — confirmed at each PR

Update — 2026-06-12: P1 + P2 shipped, 2.1.168 reverse pass

Captures actual shipped state and the deltas found in the Claude Code 2.1.168 binary scan. The original plan, decisions, and risks above remain authoritative for the unshipped phases; this section adds (i) what actually shipped vs the original LOC/scope estimate, (ii) what changed upstream between 2.1.160 and 2.1.168, and (iii) confirmed adjacent-infrastructure reuse paths for P3–P7.

Shipped phases

LOC over-run vs the original ~600 / ~300 estimates is dominated by test coverage and review-round security hardening; no unplanned feature shipped. The "extras" below are all positive drift discovered during review.

P1 positive drift (beyond original plan):

• 30-min async wall-clock timeout (QWEN_CODE_MAX_WORKFLOW_SECONDS, default 1800s) — catches 0-token hangs that vm timeout and the future budget cap cannot reach (T23 R2)
• AbortSignal threading into subagent.execute so wall-clock abort propagates into in-flight subagents (T40 R4)
• abortOnTimeout child-controller injection seam for explicit timeout coordination (T40 R4)

P2 positive drift (beyond original plan):

• Hard ceilings on env-overridable caps: HARD_MAX_AGENTS_PER_RUN_CEILING = 10000, HARD_MAX_CONCURRENCY_CEILING = 64 — prevents fat-finger misconfiguration uncapping a runaway workflow (R1 wenshao T4)
• Per-element vm-realm JSON revival of parallel/pipeline results instead of whole-array — closes T1/T8/T14 escape: a single non-serializable thunk result no longer wipes out sibling results (R1 self-review EAD-1)
• Dispatch-layer concurrency throttling (not thunk-layer) — prevents nested parallel-in-pipeline deadlock (the canonical /deep-research shape); verified with a gate-based RED test on concurrency=1 (F1 fix)
• Observability: debugLogger.warn for rejected thunks (R1), logRevivalFailure hook for non-serializable results (R2) — disambiguates "null at index" failure modes
• Limiter prompt-queue abort listener — strengthens limiter invariant when an in-flight thunk hangs (R2)

Shipped env vars and caps

P3+ injection seams already pre-wired in P1/P2

• agent({schema}), agent({agentType}), agent({isolation}), agent({model}) are all STUB-THROW today — P3 replaces the throw with the real implementation, no sandbox re-opening needed
• SandboxOptions.budget interface is wired (default spent()/remaining() throw) — P5 injects the real implementation through the existing seam
• SandboxOptions.parallel / SandboxOptions.pipeline are populated (P2)
• resumeFromRunId + JSONL journal: NOT pre-wired — P6 is a net-new subsystem
• Ultracode session mode + workflowKeywordTriggerEnabled: NOT pre-wired — P7 is net-new

Claude Code 2.1.168 reverse pass — deltas vs 2.1.160 baseline

Binary strings cross-compared across 2.1.161 / 2.1.162 / 2.1.168 against the 2.1.160-documented baseline at the top of this issue.

Unchanged: concurrent cap max(1, min(16, cpus-2)), per-run agent cap 1000, schema nudge count 2 in-conversation, wall-clock 30 min, single-level workflow nesting.

New upstream features (post-2.1.160) confirmed shipped:

Verdict: Workflow surface is stable across 2.1.160 → 2.1.168 for everything #4721 covers. Upstream has already shipped P3 / P5 / P6 (only isolation:'remote' is gated off), giving qwen a clear contract to match. Agent-memory scoping by agentType is new in 2.1.168 — out of #4721's original scope, candidate for a post-P7 follow-up if there's appetite.

Adjacent infrastructure reuse confirmed on origin/main

Agent Team (#4844) integration risk = LOW: Team and Workflow share the same SubagentManager registry so agentType semantics align, but their call sites (team.spawn() vs workflow.agent()) don't overlap. Documentation will need to disambiguate "which to use when".

Refined phase plan (no scope drift, refined LOC estimates)

The plan above remains the authoritative scope; this is a refined estimate based on the confirmed reuse paths. P3 ships as a single PR covering schema + agentType + isolation:'worktree' rather than splitting — the model-facing API and the sandbox-execution wiring are easier to review together than as two coupled PRs.

Remaining total ≈ 3000-3950 LOC across 5 PRs (average ~600/PR vs P1+P2 average ~2100/PR — easier reviews).

Update — 2026-06-14: P3 shipped, P4 startup plan

This section adds the actual P3 shipped state and the refined plan for P4–P7. The original plan, decisions, and risks above remain authoritative; this section adds (i) what actually shipped, (ii) what the 2.1.168 reverse re-pass confirms (no new findings since the 2026-06-12 update — same binary, same surface), and (iii) the P4 startup plan based on a fresh adjacent-infra scout.

P3 shipped

Squash merge commit on main: 06345a2f. Pre-squash branch carried 4 commits — R0 implementation + R1/R2 author self-review (proactive) + R3 wenshao review response.

P3 positive drift (beyond original plan, all review-driven hardening):

• Per-call agentOpts JSON revival inside the vm realm before crossing the host boundary — closes a Proxy / inherited-getter / non-plain-object escape that the user-supplied schema field would otherwise have re-opened (mirror of the parallel/pipeline result revival, applied per-call to the options bag).
• agentType interpolation in error messages sanitized through sanitizeForErrorMessage (control characters → space) so a model-authored agentType cannot fragment the single-line error across log records / OTLP fields / display payloads.
• Outer try/finally moved to start immediately after provisionWorkflowWorktree, so a throw from schema setup (createSchemaConfigOverride, createSchemaModeState, abort-listener attachment) no longer orphans the just-provisioned worktree under .qwen/worktrees/.
• Schema mode + agentType: augmented.tools auto-appends structured_output when the agentType allowlist is restricted (no '*'), and systemPrompt is appended-not-replaced so the agentType's persona is preserved alongside the StructuredOutput instruction block.
• Parent-abort listener stored as a named handler and removed in the outer finally regardless of how the dispatch ended — the previous { once: true } only auto-removed on actual parent abort, leaving listeners + child-controller closures stuck on the per-run signal across happy-path dispatches.
• Terminate-mode disambiguation in schema-mode error path: TIMEOUT / MAX_TURNS / ERROR now throw the existing "did not complete (terminate mode: X)" message that the non-schema path uses; the upstream-verbatim "(after 2 in-conversation nudges)" wording is preserved only for the actual 3-failure case; the 0-call case gets the accurate "no validation attempt — model produced plain-text content" message.

Tests: 75/75 orchestrator + 111/111 sandbox/tool/limiter + 217/217 adjacent regression (subagents / syntheticOutput / agent-override) — all green. Real-LLM E2E: 7/7 against qwen3-coder-plus via DashScope (S1 schema happy path, S2 agentType not found, S3 isolation:'remote' unavailable, S4 agentType=Explore resolves, S5 no-opts regression, S6 parallel+schema, S7 isolation:'worktree' lifecycle in a fresh git repo).

P3+ injection seams now present in main

• agent({schema}) / agent({agentType}) / agent({model}) / agent({isolation: 'worktree'}) — all wired through SubagentManager.createAgentHeadless with provider routing via buildRuntimeContentGeneratorView and per-agent ToolRegistry + hooks lifecycle
• agent({isolation: 'remote'}) — wired to upstream-verbatim "not available in this build" so downstream callers can detect the gating
• SyntheticOutputTool per-call injection in the subagent's rebuilt registry (via rebuildToolRegistryOnOverride); event-driven structured_output capture through AgentEventEmitter TOOL_CALL / TOOL_RESULT listeners
• WorkflowAgentResult widened from string to string | object (schema-mode object payload)
• vm-realm per-call revival for both agent() object returns AND agentOpts (security hardening)

Claude Code 2.1.168 reverse — no delta since the 2026-06-12 update

Same binary (no newer 2.1.169+ installed locally). The earlier reverse pass remains the authoritative baseline. Re-confirmed for P4 specifically:

• /workflows slash command — literal string in binary; "List all available shortcuts and workflows" surface; subcommand routing not yet shipped upstream (P4 catches up)
• extractAndStripMeta (upstream uses acorn AST extraction) — qwen-code will diverge on parser choice (see P4 plan below)
• Meta object shape: {name, description, title?, whenToUse?, phases?: Array<{title, detail?, model?}>}
• tengu_workflow_phase_completed event — present in binary; will drive phase-tree UI progress signals
• PhaseScrollIndicator string present in binary but no rendering logic — qwen-code can pick the UI shape independently
• TaskKind workflow entry — not yet in upstream source code either; qwen-code lands on the same starting line as upstream here

Adjacent infra confirmed for P4

P4 startup plan

Parser choice: stay on the P1 zero-dep + node:vm posture. Extend the existing brace-walker to capture the export const meta = {...} source range, then evaluate that source inside the sandbox vm context (the same context where the script runs) to materialize the meta object, and JSON-revive the result into the host as a plain object. This:

• Keeps the security profile identical to P1 (no new realm, no new parser surface)
• Lets the model author meta using normal JS object literal syntax (single quotes, unquoted keys, template strings, etc.) without us re-implementing a JS parser
• Matches the upstream contract (name, description, whenToUse?, phases[]) at the semantic layer, even though the parser is structurally different from upstream's acorn AST

Divergence from upstream documented: the error messages and meta-shape contract match (verbatim "meta.name must be a non-empty string" etc.); the underlying parser does not. Net behavior identical for any well-formed meta block.

Saved workflow directory: .qwen/workflows/ and ~/.qwen/workflows/ (matches qwen convention from decision #4 in the original plan).

Refined phase plan (no scope drift, fresher LOC numbers)

The plan above remains the authoritative scope; this is a refined estimate based on the shipping experience of P1–P3 and the freshly-scouted seam state.

Remaining total ≈ 1850-2450 LOC across 4 PRs (average ~500/PR; lighter than P1–P3 average ~2300/PR because the new scope is mostly wiring, not new sandbox/dispatch machinery).

Updated acceptance criteria

• Workflow tool registered when an enableWorkflows setting is on; disabled by default in v1 — P1 feat(core): Workflow tool P1 — minimal node:vm sandbox + sequential agent() (#4721) #4732
• Model can call Workflow({ script, args }) and the script runs in a node:vm sandbox with the documented globals — P1 feat(core): Workflow tool P1 — minimal node:vm sandbox + sequential agent() (#4721) #4732
• phase(), agent(), log() work sequentially (P1) — P1 feat(core): Workflow tool P1 — minimal node:vm sandbox + sequential agent() (#4721) #4732
• parallel() / pipeline() run concurrently with cap enforcement and errors-as-data null semantics (P2) — P2 feat(core): Workflow P2 — parallel() + pipeline() concurrent fan-out (#4721) #4947
• agent({ schema }) returns validated objects, retries on mismatch, returns null on skip (P3) — P3 feat(core): Workflow P3 — agent({schema, agentType, model, isolation:'worktree'}) (#4721) #5034
• agent({ agentType }) resolves against the declarative-agents registry (feat(agents): support declarative agent definitions via frontmatter files #4821) when present; falls back to the built-in workflow subagent prompt when agentType is unset or doesn't resolve (P3) — P3 feat(core): Workflow P3 — agent({schema, agentType, model, isolation:'worktree'}) (#4721) #5034
• /workflows slash command lists active and completed runs; pill shows workflow count (P4)
• budget.total / spent() / remaining() reflect output-token usage; hard ceiling throws WorkflowBudgetExceededError (P5)
• Resume via resumeFromRunId returns cached prefix instantly; first edited or new agent() runs live (P6)
• Existing /swarm and Agent Team features remain unchanged; no regression in their test suites — confirmed at each PR

Update — 2026-06-16: P4 shipped, P5 startup plan

P4 shipped

Squash-merged via PR #5094 at 72da11217 (2026-06-16). 7 commits in the squash:

Verified end-to-end against qwen3-coder-plus via DashScope:

• meta extraction + display threading (6 real-LLM E2E scenarios)
• TUI: footer pill counts workflows, live phase-tree JSON updates, /workflows list + /workflows <runId> detail render correctly
• /clear clears workflow registry (no cross-session leak)
• safePhase deduplication: phase('X'); phase('X') produces ['X'] consistently in both terminal display and live UI
• 232/232 core workflow tests + 105/105 CLI ripple tests pass
• Approved by @DragonnZhang LGTM (via /review claude-opus-4-6 verdict); reviewed by @wenshao through R7 with merged-state local-build verification

Deferred to follow-up PRs

• P4c — ACP daemon protocol propagation: workflows currently invisible to SDK + web-shell consumers because packages/acp-bridge/src/bridgeTypes.ts + status.ts + tasksSnapshot.ts were not widened with 'workflow'. Filed as out-of-scope by design (cross-SDK contract change deserves its own review cycle).
• Pill focus chain infra gap: setPillFocused(true) is missing from the codebase (pre-existing, not P4-introduced). The BackgroundTasksDialog body for workflows is reachable via the existing detail-from-panel path for agents but not the pill-focus-from-composer path. P4 softened the /workflows tip to avoid advertising the broken path; restoring pill focus is its own UX PR.

P5 startup plan

Scope: budget global API surface fills the SandboxOptions.budget seam P1 reserved with throwing stubs.

Acceptance:

• budget.total: number | null reads QWEN_CODE_MAX_TOKENS_PER_WORKFLOW (env), null when unset
• budget.spent() returns cumulative output-token count across all agent() dispatches in the run
• budget.remaining() returns max(0, total - spent()) when total set, Infinity otherwise
• Hard ceiling: each agent() call checks budget.remaining() > 0 before dispatch; over-budget throws WorkflowBudgetExceededError (new exception class)
• Registry surface: WorkflowTask gains tokensSpent: number + tokenBudgetTotal: number | null; emitter fires budgetUpdated(spent, remaining) on each agent completion
• UI: /workflows <runId> detail dump shows per-phase token totals (rolled up by phase: <label> source key); WorkflowDetailBody renders "spent / total" footer
• One-time usage warning banner: first workflow run shows "workflows can spend N tokens" notice; suppressed via skipWorkflowUsageWarning setting
• Free side benefit: dynamic-loop pattern while (budget.total && budget.remaining() > 50_000) { ... } works end-to-end

Reuse seams (no net-new subsystems):

• AgentStatistics per-agent token tracker — sum output_tokens across the run's dispatches
• SandboxOptions.budget (P1) — was a throwing stub; replace with WorkflowBudgetImpl
• WorkflowOrchestratorEmitter (P4) — extend with budgetUpdated event
• WorkflowTask (P4) — extend with tokensSpent + tokenBudgetTotal fields
• /workflows detail formatter (P4) — extend with per-phase token rollup

Estimated LOC: 400-500 (lower bound; P1 seam is already wired, just needs filling).

Risk: LOW. Single subsystem (token tracking), no new orchestration paths, no security-boundary changes, no API surface widening beyond emitter + entry fields.

Files touched (rough):

• NEW packages/core/src/agents/runtime/workflow-budget.ts (~150 LOC + test)
• EDIT workflow-sandbox.ts — replace throwing stub with WorkflowBudgetImpl factory
• EDIT workflow-orchestrator.ts — wire token tracker into countedDispatch + emit budgetUpdated
• EDIT workflow-run-registry.ts — extend WorkflowTask with token fields
• EDIT workflowsCommand.ts — render per-phase token totals
• EDIT BackgroundTasksDialog.tsx WorkflowDetailBody — render budget footer
• EDIT config.ts — QWEN_CODE_MAX_TOKENS_PER_WORKFLOW env wiring + skipWorkflowUsageWarning setting

Remaining roadmap

Remaining total ≈ 1150-1550 LOC across 2-3 PRs.

Lessons captured from P4 review rounds

Two failure-class patterns recurred across P4 reviews; documented in maintainer auto-memory to defend against them in P5+:

1. Sibling-drift on Config method additions: every time P4 added a method to Config (e.g. getWorkflowRunRegistry), the test mocks that already shipped Config-shaped objects went stale until each mock site stubbed the new method. Burned 2 CI rounds (#249191181 for isWorkflowsEnabled on BuiltinCommandLoader, #7b0ea82de for the workflow registry methods on clearCommand + useResumeCommand). Defense: before merging any PR that adds a Config method, grep getBackgroundShellRegistry (or similar canonical sibling) and audit every mock against the new method.

2. Docstring claim-vs-code drift: I wrote docstrings describing behavior I hadn't implemented or that diverged from sibling code. wenshao R7 caught two ("validates the shape wf_<hex>" was aspirational, "Mirrors the sandbox's safePhase collapse" was inaccurate — safePhase didn't dedup). Defense: every docstring claim of the form "X mirrors / validates / ensures Y" requires grep-verifying Y against current code before merging.