@dzhechkov/harness-core 0.8.6 → 0.8.10

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

package/src/lesson-generalization.ts

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto';
+
+export type LessonForm = 'specific' | 'class';
+export type LessonMatchedForm = 'specific' | 'class' | 'both';
+
+export interface LessonFormsInput {
+  readonly specific: string;
+  readonly classForm?: string;
+  readonly classAdvisory?: string;
+}
+
+export interface LessonFormRankedHit<T> {
+  readonly key: string;
+  readonly value: T;
+  readonly matchedForm: LessonForm;
+}
+
+export interface MergedLessonFormHit<T> {
+  readonly key: string;
+  readonly value: T;
+  readonly matchedForm: LessonMatchedForm;
+  readonly score: number;
+}
+
+export function normalizeLessonForms(specific: string, classInput?: unknown): LessonFormsInput {
+  if (classInput === undefined || (typeof classInput === 'string' && classInput.trim() === '')) {
+    return { specific };
+  }
+  if (typeof classInput !== 'string') {
+    return { specific, classAdvisory: 'class form must be text; the specific lesson was kept' };
+  }
+  return { specific, classForm: classInput.trim() };
+}
+
+function normalizedText(value: string): string {
+  return value.normalize('NFC').toLocaleLowerCase('und').replace(/\s+/gu, ' ').trim();
+}
+
+function escapedLiteral(value: string): string {
+  return normalizedText(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
+}
+
+export function validateClassTemplate(
+  specific: string,
+  classTemplate: string,
+): { readonly ok: true } | { readonly ok: false; readonly reason: string } {
+  const slot = /:([A-Za-z][A-Za-z0-9_-]*)/g;
+  const parts: string[] = [];
+  let slots = 0;
+  let cursor = 0;
+  for (const match of classTemplate.matchAll(slot)) {
+    const index = match.index ?? 0;
+    const literal = classTemplate.slice(cursor, index);
+    if (literal.includes(':')) return { ok: false, reason: 'invalid :slot name' };
+    parts.push(escapedLiteral(literal), '(.+?)');
+    slots += 1;
+    cursor = index + match[0].length;
+  }
+  const tail = classTemplate.slice(cursor);
+  if (tail.includes(':')) return { ok: false, reason: 'invalid :slot name' };
+  if (slots === 0) return { ok: false, reason: 'class form must contain at least one :slot' };
+  parts.push(escapedLiteral(tail));
+  try {
+    return new RegExp(`^${parts.join('')}$`, 'u').test(normalizedText(specific))
+      ? { ok: true }
+      : { ok: false, reason: 'class form does not syntactically cover the specific lesson' };
+  } catch {
+    return { ok: false, reason: 'class form contains an invalid template' };
+  }
+}
+
+export function lessonPairIdOf(specific: string, classTemplate: string, ts: string): string {
+  const digest = createHash('sha256')
+    .update(`${specific}\u0000${classTemplate}\u0000${ts}`)
+    .digest('hex')
+    .slice(0, 16);
+  return `lesson-pair:${digest}`;
+}
+
+export function mergeLessonMatchedForms(
+  left: LessonMatchedForm | undefined,
+  right: LessonMatchedForm | undefined,
+): LessonMatchedForm | undefined {
+  if (left === undefined) return right;
+  if (right === undefined || left === right) return left;
+  return 'both';
+}
+
+export function mergeLessonFormHits<T>(
+  specificHits: readonly LessonFormRankedHit<T>[],
+  classHits: readonly LessonFormRankedHit<T>[],
+  limit: number,
+): MergedLessonFormHit<T>[] {
+  interface Acc { value: T; specific: boolean; classForm: boolean; score: number }
+  const merged = new Map<string, Acc>();
+  const add = (hit: LessonFormRankedHit<T>, rank: number): void => {
+    const current = merged.get(hit.key) ?? { value: hit.value, specific: false, classForm: false, score: 0 };
+    if (hit.matchedForm === 'specific') current.specific = true;
+    else current.classForm = true;
+    current.score += 1 / (60 + rank + 1);
+    merged.set(hit.key, current);
+  };
+  specificHits.forEach(add);
+  classHits.forEach(add);
+  const safeLimit = Number.isFinite(limit) ? Math.max(0, Math.trunc(limit)) : merged.size;
+  return [...merged.entries()]
+    .sort((a, b) => b[1].score - a[1].score || a[0].localeCompare(b[0]))
+    .slice(0, safeLimit)
+    .map(([key, hit]) => ({
+      key,
+      value: hit.value,
+      matchedForm: hit.specific && hit.classForm ? 'both' : hit.classForm ? 'class' : 'specific',
+      score: hit.score,
+    }));
+}

package/src/operations.ts

@@ -57,6 +57,17 @@ import { describeSkillLoadFailure, discoverSkillIds, loadSkillFromDir } from './
 import type { SkillApplyFailure, SkillLoadFailure } from './skills.js';
 import { TARGETS } from './targets.js';
 import type { TargetName } from './targets.js';
+import {
+  TARGET_INTEGRATIONS,
+  aggregateIntegrationManifests,
+  notRequestedOutcomes,
+  refusedOutcome,
+  staticPolicyOutcomes,
+  type IntegrationOutcome,
+  type IntegrationManifestSource,
+} from './target-integrations.js';
+import { applyIntegrationFragments, IntegrationApplyError, type IntegrationApplyFault } from './integration-apply.js';
+import { verifyTargetIntegration, type IntegrationProcessPort } from './integrations-verify.js';
 import {
   AGENTS_MD_BUDGET_WARN_FRACTION,
   CODEX_PROJECT_DOC_MAX_BYTES,
@@ -87,6 +98,24 @@ export interface InitOptions {
   readonly select?: readonly string[];
   /** When set, generate platform-specific enrichment files alongside SKILL.md. */
   readonly enrich?: boolean;
+  /** Exact content-bound digest printed by the first integration-aware run. */
+  readonly allowIntegrations?: string;
+  /** Explicit hook opt-out; maps hooks to not-requested. */
+  readonly noHooks?: boolean;
+  /** Explicit skills-only opt-out, even when selected skills carry manifests. */
+  readonly noIntegrations?: boolean;
+  /** Live verification is load-bearing; requesting this flag makes requested integrations refuse. */
+  readonly noVerify?: boolean;
+  /** Injectable process boundary for deterministic integration tests. */
+  readonly integrationProcessPort?: IntegrationProcessPort;
+  /** Test-only fault at the carrier/ownership-journal durability boundary. */
+  readonly integrationApplyFault?: IntegrationApplyFault;
+  /**
+   * Install-level manifest sources. The CLI supplies this only on the first
+   * per-directory run so companion planning, authorization, and probing happen
+   * exactly once across every discovered skill pack.
+   */
+  readonly integrationManifestSources?: readonly IntegrationManifestSource[];
 }
 
 /** Per-skill outcome of {@link runInit}. */
@@ -130,6 +159,10 @@ export interface InitReport {
    * any per-skill loop.
    */
   readonly applyFailures: readonly SkillApplyFailure[];
+  /** Exactly two ordered companion outcomes: MCP, then hooks. */
+  readonly integrations: readonly [IntegrationOutcome, IntegrationOutcome];
+  /** Safe digest used by `--allow-integrations`; absent when no manifest exists. */
+  readonly integrationDigest?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -266,6 +299,8 @@ export interface AgentsMdInitOptions {
   readonly projectRoot: string;
   /** When set, install only these skill ids (a preset selection). */
   readonly select?: readonly string[] | undefined;
+  readonly noHooks?: boolean;
+  readonly noIntegrations?: boolean;
 }
 
 /** The parts of a single-file managed-Markdown target that vary by filename. */
@@ -367,6 +402,28 @@ function runInitSingleFileMd(options: AgentsMdInitOptions, config: SingleFileMdC
   }
   const missing = selection === undefined ? [] : selection.filter((id) => !discovered.has(id));
 
+  let aggregate = { manifest: undefined, digest: undefined } as ReturnType<typeof aggregateIntegrationManifests>;
+  try {
+    if (options.noIntegrations !== true) {
+      aggregate = aggregateIntegrationManifests(picked.map(({ id, skillsDir }) => ({ skillId: id, skillDir: skillsDir })));
+    }
+  } catch (error) {
+    const remediation = error instanceof Error ? error.message : String(error);
+    return {
+      target: config.target,
+      skillsDir: joinedDir,
+      projectRoot: options.projectRoot,
+      skills: [],
+      missing,
+      failures: [],
+      applyFailures: [],
+      integrations: [
+        refusedOutcome(config.target, 'mcp', 'MANIFEST_INVALID', remediation),
+        refusedOutcome(config.target, 'hooks', 'MANIFEST_INVALID', remediation),
+      ],
+    };
+  }
+
   // Skip-and-collect: one unloadable skill must not discard the whole aggregation.
   const failures: SkillLoadFailure[] = [];
   const loaded: { id: string; section: string }[] = [];
@@ -397,7 +454,19 @@ function runInitSingleFileMd(options: AgentsMdInitOptions, config: SingleFileMdC
 
   // No apply failures are possible here: the single write is outside every per-skill
   // loop, so a write error propagates as itself rather than being attributed to a skill.
-  return { target: config.target, skillsDir: joinedDir, projectRoot: options.projectRoot, skills, missing, failures, applyFailures: [] };
+  return {
+    target: config.target,
+    skillsDir: joinedDir,
+    projectRoot: options.projectRoot,
+    skills,
+    missing,
+    failures,
+    applyFailures: [],
+    integrations: options.noIntegrations === true
+      ? notRequestedOutcomes(config.target)
+      : staticPolicyOutcomes(config.target, aggregate.manifest, options.noHooks === true),
+    ...(aggregate.digest !== undefined ? { integrationDigest: aggregate.digest } : {}),
+  };
 }
 
 /**
@@ -546,6 +615,8 @@ export async function runInit(options: InitOptions): Promise<InitReport> {
       skillsDirs: [options.skillsDir],
       projectRoot: options.projectRoot,
       select: options.select,
+      ...(options.noHooks !== undefined ? { noHooks: options.noHooks } : {}),
+      ...(options.noIntegrations !== undefined ? { noIntegrations: options.noIntegrations } : {}),
     });
   }
   // gemini is likewise a flattening single-file target — aggregate into ONE root
@@ -555,6 +626,8 @@ export async function runInit(options: InitOptions): Promise<InitReport> {
       skillsDirs: [options.skillsDir],
       projectRoot: options.projectRoot,
       select: options.select,
+      ...(options.noHooks !== undefined ? { noHooks: options.noHooks } : {}),
+      ...(options.noIntegrations !== undefined ? { noIntegrations: options.noIntegrations } : {}),
     });
   }
 
@@ -568,6 +641,78 @@ export async function runInit(options: InitOptions): Promise<InitReport> {
   const missing = selection === undefined
     ? []
     : selection.filter((id) => !discovered.includes(id));
+  const manifestSources: readonly IntegrationManifestSource[] = options.integrationManifestSources
+    ?? ids.map((id) => ({ skillId: id, skillDir: options.skillsDir }));
+  let aggregate = { manifest: undefined, digest: undefined } as ReturnType<typeof aggregateIntegrationManifests>;
+  try {
+    if (options.noIntegrations !== true) aggregate = aggregateIntegrationManifests(manifestSources);
+  } catch (error) {
+    const remediation = error instanceof Error ? error.message : String(error);
+    return {
+      target: options.target,
+      skillsDir: options.skillsDir,
+      projectRoot: options.projectRoot,
+      skills: [],
+      missing,
+      failures: [],
+      applyFailures: [],
+      integrations: [
+        refusedOutcome(options.target, 'mcp', 'MANIFEST_INVALID', remediation),
+        refusedOutcome(options.target, 'hooks', 'MANIFEST_INVALID', remediation),
+      ],
+    };
+  }
+
+  let integrations: readonly [IntegrationOutcome, IntegrationOutcome] = notRequestedOutcomes(options.target);
+  let eligibleClaudePlan: ReturnType<(typeof TARGET_INTEGRATIONS)['claude-code']['plan']> | undefined;
+  if (aggregate.manifest !== undefined && options.noIntegrations !== true) {
+    if (options.target !== 'claude-code') {
+      integrations = staticPolicyOutcomes(options.target, aggregate.manifest, options.noHooks === true);
+    } else {
+      const mcpRequested = Object.keys(aggregate.manifest.mcpServers ?? {}).length > 0;
+      const hooksRequested = (aggregate.manifest.hooks?.length ?? 0) > 0 && options.noHooks !== true;
+      let mcpOutcome: IntegrationOutcome = { target: options.target, component: 'mcp', status: 'not-requested', registrations: [] };
+      if (mcpRequested) {
+        if (options.noVerify === true) {
+          mcpOutcome = refusedOutcome(options.target, 'mcp', 'NO_QUALIFYING_LIVE_RECEIPT', '--no-verify cannot authorize integration emission; rerun with live verification enabled');
+        } else if (aggregate.digest === undefined || options.allowIntegrations !== aggregate.digest) {
+          mcpOutcome = refusedOutcome(options.target, 'mcp', 'INTEGRATION_AUTHORIZATION_REQUIRED', `rerun with --allow-integrations ${aggregate.digest ?? '<missing-digest>'}`);
+        } else {
+          const plan = TARGET_INTEGRATIONS['claude-code'].plan(aggregate.manifest, { target: 'claude-code' });
+          const refusal = plan.refusals.find((row) => row.component === 'mcp');
+          if (refusal !== undefined) {
+            mcpOutcome = refusedOutcome(options.target, 'mcp', refusal.reasonCode, refusal.remediation);
+          } else {
+            const preflight = verifyTargetIntegration({
+              target: 'claude-code',
+              component: 'mcp',
+              projectRoot: options.projectRoot,
+              phase: 'preflight',
+              ...(options.integrationProcessPort !== undefined ? { processPort: options.integrationProcessPort } : {}),
+            });
+            if (!preflight.ok) {
+              mcpOutcome = refusedOutcome(options.target, 'mcp', preflight.reasonCode ?? 'LIVE_PROBE_FAILED', preflight.remediation ?? 'live preflight did not qualify');
+            } else {
+              eligibleClaudePlan = plan;
+              mcpOutcome = {
+                target: options.target,
+                component: 'mcp',
+                status: 'emitted',
+                registrations: [],
+                carrier: { scope: 'project', path: '.mcp.json' },
+                ...(preflight.runtimeVersion !== undefined ? { runtimeVersion: preflight.runtimeVersion } : {}),
+                ...(preflight.evidenceVersion !== undefined ? { evidenceVersion: preflight.evidenceVersion } : {}),
+              };
+            }
+          }
+        }
+      }
+      const hookOutcome: IntegrationOutcome = hooksRequested
+        ? refusedOutcome(options.target, 'hooks', 'NO_ACTIVATION_RECEIPT', 'record a nonce canary and negative-control activation receipt')
+        : { target: options.target, component: 'hooks', status: 'not-requested', registrations: [] };
+      integrations = [mcpOutcome, hookOutcome];
+    }
+  }
   // Skip-and-collect (D1): one unparseable SKILL.md must not discard the whole install.
   // Same shape as `runVerify`'s long-standing per-id try/catch below.
   //
@@ -602,7 +747,59 @@ export async function runInit(options: InitOptions): Promise<InitReport> {
       applyFailures.push({ id, reason: error instanceof Error ? error.message : String(error) });
     }
   }
-  return { target: options.target, skillsDir: options.skillsDir, projectRoot: options.projectRoot, skills, missing, failures, applyFailures };
+  if (eligibleClaudePlan !== undefined && integrations[0].status === 'emitted') {
+    try {
+      applyIntegrationFragments({
+        projectRoot: options.projectRoot,
+        fragments: eligibleClaudePlan.fragments,
+        ...(options.integrationApplyFault !== undefined ? { injectFault: options.integrationApplyFault } : {}),
+      });
+      const registrations = Object.keys(aggregate.manifest?.mcpServers ?? {});
+      const observed = [];
+      let failedObservation: ReturnType<typeof verifyTargetIntegration> | undefined;
+      for (const registrationId of registrations) {
+        const result = verifyTargetIntegration({
+          target: 'claude-code',
+          component: 'mcp',
+          projectRoot: options.projectRoot,
+          registrationId,
+          phase: 'post-write',
+          ...(options.integrationProcessPort !== undefined ? { processPort: options.integrationProcessPort } : {}),
+        });
+        if (!result.ok) { failedObservation = result; break; }
+        observed.push(...result.registrations);
+      }
+      if (failedObservation !== undefined) {
+        integrations = [
+          {
+            ...refusedOutcome(options.target, 'mcp', failedObservation.reasonCode ?? 'POST_WRITE_REGISTRATION_NOT_OBSERVED', failedObservation.remediation ?? 'registration was written but not observed'),
+            carrier: { scope: 'project', path: '.mcp.json' },
+            applied: true,
+          },
+          integrations[1],
+        ];
+      } else {
+        integrations = [{ ...integrations[0], registrations: observed }, integrations[1]];
+      }
+    } catch (error) {
+      const reasonCode = error instanceof IntegrationApplyError ? error.reasonCode : 'APPLY_FAILED';
+      integrations = [{
+        ...refusedOutcome(options.target, 'mcp', reasonCode, error instanceof Error ? error.message : String(error)),
+        ...(error instanceof IntegrationApplyError && error.applied ? { applied: true } : {}),
+      }, integrations[1]];
+    }
+  }
+  return {
+    target: options.target,
+    skillsDir: options.skillsDir,
+    projectRoot: options.projectRoot,
+    skills,
+    missing,
+    failures,
+    applyFailures,
+    integrations,
+    ...(aggregate.digest !== undefined ? { integrationDigest: aggregate.digest } : {}),
+  };
 }
 
 // ---------------------------------------------------------------------------