@principles/pd-cli 1.147.0 → 1.147.2

package/src/services/workspace-tool-semantics.ts

@@ -0,0 +1,26 @@
+/**
+ * Workspace Tool Semantics Resolution — PRI-634-F R2 (review P1-2), R3
+ * (SPEC §五 P1-1): thin delegation to the ONE host-runtime resolver so CLI,
+ * Console, and any future entry point share the same multi-host
+ * load/merge/validate/resolve path. The CLI refusal policy (code_tool_hook
+ * refuses when unresolvable — no host guessing, no silent skip) stays here.
+ */
+
+import type { ToolSemanticRegistry } from '@principles/core/runtime-v2';
+import { resolveWorkspaceHostToolSemantics } from '@principles/host-runtime';
+
+export type WorkspaceToolSemanticsResolution =
+  | { readonly ok: true; readonly registry: ToolSemanticRegistry; readonly hostKind: string }
+  | { readonly ok: false; readonly reason: string; readonly nextAction: string };
+
+export function resolveWorkspaceToolSemantics(workspaceDir: string): WorkspaceToolSemanticsResolution {
+  const resolved = resolveWorkspaceHostToolSemantics(workspaceDir);
+  if (!resolved.ok) {
+    return { ok: false, reason: resolved.reason, nextAction: resolved.nextAction };
+  }
+  return {
+    ok: true,
+    registry: resolved.registry,
+    hostKind: resolved.hostKinds.join('+'),
+  };
+}

package/tests/commands/health.test.ts

@@ -31,6 +31,11 @@ const {
 });
 
 vi.mock('@principles/core/runtime-v2', () => ({
+  // PRI-634-F R2: full-module mocks must track new public exports — the
+  // activation graph imports buildToolSemanticRegistry transitively
+  // (workspace-tool-semantics), and vitest throws on the missing property
+  // access at import time even when never called.
+  buildToolSemanticRegistry: vi.fn().mockReturnValue({ ok: true, registry: {} }),
   PruningReadModel: vi.fn().mockImplementation(function () {
     return { getHealthSummary: mockPruningGetHealthSummary };
   }),

package/tests/commands/rulecode.test.ts

@@ -14,6 +14,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import os from 'os';
 import { loadGoldenTraceCases } from '../../src/commands/rulecode.js';
+import { vi } from 'vitest';
 
 const VALID_CASES = JSON.stringify([
   {
@@ -133,3 +134,44 @@ describe('loadGoldenTraceCases containment', () => {
     expect(result.error?.reason).toContain('not valid JSON');
   });
 });
+
+
+// ── PRI-634-F R2 (review P2): replay --json carries structured failure ──────
+
+describe('handleRulecodeReplay — structured failure attribution on --json', () => {
+  it('a failing replay surfaces {layer, reasonCode, evidence, nextAction} in the JSON output', async () => {
+    const { handleRulecodeReplay } = await import('../../src/commands/rulecode.js');
+    const code = [
+      'const evaluate = (input) => {',
+      '  return { decision: "allow", matched: false, reason: "never blocks" };',
+      '};',
+    ].join(String.fromCharCode(10));
+    // The --golden-trace CLI input is a JSON ARRAY of cases (not the
+    // persisted GoldenTrace envelope) — see loadGoldenTraceCases.
+    const cases = [
+      { caseId: 'negative-1', kind: 'negative', toolName: 'write_file', params: { file_path: '/prod.env' }, expectedDecision: 'block' },
+      { caseId: 'positive-1', kind: 'positive', toolName: 'write_file', params: { file_path: '/repo/a.ts' }, expectedDecision: 'allow' },
+    ];
+    const traceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-replay-'));
+    const traceFile = path.join(traceDir, 'golden-trace-cases.json');
+    fs.writeFileSync(traceFile, JSON.stringify(cases), 'utf8');
+
+    const logs: string[] = [];
+    const spy = vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => { logs.push(String(args[0])); });
+    try {
+      await handleRulecodeReplay({ code, goldenTrace: traceFile, json: true });
+    } finally {
+      spy.mockRestore();
+      fs.rmSync(traceDir, { recursive: true, force: true });
+    }
+    expect(process.exitCode).toBe(1);
+    process.exitCode = 0;
+    const output = JSON.parse(logs[0]);
+    expect(output.status).toBe('failed');
+    expect(output.decision).toBe('rejected_validation_failed');
+    expect(output.failure).toBeDefined();
+    expect(output.failure.layer).toBe('rule');
+    expect(output.failure.reasonCode).toBe('replay_decision_mismatch');
+    expect(typeof output.failure.nextAction).toBe('string');
+  });
+});

package/tests/commands/runtime-activation.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { createHash } from 'node:crypto';
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { resolveWorkspaceToolSemantics } from '../../src/services/workspace-tool-semantics.js';
+import { vi as _vi } from 'vitest';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
@@ -25,6 +27,14 @@ const mockListCodeToolHookActivations = vi.fn().mockResolvedValue([
   { activationId: 'act-hook-1', artifactId: 'art-002', channel: 'code_tool_hook', action: 'code_tool_hook_shadow_activate', targetRef: 'rule-001', activatedAt: '2026-06-18T00:00:00.000Z', promotedAt: null, deactivatedAt: null },
 ]);
 
+vi.mock('../../src/services/workspace-tool-semantics.js', () => ({
+  // Unit boundary: dispatch/approve tests exercise flag wiring and approval
+  // state transitions; host-provenance resolution has its own contract tests
+  // (workspace-tool-semantics.test.ts). Tests that need the refusal path
+  // override the return value via vi.mocked.
+  resolveWorkspaceToolSemantics: vi.fn().mockReturnValue({ ok: true, registry: { version: 1, hasHostLayer: true }, hostKind: 'test-host' }),
+}));
+
 vi.mock('../../src/resolve-workspace.js', () => ({
   resolveWorkspaceDir: vi.fn().mockReturnValue('/fake/workspace'),
 }));
@@ -97,7 +107,9 @@ vi.mock('@principles/core/runtime-v2', async (importOriginal) => {
       };
     }),
     ApprovalQueue: vi.fn().mockImplementation(function () {
-      return { approve: mockApprovalApprove, resetToPending: mockApprovalResetToPending };
+      // PRI-634-F R2: getById backs the pre-approve host-provenance check
+      // (null = no record; the approve path handles not-found itself).
+      return { approve: mockApprovalApprove, resetToPending: mockApprovalResetToPending, getById: async () => null };
     }),
     ApprovalCompletionService: vi.fn().mockImplementation(function () {
       return { completeApproval: mockCompletionComplete };
@@ -1966,3 +1978,73 @@ describe('PRI-499: cli-2-exit-stops — failure paths set exitCode and do not co
     expect(RuntimeStateManager).not.toHaveBeenCalled();
   });
 });
+
+
+describe('handleRuntimeActivationDispatch — PRI-634-F R2 host provenance refusal', () => {
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRuleHostWriterConfigs.length = 0;
+    mockGetArtifactById.mockResolvedValue(makeArtifact());
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+    process.exitCode = 0;
+  });
+
+  it('refuses code_tool_hook activation when host provenance is unresolvable — structured reason + nextAction, no writer constructed (review P1)', async () => {
+    vi.mocked(resolveWorkspaceToolSemantics).mockReturnValueOnce({
+      ok: false,
+      reason: 'host_tool_declaration_missing',
+      nextAction: 'start the workspace host once so it persists its tool declaration',
+    });
+    await handleRuntimeActivationDispatch({
+      workspace: WS,
+      artifactId: 'art-001',
+      channel: 'code_tool_hook',
+      json: true,
+    });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+    expect(output.decision).toBe('refused');
+    expect(output.reason).toBe('host_tool_declaration_missing');
+    expect(output.nextAction).toContain('host');
+    // Fail-closed: the dispatcher (and its writers) must never run —
+    // cli-5-failure-no-mutation.
+    expect(mockRuleHostWriterConfigs).toHaveLength(0);
+    expect(process.exitCode).toBe(1);
+  });
+
+  it('non-code_tool_hook channels are unaffected by unresolvable provenance', async () => {
+    vi.mocked(resolveWorkspaceToolSemantics).mockReturnValueOnce({
+      ok: false,
+      reason: 'host_tool_declaration_missing',
+      nextAction: 'start the workspace host once',
+    });
+    await handleRuntimeActivationDispatch({
+      workspace: WS,
+      artifactId: 'art-001',
+      channel: 'prompt',
+      json: true,
+    });
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+    expect(output.decision).not.toBe('refused');
+  });
+
+  it('code_tool_hook dispatch threads the resolved registry into RuleHostWriter and gateDeps', async () => {
+    const registry = { version: 1, hasHostLayer: true, resolve: () => 'write', lookup: () => null, hasHostTool: () => true };
+    vi.mocked(resolveWorkspaceToolSemantics).mockReturnValueOnce({ ok: true, registry, hostKind: 'openclaw' });
+    await handleRuntimeActivationDispatch({
+      workspace: WS,
+      artifactId: 'art-001',
+      channel: 'code_tool_hook',
+      json: true,
+    });
+    expect(mockRuleHostWriterConfigs).toHaveLength(1);
+    expect(mockRuleHostWriterConfigs[0]?.toolSemantics).toBe(registry);
+    expect(mockRuleHostWriterConfigs[0]?.gateDeps).toBeDefined();
+  });
+});

package/tests/commands/runtime-internalization-run-once-evaluator-parity.test.ts

@@ -0,0 +1,269 @@
+/**
+ * PRI-661 — run-once evaluator runtime parity (E2E through the REAL CLI
+ * handler).
+ *
+ * Drives `handleRuntimeInternalizationRunOnce --runner evaluator` against a
+ * REAL sqlite workspace + REAL persisted host declaration + the REAL resolver
+ * and sandbox. Only the LLM boundary is the CLI's own test-double runtime.
+ *
+ * Pins the acceptance from the Linear issue:
+ *   1. a declared workspace runs the deterministic adversarial replay to
+ *      completion through run-once (the gap this PR closes);
+ *   2. the SAME artifact replays to the SAME verdict through the
+ *      consumer-cycle assembly formula (live registry from the same mapping
+ *      constants) — replay/production parity, not just "some gate ran";
+ *   3. an undeclared workspace refuses BEFORE leasing any task, with the same
+ *      structured semantics as runtime-activation (no baseline fallback);
+ *   4. a replay-failing rule records adversarialResult.passed=false — the
+ *      deterministic verdict the downstream approval chain consumes.
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  RuntimeStateManager,
+  createPITaskDiagnosticJson,
+  buildToolSemanticRegistry,
+  createProductionGateDeps,
+  type ToolSemanticMappingV1,
+} from '@principles/core/runtime-v2';
+import { saveHostToolDeclaration } from '@principles/host-runtime';
+import { handleRuntimeInternalizationRunOnce } from '../../src/commands/runtime-internalization-run-once.js';
+
+const HOST_MAPPINGS: readonly ToolSemanticMappingV1[] = [
+  { rawToolName: 'Write', canonicalKind: 'write' },
+  { rawToolName: 'Edit', canonicalKind: 'write' },
+  { rawToolName: 'write_file', canonicalKind: 'write' },
+  { rawToolName: 'Bash', canonicalKind: 'execute' },
+];
+
+/**
+ * A realistic write-after-read guard that satisfies both the fixture's golden
+ * cases and the runner's 5 auto-generated v2 adversarial templates:
+ * risk-path writes always block (v1 action check dominates); otherwise a
+ * write is allowed only with prior-read evidence or an explicitly benign
+ * context posture (unavailable/truncated/unknown fail open).
+ * Registry-sensitive: it keys off action.canonicalKind — the field the host
+ * tool registry injects into replay inputs.
+ */
+const PASSING_CODE = [
+  'function evaluate(input) {',
+  '  const action = input && input.action ? input.action : {};',
+  '  const kind = action.canonicalKind ? action.canonicalKind : "other";',
+  '  const params = action.paramsSummary ? action.paramsSummary : {};',
+  '  const p = typeof params.path === "string" ? params.path : "";',
+  '  if (kind !== "write") {',
+  '    return { decision: "allow", matched: false, reason: "not a write" };',
+  '  }',
+  '  if (p.indexOf("/etc/") === 0) {',
+  '    return { decision: "block", matched: true, reason: "risk path write" };',
+  '  }',
+  '  const ctx = input && input.context ? input.context : null;',
+  '  const facts = ctx && ctx.facts ? ctx.facts : {};',
+  '  if (facts.priorReadOfTarget === "yes") {',
+  '    return { decision: "allow", matched: false, reason: "write after read" };',
+  '  }',
+  '  if (facts.priorReadOfTarget === "no") {',
+  '    return { decision: "block", matched: true, reason: "write without prior read" };',
+  '  }',
+  '  return { decision: "allow", matched: false, reason: "unknown history fails open" };',
+  '}',
+].join('\n');
+
+/** Same shape, but never blocks — the negative golden case fails under replay. */
+const REPLAY_FAILING_CODE = [
+  'function evaluate(input) {',
+  '  return { decision: "allow", matched: false, reason: "never blocks" };',
+  '}',
+].join('\n');
+
+const GOLDEN_CASES = [
+  { caseId: 'c-neg', kind: 'negative', toolName: 'write_file', params: { path: '/etc/passwd' }, expectedDecision: 'block' },
+  { caseId: 'c-pos', kind: 'positive', toolName: 'write_file', params: { path: '/project/src/safe.ts' }, expectedDecision: 'allow' },
+];
+
+function codeBearingArtificerContent(implementationCode: string): string {
+  return JSON.stringify({
+    implementationCode,
+    goldenTraceCases: GOLDEN_CASES,
+    affectedTools: ['write_file'],
+  });
+}
+
+const dirs: string[] = [];
+
+function makeWorkspace(withDeclaration: boolean): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-runonce-parity-'));
+  dirs.push(dir);
+  if (withDeclaration) {
+    saveHostToolDeclaration(dir, {
+      version: 1,
+      hostKind: 'openclaw',
+      mappings: HOST_MAPPINGS,
+      declaredAt: new Date().toISOString(),
+    });
+  }
+  return dir;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const dir of dirs.splice(0)) {
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* temp */ }
+  }
+});
+
+/**
+ * Seed the dependency chain exactly like the core gate-authority fixture:
+ * artificer(succeeded) + its code-bearing artifact + evaluator(pending,
+ * dep=artificer). The artifact id matches the CLI test-double's default echo.
+ */
+async function seedEvaluatorTask(workspaceDir: string, implementationCode: string): Promise<void> {
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+  await stateManager.initialize();
+  try {
+    const meta = (deps: string[]): string =>
+      createPITaskDiagnosticJson({
+        dependencyTaskIds: deps, channel: 'prompt', timeoutMs: 300_000,
+        inputArtifactRefs: [], outputArtifactRefs: [],
+      });
+    await stateManager.createTask({ taskId: 'artificer-seed', taskKind: 'artificer', status: 'pending', attemptCount: 0, maxAttempts: 3, diagnosticJson: meta([]) });
+    await stateManager.acquireLease({ taskId: 'artificer-seed', owner: 'seed', runtimeKind: 'test-double' });
+    await stateManager.markTaskSucceeded('artificer-seed');
+    await stateManager.createTask({ taskId: 'evaluator-under-test', taskKind: 'evaluator', status: 'pending', attemptCount: 0, maxAttempts: 3, diagnosticJson: meta(['artificer-seed']) });
+    await stateManager.piArtifactStore.upsertArtifact({
+      artifactId: 'pi-art-test-artificer',
+      artifactKind: 'principle',
+      sourceTaskId: 'artificer-seed',
+      lineageArtifactIds: [],
+      validationStatus: 'validated',
+      contentJson: codeBearingArtificerContent(implementationCode),
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    });
+  } finally {
+    await stateManager.close();
+  }
+}
+
+async function readEvaluatorArtifact(workspaceDir: string): Promise<Record<string, unknown> | null> {
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+  await stateManager.initialize();
+  try {
+    const artifacts = await stateManager.piArtifactStore.listBySourceTaskId('evaluator-under-test');
+    const principle = artifacts.find((a) => a.artifactKind === 'principle');
+    return principle ? (JSON.parse(principle.contentJson) as Record<string, unknown>) : null;
+  } finally {
+    await stateManager.close();
+  }
+}
+
+/** The consumer-cycle assembly formula: live registry from the same constants a host passes in memory. */
+function consumerCycleFormulaReplay(implementationCode: string): { passed: boolean; failedCaseCount: number } {
+  const liveRegistry = buildToolSemanticRegistry(HOST_MAPPINGS);
+  if (!liveRegistry.ok) throw new Error(liveRegistry.errors.join('; '));
+  const gateDeps = createProductionGateDeps({ toolSemantics: liveRegistry.registry });
+  // RUNTIME_CONTRACT: the gate structurally validates the trace at runtime;
+  // the fabricated minimal object intentionally omits the full GoldenTrace
+  // provenance fields, so the literal cannot satisfy the parameter type
+  // directly (same documented pattern as evaluator-gate-authority fixtures).
+  const result = gateDeps.evaluateInSandbox(implementationCode, {
+    version: 1,
+    cases: GOLDEN_CASES.map((c) => ({ ...c })),
+    createdAt: '2026-09-04T00:00:00.000Z',
+  } as never);
+  return {
+    passed: result.success,
+    failedCaseCount: result.failedCases.length,
+  };
+}
+
+async function runOnceJson(workspaceDir: string): Promise<{ output: Record<string, unknown>; logSpy: ReturnType<typeof vi.spyOn> }> {
+  const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  const prevExitCode = process.exitCode;
+  try {
+    await handleRuntimeInternalizationRunOnce({
+      workspace: workspaceDir,
+      runner: 'evaluator',
+      runtime: 'test-double',
+      allowTestDouble: true,
+      enqueueNext: false,
+      json: true,
+    });
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).filter((s) => s.trim().startsWith('{'));
+    expect(printed.length).toBeGreaterThan(0);
+    return { output: JSON.parse(printed[0]) as Record<string, unknown>, logSpy };
+  } finally {
+    vi.restoreAllMocks();
+    process.exitCode = prevExitCode;
+  }
+}
+
+describe('run-once evaluator runtime parity (PRI-661)', () => {
+  it('declared workspace: adversarial replay runs to completion and matches the consumer-cycle verdict', async () => {
+    const workspaceDir = makeWorkspace(true);
+    await seedEvaluatorTask(workspaceDir, PASSING_CODE);
+
+    const { output } = await runOnceJson(workspaceDir);
+    expect(output.decision).toBe('would_lease');
+    expect(output.runnerResult, JSON.stringify(output)).toMatchObject({ status: 'succeeded' });
+
+    const artifact = await readEvaluatorArtifact(workspaceDir);
+    expect(artifact).not.toBeNull();
+    const adversarial = (artifact?.adversarialResult ?? null) as { passed?: boolean; failedCases?: unknown[] } | null;
+    expect(adversarial, 'deterministic replay must record adversarialResult').not.toBeNull();
+    expect(adversarial?.passed).toBe(true);
+    expect(adversarial?.failedCases ?? []).toEqual([]);
+
+    // Parity: the SAME code replays to the SAME verdict through the
+    // consumer-cycle assembly formula (live registry, same constants).
+    expect(consumerCycleFormulaReplay(PASSING_CODE)).toEqual({ passed: true, failedCaseCount: 0 });
+  }, 60_000);
+
+  it('declared workspace: a replay-failing rule records passed=false with structured failed cases', async () => {
+    const workspaceDir = makeWorkspace(true);
+    await seedEvaluatorTask(workspaceDir, REPLAY_FAILING_CODE);
+
+    const { output } = await runOnceJson(workspaceDir);
+
+    const artifact = await readEvaluatorArtifact(workspaceDir);
+    expect(artifact).not.toBeNull();
+    const adversarial = (artifact?.adversarialResult ?? null) as { passed?: boolean; failedCases?: Array<{ caseId?: string }> } | null;
+    expect(adversarial).not.toBeNull();
+    expect(adversarial?.passed).toBe(false);
+    // The auto-generated v2 templates expecting block are the ones a
+    // never-blocking rule fails (path-boundary + combination at minimum).
+    const failedIds = (adversarial?.failedCases ?? []).map((c) => c.caseId);
+    expect(failedIds).toContain('v2-path-boundary');
+    expect(failedIds).toContain('v2-combination');
+
+    // The deterministic verdict the approval chain would consume matches the
+    // consumer-cycle formula for the same artifact content.
+    expect(consumerCycleFormulaReplay(REPLAY_FAILING_CODE)).toMatchObject({ passed: false });
+    void output;
+  }, 60_000);
+
+  it('undeclared workspace: refuses BEFORE leasing, structured reason, queue untouched', async () => {
+    const workspaceDir = makeWorkspace(false);
+    await seedEvaluatorTask(workspaceDir, PASSING_CODE);
+
+    const { output } = await runOnceJson(workspaceDir);
+    expect(output.decision).toBe('refused');
+    expect(output.reason).toBe('host_tool_declaration_missing');
+    expect(typeof output.nextAction).toBe('string');
+    expect((output.nextAction as string).length).toBeGreaterThan(0);
+
+    // cli-5: refusal performed NO queue mutation — the evaluator task is
+    // still pending and unleased.
+    const stateManager = new RuntimeStateManager({ workspaceDir });
+    await stateManager.initialize();
+    try {
+      const task = await stateManager.getTask('evaluator-under-test');
+      expect(task?.status).toBe('pending');
+      expect(task?.leasedBy ?? null).toBeNull();
+    } finally {
+      await stateManager.close();
+    }
+  }, 60_000);
+});

package/tests/commands/runtime-internalization-run-once.test.ts

@@ -170,6 +170,21 @@ vi.mock('../../src/config-reader.js', () => ({
   readOutputLanguageFromWorkspace: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
 }));
 
+// PRI-661: run-once now builds the evaluator replay context through the ONE
+// host-runtime builder. Mock just that seam here — the unit tests below prove
+// dispatch wiring; the real resolver + declaration fixture path is proven by
+// runtime-internalization-run-once-evaluator-parity.test.ts.
+const { mockCreateEvaluatorRuntimeContext } = vi.hoisted(() => {
+  const mockCreateEvaluatorRuntimeContext = vi.fn().mockReturnValue({
+    ok: true,
+    gateDeps: { evaluateInSandbox: vi.fn() },
+  });
+  return { mockCreateEvaluatorRuntimeContext };
+});
+vi.mock('@principles/host-runtime', () => ({
+  createEvaluatorRuntimeContext: mockCreateEvaluatorRuntimeContext,
+}));
+
 import { handleRuntimeInternalizationRunOnce } from '../../src/commands/runtime-internalization-run-once.js';
 
 const WS = '/fake/workspace';
@@ -1136,6 +1151,28 @@ describe('handleRuntimeInternalizationRunOnce', () => {
     expect(output.runnerResult.status).toBe('succeeded');
   });
 
+  it('--runner evaluator refuses BEFORE leasing when the runtime context is unresolvable (PRI-661)', async () => {
+    mockCreateEvaluatorRuntimeContext.mockReturnValueOnce({
+      ok: false,
+      reason: 'host_tool_declaration_missing',
+      nextAction: 'start a host (OpenClaw/Codex) once so it persists its tool declaration',
+    });
+
+    await handleRuntimeInternalizationRunOnce({ workspace: WS, runner: 'evaluator', runtime: 'test-double', allowTestDouble: true, json: true });
+
+    // cli-5: refusal must not lease/advance any task.
+    expect(mockWakeOnce).not.toHaveBeenCalled();
+    const EvaluatorRunnerMock = vi.mocked(
+      await import('@principles/core/runtime-v2').then(m => m.EvaluatorRunner),
+    );
+    expect(EvaluatorRunnerMock).not.toHaveBeenCalled();
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+    expect(output.decision).toBe('refused');
+    expect(output.reason).toBe('host_tool_declaration_missing');
+    expect(output.nextAction).toContain('host');
+  });
+
   it('auto-enqueue: --runner evaluator returns successor decision', async () => {
     mockWakeOnce.mockResolvedValue({
       decision: 'would_lease',

package/tests/e2e/cross-package-acceptance.test.ts

@@ -37,6 +37,8 @@ import {
   createSandboxGateDeps,
 } from '../../src/services/rulehost-pipeline-runner.js';
 import { RuleHost } from '../../../openclaw-plugin/src/core/rule-host.js';
+import { OPENCLAW_TOOL_SEMANTIC_MAPPINGS } from '../../../openclaw-plugin/src/constants/tool-semantics.js';
+import { saveHostToolDeclaration } from '@principles/host-runtime';
 import type { CodeRuleCapability } from '../../src/services/rulehost-pipeline-runner.js';
 import type { PDRuntimeAdapter, RunHandle, RunStatus, PIArtifactStore, RuntimeCapabilities, RuntimeHealth, RuntimeArtifactRef, ContextItem, StructuredRunOutput, StartRunInput } from '@principles/core/runtime-v2';
 import {
@@ -204,6 +206,16 @@ let tmpDir = '';
 function makeTmpDir(): string {
   const dir = path.join(os.tmpdir(), `pd-xpkg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
   fs.mkdirSync(dir, { recursive: true });
+  // PRI-661: the pipeline's evaluator replay resolves the production gate
+  // context from durable workspace provenance. Seed the declaration the real
+  // OpenClaw host would persist on startup (same mapping constants), so the
+  // generation-time replay and the activation gate see the same registry.
+  saveHostToolDeclaration(dir, {
+    version: 1,
+    hostKind: 'openclaw',
+    mappings: OPENCLAW_TOOL_SEMANTIC_MAPPINGS,
+    declaredAt: new Date().toISOString(),
+  });
   return dir;
 }
 

package/tests/services/rulehost-pipeline-runner.test.ts

@@ -20,6 +20,7 @@ import { runRuleHostPipeline } from '../../src/services/rulehost-pipeline-runner
 import type { CodeRuleCapability } from '../../src/services/rulehost-pipeline-runner.js';
 import type { PDRuntimeAdapter, RunHandle, RunStatus, PIArtifactStore, RuntimeCapabilities, RuntimeHealth, RuntimeArtifactRef, ContextItem, StructuredRunOutput, StartRunInput } from '@principles/core/runtime-v2';
 import { RuntimeStateManager, createPITaskDiagnosticJson } from '@principles/core/runtime-v2';
+import { saveHostToolDeclaration } from '@principles/host-runtime';
 
 type StageFactory = (taskId: string, priorArtifactId?: string) => unknown;
 type EvaluatorFactory = (taskId: string, artificerArtifactId: string) => unknown;
@@ -192,6 +193,19 @@ let tmpDir = '';
 function makeTmpDir(): string {
   const dir = path.join(os.tmpdir(), `pd-pipe-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
   fs.mkdirSync(dir, { recursive: true });
+  // PRI-661: the pipeline's evaluator replay resolves the production gate
+  // context from durable workspace provenance — seed a declaration like every
+  // real host does on startup.
+  saveHostToolDeclaration(dir, {
+    version: 1,
+    hostKind: 'testhost',
+    mappings: [
+      { rawToolName: 'Write', canonicalKind: 'write' },
+      { rawToolName: 'Edit', canonicalKind: 'write' },
+      { rawToolName: 'Bash', canonicalKind: 'execute' },
+    ],
+    declaredAt: new Date().toISOString(),
+  });
   return dir;
 }
 

package/tests/services/workspace-tool-semantics.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Workspace Tool Semantics Resolution tests — PRI-634-F R2 (review P1-2)
+ *
+ * The CLI must resolve the host registry from DURABLE workspace provenance
+ * and refuse (never guess, never silently skip) when unavailable.
+ */
+
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { resolveWorkspaceToolSemantics } from '../../src/services/workspace-tool-semantics.js';
+
+let ws: string;
+
+beforeEach(() => {
+  ws = mkdtempSync(path.join(tmpdir(), 'pd-wts-'));
+});
+
+afterEach(() => {
+  rmSync(ws, { recursive: true, force: true });
+});
+
+function writeDeclaration(payload: unknown, hostKind = 'openclaw'): void {
+  // R3: per-host partition — <ws>/.pd/host-tool-semantics/<hostKind>.json
+  mkdirSync(path.join(ws, '.pd', 'host-tool-semantics'), { recursive: true });
+  writeFileSync(path.join(ws, '.pd', 'host-tool-semantics', `${hostKind}.json`), JSON.stringify(payload), 'utf8');
+}
+
+describe('resolveWorkspaceToolSemantics', () => {
+  it('resolves a valid persisted host declaration into a host-layered registry', () => {
+    writeDeclaration({
+      version: 1,
+      hostKind: 'openclaw',
+      mappings: [
+        { rawToolName: 'shell', canonicalKind: 'execute' },
+        { rawToolName: 'write_file', canonicalKind: 'write' },
+      ],
+      declaredAt: '2026-09-04T00:00:00.000Z',
+    });
+    const result = resolveWorkspaceToolSemantics(ws);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.hostKind).toBe('openclaw');
+    expect(result.registry.hasHostTool('shell')).toBe(true);
+    // Core baseline names still classify, but are NOT host-declared here.
+    expect(result.registry.hasHostTool('execute_command')).toBe(false);
+    expect(result.registry.hasHostTool('read_file')).toBe(false);
+  });
+
+  it('missing declaration → structured failure with actionable nextAction (no guessing)', () => {
+    const result = resolveWorkspaceToolSemantics(ws);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe('host_tool_declaration_missing');
+    expect(result.nextAction).toContain('host');
+  });
+
+  it('malformed declaration → host_tool_declaration_invalid, never baseline fallback', () => {
+    writeDeclaration({ version: 1, hostKind: 'x', mappings: [{ rawToolName: 'bad', canonicalKind: 'nope' }], declaredAt: 't' });
+    const result = resolveWorkspaceToolSemantics(ws);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain('host_tool_declaration_invalid');
+    expect(result.reason).toContain('openclaw');
+  });
+
+  it('not JSON at all → host_tool_declaration_invalid (per-host file)', () => {
+    mkdirSync(path.join(ws, '.pd', 'host-tool-semantics'), { recursive: true });
+    writeFileSync(path.join(ws, '.pd', 'host-tool-semantics', 'openclaw.json'), '{not json', 'utf8');
+    const result = resolveWorkspaceToolSemantics(ws);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe('host_tool_declaration_invalid (openclaw: not valid JSON)');
+  });
+});