@principles/pd-cli 1.83.0 → 1.84.0

package/dist/utils/production-workspace-guard.js

@@ -0,0 +1,170 @@
+/**
+ * Production Workspace Guard
+ *
+ * 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
+ *
+ * This module follows ERR-030 (path prefix matching must use segment boundaries)
+ * and EP-03/EP-04 (fail loud with structured reason and nextAction).
+ */
+import * as path from 'path';
+import * as os from 'os';
+import { existsSync } from 'fs';
+// ── Production workspace paths ─────────────────────────────────────────────────
+/**
+ * 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.
+ */
+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')),
+];
+// ── Resolution helpers ───────────────────────────────────────────────────────
+/**
+ * Resolve the workspace path from environment variable or current directory.
+ */
+export function resolveWorkspacePath(inputPath) {
+    if (!inputPath) {
+        // Default to current directory
+        return path.resolve(process.cwd());
+    }
+    return path.resolve(inputPath);
+}
+/**
+ * Check if a path is a production workspace.
+ *
+ * This follows ERR-030: path matching must use segment boundaries (path.sep)
+ * to avoid false positives on sibling directories like "workspace-backup".
+ *
+ * @param resolvedPath - The absolute, normalized workspace path to check
+ * @returns true if the path is a production workspace
+ */
+export function isProductionWorkspace(resolvedPath) {
+    const normalized = resolvedPath.toLowerCase();
+    for (const prodPath of PRODUCTION_WORKSPACE_PATHS) {
+        const normalizedProd = prodPath.toLowerCase();
+        // Exact match
+        if (normalized === normalizedProd) {
+            return true;
+        }
+        // Descendant match: must have path separator after prefix
+        // ERR-030: "startsWith" without separator matches sibling directories
+        if (normalized.startsWith(normalizedProd + path.sep)) {
+            return true;
+        }
+        // Handle Windows path variations
+        // D:\.openclaw\workspace should not match D:\.openclaw\workspace-backup
+        // Use case-insensitive comparison (already normalized)
+        if (path.sep === '\\') {
+            // Windows: check both forward and backslash
+            if (normalized.startsWith(normalizedProd + '/')) {
+                return true;
+            }
+            if (normalized.startsWith(normalizedProd.replace(/\\/g, '/') + '/')) {
+                return true;
+            }
+            if (normalized.startsWith(normalizedProd.replace(/\\/g, '/') + '\\')) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Check if a workspace is protected from UAT/test writes.
+ *
+ * This is the main guard function for UAT/runtime test commands.
+ * It returns a structured result following EP-03/EP-04 requirements.
+ *
+ * @param inputPath - The workspace path to check (optional, resolves to cwd if not provided)
+ * @param commandContext - Context string for the error message (e.g., "pd runtime uat")
+ * @returns GuardResult indicating if the operation is allowed or refused
+ */
+export function guardUatWorkspace(inputPath, _commandContext) {
+    const resolved = resolveWorkspacePath(inputPath);
+    // PRI-334: Guard check should happen BEFORE file existence check
+    // This prevents production workspace writes even if directory doesn't exist yet
+    if (isProductionWorkspace(resolved)) {
+        return {
+            refused: true,
+            workspace: resolved,
+            isProduction: true,
+            reason: `UAT/runtime test commands are not allowed to write to the production workspace (${resolved}). This prevents test/synthetic data from polluting your real PD state.`,
+            nextAction: `Use a temporary workspace for testing (recommended: ${os.tmpdir()}/pd-uat-workspace) or explicitly confirm you understand the risk by using --allow-production-workspace-for-uat (not recommended).`,
+        };
+    }
+    if (!existsSync(resolved)) {
+        // Non-existent workspace is safe to use (will be created)
+        return {
+            refused: false,
+            workspace: resolved,
+            isProduction: false,
+        };
+    }
+    return {
+        refused: false,
+        workspace: resolved,
+        isProduction: false,
+    };
+}
+/**
+ * Get a safe UAT workspace path in the system temp directory.
+ *
+ * This follows the safe execution path requirement from PRI-334.
+ */
+export function getSafeUatWorkspacePath() {
+    const tempDir = os.tmpdir();
+    // Create a unique but deterministic path for UAT workspaces
+    const uatWorkspace = path.join(tempDir, 'pd-uat-workspace');
+    return uatWorkspace;
+}
+/**
+ * Check if --allow-production-workspace-for-uat flag is set.
+ *
+ * This is the escape hatch for cases where the operator explicitly wants to run UAT on production.
+ * The flag must be very explicit in both name and output (as required by PRI-334).
+ */
+export function isProductionWorkspaceAllowed() {
+    // Check if the flag was parsed and passed through opts
+    // This will be called from command handlers after Commander parses flags
+    return false; // Placeholder; actual check depends on Commander opts
+}
+/**
+ * Format guard refusal for console output.
+ *
+ * Follows EP-03/EP-04: structured reason + nextAction.
+ */
+export function formatGuardRefusal(refusal, commandContext, jsonMode = false) {
+    if (jsonMode) {
+        // JSON mode: output exactly one JSON object with reason and nextAction
+        return JSON.stringify({
+            status: 'refused',
+            reason: refusal.reason,
+            nextAction: refusal.nextAction,
+            workspace: refusal.workspace,
+            isProduction: refusal.isProduction,
+        }, null, 2);
+    }
+    // Text mode: human-readable structured output
+    return [
+        `[pd-cli] ERROR: ${commandContext} - workspace guard triggered`,
+        '',
+        `Reason: ${refusal.reason}`,
+        `Next Action: ${refusal.nextAction}`,
+        `Workspace: ${refusal.workspace}`,
+        '',
+        'This guard prevents UAT/runtime test data from polluting your production workspace.',
+    ].join('\n');
+}
+//# sourceMappingURL=production-workspace-guard.js.map

package/dist/utils/production-workspace-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-workspace-guard.js","sourceRoot":"","sources":["../../src/utils/production-workspace-guard.ts"],"names":[],"mappings":"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"}

package/dist/utils/production-workspace-guard.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=production-workspace-guard.test.d.ts.map

package/dist/utils/production-workspace-guard.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-workspace-guard.test.d.ts","sourceRoot":"","sources":["../../src/utils/production-workspace-guard.test.ts"],"names":[],"mappings":""}

package/dist/utils/production-workspace-guard.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import * as path from 'path';
+import * as os from 'os';
+import { isProductionWorkspace, guardUatWorkspace, getSafeUatWorkspacePath, formatGuardRefusal, } from './production-workspace-guard.js';
+const PRODUCTION_PATHS = [
+    'D:\\.openclaw\\workspace',
+    'C:\\.openclaw\\workspace',
+    'C:\\Users\\Administrator\\.openclaw\\workspace',
+    path.join(os.homedir(), '.openclaw', 'workspace'),
+];
+const SAFE_PATHS = [
+    'D:\\.openclaw\\workspace-test',
+    'D:\\.openclaw\\workspace-backup',
+    path.join(os.tmpdir(), 'pd-uat-workspace'),
+    path.join(os.tmpdir(), 'pd-test-any'),
+    'C:\\completely-unrelated\\work',
+];
+describe('isProductionWorkspace', () => {
+    it.each(PRODUCTION_PATHS)('detects production: %s', (prodPath) => {
+        expect(isProductionWorkspace(path.resolve(prodPath))).toBe(true);
+    });
+    it.each(SAFE_PATHS)('allows safe: %s', (safePath) => {
+        expect(isProductionWorkspace(path.resolve(safePath))).toBe(false);
+    });
+    it('detects descendant', () => {
+        expect(isProductionWorkspace(path.resolve('D:\\.openclaw\\workspace\\sub\\child'))).toBe(true);
+    });
+    it('rejects sibling workspace-test (ERR-030)', () => {
+        expect(isProductionWorkspace(path.resolve('D:\\.openclaw\\workspace-test'))).toBe(false);
+    });
+    it('rejects sibling workspace-backup (ERR-030)', () => {
+        expect(isProductionWorkspace(path.resolve('D:\\.openclaw\\workspace-backup'))).toBe(false);
+    });
+});
+describe('guardUatWorkspace', () => {
+    describe('refused', () => {
+        it.each(PRODUCTION_PATHS)('refuses production: %s', (prodPath) => {
+            const r = guardUatWorkspace(prodPath, 'test');
+            expect(r.refused).toBe(true);
+            if (r.refused) {
+                expect(r.reason).toContain('UAT/runtime test commands are not allowed');
+                expect(r.nextAction).toContain('temporary workspace');
+            }
+        });
+        it('refuses descendant', () => {
+            expect(guardUatWorkspace('D:\\.openclaw\\workspace\\subdir', 'test').refused).toBe(true);
+        });
+    });
+    describe('allowed', () => {
+        it.each(SAFE_PATHS)('allows safe: %s', (safePath) => {
+            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) => {
+            expect(guardUatWorkspace(p, 'test').refused).toBe(false);
+        });
+    });
+});
+describe('JSON output (EP-04)', () => {
+    it('outputs single object with reason and nextAction', () => {
+        const r = guardUatWorkspace('D:\\.openclaw\\workspace', 'test');
+        const json = formatGuardRefusal(r, 'test', true);
+        const parsed = JSON.parse(json);
+        expect(parsed).toMatchObject({
+            status: 'refused', reason: expect.any(String), nextAction: expect.any(String),
+            workspace: expect.any(String), isProduction: true,
+        });
+        expect(Array.isArray(parsed)).toBe(false);
+    });
+    it('no console prefixes in JSON', () => {
+        const r = guardUatWorkspace('D:\\.openclaw\\workspace', 'test');
+        const json = formatGuardRefusal(r, 'test', true);
+        expect(json).not.toContain('[pd-cli]');
+        expect(json).not.toContain('ERROR:');
+        expect(json.trim().startsWith('{')).toBe(true);
+    });
+});
+describe('text output (EP-03)', () => {
+    it('includes reason and nextAction', () => {
+        const r = guardUatWorkspace('D:\\.openclaw\\workspace', 'test');
+        const text = formatGuardRefusal(r, 'test', false);
+        expect(text).toContain('Reason:');
+        expect(text).toContain('Next Action:');
+    });
+});
+describe('getSafeUatWorkspacePath', () => {
+    it('returns deterministic temp path', () => {
+        const p1 = getSafeUatWorkspacePath();
+        const p2 = getSafeUatWorkspacePath();
+        expect(p1).toBe(p2);
+        expect(p1).toContain(os.tmpdir());
+        expect(p1).toContain('pd-uat-workspace');
+    });
+});
+//# sourceMappingURL=production-workspace-guard.test.js.map

package/dist/utils/production-workspace-guard.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-workspace-guard.test.js","sourceRoot":"","sources":["../../src/utils/production-workspace-guard.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/pd-cli",
-  "version": "1.83.0",
+  "version": "1.84.0",
   "description": "PD CLI — Pain recording, sample management, and evolution tasks",
   "type": "module",
   "bin": {

package/src/commands/runtime-uat.guard.test.ts

@@ -0,0 +1,177 @@
+/**
+ * PRI-334: Runtime UAT guard — command-level integration tests.
+ *
+ * These tests verify the guard is wired into the real Commander command
+ * and that refused paths do NOT call execFileSync (mutation prevention).
+ */
+import { describe, it, expect, vi, beforeEach, afterAll, beforeAll } from 'vitest';
+import { Command } from 'commander';
+import * as path from 'path';
+import * as os from 'os';
+
+// ─── Mocks ─────────────────────────────────────────────────────────────────
+const mockExecFileSync = vi.fn();
+vi.mock('child_process', () => ({
+  execFileSync: mockExecFileSync,
+}));
+
+const { handleRuntimeUat } = await import('./runtime-uat.js');
+const { guardUatWorkspace } = await import('../utils/production-workspace-guard.js');
+
+// ─── Test Setup ─────────────────────────────────────────────────────────────
+const capturedStderr: string[] = [];
+const capturedStdout: string[] = [];
+let capturedExitCode: number | null = null;
+
+const originalExit = process.exit;
+const originalError = console.error;
+const originalLog = console.log;
+const originalEnv = { ...process.env };
+
+beforeAll(() => {
+  process.exit = vi.fn(((code?: number) => {
+    capturedExitCode = code ?? 0;
+  }) as typeof process.exit);
+  console.error = vi.fn((...args: unknown[]) => { capturedStderr.push(args.join(' ')); });
+  console.log = vi.fn((...args: unknown[]) => { capturedStdout.push(args.join(' ')); });
+});
+
+afterAll(() => {
+  process.exit = originalExit;
+  console.error = originalError;
+  console.log = originalLog;
+  process.env = originalEnv;
+});
+
+beforeEach(() => {
+  capturedExitCode = null;
+  capturedStderr.length = 0;
+  capturedStdout.length = 0;
+  mockExecFileSync.mockReset();
+  process.env = { ...process.env, MINIMAX_CN_API_KEY: 'test-key-for-pri-334' };
+});
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+describe('PRI-334: production workspace refusal', () => {
+  it('refuses D: workspace with exit code 1', async () => {
+    mockExecFileSync.mockClear();
+    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace', count: 1 });
+    expect(capturedExitCode).toBe(1);
+    expect(mockExecFileSync).not.toHaveBeenCalled();
+  });
+
+  it('refuses C: workspace with exit code 1', async () => {
+    mockExecFileSync.mockClear();
+    await handleRuntimeUat({ workspace: 'C:\\.openclaw\\workspace', count: 1 });
+    expect(capturedExitCode).toBe(1);
+    expect(mockExecFileSync).not.toHaveBeenCalled();
+  });
+
+  it('refuses production workspace subdirectory', async () => {
+    mockExecFileSync.mockClear();
+    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace\\sub\\path', count: 1 });
+    expect(capturedExitCode).toBe(1);
+    expect(mockExecFileSync).not.toHaveBeenCalled();
+  });
+});
+
+describe('PRI-334: allowed paths (guard level)', () => {
+  it('allows temp workspace', () => {
+    const tempPath = path.join(os.tmpdir(), 'pd-test-' + Date.now());
+    expect(guardUatWorkspace(tempPath, 'test').refused).toBe(false);
+  });
+
+  it('allows workspace-test sibling (ERR-030)', () => {
+    expect(guardUatWorkspace('D:\\.openclaw\\workspace-test', 'test').refused).toBe(false);
+  });
+
+  it('allows workspace-backup sibling (ERR-030)', () => {
+    expect(guardUatWorkspace('D:\\.openclaw\\workspace-backup', 'test').refused).toBe(false);
+  });
+});
+
+describe('PRI-334: JSON output (EP-04)', () => {
+  it('outputs single JSON object with reason and nextAction', async () => {
+    mockExecFileSync.mockClear();
+    capturedStdout.length = 0;
+    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace', count: 1, json: true });
+    expect(capturedExitCode).toBe(1);
+    expect(mockExecFileSync).not.toHaveBeenCalled();
+
+    const jsonOutput = capturedStdout.join('');
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed).toMatchObject({
+      status: 'refused', reason: expect.any(String), nextAction: expect.any(String),
+      workspace: expect.any(String), isProduction: true,
+    });
+    expect(Array.isArray(parsed)).toBe(false);
+  });
+});
+
+describe('PRI-334: escape hatch', () => {
+  it('warns when allow-production-workspace-for-uat flag is set', async () => {
+    mockExecFileSync.mockClear();
+    mockExecFileSync.mockImplementation(() => '{"painId":"test","taskId":"t1","runId":"r1","candidateIds":["c1"],"ledgerEntryIds":["l1"]}');
+    capturedStderr.length = 0;
+    capturedExitCode = null;
+
+    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace', count: 1, allowProductionWorkspaceForUat: true });
+    const stderrText = capturedStderr.join('\n');
+    expect(stderrText).toContain('WARNING');
+    expect(stderrText).toContain('--allow-production-workspace-for-uat');
+  });
+});
+
+describe('PRI-334: mutation prevention', () => {
+  it('does not call execFileSync after guard refusal', async () => {
+    mockExecFileSync.mockClear();
+    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace', count: 1 });
+    expect(mockExecFileSync).not.toHaveBeenCalled();
+  });
+});
+
+describe('PRI-334: Commander flag wiring (ERR-063)', () => {
+  it('parses --allow-production-workspace-for-uat', () => {
+    const program = new Command();
+    const rt = program.command('runtime');
+    rt.command('uat')
+      .option('--allow-production-workspace-for-uat', 'Escape hatch')
+      .action(() => { /* noop */ });
+    const cmd = rt.commands.find((c) => c.name() === 'uat') as Command;
+    const opt = cmd.options.find((o) => o.long === '--allow-production-workspace-for-uat');
+    expect(opt).toBeDefined();
+    expect(opt?.long).toBe('--allow-production-workspace-for-uat');
+  });
+
+  it('negated form is NOT registered', () => {
+    const program = new Command();
+    const rt = program.command('runtime');
+    rt.command('uat')
+      .option('--allow-production-workspace-for-uat', 'Escape hatch')
+      .action(() => { /* noop */ });
+    const cmd = rt.commands.find((c) => c.name() === 'uat') as Command;
+    const noForm = cmd.options.find((o) => o.long === '--no-allow-production-workspace-for-uat');
+    expect(noForm).toBeUndefined();
+  });
+});
+
+describe('PRI-334: shouldExitWithError exit path (EP-04)', () => {
+  it('exits 1 and does not print ALL CHECKS PASSED when shouldExitWithError is true', async () => {
+    const tempWorkspace = path.join(os.tmpdir(), 'pd-exit-test-' + Date.now());
+    mockExecFileSync.mockClear();
+    // Make all iterations fail (execFileSync throws) so shouldExitWithError returns true
+    mockExecFileSync.mockRejectedValue(new Error('simulated failure'));
+    capturedStderr.length = 0;
+    capturedExitCode = null;
+
+    await handleRuntimeUat({
+      workspace: tempWorkspace,
+      count: 1,
+      minSuccessRate: 1.0,
+    });
+
+    expect(capturedExitCode).toBe(1);
+    const stderrText = capturedStderr.join('\n');
+    expect(stderrText).not.toContain('ALL CHECKS PASSED');
+  });
+});

package/src/commands/runtime-uat.ts

@@ -17,6 +17,12 @@ import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'node:url';
 import * as path from 'path';
 import * as fs from 'fs';
+import {
+  guardUatWorkspace,
+  formatGuardRefusal,
+  type GuardResult,
+  type GuardRefusal,
+} from '../utils/production-workspace-guard.js';
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -25,6 +31,7 @@ interface UatOptions {
   count?: number;
   minSuccessRate?: number;
   json?: boolean;
+  allowProductionWorkspaceForUat?: boolean;
 }
 
 interface PainRecordResult {
@@ -73,6 +80,8 @@ export function parseUatArgs(argv: string[]): UatOptions {
     } else if (argv[i] === '--min-success-rate') {
       const rate = parseFloat(argv[++i] ?? '1.0');
       args.minSuccessRate = isNaN(rate) ? 1.0 : rate;
+    } else if (argv[i] === '--allow-production-workspace-for-uat') {
+      args.allowProductionWorkspaceForUat = true;
     }
   }
   return args;
@@ -153,8 +162,6 @@ interface IterationConfig {
 export function runUatIteration(config: IterationConfig): PainRecordResult {
   const { iteration, reason, workspace, timeoutMs = 300_000 } = config;
   const iterStart = Date.now();
-
-  // eslint-disable-next-line @typescript-eslint/init-declarations
   let recordOutput: string;
   try {
     recordOutput = pd(['pain', 'record', '--reason', reason, '--score', '85', '--source', 'manual', '--json'], workspace, timeoutMs);
@@ -173,7 +180,6 @@ export function runUatIteration(config: IterationConfig): PainRecordResult {
   }
 
   const wallTimeMs = Date.now() - iterStart;
-  // eslint-disable-next-line @typescript-eslint/init-declarations
   let parsed: Record<string, unknown>;
   try {
     parsed = parseJsonOutput(recordOutput) as Record<string, unknown>;
@@ -190,7 +196,6 @@ export function runUatIteration(config: IterationConfig): PainRecordResult {
     };
   }
 
-  // eslint-disable-next-line @typescript-eslint/init-declarations
   let auditStatus: string;
   try {
     const auditOut = pd(['candidate', 'audit', '--json'], workspace, 30_000);
@@ -276,6 +281,37 @@ export async function handleRuntimeUat(opts: UatOptions): Promise<void> {
   if (!workspace) {
     console.error('Error: --workspace <path> is required');
     process.exit(1);
+    return;
+  }
+
+  // PRI-334: Guard against writing to production workspace
+  const guardResult: GuardResult = guardUatWorkspace(workspace, 'pd runtime uat');
+
+  if (guardResult.refused && !opts.allowProductionWorkspaceForUat) {
+    // Fail loud with structured reason and nextAction (EP-03/EP-04)
+    const refused: GuardRefusal = guardResult;
+    const refusalOutput = formatGuardRefusal(
+      refused,
+      'pd runtime uat',
+      !!opts.json
+    );
+
+    if (opts.json) {
+      console.log(refusalOutput);
+    } else {
+      console.error(refusalOutput);
+    }
+
+    process.exit(1);
+    return;
+  }
+
+  if (guardResult.refused && opts.allowProductionWorkspaceForUat) {
+    // Escape hatch used: warn but allow
+    console.error('[pd-cli] WARNING: --allow-production-workspace-for-uat is set.');
+    console.error('  Test/synthetic data will be written to your production workspace.');
+    console.error('  This is not recommended and may pollute your real PD state.');
+    console.error('');
   }
 
   console.error(`[${new Date().toISOString()}] Runtime V2 Chain UAT — workspace: ${workspace}, count: ${count}`);
@@ -284,6 +320,7 @@ export async function handleRuntimeUat(opts: UatOptions): Promise<void> {
   if (!process.env.MINIMAX_CN_API_KEY) {
     console.error('Error: MINIMAX_CN_API_KEY environment variable not set');
     process.exit(1);
+    return;
   }
 
   const results: PainRecordResult[] = [];
@@ -332,6 +369,7 @@ export async function handleRuntimeUat(opts: UatOptions): Promise<void> {
     console.error(`FAIL: successRate=${summary.successRate} (threshold: ${minSuccessRate}) ` +
       `ledger=${summary.ledgerConsistencyOk} candidates=${summary.allHaveCandidates} ledger=${summary.allHaveLedger}`);
     process.exit(1);
+    return;
   }
 
   console.error('');

package/src/index.ts

@@ -475,12 +475,14 @@ runtimeCmd
   .option('--count <n>', 'Number of iterations (default: 5, max: 50)', parseInt)
   .option('--min-success-rate <rate>', 'Minimum success rate threshold (default: 1.0)', parseFloat)
   .option('--json', 'Output machine-readable JSON summary')
+  .option('--allow-production-workspace-for-uat', 'DANGEROUS: Allow UAT to write to production workspace (NOT RECOMMENDED)')
   .action(async (opts) => {
     await handleRuntimeUat({
       workspace: opts.workspace,
       count: opts.count,
       minSuccessRate: opts.minSuccessRate,
       json: opts.json,
+      allowProductionWorkspaceForUat: opts.allowProductionWorkspaceForUat,
     });
   });