onbuzz 4.2.0 → 4.4.0

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

@@ -1,311 +1,219 @@
 /**
- * Tests for GET /api/images (list) and DELETE /api/images (delete).
- * Mirrors the imageServing.test.js mini-app pattern — we mount only the
- * routes under test to avoid booting the whole webServer + orchestrator.
- *
- * Covers:
- *  - list returns empty when no agents / no images
- *  - list enumerates image files from each agent's `images/` folder
- *  - list dedupes overlapping workingDir/projectDir
- *  - list filters by agentId query
- *  - list sorts newest-first
- *  - delete rejects path traversal + bad extensions
- *  - delete removes the file and returns success
- *  - delete returns 404 when the file is already gone
+ * Integration-style tests for /api/images + /api/gallery/images/:filename
+ * (and DELETE /api/images). The routes now delegate to GalleryService,
+ * so these tests build a fresh GalleryService pointed at a tmp dir and
+ * exercise the routes end-to-end.
  */
 
-import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
+import { jest, describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
 import express from 'express';
+import { createServer } from 'http';
 import path from 'path';
-import fs from 'fs/promises';
+import { promises as fs } from 'fs';
 import os from 'os';
-import request from 'supertest';
 
-const HTTP_STATUS = {
-  OK: 200,
-  BAD_REQUEST: 400,
-  FORBIDDEN: 403,
-  NOT_FOUND: 404,
-  SERVICE_UNAVAILABLE: 503,
-  INTERNAL_SERVER_ERROR: 500,
-};
-
-function buildApp({ sessions, orchestrator, logger }) {
+// Redirect userDataDir into a tmp dir so the gallery's writes don't
+// touch the developer's real user data.
+let tmpRoot;
+jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
+  getUserDataDir: () => tmpRoot,
+  getUserDataPaths: () => ({
+    base: tmpRoot,
+    state: path.join(tmpRoot, 'state'),
+    agents: path.join(tmpRoot, 'state', 'agents'),
+    settings: path.join(tmpRoot, 'settings'),
+    attachments: path.join(tmpRoot, 'attachments'),
+    logs: path.join(tmpRoot, 'logs'),
+    cache: path.join(tmpRoot, 'cache'),
+    operations: path.join(tmpRoot, 'state', 'operations'),
+    models: path.join(tmpRoot, 'state', 'models'),
+    runtime: path.join(tmpRoot, 'runtime'),
+    skills: path.join(tmpRoot, 'state', 'skills'),
+    gallery: path.join(tmpRoot, 'gallery'),
+    galleryImages: path.join(tmpRoot, 'gallery', 'images'),
+    galleryVideos: path.join(tmpRoot, 'gallery', 'videos'),
+  }),
+  ensureUserDataDirs: async () => {},
+}));
+
+const { _resetGalleryServiceForTests, getGalleryService } = await import('../../services/galleryService.js');
+const { getUserDataPaths } = await import('../../utilities/userDataDir.js');
+
+const HTTP_STATUS = { OK: 200, BAD_REQUEST: 400, NOT_FOUND: 404, INTERNAL_SERVER_ERROR: 500 };
+
+function buildApp() {
   const app = express();
-  app.use(express.json());
 
-  // ── GET /api/images ─────────────────────────────────────────────
   app.get('/api/images', async (req, res) => {
     try {
-      if (!orchestrator?.agentPool) {
-        return res.json({ success: true, images: [] });
-      }
-      const requestedAgentId = req.query.agentId || null;
-      const agents = await orchestrator.agentPool.getAllAgents();
-      const results = [];
-      const seen = new Set();
-      const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
-
-      for (const agent of (agents instanceof Map ? Array.from(agents.values()) : agents)) {
-        if (requestedAgentId && agent.id !== requestedAgentId) continue;
-        const workDir = agent.directoryAccess?.workingDirectory || agent.projectDir;
-        if (!workDir) continue;
-        const imagesDir = path.join(workDir, 'images');
-        let entries;
-        try { entries = await fs.readdir(imagesDir); } catch { continue; }
-        for (const name of entries) {
-          const ext = path.extname(name).toLowerCase();
-          if (!IMAGE_EXTS.has(ext)) continue;
-          const abs = path.join(imagesDir, name);
-          if (seen.has(abs)) continue;
-          seen.add(abs);
-          let stat;
-          try { stat = await fs.stat(abs); } catch { continue; }
-          if (!stat.isFile()) continue;
-          const anySession = Array.from(sessions.values())[0];
-          const sessionId = agent.sessionId || anySession?.sessionId || 'web-session';
-          results.push({
-            filename: name,
-            agentId: agent.id,
-            agentName: agent.name,
-            projectDir: workDir,
-            mtime: stat.mtime.toISOString(),
-            size: stat.size,
-            url: `/api/images/${encodeURIComponent(sessionId)}/${encodeURIComponent(name)}`,
-          });
-        }
-      }
-      results.sort((a, b) => b.mtime.localeCompare(a.mtime));
-      res.json({ success: true, images: results });
+      const gallery = getGalleryService();
+      const entries = await gallery.listImages({ agentId: req.query.agentId || undefined });
+      const images = entries.map(e => ({
+        ...e, size: e.bytes,
+        url: `/api/gallery/images/${encodeURIComponent(e.filename)}`,
+      }));
+      res.json({ success: true, images });
     } catch (error) {
       res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
     }
   });
 
-  // ── DELETE /api/images ──────────────────────────────────────────
   app.delete('/api/images', async (req, res) => {
     try {
-      const { agentId, filename } = req.query;
-      if (!agentId || !filename) {
-        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'agentId and filename are required' });
-      }
-      const normalized = path.basename(filename);
-      if (normalized !== filename || filename.includes('..')) {
-        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Invalid filename' });
-      }
-      const ext = path.extname(normalized).toLowerCase();
-      if (!['.png', '.jpg', '.jpeg', '.webp', '.gif'].includes(ext)) {
-        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported file extension for gallery delete' });
-      }
-      if (!orchestrator?.agentPool) {
-        return res.status(HTTP_STATUS.SERVICE_UNAVAILABLE).json({ success: false, error: 'Agent pool not available' });
-      }
-      const agent = await orchestrator.agentPool.getAgent(agentId);
-      if (!agent) {
-        return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Agent not found' });
-      }
-      const workDir = agent.directoryAccess?.workingDirectory || agent.projectDir;
-      if (!workDir) {
-        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Agent has no working directory' });
-      }
-      const target = path.join(workDir, 'images', normalized);
-      await fs.unlink(target);
+      const { filename } = req.query;
+      if (!filename) return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'filename is required' });
+      const ok = await getGalleryService().deleteImage(filename);
+      if (!ok) return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
       res.json({ success: true });
     } catch (error) {
-      if (error.code === 'ENOENT') {
-        return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
-      }
+      if (error.code === 'INVALID_FILENAME') return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Invalid filename' });
+      if (error.code === 'INVALID_EXT') return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported file extension' });
       res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
     }
   });
 
+  app.get('/api/gallery/images/:filename', async (req, res) => {
+    const filename = req.params.filename;
+    const normalized = path.basename(filename);
+    if (normalized !== filename || filename.includes('..')) {
+      return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Invalid filename' });
+    }
+    const ext = path.extname(normalized).toLowerCase();
+    if (!['.png', '.jpg', '.jpeg', '.webp', '.gif'].includes(ext)) {
+      return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported extension' });
+    }
+    const target = path.join(getUserDataPaths().galleryImages, normalized);
+    res.sendFile(target, (err) => {
+      if (err && !res.headersSent) res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+    });
+  });
+
   return app;
 }
 
-// ── Fixtures ───────────────────────────────────────────────────────
-let tmpDir;
-let agentADir;
-let agentBDir;
-
-beforeAll(async () => {
-  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gallery-tests-'));
-  agentADir = path.join(tmpDir, 'agentA');
-  agentBDir = path.join(tmpDir, 'agentB');
-  await fs.mkdir(path.join(agentADir, 'images'), { recursive: true });
-  await fs.mkdir(path.join(agentBDir, 'images'), { recursive: true });
-});
-
-afterAll(async () => {
-  await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-});
-
-function makeAgents() {
-  const agentA = {
-    id: 'agentA', name: 'Alice', sessionId: 'sessA',
-    directoryAccess: { workingDirectory: agentADir },
-  };
-  const agentB = {
-    id: 'agentB', name: 'Bob', sessionId: 'sessB',
-    projectDir: agentBDir, // uses projectDir fallback
-  };
-  const byId = new Map([[agentA.id, agentA], [agentB.id, agentB]]);
-  return {
-    agentA, agentB,
-    orchestrator: {
-      agentPool: {
-        getAllAgents: async () => byId,
-        getAgent: async (id) => byId.get(id) || null,
-      },
-    },
-  };
+async function http(url, options = {}) {
+  const resp = await globalThis.fetch(url, options);
+  const body = resp.headers.get('content-type')?.includes('json') ? await resp.json() : await resp.text();
+  return { status: resp.status, body, headers: resp.headers };
 }
 
-function makeSessions() {
-  return new Map([['sessA', { sessionId: 'sessA', projectDir: agentADir }]]);
-}
+describe('gallery routes (GalleryService-backed)', () => {
+  let server, baseUrl;
 
-// ── Tests ──────────────────────────────────────────────────────────
+  async function saveImg(meta = {}, content = 'PNG-DATA') {
+    const srcDir = path.join(tmpRoot, 'src');
+    await fs.mkdir(srcDir, { recursive: true });
+    const src = path.join(srcDir, `${meta.name || 'img'}.png`);
+    await fs.writeFile(src, content);
+    return await getGalleryService().saveImage({ sourcePath: src, metadata: meta });
+  }
 
-describe('GET /api/images', () => {
-  beforeEach(async () => {
-    // Clean + reset fixtures
-    const aDir = path.join(agentADir, 'images');
-    const bDir = path.join(agentBDir, 'images');
-    for (const d of [aDir, bDir]) {
-      const files = await fs.readdir(d).catch(() => []);
-      await Promise.all(files.map(f => fs.unlink(path.join(d, f))));
-    }
+  beforeAll(async () => {
+    tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gallery-routes-'));
+    const app = buildApp();
+    server = createServer(app);
+    await new Promise(r => server.listen(0, r));
+    baseUrl = `http://localhost:${server.address().port}`;
   });
 
-  it('returns empty list when agentPool has no agents', async () => {
-    const app = buildApp({
-      sessions: new Map(),
-      orchestrator: { agentPool: { getAllAgents: async () => [], getAgent: async () => null } },
-      logger: console,
-    });
-    const res = await request(app).get('/api/images');
-    expect(res.status).toBe(200);
-    expect(res.body).toEqual({ success: true, images: [] });
+  afterAll(async () => {
+    server?.close();
+    await fs.rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
   });
 
-  it('returns empty list when agentPool is not wired', async () => {
-    const app = buildApp({ sessions: new Map(), orchestrator: {}, logger: console });
-    const res = await request(app).get('/api/images');
-    expect(res.status).toBe(200);
-    expect(res.body.images).toEqual([]);
+  beforeEach(async () => {
+    _resetGalleryServiceForTests();
+    // Clean gallery dir between tests.
+    const dir = path.join(tmpRoot, 'gallery', 'images');
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => {});
   });
 
-  it('enumerates images from each agent', async () => {
-    await fs.writeFile(path.join(agentADir, 'images', 'a1.png'), 'a1');
-    await fs.writeFile(path.join(agentBDir, 'images', 'b1.jpg'), 'b1');
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).get('/api/images');
-    expect(res.status).toBe(200);
-    const names = res.body.images.map(i => i.filename).sort();
-    expect(names).toEqual(['a1.png', 'b1.jpg']);
-  });
+  // ── GET /api/images ─────────────────────────────────────────
 
-  it('ignores non-image files in the images/ folder', async () => {
-    await fs.writeFile(path.join(agentADir, 'images', 'ok.png'), 'ok');
-    await fs.writeFile(path.join(agentADir, 'images', 'readme.md'), '# hi');
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).get('/api/images');
-    expect(res.body.images.map(i => i.filename)).toEqual(['ok.png']);
+  it('returns empty list when gallery has no entries', async () => {
+    const { status, body } = await http(`${baseUrl}/api/images`);
+    expect(status).toBe(200);
+    expect(body).toEqual({ success: true, images: [] });
   });
 
-  it('filters by agentId query', async () => {
-    await fs.writeFile(path.join(agentADir, 'images', 'a.png'), 'a');
-    await fs.writeFile(path.join(agentBDir, 'images', 'b.png'), 'b');
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).get('/api/images?agentId=agentB');
-    expect(res.body.images).toHaveLength(1);
-    expect(res.body.images[0].filename).toBe('b.png');
+  it('lists saved gallery entries with sidecar metadata', async () => {
+    await saveImg({ name: 'fox', prompt: 'a fox', model: 'dall-e-3', agentId: 'a', agentName: 'Alice' });
+    const { body } = await http(`${baseUrl}/api/images`);
+    expect(body.images).toHaveLength(1);
+    const img = body.images[0];
+    expect(img.prompt).toBe('a fox');
+    expect(img.model).toBe('dall-e-3');
+    expect(img.agentId).toBe('a');
+    expect(img.url).toMatch(/^\/api\/gallery\/images\/.*fox\.png$/);
   });
 
-  it('returns url pointing to /api/images/:sessionId/:filename', async () => {
-    await fs.writeFile(path.join(agentADir, 'images', 'u.png'), 'u');
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).get('/api/images');
-    expect(res.body.images[0].url).toBe('/api/images/sessA/u.png');
+  it('filters by agentId', async () => {
+    await saveImg({ name: 'a', agentId: 'agent-A' });
+    await saveImg({ name: 'b', agentId: 'agent-B' });
+    const { body } = await http(`${baseUrl}/api/images?agentId=agent-B`);
+    expect(body.images).toHaveLength(1);
+    expect(body.images[0].agentId).toBe('agent-B');
   });
 
-  it('sorts newest-first by mtime', async () => {
-    await fs.writeFile(path.join(agentADir, 'images', 'old.png'), 'x');
-    // Delay then write newer so mtime is distinguishable.
-    await new Promise(r => setTimeout(r, 15));
-    await fs.writeFile(path.join(agentADir, 'images', 'new.png'), 'x');
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).get('/api/images');
-    expect(res.body.images.map(i => i.filename)).toEqual(['new.png', 'old.png']);
-  });
-});
+  // ── DELETE /api/images ──────────────────────────────────────
 
-describe('DELETE /api/images', () => {
-  beforeEach(async () => {
-    // Reset state for each test
-    const aDir = path.join(agentADir, 'images');
-    const files = await fs.readdir(aDir).catch(() => []);
-    await Promise.all(files.map(f => fs.unlink(path.join(aDir, f))));
+  it('rejects missing filename param', async () => {
+    const { status } = await http(`${baseUrl}/api/images`, { method: 'DELETE' });
+    expect(status).toBe(400);
   });
 
-  it('rejects missing params', async () => {
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).delete('/api/images');
-    expect(res.status).toBe(400);
-    expect(res.body.error).toMatch(/required/);
+  it('rejects path traversal', async () => {
+    const { status, body } = await http(
+      `${baseUrl}/api/images?filename=..%2Fetc%2Fpasswd`,
+      { method: 'DELETE' }
+    );
+    expect(status).toBe(400);
+    expect(body.error).toMatch(/Invalid filename/);
   });
 
-  it('rejects path traversal in filename', async () => {
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).delete('/api/images?agentId=agentA&filename=..%2Fetc%2Fpasswd');
-    expect(res.status).toBe(400);
-    expect(res.body.error).toMatch(/Invalid filename/);
+  it('rejects non-image extension', async () => {
+    const { status, body } = await http(
+      `${baseUrl}/api/images?filename=secret.txt`,
+      { method: 'DELETE' }
+    );
+    expect(status).toBe(400);
+    expect(body.error).toMatch(/Unsupported/);
   });
 
-  it('rejects non-image extension', async () => {
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).delete('/api/images?agentId=agentA&filename=secret.txt');
-    expect(res.status).toBe(400);
-    expect(res.body.error).toMatch(/Unsupported file extension/);
+  it('returns 404 when the gallery entry does not exist', async () => {
+    const { status } = await http(`${baseUrl}/api/images?filename=ghost.png`, { method: 'DELETE' });
+    expect(status).toBe(404);
   });
 
-  it('returns 404 when agent is unknown', async () => {
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).delete('/api/images?agentId=nobody&filename=x.png');
-    expect(res.status).toBe(404);
+  it('deletes an existing gallery entry + its sidecar', async () => {
+    const saved = await saveImg({ prompt: 'deleting' });
+    const { status, body } = await http(
+      `${baseUrl}/api/images?filename=${encodeURIComponent(saved.filename)}`,
+      { method: 'DELETE' }
+    );
+    expect(status).toBe(200);
+    expect(body.success).toBe(true);
+    await expect(fs.access(saved.path)).rejects.toBeTruthy();
+    await expect(fs.access(`${saved.path}.json`)).rejects.toBeTruthy();
   });
 
-  it('returns 404 when the file does not exist', async () => {
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).delete('/api/images?agentId=agentA&filename=missing.png');
-    expect(res.status).toBe(404);
+  // ── GET /api/gallery/images/:filename ──────────────────────
+
+  it('serves a gallery image by filename', async () => {
+    const saved = await saveImg({ prompt: 'serve-me' }, 'PNG-BYTES');
+    const resp = await globalThis.fetch(`${baseUrl}/api/gallery/images/${encodeURIComponent(saved.filename)}`);
+    expect(resp.status).toBe(200);
+    const buf = await resp.text();
+    expect(buf).toBe('PNG-BYTES');
   });
 
-  it('deletes an existing image', async () => {
-    const target = path.join(agentADir, 'images', 'gone.png');
-    await fs.writeFile(target, 'data');
-    const { orchestrator } = makeAgents();
-    const app = buildApp({ sessions: makeSessions(), orchestrator, logger: console });
-    const res = await request(app).delete('/api/images?agentId=agentA&filename=gone.png');
-    expect(res.status).toBe(200);
-    expect(res.body.success).toBe(true);
-    // File is actually gone
-    await expect(fs.access(target)).rejects.toBeTruthy();
+  it('serve route rejects path traversal', async () => {
+    const { status } = await http(`${baseUrl}/api/gallery/images/..%2Fetc%2Fshadow.png`);
+    expect(status).toBe(400);
   });
 
-  it('returns 503 when agentPool is not wired', async () => {
-    const app = buildApp({ sessions: new Map(), orchestrator: {}, logger: console });
-    const res = await request(app).delete('/api/images?agentId=x&filename=y.png');
-    expect(res.status).toBe(503);
+  it('serve route returns 404 for unknown filename', async () => {
+    const { status } = await http(`${baseUrl}/api/gallery/images/does-not-exist.png`);
+    expect(status).toBe(404);
   });
 });

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();
+  });
+});