@timurproko/a1 0.1.1-dev.5 → 0.1.1-dev.7

package/dist/src/foundation/process-containment/contracts.js

@@ -0,0 +1,35 @@
+export async function closeVerifiedContainment(containment, inspector, rootIdentity, reason, deadlineMs = 1_500) {
+    if (!await ownershipMatches(containment, inspector, rootIdentity)) {
+        return ownershipMismatch("refusing graceful cleanup because launch-instance ownership changed");
+    }
+    await containment.stop(false);
+    if (await containment.waitForEmpty(deadlineMs)) {
+        return { outcome: { kind: "stopped", reason }, graceful: true, forced: false };
+    }
+    if (!await ownershipMatches(containment, inspector, rootIdentity)) {
+        return ownershipMismatch("refusing forced cleanup because launch-instance ownership changed");
+    }
+    await containment.stop(true);
+    if (await containment.waitForEmpty(deadlineMs)) {
+        return { outcome: { kind: "stopped", reason }, graceful: false, forced: true };
+    }
+    return {
+        outcome: {
+            kind: "cleanup-error",
+            message: "launch-instance process tree did not exit within the bounded cleanup deadline",
+            code: "CONTAINMENT_CLEANUP_TIMEOUT",
+        },
+        graceful: false,
+        forced: true,
+    };
+}
+async function ownershipMatches(containment, inspector, rootIdentity) {
+    return await inspector.matches(rootIdentity) && await containment.contains(rootIdentity);
+}
+function ownershipMismatch(message) {
+    return {
+        outcome: { kind: "cleanup-error", message, code: "PROCESS_IDENTITY_MISMATCH" },
+        graceful: false,
+        forced: false,
+    };
+}

package/dist/src/foundation/process-containment/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./artifact.js";
+export * from "./contracts.js";
+export * from "./linux-process-inspector.js";
+export * from "./native-guardian-containment.js";
+export * from "./windows-process-inspector.js";

package/dist/src/foundation/process-containment/index.js

@@ -0,0 +1,5 @@
+export * from "./artifact.js";
+export * from "./contracts.js";
+export * from "./linux-process-inspector.js";
+export * from "./native-guardian-containment.js";
+export * from "./windows-process-inspector.js";

package/dist/src/foundation/process-containment/linux-process-inspector.d.ts

@@ -0,0 +1,6 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+export declare class LinuxNativeProcessInspector implements NativeProcessInspector {
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

package/dist/src/foundation/process-containment/linux-process-inspector.js

@@ -0,0 +1,26 @@
+import { readFile } from "node:fs/promises";
+export class LinuxNativeProcessInspector {
+    async observe(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new TypeError("inspected PID must be a positive safe integer");
+        let stat;
+        try {
+            stat = await readFile(`/proc/${pid}/stat`, "utf8");
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+        const commandEnd = stat.lastIndexOf(")");
+        const fields = commandEnd >= 0 ? stat.slice(commandEnd + 1).trim().split(/\s+/) : [];
+        const startTicks = fields[19];
+        if (!startTicks || !/^\d+$/.test(startTicks))
+            throw new Error("process stat has no valid start-time field");
+        return { pid, startIdentity: `linux-proc-start:${startTicks}` };
+    }
+    async matches(identity) {
+        const observed = await this.observe(identity.pid);
+        return observed !== null && observed.startIdentity === identity.startIdentity;
+    }
+}

package/dist/src/foundation/process-containment/native-guardian-containment.d.ts

@@ -0,0 +1,16 @@
+import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+import type { ContainedProcessHandle, ContainedSpawnOptions, ProcessContainment } from "./contracts.js";
+export declare class NativeGuardianContainment implements ProcessContainment {
+    #private;
+    readonly instanceId: string;
+    readonly helperPath: string;
+    readonly statusPath: string;
+    constructor(instanceId: string, helperPath: string, statusPath: string);
+    get identity(): ProcessContainmentIdentity;
+    spawn(executable: string, arguments_: readonly string[], options: ContainedSpawnOptions): Promise<ContainedProcessHandle>;
+    contains(identity: NativeProcessIdentity): Promise<boolean>;
+    stop(force: boolean): Promise<void>;
+    waitForEmpty(timeoutMs: number): Promise<boolean>;
+    close(): Promise<void>;
+}
+export declare function resolveProcessGuardianPath(releaseRoot: string, environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, architecture?: string): string;

package/dist/src/foundation/process-containment/native-guardian-containment.js

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export class NativeGuardianContainment {
+    instanceId;
+    helperPath;
+    statusPath;
+    #identity;
+    #helper = null;
+    #rootIdentity = null;
+    #outcome = null;
+    constructor(instanceId, helperPath, statusPath) {
+        this.instanceId = instanceId;
+        this.helperPath = helperPath;
+        this.statusPath = statusPath;
+        this.#identity = { provider: "native-guardian-pending", token: instanceId };
+    }
+    get identity() {
+        return this.#identity;
+    }
+    async spawn(executable, arguments_, options) {
+        if (this.#helper)
+            throw new Error("process containment already has a root runtime");
+        await mkdir(dirname(this.statusPath), { recursive: true, mode: 0o700 });
+        await rm(this.statusPath, { force: true });
+        const helper = spawn(this.helperPath, [
+            "--parent-pid", String(process.pid),
+            "--instance", this.instanceId,
+            "--status-file", this.statusPath,
+            "--", executable, ...arguments_,
+        ], {
+            cwd: options.cwd,
+            env: { ...options.environment, ...(options.terminalType ? { TERM: options.terminalType } : {}) },
+            shell: false,
+            stdio: "inherit",
+            windowsHide: false,
+        });
+        this.#helper = helper;
+        this.#outcome = helperOutcome(helper);
+        const status = await waitForReadyStatus(this.statusPath, this.#outcome, 5_000);
+        this.#rootIdentity = { pid: status.pid, startIdentity: status.startIdentity };
+        this.#identity = { provider: status.containmentProvider, token: status.containmentToken };
+        return { identity: this.#rootIdentity, outcome: this.#outcome };
+    }
+    async contains(identity) {
+        return this.#rootIdentity !== null
+            && identity.pid === this.#rootIdentity.pid
+            && identity.startIdentity === this.#rootIdentity.startIdentity;
+    }
+    async stop(force) {
+        const root = this.#rootIdentity;
+        if (!root)
+            return;
+        try {
+            process.kill(root.pid, force ? "SIGKILL" : "SIGTERM");
+        }
+        catch { }
+    }
+    async waitForEmpty(timeoutMs) {
+        if (!this.#helper || this.#helper.exitCode !== null || this.#helper.signalCode !== null)
+            return true;
+        return await new Promise(resolvePromise => {
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            timer.unref();
+            const finish = (empty) => {
+                clearTimeout(timer);
+                this.#helper?.off("close", onClose);
+                resolvePromise(empty);
+            };
+            const onClose = () => finish(true);
+            this.#helper?.once("close", onClose);
+        });
+    }
+    async close() {
+        const helper = this.#helper;
+        if (helper && helper.exitCode === null && helper.signalCode === null)
+            helper.kill("SIGKILL");
+        await this.waitForEmpty(1_500);
+        await rm(this.statusPath, { force: true });
+    }
+}
+export function resolveProcessGuardianPath(releaseRoot, environment = process.env, platform = process.platform, architecture = process.arch) {
+    const override = environment[PRODUCT_IDENTITY.environment.processGuardianPath]?.trim();
+    if (override)
+        return resolve(override);
+    const executable = platform === "win32"
+        ? `${PRODUCT_IDENTITY.artifacts.processGuardianExecutable}.exe`
+        : PRODUCT_IDENTITY.artifacts.processGuardianExecutable;
+    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, executable);
+}
+function helperOutcome(helper) {
+    return new Promise(resolvePromise => {
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise(outcome);
+        };
+        helper.once("error", error => settle({ kind: "guardian-error", message: error.message, code: errorCode(error) }));
+        helper.once("close", (code, signal) => {
+            if (signal)
+                settle({ kind: "signaled", signal });
+            else
+                settle({ kind: "exited", exitCode: code ?? 1 });
+        });
+    });
+}
+async function waitForReadyStatus(path, outcome, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let terminalOutcome = null;
+    void outcome.then(value => { terminalOutcome = value; });
+    while (Date.now() < deadline) {
+        try {
+            const value = JSON.parse(await readFile(path, "utf8"));
+            if (isReadyStatus(value))
+                return value;
+            throw new Error("process guardian published invalid ready status");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        if (terminalOutcome)
+            throw new Error(`process guardian exited before readiness: ${JSON.stringify(terminalOutcome)}`);
+        await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
+    }
+    throw new Error(`process guardian did not publish readiness within ${timeoutMs}ms`);
+}
+function isReadyStatus(value) {
+    return Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+        && typeof value.startIdentity === "string" && value.startIdentity.length > 0
+        && typeof value.containmentProvider === "string" && value.containmentProvider.length > 0
+        && typeof value.containmentToken === "string" && value.containmentToken.length > 0;
+}
+function errorCode(error) {
+    return "code" in error && typeof error.code === "string" ? error.code : null;
+}

package/dist/src/foundation/process-containment/windows-process-inspector.d.ts

@@ -0,0 +1,17 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+export interface InspectorCommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface InspectorCommandRunner {
+    run(executable: string, arguments_: readonly string[]): Promise<InspectorCommandResult>;
+}
+export declare class WindowsNativeProcessInspector implements NativeProcessInspector {
+    readonly helperPath: string;
+    private readonly runner;
+    constructor(helperPath: string, runner?: InspectorCommandRunner);
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

package/dist/src/foundation/process-containment/windows-process-inspector.js

@@ -0,0 +1,53 @@
+import { execFile } from "node:child_process";
+export class WindowsNativeProcessInspector {
+    helperPath;
+    runner;
+    constructor(helperPath, runner = defaultRunner) {
+        this.helperPath = helperPath;
+        this.runner = runner;
+        if (!helperPath || helperPath.includes("\0"))
+            throw new TypeError("process guardian helper path is invalid");
+    }
+    async observe(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new TypeError("inspected PID must be a positive safe integer");
+        const result = await this.runner.run(this.helperPath, ["--inspect-pid", String(pid)]);
+        if (result.exitCode === 3)
+            return null;
+        if (result.exitCode !== 0) {
+            const detail = result.stderr.trim() || `helper exited ${result.exitCode}`;
+            throw Object.assign(new Error(`cannot inspect native process identity: ${detail}`), { code: "PROCESS_INSPECTION_FAILED" });
+        }
+        let value;
+        try {
+            value = JSON.parse(result.stdout);
+        }
+        catch {
+            throw Object.assign(new Error("process guardian returned malformed identity data"), { code: "PROCESS_INSPECTION_INVALID" });
+        }
+        if (!isIdentity(value) || value.pid !== pid || !value.startIdentity.startsWith("windows-filetime:")) {
+            throw Object.assign(new Error("process guardian returned mismatched identity data"), { code: "PROCESS_INSPECTION_INVALID" });
+        }
+        return value;
+    }
+    async matches(identity) {
+        const observed = await this.observe(identity.pid);
+        return observed !== null && observed.startIdentity === identity.startIdentity;
+    }
+}
+const defaultRunner = {
+    async run(executable, arguments_) {
+        return await new Promise(resolvePromise => {
+            execFile(executable, [...arguments_], { windowsHide: true, timeout: 2_000, maxBuffer: 8 * 1_024 }, (error, stdout, stderr) => {
+                const exitCode = error && "code" in error && typeof error.code === "number" ? error.code : error ? 1 : 0;
+                resolvePromise({ exitCode, stdout, stderr });
+            });
+        });
+    },
+};
+function isIdentity(value) {
+    return typeof value === "object" && value !== null
+        && "pid" in value && Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+        && "startIdentity" in value && typeof value.startIdentity === "string"
+        && value.startIdentity.length > 0 && value.startIdentity.length <= 512 && !value.startIdentity.includes("\0");
+}

package/dist/src/foundation/protocol/client.d.ts

@@ -1,7 +1,8 @@
 import { EventEmitter } from "node:events";
-import type { CommandResult, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
+import type { CommandResult, LaunchInstanceStopIntent, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
 interface ClientEvents {
     snapshot: [SupervisorSnapshot];
+    stopIntent: [LaunchInstanceStopIntent];
     disconnect: [];
 }
 export declare class SupervisorClient extends EventEmitter<ClientEvents> {

package/dist/src/foundation/protocol/client.js

@@ -91,6 +91,9 @@ export class SupervisorClient extends EventEmitter {
                                 pending.resolve(message.result);
                             }
                         }
+                        else if (message.type === "stop-launch-instance" && message.instanceId && message.requestId && message.reason) {
+                            this.emit("stopIntent", message);
+                        }
                         else if (message.type === "protocol-error") {
                             fail(new Error(message.message ?? "protocol error"));
                         }

package/dist/src/foundation/protocol/messages.d.ts

@@ -1,7 +1,7 @@
-import type { CommandResult, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
+import type { CommandResult, LaunchInstanceStopIntent, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
 export declare const CONTROL_ENVELOPE: string;
 export declare const CONTROL_ENVELOPE_REVISION: 1;
-export declare const REQUIRED_CONTROL_FEATURES: readonly ["handshake.features.v1", "snapshot.revision.v1", "commands.request-identity.v1", "generation.lifecycle.v1", "terminal.foreground-lease.v1"];
+export declare const REQUIRED_CONTROL_FEATURES: readonly ["handshake.features.v1", "snapshot.revision.v1", "commands.request-identity.v1", "generation.lifecycle.v1", "launch.instance-lifecycle.v1"];
 export declare const OPTIONAL_CONTROL_FEATURES: readonly ["messages.unknown-additive-ignore.v1", "snapshot.resynchronize.v1"];
 export type ControlFeature = string;
 export declare const GENERATED_CONTRACT_DIGEST: string;
@@ -41,12 +41,12 @@ export type ServerMessage = {
     readonly type: "release-ownership-result";
     readonly released: boolean;
     readonly reason: string;
-    readonly liveGenerationIds: readonly string[];
+    readonly liveInstanceIds: readonly string[];
 } | {
     readonly type: "release-update-result";
     readonly accepted: boolean;
     readonly reason: string;
-    readonly liveGenerationIds: readonly string[];
+    readonly liveInstanceIds: readonly string[];
 } | ({
     readonly type: "server-hello";
     readonly supervisorId: string;
@@ -60,7 +60,7 @@ export type ServerMessage = {
 } | {
     readonly type: "command-result";
     readonly result: CommandResult;
-} | {
+} | LaunchInstanceStopIntent | {
     readonly type: "protocol-error";
     readonly code: string;
     readonly message: string;

package/dist/src/foundation/protocol/messages.js

@@ -7,7 +7,7 @@ export const REQUIRED_CONTROL_FEATURES = [
     "snapshot.revision.v1",
     "commands.request-identity.v1",
     "generation.lifecycle.v1",
-    "terminal.foreground-lease.v1",
+    "launch.instance-lifecycle.v1",
 ];
 export const OPTIONAL_CONTROL_FEATURES = [
     "messages.unknown-additive-ignore.v1",

package/dist/src/foundation/release/bootstrap.js

@@ -55,7 +55,7 @@ export async function runBootstrap(options) {
     probe = endpoint ? await probeOwnership(endpoint) : "dead";
     let decision = selectCohortLaunch(candidate, state, endpoint, probe);
     if (decision.action === "blocked") {
-        await stateStore.blockPending(decision.reason, endpoint?.ownership.liveGenerationIds ?? []);
+        await stateStore.blockPending(decision.reason, endpoint?.ownership.liveInstanceIds ?? []);
         output.write(`${PRODUCT_TEXT.diagnostic(`startup is blocked to preserve uncertain live ownership: ${decision.reason}`)}\n`);
         return 1;
     }
@@ -73,7 +73,7 @@ export async function runBootstrap(options) {
     if (decision.action === "launch-retained-ui") {
         const retained = await verifyMaterializedRelease(decision.releaseRoot, undefined, resolve(paths.dataDir, "releases"));
         if (decision.recordPending && endpoint) {
-            await stateStore.blockPending("candidate activation deferred by live non-resumable generations", endpoint.ownership.nonResumableGenerationIds);
+            await stateStore.blockPending("candidate activation deferred by live non-resumable instances", endpoint.ownership.nonResumableInstanceIds);
         }
         const code = await launchUi(retained, environment);
         if (decision.recordPending)
@@ -85,12 +85,12 @@ export async function runBootstrap(options) {
         await stateStore.approve(candidate.releaseId, diagnosticsPath);
         const released = await requestIdleOwnershipRelease(endpoint, candidate.releaseId, 2_000);
         if (!released) {
-            await stateStore.blockPending("idle supervisor did not verify ownership release", endpoint.ownership.liveGenerationIds);
+            await stateStore.blockPending("idle supervisor did not verify ownership release", endpoint.ownership.liveInstanceIds);
             output.write(`${PRODUCT_TEXT.diagnostic("could not verify idle cohort ownership release; the retained release remains selected.")}\n`);
             return 1;
         }
         if (!await releaseVerifiedIdleOwner(endpoint, paths.dataDir)) {
-            await stateStore.blockPending("idle supervisor acknowledged release but did not terminate", endpoint.ownership.liveGenerationIds);
+            await stateStore.blockPending("idle supervisor acknowledged release but did not terminate", endpoint.ownership.liveInstanceIds);
             output.write(`${PRODUCT_TEXT.diagnostic("could not complete bounded idle cohort shutdown; the candidate remains pending.")}\n`);
             return 1;
         }
@@ -152,7 +152,7 @@ export async function startSupervisor(release, environment) {
     child.unref();
 }
 async function launchUi(release, environment) {
-    const entry = await resolveReleaseEntryPoint(release, "bin/a1-ui.js");
+    const entry = await resolveReleaseEntryPoint(release, "bin/a1-guardian.js");
     return await new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(process.execPath, [entry], {
             env: releaseEnvironment(environment, release),
@@ -184,13 +184,29 @@ export async function waitForVerifiedEndpoint(path, release, timeoutMs) {
 export async function readEndpointMetadata(path) {
     try {
         const value = JSON.parse(await readFile(path, "utf8"));
+        const ownership = value.ownership;
+        const liveInstanceIds = Array.isArray(ownership?.liveInstanceIds)
+            ? ownership.liveInstanceIds
+            : Array.isArray(ownership?.liveGenerationIds) ? ownership.liveGenerationIds : null;
+        const nonResumableInstanceIds = Array.isArray(ownership?.nonResumableInstanceIds)
+            ? ownership.nonResumableInstanceIds
+            : Array.isArray(ownership?.nonResumableGenerationIds) ? ownership.nonResumableGenerationIds : null;
+        const uncertainInstanceIds = Array.isArray(ownership?.uncertainInstanceIds) ? ownership.uncertainInstanceIds : [];
         if (!value || value.schema !== PRODUCT_IDENTITY.protocol.supervisorSchema || typeof value.supervisorId !== "string" || typeof value.endpoint !== "string" || !Number.isSafeInteger(value.pid)
             || typeof value.pidStartIdentity !== "string" || typeof value.bootNonce !== "string" || typeof value.releaseId !== "string"
-            || typeof value.releaseRoot !== "string" || typeof value.contentDigest !== "string" || !value.ownership
-            || !Array.isArray(value.ownership.liveGenerationIds) || !Array.isArray(value.ownership.nonResumableGenerationIds)) {
+            || typeof value.releaseRoot !== "string" || typeof value.contentDigest !== "string" || !ownership
+            || !isStringArray(liveInstanceIds) || !isStringArray(nonResumableInstanceIds) || !isStringArray(uncertainInstanceIds)) {
             return null;
         }
-        return value;
+        return {
+            ...value,
+            ownership: {
+                ...ownership,
+                liveInstanceIds,
+                nonResumableInstanceIds,
+                uncertainInstanceIds,
+            },
+        };
     }
     catch {
         return null;
@@ -243,11 +259,11 @@ async function activatePendingAfterBlockerExit(candidate, stateStore, paths, env
     let endpoint = null;
     while (Date.now() < deadline) {
         endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-        if (!endpoint || endpoint.ownership.liveGenerationIds.length === 0)
+        if (!endpoint || endpoint.ownership.liveInstanceIds.length === 0)
             break;
         await new Promise(resolvePromise => setTimeout(resolvePromise, 40));
     }
-    if (!endpoint || endpoint.ownership.liveGenerationIds.length > 0 || await probeOwnership(endpoint) !== "live-verified")
+    if (!endpoint || endpoint.ownership.liveInstanceIds.length > 0 || await probeOwnership(endpoint) !== "live-verified")
         return;
     const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
     await stateStore.approve(candidate.releaseId, diagnosticsPath);
@@ -300,6 +316,9 @@ async function requestIdleOwnershipRelease(metadata, candidateReleaseId, timeout
         setTimeout(() => finish(false), timeoutMs).unref();
     });
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === "string" && item.length > 0);
+}
 export async function waitForProcessExit(pid, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {

package/dist/src/foundation/release/cohort-selection.js

@@ -10,7 +10,7 @@ export function selectCohortLaunch(candidate, state, endpoint, probe) {
                 pid: endpoint.pid,
             };
         }
-        if (endpoint.releaseId !== candidate.releaseId && endpoint.ownership.liveGenerationIds.length === 0) {
+        if (endpoint.releaseId !== candidate.releaseId && endpoint.ownership.liveInstanceIds.length === 0) {
             return {
                 action: "replace-idle-cohort",
                 releaseId: candidate.releaseId,
@@ -30,12 +30,12 @@ export function selectCohortLaunch(candidate, state, endpoint, probe) {
         };
     }
     if (endpoint && probe === "unresponsive") {
-        if (endpoint.ownership.liveGenerationIds.length > 0 || endpoint.ownership.nonResumableGenerationIds.length > 0) {
+        if (endpoint.ownership.liveInstanceIds.length > 0 || endpoint.ownership.nonResumableInstanceIds.length > 0) {
             return {
                 action: "blocked",
                 releaseId: endpoint.releaseId,
                 releaseRoot: endpoint.releaseRoot,
-                reason: "ownership of live generations is uncertain; preserving the unresponsive supervisor",
+                reason: "ownership of live launch instances is uncertain; preserving the unresponsive supervisor",
                 pid: endpoint.pid,
             };
         }

package/dist/src/foundation/release/cohort-state.d.ts

@@ -32,8 +32,9 @@ export interface CohortState {
 }
 export interface EndpointOwnership {
     readonly state: "idle" | "busy" | "draining" | "released" | "blocked";
-    readonly liveGenerationIds: readonly string[];
-    readonly nonResumableGenerationIds: readonly string[];
+    readonly liveInstanceIds: readonly string[];
+    readonly nonResumableInstanceIds: readonly string[];
+    readonly uncertainInstanceIds: readonly string[];
 }
 export interface SupervisorEndpointMetadata {
     readonly schema: string;

package/dist/src/foundation/release/process-cleanup.d.ts

@@ -9,6 +9,6 @@ export declare function processIsAlive(pid: number): boolean;
 export declare function cleanupProvenIdleOwner(metadata: SupervisorEndpointMetadata, graceMs?: number): Promise<CleanupDiagnostics>;
 export declare function cleanupVerifiedOwner(metadata: SupervisorEndpointMetadata, options?: {
     readonly graceMs?: number;
-    readonly allowLiveGenerations?: boolean;
+    readonly allowLiveInstances?: boolean;
     readonly reason?: "stale-idle-owner" | "explicit-update" | "legacy-mutable-install";
 }): Promise<CleanupDiagnostics>;

package/dist/src/foundation/release/process-cleanup.js

@@ -11,11 +11,11 @@ export function processIsAlive(pid) {
     }
 }
 export async function cleanupProvenIdleOwner(metadata, graceMs = 1_500) {
-    return await cleanupVerifiedOwner(metadata, { graceMs, allowLiveGenerations: false });
+    return await cleanupVerifiedOwner(metadata, { graceMs, allowLiveInstances: false });
 }
 export async function cleanupVerifiedOwner(metadata, options = {}) {
     const graceMs = options.graceMs ?? 1_500;
-    if (!options.allowLiveGenerations && (metadata.ownership.liveGenerationIds.length > 0 || metadata.ownership.nonResumableGenerationIds.length > 0)) {
+    if (!options.allowLiveInstances && (metadata.ownership.liveInstanceIds.length > 0 || metadata.ownership.nonResumableInstanceIds.length > 0)) {
         throw new Error("refusing to terminate an owner with recorded live generations");
     }
     const started = Date.now();

package/dist/src/foundation/release/update.js

@@ -71,7 +71,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                 // Explicit update consent permits bounded cleanup of an authenticated
                 // older owner that predates the update-shutdown message.
                 const cleanup = await cleanupVerifiedOwner(endpoint, {
-                    allowLiveGenerations: true,
+                    allowLiveInstances: true,
                     reason: legacyMutableInstall ? "legacy-mutable-install" : "explicit-update",
                 });
                 if (!cleanup.terminated)
@@ -80,7 +80,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             else if (identity.accepted) {
                 await waitForProcessExit(endpoint.pid, 3_000).catch(async () => {
                     const cleanup = await cleanupVerifiedOwner(endpoint, {
-                        allowLiveGenerations: true,
+                        allowLiveInstances: true,
                         reason: legacyMutableInstall ? "legacy-mutable-install" : "explicit-update",
                     });
                     if (!cleanup.terminated)

package/dist/src/foundation/storage/control-store.d.ts

@@ -1,6 +1,6 @@
 import { DatabaseSync } from "node:sqlite";
 import type { ManagedAgentDescriptor, PaneId, AgentRecoveryAuthority, RecoveryReferenceId, TerminalSessionLaunch, TerminalTopologySnapshot } from "../workspace-contracts/index.js";
-import type { ForegroundTerminalLease, ForegroundTerminalLeaseId, GenerationId, NativeProcessIdentity, TransparentTerminalLifecycleOutcome } from "../lifecycle/index.js";
+import type { LaunchInstance, LaunchInstanceId, LaunchInstanceOutcome, NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
 export declare const DEFAULT_WORKSPACE_ID = "workspace-default";
 export interface WorkspaceAgentPresentation {
     readonly unreadActivity: number;
@@ -21,12 +21,13 @@ export declare class ControlStore {
     constructor(path: string, bootNonce?: string | null);
     migrate(): void;
     reconcilePriorBootGenerations(bootNonce: string): number;
-    acquireForegroundTerminalLease(lease: ForegroundTerminalLease): void;
-    activateForegroundTerminalLease(leaseId: ForegroundTerminalLeaseId, generationId: GenerationId, processIdentity: NativeProcessIdentity, heartbeatAt: string): boolean;
-    heartbeatForegroundTerminalLease(leaseId: ForegroundTerminalLeaseId, processIdentity: NativeProcessIdentity, heartbeatAt: string): boolean;
-    releaseForegroundTerminalLease(leaseId: ForegroundTerminalLeaseId, processIdentity: NativeProcessIdentity | null, outcome: TransparentTerminalLifecycleOutcome, releasedAt: string): boolean;
-    loadLiveForegroundTerminalLease(): ForegroundTerminalLease | null;
-    reconcilePriorBootForegroundTerminalLeases(bootNonce: string, reconciledAt?: string): number;
+    createLaunchInstance(instance: LaunchInstance): void;
+    activateLaunchInstance(instanceId: LaunchInstanceId, ownerClientId: string, rootIdentity: NativeProcessIdentity, containmentIdentity: ProcessContainmentIdentity, activatedAt: string): boolean;
+    beginLaunchInstanceStop(instanceId: LaunchInstanceId, ownerClientId: string, stoppingAt: string): boolean;
+    completeLaunchInstance(instanceId: LaunchInstanceId, ownerClientId: string, terminalState: "completed" | "interrupted", outcome: LaunchInstanceOutcome, completedAt: string): boolean;
+    loadActiveLaunchInstances(): LaunchInstance[];
+    loadLaunchInstance(instanceId: LaunchInstanceId): LaunchInstance | null;
+    reconcilePriorBootLaunchInstances(bootNonce: string, reconciledAt?: string): number;
     persistWorkspaceAgent(agent: ManagedAgentDescriptor, updatedAt?: string): void;
     persistWorkspaceAgentRecord(record: StoredWorkspaceAgent, updatedAt?: string): void;
     replaceWorkspaceAgentRecords(records: readonly StoredWorkspaceAgent[], selectedAgentId: string | null, revision: number, updatedAt?: string): void;