@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/dist/clients/bounded-pid-file-lock.js

@@ -0,0 +1,192 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+const waitArray = new Int32Array(new SharedArrayBuffer(4));
+function ownerPidIsLive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function quarantinePath(lockPath, token) {
+    return `${lockPath}.quarantine-${process.pid}-${token}`;
+}
+async function restoreQuarantinedLock(lockPath, quarantined) {
+    try {
+        await fsp.rename(quarantined, lockPath);
+    }
+    catch {
+        // A replacement owner may already hold the canonical name. Never overwrite it.
+    }
+}
+async function releaseQuarantineLock(lockPath, token) {
+    const quarantined = quarantinePath(lockPath, `release-${token}`);
+    let renamed = false;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            await fsp.rename(lockPath, quarantined);
+            renamed = true;
+            break;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" ||
+                attempt === 2)
+                return;
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+    }
+    if (!renamed)
+        return;
+    try {
+        const owner = JSON.parse(await fsp.readFile(path.join(quarantined, "owner.json"), "utf8"));
+        if (owner.token === token) {
+            await fsp.rm(quarantined, { recursive: true, force: true });
+        }
+        else {
+            await restoreQuarantinedLock(lockPath, quarantined);
+        }
+    }
+    catch {
+        await restoreQuarantinedLock(lockPath, quarantined);
+    }
+}
+function quarantineOwnerIsStale(owner, staleMs) {
+    return Number.isInteger(owner.pid) && owner.pid > 0 &&
+        Number.isFinite(owner.createdAt) &&
+        (!ownerPidIsLive(owner.pid) || Date.now() - owner.createdAt > staleMs);
+}
+async function reclaimQuarantineLock(lockPath, staleMs) {
+    const quarantined = quarantinePath(lockPath, `reclaim-${Date.now()}-${randomUUID()}`);
+    try {
+        await fsp.rename(lockPath, quarantined);
+    }
+    catch {
+        return false;
+    }
+    let stale = false;
+    try {
+        const owner = JSON.parse(await fsp.readFile(path.join(quarantined, "owner.json"), "utf8"));
+        stale = quarantineOwnerIsStale(owner, staleMs);
+    }
+    catch {
+        try {
+            stale = Date.now() - (await fsp.stat(quarantined)).mtimeMs > staleMs;
+        }
+        catch {
+            stale = false;
+        }
+    }
+    if (stale) {
+        await fsp.rm(quarantined, { recursive: true, force: true });
+        return true;
+    }
+    await restoreQuarantinedLock(lockPath, quarantined);
+    return false;
+}
+async function tryAcquireQuarantineLock(lockPath, staleMs) {
+    const owner = {
+        pid: process.pid,
+        createdAt: Date.now(),
+        token: `${process.pid}-${Date.now()}-${randomUUID()}`,
+    };
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            await fsp.mkdir(lockPath);
+            try {
+                await fsp.writeFile(path.join(lockPath, "owner.json"), JSON.stringify(owner), "utf8");
+            }
+            catch (error) {
+                await fsp.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                throw error;
+            }
+            return () => releaseQuarantineLock(lockPath, owner.token);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        let stale;
+        try {
+            const existing = JSON.parse(await fsp.readFile(path.join(lockPath, "owner.json"), "utf8"));
+            stale = quarantineOwnerIsStale(existing, staleMs);
+        }
+        catch {
+            try {
+                stale = Date.now() - (await fsp.stat(lockPath)).mtimeMs > staleMs;
+            }
+            catch {
+                stale = true;
+            }
+        }
+        if (!stale || !(await reclaimQuarantineLock(lockPath, staleMs)))
+            return null;
+    }
+    return null;
+}
+export async function acquireQuarantinePidFileLock(lockPath, options) {
+    const deadline = Date.now() + options.waitMs;
+    for (;;) {
+        const release = await tryAcquireQuarantineLock(lockPath, options.staleMs);
+        if (release)
+            return release;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            if (options.onContention === "skip-log") {
+                options.logContention();
+                return null;
+            }
+            throw new Error(options.timeoutMessage);
+        }
+        await new Promise((resolve) => setTimeout(resolve, Math.min(options.retryMs, remaining)));
+    }
+}
+export function acquireBoundedPidFileLock(lockPath, options) {
+    const token = `${process.pid}:${Date.now()}:${randomUUID()}`;
+    const deadline = Date.now() + options.waitMs;
+    for (;;) {
+        try {
+            const fd = fs.openSync(lockPath, "wx");
+            fs.writeFileSync(fd, token, "utf8");
+            fs.closeSync(fd);
+            return () => {
+                try {
+                    if (fs.readFileSync(lockPath, "utf8") === token) {
+                        fs.unlinkSync(lockPath);
+                    }
+                }
+                catch {
+                    // Protected write completed; cleanup is best-effort.
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                const [pidText] = fs.readFileSync(lockPath, "utf8").split(":", 1);
+                if (!ownerPidIsLive(Number.parseInt(pidText ?? "", 10))) {
+                    fs.unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch (lockError) {
+                if (lockError.code === "ENOENT")
+                    continue;
+            }
+            if (Date.now() >= deadline) {
+                if (options.onContention === "skip-log") {
+                    options.logContention();
+                    return null;
+                }
+                throw new Error(options.timeoutMessage);
+            }
+            Atomics.wait(waitArray, 0, 0, options.retryMs);
+        }
+    }
+}

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

@@ -1,13 +1,20 @@
 /**
  * Persistent NDJSON trace of `pi.events` bus publish attempts
  * (`pilens:files:touched` #482 / `pilens:diagnostics` #502 /
- * `pilens:format:queued` + `pilens:format:start` #673).
+ * `pilens:diagnostic:disposition` / `pilens:format:queued` +
+ * `pilens:format:start` + `pilens:autofix:start` #673/#684 /
+ * `pi-lens/analysis-complete` + `pi-lens/findings` + `pi-lens/turn-findings`
+ * #1415) — nine event names across five producers.
  *
- * All four producers (clients/bus-publish.ts, clients/diagnostics-publish.ts,
- * clients/format-events-publish.ts) are fire-and-forget: on failure or on a
- * structural no-op (never wired, kill switch off) they only invoke an
- * optional `dbg` callback, which varies by host and is a documented no-op in
- * the MCP host (clients/mcp/session.ts's `dbg: noop`). That leaves
+ * All five producers (clients/bus-publish.ts, clients/diagnostics-publish.ts,
+ * clients/disposition-publish.ts, clients/format-events-publish.ts,
+ * clients/lens-events.ts) are fire-and-forget: on failure or on a structural
+ * no-op (never wired, kill switch off) the four #482/#502/#673/#684
+ * producers only invoke an optional `dbg` callback, which varies by host and
+ * is a documented no-op in the MCP host (clients/mcp/session.ts's
+ * `dbg: noop`); `lens-events.ts` (#1415) has no `dbg` param at all — its
+ * events are purely observational inter-extension telemetry, so this NDJSON
+ * trace is its ONLY failure-visible surface. Either way, that leaves
  * bus-publish outcomes invisible in exactly the context where they matter
  * most — same failure shape as the #544 MCP session_start incident this repo
  * already fixed once.
@@ -26,6 +33,9 @@
  * spam one identical line per write batch for an entire session with zero
  * new information after the first. Both are gated log-once-per-process, the
  * same `hasLoggedFailure` shape the producers already use for emit_failed.
+ * `skipped_stale_session` is an info-level per-occurrence outcome: the emit
+ * seam intentionally declined a target whose associated ctx was confirmed
+ * stale, so it is neither a bus failure nor input for the smells rollup.
  * The empty-batch branch (`paths.length === 0` / `files.length === 0`) is
  * NOT logged at all: every call site already guards against invoking these
  * functions with nothing to report (see clients/pipeline.ts,
@@ -37,17 +47,63 @@ import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.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 writer = createNdjsonLogger({
     filePath: BUS_EVENTS_LOG_FILE,
     maxBytes: getMaxLogSizeMB() * 1024 * 1024,
 });
+const eventRollupCounts = new Map();
+function bumpRollupCount(event, outcome) {
+    const existing = eventRollupCounts.get(event) ?? {
+        emitted: 0,
+        skipped_stale_session: 0,
+        emit_failed: 0,
+    };
+    existing[outcome] += 1;
+    eventRollupCounts.set(event, existing);
+}
 export function logBusEvent(entry) {
+    if (entry.outcome === "emitted" ||
+        entry.outcome === "skipped_stale_session" ||
+        entry.outcome === "emit_failed") {
+        bumpRollupCount(entry.event, entry.outcome);
+    }
     if (isTestMode()) {
         return;
     }
     writer.log({ ts: new Date().toISOString(), ...entry });
 }
+/** Snapshot the current session's rollup, keyed by event name. Non-mutating —
+ *  pair with {@link resetBusEventRollupCounts} at session end. */
+export function getBusEventRollupCounts() {
+    return Object.fromEntries(eventRollupCounts);
+}
+/** Clear the rollup — call once the session-end snapshot has been logged
+ *  (or from tests) so a new session starts from zero. */
+export function resetBusEventRollupCounts() {
+    eventRollupCounts.clear();
+}
+/**
+ * Log one `session_end_bus_rollup` latency row per event NAME that had any
+ * activity this session, then clear the rollup. Called from index.ts's
+ * `session_shutdown` handler (the session-end hook this repo's other
+ * teardown work — LSP fleet shutdown, cache-prefix eviction — already runs
+ * from). A no-op (logs nothing) when nothing was ever published, matching
+ * `formatSmellsSessionStartLine`'s "no noise on an ordinary session" shape.
+ */
+export function emitBusEventRollupAtSessionEnd(cwd) {
+    for (const [event, counts] of eventRollupCounts) {
+        logLatency({
+            type: "phase",
+            phase: "session_end_bus_rollup",
+            filePath: cwd,
+            durationMs: 0,
+            metadata: { event, ...counts },
+        });
+    }
+    resetBusEventRollupCounts();
+}
 export function getBusEventsLogPath() {
     return BUS_EVENTS_LOG_FILE;
 }

package/node_modules/pi-lens/dist/clients/bus-publish.js

@@ -20,9 +20,10 @@
 import { logBusEvent } from "./bus-events-logger.js";
 import { normalizeFilePath } from "./path-utils.js";
 import { appendRecentTouches } from "./recent-touches.js";
+import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
 export const BUS_FILES_TOUCHED_EVENT = "pilens:files:touched";
 export const BUS_FILES_TOUCHED_VERSION = 1;
-let busEmit;
+const liveEmitter = createLiveBusEmitter();
 let hasLoggedFailure = false;
 // Log-once-per-process guards for the two structural-no-op outcomes below
 // (see bus-events-logger.ts's module doc for why these aren't logged on
@@ -38,11 +39,14 @@ let hasLoggedDisabled = false;
  * no `pi.events`).
  */
 export function wireBusEmitter(emitFn) {
-    busEmit = emitFn;
+    liveEmitter.wire(emitFn);
+}
+export function wireBusEmitterGetter(getter) {
+    liveEmitter.wireGetter(getter);
 }
 /** Test-only: reset module state between test files. */
 export function _resetForTests() {
-    busEmit = undefined;
+    liveEmitter.reset();
     hasLoggedFailure = false;
     hasLoggedUnwired = false;
     hasLoggedDisabled = false;
@@ -102,7 +106,14 @@ export function publishFilesTouched(args) {
     }).catch((err) => {
         args.dbg?.(`bus-publish: recent-touches append failed: ${err}`);
     });
-    if (!busEmit) {
+    const resolution = resolveLiveBusEmitter(liveEmitter, () => ({
+        event: BUS_FILES_TOUCHED_EVENT,
+        cwd: normalizeFilePath(args.cwd),
+        reason: args.reason,
+    }));
+    if (resolution.outcome === "stale-session")
+        return;
+    if (resolution.outcome === "unwired") {
         if (!hasLoggedUnwired) {
             hasLoggedUnwired = true;
             logBusEvent({
@@ -114,6 +125,7 @@ export function publishFilesTouched(args) {
         }
         return;
     }
+    const busEmit = resolution.emit;
     try {
         const payload = {
             v: BUS_FILES_TOUCHED_VERSION,
@@ -129,6 +141,7 @@ export function publishFilesTouched(args) {
             }));
         }
         busEmit(BUS_FILES_TOUCHED_EVENT, payload);
+        hasLoggedFailure = false;
         logBusEvent({
             event: BUS_FILES_TOUCHED_EVENT,
             outcome: "emitted",
@@ -144,9 +157,11 @@ export function publishFilesTouched(args) {
             cwd: normalizeFilePath(args.cwd),
             reason: args.reason,
             error: String(err),
+            ctxSource: resolution.ctxSource,
         });
         if (!hasLoggedFailure) {
             hasLoggedFailure = true;
+            recordStaleBusFailure(BUS_FILES_TOUCHED_EVENT, err);
             args.dbg?.(`bus-publish: pilens:files:touched emit failed (further failures suppressed): ${err}`);
         }
     }

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

@@ -9,6 +9,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "../file-utils.js";
 import { readJsonCache } from "../json-cache-read.js";
+import { resolvePackagePath } from "../package-root.js";
+import { writeFileAtomic } from "../atomic-write.js";
 // v4: cache skip_test_files + fix_action — v3 entries silently dropped them,
 // and ruleHash (rule-file mtimes) never invalidates on a code-only fix.
 // v5 (#675): rule SELECTION changed in code — javascript no longer inherits the
@@ -20,7 +22,37 @@ import { readJsonCache } from "../json-cache-read.js";
 // the language's own. A v5 tsx entry was hashed over tsx files only, so a
 // typescript-rule edit never invalidated it; v5 entries self-miss anyway (the
 // hash input set changed), the bump just makes the semantics break explicit.
-export const CACHE_VERSION = "v6";
+// v7 (#1118): computeRuleHash now CONTENT-hashes project-local rule files
+// instead of trusting mtime+size alone. mtime+size is the review-graph
+// first-filter, not the full gold standard (size:mtimeMs + confirmContentChanged)
+// — a rule-file edit that preserves both (git checkout timestamp restoration, a
+// same-length tweak, a formatter that preserves mtime) replayed a stale
+// compiled set from disk and re-persisted it under the still-matching
+// fingerprint, poisoning every future process. The bump forces every v6 entry
+// (hashed under the old metadata-only formula) to miss once on upgrade, so a
+// silently-poisoned v6 entry can't be trusted by the new code.
+export const CACHE_VERSION = "v7";
+/**
+ * Bundled rule files ship with the extension and are immutable within a
+ * process — they can't change mid-session, so the cheap mtime+size
+ * fingerprint (v6's whole-set formula) is sufficient for them, and there are
+ * ~705 of them across all languages, so unconditionally reading+hashing their
+ * bytes on every edit would be the unconditional hot-path hashing the
+ * event-loop discipline forbids (RuleCache.get runs on the per-edit
+ * tree-sitter runner hot path).
+ *
+ * Project-local rule files (under `<project>/rules/tree-sitter-queries/`,
+ * see `ruleFilesForLanguage`) are the opposite: mutable, and a SMALL set (the
+ * handful a developer actually maintains) — cheap to content-hash. Splitting
+ * 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.
+ */
+const BUNDLED_RULES_ROOT = resolvePackagePath(import.meta.url, "rules", "tree-sitter-queries");
+function isBundledRuleFile(resolvedFile) {
+    return (resolvedFile === BUNDLED_RULES_ROOT ||
+        resolvedFile.startsWith(BUNDLED_RULES_ROOT + path.sep));
+}
 export class RuleCache {
     cacheFile;
     cacheDir;
@@ -38,9 +70,19 @@ export class RuleCache {
     computeRuleHash(ruleFiles) {
         const hash = crypto.createHash("sha256");
         for (const file of ruleFiles.sort((a, b) => a.localeCompare(b))) {
-            if (fs.existsSync(file)) {
-                const stat = fs.statSync(file);
-                hash.update(`${file}:${stat.mtimeMs}:${stat.size}`);
+            const resolved = path.resolve(file);
+            if (!fs.existsSync(resolved))
+                continue;
+            const stat = fs.statSync(resolved);
+            hash.update(`${file}:${stat.mtimeMs}:${stat.size}`);
+            // Content-CONFIRM only the project-local, mutable subset (a handful of
+            // files) — mtime+size alone is a first filter, not proof of freshness,
+            // and a preserved-mtime+size edit here would otherwise replay (and
+            // re-persist) a stale compiled set. Bundled files (~705, immutable
+            // within a process) skip this: the metadata fingerprint stays their
+            // whole story, keeping the common no-project-rules case as cheap as v6.
+            if (!isBundledRuleFile(resolved)) {
+                hash.update(fs.readFileSync(resolved));
             }
         }
         return hash.digest("hex").slice(0, 16);
@@ -74,7 +116,7 @@ export class RuleCache {
                 ruleHash: this.computeRuleHash(ruleFiles),
                 queries,
             };
-            fs.writeFileSync(this.cacheFile, JSON.stringify(entry, null, 2));
+            writeFileAtomic(this.cacheFile, JSON.stringify(entry, null, 2));
             this.pruneStaleVersions();
         }
         catch {

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

@@ -8,9 +8,11 @@
  *
  * All paths are relative to project root (process.cwd()).
  */
+import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 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";
 // --- Defaults ---
@@ -21,6 +23,8 @@ const DEFAULT_TURN_STATE = {
     maxCycles: 3,
     lastUpdated: "",
 };
+export const MCP_TURN_STATE_OWNER_ID = `mcp-${process.pid}`;
+const TURN_OWNER_STALE_MS = 30 * 60 * 1000;
 // --- Helpers ---
 function getLensDir(cwd) {
     return getProjectDataDir(cwd);
@@ -36,7 +40,7 @@ export class CacheManager {
     log;
     constructor(verbose = false) {
         this.log = verbose
-            ? (msg) => console.error(`[cache] ${msg}`)
+            ? createSubsystemLogger("cache")
             : () => { };
     }
     /**
@@ -107,10 +111,45 @@ export class CacheManager {
             timestamp: new Date().toISOString(),
             ...extraMeta,
         };
-        fs.writeFileSync(cachePath, JSON.stringify(data, null, 2));
-        fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+        writeFileAtomic(cachePath, JSON.stringify(data, null, 2), {
+            bestEffort: false,
+        });
+        writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), {
+            bestEffort: false,
+        });
         this.log(`Cache written: ${scanner}`);
     }
+    /** Inspect a cache without changing the behavior of readCache consumers. */
+    inspectCache(scanner, cwd, maxAgeMs = DEFAULT_MAX_AGE_MS) {
+        const cachePath = path.join(getCacheDir(cwd), `${scanner}.json`);
+        const metaPath = path.join(getCacheDir(cwd), `${scanner}.meta.json`);
+        for (const cachePathname of [cachePath, metaPath]) {
+            try {
+                fs.statSync(cachePathname);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return "missing";
+                return "unreadable";
+            }
+        }
+        try {
+            const meta = readJsonCache(metaPath, (parsed) => parsed);
+            if (!meta || typeof meta.timestamp !== "string")
+                return "malformed";
+            const timestamp = new Date(meta.timestamp).getTime();
+            if (!Number.isFinite(timestamp))
+                return "malformed";
+            const age = Date.now() - timestamp;
+            if (age < 0 || age > maxAgeMs)
+                return age < 0 ? "malformed" : "stale";
+            const data = readJsonCache(cachePath, (parsed) => parsed);
+            return data === undefined ? "malformed" : "fresh";
+        }
+        catch {
+            return "unreadable";
+        }
+    }
     /**
      * Check if a cache entry is fresh (exists and not expired).
      */
@@ -175,16 +214,57 @@ export class CacheManager {
         fs.mkdirSync(lensDir, { recursive: true });
         const statePath = getTurnStatePath(cwd);
         state.lastUpdated = new Date().toISOString();
-        fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+        writeFileAtomic(statePath, JSON.stringify(state, null, 2));
+    }
+    /** Return whether a writer may read/write this workspace worklist. */
+    getTurnStateAccess(cwd, owner) {
+        const state = this.readTurnState(cwd);
+        if (!state.owner) {
+            if (!state.sessionId || state.sessionId === owner.id)
+                return "owned";
+            // Pre-owner files have no liveness information. Preserve the existing
+            // stale-session eviction behavior for this legacy shape.
+            return "available";
+        }
+        if (state.owner.kind === owner.kind &&
+            state.owner.id === owner.id) {
+            return "owned";
+        }
+        return this.isTurnStateOwnerStale(state.owner) ? "available" : "foreign-live";
+    }
+    isTurnStateOwnerStale(owner) {
+        if (owner.pid > 0 && owner.pid !== process.pid) {
+            try {
+                process.kill(owner.pid, 0);
+                return false;
+            }
+            catch {
+                return true;
+            }
+        }
+        const lastSeen = Date.parse(owner.lastSeen);
+        return !Number.isFinite(lastSeen) || Date.now() - lastSeen > TURN_OWNER_STALE_MS;
     }
     /**
      * Add or update a file's modified ranges in turn state.
-     * Merges overlapping ranges.
+     * Merges overlapping ranges. `sessionId:null` deliberately preserves the
+     * current owner; callers must provide an explicit owner id to claim a stale
+     * worklist.
      */
-    addModifiedRange(filePath, range, importsChanged, cwd, sessionId) {
+    addModifiedRange(filePath, range, importsChanged, cwd, sessionId, ownerKind = "pi") {
         const state = this.readTurnState(cwd);
-        if (sessionId)
+        if (sessionId) {
+            const owner = {
+                kind: ownerKind,
+                id: sessionId,
+                pid: process.pid,
+                lastSeen: new Date().toISOString(),
+            };
+            if (this.getTurnStateAccess(cwd, owner) === "foreign-live")
+                return state;
             state.sessionId = sessionId;
+            state.owner = owner;
+        }
         const normalizedPath = this.toTurnStateKey(filePath, cwd);
         const existing = state.files[normalizedPath];
         if (existing) {
@@ -209,19 +289,27 @@ export class CacheManager {
     /**
      * Clear turn state (after turn_end processes it).
      */
-    clearTurnState(cwd) {
+    clearTurnState(cwd, owner) {
+        const currentState = this.readTurnState(cwd);
+        const isCurrentOwner = this.getTurnStateAccess(cwd, owner) !== "foreign-live";
+        if (!isCurrentOwner && process.pid !== currentState.owner?.pid)
+            return false;
         const state = {
             ...DEFAULT_TURN_STATE,
             files: {}, // fresh object — DEFAULT_TURN_STATE.files can be polluted by addModifiedRange
             lastUpdated: new Date().toISOString(),
         };
         this.writeTurnState(state, cwd);
+        return true;
     }
     /**
      * Increment turn cycle counter.
      */
-    incrementTurnCycle(cwd) {
+    incrementTurnCycle(cwd, owner) {
         const state = this.readTurnState(cwd);
+        const isCurrentOwner = this.getTurnStateAccess(cwd, owner) !== "foreign-live";
+        if (!isCurrentOwner && process.pid !== state.owner?.pid)
+            return state;
         state.turnCycles++;
         this.writeTurnState(state, cwd);
         return state;