@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/shared-checkout-guard.js

@@ -0,0 +1,338 @@
+/**
+ * Shared-checkout WIP guard (#2007).
+ *
+ * THE HAZARD. Several agent sessions can run against ONE checkout. Nothing
+ * in git binds a session to a directory, so when one session runs
+ * `git checkout <branch>`, git overwrites the tracked files another live
+ * session was editing. The work is not recoverable: it was never committed
+ * and never stashed. The reported incident lost uncommitted edits to three
+ * files between two observations minutes apart.
+ *
+ * THE ANSWER IS REFUSAL, NOT RESCUE. An auto-stash would be invisible
+ * machinery that moves another session's work somewhere it did not ask for,
+ * and `git stash` is repo-global across worktrees, so the rescue would be a
+ * second instance of the same defect. This guard instead DECLINES the
+ * command and says who else is here. The operator resolves it the way the
+ * design contract already says to: commit, or take a dedicated
+ * `git worktree`.
+ *
+ * THREE FACTS MUST ALL HOLD BEFORE ANYTHING IS DECLINED, cheapest first:
+ *
+ *   1. The bash input really invokes a git verb that rewrites the working
+ *      tree, read from git's own COMMAND POSITION. Pure string work, no I/O —
+ *      see `WORKTREE_MUTATING_GIT_MATCHER`. The directory judged is the one
+ *      the invocation TARGETS, which `-C` and `--work-tree` can move away
+ *      from the caller's cwd.
+ *   2. Another live pi-lens session is in the SAME WORKING TREE.
+ *      `selectLivePeerInstances` (clients/instance-registry.ts) owns liveness
+ *      and is the single source of truth for it; warm-attach reads the same
+ *      predicate in `"exact"` mode. Path containment alone is not identity
+ *      here, in either direction: a peer at the repo root and a command run
+ *      from a subdirectory DO share one tree, while a linked worktree nested
+ *      under the main checkout shares nothing with it. Containment against
+ *      the toplevel is the pre-filter; `git rev-parse --show-toplevel` is the
+ *      decision. No peer means nothing to protect.
+ *   3. The working tree actually carries uncommitted work. A clean tree can
+ *      be switched freely.
+ *
+ * That ordering is the cost story: the two `git` probes run only after a
+ * genuine worktree-mutating command in a genuinely shared checkout, which is
+ * rare. Ordinary bash traffic pays one string classification.
+ *
+ * UNKNOWN IS NOT CLEAN (catalog shape 10). When `git status` cannot answer,
+ * the guard declines with its OWN reason rather than assuming the tree is
+ * clean, and records a counted degradation so a repeatedly broken probe is
+ * visible instead of silently permissive.
+ *
+ * The TOPLEVEL probes fail open, deliberately and asymmetrically to the
+ * dirtiness probe: a candidate peer whose `git rev-parse --show-toplevel`
+ * fails is dropped, and the allow record folds into `no_peer_session`; a cwd
+ * whose probe fails folds into `not_a_git_worktree`. Both read as facts in
+ * latency.log when they may be a timeout or a lock. Chosen because failing
+ * closed here would let a broken probe block every branch switch; the cost is
+ * that those two reasons are not distinguishable from the genuine cases.
+ *
+ * NO LATCHES HERE (catalog shape 17). Every decision is recomputed from the
+ * registry and the tree. Repeat-suppression for telemetry lives in the
+ * degradation ledger, which already re-arms at `session_start`.
+ */
+import { emitBounded } from "./bounded-telemetry.js";
+import { collectGitInvocations, detectGuardedGitVerb, matchGitVerbAtCommandPosition, resolveGitTargetDirectory, } from "./git-guard.js";
+import { getInstanceRoots, readInstanceRegistry, selectLivePeerInstances, } from "./instance-registry.js";
+import { realIsPidAlive } from "./instance-reaper.js";
+import { logLatency } from "./latency-logger.js";
+import { resolveGitToplevel } from "./opaque-mutation-scan.js";
+import { normalizeFilePath } from "./path-utils.js";
+import { safeSpawnAsync } from "./safe-spawn.js";
+import { truncatedByOutputCap } from "./spawn-output-cap.js";
+/** Verbs that rewrite tracked files unconditionally. */
+const ALWAYS_MUTATING_VERBS = new Set([
+    "checkout",
+    "switch",
+    "restore",
+    "merge",
+    "rebase",
+    "pull",
+    "cherry-pick",
+    "revert",
+]);
+/** `git reset` touches the working tree only in these modes. */
+const RESET_WORKTREE_MODES = new Set([
+    "--hard",
+    "--merge",
+    "--keep",
+]);
+/** `git stash` subcommands that only read. Everything else moves files. */
+const READ_ONLY_STASH_SUBCOMMANDS = new Set([
+    "list",
+    "show",
+]);
+/**
+ * `git clean` in dry-run mode reports and deletes nothing.
+ *
+ * Short flags CLUSTER (`git clean -nfd` is `-n -f -d`), so an exact-token set
+ * would read `-nfd` as mutating and decline a command that touches nothing.
+ * Match the letter inside any short cluster, and `--dry-run` exactly.
+ */
+function isCleanDryRun(argsAfterVerb) {
+    return argsAfterVerb.some((arg) => arg === "--dry-run" ||
+        (arg.startsWith("-") && !arg.startsWith("--") && arg.includes("n")));
+}
+/**
+ * The verb question for the shared-checkout guard. Every other part of the
+ * classification (wrappers, `$IFS`, substitutions, PATHEXT, text consumers)
+ * is the #1063 git-guard machinery, reused rather than re-implemented.
+ *
+ * `indirectAlwaysMatches` is FALSE here on purpose. The commit gate is a
+ * policy an agent may want to evade, so it fails closed on any indirect
+ * `git`. This guard protects an agent from its own accident, so failing
+ * closed on `xargs git status` would cost far more than it saves; the
+ * indirect path stays armed only when the argv also carries a governed verb.
+ *
+ * DELIBERATELY OUT OF SCOPE: `git apply` and `git am`. They add the caller's
+ * own patch on top of the tree and fail loudly into `.rej` files rather than
+ * discarding tracked content wholesale, and `git apply` is the sanctioned
+ * replacement for the forbidden `git stash`. Blocking it would push
+ * operators back toward stash.
+ */
+export const WORKTREE_MUTATING_GIT_MATCHER = {
+    id: "worktree-mutating",
+    indirectAlwaysMatches: false,
+    // `git checkout --help` opens documentation and changes nothing. This
+    // guard can afford to read a leading help flag as documentation; the
+    // commit gate cannot — see `suppressPostVerbHelp`'s own docstring.
+    suppressPostVerbHelp: true,
+    matchesVerb(verb, argsAfterVerb) {
+        if (ALWAYS_MUTATING_VERBS.has(verb))
+            return true;
+        if (verb === "reset") {
+            return argsAfterVerb.some((arg) => RESET_WORKTREE_MODES.has(arg));
+        }
+        if (verb === "stash") {
+            const subcommand = argsAfterVerb.find((arg) => !arg.startsWith("-"));
+            return (subcommand === undefined || !READ_ONLY_STASH_SUBCOMMANDS.has(subcommand));
+        }
+        if (verb === "clean")
+            return !isCleanDryRun(argsAfterVerb);
+        return false;
+    },
+};
+/** True when this one git invocation's subcommand rewrites tracked files. */
+function matchesWorktreeMutatingVerb(gitTokens) {
+    return matchGitVerbAtCommandPosition(gitTokens, WORKTREE_MUTATING_GIT_MATCHER);
+}
+/** True when this bash input runs a git verb that rewrites tracked files. */
+export function isWorktreeMutatingGitAttempt(toolName, input) {
+    return detectGuardedGitVerb(toolName, input, WORKTREE_MUTATING_GIT_MATCHER);
+}
+// A `git status --porcelain --untracked-files=all` listing over a huge
+// untracked tree (an unignored `node_modules`, a vendored dependency dump) can
+// run to many MiB. This is a blast-radius bound on a wedged or runaway git, not
+// a working limit; 16 MiB matches the sibling git-status probes
+// (`opaque-mutation-scan.ts`'s `MAX_GIT_STATUS_OUTPUT_BYTES` and
+// `git-tracked-ignore.ts`'s `MAX_LS_FILES_OUTPUT_BYTES`, both 16 MiB). Without
+// it `outputTruncated` can never fire, so the truncation guard below was
+// dormant (#2100 F3).
+const MAX_GIT_STATUS_OUTPUT_BYTES = 16 * 1024 * 1024;
+/**
+ * Ask git whether the working tree carries uncommitted work.
+ *
+ * Deliberately narrower than `recoverOpaqueChangesViaGit`: that function
+ * answers WHICH files changed inside a time window and stats each one, which
+ * drops deletions and costs one stat per entry. Here the only question is
+ * whether ANY entry exists, so a truncated listing is still a definite
+ * `dirty` — a prefix of dirt is dirt.
+ */
+export async function probeWorkingTreeState(root) {
+    const result = await safeSpawnAsync("git", ["status", "--porcelain", "--untracked-files=all"], { cwd: root, timeout: 5000, maxOutputBytes: MAX_GIT_STATUS_OUTPUT_BYTES });
+    // Read truncation FIRST (#2100 F3), through the shared seam that
+    // git-tracked-ignore uses. Reaching the cap makes safe-spawn kill the tree,
+    // which settles as `error` + null status on POSIX and status 1 on Windows —
+    // both of which the failure check below reads as `unknown`. So a definite
+    // dirty (we captured 16 MiB of porcelain) was being downgraded to `unknown`
+    // the moment the cap fired. Timeout and abort keep their own classification
+    // and fall through to `unknown`, since a hung git cannot prove dirtiness.
+    if (truncatedByOutputCap(result))
+        return "dirty";
+    if (result.error || (result.status !== 0 && result.status !== null)) {
+        return "unknown";
+    }
+    return (result.stdout ?? "").trim().length > 0 ? "dirty" : "clean";
+}
+function logAllow(root, reasonCategory) {
+    logLatency({
+        type: "phase",
+        toolName: "shared-checkout-guard",
+        phase: "shared_checkout_guard_allow",
+        filePath: root,
+        durationMs: 0,
+        metadata: { decision: "allowed", reasonCategory },
+    });
+}
+function describePeers(peers) {
+    const pids = peers.slice(0, 4).map((peer) => peer.pid);
+    const suffix = peers.length > pids.length ? ", …" : "";
+    return `${peers.length} other live pi-lens session${peers.length === 1 ? "" : "s"} (pid ${pids.join(", ")}${suffix})`;
+}
+/**
+ * Decide whether one worktree-mutating git command may run here.
+ *
+ * Never throws: a registry read that fails yields an empty peer list, which
+ * reads as "no shared checkout" and allows. That direction is deliberate —
+ * the registry is observability substrate and an outage of it must not
+ * start refusing every branch switch on every machine.
+ */
+export async function evaluateSharedCheckoutGuard(toolName, input, cwd, deps = {}) {
+    if (!isWorktreeMutatingGitAttempt(toolName, input))
+        return { block: false };
+    // #2007: `git -C <dir>` and `--work-tree` retarget the command at a
+    // DIFFERENT directory. Evaluating the caller's cwd would inspect the wrong
+    // working tree and allow the destructive command against a shared one, so
+    // every targeted directory is evaluated and the first contended one wins.
+    const targets = resolveGuardTargets(toolName, input, cwd);
+    let entries;
+    try {
+        entries = await (deps.readRegistry ?? readInstanceRegistry)();
+    }
+    catch {
+        logAllow(normalizeFilePath(cwd), "registry_unreadable");
+        return { block: false };
+    }
+    for (const target of targets) {
+        const decision = await evaluateOneTarget(target, entries, deps);
+        if (decision.block)
+            return decision;
+    }
+    return { block: false };
+}
+/** Distinct directories the command's git invocations actually target. */
+function resolveGuardTargets(toolName, input, cwd) {
+    const targets = new Set();
+    for (const gitTokens of collectGitInvocations(toolName, input)) {
+        if (!matchesWorktreeMutatingVerb(gitTokens))
+            continue;
+        targets.add(resolveGitTargetDirectory(gitTokens, cwd));
+    }
+    // A wrapper or substitution form the token scan cannot attribute to a
+    // directory still matched the classifier, so fall back to the cwd rather
+    // than evaluating nothing.
+    if (targets.size === 0)
+        targets.add(cwd);
+    return [...targets];
+}
+async function evaluateOneTarget(cwd, entries, deps) {
+    const root = normalizeFilePath(cwd);
+    const resolveToplevel = deps.resolveToplevel ?? resolveGitToplevel;
+    const toplevel = await resolveToplevel(cwd);
+    if (toplevel === undefined) {
+        logAllow(root, "not_a_git_worktree");
+        return { block: false };
+    }
+    const normalizedToplevel = normalizeFilePath(toplevel);
+    // Containment against the TOPLEVEL, not against the caller's directory:
+    // two sessions in sibling subdirectories of one checkout share it, and
+    // comparing them to each other would miss that. Every directory in a
+    // working tree is under its own toplevel, so this pre-filter can only
+    // admit candidates, never drop a real peer.
+    const candidates = selectLivePeerInstances(entries, normalizedToplevel, deps.now ?? Date.now(), deps.isPidAlive ?? realIsPidAlive, "containment");
+    // Path containment is NOT shared-checkout identity. A linked worktree sits
+    // at a path nested under the main checkout — this repo puts agent
+    // worktrees under `.claude/worktrees/` — and shares no working files with
+    // it. Confirm each candidate belongs to the SAME working tree before
+    // declining anything, or the guard tells an operator already inside a
+    // dedicated worktree to go get a dedicated worktree.
+    //
+    // #2130: confirm against EVERY root the candidate serves, not only
+    // `projectRoot`. `selectLivePeerInstances` admits a candidate when ANY of
+    // its roots overlaps the target, so resolving the index-0 root alone drops
+    // a peer admitted on a SECONDARY root — and dropping the only peer allows
+    // the destructive command. `getInstanceRoots` is the single reader for
+    // registry root identity precisely so no caller re-derives it from the
+    // scalar field.
+    //
+    // Cost: at most one `git rev-parse` per distinct root, capped by
+    // `INSTANCE_ROOT_CAP` (32) and memoized below, on a path that already
+    // spawns one `rev-parse` for the target. The loop short-circuits on the
+    // first matching root, so the common single-root peer costs exactly what it
+    // did before.
+    const toplevelMemo = new Map();
+    const resolveToplevelOnce = async (dir) => {
+        if (toplevelMemo.has(dir))
+            return toplevelMemo.get(dir);
+        const resolved = await resolveToplevel(dir);
+        toplevelMemo.set(dir, resolved);
+        return resolved;
+    };
+    const peers = [];
+    for (const candidate of candidates) {
+        for (const candidateRoot of getInstanceRoots(candidate)) {
+            const peerToplevel = await resolveToplevelOnce(candidateRoot);
+            if (peerToplevel !== undefined &&
+                normalizeFilePath(peerToplevel) === normalizedToplevel) {
+                peers.push(candidate);
+                break;
+            }
+        }
+    }
+    if (peers.length === 0) {
+        logAllow(root, "no_peer_session");
+        return { block: false };
+    }
+    const state = await (deps.probeWorkingTree ?? probeWorkingTreeState)(cwd);
+    if (state === "clean") {
+        logAllow(root, "working_tree_clean");
+        return { block: false };
+    }
+    if (state === "unknown") {
+        emitBounded("shared_checkout_probe_failed", root, {
+            toolName: "shared-checkout-guard",
+            durationMs: 0,
+            metadata: { decision: "blocked", peerCount: peers.length },
+        }, {
+            ledgerKind: "shared-checkout-probe",
+            risingEdgePer: "identity",
+            reason: "git status could not report working-tree state",
+        });
+        return {
+            block: true,
+            unknown: true,
+            reason: "🔴 WORKING-TREE CHANGE BLOCKED (--lens-checkout-guard): git could not report whether this checkout has uncommitted work, and it is shared with " +
+                `${describePeers(peers)}. Re-run the command once git answers, or take a dedicated git worktree.`,
+        };
+    }
+    emitBounded("shared_checkout_switch_blocked", root, {
+        toolName: "shared-checkout-guard",
+        durationMs: 0,
+        metadata: { decision: "blocked", peerCount: peers.length },
+    }, {
+        ledgerKind: "shared-checkout-wip",
+        risingEdgePer: "identity",
+        reason: "worktree-mutating git command declined on a shared checkout",
+    });
+    return {
+        block: true,
+        reason: "🔴 WORKING-TREE CHANGE BLOCKED (--lens-checkout-guard): this checkout has uncommitted changes and is shared with " +
+            `${describePeers(peers)}. The command would discard work that may not be yours. ` +
+            "Commit the changes first, or run this in a dedicated git worktree.",
+    };
+}

package/node_modules/pi-lens/dist/clients/spawn-output-cap.js

@@ -0,0 +1,37 @@
+/**
+ * The one reading of `SpawnResult.outputTruncated` (#2100).
+ *
+ * Its own module for the same reason `ledger-bounds.ts` is: `spawn-outcome.ts`
+ * is on the shared runner path that dozens of test files reach with a bare
+ * `vi.mock("safe-spawn.js")`, and importing a VALUE from safe-spawn there makes
+ * every one of those mocks have to re-export it. This module has no imports, so
+ * nobody has to mock it.
+ */
+/**
+ * True when `outputTruncated` is the OUTPUT CAP's own verdict about this run,
+ * and not a detail of some other ending.
+ *
+ * A timeout or an abort can carry `outputTruncated` too. Those endings own
+ * their own classification, so they are excluded here rather than reported as
+ * truncation.
+ *
+ * Typed structurally so `SpawnResult` and runner-level result shapes that
+ * re-spell `failure` can both use it.
+ */
+export function truncatedByOutputCap(result) {
+    return (result.outputTruncated === true &&
+        result.failure !== "timeout" &&
+        result.failure !== "aborted");
+}
+/**
+ * True when `stopForOutputLimit` started terminating the child.
+ *
+ * Windows reports that termination as status 1 without a signal or failure,
+ * while POSIX commonly reports SIGTERM. This field avoids reconstructing our
+ * action from either platform's exit shape.
+ */
+export function killedForOutputCap(result) {
+    return (result.killedForOutputCap === true &&
+        result.failure !== "timeout" &&
+        result.failure !== "aborted");
+}

package/node_modules/pi-lens/dist/clients/spawn-timeout-cooldown.js

@@ -24,6 +24,7 @@
  */
 import path from "node:path";
 import { logLatency } from "./latency-logger.js";
+import { normalizeLoggedPath } from "./path-utils.js";
 const COOLDOWN_STATE_KEY = Symbol.for("pi-lens:spawn-timeout-cooldown");
 const _global = globalThis;
 if (!_global[COOLDOWN_STATE_KEY]) {
@@ -57,11 +58,24 @@ export function noteSpawnTimeout(input) {
         phase: input.phase,
         atMs: Date.now(),
     });
+    // #2229 review round 1, F3, reverted in round 3 (R2-F2): normalizing
+    // `filePath` here is fine (it is `logLatency`'s emit-seam field, a
+    // display value with no reader). `metadata.command` is NOT a display
+    // value — `safe-spawn-timeout-teardown.test.ts` reads it back to match
+    // the cooldown row against the RAW command, and `cooldownKey` above
+    // deliberately keys on basename because the same binary arrives in
+    // multiple spellings across call sites. Normalizing it changed a
+    // correlation key's contents, which is a behavior change other code
+    // reads, not just a display fix — narrower than what F3 asked for.
+    // `filePath` and `metadata.command` can legitimately show two spellings
+    // of the same command in one record; if that turns out to matter, the
+    // fix belongs in a follow-up that stops `filePath` from carrying
+    // commands at all, not in widening this field's normalization.
     logLatency({
         type: "phase",
         toolName: input.tool,
         phase: "spawn_timeout_cooldown",
-        filePath: input.command,
+        filePath: normalizeLoggedPath(input.command),
         durationMs: input.durationMs ?? 0,
         status: "cooldown_armed",
         metadata: {

package/node_modules/pi-lens/dist/clients/startup-scan.js

@@ -15,7 +15,7 @@ import { getProjectIgnoreMatcher, } from "./file-utils.js";
 import { isAtOrAboveHomeDir } from "./path-utils.js";
 import { getStartupScanMaxSourceFilesDerived } from "./project-scale.js";
 import { shouldRecurseIntoDir, walkTreeStackAsync, walkTreeStackSync, } from "./source-walker.js";
-import { getDirectoryMarkers } from "./workspace-topology.js";
+import { getDirectoryMarkers, registerWorkspaceTopologyReset, } from "./workspace-topology.js";
 export const PROJECT_ROOT_MARKERS = [
     ".git",
     "package.json",
@@ -217,15 +217,14 @@ export function countSourceFilesWithinLimit(dir, limit) {
     // startup-scan verdict path via `walkSourceCount`.
     return walkSourceCount(dir, limit, Number.POSITIVE_INFINITY).count;
 }
-// Process-lifetime memo for the (cwd, homeDir, maxSourceFiles) tuple. The
+// Session-lifetime memo for the (cwd, homeDir, maxSourceFiles) tuple. The
 // underlying computation walks the entire project root counting source
 // files and is dominated by ignoreMatcher.isIgnored() calls; on a 2k-file
-// project it costs ~2-3s the first time. Every `session_start` invocation
-// (boot, /new, --print) recomputes this otherwise. Since the answer
-// depends only on the file tree shape and ignore rules — both of which
-// are also captured by the project snapshot freshness check upstream —
-// in-process memoisation is safe for the duration of a single pi process.
+// project it costs ~2-3s the first time. The topology-reset registry clears
+// this memo at session start, so each session re-derives its answer. The memo
+// remains valid until the next session-start reset.
 const startupScanContextCache = new BoundedLruCache(32);
+registerWorkspaceTopologyReset(() => startupScanContextCache.clear());
 function startupScanCacheKey(cwd, options) {
     return [
         normalizeMapKey(path.resolve(cwd)),

package/node_modules/pi-lens/dist/clients/startup-timing.js

@@ -6,6 +6,7 @@ import { performance } from "node:perf_hooks";
 // wherever this file is imported, including test-only measurement code that
 // has no business flipping a global switch.
 import { PI_LENS_EVAL_STARTED_MS } from "./eval-timestamp.js";
+import { getProcessSingleton, nextModuleEvaluationOrdinal, } from "./process-singletons.js";
 /**
  * Startup timing for pi-lens.
  *
@@ -20,9 +21,30 @@ import { PI_LENS_EVAL_STARTED_MS } from "./eval-timestamp.js";
 export const PI_LENS_LOADED_FROM = import.meta.url.endsWith(".js")
     ? "dist"
     : "source";
+// `loadMs`/`loadedAtMs` deliberately stay at module scope: they measure THIS
+// evaluation's own load cost, so a second evaluation must get its own numbers
+// rather than adopt the first's (#2146 class sweep — per-evaluation by design).
 let loadMs;
 let loadedAtMs;
-let hostReadyDelayAnchorConsumed = false;
+/**
+ * The host-ready anchor is a once-PER-PROCESS latch, so it lives on the shared
+ * process singleton (#2146). Left at module scope it was consumed once per
+ * module evaluation, which meant a nine-evaluation process could emit the
+ * "first session" host-ready delay nine times.
+ */
+const HOST_READY_ANCHOR_FAMILY = "startup-timing.host-ready-anchor";
+const HOST_READY_ANCHOR_VERSION = 1;
+function hostReadyAnchorState() {
+    return getProcessSingleton(HOST_READY_ANCHOR_FAMILY, HOST_READY_ANCHOR_VERSION, () => ({ consumed: false }));
+}
+/**
+ * 1-based count of pi-lens module-graph evaluations in this process (#2146).
+ *
+ * Captured at module scope so it advances exactly once per evaluation, and
+ * carried on `host_boot.metadata.evaluationOrdinal` so multi-evaluation hosts
+ * are greppable in `latency.log`.
+ */
+export const PI_LENS_EVALUATION_ORDINAL = nextModuleEvaluationOrdinal();
 /**
  * Record the load-complete time. Call once, as the first statement in the
  * extension entry's module body — by then every import has been evaluated, so
@@ -42,14 +64,15 @@ export function getPiLensLoadedAtMs() {
 }
 /** Consume the process-lifetime first-session host-ready anchor exactly once. */
 export function consumeHostReadyDelayAnchor() {
-    if (hostReadyDelayAnchorConsumed)
+    const state = hostReadyAnchorState();
+    if (state.consumed)
         return false;
-    hostReadyDelayAnchorConsumed = true;
+    state.consumed = true;
     return true;
 }
 /** Test seam for the process-lifetime session-state registry probe boundary. */
 export function resetHostReadyDelayAnchorForTests() {
-    hostReadyDelayAnchorConsumed = false;
+    hostReadyAnchorState().consumed = false;
 }
 /** ms from pi process start to pi-lens load-complete, or undefined if unmarked. */
 export function getPiLensLoadMs() {
@@ -63,3 +86,45 @@ export function getPiLensEvalMs() {
         ? undefined
         : Math.max(0, loadMs - PI_LENS_HOST_BOOT_MS);
 }
+/**
+ * Build the three startup latency records the extension entry emits at module
+ * scope (`extension_loaded`, `host_boot`, `extension_eval`).
+ *
+ * A builder rather than three inline `logLatency` calls in `index.ts` so the
+ * record CONTENT is testable: `logLatency` is a no-op under `PI_LENS_TEST_MODE`,
+ * and `index.ts`'s module body cannot be re-run per assertion. `index.ts` maps
+ * the returned records straight into `logLatency`, so this is the production
+ * shape, not a parallel path.
+ *
+ * `host_boot` carries `evaluationOrdinal` (#2146): one `host_boot` line is one
+ * module-graph evaluation, and the ordinal makes a multi-evaluation host
+ * greppable instead of inferable by counting lines per pid.
+ */
+export function buildStartupTimingRecords(input) {
+    return [
+        {
+            type: "phase",
+            filePath: "<pi-lens>",
+            phase: "extension_loaded",
+            durationMs: input.loadMs,
+            metadata: { loadedFrom: PI_LENS_LOADED_FROM },
+        },
+        {
+            type: "phase",
+            filePath: "<pi-lens>",
+            phase: "host_boot",
+            durationMs: PI_LENS_HOST_BOOT_MS,
+            metadata: {
+                loadedFrom: PI_LENS_LOADED_FROM,
+                evaluationOrdinal: PI_LENS_EVALUATION_ORDINAL,
+            },
+        },
+        {
+            type: "phase",
+            filePath: "<pi-lens>",
+            phase: "extension_eval",
+            durationMs: input.evalMs,
+            metadata: { loadedFrom: PI_LENS_LOADED_FROM },
+        },
+    ];
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Ordinal (code-unit) string comparator for identity-feeding sorts — cache
+ * keys, dedupe keys, hashes, and signatures. Refs #2155, #2165.
+ *
+ * `localeCompare` orders strings by locale-dependent collation (the DEFAULT
+ * `Array.prototype.sort`, with no comparator, does not — it compares UTF-16
+ * code units, which is already ordinal). Locale-dependent order is fine for
+ * a list a human reads. It is a bug (SonarCloud S2871) when the sorted
+ * result feeds an identity: two processes — or one process whose locale
+ * changes — can order the same input differently under `localeCompare` and
+ * mint different keys for equivalent state, producing a silent cache or
+ * dedupe miss.
+ *
+ * Use this comparator whenever a sort's output becomes a key, a hash input,
+ * or a signature compared for equality later. Keep `localeCompare` for
+ * sorting that only affects what a person reads.
+ */
+export function compareOrdinal(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}