@jrpool/kilotest 55.0.0 → 57.1.0

package/mcp.test.ts

@@ -37,10 +37,10 @@ test('mcpPath is /mcp', () => {
   assert.equal(mcpPath, '/mcp');
 });
 
-test('createMCPServer registers all 9 tools', () => {
+test('createMCPServer registers all 12 tools', () => {
   const server = createMCPServer();
   const toolNames = Object.keys((server as any)._registeredTools);
-  assert.equal(toolNames.length, 9);
+  assert.equal(toolNames.length, 12);
   assert.deepEqual(toolNames, [
     'getKilotestOverview',
     'listReports',
@@ -48,9 +48,12 @@ test('createMCPServer registers all 9 tools', () => {
     'listViolators',
     'listDiagnoses',
     'getReport',
-    'requestTest',
+    'requestNewTest',
     'requestRetest',
-    'requestFeature'
+    'requestFeature',
+    'orderNewTest',
+    'orderRetest',
+    'awaitTest'
   ]);
 });
 
@@ -159,10 +162,10 @@ test('getReport handler returns content and structuredContent for a valid report
   assert.equal(getToolCallCount('getReport'), countBefore + 1);
 });
 
-test('requestTest handler returns content and structuredContent', async () => {
+test('requestNewTest handler returns content and structuredContent', async () => {
   const server = createMCPServer();
-  const countBefore = getToolCallCount('requestTest');
-  const result = await (server as any)._registeredTools.requestTest.handler({
+  const countBefore = getToolCallCount('requestNewTest');
+  const result = await (server as any)._registeredTools.requestNewTest.handler({
     description: 'Test Page',
     URL: 'https://example.com/test',
     reason: 'Because accessibility matters'
@@ -170,7 +173,7 @@ test('requestTest handler returns content and structuredContent', async () => {
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
-  assert.equal(getToolCallCount('requestTest'), countBefore + 1);
+  assert.equal(getToolCallCount('requestNewTest'), countBefore + 1);
 });
 
 test('requestRetest handler returns content and structuredContent for a valid report', async () => {
@@ -199,6 +202,60 @@ test('requestFeature handler returns content and structuredContent', async () =>
   assert.equal(getToolCallCount('requestFeature'), countBefore + 1);
 });
 
+test('orderNewTest handler returns content and structuredContent, and enqueues a job', async () => {
+  const {jobsPath} = await import('./util.ts');
+  const server = createMCPServer();
+  const countBefore = getToolCallCount('orderNewTest');
+  const result = await (server as any)._registeredTools.orderNewTest.handler({
+    description: 'MCP Ordered Page',
+    URL: 'https://example.com/mcp-ordered',
+    reason: 'Because accessibility matters here'
+  });
+  assert.ok(result.content);
+  assert.equal(result.content[0].type, 'text');
+  assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('orderNewTest'), countBefore + 1);
+  const reportIdentifier = result.structuredContent['response content']['disposition of your order']['report identifier'];
+  assert.ok(reportIdentifier);
+  const queuedPath = `${jobsPath()}/queue/${reportIdentifier.timeStamp}-${reportIdentifier.jobID}.json`;
+  fs.unlinkSync(queuedPath);
+});
+
+test('orderRetest handler returns content and structuredContent, and enqueues a job', async () => {
+  const {jobsPath} = await import('./util.ts');
+  const server = createMCPServer();
+  const countBefore = getToolCallCount('orderRetest');
+  // 260202T0000-new is the latest report of "Mixed Outcomes Page" (260101T0000-mix is an
+  // earlier, superseded report of the same page), so this order is accepted.
+  const result = await (server as any)._registeredTools.orderRetest.handler({
+    timeStamp: '260202T0000',
+    jobID: 'new',
+    reason: 'Because the report is obsolete'
+  });
+  assert.ok(result.content);
+  assert.equal(result.content[0].type, 'text');
+  assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('orderRetest'), countBefore + 1);
+  const reportIdentifier = result.structuredContent['response content']['disposition of your order']['report identifier'];
+  assert.ok(reportIdentifier);
+  const queuedPath = `${jobsPath()}/queue/${reportIdentifier.timeStamp}-${reportIdentifier.jobID}.json`;
+  fs.unlinkSync(queuedPath);
+});
+
+test('awaitTest handler returns content and structuredContent for an already-completed report', async () => {
+  const server = createMCPServer();
+  const countBefore = getToolCallCount('awaitTest');
+  const result = await (server as any)._registeredTools.awaitTest.handler({
+    timeStamp: '260101T0000',
+    jobID: 'mix'
+  });
+  assert.ok(result.content);
+  assert.equal(result.content[0].type, 'text');
+  assert.ok(result.structuredContent);
+  assert.equal(result.structuredContent['response content']['disposition of your wait'].outcome, 'completed');
+  assert.equal(getToolCallCount('awaitTest'), countBefore + 1);
+});
+
 test('listIssues handler returns an error for a nonexistent report', async () => {
   const server = createMCPServer();
   const result = await (server as any)._registeredTools.listIssues.handler({
@@ -301,7 +358,7 @@ test('handleMCP responds to initialize with server info', async () => {
   }
 });
 
-test('handleMCP lists all 9 tools via tools/list', async () => {
+test('handleMCP lists all 12 tools via tools/list', async () => {
   const server = await startMCPServer();
   try {
     const port = server.address().port;
@@ -309,7 +366,7 @@ test('handleMCP lists all 9 tools via tools/list', async () => {
     assert.equal(res.statusCode, 200);
     const result = parseSSEResult(res.body);
     const toolNames = result.result.tools.map((t: any) => t.name);
-    assert.equal(toolNames.length, 9);
+    assert.equal(toolNames.length, 12);
     assert.deepEqual(toolNames, [
       'getKilotestOverview',
       'listReports',
@@ -317,9 +374,12 @@ test('handleMCP lists all 9 tools via tools/list', async () => {
       'listViolators',
       'listDiagnoses',
       'getReport',
-      'requestTest',
+      'requestNewTest',
       'requestRetest',
-      'requestFeature'
+      'requestFeature',
+      'orderNewTest',
+      'orderRetest',
+      'awaitTest'
     ]);
   }
   finally {

package/mcp.ts

@@ -13,9 +13,12 @@ import * as listReportsAPI from './api/listReports.ts';
 import * as listIssuesAPI from './api/listIssues.ts';
 import * as listViolatorsAPI from './api/listViolators.ts';
 import * as listDiagnosesAPI from './api/listDiagnoses.ts';
-import * as requestTestAPI from './api/requestTest.ts';
+import * as requestNewTestAPI from './api/requestNewTest.ts';
 import * as requestRetestAPI from './api/requestRetest.ts';
 import * as requestFeatureAPI from './api/requestFeature.ts';
+import * as orderNewTestAPI from './api/orderNewTest.ts';
+import * as orderRetestAPI from './api/orderRetest.ts';
+import * as awaitTestAPI from './api/awaitTest.ts';
 import {version} from './api/version.ts';
 import {recordMetric} from './util.ts';
 
@@ -24,17 +27,23 @@ import {
   listIssuesSchema,
   listViolatorsSchema,
   listDiagnosesSchema,
-  requestTestSchema,
+  requestNewTestSchema,
   requestRetestSchema,
   requestFeatureSchema,
+  orderNewTestSchema,
+  orderRetestSchema,
+  awaitTestSchema,
   listReportsResponseSchema,
   listIssuesResponseSchema,
   listViolatorsResponseSchema,
   listDiagnosesResponseSchema,
   getReportResponseSchema,
-  requestTestResponseSchema,
+  requestNewTestResponseSchema,
   requestRetestResponseSchema,
-  requestFeatureResponseSchema
+  requestFeatureResponseSchema,
+  orderNewTestResponseSchema,
+  orderRetestResponseSchema,
+  awaitTestResponseSchema
 } from './api/schemas.ts';
 
 // CONSTANTS
@@ -53,7 +62,8 @@ const kilotestOverview = [
   'Kilotest tests web pages for front-end quality: accessibility, usability, and standards conformity.',
   'Kilotest integrates an ensemble of twelve independent rule engines to test a web page and stores the results as a structured report.',
   'Results are organized as a hierarchy. A report contains issues. An issue has violators: elements of the tested page reported as exhibiting the issue. A violator has diagnoses: explanations from rule engines of how the element exhibited the issue.',
-  'Typical workflow: call the listReports tool to learn whether a report about the page already exists. If it does, drill down with the listIssues, listViolators, and listDiagnoses tools, or retrieve the entire report with the getReport tool. If no report exists, request a test with the requestTest tool. If the latest report is obsolete, request a retest with the requestRetest tool.',
+  'Typical workflow: call the listReports tool to learn whether a report about the page already exists. If it does, drill down with the listIssues, listViolators, and listDiagnoses tools, or retrieve the entire report with the getReport tool. If no report exists, request a test with the requestNewTest tool. If the latest report is obsolete, request a retest with the requestRetest tool.',
+  'For immediate, automatically approved testing, use the orderNewTest tool (for a new page) or the orderRetest tool (for a page with an obsolete report) instead of requestNewTest or requestRetest. Each enqueues the job right away, with no manual approval step, and returns a report identifier along with a question about whether to wait for completion. To wait, call the awaitTest tool with that identifier; it blocks until the report is ready, the job fails, or a maximum wait time elapses. To check later instead, call the listIssues tool with the same identifier.',
   'More documentation is available at https://kilotest.com/llms.txt and https://kilotest.com/llms-full.txt.'
 ].join('\n\n');
 
@@ -71,7 +81,7 @@ export const createMCPServer = (): McpServer => {
     description: 'Tools that test web pages for front-end quality (accessibility, usability, and standards conformity) and make test results available'
   },
   {
-    instructions: `${sharedContext} Use the listReports tool to start. If it shows that there is a report available about the page you want facts about, drill down with the listIssues, listViolators, and listDiagnoses tools. If not, use the requestTest tool to request that the page be tested. If the latest report about the page is obsolete, use the requestRetest tool to request that the page be retested. For detailed documentation, call the getKilotestOverview tool.`
+    instructions: `${sharedContext} Use the listReports tool to start. If it shows that there is a report available about the page you want facts about, drill down with the listIssues, listViolators, and listDiagnoses tools. If not, use the requestNewTest tool to request that the page be tested, or the orderNewTest tool for immediate, automatically approved testing. If the latest report about the page is obsolete, use the requestRetest tool to request that the page be retested, or the orderRetest tool for immediate, automatically approved retesting. For detailed documentation, call the getKilotestOverview tool.`
   });
   server.registerTool(
     'getKilotestOverview',
@@ -192,11 +202,11 @@ export const createMCPServer = (): McpServer => {
     }
   );
   server.registerTool(
-    'requestTest',
+    'requestNewTest',
     {
       description: toolDoc('Process my request to test a page about which no report is available yet.'),
-      inputSchema: requestTestSchema,
-      outputSchema: requestTestResponseSchema,
+      inputSchema: requestNewTestSchema,
+      outputSchema: requestNewTestResponseSchema,
       annotations: {
         title: toolDoc('Process my request to test a page about which no report is available yet.'),
         readOnlyHint: false,
@@ -206,8 +216,8 @@ export const createMCPServer = (): McpServer => {
       }
     },
     async ({description, URL, reason}) => {
-      const result = await requestTestAPI.response([description, URL, reason]);
-      await recordMetric('mcpToolCalls', 'requestTest');
+      const result = await requestNewTestAPI.response([description, URL, reason]);
+      await recordMetric('mcpToolCalls', 'requestNewTest');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
@@ -251,6 +261,66 @@ export const createMCPServer = (): McpServer => {
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
+  server.registerTool(
+    'orderNewTest',
+    {
+      description: toolDoc('Process my order to test a page about which no report is available yet, immediately and automatically approved, instead of waiting for manual approval. Testing typically takes about 2 minutes and occasionally up to 4 minutes.'),
+      inputSchema: orderNewTestSchema,
+      outputSchema: orderNewTestResponseSchema,
+      annotations: {
+        title: toolDoc('Process my order to test a page about which no report is available yet, immediately and automatically approved.'),
+        readOnlyHint: false,
+        idempotentHint: false,
+        destructiveHint: false,
+        openWorldHint: false
+      }
+    },
+    async ({description, URL, reason}) => {
+      const result = await orderNewTestAPI.response([description, URL, reason]);
+      await recordMetric('mcpToolCalls', 'orderNewTest');
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
+    }
+  );
+  server.registerTool(
+    'orderRetest',
+    {
+      description: toolDoc('Process my order to retest a page immediately and automatically approved, instead of waiting for manual approval. Testing typically takes about 2 minutes and occasionally up to 4 minutes.'),
+      inputSchema: orderRetestSchema,
+      outputSchema: orderRetestResponseSchema,
+      annotations: {
+        title: toolDoc('Process my order to retest a page immediately and automatically approved.'),
+        readOnlyHint: false,
+        idempotentHint: false,
+        destructiveHint: false,
+        openWorldHint: false
+      }
+    },
+    async ({timeStamp, jobID, reason}) => {
+      const result = await orderRetestAPI.response([timeStamp, jobID, reason]);
+      await recordMetric('mcpToolCalls', 'orderRetest');
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
+    }
+  );
+  server.registerTool(
+    'awaitTest',
+    {
+      description: toolDoc('Wait for a job ordered via the orderNewTest or orderRetest tool to complete, using the report identifier either tool returned. Blocks until the report is ready, the job fails, or a maximum wait time elapses; sends no interim notices.'),
+      inputSchema: awaitTestSchema,
+      outputSchema: awaitTestResponseSchema,
+      annotations: {
+        title: toolDoc('Wait for a job ordered via the orderNewTest or orderRetest tool to complete.'),
+        readOnlyHint: true,
+        idempotentHint: false,
+        destructiveHint: false,
+        openWorldHint: false
+      }
+    },
+    async ({timeStamp, jobID}) => {
+      const result = await awaitTestAPI.response([timeStamp, jobID]);
+      await recordMetric('mcpToolCalls', 'awaitTest');
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
+    }
+  );
   server.registerResource(
     'kilotest-overview',
     'docs://kilotest/overview',

package/memory/MEMORY.md

@@ -5,3 +5,4 @@ This directory holds persistent context files for the Kilotest project. Each fil
 ## Index
 
 - [user_maintainer_context.md](user_maintainer_context.md) — user: Maintainer is 84 years old, sole contributor, prioritizes legibility for future maintainers over short-term velocity
+- [plan_issue_111_instant_test.md](plan_issue_111_instant_test.md) — project: orderTest/orderRetest/awaitTest (issue #111), implemented on orderTest branch with full REST+MCP parity

package/memory/plan_issue_111_instant_test.md

@@ -0,0 +1,198 @@
+---
+type: project
+name: Plan for issue #111 (instant testing)
+description: Design and implementation of orderTest/orderRetest/awaitTest, the three-tool MCP addition (with REST parity) for immediate, auto-approved testing with an optional wait for completion. Implemented on the orderTest branch.
+---
+
+# Issue #111: instant-testing MCP tools (implemented)
+
+Issue: [jrpool/kilotest#111](https://github.com/jrpool/kilotest/issues/111). The issue's own comment already
+narrowed scope to a minimal increment: keep the existing single-worker Testaro polling
+model, add new MCP tools, skip cost recovery, add only a lightweight anti-abuse gate.
+This was implemented on the `orderTest` branch as three tools, `orderTest`, `orderRetest`,
+and `awaitTest`, each with REST (`/api/*`) and MCP exposure, at the user's request for
+full parity with the existing `requestTest`/`requestRetest` tools.
+
+## Why two tools, not one
+
+MCP `tools/call` is one request, one response; a tool cannot pose a question mid-call
+and get an answer in the same call. The natural interaction is: order the test (fast,
+always returns quickly), then, as a genuinely separate second call, decide whether to
+wait for the result. Splitting into two tools avoids needing any new MCP machinery
+(progress tokens, progress notifications) to solve the timeout problem below.
+
+### The problem that killed the single-tool, blocking-wait design
+
+An earlier design considered one tool with a `waitForCompletion` flag, where a `true`
+call would enqueue and then block up to ~4 minutes for the report. This breaks if the
+MCP client times out client-side before Kilotest responds: the client has stopped
+listening, so nothing the server does (a final response, a progress notification) can
+reach it, unless the client supplied a `progressToken` up front and progress
+notifications were emitted early enough to carry the job identifier before the
+timeout hit. That makes the wait's safety depend on client capabilities the caller may
+not have, with no way for the server to detect or work around the gap.
+
+The fix is not "notify them anyway", it is: never let identifier delivery depend on a
+wait completing. `orderTest` returns immediately, always, with the identifier already
+in hand, before any wait is ever proposed. This makes the whole progress-token /
+client-timeout question moot for the ordering step; the identifier is guaranteed
+delivered before any risky wait begins.
+
+### Why a caller could never misuse awaitTest on a manually-approved job
+
+Considered and rejected: restricting `awaitTest` to jobs specifically created by
+`orderTest`, versus letting it work generically on any pending job by `timeStamp`/
+`jobID`. This turned out to be moot: `requestTest`/`requestRetest` never hand the
+caller a `timeStamp`/`jobID` at all (nothing exists yet), only instructions to poll
+`listReports` later by description/URL. An identifier for a report only becomes
+visible once the report is complete. So no caller can ever construct an `awaitTest`
+call naming a manually-approved, still-pending job; the scenario that would need a
+restriction cannot arise. No state-check or restriction is needed in `awaitTest`.
+`orderTest` is the only path that exposes a pre-completion identifier at all, because
+it enqueues synchronously and returns the job's own identifier immediately.
+
+## Implementation notes
+
+- `orderJob(target, reason)` in `util.ts` is the shared enqueue function backing both
+  `orderTest` (target `{description, url}`) and `orderRetest` (target `{timeStamp,
+  jobID}`), mirroring `processTestRequest`'s own dual-target design. It shares
+  `testRequestsLock` with `processTestRequest` so the two can never race to enqueue
+  duplicate jobs for the same page.
+- `awaitJob(timeStamp, jobID)` in `util.ts` is the shared poll function backing
+  `awaitTest`; it works for jobs from either `orderTest` or `orderRetest` (or, in
+  principle, any job in the queue/claimed pipeline), since it only inspects
+  `getJobNames()`/`getReportStats()`, not job origin. Poll interval and timeout are
+  injectable via `AWAIT_JOB_POLL_MS`/`AWAIT_JOB_TIMEOUT_MS` so tests do not need to
+  wait the real ~2-4 minutes.
+- Full REST+MCP parity: `api/routes.ts`, `index.ts`'s `/api/*` POST dispatch, and
+  `openapi.yaml` (regenerated via `npm run generate:openapi`) all cover the three new
+  operations, alongside the MCP tool registrations in `mcp.ts`. `smokeTest.ts` needed
+  no change, since it already smoke-tests the `/api/*` wildcard generically via one
+  representative path, not every individual operation.
+- Web-UI-equivalent URL fields (`'URLs of similar requests for web users'`) are `null`
+  for `orderTest`/`orderRetest`/`awaitTest`'s own request, per explicit instruction:
+  "web users will not be offered an order option." The *ancestor* request's web URL
+  (e.g. `listReports.html`, `listIssues.html`) is still populated where one exists.
+- `requestReferenceSchema` (`api/schemas.ts`) had to be widened from `method:
+  z.literal('GET')` to `z.enum(['GET', 'POST'])`, since `awaitTest`'s ancestors,
+  `orderTest`/`orderRetest`, are POSTs, unlike every other tool's GET ancestor.
+- **`awaitTest` has two possible ancestors, not one**: a bug in the first cut had
+  `awaitTest.ts` unconditionally naming `orderTest` as `'closest ancestor request'`,
+  wrong for any identifier that actually came from `orderRetest`, and `awaitTest`
+  cannot tell which one produced a given `timeStamp`/`jobID`, nor does it need to (its
+  poll logic is origin-agnostic, per the earlier finding above). Considered and
+  rejected: adding an `orderType: 'test' | 'retest'` parameter so `awaitTest` could
+  report a single correct ancestor; rejected because it would force every caller to
+  track and pass through a fact `awaitTest`'s own behavior never uses, reintroducing
+  exactly the origin-coupling the generic design deliberately avoided. Adopted instead:
+  `'closest ancestor request'` reports both `orderTest` and `orderRetest` as an array,
+  only for `awaitTest` (every other tool keeps a single nullable ancestor object).
+  Implemented by giving `thisRequestSchema`/`envelope` (`api/schemas.ts`) an optional
+  `ancestorSchema` override parameter, mirroring the existing `similarWebSchema`
+  override pattern, rather than widening the shared schema for every tool.
+- The caller's stated `reason` is persisted onto the job itself (`job.sources.reason`),
+  surviving into the eventual report exactly as `sources.worker` already does. No
+  approval rule consults it yet; the user's rationale for keeping the field even though
+  there is no human review is to accumulate real callers' stated reasons as data to
+  inform more sophisticated, reason-aware approval rules in a later iteration.
+- Shared response-shaping helpers landed in `api/util.ts`: `getRequestFailureReason`
+  and `buildRequestDisposition`, extracted from `requestTest.ts`/`requestRetest.ts`
+  (now refactored to use them) before `orderTest.ts`/`orderRetest.ts` were written
+  against the same helpers.
+
+## Tool 1: orderTest
+
+- Reuses `requestTest.ts`'s existing validation (length/URL/target-safety checks
+  already in top-level `util.ts`: `checkLength`, `isURL`, `isAllowedTarget`,
+  `isAllowedRedirectTarget`).
+- On success, enqueues directly into `db/jobs/queue` (bypassing the manual-approval
+  inbox `db/jobs/testRequests.json` entirely), following the job-template population
+  logic already in `web/enqueue/index.ts` (`jobName = ${nowStamp}-${jobIDSuffix}`,
+  etc.).
+- Approval gate (lightweight, per the issue's own comment, no human-in-the-loop):
+  - Queue-size cap: env var **`JOB_QUEUE_MAX`** (not "instant-test"-scoped; `db/jobs/queue`
+    is a shared resource fed by manual approvals, the web UI, and this tool, so the cap
+    name must not imply a per-source quota). Checked against the live count of
+    `db/jobs/queue` at call time via the existing `queuePath()` helper, not a
+    self-maintained counter. Parallels the existing `TEST_REQUEST_QUEUE_MAX` (which caps
+    the earlier-stage pending-approval inbox), as the sibling cap one stage further down
+    the same pipeline.
+  - Dedup against `queue`/`claimed`, reusing/extending `processTestRequest`'s existing
+    per-URL/description dedup logic.
+- Response, in all cases (accepted or rejected), returns immediately:
+  - If rejected: says why (queue full, duplicate), no identifier.
+  - If accepted: includes the job's `timeStamp`/`jobID` (or equivalent identifier),
+    states that testing has begun and the report will be available via `listIssues`
+    with those parameters, and asks the literal question: "Do you want to wait
+    (typically about 2 minutes, occasionally up to 4 minutes) and be notified of
+    completion?" The calling model decides and, if yes, makes a separate `awaitTest`
+    call.
+
+## Tool 2: awaitTest
+
+- Takes the identifier (`timeStamp`/`jobID`) `orderTest` returned.
+- Blocks, polling for report completion, until the report exists or a ~4-minute cap
+  elapses.
+- No progress notifications during the wait ("no notices until job completion or job
+  timeout", per explicit instruction). This is a pure bounded poll.
+- On completion or timeout, returns a response pointing at the same `listIssues`
+  parameters already given, so both outcomes converge on the same follow-up action.
+- Needs zero Testaro changes and zero MCP progress-notification plumbing: it derives
+  status purely from Kilotest's own already-tracked state (`db/jobs/claimed/` vs. a
+  completed report existing), not from any per-rule-engine signal.
+
+## Deferred: detailed (per-rule-engine) progress reporting
+
+Explicitly postponed; "the work is substantial even with generic progress reporting."
+Findings, kept for whenever this is revisited:
+
+- Testaro's `doActs.js` already has the needed hook, `opts.onProgress`, firing
+  `actStart`/`actEnd` per act (including per rule-engine `test` act, with `which`
+  naming the tool and `actEnd` carrying `outcome`/`elapsedMs`), built for Testaro's own
+  issue #44.
+- However, **no current Testaro entry point supplies `opts`**: `call.js`, `dirWatch.js`,
+  and `netWatch.js` (the one a Kilotest Testaro worker actually runs) all call
+  `doJob(job)` with a single argument. `opts.onProgress` is dead code from any shipped
+  Testaro CLI/watch surface today.
+- Consuming detailed progress therefore requires a **Testaro-side revision** to
+  `netWatch.js` (to accept/forward progress, plausibly keyed off a job property rather
+  than a runtime `opts` argument, since `netWatch.js`'s call site has no second argument
+  to attach a callback to) plus a **new worker-to-Kilotest channel** (the worker
+  currently only talks to Kilotest at claim-time and report-time; no mid-job channel
+  exists). This is real, separate scope: a Testaro release plus a worker deployment
+  update, before Kilotest's side could even be attempted. File as its own Testaro issue
+  when picked up, not bundled into this work.
+- Generic progress (this plan) needed none of this, since Kilotest already knows
+  claimed-vs-reported from its own state.
+
+## Tool 3: orderRetest
+
+Same shape as `orderTest`, but for retesting a page with an existing report: target is
+`{timeStamp, jobID}` of the report to retest, matching `requestRetest`'s own parameters.
+Added at the user's explicit request, alongside full REST/MCP parity, for symmetry with
+`orderTest`. Reuses the same `orderJob` function (see Implementation notes above) and the
+same `awaitTest` tool for waiting; no separate wait tool was needed.
+
+## Out of scope for this increment
+
+- Cost recovery (explicit in the issue's own comment).
+- Any change to the Testaro worker or its single-worker polling model.
+- Any human-approval step for `orderTest`/`orderRetest`-originated jobs.
+
+## Likely shared-code extraction
+
+`requestTest.ts` and `requestRetest.ts` already duplicate a failure-reason mapping
+(`requestResult` → human-readable string) and a `requestDisposition` envelope shape
+(`'what happens next'` / `'how you can check for completion'` / `'how a web user can
+check for completion'`). A third near-identical need in `orderTest.ts` makes this real
+duplication (three call sites), worth extracting into small helpers in `api/util.ts`
+before or alongside writing `orderTest.ts`. The outer response-body envelope
+(`'tool collection'`, `'this request'`, etc.) is NOT worth extracting further; it is
+already assembled from `getToolsFacts()`/`getResponseMetadata()` and the remaining
+per-tool differences (method, URL, body shape, ancestor request) are genuinely
+tool-specific.
+
+See also `user_maintainer_context` for the legibility-for-future-maintainers priority
+this design tries to respect (explicit state checks over implicit invariants, e.g. why
+`awaitTest` needed no special-casing once the actual constraint was understood, rather
+than adding a defensive check for a scenario that cannot occur).