@unbrained/pm-cli 2026.7.1 → 2026.7.3

package/dist/cli/commands/health.js

@@ -4,7 +4,7 @@
  * 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]="7b0dc685-2469-5d2e-98c8-07eebf79ee3e")}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]="d078e1a2-2f92-566c-8ecd-542b2730a9b6")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -150,6 +150,9 @@ async function listItemDocumentPaths(pmRoot, typeToFolder) {
     itemPaths.sort((left, right) => normalizeRelativePath(pmRoot, left).localeCompare(normalizeRelativePath(pmRoot, right)));
     return itemPaths;
 }
+function shouldReportHistoryDirectoryUnreadable(error) {
+    return !(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT");
+}
 async function buildIntegrityCheck(pmRoot, typeToFolder, schema) {
     const itemPaths = await listItemDocumentPaths(pmRoot, typeToFolder);
     const itemUnreadable = [];
@@ -195,7 +198,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema) {
     }
     catch (error) {
         /* c8 ignore start -- ENOENT/non-ENOENT differentiation requires filesystem fault injection */
-        if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")) {
+        if (shouldReportHistoryDirectoryUnreadable(error)) {
             historyUnreadable.push("history");
         }
         /* c8 ignore stop */
@@ -636,49 +639,50 @@ function summarizeStringList(value, limit) {
         truncated: strings.length > limit,
     };
 }
-/* c8 ignore start -- brief/summary projection matrix branches are validated in projection integration tests */
-function summarizeHealthCheckDetails(check, limit) {
-    const details = check.details;
-    if (check.name === "settings") {
-        return {
-            version: details.version,
-            id_prefix: details.id_prefix,
-            locks_ttl_seconds: details.locks_ttl_seconds,
-            warnings: summarizeStringList(details.warnings, limit),
-        };
-    }
-    if (check.name === "directories") {
-        return {
-            required_count: Array.isArray(details.required) ? details.required.length : 0,
-            optional_count: Array.isArray(details.optional) ? details.optional.length : 0,
-            missing_required: summarizeStringList(details.missing_required, limit),
-            missing_optional: summarizeStringList(details.missing_optional, limit),
-            missing: summarizeStringList(details.missing, limit),
-            strict_directories: details.strict_directories,
-        };
+function summarizeActivationMigrationStatus(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
     }
-    if (check.name === "settings_values") {
-        return {
-            warnings: summarizeStringList(details.warnings, limit),
-        };
-    }
-    if (check.name === "telemetry") {
-        return {
-            enabled: details.enabled,
-            capture_level: details.capture_level,
-            endpoint: details.endpoint,
-            queue_exists: details.queue_exists,
-            queue_entries: details.queue_entries,
-            queue_draining: details.queue_draining,
-            queue_invalid_rows: details.queue_invalid_rows,
-            queue_rows_total: details.queue_rows_total,
-            last_successful_flush_at: details.last_successful_flush_at,
-            last_failed_flush_at: details.last_failed_flush_at,
-            endpoint_probe: details.endpoint_probe,
-            env_overrides: details.env_overrides,
-        };
-    }
-    if (check.name === "extensions") {
+    const status = value;
+    return {
+        applied_count: status.applied_count,
+        pending_count: status.pending_count,
+        failed_count: status.failed_count,
+    };
+}
+const HEALTH_DETAIL_SUMMARIZERS = {
+    settings: (details, limit) => ({
+        version: details.version,
+        id_prefix: details.id_prefix,
+        locks_ttl_seconds: details.locks_ttl_seconds,
+        warnings: summarizeStringList(details.warnings, limit),
+    }),
+    directories: (details, limit) => ({
+        required_count: Array.isArray(details.required) ? details.required.length : 0,
+        optional_count: Array.isArray(details.optional) ? details.optional.length : 0,
+        missing_required: summarizeStringList(details.missing_required, limit),
+        missing_optional: summarizeStringList(details.missing_optional, limit),
+        missing: summarizeStringList(details.missing, limit),
+        strict_directories: details.strict_directories,
+    }),
+    settings_values: (details, limit) => ({
+        warnings: summarizeStringList(details.warnings, limit),
+    }),
+    telemetry: (details) => ({
+        enabled: details.enabled,
+        capture_level: details.capture_level,
+        endpoint: details.endpoint,
+        queue_exists: details.queue_exists,
+        queue_entries: details.queue_entries,
+        queue_draining: details.queue_draining,
+        queue_invalid_rows: details.queue_invalid_rows,
+        queue_rows_total: details.queue_rows_total,
+        last_successful_flush_at: details.last_successful_flush_at,
+        last_failed_flush_at: details.last_failed_flush_at,
+        endpoint_probe: details.endpoint_probe,
+        env_overrides: details.env_overrides,
+    }),
+    extensions: (details, limit) => {
         const activation = typeof details.activation === "object" && details.activation !== null ? details.activation : {};
         return {
             disabled_by_flag: details.disabled_by_flag,
@@ -695,79 +699,67 @@ function summarizeHealthCheckDetails(check, limit) {
                 service_override_count: activation.service_override_count,
                 renderer_override_count: activation.renderer_override_count,
                 registration_counts: activation.registration_counts,
-                migration_status: typeof activation.migration_status === "object" && activation.migration_status !== null
-                    ? {
-                        applied_count: activation.migration_status.applied_count,
-                        pending_count: activation.migration_status.pending_count,
-                        failed_count: activation.migration_status.failed_count,
-                    }
-                    : null,
+                migration_status: summarizeActivationMigrationStatus(activation.migration_status),
             },
             triage: details.triage,
             capability_contract: details.capability_contract,
             capability_guidance: summarizeRecordList(details.capability_guidance, limit),
         };
-    }
-    if (check.name === "storage") {
-        return details;
-    }
-    if (check.name === "locks") {
-        // Counts only: drops remediation_map, which is full-output-only by contract.
-        return {
-            active_lock_count: details.active_lock_count,
-            stale_lock_count: details.stale_lock_count,
-            unreadable_lock_count: details.unreadable_lock_count,
-            unparseable_lock_count: details.unparseable_lock_count,
-        };
-    }
-    if (check.name === "integrity") {
-        return {
-            checked_item_files: details.checked_item_files,
-            checked_history_streams: details.checked_history_streams,
-            counts: details.counts,
-            item_unreadable: summarizeStringList(details.item_unreadable, limit),
-            item_conflict_markers: summarizeRecordList(details.item_conflict_markers, limit),
-            item_parse_failures: summarizeStringList(details.item_parse_failures, limit),
-            history_unreadable: summarizeStringList(details.history_unreadable, limit),
-            history_conflict_markers: summarizeRecordList(details.history_conflict_markers, limit),
-            history_invalid_json: summarizeRecordList(details.history_invalid_json, limit),
-            skipped: details.skipped,
-        };
-    }
-    if (check.name === "history_drift") {
-        return {
-            checked_items: details.checked_items,
-            counts: details.counts,
-            drifted_items: summarizeStringList(details.drifted_items, limit),
-            missing_streams: summarizeStringList(details.missing_streams, limit),
-            unreadable_streams: summarizeStringList(details.unreadable_streams, limit),
-            hash_mismatches: summarizeStringList(details.hash_mismatches, limit),
-            chain_mismatches: summarizeStringList(details.chain_mismatches, limit),
-            skipped: details.skipped,
-        };
-    }
-    if (check.name === "vectorization") {
-        return {
-            semantic_runtime_available: details.semantic_runtime_available,
-            compatibility_mode_auto_defaults: details.compatibility_mode_auto_defaults,
-            auto_ollama_defaults_applied: details.auto_ollama_defaults_applied,
-            refresh_policy: details.refresh_policy,
-            provider_active: details.provider_active,
-            vector_store_active: details.vector_store_active,
-            items: details.items,
-            ledger_entries_before: details.ledger_entries_before,
-            stale_items_before_total: details.stale_items_before_total,
-            stale_items_before: summarizeStringList(details.stale_items_before, limit),
-            refresh_attempted: details.refresh_attempted,
-            refresh_skipped_reason: details.refresh_skipped_reason,
-            refresh_result: details.refresh_result,
-            ledger_entries_after: details.ledger_entries_after,
-            stale_items_after_total: details.stale_items_after_total,
-            stale_items_after: summarizeStringList(details.stale_items_after, limit),
-            skipped: details.skipped,
-        };
-    }
-    return details;
+    },
+    // Storage details are already compact counters; keep the pre-refactor pass-through shape.
+    storage: (details) => details,
+    locks: (details) => ({
+        active_lock_count: details.active_lock_count,
+        stale_lock_count: details.stale_lock_count,
+        unreadable_lock_count: details.unreadable_lock_count,
+        unparseable_lock_count: details.unparseable_lock_count,
+    }),
+    integrity: (details, limit) => ({
+        checked_item_files: details.checked_item_files,
+        checked_history_streams: details.checked_history_streams,
+        counts: details.counts,
+        item_unreadable: summarizeStringList(details.item_unreadable, limit),
+        item_conflict_markers: summarizeRecordList(details.item_conflict_markers, limit),
+        item_parse_failures: summarizeStringList(details.item_parse_failures, limit),
+        history_unreadable: summarizeStringList(details.history_unreadable, limit),
+        history_conflict_markers: summarizeRecordList(details.history_conflict_markers, limit),
+        history_invalid_json: summarizeRecordList(details.history_invalid_json, limit),
+        skipped: details.skipped,
+    }),
+    history_drift: (details, limit) => ({
+        checked_items: details.checked_items,
+        counts: details.counts,
+        drifted_items: summarizeStringList(details.drifted_items, limit),
+        missing_streams: summarizeStringList(details.missing_streams, limit),
+        unreadable_streams: summarizeStringList(details.unreadable_streams, limit),
+        hash_mismatches: summarizeStringList(details.hash_mismatches, limit),
+        chain_mismatches: summarizeStringList(details.chain_mismatches, limit),
+        skipped: details.skipped,
+    }),
+    vectorization: (details, limit) => ({
+        semantic_runtime_available: details.semantic_runtime_available,
+        compatibility_mode_auto_defaults: details.compatibility_mode_auto_defaults,
+        auto_ollama_defaults_applied: details.auto_ollama_defaults_applied,
+        refresh_policy: details.refresh_policy,
+        provider_active: details.provider_active,
+        vector_store_active: details.vector_store_active,
+        items: details.items,
+        ledger_entries_before: details.ledger_entries_before,
+        stale_items_before_total: details.stale_items_before_total,
+        stale_items_before: summarizeStringList(details.stale_items_before, limit),
+        refresh_attempted: details.refresh_attempted,
+        refresh_skipped_reason: details.refresh_skipped_reason,
+        refresh_result: details.refresh_result,
+        ledger_entries_after: details.ledger_entries_after,
+        stale_items_after_total: details.stale_items_after_total,
+        stale_items_after: summarizeStringList(details.stale_items_after, limit),
+        skipped: details.skipped,
+    }),
+};
+/* c8 ignore start -- brief/summary projection matrix branches are validated in projection integration tests */
+function summarizeHealthCheckDetails(check, limit) {
+    const summarize = HEALTH_DETAIL_SUMMARIZERS[check.name];
+    return summarize ? summarize(check.details, limit) : check.details;
 }
 /* c8 ignore stop */
 function applyBriefHealthProjection(result) {
@@ -903,6 +895,101 @@ function parseTelemetryQueue(raw) {
         maxAttempts,
     };
 }
+function emptyTelemetryQueueSummary() {
+    return { validEntries: 0, invalidRows: 0, totalRows: 0, highRetryEntries: 0, maxAttempts: 0 };
+}
+/* c8 ignore start -- telemetry state corruption and otel-failure branches require runtime-coordinated fixture mutation */
+function parseTelemetryRuntimeState(stateRaw) {
+    if (!stateRaw || stateRaw.trim().length === 0) {
+        return { runtimeState: {}, stateParseFailed: false };
+    }
+    try {
+        const parsed = JSON.parse(stateRaw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return { runtimeState: parsed, stateParseFailed: false };
+        }
+        return { runtimeState: {}, stateParseFailed: true };
+    }
+    catch {
+        return { runtimeState: {}, stateParseFailed: true };
+    }
+}
+async function maybeProbeTelemetryEndpoint(settings, checkTelemetry) {
+    const endpoint = settings.telemetry.endpoint.trim();
+    if (!checkTelemetry || !settings.telemetry.enabled || endpoint.length === 0) {
+        return undefined;
+    }
+    const probe = await probeTelemetryEndpointHealth(endpoint);
+    return {
+        attempted: true,
+        ...probe,
+    };
+}
+function collectTelemetryQueueWarnings(settings, queueSummary, runtimeState) {
+    const warnings = [];
+    if (queueSummary.invalidRows > 0) {
+        warnings.push(`telemetry_queue_invalid_rows:${queueSummary.invalidRows}`);
+    }
+    if (!settings.telemetry.enabled || queueSummary.validEntries === 0) {
+        return warnings;
+    }
+    const lastSuccess = runtimeState.last_successful_flush_at;
+    const lastFailure = runtimeState.last_failed_flush_at;
+    const activeFailure = lastFailure && (!lastSuccess || lastFailure > lastSuccess);
+    const neverFlushed = !lastSuccess;
+    const highWater = queueSummary.validEntries >= TELEMETRY_QUEUE_HIGH_WATER_MARK;
+    if (activeFailure || neverFlushed || highWater) {
+        warnings.push(`telemetry_queue_pending:${queueSummary.validEntries}`);
+    }
+    if (queueSummary.highRetryEntries > 0) {
+        warnings.push(`telemetry_queue_high_retries:${queueSummary.highRetryEntries}`);
+    }
+    return warnings;
+}
+function collectTelemetryEndpointWarnings(endpointProbe) {
+    if (!endpointProbe || endpointProbe.ok !== false) {
+        return [];
+    }
+    return typeof endpointProbe.status === "number"
+        ? [`telemetry_endpoint_probe_http_status:${endpointProbe.status}`]
+        : ["telemetry_endpoint_probe_failed"];
+}
+function collectTelemetrySchemaWarnings(endpointProbe) {
+    const parsedMaxSchemaVersion = Number.parseInt(endpointProbe?.max_schema_version ?? "", 10);
+    if (endpointProbe?.ok === true && Number.isInteger(parsedMaxSchemaVersion) && parsedMaxSchemaVersion > TELEMETRY_SCHEMA_VERSION) {
+        return [`telemetry_schema_version_behind:${parsedMaxSchemaVersion}`];
+    }
+    return [];
+}
+function collectTelemetryOtelWarnings(settings, runtimeState) {
+    const pendingOtelSpans = typeof runtimeState.pending_otel_spans === "number" ? runtimeState.pending_otel_spans : 0;
+    const lastOtelSuccess = runtimeState.last_otel_success_at;
+    const lastOtelFailure = runtimeState.last_otel_failure_at;
+    const otelExportFailing = settings.telemetry.enabled &&
+        pendingOtelSpans > 0 &&
+        Boolean(lastOtelFailure) &&
+        // >= so a mixed-outcome batch (success + failure share the same attempt
+        // timestamp) still surfaces the warning rather than being masked by the tie.
+        (!lastOtelSuccess || lastOtelFailure >= lastOtelSuccess);
+    return otelExportFailing ? [`telemetry_otel_export_failing:${pendingOtelSpans}`] : [];
+}
+function buildTelemetryEnvOverrideDetails() {
+    return {
+        telemetry_disabled: telemetryEnvFlagEnabled("PM_TELEMETRY_DISABLED") || telemetryEnvFlagEnabled("PM_NO_TELEMETRY"),
+        pm_no_telemetry: telemetryEnvFlagEnabled("PM_NO_TELEMETRY"),
+        telemetry_otel_disabled: telemetryEnvFlagEnabled("PM_TELEMETRY_OTEL_DISABLED"),
+        telemetry_inline_flush: telemetryEnvFlagEnabled("PM_TELEMETRY_INLINE_FLUSH"),
+        telemetry_source_context: telemetrySourceContextOverride(),
+    };
+}
+/* c8 ignore stop */
+function telemetryQueueHasEntries(settings, queueSummary) {
+    return settings.telemetry.enabled && queueSummary.validEntries > 0;
+}
+function isTelemetryQueueDraining(queueHasEntries, warnings) {
+    return (queueHasEntries &&
+        warnings.every((warning) => !warning.startsWith("telemetry_queue_pending:") && !warning.startsWith("telemetry_queue_high_retries:")));
+}
 async function probeTelemetryEndpointHealth(endpoint) {
     let probeUrl = endpoint;
     try {
@@ -951,88 +1038,19 @@ async function buildTelemetryCheck(settings, options) {
     const queueRaw = await readFileIfExists(queuePath);
     const queueExists = queueRaw !== null;
     const queueSizeBytes = queueRaw ? Buffer.byteLength(queueRaw, "utf8") : 0;
-    const queueSummary = queueRaw
-        ? parseTelemetryQueue(queueRaw)
-        : { validEntries: 0, invalidRows: 0, totalRows: 0, highRetryEntries: 0, maxAttempts: 0 };
+    const queueSummary = queueRaw ? parseTelemetryQueue(queueRaw) : emptyTelemetryQueueSummary();
     const stateRaw = await readFileIfExists(statePath);
-    let runtimeState = {};
-    let stateParseFailed = false;
-    /* c8 ignore start -- telemetry state corruption and otel-failure branches require runtime-coordinated fixture mutation */
-    if (stateRaw && stateRaw.trim().length > 0) {
-        try {
-            const parsed = JSON.parse(stateRaw);
-            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-                runtimeState = parsed;
-            }
-            else {
-                /* c8 ignore next -- malformed runtime-state payloads are integration-only corruption cases */
-                stateParseFailed = true;
-            }
-        }
-        catch {
-            stateParseFailed = true;
-        }
-    }
+    const { runtimeState, stateParseFailed } = parseTelemetryRuntimeState(stateRaw);
     const endpoint = settings.telemetry.endpoint.trim();
     const endpointDisplay = normalizeEndpointForDisplay(endpoint);
-    let endpointProbe;
-    if (options.checkTelemetry && settings.telemetry.enabled && endpoint.length > 0) {
-        const probe = await probeTelemetryEndpointHealth(endpoint);
-        endpointProbe = {
-            attempted: true,
-            ...probe,
-        };
-    }
+    const endpointProbe = await maybeProbeTelemetryEndpoint(settings, options.checkTelemetry);
     const warnings = [];
     if (stateParseFailed) {
         warnings.push("telemetry_state_invalid_json");
     }
-    if (queueSummary.invalidRows > 0) {
-        warnings.push(`telemetry_queue_invalid_rows:${queueSummary.invalidRows}`);
-    }
-    const queueHasEntries = settings.telemetry.enabled && queueSummary.validEntries > 0;
-    if (queueHasEntries) {
-        const lastSuccess = runtimeState.last_successful_flush_at;
-        const lastFailure = runtimeState.last_failed_flush_at;
-        const activeFailure = lastFailure && (!lastSuccess || lastFailure > lastSuccess);
-        const neverFlushed = !lastSuccess;
-        const highWater = queueSummary.validEntries >= TELEMETRY_QUEUE_HIGH_WATER_MARK;
-        const highRetries = queueSummary.highRetryEntries > 0;
-        if (activeFailure || neverFlushed || highWater) {
-            warnings.push(`telemetry_queue_pending:${queueSummary.validEntries}`);
-        }
-        if (highRetries) {
-            warnings.push(`telemetry_queue_high_retries:${queueSummary.highRetryEntries}`);
-        }
-    }
-    if (endpointProbe && !endpointProbe.ok) {
-        if (typeof endpointProbe.status === "number") {
-            warnings.push(`telemetry_endpoint_probe_http_status:${endpointProbe.status}`);
-        }
-        else {
-            warnings.push("telemetry_endpoint_probe_failed");
-        }
-    }
-    const parsedMaxSchemaVersion = Number.parseInt(endpointProbe?.max_schema_version ?? "", 10);
-    if (endpointProbe &&
-        endpointProbe.ok &&
-        Number.isInteger(parsedMaxSchemaVersion) &&
-        parsedMaxSchemaVersion > TELEMETRY_SCHEMA_VERSION) {
-        warnings.push(`telemetry_schema_version_behind:${parsedMaxSchemaVersion}`);
-    }
+    warnings.push(...collectTelemetryQueueWarnings(settings, queueSummary, runtimeState), ...collectTelemetryEndpointWarnings(endpointProbe), ...collectTelemetrySchemaWarnings(endpointProbe), ...collectTelemetryOtelWarnings(settings, runtimeState));
+    const queueHasEntries = telemetryQueueHasEntries(settings, queueSummary);
     const pendingOtelSpans = typeof runtimeState.pending_otel_spans === "number" ? runtimeState.pending_otel_spans : 0;
-    const lastOtelSuccess = runtimeState.last_otel_success_at;
-    const lastOtelFailure = runtimeState.last_otel_failure_at;
-    const otelExportFailing = settings.telemetry.enabled &&
-        pendingOtelSpans > 0 &&
-        Boolean(lastOtelFailure) &&
-        // >= so a mixed-outcome batch (success + failure share the same attempt
-        // timestamp) still surfaces the warning rather than being masked by the tie.
-        (!lastOtelSuccess || lastOtelFailure >= lastOtelSuccess);
-    if (otelExportFailing) {
-        warnings.push(`telemetry_otel_export_failing:${pendingOtelSpans}`);
-    }
-    /* c8 ignore stop */
     return {
         check: {
             name: "telemetry",
@@ -1045,8 +1063,7 @@ async function buildTelemetryCheck(settings, options) {
                 queue_path: queuePath,
                 queue_exists: queueExists,
                 queue_entries: queueSummary.validEntries,
-                queue_draining: queueHasEntries &&
-                    warnings.every((warning) => !warning.startsWith("telemetry_queue_pending:") && !warning.startsWith("telemetry_queue_high_retries:")),
+                queue_draining: isTelemetryQueueDraining(queueHasEntries, warnings),
                 queue_invalid_rows: queueSummary.invalidRows,
                 queue_rows_total: queueSummary.totalRows,
                 queue_size_bytes: queueSizeBytes,
@@ -1063,18 +1080,8 @@ async function buildTelemetryCheck(settings, options) {
                 last_otel_success_at: runtimeState.last_otel_success_at ?? null,
                 last_otel_failure_at: runtimeState.last_otel_failure_at ?? null,
                 last_otel_failure_error: runtimeState.last_otel_failure_error ?? null,
-                endpoint_probe: endpointProbe ?? {
-                    attempted: false,
-                },
-                /* c8 ignore start -- env-override combinations are validated through runtime integration suites */
-                env_overrides: {
-                    telemetry_disabled: telemetryEnvFlagEnabled("PM_TELEMETRY_DISABLED") || telemetryEnvFlagEnabled("PM_NO_TELEMETRY"),
-                    pm_no_telemetry: telemetryEnvFlagEnabled("PM_NO_TELEMETRY"),
-                    telemetry_otel_disabled: telemetryEnvFlagEnabled("PM_TELEMETRY_OTEL_DISABLED"),
-                    telemetry_inline_flush: telemetryEnvFlagEnabled("PM_TELEMETRY_INLINE_FLUSH"),
-                    telemetry_source_context: telemetrySourceContextOverride(),
-                },
-                /* c8 ignore stop */
+                endpoint_probe: endpointProbe ?? { attempted: false },
+                env_overrides: buildTelemetryEnvOverrideDetails(),
             },
         },
         warnings,
@@ -1165,78 +1172,136 @@ async function buildHistoryDriftCheck(pmRoot, items) {
         warnings,
     };
 }
-async function buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, verboseStaleItems) {
+function buildVectorizationRuntimeSnapshot(settings) {
     const runtimeDefaults = resolveSettingsWithSemanticRuntimeDefaults(settings);
     const providerResolution = resolveEmbeddingProviders(runtimeDefaults.settings);
     const vectorStoreResolution = resolveVectorStores(runtimeDefaults.settings);
     const runtimeEmbeddingIdentity = providerResolution.active
         ? buildVectorizationEmbeddingIdentity(providerResolution.active.name, providerResolution.active.model)
         : null;
-    const semanticRuntimeAvailable = Boolean(providerResolution.active && vectorStoreResolution.active);
-    const ledgerBefore = await readVectorizationStatusLedger(pmRoot);
-    const staleBefore = semanticRuntimeAvailable ? collectStaleVectorizationIds(items, ledgerBefore.entries) : [];
-    let refreshResult = {
+    return {
+        runtimeDefaults,
+        providerResolution,
+        vectorStoreResolution,
+        runtimeEmbeddingIdentity,
+        semanticRuntimeAvailable: Boolean(providerResolution.active && vectorStoreResolution.active),
+    };
+}
+function emptyVectorizationRefreshResult() {
+    return {
         refreshed: [],
         skipped: [],
         warnings: [],
     };
-    if (refreshPolicy.enabled && semanticRuntimeAvailable && staleBefore.length > 0) {
-        refreshResult = await refreshSemanticEmbeddingsForMutatedItems(pmRoot, staleBefore, {
-            settings: runtimeDefaults.settings,
-            apply_runtime_defaults: false,
-        });
+}
+async function refreshStaleVectorizationItems(params) {
+    if (!params.refreshPolicy.enabled || !params.snapshot.semanticRuntimeAvailable || params.staleBefore.length === 0) {
+        return emptyVectorizationRefreshResult();
     }
-    const ledgerAfter = await readVectorizationStatusLedger(pmRoot);
-    const staleAfter = semanticRuntimeAvailable ? collectStaleVectorizationIds(items, ledgerAfter.entries) : [];
-    const strictVectorizationWarnings = !runtimeDefaults.auto_ollama_defaults_applied;
-    const embeddingIdentityChanged = strictVectorizationWarnings &&
-        semanticRuntimeAvailable &&
-        Boolean(ledgerBefore.embedding &&
-            runtimeEmbeddingIdentity &&
-            hasVectorizationEmbeddingIdentityChanged(ledgerBefore.embedding, runtimeEmbeddingIdentity));
-    /* c8 ignore start -- strict-vectorization warning synthesis branches are integration-only policy permutations */
-    const warningSet = new Set([...ledgerBefore.warnings, ...ledgerAfter.warnings]);
-    if (strictVectorizationWarnings) {
-        for (const warning of refreshResult.warnings) {
+    return refreshSemanticEmbeddingsForMutatedItems(params.pmRoot, params.staleBefore, {
+        settings: params.snapshot.runtimeDefaults.settings,
+        apply_runtime_defaults: false,
+    });
+}
+function vectorizationEmbeddingIdentityChanged(params) {
+    return (params.strictVectorizationWarnings &&
+        params.semanticRuntimeAvailable &&
+        Boolean(params.ledgerBefore.embedding &&
+            params.runtimeEmbeddingIdentity &&
+            hasVectorizationEmbeddingIdentityChanged(params.ledgerBefore.embedding, params.runtimeEmbeddingIdentity)));
+}
+/* c8 ignore start -- strict-vectorization warning synthesis branches are integration-only policy permutations */
+function collectVectorizationWarnings(params) {
+    const warningSet = new Set([...params.ledgerBefore.warnings, ...params.ledgerAfter.warnings]);
+    if (params.strictVectorizationWarnings) {
+        for (const warning of params.refreshResult.warnings) {
             warningSet.add(warning);
         }
     }
-    if (embeddingIdentityChanged) {
+    if (params.embeddingIdentityChanged) {
         warningSet.add("vectorization_embedding_identity_changed");
     }
-    if (strictVectorizationWarnings && semanticRuntimeAvailable && staleAfter.length > 0) {
-        warningSet.add(`vectorization_stale_items_remaining:${staleAfter.length}`);
+    if (params.strictVectorizationWarnings && params.semanticRuntimeAvailable && params.staleAfter.length > 0) {
+        warningSet.add(`vectorization_stale_items_remaining:${params.staleAfter.length}`);
     }
-    const warnings = [...warningSet].sort((left, right) => left.localeCompare(right));
+    return [...warningSet].sort((left, right) => left.localeCompare(right));
+}
+/* c8 ignore stop */
+function resolveVectorizationRefreshSkippedReason(refreshPolicy, semanticRuntimeAvailable, staleBefore) {
+    if (refreshPolicy.enabled && semanticRuntimeAvailable && staleBefore.length > 0) {
+        return null;
+    }
+    if (!refreshPolicy.enabled) {
+        return "refresh_disabled";
+    }
+    return semanticRuntimeAvailable ? "no_stale_items" : "semantic_runtime_unavailable";
+}
+function buildVectorizationProviderDetails(settings, snapshot) {
+    const activeProvider = snapshot.providerResolution.active?.name ?? null;
+    const activeVectorStore = snapshot.vectorStoreResolution.active?.name ?? null;
+    return {
+        provider_active: activeProvider,
+        // GH-244: surface the persisted (possibly empty) configured value and
+        // how the active resolution was sourced, so a config audit can tell
+        // "auto-detected" apart from a genuine misconfiguration when
+        // settings.search.provider / vector_store.adapter are empty strings.
+        provider_configured: typeof settings.search?.provider === "string" ? settings.search.provider : null,
+        provider_source: resolveProviderConfigSource(activeProvider, settings.search?.provider ?? null),
+        vector_store_active: activeVectorStore,
+        vector_store_configured: typeof settings.vector_store?.adapter === "string" ? settings.vector_store.adapter : null,
+        vector_store_source: resolveProviderConfigSource(activeVectorStore, settings.vector_store?.adapter ?? null),
+    };
+}
+function buildVectorizationRefreshPolicyDetails(refreshPolicy) {
+    return {
+        enabled: refreshPolicy.enabled,
+        check_only: refreshPolicy.checkOnly,
+        no_refresh: refreshPolicy.noRefresh,
+        refresh_vectors: refreshPolicy.refreshVectors,
+    };
+}
+function vectorizationRefreshAttempted(refreshPolicy, semanticRuntimeAvailable, staleBefore) {
+    return refreshPolicy.enabled && staleBefore.length > 0 && semanticRuntimeAvailable;
+}
+async function buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, verboseStaleItems) {
+    const snapshot = buildVectorizationRuntimeSnapshot(settings);
+    const ledgerBefore = await readVectorizationStatusLedger(pmRoot);
+    const staleBefore = snapshot.semanticRuntimeAvailable ? collectStaleVectorizationIds(items, ledgerBefore.entries) : [];
+    const refreshResult = await refreshStaleVectorizationItems({ pmRoot, snapshot, refreshPolicy, staleBefore });
+    const ledgerAfter = await readVectorizationStatusLedger(pmRoot);
+    const staleAfter = snapshot.semanticRuntimeAvailable ? collectStaleVectorizationIds(items, ledgerAfter.entries) : [];
+    const strictVectorizationWarnings = !snapshot.runtimeDefaults.auto_ollama_defaults_applied;
+    const embeddingIdentityChanged = vectorizationEmbeddingIdentityChanged({
+        strictVectorizationWarnings,
+        semanticRuntimeAvailable: snapshot.semanticRuntimeAvailable,
+        ledgerBefore,
+        runtimeEmbeddingIdentity: snapshot.runtimeEmbeddingIdentity,
+    });
+    const warnings = collectVectorizationWarnings({
+        ledgerBefore,
+        ledgerAfter,
+        refreshResult,
+        strictVectorizationWarnings,
+        semanticRuntimeAvailable: snapshot.semanticRuntimeAvailable,
+        embeddingIdentityChanged,
+        staleAfter,
+    });
     const staleBeforeDetail = selectStaleItemDetail(staleBefore, verboseStaleItems);
     const staleAfterDetail = selectStaleItemDetail(staleAfter, verboseStaleItems);
+    const refreshAttempted = vectorizationRefreshAttempted(refreshPolicy, snapshot.semanticRuntimeAvailable, staleBefore);
     return {
         check: {
             name: "vectorization",
             status: warnings.length === 0 ? "ok" : "warn",
             details: {
-                semantic_runtime_available: semanticRuntimeAvailable,
-                compatibility_mode_auto_defaults: runtimeDefaults.auto_ollama_defaults_applied,
-                auto_ollama_defaults_applied: runtimeDefaults.auto_ollama_defaults_applied,
-                refresh_policy: {
-                    enabled: refreshPolicy.enabled,
-                    check_only: refreshPolicy.checkOnly,
-                    no_refresh: refreshPolicy.noRefresh,
-                    refresh_vectors: refreshPolicy.refreshVectors,
-                },
-                provider_active: providerResolution.active?.name ?? null,
-                // GH-244: surface the persisted (possibly empty) configured value and
-                // how the active resolution was sourced, so a config audit can tell
-                // "auto-detected" apart from a genuine misconfiguration when
-                // settings.search.provider / vector_store.adapter are empty strings.
-                provider_configured: typeof settings.search?.provider === "string" ? settings.search.provider : null,
-                provider_source: resolveProviderConfigSource(providerResolution.active?.name ?? null, settings.search?.provider ?? null),
-                vector_store_active: vectorStoreResolution.active?.name ?? null,
-                vector_store_configured: typeof settings.vector_store?.adapter === "string" ? settings.vector_store.adapter : null,
-                vector_store_source: resolveProviderConfigSource(vectorStoreResolution.active?.name ?? null, settings.vector_store?.adapter ?? null),
+                semantic_runtime_available: snapshot.semanticRuntimeAvailable,
+                compatibility_mode_auto_defaults: snapshot.runtimeDefaults.auto_ollama_defaults_applied,
+                auto_ollama_defaults_applied: snapshot.runtimeDefaults.auto_ollama_defaults_applied,
+                refresh_policy: buildVectorizationRefreshPolicyDetails(refreshPolicy),
+                ...buildVectorizationProviderDetails(settings, snapshot),
                 embedding_identity_changed: embeddingIdentityChanged,
                 embedding_identity_before: ledgerBefore.embedding ?? null,
-                embedding_identity_runtime: runtimeEmbeddingIdentity ?? null,
+                embedding_identity_runtime: snapshot.runtimeEmbeddingIdentity ?? null,
                 items: items.length,
                 ledger_entries_before: Object.keys(ledgerBefore.entries).length,
                 stale_items_detail_mode: verboseStaleItems ? "full" : "summary",
@@ -1244,14 +1309,8 @@ async function buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, v
                 stale_items_before_total: staleBeforeDetail.total,
                 stale_items_before: staleBeforeDetail.values,
                 stale_items_before_truncated: staleBeforeDetail.truncated,
-                refresh_attempted: refreshPolicy.enabled && staleBefore.length > 0 && semanticRuntimeAvailable,
-                refresh_skipped_reason: refreshPolicy.enabled && semanticRuntimeAvailable && staleBefore.length > 0
-                    ? null
-                    : !refreshPolicy.enabled
-                        ? "refresh_disabled"
-                        : !semanticRuntimeAvailable
-                            ? "semantic_runtime_unavailable"
-                            : "no_stale_items",
+                refresh_attempted: refreshAttempted,
+                refresh_skipped_reason: resolveVectorizationRefreshSkippedReason(refreshPolicy, snapshot.semanticRuntimeAvailable, staleBefore),
                 refresh_result: refreshResult,
                 ledger_entries_after: Object.keys(ledgerAfter.entries).length,
                 stale_items_after_total: staleAfterDetail.total,
@@ -1261,7 +1320,6 @@ async function buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, v
         },
         warnings,
     };
-    /* c8 ignore stop */
 }
 function validateSettingsValues(settings) {
     const warnings = [];
@@ -1290,20 +1348,7 @@ function resolveVectorRefreshPolicy(options) {
         refreshVectors,
     };
 }
-/**
- * Implements run health for the public runtime surface of this module.
- */
-export async function runHealth(global, options = {}) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    const settingsPath = getSettingsPath(pmRoot);
-    if (!(await pathExists(settingsPath))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
-    const { settings, warnings: settingsReadWarnings } = await readSettingsWithMetadata(pmRoot);
-    const normalizedSettingsReadWarnings = [...new Set(settingsReadWarnings)];
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const strictDirectories = options.strictDirectories === true;
-    const refreshPolicy = resolveVectorRefreshPolicy(options);
+function resolveHealthDirectoryLists(typeRegistry) {
     const optionalBuiltinDirs = new Set(PM_OPTIONAL_TYPE_SUBDIRS.filter((entry) => entry.length > 0));
     const requiredDirSet = new Set(PM_CORE_REQUIRED_SUBDIRS.filter((entry) => entry.length > 0));
     const optionalDirSet = new Set();
@@ -1314,44 +1359,208 @@ export async function runHealth(global, options = {}) {
         }
         requiredDirSet.add(folder);
     }
-    const requiredDirs = [...requiredDirSet].sort((left, right) => left.localeCompare(right));
-    const optionalDirs = [...optionalDirSet].sort((left, right) => left.localeCompare(right));
+    return {
+        requiredDirs: [...requiredDirSet].sort((left, right) => left.localeCompare(right)),
+        optionalDirs: [...optionalDirSet].sort((left, right) => left.localeCompare(right)),
+        optionalDirSet,
+    };
+}
+async function scanHealthDirectories(pmRoot, typeRegistry, strictDirectories) {
+    const { requiredDirs, optionalDirs, optionalDirSet } = resolveHealthDirectoryLists(typeRegistry);
     const missingRequiredDirs = [];
     const missingOptionalDirs = [];
     const hookWarnings = [];
     for (const relativeDir of [...requiredDirs, ...optionalDirs]) {
         const directoryPath = path.join(pmRoot, relativeDir);
-        hookWarnings.push(...(await runActiveOnReadHooks({
-            path: directoryPath,
-            scope: "project",
-        })));
-        if (!(await isDirectory(directoryPath))) {
-            if (optionalDirSet.has(relativeDir)) {
-                missingOptionalDirs.push(relativeDir);
-            }
-            else {
-                missingRequiredDirs.push(relativeDir);
-            }
+        hookWarnings.push(...(await runActiveOnReadHooks({ path: directoryPath, scope: "project" })));
+        if (await isDirectory(directoryPath)) {
+            continue;
+        }
+        if (optionalDirSet.has(relativeDir)) {
+            missingOptionalDirs.push(relativeDir);
+        }
+        else {
+            missingRequiredDirs.push(relativeDir);
+        }
+    }
+    return {
+        requiredDirs,
+        optionalDirs,
+        missingRequiredDirs,
+        missingOptionalDirs,
+        missingDirs: strictDirectories ? [...missingRequiredDirs, ...missingOptionalDirs] : [...missingRequiredDirs],
+        hookWarnings,
+    };
+}
+function resolveHealthSkipPolicy(options) {
+    const summaryMode = options.summary === true && options.full !== true;
+    const fastProjectionCheckOnly = options.checkOnly === true && (options.brief === true || options.summary === true) && options.full !== true;
+    return {
+        summaryMode,
+        skipIntegrity: (options.skipIntegrity === true || fastProjectionCheckOnly) && options.full !== true,
+        skipDrift: (options.skipDrift === true || fastProjectionCheckOnly) && options.full !== true,
+        skipVectors: (options.skipVectors === true || fastProjectionCheckOnly) && options.full !== true,
+    };
+}
+async function readHealthItems(params) {
+    if (params.skipPolicy.skipDrift && params.skipPolicy.skipVectors) {
+        return listAllFrontMatter(params.pmRoot, params.settings.item_format, params.typeRegistry.type_to_folder, params.itemReadWarnings, params.settings.schema);
+    }
+    return listAllFrontMatterWithBody(params.pmRoot, params.settings.item_format, params.typeRegistry.type_to_folder, params.itemReadWarnings, params.settings.schema);
+}
+function buildSkippedHealthCheck(name) {
+    return { check: { name, status: "ok", details: { skipped: true } }, warnings: [] };
+}
+function buildSettingsHealthCheck(settingsPath, settings, normalizedSettingsReadWarnings) {
+    return {
+        name: "settings",
+        /* c8 ignore next -- settings read-warning status split is covered in broader read-settings integration tests */
+        status: normalizedSettingsReadWarnings.length === 0 ? "ok" : "warn",
+        details: {
+            path: settingsPath,
+            version: settings.version,
+            id_prefix: settings.id_prefix,
+            locks_ttl_seconds: settings.locks.ttl_seconds,
+            warnings: normalizedSettingsReadWarnings,
+        },
+    };
+}
+function buildDirectoriesHealthCheck(directoryState, strictDirectories) {
+    return {
+        name: "directories",
+        status: directoryState.missingDirs.length === 0 ? "ok" : "warn",
+        details: {
+            required: directoryState.requiredDirs,
+            optional: directoryState.optionalDirs,
+            missing_required: directoryState.missingRequiredDirs,
+            missing_optional: directoryState.missingOptionalDirs,
+            missing: directoryState.missingDirs,
+            strict_directories: strictDirectories,
+        },
+    };
+}
+function buildSettingsValuesHealthCheck(settingWarnings) {
+    return {
+        name: "settings_values",
+        status: settingWarnings.length === 0 ? "ok" : "warn",
+        details: { warnings: settingWarnings },
+    };
+}
+function buildStorageHealthCheck(items, settings, historySummary) {
+    return {
+        name: "storage",
+        status: historySummary.over_threshold.length === 0 ? "ok" : "warn",
+        details: {
+            items: items.length,
+            history_streams: historySummary.count,
+            ...(historySummary.max_entries !== null
+                ? {
+                    compact_policy: {
+                        enabled: settings.history.compact_policy.enabled,
+                        max_entries: historySummary.max_entries,
+                        trigger: settings.history.compact_policy.trigger,
+                        over_threshold_count: historySummary.over_threshold.length,
+                        over_threshold: historySummary.over_threshold,
+                    },
+                }
+                : {}),
+        },
+    };
+}
+function collectHealthWarnings(params) {
+    const warnings = [
+        ...params.directoryState.missingDirs.map((dir) => `missing_directory:${dir}`),
+        ...params.normalizedSettingsReadWarnings,
+        ...params.settingWarnings,
+        ...params.normalizedItemReadWarnings,
+        ...params.telemetryCheck.warnings,
+        ...params.extensionCheck.warnings,
+        ...params.historyPolicyWarnings,
+        ...params.historySummary.warnings,
+        ...params.locksCheck.warnings,
+        ...params.integrityCheck.warnings,
+        ...params.historyDriftCheck.warnings,
+        ...params.vectorizationCheck.warnings,
+        ...params.directoryState.hookWarnings,
+    ];
+    return [...new Set(warnings)];
+}
+function extractHistoryDriftedCount(historyDriftCheck) {
+    const counts = historyDriftCheck.check.details.counts;
+    return typeof counts?.drifted === "number" ? counts.drifted : 0;
+}
+function buildHealthRemediationSources(params) {
+    return {
+        settings: params.normalizedSettingsReadWarnings,
+        directories: params.directoryState.missingDirs.map((dir) => `missing_directory:${dir}`),
+        settings_values: params.settingWarnings,
+        telemetry: params.telemetryCheck.warnings,
+        extensions: params.extensionCheck.warnings,
+        storage: params.historySummary.over_threshold.map((id) => `history_stream_over_compact_threshold:${id}`),
+        locks: params.locksCheck.warnings,
+        integrity: params.integrityCheck.warnings,
+        history_drift: params.historyDriftCheck.warnings,
+        vectorization: params.vectorizationCheck.warnings,
+    };
+}
+function rewriteBulkHealthRemediation(params) {
+    if (params.check.name === "history_drift" && params.historyDriftedCount > 1) {
+        for (const code of Object.keys(params.remediationMap)) {
+            params.remediationMap[code] = "pm history-repair --all";
         }
     }
-    const missingDirs = strictDirectories ? [...missingRequiredDirs, ...missingOptionalDirs] : [...missingRequiredDirs];
+    if (params.check.name === "storage" && params.overThresholdCount > 1) {
+        for (const code of Object.keys(params.remediationMap)) {
+            params.remediationMap[code] = "pm history-compact --all-streams";
+        }
+    }
+}
+function attachHealthRemediationMaps(params) {
+    for (const check of params.checks) {
+        const remediationMap = buildRemediationMap(params.remediationSources[check.name]);
+        rewriteBulkHealthRemediation({
+            check,
+            remediationMap,
+            historyDriftedCount: params.historyDriftedCount,
+            overThresholdCount: params.overThresholdCount,
+        });
+        if (Object.keys(remediationMap).length > 0) {
+            check.details = { ...check.details, remediation_map: remediationMap };
+        }
+    }
+}
+function projectHealthResult(result, options, summaryMode) {
+    if (summaryMode) {
+        return applySummaryHealthProjection(result);
+    }
+    return options.brief === true ? applyBriefHealthProjection(result) : result;
+}
+/**
+ * Implements run health for the public runtime surface of this module.
+ */
+export async function runHealth(global, options = {}) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    const settingsPath = getSettingsPath(pmRoot);
+    if (!(await pathExists(settingsPath))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const { settings, warnings: settingsReadWarnings } = await readSettingsWithMetadata(pmRoot);
+    const normalizedSettingsReadWarnings = [...new Set(settingsReadWarnings)];
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const strictDirectories = options.strictDirectories === true;
+    const refreshPolicy = resolveVectorRefreshPolicy(options);
+    const directoryState = await scanHealthDirectories(pmRoot, typeRegistry, strictDirectories);
     const settingWarnings = validateSettingsValues(settings);
     const telemetryCheck = await buildTelemetryCheck(settings, {
         checkTelemetry: options.checkTelemetry === true,
     });
     const extensionCheck = await buildExtensionCheck(pmRoot, settings, Boolean(global.noExtensions));
-    const summaryMode = options.summary === true && options.full !== true;
-    const fastProjectionCheckOnly = options.checkOnly === true && (options.brief === true || options.summary === true) && options.full !== true;
-    const skipIntegrity = (options.skipIntegrity === true || fastProjectionCheckOnly) && options.full !== true;
-    const skipDrift = (options.skipDrift === true || fastProjectionCheckOnly) && options.full !== true;
-    const skipVectors = (options.skipVectors === true || fastProjectionCheckOnly) && options.full !== true;
+    const skipPolicy = resolveHealthSkipPolicy(options);
     const itemReadWarnings = [];
-    const items = skipDrift && skipVectors
-        ? await listAllFrontMatter(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema)
-        : await listAllFrontMatterWithBody(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema);
+    const items = await readHealthItems({ pmRoot, settings, typeRegistry, skipPolicy, itemReadWarnings });
     const itemsWithBody = items;
     const normalizedItemReadWarnings = [...new Set(itemReadWarnings)];
-    const historyPolicy = skipDrift
+    const historyPolicy = skipPolicy.skipDrift
         ? { warnings: [] }
         : await enforceHistoryStreamPolicyForItems({
             pmRoot,
@@ -1361,137 +1570,58 @@ export async function runHealth(global, options = {}) {
         });
     const historySummary = await countHistoryStreams(pmRoot, settings.history.compact_policy);
     const locksCheck = await buildLocksCheck(pmRoot);
-    const integrityCheck = skipIntegrity
-        ? { check: { name: "integrity", status: "ok", details: { skipped: true } }, warnings: [] }
+    const integrityCheck = skipPolicy.skipIntegrity
+        ? buildSkippedHealthCheck("integrity")
         : await buildIntegrityCheck(pmRoot, typeRegistry.type_to_folder, settings.schema);
-    const historyDriftCheck = skipDrift
-        ? { check: { name: "history_drift", status: "ok", details: { skipped: true } }, warnings: [] }
+    const historyDriftCheck = skipPolicy.skipDrift
+        ? buildSkippedHealthCheck("history_drift")
         : await buildHistoryDriftCheck(pmRoot, itemsWithBody);
-    const vectorizationCheck = skipVectors
-        ? { check: { name: "vectorization", status: "ok", details: { skipped: true } }, warnings: [] }
+    const vectorizationCheck = skipPolicy.skipVectors
+        ? buildSkippedHealthCheck("vectorization")
         : await buildVectorizationCheck(pmRoot, settings, itemsWithBody, refreshPolicy, options.verboseStaleItems === true);
     const checks = [
-        {
-            name: "settings",
-            /* c8 ignore next -- settings read-warning status split is covered in broader read-settings integration tests */
-            status: normalizedSettingsReadWarnings.length === 0 ? "ok" : "warn",
-            details: {
-                path: settingsPath,
-                version: settings.version,
-                id_prefix: settings.id_prefix,
-                locks_ttl_seconds: settings.locks.ttl_seconds,
-                warnings: normalizedSettingsReadWarnings,
-            },
-        },
-        {
-            name: "directories",
-            status: missingDirs.length === 0 ? "ok" : "warn",
-            details: {
-                required: requiredDirs,
-                optional: optionalDirs,
-                missing_required: missingRequiredDirs,
-                missing_optional: missingOptionalDirs,
-                missing: missingDirs,
-                strict_directories: strictDirectories,
-            },
-        },
-        {
-            name: "settings_values",
-            status: settingWarnings.length === 0 ? "ok" : "warn",
-            details: {
-                warnings: settingWarnings,
-            },
-        },
+        buildSettingsHealthCheck(settingsPath, settings, normalizedSettingsReadWarnings),
+        buildDirectoriesHealthCheck(directoryState, strictDirectories),
+        buildSettingsValuesHealthCheck(settingWarnings),
         telemetryCheck.check,
         extensionCheck.check,
-        {
-            name: "storage",
-            status: historySummary.over_threshold.length === 0 ? "ok" : "warn",
-            details: {
-                items: items.length,
-                history_streams: historySummary.count,
-                ...(historySummary.max_entries !== null
-                    ? {
-                        compact_policy: {
-                            enabled: settings.history.compact_policy.enabled,
-                            max_entries: historySummary.max_entries,
-                            trigger: settings.history.compact_policy.trigger,
-                            over_threshold_count: historySummary.over_threshold.length,
-                            over_threshold: historySummary.over_threshold,
-                        },
-                    }
-                    : {}),
-            },
-        },
+        buildStorageHealthCheck(items, settings, historySummary),
         locksCheck.check,
         integrityCheck.check,
         historyDriftCheck.check,
         vectorizationCheck.check,
     ];
-    const warnings = [
-        ...missingDirs.map((dir) => `missing_directory:${dir}`),
-        ...normalizedSettingsReadWarnings,
-        ...settingWarnings,
-        ...normalizedItemReadWarnings,
-        ...telemetryCheck.warnings,
-        ...extensionCheck.warnings,
-        ...historyPolicy.warnings,
-        ...historySummary.warnings,
-        ...locksCheck.warnings,
-        ...integrityCheck.warnings,
-        ...historyDriftCheck.warnings,
-        ...vectorizationCheck.warnings,
-        ...hookWarnings,
-    ];
-    const normalizedWarnings = [...new Set(warnings)];
-    // Attach a machine-executable remediation_map (warning-code-prefix -> fix
-    // command) to each non-extension check so agents gating on `pm health --json`
-    // never have to hardcode the warning-code -> fix mapping. The extensions check
-    // keeps its richer, contextual `details.triage.remediation`; brief/summary
-    // projections omit remediation_map (it lives only in full check details).
-    // Every health check contributes its warning tokens as a remediation source.
-    // Most resolve to a registered fix command; the extensions check passes its
-    // full warning list because only the system-wide partial-coverage adoption
-    // gap is registered — per-extension findings resolve to nothing here and keep
-    // their richer `details.triage.remediation`, so buildRemediationMap simply
-    // skips every unregistered code (pm-bdvm). The map is total over
-    // HealthCheck["name"], so no check is ever silently missing a source.
-    const checkRemediationSources = {
-        settings: normalizedSettingsReadWarnings,
-        directories: missingDirs.map((dir) => `missing_directory:${dir}`),
-        settings_values: settingWarnings,
-        telemetry: telemetryCheck.warnings,
-        extensions: extensionCheck.warnings,
-        storage: historySummary.over_threshold.map((id) => `history_stream_over_compact_threshold:${id}`),
-        locks: locksCheck.warnings,
-        integrity: integrityCheck.warnings,
-        history_drift: historyDriftCheck.warnings,
-        vectorization: vectorizationCheck.warnings,
-    };
-    const historyDriftedCount = typeof historyDriftCheck.check.details.counts?.drifted === "number"
-        ? (historyDriftCheck.check.details.counts.drifted)
-        : 0;
-    for (const check of checks) {
-        const remediationMap = buildRemediationMap(checkRemediationSources[check.name]);
-        // With multiple drifted streams the per-item `pm history-repair <id>`
-        // template would have to be run once per stream; suggest the bulk audited
-        // pass instead so agents repair everything in one command.
-        if (check.name === "history_drift" && historyDriftedCount > 1) {
-            for (const code of Object.keys(remediationMap)) {
-                remediationMap[code] = "pm history-repair --all";
-            }
-        }
-        // With multiple over-threshold streams, point at the one-pass bulk sweep
-        // rather than a per-stream `pm history-compact <id>` template.
-        if (check.name === "storage" && historySummary.over_threshold.length > 1) {
-            for (const code of Object.keys(remediationMap)) {
-                remediationMap[code] = "pm history-compact --all-streams";
-            }
-        }
-        if (Object.keys(remediationMap).length > 0) {
-            check.details = { ...check.details, remediation_map: remediationMap };
-        }
-    }
+    const normalizedWarnings = collectHealthWarnings({
+        directoryState,
+        normalizedSettingsReadWarnings,
+        settingWarnings,
+        normalizedItemReadWarnings,
+        telemetryCheck,
+        extensionCheck,
+        historyPolicyWarnings: historyPolicy.warnings,
+        historySummary,
+        locksCheck,
+        integrityCheck,
+        historyDriftCheck,
+        vectorizationCheck,
+    });
+    attachHealthRemediationMaps({
+        checks,
+        remediationSources: buildHealthRemediationSources({
+            directoryState,
+            normalizedSettingsReadWarnings,
+            settingWarnings,
+            telemetryCheck,
+            extensionCheck,
+            historySummary,
+            locksCheck,
+            integrityCheck,
+            historyDriftCheck,
+            vectorizationCheck,
+        }),
+        historyDriftedCount: extractHistoryDriftedCount(historyDriftCheck),
+        overThresholdCount: historySummary.over_threshold.length,
+    });
     // Telemetry is an opt-out, non-critical observability feature. Its operational
     // state (queue backlog, unreachable endpoint, corrupt local state) is advisory:
     // it must never flip overall project health to not-ok. Such warnings are still
@@ -1503,14 +1633,12 @@ export async function runHealth(global, options = {}) {
         warnings: normalizedWarnings,
         generated_at: nowIso(),
     };
-    if (summaryMode) {
-        return applySummaryHealthProjection(result);
-    }
-    return options.brief === true ? applyBriefHealthProjection(result) : result;
+    return projectHealthResult(result, options, skipPolicy.summaryMode);
 }
 export const _testOnlyHealthCommand = {
     buildExtensionHealthTriageSummary,
     buildCapabilityContractMetadata,
+    buildVectorizationProviderDetails,
     collectUnknownCapabilityGuidance,
     isAdvisoryHealthWarning,
     isDirectory,
@@ -1529,4 +1657,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=7b0dc685-2469-5d2e-98c8-07eebf79ee3e
+//# debugId=d078e1a2-2f92-566c-8ecd-542b2730a9b6