workflow: dynamic workflows — script-driven multi-agent orchestration

A new capability family at packages/workflow/ in the bash seam shape,
modeled on Claude Code's dynamic workflows: the model writes a JavaScript
orchestration script (export const meta = {...} + plain-JS body), a runtime
executes it, and the script — not the conversation — holds the loop, the
branching, and the intermediate results.

- dsh-workflow (ctx.workflows): abstract WorkflowService + run vocabulary
  (WorkflowRun whose result NEVER rejects) + observe-only workflow/* events
  carrying data snapshots (id + meta, never the live run), per-listener
  contained like subagent/*.
- dsh-workflow-vm: in-process node:vm engine. Meta extraction via a
  string/comment-aware scanner (template interpolation rejected; literal
  evaluated alone in an empty timed context; statement blanked line-
  preservingly so stacks keep script line numbers). Hooks: agent(prompt,
  {label, phase, schema, model}) over ctx.subagents, parallel(), pipeline()
  (no cross-stage barrier), phase(), log(), args. Fatal-vs-null discipline:
  hook misuse (unknown/deferred options, bad arguments, unsupported
  schemas, tripped caps, seam start failures, cancellation) throws fatal
  WorkflowErrors the combinators RE-THROW — never dissolved into the
  per-item null reserved for child failures. Realm boundary: inbound values
  materialized by descriptor walks that never invoke accessors (defineProperty
  copies, __proto__-safe); outbound values rebuilt in-realm via the
  context's own JSON.parse. Determinism bans (Date.now/Math.random/argless
  new Date) kept so future resume support cannot break scripts. Caps and
  timeouts are validated Config. Every hook promise carries a no-op
  rejection consumer (app-boot exits on unhandled rejections).
- dsh-tool-workflow: the model-facing workflow tool, synchronous like
  dsh-tool-subagent (start → await → try/finally dispose; abort bridged;
  non-completed → isError). Generic render card titled by a textual
  meta.name sniff. The tool description carries the authoring contract.

Wired into examples/{coding-agent,acp-agent} with explicit-ask-only
guidance. Coverage at every tier: unit (meta scanner, materializer incl.
counting-getter and __proto__ regressions, combinator semantics,
concurrency ceiling, caps, cancellation, no-unhandled-rejection abandon),
integration over the real spawn stack, with-key e2e (real two-phase run +
the tool through the registry pipeline), and a recorded ACP snapshot
scenario (workflow-run, 1 child session). RFC:
docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md (deferred
work explicitly listed). AGENTS.md budget 1575 → 1590 for the new group's
layout line.

packages/workflow/workflow/tests/workflow.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import WorkflowServiceDefault, {
+  isFatalWorkflowError,
+  WorkflowError,
+  WorkflowRunId,
+  WorkflowService,
+} from '../src/index.ts'
+import type { WorkflowRun, WorkflowRunInfo, WorkflowStartRequest } from '../src/index.ts'
+
+/** A minimal concrete subclass exposing the protected emit helper for tests. */
+class StubEngine extends WorkflowService {
+  start(request: WorkflowStartRequest): WorkflowRun {
+    void request
+    throw new Error('not under test')
+  }
+
+  emit(name: Parameters<WorkflowService['emitWorkflowEvent']>[0], ...args: unknown[]): void {
+    this.emitWorkflowEvent(name, ...args)
+  }
+}
+
+const INFO: WorkflowRunInfo = { id: WorkflowRunId('run-1'), meta: { name: 'w', description: 'd' } }
+
+describe('dsh-workflow (interface)', () => {
+  it('WorkflowRunId brands a string (identity at runtime)', () => {
+    expect(WorkflowRunId('abc')).toBe('abc')
+  })
+
+  it('WorkflowError carries code + fatal (default true) and reads as a HarnessError', () => {
+    const error = new WorkflowError('cap hit', 'AGENT_CAP')
+    expect(error.code).toBe('AGENT_CAP')
+    expect(error.fatal).toBe(true)
+    expect(error.name).toBe('WorkflowError')
+    const soft = new WorkflowError('advisory', 'ITEM_CAP', { fatal: false })
+    expect(soft.fatal).toBe(false)
+  })
+
+  it('isFatalWorkflowError: true only for a fatal WorkflowError', () => {
+    expect(isFatalWorkflowError(new WorkflowError('x', 'CANCELLED'))).toBe(true)
+    expect(isFatalWorkflowError(new WorkflowError('x', 'CANCELLED', { fatal: false }))).toBe(false)
+    expect(isFatalWorkflowError(new Error('plain'))).toBe(false)
+    expect(isFatalWorkflowError('string')).toBe(false)
+  })
+
+  it('registers as ctx.workflows and unregisters when its fiber is disposed (HMR safety)', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(StubEngine)
+    expect(ctx.get('workflows')).toBeInstanceOf(StubEngine)
+    await fiber.dispose()
+    expect(ctx.get('workflows')).toBeUndefined()
+  })
+
+  it('emitWorkflowEvent dispatches to every listener with the payload tuple', async () => {
+    const ctx = new Context()
+    await ctx.plugin(StubEngine)
+    const seen: unknown[][] = []
+    ctx.on('workflow/log', (info, message) => { seen.push([info, message]) })
+    ctx.on('workflow/agent-start', (info, agent) => { seen.push([info, agent]) })
+    const engine = ctx.workflows as StubEngine
+    engine.emit('workflow/log', INFO, 'hello')
+    engine.emit('workflow/agent-start', INFO, { seq: 1, label: 'l', childId: 'c' })
+    expect(seen).toEqual([
+      [INFO, 'hello'],
+      [INFO, { seq: 1, label: 'l', childId: 'c' }],
+    ])
+  })
+
+  it('contains a throwing listener PER LISTENER: later listeners still run, nothing propagates', async () => {
+    const ctx = new Context()
+    await ctx.plugin(StubEngine)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => ctx.logger)
+    const reached: string[] = []
+    ctx.on('workflow/phase', () => { throw new Error('bad listener') })
+    ctx.on('workflow/phase', (_info, title) => { reached.push(title) })
+    const engine = ctx.workflows as StubEngine
+    expect(() => { engine.emit('workflow/phase', INFO, 'Scan') }).not.toThrow()
+    expect(reached).toEqual(['Scan'])
+    expect(warn).toHaveBeenCalledOnce()
+    expect(String(warn.mock.calls[0]![0])).toContain('workflow/phase listener threw')
+  })
+
+  it('has the expected export surface (default = the abstract service class)', () => {
+    expect(WorkflowServiceDefault).toBe(WorkflowService)
+  })
+})