feat(test): make "test wait" variadic — attach to several runs in one invocation (#178)

* feat(test): make "test wait" variadic — attach to several runs in one invocation

* fix(wait): honor the shared deadline for queued members and hint only resumable runs

Author: Andy00L

src/commands/test.test.ts

@@ -36,6 +36,7 @@ import {
   runPlanPut,
   runResult,
   runSteps,
+  runTestWaitMany,
   runUpdate,
 } from './test.js';
 
@@ -3042,6 +3043,160 @@ describe('runLint', () => {
   });
 });
 
+describe('runTestWaitMany', () => {
+  const terminalRun = (runId: string, status: string) => ({
+    runId,
+    testId: `test_of_${runId}`,
+    projectId: 'project_alice',
+    userId: 'u1',
+    status,
+    source: 'cli',
+    createdAt: '2026-06-01T10:00:00.000Z',
+    startedAt: '2026-06-01T10:00:01.000Z',
+    finishedAt: '2026-06-01T10:00:30.000Z',
+    codeVersion: 'v1',
+    targetUrl: 'https://example.com',
+    createdFrom: null,
+    failedStepIndex: null,
+    failureKind: null,
+    error: null,
+    videoUrl: null,
+    stepSummary: { total: 1, completed: 1, passedCount: 1, failedCount: 0 },
+  });
+
+  it('polls every run, keeps input order, and exits 1 when one finished non-passed', async () => {
+    const { credentialsPath } = makeCreds();
+    const fetchImpl = makeFetch(url => ({
+      body: url.includes('run_bad')
+        ? terminalRun('run_bad', 'failed')
+        : terminalRun('run_ok', 'passed'),
+    }));
+    const out: string[] = [];
+    const rejection = await runTestWaitMany(
+      {
+        profile: 'default',
+        output: 'json',
+        debug: false,
+        runIds: ['run_ok', 'run_bad'],
+        timeoutSeconds: 30,
+        maxConcurrency: 2,
+      },
+      { credentialsPath, fetchImpl, stdout: line => out.push(line) },
+    ).catch((error: unknown) => error);
+    expect(rejection).toMatchObject({ exitCode: 1 });
+    const payload = JSON.parse(out.join('')) as {
+      results: Array<{ runId: string; status: string }>;
+      summary: { passed: number; failed: number };
+    };
+    expect(payload.results.map(row => row.runId)).toEqual(['run_ok', 'run_bad']);
+    expect(payload.summary).toMatchObject({ passed: 1, failed: 1 });
+  });
+
+  it('a member whose poll errors is captured as error:<CODE> and the others survive (exit 7)', async () => {
+    const { credentialsPath } = makeCreds();
+    const fetchImpl = makeFetch(url => {
+      if (url.includes('run_gone')) {
+        return {
+          status: 404,
+          body: {
+            error: {
+              code: 'NOT_FOUND',
+              message: 'no such run',
+              nextAction: 'check the id',
+              requestId: 'req_x',
+              details: {},
+            },
+          },
+        };
+      }
+      return { body: terminalRun('run_ok', 'passed') };
+    });
+    const out: string[] = [];
+    const errs: string[] = [];
+    const rejection = await runTestWaitMany(
+      {
+        profile: 'default',
+        output: 'json',
+        debug: false,
+        runIds: ['run_ok', 'run_gone'],
+        timeoutSeconds: 30,
+        maxConcurrency: 2,
+      },
+      {
+        credentialsPath,
+        fetchImpl,
+        stdout: line => out.push(line),
+        stderr: line => errs.push(line),
+      },
+    ).catch((error: unknown) => error);
+    expect(rejection).toMatchObject({ exitCode: 7 });
+    const payload = JSON.parse(out.join('')) as {
+      results: Array<{ runId: string; status: string }>;
+    };
+    // The failing member did not abort the pool: the passed verdict survived.
+    expect(payload.results[0]).toMatchObject({ runId: 'run_ok', status: 'passed' });
+    expect(payload.results[1]!.status).toBe('error:NOT_FOUND');
+    // The re-attach hint names the errored member (resumable) but NOT the
+    // already-terminal passed one.
+    const hint = errs.find(line => line.includes('Re-attach with:'));
+    expect(hint).toContain('run_gone');
+    expect(hint).not.toContain('run_ok');
+  });
+
+  it('members dequeued after the shared deadline are not granted extra poll time', async () => {
+    const { credentialsPath } = makeCreds();
+    let fetches = 0;
+    const fetchImpl = makeFetch(() => {
+      fetches += 1;
+      return { body: terminalRun('run_any', 'passed') };
+    });
+    // timeoutSeconds 0: the shared deadline is already in the past when the
+    // pool starts, so every member must resolve to timeout WITHOUT polling
+    // (previously each dequeued member was granted a fresh 1s minimum).
+    const rejection = await runTestWaitMany(
+      {
+        profile: 'default',
+        output: 'json',
+        debug: false,
+        runIds: ['run_a', 'run_b', 'run_c'],
+        timeoutSeconds: 0,
+        maxConcurrency: 1,
+      },
+      { credentialsPath, fetchImpl, stdout: () => undefined, stderr: () => undefined },
+    ).catch((error: unknown) => error);
+    expect(rejection).toMatchObject({ exitCode: 7 });
+    expect(fetches).toBe(0);
+  });
+
+  it('an auth error escalates the exit code to 3', async () => {
+    const { credentialsPath } = makeCreds();
+    const fetchImpl = makeFetch(() => ({
+      status: 401,
+      body: {
+        error: {
+          code: 'AUTH_INVALID',
+          message: 'bad key',
+          nextAction: 'run setup',
+          requestId: 'req_y',
+          details: {},
+        },
+      },
+    }));
+    const rejection = await runTestWaitMany(
+      {
+        profile: 'default',
+        output: 'json',
+        debug: false,
+        runIds: ['run_a', 'run_b'],
+        timeoutSeconds: 30,
+        maxConcurrency: 2,
+      },
+      { credentialsPath, fetchImpl, stdout: () => undefined },
+    ).catch((error: unknown) => error);
+    expect(rejection).toMatchObject({ exitCode: 3 });
+  });
+});
+
 describe('runResult', () => {
   it('JSON mode prints the §6.5 LatestResult shape verbatim', async () => {
     const { credentialsPath } = makeCreds();