@principles/pd-cli 1.147.16 → 1.148.0

package/src/commands/pain-list.ts

@@ -3,6 +3,8 @@
  *
  * Read-only: lists canonical pain_events rows from trajectory.db with their
  * host attribution. `--host` filters by openclaw / codex / unknown.
+ * PRI-743: the result (human and --json) also carries `byHost`, the
+ * full-table host distribution independent of --host/--limit.
  *
  * Usage:
  *   pd pain list [--workspace <path>] [--limit N] [--host openclaw|codex|unknown] [--json]
@@ -43,6 +45,14 @@ export interface PainListResult {
   pains: PainListEntry[];
   workspace: string;
   hostFilter: PainListHostFilter | null;
+  /**
+   * PRI-743: full-table host distribution (independent of --limit and --host
+   * filtering) so operator tooling can group by host without an external
+   * script. `null` only on a pre-PRI-640 database without the host_kind
+   * column — the distribution is unprovable there, never guessed (rc-3/rc-9;
+   * see the accompanying host_kind_column_missing warning).
+   */
+  byHost: { openclaw: number; codex: number; unknown: number } | null;
   warnings: string[];
 }
 
@@ -91,6 +101,27 @@ export async function listPains(dbPath: string, options: { limit?: number; host?
       warnings.push('host_kind_column_missing');
     }
 
+    // PRI-743: full-table distribution, deliberately NOT narrowed by the
+    // --host filter or --limit below — the operator question this answers is
+    // "how do pains split across hosts in this workspace", which a filtered
+    // count cannot answer. Non-openclaw/codex values (incl. NULL) count as
+    // unknown, mirroring toPainEntry's read-side normalization.
+    const byHost: PainListResult['byHost'] = hasHostKindColumn
+      ? { openclaw: 0, codex: 0, unknown: 0 }
+      : null;
+    if (byHost) {
+      const distRows: unknown[] = db
+        .prepare("SELECT COALESCE(host_kind, 'unknown') AS host_bucket, COUNT(*) AS n FROM pain_events GROUP BY host_kind")
+        .all();
+      for (const row of distRows) {
+        const bucket = ownField(row, 'host_bucket');
+        const n = ownField(row, 'n');
+        if ((bucket === 'openclaw' || bucket === 'codex' || bucket === 'unknown') && typeof n === 'number') {
+          byHost[bucket] += n;
+        }
+      }
+    }
+
     const params: (string | number)[] = [];
     let query = 'SELECT id, source, score, severity, created_at, canonical_pain_id, runtime_task_id';
     query += hasHostKindColumn ? ', host_kind' : ", NULL AS host_kind";
@@ -99,7 +130,7 @@ export async function listPains(dbPath: string, options: { limit?: number; host?
       query += hasHostKindColumn ? ' AND host_kind IS NULL' : '';
     } else if (options.host === 'openclaw' || options.host === 'codex') {
       if (!hasHostKindColumn) {
-        return { count: 0, pains: [], workspace: path.dirname(path.dirname(dbPath)), hostFilter: options.host, warnings };
+        return { count: 0, pains: [], workspace: path.dirname(path.dirname(dbPath)), hostFilter: options.host, byHost, warnings };
       }
       query += ' AND host_kind = ?';
       params.push(options.host);
@@ -122,6 +153,7 @@ export async function listPains(dbPath: string, options: { limit?: number; host?
       pains,
       workspace: path.dirname(path.dirname(dbPath)),
       hostFilter: options.host ?? null,
+      byHost,
       warnings,
     };
   } finally {
@@ -132,6 +164,10 @@ export async function listPains(dbPath: string, options: { limit?: number; host?
 function printHuman(result: PainListResult): void {
   const filterNote = result.hostFilter ? ` (host: ${result.hostFilter})` : '';
   console.log(`Pain events — ${result.count} shown${filterNote}`);
+  if (result.byHost) {
+    const { openclaw, codex, unknown } = result.byHost;
+    console.log(`By host: openclaw=${openclaw} codex=${codex} unknown=${unknown}`);
+  }
   console.log('─'.repeat(96));
   for (const pain of result.pains) {
     const painId = pain.painId.length > 40 ? `${pain.painId.slice(0, 37)}...` : pain.painId;

package/src/commands/pain-record.ts

@@ -11,7 +11,16 @@
  * workspace's trajectory.db, and collect raw evidence entries.
  *
  * Usage:
- *   pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--session <id>] [--json]
+ *   pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--session <id>] [--host openclaw|codex] [--json]
+ *
+ * PRI-743: `--host` makes host attribution explicit instead of assumed.
+ * `--host openclaw` records the default attribution without the disclosure
+ * warning; `--host codex` refuses loudly — the CLI can verify OpenClaw
+ * trajectory sessions but can never verify a Codex lineage tuple
+ * (rolloutIdentity / logicalObservationKey, rc-6), so codex pains must come
+ * from the Codex ingestion path, never from the CLI. The correlation schema
+ * itself is NOT changed — PainIngressCorrelationV1 bound branches only admit
+ * openclaw/codex.
  */
 import {
   PainToPrincipleService,
@@ -35,6 +44,8 @@ interface RecordOptions {
   json?: boolean;
   session?: string;
   wait?: boolean;
+  /** PRI-743: explicit host attribution for a bound --session pain. */
+  host?: string;
 }
 
 function emitSessionBindingFailure(
@@ -135,10 +146,16 @@ function resolveIngressDecision(
 
   // Available evidence: a real session with real entries — submit, bound.
   if (acquisition.status === 'available') {
+    // PRI-743: host attribution is explicit when --host openclaw is given;
+    // absent --host keeps the pre-PRI-743 'openclaw' default (validated and
+    // disclosed by handlePainRecord — rc-9). --host codex never reaches this
+    // point: it is refused before any mutation (no verifiable lineage), so
+    // the bound correlation below is always the openclaw shape.
+    const hostKind = 'openclaw' as const;
     const decision = evaluatePainIngress({
       ...base,
       origin: { kind: 'owner_manual', channel: 'cli_explicit_session' },
-      correlation: { status: 'bound', hostKind: 'openclaw', sessionId: opts.session },
+      correlation: { status: 'bound', hostKind, sessionId: opts.session },
       evidence: { status: 'available', entries: acquisition.entries.map(toIngressEntry) as [IngressEvidenceEntry, ...IngressEvidenceEntry[]] },
     });
     return { decision, acquisitionDetail: null, acquisitionReason: null };
@@ -157,9 +174,48 @@ function resolveIngressDecision(
 }
 
 export async function handlePainRecord(opts: RecordOptions): Promise<void> {
+  // PRI-743: fail loud on an unknown --host before any mutation (cli-5/cli-6).
+  if (opts.host !== undefined && opts.host !== 'openclaw' && opts.host !== 'codex') {
+    const message = `invalid --host: expected openclaw | codex, got ${opts.host}`;
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'failed',
+        reason: 'invalid_host_kind',
+        message,
+        nextAction: 'Pass --host openclaw or --host codex, or omit --host (defaults to openclaw).',
+      }, null, 2));
+    } else {
+      console.error(`Error: ${message}`);
+      console.error('Next action: pass --host openclaw or --host codex, or omit --host (defaults to openclaw).');
+    }
+    process.exit(1);
+    return; // guard: test stubs of process.exit continue execution (cli-2-exit-stops)
+  }
+
+  // PRI-743: a CLI-claimed codex attribution would be a PRI-642 recurrence in
+  // another shape — the shared ingress evaluator requires the rollout lineage
+  // tuple (rc-6) that only the Codex ingestion path can produce, and the CLI
+  // owns no Codex identity. Refuse before any mutation instead of faking it.
+  if (opts.host === 'codex') {
+    const message = 'the CLI cannot verify Codex lineage (rolloutIdentity / logicalObservationKey) — codex pains are produced by the Codex ingestion path, not by pd pain record';
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'failed',
+        reason: 'codex_lineage_unverifiable_by_cli',
+        message,
+        nextAction: 'Record Codex pains through the Codex ingestion path (pd codex setup enables it), or use --host openclaw for OpenClaw-attributed sessions.',
+      }, null, 2));
+    } else {
+      console.error(`Error: ${message}`);
+      console.error('Next action: record Codex pains through the Codex ingestion path (pd codex setup enables it), or use --host openclaw for OpenClaw-attributed sessions.');
+    }
+    process.exit(1);
+    return; // guard: test stubs of process.exit continue execution (cli-2-exit-stops)
+  }
+
   if (!opts.reason) {
     console.error('Error: --reason <text> is required');
-    console.error('Usage: pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--session <id>] [--json]');
+    console.error('Usage: pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--session <id>] [--host openclaw|codex] [--json]');
     process.exit(1);
     return;
   }
@@ -363,8 +419,21 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
       : [];
   const cliWarnings = [...decisionWarnings, gatedWarning].filter((w): w is string => w !== null && w !== undefined);
 
+  // PRI-743: the pre-existing 'openclaw' default is an assumption, not
+  // evidence — disclose it whenever it actually applies (rc-9), so host
+  // attribution can never silently distort PRI-743-style host comparisons.
+  const hostDefaultWarning = binding.sessionId !== undefined && opts.host === undefined
+    ? `host attribution defaulted to 'openclaw' (--host not given); pass --host codex to attribute this pain to the Codex host.`
+    : null;
+  if (hostDefaultWarning !== null) cliWarnings.push(hostDefaultWarning);
+
   if (opts.json) {
     const out: Record<string, unknown> = { ...result };
+    // PRI-743: surface the effective host attribution explicitly in --json
+    // (machine consumers doing host comparisons must not re-derive it).
+    if (binding.sessionId !== undefined) {
+      out.hostAttribution = binding.hostKind;
+    }
     // Ensure nextAction is present for actionable states
     if (out.status === 'submitted') {
       if (!out.nextAction) {
@@ -412,7 +481,7 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
       console.log(`   Source: ${opts.source ?? 'manual'}`);
       console.log(`   Workspace: ${workspaceDir}`);
       if (binding.sessionId) {
-        console.log(`   Session: ${binding.sessionId} (bound, ${binding.evidence.length} evidence entries)`);
+        console.log(`   Session: ${binding.sessionId} (bound, host=${binding.hostKind}, ${binding.evidence.length} evidence entries)`);
       } else {
         console.log('   Session: unbound (Owner report; no trajectory evidence)');
       }

package/src/commands/runtime-internalization-run-once.ts

@@ -18,7 +18,7 @@ import {
   TestDoubleRuntimeAdapter,
 } from '@principles/core/runtime-v2';
 import type { WakeOnceResult, DreamerRunnerResult, PhilosopherRunnerResult, ScribeRunnerResult, ArtificerRunnerResult, EvaluatorRunnerResult, RolloutReviewerRunnerResult, PDRuntimeAdapter, PeerRunnerKind, OutputLanguage } from '@principles/core/runtime-v2';
-import { resolveRuntimeConfigFromPdConfig, isRuntimeConfigError } from '@principles/core/runtime-v2';
+import { resolveRuntimeConfigForAgent, AGENT_NAME_FOR_TASK_KIND, isRuntimeConfigError } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { readOutputLanguageFromWorkspace } from '../config-reader.js';
 import { loadPdConfig } from '../services/pd-config-loader.js';
@@ -501,13 +501,24 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
   const outputLangResult = readOutputLanguageFromWorkspace(workspaceDir);
   const outputLanguage: OutputLanguage | undefined = outputLangResult.outputLanguage;
 
-  // PRI-670: profile timeout fallback for the runner deadline. The shared
-  // resolver reads the diagnostician binding (the binding ALL peer stages
-  // share today) — on any resolution error, fall back to the 300s default
-  // rather than refusing the run: the flag-off/legacy behavior was 300s.
+  // PRI-670: profile timeout fallback for the runner deadline. PRI-719: the
+  // profile resolves for the SELECTED RUNNER's agent binding — the shared
+  // resolver used to read the diagnostician binding for every stage, silently
+  // ignoring per-agent runtimeProfile declarations (EP002-R2 F4). On any
+  // resolution error, fall back to the 300s default rather than refusing the
+  // run: the flag-off/legacy behavior was 300s.
+  // PRI-719 review: explicit run-once is a PEER execution path — its scope
+  // is the internalization_full_chain flag, not agents[kind].enabled (the
+  // shipped default disables evaluator/rolloutReviewer, which must not block
+  // an explicit stage run). Same ignoreAgentEnabled semantics as the
+  // auto-consumer; `enabled` keeps gating the diagnostician bridge.
+  const runnerAgentName = AGENT_NAME_FOR_TASK_KIND[runnerKind];
   let profileTimeoutMs: number | undefined;
-  if (effectiveConfig) {
-    const resolved = resolveRuntimeConfigFromPdConfig(effectiveConfig, (name) => process.env[name]);
+  if (effectiveConfig && runnerAgentName !== undefined) {
+    const resolved = resolveRuntimeConfigForAgent(effectiveConfig, runnerAgentName, {
+      getEnvVar: (name) => process.env[name],
+      ignoreAgentEnabled: true,
+    });
     if (!isRuntimeConfigError(resolved)) {
       profileTimeoutMs = resolved.timeoutMs;
     }
@@ -544,6 +555,11 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
         runtimeKind,
         workspaceDir,
         runnerKind,
+        // PRI-719: resolve the SELECTED runner's own agent binding so its
+        // declared runtimeProfile governs the adapter — with the SAME
+        // ignoreAgentEnabled peer semantics as the timeout resolution above
+        // (declared profile == timeout profile == adapter profile).
+        ...(runnerAgentName !== undefined ? { agentName: runnerAgentName, ignoreAgentEnabled: true } : {}),
         timeoutMs: cliTimeoutMs,
         allowTestDouble: true,
         testDoublePayloadBuilder: () => buildTestDoubleAdapter(runnerKind, wakeResult.taskId),

package/src/index.ts

@@ -123,6 +123,7 @@ painCmd
   .option('-S, --source <text>', 'Source of the pain signal', 'manual')
   .option('-w, --workspace <path>', 'Workspace directory')
   .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('--host <kind>', 'PRI-743: explicit host attribution (openclaw | codex). openclaw = default attribution without the disclosure warning; codex refuses — the CLI cannot verify Codex lineage.', undefined)
   .option('--wait', 'Wait for diagnosis to complete (sync mode, overrides async flag)')
   .option('--json', 'Output raw JSON')
   .action(async (opts) => {

package/src/services/__tests__/runtime-adapter-resolver.test.ts

@@ -422,7 +422,10 @@ describe('resolveRuntimeAdapterFromConfig (PRI-431)', () => {
       });
 
       expect(result).toHaveProperty('__type', 'PiAiRuntimeAdapter');
-      expect(mockResolveRuntimeFromPdConfig).toHaveBeenCalledWith('/ws');
+      // PRI-719 (+review): the resolver threads the optional per-call options
+      // (agentName + ignoreAgentEnabled, both undefined when the caller does
+      // not select a peer stage).
+      expect(mockResolveRuntimeFromPdConfig).toHaveBeenCalledWith('/ws', { agentName: undefined, ignoreAgentEnabled: undefined });
     });
 
     it('delegates to openclaw-cli when config resolves to openclaw-cli', () => {

package/src/services/resolve-runtime-from-pd-config.ts

@@ -14,7 +14,7 @@
  */
 
 import {
-  resolveRuntimeConfigFromPdConfig,
+  resolveRuntimeConfigForAgent,
   isRuntimeConfigError,
   resolveAgentRuntimeBinding,
 } from '@principles/core/runtime-v2';
@@ -23,6 +23,7 @@ import type {
   RuntimeConfig,
   RuntimeConfigError,
 } from '@principles/core/runtime-v2';
+import type { InternalAgentName } from '@principles/core/runtime-v2';
 import { loadPdConfig } from './pd-config-loader.js';
 import type { PdConfigLoadResult } from './pd-config-loader.js';
 
@@ -64,6 +65,31 @@ function buildProfileLabel(profileId: string, profile: { type: string; provider?
   return `pi-ai: ${profile.provider ?? 'unknown'}/${profile.model ?? 'unknown'}`;
 }
 
+/**
+ * PRI-719: per-call resolution options for resolveRuntimeFromPdConfig.
+ */
+export interface ResolveRuntimeFromPdConfigOptions {
+  /** Env var accessor, defaults to process.env. */
+  readonly getEnvVar?: (name: string) => string | undefined;
+  /**
+   * Whose `internalAgents.agents[agent]` .runtimeProfile binding resolves
+   * (default 'diagnostician' — the pain-signal bridge path). run-once passes
+   * the selected runner's agent so each stage executes on ITS declared
+   * profile (EP002-R2 F4).
+   */
+  readonly agentName?: InternalAgentName;
+  /**
+   * PRI-719 review: resolve the binding even when the agent is disabled.
+   * Peer execution scope (auto-consumer AND explicit run-once) is governed
+   * by the internalization_full_chain FLAG, not by
+   * internalAgents.agents[kind].enabled — the shipped default config
+   * disables philosopher/evaluator/rolloutReviewer yet the full chain runs
+   * them. `enabled` keeps gating the diagnostician bridge (callers that
+   * omit this option honor it, PRI-638 semantics unchanged).
+   */
+  readonly ignoreAgentEnabled?: boolean;
+}
+
 /**
  * Resolve runtime configuration exclusively from .pd/config.yaml.
  *
@@ -72,13 +98,15 @@ function buildProfileLabel(profileId: string, profile: { type: string; provider?
  * called by probe/run-once/diagnose/pain-retry.
  *
  * @param workspaceDir - The resolved workspace directory.
- * @param getEnvVar - Env var accessor, defaults to process.env.
+ * @param options - Per-call resolution options (defaults = diagnostician
+ *   binding, honor enabled, process.env).
  * @returns Resolved runtime config with legacy warnings.
  */
 export function resolveRuntimeFromPdConfig(
   workspaceDir: string,
-  getEnvVar: (name: string) => string | undefined = (name) => process.env[name],
+  options: ResolveRuntimeFromPdConfigOptions = {},
 ): ResolvedRuntimeFromPdConfig {
+  const { getEnvVar = (name) => process.env[name], agentName = 'diagnostician', ignoreAgentEnabled = false } = options;
   const configLoadResult = loadPdConfig(workspaceDir);
 
   // Malformed config → fail loud. Do NOT fall back to defaults for execution.
@@ -110,15 +138,25 @@ export function resolveRuntimeFromPdConfig(
     };
   }
 
-  const result = resolveRuntimeConfigFromPdConfig(configLoadResult.effective, getEnvVar);
+  const result = resolveRuntimeConfigForAgent(configLoadResult.effective, agentName, { getEnvVar, ignoreAgentEnabled });
 
   // PRI-402: Extract profile ID and label for probe output alignment with doctor
   let runtimeProfileId: string | null = null;
   let runtimeProfileLabel: string | null = null;
-  const bindingResult = resolveAgentRuntimeBinding(configLoadResult.effective, 'diagnostician');
+  const bindingResult = resolveAgentRuntimeBinding(configLoadResult.effective, agentName);
   if (bindingResult.ok) {
     runtimeProfileId = bindingResult.profileId;
     runtimeProfileLabel = buildProfileLabel(bindingResult.profileId, bindingResult.profile);
+  } else if (!isRuntimeConfigError(result) && result.runtimeProfileId !== undefined) {
+    // PRI-719 review: on the peer path (ignoreAgentEnabled) the runtime may
+    // resolve fine for a shipped-disabled agent while the raw binding still
+    // reports disabled — derive the label from the resolved profile identity.
+    const { runtimeProfileId: resolvedProfileId } = result;
+    const profile = configLoadResult.effective.config.runtimeProfiles[resolvedProfileId];
+    if (resolvedProfileId !== undefined && profile) {
+      runtimeProfileId = resolvedProfileId;
+      runtimeProfileLabel = buildProfileLabel(resolvedProfileId, profile);
+    }
   }
 
   const legacyWarnings = configLoadResult.legacyFilesDetected.length > 0
@@ -161,7 +199,7 @@ export function resolveRuntimeWithOverrides(
   },
   getEnvVar: (name: string) => string | undefined = (name) => process.env[name],
 ): ResolvedRuntimeFromPdConfig & { mergedConfig: RuntimeConfig | null } {
-  const base = resolveRuntimeFromPdConfig(workspaceDir, getEnvVar);
+  const base = resolveRuntimeFromPdConfig(workspaceDir, { getEnvVar });
 
   if (isRuntimeConfigError(base.result)) {
     return { ...base, mergedConfig: null };

package/src/services/rulehost-readiness.ts

@@ -207,7 +207,7 @@ function resolveRuleHostReadinessUnchecked(
   getEnvVar: (name: string) => string | undefined,
 ): RuleHostReadinessResult {
   // ── Step 1: Load config ──
-  const { configLoadResult } = resolveRuntimeFromPdConfig(workspaceDir, getEnvVar);
+  const { configLoadResult } = resolveRuntimeFromPdConfig(workspaceDir, { getEnvVar });
 
   if (!configLoadResult.ok) {
     const [firstError] = configLoadResult.errors;

package/src/services/runtime-adapter-resolver.ts

@@ -32,7 +32,7 @@ import {
   isRuntimeConfigError,
   validateRuntimeConfig,
 } from '@principles/core/runtime-v2';
-import type { PDRuntimeAdapter, PdL2ArtifactReader, RuntimeConfig, RuntimeConfigResult } from '@principles/core/runtime-v2';
+import type { PDRuntimeAdapter, PdL2ArtifactReader, RuntimeConfig, RuntimeConfigResult, InternalAgentName } from '@principles/core/runtime-v2';
 import { loadLedger } from '@principles/core/principle-tree-ledger';
 import { loadPdConfig, computeFlagsFromLoadResult } from './pd-config-loader.js';
 import { resolveRuntimeFromPdConfig } from './resolve-runtime-from-pd-config.js';
@@ -80,6 +80,19 @@ export interface ResolveAdapterOptions {
   workspaceDir: string;
   /** Runner kind (for L2 dreamer routing). Optional. */
   runnerKind?: string;
+  /**
+   * PRI-719: internal agent whose runtimeProfile binding resolves
+   * (default 'diagnostician'). run-once passes the selected runner's agent
+   * so each stage executes on its own declared profile.
+   */
+  agentName?: InternalAgentName;
+  /**
+   * PRI-719 review: resolve the binding even when the agent is disabled —
+   * peer execution scope is the internalization_full_chain flag (auto-
+   * consumer AND explicit run-once), not agents[kind].enabled. Omitted by
+   * non-peer callers (probe/diagnose) which keep honoring `enabled`.
+   */
+  ignoreAgentEnabled?: boolean;
   /** CLI timeout override. Takes precedence over config timeoutMs. */
   timeoutMs?: number;
   /**
@@ -163,7 +176,10 @@ export function resolveRuntimeAdapterFromConfig(opts: ResolveAdapterOptions): PD
   }
 
   // ── Resolve config from .pd/config.yaml (for pi-ai, openclaw-cli, config) ──
-  const resolved = resolveRuntimeFromPdConfig(opts.workspaceDir);
+  const resolved = resolveRuntimeFromPdConfig(opts.workspaceDir, {
+    agentName: opts.agentName,
+    ignoreAgentEnabled: opts.ignoreAgentEnabled,
+  });
   const configResult: RuntimeConfigResult = resolved.result;
 
   // PRI-431 Step 1d: invoke onConfigResolved callback (for telemetry, legacyWarnings, etc.)

package/tests/commands/pain-list.test.ts

@@ -105,6 +105,39 @@ describe('listPains (PRI-640 host filter)', () => {
     expect(result.pains[0]?.host).toBe('unknown');
   });
 
+  it('PRI-743: byHost reports the full-table distribution independent of --host/--limit', async () => {
+    const { db } = makeWorkspace();
+    seedPain(db, { id: 1, source: 'user_correction', canonical: 'pain_oc_1', host: 'openclaw', created: '2026-09-01T10:00:00.000Z' });
+    seedPain(db, { id: 2, source: 'user_correction', canonical: 'pain_oc_2', host: 'openclaw', created: '2026-09-01T10:05:00.000Z' });
+    seedPain(db, { id: 3, source: 'tool_failure', canonical: 'pain_cx_1', host: 'codex', created: '2026-09-01T11:00:00.000Z' });
+    seedPain(db, { id: 4, source: 'manual', canonical: 'pain_null_1', host: null, created: '2026-09-01T12:00:00.000Z' });
+    seedPain(db, { id: 5, source: 'manual', canonical: 'pain_null_2', host: null, created: '2026-09-01T12:05:00.000Z' });
+    const dbPath = dbPathOf(db);
+    db.close();
+
+    // --limit narrows the row list but must NOT narrow the distribution.
+    const limited = await listPains(dbPath, { limit: 2 });
+    expect(limited.count).toBe(2);
+    expect(limited.byHost).toEqual({ openclaw: 2, codex: 1, unknown: 2 });
+
+    // --host narrows the row list but must NOT narrow the distribution.
+    const filtered = await listPains(dbPath, { limit: 10, host: 'codex' });
+    expect(filtered.count).toBe(1);
+    expect(filtered.byHost).toEqual({ openclaw: 2, codex: 1, unknown: 2 });
+  });
+
+  it('PRI-743: byHost is null (never guessed) on a pre-PRI-640 database', async () => {
+    const { db } = makePre640Workspace();
+    db.prepare(`INSERT INTO pain_events (session_id, source, score, reason, severity, origin, confidence, text, canonical_pain_id, runtime_task_id, created_at)
+      VALUES ('s1', 'tool_failure', 70, 'r', 'moderate', 'system_infer', NULL, NULL, 'pain_legacy', NULL, '2026-08-01T00:00:00.000Z')`).run();
+    const dbPath = dbPathOf(db);
+    db.close();
+
+    const result = await listPains(dbPath, { limit: 10 });
+    expect(result.byHost).toBeNull();
+    expect(result.warnings).toContain('host_kind_column_missing');
+  });
+
   it('degrades observably on a pre-PRI-640 database without the host_kind column (rc-9)', async () => {
     const { db } = makePre640Workspace();
     db.prepare(`INSERT INTO pain_events (session_id, source, score, reason, severity, origin, confidence, text, canonical_pain_id, runtime_task_id, created_at)
@@ -152,11 +185,12 @@ describe('handlePainList (CLI contract)', () => {
     await handlePainList({ json: true });
     expect(exitSpy).not.toHaveBeenCalled();
     const raw = logSpy.mock.calls.map((args) => String(args[0])).join('\n');
-    const parsed = JSON.parse(raw) as { count: number; pains: { host: string; painId: string }[]; hostFilter: unknown; warnings: string[] };
+    const parsed = JSON.parse(raw) as { count: number; pains: { host: string; painId: string }[]; hostFilter: unknown; warnings: string[]; byHost: { openclaw: number; codex: number; unknown: number } | null };
     expect(parsed.count).toBe(2);
     expect(parsed.pains.map((p) => `${p.painId}:${p.host}`).sort()).toEqual(['pain_cli_cx:codex', 'pain_cli_oc:openclaw']);
     expect(parsed.hostFilter).toBeNull();
     expect(parsed.warnings).toEqual([]);
+    expect(parsed.byHost).toEqual({ openclaw: 1, codex: 1, unknown: 0 });
   });
 
   it('--host filter is reflected in the JSON result', async () => {

package/tests/commands/pain-record-session-parser.test.ts

@@ -86,6 +86,33 @@ describe('pd pain record --session (real Commander + real trajectory.db)', () =>
     expect(result.stdout).toContain('--session');
   }, 15_000);
 
+  it('PRI-743: --help registers --host with the openclaw|codex contract', async () => {
+    const result = await runBuiltCli(['pain', 'record', '--help']);
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('--host <kind>');
+    // Commander wraps help text; normalize whitespace before asserting content.
+    const normalized = result.stdout.replace(/\s+/g, ' ');
+    expect(normalized).toContain('openclaw | codex');
+    expect(normalized).toContain('codex refuses');
+  }, 15_000);
+
+  it('PRI-743: an invalid --host value exits non-zero with a single structured JSON object', async () => {
+    const result = await runBuiltCli([
+      'pain', 'record',
+      '--reason', 'parser test pain',
+      '--host', 'claude',
+      '--workspace', tmpDir,
+      '--json',
+    ]);
+
+    expect(result.status).not.toBe(0);
+    const trimmed = result.stdout.trim();
+    const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+    expect(parsed.status).toBe('failed');
+    expect(parsed.reason).toBe('invalid_host_kind');
+    expect(typeof parsed.nextAction).toBe('string');
+  }, 15_000);
+
   it('fails with a single JSON object and reason session_not_found for a nonexistent session (SPEC 12.1.4)', async () => {
     const result = await runBuiltCli([
       'pain', 'record',

package/tests/commands/pain-record.test.ts

@@ -399,6 +399,83 @@ describe('pd pain record', () => {
     exitSpy.mockRestore();
   });
 
+  // ── PRI-743: explicit --host attribution ──────────────────────────────────
+
+  it('PRI-743: --host openclaw records without the default-assumption disclosure', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'explicit openclaw', session: 'sess-oc', host: 'openclaw', json: true });
+
+    expect(lastRecordPainInput).toBeTruthy();
+    expect(lastRecordPainInput!.sessionId).toBe('sess-oc');
+    expect(lastRecordPainInput!.hostKind).toBe('openclaw');
+    expect(lastRecordPainInput!.provenance).toBe('host_context_bound');
+
+    const jsonOutput = JSON.parse(logSpy.mock.calls[0][0]) as { hostAttribution?: string; warnings?: string[] };
+    expect(jsonOutput.hostAttribution).toBe('openclaw');
+    expect((jsonOutput.warnings ?? []).some((w) => w.includes("defaulted to 'openclaw'"))).toBe(false);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  it('PRI-743: --host codex refuses loudly — the CLI cannot verify Codex lineage (rc-6)', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'codex mistake', session: 'sess-codex', host: 'codex', json: true });
+
+    // cli-1: exactly one JSON object on stdout
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const jsonOutput = JSON.parse(logSpy.mock.calls[0][0]) as { status: string; reason: string; nextAction: string };
+    expect(jsonOutput).toMatchObject({ status: 'failed', reason: 'codex_lineage_unverifiable_by_cli' });
+    expect(jsonOutput.nextAction).toContain('Codex ingestion');
+    // cli-2/cli-5: refused before any evidence acquisition or service mutation
+    expect(lastRecordPainInput).toBeNull();
+    expect(acquireTrajectoryEvidenceFromDb).not.toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  it('PRI-743: omitting --host keeps the openclaw default but discloses the assumption (rc-9)', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'legacy path', session: 'sess-123', json: true });
+
+    expect(lastRecordPainInput).toBeTruthy();
+    expect(lastRecordPainInput!.hostKind).toBe('openclaw');
+    const jsonOutput = JSON.parse(logSpy.mock.calls[0][0]) as { hostAttribution?: string; warnings?: string[] };
+    expect(jsonOutput.hostAttribution).toBe('openclaw');
+    expect((jsonOutput.warnings ?? []).some((w) => w.includes("defaulted to 'openclaw'") && w.includes('--host codex'))).toBe(true);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  it('PRI-743: an invalid --host value fails loudly before any mutation (cli-5/cli-6)', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'typo host', session: 'sess-123', host: 'claude', json: true });
+
+    // cli-1: exactly one JSON object on stdout
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const jsonOutput = JSON.parse(logSpy.mock.calls[0][0]) as { status: string; reason: string; nextAction: string };
+    expect(jsonOutput).toMatchObject({ status: 'failed', reason: 'invalid_host_kind' });
+    expect(jsonOutput.nextAction).toContain('--host codex');
+    // cli-2/cli-5: execution stopped before any evidence acquisition or service mutation
+    expect(lastRecordPainInput).toBeNull();
+    expect(acquireTrajectoryEvidenceFromDb).not.toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
   // 用例 C2 (PRI-642 rewrite): without session, no sentinel session, no
   // placeholder evidence — an honest unbound Owner report (SPEC §7.4).
   it('C2: submits an honest unbound report when no --session provided', async () => {