tape-six 1.9.0 → 1.10.0

package/README.md

@@ -122,6 +122,8 @@ See how it can be used in [tests/](https://github.com/uhop/tape-six/tree/master/
 
 For AI assistants: see [llms.txt](https://github.com/uhop/tape-six/blob/master/llms.txt) and [llms-full.txt](https://github.com/uhop/tape-six/blob/master/llms-full.txt) for LLM-optimized documentation.
 
+When you use `tape-six` as a dependency, point your AI coding agent at the guides shipped inside `node_modules/tape-six/`: [`TESTING.md`](https://github.com/uhop/tape-six/blob/master/TESTING.md) and the `skills/` directory (`write-tests`, `run-tests`). They are written so an agent can write and run `tape-six` tests correctly without fetching anything.
+
 The whole API is based on two objects: `test` and `Tester`.
 
 ### `test`
@@ -425,7 +427,8 @@ Test output can be controlled by flags. See [Supported flags](https://github.com
 
 The most recent releases:
 
-- 1.9.0 _New features: `t.plan(n)` emits a TAP-comment diagnostic on mismatch, `registerTesterMethod(name, fn)` registers tester plugins idempotently. New wiki: 3rd-party library catalog and "Writing plugins" page. Removed `chai` from dev dependencies._
+- 1.10.0 _Worker control channel stops in-flight workers, draining cleanup before a force-kill._
+- 1.9.0 _New features: `t.plan(n)` emits a TAP-comment diagnostic on mismatch, `registerTesterMethod(name, fn)` registers tester plugins idempotently._
 - 1.8.0 _New subpath modules: `tape-six/server` (HTTP server harness) and `tape-six/response` (response reading helpers for `Response` and `IncomingMessage`)._
 - 1.7.14 _Updated vendored `deep6` to 1.2.0._
 - 1.7.13 _Replaced `process.exit()` / `Deno.exit()` with `process.exitCode` in test runners and `index.js` for graceful stdout flushing. Updated dependencies, GitHub Actions._

package/TESTING.md

@@ -335,127 +335,6 @@ test('suite B', dbOpts, async t => {
 });
 ```
 
-## Testing HTTP code
-
-Two subpath modules ship for tests that need HTTP-shaped fixtures. Both work on Node, Bun, and Deno via `node:http`. Browsers don't get them — running an HTTP server inside a webpage isn't a use case.
-
-> **Placement matters.** Test files that import `tape-six/server`, `tape-six/response`, or any other node-only API (e.g. `node:http`, `node:fs`, `node:child_process`) **must not** match a `tape6.tests` pattern that's universal to all environments — the browser worker would try to load them and fail with `Worker error` on the missing built-in. Put them in a CLI-only location (e.g. `tests/cli/test-*.js`) and add the matching glob to `tape6.cli` so it covers Node/Bun/Deno but not browsers. See [Configuring test discovery](#configuring-test-discovery).
-
-### `tape-six/server` — server harness
-
-```js
-import {withServer, startServer, setupServer} from 'tape-six/server';
-```
-
-Three exports for three lifetimes. `withServer` is the per-test scoped resource (95% case). `startServer` is the procedural primitive. `setupServer` registers `beforeAll`/`afterAll` for suite-shared servers.
-
-**Per-test server** — start before the test body, tear down in `finally`:
-
-```js
-import test from 'tape-six';
-import {withServer} from 'tape-six/server';
-
-test('GET / returns 200', t =>
-  withServer(myHandler, async base => {
-    const res = await fetch(`${base}/`);
-    t.equal(res.status, 200);
-  }));
-```
-
-`myHandler` is a `(req, res) => void` callback (`http.RequestListener`). `base` is the bound URL, e.g. `"http://127.0.0.1:54321"`. Default host is `'127.0.0.1'` (explicit IPv4); pass `{host, port}` to override.
-
-`withServer` handles the symmetric case where the test makes requests directly. It's also the right tool when the SUT is something else (a CLI spawned in a subprocess) and the handler is a mock — the test body just looks different:
-
-```js
-test('CLI hits the API correctly', t =>
-  withServer(mockApi, async base => {
-    const result = await spawnCli({env: {API_URL: base}});
-    t.equal(result.exitCode, 0);
-    t.equal(recordedRequests.length, 1);
-  }));
-```
-
-Either side may be the SUT. The names `serverHandler` / `clientHandler` reflect role on the wire, not which side is being tested.
-
-**Suite-shared server** — register hooks once, share across many tests:
-
-```js
-import test, {beforeEach} from 'tape-six';
-import {setupServer} from 'tape-six/server';
-
-let recorded;
-const server = setupServer((req, res) => {
-  recorded.push({method: req.method, url: req.url});
-  res.writeHead(204).end();
-});
-beforeEach(() => {
-  recorded = [];
-});
-
-test('records exactly one request', async t => {
-  await fetch(`${server.base}/foo`);
-  t.equal(recorded.length, 1);
-});
-
-test('records the path correctly', async t => {
-  await fetch(`${server.base}/bar`);
-  t.equal(recorded[0].url, '/bar');
-});
-```
-
-The returned handle has live getters — `server.base` reads the current state on each access. **Don't destructure** at module load (`const {base} = setupServer(...)`); `base` is `undefined` until `beforeAll` runs. Per-test state reset (the `recorded = []` above) is user-side via your own `beforeEach`; `setupServer` owns the server lifecycle, you own state.
-
-**Procedural primitive** — for multi-phase tests or non-test code:
-
-```js
-import http from 'node:http';
-import {startServer} from 'tape-six/server';
-
-const lc = await startServer(http.createServer(handler), {host, port});
-try {
-  // ... lc.base, lc.port, lc.host ...
-} finally {
-  await lc.close();
-}
-```
-
-`startServer` accepts a fully-constructed server (so the caller can attach `'clientError'` listeners or configure TLS first). It races `'listening'` against `'error'` so port-busy / `EACCES` rejects with the original error rather than hanging — the failure mode existing helpers across the ecosystem suffer from on busy CI machines.
-
-`close()` is idempotent and calls `server.closeAllConnections()` (when available, Node 18.2+) so keep-alive sockets from `fetch` don't delay teardown.
-
-### `tape-six/response` — response reading helpers
-
-```js
-import {asText, asJson, asBytes, header, headers} from 'tape-six/response';
-```
-
-Five reading helpers that work uniformly on both W3C `Response` (from `fetch`) and Node `http.IncomingMessage` (from `http.request`).
-
-```js
-import test from 'tape-six';
-import {withServer} from 'tape-six/server';
-import {asJson, header} from 'tape-six/response';
-
-test('GET / returns JSON', t =>
-  withServer(handler, async base => {
-    const res = await fetch(`${base}/`);
-    t.equal(res.status, 200);
-    t.match(header(res, 'content-type'), /^application\/json/);
-    const body = await asJson(res);
-    t.deepEqual(body, {ok: true});
-  }));
-```
-
-| Helper              | Returns                  | Notes                               |
-| ------------------- | ------------------------ | ----------------------------------- |
-| `asText(res)`       | `Promise<string>`        | UTF-8                               |
-| `asJson(res)`       | `Promise<unknown>`       | parses JSON                         |
-| `asBytes(res)`      | `Promise<Uint8Array>`    | raw bytes                           |
-| `header(res, name)` | `string \| null`         | case-insensitive single-header read |
-| `headers(res)`      | `Record<string, string>` | all headers, lowercase keys         |
-
-For status code, just use `res.status` (W3C `Response`) or `res.statusCode` (Node `IncomingMessage`) directly — no helper needed.
-
 ## Migrating from other test frameworks
 
 `tape-six` supports `describe`/`it` and `before`/`after` aliases. When called inside a test body, all top-level functions automatically delegate to the current tester. This means migration from Mocha, Jest, or `node:test` is nearly mechanical — change the import and swap assertions.

package/index.js

@@ -162,6 +162,33 @@ const init = async () => {
     setCurrentReporter?.(reporter);
   }
 
+  if (isBrowser && typeof window.addEventListener == 'function') {
+    // Control plane: the parent page posts `tape6-terminate` to drain a running
+    // test (failOnce / bail / worker deadline). The reporter arms stopTest +
+    // fires the abort signal so the test unwinds. There is no in-page
+    // force-kill — see dev-docs/worker-control-channel.md.
+    window.addEventListener('message', event => {
+      if (event.data?.type === 'tape6-terminate') getReporter()?.terminate();
+    });
+  }
+
+  if (isCli) {
+    // Control plane (proc transport): a child spawned by tape-six-proc is
+    // marked with TAPE6_CONTROL. Open the stdin control channel so the parent
+    // can drain / terminate it, and so it stays alive after `end` until told to
+    // exit — see dev-docs/worker-control-channel.md.
+    const controlled =
+      (isDeno && Deno.env.get('TAPE6_CONTROL')) ||
+      (isBun && Bun.env.TAPE6_CONTROL) ||
+      (isNode && process.env.TAPE6_CONTROL);
+    if (controlled) {
+      const {listenControlChannel} = await import(
+        new URL('./src/utils/control-channel.js', import.meta.url)
+      );
+      listenControlChannel(getReporter);
+    }
+  }
+
   return {options, isBrowser, isBun, isDeno, isNode, isCli};
 };
 

package/llms-full.txt

@@ -279,108 +279,6 @@ test('cli', async t => {
 
 Plugin installation is **per-file**. `tape6-seq` runs all files in one process; `tape6` uses workers; `tape6-proc` (from the sister package `tape-six-proc`) uses subprocesses; browser tests run in iframes. Each isolation context has its own module graph, so a plugin import in file A is invisible to file B when they're in different contexts. Every test file that uses a plugin must import it directly. `registerTesterMethod`'s idempotency makes repeated imports safe. See [Writing plugins](https://github.com/uhop/tape-six/wiki/Writing-plugins) for the full guide.
 
-## Subpath modules
-
-Two helper modules ship as separate subpath imports for tests that need HTTP-shaped fixtures. Both are cross-runtime (Node, Bun, Deno via `node:http`); browsers don't need them because running an HTTP server inside a webpage isn't a use case.
-
-### tape-six/server — HTTP server harness
-
-```js
-import {withServer, startServer, setupServer} from 'tape-six/server';
-```
-
-#### `withServer(serverHandler, clientHandler, opts?)` — scoped resource (95% case)
-
-Spins up an `http.Server` with `serverHandler`, runs `clientHandler` with the bound base URL, tears down in `finally`. Cleanup runs whether `clientHandler` resolves, rejects, or throws synchronously. Returns whatever `clientHandler` returns.
-
-```js
-test('GET / returns 200', t =>
-  withServer(handler, async base => {
-    const res = await fetch(`${base}/`);
-    t.equal(res.status, 200);
-  }));
-```
-
-`serverHandler` is the per-request callback Node invokes on each incoming request. `clientHandler` is the per-scope test body, called once with `(base, lifecycle)` — naming reflects role on the wire (server side / client side), not which side is the SUT. Either side may be the code under test.
-
-`clientHandler` may make HTTP requests itself (`fetch(base)`-style), or set up a separate SUT that does (e.g., a spawned CLI given `${base}` as its endpoint env var), or do neither (multi-phase setup + assertions).
-
-#### `startServer(server, opts?)` — procedural primitive
-
-For multi-phase tests that span the lifecycle, or non-test code (e.g. `bin/tape6-server`) that wants long-term control. Accepts a fully-constructed `http.Server` (so callers can attach `'clientError'` handlers, configure TLS, etc., before listen).
-
-```js
-const lc = await startServer(http.createServer(handler), {host, port});
-// ... use lc.base ...
-await lc.close();
-```
-
-Returns a lifecycle handle:
-
-- `server` — the underlying `http.Server`.
-- `base` — bound base URL, e.g. `"http://127.0.0.1:54321"`.
-- `port` — actual bound port (OS-assigned when `port: 0`).
-- `host` — bound host.
-- `close()` — idempotent. Calls `server.closeAllConnections()` (when available) so keep-alive sockets don't delay teardown.
-
-Races `'listening'` against `'error'`: port-busy / `EACCES` rejects with the original error rather than hanging. Existing helpers across the toolkit ecosystem don't do this and have hung CI machines as a result.
-
-#### `setupServer(serverHandler, opts?)` — hook helper
-
-Registers `beforeAll` (start) and `afterAll` (close) and returns a live-getter handle for suite-shared servers:
-
-```js
-const server = setupServer(handler);
-
-test('first', async t => {
-  const res = await fetch(`${server.base}/foo`);
-});
-
-test('second', async t => {
-  const res = await fetch(`${server.base}/bar`);
-});
-```
-
-The returned object is `Object.freeze`d and uses property getters that read the live lifecycle. Don't destructure at module load (`const {base} = setupServer(...)`) — `base` is `undefined` until `beforeAll` runs.
-
-State reset stays user-side. For mock-server scenarios that need per-test state clearing, compose your own `beforeEach`:
-
-```js
-const server = setupServer((req, res) => {
-  recorded.push({method: req.method, url: req.url});
-  res.writeHead(204).end();
-});
-let recorded;
-beforeEach(() => { recorded = []; });
-```
-
-`setupServer` owns the suite lifecycle; the caller owns suite state.
-
-#### Options
-
-```ts
-interface ServerOptions {
-  host?: string;  // default '127.0.0.1' — explicit IPv4 avoids dual-stack ambiguity
-  port?: number;  // default 0 — OS-assigned
-}
-```
-
-### tape-six/response — HTTP response helpers
-
-Reading helpers that work uniformly with both `Response` (fetch results) and Node `http.IncomingMessage`:
-
-```js
-import {asText, asJson, asBytes, header, headers} from 'tape-six/response';
-```
-
-- `asText(res)` → `Promise<string>` — body as UTF-8.
-- `asJson(res)` → `Promise<unknown>` — body parsed as JSON.
-- `asBytes(res)` → `Promise<Uint8Array>` — body as raw bytes.
-- `header(res, name)` → `string | null` — case-insensitive single-header read. Array-valued `IncomingMessage` headers (e.g. `set-cookie`) are joined with `, `.
-- `headers(res)` → `Record<string, string>` — all headers as a plain object with lowercase keys.
-
-For status code, just use `res.status` — same on both `Response` and `IncomingMessage`.
-
 ## Configuring tests
 
 Configuration is read from `tape6.json` or the `"tape6"` section of `package.json`:
@@ -480,6 +378,8 @@ Browser: `http://localhost:3000/?flags=FO`
 - `TAPE6_JSONL` — force JSONL reporter (any non-empty value).
 - `TAPE6_MIN` — force minimal reporter (any non-empty value).
 - `TAPE6_TEST_FILE_NAME` — set by runners to identify the current test file.
+- `TAPE6_GRACE_TIMEOUT` — ms a worker gets to drain (run cleanup, flush) after the runner asks it to stop, before being force-killed (default: 5000).
+- `TAPE6_WORKER_TIMEOUT` — per-file wall-clock budget in ms; on expiry the runner stops that worker (default: 0, disabled). The complement to the per-test `timeout` option: this one can stop a worker that ignores `t.signal`.
 
 ## Browser testing
 

package/llms.txt

@@ -143,37 +143,6 @@ test('suite', async t => {
 test.beforeAll(() => { /* ... */ });
 ```
 
-## Subpath modules
-
-### tape-six/server — HTTP server harness
-
-Helpers for tests that need an ephemeral `node:http` server. Cross-runtime (Node, Bun, Deno; not for browser-side tests).
-
-```js
-import {withServer, startServer, setupServer} from 'tape-six/server';
-```
-
-- `withServer(serverHandler, clientHandler, opts?)` — scoped resource: spin up a server, run the test body with the base URL, tear down in `finally`. The 95% case.
-- `startServer(server, opts?)` — procedural primitive: returns `{server, base, port, host, close}`. For multi-phase tests or non-test code (e.g., `bin/tape6-server`) that wants long-term control. Races `'listening'` against `'error'` so port-busy rejects instead of hanging.
-- `setupServer(serverHandler, opts?)` — registers `beforeAll`/`afterAll` and returns a live-getter context for suite-shared servers. Don't destructure the returned object at module load — properties read live state on each access.
-- Options: `{host = '127.0.0.1', port = 0}`. Default host is explicit IPv4.
-
-`serverHandler` is the per-request callback (Node calls it once per incoming request). `clientHandler` is the per-scope test body (called once with the base URL). Either side may be the SUT.
-
-### tape-six/response — HTTP response helpers
-
-Reading helpers that work uniformly with both `Response` (fetch results) and `http.IncomingMessage` (Node low-level requests).
-
-```js
-import {asText, asJson, asBytes, header, headers} from 'tape-six/response';
-```
-
-- `asText(res)` — body as UTF-8 string.
-- `asJson(res)` — body parsed as JSON.
-- `asBytes(res)` — body as `Uint8Array`.
-- `header(res, name)` — single header value, case-insensitive. Returns `null` if absent.
-- `headers(res)` — all headers as a plain object with lowercase keys.
-
 ## Common patterns
 
 ### Basic test file
@@ -248,41 +217,6 @@ describe('my module', () => {
 });
 ```
 
-### Testing HTTP code with `withServer`
-
-```js
-import test from 'tape-six';
-import {withServer} from 'tape-six/server';
-import {asJson} from 'tape-six/response';
-
-test('GET /users returns the list', t =>
-  withServer(myHandler, async base => {
-    const res = await fetch(`${base}/users`);
-    t.equal(res.status, 200);
-    const body = await asJson(res);
-    t.equal(body.length, 3);
-  }));
-```
-
-Suite-shared server (multiple tests against one instance):
-
-```js
-import test, {beforeEach} from 'tape-six';
-import {setupServer} from 'tape-six/server';
-
-const server = setupServer((req, res) => {
-  recorded.push({method: req.method, url: req.url});
-  res.writeHead(204).end();
-});
-let recorded;
-beforeEach(() => { recorded = []; });
-
-test('records one request', async t => {
-  await fetch(`${server.base}/foo`);
-  t.equal(recorded.length, 1);
-});
-```
-
 ### Skip and TODO
 
 ```js
@@ -307,6 +241,8 @@ npx tape6-server --trace   # start browser test server
 - `TAPE6_JSONL` — force JSONL reporter (any non-empty value).
 - `TAPE6_MIN` — force minimal reporter (any non-empty value).
 - `TAPE6_TEST_FILE_NAME` — set by runners to identify the current test file.
+- `TAPE6_GRACE_TIMEOUT` — ms a worker gets to drain (run cleanup, flush) after the runner asks it to stop, before being force-killed (default: 5000).
+- `TAPE6_WORKER_TIMEOUT` — per-file wall-clock budget in ms; on expiry the runner stops that worker (default: 0, disabled). Complements the per-test `timeout` option: this one can stop a worker that ignores `t.signal`.
 
 ## Configuration (package.json)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "TAP-inspired unit test library for Node, Deno, Bun, and browsers. ES modules, TypeScript, zero dependencies.",
   "type": "module",
   "main": "index.js",
@@ -8,15 +8,6 @@
   "types": "index.d.ts",
   "exports": {
     ".": "./index.js",
-    "./server": {
-      "types": "./src/server.d.ts",
-      "default": "./src/server.js"
-    },
-    "./response": {
-      "types": "./src/response.d.ts",
-      "default": "./src/response.js"
-    },
-    "./bin/*": "./bin/*",
     "./*": "./src/*"
   },
   "bin": {
@@ -112,7 +103,7 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.1",
     "typescript": "^6.0.3"
   }
 }

package/skills/run-tests/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: run-tests
+description: Set up `npm test` and run tape-six tests for a project. Use when configuring a project's test scripts in package.json, picking a runner, or debugging test invocation.
+---
+
+# Run Tests
+
+Configure and invoke tape-six tests for a project that uses `tape-six`.
+
+## What the runner is for
+
+**tape-six test files are directly executable** — `node tests/test-foo.js` (or `bun tests/test-foo.js`, `deno run -A tests/test-foo.js`) works without any runner, no transpilation, no harness wrapping the test code. This is a defining property of tape-six.
+
+The `tape6` runner exists only for **orchestration**: parallel execution via worker threads, glob-based test discovery, per-environment filtering (Node / Bun / Deno / browser), and aggregated reporting. When iterating on a single file, run it directly — it's faster and gives cleaner stack traces. Use the runner for `npm test` (full-suite invocation) and CI.
+
+## Steps
+
+1. **Install** tape-six as a dev dependency: `npm install -D tape-six`.
+
+2. **Add the test script** to `package.json#scripts`:
+
+   ```jsonc
+   {
+     "scripts": {
+       "test": "tape6 --flags FO"
+     }
+   }
+   ```
+
+   Optional siblings:
+   - `"test:seq": "tape6-seq --flags FO"` — sequential, in-process; easier to debug.
+   - `"test:bun": "tape6-bun --flags FO"` / `"test:deno": "tape6-deno --flags FO"` — explicit-runtime sweeps for cross-runtime libraries.
+   - `"start": "tape6-server --trace"` — browser-test HTTP harness.
+
+3. **Add the `tape6` config block** to `package.json` for test discovery:
+
+   ```jsonc
+   {
+     "tape6": {
+       "tests": ["/tests/test-*.js"],
+       "importmap": {
+         "imports": {
+           "my-package": "/index.js",
+           "my-package/": "/src/"
+         }
+       }
+     }
+   }
+   ```
+
+   Per-environment globs (`cli`, `node`, `bun`, `deno`, `browser`) are additive on top of `tests`. Use them when a test imports environment-specific APIs (e.g. `node:http` tests under `cli` so they don't run in the browser worker).
+
+4. **Verify**: `npm test`. To run a single file directly without the runner: `node tests/test-foo.js` (tape-six tests are directly executable; this is the fastest path when iterating on one file).
+
+## Default flags
+
+`--flags FO` — **F**ailures only, fail **O**nce (quiet on green, stop on the first red). It is a recommended default, not a mandate; some teams prefer the verbose default (no flags) or just `F` without early-exit. Lowercase disables, so `--flags fo` inverts both for one run (shows passes, continues past failures). Override per-invocation with the `TAPE6_FLAGS` environment variable: `TAPE6_FLAGS=FO node tests/test-foo.js`. Other flag letters cover banner / time / data / numbers / color — see [Supported flags](https://github.com/uhop/tape-six/wiki/Supported-flags) for the full list and override precedence.
+
+## Runner family
+
+Pick by environment, not preference. Default `tape6` auto-detects the runtime and routes appropriately; explicit pinning is for cross-runtime CI sweeps.
+
+- **`tape6`** — default. Auto-detects Node / Bun / Deno.
+- **`tape6-bun` / `tape6-deno` / `tape6-node`** — pin to a specific runtime (typically for cross-runtime CI matrices).
+- **`tape6-seq`** — sequential, in-process. Use for debugging or when tests share state.
+- **`tape6-server`** — browser-test HTTP harness. Run `npx tape6-server --trace`, then open `http://localhost:3000`.
+- **`tape-six-proc`** (separate npm package) — process-per-file isolation when worker threads aren't enough.
+
+## Further reading (wiki)
+
+For anything beyond this skill, consult the wiki — it has the long tail:
+
+- [Set-up tests](https://github.com/uhop/tape-six/wiki/Set-up-tests) — full `tape6` config-block reference, every per-environment glob.
+- [Supported flags](https://github.com/uhop/tape-six/wiki/Supported-flags) — every flag, every override layer.
+- [Utility tape6](https://github.com/uhop/tape-six/wiki/Utility-‐-tape6) — runner CLI options, env vars (`TAPE6_FLAGS`, `TAPE6_PAR`, `TAPE6_WORKER_START_TIMEOUT`), parallelism control, `--info`.
+- [Utility tape6-server](https://github.com/uhop/tape-six/wiki/Utility-‐-tape6‐server) — browser harness, query parameters, dev-time path mounts.
+- [Environment — Node](https://github.com/uhop/tape-six/wiki/Environment-‐-Node) / [Bun](https://github.com/uhop/tape-six/wiki/Environment-‐-Bun) / [Deno](https://github.com/uhop/tape-six/wiki/Environment-‐-Deno) / [Browsers](https://github.com/uhop/tape-six/wiki/Environment-‐-Browsers) — runtime-specific guidance.

package/skills/write-tests/SKILL.md

@@ -65,23 +65,17 @@ Write or update tests using the tape-six testing library.
    - `t.skipTest(msg)` — skip the _current_ test from inside it.
    - `t.bailOut(msg)` — stop the entire run (catastrophic).
    - `t.OK(expr, msg)` (aliases `t.TRUE`, `t.ASSERT`) — returns a code string for `eval()` that asserts an expression and dumps top-level variables on failure. Useful for compact arithmetic/state checks: `eval(t.OK('a + b === 3'))`. Do not use in CSP-restricted contexts.
-10. **Testing HTTP code** — for tests that need an ephemeral HTTP server or want to read responses uniformly:
-    - **`tape-six/server`** (`withServer` / `startServer` / `setupServer`) — wraps the `node:http` lifecycle. `withServer(serverHandler, clientHandler, opts?)` is the per-test scoped resource: starts a server, runs the test body with the bound base URL, tears down in `finally`. `setupServer(serverHandler, opts?)` registers `beforeAll`/`afterAll` and returns a live-getter handle for suite-shared servers (don't destructure at module load — properties read live state). `startServer(server, opts?)` is the procedural primitive for multi-phase tests. Default host is `'127.0.0.1'`. Cross-runtime (Node, Bun, Deno).
-    - **`tape-six/response`** (`asText` / `asJson` / `asBytes` / `header` / `headers`) — reading helpers that work uniformly on both W3C `Response` (fetch results) and Node `http.IncomingMessage`.
-    - Per-test mock-server state reset (e.g., clearing a `recorded[]` array) stays user-side: compose your own `beforeEach`. `setupServer` owns the server lifecycle; you own state.
-    - **Placement:** these tests can't run in the browser worker — `node:http` doesn't exist there. Don't drop them into a folder matched by the universal `tape6.tests` glob; put them in a CLI-only path (e.g. `tests/cli/test-*.js`) and ensure the matching glob is in `tape6.cli` instead.
-    - See "Testing HTTP code" in `TESTING.md` for examples.
-11. **Browser-specific tests** — if the project uses browser testing with `tape6-server`. See "Browser testing" in `TESTING.md`.
+10. **Browser-specific tests** — if the project uses browser testing with `tape6-server`. See "Browser testing" in `TESTING.md`.
     - Browsers run `.js` and `.mjs` only — no TypeScript, no CommonJS.
     - Browsers can also run `.html` shim files (with inline importmap and `<script type="module">`).
     - Place browser-only files in `tests/browser/` and add patterns to `"browser"` in the `tape6` config.
     - Run: `npx tape6-server --trace`, then open `http://localhost:3000`. Use `?q=<glob>` to filter, `?flags=FO` and `?par=N` to control output and parallelism.
-12. **Environment-specific tests** — the `tape6` config in `package.json` supports per-env patterns (`tests`, `cli`, `node`, `bun`, `deno`, `browser`). All are additive. See "Configuring test discovery" in `TESTING.md`.
-13. **Verify (CLI):** run the new test file directly: `node tests/test-<name>.js`
+11. **Environment-specific tests** — the `tape6` config in `package.json` supports per-env patterns (`tests`, `cli`, `node`, `bun`, `deno`, `browser`). All are additive. See "Configuring test discovery" in `TESTING.md`.
+12. **Verify (CLI):** run the new test file directly: `node tests/test-<name>.js`
     - Run the full suite to check for regressions: `npm test`
     - For debugging, use `npm run test:seq` (sequential, in-process).
     - To see which files are being run, add `--flags fo` (overrides the default `--flags FO`).
     - To inspect the resolved config without running, use `npx tape6 --info`.
     - For tests with heavy `beforeAll` (Docker spawn, big fixture loads), bump the worker startup timer with `TAPE6_WORKER_START_TIMEOUT=60000`. The default is 5 s.
-14. **Verify (browser):** start `npx tape6-server --trace`, then open `http://localhost:3000/?q=/tests/test-<name>.js` to run a specific file. Use multiple `?q=` parameters to run several files. Open `http://localhost:3000/` to run all configured tests.
-15. Report results and any failures.
+13. **Verify (browser):** start `npx tape6-server --trace`, then open `http://localhost:3000/?q=/tests/test-<name>.js` to run a specific file. Use multiple `?q=` parameters to run several files. Open `http://localhost:3000/` to run all configured tests.
+14. Report results and any failures.

package/src/reporters/Reporter.js

@@ -7,6 +7,7 @@ export class Reporter {
     this.state = null;
     this.depth = 0;
     this.timer = timer || getTimer();
+    this.terminating = false;
   }
 
   get signal() {
@@ -17,6 +18,22 @@ export class Reporter {
     this.state?.abort();
   }
 
+  // Control plane: a `terminate` command reached this worker (failOnce / bail
+  // drain, or a worker deadline). Arm stopTest and fire the abort signal across
+  // the live state chain so a running test unwinds — StopTest at the next
+  // assertion, t.signal rejects signal-aware awaits — and remember it so any
+  // test that starts afterwards stops at its first assertion too (closing the
+  // race where `terminate` lands while the worker is still starting up). The
+  // test's cleanup (finally / afterEach / afterAll) still runs. See
+  // dev-docs/worker-control-channel.md.
+  terminate() {
+    this.terminating = true;
+    for (let state = this.state; state; state = state.parent) {
+      state.stopTest = true;
+      state.abort();
+    }
+  }
+
   onTest(event) {
     this.state = new State(this.state, {
       name: event.name,
@@ -28,6 +45,12 @@ export class Reporter {
       timer: this.timer
     });
     ++this.depth;
+    // A terminate landed before this test started — stop it at its first
+    // assertion rather than letting it run to completion.
+    if (this.terminating) {
+      this.state.stopTest = true;
+      this.state.abort();
+    }
     if (typeof event.time != 'number') {
       event = {...event, time: this.state.time};
     }

package/src/runners/bun/TestWorker.js

@@ -10,6 +10,7 @@ export default class TestWorker extends EventServer {
     super(reporter, numberOfTasks, options);
     this.counter = 0;
     this.idToWorker = {};
+    this.graceTimers = {};
   }
   makeTask(fileName) {
     const testName = new URL(fileName, baseName),
@@ -69,7 +70,31 @@ export default class TestWorker extends EventServer {
     });
     return id;
   }
-  destroyTask(id) {
+  destroyTask(id, reason = 'done') {
+    const worker = this.idToWorker[id];
+    if (!worker) return;
+    if (reason === 'done') {
+      // The test already finished; just tear the worker down.
+      this.#kill(id);
+      return;
+    }
+    // Cooperative drain (abort): ask the child to fire its abort signal and run
+    // cleanup hooks, then force-kill as a backstop after graceTimeout in case
+    // the test ignores the signal and never settles.
+    if (this.graceTimers[id]) return; // already draining
+    try {
+      worker.postMessage({type: 'terminate', reason});
+    } catch (e) {
+      void e;
+    }
+    this.graceTimers[id] = setTimeout(() => this.#kill(id), this.graceTimeout);
+  }
+  #kill(id) {
+    const grace = this.graceTimers[id];
+    if (grace) {
+      clearTimeout(grace);
+      delete this.graceTimers[id];
+    }
     const worker = this.idToWorker[id];
     if (worker) {
       worker.terminate();

package/src/runners/bun/worker.js

@@ -33,14 +33,27 @@ const reportToParent = fileName => {
   };
 };
 
+let currentReporter = null,
+  pendingTerminate = false;
+
 addEventListener('message', async event => {
   const msg = event.data;
+  // Control plane: drain on `terminate`. The reporter arms stopTest + fires the
+  // abort signal so a running test unwinds (cleanup runs); a terminate that
+  // lands before the reporter exists is remembered and applied at startup.
+  if (msg?.type === 'terminate') {
+    pendingTerminate = true;
+    currentReporter?.terminate();
+    return;
+  }
   try {
     const [{setReporter}, {ProxyReporter}] = await Promise.all([
       import(new URL('test.js', msg.srcName)),
       import(new URL('./reporters/ProxyReporter.js', msg.srcName))
     ]);
-    setReporter(new ProxyReporter({...msg.options, reportTo: reportToParent(msg.fileName)}));
+    currentReporter = new ProxyReporter({...msg.options, reportTo: reportToParent(msg.fileName)});
+    setReporter(currentReporter);
+    if (pendingTerminate) currentReporter.terminate();
     await import(msg.testName);
   } catch (error) {
     postMessage({type: 'test', test: 0});

package/src/runners/deno/TestWorker.js

@@ -11,6 +11,7 @@ export default class TestWorker extends EventServer {
     super(reporter, numberOfTasks, options);
     this.counter = 0;
     this.idToWorker = {};
+    this.graceTimers = {};
   }
   makeTask(fileName) {
     const testName = new URL(fileName, baseName),
@@ -53,7 +54,31 @@ export default class TestWorker extends EventServer {
     });
     return id;
   }
-  destroyTask(id) {
+  destroyTask(id, reason = 'done') {
+    const worker = this.idToWorker[id];
+    if (!worker) return;
+    if (reason === 'done') {
+      // The test already finished; just tear the worker down.
+      this.#kill(id);
+      return;
+    }
+    // Cooperative drain (abort): ask the child to fire its abort signal and run
+    // cleanup hooks, then force-kill as a backstop after graceTimeout in case
+    // the test ignores the signal and never settles.
+    if (this.graceTimers[id]) return; // already draining
+    try {
+      worker.postMessage({type: 'terminate', reason});
+    } catch (e) {
+      void e;
+    }
+    this.graceTimers[id] = setTimeout(() => this.#kill(id), this.graceTimeout);
+  }
+  #kill(id) {
+    const grace = this.graceTimers[id];
+    if (grace) {
+      clearTimeout(grace);
+      delete this.graceTimers[id];
+    }
     const worker = this.idToWorker[id];
     if (worker) {
       worker.terminate();

package/src/runners/deno/worker.js

@@ -33,14 +33,27 @@ const reportToParent = fileName => {
   };
 };
 
+let currentReporter = null,
+  pendingTerminate = false;
+
 addEventListener('message', async event => {
   const msg = event.data;
+  // Control plane: drain on `terminate`. The reporter arms stopTest + fires the
+  // abort signal so a running test unwinds (cleanup runs); a terminate that
+  // lands before the reporter exists is remembered and applied at startup.
+  if (msg?.type === 'terminate') {
+    pendingTerminate = true;
+    currentReporter?.terminate();
+    return;
+  }
   try {
     const [{setReporter}, {ProxyReporter}] = await Promise.all([
       import(new URL('test.js', msg.srcName)),
       import(new URL('./reporters/ProxyReporter.js', msg.srcName))
     ]);
-    setReporter(new ProxyReporter({...msg.options, reportTo: reportToParent(msg.fileName)}));
+    currentReporter = new ProxyReporter({...msg.options, reportTo: reportToParent(msg.fileName)});
+    setReporter(currentReporter);
+    if (pendingTerminate) currentReporter.terminate();
     await import(msg.testName);
   } catch (error) {
     postMessage({type: 'test', test: 0});

package/src/runners/node/TestWorker.js

@@ -13,6 +13,7 @@ export default class TestWorker extends EventServer {
     super(reporter, numberOfTasks, options);
     this.counter = 0;
     this.idToWorker = {};
+    this.graceTimers = {};
   }
   makeTask(fileName) {
     const testName = new URL(fileName, baseName),
@@ -71,7 +72,32 @@ export default class TestWorker extends EventServer {
     });
     return id;
   }
-  destroyTask(id) {
+  destroyTask(id, reason = 'done') {
+    const worker = this.idToWorker[id];
+    if (!worker) return;
+    if (reason === 'done') {
+      // The test already finished; worker_threads have no flush race, so just
+      // tear the worker down.
+      this.#kill(id);
+      return;
+    }
+    // Cooperative drain (abort): ask the child to fire its abort signal and run
+    // cleanup hooks, then force-kill as a backstop after graceTimeout in case
+    // the test ignores the signal and never settles.
+    if (this.graceTimers[id]) return; // already draining
+    try {
+      worker.postMessage({type: 'terminate', reason});
+    } catch (e) {
+      void e;
+    }
+    this.graceTimers[id] = setTimeout(() => this.#kill(id), this.graceTimeout);
+  }
+  #kill(id) {
+    const grace = this.graceTimers[id];
+    if (grace) {
+      clearTimeout(grace);
+      delete this.graceTimers[id];
+    }
     const worker = this.idToWorker[id];
     if (worker) {
       worker.terminate();

package/src/runners/node/worker.js

@@ -36,13 +36,26 @@ const reportToParent = fileName => {
   };
 };
 
+let currentReporter = null,
+  pendingTerminate = false;
+
 parentPort.on('message', async msg => {
+  // Control plane: drain on `terminate`. The reporter arms stopTest + fires the
+  // abort signal so a running test unwinds (cleanup runs); a terminate that
+  // lands before the reporter exists is remembered and applied at startup.
+  if (msg?.type === 'terminate') {
+    pendingTerminate = true;
+    currentReporter?.terminate();
+    return;
+  }
   try {
     const [{setReporter}, {ProxyReporter}] = await Promise.all([
       import(new URL('test.js', msg.srcName)),
       import(new URL('./reporters/ProxyReporter.js', msg.srcName))
     ]);
-    setReporter(new ProxyReporter({...msg.options, reportTo: reportToParent(msg.fileName)}));
+    currentReporter = new ProxyReporter({...msg.options, reportTo: reportToParent(msg.fileName)});
+    setReporter(currentReporter);
+    if (pendingTerminate) currentReporter.terminate();
     await import(msg.testName);
   } catch (error) {
     parentPort.postMessage({type: 'test', test: 0});

package/src/runners/seq/TestWorker.js

@@ -60,7 +60,15 @@ export default class TestWorker extends EventServer {
       .catch(error => this.#reportError(id, error));
     return id;
   }
-  destroyTask() {
+  destroyTask(id, reason = 'done') {
+    if (reason !== 'done') {
+      // Abort trigger (failOnce / bail / worker deadline). The test runs in this
+      // same process, so "terminate" is just reporter.terminate(): arm stopTest
+      // + fire the abort signal. The run unwinds and closes itself with 'done',
+      // where the reset below happens.
+      this.reporter.terminate();
+      return;
+    }
     setReporter(this.reporter);
     setCurrentReporter(null);
     clearBeforeAll();

package/src/utils/EventServer.js

@@ -1,18 +1,47 @@
 import defer from './defer.js';
 
+// Fallback used when no graceTimeout is supplied through options (e.g. the
+// in-browser web-app worker). CLI runners inject the env-configurable value
+// (TAPE6_GRACE_TIMEOUT) via getOptions(); see src/utils/config.js.
+const DEFAULT_GRACE_TIMEOUT = 5_000;
+
+// EventServer owns two planes. The DATA plane (worker -> reporter) is the
+// report()/close() event-ordering machinery. The CONTROL plane
+// (reporter/runner -> worker) is a single command, `terminate`, delivered per
+// transport by destroyTask(id, reason). Two triggers fire it:
+//   - normal completion: close() terminates the just-finished worker ('done');
+//   - stop / bail-out:   when reporter.state.stopTest is set (failOnce / bail),
+//                        every in-flight worker is terminated ('failOnce').
+// An optional per-worker wall-clock deadline (workerTimeout, Layer 2) fires the
+// same command on expiry ('timeout'). See dev-docs/worker-control-channel.md.
 export default class EventServer {
   constructor(reporter, numberOfTasks = 1, options = {}) {
     this.reporter = reporter;
     this.numberOfTasks = numberOfTasks;
     this.options = options;
 
+    this.graceTimeout = options.graceTimeout > 0 ? options.graceTimeout : DEFAULT_GRACE_TIMEOUT;
+    this.workerTimeout = options.workerTimeout > 0 ? options.workerTimeout : 0;
+
     this.totalTasks = 0;
     this.fileQueue = [];
     this.passThroughId = null;
     this.retained = {};
     this.readyQueue = [];
+
+    // control plane bookkeeping
+    this.liveTasks = new Set();
+    this.deadlineTimers = {};
+    this.stopRequested = false;
   }
   report(id, event) {
+    // Stop / bail-out trigger. React the moment the signal arrives, even if
+    // this worker's events are still buffered behind the pass-through worker
+    // (its stopTest would otherwise not reach reporter.state until it flushes,
+    // which can be many seconds later). Children pre-set event.stopTest; the
+    // in-process (seq) path sets it during the forward below, caught by the
+    // reporter.state check.
+    if (event && (event.stopTest || event.type === 'bail-out')) this.#requestStop();
     if (this.passThroughId === null) this.passThroughId = id;
     const events = this.retained[id];
     if (this.passThroughId === id) {
@@ -22,7 +51,9 @@ export default class EventServer {
         }
         delete this.retained[id];
       }
-      return this.reporter.report(event, true);
+      this.reporter.report(event, true);
+      if (this.reporter.state?.stopTest) this.#requestStop();
+      return;
     }
     if (Array.isArray(events)) {
       events.push(event);
@@ -31,7 +62,9 @@ export default class EventServer {
     }
   }
   close(id) {
-    this.destroyTask(id);
+    this.#clearDeadline(id);
+    this.liveTasks.delete(id);
+    this.destroyTask(id, 'done');
     --this.totalTasks;
     if (this.fileQueue.length) {
       if (this.reporter.state?.stopTest) {
@@ -39,7 +72,7 @@ export default class EventServer {
       } else {
         ++this.totalTasks;
         const nextFile = this.fileQueue.shift();
-        defer(() => this.makeTask(nextFile));
+        defer(() => this.#startTask(nextFile));
       }
     }
     if (this.passThroughId === id) {
@@ -75,7 +108,7 @@ export default class EventServer {
     if (this.reporter.state?.stopTest) return;
     if (this.totalTasks < this.numberOfTasks) {
       ++this.totalTasks;
-      this.makeTask(fileName);
+      this.#startTask(fileName);
     } else {
       this.fileQueue.push(fileName);
     }
@@ -83,11 +116,46 @@ export default class EventServer {
   execute(files) {
     files.forEach(fileName => this.createTask(fileName));
   }
+  // Spawn one worker and register it for control-plane tracking. Routes both
+  // the initial batch (createTask) and queue drains (close) so liveTasks and
+  // the optional deadline cover every task, not just the first numberOfTasks.
+  #startTask(fileName) {
+    const id = this.makeTask(fileName);
+    if (id == null) return id;
+    this.liveTasks.add(id);
+    if (this.workerTimeout > 0) {
+      this.deadlineTimers[id] = setTimeout(() => {
+        delete this.deadlineTimers[id];
+        if (this.liveTasks.has(id)) this.destroyTask(id, 'timeout');
+      }, this.workerTimeout);
+    }
+    return id;
+  }
+  #clearDeadline(id) {
+    const timer = this.deadlineTimers[id];
+    if (timer) {
+      clearTimeout(timer);
+      delete this.deadlineTimers[id];
+    }
+  }
+  // Terminate every in-flight worker (abort) on top of the existing "stop
+  // scheduling new files." Fires at most once per run; callers decide when a
+  // stop / bail-out signal has been observed.
+  #requestStop() {
+    if (this.stopRequested) return;
+    this.stopRequested = true;
+    for (const id of this.liveTasks) {
+      this.destroyTask(id, 'failOnce');
+    }
+  }
   makeTask(fileName) {
     // TBD in children
     // should return a task id as a string
   }
-  destroyTask(id) {
-    // TBD in children
+  destroyTask(id, reason) {
+    // TBD in children: deliver `terminate` to one worker.
+    //   reason === 'done'    -> task finished; tear the worker down now
+    //   otherwise (abort)    -> drain (run cleanup), then force-kill after
+    //                           graceTimeout where the transport allows
   }
 }

package/src/utils/config.js

@@ -173,16 +173,34 @@ export const getReporterFileName = type => {
 };
 
 export const DEFAULT_START_TIMEOUT = 5_000;
-
-export const getTimeoutValue = () => {
-  if (runtime.name === 'browser') return DEFAULT_START_TIMEOUT;
-  const timeoutValue = runtime.getEnvVar('TAPE6_WORKER_START_TIMEOUT');
-  if (!timeoutValue) return DEFAULT_START_TIMEOUT;
-  let timeout = Number(timeoutValue);
-  if (isNaN(timeout) || timeout <= 0 || timeout === Infinity) timeout = DEFAULT_START_TIMEOUT;
+export const DEFAULT_GRACE_TIMEOUT = 5_000;
+
+// Read a positive-millisecond env var, falling back to `fallback` when it is
+// unset, non-numeric, non-positive, or Infinity. Always returns `fallback` in
+// the browser, where these env vars don't exist.
+const readTimeoutEnv = (name, fallback) => {
+  if (runtime.name === 'browser') return fallback;
+  const value = runtime.getEnvVar(name);
+  if (!value) return fallback;
+  const timeout = Number(value);
+  if (isNaN(timeout) || timeout <= 0 || timeout === Infinity) return fallback;
   return timeout;
 };
 
+// Per-worker startup budget: how long a freshly spawned worker has to emit its
+// first event before it's declared dead on arrival.
+export const getTimeoutValue = () =>
+  readTimeoutEnv('TAPE6_WORKER_START_TIMEOUT', DEFAULT_START_TIMEOUT);
+
+// Grace period a worker gets to drain (run cleanup hooks, flush) after a
+// `terminate` is issued, before the parent force-kills it where the transport
+// allows. See dev-docs/worker-control-channel.md.
+export const getGraceTimeout = () => readTimeoutEnv('TAPE6_GRACE_TIMEOUT', DEFAULT_GRACE_TIMEOUT);
+
+// Optional wall-clock budget per worker/file (Layer 2 termination). 0 disables
+// it — the default — so a worker deadline fires only when explicitly set.
+export const getWorkerTimeout = () => readTimeoutEnv('TAPE6_WORKER_TIMEOUT', 0);
+
 // parsing options
 
 export const flagNames = Object.fromEntries(
@@ -312,6 +330,11 @@ export const getOptions = extraOptions => {
   }
   options.parallel = parallel;
 
+  // Control-channel budgets ride along in the options bag handed to the
+  // TestWorker (EventServer). Children ignore them; only the parent acts.
+  options.flags.graceTimeout = getGraceTimeout();
+  options.flags.workerTimeout = getWorkerTimeout();
+
   return options;
 };
 

package/src/utils/control-channel.js

@@ -0,0 +1,109 @@
+import {runtime, getGraceTimeout} from './config.js';
+
+// Control plane, child side (proc transport). A proc-spawned child is an
+// ordinary test file run by this runtime; tape-six-proc marks it with
+// TAPE6_CONTROL and talks to it over stdin (line-delimited, mirroring the JSONL
+// data plane). The contract — see dev-docs/worker-control-channel.md:
+//   - The pending stdin read keeps the event loop open, so the child stays
+//     alive after emitting its top-level `end` and the parent decides when it
+//     exits. That parent-driven exit is what closes the Bun stdout-flush race
+//     (the child no longer self-exits while the parent's Web-Stream view of the
+//     pipe is mid-teardown; see topics/tape-six-proc-bun-summary-suppressed).
+//   - On a `terminate` line the child drains a running test via
+//     reporter.terminate() (arms stopTest + fires the abort signal; cleanup
+//     hooks still run).
+//   - On control-channel EOF (parent done, died, or pipe broke) it soft-
+//     terminates and lets the event loop empty for a natural, fully-flushed
+//     exit. An unref'd watchdog is the hard backstop: it fires only if a hung
+//     test keeps the loop alive past graceTimeout (e.g. the parent died before
+//     it could force-kill).
+
+const getStdinStream = async () => {
+  switch (runtime.name) {
+    case 'deno':
+      return Deno.stdin.readable;
+    case 'bun':
+      return Bun.stdin.stream();
+    case 'node': {
+      const {Readable} = await import('node:stream');
+      return Readable.toWeb(process.stdin);
+    }
+  }
+  return null;
+};
+
+const exitProcess = code => {
+  if (runtime.name === 'deno') {
+    Deno.exit(code || 0);
+  } else if (typeof process == 'object' && typeof process.exit == 'function') {
+    process.exit(code || 0);
+  }
+};
+
+const armWatchdog = (graceTimeout, getExitCode) => {
+  const watchdog = setTimeout(() => exitProcess(getExitCode()), graceTimeout);
+  // The watchdog must never keep the child alive on its own — it only matters
+  // when something else (a hung test) does. Unref so a clean drain exits at once.
+  if (typeof watchdog?.unref == 'function') {
+    watchdog.unref();
+  } else if (runtime.name === 'deno' && typeof Deno.unrefTimer == 'function') {
+    Deno.unrefTimer(watchdog);
+  }
+};
+
+export const listenControlChannel = async getReporter => {
+  const stream = await getStdinStream();
+  if (!stream) return;
+
+  const graceTimeout = getGraceTimeout(),
+    decoder = new TextDecoder(),
+    reader = stream.getReader(),
+    getExitCode = () =>
+      typeof process == 'object' && typeof process.exitCode == 'number' ? process.exitCode : 0;
+
+  let terminated = false;
+  const handleLine = line => {
+    const cmd = line.trim();
+    if (!cmd) return;
+    // Accept a bare `terminate` or a JSON {"cmd":"terminate","reason":...}.
+    if (cmd === 'terminate') {
+      terminated = true;
+      getReporter()?.terminate();
+    } else if (cmd[0] === '{') {
+      try {
+        const msg = JSON.parse(cmd);
+        if (msg?.cmd === 'terminate') {
+          terminated = true;
+          getReporter()?.terminate();
+        }
+      } catch (e) {
+        void e; // ignore a malformed control line
+      }
+    }
+  };
+
+  let buffer = '';
+  try {
+    for (;;) {
+      const {done, value} = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, {stream: true});
+      let nl;
+      while ((nl = buffer.indexOf('\n')) >= 0) {
+        handleLine(buffer.slice(0, nl));
+        buffer = buffer.slice(nl + 1);
+      }
+    }
+  } catch (e) {
+    void e; // a broken pipe reads as EOF for our purposes
+  }
+  if (buffer) handleLine(buffer);
+
+  // Control-channel EOF. If no explicit terminate arrived (parent died / pipe
+  // broke), soft-terminate so a still-running test drains. Then fall through:
+  // the loop empties and the runtime exits naturally, flushing stdout.
+  if (!terminated) getReporter()?.terminate();
+  armWatchdog(graceTimeout, getExitCode);
+};
+
+export default listenControlChannel;

package/web-app/TestWorker.js

@@ -7,6 +7,7 @@ export default class TestWorker extends EventServer {
 
     this.importmap = options?.importmap;
     this.counter = 0;
+    this.graceTimers = {};
 
     window.__tape6_reporter = (id, event) => {
       this.report(id, event);
@@ -83,8 +84,33 @@ export default class TestWorker extends EventServer {
     }
     return id;
   }
-  destroyTask(id) {
+  destroyTask(id, reason = 'done') {
+    if (reason === 'done') {
+      this.#removeIframe(id);
+      return;
+    }
+    // Cooperative drain only — in-page JS can't force-kill a hung iframe script.
+    // postMessage `terminate` so a cooperative test unwinds and runs its cleanup
+    // hooks; if it doesn't exit within graceTimeout, remove the iframe as a
+    // best-effort backstop. A driver-backed run (puppeteer / playwright) can do
+    // a real kill from Node — not wired here. See dev-docs/worker-control-channel.md.
+    if (this.graceTimers[id]) return;
+    const iframe = document.getElementById('test-iframe-' + id);
+    if (!iframe) return;
+    try {
+      iframe.contentWindow?.postMessage({type: 'tape6-terminate', reason}, '*');
+    } catch (e) {
+      void e;
+    }
+    this.graceTimers[id] = setTimeout(() => this.#removeIframe(id), this.graceTimeout);
+  }
+  #removeIframe(id) {
+    const grace = this.graceTimers[id];
+    if (grace) {
+      clearTimeout(grace);
+      delete this.graceTimers[id];
+    }
     const iframe = document.getElementById('test-iframe-' + id);
-    iframe && iframe.parentElement.removeChild(iframe);
+    iframe && iframe.parentElement && iframe.parentElement.removeChild(iframe);
   }
 }