@principles/pd-cli 1.145.1 → 1.146.0

package/src/commands/pain-record.ts

@@ -2,6 +2,13 @@
  * pd pain record command — Runtime v2 pain signal entry point.
  *
  * Uses PainToPrincipleService as the single write-side orchestration API.
+ * PRI-642 (review blocker 1): the ingress semantic interpretation — origin,
+ * bound/unbound correlation, provenance derivation, sentinel handling,
+ * submit/degrade/refuse semantics and painIngress.v1 construction — comes
+ * from the SHARED evaluator `evaluatePainIngress` in @principles/core
+ * (the same authority the OpenClaw funnel uses). This adapter only does
+ * host-specific ACQUISITION: read --session, validate it against this
+ * workspace's trajectory.db, and collect raw evidence entries.
  *
  * Usage:
  *   pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--session <id>] [--json]
@@ -13,10 +20,12 @@ import {
   isRuntimeConfigError,
   isFeatureEnabled,
   isBuiltinPiAiProvider,
+  evaluatePainIngress,
 } from '@principles/core/runtime-v2';
+import type { PainIngressDecision, IngressEvidenceEntry, PainEvidenceEntry } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
-import { buildTrajectoryEvidenceFromDb } from './build-trajectory-evidence.js';
+import { acquireTrajectoryEvidenceFromDb } from './build-trajectory-evidence.js';
 
 interface RecordOptions {
   reason?: string;
@@ -28,6 +37,125 @@ interface RecordOptions {
   wait?: boolean;
 }
 
+function emitSessionBindingFailure(
+  opts: RecordOptions,
+  failure: { reason: string; message: string; nextAction: string },
+): void {
+  if (opts.json) {
+    console.log(JSON.stringify({
+      status: 'failed',
+      reason: failure.reason,
+      message: failure.message,
+      nextAction: failure.nextAction,
+    }, null, 2));
+  } else {
+    console.error(`Error: ${failure.message}`);
+    console.error(`Reason: ${failure.reason}`);
+    console.error(`Next action: ${failure.nextAction}`);
+  }
+  process.exit(1);
+}
+
+function toIngressEntry(entry: PainEvidenceEntry): IngressEvidenceEntry {
+  // Trajectory evidence references observed behavior (owner messages,
+  // assistant turns, tool-call failures) — behavior traces.
+  return { kind: 'behavior_trace', sourceRef: entry.sourceRef, note: entry.note };
+}
+
+/**
+ * PRI-642 (SPEC §7.3/§7.4, review blocker 1): build the report from this
+ * adapter's host-specific facts and let the SHARED evaluator decide.
+ *
+ * Per-channel policy (SPEC §7.3 vs OpenClaw):
+ *
+ * - explicit `--session` + acquisition available (real session + real entries):
+ *     → cli_explicit_session + bound → submit with real evidence.
+ * - explicit `--session` + acquisition unavailable (session_not_found /
+ *     empty_trajectory / trajectory_unavailable / evidence_read_failed):
+ *     → cli_explicit_session + unbound → shared evaluator REFUSES
+ *       (row 5) before any LLM/task/candidate mutation.
+ *     The CLI does NOT share the OpenClaw funnel's "degrade" semantics
+ *     because the CLI does not own the session identity the way the host
+ *     command context does (Evidence Over Assumption — an unverified
+ *     session claimed as bound would be a PRI-642 recurrence).
+ * - no `--session` → unbound Owner report (matrix row 6) → submit with
+ *   disclosure; no sentinel session, no placeholder evidence, no trajectory
+ *   projection (the CLI skips observability when the ingress yields no
+ *   bound session — SPEC §7.4).
+ */
+function resolveIngressDecision(
+  input: { opts: RecordOptions; stateDir: string; workspaceDir: string; painId: string },
+): { decision: PainIngressDecision; acquisitionDetail: string | null; acquisitionReason: string | null } {
+  const { opts, stateDir, workspaceDir, painId } = input;
+  const score = opts.score ?? 80;
+  const base = {
+    identity: { kind: 'manual_pain_id' as const, painId },
+    painType: 'user_frustration' as const,
+    source: opts.source ?? 'manual',
+    reason: opts.reason ?? '',
+    score,
+  };
+
+  if (!opts.session) {
+    // No --session: external unbound Owner report (matrix row 6). Allowed
+    // by SPEC §7.4 with a disclosure warning; never claims host binding.
+    const decision = evaluatePainIngress({
+      ...base,
+      origin: { kind: 'owner_manual', channel: 'external_cli_unbound' },
+      correlation: { status: 'unbound', reason: 'external_cli' },
+      evidence: { status: 'unavailable', reason: 'not_applicable_unbound' },
+    });
+    return { decision, acquisitionDetail: null, acquisitionReason: null };
+  }
+
+  // --session: SPEC §7.3 demands a fail-loud refusal whenever the CLI
+  // cannot actually verify the claimed binding. We do not share the
+  // OpenClaw funnel's "degrade" semantics here because the CLI does
+  // not own the session identity the way the host command context does
+  // (Evidence Over Assumption): an unverified session that we still
+  // claimed as bound would be a PRI-642 recurrence in a different
+  // shape. Per-channel policy differs; semantic authority is shared.
+  const acquisition = acquireTrajectoryEvidenceFromDb(stateDir, opts.session, workspaceDir);
+  if (acquisition.status === 'unavailable') {
+    // session_not_found / empty_trajectory / trajectory_unavailable /
+    // evidence_read_failed — refuse (row 5) before any LLM/task/candidate
+    // mutation. The CLI surfaces the reasonCode with a SPEC §7.3 next
+    // action; the evaluator produces the refuse decision.
+    const {reasonCode} = acquisition;
+    const decision = evaluatePainIngress({
+      ...base,
+      origin: { kind: 'owner_manual', channel: 'cli_explicit_session' },
+      correlation: { status: 'unbound', reason: 'external_cli' },
+      evidence: { status: 'unavailable', reason: reasonCode === 'session_not_found' ? 'not_applicable_unbound' : reasonCode },
+    });
+    if (decision.action === 'refuse') {
+      return { decision, acquisitionDetail: acquisition.detail, acquisitionReason: reasonCode };
+    }
+  }
+
+  // Available evidence: a real session with real entries — submit, bound.
+  if (acquisition.status === 'available') {
+    const decision = evaluatePainIngress({
+      ...base,
+      origin: { kind: 'owner_manual', channel: 'cli_explicit_session' },
+      correlation: { status: 'bound', hostKind: 'openclaw', sessionId: opts.session },
+      evidence: { status: 'available', entries: acquisition.entries.map(toIngressEntry) as [IngressEvidenceEntry, ...IngressEvidenceEntry[]] },
+    });
+    return { decision, acquisitionDetail: null, acquisitionReason: null };
+  }
+
+  // Exhaustive — acquireTrajectoryEvidenceFromDb returns {available, unavailable}
+  // only. The empty-trajectory branch was collapsed to refuse above; a
+  // future-added reason would land here and must also refuse.
+  const decision = evaluatePainIngress({
+    ...base,
+    origin: { kind: 'owner_manual', channel: 'cli_explicit_session' },
+    correlation: { status: 'unbound', reason: 'external_cli' },
+    evidence: { status: 'unavailable', reason: 'not_applicable_unbound' },
+  });
+  return { decision, acquisitionDetail: null, acquisitionReason: null };
+}
+
 export async function handlePainRecord(opts: RecordOptions): Promise<void> {
   if (!opts.reason) {
     console.error('Error: --reason <text> is required');
@@ -50,24 +178,57 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
       }, null, 2));
     } else {
       console.error(`Error: --reason must be at most ${MAX_REASON_LENGTH} characters (got ${opts.reason.length})`);
-      console.error('Next action: shorten the reason text or split into multiple pain records.');
+      console.error('Next action: shorten the reason text or split it into multiple pain records.');
     }
     process.exit(1);
     return;
   }
 
   if (opts.score !== undefined && (isNaN(opts.score) || opts.score < 0 || opts.score > 100)) {
-    console.error('Error: --score must be a number between 0 and 100');
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'failed',
+        reason: 'score_invalid',
+        message: '--score must be a number between 0 and 100',
+        nextAction: 'Provide --score as an integer from 0 to 100, or omit it for the default (80).',
+      }, null, 2));
+    } else {
+      console.error('Error: --score must be a number between 0 and 100');
+      console.error('Next action: provide --score as an integer from 0 to 100, or omit it for the default (80).');
+    }
     process.exit(1);
+    return;
   }
 
   const workspaceDir = resolveWorkspaceDir(opts.workspace);
   const stateDir = `${workspaceDir}/.state`;
   const painId = `manual_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 
-  // PRI-341: Build evidence from trajectory DB if session provided
-  const effectiveSessionId = opts.session ?? 'cli';
-  const evidence = buildTrajectoryEvidenceFromDb(stateDir, opts.session, workspaceDir);
+  // PRI-642: run the SHARED ingress evaluator before any service/LLM/task
+  // mutation; the decision (submit/degrade/refuse) is not made here.
+  const { decision, acquisitionDetail, acquisitionReason } = resolveIngressDecision({ opts, stateDir, workspaceDir, painId });
+
+  if (decision.action === 'refuse') {
+    // SPEC §7.3: the CLI must surface the specific acquisition reason
+    // (session_not_found / empty_trajectory / trajectory_unavailable /
+    // evidence_read_failed) — the shared evaluator produces the refuse
+    // decision; we map the acquisition detail to the Operator reason.
+    const reason = opts.session !== undefined && acquisitionReason !== null
+      ? acquisitionReason
+      : decision.reasonCode;
+    const detailSuffix = acquisitionDetail !== null ? ` (${acquisitionDetail})` : '';
+    emitSessionBindingFailure(opts, {
+      reason,
+      message: `${decision.warning}${detailSuffix}`,
+      nextAction: decision.nextAction,
+    });
+    return;
+  }
+
+  const binding = decision.legacy;
+  // SPEC §7.4: without a bound session the trajectory projection is skipped
+  // (disclosed below) instead of fabricating the sentinel session 'cli'.
+  const recordObservability = binding.sessionId !== undefined;
 
   const ledgerAdapter = new PrincipleTreeLedgerAdapter({ stateDir });
   // PRI-306: Load .pd/config.yaml for config-driven runtime binding
@@ -104,11 +265,13 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
     source: opts.source ?? 'manual',
     reason: opts.reason,
     score: opts.score ?? 80,
-    sessionId: effectiveSessionId,
+    sessionId: binding.sessionId,
     agentId: 'pd-cli',
-    provenance: 'owner_reported_no_host_trace',
-    evidence,
-    recordObservability: true,
+    provenance: binding.provenance,
+    hostKind: binding.hostKind,
+    evidence: binding.evidence,
+    recordObservability,
+    painIngress: binding.painIngress,
   });
 
   // Show diagnostic info for config failures
@@ -181,6 +344,25 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
     }
   }
 
+  // PRI-642 (SPEC §12.1.6): generated-but-unadmitted candidates must never
+  // read as completed internalization — surface the admission disposition.
+  const admissionDecisions = result.admissionResults?.map(r => r.admission.decision) ?? [];
+  const admittedCount = admissionDecisions.filter(d => d === 'admitted').length;
+  const gatedWarning = result.status === 'succeeded'
+    && result.candidateIds.length > 0
+    && admittedCount === 0
+    ? `admitted: 0 of ${result.candidateIds.length} candidates (all gated — needs_evidence/deferred); `
+      + 'nothing was internalized. See admissionResults for per-candidate reasons; add --session evidence or Owner context to raise confidence above the admission threshold.'
+    : null;
+  // PRI-642: the ingress decision's own disclosures (degrade warning /
+  // unbound context_unbound warning) are surfaced to the operator.
+  const decisionWarnings = decision.action === 'degrade'
+    ? [`${decision.warning} Next action: ${decision.nextAction}`]
+    : decision.action === 'submit'
+      ? decision.warnings
+      : [];
+  const cliWarnings = [...decisionWarnings, gatedWarning].filter((w): w is string => w !== null && w !== undefined);
+
   if (opts.json) {
     const out: Record<string, unknown> = { ...result };
     // Ensure nextAction is present for actionable states
@@ -191,13 +373,22 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
       if (!out.reason) {
         out.reason = out.message;
       }
-      // PRI-570: async submission has NO automatic consumer — the
-      // internalization auto-consumer's runner kinds (dreamer..rollout_reviewer)
-      // do not include 'diagnostician', so a submitted task stays pending until
-      // the owner runs the diagnose command. Never let that stay implicit (rc-9).
-      out.warning = 'Async mode: no background consumer picks up diagnostician tasks. '
+    }
+    // PRI-570: async submission has NO automatic consumer — the
+    // internalization auto-consumer's runner kinds (dreamer..rollout_reviewer)
+    // do not include 'diagnostician', so a submitted task stays pending until
+    // the owner runs the diagnose command. Never let that stay implicit (rc-9).
+    // PRI-642: unbound/gated disclosures join the same warnings channel.
+    const submittedWarning = out.status === 'submitted'
+      ? 'Async mode: no background consumer picks up diagnostician tasks. '
         + `Run ${out.nextAction} or the pain signal will remain pending indefinitely. `
-        + 'Use --wait to diagnose synchronously instead.';
+        + 'Use --wait to diagnose synchronously instead.'
+      : null;
+    const allWarnings = [...cliWarnings];
+    if (submittedWarning !== null) allWarnings.unshift(submittedWarning);
+    if (allWarnings.length > 0) {
+      out.warning = allWarnings.join(' ');
+      out.warnings = allWarnings;
     }
     console.log(JSON.stringify(out, null, 2));
     if (result.status !== 'succeeded' && result.status !== 'skipped' && result.status !== 'retried' && result.status !== 'submitted') {
@@ -213,11 +404,28 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
       if (result.artifactId) console.log(`   Artifact ID: ${result.artifactId}`);
       if (result.candidateIds.length > 0) console.log(`   Candidate IDs: ${result.candidateIds.join(', ')}`);
       if (result.ledgerEntryIds.length > 0) console.log(`   Ledger Entry IDs: ${result.ledgerEntryIds.join(', ')}`);
+      if (result.progress && result.progress.seededTaskIds.length > 0) {
+        console.log(`   Seeded Task IDs: ${result.progress.seededTaskIds.join(', ')}`);
+      }
       console.log(`   Reason: ${opts.reason}`);
       console.log(`   Score: ${opts.score ?? 80}`);
       console.log(`   Source: ${opts.source ?? 'manual'}`);
       console.log(`   Workspace: ${workspaceDir}`);
+      if (binding.sessionId) {
+        console.log(`   Session: ${binding.sessionId} (bound, ${binding.evidence.length} evidence entries)`);
+      } else {
+        console.log('   Session: unbound (Owner report; no trajectory evidence)');
+      }
+      if (result.admissionResults && result.admissionResults.length > 0) {
+        console.log(`   Admission: ${admittedCount} of ${result.admissionResults.length} candidates admitted`);
+        for (const r of result.admissionResults) {
+          console.log(`     - ${r.candidateId}: ${r.admission.decision} (${r.admission.reason})`);
+        }
+      }
       if (result.latencyMs !== undefined) console.log(`   Latency: ${result.latencyMs}ms`);
+      for (const w of cliWarnings) {
+        console.warn(`   ⚠️  ${w}`);
+      }
       console.log(`\nDiagnostician pipeline running. Check progress with:`);
       console.log(`   pd task show ${result.taskId} --workspace "${workspaceDir}"`);
     } else if (result.status === 'submitted') {

package/src/commands/pain-retry.ts

@@ -24,7 +24,6 @@ import {
   DiagRouterRunner,
   DefaultDiagRootCauseValidator,
   DefaultDiagDistillerValidator,
-  DisabledDiagnosticianRunner,
   type DiagnosticianRunnerLike,
   TestDoubleRuntimeAdapter,
   OpenClawCliRuntimeAdapter,
@@ -33,8 +32,8 @@ import {
   isRuntimeConfigError,
   CandidateIntakeService,
   run as diagnoseRun,
-  isFeatureEnabled,
   SPLIT_PIPELINE_TOTAL_TIMEOUT_MS,
+  resolveDiagnosticianCapability,
   PrincipleTreeLedgerAdapter,
   SqliteDeadLetterStore,
   PainSignalBridge,
@@ -44,7 +43,7 @@ import {
 } from '@principles/core/runtime-v2';
 import type { PDRuntimeAdapter, RuntimeConfig, OutputLanguage } from '@principles/core/runtime-v2';
 import type { Command } from 'commander';
-import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
+import { loadPdConfig } from '../services/pd-config-loader.js';
 import { resolveRuntimeFromPdConfig } from '../services/resolve-runtime-from-pd-config.js';
 import { createHash } from 'node:crypto';
 /** Layer 0 content-hash (design §6.1); injected so diag writers can attach predecessorSummary hashes. */
@@ -226,6 +225,9 @@ function refuseExit(opts: PainRetryOptions, payload: { status?: string; painId:
     }));
   } else {
     console.error(`error: ${payload.message ?? payload.reason}`);
+    // PRI-638: the reason must be visible in text mode too — an Owner kill
+    // switch (capability_disabled) must not read like a runtime fault.
+    console.error(`reason: ${payload.reason}`);
     console.error(`nextAction: ${payload.nextAction}`);
   }
   process.exit(1);
@@ -245,6 +247,28 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
 
   const { taskId } = resolution;
 
+  // PRI-638: the capability gate comes BEFORE runtime resolution. Previously an
+  // Owner-disabled Diagnostician surfaced here as `missing_runtime` ("no
+  // .pd/config.yaml runtime binding found"), which told the Owner their config
+  // was broken when they had deliberately switched the agent off. This reads the
+  // same canonical authority (`internalAgents.agents.diagnostician.enabled`) the
+  // runtime factory uses — the CLI owns no kill switch of its own.
+  const capability = resolveDiagnosticianCapability(
+    (() => {
+      const loaded = loadPdConfig(workspaceDir);
+      return loaded.ok ? loaded.effective : loaded.defaults;
+    })(),
+  );
+  if (!capability.available) {
+    return refuseExit(opts, {
+      painId: opts.painId,
+      taskId,
+      reason: capability.reason,
+      message: capability.message,
+      nextAction: capability.nextAction,
+    });
+  }
+
   // Step 2: Look up task and validate
   const stateManager = new RuntimeStateManager({ workspaceDir });
 
@@ -522,17 +546,18 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
     const outputLangResult = readOutputLanguageFromWorkspace(workspaceDir);
     const outputLanguage: OutputLanguage | undefined = outputLangResult.outputLanguage;
 
-    // Check if split pipeline is enabled — 3 serial LLM calls need more time
-    const configLoadResult = loadPdConfig(workspaceDir);
-    const featureFlags = computeFlagsFromLoadResult(configLoadResult);
-    const isSplitPipeline = isFeatureEnabled(featureFlags, 'diagnostician_split_pipeline');
-    const pipelineTimeoutMs = isSplitPipeline ? SPLIT_PIPELINE_TOTAL_TIMEOUT_MS : 300_000;
+    // PRI-638: implementation selection is gone. The split pipeline is the only
+    // Diagnostician implementation, so it always runs with its documented
+    // 3-stage budget; `diagnostician_split_pipeline` no longer selects a runner
+    // nor disables capability (the capability gate above owns that).
+    const pipelineTimeoutMs = SPLIT_PIPELINE_TOTAL_TIMEOUT_MS;
     // BUG-1 (PRI-442): extract effectiveConfig so ADR-0019 LLM rate-limit
     // degradation (isDegradationEnabled in base-peer-runner) can read the
     // diagnostician_llm_degradation feature flag. Without this, the runners
     // receive no effectiveConfig and degradation silently never fires.
     // CR-1 (CodeRabbit P2, rc-9): warn when config load failed so the
     // fallback to defaults is observable — no silent degradation.
+    const configLoadResult = loadPdConfig(workspaceDir);
     if (!configLoadResult.ok) {
       const errSummary = configLoadResult.errors
         .map((e) => `${e.path}: ${e.reason}`)
@@ -543,34 +568,29 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
     }
     const effectiveConfig = configLoadResult.ok ? configLoadResult.effective : configLoadResult.defaults;
 
-    let runner: DiagnosticianRunnerLike;
-    if (isSplitPipeline) {
-      const resolvedKind = typeof runtimeAdapter.kind === 'function' ? runtimeAdapter.kind() : runtimeKind;
-      const perStageTimeoutMs = pipelineTimeoutMs / 3;
-      const rootCauseRunner = new DiagRootCauseRunner(
-        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagRootCauseValidator(), contextAssembler, contentHashFn },
-        { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
-      );
-      const distillerRunner = new DiagDistillerRunner(
-        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagDistillerValidator(), contentHashFn },
-        { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
-      );
-      const routerRunner = new DiagRouterRunner(
-        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, committer, contentHashFn },
-        { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
-      );
-
-      runner = new SplitDiagnosticianRunner({
-        rootCauseRunner,
-        distillerRunner,
-        routerRunner,
-        stateManager,
-        committer,
-        perStageTimeoutMs,
-      });
-    } else {
-      runner = new DisabledDiagnosticianRunner();
-    }
+    const resolvedKind = typeof runtimeAdapter.kind === 'function' ? runtimeAdapter.kind() : runtimeKind;
+    const perStageTimeoutMs = pipelineTimeoutMs / 3;
+    const rootCauseRunner = new DiagRootCauseRunner(
+      { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagRootCauseValidator(), contextAssembler, contentHashFn },
+      { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
+    );
+    const distillerRunner = new DiagDistillerRunner(
+      { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagDistillerValidator(), contentHashFn },
+      { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
+    );
+    const routerRunner = new DiagRouterRunner(
+      { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, committer, contentHashFn },
+      { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
+    );
+
+    const runner: DiagnosticianRunnerLike = new SplitDiagnosticianRunner({
+      rootCauseRunner,
+      distillerRunner,
+      routerRunner,
+      stateManager,
+      committer,
+      perStageTimeoutMs,
+    });
 
     // ── Dead letter replay branch ──────────────────────────────────────────
     // When task was null but a dead letter was found, replay the pain signal

package/src/index.ts

@@ -122,7 +122,7 @@ painCmd
   .option('-s, --score <number>', 'Pain score 0-100', parseInt)
   .option('-S, --source <text>', 'Source of the pain signal', 'manual')
   .option('-w, --workspace <path>', 'Workspace directory')
-  .option('--session <id>', 'OpenClaw session ID for trajectory evidence extraction')
+  .option('--session <id>', 'Session ID to bind (validated against this workspace\'s trajectory.db; without it the record is unbound: no trajectory evidence, candidates likely gated by the admission threshold)')
   .option('--wait', 'Wait for diagnosis to complete (sync mode, overrides async flag)')
   .option('--json', 'Output raw JSON')
   .action(async (opts) => {

package/tests/bdd/cli-contract.steps.ts

@@ -133,6 +133,9 @@ vi.mock('@principles/core/runtime-v2', () => {
     OpenClawCliRuntimeAdapter: vi.fn().mockImplementation(function () { return {}; }),
     PiAiRuntimeAdapter: vi.fn().mockImplementation(function () { return {}; }),
     SPLIT_PIPELINE_TOTAL_TIMEOUT_MS: 300000,
+    // PRI-638: capability gate — available by default so the BDD scenarios
+    // exercise the pre-existing success/failure JSON contracts unchanged.
+    resolveDiagnosticianCapability: vi.fn(() => ({ available: true })),
     PDRuntimeError: class PDRuntimeError extends Error {
       constructor(public category: string, message: string) {
         super(message);