@atolljs/core 0.1.6 → 0.1.8

package/src/pool/subWorkerClient.ts

@@ -0,0 +1,70 @@
+import type { SharedSpec } from '../contract/sharedMemory';
+import type { WorkerDefinition } from '../worker/defineWorker';
+import { connectWorker, type ConnectWorkerConfig, type WorkerClient } from './workerClient';
+
+/**
+ * Worker-shell side of a nested pool: identical options to
+ * {@link ConnectWorkerConfig}, since the pool protocol (INIT / INIT_MEMORY /
+ * EXECUTE_TASK) doesn't care which side of the thread boundary spawned the
+ * workers. The distinguishing knob is `sharedBuffer` — inside a worker
+ * shell, a bound contract's `.buffer` (or the shell pool's `sharedBuffer`)
+ * lets sub-workers attach to the SAME shared memory instead of a fresh one.
+ */
+export interface ConnectSubWorkerConfig<S extends SharedSpec> extends ConnectWorkerConfig<S> {}
+
+/**
+ * Spawn a worker pool from INSIDE a worker — the worker-shell counterpart
+ * of {@link connectWorker}. The sub-worker entry is a normal `defineWorker`
+ * module; only the spawn site differs:
+ *
+ *   // shell.worker.ts — runs inside a dedicated worker
+ *   const sub = connectSubWorker<SubWorker>({
+ *     worker: () => new Worker(new URL('./sub.worker.ts', import.meta.url), { type: 'module' }),
+ *     sharedMemory: memory,                    // fresh buffer per sub-pool
+ *     // — or attach sub-workers to THIS worker's bound buffer:
+ *     // sharedBuffer: memory.buffer,
+ *     workers: 2,
+ *   });
+ *
+ *   methods: { fanOut: (chunks) => Promise.all(chunks.map((c) => sub.crunch(c))) }
+ *
+ * Memory modes (both supported, pick per config):
+ *  - `sharedMemory` without `sharedBuffer`: the sub-pool allocates its own
+ *    WebAssembly.Memory inside the worker and binds the contract to it —
+ *    a private buffer for this tier.
+ *  - `sharedBuffer: someContract.buffer`: no allocation — every sub-worker
+ *    binds the shell's existing buffer, so all three tiers (main, shell,
+ *    sub) read and write the same fields. Hub-and-spoke sharing.
+ *
+ * Nested workers need `new Worker` inside a worker context: Chrome and
+ * Firefox support it, Safari does not — feature-detect and fall back to
+ * dispatching on the main-thread pool. Node's `worker_threads` nests
+ * natively; use `worker: () => createNodeWorker(new Worker('./sub.js'))`
+ * (a sub-worker entry still needs `@atolljs/node/shim` first).
+ *
+ * Bundlers detect `new Worker(new URL(...))` inside a worker bundle too:
+ * the @atolljs/vite dev plugin rewrites nested entry URLs back onto its
+ * `?worker_file` bundling path, and `vite build` emits nested worker
+ * chunks. The same rules as the main thread apply — the URL must stay an
+ * inline literal, never hoisted or computed.
+ */
+export function connectSubWorker<
+  W extends WorkerDefinition,
+  S extends SharedSpec = W extends WorkerDefinition<infer X> ? X : SharedSpec,
+>(config: ConnectSubWorkerConfig<S>): WorkerClient<W, S> {
+  const guarded: ConnectSubWorkerConfig<S> = { ...config };
+  if (typeof config.worker !== 'function') {
+    // A URL config means we call `new Worker` ourselves — surface a clear
+    // error on engines without nested workers instead of a bare
+    // ReferenceError at spawn time.
+    guarded.worker = () => {
+      if (typeof Worker === 'undefined') {
+        throw new Error(
+          'connectSubWorker: no `Worker` global in this context — nested dedicated workers are unsupported here (e.g. Safari). Feature-detect and fall back to a main-thread pool.',
+        );
+      }
+      return new Worker(config.worker as URL, { type: 'module' });
+    };
+  }
+  return connectWorker<W, S>(guarded);
+}

package/src/pool/workerChannel.ts

@@ -0,0 +1,99 @@
+/**
+ * The per-worker plumbing both runners share: `WorkerPool` (N workers,
+ * queue + least-busy scheduling) and `DedicatedWorker` (one worker, no
+ * pool). Memory setup, the INIT handshake, and devtools forwarding are the
+ * same protocol whichever runner owns the worker.
+ */
+import { MemoryManager } from './memory';
+import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
+import type { MemoryPersistence, TaskMap, WorkerPoolConfig } from '../contract/types';
+import { devtoolsEnabled, forwardDevtools, type EmittedDevtoolsEvent } from '../devtools';
+
+export interface ChannelMemory<S extends SharedSpec> {
+  sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
+  memoryManager?: MemoryManager;
+  /** A caller-supplied buffer shipped via INIT_MEMORY (sub-worker / second-runner sharing). */
+  injectedBuffer?: SharedArrayBuffer;
+  persistence: MemoryPersistence | undefined;
+}
+
+/**
+ * Resolve the runner's memory once, at construction: a caller-supplied
+ * buffer binds the contract to those bytes, otherwise a fresh
+ * WebAssembly.Memory is allocated. Message-only runners get neither.
+ */
+export function setupChannelMemory<S extends SharedSpec>(
+  config: WorkerPoolConfig<S, TaskMap>,
+  owner: string,
+): ChannelMemory<S> {
+  if (config.sharedMemory || config.sharedBuffer !== undefined) {
+    if (typeof SharedArrayBuffer === 'undefined' || (typeof crossOriginIsolated !== 'undefined' && !crossOriginIsolated)) {
+      throw new Error(
+        `${owner} requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.`
+      );
+    }
+  }
+  let injectedBuffer: SharedArrayBuffer | undefined;
+  if (config.sharedBuffer !== undefined) {
+    injectedBuffer = typeof config.sharedBuffer === 'function' ? config.sharedBuffer() : config.sharedBuffer;
+    if (!injectedBuffer) {
+      throw new Error(
+        `${owner}: \`sharedBuffer\` resolved to an empty buffer — the producing pool or contract has no bound memory yet.`
+      );
+    }
+  }
+  if (!config.sharedMemory) return { sharedMemory: undefined, injectedBuffer, persistence: undefined };
+
+  const sharedMemory = config.sharedMemory;
+  let memoryManager: MemoryManager | undefined;
+  if (injectedBuffer) {
+    sharedMemory.bind(injectedBuffer);
+  } else {
+    memoryManager = new MemoryManager(config.memory);
+    memoryManager.ensureCapacity(sharedMemory.totalBytes);
+    sharedMemory.bind(memoryManager.getBuffer());
+  }
+  return { sharedMemory, memoryManager, injectedBuffer, persistence: config.persistence?.(sharedMemory) };
+}
+
+/**
+ * The INIT handshake: INIT_MEMORY with the runner's memory (or the injected
+ * buffer), bare INIT for message-only runners. `devtools` tells the worker
+ * to forward its instrumentation back only when a sink is live at spawn.
+ */
+export function sendInit<S extends SharedSpec>(worker: Worker, mem: ChannelMemory<S>): 'INIT' | 'INIT_MEMORY' {
+  if (mem.memoryManager) {
+    worker.postMessage({ type: 'INIT_MEMORY', memory: mem.memoryManager.memory, devtools: devtoolsEnabled() });
+    return 'INIT_MEMORY';
+  }
+  if (mem.injectedBuffer) {
+    worker.postMessage({ type: 'INIT_MEMORY', buffer: mem.injectedBuffer, devtools: devtoolsEnabled() });
+    return 'INIT_MEMORY';
+  }
+  worker.postMessage({ type: 'INIT', devtools: devtoolsEnabled() });
+  return 'INIT';
+}
+
+/**
+ * Re-emit a worker-forwarded devtools event into this thread's sink.
+ *
+ * A runner constructed inside a worker mints ids ('pool-1', 'worker-1') on
+ * that context's own counters, which collide textually with ids minted on
+ * the parent thread. Every id arriving from a worker refers to the worker's
+ * local id space, so it is qualified unconditionally as
+ * `${runnerId}#${slot}~${id}`: the id then encodes the spawn path and
+ * dashboards can draw parent→child edges. Existing `worker` stamps
+ * (multi-hop forwarding) are qualified the same way so attribution stays
+ * pinned to the deepest emitting worker.
+ */
+export function forwardWorkerDevtools(runnerId: string, slot: number, ev: EmittedDevtoolsEvent & { poolId?: string }): void {
+  const qualify = (id: string): string => `${runnerId}#${slot}~${id}`;
+  forwardDevtools({
+    ...ev,
+    ...(ev.poolId !== undefined ? { poolId: qualify(ev.poolId) } : {}),
+    worker:
+      ev.worker === undefined
+        ? { poolId: runnerId, slot }
+        : { poolId: qualify(ev.worker.poolId), slot: ev.worker.slot },
+  });
+}

package/src/pool/workerClient.ts

@@ -2,6 +2,7 @@ import type { ServiceMethod, TaskRunner } from '../service';
 import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
 import type { MemoryConfig, Prettify } from '../contract/types';
 import { WorkerPool, type RunOptions } from './workerPool';
+import { DedicatedWorker } from './dedicatedWorker';
 import type {
   WorkerDefinition,
   WorkerMethodMap,
@@ -92,16 +93,33 @@ export function workerClient<W extends WorkerDefinition>(
 export interface ConnectWorkerConfig<S extends SharedSpec> {
   /** Omit for a message-only pool — the SharedArrayBuffer check is skipped. */
   sharedMemory?: SharedMemory<S> & Prettify<SharedAccess<S>>;
+  /**
+   * Ship an existing SharedArrayBuffer to every worker instead of
+   * allocating one — e.g. `sharedBuffer: anotherPool.sharedBuffer`, or a
+   * bound contract's `contract.buffer` inside a worker shell. A thunk is
+   * resolved once at pool construction.
+   */
+  sharedBuffer?: SharedArrayBuffer | (() => SharedArrayBuffer | undefined);
   /**
    * Bundler-detectable factory `() => new Worker(new URL('./x.worker.ts', import.meta.url), { type: 'module' })`,
    * or a URL.
    */
   worker: (() => Worker) | URL;
+  /**
+   * How many workers this client needs. `1` (the default) is a single
+   * dedicated worker with no pool: calls post straight to it, no queue or
+   * scheduler. `N > 1` builds a pool that spreads separate calls across N
+   * workers; `'auto'` sizes it to `navigator.hardwareConcurrency ?? 4`.
+   */
+  workers?: number | 'auto';
+  /** @deprecated Use `workers`. Read only when `workers` is absent. */
   poolSize?: number | 'auto';
+  /** Display label for devtools/dashboards — falls back to a generated id. */
+  name?: string;
   memory?: MemoryConfig;
-  /** Max in-flight tasks per worker (default 1); excess calls queue FIFO. */
+  /** Pool only: max in-flight tasks per worker (default 1); excess calls queue FIFO. */
   concurrency?: number;
-  /** Max queued calls (default Infinity); a full queue rejects with PoolQueueFullError. */
+  /** Pool only: max queued calls (default Infinity); a full queue rejects with PoolQueueFullError. */
   maxQueue?: number;
   /** Default true — a crashed worker is replaced and its in-flight calls reject. */
   respawn?: boolean;
@@ -111,13 +129,29 @@ export interface ConnectWorkerConfig<S extends SharedSpec> {
   lazy?: boolean;
 }
 
-/** A typed worker client plus pool lifecycle controls. */
+/** What a client runs on: a pool (`workers > 1`) or one dedicated worker. */
+export type WorkerRunner<S extends SharedSpec = SharedSpec> = WorkerPool<S> | DedicatedWorker<S>;
+
+/** Resolve a `workers` count: `'auto'` is one per core (4 when unknown). */
+export const resolveWorkerCount = (n: number | 'auto' | undefined): number =>
+  n === 'auto'
+    ? typeof navigator !== 'undefined'
+      ? (navigator.hardwareConcurrency ?? 4)
+      : 4
+    : Math.max(1, Math.floor(n ?? 1));
+
+/** A typed worker client plus lifecycle controls. */
 export type WorkerClient<W extends WorkerDefinition, S extends SharedSpec> = WorkerMethods<W> & {
-  /** Spawn the pool now (idempotent). */
+  /** Spawn the worker(s) now (idempotent). */
   start(): void;
-  /** Terminate the pool; the next method call re-spawns it. */
+  /** Terminate the worker(s); the next method call re-spawns. */
   terminate(): void;
-  readonly pool: WorkerPool<S> | null;
+  /**
+   * The runner once spawned: a `DedicatedWorker` for `workers: 1`, a
+   * `WorkerPool` otherwise. Both expose `stats()`, `close()`, `terminate()`,
+   * `workers`, `sharedBuffer` and `poolId`.
+   */
+  readonly pool: WorkerRunner<S> | null;
   readonly sharedMemory: ConnectWorkerConfig<S>['sharedMemory'] | undefined;
 };
 
@@ -130,12 +164,15 @@ export type WorkerClient<W extends WorkerDefinition, S extends SharedSpec> = Wor
  *   export const incidents = connectWorker<IncidentsWorker>({
  *     sharedMemory: incidentsMemory,
  *     worker: () => new Worker(new URL('./worker/incidents.worker.ts', import.meta.url), { type: 'module' }),
- *     poolSize: 1,
+ *     workers: 3,                         // omit for one dedicated worker
  *   });
  *
- *   await incidents.queryIncidents(q);   // typed dispatch to the pool
+ *   await incidents.queryIncidents(q);   // typed dispatch
  *   incidents.terminate();               // next call lazily re-spawns
  *
+ * `workers` states what the work needs and the client picks the runner:
+ * 1 (default) → a `DedicatedWorker`, no pool; more → a `WorkerPool`.
+ *
  * Lazy by default: no Worker is touched until the first method call (or
  * `start()`), so importing the client is SSR-safe.
  */
@@ -143,21 +180,33 @@ export function connectWorker<
   W extends WorkerDefinition,
   S extends SharedSpec = W extends WorkerDefinition<infer X> ? X : SharedSpec,
 >(config: ConnectWorkerConfig<S>): WorkerClient<W, S> {
-  let pool: WorkerPool<S> | null = null;
-  const spawn = (): WorkerPool<S> =>
-    (pool ??= new WorkerPool<S>({
+  let pool: WorkerRunner<S> | null = null;
+  const spawn = (): WorkerRunner<S> => {
+    if (pool) return pool;
+    const count = resolveWorkerCount(config.workers ?? config.poolSize);
+    const base = {
       sharedMemory: config.sharedMemory,
+      sharedBuffer: config.sharedBuffer,
       createWorker:
         typeof config.worker === 'function'
           ? config.worker
           : () => new Worker(config.worker as URL, { type: 'module' }),
-      poolSize: config.poolSize,
+      name: config.name,
       memory: config.memory,
-      concurrency: config.concurrency,
-      maxQueue: config.maxQueue,
       respawn: config.respawn,
       taskTimeout: config.taskTimeout,
-    }));
+    };
+    pool =
+      count === 1
+        ? new DedicatedWorker<S>(base)
+        : new WorkerPool<S>({
+            ...base,
+            poolSize: count,
+            concurrency: config.concurrency,
+            maxQueue: config.maxQueue,
+          });
+    return pool;
+  };
 
   if (config.lazy === false) spawn();
 

package/src/pool/workerPool.ts

@@ -1,8 +1,12 @@
-import { MemoryManager } from './memory';
+import type { MemoryManager } from './memory';
 import { PoolQueueFullError, TaskAbortedError, TaskTimeoutError, WorkerCrashedError } from './errors';
 import { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
 import { MemoryPersistence, PoolTasks, TaskContract, TaskMap, TaskResult, WorkerPoolConfig } from '../contract/types';
+import { devtoolsEnabled, emitDevtools, estimateCloneBytes, nextDevtoolsId, type EmittedDevtoolsEvent } from '../devtools';
+import { measureTaskCall } from '../userTiming';
+import { forwardWorkerDevtools, sendInit, setupChannelMemory, type ChannelMemory } from './workerChannel';
 import { fmtBytes, scoped } from '../log';
+import { applyChaos, CHAOS_FAILURE, KILL_MESSAGE, registerDevtoolsRunner, type ChaosConfig } from './devtoolsCommands';
 
 const poolLog = scoped('pool');
 const taskLog = scoped('task');
@@ -59,6 +63,8 @@ export interface PoolStats {
 interface TaskEntry {
   contract: TaskContract<any[], any>;
   args: any[];
+  /** Per-pool sequence — correlates a call's devtools events across its lifecycle. */
+  callId: number;
   enqueuedAt: number;
   resolve: (v: any) => void;
   reject: (e: unknown) => void;
@@ -83,7 +89,10 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
   private pending = new Map<number, TaskEntry>();
   private nextMessageId = 0;
   private queue: TaskEntry[] = [];
+  private readonly mem: ChannelMemory<S>;
   private memoryManager?: MemoryManager;
+  /** A caller-supplied buffer shipped via INIT_MEMORY (sub-worker / second-pool sharing). */
+  private injectedBuffer?: SharedArrayBuffer;
   private workerUrl?: URL;
   private spawn: () => Worker;
   private readonly concurrency: number;
@@ -91,6 +100,9 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
   private readonly respawn: boolean;
   private readonly taskTimeout?: number;
   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,
@@ -100,18 +112,19 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     waitMs: agg(),
     runMs: agg(),
   };
+  /**
+   * Devtools correlation id, stamped on every event this pool emits:
+   * '<name>-p' when the config has a `name`, else 'pool-N'.
+   */
+  readonly poolId: string;
+  private readonly label?: string;
+  private nextCallId = 0;
   public readonly sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
   /** The attached memory-persistence adapter, if the config supplied one. */
   public readonly persistence: MemoryPersistence | undefined;
 
   constructor(config: WorkerPoolConfig<S, TaskMap>) {
-    if (config.sharedMemory) {
-      if (typeof SharedArrayBuffer === 'undefined' || (typeof crossOriginIsolated !== 'undefined' && !crossOriginIsolated)) {
-        throw new Error(
-          'WorkerPool requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.'
-        );
-      }
-    }
+    const mem = setupChannelMemory(config, 'WorkerPool');
     if (!config.workerUrl && !config.createWorker) {
       throw new Error('WorkerPool requires either `workerUrl` or `createWorker` in its config.');
     }
@@ -121,30 +134,58 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     this.maxQueue = config.maxQueue ?? Infinity;
     this.respawn = config.respawn ?? true;
     this.taskTimeout = config.taskTimeout;
-
-    if (config.sharedMemory) {
-      this.sharedMemory = config.sharedMemory;
-      this.memoryManager = new MemoryManager(config.memory);
-      this.memoryManager.ensureCapacity(this.sharedMemory.totalBytes);
-      this.sharedMemory.bind(this.memoryManager.getBuffer());
-      this.persistence = config.persistence?.(config.sharedMemory);
-    }
+    this.label = config.name;
+    this.poolId = nextDevtoolsId('pool', config.name);
+    this.mem = mem;
+    this.sharedMemory = mem.sharedMemory;
+    this.memoryManager = mem.memoryManager;
+    this.injectedBuffer = mem.injectedBuffer;
+    this.persistence = mem.persistence;
 
     const requestedSize = config.poolSize ?? 'auto';
     const poolSize =
-      requestedSize === 'auto' ? (navigator.hardwareConcurrency ?? 4) : requestedSize;
+      requestedSize === 'auto'
+        ? (typeof navigator !== 'undefined' ? navigator.hardwareConcurrency ?? 4 : 4)
+        : requestedSize;
 
     poolLog.info(
       this.sharedMemory
         ? `spawning ${poolSize} worker(s) with ${fmtBytes(this.sharedMemory.totalBytes)} shared buffer`
-        : `spawning ${poolSize} worker(s), message-only`,
+        : this.injectedBuffer
+          ? `spawning ${poolSize} worker(s) with ${fmtBytes(this.injectedBuffer.byteLength)} inherited buffer`
+          : `spawning ${poolSize} worker(s), message-only`,
       { workerUrl: config.workerUrl ? String(config.workerUrl) : 'createWorker()' },
     );
     poolLog.debug(`tip: setLogLevel('trace') for per-task detail`);
 
+    emitDevtools({
+      type: 'pool:init',
+      poolId: this.poolId,
+      label: this.label,
+      poolSize,
+      concurrency: this.concurrency,
+      memoryBytes: this.sharedMemory?.totalBytes ?? this.injectedBuffer?.byteLength,
+    });
+
     for (let i = 0; i < poolSize; i++) {
       this.addWorker(this.spawn());
     }
+    if (devtoolsEnabled()) {
+      this.devtoolsOff = registerDevtoolsRunner({
+        poolId: this.poolId,
+        label: this.label,
+        dedicated: false,
+        size: () => this.slots.length,
+        stats: () => this.stats(),
+        kill: (slot) => {
+          const s = this.slots[slot];
+          if (!s) throw new Error(`${this.poolId} has no worker slot ${slot}`);
+          this.handleWorkerError(s, { message: KILL_MESSAGE });
+        },
+        getChaos: () => this.chaos,
+        setChaos: (chaos) => { this.chaos = chaos; },
+      });
+    }
 
     // Install first-class task methods: pool.queryIncidents(q) →
     // runTask(QueryIncidents, q). Typed through PoolTasks<T> at the
@@ -167,18 +208,24 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
   private addWorker(worker: Worker): WorkerSlot {
     const slot: WorkerSlot = { worker, inFlight: 0 };
     worker.addEventListener('message', (event: MessageEvent) => {
-      this.handleReply(slot, event.data as TaskResult & { messageId?: number });
+      const data = event.data as TaskResult & { messageId?: number; type?: string; event?: EmittedDevtoolsEvent };
+      // Worker-side instrumentation forwarded on the task channel — re-emit
+      // into the local sink so one sink sees the whole app. Stamp which
+      // slot produced it so worker-side fetches/heap/memory writes
+      // attribute to a specific worker.
+      if (data.type === 'ATOLL_DEVTOOLS' && data.event) {
+        forwardWorkerDevtools(this.poolId, this.slots.indexOf(slot), data.event);
+        return;
+      }
+      this.handleReply(slot, data);
     });
     worker.addEventListener('error', (event: unknown) => {
       this.handleWorkerError(slot, event);
     });
-    if (this.memoryManager) {
-      worker.postMessage({ type: 'INIT_MEMORY', memory: this.memoryManager.memory });
-    } else {
-      worker.postMessage({ type: 'INIT' });
-    }
+    const init = sendInit(worker, this.mem);
     this.slots.push(slot);
-    poolLog.debug(`worker spawned, ${this.memoryManager ? 'INIT_MEMORY' : 'INIT'} sent`);
+    poolLog.debug(`worker spawned, ${init} sent`);
+    emitDevtools({ type: 'worker:spawn', poolId: this.poolId, slot: this.slots.indexOf(slot) });
     return slot;
   }
 
@@ -192,14 +239,24 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     // stats and settlement — the caller was already rejected.
     if (!entry.done) {
       entry.done = true;
-      this.statsAgg.runMs.add(performance.now() - (entry.sentAt ?? entry.enqueuedAt));
+      const start = entry.sentAt ?? entry.enqueuedAt;
+      const runMs = performance.now() - start;
+      this.statsAgg.runMs.add(runMs);
       if (data.success) {
         this.statsAgg.completed++;
         taskLog.debug(`← ${entry.contract.taskId} ok`);
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'ok', runMs, resultBytes: estimateCloneBytes(data.result) });
+          measureTaskCall(this.poolId, entry.contract.taskId, entry.callId, this.slots.indexOf(slot), start, start + runMs, true);
+        }
         entry.resolve(data.result);
       } else {
         this.statsAgg.failed++;
         taskLog.warn(`← ${entry.contract.taskId} failed: ${data.error}`);
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'error', runMs, error: data.error });
+          measureTaskCall(this.poolId, entry.contract.taskId, entry.callId, this.slots.indexOf(slot), start, start + runMs, false);
+        }
         entry.reject(new Error(data.error));
       }
     }
@@ -212,6 +269,8 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     const e = event as { message?: string; error?: Error } | undefined;
     const message = e?.message ?? (e?.error ? String(e.error) : 'worker error');
     poolLog.warn(`worker error: ${message}`);
+    const idx = this.slots.indexOf(slot);
+    emitDevtools({ type: 'worker:error', poolId: this.poolId, slot: idx, message });
 
     // Reject the dead worker's in-flight tasks. Orphaned (already
     // aborted/timed-out) entries are dropped without re-counting.
@@ -222,23 +281,25 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
         if (entry.done) continue;
         entry.done = true;
         this.statsAgg.failed++;
+        emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'crashed', error: message });
         entry.reject(new WorkerCrashedError(message));
       }
     }
 
-    const idx = this.slots.indexOf(slot);
     if (idx >= 0) this.slots.splice(idx, 1);
     slot.worker.terminate();
 
     if (this.respawn) {
       poolLog.info('respawning crashed worker');
       this.addWorker(this.spawn());
+      emitDevtools({ type: 'worker:respawn', poolId: this.poolId, slot: this.slots.length - 1 });
     } else if (this.slots.length === 0) {
       // No workers left to ever serve the queue.
       for (const entry of this.queue.splice(0)) {
         entry.done = true;
         this.detach(entry);
         this.statsAgg.failed++;
+        emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'crashed', error: message });
         entry.reject(new WorkerCrashedError(message));
       }
     }
@@ -270,16 +331,26 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     entry.messageId = messageId;
     entry.slot = slot;
     entry.sentAt = performance.now();
-    this.statsAgg.waitMs.add(performance.now() - entry.enqueuedAt);
+    const waitMs = entry.sentAt - entry.enqueuedAt;
+    this.statsAgg.waitMs.add(waitMs);
     slot.inFlight++;
     this.pending.set(messageId, entry);
-    taskLog.debug(`→ ${entry.contract.taskId}`, { worker: this.slots.indexOf(slot), args: entry.args });
-    slot.worker.postMessage({
-      type: 'EXECUTE_TASK',
-      messageId,
-      taskId: entry.contract.taskId,
-      args: entry.args,
-    });
+    const slotIndex = this.slots.indexOf(slot);
+    taskLog.debug(`→ ${entry.contract.taskId}`, { worker: slotIndex, args: entry.args });
+    if (devtoolsEnabled()) {
+      emitDevtools({ type: 'task:dispatch', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, slot: slotIndex, waitMs, argBytes: estimateCloneBytes(entry.args) });
+    }
+    const msg = { type: 'EXECUTE_TASK', messageId, taskId: entry.contract.taskId, args: entry.args };
+    if (this.chaos) {
+      applyChaos(this.chaos, {
+        live: () => this.pending.get(messageId) === entry,
+        fail: () => this.handleReply(slot, { messageId, taskId: msg.taskId, success: false, error: CHAOS_FAILURE }),
+        timeout: () => this.cancel(entry, new TaskTimeoutError()),
+        post: () => slot.worker.postMessage(msg),
+      });
+    } else {
+      slot.worker.postMessage(msg);
+    }
   }
 
   /** Detaches signal/timeout listeners from a finalized entry. */
@@ -302,6 +373,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     entry.done = true;
     this.detach(entry);
     this.statsAgg.aborted++;
+    emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: err instanceof TaskTimeoutError ? 'timeout' : 'aborted' });
     entry.reject(err);
     this.drainQueue();
     this.checkDrained();
@@ -333,6 +405,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
       const entry: TaskEntry = {
         contract,
         args: args as any[],
+        callId: ++this.nextCallId,
         enqueuedAt: performance.now(),
         resolve,
         reject,
@@ -348,12 +421,14 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
         entry.timer = setTimeout(() => this.cancel(entry, new TaskTimeoutError()), timeout);
       }
 
+      emitDevtools({ type: 'task:enqueue', poolId: this.poolId, callId: entry.callId, taskId: contract.taskId });
       const slot = this.pickWorker();
       if (slot) {
         this.send(slot, entry);
       } else if (this.queue.length >= this.maxQueue) {
         entry.done = true;
         this.detach(entry);
+        emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: contract.taskId, outcome: 'queue-full' });
         reject(new PoolQueueFullError()); // never dispatched — stats untouched
         return;
       } else {
@@ -376,7 +451,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
    * (e.g. a second pool of HTTP workers via withSharedBuffer).
    */
   public get sharedBuffer(): SharedArrayBuffer | undefined {
-    return this.memoryManager?.getBuffer();
+    return this.memoryManager?.getBuffer() ?? this.injectedBuffer;
   }
 
   /**
@@ -420,17 +495,20 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
 
   public terminate(): void {
     this.closed = true;
+    this.devtoolsOff?.();
     // Final flush + release — fire-and-forget; terminate() stays synchronous.
     void this.persistence?.stop()?.catch?.((e: unknown) =>
       poolLog.warn('memory persistence stop failed', e),
     );
     poolLog.info(`terminating ${this.slots.length} worker(s)`);
+    emitDevtools({ type: 'pool:terminate', poolId: this.poolId });
     const crashed = new WorkerCrashedError('pool terminated');
     for (const [, entry] of this.pending) {
       this.detach(entry);
       if (entry.done) continue; // orphaned — already counted as aborted
       entry.done = true;
       this.statsAgg.failed++;
+      emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'crashed', error: 'pool terminated' });
       entry.reject(crashed);
     }
     this.pending.clear();
@@ -438,6 +516,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
       entry.done = true;
       this.detach(entry);
       this.statsAgg.failed++;
+      emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'crashed', error: 'pool terminated' });
       entry.reject(crashed);
     }
     for (const slot of this.slots) {