@unbrained/pm-cli 2026.8.13 → 2026.8.15

package/dist/sdk/governance/extension-host-version.js

@@ -0,0 +1,105 @@
+/**
+ * @module sdk/governance/extension-host-version
+ *
+ * Discovers the pm-cli copy that each loaded extension resolves at runtime so
+ * package-manager layout skew is visible before SDK singleton state diverges.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b55cafdc-9a3b-5386-bd85-cbd2311a5933")}catch(e){}}();
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { resolvePmPackageRootFromModule } from "../../core/packages/root.js";
+function displayPackagePath(packageJsonPath, workspaceRoot) {
+    const relative = path.relative(workspaceRoot, packageJsonPath);
+    if (relative.length > 0 &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative)) {
+        return relative.split(path.sep).join("/");
+    }
+    const externalPath = path.resolve(packageJsonPath);
+    let fingerprint = 0xcbf29ce484222325n;
+    for (let index = 0; index < externalPath.length; index += 1) {
+        fingerprint ^= BigInt(externalPath.charCodeAt(index));
+        fingerprint = BigInt.asUintN(64, fingerprint * 0x100000001b3n);
+    }
+    const installationId = fingerprint.toString(16).padStart(16, "0");
+    return `<external>/${installationId}/${path.basename(path.dirname(packageJsonPath))}/package.json`;
+}
+function dependencyLayout(packageJsonPath) {
+    if (packageJsonPath.includes(`${path.sep}.pnpm${path.sep}`))
+        return "pnpm";
+    if (packageJsonPath.includes(`${path.sep}node_modules${path.sep}`)) {
+        return "npm";
+    }
+    return "other";
+}
+async function readPackageVersion(packageJsonPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+        return parsed.name === "@unbrained/pm-cli" &&
+            typeof parsed.version === "string" &&
+            parsed.version.trim().length > 0
+            ? parsed.version.trim()
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Scan the host plus the nearest pm-cli package resolvable by every loaded extension. */
+export async function scanExtensionHostVersions(loadedExtensions, workspaceRoot, hostPackageRoot = resolvePmPackageRootFromModule(import.meta.url, [
+    "../../..",
+])) {
+    const hostPackageJson = path.join(hostPackageRoot, "package.json");
+    const hostVersion = await readPackageVersion(hostPackageJson);
+    const copies = new Map();
+    if (hostVersion !== undefined) {
+        copies.set(path.resolve(hostPackageJson), {
+            version: hostVersion,
+            path: displayPackagePath(hostPackageJson, workspaceRoot),
+            layout: "host",
+            consumers: ["pm-cli-host"],
+        });
+    }
+    for (const extension of loadedExtensions) {
+        try {
+            const resolved = createRequire(extension.entry_path).resolve("@unbrained/pm-cli/package.json");
+            const version = await readPackageVersion(resolved);
+            if (version === undefined)
+                continue;
+            const key = path.resolve(resolved);
+            const existing = copies.get(key);
+            if (existing) {
+                if (!existing.consumers.includes(extension.name)) {
+                    existing.consumers.push(extension.name);
+                    existing.consumers.sort((left, right) => left.localeCompare(right));
+                }
+                continue;
+            }
+            copies.set(key, {
+                version,
+                path: displayPackagePath(resolved, workspaceRoot),
+                layout: dependencyLayout(resolved),
+                consumers: [extension.name],
+            });
+        }
+        catch {
+            // Extensions that do not resolve pm-cli use the host surface they were
+            // handed. Load/activation diagnostics own unrelated resolution failures.
+        }
+    }
+    const sortedCopies = [...copies.values()].sort((left, right) => left.path.localeCompare(right.path));
+    const mismatches = hostVersion === undefined
+        ? []
+        : sortedCopies.filter((copy) => copy.version !== hostVersion);
+    return {
+        host_version: hostVersion ?? null,
+        copies: sortedCopies,
+        mismatches,
+        warnings: mismatches.map((copy) => `extension_host_pm_cli_version_skew:${hostVersion}:${copy.version}:${copy.consumers.join("+")}`),
+    };
+}
+//# sourceMappingURL=extension-host-version.js.map
+//# debugId=b55cafdc-9a3b-5386-bd85-cbd2311a5933

package/dist/sdk/governance/health.d.ts

@@ -20,6 +20,21 @@ export interface HealthCheck {
     /** Value that configures or reports details for this contract. */
     details: Record<string, unknown>;
 }
+/** One warning indexed to the check, severity, and safe next action that decide health. */
+export interface HealthFinding {
+    /** Original stable warning token. */
+    warning: string;
+    /** Stable colon-delimited warning code. */
+    code: string;
+    /** Health check that owns the finding. */
+    check: HealthCheck["name"];
+    /** Whether the finding blocks the top-level health verdict. */
+    severity: "advisory" | "gate_failing";
+    /** Executable remediation when one is safe and fully specified. */
+    remediation?: string;
+    /** Explicit refusal when automatic remediation would require operator choices. */
+    disposition?: "no_safe_automatic_remediation";
+}
 /** Documents the health result payload exchanged by command, SDK, and package integrations. */
 export interface HealthResult {
     /** Whether the operation completed without a blocking failure. */
@@ -28,8 +43,16 @@ export interface HealthResult {
     checks: HealthCheck[];
     /** Number of warning entries represented by this result. */
     warning_count?: number;
+    /** Maximum warning rows retained in every projection. */
+    warning_limit?: number;
+    /** Whether warning rows were omitted after the declared limit. */
+    warnings_truncated?: boolean;
     /** Value that configures or reports warnings for this contract. */
     warnings: string[];
+    /** Every retained warning indexed to its owning check and severity. */
+    findings: HealthFinding[];
+    /** Exact gate-failing warning tokens that make `ok` false. */
+    failed_because: string[];
     /** Value that configures or reports projection for this contract. */
     projection?: {
         mode: "brief" | "summary" | "full";
@@ -115,7 +138,7 @@ interface ExtensionHealthTriageSummary {
     top_warnings: string[];
     remediation: string[];
 }
-/** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. Invalid legacy provenance values remain immutable diagnostic evidence: write-time resolvers reject new invalid values, while health reports the bounded aggregate without requiring truthful history to be rewritten. */
+/** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. Invalid legacy provenance remains advisory until an operator explicitly applies the privacy-safe history normalizer. */
 declare function isAdvisoryHealthWarning(warning: string, requireMergeDrivers?: boolean): boolean;
 declare function warningCode(value: string): string;
 declare function normalizeExtensionNameForMatch(value: string): string;
@@ -183,12 +206,20 @@ declare function buildStaleInProgressHealthSummary(scan: StaleInProgressScan): {
     scan: StaleInProgressScan;
     warnings: string[];
 };
+/** Index every warning to exactly one health check, severity, and safe next action. */
+declare function buildHealthFindings(params: {
+    warnings: string[];
+    checks: HealthCheck[];
+    remediationSources: Record<HealthCheck["name"], string[]>;
+    requireMergeDrivers: boolean;
+}): HealthFinding[];
 declare function projectHealthResult(result: HealthResult, options: RunHealthOptions, summaryMode: boolean): HealthResult;
 /** Implements run health for the public runtime surface of this module. */
 export declare function runHealth(global: GlobalOptions, options?: RunHealthOptions): Promise<HealthResult>;
 /** Public contract for test only health command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlyHealthCommand: {
     buildExtensionHealthTriageSummary: typeof buildExtensionHealthTriageSummary;
+    buildHealthFindings: typeof buildHealthFindings;
     buildCapabilityContractMetadata: typeof buildCapabilityContractMetadata;
     buildStaleInProgressHealthSummary: typeof buildStaleInProgressHealthSummary;
     buildVectorizationProviderDetails: typeof buildVectorizationProviderDetails;

package/dist/sdk/governance/health.js

@@ -4,11 +4,11 @@
  * Implements the pm health command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5cee1eaa-73f3-5709-867f-a8d73081da8b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e7be701e-085c-5903-96da-61149452c673")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
-import { isFileMissingError, pathExists, readFileIfExists } from "../../core/fs/fs-utils.js";
+import { isFileMissingError, pathExists, readFileIfExists, } from "../../core/fs/fs-utils.js";
 import { activateExtensions, getActiveExtensionRegistrations, loadExtensions, runActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
 import { KNOWN_EXTENSION_CAPABILITIES, } from "../../core/extensions/loader.js";
@@ -30,9 +30,10 @@ import { parseItemDocument } from "../../core/item/item-format.js";
 import { effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
 import { listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
 import { PM_TELEMETRY_SOURCE_CONTEXT_VALUES, TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS, TELEMETRY_SCHEMA_VERSION, } from "../../core/telemetry/runtime.js";
-import { getItemFormatFromPath, getSettingsPath, ITEM_FILE_EXTENSIONS, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { getItemFormatFromPath, getSettingsPath, ITEM_FILE_EXTENSIONS, resolveGlobalPmRoot, resolvePmRoot, resolveWorkspaceRoot, } from "../../core/store/paths.js";
 import { readSettingsWithMetadata } from "../../core/store/settings.js";
-import { buildRemediationMap } from "../../core/diagnostics/remediation.js";
+import { buildRemediationMap, resolveRemediation, } from "../../core/diagnostics/remediation.js";
+import { scanExtensionHostVersions } from "./extension-host-version.js";
 import { scanHistoryAuthorAttribution, } from "../author-attribution.js";
 import { readManagedExtensionState } from "../extension.js";
 import { scanProvenanceResolverHealth } from "./provenance-health.js";
@@ -45,6 +46,7 @@ import { listMergeReceipts, partitionMergeReceipts, } from "../merge/receipts.js
 const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
 const STALE_VECTORIZATION_SUMMARY_LIMIT = 25;
 const BRIEF_HEALTH_DETAIL_LIMIT = 8;
+const HEALTH_WARNING_LIMIT = 100;
 const TELEMETRY_QUEUE_RELATIVE_PATH = path.join("runtime", "telemetry", "events.jsonl");
 const TELEMETRY_STATE_RELATIVE_PATH = path.join("runtime", "telemetry", "state.json");
 const TELEMETRY_ENDPOINT_PROBE_TIMEOUT_MS = 2_500;
@@ -54,7 +56,7 @@ const TELEMETRY_SERVER_MAX_SCHEMA_VERSION_HEADERS = [
     "x-pm-telemetry-max-schema-version",
     "x-pm-telemetry-max-version",
 ];
-/** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. Invalid legacy provenance values remain immutable diagnostic evidence: write-time resolvers reject new invalid values, while health reports the bounded aggregate without requiring truthful history to be rewritten. */
+/** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. Invalid legacy provenance remains advisory until an operator explicitly applies the privacy-safe history normalizer. */
 function isAdvisoryHealthWarning(warning, requireMergeDrivers = false) {
     return (warning.startsWith("telemetry_") ||
         warning.startsWith("history_stream_over_compact_threshold:") ||
@@ -612,6 +614,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
         noExtensions: noExtensionsFlag,
     });
     const loadedSummaries = loadResult.loaded.map((extension) => summarizeLoadedExtension(extension));
+    const hostVersionCensus = await scanExtensionHostVersions(loadResult.loaded, resolveWorkspaceRoot(pmRoot));
     const activationResult = await activateExtensions({
         ...loadResult,
         loaded: loadResult.loaded,
@@ -696,6 +699,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
         ...projectManagedState.warnings,
         ...globalManagedState.warnings,
         ...updateCoverageWarnings,
+        ...hostVersionCensus.warnings,
     ];
     const capabilityGuidance = collectUnknownCapabilityGuidance(extensionWarnings);
     const capabilityContract = buildCapabilityContractMetadata();
@@ -721,6 +725,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
                     : {}),
                 capability_contract: capabilityContract,
                 capability_guidance: capabilityGuidance,
+                host_version_census: hostVersionCensus,
             },
         },
         warnings: extensionWarnings,
@@ -858,6 +863,7 @@ const HEALTH_DETAIL_SUMMARIZERS = {
             triage: details.triage,
             capability_contract: details.capability_contract,
             capability_guidance: summarizeRecordList(details.capability_guidance, limit),
+            host_version_census: details.host_version_census,
         };
     },
     storage: (details, limit) => {
@@ -917,6 +923,9 @@ const HEALTH_DETAIL_SUMMARIZERS = {
         unreadable_streams: summarizeStringList(details.unreadable_streams, limit),
         hash_mismatches: summarizeStringList(details.hash_mismatches, limit),
         chain_mismatches: summarizeStringList(details.chain_mismatches, limit),
+        workspace_state_mismatches: summarizeStringList(details.workspace_state_mismatches, limit),
+        workspace_state_missing: summarizeStringList(details.workspace_state_missing, limit),
+        workspace_state_unreadable: summarizeStringList(details.workspace_state_unreadable, limit),
         skipped: details.skipped,
     }),
     vectorization: (details, limit) => ({
@@ -958,6 +967,9 @@ function applyBriefHealthProjection(result) {
             details: summarizeHealthCheckDetails(check, BRIEF_HEALTH_DETAIL_LIMIT),
         })),
         warnings: warningsSummary.sample,
+        findings: result.findings.filter((finding) => warningsSummary.sample.includes(finding.warning) ||
+            result.failed_because.includes(finding.warning)),
+        failed_because: result.failed_because,
         projection: {
             mode: "brief",
             warning_count: warningsSummary.count,
@@ -987,6 +999,9 @@ function applySummaryHealthProjection(result) {
         })),
         warning_count: warningsSummary.count,
         warnings: warningsSummary.sample,
+        findings: result.findings.filter((finding) => warningsSummary.sample.includes(finding.warning) ||
+            result.failed_because.includes(finding.warning)),
+        failed_because: result.failed_because,
         projection: {
             mode: "summary",
             warning_count: warningsSummary.count,
@@ -1351,12 +1366,15 @@ async function buildLocksCheck(pmRoot) {
 }
 async function buildHistoryDriftCheck(pmRoot, items) {
     const cacheHitVerification = "metadata";
-    const { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems, } = await scanHistoryDrift(pmRoot, items, { cacheHitVerification });
+    const { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems, workspaceStateMismatches, workspaceStateMissing, workspaceStateUnreadable, } = await scanHistoryDrift(pmRoot, items, { cacheHitVerification });
     const warnings = [
         ...missingStreams.map((id) => `history_drift_missing_stream:${id}`),
         ...unreadableStreams.map((id) => `history_drift_unreadable_stream:${id}`),
         ...hashMismatches.map((id) => `history_drift_hash_mismatch:${id}`),
         ...chainMismatches.map((id) => `history_drift_chain_mismatch:${id}`),
+        ...workspaceStateMismatches.map((documentPath) => `history_drift_workspace_state_mismatch:${documentPath}`),
+        ...workspaceStateMissing.map((documentPath) => `history_drift_workspace_state_missing:${documentPath}`),
+        ...workspaceStateUnreadable.map((documentPath) => `history_drift_workspace_state_unreadable:${documentPath}`),
     ];
     return {
         check: {
@@ -1373,11 +1391,17 @@ async function buildHistoryDriftCheck(pmRoot, items) {
                     unreadable_streams: unreadableStreams.length,
                     hash_mismatches: hashMismatches.length,
                     chain_mismatches: chainMismatches.length,
+                    workspace_state_mismatches: workspaceStateMismatches.length,
+                    workspace_state_missing: workspaceStateMissing.length,
+                    workspace_state_unreadable: workspaceStateUnreadable.length,
                 },
                 missing_streams: missingStreams,
                 unreadable_streams: unreadableStreams,
                 hash_mismatches: hashMismatches,
                 chain_mismatches: chainMismatches,
+                workspace_state_mismatches: workspaceStateMismatches,
+                workspace_state_missing: workspaceStateMissing,
+                workspace_state_unreadable: workspaceStateUnreadable,
             },
         },
         warnings,
@@ -1807,22 +1831,62 @@ function extractHistoryDriftedCount(historyDriftCheck) {
 function buildHealthRemediationSources(params) {
     return {
         settings: params.normalizedSettingsReadWarnings,
-        directories: params.directoryState.missingDirs.map((dir) => `missing_directory:${dir}`),
+        directories: params.directoryState.missingDirs.map((dir) => `missing_directory:${dir}`).concat(params.directoryState.hookWarnings),
         settings_values: params.settingWarnings,
         telemetry: params.telemetryCheck.warnings,
         extensions: params.extensionCheck.warnings,
         storage: [
+            ...params.historyPolicyWarnings,
             ...params.historySummary.over_threshold.map((id) => `history_stream_over_compact_threshold:${id}`),
             ...params.authorAttributionWarnings,
             ...params.staleInProgressWarnings,
             ...params.provenanceWarnings,
         ],
         locks: params.locksCheck.warnings,
-        integrity: params.integrityCheck.warnings,
+        integrity: [
+            ...params.normalizedItemReadWarnings,
+            ...params.integrityCheck.warnings,
+        ],
         history_drift: params.historyDriftCheck.warnings,
         vectorization: params.vectorizationCheck.warnings,
     };
 }
+/** Index every warning to exactly one health check, severity, and safe next action. */
+function buildHealthFindings(params) {
+    const owners = new Map();
+    for (const [check, warnings] of Object.entries(params.remediationSources)) {
+        for (const warning of warnings) {
+            if (!owners.has(warning))
+                owners.set(warning, check);
+        }
+    }
+    const checksByName = new Map(params.checks.map((check) => [check.name, check]));
+    const findings = params.warnings.map((warning) => {
+        const check = owners.get(warning) ?? "integrity";
+        const code = resolveRemediation(warning)?.code ?? warningCode(warning);
+        const details = checksByName.get(check)?.details;
+        const remediationMap = typeof details?.remediation_map === "object" &&
+            details.remediation_map !== null
+            ? details.remediation_map
+            : {};
+        const remediation = remediationMap[code];
+        const severity = isAdvisoryHealthWarning(warning, params.requireMergeDrivers)
+            ? "advisory"
+            : "gate_failing";
+        return {
+            warning,
+            code,
+            check,
+            severity,
+            ...(typeof remediation === "string"
+                ? { remediation }
+                : severity === "gate_failing"
+                    ? { disposition: "no_safe_automatic_remediation" }
+                    : {}),
+        };
+    });
+    return findings;
+}
 function rewriteBulkHealthRemediation(params) {
     if (params.check.name === "history_drift" && params.historyDriftedCount > 1) {
         for (const code of Object.keys(params.remediationMap)) {
@@ -1850,10 +1914,38 @@ function attachHealthRemediationMaps(params) {
     }
 }
 function projectHealthResult(result, options, summaryMode) {
-    if (summaryMode) {
-        return applySummaryHealthProjection(result);
-    }
-    return options.brief === true ? applyBriefHealthProjection(result) : result;
+    const warningCount = result.warning_count ?? result.warnings.length;
+    const boundedResult = {
+        ...result,
+        warning_count: warningCount,
+        warning_limit: HEALTH_WARNING_LIMIT,
+        warnings_truncated: warningCount > HEALTH_WARNING_LIMIT,
+        warnings: result.warnings.slice(0, HEALTH_WARNING_LIMIT),
+        findings: (result.findings ?? []).filter((finding) => result.warnings
+            .slice(0, HEALTH_WARNING_LIMIT)
+            .includes(finding.warning) ||
+            result.failed_because.includes(finding.warning)),
+    };
+    const projected = summaryMode
+        ? applySummaryHealthProjection(boundedResult)
+        : options.brief === true
+            ? applyBriefHealthProjection(boundedResult)
+            : boundedResult;
+    return {
+        ...projected,
+        warning_count: warningCount,
+        warning_limit: HEALTH_WARNING_LIMIT,
+        warnings_truncated: warningCount > projected.warnings.length,
+        ...(projected.projection
+            ? {
+                projection: {
+                    ...projected.projection,
+                    warning_count: warningCount,
+                    warnings_truncated: warningCount > projected.warnings.length,
+                },
+            }
+            : {}),
+    };
 }
 /** Implements run health for the public runtime surface of this module. */
 export async function runHealth(global, options = {}) {
@@ -1945,23 +2037,26 @@ export async function runHealth(global, options = {}) {
         historyDriftCheck,
         vectorizationCheck,
     });
+    const remediationSources = buildHealthRemediationSources({
+        directoryState,
+        normalizedSettingsReadWarnings,
+        settingWarnings,
+        normalizedItemReadWarnings,
+        telemetryCheck,
+        extensionCheck,
+        historyPolicyWarnings: historyPolicy.warnings,
+        historySummary,
+        authorAttributionWarnings,
+        staleInProgressWarnings: staleInProgress.warnings,
+        provenanceWarnings,
+        locksCheck,
+        integrityCheck,
+        historyDriftCheck,
+        vectorizationCheck,
+    });
     attachHealthRemediationMaps({
         checks,
-        remediationSources: buildHealthRemediationSources({
-            directoryState,
-            normalizedSettingsReadWarnings,
-            settingWarnings,
-            telemetryCheck,
-            extensionCheck,
-            historySummary,
-            authorAttributionWarnings,
-            staleInProgressWarnings: staleInProgress.warnings,
-            provenanceWarnings,
-            locksCheck,
-            integrityCheck,
-            historyDriftCheck,
-            vectorizationCheck,
-        }),
+        remediationSources,
         historyDriftedCount: extractHistoryDriftedCount(historyDriftCheck),
         overThresholdCount: historySummary.over_threshold.length,
     });
@@ -1970,10 +2065,18 @@ export async function runHealth(global, options = {}) {
     // it must never flip overall project health to not-ok. Such warnings are still
     // surfaced in `warnings` and the telemetry check's own `warn` status.
     const blockingWarnings = normalizedWarnings.filter((warning) => !isAdvisoryHealthWarning(warning, options.requireMergeDrivers === true));
+    const findings = buildHealthFindings({
+        warnings: normalizedWarnings,
+        checks,
+        remediationSources,
+        requireMergeDrivers: options.requireMergeDrivers === true,
+    });
     const result = {
         ok: blockingWarnings.length === 0,
         checks,
         warnings: normalizedWarnings,
+        findings,
+        failed_because: blockingWarnings,
         generated_at: nowIso(),
     };
     return projectHealthResult(result, options, skipPolicy.summaryMode);
@@ -1981,6 +2084,7 @@ export async function runHealth(global, options = {}) {
 /** Public contract for test only health command, shared by SDK and presentation-layer consumers. */
 export const _testOnlyHealthCommand = {
     buildExtensionHealthTriageSummary,
+    buildHealthFindings,
     buildCapabilityContractMetadata,
     buildStaleInProgressHealthSummary,
     buildVectorizationProviderDetails,
@@ -2007,4 +2111,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=5cee1eaa-73f3-5709-867f-a8d73081da8b
+//# debugId=e7be701e-085c-5903-96da-61149452c673

package/dist/sdk/governance/provenance-health.d.ts

@@ -1,3 +1,4 @@
+import type { HistoryEntry } from "../../types/index.js";
 /** Aggregated resolver attempts for one harness provenance dimension. */
 export interface ProvenanceResolverHealthOutcome {
     /** Detected harness namespace. */
@@ -35,5 +36,31 @@ export interface ProvenanceResolverHealthScan {
     /** Whether an event or byte ceiling omitted history input. */
     truncated: boolean;
 }
+/** Privacy-safe receipt for an explicit provenance normalization pass. */
+export interface ProvenanceNormalizationReceipt {
+    /** Whether at least one immutable event required normalization. */
+    changed: boolean;
+    /** Immutable events whose invalid provenance observations were removed. */
+    events_changed: number;
+    /** Total invalid observations removed without retaining their values. */
+    observations_removed: number;
+    /** Aggregate invalid-value classes removed by the pass. */
+    invalid_values: ProvenanceValueHealthFinding[];
+}
+/** Normalized entries plus the privacy-safe mutation receipt. */
+export interface ProvenanceNormalizationResult {
+    /** History entries with invalid bounded observations removed. */
+    entries: HistoryEntry[];
+    /** Aggregate mutation receipt; never includes an observed value. */
+    receipt: ProvenanceNormalizationReceipt;
+}
+/**
+ * Remove only provenance observations whose values violate the bounded domain.
+ * History operations, patches, timestamps, authors, and hashes are retained;
+ * the receipt exposes aggregate classes and counts but never the removed value.
+ */
+export declare function normalizeInvalidHistoryProvenance(entries: HistoryEntry[]): ProvenanceNormalizationResult;
+/** Find every history stream requiring provenance normalization without returning raw values. */
+export declare function listInvalidProvenanceHistoryStreamIds(pmRoot: string): Promise<string[]>;
 /** Scan immutable history without failing over malformed streams owned by integrity checks. */
 export declare function scanProvenanceResolverHealth(pmRoot: string, eventLimit?: number): Promise<ProvenanceResolverHealthScan>;

package/dist/sdk/governance/provenance-health.js

@@ -4,7 +4,7 @@
  * Reads bounded, privacy-safe provenance resolver outcomes for health checks.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="60154e1b-8348-5b6b-badf-e76bba43bef8")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6efed404-acd2-5c3a-a008-856df67c8b77")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 const DEFAULT_PROVENANCE_HISTORY_BYTE_LIMIT = 8_388_608;
@@ -27,6 +27,98 @@ const INVALID_PROVENANCE_VALUE_CLASSIFIERS = [
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function invalidProvenanceValueKind(value) {
+    return INVALID_PROVENANCE_VALUE_CLASSIFIERS.find((classifier) => classifier.matches(value))?.kind;
+}
+/**
+ * Remove only provenance observations whose values violate the bounded domain.
+ * History operations, patches, timestamps, authors, and hashes are retained;
+ * the receipt exposes aggregate classes and counts but never the removed value.
+ */
+export function normalizeInvalidHistoryProvenance(entries) {
+    const invalidValues = new Map();
+    let eventsChanged = 0;
+    let observationsRemoved = 0;
+    const normalized = entries.map((entry) => {
+        const provenance = isRecord(entry.agent_provenance)
+            ? entry.agent_provenance
+            : undefined;
+        if (provenance === undefined)
+            return entry;
+        const retained = {};
+        let eventChanged = false;
+        for (const [dimension, observation] of Object.entries(provenance)) {
+            const kind = isRecord(observation)
+                ? invalidProvenanceValueKind(observation.value)
+                : undefined;
+            if (kind === undefined) {
+                retained[dimension] = observation;
+                continue;
+            }
+            eventChanged = true;
+            observationsRemoved += 1;
+            const harness = entry.agent_harness ?? "unknown";
+            const key = `${harness}\0${dimension}\0${kind}`;
+            const aggregate = invalidValues.get(key) ?? {
+                harness,
+                dimension,
+                kind,
+                count: 0,
+            };
+            aggregate.count += 1;
+            invalidValues.set(key, aggregate);
+        }
+        if (!eventChanged)
+            return entry;
+        eventsChanged += 1;
+        const next = { ...entry };
+        if (Object.keys(retained).length === 0) {
+            delete next.agent_provenance;
+        }
+        else {
+            next.agent_provenance = retained;
+        }
+        return next;
+    });
+    return {
+        entries: normalized,
+        receipt: {
+            changed: eventsChanged > 0,
+            events_changed: eventsChanged,
+            observations_removed: observationsRemoved,
+            invalid_values: [...invalidValues.values()].sort((left, right) => left.harness.localeCompare(right.harness) ||
+                left.dimension.localeCompare(right.dimension) ||
+                left.kind.localeCompare(right.kind)),
+        },
+    };
+}
+/** Find every history stream requiring provenance normalization without returning raw values. */
+export async function listInvalidProvenanceHistoryStreamIds(pmRoot) {
+    const ids = [];
+    for (const file of await listHistoryFiles(pmRoot)) {
+        try {
+            const content = await fs.readFile(path.join(pmRoot, "history", file), "utf8");
+            for (const line of content.split("\n")) {
+                if (line.trim().length === 0)
+                    continue;
+                const entry = parseHistoryEntry(line);
+                if (entry === null || !isRecord(entry.agent_provenance))
+                    continue;
+                const invalid = Object.values(entry.agent_provenance).some((observation) => isRecord(observation) &&
+                    invalidProvenanceValueKind(observation.value) !== undefined);
+                if (invalid) {
+                    ids.push(file.slice(0, -".jsonl".length));
+                    break;
+                }
+            }
+        }
+        catch {
+            // Integrity diagnostics own unreadable or malformed streams. This census
+            // only selects safely parseable streams for the explicit normalizer.
+        }
+    }
+    return ids;
+}
 async function listHistoryFiles(pmRoot) {
     try {
         return (await fs.readdir(path.join(pmRoot, "history")))
@@ -84,7 +176,7 @@ function collectResolverOutcomes(entry, aggregates, invalidValues) {
     Object.entries(provenance).forEach(([dimension, observation]) => {
         if (!isRecord(observation))
             return;
-        const kind = INVALID_PROVENANCE_VALUE_CLASSIFIERS.find((classifier) => classifier.matches(observation.value))?.kind;
+        const kind = invalidProvenanceValueKind(observation.value);
         if (!kind)
             return;
         const key = `${harness}\0${dimension}\0${kind}`;
@@ -182,4 +274,4 @@ export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000)
     };
 }
 //# sourceMappingURL=provenance-health.js.map
-//# debugId=60154e1b-8348-5b6b-badf-e76bba43bef8
+//# debugId=6efed404-acd2-5c3a-a008-856df67c8b77

package/dist/sdk/governance/validate-history-drift.d.ts

@@ -0,0 +1,7 @@
+import type { ValidateCheck } from "./validate.js";
+import type { ValidateItem } from "./validate-item-reader.js";
+/** Build the validation warning and bounded evidence projection for history drift. */
+export declare function buildValidateHistoryDriftCheck(pmRoot: string, items: ValidateItem[], verboseDiagnostics: boolean): Promise<{
+    check: ValidateCheck;
+    warnings: string[];
+}>;