@timurproko/a1 0.1.0 → 0.1.1-dev.10

package/dist/src/foundation/agent-engine-contracts/validation.js

@@ -0,0 +1,128 @@
+import { AGENT_ENGINE_CONTRACT_VERSION, } from "./model.js";
+import { assertAgentMessage } from "./domain-validation.js";
+const COMMANDS = new Set(["prompt", "steer", "follow-up", "abort", "retry", "compact", "bash", "replace-session"]);
+const EVENTS = new Set(["lifecycle", "content", "command-outcome", "snapshot-invalidated", "diagnostic"]);
+const LIFECYCLES = new Set(["starting", "ready", "busy", "stopping", "stopped", "failed"]);
+const OUTCOMES = new Set(["accepted", "completed", "rejected", "failed", "cancelled"]);
+const MAX_TEXT_BYTES = 256 * 1024;
+const MAX_COLLECTION = 10_000;
+export function assertAgentCapabilityContract(value) {
+    assertVersion(value.contractVersion);
+    assertUniqueEnum(value.commands, COMMANDS, "agent command capabilities");
+    assertUniqueEnum(value.events, EVENTS, "agent event capabilities");
+    if (typeof value.snapshots?.supported !== "boolean" || !Number.isSafeInteger(value.snapshots.maxBytes) || value.snapshots.maxBytes < 1024) {
+        throw new TypeError("agent snapshot capability is invalid");
+    }
+}
+export function assertAgentCommand(command, capabilities) {
+    assertVersion(command.contractVersion);
+    assertId(command.commandId, "agent command id");
+    assertId(command.sessionId, "agent command session id");
+    if (!COMMANDS.has(command.type))
+        throw new TypeError("agent command type is unknown");
+    if (capabilities !== undefined) {
+        assertAgentCapabilityContract(capabilities);
+        if (!capabilities.commands.includes(command.type))
+            throw new TypeError(`agent command capability is unavailable: ${command.type}`);
+    }
+    if (command.type === "prompt" || command.type === "steer" || command.type === "follow-up")
+        assertText(command.text, "agent command text");
+    if (command.type === "bash")
+        assertText(command.command, "agent bash command");
+    if (command.type === "replace-session" && command.source.kind === "resume")
+        assertText(command.source.sessionPath, "agent resume path");
+}
+export function assertAgentEvent(event, capabilities) {
+    assertVersion(event.contractVersion);
+    assertId(event.sessionId, "agent event session id");
+    assertNonNegative(event.sequence, "agent event sequence");
+    if (!EVENTS.has(event.type))
+        throw new TypeError("agent event type is unknown");
+    if (capabilities !== undefined) {
+        assertAgentCapabilityContract(capabilities);
+        if (!capabilities.events.includes(event.type))
+            throw new TypeError(`agent event capability is unavailable: ${event.type}`);
+    }
+    switch (event.type) {
+        case "lifecycle":
+            if (!LIFECYCLES.has(event.lifecycle))
+                throw new TypeError("agent lifecycle is invalid");
+            if (event.reason !== null)
+                assertText(event.reason, "agent lifecycle reason");
+            return;
+        case "content":
+            assertAgentMessage(event.content);
+            return;
+        case "command-outcome":
+            assertId(event.commandId, "agent outcome command id");
+            if (!OUTCOMES.has(event.outcome))
+                throw new TypeError("agent command outcome is invalid");
+            if (event.diagnostic !== null)
+                assertText(event.diagnostic, "agent outcome diagnostic");
+            return;
+        case "snapshot-invalidated":
+            assertNonNegative(event.expectedRevision, "agent expected snapshot revision");
+            return;
+        case "diagnostic":
+            assertId(event.code, "agent diagnostic code");
+            assertText(event.message, "agent diagnostic message");
+            if (typeof event.recoverable !== "boolean")
+                throw new TypeError("agent diagnostic recovery flag is invalid");
+    }
+}
+export function assertAgentSnapshot(snapshot) {
+    assertVersion(snapshot.contractVersion);
+    assertId(snapshot.snapshotId, "agent snapshot id");
+    assertId(snapshot.sessionId, "agent snapshot session id");
+    assertNonNegative(snapshot.revision, "agent snapshot revision");
+    assertNonNegative(snapshot.sequence, "agent snapshot sequence");
+    if (!LIFECYCLES.has(snapshot.lifecycle))
+        throw new TypeError("agent snapshot lifecycle is invalid");
+    assertAgentCapabilityContract(snapshot.capabilities);
+    if (!Array.isArray(snapshot.content) || snapshot.content.length > MAX_COLLECTION)
+        throw new RangeError("agent snapshot content collection is invalid");
+    for (const content of snapshot.content)
+        assertAgentEvent({ contractVersion: AGENT_ENGINE_CONTRACT_VERSION, sessionId: snapshot.sessionId, sequence: snapshot.sequence, type: "content", content });
+    if (!Array.isArray(snapshot.activeCommandIds) || snapshot.activeCommandIds.length > MAX_COLLECTION)
+        throw new RangeError("agent active command collection is invalid");
+    const ids = new Set();
+    for (const id of snapshot.activeCommandIds) {
+        assertId(id, "agent active command id");
+        if (ids.has(id))
+            throw new TypeError(`duplicate agent active command id: ${id}`);
+        ids.add(id);
+    }
+}
+function assertVersion(version) {
+    if (version !== AGENT_ENGINE_CONTRACT_VERSION)
+        throw new TypeError("unsupported agent engine contract version");
+}
+function assertUniqueEnum(values, allowed, label) {
+    if (!Array.isArray(values))
+        throw new TypeError(`${label} must be an array`);
+    const unique = new Set();
+    for (const value of values) {
+        if (!allowed.has(value))
+            throw new TypeError(`${label} contains an unknown value: ${String(value)}`);
+        if (unique.has(value))
+            throw new TypeError(`${label} contains a duplicate value: ${String(value)}`);
+        unique.add(value);
+    }
+}
+function assertId(value, label) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value))
+        throw new TypeError(`${label} is invalid`);
+}
+function assertText(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`${label} is invalid`);
+    assertPossiblyEmptyText(value, label);
+}
+function assertPossiblyEmptyText(value, label) {
+    if (typeof value !== "string" || Buffer.byteLength(value, "utf8") > MAX_TEXT_BYTES)
+        throw new RangeError(`${label} exceeds its byte limit`);
+}
+function assertNonNegative(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new TypeError(`${label} is invalid`);
+}

package/dist/src/foundation/launch-guardian/index.d.ts

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

package/dist/src/foundation/launch-guardian/index.js

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

package/dist/src/foundation/launch-guardian/main.d.ts

@@ -0,0 +1,31 @@
+import type { LaunchInstanceStopIntent, LaunchProfileId, SupervisorCommand } from "../lifecycle/index.js";
+import { type NativeProcessInspector, type ProcessContainment } from "../process-containment/index.js";
+interface GuardianControl {
+    connect(endpoint: string, timeoutMs?: number): Promise<unknown>;
+    command(command: SupervisorCommand): Promise<{
+        readonly ok: boolean;
+        readonly error?: {
+            readonly code: string;
+            readonly message: string;
+        };
+    }>;
+    on(event: "stopIntent", listener: (intent: LaunchInstanceStopIntent) => void): unknown;
+    on(event: "disconnect", listener: () => void): unknown;
+    off(event: "stopIntent", listener: (intent: LaunchInstanceStopIntent) => void): unknown;
+    off(event: "disconnect", listener: () => void): unknown;
+    close(): void;
+}
+export interface LaunchGuardianOptions {
+    readonly profileId: LaunchProfileId;
+    readonly releaseRoot: string;
+    readonly uiEntry: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly cwd?: string;
+    readonly helperPath?: string;
+    readonly inspector?: NativeProcessInspector;
+    readonly control?: GuardianControl;
+    readonly containment?: ProcessContainment;
+    readonly ensureHelper?: (path: string) => Promise<void>;
+}
+export declare function runLaunchGuardian(options: LaunchGuardianOptions): Promise<number>;
+export {};

package/dist/src/foundation/launch-guardian/main.js

@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { resolve } from "node:path";
+import { assertLaunchProfileId } from "../lifecycle/index.js";
+import { closeVerifiedContainment, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
+import { SupervisorClient } from "../protocol/index.js";
+import { resolveProductPaths } from "../supervision/index.js";
+export async function runLaunchGuardian(options) {
+    assertLaunchProfileId(options.profileId);
+    const environment = { ...(options.environment ?? process.env) };
+    const paths = resolveProductPaths(environment);
+    const instanceId = randomUUID();
+    const helperPath = options.helperPath ?? resolveProcessGuardianPath(options.releaseRoot, environment);
+    const inspector = options.inspector ?? platformInspector(helperPath);
+    await (options.ensureHelper ?? verifyProcessGuardianArtifact)(helperPath);
+    const guardianIdentity = await inspector.observe(process.pid);
+    if (!guardianIdentity)
+        throw diagnosticError("launch guardian cannot verify its own native process identity", "PROCESS_IDENTITY_UNAVAILABLE");
+    const client = options.control ?? new SupervisorClient(environment[PRODUCT_IDENTITY.environment.releaseId]);
+    await client.connect(paths.endpoint);
+    const containment = options.containment ?? new NativeGuardianContainment(instanceId, helperPath, resolve(paths.runtimeDir, "launch-instances", `${instanceId}.ready.json`));
+    const stop = stopRequests(client, instanceId);
+    let rootIdentity = null;
+    try {
+        await requireAccepted(client, {
+            type: "create-launch-instance",
+            requestId: randomUUID(),
+            instanceId,
+            profileId: options.profileId,
+            shutdownPolicy: "terminate-tree-on-close",
+            guardianIdentity,
+        });
+        let handle;
+        try {
+            handle = await containment.spawn(process.execPath, [options.uiEntry], {
+                cwd: options.cwd ?? process.cwd(),
+                environment: environmentEntries(environment),
+                ...(environment.TERM ? { terminalType: environment.TERM } : {}),
+            });
+            rootIdentity = handle.identity;
+            await requireAccepted(client, {
+                type: "activate-launch-instance",
+                requestId: randomUUID(),
+                instanceId,
+                rootIdentity,
+                containmentIdentity: containment.identity,
+            });
+        }
+        catch (error) {
+            const outcome = failureOutcome(error, "guardian-error");
+            await completeBestEffort(client, instanceId, "completed", outcome);
+            throw error;
+        }
+        const outcome = await Promise.race([
+            handle.outcome,
+            stop.requested.then(async (reason) => {
+                if (reason !== "supervisor-disconnect") {
+                    await requireAccepted(client, {
+                        type: "begin-launch-instance-stop",
+                        requestId: randomUUID(),
+                        instanceId,
+                        reason,
+                    });
+                }
+                if (!rootIdentity)
+                    return failureOutcome(new Error("launch root identity is unavailable"), "cleanup-error");
+                const result = await closeVerifiedContainment(containment, inspector, rootIdentity, reason);
+                await containment.close();
+                if (reason === "supervisor-disconnect" && result.outcome.kind === "stopped") {
+                    return {
+                        kind: "interrupted",
+                        reason,
+                        message: "supervisor disconnected after local launch-instance containment closed",
+                    };
+                }
+                return result.outcome;
+            }),
+        ]);
+        await containment.close();
+        if (outcome.kind !== "interrupted" || outcome.reason !== "supervisor-disconnect") {
+            await completeBestEffort(client, instanceId, outcome.kind === "interrupted" || outcome.kind === "cleanup-error" ? "interrupted" : "completed", outcome);
+        }
+        return exitCode(outcome);
+    }
+    catch (error) {
+        await containment.close().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        stop.dispose();
+        client.close();
+    }
+}
+function platformInspector(helperPath) {
+    if (process.platform === "win32")
+        return new WindowsNativeProcessInspector(helperPath);
+    if (process.platform === "linux")
+        return new LinuxNativeProcessInspector();
+    throw diagnosticError(`launch-instance process containment is unsupported on ${process.platform}`, "CONTAINMENT_UNSUPPORTED");
+}
+function stopRequests(client, instanceId) {
+    let resolveStop;
+    let settled = false;
+    const requested = new Promise(resolvePromise => { resolveStop = resolvePromise; });
+    const request = (reason) => {
+        if (settled)
+            return;
+        settled = true;
+        resolveStop(reason);
+    };
+    const onStopIntent = (intent) => {
+        if (intent.instanceId === instanceId)
+            request(intent.reason);
+    };
+    const onDisconnect = () => request("supervisor-disconnect");
+    const onSigterm = () => request("user-request");
+    const onSigint = () => undefined;
+    client.on("stopIntent", onStopIntent);
+    client.on("disconnect", onDisconnect);
+    process.once("SIGTERM", onSigterm);
+    process.on("SIGINT", onSigint);
+    return {
+        requested,
+        dispose() {
+            client.off("stopIntent", onStopIntent);
+            client.off("disconnect", onDisconnect);
+            process.off("SIGTERM", onSigterm);
+            process.off("SIGINT", onSigint);
+        },
+    };
+}
+async function requireAccepted(client, command) {
+    const result = await client.command(command);
+    if (!result.ok)
+        throw diagnosticError(result.error?.message ?? `supervisor rejected ${command.type}`, result.error?.code ?? "SUPERVISOR_REJECTED");
+}
+async function completeBestEffort(client, instanceId, terminalState, outcome) {
+    await requireAccepted(client, {
+        type: "complete-launch-instance",
+        requestId: randomUUID(),
+        instanceId,
+        terminalState,
+        outcome,
+    }).catch(() => undefined);
+}
+function environmentEntries(environment) {
+    return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
+}
+function failureOutcome(error, kind) {
+    return {
+        kind,
+        message: error instanceof Error ? error.message : String(error),
+        code: error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null,
+    };
+}
+function exitCode(outcome) {
+    if (outcome.kind === "exited")
+        return outcome.exitCode;
+    if (outcome.kind === "stopped")
+        return 0;
+    return 1;
+}
+function diagnosticError(message, code) {
+    return Object.assign(new Error(`A1: ${message}`), { code });
+}

package/dist/src/foundation/lifecycle/commands.d.ts

@@ -0,0 +1,40 @@
+import type { LaunchInstanceId, LaunchInstanceOutcome, LaunchInstanceShutdownPolicy, LaunchInstanceStopReason, ProcessContainmentIdentity } from "./launch-instance.js";
+import type { LaunchProfileId, NativeProcessIdentity, RequestId } from "./model.js";
+export type SupervisorCommand = {
+    readonly type: "create-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly profileId: LaunchProfileId;
+    readonly shutdownPolicy: LaunchInstanceShutdownPolicy;
+    readonly guardianIdentity: NativeProcessIdentity;
+} | {
+    readonly type: "activate-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly rootIdentity: NativeProcessIdentity;
+    readonly containmentIdentity: ProcessContainmentIdentity;
+} | {
+    readonly type: "begin-launch-instance-stop";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly reason: LaunchInstanceStopReason;
+} | {
+    readonly type: "complete-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly terminalState: "completed" | "interrupted";
+    readonly outcome: LaunchInstanceOutcome;
+} | {
+    readonly type: "reconcile-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+} | {
+    readonly type: "resynchronize";
+    readonly requestId: RequestId;
+};
+export interface LaunchInstanceStopIntent {
+    readonly type: "stop-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly reason: LaunchInstanceStopReason;
+}

package/dist/src/foundation/lifecycle/commands.js

@@ -0,0 +1 @@
+export {};

package/dist/src/foundation/lifecycle/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./commands.js";
+export * from "./launch-instance.js";
 export * from "./model.js";
 export * from "./paths.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/foundation/lifecycle/index.js

@@ -1,3 +1,4 @@
+export * from "./commands.js";
+export * from "./launch-instance.js";
 export * from "./model.js";
 export * from "./paths.js";
-//# sourceMappingURL=index.js.map

package/dist/src/foundation/lifecycle/launch-instance.d.ts

@@ -0,0 +1,46 @@
+import type { LaunchProfileId, NativeProcessIdentity } from "./model.js";
+export type LaunchInstanceId = string;
+export type LaunchInstanceState = "requested" | "active" | "stopping" | "completed" | "interrupted";
+export type LaunchInstanceShutdownPolicy = "terminate-tree-on-close";
+export type LaunchInstanceStopReason = "owner-disconnect" | "supervisor-disconnect" | "user-request" | "update";
+export interface ProcessContainmentIdentity {
+    readonly provider: string;
+    readonly token: string;
+}
+export type LaunchInstanceOutcome = {
+    readonly kind: "exited";
+    readonly exitCode: number;
+} | {
+    readonly kind: "signaled";
+    readonly signal: string;
+} | {
+    readonly kind: "stopped";
+    readonly reason: LaunchInstanceStopReason;
+} | {
+    readonly kind: "spawn-error" | "guardian-error" | "cleanup-error";
+    readonly message: string;
+    readonly code: string | null;
+} | {
+    readonly kind: "interrupted";
+    readonly reason: "owner-disconnect" | "supervisor-disconnect" | "guardian-exit" | "legacy-migration";
+    readonly message: string;
+};
+export interface LaunchInstance {
+    readonly id: LaunchInstanceId;
+    readonly ownerClientId: string;
+    readonly profileId: LaunchProfileId;
+    readonly state: LaunchInstanceState;
+    readonly shutdownPolicy: LaunchInstanceShutdownPolicy;
+    readonly guardianIdentity: NativeProcessIdentity;
+    readonly rootIdentity: NativeProcessIdentity | null;
+    readonly containmentIdentity: ProcessContainmentIdentity | null;
+    readonly createdAt: string;
+    readonly activatedAt: string | null;
+    readonly stoppingAt: string | null;
+    readonly completedAt: string | null;
+    readonly outcome: LaunchInstanceOutcome | null;
+}
+export declare function assertLaunchInstance(instance: LaunchInstance): void;
+export declare function assertLaunchInstanceTransition(previous: LaunchInstance, next: LaunchInstance): void;
+export declare function assertProcessContainmentIdentity(identity: ProcessContainmentIdentity): void;
+export declare function assertLaunchInstanceOutcome(outcome: LaunchInstanceOutcome): void;

package/dist/src/foundation/lifecycle/launch-instance.js

@@ -0,0 +1,134 @@
+import { assertLaunchProfileId, assertNativeProcessIdentity } from "./model.js";
+const ALLOWED_TRANSITIONS = {
+    requested: ["active", "completed", "interrupted"],
+    active: ["stopping", "completed", "interrupted"],
+    stopping: ["completed", "interrupted"],
+    completed: [],
+    interrupted: [],
+};
+export function assertLaunchInstance(instance) {
+    assertIdentifier(instance.id, "launch instance identity");
+    assertIdentifier(instance.ownerClientId, "launch instance owner identity");
+    assertLaunchProfileId(instance.profileId);
+    if (!(instance.state in ALLOWED_TRANSITIONS))
+        throw new TypeError(`invalid launch instance state: ${String(instance.state)}`);
+    if (instance.shutdownPolicy !== "terminate-tree-on-close")
+        throw new TypeError("launch instance shutdown policy must terminate its process tree on close");
+    assertNativeProcessIdentity(instance.guardianIdentity);
+    if (instance.rootIdentity !== null)
+        assertNativeProcessIdentity(instance.rootIdentity);
+    if (instance.containmentIdentity !== null)
+        assertProcessContainmentIdentity(instance.containmentIdentity);
+    assertTimestamp(instance.createdAt, "launch instance creation time");
+    assertOptionalTimestamp(instance.activatedAt, "launch instance activation time");
+    assertOptionalTimestamp(instance.stoppingAt, "launch instance stopping time");
+    assertOptionalTimestamp(instance.completedAt, "launch instance completion time");
+    if (instance.outcome !== null)
+        assertLaunchInstanceOutcome(instance.outcome);
+    if (instance.state === "requested") {
+        if (instance.rootIdentity !== null || instance.containmentIdentity !== null || instance.activatedAt !== null) {
+            throw new TypeError("requested launch instance cannot have active runtime ownership");
+        }
+        if (instance.stoppingAt !== null || instance.completedAt !== null || instance.outcome !== null) {
+            throw new TypeError("requested launch instance cannot have stopping or terminal state");
+        }
+        return;
+    }
+    if (instance.state === "active" || instance.state === "stopping") {
+        if (instance.rootIdentity === null || instance.containmentIdentity === null || instance.activatedAt === null) {
+            throw new TypeError(`${instance.state} launch instance requires root and containment ownership`);
+        }
+        if (instance.completedAt !== null || instance.outcome !== null)
+            throw new TypeError(`${instance.state} launch instance cannot have a terminal outcome`);
+        if (instance.state === "active" && instance.stoppingAt !== null)
+            throw new TypeError("active launch instance cannot have a stopping time");
+        if (instance.state === "stopping" && instance.stoppingAt === null)
+            throw new TypeError("stopping launch instance requires a stopping time");
+        return;
+    }
+    if (instance.completedAt === null || instance.outcome === null)
+        throw new TypeError("terminal launch instance requires completion time and outcome");
+    if (instance.state === "completed" && instance.outcome.kind === "interrupted")
+        throw new TypeError("completed launch instance cannot carry an interrupted outcome");
+    if (instance.state === "interrupted" && instance.outcome.kind !== "interrupted" && instance.outcome.kind !== "cleanup-error") {
+        throw new TypeError("interrupted launch instance requires an interrupted or cleanup-error outcome");
+    }
+}
+export function assertLaunchInstanceTransition(previous, next) {
+    assertLaunchInstance(previous);
+    assertLaunchInstance(next);
+    if (previous.id !== next.id || previous.ownerClientId !== next.ownerClientId || previous.profileId !== next.profileId) {
+        throw new TypeError("launch instance identity and ownership are immutable");
+    }
+    if (previous.shutdownPolicy !== next.shutdownPolicy
+        || !sameProcessIdentity(previous.guardianIdentity, next.guardianIdentity)
+        || previous.createdAt !== next.createdAt) {
+        throw new TypeError("launch instance guardian, policy, and creation identity are immutable");
+    }
+    const allowedTransitions = ALLOWED_TRANSITIONS[previous.state];
+    if (!allowedTransitions.includes(next.state)) {
+        throw new TypeError(`invalid launch instance transition: ${previous.state} -> ${next.state}`);
+    }
+    if (previous.rootIdentity !== null && !sameProcessIdentity(previous.rootIdentity, next.rootIdentity)) {
+        throw new TypeError("launch instance root identity is immutable after activation");
+    }
+    if (previous.containmentIdentity !== null && !sameContainmentIdentity(previous.containmentIdentity, next.containmentIdentity)) {
+        throw new TypeError("launch instance containment identity is immutable after activation");
+    }
+}
+export function assertProcessContainmentIdentity(identity) {
+    assertIdentifier(identity.provider, "process containment provider");
+    assertIdentifier(identity.token, "process containment token");
+}
+export function assertLaunchInstanceOutcome(outcome) {
+    if (outcome.kind === "exited") {
+        if (!Number.isSafeInteger(outcome.exitCode))
+            throw new TypeError("launch instance exit code must be a safe integer");
+        return;
+    }
+    if (outcome.kind === "signaled") {
+        assertIdentifier(outcome.signal, "launch instance signal");
+        return;
+    }
+    if (outcome.kind === "stopped") {
+        if (!["owner-disconnect", "supervisor-disconnect", "user-request", "update"].includes(outcome.reason)) {
+            throw new TypeError("invalid launch instance stop reason");
+        }
+        return;
+    }
+    if (outcome.kind === "interrupted") {
+        if (!["owner-disconnect", "supervisor-disconnect", "guardian-exit", "legacy-migration"].includes(outcome.reason)) {
+            throw new TypeError("invalid launch instance interruption reason");
+        }
+        assertDiagnostic(outcome.message, "launch instance interruption message");
+        return;
+    }
+    if (outcome.kind !== "spawn-error" && outcome.kind !== "guardian-error" && outcome.kind !== "cleanup-error") {
+        throw new TypeError(`invalid launch instance outcome: ${String(outcome.kind)}`);
+    }
+    assertDiagnostic(outcome.message, "launch instance failure message");
+    if (outcome.code !== null)
+        assertIdentifier(outcome.code, "launch instance failure code");
+}
+function sameProcessIdentity(left, right) {
+    return right !== null && left.pid === right.pid && left.startIdentity === right.startIdentity;
+}
+function sameContainmentIdentity(left, right) {
+    return right !== null && left.provider === right.provider && left.token === right.token;
+}
+function assertIdentifier(value, name) {
+    if (!value || value.length > 512 || value.includes("\0"))
+        throw new TypeError(`${name} must be non-empty, bounded, and contain no null byte`);
+}
+function assertDiagnostic(value, name) {
+    if (!value || value.length > 4_096 || value.includes("\0"))
+        throw new TypeError(`${name} must be non-empty, bounded, and contain no null byte`);
+}
+function assertTimestamp(value, name) {
+    if (!value || !Number.isFinite(Date.parse(value)))
+        throw new TypeError(`${name} must be a valid timestamp`);
+}
+function assertOptionalTimestamp(value, name) {
+    if (value !== null)
+        assertTimestamp(value, name);
+}

package/dist/src/foundation/lifecycle/model.d.ts

@@ -1,8 +1,7 @@
-export type LaunchProfileId = "addone" | "pi" | "sandbox";
+export type LaunchProfileId = "a1" | "pi" | "sandbox";
 export type GenerationId = string;
 export type DriverProfileId = string;
 export type RequestId = string;
-export type ForegroundTerminalLeaseId = string;
 export interface TerminalDimensions {
     readonly columns: number;
     readonly rows: number;
@@ -42,55 +41,20 @@ export type TransparentTerminalLifecycleOutcome = {
     readonly message: string;
     readonly code: string | null;
 };
-export type ForegroundTerminalLeaseState = "requested" | "active" | "released";
-export interface ForegroundTerminalLease {
-    readonly id: ForegroundTerminalLeaseId;
-    readonly ownerId: string;
-    readonly profile: TransparentTerminalLaunchProfile;
-    readonly state: ForegroundTerminalLeaseState;
-    readonly generationId: GenerationId | null;
-    readonly processIdentity: NativeProcessIdentity | null;
-    readonly acquiredAt: string;
-    readonly heartbeatAt: string | null;
-    readonly releasedAt: string | null;
-    readonly outcome: TransparentTerminalLifecycleOutcome | null;
-}
 export interface SupervisorSnapshot {
     readonly revision: number;
+    readonly activeInstances: readonly {
+        readonly id: string;
+        readonly profileId: LaunchProfileId;
+        readonly state: "requested" | "active" | "stopping";
+    }[];
 }
-export type SupervisorCommand = {
-    readonly type: "acquire-foreground-terminal-lease";
-    readonly requestId: RequestId;
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly ownerId: string;
-    readonly profile: TransparentTerminalLaunchProfile;
-} | {
-    readonly type: "activate-foreground-terminal-lease";
-    readonly requestId: RequestId;
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly generationId: GenerationId;
-    readonly processIdentity: NativeProcessIdentity;
-} | {
-    readonly type: "heartbeat-foreground-terminal-lease";
-    readonly requestId: RequestId;
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly processIdentity: NativeProcessIdentity;
-} | {
-    readonly type: "release-foreground-terminal-lease";
-    readonly requestId: RequestId;
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly processIdentity: NativeProcessIdentity | null;
-    readonly outcome: TransparentTerminalLifecycleOutcome;
-} | {
-    readonly type: "resynchronize";
-    readonly requestId: RequestId;
-};
 export interface CommandResult {
     readonly requestId: RequestId;
     readonly ok: boolean;
     readonly revision: number;
     readonly error?: {
-        readonly code: "invalid-command" | "not-found" | "stale-generation" | "capability-error" | "driver-error";
+        readonly code: "invalid-command" | "not-found" | "stale-generation" | "capability-error" | "containment-unsupported" | "ownership-error" | "driver-error";
         readonly message: string;
     };
 }
@@ -98,4 +62,3 @@ export declare function assertLaunchProfileId(value: unknown): asserts value is
 export declare function assertDimensions(dimensions: TerminalDimensions): void;
 export declare function assertTransparentTerminalLaunchProfile(profile: TransparentTerminalLaunchProfile): void;
 export declare function assertNativeProcessIdentity(identity: NativeProcessIdentity): void;
-//# sourceMappingURL=model.d.ts.map

package/dist/src/foundation/lifecycle/model.js

@@ -1,6 +1,7 @@
+import { PRODUCT_TEXT } from "../../product-identity.js";
 export function assertLaunchProfileId(value) {
-    if (value !== "addone" && value !== "pi" && value !== "sandbox")
-        throw new TypeError(`invalid AddOne launch profile: ${String(value)}`);
+    if (value !== "a1" && value !== "pi" && value !== "sandbox")
+        throw new TypeError(PRODUCT_TEXT.diagnostic(`launch profile is invalid: ${String(value)}`));
 }
 export function assertDimensions(dimensions) {
     if (!Number.isInteger(dimensions.columns) || dimensions.columns < 2 || dimensions.columns > 500) {
@@ -37,4 +38,3 @@ export function assertNativeProcessIdentity(identity) {
         throw new TypeError("invalid native process identity");
     }
 }
-//# sourceMappingURL=model.js.map