pi-lens 4.2.0 → 4.3.0

package/dist/clients/cascade-format.js

@@ -3,6 +3,7 @@ import { retagAuxiliaryDiagnostics } from "./dispatch/auxiliary-lsp.js";
 import { applyFindingPolicy, loadProjectRulePolicyMap, renderedRuleIdentities, } from "./dispatch/finding-policy.js";
 import { detectFileRole } from "./file-role.js";
 import { logLatency } from "./latency-logger.js";
+import { formatCacheAgeLabel } from "./finding-delivery-gate.js";
 import { convertLspDiagnostics } from "./dispatch/utils/lsp-diagnostics.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
@@ -140,6 +141,12 @@ export function buildResolvedFoundCascadeRun(cwd, neighbor) {
         },
         neighborCount: 1,
         diagnosticCount: diagnostics.length,
+        // #3168 F3: the #1444 publish stamp — the run's own observation time, so
+        // the carried-render age label states the real age instead of claiming
+        // no stamp exists.
+        ...(neighbor.publishedAt !== undefined
+            ? { observedAt: neighbor.publishedAt }
+            : {}),
     };
 }
 /**
@@ -289,3 +296,20 @@ function readNeighborContent(filePath) {
         return undefined;
     }
 }
+/**
+ * Fix B (#3167/#3168): the carry label for a cascade run re-rendered at a
+ * later turn_end. The carry is bounded to ONE turn (`RuntimeCoordinator.beginTurn`
+ * drops anything that would reach 2), so the honest label names the carry
+ * count. #3168 F3 corrected this docstring's earlier claim that no stamp
+ * exists: the run DOES carry one (`observedAt`, threaded from #1444's
+ * `publishedAt` through the resolved-found plumb), so the age half renders
+ * from it via `formatCacheAgeLabel`. The deferred-compute re-park arm has no
+ * stamp and correctly falls to the neutral wording. Returns `undefined` for
+ * non-carried runs: no label noise on fresh observations.
+ */
+export function cascadeCarrySuffix(carriedTurns, observedAt) {
+    if (carriedTurns === undefined || carriedTurns < 1)
+        return undefined;
+    const noun = carriedTurns === 1 ? "turn" : "turns";
+    return `(carried ${carriedTurns} ${noun} · ${formatCacheAgeLabel(observedAt)})`;
+}

package/dist/clients/child-unref.js

@@ -11,12 +11,16 @@
  * new-code-duplication finding: two near-identical spawn→collect-stdout
  * blocks in `clients/resource-sampler.ts` collapsed to one shared helper).
  *
- * Deliberately has NO imports beyond `node:child_process` types, so both
+ * Deliberately has NO imports beyond `node:child_process` types and
+ * `spawn-output-cap.ts` (itself import-free, #3383), so both
  * `clients/instance-reaper.ts` and `clients/resource-sampler.ts` (which
  * `clients/safe-spawn.ts` itself depends on) can import this without risking
- * a circular-import chain.
+ * a circular-import chain. That is also why the output bound below reports
+ * nothing to the degradation ledger: importing the ledger here would put
+ * `safe-spawn.ts`'s own dependency above it in the graph.
  */
 import { spawn as nodeSpawn } from "node:child_process";
+import { createBoundedOutputSink } from "./spawn-output-cap.js";
 /**
  * Detach a best-effort, fire-and-forget child process from the event loop.
  *
@@ -64,13 +68,18 @@ export function spawnCollectStdoutResult(command, args, options, collectOptions
         try {
             const child = nodeSpawn(command, args, options);
             unrefChildAndPipes(child);
-            let out = "";
-            child.stdout?.on("data", (chunk) => {
-                out += chunk.toString();
-            });
+            // #3383: bounded, not `out += chunk`. The producer is a process-table
+            // query (`ps`, `wmic`, `powershell`) whose output nothing else limits,
+            // and the concatenation runs inside a `data` handler where V8's
+            // `RangeError: Invalid string length` would be an uncaught exception
+            // rather than this promise's result. A truncated table is the ending
+            // this contract already documents for a timed-out child: whatever was
+            // kept is parsed, and the caller reads `status`.
+            const out = createBoundedOutputSink();
+            child.stdout?.on("data", (chunk) => out.append(chunk));
             child.once("error", (error) => settle({ stdout: "", status: "spawn-error", error }));
             child.once("close", (code, signal) => settle(code === 0 && signal === null
-                ? { stdout: out, status: "ok" }
+                ? { stdout: out.text, status: "ok" }
                 : {
                     stdout: "",
                     status: "exit-error",
@@ -83,7 +92,7 @@ export function spawnCollectStdoutResult(command, args, options, collectOptions
                     // Settle only AFTER the child's fate is known. Killing and
                     // resolving in the same tick bounds the caller and abandons the
                     // child, which is the leak this timeout exists to prevent.
-                    void terminateTimedOutChild(child, collectOptions.onTimeout).then((timeoutKill) => settle({ stdout: out, status: "timeout", timeoutKill }));
+                    void terminateTimedOutChild(child, collectOptions.onTimeout).then((timeoutKill) => settle({ stdout: out.text, status: "timeout", timeoutKill }));
                 }, timeoutMs);
                 timer.unref();
             }

package/dist/clients/config-diagnostic-codes.js

@@ -173,6 +173,8 @@ export const CONFIG_DIAGNOSTIC_CODES = {
     PILENS_CFG_0008: "config resolution failed; whole configuration ignored",
     /** A tool key is unknown or names a required, non-disableable tool. */
     PILENS_CFG_0009: "unknown or non-disableable tool config key ignored",
+    /** A lower-precedence supported global config file was shadowed by the winner. */
+    PILENS_CFG_0010: "lower-precedence global config file shadowed",
 };
 /** The shape every code in the namespace must match. */
 export const CONFIG_DIAGNOSTIC_CODE_PATTERN = /^PILENS_CFG_\d{4}$/;

package/dist/clients/config-locations.js

@@ -22,12 +22,17 @@
  * exactly the registry's `kind: "file"` rows. Registry owns WHICH surfaces are
  * deprecated; this module owns only their precedence.
  *
- * Pure data plus one walk. No file reads, no caching, no state.
+ * Pure data, one walk, and — as of the global-config-location PR (refs #2457,
+ * #2426) — the ONE existence probe and memoized resolution that decide which
+ * file supplies the global tier. The probe is a single `statSync` under the
+ * resolution memo; no other file reads, no state beyond that one memo.
  */
+import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { DEPRECATED_CONFIG_SURFACES } from "./config-diagnostic-codes.js";
-import { isAtOrAboveHomeDir, walkUpDirs } from "./path-utils.js";
+import { errorClassName } from "./error-class.js";
+import { isAtOrAboveHomeDir, isWindowsPath, normalizeFilePath, realpathOrResolve, walkUpDirs, } from "./path-utils.js";
 /** The one canonical PROJECT config file. Never deprecated. */
 export const CANONICAL_PROJECT_CONFIG_FILE = ".pi-lens.json";
 /** Basename of the one canonical GLOBAL config file inside `~/.pi-lens/`. */
@@ -139,9 +144,167 @@ export function configSearchDirs(startDir, homeDir = os.homedir()) {
     }
     return dirs;
 }
+function defaultGlobalConfigExists(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch (error) {
+        // ENOENT is the ordinary ABSENT answer the tier walk consumes. Any other
+        // stat failure (ENOTDIR when a file sits where a directory belongs,
+        // EACCES, ELOOP) propagates: the discriminated probe in
+        // `resolveGlobalConfigLocation` retains the errored tier instead of
+        // silently switching config sources (#3251 review H2, defect shape 48),
+        // and the load's read of the retained path is reported by the existing
+        // `PILENS_CFG_0001` seam.
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
 /**
- * The absolute path of the canonical GLOBAL config — `~/.pi-lens/config.json`,
- * or `PI_LENS_CONFIG_PATH` when it overrides that.
+ * The agent-dir config path for one `PI_CODING_AGENT_DIR` value, shared by the
+ * resolution and the recognized-location set so the two can never spell the
+ * same location differently.
+ *
+ * Shape-aware joining (defect shape 2): a Windows-shaped agent dir is joined
+ * with `path.win32` regardless of host — the host-default `path.resolve` on
+ * POSIX treats a drive-letter path as RELATIVE and mangles it, which made a
+ * case-folded Windows spelling unmatchable (#3251 review M1).
+ */
+function agentConfigPathFor(agentDir) {
+    return isWindowsPath(agentDir)
+        ? path.win32.join(path.win32.resolve(agentDir), "extensions", "pi-lens.json")
+        : path.join(path.resolve(agentDir), "extensions", "pi-lens.json");
+}
+/**
+ * Resolve which file supplies the global config tier (see
+ * `GlobalConfigLocationSource` for the order).
+ *
+ * Lives here rather than in `lens-config.ts` (#2426 review round 3, S1):
+ * this module is the one that already states "WHERE pi-lens config lives",
+ * and BOTH discovery seams that must refuse the resolved global path
+ * (`project-lens-config.ts`, `workspace-topology.ts`) already import from
+ * here — importing the resolver from `lens-config.ts` would close a cycle
+ * (`lens-config.ts` itself imports from `project-lens-config.ts`).
+ * `lens-config.ts` re-exports the accessors so its own, pre-existing import
+ * sites are unaffected.
+ */
+export function resolveGlobalConfigLocation(options) {
+    // An options object means the caller OWNS the resolution context (a test
+    // or explicitly-scoped caller): the ambient host env must not leak into it,
+    // or a test that resolves-then-writes "under its own home" lands in the
+    // maintainer's real config (dogfooded live: ambient PI_CODING_AGENT_DIR
+    // redirected a suite's writeConfig into ~/.config/pi/agent/extensions/
+    // pi-lens.json). Owned contexts therefore ignore PI_CODING_AGENT_DIR
+    // entirely; only the production resolution (no options) walks the
+    // host-relative tier. PI_LENS_HOME does not participate in this resolution
+    // at all — the canonical default keeps its released homedir spelling, and
+    // the #2457 split-brain (which concerns the machine root, not the config
+    // file) stays a separate issue.
+    const owned = options !== undefined;
+    const homeDir = options?.homeDir ?? os.homedir();
+    const legacyDefault = path.join(homeDir, ".pi-lens", CANONICAL_GLOBAL_CONFIG_FILE);
+    // Byte-compatible with the released override: any non-empty value wins,
+    // untrimmed, exactly as before.
+    const override = process.env.PI_LENS_CONFIG_PATH;
+    if (override) {
+        return { path: path.resolve(override), source: "pi-lens-config-path" };
+    }
+    // The probe is DISCRIMINATED (#3251 review H2, defect shape 48): "error"
+    // (ENOTDIR when a file sits where a directory belongs, EACCES, ELOOP) is
+    // NOT absent — the errored tier is RETAINED, so the load's read of that
+    // same path fails and the existing `reportConfigReadFailure` seam
+    // (`PILENS_CFG_0001`) reports it. Absorbing the error as ABSENT would
+    // silently select a lower tier: different user settings applying with no
+    // diagnostic, and the read seam would only ever see the finally-read path,
+    // never the probe that failed.
+    let probeError;
+    const probe = (file) => {
+        try {
+            return (options?.exists ?? defaultGlobalConfigExists)(file)
+                ? "present"
+                : "absent";
+        }
+        catch (error) {
+            // The caught error is carried to the retained tier's resolution so
+            // the loader's retention record can name the error CLASS (never
+            // the message, per the #2431/#2451 rule).
+            probeError = error;
+            return "error";
+        }
+    };
+    const agentDir = owned ? undefined : process.env.PI_CODING_AGENT_DIR?.trim();
+    const agentPath = agentDir ? agentConfigPathFor(agentDir) : undefined;
+    const legacyProbe = probe(legacyDefault);
+    if (legacyProbe === "present") {
+        if (agentPath !== undefined && probe(agentPath) === "present") {
+            return {
+                path: legacyDefault,
+                source: "legacy-default-existing",
+                shadowedPath: agentPath,
+            };
+        }
+        return { path: legacyDefault, source: "legacy-default-existing" };
+    }
+    if (legacyProbe === "error") {
+        // Fail closed at the location the probe could not evaluate: the file
+        // might exist, and switching sources would silently swap the user's
+        // settings. The subsequent read reports the failure (`PILENS_CFG_0001`),
+        // and the loader emits the probe-failed retention record.
+        return {
+            path: legacyDefault,
+            source: "legacy-default-unprobed",
+            existsProbeFailed: {
+                path: legacyDefault,
+                errorClassName: errorClassName(probeError),
+            },
+        };
+    }
+    if (agentPath !== undefined) {
+        const agentProbe = probe(agentPath);
+        if (agentProbe === "present") {
+            return { path: agentPath, source: "pi-coding-agent-dir" };
+        }
+        if (agentProbe === "error") {
+            // Same rule one tier down: the agent-dir identity is retained, and
+            // the read of it reports the failure rather than the resolution
+            // silently falling to the canonical default.
+            return {
+                path: agentPath,
+                source: "pi-coding-agent-dir-unprobed",
+                existsProbeFailed: {
+                    path: agentPath,
+                    errorClassName: errorClassName(probeError),
+                },
+            };
+        }
+    }
+    return { path: legacyDefault, source: "canonical-default" };
+}
+let memoizedGlobalConfigResolution;
+function globalConfigEnvFingerprint() {
+    return JSON.stringify([
+        process.env.PI_LENS_CONFIG_PATH,
+        process.env.PI_CODING_AGENT_DIR,
+    ]);
+}
+export function getProductionGlobalConfigResolution() {
+    const fingerprint = globalConfigEnvFingerprint();
+    if (memoizedGlobalConfigResolution?.fingerprint !== fingerprint) {
+        memoizedGlobalConfigResolution = {
+            fingerprint,
+            resolution: resolveGlobalConfigLocation(),
+        };
+    }
+    return memoizedGlobalConfigResolution.resolution;
+}
+/** Test-only: drop the memoized production resolution so the next call re-probes. */
+export function resetGlobalConfigLocationCache() {
+    memoizedGlobalConfigResolution = undefined;
+}
+/**
+ * The absolute path of the canonical GLOBAL config (see
+ * `GlobalConfigLocationSource` for the full resolution order).
  *
  * Lives here rather than in `lens-config.ts` (#2426 review round 3, S1),
  * which is where it originated: this module is the one that already states
@@ -152,9 +315,74 @@ export function configSearchDirs(startDir, homeDir = os.homedir()) {
  * `project-lens-config.ts`. `lens-config.ts` re-exports this so its own,
  * pre-existing import sites are unaffected.
  */
-export function getPiLensGlobalConfigPath(homeDir = os.homedir()) {
-    const override = process.env.PI_LENS_CONFIG_PATH;
-    if (override)
-        return path.resolve(override);
-    return path.join(homeDir, ".pi-lens", CANONICAL_GLOBAL_CONFIG_FILE);
+export function getPiLensGlobalConfigPath(homeDir) {
+    return homeDir === undefined
+        ? getProductionGlobalConfigResolution().path
+        : resolveGlobalConfigLocation({ homeDir }).path;
+}
+/**
+ * Whether `candidate` matches ANY location the global config tier recognizes —
+ * the resolved file, the legacy default, and the agent-dir target.
+ *
+ * The one predicate every project-config discovery seam consults before it
+ * adopts a candidate (#783's nested layering, the upward walk, and the
+ * workspace marker index): a file the global tier recognizes must not be
+ * discovered a second time as a project config — the discovery loader would
+ * full-validate it, ignore every global-only key in it, and advise the user
+ * to set those keys in the very file it is ignoring. The check covers the
+ * POTENTIAL set, not just whichever file currently won the read: a second
+ * recognized file that exists but lost the tier walk (the grandfathered
+ * legacy file beside an adopted agent-dir file, say) is equally not a project
+ * config.
+ *
+ * Comparison is alias-anchored on BOTH sides (#3251 review M1 round 2):
+ * each path is canonicalized through `realpathOrResolve` (resolving existing
+ * symlink aliases; a nonexistent path falls back to its resolved spelling —
+ * the documented fallback) and then `normalizeFilePath` (separator-agnostic,
+ * case-insensitive on Windows, casing-adoption). A symlinked-home alias of a
+ * recognized location is therefore the same identity as its real spelling,
+ * and a case-folded or separator-differing Windows spelling cannot dodge the
+ * refusal either.
+ */
+export function isResolvedGlobalConfigPath(candidate) {
+    return recognizedGlobalConfigPaths().has(canonicalPathIdentity(candidate));
+}
+/**
+ * Canonical path identity for one candidate: realpath-anchored so an
+ * existing symlink alias resolves to the same identity as its real spelling
+ * (#3251 review M1 round 2), with `realpathOrResolve`'s documented
+ * nonexistent-path fallback (the resolved spelling, dot-folded and
+ * case-normalized by `normalizeFilePath` — which pays its own `realpath`
+ * only when the path exists). The discovery seams consult this predicate
+ * per config candidate, and the env-derived recognized set is canonicalized
+ * with the SAME helper once per env fingerprint, so both sides of the
+ * comparison share one identity function.
+ */
+export function canonicalPathIdentity(candidate) {
+    // Shape-aware (defect shape 2): a Windows-shaped path is resolved with
+    // `path.win32` — the host resolver on POSIX treats a drive-letter path as
+    // RELATIVE and mangles it before any comparison could run. On a real
+    // Windows host this arm is the native one, and `normalizeFilePath`'s
+    // Windows branch does the alias resolution itself (realpathSync.native
+    // plus canonical-casing adoption).
+    if (isWindowsPath(candidate)) {
+        return normalizeFilePath(path.win32.resolve(candidate));
+    }
+    return normalizeFilePath(realpathOrResolve(candidate));
+}
+let recognizedCache;
+function recognizedGlobalConfigPaths() {
+    const fingerprint = globalConfigEnvFingerprint();
+    if (recognizedCache?.fingerprint !== fingerprint) {
+        const paths = new Set();
+        const override = process.env.PI_LENS_CONFIG_PATH;
+        if (override)
+            paths.add(canonicalPathIdentity(path.resolve(override)));
+        paths.add(canonicalPathIdentity(path.join(os.homedir(), ".pi-lens", CANONICAL_GLOBAL_CONFIG_FILE)));
+        const agentDir = process.env.PI_CODING_AGENT_DIR?.trim();
+        if (agentDir)
+            paths.add(canonicalPathIdentity(agentConfigPathFor(agentDir)));
+        recognizedCache = { fingerprint, paths };
+    }
+    return recognizedCache.paths;
 }

package/dist/clients/config-resolve.js

@@ -60,7 +60,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { DEPRECATED_CONFIG_SURFACES, } from "./config-diagnostic-codes.js";
-import { CANONICAL_GLOBAL_CONFIG_FILE, CANONICAL_PROJECT_CONFIG_FILE, GLOBAL_CONFIG_LOCATIONS, LEGACY_ROOT_LSP_KEYS, LSP_NAMESPACE_KEY, PROJECT_CONFIG_LOCATIONS, configSearchDirs, } from "./config-locations.js";
+import { CANONICAL_GLOBAL_CONFIG_FILE, CANONICAL_PROJECT_CONFIG_FILE, GLOBAL_CONFIG_LOCATIONS, isResolvedGlobalConfigPath, LEGACY_ROOT_LSP_KEYS, LSP_NAMESPACE_KEY, PROJECT_CONFIG_LOCATIONS, configSearchDirs, } from "./config-locations.js";
 // The core's halves are imported directly rather than through
 // `config-core/index.js` (#2426). The barrel re-exports the whole vocabulary
 // including `process-spec.js`, which reaches `project-trust.js` and the
@@ -126,6 +126,12 @@ function collectDocuments(dir, locations, tier, onReadError) {
     const documents = [];
     for (const location of locations) {
         const file = path.join(dir, location.relativePath);
+        // The global tier reads its file by absolute path; a candidate that IS
+        // that file is refused rather than adopted as a project/nested-project
+        // document, which would double-read and double-validate it
+        // (global-config-location PR, refs #2457).
+        if (tier !== "global" && isResolvedGlobalConfigPath(file))
+            continue;
         const outcome = readConfigDocument(file);
         if (outcome.status === "missing")
             continue;

package/dist/clients/degradation-ledger.js

@@ -37,10 +37,21 @@ let ledgerGeneration = 0;
 export function getDegradationLedgerGeneration() {
     return ledgerGeneration;
 }
+/**
+ * Test-only population probe for bounded-container regressions. Keep this
+ * read-only and deliberately expose sizes, not the retained identities.
+ */
+export function _getDegradationLedgerStateForTests() {
+    return {
+        onceKeys: onceKeys.size,
+        tallies: tallies.size,
+        retainedEntries: [...groups.values()].reduce((total, group) => total + group.entries.length, 0),
+    };
+}
 export function recordDegradation(record) {
     try {
         const kind = boundedKind(record.kind);
-        const subject = truncateForLedger(record.subject);
+        const subject = subjectForLedger(record.subject);
         const reason = truncateForLedger(record.reason);
         let group = groups.get(kind);
         if (!group) {
@@ -67,7 +78,7 @@ export function recordDegradation(record) {
 export function recordDegradationOnce(record) {
     try {
         const kind = boundedKind(record.kind);
-        const subject = truncateForLedger(record.subject);
+        const subject = subjectForLedger(record.subject);
         const key = `${kind}\0${subject}`;
         if (onceKeys.has(key))
             return;
@@ -96,7 +107,7 @@ export function recordDegradationOnce(record) {
 export function incrementDegradationCount(record) {
     try {
         const kind = boundedKind(record.kind);
-        const subject = truncateForLedger(record.subject);
+        const subject = subjectForLedger(record.subject);
         const reason = truncateForLedger(record.reason);
         const key = `${kind}\0${subject}`;
         const count = (tallies.get(key) ?? 0) + 1;
@@ -172,6 +183,25 @@ function boundLedgerMetadata(metadata) {
 function isPowerOfTwo(value) {
     return value > 0 && (value & (value - 1)) === 0;
 }
+/**
+ * A subject is an IDENTITY: it is the row's discriminator, the `filePath` of
+ * its durable latency row, and the text `renderDegradationLines` prints after
+ * the count. A blank one names nothing — `⚠ kind: 1 — : reason` — so blank and
+ * missing are the same case and both read `unknown` (#3389 verify round 2,
+ * F3395-02: a socket error carrying `code: ""` wrote an empty subject).
+ *
+ * This is deliberately NOT `normalizeForLedger`'s job, though every ledger
+ * field passes through it: that normalizer keeps falsy primitives on purpose
+ * (`tests/clients/ledger-bounds.test.ts` "keeps primitives, including falsy
+ * ones"), because a metadata VALUE of `""` or `0` is data, not absence. Only
+ * the identity fields fold blank into missing, and `0`/`false` still name
+ * something here too — the check reads the NORMALIZED text, never the caller's
+ * truthiness.
+ */
+function subjectForLedger(value) {
+    const subject = truncateForLedger(value);
+    return subject.trim() === "" ? "unknown" : subject;
+}
 function boundedKind(value) {
     const kind = truncateForLedger(value);
     if (groups.has(kind) || kind === OVERFLOW_KIND)