@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

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

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { PRODUCT_TEXT } from "../../product-identity.js";
+import { readLaunchContext } from "../launch-context/index.js";
+import { resolve } from "node:path";
+import { assertLaunchProfileId, sessionSelectionArguments } from "../lifecycle/index.js";
+import { closeVerifiedContainment, DarwinNativeProcessInspector, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
+import { SupervisorClient } from "../protocol/index.js";
+import { resolveCohortEndpoint, resolveProductPaths } from "../supervision/index.js";
+import { markStartupPhase } from "../startup/index.js";
+export async function runLaunchGuardian(options) {
+    assertLaunchProfileId(options.profileId);
+    const sessionArgs = sessionSelectionArguments(options.sessionSelection);
+    if (sessionArgs.length > 0 && options.profileId !== "a1")
+        throw new Error("session selection requires the normal A1 profile");
+    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 context = readLaunchContext(environment);
+    const client = options.control ?? new SupervisorClient(context.releaseId);
+    // Invariant: an instance belongs to the cohort that launched it and talks to that cohort's endpoint
+    // for its whole life, whatever release becomes the active one meanwhile.
+    const releaseId = context.releaseId;
+    const endpoint = releaseId
+        ? resolveCohortEndpoint(paths, releaseId, environment).endpoint
+        : paths.endpoint;
+    await client.connect(endpoint);
+    await markStartupPhase(environment, "guardian-connected");
+    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, ...sessionArgs], {
+                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();
+    if (process.platform === "darwin")
+        return new DarwinNativeProcessInspector(helperPath);
+    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(`${PRODUCT_TEXT.displayName}: ${message}`), { code });
+}

package/dist/foundation/lifecycle/commands.js

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

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

@@ -0,0 +1,11 @@
+export type { LaunchInstanceStopIntent, SupervisorCommand } from "./commands.js";
+export { assertLaunchInstance, assertLaunchInstanceOutcome, assertLaunchInstanceTransition, assertProcessContainmentIdentity } from "./launch-instance.js";
+export type { LaunchInstance, LaunchInstanceId, LaunchInstanceOutcome, LaunchInstanceShutdownPolicy, LaunchInstanceState, LaunchInstanceStopReason, ProcessContainmentIdentity, } from "./launch-instance.js";
+export { assertDimensions, assertLaunchProfileId, assertNativeProcessIdentity, assertTransparentTerminalLaunchProfile } from "./model.js";
+export type { CommandResult, DriverProfileId, GenerationId, LaunchProfileId, NativeProcessIdentity, RequestId, SupervisorSnapshot, TerminalDimensions, TransparentTerminalLaunchProfile, TransparentTerminalLifecycleOutcome, } from "./model.js";
+export { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
+export type { CohortEndpointPaths, ProductPaths } from "./paths.js";
+export { parseSessionSelection, sessionSelectionArguments } from "./session-selection.js";
+export type { SessionSelection } from "./session-selection.js";
+export { createSupervisorStartupAttempt, publishSupervisorStartupResult, readSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath, } from "./supervisor-startup.js";
+export type { SupervisorStartupAttemptIdentity, SupervisorStartupResult } from "./supervisor-startup.js";

package/dist/foundation/lifecycle/index.js

@@ -0,0 +1,5 @@
+export { assertLaunchInstance, assertLaunchInstanceOutcome, assertLaunchInstanceTransition, assertProcessContainmentIdentity } from "./launch-instance.js";
+export { assertDimensions, assertLaunchProfileId, assertNativeProcessIdentity, assertTransparentTerminalLaunchProfile } from "./model.js";
+export { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
+export { parseSessionSelection, sessionSelectionArguments } from "./session-selection.js";
+export { createSupervisorStartupAttempt, publishSupervisorStartupResult, readSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath, } from "./supervisor-startup.js";

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

@@ -0,0 +1,64 @@
+export type LaunchProfileId = "a1" | "pi";
+export type GenerationId = string;
+export type DriverProfileId = string;
+export type RequestId = string;
+export interface TerminalDimensions {
+    readonly columns: number;
+    readonly rows: number;
+}
+export interface TransparentTerminalLaunchProfile {
+    readonly id: DriverProfileId;
+    readonly terminalCapability: "transparent";
+    readonly executable: string;
+    readonly arguments: readonly string[];
+    readonly cwd: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly terminalType: string;
+    readonly dimensions: TerminalDimensions;
+    readonly ownerDisconnect: "stop" | "detach";
+    readonly recovery: "detach-only" | "none";
+    readonly surface: "none";
+    readonly visualReconnection: "none";
+}
+export interface NativeProcessIdentity {
+    readonly pid: number;
+    readonly startIdentity: string;
+}
+export type TransparentTerminalLifecycleOutcome = {
+    readonly kind: "exited";
+    readonly exitCode: number;
+} | {
+    readonly kind: "signaled";
+    readonly signal: string;
+} | {
+    readonly kind: "stopped";
+    readonly reason: "owner-disconnect" | "user-request" | "update";
+} | {
+    readonly kind: "detached";
+    readonly reason: "owner-disconnect";
+} | {
+    readonly kind: "spawn-error" | "broker-error";
+    readonly message: string;
+    readonly code: string | null;
+};
+export interface SupervisorSnapshot {
+    readonly revision: number;
+    readonly activeInstances: readonly {
+        readonly id: string;
+        readonly profileId: LaunchProfileId;
+        readonly state: "requested" | "active" | "stopping";
+    }[];
+}
+export interface CommandResult {
+    readonly requestId: RequestId;
+    readonly ok: boolean;
+    readonly revision: number;
+    readonly error?: {
+        readonly code: "invalid-command" | "not-found" | "stale-generation" | "capability-error" | "containment-unsupported" | "ownership-error" | "driver-error";
+        readonly message: string;
+    };
+}
+export declare function assertLaunchProfileId(value: unknown): asserts value is LaunchProfileId;
+export declare function assertDimensions(dimensions: TerminalDimensions): void;
+export declare function assertTransparentTerminalLaunchProfile(profile: TransparentTerminalLaunchProfile): void;
+export declare function assertNativeProcessIdentity(identity: NativeProcessIdentity): void;

package/dist/foundation/lifecycle/model.js

@@ -0,0 +1,40 @@
+import { PRODUCT_TEXT } from "../../product-identity.js";
+export function assertLaunchProfileId(value) {
+    if (value !== "a1" && value !== "pi")
+        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) {
+        throw new RangeError("terminal columns must be an integer from 2 to 500");
+    }
+    if (!Number.isInteger(dimensions.rows) || dimensions.rows < 1 || dimensions.rows > 300) {
+        throw new RangeError("terminal rows must be an integer from 1 to 300");
+    }
+}
+export function assertTransparentTerminalLaunchProfile(profile) {
+    if (!profile.id || profile.terminalCapability !== "transparent")
+        throw new TypeError("invalid transparent terminal profile identity");
+    if (!profile.executable || profile.executable.includes("\0"))
+        throw new TypeError("transparent executable must be non-empty and contain no null byte");
+    if (!profile.cwd || profile.cwd.includes("\0"))
+        throw new TypeError("transparent working directory must be non-empty and contain no null byte");
+    if (profile.arguments.some(value => typeof value !== "string" || value.includes("\0")))
+        throw new TypeError("transparent arguments must contain no null byte");
+    if (Object.entries(profile.environment).some(([name, value]) => !name || name.includes("=") || name.includes("\0") || value.includes("\0"))) {
+        throw new TypeError("transparent environment contains an invalid name or value");
+    }
+    if (!profile.terminalType || profile.terminalType.includes("\0"))
+        throw new TypeError("transparent terminal type is invalid");
+    assertDimensions(profile.dimensions);
+    if (profile.surface !== "none" || profile.visualReconnection !== "none")
+        throw new TypeError("transparent profiles cannot declare a surface or visual reconnection");
+    if (profile.ownerDisconnect === "detach" && profile.recovery !== "detach-only")
+        throw new TypeError("transparent detach policy requires detach-only recovery");
+    if (profile.ownerDisconnect === "stop" && profile.recovery !== "none")
+        throw new TypeError("transparent stop policy requires no recovery claim");
+}
+export function assertNativeProcessIdentity(identity) {
+    if (!Number.isSafeInteger(identity.pid) || identity.pid <= 0 || !identity.startIdentity || identity.startIdentity.includes("\0")) {
+        throw new TypeError("invalid native process identity");
+    }
+}

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

@@ -0,0 +1,30 @@
+export interface ProductPaths {
+    readonly configDir: string;
+    readonly dataDir: string;
+    readonly runtimeDir: string;
+    readonly databasePath: string;
+    /** The endpoint written by releases that predate cohort-scoped identity. */
+    readonly endpoint: string;
+    /** The metadata written by releases that predate cohort-scoped identity. */
+    readonly endpointMetadataPath: string;
+    readonly endpointsDir: string;
+    /** A short, A1-managed socket directory when the host imposes a small Unix-path limit. */
+    readonly endpointDirectory?: string | null;
+    readonly supervisorLogPath: string;
+}
+/** Where one cohort listens, and where it records that it is listening. */
+export interface CohortEndpointPaths {
+    readonly endpoint: string;
+    readonly endpointMetadataPath: string;
+}
+/**
+ * Endpoint identity for one release cohort. Two cohorts can be live at once — an update
+ * leaves a working session on the release it started on — so the name a supervisor listens
+ * on has to name the release as well as the runtime directory, or the two contend for one
+ * endpoint and replacing one means ending the other.
+ *
+ * An explicit endpoint override keeps its single endpoint: it is how an isolated run pins
+ * the address it is going to talk to.
+ */
+export declare function resolveCohortEndpoint(paths: ProductPaths, releaseId: string, environment?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform): CohortEndpointPaths;
+export declare function resolveProductPaths(environment?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform, fallbackHome?: string): ProductPaths;

package/dist/foundation/lifecycle/paths.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { homedir, platform } from "node:os";
+import { posix, win32 } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/**
+ * Endpoint identity for one release cohort. Two cohorts can be live at once — an update
+ * leaves a working session on the release it started on — so the name a supervisor listens
+ * on has to name the release as well as the runtime directory, or the two contend for one
+ * endpoint and replacing one means ending the other.
+ *
+ * An explicit endpoint override keeps its single endpoint: it is how an isolated run pins
+ * the address it is going to talk to.
+ */
+export function resolveCohortEndpoint(paths, releaseId, environment = process.env, hostPlatform = platform()) {
+    if (environment[PRODUCT_IDENTITY.environment.endpoint]) {
+        return { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+    }
+    const path = hostPlatform === "win32" ? win32 : posix;
+    const token = createHash("sha256").update(releaseId).digest("hex").slice(0, 16);
+    const endpoint = hostPlatform === "win32"
+        ? `${paths.endpoint}-${token}`
+        : path.join(paths.endpointDirectory ?? paths.runtimeDir, `${token}-${PRODUCT_IDENTITY.endpoint.unixSocketFilename}`);
+    return { endpoint, endpointMetadataPath: path.join(paths.endpointsDir, `${token}.json`) };
+}
+export function resolveProductPaths(environment = process.env, hostPlatform = platform(), fallbackHome = homedir()) {
+    const windows = hostPlatform === "win32";
+    const path = windows ? win32 : posix;
+    const home = environment.HOME ?? environment.USERPROFILE ?? fallbackHome;
+    const configOverride = environment[PRODUCT_IDENTITY.environment.configDir];
+    const dataOverride = environment[PRODUCT_IDENTITY.environment.dataDir];
+    const runtimeOverride = environment[PRODUCT_IDENTITY.environment.runtimeDir];
+    const databaseOverride = environment[PRODUCT_IDENTITY.environment.databasePath];
+    const endpointOverride = environment[PRODUCT_IDENTITY.environment.endpoint];
+    const configDir = path.resolve(configOverride
+        ?? (windows
+            ? path.join(environment.APPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : path.join(environment.XDG_CONFIG_HOME ?? path.join(home, ".config"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    const dataDir = path.resolve(dataOverride
+        ?? (windows
+            ? path.join(environment.LOCALAPPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : path.join(environment.XDG_DATA_HOME ?? path.join(home, ".local", "share"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    const runtimeDir = path.resolve(runtimeOverride
+        ?? (windows
+            ? path.join(dataDir, "runtime")
+            : environment.XDG_RUNTIME_DIR
+                ? path.join(environment.XDG_RUNTIME_DIR, PRODUCT_IDENTITY.state.unixControlDirectory)
+                : path.join(dataDir, "runtime")));
+    const namespace = createHash("sha256").update(runtimeDir.toLowerCase()).digest("hex").slice(0, 20);
+    // Platform: Darwin limits Unix-domain socket paths to roughly 104 bytes. Runtime roots
+    // under /var/folders can exceed that before the cohort suffix is added, so only socket
+    // files use a short owned namespace while metadata remains under the selected runtime.
+    const endpointDirectory = !endpointOverride && hostPlatform === "darwin"
+        ? posix.join("/tmp", `${PRODUCT_IDENTITY.state.unixControlDirectory}-${namespace}`)
+        : null;
+    const endpoint = endpointOverride
+        ?? (windows
+            ? `\\\\.\\pipe\\${PRODUCT_IDENTITY.endpoint.windowsPipeStem}-${namespace}`
+            : path.join(endpointDirectory ?? runtimeDir, PRODUCT_IDENTITY.endpoint.unixSocketFilename));
+    return {
+        configDir,
+        dataDir,
+        runtimeDir,
+        databasePath: path.resolve(databaseOverride ?? path.join(dataDir, PRODUCT_IDENTITY.endpoint.databaseFilename)),
+        endpoint,
+        endpointMetadataPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.metadataFilename),
+        endpointsDir: path.join(runtimeDir, "endpoints"),
+        endpointDirectory,
+        supervisorLogPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.supervisorLogFilename),
+    };
+}

package/dist/foundation/lifecycle/session-selection.d.ts

@@ -0,0 +1,9 @@
+/** Invocation-scoped selection; never inferred from a parent's active-session environment. */
+export interface SessionSelection {
+    readonly target: string;
+    readonly sessionDir?: string;
+}
+/** Shared public/internal grammar, deliberately not arbitrary Pi argument passthrough. */
+export declare function parseSessionSelection(arguments_: readonly string[]): SessionSelection | undefined;
+/** Encode only validated values into separate argv entries; no shell quoting or evaluation. */
+export declare function sessionSelectionArguments(selection?: SessionSelection): string[];

package/dist/foundation/lifecycle/session-selection.js

@@ -0,0 +1,39 @@
+/** Shared public/internal grammar, deliberately not arbitrary Pi argument passthrough. */
+export function parseSessionSelection(arguments_) {
+    if (arguments_.length === 0)
+        return undefined;
+    let target;
+    let sessionDir;
+    for (let index = 0; index < arguments_.length; index += 2) {
+        const option = arguments_[index];
+        if (option !== "--session" && option !== "--session-dir")
+            throw new Error("expected --session <path|id> with optional --session-dir <dir>");
+        const value = arguments_[index + 1];
+        if (value === undefined || value.startsWith("-") || !validValue(value))
+            throw new Error(`${option} requires a nonempty value`);
+        if (option === "--session") {
+            if (target !== undefined)
+                throw new Error("--session may occur only once");
+            target = value;
+        }
+        else {
+            if (sessionDir !== undefined)
+                throw new Error("--session-dir may occur only once");
+            sessionDir = value;
+        }
+    }
+    if (target === undefined)
+        throw new Error("--session-dir requires --session <path|id>");
+    return Object.freeze({ target, ...(sessionDir === undefined ? {} : { sessionDir }) });
+}
+/** Encode only validated values into separate argv entries; no shell quoting or evaluation. */
+export function sessionSelectionArguments(selection) {
+    if (selection === undefined)
+        return [];
+    const args = [...(selection.sessionDir === undefined ? [] : ["--session-dir", selection.sessionDir]), "--session", selection.target];
+    parseSessionSelection(args);
+    return args;
+}
+function validValue(value) {
+    return value.trim().length > 0 && value.length <= 32_768 && !/[\u0000\r\n]/.test(value);
+}

package/dist/foundation/lifecycle/supervisor-startup.d.ts

@@ -0,0 +1,30 @@
+declare const STARTUP_SCHEMA = "a1-supervisor-startup-v1";
+export interface SupervisorStartupAttemptIdentity {
+    readonly attemptId: string;
+    readonly releaseId: string;
+    readonly resultPath: string;
+}
+export type SupervisorStartupResult = {
+    readonly schema: typeof STARTUP_SCHEMA;
+    readonly attemptId: string;
+    readonly releaseId: string;
+    readonly outcome: "ready";
+    readonly pid: number;
+} | {
+    readonly schema: typeof STARTUP_SCHEMA;
+    readonly attemptId: string;
+    readonly releaseId: string;
+    readonly outcome: "failure";
+    readonly stage: string;
+    readonly code: string | null;
+    readonly message: string;
+};
+/** Create one unguessable startup result authority under the protected runtime root. */
+export declare function createSupervisorStartupAttempt(runtimeDir: string, releaseId: string): Promise<SupervisorStartupAttemptIdentity>;
+export declare function supervisorStartupResultPath(runtimeDir: string, attemptId: string): string;
+/** Atomically publish the bounded result for one detached supervisor startup attempt. */
+export declare function publishSupervisorStartupResult(path: string, result: SupervisorStartupResult): Promise<void>;
+export declare function readSupervisorStartupResult(path: string, attemptId: string, releaseId: string): Promise<SupervisorStartupResult | null>;
+export declare function supervisorStartupFailure(error: unknown, attemptId: string, releaseId: string, stage: string): SupervisorStartupResult;
+export declare function supervisorStartupReady(attemptId: string, releaseId: string): SupervisorStartupResult;
+export {};

package/dist/foundation/lifecycle/supervisor-startup.js

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+const STARTUP_SCHEMA = "a1-supervisor-startup-v1";
+const MAX_RESULT_BYTES = 8 * 1024;
+const MAX_MESSAGE_LENGTH = 1_024;
+const MAX_RETAINED_RESULTS = 16;
+const MAX_RESULT_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+const ATTEMPT_PATTERN = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+/** Create one unguessable startup result authority under the protected runtime root. */
+export async function createSupervisorStartupAttempt(runtimeDir, releaseId) {
+    const attemptId = randomUUID();
+    const directory = resolve(runtimeDir, "supervisor-startup");
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await pruneSupervisorStartupResults(directory);
+    return { attemptId, releaseId, resultPath: supervisorStartupResultPath(runtimeDir, attemptId) };
+}
+export function supervisorStartupResultPath(runtimeDir, attemptId) {
+    if (!ATTEMPT_PATTERN.test(attemptId))
+        throw new TypeError("supervisor startup attempt identity is invalid");
+    return resolve(runtimeDir, "supervisor-startup", `${attemptId}.json`);
+}
+/** Atomically publish the bounded result for one detached supervisor startup attempt. */
+export async function publishSupervisorStartupResult(path, result) {
+    validateSupervisorStartupResult(result, result.attemptId, result.releaseId);
+    const body = `${JSON.stringify(result)}\n`;
+    if (Buffer.byteLength(body) > MAX_RESULT_BYTES)
+        throw new Error("supervisor startup result exceeds its size bound");
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, body, { encoding: "utf8", mode: 0o600 });
+    await rename(temporary, path);
+}
+export async function readSupervisorStartupResult(path, attemptId, releaseId) {
+    let metadata;
+    try {
+        metadata = await stat(path);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return null;
+        throw error;
+    }
+    if (!metadata.isFile() || metadata.size > MAX_RESULT_BYTES)
+        throw new Error("supervisor startup result is invalid or oversized");
+    const value = JSON.parse(await readFile(path, "utf8"));
+    return validateSupervisorStartupResult(value, attemptId, releaseId);
+}
+export function supervisorStartupFailure(error, attemptId, releaseId, stage) {
+    const source = error instanceof Error ? error : new Error(String(error));
+    return {
+        schema: STARTUP_SCHEMA,
+        attemptId,
+        releaseId,
+        outcome: "failure",
+        stage: boundedToken(stage, "unknown"),
+        code: "code" in source && typeof source.code === "string" ? boundedToken(source.code, "UNKNOWN") : null,
+        message: sanitizeMessage(source.message),
+    };
+}
+export function supervisorStartupReady(attemptId, releaseId) {
+    return { schema: STARTUP_SCHEMA, attemptId, releaseId, outcome: "ready", pid: process.pid };
+}
+async function pruneSupervisorStartupResults(directory) {
+    const now = Date.now();
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = (await Promise.all(entries.filter(entry => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => {
+        const path = resolve(directory, entry.name);
+        const metadata = await stat(path).catch(() => null);
+        return metadata ? { path, modified: metadata.mtimeMs } : null;
+    }))).filter((file) => file !== null);
+    files.sort((left, right) => right.modified - left.modified);
+    await Promise.all(files.flatMap((file, index) => index >= MAX_RETAINED_RESULTS - 1 || now - file.modified > MAX_RESULT_AGE_MS
+        ? [rm(file.path, { force: true })]
+        : []));
+}
+function validateSupervisorStartupResult(value, attemptId, releaseId) {
+    if (!value || typeof value !== "object")
+        throw new Error("supervisor startup result is malformed");
+    const result = value;
+    if (result.schema !== STARTUP_SCHEMA || result.attemptId !== attemptId || result.releaseId !== releaseId) {
+        throw new Error("supervisor startup result does not match the selected attempt and release");
+    }
+    if (result.outcome === "ready" && Number.isSafeInteger(result.pid) && Number(result.pid) > 0)
+        return result;
+    if (result.outcome === "failure" && typeof result.stage === "string" && result.stage.length > 0 && result.stage.length <= 128
+        && (result.code === null || typeof result.code === "string") && typeof result.message === "string" && result.message.length <= MAX_MESSAGE_LENGTH) {
+        return result;
+    }
+    throw new Error("supervisor startup result is malformed");
+}
+function sanitizeMessage(message) {
+    let value = message.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/:\/\/[^\s/@:]+:[^\s/@]+@/g, "://<redacted>@");
+    for (const [name, secret] of Object.entries(process.env)) {
+        if (!secret || secret.length < 4 || !/(?:TOKEN|SECRET|PASSWORD|COOKIE|CREDENTIAL|AUTH)/i.test(name))
+            continue;
+        value = value.split(secret).join("<redacted>");
+    }
+    return value.trim().slice(0, MAX_MESSAGE_LENGTH) || "supervisor startup failed";
+}
+function boundedToken(value, fallback) {
+    const normalized = value.replace(/[^A-Za-z0-9_.:-]/g, "-").slice(0, 128);
+    return normalized || fallback;
+}
+function isNodeError(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

package/dist/foundation/process-containment/darwin-process-inspector.d.ts

@@ -0,0 +1,5 @@
+import { WindowsNativeProcessInspector, type InspectorCommandRunner } from "./windows-process-inspector.js";
+/** Verifies Darwin process identity through the bounded native guardian inspection command. */
+export declare class DarwinNativeProcessInspector extends WindowsNativeProcessInspector {
+    constructor(helperPath: string, runner?: InspectorCommandRunner);
+}

package/dist/foundation/process-containment/darwin-process-inspector.js

@@ -0,0 +1,7 @@
+import { WindowsNativeProcessInspector } from "./windows-process-inspector.js";
+/** Verifies Darwin process identity through the bounded native guardian inspection command. */
+export class DarwinNativeProcessInspector extends WindowsNativeProcessInspector {
+    constructor(helperPath, runner) {
+        super(helperPath, runner, "darwin-proc-start:");
+    }
+}

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

@@ -0,0 +1,8 @@
+export { verifyProcessGuardianArtifact } from "./artifact.js";
+export { closeVerifiedContainment } from "./contracts.js";
+export type { ContainedProcessHandle, ContainedSpawnOptions, ContainmentCloseResult, NativeProcessInspector, ProcessContainment, ProcessContainmentFactory, } from "./contracts.js";
+export { DarwinNativeProcessInspector } from "./darwin-process-inspector.js";
+export { LinuxNativeProcessInspector } from "./linux-process-inspector.js";
+export { NativeGuardianContainment, resolveProcessGuardianPath } from "./native-guardian-containment.js";
+export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";
+export type { InspectorCommandResult, InspectorCommandRunner } from "./windows-process-inspector.js";

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

@@ -0,0 +1,6 @@
+export { verifyProcessGuardianArtifact } from "./artifact.js";
+export { closeVerifiedContainment } from "./contracts.js";
+export { DarwinNativeProcessInspector } from "./darwin-process-inspector.js";
+export { LinuxNativeProcessInspector } from "./linux-process-inspector.js";
+export { NativeGuardianContainment, resolveProcessGuardianPath } from "./native-guardian-containment.js";
+export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";

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

@@ -0,0 +1,7 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+/** Verifies Linux process identity from the PID and kernel start-time field in procfs. */
+export declare class LinuxNativeProcessInspector implements NativeProcessInspector {
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}