@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.226

package/dist/foundation/release/warmup.js

@@ -0,0 +1,35 @@
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { releaseEnvironment } from "./bootstrap.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/** Import the exact immutable startup graph in a terminal-free bounded child process. */
+export async function warmMaterializedRelease(release, environment, timeoutMs = 15_000) {
+    const entry = resolve(release.releaseRoot, "bin", "warmup.js");
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [entry], {
+            env: { ...releaseEnvironment(environment, release), [PRODUCT_IDENTITY.environment.immutableWarmup]: "1" },
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                rejectPromise(error);
+            else
+                resolvePromise();
+        };
+        child.once("error", error => finish(error));
+        child.once("close", (code, signal) => finish(code === 0
+            ? undefined
+            : new Error(`immutable startup warmup exited with ${code === null ? signal ?? "unknown status" : `status ${code}`}`)));
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(new Error(`immutable startup warmup exceeded ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+    });
+}

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

@@ -0,0 +1 @@
+export * from "./startup-runtime.js";

package/dist/foundation/startup/index.js

@@ -0,0 +1 @@
+export * from "./startup-runtime.js";

package/dist/foundation/startup/startup-runtime.d.ts

@@ -0,0 +1,36 @@
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export type StartupPhase = "command-invoked" | "bootstrap-start" | "bootstrap-selected" | "guardian-start" | "guardian-connected" | "ui-entry" | "ui-modules-loaded" | "pi-services" | "resource-discovery" | "session-created" | "settings-loaded" | "first-input-ready-render";
+export interface StartupPerformanceEvidence {
+    readonly profileId: "a1" | "pi";
+    readonly launchKind: "post-update" | "warm";
+    readonly events: readonly StartupTraceEvent[];
+}
+export interface StartupTraceEvent {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.startupTraceSchema;
+    readonly traceId: string;
+    readonly phase: StartupPhase;
+    readonly elapsedMs: number;
+    readonly processId: number;
+    readonly profileId: string;
+    readonly releaseId: string | null;
+    readonly dependencyLayerIds: readonly string[];
+    readonly nodeVersion: string;
+    readonly fileReadOperations: number;
+}
+/** Initialize opt-in startup tracing from a caller-provided evidence path. */
+export declare function initializeStartupTrace(environment: NodeJS.ProcessEnv, profileId: string, startedAtMs?: number): void;
+/** Append one redacted phase event; ordinary launches without trace context perform no I/O. */
+export declare function markStartupPhase(environment: NodeJS.ProcessEnv, phase: StartupPhase): Promise<void>;
+export declare function assertImmutableWarmupEnvironment(environment: NodeJS.ProcessEnv): void;
+/** Enable the compile cache directly from launch environment without loading profile services. */
+export declare function enableEnvironmentCompileCache(environment: NodeJS.ProcessEnv): string | null;
+/** Enable Node's supported persistent compile cache in an immutable-identity namespace. */
+export declare function enableStartupCompileCache(dataDir: string, releaseId: string | null, dependencyLayerIds: readonly string[]): string | null;
+export declare function startupCompileCachePath(dataDir: string, releaseId: string | null, dependencyLayerIds: readonly string[]): string;
+/** Retain current compile namespaces plus a bounded number of recent fallbacks. */
+export declare function collectCompileCaches(dataDir: string, protectedPaths: readonly string[], keepRecent?: number): Promise<void>;
+export declare function assertStartupPerformanceBudget(evidence: StartupPerformanceEvidence, budgets?: {
+    readonly postUpdateMs: number;
+    readonly warmMs: number;
+}): void;
+export declare function parseStartupTrace(source: string): readonly StartupTraceEvent[];

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

@@ -0,0 +1,140 @@
+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";
+/** 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 context = {
+        path: resolve(configured),
+        traceId: randomUUID(),
+        startedAtMs,
+        profileId,
+        releaseId: environment[PRODUCT_IDENTITY.environment.releaseId] ?? null,
+        dependencyLayerIds: parseLayerIds(environment[PRODUCT_IDENTITY.environment.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 event = {
+        schema: PRODUCT_IDENTITY.evidence.startupTraceSchema,
+        traceId: context.traceId,
+        phase,
+        elapsedMs: Math.max(0, performance.timeOrigin + performance.now() - context.startedAtMs),
+        processId: process.pid,
+        profileId: context.profileId,
+        releaseId: environment[PRODUCT_IDENTITY.environment.releaseId] ?? context.releaseId,
+        dependencyLayerIds: parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers]).length > 0
+            ? parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers])
+            : 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) {
+    if (environment[PRODUCT_IDENTITY.environment.immutableWarmup] !== "1") {
+        throw new Error("warmup entry is private to verified update activation");
+    }
+}
+/** 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)));
+    return enableStartupCompileCache(dataDir, environment[PRODUCT_IDENTITY.environment.releaseId] ?? null, parseLayerIds(environment[PRODUCT_IDENTITY.environment.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 === "post-update" ? budgets.postUpdateMs : budgets.warmMs;
+    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/{src/foundation → foundation}/supervision/main.js

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

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

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

package/dist/foundation/supervision/paths.js

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

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

@@ -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

@@ -8,12 +8,15 @@ 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 +34,22 @@ export class SupervisorServer {
     #results = new Map();
     #metadataWrites = Promise.resolve();
     #closing = false;
-    constructor(store, paths = resolveProductPaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code), reconciliationDeadlineMs = 3_000, shutdownDeadlineMs = 1_500) {
+    #superseded = false;
+    #supersededPoll = null;
+    constructor(store, paths = resolveProductPaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code), reconciliationDeadlineMs = 3_000, shutdownDeadlineMs = 1_500, 
+    /**
+     * Which release new sessions start on. A cohort that is no longer that release keeps
+     * serving the instances it already has, takes no new ones, and exits when its last one
+     * leaves. Absent, this supervisor never considers itself superseded.
+     */
+    readActiveReleaseId = null, supersededPollMs = 1_000) {
         this.store = store;
         this.release = release;
         this.terminateProcess = terminateProcess;
         this.reconciliationDeadlineMs = reconciliationDeadlineMs;
         this.shutdownDeadlineMs = shutdownDeadlineMs;
+        this.readActiveReleaseId = readActiveReleaseId;
+        this.supersededPollMs = supersededPollMs;
         this.bootNonce = bootNonce;
         this.paths = paths;
         for (const instance of store.loadActiveLaunchInstances())
@@ -56,6 +69,7 @@ export class SupervisorServer {
         if (this.#server)
             throw new Error("supervisor is already listening");
         await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
+        await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
         if (platform() !== "win32") {
             if (await endpointIsLive(this.paths.endpoint))
                 throw new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`));
@@ -71,12 +85,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 +240,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 +325,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 +419,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;
             }

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[];