@principles/pd-cli 1.118.0 → 1.120.0

package/src/commands/rulecode.ts

@@ -0,0 +1,434 @@
+/**
+ * pd rulecode — RuleCode dialect spec, static validation, and sandbox replay.
+ *
+ * PRI-439 Phase 5: Read-only CLI commands that mirror 3 of the 4 Artificer L2
+ * agent tools (read_rulecode_spec, validate_rulecode, replay_rulecode). These
+ * commands let operators inspect the RuleCode contract and dry-run code
+ * against the same pure-logic validators the Artificer L2 agent uses.
+ *
+ * Subcommands:
+ *   - spec     : print the RuleCode dialect spec text
+ *   - validate : run static validation (forbidden patterns + return shape +
+ *                matched=false decision check) on a code string
+ *   - replay   : run sandbox replay of code against a golden trace JSON file
+ *
+ * All three are READ-ONLY: no DB mutation, no artifact writes, no approvals,
+ * no activations. Failure paths include structured reason + nextAction
+ * (CLI Operator Gate rule 6).
+ *
+ * JSON mode is strict: --json outputs exactly one parseable JSON object on
+ * stdout, no banners (CLI Operator Gate rule 1).
+ *
+ * ERR refs:
+ *   - ERR-001 (no any): all types explicit; untrusted JSON parsed as unknown
+ *   - ERR-005 (no as bypass): golden trace cases validated with type guards
+ *   - ERR-009 (fail loud): missing --code/--code-file fails with reason
+ *   - ERR-002 (graceful degradation with reason): all failure paths include
+ *     reason + nextAction
+ *   - ERR-014 (bounded preview): safeStringifyPreview on unknown payloads
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import type { Command } from 'commander';
+import {
+  RULECODE_SPEC_TEXT,
+  checkForbiddenPatterns,
+  checkReturnStatementsMissingFields,
+  checkMatchedFalseDecisions,
+  evaluateRefinerRuleHostGate,
+  buildGoldenTraceFromArtificer,
+  createProductionGateDeps,
+} from '@principles/core/runtime-v2';
+import type { GoldenTraceCaseInput } from '@principles/core/runtime-v2';
+import { emitResult } from '../services/cli-output.js';
+
+// ── Output types ─────────────────────────────────────────────────────────────
+
+export interface RulecodeSpecOutput {
+  status: 'ok';
+  spec: string;
+}
+
+export interface RulecodeValidateOutput {
+  status: 'ok' | 'failed';
+  valid: boolean;
+  violationCount: number;
+  violations: string[];
+  reason?: string;
+  nextAction?: string;
+}
+
+export interface RulecodeReplayOutput {
+  status: 'ok' | 'failed';
+  decision: string;
+  reasons: string[];
+  failedCases: { caseId: string; errorType: string; message: string }[];
+  forbiddenPatternViolations: string[];
+  reason?: string;
+  nextAction?: string;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve code from --code (inline) or --code-file (path). Fails loud if
+ * neither is provided or the file cannot be read.
+ */
+function resolveCode(opts: { code?: string; codeFile?: string }): { code?: string; error?: { reason: string; nextAction: string } } {
+  if (opts.code && opts.code.trim().length > 0) {
+    return { code: opts.code };
+  }
+  if (opts.codeFile) {
+    try {
+      const resolved = path.resolve(opts.codeFile);
+      const content = fs.readFileSync(resolved, 'utf8');
+      if (content.trim().length === 0) {
+        return { error: { reason: `code file is empty: ${resolved}`, nextAction: 'provide a non-empty rule implementation file' } };
+      }
+      return { code: content };
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      return { error: { reason: `cannot read --code-file: ${reason}`, nextAction: 'verify the file path exists and is readable' } };
+    }
+  }
+  return { error: { reason: 'no code provided: pass --code <string> or --code-file <path>', nextAction: 'specify one of --code or --code-file' } };
+}
+
+/**
+ * Type guard: validate that an unknown value is a GoldenTraceCaseInput.
+ * Treats parsed JSON as untrusted (Runtime Contract Rule 1/2/4).
+ */
+function isGoldenTraceCaseInput(value: unknown): value is GoldenTraceCaseInput {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.caseId !== 'string' || v.caseId.length === 0) return false;
+  if (v.kind !== 'positive' && v.kind !== 'negative') return false;
+  if (typeof v.toolName !== 'string' || v.toolName.length === 0) return false;
+  if (typeof v.params !== 'object' || v.params === null) return false;
+  if (typeof v.expectedDecision !== 'string') return false;
+  return true;
+}
+
+/**
+ * Load and validate golden trace cases from a JSON file.
+ * Returns either the validated cases or a structured error.
+ */
+function loadGoldenTraceCases(filePath: string): { cases?: GoldenTraceCaseInput[]; error?: { reason: string; nextAction: string } } {
+  let raw: string;
+  try {
+    const resolved = path.resolve(filePath);
+    raw = fs.readFileSync(resolved, 'utf8');
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { error: { reason: `cannot read --golden-trace file: ${reason}`, nextAction: 'verify the file path exists and is readable' } };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { error: { reason: `golden trace file is not valid JSON: ${reason}`, nextAction: 'fix the JSON syntax in the golden trace file' } };
+  }
+
+  if (!Array.isArray(parsed)) {
+    return { error: { reason: 'golden trace file must contain a JSON array of cases', nextAction: 'provide an array of GoldenTraceCaseInput objects' } };
+  }
+
+  // Validate each element (Runtime Contract Rule 4 — validate array element types)
+  const cases: GoldenTraceCaseInput[] = [];
+  for (let i = 0; i < parsed.length; i++) {
+    const element = parsed[i];
+    if (!isGoldenTraceCaseInput(element)) {
+      return { error: { reason: `golden trace case at index ${i} is malformed (requires caseId, kind, toolName, params, expectedDecision)`, nextAction: `fix case at index ${i} in the golden trace file` } };
+    }
+    cases.push(element);
+  }
+
+  if (cases.length < 2) {
+    return { error: { reason: `golden trace must contain at least 2 cases (1 positive + 1 negative), got ${cases.length}`, nextAction: 'add more cases to the golden trace file' } };
+  }
+
+  return { cases };
+}
+
+// ── Handlers ─────────────────────────────────────────────────────────────────
+
+interface SpecOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+export async function handleRulecodeSpec(opts: SpecOptions): Promise<void> {
+  const output: RulecodeSpecOutput = {
+    status: 'ok',
+    spec: RULECODE_SPEC_TEXT,
+  };
+  emitResult(output, {
+    json: opts.json ?? false,
+    formatText: (o) => o.spec,
+  });
+}
+
+interface ValidateOptions {
+  code?: string;
+  codeFile?: string;
+  workspace?: string;
+  json?: boolean;
+}
+
+export async function handleRulecodeValidate(opts: ValidateOptions): Promise<void> {
+  const json = opts.json ?? false;
+  const codeResult = resolveCode(opts);
+  if (codeResult.error || codeResult.code === undefined) {
+    const { error } = codeResult;
+    const output: RulecodeValidateOutput = {
+      status: 'failed',
+      valid: false,
+      violationCount: 0,
+      violations: [],
+      reason: error?.reason ?? 'unknown error',
+      nextAction: error?.nextAction ?? 'check input and retry',
+    };
+    emitResult(output, {
+      json,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  const { code } = codeResult;
+  const forbidden = checkForbiddenPatterns(code);
+  const missingFields = checkReturnStatementsMissingFields(code);
+  const matchedFalseViolations = checkMatchedFalseDecisions(code);
+
+  const allViolations = [
+    ...forbidden.map((label) => `forbidden pattern: ${label}`),
+    ...missingFields,
+    ...matchedFalseViolations,
+  ];
+
+  const output: RulecodeValidateOutput = {
+    status: allViolations.length === 0 ? 'ok' : 'failed',
+    valid: allViolations.length === 0,
+    violationCount: allViolations.length,
+    violations: allViolations,
+  };
+
+  if (allViolations.length > 0) {
+    output.reason = `${allViolations.length} static violation(s) found`;
+    output.nextAction = 'fix the listed violations, then run `pd rulecode replay` to verify sandbox behavior';
+  }
+
+  emitResult(output, {
+    json,
+    formatText: (o) => {
+      if (o.valid) return 'VALID: no static violations detected.';
+      const lines = [`INVALID: ${o.violationCount} violation(s):`];
+      for (const v of o.violations) lines.push(`  - ${v}`);
+      return lines.join('\n');
+    },
+  });
+
+  if (output.status === 'failed') {
+    process.exitCode = 1;
+  }
+}
+
+interface ReplayOptions {
+  code?: string;
+  codeFile?: string;
+  goldenTrace?: string;
+  workspace?: string;
+  json?: boolean;
+}
+
+export async function handleRulecodeReplay(opts: ReplayOptions): Promise<void> {
+  const json = opts.json ?? false;
+  const codeResult = resolveCode(opts);
+  if (codeResult.error || codeResult.code === undefined) {
+    const { error } = codeResult;
+    const output: RulecodeReplayOutput = {
+      status: 'failed',
+      decision: 'rejected_input',
+      reasons: [],
+      failedCases: [],
+      forbiddenPatternViolations: [],
+      reason: error?.reason ?? 'unknown error',
+      nextAction: error?.nextAction ?? 'check input and retry',
+    };
+    emitResult(output, {
+      json,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!opts.goldenTrace) {
+    // Should not happen — --golden-trace is requiredOption. Defense-in-depth.
+    const output: RulecodeReplayOutput = {
+      status: 'failed',
+      decision: 'rejected_input',
+      reasons: [],
+      failedCases: [],
+      forbiddenPatternViolations: [],
+      reason: '--golden-trace is required',
+      nextAction: 'pass --golden-trace <path> with a JSON file of golden trace cases',
+    };
+    emitResult(output, {
+      json,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  const traceResult = loadGoldenTraceCases(opts.goldenTrace);
+  if (traceResult.error || traceResult.cases === undefined) {
+    const { error } = traceResult;
+    const output: RulecodeReplayOutput = {
+      status: 'failed',
+      decision: 'rejected_input',
+      reasons: [],
+      failedCases: [],
+      forbiddenPatternViolations: [],
+      reason: error?.reason ?? 'unknown error',
+      nextAction: error?.nextAction ?? 'check golden trace file and retry',
+    };
+    emitResult(output, {
+      json,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  // Build the GoldenTrace from the artificer-input shape.
+  const buildResult = buildGoldenTraceFromArtificer({
+    cases: traceResult.cases,
+    sourceArtifactId: undefined,
+  });
+  if (!buildResult.ok) {
+    const output: RulecodeReplayOutput = {
+      status: 'failed',
+      decision: 'rejected_input',
+      reasons: [],
+      failedCases: [],
+      forbiddenPatternViolations: [],
+      reason: `golden trace build failed: ${buildResult.reason}`,
+      nextAction: 'ensure the golden trace has at least 1 positive + 1 negative case',
+    };
+    emitResult(output, {
+      json,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  // Run the sandbox replay via production gate deps.
+  const gateDeps = createProductionGateDeps();
+  const gateResult = evaluateRefinerRuleHostGate(
+    { code: codeResult.code, goldenTrace: buildResult.trace },
+    gateDeps,
+  );
+
+  const output: RulecodeReplayOutput = {
+    status: gateResult.decision === 'accepted_shadow' ? 'ok' : 'failed',
+    decision: gateResult.decision,
+    reasons: gateResult.reasons,
+    failedCases: gateResult.sandboxResult.failedCases.map((c) => ({
+      caseId: c.caseId,
+      errorType: c.errorType,
+      message: c.message,
+    })),
+    forbiddenPatternViolations: gateResult.sandboxResult.forbiddenPatternViolations,
+  };
+
+  if (output.status === 'failed') {
+    output.reason = `sandbox replay rejected: ${gateResult.decision}`;
+    output.nextAction = 'fix the code or golden trace cases based on the failed cases above';
+  }
+
+  emitResult(output, {
+    json,
+    formatText: (o) => {
+      if (o.status === 'ok') return 'PASSED: all golden trace cases replayed successfully.';
+      const lines = [`FAILED: ${o.decision}`];
+      for (const r of o.reasons) lines.push(`  - ${r}`);
+      for (const c of o.failedCases) lines.push(`  - caseId: ${c.caseId} | ${c.errorType}: ${c.message}`);
+      for (const p of o.forbiddenPatternViolations) lines.push(`  - forbidden: ${p}`);
+      return lines.join('\n');
+    },
+  });
+
+  if (output.status === 'failed') {
+    process.exitCode = 1;
+  }
+}
+
+// ── Registration ─────────────────────────────────────────────────────────────
+
+/**
+ * Register the `rulecode` parent command with 3 subcommands (spec, validate,
+ * replay). Returns the parent command for chaining.
+ *
+ * This is the single source of truth for flag registration — both index.ts
+ * and parser tests call this function (CLI gate rule 7).
+ */
+export function registerRulecodeCommand(parentCmd: Command): Command {
+  const rulecodeCmd = parentCmd
+    .command('rulecode')
+    .description('RuleCode dialect spec, static validation, and sandbox replay (read-only)');
+
+  // spec — no code input needed
+  rulecodeCmd
+    .command('spec')
+    .description('Print the RuleCode dialect spec text (canonical form, forbidden patterns, return shape)')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleRulecodeSpec({ workspace: opts.workspace, json: opts.json });
+    });
+
+  // validate — static validation only
+  rulecodeCmd
+    .command('validate')
+    .description('Run static validation on rule implementation code (forbidden patterns + return shape)')
+    .option('--code <string>', 'Rule implementation source code (inline)')
+    .option('--code-file <path>', 'Read rule implementation code from file')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleRulecodeValidate({
+        code: opts.code,
+        codeFile: opts.codeFile,
+        workspace: opts.workspace,
+        json: opts.json,
+      });
+    });
+
+  // replay — sandbox replay against a golden trace
+  rulecodeCmd
+    .command('replay')
+    .description('Run sandbox replay of rule code against a golden trace JSON file')
+    .option('--code <string>', 'Rule implementation source code (inline)')
+    .option('--code-file <path>', 'Read rule implementation code from file')
+    .requiredOption('--golden-trace <path>', 'JSON file containing golden trace cases array')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleRulecodeReplay({
+        code: opts.code,
+        codeFile: opts.codeFile,
+        goldenTrace: opts.goldenTrace,
+        workspace: opts.workspace,
+        json: opts.json,
+      });
+    });
+
+  return rulecodeCmd;
+}

package/src/commands/runtime-internalization-run-rulehost.ts

@@ -31,7 +31,6 @@ import { createSandboxGateDeps } from '../services/rulehost-pipeline-runner.js';
 import {
   PiAiRuntimeAdapter,
   ArtificerL2Adapter,
-  buildArtificerL2GenerateCode,
   DefaultArtificerValidator,
   resolveAgentRuntimeBinding,
   computeFeatureFlagsFromConfig,
@@ -184,18 +183,14 @@ function resolveRunRuleHostRuntime(
   agentRuntimeProfiles.artificer = artificerBinding.profileId;
   agentRuntimeProfiles.evaluator = evaluator.profileId;
 
-  const generateCode = buildArtificerL2GenerateCode({
+  const artificerAdapter = new ArtificerL2Adapter({
     provider: artificerProfile.provider,
     model: artificerProfile.model,
-    apiKey,
+    apiKeyEnv: artificerProfile.apiKeyEnv,
     baseUrl: artificerProfile.baseUrl,
-    timeoutMs,
-  });
-
-  const artificerAdapter = new ArtificerL2Adapter({
-    generateCode,
     gateDeps: createSandboxGateDeps(),
     validator: new DefaultArtificerValidator(),
+    totalBudgetMs: timeoutMs,
   });
 
   return {

package/src/index.ts

@@ -53,6 +53,7 @@ import { handleDemoStoryA } from './commands/demo-story-a.js';
 import { handleRuntimeFeaturesStatus } from './commands/runtime-features.js';
 import { handleConfigDoctor } from './commands/config-doctor.js';
 import { registerMvpCommands } from './commands/mvp-smoke.js';
+import { registerRulecodeCommand } from './commands/rulecode.js';
 
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
@@ -895,23 +896,44 @@ artifactCmd
 
 const _legacyCleanupCmd = legacyCmd
   .command('cleanup')
-  .description('Clean legacy empathy/diagnostician artifacts from workspace')
+  .description('Clean legacy empathy/diagnostician artifacts and V1 Artificer artifacts from workspace')
   .requiredOption('-w, --workspace <path>', 'Workspace directory')
-  .option('--dry-run', 'Show what would be cleaned without applying', false)
-  .option('--apply', 'Actually apply the cleanup', false)
-  .action(async (opts) => {
-    const apply = opts.apply ?? false;
-    if (!apply && !opts.dryRun) {
-      console.error('Specify --dry-run or --apply');
-      process.exit(1);
+  .option('--dry-run', 'Show what would be cleaned without applying (default)')
+  .option('--apply', 'Actually apply the cleanup')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    // CLI gate rule 4: --dry-run and --apply are mutually exclusive
+    if (opts.dryRun && opts.apply) {
+      const msg = 'Error: --dry-run and --apply are mutually exclusive';
+      if (opts.json) {
+        console.log(JSON.stringify({ status: 'failed', reason: msg, nextAction: 'Specify either --dry-run or --apply, not both' }, null, 2));
+      } else {
+        console.error(msg);
+      }
+      process.exitCode = 1;
+      return;
     }
-    await handleLegacyCleanup(opts.workspace, apply);
+    // Default to dry-run if neither flag is set (CLI gate rule 4).
+    // Pass undefined through — the handler's logic
+    // (opts.apply === true ? false : opts.dryRun !== false) correctly
+    // defaults to dry-run when both are undefined.
+    await handleLegacyCleanup({
+      workspacePath: opts.workspace,
+      dryRun: opts.dryRun,
+      apply: opts.apply,
+      json: opts.json ?? false,
+    });
   });
 
 // ─── MVP Smoke (PRI-397) ────────────────────────────────────────────────────
 
 registerMvpCommands(program);
 
+// ─── RuleCode CLI (PRI-439 Phase 5) ─────────────────────────────────────────
+// Read-only commands: spec, validate, replay. No DB mutation, no artifact writes.
+
+registerRulecodeCommand(program);
+
 const consoleCmd = program
   .command('console')
   .description('Start the pd-console web UI for principle review (default: legacy launcher)')

package/src/services/rulehost-pipeline-runner.ts

@@ -39,6 +39,7 @@ import {
   EvaluatorRunner,
   DefaultEvaluatorValidator,
   createPITaskDiagnosticJson,
+  parsePITaskMetadata,
   runAdversarialLoop,
   evaluateInRefinerSandbox,
   DEFAULT_MAX_ROUNDS,
@@ -263,7 +264,7 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
     // D fix (PRI-429): exact sourcePainId match via Object.hasOwn on parsed
     // diagnosticJson. No substring matching (pain-1 must NOT match pain-10).
     onProgress('pain_lookup', 'start', `painId=${opts.painId}`);
-    const dreamerLookup = await findDreamerTaskForPain(stateManager, opts.painId);
+    const dreamerLookup = await findDreamerTaskForPain(stateManager, opts.painId, channel);
     if (dreamerLookup.status === 'ambiguous') {
       const reason = `ambiguous_dreamer_tasks_for_pain: ${dreamerLookup.taskIds.join(',')}`;
       stages.push({ name: 'pain_lookup', status: 'failed', reason });
@@ -281,15 +282,19 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
 
     // ── Stage: dreamer ──
     onProgress('dreamer', 'start');
-    const dreamerRunner = new DreamerRunner(
-      { stateManager, runtimeAdapter: agentAdapters.dreamer, eventEmitter, validator: new DefaultDreamerValidator(), artifactStore },
-      runnerOptsFor(agentAdapters.dreamer),
-    );
-    const dreamerResult = await runStage(dreamerRunner, dreamerSeedTaskId, { maxStageRetries, pollIntervalMs });
-    stages.push(stageFromResult('dreamer', dreamerSeedTaskId, dreamerResult));
-    if (dreamerResult.status !== 'succeeded') {
-      onProgress('dreamer', 'failed', dreamerResult.failureReason);
-      return rejectedResult(opts.painId, stages, `dreamer_failed: ${dreamerResult.failureReason ?? dreamerResult.status}`);
+    if (dreamerLookup.taskStatus === 'succeeded') {
+      stages.push({ name: 'dreamer', taskId: dreamerSeedTaskId, status: 'succeeded' });
+    } else {
+      const dreamerRunner = new DreamerRunner(
+        { stateManager, runtimeAdapter: agentAdapters.dreamer, eventEmitter, validator: new DefaultDreamerValidator(), artifactStore },
+        runnerOptsFor(agentAdapters.dreamer),
+      );
+      const dreamerResult = await runStage(dreamerRunner, dreamerSeedTaskId, { maxStageRetries, pollIntervalMs });
+      stages.push(stageFromResult('dreamer', dreamerSeedTaskId, dreamerResult));
+      if (dreamerResult.status !== 'succeeded') {
+        onProgress('dreamer', 'failed', dreamerResult.failureReason);
+        return rejectedResult(opts.painId, stages, `dreamer_failed: ${dreamerResult.failureReason ?? dreamerResult.status}`);
+      }
     }
     onProgress('dreamer', 'succeeded');
 
@@ -451,18 +456,25 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
  *   - ERR-009: missing sourcePainId = no match (fail loud, not silent skip)
  */
 type DreamerTaskLookup =
-  | { readonly status: 'found'; readonly taskId: string }
+  | { readonly status: 'found'; readonly taskId: string; readonly taskStatus: 'pending' | 'retry_wait' | 'succeeded' }
   | { readonly status: 'not_found' }
   | { readonly status: 'ambiguous'; readonly taskIds: readonly string[] };
 
-async function findDreamerTaskForPain(stateManager: RuntimeStateManager, painId: string): Promise<DreamerTaskLookup> {
+async function findDreamerTaskForPain(
+  stateManager: RuntimeStateManager,
+  painId: string,
+  channel: 'prompt' | 'code_tool_hook' | 'defer_archive',
+): Promise<DreamerTaskLookup> {
   const tasks = await stateManager.listTasks();
   const dreamerTasks = tasks.filter((t) =>
-    t.taskKind === 'dreamer' && (t.status === 'pending' || t.status === 'retry_wait'),
+    t.taskKind === 'dreamer' && (t.status === 'pending' || t.status === 'retry_wait' || t.status === 'succeeded'),
   );
-  const matches: string[] = [];
+  const allMatches: typeof dreamerTasks = [];
+  const channelMatches: typeof dreamerTasks = [];
   for (const t of dreamerTasks) {
     if (typeof t.diagnosticJson !== 'string') continue;
+    const metadata = parsePITaskMetadata(t.diagnosticJson);
+    if (!metadata) continue;
     let parsed: unknown;
     try {
       parsed = JSON.parse(t.diagnosticJson);
@@ -476,13 +488,19 @@ async function findDreamerTaskForPain(stateManager: RuntimeStateManager, painId:
     if (!Object.hasOwn(parsed, 'sourcePainId')) continue;
     const stored = Reflect.get(parsed, 'sourcePainId');
     if (typeof stored === 'string' && stored === painId) {
-      matches.push(t.taskId);
+      allMatches.push(t);
+      if (metadata.channel === channel) channelMatches.push(t);
     }
   }
-  matches.sort();
+  const matches = channelMatches.length > 0 ? channelMatches : allMatches;
+  matches.sort((left, right) => left.taskId.localeCompare(right.taskId));
   if (matches.length === 0) return { status: 'not_found' };
-  if (matches.length > 1) return { status: 'ambiguous', taskIds: matches };
-  return { status: 'found', taskId: matches[0] };
+  if (matches.length > 1) return { status: 'ambiguous', taskIds: matches.map((task) => task.taskId) };
+  const [match] = matches;
+  if (!match || (match.status !== 'pending' && match.status !== 'retry_wait' && match.status !== 'succeeded')) {
+    return { status: 'not_found' };
+  }
+  return { status: 'found', taskId: match.taskId, taskStatus: match.status };
 }
 
 // eslint-disable-next-line @typescript-eslint/max-params

package/tests/commands/candidate-internalize-lineage.test.ts

@@ -519,3 +519,47 @@ describe('PRI-435: candidate internalize rejects non-diagnostician task for line
     expect(Object.hasOwn(parsed, 'nextAction'), 'nextAction field must be present').toBe(true);
   });
 });
+
+describe('candidate internalize resolves the production diag_router candidate chain', () => {
+  it('follows the router run diagnosisId back to the originating diagnostician task', async () => {
+    tmpDir = makeTmpDir();
+    const sm = new RuntimeStateManager({ workspaceDir: tmpDir });
+    await sm.initialize();
+    const painId = 'pain-router-lineage-001';
+    const seeded = await seedDiagnosisToCandidate(sm, painId);
+    const routerTaskId = `diag_router-${seeded.taskId}`;
+    await sm.createTask({
+      taskId: routerTaskId, taskKind: 'diag_router', status: 'pending',
+      attemptCount: 0, maxAttempts: 3, diagnosticJson: JSON.stringify({ pi_metadata: {
+        dependencyTaskIds: [], channel: 'prompt', timeoutMs: 1000,
+        inputArtifactRefs: [], outputArtifactRefs: [],
+      } }),
+    });
+    await sm.acquireLease({ taskId: routerTaskId, owner: 'test', durationMs: 60_000, runtimeKind: 'openclaw' });
+    const [routerRun] = await sm.getRunsByTask(routerTaskId);
+    if (!routerRun) throw new Error('router run not created');
+    await sm.updateRunOutput(routerRun.runId, JSON.stringify({ diagnosisId: seeded.taskId }));
+    sm.connection.getDb().prepare(
+      'UPDATE principle_candidates SET task_id = ?, source_run_id = ? WHERE candidate_id = ?',
+    ).run(routerTaskId, routerRun.runId, seeded.candidateId);
+    await sm.close();
+
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      await handleCandidateInternalize({ candidateId: seeded.candidateId, workspace: tmpDir, json: true });
+    } finally {
+      logSpy.mockRestore();
+    }
+
+    const verify = new RuntimeStateManager({ workspaceDir: tmpDir });
+    await verify.initialize();
+    const dreamer = (await verify.listTasks()).find((task) => task.taskKind === 'dreamer');
+    expect(dreamer).toBeDefined();
+    const diagnostic: unknown = JSON.parse(dreamer?.diagnosticJson ?? '{}');
+    if (diagnostic === null || typeof diagnostic !== 'object' || Array.isArray(diagnostic)) {
+      throw new Error('dreamer diagnosticJson must be an object');
+    }
+    expect(Reflect.get(diagnostic, 'sourcePainId')).toBe(painId);
+    await verify.close();
+  });
+});