@animalabs/agent-framework 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "type": "module",
   "main": "dist/src/index.js",

package/src/framework.ts

@@ -51,6 +51,7 @@ import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { safeSlice } from './safe-slice.js';
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
+import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
 import { UsageTracker, type PersistedUsageState } from './usage/usage-tracker.js';
 import type { SessionUsageSnapshot, UsageUpdatedEvent } from './usage/types.js';
@@ -473,6 +474,16 @@ export class AgentFramework {
     this.traceListeners.push(listener);
   }
 
+  /**
+   * Public accessor for the MCPL channel registry.
+   * Null when no MCPL servers are configured.
+   * Modules that need channel-level operations (typing indicators, default publish channel,
+   * etc.) obtain them here.
+   */
+  get channels(): ChannelRegistry | null {
+    return this.channelRegistry;
+  }
+
   /**
    * Remove a trace event listener.
    */
@@ -2101,6 +2112,13 @@ export class AgentFramework {
     }
     const prefix = config.toolPrefix ?? `mcpl--${config.id}`;
     const toolName = call.name.slice(prefix.length + 2); // Strip prefix + '--'
+    if (!isToolAllowed(toolName, config)) {
+      return {
+        success: false,
+        error: `Tool '${call.name}' is not permitted by this server's tool policy.`,
+        isError: true,
+      };
+    }
     try {
       const result = await server.sendToolsCall(toolName, call.input as Record<string, unknown>);
       return {
@@ -2457,10 +2475,10 @@ export class AgentFramework {
       (event) => this.pushEvent(event),
       (event) => this.emitTrace(event as { type: TraceEvent['type']; [key: string]: unknown }),
       {
-        sendTypingFn: (serverId, channelId) => {
+        sendTypingFn: (serverId, channelId, metadata, op) => {
           const server = this.mcplServerRegistry!.getServer(serverId);
           if (server) {
-            server.sendChannelsTyping(channelId);
+            server.sendChannelsTyping(channelId, metadata, op);
           }
         },
         shouldTriggerInference: triggerFilter,
@@ -2547,6 +2565,12 @@ export class AgentFramework {
    * Push events and inference requests are deferred to Steps 6/7.
    */
   private wireMcplEvents(connection: McplServerConnection): void {
+    // Forward subprocess stderr lines as trace events so consumers (conhost,
+    // log sinks, TUI badges) can persist and surface them.
+    connection.on('stderr', (params: { line: string }) => {
+      this.emitTrace({ type: 'mcpl:server-stderr', serverId: connection.id, line: params.line });
+    });
+
     // Handle dynamic feature set changes from server
     connection.on('feature-sets-changed', (params: FeatureSetsChangedParams) => {
       this.featureSetManager?.handleFeatureSetsChanged(connection.id, params);
@@ -2644,6 +2668,7 @@ export class AgentFramework {
       try {
         const result = await server.sendToolsList();
         for (const tool of result.tools) {
+          if (!isToolAllowed(tool.name, config)) continue;
           // MCP tool schemas are generic JSON Schema; cast to membrane's ToolDefinition format
           const schema = tool.inputSchema as import('./types/index.js').ToolDefinition['inputSchema'];
           tools.push({
@@ -2733,6 +2758,23 @@ export class AgentFramework {
       return;
     }
 
+    const config = this.mcplServerConfigs.get(serverId);
+    if (!isToolAllowed(toolName, config)) {
+      this.emitTrace({ type: 'tool:failed', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, error: 'denied by tool policy' });
+      this.pushEvent({
+        type: 'tool-result',
+        callId: call.id,
+        agentName,
+        moduleName: `mcpl:${serverId}`,
+        result: {
+          success: false,
+          error: `Tool '${call.name}' is not permitted by this server's tool policy.`,
+          isError: true,
+        },
+      });
+      return;
+    }
+
     this.emitTrace({ type: 'tool:started', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, input: call.input });
     const startTime = Date.now();
     const args = (call.input && typeof call.input === 'object') ? call.input as Record<string, unknown> : {};

package/src/index.ts

@@ -60,6 +60,9 @@ export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent
 export { EventGate } from './gate/index.js';
 export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior } from './gate/index.js';
 
+// MCPL channel registry (exposed for modules that need channel-level operations)
+export { ChannelRegistry } from './mcpl/index.js';
+
 // Re-export commonly used types from dependencies
 export type { ContextManager, ContextStrategy, TokenBudget } from '@animalabs/context-manager';
 export { PassthroughStrategy, AutobiographicalStrategy, KnowledgeStrategy } from '@animalabs/context-manager';

package/src/mcpl/channel-registry.ts

@@ -38,6 +38,21 @@ import type { ToolDefinition, ToolResult, ProcessEvent } from '../types/index.js
 
 const TYPING_INTERVAL_MS = 7_000;
 
+function shallowEqualRecord(
+  a: Record<string, unknown> | undefined,
+  b: Record<string, unknown> | undefined,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const k of keysA) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+}
+
 // ============================================================================
 // Internal Types
 // ============================================================================
@@ -179,7 +194,12 @@ export class ChannelRegistry {
   private featureSetManager: FeatureSetManager;
   private pushEventFn: (event: ProcessEvent) => void;
   private emitTraceFn: (event: { type: string; [key: string]: unknown }) => void;
-  private sendTypingFn?: (serverId: string, channelId: string) => void;
+  private sendTypingFn?: (
+    serverId: string,
+    channelId: string,
+    metadata?: Record<string, unknown>,
+    op?: 'start' | 'stop',
+  ) => void;
   private shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
 
   /** Registered channels, keyed by `{serverId}:{channelId}`. */
@@ -195,6 +215,10 @@ export class ChannelRegistry {
   /** Per-channel typing indicator timers. */
   private typingIntervals = new Map<string, ReturnType<typeof setInterval>>();
 
+  /** Per-channel typing metadata — carried on the 7s refresh so the target
+   *  server keeps getting the same routing hints (e.g. Zulip topic). */
+  private typingMetadata = new Map<string, Record<string, unknown>>();
+
   /**
    * Per-server channel auto-open policy. Populated by the framework from
    * each McplServerConfig at connect time; default ('auto') applies when
@@ -208,7 +232,12 @@ export class ChannelRegistry {
     pushEventFn: (event: ProcessEvent) => void,
     emitTraceFn: (event: { type: string; [key: string]: unknown }) => void,
     options?: ChannelRegistryOptions & {
-      sendTypingFn?: (serverId: string, channelId: string) => void;
+      sendTypingFn?: (
+        serverId: string,
+        channelId: string,
+        metadata?: Record<string, unknown>,
+        op?: 'start' | 'stop',
+      ) => void;
     },
   ) {
     this.serverRegistry = serverRegistry;
@@ -413,9 +442,27 @@ export class ChannelRegistry {
    *
    * No-op if already typing on this channel.
    */
-  startTyping(channelId: string): void {
+  startTyping(channelId: string, metadata?: Record<string, unknown>): void {
+    const metadataChanged =
+      metadata !== undefined &&
+      !shallowEqualRecord(this.typingMetadata.get(channelId), metadata);
+    if (metadata) {
+      this.typingMetadata.set(channelId, metadata);
+    }
+
     if (this.typingIntervals.has(channelId)) {
-      return; // Already typing
+      // Already typing. If the caller supplied new routing metadata (e.g. the
+      // relevant Zulip topic just moved because a newer message arrived),
+      // dispatch an immediate refresh so the server sees the new routing
+      // within this request instead of waiting up to TYPING_INTERVAL_MS for
+      // the next tick.
+      if (metadataChanged) {
+        const entry = this.findChannelEntry(channelId);
+        if (entry) {
+          this.sendTypingNotification(entry.serverId, channelId);
+        }
+      }
+      return;
     }
 
     // Find the channel entry and its server
@@ -427,7 +474,9 @@ export class ChannelRegistry {
     // Send typing immediately
     this.sendTypingNotification(entry.serverId, channelId);
 
-    // Set up interval
+    // Set up interval — pulls the latest metadata on each tick so mid-stream
+    // updates (e.g. a newer incoming message switching the relevant topic)
+    // take effect on the next refresh.
     const interval = setInterval(() => {
       this.sendTypingNotification(entry.serverId, channelId);
     }, TYPING_INTERVAL_MS);
@@ -447,13 +496,32 @@ export class ChannelRegistry {
       if (interval) {
         clearInterval(interval);
         this.typingIntervals.delete(channelId);
+        // Dispatch an explicit 'stop' so servers that support it (e.g. Zulip)
+        // clear the indicator immediately rather than waiting for auto-expire.
+        // Metadata still carries the routing hint so the stop hits the same
+        // topic/thread as the start. Guarded by `interval`: matches the
+        // global-clear branch's semantics, and keeps defensive stopTyping(ch)
+        // calls from spamming stops at a server that never saw a start.
+        const entry = this.findChannelEntry(channelId);
+        if (entry && this.sendTypingFn) {
+          this.sendTypingFn(entry.serverId, channelId, this.typingMetadata.get(channelId), 'stop');
+        }
       }
+      this.typingMetadata.delete(channelId);
     } else {
-      // Clear all typing intervals
+      // Clear all typing intervals and dispatch stop for each known channel
+      const channels = Array.from(this.typingIntervals.keys());
       for (const interval of this.typingIntervals.values()) {
         clearInterval(interval);
       }
       this.typingIntervals.clear();
+      if (this.sendTypingFn) {
+        for (const id of channels) {
+          const entry = this.findChannelEntry(id);
+          if (entry) this.sendTypingFn(entry.serverId, id, this.typingMetadata.get(id), 'stop');
+        }
+      }
+      this.typingMetadata.clear();
     }
   }
 
@@ -652,7 +720,7 @@ export class ChannelRegistry {
    */
   private sendTypingNotification(serverId: string, channelId: string): void {
     if (this.sendTypingFn) {
-      this.sendTypingFn(serverId, channelId);
+      this.sendTypingFn(serverId, channelId, this.typingMetadata.get(channelId));
     }
     // TODO: When server-connection exposes a public sendNotification or
     // sendTyping method, wire it here directly instead of using a callback.

package/src/mcpl/server-connection.ts

@@ -95,6 +95,9 @@ export class McplServerConnection extends EventEmitter {
   private reconnectIntervalMs = 5000;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /** Swaps the line handler on the current child's stderr pipe. Re-bound on reconnect. */
+  private rebindStderr: ((next: (line: string) => void) => void) | null = null;
+
   /**
    * Private constructor. Use `McplServerConnection.connect()` instead.
    */
@@ -151,6 +154,33 @@ export class McplServerConnection extends EventEmitter {
   // Static factory
   // ==========================================================================
 
+  /**
+   * Wire stderr forwarding on a child process. Lines are forwarded to the
+   * supplied callback. The callback can be swapped at any time via `rebind`
+   * (used during reconnect, when we want already-wired pipes to target a new
+   * emitter).
+   */
+  private static wireStderrForwarding(
+    child: ChildProcess,
+    initialLineHandler: (line: string) => void,
+  ): { rebind: (next: (line: string) => void) => void } {
+    let onLine = initialLineHandler;
+    let carry = '';
+    child.stderr?.on('data', (chunk: Buffer) => {
+      const text = carry + chunk.toString('utf8');
+      const lines = text.split('\n');
+      carry = lines.pop() ?? '';
+      for (const line of lines) {
+        if (line.length > 0) onLine(line);
+      }
+    });
+    return {
+      rebind(next) {
+        onLine = next;
+      },
+    };
+  }
+
   /**
    * Spawn a server process, perform the MCP initialize handshake with MCPL
    * capability negotiation, and return a ready-to-use connection.
@@ -166,6 +196,14 @@ export class McplServerConnection extends EventEmitter {
       env: { ...process.env, ...config.env },
     });
 
+    // Capture child stderr so it isn't silently dropped. During the handshake
+    // window (before the instance exists) lines are buffered; the buffer is
+    // drained once we have an instance to emit 'stderr' events on.
+    const earlyStderrBuffer: string[] = [];
+    const attachStderr = McplServerConnection.wireStderrForwarding(child, (line) =>
+      earlyStderrBuffer.push(line),
+    );
+
     // Fail fast if the process exits before the handshake completes
     const earlyExitPromise = new Promise<never>((_resolve, reject) => {
       child.on('error', (err) => {
@@ -251,6 +289,16 @@ export class McplServerConnection extends EventEmitter {
 
     const connection = new McplServerConnection(config.id, mcplCaps, child, rl);
 
+    // Swap the stderr handler to emit events on the instance, then drain
+    // anything that arrived during the handshake window. Keep the rebind
+    // handle on the instance so reconnect can re-target it later.
+    connection.rebindStderr = attachStderr.rebind;
+    attachStderr.rebind((line: string) => connection.emit('stderr', { line }));
+    for (const line of earlyStderrBuffer) {
+      connection.emit('stderr', { line });
+    }
+    earlyStderrBuffer.length = 0;
+
     // Store config for reconnection
     if (config.reconnect) {
       connection.config = config;
@@ -395,9 +443,21 @@ export class McplServerConnection extends EventEmitter {
     this.sendNotification(McplMethod.ChannelsOutgoingComplete, params as unknown as Record<string, unknown>);
   }
 
-  /** Send `channels/typing` notification (best-effort). */
-  sendChannelsTyping(channelId: string): void {
-    this.sendNotification(McplMethod.ChannelsTyping, { channelId });
+  /** Send `channels/typing` notification (best-effort).
+   *  `metadata` is opaque routing hints for the server — e.g. Zulip uses
+   *  `topic` to target a specific thread; other servers ignore what they don't
+   *  recognize. Typically sourced from the most recent incoming message's
+   *  metadata on the same channel.
+   *  `op` defaults to 'start'; pass 'stop' to clear an active indicator
+   *  immediately rather than waiting for server-side auto-expire. */
+  sendChannelsTyping(
+    channelId: string,
+    metadata?: Record<string, unknown>,
+    op: 'start' | 'stop' = 'start',
+  ): void {
+    const params: Record<string, unknown> = { channelId, op };
+    if (metadata) params.metadata = metadata;
+    this.sendNotification(McplMethod.ChannelsTyping, params);
   }
 
   // ==========================================================================
@@ -499,6 +559,21 @@ export class McplServerConnection extends EventEmitter {
       this.nextRequestId = 1;
       this.pendingRequests.clear();
 
+      // Re-target stderr forwarding from the throwaway `fresh` instance to `this`.
+      //
+      // Note: this follows the same "transfer internals, leak listeners on the
+      // dead instance" pattern as the message-routing and lifecycle rewiring
+      // below — `fresh`'s own readline 'line' handler and process 'exit'
+      // handler stay registered on the transferred child, short-circuited by
+      // `fresh.closed = true` set in extractInternals(). Rebinding fresh's
+      // stderr listener (rather than removing it) keeps that invariant: if we
+      // ever clean up the message-routing duplication, fresh's stderr data
+      // listener closure-holds onLine and would need the same teardown.
+      if (fresh.rebindStderr) {
+        fresh.rebindStderr((line: string) => this.emit('stderr', { line }));
+        this.rebindStderr = fresh.rebindStderr;
+      }
+
       // Re-wire message routing and lifecycle on the new process
       this.setupMessageRouting();
       this.setupLifecycle();

package/src/mcpl/tool-policy.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool allow/deny policy for MCPL servers.
+ *
+ * `enabledTools` and `disabledTools` on McplServerConfig hold bare tool names
+ * (no toolPrefix) with `*` substring wildcards. This module owns the predicate
+ * used at both tool-list time and dispatch time.
+ *
+ * Semantics:
+ *   - No fields set                 → all tools allowed.
+ *   - Only enabledTools set         → tool must match at least one pattern.
+ *   - Only disabledTools set        → tool must NOT match any pattern.
+ *   - Both set                      → must match enabledTools AND not match disabledTools.
+ *                                     (deny wins on overlap.)
+ */
+
+/**
+ * Compile a pattern with `*` substring wildcards into a regex.
+ * `*` matches any run of characters (including empty); other characters are literal.
+ */
+function compilePattern(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function anyMatch(patterns: string[], name: string): boolean {
+  for (const p of patterns) {
+    if (compilePattern(p).test(name)) return true;
+  }
+  return false;
+}
+
+export interface ToolPolicy {
+  enabledTools?: string[];
+  disabledTools?: string[];
+}
+
+/**
+ * Returns true if `bareToolName` (server-native name, no prefix) is allowed
+ * under the supplied policy.
+ */
+export function isToolAllowed(bareToolName: string, policy: ToolPolicy | undefined): boolean {
+  if (!policy) return true;
+  const { enabledTools, disabledTools } = policy;
+
+  if (disabledTools && disabledTools.length > 0 && anyMatch(disabledTools, bareToolName)) {
+    return false;
+  }
+  if (enabledTools && enabledTools.length > 0) {
+    return anyMatch(enabledTools, bareToolName);
+  }
+  return true;
+}

package/src/mcpl/types.ts

@@ -180,6 +180,24 @@ export interface McplServerConfig {
   /** Feature sets to explicitly disable on connect */
   disabledFeatureSets?: string[];
 
+  /**
+   * Tool allow-list (bare tool names as the server exports them, no toolPrefix).
+   * Supports `*` as a substring wildcard (e.g. `read_*`, `*_file`, `*`).
+   * If set, only tools matching at least one pattern are exposed.
+   * `disabledTools` takes precedence on conflict.
+   *
+   * Filter is applied in two places: at tool-list time (model never sees the
+   * tool) and at dispatch time (call rejected with a tool-result error, in
+   * case the model imitates a prior call from message history).
+   */
+  enabledTools?: string[];
+
+  /**
+   * Tool deny-list (bare tool names, same wildcard syntax as enabledTools).
+   * Wins over enabledTools on conflict.
+   */
+  disabledTools?: string[];
+
   /** Scope configurations per feature set */
   scopes?: Record<string, ScopeConfig>;
 

package/src/modules/workspace/index.ts

@@ -121,6 +121,8 @@ export class WorkspaceModule implements Module {
         initialSyncDone: false,
         lastMaterializedBranchId: null,
         materializedHashes: new Map(),
+        watcherReadyAt: null,
+        watcherError: null,
       };
       this.mounts.set(mount.name, mountState);
     }
@@ -140,6 +142,9 @@ export class WorkspaceModule implements Module {
           if (mount) {
             mount.lastMaterializedSeq = meta.lastMaterializedSeq;
             mount.lastMaterializedBranchId = meta.lastMaterializedBranchId ?? null;
+            // watcherReadyAt intentionally not restored — each session must
+            // observe its own watcher attach, otherwise a stale timestamp
+            // would hide a new-session attach failure.
           }
         }
       }
@@ -161,9 +166,27 @@ export class WorkspaceModule implements Module {
 
       const watchMode = mount.config.watch ?? 'always';
       if (watchMode === 'always') {
-        const watcher = new MountWatcher(mount.config, (changes) => {
-          this.handleFsChanges(name, changes);
-        });
+        const watcher = new MountWatcher(
+          mount.config,
+          (changes) => {
+            this.handleFsChanges(name, changes);
+          },
+          {
+            onReady: () => {
+              mount.watcherReadyAt = Date.now();
+              mount.watcherError = null;
+            },
+            onError: (err) => {
+              mount.watcherError = err.message;
+              this.ctx?.pushEvent({
+                type: 'workspace:watcher-error',
+                mount: name,
+                path: mount.config.path,
+                error: err.message,
+              } as ProcessEvent);
+            },
+          },
+        );
         watcher.start();
         this.watchers.set(name, watcher);
 
@@ -212,6 +235,8 @@ export class WorkspaceModule implements Module {
         state.mounts[name] = {
           lastMaterializedSeq: mount.lastMaterializedSeq,
           lastMaterializedBranchId: mount.lastMaterializedBranchId ?? undefined,
+          watcherReadyAt: mount.watcherReadyAt,
+          watcherError: mount.watcherError,
         };
       }
       this.ctx.setState(state);
@@ -406,6 +431,21 @@ export class WorkspaceModule implements Module {
   // Path Resolution
   // ==========================================================================
 
+  /**
+   * Resolve a mount-prefixed path (e.g. "tickets/2026-04-22-foo.md") to its
+   * absolute filesystem path. Returns null if the mount is unknown or the
+   * resolved path escapes the mount root (path-traversal guard). Public API
+   * for peer modules that need to read workspace files directly.
+   */
+  resolveAbsolutePath(mountPrefixedPath: string): string | null {
+    try {
+      const { mount, relativePath } = this.parsePath(mountPrefixedPath);
+      return resolve(mount.config.path, relativePath);
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Parse a mount-prefixed path into (mountName, relativePath).
    */

package/src/modules/workspace/types.ts

@@ -94,6 +94,15 @@ export interface MountState {
   lastMaterializedBranchId: string | null;
   /** Per-file hash at time of last materialization — baseline for conflict detection */
   materializedHashes: Map<string, string>;
+  /**
+   * Wall-clock time chokidar emitted `ready` for this mount, or null if the
+   * watcher hasn't finished its initial scan. null after session start =
+   * watcher attach silently failed; a set value with empty tree = attached
+   * to an empty directory.
+   */
+  watcherReadyAt: number | null;
+  /** Most recent chokidar error for this mount, if any. */
+  watcherError: string | null;
 }
 
 /**
@@ -104,6 +113,8 @@ export interface WorkspaceModuleState {
   mounts: Record<string, {
     lastMaterializedSeq: number;
     lastMaterializedBranchId?: string;
+    watcherReadyAt?: number | null;
+    watcherError?: string | null;
   }>;
   /** Branch ID considered "active" for materialization */
   activeBranchId?: string;

package/src/modules/workspace/watcher.ts

@@ -6,6 +6,7 @@
  */
 
 import { watch, type FSWatcher } from 'chokidar';
+import { mkdirSync } from 'node:fs';
 import { type MountConfig } from './types.js';
 
 export type FsOp = 'created' | 'modified' | 'deleted';
@@ -19,6 +20,18 @@ export interface WatcherEvents {
   onChange(changes: FsChange[]): void;
 }
 
+/**
+ * Optional lifecycle callbacks. Without these, chokidar's `ready` and `error`
+ * events are silently dropped — which is how a failed attach can look
+ * identical to an empty directory in the recorded state.
+ */
+export interface WatcherLifecycle {
+  /** Fires once, when chokidar completes its initial scan. */
+  onReady?: () => void;
+  /** Fires on any chokidar-reported error (ENOENT, EACCES, platform faults). */
+  onError?: (err: Error) => void;
+}
+
 /**
  * Manages filesystem watching for a single mount.
  * Handles debouncing, ignore patterns, and write suppression.
@@ -34,14 +47,17 @@ export class MountWatcher {
   private readonly debounceMs: number;
   private readonly config: MountConfig;
   private readonly onChangeCallback: (changes: FsChange[]) => void;
+  private readonly lifecycle: WatcherLifecycle;
 
   constructor(
     config: MountConfig,
     onChange: (changes: FsChange[]) => void,
+    lifecycle: WatcherLifecycle = {},
   ) {
     this.config = config;
     this.debounceMs = config.watchDebounceMs ?? 300;
     this.onChangeCallback = onChange;
+    this.lifecycle = lifecycle;
   }
 
   /**
@@ -50,6 +66,21 @@ export class MountWatcher {
   start(): void {
     if (this.watcher) return;
 
+    // Read-write mounts: ensure the path exists before chokidar attaches.
+    // chokidar 4's fs.watch-based backend silently fails to fire events when
+    // the watched path OR any of its parent directories don't exist at
+    // subscribe time (see case C in the WSL/Linux repro). `ready` still fires,
+    // so the failure is indistinguishable from an empty directory without
+    // this defensive mkdir. Read-only mounts are left alone — creating
+    // directories a user asked us only to read would be surprising.
+    if (this.config.mode === 'read-write') {
+      try {
+        mkdirSync(this.config.path, { recursive: true });
+      } catch (err) {
+        this.lifecycle.onError?.(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+
     const ignored = this.config.ignore ?? [];
 
     this.watcher = watch(this.config.path, {
@@ -79,6 +110,15 @@ export class MountWatcher {
     this.watcher.on('add', handleEvent('created'));
     this.watcher.on('change', handleEvent('modified'));
     this.watcher.on('unlink', handleEvent('deleted'));
+
+    if (this.lifecycle.onReady) {
+      this.watcher.once('ready', this.lifecycle.onReady);
+    }
+    if (this.lifecycle.onError) {
+      this.watcher.on('error', (err) => {
+        this.lifecycle.onError?.(err instanceof Error ? err : new Error(String(err)));
+      });
+    }
   }
 
   /**

package/src/types/trace.ts

@@ -206,6 +206,13 @@ export type TraceEvent =
       agentName: string;
       fromBranch: string;
       toBranch: string;
+    })
+
+  // MCPL subprocess stderr (one trace per line, for receipts when things break)
+  | (TraceEventBase & {
+      type: 'mcpl:server-stderr';
+      serverId: string;
+      line: string;
     });
 
 /**