pi-watchdog-supervisor 0.1.0

package/src/tools.ts

@@ -0,0 +1,289 @@
+import { Type } from 'typebox';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { mergeConfig, pickKnownConfig } from './config.ts';
+import { detectStuck, shouldAlert } from './detector.ts';
+import type { AlertSeverity, WatchdogStore } from './store.ts';
+import type { TargetRegistry } from './registry.ts';
+import type { SubagentsIntegration } from './integrations/gotgenes-subagents.ts';
+import type { StuckAnalysis, WatchdogConfig, WatchdogEvent } from './types.ts';
+
+export type ToolDeps = {
+  store: WatchdogStore;
+  registry: TargetRegistry;
+  getIntegration: () => Promise<SubagentsIntegration>;
+  baseConfig: WatchdogConfig;
+  now: () => number;
+};
+
+const TERMINAL_STATUSES = new Set(['completed', 'aborted', 'stopped', 'error']);
+
+const effectiveConfig = (deps: ToolDeps): WatchdogConfig =>
+  mergeConfig(deps.baseConfig, deps.store.getConfigOverride());
+
+const effectiveRescueMessage = (deps: ToolDeps): string =>
+  deps.store.getRescueMessage() ?? effectiveConfig(deps).rescueMessage;
+
+const analyzeTarget = (deps: ToolDeps, targetKey: string): StuckAnalysis =>
+  detectStuck(
+    deps.store.getEvents(targetKey),
+    effectiveConfig(deps),
+    deps.now(),
+    deps.store.getLastAlert(targetKey)?.at ?? 0,
+  );
+
+// Pull the repeat count out of the repeated_llm_* evidence summaries
+const repeatedMessageCount = (analysis: StuckAnalysis): number => {
+  const counts = analysis.evidence
+    .filter((item) => item.type === 'repeated_llm_input' || item.type === 'repeated_llm_output')
+    .map((item) => Number(item.summary.match(/repeated (\d+) times/)?.[1] ?? 0));
+  return Math.max(0, ...counts);
+};
+
+export const executeListTargets = async (
+  deps: ToolDeps,
+  input: { includeCompleted?: boolean },
+): Promise<string> => {
+  const integration = await deps.getIntegration();
+  if (!integration.available) {
+    return `targets unavailable: ${integration.reason}`;
+  }
+  deps.registry.syncFromRecords(integration.listAgents());
+  const targets = deps.registry
+    .list()
+    .filter((target) => input.includeCompleted === true || !TERMINAL_STATUSES.has(target.status))
+    .map((target) => {
+      const key = deps.store.resolveTargetKey(target.id);
+      const analysis = key ? analyzeTarget(deps, key) : undefined;
+      return {
+        id: target.id,
+        name: target.name,
+        kind: target.kind,
+        status: target.status,
+        lastActiveAt: new Date(target.lastActiveAt).toISOString(),
+        toolCallCount: target.toolCallCount,
+        patchCount: key
+          ? deps.store.getEvents(key).filter((event) => event.type === 'edit').length
+          : 0,
+        repeatedMessageCount: analysis ? repeatedMessageCount(analysis) : 0,
+        likelyStuck: analysis?.likelyStuck ?? false,
+      };
+    });
+  return JSON.stringify({ targets }, null, 2);
+};
+
+export const executeReadEvents = (
+  deps: ToolDeps,
+  input: { targetId: string; limit?: number },
+): string => {
+  const key = deps.store.resolveTargetKey(input.targetId);
+  if (!key) {
+    return `Unknown target: ${input.targetId}`;
+  }
+  const events = deps.store.getEvents(key, input.limit ?? 50);
+  return JSON.stringify({ targetId: key, events }, null, 2);
+};
+
+export const executeDetectStuck = (deps: ToolDeps, input: { targetId: string }): string => {
+  const key = deps.store.resolveTargetKey(input.targetId);
+  if (!key) {
+    return `Unknown target: ${input.targetId}`;
+  }
+  const analysis = analyzeTarget(deps, key);
+  return JSON.stringify(
+    {
+      targetId: key,
+      likelyStuck: analysis.likelyStuck,
+      confidence: analysis.confidence,
+      reasons: analysis.reasons,
+      evidence: analysis.evidence,
+      evidenceKey: analysis.evidenceKey,
+      suggestedRescueMessage: effectiveRescueMessage(deps),
+    },
+    null,
+    2,
+  );
+};
+
+export const formatAlert = (
+  targetId: string,
+  analysis: Pick<StuckAnalysis, 'likelyStuck' | 'confidence' | 'evidence'>,
+  events: WatchdogEvent[],
+  note: string,
+  rescueMessage?: string,
+): string => {
+  const lastCommand = [...events].reverse().find((event) => event.commandKey)?.commandKey;
+  const evidenceLines =
+    analysis.evidence.length > 0
+      ? analysis.evidence.map((item) => `- ${item.summary}`).join('\n')
+      : '- (no deterministic evidence; reported by watchdog agent)';
+  return [
+    '[Watchdog Alert]',
+    '',
+    `Target: ${targetId}`,
+    `Status: ${analysis.likelyStuck ? 'likely stuck' : 'reported by watchdog'}`,
+    `Confidence: ${analysis.confidence}`,
+    '',
+    'Evidence:',
+    evidenceLines,
+    '',
+    'Note:',
+    note,
+    '',
+    'Last command:',
+    lastCommand ?? '(none recorded)',
+    '',
+    'Suggested rescue:',
+    rescueMessage ?? '',
+  ].join('\n');
+};
+
+export const executeAlertMain = (
+  deps: ToolDeps,
+  input: { targetId: string; message: string; severity?: AlertSeverity },
+): string => {
+  if (deps.store.isPaused()) {
+    return 'alert suppressed (watchdog paused)';
+  }
+  const key = deps.store.resolveTargetKey(input.targetId) ?? input.targetId;
+  const config = effectiveConfig(deps);
+  const now = deps.now();
+  const analysis = analyzeTarget(deps, key);
+  if (
+    analysis.likelyStuck &&
+    !shouldAlert(deps.store.getLastAlert(key), analysis, now, config.cooldownSec)
+  ) {
+    return 'alert suppressed (cooldown)';
+  }
+  const alert = formatAlert(
+    key,
+    analysis,
+    deps.store.getEvents(key),
+    input.message,
+    effectiveRescueMessage(deps),
+  );
+  if (!deps.store.alert(alert, input.severity ?? 'warning')) {
+    return 'alert failed: no alert sink registered (is the main session running this extension?)';
+  }
+  if (analysis.likelyStuck) {
+    deps.store.recordAlert(key, analysis.evidenceKey, now);
+  }
+  return `alert sent to main session (severity=${input.severity ?? 'warning'})`;
+};
+
+export const executeSteerSubagent = async (
+  deps: ToolDeps,
+  input: { targetId: string; message?: string; dryRun?: boolean },
+): Promise<string> => {
+  const message = input.message ?? effectiveRescueMessage(deps);
+  const config = effectiveConfig(deps);
+  // Explicit dryRun wins; otherwise use steerDryRunDefault (null = dry-run)
+  const dryRun = input.dryRun ?? config.steerDryRunDefault ?? true;
+  if (dryRun) {
+    return `dry-run: would steer ${input.targetId} with:\n${message}`;
+  }
+  if (config.alertMode === 'main_only') {
+    return `steer refused: alertMode is main_only — update config (alertMode: direct_subagent or both) to allow direct steering`;
+  }
+  const agentId = deps.store.resolveAgentId(input.targetId);
+  if (!agentId) {
+    return `Unknown target: ${input.targetId} (no linked agent id)`;
+  }
+  const integration = await deps.getIntegration();
+  if (!integration.available) {
+    return `steer unavailable: ${integration.reason}`;
+  }
+  const ok = await integration.steer(agentId, message);
+  return ok ? `steered ${agentId} with rescue message` : `steer failed for ${agentId}`;
+};
+
+export const executeConfig = (
+  deps: ToolDeps,
+  input: { action: 'get' | 'set'; config?: Partial<WatchdogConfig> },
+): string => {
+  if (input.action === 'set') {
+    deps.store.setConfigOverride(pickKnownConfig((input.config ?? {}) as Record<string, unknown>));
+  }
+  return JSON.stringify(effectiveConfig(deps), null, 2);
+};
+
+const text = (value: string) => ({ content: [{ type: 'text' as const, text: value }], details: undefined });
+
+export const registerWatchdogTools = (pi: ExtensionAPI, deps: ToolDeps) => {
+  pi.registerTool({
+    name: 'watchdog_list_targets',
+    label: 'Watchdog: list targets',
+    description:
+      'List sub-agents visible to the watchdog with status and stuck signals. Completed agents are excluded unless includeCompleted is true.',
+    parameters: Type.Object({
+      includeCompleted: Type.Optional(Type.Boolean()),
+    }),
+    execute: async (_id, params) => text(await executeListTargets(deps, params)),
+  });
+
+  pi.registerTool({
+    name: 'watchdog_read_events',
+    label: 'Watchdog: read events',
+    description: 'Read compact recent events (commands, output hashes, edits) for one target.',
+    parameters: Type.Object({
+      targetId: Type.String(),
+      limit: Type.Optional(Type.Number()),
+    }),
+    execute: async (_id, params) => text(executeReadEvents(deps, params)),
+  });
+
+  pi.registerTool({
+    name: 'watchdog_detect_stuck',
+    label: 'Watchdog: detect stuck',
+    description:
+      'Run deterministic stuck analysis for one target: repeated LLM input/output message bodies, idle without progress.',
+    parameters: Type.Object({
+      targetId: Type.String(),
+    }),
+    execute: async (_id, params) => text(executeDetectStuck(deps, params)),
+  });
+
+  pi.registerTool({
+    name: 'watchdog_alert_main',
+    label: 'Watchdog: alert main session',
+    description:
+      'Send a compact stuck alert to the main agent session. Respects pause state and per-target cooldown.',
+    parameters: Type.Object({
+      targetId: Type.String(),
+      message: Type.String(),
+      severity: Type.Optional(
+        Type.Union([Type.Literal('info'), Type.Literal('warning'), Type.Literal('critical')]),
+      ),
+    }),
+    execute: async (_id, params) => text(executeAlertMain(deps, params)),
+  });
+
+  pi.registerTool({
+    name: 'watchdog_steer_subagent',
+    label: 'Watchdog: steer sub-agent',
+    description:
+      'Send a rescue message to a target sub-agent. Defaults to dry-run (configurable via steerDryRunDefault); real steering requires alertMode other than main_only.',
+    parameters: Type.Object({
+      targetId: Type.String(),
+      message: Type.Optional(Type.String()),
+      dryRun: Type.Optional(Type.Boolean()),
+    }),
+    execute: async (_id, params) => text(await executeSteerSubagent(deps, params)),
+  });
+
+  pi.registerTool({
+    name: 'watchdog_config',
+    label: 'Watchdog: config',
+    description: 'Read or update the watchdog policy (thresholds, cooldown, alertMode, rescue message).',
+    parameters: Type.Object({
+      action: Type.Union([Type.Literal('get'), Type.Literal('set')]),
+      config: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    }),
+    execute: async (_id, params) =>
+      text(
+        executeConfig(deps, {
+          action: params.action,
+          config: params.config as Partial<WatchdogConfig> | undefined,
+        }),
+      ),
+  });
+};

package/src/types.ts

@@ -0,0 +1,80 @@
+export type AlertMode = 'main_only' | 'direct_subagent' | 'both';
+
+export type TargetKind = 'task' | 'watchdog' | 'unknown';
+
+export type TargetStatus =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'steered'
+  | 'aborted'
+  | 'stopped'
+  | 'error';
+
+export type WatchdogTarget = {
+  id: string;
+  name?: string;
+  kind: TargetKind;
+  status: TargetStatus;
+  toolCallCount: number;
+  createdAt: number;
+  lastActiveAt: number;
+};
+
+export type WatchdogEventType =
+  | 'subagent_created'
+  | 'subagent_started'
+  | 'subagent_completed'
+  | 'subagent_failed'
+  | 'tool_call'
+  | 'tool_result'
+  | 'edit'
+  | 'llm_input'
+  | 'llm_output';
+
+export type WatchdogEvent = {
+  id: string;
+  targetId: string;
+  at: number;
+  type: WatchdogEventType;
+  summary: string;
+  commandKey?: string;
+  outputHash?: string;
+  outputPreview?: string;
+};
+
+export type StuckEvidenceType =
+  | 'repeated_llm_input'
+  | 'repeated_llm_output'
+  | 'idle_no_progress';
+
+export type StuckEvidence = {
+  type: StuckEvidenceType;
+  summary: string;
+};
+
+export type StuckAnalysis = {
+  likelyStuck: boolean;
+  confidence: 'low' | 'medium' | 'high';
+  reasons: string[];
+  evidence: StuckEvidence[];
+  evidenceKey: string;
+};
+
+export type WatchdogConfig = {
+  enabled: boolean;
+  rescueMessage: string;
+  // Identical (normalized) LLM message bodies in a row to count as a loop; 0 disables
+  llmRepeatThreshold: number;
+  idleNoProgressSec: number;
+  cooldownSec: number;
+  maxPreviewLines: number;
+  maxEventsPerAgent: number;
+  alertMode: AlertMode;
+  // Default for watchdog_steer_subagent's dryRun when the call omits it;
+  // null keeps the built-in safe default (dry-run)
+  steerDryRunDefault: boolean | null;
+  // Show the lm-debug console below the editor with the full latest
+  // sent/received LLM messages (newlines preserved, untruncated)
+  debug: boolean;
+};

package/test/checker.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { DEFAULT_CONFIG } from '../src/config.ts';
+import { getOrCreateStore, resetStoreForTest } from '../src/store.ts';
+import { createStuckChecker, type SendMessageLike } from '../src/checker.ts';
+
+const SESSION = 'sess-main';
+
+type SentMessage = { message: Record<string, unknown>; options: Record<string, unknown> };
+
+const makePi = (sent: SentMessage[]): SendMessageLike => ({
+  sendMessage: (message, options) => {
+    sent.push({ message: message as Record<string, unknown>, options: options as Record<string, unknown> });
+  },
+});
+
+const feedRepeatedResults = (
+  store: ReturnType<typeof getOrCreateStore>,
+  times: number,
+  baseAt = Date.now() - times * 1000,
+) => {
+  for (let i = 0; i < times; i += 1) {
+    store.appendEvent(SESSION, {
+      at: baseAt + i * 1000,
+      type: 'llm_output',
+      summary: 'llm_output: same body',
+      commandKey: 'llm_output',
+      outputHash: 'hash-same',
+    });
+  }
+};
+
+describe('createStuckChecker', () => {
+  afterEach(() => {
+    resetStoreForTest();
+  });
+
+  it('sends a steer rescue message when stuck is detected', () => {
+    const store = getOrCreateStore(50);
+    const sent: SentMessage[] = [];
+    feedRepeatedResults(store, 3);
+    const check = createStuckChecker(makePi(sent), store, SESSION, DEFAULT_CONFIG);
+    check();
+    expect(sent).toHaveLength(1);
+    expect(sent[0].message.content).toContain(DEFAULT_CONFIG.rescueMessage);
+    expect(sent[0].options.deliverAs).toBe('steer');
+  });
+
+  it('resets the counter after an alert: no re-alert until the loop repeats again', () => {
+    const store = getOrCreateStore(50);
+    const sent: SentMessage[] = [];
+    feedRepeatedResults(store, 3);
+    const check = createStuckChecker(makePi(sent), store, SESSION, DEFAULT_CONFIG);
+    check();
+    expect(sent).toHaveLength(1);
+    // no new events: the historical run is excluded by the alert cutoff
+    check();
+    expect(sent).toHaveLength(1);
+    // the loop keeps going: three fresh repeats re-trigger (no cooldown by default)
+    feedRepeatedResults(store, 3, Date.now() + 1000);
+    check();
+    expect(sent).toHaveLength(2);
+  });
+
+  it('does not re-trigger within a positive cooldown even when the loop repeats', () => {
+    const store = getOrCreateStore(50);
+    const sent: SentMessage[] = [];
+    feedRepeatedResults(store, 3);
+    const check = createStuckChecker(makePi(sent), store, SESSION, {
+      ...DEFAULT_CONFIG,
+      cooldownSec: 60,
+    });
+    check();
+    feedRepeatedResults(store, 3, Date.now() + 1000);
+    check();
+    expect(sent).toHaveLength(1);
+  });
+
+  it('respects the pause state', () => {
+    const store = getOrCreateStore(50);
+    const sent: SentMessage[] = [];
+    feedRepeatedResults(store, 3);
+    store.setPaused(true);
+    const check = createStuckChecker(makePi(sent), store, SESSION, DEFAULT_CONFIG);
+    check();
+    expect(sent).toHaveLength(0);
+  });
+
+  it('does nothing when the session is not stuck', () => {
+    const store = getOrCreateStore(50);
+    const sent: SentMessage[] = [];
+    const check = createStuckChecker(makePi(sent), store, SESSION, DEFAULT_CONFIG);
+    check();
+    expect(sent).toHaveLength(0);
+  });
+
+  it('does nothing when the watchdog is disabled via config', () => {
+    const store = getOrCreateStore(50);
+    const sent: SentMessage[] = [];
+    feedRepeatedResults(store, 3);
+    const check = createStuckChecker(makePi(sent), store, SESSION, {
+      ...DEFAULT_CONFIG,
+      enabled: false,
+    });
+    check();
+    expect(sent).toHaveLength(0);
+  });
+
+  it('prefers the runtime rescue message override', () => {
+    const store = getOrCreateStore(50);
+    const sent: SentMessage[] = [];
+    feedRepeatedResults(store, 3);
+    store.setRescueMessage('custom rescue');
+    const check = createStuckChecker(makePi(sent), store, SESSION, DEFAULT_CONFIG);
+    check();
+    expect(sent).toHaveLength(1);
+    expect(sent[0].message.content).toContain('custom rescue');
+  });
+});

package/test/collector.test.ts

@@ -0,0 +1,201 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { startCollector, startLlmCollector } from '../src/collector.ts';
+import { getOrCreateStore, resetStoreForTest } from '../src/store.ts';
+import { DEFAULT_CONFIG } from '../src/config.ts';
+
+afterEach(() => {
+  resetStoreForTest();
+});
+
+type Handler = (event: unknown) => void;
+
+// Fake pi exposing only the `on` surface the collector uses
+const createFakePi = () => {
+  const handlers = new Map<string, Handler[]>();
+  return {
+    pi: {
+      on: (event: string, handler: Handler) => {
+        handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+      },
+    },
+    emit: (event: string, payload: unknown) => {
+      for (const handler of handlers.get(event) ?? []) {
+        handler(payload);
+      }
+    },
+  };
+};
+
+describe('startCollector', () => {
+  it('records bash tool_call with normalized commandKey', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startCollector(pi, store, 'sess-1', DEFAULT_CONFIG);
+    emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 'tc-1',
+      toolName: 'bash',
+      input: { command: 'rg  "X"  src' },
+    });
+    const events = store.getEvents('sess-1');
+    expect(events).toHaveLength(1);
+    expect(events[0]?.type).toBe('tool_call');
+    expect(events[0]?.commandKey).toBe('rg "X" src');
+    expect(events[0]?.summary).toBe('bash: rg "X" src');
+  });
+
+  it('records tool_result with output hash and preview', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startCollector(pi, store, 'sess-1', DEFAULT_CONFIG);
+    emit('tool_result', {
+      type: 'tool_result',
+      toolCallId: 'tc-1',
+      toolName: 'bash',
+      input: { command: 'rg "X" src' },
+      content: [{ type: 'text', text: 'match line 1\nmatch line 2' }],
+      isError: false,
+    });
+    const events = store.getEvents('sess-1');
+    expect(events).toHaveLength(1);
+    expect(events[0]?.type).toBe('tool_result');
+    expect(events[0]?.outputHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(events[0]?.outputPreview).toBe('match line 1\nmatch line 2');
+  });
+
+  it('classifies edit-family tools as edit events', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startCollector(pi, store, 'sess-1', DEFAULT_CONFIG);
+    emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 'tc-2',
+      toolName: 'edit',
+      input: { path: 'src/a.ts' },
+    });
+    expect(store.getEvents('sess-1')[0]?.type).toBe('edit');
+  });
+
+  it('uses first string input value as commandKey for non-bash tools', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startCollector(pi, store, 'sess-1', DEFAULT_CONFIG);
+    emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 'tc-3',
+      toolName: 'grep',
+      input: { pattern: 'TOKEN', path: 'src' },
+    });
+    expect(store.getEvents('sess-1')[0]?.commandKey).toBe('grep TOKEN');
+  });
+
+  it('ignores malformed payloads without throwing', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startCollector(pi, store, 'sess-1', DEFAULT_CONFIG);
+    emit('tool_call', null);
+    emit('tool_result', { unexpected: true });
+    expect(store.getEvents('sess-1')).toEqual([]);
+  });
+
+  it('stops recording after unsubscribe', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    const stop = startCollector(pi, store, 'sess-1', DEFAULT_CONFIG);
+    stop();
+    emit('tool_call', {
+      type: 'tool_call',
+      toolCallId: 'tc-4',
+      toolName: 'bash',
+      input: { command: 'ls' },
+    });
+    expect(store.getEvents('sess-1')).toEqual([]);
+  });
+});
+
+describe('startLlmCollector', () => {
+  it('records the last payload message as llm_input with a normalized-body hash', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startLlmCollector(pi, store, 'sess-1');
+    emit('before_provider_request', {
+      type: 'before_provider_request',
+      payload: {
+        messages: [
+          { role: 'system', content: 'sys' },
+          { role: 'user', content: 'fix bug at 2026-07-08T14:15:23Z run #17' },
+        ],
+      },
+    });
+    const events = store.getEvents('sess-1');
+    expect(events).toHaveLength(1);
+    expect(events[0]?.type).toBe('llm_input');
+    expect(events[0]?.commandKey).toBe('llm_input');
+    expect(events[0]?.outputHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(events[0]?.outputPreview).toContain('user: fix bug at <ts> run #<n>');
+  });
+
+  it('hashes identically when bodies differ only in timestamps/ids', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startLlmCollector(pi, store, 'sess-1');
+    const send = (text: string) =>
+      emit('before_provider_request', {
+        type: 'before_provider_request',
+        payload: { messages: [{ role: 'user', content: text }] },
+      });
+    send('retry at 2026-07-08T14:15:23Z seq 17');
+    send('retry at 2026-07-08T14:16:41Z seq 42');
+    const [first, second] = store.getEvents('sess-1');
+    expect(first?.outputHash).toBe(second?.outputHash);
+  });
+
+  it('records assistant message_end as llm_output including tool calls', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startLlmCollector(pi, store, 'sess-1');
+    emit('message_end', {
+      type: 'message_end',
+      message: {
+        role: 'assistant',
+        content: [
+          { type: 'thinking', thinking: 'I need to edit the file' },
+          { type: 'text', text: 'Editing now' },
+          { type: 'toolCall', id: 'tc-1', name: 'edit', arguments: { path: 'a.ts' } },
+        ],
+      },
+    });
+    const events = store.getEvents('sess-1');
+    expect(events).toHaveLength(1);
+    expect(events[0]?.type).toBe('llm_output');
+    expect(events[0]?.outputPreview).toContain('toolCall edit');
+  });
+
+  it('invokes onEvent after each recorded llm event (event-driven check hook)', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    let calls = 0;
+    startLlmCollector(pi, store, 'sess-1', () => {
+      calls += 1;
+      expect(store.getEvents('sess-1').length).toBe(calls);
+    });
+    emit('before_provider_request', {
+      type: 'before_provider_request',
+      payload: { messages: [{ role: 'user', content: 'go' }] },
+    });
+    emit('message_end', {
+      type: 'message_end',
+      message: { role: 'assistant', content: [{ type: 'text', text: 'ok' }] },
+    });
+    expect(calls).toBe(2);
+  });
+
+  it('ignores non-assistant message_end and malformed payloads', () => {
+    const store = getOrCreateStore(10);
+    const { pi, emit } = createFakePi();
+    startLlmCollector(pi, store, 'sess-1');
+    emit('message_end', { type: 'message_end', message: { role: 'toolResult', content: [] } });
+    emit('before_provider_request', { type: 'before_provider_request', payload: null });
+    expect(store.getEvents('sess-1')).toEqual([]);
+  });
+});