@principles/pd-cli 1.152.12 → 1.152.13

package/src/commands/mvp-smoke.ts

@@ -1,160 +0,0 @@
-/**
- * pd mvp smoke — MVP mainline readiness check (PRI-397 / C5).
- *
- * Assembles a MainlineSnapshot from the shared reader, judges it via the
- * pure assertMainlineContract, and outputs a single JSON verdict.
- *
- * Rules (EP-04, EP-02):
- *   - Read-only by default. NEVER mutates workspace state.
- *   - Uses the shared mainline-snapshot-assembler (no new chain logic).
- *   - --json mode: stdout = exactly one parseable JSON object — even on failure.
- *     Every degraded/refused path emits a structured `{ok, reason, nextAction}`
- *     JSON so CI/script consumers can branch on outcome (EP-04 Rule 6).
- *   - Human mode: formatted output to stdout.
- *   - Exit code: 0 on overall === 'ok', 1 on overall === 'violation' or failure.
- */
-
-import type { Command } from 'commander';
-import {
-  assembleMainlineSnapshot,
-  assertMainlineContract,
-} from '../services/mainline-snapshot-assembler.js';
-import { resolveWorkspaceDir } from '../resolve-workspace.js';
-import { withWorkspaceAndJson } from './command-helpers.js';
-
-export interface MvpSmokeOptions {
-  workspace?: string;
-  json?: boolean;
-}
-
-/**
- * Classify a thrown error so the failure JSON can name a real next action.
- * EP-03: never silently swallow; emit a structured reason + actionable next step.
- */
-function classifySmokeError(err: unknown): { reason: string; nextAction: string } {
-  if (err instanceof Error) {
-    const msg = err.message;
-    const lower = msg.toLowerCase();
-    // No .pd/state.db on disk (fresh / reset workspace) is the post-PRI-398
-    // expected first failure — name the recovery path explicitly.
-    if (
-      msg.includes('SQLITE_CANTOPEN') ||
-      lower.includes('no such file') ||
-      lower.includes('no such table') ||
-      lower.includes('cannot open database') ||
-      lower.includes('directory does not exist')
-    ) {
-      return {
-        reason: `Workspace database is missing or unreadable: ${msg}`,
-        nextAction: 'Run "pd runtime internalization integrity-repair --confirm" or restore the workspace; this command requires a bootstrapped .pd/state.db.',
-      };
-    }
-    if (lower.includes('workspace') && lower.includes('not configured')) {
-      return {
-        reason: msg,
-        nextAction: 'Set --workspace <path>, PD_WORKSPACE_DIR, or add workspace.default to .pd/config.yaml.',
-      };
-    }
-    return {
-      reason: msg,
-      nextAction: 'Inspect the workspace state and retry. Run "pd config doctor --json" to validate the workspace.',
-    };
-  }
-  return {
-    reason: `Unknown failure: ${String(err)}`,
-    nextAction: 'Inspect the workspace state and retry. Run "pd config doctor --json" to validate the workspace.',
-  };
-}
-
-export async function handleMvpSmoke(opts: MvpSmokeOptions): Promise<void> {
-  // Pass through resolveWorkspaceDir to honor the consistency warning for
-  // --workspace flags that disagree with the config default. The resolver
-  // returns an absolute, normalized path either way.
-  const workspaceDir = resolveWorkspaceDir(opts.workspace);
-
-  let result;
-  try {
-    result = await assembleMainlineSnapshot({ workspaceDir });
-  } catch (err: unknown) {
-    const { reason, nextAction } = classifySmokeError(err);
-    if (opts.json) {
-      // EP-04 Rule 1 + 6: stdout = exactly one parseable JSON object carrying
-      // a structured reason and nextAction, even on the failure path.
-      console.log(JSON.stringify({
-        ok: false,
-        reason,
-        nextAction,
-        workspace: workspaceDir,
-      }, null, 2));
-    } else {
-      console.error(`MVP smoke failed: ${reason}`);
-      console.error(`nextAction: ${nextAction}`);
-    }
-    process.exit(1);
-    return;
-  }
-
-  const verdict = assertMainlineContract(result.snapshot);
-
-  if (opts.json) {
-    console.log(JSON.stringify({
-      ok: verdict.overall === 'ok',
-      verdict,
-      warnings: result.warnings,
-      resolvedPainId: result.resolvedPainId,
-    }, null, 2));
-  } else {
-    console.log(`\nMVP Smoke — ${workspaceDir}\n`);
-    console.log(`  Overall:      ${verdict.overall}`);
-    console.log(`  Pain ID:      ${verdict.painId ?? '(none)'}`);
-    console.log(`  Generated At: ${verdict.generatedAt}\n`);
-
-    console.log('  Stages:');
-    for (const s of verdict.stages) {
-      const icon = s.status === 'ok' ? '  OK' : s.status === 'violation' ? ' VIOLATION' : ' SKIP';
-      console.log(`    [${icon}] ${s.stage}`);
-      console.log(`           ${s.reason}`);
-      if (s.nextAction) {
-        console.log(`           nextAction: ${s.nextAction}`);
-      }
-      console.log('');
-    }
-
-    if (result.warnings.length > 0) {
-      console.log('  Warnings:');
-      for (const w of result.warnings) {
-        console.log(`    - ${w}`);
-      }
-      console.log('');
-    }
-  }
-
-  if (verdict.overall === 'violation') {
-    process.exit(1);
-    return;
-  }
-}
-
-/**
- * Register the `pd mvp` parent command and its `smoke` subcommand.
- *
- * Single source of truth for both production (`index.ts`) and parser tests
- * (`mvp-smoke.test.ts`). If a test passes against this function, the same
- * registration runs in production — flag typos surface at parseAsync time.
- */
-export function registerMvpCommands(program: Command): Command {
-  const mvpCmd = program
-    .command('mvp', { hidden: true })
-    .description('MVP readiness commands');
-
-  withWorkspaceAndJson(
-    mvpCmd
-      .command('smoke')
-      .description('Check MVP mainline readiness: assemble snapshot → assert contract → structured verdict')
-      .action(async (opts: { workspace?: string; json?: boolean }) => {
-        await handleMvpSmoke({ workspace: opts.workspace, json: opts.json });
-      }),
-  );
-
-  return mvpCmd;
-}

package/src/commands/pain-evidence.ts

@@ -1,226 +0,0 @@
-/**
- * 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.
- *
- * Note: TRIGGER_DECISION entries are pain-signal admission gate decisions
- * (Gate B / TriggerController). These are distinct from GFI (General
- * Friction Index) friction events like GFI_SLICE_RESET, which track
- * session-level tool-friction resets and are NOT pain signals. This command
- * does not surface GFI events; use `pd runtime health gfi` for GFI state.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { resolveWorkspaceDir } from '../resolve-workspace.js';
-import { assertSafeDirectoryRoot, isPathInside } from '../utils/path-security.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 (canonical root).
- * SystemLogger writes to <workspace>/memory/logs/SYSTEM_YYYY-MM-DD.log.
- * The workspace root is canonicalized once here so downstream containment
- * checks compare canonical paths (relative --workspace inputs work).
- */
-function getLogDir(workspaceDir: string): string {
-  const root = assertSafeDirectoryRoot(workspaceDir, 'workspace path');
-  return path.join(root, '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;
-
-    // CWE-22: verify the canonical log path stays inside the canonical
-    // logDir before reading (canonical-vs-canonical containment, so relative
-    // workspace roots work).
-    const filePath = path.resolve(logDir, logFile);
-    if (!isPathInside(logDir, filePath)) continue;
-    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')}`);
-    // PRI-763: the historic painEvidenceAdmission flag (and its advice) was
-    // retired — it never had executable consumers; Gate B records
-    // unconditionally when the plugin runs.
-    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/pain-list.ts

@@ -1,239 +0,0 @@
-/**
- * pd pain list command — PRI-640 (Governance Signal Host Attribution v0.1)
- *
- * Read-only: lists canonical pain_events rows from trajectory.db with their
- * host attribution. `--host` filters by openclaw / codex / unknown.
- * PRI-743: the result (human and --json) also carries `byHost`, the
- * full-table host distribution independent of --host/--limit.
- *
- * Usage:
- *   pd pain list [--workspace <path>] [--limit N] [--host openclaw|codex|unknown] [--json]
- *
- * Host semantics (SPEC §6/§12): host_kind is observability metadata only.
- * NULL (legacy / manual / unprovable) is reported as `unknown` — never guessed.
- * On a pre-PRI-640 database without the host_kind column every row reports
- * `unknown` and a `host_kind_column_missing` warning is emitted (rc-9).
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { resolveWorkspaceDir } from '../resolve-workspace.js';
-
-export type PainListHostFilter = 'openclaw' | 'codex' | 'unknown';
-
-export interface PainListOptions {
-  workspace?: string;
-  limit?: number;
-  host?: string;
-  json?: boolean;
-}
-
-export interface PainListEntry {
-  /** Canonical pain identity; `row:<id>` when the legacy row has none. */
-  painId: string;
-  source: string;
-  /** 'openclaw' | 'codex' | 'unknown' — unknown covers NULL/unprovable. */
-  host: PainListHostFilter | 'unknown';
-  score: number;
-  severity: string | null;
-  createdAt: string;
-  runtimeTaskId: string | null;
-}
-
-export interface PainListResult {
-  count: number;
-  pains: PainListEntry[];
-  workspace: string;
-  hostFilter: PainListHostFilter | null;
-  /**
-   * PRI-743: full-table host distribution (independent of --limit and --host
-   * filtering) so operator tooling can group by host without an external
-   * script. `null` only on a pre-PRI-640 database without the host_kind
-   * column — the distribution is unprovable there, never guessed (rc-3/rc-9;
-   * see the accompanying host_kind_column_missing warning).
-   */
-  byHost: { openclaw: number; codex: number; unknown: number } | null;
-  warnings: string[];
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function ownField(row: unknown, key: string): unknown {
-  return isRecord(row) && Object.hasOwn(row, key) ? row[key] : undefined;
-}
-
-/** Runtime Contract #1/#4: validate each DB row; skip malformed rows loudly. */
-function toPainEntry(row: unknown): PainListEntry | null {
-  const id = ownField(row, 'id');
-  const source = ownField(row, 'source');
-  const score = ownField(row, 'score');
-  const createdAt = ownField(row, 'created_at');
-  if (typeof id !== 'number' || typeof source !== 'string' || typeof score !== 'number' || typeof createdAt !== 'string') {
-    return null;
-  }
-  const canonicalPainId = ownField(row, 'canonical_pain_id');
-  const hostKind = ownField(row, 'host_kind');
-  const severity = ownField(row, 'severity');
-  const runtimeTaskId = ownField(row, 'runtime_task_id');
-  const host: PainListEntry['host'] =
-    hostKind === 'openclaw' || hostKind === 'codex' ? hostKind : 'unknown';
-  return {
-    painId: typeof canonicalPainId === 'string' && canonicalPainId.length > 0 ? canonicalPainId : `row:${id}`,
-    source,
-    host,
-    score,
-    severity: typeof severity === 'string' ? severity : null,
-    createdAt,
-    runtimeTaskId: typeof runtimeTaskId === 'string' && runtimeTaskId.length > 0 ? runtimeTaskId : null,
-  };
-}
-
-export async function listPains(dbPath: string, options: { limit?: number; host?: PainListHostFilter } = {}): Promise<PainListResult> {
-  const Database = (await import('better-sqlite3')).default;
-  const db = new Database(dbPath, { readonly: true });
-  try {
-    const warnings: string[] = [];
-    const columns: unknown[] = db.prepare('PRAGMA table_info(pain_events)').all();
-    const hasHostKindColumn = columns.some((row) => ownField(row, 'name') === 'host_kind');
-    if (!hasHostKindColumn) {
-      warnings.push('host_kind_column_missing');
-    }
-
-    // PRI-743: full-table distribution, deliberately NOT narrowed by the
-    // --host filter or --limit below — the operator question this answers is
-    // "how do pains split across hosts in this workspace", which a filtered
-    // count cannot answer. Non-openclaw/codex values (incl. NULL) count as
-    // unknown, mirroring toPainEntry's read-side normalization.
-    const byHost: PainListResult['byHost'] = hasHostKindColumn
-      ? { openclaw: 0, codex: 0, unknown: 0 }
-      : null;
-    if (byHost) {
-      const distRows: unknown[] = db
-        .prepare("SELECT COALESCE(host_kind, 'unknown') AS host_bucket, COUNT(*) AS n FROM pain_events GROUP BY host_kind")
-        .all();
-      for (const row of distRows) {
-        const bucket = ownField(row, 'host_bucket');
-        const n = ownField(row, 'n');
-        if ((bucket === 'openclaw' || bucket === 'codex' || bucket === 'unknown') && typeof n === 'number') {
-          byHost[bucket] += n;
-        }
-      }
-    }
-
-    const params: (string | number)[] = [];
-    let query = 'SELECT id, source, score, severity, created_at, canonical_pain_id, runtime_task_id';
-    query += hasHostKindColumn ? ', host_kind' : ", NULL AS host_kind";
-    query += ' FROM pain_events WHERE 1=1';
-    if (options.host === 'unknown') {
-      query += hasHostKindColumn ? ' AND host_kind IS NULL' : '';
-    } else if (options.host === 'openclaw' || options.host === 'codex') {
-      if (!hasHostKindColumn) {
-        return { count: 0, pains: [], workspace: path.dirname(path.dirname(dbPath)), hostFilter: options.host, byHost, warnings };
-      }
-      query += ' AND host_kind = ?';
-      params.push(options.host);
-    }
-    query += ' ORDER BY created_at DESC, id DESC';
-    const limit = options.limit ?? 20;
-    query += ' LIMIT ?';
-    params.push(limit);
-
-    const rawRows: unknown[] = db.prepare(query).all(...params);
-    const skipped = rawRows.length - rawRows.map(toPainEntry).filter((entry) => entry !== null).length;
-    if (skipped > 0) {
-      warnings.push(`malformed_rows_skipped:${skipped}`);
-    }
-    const pains = rawRows
-      .map(toPainEntry)
-      .filter((entry): entry is PainListEntry => entry !== null);
-    return {
-      count: pains.length,
-      pains,
-      workspace: path.dirname(path.dirname(dbPath)),
-      hostFilter: options.host ?? null,
-      byHost,
-      warnings,
-    };
-  } finally {
-    db.close();
-  }
-}
-
-function printHuman(result: PainListResult): void {
-  const filterNote = result.hostFilter ? ` (host: ${result.hostFilter})` : '';
-  console.log(`Pain events — ${result.count} shown${filterNote}`);
-  if (result.byHost) {
-    const { openclaw, codex, unknown } = result.byHost;
-    console.log(`By host: openclaw=${openclaw} codex=${codex} unknown=${unknown}`);
-  }
-  console.log('─'.repeat(96));
-  for (const pain of result.pains) {
-    const painId = pain.painId.length > 40 ? `${pain.painId.slice(0, 37)}...` : pain.painId;
-    console.log(`  ${pain.createdAt}  host=${pain.host.padEnd(8)} score=${String(pain.score).padEnd(3)} ${pain.severity ?? '-'.padEnd(6)} ${pain.source}`);
-    console.log(`    id: ${painId}${pain.runtimeTaskId ? ` | task: ${pain.runtimeTaskId}` : ''}`);
-  }
-  console.log('─'.repeat(96));
-  for (const warning of result.warnings) {
-    console.error(`WARN: ${warning}`);
-  }
-  if (result.warnings.includes('host_kind_column_missing')) {
-    console.error('Next: run `pd runtime init --workspace <dir>` (or restart the OpenClaw plugin) to migrate this workspace schema.');
-  }
-}
-
-export async function handlePainList(opts: PainListOptions): Promise<void> {
-  const { workspace, limit: rawLimit, host: rawHost, json } = opts;
-
-  if (rawHost !== undefined && rawHost !== 'openclaw' && rawHost !== 'codex' && rawHost !== 'unknown') {
-    const message = `invalid host filter: expected openclaw | codex | unknown, got ${rawHost}`;
-    if (json) {
-      console.log(JSON.stringify({ status: 'failed', reason: 'invalid_host_filter', message, nextAction: 'Pass --host openclaw, --host codex, or --host unknown.' }));
-    } else {
-      console.error('Error: ' + message);
-      console.error('Next: Pass --host openclaw, --host codex, or --host unknown.');
-    }
-    process.exit(1);
-    return; // guard: test stubs of process.exit continue execution (cli-2-exit-stops)
-  }
-  const hostFilter: PainListHostFilter | undefined = rawHost;
-
-  let effectiveLimit = 20;
-  if (rawLimit !== undefined) {
-    if (!Number.isInteger(rawLimit) || rawLimit < 1 || rawLimit > 10000) {
-      const message = `invalid limit: limit must be an integer between 1 and 10000, got ${rawLimit}`;
-      if (json) {
-        console.log(JSON.stringify({ status: 'failed', reason: 'invalid_limit', message, nextAction: 'Pass --limit with a valid integer (1-10000).' }));
-      } else {
-        console.error('Error: ' + message);
-        console.error('Next: Pass --limit with a valid integer (1-10000).');
-      }
-      process.exit(1);
-      return; // guard: test stubs of process.exit continue execution (cli-2-exit-stops)
-    }
-    effectiveLimit = rawLimit;
-  }
-
-  const workspaceDir = resolveWorkspaceDir(workspace);
-  const dbPath = path.join(workspaceDir, '.state', 'trajectory.db');
-  if (!fs.existsSync(dbPath)) {
-    const message = `trajectory database not found at ${dbPath}`;
-    if (json) {
-      console.log(JSON.stringify({ status: 'failed', reason: 'trajectory_db_not_found', message, nextAction: 'Initialize the PD workspace first (pd runtime init), or pass --workspace pointing at an initialized workspace.' }));
-    } else {
-      console.error('Error: ' + message);
-      console.error('Next: Initialize the PD workspace first (pd runtime init), or pass --workspace pointing at an initialized workspace.');
-    }
-    process.exit(1);
-    return; // guard: test stubs of process.exit continue execution (cli-2-exit-stops)
-  }
-
-  const result = await listPains(dbPath, { limit: effectiveLimit, ...(hostFilter ? { host: hostFilter } : {}) });
-
-  if (json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  printHuman(result);
-}