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

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";
@@ -26,7 +28,7 @@ export type { ProcessRequest, ProcessResult, SelfUpdateOptions, UpdateActivation
 export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, UpdateActivationBlockedError, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
 export type { UpdateActivationCallbacks, UpdateActivationEvent, UpdateActivationRequest } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
-export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, npmPrefixForGlobalRoot, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
+export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, npmPrefixForGlobalRoot, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, resolveNpmCli, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
 export type { ProtectedPackageReplacementOptions, ProtectedPackageReplacementResult, UpdateRecoveryCapsule, UpdateRecoveryResult } from "./update-recovery.js";
 export { UPDATE_JOURNAL_SCHEMA, UpdateTransactionStore } from "./update-transaction.js";
 export type { UpdateRecoveryState, UpdateTransaction, UpdateTransactionPhase } from "./update-transaction.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";
@@ -13,6 +15,6 @@ export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistr
 export { PACKAGE_UNLOCK_PATIENCE_MS, UPDATE_ACTIVATION_BLOCKED_EXIT_CODE, UPDATE_ALREADY_RUNNING_EXIT_CODE, PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, isPackageLockError, lockedPackageDiagnostic, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
 export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, UpdateActivationBlockedError, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
-export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, npmPrefixForGlobalRoot, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
+export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, npmPrefixForGlobalRoot, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, resolveNpmCli, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
 export { UPDATE_JOURNAL_SCHEMA, UpdateTransactionStore } from "./update-transaction.js";
 export { warmMaterializedRelease } from "./warmup.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) {
@@ -757,7 +757,7 @@ export async function runSelfUpdate(options) {
             const message = errorMessage(error);
             if (error instanceof UpdateAutomaticDeferred)
                 return 1;
-            const blockedExit = await preparedActivationExit(error, transaction, mode, output, transactionStore);
+            const blockedExit = await preparedActivationExit(error, transaction, mode, output, transactionStore, targetVersion, paths.configDir);
             if (blockedExit !== null)
                 return blockedExit;
             if (error instanceof UpdatePreflightFailure) {
@@ -769,7 +769,7 @@ export async function runSelfUpdate(options) {
                 : await rollbackPriorCohort(paths.dataDir, environment, transaction?.priorActiveReleaseId ?? null).catch(rollbackError => `rollback failed: ${errorMessage(rollbackError)}`);
             if (transaction)
                 await transactionStore.finish(rollback === "rolled back" ? "rolled-back" : "failed", `${message}; ${rollback}`);
-            output.stderr(`${PRODUCT_TEXT.diagnostic(`update failed: ${message}. ${rollback}. Diagnostics: ${transactionStore.path}`)}\n`);
+            output.stderr(updateFailureLine(message, rollback, transactionStore.path));
             return error instanceof UpdateFailure ? error.exitCode : 1;
         }
     });
@@ -869,13 +869,22 @@ async function activateUpdateTransaction(lifecycle, transaction, packageRoot, ta
     else
         await lifecycle.activateInstalled(packageRoot, targetVersion, phase, materializing, warmup);
 }
-async function preparedActivationExit(error, transaction, mode, output, journal) {
+async function preparedActivationExit(error, transaction, mode, output, journal, targetVersion, configDir) {
     if (!(error instanceof UpdateActivationBlockedError) || transaction === null || phaseBefore(transaction.phase, "certified"))
         return null;
-    if (mode === "manual")
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`update prepared, but activation is blocked: ${error.message}. The prior client remains selected; run the update again after the resident blocker clears.`)}\n`);
     await journal.recordActiveError?.(error.message);
-    return UPDATE_ACTIVATION_BLOCKED_EXIT_CODE;
+    if (mode === "automatic")
+        return UPDATE_ACTIVATION_BLOCKED_EXIT_CODE;
+    // Invariant: a certified candidate waiting only for resident continuity is an installed update;
+    // the next startup check retries activation without another installation.
+    await invalidateReleaseCheckCache(configDir).catch(() => undefined);
+    output.stdout(`${PRODUCT_TEXT.commandName} updated to ${targetVersion}; it takes over automatically once running Agents can switch\n`);
+    return 0;
+}
+/** One reason and one next step; routine rollback detail stays in the journal. */
+function updateFailureLine(message, rollback, journalPath) {
+    const note = rollback.startsWith("rollback failed") ? ` (${rollback})` : "";
+    return `${PRODUCT_TEXT.diagnostic(`update failed: ${message}${note}. Run ${PRODUCT_TEXT.commandName} update to retry. Details: ${journalPath}`)}\n`;
 }
 function phaseBefore(current, target) {
     const phases = ["shutdown-intent", "ownership-released", "package-installed", "materialized", "certified", "active-reference-committed", "supervisor-verified"];

package/dist/foundation/resident-tabs/boot-identity.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mirrors the native boot matching rule. Legacy `macos-boot:<sec>:<usec>` records drift on clock
+ * corrections, so two of them match within the tolerance; only the native host can prove one
+ * against a current identity.
+ */
+export declare function sameBootIdentity(left: string, right: string): boolean;

package/dist/foundation/resident-tabs/boot-identity.js

@@ -0,0 +1,16 @@
+/** Seconds a legacy clock-derived boot identity may drift and still name the same boot. */
+const LEGACY_BOOT_TOLERANCE_SECONDS = 2;
+const LEGACY_MACOS_BOOT = /^macos-boot:(\d+):\d+$/u;
+/**
+ * Mirrors the native boot matching rule. Legacy `macos-boot:<sec>:<usec>` records drift on clock
+ * corrections, so two of them match within the tolerance; only the native host can prove one
+ * against a current identity.
+ */
+export function sameBootIdentity(left, right) {
+    if (left === right)
+        return true;
+    const first = LEGACY_MACOS_BOOT.exec(left)?.[1];
+    const second = LEGACY_MACOS_BOOT.exec(right)?.[1];
+    return first !== undefined && second !== undefined
+        && Math.abs(Number(first) - Number(second)) <= LEGACY_BOOT_TOLERANCE_SECONDS;
+}

package/dist/foundation/resident-tabs/bounded-host-command.d.ts

@@ -2,6 +2,8 @@ import type { TerminalHostCommand } from "./ensure-terminal-host.js";
 export interface BoundedHostCommandResult {
     readonly code: number;
     readonly stdout: string;
+    /** The command's last diagnostic line, bounded and stripped of control characters; never parsed. */
+    readonly stderr: string;
 }
 export interface BoundedHostCommandLimits {
     /** Output beyond this many bytes fails the exchange instead of being parsed. */

package/dist/foundation/resident-tabs/bounded-host-command.js

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+/** Diagnostics beyond this many bytes are dropped rather than buffered. */
+const MAX_STDERR_BYTES = 4096;
 /**
  * Runs one terminal-host command whose report is small. An oversized report kills the command and
  * reports a failed exchange; a command that outlives its deadline is killed and rejected.
@@ -8,9 +10,18 @@ export async function runBoundedHostCommand(command, arguments_, limits) {
         const child = spawn(command.executable, [command.entry, ...arguments_], {
             env: limits.environment,
             windowsHide: true,
-            stdio: ["ignore", "pipe", "ignore"],
+            stdio: ["ignore", "pipe", "pipe"],
         });
         const stdout = [];
+        const stderr = [];
+        let stderrSize = 0;
+        child.stderr.on("data", (chunk) => {
+            if (stderrSize >= MAX_STDERR_BYTES)
+                return;
+            const kept = chunk.subarray(0, MAX_STDERR_BYTES - stderrSize);
+            stderrSize += kept.length;
+            stderr.push(Buffer.from(kept));
+        });
         let size = 0;
         let overflowed = false;
         child.stdout.on("data", chunk => {
@@ -26,9 +37,10 @@ export async function runBoundedHostCommand(command, arguments_, limits) {
         child.once("error", rejectPromise);
         child.once("close", code => {
             clearTimeout(timer);
+            const diagnostic = lastDiagnosticLine(Buffer.concat(stderr).toString("utf8"));
             resolvePromise(overflowed
-                ? { code: code === 0 || code === null ? 1 : code, stdout: "" }
-                : { code: code ?? 1, stdout: Buffer.concat(stdout).toString("utf8") });
+                ? { code: code === 0 || code === null ? 1 : code, stdout: "", stderr: diagnostic }
+                : { code: code ?? 1, stdout: Buffer.concat(stdout).toString("utf8"), stderr: diagnostic });
         });
         const timer = setTimeout(() => {
             child.kill("SIGKILL");
@@ -37,3 +49,14 @@ export async function runBoundedHostCommand(command, arguments_, limits) {
         timer.unref();
     });
 }
+/** Keeps one terminal-safe line: the native host reports its reason last. */
+function lastDiagnosticLine(text) {
+    const lines = text.split(/\r?\n/u)
+        // Security: diagnostics never carry terminal controls into a later message.
+        .map(line => line
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, "")
+        .replace(/[\u0000-\u001f\u007f-\u009f]/gu, "")
+        .trim())
+        .filter(line => line.length > 0);
+    return (lines.at(-1) ?? "").slice(0, 300);
+}

package/dist/foundation/resident-tabs/continuity.js

@@ -10,7 +10,7 @@ export async function assertResidentContinuity(options) {
     const first = await inspect(context);
     const second = await inspect(context);
     if (first !== second && second !== await inspect(context)) {
-        throw new Error("Resident workspace changed during update readiness; the prior client remains selected.");
+        throw new Error("Resident workspace changed during update readiness");
     }
 }
 /** Native inspection/import is read-only toward execution and never starts or stops a source. */
@@ -40,16 +40,24 @@ export async function inspectResidentContinuity(options) {
         "workspace-check", "--profile", options.profileRoot,
         "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir,
     ], { label: "resident continuity check", maxStdoutBytes: 4096, timeoutMs: 8_000, environment: options.environment });
+    const unverified = new Error(continuityFailure(result.stderr));
     let report;
     try {
         report = JSON.parse(result.stdout.trim());
     }
     catch {
-        throw new Error("Resident control compatibility could not be verified; the prior client remains selected.");
+        throw unverified;
     }
     if (result.code !== 0 || report.schema !== "resident-workspace-check-v1" || report.compatible !== true
         || typeof report.fingerprint !== "string" || !/^[a-f0-9]{64}$/u.test(report.fingerprint)) {
-        throw new Error("Resident control compatibility could not be verified; the prior client remains selected.");
+        throw unverified;
     }
     return report.fingerprint;
 }
+/** Names the native reason when the host reported one, without the host's own prefix. */
+function continuityFailure(diagnostic) {
+    const reason = diagnostic.replace(/^a1-terminal-host:\s*/u, "").replace(/[.\s]+$/u, "");
+    return reason.length > 0
+        ? `Resident control compatibility could not be verified: ${reason}`
+        : "Resident control compatibility could not be verified";
+}

package/dist/foundation/resident-tabs/runtime-control.js

@@ -1,3 +1,4 @@
+import { sameBootIdentity } from "./boot-identity.js";
 import { runTerminalHostMaintenance } from "./maintenance.js";
 /** Mandatory native control semantics; optional methods never establish source authority. */
 export const RUNTIME_CONTROL_API = "resident-control-v1";
@@ -21,7 +22,7 @@ export function assessRuntimeControl(value, expected) {
         return blocked("invalid-contract");
     }
     if (value.releaseId !== expected.releaseId || value.scope !== expected.scope
-        || value.bootId !== expected.bootId || value.osSessionId !== expected.osSessionId)
+        || !sameBootIdentity(value.bootId, expected.bootId) || value.osSessionId !== expected.osSessionId)
         return blocked("source-mismatch");
     if (value.epoch !== expected.epoch)
         return blocked("stale-epoch");

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();