@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/__tests__/safe-text-boundary.test.tsx

@@ -0,0 +1,75 @@
+/**
+ * #2222: the SafeText boundary, asserted against the BYTES Ink writes to a tty — not against
+ * `lastFrame()`. Measured on PR #2212: Ink itself strips OSC 52 / OSC 0 / CSI / DCS / APC from a
+ * frame and passes SGR, OSC 8 and a bare CR, so a frame assertion is green whether or not the code
+ * sanitizes. Only the stream a real terminal would receive tells the two apart.
+ *
+ * The raw-`Text` case below is REQUIRED to leak: it is what proves the detector can answer "yes".
+ */
+
+import { Writable } from 'node:stream';
+
+import { Text as RawInkText, render } from 'ink';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { SafeText, Text } from '../SafeText.js';
+
+import type { ReactElement } from 'react';
+
+/** OSC 8 hyperlink (Ink passes it through) and a bare CR — the two markers a frame cannot show. */
+const OSC8 = ']8;;https://evil.exampleclick]8;;';
+const POISON = `before${OSC8}\rafter`;
+
+/** A stream that claims to be a tty, so Ink writes what a terminal would receive. */
+function createTtyCapture(): { stdout: NodeJS.WriteStream; bytes: () => string } {
+  const chunks: string[] = [];
+  const stream = new Writable({
+    write(chunk: Buffer | string, _encoding, callback) {
+      chunks.push(chunk.toString());
+      callback();
+    },
+  });
+  const stdout = Object.assign(stream, {
+    isTTY: true,
+    columns: 80,
+    rows: 24,
+  }) as unknown as NodeJS.WriteStream;
+  return { stdout, bytes: () => chunks.join('') };
+}
+
+async function renderToTty(element: ReactElement): Promise<string> {
+  const capture = createTtyCapture();
+  const instance = render(element, { stdout: capture.stdout, patchConsole: false });
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  instance.unmount();
+  return capture.bytes();
+}
+
+describe('SafeText boundary (#2222)', () => {
+  it('a raw ink Text render LEAKS the markers to the tty stream (detector proof)', async () => {
+    const bytes = await renderToTty(<RawInkText>{POISON}</RawInkText>);
+    expect(bytes).toContain(']8;;https://evil.example');
+    expect(bytes).toContain('before');
+  });
+
+  it('SafeText removes the markers from the same payload, keeping the visible text', async () => {
+    const bytes = await renderToTty(<SafeText>{POISON}</SafeText>);
+    expect(bytes).not.toContain('evil.example');
+    expect(bytes).not.toContain(']8;;');
+    expect(bytes).toContain('before');
+    expect(bytes).toContain('after');
+  });
+
+  it('the `Text` alias call sites use is the boundary, and nested children are covered', async () => {
+    const bytes = await renderToTty(
+      <Text>
+        {'label: '}
+        <Text bold>{POISON}</Text>
+        {[POISON, 42]}
+      </Text>,
+    );
+    expect(bytes).not.toContain('evil.example');
+    expect(bytes).toContain('42');
+  });
+});

package/src/__tests__/screen-reader-input.test.tsx

@@ -0,0 +1,106 @@
+/**
+ * CLI-2004 TC-10 — the input area in screen-reader mode.
+ *
+ * Two things, and they fail for the same reason. The hand-drawn rules above and below the input are
+ * repainted with the line, so a reader hears a wall of dashes on every keystroke; and a word
+ * deletion leaves a reader announcing what REMAINS, which is precisely not the information wanted.
+ */
+
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import InputArea from '../InputArea.js';
+import { formatDeletionAnnouncement } from '../input-area-rules.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+
+async function tick(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+function renderInput(enabled: boolean): ReturnType<typeof render> {
+  return render(
+    <ScreenReaderProvider enabled={enabled}>
+      <InputArea onSubmit={vi.fn()} isDisabled={false} />
+    </ScreenReaderProvider>,
+  );
+}
+
+describe('TC-10: the input area chrome', () => {
+  it('renders no rule line and no border in the mode', async () => {
+    const { lastFrame, unmount } = renderInput(true);
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).not.toContain('─');
+    expect(frame).not.toMatch(/[╭╮╰╯│┌┐└┘]/u);
+    expect(frame).toContain('Type a message');
+  });
+
+  it('still renders the rules when the mode is off', async () => {
+    const { lastFrame, unmount } = renderInput(false);
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain('─');
+  });
+});
+
+describe('TC-10: the deletion announcement', () => {
+  it('prints `[deleted: <word>]` exactly once after a word deletion', async () => {
+    const { stdin, lastFrame, unmount } = renderInput(true);
+    await tick();
+
+    for (const char of 'hello world') {
+      stdin.write(char);
+    }
+    await tick();
+    // Ctrl+W — the word delete.
+    stdin.write('\x17');
+    await tick();
+
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    const announcement = formatDeletionAnnouncement('world');
+    expect(frame).toContain(announcement);
+    expect(frame.split(announcement).length - 1).toBe(1);
+  });
+
+  it('announces the whole line for a line deletion', async () => {
+    const { stdin, lastFrame, unmount } = renderInput(true);
+    await tick();
+
+    for (const char of 'abc') {
+      stdin.write(char);
+    }
+    await tick();
+    // Ctrl+U — the line delete.
+    stdin.write('\x15');
+    await tick();
+
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain(formatDeletionAnnouncement('abc'));
+  });
+
+  it('announces nothing when the mode is off', async () => {
+    const { stdin, lastFrame, unmount } = renderInput(false);
+    await tick();
+
+    for (const char of 'hello world') {
+      stdin.write(char);
+    }
+    await tick();
+    stdin.write('\x17');
+    await tick();
+
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).not.toContain('[deleted:');
+  });
+});

package/src/__tests__/screen-reader-labels.test.ts

@@ -0,0 +1,91 @@
+/**
+ * CLI-2004 TC-05 — the role-derived, provider-invariant label vocabulary.
+ *
+ * The point of the negative assertion below is not tidiness: a label naming the vendor would make
+ * the transcript differ between `agent-provider-*` packages for the same conversation, and a reader
+ * grepping their scrollback for "assistant:" would find nothing after switching providers.
+ */
+
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { RoleLabel } from '../RoleLabel.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+import {
+  SCREEN_READER_LABELS,
+  screenReaderLabelForRole,
+  screenReaderLabelValues,
+} from '../screen-reader-labels.js';
+
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+
+/** Every provider package this repo ships, plus the vendor names behind them. */
+const VENDOR_WORDS = /(claude|anthropic|openai|gpt|gemini|google|robota|llama|mistral|copilot)/i;
+
+function renderLabel(role: TUniversalMessage['role'], enabled: boolean, driverId?: string): string {
+  const label = React.createElement(
+    RoleLabel,
+    driverId === undefined ? { role } : { role, driverId },
+  );
+  const { lastFrame, unmount } = render(
+    React.createElement(ScreenReaderProvider, { enabled, children: label }),
+  );
+  const frame = lastFrame() ?? '';
+  unmount();
+  return frame;
+}
+
+describe('TC-05: the label vocabulary', () => {
+  it('covers all nine label kinds', () => {
+    expect(Object.keys(SCREEN_READER_LABELS)).toHaveLength(9);
+    expect(screenReaderLabelValues()).toEqual([
+      'you:',
+      'assistant:',
+      'thinking:',
+      'tool:',
+      'tool error:',
+      'error:',
+      'warning:',
+      'permission required:',
+      'cost:',
+    ]);
+  });
+
+  it('is entirely lowercase', () => {
+    for (const label of screenReaderLabelValues()) {
+      expect(label).toBe(label.toLowerCase());
+    }
+  });
+
+  it('names no provider or vendor', () => {
+    for (const label of screenReaderLabelValues()) {
+      expect(label).not.toMatch(VENDOR_WORDS);
+    }
+  });
+
+  it('maps every transcript role onto the vocabulary', () => {
+    expect(screenReaderLabelForRole('user')).toBe('you:');
+    expect(screenReaderLabelForRole('assistant')).toBe('assistant:');
+    expect(screenReaderLabelForRole('tool')).toBe('tool:');
+    expect(screenReaderLabelForRole('system')).toBe('warning:');
+  });
+});
+
+describe('TC-05: RoleLabel in the mode', () => {
+  it('renders `assistant:` for an assistant message — the same under every provider', () => {
+    const frame = renderLabel('assistant', true);
+    expect(frame).toContain('assistant:');
+    expect(frame).not.toMatch(VENDOR_WORDS);
+  });
+
+  it('renders `you:` for the operator, and the driver id for a co-driven turn', () => {
+    expect(renderLabel('user', true)).toContain('you:');
+    expect(renderLabel('user', true, 'peer:s-1')).toContain('peer:s-1:');
+  });
+
+  it('uses neutral visual labels when the mode is off', () => {
+    expect(renderLabel('assistant', false)).toContain('Assistant:');
+    expect(renderLabel('user', false)).toContain('You:');
+  });
+});

package/src/__tests__/screen-reader-menus.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * CLI-2004 TC-06 / TC-07 — arrow-key menus become numbered lists with a typed answer.
+ *
+ * Position is the thing a reader cannot get: the `> ` cursor and the accent colour say which row is
+ * selected, and neither survives being read aloud. A spoken number does.
+ */
+
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import ConfirmPrompt, { CONFIRM_PROMPT_TYPED_LITERAL } from '../ConfirmPrompt.js';
+import MenuSelect from '../MenuSelect.js';
+import { NUMBERED_LIST_CANCEL_SUFFIX } from '../numbered-list.js';
+import PermissionPrompt from '../PermissionPrompt.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+
+import type { IPendingPermissionRequest } from '../types.js';
+
+/** Ink needs a tick to deliver stdin and flush a frame. */
+async function tick(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+function renderInMode(element: React.ReactElement): ReturnType<typeof render> {
+  return render(<ScreenReaderProvider enabled={true}>{element}</ScreenReaderProvider>);
+}
+
+const ITEMS = [
+  { label: 'First option', value: 'a' },
+  { label: 'Second option', value: 'b' },
+  { label: 'Third option', value: 'c' },
+];
+
+describe('TC-06: MenuSelect as a numbered list', () => {
+  it('renders `1. `, `2. `, `3. ` rows and the authored prompt literal', async () => {
+    const { lastFrame, unmount } = renderInMode(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={vi.fn()} onBack={vi.fn()} />,
+    );
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain('1. First option');
+    expect(frame).toContain('2. Second option');
+    expect(frame).toContain('3. Third option');
+    expect(frame).toContain('Enter selection (1-3)');
+    expect(frame).not.toContain('> ');
+    expect(frame).not.toMatch(/[╭╮╰╯│─]/u);
+  });
+
+  it('a cancellable menu names Escape in the same literal', async () => {
+    const { lastFrame, unmount } = renderInMode(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={vi.fn()} onBack={vi.fn()} />,
+    );
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain(`Enter selection (1-3)${NUMBERED_LIST_CANCEL_SUFFIX}`);
+  });
+
+  it('typing `2` then Enter selects the SECOND option', async () => {
+    const onSelect = vi.fn();
+    const { stdin, unmount } = renderInMode(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={onSelect} onBack={vi.fn()} />,
+    );
+    await tick();
+    stdin.write('2');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect).toHaveBeenCalledWith('b');
+  });
+
+  it('typing `9` then Enter selects nothing and re-prints the same literal', async () => {
+    const onSelect = vi.fn();
+    const { stdin, lastFrame, unmount } = renderInMode(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={onSelect} onBack={vi.fn()} />,
+    );
+    await tick();
+    stdin.write('9');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(onSelect).not.toHaveBeenCalled();
+    // The range IS the correction: the same literal comes back, twice in the frame.
+    expect(frame.split('Enter selection (1-3)').length - 1).toBeGreaterThanOrEqual(2);
+  });
+
+  it('keeps the bordered arrow-key menu when the mode is off', async () => {
+    const { lastFrame, unmount } = render(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={vi.fn()} onBack={vi.fn()} />,
+    );
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain('> First option');
+    expect(frame).not.toContain('Enter selection');
+    expect(frame).toMatch(/[╭╮╰╯]/u);
+  });
+});
+
+describe('TC-07: PermissionPrompt and ConfirmPrompt', () => {
+  function permissionRequest(resolve: (value: unknown) => void): IPendingPermissionRequest {
+    return {
+      toolName: 'Bash',
+      toolArgs: { command: 'ls -la' },
+      resolve,
+    } as unknown as IPendingPermissionRequest;
+  }
+
+  it('renders the permission ask as a numbered list with no border', async () => {
+    const { lastFrame, unmount } = renderInMode(
+      <PermissionPrompt request={permissionRequest(vi.fn())} />,
+    );
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain('permission required:');
+    expect(frame).toContain('1. Allow');
+    expect(frame).toContain('Enter selection (1-4)');
+    expect(frame).not.toMatch(/[╭╮╰╯│─]/u);
+    expect(frame).not.toContain('> ');
+  });
+
+  it('a typed number resolves the permission ask', async () => {
+    const resolve = vi.fn();
+    const { stdin, unmount } = renderInMode(
+      <PermissionPrompt request={permissionRequest(resolve)} />,
+    );
+    await tick();
+    stdin.write('4');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    // Option 4 is Deny.
+    expect(resolve).toHaveBeenCalledWith(false);
+  });
+
+  it('ConfirmPrompt accepts `y` + Enter', async () => {
+    const onSelect = vi.fn();
+    const { stdin, lastFrame, unmount } = renderInMode(
+      <ConfirmPrompt message="Proceed?" onSelect={onSelect} />,
+    );
+    await tick();
+    expect(lastFrame() ?? '').toContain(CONFIRM_PROMPT_TYPED_LITERAL);
+    stdin.write('y');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    expect(onSelect).toHaveBeenCalledWith(0);
+  });
+
+  it('ConfirmPrompt accepts `no` + Enter', async () => {
+    const onSelect = vi.fn();
+    const { stdin, unmount } = renderInMode(
+      <ConfirmPrompt message="Proceed?" onSelect={onSelect} />,
+    );
+    await tick();
+    stdin.write('n');
+    await tick();
+    stdin.write('o');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    expect(onSelect).toHaveBeenCalledWith(1);
+  });
+
+  it('ConfirmPrompt rejects anything else without selecting', async () => {
+    const onSelect = vi.fn();
+    const { stdin, unmount } = renderInMode(
+      <ConfirmPrompt message="Proceed?" onSelect={onSelect} />,
+    );
+    await tick();
+    stdin.write('m');
+    await tick();
+    stdin.write('a');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/screen-reader-pacing.test.ts

@@ -0,0 +1,230 @@
+/**
+ * CLI-2004 TC-20 — the startup quiet period.
+ *
+ * The bound matters more than the default: a mistyped host timing override is
+ * how a session appears to hang forever, and a silently-swallowed value is how it appears to have no
+ * effect at all. Every rejection and every clamp is REPORTED, and this asserts the report.
+ *
+ * The last case is the one the review added: "any keypress ends the wait" is only true if something
+ * puts a TTY stdin into raw mode first, because a canonical-mode terminal delivers nothing until
+ * Enter. Asserting it against a synthetic source alone would have proved a behaviour the product
+ * does not have.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  awaitStartupQuietPeriod,
+  DEFAULT_PREPARK_MS,
+  DEFAULT_STARTUP_QUIET_MS,
+  PREPARK_MS_MAX,
+  resolvePacing,
+  STARTUP_QUIET_MS_MAX,
+} from '../screen-reader-pacing.js';
+
+const STARTUP_LABEL = 'ACME_SCREEN_READER_STARTUP_QUIET_MS';
+const PREPARK_LABEL = 'ACME_SCREEN_READER_PREPARK_MS';
+
+function startup(raw: string) {
+  return { startupQuiet: { raw, label: STARTUP_LABEL } };
+}
+
+function prepark(raw: string) {
+  return { prepark: { raw, label: PREPARK_LABEL } };
+}
+
+function collectWarnings(): { notes: string[]; warn: (message: string) => void } {
+  const notes: string[] = [];
+  return { notes, warn: (message: string): void => void notes.push(message) };
+}
+
+describe('TC-20: resolvePacing', () => {
+  it('ignores ambient Robota pacing variables without a host choice', () => {
+    vi.stubEnv('ROBOTA_SCREEN_READER_STARTUP_QUIET_MS', '0');
+    vi.stubEnv('ROBOTA_SCREEN_READER_PREPARK_MS', '0');
+    try {
+      expect(resolvePacing({ enabled: true })).toEqual({
+        startupQuietMs: DEFAULT_STARTUP_QUIET_MS,
+        preparkMs: DEFAULT_PREPARK_MS,
+      });
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  it('returns the documented default when the host supplies no override', () => {
+    expect(resolvePacing({ enabled: true })).toEqual({
+      startupQuietMs: DEFAULT_STARTUP_QUIET_MS,
+      preparkMs: DEFAULT_PREPARK_MS,
+    });
+  });
+
+  it('honours an explicit 0 exactly — the documented way to ask for no wait', () => {
+    expect(resolvePacing({ enabled: true, overrides: startup('0') })).toEqual({
+      startupQuietMs: 0,
+      preparkMs: DEFAULT_PREPARK_MS,
+    });
+  });
+
+  it('clamps the variable to its sanity bound AND reports the clamp', () => {
+    const sink = collectWarnings();
+    const pacing = resolvePacing({
+      enabled: true,
+      overrides: startup('999999'),
+      warn: sink.warn,
+    });
+
+    expect(pacing).toEqual({ startupQuietMs: STARTUP_QUIET_MS_MAX, preparkMs: DEFAULT_PREPARK_MS });
+    expect(sink.notes).toHaveLength(1);
+    expect(sink.notes[0]).toContain(`clamping 999999 to the ${STARTUP_QUIET_MS_MAX} ms`);
+  });
+
+  it('refuses a non-numeric value with a note instead of silently treating it as 0', () => {
+    const sink = collectWarnings();
+    const pacing = resolvePacing({
+      enabled: true,
+      overrides: startup('soon'),
+      warn: sink.warn,
+    });
+
+    expect(pacing.startupQuietMs).toBe(DEFAULT_STARTUP_QUIET_MS);
+    expect(pacing.startupQuietMs).not.toBe(0);
+    expect(sink.notes[0]).toContain('ignoring "soon"');
+  });
+
+  it('resolves the wait to 0 without warnings when the mode is off', () => {
+    const sink = collectWarnings();
+    expect(resolvePacing({
+      enabled: false,
+      overrides: startup('invalid'),
+      warn: sink.warn,
+    })).toEqual({
+      startupQuietMs: 0,
+      preparkMs: 0,
+    });
+    expect(sink.notes).toEqual([]);
+  });
+});
+
+describe('TC-20: the startup quiet period', () => {
+  it('settles at its deadline when nothing is pressed', async () => {
+    vi.useFakeTimers();
+    try {
+      const settled = awaitStartupQuietPeriod(500);
+      await vi.advanceTimersByTimeAsync(500);
+      await expect(settled).resolves.toBe('elapsed');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('a keypress settles it BEFORE its deadline', async () => {
+    vi.useFakeTimers();
+    try {
+      let onData: (() => void) | undefined;
+      const keys = {
+        once: (_event: 'data', listener: () => void): void => void (onData = listener),
+        off: (): void => {},
+        resume: (): void => {},
+        pause: (): void => {},
+      };
+      const settled = awaitStartupQuietPeriod(600_000, keys);
+      await vi.advanceTimersByTimeAsync(10);
+      onData?.();
+      await expect(settled).resolves.toBe('keypress');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('resolves immediately for a 0 wait without touching the keypress source', async () => {
+    let touched = false;
+    await expect(
+      awaitStartupQuietPeriod(0, {
+        once: (): void => void (touched = true),
+        off: (): void => {},
+      }),
+    ).resolves.toBe('elapsed');
+    expect(touched).toBe(false);
+  });
+
+  it('puts a TTY stdin into raw mode for the wait and restores it — without raw mode only Enter arrives', async () => {
+    vi.useFakeTimers();
+    try {
+      const modes: boolean[] = [];
+      let onData: (() => void) | undefined;
+      const keys = {
+        once: (_event: 'data', listener: () => void): void => void (onData = listener),
+        off: (): void => {},
+        resume: (): void => {},
+        pause: (): void => {},
+        isTTY: true,
+        setRawMode: (mode: boolean): void => void modes.push(mode),
+      };
+
+      const settled = awaitStartupQuietPeriod(600_000, keys);
+      expect(modes).toEqual([true]);
+      onData?.();
+      await expect(settled).resolves.toBe('keypress');
+      expect(modes).toEqual([true, false]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('leaves a non-TTY stdin alone — there is no raw mode to set on a pipe', async () => {
+    vi.useFakeTimers();
+    try {
+      let touchedRawMode = false;
+      const keys = {
+        once: (): void => {},
+        off: (): void => {},
+        isTTY: false,
+        setRawMode: (): void => void (touchedRawMode = true),
+      };
+      const settled = awaitStartupQuietPeriod(200, keys);
+      await vi.advanceTimersByTimeAsync(200);
+      await expect(settled).resolves.toBe('elapsed');
+      expect(touchedRawMode).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('SCREEN-2670 TC-01: resolvePacing returns preparkMs by the same discipline', () => {
+  it('defaults to the provisional 50 and honours an explicit 0 exactly', () => {
+    expect(resolvePacing({ enabled: true }).preparkMs).toBe(50);
+    expect(resolvePacing({ enabled: true, overrides: prepark('0') }).preparkMs).toBe(0);
+    expect(resolvePacing({ enabled: true, overrides: prepark('250') }).preparkMs).toBe(250);
+  });
+
+  it('refuses a non-numeric or negative value WITH a note naming the variable', () => {
+    for (const raw of ['soon', '-5', '1.5']) {
+      const sink = collectWarnings();
+      const pacing = resolvePacing({ enabled: true, overrides: prepark(raw), warn: sink.warn });
+      expect(pacing.preparkMs).toBe(DEFAULT_PREPARK_MS);
+      expect(sink.notes).toHaveLength(1);
+      expect(sink.notes[0]).toContain(PREPARK_LABEL);
+      expect(sink.notes[0]).toContain(`"${raw}"`);
+    }
+  });
+
+  it('clamps above the bound AND reports the clamp', () => {
+    const sink = collectWarnings();
+    const pacing = resolvePacing({
+      enabled: true,
+      overrides: prepark('99999'),
+      warn: sink.warn,
+    });
+    expect(pacing.preparkMs).toBe(PREPARK_MS_MAX);
+    expect(sink.notes[0]).toContain(`clamping 99999 to the ${PREPARK_MS_MAX} ms`);
+  });
+
+  it('is 0 whenever the mode is off, regardless of the variable', () => {
+    expect(resolvePacing({ enabled: false, overrides: prepark('250') })).toEqual({
+      startupQuietMs: 0,
+      preparkMs: 0,
+    });
+  });
+});