@unbrained/pm-cli 2026.6.19 → 2026.6.21

package/dist/cli/commands/gc.d.ts

@@ -1,5 +1,5 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
-declare const GC_SCOPE_VALUES: readonly ["index", "embeddings", "runtime", "locks"];
+declare const GC_SCOPE_VALUES: readonly ["index", "embeddings", "runtime", "locks", "checkpoints"];
 type GcScope = (typeof GC_SCOPE_VALUES)[number];
 /**
  * Documents the gc command options payload exchanged by command, SDK, and package integrations.
@@ -16,6 +16,15 @@ export interface GcLocksSummary {
     removed: number;
     retained: number;
 }
+/**
+ * Documents the gc checkpoints summary payload exchanged by command, SDK, and package integrations.
+ */
+export interface GcCheckpointsSummary {
+    scanned: number;
+    removed: number;
+    retained: number;
+    retention_days: number;
+}
 /**
  * Documents the gc result payload exchanged by command, SDK, and package integrations.
  */
@@ -29,6 +38,8 @@ export interface GcResult {
     guidance: string[];
     /** Present only when the locks scope was selected. Summarizes the stale-lock sweep. */
     locks?: GcLocksSummary;
+    /** Present only when the checkpoints scope was selected. Summarizes the rollback-checkpoint sweep. */
+    checkpoints?: GcCheckpointsSummary;
     generated_at: string;
 }
 /**

package/dist/cli/commands/gc.js

@@ -4,9 +4,10 @@
  * Implements the pm gc 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]="ba470490-f30a-5975-bcde-78ef3a04f30a")}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]="15ee0289-1af7-5b11-b023-f19cfc3363fc")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
+import { runCheckpointGc } from "../../core/checkpoint/checkpoint-gc.js";
 import { runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { runLockGc } from "../../core/lock/lock-gc.js";
@@ -15,7 +16,7 @@ import { PmCliError } from "../../core/shared/errors.js";
 import { nowIso } from "../../core/shared/time.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
-const GC_SCOPE_VALUES = ["index", "embeddings", "runtime", "locks"];
+const GC_SCOPE_VALUES = ["index", "embeddings", "runtime", "locks", "checkpoints"];
 const GC_TARGETS = [
     {
         scope: "index",
@@ -37,6 +38,21 @@ const GC_TARGETS = [
         relativePath: "search/lancedb",
         kind: "directory",
     },
+    {
+        // Removing embeddings invalidates the whole semantic index, so the queued
+        // background-refresh work is also meaningless: a worker draining a stale
+        // queue against an empty ledger would rebuild a partial, inconsistent index
+        // (only the queued items vectorized). Clear the queue and its gate so the
+        // next mutation re-seeds from a clean slate. See core/search/background-refresh.ts.
+        scope: "embeddings",
+        relativePath: "search/pending-refresh.json",
+        kind: "file",
+    },
+    {
+        scope: "embeddings",
+        relativePath: "search/pending-refresh.gate.lock",
+        kind: "directory",
+    },
     {
         scope: "runtime",
         relativePath: "runtime/test-runs",
@@ -133,13 +149,18 @@ function buildGcGuidance(params) {
     const searchArtifactsAffected = params.removed.some((entry) => entry === "index/manifest.json" ||
         entry === "search/embeddings.jsonl" ||
         entry === "search/vectorization-status.json" ||
-        entry === "search/lancedb");
+        entry === "search/lancedb" ||
+        entry === "search/pending-refresh.json" ||
+        entry === "search/pending-refresh.gate.lock");
     if (searchScopeSelected && searchArtifactsAffected) {
-        guidance.push('Search artifacts were removed; run "pm install search-advanced --project" if reindex is unavailable, then "pm reindex --mode keyword" (and "--mode semantic" when semantic search is enabled) before search-heavy workflows.');
+        guidance.push('Search artifacts were removed; the semantic index (including any queued background refresh) is invalidated. Run "pm install search-advanced --project" if reindex is unavailable, then "pm reindex --mode keyword" (and "--mode semantic" when semantic search is enabled) before search-heavy workflows.');
     }
     if (params.removed.includes("runtime/history-drift-cache.json")) {
         guidance.push('History drift cache was removed; the next "pm health" run performs a full history-drift re-scan.');
     }
+    if (!params.dryRun && params.removed.some((entry) => entry.startsWith("checkpoints/"))) {
+        guidance.push('Aged rollback checkpoints were removed; their "pm update-many"/"pm close-many --rollback" windows are no longer recoverable.');
+    }
     return guidance;
 }
 /**
@@ -150,7 +171,7 @@ export async function runGc(global, options = {}) {
     if (!(await pathExists(getSettingsPath(pmRoot)))) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
-    await readSettings(pmRoot);
+    const settings = await readSettings(pmRoot);
     const dryRun = options.dryRun === true;
     const scopes = parseScopes(options.scope);
     const selectedTargets = GC_TARGETS.filter((target) => scopes.includes(target.scope));
@@ -188,6 +209,31 @@ export async function runGc(global, options = {}) {
             retained: lockResult.retained.length,
         };
     }
+    // The checkpoints scope is also not a path-based GC_TARGET: it sweeps
+    // checkpoints/ and removes only rollback checkpoints older than the configured
+    // checkpoints.retention_days, retaining active and unparseable files. See
+    // core/checkpoint/checkpoint-gc.ts.
+    let checkpointsSummary;
+    if (scopes.includes("checkpoints")) {
+        const retentionDays = settings.checkpoints.retention_days;
+        const checkpointResult = await runCheckpointGc(pmRoot, {
+            dryRun,
+            retentionDays,
+            hooks: {
+                onRead: (checkpointPath) => runActiveOnReadHooks({ path: checkpointPath, scope: "project" }),
+                onWrite: (checkpointPath) => runActiveOnWriteHooks({ path: checkpointPath, scope: "project", op: "gc:checkpoint_remove" }),
+            },
+        });
+        removed.push(...checkpointResult.removed);
+        retained.push(...checkpointResult.retained);
+        warnings.push(...checkpointResult.warnings);
+        checkpointsSummary = {
+            scanned: checkpointResult.scanned,
+            removed: checkpointResult.removed.length,
+            retained: checkpointResult.retained.length,
+            retention_days: retentionDays,
+        };
+    }
     warnings.push(...(await runActiveOnIndexHooks({
         mode: dryRun ? "gc:dry-run" : "gc",
         total_items: selectedTargets.length,
@@ -205,9 +251,10 @@ export async function runGc(global, options = {}) {
         retained,
         warnings,
         ...(locksSummary ? { locks: locksSummary } : {}),
+        ...(checkpointsSummary ? { checkpoints: checkpointsSummary } : {}),
         guidance,
         generated_at: nowIso(),
     };
 }
 //# sourceMappingURL=gc.js.map
-//# debugId=ba470490-f30a-5975-bcde-78ef3a04f30a
+//# debugId=15ee0289-1af7-5b11-b023-f19cfc3363fc

package/dist/cli/commands/gc.js.map

@@ -1 +1 @@
-{"version":3,"file":"gc.js","sources":["cli/commands/gc.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/gc\n *\n * Implements the pm gc command surface and its agent-facing runtime behavior.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks } from \"../../core/extensions/index.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { runLockGc } from \"../../core/lock/lock-gc.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\n\nconst GC_SCOPE_VALUES = [\"index\", \"embeddings\", \"runtime\", \"locks\"] as const;\ntype GcScope = (typeof GC_SCOPE_VALUES)[number];\n\ninterface GcTarget {\n  scope: GcScope;\n  relativePath: string;\n  kind: \"file\" | \"directory\";\n}\n\nconst GC_TARGETS: readonly GcTarget[] = [\n  {\n    scope: \"index\",\n    relativePath: \"index/manifest.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/embeddings.jsonl\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/vectorization-status.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/lancedb\",\n    kind: \"directory\",\n  },\n  {\n    scope: \"runtime\",\n    relativePath: \"runtime/test-runs\",\n    kind: \"directory\",\n  },\n  {\n    scope: \"runtime\",\n    relativePath: \"runtime/history-drift-cache.json\",\n    kind: \"file\",\n  },\n] as const;\n\n/**\n * Documents the gc command options payload exchanged by command, SDK, and package integrations.\n */\nexport interface GcCommandOptions {\n  dryRun?: boolean;\n  scope?: string[];\n}\n\n/**\n * Documents the gc locks summary payload exchanged by command, SDK, and package integrations.\n */\nexport interface GcLocksSummary {\n  scanned: number;\n  removed: number;\n  retained: number;\n}\n\n/**\n * Documents the gc result payload exchanged by command, SDK, and package integrations.\n */\nexport interface GcResult {\n  ok: boolean;\n  dry_run: boolean;\n  scope: GcScope[];\n  removed: string[];\n  retained: string[];\n  warnings: string[];\n  guidance: string[];\n  /** Present only when the locks scope was selected. Summarizes the stale-lock sweep. */\n  locks?: GcLocksSummary;\n  generated_at: string;\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n  return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: string }).code === code;\n}\n\nasync function removeCacheFile(\n  pmRoot: string,\n  target: GcTarget,\n  dryRun: boolean,\n): Promise<{ removed: boolean; warnings: string[] }> {\n  const relativePath = target.relativePath;\n  const absolutePath = path.join(pmRoot, relativePath);\n  const warnings = await runActiveOnReadHooks({\n    path: absolutePath,\n    scope: \"project\",\n  });\n  try {\n    const stats = await fs.stat(absolutePath);\n    if (target.kind === \"file\" && !stats.isFile()) {\n      return {\n        removed: false,\n        warnings: [...warnings, `not_a_file:${relativePath}`],\n      };\n    }\n    if (target.kind === \"directory\" && !stats.isDirectory()) {\n      return {\n        removed: false,\n        warnings: [...warnings, `not_a_directory:${relativePath}`],\n      };\n    }\n    if (dryRun) {\n      return {\n        removed: true,\n        warnings,\n      };\n    }\n    if (target.kind === \"file\") {\n      await fs.unlink(absolutePath);\n    } else {\n      await fs.rm(absolutePath, { recursive: true, force: true });\n    }\n    const writeWarnings = await runActiveOnWriteHooks({\n      path: absolutePath,\n      scope: \"project\",\n      op: \"gc:remove\",\n    });\n    return {\n      removed: true,\n      warnings: [...warnings, ...writeWarnings],\n    };\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return {\n        removed: false,\n        warnings,\n      };\n    }\n    throw error;\n  }\n}\n\nfunction parseScopes(raw: string[] | undefined): GcScope[] {\n  if (!raw || raw.length === 0) {\n    return [...GC_SCOPE_VALUES];\n  }\n  const tokens = raw\n    .flatMap((entry) => entry.split(\",\"))\n    .map((entry) => entry.trim().toLowerCase())\n    .filter((entry) => entry.length > 0);\n  if (tokens.length === 0) {\n    throw new PmCliError(`--scope requires at least one value (${GC_SCOPE_VALUES.join(\",\")})`, EXIT_CODE.USAGE);\n  }\n  const resolved = new Set<GcScope>();\n  for (const token of tokens) {\n    if (!(GC_SCOPE_VALUES as readonly string[]).includes(token)) {\n      throw new PmCliError(\n        `Invalid --scope value \"${token}\". Expected one or more of: ${GC_SCOPE_VALUES.join(\", \")}`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    resolved.add(token as GcScope);\n  }\n  return GC_SCOPE_VALUES.filter((scope) => resolved.has(scope));\n}\n\nfunction buildGcGuidance(params: {\n  dryRun: boolean;\n  scopes: GcScope[];\n  removed: string[];\n}): string[] {\n  const guidance: string[] = [];\n  if (params.dryRun) {\n    guidance.push(\"Dry-run preview only: no cache artifacts were deleted.\");\n  }\n  const searchScopeSelected = params.scopes.includes(\"index\") || params.scopes.includes(\"embeddings\");\n  const searchArtifactsAffected = params.removed.some(\n    (entry) =>\n      entry === \"index/manifest.json\" ||\n      entry === \"search/embeddings.jsonl\" ||\n      entry === \"search/vectorization-status.json\" ||\n      entry === \"search/lancedb\",\n  );\n  if (searchScopeSelected && searchArtifactsAffected) {\n    guidance.push(\n      'Search artifacts were removed; run \"pm install search-advanced --project\" if reindex is unavailable, then \"pm reindex --mode keyword\" (and \"--mode semantic\" when semantic search is enabled) before search-heavy workflows.',\n    );\n  }\n  if (params.removed.includes(\"runtime/history-drift-cache.json\")) {\n    guidance.push('History drift cache was removed; the next \"pm health\" run performs a full history-drift re-scan.');\n  }\n  return guidance;\n}\n\n/**\n * Implements run gc for the public runtime surface of this module.\n */\nexport async function runGc(global: GlobalOptions, options: GcCommandOptions = {}): Promise<GcResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n\n  await readSettings(pmRoot);\n  const dryRun = options.dryRun === true;\n  const scopes = parseScopes(options.scope);\n  const selectedTargets = GC_TARGETS.filter((target) => scopes.includes(target.scope));\n\n  const removed: string[] = [];\n  const retained: string[] = [];\n  const warnings: string[] = [];\n\n  for (const target of selectedTargets) {\n    const result = await removeCacheFile(pmRoot, target, dryRun);\n    if (result.removed) {\n      removed.push(target.relativePath);\n    } else {\n      retained.push(target.relativePath);\n    }\n    warnings.push(...result.warnings);\n  }\n\n  // The locks scope is not a path-based GC_TARGET: it sweeps the locks/ directory\n  // and removes only locks whose own embedded ttl has expired (crashed-process\n  // debris), retaining active and unparseable locks. See core/lock/lock-gc.ts.\n  let locksSummary: GcLocksSummary | undefined;\n  if (scopes.includes(\"locks\")) {\n    const lockResult = await runLockGc(pmRoot, {\n      dryRun,\n      hooks: {\n        onRead: (lockPath) => runActiveOnReadHooks({ path: lockPath, scope: \"project\" }),\n        onWrite: (lockPath) => runActiveOnWriteHooks({ path: lockPath, scope: \"project\", op: \"gc:lock_remove\" }),\n      },\n    });\n    removed.push(...lockResult.removed);\n    retained.push(...lockResult.retained);\n    warnings.push(...lockResult.warnings);\n    locksSummary = {\n      scanned: lockResult.scanned,\n      removed: lockResult.removed.length,\n      retained: lockResult.retained.length,\n    };\n  }\n\n  warnings.push(\n    ...(await runActiveOnIndexHooks({\n      mode: dryRun ? \"gc:dry-run\" : \"gc\",\n      total_items: selectedTargets.length,\n    })),\n  );\n  const guidance = buildGcGuidance({\n    dryRun,\n    scopes,\n    removed,\n  });\n\n  return {\n    ok: warnings.length === 0,\n    dry_run: dryRun,\n    scope: scopes,\n    removed,\n    retained,\n    warnings,\n    ...(locksSummary ? { locks: locksSummary } : {}),\n    guidance,\n    generated_at: nowIso(),\n  };\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACpH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAU,CAAC;AAS7E,MAAM,UAAU,GAAwB;IACtC;QACE,KAAK,EAAE,OAAO;QACd,YAAY,EAAE,qBAAqB;QACnC,IAAI,EAAE,MAAM;KACb;IACD;QACE,KAAK,EAAE,YAAY;QACnB,YAAY,EAAE,yBAAyB;QACvC,IAAI,EAAE,MAAM;KACb;IACD;QACE,KAAK,EAAE,YAAY;QACnB,YAAY,EAAE,kCAAkC;QAChD,IAAI,EAAE,MAAM;KACb;IACD;QACE,KAAK,EAAE,YAAY;QACnB,YAAY,EAAE,gBAAgB;QAC9B,IAAI,EAAE,WAAW;KAClB;IACD;QACE,KAAK,EAAE,SAAS;QAChB,YAAY,EAAE,mBAAmB;QACjC,IAAI,EAAE,WAAW;KAClB;IACD;QACE,KAAK,EAAE,SAAS;QAChB,YAAY,EAAE,kCAAkC;QAChD,IAAI,EAAE,MAAM;KACb;CACO,CAAC;AAmCX,SAAS,OAAO,CAAC,KAAc,EAAE,IAAY;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAK,KAA2B,CAAC,IAAI,KAAK,IAAI,CAAC;AACtH,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,MAAc,EACd,MAAgB,EAChB,MAAe;IAEf,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IACzC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC;QAC1C,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YAC9C,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,cAAc,YAAY,EAAE,CAAC;aACtD,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxD,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,mBAAmB,YAAY,EAAE,CAAC;aAC3D,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,QAAQ;aACT,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,MAAM,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,aAAa,GAAG,MAAM,qBAAqB,CAAC;YAChD,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,SAAS;YAChB,EAAE,EAAE,WAAW;SAChB,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,aAAa,CAAC;SAC1C,CAAC;IACJ,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,QAAQ;aACT,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,GAAyB;IAC5C,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,MAAM,GAAG,GAAG;SACf,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;SACpC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAC1C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,wCAAwC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9G,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAW,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAE,eAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,UAAU,CAClB,0BAA0B,KAAK,+BAA+B,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC1F,SAAS,CAAC,KAAK,CAChB,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,KAAgB,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,eAAe,CAAC,MAIxB;IACC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,QAAQ,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IACpG,MAAM,uBAAuB,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CACjD,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,KAAK,qBAAqB;QAC/B,KAAK,KAAK,yBAAyB;QACnC,KAAK,KAAK,kCAAkC;QAC5C,KAAK,KAAK,gBAAgB,CAC7B,CAAC;IACF,IAAI,mBAAmB,IAAI,uBAAuB,EAAE,CAAC;QACnD,QAAQ,CAAC,IAAI,CACX,8NAA8N,CAC/N,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,kCAAkC,CAAC,EAAE,CAAC;QAChE,QAAQ,CAAC,IAAI,CAAC,kGAAkG,CAAC,CAAC;IACpH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,MAAqB,EAAE,UAA4B,EAAE;IAC/E,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,UAAU,CAAC,iCAAiC,MAAM,sBAAsB,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC3G,CAAC;IAED,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC;IACvC,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,eAAe,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAErF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7D,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QACrC,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,gFAAgF;IAChF,6EAA6E;IAC7E,6EAA6E;IAC7E,IAAI,YAAwC,CAAC;IAC7C,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE;YACzC,MAAM;YACN,KAAK,EAAE;gBACL,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,oBAAoB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;gBAChF,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC;aACzG;SACF,CAAC,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QACtC,QAAQ,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QACtC,YAAY,GAAG;YACb,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,MAAM;YAClC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,MAAM;SACrC,CAAC;IACJ,CAAC;IAED,QAAQ,CAAC,IAAI,CACX,GAAG,CAAC,MAAM,qBAAqB,CAAC;QAC9B,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI;QAClC,WAAW,EAAE,eAAe,CAAC,MAAM;KACpC,CAAC,CAAC,CACJ,CAAC;IACF,MAAM,QAAQ,GAAG,eAAe,CAAC;QAC/B,MAAM;QACN,MAAM;QACN,OAAO;KACR,CAAC,CAAC;IAEH,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC;QACzB,OAAO,EAAE,MAAM;QACf,KAAK,EAAE,MAAM;QACb,OAAO;QACP,QAAQ;QACR,QAAQ;QACR,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,QAAQ;QACR,YAAY,EAAE,MAAM,EAAE;KACvB,CAAC;AACJ,CAAC","debugId":"ba470490-f30a-5975-bcde-78ef3a04f30a"}
+{"version":3,"file":"gc.js","sources":["cli/commands/gc.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/gc\n *\n * Implements the pm gc command surface and its agent-facing runtime behavior.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { runCheckpointGc } from \"../../core/checkpoint/checkpoint-gc.js\";\nimport { runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks } from \"../../core/extensions/index.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { runLockGc } from \"../../core/lock/lock-gc.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\n\nconst GC_SCOPE_VALUES = [\"index\", \"embeddings\", \"runtime\", \"locks\", \"checkpoints\"] as const;\ntype GcScope = (typeof GC_SCOPE_VALUES)[number];\n\ninterface GcTarget {\n  scope: GcScope;\n  relativePath: string;\n  kind: \"file\" | \"directory\";\n}\n\nconst GC_TARGETS: readonly GcTarget[] = [\n  {\n    scope: \"index\",\n    relativePath: \"index/manifest.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/embeddings.jsonl\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/vectorization-status.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/lancedb\",\n    kind: \"directory\",\n  },\n  {\n    // Removing embeddings invalidates the whole semantic index, so the queued\n    // background-refresh work is also meaningless: a worker draining a stale\n    // queue against an empty ledger would rebuild a partial, inconsistent index\n    // (only the queued items vectorized). Clear the queue and its gate so the\n    // next mutation re-seeds from a clean slate. See core/search/background-refresh.ts.\n    scope: \"embeddings\",\n    relativePath: \"search/pending-refresh.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/pending-refresh.gate.lock\",\n    kind: \"directory\",\n  },\n  {\n    scope: \"runtime\",\n    relativePath: \"runtime/test-runs\",\n    kind: \"directory\",\n  },\n  {\n    scope: \"runtime\",\n    relativePath: \"runtime/history-drift-cache.json\",\n    kind: \"file\",\n  },\n] as const;\n\n/**\n * Documents the gc command options payload exchanged by command, SDK, and package integrations.\n */\nexport interface GcCommandOptions {\n  dryRun?: boolean;\n  scope?: string[];\n}\n\n/**\n * Documents the gc locks summary payload exchanged by command, SDK, and package integrations.\n */\nexport interface GcLocksSummary {\n  scanned: number;\n  removed: number;\n  retained: number;\n}\n\n/**\n * Documents the gc checkpoints summary payload exchanged by command, SDK, and package integrations.\n */\nexport interface GcCheckpointsSummary {\n  scanned: number;\n  removed: number;\n  retained: number;\n  retention_days: number;\n}\n\n/**\n * Documents the gc result payload exchanged by command, SDK, and package integrations.\n */\nexport interface GcResult {\n  ok: boolean;\n  dry_run: boolean;\n  scope: GcScope[];\n  removed: string[];\n  retained: string[];\n  warnings: string[];\n  guidance: string[];\n  /** Present only when the locks scope was selected. Summarizes the stale-lock sweep. */\n  locks?: GcLocksSummary;\n  /** Present only when the checkpoints scope was selected. Summarizes the rollback-checkpoint sweep. */\n  checkpoints?: GcCheckpointsSummary;\n  generated_at: string;\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n  return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: string }).code === code;\n}\n\nasync function removeCacheFile(\n  pmRoot: string,\n  target: GcTarget,\n  dryRun: boolean,\n): Promise<{ removed: boolean; warnings: string[] }> {\n  const relativePath = target.relativePath;\n  const absolutePath = path.join(pmRoot, relativePath);\n  const warnings = await runActiveOnReadHooks({\n    path: absolutePath,\n    scope: \"project\",\n  });\n  try {\n    const stats = await fs.stat(absolutePath);\n    if (target.kind === \"file\" && !stats.isFile()) {\n      return {\n        removed: false,\n        warnings: [...warnings, `not_a_file:${relativePath}`],\n      };\n    }\n    if (target.kind === \"directory\" && !stats.isDirectory()) {\n      return {\n        removed: false,\n        warnings: [...warnings, `not_a_directory:${relativePath}`],\n      };\n    }\n    if (dryRun) {\n      return {\n        removed: true,\n        warnings,\n      };\n    }\n    if (target.kind === \"file\") {\n      await fs.unlink(absolutePath);\n    } else {\n      await fs.rm(absolutePath, { recursive: true, force: true });\n    }\n    const writeWarnings = await runActiveOnWriteHooks({\n      path: absolutePath,\n      scope: \"project\",\n      op: \"gc:remove\",\n    });\n    return {\n      removed: true,\n      warnings: [...warnings, ...writeWarnings],\n    };\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return {\n        removed: false,\n        warnings,\n      };\n    }\n    throw error;\n  }\n}\n\nfunction parseScopes(raw: string[] | undefined): GcScope[] {\n  if (!raw || raw.length === 0) {\n    return [...GC_SCOPE_VALUES];\n  }\n  const tokens = raw\n    .flatMap((entry) => entry.split(\",\"))\n    .map((entry) => entry.trim().toLowerCase())\n    .filter((entry) => entry.length > 0);\n  if (tokens.length === 0) {\n    throw new PmCliError(`--scope requires at least one value (${GC_SCOPE_VALUES.join(\",\")})`, EXIT_CODE.USAGE);\n  }\n  const resolved = new Set<GcScope>();\n  for (const token of tokens) {\n    if (!(GC_SCOPE_VALUES as readonly string[]).includes(token)) {\n      throw new PmCliError(\n        `Invalid --scope value \"${token}\". Expected one or more of: ${GC_SCOPE_VALUES.join(\", \")}`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    resolved.add(token as GcScope);\n  }\n  return GC_SCOPE_VALUES.filter((scope) => resolved.has(scope));\n}\n\nfunction buildGcGuidance(params: {\n  dryRun: boolean;\n  scopes: GcScope[];\n  removed: string[];\n}): string[] {\n  const guidance: string[] = [];\n  if (params.dryRun) {\n    guidance.push(\"Dry-run preview only: no cache artifacts were deleted.\");\n  }\n  const searchScopeSelected = params.scopes.includes(\"index\") || params.scopes.includes(\"embeddings\");\n  const searchArtifactsAffected = params.removed.some(\n    (entry) =>\n      entry === \"index/manifest.json\" ||\n      entry === \"search/embeddings.jsonl\" ||\n      entry === \"search/vectorization-status.json\" ||\n      entry === \"search/lancedb\" ||\n      entry === \"search/pending-refresh.json\" ||\n      entry === \"search/pending-refresh.gate.lock\",\n  );\n  if (searchScopeSelected && searchArtifactsAffected) {\n    guidance.push(\n      'Search artifacts were removed; the semantic index (including any queued background refresh) is invalidated. Run \"pm install search-advanced --project\" if reindex is unavailable, then \"pm reindex --mode keyword\" (and \"--mode semantic\" when semantic search is enabled) before search-heavy workflows.',\n    );\n  }\n  if (params.removed.includes(\"runtime/history-drift-cache.json\")) {\n    guidance.push('History drift cache was removed; the next \"pm health\" run performs a full history-drift re-scan.');\n  }\n  if (!params.dryRun && params.removed.some((entry) => entry.startsWith(\"checkpoints/\"))) {\n    guidance.push(\n      'Aged rollback checkpoints were removed; their \"pm update-many\"/\"pm close-many --rollback\" windows are no longer recoverable.',\n    );\n  }\n  return guidance;\n}\n\n/**\n * Implements run gc for the public runtime surface of this module.\n */\nexport async function runGc(global: GlobalOptions, options: GcCommandOptions = {}): Promise<GcResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n\n  const settings = await readSettings(pmRoot);\n  const dryRun = options.dryRun === true;\n  const scopes = parseScopes(options.scope);\n  const selectedTargets = GC_TARGETS.filter((target) => scopes.includes(target.scope));\n\n  const removed: string[] = [];\n  const retained: string[] = [];\n  const warnings: string[] = [];\n\n  for (const target of selectedTargets) {\n    const result = await removeCacheFile(pmRoot, target, dryRun);\n    if (result.removed) {\n      removed.push(target.relativePath);\n    } else {\n      retained.push(target.relativePath);\n    }\n    warnings.push(...result.warnings);\n  }\n\n  // The locks scope is not a path-based GC_TARGET: it sweeps the locks/ directory\n  // and removes only locks whose own embedded ttl has expired (crashed-process\n  // debris), retaining active and unparseable locks. See core/lock/lock-gc.ts.\n  let locksSummary: GcLocksSummary | undefined;\n  if (scopes.includes(\"locks\")) {\n    const lockResult = await runLockGc(pmRoot, {\n      dryRun,\n      hooks: {\n        onRead: (lockPath) => runActiveOnReadHooks({ path: lockPath, scope: \"project\" }),\n        onWrite: (lockPath) => runActiveOnWriteHooks({ path: lockPath, scope: \"project\", op: \"gc:lock_remove\" }),\n      },\n    });\n    removed.push(...lockResult.removed);\n    retained.push(...lockResult.retained);\n    warnings.push(...lockResult.warnings);\n    locksSummary = {\n      scanned: lockResult.scanned,\n      removed: lockResult.removed.length,\n      retained: lockResult.retained.length,\n    };\n  }\n\n  // The checkpoints scope is also not a path-based GC_TARGET: it sweeps\n  // checkpoints/ and removes only rollback checkpoints older than the configured\n  // checkpoints.retention_days, retaining active and unparseable files. See\n  // core/checkpoint/checkpoint-gc.ts.\n  let checkpointsSummary: GcCheckpointsSummary | undefined;\n  if (scopes.includes(\"checkpoints\")) {\n    const retentionDays = settings.checkpoints.retention_days;\n    const checkpointResult = await runCheckpointGc(pmRoot, {\n      dryRun,\n      retentionDays,\n      hooks: {\n        onRead: (checkpointPath) => runActiveOnReadHooks({ path: checkpointPath, scope: \"project\" }),\n        onWrite: (checkpointPath) =>\n          runActiveOnWriteHooks({ path: checkpointPath, scope: \"project\", op: \"gc:checkpoint_remove\" }),\n      },\n    });\n    removed.push(...checkpointResult.removed);\n    retained.push(...checkpointResult.retained);\n    warnings.push(...checkpointResult.warnings);\n    checkpointsSummary = {\n      scanned: checkpointResult.scanned,\n      removed: checkpointResult.removed.length,\n      retained: checkpointResult.retained.length,\n      retention_days: retentionDays,\n    };\n  }\n\n  warnings.push(\n    ...(await runActiveOnIndexHooks({\n      mode: dryRun ? \"gc:dry-run\" : \"gc\",\n      total_items: selectedTargets.length,\n    })),\n  );\n  const guidance = buildGcGuidance({\n    dryRun,\n    scopes,\n    removed,\n  });\n\n  return {\n    ok: warnings.length === 0,\n    dry_run: dryRun,\n    scope: scopes,\n    removed,\n    retained,\n    warnings,\n    ...(locksSummary ? { locks: locksSummary } : {}),\n    ...(checkpointsSummary ? { checkpoints: checkpointsSummary } : {}),\n    guidance,\n    generated_at: nowIso(),\n  };\n}\n"],"names":[],"mappings":"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","debugId":"15ee0289-1af7-5b11-b023-f19cfc3363fc"}

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]="1ab8503b-2a2e-5485-9d9a-5af40782bc29")}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]="7b0dc685-2469-5d2e-98c8-07eebf79ee3e")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -27,6 +27,7 @@ import { PmCliError } from "../../core/shared/errors.js";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
 import { nowIso } from "../../core/shared/time.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
+import { effectiveItemFormatVersion, scanItemFormatVersions } from "../../core/item/item-format-version.js";
 import { listAllFrontMatter, listAllFrontMatterWithBody } 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";
 const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
@@ -154,6 +155,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema) {
     const itemUnreadable = [];
     const itemConflictMarkers = [];
     const itemParseFailures = [];
+    const formatVersionEntries = [];
     const extensionFieldNames = collectRegisteredItemFieldNames(getActiveExtensionRegistrations());
     for (const itemPath of itemPaths) {
         const relativePath = normalizeRelativePath(pmRoot, itemPath);
@@ -175,12 +177,14 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema) {
             continue;
         }
         try {
-            parseItemDocument(raw, { format: getItemFormatFromPath(itemPath), schema, extensionFieldNames });
+            const parsed = parseItemDocument(raw, { format: getItemFormatFromPath(itemPath), schema, extensionFieldNames });
+            formatVersionEntries.push({ ref: relativePath, version: effectiveItemFormatVersion(parsed.metadata) });
         }
         catch {
             itemParseFailures.push(relativePath);
         }
     }
+    const formatVersionScan = scanItemFormatVersions(formatVersionEntries);
     const historyDir = path.join(pmRoot, "history");
     const historyUnreadable = [];
     const historyConflictMarkers = [];
@@ -240,6 +244,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema) {
         ...historyUnreadable.map((entry) => `integrity_history_unreadable:${entry}`),
         ...historyConflictMarkers.map((entry) => `integrity_history_conflict_marker:${entry.id}:L${entry.line}`),
         ...historyInvalidJson.map((entry) => `integrity_history_invalid_json:${entry.id}:L${entry.line}`),
+        /* c8 ignore start -- outdated-version items are unreachable until CURRENT_ITEM_FORMAT_VERSION advances past the baseline (an effective version below 1 cannot occur); the per-item mapping is covered in item-format-version.spec, and the ahead path below is covered by health-command.spec */
+        ...formatVersionScan.outdated.map((entry) => `integrity_item_outdated_format_version:${entry}`),
+        /* c8 ignore stop */
+        ...formatVersionScan.ahead.map((entry) => `integrity_item_ahead_format_version:${entry}`),
     ];
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
     return {
@@ -256,10 +264,14 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema) {
                     history_unreadable: historyUnreadable.length,
                     history_conflict_markers: historyConflictMarkers.length,
                     history_invalid_json: historyInvalidJson.length,
+                    item_outdated_format_version: formatVersionScan.outdated.length,
+                    item_ahead_format_version: formatVersionScan.ahead.length,
                 },
                 item_unreadable: itemUnreadable,
                 item_conflict_markers: itemConflictMarkers,
                 item_parse_failures: itemParseFailures,
+                item_outdated_format_version: formatVersionScan.outdated,
+                item_ahead_format_version: formatVersionScan.ahead,
                 history_unreadable: historyUnreadable,
                 history_conflict_markers: historyConflictMarkers,
                 history_invalid_json: historyInvalidJson,
@@ -1121,7 +1133,8 @@ async function buildLocksCheck(pmRoot) {
     };
 }
 async function buildHistoryDriftCheck(pmRoot, items) {
-    const { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems } = await scanHistoryDrift(pmRoot, items);
+    const cacheHitVerification = "metadata";
+    const { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems } = await scanHistoryDrift(pmRoot, items, { cacheHitVerification });
     const warnings = [
         ...missingStreams.map((id) => `history_drift_missing_stream:${id}`),
         ...unreadableStreams.map((id) => `history_drift_unreadable_stream:${id}`),
@@ -1134,6 +1147,7 @@ async function buildHistoryDriftCheck(pmRoot, items) {
             status: warnings.length === 0 ? "ok" : "warn",
             details: {
                 checked_items: items.length,
+                cache_hit_verification: cacheHitVerification,
                 drifted_items: driftedItems,
                 counts: {
                     drifted: driftedItems.length,
@@ -1435,11 +1449,19 @@ export async function runHealth(global, options = {}) {
     // 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,
@@ -1450,11 +1472,7 @@ export async function runHealth(global, options = {}) {
         ? (historyDriftCheck.check.details.counts.drifted)
         : 0;
     for (const check of checks) {
-        const sources = checkRemediationSources[check.name];
-        if (sources === undefined) {
-            continue;
-        }
-        const remediationMap = buildRemediationMap(sources);
+        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.
@@ -1511,4 +1529,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=1ab8503b-2a2e-5485-9d9a-5af40782bc29
+//# debugId=7b0dc685-2469-5d2e-98c8-07eebf79ee3e