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

package/dist/composition/settings-route-host.js

@@ -0,0 +1,73 @@
+import { SETTINGS_APP_ID, SETTINGS_ROUTE, SettingsApp } from "../features/owned-ui/index.js";
+import { piTheme } from "../integrations/pi/components/index.js";
+import { UiAppHost, UiAppRegistry } from "../ui/apps/index.js";
+import { faint } from "../ui/components/index.js";
+/**
+ * Registers the A1-owned screens and adapts the app host to the shell's route
+ * seam. The shell mounts whatever surface it is handed and forwards keys; it
+ * never learns what an app is.
+ */
+export function createOwnedRouteHost(settings) {
+    const registry = new UiAppRegistry();
+    registry.register({ id: SETTINGS_APP_ID, route: SETTINGS_ROUTE, create: () => new SettingsApp(settings) });
+    return {
+        claims: route => registry.forRoute(route) !== null,
+        open: route => {
+            const registration = registry.forRoute(route);
+            if (registration === null)
+                return null;
+            let size = { width: 80, height: 24 };
+            let frame = [];
+            let closed = false;
+            let onRender = () => undefined;
+            let onExit = () => undefined;
+            const host = new UiAppHost({
+                registry,
+                closeOnInterrupt: true,
+                theme: pinnedTheme(),
+                surface: {
+                    size: () => size,
+                    requestRender: () => onRender(),
+                    exit: () => onExit(),
+                    present: lines => {
+                        if (lines === null)
+                            closed = true;
+                        else
+                            frame = lines;
+                    },
+                },
+            });
+            host.open(registration.id);
+            const surface = {
+                id: registration.id,
+                render: (width, height) => {
+                    size = { width, height };
+                    host.render();
+                    return frame.length === height ? frame : [...frame.slice(0, height), ...Array(Math.max(0, height - frame.length)).fill("")];
+                },
+                handleInput: data => host.handleInput(data).consumed,
+                handleMouse: event => host.handleMouse(event).consumed,
+                isClosed: () => closed || !host.isPresenting,
+                close: () => host.close(),
+                onRenderRequested: listener => { onRender = listener; },
+                onExitRequested: listener => { onExit = listener; },
+            };
+            return surface;
+        },
+    };
+}
+/** Maps A1 UI tokens onto the pinned Pi theme so owned screens match the shell. */
+function pinnedTheme() {
+    return {
+        fg: (token, text) => piTheme().fg(token, text),
+        bold: (text) => piTheme().bold(text),
+        // Unpainted, so a list reads against the terminal the reader actually has
+        // rather than against the background the configured theme was built for.
+        plain: (text) => text,
+        // Quiet, and quieter again: the terminal's own faint attribute over the
+        // dimmest colour the theme has.
+        disabled: (text) => faint(piTheme().fg("dim", text)),
+        highlight: (text) => `${text}`,
+        panel: (text) => `${text}`,
+    };
+}

package/dist/{src/features → features}/owned-ui/customization.d.ts

@@ -1,4 +1,4 @@
-import { type OwnedUiCommand, type OwnedUiCustomization, type OwnedUiSlotId, type OwnedUiTranscriptBlock } from "../../foundation/owned-ui-contracts/index.js";
+import { type OwnedUiCommand, type OwnedUiCustomization, type OwnedUiSlotId, type OwnedUiTranscriptBlock } from "../../contracts/owned-ui/index.js";
 export interface OwnedUiSlotImplementation {
     readonly payload: unknown;
     render?(input: unknown, width: number): readonly string[];

package/dist/{src/features → features}/owned-ui/customization.js

@@ -1,4 +1,4 @@
-import { assertOwnedUiCustomization, } from "../../foundation/owned-ui-contracts/index.js";
+import { assertOwnedUiCustomization, } from "../../contracts/owned-ui/index.js";
 export class OwnedCommandSurface {
     #handlers = new Map();
     #sequence = 0;

package/dist/{src/features → features}/owned-ui/diagnostics.d.ts

@@ -1,4 +1,4 @@
-import type { OwnedUiDiagnostics } from "../../foundation/owned-ui-contracts/index.js";
+import type { OwnedUiDiagnostics } from "../../contracts/owned-ui/index.js";
 export interface OwnedUiFrameObservation {
     readonly requestedFrames: number;
     readonly presentedFrames: number;

package/dist/{src/features → features}/owned-ui/run.d.ts

@@ -1,5 +1,5 @@
-import type { OwnedUiApplicationPort } from "../../foundation/presentation-contracts/index.js";
-import type { OwnedUiSettingsSession } from "../../foundation/owned-ui-settings/index.js";
+import type { OwnedUiApplicationPort } from "../../contracts/presentation/index.js";
+import type { OwnedUiSettingsSession } from "../../ui/settings/index.js";
 export interface OwnedUiRunOptions {
     readonly application: OwnedUiApplicationPort;
     /**

package/dist/{src/features → features}/owned-ui/settings-app.d.ts

@@ -1,6 +1,6 @@
-import type { AppHostServices, UiApp } from "../../foundation/ui-apps/index.js";
-import { ShortcutRegistry, type PaneInputResult, type PaneMouseEvent, type PaneRect } from "../../foundation/ui-components/index.js";
-import type { OwnedUiSettingsSession } from "../../foundation/owned-ui-settings/index.js";
+import type { AppHostServices, UiApp } from "../../ui/apps/index.js";
+import { ShortcutRegistry, type PaneInputResult, type PaneMouseEvent, type PaneRect } from "../../ui/components/index.js";
+import type { OwnedUiSettingsSession } from "../../ui/settings/index.js";
 export declare const SETTINGS_APP_ID = "settings";
 export declare const SETTINGS_ROUTE = "settings";
 type Action = "move-up" | "move-down" | "block-up" | "block-down" | "first" | "last" | "page-up" | "page-down" | "previous-value" | "next-value" | "activate" | "open-filter" | "close" | "part-previous" | "part-next" | "part-change";

package/dist/{src/features → features}/owned-ui/settings-app.js

@@ -1,4 +1,4 @@
-import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, PROMPT_GLYPH, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderStatusLine, renderListRow, renderNote, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, valueColumnFor, valueMenuFrame, promptRule, caretCell, blockRowSpan, displayWidth, faint, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollbarGeometry, selectableIndexes, } from "../../foundation/ui-components/index.js";
+import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, PROMPT_GLYPH, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderStatusLine, renderListRow, renderNote, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, valueColumnFor, valueMenuFrame, promptRule, caretCell, blockRowSpan, displayWidth, faint, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollbarGeometry, selectableIndexes, } from "../../ui/components/index.js";
 export const SETTINGS_APP_ID = "settings";
 export const SETTINGS_ROUTE = "settings";
 const SCOPE = SETTINGS_APP_ID;

package/dist/{src/features → features}/workspace/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { ManagedAgentDescriptor } from "../../foundation/workspace-contracts/index.js";
+import type { ManagedAgentDescriptor } from "../../contracts/workspace/index.js";
 export type WorkspaceCapabilityAction = {
     readonly type: "structured-command";
     readonly command: string;

package/dist/{src/features → features}/workspace/reducer.d.ts

@@ -1,4 +1,4 @@
-import { type ManagedAgentDescriptor } from "../../foundation/workspace-contracts/index.js";
+import { type ManagedAgentDescriptor } from "../../contracts/workspace/index.js";
 export interface WorkspaceAgentFailure {
     readonly code: string;
     readonly message: string;

package/dist/{src/features → features}/workspace/reducer.js

@@ -1,4 +1,4 @@
-import { assertManagedAgentDescriptor, } from "../../foundation/workspace-contracts/index.js";
+import { assertManagedAgentDescriptor, } from "../../contracts/workspace/index.js";
 const REMOVABLE_STATES = new Set(["stopped", "failed", "discontinuous"]);
 export class WorkspaceReducer {
     workspaceId;

package/dist/{src/features → features}/workspace/router.d.ts

@@ -1,5 +1,5 @@
 import { type StructuredCommandRecord } from "../../foundation/structured-agent-runtime/index.js";
-import type { ManagedAgentDescriptor } from "../../foundation/workspace-contracts/index.js";
+import type { ManagedAgentDescriptor } from "../../contracts/workspace/index.js";
 import { WorkspaceReducer, type WorkspaceAgentState, type WorkspaceView } from "./reducer.js";
 export interface RoutedStructuredCommand {
     readonly agentId: string;

package/dist/{src/features → features}/workspace/store.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRecoveryAuthority, RecoveryReferenceId } from "../../foundation/workspace-contracts/index.js";
+import type { AgentRecoveryAuthority, RecoveryReferenceId } from "../../contracts/workspace/index.js";
 import { WorkspaceReducer, type WorkspaceView } from "./reducer.js";
 export declare class WorkspaceStore {
     #private;

package/dist/{src/foundation → foundation}/launch-guardian/main.js

@@ -4,7 +4,7 @@ import { resolve } from "node:path";
 import { assertLaunchProfileId } from "../lifecycle/index.js";
 import { closeVerifiedContainment, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
 import { SupervisorClient } from "../protocol/index.js";
-import { resolveProductPaths } from "../supervision/index.js";
+import { resolveCohortEndpoint, resolveProductPaths } from "../supervision/index.js";
 export async function runLaunchGuardian(options) {
     assertLaunchProfileId(options.profileId);
     const environment = { ...(options.environment ?? process.env) };
@@ -17,7 +17,13 @@ export async function runLaunchGuardian(options) {
     if (!guardianIdentity)
         throw diagnosticError("launch guardian cannot verify its own native process identity", "PROCESS_IDENTITY_UNAVAILABLE");
     const client = options.control ?? new SupervisorClient(environment[PRODUCT_IDENTITY.environment.releaseId]);
-    await client.connect(paths.endpoint);
+    // An instance belongs to the cohort that launched it and talks to that cohort's endpoint
+    // for its whole life, whatever release becomes the active one meanwhile.
+    const releaseId = environment[PRODUCT_IDENTITY.environment.releaseId];
+    const endpoint = releaseId
+        ? resolveCohortEndpoint(paths, releaseId, environment).endpoint
+        : paths.endpoint;
+    await client.connect(endpoint);
     const containment = options.containment ?? new NativeGuardianContainment(instanceId, helperPath, resolve(paths.runtimeDir, "launch-instances", `${instanceId}.ready.json`));
     const stop = stopRequests(client, instanceId);
     let rootIdentity = null;

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

@@ -0,0 +1,28 @@
+export interface ProductPaths {
+    readonly configDir: string;
+    readonly dataDir: string;
+    readonly runtimeDir: string;
+    readonly databasePath: string;
+    /** The endpoint written by releases that predate cohort-scoped identity. */
+    readonly endpoint: string;
+    /** The metadata written by releases that predate cohort-scoped identity. */
+    readonly endpointMetadataPath: string;
+    readonly endpointsDir: string;
+    readonly supervisorLogPath: string;
+}
+/** Where one cohort listens, and where it records that it is listening. */
+export interface CohortEndpointPaths {
+    readonly endpoint: string;
+    readonly endpointMetadataPath: string;
+}
+/**
+ * Endpoint identity for one release cohort. Two cohorts can be live at once — an update
+ * leaves a working session on the release it started on — so the name a supervisor listens
+ * on has to name the release as well as the runtime directory, or the two contend for one
+ * endpoint and replacing one means ending the other.
+ *
+ * An explicit endpoint override keeps its single endpoint: it is how an isolated run pins
+ * the address it is going to talk to.
+ */
+export declare function resolveCohortEndpoint(paths: ProductPaths, releaseId: string, environment?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform): CohortEndpointPaths;
+export declare function resolveProductPaths(environment?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform, fallbackHome?: string): ProductPaths;

package/dist/{src/foundation → foundation}/lifecycle/paths.js

@@ -2,6 +2,26 @@ import { createHash } from "node:crypto";
 import { homedir, platform } from "node:os";
 import { posix, win32 } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/**
+ * Endpoint identity for one release cohort. Two cohorts can be live at once — an update
+ * leaves a working session on the release it started on — so the name a supervisor listens
+ * on has to name the release as well as the runtime directory, or the two contend for one
+ * endpoint and replacing one means ending the other.
+ *
+ * An explicit endpoint override keeps its single endpoint: it is how an isolated run pins
+ * the address it is going to talk to.
+ */
+export function resolveCohortEndpoint(paths, releaseId, environment = process.env, hostPlatform = platform()) {
+    if (environment[PRODUCT_IDENTITY.environment.endpoint]) {
+        return { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+    }
+    const path = hostPlatform === "win32" ? win32 : posix;
+    const token = createHash("sha256").update(releaseId).digest("hex").slice(0, 16);
+    const endpoint = hostPlatform === "win32"
+        ? `${paths.endpoint}-${token}`
+        : path.join(paths.runtimeDir, `${token}-${PRODUCT_IDENTITY.endpoint.unixSocketFilename}`);
+    return { endpoint, endpointMetadataPath: path.join(paths.endpointsDir, `${token}.json`) };
+}
 export function resolveProductPaths(environment = process.env, hostPlatform = platform(), fallbackHome = homedir()) {
     const windows = hostPlatform === "win32";
     const path = windows ? win32 : posix;
@@ -37,6 +57,7 @@ export function resolveProductPaths(environment = process.env, hostPlatform = pl
         databasePath: path.resolve(databaseOverride ?? path.join(dataDir, PRODUCT_IDENTITY.endpoint.databaseFilename)),
         endpoint,
         endpointMetadataPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.metadataFilename),
+        endpointsDir: path.join(runtimeDir, "endpoints"),
         supervisorLogPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.supervisorLogFilename),
     };
 }

package/dist/{src/foundation → foundation}/native-host-protocol/messages.d.ts

@@ -1,4 +1,4 @@
-import { type CorrelationId, type NativeHostCommand, type NativeHostEvent, type NativeHostHello, type PaneId, type TerminalSessionLaunch } from "../workspace-contracts/index.js";
+import { type CorrelationId, type NativeHostCommand, type NativeHostEvent, type NativeHostHello, type PaneId, type TerminalSessionLaunch } from "../../contracts/workspace/index.js";
 export declare const NATIVE_HOST_PROTOCOL_NAME: string;
 export declare const MAX_NATIVE_HOST_MESSAGE_BYTES: number;
 export type NativeHostProofMessage = {

package/dist/{src/foundation → foundation}/native-host-protocol/messages.js

@@ -1,4 +1,4 @@
-import { NATIVE_HOST_PROTOCOL_VERSION, assertNativeHostCommand, assertTerminalSessionLaunch, } from "../workspace-contracts/index.js";
+import { NATIVE_HOST_PROTOCOL_VERSION, assertNativeHostCommand, assertTerminalSessionLaunch, } from "../../contracts/workspace/index.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 export const NATIVE_HOST_PROTOCOL_NAME = PRODUCT_IDENTITY.protocol.nativeHostSchema;
 export const MAX_NATIVE_HOST_MESSAGE_BYTES = 1024 * 1024;

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

@@ -33,7 +33,7 @@ export interface UpdatePerformanceEvidence {
 export interface SelfUpdateOptions {
     packageRoot: string;
     channel?: UpdateChannel;
-    /** A specific preview to install, named by its commit or its full version. */
+    /** A specific preview to install, named by its development number or full version. */
     target?: string;
     environment?: NodeJS.ProcessEnv;
     fileSystem?: UpdateFileSystem;
@@ -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;