@principles/pd-cli 1.83.0 → 1.85.0

package/src/commands/pain-evidence.ts

@@ -0,0 +1,210 @@
+/**
+ * pd pain evidence command — PEAT-B2
+ *
+ * Query recent admission/trigger decisions from PD logs.
+ * This is a read-only diagnostic command — no side effects.
+ *
+ * Usage:
+ *   pd pain evidence [--workspace <path>] [--limit N] [--json]
+ *
+ * Shows the most recent TRIGGER_DECISION log entries.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface EvidenceOptions {
+  workspace?: string;
+  limit?: number;
+  json?: boolean;
+}
+
+interface TriggerDecisionEntry {
+  timestamp: string;
+  outcome: string;
+  sourceKind: string;
+  reason: string;
+  nextAction: string;
+  tool?: string;
+  path?: string;
+  painId?: string;
+  score?: number;
+  sessionId?: string;
+}
+
+/**
+ * Get the memory/logs directory for a workspace.
+ * SystemLogger writes to <workspace>/memory/logs/SYSTEM_YYYY-MM-DD.log.
+ */
+function getLogDir(workspaceDir: string): string {
+  return path.join(workspaceDir, 'memory', 'logs');
+}
+
+/**
+ * Parse TRIGGER_DECISION entries from a log file.
+ * Returns entries in reverse chronological order (newest first).
+ */
+function parseTriggerDecisions(logContent: string): TriggerDecisionEntry[] {
+  const entries: TriggerDecisionEntry[] = [];
+  const lines = logContent.split('\n');
+
+  for (const line of lines) {
+    if (!line.includes('TRIGGER_DECISION')) continue;
+
+    // Extract JSON payload from log line
+    const jsonStart = line.indexOf('{');
+    if (jsonStart === -1) continue;
+
+    try {
+      const payload = JSON.parse(line.slice(jsonStart));
+      // Extract timestamp from log line prefix.
+      // SystemLogger produces two formats:
+      //   - Plain:    "2026-06-08 10:16:00 [INFO] ..."
+      //   - Bracketed ISO: "[2026-06-08T10:16:00.123Z] [INFO] ..."
+      const tsMatch = /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})/.exec(line)
+        ?? /^\[(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)\]/.exec(line);
+      entries.push({
+        timestamp: tsMatch?.[1] ?? new Date().toISOString(),
+        outcome: typeof payload.outcome === 'string' ? payload.outcome : 'unknown',
+        sourceKind: typeof payload.sourceKind === 'string' ? payload.sourceKind : 'unknown',
+        reason: typeof payload.reason === 'string' ? payload.reason : '',
+        nextAction: typeof payload.nextAction === 'string' ? payload.nextAction : '',
+        tool: typeof payload.tool === 'string' ? payload.tool : undefined,
+        path: typeof payload.path === 'string' ? payload.path : undefined,
+        painId: typeof payload.painId === 'string' ? payload.painId : undefined,
+        score: typeof payload.score === 'number' ? payload.score : undefined,
+        sessionId: typeof payload.sessionId === 'string' ? payload.sessionId : undefined,
+      });
+    } catch (e) {
+      // Skip malformed entries — always log for operator visibility (EP-03)
+      console.error(`WARN: Malformed TRIGGER_DECISION entry: ${String(e).slice(0, 100)}`);
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Read recent trigger decisions from memory/logs files.
+ * SystemLogger writes date-stamped files: SYSTEM_YYYY-MM-DD.log.
+ */
+function readRecentDecisions(logDir: string, limit: number): TriggerDecisionEntry[] {
+  if (!fs.existsSync(logDir)) return [];
+
+  const logFiles = fs.readdirSync(logDir)
+    .filter(f => f.startsWith('SYSTEM_') && f.endsWith('.log'))
+    .sort()
+    .reverse(); // newest first
+
+  const allEntries: TriggerDecisionEntry[] = [];
+
+  for (const logFile of logFiles) {
+    if (allEntries.length >= limit) break;
+
+    const filePath = path.join(logDir, logFile);
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const entries = parseTriggerDecisions(content);
+      // Reverse per-file entries so combined list is newest-first.
+      // Log files are already sorted newest-first, but entries within
+      // each file are in chronological (oldest-first) order.
+      allEntries.push(...entries.reverse());
+    } catch (e) {
+      // Skip unreadable files — always log for operator visibility (EP-03)
+      console.error(`WARN: Could not read log file ${logFile}: ${String(e).slice(0, 100)}`);
+    }
+  }
+
+  return allEntries.slice(0, limit);
+}
+
+function getOutcomeEmoji(outcome: string): string {
+  switch (outcome) {
+    case 'diagnosis_created': return '🔧';
+    case 'manual_owner_admitted': return '✅';
+    case 'evidence_only': return '📋';
+    case 'health_only': return '💚';
+    case 'cooldown_skipped': return '⏳';
+    case 'owner_confirm_required': return '❓';
+    case 'refused': return '🚫';
+    default: return '❔';
+  }
+}
+
+function truncate(s: string, maxLen: number): string {
+  if (s.length <= maxLen) return s;
+  return s.slice(0, maxLen - 3) + '...';
+}
+
+export async function handlePainEvidence(opts: EvidenceOptions): Promise<void> {
+  const { workspace, limit: rawLimit, json } = opts;
+  const workspaceDir = resolveWorkspaceDir(workspace);
+  const logDir = getLogDir(workspaceDir);
+
+  // Validate limit — fail loud for invalid values
+  let effectiveLimit = 20;
+  if (rawLimit !== undefined) {
+    if (!Number.isInteger(rawLimit) || rawLimit < 1 || rawLimit > 10000) {
+      const err = {
+        status: 'refused',
+        reason: `invalid_limit: limit must be an integer between 1 and 10000, got ${rawLimit}`,
+        nextAction: 'Pass --limit with a valid integer (1-10000)',
+      };
+      const { reason, nextAction } = err;
+      if (json) {
+        console.log(JSON.stringify({ count: 0, error: err }));
+      } else {
+        console.error('Error: ' + reason);
+        console.error('Next: ' + nextAction);
+      }
+      process.exit(1);
+      return; // guard: test stubs of process.exit continue execution
+    }
+    effectiveLimit = rawLimit;
+  }
+
+  const decisions = readRecentDecisions(logDir, effectiveLimit);
+
+  if (json) {
+    console.log(JSON.stringify({ count: decisions.length, decisions, searchedPath: path.join(logDir, 'SYSTEM_*.log') }, null, 2));
+    return;
+  }
+
+  if (decisions.length === 0) {
+    console.log('No trigger decisions found in logs.');
+    console.log(`Searched: ${path.join(logDir, 'SYSTEM_*.log')}`);
+    console.log('Tip: Enable painEvidenceAdmission feature flag to start recording trigger decisions.');
+    return;
+  }
+
+  console.log(`Recent Pain Evidence Admission Decisions (${decisions.length}):`);
+  console.log('─'.repeat(80));
+
+  for (const d of decisions) {
+    const outcomeEmoji = getOutcomeEmoji(d.outcome);
+    console.log(`  ${outcomeEmoji} [${d.timestamp}] ${d.outcome}`);
+    console.log(`    Source: ${d.sourceKind} | Score: ${d.score ?? 'N/A'}`);
+    console.log(`    Reason: ${truncate(d.reason, 100)}`);
+    if (d.nextAction && d.nextAction !== 'none') {
+      console.log(`    Next: ${truncate(d.nextAction, 80)}`);
+    }
+    if (d.tool) console.log(`    Tool: ${d.tool} | Path: ${d.path ?? 'N/A'}`);
+    console.log();
+  }
+
+  // Summary
+  const byOutcome = new Map<string, number>();
+  for (const d of decisions) {
+    byOutcome.set(d.outcome, (byOutcome.get(d.outcome) ?? 0) + 1);
+  }
+  console.log('─'.repeat(80));
+  console.log('Summary:');
+  for (const [outcome, count] of byOutcome) {
+    console.log(`  ${getOutcomeEmoji(outcome)} ${outcome}: ${count}`);
+  }
+}
+
+// Export for testing
+// istanbul ignore next
+export { parseTriggerDecisions, getLogDir };

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

@@ -9,6 +9,7 @@
 import { Command } from 'commander';
 import { handlePainRecord } from './commands/pain-record.js';
 import { handlePainRetry } from './commands/pain-retry.js';
+import { handlePainEvidence } from './commands/pain-evidence.js';
 import { handleSamplesList } from './commands/samples-list.js';
 import { handleSamplesReview } from './commands/samples-review.js';
 import { handleEvolutionTasksList } from './commands/evolution-tasks-list.js';
@@ -98,6 +99,16 @@ painCmd
     await handlePainRetry(opts);
   });
 
+painCmd
+  .command('evidence')
+  .description('Show recent pain admission/trigger decisions (PEAT-B2)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('-l, --limit <number>', 'Max entries to show (default: 20)', parseInt)
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    await handlePainEvidence(opts);
+  });
+
 const samplesCmd = program
   .command('samples')
   .description('Correction sample management');
@@ -475,12 +486,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,
     });
   });
 

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

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  isProductionWorkspace,
+  guardUatWorkspace,
+  getSafeUatWorkspacePath,
+  formatGuardRefusal,
+  type GuardRefusal,
+} 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 as GuardRefusal, '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 as GuardRefusal, '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 as GuardRefusal, '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');
+  });
+});