pi-watchdog-supervisor 0.1.0

package/.tmp/detect_approach.patch

@@ -0,0 +1,253 @@
+diff --git a/src/index.ts b/src/index.ts
+index 658e0bc..b7a28d5 100644
+--- a/src/index.ts
++++ b/src/index.ts
+@@ -9,6 +9,7 @@ import { startTicker } from './ticker.ts';
+ import { mergeConfig } from './config.ts';
+ import { detectStuck } from './detector.ts';
+ import { writeRepeatStatsLog } from './statslog.ts';
++import { registerLmDebugWidget } from './lmdebug.ts';
+ import {
+   connectSubagents,
+   SUBAGENT_EVENT_CHANNELS,
+@@ -55,6 +56,7 @@ export default function watchdogSupervisor(pi: ExtensionAPI) {
+     });
+   }
+ 
++  registerLmDebugWidget(pi);
+   registerWatchdogCommands(pi, { config, registry, getIntegration, store });
+   registerWatchdogTools(pi, {
+     store,
+diff --git a/src/lmdebug.ts b/src/lmdebug.ts
+new file mode 100644
+index 0000000..3eda58b
+--- /dev/null
++++ b/src/lmdebug.ts
+@@ -0,0 +1,121 @@
++// Debug widget at the bottom of the pi console: shows the latest request sent
++// to the LLM provider (LM Studio) and the latest assistant message received,
++// each with a timestamp.
++const WIDGET_KEY = 'watchdog-lm-debug';
++const SNIPPET_LEN = 120;
++
++// Minimal surface used here; satisfied by ExtensionAPI and test fakes
++type PiLike = {
++  on(
++    event: 'before_provider_request',
++    handler: (event: { payload: unknown }, ctx: UiCtxLike) => void,
++  ): void;
++  on(
++    event: 'message_end',
++    handler: (event: { message: unknown }, ctx: UiCtxLike) => void,
++  ): void;
++};
++
++type UiCtxLike = {
++  hasUI: boolean;
++  ui: {
++    setWidget(
++      key: string,
++      content: string[] | undefined,
++      options?: { placement?: 'aboveEditor' | 'belowEditor' },
++    ): void;
++  };
++};
++
++const asRecord = (value: unknown): Record<string, unknown> | undefined =>
++  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
++
++const toSnippet = (raw: string): string => {
++  const flat = raw.replace(/\s+/g, ' ').trim();
++  return flat.length > SNIPPET_LEN ? `${flat.slice(0, SNIPPET_LEN)}…` : flat;
++};
++
++// Text from OpenAI-style content: plain string or [{type:'text',text}] parts
++const extractPartsText = (content: unknown): string => {
++  if (typeof content === 'string') {
++    return content;
++  }
++  if (!Array.isArray(content)) {
++    return '';
++  }
++  return content
++    .map((part) => {
++      const record = asRecord(part);
++      return typeof record?.text === 'string' ? record.text : '';
++    })
++    .filter((text) => text !== '')
++    .join(' ');
++};
++
++export const describeSentPayload = (payload: unknown): string => {
++  const record = asRecord(payload);
++  const messages = Array.isArray(record?.messages) ? (record.messages as unknown[]) : [];
++  const last = asRecord(messages[messages.length - 1]);
++  if (!last) {
++    return 'no messages in payload';
++  }
++  const role = typeof last.role === 'string' ? last.role : 'unknown';
++  const text = toSnippet(extractPartsText(last.content));
++  return `#${messages.length} ${role}: ${text || '(no text)'}`;
++};
++
++// Assistant messages only; other roles return undefined
++export const describeAssistantMessage = (message: unknown): string | undefined => {
++  const record = asRecord(message);
++  if (record?.role !== 'assistant' || !Array.isArray(record.content)) {
++    return undefined;
++  }
++  const parts: string[] = [];
++  for (const block of record.content) {
++    const blockRecord = asRecord(block);
++    if (!blockRecord) {
++      continue;
++    }
++    if (blockRecord.type === 'text' && typeof blockRecord.text === 'string') {
++      parts.push(blockRecord.text);
++    } else if (blockRecord.type === 'toolCall') {
++      const name = typeof blockRecord.name === 'string' ? blockRecord.name : 'tool';
++      parts.push(`[toolCall ${name}]`);
++    }
++  }
++  return `assistant: ${toSnippet(parts.join(' ')) || '(no text)'}`;
++};
++
++const formatTime = (now: number): string => {
++  const date = new Date(now);
++  const pad = (value: number) => String(value).padStart(2, '0');
++  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
++};
++
++export const registerLmDebugWidget = (pi: PiLike, now: () => number = Date.now): void => {
++  let lastSent: string | undefined;
++  let lastReceived: string | undefined;
++
++  const render = (ctx: UiCtxLike) => {
++    if (!ctx.hasUI) {
++      return;
++    }
++    ctx.ui.setWidget(WIDGET_KEY, [lastSent, lastReceived].filter((line): line is string => line !== undefined), {
++      placement: 'belowEditor',
++    });
++  };
++
++  pi.on('before_provider_request', (event, ctx) => {
++    lastSent = `▲ sent ${formatTime(now())} ${describeSentPayload(event.payload)}`;
++    render(ctx);
++  });
++
++  pi.on('message_end', (event, ctx) => {
++    const description = describeAssistantMessage(event.message);
++    if (!description) {
++      return;
++    }
++    lastReceived = `▼ recv ${formatTime(now())} ${description}`;
++    render(ctx);
++  });
++};
+diff --git a/test/lmdebug.test.ts b/test/lmdebug.test.ts
+new file mode 100644
+index 0000000..62739ea
+--- /dev/null
++++ b/test/lmdebug.test.ts
+@@ -0,0 +1,100 @@
++import { describe, expect, it } from 'vitest';
++import {
++  describeAssistantMessage,
++  describeSentPayload,
++  registerLmDebugWidget,
++} from '../src/lmdebug.ts';
++
++const NOW = new Date('2026-07-08T14:15:23').getTime();
++
++// eslint-disable-next-line @typescript-eslint/no-explicit-any -- bivariant fake for overloads
++type Handler = (event: any, ctx: any) => void;
++
++const createFakePi = () => {
++  const handlers = new Map<string, Handler[]>();
++  const widgets: Array<{ key: string; content: string[] | undefined; options: unknown }> = [];
++  const ctx = {
++    hasUI: true,
++    ui: {
++      setWidget: (key: string, content: string[] | undefined, options?: unknown) => {
++        widgets.push({ key, content, options });
++      },
++    },
++  };
++  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, ctx);
++      }
++    },
++    widgets,
++  };
++};
++
++describe('describeSentPayload', () => {
++  it('summarizes the last message of an OpenAI-style payload', () => {
++    const text = describeSentPayload({
++      messages: [
++        { role: 'system', content: 'sys' },
++        { role: 'user', content: 'fix the bug in index.tsx' },
++      ],
++    });
++    expect(text).toBe('#2 user: fix the bug in index.tsx');
++  });
++
++  it('handles content parts arrays and missing payloads', () => {
++    expect(
++      describeSentPayload({ messages: [{ role: 'tool', content: [{ type: 'text', text: 'ok' }] }] }),
++    ).toBe('#1 tool: ok');
++    expect(describeSentPayload(undefined)).toBe('no messages in payload');
++  });
++});
++
++describe('describeAssistantMessage', () => {
++  it('summarizes text and toolCall blocks', () => {
++    const text = describeAssistantMessage({
++      role: 'assistant',
++      content: [
++        { type: 'text', text: 'I will edit the file' },
++        { type: 'toolCall', name: 'edit', arguments: {} },
++      ],
++    });
++    expect(text).toBe('assistant: I will edit the file [toolCall edit]');
++  });
++
++  it('returns undefined for non-assistant messages', () => {
++    expect(describeAssistantMessage({ role: 'user', content: [] })).toBeUndefined();
++  });
++});
++
++describe('registerLmDebugWidget', () => {
++  it('renders sent/received lines with timestamps into a belowEditor widget', () => {
++    const { pi, emit, widgets } = createFakePi();
++    registerLmDebugWidget(pi, () => NOW);
++    emit('before_provider_request', {
++      payload: { messages: [{ role: 'user', content: 'hello' }] },
++    });
++    emit('message_end', {
++      message: { role: 'assistant', content: [{ type: 'text', text: 'hi there' }] },
++    });
++    expect(widgets).toHaveLength(2);
++    expect(widgets[1].key).toBe('watchdog-lm-debug');
++    expect(widgets[1].options).toEqual({ placement: 'belowEditor' });
++    expect(widgets[1].content).toEqual([
++      '▲ sent 14:15:23 #1 user: hello',
++      '▼ recv 14:15:23 assistant: hi there',
++    ]);
++  });
++
++  it('ignores non-assistant message_end events', () => {
++    const { pi, emit, widgets } = createFakePi();
++    registerLmDebugWidget(pi, () => NOW);
++    emit('message_end', { message: { role: 'toolResult', content: [] } });
++    expect(widgets).toHaveLength(0);
++  });
++});

package/README.md

@@ -0,0 +1,176 @@
+# pi-watchdog-supervisor
+
+A [Pi](https://pi.dev) extension that lets a **watchdog sub-agent** supervise
+sibling task sub-agents and report likely stuck/loop states to the main agent
+session.
+
+Typical failure it catches: a task sub-agent re-running the same `rg`/`grep`
+command, getting the same output, producing no new edits — forever.
+
+## Architecture
+
+Three layers with separate responsibilities:
+
+```txt
+Every Session (main AND child — children inherit parent extensions)
+│  ├─ listens to its OWN llm events (before_provider_request / message_end)
+│  │    and tool_call / tool_result events
+│  ├─ normalizes message bodies (timestamps/ids stripped), hashes them
+│  ├─ appends compact events to a process-shared store
+│  └─ event-driven self-check on every LLM round-trip:
+│       detect stuck on own buffer → steer rescue message into itself
+│       (no timer, no watchdog sub-agent needed)
+│        ↓
+Main Agent Session (parent)
+│  this extension
+│  ├─ tracks sub-agent lifecycle (@gotgenes/pi-subagents events)
+│  ├─ runs deterministic stuck detection + cooldown
+│  └─ receives [Watchdog Alert] messages via an alert sink
+│        ↓
+Watchdog Sub-agent Session (optional, for cross-agent supervision)
+   calls watchdog_* tools → analyzes → alerts the main agent
+```
+
+- **Extension runtime** = deterministic collector + detector (no LLM guessing
+  for repeat counts / timeouts).
+- **Watchdog sub-agent** = reasoning/reporting layer (uses the tools below).
+- **Main agent** = final decision maker; nothing is auto-killed or auto-steered
+  by default.
+
+## Requirements
+
+- `@gotgenes/pi-subagents` (optional peer dependency) — without it the
+  extension still loads, but target discovery is unavailable.
+
+## Install
+
+```bash
+pi install npm:pi-watchdog-supervisor      # once published
+# or for local development:
+pi -e ./src/index.ts
+```
+
+## Commands
+
+| Command | Behavior |
+|---|---|
+| `/watchdog status` | List targets with kind/status/tool count and stuck flag |
+| `/watchdog config` | Show effective config (defaults ← global ← project ← runtime overrides) |
+| `/watchdog set rescueMessage <msg>` | Override the rescue message for this run |
+| `/watchdog pause` | Suppress alerting temporarily |
+| `/watchdog resume` | Re-enable alerting |
+| `/watchdog inspect <targetId>` | Show recent compact events + stuck analysis for one target |
+
+## Tools (for the watchdog sub-agent)
+
+| Tool | Purpose |
+|---|---|
+| `watchdog_list_targets` | List sub-agents with status and `likelyStuck` signal |
+| `watchdog_read_events` | Read compact recent events (commands, output hashes, edits) |
+| `watchdog_detect_stuck` | Deterministic stuck analysis + `suggestedRescueMessage` |
+| `watchdog_alert_main` | Send a `[Watchdog Alert]` into the main session |
+| `watchdog_steer_subagent` | Send a rescue message to a target (defaults to dry-run) |
+| `watchdog_config` | Read/update policy at runtime |
+
+## Stuck detection rules
+
+Detection works at the LLM message level (same sources as the lm-debug
+widget): `before_provider_request` captures the newest message sent to the
+provider, `message_end` captures each finalized assistant message. Bodies are
+normalized before hashing — timestamps, dates, UUIDs, long hex ids, and digit
+runs are replaced with placeholders — so two loop iterations that differ only
+in time or sequence markers compare as identical.
+
+- `repeated_llm_input`: the same normalized input body sent to the LLM ≥
+  `llmRepeatThreshold` (3) times in a row.
+- `repeated_llm_output`: the same normalized assistant output body (text +
+  thinking + tool calls with arguments) ≥ `llmRepeatThreshold` times in a row.
+- `idle_no_progress`: tools keep running but no edit/write for ≥
+  `idleNoProgressSec`. **Disabled by default** (`0`); set a positive number of
+  seconds (e.g. `300`) to enable.
+
+Setting `llmRepeatThreshold` to `0` disables the LLM repetition rules. The
+repeats must be consecutive; a different message in between resets the run.
+Confidence: one evidence type → `medium`, two or more → `high`.
+
+## Safety & anti-spam
+
+- `alertMode`:
+  - `main_only` (default): only shows an alert message in the main session;
+    nothing is sent to the stuck sub-agent (no extra AI provider message).
+  - `direct_subagent` / `both`: additionally allow `watchdog_steer_subagent`
+    to send the rescue message into the stuck sub-agent (with
+    `dryRun: false`; the tool defaults to dry-run).
+  - `dryRun` is a parameter of the `watchdog_steer_subagent` tool call,
+    passed by the watchdog agent per invocation. When the call omits it, the
+    `steerDryRunDefault` config field decides:
+    - `null` (default) or `true`: dry-run.
+    - `false`: steer for real without a per-call `dryRun: false` — opt-in to
+      fully automatic rescue (still requires `alertMode` other than
+      `main_only`).
+    - An explicit `dryRun` in the call always wins over the config default.
+- Alerts respect a per-target cooldown (`cooldownSec`):
+  - `0` (default): no cooldown — every check that meets the threshold alerts.
+  - `-1`: infinite cooldown — the same evidence key alerts only once; new
+    evidence still alerts.
+  - `> 0`: the same evidence key is not re-alerted within that many seconds;
+    new evidence still alerts immediately.
+- The repetition counter resets at each alert: only llm messages recorded
+  after the last alert count toward the next one. A recovered agent stops
+  alerting immediately; an agent still looping re-accumulates the threshold
+  within a few round-trips.
+- `/watchdog pause` suppresses all alerts until `/watchdog resume` (including
+  the automatic tick).
+- Only output hashes and short previews are stored, never full outputs.
+- Besides the watchdog-agent-driven flow (Option A), the extension runs an
+  event-driven self-check in every session (Option B): each session (main or
+  child) re-runs stuck detection on its own event buffer on every LLM
+  round-trip — after each `before_provider_request` / `message_end` llm event
+  and on `after_provider_response` — and steers the rescue message into itself
+  the moment the threshold is crossed. No timer is involved. The check
+  respects `enabled`, `cooldownSec`, and the pause state.
+
+## Configuration
+
+Project config `.pi/watchdog-supervisor.json` overrides global config
+`~/.pi/agent/watchdog-supervisor/config.json`. See
+[examples/watchdog-supervisor.json](examples/watchdog-supervisor.json) for all
+fields (values match the defaults, except `idleNoProgressSec` which is shown
+enabled at `300`; its default is `0` = disabled). The default `rescueMessage`
+asks the agent to stop repeating the current actions and resume the task —
+override it per project or per session as needed.
+
+Set `debug: true` (default `false`) to show a debug console below the editor
+with the latest message sent to the provider and the latest assistant message
+received, each timestamped, in full (newlines preserved, no truncation).
+
+## Manual E2E scenario
+
+Prerequisites: `@gotgenes/pi-subagents` installed, this extension loaded
+(`pi -e ./src/index.ts`), API key available.
+
+1. In the main session, spawn a watchdog sub-agent using
+   [prompts/watchdog-agent.md](prompts/watchdog-agent.md) plus
+   "supervise the task agents".
+2. Spawn a dummy loop task sub-agent:
+   `Repeat the exact same step five times: run `rg "SOME_TOKEN" src` and
+   report the result with the same sentence each time.`
+3. After the task agent has looped a few turns, prompt the watchdog:
+   "Check task sub-agent status now."
+4. Expected:
+   - `watchdog_list_targets` shows the task agent with `likelyStuck: true`
+   - `watchdog_detect_stuck` returns `repeated_llm_input` /
+     `repeated_llm_output` evidence
+   - `watchdog_alert_main` puts a `[Watchdog Alert]` into the main session
+5. Main agent decides: ask the watchdog to run `watchdog_steer_subagent`
+   (dry-run by default); real steering requires
+   `watchdog_config set { "alertMode": "both" }` first.
+
+## Development
+
+```bash
+npm install
+npm run type-check
+npm test
+pi -e ./src/index.ts
+```

package/examples/AGENTS.md

@@ -0,0 +1,27 @@
+# Example main-agent instructions
+
+Copy the section below into your project's `AGENTS.md` to enable the
+supervisor workflow.
+
+---
+
+## Sub-agent watchdog workflow
+
+When running multiple background sub-agents:
+
+1. Start one watchdog sub-agent using the prompt in
+   `prompts/watchdog-agent.md` (from the pi-watchdog-supervisor package).
+2. Start task sub-agents normally.
+3. Periodically ask the watchdog sub-agent to inspect task sub-agent status
+   ("Check task sub-agent status now.") — the watchdog uses the
+   `watchdog_list_targets` / `watchdog_detect_stuck` / `watchdog_read_events`
+   tools and reports via `watchdog_alert_main`.
+4. If the watchdog reports a likely stuck task, decide whether to steer the
+   task sub-agent.
+5. Prefer sending a rescue message before stopping/restarting a sub-agent.
+   Direct steering via `watchdog_steer_subagent` requires setting
+   `alertMode` to `direct_subagent` or `both` first (default is `main_only`).
+
+Note (MVP / Option A): the watchdog sub-agent does not wake up by itself —
+the main agent drives the check cadence. An extension-driven periodic tick
+(Option B) is post-MVP.

package/examples/watchdog-supervisor.json

@@ -0,0 +1,12 @@
+{
+  "enabled": true,
+  "rescueMessage": "The AI agent might be stuck. Stop repeating the current actions, then resume the task.",
+  "llmRepeatThreshold": 3,
+  "idleNoProgressSec": 300,
+  "cooldownSec": 0,
+  "maxPreviewLines": 20,
+  "maxEventsPerAgent": 200,
+  "alertMode": "main_only",
+  "steerDryRunDefault": null,
+  "debug": false
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "pi-watchdog-supervisor",
+  "version": "0.1.0",
+  "description": "Pi extension: watchdog supervisor for task sub-agents",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@gotgenes/pi-subagents": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@gotgenes/pi-subagents": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@gotgenes/pi-subagents": "^18.0.1",
+    "@types/node": "^26.1.1",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "typebox": "^1.3.5"
+  }
+}

package/prompts/watchdog-agent.md

@@ -0,0 +1,36 @@
+# Watchdog Supervisor Agent Prompt
+
+Use this prompt when spawning a watchdog sub-agent.
+
+---
+
+You are a watchdog supervisor for Pi task sub-agents.
+
+Your job:
+- Check task sub-agent status through the watchdog tools.
+- Detect likely loop/stuck cases.
+- Report compact alerts to the main agent.
+- Do not fix code yourself unless explicitly asked.
+- Do not spam alerts; the tools enforce a per-target cooldown — respect it.
+- Prefer evidence-based alerts: run `watchdog_detect_stuck` before alerting.
+
+Workflow for each check:
+1. Call `watchdog_list_targets` to see running sub-agents.
+2. Ignore yourself and completed/failed agents.
+3. For each running task agent, call `watchdog_detect_stuck`.
+4. If `likelyStuck` is true, call `watchdog_read_events` to gather evidence.
+5. Call `watchdog_alert_main` with a compact summary.
+6. Do not call `watchdog_steer_subagent` with `dryRun: false` unless the main
+   agent explicitly allowed direct steering (and `alertMode` permits it).
+   Exception: when the config sets `steerDryRunDefault: false`, the user has
+   pre-authorized automatic steering — you may steer without per-case
+   approval.
+
+When reporting a stuck task, include:
+- sub-agent id/name
+- reason
+- repeated LLM message or error summary
+- last activity time
+- suggested rescue message (from `watchdog_detect_stuck` output)
+
+If nothing is stuck, reply briefly that all targets look healthy — do not alert.

package/skills/watchdog-supervisor/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: watchdog-supervisor
+description: |
+  Supervise Pi task sub-agents for stuck/loop states. Use when acting as a
+  watchdog sub-agent, or as a main agent coordinating task sub-agents with a
+  watchdog. Detects repeated LLM input/output message bodies (timestamps and
+  ids normalized away) and idle-without-progress via deterministic watchdog tools, then reports
+  compact alerts to the main session.
+---
+
+# Watchdog Supervisor
+
+Use this skill when supervising task sub-agents.
+
+## Steps
+
+1. Call `watchdog_list_targets`.
+2. Ignore yourself and completed agents.
+3. For each running task agent, call `watchdog_detect_stuck`.
+4. If likely stuck, call `watchdog_read_events` for evidence.
+5. Report a compact alert to the main agent via `watchdog_alert_main`.
+6. Do not directly steer unless explicitly allowed — `watchdog_steer_subagent`
+   defaults to dry-run, and real steering is refused while `alertMode` is
+   `main_only`.
+
+## Notes
+
+- Alerts respect a per-target cooldown (`cooldownSec`: `0` default = no
+  cooldown, `-1` = same evidence alerts once, `>0` = seconds) and the
+  pause state (`/watchdog pause`); a suppressed alert returns a clear reason.
+- The repetition counter resets at each alert: only llm messages after the
+  last alert count toward the next one.
+- `watchdog_detect_stuck` output includes `suggestedRescueMessage` — include it
+  in the alert so the main agent can forward it as-is.
+- Read or tune policy with `watchdog_config` (`action: "get" | "set"`).

package/src/checker.ts

@@ -0,0 +1,54 @@
+import type { WatchdogConfig } from './types.ts';
+import type { WatchdogStore } from './store.ts';
+import { mergeConfig } from './config.ts';
+import { detectStuck, shouldAlert } from './detector.ts';
+
+// Minimal message surface used by the checker; satisfied by ExtensionAPI
+export type SendMessageLike = {
+  sendMessage(
+    message: { customType: string; content: string; display: boolean },
+    options: { deliverAs: 'steer'; triggerTurn: boolean },
+  ): void;
+};
+
+// Event-driven self-check: invoked on every LLM round-trip (provider request /
+// response) instead of a timer, so a loop is caught on the round-trip that
+// crosses the threshold. Runs in every session (main or child); each session
+// checks its own buffer and steers itself.
+export const createStuckChecker = (
+  pi: SendMessageLike,
+  store: WatchdogStore,
+  sessionId: string,
+  config: WatchdogConfig,
+): (() => void) => {
+  return () => {
+    if (store.isPaused()) {
+      return;
+    }
+    const effective = mergeConfig(config, store.getConfigOverride());
+    if (!effective.enabled) {
+      return;
+    }
+    const now = Date.now();
+    const lastAlert = store.getLastAlert(sessionId);
+    const analysis = detectStuck(store.getEvents(sessionId), effective, now, lastAlert?.at ?? 0);
+    if (!analysis.likelyStuck) {
+      return;
+    }
+    if (!shouldAlert(lastAlert, analysis, now, effective.cooldownSec)) {
+      return;
+    }
+    const rescueMessage = store.getRescueMessage() ?? effective.rescueMessage;
+    pi.sendMessage(
+      {
+        customType: 'watchdog-alert',
+        content: `[Watchdog] ${rescueMessage}\nReasons: ${analysis.reasons.join('; ')}`,
+        display: true,
+      },
+      // 'steer' is delivered after the current tool calls, before the next LLM
+      // call; 'nextTurn' would wait for a user prompt that never comes in a loop
+      { deliverAs: 'steer', triggerTurn: true },
+    );
+    store.recordAlert(sessionId, analysis.evidenceKey, now);
+  };
+};