@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/bounded-cache.js

@@ -1,30 +1,73 @@
-/** Small insertion-ordered LRU used for process-lifetime memo tables. */
-export class BoundedLruCache {
-    maxEntries;
+/**
+ * Small insertion-ordered FIFO map used for process-lifetime memo tables
+ * whose eviction order must not be perturbed by reads: `get` never
+ * re-inserts, and `set` never reorders an already-present key — it behaves
+ * exactly like native `Map#set` on an existing key. A caller that wants a
+ * WRITE (not a read) to refresh recency does its own `delete` + `set` around
+ * this map, exactly as it would against a raw `Map` (#2442).
+ *
+ * {@link BoundedLruCache} extends this class and overrides exactly the two
+ * methods that differ (`get` re-inserts; `set` deletes first so a write moves
+ * the key to most-recently-used). Eviction, capacity and the whole `Map`-ish
+ * surface live here once — the two classes shipped as near-identical copies
+ * until #2442's review round flagged the duplication.
+ */
+export class BoundedFifoMap {
     entries = new Map();
+    maxEntries;
     constructor(maxEntries) {
         this.maxEntries = maxEntries;
     }
     get(key) {
-        const value = this.entries.get(key);
-        if (value !== undefined) {
-            this.entries.delete(key);
-            this.entries.set(key, value);
-        }
-        return value;
+        return this.entries.get(key);
     }
     has(key) {
         return this.entries.has(key);
     }
+    /**
+     * Insert or update `key` without reordering. Evicts the oldest
+     * (insertion-order) entries once the map exceeds capacity.
+     *
+     * Returns the evicted `[key, value]` pairs, oldest first — callers with
+     * eviction-side bookkeeping use the return value instead of hand-rolling
+     * `keys().next().value` (#2442). The VALUE is returned, not just the key,
+     * because the eviction-coupled sites need it: `tree-sitter-cache.ts` has to
+     * retire the dropped entry's WASM-heap tree (#417/#890) and
+     * `tree-sitter-client.ts` has to `delete()` the dropped compiled query.
+     * Handing back only the key would force those sites to read the value out
+     * of the map before eviction — i.e. to hand-roll the block this class
+     * exists to delete.
+     */
     set(key, value) {
-        this.entries.delete(key);
         this.entries.set(key, value);
+        return this.evictOverflow();
+    }
+    /**
+     * Change the capacity ceiling, evicting down to it immediately when it
+     * shrinks. Returns the evicted `[key, value]` pairs, oldest first, on the
+     * same contract as {@link set} — a caller with a DYNAMIC cap (an env-read
+     * ceiling, `TreeCache.setMaxSize`) needs the shrink to free the same
+     * resources an ordinary overflow frees.
+     */
+    setMaxEntries(maxEntries) {
+        this.maxEntries = maxEntries;
+        return this.evictOverflow();
+    }
+    /** Current capacity ceiling. */
+    getMaxEntries() {
+        return this.maxEntries;
+    }
+    /** Drop oldest-first until within capacity. The one eviction block. */
+    evictOverflow() {
+        const evicted = [];
         while (this.entries.size > this.maxEntries) {
-            const oldest = this.entries.keys().next().value;
+            const oldest = this.entries.entries().next().value;
             if (oldest === undefined)
                 break;
-            this.entries.delete(oldest);
+            this.entries.delete(oldest[0]);
+            evicted.push(oldest);
         }
+        return evicted;
     }
     delete(key) {
         return this.entries.delete(key);
@@ -48,3 +91,100 @@ export class BoundedLruCache {
         return this.entries[Symbol.iterator]();
     }
 }
+/**
+ * Small insertion-ordered FIFO SET used for process-lifetime membership-only
+ * caps — "is this key known", with no associated value.
+ *
+ * A thin wrapper over `BoundedFifoMap<T, true>` (#2460 review T1): eviction,
+ * capacity and the whole Map-ish surface already live in `BoundedFifoMap`
+ * exactly once, and this class's earlier standalone `Set`-backed
+ * implementation was a byte-for-byte copy of that eviction block one layer
+ * down — the exact duplication `BoundedFifoMap`'s own header describes
+ * `BoundedLruCache` existing to delete (#2442). The `true` dummy value never
+ * escapes this wrapper: it is not a cost paid by call sites, only by this
+ * file, so the earlier objection to building membership on top of the K,V
+ * map (#2460's first review, about `clients/observed-mutation.ts`'s
+ * `handled` set) does not apply here — that objection was about a caller
+ * storing a dummy value itself, not about a wrapper hiding one.
+ *
+ * Same eviction contract as {@link BoundedFifoMap}: `add` never reorders an
+ * already-present member (matches native `Set#add`), and both `add` and
+ * {@link setMaxEntries} return the evicted values, oldest first, so a call
+ * site with an eviction side effect (naming the dropped identity in a bounded
+ * telemetry record) consumes the return value instead of hand-rolling
+ * `values().next().value` or a `for (... of set) { …; break }` walk (#2442).
+ */
+export class BoundedSet {
+    entries;
+    constructor(maxEntries) {
+        this.entries = new BoundedFifoMap(maxEntries);
+    }
+    has(value) {
+        return this.entries.has(value);
+    }
+    /**
+     * Insert `value` without reordering an already-present member. Evicts the
+     * oldest (insertion-order) members once the set exceeds capacity.
+     *
+     * Returns the evicted values, oldest first — see the class doc for why a
+     * call site consumes this instead of hand-rolling the drop.
+     */
+    add(value) {
+        return this.entries.set(value, true).map(([evicted]) => evicted);
+    }
+    /**
+     * Change the capacity ceiling, evicting down to it immediately when it
+     * shrinks. Returns the evicted values, oldest first, on the same contract
+     * as {@link add}.
+     */
+    setMaxEntries(maxEntries) {
+        return this.entries.setMaxEntries(maxEntries).map(([evicted]) => evicted);
+    }
+    /** Current capacity ceiling. */
+    getMaxEntries() {
+        return this.entries.getMaxEntries();
+    }
+    delete(value) {
+        return this.entries.delete(value);
+    }
+    clear() {
+        this.entries.clear();
+    }
+    get size() {
+        return this.entries.size;
+    }
+    values() {
+        return this.entries.keys();
+    }
+    [Symbol.iterator]() {
+        return this.entries.keys();
+    }
+}
+/**
+ * Small insertion-ordered LRU used for process-lifetime memo tables. Same
+ * bounded-`Map` surface as {@link BoundedFifoMap}; the only two differences
+ * are overridden below.
+ */
+export class BoundedLruCache extends BoundedFifoMap {
+    /**
+     * Read and promote to most-recently-used.
+     *
+     * A stored `undefined` value is NOT promoted — the hit is indistinguishable
+     * from a miss on this signature, and pre-#2442 `BoundedLruCache` behaved
+     * the same way. No caller stores `undefined`; the note exists so a future
+     * one does not assume otherwise.
+     */
+    get(key) {
+        const value = this.entries.get(key);
+        if (value !== undefined) {
+            this.entries.delete(key);
+            this.entries.set(key, value);
+        }
+        return value;
+    }
+    /** Insert or update `key`, moving it to the most-recently-used position. */
+    set(key, value) {
+        this.entries.delete(key);
+        return super.set(key, value);
+    }
+}

package/node_modules/pi-lens/dist/clients/bounded-telemetry.js

@@ -10,9 +10,9 @@
  * get the bounding right. This module is the intersection of those four, not
  * a speculative framework. Three of its four options come straight from those
  * sites. The fourth, `capPerTurn`, expresses #1733's per-turn bound
- * structurally but has no caller yet: that site's bound is its call cadence,
- * and pinning a cap there would red its own wiring tests. It ships tested and
- * mutation-proofed, awaiting its first site.
+ * structurally and now caps re-raised auxiliary coverage-gap detail rows
+ * (#2356), while the aggregate count and ledger retain bounded latest
+ * identities plus the dropped count.
  *
  * Three rules the helper makes structural instead of prose:
  *
@@ -38,7 +38,7 @@
  * stated reason for staying raw.
  *
  * Nothing here ever throws. Telemetry must not perturb the path it observes —
- * every one of the four migrated sites had already decided its outcome before
+ * each caller has already decided its outcome before
  * calling in.
  */
 import { incrementDegradationCount } from "./degradation-ledger.js";
@@ -50,6 +50,13 @@ import { logLatency } from "./latency-logger.js";
  * must not also be written by a raw `logLatency` call somewhere else.
  */
 export const BOUNDED_TELEMETRY_PHASES = [
+    /**
+     * #2467: a demand for the analyzer bootstrap clients was not served and
+     * the caller proceeded without them. Rising-edge per demand reason, with
+     * the ledger holding the exact count — a wedged or missing analyzer graph
+     * must not turn every tool call into a log line.
+     */
+    "bootstrap_clients_unavailable",
     /** #1705: a deferred-format record whose origin worktree never claimed it. */
     "agent_end_deferred_format_orphan_origin_mismatch",
     /** #1713: a `textDocument`/`workspace` diagnostic pull abandoned at budget. */
@@ -92,6 +99,8 @@ export const BOUNDED_TELEMETRY_PHASES = [
      * the state cap. Selection checks and detailed rows are both capped per turn.
      */
     "test_runner_failed_target_state",
+    /** #2366: bounded lifecycle records for automatic test-result delivery. */
+    "test_runner_delivery",
     /**
      * #1723: an event-loop block at or above the floor. Not a degradation, so
      * no ledger kind; bounded by call cadence (one `turn_end` runs it once per
@@ -115,6 +124,52 @@ export const BOUNDED_TELEMETRY_PHASES = [
      * command was declined on an UNKNOWN rather than assumed clean.
      */
     "shared_checkout_probe_failed",
+    /** #2356: a notify-stall auxiliary remained uncovered after its bounded
+     * replacement window. Detailed rows are capped per turn; the ledger and
+     * aggregate turn-end row retain the complete count and identity. */
+    "lsp_scanner_coverage_gap",
+    /** #2358: a busy CPU discriminator deferred notify-stall teardown. */
+    "lsp_notify_stall_cpu_busy",
+    /**
+     * #2430: an observational pre/post snapshot was declined or cut short — the
+     * per-turn budget was already spent, the capture timed out, or the turn was
+     * aborted. Every unclassified tool call in a busy turn can reach this, so
+     * it is capped per turn with the ledger holding the exact count.
+     */
+    "observed_mutation_budget_exhausted",
+    /**
+     * #2430: the `agent_settled` tracked-file sweep could not complete within
+     * its bound. Once per settle at most, capped for the same reason.
+     */
+    "observed_sweep_skipped_budget",
+    /**
+     * #2430: a tracked file's size/mtime moved but no hashed baseline could
+     * confirm the bytes actually changed — too large for the sweep's read
+     * budget, or never hashed. Named rather than replayed, because a `touch`
+     * moves mtime without moving a byte (#2449 review round 2, F7). Bounded
+     * per turn: one settle can find many such files at once.
+     */
+    "observed_sweep_unverifiable",
+    /**
+     * #2430: an armed observation's universe was TRUNCATED because the tool
+     * named a directory with more entries than the net may watch. Bounded per
+     * turn with the ledger holding the exact count, and the identity is the
+     * tool name so the record answers WHICH tool is being watched partially
+     * (#2449 review round 3).
+     */
+    "observed_target_dir_capped",
+    /**
+     * #2430: the "pi-lens wrote these bytes itself" set hit
+     * `OBSERVED_HANDLED_MAX` and dropped its oldest entry. The dropped file is
+     * NAMED, because the eviction silently reintroduces the exact defect
+     * #2449 round 3 (S5) fixed: the ledger still holds the pre-drain bytes
+     * while the only record that those bytes were ours is gone, so the next
+     * settled sweep replays pi-lens's own formatter output as third-party
+     * drift. A cap that drops a mark has to say which one (catalog shape 10);
+     * capped per turn because a turn that overflows the set overflows it many
+     * times (#2449 review round 4, S2).
+     */
+    "observed_handled_evicted",
 ];
 const REGISTERED_PHASES = new Set(BOUNDED_TELEMETRY_PHASES);
 /** Report whether a phase name is in the registry (used by the sweep). */

package/node_modules/pi-lens/dist/clients/bundled-resource-health.js

@@ -0,0 +1,113 @@
+/**
+ * Shared health classification + degradation reporting for a bundled
+ * resource directory read DIRECTLY by pi-lens (never handed to an external
+ * spawned tool as a `--config`/`--rule-dir` argument — that class already
+ * fails loudly through the tool's own spawn-failure path).
+ *
+ * #2626 fixed this shape for `clients/skills-resolver.ts`'s `skills/`
+ * directory: `resolvePackagePath(import.meta.url, …)` walks up from the
+ * loaded entry file to the nearest `package.json`, which is correct for both
+ * the source and compiled `dist/` layouts, but goes wrong SILENTLY, not
+ * loudly, when that walk lands somewhere with no resource dir beside it —
+ * the bundled dir 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. #2636 is the class sweep:
+ * `clients/ast-grep-client.ts`'s `rules` fallback and the bundled
+ * tree-sitter-queries root (read identically by `clients/cache/rule-cache.ts`
+ * and `clients/tree-sitter-query-loader.ts`) have the exact same gap.
+ *
+ * Both callers reuse this ONE classify+report pair rather than each
+ * hand-rolling the ENOENT/EACCES distinction (#2626 review F4) a second and
+ * third time.
+ */
+import * as fs from "node:fs";
+import { incrementDegradationCount, } from "./degradation-ledger.js";
+import { notifyUserDegradation } from "./user-notify.js";
+/**
+ * Classify `dir`: does it exist, is it readable, and does it hold anything?
+ * Fail-closed and never throws. Distinguishes `ENOENT` (the common
+ * managed-cache-relocation case) from any OTHER `readdirSync` error
+ * (`EACCES` and friends) — an unreadable directory might genuinely hold a
+ * real resource pi-lens simply cannot read, so the honest report is "cannot
+ * read it", never "nothing is there" (#2626 review F4).
+ *
+ * `countEntries` lets a caller supply its OWN notion of "found" — e.g.
+ * `skills-resolver.ts` counts pi-loadable skill entry points via
+ * `scanEntriesForSkills`, not a bare directory listing — while still sharing
+ * this function's ENOENT/EACCES/empty classification shell (#2636 review F4:
+ * that shell was duplicated character-for-character between the two modules
+ * before this parameter existed). The default counts plain directory
+ * entries, which is what every OTHER caller (ast-grep's rules dir, the
+ * bundled tree-sitter-queries root) actually wants.
+ */
+export function classifyBundledResourceDir(dir, countEntries = (d) => fs.readdirSync(d).length) {
+    let entryCount;
+    try {
+        entryCount = countEntries(dir);
+    }
+    catch (error) {
+        const fsErrorCode = error?.code ?? "UNKNOWN";
+        if (fsErrorCode === "ENOENT")
+            return { status: "absent" };
+        return { status: "unreadable", fsErrorCode };
+    }
+    return entryCount > 0
+        ? { status: "healthy", entryCount }
+        : { status: "empty" };
+}
+/**
+ * Render `health` as a reason string. `emptyDescription` lets a caller name
+ * what "nothing found" actually means for its own resource (skills' loader
+ * cares about `SKILL.md`, not bare directory entries); every other status's
+ * prose is shared verbatim, since ENOENT/EACCES mean the exact same thing
+ * regardless of which resource directory hit them.
+ */
+export function describeBundledResourceHealth(health, dir, emptyDescription = `${dir} exists but holds nothing`) {
+    switch (health.status) {
+        case "absent":
+            return `no such directory: ${dir}`;
+        case "unreadable":
+            return `cannot read ${dir} (${health.fsErrorCode})`;
+        case "empty":
+            return emptyDescription;
+        default:
+            // unreachable for the "healthy" case — callers only report unhealthy ones.
+            return `${dir}: unexpected health status`;
+    }
+}
+/**
+ * Record ONE bounded `kind` degradation plus one `notifyUserDegradation`
+ * warning per (kind, dir) per session, when `health` is not healthy.
+ * Pure no-op when healthy. `incrementDegradationCount`'s own return value
+ * (not a hand-rolled Set) gates the notify to the rising edge, so a caller
+ * invoked on every dispatch (e.g. `RuleCache`'s constructor) can call this
+ * unconditionally without spamming the notify surface.
+ *
+ * `reasonOverride` lets a caller build a richer reason (skills-resolver.ts
+ * appends the entry file's directory) while still sharing the
+ * increment/notify mechanics below; the default is this module's own
+ * `describeBundledResourceHealth`.
+ *
+ * `notifyMessage` lets a caller replace the DEFAULT `pi-lens: <label>
+ * unavailable — <reason>.` sentence with its own finished wording (#2636
+ * review round 2, F1): `skills-resolver.ts`'s shipped notify text ("registers
+ * zero skills") is user-visible product text #2626 chose deliberately — the
+ * SYMPTOM the notification exists to surface — and folding onto this shared
+ * helper must never silently reword a string a maintainer already tuned.
+ */
+export function reportBundledResourceDirHealth(kind, dir, health, label, reasonOverride, notifyMessage) {
+    if (health.status === "healthy")
+        return;
+    const reason = reasonOverride ?? describeBundledResourceHealth(health, dir);
+    const isFirstOccurrence = incrementDegradationCount({
+        kind,
+        subject: dir,
+        reason,
+        metadata: health.status === "unreadable"
+            ? { fsErrorCode: health.fsErrorCode }
+            : undefined,
+    });
+    if (isFirstOccurrence) {
+        notifyUserDegradation(notifyMessage ?? `pi-lens: ${label} unavailable — ${reason}.`, "warning");
+    }
+}

package/node_modules/pi-lens/dist/clients/bus-events-logger.js

@@ -44,11 +44,11 @@
  */
 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 { createNdjsonLogger } from "./ndjson-logger.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { logLatency } from "./latency-logger.js";
-const BUS_EVENTS_LOG_FILE = path.join(getGlobalPiLensDir(), "bus-events.log");
+const BUS_EVENTS_LOG_FILE = path.join(getGlobalPiLensLogDir(), "bus-events.log");
 const writer = createNdjsonLogger({
     filePath: BUS_EVENTS_LOG_FILE,
     maxBytes: getMaxLogSizeMB() * 1024 * 1024,

package/node_modules/pi-lens/dist/clients/cache/rule-cache.js

@@ -7,9 +7,10 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { reportBundledResourceDirHealth } from "../bundled-resource-health.js";
 import { getProjectDataDir } from "../file-utils.js";
 import { readJsonCache } from "../json-cache-read.js";
-import { resolvePackagePath } from "../package-root.js";
+import { BUNDLED_QUERIES_ROOT, getBundledQueriesRootHealth, } from "../tree-sitter-query-loader.js";
 import { writeFileAtomic } from "../atomic-write.js";
 import { compareOrdinal } from "../string-utils.js";
 // v4: cache skip_test_files + fix_action — v3 entries silently dropped them,
@@ -48,11 +49,36 @@ export const CACHE_VERSION = "v7";
  * on this prefix mirrors the split `yaml-rule-parser.ts`/`ast-grep-napi.ts`
  * already use for the ast-grep side of the same class (#1105): project-origin
  * trees get a content-hash CONFIRM, bundled trees stay mtime-cheap.
+ *
+ * #2636 review F4: re-exported from `tree-sitter-query-loader.ts`'s
+ * `BUNDLED_QUERIES_ROOT` rather than computed a second time here — the two
+ * modules read the IDENTICAL physical directory, and the "one ledger row"
+ * claim below rests on that being reference equality, not two independently
+ * `resolvePackagePath`-resolved strings that happen to match.
  */
-const BUNDLED_RULES_ROOT = resolvePackagePath(import.meta.url, "rules", "tree-sitter-queries");
+export { BUNDLED_QUERIES_ROOT as BUNDLED_RULES_ROOT } from "../tree-sitter-query-loader.js";
 function isBundledRuleFile(resolvedFile) {
-    return (resolvedFile === BUNDLED_RULES_ROOT ||
-        resolvedFile.startsWith(BUNDLED_RULES_ROOT + path.sep));
+    return (resolvedFile === BUNDLED_QUERIES_ROOT ||
+        resolvedFile.startsWith(BUNDLED_QUERIES_ROOT + path.sep));
+}
+/**
+ * #2636 (the #2626 class sweep's tree-sitter leg): the bundled
+ * tree-sitter-queries root above was used unconditionally with no existence
+ * check — same managed-cache-relocation gap #2626 fixed for `skills/`.
+ * Purely observational (never gates `isBundledRuleFile`'s classification):
+ * records a bounded `tree-sitter-queries-dir-missing` degradation only when
+ * the bundled root is absent, unreadable, or (uncommonly) present but empty.
+ * Shares the exact kind + subject `clients/tree-sitter-query-loader.ts`'s
+ * `ruleFilesForLanguage` reports under — both read the SAME physical
+ * directory (`getBundledQueriesRootHealth`'s process-lifetime memo, #2636
+ * review F6 — this constructor runs per dispatched file, so an unmemoized
+ * `readdirSync` here would be the same unconditional hot-path cost the
+ * class doc comment above forbids for rule-file hashing), so the ledger's
+ * own (kind, subject) dedup collapses whichever call site observes it first
+ * into ONE row rather than two duplicates.
+ */
+function reportBundledRulesRootHealth() {
+    reportBundledResourceDirHealth("tree-sitter-queries-dir-missing", BUNDLED_QUERIES_ROOT, getBundledQueriesRootHealth(), "bundled tree-sitter query rules");
 }
 export class RuleCache {
     cacheFile;
@@ -60,6 +86,7 @@ export class RuleCache {
     language;
     constructor(language, rootDir = process.cwd()) {
         this.language = language;
+        reportBundledRulesRootHealth();
         this.cacheDir = path.join(getProjectDataDir(rootDir), "cache");
         this.cacheFile = path.join(this.cacheDir, `${language}-rules-${CACHE_VERSION}.json`);
     }

package/node_modules/pi-lens/dist/clients/cache-manager.js

@@ -3,10 +3,14 @@
  *
  * Manages persistent cache for scanner results and turn state.
  * Provides read/write/freshness checks for:
- * - Scanner cache: .pi-lens/cache/{scanner}.json
- * - Turn state: .pi-lens/turn-state.json
+ * - Scanner cache: <project-data-dir>/cache/{scanner}.json
+ * - Turn state: <project-data-dir>/turn-state.json
  *
- * All paths are relative to project root (process.cwd()).
+ * `<project-data-dir>` is `getProjectDataDir(cwd)` (clients/file-utils.ts) --
+ * `<cwd>/.pi-lens` only when that legacy directory already exists, otherwise
+ * `~/.pi-lens/projects/<slug>` or a `PILENS_DATA_DIR` location. Never assume
+ * the legacy spelling, and never show it to an agent: build a displayed path
+ * with `displayProjectDataPath` (#2521).
  */
 import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
@@ -14,7 +18,7 @@ import * as path from "node:path";
 import { getProjectDataDir } from "./file-utils.js";
 import { writeFileAtomic } from "./atomic-write.js";
 import { readJsonCache } from "./json-cache-read.js";
-import { normalizeMapKey } from "./path-utils.js";
+import { isUnderDir, normalizeMapKey } from "./path-utils.js";
 // --- Defaults ---
 const DEFAULT_MAX_AGE_MS = 30 * 60 * 1000; // 30 minutes
 const DEFAULT_TURN_STATE = {
@@ -58,6 +62,31 @@ export class CacheManager {
     /**
      * Get turn-state entry for a file path using normalized lookup.
      */
+    /**
+     * #2504: is this path inside the PROJECT the worklist belongs to?
+     *
+     * Routed through `isUnderDir` (which normalises via `normalizeFilePath`) so
+     * the answer is separator- and case-form independent, the same key rule
+     * every other turn-state map obeys.
+     *
+     * The root is the PROJECT root, not the caller's `cwd` (#2504 review round
+     * 2, F1). The two coincide for every producer whose `cwd` IS the session
+     * root, but not for `clients/lsp-mutation.ts`: `tools/lsp-navigation.ts`
+     * threads a `cwd`-scoped context for a call issued from a sub-package
+     * directory, so a monorepo-wide server's edit on a SIBLING package is
+     * inside the project and outside that `cwd`. Judging it against `cwd`
+     * dropped exactly the server-initiated edits #2450/#2479 exist to record.
+     * This is the same root `isRecordableProjectPath` (clients/file-utils.ts)
+     * is given at that call site — one predicate root, taken from
+     * `runtime.projectRoot`, not two that can disagree.
+     */
+    isTurnStatePathWithinRoot(filePath, projectRoot) {
+        const root = path.resolve(projectRoot);
+        const abs = path.resolve(root, filePath);
+        if (normalizeMapKey(abs) === normalizeMapKey(root))
+            return false;
+        return isUnderDir(abs, root);
+    }
     getTurnFileState(filePath, cwd) {
         const state = this.readTurnState(cwd);
         const key = this.toTurnStateKey(filePath, cwd);
@@ -217,9 +246,22 @@ export class CacheManager {
     /** Return whether a writer may read/write this workspace worklist. */
     getTurnStateAccess(cwd, owner) {
         const state = this.readTurnState(cwd);
+        const hasFiles = Object.keys(state.files ?? {}).length > 0;
         if (!state.owner) {
-            if (!state.sessionId || state.sessionId === owner.id)
+            if (!state.sessionId || state.sessionId === owner.id) {
+                // #2504: an OWNERLESS state was unconditionally "owned" here, and
+                // ownerless was the resting shape (pre-#2504 `clearTurnState`
+                // dropped the owner and `addModifiedRange` only stamps one when a
+                // sessionId is supplied). A worklist persisted by a session that
+                // has since exited was therefore adopted wholesale by the next
+                // session — 154 historical paths reported as "modified this turn"
+                // on a turn that made no tool calls at all. A worklist whose last
+                // write predates this session's start is not this session's work.
+                if (hasFiles && this.turnStatePredatesSession(state, owner)) {
+                    return "available";
+                }
                 return "owned";
+            }
             // Pre-owner files have no liveness information. Preserve the existing
             // stale-session eviction behavior for this legacy shape.
             return "available";
@@ -227,10 +269,35 @@ export class CacheManager {
         if (state.owner.kind === owner.kind && state.owner.id === owner.id) {
             return "owned";
         }
+        // #2504: an EMPTY worklist carries nothing to protect, so it never
+        // latches a foreign writer out. This keeps the new `clearTurnState`
+        // owner stamp from turning a cleared worklist into a cross-process lock:
+        // an MCP writer in another process must still be able to register work
+        // against a worklist a pi session just cleared, exactly as it could when
+        // clearing left the state ownerless.
+        if (!hasFiles)
+            return "owned";
         return this.isTurnStateOwnerStale(state.owner)
             ? "available"
             : "foreign-live";
     }
+    /**
+     * #2504: true when this worklist was last written before the asking
+     * session began. `lastUpdated` is restamped by `writeTurnState` on EVERY
+     * write (add/clear/cycle), so a live session's own worklist is always
+     * newer than its start; only a carried-over file can be older. An
+     * unparseable stamp is treated as stale — a worklist we cannot date is
+     * exactly the legacy shape this gate exists to evict.
+     */
+    turnStatePredatesSession(state, owner) {
+        const startedAt = owner.sessionStartedAt;
+        if (startedAt === undefined || !Number.isFinite(startedAt))
+            return false;
+        const lastUpdated = Date.parse(state.lastUpdated ?? "");
+        if (!Number.isFinite(lastUpdated))
+            return true;
+        return lastUpdated < startedAt;
+    }
     isTurnStateOwnerStale(owner) {
         if (owner.pid > 0 && owner.pid !== process.pid) {
             try {
@@ -250,7 +317,24 @@ export class CacheManager {
      * current owner; callers must provide an explicit owner id to claim a stale
      * worklist.
      */
-    addModifiedRange(filePath, range, importsChanged, cwd, sessionId, ownerKind = "pi") {
+    addModifiedRange(filePath, range, importsChanged, cwd, sessionId, ownerKind = "pi", projectRoot) {
+        // #2504: the worklist is a PROJECT worklist. A path outside the project
+        // was accepted and keyed by its absolute path, so a prior session's
+        // scratchpad, `~/.claude/plans/*.md` and `~/.plegma/work/.../TASK.md`
+        // all became "modified files" that turn_end then fed to the test runner
+        // and opened in an LSP client. Reject before the owner stamp below, so
+        // an out-of-project write cannot claim the worklist either.
+        //
+        // `projectRoot` defaults to `cwd` — true for every producer whose cwd
+        // IS the session root. A caller whose `cwd` is NARROWER than the
+        // project (an LSP call issued from a sub-package directory) passes the
+        // real root explicitly; `cwd` still selects which `turn-state.json`
+        // the entry lands in, exactly as before (#2504 review round 2, F1).
+        const containmentRoot = projectRoot ?? cwd;
+        if (!this.isTurnStatePathWithinRoot(filePath, containmentRoot)) {
+            this.log(`turn-state: rejected out-of-project path ${filePath} (project root ${containmentRoot})`);
+            return this.readTurnState(cwd);
+        }
         const state = this.readTurnState(cwd);
         if (sessionId) {
             const owner = {
@@ -293,10 +377,25 @@ export class CacheManager {
         const isCurrentOwner = this.getTurnStateAccess(cwd, owner) !== "foreign-live";
         if (!isCurrentOwner && process.pid !== currentState.owner?.pid)
             return false;
+        // #2504: stamp the CLEARING owner. Dropping `owner`/`sessionId` here made
+        // ownerless the resting shape of turn-state.json, which is what let the
+        // next session read a carried-over worklist as its own. A cleared state
+        // now says who cleared it and when, so `getTurnStateAccess` can judge it
+        // by liveness like any other owned state — and, since the worklist is
+        // empty, the stamp never latches another writer out (see the
+        // empty-worklist branch there).
         const state = {
             ...DEFAULT_TURN_STATE,
             files: {}, // fresh object — DEFAULT_TURN_STATE.files can be polluted by addModifiedRange
             lastUpdated: new Date().toISOString(),
+            sessionId: owner.id,
+            owner: {
+                kind: owner.kind,
+                id: owner.id,
+                pid: process.pid,
+                lastSeen: new Date().toISOString(),
+                sessionStartedAt: owner.sessionStartedAt,
+            },
         };
         this.writeTurnState(state, cwd);
         return true;