@principles/pd-cli 1.135.0 → 1.135.2

package/src/resolve-workspace.ts

@@ -15,15 +15,24 @@
 
 import * as path from 'path';
 import { discoverWorkspaceDefault } from './services/pd-config-loader.js';
+import { assertSafeDirectoryRoot } from './utils/path-security.js';
 
 /** Environment variable name for workspace directory. */
 export const WORKSPACE_ENV = 'PD_WORKSPACE_DIR';
 
 // ── Internal helpers ────────────────────────────────────────────────────────
 
-/** Normalize path to forward slashes for cross-platform comparison. */
+/**
+ * Normalize a path to forward slashes for cross-platform string comparison.
+ *
+ * Comparison-only helper: it never resolves against the filesystem and never
+ * feeds a filesystem operation, so it intentionally uses `path.normalize`
+ * (pure string normalization) instead of `path.resolve`. Callers compare two
+ * paths for equality after normalization; the workspace root itself is
+ * validated by `assertWorkspaceDirInside` before any IO uses it.
+ */
 function normalizePath(p: string): string {
-  return path.resolve(p).replace(/\\/g, '/');
+  return path.normalize(p).replace(/\\/g, '/');
 }
 
 /** Emit workspace warnings to stderr. */
@@ -31,6 +40,31 @@ function emitWarning(msg: string): void {
   process.stderr.write(`[PD:workspace] WARNING: ${msg}\n`);
 }
 
+/**
+ * Validate an operator-supplied workspace root before it is used as an IO
+ * root. Delegates to the shared canonical-root validator (empty, parent
+ * traversal, filesystem root). Returns nothing; callers keep the original
+ * value so downstream resolution semantics are unchanged.
+ */
+function assertWorkspaceDirInside(p: string, source: string): void {
+  assertSafeDirectoryRoot(p, source);
+}
+
+/** Emit a warning when an explicit override differs from config default. */
+function emitWarningIfDiffers(
+  override: string,
+  configDefault: string | undefined,
+  discovered: { configPath?: string } | null,
+): void {
+  if (configDefault && normalizePath(override) !== normalizePath(configDefault)) {
+    emitWarning(
+      `"${override}" differs from config default "${configDefault}" ` +
+        `(source: ${discovered?.configPath}). Using explicit override. ` +
+        `Consider updating workspace.default in config.`,
+    );
+  }
+}
+
 // ── Public API ──────────────────────────────────────────────────────────────
 
 /**
@@ -46,34 +80,24 @@ export function resolveWorkspaceDir(workspaceDir?: string): string {
 
   // Step 2: Check --workspace flag (highest priority)
   if (workspaceDir) {
-    if (configDefault && normalizePath(workspaceDir) !== normalizePath(configDefault)) {
-      emitWarning(
-        `--workspace "${workspaceDir}" differs from config default "${configDefault}" ` +
-        `(source: ${discovered.configPath}). Using explicit flag. ` +
-        `Consider updating workspace.default in config.`,
-      );
-    }
+    assertWorkspaceDirInside(workspaceDir, '--workspace');
+    emitWarningIfDiffers(workspaceDir, configDefault, discovered);
     return workspaceDir;
   }
 
   // Step 3: Check PD_WORKSPACE_DIR env var
   const envWorkspace = process.env.PD_WORKSPACE_DIR?.trim();
   if (envWorkspace) {
-    if (configDefault && normalizePath(envWorkspace) !== normalizePath(configDefault)) {
-      emitWarning(
-        `PD_WORKSPACE_DIR "${envWorkspace}" differs from config default "${configDefault}" ` +
-        `(source: ${discovered.configPath}). Using env var. ` +
-        `Consider aligning or updating workspace.default.`,
-      );
-    }
+    assertWorkspaceDirInside(envWorkspace, WORKSPACE_ENV);
+    emitWarningIfDiffers(envWorkspace, configDefault, discovered);
     return envWorkspace;
   }
 
   // Step 4: Use discovered config default
   if (configDefault) {
+    assertWorkspaceDirInside(configDefault, 'workspace.default');
     return configDefault;
   }
-
   // Step 5: No resolution possible — throw (preserves current behavior)
   throw new Error(
     'No workspace directory configured. Set --workspace <path>, ' +

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/console-launcher.ts

@@ -218,20 +218,62 @@ export async function findAvailablePort(
 
 // ─── Browser opener (best-effort, no throw) ──────────────────────────────────
 
+/**
+ * Validate a browser URL before it is handed to a system opener.
+ * Only http/https targets are allowed — other schemes (file:, javascript:,
+ * custom protocols) could be abused. This is the primary defense for the
+ * win32 opener path, which no longer routes through a shell.
+ */
+function assertSafeBrowserUrl(rawUrl: string): string {
+  if (!rawUrl || rawUrl.trim().length === 0) {
+    throw new Error('browser URL is empty');
+  }
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`invalid browser URL: "${rawUrl}"`);
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`invalid browser URL: protocol must be http(s), got "${url.protocol}"`);
+  }
+  return url.toString();
+}
+
 /**
  * Open the system browser. Best-effort — failures are reported but do not
  * crash the launcher.
+ *
+ * Security: the URL is validated (http/https only) and every opener is
+ * invoked with a parameterized `spawn` (no shell). In particular the win32
+ * path uses `explorer.exe` with an argument array instead of the previous
+ * `cmd.exe /c start "" <url>` form, which ran the URL through the cmd shell
+ * and allowed shell metacharacters in the URL to be interpreted as commands
+ * (command injection).
  */
-export async function openBrowser(url: string): Promise<{ opened: boolean; reason?: string; nextAction?: string }> {
+export async function openBrowser(rawUrl: string): Promise<{ opened: boolean; reason?: string; nextAction?: string }> {
   const { spawn } = await import('child_process');
   const { platform } = process;
 
+  let url: string;
+  try {
+    url = assertSafeBrowserUrl(rawUrl);
+  } catch (err) {
+    return {
+      opened: false,
+      reason: err instanceof Error ? err.message : String(err),
+      nextAction: 'Use an http:// or https:// URL.',
+    };
+  }
+
   let cmd: string;
   let args: string[];
 
   if (platform === 'win32') {
-    cmd = process.env.ComSpec || 'cmd.exe';
-    args = ['/c', 'start', '""', url];
+    // Parameterized spawn (no shell): explorer.exe receives the validated
+    // URL as a plain argument and opens it in the default browser.
+    cmd = 'explorer.exe';
+    args = [url];
   } else if (platform === 'darwin') {
     cmd = 'open';
     args = [url];

package/src/services/pd-config-loader.ts

@@ -15,6 +15,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'js-yaml';
+import { canonicalPath, isPathInside } from '../utils/path-security.js';
 import {
   validatePdConfig,
   computeEffectivePdConfig,
@@ -316,6 +317,32 @@ function loadOpenClawPluginConfig(): { workspace?: string } | null {
   return null;
 }
 
+/**
+ * Validate a candidate config directory before it is joined into a config
+ * path for filesystem reads. Candidate dirs are operator-supplied
+ * (PD_WORKSPACE_DIR / plugin config / home default), so we normalize with
+ * `path.normalize` (pure string, no filesystem access), then reject empty,
+ * parent-traversal, or root paths. This keeps the subsequent
+ * `path.join(dir, PD_CONFIG_DIR, ...)` inside the intended directory
+ * boundary (CWE-22 mitigation).
+ *
+ * Platform note: no `path.isAbsolute` check — absolute-ness is
+ * platform-dependent (a Windows-style path is not absolute on POSIX
+ * runners) and relative dirs resolve inside cwd without traversal risk.
+ */
+function assertConfigDirBoundary(dir: string, source: string): void {
+  if (!dir || dir.trim().length === 0) {
+    throw new Error(`Invalid config search dir (${source}): path is empty`);
+  }
+  const normalized = path.normalize(dir);
+  if (normalized.split(/[\\/]/).includes('..')) {
+    throw new Error(`Invalid config search dir (${source}): "${dir}" contains parent traversal`);
+  }
+  if (normalized === path.parse(normalized).root) {
+    throw new Error(`Invalid config search dir (${source}): "${dir}" resolves to filesystem root`);
+  }
+}
+
 /**
  * Search known locations for a .pd/config.yaml that contains a workspace.default field.
  * This runs BEFORE workspace resolution and does NOT require knowing the workspace dir.
@@ -346,7 +373,14 @@ export function discoverWorkspaceDefault(): WorkspaceDiscoveryResult | null {
 
   // Search each candidate for .pd/config.yaml with workspace.default
   for (const { dir, source } of candidates) {
-    const configPath = path.join(dir, PD_CONFIG_DIR, PD_CONFIG_FILENAME);
+    assertConfigDirBoundary(dir, source);
+    // CWE-22: resolve the candidate root once, then verify the joined config
+    // path stays inside that root before any filesystem access.
+    const candidateRoot = canonicalPath(dir);
+    const configPath = path.resolve(candidateRoot, PD_CONFIG_DIR, PD_CONFIG_FILENAME);
+    if (!isPathInside(candidateRoot, configPath)) {
+      throw new Error(`Invalid config search dir (${source}): "${dir}" escapes its boundary`);
+    }
     if (fs.existsSync(configPath)) {
       const workspaceDefault = extractWorkspaceDefault(configPath);
       if (workspaceDefault) {

package/src/services/quality-scorecard/strong-model-gate.ts

@@ -60,6 +60,40 @@ Flags: ${localEval.flags.length > 0 ? localEval.flags.join(', ') : 'none'}
 Do NOT output anything other than this JSON object.`;
 }
 
+/**
+ * CWE-918 (SSRF) mitigation for operator-supplied LLM API base URLs.
+ *
+ * Threat model: OPENAI_BASE_URL is explicitly configured by the Owner /
+ * operator in the environment or Runtime Profile — it is trusted operator
+ * configuration, NOT untrusted remote input. Local and private-network
+ * OpenAI-compatible endpoints (llama.cpp, LM Studio, local gateways,
+ * intranet model servers) are legitimate PD runtime targets and must keep
+ * working.
+ *
+ * What stays blocked:
+ * - non-http(s) schemes (file:, javascript:, data:, ...)
+ * - malformed / unparseable URLs
+ * - credentials embedded in the URL (secrets leak into logs/errors)
+ *
+ * Callers must not allow the host to be rewritten from untrusted input
+ * after this validation; the endpoint is derived from this URL only.
+ */
+export function assertSafeLlmBaseUrl(rawBaseUrl: string): URL {
+  let url: URL;
+  try {
+    url = new URL(rawBaseUrl);
+  } catch {
+    throw new Error(`Invalid OPENAI_BASE_URL: "${rawBaseUrl}" is not a valid URL`);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error(`Invalid OPENAI_BASE_URL: protocol must be http or https, got "${url.protocol}"`);
+  }
+  if (url.username || url.password) {
+    throw new Error(`Invalid OPENAI_BASE_URL: credentials must not be embedded in the URL`);
+  }
+  return url;
+}
+
 export async function adjudicate(
   episode: PainEpisode,
   localEval: LocalEvaluation,
@@ -67,7 +101,11 @@ export async function adjudicate(
 ): Promise<StrongModelAdjudication> {
   const { modelId: strongModelId, log } = config;
   const prompt = buildAdjudicationPrompt(episode, localEval);
-  const baseUrl = process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1';
+  // CWE-918 (SSRF): validate the operator-supplied base URL before any
+  // network request — http(s) only, no embedded credentials. Local and
+  // private OpenAI-compatible endpoints remain valid (trusted operator
+  // configuration; llama.cpp / LM Studio / local gateways are supported).
+  const baseUrl = assertSafeLlmBaseUrl(process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1');
   const apiKey = process.env.OPENAI_API_KEY;
 
   if (!apiKey) {
@@ -82,7 +120,11 @@ export async function adjudicate(
   }
 
   try {
-    const resp = await fetch(`${baseUrl}/chat/completions`, {
+    // Build the endpoint on the validated URL: append the chat completions
+    // path to the base URL's (possibly empty) path component.
+    const endpoint = new URL(baseUrl);
+    endpoint.pathname = endpoint.pathname.replace(/\/+$/, '') + '/chat/completions';
+    const resp = await fetch(endpoint.toString(), {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',

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/src/utils/path-security.ts

@@ -0,0 +1,96 @@
+/**
+ * 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: string): string {
+  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: string, candidate: string): boolean {
+  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: string, candidate: string, label: string): void {
+  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: string, label: string): string {
+  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;
+}

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/);
+  });
 });

package/tests/commands/legacy-cleanup.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Tests for pd legacy cleanup command.
+ *
+ * Covers:
+ * - Relative workspace root works (regression: canonical containment)
+ * - Traversal escape rejected
+ * - Filesystem root rejected
+ * - Dry-run default with no artifacts found
+ * - Apply mode with legacy targets
+ * - V1 artifact identification
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import os from 'os';
+import {
+  handleLegacyCleanup,
+  isV1ArtificerArtifact,
+} from '../../src/commands/legacy-cleanup.js';
+
+// ── Pure logic: V1 artifact identification ─────────────────────────────────
+
+describe('isV1ArtificerArtifact', () => {
+  it('returns false for V2 artifact (non-empty implementationCode)', () => {
+    const v2 = JSON.stringify({ id: 'a', implementationCode: 'code here', plan: 'plan' });
+    expect(isV1ArtificerArtifact(v2)).toBe(false);
+  });
+
+  it('returns true for V1 artifact (plan-only, no implementationCode)', () => {
+    const v1 = JSON.stringify({ id: 'b', plan: 'plan only', implementationCode: '' });
+    expect(isV1ArtificerArtifact(v1)).toBe(true);
+  });
+
+  it('returns false for invalid JSON', () => {
+    expect(isV1ArtificerArtifact('{not json')).toBe(false);
+  });
+
+  it('returns false for non-object JSON', () => {
+    expect(isV1ArtificerArtifact('"string"')).toBe(false);
+    expect(isV1ArtificerArtifact('42')).toBe(false);
+  });
+
+  it('returns false for null JSON', () => {
+    expect(isV1ArtificerArtifact('null')).toBe(false);
+  });
+});
+
+// ── Integration: relative workspace + boundary validation ─────────────────
+
+describe('legacy cleanup workspace boundary', () => {
+  it('accepts a relative workspace root (regression: canonical containment)', async () => {
+    // A relative workspace must canonicalize consistently so cleanup scans
+    // inside it, without the old startsWith-on-relative-root failure.
+    const relTmp = fs.mkdtempSync(path.join(process.cwd(), '.tmp-rel-cleanup-'));
+    try {
+      // Create a legacy artifact the scanner looks for
+      const stateDir = path.join(relTmp, '.state');
+      fs.mkdirSync(stateDir, { recursive: true });
+      const legacyDb = path.join(stateDir, 'sessions.db');
+      fs.writeFileSync(legacyDb, 'not a real db', 'utf8');
+
+      const relWorkspace = path.relative(process.cwd(), relTmp);
+      expect(path.isAbsolute(relWorkspace)).toBe(false);
+
+      const result = await handleLegacyCleanup({
+        workspacePath: relWorkspace,
+        dryRun: true,
+      });
+
+      expect(result.status).toBe('ok');
+      expect(result.mode).toBe('dry-run');
+    } finally {
+      fs.rmSync(relTmp, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects parent traversal escape', async () => {
+    await expect(
+      handleLegacyCleanup({ workspacePath: '../evil', dryRun: true }),
+    ).rejects.toThrow(/parent traversal/);
+  });
+
+  it('rejects empty workspace', async () => {
+    await expect(
+      handleLegacyCleanup({ workspacePath: '', dryRun: true }),
+    ).rejects.toThrow(/path is empty/);
+  });
+
+  it('rejects filesystem root', async () => {
+    await expect(
+      handleLegacyCleanup({ workspacePath: path.parse(process.cwd()).root, dryRun: true }),
+    ).rejects.toThrow(/filesystem root/);
+  });
+});
+
+// ── Integration: normal cleanup flow ───────────────────────────────────────
+
+describe('legacy cleanup flow', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    // mkdtempSync: CodeQL-safe random directory under os.tmpdir
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-test-cleanup-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('dry-run with no artifacts returns ok with zero targets', async () => {
+    const result = await handleLegacyCleanup({ workspacePath: tmpDir, dryRun: true });
+    expect(result.status).toBe('ok');
+    expect(result.mode).toBe('dry-run');
+    expect(result.fileTargets).toEqual([]);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('scans legacy session files under .state/sessions', async () => {
+    const sessionsDir = path.join(tmpDir, '.state', 'sessions');
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(sessionsDir, 'old-session.json'),
+      JSON.stringify({ sessionKey: 'cron:pd-empathy-optimizer-abc' }),
+      'utf8',
+    );
+
+    const result = await handleLegacyCleanup({ workspacePath: tmpDir, dryRun: true });
+    expect(result.status).toBe('ok');
+    expect(result.fileTargets.length).toBeGreaterThanOrEqual(1);
+    expect(result.fileTargets.some((t) => t.path.endsWith('old-session.json'))).toBe(true);
+  });
+
+  it('apply mode deletes legacy session files', async () => {
+    const sessionsDir = path.join(tmpDir, '.state', 'sessions');
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    const legacyFile = path.join(sessionsDir, 'old-session.json');
+    fs.writeFileSync(
+      legacyFile,
+      JSON.stringify({ sessionKey: 'cron:pd-empathy-optimizer-abc' }),
+      'utf8',
+    );
+
+    const result = await handleLegacyCleanup({ workspacePath: tmpDir, apply: true });
+    expect(result.status).toBe('ok');
+    expect(result.mode).toBe('apply');
+    expect(fs.existsSync(legacyFile)).toBe(false);
+  });
+});