workflow: simplify to the trust premise; settle result on cancellation

Two review responses that belong together — the same review argued the
engine was defending the wrong threat while a benign-input bug wedged
the product.

1) Drop hostile-value containment; state the trust premise.

Scripts are model-written — the same trust level as the model's bash
access — yet successive pre-push review rounds had ratcheted in defenses
that only matter against an adversarial author: trap-free proxy
rejection, accessor-never-invoked descriptor walks, realm-side
pre-rendering of thrown values, realm-built promises/arrays/error clones
with structural fatal recognition. That same author keeps a documented,
accepted, unkillable event-loop spin, so containing its error VALUES is
cost without a threat model — and the planned hardened engine
(worker/isolated-vm) gets value isolation by serialization and deletes
all of this machinery anyway.

What stays, because benign scripts hit it constantly: result never
rejects; dropped hook promises cannot become unhandled rejections; the
value boundary rejects LOUD everything JSON cannot carry (now a plain
recursive walk — getters are read ordinarily and their result is what
crosses; a throwing read fails loud); a "__proto__" key still copies as
a data property; the fatal-vs-null combinator discipline (now host
instanceof — unforgeable from the realm and simpler than clone-shape
recognition). What changes for scripts (documented in the engine
README): hooks hand back host values and host errors — in-script
`instanceof Error` on a hook failure is false (branch on e.name/e.code)
— and args are host-cloned once so a script cannot mutate the caller's
object. realm.ts drops 289 → 173 lines; the hostile-value test tables go
with it. The premise now leads the engine module doc, the README, and
the RFC's engine section, with the removed machinery recorded under
What was rejected.

2) result settles within the dispose grace of a cancellation.

Review finding (verified through the real registry + tool + engine): a
script parked on a promise no hook owns — `await new Promise(() => {})`,
`await Promise.race([])`, a returned never-settling thenable — could not
be settled by cancel(): hooks reject and children abort, but nothing
touches a promise the engine does not own, so `result` stayed pending
FOREVER (the previous cut even pinned that as intended). The tool awaits
run.result BEFORE its disposing finally, the registry awaits the tool,
the loop awaits the registry — one such script wedged the whole agent
turn past any abort, unrecoverable in-process; the mock engine in the
tool's abort test settles result on cancel, which is exactly the
behavior the real engine lacked, so no existing test could see it.

The seam contract now says it out loud: once a run is cancelled, result
SETTLES within the implementation's bounded grace even if the script
never does. The vm engine arms an abandon channel in cancel(); drive()
races the script against it, force-settling 'cancelled' at the grace
(the abandoned settlement stays contained; a post-slice synchronous spin
remains the documented limitation). dispose()'s outer race now exists
for child quiescence only, and `workflow/end` again fires exactly once
per started run. The old 'result stays pending' pin is FLIPPED to the
new contract (the pinned behavior was the bug); new regressions cover
cancel-then-settle on a parked script, a never-settling returned
thenable, and the full composition through the REAL registry + tool +
vm engine (tool-workflow gains workflow-vm/subagent devDeps for it).
agentsStarted JSDoc clarified while touching the vocabulary (accepted
calls, including ones still queued at cancellation).

packages/workflow/workflow/README.md

@@ -4,7 +4,7 @@ The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a wor
 
 ## Service: `WorkflowService` (abstract)
 
-`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'`). `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.
+`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.
 
 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.
 

packages/workflow/workflow/src/index.ts

@@ -127,8 +127,8 @@ export type WorkflowEventName =
  *   subset (see dsh-tools).
  * - `AGENT_CAP` / `ITEM_CAP` — the run/agent caps tripped.
  * - `AGENT_START` — the subagent seam refused to start a child.
- * - `RESULT_UNSERIALIZABLE` — a value crossing the realm boundary is not
- *   plain JSON data.
+ * - `RESULT_UNSERIALIZABLE` — a value crossing the script/host value boundary
+ *   is not plain JSON data.
  * - `CANCELLED` — the run was cancelled; pending and future hooks reject
  *   with this (the script-kill mechanism).
  */
@@ -179,7 +179,10 @@ export function isFatalWorkflowError(error: unknown): boolean {
  * - {@link start} throws synchronously for a request that cannot begin (an
  *   unparseable script, an invalid meta block). Once it returns a
  *   {@link WorkflowRun}, `result` NEVER rejects — every failure resolves with
- *   `stopReason: 'error'` (or `'cancelled'`).
+ *   `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).
  * - The `workflow/*` events fire through {@link emitWorkflowEvent} (data
  *   snapshots, per-listener containment); `workflow/end` fires exactly once
  *   per started run, after `result` is settled or as it settles.

packages/workflow/workflow/src/types.ts

@@ -85,7 +85,7 @@ export interface WorkflowResult {
   stopReason: WorkflowStopReason
   /** The failure message (present iff `stopReason` is not `completed`). */
   error?: string
-  /** How many `agent()` calls the run started (across its whole lifetime). */
+  /** How many `agent()` calls the run accepted (whole lifetime, including calls still queued for a slot when the run was cancelled). */
   agentsStarted: number
 }
 
@@ -93,17 +93,19 @@ export interface WorkflowResult {
  * The handle the consumer holds while a script executes. The consumer awaits
  * `result`, may `cancel` mid-flight, and MUST `dispose` on every path.
  * `result` does NOT reject — a script failure resolves with `stopReason:
- * 'error'` — so the consumer maps a non-`completed` reason to an `isError`
- * result. `dispose()` cancels, then waits a bounded grace for the script to
- * settle before abandoning it (the engine documents the abandonment
- * semantics); it never hangs on a stuck script.
+ * 'error'` — and once the run is cancelled it SETTLES within the engine's
+ * bounded grace even if the script itself never settles (the engine abandons
+ * the script and reports `cancelled`), so a consumer awaiting `result` is
+ * never wedged past a cancellation. `dispose()` = cancel + that bounded
+ * settle + child quiescence; it never hangs on a stuck script and is safe to
+ * call on every path (idempotent).
  */
 export interface WorkflowRun {
   readonly id: WorkflowRunId
   /** The validated meta block (available before the body runs). */
   readonly meta: WorkflowMeta
   readonly result: Promise<WorkflowResult>
-  /** Cancel the run: children abort, pending hooks reject, the script dies at its next await. */
+  /** Cancel the run: children abort, pending hooks reject, the script dies at its next await (or is abandoned at the grace). */
   cancel(reason?: string): void
   /** Cancel + bounded-grace settle; safe to call on every path (idempotent). */
   dispose(): Promise<void>
@@ -149,6 +151,6 @@ export interface WorkflowResultInfo {
   stopReason: WorkflowStopReason
   /** The failure message (present iff `stopReason` is not `completed`). */
   error?: string
-  /** How many `agent()` calls the run started. */
+  /** How many `agent()` calls the run accepted (see {@link WorkflowResult.agentsStarted}). */
   agentsStarted: number
 }