@principles/pd-cli 1.135.0 → 1.135.2

package/dist/utils/path-security.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Path containment primitives (CWE-22 boundary guards).
+ *
+ * Single source of truth for "is this filesystem target inside that root?"
+ * across pd-cli security boundaries. All containment decisions compare
+ * CANONICAL (fully resolved) paths via `path.relative`, never by string
+ * prefix — a string `startsWith` on a possibly-relative root is wrong on
+ * two counts: (1) a relative root never prefixes an absolute target, and
+ * (2) `/work/foo` is a prefix of `/work/foobar` without being a boundary.
+ *
+ * ── Symlink policy ────────────────────────────────────────────────────────
+ * The guarantee provided here is LEXICAL containment: `path.resolve` +
+ * `path.relative`, without resolving symlinks. We deliberately do NOT
+ * `realpath` the target before containment because:
+ *   1. PD's IO roots are operator-supplied workspace directories; symlinks
+ *      inside the workspace are created by the owner and treated as trusted
+ *      content.
+ *   2. On Windows, junction points (worktree junctions, `node_modules`
+ *      junctions) resolve to a *different physical location* via `realpath`;
+ *      realpath-based containment would reject legitimate local workflows
+ *      (e.g. a worktree whose `node_modules` is junctioned to the main
+ *      checkout).
+ * If a future caller must constrain the physical read target (e.g. reading a
+ * file whose path could be a symlink to an untrusted location), that caller
+ * must realpath the target FIRST and then run containment on the resolved
+ * path — do not weaken this module's contract.
+ */
+/**
+ * Canonicalize a user/operator-supplied path once. Every derived filesystem
+ * target must be compared against this canonical root.
+ */
+export declare function canonicalPath(p: string): string;
+/**
+ * True when `candidate` is strictly inside `parent` (canonical comparison).
+ *
+ * - Both arguments are resolved against cwd first, so relative inputs work.
+ * - `candidate === parent` returns false (strict containment). Callers that
+ *   want to allow the root itself should check equality separately.
+ * - Sibling-prefix attacks (`/work/foobar` vs parent `/work/foo`) cannot
+ *   pass because `path.relative` yields a non-`..`-prefixed path only for
+ *   real descendants.
+ */
+export declare function isPathInside(parent: string, candidate: string): boolean;
+/**
+ * Throw unless `candidate` is strictly inside `parent`. `label` names the
+ * candidate in the error message (e.g. "--workspace").
+ */
+export declare function assertPathInside(parent: string, candidate: string, label: string): void;
+/**
+ * Validate an operator-supplied directory root before it is used as an IO
+ * root: rejects empty values, residual parent-traversal segments, and
+ * filesystem-root results. Returns the canonical root.
+ *
+ * No `path.isAbsolute` requirement: absolute-ness is platform-dependent (a
+ * Windows-style path like `Z:\work` is not absolute on POSIX runners) and
+ * relative paths resolve inside cwd, so they carry no traversal risk. The
+ * guards that matter are: empty, parent traversal, and filesystem root.
+ */
+export declare function assertSafeDirectoryRoot(input: string, label: string): string;
+//# sourceMappingURL=path-security.d.ts.map

package/dist/utils/path-security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-security.d.ts","sourceRoot":"","sources":["../../src/utils/path-security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAUvE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAe5E"}

package/dist/utils/path-security.js

@@ -0,0 +1,90 @@
+/**
+ * Path containment primitives (CWE-22 boundary guards).
+ *
+ * Single source of truth for "is this filesystem target inside that root?"
+ * across pd-cli security boundaries. All containment decisions compare
+ * CANONICAL (fully resolved) paths via `path.relative`, never by string
+ * prefix — a string `startsWith` on a possibly-relative root is wrong on
+ * two counts: (1) a relative root never prefixes an absolute target, and
+ * (2) `/work/foo` is a prefix of `/work/foobar` without being a boundary.
+ *
+ * ── Symlink policy ────────────────────────────────────────────────────────
+ * The guarantee provided here is LEXICAL containment: `path.resolve` +
+ * `path.relative`, without resolving symlinks. We deliberately do NOT
+ * `realpath` the target before containment because:
+ *   1. PD's IO roots are operator-supplied workspace directories; symlinks
+ *      inside the workspace are created by the owner and treated as trusted
+ *      content.
+ *   2. On Windows, junction points (worktree junctions, `node_modules`
+ *      junctions) resolve to a *different physical location* via `realpath`;
+ *      realpath-based containment would reject legitimate local workflows
+ *      (e.g. a worktree whose `node_modules` is junctioned to the main
+ *      checkout).
+ * If a future caller must constrain the physical read target (e.g. reading a
+ * file whose path could be a symlink to an untrusted location), that caller
+ * must realpath the target FIRST and then run containment on the resolved
+ * path — do not weaken this module's contract.
+ */
+import * as path from 'node:path';
+/**
+ * Canonicalize a user/operator-supplied path once. Every derived filesystem
+ * target must be compared against this canonical root.
+ */
+export function canonicalPath(p) {
+    return path.resolve(p);
+}
+/**
+ * True when `candidate` is strictly inside `parent` (canonical comparison).
+ *
+ * - Both arguments are resolved against cwd first, so relative inputs work.
+ * - `candidate === parent` returns false (strict containment). Callers that
+ *   want to allow the root itself should check equality separately.
+ * - Sibling-prefix attacks (`/work/foobar` vs parent `/work/foo`) cannot
+ *   pass because `path.relative` yields a non-`..`-prefixed path only for
+ *   real descendants.
+ */
+export function isPathInside(parent, candidate) {
+    const root = path.resolve(parent);
+    const target = path.resolve(candidate);
+    const rel = path.relative(root, target);
+    return (rel !== '' &&
+        rel !== '..' &&
+        !rel.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(rel));
+}
+/**
+ * Throw unless `candidate` is strictly inside `parent`. `label` names the
+ * candidate in the error message (e.g. "--workspace").
+ */
+export function assertPathInside(parent, candidate, label) {
+    if (!isPathInside(parent, candidate)) {
+        throw new Error(`Invalid ${label}: "${candidate}" is outside "${parent}"`);
+    }
+}
+/**
+ * Validate an operator-supplied directory root before it is used as an IO
+ * root: rejects empty values, residual parent-traversal segments, and
+ * filesystem-root results. Returns the canonical root.
+ *
+ * No `path.isAbsolute` requirement: absolute-ness is platform-dependent (a
+ * Windows-style path like `Z:\work` is not absolute on POSIX runners) and
+ * relative paths resolve inside cwd, so they carry no traversal risk. The
+ * guards that matter are: empty, parent traversal, and filesystem root.
+ */
+export function assertSafeDirectoryRoot(input, label) {
+    if (!input || input.trim().length === 0) {
+        throw new Error(`Invalid ${label}: path is empty`);
+    }
+    // Un-normalized `..` segments that survive normalize() mean the input
+    // escaped a parent boundary (e.g. "..\\..\\evil") — reject rather than
+    // trust them. Foldable segments ("a/../b") canonicalize safely.
+    if (path.normalize(input).split(/[\\/]/).includes('..')) {
+        throw new Error(`Invalid ${label}: "${input}" contains parent traversal`);
+    }
+    const root = canonicalPath(input);
+    if (root === path.parse(root).root) {
+        throw new Error(`Invalid ${label}: "${input}" resolves to filesystem root`);
+    }
+    return root;
+}
+//# sourceMappingURL=path-security.js.map

package/dist/utils/path-security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-security.js","sourceRoot":"","sources":["../../src/utils/path-security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,CAAS;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,SAAiB;IAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,CACL,GAAG,KAAK,EAAE;QACV,GAAG,KAAK,IAAI;QACZ,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QAChC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CACtB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,SAAiB,EAAE,KAAa;IAC/E,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,WAAW,KAAK,MAAM,SAAS,iBAAiB,MAAM,GAAG,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,KAAa;IAClE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,WAAW,KAAK,iBAAiB,CAAC,CAAC;IACrD,CAAC;IACD,sEAAsE;IACtE,uEAAuE;IACvE,gEAAgE;IAChE,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,WAAW,KAAK,MAAM,KAAK,6BAA6B,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,WAAW,KAAK,MAAM,KAAK,+BAA+B,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/pd-cli",
-  "version": "1.135.0",
+  "version": "1.135.2",
   "description": "PD CLI — Pain recording, sample management, and evolution tasks",
   "type": "module",
   "bin": {

package/src/commands/legacy-cleanup.ts

@@ -27,6 +27,7 @@ import * as path from 'path';
 import * as os from 'os';
 import type { Database } from 'better-sqlite3';
 import { RuntimeStateManager } from '@principles/core/runtime-v2';
+import { assertSafeDirectoryRoot, isPathInside } from '../utils/path-security.js';
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -257,9 +258,21 @@ function glob(pattern: string): string[] {
   return results;
 }
 
+/**
+ * Validate a workspace root before cleanup scans derive paths from it.
+ * Returns the canonical root so all derived targets are absolute and
+ * containment checks are canonical-vs-canonical (relative workspaces work).
+ */
+function assertCleanupWorkspaceRoot(workspacePath: string): string {
+  return assertSafeDirectoryRoot(workspacePath, 'workspace path');
+}
+
 function findLegacyTargets(workspacePath: string): CleanupTarget[] {
   const targets: CleanupTarget[] = [];
-  const stateDir = path.join(workspacePath, '.state');
+  // CWE-22: resolve the workspace root once and verify it is a valid,
+  // non-root directory so every derived path stays inside the boundary.
+  const workspaceRoot = assertCleanupWorkspaceRoot(workspacePath);
+  const stateDir = path.join(workspaceRoot, '.state');
   const archiveTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
   const archiveDir = path.join(stateDir, 'legacy-archive', archiveTimestamp);
 
@@ -288,7 +301,11 @@ function findLegacyTargets(workspacePath: string): CleanupTarget[] {
   if (fs.existsSync(sessionsDir)) {
     for (const file of fs.readdirSync(sessionsDir)) {
       if (!file.endsWith('.json')) continue;
-      const filePath = path.join(sessionsDir, file);
+      const filePath = path.resolve(sessionsDir, file);
+      // CWE-22: verify the canonical path stays inside the canonical
+      // sessions dir before any filesystem access (readdir results are
+      // trusted, but defense-in-depth).
+      if (!isPathInside(sessionsDir, filePath)) continue;
       try {
         const content = fs.readFileSync(filePath, 'utf-8');
         const session = JSON.parse(content);

package/src/commands/pain-evidence.ts

@@ -19,6 +19,7 @@
 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;
@@ -40,11 +41,14 @@ interface TriggerDecisionEntry {
 }
 
 /**
- * Get the memory/logs directory for a workspace.
+ * 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 {
-  return path.join(workspaceDir, 'memory', 'logs');
+  const root = assertSafeDirectoryRoot(workspaceDir, 'workspace path');
+  return path.join(root, 'memory', 'logs');
 }
 
 /**
@@ -108,7 +112,11 @@ function readRecentDecisions(logDir: string, limit: number): TriggerDecisionEntr
   for (const logFile of logFiles) {
     if (allEntries.length >= limit) break;
 
-    const filePath = path.join(logDir, logFile);
+    // 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);

package/src/commands/rulecode.ts

@@ -31,6 +31,7 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import type { Command } from 'commander';
+import { isPathInside } from '../utils/path-security.js';
 import {
   RULECODE_SPEC_TEXT,
   checkForbiddenPatterns,
@@ -113,11 +114,33 @@ function isGoldenTraceCaseInput(value: unknown): value is GoldenTraceCaseInput {
 /**
  * Load and validate golden trace cases from a JSON file.
  * Returns either the validated cases or a structured error.
+ * Exported for boundary regression tests (internal test surface).
  */
-function loadGoldenTraceCases(filePath: string): { cases?: GoldenTraceCaseInput[]; error?: { reason: string; nextAction: string } } {
+export function loadGoldenTraceCases(
+  filePath: string,
+  workspaceDir?: string,
+): { cases?: GoldenTraceCaseInput[]; error?: { reason: string; nextAction: string } } {
   let raw: string;
   try {
+    if (!filePath || filePath.trim().length === 0) {
+      throw new Error('golden trace path is empty');
+    }
     const resolved = path.resolve(filePath);
+    // CWE-22 boundary: canonical containment against the workspace root
+    // (rejects sibling-prefix and traversal escapes; relative workspaces
+    // canonicalize consistently). Filesystem-root targets are rejected by
+    // containment when a workspace root is supplied.
+    const normalized = path.normalize(resolved);
+    if (normalized.split(/[\\/]/).includes('..')) {
+      throw new Error('golden trace path contains parent traversal');
+    }
+    if (workspaceDir) {
+      if (!isPathInside(workspaceDir, resolved)) {
+        throw new Error('golden trace path must be inside the workspace directory');
+      }
+    } else if (normalized === path.parse(normalized).root) {
+      throw new Error('golden trace path resolves to filesystem root');
+    }
     raw = fs.readFileSync(resolved, 'utf8');
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -286,7 +309,7 @@ export async function handleRulecodeReplay(opts: ReplayOptions): Promise<void> {
     return;
   }
 
-  const traceResult = loadGoldenTraceCases(opts.goldenTrace);
+  const traceResult = loadGoldenTraceCases(opts.goldenTrace, opts.workspace);
   if (traceResult.error || traceResult.cases === undefined) {
     const { error } = traceResult;
     const output: RulecodeReplayOutput = {

package/src/commands/runtime-activation.ts

@@ -45,29 +45,38 @@ interface ActivationDispatchOptions {
 }
 
 function mapRolloutDecision(reviewDecision: string | undefined): RolloutActivationDecision {
+  // P0-E (MVP_CORE_LOOP_CONTRACT INV-04): needs_revision 绝不映射 require_approval。
+  // 旧映射让"需修改"的评审结论伪装成正常审批进入 approval 队列(审计 ISSUE-027)。
+  // needs_revision 的出边是 revision loop(自动 reopen 修订目标),由
+  // rollout-reviewer-runner.handleRevisionRouting / auto-consumer 承担;
+  // CLI dispatch 对 needs_revision artifact 一律 refuse(structured reason + nextAction)。
   if (!reviewDecision) return 'require_approval';
   if (reviewDecision === 'approve_rollout') return 'auto_activate';
-  if (reviewDecision === 'needs_revision') return 'require_approval';
   if (reviewDecision === 'reject') return 'reject';
   return 'require_approval';
 }
 
-function extractRolloutDecisionFromArtifact(artifact: PIArtifactRecord): RolloutActivationDecision {
+/** 提取 artifact 上的原始 review decision(未映射),用于 needs_revision 拒绝分支 */
+function extractRawRolloutReviewDecision(artifact: PIArtifactRecord): string | null {
   try {
     const parsed = JSON.parse(artifact.contentJson) as Record<string, unknown>;
     if (parsed && typeof parsed === 'object') {
       const review = parsed.review as Record<string, unknown> | undefined;
       if (review && typeof review.decision === 'string') {
-        return mapRolloutDecision(review.decision);
+        return review.decision;
       }
       if (typeof parsed.rolloutDecision === 'string') {
-        return mapRolloutDecision(parsed.rolloutDecision);
+        return parsed.rolloutDecision;
       }
     }
   } catch {
-    return 'require_approval';
+    return null;
   }
-  return 'require_approval';
+  return null;
+}
+
+function extractRolloutDecisionFromArtifact(artifact: PIArtifactRecord): RolloutActivationDecision {
+  return mapRolloutDecision(extractRawRolloutReviewDecision(artifact) ?? undefined);
 }
 
 function toSnapshot(record: PIArtifactRecord): PIArtifactSnapshot {
@@ -158,6 +167,29 @@ export async function handleRuntimeActivationDispatch(opts: ActivationDispatchOp
     }
 
     const artifactSnapshot = toSnapshot(artifactRecord);
+
+    // P0-E: needs_revision artifact 不允许手动 dispatch 入 approval (INV-04)。
+    // 出边是 revision loop: auto-consumer 会自动 reopen 修订目标;
+    // 手动场景给出结构化 next action (cli-6)。
+    const rawReviewDecision = extractRawRolloutReviewDecision(artifactRecord);
+    if (rawReviewDecision === 'needs_revision') {
+      const refused: ActivationDecision = {
+        decision: 'refused',
+        reason: 'rollout_needs_revision_not_dispatchable',
+        nextAction: 'Revision is handled by the automatic revision loop (rollout_reviewer reopens scribe/artificer). Inspect: pd runtime internalization list --json; advance manually: pd runtime internalization run-once --runner rollout_reviewer',
+        channel,
+        riskLevel: channel === 'code_tool_hook' ? 'high' : channel === 'skill' ? 'medium' : 'low',
+      };
+      if (opts.json) {
+        console.log(JSON.stringify(refused, null, 2));
+      } else {
+        console.log(formatTextOutput(refused));
+        console.log('  nextAction: ' + refused.nextAction);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
     const rolloutDecision = extractRolloutDecisionFromArtifact(artifactRecord);
 
     const artifactReadModel = {

package/src/commands/runtime-internalization-enqueue-successors.ts

@@ -99,6 +99,54 @@ function mapCommitDecisionToAction(
         reason: 'task_not_found: task disappeared between scan and commit',
         nextAction: 'Re-scan or investigate concurrent deletion',
       };
+    case 'blocked_by_revision':
+      return {
+        taskId: commitResult.sourceTaskId,
+        taskKind: '',
+        decision: 'skipped',
+        reason: `blocked_by_revision: ${commitResult.reason} (runnerDecision=${commitResult.runnerDecision}); revision loop owns the out-edge`,
+        nextAction: 'Inspect the seeded repair/revision task: pd runtime internalization list --json',
+      };
+    case 'blocked_by_rejection':
+      return {
+        taskId: commitResult.sourceTaskId,
+        taskKind: '',
+        decision: 'skipped',
+        reason: `blocked_by_rejection: ${commitResult.reason} (runnerDecision=${commitResult.runnerDecision}); no successor, no approval`,
+        nextAction: 'Terminal reject — inspect the reviewer output or re-run the stage if the verdict was spurious',
+      };
+    case 'revision_reopened':
+      return {
+        taskId: commitResult.sourceTaskId,
+        taskKind: '',
+        decision: 'successor_created',
+        successorKind: 'evaluator',
+        successorTaskId: commitResult.reopenedTaskId,
+      };
+    case 'successor_reopened':
+      return {
+        taskId: commitResult.sourceTaskId,
+        taskKind: '',
+        decision: 'successor_created',
+        successorKind: commitResult.successorKind,
+        successorTaskId: commitResult.reopenedTaskId,
+      };
+    case 'revision_reopen_noop':
+      return {
+        taskId: commitResult.sourceTaskId,
+        taskKind: '',
+        decision: 'skipped',
+        reason: `revision_reopen_noop: ${commitResult.reason}; transition already materialized (same revision cause)`,
+        nextAction: 'No action — idempotent replay',
+      };
+    case 'blocked_missing_verdict':
+      return {
+        taskId: commitResult.taskId,
+        taskKind: '',
+        decision: 'skipped',
+        reason: `blocked_missing_verdict: ${commitResult.reason}; durable runnerDecision and legacy runs verdict both absent (fail-closed)`,
+        nextAction: 'Re-run the stage runner (writes durable verdict) or reconcile via the pending-artifacts report',
+      };
   }
 }
 

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')