@semalt-ai/code 1.8.5 → 1.20.0

package/test/agent-loop.test.js

@@ -0,0 +1,389 @@
+'use strict';
+
+// Agent-loop integration tests (Task 1.2). These drive the real runAgentLoop
+// against the mock LLM harness, wired through the production config/api_base
+// seam (no production code changes). Covers the six scenarios in the task:
+// clean tool turn, multi-iteration termination, 429 retry honoring Retry-After,
+// 400/413 self-healing, mid-stream abort, and retryable-vs-non-retryable errors.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ui = require('../lib/ui');
+const { createApiClient } = require('../lib/api');
+const { createToolExecutor, extractToolCalls } = require('../lib/tools');
+const { createPermissionManager } = require('../lib/permissions');
+const { createAgentRunner } = require('../lib/agent');
+const { startMockLLM } = require('./harness/mock-llm');
+
+let prevKey;
+before(() => { prevKey = process.env.SEMALT_API_KEY; process.env.SEMALT_API_KEY = 'test-key'; });
+after(() => {
+  if (prevKey === undefined) delete process.env.SEMALT_API_KEY;
+  else process.env.SEMALT_API_KEY = prevKey;
+});
+
+// Wire a real agent runner whose chatStream points at `base`. skipPermissions
+// auto-approves tool calls so the loop runs unattended; uiCallbacks are stubbed
+// to noops so nothing prints during the test.
+function buildRunner(base) {
+  const config = {
+    api_base: base, api_key: 'test-key', default_model: 'test-model',
+    temperature: 0.5, request_timeout_ms: 5000, stream: true, models: [],
+    // This suite exercises the agent loop, not the OS sandbox (Task 4.4). Disable
+    // it so real `echo` test commands run unsandboxed regardless of whether the
+    // runner has bwrap/sandbox-exec; the sandbox has its own dedicated tests.
+    sandbox: { mode: 'off' },
+  };
+  let saved = null;
+  const getConfig = () => config;
+  const saveConfig = (c) => { saved = { ...c }; Object.assign(config, c); };
+
+  const api = createApiClient({ getConfig, saveConfig, ui });
+  const pm = createPermissionManager(ui, { skipPermissions: true });
+  pm.setUICallbacks({ onAddMessage: () => {}, onShowModal: () => {}, onCloseModal: () => {}, onCaptureNavigation: () => () => {} });
+  const { agentExecShell, agentExecFile, describePermission } = createToolExecutor(pm, ui, getConfig);
+  const runner = createAgentRunner({
+    chatStream: api.chatStream, extractToolCalls, agentExecShell, agentExecFile,
+    describePermission, permissionManager: pm, ui, getConfig,
+  });
+  return { runner, getSaved: () => saved, config };
+}
+
+function collector(extra = {}) {
+  const ev = { tokens: [], tools: [], errors: [], retries: [], assistants: [] };
+  const cb = {
+    onToken: (t) => ev.tokens.push(t),
+    onToolStart: () => {},
+    onToolEnd: (tag, result) => ev.tools.push({ tag, result }),
+    onError: (e) => ev.errors.push(e),
+    onRetry: (next, max) => ev.retries.push({ next, max }),
+    onAssistantMessage: (m) => ev.assistants.push(m),
+    ...extra,
+  };
+  return { ev, cb };
+}
+
+// ---------------------------------------------------------------------------
+// 1. Clean single-tool-call turn
+// ---------------------------------------------------------------------------
+
+test('clean single-tool-call turn: executes the tool then ends on the final reply', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo HELLO_S1</exec>');
+  mock.replyWith('All done.');
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'do it' }];
+    const { metrics } = await runner.runAgentLoop(messages, 'test-model', 10, null, { callbacks: cb });
+
+    assert.strictEqual(metrics.turns.length, 2, 'one tool turn + one final turn');
+    assert.strictEqual(mock.pending(), 0, 'both scripted responses consumed');
+
+    const toolResult = messages.find((m) => m.role === 'user' && /Tool execution results/.test(m.content));
+    assert.ok(toolResult, 'tool results fed back to the model');
+    assert.match(toolResult.content, /HELLO_S1/);
+    assert.match(toolResult.content, /Exit code: 0/);
+
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'All done.'), 'final answer recorded');
+    assert.strictEqual(ev.tools.length, 1);
+    assert.strictEqual(ev.tools[0].tag, 'shell');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 2. Multi-iteration loop terminating correctly
+// ---------------------------------------------------------------------------
+
+test('multi-iteration loop runs each tool turn then terminates on the no-tool reply', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo step1</exec>');
+  mock.replyWith('<exec>echo step2</exec>');
+  mock.replyWith('Finished.');
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'multi' }];
+    const { metrics } = await runner.runAgentLoop(messages, 'test-model', 10, null, { callbacks: cb });
+
+    assert.strictEqual(metrics.turns.length, 3);
+    assert.strictEqual(ev.tools.length, 2, 'two tools executed across two iterations');
+    assert.strictEqual(mock.requestCount(), 3);
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'Finished.'));
+  } finally {
+    await mock.close();
+  }
+});
+
+test('maxIterations caps the loop even when the model keeps emitting tools', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo a</exec>');
+  mock.replyWith('<exec>echo b</exec>');
+  mock.replyWith('<exec>echo c</exec>'); // would be a 3rd turn — must NOT be reached
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { cb } = collector();
+    const messages = [{ role: 'user', content: 'loop' }];
+    const { metrics } = await runner.runAgentLoop(messages, 'test-model', 2, null, { callbacks: cb });
+
+    assert.strictEqual(metrics.turns.length, 2, 'stopped at the iteration cap');
+    assert.strictEqual(mock.requestCount(), 2, 'no third request was made');
+    assert.strictEqual(mock.pending(), 1, 'third scripted reply left unused');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 3. Retry/backoff on 429 honoring Retry-After
+// ---------------------------------------------------------------------------
+
+test('429 is retried, and Retry-After: 0 is honored (near-instant, not the 1s base backoff)', async () => {
+  const mock = await startMockLLM();
+  mock.failWith(429, { headers: { 'retry-after': '0' } });
+  mock.replyWith('recovered after 429');
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'retry me' }];
+
+    const t0 = Date.now();
+    const { metrics } = await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+    const elapsed = Date.now() - t0;
+
+    assert.deepStrictEqual(ev.retries, [{ next: 2, max: 3 }], 'one retry announced');
+    assert.ok(elapsed < 800, `retry honored Retry-After:0 (elapsed ${elapsed}ms, base backoff would be ~1000ms)`);
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'recovered after 429'));
+    assert.strictEqual(metrics.turns.length, 1);
+    assert.strictEqual(mock.requestCount(), 2, 'failed attempt + successful retry');
+    assert.strictEqual(ev.errors.length, 0, 'transient error not surfaced after recovery');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 4. 400/413 context-overflow self-healing (inside api.js, transparent to loop)
+// ---------------------------------------------------------------------------
+
+test('400 context-overflow self-heals: parses the window, persists it, retries, succeeds', async () => {
+  const mock = await startMockLLM();
+  mock.failWith(400, { body: JSON.stringify({ error: { message: 'This model context length is only 100 tokens, but the request used more.' } }) });
+  mock.replyWith('healed 400');
+  try {
+    const { runner, getSaved } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'x'.repeat(2000) }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'healed 400'));
+    assert.strictEqual(mock.requestCount(), 2, 'overflow request + trimmed retry');
+    assert.strictEqual(ev.retries.length, 0, 'self-heal is not an agent-level retry');
+    const trimWarn = ev.errors.find((e) => e.isWarning && /Context trimmed \(overflow-400\)/.test(e.message));
+    assert.ok(trimWarn, 'a context-trim warning was surfaced');
+    assert.strictEqual(getSaved() && getSaved().context_length, 100, 'learned context window persisted');
+  } finally {
+    await mock.close();
+  }
+});
+
+test('413 self-heals: trims and retries without an agent-level retry', async () => {
+  const mock = await startMockLLM();
+  mock.failWith(413);
+  mock.replyWith('healed 413');
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'y'.repeat(2000) }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'healed 413'));
+    assert.strictEqual(mock.requestCount(), 2);
+    assert.ok(ev.errors.some((e) => e.isWarning && /Context trimmed \(overflow-413\)/.test(e.message)));
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 5. Abort propagation mid-stream
+// ---------------------------------------------------------------------------
+
+test('aborting mid-stream stops the turn without recording an assistant message', async () => {
+  const mock = await startMockLLM();
+  // Slow, multi-delta stream so the abort flag flips while it is still open.
+  mock.replyWith(['part-a ', 'part-b ', 'part-c ', 'part-d ', 'part-e'], { gapMs: 60 });
+  try {
+    const { runner } = buildRunner(mock.base);
+    let aborted = false;
+    const { ev, cb } = collector({
+      onToken: () => { aborted = true; }, // flip on the first streamed token
+    });
+    const messages = [{ role: 'user', content: 'abort me' }];
+
+    const { metrics } = await runner.runAgentLoop(messages, 'test-model', 5, null, {
+      callbacks: cb,
+      getAbortFlag: () => aborted,
+    });
+
+    assert.strictEqual(messages.length, 1, 'no assistant/tool messages appended after abort');
+    assert.strictEqual(ev.assistants.length, 0, 'no final assistant message emitted');
+    assert.strictEqual(metrics.turns.length, 1, 'the turn started but did not complete');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 6. Retryable vs non-retryable error distinction
+// ---------------------------------------------------------------------------
+
+test('a non-retryable error (401) breaks immediately with no retry', async () => {
+  const mock = await startMockLLM();
+  mock.failWith(401, { body: JSON.stringify({ error: 'unauthorized' }) });
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'nope' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.strictEqual(ev.retries.length, 0, '401 is not retried');
+    assert.strictEqual(mock.requestCount(), 1, 'only one request made');
+    const surfaced = ev.errors.find((e) => e.statusCode === 401);
+    assert.ok(surfaced, 'the 401 error was surfaced to the caller');
+  } finally {
+    await mock.close();
+  }
+});
+
+test('a retryable error (429) is retried up to the limit, then surfaced', async () => {
+  const mock = await startMockLLM();
+  mock.failWith(429, { headers: { 'retry-after': '0' } });
+  mock.failWith(429, { headers: { 'retry-after': '0' } });
+  mock.failWith(429, { headers: { 'retry-after': '0' } });
+  try {
+    const { runner } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'keep failing' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.strictEqual(ev.retries.length, 2, 'two retries before exhausting MAX_RETRIES=3');
+    assert.deepStrictEqual(ev.retries, [{ next: 2, max: 3 }, { next: 3, max: 3 }]);
+    assert.strictEqual(mock.requestCount(), 3, 'three attempts total');
+    assert.ok(ev.errors.some((e) => e.statusCode === 429), 'final error surfaced after exhausting retries');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 7. A BUILT-IN tool through BOTH dispatch paths (Task 3.3b)
+//
+// Task 3.3 fixed a latent bug: a native function-calling response with empty
+// text content + structured tool_calls was mistaken for a dropped/empty
+// response, so native dispatch silently broke (the `!reply && !hasNativeToolCalls`
+// guard in lib/agent.js). That fix was regression-tested only via an MCP tool —
+// not via a BUILT-IN tool, which is the most-used path and the one that was
+// actually broken. These two tests lock the built-in path on both rails:
+//   (a) native function-calling (tool_calls, EMPTY text) — the regression, and
+//   (b) the XML tag path — the long-standing path,
+// proving both flow through the SAME runAgentLoop end-to-end (the extraction-level
+// equivalence Task 1.4 asserted, now asserted at loop level).
+// `read_file` is used because it is read-only (auto-runs unattended), maps from
+// both `{path}` (native) and `<read_file>…</read_file>` (XML), and returns
+// deterministic content from a temp file.
+// ---------------------------------------------------------------------------
+
+function withTempFile(contents, fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-agentloop-'));
+  const file = path.join(dir, 'fixture.txt');
+  fs.writeFileSync(file, contents, 'utf8');
+  return Promise.resolve(fn(file)).finally(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+}
+
+test('built-in tool via the NATIVE path: empty-text tool_calls response dispatches (regression locked)', async () => {
+  const MARKER = 'NATIVE_PATH_FILE_CONTENT_42';
+  await withTempFile(MARKER, async (file) => {
+    const mock = await startMockLLM();
+    // Native function-calling: the response carries tool_calls and NO text
+    // content. Pre-fix, the empty `content` made the loop treat this as an
+    // empty/dropped response and break before dispatching.
+    mock.replyWithToolCall('read_file', { path: file });
+    mock.replyWith('Read it.');
+    try {
+      const { runner } = buildRunner(mock.base);
+      const { ev, cb } = collector();
+      const messages = [{ role: 'user', content: 'read the file' }];
+      const { metrics } = await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+      // The regression's symptom was a false "empty response" warning + an
+      // un-dispatched tool. Neither must happen.
+      assert.ok(
+        !ev.errors.some((e) => /empty response/i.test(e.message || '')),
+        'native tool_calls with empty text content is NOT mistaken for an empty response',
+      );
+      assert.strictEqual(ev.tools.length, 1, 'the built-in read tool was dispatched');
+      assert.strictEqual(ev.tools[0].tag, 'read');
+
+      // The assistant turn carried structured tool_calls with empty text…
+      const assistantWithCall = messages.find((m) => m.role === 'assistant' && Array.isArray(m.tool_calls));
+      assert.ok(assistantWithCall, 'assistant message recorded the native tool_calls');
+      assert.strictEqual(assistantWithCall.content, '', 'native tool-call turn has empty text content');
+      assert.strictEqual(assistantWithCall.tool_calls[0].function.name, 'read_file');
+
+      // …and the result came back on a role:'tool' message (native shape),
+      // carrying the real file content.
+      const toolMsg = messages.find((m) => m.role === 'tool');
+      assert.ok(toolMsg, 'native path appends a role:"tool" result message');
+      assert.match(toolMsg.content, new RegExp(MARKER), 'file content flowed back to the model');
+      assert.strictEqual(toolMsg.tool_call_id, assistantWithCall.tool_calls[0].id, 'result rooted to its tool_call id');
+
+      // The loop proceeded to the final non-tool reply — proof it did not stall.
+      assert.strictEqual(metrics.turns.length, 2, 'tool turn + final turn');
+      assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'Read it.'), 'final answer recorded');
+      assert.strictEqual(mock.pending(), 0, 'both scripted responses consumed');
+    } finally {
+      await mock.close();
+    }
+  });
+});
+
+test('built-in tool via the XML path: <read_file> tag dispatches the same tool through the loop', async () => {
+  const MARKER = 'XML_PATH_FILE_CONTENT_99';
+  await withTempFile(MARKER, async (file) => {
+    const mock = await startMockLLM();
+    // XML tag path: the response is plain assistant text containing the tag.
+    mock.replyWith(`<read_file>${file}</read_file>`);
+    mock.replyWith('Read it.');
+    try {
+      const { runner } = buildRunner(mock.base);
+      const { ev, cb } = collector();
+      const messages = [{ role: 'user', content: 'read the file' }];
+      const { metrics } = await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+      assert.strictEqual(ev.tools.length, 1, 'the built-in read tool was dispatched');
+      assert.strictEqual(ev.tools[0].tag, 'read');
+
+      // XML results come back as a role:'user' "Tool execution results" message
+      // (not a role:'tool' message) — the long-standing XML shape.
+      const toolResult = messages.find((m) => m.role === 'user' && /Tool execution results/.test(m.content));
+      assert.ok(toolResult, 'XML path feeds results back as a user message');
+      assert.match(toolResult.content, new RegExp(MARKER), 'file content flowed back to the model');
+      assert.ok(!messages.some((m) => m.role === 'tool'), 'XML path does not use role:"tool" messages');
+
+      assert.strictEqual(metrics.turns.length, 2, 'tool turn + final turn');
+      assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'Read it.'), 'final answer recorded');
+      assert.strictEqual(mock.pending(), 0, 'both scripted responses consumed');
+    } finally {
+      await mock.close();
+    }
+  });
+});

package/test/anim-driver.test.js

@@ -0,0 +1,153 @@
+'use strict';
+
+// Single animation driver (Output Refactor — Phase 3).
+//
+// THE CHANGE: the status bar used to own TWO independent setIntervals — a 1 Hz
+// clock tick and a 100 ms spinner glyph cycle — that each repainted the whole
+// live region without coordinating. Phase 3 replaces both with ONE driver
+// (lib/ui/anim.js). The clock and spinner are now subscribers: one timer, one
+// frame counter, and at most ONE coordinated repaint per tick.
+//
+// These tests drive the single timer via node:test mock timers and assert that
+// (a) only one interval is ever created by a constructed status bar, (b)
+// advancing it updates BOTH the clock field and the spinner glyph, and (c) a
+// tick that fires more than one subscriber still produces exactly one repaint.
+
+const { test, mock } = require('node:test');
+const assert = require('node:assert');
+
+const { AnimDriver, BASE_INTERVAL_MS, TICKS_PER_SECOND } = require('../lib/ui/anim');
+const { FullStatusBar } = require('../lib/ui/status-bar');
+
+const layout = { cols: 200 };
+
+// ---------------------------------------------------------------------------
+// Exactly one interval is created — the clock and spinner share it.
+// ---------------------------------------------------------------------------
+
+test('a constructed status bar creates exactly one setInterval (one driver, not two)', () => {
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let intervalsCreated = 0;
+    const realSetInterval = global.setInterval;
+    global.setInterval = (...args) => { intervalsCreated++; return realSetInterval(...args); };
+    let bar;
+    try {
+      bar = new FullStatusBar(layout, () => {});
+      // Entering an animating state must NOT create a second timer — the
+      // spinner is a subscriber to the one driver, not its own interval.
+      bar.update('tool', 'running');
+    } finally {
+      global.setInterval = realSetInterval;
+    }
+    assert.strictEqual(intervalsCreated, 1, 'only one interval for clock + spinner');
+    bar.destroy();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Advancing the one driver updates BOTH the clock and the spinner glyph.
+// ---------------------------------------------------------------------------
+
+test('advancing the single driver updates both the clock and the spinner', () => {
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let redraws = 0;
+    const bar = new FullStatusBar(layout, () => { redraws++; });
+
+    // Animating state → the spinner glyph cycles. Capture the rendered glyph
+    // across two base-interval ticks; it must change.
+    bar.update('thinking', 'Thinking');
+    const glyphAt = () => {
+      const line = bar.renderLine();
+      // First non-space visible char after stripping ANSI is the spinner glyph.
+      const stripped = line.replace(/\x1b\[[0-9;]*m/g, '');
+      return stripped.trimStart()[0];
+    };
+    const g0 = glyphAt();
+    mock.timers.tick(BASE_INTERVAL_MS);
+    const g1 = glyphAt();
+    assert.notStrictEqual(g0, g1, 'spinner glyph advances on a driver tick');
+
+    // And the clock still ticks once per second off the SAME driver. Over a
+    // full second the driver fires repaints (the clock subscriber gates on
+    // frame % TICKS_PER_SECOND); assert at least the spinner cadence redraws.
+    redraws = 0;
+    mock.timers.tick(1000);
+    assert.ok(redraws >= TICKS_PER_SECOND - 1, 'driver repaints at the spinner cadence while animating');
+
+    bar.destroy();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// One coordinated repaint per tick — even when multiple subscribers fire.
+// ---------------------------------------------------------------------------
+
+test('a tick that fires multiple subscribers still yields exactly one repaint', () => {
+  // Pure driver-level check: two subscribers both request a repaint on the
+  // same frame; the driver coalesces them into a single _repaint call.
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let repaints = 0;
+    const d = new AnimDriver();
+    d.onRepaint(() => { repaints++; });
+    d.subscribe(() => true);  // always wants a repaint
+    d.subscribe(() => true);  // also always wants a repaint
+    d.start();
+    mock.timers.tick(BASE_INTERVAL_MS);
+    assert.strictEqual(repaints, 1, 'two truthy subscribers → one coordinated repaint');
+    mock.timers.tick(BASE_INTERVAL_MS);
+    assert.strictEqual(repaints, 2, 'one repaint per subsequent tick too');
+    d.stop();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// A tick where no subscriber wants a repaint produces none (idle clock gap).
+// ---------------------------------------------------------------------------
+
+test('a tick with no truthy subscriber produces no repaint', () => {
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let repaints = 0;
+    const d = new AnimDriver();
+    d.onRepaint(() => { repaints++; });
+    d.subscribe(() => false);
+    d.start();
+    mock.timers.tick(BASE_INTERVAL_MS * 5);
+    assert.strictEqual(repaints, 0, 'no repaint when nothing requests one');
+    d.stop();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// start()/stop() are idempotent — no stacked timers (the 5404bd0 lesson).
+// ---------------------------------------------------------------------------
+
+test('AnimDriver start()/stop() are idempotent and never stack timers', () => {
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let ticks = 0;
+    const d = new AnimDriver();
+    d.subscribe(() => { ticks++; return false; });
+    d.start(); d.start(); d.start();  // three starts → one timer
+    mock.timers.tick(BASE_INTERVAL_MS);
+    assert.strictEqual(ticks, 1, 'one tick per interval despite repeated start()');
+    d.stop(); d.stop();               // two stops → no error, fully stopped
+    ticks = 0;
+    mock.timers.tick(BASE_INTERVAL_MS * 5);
+    assert.strictEqual(ticks, 0, 'no ticks after stop()');
+    assert.strictEqual(d.isRunning(), false, 'isRunning() reflects stopped state');
+  } finally {
+    mock.timers.reset();
+  }
+});