@principles/pd-cli 1.132.0 → 1.134.0

package/src/services/runtime-adapter-resolver.ts

@@ -103,6 +103,7 @@ export interface ResolveAdapterOptions {
     apiKeyEnv?: string;
     baseUrl?: string;
     maxRetries?: number;
+    maxTokens?: number;
   };
   /**
    * CLI override for openclaw mode (from --openclaw-local / --openclaw-gateway flags).
@@ -215,6 +216,7 @@ export function resolveRuntimeAdapterFromConfig(opts: ResolveAdapterOptions): PD
     const apiKeyEnv = opts.piAiOverrides?.apiKeyEnv ?? configFields.apiKeyEnv;
     const baseUrl = opts.piAiOverrides?.baseUrl ?? configFields.baseUrl;
     const maxRetries = opts.piAiOverrides?.maxRetries ?? configFields.maxRetries;
+    const maxTokens = opts.piAiOverrides?.maxTokens ?? configFields.maxTokens;
     const adapterTimeoutMs = opts.timeoutMs ?? configFields.timeoutMs;
 
     // PRI-431 Step 1d + PR review fix: manual missing-field check on MERGED values
@@ -283,9 +285,11 @@ export function resolveRuntimeAdapterFromConfig(opts: ResolveAdapterOptions): PD
       model: String(model),
       apiKeyEnv: String(apiKeyEnv),
       maxRetries,
+      maxTokens,
       timeoutMs: adapterTimeoutMs,
       baseUrl,
       workspace: opts.workspaceDir,
+      ...(configFields.systemPrompt ? { systemPrompt: configFields.systemPrompt } : {}),
     });
   }
 

package/src/services/synthetic-baseline-runner.ts

@@ -21,6 +21,7 @@ import { auditCandidateLedgerConsistency } from '@principles/core/runtime-v2';
 import { OperatorHealthReadModel } from '@principles/core/runtime-v2';
 import { createInternalizationQueueReadModel } from '@principles/core/runtime-v2';
 import { createPITaskDiagnosticJson } from '@principles/core/runtime-v2';
+import { contentHashFn } from './rulehost-pipeline-runner.js';
 import {
   computeOverallStatus,
   boundedEvidence,
@@ -148,6 +149,7 @@ export async function runSyntheticBaseline(opts: SyntheticBaselineRunnerOptions)
         artifactStore: stateManager.piArtifactStore,
         validator: new DefaultDiagRootCauseValidator(),
         contextAssembler,
+        contentHashFn,
       },
       {
         owner: 'synthetic-baseline',
@@ -164,6 +166,7 @@ export async function runSyntheticBaseline(opts: SyntheticBaselineRunnerOptions)
         eventEmitter,
         artifactStore: stateManager.piArtifactStore,
         validator: new DefaultDiagDistillerValidator(),
+        contentHashFn,
       },
       {
         owner: 'synthetic-baseline',
@@ -180,6 +183,7 @@ export async function runSyntheticBaseline(opts: SyntheticBaselineRunnerOptions)
         eventEmitter,
         artifactStore: stateManager.piArtifactStore,
         committer,
+        contentHashFn,
       },
       {
         owner: 'synthetic-baseline',
@@ -214,6 +218,13 @@ export async function runSyntheticBaseline(opts: SyntheticBaselineRunnerOptions)
       painType: 'tool_failure',
       source: 'synthetic-baseline',
       reason: 'Synthetic baseline deterministic pain signal',
+      // Synthetic baseline is a deterministic smoke tool — it has no real host
+      // session to harvest evidence from. Provide a synthetic evidence entry so
+      // the PEAT-B1 admission gate (painEvidenceAdmission, default-on) does not
+      // short-circuit the pain before diagnosis. Without this, the baseline
+      // reports `short_circuited: input evidence empty` and every downstream
+      // stage fails, even though the pipeline itself is healthy.
+      evidence: [{ sourceRef: `synthetic:${painId}`, note: 'Synthetic baseline deterministic evidence anchor' }],
     });
 
     const painPassed = bridgeResult.status === 'succeeded';

package/src/utils/production-workspace-guard.test.ts

@@ -5,23 +5,27 @@ import {
   isProductionWorkspace,
   guardUatWorkspace,
   getSafeUatWorkspacePath,
+  resolveWorkspacePath,
   formatGuardRefusal,
   type GuardRefusal,
 } from './production-workspace-guard.js';
 
+// Use os.homedir()-derived paths so the tests work cross-platform
+// (previously hardcoded Windows paths like D:\.openclaw\workspace which on
+// Linux resolve to <cwd>/D:\.openclaw\workspace — meaningless).
+const HOMEDIR_WORKSPACE = path.join(os.homedir(), '.openclaw', 'workspace');
+
 const PRODUCTION_PATHS = [
-  'D:\\.openclaw\\workspace',
-  'C:\\.openclaw\\workspace',
-  'C:\\Users\\Administrator\\.openclaw\\workspace',
-  path.join(os.homedir(), '.openclaw', 'workspace'),
+  HOMEDIR_WORKSPACE,
 ];
 
 const SAFE_PATHS = [
-  'D:\\.openclaw\\workspace-test',
-  'D:\\.openclaw\\workspace-backup',
+  path.join(os.homedir(), '.openclaw', 'workspace-test'),
+  path.join(os.homedir(), '.openclaw', 'workspace-backup'),
   path.join(os.tmpdir(), 'pd-uat-workspace'),
   path.join(os.tmpdir(), 'pd-test-any'),
-  'C:\\completely-unrelated\\work',
+  // A path that is clearly unrelated on every platform
+  path.join(os.tmpdir(), 'completely-unrelated-work'),
 ];
 
 describe('isProductionWorkspace', () => {
@@ -32,18 +36,15 @@ describe('isProductionWorkspace', () => {
     expect(isProductionWorkspace(path.resolve(safePath))).toBe(false);
   });
   it('detects descendant', () => {
-    // Use a platform-appropriate descendant path so the test works on both
-    // Windows (where D:\... resolves as-is) and Linux CI (where D:\... is
-    // treated as a relative path and resolves under cwd).
-    const prodPath = path.resolve(path.join(os.homedir(), '.openclaw', 'workspace'));
+    const prodPath = path.resolve(HOMEDIR_WORKSPACE);
     const descendantPath = path.join(prodPath, 'sub', 'child');
     expect(isProductionWorkspace(descendantPath)).toBe(true);
   });
   it('rejects sibling workspace-test (ERR-030)', () => {
-    expect(isProductionWorkspace(path.resolve('D:\\.openclaw\\workspace-test'))).toBe(false);
+    expect(isProductionWorkspace(path.resolve(path.join(os.homedir(), '.openclaw', 'workspace-test')))).toBe(false);
   });
   it('rejects sibling workspace-backup (ERR-030)', () => {
-    expect(isProductionWorkspace(path.resolve('D:\\.openclaw\\workspace-backup'))).toBe(false);
+    expect(isProductionWorkspace(path.resolve(path.join(os.homedir(), '.openclaw', 'workspace-backup')))).toBe(false);
   });
 });
 
@@ -58,7 +59,7 @@ describe('guardUatWorkspace', () => {
       }
     });
     it('refuses descendant', () => {
-      const prodPath = path.resolve(path.join(os.homedir(), '.openclaw', 'workspace'));
+      const prodPath = path.resolve(HOMEDIR_WORKSPACE);
       const descendantPath = path.join(prodPath, 'subdir');
       expect(guardUatWorkspace(descendantPath, 'test').refused).toBe(true);
     });
@@ -68,8 +69,10 @@ describe('guardUatWorkspace', () => {
       const r = guardUatWorkspace(safePath, 'test');
       expect(r.refused).toBe(false);
     });
-    it.each(['D:\\.openclaw\\workspace-test', 'D:\\.openclaw\\workspace-backup'])(
-      'allows sibling: %s (ERR-030)', (p) => {
+    it.each([
+      path.join(os.homedir(), '.openclaw', 'workspace-test'),
+      path.join(os.homedir(), '.openclaw', 'workspace-backup'),
+    ])('allows sibling: %s (ERR-030)', (p) => {
         expect(guardUatWorkspace(p, 'test').refused).toBe(false);
       });
   });
@@ -77,7 +80,7 @@ describe('guardUatWorkspace', () => {
 
 describe('JSON output (EP-04)', () => {
   it('outputs single object with reason and nextAction', () => {
-    const r = guardUatWorkspace('D:\\.openclaw\\workspace', 'test');
+    const r = guardUatWorkspace(HOMEDIR_WORKSPACE, 'test');
     const json = formatGuardRefusal(r as GuardRefusal, 'test', true);
     const parsed = JSON.parse(json);
     expect(parsed).toMatchObject({
@@ -87,7 +90,7 @@ describe('JSON output (EP-04)', () => {
     expect(Array.isArray(parsed)).toBe(false);
   });
   it('no console prefixes in JSON', () => {
-    const r = guardUatWorkspace('D:\\.openclaw\\workspace', 'test');
+    const r = guardUatWorkspace(HOMEDIR_WORKSPACE, 'test');
     const json = formatGuardRefusal(r as GuardRefusal, 'test', true);
     expect(json).not.toContain('[pd-cli]');
     expect(json).not.toContain('ERROR:');
@@ -97,7 +100,7 @@ describe('JSON output (EP-04)', () => {
 
 describe('text output (EP-03)', () => {
   it('includes reason and nextAction', () => {
-    const r = guardUatWorkspace('D:\\.openclaw\\workspace', 'test');
+    const r = guardUatWorkspace(HOMEDIR_WORKSPACE, 'test');
     const text = formatGuardRefusal(r as GuardRefusal, 'test', false);
     expect(text).toContain('Reason:');
     expect(text).toContain('Next Action:');
@@ -112,4 +115,43 @@ describe('getSafeUatWorkspacePath', () => {
     expect(p1).toContain(os.tmpdir());
     expect(p1).toContain('pd-uat-workspace');
   });
-});
+});
+
+describe('resolveWorkspacePath', () => {
+  it('resolves an absolute path as-is', () => {
+    const abs = path.resolve('/tmp/my-workspace');
+    expect(resolveWorkspacePath(abs)).toBe(abs);
+  });
+
+  it('resolves a relative path against cwd', () => {
+    const result = resolveWorkspacePath('relative/path');
+    const expected = path.resolve(process.cwd(), 'relative/path');
+    expect(result).toBe(expected);
+  });
+
+  it('defaults to cwd when no input is provided', () => {
+    const result = resolveWorkspacePath(undefined);
+    expect(result).toBe(path.resolve(process.cwd()));
+  });
+});
+
+describe('PD_PRODUCTION_WORKSPACE env var (module-load-time)', () => {
+  // NOTE: PRODUCTION_WORKSPACE_PATHS is built once at module load time from
+  // process.env.PD_PRODUCTION_WORKSPACE. Setting the env var after the module
+  // is loaded does NOT change behavior. These tests verify that the default
+  // production path (HOMEDIR_WORKSPACE) is correctly protected, which is the
+  // primary regression risk.
+
+  it('guardUatWorkspace refuses the default production workspace', () => {
+    const r = guardUatWorkspace(HOMEDIR_WORKSPACE, 'test');
+    expect(r.refused).toBe(true);
+    if (r.refused) {
+      expect(r.isProduction).toBe(true);
+      expect(r.workspace).toBe(path.resolve(HOMEDIR_WORKSPACE));
+    }
+  });
+
+  it('isProductionWorkspace returns true for the default production path', () => {
+    expect(isProductionWorkspace(path.resolve(HOMEDIR_WORKSPACE))).toBe(true);
+  });
+});

package/src/utils/production-workspace-guard.ts

@@ -3,10 +3,10 @@
  *
  * Prevents UAT/runtime test commands from writing to production workspaces.
  *
- * Production workspaces are:
- * - D:\.openclaw\workspace
- * - C:\Users\Administrator\.openclaw\workspace
- * - And the default workspace resolved by OpenClaw configuration
+ * Production workspaces:
+ * - Default: ~/.openclaw/workspace (cross-platform)
+ * - Additional paths declared via PD_PRODUCTION_WORKSPACE env var
+ *   (use path.delimiter — `;` on Windows, `:` on Unix — to separate multiple paths)
  *
  * This module follows ERR-030 (path prefix matching must use segment boundaries)
  * and EP-03/EP-04 (fail loud with structured reason and nextAction).
@@ -20,19 +20,22 @@ import { existsSync } from 'fs';
 
 /**
  * List of production workspace paths that should be protected from UAT/test writes.
- * These are the default paths where PD is typically installed and used for real work.
+ * Built from: the universal default (~/.openclaw/workspace) plus any paths
+ * declared via PD_PRODUCTION_WORKSPACE.
  */
-const PRODUCTION_WORKSPACE_PATHS = [
-  // Windows default
-  path.resolve('D:\\.openclaw\\workspace'),
-  path.resolve('C:\\.openclaw\\workspace'),
-  path.resolve('C:\\Users\\Administrator\\.openclaw\\workspace'),
-  path.resolve('C:\\Users\\Admin\\.openclaw\\workspace'),
-  // Unix-like defaults
-  path.resolve(path.join(os.homedir(), '.openclaw', 'workspace')),
-  // macOS-specific
-  path.resolve(path.join(os.homedir(), '.openclaw', 'workspace')),
-];
+function buildProductionWorkspacePaths(): string[] {
+  const paths = [path.resolve(path.join(os.homedir(), '.openclaw', 'workspace'))];
+  const extra = process.env.PD_PRODUCTION_WORKSPACE;
+  if (extra) {
+    for (const p of extra.split(path.delimiter)) {
+      const trimmed = p.trim();
+      if (trimmed) paths.push(path.resolve(trimmed));
+    }
+  }
+  return paths;
+}
+
+const PRODUCTION_WORKSPACE_PATHS = buildProductionWorkspacePaths();
 
 // ── Resolution helpers ───────────────────────────────────────────────────────
 

package/tests/bdd/cli-contract.steps.ts

@@ -0,0 +1,343 @@
+/**
+ * BDD step definitions for CLI strict JSON output contract (cli-1-strict-json).
+ *
+ * Approach: Command + mocks (NOT real CLI subprocess execution).
+ * Reuses the exact same mock pattern as tests/commands/pain-retry.test.ts:
+ *   - vi.hoisted() + vi.mock() to stub @principles/core/runtime-v2 and friends
+ *   - Import handlePainRetry directly and call it in-process
+ *   - Capture console.log via vi.spyOn to verify stdout JSON contract
+ *
+ * Rationale: pd pain retry needs a real workspace + pain-id + config to execute
+ * as a subprocess. Testing the JSON output contract in-process with mocks is
+ * more reliable and follows the established pattern in this repo.
+ */
+import { vi, expect } from 'vitest';
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { createStepRegistry, defineFeature } from './support/vitest-bdd.js';
+import { resolveFeaturePath } from './support/repo-root.js';
+
+// ── Mocks (mirrors tests/commands/pain-retry.test.ts) ──────────────────────────
+
+const {
+  MockRuntimeStateManager,
+  mockGetTask,
+  mockGetCandidatesByTaskId,
+  mockUpdateCandidateStatus,
+  mockGetRunsByTask,
+} = vi.hoisted(() => {
+  const mockGetTask = vi.fn().mockResolvedValue(null);
+  const mockGetCandidatesByTaskId = vi.fn().mockResolvedValue([]);
+  const mockUpdateCandidateStatus = vi.fn().mockResolvedValue(undefined);
+  const mockGetRunsByTask = vi.fn().mockResolvedValue([]);
+
+  class MockRuntimeStateManager {
+    initialize = vi.fn().mockResolvedValue(undefined);
+    close = vi.fn().mockResolvedValue(undefined);
+    getTask = mockGetTask;
+    getCandidatesByTaskId = mockGetCandidatesByTaskId;
+    updateCandidateStatus = mockUpdateCandidateStatus;
+    getRunsByTask = mockGetRunsByTask;
+    connection = {} as Record<string, unknown>;
+    taskStore = {};
+    runStore = {};
+  }
+  return {
+    MockRuntimeStateManager,
+    mockGetTask,
+    mockGetCandidatesByTaskId,
+    mockUpdateCandidateStatus,
+    mockGetRunsByTask,
+  };
+}, { validateType: true });
+
+const { mockIntake, MockCandidateIntakeService } = vi.hoisted(() => {
+  const mockIntake = vi.fn();
+  function MockCandidateIntakeService(this: unknown) {
+    return { intake: mockIntake };
+  }
+  MockCandidateIntakeService.prototype = {};
+  return { mockIntake, MockCandidateIntakeService };
+});
+
+const { MockPrincipleTreeLedgerAdapter } = vi.hoisted(() => {
+  function MockPrincipleTreeLedgerAdapter(this: unknown) {
+    return {};
+  }
+  MockPrincipleTreeLedgerAdapter.prototype = {};
+  return { MockPrincipleTreeLedgerAdapter };
+});
+
+const { mockRun, mockResolveRuntimeConfig, mockResolveRuntimeFromPdConfig } = vi.hoisted(() => {
+  const mockRun = vi.fn().mockResolvedValue({
+    status: 'succeeded',
+    taskId: 'diagnosis_test-pain-1',
+    runId: 'run-retry-1',
+    contextHash: 'abc123',
+  });
+  const mockResolveRuntimeConfig = vi.fn().mockReturnValue({
+    runtimeKind: 'pi-ai',
+    provider: 'test-provider',
+    model: 'test-model',
+    apiKeyEnv: 'TEST_KEY',
+    timeoutMs: 300000,
+    agentId: 'main',
+  });
+  const mockResolveRuntimeFromPdConfig = vi.fn().mockReturnValue({
+    result: {
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_KEY',
+      timeoutMs: 300000,
+      agentId: 'main',
+    },
+    legacyWarnings: [],
+    configSource: '.pd/config.yaml',
+    configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
+  });
+  return { mockRun, mockResolveRuntimeConfig, mockResolveRuntimeFromPdConfig };
+});
+
+vi.mock('../../src/resolve-workspace.js', () => ({
+  resolveWorkspaceDir: vi.fn().mockReturnValue('/tmp/fake-workspace'),
+}));
+
+vi.mock('@principles/core/runtime-v2', () => {
+  return {
+    RuntimeStateManager: vi.fn().mockImplementation(function () {
+      return new MockRuntimeStateManager();
+    }),
+    SqliteHistoryQuery: vi.fn().mockImplementation(function () { return {}; }),
+    SqliteContextAssembler: vi.fn().mockImplementation(function () { return {}; }),
+    SqliteDiagnosticianCommitter: vi.fn().mockImplementation(function () { return {}; }),
+    SqliteTrajectoryLocator: vi.fn().mockImplementation(function () { return {}; }),
+    SqliteSourceTraceLocator: vi.fn().mockImplementation(function () { return {}; }),
+    // Dead-letter store mock: getByPainId returns null so the implementation
+    // produces status='not_found' with reason='task_not_found' for the
+    // "失败命令的 --json 输出含 reason 和 nextAction" scenario.
+    SqliteDeadLetterStore: vi.fn().mockImplementation(function () {
+      return { getByPainId: vi.fn().mockReturnValue(null) };
+    }),
+    PainSignalBridge: vi.fn().mockImplementation(function () { return {}; }),
+    StoreEventEmitter: vi.fn().mockImplementation(function () { return {}; }),
+    storeEmitter: { emitTelemetry: vi.fn() },
+    SplitDiagnosticianRunner: vi.fn().mockImplementation(function () { return {}; }),
+    DiagRootCauseRunner: vi.fn().mockImplementation(function () { return {}; }),
+    DiagDistillerRunner: vi.fn().mockImplementation(function () { return {}; }),
+    DiagRouterRunner: vi.fn().mockImplementation(function () { return {}; }),
+    DefaultDiagRootCauseValidator: vi.fn().mockImplementation(function () { return {}; }),
+    DefaultDiagDistillerValidator: vi.fn().mockImplementation(function () { return {}; }),
+    DisabledDiagnosticianRunner: vi.fn().mockImplementation(function () { return {}; }),
+    TestDoubleRuntimeAdapter: vi.fn().mockImplementation(function () { return {}; }),
+    OpenClawCliRuntimeAdapter: vi.fn().mockImplementation(function () { return {}; }),
+    PiAiRuntimeAdapter: vi.fn().mockImplementation(function () { return {}; }),
+    SPLIT_PIPELINE_TOTAL_TIMEOUT_MS: 300000,
+    PDRuntimeError: class PDRuntimeError extends Error {
+      constructor(public category: string, message: string) {
+        super(message);
+        this.name = 'PDRuntimeError';
+      }
+    },
+    CandidateIntakeService: MockCandidateIntakeService,
+    resolveRuntimeConfig: mockResolveRuntimeConfig,
+    isRuntimeConfigError: vi.fn().mockReturnValue(false),
+    isFeatureEnabled: vi.fn().mockReturnValue(true),
+    resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
+    validatePdConfig: vi.fn().mockReturnValue({ valid: true, errors: [] }),
+    computeEffectivePdConfig: vi.fn().mockReturnValue({ config: {}, source: 'defaults', warnings: [] }),
+    computeFeatureFlagsFromConfig: vi.fn().mockReturnValue({}),
+    redactPdConfig: vi.fn().mockImplementation((c) => c),
+    run: mockRun,
+    status: vi.fn(),
+    PrincipleTreeLedgerAdapter: MockPrincipleTreeLedgerAdapter,
+  };
+});
+
+vi.mock('../../src/config-reader.js', () => ({
+  readOutputLanguageFromWorkspace: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
+}));
+
+vi.mock('../../src/services/resolve-runtime-from-pd-config.js', () => ({
+  resolveRuntimeFromPdConfig: mockResolveRuntimeFromPdConfig,
+}));
+
+import { registerPainRetryCommand } from '../../src/commands/pain-retry.js';
+
+// ── Test data ──────────────────────────────────────────────────────────────────
+
+const RETRY_WAIT_TASK = {
+  taskId: 'diagnosis_pain-001',
+  taskKind: 'diagnostician',
+  status: 'retry_wait' as const,
+  attemptCount: 1,
+  maxAttempts: 3,
+  lastError: 'output_invalid',
+  leaseOwner: null,
+  leaseExpiresAt: null,
+  resultRef: null,
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+};
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+/** Reset all mocks to a clean default state for the next scenario. */
+function resetMocksForScenario(painId: string): void {
+  vi.clearAllMocks();
+
+  mockResolveRuntimeConfig.mockReturnValue({
+    runtimeKind: 'pi-ai',
+    provider: 'test-provider',
+    model: 'test-model',
+    apiKeyEnv: 'TEST_KEY',
+    timeoutMs: 300000,
+    agentId: 'main',
+  });
+  mockResolveRuntimeFromPdConfig.mockReturnValue({
+    result: {
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_KEY',
+      timeoutMs: 300000,
+      agentId: 'main',
+    },
+    legacyWarnings: [],
+    configSource: '.pd/config.yaml',
+    configLoadResult: { ok: true, effective: {}, defaults: {}, legacyFilesDetected: [] },
+  });
+  mockGetCandidatesByTaskId.mockResolvedValue([]);
+  mockUpdateCandidateStatus.mockResolvedValue(undefined);
+  mockGetRunsByTask.mockResolvedValue([]);
+  mockIntake.mockReset();
+
+  if (painId === 'nonexistent') {
+    // Failure scenario: task not found
+    mockGetTask.mockResolvedValue(null);
+  } else {
+    // Success scenario: retry_wait task → succeeded
+    mockGetTask.mockResolvedValue({
+      ...RETRY_WAIT_TASK,
+      taskId: `diagnosis_${painId}`,
+    });
+    mockRun.mockResolvedValue({
+      status: 'succeeded',
+      taskId: `diagnosis_${painId}`,
+      runId: 'run-retry-1',
+      contextHash: 'abc123',
+    });
+  }
+}
+
+// ── Step definitions ───────────────────────────────────────────────────────────
+
+const registry = createStepRegistry();
+
+registry.given('一个可用的 pd-cli 可执行文件', () => {
+  if (typeof registerPainRetryCommand !== 'function') {
+    throw new Error('pd-cli pain retry registration not available');
+  }
+});
+
+registry.when(/operator 执行 "(.+)"/, async (ctx, command: string) => {
+  const argv = command.trim().split(/\s+/);
+  if (argv.shift() !== 'pd') {
+    throw new Error(`expected command to start with pd: ${command}`);
+  }
+  const painIdIndex = argv.indexOf('--pain-id');
+  const painId = painIdIndex >= 0 ? argv[painIdIndex + 1] : '';
+  resetMocksForScenario(painId);
+
+  const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+
+  try {
+    const program = new Command().name('pd').exitOverride();
+    registerPainRetryCommand(program.command('pain'));
+    await program.parseAsync(['node', 'pd', ...argv]);
+  } finally {
+    expect(exitSpy).not.toHaveBeenCalledWith(0);
+  }
+
+  const allLogCalls = logSpy.mock.calls.map((c) => String(c[0]));
+  const jsonCall = allLogCalls.find((s) => {
+    try { JSON.parse(s); return true; } catch { return false; }
+  });
+  // cli-1: 统计 stdout 上可解析为 JSON 的调用数，用于 Then 步骤验证"恰好一个"
+  const jsonCallCount = allLogCalls.filter((s) => {
+    try { JSON.parse(s); return true; } catch { return false; }
+  }).length;
+  const stdout = allLogCalls.join('\n');
+  const stderr = errorSpy.mock.calls.map((c) => String(c[0])).join('\n');
+  ctx.state.cliResult = { stdout, stderr, jsonCallCount, allLogCallCount: allLogCalls.length };
+
+  // Restore spies so Then steps don't capture new calls
+  logSpy.mockRestore();
+  errorSpy.mockRestore();
+  exitSpy.mockRestore();
+});
+
+registry.then('stdout 是严格的单一 JSON 对象', (ctx) => {
+  const result = ctx.state.cliResult as {
+    stdout: string;
+    jsonCallCount: number;
+    allLogCallCount: number;
+  };
+  const out = result.stdout.trim();
+  // Must start with { and parse as a non-null object
+  expect(out.startsWith('{')).toBe(true);
+  const parsed = JSON.parse(out);
+  expect(typeof parsed).toBe('object');
+  expect(parsed).not.toBeNull();
+  expect(result.allLogCallCount).toBe(1);
+  expect(result.jsonCallCount).toBe(1);
+});
+
+registry.then('该 JSON 对象可以被 JSON.parse 解析', (ctx) => {
+  const result = ctx.state.cliResult as { stdout: string };
+  expect(() => JSON.parse(result.stdout.trim())).not.toThrow();
+});
+
+registry.then('stdout 不包含任何 banner 或 heading', (ctx) => {
+  const result = ctx.state.cliResult as { stdout: string };
+  const out = result.stdout.trim();
+  expect(out.startsWith('===')).toBe(false);
+  expect(out.startsWith('#')).toBe(false);
+  expect(out.startsWith('PD CLI')).toBe(false);
+  expect(out.startsWith('pd ')).toBe(false);
+  // Strict JSON output must start with {
+  expect(out.startsWith('{')).toBe(true);
+});
+
+registry.then('该 JSON 对象的 status 字段表示失败', (ctx) => {
+  const result = ctx.state.cliResult as { stdout: string };
+  const parsed = JSON.parse(result.stdout.trim());
+  expect(parsed).toHaveProperty('status');
+  expect(parsed.status).not.toBe('succeeded');
+});
+
+registry.then('该 JSON 对象包含 reason 字段', (ctx) => {
+  const result = ctx.state.cliResult as { stdout: string };
+  const parsed = JSON.parse(result.stdout.trim());
+  expect(parsed).toHaveProperty('reason');
+  expect(typeof parsed.reason).toBe('string');
+  expect(parsed.reason.length).toBeGreaterThan(0);
+});
+
+registry.then('该 JSON 对象包含 nextAction 字段', (ctx) => {
+  const result = ctx.state.cliResult as { stdout: string };
+  const parsed = JSON.parse(result.stdout.trim());
+  expect(parsed).toHaveProperty('nextAction');
+  expect(typeof parsed.nextAction).toBe('string');
+  expect(parsed.nextAction.length).toBeGreaterThan(0);
+});
+
+// ── Load and register feature ──────────────────────────────────────────────────
+
+const featureText = readFileSync(
+  resolveFeaturePath('docs/specs/features/cli/json-output.feature'),
+  'utf8'
+);
+defineFeature(featureText, registry);