agent-working-memory 0.7.17 → 0.8.6

package/src/coordination/circuit-breaker.ts

@@ -0,0 +1,83 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Per-worker CircuitBreaker for the coordination control layer.
+ * Prevents chronically-stale workers from poisoning the assignment queue.
+ * Part of AWM 0.8.1 — additive, no breaking changes.
+ *
+ * States:
+ *   closed    — normal operation
+ *   open      — worker blocked after FAILURE_THRESHOLD consecutive failures
+ *   half_open — probe window (30s after open), allows one assignment attempt
+ */
+
+import type Database from 'better-sqlite3';
+
+export type CircuitState = 'closed' | 'open' | 'half_open';
+
+const FAILURE_THRESHOLD = 5;
+const HALF_OPEN_DELAY_MS = 30_000;
+
+/** Record a worker failure. Opens the circuit when consecutive failures hit the threshold. */
+export function recordFailure(db: Database.Database, agentId: string): void {
+  db.prepare(`
+    INSERT INTO coord_circuit_state (agent_id, consecutive_failures, last_transition_at)
+    VALUES (?, 1, datetime('now'))
+    ON CONFLICT(agent_id) DO UPDATE SET
+      consecutive_failures = consecutive_failures + 1,
+      state = CASE
+        WHEN consecutive_failures + 1 >= ${FAILURE_THRESHOLD} THEN 'open'
+        ELSE state
+      END,
+      opened_at = CASE
+        WHEN consecutive_failures + 1 >= ${FAILURE_THRESHOLD} AND (state != 'open' OR opened_at IS NULL)
+        THEN datetime('now')
+        ELSE opened_at
+      END,
+      last_transition_at = datetime('now')
+  `).run(agentId);
+}
+
+/** Record a worker success. Resets to closed regardless of prior state. */
+export function recordSuccess(db: Database.Database, agentId: string): void {
+  db.prepare(`
+    INSERT INTO coord_circuit_state (agent_id, state, consecutive_failures, last_transition_at)
+    VALUES (?, 'closed', 0, datetime('now'))
+    ON CONFLICT(agent_id) DO UPDATE SET
+      state = 'closed',
+      consecutive_failures = 0,
+      opened_at = NULL,
+      last_transition_at = datetime('now')
+  `).run(agentId);
+}
+
+/**
+ * Get current circuit state for a worker.
+ * If the circuit has been open for >30s, auto-transitions to half_open.
+ */
+export function getState(db: Database.Database, agentId: string): CircuitState {
+  const row = db.prepare(
+    `SELECT state, opened_at FROM coord_circuit_state WHERE agent_id = ?`
+  ).get(agentId) as { state: string; opened_at: string | null } | undefined;
+
+  if (!row || row.state === 'closed') return 'closed';
+  if (row.state === 'half_open') return 'half_open';
+
+  // open — check if half-open window has elapsed
+  if (row.state === 'open' && row.opened_at) {
+    const openedAt = new Date(row.opened_at.endsWith('Z') ? row.opened_at : row.opened_at + 'Z').getTime();
+    if (Date.now() - openedAt > HALF_OPEN_DELAY_MS) {
+      db.prepare(
+        `UPDATE coord_circuit_state SET state = 'half_open', last_transition_at = datetime('now') WHERE agent_id = ?`
+      ).run(agentId);
+      return 'half_open';
+    }
+  }
+
+  return 'open';
+}
+
+/** Returns true when the worker is eligible to receive an assignment. */
+export function isAvailable(db: Database.Database, agentId: string): boolean {
+  return getState(db, agentId) !== 'open';
+}

package/src/coordination/events.ts

@@ -1,90 +1,90 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Typed internal event emitter for coordination.
- * Lightweight Node EventEmitter wrapper with typed events.
- * Used to decouple route handlers from side-effects (channel push, logging, etc).
- */
-
-import { EventEmitter } from 'events';
-
-// ─── Event Payloads ──────────────────────────────────────────────
-
-export interface AssignmentCreatedEvent {
-  assignmentId: string;
-  agentId: string;
-  task: string;
-  workspace?: string;
-}
-
-export interface AssignmentUpdatedEvent {
-  assignmentId: string;
-  agentId: string | null;
-  status: string;
-  result?: string;
-}
-
-export interface AssignmentCompletedEvent {
-  assignmentId: string;
-  agentId: string | null;
-  result: string | null;
-}
-
-export interface AgentCheckinEvent {
-  agentId: string;
-  name: string;
-  role: string;
-  workspace?: string;
-}
-
-export interface AgentCheckoutEvent {
-  agentId: string;
-  name: string;
-}
-
-export interface SessionStartedEvent {
-  agentId: string;
-  channelId: string;
-}
-
-export interface SessionClosedEvent {
-  agentId: string;
-  channelId: string;
-}
-
-// ─── Event Map ───────────────────────────────────────────────────
-
-export interface CoordinationEvents {
-  'assignment.created': [AssignmentCreatedEvent];
-  'assignment.updated': [AssignmentUpdatedEvent];
-  'assignment.completed': [AssignmentCompletedEvent];
-  'agent.checkin': [AgentCheckinEvent];
-  'agent.checkout': [AgentCheckoutEvent];
-  'session.started': [SessionStartedEvent];
-  'session.closed': [SessionClosedEvent];
-}
-
-// ─── Typed Event Bus ─────────────────────────────────────────────
-
-export class CoordinationEventBus extends EventEmitter {
-  emit<K extends keyof CoordinationEvents>(event: K, ...args: CoordinationEvents[K]): boolean {
-    return super.emit(event, ...args);
-  }
-
-  on<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
-    return super.on(event, listener as (...args: unknown[]) => void);
-  }
-
-  once<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
-    return super.once(event, listener as (...args: unknown[]) => void);
-  }
-
-  off<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
-    return super.off(event, listener as (...args: unknown[]) => void);
-  }
-}
-
-/** Create a new coordination event bus. */
-export function createEventBus(): CoordinationEventBus {
-  return new CoordinationEventBus();
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Typed internal event emitter for coordination.
+ * Lightweight Node EventEmitter wrapper with typed events.
+ * Used to decouple route handlers from side-effects (channel push, logging, etc).
+ */
+
+import { EventEmitter } from 'events';
+
+// ─── Event Payloads ──────────────────────────────────────────────
+
+export interface AssignmentCreatedEvent {
+  assignmentId: string;
+  agentId: string;
+  task: string;
+  workspace?: string;
+}
+
+export interface AssignmentUpdatedEvent {
+  assignmentId: string;
+  agentId: string | null;
+  status: string;
+  result?: string;
+}
+
+export interface AssignmentCompletedEvent {
+  assignmentId: string;
+  agentId: string | null;
+  result: string | null;
+}
+
+export interface AgentCheckinEvent {
+  agentId: string;
+  name: string;
+  role: string;
+  workspace?: string;
+}
+
+export interface AgentCheckoutEvent {
+  agentId: string;
+  name: string;
+}
+
+export interface SessionStartedEvent {
+  agentId: string;
+  channelId: string;
+}
+
+export interface SessionClosedEvent {
+  agentId: string;
+  channelId: string;
+}
+
+// ─── Event Map ───────────────────────────────────────────────────
+
+export interface CoordinationEvents {
+  'assignment.created': [AssignmentCreatedEvent];
+  'assignment.updated': [AssignmentUpdatedEvent];
+  'assignment.completed': [AssignmentCompletedEvent];
+  'agent.checkin': [AgentCheckinEvent];
+  'agent.checkout': [AgentCheckoutEvent];
+  'session.started': [SessionStartedEvent];
+  'session.closed': [SessionClosedEvent];
+}
+
+// ─── Typed Event Bus ─────────────────────────────────────────────
+
+export class CoordinationEventBus extends EventEmitter {
+  emit<K extends keyof CoordinationEvents>(event: K, ...args: CoordinationEvents[K]): boolean {
+    return super.emit(event, ...args);
+  }
+
+  on<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
+    return super.on(event, listener as (...args: unknown[]) => void);
+  }
+
+  once<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
+    return super.once(event, listener as (...args: unknown[]) => void);
+  }
+
+  off<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
+    return super.off(event, listener as (...args: unknown[]) => void);
+  }
+}
+
+/** Create a new coordination event bus. */
+export function createEventBus(): CoordinationEventBus {
+  return new CoordinationEventBus();
+}

package/src/coordination/failure-modes.ts

@@ -0,0 +1,50 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * FailureMode taxonomy and mutation-hint map for the coordination control layer.
+ * Part of AWM 0.8.1 — additive, no breaking changes.
+ */
+
+export enum FailureMode {
+  AGENT_STALE    = 'agent_stale',
+  TIMEOUT        = 'timeout',
+  OUTPUT_INVALID = 'output_invalid',
+  TEST_FAIL      = 'test_fail',
+  LINT_FAIL      = 'lint_fail',
+  MERGE_CONFLICT = 'merge_conflict',
+  UNKNOWN        = 'unknown',
+}
+
+/** Classify a failure result string into one of the known modes. */
+export function classifyFailure(result: string | null): FailureMode {
+  if (!result) return FailureMode.UNKNOWN;
+  const r = result.toLowerCase();
+  if (r.includes('stale') || r.includes('disconnected')) return FailureMode.AGENT_STALE;
+  if (r.includes('timeout') || r.includes('timed out'))  return FailureMode.TIMEOUT;
+  if (r.includes('json') || r.includes('schema') || r.includes('parse')) return FailureMode.OUTPUT_INVALID;
+  if (r.includes('test fail') || r.includes('vitest') || r.includes('jest')) return FailureMode.TEST_FAIL;
+  if (r.includes('lint') || r.includes('eslint') || r.includes('typecheck')) return FailureMode.LINT_FAIL;
+  if (r.includes('conflict'))                             return FailureMode.MERGE_CONFLICT;
+  return FailureMode.UNKNOWN;
+}
+
+/**
+ * Corrective guidance injected into the task description on retry.
+ * Each hint is written in the vocabulary the next worker will read.
+ */
+export const MUTATION_HINTS: Record<FailureMode, string> = {
+  [FailureMode.AGENT_STALE]:
+    'Previous worker disconnected before completion. Resume from last known state; check git status before re-running destructive commands.',
+  [FailureMode.TIMEOUT]:
+    'Previous attempt timed out. Break work into smaller commits; report progress every 5 minutes.',
+  [FailureMode.OUTPUT_INVALID]:
+    'Previous output failed validation. Return a single fenced code block; verify JSON parses before submitting.',
+  [FailureMode.TEST_FAIL]:
+    'Previous attempt left tests failing. Run vitest before completion; do NOT mark complete if any test fails.',
+  [FailureMode.LINT_FAIL]:
+    'Previous attempt had lint/typecheck errors. Run pnpm typecheck and pnpm lint before completion.',
+  [FailureMode.MERGE_CONFLICT]:
+    'Previous attempt left merge conflicts unresolved. git pull --rebase, resolve, then re-attempt.',
+  [FailureMode.UNKNOWN]:
+    'Previous attempt failed for an unclassified reason. Investigate the prior result before re-running.',
+};

package/src/coordination/peer-decisions.ts

@@ -1,105 +1,105 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Peer-decision injection for memory_recall.
- *
- * When coordination is enabled, memory_recall appends recent decisions
- * made by OTHER agents that are relevant to the current recall query.
- * This enables passive cross-agent knowledge sharing without explicit
- * communication.
- */
-
-import type Database from 'better-sqlite3';
-
-export interface PeerDecision {
-  id: number;
-  author_name: string;
-  assignment_id: string | null;
-  tags: string | null;
-  summary: string;
-  created_at: string;
-}
-
-/** Stop words filtered out before keyword matching. */
-const STOP_WORDS = new Set([
-  'that', 'this', 'with', 'from', 'have', 'been', 'will', 'when', 'what',
-  'which', 'then', 'than', 'into', 'over', 'after', 'some', 'more', 'also',
-  'most', 'other', 'each', 'such', 'only', 'just', 'about', 'there', 'their',
-  'where', 'would', 'could', 'should', 'these', 'those', 'make', 'made',
-  'using', 'used', 'call', 'calls', 'does', 'done', 'were', 'they',
-]);
-
-/**
- * Extract significant keywords from a recall query for relevance matching.
- * Returns up to maxKeywords words of length >= 4 that are not stop words.
- */
-export function extractKeywords(query: string, maxKeywords = 8): string[] {
-  return query
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]/g, ' ')
-    .split(/\s+/)
-    .filter(w => w.length >= 4 && !STOP_WORDS.has(w))
-    .slice(0, maxKeywords);
-}
-
-/**
- * Query coord_decisions for recent decisions by agents OTHER than the current one
- * that are relevant to the given query string.
- *
- * @param db         The shared coordination database handle.
- * @param selfName   The current agent's name (AWM_AGENT_ID / WORKER_NAME). Excluded from results.
- * @param query      The recall query text used for keyword relevance matching.
- * @param windowHours  How far back to look (default 1 hour).
- * @param limit      Maximum number of decisions to return (default 5).
- * @returns Array of peer decisions, ordered newest-first. Empty array on any error.
- */
-export function queryPeerDecisions(
-  db: Database.Database,
-  selfName: string,
-  query: string,
-  windowHours = 1,
-  limit = 5,
-): PeerDecision[] {
-  try {
-    const safeHours = Math.max(0.1, Math.min(windowHours, 168)); // 6min – 1 week
-    const safeLimit = Math.max(1, Math.min(limit, 50));
-    const keywords = extractKeywords(query);
-
-    const baseWhere = `
-      d.created_at >= datetime('now', '-${safeHours} hours')
-      AND a.name != ?
-    `;
-
-    const select = `
-      SELECT d.id, a.name AS author_name, d.assignment_id, d.tags, d.summary, d.created_at
-      FROM coord_decisions d
-      JOIN coord_agents a ON d.author_id = a.id
-    `;
-
-    if (keywords.length === 0) {
-      // No useful keywords — return the N most recent decisions from other agents
-      const sql = `${select} WHERE ${baseWhere} ORDER BY d.created_at DESC LIMIT ?`;
-      return db.prepare(sql).all(selfName, safeLimit) as PeerDecision[];
-    }
-
-    // Build keyword filter: match any keyword in summary or tags
-    const kwClauses = keywords.map(() => `(d.summary LIKE ? OR d.tags LIKE ?)`).join(' OR ');
-    const sql = `${select} WHERE ${baseWhere} AND (${kwClauses}) ORDER BY d.created_at DESC LIMIT ?`;
-    const kwParams = keywords.flatMap(kw => [`%${kw}%`, `%${kw}%`]);
-
-    return db.prepare(sql).all(selfName, ...kwParams, safeLimit) as PeerDecision[];
-  } catch {
-    return []; // non-fatal — peer decisions are best-effort
-  }
-}
-
-/**
- * Format peer decisions as a text section to append to memory_recall output.
- * Returns an empty string when there are no peer decisions.
- */
-export function formatPeerDecisions(decisions: PeerDecision[], windowHours = 1): string {
-  if (decisions.length === 0) return '';
-  const label = windowHours === 1 ? '1h' : `${windowHours}h`;
-  const lines = decisions.map(d => `[${d.author_name}] ${d.summary}`);
-  return `\n--- Peer Decisions (last ${label}) ---\n${lines.join('\n')}`;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Peer-decision injection for memory_recall.
+ *
+ * When coordination is enabled, memory_recall appends recent decisions
+ * made by OTHER agents that are relevant to the current recall query.
+ * This enables passive cross-agent knowledge sharing without explicit
+ * communication.
+ */
+
+import type Database from 'better-sqlite3';
+
+export interface PeerDecision {
+  id: number;
+  author_name: string;
+  assignment_id: string | null;
+  tags: string | null;
+  summary: string;
+  created_at: string;
+}
+
+/** Stop words filtered out before keyword matching. */
+const STOP_WORDS = new Set([
+  'that', 'this', 'with', 'from', 'have', 'been', 'will', 'when', 'what',
+  'which', 'then', 'than', 'into', 'over', 'after', 'some', 'more', 'also',
+  'most', 'other', 'each', 'such', 'only', 'just', 'about', 'there', 'their',
+  'where', 'would', 'could', 'should', 'these', 'those', 'make', 'made',
+  'using', 'used', 'call', 'calls', 'does', 'done', 'were', 'they',
+]);
+
+/**
+ * Extract significant keywords from a recall query for relevance matching.
+ * Returns up to maxKeywords words of length >= 4 that are not stop words.
+ */
+export function extractKeywords(query: string, maxKeywords = 8): string[] {
+  return query
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length >= 4 && !STOP_WORDS.has(w))
+    .slice(0, maxKeywords);
+}
+
+/**
+ * Query coord_decisions for recent decisions by agents OTHER than the current one
+ * that are relevant to the given query string.
+ *
+ * @param db         The shared coordination database handle.
+ * @param selfName   The current agent's name (AWM_AGENT_ID / WORKER_NAME). Excluded from results.
+ * @param query      The recall query text used for keyword relevance matching.
+ * @param windowHours  How far back to look (default 1 hour).
+ * @param limit      Maximum number of decisions to return (default 5).
+ * @returns Array of peer decisions, ordered newest-first. Empty array on any error.
+ */
+export function queryPeerDecisions(
+  db: Database.Database,
+  selfName: string,
+  query: string,
+  windowHours = 1,
+  limit = 5,
+): PeerDecision[] {
+  try {
+    const safeHours = Math.max(0.1, Math.min(windowHours, 168)); // 6min – 1 week
+    const safeLimit = Math.max(1, Math.min(limit, 50));
+    const keywords = extractKeywords(query);
+
+    const baseWhere = `
+      d.created_at >= datetime('now', '-${safeHours} hours')
+      AND a.name != ?
+    `;
+
+    const select = `
+      SELECT d.id, a.name AS author_name, d.assignment_id, d.tags, d.summary, d.created_at
+      FROM coord_decisions d
+      JOIN coord_agents a ON d.author_id = a.id
+    `;
+
+    if (keywords.length === 0) {
+      // No useful keywords — return the N most recent decisions from other agents
+      const sql = `${select} WHERE ${baseWhere} ORDER BY d.created_at DESC LIMIT ?`;
+      return db.prepare(sql).all(selfName, safeLimit) as PeerDecision[];
+    }
+
+    // Build keyword filter: match any keyword in summary or tags
+    const kwClauses = keywords.map(() => `(d.summary LIKE ? OR d.tags LIKE ?)`).join(' OR ');
+    const sql = `${select} WHERE ${baseWhere} AND (${kwClauses}) ORDER BY d.created_at DESC LIMIT ?`;
+    const kwParams = keywords.flatMap(kw => [`%${kw}%`, `%${kw}%`]);
+
+    return db.prepare(sql).all(selfName, ...kwParams, safeLimit) as PeerDecision[];
+  } catch {
+    return []; // non-fatal — peer decisions are best-effort
+  }
+}
+
+/**
+ * Format peer decisions as a text section to append to memory_recall output.
+ * Returns an empty string when there are no peer decisions.
+ */
+export function formatPeerDecisions(decisions: PeerDecision[], windowHours = 1): string {
+  if (decisions.length === 0) return '';
+  const label = windowHours === 1 ? '1h' : `${windowHours}h`;
+  const lines = decisions.map(d => `[${d.author_name}] ${d.summary}`);
+  return `\n--- Peer Decisions (last ${label}) ---\n${lines.join('\n')}`;
+}

package/src/coordination/plugin-loader.ts

@@ -1,60 +1,60 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Plugin loader for AWM coordination.
- *
- * Reads AWM_PLUGINS env var (comma-separated module paths or package names),
- * dynamically imports each, and calls register() with the plugin context.
- *
- * Usage:
- *   AWM_PLUGINS=./plugins/slack-notify.js,my-awm-plugin npm start
- */
-
-import type { AWMPlugin, AWMPluginContext } from './plugin.js';
-
-/** Loaded plugin instances (for teardown). */
-const loadedPlugins: AWMPlugin[] = [];
-
-/**
- * Load and register all plugins specified in AWM_PLUGINS env var.
- * Errors in individual plugins are logged but don't prevent other plugins from loading.
- */
-export async function loadPlugins(ctx: AWMPluginContext): Promise<void> {
-  const pluginList = process.env.AWM_PLUGINS;
-  if (!pluginList) return;
-
-  const paths = pluginList
-    .split(',')
-    .map((p) => p.trim())
-    .filter(Boolean);
-
-  for (const modulePath of paths) {
-    try {
-      const mod = await import(modulePath);
-      const plugin: AWMPlugin = mod.default ?? mod;
-
-      if (!plugin.name || typeof plugin.register !== 'function') {
-        console.warn(`  [plugin] Skipping ${modulePath}: missing name or register()`);
-        continue;
-      }
-
-      await plugin.register(ctx);
-      loadedPlugins.push(plugin);
-      console.log(`  [plugin] Loaded: ${plugin.name}`);
-    } catch (err) {
-      console.error(`  [plugin] Failed to load ${modulePath}:`, (err as Error).message);
-    }
-  }
-}
-
-/** Teardown all loaded plugins (call on shutdown). */
-export async function teardownPlugins(): Promise<void> {
-  for (const plugin of loadedPlugins) {
-    try {
-      await plugin.teardown?.();
-    } catch (err) {
-      console.error(`  [plugin] Teardown error (${plugin.name}):`, (err as Error).message);
-    }
-  }
-  loadedPlugins.length = 0;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Plugin loader for AWM coordination.
+ *
+ * Reads AWM_PLUGINS env var (comma-separated module paths or package names),
+ * dynamically imports each, and calls register() with the plugin context.
+ *
+ * Usage:
+ *   AWM_PLUGINS=./plugins/slack-notify.js,my-awm-plugin npm start
+ */
+
+import type { AWMPlugin, AWMPluginContext } from './plugin.js';
+
+/** Loaded plugin instances (for teardown). */
+const loadedPlugins: AWMPlugin[] = [];
+
+/**
+ * Load and register all plugins specified in AWM_PLUGINS env var.
+ * Errors in individual plugins are logged but don't prevent other plugins from loading.
+ */
+export async function loadPlugins(ctx: AWMPluginContext): Promise<void> {
+  const pluginList = process.env.AWM_PLUGINS;
+  if (!pluginList) return;
+
+  const paths = pluginList
+    .split(',')
+    .map((p) => p.trim())
+    .filter(Boolean);
+
+  for (const modulePath of paths) {
+    try {
+      const mod = await import(modulePath);
+      const plugin: AWMPlugin = mod.default ?? mod;
+
+      if (!plugin.name || typeof plugin.register !== 'function') {
+        console.warn(`  [plugin] Skipping ${modulePath}: missing name or register()`);
+        continue;
+      }
+
+      await plugin.register(ctx);
+      loadedPlugins.push(plugin);
+      console.log(`  [plugin] Loaded: ${plugin.name}`);
+    } catch (err) {
+      console.error(`  [plugin] Failed to load ${modulePath}:`, (err as Error).message);
+    }
+  }
+}
+
+/** Teardown all loaded plugins (call on shutdown). */
+export async function teardownPlugins(): Promise<void> {
+  for (const plugin of loadedPlugins) {
+    try {
+      await plugin.teardown?.();
+    } catch (err) {
+      console.error(`  [plugin] Teardown error (${plugin.name}):`, (err as Error).message);
+    }
+  }
+  loadedPlugins.length = 0;
+}