webmcp-gauge 0.1.0

package/core/lint.test.mjs

@@ -0,0 +1,346 @@
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { DEFAULT_OPTIONS, lintManifest, lintToText, RULES, similarity } from './lint.mjs';
+
+const toolsFile = JSON.parse(
+  await readFile(new URL('../fixtures/broken/tools.json', import.meta.url), 'utf8')
+);
+
+/** The linter reads a manifest, so a variant from the fixture file is one directly. */
+const manifestOf = (variant) => ({
+  present: true,
+  settled: true,
+  settledAtMs: 1000,
+  tools: toolsFile.variants[variant].map(({ name, description, inputSchema, annotations }) => ({
+    name,
+    description,
+    inputSchema,
+    annotations,
+  })),
+});
+
+const rulesFired = (result) => new Set(result.findings.map((finding) => finding.rule));
+
+test('the reference-quality manifest lints clean, which is what calibrates the defaults', () => {
+  const result = lintManifest({ manifest: manifestOf('clean') });
+
+  assert.deepEqual(
+    result.findings,
+    [],
+    `a default that flags the page measured at 100% is a broken default. Fired: ${JSON.stringify(result.findings.map((f) => `${f.rule}:${f.tool}`))}`
+  );
+  assert.equal(result.counts.error, 0);
+  assert.equal(result.counts.warning, 0);
+  assert.equal(result.manifest.toolCount, 7);
+});
+
+test('the degraded manifest trips every documented failure family except budget', () => {
+  const result = lintManifest({ manifest: manifestOf('degraded') });
+
+  // Budget needs a tool count the sweep page deliberately does not have; it is
+  // reached with ?flood=N and tested separately below.
+  assert.deepEqual(result.families.sort(), ['description', 'name', 'schema']);
+  assert.ok(result.counts.error > 0, 'a page this bad must produce errors, not only advice');
+});
+
+test('each defect registered in the fixture fires the rule it claims to', () => {
+  const fired = rulesFired(lintManifest({ manifest: manifestOf('degraded') }));
+
+  // fixtures/broken/tools.json records, per injected defect, which rules it should
+  // trip. That register is the fixture's contract with the linter: if a defect
+  // stops firing its rule, one of the two changed silently.
+  const claimed = new Set(
+    toolsFile.defects.flatMap((defect) => defect.rules).filter((rule) => !rule.startsWith('budget/'))
+  );
+  assert.ok(claimed.size >= 6, 'the fixture should claim a spread of rules, not one');
+
+  for (const rule of claimed) {
+    assert.ok(fired.has(rule), `fixture claims ${rule} but the linter did not report it`);
+  }
+});
+
+test('an invalid name is reported with the character that makes it invalid', () => {
+  const result = lintManifest({
+    manifest: { present: true, settled: true, tools: [{ name: 'Clear Highlights', description: 'x'.repeat(80), inputSchema: { type: 'object', properties: {} } }] },
+  });
+
+  const finding = result.findings.find((entry) => entry.rule === 'name/invalid-characters');
+  assert.ok(finding, 'a name with a space must be flagged');
+  assert.match(finding.detail, /a space/);
+  assert.equal(finding.severity, 'error');
+});
+
+test('two tools with one name are reported, because only one of them is reachable', () => {
+  const tool = {
+    name: 'filter_rows',
+    description: 'A'.repeat(80),
+    inputSchema: { type: 'object', properties: {} },
+  };
+  const result = lintManifest({ manifest: { present: true, settled: true, tools: [tool, { ...tool, description: 'B'.repeat(80) }] } });
+
+  assert.equal(result.findings.filter((entry) => entry.rule === 'name/duplicate').length, 1);
+});
+
+test('identical descriptions are an error and near-identical ones a warning', () => {
+  const identical = lintManifest({
+    manifest: {
+      present: true,
+      settled: true,
+      tools: [
+        { name: 'a_tool', description: 'Works with the rows in the table and returns totals for what it finds.', inputSchema: { type: 'object', properties: {} } },
+        { name: 'b_tool', description: 'Works with the rows in the table and returns totals for what it finds.', inputSchema: { type: 'object', properties: {} } },
+      ],
+    },
+  });
+  const duplicate = identical.findings.find((entry) => entry.rule === 'description/duplicate');
+  assert.ok(duplicate);
+  assert.equal(duplicate.severity, 'error');
+  assert.equal(duplicate.tool, 'a_tool + b_tool');
+
+  const near = lintManifest({
+    manifest: {
+      present: true,
+      settled: true,
+      tools: [
+        { name: 'a_tool', description: 'Works with the rows in the table and returns totals for what it finds.', inputSchema: { type: 'object', properties: {} } },
+        { name: 'b_tool', description: 'Works with the rows in the table and returns counts for what it finds.', inputSchema: { type: 'object', properties: {} } },
+      ],
+    },
+  });
+  const nearFinding = near.findings.find((entry) => entry.rule === 'description/near-duplicate');
+  assert.ok(nearFinding, 'one changed word must not make two descriptions distinguishable');
+  assert.equal(nearFinding.severity, 'warning');
+  assert.equal(near.findings.some((entry) => entry.rule === 'description/duplicate'), false);
+});
+
+test('two genuinely different descriptions of the same length are left alone', () => {
+  const result = lintManifest({
+    manifest: {
+      present: true,
+      settled: true,
+      tools: [
+        { name: 'a_tool', description: 'Total the loaded spending per calendar month, oldest first, so month-on-month changes are visible.', inputSchema: { type: 'object', properties: {} } },
+        { name: 'b_tool', description: 'Find rows that are unusually large compared with the rest of their own category, using a z-score.', inputSchema: { type: 'object', properties: {} } },
+      ],
+    },
+  });
+
+  assert.deepEqual(result.findings, []);
+});
+
+/**
+ * `description/indistinguishable-pair`, adopted 2026-09-05 after five measured arms
+ * showed a 45-point loss that no description-similarity threshold catches. These
+ * tests pin the two halves of the rule and, more importantly, the cases it must
+ * stay silent on — each of which is a manifest with a measured rate at or near the
+ * ceiling, so a false positive here would be a rule that flags working pages.
+ */
+const pairPresent = (result) =>
+  result.findings.some((entry) => entry.rule === 'description/indistinguishable-pair');
+
+const twoTools = (aName, aDescription, bName, bDescription, options) =>
+  lintManifest({
+    manifest: {
+      present: true,
+      settled: true,
+      tools: [
+        { name: aName, description: aDescription, inputSchema: { type: 'object', properties: {} } },
+        { name: bName, description: bDescription, inputSchema: { type: 'object', properties: {} } },
+      ],
+    },
+    options,
+  });
+
+const VAGUE = 'Works with the rows in the table and returns totals for what it finds.';
+const ALSO_VAGUE = 'Handles the listed entries and hands back combined figures for whatever turns up.';
+const INFORMATIVE = 'Total the loaded spending by category, largest first, and return aggregates only.';
+
+test('close names plus two descriptions that never say which tool is which is a warning', () => {
+  const result = twoTools('sum_by_category', VAGUE, 'summarise_by_category', ALSO_VAGUE);
+  const finding = result.findings.find((entry) => entry.rule === 'description/indistinguishable-pair');
+
+  assert.ok(finding, 'this is the configuration measured at 48–58% against a 95% baseline');
+  assert.equal(finding.severity, 'warning');
+  assert.equal(finding.tool, 'sum_by_category + summarise_by_category');
+  assert.equal(finding.evidence.nameSimilarity, 0.5);
+  // It must not need the two descriptions to resemble each other: these two share
+  // almost nothing, which is exactly the case the similarity rules cannot see.
+  assert.ok(similarity(VAGUE, ALSO_VAGUE) < DEFAULT_OPTIONS.nearDuplicateThreshold);
+  assert.equal(result.findings.some((entry) => entry.rule === 'description/near-duplicate'), false);
+});
+
+test('one description that says what its own tool is for is enough to stay silent', () => {
+  // Measured: `ablate-competitor-vague` — a vague competitor beside a well-described
+  // tool — cost nothing at all (95.0%, identical to clean failure for failure).
+  assert.equal(pairPresent(twoTools('sum_by_category', INFORMATIVE, 'summarise_by_category', VAGUE)), false);
+  assert.equal(pairPresent(twoTools('sum_by_category', VAGUE, 'summarise_by_category', INFORMATIVE)), false);
+});
+
+test('two vague descriptions on unrelated names are not this rule\'s business', () => {
+  // Measured: `ablate-desc-degraded` — vague descriptions with no close-named
+  // sibling — cost 1.7 points, inside the harness's own noise.
+  assert.equal(pairPresent(twoTools('sum_by_category', VAGUE, 'clear_highlights', ALSO_VAGUE)), false);
+});
+
+test('the name-similarity threshold is an option, and the rule follows it', () => {
+  const names = ['fetch_orders', VAGUE, 'orders_report', ALSO_VAGUE];
+  assert.equal(pairPresent(twoTools(...names)), false, 'these names share one token of three');
+  assert.equal(pairPresent(twoTools(...names, { nameSimilarityThreshold: 0.3 })), true);
+});
+
+test('the rule reports presence, not cost — it cannot know what a pair will cost', () => {
+  // The five measured rungs span 48.3% to 83.3% and the rule fires identically on
+  // all of them. That is deliberate: severity is a property of the rule, and only
+  // `run` measures what a defect costs.
+  const identical = twoTools('sum_by_category', VAGUE, 'summarise_by_category', VAGUE);
+  const distant = twoTools('sum_by_category', VAGUE, 'summarise_by_category', ALSO_VAGUE);
+  const pairOf = (result) => result.findings.find((entry) => entry.rule === 'description/indistinguishable-pair');
+
+  assert.equal(pairOf(identical).severity, pairOf(distant).severity);
+  // The byte-identical case additionally trips the error-graded duplicate rule, so
+  // the two rules stack rather than replace one another.
+  assert.equal(identical.findings.some((entry) => entry.rule === 'description/duplicate'), true);
+  assert.equal(distant.findings.some((entry) => entry.rule === 'description/duplicate'), false);
+});
+
+test('a required property with no description is an error, an optional one a warning', () => {
+  const result = lintManifest({
+    manifest: {
+      present: true,
+      settled: true,
+      tools: [
+        {
+          name: 'top_expenses',
+          description: 'D'.repeat(80),
+          inputSchema: {
+            type: 'object',
+            required: ['mode'],
+            properties: { mode: { type: 'string' }, locale: { type: 'string' } },
+          },
+        },
+      ],
+    },
+  });
+
+  const required = result.findings.find((entry) => entry.rule === 'schema/required-without-description');
+  const optional = result.findings.find((entry) => entry.rule === 'schema/undocumented-property');
+  assert.equal(required.severity, 'error');
+  assert.match(required.detail, /must guess/);
+  assert.match(optional.detail, /'locale'/);
+});
+
+test('a required property that is not declared at all is reported', () => {
+  const result = lintManifest({
+    manifest: {
+      present: true,
+      settled: true,
+      tools: [{ name: 'a_tool', description: 'D'.repeat(80), inputSchema: { type: 'object', required: ['ghost'], properties: {} } }],
+    },
+  });
+
+  assert.match(
+    result.findings.find((entry) => entry.rule === 'schema/required-without-description').detail,
+    /not declared in properties/
+  );
+});
+
+test('a non-object schema stops schema analysis for that tool rather than throwing', () => {
+  const result = lintManifest({
+    manifest: {
+      present: true,
+      settled: true,
+      tools: [{ name: 'top.expenses.v2', description: 'D'.repeat(80), inputSchema: { type: 'string' } }],
+    },
+  });
+
+  assert.equal(result.findings.filter((entry) => entry.rule.startsWith('schema/')).length, 1);
+  assert.equal(result.findings.find((entry) => entry.rule === 'schema/not-object').severity, 'error');
+});
+
+test('the property-count threshold sits exactly where the reference page does', () => {
+  const propertiesOf = (count) =>
+    Object.fromEntries(
+      Array.from({ length: count }, (_, index) => [`p${index}`, { type: 'string', description: 'documented' }])
+    );
+  const at = lintManifest({
+    manifest: { present: true, settled: true, tools: [{ name: 'a_tool', description: 'D'.repeat(80), inputSchema: { type: 'object', properties: propertiesOf(DEFAULT_OPTIONS.maxProperties) } }] },
+  });
+  const over = lintManifest({
+    manifest: { present: true, settled: true, tools: [{ name: 'a_tool', description: 'D'.repeat(80), inputSchema: { type: 'object', properties: propertiesOf(DEFAULT_OPTIONS.maxProperties + 1) } }] },
+  });
+
+  assert.deepEqual(at.findings, [], 'six properties is what the reference page ships and it invokes at 99.2%');
+  assert.equal(over.findings.filter((entry) => entry.rule === 'schema/over-parameterised').length, 1);
+});
+
+test('budget headroom warns well below the count that has been reported to break a page, and stays a warning at it', () => {
+  const manifestWith = (count) => ({
+    present: true,
+    settled: true,
+    tools: Array.from({ length: count }, (_, index) => ({
+      name: `filler_tool_${index}`,
+      description: 'A filler tool registered only to occupy a slot in this manifest.',
+      inputSchema: { type: 'object', properties: {} },
+    })),
+  });
+
+  assert.equal(
+    lintManifest({ manifest: manifestWith(DEFAULT_OPTIONS.budgetWarnAt - 1) }).findings.some((entry) => entry.rule === 'budget/headroom'),
+    false
+  );
+  const warned = lintManifest({ manifest: manifestWith(DEFAULT_OPTIONS.budgetWarnAt) }).findings.find((entry) => entry.rule === 'budget/headroom');
+  assert.equal(warned.severity, 'warning');
+  assert.match(warned.detail, /headroom here is unknown rather than fine/);
+
+  // Chrome 152 registered and surfaced all 507 tools of a flooded fixture (measured
+  // 2026-08-31), so the 296 field report is an unknown rather than a ceiling. An
+  // error here would be the false positive the calibrated defaults exist to prevent.
+  const atReported = lintManifest({ manifest: manifestWith(DEFAULT_OPTIONS.budgetBreakAt) }).findings.find((entry) => entry.rule === 'budget/headroom');
+  assert.equal(atReported.severity, 'warning');
+  assert.match(atReported.detail, /does not reproduce on Chrome 152/);
+});
+
+test('thresholds are options, so a project can set its own and still be reported', () => {
+  const manifest = {
+    present: true,
+    settled: true,
+    tools: [{ name: 'a_tool', description: 'Short one.', inputSchema: { type: 'object', properties: {} } }],
+  };
+
+  assert.equal(lintManifest({ manifest }).findings.some((entry) => entry.rule === 'description/thin'), true);
+  assert.equal(
+    lintManifest({ manifest, options: { minDescriptionChars: 5 } }).findings.some((entry) => entry.rule === 'description/thin'),
+    false
+  );
+  assert.equal(lintManifest({ manifest, options: { minDescriptionChars: 5 } }).thresholds.minDescriptionChars, 5);
+});
+
+test('similarity is symmetric, 1 for identical text and 0 against nothing', () => {
+  assert.equal(similarity('a b c', 'c b a'), 1);
+  assert.equal(similarity('a b c', ''), 0);
+  assert.equal(similarity('one two', 'two three'), similarity('two three', 'one two'));
+});
+
+test('every rule in the registry has a severity the emitter can render', () => {
+  for (const rule of RULES) {
+    assert.ok(['error', 'warning'].includes(rule.severity), `${rule.id} has severity ${rule.severity}`);
+    assert.ok(rule.id.includes('/'), `${rule.id} is not family-prefixed`);
+  }
+  assert.equal(new Set(RULES.map((rule) => rule.id)).size, RULES.length);
+});
+
+test('the text report never lets a clean lint read as a measured invocation rate', () => {
+  const text = lintToText(lintManifest({ manifest: manifestOf('clean') }), { subject: 'clean' });
+
+  assert.match(text, /No findings/);
+  assert.match(text, /A clean lint is not a measured invocation rate/);
+});
+
+test('the text report leads with errors and names the thresholds it used', () => {
+  const text = lintToText(lintManifest({ manifest: manifestOf('degraded') }), { subject: 'degraded' });
+  const firstFindingLine = text.split('\n').find((line) => line.startsWith('ERROR') || line.startsWith('WARN'));
+
+  assert.ok(firstFindingLine.startsWith('ERROR'), `errors must sort first, got ${firstFindingLine}`);
+  assert.match(text, /Calibrated on the reference page, not taken from the spec/);
+});

package/core/orchestrate.mjs

@@ -0,0 +1,128 @@
+/**
+ * Runs S measurement sessions, each in its own OS process.
+ *
+ * The child process is not ceremony. Node pools HTTP connections per process, so
+ * sessions sharing a process share the judge's keep-alive connections, and a
+ * "session" that reuses the same socket to the same provider is not independent in
+ * the way a reproducibility claim needs. One process per session also means one
+ * browser, one cold profile, and crash isolation: a session that dies takes only
+ * its own trials with it, and the checkpoint keeps the rest.
+ *
+ * What this still does not isolate, and the report says so: the machine, the
+ * network path, the provider's own server-side state, and time - three sessions
+ * minutes apart are not three sessions on three days.
+ *
+ * A session is watched rather than merely awaited. A child that stops making
+ * progress and never exits stalled a whole run silently once, and the layer that
+ * notices has to be the one that can kill it. The watchdog is measured in *progress*
+ * rather than elapsed time: an honest session duration depends on how many trials it
+ * was given, while "wrote nothing for ten minutes" means the same thing for a
+ * 20-trial session and a 480-trial one.
+ */
+import { spawn } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import { killTree } from '../browser/launch.mjs';
+
+/** Newest mtime across the files a session appends to as it works. */
+const lastProgressAt = async (paths) => {
+  let newest = 0;
+  for (const path of paths) {
+    try {
+      const info = await stat(path);
+      newest = Math.max(newest, info.mtimeMs);
+    } catch {
+      // A file that does not exist yet is not progress, and not an error either.
+    }
+  }
+  return newest;
+};
+
+export const runSessions = async ({
+  sessions = 3,
+  binPath,
+  args,
+  gapSeconds = 0,
+  /** Files a working session appends to: the checkpoint and the failure log. */
+  progressPaths = [],
+  /**
+   * How long a session may write nothing before it counts as stalled. The per-trial
+   * deadline inside a session is 180s, so ten minutes of silence means the stall is
+   * somewhere a trial deadline cannot see - launching a browser, or the process.
+   */
+  stallTimeoutMs = 600000,
+  pollIntervalMs = 15000,
+  onSessionStart = () => {},
+  onSessionEnd = () => {},
+}) => {
+  const results = [];
+
+  for (let session = 1; session <= sessions; session += 1) {
+    if (session > 1 && gapSeconds > 0) {
+      await new Promise((resolve) => setTimeout(resolve, gapSeconds * 1000));
+    }
+
+    onSessionStart({ session, sessions });
+    const startedMs = Date.now();
+
+    const result = await new Promise((resolve) => {
+      const child = spawn(
+        process.execPath,
+        [binPath, 'session', '--session', String(session), ...args],
+        { stdio: ['ignore', 'inherit', 'inherit'] }
+      );
+
+      let settled = false;
+      const finish = (value) => {
+        if (settled) return;
+        settled = true;
+        clearInterval(watchdog);
+        resolve(value);
+      };
+
+      let lastSeenAt = Date.now();
+      let lastProgress = 0;
+      // Set before the kill, because killing the child makes 'close' fire while the
+      // watchdog is still awaiting taskkill, and the first finish() wins. Without
+      // this flag a session we killed reports as an ordinary non-zero exit, which is
+      // the one distinction the watchdog exists to make.
+      let stallReason = null;
+
+      const watchdog = setInterval(async () => {
+        if (settled || stallReason) return;
+
+        const progressAt = await lastProgressAt(progressPaths);
+        if (progressAt > lastProgress) {
+          lastProgress = progressAt;
+          lastSeenAt = Date.now();
+          return;
+        }
+        if (Date.now() - lastSeenAt < stallTimeoutMs) return;
+
+        // Killed rather than waited on, and reported as a stall rather than as a
+        // crash: the parent recomputes coverage from the plan, so whatever this
+        // session did not reach comes back as missing and --resume retries it.
+        stallReason = `wrote nothing for ${Math.round((Date.now() - lastSeenAt) / 1000)}s and was killed`;
+        if (child.pid) await killTree(child.pid);
+        finish({ session, code: null, stalled: true, error: stallReason });
+      }, pollIntervalMs);
+      watchdog.unref?.();
+
+      child.on('error', (error) =>
+        finish({ session, code: null, stalled: false, error: String(error.message ?? error) })
+      );
+      child.on('close', (code) =>
+        finish(
+          stallReason
+            ? // The exit code of a process we killed describes the kill, not the run.
+              { session, code: null, stalled: true, error: stallReason }
+            : { session, code, stalled: false, error: null }
+        )
+      );
+    });
+
+    results.push({ ...result, elapsedMs: Date.now() - startedMs });
+    onSessionEnd({ session, sessions, ...result });
+  }
+
+  return results;
+};

package/core/orchestrate.test.mjs

@@ -0,0 +1,191 @@
+/**
+ * The orchestrator's job in a failure is to notice and to kill. These tests use
+ * throwaway "session" scripts instead of the real one, because what is being tested
+ * is the watchdog contract - progress resets it, silence trips it, and a stall is
+ * reported as a stall rather than as a crash - not anything about browsers or judges.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runSessions } from './orchestrate.mjs';
+
+const withTempDir = async (body) => {
+  const dir = await mkdtemp(join(tmpdir(), 'webmcp-gauge-orch-'));
+  try {
+    return await body(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+};
+
+const fakeSession = async (dir, name, source) => {
+  const path = join(dir, name);
+  await writeFile(path, source, 'utf8');
+  return path;
+};
+
+test('a session that exits is reported by its exit code, with no stall', async () => {
+  await withTempDir(async (dir) => {
+    const binPath = await fakeSession(dir, 'ok-session.mjs', 'process.exitCode = 0;\n');
+
+    const results = await runSessions({
+      sessions: 2,
+      binPath,
+      args: [],
+      progressPaths: [join(dir, 'sweep.jsonl')],
+      stallTimeoutMs: 60000,
+      pollIntervalMs: 50,
+    });
+
+    assert.deepEqual(
+      results.map(({ session, code, stalled, error }) => ({ session, code, stalled, error })),
+      [
+        { session: 1, code: 0, stalled: false, error: null },
+        { session: 2, code: 0, stalled: false, error: null },
+      ]
+    );
+  });
+});
+
+test('a non-zero exit is an exit, not a stall', async () => {
+  await withTempDir(async (dir) => {
+    // This is what an incomplete session looks like under the exit-code contract:
+    // code 2, which the parent must not confuse with a process it had to kill.
+    const binPath = await fakeSession(dir, 'incomplete-session.mjs', 'process.exitCode = 2;\n');
+
+    const [result] = await runSessions({
+      sessions: 1,
+      binPath,
+      args: [],
+      progressPaths: [join(dir, 'sweep.jsonl')],
+      stallTimeoutMs: 60000,
+      pollIntervalMs: 50,
+    });
+
+    assert.equal(result.code, 2);
+    assert.equal(result.stalled, false);
+  });
+});
+
+test('a session that writes nothing is killed and reported as stalled', async () => {
+  await withTempDir(async (dir) => {
+    const binPath = await fakeSession(
+      dir,
+      'hanging-session.mjs',
+      'setInterval(() => {}, 1000);\n'
+    );
+
+    const startedMs = Date.now();
+    const [result] = await runSessions({
+      sessions: 1,
+      binPath,
+      args: [],
+      progressPaths: [join(dir, 'sweep.jsonl')],
+      stallTimeoutMs: 400,
+      pollIntervalMs: 100,
+    });
+
+    assert.equal(result.stalled, true, 'a process that never exits must be killed, not awaited');
+    assert.equal(result.code, null);
+    assert.match(result.error, /wrote nothing for \d+s and was killed/);
+    assert.ok(
+      Date.now() - startedMs < 30000,
+      'the whole point is that this returns in seconds rather than never'
+    );
+  });
+});
+
+test('progress resets the watchdog, so a slow session is not mistaken for a stalled one', async () => {
+  await withTempDir(async (dir) => {
+    const checkpoint = join(dir, 'sweep.jsonl');
+    const binPath = await fakeSession(
+      dir,
+      'slow-session.mjs',
+      `import { appendFile } from 'node:fs/promises';
+let written = 0;
+const tick = setInterval(async () => {
+  written += 1;
+  await appendFile(${JSON.stringify(checkpoint)}, JSON.stringify({ trial: written }) + '\\n', 'utf8');
+  if (written >= 8) {
+    clearInterval(tick);
+    process.exit(0);
+  }
+}, 100);
+`
+    );
+
+    const [result] = await runSessions({
+      sessions: 1,
+      binPath,
+      args: [],
+      progressPaths: [checkpoint],
+      // Shorter than the session's total runtime, longer than the gap between writes:
+      // the difference between "taking a while" and "not working" is progress.
+      stallTimeoutMs: 350,
+      pollIntervalMs: 50,
+    });
+
+    assert.equal(result.stalled, false, `killed a session that was making progress: ${result.error}`);
+    assert.equal(result.code, 0);
+    assert.equal((await readFile(checkpoint, 'utf8')).trim().split('\n').length, 8);
+  });
+});
+
+test('--gap actually spaces the sessions out, which is the only way drift can be measured', async () => {
+  await withTempDir(async (dir) => {
+    const binPath = await fakeSession(dir, 'quick-session.mjs', 'process.exitCode = 0;\n');
+
+    const shape = { binPath, args: [], progressPaths: [join(dir, 'sweep.jsonl')], pollIntervalMs: 50 };
+    const startedBackToBack = Date.now();
+    await runSessions({ sessions: 3, ...shape });
+    const backToBackMs = Date.now() - startedBackToBack;
+
+    const startedSpaced = Date.now();
+    await runSessions({ sessions: 3, gapSeconds: 0.4, ...shape });
+    const spacedMs = Date.now() - startedSpaced;
+
+    // Two gaps for three sessions - the wait goes before every session except the
+    // first, or the run would end with a pointless sleep.
+    assert.ok(
+      spacedMs - backToBackMs >= 700,
+      `expected roughly two 400ms gaps, got ${spacedMs}ms against ${backToBackMs}ms`
+    );
+  });
+});
+
+test('the failure log counts as progress, so an all-failing session is not killed', async () => {
+  await withTempDir(async (dir) => {
+    // A session whose every trial fails writes only to the failure log. Watching the
+    // checkpoint alone would kill exactly the run that has the most to report.
+    const failures = join(dir, 'harness-failures.jsonl');
+    const binPath = await fakeSession(
+      dir,
+      'failing-session.mjs',
+      `import { appendFile } from 'node:fs/promises';
+let n = 0;
+const tick = setInterval(async () => {
+  n += 1;
+  await appendFile(${JSON.stringify(failures)}, JSON.stringify({ kind: 'judge_unavailable', n }) + '\\n', 'utf8');
+  if (n >= 6) {
+    clearInterval(tick);
+    process.exit(2);
+  }
+}, 100);
+`
+    );
+
+    const [result] = await runSessions({
+      sessions: 1,
+      binPath,
+      args: [],
+      progressPaths: [join(dir, 'sweep.jsonl'), failures],
+      stallTimeoutMs: 350,
+      pollIntervalMs: 50,
+    });
+
+    assert.equal(result.stalled, false, `killed an all-failing session: ${result.error}`);
+    assert.equal(result.code, 2);
+  });
+});