pi-lens 4.3.0 → 4.4.1

package/dist/clients/post-autofix-notice.js

@@ -1,37 +0,0 @@
-/**
- * The single post-autofix instruction about a written file (#1590).
- *
- * Two layers used to phrase this. `clients/pipeline.ts` claimed "the attached
- * full content is authoritative" from changed-file membership alone, and
- * `clients/runtime-tool-result.ts` — the only layer that sees the per-file
- * attachment cap and the per-command aggregate budget — appended "too large to
- * attach" for the same file. On a size-capped write the agent got both.
- *
- * The wording now lives here, and `handleToolResult` is the only caller: the
- * pipeline supplies the data (display paths it already resolved) and the layer
- * that made the attachment decision picks the sentence. Keeping the renderer
- * out of `pipeline.ts` also keeps it real in tests that mock the pipeline away.
- */
-/** Render the ONE post-autofix instruction for `decision`. */
-export function renderPostAutofixNotice(notice, decision) {
-    const topFiles = notice.changedFiles
-        .slice(0, 8)
-        .map((f) => "  - " + f)
-        .join("\n");
-    const overflow = notice.changedFiles.length > 8
-        ? "\n  - ... and " + (notice.changedFiles.length - 8) + " more"
-        : "";
-    const fileList = notice.changedFiles.length
-        ? "\nModified files:\n" + topFiles + overflow
-        : "";
-    switch (decision) {
-        case "attached":
-            return `⚠️ **The attached full content for ${notice.targetPath} is authoritative after autofix. You MUST re-read any other modified side-effect files before editing them.**${fileList}`;
-        case "size-capped":
-            return `⚠️ **File was modified by auto-format/fix. You MUST re-read ${notice.targetPath} before making any further edits — the authoritative content is too large to attach.**${fileList}`;
-        case "aggregate-budget-degraded":
-            return `⚠️ **File was modified by auto-format/fix. You MUST re-read ${notice.targetPath} before making any further edits — the aggregate authoritative content for this command is too large to attach.**${fileList}`;
-        default:
-            return `⚠️ **File was modified by auto-format/fix. You MUST re-read modified file(s) before making any further edits — the content on disk has changed (whitespace, indentation, quotes, or code). Editing from memory will produce mismatches.**${fileList}`;
-    }
-}

package/dist/clients/print-mode.js

@@ -1,21 +0,0 @@
-/**
- * One-shot invocation detection, shared across the session_start-scheduled
- * background work that must NOT run — or retain the process — in print mode
- * (#1154 quick-mode warmup, #1153 orphan-reaper).
- *
- * `pi -p` / `pi --print` is a one-shot: the host computes a single turn and
- * exits. Work scheduled to warm caches / clean up state for a *future* session
- * in the same process is pure waste in this mode AND — when it arms a
- * referenced libuv handle (a non-`unref`'d timer, an LSP child, an fs walk)
- * with no session_shutdown teardown — keeps the already-settled one-shot
- * process alive. That is the referenced-handle retention class of
- * #1097/#1110/#1148/#1149 and the located #1122 hypothesis-A concern.
- *
- * argv is read live (not captured at module load) so tests can drive it; the
- * flag never changes within a real process, and there is no hot-path caller,
- * so recomputing is free. This mirrors the print detection in
- * `runtime-session.ts`'s `resolveStartupMode` — keep them a single source.
- */
-export function isPrintMode(argv = process.argv) {
-    return argv.includes("--print") || argv.includes("-p");
-}

package/dist/clients/probe-home-state.js

@@ -1,228 +0,0 @@
-/**
- * The #2506 probe-home redirect, whole: the decision, the per-process memo it
- * is cached in, and the degradation event that decision produced.
- *
- * WHAT IT DECIDES. An ad-hoc probe against the BUILT `clients/*.js` — a bare
- * `node -e`, a throwaway `.mjs`, a harness script — has no `PI_LENS_HOME` pin,
- * so every logger and ledger it touches used to write into the maintainer's
- * REAL `~/.pi-lens`. Confirmed live on 2026-09-02: two review probes left 42
- * rows of `/p/.pi-lens.json` fixture garbage in real telemetry. When
- * `PI_LENS_HOME` is unset and the process looks like a probe — `PILENS_PROBE=1`,
- * a `cwd` inside a specific agent worktree, or a `cwd` under `os.tmpdir()` —
- * `resolveProbeHomeDir()` answers with a per-probe directory instead.
- *
- * WHY IT ALL LIVES HERE and not beside its `getGlobalPiLensDir()` sibling in
- * `file-utils.ts`, where round 2 of #2516 left it. `file-utils.ts` sits on an
- * import cycle (it still does, via `safe-spawn.js` -> `resource-sampler.js` ->
- * `instance-reaper.js` -> `file-utils.js`; the shorter route through
- * `degradation-ledger.js` -> `extension-log.js` was this move's doing —
- * `extension-log.ts` imported `file-utils.ts` for THIS function and nothing
- * else, so the edge went with it, and the known-violations baseline dropped
- * from 33 pinned cycles to 12 with none added). Fifteen log-family modules
- * call `getGlobalPiLensLogDir()` at their OWN module
- * top level. Under vitest's vite-SSR transform each import becomes a
- * `__vite_ssr_import_N__` variable assigned in source order, so one of those
- * top-level calls re-enters `file-utils.ts` while its body is only PARTWAY
- * through those assignments — and a resolver sitting there then dereferences a
- * binding that has not been assigned yet, throwing `ReferenceError: Cannot
- * access '__vite_ssr_import_N__' before initialization`. Measured live: the
- * re-entry arrives through `file-utils.ts`'s FIFTH import,
- * `spawn-timeout-cooldown.js`, so every binding declared from the sixth import
- * onward is unsafe on that path — which is most of the file.
- *
- * Round 2 of #2516 papered over that with an `isTestMode()` early return placed
- * ahead of the first unsafe dereference. That was load-order luck, not a
- * design: moving `file-utils.ts`'s own `isTestMode` import from fifth to last
- * makes the GUARD LINE ITSELF throw the same error. It also DEFEATED the
- * redirect for every process that has `VITEST` set but no `PI_LENS_HOME` pin —
- * vitest's own globalSetup/child processes — sending their logs to the real
- * home: the exact hermeticity hole the redirect exists to close.
- *
- * THIS module is off that cycle. It imports only node builtins and
- * `path-utils.js`, itself a leaf (node builtins plus the vendored, zero-import
- * `deps/minimatch.js`). A module off every cycle is fully evaluated before any
- * importer's body runs — in plain ESM and under the vite-SSR transform alike —
- * so none of its own bindings can ever be observed uninitialized, wherever an
- * importer chooses to place the import. That is what makes the guard
- * unnecessary rather than merely well-placed, and it is why module-scope
- * `const`s (including the `Symbol.for` below) are ordinary here where they were
- * a hazard in `file-utils.ts`.
- *
- * `tests/config/global-dir-probe-redirect.test.ts` pins the behaviour through
- * real spawned `node` children, including the VITEST-set-but-unpinned case.
- */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { isUnderDir, normalizeFilePath } from "./path-utils.js";
-/**
- * The memo lives in a process-wide `globalThis` slot rather than a plain
- * module-scope `let` so that a bundled `dist/index.js` and the loose
- * `clients/*.js` loaded into the same process — the shape #335 ships — share
- * ONE decision instead of memoizing two. A `Symbol.for` key is interned by
- * string, so both copies of this module resolve to the same slot.
- */
-const RESOLUTION_SLOT = Symbol.for("pi-lens.probe-home-state.resolution");
-/** The memoized resolution for this process, or `undefined` before first use. */
-export function getProbeHomeResolution() {
-    return globalThis[RESOLUTION_SLOT];
-}
-/**
- * The degradation row for a redirect that actually happened, or `undefined`
- * when this process was not redirected (or has not resolved yet).
- * `degradation-ledger.ts`'s `getDegradationSummary()` is the only caller — it
- * folds this at READ time rather than having the resolver push a row, because a
- * direct import between `file-utils.ts` and `degradation-ledger.ts` in EITHER
- * direction (a dynamic `import()` included) adds unpinned `no-client-cycles`
- * violations to the cycle named in this module's doc comment.
- */
-export function getProbeHomeRedirectEvent() {
-    return getProbeHomeResolution()?.event;
-}
-/**
- * Where pi-lens writes its LOGS, ledger rows and debug dumps: `~/.pi-lens/` by
- * default, exactly like `getGlobalPiLensDir()` in `file-utils.ts` — but
- * redirected to a per-probe directory when this process looks like an ad-hoc
- * probe rather than a real pi session (#2506).
- *
- * Every log-family writer routes here: `latency.log`, `extension.log`,
- * `sessionstart.log`, `cascade.log`, `read-guard.log`, `tree-sitter.log`,
- * `word-index.log`, `bus-events.log`, `dispositions.log`, `dead-code.log`,
- * `ast-grep-tools.log`, `actionable-warnings.log`, `review-graph.log`, the
- * `logs/*.jsonl` diagnostic dir, the debug handle/heap dumps,
- * `log-cleanup.ts`'s sweep over all of the above, and `smells-rollup.ts`'s
- * read-side tail of `latency.log`/`bus-events.log` (a reader, but it must
- * follow the same root or it tails a file nobody is writing).
- *
- * WHY IT LIVES IN THIS MODULE and not next to its `getGlobalPiLensDir()`
- * sibling in `file-utils.ts` — see this file's header. Fifteen of the writers
- * listed above call this function at their OWN module top level, and
- * `file-utils.ts` is on an import cycle, so resolving from there could observe
- * `file-utils.ts` mid-initialization. Resolving from a module off every cycle
- * cannot.
- *
- * `PI_LENS_HOME` wins over any redirect, which is how
- * `tests/support/vitest-setup.ts` keeps test workers hermetic. Note the
- * redirect still applies under vitest for processes that setup does not cover
- * (globalSetup, and children spawned without the pin): #2516 round 2's
- * `isTestMode()` guard sent exactly those to the developer's real home.
- *
- * Deliberately does NOT write a line to the terminal when it fires. #1333 gives
- * pi sole ownership of the TTY, and
- * `tests/clients/extension-terminal-silence.test.ts` enforces that nothing
- * under `clients/` calls `process.std*.write` or `console.*` (round 2 of
- * #2506 shipped a `process.stderr.write` here and was red in CI for exactly
- * that). Nor can it log through `extension-log.ts`'s
- * `createSubsystemLogger`: that module imports THIS one, so an import back
- * the other way would close a new, unpinned `no-client-cycles` cycle — and
- * `extension.log` is itself redirected by this very function, so the line
- * would land in the probe home nobody reads. The durable signal is the
- * `global-dir-probe-redirect` degradation row instead, folded into
- * `getDegradationSummary()` at read time via
- * `getProbeHomeRedirectEvent()` above.
- */
-export function getGlobalPiLensLogDir() {
-    const override = process.env.PI_LENS_HOME?.trim();
-    if (override)
-        return path.resolve(override);
-    return resolveProbeHomeDir() ?? path.join(os.homedir(), ".pi-lens");
-}
-/**
- * Resolve the probe-home redirect at most ONCE per process, caching both the
- * "yes, here" and the "no redirect" answers (#2506 round 3, F5). Round 2 read
- * `process.cwd()` live on every call, which gave a single process up to three
- * different global dirs as it chdir'd, and re-ran the whole decision on the hot
- * logging path.
- *
- * `undefined` means "no redirect applies"; `getGlobalPiLensLogDir()` above
- * falls back to the real home. This function never consults `PI_LENS_HOME` —
- * that pin is handled by its caller, ahead of this decision, so a pinned
- * process never memoizes a probe answer it would then keep after the pin
- * changed.
- */
-function resolveProbeHomeDir() {
-    const slot = globalThis;
-    const cached = slot[RESOLUTION_SLOT];
-    if (cached)
-        return cached.probeHome;
-    const cwd = process.cwd();
-    const probeHome = computeProbeHomeDir(cwd);
-    slot[RESOLUTION_SLOT] = {
-        probeHome,
-        event: probeHome ? { probeHome, cwd } : undefined,
-    };
-    return probeHome;
-}
-/**
- * Clears the memoized decision AND the event it produced, so the next
- * `getGlobalPiLensLogDir()` call re-resolves from scratch. Exercised by
- * `tests/config/global-dir-probe-redirect.test.ts`, which drives the resolver
- * repeatedly under different in-process conditions; without it the first call
- * in a worker would pin the answer for every later case in the same file.
- */
-export function _resetProbeHomeRedirectStateForTests() {
-    globalThis[RESOLUTION_SLOT] = undefined;
-}
-/** The redirect decision itself. */
-function computeProbeHomeDir(cwd) {
-    // The explicit force wins first: it is how a probe run from an ordinary
-    // project checkout opts in, and it must work even under a harness that has
-    // set a test-mode marker but no PI_LENS_HOME.
-    if (process.env.PILENS_PROBE === "1") {
-        return path.join(cwd, ".pi-lens-probe-home");
-    }
-    const worktreeRoot = findAgentWorktreeRoot(cwd);
-    if (worktreeRoot)
-        return path.join(worktreeRoot, ".pi-lens-probe-home");
-    if (isUnderRealDir(cwd, os.tmpdir())) {
-        return path.join(cwd, ".pi-lens-probe-home");
-    }
-    return undefined;
-}
-/**
- * The directory of the SPECIFIC agent worktree containing `cwd`, or
- * `undefined` when `cwd` is not inside one.
- *
- * Requires at least one path segment AFTER `worktrees/`, and anchors the
- * probe home at that segment rather than at the live `cwd` (#2506 round 3,
- * F5). Round 2's trailing `(\/|$)` alternative also matched a `cwd` of
- * `.claude/worktrees` ITSELF, which would have put the probe home in the
- * SHARED worktrees parent — every concurrent agent on the box writing into
- * one directory, the cross-agent collision this redirect is supposed to
- * prevent. Anchoring at the worktree also means a probe run from a
- * subdirectory (`<worktree>/clients`) and one run from the worktree root
- * agree on a single probe home instead of scattering one per cwd.
- */
-function findAgentWorktreeRoot(cwd) {
-    const normalized = normalizeFilePath(path.resolve(cwd));
-    const match = /(?:^|\/)\.claude\/worktrees\/[^/]+(?:\/|$)/.exec(normalized);
-    if (!match)
-        return undefined;
-    return normalized.slice(0, match.index + match[0].length).replace(/\/$/, "");
-}
-/**
- * `isUnderDir`, but with both sides resolved through `realpath` first
- * (#2506 round 3, F7).
- *
- * On macOS `os.tmpdir()` reports `/var/folders/...` while a `cwd` created
- * under it resolves to `/private/var/folders/...` (`/var` is a symlink to
- * `/private/var`), so the two NEVER prefix-match unresolved and the tmpdir
- * branch would be dead on every Mac. Windows has the same shape with 8.3
- * short names and substituted drives. Both sides go through the same
- * function, so `realpathSync.native`'s canonical Windows casing applies
- * consistently; the result is used only for this containment test, never to
- * build the returned path, so no casing change can leak into a log path.
- * Best-effort by design: a path that does not exist yet (or an EPERM) falls
- * back to its literal form rather than throwing on the logging hot path.
- */
-function isUnderRealDir(child, parent) {
-    return isUnderDir(toRealPath(child), toRealPath(parent));
-}
-function toRealPath(target) {
-    try {
-        return fs.realpathSync.native(target);
-    }
-    catch {
-        return target;
-    }
-}

package/dist/clients/process-bridge.js

@@ -1,66 +0,0 @@
-/**
- * Shared process-bridge registration helper (#2437).
- *
- * `clients/read-bridge.ts` (#1265) and `clients/mutation-bridge.ts` (#2423)
- * each mount a versioned, frozen method-table object at a well-known
- * `globalThis[Symbol.for("pi-lens:...")]` key so a same-process producer can
- * reach pi-lens's bookkeeping without importing its internals. Both bridges
- * carried an identical mount body — a first-wins existence check,
- * `Object.freeze`, and a non-writable/non-configurable `Object.defineProperty`
- * — differing only in their key and method table (named by the #2432 review,
- * refs #2423). This module owns that body once.
- *
- * NOT `clients/process-singletons.ts` (#2146): that module keeps a single
- * MUTABLE, adopt-if-version-compatible value per "family" inside ONE shared
- * container (a different, single key mounts the container itself, and a
- * version mismatch there means "discard and rebuild"). A bridge's contract is
- * the opposite: the documented producer protocol reads
- * `globalThis[Symbol.for("pi-lens:mutation-bridge")]` directly as a frozen,
- * first-wins, unreplaceable property, and a version mismatch is the
- * PRODUCER's problem — an unsupported bridge it should not call — never a
- * signal for pi-lens to silently reset its own mount. Reusing the singleton
- * container would change that documented external contract, so this stays a
- * separate, deliberately smaller leaf built for the bridge shape only.
- *
- * STATIC IMPORTS: none, deliberately. Both `read-bridge.ts` and
- * `mutation-bridge.ts` import this module; it must stay a dependency leaf so
- * neither gains an edge onto anything else in `clients/` (`no-client-cycles`).
- */
-/**
- * Mount `build()`'s result at `globalThis[key]`, once per process.
- *
- * First-wins: if `key` already exists on `globalThis` — from an earlier call
- * in this process, whether this bridge's own prior registration or a
- * redundant re-activation — `build()` is never invoked and the existing
- * mount is left untouched. The mounted value is frozen and installed
- * non-writable/non-configurable so no later code can silently replace or
- * extend it; the `in` check above is what keeps a redundant call from
- * throwing on that now-frozen property.
- */
-export function registerProcessBridge(key, build) {
-    if (key in globalThis)
-        return;
-    const bridge = Object.freeze(build());
-    Object.defineProperty(globalThis, key, {
-        value: bridge,
-        writable: false,
-        configurable: false,
-        enumerable: false,
-    });
-}
-/**
- * The bridge mounted at `key`, or `undefined` when nothing is mounted, the
- * mounted value is not an object, or its `version` does not equal `version`.
- * A version mismatch means "not a bridge this caller recognizes" — never
- * adopted and never reset; the reset-on-mismatch behavior belongs to
- * `process-singletons.ts`'s different contract, not this one.
- */
-export function getProcessBridge(key, version) {
-    const bridge = globalThis[key];
-    if (!bridge || typeof bridge !== "object")
-        return undefined;
-    const candidate = bridge;
-    if (candidate.version !== version)
-        return undefined;
-    return candidate;
-}

package/dist/clients/process-singletons.js

@@ -1,210 +0,0 @@
-/**
- * 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;
-}

package/dist/clients/process-snapshot.js

@@ -1,68 +0,0 @@
-/**
- * The extension runtime's door onto the ONE process-table seam (#2443).
- *
- * `scripts/lib/process-scan.mjs` owns what a process listing IS: the field →
- * platform-column table, the Windows CIM/WQL and POSIX `ps` command
- * composition, the WQL escaping, and the row parser. This module owns how
- * clients/ RUNS one, which is genuinely different from how a script runs one
- * and stays different on purpose:
- *
- * - the child and its stdout pipe are `unref`'d (#1155) so a one-shot
- *   `pi --print` can settle without waiting on a CIM query;
- * - a child that blows its timeout is terminated through the caller's own
- *   tree-kill-and-verify machinery (#1864 F3), injected as `onTimeout` — a
- *   sweep that leaks its own scanner is the defect the sweep exists to fix;
- * - the outcome carries a `SpawnCollectStatus`, so "the table is empty" and
- *   "the query never ran" stay distinguishable and the caller can record the
- *   degradation (#1857).
- *
- * WHY THE SEAM IS IMPORTED FROM scripts/ RATHER THAN LIVING HERE: the .mjs
- * header argues it in full. Short version — `scripts/prune-agent-worktrees.mjs`
- * is a SessionStart/SubagentStop hook that runs inside freshly created agent
- * worktrees, where `clients/*.js` (gitignored build output) does not exist
- * yet, so the shared half has to be the side that needs no build. This file
- * is the single crossing point; nothing else in clients/ imports scripts/.
- */
-import { spawnCollectStdoutResult, } from "./child-unref.js";
-import { buildProcessQuery, parseProcessTable, } from "../scripts/lib/process-scan.mjs";
-/**
- * Re-exported, not redefined. `windowsExe` resolves an absolute System32
- * interpreter path for a spawn this process is about to make (a bare
- * `powershell.exe`/`taskkill.exe` is resolvable through a PATH a caller can
- * shadow, and these spawns decide what gets killed) — one definition of that
- * rule is the whole point of the seam.
- */
-export { windowsExe } from "../scripts/lib/process-scan.mjs";
-/**
- * Run one process-table query on the extension's spawn rails.
- *
- * Never throws and never rejects: an unbuildable query (a Windows-only column
- * asked for on POSIX, an empty filter) resolves as `spawn-error` with no rows,
- * the same shape every other failure takes, because every caller here is
- * best-effort instrumentation or a best-effort sweep.
- */
-export async function queryProcessTable(request, options) {
-    let query;
-    try {
-        query = buildProcessQuery(request.fields, {
-            filter: request.filter,
-            excludeSelfPid: request.excludeSelfPid,
-        });
-    }
-    catch {
-        return { rows: [], status: "spawn-error", serverSideFiltered: false };
-    }
-    const result = await spawnCollectStdoutResult(query.command, query.args, { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, { timeoutMs: options.timeoutMs, onTimeout: options.onTimeout });
-    return {
-        // Whatever the collector kept is parsed rather than discarded here: it
-        // drops stdout on a non-zero exit (that output is not evidence of what
-        // is NOT running) but KEEPS the partial table from a timed-out child,
-        // and the caller decides what a partial table is worth by reading
-        // `status`. Re-deciding that here would be a second policy.
-        rows: parseProcessTable(result.stdout, query.tabSeparated, query.fields),
-        status: result.status,
-        exitCode: result.exitCode,
-        timeoutKill: result.timeoutKill,
-        serverSideFiltered: query.serverSideFiltered,
-    };
-}