@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/rust-client.js

@@ -63,4 +63,35 @@ export class RustClient {
     isRustFile(filePath) {
         return path.extname(filePath).toLowerCase() === ".rs";
     }
+    /** Forget the memoized cargo path and latched availability verdict — #2455. */
+    resetAvailability() {
+        this.availability.reset();
+    }
+}
+/**
+ * The one `RustClient` this process owns (#2455 fix round 4, F2).
+ *
+ * Same shape as `go-client.ts`'s `goClient`, and the same round-2 defect: the
+ * runner (`dispatch/runners/rust-clippy.ts`) and `bootstrap.ts` each built
+ * their own instance, so `resetRustAvailability` re-armed one latch while
+ * `handleSessionStart`'s "Active tools" line read the other's never-expiring
+ * probe-class "missing" verdict. One instance, in the module that owns the
+ * class; `tests/clients/toolchain-client-singleton.test.ts` holds the line.
+ */
+export const rustClient = new RustClient();
+/**
+ * Forget `rustClient`'s memoized cargo path and latched availability verdict —
+ * #2455. Same #1496/#1535 shape as `resetZizmorTokenAvailability`; wired into
+ * `handleSessionStart` beside it (`clients/runtime-session.ts`) so a Rust
+ * toolchain installed mid-process is observed by the next session instead of
+ * staying "missing" for the rest of the process's life.
+ *
+ * This module — not `rust-clippy.ts` — because the reset must sit beside the
+ * single instance it clears (#2455 fix round 4, F2). `rust-clippy.ts`'s
+ * `clippyAvailabilityByCargo` is a separate, already-covered latch: it rides
+ * `createCwdCachedProbe`'s shared `availabilityGeneration` counter (see
+ * `runner-helpers.ts`'s `resetDispatchAvailabilityState`), not this reset.
+ */
+export function resetRustAvailability() {
+    rustClient.resetAvailability();
 }

package/node_modules/pi-lens/dist/clients/safe-spawn.js

@@ -16,6 +16,7 @@
 import { spawn, spawnSync, } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { BoundedFifoMap } from "./bounded-cache.js";
 import { logLatency } from "./latency-logger.js";
 import { recordDegradation } from "./degradation-ledger.js";
 import { logExtension } from "./extension-log.js";
@@ -570,23 +571,21 @@ function resolveWindowsPathEntry(entry, effectiveCwd, env) {
  * cache is also count-bounded with oldest-entry eviction because a long-lived
  * process can encounter unbounded cwd/environment combinations.
  */
-const WINDOWS_COMMAND_CACHE_MAX_ENTRIES = 256;
+export const WINDOWS_COMMAND_CACHE_MAX_ENTRIES = 256;
 const WINDOWS_COMMAND_NEGATIVE_CACHE_TTL_MS = 1000;
-const windowsCommandCache = new Map();
+const windowsCommandCache = new BoundedFifoMap(WINDOWS_COMMAND_CACHE_MAX_ENTRIES);
 /** Reset after session replacement or a successful managed install. */
 export function resetSafeSpawnWindowsCommandCache() {
     windowsCommandCache.clear();
     loggedSpawnClassifications.clear();
 }
 function cacheWindowsCommandResult(key, resolved) {
-    if (windowsCommandCache.size >= WINDOWS_COMMAND_CACHE_MAX_ENTRIES) {
-        // Resolution entries are session-scoped and cheap to recompute. Evict the
-        // oldest insertion first so a long-lived process cannot retain every cwd /
-        // environment it has ever touched.
-        const oldest = windowsCommandCache.keys().next().value;
-        if (oldest !== undefined)
-            windowsCommandCache.delete(oldest);
-    }
+    // Resolution entries are session-scoped and cheap to recompute. The
+    // caller always deletes any stale entry for `key` before reaching here
+    // (see resolveWindowsCommandForEnvironment), so this can only grow the
+    // map; BoundedFifoMap evicts the oldest insertion first once the map
+    // exceeds capacity, so a long-lived process cannot retain every cwd /
+    // environment it has ever touched.
     windowsCommandCache.set(key, { resolved, checkedAt: Date.now() });
 }
 function getPathExts(env) {
@@ -848,6 +847,30 @@ const EXIT_PIPE_IDLE_MAX_WAIT_MS = 2000;
  * - Kills the process on timeout (preventing zombies)
  * - Supports cancellation via AbortSignal
  *
+ * ## Why this bound is NOT `bounded()` — the one documented exception (#2523)
+ *
+ * #2523 slice 2 folded every other "deadline AND abort signal" implementation
+ * in the tree onto `clients/deadline-utils.ts#bounded`. This one stays, and it
+ * is not a copy of the same idea:
+ *
+ * `bounded()` ABANDONS a promise — it stops waiting and lets the work run on
+ * unobserved, which is safe precisely because everything it wraps is in-process
+ * (a dynamic import, an LSP round trip, a `stat`). This function's work is a
+ * CHILD PROCESS, and abandoning one leaks it. So its timer does not settle a
+ * race at all: `timeoutId` sets `timedOut`, then runs `killTree()` — SIGTERM,
+ * an escalation timer, SIGKILL, and on Windows a `taskkill /T` of the whole
+ * tree — and the promise settles only when the child's own `close` arrives (or
+ * the escalation gives up). The result it produces carries the teardown
+ * EVIDENCE (`timeoutTeardown`, #2010): which signal killed it, whether the
+ * tree actually died, how long it took. Replacing that with `bounded()` would
+ * return `undefined` at the deadline and leave a live `vitest`/`gradle` behind
+ * — the orphan class #2504 measured as 59 concurrent spawns starving a turn.
+ *
+ * The rule the exception preserves: a bound that can CANCEL its work must
+ * cancel it. `bounded()` is for work that cannot be cancelled; this is not
+ * that. Anything wrapping THIS function still gets `bounded()` around its own
+ * await if it needs one.
+ *
  * @example
  * const result = await safeSpawnAsync("npm", ["test"], { timeout: 30000 });
  * if (result.error) console.error("Failed:", result.error);

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

@@ -6,8 +6,14 @@
  */
 // --- Constants ---
 // ANSI escape codes for colors and formatting
+// oxlint-disable-next-line no-control-regex -- ESC (\x1b) is the literal ANSI escape-sequence lead byte this pattern strips, not accidental input.
 const ANSI_ESCAPE = /\x1b\[[0-9;]*m/g;
-const ANSI_ESCAPE_EXTENDED = /\x1b\[[0-9;]*[A-Za-z]/g;
+// Full ECMA-48 CSI grammar (parameter bytes 0-9;? , intermediate bytes
+// space-/, final byte @-~) — matches every CSI sequence ANSI_ESCAPE does
+// plus non-SGR ones (cursor moves, private-mode `?` sequences like
+// `\x1b[?25l`, etc.), not just the `m`-terminated color codes.
+// oxlint-disable-next-line no-control-regex -- ESC (\x1b) is the literal ANSI escape-sequence lead byte this pattern strips, not accidental input.
+const ANSI_ESCAPE_EXTENDED = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
 // Common error patterns from different tools
 const ERROR_INDICATORS = [
     /\berror\b/i,

package/node_modules/pi-lens/dist/clients/scratch-tree-policy.js

@@ -54,6 +54,7 @@
  *     fully in scope.
  */
 import { EXCLUDED_DIRS, getExcludedDirGlobs } from "./file-utils.js";
+import { escapeRegExp } from "./string-utils.js";
 /** Directory-name entries only — drops glob entries (e.g. `*.dSYM`) that a
  * bare directory-name/regex exclude can't express. */
 function literalExcludedDirNames() {
@@ -68,9 +69,6 @@ function literalExcludedDirNames() {
 export function getScratchTreeGlobPatterns() {
     return getExcludedDirGlobs();
 }
-function escapeRegExp(literal) {
-    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 /** Bare directory names, for tools (opengrep/semgrep `--exclude`) that treat a
  * slash-free pattern as "this directory name, anywhere in the tree". */
 export function getScratchTreeDirNames() {

package/node_modules/pi-lens/dist/clients/security-scan-client.js

@@ -71,6 +71,7 @@ export class SecurityScanClient {
     logDurableAbsence(evidence, elapsedMs = 0) {
         logAvailabilityDecision({
             tool: this.toolName,
+            producer: "security-scan",
             verdict: "unavailable",
             outcome: "missing",
             cause: "not-found",
@@ -154,6 +155,7 @@ export class SecurityScanClient {
             this.log(`${this.toolName} found: ${probe.stdout.trim().split("\n")[0]}`);
             logAvailabilityDecision({
                 tool: this.toolName,
+                producer: "security-scan",
                 verdict: "available",
                 outcome: "success",
                 cause: "ok",
@@ -185,6 +187,7 @@ export class SecurityScanClient {
             : 0;
         logAvailabilityDecision({
             tool: this.toolName,
+            producer: "security-scan",
             verdict: "unavailable",
             outcome,
             cause,

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

@@ -91,7 +91,7 @@ export function getActivePrimaryRoot() {
  * `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.
+ * per file (`clients/lsp/session-roots.ts`), not from this handler.
  *
  * Ordering note: the root check sits BELOW the `priorCtxActive === true`
  * branch so a live sibling still reports the more specific

package/node_modules/pi-lens/dist/clients/session-start-observability.js

@@ -1,10 +1,42 @@
 import { logLatency } from "./latency-logger.js";
+import { getProcessSingleton } from "./process-singletons.js";
 /**
  * The complete observability path for a concurrent secondary. It deliberately
  * emits one bind record only: secondary sessions skip every primary reset and
  * hydration phase.
  */
+// #2249: bounded per-session rollup of declined binds, counted at this shared
+// seam so every decline the process's PRIMARY has seen this session —
+// `concurrent-secondary` and `secondary-root` alike — is summarized in one row
+// at session end instead of requiring a reader to hand-count
+// `concurrent_session_bind` lines. Process-singleton backed (AGENTS.md catalog
+// shape 25), NOT a module-scope `let` like the other `*_rollup` counters
+// (bus-events-logger.ts, path-attribution-telemetry.ts): a `let` here exists
+// once per module EVALUATION, not once per process, and #2146 measured one pid
+// evaluating this exact graph nine times — a bare `let` would only ever see
+// the binds routed through its own copy, undercounting every rollup that
+// isn't reached through the first evaluation. `decideSessionStart` never
+// returns a declined classification outside `concurrent-secondary`/
+// `secondary-root` (session-lifecycle.ts), so those two are the whole
+// contract; `unclassified` is a bounded third bucket for the legacy callers
+// this function's `classification?` param still accepts.
+const BIND_ROLLUP_FAMILY = "concurrent-session-bind-rollup";
+const BIND_ROLLUP_VERSION = 1;
+function bindRollupCounts() {
+    return getProcessSingleton(BIND_ROLLUP_FAMILY, BIND_ROLLUP_VERSION, () => ({
+        "concurrent-secondary": 0,
+        "secondary-root": 0,
+        unclassified: 0,
+    }));
+}
+function bindRollupKey(classification) {
+    return classification === "concurrent-secondary" ||
+        classification === "secondary-root"
+        ? classification
+        : "unclassified";
+}
 export function logConcurrentSessionBind(args) {
+    bindRollupCounts()[bindRollupKey(args.classification)] += 1;
     logLatency({
         type: "phase",
         filePath: "<pi-lens>",
@@ -13,3 +45,50 @@ export function logConcurrentSessionBind(args) {
         metadata: args,
     });
 }
+/** Snapshot of the current rollup counters, keyed by classification.
+ *  Non-mutating — for tests/observability, mirroring
+ *  `getBusEventRollupCounts`/`getVerifiedPathAttributionGuessCount`. */
+export function getConcurrentSessionBindRollupCounts() {
+    return { ...bindRollupCounts() };
+}
+/**
+ * Log one `concurrent_session_bind_rollup` row summarizing this session's
+ * declined binds by classification, then clear the counters. Call from
+ * index.ts's `session_shutdown` handler at the same primary-only placement as
+ * `emitBusEventRollupAtSessionEnd`/`emitVerifiedPathAttributionRollup` — a
+ * concurrent secondary's own shutdown returns before reaching that point, and
+ * the counters are process-wide state a still-live secondary would still need.
+ * A no-op when nothing was ever declined this session, matching those same
+ * rollups' "no noise on an ordinary session" shape.
+ */
+export function emitConcurrentSessionBindRollupAtSessionEnd(cwd) {
+    const counts = bindRollupCounts();
+    const total = counts["concurrent-secondary"] +
+        counts["secondary-root"] +
+        counts.unclassified;
+    if (total === 0)
+        return;
+    logLatency({
+        type: "phase",
+        filePath: cwd,
+        phase: "concurrent_session_bind_rollup",
+        durationMs: 0,
+        metadata: { ...counts },
+    });
+    resetConcurrentSessionBindRollupCounts();
+}
+/**
+ * Session-boundary reset (AGENTS.md catalog shape 17). Call from index.ts's
+ * `session_start` handler on the PRIMARY continuation path only — never from
+ * a declined bind's own `session_start`, which is exactly what increments
+ * these counters, so resetting there would erase every prior sibling's tally
+ * from the same primary session. Covers the case a primary session never
+ * reaches `session_shutdown` (a crash, a forced kill) and the process's next
+ * primary must still start from zero. Also exported for tests.
+ */
+export function resetConcurrentSessionBindRollupCounts() {
+    const counts = bindRollupCounts();
+    counts["concurrent-secondary"] = 0;
+    counts["secondary-root"] = 0;
+    counts.unclassified = 0;
+}

package/node_modules/pi-lens/dist/clients/sessionstart-logger.js

@@ -1,10 +1,19 @@
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
+import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
-export const SESSIONSTART_LOG_FILE = path.join(getGlobalPiLensDir(), "sessionstart.log");
+export const SESSIONSTART_LOG_FILE = path.join(getGlobalPiLensLogDir(), "sessionstart.log");
 // All ordinary writers share this queue, preserving their in-process order.
-const writer = createNdjsonLogger({ filePath: SESSIONSTART_LOG_FILE });
+// Bounded like every other global sink (#2505): an unbounded sink has no
+// size check on the write path at all, so it grows until the
+// once-per-process session-start sweep happens to look at it — which, in a
+// long-lived process (the warm MCP server), may be never.
+const writer = createNdjsonLogger({
+    filePath: SESSIONSTART_LOG_FILE,
+    maxBytes: getMaxLogSizeMB() * 1024 * 1024,
+    backupPath: `${SESSIONSTART_LOG_FILE}.1`,
+});
 export function logSessionStart(message) {
     if (isTestMode())
         return;

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

@@ -9,7 +9,12 @@ import { findLocalToolConfig } from "./path-utils.js";
 // it only operates in a project that has an `sgconfig.y[a]ml` at (or above) the
 // file. These are the names ast-grep itself looks for as root markers.
 export const SGCONFIG_NAMES = ["sgconfig.yml", "sgconfig.yaml"];
-/** Nearest `sgconfig.y[a]ml` walking up from `startDir`, or undefined if none. */
+/**
+ * Nearest `sgconfig.y[a]ml` walking up from `startDir`, or undefined if none.
+ * Deliberately UNCEILINGED at $HOME (refs #2472 review round 3, F1): ast-grep
+ * itself resolves `~/sgconfig.yml` as a legitimate global root config, not an
+ * escaped-workspace accident.
+ */
 export function findLocalSgconfig(startDir) {
     return findLocalToolConfig(startDir, SGCONFIG_NAMES);
 }

package/node_modules/pi-lens/dist/clients/skills-resolver.js

@@ -0,0 +1,105 @@
+/**
+ * Resolves the skills directory the `resources_discover` handler (#205)
+ * registers, and reports the one condition that pi previously loaded with NO
+ * visible signal: `<packageRoot>/skills` is absent, unreadable, or holds no
+ * skill pi's own loader would find (#2626).
+ *
+ * `resolvePackagePath(import.meta.url, "skills")`-equivalent resolution
+ * (`clients/package-root.ts`'s `getPackageRoot`) is correct for both the
+ * source and compiled `dist/` layouts — it walks up from the loaded entry
+ * file to the nearest `package.json`. It goes wrong silently, not loudly,
+ * when that walk lands somewhere with no `skills/` beside it: `skills/`
+ * missing from an installed package, or the entry file copied out of the
+ * package tree by a managed extension cache so the nearest `package.json`
+ * is the cache's own. Either way `resources_discover` used to hand pi a
+ * path that does not exist, `pi` registered zero skills, and nothing — no
+ * extension error, no stderr line — said so (investigated on #2587).
+ *
+ * #2626 review round 2, F1: the FIRST version of this fix inverted the
+ * acceptance criterion — it returned `[]` (no skills registered) whenever
+ * its own predicate disagreed with pi's real loader, which is worse than
+ * the bug it fixed on every layout the predicate got wrong (dropping skills
+ * pi WOULD have loaded, a regression vs. pre-fix `master`). The acceptance
+ * criteria ask for a RECORD, never a changed return value: this module
+ * returns `[skillsDir]` UNCONDITIONALLY, exactly like the pre-fix handler —
+ * pi's own `loadSkills`/`collectSkillEntries` already treat a nonexistent
+ * path as zero skills from that entry, gracefully, so handing it a path
+ * that turns out to be empty is exactly as safe as `master`'s behavior
+ * always was. The health check below is PURELY observational.
+ *
+ * #2636 review F4: the ENOENT/EACCES classification shell below used to be
+ * hand-rolled here, character-identical to the ast-grep/tree-sitter sites
+ * #2636 fixed for the same silent-zero shape — now shared via
+ * `bundled-resource-health.ts`, with `scanEntriesForSkills` supplied as this
+ * module's own "what counts as found" predicate.
+ */
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as fs from "node:fs";
+import { scanEntriesForSkills } from "../scripts/lib/skills-predicate.mjs";
+import { classifyBundledResourceDir, describeBundledResourceHealth, reportBundledResourceDirHealth, } from "./bundled-resource-health.js";
+import { logLatency } from "./latency-logger.js";
+import { getPackageRoot } from "./package-root.js";
+/** The ledger kind this module records under (`clients/degradation-ledger.ts`). */
+const SKILLS_DIR_MISSING_KIND = "skills-dir-missing";
+/**
+ * Read `skillsDir` and classify it, sharing `classifyBundledResourceDir`'s
+ * ENOENT/EACCES/empty shell but counting pi-LOADABLE skill entry points
+ * (`scanEntriesForSkills`), not a bare directory listing — a `skills/`
+ * holding only a stray `.gitkeep` must read "empty", not "healthy".
+ */
+function checkSkillsHealth(skillsDir) {
+    return classifyBundledResourceDir(skillsDir, (dir) => {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        return scanEntriesForSkills(dir, entries, true).length;
+    });
+}
+/**
+ * Resolve the skill path for `resources_discover`. ALWAYS returns
+ * `[skillsDir]` (see the module doc for why — F1). When `skillsDir` is
+ * absent, unreadable, or holds no skill pi's loader would find, records ONE
+ * bounded `skills-dir-missing` degradation and a single `notifyUserDegradation`
+ * warning, both naming the resolved path and the entry file's directory.
+ *
+ * Either way, one `skills_resolved` phase/latency record is written so an
+ * empty ledger (no `skills-dir-missing` row) is distinguishable from
+ * "`resources_discover` never ran at all" (#2626 review F5) — the SAME
+ * silent-zero shape one level up the call stack.
+ */
+export function resolveSkillPaths(importMetaUrl) {
+    const packageRoot = getPackageRoot(importMetaUrl);
+    const skillsDir = path.join(packageRoot, "skills");
+    const health = checkSkillsHealth(skillsDir);
+    logLatency({
+        type: "phase",
+        phase: "skills_resolved",
+        filePath: skillsDir,
+        durationMs: 0,
+        metadata: {
+            status: health.status,
+            entryCount: health.status === "healthy" ? health.entryCount : 0,
+        },
+    });
+    if (health.status !== "healthy") {
+        const entryDir = path.dirname(fileURLToPath(importMetaUrl));
+        const reason = `${describeBundledResourceHealth(health, skillsDir, `no SKILL.md (or loadable .md) found under ${skillsDir}`)} (entry loaded from ${entryDir})`;
+        // #2626 review F3: the notify-once gate previously re-derived "have we
+        // already recorded this" by scanning `getDegradationSummary()` and
+        // comparing the RAW `skillsDir` against subjects the ledger stores
+        // `truncateForLedger`-ed — a mismatch on any subject over
+        // `LEDGER_FIELD_MAX` (200 chars, an ordinary length for a managed-cache
+        // path) renotified on every call. `reportBundledResourceDirHealth`
+        // reads `incrementDegradationCount`'s own return value for the rising
+        // edge, computed after the SAME truncation the ledger stores by, so
+        // there is no separate key to keep in sync.
+        // #2636 review round 2, F1: the shipped notify sentence ("registers
+        // zero skills") is user-visible product text #2626 chose deliberately
+        // — it names the exact SYMPTOM this whole issue exists to surface, so
+        // the shared helper's generic "<label> unavailable" template must
+        // never silently replace it. Passed explicitly rather than inferred
+        // from `label` so this stays a per-caller decision, not a convention
+        // the next caller has to remember.
+        reportBundledResourceDirHealth(SKILLS_DIR_MISSING_KIND, skillsDir, health, "skills", reason, `pi-lens: registers zero skills — ${reason}.`);
+    }
+    return [skillsDir];
+}

package/node_modules/pi-lens/dist/clients/smells-rollup.js

@@ -55,7 +55,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 /** Bounded tail-read budget PER source log file — never a full-file scan. */
 export const SMELLS_TAIL_BYTES_PER_FILE = 64 * 1024;
 export const SMELLS_ROLLING_WINDOW_MS = 24 * 60 * 60_000;
@@ -159,7 +159,7 @@ function isOpengrepRespawn(entry) {
  * `2 * SMELLS_TAIL_BYTES_PER_FILE` regardless of how large the (size-rotated,
  * up to ~10MB) source files are. `root` is injectable for tests.
  */
-export function countRecentSmells(root = getGlobalPiLensDir(), sessionStartMs) {
+export function countRecentSmells(root = getGlobalPiLensLogDir(), sessionStartMs) {
     const sinceMs = sessionStartMs ?? Date.now() - SMELLS_ROLLING_WINDOW_MS;
     const busTail = tailReadText(path.join(root, "bus-events.log"), SMELLS_TAIL_BYTES_PER_FILE);
     const latencyTail = tailReadText(path.join(root, "latency.log"), SMELLS_TAIL_BYTES_PER_FILE);

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

@@ -18,3 +18,16 @@
 export function compareOrdinal(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+/**
+ * Escape a string for safe interpolation into a `RegExp` source, so every
+ * regex metacharacter it contains is matched literally instead of taking on
+ * its regex meaning. This is the ONE runtime copy (#2558) — string-utils.ts
+ * is a leaf (no imports of its own), so importing it never creates a cycle.
+ * Before #2558 this same body was hand-copied under this name (and as
+ * `escapeRegExpChar`/`escapeRegExpLiteral`) into ~8 production modules and 3
+ * test helpers; fold new call sites onto this export instead of re-copying
+ * it.
+ */
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/node_modules/pi-lens/dist/clients/subagent-mode.js

@@ -4,8 +4,16 @@
  * Two known subagent-spawning ecosystems set different env vocabularies in
  * every spawned child's environment:
  *
- * - nicobailon/pi-subagents sets `PI_SUBAGENT_CHILD=1` unconditionally (plus
- *   `PI_SUBAGENT_RUN_ID` / `PI_SUBAGENT_CHILD_AGENT` for best-effort identity).
+ * - nicobailon/pi-subagents sets `PI_SUBAGENT_CHILD=1` unconditionally on
+ *   every process that hosts a child session — the only var light mode keys
+ *   on for this vocabulary. It ALSO used to set `PI_SUBAGENT_RUN_ID` /
+ *   `PI_SUBAGENT_CHILD_AGENT` alongside it for best-effort identity, but
+ *   removed both entirely in `pi-subagents@0.65.0`'s native-AgentSession
+ *   rewrite (grep-verified absent from the whole 0.66.0 source tree, #2581/
+ *   #2680) — child identity now travels through an in-process object, not
+ *   env vars. `getSubagentIdentity()` below already treats identity as
+ *   optional best-effort metadata, so this permanent absence for the
+ *   nicobailon vocabulary needed no behavior change, only the doc update.
  * - avtc-pi-subagent (the spawn engine under avtc-pi-feature-flow) is the same
  *   execution model — real child-process `pi --mode rpc` / `--mode json -p`
  *   spawns, full env inheritance — but never sets `PI_SUBAGENT_CHILD`. It sets
@@ -63,8 +71,13 @@ export function isSubagentSession() {
 /**
  * Best-effort identity of the current subagent, read from the env vars the
  * detected extension sets alongside its subagent marker. Returns `undefined`
- * when neither identity var is present (e.g. not a subagent session, or a
- * future extension that doesn't set them).
+ * when neither identity var is present — not a subagent session, an
+ * extension that never set them, OR nicobailon/pi-subagents@0.65.0+, which
+ * removed both identity vars upstream while still setting `PI_SUBAGENT_CHILD`
+ * (#2581/#2680): light mode still engages via `isSubagentSession()` alone,
+ * `marker` is still populated, only `runId`/`agentName` degrade to
+ * `undefined`. Identity is metadata for observability, never a light-mode
+ * gate — callers must not treat its absence as "not a subagent".
  */
 export function getSubagentIdentity() {
     const runId = process.env.PI_SUBAGENT_RUN_ID || undefined;