@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/opaque-mutation-scan.js

@@ -41,12 +41,21 @@ import { createHash } from "node:crypto";
 import { normalizeMapKey } from "./path-utils.js";
 import { freshnessFromMtime } from "./freshness.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { truncatedByOutputCap } from "./spawn-output-cap.js";
 /** Stop hashing once this many cumulative bytes were read (per capture). */
 export const OPAQUE_HASH_BUDGET_BYTES = 8 * 1024 * 1024;
 /** Hard cap on scanned files — beyond it the verdict is coverage-unknown. */
 export const OPAQUE_SCAN_MAX_FILES = 2000;
 /** How far before recorded start an earlier write may still be attributed. */
 export const OPAQUE_MTIME_TOLERANCE_MS = 150;
+// `--untracked-files=all` lists untracked files individually instead of
+// collapsing them per directory (it does NOT add ignored paths — that needs
+// `--ignored`), so the worst realistic case is a working tree with a large
+// unignored generated or vendored directory, and a rename entry costs two
+// paths. 16 MiB is a blast-radius bound on that, well past any tree this can
+// answer usefully about, and it is what makes the truncation guard below
+// reachable at all (#2100).
+const MAX_GIT_STATUS_OUTPUT_BYTES = 16 * 1024 * 1024;
 export async function captureFileStats(root, options = {}) {
     const budgetMs = options.budgetMs ?? 50;
     try {
@@ -152,6 +161,7 @@ const gitRepoMemo = new Map();
 export function resetOpaqueMutationState() {
     getOpaqueBaselineStore().takeAllForTest();
     gitRepoMemo.clear();
+    gitToplevelMemo.clear();
 }
 /** Cached git-worktree probe (repos don't stop being git mid-session). */
 export async function isGitWorktree(root) {
@@ -166,14 +176,141 @@ export async function isGitWorktree(root) {
 }
 export function _resetGitWorktreeMemoForTests() {
     gitRepoMemo.clear();
+    gitToplevelMemo.clear();
+}
+const gitToplevelMemo = new Map();
+/**
+ * The root of the working tree `root` belongs to, or `undefined` when it is
+ * not inside one (#2007).
+ *
+ * This is WORKTREE IDENTITY, which path containment cannot supply. A linked
+ * worktree lives at a path nested under the main checkout — this repo keeps
+ * agent worktrees under `.claude/worktrees/` — yet shares no working files
+ * with it. `--show-toplevel` answers which tree a directory really belongs
+ * to, so two directories are the same checkout when, and only when, their
+ * toplevels match.
+ *
+ * Memoized beside `isGitWorktree`, and cleared by the same
+ * `resetOpaqueMutationState` session boundary, so it cannot become a
+ * process-lifetime latch (catalog shape 17). `undefined` is a real cached
+ * answer, so the memo is probed with `has`, never by truthiness.
+ */
+export async function resolveGitToplevel(root) {
+    const key = normalizeMapKey(path.resolve(root));
+    if (gitToplevelMemo.has(key))
+        return gitToplevelMemo.get(key);
+    const result = await safeSpawnAsync("git", ["rev-parse", "--show-toplevel"], {
+        cwd: root,
+        timeout: 3000,
+    });
+    const toplevel = !result.error && result.status === 0 && result.stdout?.trim()
+        ? result.stdout.trim()
+        : undefined;
+    gitToplevelMemo.set(key, toplevel);
+    return toplevel;
+}
+const UNMERGED_PORCELAIN_STATUSES = new Set([
+    "DD",
+    "AU",
+    "UD",
+    "UA",
+    "DU",
+    "AA",
+    "UU",
+]);
+/**
+ * Git's Porcelain v1 ordinary-status table, not a Cartesian product. A clean
+ * index permits worktree M/T/D, intent-to-add A, and worktree rename/copy R/C.
+ * M/T/A/R/C may pair with blank/M/T/D; staged deletion is D<space>, DR or DC.
+ * Broaden only with Git docs and a real-status probe.
+ *
+ * Membership no longer decides pass/fail for a whole command - an absent pair
+ * is counted and kept, not fatal (#2060). It still decides which entries the
+ * failed-integration filter may treat as "clean index-only incoming", so an
+ * unknown pair is never silently classified as someone else's content.
+ */
+const LEGAL_ORDINARY_PORCELAIN_STATUSES = new Set([
+    " M",
+    " T",
+    " D",
+    " A",
+    " R",
+    " C",
+    "DR",
+    "DC",
+    "M ",
+    "MM",
+    "MT",
+    "MD",
+    "T ",
+    "TM",
+    "TT",
+    "TD",
+    "A ",
+    "AM",
+    "AT",
+    "AD",
+    "D ",
+    "R ",
+    "RM",
+    "RT",
+    "RD",
+    "C ",
+    "CM",
+    "CT",
+    "CD",
+]);
+function isUnmergedStatus(status) {
+    return UNMERGED_PORCELAIN_STATUSES.has(status);
+}
+/** An XY pair this module can classify. Unknown pairs are kept, not rejected. */
+function isKnownPorcelainStatus(status) {
+    return (status === "??" ||
+        status === "!!" ||
+        isUnmergedStatus(status) ||
+        LEGAL_ORDINARY_PORCELAIN_STATUSES.has(status));
+}
+/**
+ * The characters Git's short format can put in an XY pair. This is the real
+ * fail-closed line (#2060): output whose status field is outside this alphabet,
+ * or carries no status at all, is not Porcelain v1 and nothing in it can be
+ * trusted. An in-alphabet pair we happen not to have tabulated is a gap in our
+ * table, so voiding the whole command's recovery for it would throw away every
+ * other path - the read-guard hole this subsystem exists to close.
+ */
+const PORCELAIN_STATUS_CHARS = /^[ MTADRCU?!]{2}$/;
+function isStructurallyValidStatus(status) {
+    return PORCELAIN_STATUS_CHARS.test(status) && status.trim() !== "";
 }
 /**
  * Files dirty in the working tree whose mtime falls inside
  * [startedAt - tolerance, now]. Porcelain -z parsing handles renames
- * (the NEW path is reported; the old path token is skipped).
+ * (the NEW path is reported; the old path token is skipped before filtering).
  */
-export async function recoverOpaqueChangesViaGit(root, startedAt) {
-    const result = await safeSpawnAsync("git", ["status", "--porcelain", "-z", "--untracked-files=all"], { cwd: root, timeout: 5000 });
+export async function recoverOpaqueChangesViaGit(root, startedAt, options = {}) {
+    const result = await safeSpawnAsync("git", ["status", "--porcelain", "-z", "--untracked-files=all"], {
+        cwd: root,
+        timeout: 5000,
+        maxOutputBytes: MAX_GIT_STATUS_OUTPUT_BYTES,
+    });
+    // #2060: safe-spawn caps stdout before the child finishes. A capped listing
+    // is a PREFIX of the truth, so reading it as complete would report every
+    // path the cap removed as unchanged.
+    //
+    // #2100: FIRST, ahead of the git-failed check. Hitting the cap makes
+    // safe-spawn SIGTERM the child, so the result also carries an error and a
+    // null status — read in the other order every cap kill reported as
+    // "git-failed" and this guard could never speak. `truncatedByOutputCap`
+    // leaves a timed-out or aborted read to the git-failed branch below, which
+    // is the honest answer for those.
+    if (truncatedByOutputCap(result)) {
+        return {
+            verdict: "unknown",
+            paths: [],
+            unknownReason: "git-status-parse-failed",
+            scannedCount: 0,
+        };
+    }
     if (result.error || (result.status !== 0 && result.status !== null)) {
         return {
             verdict: "unknown",
@@ -182,12 +319,19 @@ export async function recoverOpaqueChangesViaGit(root, startedAt) {
             scannedCount: 0,
         };
     }
-    const floorMs = startedAt - OPAQUE_MTIME_TOLERANCE_MS;
     const raw = result.stdout ?? "";
-    const tokens = raw.split("\0");
-    const paths = [];
+    if (raw && !raw.endsWith("\0")) {
+        return {
+            verdict: "unknown",
+            paths: [],
+            unknownReason: "git-status-parse-failed",
+            scannedCount: 0,
+        };
+    }
+    const entries = [];
+    let unknownStatusCount = 0;
     let skipNext = false; // rename's OLD path follows its NEW path
-    for (const token of tokens) {
+    for (const token of raw.split("\0")) {
         if (!token)
             continue;
         if (skipNext) {
@@ -195,26 +339,96 @@ export async function recoverOpaqueChangesViaGit(root, startedAt) {
             continue;
         }
         // Each entry: two status chars, one space, then the path.
-        if (token.length < 4 || token[2] !== " ")
-            continue;
+        if (token.length < 4 || token[2] !== " ") {
+            return {
+                verdict: "unknown",
+                paths: [],
+                unknownReason: "git-status-parse-failed",
+                scannedCount: 0,
+            };
+        }
         const status = token.slice(0, 2);
         const relPath = token.slice(3);
+        if (!isStructurallyValidStatus(status) || !relPath) {
+            return {
+                verdict: "unknown",
+                paths: [],
+                unknownReason: "git-status-parse-failed",
+                scannedCount: 0,
+            };
+        }
+        if (!isKnownPorcelainStatus(status))
+            unknownStatusCount += 1;
         if (status.includes("R") || status.includes("C"))
             skipNext = true;
-        const abs = path.resolve(root, relPath);
+        entries.push({ status, absPath: path.resolve(root, relPath) });
+    }
+    if (skipNext) {
+        return {
+            verdict: "unknown",
+            paths: [],
+            unknownReason: "git-status-parse-failed",
+            scannedCount: 0,
+        };
+    }
+    const hasUnmerged = entries.some((entry) => isUnmergedStatus(entry.status));
+    const floorMs = startedAt - OPAQUE_MTIME_TOLERANCE_MS;
+    // Kernel "stale" = modified AFTER the window floor - exactly the writes
+    // this command may have authored, so exactly the entries that would be
+    // dispatched absent any other filtering.
+    async function isInWindow(absPath) {
         try {
-            const stat = await fs.promises.stat(abs);
-            if (stat.isFile() &&
+            const stat = await fs.promises.stat(absPath);
+            return (stat.isFile() &&
                 freshnessFromMtime({ mtimeMs: stat.mtimeMs, referenceMs: floorMs })
-                    .verdict === "stale") {
-                // Kernel "stale" = modified AFTER the window floor - exactly the
-                // writes this command may have authored.
-                paths.push(normalizeMapKey(abs));
-            }
+                    .verdict === "stale");
         }
         catch {
             // Deleted or vanished: deletions are deliberately unreported.
+            return false;
+        }
+    }
+    let excludedIncomingCount = 0;
+    let candidates = entries;
+    if (options.excludeIndexOnlyWhenUnmerged === true && hasUnmerged) {
+        // Clean index-only (`XY` with a blank Y) means "staged, worktree matches
+        // the index". After a failed integration that content came from the other
+        // side, never from the agent: merge, rebase, cherry-pick and revert all
+        // REFUSE to start against a dirty index, so no agent-staged file can be
+        // sitting here (#2060 F5, probed on git 2.55). An unknown-but-well-formed
+        // pair is NOT classified as incoming - capture wins when in doubt.
+        // Scope: the refusal argument covers content staged BEFORE the
+        // integration started. Content staged mid-call, after the conflict
+        // began, is indistinguishable from incoming and is excluded too; the
+        // excluded count below is the visibility for that edge.
+        // A blank Y already excludes every unmerged pair (all seven are two
+        // letters), so this needs no separate unmerged term.
+        const kept = [];
+        for (const entry of entries) {
+            const cleanIndexOnly = entry.status[1] === " " && isKnownPorcelainStatus(entry.status);
+            if (!cleanIndexOnly) {
+                kept.push(entry);
+                continue;
+            }
+            // #2081: only count entries the mtime window would otherwise have
+            // dispatched. A long-staged clean-index path outside the window was
+            // never going to be reported, so dropping it here is not suppression.
+            if (await isInWindow(entry.absPath))
+                excludedIncomingCount += 1;
         }
+        candidates = kept;
+    }
+    const paths = [];
+    for (const { absPath } of candidates) {
+        if (await isInWindow(absPath))
+            paths.push(normalizeMapKey(absPath));
     }
-    return { verdict: "recovered", paths, scannedCount: paths.length };
+    return {
+        verdict: "recovered",
+        paths,
+        scannedCount: paths.length,
+        // Omitted when zero so the common outcome keeps one shape.
+        ...(excludedIncomingCount > 0 ? { excludedIncomingCount } : {}),
+        ...(unknownStatusCount > 0 ? { unknownStatusCount } : {}),
+    };
 }

package/node_modules/pi-lens/dist/clients/package-manager.js

@@ -18,6 +18,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { classifyProbeFailure, createAvailabilityLatch, isTransientDecision, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { createAvailabilityProbeFlight } from "./availability-probe-flight.js";
 /**
  * Fallback preference when nothing is declared (or the declared manager is
  * missing). npm first for maximum compatibility; bun last. A project lockfile
@@ -29,6 +30,7 @@ const PREFERENCE = [
     "yarn",
     "bun",
 ];
+const packageManagerProbeFlights = createAvailabilityProbeFlight();
 function onWindows() {
     return process.platform === "win32";
 }
@@ -94,7 +96,6 @@ const PROBE_TIMEOUT_MS = 5_000;
  * a timeout, abort or host stall expires on a cooldown and is re-probed.
  */
 const availabilityLatches = new Map();
-const inFlightProbes = new Map();
 function getLatch(pm) {
     let latch = availabilityLatches.get(pm);
     if (!latch) {
@@ -128,6 +129,7 @@ async function probeAvailability(pm) {
             latched: true,
             hostStallMs,
             budgetMs: PROBE_TIMEOUT_MS,
+            classifiedBy: "probe",
         });
         return true;
     }
@@ -181,22 +183,8 @@ function isAvailable(pm, onTransient) {
         return Promise.resolve(reportIfTransient(memo));
     // A verdict can now expire, so concurrent callers arriving just after a
     // cooldown must share ONE probe rather than each spawning their own.
-    const inFlight = inFlightProbes.get(pm);
-    if (inFlight)
-        return inFlight.then(reportIfTransient);
-    // #1653 review F1: a probe started before a session reset can settle AFTER
-    // a later session's own probe for the same manager is already in flight.
-    // An unconditional delete-by-key would evict that NEWER entry out from
-    // under it, so a third caller in the gap finds nothing in-flight and
-    // spawns a duplicate. Only remove the entry if it is still THIS call's
-    // promise — the same identity guard `resolveMadge` uses in
-    // dependency-checker.ts for the equivalent race.
-    const probe = probeAvailability(pm).finally(() => {
-        if (inFlightProbes.get(pm) === probe)
-            inFlightProbes.delete(pm);
-    });
-    inFlightProbes.set(pm, probe);
-    return probe.then(reportIfTransient);
+    const shared = packageManagerProbeFlights.run(`package-manager:${pm}`, () => probeAvailability(pm));
+    return shared.promise.then(reportIfTransient);
 }
 /**
  * Clear the process-wide availability cache: pnpm/yarn/bun/npm each sit
@@ -213,7 +201,7 @@ function isAvailable(pm, onTransient) {
  */
 export function _resetPackageManagerCache() {
     availabilityLatches.clear();
-    inFlightProbes.clear();
+    packageManagerProbeFlights.clear();
 }
 // ============================================================================
 // RESOLUTION

package/node_modules/pi-lens/dist/clients/path-keyed-map.js

@@ -48,7 +48,20 @@ export class PathKeyedMap {
         return this;
     }
     delete(path) {
-        return this.store.delete(this.normalize(path));
+        if (this.store.delete(this.normalize(path)))
+            return true;
+        // A filesystem-aware normalizer can change after the keyed file is
+        // deleted (for example, real on-disk casing becomes a lowercased missing
+        // tail on Windows). The caller may still hold the exact display key it
+        // received from this map. Honor that captured identity without deriving a
+        // second path form, so deletion remains possible across existence changes.
+        for (const [key, entry] of this.store) {
+            if (entry.displayPath !== path)
+                continue;
+            this.store.delete(key);
+            return true;
+        }
+        return false;
     }
     clear() {
         this.store.clear();

package/node_modules/pi-lens/dist/clients/path-utils.js

@@ -110,6 +110,38 @@ export function normalizeFilePath(filePath) {
         }
     }
 }
+/**
+ * Normalize a logged `filePath`/`cwd` value, but ONLY when it is already a
+ * fully-qualified path (#2219, the #2141 class's sibling loggers). Several
+ * NDJSON log-entry types reuse a `filePath`-typed field for non-path
+ * sentinels alongside genuine paths — `"<quiet-window>"` in
+ * `cascade-logger.ts`, `"<tree-sitter>"` in `tree-sitter-logger.ts`, a shell
+ * command or an empty placeholder in `latency-logger.ts`. `normalizeFilePath`
+ * resolves a relative-looking string against the CURRENT process cwd (see
+ * `resolveNonExisting` above), so running it over one of those sentinels
+ * would silently corrupt it into `"<repoRoot>/<quiet-window>"` instead of
+ * normalizing it. Only a value that is already fully qualified can be the
+ * #2141 mixed-raw/normalized-path defect; anything else is passed through
+ * unchanged.
+ *
+ * #2229 review round 1, F1: this classifier checks BOTH host shapes
+ * (`isFullyQualifiedWin32(value) || isFullyQualifiedPosix(value)`), not
+ * `isFullyQualified(value)` (host-dispatched on `process.platform`). A
+ * Windows-shaped absolute path (`C:\Users\...`) is exactly the log payload
+ * this fix exists to normalize, but `isFullyQualified` on Linux CI routes to
+ * `isFullyQualifiedPosix`, which rejects it (no leading `/`) — so on Linux
+ * the guard silently no-ops for the very inputs the #2141 defect produces,
+ * passing the raw backslash form straight through. Checking both shapes
+ * makes the classifier's answer for a given STRING independent of which OS
+ * is asking; `normalizeFilePath` itself still branches on `process.platform`
+ * for how the file is resolved, but whether to normalize at all no longer
+ * does (AGENTS.md shape 2, the #1024/#1150 OS-divergence class).
+ */
+export function normalizeLoggedPath(value) {
+    return isFullyQualifiedWin32(value) || isFullyQualifiedPosix(value)
+        ? normalizeFilePath(value)
+        : value;
+}
 /**
  * Resolve a non-existing path by finding the nearest existing parent,
  * getting its canonical casing, then appending the non-existent parts lowercased.

package/node_modules/pi-lens/dist/clients/pipeline.js

@@ -25,7 +25,6 @@ import { classifyProbeFailure, createAvailabilityChecker, createAvailabilityLatc
 import { findDetektConfig } from "./dispatch/runners/detekt.js";
 import { detectFileKind, getFileKindLabel } from "./file-kinds.js";
 import { detectFileChangedAfterCommand, getProjectIgnoreMatcher, isExcludedDirName, } from "./file-utils.js";
-import { isInSpawnTimeoutCooldown } from "./spawn-timeout-cooldown.js";
 import { logLatency } from "./latency-logger.js";
 import { emitLensAnalysisComplete } from "./lens-events.js";
 import { publishFilesTouched } from "./bus-publish.js";
@@ -338,17 +337,10 @@ async function tryDetektFix(filePath, cwd) {
     const absPath = path.resolve(cwd, filePath);
     return detectFileChangedAfterCommand(filePath, cmd, ["--auto-correct", "--input", absPath, "--config", configPath], cwd, [1, 2]);
 }
-// Exported for #1995 cooldown wiring tests: the guard on this lane is
-// one of three mutation-proof surfaces.
 export async function tryMarkdownlintFix(filePath, cwd) {
     const cmd = await resolveToolCommandWithInstallFallback(cwd, "markdownlint");
     if (!cmd)
         return 0;
-    // #1995: skip the spawn entirely when the command is cooling down after a
-    // timeout — detectFileChangedAfterCommand also self-guards, but a wedged
-    // command should not even reach a second budget in the hot loop.
-    if (isInSpawnTimeoutCooldown(cmd))
-        return 0;
     // Shared config-args seam (#1247): the lint runner consumes the same
     // builder, so the bare --fix here can never fall back to markdownlint's
     // default all-rules-on config again (the whole-file CHANGELOG/AGENTS

package/node_modules/pi-lens/dist/clients/process-singletons.js

@@ -0,0 +1,210 @@
+/**
+ * Process singletons — state that must exist ONCE PER PROCESS, not once per
+ * module evaluation (#2146).
+ *
+ * WHY THIS MODULE EXISTS. pi evaluates the pi-lens module graph more than once
+ * in a single process: dogfood pass 3 measured one pid emitting `host_boot`
+ * nine times, another four times. Source and compiled entries load through
+ * separate module graphs, in-process subagent sessions re-enter the extension
+ * loader, and vitest re-evaluates modules on `vi.resetModules()`. Every
+ * module-scope `let` therefore exists N times, and any state whose CORRECTNESS
+ * depends on being the process's only copy silently breaks:
+ *
+ *  - `session-lifecycle.ts`'s registered primary: evaluation 2 starts with an
+ *    empty registration, classifies a subagent temp root as `primary`, and runs
+ *    the full session_start battery the #473/#2129/#2133 guard exists to
+ *    decline. Measured cost: three identical word-index full rebuilds in one
+ *    90s burst, 240.8s of CPU for one index.
+ *  - `instance-registry.ts`'s mutation tail: N tails are N concurrent
+ *    read-modify-write cycles over one `instances.json`. Measured: three
+ *    `instance-registry-corrupt` records in a 9s window, with two project roots
+ *    and one live instance lost from the file.
+ *
+ * PRECEDENT, both in-repo and both cited rather than invented:
+ *  - `clients/runtime-session.ts:1826` hangs `__piLensFirstSessionDone` /
+ *    `__piLensWarmupScheduled` on `globalThis` for exactly this reason.
+ *  - `clients/ndjson-logger.ts:125` does the versioned form: a
+ *    `Symbol.for()` key, a schema string, a version number, and an explicit
+ *    adopt-or-decline decision for a state written by a different build.
+ *
+ * This module generalizes the second one so each state family gets the same
+ * treatment without re-deriving the protocol per site.
+ *
+ * WHAT BELONGS HERE. Only state that is WRONG when duplicated: process-wide
+ * registrations, serialization points, and once-per-process latches. A memo or
+ * cache that re-derives the same answer from a stable source (an env read, a
+ * host probe) is merely wasteful when duplicated, not wrong, and stays at
+ * module scope — see the class-sweep table in the #2146 PR body for the
+ * per-family verdicts.
+ *
+ * VERSIONING AND THE OLDER-SHAPE FALLBACK. Two builds can meet in one process:
+ * a stale `dist/` graph and a fresh source graph, or an extension reload after
+ * an upgrade. Each family carries its own `version`. The rule is
+ * adopt-if-compatible, reset otherwise:
+ *
+ *  - Same schema and same version -> ADOPT the existing value. This is the
+ *    common case and the whole point of the module.
+ *  - Anything else (missing schema, different schema, older version, NEWER
+ *    version) -> do NOT adopt. A shape this build cannot read is not safely
+ *    readable in either direction, so guessing is worse than starting clean.
+ *    The cell is replaced with a fresh value from `create()` and ONE bounded
+ *    `process-singleton-reset` entry is logged per family, so a nine-evaluation
+ *    process still reports at most one row per family. Behavior after a reset is
+ *    exactly today's module-scope behavior for that family, which is the
+ *    fail-safe direction.
+ *
+ * The container key itself is versioned (`SINGLETON_HOST_KEY`). A future change
+ * to the CONTAINER shape bumps the key, so an old container is simply not
+ * found rather than mis-read.
+ */
+/**
+ * STATIC IMPORTS: none, deliberately. This module is a dependency leaf.
+ *
+ * It cannot import the degradation ledger. `instance-registry.ts` imports this
+ * module, and the ledger reaches `instance-reaper.ts` (through `extension-log`
+ * -> `file-utils` -> `git-tracked-ignore` -> `safe-spawn` -> `resource-sampler`),
+ * and `instance-reaper` imports the registry back. Any edge from here to the
+ * ledger closes a `no-client-cycles` cycle, which CI's dependency-boundaries
+ * lane rejects. A dynamic import does not help: the rule excludes
+ * `dynamic-import` only on the edge it evaluates, not on the intermediate edges
+ * of the cycle it walks.
+ *
+ * So the direction is inverted, exactly as `ndjson-logger.ts` already does for
+ * its own sink-write failures: this module keeps a bounded reset log, and
+ * `degradation-ledger.ts` PULLS it at read time through
+ * {@link getProcessSingletonResets} and folds it into `getDegradationSummary()`.
+ * The record still reaches `pilens_health`, with no import from here.
+ */
+/** Bump only when the CONTAINER shape changes, never for a family's shape. */
+const SINGLETON_HOST_KEY = Symbol.for("pi-lens.process-singletons.v1");
+const SINGLETON_SCHEMA = "pi-lens.process-singletons";
+/** Degradation kind emitted when an incompatible cell is discarded. */
+export const PROCESS_SINGLETON_RESET_KIND = "process-singleton-reset";
+const singletonHost = globalThis;
+/**
+ * The process's one container. Deliberately created on first read rather than
+ * at module scope of a single graph: whichever evaluation runs first wins, and
+ * every later evaluation adopts it.
+ */
+function container() {
+    const existing = singletonHost[SINGLETON_HOST_KEY];
+    if (existing instanceof Map)
+        return existing;
+    const fresh = new Map();
+    singletonHost[SINGLETON_HOST_KEY] = fresh;
+    return fresh;
+}
+function isAdoptable(cell, version) {
+    if (!cell || typeof cell !== "object")
+        return false;
+    const candidate = cell;
+    return (candidate.schema === SINGLETON_SCHEMA &&
+        candidate.version === version &&
+        candidate.value !== undefined);
+}
+/** One bounded reset log per process, capped so a pathological build pair
+ * cannot grow it without limit. */
+export const PROCESS_SINGLETON_RESET_LOG_FAMILY = "process-singleton-reset-log";
+const RESET_LOG_FAMILY = PROCESS_SINGLETON_RESET_LOG_FAMILY;
+const RESET_LOG_VERSION = 1;
+const RESET_LOG_CAP = 16;
+function resetLog() {
+    return getProcessSingleton(RESET_LOG_FAMILY, RESET_LOG_VERSION, () => ({
+        entries: [],
+    }));
+}
+/**
+ * Record that an incompatible cell was discarded. Bounded twice: once per
+ * family (a nine-evaluation process logs at most one entry per family) and once
+ * overall by {@link RESET_LOG_CAP}.
+ */
+function recordIncompatibleCell(family, wantedVersion, found) {
+    // The reset log is itself a family, so recording ITS reset would recurse.
+    // Dropping that one record is correct: the log it would be written to is the
+    // thing being discarded.
+    if (family === RESET_LOG_FAMILY)
+        return;
+    const log = resetLog();
+    if (log.entries.some((entry) => entry.family === family))
+        return;
+    if (log.entries.length >= RESET_LOG_CAP)
+        return;
+    log.entries.push({
+        family,
+        reason: `incompatible process singleton discarded (found schema=${String(found.schema)} ` +
+            `version=${String(found.version)}, this build wants schema=${SINGLETON_SCHEMA} ` +
+            `version=${wantedVersion})`,
+    });
+}
+/**
+ * Read-time view for `degradation-ledger.ts` (see the header). Never performs
+ * I/O and never throws, so folding it into a health summary is free.
+ */
+export function getProcessSingletonResets() {
+    return resetLog().entries.map((entry) => ({ ...entry }));
+}
+/**
+ * Return the process-wide value for `family`, creating it on the first
+ * evaluation that asks and adopting it on every later one.
+ *
+ * `version` describes the SHAPE of the value `create()` builds. Bump it when a
+ * build changes that shape, so a graph carrying the old shape is discarded
+ * instead of mis-read (see the module docstring's fallback rules).
+ *
+ * `create()` runs at most once per process per family, unless an incompatible
+ * cell forced a reset.
+ *
+ * `onIncompatible` is for values that own external resources. It runs before
+ * the cell is replaced, so the owner can tear those resources down safely.
+ */
+export function getProcessSingleton(family, version, create, onIncompatible) {
+    const cells = container();
+    const existing = cells.get(family);
+    if (isAdoptable(existing, version))
+        return existing.value;
+    if (existing !== undefined) {
+        // An incompatible cell from another build. One bounded row per family:
+        // nine evaluations must not write nine records (AGENTS.md's bounded-record
+        // rule; `recordDegradationOnce` keys on kind + subject).
+        recordIncompatibleCell(family, version, existing);
+        onIncompatible?.(existing.value);
+    }
+    const value = create();
+    cells.set(family, { schema: SINGLETON_SCHEMA, version, value });
+    return value;
+}
+/**
+ * Test-only: drop the process-wide container so the next
+ * {@link getProcessSingleton} call rebuilds every family from `create()`.
+ *
+ * This clears the GLOBAL state, not a module-local copy — a reset that only
+ * cleared module scope would be the very defect this module fixes, and would
+ * make every suite that relies on isolation pass vacuously (catalog shape 7).
+ */
+export function _resetProcessSingletonsForTests() {
+    singletonHost[SINGLETON_HOST_KEY] = new Map();
+}
+/**
+ * Test-only: install a raw cell so a suite can exercise the older/newer-shape
+ * fallback without needing two real builds in one process.
+ */
+export function _seedProcessSingletonCellForTests(family, cell) {
+    container().set(family, cell);
+}
+// --- Module-evaluation ordinal (#2146 observability) ---
+const EVALUATION_ORDINAL_FAMILY = "module-evaluation-ordinal";
+const EVALUATION_ORDINAL_VERSION = 1;
+/**
+ * How many times this process has evaluated the pi-lens module graph, 1-based.
+ *
+ * Called once, at module scope of `clients/startup-timing.ts`, so the number it
+ * returns is the evaluation count of the graph that contains the extension
+ * entry. It is carried on `host_boot.metadata.evaluationOrdinal` so a multi-eval
+ * process is greppable from `latency.log` instead of having to be inferred by
+ * counting `host_boot` lines per pid — the observability gap #2146 names.
+ */
+export function nextModuleEvaluationOrdinal() {
+    const state = getProcessSingleton(EVALUATION_ORDINAL_FAMILY, EVALUATION_ORDINAL_VERSION, () => ({ evaluations: 0 }));
+    state.evaluations += 1;
+    return state.evaluations;
+}