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

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/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);
+}

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

@@ -1,4 +1,5 @@
 import type { OwnershipProbe } from "./cohort-selection.js";
+import { type ObserveSupervisorProcess } from "./supervisor-identity.js";
 import type { SupervisorEndpointMetadata } from "./cohort-state.js";
 import type { CohortEndpointPaths, ProductPaths } from "../lifecycle/index.js";
 export interface RecordedEndpoint {
@@ -20,5 +21,12 @@ export declare function sweepDeadEndpoints(paths: ProductPaths): Promise<readonl
 /** The releases that an identity-verified live cohort runs from and that must be retained. */
 export declare function liveReleaseIds(paths: ProductPaths): Promise<readonly string[]>;
 export declare function readEndpointMetadata(path: string): Promise<SupervisorEndpointMetadata | null>;
-export declare function probeOwnership(metadata: SupervisorEndpointMetadata): Promise<OwnershipProbe>;
-export declare function removeEndpointArtifacts(metadataPath: string, endpoint: string): Promise<void>;
+export interface OwnershipProbeOptions {
+    readonly observe?: ObserveSupervisorProcess;
+    readonly attempts?: number;
+    readonly timeoutMs?: number;
+}
+/** Reprobe transient failures; only native absence or a replaced generation establishes death. */
+export declare function probeOwnership(metadata: SupervisorEndpointMetadata, options?: OwnershipProbeOptions): Promise<OwnershipProbe>;
+/** Retire only a still-dead exact publication. Socket removal belongs to the gated listener. */
+export declare function removeEndpointArtifacts(metadataPath: string, endpoint: string, expected: SupervisorEndpointMetadata): Promise<boolean>;

package/dist/foundation/release/endpoints.js

@@ -1,10 +1,10 @@
 import { readdir, readFile, rm } from "node:fs/promises";
 import { connect } from "node:net";
-import { platform } from "node:os";
 import { resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
-import { processIsAlive } from "./process-cleanup.js";
+import { supervisorProcessState } from "./supervisor-identity.js";
+import { withEndpointLock } from "./endpoint-lock.js";
 /**
  * Every endpoint recorded under this runtime directory: one per cohort, plus the single
  * endpoint published by releases that predate cohort-scoped identity. More than one can be
@@ -12,9 +12,12 @@ import { processIsAlive } from "./process-cleanup.js";
  */
 export async function listRecordedEndpoints(paths) {
     const recorded = [];
-    const legacy = await readEndpointMetadata(paths.endpointMetadataPath);
+    // Compatibility: a cohort listener passes its scoped paths here; legacy discovery still
+    // names the runtime directory's fixed metadata path, not that listener's own record.
+    const legacyPath = resolve(paths.runtimeDir, PRODUCT_IDENTITY.endpoint.metadataFilename);
+    const legacy = await readEndpointMetadata(legacyPath);
     if (legacy) {
-        recorded.push({ metadata: legacy, paths: { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath } });
+        recorded.push({ metadata: legacy, paths: { endpoint: legacy.endpoint, endpointMetadataPath: legacyPath } });
     }
     const names = await readdir(paths.endpointsDir).catch(() => []);
     for (const name of names) {
@@ -35,10 +38,11 @@ export async function listRecordedEndpoints(paths) {
 export async function sweepDeadEndpoints(paths) {
     const swept = [];
     for (const recorded of await listRecordedEndpoints(paths)) {
-        if (processIsAlive(recorded.metadata.pid))
+        if (await supervisorProcessState(recorded.metadata) !== "gone")
             continue;
-        await removeEndpointArtifacts(recorded.paths.endpointMetadataPath, recorded.paths.endpoint);
-        swept.push(recorded.metadata.releaseId);
+        if (await removeEndpointArtifacts(recorded.paths.endpointMetadataPath, recorded.paths.endpoint, recorded.metadata)) {
+            swept.push(recorded.metadata.releaseId);
+        }
     }
     return swept;
 }
@@ -82,18 +86,24 @@ export async function readEndpointMetadata(path) {
         return null;
     }
 }
-export async function probeOwnership(metadata) {
-    if (!processIsAlive(metadata.pid))
-        return "dead";
-    const identity = await requestIdentity(metadata.endpoint, 500);
-    if (!identity)
-        return "unresponsive";
-    return identity.supervisorId === metadata.supervisorId
-        && identity.bootNonce === metadata.bootNonce
-        && identity.pidStartIdentity === metadata.pidStartIdentity
-        && identity.releaseId === metadata.releaseId
-        ? "live-verified"
-        : "identity-mismatch";
+/** Reprobe transient failures; only native absence or a replaced generation establishes death. */
+export async function probeOwnership(metadata, options = {}) {
+    const attempts = options.attempts ?? 3;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const identity = await requestIdentity(metadata.endpoint, options.timeoutMs ?? 500);
+        if (identity) {
+            return identity.supervisorId === metadata.supervisorId
+                && identity.bootNonce === metadata.bootNonce
+                && identity.pidStartIdentity === metadata.pidStartIdentity
+                && identity.releaseId === metadata.releaseId
+                ? "live-verified" : "identity-mismatch";
+        }
+        if (await supervisorProcessState(metadata, options.observe) === "gone")
+            return "dead";
+        if (attempt + 1 < attempts)
+            await new Promise(resolvePromise => setTimeout(resolvePromise, 50));
+    }
+    return "unresponsive";
 }
 async function requestIdentity(endpoint, timeoutMs) {
     return await new Promise(resolvePromise => {
@@ -104,6 +114,7 @@ async function requestIdentity(endpoint, timeoutMs) {
             if (settled)
                 return;
             settled = true;
+            clearTimeout(timer);
             socket.destroy();
             resolvePromise(value);
         };
@@ -121,14 +132,21 @@ async function requestIdentity(endpoint, timeoutMs) {
                 finish(null);
             }
         });
-        setTimeout(() => finish(null), timeoutMs).unref();
+        const timer = setTimeout(() => finish(null), timeoutMs);
     });
 }
 function isStringArray(value) {
     return Array.isArray(value) && value.every(item => typeof item === "string" && item.length > 0);
 }
-export async function removeEndpointArtifacts(metadataPath, endpoint) {
-    await rm(metadataPath, { force: true });
-    if (platform() !== "win32")
-        await rm(endpoint, { force: true });
+/** Retire only a still-dead exact publication. Socket removal belongs to the gated listener. */
+export async function removeEndpointArtifacts(metadataPath, endpoint, expected) {
+    return await withEndpointLock(metadataPath, async () => {
+        const current = await readEndpointMetadata(metadataPath);
+        if (!current || current.endpoint !== endpoint || JSON.stringify(current) !== JSON.stringify(expected))
+            return false;
+        if (await supervisorProcessState(current) !== "gone" || await probeOwnership(current, { attempts: 1 }) !== "dead")
+            return false;
+        await rm(metadataPath, { force: true });
+        return true;
+    });
 }

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

@@ -8,6 +8,8 @@ export type { ActiveReleaseTransactionReference, CohortState, EndpointOwnership,
 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";
 export { listRecordedEndpoints, liveReleaseIds, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, sweepDeadEndpoints } from "./endpoints.js";
+export { currentSupervisorStartIdentity, observeSupervisorProcess, supervisorProcessState } from "./supervisor-identity.js";
+export { withEndpointLock } from "./endpoint-lock.js";
 export type { RecordedEndpoint } from "./endpoints.js";
 export { cleanupProvenIdleOwner, cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
 export type { CleanupDiagnostics } from "./process-cleanup.js";

package/dist/foundation/release/index.js

@@ -4,6 +4,8 @@ export { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
 export { CohortStateStore, RELEASE_COHORT_SCHEMA, emptyState, planProtectedReleases } from "./cohort-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 { listRecordedEndpoints, liveReleaseIds, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, sweepDeadEndpoints } from "./endpoints.js";
+export { currentSupervisorStartIdentity, observeSupervisorProcess, supervisorProcessState } from "./supervisor-identity.js";
+export { withEndpointLock } from "./endpoint-lock.js";
 export { cleanupProvenIdleOwner, cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
 export { PRODUCT_PACKAGE_NAME, createReleaseIdentity, deriveReleaseIdentity, digestManifestFiles, discoverReleasePayload, packageRootFromModule, releaseFileIdentity, resolveWithin, } from "./release.js";
 export { collectRelease, prepareReleaseCleanup, runBoundedReleaseCleanup, runReleaseCleanupWorker, scheduleReleaseCleanup } from "./release-gc.js";

package/dist/foundation/release/process-cleanup.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { supervisorProcessState } from "./supervisor-identity.js";
 export function processIsAlive(pid) {
     if (!Number.isSafeInteger(pid) || pid <= 0)
         return false;
@@ -15,17 +16,26 @@ export async function cleanupProvenIdleOwner(metadata, graceMs = 1_500) {
 }
 export async function cleanupVerifiedOwner(metadata, options = {}) {
     const graceMs = options.graceMs ?? 1_500;
-    if (!options.allowLiveInstances && (metadata.ownership.liveInstanceIds.length > 0 || metadata.ownership.nonResumableInstanceIds.length > 0)) {
+    if (!options.allowLiveInstances && (metadata.ownership.liveInstanceIds.length > 0 || metadata.ownership.nonResumableInstanceIds.length > 0 || metadata.ownership.uncertainInstanceIds.length > 0)) {
         throw new Error("refusing to terminate an owner with recorded live generations");
     }
     const started = Date.now();
     const attempted = [];
-    if (!processIsAlive(metadata.pid))
+    const state = await supervisorProcessState(metadata);
+    if (state === "gone")
         return { pid: metadata.pid, attempted: ["owner-already-dead"], terminated: true, elapsedMs: Date.now() - started };
+    // Security: ordinary recovery never signals a live owner, even with an empty durable list.
+    // Explicit update cleanup also needs the exact native generation, not merely an old handshake.
+    if (!options.allowLiveInstances || state !== "same") {
+        return { pid: metadata.pid, attempted: ["live-owner-preserved"], terminated: false, elapsedMs: Date.now() - started };
+    }
     attempted.push("graceful-termination");
     await terminate(metadata.pid, false);
     if (await waitUntilDead(metadata.pid, graceMs))
         return { pid: metadata.pid, attempted, terminated: true, elapsedMs: Date.now() - started };
+    if (await supervisorProcessState(metadata) !== "same") {
+        return { pid: metadata.pid, attempted, terminated: await supervisorProcessState(metadata) === "gone", elapsedMs: Date.now() - started };
+    }
     attempted.push("forced-process-tree-termination");
     await terminate(metadata.pid, true);
     const terminated = await waitUntilDead(metadata.pid, graceMs);

package/dist/foundation/release/supervisor-identity.d.ts

@@ -0,0 +1,15 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { SupervisorEndpointMetadata } from "./cohort-state.js";
+export type SupervisorProcessState = "same" | "gone" | "unknown";
+export type ObserveSupervisorProcess = (pid: number) => Promise<NativeProcessIdentity | null>;
+/** Inspection code comes from this runtime, never from a path in a stale endpoint record. */
+export declare function observeSupervisorProcess(pid: number): Promise<NativeProcessIdentity | null>;
+/** New supervisors use a native creation token as their opaque handshake identity as well. */
+export declare function currentSupervisorStartIdentity(): string;
+/** The current runtime also owns the OS gate ABI; metadata cannot choose a different addon. */
+export declare function acquireSupervisorGate(path: string): {
+    readonly acquired: boolean;
+    release(): void;
+};
+/** A failed inspection is uncertainty, never permission to erase a possibly live owner. */
+export declare function supervisorProcessState(metadata: SupervisorEndpointMetadata, observe?: ObserveSupervisorProcess): Promise<SupervisorProcessState>;

package/dist/foundation/release/supervisor-identity.js

@@ -0,0 +1,63 @@
+import { fileURLToPath } from "node:url";
+import { createNativeProcessInspector, loadProcessGuardianAddon, resolveProcessGuardianPath } from "../process-containment/index.js";
+const ownRoot = fileURLToPath(new URL("../../../", import.meta.url));
+/** Inspection code comes from this runtime, never from a path in a stale endpoint record. */
+export async function observeSupervisorProcess(pid) {
+    return await (await createNativeProcessInspector(process.env, process.platform, ownRoot)).observe(pid);
+}
+/** New supervisors use a native creation token as their opaque handshake identity as well. */
+export function currentSupervisorStartIdentity() {
+    try {
+        const token = loadProcessGuardianAddon(resolveProcessGuardianPath(ownRoot, process.env)).inspectProcessStart(process.pid);
+        if (!validNativeToken(token))
+            throw new Error("native process identity is unavailable");
+        return token;
+    }
+    catch (cause) {
+        throw Object.assign(new Error("cannot verify A1's background service process; check installation and process-inspection permissions", { cause }), { code: "SUPERVISOR_RECOVERY_UNAVAILABLE" });
+    }
+}
+/** The current runtime also owns the OS gate ABI; metadata cannot choose a different addon. */
+export function acquireSupervisorGate(path) {
+    const addon = loadProcessGuardianAddon(resolveProcessGuardianPath(ownRoot, process.env));
+    if (!addon.tryAcquireProcessGate)
+        throw new Error("this installation lacks startup recovery support; update or repair A1");
+    return addon.tryAcquireProcessGate(path);
+}
+/** A failed inspection is uncertainty, never permission to erase a possibly live owner. */
+export async function supervisorProcessState(metadata, observe = observeSupervisorProcess) {
+    let identity;
+    try {
+        identity = await observe(metadata.pid);
+    }
+    catch {
+        return "unknown";
+    }
+    if (identity === null)
+        return "gone";
+    if (identity.pid !== metadata.pid)
+        return "unknown";
+    if (metadata.nativeStartIdentity !== undefined) {
+        // Compatibility: only compare tokens of the same native format, not an old Node timestamp.
+        if (!validNativeToken(metadata.nativeStartIdentity) || !validNativeToken(identity.startIdentity)
+            || identity.startIdentity.split(":")[0] !== metadata.nativeStartIdentity.split(":")[0])
+            return "unknown";
+        return identity.startIdentity === metadata.nativeStartIdentity ? "same" : "gone";
+    }
+    // Compatibility: legacy publication happened after process creation. A native creation time
+    // strictly later than that publication (with a one-second clock margin) disproves ownership;
+    // a near timestamp is NOT proof of ownership. Linux tick-only tokens cannot prove this.
+    const published = Date.parse(metadata.startedAt);
+    const created = nativeCreationTime(identity.startIdentity);
+    return Number.isFinite(published) && created !== null && created > published + 1_000 ? "gone" : "unknown";
+}
+function validNativeToken(value) {
+    return typeof value === "string" && /^(?:windows-filetime:\d{1,20}|linux-proc-start:\d{1,20}|darwin-proc-start:\d{1,20}:\d{1,6})$/.test(value);
+}
+function nativeCreationTime(identity) {
+    const windows = /^windows-filetime:(\d+)$/.exec(identity);
+    if (windows)
+        return Number(BigInt(windows[1]) / 10000n - 11644473600000n);
+    const darwin = /^darwin-proc-start:(\d+):(\d+)$/.exec(identity);
+    return darwin ? Number(darwin[1]) * 1_000 + Number(darwin[2]) / 1_000 : null;
+}

package/dist/foundation/release/update.js

@@ -155,7 +155,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             }
             const plan = planUpdateOwnership(ownership, await canonicalImmutableRoot(paths.dataDir, endpoint.releaseRoot));
             if (plan === "clean-dead-record") {
-                await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint);
+                await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint, endpoint);
                 return { priorActiveVersion };
             }
             // Rationale: leaving sessions alone is the expected outcome, and saying so mid-update tears
@@ -182,7 +182,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                         throw new Error(`verified ${PRODUCT_TEXT.displayName} owner ${endpoint.pid} did not terminate`);
                 });
             }
-            await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint);
+            await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint, endpoint);
             return { priorActiveVersion };
         },
         async verifyPackageUnlocked(packageRoot) {

package/dist/foundation/storage/control-store.d.ts

@@ -5,14 +5,16 @@ export declare class ControlStore {
     #private;
     readonly database: DatabaseSync;
     readonly bootNonce: string | null;
-    constructor(path: string, bootNonce?: string | null);
+    constructor(path: string, bootNonce?: string | null, options?: {
+        readonly reconcileOnOpen?: boolean;
+    });
     migrate(): void;
     createLaunchInstance(instance: LaunchInstance): void;
     activateLaunchInstance(instanceId: LaunchInstanceId, ownerClientId: string, rootIdentity: NativeProcessIdentity, containmentIdentity: ProcessContainmentIdentity, activatedAt: string): boolean;
     beginLaunchInstanceStop(instanceId: LaunchInstanceId, ownerClientId: string, stoppingAt: string): boolean;
     completeLaunchInstance(instanceId: LaunchInstanceId, ownerClientId: string, terminalState: "completed" | "interrupted", outcome: LaunchInstanceOutcome, completedAt: string): boolean;
-    loadActiveLaunchInstances(): LaunchInstance[];
+    loadActiveLaunchInstances(bootNonce?: string): LaunchInstance[];
     loadLaunchInstance(instanceId: LaunchInstanceId): LaunchInstance | null;
-    reconcilePriorBootLaunchInstances(bootNonce: string, reconciledAt?: string): number;
+    reconcilePriorBootLaunchInstances(bootNonce: string, reconciledAt?: string, protectedBoots?: readonly string[]): number;
     close(): void;
 }

package/dist/foundation/storage/control-store.js

@@ -30,7 +30,7 @@ const LAUNCH_INSTANCES_TABLE = `
 export class ControlStore {
     database;
     bootNonce;
-    constructor(path, bootNonce = null) {
+    constructor(path, bootNonce = null, options = {}) {
         this.bootNonce = bootNonce;
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         this.database = new DatabaseSync(path);
@@ -38,7 +38,7 @@ export class ControlStore {
             this.database.exec("PRAGMA journal_mode = WAL");
             this.database.exec("PRAGMA foreign_keys = ON");
             this.migrate();
-            if (bootNonce !== null)
+            if (bootNonce !== null && options.reconcileOnOpen !== false)
                 this.reconcilePriorBootLaunchInstances(bootNonce);
         }
         catch (error) {
@@ -284,16 +284,16 @@ export class ControlStore {
             .run(terminalState, completedAt, JSON.stringify(outcome), instanceId, ownerClientId, this.bootNonce);
         return Number(result.changes) === 1;
     }
-    loadActiveLaunchInstances() {
+    loadActiveLaunchInstances(bootNonce) {
         return this.database.prepare(`SELECT * FROM launch_instances
-      WHERE state IN ('requested', 'active', 'stopping') ORDER BY created_at, id`).all()
+      WHERE state IN ('requested', 'active', 'stopping') ${bootNonce === undefined ? "" : "AND owner_boot_nonce = ?"} ORDER BY created_at, id`).all(...(bootNonce === undefined ? [] : [bootNonce]))
             .map(launchInstanceFromRow);
     }
     loadLaunchInstance(instanceId) {
         const row = this.database.prepare("SELECT * FROM launch_instances WHERE id = ?").get(instanceId);
         return row ? launchInstanceFromRow(row) : null;
     }
-    reconcilePriorBootLaunchInstances(bootNonce, reconciledAt = new Date().toISOString()) {
+    reconcilePriorBootLaunchInstances(bootNonce, reconciledAt = new Date().toISOString(), protectedBoots = []) {
         const outcome = {
             kind: "interrupted",
             reason: "supervisor-disconnect",
@@ -301,8 +301,9 @@ export class ControlStore {
         };
         const result = this.database.prepare(`UPDATE launch_instances
       SET state = 'interrupted', completed_at = ?, outcome_json = ?
-      WHERE state IN ('requested', 'active', 'stopping') AND owner_boot_nonce <> ?`)
-            .run(reconciledAt, JSON.stringify(outcome), bootNonce);
+      WHERE state IN ('requested', 'active', 'stopping') AND owner_boot_nonce <> ?
+      ${protectedBoots.length === 0 ? "" : `AND owner_boot_nonce NOT IN (${protectedBoots.map(() => "?").join(",")})`}`)
+            .run(reconciledAt, JSON.stringify(outcome), bootNonce, ...protectedBoots);
         return Number(result.changes);
     }
     close() {

package/dist/foundation/supervision/main.js

@@ -36,7 +36,9 @@ export async function runSupervisor(arguments_ = []) {
         paths = { ...productPaths, ...resolveCohortEndpoint(productPaths, release.releaseId) };
         stage = "storage";
         const bootNonce = randomUUID();
-        const store = new ControlStore(paths.databasePath, bootNonce);
+        // Concurrency: opening SQLite does not establish endpoint authority. The winning listener
+        // reconciles old boots only after binding; losing startup attempts must not mutate live rows.
+        const store = new ControlStore(paths.databasePath, bootNonce, { reconcileOnOpen: false });
         const cohortState = new CohortStateStore(paths.dataDir);
         server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => {
             const transaction = await new UpdateTransactionStore(paths.dataDir).read();

package/dist/foundation/supervision/server.js

@@ -5,7 +5,7 @@ import { platform } from "node:os";
 import { dirname } from "node:path";
 import { assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
 import { encodeFrame, isCommandMessage, isControlHello, LineFrameDecoder, localControlHello, MAX_CONTROL_FRAME_BYTES, negotiateControlFeatures } from "../protocol/index.js";
-import { processIsAlive } from "../release/index.js";
+import { listRecordedEndpoints, readEndpointMetadata, supervisorProcessState, currentSupervisorStartIdentity, withEndpointLock, processIsAlive } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveProductPaths } from "./paths.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
@@ -43,7 +43,7 @@ export async function commitEndpointMetadata(path, source, operations = {}) {
 export class SupervisorServer {
     id = randomUUID();
     bootNonce;
-    pidStartIdentity = `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
+    pidStartIdentity = currentSupervisorStartIdentity();
     startedAt = new Date().toISOString();
     paths;
     #server = null;
@@ -84,7 +84,7 @@ export class SupervisorServer {
         this.supersededPollMs = supersededPollMs;
         this.bootNonce = bootNonce;
         this.paths = paths;
-        for (const instance of store.loadActiveLaunchInstances())
+        for (const instance of store.loadActiveLaunchInstances(bootNonce))
             this.#instances.set(instance.id, instance);
     }
     snapshot() {
@@ -98,41 +98,60 @@ export class SupervisorServer {
         };
     }
     async listen() {
-        if (this.#server)
-            throw new Error("supervisor is already listening");
-        await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
-        await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
-        if (platform() !== "win32") {
-            if (this.paths.endpointDirectory)
-                await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
-            const existing = await lstat(this.paths.endpoint).catch(error => {
-                if (error.code === "ENOENT")
-                    return null;
-                throw error;
-            });
-            if (existing) {
-                if (await endpointIsLive(this.paths.endpoint)) {
-                    throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`)), { code: "EADDRINUSE" });
+        await withEndpointLock(this.paths.endpointMetadataPath, async () => {
+            if (this.#server)
+                throw new Error("supervisor is already listening");
+            await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
+            await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
+            const recorded = await readEndpointMetadata(this.paths.endpointMetadataPath);
+            if (recorded && await supervisorProcessState(recorded) !== "gone") {
+                throw Object.assign(new Error("another supervisor still owns this endpoint"), { code: "EADDRINUSE" });
+            }
+            if (platform() !== "win32") {
+                if (this.paths.endpointDirectory)
+                    await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
+                const existing = await lstat(this.paths.endpoint).catch(error => {
+                    if (error.code === "ENOENT")
+                        return null;
+                    throw error;
+                });
+                if (existing) {
+                    if (await endpointIsLive(this.paths.endpoint)) {
+                        throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`)), { code: "EADDRINUSE" });
+                    }
+                    await rm(this.paths.endpoint, { force: true });
                 }
-                await rm(this.paths.endpoint, { force: true });
             }
-        }
-        const server = createServer(socket => this.#attach(socket));
-        this.#server = server;
-        await new Promise((resolve, reject) => {
-            server.once("error", reject);
-            server.listen(this.paths.endpoint, () => {
-                this.#ownsEndpoint = true;
-                server.off("error", reject);
-                resolve();
+            const server = createServer(socket => this.#attach(socket));
+            this.#server = server;
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(this.paths.endpoint, () => {
+                    this.#ownsEndpoint = true;
+                    server.off("error", reject);
+                    resolve();
+                });
+            });
+            // Concurrency: only the bound winner may reconcile shared control data. Other cohort boots
+            // remain protected even when temporarily unresponsive; their instances never become ours.
+            await withEndpointLock(this.paths.databasePath, async () => {
+                // Concurrency: all cohorts sharing SQLite serialize boot reconciliation plus publication, so a new
+                // cohort cannot insert instances between another cohort's inventory and stale-row update.
+                const protectedBoots = [];
+                for (const other of await listRecordedEndpoints(this.paths)) {
+                    if (other.paths.endpointMetadataPath !== this.paths.endpointMetadataPath
+                        && await supervisorProcessState(other.metadata) !== "gone")
+                        protectedBoots.push(other.metadata.bootNonce);
+                }
+                this.store.reconcilePriorBootLaunchInstances(this.bootNonce, new Date().toISOString(), protectedBoots);
+                await this.#writeEndpointMetadata();
             });
+            if (this.readActiveReleaseId) {
+                const poll = setInterval(() => void this.#refreshCohortRole(), this.supersededPollMs);
+                poll.unref();
+                this.#supersededPoll = poll;
+            }
         });
-        await this.#writeEndpointMetadata();
-        if (this.readActiveReleaseId) {
-            const poll = setInterval(() => void this.#refreshCohortRole(), this.supersededPollMs);
-            poll.unref();
-            this.#supersededPoll = poll;
-        }
     }
     // Invariant: superseding a cohort never interrupts its held instances; it retires only when empty.
     async #refreshCohortRole() {
@@ -167,27 +186,29 @@ export class SupervisorServer {
         this.#supersededPoll = null;
         for (const client of this.#clients)
             client.destroy();
-        try {
-            await this.#metadataWrites.catch(() => undefined);
-            if (this.#ownsEndpoint) {
-                // Concurrency: remove only our publication, before releasing the listening endpoint.
-                // A contender that failed to bind must never erase the successful owner's discovery file.
-                const metadata = await readFile(this.paths.endpointMetadataPath, "utf8").then(source => JSON.parse(source)).catch(() => null);
-                if (metadata?.supervisorId === this.id && metadata.bootNonce === this.bootNonce) {
-                    await rm(this.paths.endpointMetadataPath, { force: true });
+        await withEndpointLock(this.paths.endpointMetadataPath, async () => {
+            try {
+                await this.#metadataWrites.catch(() => undefined);
+                if (this.#ownsEndpoint) {
+                    // Concurrency: remove only our publication, before releasing the listening endpoint.
+                    // A contender that failed to bind must never erase the successful owner's discovery file.
+                    const metadata = await readFile(this.paths.endpointMetadataPath, "utf8").then(source => JSON.parse(source)).catch(() => null);
+                    if (metadata?.supervisorId === this.id && metadata.bootNonce === this.bootNonce) {
+                        await rm(this.paths.endpointMetadataPath, { force: true });
+                    }
+                    // Platform: Node unlinks its Unix socket when the server closes; unlinking it early would
+                    // let a replacement bind before the old server finishes releasing that path.
                 }
-                // Platform: Node unlinks its Unix socket when the server closes; unlinking it early would
-                // let a replacement bind before the old server finishes releasing that path.
             }
-        }
-        finally {
-            // Platform: a metadata sharing error must not leave a bound but undiscoverable listener.
-            if (this.#server)
-                await new Promise(resolve => this.#server?.close(() => resolve()));
-            this.#server = null;
-            this.#ownsEndpoint = false;
-            this.store.close();
-        }
+            finally {
+                // Platform: a metadata sharing error must not leave a bound but undiscoverable listener.
+                if (this.#server)
+                    await new Promise(resolve => this.#server?.close(() => resolve()));
+                this.#server = null;
+                this.#ownsEndpoint = false;
+                this.store.close();
+            }
+        });
     }
     async closeForReleaseReplacement(stopAgents) {
         await this.close(stopAgents);
@@ -518,6 +539,7 @@ export class SupervisorServer {
             supervisorId: this.id,
             pid: process.pid,
             pidStartIdentity: this.pidStartIdentity,
+            nativeStartIdentity: this.pidStartIdentity,
             bootNonce: this.bootNonce,
             endpoint: this.paths.endpoint,
             databasePath: this.paths.databasePath,

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

@@ -7,11 +7,11 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-11-06T06:57:04.765Z",
+  "builtAt": "2026-11-06T08:23:55.616Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "5a314f46b164ef006957528ea7b1743e104895449a1b5a9e3c8b5adbf7122d33",
-    "size": 456080
+    "sha256": "9ab579426034c752ef8ed53a789566f5b7cfe102149d30c28f4bdb60e73107c5",
+    "size": 456272
   },
   "provenance": {
     "language": "Rust",

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

@@ -9,7 +9,7 @@
   "architecture": "arm64",
   "target": "aarch64-apple-darwin",
   "capability": "supported",
-  "builtAt": "2026-11-06T07:00:26.658Z",
+  "builtAt": "2026-11-06T08:27:51.656Z",
   "artifact": {
     "filename": "terminal-host.node",
     "sha256": "b2548f95b9660b11b6d28fb4b35f254cde9940d9d19233517bb70507ffcf76ab",

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

@@ -7,11 +7,11 @@
   "platform": "darwin",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-11-06T06:57:12.911Z",
+  "builtAt": "2026-11-06T08:24:02.357Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "b4d66ed5920c3b2d4ac1cb658fe87549cdad2f81948dbe8cfa698ff6d87162e1",
-    "size": 444248
+    "sha256": "65f3a469a6faa9b578bc095e7559012775ee85e5b93cbc9451c62604f769146e",
+    "size": 452648
   },
   "provenance": {
     "language": "Rust",

package/dist/native/darwin-x64/terminal-host.manifest.json

@@ -9,7 +9,7 @@
   "architecture": "x64",
   "target": "x86_64-apple-darwin",
   "capability": "supported",
-  "builtAt": "2026-11-06T07:03:27.415Z",
+  "builtAt": "2026-11-06T08:31:58.733Z",
   "artifact": {
     "filename": "terminal-host.node",
     "sha256": "cd1103472889d53e2e039cf7673b2fe6e9e0937234591b1202234d0c1c357d2a",

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

@@ -7,11 +7,11 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-11-06T06:56:45.470Z",
+  "builtAt": "2026-11-06T08:23:51.242Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "18442075f91a02d22071548c0a2c882c69ee04b2e48e0b1130f23a86c5b258ca",
-    "size": 491536
+    "sha256": "64232d4c827bb7f69c14612986f9b6780a0593d8842cd039a411b6bfe29cd5da",
+    "size": 500264
   },
   "provenance": {
     "language": "Rust",

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

@@ -9,7 +9,7 @@
   "architecture": "x64",
   "target": "x86_64-unknown-linux-gnu",
   "capability": "supported",
-  "builtAt": "2026-11-06T06:59:02.808Z",
+  "builtAt": "2026-11-06T08:26:29.024Z",
   "artifact": {
     "filename": "terminal-host.node",
     "sha256": "f5abfe9464780c9acdf85dfbf8a0f194bf0355188ab23feaa09cb7df84363088",

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

@@ -7,11 +7,11 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-11-06T06:57:32.942Z",
+  "builtAt": "2026-11-06T08:24:41.351Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "eb4519e51e5c77a740b9c290e28def2293363675b103a21388532fa73d208893",
-    "size": 402432
+    "sha256": "dab6b6aed5ab24435d7814fc5099f26707486ee187551ff1dfd939679682f32b",
+    "size": 414208
   },
   "provenance": {
     "language": "Rust",

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

@@ -9,10 +9,10 @@
   "architecture": "x64",
   "target": "x86_64-pc-windows-msvc",
   "capability": "supported",
-  "builtAt": "2026-11-06T06:59:37.419Z",
+  "builtAt": "2026-11-06T08:29:00.280Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "148523e2ee5648749b4c5b84518e3d120aacf247cdf8620c3fa205df5c960dff",
+    "sha256": "00dc90f70d76ff36418a301d36dd406d143a6bf1da6b56e24ae5341b4e0c7d8e",
     "size": 7131136
   },
   "entry": {

package/docs/architecture/project-structure.md

@@ -47,6 +47,8 @@ Three layer boundaries hold regardless of the DAG: `src/contracts/*` import noth
 
 `src/cli` contains command policy but delegates runtime work. `src/composition` is the concrete dependency-injection boundary: it may know both neutral contracts and Pi implementations, while product features receive vendor-neutral ports. Foundation modules never import product features. Pi package knowledge remains inside the Pi adapter owners.
 
+Release-owned endpoint observation and recovery coordinate with supervision-owned publication and storage-owned boot reconciliation through the process guardian's OS-released gates; see [startup recovery](../launch-recovery.md) for the identity, concurrency, and diagnostic boundaries.
+
 Shared code moves to foundation only when it is product-agnostic, has a precise contract, and has more than one real consumer. Do not create `core`, `common`, `utils`, or `misc` dumping grounds.
 
 ## Feature ownership

package/docs/launch-recovery.md

@@ -0,0 +1,23 @@
+# Startup recovery after process termination
+
+A1 reconciles recoverable runtime ownership automatically when the user starts it again after a process crash or forced termination. Users should not need to find PIDs, delete session or control databases, restart a supervisor, or reboot to clear a stale record.
+
+## Recovery boundary
+
+Supervisor metadata carries an additive native process-creation token. Endpoint handshakes still use the existing supervisor, boot, release, and opaque start-identity fields for compatibility; new supervisors use their native token in that start field as well. A failed probe is retried; native process inspection distinguishes a terminated process object or reused PID from the recorded owner. Older records remain readable: an absent process is reclaimable, while a live legacy PID is not treated as dead merely because its timestamp format differs. Windows and macOS native creation times strictly later than a legacy publication, with a one-second margin, can disprove that recorded ownership. Tick-only Linux legacy evidence remains conservative until absence or a matching handshake establishes the outcome.
+
+Endpoint retirement requires the same publication and a fresh dead-owner observation under a native file-descriptor gate. The gate is never deleted; the OS releases its lock on exit, including forced exit. Supervisor binding, Unix stale-socket removal, metadata publication, and closure use that gate. Losing startups cannot delete the winner's endpoint. A separate shared-database gate serializes boot reconciliation and publication across cohorts. Only the bound winner reconciles old rows, and recorded surviving cohort boots remain protected.
+
+Successful recovery is silent and continues the original profile, launch mode, and session selection. Saved sessions are not deleted or rewritten by endpoint recovery. Resident holders and their session-writer locks retain their independent ownership; restarting a supervisor is not permission to stop a resident tab or create a second session writer.
+
+## Exceptional failures
+
+An uninspectable or genuinely unresponsive live owner is preserved after bounded retries. Empty saved instance lists are not authority to terminate it. The command returns a short recovery message instead of an uncaught stack or the old internal uncertain-live-ownership paragraph. Missing native recovery support or inaccessible runtime storage remains an installation or permission failure, not proof that an owner is dead.
+
+A recovery attempt may replace one bounded `<endpoint-metadata>.recovery.json` summary containing only a reason, attempt count, and timestamp. It is diagnostic only, contains no session data or credentials, and never grants cleanup authority. The `.authority` gate files are also not user cleanup targets.
+
+This restores launch availability, not killed process memory. Killing every Node process also kills the terminal-restoration watcher; no alternative executable is started to evade that limitation. Real OS permission failures, damaged installations, and persistently live unresponsive services cannot be converted into safe success by ignoring ownership.
+
+## Regression boundaries
+
+The focused fixtures use isolated runtime/data roots and recorded fixture process identities. They cover supervisor, guardian, root-runtime, recovery-gate, PID-reuse, concurrent-startup, and Windows all-recorded-Node loss, plus native resident server/holder/tab loss in the resident lane. They never terminate processes by image name. Another managed runtime, a separate cohort, saved session bytes, and an unrelated sentinel process establish the preservation boundaries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.2.7-dev.1244",
+  "version": "0.2.7-dev.1245",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -126,7 +126,7 @@
     "@mariozechner/clipboard": "^0.3.9"
   },
   "publication": {
-    "source": "111a66b7e3174dcf876416a0b35f09960526ee93",
-    "pullRequest": 868
+    "source": "fc4a2588e22b6d90034465d80d7923c8fede91d8",
+    "pullRequest": 870
   }
 }