@animalabs/connectome-host 0.3.1

package/test/subagent-peek-scoping.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Postmortem 2026-05-28 P3 #8: scope `peek` and the `gatherContext` HUD to
+ * the caller's descendants only. Today both surfaces show the global roster:
+ *
+ *   - `peek()` (no arg) returns snapshots for every running subagent in the
+ *      fleet, including peers and cousins of the caller.
+ *   - `peek(name)` accepts any name — there's no descendant check.
+ *   - `gatherContext` iterates `activeSubagents` directly with no parent
+ *      filter, so when the HUD is on the caller's context is injected with
+ *      the full fleet roster every turn.
+ *
+ * This invites a "coordinate with peers" anti-pattern (visible in the
+ * production miner's narration: scouts gossiping about siblings being
+ * zombied) and lets one slow scout's status saturate the orchestrator's
+ * context and trigger retry-storm spawn behavior.
+ *
+ * The fix uses `parentMap` (already maintained for cancelChildren) to walk
+ * descendants. A caller sees only its own subtree — peers and ancestors are
+ * filtered out.
+ */
+import { describe, test, expect } from 'bun:test';
+import {
+  SubagentModule,
+  type ActiveSubagent,
+} from '../src/modules/subagent-module.js';
+
+interface FakeLiveState {
+  frameworkAgentName: string;
+  displayName: string;
+  systemPrompt: string;
+  contextManager: { compile: () => Promise<{ messages: unknown[] }> };
+  currentStream: string;
+  pendingToolCalls: Array<{ name: string; input?: unknown }>;
+  activeCallIds: Set<string>;
+  requestInFlightSince?: number;
+}
+
+/** Build a peek-ready SubagentModule with a tree of subagents wired up:
+ *
+ *      root  ('top')
+ *        ├── child-a   (parent: root)
+ *        │     └── grandchild-a1 (parent: child-a)
+ *        ├── child-b   (parent: root)
+ *        └── peer      (parent: 'other-root') — NOT in the tree
+ *
+ * Caller framework agent names: root = 'fw-top', child-a = 'fw-a',
+ * child-b = 'fw-b', grandchild-a1 = 'fw-a1', peer = 'fw-peer'.
+ */
+function makeTree(): SubagentModule {
+  const mod = new SubagentModule();
+  const privateView = mod as unknown as {
+    liveSubagents: Map<string, FakeLiveState>;
+    frameworkNameIndex: Map<string, string>;
+  };
+
+  const installOne = (displayName: string, frameworkAgentName: string, parent?: string): void => {
+    const live: FakeLiveState = {
+      frameworkAgentName,
+      displayName,
+      systemPrompt: 'test',
+      contextManager: { compile: async () => ({ messages: [] }) },
+      currentStream: '',
+      pendingToolCalls: [],
+      activeCallIds: new Set(),
+    };
+    privateView.liveSubagents.set(displayName, live);
+    privateView.frameworkNameIndex.set(frameworkAgentName, displayName);
+    const entry: ActiveSubagent = {
+      name: displayName,
+      type: 'spawn',
+      task: `task-${displayName}`,
+      status: 'running',
+      startedAt: Date.now(),
+      lastActivityAt: Date.now(),
+      toolCallsCount: 0,
+      findingsCount: 0,
+    };
+    mod.activeSubagents.set(`entry-${displayName}`, entry);
+    if (parent !== undefined) mod.parentMap.set(displayName, parent);
+  };
+
+  installOne('child-a', 'fw-a', 'fw-top');
+  installOne('child-b', 'fw-b', 'fw-top');
+  installOne('grandchild-a1', 'fw-a1', 'fw-a');
+  installOne('peer', 'fw-peer', 'fw-other-root');
+
+  return mod;
+}
+
+describe('SubagentModule peek + HUD descendant scoping (P3 #8)', () => {
+  test('peek() with no name and a caller returns only descendants', async () => {
+    const mod = makeTree();
+    // The top-level caller ('fw-top') owns child-a, child-b, grandchild-a1
+    // (transitively). It does NOT own peer.
+    const callerView = mod as unknown as {
+      handlePeek: (input: { name?: string }, caller?: string) => Promise<{ success: boolean; data: unknown }>;
+    };
+    const result = await callerView.handlePeek({}, 'fw-top');
+    const data = result.data as Array<{ name: string }>;
+    const names = new Set(data.map(s => s.name));
+    expect(names.has('child-a')).toBe(true);
+    expect(names.has('child-b')).toBe(true);
+    expect(names.has('grandchild-a1')).toBe(true);
+    expect(names.has('peer')).toBe(false);
+  });
+
+  test('peek() called by a mid-tree caller scopes to that subtree', async () => {
+    const mod = makeTree();
+    const callerView = mod as unknown as {
+      handlePeek: (input: { name?: string }, caller?: string) => Promise<{ success: boolean; data: unknown }>;
+    };
+    // child-a's subtree is just grandchild-a1 — siblings (child-b) and
+    // cousins (peer) and ancestors (root) must be invisible.
+    const result = await callerView.handlePeek({}, 'fw-a');
+    const data = result.data as Array<{ name: string }>;
+    const names = new Set(data.map(s => s.name));
+    expect(names.has('grandchild-a1')).toBe(true);
+    expect(names.has('child-b')).toBe(false);
+    expect(names.has('peer')).toBe(false);
+    expect(names.has('child-a')).toBe(false); // caller doesn't see itself
+  });
+
+  test('peek(name) on a non-descendant returns empty even if the name exists', async () => {
+    const mod = makeTree();
+    const callerView = mod as unknown as {
+      handlePeek: (input: { name?: string }, caller?: string) => Promise<{ success: boolean; data: unknown }>;
+    };
+    // child-a tries to peek peer (which exists fleet-wide but is not a
+    // descendant of child-a). Should return "no such subagent" from
+    // child-a's perspective.
+    const result = await callerView.handlePeek({ name: 'peer' }, 'fw-a');
+    expect(result.data).toEqual({ message: "No running subagent named 'peer'" });
+  });
+
+  test('peek(name) on a descendant works as before', async () => {
+    const mod = makeTree();
+    const callerView = mod as unknown as {
+      handlePeek: (input: { name?: string }, caller?: string) => Promise<{ success: boolean; data: unknown }>;
+    };
+    const result = await callerView.handlePeek({ name: 'grandchild-a1' }, 'fw-a');
+    const data = result.data as Array<{ name: string }>;
+    expect(data.length).toBe(1);
+    expect(data[0].name).toBe('grandchild-a1');
+  });
+
+  test('peek() without a caller (e.g. internal call) still sees everything', async () => {
+    // Backward compat: not all callers thread an identity through (e.g.
+    // internal observability paths, tests). When no caller is provided, the
+    // descendant filter is bypassed.
+    const mod = makeTree();
+    const all = await mod.peek();
+    expect(all.length).toBe(4); // child-a + child-b + grandchild-a1 + peer
+  });
+
+  test('gatherContext HUD is scoped to descendants of the calling agent', async () => {
+    const mod = makeTree();
+    // Force the HUD on by directly setting the persisted flag's source — the
+    // module checks ctx?.getState().hudEnabled, but in this minimal test
+    // there's no ctx, so the early return at the top of gatherContext would
+    // bail. Pre-fix the function returned [] without ctx; post-fix the
+    // descendant filter must still be exercised. To keep the test focused on
+    // scoping (not on persistence wiring), stub ctx with a hudEnabled=true
+    // state-bag and an empty setState.
+    (mod as unknown as { ctx: unknown }).ctx = {
+      getState: () => ({ hudEnabled: true }),
+      setState: () => {},
+    };
+    const injections = await mod.gatherContext('fw-a');
+    expect(injections.length).toBeGreaterThan(0);
+    const text = (injections[0].content[0] as { text: string }).text;
+    // Each HUD line begins with two spaces then the subagent name and ' [type]'.
+    // Anchor on that to avoid substring collisions (grandchild-a1 contains
+    // the literal 'child-a' as a substring, which would make a naïve
+    // includes() check false-positive).
+    expect(text).toMatch(/^\s*grandchild-a1 \[/m);
+    expect(text).not.toMatch(/^\s*child-b \[/m);
+    expect(text).not.toMatch(/^\s*peer \[/m);
+    expect(text).not.toMatch(/^\s*child-a \[/m); // caller's own entry not surfaced
+  });
+});

package/test/subagent-peek-zombie.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Postmortem 2026-05-28 F2: dual-clock zombie bug in SubagentModule.
+ *
+ * The reaper (reclaimZombieSlots) was correctly updated to use `lastActivityAt`
+ * — the merciful clock that distinguishes "long-running but progressing" from
+ * "silently stuck." The peek observability surface (peekOne / isZombie field)
+ * still uses `startedAt`, which flags ANY subagent older than 30s as a zombie
+ * the moment it's between tokens.
+ *
+ * This false positive saturates orchestrator context: scouts narrate about
+ * peer zombies, the orchestrator re-spawns them as -retryN, abandoned
+ * originals get aborted, the admin UI paints them red. The reap doesn't even
+ * have to happen for the symptom to manifest.
+ *
+ * These tests assert the merciful (lastActivityAt-based) semantics from peek's
+ * point of view. Each test seeds the module's private maps directly to keep
+ * the surface small — `peek()` does not need a full framework / context-manager
+ * stack to exercise the predicate.
+ */
+import { describe, test, expect } from 'bun:test';
+import { SubagentModule, type ActiveSubagent } from '../src/modules/subagent-module.js';
+
+interface FakeLiveState {
+  frameworkAgentName: string;
+  displayName: string;
+  systemPrompt: string;
+  contextManager: { compile: () => Promise<{ messages: unknown[] }> };
+  currentStream: string;
+  pendingToolCalls: Array<{ name: string; input?: unknown }>;
+  activeCallIds: Set<string>;
+}
+
+/** Build a peek-ready SubagentModule with one synthetic subagent installed. */
+function makeModuleWithSubagent(opts: {
+  displayName: string;
+  startedAt: number;
+  lastActivityAt: number;
+  currentStream?: string;
+  pendingToolCalls?: Array<{ name: string; input?: unknown }>;
+  status?: 'running' | 'completed' | 'failed';
+}): SubagentModule {
+  const mod = new SubagentModule();
+  const live: FakeLiveState = {
+    frameworkAgentName: `fw-${opts.displayName}`,
+    displayName: opts.displayName,
+    systemPrompt: 'test',
+    // Minimal stub — peekOne wraps compile() in try/catch and treats failures as
+    // "context manager mid-modification, return what we have," so this is fine.
+    contextManager: { compile: async () => ({ messages: [] }) },
+    currentStream: opts.currentStream ?? '',
+    pendingToolCalls: opts.pendingToolCalls ?? [],
+    activeCallIds: new Set(),
+  };
+  const entry: ActiveSubagent = {
+    name: opts.displayName,
+    type: 'spawn',
+    task: 'test-task',
+    status: opts.status ?? 'running',
+    startedAt: opts.startedAt,
+    lastActivityAt: opts.lastActivityAt,
+    toolCallsCount: 0,
+    findingsCount: 0,
+  };
+
+  // `liveSubagents` is private — go around the visibility modifier. The map is
+  // the canonical source for peek; we keep the test's surface minimal by
+  // skipping the spawn/fork wiring.
+  (mod as unknown as { liveSubagents: Map<string, FakeLiveState> }).liveSubagents.set(
+    opts.displayName,
+    live,
+  );
+  // activeSubagents is `readonly` (re-binding the Map is what's forbidden), so
+  // mutating it directly is fine.
+  mod.activeSubagents.set(`entry-${opts.displayName}`, entry);
+  return mod;
+}
+
+describe('SubagentModule.peek — F2 dual-clock zombie predicate', () => {
+  test('healthy long-running scout is NOT zombie (lastActivityAt fresh)', async () => {
+    // Productive scout 5 minutes in, last bumped activity 5s ago, currently
+    // between an inference round and its first token. Pre-fix: peek reports
+    // isZombie=true because elapsedMs from startedAt is 5min > 30s. Post-fix:
+    // peek consults lastActivityAt, sees fresh activity, reports isZombie=false.
+    const now = Date.now();
+    const mod = makeModuleWithSubagent({
+      displayName: 'scout',
+      startedAt: now - 5 * 60_000,
+      lastActivityAt: now - 5_000,
+    });
+    const [snap] = await mod.peek('scout');
+    expect(snap).toBeDefined();
+    expect(snap!.isZombie).toBe(false);
+  });
+
+  test('genuinely stuck subagent IS zombie (lastActivityAt stale, no stream/tools)', async () => {
+    // Activity stopped 5 minutes ago with no current stream and no pending
+    // tools — the case the reaper exists to catch. Silence picked well above
+    // both 30s (old) and 120s (post-F3) thresholds so the test stays valid
+    // regardless of future threshold tuning.
+    const now = Date.now();
+    const mod = makeModuleWithSubagent({
+      displayName: 'stuck',
+      startedAt: now - 10 * 60_000,
+      lastActivityAt: now - 5 * 60_000,
+    });
+    const [snap] = await mod.peek('stuck');
+    expect(snap!.isZombie).toBe(true);
+  });
+
+  test('subagent currently streaming is NOT zombie even with old lastActivityAt', async () => {
+    // currentStream non-empty short-circuits the predicate regardless of clocks.
+    const now = Date.now();
+    const mod = makeModuleWithSubagent({
+      displayName: 'streaming',
+      startedAt: now - 10 * 60_000,
+      lastActivityAt: now - 5 * 60_000,
+      currentStream: 'tokens flowing',
+    });
+    const [snap] = await mod.peek('streaming');
+    expect(snap!.isZombie).toBe(false);
+  });
+
+  test('subagent with pending tool calls is NOT zombie', async () => {
+    // pendingToolCalls non-empty also short-circuits — agent is awaiting tool
+    // results, not stuck.
+    const now = Date.now();
+    const mod = makeModuleWithSubagent({
+      displayName: 'awaiting-tools',
+      startedAt: now - 10 * 60_000,
+      lastActivityAt: now - 5 * 60_000,
+      pendingToolCalls: [{ name: 'files--read', input: { path: '/x' } }],
+    });
+    const [snap] = await mod.peek('awaiting-tools');
+    expect(snap!.isZombie).toBe(false);
+  });
+
+  test('completed subagent is never reported as zombie', async () => {
+    const now = Date.now();
+    const mod = makeModuleWithSubagent({
+      displayName: 'done',
+      startedAt: now - 10 * 60_000,
+      lastActivityAt: now - 5 * 60_000,
+      status: 'completed',
+    });
+    const [snap] = await mod.peek('done');
+    expect(snap!.isZombie).toBe(false);
+  });
+});

package/test/subagent-reaper-in-flight.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Postmortem 2026-05-28 F3: reaper's guard does not cover the
+ * "request in flight, awaiting first token" window.
+ *
+ * Today's reap guard is `!live.currentStream && pendingToolCalls.length === 0`.
+ * At inference:started and inference:stream_resumed, both are cleared. The
+ * agent then sits with the guard open while the next LLM request is on the
+ * wire. With Opus on 100–165K-token contexts under rate-limited MCP tools,
+ * single-round TTFT routinely exceeds 30s, and the periodic reaper executes
+ * mid-request even though the agent is genuinely progressing.
+ *
+ * Forensic signature in production: every reaped scout's last message in the
+ * Chronicle store is an unconsumed `tool_result` — i.e., tool results came
+ * back, stream_resumed cleared the guards, the next request was dispatched,
+ * the reaper struck before the first token.
+ *
+ * Tests:
+ *   1) reaper does NOT cancel an entry with `requestInFlightSince` set, even
+ *      when lastActivityAt is older than the threshold.
+ *   2) reaper DOES cancel a genuinely silent entry (control — proves the
+ *      threshold path is still alive).
+ *   3) Lifecycle: trace events set/clear `requestInFlightSince` on the live
+ *      subagent state via the module's onTrace handler.
+ */
+import { describe, test, expect } from 'bun:test';
+import {
+  SubagentModule,
+  type ActiveSubagent,
+} from '../src/modules/subagent-module.js';
+import type { TraceEvent } from '@animalabs/agent-framework';
+
+interface FakeLiveState {
+  frameworkAgentName: string;
+  displayName: string;
+  systemPrompt: string;
+  contextManager: { compile: () => Promise<{ messages: unknown[] }> };
+  currentStream: string;
+  pendingToolCalls: Array<{ name: string; input?: unknown }>;
+  activeCallIds: Set<string>;
+  /** Populated when an inference request has been dispatched but no token
+   *  has arrived yet. The reaper must treat this as a protected state. */
+  requestInFlightSince?: number;
+}
+
+function installSubagent(
+  mod: SubagentModule,
+  opts: {
+    displayName: string;
+    frameworkAgentName?: string;
+    startedAt: number;
+    lastActivityAt: number;
+    currentStream?: string;
+    pendingToolCalls?: Array<{ name: string; input?: unknown }>;
+    requestInFlightSince?: number;
+    status?: 'running' | 'completed' | 'failed';
+  },
+): { live: FakeLiveState; entry: ActiveSubagent } {
+  const frameworkAgentName = opts.frameworkAgentName ?? `fw-${opts.displayName}`;
+  const live: FakeLiveState = {
+    frameworkAgentName,
+    displayName: opts.displayName,
+    systemPrompt: 'test',
+    contextManager: { compile: async () => ({ messages: [] }) },
+    currentStream: opts.currentStream ?? '',
+    pendingToolCalls: opts.pendingToolCalls ?? [],
+    activeCallIds: new Set(),
+    requestInFlightSince: opts.requestInFlightSince,
+  };
+  const entry: ActiveSubagent = {
+    name: opts.displayName,
+    type: 'spawn',
+    task: 'test-task',
+    status: opts.status ?? 'running',
+    startedAt: opts.startedAt,
+    lastActivityAt: opts.lastActivityAt,
+    toolCallsCount: 0,
+    findingsCount: 0,
+  };
+  const privateView = mod as unknown as {
+    liveSubagents: Map<string, FakeLiveState>;
+    frameworkNameIndex: Map<string, string>;
+  };
+  privateView.liveSubagents.set(opts.displayName, live);
+  privateView.frameworkNameIndex.set(frameworkAgentName, opts.displayName);
+  mod.activeSubagents.set(`entry-${opts.displayName}`, entry);
+  return { live, entry };
+}
+
+/** Captures the trace handler that SubagentModule.setFramework registers, so
+ *  the lifecycle test can fire events without spinning up the full framework. */
+function makeTraceCapturingFramework(): {
+  framework: { onTrace: (cb: (e: TraceEvent) => void) => void };
+  fire: (event: TraceEvent) => void;
+} {
+  let captured: ((e: TraceEvent) => void) | null = null;
+  return {
+    framework: {
+      onTrace(cb: (e: TraceEvent) => void) {
+        captured = cb;
+      },
+    },
+    fire(event: TraceEvent) {
+      if (!captured) throw new Error('onTrace was never called');
+      captured(event);
+    },
+  };
+}
+
+describe('SubagentModule reaper — F3 request-in-flight protection', () => {
+  test('reaper does NOT cancel an agent with a request in flight', () => {
+    // Postmortem scenario: stream_resumed fired, currentStream + pendingToolCalls
+    // cleared, the next LLM round is on the wire. lastActivityAt is frozen at
+    // the moment of stream_resumed dispatch. TTFT is 45s — pre-fix the reaper
+    // would strike mid-request because all of (!currentStream, no pending tools,
+    // silentMs > threshold) hold. With the in-flight guard, the agent is left
+    // alone.
+    const now = Date.now();
+    const mod = new SubagentModule();
+    const { entry } = installSubagent(mod, {
+      displayName: 'opus-in-flight',
+      startedAt: now - 5 * 60_000,
+      lastActivityAt: now - 3 * 60_000,        // well past any threshold
+      requestInFlightSince: now - 3 * 60_000,  // request dispatched, no token yet
+    });
+
+    const reclaimed = (mod as unknown as { reclaimZombieSlots: () => number })
+      .reclaimZombieSlots();
+
+    expect(reclaimed).toBe(0);
+    expect(entry.status).toBe('running');
+  });
+
+  test('reaper DOES cancel a genuinely silent agent (control)', () => {
+    // Same staleness, but no request in flight — this is the "stuck" case the
+    // reaper exists to clean up. 5 min silence exceeds both the pre- and
+    // post-fix thresholds, so this test stays valid if the threshold is
+    // tuned in either direction.
+    const now = Date.now();
+    const mod = new SubagentModule();
+    const { entry } = installSubagent(mod, {
+      displayName: 'genuinely-stuck',
+      startedAt: now - 10 * 60_000,
+      lastActivityAt: now - 5 * 60_000,
+    });
+
+    const reclaimed = (mod as unknown as { reclaimZombieSlots: () => number })
+      .reclaimZombieSlots();
+
+    expect(reclaimed).toBe(1);
+    // Postmortem 2026-05-28 P1 #4: zombie-reaped subagents land in
+    // 'cancelled' (terminal-but-benign), not 'failed'. Aligns the
+    // SubagentModule's terminal state with the reducer's split between
+    // genuine faults (inference:failed) and benign cancels.
+    expect(entry.status).toBe('cancelled');
+  });
+
+  test('peek.isZombie also respects requestInFlightSince', async () => {
+    // The peek surface drives the orchestrator's perception. Postmortem F2 was
+    // about dual clocks; F3 is the same shape: a healthy in-flight agent must
+    // not report isZombie=true.
+    const now = Date.now();
+    const mod = new SubagentModule();
+    installSubagent(mod, {
+      displayName: 'opus-in-flight',
+      startedAt: now - 5 * 60_000,
+      lastActivityAt: now - 3 * 60_000,
+      requestInFlightSince: now - 3 * 60_000,
+    });
+    const [snap] = await mod.peek('opus-in-flight');
+    expect(snap!.isZombie).toBe(false);
+  });
+
+  test('lifecycle: inference:started sets requestInFlightSince', () => {
+    const now = Date.now();
+    const mod = new SubagentModule();
+    const { live } = installSubagent(mod, {
+      displayName: 'lc',
+      frameworkAgentName: 'fw-lc',
+      startedAt: now - 10_000,
+      lastActivityAt: now - 10_000,
+    });
+    expect(live.requestInFlightSince).toBeUndefined();
+
+    const fake = makeTraceCapturingFramework();
+    // setFramework registers the onTrace handler. Cast: our fake satisfies the
+    // surface SubagentModule uses at registration time.
+    mod.setFramework(fake.framework as never);
+
+    fake.fire({ type: 'inference:started', agentName: 'fw-lc', timestamp: Date.now() } as never);
+    expect(typeof live.requestInFlightSince).toBe('number');
+  });
+
+  test('lifecycle: first inference:tokens clears requestInFlightSince', () => {
+    const now = Date.now();
+    const mod = new SubagentModule();
+    const { live } = installSubagent(mod, {
+      displayName: 'lc2',
+      frameworkAgentName: 'fw-lc2',
+      startedAt: now - 10_000,
+      lastActivityAt: now - 10_000,
+      requestInFlightSince: now - 5_000,
+    });
+
+    const fake = makeTraceCapturingFramework();
+    mod.setFramework(fake.framework as never);
+
+    fake.fire({ type: 'inference:tokens', agentName: 'fw-lc2', content: 'hello', timestamp: Date.now() } as never);
+    expect(live.requestInFlightSince).toBeUndefined();
+  });
+
+  test('lifecycle: inference:stream_resumed sets requestInFlightSince again', () => {
+    // After a tool round, the framework emits stream_resumed and dispatches a
+    // new request. This is the gap the postmortem traced reaps to.
+    const now = Date.now();
+    const mod = new SubagentModule();
+    const { live } = installSubagent(mod, {
+      displayName: 'lc3',
+      frameworkAgentName: 'fw-lc3',
+      startedAt: now - 60_000,
+      lastActivityAt: now - 60_000,
+    });
+
+    const fake = makeTraceCapturingFramework();
+    mod.setFramework(fake.framework as never);
+
+    fake.fire({ type: 'inference:stream_resumed', agentName: 'fw-lc3', timestamp: Date.now() } as never);
+    expect(typeof live.requestInFlightSince).toBe('number');
+  });
+});

package/test/subscription-gc-module.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect } from 'bun:test';
+import { SubscriptionGcModule } from '../src/modules/subscription-gc-module.js';
+import type { ModuleContext, ProcessEvent, ProcessState } from '@animalabs/agent-framework';
+
+function mockCtx() {
+  let state: unknown = null;
+  const traceListeners: Array<(e: { type: string; agentName?: string }) => void> = [];
+  const toolCalls: Array<{ name: string; input: Record<string, unknown> }> = [];
+  const ctx = {
+    getState: () => state,
+    setState: (s: unknown) => {
+      state = s;
+    },
+    onTrace: (l: (e: { type: string }) => void) => {
+      traceListeners.push(l);
+      return () => {};
+    },
+    callTool: async (call: { name: string; input: Record<string, unknown> }) => {
+      toolCalls.push(call);
+      return { success: true, data: {}, isError: false };
+    },
+  } as unknown as ModuleContext;
+  return { ctx, traceListeners, toolCalls, getState: () => state };
+}
+
+function ambient(
+  channelId: string,
+  text: string,
+  opts: { isMention?: boolean; isDM?: boolean; serverId?: string } = {},
+): ProcessEvent {
+  return {
+    type: 'mcpl:push-event',
+    serverId: opts.serverId ?? 'discord',
+    featureSet: 'discord.messaging',
+    eventId: 'e1',
+    content: [{ type: 'text', text }],
+    origin: {
+      source: 'discord',
+      channelId,
+      isMention: !!opts.isMention,
+      isDM: !!opts.isDM,
+    },
+    timestamp: '2026-01-01T00:00:00Z',
+    inferenceId: 'i1',
+  } as unknown as ProcessEvent;
+}
+
+const PS = {} as ProcessState;
+
+describe('SubscriptionGcModule', () => {
+  test('auto-unsubscribes when ambient crosses the limit', async () => {
+    const m = new SubscriptionGcModule({ defaultLimitChars: 10, serverId: 'discord' });
+    const { ctx, toolCalls } = mockCtx();
+    await m.start(ctx);
+
+    let r = await m.onProcess(ambient('c1', 'abcdef'), PS); // 6 — under
+    expect(toolCalls.length).toBe(0);
+    expect(r.addMessages).toBeUndefined();
+
+    r = await m.onProcess(ambient('c1', 'ghijkl'), PS); // +6 = 12 > 10 → unsub
+    expect(toolCalls.length).toBe(1);
+    expect(toolCalls[0].name).toBe('mcpl--discord--unsubscribe_channel');
+    expect(toolCalls[0].input.channelId).toBe('c1');
+    expect(r.addMessages?.length).toBe(1);
+
+    await m.stop();
+  });
+
+  test('does not count mentions, DMs, or other servers', async () => {
+    const m = new SubscriptionGcModule({ defaultLimitChars: 5 });
+    const { ctx, toolCalls } = mockCtx();
+    await m.start(ctx);
+
+    await m.onProcess(ambient('c1', 'longmention', { isMention: true }), PS);
+    await m.onProcess(ambient('c1', 'longdm', { isDM: true }), PS);
+    await m.onProcess(ambient('c1', 'otherserver', { serverId: 'slack' }), PS);
+    expect(toolCalls.length).toBe(0);
+
+    await m.stop();
+  });
+
+  test('an activation resets all counters', async () => {
+    const m = new SubscriptionGcModule({ defaultLimitChars: 10 });
+    const { ctx, traceListeners, toolCalls } = mockCtx();
+    await m.start(ctx);
+
+    await m.onProcess(ambient('c1', 'abcdefgh'), PS); // 8 — under
+    traceListeners[0]({ type: 'inference:started', agentName: 'lena' }); // reset
+    await m.onProcess(ambient('c1', 'abcdefgh'), PS); // 8 again, not 16 → no unsub
+    expect(toolCalls.length).toBe(0);
+
+    await m.stop();
+  });
+
+  test('"off" override pins a channel; counters persist across restart', async () => {
+    const m = new SubscriptionGcModule({ defaultLimitChars: 5 });
+    const { ctx, toolCalls, getState } = mockCtx();
+    await m.start(ctx);
+
+    await m.handleToolCall({
+      id: 't1',
+      name: 'set_channel_idle_limit',
+      input: { channelId: 'c1', limit: 'off' },
+    });
+    await m.onProcess(ambient('c1', 'waytoolongambient'), PS);
+    expect(toolCalls.length).toBe(0); // pinned → never unsubscribed
+
+    // A different channel still accrues, and state is persisted.
+    await m.onProcess(ambient('c2', 'abc'), PS);
+    const persisted = getState() as { overrides: Record<string, unknown>; counters: Record<string, number> };
+    expect(persisted.overrides.c1).toBe('off');
+
+    // Simulate restart: a new module loads the persisted state (counters carry
+    // across — a restart is not an activation).
+    const m2 = new SubscriptionGcModule({ defaultLimitChars: 5 });
+    const restart = mockCtx();
+    // Feed the prior persisted state into the "restarted" module.
+    const ctx2 = {
+      getState: () => persisted,
+      setState: () => {},
+      onTrace: () => () => {},
+      callTool: async (c: { name: string; input: Record<string, unknown> }) => {
+        restart.toolCalls.push(c);
+        return { success: true, data: {}, isError: false };
+      },
+    } as unknown as ModuleContext;
+    await m2.start(ctx2);
+    // c2 was at 3; +3 = 6 > 5 → unsubscribe (counter survived the "restart")
+    await m2.onProcess(ambient('c2', 'def'), PS);
+    expect(restart.toolCalls.length).toBe(1);
+    expect(restart.toolCalls[0].input.channelId).toBe('c2');
+
+    await m.stop();
+    await m2.stop();
+  });
+});