@timurproko/a1 0.2.7-dev.1276 → 0.2.7-dev.1286

package/dist/foundation/lifecycle/session-claim-lock.js

@@ -4,18 +4,44 @@ import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { tryAcquireClaimGate } from "./claim-gate.js";
 const FILES = new Set(["owner.json", "owner.next", "recovery.json", "recovery.next"]);
-/** Inventory is advisory and read-only, including when abandoned metadata needs recovery. */
-export async function claimMutationPending(directory) {
+/** Read a consistent claim snapshot without publishing or repairing mutation metadata. */
+export async function withSessionClaimSnapshot(directory, options, operation) {
+    let canonical;
     try {
-        const barrier = join(directory, "mutation.lock");
-        const metadata = await lstat(barrier);
-        if (!metadata.isDirectory() || metadata.isSymbolicLink())
-            return true;
-        const files = await readdir(barrier);
-        return files.some(name => name !== "recovery.json");
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        canonical = await realpath(directory);
     }
-    catch (error) {
-        return !hasCode(error, "ENOENT");
+    catch (cause) {
+        throw failure("worktree-coordination-io", "cannot access worktree coordination; check permissions and filesystem availability", cause);
+    }
+    const deadline = Date.now() + (options.lockTimeoutMs ?? 5_000);
+    for (;;) {
+        options.signal?.throwIfAborted();
+        const gate = tryAcquireClaimGate(join(canonical, "mutation.authority"));
+        if (gate !== null) {
+            try {
+                const barrier = await lstat(join(canonical, "mutation.lock")).catch(error => {
+                    if (hasCode(error, "ENOENT"))
+                        return null;
+                    throw error;
+                });
+                if (barrier !== null && (!barrier.isDirectory() || barrier.isSymbolicLink())) {
+                    throw failure("worktree-legacy-recovery-required", "older coordination state requires recovery before a consistent inventory can be read");
+                }
+                return await operation();
+            }
+            catch (error) {
+                if (error instanceof Error && (error.name === "AbortError" || ("code" in error && String(error.code).startsWith("worktree-"))))
+                    throw error;
+                throw failure("worktree-coordination-io", "cannot read worktree coordination; check permissions and filesystem availability", error);
+            }
+            finally {
+                gate.release();
+            }
+        }
+        if (Date.now() >= deadline)
+            throw failure("worktree-claim-busy", "worktree coordination did not settle within the operation budget; no worktree ownership was changed");
+        await delay(20, undefined, { signal: options.signal });
     }
 }
 /**

package/dist/foundation/lifecycle/session-context-retry.d.ts

@@ -0,0 +1,2 @@
+/** Transient coordination belongs to the operation, never an agent-authored retry procedure. */
+export declare function retrySessionCoordination<T>(operation: () => Promise<T>, budgetMs?: number, signal?: AbortSignal): Promise<T>;

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

@@ -0,0 +1,17 @@
+import { setTimeout as delay } from "node:timers/promises";
+/** Transient coordination belongs to the operation, never an agent-authored retry procedure. */
+export async function retrySessionCoordination(operation, budgetMs = 8_000, signal) {
+    const deadline = Date.now() + budgetMs;
+    for (;;) {
+        signal?.throwIfAborted();
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? error.code : null;
+            if (!["worktree-claim-busy", "session-runtime-unavailable", "worktree-context-changed"].includes(String(code)) || Date.now() >= deadline)
+                throw error;
+            await delay(Math.min(150, Math.max(1, deadline - Date.now())), undefined, { signal });
+        }
+    }
+}

package/dist/foundation/lifecycle/session-repository-context.d.ts

@@ -49,5 +49,11 @@ export interface SessionRepositoryObservation {
  * The callback must not perform asynchronous work; provider I/O never holds this gate.
  */
 export declare function withSessionRepositoryObservation<T>(identity: SessionRepositoryIdentity, consume: (context: SessionRepositoryObservation) => T, options?: SessionRepositoryContextOptions): Promise<T>;
-/** List same-repository worktrees without acquiring, releasing, or repairing a claim. */
+/** Validate the command's existing runtime before any Git worktree creation. */
+export declare function assertSessionRepositoryRuntime(identity: SessionRepositoryIdentity, options: SessionRepositoryContextOptions): Promise<void>;
+/** Startup root used by product worktree operations; the durable session header stays unchanged. */
+export declare function readSessionStartupRoot(identity: SessionRepositoryIdentity): Promise<string>;
+/** Read a live attachment without activating or rewriting its claim. Invalid state never means detached. */
+export declare function readActiveSessionRepositoryContext(identity: SessionRepositoryIdentity, options: SessionRepositoryContextOptions): Promise<SessionRepositoryObservation | null>;
+/** List same-repository worktrees without acquiring, releasing, or repairing an editing claim. */
 export declare function listSessionRepositoryWorktrees(identity: SessionRepositoryIdentity, options?: SessionRepositoryContextOptions): Promise<readonly SessionWorktreeInventoryEntry[]>;

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

@@ -5,7 +5,7 @@ import { promisify } from "node:util";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { inspectLiveProcess } from "./process-liveness.js";
 import { resolveProductPaths } from "./paths.js";
-import { claimMutationPending, withSessionClaimLock } from "./session-claim-lock.js";
+import { withSessionClaimSnapshot, withSessionClaimLock } from "./session-claim-lock.js";
 const CONTEXT_SCHEMA = "a1-session-repository-context-v1";
 const RUNTIME_SCHEMA = "a1-session-runtime-v1";
 const CLAIM_SCHEMA = "a1-session-worktree-claim-v1";
@@ -77,9 +77,28 @@ 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");
     }
+    if (samePath(selected.gitDir, selected.commonDir)) {
+        throw contextError("task attachment requires a linked worktree, not the primary checkout", "worktree-primary-checkout");
+    }
+    const registered = await listGitWorktrees(startup.root, startup.commonDir, options.signal);
+    if (!registered.some(entry => !("stale" in entry) && samePath(entry.root, selected.root) && samePath(entry.gitDir, selected.gitDir))) {
+        throw contextError("selected path is not a registered worktree", "worktree-not-registered");
+    }
+    if (await lstat(join(selected.gitDir, "locked")).then(() => true, error => { if (isMissingPathError(error))
+        return false; throw error; })) {
+        throw contextError("selected worktree is locked in Git", "worktree-git-locked");
+    }
     const owner = { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) };
     return await withClaimLock(options, async () => {
         const runtime = await requireLiveRuntime(header, owner, options);
+        const current = await readGitWorktreeIdentity(selected.root, true, options.signal);
+        if (!samePath(current.gitDir, selected.gitDir) || !samePath(current.commonDir, selected.commonDir) || current.branch !== selected.branch) {
+            throw contextError("worktree changed while attaching", "worktree-context-changed");
+        }
+        if (await lstat(join(selected.gitDir, "locked")).then(() => true, error => { if (isMissingPathError(error))
+            return false; throw error; })) {
+            throw contextError("selected worktree is locked in Git", "worktree-git-locked");
+        }
         const status = await claimAvailability(selected, owner, options);
         if (status === "busy")
             throw contextError("worktree is active in another session", "worktree-active-in-another-session");
@@ -185,7 +204,44 @@ export async function withSessionRepositoryObservation(identity, consume, option
         return consume(context);
     });
 }
-/** List same-repository worktrees without acquiring, releasing, or repairing a claim. */
+/** Validate the command's existing runtime before any Git worktree creation. */
+export async function assertSessionRepositoryRuntime(identity, options) {
+    await requireLiveRuntime(await readSessionHeader(identity), { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) }, options);
+}
+/** Startup root used by product worktree operations; the durable session header stays unchanged. */
+export async function readSessionStartupRoot(identity) {
+    return (await readSessionHeader(identity)).cwd;
+}
+/** Read a live attachment without activating or rewriting its claim. Invalid state never means detached. */
+export async function readActiveSessionRepositoryContext(identity, options) {
+    const header = await readSessionHeader(identity);
+    const owner = { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) };
+    await requireLiveRuntime(header, owner, options);
+    const path = contextRecordPath(header, options);
+    const metadata = await lstat(path).catch(error => { if (isMissingPathError(error))
+        return null; throw error; });
+    if (metadata === null)
+        return null;
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > MAX_RECORD_BYTES) {
+        throw contextError("repository attachment cannot be verified", "worktree-owner-unverifiable");
+    }
+    const record = await readContextRecord(header, options);
+    if (record === null)
+        throw contextError("repository attachment cannot be verified", "worktree-owner-unverifiable");
+    const selected = await validateContextRecord(header, record, options.signal);
+    const claim = await readClaim(selected, options);
+    if (claim === undefined)
+        throw contextError("the editing claim needs reactivation", "worktree-context-changed");
+    if (claim === null || !claimMatchesWorktree(claim, selected) || !ownedBy(claim, owner)) {
+        throw contextError("the session no longer owns its attached worktree", "worktree-owner-unverifiable");
+    }
+    const after = await readContextRecord(header, options);
+    if (after === null || after.revision !== record.revision || !samePath(after.worktreeGitDir, record.worktreeGitDir)) {
+        throw contextError("repository attachment changed during observation", "worktree-context-changed");
+    }
+    return { cwd: selected.root, branch: requireBranch(selected), revision: record.revision ?? "legacy" };
+}
+/** List same-repository worktrees without acquiring, releasing, or repairing an editing claim. */
 export async function listSessionRepositoryWorktrees(identity, options = {}) {
     const header = await readSessionHeader(identity);
     const owner = { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) };
@@ -194,22 +250,23 @@ export async function listSessionRepositoryWorktrees(identity, options = {}) {
     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 ("stale" in selected) {
-            entries.push({ cwd: selected.root, branch: selected.branch ?? "(detached)", status: "unverifiable", agentId: null });
-            continue;
-        }
-        if (selected.branch === null) {
-            entries.push({ cwd: selected.root, branch: "(detached)", status: "unverifiable", agentId: null });
-            continue;
+    return await withSessionClaimSnapshot(claimStoreRoot(options), options, async () => {
+        const entries = [];
+        for (const selected of worktrees) {
+            if ("stale" in selected) {
+                entries.push({ cwd: selected.root, branch: selected.branch ?? "(detached)", status: "unverifiable", agentId: null });
+                continue;
+            }
+            if (selected.branch === null) {
+                entries.push({ cwd: selected.root, branch: "(detached)", status: "unverifiable", agentId: null });
+                continue;
+            }
+            const status = 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 });
         }
-        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)));
+        return entries.sort((left, right) => pathKey(left.cwd).localeCompare(pathKey(right.cwd)));
+    });
 }
 async function requireLiveRuntime(header, owner, options) {
     const runtime = await readRuntimeRecord(owner, options);
@@ -466,27 +523,39 @@ async function listGitWorktrees(cwd, commonDir, signal) {
     if (current !== null)
         records.push(current);
     return await Promise.all(records.map(async (record) => {
-        const root = await realpath(record.root).catch(error => { if (isMissingPathError(error))
-            return null; throw error; });
-        if (root === null)
+        try {
+            const root = await realpath(record.root).catch(error => { if (isMissingPathError(error))
+                return null; throw error; });
+            if (root === null)
+                return { stale: true, root: resolve(record.root), branch: record.branch };
+            const dotGit = join(root, ".git");
+            const metadata = await lstat(dotGit).catch(error => { if (isMissingPathError(error))
+                return null; throw error; });
+            if (metadata === null)
+                return { stale: true, root, branch: record.branch };
+            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");
+            if (!samePath(gitDir, commonDir)) {
+                const common = await realpath(resolve(gitDir, (await readFile(join(gitDir, "commondir"), "utf8")).trim()));
+                if (!samePath(common, commonDir))
+                    throw new Error("registered worktree points to a different repository");
+            }
+            return { root, commonDir, gitDir, branch: record.branch };
+        }
+        catch {
+            signal?.throwIfAborted();
+            // Invariant: a broken unrelated registration is one unverifiable row, not a repository-wide veto.
             return { stale: true, root: resolve(record.root), branch: record.branch };
-        const dotGit = join(root, ".git");
-        const metadata = await lstat(dotGit).catch(error => { if (isMissingPathError(error))
-            return null; throw error; });
-        if (metadata === null)
-            return { stale: true, root, branch: record.branch };
-        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 };
     }));
 }
 /** True for the errors a deleted directory or file produces, which mark a registered worktree as stale rather than broken. */
@@ -498,9 +567,6 @@ async function executeGit(arguments_, cwd, maxBuffer, signal) {
     const execute = promisify(execFile);
     return await execute("git", [...arguments_], { cwd, windowsHide: true, timeout: GIT_TIMEOUT_MS, maxBuffer, encoding: "utf8", signal });
 }
-async function mutationLockExists(options) {
-    return await claimMutationPending(claimStoreRoot(options));
-}
 async function withClaimLock(options, operation) {
     return await withSessionClaimLock(claimStoreRoot(options), options, operation);
 }

package/dist/foundation/lifecycle/session-worktree-entry.d.ts

@@ -0,0 +1,3 @@
+import { type SessionRepositoryContext, type SessionRepositoryContextOptions, type SessionRepositoryIdentity } from "./session-repository-context.js";
+/** Create or resume a matching registered checkout. Failed attachment never deletes existing work. */
+export declare function enterSessionRepositoryWorktree(identity: SessionRepositoryIdentity, branch: string, base: string | undefined, options: SessionRepositoryContextOptions): Promise<SessionRepositoryContext>;

package/dist/foundation/lifecycle/session-worktree-entry.js

@@ -0,0 +1,87 @@
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { assertSessionRepositoryRuntime, readSessionStartupRoot, setSessionRepositoryContext, } from "./session-repository-context.js";
+/** Create or resume a matching registered checkout. Failed attachment never deletes existing work. */
+export async function enterSessionRepositoryWorktree(identity, branch, base, options) {
+    if (!/^[a-z][a-z0-9-]*\/[a-z0-9][a-z0-9-]{0,99}$/u.test(branch)) {
+        throw failure("worktree-branch-invalid", "use a task branch such as fix/short-description");
+    }
+    await assertSessionRepositoryRuntime(identity, options);
+    const startup = await readSessionStartupRoot(identity);
+    // Performance: unrelated lifecycle consumers do not need Git process bindings at import time.
+    const { execFile } = await import("node:child_process");
+    const execute = promisify(execFile);
+    const git = async (...args) => (await execute("git", ["-c", "core.hooksPath=/dev/null", ...args], {
+        cwd: startup, encoding: "utf8", windowsHide: true, timeout: 15_000, maxBuffer: 256 * 1024, signal: options.signal,
+    })).stdout.trim();
+    const inventory = await git("worktree", "list", "--porcelain", "-z");
+    const rows = inventory.split("\0\0").filter(Boolean).map(record => {
+        const fields = record.split("\0");
+        return {
+            root: fields.find(field => field.startsWith("worktree "))?.slice(9),
+            branch: fields.find(field => field.startsWith("branch refs/heads/"))?.slice(18),
+        };
+    });
+    const primary = rows[0]?.root;
+    if (primary === undefined)
+        throw failure("worktree-repository-invalid", "cannot determine the primary Git checkout");
+    const root = await realpath(primary);
+    const worktreeRoot = join(root, ".worktrees");
+    await mkdir(worktreeRoot, { recursive: true });
+    const directory = await lstat(worktreeRoot);
+    if (!directory.isDirectory() || directory.isSymbolicLink()) {
+        throw failure("worktree-path-collision", "the worktree directory is a link or unexpected entry; it was preserved");
+    }
+    const path = join(worktreeRoot, branch.slice(branch.indexOf("/") + 1));
+    const matching = rows.find(row => row.branch === branch);
+    if (matching !== undefined) {
+        if (matching.root === undefined || !samePath(await realpath(matching.root), path)) {
+            throw failure("worktree-branch-collision", "the task branch is checked out at another path; attach its exact worktree instead");
+        }
+        return await setSessionRepositoryContext(identity, path, options);
+    }
+    if (await lstat(path).then(() => true, error => { if (hasCode(error, "ENOENT"))
+        return false; throw error; })) {
+        throw failure("worktree-path-collision", "the task path already exists; existing files were preserved");
+    }
+    if (await git("branch", "--list", branch)) {
+        throw failure("worktree-branch-collision", "the branch already exists without a matching checkout; existing history was preserved");
+    }
+    // Security: never execute repository setup. The selected base is data, not a shell expression.
+    const configured = base ?? await git("config", "--get", "a1.worktreeBase").catch(() => "");
+    const remotes = (await git("remote")).split(/\r?\n/u);
+    let selectedBase = configured;
+    if (remotes.includes("origin")) {
+        if (!selectedBase) {
+            selectedBase = await git("symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD").catch(() => "");
+            if (!selectedBase) {
+                const head = await git("ls-remote", "--symref", "origin", "HEAD");
+                selectedBase = /^ref: refs\/heads\/([^\t\r\n]+)\tHEAD/mu.exec(head)?.[1] ?? "";
+            }
+        }
+        const name = selectedBase.replace(/^origin\//u, "");
+        if (!name || name.startsWith("-") || !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/u.test(name)) {
+            throw failure("worktree-base-invalid", "cannot determine a safe base branch; select it with --base");
+        }
+        await git("check-ref-format", `refs/heads/${name}`);
+        await git("fetch", "--no-tags", "origin", `refs/heads/${name}:refs/remotes/origin/${name}`);
+        selectedBase = `refs/remotes/origin/${name}`;
+    }
+    else {
+        selectedBase ||= (await execute("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+            cwd: root, encoding: "utf8", windowsHide: true, timeout: 5_000, signal: options.signal,
+        })).stdout.trim();
+        if (!selectedBase || selectedBase.startsWith("-"))
+            throw failure("worktree-base-invalid", "select a base branch with --base");
+        await git("check-ref-format", `refs/heads/${selectedBase}`);
+    }
+    await git("worktree", "add", "--no-track", "-b", branch, path, selectedBase);
+    return await setSessionRepositoryContext(identity, path, options);
+}
+function samePath(left, right) {
+    const key = (value) => process.platform === "win32" ? resolve(value).toLowerCase() : resolve(value);
+    return key(left) === key(right);
+}
+function hasCode(error, code) { return error instanceof Error && "code" in error && error.code === code; }
+function failure(code, message) { return Object.assign(new Error(message), { code }); }

package/dist/foundation/release/automatic-update.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawnReleaseEntry } from "./release-use.js";
 import { randomUUID } from "node:crypto";
 import { watch } from "node:fs";
 import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
@@ -337,7 +337,7 @@ async function recordAutomaticPreflightFailure(parsed, dataDir) {
     }
 }
 async function spawnAutomaticUpdateWorker(entry, arguments_, environment) {
-    const child = spawn(process.execPath, [entry, ...arguments_], {
+    const child = await spawnReleaseEntry(entry, arguments_, {
         detached: true,
         env: environment,
         stdio: "ignore",

package/dist/foundation/release/bootstrap.js

@@ -4,6 +4,7 @@ import { deliverExitNotice, restoreAfterOwnedExit } from "../terminal-cleanup/in
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
+import { acquireReleaseUse } from "./release-use.js";
 import { ReleaseStateStore } from "./release-state.js";
 import { assertLaunchProfileId, resolveProductPaths, sessionSelectionArguments } from "../lifecycle/index.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
@@ -31,7 +32,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     const paths = resolveProductPaths(environment);
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const launchSelected = async (release) => {
-        const result = await launchUi(release, environment, sessionArgs, paths.runtimeDir);
+        const result = await launchUi(release, environment, sessionArgs, paths.runtimeDir, paths.dataDir);
         if (!result.releaseSuperseded)
             return result.code;
         if (retriesRemaining > 0)
@@ -205,7 +206,16 @@ export async function recordParentCertifiedRelease(release, dataDir) {
  * Run the selected release's UI as the one attached child. The launcher still owns the terminal,
  * so when the child ends uncleanly it restores the terminal and prints any notice the UI left armed.
  */
-async function launchUi(release, environment, sessionArgs, runtimeDir) {
+async function launchUi(release, environment, sessionArgs, runtimeDir, dataDir) {
+    const use = await acquireReleaseUse(dataDir, release.releaseId);
+    try {
+        return await launchClaimedUi(release, environment, sessionArgs, runtimeDir, use);
+    }
+    finally {
+        await use.release().catch(() => undefined);
+    }
+}
+async function launchClaimedUi(release, environment, sessionArgs, runtimeDir, use) {
     await markStartupPhase(environment, "bootstrap-selected");
     const entry = await resolveReleaseEntryPoint(release, "bin/ui.js");
     const ownsTerminal = readLaunchContext(environment).launchProfile === "a1";
@@ -223,13 +233,19 @@ async function launchUi(release, environment, sessionArgs, runtimeDir) {
             stdio: ["inherit", "inherit", "inherit", "ipc"],
             windowsHide: false,
         });
+        let handoff = Promise.resolve();
+        child.once("spawn", () => {
+            // Security: failure keeps the durable launching reservation rather than guessing the child dead.
+            handoff = use.started(child.pid).catch(() => undefined);
+        });
         child.on("message", message => {
             if (message && typeof message === "object" && "type" in message && message.type === RELEASE_RESELECTION_MESSAGE) {
                 releaseSuperseded = true;
             }
         });
         child.once("error", rejectPromise);
-        child.once("close", (code, signal) => {
+        child.once("close", async (code, signal) => {
+            await handoff;
             const outcome = releaseSuperseded ? code ?? 1 : restoreAfterOwnedExit(ownsTerminal, code, signal);
             // Invariant: the UI removes its notice on a clean exit; one still armed means the UI died.
             if (ownsTerminal)

package/dist/foundation/release/index.d.ts

@@ -1,7 +1,7 @@
 export { certifyMaterializedRelease, recordParentCertifiedRelease, releaseEnvironment, runBootstrap, } from "./bootstrap.js";
 export type { BootstrapOptions } from "./bootstrap.js";
 export { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
-export { ReleaseStateStore, RELEASE_STATE_SCHEMA, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
+export { ReleaseStateStore, ReleaseStateNewerError, isReleaseStateNewerError, RELEASE_STATE_SCHEMA, RELEASE_STATE_LEVEL, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
 export type { ActiveReleaseTransactionReference, ReleaseState, OrphanReleaseDisposition, ProtectedReleaseInputs, ProtectedReleasePlan, ReleaseApproval, ReleaseCleanupDiagnostic, ReleaseCleanupDisposition, ReleaseCleanupStage, ReleaseCleanupState, ReleaseCleanupWorkerRun, ReleaseCleanupWorkerStatus, ReleaseCleanupWorkerSummary, ReleaseRecord, ReleaseReferences, ReleaseRetentionReconciliation, } from "./release-state.js";
 export { DEPENDENCY_LAYER_MANIFEST, DEPENDENCY_LAYER_SCHEMA, RUNTIME_PAYLOAD_INVENTORY, dependencyLayerCertificationPath, dependencyReference, generateDependencyRuntimePayload, legacyDependencyLayerCertificationPath, materializeDependencyLayer, readCertifiedDependencyLayer, selectDependencyRuntimePayload, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 export type { DependencyLayerIdentity, DependencyLayerOperationEvent, DependencyLayerReference, GeneratedRuntimePayload, MaterializeDependencyLayerOptions, MaterializedDependencyLayer, PublishedRuntimeFileClassification, PublishedRuntimePayload, ReadCertifiedDependencyLayerOptions, RuntimePayloadExclusion, RuntimePayloadInventory, SelectedRuntimePayload, } from "./dependency-layer.js";

package/dist/foundation/release/index.js

@@ -1,6 +1,6 @@
 export { certifyMaterializedRelease, recordParentCertifiedRelease, releaseEnvironment, runBootstrap, } from "./bootstrap.js";
 export { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
-export { ReleaseStateStore, RELEASE_STATE_SCHEMA, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
+export { ReleaseStateStore, ReleaseStateNewerError, isReleaseStateNewerError, RELEASE_STATE_SCHEMA, RELEASE_STATE_LEVEL, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
 export { DEPENDENCY_LAYER_MANIFEST, DEPENDENCY_LAYER_SCHEMA, RUNTIME_PAYLOAD_INVENTORY, dependencyLayerCertificationPath, dependencyReference, generateDependencyRuntimePayload, legacyDependencyLayerCertificationPath, materializeDependencyLayer, readCertifiedDependencyLayer, selectDependencyRuntimePayload, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 export { processIsAlive } from "./process-liveness.js";
 export { PRODUCT_PACKAGE_NAME, createReleaseIdentity, deriveReleaseIdentity, digestManifestFiles, discoverReleasePayload, packageRootFromModule, releaseFileIdentity, resolveWithin, } from "./release.js";

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

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
+import { spawnReleaseEntry } from "./release-use.js";
 import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
 import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ReleaseStateStore, } from "./release-state.js";
+import { ReleaseStateStore, releaseUseIsLive, isReleaseStateNewerError, } from "./release-state.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
 import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
 import { DEPENDENCY_LAYER_MANIFEST, readCertifiedDependencyLayer } from "./dependency-layer.js";
@@ -130,6 +130,16 @@ export async function runBoundedReleaseCleanup(dataDir, paths, options = {}) {
  * potentially slow recursive deletion. A later launch/update resumes work if spawning fails.
  */
 export async function scheduleReleaseCleanup(dataDir, paths, options = {}) {
+    try {
+        await scheduleOwnedReleaseCleanup(dataDir, paths, options);
+    }
+    catch (error) {
+        // Compatibility: a newer release owns state this code may not write; its own maintenance cleans up.
+        if (!isReleaseStateNewerError(error))
+            throw error;
+    }
+}
+async function scheduleOwnedReleaseCleanup(dataDir, paths, options) {
     const { store } = await prepareReleaseCleanup(dataDir, paths, options);
     const runId = randomUUID();
     await store.recordCleanupWorkerScheduled(runId);
@@ -152,6 +162,17 @@ export async function scheduleReleaseCleanup(dataDir, paths, options = {}) {
 }
 /** Entry used by the private cleanup executable shipped in every immutable release. */
 export async function runReleaseCleanupWorker(environment = process.env, workerOptions = {}) {
+    try {
+        return await runOwnedReleaseCleanupWorker(environment, workerOptions);
+    }
+    catch (error) {
+        // Compatibility: a worker started by an older release stands down once a newer release owns the state.
+        if (!isReleaseStateNewerError(error))
+            throw error;
+        return { planned: 0, attempted: 0, completed: 0, remaining: 0, durationMs: 0 };
+    }
+}
+async function runOwnedReleaseCleanupWorker(environment, workerOptions) {
     const paths = resolveProductPaths(environment);
     const store = new ReleaseStateStore(paths.dataDir);
     const runId = environment[WORKER_RUN_ID_ENV] ?? randomUUID();
@@ -233,7 +254,8 @@ async function collectDisposition(store, dataDir, disposition, options) {
     try {
         const inputs = await protectionInputs(options.transactionStore ?? new UpdateTransactionStore(dataDir), options);
         const current = await store.read();
-        if (isProtectedDetachedRelease(current, inputs, releaseId))
+        if (isProtectedDetachedRelease(current, inputs, releaseId)
+            || (disposition.release.approval === "approved" && disposition.release.lifetimeClaims !== true))
             return false;
         const storeRoot = await canonicalReleaseStore(dataDir);
         const trashRoot = await canonicalTrashRoot(storeRoot);
@@ -252,7 +274,19 @@ async function collectDisposition(store, dataDir, disposition, options) {
             else {
                 await assertReleaseDirectory(source, storeRoot, disposition.release, releaseId);
                 trashPath = resolve(trashRoot, `${releaseId}--${randomUUID()}`);
-                await (options.operations?.rename ?? rename)(source, trashPath);
+                let moved = false;
+                const destination = trashPath;
+                // Concurrency: claim admission and destructive rename share the state gate. A launch recorded
+                // after discovery cannot slip between the last protection read and deletion.
+                await store.update(async (latest) => {
+                    if (!isProtectedDetachedRelease(latest, inputs, releaseId)) {
+                        await (options.operations?.rename ?? rename)(source, destination);
+                        moved = true;
+                    }
+                    return latest;
+                });
+                if (!moved)
+                    return false;
             }
             await store.markCleanupTrash(releaseId, trashPath);
         }
@@ -274,6 +308,7 @@ function isProtectedDetachedRelease(state, inputs, releaseId) {
         .some(reference => reference === releaseId);
     // Concurrency: a launch may have recorded the same release again after it was detached.
     return selected
+        || Object.values(state.uses ?? {}).some(claim => claim.releaseId === releaseId && releaseUseIsLive(claim))
         || state.releases[releaseId] !== undefined
         || (inputs.ownReleaseIds ?? []).includes(releaseId)
         || (inputs.transaction?.status === "active" && inputs.transaction.priorActiveReleaseId === releaseId);
@@ -392,6 +427,7 @@ async function readReleaseRecord(path, parent, expectedName, dataDir) {
         releaseRoot: resolve(parent, manifest.releaseId),
         packageVersion: manifest.packageVersion,
         contentDigest: manifest.contentDigest,
+        ...(Array.isArray(manifest.files) && manifest.files.some(file => file?.path === "dist/foundation/release/release-use.js") ? { lifetimeClaims: true } : {}),
         approval: "approved",
         materializedAt: new Date(0).toISOString(),
         certifiedAt: null,
@@ -661,7 +697,7 @@ function sortArtifacts(artifacts, state) {
         || artifactName(left).localeCompare(artifactName(right)));
 }
 async function spawnCleanupWorker(entry, environment) {
-    const child = spawn(process.execPath, [entry], {
+    const child = await spawnReleaseEntry(entry, [], {
         detached: true,
         windowsHide: true,
         stdio: "ignore",