@principles/pd-cli 1.147.5 → 1.147.7

package/src/index.ts

@@ -584,6 +584,32 @@ const codexCmd = program
   .command('codex')
   .description('Codex host governance operations');
 
+// ── pd codex setup — consent UX for conversation ingestion (Slice D) ─────────
+// PRI-625, SPEC rev 2 §17 + G2A frozen disclosure: the ONE authority that can
+// enable codex_conversation_ingestion — presents the frozen disclosure and
+// records the explicit Owner decision BEFORE flipping the flag. Declining
+// leaves all existing governance unchanged and reads no transcript.
+codexCmd
+  .command('setup')
+  .description('Present the frozen ingestion disclosure and record the explicit consent decision (accept enables codex_conversation_ingestion; decline keeps everything off)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--accept', 'Explicitly accept after the disclosure has been presented (non-interactive)')
+  .option('--decline', 'Explicitly decline; the ingestion flag stays off and no transcript is ever read')
+  .option('--show-disclosure', 'Print the frozen disclosure text (zh default, --lang en) and exit without mutating anything')
+  .option('--lang <zh|en>', 'Disclosure language for presentation', undefined)
+  .option('--json', 'Output raw JSON (decision must be explicit: --accept or --decline)')
+  .action(async (opts) => {
+    const { handleCodexSetup } = await import('./commands/codex-setup.js');
+    await handleCodexSetup({
+      workspace: opts.workspace,
+      json: opts.json === true,
+      accept: opts.accept === true,
+      decline: opts.decline === true,
+      showDisclosure: opts.showDisclosure === true,
+      ...(typeof opts.lang === 'string' ? { lang: opts.lang } : {}),
+    });
+  });
+
 codexCmd
   .command('reconcile')
   .description('Reconcile admitted Codex pains with Diagnostician tasks and promotion tails (idempotent)')
@@ -624,6 +650,33 @@ codexIngestCmd
     });
   });
 
+// ── pd codex ingest quarantine — audited recovery for invalid records ────────
+// Codex Governance Closure Slice D (PRI-625, SPEC §15): dry-run by default,
+// --confirm required to mutate; records digest/reason/operator/timestamp/gap;
+// never edits the Codex transcript; promoted evidence is refused.
+codexIngestCmd
+  .command('quarantine')
+  .description('Quarantine a permanently invalid governance observation (dry-run by default; --confirm to apply; never touches the transcript)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--rollout <id>', 'Rollout identity that owns the record (required)')
+  .option('--record <id>', 'Numeric governance_observations.id to quarantine (required)')
+  .option('--reason <text>', 'Why the record is permanently invalid, 1-200 chars (required)')
+  .option('--operator <id>', 'Operator identity recorded in the audit metadata (default: current OS user)')
+  .option('--confirm', 'Apply the quarantine; without this flag the command is a dry run')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const { handleCodexIngestQuarantine } = await import('./commands/codex-ingest-quarantine.js');
+    await handleCodexIngestQuarantine({
+      workspace: opts.workspace,
+      rollout: opts.rollout,
+      record: opts.record,
+      reason: opts.reason,
+      ...(typeof opts.operator === 'string' ? { operator: opts.operator } : {}),
+      confirm: opts.confirm === true,
+      json: opts.json === true,
+    });
+  });
+
 // ── 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

package/src/services/console-launcher.ts

@@ -408,6 +408,11 @@ export async function planConsoleLaunch(input: OrchestratorInput): Promise<Orche
   const health = await probeConsoleHealth({ host, port: preferredPort, token });
   if (health.healthy) {
     if (token && health.authenticationMode !== 'authenticated') {
+      // PRI-695: a token-bearing caller must not land on a no_auth server
+      // (governance writes would be unauthenticated). The refusal stays, but
+      // the guidance must tell the user WHAT is running and the two ways out —
+      // the old text referenced "Companion", which a CLI-only user has never
+      // configured.
       return {
         status: 'refused',
         url: '',
@@ -415,7 +420,10 @@ export async function planConsoleLaunch(input: OrchestratorInput): Promise<Orche
         host,
         reused: false,
         reason: 'console_authentication_mode_mismatch',
-        nextAction: `Stop the Console on port ${preferredPort}, then retry so Companion can start an authenticated Console.`,
+        nextAction:
+          `A Console without authentication is already running on port ${preferredPort} ` +
+          '(the post-install default). Reopen without a token to reuse it, or stop that ' +
+          'Console and start with --token for authenticated access.',
       };
     }
     return {

package/tests/commands/codex-consent-reversibility.steps.test.ts

@@ -0,0 +1,299 @@
+import { afterEach, beforeEach, expect, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import * as yaml from 'js-yaml';
+import { getDefaultPdConfig } from '@principles/core/runtime-v2';
+import { catchUpCodexIngestion } from '@principles/codex-adapter';
+import {
+  ingestGovernanceObservations,
+  listGovernanceObservations,
+  promoteGovernanceEvidence,
+  readCodexIngestionConsent,
+  CODEX_INGESTION_DISCLOSURE_VERSION,
+} from '@principles/host-runtime';
+import { createStepRegistry, defineFeature } from '../../../principles-core/tests/bdd/support/vitest-bdd.js';
+import { resolveFeaturePath } from '../../../principles-core/tests/bdd/support/repo-root.js';
+
+/**
+ * Codex Governance Closure Slice D (PRI-625): consent & reversibility BDD
+ * steps for SPEC rev 2 §18 scenarios 17 and 15 (flag-off half). Drives the
+ * REAL setup handler (the installed-path consent authority) and the REAL
+ * catch-up/consent/evidence seams. The uninstall/legacy-migration half of
+ * §18-15 is bound in create-principles-disciple's installer suites.
+ *
+ * R1 behaviors proven here (SPEC §3):
+ *   R1-1 the disclosure is presented before ingestion can be enabled;
+ *   R1-2 declining leaves the flag off and governance working unchanged;
+ *   R1-3 declining never opens or reads the transcript;
+ *   R1-4 upgrade/machine paths never enable ingestion implicitly.
+ */
+
+let logLines: string[];
+
+/** Guarded path builder: only allowlisted basenames under <root>/.pd. */
+function pdFile(root: string, name: string): string | null {
+  if (!FILENAME_ALLOWLIST.includes(name)) return null;
+  const base = path.join(root, '.pd');
+  const target = path.join(base, name);
+  if (!target.startsWith(base + path.sep)) return null;
+  return target;
+}
+
+const FILENAME_ALLOWLIST = ['config.yaml', 'codex-ingestion-consent.json'];
+
+function makeWorkspace(options: { handEnableIngestion?: boolean } = {}): string {
+  const ws = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-bdd-consent-'));
+  fs.mkdirSync(path.join(ws, '.pd'), { recursive: true });
+  fs.mkdirSync(path.join(ws, '.state'), { recursive: true });
+  fs.writeFileSync(path.join(ws, '.state', 'trajectory.db'), '');
+  const config = getDefaultPdConfig();
+  config.features['host.codex'].enabled = true;
+  if (options.handEnableIngestion) {
+    config.features['codex_conversation_ingestion'].enabled = true;
+  }
+  // Multi-line YAML dump: the line-targeted editor needs a `features:` line.
+  fs.writeFileSync(path.join(ws, '.pd', 'config.yaml'), yaml.dump(config, { indent: 2, lineWidth: 200, noRefs: true }));
+  return ws;
+}
+
+/** Snapshot the fixed, allowlisted file set a consent run may touch. */
+function snapshot(root: string): Map<string, string> {
+  const files = new Map<string, string>();
+  for (const name of FILENAME_ALLOWLIST) {
+    const full = pdFile(root, name);
+    if (full === null) continue;
+    // Read first, no stat-then-read window (CodeQL FS race): ENOENT simply
+    // means the file is absent for this snapshot.
+    try {
+      files.set(full, fs.readFileSync(full, 'utf8'));
+    } catch {
+      // absent file — snapshot stays empty for it
+    }
+  }
+  return files;
+}
+
+async function runSetup(options: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const { handleCodexSetup } = await import('../../src/commands/codex-setup.js');
+  const captured: string[] = [];
+  // Install the capture INSIDE the step: defineFeature-created tests may not
+  // see file-level console/stdout spies reliably, and the capture must wrap
+  // exactly the handler call.
+  const logSpy = vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+    captured.push(args.map(String).join(' '));
+  });
+  const outSpy = vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: unknown) => {
+    captured.push(String(chunk));
+    return true;
+  }) as typeof process.stdout.write);
+  try {
+    await handleCodexSetup({ ...options, json: options.json === true } as never);
+  } finally {
+    logSpy.mockRestore();
+    outSpy.mockRestore();
+  }
+  logLines.push(...captured);
+  const jsonLine = captured.reverse().find((line) => line.startsWith('{'));
+  if (jsonLine === undefined) return {};
+  try {
+    return JSON.parse(jsonLine) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+beforeEach(() => {
+  logLines = [];
+  vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+    logLines.push(args.map(String).join(' '));
+  });
+  vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: unknown) => {
+    logLines.push(String(chunk));
+    return true;
+  }) as typeof process.stdout.write);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+});
+
+const registry = createStepRegistry();
+let ws: string;
+let beforeFiles: Map<string, string>;
+
+registry.given('an isolated Codex Workspace without a consent record', () => {
+  ws = makeWorkspace();
+  beforeFiles = snapshot(ws);
+});
+
+registry.given('an isolated Codex Workspace with the ingestion flag hand-enabled and no consent record', () => {
+  ws = makeWorkspace({ handEnableIngestion: true });
+  beforeFiles = snapshot(ws);
+});
+
+registry.when('setup presents the ingestion disclosure', async () => {
+  await runSetup({ workspace: ws, showDisclosure: true });
+});
+
+registry.then('the frozen Chinese text is shown verbatim with the version of the approved decision package', () => {
+  const output = logLines.join('\n');
+  expect(output, `captured=${JSON.stringify(logLines).slice(0, 200)}`).toContain('### Principles Disciple — 对话观察与治理闭环（Codex）');
+  expect(output).toContain('默认关闭。只有你在看到本说明后明确选择开启才会生效；升级 PD 永远不会替你开启。');
+  expect(CODEX_INGESTION_DISCLOSURE_VERSION).toBe('g2a-2026-08-28');
+  const read = readCodexIngestionConsent(ws);
+  expect(read.ok && read.record).toBeNull();
+});
+
+registry.when('the Owner explicitly accepts after the disclosure', async () => {
+  // The disclosure was presented first (R1-1 ordering): show, then accept.
+  await runSetup({ workspace: ws, showDisclosure: true });
+  const report = await runSetup({ workspace: ws, accept: true, json: true });
+  expect(report.status, JSON.stringify(report)).toBe('ok');
+});
+
+registry.then('the consent record exists with the granted decision and the ingestion flag is enabled', () => {
+  const read = readCodexIngestionConsent(ws);
+  expect(read.ok && read.record?.decision).toBe('granted');
+  if (read.ok && read.record) {
+    expect(read.record.disclosureVersion).toBe(CODEX_INGESTION_DISCLOSURE_VERSION);
+    expect(read.record.decidedVia).toBe('pd_codex_setup');
+  }
+  const config = pdFile(ws, 'config.yaml');
+  expect(config).not.toBeNull();
+  if (config !== null) {
+    expect(fs.readFileSync(config, 'utf8')).toContain('enabled: true');
+  }
+});
+
+registry.then('no config outside the workspace consent flow was modified', () => {
+  // The consent flow touches exactly two files: config.yaml and the consent
+  // record (the allowlisted snapshot). New files may only be the consent
+  // record; every pre-existing file may only be the config.yaml flip.
+  const after = snapshot(ws);
+  for (const [file, content] of beforeFiles) {
+    if (file.endsWith('config.yaml')) continue; // the flag flip is the point
+    expect(after.get(file) ?? '', `unexpected change: ${file}`).toBe(content);
+  }
+  const consentPath = path.join(ws, '.pd', 'codex-ingestion-consent.json');
+  expect(after.has(consentPath), 'the consent record must be the only new file').toBe(true);
+});
+
+registry.when('the Owner explicitly declines', async () => {
+  const report = await runSetup({ workspace: ws, decline: true, json: true });
+  expect(report.status).toBe('ok');
+  expect(report.decision).toBe('revoked');
+});
+
+registry.then('the consent record exists with the declined decision and the ingestion flag is off', () => {
+  const read = readCodexIngestionConsent(ws);
+  expect(read.ok && read.record?.decision).toBe('revoked');
+  const config = pdFile(ws, 'config.yaml');
+  expect(config).not.toBeNull();
+  if (config !== null) {
+    const content = fs.readFileSync(config, 'utf8');
+    expect(content).toContain('codex_conversation_ingestion:');
+    expect(content).toContain('enabled: false');
+  }
+});
+
+registry.then('no transcript was opened by the decline', () => {
+  // The decline only rewrites the two allowlisted .pd files; the handler has
+  // no transcript argument and no Codex-home FS surface. (The CODEX_HOME env
+  // assertion was removed in review round 3: it depends on the developer's
+  // machine environment, not on the behavior under test.)
+  expect(readCodexIngestionConsent(ws).ok && readCodexIngestionConsent(ws).record?.decision).toBe('revoked');
+});
+
+registry.when('setup runs in machine mode without an explicit accept or decline', async () => {
+  const report = await runSetup({ workspace: ws, json: true });
+  expect(report.reason).toBe('decision_required');
+});
+
+registry.then('nothing is recorded and nothing is enabled', () => {
+  expect(readCodexIngestionConsent(ws).ok && readCodexIngestionConsent(ws).record).toBeNull();
+  const after = snapshot(ws);
+  for (const [file, content] of beforeFiles) {
+    expect(after.get(file) ?? '').toBe(content);
+  }
+});
+
+// ── §18-15 flag-off reversibility ─────────────────────────────────────────────
+
+registry.given('an isolated Codex Workspace with conversation ingestion enabled and evidence recorded', () => {
+  ws = makeWorkspace({ handEnableIngestion: true });
+  const now = new Date();
+  const seeded = ingestGovernanceObservations({
+    workspaceDir: ws,
+    now,
+    observations: [{
+      hostKind: 'codex', rolloutIdentity: 'r-evidence', rootSessionId: 'root-evidence',
+      hostTurnId: 't1', kind: 'user_turn', logicalObservationKey: 'codex|r-evidence|t1|user',
+      source: 'transcript', completeness: 'complete', observedAt: now.toISOString(),
+      recordByteStart: 100, recordOrdinal: 1, visibleText: 'owner correction evidence',
+    }],
+  });
+  expect(seeded.ok).toBe(true);
+});
+
+registry.when('the ingestion flag is turned off', async () => {
+  const report = await runSetup({ workspace: ws, decline: true, json: true });
+  expect(report.status).toBe('ok');
+});
+
+registry.then('catch-up reports feature_disabled with zero transcript reads', async () => {
+  const result = await catchUpCodexIngestion({ workspaceDir: ws });
+  expect(result.status).toBe('skipped');
+  if (result.status === 'skipped') {
+    expect(result.reason).toBe('feature_disabled');
+    expect(result.nextAction).toContain('codex_conversation_ingestion');
+  }
+});
+
+registry.then('previously promoted evidence remains intact', async () => {
+  const promotion = promoteGovernanceEvidence({
+    workspaceDir: ws, hostKind: 'codex', rolloutIdentity: 'r-evidence',
+    triggerLogicalKey: 'codex|r-evidence|t1|user', painRef: 'pain_reversibility_1',
+  });
+  expect(promotion.ok).toBe(true);
+  const listed = listGovernanceObservations({ workspaceDir: ws });
+  expect(listed.ok).toBe(true);
+  if (!listed.ok) return;
+  expect(listed.observations.find((row) => row.logicalKey === 'codex|r-evidence|t1|user')?.retentionClass).toBe('promoted');
+});
+
+// ── §18-15 / R1-4: the upgrade path never enables ingestion ──────────────────
+
+registry.given('an isolated Codex Workspace where the Owner declined ingestion', async () => {
+  ws = makeWorkspace();
+  const report = await runSetup({ workspace: ws, decline: true, json: true });
+  expect(report.status).toBe('ok');
+  expect(report.decision).toBe('revoked');
+});
+
+registry.when('the production runtime initializer re-runs over the workspace', async () => {
+  // `pd runtime init` is the upgrade/re-init entry over an existing workspace.
+  const { handleRuntimeInit } = await import('../../src/commands/runtime-init.js');
+  const captured: string[] = [];
+  const logSpy = vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+    captured.push(args.map(String).join(' '));
+  });
+  try {
+    await handleRuntimeInit({ workspace: ws, confirm: true, json: true });
+  } finally {
+    logSpy.mockRestore();
+  }
+  void captured;
+});
+
+registry.then('the ingestion flag is still off and the declined consent record is untouched', () => {
+  const read = readCodexIngestionConsent(ws);
+  expect(read.ok && read.record?.decision).toBe('revoked');
+  const config = fs.readFileSync(path.join(ws, '.pd', 'config.yaml'), 'utf8');
+  expect(config).toContain('codex_conversation_ingestion:');
+  expect(config).toContain('enabled: false');
+  expect(config).not.toMatch(/codex_conversation_ingestion:[\s\S]{0,40}enabled: true/);
+});
+
+defineFeature(fs.readFileSync(resolveFeaturePath('docs/specs/features/codex-governance/codex-consent-reversibility.feature'), 'utf8'), registry);

package/tests/commands/codex-ingest-quarantine.test.ts

@@ -0,0 +1,136 @@
+/**
+ * pd codex ingest quarantine command tests (Slice D, SPEC §15).
+ *
+ * Functional, real-filesystem: seeds a workspace trajectory.db through the
+ * production store, then exercises the handler. Proven:
+ * - dry run is the DEFAULT: --json reports dryRun=true and the record row is
+ *   untouched;
+ * - --confirm quarantines (row becomes terminal, bodies dropped);
+ * - missing/invalid flags are refused with reason + nextAction, exit 1, and
+ *   mutate nothing (cli-5);
+ * - --json emits exactly one parseable object (cli-1).
+ */
+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 { getDefaultPdConfig } from '@principles/core/runtime-v2';
+import { ingestGovernanceObservations, listGovernanceObservations } from '@principles/host-runtime';
+
+let workspaceDir: string;
+let corruptRecordId = 0;
+let logSpy: ReturnType<typeof vi.spyOn>;
+let savedExitCode: number | undefined;
+
+beforeEach(() => {
+  workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-cli-quarantine-'));
+  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 = true;
+  fs.writeFileSync(path.join(workspaceDir, '.pd', 'config.yaml'), JSON.stringify(config));
+  const now = new Date('2026-08-29T12:00:00.000Z');
+  const seeded = ingestGovernanceObservations({
+    workspaceDir,
+    now,
+    observations: [
+      { hostKind: 'codex', rolloutIdentity: 'rollout-uuid-1', rootSessionId: 'root-1', hostTurnId: 't1', kind: 'user_turn', logicalObservationKey: 'codex|rollout-uuid-1|t1|user', source: 'transcript', completeness: 'complete', observedAt: now.toISOString(), recordByteStart: 100, recordOrdinal: 1, visibleText: 'first' },
+      { hostKind: 'codex', rolloutIdentity: 'rollout-uuid-1', rootSessionId: 'root-1', hostTurnId: 't2', kind: 'user_turn', logicalObservationKey: 'codex|rollout-uuid-1|t2|user', source: 'transcript', completeness: 'partial', observedAt: now.toISOString(), recordByteStart: 300, recordOrdinal: 3, visibleText: 'corrupt record' },
+    ],
+  });
+  expect(seeded.ok, JSON.stringify(seeded)).toBe(true);
+  const listed = listGovernanceObservations({ workspaceDir });
+  expect(listed.ok).toBe(true);
+  if (!listed.ok) throw new Error('unreachable');
+  const corrupt = listed.observations.find((row) => row.logicalKey === 'codex|rollout-uuid-1|t2|user');
+  expect(corrupt).toBeDefined();
+  corruptRecordId = corrupt.id;
+
+  savedExitCode = process.exitCode;
+  process.exitCode = undefined;
+  logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  process.exitCode = savedExitCode;
+  fs.rmSync(workspaceDir, { recursive: true, force: true });
+});
+
+function findRecord(): { retentionClass: string; visibleText: string | null } {
+  const listed = listGovernanceObservations({ workspaceDir });
+  if (!listed.ok) throw new Error('list failed');
+  const row = listed.observations.find((entry) => entry.id === corruptRecordId);
+  if (!row) throw new Error('record vanished');
+  return row;
+}
+
+async function run(options: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const { handleCodexIngestQuarantine } = await import('../../src/commands/codex-ingest-quarantine.js');
+  const callsBefore = logSpy.mock.calls.length;
+  await handleCodexIngestQuarantine({ workspace: workspaceDir, ...options } as never);
+  const newOutput = logSpy.mock.calls.slice(callsBefore).map((call) => String(call[0]));
+  const jsonLine = newOutput.reverse().find((line) => line.startsWith('{'));
+  expect(jsonLine, 'handler must emit exactly one JSON object for --json').toBeDefined();
+  return JSON.parse(jsonLine as string) as Record<string, unknown>;
+}
+
+describe('pd codex ingest quarantine (functional)', () => {
+  it('dry run is the default: reports digest/gap, mutates nothing, exits 0', { timeout: 20_000 }, async () => {
+    const report = await run({ rollout: 'rollout-uuid-1', record: String(corruptRecordId), reason: 'stable-invalid', json: true });
+    expect(report.status).toBe('ok');
+    expect(report.dryRun).toBe(true);
+    expect(report.confirmed).toBe(false);
+    expect(report.transcriptTouched).toBe(false);
+    const record = report.record as { digest: string; gap: string; id: number };
+    expect(record.id).toBe(corruptRecordId);
+    expect(record.digest).toMatch(/^[0-9a-f]{64}$/);
+    expect(record.gap).toContain('prev=');
+    expect(findRecord().retentionClass).toBe('operational');
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+
+  it('--confirm quarantines the record; a repeat is idempotent', { timeout: 20_000 }, async () => {
+    const report = await run({ rollout: 'rollout-uuid-1', record: String(corruptRecordId), reason: 'stable-invalid', operator: 'tester', confirm: true, json: true });
+    expect(report.dryRun).toBe(false);
+    expect(report.alreadyQuarantined).toBe(false);
+    expect(findRecord().retentionClass).toBe('quarantined');
+    expect(findRecord().visibleText).toBeNull();
+
+    const repeat = await run({ rollout: 'rollout-uuid-1', record: String(corruptRecordId), reason: 'stable-invalid', confirm: true, json: true });
+    expect(repeat.alreadyQuarantined).toBe(true);
+  });
+
+  it('refuses invalid arguments with reason+nextAction and no mutation (cli-5/cli-6)', { timeout: 30_000 }, async () => {
+    // Case table is built INSIDE the test so record ids reference the row
+    // seeded in beforeEach (an it.each table would evaluate before seeding).
+    const cases: [Record<string, unknown>, string][] = [
+      [{ reason: 'x' }, 'rollout_required'],
+      [{ rollout: 'rollout-uuid-1', reason: 'x' }, 'record_required'],
+      [{ rollout: 'rollout-uuid-1', record: 'abc' }, 'record_required'],
+      [{ rollout: 'rollout-uuid-1', record: String(corruptRecordId) }, 'reason_required'],
+      [{ rollout: 'unknown-rollout', record: String(corruptRecordId), reason: 'x' }, 'rollout_not_found'],
+    ];
+    for (const [options, expectedReason] of cases) {
+      process.exitCode = undefined;
+      const report = await run({ ...options, json: true });
+      expect(report.status, JSON.stringify({ options, report })).toBe('refused');
+      expect(report.reason).toBe(expectedReason);
+      expect(String(report.nextAction).length).toBeGreaterThan(0);
+      expect(process.exitCode).toBe(1);
+      expect(findRecord().retentionClass, String(expectedReason)).toBe('operational');
+    }
+  });
+
+  it('text output includes the dry-run next action', { timeout: 20_000 }, async () => {
+    const { handleCodexIngestQuarantine } = await import('../../src/commands/codex-ingest-quarantine.js');
+    await handleCodexIngestQuarantine({ workspace: workspaceDir, rollout: 'rollout-uuid-1', record: String(corruptRecordId), reason: 'stable-invalid' });
+    const output = logSpy.mock.calls.map((call) => String(call[0])).join('\n');
+    expect(output).toContain('dry-run');
+    expect(output).toContain('digest:');
+    expect(output).toContain('--confirm');
+    expect(process.exitCode ?? 0).toBe(0);
+  });
+});