@timurproko/a1 0.2.6-dev.734 → 0.2.6

package/dist/foundation/lifecycle/session-repository-context.js

@@ -13,52 +13,60 @@ const MAX_WORKTREES = 256;
 const GIT_TIMEOUT_MS = 5_000;
 const LOCK_TIMEOUT_MS = 2_000;
 const LOCK_RETRY_MS = 20;
+/** Records without an agent id were written by a single-agent release and belong to its one agent. */
+export const PRIMARY_SESSION_AGENT_ID = "primary";
+const RECORD_FORMAT_VERSION = 2;
 /** Publish the exact live runtime that may acquire a delivery worktree. */
 export async function registerSessionRepositoryRuntime(identity, runtimeId, runtimeIdentity, options = {}) {
     const header = await readSessionHeader(identity);
     assertRuntimeId(runtimeId);
+    const agentId = requireAgentId(options);
     assertProcessIdentity(runtimeIdentity);
-    await withClaimLock(options, async () => {
-        await writeRuntimeRecord(header, runtimeId, runtimeIdentity, options);
+    await withClaimLock({ ...options, runtimeIdentity }, async () => {
+        await writeRuntimeRecord(header, runtimeId, agentId, runtimeIdentity, options);
     });
 }
-/** Revalidate a durable association and acquire its live claim for this runtime. */
+/** Revalidate a durable association and acquire its live claim for this runtime's agent; sibling agents' claims stay. */
 export async function activateSessionRepositoryContext(identity, runtimeId, runtimeIdentity, options = {}) {
     const header = await readSessionHeader(identity);
     assertRuntimeId(runtimeId);
+    const agentId = requireAgentId(options);
     assertProcessIdentity(runtimeIdentity);
-    return await withClaimLock(options, async () => {
-        await writeRuntimeRecord(header, runtimeId, runtimeIdentity, options);
+    const owner = { runtimeId, agentId };
+    return await withClaimLock({ ...options, runtimeIdentity }, async () => {
+        await writeRuntimeRecord(header, runtimeId, agentId, runtimeIdentity, options);
         const record = await readContextRecord(header, options);
         if (record === null) {
-            await releaseClaimsOwnedBy(runtimeId, null, options);
+            await releaseClaimsOwnedBy(owner, null, options);
             return null;
         }
         const selected = await validateContextRecord(header, record, options.signal).catch(() => null);
         if (selected === null) {
-            await releaseClaimsOwnedBy(runtimeId, null, options);
+            await releaseClaimsOwnedBy(owner, null, options);
             return null;
         }
-        const status = await claimAvailability(selected, runtimeId, options);
+        const status = await claimAvailability(selected, owner, options);
         if (status !== "available" && status !== "current") {
-            await releaseClaimsOwnedBy(runtimeId, null, options);
+            await releaseClaimsOwnedBy(owner, null, options);
             return null;
         }
-        await writeClaim(header, selected, runtimeId, runtimeIdentity, options);
-        await releaseClaimsOwnedBy(runtimeId, selected.gitDir, options);
+        await writeClaim(header, selected, owner, runtimeIdentity, options);
+        await releaseClaimsOwnedBy(owner, selected.gitDir, options);
         return { cwd: selected.root, branch: requireBranch(selected) };
     });
 }
-/** Release only this exact runtime generation's cooperative editing claims. */
+/** Release every agent's cooperative editing claims held by this exact runtime generation. */
 export async function releaseSessionRepositoryRuntime(runtimeId, runtimeIdentity, options = {}) {
     assertRuntimeId(runtimeId);
     assertProcessIdentity(runtimeIdentity);
-    await withClaimLock(options, async () => {
-        const runtime = await readRuntimeRecord(runtimeId, options);
-        if (runtime === null || runtime.pid !== runtimeIdentity.pid || runtime.startIdentity !== runtimeIdentity.startIdentity)
+    await withClaimLock({ ...options, runtimeIdentity }, async () => {
+        const runtimes = (await readRuntimeRecordsOf(runtimeId, options))
+            .filter(({ record }) => record.pid === runtimeIdentity.pid && record.startIdentity === runtimeIdentity.startIdentity);
+        if (runtimes.length === 0)
             return;
-        await releaseClaimsOwnedBy(runtimeId, null, options);
-        await rm(runtimeRecordPath(runtimeId, options), { force: true });
+        await releaseRuntimeClaims(runtimeId, options);
+        for (const { path } of runtimes)
+            await rm(path, { force: true });
     });
 }
 /** Persist one explicit same-repository worktree association after atomically claiming it. */
@@ -69,27 +77,27 @@ export async function setSessionRepositoryContext(identity, worktreePath, option
     if (!samePath(startup.commonDir, selected.commonDir)) {
         throw contextError("associated worktree belongs to a different Git repository", "worktree-foreign-repository");
     }
-    const runtimeId = requireRuntimeId(options);
+    const owner = { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) };
     return await withClaimLock(options, async () => {
-        const runtime = await requireLiveRuntime(header, runtimeId, options);
-        const status = await claimAvailability(selected, runtimeId, options);
+        const runtime = await requireLiveRuntime(header, owner, options);
+        const status = await claimAvailability(selected, owner, options);
         if (status === "busy")
             throw contextError("worktree is active in another session", "worktree-active-in-another-session");
         if (status === "unverifiable")
             throw contextError("worktree ownership cannot be verified", "worktree-owner-unverifiable");
         const prior = await readContextRecord(header, options);
-        await writeClaim(header, selected, runtimeId, processIdentityOf(runtime), options);
+        await writeClaim(header, selected, owner, processIdentityOf(runtime), options);
         try {
             await writeContextRecord(header, startup, selected, options);
         }
         catch (error) {
             if (status !== "current")
-                await removeMatchingClaim(selected, runtimeId, options);
+                await removeMatchingClaim(selected, owner, options);
             throw error;
         }
-        await releaseClaimsOwnedBy(runtimeId, selected.gitDir, options);
+        await releaseClaimsOwnedBy(owner, selected.gitDir, options);
         if (prior !== null && !samePath(prior.worktreeGitDir, selected.gitDir)) {
-            await removeClaimByGitDir(prior.worktreeCommonDir, prior.worktreeGitDir, runtimeId, options);
+            await removeClaimByGitDir(prior.worktreeCommonDir, prior.worktreeGitDir, owner, options);
         }
         return { cwd: selected.root, branch: requireBranch(selected) };
     });
@@ -101,11 +109,11 @@ export async function clearSessionRepositoryContext(identity, options = {}) {
         await rm(contextRecordPath(header, options), { force: true });
         return;
     }
-    const runtimeId = requireRuntimeId(options);
+    const owner = { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) };
     await withClaimLock(options, async () => {
-        await requireLiveRuntime(header, runtimeId, options);
+        await requireLiveRuntime(header, owner, options);
         await rm(contextRecordPath(header, options), { force: true });
-        await releaseClaimsOwnedBy(runtimeId, null, options);
+        await releaseClaimsOwnedBy(owner, null, options);
     });
 }
 /** Read and revalidate a persisted association; malformed or stale state fails closed to absence. */
@@ -126,8 +134,8 @@ export async function readSessionRepositoryContext(identity, options = {}) {
 /** List same-repository worktrees without acquiring, releasing, or repairing a claim. */
 export async function listSessionRepositoryWorktrees(identity, options = {}) {
     const header = await readSessionHeader(identity);
-    const runtimeId = requireRuntimeId(options);
-    await requireLiveRuntime(header, runtimeId, options);
+    const owner = { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) };
+    await requireLiveRuntime(header, owner, options);
     const startup = await readGitWorktreeIdentity(header.cwd, false, options.signal);
     const worktrees = await listGitWorktrees(startup.root, startup.commonDir, options.signal);
     if (worktrees.length > MAX_WORKTREES)
@@ -136,19 +144,17 @@ export async function listSessionRepositoryWorktrees(identity, options = {}) {
     const entries = [];
     for (const selected of worktrees) {
         if (selected.branch === null) {
-            entries.push({ cwd: selected.root, branch: "(detached)", status: "unverifiable" });
+            entries.push({ cwd: selected.root, branch: "(detached)", status: "unverifiable", agentId: null });
             continue;
         }
-        entries.push({
-            cwd: selected.root,
-            branch: selected.branch,
-            status: contended ? "unverifiable" : await claimAvailability(selected, runtimeId, options),
-        });
+        const status = contended ? "unverifiable" : await claimAvailability(selected, owner, options);
+        const claim = status === "current" || status === "busy" ? await readClaim(selected, options) : null;
+        entries.push({ cwd: selected.root, branch: selected.branch, status, agentId: claim?.agentId ?? null });
     }
     return entries.sort((left, right) => pathKey(left.cwd).localeCompare(pathKey(right.cwd)));
 }
-async function requireLiveRuntime(header, runtimeId, options) {
-    const runtime = await readRuntimeRecord(runtimeId, options);
+async function requireLiveRuntime(header, owner, options) {
+    const runtime = await readRuntimeRecord(owner, options);
     if (runtime === null || runtime.sessionId !== header.id || runtime.sessionFile !== header.file) {
         throw contextError("active session runtime is unavailable", "session-runtime-unavailable");
     }
@@ -165,14 +171,15 @@ async function requireLiveRuntime(header, runtimeId, options) {
     }
     return runtime;
 }
-async function claimAvailability(selected, runtimeId, options) {
+async function claimAvailability(selected, owner, options) {
     const claim = await readClaim(selected, options);
     if (claim === undefined)
         return "available";
     if (claim === null || !claimMatchesWorktree(claim, selected))
         return "unverifiable";
-    if (claim.runtimeId === runtimeId)
+    if (ownedBy(claim, owner))
         return "current";
+    // Invariant: a sibling agent of this runtime is live by construction, so its claim reads busy below.
     const inspection = requireInspector(options);
     let observed;
     try {
@@ -184,8 +191,8 @@ async function claimAvailability(selected, runtimeId, options) {
     const live = observed !== null && observed.pid === claim.pid && observed.startIdentity === claim.startIdentity;
     return live ? "busy" : "available";
 }
-async function writeRuntimeRecord(header, runtimeId, runtimeIdentity, options) {
-    const existing = await readRuntimeRecord(runtimeId, options);
+async function writeRuntimeRecord(header, runtimeId, agentId, runtimeIdentity, options) {
+    const existing = await readRuntimeRecord({ runtimeId, agentId }, options);
     if (existing !== null && (existing.pid !== runtimeIdentity.pid || existing.startIdentity !== runtimeIdentity.startIdentity)) {
         const inspection = requireInspector(options);
         let observed;
@@ -201,14 +208,16 @@ async function writeRuntimeRecord(header, runtimeId, runtimeIdentity, options) {
     }
     const record = {
         schema: RUNTIME_SCHEMA,
+        formatVersion: RECORD_FORMAT_VERSION,
         runtimeId,
+        agentId,
         sessionId: header.id,
         sessionFile: header.file,
         pid: runtimeIdentity.pid,
         startIdentity: runtimeIdentity.startIdentity,
         updatedAt: new Date().toISOString(),
     };
-    await atomicWrite(runtimeRecordPath(runtimeId, options), record);
+    await atomicWrite(runtimeRecordPath({ runtimeId, agentId }, options), record);
 }
 async function writeContextRecord(header, startup, selected, options) {
     const record = {
@@ -224,10 +233,12 @@ async function writeContextRecord(header, startup, selected, options) {
     };
     await atomicWrite(contextRecordPath(header, options), record);
 }
-async function writeClaim(header, selected, runtimeId, runtimeIdentity, options) {
+async function writeClaim(header, selected, owner, runtimeIdentity, options) {
     const claim = {
         schema: CLAIM_SCHEMA,
-        runtimeId,
+        formatVersion: RECORD_FORMAT_VERSION,
+        runtimeId: owner.runtimeId,
+        agentId: owner.agentId,
         sessionId: header.id,
         worktreeRoot: selected.root,
         worktreeCommonDir: selected.commonDir,
@@ -241,8 +252,34 @@ async function writeClaim(header, selected, runtimeId, runtimeIdentity, options)
 async function readContextRecord(header, options) {
     return await readJsonRecord(contextRecordPath(header, options), isContextRecord);
 }
-async function readRuntimeRecord(runtimeId, options) {
-    return await readJsonRecord(runtimeRecordPath(runtimeId, options), isRuntimeRecord);
+async function readRuntimeRecord(owner, options) {
+    const record = await readRuntimeRecordAt(runtimeRecordPath(owner, options));
+    return record !== null && ownedBy(record, owner) ? record : null;
+}
+async function readRuntimeRecordAt(path) {
+    const stored = await readJsonRecord(path, isStoredRuntimeRecord);
+    return stored === null ? null : { ...stored, formatVersion: RECORD_FORMAT_VERSION, agentId: stored.agentId ?? PRIMARY_SESSION_AGENT_ID };
+}
+/** Every agent's runtime record of one runtime, with the file that holds it. */
+async function readRuntimeRecordsOf(runtimeId, options) {
+    const directory = runtimesDirectory(options);
+    const names = await readdir(directory).catch(() => []);
+    if (names.length > MAX_WORKTREES * 4)
+        throw contextError("session runtime store exceeds its bounded limit", "session-runtime-limit");
+    const records = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const path = join(directory, name);
+        const record = await readRuntimeRecordAt(path);
+        if (record?.runtimeId === runtimeId)
+            records.push({ path, record });
+    }
+    return records;
+}
+async function readClaimRecordAt(path) {
+    const stored = await readJsonRecord(path, isStoredClaimRecord);
+    return stored === null ? null : normalizeClaim(stored);
 }
 /** Undefined means absent; null means present but invalid. */
 async function readClaim(selected, options) {
@@ -252,7 +289,7 @@ async function readClaim(selected, options) {
         if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
             return null;
         const value = JSON.parse((await readFile(path, { signal: options.signal })).toString("utf8"));
-        return isClaimRecord(value) ? value : null;
+        return isStoredClaimRecord(value) ? normalizeClaim(value) : null;
     }
     catch (error) {
         if (error instanceof Error && "code" in error && error.code === "ENOENT")
@@ -274,7 +311,15 @@ async function validateContextRecord(header, record, signal) {
         throw new Error("associated worktree identity changed");
     return selected;
 }
-async function releaseClaimsOwnedBy(runtimeId, keepGitDir, options) {
+/** Release one agent's claims except the one it keeps; sibling agents of the runtime are untouched. */
+async function releaseClaimsOwnedBy(owner, keepGitDir, options) {
+    await releaseClaimsWhere(claim => ownedBy(claim, owner) && (keepGitDir === null || !samePath(claim.worktreeGitDir, keepGitDir)), options);
+}
+/** Release every agent's claims of one runtime; only process exit does this. */
+async function releaseRuntimeClaims(runtimeId, options) {
+    await releaseClaimsWhere(claim => claim.runtimeId === runtimeId, options);
+}
+async function releaseClaimsWhere(release, options) {
     const directory = claimsDirectory(options);
     const names = await readdir(directory).catch(() => []);
     if (names.length > MAX_WORKTREES * 4)
@@ -283,19 +328,18 @@ async function releaseClaimsOwnedBy(runtimeId, keepGitDir, options) {
         if (!name.endsWith(".json"))
             continue;
         const path = join(directory, name);
-        const claim = await readJsonRecord(path, isClaimRecord);
-        if (claim?.runtimeId === runtimeId && (keepGitDir === null || !samePath(claim.worktreeGitDir, keepGitDir))) {
+        const claim = await readClaimRecordAt(path);
+        if (claim !== null && release(claim))
             await rm(path, { force: true });
-        }
     }
 }
-async function removeMatchingClaim(selected, runtimeId, options) {
-    await removeClaimByGitDir(selected.commonDir, selected.gitDir, runtimeId, options);
+async function removeMatchingClaim(selected, owner, options) {
+    await removeClaimByGitDir(selected.commonDir, selected.gitDir, owner, options);
 }
-async function removeClaimByGitDir(commonDir, gitDir, runtimeId, options) {
+async function removeClaimByGitDir(commonDir, gitDir, owner, options) {
     const path = claimRecordPath(commonDir, gitDir, options);
-    const claim = await readJsonRecord(path, isClaimRecord);
-    if (claim?.runtimeId === runtimeId)
+    const claim = await readClaimRecordAt(path);
+    if (claim !== null && ownedBy(claim, owner))
         await rm(path, { force: true });
 }
 async function readSessionHeader(identity) {
@@ -401,21 +445,30 @@ async function withClaimLock(options, operation) {
     await mkdir(directory, { recursive: true, mode: 0o700 });
     const path = join(directory, "mutation.lock");
     const deadline = Date.now() + (options.lockTimeoutMs ?? LOCK_TIMEOUT_MS);
+    const holder = await lockHolderIdentity(options);
     let handle;
-    while (handle === undefined) {
+    for (let attempt = 0; handle === undefined; attempt++) {
         try {
             handle = await open(path, "wx", 0o600);
         }
         catch (error) {
             if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
                 throw error;
+            if (attempt === 0 && await evictDeadLockHolder(path, options))
+                continue;
             if (Date.now() >= deadline)
                 throw contextError("worktree claim mutation is busy", "worktree-claim-busy");
             await new Promise(resolvePromise => setTimeout(resolvePromise, LOCK_RETRY_MS));
         }
     }
     try {
-        await handle.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`);
+        const record = {
+            pid: process.pid,
+            ...(holder === null ? {} : { startIdentity: holder.startIdentity }),
+            acquiredAt: new Date().toISOString(),
+            nonce: randomUUID(),
+        };
+        await handle.writeFile(`${JSON.stringify(record)}\n`);
         return await operation();
     }
     finally {
@@ -423,6 +476,59 @@ async function withClaimLock(options, operation) {
         await rm(path, { force: true }).catch(() => undefined);
     }
 }
+const lockHolderIdentities = new WeakMap();
+/** This process's identity as recorded in the lock; null leaves the lock unevictable, never wrongly evictable. */
+async function lockHolderIdentity(options) {
+    if (options.runtimeIdentity?.pid === process.pid)
+        return options.runtimeIdentity;
+    const inspection = options.inspectProcess;
+    if (inspection === undefined)
+        return null;
+    let identity = lockHolderIdentities.get(inspection);
+    if (identity === undefined) {
+        identity = inspection(process.pid)
+            .then(observed => observed !== null && observed.pid === process.pid ? observed : null)
+            .catch(() => null);
+        lockHolderIdentities.set(inspection, identity);
+    }
+    return await identity;
+}
+/**
+ * Evict the mutation lock only when its recorded holder is proven dead: the pid is gone or now names a process
+ * with another start identity. A lock without a holder identity, or a holder that cannot be inspected, is kept.
+ */
+async function evictDeadLockHolder(path, options) {
+    const inspection = options.inspectProcess;
+    if (inspection === undefined)
+        return false;
+    const holder = await readJsonRecord(path, isMutationLockRecord);
+    if (holder === null || holder.startIdentity === undefined || holder.pid === process.pid)
+        return false;
+    let observed;
+    try {
+        observed = await inspection(holder.pid);
+    }
+    catch {
+        return false;
+    }
+    if (observed !== null && observed.pid === holder.pid && observed.startIdentity === holder.startIdentity)
+        return false;
+    const evicted = `${path}.${randomUUID()}.evicted`;
+    try {
+        await rename(path, evicted);
+    }
+    catch {
+        return false;
+    }
+    const moved = await readJsonRecord(evicted, isMutationLockRecord);
+    if (moved?.nonce !== holder.nonce) {
+        // Concurrency: another waiter evicted first and a live holder took the lock since; hand it back untouched.
+        await rename(evicted, path).catch(() => undefined);
+        return false;
+    }
+    await rm(evicted, { force: true });
+    return true;
+}
 async function atomicWrite(path, value) {
     const directory = dirname(path);
     await mkdir(directory, { recursive: true, mode: 0o700 });
@@ -455,8 +561,13 @@ function contextRecordPath(header, options) {
 function claimStoreRoot(options) {
     return join(options.dataDir ?? resolveProductPaths().dataDir, PRODUCT_IDENTITY.state.sessionWorktreeClaimDirectory);
 }
-function runtimeRecordPath(runtimeId, options) {
-    return join(claimStoreRoot(options), "runtimes", `${digest(runtimeId)}.json`);
+function runtimesDirectory(options) {
+    return join(claimStoreRoot(options), "runtimes");
+}
+// Compatibility: the primary agent keeps the single-agent file name, so a version-1 runtime record is its record.
+function runtimeRecordPath(owner, options) {
+    const key = owner.agentId === PRIMARY_SESSION_AGENT_ID ? owner.runtimeId : `${owner.runtimeId}\0${owner.agentId}`;
+    return join(runtimesDirectory(options), `${digest(key)}.json`);
 }
 function claimsDirectory(options) {
     return join(claimStoreRoot(options), "worktrees");
@@ -472,6 +583,15 @@ function requireRuntimeId(options) {
     assertRuntimeId(runtimeId);
     return runtimeId;
 }
+function requireAgentId(options) {
+    const agentId = options.agentId ?? PRIMARY_SESSION_AGENT_ID;
+    if (!validSessionId(agentId))
+        throw contextError("session agent identity is invalid", "session-agent-invalid");
+    return agentId;
+}
+function ownedBy(record, owner) {
+    return record.runtimeId === owner.runtimeId && record.agentId === owner.agentId;
+}
 function requireInspector(options) {
     if (options.inspectProcess === undefined)
         throw contextError("native process identity inspection is unavailable", "process-inspection-unavailable");
@@ -520,19 +640,34 @@ function isContextRecord(value) {
         && validPath(value.worktreeRoot) && validPath(value.worktreeCommonDir) && validPath(value.worktreeGitDir)
         && typeof value.updatedAt === "string";
 }
-function isRuntimeRecord(value) {
-    return isRecord(value) && value.schema === RUNTIME_SCHEMA && validSessionId(value.runtimeId) && validSessionId(value.sessionId)
-        && validPath(value.sessionFile) && Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+function isStoredRuntimeRecord(value) {
+    return isRecord(value) && value.schema === RUNTIME_SCHEMA && validRecordVersion(value) && validSessionId(value.runtimeId)
+        && validSessionId(value.sessionId) && validPath(value.sessionFile) && Number.isSafeInteger(value.pid) && Number(value.pid) > 0
         && typeof value.startIdentity === "string" && value.startIdentity.length > 0 && value.startIdentity.length <= 512
         && !value.startIdentity.includes("\0") && typeof value.updatedAt === "string";
 }
-function isClaimRecord(value) {
-    return isRecord(value) && value.schema === CLAIM_SCHEMA && validSessionId(value.runtimeId) && validSessionId(value.sessionId)
+function isStoredClaimRecord(value) {
+    return isRecord(value) && value.schema === CLAIM_SCHEMA && validRecordVersion(value) && validSessionId(value.runtimeId)
+        && validSessionId(value.sessionId)
         && validPath(value.worktreeRoot) && validPath(value.worktreeCommonDir) && validPath(value.worktreeGitDir)
         && Number.isSafeInteger(value.pid) && Number(value.pid) > 0
         && typeof value.startIdentity === "string" && value.startIdentity.length > 0 && value.startIdentity.length <= 512
         && !value.startIdentity.includes("\0") && typeof value.updatedAt === "string";
 }
+function isMutationLockRecord(value) {
+    return isRecord(value) && Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+        && (value.startIdentity === undefined || (typeof value.startIdentity === "string" && value.startIdentity.length > 0
+            && value.startIdentity.length <= 512 && !value.startIdentity.includes("\0")))
+        && typeof value.acquiredAt === "string" && typeof value.nonce === "string" && value.nonce.length > 0;
+}
+function validRecordVersion(value) {
+    if (value.formatVersion === undefined)
+        return value.agentId === undefined;
+    return value.formatVersion === RECORD_FORMAT_VERSION && validSessionId(value.agentId);
+}
+function normalizeClaim(stored) {
+    return { ...stored, formatVersion: RECORD_FORMAT_VERSION, agentId: stored.agentId ?? PRIMARY_SESSION_AGENT_ID };
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/foundation/release/cohort-state.js

@@ -402,9 +402,12 @@ async function acquireLock(path) {
             return lock;
         }
         catch (error) {
-            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+            const code = error instanceof Error && "code" in error ? error.code : undefined;
+            // Platform: Windows reports a lock file another holder is still deleting as EPERM or EACCES.
+            const releasing = process.platform === "win32" && (code === "EPERM" || code === "EACCES");
+            if (code !== "EEXIST" && !releasing)
                 throw error;
-            if (await reclaimAbandonedLock(path))
+            if (code === "EEXIST" && await reclaimAbandonedLock(path))
                 continue;
             if (Date.now() >= deadline)
                 throw error;

package/dist/integrations/pi/tui-runtime/damage-aware-terminal.d.ts

@@ -1,6 +1,11 @@
 import type { PiTuiTerminalPort } from "./contracts.js";
 export declare const PINNED_PI_TUI_DAMAGE_GRAMMAR = "@earendil-works/pi-tui@1.1.0:tui-alt-screen-one-write-v1";
 export interface PiTuiDamageFrameDescriptor {
+    /**
+     * Frame ids are compared only within one presentation epoch; absent means the current epoch. A
+     * presenter switch starts a new epoch, because each presenter numbers its own frames.
+     */
+    readonly epoch?: number;
     readonly frameId: number;
     readonly width: number;
     readonly height: number;
@@ -64,6 +69,12 @@ export declare class DamageAwareTerminalAdapter implements PiTuiTerminalPort {
     get lastDecision(): PiTuiDamageDecision;
     get hyperlinkCleanupPending(): boolean;
     get canvasBackgroundAnsi(): string | null;
+    get presentationEpoch(): number;
+    /**
+     * Starts a new presentation epoch: the remembered cells and the armed frame are discarded and frame ids
+     * restart, so the next frame is painted in full rather than reconciled against another presenter's.
+     */
+    invalidatePresentation(): void;
     /** Invalidates remembered terminal cells before the shell forces one complete canvas repaint. */
     setCanvasBackground(ansi: string | null): boolean;
     /**

package/dist/integrations/pi/tui-runtime/damage-aware-terminal.js

@@ -23,6 +23,7 @@ export class DamageAwareTerminalAdapter {
     #cleanedRevision = 0;
     #recoveryRevision = 0;
     #epoch = 0;
+    #presentationEpoch = 0;
     #armed;
     #lastConsumedFrameId = 0;
     #cacheWidth = 0;
@@ -44,6 +45,17 @@ export class DamageAwareTerminalAdapter {
     get lastDecision() { return this.#decision; }
     get hyperlinkCleanupPending() { return this.#cleanupRevision > this.#cleanedRevision; }
     get canvasBackgroundAnsi() { return this.#canvasBackgroundAnsi; }
+    get presentationEpoch() { return this.#presentationEpoch; }
+    /**
+     * Starts a new presentation epoch: the remembered cells and the armed frame are discarded and frame ids
+     * restart, so the next frame is painted in full rather than reconciled against another presenter's.
+     */
+    invalidatePresentation() {
+        this.#presentationEpoch += 1;
+        this.#armed = undefined;
+        this.#lastConsumedFrameId = 0;
+        this.#invalidatePresentation();
+    }
     /** Invalidates remembered terminal cells before the shell forces one complete canvas repaint. */
     setCanvasBackground(ansi) {
         if (this.#canvasBackgroundAnsi === ansi)
@@ -108,7 +120,7 @@ export class DamageAwareTerminalAdapter {
         const armed = this.#armed;
         this.#armed = undefined;
         const parsed = parsePinnedFullscreenWrite(data);
-        if (armed !== undefined && armed.descriptor.frameId <= this.#lastConsumedFrameId) {
+        if (armed !== undefined && this.#isStale(armed.descriptor)) {
             // Concurrency: a recognized obsolete frame must never repaint newer cells,
             // acknowledge cleanup, or become the reference for a subsequent differential.
             this.#decision = this.#decide(armed, parsed);
@@ -189,7 +201,7 @@ export class DamageAwareTerminalAdapter {
             shiftRows: descriptor.verticalShiftRows,
             paintedRows: [],
         };
-        if (descriptor.frameId <= this.#lastConsumedFrameId)
+        if (this.#isStale(descriptor))
             return { ...base, reason: "stale-frame" };
         this.#lastConsumedFrameId = descriptor.frameId;
         if (this.hyperlinkCleanupPending)
@@ -265,6 +277,10 @@ export class DamageAwareTerminalAdapter {
             paintedRows: [...painted].sort((left, right) => left - right),
         };
     }
+    #isStale(descriptor) {
+        return (descriptor.epoch ?? this.#presentationEpoch) !== this.#presentationEpoch
+            || descriptor.frameId <= this.#lastConsumedFrameId;
+    }
     #rememberFrame(descriptor, parsed, raw) {
         if (raw.includes("\u001b[2J") || raw.includes("\u001b[?1049") || raw.includes("\u001b_G") || raw.includes("\u001bPq")) {
             this.#invalidateRows();

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-10-10T06:00:13.890Z",
+  "builtAt": "2026-10-10T17:42:20.005Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "51b0b2dc1c9ae577f2586c4217066929278726c2c15308d9144eb6f538e118ff",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-10T06:00:04.832Z",
+  "builtAt": "2026-10-10T17:42:10.255Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "ef62679e83bc1fad3d38f9f21675d9256f08d20e67fd4791571032115ca1b0e9",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-10T06:00:51.067Z",
+  "builtAt": "2026-10-10T17:42:54.136Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "e9c6d7e4596a7cd2634bb74b67925499fe6817cbfb667b574d27ff1b7cb33d93",
+    "sha256": "bdafa323144718cc73b6e5a970608fd58420ec343f6fa7fac76aeb216edae485",
     "size": 288256
   },
   "provenance": {

package/dist/ui/components/value-menu.d.ts

@@ -1,8 +1,8 @@
 import type { UiTheme } from "./theme.js";
 /**
  * The menu a value opens: anchored to the row it was opened from, marking what
- * is in effect, highlighting nothing until something is picked, and flipping
- * above its anchor only when it would otherwise run off the bottom.
+ * is in effect, highlighting nothing until something is picked, and laid over
+ * its anchor so the value in effect stays where it was read.
  */
 export interface ValueMenuState {
     /** Values offered, as they should read. */
@@ -37,7 +37,10 @@ export interface ValueMenuLayout {
     /** Columns reserved at the right edge, such as a scrollbar rail. */
     readonly reservedRight: number;
 }
-/** Where the menu is placed: below its anchor where there is room, else above. */
+/**
+ * Where the menu is placed: over its anchor, so the value in effect sits on the very
+ * row it was read from, shifted only as far as the body edges require.
+ */
 export declare function valueMenuFrame(state: ValueMenuState, anchor: ValueMenuAnchor, layout: ValueMenuLayout): ValueMenuFrame;
 /** Draws the menu over the rows behind it, leaving them otherwise untouched. */
 export declare function renderValueMenu(lines: readonly string[], state: ValueMenuState, frame: ValueMenuFrame, theme: UiTheme): readonly string[];