onbuzz 4.3.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

package/src/core/__tests__/agentScheduler.visualizer.test.js

@@ -0,0 +1,258 @@
+/**
+ * Tests for the scheduler-visualizer surface on AgentScheduler.
+ *
+ * Covers the in-memory bookkeeping that backs the /scheduler page:
+ *   - _recordCycle ring buffer (push + trim to _CYCLE_HISTORY_MAX)
+ *   - lock acquire/release timestamping (_lockAcquiredAt)
+ *   - processingCycle records exactly one entry per outcome path
+ *       idle / all-locked / concurrency-cap / launched
+ *   - getState() shape: scheduler block, locks block, agent rows
+ *   - lockHeldMs reflects elapsed time since acquisition
+ *
+ * No real agent processing is exercised — we drive processingCycle directly
+ * with a stubbed agent pool so each cycle's outcome is deterministic.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+import AgentScheduler from '../agentScheduler.js';
+import { AGENT_MODES, AGENT_STATUS } from '../../utilities/constants.js';
+
+function makeAgent(overrides = {}) {
+  return {
+    id: 'a1', name: 'Alpha',
+    mode: AGENT_MODES.AGENT,
+    status: AGENT_STATUS.ACTIVE,
+    sessionId: 's1',
+    taskList: { tasks: [{ status: 'pending', content: 'do the thing' }] },
+    messageQueues: { userMessages: [], interAgentMessages: [], toolResults: [] },
+    conversations: { full: { messages: [] } },
+    ...overrides,
+  };
+}
+
+function makeScheduler(agents = [makeAgent()]) {
+  const agentPool = {
+    getAgent: jest.fn(id => Promise.resolve(agents.find(a => a.id === id) || null)),
+    getAllAgents: jest.fn().mockResolvedValue(agents),
+    persistAgentState: jest.fn().mockResolvedValue(undefined),
+    getCompactionMetadata: jest.fn().mockResolvedValue(null),
+    getMessagesForAI: jest.fn().mockResolvedValue([]),
+  };
+  const messageProcessor = {
+    extractAndExecuteTools: jest.fn().mockResolvedValue([]),
+    extractToolCommands: jest.fn().mockResolvedValue([]),
+  };
+  const aiService = {
+    sendMessage: jest.fn().mockResolvedValue({ content: 'x', tokenUsage: {} }),
+    abortRequest: jest.fn().mockReturnValue(false),
+    getActiveRequest: jest.fn().mockReturnValue(null),
+  };
+  const webSocketManager = { broadcastToSession: jest.fn() };
+  const scheduler = new AgentScheduler(
+    agentPool, messageProcessor, aiService,
+    createMockLogger(), webSocketManager
+  );
+  // Don't actually spawn timers — we drive processingCycle by hand.
+  scheduler.broadcastAgentStateUpdate = jest.fn().mockResolvedValue(undefined);
+  // Stub processAgentsInParallel: a real launch acquires the lock inside
+  // processAgent, but for visualizer tests we only care about pre-launch
+  // bookkeeping (skip lists, recorded cycle entries). Make it a no-op.
+  scheduler.processAgentsInParallel = jest.fn().mockResolvedValue(undefined);
+  return { scheduler, agents, agentPool, aiService };
+}
+
+describe('_recordCycle ring buffer', () => {
+  test('appends entries newest-last', () => {
+    const { scheduler } = makeScheduler();
+    scheduler._recordCycle({ n: 1, outcome: 'idle' });
+    scheduler._recordCycle({ n: 2, outcome: 'launched' });
+    expect(scheduler._cycleHistory).toHaveLength(2);
+    expect(scheduler._cycleHistory[0].n).toBe(1);
+    expect(scheduler._cycleHistory[1].n).toBe(2);
+  });
+
+  test('trims to _CYCLE_HISTORY_MAX, keeping the newest entries', () => {
+    const { scheduler } = makeScheduler();
+    scheduler._CYCLE_HISTORY_MAX = 5;
+    for (let i = 1; i <= 12; i++) scheduler._recordCycle({ n: i, outcome: 'idle' });
+    expect(scheduler._cycleHistory).toHaveLength(5);
+    expect(scheduler._cycleHistory[0].n).toBe(8);   // 12-5+1
+    expect(scheduler._cycleHistory[4].n).toBe(12);
+  });
+});
+
+describe('processingCycle records one entry per outcome', () => {
+  test('outcome=idle when no agent is active', async () => {
+    const idleAgent = makeAgent({ taskList: { tasks: [] } });   // no pending tasks → not active
+    const { scheduler } = makeScheduler([idleAgent]);
+    await scheduler.processingCycle();
+    expect(scheduler._cycleHistory).toHaveLength(1);
+    expect(scheduler._cycleHistory[0].outcome).toBe('idle');
+    expect(scheduler._cycleHistory[0].activeCount).toBe(0);
+    expect(scheduler._cycleHistory[0].launched).toEqual([]);
+  });
+
+  test('outcome=all-locked when every active agent is already locked', async () => {
+    const { scheduler } = makeScheduler();
+    // Pre-lock the only active agent.
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date());
+    await scheduler.processingCycle();
+    expect(scheduler._cycleHistory).toHaveLength(1);
+    expect(scheduler._cycleHistory[0].outcome).toBe('all-locked');
+    expect(scheduler._cycleHistory[0].skippedLocked).toEqual(['a1']);
+    expect(scheduler._cycleHistory[0].launched).toEqual([]);
+  });
+
+  test('outcome=launched and includes the agent id in launched[]', async () => {
+    const { scheduler } = makeScheduler();
+    await scheduler.processingCycle();
+    expect(scheduler._cycleHistory).toHaveLength(1);
+    expect(scheduler._cycleHistory[0].outcome).toBe('launched');
+    expect(scheduler._cycleHistory[0].launched).toEqual(['a1']);
+    expect(scheduler._cycleHistory[0].activeCount).toBe(1);
+    expect(scheduler._cycleHistory[0].active[0]).toMatchObject({ agentId: 'a1', name: 'Alpha' });
+  });
+
+  test('outcome=concurrency-cap when slots are exhausted by in-flight work', async () => {
+    // Two active agents, but pretend the cap is already saturated by 3 unrelated
+    // in-flight ids. unlockedAgents.length > 0 but slotsAvailable === 0.
+    const a = makeAgent({ id: 'a1', name: 'A' });
+    const b = makeAgent({ id: 'a2', name: 'B' });
+    const { scheduler } = makeScheduler([a, b]);
+    // Saturate concurrency. Default MAX_CONCURRENT_AGENTS in scheduler = 3.
+    scheduler.agentProcessingLocks.set('ghost-1', true);
+    scheduler.agentProcessingLocks.set('ghost-2', true);
+    scheduler.agentProcessingLocks.set('ghost-3', true);
+    await scheduler.processingCycle();
+    const entry = scheduler._cycleHistory.at(-1);
+    expect(entry.outcome).toBe('concurrency-cap');
+    expect(entry.launched).toEqual([]);
+    expect(entry.skippedConcurrency.length).toBe(2);  // a1 + a2 both deferred
+    expect(entry.skippedLocked).toEqual([]);
+  });
+
+  test('cycleCounter increments monotonically, n matches the cycle order', async () => {
+    const { scheduler } = makeScheduler();
+    await scheduler.processingCycle();
+    await scheduler.processingCycle();
+    await scheduler.processingCycle();
+    expect(scheduler._cycleCounter).toBe(3);
+    const ns = scheduler._cycleHistory.map(c => c.n);
+    expect(ns).toEqual([1, 2, 3]);
+  });
+});
+
+describe('lock timestamping', () => {
+  test('processAgent acquires lock + records timestamp; release clears both', async () => {
+    const { scheduler } = makeScheduler();
+    // Stub the heavy bits inside processAgent so we exercise just the
+    // lock-acquire/release path.
+    scheduler._processAgentInner = jest.fn().mockResolvedValue(undefined);
+    // The simplest check: drive the lock map directly via the same code path
+    // processAgent uses (set + _lockAcquiredAt.set / delete + delete).
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date(Date.now() - 1234));
+    expect(scheduler.agentProcessingLocks.has('a1')).toBe(true);
+    expect(scheduler._lockAcquiredAt.get('a1')).toBeInstanceOf(Date);
+    // Release path
+    scheduler.agentProcessingLocks.delete('a1');
+    scheduler._lockAcquiredAt.delete('a1');
+    expect(scheduler.agentProcessingLocks.has('a1')).toBe(false);
+    expect(scheduler._lockAcquiredAt.has('a1')).toBe(false);
+  });
+
+  test('removeAgent clears the lock-acquired timestamp', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date());
+    scheduler.removeAgent('a1', 'unit-test');
+    expect(scheduler._lockAcquiredAt.has('a1')).toBe(false);
+    expect(scheduler.agentProcessingLocks.has('a1')).toBe(false);
+  });
+
+  test('stop() clears the entire _lockAcquiredAt map and _cycleHistory', () => {
+    const { scheduler } = makeScheduler();
+    // stop() early-returns if !isRunning. Force the running flag so cleanup runs.
+    scheduler.isRunning = true;
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date());
+    scheduler._recordCycle({ n: 1, outcome: 'idle' });
+    scheduler.stop();
+    expect(scheduler._lockAcquiredAt.size).toBe(0);
+    expect(scheduler._cycleHistory.length).toBe(0);
+  });
+});
+
+describe('getState() snapshot shape', () => {
+  test('top-level shape: serverTime, scheduler{}, locks[], cycles[], agents[]', async () => {
+    const { scheduler } = makeScheduler();
+    const state = await scheduler.getState();
+    expect(state).toMatchObject({
+      serverTime: expect.any(String),
+      scheduler: expect.objectContaining({
+        running: expect.any(Boolean),
+        iterationDelayMs: expect.any(Number),
+        maxConcurrent: expect.any(Number),
+        currentlyInFlight: expect.any(Number),
+        cycleCount: expect.any(Number),
+      }),
+      locks: expect.any(Array),
+      cycles: expect.any(Array),
+      agents: expect.any(Array),
+    });
+    // serverTime is ISO-parseable
+    expect(Number.isNaN(new Date(state.serverTime).getTime())).toBe(false);
+  });
+
+  test('agent row carries activity/lockHeld/queues/tasks fields', async () => {
+    const { scheduler } = makeScheduler();
+    const state = await scheduler.getState();
+    expect(state.agents).toHaveLength(1);
+    const row = state.agents[0];
+    expect(row).toMatchObject({
+      id: 'a1', name: 'Alpha',
+      mode: AGENT_MODES.AGENT,
+      status: AGENT_STATUS.ACTIVE,
+      lockHeld: false,
+      lockHeldMs: null,
+      activity: expect.objectContaining({ active: expect.any(Boolean) }),
+      tasks: expect.objectContaining({ total: 1, pending: 1 }),
+      queues: expect.objectContaining({ userMessages: 0, interAgentMessages: 0, toolResults: 0 }),
+    });
+  });
+
+  test('lockHeldMs is non-null and ≥ 0 once the lock is held', async () => {
+    const { scheduler } = makeScheduler();
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date(Date.now() - 50));
+    const state = await scheduler.getState();
+    const row = state.agents.find(r => r.id === 'a1');
+    expect(row.lockHeld).toBe(true);
+    expect(typeof row.lockHeldMs).toBe('number');
+    expect(row.lockHeldMs).toBeGreaterThanOrEqual(40);   // tolerate timer slop
+    // locks[] surfaces it too
+    expect(state.locks).toEqual([
+      expect.objectContaining({ agentId: 'a1', heldMs: expect.any(Number) }),
+    ]);
+    expect(state.scheduler.currentlyInFlight).toBe(1);
+  });
+
+  test('cycles[] reflects what was recorded by processingCycle', async () => {
+    const { scheduler } = makeScheduler();
+    await scheduler.processingCycle();   // outcome=launched, n=1
+    const state = await scheduler.getState();
+    expect(state.cycles).toHaveLength(1);
+    expect(state.cycles[0]).toMatchObject({ n: 1, outcome: 'launched', launched: ['a1'] });
+    expect(state.scheduler.cycleCount).toBe(1);
+  });
+
+  test('survives an agent without a taskList / messageQueues without throwing', async () => {
+    const stub = makeAgent({ id: 'a1', taskList: undefined, messageQueues: undefined });
+    const { scheduler } = makeScheduler([stub]);
+    const state = await scheduler.getState();
+    expect(state.agents[0].tasks).toMatchObject({ total: 0, pending: 0, inProgress: 0, completed: 0 });
+    expect(state.agents[0].queues).toMatchObject({ userMessages: 0, interAgentMessages: 0, toolResults: 0 });
+  });
+});

package/src/core/agentScheduler.js

@@ -981,7 +981,13 @@ class AgentScheduler {
         role: MESSAGE_ROLES.USER,
         content: boundaryContent.trim(),
         timestamp: new Date().toISOString(),
-        type: 'task-boundary'
+        // `task-boundary` stays as the specific subtype, but it IS a
+        // tool-result drain — mark it so downstream consumers (UI filter,
+        // token accounting, export) can treat it uniformly without
+        // having to enumerate every subtype.
+        type: 'task-boundary',
+        isToolResultInjection: true,
+        originalMessageCount: staleCount,
       }, false);
 
       queues.toolResults.length = 0;

package/src/index.js

@@ -485,6 +485,14 @@ class LoxiaApplication {
     // Register WhatsApp Tool
     await this.toolsRegistry.registerTool(WhatsAppTool);
 
+    // widget-module: remove this block if the module is deleted.
+    // Registers the WidgetTool for agent-facing custom-UI rendering.
+    // Honors LOXIA_DISABLE_WIDGETS=1 env flag for a zero-source kill switch.
+    const widgetModule = await import('./modules/widget/index.js');
+    if (!widgetModule.isDisabled()) {
+      await this.toolsRegistry.registerTool(widgetModule.WidgetTool);
+    }
+
     // Set ToolsRegistry dependency for HelpTool (two-layer tool description system)
     const helpTool = this.toolsRegistry.getTool('help');
     if (helpTool && typeof helpTool.setToolsRegistry === 'function') {

package/src/interfaces/__tests__/schedulerRoutes.test.js

@@ -0,0 +1,176 @@
+/**
+ * HTTP route tests for the scheduler visualizer.
+ *
+ * Mounts a real Express app + the production registerSchedulerRoutes helper
+ * — same shape webServer.js uses — so this catches the class of bug we hit
+ * with the widget routes (handler reading from the wrong owner).
+ *
+ * Coverage:
+ *   GET /api/scheduler/state — 200 happy path, 503 when scheduler missing,
+ *                              503 when scheduler has no getState method,
+ *                              500 on getState throw, late-attach via thunk.
+ *   GET /scheduler           — 200 + html content-type + body equals supplied html.
+ */
+
+import { jest, describe, it, expect, beforeAll, afterAll } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import { registerSchedulerRoutes } from '../schedulerRoutes.js';
+
+async function http(url, options = {}) {
+  const resp = await globalThis.fetch(url, options);
+  const ct = resp.headers.get('content-type') || '';
+  const body = ct.includes('json') ? await resp.json() : await resp.text();
+  return { status: resp.status, body, headers: resp.headers };
+}
+
+function startApp(deps) {
+  const app = express();
+  registerSchedulerRoutes(app, deps);
+  const server = createServer(app);
+  return new Promise(resolve => {
+    server.listen(0, () => {
+      const port = server.address().port;
+      resolve({ server, baseUrl: `http://localhost:${port}` });
+    });
+  });
+}
+
+describe('GET /api/scheduler/state — happy path', () => {
+  let server, baseUrl;
+  const SNAPSHOT = {
+    serverTime: '2026-04-25T10:00:00.000Z',
+    scheduler: { running: true, iterationDelayMs: 1000, maxConcurrent: 3, currentlyInFlight: 0, cycleCount: 7, cycleHistoryMax: 200 },
+    locks: [],
+    cycles: [{ n: 7, outcome: 'idle', at: '2026-04-25T10:00:00.000Z' }],
+    agents: [{ id: 'a1', name: 'A', activity: { active: true, reason: 'has-pending-tasks' } }],
+  };
+  beforeAll(async () => {
+    const fakeScheduler = { getState: jest.fn().mockResolvedValue(SNAPSHOT) };
+    ({ server, baseUrl } = await startApp({
+      getScheduler: () => fakeScheduler,
+      logger: { error: jest.fn() },
+      html: '<html>viz</html>',
+    }));
+  });
+  afterAll(() => server?.close());
+
+  it('returns 200 with the full snapshot shape', async () => {
+    const r = await http(`${baseUrl}/api/scheduler/state`);
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual(SNAPSHOT);
+  });
+});
+
+describe('GET /api/scheduler/state — 503 paths (scheduler not attached / wrong shape)', () => {
+  it('503 when getScheduler() returns null (boot ordering)', async () => {
+    const { server, baseUrl } = await startApp({
+      getScheduler: () => null,
+      logger: { error: jest.fn() },
+      html: '<x/>',
+    });
+    try {
+      const r = await http(`${baseUrl}/api/scheduler/state`);
+      expect(r.status).toBe(503);
+      expect(r.body).toMatchObject({ error: expect.stringMatching(/not attached/) });
+    } finally { server.close(); }
+  });
+
+  it('503 when getScheduler() returns an object missing getState (defensive)', async () => {
+    const { server, baseUrl } = await startApp({
+      getScheduler: () => ({ /* no getState */ }),
+      logger: { error: jest.fn() },
+      html: '<x/>',
+    });
+    try {
+      const r = await http(`${baseUrl}/api/scheduler/state`);
+      expect(r.status).toBe(503);
+    } finally { server.close(); }
+  });
+
+  it('503 when no getScheduler dep is supplied at all', async () => {
+    const { server, baseUrl } = await startApp({ logger: { error: jest.fn() }, html: '<x/>' });
+    try {
+      const r = await http(`${baseUrl}/api/scheduler/state`);
+      expect(r.status).toBe(503);
+    } finally { server.close(); }
+  });
+});
+
+describe('GET /api/scheduler/state — 500 path', () => {
+  it('returns 500 with the error message when getState throws', async () => {
+    const errorLog = jest.fn();
+    const fakeScheduler = { getState: jest.fn().mockRejectedValue(new Error('boom')) };
+    const { server, baseUrl } = await startApp({
+      getScheduler: () => fakeScheduler,
+      logger: { error: errorLog },
+      html: '<x/>',
+    });
+    try {
+      const r = await http(`${baseUrl}/api/scheduler/state`);
+      expect(r.status).toBe(500);
+      expect(r.body).toMatchObject({ error: 'boom' });
+      expect(errorLog).toHaveBeenCalledWith(
+        expect.stringMatching(/scheduler state/i),
+        expect.objectContaining({ error: 'boom' }),
+      );
+    } finally { server.close(); }
+  });
+});
+
+describe('thunk semantics: scheduler attached AFTER route registration', () => {
+  it('first call 503s, then 200 once getScheduler() starts returning the scheduler', async () => {
+    let scheduler = null;
+    const { server, baseUrl } = await startApp({
+      getScheduler: () => scheduler,
+      logger: { error: jest.fn() },
+      html: '<x/>',
+    });
+    try {
+      const r1 = await http(`${baseUrl}/api/scheduler/state`);
+      expect(r1.status).toBe(503);
+      // Late-attach: this is the production-relevant scenario — webServer
+      // mounts routes before orchestrator has wired the scheduler in.
+      scheduler = { getState: jest.fn().mockResolvedValue({ ok: true, agents: [], cycles: [], locks: [], scheduler: {}, serverTime: 'x' }) };
+      const r2 = await http(`${baseUrl}/api/scheduler/state`);
+      expect(r2.status).toBe(200);
+      expect(r2.body).toMatchObject({ ok: true });
+    } finally { server.close(); }
+  });
+});
+
+describe('GET /scheduler — HTML viewer page', () => {
+  it('200 + text/html + supplied html body', async () => {
+    const html = '<!doctype html><title>UNIQUE-MARKER</title>';
+    const { server, baseUrl } = await startApp({
+      getScheduler: () => ({ getState: async () => ({}) }),
+      logger: { error: jest.fn() },
+      html,
+    });
+    try {
+      const r = await http(`${baseUrl}/scheduler`);
+      expect(r.status).toBe(200);
+      expect(r.headers.get('content-type')).toMatch(/html/);
+      expect(r.body).toBe(html);
+      expect(r.body).toContain('UNIQUE-MARKER');
+    } finally { server.close(); }
+  });
+
+  it('falls back to a built-in stub html when none is supplied (defensive)', async () => {
+    const { server, baseUrl } = await startApp({ getScheduler: () => null });
+    try {
+      const r = await http(`${baseUrl}/scheduler`);
+      expect(r.status).toBe(200);
+      expect(r.headers.get('content-type')).toMatch(/html/);
+      expect(typeof r.body).toBe('string');
+      expect(r.body.length).toBeGreaterThan(0);
+    } finally { server.close(); }
+  });
+});
+
+describe('registerSchedulerRoutes — defensive guards', () => {
+  it('no-ops when app is null/undefined (does not throw)', () => {
+    expect(() => registerSchedulerRoutes(null, {})).not.toThrow();
+    expect(() => registerSchedulerRoutes(undefined, {})).not.toThrow();
+  });
+});

package/src/interfaces/schedulerRoutes.js

@@ -0,0 +1,50 @@
+/**
+ * Scheduler visualizer routes — extracted from webServer.js so they're
+ * testable against the real production wiring (the lesson from the widget
+ * routes 503 incident: tests that don't match production shape don't catch
+ * production bugs).
+ *
+ * Two routes:
+ *   GET /api/scheduler/state   — JSON snapshot from scheduler.getState()
+ *   GET /scheduler             — self-contained HTML viewer page
+ *
+ * Registration:
+ *   registerSchedulerRoutes(app, {
+ *     getScheduler: () => orchestrator?.agentPool?.scheduler,
+ *     logger,
+ *     html: SCHEDULER_VIEWER_HTML,
+ *   });
+ *
+ * `getScheduler` is a thunk (not the scheduler itself) so the routes resolve
+ * the scheduler at request-time — handles the case where the scheduler is
+ * attached after the routes are registered (orchestrator startup ordering).
+ */
+
+export function registerSchedulerRoutes(app, deps = {}) {
+  if (!app) return;
+  const getScheduler = typeof deps.getScheduler === 'function' ? deps.getScheduler : () => null;
+  const logger = deps.logger || { error: () => {} };
+  const html = typeof deps.html === 'string' ? deps.html : '<!doctype html><title>scheduler</title>';
+
+  // JSON snapshot of scheduler + all agents — polled by /scheduler at 1 Hz.
+  app.get('/api/scheduler/state', async (req, res) => {
+    try {
+      const sched = getScheduler();
+      if (!sched || typeof sched.getState !== 'function') {
+        return res.status(503).json({ error: 'scheduler is not attached' });
+      }
+      const state = await sched.getState();
+      res.json(state);
+    } catch (err) {
+      try { logger.error('Failed to build scheduler state', { error: err?.message }); } catch (_) {}
+      res.status(500).json({ error: err?.message || 'unknown' });
+    }
+  });
+
+  // Self-contained HTML viewer page (no external assets).
+  app.get('/scheduler', (req, res) => {
+    res.type('html').send(html);
+  });
+}
+
+export default { registerSchedulerRoutes };

package/src/interfaces/webServer.js

@@ -44,6 +44,9 @@ import { initFileExplorerModule } from '../modules/fileExplorer/index.js';
 // Import FlowExecutor for flow pipeline execution
 import FlowExecutor from '../core/flowExecutor.js';
 
+// Scheduler visualizer routes (extracted for testability)
+import { registerSchedulerRoutes } from './schedulerRoutes.js';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -432,7 +435,7 @@ class WebServer {
   async initialize() {
     try {
       this.setupMiddleware();
-      this.setupRoutes();
+      await this.setupRoutes();
       this.setupWebSocket();
 
       await this.startServer();
@@ -661,7 +664,61 @@ class WebServer {
    * Setup API routes
    * @private
    */
-  setupRoutes() {
+  async setupRoutes() {
+    // widget-module: remove this block if the module is deleted.
+    // Mounts the widget runtime asset + audit routes under /api/widget/*.
+    // AWAITED BEFORE other routes: Express matches routes in registration
+    // order, and the SPA catch-all registered later in this file matches
+    // EVERY GET request — if widget routes aren't in place first, the
+    // fallback returns index.html for /api/widget/runtime.js and the
+    // iframe tries to parse HTML as JS ("Unexpected token '<'").
+    try {
+      const mod = await import('../modules/widget/index.js');
+      if (!mod.isDisabled()) {
+        // The orchestrator does NOT carry toolsRegistry in production —
+        // it lives on `this` (the WebServer). Other route handlers in
+        // this file work around it with a `this.toolsRegistry || ...
+        // orchestrator?.toolsRegistry` fallback. Pass both explicitly
+        // so the widget module's routes resolve the tool reliably.
+        mod.registerRoutes(this.app, this.orchestrator, {
+          toolsRegistry: this.toolsRegistry,
+        });
+        this.logger.info('Widget module routes registered');
+
+        // Bridge the WidgetTool's event bus to a `widget_changed` WebSocket
+        // push. The artifacts panel listens for these so its summary cache
+        // stays current — independent of whether the chat feed has the
+        // tool-result message mounted (the feed is lazily virtualized; old
+        // entries unload as the user scrolls and would otherwise be missed).
+        try {
+          const widgetTool =
+            this.toolsRegistry?.getTool?.('widget') ||
+            this.orchestrator?.toolsRegistry?.getTool?.('widget');
+          if (widgetTool?.events?.on) {
+            widgetTool.events.on('widget-changed', (evt) => {
+              try {
+                // sessionId=null → broadcastToSession falls back to all
+                // connections. The frontend filters on currentAgent.
+                this.broadcastToSession(null, {
+                  type: 'widget_changed',
+                  data: evt,
+                });
+              } catch (err) {
+                this.logger.warn('Failed to broadcast widget_changed', { error: err.message });
+              }
+            });
+            this.logger.info('Widget event bus bridged to WebSocket');
+          } else {
+            this.logger.warn('Widget tool has no events bus — push updates disabled');
+          }
+        } catch (err) {
+          this.logger.warn('Widget event bus subscribe failed', { error: err.message });
+        }
+      }
+    } catch (err) {
+      this.logger.warn('Widget module not available', { error: err.message });
+    }
+
     // Health check
     this.app.get('/api/health', async (req, res) => {
       try {
@@ -3428,24 +3485,13 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
     // Scheduler Visualizer — JSON state endpoint + HTML viewer
     // ============================================
 
-    // JSON snapshot of scheduler + all agents — polled by /scheduler at 1 Hz.
-    this.app.get('/api/scheduler/state', async (req, res) => {
-      try {
-        const sched = this.orchestrator?.agentPool?.scheduler;
-        if (!sched?.getState) {
-          return res.status(503).json({ error: 'scheduler is not attached' });
-        }
-        const state = await sched.getState();
-        res.json(state);
-      } catch (err) {
-        this.logger.error('Failed to build scheduler state', { error: err.message });
-        res.status(500).json({ error: err.message });
-      }
-    });
-
-    // Self-contained HTML viewer. See SCHEDULER_VIEWER_HTML below.
-    this.app.get('/scheduler', (req, res) => {
-      res.type('html').send(SCHEDULER_VIEWER_HTML);
+    // Mount scheduler visualizer routes via the extracted helper. The thunk
+    // form for getScheduler ensures we resolve the scheduler at request time
+    // (it may be attached after route registration during orchestrator boot).
+    registerSchedulerRoutes(this.app, {
+      getScheduler: () => this.orchestrator?.agentPool?.scheduler,
+      logger: this.logger,
+      html: SCHEDULER_VIEWER_HTML,
     });
 
     // ============================================