@principles/pd-cli 1.135.1 → 1.135.2

package/src/commands/runtime-internalization-retry.ts

@@ -0,0 +1,163 @@
+/**
+ * pd runtime internalization retry — needs_human_review 的 Owner 出边
+ * (MVP_CORE_LOOP_CONTRACT INV-03: inspect / retry / revise / reject-archive)。
+ *
+ * 修复前 needs_human_review 是 display-only 单向终态 (审计 ISSUE-006)。
+ * 本命令把 needs_human_review 任务重新入队 (→ pending, attemptCount 重置),
+ * 由 auto-consumer / run-once 重新驱动。
+ *
+ * Owner retry = 显式人类 authority reset,与 crash retry 严格区分:
+ * crash / lease recovery / automatic retry 保留 completionIntent(入口门
+ * resume 原 verdict,零 LLM);Owner retry 必须同时清空 runnerDecision 与
+ * completionIntent,允许新一轮 LLM verdict 成为 authority——否则入口门会
+ * resume/finalize 旧 verdict,LLM 永不运行,Owner retry 实际失效。
+ *
+ * 落库形态: status/attemptCount 与清空后的 metadata 在同一次 updateTask
+ * (SQLite 单条 UPDATE) 中原子生效——两个独立写之间失败会留下
+ * "authority 已清但任务仍 needs_human_review" 的 partial Owner action。
+ * metadata 不可 hydrate 时 fail closed (metadata_invalid),不得只改 status。
+ *
+ * CLI gate: 默认 dry-run;--confirm 才落地 (cli-4);JSON 模式严格单对象 (cli-1);
+ * 失败路径不产生任何状态变更 (cli-5)。
+ */
+
+import * as path from 'path';
+import { RuntimeStateManager } from '@principles/core/runtime-v2';
+import { hydratePITaskRecord, createPITaskDiagnosticJson, mergePITaskMetadata } from '@principles/core/runtime-v2';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+export interface InternalizationRetryOptions {
+  workspace?: string;
+  taskId?: string;
+  confirm?: boolean;
+  json?: boolean;
+}
+
+export interface InternalizationRetryOutput {
+  status: 'requeued' | 'dry_run' | 'skipped' | 'failed';
+  taskId: string;
+  taskKind?: string;
+  previousStatus?: string;
+  reason?: string;
+  nextAction?: string;
+}
+
+function emit(out: InternalizationRetryOutput, json?: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+  console.log(`Retry: ${out.status}${out.previousStatus ? ` (was ${out.previousStatus})` : ''}`);
+  if (out.reason) console.log(`  reason: ${out.reason}`);
+  if (out.nextAction) console.log(`  nextAction: ${out.nextAction}`);
+}
+
+export async function handleRuntimeInternalizationRetry(opts: InternalizationRetryOptions): Promise<void> {
+  if (!opts.taskId) {
+    const out: InternalizationRetryOutput = {
+      status: 'failed',
+      taskId: '',
+      reason: 'task_id_required',
+      nextAction: 'Pass --task <taskId> (find ids via: pd runtime internalization queue --json or pd errors list)',
+    };
+    emit(out, opts.json);
+    process.exitCode = 1;
+    return;
+  }
+
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+  try {
+    await stateManager.initialize();
+    const task = await stateManager.getTask(opts.taskId);
+    if (!task) {
+      const out: InternalizationRetryOutput = {
+        status: 'failed',
+        taskId: opts.taskId,
+        reason: 'task_not_found',
+        nextAction: 'Verify the task id and workspace',
+      };
+      emit(out, opts.json);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (task.status !== 'needs_human_review') {
+      const out: InternalizationRetryOutput = {
+        status: 'skipped',
+        taskId: opts.taskId,
+        taskKind: task.taskKind,
+        previousStatus: task.status,
+        reason: 'only_needs_human_review_tasks_are_retryable',
+        nextAction: 'This task is not in the owner attention queue; use run-once / enqueue-successors instead',
+      };
+      emit(out, opts.json);
+      return;
+    }
+
+    if (!opts.confirm) {
+      const out: InternalizationRetryOutput = {
+        status: 'dry_run',
+        taskId: opts.taskId,
+        taskKind: task.taskKind,
+        previousStatus: task.status,
+        reason: 'dry_run_no_mutation',
+        nextAction: 'Re-run with --confirm to requeue this task',
+      };
+      emit(out, opts.json);
+      return;
+    }
+
+    // Owner retry = authority reset: runnerDecision 与 completionIntent 同时
+    // 清空 (保留 revisionCount / revisionCauseId / rolloutRevisionPayload /
+    // repairPayload / lineage — revision budget 证据不动)。
+    const piTask = hydratePITaskRecord(task);
+    if (!piTask) {
+      // fail closed: 只改 status 会把(可能损坏的)旧 authority 记录原样留在
+      // metadata 里,下一次 run 由它接管 —— 产生 partial retry。
+      const out: InternalizationRetryOutput = {
+        status: 'failed',
+        taskId: opts.taskId,
+        taskKind: task.taskKind,
+        previousStatus: task.status,
+        reason: 'metadata_invalid',
+        nextAction: 'Task metadata failed PI hydration; a retry now would risk a partial authority reset. Inspect: pd runtime internalization integrity --json',
+      };
+      emit(out, opts.json);
+      process.exitCode = 1;
+      return;
+    }
+    // 原子单写: 同一 patch 同时落 status=pending / attemptCount=0 / 清空后的
+    // diagnosticJson。updateTask 抛错时 DB 行保持原样(单条 UPDATE),无 partial reset。
+    const merged = mergePITaskMetadata(piTask, {
+      runnerDecision: undefined,
+      completionIntent: undefined,
+    });
+    await stateManager.updateTask(opts.taskId, {
+      status: 'pending',
+      attemptCount: 0,
+      diagnosticJson: createPITaskDiagnosticJson(merged),
+    });
+
+    const out: InternalizationRetryOutput = {
+      status: 'requeued',
+      taskId: opts.taskId,
+      taskKind: task.taskKind,
+      previousStatus: task.status,
+      nextAction: 'Task requeued; it will be picked up by the auto-consumer cycle, or advance manually: pd runtime internalization run-once',
+    };
+    emit(out, opts.json);
+  } catch (err) {
+    const out: InternalizationRetryOutput = {
+      status: 'failed',
+      taskId: opts.taskId,
+      reason: err instanceof Error ? err.message : String(err),
+      nextAction: 'Check workspace DB integrity (pd runtime internalization integrity)',
+    };
+    emit(out, opts.json);
+    process.exitCode = 1;
+  } finally {
+    await stateManager.close();
+  }
+}
+

package/src/index.ts

@@ -33,6 +33,7 @@ import { handleRuntimeUat } from './commands/runtime-uat.js';
 import { handleRuntimeInternalizationQueue } from './commands/runtime-internalization-queue.js';
 import { handleRuntimeInternalizationWakeOnce } from './commands/runtime-internalization-wake-once.js';
 import { handleRuntimeInternalizationRunOnce } from './commands/runtime-internalization-run-once.js';
+import { handleRuntimeInternalizationRetry } from './commands/runtime-internalization-retry.js';
 import { registerRunRuleHostCommand } from './commands/runtime-internalization-run-rulehost.js';
 import { handleCandidateList, handleCandidateShow, handleCandidateIntake, handleCandidateAudit, handleCandidateRepair, handleCandidateRoute, handleCandidateInternalize, handleCandidateInternalizationBackfill } from './commands/candidate.js';
 import { handleArtifactShow } from './commands/artifact.js';
@@ -554,6 +555,17 @@ internalizationCmd
     await handleRuntimeInternalizationWakeOnce({ workspace: opts.workspace, dryRun: opts.dryRun, json: opts.json });
   });
 
+internalizationCmd
+  .command('retry')
+  .description('Requeue a needs_human_review task (owner attention queue out-edge)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .requiredOption('--task <taskId>', 'Task id to requeue')
+  .option('--confirm', 'Actually requeue (default is dry-run)')
+  .option('--json', 'Output as JSON')
+  .action(async (opts) => {
+    await handleRuntimeInternalizationRetry({ workspace: opts.workspace, taskId: opts.task, confirm: opts.confirm, json: opts.json });
+  });
+
 internalizationCmd
   .command('run-once')
   .description('Wake-and-run: lease the next PI task and execute it')

package/src/services/__tests__/evaluator-runner-deps.test.ts

@@ -100,6 +100,8 @@ function createMockStateManager(): {
 } {
   const createdTasks: TaskRecord[] = [];
   const stateManager = {
+    getTask: vi.fn(async (taskId: string) =>
+      createdTasks.find((t) => t.taskId === taskId) ?? null),
     createTask: vi.fn(async (record: Omit<TaskRecord, 'createdAt' | 'updatedAt'>) => {
       const now = new Date().toISOString();
       const task: TaskRecord = { ...record, createdAt: now, updatedAt: now };
@@ -185,7 +187,7 @@ describe('PRI-510 (DEFECT-004): createEvaluatorRunnerDeps wires repair loop into
     expect(deps.isRepairLoopEnabled()).toBe(false);
   });
 
-  it('flag absent in config → isRepairLoopEnabled() returns false (defaults apply)', () => {
+  it('flag absent in config → isRepairLoopEnabled() returns true (P0-D: default-on since core-loop closure)', () => {
     const workspaceDir = createTempWorkspace(null);
     tmpWorkspaces.push(workspaceDir);
     const { stateManager } = createMockStateManager();
@@ -201,10 +203,11 @@ describe('PRI-510 (DEFECT-004): createEvaluatorRunnerDeps wires repair loop into
 
     expect(typeof deps.isRepairLoopEnabled).toBe('function');
     if (typeof deps.isRepairLoopEnabled !== 'function') throw new Error('isRepairLoopEnabled missing');
-    expect(deps.isRepairLoopEnabled()).toBe(false);
+    // 契约变更 (2026-08-18, INV-02): registry 默认 ON;flag 缺省 = 默认生效
+    expect(deps.isRepairLoopEnabled()).toBe(true);
   });
 
-  it('malformed config → isRepairLoopEnabled() returns false (rc-9: fail safe, not throw)', () => {
+  it('malformed config → isRepairLoopEnabled() falls back to registry defaults (default-on), never throws', () => {
     // CodeQL: use mkdtempSync for atomic, unpredictable temp dir creation.
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-pri-510-malformed-'));
     tmpWorkspaces.push(tmpDir);
@@ -223,10 +226,11 @@ describe('PRI-510 (DEFECT-004): createEvaluatorRunnerDeps wires repair loop into
       workspaceDir: tmpDir,
     });
 
-    // Malformed config must NOT throw — return false so the legacy path runs.
+    // Malformed config must NOT throw — falls back to registry defaults
+    // (P0-D: evaluator_artificer_repair_loop default-on since core-loop closure).
     expect(typeof deps.isRepairLoopEnabled).toBe('function');
     if (typeof deps.isRepairLoopEnabled !== 'function') throw new Error('isRepairLoopEnabled missing');
-    expect(deps.isRepairLoopEnabled()).toBe(false);
+    expect(deps.isRepairLoopEnabled()).toBe(true);
   });
 
   it('seedArtificerRepairTask → creates artificer task with repairPayload in diagnosticJson (rc-1, rc-6)', async () => {
@@ -286,7 +290,7 @@ describe('PRI-510 (DEFECT-004): createEvaluatorRunnerDeps wires repair loop into
     expect(meta.inputArtifactRefs).toEqual(params.inheritedInputArtifactRefs);
   });
 
-  it('seedArtificerRepairTask → each call returns a UNIQUE task ID (rc-7: no stale state)', async () => {
+  it('seedArtificerRepairTask → deterministic id + replay reuse (P0-4); 不同 iteration 不同 id (rc-7)', async () => {
     const workspaceDir = createTempWorkspace(true);
     tmpWorkspaces.push(workspaceDir);
     const { stateManager } = createMockStateManager();
@@ -303,9 +307,17 @@ describe('PRI-510 (DEFECT-004): createEvaluatorRunnerDeps wires repair loop into
 
     if (typeof deps.seedArtificerRepairTask !== 'function') throw new Error('seedArtificerRepairTask missing');
     const id1 = await deps.seedArtificerRepairTask(params);
+    // P0-4: 同一 evaluator+iteration 的重放 (consumer 重复周期 / crash 恢复)
+    // reuse 同一确定性 id,不重复创建
+    expect(id1).toBe(`artificer-repair-${params.repairPayload.sourceEvaluatorTaskId}-r${params.repairPayload.repairIteration}`);
     const id2 = await deps.seedArtificerRepairTask(params);
-
-    expect(id1).not.toBe(id2);
+    expect(id2).toBe(id1);
+    // 不同 iteration (下一逻辑修复轮) → 不同 id
+    const id3 = await deps.seedArtificerRepairTask({
+      ...params,
+      repairPayload: { ...params.repairPayload, repairIteration: params.repairPayload.repairIteration + 1 },
+    });
+    expect(id3).not.toBe(id1);
   });
 
   it('deps spread contains all required base PeerRunnerDeps fields (EP-02: real path gets full deps)', () => {

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

@@ -66,7 +66,7 @@ import type {
   SeedArtificerRepairParams,
   EvaluatorValidator,
 } from '@principles/core/runtime-v2';
-import { randomUUID, createHash } from 'node:crypto';
+import { createHash } from 'node:crypto';
 import { loadPdConfig } from './pd-config-loader.js';
 /* eslint-disable @typescript-eslint/no-use-before-define -- helpers declared after main, matching codebase convention */
 import { compileDemoRule } from './demo-rule-compiler.js';
@@ -646,7 +646,10 @@ export function createEvaluatorRunnerDeps(inputs: CreateEvaluatorRunnerDepsInput
     },
     seedArtificerRepairTask: async (params: SeedArtificerRepairParams): Promise<string> => {
       // rc-7: each call gets a fresh task ID — never reuse a cached ID.
-      const repairTaskId = `artificer-repair-${randomUUID()}`;
+      // P0-4: deterministic revision identity + reuse on replay
+      const repairTaskId = `artificer-repair-${params.repairPayload.sourceEvaluatorTaskId}-r${params.repairPayload.repairIteration}`;
+      const existing = await stateManager.getTask(repairTaskId);
+      if (existing) return repairTaskId;
       await stateManager.createTask({
         taskId: repairTaskId,
         // D1 (PRI-509): task kind is 'artificer' — reuses the artificer

package/tests/commands/cli-command-tree.test.ts

@@ -126,4 +126,19 @@ describe('CLI command tree structure', () => {
     const output = runPdHelp(['legacy', 'cleanup', '--help']);
     expect(output).toContain('V1 Artificer');
   });
+
+  // cli-7-test-wiring (PR #1358 known gap 补齐): retry 是 INV-03 的核心 Owner
+  // 出边,command-tree 注册必须有 wiring 证明,不能只靠 handler 测试。
+  it('internalization retry command exists under runtime internalization (pd runtime internalization retry --help)', () => {
+    const output = runPdHelp(['runtime', 'internalization', 'retry', '--help']);
+    expect(output).toContain('--task');
+    expect(output).toContain('--confirm');
+    expect(output).toContain('--workspace');
+    expect(output).toContain('--json');
+  });
+
+  it('internalization subcommand list includes retry (pd runtime internalization --help)', () => {
+    const output = runPdHelp(['runtime', 'internalization', '--help']);
+    expect(output).toMatch(/retry\s/);
+  });
 });