@timurproko/a1 0.1.8-dev.112 → 0.1.8-dev.122

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

@@ -5,9 +5,10 @@ import { platform } from "node:os";
 import { resolve } from "node:path";
 import { selectCohortLaunch } from "./cohort-selection.js";
 import { CohortStateStore } from "./cohort-state.js";
-import { assertLaunchProfileId, resolveProductPaths } from "../lifecycle/index.js";
+import { assertLaunchProfileId, resolveCohortEndpoint, resolveProductPaths } from "../lifecycle/index.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
+import { sweepDeadEndpoints } from "./endpoints.js";
 import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export async function runBootstrap(options) {
@@ -20,7 +21,27 @@ export async function runBootstrap(options) {
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const stateStore = new CohortStateStore(paths.dataDir);
     let state = await stateStore.read();
-    let endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
+    // 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.
+    await sweepDeadEndpoints(paths).catch(() => []);
+    // Each cohort keeps its own endpoint, so a launch looks for the endpoint of the release it
+    // is about to run rather than for the one endpoint the runtime directory used to have.
+    const activeReleaseId = state.references.active;
+    let endpointPaths = activeReleaseId === null
+        ? { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath }
+        : resolveCohortEndpoint(paths, activeReleaseId, environment);
+    let endpoint = await readEndpointMetadata(endpointPaths.endpointMetadataPath);
+    if (endpoint === null) {
+        // A release that predates cohort-scoped endpoints published one endpoint for the whole
+        // runtime directory. Recognizing it is what lets a session started by that release keep
+        // working through the first launch that knows about cohorts.
+        const legacy = await readEndpointMetadata(paths.endpointMetadataPath);
+        if (legacy !== null) {
+            endpoint = legacy;
+            endpointPaths = { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+        }
+    }
     let probe = endpoint ? await probeOwnership(endpoint) : "dead";
     const installedVersion = await readInstalledVersion(options.packageRoot);
     const activeId = state.references.active;
@@ -35,10 +56,11 @@ export async function runBootstrap(options) {
         }
         if (endpoint === null || probe === "dead") {
             if (endpoint)
-                await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
+                await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
             const retained = await readMaterializedRelease(active.releaseRoot);
+            const retainedPaths = resolveCohortEndpoint(paths, retained.releaseId, environment);
             await startSupervisor(retained, environment);
-            await waitForVerifiedEndpoint(paths.endpointMetadataPath, retained, 8_000);
+            await waitForVerifiedEndpoint(retainedPaths.endpointMetadataPath, retained, 8_000);
             return await launchUi(retained, environment);
         }
     }
@@ -51,7 +73,17 @@ export async function runBootstrap(options) {
         await stateStore.activate(candidate.releaseId);
         state = await stateStore.read();
     }
-    endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
+    // The candidate's own endpoint decides whether this launch attaches or starts a supervisor.
+    // A cohort other than this one is not in the way: it listens somewhere else.
+    endpointPaths = resolveCohortEndpoint(paths, candidate.releaseId, environment);
+    endpoint = await readEndpointMetadata(endpointPaths.endpointMetadataPath);
+    if (endpoint === null) {
+        const legacy = await readEndpointMetadata(paths.endpointMetadataPath);
+        if (legacy !== null) {
+            endpoint = legacy;
+            endpointPaths = { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+        }
+    }
     probe = endpoint ? await probeOwnership(endpoint) : "dead";
     let decision = selectCohortLaunch(candidate, state, endpoint, probe);
     if (decision.action === "blocked") {
@@ -64,11 +96,11 @@ export async function runBootstrap(options) {
         await writeFile(resolve(paths.dataDir, `cleanup-${Date.now()}.json`), JSON.stringify(diagnostics, null, 2));
         if (!diagnostics.terminated)
             throw new Error(`could not safely clean stale ${PRODUCT_TEXT.displayName} supervisor ${endpoint.pid}`);
-        await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
+        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
         decision = selectCohortLaunch(candidate, await stateStore.read(), null, "dead");
     }
     else if (endpoint && probe === "dead") {
-        await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
+        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
     }
     if (decision.action === "launch-retained-ui") {
         const retained = await verifyMaterializedRelease(decision.releaseRoot, undefined, resolve(paths.dataDir, "releases"));
@@ -94,7 +126,7 @@ export async function runBootstrap(options) {
             output.write(`${PRODUCT_TEXT.diagnostic("could not complete bounded idle cohort shutdown; the candidate remains pending.")}\n`);
             return 1;
         }
-        await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
+        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
         await stateStore.activate(candidate.releaseId);
         decision = { action: "activate-candidate", releaseId: candidate.releaseId, releaseRoot: candidate.releaseRoot, reason: "idle cohort released ownership" };
     }
@@ -113,7 +145,7 @@ export async function runBootstrap(options) {
         selected = await readMaterializedRelease(decision.releaseRoot);
     }
     await startSupervisor(selected, environment);
-    await waitForVerifiedEndpoint(paths.endpointMetadataPath, selected, 8_000);
+    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, selected.releaseId, environment).endpointMetadataPath, selected, 8_000);
     return await launchUi(selected, environment);
 }
 async function readInstalledVersion(packageRoot) {
@@ -274,7 +306,7 @@ async function activatePendingAfterBlockerExit(candidate, stateStore, paths, env
     await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
     await stateStore.activate(candidate.releaseId);
     await startSupervisor(candidate, environment);
-    await waitForVerifiedEndpoint(paths.endpointMetadataPath, candidate, 8_000);
+    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000);
 }
 export async function releaseVerifiedIdleOwner(metadata, dataDir, operations = {}) {
     try {

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

@@ -0,0 +1,20 @@
+import type { SupervisorEndpointMetadata } from "./cohort-state.js";
+import type { CohortEndpointPaths, ProductPaths } from "../lifecycle/index.js";
+export interface RecordedEndpoint {
+    readonly metadata: SupervisorEndpointMetadata;
+    readonly paths: CohortEndpointPaths;
+}
+/**
+ * Every endpoint recorded under this runtime directory: one per cohort, plus the single
+ * endpoint published by releases that predate cohort-scoped identity. More than one can be
+ * live at a time, and each is validated on its own identity rather than by being the only one.
+ */
+export declare function listRecordedEndpoints(paths: ProductPaths): Promise<readonly RecordedEndpoint[]>;
+/**
+ * Removes the records of cohorts whose processes are gone. A record left by a cohort that
+ * exited without cleaning up is not evidence of ownership, and a later launch should not have
+ * to reason about it. Returns the release ids whose records were removed.
+ */
+export declare function sweepDeadEndpoints(paths: ProductPaths): Promise<readonly string[]>;
+/** The releases that a live cohort is running from, and so must be retained. */
+export declare function liveReleaseIds(paths: ProductPaths): Promise<readonly string[]>;

package/dist/foundation/release/endpoints.js

@@ -0,0 +1,50 @@
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { readEndpointMetadata, removeEndpointArtifacts } from "./bootstrap.js";
+import { processIsAlive } from "./process-cleanup.js";
+/**
+ * Every endpoint recorded under this runtime directory: one per cohort, plus the single
+ * endpoint published by releases that predate cohort-scoped identity. More than one can be
+ * live at a time, and each is validated on its own identity rather than by being the only one.
+ */
+export async function listRecordedEndpoints(paths) {
+    const recorded = [];
+    const legacy = await readEndpointMetadata(paths.endpointMetadataPath);
+    if (legacy) {
+        recorded.push({ metadata: legacy, paths: { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath } });
+    }
+    const names = await readdir(paths.endpointsDir).catch(() => []);
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const endpointMetadataPath = resolve(paths.endpointsDir, name);
+        const metadata = await readEndpointMetadata(endpointMetadataPath);
+        if (metadata)
+            recorded.push({ metadata, paths: { endpoint: metadata.endpoint, endpointMetadataPath } });
+    }
+    return recorded;
+}
+/**
+ * Removes the records of cohorts whose processes are gone. A record left by a cohort that
+ * exited without cleaning up is not evidence of ownership, and a later launch should not have
+ * to reason about it. Returns the release ids whose records were removed.
+ */
+export async function sweepDeadEndpoints(paths) {
+    const swept = [];
+    for (const recorded of await listRecordedEndpoints(paths)) {
+        if (processIsAlive(recorded.metadata.pid))
+            continue;
+        await removeEndpointArtifacts(recorded.paths.endpointMetadataPath, recorded.paths.endpoint);
+        swept.push(recorded.metadata.releaseId);
+    }
+    return swept;
+}
+/** The releases that a live cohort is running from, and so must be retained. */
+export async function liveReleaseIds(paths) {
+    const live = [];
+    for (const recorded of await listRecordedEndpoints(paths)) {
+        if (processIsAlive(recorded.metadata.pid))
+            live.push(recorded.metadata.releaseId);
+    }
+    return live;
+}

package/dist/{src/foundation → foundation}/release/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./bootstrap.js";
 export * from "./cohort-selection.js";
 export * from "./cohort-state.js";
+export * from "./endpoints.js";
 export * from "./process-cleanup.js";
 export * from "./release.js";
 export * from "./release-gc.js";

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

@@ -1,6 +1,7 @@
 export * from "./bootstrap.js";
 export * from "./cohort-selection.js";
 export * from "./cohort-state.js";
+export * from "./endpoints.js";
 export * from "./process-cleanup.js";
 export * from "./release.js";
 export * from "./release-gc.js";

package/dist/{src/foundation → foundation}/release/release-gc.d.ts

@@ -1,5 +1,8 @@
 import { CohortStateStore } from "./cohort-state.js";
+import type { ProductPaths } from "../lifecycle/index.js";
 /** Remove only a release that has no active, pending, approval, rollback,
  * retention, process, agent, or migration reference. State is detached first;
  * a filesystem failure can leave a safe orphan but never a dangling selector. */
-export declare function collectRelease(store: CohortStateStore, dataDir: string, releaseId: string, externalReferences: readonly string[]): Promise<void>;
+export declare function collectRelease(store: CohortStateStore, dataDir: string, releaseId: string, externalReferences: readonly string[], 
+/** Where endpoints are recorded, so a release a live cohort runs from is retained. */
+paths?: ProductPaths): Promise<void>;

package/dist/{src/foundation → foundation}/release/release-gc.js

@@ -1,15 +1,23 @@
 import { rm } from "node:fs/promises";
 import { resolve } from "node:path";
 import { CohortStateStore } from "./cohort-state.js";
+import { liveReleaseIds } from "./endpoints.js";
 import { verifyMaterializedRelease } from "./release-store.js";
 /** Remove only a release that has no active, pending, approval, rollback,
  * retention, process, agent, or migration reference. State is detached first;
  * a filesystem failure can leave a safe orphan but never a dangling selector. */
-export async function collectRelease(store, dataDir, releaseId, externalReferences) {
+export async function collectRelease(store, dataDir, releaseId, externalReferences, 
+/** Where endpoints are recorded, so a release a live cohort runs from is retained. */
+paths) {
     const state = await store.read();
     const release = state.releases[releaseId];
     if (!release)
         throw new Error(`unknown release ${releaseId}`);
+    // A superseded cohort keeps working until its last session leaves, and it runs from this
+    // content while it does. Collecting it would pull the release out from under live work.
+    if (paths && (await liveReleaseIds(paths)).includes(releaseId)) {
+        throw new Error(`release ${releaseId} is still running a live cohort`);
+    }
     await verifyMaterializedRelease(release.releaseRoot, undefined, resolve(dataDir, "releases"));
     await store.removeUnreferencedRelease(releaseId, externalReferences);
     await rm(release.releaseRoot, { recursive: true, force: false });

package/dist/{src/foundation → foundation}/release/update.d.ts

@@ -77,6 +77,14 @@ export interface UpdateTransactionJournal {
     clearCompleted(): Promise<void>;
 }
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
+export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end-session";
+/**
+ * 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 declare function planUpdateOwnership(ownership: "live-verified" | "dead", runsFromRetainedRelease: boolean): UpdateOwnershipAction;
 export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
 export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
 export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;

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";
@@ -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);
         },
     };
 }
@@ -491,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>;
 }