onbuzz 4.7.1 → 4.8.0

package/src/tools/desktop/__tests__/DesktopTool.test.js

@@ -0,0 +1,507 @@
+/**
+ * DesktopTool unit tests.
+ *
+ * All native deps mocked: osController + grounding adapter are stubs.
+ * Verifies:
+ *   - kill switch (env)
+ *   - per-agent allowlist
+ *   - parameter dispatch + validation
+ *   - intent → grounding → coord validation pipeline
+ *   - drag's screenshot reuse optimisation
+ *   - audit logging shape
+ */
+
+import { jest, describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import { DesktopTool, DesktopAction } from '../DesktopTool.js';
+
+// ─── fakes ─────────────────────────────────────────────────────────────
+
+function fakeOsc(overrides = {}) {
+  const calls = [];
+  const record = (name) => jest.fn(async (...args) => { calls.push({ name, args }); });
+  return {
+    screenshot:   jest.fn(async () => Buffer.from('png-bytes')),
+    screenSize:   jest.fn(async () => ({ width: 1920, height: 1080, dpr: 1 })),
+    mouseMove:    record('mouseMove'),
+    mouseClick:   record('mouseClick'),
+    mouseScroll:  record('mouseScroll'),
+    mouseDrag:    record('mouseDrag'),
+    typeText:     record('typeText'),
+    keyPress:     record('keyPress'),
+    listWindows:  jest.fn(async () => [{ title: 'Notepad' }, { title: 'Browser' }]),
+    focusWindow:  jest.fn(async ({ titleMatch }) => ({
+      focused: titleMatch === 'note' || titleMatch === 'Notepad',
+      title: 'Notepad',
+    })),
+    describeCapabilities: jest.fn(async () => ({
+      os: 'win32', display: null,
+      screenshot: true, mouseInput: true, keyboardInput: true, windowFocus: true,
+      degradedReason: null, nativeLoaded: true,
+    })),
+    _calls: calls,
+    ...overrides,
+  };
+}
+
+/** A stub aiService that carries a base url + a fake key manager. */
+function fakeAIService() {
+  return {
+    baseUrl: 'https://api.test.loxia.ai',
+    config: { apiKey: 'test-loxia-key' },
+    apiKeyManager: {
+      getKeysForRequest: jest.fn(() => ({ loxiaApiKey: 'test-loxia-key' })),
+    },
+  };
+}
+
+/**
+ * Build a DesktopTool with a stubbed grounding adapter that returns
+ * the coords we tell it to.
+ */
+function makeTool({ osc = fakeOsc(), groundResult, aiService = fakeAIService() } = {}) {
+  const tool = DesktopTool.withDependencies({
+    aiService,
+    osController: osc,
+    config: {},
+    logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+  });
+  // Pre-seed adapter cache so we don't hit the registry.
+  tool._adapterCache = {
+    ground: jest.fn(async () => groundResult || {
+      answer: 'x=500, y=400',
+      coords: { x: 500, y: 400 },
+      usage: { input_tokens: 1, output_tokens: 1 },
+      elapsed_ms: 5,
+    }),
+  };
+  return tool;
+}
+
+const FULL_ALLOW = { allowedActions: Object.values(DesktopAction) };
+
+// ─── kill switch / allowlist ───────────────────────────────────────────
+
+describe('DesktopTool — gating', () => {
+  const originalEnv = process.env.LOXIA_DESKTOP_TOOL_DISABLED;
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env.LOXIA_DESKTOP_TOOL_DISABLED;
+    else process.env.LOXIA_DESKTOP_TOOL_DISABLED = originalEnv;
+  });
+
+  test('env kill switch short-circuits every call', async () => {
+    process.env.LOXIA_DESKTOP_TOOL_DISABLED = '1';
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'screenshot' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('DESKTOP_DISABLED');
+  });
+
+  test('default (no allowedActions) refuses every action', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'screenshot' }, {});
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('NOT_PERMITTED');
+  });
+
+  test('explicit allowlist gates per action', async () => {
+    const tool = makeTool();
+    const r1 = await tool.execute(
+      { action: 'screenshot' },
+      { toolConfig: { allowedActions: ['screenshot'] } },
+    );
+    expect(r1.success).toBe(true);
+
+    const r2 = await tool.execute(
+      { action: 'click', x: 10, y: 10 },
+      { toolConfig: { allowedActions: ['screenshot'] } }, // click NOT in list
+    );
+    expect(r2.success).toBe(false);
+    expect(r2.code).toBe('NOT_PERMITTED');
+  });
+
+  test('unknown action returns INVALID_ACTION', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'self_destruct' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('INVALID_ACTION');
+  });
+});
+
+// ─── action dispatch ───────────────────────────────────────────────────
+
+describe('DesktopTool — actions', () => {
+  test('screenshot saves to disk and returns the path (no inline base64)', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'screenshot' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(true);
+    // Critical: we MUST NOT return raw base64 bytes in the tool result —
+    // the agent can't read PNG bytes from text, and dumping 200 KB of
+    // base64 into the conversation derails the next model turn.
+    expect(r).not.toHaveProperty('screenshotBase64');
+    expect(typeof r.screenshotPath).toBe('string');
+    expect(r.screenshotPath).toMatch(/screenshot-\d+\.png$/);
+    expect(r.size).toMatchObject({ width: 1920, height: 1080 });
+    expect(r.bytes).toBe(Buffer.from('png-bytes').length);
+  });
+
+  test('click with raw (x,y) skips grounding', async () => {
+    const osc = fakeOsc();
+    const tool = makeTool({ osc });
+    const r = await tool.execute(
+      { action: 'click', x: 100, y: 200, button: 'right' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expect(r.coords).toEqual({ x: 100, y: 200 });
+    expect(r.groundedFrom).toBeNull();
+    expect(osc.mouseClick).toHaveBeenCalledWith(100, 200, { button: 'right', count: undefined });
+    // Grounding adapter NOT consulted.
+    expect(tool._adapterCache.ground).not.toHaveBeenCalled();
+  });
+
+  test('click with intent grounds, then clicks', async () => {
+    const osc = fakeOsc();
+    const tool = makeTool({ osc });
+    const r = await tool.execute(
+      { action: 'click', intent: 'the Save button' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expect(r.coords).toEqual({ x: 500, y: 400 });
+    expect(r.groundedFrom).toBe('the Save button');
+    expect(tool._adapterCache.ground).toHaveBeenCalledTimes(1);
+    expect(osc.mouseClick).toHaveBeenCalledWith(500, 400, expect.any(Object));
+  });
+
+  test('click with neither coords nor intent fails INVALID_INPUT', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'click' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('INVALID_INPUT');
+  });
+
+  test('grounding miss (no coords parsed) → GROUNDING_FAILED', async () => {
+    const tool = makeTool({
+      groundResult: { answer: 'I have no idea where that is', usage: {}, elapsed_ms: 1 },
+    });
+    const r = await tool.execute(
+      { action: 'click', intent: 'mystery button' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('GROUNDING_FAILED');
+    expect(r.error).toMatch(/no idea/);
+  });
+
+  test('grounded coords outside screen → COORDS_OUT_OF_BOUNDS', async () => {
+    const tool = makeTool({
+      groundResult: { answer: 'x=9999, y=9999', coords: { x: 9999, y: 9999 } },
+    });
+    const r = await tool.execute(
+      { action: 'click', intent: 'somewhere' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('COORDS_OUT_OF_BOUNDS');
+  });
+
+  test('type forwards text and length', async () => {
+    const osc = fakeOsc();
+    const tool = makeTool({ osc });
+    const r = await tool.execute(
+      { action: 'type', text: 'hello world' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expect(osc.typeText).toHaveBeenCalledWith('hello world', expect.any(Object));
+  });
+
+  test('type with empty text → INVALID_INPUT', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'type', text: '' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('INVALID_INPUT');
+  });
+
+  test('key_press forwards keys array', async () => {
+    const osc = fakeOsc();
+    const tool = makeTool({ osc });
+    const r = await tool.execute(
+      { action: 'key_press', keys: ['Control', 'S'] },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expect(osc.keyPress).toHaveBeenCalledWith(['Control', 'S']);
+    expect(r.output).toMatch(/Control\+S/);
+  });
+
+  test('key_press empty keys → INVALID_INPUT', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'key_press', keys: [] }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('INVALID_INPUT');
+  });
+
+  test('scroll requires dy', async () => {
+    const tool = makeTool();
+    const r = await tool.execute(
+      { action: 'scroll', x: 100, y: 100 },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('INVALID_INPUT');
+  });
+
+  test('scroll with raw coords + dy works', async () => {
+    const osc = fakeOsc();
+    const tool = makeTool({ osc });
+    const r = await tool.execute(
+      { action: 'scroll', x: 100, y: 100, dy: -3 },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expect(osc.mouseScroll).toHaveBeenCalledWith(100, 100, -3);
+  });
+
+  test('drag with raw from/to → two coord pairs, no grounding', async () => {
+    const osc = fakeOsc();
+    const tool = makeTool({ osc });
+    const r = await tool.execute(
+      { action: 'drag', from: { x: 10, y: 20 }, to: { x: 50, y: 60 } },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expect(r.from).toEqual({ x: 10, y: 20 });
+    expect(r.to).toEqual({ x: 50, y: 60 });
+    expect(osc.mouseDrag).toHaveBeenCalledTimes(1);
+    expect(tool._adapterCache.ground).not.toHaveBeenCalled();
+  });
+
+  test('list_windows returns titles, filters empty, caps to 50', async () => {
+    // Build a stub that mimics a real OS — most "windows" have empty
+    // titles (system handles) and the OS reports way more than 50.
+    const osc = fakeOsc({
+      listWindows: jest.fn(async () => {
+        const out = [{ title: 'Notepad' }, { title: 'Browser' }];
+        for (let i = 0; i < 200; i++) out.push({ title: '' });          // untitled handles
+        for (let i = 0; i < 60; i++)  out.push({ title: `App-${i}` });  // 60 real titles
+        return out;
+      }),
+    });
+    const tool = makeTool({ osc });
+    const r = await tool.execute({ action: 'list_windows' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(true);
+    expect(r.totalCount).toBe(262);
+    expect(r.titledCount).toBe(62);        // 2 + 60 titled
+    expect(r.windows).toHaveLength(50);    // capped
+    expect(r.truncated).toBe(true);
+    expect(r.output).toMatch(/Notepad/);
+    expect(r.output).toMatch(/filtered 200 untitled/);
+  });
+
+  test('focus_window without titleMatch → INVALID_INPUT', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'focus_window' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('INVALID_INPUT');
+  });
+
+  test('focus_window match found', async () => {
+    const tool = makeTool();
+    const r = await tool.execute(
+      { action: 'focus_window', titleMatch: 'note' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expect(r.focused).toBe(true);
+  });
+
+  test('describe_capabilities returns the capability snapshot', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ action: 'describe_capabilities' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(true);
+    expect(r.capabilities.os).toBe('win32');
+    expect(r.output).toMatch(/screenshot=true/);
+  });
+});
+
+// ─── adapter build ─────────────────────────────────────────────────────
+
+// ─── REGRESSION: every tool result is action-tagged ────────────────────
+//
+// Background: in a real run on 2026-05-13 the agent thought a click on
+// the Netflix taskbar icon had succeeded because msg[5] in the
+// conversation came back with `success:true` and a screenshot path —
+// but msg[5] was actually a stale duplicate-screenshot result that
+// landed where the click result was expected (msg[7] later carried the
+// real click failure, by which point the agent had moved on).
+//
+// Fix: every action's result `output` MUST begin with "[action: <id>]"
+// so the model can ALWAYS map a tool result back to the action it
+// belongs to, even when results arrive out-of-order in batched messages.
+//
+// These tests lock the invariant. Adding a new action without tagging
+// the output will fail here and force the author to update both
+// places.
+
+describe('REGRESSION: every desktop result includes its action tag', () => {
+  function expectActionTag(result, expected) {
+    expect(typeof result.output).toBe('string');
+    expect(result.output.startsWith(`[action: ${expected}]`)).toBe(true);
+    // Structured field too, so consumers don't have to parse the prefix.
+    expect(result.action).toBe(expected);
+  }
+
+  test('screenshot output begins with [action: screenshot]', async () => {
+    const r = await makeTool().execute({ action: 'screenshot' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'screenshot');
+  });
+
+  test('click output begins with [action: click]', async () => {
+    const r = await makeTool().execute(
+      { action: 'click', x: 100, y: 200 },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'click');
+  });
+
+  test('type output begins with [action: type]', async () => {
+    const r = await makeTool().execute(
+      { action: 'type', text: 'x' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'type');
+  });
+
+  test('key_press output begins with [action: key_press]', async () => {
+    const r = await makeTool().execute(
+      { action: 'key_press', keys: ['LeftWin'] },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'key_press');
+  });
+
+  test('scroll output begins with [action: scroll]', async () => {
+    const r = await makeTool().execute(
+      { action: 'scroll', x: 1, y: 1, dy: 5 },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'scroll');
+  });
+
+  test('drag output begins with [action: drag]', async () => {
+    const r = await makeTool().execute(
+      { action: 'drag', from: { x: 1, y: 1 }, to: { x: 2, y: 2 } },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'drag');
+  });
+
+  test('list_windows output begins with [action: list_windows]', async () => {
+    const r = await makeTool().execute({ action: 'list_windows' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'list_windows');
+  });
+
+  test('focus_window output begins with [action: focus_window]', async () => {
+    const r = await makeTool().execute(
+      { action: 'focus_window', titleMatch: 'note' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'focus_window');
+  });
+
+  test('describe_capabilities output begins with [action: describe_capabilities]', async () => {
+    const r = await makeTool().execute({ action: 'describe_capabilities' }, { toolConfig: FULL_ALLOW });
+    expect(r.success).toBe(true);
+    expectActionTag(r, 'describe_capabilities');
+  });
+
+  test('failure outputs also tag the action (so an error mid-batch is unambiguous)', async () => {
+    const r = await makeTool().execute(
+      { action: 'type', text: '' },  // invalid, triggers _fail
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(false);
+    expect(r.output).toMatch(/^\[action: type\]/);
+    expect(r.action).toBe('type');
+  });
+
+  test('grounding-failure click result tags the action', async () => {
+    const tool = makeTool({
+      groundResult: { answer: 'nope', usage: {}, elapsed_ms: 1 },
+    });
+    const r = await tool.execute(
+      { action: 'click', intent: 'foo' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(false);
+    expect(r.output).toMatch(/^\[action: click\]/);
+    expect(r.action).toBe('click');
+  });
+});
+
+describe('DesktopTool — adapter construction', () => {
+  test('intent path without aiService → NOT_INITIALISED', async () => {
+    const tool = new DesktopTool({ osController: fakeOsc() });
+    tool._adapterCache = null; // force real build
+    const r = await tool.execute(
+      { action: 'click', intent: 'foo' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(false);
+    expect(r.code).toBe('NOT_INITIALISED');
+  });
+});
+
+// ─── parseParameters ───────────────────────────────────────────────────
+
+describe('DesktopTool — parseParameters', () => {
+  test('parses {parameters: ...} envelope', () => {
+    const tool = makeTool();
+    const out = tool.parseParameters('{"parameters": {"action": "screenshot"}}');
+    expect(out).toEqual({ action: 'screenshot' });
+  });
+
+  test('parses bare object', () => {
+    const tool = makeTool();
+    const out = tool.parseParameters('{"action": "click", "x": 1, "y": 2}');
+    expect(out).toEqual({ action: 'click', x: 1, y: 2 });
+  });
+
+  test('rejects non-JSON', () => {
+    const tool = makeTool();
+    expect(() => tool.parseParameters('<click/>')).toThrow(/JSON/);
+  });
+});
+
+// ─── drag screenshot reuse ─────────────────────────────────────────────
+
+describe('DesktopTool — drag screenshot reuse', () => {
+  test('drag with two intents calls screenshot once, grounds twice', async () => {
+    const osc = fakeOsc();
+    const tool = makeTool({ osc });
+    tool._adapterCache = {
+      ground: jest.fn(async ({ intent }) => ({
+        answer: 'ok',
+        coords: intent === 'A' ? { x: 100, y: 100 } : { x: 200, y: 200 },
+      })),
+    };
+    const r = await tool.execute(
+      { action: 'drag', fromIntent: 'A', toIntent: 'B' },
+      { toolConfig: FULL_ALLOW },
+    );
+    expect(r.success).toBe(true);
+    expect(osc.screenshot).toHaveBeenCalledTimes(1); // reused for second leg
+    expect(tool._adapterCache.ground).toHaveBeenCalledTimes(2);
+    expect(r.from).toEqual({ x: 100, y: 100 });
+    expect(r.to).toEqual({ x: 200, y: 200 });
+  });
+});

package/src/tools/desktop/__tests__/osCapabilities.test.js

@@ -0,0 +1,106 @@
+/**
+ * osCapabilities tests — no real OS probes, all injected.
+ *
+ * Verifies: platform mapping, Wayland degradation, macOS permission
+ * branching, cache invalidation, snapshot freezing.
+ */
+
+import { describe, test, expect, beforeEach } from '@jest/globals';
+import {
+  detectOSCapabilities,
+  _resetCacheForTests,
+  PlatformId,
+  DisplayServer,
+} from '../osCapabilities.js';
+
+beforeEach(() => _resetCacheForTests());
+
+describe('detectOSCapabilities — platform mapping', () => {
+  test('Windows: fully capable, no macOS permissions, no display server', async () => {
+    const c = await detectOSCapabilities({ platform: 'win32', env: {} });
+    expect(c.os).toBe(PlatformId.WIN);
+    expect(c.display).toBeNull();
+    expect(c.mouseInput).toBe(true);
+    expect(c.keyboardInput).toBe(true);
+    expect(c.screenshot).toBe(true);
+    expect(c.permissions.requiresAccessibility).toBe(false);
+    expect(c.degradedReason).toBeNull();
+  });
+
+  test('Linux X11: fully capable, no degradation', async () => {
+    const c = await detectOSCapabilities({
+      platform: 'linux',
+      env: { XDG_SESSION_TYPE: 'x11' },
+    });
+    expect(c.os).toBe(PlatformId.LINUX);
+    expect(c.display).toBe(DisplayServer.X11);
+    expect(c.mouseInput).toBe(true);
+    expect(c.degradedReason).toBeNull();
+  });
+
+  test('Linux Wayland: input blocked, degradedReason populated, screenshot still allowed', async () => {
+    const c = await detectOSCapabilities({
+      platform: 'linux',
+      env: { XDG_SESSION_TYPE: 'wayland' },
+    });
+    expect(c.os).toBe(PlatformId.LINUX);
+    expect(c.display).toBe(DisplayServer.WAYLAND);
+    expect(c.mouseInput).toBe(false);
+    expect(c.keyboardInput).toBe(false);
+    expect(c.windowFocus).toBe(false);
+    expect(c.screenshot).toBe(true);
+    expect(c.permissions.portalsOnly).toBe(true);
+    expect(c.degradedReason).toMatch(/Wayland blocks input injection/);
+  });
+
+  test('Linux with no XDG_SESSION_TYPE: defaults to X11', async () => {
+    const c = await detectOSCapabilities({ platform: 'linux', env: {} });
+    expect(c.display).toBe(DisplayServer.X11);
+    expect(c.mouseInput).toBe(true);
+  });
+
+  test('Unknown platform: unknown id, defaults to capable', async () => {
+    // We don't pretend to know what FreeBSD / Solaris support — let
+    // OSController surface real errors when they happen.
+    const c = await detectOSCapabilities({ platform: 'sunos', env: {} });
+    expect(c.os).toBe(PlatformId.UNKNOWN);
+  });
+});
+
+describe('detectOSCapabilities — snapshot semantics', () => {
+  test('returns the same frozen object across calls (cached)', async () => {
+    const a = await detectOSCapabilities({ platform: 'win32', env: {} });
+    const b = await detectOSCapabilities({ platform: 'win32', env: {} });
+    expect(a).toBe(b);                           // identity, not just equality
+    expect(Object.isFrozen(a)).toBe(true);
+    expect(Object.isFrozen(a.permissions)).toBe(true);
+  });
+
+  test('refresh:true re-probes and returns a new snapshot', async () => {
+    const a = await detectOSCapabilities({ platform: 'win32', env: {} });
+    const b = await detectOSCapabilities({ platform: 'win32', env: {}, refresh: true });
+    expect(a).not.toBe(b);
+    // Same shape though.
+    expect(b.os).toBe(a.os);
+  });
+
+  test('probedAt is a sensible timestamp', async () => {
+    const before = Date.now();
+    const c = await detectOSCapabilities({ platform: 'win32', env: {} });
+    expect(c.probedAt).toBeGreaterThanOrEqual(before);
+    expect(c.probedAt).toBeLessThanOrEqual(Date.now());
+  });
+});
+
+describe('PlatformId / DisplayServer enums', () => {
+  test('PlatformId values are the canonical Node strings', () => {
+    expect(PlatformId.WIN).toBe('win32');
+    expect(PlatformId.MAC).toBe('darwin');
+    expect(PlatformId.LINUX).toBe('linux');
+  });
+
+  test('enum objects are frozen (no mutation)', () => {
+    expect(() => { PlatformId.WIN = 'x'; }).toThrow();
+    expect(() => { DisplayServer.X11 = 'y'; }).toThrow();
+  });
+});