@timurproko/a1 0.2.7-dev.1241 → 0.2.7-dev.1245

package/dist/foundation/lifecycle/native-claim-gate.d.ts

@@ -0,0 +1,5 @@
+export interface ClaimGateHandle {
+    release(): void;
+}
+/** No PID-file fallback: only the platform descriptor can prove upgraded-writer exclusion. */
+export declare function tryAcquireClaimGate(path: string): ClaimGateHandle | null;

package/dist/foundation/lifecycle/native-claim-gate.js

@@ -0,0 +1,41 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+let backend;
+/** No PID-file fallback: only the platform descriptor can prove upgraded-writer exclusion. */
+export function tryAcquireClaimGate(path) {
+    if (backend === undefined) {
+        const require = createRequire(import.meta.url);
+        // Security: resolve only this release's addon, never a binary supplied by tool cwd.
+        const own = resolve(fileURLToPath(new URL("../../../", import.meta.url)), "dist", "native", `${process.platform}-${process.arch}`, `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`);
+        const override = process.env[PRODUCT_IDENTITY.environment.developmentInstanceId]
+            ? process.env[PRODUCT_IDENTITY.environment.terminalHostPath] : undefined;
+        for (const candidate of override ? [override, own] : [own]) {
+            if (!existsSync(candidate))
+                continue;
+            try {
+                const loaded = require(candidate);
+                if (typeof loaded.SessionLock?.tryAcquireGate === "function") {
+                    backend = loaded.SessionLock;
+                    break;
+                }
+            }
+            catch { /* Compatibility: an unusable addon is unavailable, not contended. */ }
+        }
+    }
+    if (backend === undefined)
+        throw Object.assign(new Error("native worktree coordination is unavailable; repair or update this A1 installation and retry"), {
+            code: "worktree-coordination-unavailable",
+        });
+    try {
+        const handle = backend.tryAcquireGate(path);
+        return handle.acquired ? handle : null;
+    }
+    catch (cause) {
+        throw Object.assign(new Error("cannot access the worktree mutation gate; check A1 data-directory permissions and filesystem availability", { cause }), {
+            code: "worktree-coordination-io",
+        });
+    }
+}

package/dist/foundation/lifecycle/session-claim-lock.d.ts

@@ -0,0 +1,13 @@
+interface ClaimLockOptions {
+    readonly signal?: AbortSignal;
+    readonly lockTimeoutMs?: number;
+}
+/** Inventory is advisory and read-only, including when abandoned metadata needs recovery. */
+export declare function claimMutationPending(directory: string): Promise<boolean>;
+/**
+ * The persistent directory excludes legacy wx-file writers. Only native descriptor authority
+ * permits upgraded mutations; owner.json is disposable evidence, never a liveness oracle.
+ * Never remove the barrier or authority file: doing so would create a second lock universe.
+ */
+export declare function withSessionClaimLock<T>(directory: string, options: ClaimLockOptions, operation: () => Promise<T>): Promise<T>;
+export {};

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

@@ -0,0 +1,131 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readdir, realpath, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { tryAcquireClaimGate } from "./native-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) {
+    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");
+    }
+    catch (error) {
+        return !hasCode(error, "ENOENT");
+    }
+}
+/**
+ * The persistent directory excludes legacy wx-file writers. Only native descriptor authority
+ * permits upgraded mutations; owner.json is disposable evidence, never a liveness oracle.
+ * Never remove the barrier or authority file: doing so would create a second lock universe.
+ */
+export async function withSessionClaimLock(directory, options, operation) {
+    options.signal?.throwIfAborted();
+    let canonical;
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        canonical = await realpath(directory);
+    }
+    catch (cause) {
+        throw failure("worktree-coordination-io", "cannot access the A1 claim directory; check permissions and filesystem availability", cause);
+    }
+    const authority = join(canonical, "mutation.authority");
+    const barrier = join(canonical, "mutation.lock");
+    const deadline = Date.now() + (options.lockTimeoutMs ?? 2_000);
+    let gate;
+    while (gate === undefined) {
+        options.signal?.throwIfAborted();
+        const acquired = tryAcquireClaimGate(authority);
+        if (acquired !== null) {
+            gate = acquired;
+            break;
+        }
+        if (Date.now() >= deadline)
+            throw failure("worktree-claim-busy", "worktree mutation is temporarily busy; automatic runtime registration will retry, and linking can be retried");
+        await delay(Math.min(20, Math.max(1, deadline - Date.now())), undefined, { signal: options.signal });
+    }
+    let operationStarted = false;
+    try {
+        options.signal?.throwIfAborted();
+        try {
+            await mkdir(barrier, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+        }
+        const metadata = await lstat(barrier);
+        if (metadata.isSymbolicLink() || (!metadata.isFile() && !metadata.isDirectory())) {
+            throw failure("worktree-coordination-boundary", "worktree mutation barrier is not a regular file or directory; retain it for inspection");
+        }
+        if (metadata.isFile()) {
+            // Security: a new OS gate proves nothing about an older writer that does not participate in it.
+            // Even a dead legacy PID does not exclude a competing legacy reclaimer's rename race.
+            throw failure("worktree-legacy-recovery-required", "legacy worktree lock prevents safe recovery; stop all older A1 processes, back up only session-worktree-claims/mutation.lock while stopped, then start the updated A1; do not delete sessions or worktree claims");
+        }
+        for (const name of await readdir(barrier)) {
+            const entry = await lstat(join(barrier, name));
+            if (!FILES.has(name) || !entry.isFile() || entry.isSymbolicLink()) {
+                throw failure("worktree-coordination-boundary", "unexpected worktree coordination entry; retain it for inspection rather than deleting the claim store");
+            }
+        }
+        const owner = join(barrier, "owner.json");
+        const pending = join(barrier, "owner.next");
+        if (await exists(owner) || await exists(pending)) {
+            // Security: keep one bounded summary, not an accumulating dump of potentially sensitive corrupt bytes.
+            await publish(barrier, "recovery", { reason: "abandoned-mutation-metadata", recoveredAt: new Date().toISOString() });
+            await rm(owner, { force: true });
+            await rm(pending, { force: true });
+        }
+        await publish(barrier, "owner", { generation: randomUUID(), acquiredAt: new Date().toISOString() });
+        try {
+            options.signal?.throwIfAborted();
+            operationStarted = true;
+            return await operation();
+        }
+        finally {
+            // Concurrency: authority is still held; no successor can publish until after this removal completes.
+            await rm(owner, { force: true });
+        }
+    }
+    catch (error) {
+        if (operationStarted)
+            throw error;
+        if (error instanceof Error && (error.name === "AbortError" || ("code" in error && String(error.code).startsWith("worktree-"))))
+            throw error;
+        throw failure("worktree-coordination-io", "worktree coordination I/O failed; check A1 data-directory permissions and filesystem availability, then retry", error);
+    }
+    finally {
+        gate.release();
+    }
+}
+async function publish(directory, name, value) {
+    const pending = join(directory, `${name}.next`);
+    await rm(pending, { force: true });
+    const handle = await open(pending, "wx", 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(value)}\n`);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await rename(pending, join(directory, `${name}.json`));
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+function hasCode(error, code) { return error instanceof Error && "code" in error && error.code === code; }
+function failure(code, message, cause) { return Object.assign(new Error(message, { cause }), { code }); }

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

@@ -4,6 +4,7 @@ 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";
+import { claimMutationPending, 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";
@@ -11,8 +12,6 @@ const MAX_RECORD_BYTES = 16 * 1024;
 const MAX_HEADER_BYTES = 64 * 1024;
 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;
@@ -444,104 +443,10 @@ async function executeGit(arguments_, cwd, maxBuffer, 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;
-    }
+    return await claimMutationPending(claimStoreRoot(options));
 }
 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);
-    const holder = await lockHolderIdentity(options);
-    let handle;
-    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 {
-        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 {
-        await handle.close().catch(() => undefined);
-        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;
+    return await withSessionClaimLock(claimStoreRoot(options), options, operation);
 }
 async function atomicWrite(path, value) {
     const directory = dirname(path);
@@ -668,12 +573,6 @@ function isStoredClaimRecord(value) {
         && 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;

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

@@ -25,6 +25,11 @@ export interface SpawnContainedOptions {
 export interface ProcessGuardianAddon {
     version(): ProcessGuardianVersion;
     inspectProcessStart(pid: number): string | null;
+    /** Additive capability; older retained addons remain usable for containment, not recovery gates. */
+    tryAcquireProcessGate?(path: string): {
+        readonly acquired: boolean;
+        release(): void;
+    };
     captureTerminalModes(): string;
     restoreTerminalModes(encoded: string): void;
     deliverExitNotice(path: string, encodedModes: string): void;

package/dist/foundation/release/automatic-update.d.ts

@@ -1,7 +1,7 @@
 import { type AvailableRelease, type ReleaseChannel } from "./latest-release.js";
 export declare const AUTOMATIC_UPDATE_STATE_SCHEMA = 1;
 export declare const AUTOMATIC_UPDATE_RETRY_MS: number;
-export declare const AUTOMATIC_UPDATE_ACTIVATION_RETRY_MS: number;
+export declare const AUTOMATIC_UPDATE_ACTIVATION_RETRY_MS = 15000;
 export declare const ACTIVE_RELEASE_FALLBACK_MS = 5000;
 export interface AutomaticUpdateState {
     readonly schema: typeof AUTOMATIC_UPDATE_STATE_SCHEMA;

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

@@ -15,7 +15,7 @@ import { UpdateTransactionStore } from "./update-transaction.js";
 import { runSelfUpdate, UPDATE_ACTIVATION_BLOCKED_EXIT_CODE, UPDATE_ALREADY_RUNNING_EXIT_CODE } from "./update.js";
 export const AUTOMATIC_UPDATE_STATE_SCHEMA = 1;
 export const AUTOMATIC_UPDATE_RETRY_MS = 24 * 60 * 60_000;
-export const AUTOMATIC_UPDATE_ACTIVATION_RETRY_MS = 15 * 60_000;
+export const AUTOMATIC_UPDATE_ACTIVATION_RETRY_MS = 15_000;
 const AUTOMATIC_UPDATE_STATE_FILENAME = "automatic-update.json";
 const MAX_STATE_BYTES = 16_384;
 const OBSERVER_POLL_MS = 250;

package/dist/foundation/release/bootstrap.js

@@ -4,6 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { connect } from "node:net";
 import { resolve } from "node:path";
 import { selectCohortLaunch } from "./cohort-selection.js";
+import { recoverSupervisorEndpoint } from "./endpoint-recovery.js";
 import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
 import { releaseChannelOf } from "./latest-release.js";
 import { CohortStateStore } from "./cohort-state.js";
@@ -22,7 +23,16 @@ import { PRIVATE_ENVIRONMENT, isCurrentLaunchContract, launchContractTarget, rea
 import { assertResidentContinuity, ensureTerminalHost, readResidentTabLaunchSettings, selectResidentHost } from "../resident-tabs/index.js";
 const RELEASE_RESELECTION_MESSAGE = "a1-release-reselection";
 export async function runBootstrap(options) {
-    return await runBootstrapAttempt(options, 1);
+    try {
+        return await runBootstrapAttempt(options, 1);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && typeof error.code === "string" && error.code.startsWith("SUPERVISOR_RECOVERY_")))
+            throw error;
+        // Rationale: actionable recovery failures are a single line, not an uncaught Node stack trace.
+        (options.output ?? process.stderr).write(`${PRODUCT_TEXT.diagnostic(error.message)}\n`);
+        return 1;
+    }
 }
 async function runBootstrapAttempt(options, retriesRemaining) {
     const launchProfileId = options.launchIntent?.profileId ?? "a1";
@@ -122,7 +132,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
         }
         if (endpoint === null || probe === "dead") {
             if (endpoint)
-                await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
+                await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint, endpoint);
             await markStartupPhase(environment, "durable-validation-start");
             const retained = await readRestartCertifiedRelease(active, paths.dataDir).catch(async () => {
                 let verified;
@@ -217,20 +227,12 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     probe = endpoint ? await probeOwnership(endpoint) : "dead";
     let decision = selectCohortLaunch(candidate, state, endpoint, probe);
     if (decision.action === "blocked") {
-        await stateStore.blockPending(decision.reason, endpoint?.ownership.liveInstanceIds ?? []);
-        output.write(`${PRODUCT_TEXT.diagnostic(`startup is blocked to preserve uncertain live ownership: ${decision.reason}`)}\n`);
-        return 1;
-    }
-    if (decision.action === "clean-stale-owner" && endpoint) {
-        const diagnostics = await cleanupProvenIdleOwner(endpoint);
-        await writeFile(resolve(paths.dataDir, `cleanup-${Date.now()}.json`), JSON.stringify(diagnostics, null, 2));
-        if (!diagnostics.terminated)
-            throw new Error(`could not safely clean stale ${PRODUCT_TEXT.displayName} supervisor ${endpoint.pid}`);
-        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
-        decision = selectCohortLaunch(candidate, await stateStore.read(), null, "dead");
+        // Concurrency: reread through the common recovery path rather than fail on an old snapshot.
+        await ensureSupervisor(candidate, environment);
+        return await launchSelected(candidate);
     }
-    else if (endpoint && probe === "dead") {
-        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
+    if (endpoint && probe === "dead") {
+        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint, endpoint);
     }
     if (decision.action === "launch-retained-ui") {
         const retainedRecord = state.releases[decision.releaseId];
@@ -259,7 +261,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
             output.write(`${PRODUCT_TEXT.diagnostic("could not complete bounded idle cohort shutdown; the candidate remains pending.")}\n`);
             return 1;
         }
-        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
+        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint, endpoint);
         await stateStore.activate(candidate.releaseId);
         decision = { action: "activate-candidate", releaseId: candidate.releaseId, releaseRoot: candidate.releaseRoot, reason: "idle cohort released ownership" };
     }
@@ -377,17 +379,15 @@ export async function recordParentCertifiedRelease(release, dataDir) {
 /** Reuse a verified owner, or join the winner if another launch starts the same cohort first. */
 export async function ensureSupervisor(release, environment) {
     const paths = resolveCohortEndpoint(resolveProductPaths(environment), release.releaseId, environment);
-    const metadata = await readEndpointMetadata(paths.endpointMetadataPath);
-    if (metadata) {
-        const probe = await probeOwnership(metadata);
-        if (probe !== "dead") {
-            if (probe === "live-verified" && endpointMatchesRelease(metadata, release))
-                return;
-            throw new Error(PRODUCT_TEXT.diagnostic(`refused duplicate supervisor startup: existing ownership is ${probe}`));
-        }
-    }
-    const startup = await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000, startup);
+    await recoverSupervisorEndpoint({
+        metadataPath: paths.endpointMetadataPath,
+        endpoint: paths.endpoint,
+        matches: metadata => endpointMatchesRelease(metadata, release),
+        startAndWait: async () => {
+            const startup = await startSupervisor(release, environment);
+            await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000, startup);
+        },
+    });
 }
 function endpointMatchesRelease(metadata, release) {
     return metadata.releaseId === release.releaseId && metadata.releaseRoot === release.releaseRoot
@@ -463,7 +463,7 @@ export async function waitForVerifiedEndpoint(path, release, timeoutMs, startup)
     void startup?.childOutcome.then(outcome => { childOutcome = outcome; });
     while (Date.now() < deadline) {
         const metadata = await readEndpointMetadata(path);
-        if (metadata && endpointMatchesRelease(metadata, release) && await probeOwnership(metadata) === "live-verified") {
+        if (metadata && endpointMatchesRelease(metadata, release) && await probeOwnership(metadata, { attempts: 1 }) === "live-verified") {
             if (startup)
                 await rm(startup.resultPath, { force: true });
             return;
@@ -507,18 +507,21 @@ async function activatePendingAfterBlockerExit(candidate, stateStore, paths, env
         return;
     if (!await releaseVerifiedIdleOwner(endpoint, paths.dataDir))
         return;
-    await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
+    await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint, endpoint);
     await stateStore.activate(candidate.releaseId);
     await ensureSupervisor(candidate, environment);
 }
 export async function releaseVerifiedIdleOwner(metadata, dataDir, operations = {}) {
     try {
+        // Protocol: the owner rechecks its boot nonce and live instances before cooperative exit.
+        // A durable idle snapshot alone never authorizes a signal to a still-live process.
+        await requestIdleOwnershipRelease(metadata, metadata.releaseId, 2_000);
         await (operations.waitForExit ?? waitForProcessExit)(metadata.pid, 3_000);
         return true;
     }
     catch {
-        // Security: the authenticated idle-release handshake authorizes bounded cleanup of
-        // this exact boot when a native handle outlives graceful shutdown.
+        // Security: a lingering Windows handle can keep numeric PID probes positive after exit.
+        // Native observation may retire that exact dead boot, but never signals a still-live owner.
         const diagnostics = await (operations.cleanup ?? cleanupProvenIdleOwner)(metadata);
         await writeFile(resolve(dataDir, `cleanup-${Date.now()}.json`), JSON.stringify(diagnostics, null, 2));
         return diagnostics.terminated;

package/dist/foundation/release/cohort-selection.d.ts

@@ -23,12 +23,6 @@ export type CohortLaunchDecision = {
     readonly releaseId: string;
     readonly releaseRoot: string;
     readonly reason: string;
-} | {
-    readonly action: "clean-stale-owner";
-    readonly releaseId: string;
-    readonly releaseRoot: string;
-    readonly reason: string;
-    readonly pid: number;
 } | {
     readonly action: "blocked";
     readonly releaseId: string;

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

@@ -30,20 +30,12 @@ export function selectCohortLaunch(candidate, state, endpoint, probe) {
         };
     }
     if (endpoint && probe === "unresponsive") {
-        if (endpoint.ownership.liveInstanceIds.length > 0 || endpoint.ownership.nonResumableInstanceIds.length > 0) {
-            return {
-                action: "blocked",
-                releaseId: endpoint.releaseId,
-                releaseRoot: endpoint.releaseRoot,
-                reason: "ownership of live launch instances is uncertain; preserving the unresponsive supervisor",
-                pid: endpoint.pid,
-            };
-        }
+        // Security: even an empty persisted list cannot authorize killing an unresponsive process.
         return {
-            action: "clean-stale-owner",
-            releaseId: candidate.releaseId,
-            releaseRoot: candidate.releaseRoot,
-            reason: "unresponsive owner has no recorded live generation and is safe for bounded cleanup",
+            action: "blocked",
+            releaseId: endpoint.releaseId,
+            releaseRoot: endpoint.releaseRoot,
+            reason: "the background service did not respond after automatic recovery; retry shortly",
             pid: endpoint.pid,
         };
     }

package/dist/foundation/release/cohort-state.d.ts

@@ -94,6 +94,8 @@ export interface SupervisorEndpointMetadata {
     readonly endpoint: string;
     readonly pid: number;
     readonly pidStartIdentity: string;
+    /** Exact OS creation token; absent on historical supervisor metadata. */
+    readonly nativeStartIdentity?: string;
     readonly bootNonce: string;
     readonly startedAt: string;
     readonly releaseId: string;

package/dist/foundation/release/endpoint-lock.d.ts

@@ -0,0 +1,2 @@
+/** Serialize endpoint publication and retirement using a lock released by the OS on process death. */
+export declare function withEndpointLock<T>(metadataPath: string, operation: () => Promise<T>): Promise<T>;

package/dist/foundation/release/endpoint-lock.js

@@ -0,0 +1,37 @@
+import { mkdir, realpath } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { acquireSupervisorGate } from "./supervisor-identity.js";
+/** Serialize endpoint publication and retirement using a lock released by the OS on process death. */
+export async function withEndpointLock(metadataPath, operation) {
+    let authority;
+    try {
+        await mkdir(dirname(metadataPath), { recursive: true, mode: 0o700 });
+        authority = join(await realpath(dirname(metadataPath)), `${basename(metadataPath)}.authority`);
+    }
+    catch (cause) {
+        throw Object.assign(new Error("cannot access A1 startup state; check runtime-directory permissions and free disk space", { cause }), { code: "SUPERVISOR_RECOVERY_UNAVAILABLE" });
+    }
+    const deadline = Date.now() + 3_000;
+    for (;;) {
+        let gate;
+        try {
+            gate = acquireSupervisorGate(authority);
+        }
+        catch (cause) {
+            throw Object.assign(new Error("cannot access A1 startup coordination; check installation and runtime-directory permissions", { cause }), { code: "SUPERVISOR_RECOVERY_UNAVAILABLE" });
+        }
+        if (gate.acquired) {
+            try {
+                return await operation();
+            }
+            finally {
+                gate.release();
+            }
+        }
+        gate.release();
+        if (Date.now() >= deadline)
+            throw Object.assign(new Error("another A1 startup is still preparing; retry shortly"), { code: "SUPERVISOR_RECOVERY_BUSY" });
+        await delay(20);
+    }
+}

package/dist/foundation/release/endpoint-recovery.d.ts

@@ -0,0 +1,10 @@
+import type { SupervisorEndpointMetadata } from "./cohort-state.js";
+interface SupervisorRecoveryOptions {
+    readonly metadataPath: string;
+    readonly endpoint: string;
+    readonly matches: (metadata: SupervisorEndpointMetadata) => boolean;
+    readonly startAndWait: () => Promise<void>;
+}
+/** Recover all launch routes identically; a retry never grants permission to kill a live process. */
+export declare function recoverSupervisorEndpoint(options: SupervisorRecoveryOptions): Promise<void>;
+export {};

package/dist/foundation/release/endpoint-recovery.js

@@ -0,0 +1,45 @@
+import { writeFile } from "node:fs/promises";
+import { probeOwnership, readEndpointMetadata, removeEndpointArtifacts } from "./endpoints.js";
+/** Recover all launch routes identically; a retry never grants permission to kill a live process. */
+export async function recoverSupervisorEndpoint(options) {
+    const { metadataPath, endpoint } = options;
+    let recovered = false;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const metadata = await readEndpointMetadata(metadataPath);
+        if (metadata) {
+            const probe = await probeOwnership(metadata);
+            if (probe === "live-verified" && options.matches(metadata)) {
+                if (recovered)
+                    await diagnostic(metadataPath, "recovered", attempt + 1);
+                return;
+            }
+            // Concurrency: another owner may have published while an earlier identity probe was pending.
+            if (JSON.stringify(await readEndpointMetadata(metadataPath)) !== JSON.stringify(metadata))
+                continue;
+            if (probe !== "dead") {
+                await diagnostic(metadataPath, probe, attempt + 1);
+                throw Object.assign(new Error(probe === "unresponsive"
+                    ? "A1's background service is not responding; retry shortly. Your sessions have been preserved."
+                    : "A1's background service identity changed; retry startup. Your sessions have been preserved."), {
+                    code: "SUPERVISOR_RECOVERY_BLOCKED",
+                });
+            }
+            recovered = true;
+            if (!await removeEndpointArtifacts(metadataPath, endpoint, metadata))
+                continue;
+            await diagnostic(metadataPath, "stale-owner-retired", attempt + 1);
+        }
+        // Concurrency: the child takes the same endpoint gate before binding/publication. If another launch wins,
+        // startAndWait joins its authenticated endpoint; it never unlinks that winner's socket.
+        await options.startAndWait();
+        if (recovered)
+            await diagnostic(metadataPath, "recovered", attempt + 1);
+        return;
+    }
+    await diagnostic(metadataPath, "ownership-changing", 3);
+    throw Object.assign(new Error("A1 startup changed repeatedly; retry shortly"), { code: "SUPERVISOR_RECOVERY_BUSY" });
+}
+async function diagnostic(path, reason, attempts) {
+    // Security: one bounded summary per endpoint, no raw metadata, user paths, or session content.
+    await writeFile(`${path}.recovery.json`, JSON.stringify({ reason, attempts, at: new Date().toISOString() }), { mode: 0o600 }).catch(() => undefined);
+}