@unbrained/pm-cli 2026.8.14 → 2026.8.15

package/dist/sdk/governance/assurance.js

@@ -7,7 +7,7 @@
  * one deterministic SDK path.
  */
 
-!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]="07889857-2176-5659-96f7-8f5591f4c692")}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]="2bf52d6d-7e4f-5ec5-86bd-3e817ef521bb")}catch(e){}}();
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -15,7 +15,7 @@ import { PmCliError } from "../../core/shared/errors.js";
 import { appendWorkspaceAuditEvent, mutateWorkspaceJsonWithHistory, readFileIfExists, readHistoryEntries, readSettings, resolveAuthor, stableStringify, WORKSPACE_HISTORY_ID, getWorkspaceHistoryPath, } from "../runtime-primitives.js";
 import { resolveCanonicalRelationshipKind } from "../relationships.js";
 import { MAX_ASSURANCE_VERDICT_LIMIT } from "./assurance-limits.js";
-import { AssuranceEvaluationRefusalError, AssuranceMutationRefusalError, } from "./assurance-mutation-error.js";
+import { AssuranceEvaluationRefusalError, AssuranceMutationRefusalError, AssuranceSourceResolutionError, } from "./assurance-mutation-error.js";
 /** Current serialized assurance registry format. */
 export const ASSURANCE_DOCUMENT_VERSION = 1;
 /** Supported lifecycle points that can evaluate a gate. */
@@ -30,6 +30,18 @@ export const ASSURANCE_GATE_TRIGGERS = [
     "on-claim",
     "on-close",
 ];
+/** Supported discriminants for built-in, delegated, and derived measurements. */
+export const ASSURANCE_MEASUREMENT_SOURCE_KINDS = [
+    "items",
+    "dependency_kind",
+    "graph",
+    "validate",
+    "health",
+    "history",
+    "links",
+    "provider",
+    "derived",
+];
 const POLARITY_KEYS = [
     "ceiling",
     "floor",
@@ -161,7 +173,15 @@ export function validateMeasurementDefinition(definition) {
     if (definition.max_cost !== undefined) {
         requireFiniteNonNegative(definition.max_cost, "measurement.max_cost");
     }
-    const source = definition.source;
+    const candidateSource = definition.source;
+    if (Object.prototype.toString.call(candidateSource) !== "[object Object]") {
+        throw new AssuranceMutationRefusalError(`measurement.source.kind must be one of ${ASSURANCE_MEASUREMENT_SOURCE_KINDS.join(", ")}`);
+    }
+    const sourceKind = Reflect.get(candidateSource, "kind");
+    if (!ASSURANCE_MEASUREMENT_SOURCE_KINDS.includes(sourceKind)) {
+        throw new AssuranceMutationRefusalError(`measurement.source.kind must be one of ${ASSURANCE_MEASUREMENT_SOURCE_KINDS.join(", ")}`);
+    }
+    const source = candidateSource;
     if (source.kind === "items") {
         validateItemsMeasurementSource(source);
     }
@@ -240,14 +260,25 @@ function validateGateProviderPolicy(policy) {
 /** Validate and return one gate declaration. */
 export function validateGateDefinition(definition) {
     requireStableId(definition.id, "gate.id");
+    if (!Array.isArray(definition.assertion_ids)) {
+        throw new AssuranceMutationRefusalError("gate.assertion_ids is required and must be an array");
+    }
     if (definition.assertion_ids.length === 0) {
         throw new AssuranceMutationRefusalError("gate requires at least one assertion");
     }
     for (const id of definition.assertion_ids)
         requireStableId(id, "gate.assertion_id");
+    if (!Array.isArray(definition.triggers)) {
+        throw new AssuranceMutationRefusalError(`gate.triggers is required and must be an array of ${ASSURANCE_GATE_TRIGGERS.join(", ")}`);
+    }
     if (definition.triggers.length === 0) {
         throw new AssuranceMutationRefusalError("gate requires at least one trigger");
     }
+    for (const trigger of definition.triggers) {
+        if (!ASSURANCE_GATE_TRIGGERS.includes(trigger)) {
+            throw new AssuranceMutationRefusalError(`gate trigger must be one of ${ASSURANCE_GATE_TRIGGERS.join(", ")}`);
+        }
+    }
     if (definition.provider_policy) {
         validateGateProviderPolicy(definition.provider_policy);
     }
@@ -543,16 +574,10 @@ async function evaluateMeasurementInternal(definition, context, definitions, sta
         if (builtin !== null) {
             result = builtin;
         }
-        else if (definition.source.kind === "graph" ||
-            definition.source.kind === "validate" ||
-            definition.source.kind === "health" ||
-            definition.source.kind === "provider") {
+        else {
             result = await context.external(definition.source);
             providerCalls = 1;
         }
-        else {
-            throw new TypeError(`unsupported assurance source ${definition.source.kind}`);
-        }
     }
     const ownCost = {
         units: result.cost,
@@ -587,7 +612,21 @@ function evaluateMeasurementCached(definition, context, definitions, stack, stat
     const cached = state.cache.get(definition.id);
     if (cached)
         return cached;
-    const evaluation = evaluateMeasurementInternal(definition, context, definitions, stack, state);
+    const evaluation = evaluateMeasurementInternal(definition, context, definitions, stack, state).catch((error) => {
+        if (error instanceof AssuranceSourceResolutionError &&
+            error.measurement_id === undefined) {
+            const sourceContext = {
+                measurement_id: definition.id,
+                source_kind: error.source_kind,
+                field: error.field,
+                ...(error.check ? { check: error.check } : {}),
+            };
+            const sourceError = new AssuranceSourceResolutionError(error.message, sourceContext);
+            sourceError.cause = error;
+            throw sourceError;
+        }
+        throw error;
+    });
     state.cache.set(definition.id, evaluation);
     return evaluation;
 }
@@ -664,6 +703,28 @@ function enforceGateProviderPolicy(gate, document, context, trigger) {
         }
     }
 }
+async function evaluateGateMeasurement(gateId, assertionId, definition, context, definitions) {
+    try {
+        return await evaluateMeasurement(definition, context, definitions);
+    }
+    catch (error) {
+        if (error instanceof AssuranceSourceResolutionError) {
+            const checkLocation = error.check ? ` check ${error.check}` : "";
+            const measurementId = error.measurement_id ?? definition.id;
+            const refusal = new AssuranceEvaluationRefusalError(`assurance gate ${gateId} assertion ${assertionId} measurement ${measurementId} source ${error.source_kind}${checkLocation} field ${error.field} could not resolve: ${error.message}`, {
+                gate_id: gateId,
+                assertion_id: assertionId,
+                measurement_id: measurementId,
+                source_kind: error.source_kind,
+                field: error.field,
+                ...(error.check ? { check: error.check } : {}),
+            });
+            refusal.cause = error;
+            throw refusal;
+        }
+        throw error;
+    }
+}
 /** Evaluate a named gate into one presentation-independent verdict document. */
 export async function evaluateAssuranceGate(gateId, document, context, options) {
     validateAssuranceDocument(document);
@@ -688,7 +749,7 @@ export async function evaluateAssuranceGate(gateId, document, context, options)
         else if (assertionDefinition.scope.kind === "filter") {
             const scopeMeasurementId = assertionDefinition.scope.measurement_id;
             const scopeDefinition = document.measurements.find((entry) => entry.id === scopeMeasurementId);
-            const scope = await evaluateMeasurement(scopeDefinition, context, document.measurements);
+            const scope = await evaluateGateMeasurement(gateDefinition.id, assertionDefinition.id, scopeDefinition, context, document.measurements);
             const contributorIds = new Set(scope.contributors);
             scopedContext = {
                 ...context,
@@ -698,7 +759,7 @@ export async function evaluateAssuranceGate(gateId, document, context, options)
         const owner = context.items.find((item) => item.id === assertionDefinition.owner_item_id);
         const ownerTerminal = owner !== undefined &&
             new Set(context.terminal_statuses ?? ["closed", "canceled"]).has(owner.status);
-        return evaluateAssuranceAssertion(assertionDefinition, await evaluateMeasurement(measurementDefinition, scopedContext, document.measurements), { owner_terminal: ownerTerminal });
+        return evaluateAssuranceAssertion(assertionDefinition, await evaluateGateMeasurement(gateDefinition.id, assertionDefinition.id, measurementDefinition, scopedContext, document.measurements), { owner_terminal: ownerTerminal });
     });
     const blocking = assertions.some((entry) => entry.verdict === "fail" && entry.enforcement === "block");
     const warning = assertions.some((entry) => entry.verdict === "fail" && entry.enforcement === "warn");
@@ -711,6 +772,11 @@ export async function evaluateAssuranceGate(gateId, document, context, options)
         verdict: blocking ? "block" : warning ? "warn" : "pass",
         exit_code: blocking ? 1 : 0,
         assertions,
+        assertions_total: assertions.length,
+        row_contract: {
+            row_keys: ["assertions"],
+            jq_selector: ".assertions[]",
+        },
         cost: sumCosts(assertions.map((entry) => entry.cost), Math.max(0, ...assertions.map((entry) => entry.cost.duration_ms))),
     };
 }
@@ -940,4 +1006,4 @@ export async function listAssuranceVerdicts(pmRoot, options = {}) {
         .slice(0, limit);
 }
 //# sourceMappingURL=assurance.js.map
-//# debugId=07889857-2176-5659-96f7-8f5591f4c692
+//# debugId=2bf52d6d-7e4f-5ec5-86bd-3e817ef521bb

package/dist/sdk/governance/extension-host-version.d.ts

@@ -0,0 +1,25 @@
+import type { LoadedExtension } from "../../core/extensions/loader.js";
+/** One distinct resolvable pm-cli installation and its extension consumers. */
+export interface ExtensionHostVersionCopy {
+    /** Installed pm-cli version. */
+    version: string;
+    /** Privacy-safe workspace-relative package manifest location. */
+    path: string;
+    /** Dependency layout that exposed this copy. */
+    layout: "host" | "npm" | "pnpm" | "other";
+    /** Loaded extensions resolving this copy. */
+    consumers: string[];
+}
+/** Extension/host version census returned by the health SDK. */
+export interface ExtensionHostVersionCensus {
+    /** Version of the process-hosting pm-cli package. */
+    host_version: string | null;
+    /** Every distinct relevant copy resolved by the host or an extension. */
+    copies: ExtensionHostVersionCopy[];
+    /** Copies whose version differs from the process host. */
+    mismatches: ExtensionHostVersionCopy[];
+    /** Stable health warning tokens for mismatched copies. */
+    warnings: string[];
+}
+/** Scan the host plus the nearest pm-cli package resolvable by every loaded extension. */
+export declare function scanExtensionHostVersions(loadedExtensions: readonly LoadedExtension[], workspaceRoot: string, hostPackageRoot?: string): Promise<ExtensionHostVersionCensus>;

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]="97fd3651-47de-5505-be2b-bc466313e91f")}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) => {
@@ -961,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,
@@ -990,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,
@@ -1819,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)) {
@@ -1862,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 = {}) {
@@ -1957,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,
     });
@@ -1982,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);
@@ -1993,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,
@@ -2019,4 +2111,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=97fd3651-47de-5505-be2b-bc466313e91f
+//# debugId=e7be701e-085c-5903-96da-61149452c673