@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.402

package/dist/foundation/startup/startup-runtime.js

@@ -0,0 +1,142 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, mkdir, readdir, rm } from "node:fs/promises";
+import { constants as moduleConstants, enableCompileCache } from "node:module";
+import { dirname, resolve } from "node:path";
+import { homedir, platform } from "node:os";
+import { performance } from "node:perf_hooks";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { readLaunchContext } from "../launch-context/index.js";
+/** Initialize opt-in startup tracing from a caller-provided evidence path. */
+export function initializeStartupTrace(environment, profileId, startedAtMs = performance.timeOrigin + performance.now()) {
+    const configured = environment[PRODUCT_IDENTITY.environment.startupTrace];
+    if (!configured || parseContext(configured) !== null)
+        return;
+    const launch = readLaunchContext(environment);
+    const context = {
+        path: resolve(configured),
+        traceId: randomUUID(),
+        startedAtMs,
+        profileId,
+        releaseId: launch.releaseId ?? null,
+        dependencyLayerIds: parseLayerIds(launch.releaseLayers),
+    };
+    environment[PRODUCT_IDENTITY.environment.startupTrace] = JSON.stringify(context);
+}
+/** Append one redacted phase event; ordinary launches without trace context perform no I/O. */
+export async function markStartupPhase(environment, phase) {
+    const context = parseContext(environment[PRODUCT_IDENTITY.environment.startupTrace]);
+    if (context === null)
+        return;
+    const elapsedMs = Math.max(0, performance.timeOrigin + performance.now() - context.startedAtMs);
+    const launch = readLaunchContext(environment);
+    const dependencyLayerIds = parseLayerIds(launch.releaseLayers);
+    const event = {
+        schema: PRODUCT_IDENTITY.evidence.startupTraceSchema,
+        traceId: context.traceId,
+        phase,
+        elapsedMs,
+        processId: process.pid,
+        profileId: context.profileId,
+        releaseId: launch.releaseId ?? context.releaseId,
+        dependencyLayerIds: dependencyLayerIds.length > 0 ? dependencyLayerIds : context.dependencyLayerIds,
+        nodeVersion: process.version,
+        fileReadOperations: process.resourceUsage().fsRead,
+    };
+    await mkdir(dirname(context.path), { recursive: true, mode: 0o700 });
+    await appendFile(context.path, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+export function assertImmutableWarmupEnvironment(environment) {
+    readLaunchContext(environment, "warmup");
+}
+/** Enable the compile cache directly from launch environment without loading profile services. */
+export function enableEnvironmentCompileCache(environment) {
+    const home = environment.HOME ?? environment.USERPROFILE ?? homedir();
+    const dataDir = resolve(environment[PRODUCT_IDENTITY.environment.dataDir]
+        ?? (platform() === "win32"
+            ? resolve(environment.LOCALAPPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : resolve(environment.XDG_DATA_HOME ?? resolve(home, ".local", "share"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    const launch = readLaunchContext(environment);
+    return enableStartupCompileCache(dataDir, launch.releaseId ?? null, parseLayerIds(launch.releaseLayers));
+}
+/** Enable Node's supported persistent compile cache in an immutable-identity namespace. */
+export function enableStartupCompileCache(dataDir, releaseId, dependencyLayerIds) {
+    try {
+        const path = startupCompileCachePath(dataDir, releaseId, dependencyLayerIds);
+        const result = enableCompileCache(path);
+        return result.status === moduleConstants.compileCacheStatus.FAILED ? null : result.directory ?? path;
+    }
+    catch {
+        return null;
+    }
+}
+export function startupCompileCachePath(dataDir, releaseId, dependencyLayerIds) {
+    const layers = createHash("sha256").update(dependencyLayerIds.join("\0")).digest("hex").slice(0, 20);
+    const content = dependencyLayerIds.length > 0
+        ? `layers-${layers}`
+        : `release-${(releaseId ?? "mutable").replace(/[^0-9A-Za-z.+_-]/g, "_")}`;
+    // Performance: stable layer paths share compiled dependency entries across product releases;
+    // Node's own cache key still isolates each release-specific module path and source bytes.
+    return resolve(dataDir, "cache", "compile", `${process.versions.modules ?? "node"}-${process.version.replace(/[^0-9A-Za-z.-]/g, "_")}-${content}`);
+}
+/** Retain current compile namespaces plus a bounded number of recent fallbacks. */
+export async function collectCompileCaches(dataDir, protectedPaths, keepRecent = 2) {
+    const root = resolve(dataDir, "cache", "compile");
+    const protectedSet = new Set(protectedPaths.map(path => resolve(path)));
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const candidates = await Promise.all(entries.filter(entry => entry.isDirectory()).map(async (entry) => {
+        const path = resolve(root, entry.name);
+        const metadata = await import("node:fs/promises").then(fs => fs.stat(path));
+        return { path, mtimeMs: metadata.mtimeMs };
+    }));
+    const retainedRecent = new Set(candidates.filter(item => !protectedSet.has(item.path))
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .slice(0, keepRecent)
+        .map(item => item.path));
+    for (const candidate of candidates) {
+        if (!protectedSet.has(candidate.path) && !retainedRecent.has(candidate.path))
+            await rm(candidate.path, { recursive: true, force: true });
+    }
+}
+export function assertStartupPerformanceBudget(evidence, budgets = { postUpdateMs: 5_000, warmMs: 3_000 }) {
+    const events = [...evidence.events].sort((left, right) => left.elapsedMs - right.elapsedMs);
+    const ready = events.findLast(event => event.phase === "first-input-ready-render");
+    if (!ready)
+        throw new Error(`startup budget failed for ${evidence.profileId}: first input-ready render was not recorded`);
+    const budget = evidence.launchKind === "warm" ? budgets.warmMs : budgets.postUpdateMs;
+    if (ready.elapsedMs <= budget)
+        return;
+    const intervals = events.map((event, index) => ({
+        phase: event.phase,
+        durationMs: event.elapsedMs - (events[index - 1]?.elapsedMs ?? 0),
+    })).sort((left, right) => right.durationMs - left.durationMs);
+    throw new Error(`startup budget failed for ${evidence.profileId} ${evidence.launchKind}: ${Math.round(ready.elapsedMs)}ms exceeds ${budget}ms; dominant phases: ${intervals.slice(0, 3).map(item => `${item.phase} ${Math.round(item.durationMs)}ms`).join(", ")}`);
+}
+export function parseStartupTrace(source) {
+    const events = source.split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));
+    for (const event of events) {
+        if (event.schema !== PRODUCT_IDENTITY.evidence.startupTraceSchema || typeof event.traceId !== "string"
+            || typeof event.phase !== "string" || !Number.isFinite(event.elapsedMs) || !Array.isArray(event.dependencyLayerIds)) {
+            throw new Error("startup trace contains an invalid event");
+        }
+    }
+    return events.sort((left, right) => left.elapsedMs - right.elapsedMs);
+}
+function parseContext(value) {
+    if (!value?.startsWith("{"))
+        return null;
+    try {
+        const context = JSON.parse(value);
+        if (typeof context.path !== "string" || typeof context.traceId !== "string" || !Number.isFinite(context.startedAtMs)
+            || typeof context.profileId !== "string" || !Array.isArray(context.dependencyLayerIds))
+            return null;
+        return context;
+    }
+    catch {
+        return null;
+    }
+}
+function parseLayerIds(value) {
+    if (!value)
+        return [];
+    return [...new Set(value.split(",").filter(id => /^dependencies-[a-f0-9]{32}$/.test(id)))].sort();
+}

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 {
@@ -14,6 +14,7 @@ export interface StoredWorkspaceAgent {
     readonly agent: ManagedAgentDescriptor;
     readonly presentation: WorkspaceAgentPresentation;
 }
+/** Owns WAL-backed control persistence and reconciles prior-boot records before current use. */
 export declare class ControlStore {
     #private;
     readonly bootNonce: string | null;

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,84 @@
+import { randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { assertImmutableExecutionRoot, CohortStateStore, readCertifiedReleaseManifest, recordParentCertifiedRelease, selectSupervisorLaunchReleaseId, UpdateTransactionStore } from "../release/index.js";
+import { publishSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath } from "../lifecycle/index.js";
+import { ControlStore } from "../storage/index.js";
+import { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
+import { SupervisorServer } from "./server.js";
+import { PRODUCT_TEXT } from "../../product-identity.js";
+import { readLaunchContext } from "../launch-context/index.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 context = readLaunchContext(process.env, "release");
+    const releaseRoot = context.releaseRoot;
+    const releaseId = context.releaseId;
+    const contentDigest = context.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"));
+        // Invariant: readiness follows current-contract certification, never an old-updater upgrade path.
+        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 () => {
+            const transaction = await new UpdateTransactionStore(paths.dataDir).read();
+            return selectSupervisorLaunchReleaseId(await cohortState.read(), transaction);
+        });
+        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/foundation/supervision/server.d.ts

@@ -0,0 +1,51 @@
+import { rename, rm, writeFile } from "node:fs/promises";
+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";
+interface EndpointMetadataCommitOperations {
+    readonly platform?: NodeJS.Platform;
+    readonly write?: typeof writeFile;
+    readonly replace?: typeof rename;
+    readonly remove?: typeof rm;
+    readonly wait?: (delayMs: number) => Promise<void>;
+}
+/** Atomically replaces endpoint metadata while tolerating bounded Windows reader sharing. */
+export declare function commitEndpointMetadata(path: string, source: string, operations?: EndpointMetadataCommitOperations): Promise<void>;
+/** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
+export declare class SupervisorServer {
+    #private;
+    readonly store: ControlStore;
+    readonly release: MaterializedRelease;
+    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, 
+    /**
+     * 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>;
+}
+export {};