@atolljs/core 0.1.6 → 0.1.8

package/src/index.ts

@@ -62,13 +62,18 @@ export {
   TaskTimeoutError,
   WorkerCrashedError,
 } from './pool/errors';
-export { connectWorker, workerClient } from './pool/workerClient';
+export { DedicatedWorker } from './pool/dedicatedWorker';
+export type { DedicatedWorkerConfig } from './pool/dedicatedWorker';
+export { connectWorker, resolveWorkerCount, workerClient } from './pool/workerClient';
 export type {
   ClientMethods,
   ConnectWorkerConfig,
   WorkerClient,
   WorkerMethods,
+  WorkerRunner,
 } from './pool/workerClient';
+export { connectSubWorker } from './pool/subWorkerClient';
+export type { ConnectSubWorkerConfig } from './pool/subWorkerClient';
 
 /* ── SharedWorker — one worker (and one buffer) across tabs/iframes ──────── */
 
@@ -114,3 +119,24 @@ export { defineTask, isAsyncTask, toTask } from './task';
 export type { AsyncTask, TaskSnapshot } from './task';
 export { getLogLevel, log, scoped, setLogLevel, setLogSink } from './log';
 export type { LogEntry, LogLevel, LogSink } from './log';
+export {
+  addDevtoolsSink,
+  devtoolsEnabled,
+  emitDevtools,
+  estimateCloneBytes,
+  installFetchProbe,
+  installMemoryProbe,
+  listDevtoolsCommands,
+  previewValue,
+  registerDevtoolsCommand,
+  runDevtoolsCommand,
+  setDevtoolsSink,
+} from './devtools';
+export type {
+  DevtoolsCommandHandler,
+  DevtoolsEvent,
+  DevtoolsSink,
+  DevtoolsThread,
+  EmittedDevtoolsEvent,
+  TaskSettleOutcome,
+} from './devtools';

package/src/log.ts

@@ -7,6 +7,8 @@
  *   setLogLevel('debug'); // or 'trace', 'warn', 'off'
  */
 
+import { devtoolsEnabled, emitDevtools, previewValue } from './devtools';
+
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'off';
 
 const LEVELS: Record<LogLevel, number> = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, off: 5 };
@@ -46,9 +48,29 @@ export const getLogLevel = (): LogLevel => minLevel;
 /** Replace the console sink (e.g. collect entries for a UI panel); null restores it. */
 export const setLogSink = (custom: LogSink | null): void => { sink = custom ?? consoleSink; };
 
+/** Set while a log entry is being mirrored, so a transport that logs can't recurse. */
+let teeing = false;
+
 export function log(level: Exclude<LogLevel, 'off'>, scope: string, message: string, data?: unknown): void {
   if (LEVELS[level] < LEVELS[minLevel]) return;
   sink({ level, scope, message, data, thread: THREAD, at: performance.now() });
+  // Mirror into the devtools stream alongside (never instead of) the log
+  // sink. Worker-side entries ride the same ATOLL_DEVTOOLS forwarding as
+  // every other worker event once the INIT handshake enables it.
+  if (!teeing && devtoolsEnabled()) {
+    teeing = true;
+    try {
+      emitDevtools({
+        type: 'log',
+        level,
+        scope,
+        message,
+        ...(data !== undefined ? { data: previewValue(data, 1024) } : {}),
+      });
+    } finally {
+      teeing = false;
+    }
+  }
 }
 
 /** A logger bound to a subsystem scope: `poolLog.info('spawned')`. */

package/src/observable.ts

@@ -1,5 +1,6 @@
 import type { Connector, PathConnector, SharedMemory, SharedSpec, SpecPath } from './contract/sharedMemory';
-import { watch, type SliceOptions } from './reactive';
+import { watchNodes, type SliceOptions } from './reactive';
+import { relabelNode } from './reactiveGraph';
 import { scoped } from './log';
 
 const obsLog = scoped('observe');
@@ -57,7 +58,10 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
   let pendingBind: (() => void) | null = null;
   let rebindUn: (() => void) | null = null;
   let watched: Connector<T> | null = null;
+  /** Devtools graph id of the watch's effect node — relabelled with the subscriber count. */
+  let effectNode: string | null = null;
   const subscribers = new Set<(value: Out | undefined) => void>();
+  const relabel = () => relabelNode(effectNode, `observe(${String(key)}) · ${subscribers.size} sub${subscribers.size === 1 ? '' : 's'}`);
 
   const activate = () => {
     if (unwatch || pendingBind) return;
@@ -67,12 +71,14 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
     } catch {
       // Not bound on this thread yet — activate when it is.
       pendingBind = memory.onBound(() => {
+        const un = pendingBind;
         pendingBind = null;
+        un?.();
         activate();
       });
       return;
     }
-    unwatch = watch(
+    const w = watchNodes(
       connector,
       selectFn as (value: T) => Sel,
       (value) => {
@@ -83,8 +89,12 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
           for (const cb of subscribers) cb(value);
         }
       },
-      options
+      options,
+      { sliced: select !== undefined, label: 'observe' }
     );
+    unwatch = w.stop;
+    effectNode = w.effect;
+    relabel();
     watched = connector;
     // bind() can REBIND this contract to a different buffer — in-process
     // harnesses run every worker's bindSharedMemories in one module graph,
@@ -111,6 +121,7 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
   const deactivate = () => {
     unwatch?.();
     unwatch = null;
+    effectNode = null;
     watched = null;
     pendingBind?.();
     pendingBind = null;
@@ -142,9 +153,11 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
     subscribe(onChange) {
       subscribers.add(onChange);
       activate();
+      relabel();
       return () => {
         subscribers.delete(onChange);
         if (subscribers.size === 0) deactivate();
+        else relabel();
       };
     },
   };

package/src/pool/dedicatedWorker.ts

@@ -0,0 +1,332 @@
+import type { MemoryManager } from './memory';
+import { TaskAbortedError, TaskTimeoutError, WorkerCrashedError } from './errors';
+import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
+import type { MemoryPersistence, TaskContract, TaskMap, TaskResult, WorkerPoolConfig } from '../contract/types';
+import { devtoolsEnabled, emitDevtools, estimateCloneBytes, nextDevtoolsId, type EmittedDevtoolsEvent } from '../devtools';
+import { fmtBytes, scoped } from '../log';
+import { measureTaskCall } from '../userTiming';
+import type { PoolStats, RunOptions } from './workerPool';
+import { forwardWorkerDevtools, sendInit, setupChannelMemory, type ChannelMemory } from './workerChannel';
+import { applyChaos, CHAOS_FAILURE, KILL_MESSAGE, registerDevtoolsRunner, type ChaosConfig } from './devtoolsCommands';
+
+const workerLog = scoped('worker');
+const taskLog = scoped('task');
+
+/**
+ * Config for a single dedicated worker: the WorkerPool config minus the
+ * pool-only knobs (size, per-worker concurrency cap, queue bound, task
+ * methods). Every call posts straight to the worker.
+ */
+export type DedicatedWorkerConfig<S extends SharedSpec = SharedSpec> = Omit<
+  WorkerPoolConfig<S, TaskMap>,
+  'poolSize' | 'concurrency' | 'maxQueue' | 'tasks'
+>;
+
+interface Call {
+  contract: TaskContract<any[], any>;
+  callId: number;
+  sentAt: number;
+  resolve: (v: any) => void;
+  reject: (e: unknown) => void;
+  /** Settled (or orphaned by abort/timeout): a late reply is discarded. */
+  done: boolean;
+  timer?: ReturnType<typeof setTimeout>;
+  signal?: AbortSignal;
+  onSignalAbort?: () => void;
+}
+
+const agg = () => ({
+  count: 0,
+  mean: 0,
+  max: 0,
+  add(v: number) {
+    this.count++;
+    this.mean += (v - this.mean) / this.count;
+    if (v > this.max) this.max = v;
+  },
+});
+
+/**
+ * One worker, no pool: what `connectWorker({ workers: 1 })` (the default)
+ * builds. Calls are posted to the worker immediately, with no queue and no
+ * scheduler; the worker's own message loop runs them in arrival order (a
+ * task that awaits lets the next message start, exactly as in a pool slot
+ * with a raised concurrency cap). Kept from the pool: per-call
+ * timeout/abort, crash respawn, `stats()`, and the same devtools events,
+ * with `pool:init` flagged `dedicated: true`.
+ */
+export class DedicatedWorker<S extends SharedSpec = SharedSpec> {
+  /**
+   * Devtools correlation id: '<name>-w' when the config has a `name`, else
+   * 'worker-N'. The same role a pool's id plays.
+   */
+  readonly poolId: string;
+  readonly sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
+  readonly persistence: MemoryPersistence | undefined;
+  private readonly mem: ChannelMemory<S>;
+  private readonly spawn: () => Worker;
+  private readonly respawn: boolean;
+  private readonly taskTimeout?: number;
+  private readonly label?: string;
+  private worker: Worker | null = null;
+  private pending = new Map<number, Call>();
+  private nextMessageId = 0;
+  private nextCallId = 0;
+  private closed = false;
+  /** Dashboard fault injection (`pool.chaos`); null unless devtools set it. */
+  private chaos: ChaosConfig | null = null;
+  private devtoolsOff?: () => void;
+  private drainWaiters: Array<() => void> = [];
+  private statsAgg = { completed: 0, failed: 0, aborted: 0, runMs: agg() };
+
+  constructor(config: DedicatedWorkerConfig<S>) {
+    this.mem = setupChannelMemory(config, 'DedicatedWorker');
+    if (!config.workerUrl && !config.createWorker) {
+      throw new Error('DedicatedWorker requires either `workerUrl` or `createWorker` in its config.');
+    }
+    const url = config.workerUrl;
+    this.spawn = config.createWorker ?? (() => new Worker(url!, { type: 'module' }));
+    this.respawn = config.respawn ?? true;
+    this.taskTimeout = config.taskTimeout;
+    this.label = config.name;
+    this.poolId = nextDevtoolsId('worker', config.name);
+    this.sharedMemory = this.mem.sharedMemory;
+    this.persistence = this.mem.persistence;
+
+    const bytes = this.mem.sharedMemory?.totalBytes ?? this.mem.injectedBuffer?.byteLength;
+    workerLog.info(
+      bytes !== undefined ? `spawning 1 dedicated worker with ${fmtBytes(bytes)} shared buffer` : 'spawning 1 dedicated worker, message-only',
+    );
+    emitDevtools({
+      type: 'pool:init',
+      poolId: this.poolId,
+      label: this.label,
+      poolSize: 1,
+      concurrency: 0,
+      memoryBytes: bytes,
+      dedicated: true,
+    });
+    this.attach(this.spawn());
+    if (devtoolsEnabled()) {
+      this.devtoolsOff = registerDevtoolsRunner({
+        poolId: this.poolId,
+        label: this.label,
+        dedicated: true,
+        size: () => (this.worker ? 1 : 0),
+        stats: () => this.stats(),
+        kill: (slot) => {
+          if (slot !== 0 || !this.worker) throw new Error(`${this.poolId} has no live worker at slot ${slot}`);
+          this.handleError({ message: KILL_MESSAGE });
+        },
+        getChaos: () => this.chaos,
+        setChaos: (chaos) => { this.chaos = chaos; },
+      });
+    }
+  }
+
+  private attach(worker: Worker): void {
+    this.worker = worker;
+    worker.addEventListener('message', (event: MessageEvent) => {
+      if (this.worker !== worker) return;
+      const data = event.data as TaskResult & { messageId?: number; type?: string; event?: EmittedDevtoolsEvent };
+      if (data.type === 'ATOLL_DEVTOOLS' && data.event) {
+        forwardWorkerDevtools(this.poolId, 0, data.event);
+        return;
+      }
+      this.handleReply(data);
+    });
+    worker.addEventListener('error', (event: unknown) => {
+      if (this.worker === worker) this.handleError(event);
+    });
+    const init = sendInit(worker, this.mem);
+    workerLog.debug(`dedicated worker spawned, ${init} sent`);
+    emitDevtools({ type: 'worker:spawn', poolId: this.poolId, slot: 0 });
+  }
+
+  private detach(call: Call): void {
+    if (call.timer) clearTimeout(call.timer);
+    if (call.signal && call.onSignalAbort) call.signal.removeEventListener('abort', call.onSignalAbort);
+  }
+
+  private handleReply(data: TaskResult & { messageId?: number }): void {
+    const call = data.messageId !== undefined ? this.pending.get(data.messageId) : undefined;
+    if (!call) return;
+    this.pending.delete(data.messageId!);
+    this.detach(call);
+    if (!call.done) {
+      call.done = true;
+      const runMs = performance.now() - call.sentAt;
+      this.statsAgg.runMs.add(runMs);
+      if (data.success) {
+        this.statsAgg.completed++;
+        taskLog.debug(`← ${call.contract.taskId} ok`);
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: call.callId, taskId: call.contract.taskId, outcome: 'ok', runMs, resultBytes: estimateCloneBytes(data.result) });
+          measureTaskCall(this.poolId, call.contract.taskId, call.callId, 0, call.sentAt, call.sentAt + runMs, true);
+        }
+        call.resolve(data.result);
+      } else {
+        this.statsAgg.failed++;
+        taskLog.warn(`← ${call.contract.taskId} failed: ${data.error}`);
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: call.callId, taskId: call.contract.taskId, outcome: 'error', runMs, error: data.error });
+          measureTaskCall(this.poolId, call.contract.taskId, call.callId, 0, call.sentAt, call.sentAt + runMs, false);
+        }
+        call.reject(new Error(data.error));
+      }
+    }
+    this.checkDrained();
+  }
+
+  private handleError(event: unknown): void {
+    if (this.closed) return;
+    const e = event as { message?: string; error?: Error } | undefined;
+    const message = e?.message ?? (e?.error ? String(e.error) : 'worker error');
+    workerLog.warn(`worker error: ${message}`);
+    emitDevtools({ type: 'worker:error', poolId: this.poolId, slot: 0, message });
+    this.rejectPending(message);
+    this.worker?.terminate();
+    this.worker = null;
+    if (this.respawn) {
+      workerLog.info('respawning crashed worker');
+      this.attach(this.spawn());
+      emitDevtools({ type: 'worker:respawn', poolId: this.poolId, slot: 0 });
+    }
+    this.checkDrained();
+  }
+
+  private rejectPending(message: string): void {
+    const err = new WorkerCrashedError(message);
+    for (const call of this.pending.values()) {
+      this.detach(call);
+      if (call.done) continue;
+      call.done = true;
+      this.statsAgg.failed++;
+      emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: call.callId, taskId: call.contract.taskId, outcome: 'crashed', error: message });
+      call.reject(err);
+    }
+    this.pending.clear();
+  }
+
+  /** Abort/timeout: the caller rejects now; the worker's eventual reply is discarded. */
+  private cancel(call: Call, err: Error): void {
+    if (call.done) return;
+    call.done = true;
+    this.detach(call);
+    this.statsAgg.aborted++;
+    emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: call.callId, taskId: call.contract.taskId, outcome: err instanceof TaskTimeoutError ? 'timeout' : 'aborted' });
+    call.reject(err);
+  }
+
+  private checkDrained(): void {
+    if (this.pending.size > 0) return;
+    for (const w of this.drainWaiters.splice(0)) w();
+  }
+
+  /** Post the call straight to the worker — no queue, no scheduler. */
+  public dispatch<Args extends any[], Result>(
+    contract: TaskContract<Args, Result>,
+    args: Args,
+    options?: RunOptions,
+  ): Promise<Result> {
+    const worker = this.worker;
+    if (this.closed || worker === null) {
+      return Promise.reject(new WorkerCrashedError('DedicatedWorker has been terminated — no worker available.'));
+    }
+    if (options?.signal?.aborted) return Promise.reject(new TaskAbortedError());
+    return new Promise<Result>((resolve, reject) => {
+      const call: Call = {
+        contract,
+        callId: ++this.nextCallId,
+        sentAt: performance.now(),
+        resolve,
+        reject,
+        done: false,
+        signal: options?.signal,
+      };
+      if (options?.signal) {
+        call.onSignalAbort = () => this.cancel(call, new TaskAbortedError());
+        options.signal.addEventListener('abort', call.onSignalAbort, { once: true });
+      }
+      const timeout = options?.timeout ?? this.taskTimeout;
+      if (timeout !== undefined) call.timer = setTimeout(() => this.cancel(call, new TaskTimeoutError()), timeout);
+
+      const messageId = this.nextMessageId++;
+      this.pending.set(messageId, call);
+      taskLog.debug(`→ ${contract.taskId}`, { args });
+      emitDevtools({ type: 'task:enqueue', poolId: this.poolId, callId: call.callId, taskId: contract.taskId });
+      if (devtoolsEnabled()) {
+        emitDevtools({ type: 'task:dispatch', poolId: this.poolId, callId: call.callId, taskId: contract.taskId, slot: 0, waitMs: 0, argBytes: estimateCloneBytes(args) });
+      }
+      const msg = { type: 'EXECUTE_TASK', messageId, taskId: contract.taskId, args };
+      if (this.chaos) {
+        applyChaos(this.chaos, {
+          live: () => this.pending.get(messageId) === call,
+          fail: () => this.handleReply({ messageId, taskId: contract.taskId, success: false, error: CHAOS_FAILURE }),
+          timeout: () => this.cancel(call, new TaskTimeoutError()),
+          post: () => worker.postMessage(msg),
+        });
+      } else {
+        worker.postMessage(msg);
+      }
+    });
+  }
+
+  public runTask<Args extends any[], Result>(contract: TaskContract<Args, Result>, ...args: Args): Promise<Result> {
+    return this.dispatch(contract, args);
+  }
+
+  /** The shared buffer handed to the worker via INIT_MEMORY; undefined when message-only. */
+  public get sharedBuffer(): SharedArrayBuffer | undefined {
+    return (this.mem.memoryManager as MemoryManager | undefined)?.getBuffer() ?? this.mem.injectedBuffer;
+  }
+
+  /** The worker, as a one-element snapshot (same shape as `WorkerPool.workers`). */
+  public get workers(): readonly Worker[] {
+    return this.worker ? [this.worker] : [];
+  }
+
+  /** Same shape as `WorkerPool.stats()`; `queued` and `waitMs` stay zero (there is no queue). */
+  public stats(): PoolStats {
+    const live = this.worker ? 1 : 0;
+    const { runMs } = this.statsAgg;
+    return {
+      workers: live,
+      idle: live && this.pending.size === 0 ? 1 : 0,
+      inFlight: this.pending.size,
+      queued: 0,
+      completed: this.statsAgg.completed,
+      failed: this.statsAgg.failed,
+      aborted: this.statsAgg.aborted,
+      waitMs: { count: 0, mean: 0, max: 0 },
+      runMs: { count: runMs.count, mean: runMs.mean, max: runMs.max },
+    };
+  }
+
+  /** Resolves once nothing is in flight, then terminates. */
+  public close(): Promise<void> {
+    if (this.pending.size === 0) {
+      this.terminate();
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.drainWaiters.push(() => {
+        this.terminate();
+        resolve();
+      });
+    });
+  }
+
+  public terminate(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.devtoolsOff?.();
+    void this.persistence?.stop()?.catch?.((e: unknown) => workerLog.warn('memory persistence stop failed', e));
+    workerLog.info('terminating dedicated worker');
+    emitDevtools({ type: 'pool:terminate', poolId: this.poolId });
+    this.rejectPending('worker terminated');
+    this.worker?.terminate();
+    this.worker = null;
+    this.checkDrained();
+  }
+}

package/src/pool/devtoolsCommands.ts

@@ -0,0 +1,165 @@
+/**
+ * Dashboard control over the live runners of this thread: `pool.list`,
+ * `pool.stats`, `worker.kill`, `pool.chaos`. Runners (`WorkerPool`,
+ * `DedicatedWorker`) register here from their constructor only when
+ * `devtoolsEnabled()`, and unregister on terminate — with devtools off
+ * nothing is registered and the runners' only cost is one `chaos` field
+ * check per dispatch.
+ *
+ * Scope: one registry per thread. Pools spawned inside workers (sub-pools,
+ * nested island clients) register in the worker's own registry, which the
+ * dashboard's control channel (main thread only) cannot reach.
+ */
+import { registerDevtoolsCommand } from '../devtools';
+import type { PoolStats } from './workerPool';
+
+/** Fault injection applied at dispatch. All rates are probabilities in 0..1. */
+export interface ChaosConfig {
+  /** Delay before the call is posted to the worker. */
+  delayMs?: number;
+  /** Share of calls rejected with `CHAOS_FAILURE` (settle outcome 'error'). */
+  failRate?: number;
+  /** Share of calls failed through the timeout path (settle outcome 'timeout'). */
+  timeoutRate?: number;
+}
+
+/** Error message of a chaos-injected failure. */
+export const CHAOS_FAILURE = 'chaos: injected failure';
+/** Crash message of a dashboard `worker.kill`. */
+export const KILL_MESSAGE = 'killed from devtools';
+
+/** What a runner exposes to the dashboard commands. */
+export interface DevtoolsRunnerHandle {
+  poolId: string;
+  label?: string;
+  dedicated: boolean;
+  /** Live worker count. */
+  size(): number;
+  stats(): PoolStats;
+  /** Run the runner's real crash handler for that slot (throws on a bad slot). */
+  kill(slot: number): void;
+  getChaos(): ChaosConfig | null;
+  setChaos(chaos: ChaosConfig | null): void;
+}
+
+const runners = new Map<string, DevtoolsRunnerHandle>();
+let uninstall: (() => void) | null = null;
+
+const runnerOf = (args: Record<string, unknown>): DevtoolsRunnerHandle => {
+  const id = args.poolId;
+  if (typeof id !== 'string') throw new Error('poolId (string) is required');
+  const r = runners.get(id);
+  if (!r) {
+    throw new Error(
+      id.includes('~')
+        ? `runner '${id}' lives inside a worker: nested pools are not controllable from the dashboard`
+        : `no live runner '${id}' on this thread`,
+    );
+  }
+  return r;
+};
+
+const rate = (v: unknown, name: string): number | undefined => {
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > 1) {
+    throw new Error(`${name} must be a number in 0..1`);
+  }
+  return v || undefined;
+};
+
+/** Validate `pool.chaos` args into a config; null when nothing is active (clears). */
+export const parseChaos = (args: Record<string, unknown>): ChaosConfig | null => {
+  const { delayMs } = args;
+  if (delayMs !== undefined && delayMs !== null && (typeof delayMs !== 'number' || !Number.isFinite(delayMs) || delayMs < 0)) {
+    throw new Error('delayMs must be a non-negative number');
+  }
+  const failRate = rate(args.failRate, 'failRate');
+  const timeoutRate = rate(args.timeoutRate, 'timeoutRate');
+  if ((failRate ?? 0) + (timeoutRate ?? 0) > 1) throw new Error('failRate + timeoutRate must not exceed 1');
+  const chaos: ChaosConfig = {};
+  if (delayMs) chaos.delayMs = delayMs as number;
+  if (failRate) chaos.failRate = failRate;
+  if (timeoutRate) chaos.timeoutRate = timeoutRate;
+  return Object.keys(chaos).length ? chaos : null;
+};
+
+const listRunners = () =>
+  [...runners.values()].map((r) => ({
+    poolId: r.poolId,
+    label: r.label ?? r.poolId,
+    size: r.size(),
+    dedicated: r.dedicated,
+    chaos: r.getChaos(),
+  }));
+
+const install = (): (() => void) => {
+  const offs = [
+    registerDevtoolsCommand('pool.list', () => listRunners()),
+    registerDevtoolsCommand('pool.stats', (args) => runnerOf(args).stats()),
+    registerDevtoolsCommand('worker.kill', (args) => {
+      const r = runnerOf(args);
+      const slot = args.slot ?? 0;
+      if (typeof slot !== 'number' || !Number.isInteger(slot) || slot < 0) {
+        throw new Error('slot must be a non-negative integer');
+      }
+      r.kill(slot);
+      return { poolId: r.poolId, slot, killed: true };
+    }),
+    registerDevtoolsCommand('pool.chaos', (args) => {
+      const r = runnerOf(args);
+      r.setChaos(parseChaos(args));
+      return r.getChaos();
+    }),
+  ];
+  return () => offs.forEach((off) => off());
+};
+
+/**
+ * Register a live runner; returns its unregister. The pool commands are
+ * installed with the first runner and removed with the last, so the
+ * dashboard's `devtools.commands` only advertises them while there is
+ * something to control.
+ */
+export const registerDevtoolsRunner = (handle: DevtoolsRunnerHandle): (() => void) => {
+  runners.set(handle.poolId, handle);
+  uninstall ??= install();
+  return () => {
+    if (runners.get(handle.poolId) !== handle) return;
+    runners.delete(handle.poolId);
+    if (runners.size === 0 && uninstall) {
+      uninstall();
+      uninstall = null;
+    }
+  };
+};
+
+/** Hooks a runner supplies to `applyChaos` for one dispatched call. */
+export interface ChaosCall {
+  /** Still awaiting its reply (not crashed/terminated away during the delay). */
+  live(): boolean;
+  /** Settle as a worker-reported failure (the runner's reply path). */
+  fail(): void;
+  /** Settle through the runner's timeout path. */
+  timeout(): void;
+  /** Post the call to the worker. */
+  post(): void;
+}
+
+/**
+ * Apply an active chaos config to one dispatched call. An injected failure
+ * never reaches the worker; an injected timeout settles the caller through
+ * the timeout path and still posts the call, exactly like a real timeout
+ * (the worker runs it; its late reply frees the slot and is discarded).
+ */
+export const applyChaos = (chaos: ChaosConfig, call: ChaosCall): void => {
+  const r = Math.random();
+  const fail = r < (chaos.failRate ?? 0);
+  const timeout = !fail && r < (chaos.failRate ?? 0) + (chaos.timeoutRate ?? 0);
+  if (!chaos.delayMs && !fail && !timeout) return call.post();
+  setTimeout(() => {
+    if (!call.live()) return;
+    if (fail) return call.fail();
+    if (timeout) call.timeout();
+    call.post();
+  }, chaos.delayMs ?? 0);
+};