@principles/pd-cli 1.144.0 → 1.145.1

package/src/commands/pain-list.ts

@@ -0,0 +1,203 @@
+/**
+ * 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.
+ *
+ * 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;
+  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');
+    }
+
+    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, 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,
+      warnings,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+function printHuman(result: PainListResult): void {
+  const filterNote = result.hostFilter ? ` (host: ${result.hostFilter})` : '';
+  console.log(`Pain events — ${result.count} shown${filterNote}`);
+  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);
+}

package/src/commands/runtime-init.ts

@@ -95,12 +95,23 @@ const DB_NAMES = {
  */
 function buildConfigYaml(workspaceDir: string): string {
   const config = getDefaultPdConfig();
+  // PRI-637: `pd runtime init` is PD machinery writing a bootstrap snapshot, so
+  // every flag entry records `source: 'system'` — an ORIGIN HINT, NOT proof that
+  // the value lacks Owner intent (direct .pd/config.yaml editing is a supported
+  // path; an Owner may later pin behavior on top of this entry). Labels are
+  // metadata only; effective values are unchanged. If a flag graduates, system-
+  // origin entries are cleanup CANDIDATES that still require explicit Owner
+  // confirmation before removal.
+  const features: Record<string, unknown> = {};
+  for (const [id, entry] of Object.entries(config.features)) {
+    features[id] = { category: entry.category, enabled: entry.enabled, source: 'system' };
+  }
   const yamlObj: Record<string, unknown> = {
     version: config.version,
     workspace: {
       default: workspaceDir,
     },
-    features: config.features,
+    features,
     runtimeProfiles: config.runtimeProfiles,
     internalAgents: config.internalAgents,
     ui: config.ui,

package/src/index.ts

@@ -10,6 +10,7 @@ import { Command } from 'commander';
 import { handlePainRecord } from './commands/pain-record.js';
 import { registerPainRetryCommand } from './commands/pain-retry.js';
 import { handlePainEvidence } from './commands/pain-evidence.js';
+import { handlePainList } from './commands/pain-list.js';
 import { handleSamplesList } from './commands/samples-list.js';
 import { handleSamplesReview } from './commands/samples-review.js';
 import { handleEvolutionTasksList } from './commands/evolution-tasks-list.js';
@@ -130,6 +131,17 @@ painCmd
 
 registerPainRetryCommand(painCmd);
 
+painCmd
+  .command('list')
+  .description('List canonical pain events with host attribution (PRI-640)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('-l, --limit <number>', 'Max entries to show (default: 20)', parseInt)
+  .option('--host <kind>', 'Filter by host: openclaw | codex | unknown')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    await handlePainList(opts);
+  });
+
 painCmd
   .command('evidence')
   .description('Show recent TRIGGER_DECISION log entries — pain admission gate decisions only (PEAT-B2)')
@@ -588,6 +600,56 @@ codexCmd
     });
   });
 
+// ── pd codex ingest catch-up — bounded manual transcript lag recovery ────────
+// Codex Governance Closure Slice C (PRI-624, SPEC §15): the manual-mode
+// counterpart of the Companion worker's catch-up step. Zero transcript I/O
+// when codex_conversation_ingestion is disabled.
+const codexIngestCmd = codexCmd
+  .command('ingest')
+  .description('Codex conversation-ingestion operations');
+
+codexIngestCmd
+  .command('catch-up')
+  .description('Catch up transcript lag from durable checkpoints (bounded, non-destructive, no LLM)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--max-rollouts <n>', 'Maximum rollouts to catch up per pass (1-32, default 8)')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const { handleCodexIngestCatchUp } = await import('./commands/codex-ingest-catchup.js');
+    const maxRollouts = typeof opts.maxRollouts === 'string' ? Number.parseInt(opts.maxRollouts, 10) : undefined;
+    await handleCodexIngestCatchUp({
+      workspace: opts.workspace,
+      json: opts.json === true,
+      ...(maxRollouts !== undefined && Number.isInteger(maxRollouts) ? { maxRollouts } : {}),
+    });
+  });
+
+// ── pd codex worker — Workspace-scoped governance worker ─────────────────────
+// Codex Governance Closure Slice C (PRI-624, SPEC §13; ADR-0020 §11.1): the
+// one Owner-approved background worker (catch-up → reconciliation → one
+// Diagnostician execution → one bounded downstream consumer cycle). The
+// Companion spawns this per registered workspace; --once is the manual and
+// supervised-restart form.
+codexCmd
+  .command('worker')
+  .description('Run the Codex workspace governance worker (catch-up, reconciliation, diagnostician, downstream)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--once', 'Run exactly one bounded cycle and exit')
+  .option('--interval <ms>', 'Cycle interval for continuous mode (default 120000, minimum 1000)')
+  .option('--status', 'Report the SPEC §15 worker mode without executing anything')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const { handleCodexWorker } = await import('./commands/codex-worker.js');
+    const intervalMs = typeof opts.interval === 'string' ? Number.parseInt(opts.interval, 10) : undefined;
+    await handleCodexWorker({
+      workspace: opts.workspace,
+      json: opts.json === true,
+      once: opts.once === true,
+      status: opts.status === true,
+      ...(intervalMs !== undefined && Number.isInteger(intervalMs) ? { intervalMs } : {}),
+    });
+  });
+
 runtimeHealthCmd
   .command('gfi')
   .description('GFI workspace snapshot — active vs stale session breakdown')

package/tests/commands/codex-worker-registration.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Command-registration / parser + functional tests for the PRI-624 Slice C
+ * Codex commands (cli-7): `pd codex ingest catch-up` and `pd codex worker`.
+ *
+ * Registration mirrors src/index.ts. Functional tests exercise the real
+ * handlers against a temp workspace: --json emits exactly one parseable
+ * JSON object (cli-1), flag-off skips carry reason + nextAction (cli-6), and
+ * failed paths mutate nothing.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Command } from 'commander';
+import { getDefaultPdConfig } from '@principles/core/runtime-v2';
+
+function buildTestProgram(): Command {
+  const program = new Command();
+  const codex = program.command('codex');
+  codex.command('reconcile');
+  const ingest = codex.command('ingest');
+  ingest
+    .command('catch-up')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--max-rollouts <n>', 'Maximum rollouts to catch up per pass (1-32, default 8)')
+    .option('--json', 'Output raw JSON')
+    .action(() => {});
+  codex
+    .command('worker')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--once', 'Run exactly one bounded cycle and exit')
+    .option('--interval <ms>', 'Cycle interval for continuous mode')
+    .option('--status', 'Report the SPEC §15 worker mode without executing anything')
+    .option('--json', 'Output raw JSON')
+    .action(() => {});
+  return program;
+}
+
+describe('codex Slice C command registration (cli-7)', () => {
+  it('parses codex ingest catch-up flags', () => {
+    const program = buildTestProgram();
+    program.parse(['node', 'pd', 'codex', 'ingest', 'catch-up', '--workspace', '/tmp/ws', '--max-rollouts', '4', '--json']);
+    const codex = program.commands.find((c) => c.name() === 'codex');
+    const ingest = codex?.commands.find((c) => c.name() === 'ingest');
+    const catchUp = ingest?.commands.find((c) => c.name() === 'catch-up');
+    expect(catchUp).toBeDefined();
+    expect(catchUp?.opts().workspace).toBe('/tmp/ws');
+    expect(catchUp?.opts().maxRollouts).toBe('4');
+    expect(catchUp?.opts().json).toBe(true);
+  });
+
+  it('parses codex worker flags including --once and --status', () => {
+    const program = buildTestProgram();
+    program.parse(['node', 'pd', 'codex', 'worker', '--workspace', '/tmp/ws', '--once', '--json']);
+    const codex = program.commands.find((c) => c.name() === 'codex');
+    const worker = codex?.commands.find((c) => c.name() === 'worker');
+    expect(worker).toBeDefined();
+    expect(worker?.opts().workspace).toBe('/tmp/ws');
+    expect(worker?.opts().once).toBe(true);
+    expect(worker?.opts().json).toBe(true);
+
+    const program2 = buildTestProgram();
+    program2.parse(['node', 'pd', 'codex', 'worker', '--status']);
+    const worker2 = program2.commands.find((c) => c.name() === 'codex')?.commands.find((c) => c.name() === 'worker');
+    expect(worker2?.opts().status).toBe(true);
+    // --interval is registered for continuous mode
+    const intervalOption = worker?.options.find((o) => o.long === '--interval');
+    expect(intervalOption).toBeDefined();
+  });
+});
+
+describe('codex ingest catch-up handler (functional)', () => {
+  let workspaceDir: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-cli-catchup-'));
+    fs.mkdirSync(path.join(workspaceDir, '.pd'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceDir, '.state'), { recursive: true });
+    fs.writeFileSync(path.join(workspaceDir, '.state', 'trajectory.db'), '');
+    const config = getDefaultPdConfig();
+    config.features['host.codex'].enabled = true;
+    config.features.codex_conversation_ingestion.enabled = false;
+    fs.writeFileSync(path.join(workspaceDir, '.pd', 'config.yaml'), JSON.stringify(config));
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    fs.rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  it('emits exactly one JSON object and skips with reason+nextAction when ingestion is off', { timeout: 20_000 }, async () => {
+    const { handleCodexIngestCatchUp } = await import('../../src/commands/codex-ingest-catchup.js');
+    await handleCodexIngestCatchUp({ workspace: workspaceDir, json: true });
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const report = JSON.parse(logSpy.mock.calls[0]?.[0] as string) as { status: string; reason: string; nextAction: string };
+    expect(report.status).toBe('skipped');
+    expect(report.reason).toBe('feature_disabled');
+    expect(report.nextAction).toContain('codex_conversation_ingestion');
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+});
+
+describe('codex worker handler (functional)', () => {
+  let workspaceDir: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-cli-worker-'));
+    fs.mkdirSync(path.join(workspaceDir, '.pd'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceDir, '.state'), { recursive: true });
+    fs.writeFileSync(path.join(workspaceDir, '.state', 'trajectory.db'), '');
+    const config = getDefaultPdConfig();
+    config.features['host.codex'].enabled = true;
+    config.features.internalization_auto_consumer.enabled = false;
+    fs.writeFileSync(path.join(workspaceDir, '.pd', 'config.yaml'), JSON.stringify(config));
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    process.exitCode = 0;
+    fs.rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  it('--once reports paused with reason+nextAction when the consumer flag is off', { timeout: 20_000 }, async () => {
+    const { handleCodexWorker } = await import('../../src/commands/codex-worker.js');
+    await handleCodexWorker({ workspace: workspaceDir, once: true, json: true });
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const report = JSON.parse(logSpy.mock.calls[0]?.[0] as string) as { mode: string; reason: string; nextAction: string };
+    expect(report.mode).toBe('paused');
+    expect(report.reason).toBe('internalization_auto_consumer_disabled');
+    expect(report.nextAction).toContain('pd diagnose');
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+
+  it('--json without --once/--status is refused (continuous mode streams, it is not one JSON document)', async () => {
+    const { handleCodexWorker } = await import('../../src/commands/codex-worker.js');
+    await handleCodexWorker({ workspace: workspaceDir, json: true });
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const error = JSON.parse(logSpy.mock.calls[0]?.[0] as string) as { error: string; reason: string; nextAction: string };
+    expect(error.error).toBe('cli_contract');
+    expect(error.reason).toBe('json_without_once_or_status');
+    expect(error.nextAction).toContain('--once');
+    expect(process.exitCode).toBe(1);
+  });
+
+  it('--once without --json prints the human-readable cycle report', { timeout: 20_000 }, async () => {
+    const { handleCodexWorker } = await import('../../src/commands/codex-worker.js');
+    await handleCodexWorker({ workspace: workspaceDir, once: true, json: false });
+    // Human-readable form: one multi-line report, no JSON envelope.
+    const output = logSpy.mock.calls.map((call) => String(call[0])).join('\n');
+    expect(output).toContain('Codex workspace worker');
+    expect(output).toContain('mode: paused');
+    expect(output).toContain('catch-up:');
+    expect(output).toContain('reconcile:');
+    expect(output).toContain('next action:');
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+
+  it('--status reports manual_action_required for a workspace absent from the install manifest', async () => {
+    const { handleCodexWorker } = await import('../../src/commands/codex-worker.js');
+    // Execution enabled — the manifest absence is then the deciding fact.
+    const config = getDefaultPdConfig();
+    config.features['host.codex'].enabled = true;
+    config.features.internalization_auto_consumer.enabled = true;
+    fs.writeFileSync(path.join(workspaceDir, '.pd', 'config.yaml'), JSON.stringify(config));
+    await handleCodexWorker({ workspace: workspaceDir, status: true, json: true });
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const report = JSON.parse(logSpy.mock.calls[0]?.[0] as string) as { mode: string; reason: string; registeredInInstallManifest: boolean; nextAction: string };
+    expect(report.mode).toBe('manual_action_required');
+    expect(report.reason).toBe('workspace_not_in_install_manifest');
+    expect(report.registeredInInstallManifest).toBe(false);
+    expect(report.nextAction).toContain('pd codex ingest catch-up');
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+});

package/tests/commands/health.test.ts

@@ -39,6 +39,10 @@ vi.mock('@principles/core/runtime-v2', () => ({
   }),
   auditCandidateLedgerConsistency: mockAuditCandidateLedgerConsistency,
   resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
+  // host-runtime's workspace-telemetry-emitter (transitively imported via the
+  // host-runtime barrel) extends this class at module-load time — the mock
+  // must provide a constructible base or the import chain throws.
+  StoreEventEmitter: class {},
 }));
 
 // PRI-443 Phase 5: getLedgerFilePathPublic now imported from