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

package/dist/foundation/release/update.js

@@ -1,22 +1,18 @@
 import { spawn } from "node:child_process";
 import { access, lstat, readFile, realpath, rename } from "node:fs/promises";
-import { connect } from "node:net";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { dirname, resolve } from "node:path";
 import crossSpawn from "cross-spawn";
 import { valid as validSemver } from "semver";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { earlyAccentPalette, earlyTerminalAppearance, earlyTerminalColorMode, resolveEarlyAccentColor } from "./early-accent.js";
 import { SHARED_PROGRESS_ACCENT_ANSI } from "./progress-palette.generated.js";
 import { createRegistryFetcher, invalidateReleaseCheckCache, isNewerRelease, queryPublishedVersions, releaseChannelOf, } from "./latest-release.js";
-import { certifyMaterializedRelease, ensureSupervisor, waitForProcessExit, } from "./bootstrap.js";
-import { probeOwnership, readEndpointMetadata, removeEndpointArtifacts } from "./endpoints.js";
-import { resolveCohortEndpoint, resolveProductPaths } from "../lifecycle/index.js";
-import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
+import { certifyMaterializedRelease } from "./bootstrap.js";
+import { resolveProductPaths } from "../lifecycle/index.js";
 import { CohortStateStore } from "./cohort-state.js";
-import { cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
 import { materializeRelease, readMaterializedRelease } from "./release-store.js";
 import { scheduleReleaseCleanup } from "./release-gc.js";
-import { UPDATE_ACTIVATION_CONTRACT, UpdateActivationBlockedError, activateInstalledRelease, delegateActivation, readActivationContracts, } from "./update-activation.js";
+import { UPDATE_ACTIVATION_CONTRACT, activateInstalledRelease, delegateActivation, readActivationContracts, } from "./update-activation.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 import { acquireUpdateExecutionLease, reclaimDeadLease } from "./update-execution-lease.js";
 import { npmPrefixForGlobalRoot, removeUpdateRecoveryCapsule, resolveNpmCli, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
@@ -37,7 +33,6 @@ const defaultFileSystem = {
  */
 export const PACKAGE_UNLOCK_PATIENCE_MS = 15_000;
 export const UPDATE_ALREADY_RUNNING_EXIT_CODE = 75;
-export const UPDATE_ACTIVATION_BLOCKED_EXIT_CODE = 76;
 /** A named preview reads the registry's whole package document, which is larger than a dist-tag lookup. */
 const PREVIEW_LOOKUP_TIMEOUT_MS = 30_000;
 const PACKAGE_UNLOCK_INITIAL_DELAY_MS = 100;
@@ -53,7 +48,7 @@ export function isPackageLockError(error) {
 /** What the user reads when the package stayed held for the whole patience window. */
 export function lockedPackageDiagnostic(packageRoot, waitedMs, attempts, error) {
     const seconds = Math.max(1, Math.round(waitedMs / 1_000));
-    return PRODUCT_TEXT.diagnostic(`package remained locked for ${seconds}s after verified shutdown (${attempts} checks): ${errorMessage(error)}. `
+    return PRODUCT_TEXT.diagnostic(`package remained locked for ${seconds}s (${attempts} checks): ${errorMessage(error)}. `
         + `Another program is holding a file under ${packageRoot}: an antivirus scan, a file browser or terminal open inside it, `
         + `or a session still shutting down. Close it and run the update again; nothing was changed.`);
 }
@@ -87,103 +82,14 @@ export function createNpmProcessRunner(platform = process.platform) {
         } });
     });
 }
-/**
- * What an update does about the owner it found. A cohort running from retained immutable
- * content keeps its work: the installation replaces files it does not read, and it listens on
- * its own endpoint. A cohort running from the mutable installation is the one exception,
- * because that installation is exactly what is about to be replaced under it.
- */
-async function verifyAutomaticUpdateSafety(paths, stateStore, environment) {
-    const state = await stateStore.read();
-    const owner = await readActiveEndpoint(paths, state.references.active, environment);
-    if (!owner)
-        return;
-    const ownership = await probeOwnership(owner.metadata);
-    if (ownership === "dead")
-        return;
-    if (ownership !== "live-verified") {
-        throw new UpdateAutomaticDeferred(PRODUCT_TEXT.diagnostic(`automatic update deferred because supervisor ownership is ${ownership}`));
-    }
-    if (!await canonicalImmutableRoot(paths.dataDir, owner.metadata.releaseRoot)) {
-        throw new UpdateAutomaticDeferred(PRODUCT_TEXT.diagnostic("automatic update deferred because the running session is not using a retained immutable release; run the update command manually"));
-    }
-}
-export function planUpdateOwnership(ownership, runsFromRetainedRelease) {
-    if (ownership === "dead")
-        return "clean-dead-record";
-    return runsFromRetainedRelease ? "leave-running" : "end-session";
-}
-/**
- * The endpoint of the active cohort, together with where it is recorded, so a caller that
- * finds it can also clean it up. A release that predates cohort-scoped endpoints published
- * one endpoint for the runtime directory, and that one is recognized too.
- */
-async function readActiveEndpoint(paths, activeReleaseId, environment) {
-    if (activeReleaseId !== null) {
-        const cohort = resolveCohortEndpoint(paths, activeReleaseId, environment);
-        const metadata = await readEndpointMetadata(cohort.endpointMetadataPath);
-        if (metadata)
-            return { metadata, paths: cohort };
-    }
-    const legacyPaths = { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
-    const legacy = await readEndpointMetadata(legacyPaths.endpointMetadataPath);
-    return legacy ? { metadata: legacy, paths: legacyPaths } : null;
-}
-export function createUpdateLifecycleCoordinator(environment = process.env, fileSystem = defaultFileSystem, output = defaultOutput, patience = {}) {
+export function createUpdateLifecycleCoordinator(environment = process.env, fileSystem = defaultFileSystem, _output = defaultOutput, patience = {}) {
     const paths = resolveProductPaths(environment);
     const stateStore = new CohortStateStore(paths.dataDir);
     return {
         async targetIsActive(targetVersion) {
             const state = await stateStore.read(), activeId = state.references.active;
-            if (!activeId || state.releases[activeId]?.packageVersion !== targetVersion)
-                return false;
-            const endpoint = await readActiveEndpoint(paths, activeId, environment);
-            return endpoint?.metadata.releaseId === activeId && await probeOwnership(endpoint.metadata) === "live-verified";
-        },
-        async verifyAutomaticSafety() { await verifyAutomaticUpdateSafety(paths, stateStore, environment); },
-        async shutdownVerifiedOwners(targetVersion) {
-            const state = await stateStore.read();
-            const activeId = state.references.active;
-            const priorActiveVersion = activeId ? state.releases[activeId]?.packageVersion ?? null : null;
-            const owner = await readActiveEndpoint(paths, activeId, environment);
-            if (!owner)
-                return { priorActiveVersion };
-            const endpoint = owner.metadata;
-            const ownership = await probeOwnership(endpoint);
-            if (ownership !== "live-verified" && ownership !== "dead") {
-                throw new Error(PRODUCT_TEXT.diagnostic(`refused update shutdown because supervisor ownership is ${ownership}`));
-            }
-            const plan = planUpdateOwnership(ownership, await canonicalImmutableRoot(paths.dataDir, endpoint.releaseRoot));
-            if (plan === "clean-dead-record") {
-                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
-            // the progress bar; only ending a session (below) is worth interrupting it for.
-            if (plan === "leave-running")
-                return { priorActiveVersion };
-            // Rationale: say whose work is ending before it ends.
-            const live = endpoint.ownership.liveInstanceIds.length;
-            if (live > 0) {
-                output.stderr(`${PRODUCT_TEXT.diagnostic(`ending ${live === 1 ? "one session" : `${live} sessions`} that run from the installation being replaced; a session started by an installed release would have been left alone.`)}\n`);
-            }
-            const identity = await requestUpdateShutdown(endpoint, targetVersion, 2_000);
-            if (!identity.accepted && processIsAlive(endpoint.pid)) {
-                // Security: explicit update consent permits bounded cleanup of an authenticated
-                // older owner that predates the update-shutdown message.
-                const cleanup = await cleanupVerifiedOwner(endpoint, { allowLiveInstances: true, reason: "legacy-mutable-install" });
-                if (!cleanup.terminated)
-                    throw new Error(`verified ${PRODUCT_TEXT.displayName} owner ${endpoint.pid} rejected shutdown and could not be terminated: ${identity.reason}`);
-            }
-            else if (identity.accepted) {
-                await waitForProcessExit(endpoint.pid, 3_000).catch(async () => {
-                    const cleanup = await cleanupVerifiedOwner(endpoint, { allowLiveInstances: true, reason: "legacy-mutable-install" });
-                    if (!cleanup.terminated)
-                        throw new Error(`verified ${PRODUCT_TEXT.displayName} owner ${endpoint.pid} did not terminate`);
-                });
-            }
-            await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint, endpoint);
-            return { priorActiveVersion };
+            const active = activeId === null ? undefined : state.releases[activeId];
+            return active?.approval === "approved" && active.packageVersion === targetVersion;
         },
         async verifyPackageUnlocked(packageRoot) {
             if (fileSystem.access)
@@ -196,7 +102,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             const startedAt = now();
             let delay = PACKAGE_UNLOCK_INITIAL_DELAY_MS;
             let attempts = 0;
-            // Rationale: a holder found right after ownership was released is almost always transient,
+            // Rationale: a holder found before the replacement is almost always transient,
             // so one failed rename is a reason to look again, not to abandon an update that has not
             // yet changed anything. The wait is bounded so a genuine lock still fails clearly.
             const withPatience = async (from, to, describeFailure) => {
@@ -236,13 +142,8 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             else
                 await activateInstalledRelease(request, callbacks);
         },
-        async activatePrepared(targetVersion, phase) { await retryPreparedActivation(paths.dataDir, environment, targetVersion, phase); },
     };
 }
-async function retryPreparedActivation(dataDir, environment, targetVersion, phase) {
-    await (await import("./prepared-update-activation.js"))
-        .activatePreparedRelease({ dataDir, targetVersion, environment }, { phase });
-}
 const PROGRESS_BAR_WIDTH = 38;
 const PROGRESS_TICK_MS = 200;
 /**
@@ -513,10 +414,10 @@ async function withUpdateExecutionLease(input, options, output, operation) {
     let lease = await acquireUpdateExecutionLease(input);
     if (lease.status === "interrupted") {
         // Rationale: the owner that targeted another version is gone. Its durable transaction is rolled
-        // back to the cohort that ran before it, so this request proceeds as an ordinary update of its
+        // back to the release that ran before it, so this request proceeds as an ordinary update of its
         // own target instead of reporting a dead attempt as in progress.
         const interrupted = lease.owner.targetVersion;
-        const rollback = await rollbackPriorCohort(input.dataDir, options.environment ?? process.env, lease.transaction.priorActiveReleaseId)
+        const rollback = await rollbackPriorRelease(input.dataDir, lease.transaction.priorActiveReleaseId)
             .catch(error => `rollback failed: ${errorMessage(error)}`);
         const store = new UpdateTransactionStore(input.dataDir);
         await store.finish("rolled-back", `interrupted ${interrupted} update settled by ${input.targetVersion}; ${rollback}`);
@@ -610,8 +511,6 @@ export async function runSelfUpdate(options) {
         let transaction = await transactionStore.read();
         let npmCli;
         try {
-            if (mode === "automatic")
-                await lifecycle.verifyAutomaticSafety?.();
             if ((!transaction || transaction.status === "completed") && await lifecycle.targetIsActive(targetVersion)) {
                 await maintenance();
                 await transactionStore.clearCompleted();
@@ -650,10 +549,7 @@ export async function runSelfUpdate(options) {
                 priorActiveReleaseId,
             });
             if (phaseBefore(transaction.phase, "ownership-released")) {
-                await measure("ownership-release", async () => {
-                    await lifecycle.shutdownVerifiedOwners(targetVersion);
-                    await lifecycle.verifyPackageUnlocked(packageRoot);
-                });
+                await measure("ownership-release", async () => { await lifecycle.verifyPackageUnlocked(packageRoot); });
                 transaction = await transactionStore.advance("ownership-released");
             }
             progress.set(15, 70);
@@ -711,12 +607,7 @@ export async function runSelfUpdate(options) {
                     transaction = await transactionStore.advance("package-installed");
                 }
             }
-            progress.set(70, 75);
-            // Concurrency: ownership can be reacquired after an interrupted installation (for
-            // example, if bare A1 is launched before the update is resumed). Recheck
-            // immediately before activation so recovery cannot start a second cohort.
-            await measure("ownership-release", async () => { await lifecycle.shutdownVerifiedOwners(targetVersion); });
-            progress.set(75, MATERIALIZE_PROGRESS.from);
+            progress.set(70, MATERIALIZE_PROGRESS.from);
             let activationPhaseStartedAt = now();
             const recordActivationPhase = async (phase) => {
                 options.onPhaseTiming?.({ phase, durationMs: Math.max(0, now() - activationPhaseStartedAt) });
@@ -724,7 +615,7 @@ export async function runSelfUpdate(options) {
                 progress.set(ACTIVATION_PROGRESS[phase].at, ACTIVATION_PROGRESS[phase].creepTo);
                 activationPhaseStartedAt = now();
             };
-            await activateUpdateTransaction(lifecycle, transaction, packageRoot, targetVersion, recordActivationPhase, ({ completed, total }) => progress.set(MATERIALIZE_PROGRESS.from
+            await lifecycle.activateInstalled(packageRoot, targetVersion, recordActivationPhase, ({ completed, total }) => progress.set(MATERIALIZE_PROGRESS.from
                 + (MATERIALIZE_PROGRESS.to - MATERIALIZE_PROGRESS.from) * (total > 0 ? Math.min(1, completed / total) : 0)), state => {
                 if (state === "started") {
                     activationPhaseStartedAt = now();
@@ -736,9 +627,7 @@ export async function runSelfUpdate(options) {
                     progress.set(99);
                 }
             });
-            options.onPhaseTiming?.({ phase: "supervisor-verified", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
             const transactionStartedAt = now();
-            await transactionStore.advance("supervisor-verified");
             if (transaction.recovery?.capsulePath)
                 await removeUpdateRecoveryCapsule(paths.dataDir, transaction.transactionId);
             // Invariant: successful output follows the durable cleanup disposition. Slow recursive
@@ -755,18 +644,13 @@ export async function runSelfUpdate(options) {
         catch (error) {
             progress.clear();
             const message = errorMessage(error);
-            if (error instanceof UpdateAutomaticDeferred)
-                return 1;
-            const blockedExit = await preparedActivationExit(error, transaction, mode, output, transactionStore, targetVersion, paths.configDir);
-            if (blockedExit !== null)
-                return blockedExit;
             if (error instanceof UpdatePreflightFailure) {
                 output.stderr(`${PRODUCT_TEXT.diagnostic(`update could not start safely: ${message}. Nothing was changed. Retry with npm x -y -- ${PRODUCT_PACKAGE}-install`)}\n`);
                 return 1;
             }
             const rollback = options.lifecycle
                 ? "previous test lifecycle retained"
-                : await rollbackPriorCohort(paths.dataDir, environment, transaction?.priorActiveReleaseId ?? null).catch(rollbackError => `rollback failed: ${errorMessage(rollbackError)}`);
+                : await rollbackPriorRelease(paths.dataDir, transaction?.priorActiveReleaseId ?? null).catch(rollbackError => `rollback failed: ${errorMessage(rollbackError)}`);
             if (transaction)
                 await transactionStore.finish(rollback === "rolled back" ? "rolled-back" : "failed", `${message}; ${rollback}`);
             output.stderr(updateFailureLine(message, rollback, transactionStore.path));
@@ -790,35 +674,6 @@ export function assertUpdatePerformanceBudget(evidence, maximumPostNpmDurationMs
     if (failures.length > 0)
         throw new Error(`update performance budget failed: ${failures.join("; ")}`);
 }
-async function requestUpdateShutdown(metadata, targetVersion, timeoutMs) {
-    if (!processIsAlive(metadata.pid))
-        return { accepted: false, reason: "recorded owner is dead" };
-    return await new Promise(resolvePromise => {
-        const socket = connect(metadata.endpoint);
-        const decoder = new LineFrameDecoder();
-        let settled = false;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            socket.destroy();
-            resolvePromise(value);
-        };
-        socket.once("error", () => finish({ accepted: false, reason: "verified endpoint did not respond" }));
-        socket.once("connect", () => socket.write(encodeFrame({ type: "release-update-ownership", bootNonce: metadata.bootNonce, targetVersion })));
-        socket.on("data", chunk => {
-            try {
-                const message = decoder.push(chunk)[0];
-                if (message?.type === "release-update-result")
-                    finish({ accepted: message.accepted === true, reason: String(message.reason ?? "shutdown rejected") });
-            }
-            catch {
-                finish({ accepted: false, reason: "invalid shutdown response" });
-            }
-        });
-        setTimeout(() => finish({ accepted: false, reason: "verified endpoint shutdown timed out" }), timeoutMs).unref();
-    });
-}
 async function runNpm(runner, arguments_, captureStdout, output, action, reportNonzero = true) {
     let result;
     try {
@@ -843,51 +698,31 @@ function reportChildDiagnostics(output, result) {
     output.stderr(`${text}\n`);
     return true;
 }
-async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
+async function rollbackPriorRelease(dataDir, priorReleaseId) {
     if (!priorReleaseId)
-        return "no prior cohort was available for rollback";
+        return "no prior release was available for rollback";
     const stateStore = new CohortStateStore(dataDir);
     const state = await stateStore.read();
     const prior = state.releases[priorReleaseId];
     if (!prior || prior.approval !== "approved")
-        return "prior cohort is not a verified rollback candidate";
+        return "prior release is not a verified rollback candidate";
     if (state.references.active !== priorReleaseId) {
         if (state.references.rollback === priorReleaseId)
-            await stateStore.rollback(true);
+            await stateStore.rollback();
         else
-            throw new Error(`prior release ${priorReleaseId} is not the recorded rollback cohort`);
+            throw new Error(`prior release ${priorReleaseId} is not the recorded rollback release`);
     }
-    const release = await readMaterializedRelease(prior.releaseRoot);
-    // Invariant: rollback reuses a surviving prior cohort rather than racing its occupied endpoint.
-    await ensureSupervisor(release, environment);
+    // Invariant: rollback selects only a prior release whose retained content still verifies.
+    await readMaterializedRelease(prior.releaseRoot);
     return "rolled back";
 }
-async function activateUpdateTransaction(lifecycle, transaction, packageRoot, targetVersion, phase, materializing, warmup) {
-    if (!phaseBefore(transaction.phase, "certified") && phaseBefore(transaction.phase, "active-reference-committed")
-        && lifecycle.activatePrepared !== undefined)
-        await lifecycle.activatePrepared(targetVersion, phase);
-    else
-        await lifecycle.activateInstalled(packageRoot, targetVersion, phase, materializing, warmup);
-}
-async function preparedActivationExit(error, transaction, mode, output, journal, targetVersion, configDir) {
-    if (!(error instanceof UpdateActivationBlockedError) || transaction === null || phaseBefore(transaction.phase, "certified"))
-        return null;
-    await journal.recordActiveError?.(error.message);
-    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"];
+    const phases = ["shutdown-intent", "ownership-released", "package-installed", "materialized", "certified", "active-reference-committed"];
     return phases.indexOf(current) < phases.indexOf(target);
 }
 class UpdateFailure extends Error {
@@ -896,18 +731,6 @@ class UpdateFailure extends Error {
 }
 class UpdatePreflightFailure extends Error {
 }
-class UpdateAutomaticDeferred extends Error {
-}
-async function canonicalImmutableRoot(dataDir, releaseRoot) {
-    try {
-        const [store, selected] = await Promise.all([realpath(resolve(dataDir, "releases")), realpath(releaseRoot)]);
-        const fromStore = relative(store, selected);
-        return fromStore.length > 0 && fromStore !== ".." && !fromStore.startsWith(`..${sep}`) && !isAbsolute(fromStore);
-    }
-    catch {
-        return false;
-    }
-}
 function samePath(left, right) {
     return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
 }

package/dist/foundation/session-writer-lock/index.d.ts

@@ -1,11 +1,11 @@
-import { existsSync } from "node:fs";
-export interface NativeLock {
+/** One held authority; `bindCreated` moves a reservation onto the file it created. */
+export interface WriterLock {
     readonly bound: boolean;
     bindCreated(path: string): void;
     release(): void;
 }
 export interface LockBackend {
-    acquire(path: string): NativeLock;
+    acquire(path: string): WriterLock;
 }
 /** Reports that a canonical session identity already has a live writer. */
 export declare class SessionWriterConflict extends Error {
@@ -19,12 +19,20 @@ export interface SessionWriterHandle {
     bind(createdPath?: string): void;
     release(): void;
 }
-/** Security: a release that carries its own terminal-host addon never loads one chosen by cwd. */
-export declare function nativeCandidates(moduleUrl?: string, env?: NodeJS.ProcessEnv, cwd?: string, exists?: typeof existsSync): string[];
+/**
+ * A crashed writer is not released by the kernel; its lock becomes stale once its holder stops
+ * refreshing it. The bound keeps resume after a crash a matter of seconds.
+ */
+export declare const SESSION_WRITER_STALE_MS = 10000;
+/**
+ * Locks live in one per-user directory keyed by canonical identity, not beside the session, so two
+ * spellings of one file (case, short names, links, hard links) contend for the same lock.
+ */
+export declare function lockfileBackend(root?: string, staleMs?: number): LockBackend;
 export declare function acquireExisting(path: string): SessionWriterHandle;
 export declare function reserveNew(parent: string, name: string): SessionWriterHandle;
 export declare function acquireSessionWriter(path: string): SessionWriterHandle;
 export declare function bind(handle: SessionWriterHandle, createdPath?: string): void;
 export declare function release(handle: SessionWriterHandle): void;
-/** Test-only backend seam; passing undefined restores native discovery. */
+/** Test-only backend seam; passing undefined restores the default backend. */
 export declare function setSessionWriterLockBackendForTest(value: LockBackend | undefined): void;

package/dist/foundation/session-writer-lock/index.js

@@ -1,10 +1,8 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
+import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import lockfile from "proper-lockfile";
 /** Reports that a canonical session identity already has a live writer. */
 export class SessionWriterConflict extends Error {
     path;
@@ -16,107 +14,60 @@ export class SessionWriterConflict extends Error {
         this.holderKind = holderKind;
     }
 }
+/**
+ * A crashed writer is not released by the kernel; its lock becomes stale once its holder stops
+ * refreshing it. The bound keeps resume after a crash a matter of seconds.
+ */
+export const SESSION_WRITER_STALE_MS = 10_000;
 let backendOverride;
 let cachedBackend;
-/** Security: a release that carries its own terminal-host addon never loads one chosen by cwd. */
-export function nativeCandidates(moduleUrl = import.meta.url, env = process.env, cwd = process.cwd(), exists = existsSync) {
-    const addon = `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`;
-    // Invariant: this module sits at dist/foundation/session-writer-lock/ inside the release root.
-    const own = resolve(fileURLToPath(new URL("../../../", moduleUrl)), "dist", "native", `${process.platform}-${process.arch}`, addon);
-    const override = env[PRODUCT_IDENTITY.environment.developmentInstanceId]
-        ? env[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim() || undefined
-        : undefined;
-    const local = exists(own)
-        ? [own]
-        : [resolve(cwd, "dist", "native", `${process.platform}-${process.arch}`, addon), resolve(cwd, ".artifacts", "terminal-host", addon)];
-    return override ? [override, ...local] : local;
-}
-function loadNativeBackend() {
-    const require = createRequire(import.meta.url);
-    for (const candidate of nativeCandidates()) {
-        if (!existsSync(candidate))
-            continue;
-        try {
-            const loaded = require(candidate);
-            if (loaded.SessionLock?.acquire)
-                return loaded.SessionLock;
-        }
-        catch {
-            // Compatibility: an addon for another Node ABI is unusable; try the next location.
-        }
-    }
-    return undefined;
-}
-function processIsLive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** Development fallback. Installed releases carry the verified Node-API lock resolved above. */
-function portableBackend() {
-    const root = join(tmpdir(), "a1-session-writer-locks");
-    mkdirSync(root, { recursive: true, mode: 0o700 });
+/**
+ * Locks live in one per-user directory keyed by canonical identity, not beside the session, so two
+ * spellings of one file (case, short names, links, hard links) contend for the same lock.
+ */
+export function lockfileBackend(root = join(tmpdir(), "a1-session-writer-locks"), staleMs = SESSION_WRITER_STALE_MS) {
     const authorityPath = (kind, key) => join(root, `${createHash("sha256").update(`${kind}\0${key}`).digest("hex")}.lock`);
+    // Platform: Windows file names are case-insensitive, and realpath canonicalizes only existing parents.
     const locationKey = (path) => `${realpathSync.native(dirname(path))}\0${process.platform === "win32" ? basename(path).toLowerCase() : basename(path)}`;
     const identityKey = (path) => {
-        const physical = realpathSync.native(path);
-        const metadata = statSync(physical, { bigint: true });
+        const metadata = statSync(realpathSync.native(path), { bigint: true });
         return `${metadata.dev}:${metadata.ino}`;
     };
     const acquireAuthority = (path) => {
-        for (let attempt = 0; attempt < 2; attempt += 1) {
-            try {
-                const descriptor = openSync(path, "wx", 0o600);
-                writeFileSync(descriptor, JSON.stringify({ pid: process.pid, kind: process.env.A1_TAB_ID ? "resident tab" : "another A1 process" }));
-                closeSync(descriptor);
-                return;
-            }
-            catch (error) {
-                if (attempt === 0) {
-                    try {
-                        const record = JSON.parse(readFileSync(path, "utf8"));
-                        if (typeof record.pid === "number" && !processIsLive(record.pid)) {
-                            rmSync(path, { force: true });
-                            continue;
-                        }
-                    }
-                    catch {
-                        // Security: malformed or racing lock evidence remains authoritative and fails closed.
-                    }
-                }
-                throw error;
-            }
-        }
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        // Rationale: the lock directory is the authority; no target file exists or is needed.
+        return lockfile.lockSync(path, {
+            realpath: false,
+            lockfilePath: path,
+            stale: staleMs,
+            // Rationale: a missed refresh means this process stalled; the next writer takes over, and the
+            // stalled one must not crash for it.
+            onCompromised: () => { },
+        });
     };
     return {
         acquire(requested) {
             const absolute = resolve(requested);
-            const location = authorityPath("location", locationKey(absolute));
-            acquireAuthority(location);
-            let identity;
-            let identityAcquired = false;
+            let releaseCurrent = acquireAuthority(authorityPath("location", locationKey(absolute)));
             let bound = false;
-            try {
-                if (existsSync(absolute)) {
-                    const key = identityKey(absolute);
-                    identity = authorityPath("identity", key);
-                    acquireAuthority(identity);
-                    identityAcquired = true;
-                    if (identityKey(absolute) !== key) {
-                        throw new Error("session identity changed while its writer lock was acquired");
-                    }
-                    rmSync(location, { force: true });
-                    bound = true;
+            const bindTo = () => {
+                const key = identityKey(absolute);
+                const releaseIdentity = acquireAuthority(authorityPath("identity", key));
+                if (identityKey(absolute) !== key) {
+                    releaseIdentity();
+                    throw new Error("session identity changed while its writer lock was acquired");
                 }
+                // Invariant: the identity lock is held before the location lock goes, so there is no gap.
+                releaseCurrent();
+                releaseCurrent = releaseIdentity;
+                bound = true;
+            };
+            try {
+                if (existsSync(absolute))
+                    bindTo();
             }
             catch (error) {
-                rmSync(location, { force: true });
-                if (identityAcquired && identity !== undefined)
-                    rmSync(identity, { force: true });
+                releaseCurrent();
                 throw error;
             }
             let released = false;
@@ -126,29 +77,23 @@ function portableBackend() {
                     if (bound || resolve(created) !== absolute || !existsSync(absolute)) {
                         throw new Error("created session does not match its reservation");
                     }
-                    const key = identityKey(absolute);
-                    identity = authorityPath("identity", key);
-                    acquireAuthority(identity);
-                    if (identityKey(absolute) !== key) {
-                        rmSync(identity, { force: true });
-                        identity = undefined;
-                        throw new Error("created session identity changed during bind");
-                    }
-                    rmSync(location, { force: true });
-                    bound = true;
+                    bindTo();
                 },
                 release() {
                     if (released)
                         throw new Error("session lock was already released");
                     released = true;
-                    rmSync(bound ? identity : location, { force: true });
+                    try {
+                        releaseCurrent();
+                    }
+                    catch { /* Compatibility: a reclaimed stale lock is already gone. */ }
                 },
             };
         },
     };
 }
 function backend() {
-    return backendOverride ?? (cachedBackend ??= loadNativeBackend() ?? portableBackend());
+    return backendOverride ?? (cachedBackend ??= lockfileBackend());
 }
 function acquire(path) {
     const absolute = resolve(path);
@@ -157,7 +102,7 @@ function acquire(path) {
         lock = backend().acquire(absolute);
     }
     catch {
-        throw new SessionWriterConflict(absolute, process.env.A1_TAB_ID ? "a resident tab" : "another A1 process");
+        throw new SessionWriterConflict(absolute);
     }
     let released = false;
     return {
@@ -196,7 +141,7 @@ export function bind(handle, createdPath) {
 export function release(handle) {
     handle.release();
 }
-/** Test-only backend seam; passing undefined restores native discovery. */
+/** Test-only backend seam; passing undefined restores the default backend. */
 export function setSessionWriterLockBackendForTest(value) {
     backendOverride = value;
     cachedBackend = undefined;

package/dist/foundation/startup/startup-runtime.d.ts

@@ -1,5 +1,5 @@
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-export type StartupPhase = "command-invoked" | "bootstrap-start" | "bootstrap-selected" | "durable-validation-start" | "durable-validation-complete" | "replacement-supervisor-start" | "replacement-supervisor-ready" | "guardian-start" | "guardian-connected" | "ui-entry" | "ui-modules-loaded" | "pi-services" | "resource-discovery" | "session-created" | "settings-loaded" | "first-input-ready-render";
+export type StartupPhase = "command-invoked" | "bootstrap-start" | "bootstrap-selected" | "durable-validation-start" | "durable-validation-complete" | "ui-entry" | "ui-modules-loaded" | "pi-services" | "resource-discovery" | "session-created" | "settings-loaded" | "first-input-ready-render";
 export interface StartupTraceEvent {
     readonly schema: typeof PRODUCT_IDENTITY.evidence.startupTraceSchema;
     readonly traceId: string;

package/dist/foundation/terminal-cleanup/exit-notice.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The launcher's half of the unclean-exit protocol. The UI arms a notice file while it runs and
+ * removes it on a clean exit, so a notice that is still present when the UI ends means the UI was
+ * stopped unexpectedly: restore the terminal, print the notice as plain text, and consume it.
+ */
+export declare function deliverExitNotice(path: string, write: (text: string) => void, restore?: () => void): boolean;