@timurproko/a1 0.1.8-dev.0b6d8cc → 0.1.8-dev.121

package/dist/{src/foundation → foundation}/release/update.js

@@ -6,7 +6,7 @@ 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 { resolveProductPaths } from "../lifecycle/index.js";
+import { resolveCohortEndpoint, resolveProductPaths } from "../lifecycle/index.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { CohortStateStore } from "./cohort-state.js";
 import { cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
@@ -20,7 +20,7 @@ const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
  * a release, and that is the word the repository, its tags, and its GitHub
  * releases all use.
  */
-const UPDATE_CHANNEL_LABELS = { stable: "release", next: "next" };
+const UPDATE_CHANNEL_LABELS = { stable: "release", next: "develop" };
 const defaultFileSystem = {
     async readFile(path) { return await readFile(path, "utf8"); },
     realpath,
@@ -47,6 +47,33 @@ 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.
+ */
+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) {
     const paths = resolveProductPaths(environment);
     const stateStore = new CohortStateStore(paths.dataDir);
@@ -56,45 +83,54 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             const activeId = state.references.active;
             if (!activeId || state.releases[activeId]?.packageVersion !== targetVersion)
                 return false;
-            const endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-            return endpoint?.releaseId === activeId && await probeOwnership(endpoint) === "live-verified";
+            const endpoint = await readActiveEndpoint(paths, activeId, environment);
+            return endpoint?.metadata.releaseId === activeId && await probeOwnership(endpoint.metadata) === "live-verified";
         },
         async shutdownVerifiedOwners(targetVersion) {
             const state = await stateStore.read();
-            const priorActiveVersion = state.references.active ? state.releases[state.references.active]?.packageVersion ?? null : null;
-            const endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-            if (!endpoint)
+            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 immutableRoot = await canonicalImmutableRoot(paths.dataDir, endpoint.releaseRoot);
-            const legacyMutableInstall = ownership === "live-verified" && !immutableRoot;
-            const identity = ownership === "dead"
-                ? { accepted: false, reason: "recorded owner is dead" }
-                : await requestUpdateShutdown(endpoint, targetVersion, 2_000);
+            const plan = planUpdateOwnership(ownership, await canonicalImmutableRoot(paths.dataDir, endpoint.releaseRoot));
+            if (plan === "clean-dead-record") {
+                await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint);
+                return { priorActiveVersion };
+            }
+            if (plan === "leave-running") {
+                const running = endpoint.ownership.liveInstanceIds.length;
+                if (running > 0) {
+                    output.stdout(`${PRODUCT_TEXT.commandName} update: leaving ${running === 1 ? "one session" : `${running} sessions`} running on ${endpoint.releaseId}\n`);
+                }
+                return { priorActiveVersion };
+            }
+            // 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)) {
                 // 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: legacyMutableInstall ? "legacy-mutable-install" : "explicit-update",
-                });
+                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: legacyMutableInstall ? "legacy-mutable-install" : "explicit-update",
-                    });
+                    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(paths.endpointMetadataPath, paths.endpoint);
+            await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint);
             return { priorActiveVersion };
         },
         async verifyPackageUnlocked(packageRoot) {
@@ -137,7 +173,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             await stateStore.activate(candidate.releaseId);
             await phase("active-reference-committed");
             await startSupervisor(candidate, environment);
-            await waitForVerifiedEndpoint(paths.endpointMetadataPath, candidate, 8_000);
+            await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000);
         },
     };
 }
@@ -223,12 +259,13 @@ function createUpdateProgress(output, enabled) {
 }
 /** The newest version the channel points at, which is what an unqualified update takes. */
 async function resolveChannelHead(runner, distTag, output) {
-    const lookup = await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${distTag} channel`);
+    const publicChannel = distTag === "next" ? "development" : "release";
+    const lookup = await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${publicChannel} channel`);
     if (lookup.result === null)
         return { version: null, exitCode: lookup.exitCode };
     const version = validSemver(lookup.result.stdout.trim());
     if (version === null) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed ${distTag} version from npm: ${JSON.stringify(lookup.result.stdout.trim())}.`)}\n`);
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed ${publicChannel} channel version from npm: ${JSON.stringify(lookup.result.stdout.trim())}.`)}\n`);
         return { version: null, exitCode: 1 };
     }
     return { version, exitCode: 0 };
@@ -236,14 +273,10 @@ async function resolveChannelHead(runner, distTag, output) {
 /**
  * Resolve a preview the caller named.
  *
- * A preview is published as `<version>-dev.<commit>`, so its commit is enough to
- * say which one is wanted — the version in front of it is not something anyone
- * should have to remember. A full version is accepted too, for anyone reading one
- * back from `a1 version` or a changelog.
- *
- * The published list is the authority: naming a commit that was never published,
- * or one published more than once under different versions, is an error rather
- * than a guess.
+ * A preview is published as `<version>-dev.<pull-request-number>`, so its decimal
+ * development number is enough to identify it. A full version is accepted too.
+ * The published list remains authoritative: nothing is constructed from the
+ * installed package's base version.
  */
 async function resolveRequestedPreview(runner, requested, output) {
     const lookup = await runNpm(runner, ["view", PRODUCT_PACKAGE, "versions", "--json"], true, output, "list the published versions");
@@ -261,8 +294,7 @@ async function resolveRequestedPreview(runner, requested, output) {
     const exact = versions.find(version => version === requested);
     if (exact !== undefined) {
         // Naming a release here would install it through the preview path, which is a
-        // different command with a different meaning. The commit form cannot express
-        // one, so only the fuller spelling of a preview reaches this.
+        // different command with a different meaning.
         if (!exact.includes("-dev.")) {
             output.stderr(`${PRODUCT_TEXT.diagnostic(`${exact} is a release, not a preview; run ${PRODUCT_TEXT.commandName} update to move to the current release.`)}\n`);
             return { version: null, exitCode: 1 };
@@ -495,8 +527,10 @@ async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
     }
     const release = await readMaterializedRelease(prior.releaseRoot);
     const paths = resolveProductPaths(environment);
+    // 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.
     await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000);
+    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, release.releaseId, environment).endpointMetadataPath, release, 8_000);
     return "rolled back";
 }
 function phaseBefore(current, target) {

package/dist/{src/foundation → foundation}/storage/control-store.d.ts

@@ -1,5 +1,5 @@
 import { DatabaseSync } from "node:sqlite";
-import type { ManagedAgentDescriptor, PaneId, AgentRecoveryAuthority, RecoveryReferenceId, TerminalSessionLaunch, TerminalTopologySnapshot } from "../workspace-contracts/index.js";
+import type { ManagedAgentDescriptor, PaneId, AgentRecoveryAuthority, RecoveryReferenceId, TerminalSessionLaunch, TerminalTopologySnapshot } from "../../contracts/workspace/index.js";
 import type { LaunchInstance, LaunchInstanceId, LaunchInstanceOutcome, NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
 export declare const DEFAULT_WORKSPACE_ID = "workspace-default";
 export interface WorkspaceAgentPresentation {

package/dist/{src/foundation → foundation}/storage/control-store.js

@@ -2,7 +2,7 @@ import { DatabaseSync } from "node:sqlite";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { assertManagedAgentDescriptor, assertRecoveryAuthority, assertTerminalSessionLaunch, assertTerminalTopologySnapshot, } from "../workspace-contracts/index.js";
+import { assertManagedAgentDescriptor, assertRecoveryAuthority, assertTerminalSessionLaunch, assertTerminalTopologySnapshot, } from "../../contracts/workspace/index.js";
 import { assertLaunchInstance, assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
 export const DEFAULT_WORKSPACE_ID = "workspace-default";
 const INITIAL_WORKSPACE_ID = DEFAULT_WORKSPACE_ID;

package/dist/{src/foundation → foundation}/structured-agent-runtime/backpressure.d.ts

@@ -1,4 +1,4 @@
-import { type StructuredCapabilityContract } from "../workspace-contracts/index.js";
+import { type StructuredCapabilityContract } from "../../contracts/workspace/index.js";
 export type StructuredBackpressureResource = "events" | "commands" | "snapshots" | "attachments" | "reconnect-replay";
 export type StructuredBackpressureAction = "none" | "reject-payload" | "pause-adapter" | "reject-request" | "disconnect-adapter";
 export interface StructuredResourceLease {

package/dist/{src/foundation → foundation}/structured-agent-runtime/backpressure.js

@@ -1,4 +1,4 @@
-import { assertStructuredCapability, } from "../workspace-contracts/index.js";
+import { assertStructuredCapability, } from "../../contracts/workspace/index.js";
 export class StructuredBackpressureController {
     adapterId;
     #budgets;

package/dist/{src/foundation → foundation}/structured-agent-runtime/commands.d.ts

@@ -1,4 +1,4 @@
-import { type StructuredCapabilityContract, type WorkspaceCommand } from "../workspace-contracts/index.js";
+import { type StructuredCapabilityContract, type WorkspaceCommand } from "../../contracts/workspace/index.js";
 export type StructuredCommandRequest = Extract<WorkspaceCommand, {
     readonly type: "structured-command";
 }>;

package/dist/{src/foundation → foundation}/structured-agent-runtime/commands.js

@@ -1,4 +1,4 @@
-import { assertStructuredCapability, assertWorkspaceCommand, } from "../workspace-contracts/index.js";
+import { assertStructuredCapability, assertWorkspaceCommand, } from "../../contracts/workspace/index.js";
 export class StructuredCommandTracker {
     agentId;
     #capability;

package/dist/{src/foundation → foundation}/structured-agent-runtime/handshake.d.ts

@@ -1,4 +1,4 @@
-import { type AdapterId, type StructuredCapabilityContract, type StructuredFlowLimits } from "../workspace-contracts/index.js";
+import { type AdapterId, type StructuredCapabilityContract, type StructuredFlowLimits } from "../../contracts/workspace/index.js";
 export declare const STRUCTURED_ADAPTER_ENVELOPE: string;
 export declare const STRUCTURED_ADAPTER_ENVELOPE_REVISION: 1;
 export declare const REQUIRED_STRUCTURED_FEATURES: readonly ["identity.adapter.v1", "commands.correlated.v1", "events.typed.v1", "flow-control.limits.v1"];

package/dist/{src/foundation → foundation}/structured-agent-runtime/handshake.js

@@ -1,4 +1,4 @@
-import { WORKSPACE_CONTRACT_VERSION, assertStructuredCapability, } from "../workspace-contracts/index.js";
+import { WORKSPACE_CONTRACT_VERSION, assertStructuredCapability, } from "../../contracts/workspace/index.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export const STRUCTURED_ADAPTER_ENVELOPE = PRODUCT_IDENTITY.protocol.structuredAgentSchema;
 export const STRUCTURED_ADAPTER_ENVELOPE_REVISION = 1;

package/dist/{src/foundation → foundation}/structured-agent-runtime/reconnection.d.ts

@@ -1,4 +1,4 @@
-import { type AgentRecoveryAuthority, type StructuredAgentSnapshot, type StructuredCapabilityContract, type StructuredRecoveryAuthority } from "../workspace-contracts/index.js";
+import { type AgentRecoveryAuthority, type StructuredAgentSnapshot, type StructuredCapabilityContract, type StructuredRecoveryAuthority } from "../../contracts/workspace/index.js";
 import { StructuredEventReducer, type StructuredRuntimeView } from "./state.js";
 export interface StructuredResumeProof {
     readonly protocolVersion: number;

package/dist/{src/foundation → foundation}/structured-agent-runtime/reconnection.js

@@ -1,4 +1,4 @@
-import { WORKSPACE_CONTRACT_VERSION, assertRecoveryAuthority, assertStructuredAgentSnapshot, assertStructuredCapability, } from "../workspace-contracts/index.js";
+import { WORKSPACE_CONTRACT_VERSION, assertRecoveryAuthority, assertStructuredAgentSnapshot, assertStructuredCapability, } from "../../contracts/workspace/index.js";
 import { StructuredEventReducer } from "./state.js";
 export class StructuredReconnectionManager {
     #capability;

package/dist/{src/foundation → foundation}/structured-agent-runtime/state.d.ts

@@ -1,4 +1,4 @@
-import { type StructuredAgentSnapshot, type StructuredCapabilityContract, type WorkspaceEvent } from "../workspace-contracts/index.js";
+import { type StructuredAgentSnapshot, type StructuredCapabilityContract, type WorkspaceEvent } from "../../contracts/workspace/index.js";
 export type StructuredAgentEvent = Extract<WorkspaceEvent, {
     readonly type: "structured-event";
 }>;

package/dist/{src/foundation → foundation}/structured-agent-runtime/state.js

@@ -1,4 +1,4 @@
-import { assertStructuredAgentSnapshot, assertStructuredCapability, assertWorkspaceEvent, } from "../workspace-contracts/index.js";
+import { assertStructuredAgentSnapshot, assertStructuredCapability, assertWorkspaceEvent, } from "../../contracts/workspace/index.js";
 export class StructuredEventReducer {
     agentId;
     #capability;

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

@@ -0,0 +1,3 @@
+export * from "./main.js";
+export * from "./server.js";
+export { resolveCohortEndpoint, resolveProductPaths, type CohortEndpointPaths, type ProductPaths } from "../lifecycle/index.js";

package/dist/foundation/supervision/index.js

@@ -0,0 +1,3 @@
+export * from "./main.js";
+export * from "./server.js";
+export { resolveCohortEndpoint, resolveProductPaths } from "../lifecycle/index.js";

package/dist/{src/foundation → foundation}/supervision/main.js

@@ -1,14 +1,16 @@
 import { randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
-import { assertImmutableExecutionRoot, readCertifiedReleaseManifest } from "../release/index.js";
+import { assertImmutableExecutionRoot, CohortStateStore, readCertifiedReleaseManifest } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
-import { resolveProductPaths } from "./paths.js";
+import { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
 import { SupervisorServer } from "./server.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export async function runSupervisor() {
-    const paths = resolveProductPaths();
-    mkdirSync(paths.runtimeDir, { recursive: true, mode: 0o700 });
+    const productPaths = resolveProductPaths();
+    mkdirSync(productPaths.runtimeDir, { recursive: true, mode: 0o700 });
+    mkdirSync(productPaths.endpointsDir, { recursive: true, mode: 0o700 });
+    let paths = productPaths;
     const log = (message) => appendFileSync(paths.supervisorLogPath, `${new Date().toISOString()} ${message}\n`);
     const releaseRoot = process.env[PRODUCT_IDENTITY.environment.releaseRoot];
     const releaseId = process.env[PRODUCT_IDENTITY.environment.releaseId];
@@ -17,9 +19,13 @@ export async function runSupervisor() {
         throw new Error(PRODUCT_TEXT.diagnostic("supervisor must be launched from a verified immutable release"));
     const release = await readCertifiedReleaseManifest({ releaseRoot, releaseId, contentDigest }, resolve(paths.dataDir, "releases"));
     await assertImmutableExecutionRoot(release, paths.dataDir);
+    // One endpoint per cohort: a superseded cohort keeps serving what it already has while the
+    // installed release listens on its own address.
+    paths = { ...productPaths, ...resolveCohortEndpoint(productPaths, release.releaseId) };
     const bootNonce = randomUUID();
     const store = new ControlStore(paths.databasePath, bootNonce);
-    const server = new SupervisorServer(store, paths, release, bootNonce);
+    const cohortState = new CohortStateStore(paths.dataDir);
+    const server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => (await cohortState.read()).references.active);
     await server.listen();
     log(`supervisor ${server.id} listening at ${paths.endpoint} (pid ${process.pid})`);
     let closing = false;

package/dist/foundation/supervision/paths.d.ts

@@ -0,0 +1 @@
+export { resolveCohortEndpoint, resolveProductPaths, type CohortEndpointPaths, type ProductPaths, } from "../lifecycle/index.js";

package/dist/foundation/supervision/paths.js

@@ -0,0 +1 @@
+export { resolveCohortEndpoint, resolveProductPaths, } from "../lifecycle/index.js";

package/dist/{src/foundation → foundation}/supervision/server.d.ts

@@ -9,14 +9,31 @@ export declare class SupervisorServer {
     readonly terminateProcess: (code: number) => void;
     readonly reconciliationDeadlineMs: number;
     readonly shutdownDeadlineMs: number;
+    /**
+     * Which release new sessions start on. A cohort that is no longer that release keeps
+     * serving the instances it already has, takes no new ones, and exits when its last one
+     * leaves. Absent, this supervisor never considers itself superseded.
+     */
+    readonly readActiveReleaseId: (() => Promise<string | null>) | null;
+    readonly supersededPollMs: number;
     readonly id: `${string}-${string}-${string}-${string}-${string}`;
     readonly bootNonce: string;
     readonly pidStartIdentity: string;
     readonly startedAt: string;
     readonly paths: ProductPaths;
-    constructor(store: ControlStore, paths: ProductPaths | undefined, release: MaterializedRelease, bootNonce?: string, terminateProcess?: (code: number) => void, reconciliationDeadlineMs?: number, shutdownDeadlineMs?: number);
+    constructor(store: ControlStore, paths: ProductPaths | undefined, release: MaterializedRelease, bootNonce?: string, terminateProcess?: (code: number) => void, reconciliationDeadlineMs?: number, shutdownDeadlineMs?: number, 
+    /**
+     * Which release new sessions start on. A cohort that is no longer that release keeps
+     * serving the instances it already has, takes no new ones, and exits when its last one
+     * leaves. Absent, this supervisor never considers itself superseded.
+     */
+    readActiveReleaseId?: (() => Promise<string | null>) | null, supersededPollMs?: number);
     snapshot(): SupervisorSnapshot;
     listen(): Promise<void>;
+    /** Whether new sessions start on some other release. */
+    get superseded(): boolean;
+    /** Leaves, taking this cohort's own endpoint artifacts with it. */
+    retire(): Promise<void>;
     close(stopAgents?: boolean): Promise<void>;
     closeForReleaseReplacement(stopAgents: boolean): Promise<void>;
 }

package/dist/{src/foundation → foundation}/supervision/server.js

@@ -14,6 +14,8 @@ export class SupervisorServer {
     terminateProcess;
     reconciliationDeadlineMs;
     shutdownDeadlineMs;
+    readActiveReleaseId;
+    supersededPollMs;
     id = randomUUID();
     bootNonce;
     pidStartIdentity = `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
@@ -31,12 +33,22 @@ export class SupervisorServer {
     #results = new Map();
     #metadataWrites = Promise.resolve();
     #closing = false;
-    constructor(store, paths = resolveProductPaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code), reconciliationDeadlineMs = 3_000, shutdownDeadlineMs = 1_500) {
+    #superseded = false;
+    #supersededPoll = null;
+    constructor(store, paths = resolveProductPaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code), reconciliationDeadlineMs = 3_000, shutdownDeadlineMs = 1_500, 
+    /**
+     * Which release new sessions start on. A cohort that is no longer that release keeps
+     * serving the instances it already has, takes no new ones, and exits when its last one
+     * leaves. Absent, this supervisor never considers itself superseded.
+     */
+    readActiveReleaseId = null, supersededPollMs = 1_000) {
         this.store = store;
         this.release = release;
         this.terminateProcess = terminateProcess;
         this.reconciliationDeadlineMs = reconciliationDeadlineMs;
         this.shutdownDeadlineMs = shutdownDeadlineMs;
+        this.readActiveReleaseId = readActiveReleaseId;
+        this.supersededPollMs = supersededPollMs;
         this.bootNonce = bootNonce;
         this.paths = paths;
         for (const instance of store.loadActiveLaunchInstances())
@@ -56,6 +68,7 @@ export class SupervisorServer {
         if (this.#server)
             throw new Error("supervisor is already listening");
         await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
+        await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
         if (platform() !== "win32") {
             if (await endpointIsLive(this.paths.endpoint))
                 throw new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`));
@@ -71,12 +84,44 @@ export class SupervisorServer {
             });
         });
         await this.#writeEndpointMetadata();
+        if (this.readActiveReleaseId) {
+            const poll = setInterval(() => void this.#refreshCohortRole(), this.supersededPollMs);
+            poll.unref();
+            this.#supersededPoll = poll;
+        }
+    }
+    /**
+     * Notices that another release has become the one new sessions start on. Nothing is
+     * interrupted by that: this cohort finishes what it is holding and then leaves.
+     */
+    async #refreshCohortRole() {
+        if (this.#closing || !this.readActiveReleaseId)
+            return;
+        const active = await this.readActiveReleaseId().catch(() => null);
+        if (active === null)
+            return;
+        this.#superseded = active !== this.release.releaseId;
+        if (this.#superseded && this.#instances.size === 0)
+            await this.retire();
+    }
+    /** Whether new sessions start on some other release. */
+    get superseded() {
+        return this.#superseded;
+    }
+    /** Leaves, taking this cohort's own endpoint artifacts with it. */
+    async retire() {
+        if (this.#closing)
+            return;
+        await this.close(false);
     }
     async close(stopAgents = false) {
         if (stopAgents && !await this.#drainInstances("update", this.shutdownDeadlineMs)) {
             throw new Error("active launch instances did not release ownership within the shutdown deadline");
         }
         this.#closing = true;
+        if (this.#supersededPoll)
+            clearInterval(this.#supersededPoll);
+        this.#supersededPoll = null;
         for (const client of this.#clients)
             client.destroy();
         if (this.#server)
@@ -197,6 +242,9 @@ export class SupervisorServer {
     #createLaunchInstance(command, socket, clientId) {
         assertNativeProcessIdentity(command.guardianIdentity);
         const existing = this.store.loadLaunchInstance(command.instanceId);
+        if (this.#superseded && !existing) {
+            throw new Error(PRODUCT_TEXT.diagnostic(`release ${this.release.releaseId} is no longer the release new sessions start on`));
+        }
         if (existing) {
             if (existing.ownerClientId !== clientId
                 || existing.profileId !== command.profileId
@@ -279,6 +327,9 @@ export class SupervisorServer {
         this.#uncertainInstances.delete(stored.id);
         this.#unbindOwner(stored.id, socket);
         this.#mutated();
+        // The last session on a superseded cohort has left; there is nothing here to keep.
+        if (this.#superseded && this.#instances.size === 0)
+            void this.retire();
     }
     #ownedInstance(instanceId, socket, clientId) {
         const instance = this.#instances.get(instanceId) ?? this.store.loadLaunchInstance(instanceId);

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/components.d.ts

@@ -1,4 +1,4 @@
-import type { OwnedUiTranscriptBlock } from "../owned-ui-contracts/index.js";
+import type { OwnedUiTranscriptBlock } from "../../../contracts/owned-ui/index.js";
 export declare function adaptPiUserMessage(block: OwnedUiTranscriptBlock, width: number): readonly string[];
 export declare function adaptPiAssistantMessage(block: OwnedUiTranscriptBlock, width: number): readonly string[];
 export declare function adaptPiToolExecution(block: OwnedUiTranscriptBlock, width: number, cwd: string): readonly string[];

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/conformance.js

@@ -2,9 +2,9 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AssistantMessageComponent, ExtensionSelectorComponent, initTheme, LoginDialogComponent, ModelSelectorComponent, SettingsSelectorComponent, ThemeSelectorComponent, ThinkingSelectorComponent, ToolExecutionComponent, UserMessageComponent, UserMessageSelectorComponent, VERSION, } from "@earendil-works/pi-coding-agent";
-import { OWNED_UI_CONTRACT_VERSION } from "../owned-ui-contracts/index.js";
+import { OWNED_UI_CONTRACT_VERSION } from "../../../contracts/owned-ui/index.js";
 import { createTuiFacade, validatedAssistantMessage } from "./shell-components.js";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { PRODUCT_IDENTITY } from "../../../product-identity.js";
 export class PiComponentConformanceError extends Error {
     stage;
     constructor(stage, cause) {

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/shell-extension-ui.d.ts

@@ -1,5 +1,5 @@
 import { type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import type { OwnedUiExtensionOverlayHandle, OwnedUiExtensionOverlayOptions } from "../owned-ui-contracts/index.js";
+import type { OwnedUiExtensionOverlayHandle, OwnedUiExtensionOverlayOptions } from "../../../contracts/owned-ui/index.js";
 import { type PiShellComponentPort, type PiShellEditorOptions } from "./shell-shared-facade.js";
 export interface PiExtensionUiBridgeHost {
     readonly runtime: Pick<PiShellEditorOptions, "getColumns" | "getRows" | "requestRender">;

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/shell-footer-status.d.ts

@@ -1,4 +1,4 @@
-import type { OwnedUiSessionViewModel } from "../owned-ui-contracts/index.js";
+import type { OwnedUiSessionViewModel } from "../../../contracts/owned-ui/index.js";
 import { type PiShellViewComponentPort, type PiShellStatusPort, type PiShellQueuedInputPort, type PiShellHeaderPort, type PiShellResourceEntry, type PiShellLoadedResourcesPort, type PiShellHeaderOptions, type PiShellEditorOptions } from "./shell-shared-facade.js";
 export declare function createPiShellHeader(options?: PiShellHeaderOptions): PiShellHeaderPort;
 export declare function createPiShellLoadedResources(resources: readonly PiShellResourceEntry[], initialExpanded?: boolean): PiShellLoadedResourcesPort;

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/shell-presenters-transcript.d.ts

@@ -1,5 +1,5 @@
 import { AssistantMessageComponent } from "@earendil-works/pi-coding-agent";
-import type { OwnedUiTranscriptBlock } from "../owned-ui-contracts/index.js";
+import type { OwnedUiTranscriptBlock } from "../../../contracts/owned-ui/index.js";
 import { type PiShellComponentPort, type PiShellExtensionRendererResolver, type PiShellTranscriptComponentPort } from "./shell-shared-facade.js";
 export interface PiShellSessionInfoPresentation {
     readonly sessionName?: string;

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/shell-presenters-transcript.js

@@ -1,7 +1,7 @@
 import { AssistantMessageComponent, BashExecutionComponent, CompactionSummaryMessageComponent, CustomMessageComponent, DynamicBorder, getMarkdownTheme, parseSkillBlock, ToolExecutionComponent, UserMessageComponent, } from "@earendil-works/pi-coding-agent";
 import { SkillInvocationMessageComponent, } from "./upstream/components/skill-invocation-message.js";
 import { Container, Markdown, Spacer, Text, } from "#pi-tui";
-import { PRODUCT_TEXT } from "../../product-identity.js";
+import { PRODUCT_TEXT } from "../../../product-identity.js";
 import { KeybindingsManager, } from "./upstream/adjacent/core/keybindings.js";
 import { PINNED_PI_LAYOUT, piTheme, } from "./theme.js";
 import { componentPort, createTuiFacade, ensureTheme, formatSessionTokens, isRecord, } from "./shell-shared-facade.js";

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/shell-selectors-dialogs.d.ts

@@ -1,5 +1,5 @@
 import { ModelSelectorComponent, type SessionInfo, type SettingsCallbacks, type SettingsConfig } from "@earendil-works/pi-coding-agent";
-import type { OwnedUiDialog } from "../owned-ui-contracts/index.js";
+import type { OwnedUiDialog } from "../../../contracts/owned-ui/index.js";
 import { type TrustDecision, type TrustOption, type TrustUpdate } from "./upstream/components/trust-selector.js";
 import { type PiShellComponentPort, type PiShellEditorOptions, type PiShellSelectorOption, type PiShellSelectorOptions } from "./shell-shared-facade.js";
 export declare function createPiShellSelector(options: PiShellSelectorOptions): PiShellComponentPort;

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/shell-shared-facade.d.ts

@@ -1,5 +1,5 @@
 import { type AutocompleteProvider, type Component, type TUI } from "#pi-tui";
-import type { OwnedUiSessionViewModel, OwnedUiThinkingLevel, OwnedUiTranscriptBlock } from "../owned-ui-contracts/index.js";
+import type { OwnedUiSessionViewModel, OwnedUiThinkingLevel, OwnedUiTranscriptBlock } from "../../../contracts/owned-ui/index.js";
 export interface PiShellComponentPort {
     render(width: number): readonly string[];
     handleInput?(data: string): void;

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/upstream/components/session-footer.d.ts

@@ -1,5 +1,5 @@
 import { type Component } from "#pi-tui";
-import type { OwnedUiSessionViewModel } from "../../../owned-ui-contracts/index.js";
+import type { OwnedUiSessionViewModel } from "../../../../../contracts/owned-ui/index.js";
 export declare class SessionFooter implements Component {
     private readonly getView;
     private readonly cwd;

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/adapter.d.ts

@@ -1,7 +1,7 @@
 import { type AgentSessionRuntime, type AgentSessionServices, type SessionInfo } from "@earendil-works/pi-coding-agent";
-import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, type OwnedUiCommand, type OwnedUiCommandOutcome, type OwnedUiEvent, type OwnedUiSessionViewModel, type OwnedUiSnapshot } from "../owned-ui-contracts/index.js";
+import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, type OwnedUiCommand, type OwnedUiCommandOutcome, type OwnedUiEvent, type OwnedUiSessionViewModel, type OwnedUiSnapshot } from "../../../contracts/owned-ui/index.js";
 import { type PiAuthenticationProviderOption, type PiBashWorkflowResult, type PiPinnedSettingsCallback, type PiPinnedSettingsSnapshot, type PiWorkflowAutocompleteCommand, type PiWorkflowHost, type PiWorkflowInteractionHost, type PiWorkflowOption, type PiWorkflowRequest, type PiWorkflowResult } from "./workflows.js";
-import type { AgentSettingsPort } from "../agent-engine-contracts/index.js";
+import type { AgentSettingsPort } from "../../../contracts/agent-engine/index.js";
 export interface PiEngineRuntimeFactoryInput {
     readonly cwd: string;
     readonly agentDir: string;