switchroom 0.7.15 → 0.10.0

package/telegram-plugin/tests/gateway-startup-network-retry.test.ts

@@ -18,6 +18,7 @@ import { describe, it, expect, vi } from 'vitest'
 import {
   isBootNetworkError,
   gatewayStartupRetry,
+  classifyStartupError,
   STARTUP_RETRY_DELAYS_MS,
 } from '../gateway/startup-network-retry'
 
@@ -76,6 +77,57 @@ describe('isBootNetworkError', () => {
   })
 })
 
+// ── classifyStartupError ──────────────────────────────────────────────────────
+
+describe('classifyStartupError', () => {
+  it('classifies grammy 401 (GrammyError, error_code=401) as unauthorized', () => {
+    const err = Object.assign(new Error('Unauthorized'), {
+      name: 'GrammyError',
+      error_code: 401,
+    })
+    expect(classifyStartupError(err)).toBe('unauthorized')
+  })
+
+  it('classifies an Unauthorized-message error as unauthorized — defence in depth', () => {
+    expect(classifyStartupError(new Error('Unauthorized'))).toBe('unauthorized')
+  })
+
+  it('does NOT mis-classify a network error mentioning "401" port as unauthorized', () => {
+    // Hypothetical message that happens to contain "401" but isn't a
+    // 401 status. classifyStartupError matches on the literal token
+    // "Unauthorized" rather than the substring "401" to avoid this.
+    expect(classifyStartupError(new Error('connect ECONNREFUSED 10.0.0.1:401'))).toBe('network')
+  })
+
+  it('classifies HttpError as network', () => {
+    const err = Object.assign(new Error('Network request failed'), {
+      name: 'HttpError',
+    })
+    expect(classifyStartupError(err)).toBe('network')
+  })
+
+  it('classifies ETIMEDOUT as network', () => {
+    expect(classifyStartupError(new Error('connect ETIMEDOUT 1.2.3.4:443'))).toBe('network')
+  })
+
+  it('classifies a bare app error as other', () => {
+    expect(classifyStartupError(new Error('something else'))).toBe('other')
+  })
+
+  it('classifies non-Error values as other', () => {
+    expect(classifyStartupError('string')).toBe('other')
+    expect(classifyStartupError(null)).toBe('other')
+  })
+
+  it('classifies a GrammyError 403 (kicked) as other — surfaces as a fatal rethrow', () => {
+    const err = Object.assign(new Error('Forbidden: bot was kicked'), {
+      name: 'GrammyError',
+      error_code: 403,
+    })
+    expect(classifyStartupError(err)).toBe('other')
+  })
+})
+
 // ── gatewayStartupRetry ───────────────────────────────────────────────────────
 
 describe('gatewayStartupRetry', () => {
@@ -162,6 +214,58 @@ describe('gatewayStartupRetry', () => {
     expect(STARTUP_RETRY_DELAYS_MS[STARTUP_RETRY_DELAYS_MS.length - 1]).toBe(64_000)
   })
 
+  it('calls onUnauthorized (not onExhausted, not rethrow) on a 401 — #1076', async () => {
+    // Grammy surfaces 401 via GrammyError with error_code=401.
+    const authErr = Object.assign(new Error('Unauthorized'), {
+      name: 'GrammyError',
+      error_code: 401,
+    })
+    const fn = vi.fn().mockRejectedValue(authErr)
+    const onUnauthorized = vi.fn(() => {
+      throw new Error('__quarantined__')
+    }) as unknown as (err: unknown) => never
+    const onExhausted = vi.fn(() => {
+      throw new Error('__exhausted__')
+    }) as unknown as (err: unknown) => never
+    const sleep = vi.fn().mockResolvedValue(undefined)
+
+    await expect(
+      gatewayStartupRetry(fn, {
+        delaysMs: [100, 200, 400],
+        sleep,
+        onUnauthorized,
+        onExhausted,
+        log: noopLog,
+      }),
+    ).rejects.toThrow('__quarantined__')
+
+    // 401 short-circuits — only one fn() call, no retries, no exhaustion path.
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(sleep).not.toHaveBeenCalled()
+    expect(onExhausted).not.toHaveBeenCalled()
+    expect(onUnauthorized).toHaveBeenCalledTimes(1)
+    expect(onUnauthorized).toHaveBeenCalledWith(authErr)
+  })
+
+  it('classifies a 401-message-only error (no error_code) as unauthorized — defence in depth', async () => {
+    // Some fetch wrappers / test fixtures surface 401 only in the message.
+    const authErr = new Error('Unauthorized')
+    const fn = vi.fn().mockRejectedValue(authErr)
+    const onUnauthorized = vi.fn(() => {
+      throw new Error('__quarantined__')
+    }) as unknown as (err: unknown) => never
+
+    await expect(
+      gatewayStartupRetry(fn, {
+        delaysMs: [1, 2],
+        sleep: vi.fn(),
+        onUnauthorized,
+        log: noopLog,
+      }),
+    ).rejects.toThrow('__quarantined__')
+    expect(onUnauthorized).toHaveBeenCalledTimes(1)
+  })
+
   it('logs retry progress before each sleep', async () => {
     const networkErr = Object.assign(new Error('Network request failed'), {
       name: 'HttpError',

package/telegram-plugin/tests/history-reaper.test.ts

@@ -0,0 +1,378 @@
+/**
+ * Tests for the history reaper (#1073).
+ *
+ * Covers:
+ *   - `pruneSubagentsOlderThan` / `pruneTurnsOlderThan` correctness:
+ *     rows below the cutoff are deleted, rows above are preserved,
+ *     coalesce semantics (ended_at | last_activity_at | started_at)
+ *     are honored.
+ *   - Batch-loop bounded scan: 6000-row backlog drains across multiple
+ *     batches when batchLimit=2000.
+ *   - WAL checkpoint runs (file-backed DB; assert .db-wal exists and
+ *     shrinks, or at least that checkpoint reports success).
+ *   - `resolveRetentionDays`: env > access > default precedence, plus
+ *     guards against invalid env values.
+ *   - `pruneMessagesOlderThanDays` on the history DB respects the
+ *     batch cap and preserves recent rows.
+ *
+ * Runs under bun (uses bun:sqlite via the schema modules' lazy loader).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { mkdtempSync, rmSync, existsSync, statSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  pruneSubagentsOlderThan,
+  pruneTurnsOlderThan,
+  runRegistryReaper,
+  resolveRetentionDays,
+  DEFAULT_RETENTION_DAYS,
+} from '../registry/reaper.js'
+import {
+  openSubagentsDbInMemory,
+  recordSubagentStart,
+} from '../registry/subagents-schema.js'
+import {
+  initHistory,
+  recordInbound,
+  pruneMessagesOlderThanDays,
+  query as queryHistory,
+  _resetForTests as resetHistory,
+} from '../history.js'
+
+// `bun:sqlite` for direct file-backed DB tests (WAL inspection).
+// Same lazy-load pattern as the schemas use, but inline here.
+type SqliteDatabase = {
+  exec(sql: string): void
+  prepare(sql: string): {
+    run(...params: unknown[]): unknown
+    all(...params: unknown[]): unknown[]
+    get(...params: unknown[]): unknown
+  }
+  close(): void
+}
+type SqliteDatabaseCtor = new (path: string, opts?: { create?: boolean }) => SqliteDatabase
+function bunSqlite(): SqliteDatabaseCtor {
+  const metaRequire = (import.meta as { require?: (id: string) => unknown }).require
+  if (typeof metaRequire !== 'function') throw new Error('bun runtime required')
+  const mod = metaRequire('bun:sqlite') as { Database: SqliteDatabaseCtor }
+  return mod.Database
+}
+
+const DAY_MS = 86_400_000
+
+// ---------------------------------------------------------------------------
+// pruneSubagentsOlderThan
+// ---------------------------------------------------------------------------
+
+describe('pruneSubagentsOlderThan', () => {
+  it('deletes rows older than the cutoff and preserves recent ones', () => {
+    const db = openSubagentsDbInMemory()
+    const now = 1_000_000_000_000
+    // Three rows: 30 days ago, 5 days ago, 1 day ago.
+    recordSubagentStart(db, { id: 'old', background: true, startedAt: now - 30 * DAY_MS })
+    recordSubagentStart(db, { id: 'mid', background: true, startedAt: now - 5 * DAY_MS })
+    recordSubagentStart(db, { id: 'new', background: true, startedAt: now - 1 * DAY_MS })
+
+    // Cutoff: 14 days ago. Only `old` should go.
+    const cutoff = now - 14 * DAY_MS
+    const result = pruneSubagentsOlderThan(db, cutoff)
+    expect(result.deleted).toBe(1)
+
+    const remaining = db.prepare('SELECT id FROM subagents ORDER BY started_at').all() as Array<{ id: string }>
+    expect(remaining.map((r) => r.id)).toEqual(['mid', 'new'])
+  })
+
+  it('uses COALESCE(ended_at, last_activity_at, started_at)', () => {
+    const db = openSubagentsDbInMemory()
+    const now = 1_000_000_000_000
+    // started_at is ancient but last_activity_at is recent — should NOT prune.
+    recordSubagentStart(db, { id: 'still-active', background: true, startedAt: now - 60 * DAY_MS })
+    db.prepare('UPDATE subagents SET last_activity_at = ? WHERE id = ?').run(now - 2 * DAY_MS, 'still-active')
+
+    // started_at + last_activity_at ancient but ended_at recent — should NOT prune.
+    recordSubagentStart(db, { id: 'recent-end', background: true, startedAt: now - 60 * DAY_MS })
+    db.prepare('UPDATE subagents SET last_activity_at = ?, ended_at = ?, status = ? WHERE id = ?')
+      .run(now - 50 * DAY_MS, now - 2 * DAY_MS, 'completed', 'recent-end')
+
+    // Truly old — all three timestamps are ancient.
+    recordSubagentStart(db, { id: 'truly-old', background: true, startedAt: now - 60 * DAY_MS })
+    db.prepare('UPDATE subagents SET last_activity_at = ?, ended_at = ?, status = ? WHERE id = ?')
+      .run(now - 59 * DAY_MS, now - 58 * DAY_MS, 'completed', 'truly-old')
+
+    const cutoff = now - 14 * DAY_MS
+    const result = pruneSubagentsOlderThan(db, cutoff)
+    expect(result.deleted).toBe(1)
+
+    const ids = (db.prepare('SELECT id FROM subagents ORDER BY id').all() as Array<{ id: string }>).map((r) => r.id)
+    expect(ids).toEqual(['recent-end', 'still-active'])
+  })
+
+  it('batches a large backlog and drains it across iterations', () => {
+    const db = openSubagentsDbInMemory()
+    const now = 1_000_000_000_000
+    const insert = db.prepare(`
+      INSERT INTO subagents
+        (id, background, started_at, last_activity_at, status)
+      VALUES (?, 1, ?, ?, 'running')
+    `)
+    const tx = (db as unknown as { transaction: (fn: (n: number) => void) => (n: number) => void })
+      .transaction((n: number) => {
+        for (let i = 0; i < n; i++) {
+          insert.run(`old-${i}`, now - 30 * DAY_MS, now - 30 * DAY_MS)
+        }
+      })
+    tx(6000)
+    // Plus 50 recent rows.
+    for (let i = 0; i < 50; i++) {
+      insert.run(`new-${i}`, now - 1 * DAY_MS, now - 1 * DAY_MS)
+    }
+
+    const cutoff = now - 14 * DAY_MS
+    const result = pruneSubagentsOlderThan(db, cutoff, 2000)
+    expect(result.deleted).toBe(6000)
+    // 6000 / 2000 = 3 full batches + a final 0-row sentinel batch.
+    expect(result.batches).toBeGreaterThanOrEqual(3)
+
+    const remaining = db.prepare('SELECT COUNT(*) as c FROM subagents').get() as { c: number }
+    expect(remaining.c).toBe(50)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// pruneTurnsOlderThan
+// ---------------------------------------------------------------------------
+
+describe('pruneTurnsOlderThan', () => {
+  it('deletes turns older than the cutoff, preserves recent and open turns', () => {
+    const db = openSubagentsDbInMemory()
+    const now = 1_000_000_000_000
+
+    const insert = db.prepare(`
+      INSERT INTO turns
+        (turn_key, chat_id, started_at, ended_at, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `)
+    // ancient + ended → prune
+    insert.run('old-ended', '-100', now - 60 * DAY_MS, now - 59 * DAY_MS, now - 60 * DAY_MS, now - 59 * DAY_MS)
+    // ancient + open → COALESCE falls through to started_at, also prunes
+    insert.run('old-open', '-100', now - 60 * DAY_MS, null, now - 60 * DAY_MS, now - 60 * DAY_MS)
+    // recent + ended → preserve
+    insert.run('recent', '-100', now - 1 * DAY_MS, now - 1 * DAY_MS, now - 1 * DAY_MS, now - 1 * DAY_MS)
+    // ancient started but ended recently → COALESCE picks ended_at, preserves
+    insert.run('long-running', '-100', now - 60 * DAY_MS, now - 1 * DAY_MS, now - 60 * DAY_MS, now - 1 * DAY_MS)
+
+    const cutoff = now - 14 * DAY_MS
+    const result = pruneTurnsOlderThan(db, cutoff)
+    expect(result.deleted).toBe(2)
+
+    const keys = (db.prepare('SELECT turn_key FROM turns ORDER BY turn_key').all() as Array<{ turn_key: string }>).map((r) => r.turn_key)
+    expect(keys).toEqual(['long-running', 'recent'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// runRegistryReaper + WAL checkpoint
+// ---------------------------------------------------------------------------
+
+describe('runRegistryReaper', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'reaper-test-'))
+  })
+
+  afterEach(() => {
+    if (existsSync(tmpDir)) rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('prunes both tables and reports a successful WAL checkpoint', () => {
+    const Database = bunSqlite()
+    const dbPath = join(tmpDir, 'registry.db')
+    const db = new Database(dbPath, { create: true })
+    db.exec('PRAGMA journal_mode = WAL')
+    // Apply both schemas inline (mirrors openTurnsDb + applySubagentsSchema).
+    db.exec(`
+      CREATE TABLE turns (
+        turn_key TEXT PRIMARY KEY,
+        chat_id TEXT NOT NULL,
+        thread_id TEXT,
+        started_at INTEGER NOT NULL,
+        ended_at INTEGER,
+        ended_via TEXT,
+        last_assistant_msg_id TEXT,
+        last_assistant_done INTEGER,
+        last_user_msg_id TEXT,
+        user_prompt_preview TEXT,
+        assistant_reply_preview TEXT,
+        tool_call_count INTEGER,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+      CREATE TABLE subagents (
+        id TEXT PRIMARY KEY,
+        parent_session_id TEXT,
+        parent_turn_key TEXT,
+        agent_type TEXT,
+        description TEXT,
+        background INTEGER NOT NULL,
+        started_at INTEGER NOT NULL,
+        last_activity_at INTEGER,
+        ended_at INTEGER,
+        status TEXT NOT NULL,
+        result_summary TEXT,
+        jsonl_agent_id TEXT
+      );
+    `)
+
+    const now = Date.now()
+    db.prepare(`
+      INSERT INTO subagents (id, background, started_at, last_activity_at, status)
+      VALUES ('old', 1, ?, ?, 'running')
+    `).run(now - 30 * DAY_MS, now - 30 * DAY_MS)
+    db.prepare(`
+      INSERT INTO turns (turn_key, chat_id, started_at, ended_at, created_at, updated_at)
+      VALUES ('old-turn', '-1', ?, ?, ?, ?)
+    `).run(now - 30 * DAY_MS, now - 30 * DAY_MS, now - 30 * DAY_MS, now - 30 * DAY_MS)
+
+    // Force some WAL activity before the checkpoint so there's something to flush.
+    db.prepare(`INSERT INTO turns (turn_key, chat_id, started_at, created_at, updated_at) VALUES ('recent', '-1', ?, ?, ?)`)
+      .run(now, now, now)
+
+    const walPath = `${dbPath}-wal`
+    expect(existsSync(walPath)).toBe(true)
+    const walSizeBefore = statSync(walPath).size
+    expect(walSizeBefore).toBeGreaterThan(0)
+
+    const result = runRegistryReaper(db, { retentionDays: 14, now })
+    expect(result.subagents.deleted).toBe(1)
+    expect(result.turns.deleted).toBe(1)
+    expect(result.walCheckpointed).toBe(true)
+
+    // After TRUNCATE checkpoint, the WAL file is truncated to zero bytes.
+    // (Strict equality may vary across SQLite builds, but the post-truncate
+    // size must be strictly less than the pre-truncate size.)
+    const walSizeAfter = statSync(walPath).size
+    expect(walSizeAfter).toBeLessThan(walSizeBefore)
+
+    db.close()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// resolveRetentionDays
+// ---------------------------------------------------------------------------
+
+describe('resolveRetentionDays', () => {
+  const savedEnv = process.env.HISTORY_RETENTION_DAYS
+
+  afterEach(() => {
+    if (savedEnv === undefined) delete process.env.HISTORY_RETENTION_DAYS
+    else process.env.HISTORY_RETENTION_DAYS = savedEnv
+  })
+
+  it('returns DEFAULT_RETENTION_DAYS when nothing is set', () => {
+    delete process.env.HISTORY_RETENTION_DAYS
+    expect(resolveRetentionDays()).toBe(DEFAULT_RETENTION_DAYS)
+    expect(DEFAULT_RETENTION_DAYS).toBe(14)
+  })
+
+  it('prefers env over access', () => {
+    process.env.HISTORY_RETENTION_DAYS = '1'
+    expect(resolveRetentionDays(30)).toBe(1)
+  })
+
+  it('falls back to access when env is missing', () => {
+    delete process.env.HISTORY_RETENTION_DAYS
+    expect(resolveRetentionDays(7)).toBe(7)
+  })
+
+  it('rejects invalid env values', () => {
+    process.env.HISTORY_RETENTION_DAYS = 'abc'
+    expect(resolveRetentionDays(7)).toBe(7)
+    process.env.HISTORY_RETENTION_DAYS = '0'
+    expect(resolveRetentionDays(7)).toBe(7)
+    process.env.HISTORY_RETENTION_DAYS = '-5'
+    expect(resolveRetentionDays(7)).toBe(7)
+  })
+
+  it('rejects invalid access values', () => {
+    delete process.env.HISTORY_RETENTION_DAYS
+    expect(resolveRetentionDays(0)).toBe(DEFAULT_RETENTION_DAYS)
+    expect(resolveRetentionDays(-1)).toBe(DEFAULT_RETENTION_DAYS)
+    expect(resolveRetentionDays(NaN)).toBe(DEFAULT_RETENTION_DAYS)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// history.ts: pruneMessagesOlderThanDays
+// ---------------------------------------------------------------------------
+
+describe('pruneMessagesOlderThanDays', () => {
+  let stateDir: string
+
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), 'history-reaper-test-'))
+    initHistory(stateDir, 0) // 0 disables the init-time prune so we can seed cleanly
+  })
+
+  afterEach(() => {
+    resetHistory()
+    if (existsSync(stateDir)) rmSync(stateDir, { recursive: true, force: true })
+  })
+
+  it('deletes only messages older than retentionDays', () => {
+    const nowSec = 2_000_000_000
+    // Old (60d ago), borderline (15d ago), recent (1d ago).
+    recordInbound({
+      chat_id: '-100', thread_id: null, message_id: 1, user: 'u', user_id: '1',
+      ts: nowSec - 60 * 86400, text: 'old',
+    })
+    recordInbound({
+      chat_id: '-100', thread_id: null, message_id: 2, user: 'u', user_id: '1',
+      ts: nowSec - 15 * 86400, text: 'mid',
+    })
+    recordInbound({
+      chat_id: '-100', thread_id: null, message_id: 3, user: 'u', user_id: '1',
+      ts: nowSec - 1 * 86400, text: 'new',
+    })
+
+    const deleted = pruneMessagesOlderThanDays(14, nowSec)
+    expect(deleted).toBe(2)
+
+    const remaining = queryHistory({ chat_id: '-100' })
+    expect(remaining.map((r) => r.text)).toEqual(['new'])
+  })
+
+  it('batches a >5k backlog and drains it', () => {
+    const nowSec = 2_000_000_000
+    for (let i = 0; i < 6000; i++) {
+      recordInbound({
+        chat_id: '-100', thread_id: null, message_id: i + 1, user: 'u', user_id: '1',
+        ts: nowSec - 60 * 86400, text: `old-${i}`,
+      })
+    }
+    for (let i = 0; i < 30; i++) {
+      recordInbound({
+        chat_id: '-100', thread_id: null, message_id: 100_000 + i, user: 'u', user_id: '1',
+        ts: nowSec - 1 * 86400, text: `new-${i}`,
+      })
+    }
+    const deleted = pruneMessagesOlderThanDays(14, nowSec, 2000)
+    expect(deleted).toBe(6000)
+    const remaining = queryHistory({ chat_id: '-100', limit: 50 })
+    expect(remaining.length).toBe(30)
+  })
+
+  it('respects retentionDays <= 0 as disabled', () => {
+    const nowSec = 2_000_000_000
+    recordInbound({
+      chat_id: '-100', thread_id: null, message_id: 1, user: 'u', user_id: '1',
+      ts: nowSec - 60 * 86400, text: 'old',
+    })
+    expect(pruneMessagesOlderThanDays(0, nowSec)).toBe(0)
+    expect(pruneMessagesOlderThanDays(-1, nowSec)).toBe(0)
+    expect(queryHistory({ chat_id: '-100' })).toHaveLength(1)
+  })
+})

package/telegram-plugin/tests/hostd-dispatch.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Unit tests for `hostd-dispatch.ts` — the gateway's helper that routes
+ * self-restart slash-commands through the hostd UDS when enabled.
+ *
+ * The config-loading branches are validated by mocking
+ * `loadSwitchroomConfig` (the schema's complexity isn't this test's
+ * concern — we just need to feed it a known value). The wire-error
+ * branch is validated by pointing the helper at a nonexistent socket.
+ *
+ * The "actually hits a real hostd" path is covered in
+ * `tests/host-control/server.test.ts` end-to-end — we don't re-test
+ * the server here.
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  vi,
+} from "vitest";
+
+const loadConfigMock = vi.fn();
+vi.mock("../../src/config/loader.js", () => ({
+  loadConfig: loadConfigMock,
+}));
+
+// Import AFTER the mock so the module captures the mocked function.
+const {
+  tryHostdDispatch,
+  hostdWillBeUsed,
+  isHostdEnabled,
+  hostdSocketPath,
+  _resetHostdEnabledCache,
+} = await import("../gateway/hostd-dispatch.js");
+
+beforeEach(() => {
+  _resetHostdEnabledCache();
+  loadConfigMock.mockReset();
+});
+
+afterEach(() => {
+  _resetHostdEnabledCache();
+});
+
+describe("isHostdEnabled() — config gate", () => {
+  it("returns false when host_control absent", () => {
+    loadConfigMock.mockReturnValue({});
+    expect(isHostdEnabled()).toBe(false);
+  });
+
+  it("returns false when host_control.enabled is false", () => {
+    loadConfigMock.mockReturnValue({ host_control: { enabled: false } });
+    expect(isHostdEnabled()).toBe(false);
+  });
+
+  it("returns true when host_control.enabled is true", () => {
+    loadConfigMock.mockReturnValue({ host_control: { enabled: true } });
+    expect(isHostdEnabled()).toBe(true);
+  });
+
+  it("returns false on config-load throw (best-effort fallback)", () => {
+    // Gateway runs in environments where the config may not be
+    // readable yet (very-early-boot, broken symlink). The helper must
+    // not propagate — it just disables the hostd path.
+    loadConfigMock.mockImplementation(() => {
+      throw new Error("config: file not found");
+    });
+    expect(isHostdEnabled()).toBe(false);
+  });
+
+  it("caches the result across calls (no re-read)", () => {
+    loadConfigMock.mockReturnValue({ host_control: { enabled: true } });
+    expect(isHostdEnabled()).toBe(true);
+    expect(isHostdEnabled()).toBe(true);
+    expect(isHostdEnabled()).toBe(true);
+    expect(loadConfigMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("hostdWillBeUsed() — config + socket existence", () => {
+  it("false when hostd disabled even if socket would be present", () => {
+    loadConfigMock.mockReturnValue({});
+    expect(hostdWillBeUsed("klanker")).toBe(false);
+  });
+
+  it("false when hostd enabled but per-agent socket isn't bound", () => {
+    loadConfigMock.mockReturnValue({ host_control: { enabled: true } });
+    // hostdSocketPath() is hard-coded to /run/switchroom/hostd/<name>/sock
+    // — that path doesn't exist in the test env, so existsSync returns
+    // false and hostdWillBeUsed is false.
+    expect(hostdWillBeUsed("klanker-no-such-agent")).toBe(false);
+  });
+});
+
+describe("tryHostdDispatch()", () => {
+  it("returns 'not-configured' when hostd disabled", async () => {
+    loadConfigMock.mockReturnValue({});
+    const result = await tryHostdDispatch("klanker", {
+      v: 1,
+      op: "agent_restart",
+      request_id: "test-1",
+      args: { name: "klanker", force: true },
+    });
+    expect(result).toBe("not-configured");
+  });
+
+  it("returns 'not-configured' when socket absent", async () => {
+    loadConfigMock.mockReturnValue({ host_control: { enabled: true } });
+    const result = await tryHostdDispatch("nonexistent-agent", {
+      v: 1,
+      op: "agent_restart",
+      request_id: "test-2",
+      args: { name: "nonexistent-agent", force: true },
+    });
+    expect(result).toBe("not-configured");
+  });
+
+  it("locks the socket-path contract", () => {
+    // RFC C pins this path. If the gateway and the compose generator
+    // drift apart on the bind path, the mount silently goes nowhere
+    // and every dispatch returns "not-configured". Catch any rename
+    // in lockstep with the compose-generator test.
+    expect(hostdSocketPath("klanker")).toBe(
+      "/run/switchroom/hostd/klanker/sock",
+    );
+  });
+});