@principles/pd-cli 1.133.0 → 1.135.0

package/tests/commands/candidate-intake.test.ts

@@ -72,6 +72,19 @@ vi.mock('@principles/core/runtime-v2', () => ({
   RuntimeStateManager: MockRuntimeStateManager,
   resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
   PrincipleTreeLedgerAdapter: MockPrincipleTreeLedgerAdapter,
+  evaluateCandidateAdmissionFromRecord: vi.fn((candidate: { recommendationKind: string; confidence: number | null }) => {
+    // Mirror the real implementation for test purposes
+    if (candidate.recommendationKind === 'defer') {
+      return { decision: 'deferred', reason: 'recommendation_kind_defer_not_actionable', nextAction: 'review_defer_disposition_manually', evidenceStatus: 'unknown' };
+    }
+    if (candidate.confidence === null) {
+      return { decision: 'needs_evidence', reason: 'confidence_missing_on_candidate_record', nextAction: 're_run_diagnosis_to_populate_confidence_or_manual_review', evidenceStatus: 'unknown' };
+    }
+    if (candidate.confidence < 0.5) {
+      return { decision: 'needs_evidence', reason: `confidence_below_threshold:${candidate.confidence.toFixed(2)}<0.5`, nextAction: 'provide_additional_evidence_or_manual_review', evidenceStatus: 'unknown' };
+    }
+    return { decision: 'admitted', reason: 'cli_partial_check_passed_confidence_and_kind', nextAction: 'none', evidenceStatus: 'unknown' };
+  }),
 }));
 
 vi.mock('../../src/resolve-workspace.js', () => ({
@@ -348,29 +361,37 @@ describe('pd candidate intake', () => {
 
   // Test 4: Non-existent candidate
   it('Test 4 (non-existent candidate): throws CANDIDATE_NOT_FOUND error', async () => {
-    // Setup: service.intake throws CANDIDATE_NOT_FOUND when candidate doesn't exist
-    mockService.intake.mockImplementation(() => {
-      throw new MockCandidateIntakeError(
-        `Candidate invalid-id not found`,
-        'CANDIDATE_NOT_FOUND',
-        { candidateId: 'invalid-id' }
-      );
-    });
+    // PRI-442 Stage 4: getCandidate now returns null before service.intake is called.
+    // The CLI exits with "Candidate not found" instead of relying on service.intake
+    // to throw CANDIDATE_NOT_FOUND.
+    mockStateManager.getCandidate.mockResolvedValue(null);
 
     await handleCandidateIntake({
       candidateId: 'invalid-id',
       workspace: '/tmp/test-workspace',
     });
 
-    // Verify error output contains CANDIDATE_NOT_FOUND
+    // Verify error output contains "Candidate not found"
     expect(consoleErrorSpy).toHaveBeenCalledWith(
-      expect.stringContaining('CANDIDATE_NOT_FOUND')
+      expect.stringContaining('Candidate not found')
     );
     expect(exitSpy).toHaveBeenCalledWith(1);
   });
 
   // Test 5: Invalid candidateId (empty string)
   it('Test 5 (invalid candidateId): empty string throws INPUT_INVALID error', async () => {
+    // PRI-442 Stage 4: getCandidate is called before service.intake, so we need
+    // to mock it to return a valid candidate so service.intake is reached.
+    const mockCandidate = {
+      candidateId: '',
+      artifactId: 'artifact-1',
+      taskId: 'task-1',
+      title: 'Test',
+      description: 'Test',
+      status: 'pending',
+    };
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate);
+
     // Setup: service.intake throws INPUT_INVALID for empty candidateId
     mockService.intake.mockImplementation(() => {
       throw new MockCandidateIntakeError(
@@ -475,6 +496,18 @@ describe('pd candidate intake', () => {
 
   // Test 7: Generic error (non-CandidateIntakeError, covers line 247)
   it('Test 7 (generic error): handles non-CandidateIntakeError errors', async () => {
+    // PRI-442 Stage 4: getCandidate is called before service.intake, so we need
+    // to mock it to return a valid candidate so service.intake is reached.
+    const mockCandidate = {
+      candidateId: 'valid-id',
+      artifactId: 'artifact-1',
+      taskId: 'task-1',
+      title: 'Test',
+      description: 'Test',
+      status: 'pending',
+    };
+    mockStateManager.getCandidate.mockResolvedValue(mockCandidate);
+
     // Setup: service.intake throws a generic Error (not CandidateIntakeError)
     mockService.intake.mockImplementation(() => {
       throw new Error('Some unexpected error');
@@ -584,4 +617,116 @@ describe('pd candidate intake', () => {
       mockStateManager.connection = originalConnection;
     }
   });
+
+  // PRI-442 Stage 4: admission gate bypass tests
+  describe('admission gate bypass prevention (PRI-442 Stage 4)', () => {
+    it('refuses intake when recommendationKind is defer', async () => {
+      const mockCandidate = {
+        candidateId: 'defer-cand',
+        artifactId: 'artifact-1',
+        taskId: 'task-1',
+        title: 'Deferred candidate',
+        description: 'Should not be intakeable',
+        status: 'pending',
+        recommendationKind: 'defer',
+        confidence: 0.9,
+      };
+      mockStateManager.getCandidate.mockResolvedValue(mockCandidate);
+
+      await handleCandidateIntake({
+        candidateId: 'defer-cand',
+        workspace: '/tmp/test-workspace',
+        json: true,
+      });
+
+      // Should NOT call service.intake
+      expect(mockService.intake).not.toHaveBeenCalled();
+      // Should output refused status
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('"status": "refused"')
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('"admissionDecision": "deferred"')
+      );
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('refuses intake when confidence is below threshold', async () => {
+      const mockCandidate = {
+        candidateId: 'low-conf-cand',
+        artifactId: 'artifact-1',
+        taskId: 'task-1',
+        title: 'Low confidence candidate',
+        description: 'Should not be intakeable',
+        status: 'pending',
+        recommendationKind: 'principle',
+        confidence: 0.3,
+      };
+      mockStateManager.getCandidate.mockResolvedValue(mockCandidate);
+
+      await handleCandidateIntake({
+        candidateId: 'low-conf-cand',
+        workspace: '/tmp/test-workspace',
+        json: false,
+      });
+
+      expect(mockService.intake).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Admission gate refused')
+      );
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('needs_evidence')
+      );
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('refuses intake when confidence is null (rc-3 fail loud)', async () => {
+      const mockCandidate = {
+        candidateId: 'null-conf-cand',
+        artifactId: 'artifact-1',
+        taskId: 'task-1',
+        title: 'Null confidence candidate',
+        description: 'Should not be intakeable',
+        status: 'pending',
+        recommendationKind: 'principle',
+        confidence: null,
+      };
+      mockStateManager.getCandidate.mockResolvedValue(mockCandidate);
+
+      await handleCandidateIntake({
+        candidateId: 'null-conf-cand',
+        workspace: '/tmp/test-workspace',
+        json: true,
+      });
+
+      expect(mockService.intake).not.toHaveBeenCalled();
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('confidence_missing_on_candidate_record')
+      );
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('allows intake when candidate passes admission gate', async () => {
+      const mockCandidate = {
+        candidateId: 'admitted-cand',
+        artifactId: 'artifact-1',
+        taskId: 'task-1',
+        title: 'Admitted candidate',
+        description: 'Should be intakeable',
+        status: 'pending',
+        recommendationKind: 'principle',
+        confidence: 0.8,
+      };
+      mockStateManager.getCandidate.mockResolvedValue(mockCandidate);
+      mockService.intake.mockResolvedValue({ id: 'entry-1', title: 'Test', text: 'Test', status: 'probation' });
+
+      await handleCandidateIntake({
+        candidateId: 'admitted-cand',
+        workspace: '/tmp/test-workspace',
+        json: true,
+      });
+
+      expect(mockService.intake).toHaveBeenCalledWith('admitted-cand');
+    });
+  });
 });

package/tests/commands/candidate-internalization-backfill.test.ts

@@ -477,6 +477,36 @@ describe('Commander wiring for backfill --include-pending', () => {
     expect(output.details.totalPending).toBe(1);
   });
 
+  // PRI-442 Stage 4: admission gate bypass prevention for backfill --include-pending
+  it('--include-pending refuses deferred candidate (admission gate bypass prevention)', async () => {
+    mockPrepareAll.mockImplementation((sql: string) => {
+      if (sql.includes("'consumed'")) return [];
+      if (sql.includes("'pending'")) return [{ candidate_id: 'cand-defer-1' }];
+      return [];
+    });
+    mockGetCandidate.mockResolvedValue({
+      candidateId: 'cand-defer-1',
+      taskId: 'diag-task-cand-defer-1',
+      description: 'deferred candidate',
+      recommendationKind: 'defer',
+      confidence: 0.9,
+      sourceRecommendationJson: JSON.stringify({ kind: 'defer', description: 'deferred' }),
+    });
+
+    const program = createBackfillTestProgram();
+    await program.parseAsync(['node', 'pd', 'candidate', 'internalization', 'backfill', '--workspace', WS, '--include-pending', '--confirm', '--json']);
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+    // Should NOT have called intake for the deferred candidate
+    expect(mockIntake).not.toHaveBeenCalled();
+    // Should have an intake_failed result with admission gate reason
+    const failedResult = output.details.results.find(
+      (r: { status: string; reason: string }) => r.status === 'intake_failed' && r.reason.includes('Admission gate refused'),
+    );
+    expect(failedResult).toBeDefined();
+    expect(output.details.intakeFailed).toBe(1);
+  });
+
   it('--dry-run -> RuntimeStateManager readonly=true', async () => {
     const program = createBackfillTestProgram();
     await program.parseAsync(['node', 'pd', 'candidate', 'internalization', 'backfill', '--workspace', WS, '--dry-run', '--json']);

package/tests/commands/cli-help-snapshot.test.ts

@@ -86,7 +86,6 @@ describe('PRI-455: pd runtime --help shows only MVP owner subcommands', () => {
     'canary',
     'synthetic',
     'uat',
-    'internalization',
     'recovery',
     'pruning',
     'diagnostics',
@@ -133,3 +132,18 @@ describe('PRI-455: hidden commands still function (de-surface, not delete)', ()
     expect(output).toContain('--apply');
   });
 });
+
+describe('pd demo first-principle alias (Fix-24)', () => {
+  // cli-7-test-wiring: verify the alias resolves to the same command as story-a.
+  it('pd demo first-principle --help works and matches story-a', () => {
+    const aliasOutput = runPdHelp(['demo', 'first-principle', '--help']);
+    const storyAOutput = runPdHelp(['demo', 'story-a', '--help']);
+
+    // Both should show the same options
+    expect(aliasOutput).toContain('--workspace');
+    expect(aliasOutput).toContain('--json');
+    expect(aliasOutput).toContain('--channels');
+    // Alias output should be identical to story-a output
+    expect(aliasOutput).toBe(storyAOutput);
+  });
+});

package/tests/commands/console-open.test.ts

@@ -496,11 +496,22 @@ describe('CLI command wiring (pd console open)', () => {
     workspaceRoot = path.resolve(__dirname, '../../../..');
     cliPath = path.join(workspaceRoot, 'packages', 'pd-cli', 'dist', 'index.js');
     tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-console-open-test-'));
-    // Fake a console install: create dir + dist/server.js with a minimal HTTP server
-    const consoleDir = path.join(os.homedir(), '.openclaw', 'extensions', 'principles-disciple', 'console');
-    fs.mkdirSync(path.join(consoleDir, 'dist'), { recursive: true });
+    // Isolated fake HOME so the tests never read from — or rmSync-destroy — a
+    // real ~/.openclaw install on developer machines. runPd() points the CLI
+    // child at this home via __PD_CONSOLE_TEST_FAKE_HOME.
+    const fakeHome = path.join(tmp, 'home');
+    process.env.__PD_CONSOLE_TEST_FAKE_HOME = fakeHome;
+    // Fake a console install: dir + ESM package.json + dist/server.js with a
+    // minimal HTTP server. The package.json "type": "module" makes the fake
+    // server's module system deterministic regardless of whether a real
+    // extension-root package.json exists above the console dir.
+    const consoleDir = path.join(fakeHome, '.openclaw', 'extensions', 'principles-disciple', 'console');
+    fs.mkdirSync(path.join(consoleDir, 'dist', 'web'), { recursive: true });
+    fs.writeFileSync(path.join(consoleDir, 'package.json'), JSON.stringify({ name: 'fake-pd-console', version: '0.0.0', type: 'module' }, null, 2));
+    // EP-06 regression guard: dist/web/index.html must exist (PR #1169 fix)
+    fs.writeFileSync(path.join(consoleDir, 'dist', 'web', 'index.html'), '<!DOCTYPE html><html></html>');
     fs.writeFileSync(path.join(consoleDir, 'dist', 'server.js'), `
-      const http = require('http');
+      import http from 'node:http';
       const args = process.argv.slice(2);
       const portIdx = args.indexOf('--port');
       const port = portIdx >= 0 ? parseInt(args[portIdx + 1]) : 3100;
@@ -522,11 +533,8 @@ describe('CLI command wiring (pd console open)', () => {
   });
 
   afterEach(() => {
+    delete process.env.__PD_CONSOLE_TEST_FAKE_HOME;
     try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
-    try {
-      const consoleDir = path.join(os.homedir(), '.openclaw', 'extensions', 'principles-disciple', 'console');
-      fs.rmSync(consoleDir, { recursive: true, force: true });
-    } catch { /* ignore */ }
   });
 
   it('console open subcommand is registered (pd console open --help)', () => {
@@ -569,6 +577,58 @@ describe('CLI command wiring (pd console open)', () => {
     expect(parsed).toHaveProperty('browserOpened');
   }, 10_000);
 
+  it('pd console open --json fresh spawn includes a positive integer serverPid (PRI-526)', async () => {
+    // Async stream-parse + guaranteed teardown. execFileSync patterns are
+    // unreliable here on Windows: the CLI keeps running after printing JSON
+    // (fresh spawn) or may unexpectedly take another branch, and killing via
+    // timeout can leave the grandchild server holding pipe handles.
+    let run: CliJsonRun | undefined;
+    try {
+      run = await runPdUntilJson(
+        ['console', 'open', '--workspace', tmp, '--port', '49390', '--json', '--no-browser'],
+        workspaceRoot,
+      );
+      if (!isRecord(run.parsed)) throw new Error('CLI JSON output was not an object');
+      expect(run.parsed.status).toBe('started');
+      expect(run.parsed.reused).toBe(false);
+      const serverPid = run.parsed.serverPid;
+      expect(typeof serverPid === 'number' && Number.isInteger(serverPid) && serverPid > 0).toBe(true);
+    } finally {
+      await teardownCliTree(run);
+    }
+  }, 20_000);
+
+  it('pd console open --json reused path does NOT include serverPid (PRI-526)', async () => {
+    // Stand up a fake healthy console in-process, then point the CLI at its
+    // port: planConsoleLaunch probes /api/health → 200 → reused, no spawn.
+    const server = http.createServer((req, res) => {
+      if (req.url === '/api/health') {
+        res.statusCode = 200;
+        res.end(JSON.stringify({ success: true }));
+        return;
+      }
+      res.statusCode = 404;
+      res.end();
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+    const addr = server.address();
+    if (typeof addr !== 'object' || !addr) throw new Error('no addr');
+    let run: CliJsonRun | undefined;
+    try {
+      run = await runPdUntilJson(
+        ['console', 'open', '--workspace', tmp, '--port', String(addr.port), '--json', '--no-browser'],
+        workspaceRoot,
+      );
+      if (!isRecord(run.parsed)) throw new Error('CLI JSON output was not an object');
+      expect(run.parsed.status).toBe('reused');
+      expect(run.parsed.reused).toBe(true);
+      expect(run.parsed).not.toHaveProperty('serverPid');
+    } finally {
+      await teardownCliTree(run);
+      server.close();
+    }
+  }, 20_000);
+
   it('pd console open --port 99999 --json returns a structured failure (invalid port)', () => {
     const out = runPd(['console', 'open', '--workspace', tmp, '--port', '99999', '--json', '--no-browser'], workspaceRoot);
     const parsed = JSON.parse(out);
@@ -666,11 +726,22 @@ describe('CLI command wiring (pd console open)', () => {
 
     it('sets browserOpened: false when browser fails to open', async () => {
       const { handleConsoleOpen } = await import('../../src/commands/console.js');
-      
+
       const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
       const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
       const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
+      // The in-process handler resolves the console dir via getConsoleDir(),
+      // which reads HOME/USERPROFILE directly. Point them at the isolated
+      // fake home — a clean CI runner has no real ~/.openclaw console, and
+      // relying on one (as this test implicitly did before) makes the result
+      // machine-dependent.
+      const fakeHome = process.env.__PD_CONSOLE_TEST_FAKE_HOME ?? '';
+      const savedHome = process.env.HOME;
+      const savedUserProfile = process.env.USERPROFILE;
+      process.env.HOME = fakeHome;
+      process.env.USERPROFILE = fakeHome;
+
       const mockChild = new EventEmitter() as any;
       mockChild.unref = vi.fn();
       let spawnCalled = false;
@@ -698,23 +769,29 @@ describe('CLI command wiring (pd console open)', () => {
         };
       };
 
-      await handleConsoleOpen({
-        workspace: tmp,
-        json: false,
-      });
+      try {
+        await handleConsoleOpen({
+          workspace: tmp,
+          json: false,
+        });
 
-      await new Promise(resolve => setTimeout(resolve, 150));
+        await new Promise(resolve => setTimeout(resolve, 150));
 
-      const loggedOutput = logSpy.mock.calls.map(c => c.join(' ')).join('\n');
-      expect(exitSpy).not.toHaveBeenCalled();
-      expect(spawnCalled).toBe(true);
-      
-      expect(loggedOutput).not.toContain('Browser opened');
-      expect(loggedOutput).toContain('Open http://127.0.0.1:3100 in your browser');
+        const loggedOutput = logSpy.mock.calls.map(c => c.join(' ')).join('\n');
+        expect(exitSpy).not.toHaveBeenCalled();
+        expect(spawnCalled).toBe(true);
 
-      exitSpy.mockRestore();
-      logSpy.mockRestore();
-      errorSpy.mockRestore();
+        expect(loggedOutput).not.toContain('Browser opened');
+        expect(loggedOutput).toContain('Open http://127.0.0.1:3100 in your browser');
+      } finally {
+        if (savedHome === undefined) delete process.env.HOME;
+        else process.env.HOME = savedHome;
+        if (savedUserProfile === undefined) delete process.env.USERPROFILE;
+        else process.env.USERPROFILE = savedUserProfile;
+        exitSpy.mockRestore();
+        logSpy.mockRestore();
+        errorSpy.mockRestore();
+      }
     });
   });
 
@@ -752,6 +829,13 @@ describe('CLI command wiring (pd console open)', () => {
     it('[::1] is accepted and normalized to ::1 (not refused)', () => {
       // May spawn a long-lived server, use timeout.
       const out = runPd(['console', 'open', '--workspace', tmp, '--host', '[::1]', '--json', '--no-browser'], workspaceRoot, 8_000);
+      if (out.trim() === '') {
+        // The CLI was still in its 15s ready-poll when execFileSync timed out.
+        // Known environment limitation: on Windows hosts where IPv6 loopback
+        // connections are refused (EACCES), the health probe on ::1 never
+        // succeeds. CI (Linux) is unaffected.
+        throw new Error('CLI produced no JSON within 8s — ::1 health probe never succeeded (IPv6 loopback may be blocked on this machine)');
+      }
       const parsed = JSON.parse(out);
       // Should NOT be refused — [::1] is loopback
       expect(parsed.status).not.toBe('refused');
@@ -759,22 +843,30 @@ describe('CLI command wiring (pd console open)', () => {
       expect(parsed.host).toBe('::1');
     }, 10_000);
   });
+
+  describe('EP-06 regression guard: dist/web/index.html check (PR #1169)', () => {
+    it('returns console_web_ui_missing when dist/web/index.html does not exist', () => {
+      // beforeEach creates the fake console dir WITH dist/web/index.html.
+      // Remove it to simulate a corrupted install (the PR #1169 regression).
+      const fakeHome = process.env.__PD_CONSOLE_TEST_FAKE_HOME ?? '';
+      const webIndex = path.join(fakeHome, '.openclaw', 'extensions', 'principles-disciple', 'console', 'dist', 'web', 'index.html');
+      fs.rmSync(webIndex, { force: true });
+
+      const out = runPd(['console', 'open', '--workspace', tmp, '--json', '--no-browser'], workspaceRoot, 5_000);
+      const parsed = JSON.parse(out);
+      expect(parsed.status).toBe('failed');
+      expect(parsed.reason).toBe('console_web_ui_missing');
+      expect(parsed.nextAction).toMatch(/create-principles-disciple/);
+    }, 10_000);
+  });
 });
 
 function runPd(args: string[], cwd: string, timeoutMs?: number): string {
   try {
-    const env: Record<string, string> = { ...process.env };
-    if (!args.includes('--workspace') && !args.includes('--help') && !args.includes('-h')) {
-      env.USERPROFILE = '/nonexistent';
-      env.HOME = '/nonexistent';
-      env.HOMEPATH = '/nonexistent';
-      env.HOMEDRIVE = '/nonexistent';
-      delete env.PD_WORKSPACE_DIR;
-    }
     return execFileSync('node', [getBuiltPdCliPath(), ...args], {
       encoding: 'utf8',
       cwd,
-      env,
+      env: buildChildEnv(),
       timeout: timeoutMs,
     });
   } catch (err: unknown) {
@@ -787,3 +879,108 @@ function runPd(args: string[], cwd: string, timeoutMs?: number): string {
     throw err;
   }
 }
+
+/** Env for spawned CLI processes: isolated fake HOME, no workspace env leaks. */
+function buildChildEnv(): Record<string, string> {
+  const env = { ...process.env } as Record<string, string>;
+  const fakeHome = process.env.__PD_CONSOLE_TEST_FAKE_HOME;
+  if (fakeHome) {
+    env.USERPROFILE = fakeHome;
+    env.HOME = fakeHome;
+    delete env.HOMEPATH;
+    delete env.HOMEDRIVE;
+    delete env.PD_WORKSPACE_DIR;
+  }
+  return env;
+}
+
+/** Runtime type guard for unknown CLI JSON output (rc-1/rc-2). */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+// ─── Async CLI runner with guaranteed teardown (PRI-526 tests) ───────────────
+
+interface CliJsonRun {
+  parsed: unknown;
+  child: childProcessModule.ChildProcess;
+}
+
+/**
+ * Spawn the CLI and resolve as soon as stdout contains one parseable JSON
+ * object. Fails fast (bounded timeout / early exit) with the collected
+ * stdout in the error message. The caller MUST call teardownCliTree(run)
+ * in a finally block — the CLI process may still be alive after the JSON
+ * is emitted (fresh-spawn mode keeps the console server attached).
+ */
+async function runPdUntilJson(args: string[], cwd: string, timeoutMs = 12_000): Promise<CliJsonRun> {
+  const child = childProcessModule.spawn('node', [getBuiltPdCliPath(), ...args], {
+    cwd,
+    env: buildChildEnv(),
+  });
+  let stdout = '';
+  child.stdout?.on('data', (d: Buffer) => { stdout += d.toString('utf8'); });
+
+  const parsed: unknown = await new Promise<unknown>((resolve, reject) => {
+    let done = false;
+    const fail = (msg: string): void => {
+      if (done) return;
+      done = true;
+      reject(new Error(`${msg}; stdout so far: ${stdout.slice(0, 400)}`));
+    };
+    const timer = setTimeout(() => fail('timed out waiting for CLI JSON'), timeoutMs);
+    const tryParse = (): boolean => {
+      const trimmed = stdout.trim();
+      if (!trimmed.startsWith('{')) return false;
+      try {
+        const value = JSON.parse(trimmed) as unknown;
+        done = true;
+        clearTimeout(timer);
+        resolve(value);
+        return true;
+      } catch {
+        return false; // partial pretty-printed JSON — wait for more chunks
+      }
+    };
+    if (tryParse()) return;
+    const onData = (): void => {
+      if (tryParse()) child.stdout?.off('data', onData);
+    };
+    child.stdout?.on('data', onData);
+    child.on('error', (err: Error) => fail(`CLI spawn error: ${err.message}`));
+    child.on('exit', (code: number | null) => fail(`CLI exited with code ${code} before emitting JSON`));
+  });
+
+  return { parsed, child };
+}
+
+/**
+ * Deterministic teardown of a runPdUntilJson run: kill the reported console
+ * server PID (grandchild) first so the CLI can exit on its own, then wait a
+ * bounded time, then force-kill the whole CLI tree. Safe to call multiple
+ * times and with undefined.
+ */
+async function teardownCliTree(run: CliJsonRun | undefined): Promise<void> {
+  if (!run) return;
+  const record = isRecord(run.parsed) ? run.parsed : undefined;
+  const serverPid = record !== undefined && typeof record.serverPid === 'number' ? record.serverPid : undefined;
+  if (serverPid !== undefined) {
+    try { process.kill(serverPid); } catch { /* already gone */ }
+  }
+  await new Promise<void>((resolve) => {
+    const t = setTimeout(() => { killTreeForce(run.child); resolve(); }, 4_000);
+    run.child.once('exit', () => { clearTimeout(t); resolve(); });
+  });
+  killTreeForce(run.child);
+}
+
+/**
+ * Last-resort kill of the CLI child process. The console server grandchild is
+ * reaped separately via its reported serverPid (see teardownCliTree), so a
+ * plain signal kill suffices — no shell/argv command wrapper needed.
+ */
+function killTreeForce(child: childProcessModule.ChildProcess): void {
+  try {
+    child.kill('SIGKILL');
+  } catch { /* already gone */ }
+}