@dzhechkov/harness-core 0.8.5 → 0.8.10

package/src/integration-probe-worker.ts

@@ -0,0 +1,310 @@
+/** Isolated bounded subprocess runner used by integration registration probes. */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+export const PROBE_REDACTION_MARKER = '[REDACTED]';
+export const PROBE_TRUNCATION_MARKER = '[TRUNCATED]';
+const WORKER_INPUT_MAX_BYTES = 64 * 1024;
+const REDACTION_WORDS = ['bearer', 'token', 'secret', 'password', 'apikey', 'api_key', 'api-key'] as const;
+const ASSIGNMENT_WORDS = new Set(REDACTION_WORDS.slice(1));
+
+export interface ProbeWorkerRequest {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly timeoutMs: number;
+  readonly streamMaxBytes: number;
+  readonly aggregateMaxBytes: number;
+}
+
+export interface ProbeWorkerResult {
+  readonly status: number | null;
+  readonly signal: string | null;
+  readonly stdoutBase64: string;
+  readonly stderrBase64: string;
+  readonly errorCode?: string;
+  readonly truncated: boolean;
+}
+
+type RedactionState = 'normal' | 'word' | 'passthrough-word' | 'bearer-space' | 'bearer-value' | 'key-space' | 'key-value-space' | 'key-value';
+
+/** Stateful UTF-8 redactor: raw chunks are transformed immediately and are never retained. */
+class StreamingProbeRedactor {
+  readonly #decoder = new TextDecoder('utf-8', { fatal: true });
+  readonly #sanitized: string[] = [];
+  #state: RedactionState = 'normal';
+  #word = '';
+  #keyBuffer = '';
+  #invalidUtf8 = false;
+  #finished = false;
+
+  write(chunk: Uint8Array): boolean {
+    if (this.#finished || this.#invalidUtf8) return false;
+    try {
+      this.#consume(this.#decoder.decode(chunk, { stream: true }));
+      return true;
+    } catch {
+      this.#invalidUtf8 = true;
+      this.#sanitized.length = 0;
+      return false;
+    }
+  }
+
+  finish(): { bytes: Buffer; invalidUtf8: boolean } {
+    if (!this.#finished && !this.#invalidUtf8) {
+      try {
+        this.#consume(this.#decoder.decode());
+        if (this.#state === 'word') this.#emit(this.#word);
+        else if (this.#state === 'key-space') this.#emit(this.#keyBuffer);
+      } catch {
+        this.#invalidUtf8 = true;
+        this.#sanitized.length = 0;
+      }
+    }
+    this.#finished = true;
+    return {
+      bytes: this.#invalidUtf8 ? Buffer.alloc(0) : Buffer.from(this.#sanitized.join(''), 'utf8'),
+      invalidUtf8: this.#invalidUtf8,
+    };
+  }
+
+  #emit(value: string): void { this.#sanitized.push(value); }
+  #wordChar(value: string): boolean { return /^[A-Za-z0-9_-]$/.test(value); }
+  #secretEnd(value: string, comma: boolean): boolean {
+    return /\s/.test(value) || value === '"' || value === "'" || (comma && value === ',');
+  }
+
+  #consume(text: string): void {
+    for (const value of text) this.#character(value);
+  }
+
+  #character(value: string): void {
+    if (this.#state === 'normal') {
+      if (this.#wordChar(value)) { this.#word = value; this.#state = 'word'; }
+      else this.#emit(value);
+      return;
+    }
+    if (this.#state === 'word') {
+      if (this.#wordChar(value)) {
+        this.#word += value;
+        if (!REDACTION_WORDS.some((word) => word.startsWith(this.#word.toLowerCase()))) {
+          this.#emit(this.#word); this.#word = ''; this.#state = 'passthrough-word';
+        }
+        return;
+      }
+      const word = this.#word;
+      const lower = word.toLowerCase();
+      this.#word = '';
+      if (lower === 'bearer' && /\s/.test(value)) {
+        this.#emit(word + value); this.#state = 'bearer-space'; return;
+      }
+      if (ASSIGNMENT_WORDS.has(lower as typeof REDACTION_WORDS[number]) && (/\s/.test(value) || value === ':' || value === '=')) {
+        if (value === ':' || value === '=') { this.#emit(word + value); this.#state = 'key-value-space'; }
+        else { this.#keyBuffer = word + value; this.#state = 'key-space'; }
+        return;
+      }
+      this.#emit(word); this.#state = 'normal'; this.#character(value); return;
+    }
+    if (this.#state === 'passthrough-word') {
+      if (this.#wordChar(value)) this.#emit(value);
+      else { this.#state = 'normal'; this.#character(value); }
+      return;
+    }
+    if (this.#state === 'bearer-space') {
+      if (/\s/.test(value)) this.#emit(value);
+      else if (this.#secretEnd(value, false)) { this.#state = 'normal'; this.#character(value); }
+      else { this.#emit(PROBE_REDACTION_MARKER); this.#state = 'bearer-value'; }
+      return;
+    }
+    if (this.#state === 'bearer-value') {
+      if (this.#secretEnd(value, false)) { this.#state = 'normal'; this.#character(value); }
+      return;
+    }
+    if (this.#state === 'key-space') {
+      if (/\s/.test(value)) this.#keyBuffer += value;
+      else if (value === ':' || value === '=') { this.#emit(this.#keyBuffer + value); this.#keyBuffer = ''; this.#state = 'key-value-space'; }
+      else { this.#emit(this.#keyBuffer); this.#keyBuffer = ''; this.#state = 'normal'; this.#character(value); }
+      return;
+    }
+    if (this.#state === 'key-value-space') {
+      if (/\s/.test(value)) this.#emit(value);
+      else if (this.#secretEnd(value, true)) { this.#state = 'normal'; this.#character(value); }
+      else { this.#emit(PROBE_REDACTION_MARKER); this.#state = 'key-value'; }
+      return;
+    }
+    if (this.#secretEnd(value, true)) { this.#state = 'normal'; this.#character(value); }
+  }
+}
+
+export function redactProbeText(input: string): string {
+  const redactor = new StreamingProbeRedactor();
+  redactor.write(Buffer.from(input, 'utf8'));
+  return redactor.finish().bytes.toString('utf8');
+}
+
+function killProcessTree(child: ChildProcess): void {
+  if (child.pid === undefined) return;
+  if (process.platform !== 'win32') {
+    try {
+      process.kill(-child.pid, 'SIGKILL');
+      return;
+    } catch {
+      child.kill('SIGKILL');
+      return;
+    }
+  }
+  // Windows has no negative-PID process groups. taskkill /T is the native tree
+  // primitive; the direct kill remains a fail-safe if taskkill itself is absent.
+  const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], {
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  killer.once('error', () => child.kill('SIGKILL'));
+}
+
+function validateRequest(value: unknown): ProbeWorkerRequest {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid worker request');
+  const row = value as Record<string, unknown>;
+  if (typeof row['command'] !== 'string' || typeof row['cwd'] !== 'string' ||
+      !Array.isArray(row['args']) || !row['args'].every((arg) => typeof arg === 'string')) {
+    throw new Error('invalid worker command');
+  }
+  for (const key of ['timeoutMs', 'streamMaxBytes', 'aggregateMaxBytes'] as const) {
+    if (!Number.isSafeInteger(row[key]) || (row[key] as number) <= 0) throw new Error(`invalid worker ${key}`);
+  }
+  return {
+    command: row['command'], cwd: row['cwd'], args: row['args'] as string[],
+    timeoutMs: row['timeoutMs'] as number,
+    streamMaxBytes: row['streamMaxBytes'] as number,
+    aggregateMaxBytes: row['aggregateMaxBytes'] as number,
+  };
+}
+
+function withTruncationMarker(bytes: Buffer, maxBytes: number): Buffer {
+  const marker = Buffer.from(PROBE_TRUNCATION_MARKER, 'utf8');
+  if (marker.length >= maxBytes) return marker.subarray(0, maxBytes);
+  const keep = Math.min(bytes.length, maxBytes - marker.length);
+  let prefix = bytes.subarray(0, keep);
+  while (prefix.length > 0) {
+    try {
+      new TextDecoder('utf-8', { fatal: true }).decode(prefix);
+      break;
+    } catch {
+      prefix = prefix.subarray(0, prefix.length - 1);
+    }
+  }
+  return Buffer.concat([prefix, marker]);
+}
+
+export function runProbeWorker(request: ProbeWorkerRequest): Promise<ProbeWorkerResult> {
+  return new Promise((resolveResult) => {
+    const stdout = new StreamingProbeRedactor();
+    const stderr = new StreamingProbeRedactor();
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let truncated = false;
+    let truncatedStream: 'stdout' | 'stderr' | undefined;
+    let timedOut = false;
+    let settled = false;
+    let invalidUtf8 = false;
+    let spawnError: string | undefined;
+    const child = spawn(request.command, [...request.args], {
+      cwd: request.cwd,
+      detached: process.platform !== 'win32',
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    const killOnce = (): void => {
+      if (!child.killed) killProcessTree(child);
+    };
+    const capture = (stream: 'stdout' | 'stderr', chunk: Buffer): void => {
+      if (settled || truncated) return;
+      const ownBytes = stream === 'stdout' ? stdoutBytes : stderrBytes;
+      const remaining = Math.max(0, Math.min(
+        request.streamMaxBytes - ownBytes,
+        request.aggregateMaxBytes - stdoutBytes - stderrBytes,
+      ));
+      const accepted = chunk.subarray(0, Math.min(chunk.length, remaining));
+      if (accepted.length > 0 && !(stream === 'stdout' ? stdout : stderr).write(accepted)) {
+        invalidUtf8 = true;
+        killOnce();
+        return;
+      }
+      if (stream === 'stdout') stdoutBytes += accepted.length;
+      else stderrBytes += accepted.length;
+      if (accepted.length < chunk.length) {
+        truncated = true;
+        truncatedStream = stream;
+        killOnce();
+      }
+    };
+    child.stdout?.on('data', (chunk: Buffer) => capture('stdout', chunk));
+    child.stderr?.on('data', (chunk: Buffer) => capture('stderr', chunk));
+    child.once('error', (error: NodeJS.ErrnoException) => {
+      spawnError = error.code ?? 'PROCESS_ERROR';
+    });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killOnce();
+    }, request.timeoutMs);
+    timer.unref();
+    child.once('close', (status, signal) => {
+      settled = true;
+      clearTimeout(timer);
+      const cleanOut = stdout.finish();
+      const cleanErr = stderr.finish();
+      invalidUtf8 ||= cleanOut.invalidUtf8 || cleanErr.invalidUtf8;
+      const stdoutLimit = Math.min(
+        request.streamMaxBytes,
+        Math.max(0, request.aggregateMaxBytes - cleanErr.bytes.length),
+      );
+      const stderrLimit = Math.min(
+        request.streamMaxBytes,
+        Math.max(0, request.aggregateMaxBytes - cleanOut.bytes.length),
+      );
+      const stdoutBytesOut = truncatedStream === 'stdout'
+        ? withTruncationMarker(cleanOut.bytes, stdoutLimit)
+        : cleanOut.bytes;
+      const stderrBytesOut = truncatedStream === 'stderr'
+        ? withTruncationMarker(cleanErr.bytes, stderrLimit)
+        : cleanErr.bytes;
+      resolveResult({
+        status,
+        signal,
+        stdoutBase64: stdoutBytesOut.toString('base64'),
+        stderrBase64: stderrBytesOut.toString('base64'),
+        ...(timedOut ? { errorCode: 'ETIMEDOUT' }
+          : truncated ? { errorCode: 'OUTPUT_TRUNCATED' }
+            : invalidUtf8 ? { errorCode: 'INVALID_UTF8' }
+              : spawnError !== undefined ? { errorCode: spawnError } : {}),
+        truncated,
+      });
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    const bytes = Buffer.from(chunk as Uint8Array);
+    size += bytes.length;
+    if (size > WORKER_INPUT_MAX_BYTES) throw new Error('worker request too large');
+    chunks.push(bytes);
+  }
+  const request = validateRequest(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+  process.stdout.write(`${JSON.stringify(await runProbeWorker(request))}\n`);
+}
+
+const invokedPath = process.argv[1];
+if (invokedPath !== undefined && realpathSync(resolve(invokedPath)) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch((error) => {
+    process.stderr.write(`integration probe worker failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/integration-receipts/claude-code/mcp/2.1.235.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "target": "claude-code",
+  "component": "mcp",
+  "productSurface": "claude-code-cli",
+  "runtimeVersion": "2.1.235",
+  "scope": "project",
+  "carrierPath": ".mcp.json",
+  "serializerId": "claude-project-mcp-json-v1",
+  "probeCommandId": "claude-project-mcp-get-v1",
+  "probeCommand": ["claude", "mcp", "get", "dz-registration-probe"],
+  "timeoutMs": 30000,
+  "observedExitCode": 0,
+  "transcriptSha256": "sha256:0e30c79de6381c7e7b93a39cc644cb282b6c95ceaeb4a0f5a94fbfecb5c71549",
+  "parsedObservation": {
+    "registrationId": "dz-registration-probe",
+    "scope": "project",
+    "status": "Pending approval",
+    "approval": "pending",
+    "ready": false
+  },
+  "wrongPathNegativeControl": {
+    "carrierPath": ".claude/.mcp.json",
+    "probeCommand": ["claude", "mcp", "get", "dz-wrong-path-probe"],
+    "timeoutMs": 30000,
+    "observedExitCode": 1,
+    "transcriptSha256": "sha256:aba424ed140ee785947f314942566ae4bccc7b7c44ca9be785efbf36be0f62d5",
+    "registrationObserved": false,
+    "reasonCode": "POST_WRITE_REGISTRATION_NOT_OBSERVED"
+  },
+  "transportFamily": "stdio-local",
+  "fieldFamilies": ["type", "command", "args"],
+  "observedAt": "2026-08-30T19:22:15.366Z",
+  "documentation": ["https://code.claude.com/docs/en/mcp"]
+}

package/src/integrations-verify.ts

@@ -0,0 +1,258 @@
+/** Bounded, non-executing target registration verification. */
+
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { IntegrationComponent, IntegrationReasonCode } from '@dzhechkov/core';
+
+import { CLAUDE_MCP_RECEIPT, assessClaudeMcpEvidence } from './integration-evidence.js';
+import { TARGET_INTEGRATION_POLICY, type RegistrationObservation } from './target-integrations.js';
+import type { TargetName } from './targets.js';
+import type { ProbeWorkerResult } from './integration-probe-worker.js';
+
+export const INTEGRATION_PROBE_TIMEOUT_MS = 30_000;
+export const INTEGRATION_PROBE_STREAM_MAX_BYTES = 1024 * 1024;
+export const INTEGRATION_PROBE_AGGREGATE_MAX_BYTES = 2 * 1024 * 1024;
+
+export interface IntegrationProcessRequest {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly timeoutMs: number;
+}
+
+export interface IntegrationProcessObservation {
+  readonly status: number | null;
+  readonly signal: string | null;
+  readonly stdout: Uint8Array;
+  readonly stderr: Uint8Array;
+  readonly errorCode?: string;
+}
+
+export interface IntegrationProcessPort {
+  run(request: IntegrationProcessRequest): IntegrationProcessObservation;
+}
+
+export type IntegrationExecutableResolution =
+  | { readonly ok: true; readonly path: string }
+  | { readonly ok: false; readonly errorCode: 'ENOENT' | 'UNSAFE_EXECUTABLE' };
+
+/** Resolve PATH once and reject a project-controlled probe binary before spawning it. */
+export function resolveIntegrationExecutable(
+  command: string,
+  cwd: string,
+  pathValue = process.env['PATH'] ?? '',
+): IntegrationExecutableResolution {
+  const candidates = isAbsolute(command)
+    ? [command]
+    : command.includes('/') || command.includes('\\')
+      ? [resolve(cwd, command)]
+      : pathValue.split(delimiter).map((dir) => join(dir.length === 0 ? cwd : dir, command));
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    try {
+      accessSync(candidate, constants.X_OK);
+      const actual = realpathSync(candidate);
+      const rel = relative(realpathSync(cwd), actual);
+      if (rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel))) {
+        return { ok: false, errorCode: 'UNSAFE_EXECUTABLE' };
+      }
+      return { ok: true, path: actual };
+    } catch {
+      continue;
+    }
+  }
+  return { ok: false, errorCode: 'ENOENT' };
+}
+
+export const defaultIntegrationProcessPort: IntegrationProcessPort = {
+  run(request) {
+    const executable = resolveIntegrationExecutable(request.command, request.cwd);
+    if (!executable.ok) {
+      return { status: null, signal: null, stdout: new Uint8Array(), stderr: new Uint8Array(), errorCode: executable.errorCode };
+    }
+    const workerPath = fileURLToPath(new URL('./integration-probe-worker.js', import.meta.url));
+    const result = spawnSync(process.execPath, [workerPath], {
+      input: JSON.stringify({
+        ...request,
+        command: executable.path,
+        streamMaxBytes: INTEGRATION_PROBE_STREAM_MAX_BYTES,
+        aggregateMaxBytes: INTEGRATION_PROBE_AGGREGATE_MAX_BYTES,
+      }),
+      cwd: request.cwd,
+      timeout: request.timeoutMs + 5_000,
+      killSignal: 'SIGKILL',
+      maxBuffer: 4 * 1024 * 1024,
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (result.error !== undefined || result.status !== 0) {
+      return {
+        status: result.status,
+        signal: result.signal,
+        stdout: new Uint8Array(),
+        stderr: new Uint8Array(),
+        errorCode: (result.error as NodeJS.ErrnoException | undefined)?.code ?? 'PROCESS_ERROR',
+      };
+    }
+    let observation: ProbeWorkerResult;
+    try {
+      observation = JSON.parse(result.stdout) as ProbeWorkerResult;
+    } catch {
+      return { status: null, signal: null, stdout: new Uint8Array(), stderr: new Uint8Array(), errorCode: 'PROCESS_ERROR' };
+    }
+    return {
+      status: observation.status,
+      signal: observation.signal,
+      stdout: Buffer.from(observation.stdoutBase64, 'base64'),
+      stderr: Buffer.from(observation.stderrBase64, 'base64'),
+      ...(observation.errorCode !== undefined ? { errorCode: observation.errorCode } : {}),
+    };
+  },
+};
+
+export interface VerifyTargetIntegrationOptions {
+  readonly target: TargetName;
+  readonly component: IntegrationComponent;
+  readonly projectRoot: string;
+  readonly registrationId?: string;
+  readonly phase?: 'preflight' | 'post-write';
+  readonly processPort?: IntegrationProcessPort;
+}
+
+export interface IntegrationVerification {
+  readonly ok: boolean;
+  readonly target: TargetName;
+  readonly component: IntegrationComponent;
+  readonly runtimeVersion?: string;
+  readonly evidenceVersion?: string;
+  readonly reasonCode?: IntegrationReasonCode;
+  readonly remediation?: string;
+  readonly registrations: readonly RegistrationObservation[];
+}
+
+function decodeBounded(observation: IntegrationProcessObservation): { stdout: string; stderr: string } | IntegrationReasonCode {
+  const stdout = Buffer.from(observation.stdout);
+  const stderr = Buffer.from(observation.stderr);
+  if (stdout.length > INTEGRATION_PROBE_STREAM_MAX_BYTES || stderr.length > INTEGRATION_PROBE_STREAM_MAX_BYTES ||
+      stdout.length + stderr.length > INTEGRATION_PROBE_AGGREGATE_MAX_BYTES) return 'LIVE_PROBE_FAILED';
+  try {
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    return { stdout: decoder.decode(stdout), stderr: decoder.decode(stderr) };
+  } catch {
+    return 'LIVE_PROBE_FAILED';
+  }
+}
+
+function parseClaudeVersion(text: string): string | undefined {
+  return /(?:Claude Code\s+)?(\d+\.\d+\.\d+)/i.exec(text)?.[1];
+}
+
+function failed(
+  options: VerifyTargetIntegrationOptions,
+  reasonCode: IntegrationReasonCode,
+  remediation: string,
+  runtimeVersion?: string,
+): IntegrationVerification {
+  return {
+    ok: false,
+    target: options.target,
+    component: options.component,
+    registrations: [],
+    reasonCode,
+    remediation,
+    ...(runtimeVersion !== undefined ? { runtimeVersion } : {}),
+  };
+}
+
+function parseClaudeProjectRegistration(
+  options: VerifyTargetIntegrationOptions,
+  id: string,
+  observation: IntegrationProcessObservation,
+  runtimeVersion: string,
+): IntegrationVerification {
+  if (observation.errorCode === 'ETIMEDOUT' || observation.signal === 'SIGKILL') {
+    return failed(options, 'LIVE_PROBE_TIMEOUT', `Claude mcp get exceeded ${INTEGRATION_PROBE_TIMEOUT_MS}ms`, runtimeVersion);
+  }
+  if (observation.errorCode !== undefined) {
+    return failed(options, 'LIVE_PROBE_FAILED', `Claude registration probe failed before a trustworthy observation (${observation.errorCode})`, runtimeVersion);
+  }
+  const text = decodeBounded(observation);
+  if (typeof text === 'string') return failed(options, text, 'Claude registration output was oversized or invalid UTF-8', runtimeVersion);
+  if (observation.status !== 0) return failed(options, 'POST_WRITE_REGISTRATION_NOT_OBSERVED', `claude mcp get ${id} did not observe the project registration`, runtimeVersion);
+  const output = `${text.stdout}\n${text.stderr}`;
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Claude 2.1.235 prints either `Name: <id>` or an exact `<id>:` heading depending on the
+  // installation channel. Require one whole attributable line; a prose mention is not evidence.
+  if (!new RegExp(`^(?:Name\\s*:\\s*${escapedId}|${escapedId}:)\\s*$`, 'im').test(output) ||
+      !/Scope\s*:\s*Project\b/i.test(output)) {
+    return failed(options, 'POST_WRITE_REGISTRATION_NOT_OBSERVED', `claude mcp get ${id} did not attribute the exact id to project scope`, runtimeVersion);
+  }
+  const pending = /pending approval/i.test(output);
+  return {
+    ok: true,
+    target: options.target,
+    component: options.component,
+    runtimeVersion,
+    evidenceVersion: CLAUDE_MCP_RECEIPT.runtimeVersion,
+    registrations: [{ id, scope: 'project', registered: true, approval: pending ? 'pending' : 'unknown', ready: !pending }],
+  };
+}
+
+/**
+ * Verify only code-owned native list/get surfaces. Manifest command/URL fields
+ * are intentionally absent from this API, so they cannot be executed here.
+ */
+export function verifyTargetIntegration(options: VerifyTargetIntegrationOptions): IntegrationVerification {
+  const port = options.processPort ?? defaultIntegrationProcessPort;
+  if (options.target !== 'claude-code' || options.component !== 'mcp') {
+    const cell = TARGET_INTEGRATION_POLICY[options.target][options.component];
+    return failed(options, cell.reasonCode ?? 'NO_QUALIFYING_LIVE_RECEIPT', 'no qualifying exact-version live receipt exists for this target/component');
+  }
+
+  const versionObs = port.run({ command: 'claude', args: ['--version'], cwd: options.projectRoot, timeoutMs: INTEGRATION_PROBE_TIMEOUT_MS });
+  if (versionObs.errorCode === 'ENOENT') return failed(options, 'TARGET_BINARY_UNAVAILABLE', 'install Claude Code and rerun dz integrations-verify');
+  if (versionObs.errorCode === 'ETIMEDOUT' || versionObs.signal === 'SIGKILL') return failed(options, 'LIVE_PROBE_TIMEOUT', `Claude version probe exceeded ${INTEGRATION_PROBE_TIMEOUT_MS}ms`);
+  if (versionObs.errorCode !== undefined) return failed(options, 'LIVE_PROBE_FAILED', `Claude version probe failed before a trustworthy observation (${versionObs.errorCode})`);
+  const versionText = decodeBounded(versionObs);
+  if (typeof versionText === 'string') return failed(options, versionText, 'Claude version output was oversized or invalid UTF-8');
+  if (versionObs.status !== 0) return failed(options, 'LIVE_PROBE_FAILED', 'Claude version probe exited non-zero');
+  const runtimeVersion = parseClaudeVersion(`${versionText.stdout}\n${versionText.stderr}`);
+  if (runtimeVersion === undefined) return failed(options, 'LIVE_PROBE_FAILED', 'Claude version output did not contain an attributable semantic version');
+  const evidence = assessClaudeMcpEvidence(runtimeVersion);
+  if (!evidence.eligible) return failed(options, evidence.reasonCode ?? 'RECEIPT_STALE', `expected Claude Code ${CLAUDE_MCP_RECEIPT.runtimeVersion}; rerun after a matching receipt is recorded`, runtimeVersion);
+
+  if ((options.phase ?? 'preflight') === 'preflight') {
+    const probeId = 'dz-registration-probe';
+    const probeRoot = mkdtempSync(join(tmpdir(), 'dz-claude-mcp-probe-'));
+    try {
+      writeFileSync(join(probeRoot, '.mcp.json'), `${JSON.stringify({
+        mcpServers: { [probeId]: { type: 'stdio', command: 'node', args: ['-e', 'process.exit(0)'] } },
+      }, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+      const observation = port.run({
+        command: 'claude', args: ['mcp', 'get', probeId], cwd: probeRoot, timeoutMs: INTEGRATION_PROBE_TIMEOUT_MS,
+      });
+      const parsed = parseClaudeProjectRegistration(options, probeId, observation, runtimeVersion);
+      return parsed.ok ? { ...parsed, registrations: [] } : parsed;
+    } finally {
+      rmSync(probeRoot, { recursive: true, force: true });
+    }
+  }
+  const id = options.registrationId;
+  if (id === undefined) return failed(options, 'LIVE_PROBE_FAILED', 'post-write verification requires an exact registration id', runtimeVersion);
+  return parseClaudeProjectRegistration(
+    options,
+    id,
+    port.run({ command: 'claude', args: ['mcp', 'get', id], cwd: options.projectRoot, timeoutMs: INTEGRATION_PROBE_TIMEOUT_MS }),
+    runtimeVersion,
+  );
+}
+
+export interface RunIntegrationsVerifyOptions extends VerifyTargetIntegrationOptions {}
+
+export function runIntegrationsVerify(options: RunIntegrationsVerifyOptions): IntegrationVerification {
+  return verifyTargetIntegration(options);
+}