@dzhechkov/harness-core 0.8.5 → 0.8.10

package/src/model-recommender.ts

@@ -92,7 +92,9 @@ export function harvestStageOutcomes(records: readonly unknown[]): Harvest {
     if (!isRecord(modelsUsed)) { skipped.noModels += 1; continue; }
     const grade = extractGrade(result);
     if (grade === null) { skipped.noGrade += 1; continue; }
-    const runId = typeof source['runId'] === 'string' ? source['runId'] : JSON.stringify(modelsUsed).slice(0, 40);
+    // Full canonical JSON is intentional: the former 40-character prefix merged distinct records
+    // whose stage names shared a long prefix, manufacturing idempotency across different runs.
+    const runId = typeof source['runId'] === 'string' ? source['runId'] : `models:${JSON.stringify(modelsUsed)}`;
     const ts = typeof source['timestamp'] === 'string' ? source['timestamp'] : null;
     const tier = typeof result['tier'] === 'string' && result['tier'] !== '' ? result['tier'] : 'unknown';
     let contributed = false;
@@ -138,6 +140,8 @@ export interface Recommendation {
     readonly rule: string;
     readonly skipped: Harvest['skipped'];
     readonly crossFamilyNote: string;
+    readonly unfed: { readonly count: number; readonly runIds: string[] };
+    readonly freshness: 'current' | 'stale' | 'unfed';
   };
 }
 
@@ -154,7 +158,7 @@ const CROSS_NOTE =
   'the qe pick is computed with the family FORCED to the cross of the code pick — a same-family qe recommendation is unrepresentable (ADR-001 D3)';
 
 /** Recommend per stage over the harvested samples (optionally one tier's slice). */
-export function recommendModels(harvest: Harvest, opts: { tier?: string; qualityBar?: number; minSamples?: number } = {}): Recommendation {
+export function recommendModels(harvest: Harvest, opts: { tier?: string; qualityBar?: number; minSamples?: number; alreadyFed?: readonly string[] } = {}): Recommendation {
   const slice = opts.tier === undefined ? harvest.samples : harvest.samples.filter((s) => s.tier === opts.tier);
   const tierLabel = opts.tier ?? 'all';
   const byStage = new Map<string, HarvestSample[]>();
@@ -197,9 +201,21 @@ export function recommendModels(harvest: Harvest, opts: { tier?: string; quality
     }
   }
   if (!stages.includes('code')) perStage.unshift(code);
+  const pending = unfedRuns(harvest.samples, opts.alreadyFed ?? []);
+  const harvestRunIds = [...new Set(harvest.samples.map((s) => s.runId))];
+  const fed = new Set(opts.alreadyFed ?? []);
+  const fedInHarvest = harvestRunIds.filter((runId) => fed.has(runId)).length;
   return {
     perStage,
-    basis: { runsUsed: harvest.runsUsed, window: harvest.window, rule: harvest.rule, skipped: harvest.skipped, crossFamilyNote: CROSS_NOTE },
+    basis: {
+      runsUsed: harvest.runsUsed,
+      window: harvest.window,
+      rule: harvest.rule,
+      skipped: harvest.skipped,
+      crossFamilyNote: CROSS_NOTE,
+      unfed: { count: pending.length, runIds: pending },
+      freshness: pending.length === 0 ? 'current' : fedInHarvest === 0 ? 'unfed' : 'stale',
+    },
   };
 }
 
@@ -213,15 +229,30 @@ export interface FeedPlan {
   readonly fedAfter: string[];
 }
 
+/** One shared definition of the telemetry/store gap, used by recommendation, apply and guard. */
+export function unfedRuns(samples: readonly HarvestSample[], alreadyFed: readonly string[]): string[] {
+  const fed = new Set(alreadyFed);
+  return [...new Set(samples.map((s) => s.runId))].filter((runId) => !fed.has(runId)).sort();
+}
+
 /** A run feeds ONCE. Double-feeding the same telemetry manufactures confidence the data does not
  * contain — the second `--apply` must feed 0 and say which runs it skipped. */
 export function planFeed(samples: readonly HarvestSample[], alreadyFed: readonly string[]): FeedPlan {
   const fed = new Set(alreadyFed);
   const toFeed: HarvestSample[] = [];
   const skippedRuns = new Set<string>();
+  const seenSamples = new Set<string>();
   for (const s of samples) {
     if (fed.has(s.runId)) skippedRuns.add(s.runId);
-    else toFeed.push(s);
+    else {
+      // A multi-stage run legitimately feeds one sample per stage. Only a repeated sample from a
+      // duplicated record is suppressed within this harvest.
+      const sampleKey = JSON.stringify([s.runId, s.stage]);
+      if (!seenSamples.has(sampleKey)) {
+        seenSamples.add(sampleKey);
+        toFeed.push(s);
+      }
+    }
   }
   const fedAfter = [...new Set([...alreadyFed, ...toFeed.map((s) => s.runId)])].sort();
   return { toFeed, skippedRuns: [...skippedRuns].sort(), fedAfter };

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 } : {}),
+  };
 }
 
 // ---------------------------------------------------------------------------