@timurproko/a1 0.1.8-dev.235df0e → 0.1.8-dev.260

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

@@ -2,10 +2,11 @@ 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;
+/** Owns WAL-backed control persistence and reconciles prior-boot records before current use. */
 export class ControlStore {
     bootNonce;
     database;
@@ -30,8 +31,8 @@ export class ControlStore {
     migrate() {
         const versionRow = this.database.prepare("PRAGMA user_version").get();
         const version = versionRow.user_version;
-        if (version > 5)
-            throw new Error(`control database version ${version} is newer than supported version 5`);
+        if (version > 6)
+            throw new Error(`control database version ${version} is newer than supported version 6`);
         if (version !== 0)
             this.#assertCurrentControlSchema();
         if (version === 0) {
@@ -187,7 +188,7 @@ export class ControlStore {
         CREATE TABLE launch_instances (
           id TEXT PRIMARY KEY,
           owner_client_id TEXT NOT NULL,
-          profile_id TEXT NOT NULL CHECK (profile_id IN ('a1', 'pi', 'sandbox')),
+          profile_id TEXT NOT NULL CHECK (profile_id IN ('a1', 'pi')),
           state TEXT NOT NULL CHECK (state IN ('requested', 'active', 'stopping', 'completed', 'interrupted')),
           shutdown_policy TEXT NOT NULL CHECK (shutdown_policy = 'terminate-tree-on-close'),
           guardian_identity_json TEXT NOT NULL CHECK (json_valid(guardian_identity_json)),
@@ -208,6 +209,40 @@ export class ControlStore {
         CREATE INDEX idx_launch_instances_boot ON launch_instances(owner_boot_nonce, state);
         PRAGMA user_version = 5;
         COMMIT;
+      `);
+        }
+        if (version <= 5) {
+            this.database.exec(`
+        BEGIN IMMEDIATE;
+        ALTER TABLE launch_instances RENAME TO launch_instances_v5;
+        DROP INDEX idx_launch_instances_owner;
+        DROP INDEX idx_launch_instances_boot;
+        CREATE TABLE launch_instances (
+          id TEXT PRIMARY KEY,
+          owner_client_id TEXT NOT NULL,
+          profile_id TEXT NOT NULL CHECK (profile_id IN ('a1', 'pi')),
+          state TEXT NOT NULL CHECK (state IN ('requested', 'active', 'stopping', 'completed', 'interrupted')),
+          shutdown_policy TEXT NOT NULL CHECK (shutdown_policy = 'terminate-tree-on-close'),
+          guardian_identity_json TEXT NOT NULL CHECK (json_valid(guardian_identity_json)),
+          root_identity_json TEXT CHECK (root_identity_json IS NULL OR json_valid(root_identity_json)),
+          containment_identity_json TEXT CHECK (containment_identity_json IS NULL OR json_valid(containment_identity_json)),
+          created_at TEXT NOT NULL,
+          activated_at TEXT,
+          stopping_at TEXT,
+          completed_at TEXT,
+          outcome_json TEXT CHECK (outcome_json IS NULL OR json_valid(outcome_json)),
+          owner_boot_nonce TEXT NOT NULL,
+          CHECK ((state = 'requested' AND root_identity_json IS NULL AND containment_identity_json IS NULL AND activated_at IS NULL AND stopping_at IS NULL AND completed_at IS NULL AND outcome_json IS NULL)
+            OR (state = 'active' AND root_identity_json IS NOT NULL AND containment_identity_json IS NOT NULL AND activated_at IS NOT NULL AND stopping_at IS NULL AND completed_at IS NULL AND outcome_json IS NULL)
+            OR (state = 'stopping' AND root_identity_json IS NOT NULL AND containment_identity_json IS NOT NULL AND activated_at IS NOT NULL AND stopping_at IS NOT NULL AND completed_at IS NULL AND outcome_json IS NULL)
+            OR (state IN ('completed', 'interrupted') AND completed_at IS NOT NULL AND outcome_json IS NOT NULL))
+        );
+        INSERT INTO launch_instances SELECT * FROM launch_instances_v5 WHERE profile_id IN ('a1', 'pi');
+        DROP TABLE launch_instances_v5;
+        CREATE INDEX idx_launch_instances_owner ON launch_instances(owner_client_id, state);
+        CREATE INDEX idx_launch_instances_boot ON launch_instances(owner_boot_nonce, state);
+        PRAGMA user_version = 6;
+        COMMIT;
       `);
         }
         if (version === 0) {

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 {
@@ -33,6 +33,7 @@ export type StructuredBackpressureReleaseResult = {
     readonly code: "unknown-lease" | "invalid-request";
     readonly diagnostic: string;
 };
+/** Issues bounded resource leases and selects the negotiated backpressure action on exhaustion. */
 export declare class StructuredBackpressureController {
     #private;
     readonly adapterId: string;

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

@@ -1,4 +1,5 @@
-import { assertStructuredCapability, } from "../workspace-contracts/index.js";
+import { assertStructuredCapability, } from "../../contracts/workspace/index.js";
+/** Issues bounded resource leases and selects the negotiated backpressure action on exhaustion. */
 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";
 }>;
@@ -38,6 +38,7 @@ export type StructuredCommandOutcomeResult = {
     readonly code: string;
     readonly diagnostic: string;
 };
+/** Tracks structured commands by correlation identity through one idempotent terminal outcome. */
 export declare class StructuredCommandTracker {
     #private;
     readonly agentId: string;

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

@@ -1,4 +1,5 @@
-import { assertStructuredCapability, assertWorkspaceCommand, } from "../workspace-contracts/index.js";
+import { assertStructuredCapability, assertWorkspaceCommand, } from "../../contracts/workspace/index.js";
+/** Tracks structured commands by correlation identity through one idempotent terminal outcome. */
 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;
@@ -30,6 +30,7 @@ export type StructuredReconnectionResult = {
     readonly code: string;
     readonly diagnostic: string;
 };
+/** Accepts a recovery boundary once after validating negotiated identity, proof, and protocol continuity. */
 export declare class StructuredReconnectionManager {
     #private;
     constructor(capability: StructuredCapabilityContract);

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

@@ -1,5 +1,6 @@
-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";
+/** Accepts a recovery boundary once after validating negotiated identity, proof, and protocol continuity. */
 export class StructuredReconnectionManager {
     #capability;
     #acceptedBoundaries = new Set();

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";
 }>;
@@ -44,6 +44,7 @@ export type StructuredSnapshotApplyResult = {
     readonly code: string;
     readonly diagnostic: string;
 };
+/** Applies ordered structured events and snapshots while exposing gaps as explicit resynchronization. */
 export declare class StructuredEventReducer {
     #private;
     readonly agentId: string;

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

@@ -1,4 +1,5 @@
-import { assertStructuredAgentSnapshot, assertStructuredCapability, assertWorkspaceEvent, } from "../workspace-contracts/index.js";
+import { assertStructuredAgentSnapshot, assertStructuredCapability, assertWorkspaceEvent, } from "../../contracts/workspace/index.js";
+/** Applies ordered structured events and snapshots while exposing gaps as explicit resynchronization. */
 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/foundation/supervision/main.d.ts

@@ -0,0 +1 @@
+export declare function runSupervisor(arguments_?: readonly string[]): Promise<void>;

package/dist/foundation/supervision/main.js

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { assertImmutableExecutionRoot, CohortStateStore, readCertifiedReleaseManifest, recordParentCertifiedRelease } from "../release/index.js";
+import { publishSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath } from "../lifecycle/index.js";
+import { ControlStore } from "../storage/index.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(arguments_ = []) {
+    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];
+    const contentDigest = process.env[PRODUCT_IDENTITY.environment.releaseDigest];
+    const attemptId = startupAttempt(arguments_);
+    const resultPath = attemptId ? supervisorStartupResultPath(productPaths.runtimeDir, attemptId) : null;
+    let stage = "release-environment";
+    let server = null;
+    try {
+        if (!releaseRoot || !releaseId || !contentDigest)
+            throw new Error(PRODUCT_TEXT.diagnostic("supervisor must be launched from a verified immutable release"));
+        stage = "release-certification";
+        const release = await readCertifiedReleaseManifest({ releaseRoot, releaseId, contentDigest }, resolve(paths.dataDir, "releases"), { allowLegacyParentCertification: true });
+        // Compatibility: an older updater may have written release evidence before restart seals
+        // existed, even when its layer certification has already been upgraded by a retry.
+        await recordParentCertifiedRelease(release, paths.dataDir);
+        stage = "immutable-root";
+        await assertImmutableExecutionRoot(release, paths.dataDir);
+        // Protocol: 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) };
+        stage = "storage";
+        const bootNonce = randomUUID();
+        const store = new ControlStore(paths.databasePath, bootNonce);
+        const cohortState = new CohortStateStore(paths.dataDir);
+        server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => (await cohortState.read()).references.active);
+        stage = "endpoint-listen";
+        await server.listen();
+        if (resultPath && attemptId)
+            await publishSupervisorStartupResult(resultPath, supervisorStartupReady(attemptId, release.releaseId));
+        log(`supervisor ${server.id} listening at ${paths.endpoint} (pid ${process.pid})`);
+        let closing = false;
+        const close = async (signal) => {
+            if (closing)
+                return;
+            closing = true;
+            log(`received ${signal}; stopping supervised process tree`);
+            await server?.close(true);
+            process.exitCode = 0;
+        };
+        process.on("SIGINT", () => void close("SIGINT"));
+        process.on("SIGTERM", () => void close("SIGTERM"));
+        process.on("uncaughtException", error => {
+            log(`uncaught exception: ${error.stack ?? error.message}`);
+            process.exitCode = 1;
+        });
+        process.on("unhandledRejection", error => log(`unhandled rejection: ${String(error)}`));
+    }
+    catch (error) {
+        await server?.close(true).catch(() => undefined);
+        const message = error instanceof Error ? error.stack ?? error.message : String(error);
+        log(`startup failure at ${stage}: ${message}`);
+        if (resultPath && attemptId && releaseId) {
+            await publishSupervisorStartupResult(resultPath, supervisorStartupFailure(error, attemptId, releaseId, stage)).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+function startupAttempt(arguments_) {
+    if (arguments_.length === 0)
+        return null;
+    if (arguments_.length !== 2 || arguments_[0] !== "--startup-attempt" || !arguments_[1]) {
+        throw new Error(PRODUCT_TEXT.diagnostic("supervisor startup arguments are invalid"));
+    }
+    return arguments_[1];
+}

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

@@ -2,6 +2,7 @@ import { type SupervisorSnapshot } from "../lifecycle/index.js";
 import { type MaterializedRelease } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { type ProductPaths } from "./paths.js";
+/** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
 export declare class SupervisorServer {
     #private;
     readonly store: ControlStore;
@@ -9,14 +10,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

@@ -1,19 +1,23 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { createConnection, createServer } from "node:net";
 import { platform } from "node:os";
+import { dirname } from "node:path";
 import { assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
 import { encodeFrame, isCommandMessage, isControlHello, LineFrameDecoder, localControlHello, MAX_CONTROL_FRAME_BYTES, negotiateControlFeatures } from "../protocol/index.js";
 import { processIsAlive } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveProductPaths } from "./paths.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+/** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
 export class SupervisorServer {
     store;
     release;
     terminateProcess;
     reconciliationDeadlineMs;
     shutdownDeadlineMs;
+    readActiveReleaseId;
+    supersededPollMs;
     id = randomUUID();
     bootNonce;
     pidStartIdentity = `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
@@ -31,12 +35,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,7 +70,10 @@ 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 (this.paths.endpointDirectory)
+                await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
             if (await endpointIsLive(this.paths.endpoint))
                 throw new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`));
             await rm(this.paths.endpoint, { force: true });
@@ -71,12 +88,41 @@ export class SupervisorServer {
             });
         });
         await this.#writeEndpointMetadata();
+        if (this.readActiveReleaseId) {
+            const poll = setInterval(() => void this.#refreshCohortRole(), this.supersededPollMs);
+            poll.unref();
+            this.#supersededPoll = poll;
+        }
+    }
+    // Invariant: superseding a cohort never interrupts its held instances; it retires only when empty.
+    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 +243,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 +328,9 @@ export class SupervisorServer {
         this.#uncertainInstances.delete(stored.id);
         this.#unbindOwner(stored.id, socket);
         this.#mutated();
+        // Invariant: 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);
@@ -370,7 +422,7 @@ export class SupervisorServer {
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             if (this.#instances.size === 0) {
-                // Let the terminal command result flush before closing owner sockets.
+                // Concurrency: allow the terminal command result to flush before closing owner sockets.
                 await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
                 return this.#instances.size === 0;
             }
@@ -440,6 +492,16 @@ function sameContainmentIdentity(left, right) {
 function isMessageType(value, type) {
     return typeof value === "object" && value !== null && "type" in value && value.type === type;
 }
+async function ensureManagedEndpointDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const metadata = await lstat(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error(`managed endpoint path is not a directory: ${path}`);
+    const currentUser = process.getuid?.();
+    if (currentUser !== undefined && metadata.uid !== currentUser)
+        throw new Error(`managed endpoint directory has another owner: ${path}`);
+    await chmod(path, 0o700);
+}
 async function endpointIsLive(endpoint) {
     return await new Promise(resolve => {
         const socket = createConnection(endpoint);

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.d.ts

@@ -10,6 +10,7 @@ export interface PiComponentConformanceReport {
     readonly componentResults: readonly PiComponentConformanceResult[];
     readonly componentFamilies: readonly string[];
 }
+/** Identifies the Pi presentation-conformance stage that failed against the pinned component surface. */
 export declare class PiComponentConformanceError extends Error {
     readonly stage: "theme" | "components";
     constructor(stage: "theme" | "components", cause: unknown);

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

@@ -2,9 +2,10 @@ 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";
+/** Identifies the Pi presentation-conformance stage that failed against the pinned component surface. */
 export class PiComponentConformanceError extends Error {
     stage;
     constructor(stage, cause) {

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

@@ -3,7 +3,7 @@ export * from "./conformance.js";
 export * from "./shell-components.js";
 export * from "./theme.js";
 export * from "./upstream/theme/theme-controller.js";
-export { applyConfiguredPiTheme, getAvailablePiThemes } from "./upstream/theme/theme.js";
+export { applyConfiguredPiTheme, getAvailablePiThemes, onPiThemeChange } from "./upstream/theme/theme.js";
 export * from "./upstream/components/countdown-timer.js";
 export * from "./upstream/components/extension-editor.js";
 export * from "./upstream/components/session-selector.js";

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

@@ -3,7 +3,7 @@ export * from "./conformance.js";
 export * from "./shell-components.js";
 export * from "./theme.js";
 export * from "./upstream/theme/theme-controller.js";
-export { applyConfiguredPiTheme, getAvailablePiThemes } from "./upstream/theme/theme.js";
+export { applyConfiguredPiTheme, getAvailablePiThemes, onPiThemeChange } from "./upstream/theme/theme.js";
 export * from "./upstream/components/countdown-timer.js";
 export * from "./upstream/components/extension-editor.js";
 export * from "./upstream/components/session-selector.js";

package/dist/integrations/pi/components/owned-editor-ux.d.ts

@@ -0,0 +1,55 @@
+import { type Editor } from "#pi-tui";
+import type { KeybindingsManager } from "./upstream/adjacent/core/keybindings.js";
+import type { PiShellClipboardContent, PiShellEditorTextRange } from "./shell-shared-facade.js";
+/**
+ * Middleware boundary around Pi's editor. Interceptors may claim an input or
+ * delegate to the next interceptor/vanilla editor, and may decorate the rows
+ * vanilla Pi renders. This keeps owned UX additions out of the synchronized
+ * Pi editor port and gives future interactions one registration point.
+ */
+export interface OwnedEditorUxInterceptor {
+    handleInput(data: string, next: () => void): void;
+    render(width: number, next: () => string[]): string[];
+    reset(): void;
+    handlePointer?(event: OwnedEditorPointerEvent): boolean;
+    hasSelection?(): boolean;
+    ownsPointer?(): boolean;
+    pasteClipboard?(): boolean;
+}
+export interface OwnedEditorPointerEvent {
+    readonly kind: "press" | "motion" | "release";
+    readonly button: number;
+    readonly column: number;
+    /** One-based row relative to the top of the editor component. */
+    readonly row: number;
+}
+export declare class OwnedEditorUxInterception {
+    readonly interceptors: readonly OwnedEditorUxInterceptor[];
+    readonly fallback: {
+        handleInput(data: string): void;
+        render(width: number): string[];
+    };
+    constructor(interceptors: readonly OwnedEditorUxInterceptor[], fallback: {
+        handleInput(data: string): void;
+        render(width: number): string[];
+    });
+    handleInput(data: string): void;
+    render(width: number): string[];
+    reset(): void;
+    handlePointer(event: OwnedEditorPointerEvent): boolean;
+    hasSelection(): boolean;
+    ownsPointer(): boolean;
+    pasteClipboard(): boolean;
+}
+export interface PromptSelectionUxOptions {
+    readonly copyText: (text: string) => void;
+    readonly readClipboardContent: () => Promise<PiShellClipboardContent | null>;
+    readonly transformPastedContent: (content: PiShellClipboardContent) => string;
+    readonly atomicRanges: (line: string) => readonly PiShellEditorTextRange[];
+    readonly expandCopiedText: (text: string) => string;
+    readonly paintSelection: (line: string, from: number, to: number, atomic: boolean) => string;
+    readonly decorateRow: (row: string, width: number) => string;
+    readonly requestRender: () => void;
+    readonly getRows: () => number;
+}
+export declare function createPromptSelectionInterceptor(editor: Editor, keybindings: KeybindingsManager, options: PromptSelectionUxOptions): OwnedEditorUxInterceptor;