@timurproko/a1 0.2.6-dev.717 → 0.2.6-dev.734

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

@@ -1,49 +1,112 @@
 import { createHash, randomUUID } from "node:crypto";
-import { open, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { open, lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { resolveProductPaths } from "./paths.js";
-const SCHEMA = "a1-session-repository-context-v1";
+const CONTEXT_SCHEMA = "a1-session-repository-context-v1";
+const RUNTIME_SCHEMA = "a1-session-runtime-v1";
+const CLAIM_SCHEMA = "a1-session-worktree-claim-v1";
 const MAX_RECORD_BYTES = 16 * 1024;
 const MAX_HEADER_BYTES = 64 * 1024;
+const MAX_WORKTREES = 256;
 const GIT_TIMEOUT_MS = 5_000;
-/** Persist one explicit same-repository worktree association for a stable Pi session. */
+const LOCK_TIMEOUT_MS = 2_000;
+const LOCK_RETRY_MS = 20;
+/** 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);
+    assertProcessIdentity(runtimeIdentity);
+    await withClaimLock(options, async () => {
+        await writeRuntimeRecord(header, runtimeId, runtimeIdentity, options);
+    });
+}
+/** Revalidate a durable association and acquire its live claim for this runtime. */
+export async function activateSessionRepositoryContext(identity, runtimeId, runtimeIdentity, options = {}) {
+    const header = await readSessionHeader(identity);
+    assertRuntimeId(runtimeId);
+    assertProcessIdentity(runtimeIdentity);
+    return await withClaimLock(options, async () => {
+        await writeRuntimeRecord(header, runtimeId, runtimeIdentity, options);
+        const record = await readContextRecord(header, options);
+        if (record === null) {
+            await releaseClaimsOwnedBy(runtimeId, null, options);
+            return null;
+        }
+        const selected = await validateContextRecord(header, record, options.signal).catch(() => null);
+        if (selected === null) {
+            await releaseClaimsOwnedBy(runtimeId, null, options);
+            return null;
+        }
+        const status = await claimAvailability(selected, runtimeId, options);
+        if (status !== "available" && status !== "current") {
+            await releaseClaimsOwnedBy(runtimeId, null, options);
+            return null;
+        }
+        await writeClaim(header, selected, runtimeId, runtimeIdentity, options);
+        await releaseClaimsOwnedBy(runtimeId, selected.gitDir, options);
+        return { cwd: selected.root, branch: requireBranch(selected) };
+    });
+}
+/** Release only this exact runtime generation's cooperative editing claims. */
+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)
+            return;
+        await releaseClaimsOwnedBy(runtimeId, null, options);
+        await rm(runtimeRecordPath(runtimeId, options), { force: true });
+    });
+}
+/** Persist one explicit same-repository worktree association after atomically claiming it. */
 export async function setSessionRepositoryContext(identity, worktreePath, options = {}) {
     const header = await readSessionHeader(identity);
     const startup = await readGitWorktreeIdentity(header.cwd, false, options.signal);
     const selected = await readGitWorktreeIdentity(worktreePath, true, options.signal);
     if (!samePath(startup.commonDir, selected.commonDir)) {
-        throw new Error("associated worktree belongs to a different Git repository");
+        throw contextError("associated worktree belongs to a different Git repository", "worktree-foreign-repository");
     }
-    const record = {
-        schema: SCHEMA,
-        sessionId: header.id,
-        sessionFile: header.file,
-        startupRoot: startup.root,
-        startupCommonDir: startup.commonDir,
-        worktreeRoot: selected.root,
-        worktreeCommonDir: selected.commonDir,
-        worktreeGitDir: selected.gitDir,
-        updatedAt: new Date().toISOString(),
-    };
-    const destination = recordPath(header, options);
-    const directory = dirname(destination);
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
-    try {
-        await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
-        await rename(temporary, destination);
-    }
-    finally {
-        await rm(temporary, { force: true }).catch(() => undefined);
-    }
-    return { cwd: selected.root, branch: requireBranch(selected) };
+    const runtimeId = requireRuntimeId(options);
+    return await withClaimLock(options, async () => {
+        const runtime = await requireLiveRuntime(header, runtimeId, options);
+        const status = await claimAvailability(selected, runtimeId, 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);
+        try {
+            await writeContextRecord(header, startup, selected, options);
+        }
+        catch (error) {
+            if (status !== "current")
+                await removeMatchingClaim(selected, runtimeId, options);
+            throw error;
+        }
+        await releaseClaimsOwnedBy(runtimeId, selected.gitDir, options);
+        if (prior !== null && !samePath(prior.worktreeGitDir, selected.gitDir)) {
+            await removeClaimByGitDir(prior.worktreeCommonDir, prior.worktreeGitDir, runtimeId, options);
+        }
+        return { cwd: selected.root, branch: requireBranch(selected) };
+    });
 }
-/** Remove only the association belonging to the supplied stable session. */
+/** Remove only the association and live claim belonging to the supplied stable session/runtime. */
 export async function clearSessionRepositoryContext(identity, options = {}) {
     const header = await readSessionHeader(identity);
-    await rm(recordPath(header, options), { force: true });
+    if (options.runtimeId === undefined) {
+        await rm(contextRecordPath(header, options), { force: true });
+        return;
+    }
+    const runtimeId = requireRuntimeId(options);
+    await withClaimLock(options, async () => {
+        await requireLiveRuntime(header, runtimeId, options);
+        await rm(contextRecordPath(header, options), { force: true });
+        await releaseClaimsOwnedBy(runtimeId, null, options);
+    });
 }
 /** Read and revalidate a persisted association; malformed or stale state fails closed to absence. */
 export async function readSessionRepositoryContext(identity, options = {}) {
@@ -54,39 +117,187 @@ export async function readSessionRepositoryContext(identity, options = {}) {
     catch {
         return null;
     }
+    const record = await readContextRecord(header, options);
+    if (record === null)
+        return null;
+    const selected = await validateContextRecord(header, record, options.signal).catch(() => null);
+    return selected === null ? null : { cwd: selected.root, branch: requireBranch(selected) };
+}
+/** 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 startup = await readGitWorktreeIdentity(header.cwd, false, options.signal);
+    const worktrees = await listGitWorktrees(startup.root, startup.commonDir, options.signal);
+    if (worktrees.length > MAX_WORKTREES)
+        throw contextError("worktree inventory exceeds its bounded limit", "worktree-inventory-limit");
+    const contended = await mutationLockExists(options);
+    const entries = [];
+    for (const selected of worktrees) {
+        if (selected.branch === null) {
+            entries.push({ cwd: selected.root, branch: "(detached)", status: "unverifiable" });
+            continue;
+        }
+        entries.push({
+            cwd: selected.root,
+            branch: selected.branch,
+            status: contended ? "unverifiable" : await claimAvailability(selected, runtimeId, options),
+        });
+    }
+    return entries.sort((left, right) => pathKey(left.cwd).localeCompare(pathKey(right.cwd)));
+}
+async function requireLiveRuntime(header, runtimeId, options) {
+    const runtime = await readRuntimeRecord(runtimeId, options);
+    if (runtime === null || runtime.sessionId !== header.id || runtime.sessionFile !== header.file) {
+        throw contextError("active session runtime is unavailable", "session-runtime-unavailable");
+    }
+    const inspection = requireInspector(options);
+    let observed;
+    try {
+        observed = await inspection(runtime.pid);
+    }
+    catch {
+        throw contextError("active session runtime cannot be verified", "session-runtime-unverifiable");
+    }
+    if (observed === null || observed.pid !== runtime.pid || observed.startIdentity !== runtime.startIdentity) {
+        throw contextError("active session runtime is no longer running", "session-runtime-stopped");
+    }
+    return runtime;
+}
+async function claimAvailability(selected, runtimeId, options) {
+    const claim = await readClaim(selected, options);
+    if (claim === undefined)
+        return "available";
+    if (claim === null || !claimMatchesWorktree(claim, selected))
+        return "unverifiable";
+    if (claim.runtimeId === runtimeId)
+        return "current";
+    const inspection = requireInspector(options);
+    let observed;
+    try {
+        observed = await inspection(claim.pid);
+    }
+    catch {
+        return "unverifiable";
+    }
+    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);
+    if (existing !== null && (existing.pid !== runtimeIdentity.pid || existing.startIdentity !== runtimeIdentity.startIdentity)) {
+        const inspection = requireInspector(options);
+        let observed;
+        try {
+            observed = await inspection(existing.pid);
+        }
+        catch {
+            throw contextError("session runtime ownership cannot be verified", "session-runtime-unverifiable");
+        }
+        if (observed !== null && observed.pid === existing.pid && observed.startIdentity === existing.startIdentity) {
+            throw contextError("session runtime identity is active in another process", "session-runtime-conflict");
+        }
+    }
+    const record = {
+        schema: RUNTIME_SCHEMA,
+        runtimeId,
+        sessionId: header.id,
+        sessionFile: header.file,
+        pid: runtimeIdentity.pid,
+        startIdentity: runtimeIdentity.startIdentity,
+        updatedAt: new Date().toISOString(),
+    };
+    await atomicWrite(runtimeRecordPath(runtimeId, options), record);
+}
+async function writeContextRecord(header, startup, selected, options) {
+    const record = {
+        schema: CONTEXT_SCHEMA,
+        sessionId: header.id,
+        sessionFile: header.file,
+        startupRoot: startup.root,
+        startupCommonDir: startup.commonDir,
+        worktreeRoot: selected.root,
+        worktreeCommonDir: selected.commonDir,
+        worktreeGitDir: selected.gitDir,
+        updatedAt: new Date().toISOString(),
+    };
+    await atomicWrite(contextRecordPath(header, options), record);
+}
+async function writeClaim(header, selected, runtimeId, runtimeIdentity, options) {
+    const claim = {
+        schema: CLAIM_SCHEMA,
+        runtimeId,
+        sessionId: header.id,
+        worktreeRoot: selected.root,
+        worktreeCommonDir: selected.commonDir,
+        worktreeGitDir: selected.gitDir,
+        pid: runtimeIdentity.pid,
+        startIdentity: runtimeIdentity.startIdentity,
+        updatedAt: new Date().toISOString(),
+    };
+    await atomicWrite(claimRecordPath(selected.commonDir, selected.gitDir, options), claim);
+}
+async function readContextRecord(header, options) {
+    return await readJsonRecord(contextRecordPath(header, options), isContextRecord);
+}
+async function readRuntimeRecord(runtimeId, options) {
+    return await readJsonRecord(runtimeRecordPath(runtimeId, options), isRuntimeRecord);
+}
+/** Undefined means absent; null means present but invalid. */
+async function readClaim(selected, options) {
+    const path = claimRecordPath(selected.commonDir, selected.gitDir, options);
     try {
-        const path = recordPath(header, options);
         const metadata = await lstat(path);
         if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
             return null;
-        const bytes = await readFile(path, { signal: options.signal });
-        const value = JSON.parse(bytes.toString("utf8"));
-        if (!isRecord(value)
-            || value.schema !== SCHEMA
-            || value.sessionId !== header.id
-            || value.sessionFile !== header.file
-            || !validPath(value.startupRoot)
-            || !validPath(value.startupCommonDir)
-            || !validPath(value.worktreeRoot)
-            || !validPath(value.worktreeCommonDir)
-            || !validPath(value.worktreeGitDir)
-            || typeof value.updatedAt !== "string")
-            return null;
-        const startup = await readGitWorktreeIdentity(header.cwd, false, options.signal);
-        const selected = await readGitWorktreeIdentity(value.worktreeRoot, true, options.signal);
-        if (!samePath(startup.root, value.startupRoot)
-            || !samePath(startup.commonDir, value.startupCommonDir)
-            || !samePath(selected.root, value.worktreeRoot)
-            || !samePath(selected.commonDir, value.worktreeCommonDir)
-            || !samePath(selected.gitDir, value.worktreeGitDir)
-            || !samePath(startup.commonDir, selected.commonDir))
-            return null;
-        return { cwd: selected.root, branch: requireBranch(selected) };
+        const value = JSON.parse((await readFile(path, { signal: options.signal })).toString("utf8"));
+        return isClaimRecord(value) ? value : null;
     }
-    catch {
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
         return null;
     }
 }
+async function validateContextRecord(header, record, signal) {
+    if (record.sessionId !== header.id || record.sessionFile !== header.file)
+        throw new Error("associated session identity changed");
+    const startup = await readGitWorktreeIdentity(header.cwd, false, signal);
+    const selected = await readGitWorktreeIdentity(record.worktreeRoot, true, signal);
+    if (!samePath(startup.root, record.startupRoot)
+        || !samePath(startup.commonDir, record.startupCommonDir)
+        || !samePath(selected.root, record.worktreeRoot)
+        || !samePath(selected.commonDir, record.worktreeCommonDir)
+        || !samePath(selected.gitDir, record.worktreeGitDir)
+        || !samePath(startup.commonDir, selected.commonDir))
+        throw new Error("associated worktree identity changed");
+    return selected;
+}
+async function releaseClaimsOwnedBy(runtimeId, keepGitDir, options) {
+    const directory = claimsDirectory(options);
+    const names = await readdir(directory).catch(() => []);
+    if (names.length > MAX_WORKTREES * 4)
+        throw contextError("worktree claim store exceeds its bounded limit", "worktree-claim-limit");
+    for (const name of names) {
+        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))) {
+            await rm(path, { force: true });
+        }
+    }
+}
+async function removeMatchingClaim(selected, runtimeId, options) {
+    await removeClaimByGitDir(selected.commonDir, selected.gitDir, runtimeId, options);
+}
+async function removeClaimByGitDir(commonDir, gitDir, runtimeId, options) {
+    const path = claimRecordPath(commonDir, gitDir, options);
+    const claim = await readJsonRecord(path, isClaimRecord);
+    if (claim?.runtimeId === runtimeId)
+        await rm(path, { force: true });
+}
 async function readSessionHeader(identity) {
     if (!validSessionId(identity.sessionId) || !validPath(identity.sessionFile))
         throw new Error("active session identity is unavailable");
@@ -133,27 +344,151 @@ async function readGitWorktreeIdentity(path, requireWorktreeRoot, signal) {
     }
     return { root, commonDir, gitDir, branch };
 }
+async function listGitWorktrees(cwd, commonDir, signal) {
+    const { stdout } = await executeGit(["worktree", "list", "--porcelain", "-z"], cwd, MAX_RECORD_BYTES * 16, signal);
+    const records = [];
+    let current = null;
+    for (const field of stdout.split("\0")) {
+        if (field.length === 0) {
+            if (current !== null)
+                records.push(current);
+            current = null;
+            continue;
+        }
+        if (field.startsWith("worktree "))
+            current = { root: field.slice("worktree ".length), branch: null };
+        else if (current !== null && field.startsWith("branch refs/heads/"))
+            current.branch = field.slice("branch refs/heads/".length);
+    }
+    if (current !== null)
+        records.push(current);
+    return await Promise.all(records.map(async (record) => {
+        const root = await realpath(record.root);
+        const dotGit = join(root, ".git");
+        const metadata = await lstat(dotGit);
+        let gitDir;
+        if (metadata.isDirectory() && !metadata.isSymbolicLink())
+            gitDir = await realpath(dotGit);
+        else if (metadata.isFile() && !metadata.isSymbolicLink() && metadata.size > 0 && metadata.size <= MAX_RECORD_BYTES) {
+            const pointer = (await readFile(dotGit, { signal })).toString("utf8").trim();
+            if (!pointer.startsWith("gitdir: "))
+                throw new Error("worktree Git pointer is invalid");
+            gitDir = await realpath(resolve(root, pointer.slice("gitdir: ".length)));
+        }
+        else
+            throw new Error("worktree Git identity is invalid");
+        return { root, commonDir, gitDir, branch: record.branch };
+    }));
+}
 async function executeGit(arguments_, cwd, maxBuffer, signal) {
     const { execFile } = await import("node:child_process");
     const execute = promisify(execFile);
-    return await execute("git", [...arguments_], {
-        cwd,
-        windowsHide: true,
-        timeout: GIT_TIMEOUT_MS,
-        maxBuffer,
-        encoding: "utf8",
-        signal,
-    });
+    return await execute("git", [...arguments_], { cwd, windowsHide: true, timeout: GIT_TIMEOUT_MS, maxBuffer, encoding: "utf8", signal });
+}
+async function mutationLockExists(options) {
+    try {
+        await lstat(join(claimStoreRoot(options), "mutation.lock"));
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return false;
+        return true;
+    }
+}
+async function withClaimLock(options, operation) {
+    const directory = claimStoreRoot(options);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, "mutation.lock");
+    const deadline = Date.now() + (options.lockTimeoutMs ?? LOCK_TIMEOUT_MS);
+    let handle;
+    while (handle === undefined) {
+        try {
+            handle = await open(path, "wx", 0o600);
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+            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`);
+        return await operation();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+        await rm(path, { force: true }).catch(() => undefined);
+    }
+}
+async function atomicWrite(path, value) {
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+async function readJsonRecord(path, validator) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
+            return null;
+        const value = JSON.parse((await readFile(path)).toString("utf8"));
+        return validator(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function contextRecordPath(header, options) {
+    const dataDir = options.dataDir ?? resolveProductPaths().dataDir;
+    const digest = createHash("sha256").update(header.id).update("\0").update(pathKey(header.file)).digest("hex");
+    return join(dataDir, PRODUCT_IDENTITY.state.sessionRepositoryDirectory, `${digest}.json`);
+}
+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 claimsDirectory(options) {
+    return join(claimStoreRoot(options), "worktrees");
+}
+function claimRecordPath(commonDir, gitDir, options) {
+    return join(claimsDirectory(options), `${digest(`${pathKey(commonDir)}\0${pathKey(gitDir)}`)}.json`);
+}
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function requireRuntimeId(options) {
+    const runtimeId = options.runtimeId;
+    assertRuntimeId(runtimeId);
+    return runtimeId;
+}
+function requireInspector(options) {
+    if (options.inspectProcess === undefined)
+        throw contextError("native process identity inspection is unavailable", "process-inspection-unavailable");
+    return options.inspectProcess;
+}
+function processIdentityOf(record) {
+    return { pid: record.pid, startIdentity: record.startIdentity };
 }
 function requireBranch(identity) {
     if (identity.branch === null)
         throw new Error("associated worktree branch is unavailable");
     return identity.branch;
 }
-function recordPath(header, options) {
-    const dataDir = options.dataDir ?? resolveProductPaths().dataDir;
-    const digest = createHash("sha256").update(header.id).update("\0").update(pathKey(header.file)).digest("hex");
-    return join(dataDir, PRODUCT_IDENTITY.state.sessionRepositoryDirectory, `${digest}.json`);
+function claimMatchesWorktree(claim, worktree) {
+    return samePath(claim.worktreeRoot, worktree.root)
+        && samePath(claim.worktreeCommonDir, worktree.commonDir)
+        && samePath(claim.worktreeGitDir, worktree.gitDir);
 }
 function samePath(left, right) {
     return pathKey(left) === pathKey(right);
@@ -162,12 +497,45 @@ function pathKey(value) {
     const normalized = resolve(value);
     return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
+function assertRuntimeId(value) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u.test(value)) {
+        throw contextError("active session runtime identity is unavailable", "session-runtime-unavailable");
+    }
+}
+function assertProcessIdentity(value) {
+    if (!Number.isSafeInteger(value.pid) || value.pid <= 0 || typeof value.startIdentity !== "string"
+        || value.startIdentity.length === 0 || value.startIdentity.length > 512 || value.startIdentity.includes("\0")) {
+        throw contextError("native process identity is invalid", "process-identity-invalid");
+    }
+}
 function validSessionId(value) {
     return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u.test(value);
 }
 function validPath(value) {
     return typeof value === "string" && value.length > 0 && value.length <= 32_768 && !value.includes("\0") && isAbsolute(value);
 }
+function isContextRecord(value) {
+    return isRecord(value) && value.schema === CONTEXT_SCHEMA && validSessionId(value.sessionId)
+        && validPath(value.sessionFile) && validPath(value.startupRoot) && validPath(value.startupCommonDir)
+        && 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
+        && 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)
+        && 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 isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function contextError(message, code) {
+    return Object.assign(new Error(message), { code });
+}

package/dist/foundation/process-containment/index.d.ts

@@ -4,5 +4,6 @@ export type { ContainedProcessHandle, ContainedSpawnOptions, ContainmentCloseRes
 export { DarwinNativeProcessInspector } from "./darwin-process-inspector.js";
 export { LinuxNativeProcessInspector } from "./linux-process-inspector.js";
 export { NativeGuardianContainment, resolveProcessGuardianPath } from "./native-guardian-containment.js";
+export { createNativeProcessInspector } from "./native-process-inspector.js";
 export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";
 export type { InspectorCommandResult, InspectorCommandRunner } from "./windows-process-inspector.js";

package/dist/foundation/process-containment/index.js

@@ -3,4 +3,5 @@ export { closeVerifiedContainment } from "./contracts.js";
 export { DarwinNativeProcessInspector } from "./darwin-process-inspector.js";
 export { LinuxNativeProcessInspector } from "./linux-process-inspector.js";
 export { NativeGuardianContainment, resolveProcessGuardianPath } from "./native-guardian-containment.js";
+export { createNativeProcessInspector } from "./native-process-inspector.js";
 export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";

package/dist/foundation/process-containment/native-process-inspector.d.ts

@@ -0,0 +1,3 @@
+import type { NativeProcessInspector } from "./contracts.js";
+/** Resolve only the platform's exact-process inspector used by cooperative session ownership. */
+export declare function createNativeProcessInspector(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, releaseRoot?: string): Promise<NativeProcessInspector>;

package/dist/foundation/process-containment/native-process-inspector.js

@@ -0,0 +1,21 @@
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/** Resolve only the platform's exact-process inspector used by cooperative session ownership. */
+export async function createNativeProcessInspector(environment = process.env, platform = process.platform, releaseRoot) {
+    if (platform === "linux") {
+        const { LinuxNativeProcessInspector } = await import("./linux-process-inspector.js");
+        return new LinuxNativeProcessInspector();
+    }
+    if (platform !== "win32" && platform !== "darwin")
+        throw new Error(`native process identity is unsupported on ${platform}`);
+    if (releaseRoot === undefined && !environment[PRODUCT_IDENTITY.environment.processGuardianPath]) {
+        throw new Error("native process identity helper is unavailable");
+    }
+    const { resolveProcessGuardianPath } = await import("./native-guardian-containment.js");
+    const helper = resolveProcessGuardianPath(releaseRoot ?? process.cwd(), environment, platform);
+    if (platform === "win32") {
+        const { WindowsNativeProcessInspector } = await import("./windows-process-inspector.js");
+        return new WindowsNativeProcessInspector(helper);
+    }
+    const { DarwinNativeProcessInspector } = await import("./darwin-process-inspector.js");
+    return new DarwinNativeProcessInspector(helper);
+}

package/dist/foundation/release/bootstrap.js

@@ -2,7 +2,6 @@ import { spawn } from "node:child_process";
 import { restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { connect } from "node:net";
-import { platform } from "node:os";
 import { resolve } from "node:path";
 import { selectCohortLaunch } from "./cohort-selection.js";
 import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
@@ -16,7 +15,7 @@ import { selectUpdateLaunchRelease } from "./update-launch.js";
 import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
-import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { PRODUCT_TEXT } from "../../product-identity.js";
 import { markStartupPhase } from "../startup/index.js";
 import { launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
 const RELEASE_RESELECTION_MESSAGE = "a1-release-reselection";

package/dist/foundation/release/progress-palette.generated.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generated by scripts/pi/sync-progress-palette.ts from @earendil-works/pi-coding-agent 1.0.4
- * (MIT), commit 7c10bd4337495ee613f2224843ecdf349b80d1df. Do not edit directly.
+ * Generated by scripts/pi/sync-progress-palette.ts from @earendil-works/pi-coding-agent 1.1.0
+ * (MIT), commit abe508e1b89912adde45528136c3221eb69acdd7. Do not edit directly.
  */
 export declare const SHARED_PROGRESS_ACCENT_ANSI = "\u001B[38;2;167;152;215m";

package/dist/foundation/release/progress-palette.generated.js

@@ -1,5 +1,5 @@
 /**
- * Generated by scripts/pi/sync-progress-palette.ts from @earendil-works/pi-coding-agent 1.0.4
- * (MIT), commit 7c10bd4337495ee613f2224843ecdf349b80d1df. Do not edit directly.
+ * Generated by scripts/pi/sync-progress-palette.ts from @earendil-works/pi-coding-agent 1.1.0
+ * (MIT), commit abe508e1b89912adde45528136c3221eb69acdd7. Do not edit directly.
  */
 export const SHARED_PROGRESS_ACCENT_ANSI = "\u001b[38;2;167;152;215m";

package/dist/foundation/release/release-gc.js

@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { CohortStateStore, planProtectedReleases, } from "./cohort-state.js";
+import { CohortStateStore, } from "./cohort-state.js";
 import { liveReleaseIds } from "./endpoints.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
 import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";