refactor(subagent): unify async readiness and cancellation

packages/workflow/workflow/README.md

@@ -1,29 +1,43 @@
 # @deepseek-ai/dsh-workflow
 
-The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a workflow engine does — execute a model-written orchestration script that fans out subagents — without saying HOW. The bash-shaped third of the [workflow family](../README.md): implementations subclass `WorkflowService` and register as the `workflows` service (one per context); [`dsh-workflow-workerthread`](../workflow-workerthread/README.md) (one worker thread per run) is the implementation, and [`dsh-tool-workflow`](../tool-workflow/README.md) is the model-facing consumer.
+The workflow seam (`ctx.workflows`) executes a model-written orchestration script that can fan out subagents. The seam defines the script, run, result, error, and event contracts; an engine decides how to isolate and execute the script.
 
-## Service: `WorkflowService` (abstract)
+`@deepseek-ai/dsh-workflow-workerthread` is the current engine and `@deepseek-ai/dsh-tool-workflow` is the model-facing consumer. A future process or sandbox engine can replace the implementation without changing the tool.
 
-`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled, `result` settles within the implementation's bounded grace even if the script itself never settles (a consumer awaiting `result` must never be wedged past a cancellation). `dispose()` must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller. Runs are HOLDER-owned: the engine does not track its live runs, so disposing the engine's fiber mid-run leaves each run to its holder's teardown.
+## Service and run contract
 
-The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment and PER-LISTENER payload snapshots (a throwing subscriber is logged, never propagated, and cannot starve later listeners; each subscriber gets its own clone of the payload, so mutating it corrupts neither the engine nor other listeners) — the same containment guarantee as the subagent seam's lifecycle emits.
+`WorkflowService.start(request): WorkflowRun` validates enough synchronously to reject a malformed meta block or unparseable script before a run exists. Once returned, `WorkflowRun.result` never rejects: execution failures resolve with `stopReason: 'error'`, and cancellation resolves with `cancelled` within the engine's bounded grace.
 
-## Vocabulary
+A run is holder-owned. Engine-plugin unload prevents new starts but does not revoke accepted runs. The holder must call `dispose()` on every path; disposal cancels remaining work and reaches or abandons quiescence within the documented bound.
 
-- `WorkflowStartRequest` — `{ script, args?, parent: Agent, signal? }`. `parent` is REQUIRED: every child the script spawns is attributed to it. `args` must be plain host-realm JSON data.
-- `WorkflowMeta` / `WorkflowPhase` — the workflow's identity block, carried as plain JSON data on the start request (Claude Code meta vocabulary: required `name`/`description`, optional `whenToUse`/`phases`) and shape-validated by the engine.
-- `WorkflowRun` — `{ id, meta, result, cancel(reason?), dispose() }`; the consumer awaits `result` and MUST `dispose` on every path.
-- `WorkflowResult` — `{ value, stopReason: 'completed'|'cancelled'|'error', error?, agentsStarted }`; `value` is the script's materialized return (plain JSON data; `null` for no return).
-- `WorkflowError` — `HarnessError` with a `WorkflowErrorCode` and a `fatal` flag driving the combinator discipline: a fatal error (bad hook arguments, unsupported options/schemas, tripped caps, seam start failures, cancellation) always propagates through `parallel()`/`pipeline()` instead of dissolving into a per-item `null`. `isFatalWorkflowError(error)` is the catch-site predicate.
+`WorkflowStartRequest` contains `{ meta, script, args?, parent, signal? }`. `parent` attributes every child agent to the invoking agent. `meta` and `args` are plain data, not script fragments.
+
+`WorkflowRun` exposes `{ id, meta, result, cancel(reason?), dispose() }`. `WorkflowResult` contains `{ value, stopReason, error?, agentsStarted }`; `value` is plain JSON data or `null`.
 
 ## Events
 
-All observe-only emits carrying DATA SNAPSHOTS (`WorkflowRunInfo` = id + meta) — never the live `WorkflowRun`, so a listener cannot gain `cancel`/`dispose`; control stays with the `start()` caller:
+Workflow events are observe-only. They carry `WorkflowRunInfo` (`id` plus `meta`) rather than the live run, so listeners cannot acquire cancellation or disposal authority.
 
-- `workflow/start`(info) / `workflow/end`(info, resultInfo) — run lifecycle; `resultInfo` deliberately omits the value.
-- `workflow/phase`(info, title) / `workflow/log`(info, message) — script narration.
-- `workflow/agent-start`(info, agent) / `workflow/agent-end`(info, agent + outcome) — ready-child lifecycle correlated by `seq`; the [generated event contract](../../../docs/cordis-catalog/events.md#workflowagent-start--emit) defines publication and pairing.
+- `workflow/start` / `workflow/end` pair the run.
+- `workflow/phase` and `workflow/log` expose script narration.
+- `workflow/agent-start` / `workflow/agent-end` pair each child call by `seq`; a child whose async provider start rejects emits neither.
 
-## Non-goals (this cut)
+Same-process event payloads are borrowed immutable values. Every listener is independently contained: a synchronous throw or rejected returned promise is logged without starving peers or changing execution.
 
-Background collection, journaling/resume, saved workflows, nested `workflow()`, token budgets — see the [RFC's deferred section](../../../docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md).
+## Failure discipline
+
+`WorkflowError` carries a code and a `fatal` flag. Fatal errors always escape `parallel()` and `pipeline()` instead of becoming an ordinary per-item `null`:
+
+- `SCRIPT_PARSE` / `META_INVALID` — the workflow cannot start.
+- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA` — a hook call violates the engine contract.
+- `AGENT_CAP` / `ITEM_CAP` — configured safety limits were exceeded.
+- `AGENT_START` — the provider's async start rejected.
+- `AGENT_RESULT` — a ready child's result rejected with an infrastructure fault.
+- `RESULT_UNSERIALIZABLE` — a script/worker value is not plain JSON data.
+- `CANCELLED` — cancellation owns the run and pending/future hooks reject.
+
+A child that resolves normally with a non-completed stop reason is not an infrastructure exception: `agent()` returns `null`, allowing the script to handle an ordinary child failure.
+
+## Non-goals
+
+Background collection, journaling/resume, saved workflows, nested `workflow()`, and token budgets are deferred. See the [dynamic-workflows RFC](../../../docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md).

packages/workflow/workflow/src/index.ts

@@ -9,14 +9,12 @@
  * separate-process sandbox) swap in without touching the model-facing tool
  * that consumes them (`@deepseek-ai/dsh-tool-workflow`).
  *
- * The `workflow/*` lifecycle events are OBSERVE-ONLY data snapshots: they
+ * The `workflow/*` lifecycle events are OBSERVE-ONLY data: they
  * carry {@link WorkflowRunInfo} (id + meta), never the live {@link WorkflowRun}
  * — a listener must not gain `cancel`/`dispose`; control stays with the
- * `start()` caller holding the run. Every emit is per-listener contained (a
- * throwing subscriber is logged, never propagated) and every listener gets its
- * own payload clone (mutating it corrupts nothing), so one bad observer can
- * neither strand a live run, starve later listeners, nor poison another
- * listener's view.
+ * `start()` caller holding the run. Same-process payloads are borrowed
+ * immutable values. Every listener is independently contained, so a throw or
+ * rejected promise can neither strand a run nor starve peers.
  *
  * @module @deepseek-ai/dsh-workflow
  */
@@ -78,7 +76,7 @@ declare module 'cordis' {
     /**
      * One `agent()` call established a ready child run. Paired with
      * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
-     * crosses the provider's publication/readiness boundary emits neither
+     * receives a ready run from the provider emits neither
      * event in this pair.
      * @param info - the run's identity snapshot.
      * @param agent - the call's sequence number, label, phase, and child id.
@@ -131,11 +129,10 @@ export type WorkflowEventName =
  * - `UNSUPPORTED_SCHEMA` — an `agent()` schema outside the structured-output
  *   subset (see dsh-tools).
  * - `AGENT_CAP` / `ITEM_CAP` — the run/agent caps tripped.
- * - `AGENT_START` — synchronous subagent start or the provider's asynchronous
- *   publication/readiness boundary failed before cancellation took precedence.
- * - `AGENT_RESULT` — a run whose readiness FULFILLED had its `result` REJECT: an
- *   infrastructure fault at the subagent seam, even if the rejection settled
- *   before readiness. This is distinct from a child that failed and resolved
+ * - `AGENT_START` — the provider's asynchronous start rejected before
+ *   cancellation took precedence.
+ * - `AGENT_RESULT` — a ready run had its `result` REJECT: an infrastructure
+ *   fault at the subagent seam. This is distinct from a child that failed and resolved
  *   (which is the per-item `null`, never an error).
  * - `RESULT_UNSERIALIZABLE` — a value crossing the script/host value boundary
  *   is not plain JSON data.
@@ -198,8 +195,8 @@ export function isFatalWorkflowError(error: unknown): boolean {
  *   `result` SETTLES within the implementation's bounded grace even if the
  *   script itself never settles (a consumer awaiting `result` must never be
  *   wedged past a cancellation).
- * - The `workflow/*` events fire through {@link emitWorkflowEvent} (data
- *   snapshots, per-listener containment); `workflow/end` fires exactly once
+ * - The `workflow/*` events fire through {@link emitWorkflowEvent} (borrowed
+ *   immutable data, per-listener containment); `workflow/end` fires exactly once
  *   per started run, after `result` is settled or as it settles.
  * - `dispose()` reaches quiescence within a bounded grace: it cancels, waits
  *   for the script to settle AND its started children to finish disposing,
@@ -225,12 +222,9 @@ export abstract class WorkflowService extends Service {
   abstract start(request: WorkflowStartRequest): WorkflowRun
 
   /**
-   * Emit one `workflow/*` lifecycle event with PER-LISTENER containment and
-   * PER-LISTENER payload snapshots: each subscriber is dispatched individually
-   * with its OWN structural clone of the payload (the payloads are plain JSON
-   * data by the seam contract), so a listener mutating what it received can
-   * corrupt neither the engine's live state nor any other listener's or later
-   * event's view; a thrown listener is logged (never propagated — the logging
+   * Emit one `workflow/*` lifecycle event with per-listener containment. Each
+   * subscriber receives the same borrowed immutable payload; a throw or
+   * asynchronously rejected listener is logged (never propagated — the logging
    * itself is total, even for a thrown value whose own string coercion
    * throws), so one bad subscriber can neither fail the engine mid-run,
    * surface as an unhandled rejection on a detached settle hook, nor starve
@@ -242,9 +236,10 @@ export abstract class WorkflowService extends Service {
   protected emitWorkflowEvent(name: WorkflowEventName, ...args: unknown[]): void {
     for (const callback of this.ctx.events.dispatch('emit', [name, ...args])) {
       try {
-        // The declared workflow/* signatures are all void-returning emits; the
-        // dispatch callback applies the payload tuple.
-        ;(callback as (...payload: unknown[]) => void)(...structuredClone(args))
+        const returned: unknown = (callback as (...payload: unknown[]) => unknown)(...args)
+        void Promise.resolve(returned).catch((error: unknown) => {
+          this.ctx.logger.warn(`workflow: ${name} listener rejected: ${renderListenerError(error)}`)
+        })
       } catch (error: unknown) {
         this.ctx.logger.warn(`workflow: ${name} listener threw: ${renderListenerError(error)}`)
       }

packages/workflow/workflow/src/types.ts

@@ -128,7 +128,7 @@ export interface WorkflowRun {
   dispose(): Promise<void>
 }
 
-/** Identifying detail for a run, carried by every `workflow/*` event (a data snapshot, never the live run). */
+/** Identifying detail for a run, carried by every `workflow/*` event as borrowed immutable data, never the live run. */
 export interface WorkflowRunInfo {
   /** The run's id. */
   id: WorkflowRunId

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

@@ -66,26 +66,21 @@ describe('dsh-workflow (interface)', () => {
     ])
   })
 
-  it('gives each listener its OWN payload snapshot: mutation corrupts neither peers nor the caller', async () => {
+  it('contains an asynchronously rejected listener without starving peers', async () => {
     const ctx = new Context()
     await ctx.plugin(StubEngine)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => ctx.logger)
     const seen: string[] = []
-    ctx.on('workflow/agent-start', (info, agent) => {
-      agent.label = 'HACKED'
-      info.meta.name = 'HACKED'
-      seen.push('mutator')
-    })
-    ctx.on('workflow/agent-start', (info, agent) => {
-      seen.push(`${info.meta.name}/${agent.label}`)
-    })
+    // Runtime listeners may return thenables even though the declaration's observable result is void.
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- exercises rejected-listener containment
+    ctx.on('workflow/agent-start', async () => { throw new Error('async observer failed') })
+    ctx.on('workflow/agent-start', (_info, agent) => { seen.push(agent.label) })
     const engine = ctx.workflows as StubEngine
-    const info: WorkflowRunInfo = { id: WorkflowRunId('run-2'), meta: { name: 'w', description: 'd' } }
     const payload = { seq: 1, label: 'original', childId: 'c' }
-    engine.emit('workflow/agent-start', info, payload)
-    expect(seen).toEqual(['mutator', 'w/original'])
-    // The caller's own objects are pristine too — no listener ever saw them.
-    expect(info.meta.name).toBe('w')
-    expect(payload.label).toBe('original')
+    engine.emit('workflow/agent-start', INFO, payload)
+    await Promise.resolve()
+    expect(seen).toEqual(['original'])
+    expect(String(warn.mock.calls[0]![0])).toContain('listener rejected')
   })
 
   it('contains a throwing listener PER LISTENER: later listeners still run, nothing propagates', async () => {