@jrpool/kilotest 60.9.1 → 62.0.0

package/api/routes.test.ts

@@ -11,9 +11,9 @@ import {routes} from './routes.ts';
 
 // TESTS
 
-test('routes exports an array with 11 operations', () => {
+test('routes exports an array with 12 operations', () => {
   assert.ok(Array.isArray(routes));
-  assert.equal(routes.length, 11);
+  assert.equal(routes.length, 12);
 });
 
 test('routes includes all expected operation IDs', () => {
@@ -27,6 +27,7 @@ test('routes includes all expected operation IDs', () => {
     'listViolators',
     'orderNewTest',
     'orderRetest',
+    'reportDisagreement',
     'requestFeature',
     'requestNewTest',
     'requestRetest'

package/api/routes.ts

@@ -17,6 +17,7 @@ import {
   orderNewTestSchema,
   orderRetestSchema,
   awaitTestSchema,
+  reportDisagreementSchema,
   listPagesResponseSchema,
   listIssuesResponseSchema,
   listViolatorsResponseSchema,
@@ -27,7 +28,8 @@ import {
   requestFeatureResponseSchema,
   orderNewTestResponseSchema,
   orderRetestResponseSchema,
-  awaitTestResponseSchema
+  awaitTestResponseSchema,
+  reportDisagreementResponseSchema
 } from './schemas.ts';
 
 // ROUTES
@@ -99,6 +101,23 @@ export const routes = [
     bodySchema: z.object(requestFeatureSchema),
     responseSchema: requestFeatureResponseSchema
   },
+  {
+    operationId: 'reportDisagreement',
+    method: 'post',
+    path: '/api/reportDisagreement/{issueID}/{reportID}/{catalogIndex}',
+    summary: 'Report disagreement with a diagnosis',
+    pathParamsSchema: z.object({
+      issueID: reportDisagreementSchema.issueID,
+      reportID: reportDisagreementSchema.reportID,
+      catalogIndex: reportDisagreementSchema.catalogIndex
+    }),
+    bodySchema: z.object({
+      engineID: reportDisagreementSchema.engineID,
+      ruleID: reportDisagreementSchema.ruleID,
+      reason: reportDisagreementSchema.reason
+    }),
+    responseSchema: reportDisagreementResponseSchema
+  },
   {
     operationId: 'orderNewTest',
     method: 'post',

package/api/schemas.ts

@@ -73,6 +73,16 @@ export const awaitTestSchema = {
   reportID: z.string().describe('Report identifier returned by orderNewTest or orderRetest (example: 260503T0432-x9z)')
 };
 
+// reportDisagreement: POST /api/reportDisagreement/{issueID}/{reportID}/{catalogIndex}
+export const reportDisagreementSchema = {
+  issueID: z.string().describe('Issue identifier (example: contrastPoor)'),
+  reportID: z.string().describe('Identifier of the report (example: 260503T0432-x9z)'),
+  catalogIndex: z.string().describe('Identifier of the issue-exhibiting element in the catalog of elements on the page (example: 372)'),
+  engineID: z.string().describe('Identifier of the rule engine that produced the disputed diagnosis (example: axe), as shown in the listDiagnoses output'),
+  ruleID: z.string().describe('Identifier of the rule whose diagnosis is disputed, as shown in the listDiagnoses output (example: color-contrast); if that output shows null for the rule identifier, use its description of the violation instead'),
+  reason: z.string().describe('20- to 1000-character explanation of why the diagnosis is disputed')
+};
+
 // listPages takes no input; omitted (mcp.ts already uses inputSchema: {}).
 
 // RESPONSE SCHEMAS
@@ -195,12 +205,15 @@ const reportTimeSchema = z.object({
 });
 
 export const listPagesResponseSchema = envelope('GET', z.object({
+  'how to get test results about a page': z.object({
+    method: z.literal('GET'),
+    URL: z.string().describe('URL template; replace {identifier} with the identifier of the latest report about the page.')
+  }),
+  'web users can get test results about a page at': z.string().describe('URL template; replace {identifier} with the identifier of the latest report about the page.'),
   'basics about all tested pages': z.array(z.object({
-    'tested web page': z.object({description: z.string(), URL: z.string()}),
-    'number of reports about the page': z.number(),
-    'basics about the latest report': reportTimeSchema,
-    'how to get details about the latest report': z.object({method: z.literal('GET'), URL: z.string()}),
-    'web users can get details about the latest report at': z.string()
+    description: z.string(),
+    URL: z.string(),
+    identifier: z.string().describe('Identifier of the latest report about the page (example: 260503T0432-x9z).')
   })),
   'how to request that a page with no report be tested': z.object({
     method: z.literal('POST'),
@@ -275,7 +288,7 @@ export const listViolatorsResponseSchema = envelope('GET', z.object({
     'tag name': z.unknown().describe('Copied from the report catalog entry; type not guaranteed.'),
     'inner text': z.unknown().describe('Copied from the report catalog entry; type not guaranteed.'),
     'count of rule engines reporting that the element exhibited the issue': z.number(),
-    'how to get details about the element': z.object({URL: z.string(), 'request method': z.literal('GET')}),
+    'how to get details about the element': z.object({method: z.literal('GET'), URL: z.string()}),
     'web users can get details about the element at': z.string()
   })).nullable()
 }));
@@ -294,10 +307,20 @@ export const listDiagnosesResponseSchema = envelope('GET', z.object({
     'x, y, width, and height of bounding box': z.unknown().describe('Copied from the report catalog entry; type not guaranteed.')
   }).nullable(),
   'diagnoses of how the element exhibited the issue': z.array(z.object({
+    'identifier of the rule engine': z.unknown().describe('Copied from the report act (which); type not guaranteed.'),
     'identifier of the violated rule': z.unknown().describe('Copied from the report instance (ruleID); type not guaranteed.'),
     'description of the violation': z.unknown().describe('Copied from the report instance (what); type not guaranteed.'),
     'severity of the violation on a 0-to-3 scale': z.unknown().describe('Copied from the report instance (ordinalSeverity); type not guaranteed.'),
-    'count of violations of the rule by the element': z.number()
+    'count of violations of the rule by the element': z.number(),
+    'how to report that you disagree with this diagnosis': z.object({
+      method: z.literal('POST'),
+      URL: z.string(),
+      'request body': z.object({
+        engineID: z.string(),
+        ruleID: z.string(),
+        reason: z.string()
+      })
+    })
   })).or(z.object({error: z.string()})).nullable()
 }));
 
@@ -359,6 +382,28 @@ export const requestFeatureResponseSchema = envelope(
   z.null()
 );
 
+export const reportDisagreementResponseSchema = envelope(
+  'POST',
+  z.object({'details about your request': z.union([
+    z.object({error: z.string()}),
+    z.object({
+      'date and time received': z.string(),
+      'diagnosis you disagree with': z.object({
+        'issue identifier': z.string(),
+        'identifier of the rule engine': z.string(),
+        'identifier of the violated rule': z.string()
+      }),
+      disposition: z.string()
+    })
+  ])}),
+  z.object({
+    engineID: reportDisagreementSchema.engineID,
+    ruleID: reportDisagreementSchema.ruleID,
+    reason: reportDisagreementSchema.reason
+  }),
+  z.null()
+);
+
 // Identifies the report a successfully ordered or awaited job will produce, once complete.
 const reportIdentifierSchema = z.string().describe('Identifier of the report, to pass to listIssues once the report is ready (example: 260503T0432-x9z).');
 

package/api/util.ts

@@ -51,18 +51,20 @@ export const getResponseMetadata = () => ({
 export const getToolsFacts = () => ({
   'name': 'Kilotest',
   'description': {
-    'what Kilotest does': 'Kilotest tools generate and make available findings about the front-end quality (i.e. accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG) of web pages. A Kilotest job generates findings by using Testaro to test a page against about 1300 rules defined by an ensemble of twelve rule engines. Testaro produces a report of the job. The report describes violations of the rules. Kilotest uses Testilo to enhance the report with a classification of the rule violations into about 380 issues. Kilotest makes facts about the tested pages, the issues, and the violations retrievable at four levels of granularity.',
+    'what Kilotest does': 'Kilotest tools generate findings about the front-end quality (i.e. accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG of W3C) of web pages. A Kilotest job generates findings by using Testaro to test a page against about 1300 rules defined by an ensemble of twelve rule engines. Testaro produces a report of the job. The report describes violations of the rules. Kilotest uses Testilo to enhance the report with a classification of the rule violations into about 380 issues and then saves the report for public retrieval. Kilotest makes facts about the tested pages, the issues, and the violations retrievable at four levels of granularity.',
     'how to retrieve findings': {
-      'level 1': 'Use the listPages tool to get a list of tested pages, each with its latest report. The listIssues output about any report lists all reports about the same page.',
-      'level 2': 'Use the listIssues tool to get a list of issues in one report.',
-      'level 3': 'Use the listViolators tool to get a list of elements on one page that were reported in one report as exhibiting one issue.',
+      'level 1': 'Use the listPages tool to get a list of tested pages, each with the identifier of its latest report, for use with the listIssues tool.',
+      'level 2': 'Use the listIssues tool to get a list of issues in one report, each with a link to the level-3 results for that issue. The response also includes a history of reports about the page, each with a link to its own level-2 results.',
+      'level 3': 'Use the listViolators tool to get a list of elements on one page that were reported in one report as exhibiting one issue, each with a link to the level-4 results for that violator.',
       'level 4': 'Use the listDiagnoses tool to get a list of diagnoses of how one element on one page exhibited one issue in one report.',
     },
     'how to generate more findings': {
-      'new testing': 'If no report is available yet about a page, use the requestNewTest tool to request that it be tested.',
-      'retesting': 'If the listIssues tool shows that the latest report about a page is obsolete, because the page has been revised or for another reason, use the requestRetest tool to request that the page be retested.',
-      'latency': 'Requests for testing and retesting are usually approved and fulfilled within one day.',
-      'confirmation': 'Use the listPages tool to determine whether a requested new report exists. There is currently no process for notification of the outcome of requests.'
+      'new testing': 'If no report is available yet about a page, use the requestNewTest tool to request that it be tested, or the orderNewTest tool for immediate testing.',
+      'retesting': 'If you believe that the latest report about a page is obsolete (e.g., because the page has been revised), use the requestRetest tool to request that the page be retested, or the orderRetest tool for immediate retesting.',
+      'approval': 'Requests are manager-reviewed, usually in 1 hour to one day. Orders are automatically reviewed. Reviews result in approval or rejection.',
+      'latency': 'An approved test typically finishes in 2 to 4 minutes.',
+      'request confirmation': 'After submitting a request and waiting for manager review, you can use the listPages tool to determine whether the request has been fulfilled: a new-test request adds a page entry linking to its results, and a retest request adds a later report about the page.',
+      'order confirmation': 'After ordering a test or retest, you will receive a rejection or a report identifier, which you can use to call the awaitTest tool. That tool blocks until the test completes, fails, or a maximum wait time elapses, and then returns the outcome. If you do not call awaitTest, you can wait 2 to 4 minutes and then, if the test is complete, the listIssues tool called with the report identifier will succeed.'
     }
   },
   'URL': `${getThisHost()}/mcp`,

package/apiIntegration.test.ts

@@ -16,11 +16,13 @@ import {requestHandler} from './index.ts';
 
 const port = 3998;
 const featureRequestsPath = path.join(import.meta.dirname, 'test/fixtures/apiIntegration/featureRequests.json');
+const disagreementsPath = path.join(import.meta.dirname, 'test/fixtures/apiIntegration/disagreements.json');
 
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;
 const savedFeatureRequestsPath = process.env.FEATURE_REQUESTS_PATH;
+const savedDisagreementsPath = process.env.DISAGREEMENTS_PATH;
 let server: http.Server;
 
 before(async () => {
@@ -31,6 +33,9 @@ before(async () => {
   process.env.FEATURE_REQUESTS_PATH = featureRequestsPath;
   await fs.mkdir(path.dirname(featureRequestsPath), {recursive: true});
   await fs.writeFile(featureRequestsPath, '[]\n');
+  // The same for diagnosis disagreements.
+  process.env.DISAGREEMENTS_PATH = disagreementsPath;
+  await fs.writeFile(disagreementsPath, '[]\n');
   server = http.createServer(requestHandler);
   await new Promise<void>(resolve => server.listen(port, () => resolve()));
 });
@@ -48,6 +53,12 @@ after(async () => {
   else {
     delete process.env.FEATURE_REQUESTS_PATH;
   }
+  if (savedDisagreementsPath !== undefined) {
+    process.env.DISAGREEMENTS_PATH = savedDisagreementsPath;
+  }
+  else {
+    delete process.env.DISAGREEMENTS_PATH;
+  }
   await fs.rm(path.dirname(featureRequestsPath), {recursive: true, force: true});
   server.closeAllConnections?.();
   await new Promise<void>(resolve => {
@@ -106,3 +117,14 @@ test('POST /api/requestFeature parses a JSON body and returns a JSON response th
   assert.equal(details.error, undefined);
   assert.equal(details.disposition, 'received and logged; manager notified');
 });
+
+test('POST /api/reportDisagreement parses path parameters and a JSON body and returns a JSON response through the HTTP routing layer', async () => {
+  const {body} = await request('POST', '/api/reportDisagreement/linkNoText/260101T0000-mix/0', {
+    engineID: 'axe',
+    ruleID: 'r11',
+    reason: 'The element does have an accessible name'
+  });
+  const details = body['response content']['details about your request'];
+  assert.equal(details.error, undefined);
+  assert.equal(details.disposition, 'received and logged; manager notified');
+});

package/docs/SERVICE.md

@@ -409,9 +409,11 @@ Alerts are sent to the maintainer in the following conditions:
 
 7. **MCP feature request received**: When a user submits a feature request via the MCP server's `requestFeature` tool, an alert is sent with subject `"MCP feature request received"`, including the text of the feature request, and the request is also appended to `db/featureRequests.json`, the same way tutorial comments are appended to their own files (see item 1), so that a manager can review or delete it later via `/deleteNotesForm.html`.
 
-8. **WAVE balance low**: When Kilotest detects that the account balance for the WAVE API service (used for accessibility testing) has fallen below a threshold, an alert is sent with subject `"Kilotest: WAVE balance low"`, indicating the number of credits remaining.
+8. **Diagnosis disagreement received**: When a user reports disagreement with a diagnosis via the API’s or MCP server’s `reportDisagreement` operation, an alert is sent with subject `"Kilotest: diagnosis disagreement received"`, including the reason, the disputed diagnosis (rule engine, rule, issue, element, and report), and the disagreement is also appended to `db/disagreements.json`, so that a manager can review it and, when warranted, propose a correction to the `testaro-issues` classification (see item 3 for how such corrections take effect).
 
-9. **AI service balance low**: When Kilotest detects that the account balance for an AI service account (such as Anthropic) has fallen below a threshold, an alert is sent with subject `"Kilotest: AI service [N] balance low"`, indicating the approximate remaining balance in dollars and the estimated cost per job.
+9. **WAVE balance low**: When Kilotest detects that the account balance for the WAVE API service (used for accessibility testing) has fallen below a threshold, an alert is sent with subject `"Kilotest: WAVE balance low"`, indicating the number of credits remaining.
+
+10. **AI service balance low**: When Kilotest detects that the account balance for an AI service account (such as Anthropic) has fallen below a threshold, an alert is sent with subject `"Kilotest: AI service [N] balance low"`, indicating the approximate remaining balance in dollars and the estimated cost per job.
 
 ### Alert configuration
 
@@ -427,7 +429,7 @@ If any of these five variables is missing or empty at alert time, the alert is n
 
 ### Inbox size limits
 
-Four submission types (test requests and retest requests together, web tutorial comments, AI tutorial comments, and MCP feature requests) are each held in a pending "inbox" (`db/jobs/testRequests.json`, `db/comments/tutorialWeb.json`, `db/comments/tutorialAI.json`, and `db/featureRequests.json` respectively) awaiting manual review by the maintainer. Each inbox has a maximum size; once reached, a new, distinct submission is rejected (with a message suggesting the requester instead post to the [GitHub issues page](https://github.com/jrpool/kilotest/issues) or email `info@kilotest.com`) rather than added, so neither the inbox file nor the manager alert emails it generates can grow without bound (see GitHub issue #3, abuse type 3, repeated/automated submissions). This is modeled on a full mailbox rejecting new mail, rather than on a submission rate limit: it is the backlog size itself, not how quickly it grows, that costs the maintainer review time and risks unbounded storage. Every alert sent for an accepted submission reports the resulting inbox count against its cap, so a maintainer returning after an absence can immediately see how close an inbox is to full.
+Five submission types (test requests and retest requests together, web tutorial comments, AI tutorial comments, MCP feature requests, and diagnosis disagreements) are each held in a pending "inbox" (`db/jobs/testRequests.json`, `db/comments/tutorialWeb.json`, `db/comments/tutorialAI.json`, `db/featureRequests.json`, and `db/disagreements.json` respectively) awaiting manual review by the maintainer. Each inbox has a maximum size; once reached, a new, distinct submission is rejected (with a message suggesting the requester instead post to the [GitHub issues page](https://github.com/jrpool/kilotest/issues) or email `info@kilotest.com`) rather than added, so neither the inbox file nor the manager alert emails it generates can grow without bound (see GitHub issue #3, abuse type 3, repeated/automated submissions). This is modeled on a full mailbox rejecting new mail, rather than on a submission rate limit: it is the backlog size itself, not how quickly it grows, that costs the maintainer review time and risks unbounded storage. Every alert sent for an accepted submission reports the resulting inbox count against its cap, so a maintainer returning after an absence can immediately see how close an inbox is to full.
 
 Each cap defaults to 20 and can be set independently via an environment variable:
 
@@ -435,6 +437,7 @@ Each cap defaults to 20 and can be set independently via an environment variable
 2. **`TUTORIAL_WEB_COMMENTS_MAX`**: The maximum number of comments held on the web tutorial page (`/tutorialWeb.html`).
 3. **`TUTORIAL_AI_COMMENTS_MAX`**: The maximum number of comments held on the AI agent tutorial page (`/tutorialAI.html`).
 4. **`FEATURE_REQUESTS_MAX`**: The maximum number of feature requests held via the MCP server's `requestFeature` tool.
+5. **`DISAGREEMENTS_MAX`**: The maximum number of disagreements with diagnoses held via the API’s or MCP server’s `reportDisagreement` operation.
 
 Each variable, if set, must be a non-negative integer; if unset, empty, or not a non-negative integer, the default of 20 is used instead. A value of `0` means no limit: that inbox is never treated as full, regardless of size. Unlike the alert-configuration variables above, these are not required: an unset value never disables the limit, it only selects the default size.
 

package/env.example

@@ -35,6 +35,8 @@ TUTORIAL_WEB_COMMENTS_PATH=__placeholder__
 TUTORIAL_AI_COMMENTS_PATH=__placeholder__
 # Path of the feature requests file (defaults to db/featureRequests.json).
 FEATURE_REQUESTS_PATH=__placeholder__
+# Path of the diagnosis disagreements file (defaults to db/disagreements.json).
+DISAGREEMENTS_PATH=__placeholder__
 
 # Inbox size limits: each defaults to 20 if unset, empty, or not a non-negative integer.
 # A value of 0 means no limit.
@@ -47,6 +49,9 @@ TUTORIAL_WEB_COMMENTS_MAX=__placeholder__
 TUTORIAL_AI_COMMENTS_MAX=__placeholder__
 # Maximum number of feature requests held via the MCP server's requestFeature tool.
 FEATURE_REQUESTS_MAX=__placeholder__
+# Maximum number of disagreements with diagnoses held via the MCP server's
+# reportDisagreement tool.
+DISAGREEMENTS_MAX=__placeholder__
 # Maximum number of jobs allowed in the job queue (db/jobs/queue) at once. Shared by every
 # path that enqueues a job: manager approval of a pending test/retest request, and the
 # orderNewTest/orderRetest MCP tools, which enqueue directly.

package/index.test.ts

@@ -981,12 +981,12 @@ test('GET /qai/comments redirects to /tutorialAI.html', async () => {
   assert.equal(res.headers['location'], '/tutorialAI.html');
 });
 
-test('GET /diagnoses.html/<segments> redirects to the equivalent /listDiagnoses.html/<segments>, preserving the query string', async () => {
+test('GET /diagnoses.html/<issueID>/<timeStamp>/<jobID>/<catalogIndex> with a query string redirects in one step to the canonical /listDiagnoses.html URL', async () => {
   const res = await request(
-    'GET', '/diagnoses.html/duplicateID/260426T1741-77w/718?pathID=/html/body', {}, {followRedirects: false}
+    'GET', '/diagnoses.html/linkNoText/260101T0000/mix/0?pathID=/html/body', {}, {followRedirects: false}
   );
   assert.equal(res.statusCode, 301);
-  assert.equal(res.headers['location'], '/listDiagnoses.html/duplicateID/260426T1741-77w/718?pathID=/html/body');
+  assert.equal(res.headers['location'], '/listDiagnoses.html/linkNoText/260101T0000-mix/0');
 });
 
 test('GET /reportIssues.html/<reportID> redirects to the equivalent /listIssues.html/<reportID>', async () => {
@@ -1015,12 +1015,12 @@ test('GET /listViolators.html/<issueID>/<timeStamp>/<jobID> redirects to the sin
   assert.equal(res.headers['location'], '/listViolators.html/linkNoText/260101T0000-mix');
 });
 
-test('GET /listDiagnoses.html/<issueID>/<timeStamp>/<jobID>/<catalogIndex> redirects to the single-reportID URL, preserving the query string', async () => {
+test('GET /listDiagnoses.html/<issueID>/<timeStamp>/<jobID>/<catalogIndex> with a query string redirects in one step to the canonical single-reportID URL', async () => {
   const res = await request(
     'GET', '/listDiagnoses.html/linkNoText/260101T0000/mix/0?pathID=/html/body', {}, {followRedirects: false}
   );
   assert.equal(res.statusCode, 301);
-  assert.equal(res.headers['location'], '/listDiagnoses.html/linkNoText/260101T0000-mix/0?pathID=/html/body');
+  assert.equal(res.headers['location'], '/listDiagnoses.html/linkNoText/260101T0000-mix/0');
 });
 
 test('GET /requestRetestForm.html/<timeStamp>/<jobID> redirects to the single-reportID URL', async () => {
@@ -1077,6 +1077,33 @@ test('GET /api/listReports redirects to /api/listPages', async () => {
   assert.equal(res.headers['location'], '/api/listPages');
 });
 
+// TESTS: query-string canonicalization
+// No GET page handler reads the query string, so a request with a query returns a
+// duplicate of the queryless page. These verify that such requests permanently
+// redirect to the queryless URL.
+
+test('GET /listDiagnoses.html/<segments> with a query string redirects to the queryless URL', async () => {
+  const res = await request(
+    'GET', '/listDiagnoses.html/linkNoText/260101T0000-mix/0?pathID=/html/body', {}, {followRedirects: false}
+  );
+  assert.equal(res.statusCode, 301);
+  assert.equal(res.headers['location'], '/listDiagnoses.html/linkNoText/260101T0000-mix/0');
+});
+
+test('GET /listIssues.html/<reportID> with a query string redirects to the queryless URL', async () => {
+  const res = await request(
+    'GET', '/listIssues.html/260101T0000-mix?foo=bar', {}, {followRedirects: false}
+  );
+  assert.equal(res.statusCode, 301);
+  assert.equal(res.headers['location'], '/listIssues.html/260101T0000-mix');
+});
+
+test('GET / with a query string redirects to /', async () => {
+  const res = await request('GET', '/?utm_source=example', {}, {followRedirects: false});
+  assert.equal(res.statusCode, 301);
+  assert.equal(res.headers['location'], '/');
+});
+
 test('GET /requestTest.html redirects to /requestNewTest.html', async () => {
   const res = await request('GET', '/requestTest.html', {}, {followRedirects: false});
   assert.equal(res.statusCode, 301);
@@ -1647,12 +1674,15 @@ test('POST /metrics.html with a valid authCode sets a metrics-exclusion cookie',
   assert.ok(setCookie.includes('HttpOnly'));
 });
 
-test('GET /metrics.html with a valid authCode in the query string does not set a cookie or show the counts', async () => {
+test('GET /metrics.html with a valid authCode in the query string redirects to the queryless URL, which does not set a cookie or show the counts', async () => {
   const res = await request('GET', '/metrics.html?authCode=test-auth-code');
-  assert.equal(res.statusCode, 200);
-  assert.equal(res.headers['set-cookie'], undefined);
-  assert.ok(res.body.includes('Authorization code'));
-  assert.ok(!res.body.includes('Web page views'));
+  assert.equal(res.statusCode, 301);
+  assert.equal(res.headers['location'], '/metrics.html');
+  const redirected = await request('GET', res.headers['location']);
+  assert.equal(redirected.statusCode, 200);
+  assert.equal(redirected.headers['set-cookie'], undefined);
+  assert.ok(redirected.body.includes('Authorization code'));
+  assert.ok(!redirected.body.includes('Web page views'));
 });
 
 test('a request carrying the metrics-exclusion cookie does not record a pageViews or apiOperations metric', async () => {

package/index.ts

@@ -88,6 +88,7 @@ import {response as requestNewTestAPI} from './api/requestNewTest.ts';
 import {response as orderNewTestAPI} from './api/orderNewTest.ts';
 import {response as orderRetestAPI} from './api/orderRetest.ts';
 import {response as awaitTestAPI} from './api/awaitTest.ts';
+import {response as reportDisagreementAPI} from './api/reportDisagreement.ts';
 
 // ENVIRONMENT
 
@@ -190,6 +191,7 @@ const apiRespond: {
   orderNewTest: ApiResponder;
   orderRetest: ApiResponder;
   awaitTest: ApiResponder;
+  reportDisagreement: ApiResponder;
 } = {
   getReport: getReportAPI,
   listDiagnoses: listDiagnosesAPI,
@@ -201,7 +203,8 @@ const apiRespond: {
   requestNewTest: requestNewTestAPI,
   orderNewTest: orderNewTestAPI,
   orderRetest: orderRetestAPI,
-  awaitTest: awaitTestAPI
+  awaitTest: awaitTestAPI,
+  reportDisagreement: reportDisagreementAPI
 };
 
 // CONSTANTS
@@ -347,9 +350,10 @@ export const isPathAllowed = (method: string, pathname: string): boolean => {
   const patterns = (routes as Record<string, string[]>)[method] || [];
   return patterns.some(pattern => matchPath(pattern, pathname));
 };
-// Returns the single-reportID URL that a legacy two-segment report URL (one whose
-// path tail identifies a report with separate timeStamp and jobID segments)
-// redirects to, or null if the page has no legacy form or the tail lacks its shape.
+// Returns the single-reportID path that a legacy two-segment report path tail (one
+// identifying a report with separate timeStamp and jobID segments) canonicalizes to
+// for a page under its current name, or null if the page has no legacy form or the
+// tail lacks its shape.
 const getLegacyReportURL = (topic: string, pathTail: string): string | null => {
   const legacy = legacyReportTails[topic];
   if (!legacy) {
@@ -681,12 +685,21 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
     }
     // Otherwise, if it is for the home page:
     else if (['/', '/index.html'].includes(pathname)) {
-      await recordPageMetric('pageViews', 'index');
-      // Get the home page.
-      const {answerPage} = await home();
-      // Serve it.
-      setHeaders('text/html', '/index.html', 'medium');
-      response.end(answerPage);
+      // If the URL has a query string, redirect the request permanently to the
+      // queryless URL (see the same redirect for .html pages below).
+      if (search) {
+        response.writeHead(301, {Location: pathname});
+        response.end();
+      }
+      // Otherwise, i.e. if the URL has no query string:
+      else {
+        await recordPageMetric('pageViews', 'index');
+        // Get the home page.
+        const {answerPage} = await home();
+        // Serve it.
+        setHeaders('text/html', '/index.html', 'medium');
+        response.end(answerPage);
+      }
     }
     // Otherwise, if it is for the crawler specification:
     else if (pageName === 'robots.txt') {
@@ -766,18 +779,15 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
         // If this failed:
         if (isReportError(report)) {
           // This is not necessarily abuse: the link may have been generated (e.g. by
-          // listIssues.html) before the report was pruned or rewound, or the stored report
-          // may have become unreadable or unusable, none of which is the requester's fault.
-          // So tell the requester only that the request was invalid, without accusing them,
-          // but alert a manager with the real reason, since a syntactically valid report ID
-          // should otherwise always be usable.
+          // listIssues.html) before the report was pruned or rewound, or the identifier
+          // may have been scraped from the API documentation's examples, none of which
+          // is the requester's fault. So tell the requester only that the request was
+          // invalid, without accusing them. No manager alert is sent: a missing report
+          // is a routine miss, and a report that exists but is unreadable or unusable
+          // has already been quarantined and alerted on by getReport.
           console.error(
             `Full report ${pathTail} requested but unavailable (${report.error})`
           );
-          await sendAlert(
-            'Kilotest: requested full report unavailable',
-            `Full report ${pathTail} was requested but could not be retrieved: ${report.error}`
-          );
           await serveError({message: 'ERROR: Invalid request'}, response, true);
         }
         // Otherwise, i.e. if it succeeded:
@@ -800,20 +810,24 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
     // Otherwise, if it is for an HTML page other than the home page:
     else if (pageName.endsWith('.html')) {
       const topic = pageName.slice(0, -5);
-      const legacyReportURL = getLegacyReportURL(topic, pathTail);
-      // If it is for a page's old, pre-rename name:
-      if (renamedPagePrefixes[topic]) {
-        // Redirect the client permanently to the current page name, preserving any
-        // further path segments and the query string.
-        const newLocation = `/${renamedPagePrefixes[topic]}.html${pathTail ? `/${pathTail}` : ''}${search}`;
-        response.writeHead(301, {Location: newLocation});
-        response.end();
-      }
-      // Otherwise, if the URL identifies a report with the legacy two-segment form
-      // (a timeStamp segment and a jobID segment), redirect the request permanently
-      // to the URL with the single reportID segment, preserving the query string.
-      else if (legacyReportURL !== null) {
-        response.writeHead(301, {Location: `${legacyReportURL}${search}`});
+      // Compute the path in the current request signature: the current name if the
+      // page name is a pre-rename one, and the single-reportID tail if the tail
+      // identifies a report with the legacy two-segment form (a timeStamp segment
+      // and a jobID segment).
+      const canonicalTopic = renamedPagePrefixes[topic] ?? topic;
+      const canonicalPath = getLegacyReportURL(canonicalTopic, pathTail) ??
+        `/${canonicalTopic}.html${pathTail ? `/${pathTail}` : ''}`;
+      // If the request signature contains any obsolete element (a pre-rename page
+      // name, a legacy two-segment report tail, or a query string, which no GET
+      // page handler reads, since the search argument passed to answer() is
+      // consumed only for POST requests, where it is reconstructed from the
+      // request body), convert all of them at once by redirecting the request
+      // permanently to the canonical path with no query string. A request with a
+      // query otherwise returns a byte-identical duplicate of the queryless page,
+      // which search engines report as a duplicate without a user-selected
+      // canonical (e.g. the pathID queries still requested on listDiagnoses URLs).
+      if (canonicalPath !== pathname || search) {
+        response.writeHead(301, {Location: canonicalPath});
         response.end();
       }
       // Otherwise, if the page can be generated and is not POST-only (a POST-only path also matches
@@ -1385,6 +1399,16 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
           setHeaders('application/json', null, 'ultra');
           response.end(JSON.stringify(responseBody));
         }
+        // Otherwise, if the service is to receive a disagreement with a diagnosis:
+        else if (segments[0] === 'reportDisagreement') {
+          const {engineID, ruleID, reason} = postData as {engineID: string; ruleID: string; reason: string};
+          // Get the response body.
+          const responseBody = await apiRespond.reportDisagreement(segments.slice(1).concat(engineID, ruleID, reason));
+          await recordPageMetric('apiOperations', 'reportDisagreement');
+          // Send it.
+          setHeaders('application/json', null, 'ultra');
+          response.end(JSON.stringify(responseBody));
+        }
         // Otherwise, if the service is to order an immediate, automatically approved test:
         else if (segments[0] === 'orderNewTest') {
           const {description, URL, reason} = postData as {description: string; URL: string; reason: string};