@timurproko/a1 0.1.8-dev.332 → 0.1.8-dev.335

package/README.md

@@ -160,18 +160,29 @@ a1 update --develop 0.1.8-dev.107       # install that exact full preview versio
 ### Stable
 
 ```sh
-npm run release -- patch     # 0.1.1 -> 0.1.2
-npm run release -- minor     # 0.1.1 -> 0.2.0
-npm run release -- major     # 0.1.1 -> 1.0.0
-npm run release -- 0.4.0     # an exact version
+npm run release -- patch     # 0.1.8-dev -> 0.1.8; already-stable 0.1.8 -> 0.1.9
+npm run release -- minor     # 0.1.8-dev -> 0.2.0
+npm run release -- major     # 0.1.8-dev -> 1.0.0
+npm run release -- 0.4.0     # an exact stable version
 ```
 
-The command lands the version on `develop` through a self-merging pull request,
-dispatches publication for that exact commit, and waits for success. CI validates
-the packed release on Windows, Linux, and macOS, publishes to npm `latest` with
-provenance, then writes the `v<version>` tag and the GitHub Release. `master`
-fast-forwards to the released commit, so it always points at what npm `latest`
-serves. A failed release leaves nothing behind: no tag, no GitHub Release, no
-moved branch.
+Run from the repository root on a clean `develop` matching `origin/develop`.
+A target is required; bare `npm run release` displays usage and releases nothing.
+`patch` promotes the current prerelease rather than skipping its stable version.
+
+The command prepares a version-only PR in an isolated detached worktree, prints
+its URL, and waits for you to validate and **merge it manually**. Neither this PR
+nor the next-development PR is auto-merged, and green CI alone does not advance
+the release. After the stable PR merges, the command dispatches publication for
+that exact authoritative commit and waits for success. CI validates the packed
+release on Windows, Linux, and macOS, publishes to npm `latest` with provenance,
+then writes the `v<version>` tag and GitHub Release and fast-forwards `master`.
+
+Only after confirmed publication of `0.1.8` does the command prepare the separate
+`0.1.9-dev` PR. It reports development reopened only after you manually merge that
+PR too. Work added to your checkout during either wait is preserved, not reset.
+If publication fails or is uncertain, no reopening PR is prepared. If publication
+succeeded but reopening failed, inspect the reported phase and PR; do not republish
+the immutable stable version.
 
 `docs/ci-release-runbook.md` has the full picture.

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

@@ -35,6 +35,8 @@ export interface SupervisorStartupAttempt extends SupervisorStartupAttemptIdenti
         readonly signal: NodeJS.Signals | null;
     }>;
 }
+/** Reuse a verified owner, or join the winner if another launch starts the same cohort first. */
+export declare function ensureSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<void>;
 export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<SupervisorStartupAttempt>;
 /**
  * Hand a release the key set its own build reads. A retained pre-cutover release is

package/dist/foundation/release/bootstrap.js

@@ -10,6 +10,8 @@ import { assertLaunchProfileId, createSupervisorStartupAttempt, readSupervisorSt
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
 import { sweepDeadEndpoints } from "./endpoints.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+import { selectUpdateLaunchRelease } from "./update-launch.js";
 import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
@@ -29,6 +31,21 @@ export async function runBootstrap(options) {
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const stateStore = new CohortStateStore(paths.dataDir);
     let state = await stateStore.read();
+    const launchDuringUpdate = async () => {
+        // Concurrency: read the journal before touching npm's mutable tree, including package.json.
+        const transaction = await new UpdateTransactionStore(paths.dataDir).read();
+        if (!transaction || transaction.status === "completed")
+            return null;
+        const prior = selectUpdateLaunchRelease(await stateStore.read(), transaction);
+        if (!prior)
+            return null;
+        const retained = await readCertifiedReleaseManifest(prior, resolve(paths.dataDir, "releases"));
+        await ensureSupervisor(retained, environment);
+        return await launchUi(retained, environment, sessionArgs);
+    };
+    const duringUpdate = await launchDuringUpdate();
+    if (duringUpdate !== null)
+        return duringUpdate;
     // Invariant: records left by cohorts whose processes are gone say nothing about ownership, and there
     // can now be several of them. Clearing them first keeps the decision below about what is
     // actually running.
@@ -80,10 +97,8 @@ export async function runBootstrap(options) {
                 return verified;
             });
             await markStartupPhase(environment, "durable-validation-complete");
-            const retainedPaths = resolveCohortEndpoint(paths, retained.releaseId, environment);
             await markStartupPhase(environment, "replacement-supervisor-start");
-            const startup = await startSupervisor(retained, environment);
-            await waitForVerifiedEndpoint(retainedPaths.endpointMetadataPath, retained, 8_000, startup);
+            await ensureSupervisor(retained, environment);
             await markStartupPhase(environment, "replacement-supervisor-ready");
             return await launchUi(retained, environment, sessionArgs);
         }
@@ -102,6 +117,10 @@ export async function runBootstrap(options) {
             throw error;
         return fallback;
     }
+    // Concurrency: an update may have begun while this launch was reading the installed payload.
+    const afterMaterialization = await launchDuringUpdate();
+    if (afterMaterialization !== null)
+        return afterMaterialization;
     await stateStore.recordCandidate(candidate);
     state = await stateStore.read();
     if (!state.references.active) {
@@ -192,8 +211,7 @@ export async function runBootstrap(options) {
     else {
         selected = await readMaterializedRelease(decision.releaseRoot);
     }
-    const startup = await startSupervisor(selected, environment);
-    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, selected.releaseId, environment).endpointMetadataPath, selected, 8_000, startup);
+    await ensureSupervisor(selected, environment);
     return await launchUi(selected, environment, sessionArgs);
 }
 /**
@@ -209,14 +227,7 @@ async function launchRetainedActive(state, paths, environment, sessionArgs, outp
         return null;
     try {
         const retained = await readCertifiedReleaseManifest(active, resolve(paths.dataDir, "releases"));
-        const retainedPaths = resolveCohortEndpoint(paths, retained.releaseId, environment);
-        const endpoint = await readEndpointMetadata(retainedPaths.endpointMetadataPath);
-        if (!endpoint || await probeOwnership(endpoint) !== "live-verified") {
-            if (endpoint)
-                await removeEndpointArtifacts(retainedPaths.endpointMetadataPath, retainedPaths.endpoint);
-            const startup = await startSupervisor(retained, environment);
-            await waitForVerifiedEndpoint(retainedPaths.endpointMetadataPath, retained, 8_000, startup);
-        }
+        await ensureSupervisor(retained, environment);
         output.write(`${PRODUCT_TEXT.diagnostic(`installation is being replaced; starting the retained release ${retained.packageVersion}`)}\n`);
         return await launchUi(retained, environment, sessionArgs);
     }
@@ -246,6 +257,25 @@ export async function recordParentCertifiedRelease(release, dataDir) {
     await chmod(path, 0o400);
     return path;
 }
+/** 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);
+}
+function endpointMatchesRelease(metadata, release) {
+    return metadata.releaseId === release.releaseId && metadata.releaseRoot === release.releaseRoot
+        && metadata.contentDigest === release.contentDigest;
+}
 export async function startSupervisor(release, environment) {
     const entry = await resolveReleaseEntryPoint(release, "bin/supervisor.js");
     const paths = resolveProductPaths(environment);
@@ -296,10 +326,11 @@ export function releaseEnvironment(environment, release, profile) {
 export async function waitForVerifiedEndpoint(path, release, timeoutMs, startup) {
     const deadline = Date.now() + timeoutMs;
     let childOutcome = null;
+    let collision = null;
     void startup?.childOutcome.then(outcome => { childOutcome = outcome; });
     while (Date.now() < deadline) {
         const metadata = await readEndpointMetadata(path);
-        if (metadata && metadata.releaseId === release.releaseId && await probeOwnership(metadata) === "live-verified") {
+        if (metadata && endpointMatchesRelease(metadata, release) && await probeOwnership(metadata) === "live-verified") {
             if (startup)
                 await rm(startup.resultPath, { force: true });
             return;
@@ -307,15 +338,21 @@ export async function waitForVerifiedEndpoint(path, release, timeoutMs, startup)
         if (startup) {
             const result = await readSupervisorStartupResult(startup.resultPath, startup.attemptId, startup.releaseId);
             if (result?.outcome === "failure") {
-                throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor startup failed at ${result.stage}: ${result.message}`)), {
+                const error = Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor startup failed at ${result.stage}: ${result.message}`)), {
                     code: result.code ?? "SUPERVISOR_STARTUP_FAILED",
                 });
+                if (result.code !== "EADDRINUSE")
+                    throw error;
+                // Concurrency: the winning process may not have published its authenticated metadata yet.
+                collision = error;
             }
         }
-        if (childOutcome)
+        if (childOutcome && !collision)
             throw new Error(PRODUCT_TEXT.diagnostic(`supervisor exited before readiness: ${JSON.stringify(childOutcome)}`));
         await new Promise(resolvePromise => setTimeout(resolvePromise, 40));
     }
+    if (collision)
+        throw collision;
     throw new Error(PRODUCT_TEXT.diagnostic(`supervisor did not publish verified endpoint metadata within ${timeoutMs}ms`));
 }
 export async function readEndpointMetadata(path) {
@@ -410,8 +447,7 @@ async function activatePendingAfterBlockerExit(candidate, stateStore, paths, env
         return;
     await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
     await stateStore.activate(candidate.releaseId);
-    const startup = await startSupervisor(candidate, environment);
-    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000, startup);
+    await ensureSupervisor(candidate, environment);
 }
 export async function releaseVerifiedIdleOwner(metadata, dataDir, operations = {}) {
     try {

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

@@ -10,6 +10,7 @@ export * from "./release-store.js";
 export * from "./restart-certification.js";
 export * from "./stable-release.js";
 export * from "./update.js";
+export * from "./update-launch.js";
 export * from "./update-recovery.js";
 export * from "./update-transaction.js";
 export * from "./warmup.js";

package/dist/foundation/release/index.js

@@ -10,6 +10,7 @@ export * from "./release-store.js";
 export * from "./restart-certification.js";
 export * from "./stable-release.js";
 export * from "./update.js";
+export * from "./update-launch.js";
 export * from "./update-recovery.js";
 export * from "./update-transaction.js";
 export * from "./warmup.js";

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

@@ -0,0 +1,6 @@
+import type { CohortState, ReleaseRecord } from "./cohort-state.js";
+import type { UpdateTransaction } from "./update-transaction.js";
+/** Keep interactive launches on the last successful release until the update commits success. */
+export declare function selectUpdateLaunchRelease(state: CohortState, transaction: UpdateTransaction | null): ReleaseRecord | null;
+/** Pause cohort retirement during preparation; afterward only the successful launch release admits new sessions. */
+export declare function selectSupervisorLaunchReleaseId(state: CohortState, transaction: UpdateTransaction | null): string | null;

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

@@ -0,0 +1,17 @@
+/** Keep interactive launches on the last successful release until the update commits success. */
+export function selectUpdateLaunchRelease(state, transaction) {
+    if (transaction === null || transaction.status === "completed")
+        return null;
+    const prior = transaction.priorActiveReleaseId === null ? undefined : state.releases[transaction.priorActiveReleaseId];
+    if (!prior || prior.approval !== "approved") {
+        throw new Error("unfinished update has no verified previous release available for launch; resume the update");
+    }
+    return prior;
+}
+/** Pause cohort retirement during preparation; afterward only the successful launch release admits new sessions. */
+export function selectSupervisorLaunchReleaseId(state, transaction) {
+    // Concurrency: both the previous cohort and the warming candidate must remain available until cutover.
+    if (transaction?.status === "active")
+        return null;
+    return selectUpdateLaunchRelease(state, transaction)?.releaseId ?? state.references.active;
+}

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

@@ -112,5 +112,7 @@ export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end
  */
 export declare function planUpdateOwnership(ownership: "live-verified" | "dead", runsFromRetainedRelease: boolean): UpdateOwnershipAction;
 export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
+/** Renders the terminal-only update meter; the visual preview shares this exact frame. */
+export declare function renderUpdateProgressBar(percent: number): string;
 export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
 export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;

package/dist/foundation/release/update.js

@@ -5,7 +5,7 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
 import crossSpawn from "cross-spawn";
 import { valid as validSemver } from "semver";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
-import { certifyMaterializedRelease, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, startSupervisor, waitForProcessExit, waitForVerifiedEndpoint, } from "./bootstrap.js";
+import { certifyMaterializedRelease, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, ensureSupervisor, waitForProcessExit, } from "./bootstrap.js";
 import { resolveCohortEndpoint, resolveProductPaths } from "../lifecycle/index.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { CohortStateStore } from "./cohort-state.js";
@@ -163,17 +163,17 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             const diagnostics = await certifyMaterializedRelease(candidate, paths.dataDir);
             await stateStore.approve(candidate.releaseId, diagnostics);
             await phase("certified");
-            await stateStore.activate(candidate.releaseId);
-            await phase("active-reference-committed");
             onWarmup?.("started");
             await warmMaterializedRelease(candidate, environment);
             onWarmup?.("completed");
-            const startup = await startSupervisor(candidate, environment);
-            await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000, startup);
+            await ensureSupervisor(candidate, environment);
+            // Invariant: warmup and authenticated readiness precede changing the active reference.
+            await stateStore.activate(candidate.releaseId);
+            await phase("active-reference-committed");
         },
     };
 }
-const PROGRESS_BAR_WIDTH = 39;
+const PROGRESS_BAR_WIDTH = 40;
 const PROGRESS_TICK_MS = 200;
 /**
  * Copying the release owns 78–92 and is reported file by file, so the bar crosses
@@ -186,10 +186,15 @@ const ACTIVATION_PROGRESS = {
     certified: { at: 94, creepTo: 96 },
     "active-reference-committed": { at: 96, creepTo: 99 },
 };
-function renderProgressBar(percent) {
+/** Renders the terminal-only update meter; the visual preview shares this exact frame. */
+export function renderUpdateProgressBar(percent) {
     const bounded = Math.min(100, Math.max(0, Math.round(percent)));
     const filled = Math.round((bounded / 100) * PROGRESS_BAR_WIDTH);
-    return `${"█".repeat(filled)}${"░".repeat(PROGRESS_BAR_WIDTH - filled)} ${bounded}%`;
+    // Rationale: a gray line, a darker gray track, and one space before the percentage.
+    // Explicit RGB keeps both grays neutral even when the terminal remaps its ANSI palette.
+    const gray = "\u001b[38;2;128;128;128m";
+    const track = "\u001b[38;2;102;102;102m";
+    return `${gray}${"━".repeat(filled)}${track}${"─".repeat(PROGRESS_BAR_WIDTH - filled)}${gray} ${bounded}%\u001b[39m`;
 }
 function createUpdateProgress(output, enabled) {
     let visible = false;
@@ -202,7 +207,7 @@ function createUpdateProgress(output, enabled) {
             return;
         shown = rounded;
         visible = true;
-        output.stdout(`\r${renderProgressBar(rounded)}`);
+        output.stdout(`\r${renderUpdateProgressBar(rounded)}`);
     };
     const stopCreep = () => {
         if (timer !== null) {
@@ -375,11 +380,7 @@ export async function runSelfUpdate(options) {
         : async () => await scheduleReleaseCleanup(paths.dataDir, paths));
     let transaction = await transactionStore.read();
     try {
-        if (await lifecycle.targetIsActive(targetVersion)) {
-            if (transaction?.status === "active") {
-                await transactionStore.advance("supervisor-verified");
-                await transactionStore.finish("completed");
-            }
+        if ((!transaction || transaction.status === "completed") && await lifecycle.targetIsActive(targetVersion)) {
             await maintenance();
             await transactionStore.clearCompleted();
             output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
@@ -510,13 +511,14 @@ export async function runSelfUpdate(options) {
         options.onPhaseTiming?.({ phase: "supervisor-verified", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
         const transactionStartedAt = now();
         await transactionStore.advance("supervisor-verified");
-        await transactionStore.finish("completed");
         if (transaction.recovery?.capsulePath)
             await removeUpdateRecoveryCapsule(paths.dataDir, transaction.transactionId);
         // Invariant: successful output follows the durable cleanup disposition. Slow recursive
         // removal belongs to the detached worker started by this maintenance coordinator.
         await maintenance();
-        await transactionStore.clearCompleted();
+        // Concurrency: this is the launch cutover. No failure-prone update work follows success.
+        await transactionStore.finish("completed");
+        await transactionStore.clearCompleted().catch(() => undefined);
         options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
         progress.finish();
         output.stdout(`${PRODUCT_TEXT.commandName} updated successfully: ${targetVersion}\n`);
@@ -609,11 +611,8 @@ async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
             throw new Error(`prior release ${priorReleaseId} is not the recorded rollback cohort`);
     }
     const release = await readMaterializedRelease(prior.releaseRoot);
-    const paths = resolveProductPaths(environment);
-    // Invariant: rollback re-points the active reference and starts the prior cohort on its own endpoint;
-    // a cohort that survived the update keeps serving the work it already had.
-    const startup = await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, release.releaseId, environment).endpointMetadataPath, release, 8_000, startup);
+    // Invariant: rollback reuses a surviving prior cohort rather than racing its occupied endpoint.
+    await ensureSupervisor(release, environment);
     return "rolled back";
 }
 function phaseBefore(current, target) {

package/dist/foundation/supervision/main.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
-import { assertImmutableExecutionRoot, CohortStateStore, readCertifiedReleaseManifest, recordParentCertifiedRelease } from "../release/index.js";
+import { assertImmutableExecutionRoot, CohortStateStore, readCertifiedReleaseManifest, recordParentCertifiedRelease, selectSupervisorLaunchReleaseId, UpdateTransactionStore } from "../release/index.js";
 import { publishSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath } from "../lifecycle/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
@@ -38,7 +38,10 @@ export async function runSupervisor(arguments_ = []) {
         const bootNonce = randomUUID();
         const store = new ControlStore(paths.databasePath, bootNonce);
         const cohortState = new CohortStateStore(paths.dataDir);
-        server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => (await cohortState.read()).references.active);
+        server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => {
+            const transaction = await new UpdateTransactionStore(paths.dataDir).read();
+            return selectSupervisorLaunchReleaseId(await cohortState.read(), transaction);
+        });
         stage = "endpoint-listen";
         await server.listen();
         if (resultPath && attemptId)

package/dist/foundation/supervision/server.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createConnection, createServer } from "node:net";
 import { platform } from "node:os";
 import { dirname } from "node:path";
@@ -54,6 +54,7 @@ export class SupervisorServer {
     startedAt = new Date().toISOString();
     paths;
     #server = null;
+    #ownsEndpoint = false;
     #instances = new Map();
     #instanceOwners = new Map();
     #clientIds = new Map();
@@ -104,15 +105,24 @@ export class SupervisorServer {
         if (platform() !== "win32") {
             if (this.paths.endpointDirectory)
                 await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
-            if (await endpointIsLive(this.paths.endpoint))
-                throw new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`));
-            await rm(this.paths.endpoint, { force: true });
+            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 });
+            }
         }
         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();
             });
@@ -146,7 +156,9 @@ export class SupervisorServer {
         await this.close(false);
     }
     async close(stopAgents = false) {
-        if (stopAgents && !await this.#drainInstances("update", this.shutdownDeadlineMs)) {
+        if (this.#closing)
+            return;
+        if (stopAgents && this.#ownsEndpoint && !await this.#drainInstances("update", this.shutdownDeadlineMs)) {
             throw new Error("active launch instances did not release ownership within the shutdown deadline");
         }
         this.#closing = true;
@@ -155,14 +167,27 @@ export class SupervisorServer {
         this.#supersededPoll = null;
         for (const client of this.#clients)
             client.destroy();
-        if (this.#server)
-            await new Promise(resolve => this.#server?.close(() => resolve()));
-        this.#server = null;
-        this.store.close();
-        await this.#metadataWrites;
-        await rm(this.paths.endpointMetadataPath, { force: true });
-        if (platform() !== "win32")
-            await rm(this.paths.endpoint, { force: true });
+        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.
+            }
+        }
+        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);
@@ -473,6 +498,8 @@ export class SupervisorServer {
         return [...this.#instances.keys()];
     }
     #writeEndpointMetadata() {
+        if (this.#closing)
+            return Promise.resolve();
         const liveInstanceIds = this.#liveInstanceIds();
         const metadata = {
             schema: PRODUCT_IDENTITY.protocol.supervisorSchema,

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

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-09-12T13:59:03.140Z",
+  "builtAt": "2026-09-12T16:36:02.575Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "9db1726bbe3fc2e8292f2ead1e7e9d0fd4d7d0dc9217b372582bf354b0f565dc",

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

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-12T13:58:54.058Z",
+  "builtAt": "2026-09-12T16:36:05.106Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "d8cda6b0c7cb36c0cc41e90802aceebf6c02eaebbc08a83d7d963d2e918dbd7a",

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

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-12T13:59:34.009Z",
+  "builtAt": "2026-09-12T16:36:30.210Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "15e00144629345d7f00b110494775b80c65e6e575e6758d88b533c25b57d35d5",
+    "sha256": "0bc42bc571ebdcf244d60f42d03472a2dd57da4984b1d39931f9a2ad3787cde5",
     "size": 177664
   },
   "provenance": {

package/docs/architecture/toolchain.md

@@ -71,7 +71,7 @@ Presentation acceptance is the reader comparing `a1 pi` with pinned Pi. `node sc
 
 ## Publication
 
-One workflow publishes both channels: `.github/workflows/release.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` explicitly requests a numbered preview and `npm run release` explicitly requests stable publication after its version pull request merges. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack once and are validated on Windows, Linux, and macOS; a repeated nightly verifies the exact immutable registry tarball. All publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and the stable tag, GitHub Release, and `master` are written only after npm has the package. One global non-cancelling concurrency group serializes the final registry check.
+One workflow publishes both channels: `.github/workflows/release.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` explicitly requests a numbered preview and `npm run release -- patch` explicitly requests stable publication after its version pull request is manually merged; it promotes a development version to its stable core. The following development-version pull request also requires manual merge. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack once and are validated on Windows, Linux, and macOS; a repeated nightly verifies the exact immutable registry tarball. All publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and the stable tag, GitHub Release, and `master` are written only after npm has the package. One global non-cancelling concurrency group serializes the final registry check.
 
 `docs/ci-release-runbook.md` is the operational reference.
 

package/docs/ci-release-runbook.md

@@ -166,15 +166,40 @@ work.
 
 ## Cutting a stable release
 
-From a clean `develop` matching its remote:
+From the repository root on clean `develop` matching `origin/develop`:
 
 ```sh
-npm run release -- patch     # or minor, major, or an exact x.y.z
+npm run release -- patch     # 0.1.8-dev -> 0.1.8; already-stable 0.1.8 -> 0.1.9
+npm run release -- minor     # 0.1.8-dev -> 0.2.0
+npm run release -- major     # 0.1.8-dev -> 1.0.0
+npm run release -- 0.4.0     # exact stable target
 ```
 
-The command lands `x.y.z` through its version pull request, explicitly dispatches
-stable publication for that exact current `origin/develop` commit, and waits. Only
-after success does it land `x.y.(z+1)-dev`.
+A target is required: `npm run release` alone is a mutation-free usage error.
+`patch` preserves prerelease-aware semantics, including `0.1.8-dev.123 -> 0.1.8`.
+The command reports its source, stable target, and prospective reopening before
+preparing anything.
+
+1. The stable-version edit is committed in an owned detached worktree beneath
+   `.worktrees/`. Only this package's manifest and root lockfile version change.
+2. Follow the printed PR URL, wait for required CI, perform local validation, and
+   **merge manually after acceptance**. The helper does not merge PRs or enable
+   auto-merge. It polls for actual merge with a bounded 30-minute wait.
+3. The helper verifies the merged version and source SHA against authoritative
+   develop, then explicitly dispatches stable publication for that exact source.
+   A changed source is an error, not permission to substitute a newer commit.
+4. Only after verified publication of `0.1.8` does it prepare a separate PR for
+   `0.1.9-dev`. Validate and manually merge that PR as well. Until then the helper
+   reports development reopening as incomplete.
+
+Closed PRs, timeout, cancellation, and query failures retain identifiable phase
+work for inspection. Conflicting existing branches/PRs are not overwritten;
+matching pending PRs can be observed again without replacing them. Worktrees
+retained by an earlier attempt are not removed by a later invocation. Cleanup
+only removes clean, owned, confirmed-merged phase worktrees and unchanged remote
+phase branches. The caller is never hard-reset: a final fast-forward is attempted
+only when its branch, original HEAD, and cleanliness remain unchanged. Otherwise
+preserve local work and synchronize manually with the reported remote state.
 
 Stable publication builds the process guardian on all supported platforms, packs
 once, runs the complete suite against those exact bytes on Windows, Linux, and
@@ -200,8 +225,21 @@ Rules that do not bend:
   path, and use the confirmed apply mode only for an accepted mutable policy change.
 - **Nightly documentation review fails:** inspect the reported paths and rules, identify the introducing merge from the nightly interval, and repair the invariant before unrelated work proceeds.
 - **Development publication fails:** fix the cause and rerun `npm run develop`; an npm version that already exists is never overwritten.
-- **Stable publication fails before npm accepts bytes:** no tag, release, or moved branch exists. Fix the cause and release the next version.
-- **Stable publication is uncertain after npm accepted bytes:** stop and inspect registry version, digest, tag, and release. Never republish immutable bytes.
+- **Stable preparation stops before dispatch:** inspect the reported version PR/worktree. After preserving work, an exact matching pending PR can be observed again. If develop already declares the prepared stable version, use its exact target (for example `npm run release -- 0.1.8`) only after verifying that source's merged PR and confirming the registry/tag guards still permit it. Do not use `patch` from stable develop to retry the same version: that deliberately selects the next patch.
+- **Stable publication fails or is uncertain:** inspect the workflow, registry version/digest, tag, and release before choosing recovery. No reopening PR is prepared. Never republish immutable bytes or move a release tag.
+- **Stable publication succeeded but reopening stops:** the stable version is already published. Inspect and finish the reported next-development PR manually; do not repeat stable publication. If no reopening PR was created, prepare the next-development version through a separately validated manual PR after inspecting remote state.
+
+## Safe release-command validation
+
+Use the isolated harness rather than a live release to validate changes to this command:
+
+```sh
+npm exec --no -- vitest run test/repository-governance/release-target.test.ts test/repository-governance/release-command.test.ts --maxWorkers=1 --minWorkers=1
+```
+
+It uses disposable local Git repositories and fake GitHub, registry, and publication
+services. It does not publish a package or create production version PRs. A real
+release remains a separate deliberate operation.
 
 ## Branch protection rationale
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.332",
+  "version": "0.1.8-dev.335",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",