@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/session-lifecycle.js

@@ -28,13 +28,34 @@
  * behavior), matching the lazy-env-read house style (see
  * `subagent-mode.ts` / `runtime-config.ts`).
  */
-/** Module-scope state — deliberately shared by construction. This module is
- * loaded once per process by pi's process-global extension cache, so a
- * concurrent in-process subagent session sees the SAME instance as the
- * parent, which is exactly the signal this guard relies on. */
-let activeCtx;
-let activeSessionId;
-let secondarySessionCount = 0;
+import { normalizeFilePath } from "./path-utils.js";
+import { getProcessSingleton } from "./process-singletons.js";
+const SESSION_LIFECYCLE_FAMILY = "session-lifecycle.primary-registration";
+/** Bump when {@link SessionLifecycleState}'s shape changes. */
+const SESSION_LIFECYCLE_VERSION = 1;
+function state() {
+    return getProcessSingleton(SESSION_LIFECYCLE_FAMILY, SESSION_LIFECYCLE_VERSION, () => ({
+        activeCtx: undefined,
+        activeSessionId: undefined,
+        activeRoot: undefined,
+        secondarySessionCount: 0,
+    }));
+}
+/** The stable id of the currently registered primary session, if known. */
+export function getActiveSessionId() {
+    return state().activeSessionId;
+}
+/**
+ * The normalized project root of the currently registered primary session
+ * (#2129), or `undefined` when no primary has registered a root yet.
+ *
+ * This is the process's answer to "which directory does pi-lens actually
+ * serve", and it is what `memory_sample` carries as its root discriminator
+ * (#2130) so a record from a multi-root host is attributable.
+ */
+export function getActivePrimaryRoot() {
+    return state().activeRoot;
+}
 /**
  * PURE classifier — no I/O, no throws, fully unit-testable in isolation.
  *
@@ -49,19 +70,57 @@ let secondarySessionCount = 0;
  *     this IS the sequential case pi's own contract covers).
  *  4. Prior exists, `priorCtxActive === true`, different session id →
  *     `concurrent-secondary` (positive evidence of a live sibling).
- *  5. Prior exists, `priorCtxActive === undefined` (probe inconclusive) →
+ *  5. Prior exists, different session id, `sameRoot === false` (positive
+ *     evidence of a DIFFERENT project root) → `secondary-root` (#2129).
+ *  6. Prior exists, `priorCtxActive === undefined` (probe inconclusive) →
  *     `sequential-replacement` (fail toward today's behavior).
+ *
+ * WHY ROOT IDENTITY IS AN INPUT AT ALL (#2129). Branch 3 alone made a subagent
+ * temp worktree — a session_start in a DIFFERENT directory, arriving after the
+ * host's real session had already been disposed or had an unprobeable ctx —
+ * classify as a sequential replacement. It then re-registered itself as the
+ * process's primary and ran the full session_start body: `resetLSPService`
+ * killed the host's warm LSP fleet, and the whole async battery (opengrep,
+ * word-index rebuild, review-graph build) re-ran per temp root over content
+ * that had not changed. Two temp roots in one host cost ~50s of opengrep and
+ * ~53s of word-index rebuild EACH, and drove host RSS from 290MB to 1.1GB in
+ * four minutes.
+ *
+ * A start in a different root is therefore never allowed to steal primary. It
+ * is a `secondary-root`, which the caller treats exactly like a
+ * `concurrent-secondary`: skip the destructive resets and the expensive
+ * battery, leave the registered primary's ctx/session id/root untouched. The
+ * root still gets served — `initLSPConfig` registers session roots lazily,
+ * per file (`clients/lsp/session-roots.ts:48`), not from this handler.
+ *
+ * Ordering note: the root check sits BELOW the `priorCtxActive === true`
+ * branch so a live sibling still reports the more specific
+ * `concurrent-secondary`, and it deliberately fires even when
+ * `priorCtxActive === false`. "The prior ctx was invalidated" is exactly the
+ * state a temp-worktree start arrives in, so deferring to it would restore the
+ * defect.
+ *
+ * Accepted trade-off: an in-process SEQUENTIAL replacement that genuinely
+ * moves to a new directory (a host that switches sessions across cwds within
+ * one process) now takes the reduced path instead of a full start. It keeps
+ * working — the LSP still attaches per file — but skips the startup battery
+ * for the new root until a same-root start re-registers. `sameRoot` is only
+ * ever `false` on positive evidence, and
+ * `PI_LENS_CONCURRENT_SESSION_GUARD=0` disables this branch with the rest of
+ * the guard.
  */
 export function classifySessionStart(input) {
-    const { hasPrior, priorCtxActive, sameSessionId } = input;
+    const { hasPrior, priorCtxActive, sameSessionId, sameRoot } = input;
     if (!hasPrior)
         return "primary";
     if (sameSessionId)
         return "sequential-replacement";
-    if (priorCtxActive === false)
-        return "sequential-replacement";
     if (priorCtxActive === true)
         return "concurrent-secondary";
+    if (sameRoot === false)
+        return "secondary-root";
+    if (priorCtxActive === false)
+        return "sequential-replacement";
     // priorCtxActive === undefined: inconclusive probe — fail-safe.
     return "sequential-replacement";
 }
@@ -121,15 +180,91 @@ export function probeCtxActive(ctx) {
  * `primary` and `sequential-replacement` classifications — a sequential
  * replacement re-registers itself as the (new) primary, matching today's
  * one-active-session-at-a-time behavior. */
-export function registerPrimarySession(ctx, sessionId) {
-    activeCtx = ctx;
-    activeSessionId = sessionId;
-    secondarySessionCount = 0;
+export function registerPrimarySession(ctx, sessionId, root) {
+    const s = state();
+    s.activeCtx = ctx;
+    s.activeSessionId = sessionId;
+    // #2129: a re-registration that carries NO root must not erase a root the
+    // previous primary did record — losing it would make every later start's
+    // `sameRoot` read `undefined` (unknown) and silently restore the pre-fix
+    // "any root may steal primary" behavior.
+    if (root !== undefined)
+        s.activeRoot = normalizeRootForCompare(root);
+    s.secondarySessionCount = 0;
+}
+/**
+ * Normalize a project root for identity comparison (#2129).
+ *
+ * Uses `normalizeFilePath` — the SAME comparator `registerInstance`
+ * (`clients/instance-registry.ts:213`) writes roots with — so drive-letter
+ * case, separators, and symlinked temp dirs cannot make two spellings of one
+ * root look like two roots (catalog shape 1). Never throws: an unresolvable
+ * path degrades to `undefined`, which reads as "root unknown" and leaves the
+ * classification exactly where it was before this input existed.
+ */
+function normalizeRootForCompare(root) {
+    if (typeof root !== "string" || root.length === 0)
+        return undefined;
+    try {
+        return normalizeFilePath(root);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Release the primary registration when the primary session itself shuts down
+ * (#2129 review F3).
+ *
+ * WHY THIS EXISTS. Before root identity was an input, a stale `activeCtx` left
+ * behind by a departed primary was benign: the next start probed it, got
+ * `false` (dead ctx), and classified `sequential-replacement`, so it took over
+ * as the new primary. Root identity made that stale state DECISIVE — a start in
+ * a different root behind a dead-but-still-registered primary now classifies
+ * `secondary-root` and declines. Without an explicit release, root A's primary
+ * ending would mean every later start in root B declines FOREVER: never
+ * primary, never a full start, no re-arm.
+ *
+ * This is the catalog's process-lifetime-latch shape (state that must re-arm at
+ * a session boundary must not outlive it). `session_shutdown`'s primary path is
+ * that boundary. Deliberately NOT called on a secondary's shutdown — that path
+ * returns before the shared teardown precisely because the primary is still
+ * live.
+ *
+ * A concurrent secondary that outlives the primary now classifies `primary` on
+ * its later emissions rather than `concurrent-secondary`. That is the fail-safe
+ * direction this module has always taken (run the handler), and it is correct
+ * here: with the primary gone there is no live sibling to protect.
+ *
+ * WHAT PROTECTS A SURVIVING SECONDARY (#2130 round 2, remainder N3/F3). Not the
+ * count zeroed below, and not this module-level classification at all: it is the
+ * per-activation `ownedSessionRole` closure in `index.ts`. Each activation
+ * records the role IT was classified as at its own session_start and consults
+ * that at its own shutdown, so a secondary whose primary has already released
+ * still takes the secondary teardown path.
+ *
+ * `secondarySessionCount` is therefore an OBSERVABILITY counter, not a guard.
+ * Zeroing it here under-reports for the window between the primary's release
+ * and the next primary's registration. That is real and accepted: the only
+ * reader is `concurrent_session_bind.metadata.secondaryCount` in `latency.log`,
+ * and during that window no primary is registered, so every arriving start
+ * classifies `primary` and re-registers — which zeroes the count anyway —
+ * instead of emitting a bind record. `decrementSecondarySessionCount` clamps at
+ * zero, so a late secondary's shutdown cannot underflow it. Documented rather
+ * than changed, because a count that outlived the registration it is scoped to
+ * would disagree with `getActivePrimaryRoot()` in the same record.
+ */
+export function releasePrimarySession() {
+    const s = state();
+    s.activeCtx = undefined;
+    s.activeSessionId = undefined;
+    s.activeRoot = undefined;
+    s.secondarySessionCount = 0;
 }
 /** Register a concurrently-bound secondary (subagent) session. Does not
  * touch the primary's ctx/session id. */
 export function registerSecondarySession() {
-    secondarySessionCount += 1;
+    state().secondarySessionCount += 1;
 }
 /**
  * Classifies a `session_shutdown` firing the same fail-safe way as
@@ -152,6 +287,27 @@ export function registerSecondarySession() {
  * now classifies `primary` (conservative miss — its teardown runs and hurts
  * the parent, same as pre-#473 behavior), because uncertainty must never
  * classify `secondary`.
+ *
+ * ROOT IDENTITY (#2146 review F1). The probe-based branch above is the only
+ * evidence this function had, and it is exactly the evidence that is missing in
+ * the state #2146 describes: the host's ctx is already invalidated, which is
+ * WHY `secondary-root` fires on the start side. A subagent's teardown therefore
+ * read "the primary's ctx is dead, so I must be the primary", and index.ts's
+ * primary path called `releasePrimarySession()` and wiped the SHARED process
+ * registration. The decline then survived exactly one subagent: the next one
+ * classified `primary` and ran the full battery.
+ *
+ * So this function takes the same root discriminator `decideSessionStart` has,
+ * with the same rule and the same fail-safe direction. A shutdown whose root is
+ * POSITIVELY different from the registered primary's root is a `secondary`,
+ * even when the primary's ctx probes `false` or `undefined` — deferring to the
+ * dead-ctx branch is what restored the defect. `undefined` on either side means
+ * "root unknown" and changes no verdict.
+ *
+ * Ordering: the root check sits BELOW the id-unknown guard, not above it. That
+ * guard is the #472 fix — a session with an unreadable session id must still
+ * tear itself down — and a root comparison cannot establish "different session"
+ * when the ids that identify sessions are unavailable.
  */
 export function noteSessionShutdown(
 // Load-bearing: ctx OBJECT IDENTITY is the definitive discriminator when
@@ -160,25 +316,40 @@ export function noteSessionShutdown(
 // (Note: pi's ExtensionRunner.emit() builds a FRESH ctx object per emit,
 // so identity match is not expected with today's SDK — this check is
 // defense-in-depth for SDK versions/paths that reuse a ctx.)
-ctx, sessionId) {
-    if (ctx !== undefined && ctx === activeCtx) {
+ctx, sessionId, 
+/** This session's own project root (`ctx.cwd`), when readable. `undefined`
+ *  means "root unknown" and never on its own changes a verdict. */
+root) {
+    const s = state();
+    if (ctx !== undefined && ctx === s.activeCtx) {
         return "primary";
     }
-    if (activeCtx === undefined && activeSessionId === undefined) {
+    if (s.activeCtx === undefined && s.activeSessionId === undefined) {
         return "primary";
     }
-    if (sessionId !== undefined && sessionId === activeSessionId) {
+    if (sessionId !== undefined && sessionId === s.activeSessionId) {
         return "primary";
     }
     // Uncertainty guard: if EITHER side's session id is unknown we cannot
     // positively establish "different session", so never classify secondary.
-    if (sessionId === undefined || activeSessionId === undefined) {
+    if (sessionId === undefined || s.activeSessionId === undefined) {
         return "primary";
     }
-    const primaryStillActive = probeCtxActive(activeCtx);
+    const primaryStillActive = probeCtxActive(s.activeCtx);
     if (primaryStillActive === true) {
         return "secondary";
     }
+    // #2146 F1: positive evidence of a DIFFERENT root, in a session positively
+    // identified as not the primary. Deliberately below the probe-true branch
+    // (a live sibling is already answered) and deliberately ABOVE the
+    // dead-ctx fail-safe, because a dead primary ctx is precisely the state a
+    // subagent teardown arrives in.
+    const shutdownRoot = normalizeRootForCompare(root);
+    if (s.activeRoot !== undefined &&
+        shutdownRoot !== undefined &&
+        s.activeRoot !== shutdownRoot) {
+        return "secondary";
+    }
     // primaryStillActive is false or undefined: fail-safe to primary.
     return "primary";
 }
@@ -203,27 +374,29 @@ ctx, sessionId) {
 export function classifyCurrentSessionEmission(ctx, sessionId) {
     if (!guardEnabled())
         return "primary";
-    if (activeCtx === undefined && activeSessionId === undefined)
+    const s = state();
+    if (s.activeCtx === undefined && s.activeSessionId === undefined)
         return "primary";
-    if (ctx !== undefined && ctx === activeCtx)
+    if (ctx !== undefined && ctx === s.activeCtx)
         return "primary";
-    if (sessionId !== undefined && sessionId === activeSessionId)
+    if (sessionId !== undefined && sessionId === s.activeSessionId)
         return "primary";
     // Uncertainty guard: if EITHER side's session id is unknown we cannot
     // positively establish "different session", so never classify secondary.
-    if (sessionId === undefined || activeSessionId === undefined)
+    if (sessionId === undefined || s.activeSessionId === undefined)
         return "primary";
-    const primaryStillActive = probeCtxActive(activeCtx);
+    const primaryStillActive = probeCtxActive(s.activeCtx);
     if (primaryStillActive === true)
         return "concurrent-secondary";
     return "primary";
 }
 export function getSecondarySessionCount() {
-    return secondarySessionCount;
+    return state().secondarySessionCount;
 }
 export function decrementSecondarySessionCount() {
-    if (secondarySessionCount > 0)
-        secondarySessionCount -= 1;
+    const s = state();
+    if (s.secondarySessionCount > 0)
+        s.secondarySessionCount -= 1;
 }
 /**
  * Guard-aware wrapper used by callers (index.ts) so the kill switch lives in
@@ -238,9 +411,14 @@ export function classifySessionStartGuarded(input) {
 /** Test-only: clears all module-scope state (house style — see
  * `_resetSubagentModeForTests` / `slow-fs.ts`). */
 export function _resetSessionLifecycleForTests() {
-    activeCtx = undefined;
-    activeSessionId = undefined;
-    secondarySessionCount = 0;
+    // Resets the PROCESS state, not a module-local copy: a reset that cleared
+    // only module scope would leave the real registration behind and make every
+    // suite that relies on isolation pass vacuously (#2146, catalog shape 7).
+    const s = state();
+    s.activeCtx = undefined;
+    s.activeSessionId = undefined;
+    s.activeRoot = undefined;
+    s.secondarySessionCount = 0;
 }
 /**
  * Single entry point `index.ts`'s `session_start` handler delegates to, so
@@ -253,36 +431,54 @@ export function _resetSessionLifecycleForTests() {
  * fake object in tests is safe). `sessionId` is the STABLE session id
  * (`ctx.sessionManager.getSessionId()`), which may be `undefined`.
  */
-export function decideSessionStart(ctx, sessionId) {
-    const hasPrior = activeCtx !== undefined || activeSessionId !== undefined;
-    const priorCtxActive = hasPrior ? probeCtxActive(activeCtx) : undefined;
+export function decideSessionStart(ctx, sessionId, root) {
+    const s = state();
+    const hasPrior = s.activeCtx !== undefined || s.activeSessionId !== undefined;
+    const priorCtxActive = hasPrior ? probeCtxActive(s.activeCtx) : undefined;
     // ctx OBJECT IDENTITY: if the SDK ever hands the SAME ctx object to a
     // repeated session_start, that is by definition the same session
     // re-announcing itself — sequential, never concurrent. (Not expected with
     // today's SDK — ExtensionRunner.emit() builds a fresh ctx per emit — but
     // identity is the one signal that can't false-positive, so honor it.)
-    const sameCtx = hasPrior && ctx !== undefined && ctx === activeCtx;
+    const sameCtx = hasPrior && ctx !== undefined && ctx === s.activeCtx;
     const sameSessionId = sameCtx ||
-        (hasPrior && sessionId !== undefined && sessionId === activeSessionId);
+        (hasPrior && sessionId !== undefined && sessionId === s.activeSessionId);
+    // #2129: compare THIS start's cwd against the registered primary's root.
+    // `undefined` on either side means "unknown", never "different" — see
+    // `classifySessionStart`'s fail-safe note.
+    const incomingRoot = normalizeRootForCompare(root);
+    const sameRoot = hasPrior && s.activeRoot !== undefined && incomingRoot !== undefined
+        ? s.activeRoot === incomingRoot
+        : undefined;
+    // #2129 review F5: capture the primary root BEFORE any registration mutates
+    // it, so the reported value is genuinely the decision-time input the
+    // classifier consulted rather than the value this call just wrote.
+    const primaryRootAtDecision = s.activeRoot;
     const classification = classifySessionStartGuarded({
         hasPrior,
         priorCtxActive,
         sameSessionId,
+        sameRoot,
     });
-    if (classification === "concurrent-secondary") {
+    if (classification === "concurrent-secondary" ||
+        classification === "secondary-root") {
         registerSecondarySession();
         return {
             classification,
             runFullSessionStart: false,
-            secondaryCount: secondarySessionCount,
+            secondaryCount: s.secondarySessionCount,
+            sameRoot,
+            primaryRoot: primaryRootAtDecision,
         };
     }
     // "primary" or "sequential-replacement": register as the (new) primary
     // and proceed exactly as today.
-    registerPrimarySession(ctx, sessionId);
+    registerPrimarySession(ctx, sessionId, root);
     return {
         classification,
         runFullSessionStart: true,
-        secondaryCount: secondarySessionCount,
+        secondaryCount: s.secondarySessionCount,
+        sameRoot,
+        primaryRoot: primaryRootAtDecision,
     };
 }

package/node_modules/pi-lens/dist/clients/sg-runner.js

@@ -12,6 +12,7 @@ import { getSgCommand, resolveManagedToolClient, } from "./dispatch/runners/util
 import { getProjectIgnoreGlobs } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { truncatedByOutputCap } from "./spawn-output-cap.js";
 import { createSingleFlight } from "./single-flight.js";
 import { classifyProbeFailure, describeInstallAttempt, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 /**
@@ -87,8 +88,10 @@ function tryParseSgMatches(stdout) {
         return null;
     }
 }
+// The truncation veto lives at the head of `exec`/`interpretScanResult` now
+// (#2100), so this stays a pure parser rather than re-asking a settled question.
 function tryParseNonZeroSgMatches(result) {
-    if (result.outputTruncated || !result.stdout.trim())
+    if (!result.stdout.trim())
         return null;
     // Trimmed on purpose: a leading BOM survives JSON.parse's whitespace
     // tolerance but String.trim() strips it (matches the pre-refactor guard).
@@ -322,6 +325,7 @@ export class SgRunner {
             cause: provisional ? this.sweepTransientCause : "ok",
             elapsedMs: Date.now() - startedAt,
             latched: !provisional,
+            classifiedBy: "probe",
             hostStallMs: this.sweepHostStallMs,
             budgetMs: PROBE_TIMEOUT_MS,
             ...(provisional && {
@@ -582,6 +586,17 @@ export class SgRunner {
             totalMatches: 0,
             truncated: false,
         });
+        // FIRST (#2100): hitting the cap makes safe-spawn SIGTERM ast-grep, so a
+        // truncated run also classifies as a killed spawn. Read after the two
+        // gates below, this guard could only ever describe a run that exited
+        // before the signal reached it. A timed-out or aborted run carries the
+        // flag too and keeps its own classification below.
+        if (truncatedByOutputCap(result)) {
+            return {
+                ...empty(),
+                error: "Failed to parse output: output was truncated",
+            };
+        }
         const spawnFailure = this.failureForSpawnResult(result);
         if (spawnFailure) {
             return {
@@ -622,12 +637,6 @@ export class SgRunner {
         }
         if (!result.stdout.trim())
             return empty();
-        if (result.outputTruncated) {
-            return {
-                ...empty(),
-                error: "Failed to parse output: output was truncated",
-            };
-        }
         {
             const matches = tryParseSgMatches(result.stdout);
             if (matches) {
@@ -659,6 +668,17 @@ export class SgRunner {
         }
     }
     interpretScanResult(result, args) {
+        // FIRST (#2100): same reason as `exec` above — the cap kill is our own
+        // SIGTERM, so `failureForSpawnResult` answers "cli-failure" for it and
+        // the truncation guard below never speaks.
+        if (truncatedByOutputCap(result)) {
+            return {
+                matches: [],
+                status: result.status,
+                error: "Failed to parse ast-grep scan output: output was truncated",
+                failure: "parse-failure",
+            };
+        }
         const failure = this.failureForSpawnResult(result);
         if (failure) {
             return {
@@ -697,14 +717,6 @@ export class SgRunner {
         }
         if (!result.stdout.trim())
             return { matches: [], status: result.status };
-        if (result.outputTruncated) {
-            return {
-                matches: [],
-                status: result.status,
-                error: "Failed to parse ast-grep scan output: output was truncated",
-                failure: "parse-failure",
-            };
-        }
         {
             const matches = tryParseSgMatches(result.stdout);
             if (matches) {