@jrpool/kilotest 47.0.1 → 49.0.0

package/test/dbFixture.ts

@@ -17,5 +17,13 @@ export const fixtureDBDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kilotest-db-'
 // Copy the tracked fixture database to the temporary directory.
 fs.cpSync(path.join(import.meta.dirname, 'fixtures', 'db'), fixtureDBDir, {recursive: true});
 
+// Git does not track empty directories, so the job-state subdirectories are absent
+// from a fresh checkout even though they are part of the fixture layout. Create them
+// here rather than tracking placeholder files, which readdir-based job listing would
+// otherwise pick up as (invalid) job files.
+for (const category of ['queue', 'claimed', 'failed']) {
+  fs.mkdirSync(path.join(fixtureDBDir, 'jobs', category), {recursive: true});
+}
+
 // Remove the copy when the process exits.
 process.on('exit', () => fs.rmSync(fixtureDBDir, {recursive: true, force: true}));

package/util.test.ts

@@ -52,8 +52,7 @@ import {
   processTestRequest,
   testRequestsLock,
   testRequestsPath,
-  reportsPath,
-  addTestRequest
+  reportsPath
 } from './util.ts';
 
 // TESTS
@@ -366,9 +365,8 @@ test('objectSort sorts objects numerically descending', () => {
 
 // TESTS FOR processTestRequest AND isReportAvailable
 
-// These tests use the fixture database directory and the real web/requestTest template.
+// These tests use the fixture database directory.
 import {fixtureDBDir as fixtureDbDir} from './test/dbFixture.ts';
-const requestTestDir = path.join(import.meta.dirname, 'web', 'requestTest');
 const savedDbDir = process.env.DB_DIR;
 
 before(() => {
@@ -428,44 +426,15 @@ test('getPageDataStrings uses provided pageData instead of reading the report',
   assert.ok(strings.testInfo.includes('1 day ago'));
 });
 
-test('processTestRequest returns an error for an invalid test type', async () => {
-  const result: any = await processTestRequest('invalid', requestTestDir, 'Page', 'https://example.com', 'because');
-  assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid request');
-});
-
-test('processTestRequest returns an error for an invalid URL', async () => {
-  const result: any = await processTestRequest('test', requestTestDir, 'Page', 'not-a-url', 'because');
-  assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid request');
-});
-
-test('processTestRequest returns an error for a short reason', async () => {
-  const result: any = await processTestRequest('test', requestTestDir, 'Page', 'https://example.com', 'abc');
-  assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid request');
-});
-
-test('processTestRequest returns an error for a missing description', async () => {
-  const result: any = await processTestRequest('test', requestTestDir, '', 'https://example.com', 'because');
-  assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid request');
-});
-
-test('processTestRequest returns an error for a mismatched directory name', async () => {
-  const result: any = await processTestRequest('test', '/tmp/wrongDir', 'Page', 'https://example.com', 'because');
-  assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid request');
-});
-
-
-test('processTestRequest succeeds and populates the template for a valid request', {timeout: 500}, async () => {
+test('processTestRequest succeeds for a valid new-test request', {timeout: 500}, async () => {
   // Reset testRequests.json to empty before the test.
   await fs.writeFile(testRequestsPath(), '{}\n');
-  const result: any = await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'because accessibility');
-  assert.equal(result.status, 'ok');
-  assert.ok(result.answerPage.includes('Example Page'));
-  assert.ok(result.answerPage.includes('because accessibility'));
+  const {result} = await processTestRequest(
+    'because accessibility', {description: 'Example Page', url: 'https://example.com'}
+  );
+  assert.equal(result, 'ok');
+  const testRequests = JSON.parse(await fs.readFile(testRequestsPath(), 'utf8'));
+  assert.equal(testRequests['https://example.com'][0].description, 'Example Page');
   // Clean up testRequests.json.
   await fs.writeFile(testRequestsPath(), '{}\n');
 });
@@ -473,15 +442,23 @@ test('processTestRequest succeeds and populates the template for a valid request
 test('processTestRequest returns a duplicate error for a repeated request', {timeout: 500}, async () => {
   // Reset testRequests.json to empty, then make a successful request.
   await fs.writeFile(testRequestsPath(), '{}\n');
-  await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'because accessibility');
-  // Repeat the same request.
-  const result: any = await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'another reason');
-  assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Duplicate request');
+  const target = {description: 'Example Page', url: 'https://example.com'};
+  await processTestRequest('because accessibility', target);
+  // Repeat the same request (same description, URL, and reason).
+  const {result} = await processTestRequest('because accessibility', target);
+  assert.equal(result, 'duplicate');
   // Clean up testRequests.json.
   await fs.writeFile(testRequestsPath(), '{}\n');
 });
 
+test('processTestRequest returns a retest error when a report already exists for the page', async () => {
+  // The fixture database already has a report for this description and URL.
+  const {result} = await processTestRequest(
+    'because accessibility', {description: 'Mixed Outcomes Page', url: 'https://example.com/mixed'}
+  );
+  assert.equal(result, 'retest');
+});
+
 test('annotateReportObject annotates a report object in place without reading or writing a file', async () => {
   // A report object that was never written to disk (e.g. one just received from a worker,
   // as in index.ts's worker/report handler, which annotates before the first write).
@@ -558,6 +535,92 @@ test('isReportAvailable returns false for an unknown page and URL', async () =>
   assert.equal(result, false);
 });
 
+// TESTS FOR processTestRequest's claimed/queued-job detection
+
+test('processTestRequest returns "description" for a page matching a claimed job by description', async () => {
+  const claimedPath = path.join(jobsPath(), 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, getJSON({
+    target: {what: 'Claimed Page', url: 'https://example.com/claimed-job'}
+  }));
+  try {
+    const {result} = await processTestRequest(
+      'because', {description: 'Claimed Page', url: 'https://example.com/some-other-url'}
+    );
+    assert.equal(result, 'description');
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('processTestRequest returns "url" for a page matching a claimed job by URL', async () => {
+  const claimedPath = path.join(jobsPath(), 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, getJSON({
+    target: {what: 'Some Claimed Page', url: 'https://example.com/claimed-url'}
+  }));
+  try {
+    const {result} = await processTestRequest(
+      'because', {description: 'A Different Page', url: 'https://example.com/claimed-url'}
+    );
+    assert.equal(result, 'url');
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('processTestRequest returns "description" for a page matching a queued job by description', async () => {
+  const queuedPath = path.join(jobsPath(), 'queue', 'que.json');
+  await fs.writeFile(queuedPath, getJSON({
+    target: {what: 'Queued Page', url: 'https://example.com/queued-job'}
+  }));
+  try {
+    const {result} = await processTestRequest(
+      'because', {description: 'Queued Page', url: 'https://example.com/some-other-url'}
+    );
+    assert.equal(result, 'description');
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('processTestRequest returns "url" for a page matching a queued job by URL', async () => {
+  const queuedPath = path.join(jobsPath(), 'queue', 'que.json');
+  await fs.writeFile(queuedPath, getJSON({
+    target: {what: 'Some Queued Page', url: 'https://example.com/queued-url'}
+  }));
+  try {
+    const {result} = await processTestRequest(
+      'because', {description: 'A Different Page', url: 'https://example.com/queued-url'}
+    );
+    assert.equal(result, 'url');
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('processTestRequest returns "nonreport" when the cited report does not exist', async () => {
+  // Cite a timeStamp/jobID that does not correspond to any available report.
+  const {result} = await processTestRequest('because', {timeStamp: '999999T9999', jobID: 'xxx'});
+  assert.equal(result, 'nonreport');
+});
+
+test('processTestRequest throws when a job file in a category directory is defective', async () => {
+  const claimedPath = path.join(jobsPath(), 'claimed', 'bad.json');
+  await fs.writeFile(claimedPath, 'not valid json');
+  try {
+    await assert.rejects(
+      processTestRequest('because', {description: 'Any Page', url: 'https://example.com/any'}),
+      /Failed to process test request/
+    );
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
 // TESTS FOR REMAINING BRANCH COVERAGE
 
 test('getJobNames creates missing job directories and returns empty arrays', async () => {
@@ -605,6 +668,93 @@ test('getJobNames throws when a job directory is a file, not a directory', async
   }
 });
 
+test('getJobsData returns an empty array, instead of throwing ENOENT, when its category directory does not yet exist', async () => {
+  // Regression test: on a fresh deployment, jobs/claimed and jobs/queue may never
+  // have been created yet (no job has ever been claimed or queued there). getJobsData
+  // must tolerate that the same way getJobNames does, rather than reading the
+  // category directory directly and throwing ENOENT.
+  const os = await import('node:os');
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-jobsdata-'));
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = path.join(tmpRoot, 'db');
+  try {
+    const {getJobsData} = await import('./util.ts');
+    const result = await getJobsData('claimed');
+    assert.deepEqual(result, []);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    await fs.rm(tmpRoot, {recursive: true}).catch(() => {});
+  }
+});
+
+test('getJobsData skips a job file that is removed between the directory listing and its read', async (t) => {
+  // Regression test: on the deployed server, a worker can complete or reclaim a
+  // claimed job (moving or deleting its file) between getJobsData listing the
+  // claimed directory and reading a specific file it found there. That race must
+  // result in the vanished job simply being skipped, not an uncaught ENOENT.
+  const claimedPath = path.join(jobsPath(), 'claimed', 'raced.json');
+  await fs.writeFile(claimedPath, getJSON({
+    target: {what: 'Raced Page', url: 'https://example.com/raced'}
+  }));
+  const originalReadFile = fs.readFile;
+  t.mock.method(fs, 'readFile', async (filePath: any, ...rest: any[]) => {
+    // Simulate the file having been removed by a worker just before this read.
+    if (String(filePath) === claimedPath) {
+      await fs.unlink(claimedPath);
+      const error: any = new Error('ENOENT: no such file or directory');
+      error.code = 'ENOENT';
+      throw error;
+    }
+    return (originalReadFile as any)(filePath, ...rest);
+  });
+  try {
+    const {getJobsData} = await import('./util.ts');
+    const result = await getJobsData('claimed');
+    assert.ok(!result.some(job => job.description === 'Raced Page'));
+  }
+  finally {
+    t.mock.reset();
+    await fs.unlink(claimedPath).catch(() => {});
+  }
+});
+
+test('getJobsData throws when a job file cannot be read for a reason other than its removal', async () => {
+  // A directory where a job file is expected causes fs.readFile to fail with
+  // EISDIR, not ENOENT, so getJobsData must still treat it as defective (unlike
+  // the ENOENT case above, which is skipped as a normal race with a worker).
+  const claimedDirAsFile = path.join(jobsPath(), 'claimed', 'notAFile.json');
+  await fs.mkdir(claimedDirAsFile);
+  try {
+    const {getJobsData} = await import('./util.ts');
+    await assert.rejects(getJobsData('claimed'), /defective/);
+  }
+  finally {
+    await fs.rm(claimedDirAsFile, {recursive: true}).catch(() => {});
+  }
+});
+
+test('processTestRequest succeeds on a fresh deployment with no job directories yet', async () => {
+  // Regression test for the same ENOENT scenario, exercised through the actual
+  // public interface: a brand-new DB_DIR with no jobs/claimed or jobs/queue
+  // directories must not prevent a new-test request from being approved.
+  const os = await import('node:os');
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-freshdeploy-'));
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = path.join(tmpRoot, 'db');
+  try {
+    const {processTestRequest: freshProcessTestRequest} = await import('./util.ts');
+    const {result} = await freshProcessTestRequest(
+      'because accessibility', {description: 'Fresh Deploy Page', url: 'https://example.com/fresh'}
+    );
+    assert.equal(result, 'ok');
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    await fs.rm(tmpRoot, {recursive: true}).catch(() => {});
+  }
+});
+
 test('getObject throws for a file that is not valid JSON', async () => {
   const tmpFile = path.join((await import('node:os')).tmpdir(), 'kilotest-test-invalid.json');
   (await import('node:fs')).writeFileSync(tmpFile, 'not json');
@@ -683,69 +833,6 @@ test('getPOSTData resolves with parsed query for form-urlencoded requests', asyn
   assert.equal(result.why, 'Because');
 });
 
-test('getRequestability returns "claimed" for a URL in a claimed job', async () => {
-  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-requestability-test';
-  const fsSync = await import('node:fs');
-  fsSync.mkdirSync(tmpDir + '/jobs/claimed', {recursive: true});
-  fsSync.mkdirSync(tmpDir + '/jobs/queue', {recursive: true});
-  fsSync.mkdirSync(tmpDir + '/jobs/failed', {recursive: true});
-  fsSync.writeFileSync(tmpDir + '/jobs/claimed/job1.json', JSON.stringify({
-    target: {url: 'https://example.com/test', what: 'Test Page'}
-  }));
-  const savedDbDir = process.env.DB_DIR;
-  process.env.DB_DIR = tmpDir;
-  try {
-    const {getRequestability} = await import('./util.ts');
-    const result = await getRequestability('https://example.com/test');
-    assert.equal(result, 'claimed');
-  }
-  finally {
-    process.env.DB_DIR = savedDbDir;
-    fsSync.rmSync(tmpDir, {recursive: true});
-  }
-});
-
-test('getRequestability returns "queued" for a URL in a queued job', async () => {
-  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-requestability-test';
-  const fsSync = await import('node:fs');
-  fsSync.mkdirSync(tmpDir + '/jobs/claimed', {recursive: true});
-  fsSync.mkdirSync(tmpDir + '/jobs/queue', {recursive: true});
-  fsSync.mkdirSync(tmpDir + '/jobs/failed', {recursive: true});
-  fsSync.writeFileSync(tmpDir + '/jobs/queue/job1.json', JSON.stringify({
-    target: {url: 'https://example.com/test', what: 'Test Page'}
-  }));
-  const savedDbDir = process.env.DB_DIR;
-  process.env.DB_DIR = tmpDir;
-  try {
-    const {getRequestability} = await import('./util.ts');
-    const result = await getRequestability('https://example.com/test');
-    assert.equal(result, 'queued');
-  }
-  finally {
-    process.env.DB_DIR = savedDbDir;
-    fsSync.rmSync(tmpDir, {recursive: true});
-  }
-});
-
-test('getRequestability returns empty string for a URL with no matching jobs', async () => {
-  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-requestability-test';
-  const fsSync = await import('node:fs');
-  fsSync.mkdirSync(tmpDir + '/jobs/claimed', {recursive: true});
-  fsSync.mkdirSync(tmpDir + '/jobs/queue', {recursive: true});
-  fsSync.mkdirSync(tmpDir + '/jobs/failed', {recursive: true});
-  const savedDbDir = process.env.DB_DIR;
-  process.env.DB_DIR = tmpDir;
-  try {
-    const {getRequestability} = await import('./util.ts');
-    const result = await getRequestability('https://example.com/no-match');
-    assert.equal(result, '');
-  }
-  finally {
-    process.env.DB_DIR = savedDbDir;
-    fsSync.rmSync(tmpDir, {recursive: true});
-  }
-});
-
 test('isURL returns false for a malformed URL', () => {
   assert.equal(isURL('https://[invalid'), false);
 });
@@ -988,25 +1075,6 @@ test('testRequestsLock is a function (the lock returned by createLock)', () => {
   assert.equal(typeof testRequestsLock, 'function');
 });
 
-test('addTestRequest adds a request and returns success', async () => {
-  await fs.writeFile(testRequestsPath(), '{}\n');
-  const result = await addTestRequest('Test Page', 'https://example.com/test', 'because');
-  assert.equal(result.error, undefined);
-  const testRequests = JSON.parse(await fs.readFile(testRequestsPath(), 'utf8'));
-  assert.ok(testRequests['https://example.com/test']);
-  assert.equal(testRequests['https://example.com/test'].length, 1);
-  assert.equal(testRequests['https://example.com/test'][0].description, 'Test Page');
-  await fs.writeFile(testRequestsPath(), '{}\n');
-});
-
-test('addTestRequest returns a duplicate error for a repeated request', async () => {
-  await fs.writeFile(testRequestsPath(), '{}\n');
-  await addTestRequest('Test Page', 'https://example.com/test', 'because');
-  const result = await addTestRequest('Test Page', 'https://example.com/test', 'another reason');
-  assert.equal(result.error, 'duplicate');
-  await fs.writeFile(testRequestsPath(), '{}\n');
-});
-
 test('getReportPath returns the path of a report file', () => {
   const result = getReportPath('260101T0000', 'mix');
   assert.ok(result.endsWith('260101T0000-mix.json'));
@@ -1059,3 +1127,234 @@ test('getMultiReportWhats returns descriptions that have multiple reports', asyn
   const whats = await getMultiReportWhats();
   assert.ok(whats.includes('Mixed Outcomes Page'));
 });
+
+test('getExclusionCookieValue is deterministic for a given AUTH_CODE', async () => {
+  const savedAuthCode = process.env.AUTH_CODE;
+  process.env.AUTH_CODE = 'test-auth-code';
+  try {
+    const {getExclusionCookieValue} = await import('./util.ts');
+    const first = getExclusionCookieValue();
+    const second = getExclusionCookieValue();
+    assert.equal(first, second);
+    assert.equal(typeof first, 'string');
+    assert.ok(first.length > 0);
+  }
+  finally {
+    process.env.AUTH_CODE = savedAuthCode;
+  }
+});
+
+test('getExclusionCookieValue changes when AUTH_CODE changes', async () => {
+  const savedAuthCode = process.env.AUTH_CODE;
+  try {
+    const {getExclusionCookieValue} = await import('./util.ts');
+    process.env.AUTH_CODE = 'code-one';
+    const first = getExclusionCookieValue();
+    process.env.AUTH_CODE = 'code-two';
+    const second = getExclusionCookieValue();
+    assert.notEqual(first, second);
+  }
+  finally {
+    process.env.AUTH_CODE = savedAuthCode;
+  }
+});
+
+test('getExclusionCookieValue does not throw when AUTH_CODE is unset', async () => {
+  const savedAuthCode = process.env.AUTH_CODE;
+  delete process.env.AUTH_CODE;
+  try {
+    const {getExclusionCookieValue} = await import('./util.ts');
+    assert.equal(typeof getExclusionCookieValue(), 'string');
+  }
+  finally {
+    process.env.AUTH_CODE = savedAuthCode;
+  }
+});
+
+test('recordMetric creates the metrics file and records a first occurrence when the file is missing', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-missing-metrics-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('pageViews', 'tutorialWeb.html');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.pageViews['tutorialWeb.html'], 1);
+    assert.equal(metrics.mcpToolCalls['tutorialWeb.html'], undefined);
+    assert.equal(typeof metrics.since, 'string');
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric increments an existing count rather than overwriting it', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-existing-metrics-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('mcpToolCalls', 'listReports');
+    await recordMetric('mcpToolCalls', 'listReports');
+    await recordMetric('mcpToolCalls', 'getReport');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.mcpToolCalls.listReports, 2);
+    assert.equal(metrics.mcpToolCalls.getReport, 1);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric throws when the metrics file is not readable for a reason other than being missing', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-unreadable-test';
+  const fsSync = await import('node:fs');
+  // Create a directory where the metrics file should be, causing EISDIR rather than ENOENT.
+  fsSync.mkdirSync(tmpDir + '/metrics.json', {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric} = await import('./util.ts');
+    await assert.rejects(recordMetric('pageViews', 'tutorialWeb.html'), /not readable/);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric throws when the metrics file is not JSON', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-not-json-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  fsSync.writeFileSync(tmpDir + '/metrics.json', 'not json');
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric} = await import('./util.ts');
+    await assert.rejects(recordMetric('pageViews', 'tutorialWeb.html'), /not JSON/);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric keeps categories independent for the same name', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-categories-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('apiOperations', 'listReports');
+    await recordMetric('mcpToolCalls', 'listReports');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.apiOperations.listReports, 1);
+    assert.equal(metrics.mcpToolCalls.listReports, 1);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric tracks managerActivity outcomes separately per page', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-manager-activity-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('managerActivity', 'reannotate.html', 'ok');
+    await recordMetric('managerActivity', 'reannotate.html', 'error');
+    await recordMetric('managerActivity', 'reannotate.html', 'error');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.deepEqual(metrics.managerActivity['reannotate.html'], {ok: 1, error: 2});
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric keeps managerActivity independent of pageViews for the same name', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-manager-vs-pageviews-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('pageViews', 'hideReportForm.html');
+    await recordMetric('managerActivity', 'hideReportForm.html', 'ok');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.pageViews['hideReportForm.html'], 1);
+    assert.deepEqual(metrics.managerActivity['hideReportForm.html'], {ok: 1, error: 0});
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('getMetrics backfills categories missing from a metrics.json written before they existed', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-backfill-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  // Simulate a metrics.json written before the managerActivity category was added.
+  fsSync.writeFileSync(tmpDir + '/metrics.json', JSON.stringify({
+    since: '260101T0000',
+    pageViews: {listReports: 1},
+    mcpToolCalls: {},
+    apiOperations: {}
+  }));
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    // Recording a managerActivity outcome must not throw despite the file predating that category.
+    await recordMetric('managerActivity', 'metrics', 'ok');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.since, '260101T0000');
+    assert.equal(metrics.pageViews.listReports, 1);
+    assert.deepEqual(metrics.managerActivity.metrics, {ok: 1, error: 0});
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('getMetrics backfills every category, and generates a since stamp, from a bare empty file', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-backfill-empty-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  // Simulate a metrics.json with none of the known fields (an extreme case of an outdated schema).
+  fsSync.writeFileSync(tmpDir + '/metrics.json', '{}');
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('pageViews', 'tutorialWeb');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(typeof metrics.since, 'string');
+    assert.ok(metrics.since.length > 0);
+    assert.equal(metrics.pageViews.tutorialWeb, 1);
+    assert.deepEqual(metrics.mcpToolCalls, {});
+    assert.deepEqual(metrics.apiOperations, {});
+    assert.deepEqual(metrics.managerActivity, {});
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});