@animalabs/agent-framework 0.5.7 → 0.6.0

package/src/mcpl/transport.ts

@@ -0,0 +1,307 @@
+/**
+ * McplTransport — the byte-level seam under McplServerConnection.
+ *
+ * An MCPL connection is newline-delimited JSON-RPC over a duplex stream. The
+ * only things the connection needs from its underlying transport are: write a
+ * line, receive lines, surface diagnostics/errors, and know when it closed. By
+ * abstracting exactly that, the handshake, message routing, and every send path
+ * stay transport-agnostic and run IDENTICALLY over a spawned stdio child or a
+ * WebSocket — which is the whole point of network MCPL.
+ *
+ * Two implementations:
+ *  - StdioTransport      — spawns `config.command` and speaks over stdin/stdout;
+ *                          child stderr is surfaced as 'stderr' lines.
+ *  - WebSocketTransport  — dials `config.url` (ws:// or wss://) with the `ws`
+ *                          library, appending `?token=` when `config.token` is
+ *                          set; each WS text frame is one JSON-RPC line.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+
+import type { McplServerConfig } from './types.js';
+
+/** Why/how a transport closed. `code`/`signal` are populated for stdio child
+ *  exits; `reason` carries a WebSocket close reason or an error message. */
+export interface TransportCloseInfo {
+  code?: number | null;
+  signal?: NodeJS.Signals | null;
+  reason?: string;
+}
+
+/**
+ * A line-oriented duplex transport to an MCPL server.
+ *
+ * Events:
+ *  - `'line'`   `(line: string)`            one inbound NDJSON line (no newline)
+ *  - `'stderr'` `(line: string)`            diagnostic line (stdio child stderr; never WS)
+ *  - `'error'`  `(err: Error)`              transport-level error
+ *  - `'close'`  `(info: TransportCloseInfo)` transport closed (once)
+ *
+ * Inbound `'line'`/`'stderr'` events are buffered until the first matching
+ * listener attaches (and re-buffered whenever there are none), so no message is
+ * lost across the handshake→routing handoff regardless of attach timing.
+ */
+export abstract class McplTransport extends EventEmitter {
+  abstract readonly kind: 'stdio' | 'websocket';
+
+  private _closed = false;
+  private lineBuffer: string[] = [];
+  private stderrBuffer: string[] = [];
+
+  protected constructor() {
+    super();
+    // Flush buffered inbound lines the moment a consumer subscribes.
+    this.on('newListener', (event) => {
+      if (event === 'line' && this.lineBuffer.length > 0) {
+        const pending = this.lineBuffer;
+        this.lineBuffer = [];
+        queueMicrotask(() => { for (const l of pending) this.emit('line', l); });
+      } else if (event === 'stderr' && this.stderrBuffer.length > 0) {
+        const pending = this.stderrBuffer;
+        this.stderrBuffer = [];
+        queueMicrotask(() => { for (const l of pending) this.emit('stderr', l); });
+      }
+    });
+  }
+
+  get closed(): boolean {
+    return this._closed;
+  }
+
+  /** Deliver an inbound line, buffering it if nobody is listening yet. */
+  protected pushLine(line: string): void {
+    if (this.listenerCount('line') > 0) this.emit('line', line);
+    else this.lineBuffer.push(line);
+  }
+
+  /** Deliver a diagnostic line, buffering it if nobody is listening yet. */
+  protected pushStderr(line: string): void {
+    if (this.listenerCount('stderr') > 0) this.emit('stderr', line);
+    else this.stderrBuffer.push(line);
+  }
+
+  /** Emit 'close' exactly once. */
+  protected markClosed(info: TransportCloseInfo): void {
+    if (this._closed) return;
+    this._closed = true;
+    this.emit('close', info);
+  }
+
+  /** Write one JSON-RPC message as an NDJSON line. */
+  abstract writeLine(json: string): void;
+
+  /** Close the transport and release resources. Resolves once fully closed. */
+  abstract close(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// stdio
+// ---------------------------------------------------------------------------
+
+export class StdioTransport extends McplTransport {
+  readonly kind = 'stdio' as const;
+
+  private constructor(
+    private readonly child: ChildProcess,
+    private readonly rl: ReadlineInterface,
+  ) {
+    super();
+
+    this.rl.on('line', (line: string) => this.pushLine(line));
+
+    // Stitch stderr chunks into whole lines (a chunk can split a line).
+    let carry = '';
+    this.child.stderr?.on('data', (chunk: Buffer) => {
+      const text = carry + chunk.toString('utf8');
+      const lines = text.split('\n');
+      carry = lines.pop() ?? '';
+      for (const l of lines) if (l.length > 0) this.pushStderr(l);
+    });
+
+    this.child.on('error', (err) => this.emit('error', err));
+    this.child.on('exit', (code, signal) =>
+      this.markClosed({ code, signal, reason: 'child process exited' }),
+    );
+  }
+
+  /**
+   * Spawn `config.command` and return a ready stdio transport. Rejects if the
+   * command is missing (a config bug) or the process fails to spawn.
+   */
+  static spawn(config: McplServerConfig): StdioTransport {
+    if (!config.command) {
+      throw new Error(
+        `MCPL server "${config.id}": stdio transport requires "command" (none provided)`,
+      );
+    }
+    const child = spawn(config.command, config.args ?? [], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...config.env },
+    });
+    const rl = createInterface({ input: child.stdout! });
+    return new StdioTransport(child, rl);
+  }
+
+  writeLine(json: string): void {
+    // stdin may be gone if the child died between the closed-check and here.
+    this.child.stdin?.write(json + '\n');
+  }
+
+  async close(): Promise<void> {
+    this.markClosed({ reason: 'closed by host' });
+    this.rl.close();
+    if (this.child && !this.child.killed) {
+      this.child.kill();
+    }
+    await new Promise<void>((resolve) => {
+      if (!this.child || this.child.exitCode !== null || this.child.killed) {
+        resolve();
+      } else {
+        this.child.once('exit', () => resolve());
+      }
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket
+// ---------------------------------------------------------------------------
+
+/** Timeout for the WebSocket to reach OPEN before we give up (ms). */
+const WS_OPEN_TIMEOUT_MS = 15_000;
+
+export class WebSocketTransport extends McplTransport {
+  readonly kind = 'websocket' as const;
+
+  private constructor(private readonly ws: WebSocket) {
+    super();
+
+    this.ws.on('message', (data: WebSocket.RawData, isBinary: boolean) => {
+      // MCPL frames are UTF-8 JSON text. A frame MAY contain multiple
+      // newline-delimited messages or a trailing newline; split defensively.
+      const text = isBinary ? (data as Buffer).toString('utf8') : String(data);
+      for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0) this.pushLine(trimmed);
+      }
+    });
+
+    this.ws.on('error', (err: Error) => this.emit('error', err));
+    this.ws.on('close', (code: number, reason: Buffer) =>
+      this.markClosed({ code, reason: reason?.toString('utf8') || 'websocket closed' }),
+    );
+  }
+
+  /**
+   * Dial `config.url` and resolve once the socket is OPEN. Appends `?token=`
+   * when `config.token` is set. Rejects on connect error / timeout (and tears
+   * the socket down) so a failed dial never leaks an open handle.
+   */
+  static open(config: McplServerConfig): Promise<WebSocketTransport> {
+    const url = buildWebSocketUrl(config);
+    const ws = new WebSocket(url);
+
+    return new Promise<WebSocketTransport>((resolve, reject) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        ws.removeAllListeners();
+        try { ws.terminate(); } catch { /* already gone */ }
+        reject(new Error(`MCPL server "${config.id}" WebSocket connect timed out after ${WS_OPEN_TIMEOUT_MS}ms (${url})`));
+      }, WS_OPEN_TIMEOUT_MS);
+
+      ws.once('open', () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.removeAllListeners('error'); // the instance re-attaches its own handlers
+        resolve(new WebSocketTransport(ws));
+      });
+
+      ws.once('error', (err: Error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.removeAllListeners();
+        try { ws.terminate(); } catch { /* already gone */ }
+        reject(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${url})`));
+      });
+    });
+  }
+
+  writeLine(json: string): void {
+    if (this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(json);
+    }
+  }
+
+  async close(): Promise<void> {
+    this.markClosed({ reason: 'closed by host' });
+    await new Promise<void>((resolve) => {
+      if (this.ws.readyState === WebSocket.CLOSED) {
+        resolve();
+        return;
+      }
+      this.ws.once('close', () => resolve());
+      try {
+        this.ws.close();
+      } catch {
+        try { this.ws.terminate(); } catch { /* already gone */ }
+        resolve();
+      }
+    });
+  }
+}
+
+/**
+ * Build the dial URL: validate it's a ws(s):// URL and append the auth token as
+ * a `token` query param when provided (preserving any existing query).
+ */
+export function buildWebSocketUrl(config: McplServerConfig): string {
+  if (!config.url) {
+    throw new Error(`MCPL server "${config.id}": websocket transport requires "url" (none provided)`);
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(config.url);
+  } catch {
+    throw new Error(`MCPL server "${config.id}": invalid WebSocket url "${config.url}"`);
+  }
+  if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+    throw new Error(
+      `MCPL server "${config.id}": websocket url must be ws:// or wss://, got "${parsed.protocol}"`,
+    );
+  }
+  if (config.token) {
+    parsed.searchParams.set('token', config.token);
+  }
+  return parsed.toString();
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/** True when the config selects the WebSocket transport (explicit `transport`,
+ *  or a `url` with no `command`). */
+export function isWebSocketTransport(config: McplServerConfig): boolean {
+  if (config.transport === 'websocket') return true;
+  if (config.transport === 'stdio') return false;
+  return Boolean(config.url) && !config.command;
+}
+
+/**
+ * Open the transport selected by `config` (WebSocket when `transport` is
+ * 'websocket' or a bare `url` is given; stdio otherwise). The returned transport
+ * is connected at the byte level but has NOT performed the MCPL handshake.
+ */
+export async function openTransport(config: McplServerConfig): Promise<McplTransport> {
+  if (isWebSocketTransport(config)) {
+    return WebSocketTransport.open(config);
+  }
+  return StdioTransport.spawn(config);
+}

package/src/mcpl/types.ts

@@ -165,8 +165,12 @@ export interface McplServerConfig {
   /** Unique server identifier */
   id: string;
 
-  /** Command to spawn the server process (stdio transport) */
-  command: string;
+  /**
+   * Command to spawn the server process (stdio transport). Mutually exclusive
+   * with `url`. Required for the stdio transport; omit it (and set `url`) for
+   * the WebSocket transport.
+   */
+  command?: string;
 
   /** Arguments for the command */
   args?: string[];
@@ -174,6 +178,26 @@ export interface McplServerConfig {
   /** Environment variables for the child process */
   env?: Record<string, string>;
 
+  /**
+   * WebSocket URL for the network transport (`ws://` or `wss://`). Mutually
+   * exclusive with `command`. When set (or `transport: 'websocket'`), the host
+   * dials this endpoint instead of spawning a process — newline-delimited
+   * JSON-RPC MCPL runs over the socket identically to stdio.
+   */
+  url?: string;
+
+  /**
+   * Transport selector. Defaults to `'websocket'` when a bare `url` is given
+   * (no `command`), `'stdio'` otherwise. Set explicitly to disambiguate.
+   */
+  transport?: 'stdio' | 'websocket';
+
+  /**
+   * Bearer token for WebSocket auth. Appended to `url` as a `token` query
+   * parameter (`?token=…`) on connect. Ignored by the stdio transport.
+   */
+  token?: string;
+
   /** Feature sets to enable on connect */
   enabledFeatureSets?: string[];
 
@@ -291,6 +315,16 @@ export interface FeatureSetDeclaration {
 
   /** Whether host manages state persistence for this feature set (Section 8.1) */
   hostState?: boolean;
+
+  /** Optional, open-world tag ontology for this feature set's events
+   *  (MCPL RFC-001 §5). A hint catalog — hosts tolerate undeclared tags. */
+  tagOntology?: {
+    coreTags?: string[];
+    tags?: Record<string, unknown>;
+    keyed?: Record<string, unknown>;
+    defaultTreatment?: unknown[];
+    open?: boolean;
+  };
 }
 
 /**
@@ -390,6 +424,13 @@ export interface StateCheckpoint {
   /** Parent checkpoint (null for root) */
   parent: string | null;
 
+  /**
+   * Owning feature set, when the server tags it. Authoritative signal for
+   * attributing this checkpoint — lets the host record it to the right set
+   * instead of guessing when a server has more than one stateful feature set.
+   */
+  featureSet?: string;
+
   /**
    * Full state data (for host-managed state).
    * Mutually exclusive with `patch`.
@@ -461,6 +502,9 @@ export interface PushEventParams {
   /** Provenance metadata (server-defined) */
   origin?: Record<string, unknown>;
 
+  /** Semantic classification the host may route on (MCPL RFC-001). */
+  tags?: string[];
+
   /** Event payload */
   payload: {
     /** Content for the model to interpret */
@@ -897,6 +941,9 @@ export interface ChannelIncomingMessage {
 
   /** Platform-specific metadata */
   metadata?: Record<string, unknown>;
+
+  /** Semantic classification the host may route on (MCPL RFC-001). */
+  tags?: string[];
 }
 
 /**

package/src/module-registry.ts

@@ -55,6 +55,7 @@ export class ModuleRegistry {
 
   private pushEventFn: (event: ProcessEvent) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
+  private callToolFn: (call: ToolCall) => Promise<ToolResult>;
 
   constructor(
     store: JsStore,
@@ -68,6 +69,7 @@ export class ModuleRegistry {
       queryMessages: (filter: MessageQuery) => MessageQueryResult;
       pushEvent: (event: ProcessEvent) => void;
       onTrace: (listener: TraceEventListener) => () => void;
+      callTool: (call: ToolCall) => Promise<ToolResult>;
     }
   ) {
     this.store = store;
@@ -80,6 +82,7 @@ export class ModuleRegistry {
     this.queryMessagesFn = options.queryMessages;
     this.pushEventFn = options.pushEvent;
     this.onTraceFn = options.onTrace;
+    this.callToolFn = options.callTool;
   }
 
   /**
@@ -120,7 +123,8 @@ export class ModuleRegistry {
       this.getMessageFn,
       this.queryMessagesFn,
       this.pushEventFn,
-      this.onTraceFn
+      this.onTraceFn,
+      this.callToolFn
     );
 
     this.modules.set(module.name, module);
@@ -372,6 +376,7 @@ class ModuleContextImpl implements ModuleContext {
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
   private pushEventFn: (event: ProcessEvent) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
+  private callToolFn: (call: ToolCall) => Promise<ToolResult>;
 
   // External ID mapping stored in module state
   private externalIdMap: Map<string, MessageId> = new Map();
@@ -390,7 +395,8 @@ class ModuleContextImpl implements ModuleContext {
     getMessage: (id: MessageId) => StoredMessage | null,
     queryMessages: (filter: MessageQuery) => MessageQueryResult,
     pushEvent: (event: ProcessEvent) => void,
-    onTrace: (listener: TraceEventListener) => () => void
+    onTrace: (listener: TraceEventListener) => () => void,
+    callTool: (call: ToolCall) => Promise<ToolResult>
   ) {
     this.moduleName = moduleName;
     this.store = store;
@@ -406,6 +412,7 @@ class ModuleContextImpl implements ModuleContext {
     this.queryMessagesFn = queryMessages;
     this.pushEventFn = pushEvent;
     this.onTraceFn = onTrace;
+    this.callToolFn = callTool;
 
     // Load external ID map from state if exists
     const state = this.getState<{ externalIdMap?: Record<string, string> }>();
@@ -436,6 +443,10 @@ class ModuleContextImpl implements ModuleContext {
     return this.onTraceFn(listener);
   }
 
+  callTool(call: ToolCall): Promise<ToolResult> {
+    return this.callToolFn(call);
+  }
+
   addMessage(
     participant: string,
     content: ContentBlock[],

package/src/prose-segments.ts

@@ -0,0 +1,42 @@
+/**
+ * Split an assistant turn's content blocks into ordered prose segments.
+ *
+ * A single turn can interleave prose and tool calls — "msgA → [tool] → msgB →
+ * [tool] → msgC". The membrane accumulates the WHOLE turn (all tool rounds) into
+ * one `response.content` array in provider order, so a left-to-right walk that
+ * breaks at each tool boundary reconstructs the emission order.
+ *
+ * Host output routing used to join every text block into a single trailing post,
+ * collapsing those distinct messages into one (item 4). This helper instead
+ * yields each contiguous run of text — the segments a surface should deliver as
+ * separate, ordered messages. Contiguous text blocks merge into one segment;
+ * `tool_use` / `tool_result` blocks are segment boundaries; empty or
+ * whitespace-only runs are dropped.
+ */
+
+import type { ContentBlock } from '@animalabs/membrane';
+
+export function splitProseSegments(content: readonly ContentBlock[]): string[] {
+  const segments: string[] = [];
+  let buf: string[] = [];
+
+  const flush = (): void => {
+    const s = buf.join('\n').trim();
+    if (s) segments.push(s);
+    buf = [];
+  };
+
+  for (const block of content) {
+    if (block.type === 'text') {
+      buf.push((block as ContentBlock & { type: 'text' }).text);
+    } else if (block.type === 'tool_use' || block.type === 'tool_result') {
+      flush();
+    }
+    // Other block types (thinking, redacted_thinking, image, …) are neither
+    // prose nor boundaries: they don't reach a channel and don't separate two
+    // prose messages, so they're skipped without flushing.
+  }
+  flush();
+
+  return segments;
+}

package/src/runtime/liveness-watchdog-worker.ts

@@ -0,0 +1,66 @@
+/**
+ * Liveness watchdog worker — runs on its own thread, so it keeps ticking even
+ * when the main thread is wedged. Watches the shared heartbeat; if it goes stale
+ * past the threshold, writes a diagnostic and kills the whole process.
+ *
+ * Killing from a worker: process.kill(process.pid, signal) signals the whole
+ * process. SIGABRT → core dump (if enabled) + terminate; SIGKILL → immediate.
+ * Catchable signals (SIGTERM) are avoided — their handler would run on the
+ * wedged main thread and never fire.
+ */
+import { workerData } from 'node:worker_threads';
+import { writeFileSync } from 'node:fs';
+
+interface Data {
+  sab: SharedArrayBuffer;
+  thresholdMs: number;
+  checkMs: number;
+  action: 'abort' | 'exit';
+  reportPath: string | null;
+}
+const { sab, thresholdMs, checkMs, action, reportPath } = workerData as Data;
+
+const hb = new Float64Array(sab, 0, 1);
+const phaseBuf = new Uint8Array(sab, 16, 48);
+const dec = new TextDecoder();
+
+function currentPhase(): string {
+  return dec.decode(phaseBuf).replace(/\0+$/, '') || 'unknown';
+}
+
+function check(): void {
+  const last = hb[0];
+  const age = Date.now() - last;
+  if (last > 0 && age > thresholdMs) {
+    const phase = currentPhase();
+    const report = {
+      ts: new Date().toISOString(),
+      event: 'main-thread-wedged',
+      ageMs: Math.round(age),
+      thresholdMs,
+      phase,
+      action,
+      pid: process.pid,
+    };
+    const line = `[liveness-watchdog] main thread unresponsive ${Math.round(age)}ms ` +
+      `(phase=${phase}) — failing hard via ${action}`;
+    try {
+      console.error(line);
+    } catch {
+      /* ignore */
+    }
+    if (reportPath) {
+      try {
+        writeFileSync(reportPath, JSON.stringify(report) + '\n', { flag: 'a' });
+      } catch {
+        /* best effort */
+      }
+    }
+    // Kill the whole process. The supervisor restarts a fresh one.
+    process.kill(process.pid, action === 'abort' ? 'SIGABRT' : 'SIGKILL');
+    return; // process is dying
+  }
+  setTimeout(check, checkMs);
+}
+
+setTimeout(check, checkMs);

package/src/runtime/liveness-watchdog.ts

@@ -0,0 +1,122 @@
+/**
+ * LivenessWatchdog — detects a wedged (unresponsive) main thread and fails hard.
+ *
+ * The agent's event loop is single-threaded. A synchronous infinite loop or a
+ * self-rescheduling microtask flood (e.g. a pathological compression drain) can
+ * peg the thread for minutes: no events, no heartbeat, no recovery — the agent
+ * goes silently deaf. A same-thread timer can't catch this (it can't fire while
+ * the loop is blocked), so detection must live off-thread.
+ *
+ * Mechanism: the main thread stamps a heartbeat (and an optional phase label)
+ * into shared memory on a timer. A worker thread — which keeps running even when
+ * main is wedged — watches the heartbeat; if it goes stale past a threshold it
+ * writes a diagnostic and kills the whole process:
+ *   - 'abort' → SIGABRT (core dump if enabled, for an offline stack) then dies
+ *   - 'exit'  → SIGKILL (clean, quiet; rely on the supervisor to restart)
+ * Either way the supervisor (launchd/systemd) restarts a fresh process instead
+ * of leaving a deaf one running.
+ */
+import { Worker } from 'node:worker_threads';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { phaseChannel } from '@animalabs/context-manager';
+
+const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'liveness-watchdog-worker.js');
+
+const HEARTBEAT_OFFSET = 0; // Float64: last heartbeat (ms since epoch)
+const PHASE_OFFSET = 16; // Uint8[48]: current phase label (UTF-8)
+const PHASE_LEN = 48;
+const SAB_SIZE = 64;
+
+export interface WatchdogOptions {
+  /** Wedge threshold: kill if no heartbeat for this long. Default 30000ms. */
+  thresholdMs?: number;
+  /** Heartbeat cadence. Default 1000ms. */
+  heartbeatMs?: number;
+  /** 'abort' → SIGABRT (core dump for debugging); 'exit' → SIGKILL. Default 'abort'. */
+  action?: 'abort' | 'exit';
+  /** Optional file the worker writes a JSON wedge report to before killing. */
+  reportPath?: string;
+  /** Disable entirely. */
+  enabled?: boolean;
+}
+
+export class LivenessWatchdog {
+  private readonly sab = new SharedArrayBuffer(SAB_SIZE);
+  private readonly hb = new Float64Array(this.sab, HEARTBEAT_OFFSET, 1);
+  private readonly phaseBuf = new Uint8Array(this.sab, PHASE_OFFSET, PHASE_LEN);
+  private readonly enc = new TextEncoder();
+  private timer?: ReturnType<typeof setInterval>;
+  private worker?: Worker;
+  private started = false;
+
+  constructor(private readonly opts: WatchdogOptions = {}) {}
+
+  start(): void {
+    if (this.started || this.opts.enabled === false) return;
+    this.started = true;
+    const heartbeatMs = this.opts.heartbeatMs ?? 1000;
+    this.setPhase('starting');
+    this.beat();
+    this.timer = setInterval(() => this.beat(), heartbeatMs);
+    this.timer.unref?.();
+    try {
+      this.worker = new Worker(WORKER_PATH, {
+        workerData: {
+          sab: this.sab,
+          thresholdMs: this.opts.thresholdMs ?? 30_000,
+          checkMs: Math.min(heartbeatMs, 2000),
+          action: this.opts.action ?? 'abort',
+          reportPath: this.opts.reportPath ?? null,
+        },
+      });
+      this.worker.unref();
+      this.worker.on('error', (e) => console.error('[liveness-watchdog] worker error:', e.message));
+      // Wire the phase channel so labelled synchronous spans (compression,
+      // context-build, merge-graph walks) name themselves in a wedge report.
+      phaseChannel.report = (label: string) => this.setPhase(label);
+      console.error(
+        `[liveness-watchdog] armed: threshold=${this.opts.thresholdMs ?? 30_000}ms ` +
+          `action=${this.opts.action ?? 'abort'}`,
+      );
+    } catch (e) {
+      console.error('[liveness-watchdog] failed to start:', (e as Error).message);
+    }
+    this.setPhase('idle');
+  }
+
+  /** Stamp liveness. Called on a timer; the worker watches for staleness. */
+  private beat(): void {
+    this.hb[0] = Date.now();
+  }
+
+  /**
+   * Label the operation the main thread is about to run synchronously, so a
+   * wedge report names it (e.g. 'compression-tick', 'context-build'). Keep it
+   * short (truncated to 48 bytes). Reset to 'idle' when done.
+   */
+  setPhase(label: string): void {
+    this.phaseBuf.fill(0);
+    const bytes = this.enc.encode(label);
+    this.phaseBuf.set(bytes.subarray(0, PHASE_LEN));
+  }
+
+  /** Run a synchronous section under a named phase, restoring the prior phase. */
+  withPhase<T>(label: string, fn: () => T): T {
+    this.setPhase(label);
+    try {
+      return fn();
+    } finally {
+      this.setPhase('idle');
+    }
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    phaseChannel.report = () => {};
+    void this.worker?.terminate();
+    this.worker = undefined;
+    this.started = false;
+  }
+}