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

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

@@ -1,4 +1,5 @@
 import type { LaunchInstanceStopIntent, LaunchProfileId, SupervisorCommand } from "../lifecycle/index.js";
+import { type SessionSelection } from "../lifecycle/index.js";
 import { type NativeProcessInspector, type ProcessContainment } from "../process-containment/index.js";
 interface GuardianControl {
     connect(endpoint: string, timeoutMs?: number): Promise<unknown>;
@@ -19,6 +20,7 @@ export interface LaunchGuardianOptions {
     readonly profileId: LaunchProfileId;
     readonly releaseRoot: string;
     readonly uiEntry: string;
+    readonly sessionSelection?: SessionSelection;
     readonly environment?: NodeJS.ProcessEnv;
     readonly cwd?: string;
     readonly helperPath?: string;

package/dist/{src/foundation → foundation}/launch-guardian/main.js

@@ -1,12 +1,17 @@
 import { randomUUID } from "node:crypto";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { PRODUCT_TEXT } from "../../product-identity.js";
+import { readLaunchContext } from "../launch-context/index.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 { 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 { resolveProductPaths } from "../supervision/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();
@@ -16,8 +21,16 @@ export async function runLaunchGuardian(options) {
     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 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;
@@ -32,7 +45,7 @@ export async function runLaunchGuardian(options) {
         });
         let handle;
         try {
-            handle = await containment.spawn(process.execPath, [options.uiEntry], {
+            handle = await containment.spawn(process.execPath, [options.uiEntry, ...sessionArgs], {
                 cwd: options.cwd ?? process.cwd(),
                 environment: environmentEntries(environment),
                 ...(environment.TERM ? { terminalType: environment.TERM } : {}),
@@ -96,6 +109,8 @@ function platformInspector(helperPath) {
         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) {
@@ -161,5 +176,5 @@ function exitCode(outcome) {
     return 1;
 }
 function diagnosticError(message, code) {
-    return Object.assign(new Error(`A1: ${message}`), { code });
+    return Object.assign(new Error(`${PRODUCT_TEXT.displayName}: ${message}`), { code });
 }

package/dist/{src/foundation → foundation}/lifecycle/index.d.ts

@@ -2,3 +2,5 @@ export * from "./commands.js";
 export * from "./launch-instance.js";
 export * from "./model.js";
 export * from "./paths.js";
+export * from "./session-selection.js";
+export * from "./supervisor-startup.js";

package/dist/{src/foundation → foundation}/lifecycle/index.js

@@ -2,3 +2,5 @@ export * from "./commands.js";
 export * from "./launch-instance.js";
 export * from "./model.js";
 export * from "./paths.js";
+export * from "./session-selection.js";
+export * from "./supervisor-startup.js";

package/dist/{src/foundation → foundation}/lifecycle/model.d.ts

@@ -1,4 +1,4 @@
-export type LaunchProfileId = "a1" | "pi" | "sandbox";
+export type LaunchProfileId = "a1" | "pi";
 export type GenerationId = string;
 export type DriverProfileId = string;
 export type RequestId = string;

package/dist/{src/foundation → foundation}/lifecycle/model.js

@@ -1,6 +1,6 @@
 import { PRODUCT_TEXT } from "../../product-identity.js";
 export function assertLaunchProfileId(value) {
-    if (value !== "a1" && value !== "pi" && value !== "sandbox")
+    if (value !== "a1" && value !== "pi")
         throw new TypeError(PRODUCT_TEXT.diagnostic(`launch profile is invalid: ${String(value)}`));
 }
 export function assertDimensions(dimensions) {

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/{src/foundation → foundation}/lifecycle/paths.js

@@ -2,6 +2,26 @@ 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;
@@ -26,10 +46,16 @@ export function resolveProductPaths(environment = process.env, hostPlatform = pl
                 ? 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(runtimeDir, PRODUCT_IDENTITY.endpoint.unixSocketFilename));
+            : path.join(endpointDirectory ?? runtimeDir, PRODUCT_IDENTITY.endpoint.unixSocketFilename));
     return {
         configDir,
         dataDir,
@@ -37,6 +63,8 @@ export function resolveProductPaths(environment = process.env, hostPlatform = pl
         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/{src/foundation → foundation}/native-host-protocol/codec.d.ts

@@ -1,8 +1,10 @@
 import { type NativeHostProofMessage } from "./messages.js";
+/** Identifies a bounded native-host framing or message-contract failure. */
 export declare class NativeHostProtocolError extends Error {
     readonly code: "frame-too-large" | "malformed-frame" | "invalid-message";
     constructor(code: "frame-too-large" | "malformed-frame" | "invalid-message", message: string);
 }
+/** Encodes and incrementally decodes size-bounded newline-delimited native-host proof messages. */
 export declare class NativeHostFrameCodec {
     #private;
     encode(message: NativeHostProofMessage): string;

package/dist/{src/foundation → foundation}/native-host-protocol/codec.js

@@ -1,4 +1,5 @@
 import { MAX_NATIVE_HOST_MESSAGE_BYTES, assertNativeHostProofMessage, } from "./messages.js";
+/** Identifies a bounded native-host framing or message-contract failure. */
 export class NativeHostProtocolError extends Error {
     code;
     constructor(code, message) {
@@ -7,6 +8,7 @@ export class NativeHostProtocolError extends Error {
         this.name = "NativeHostProtocolError";
     }
 }
+/** Encodes and incrementally decodes size-bounded newline-delimited native-host proof messages. */
 export class NativeHostFrameCodec {
     #buffer = "";
     encode(message) {

package/dist/{src/foundation → foundation}/native-host-protocol/messages.d.ts

@@ -1,4 +1,4 @@
-import { type CorrelationId, type NativeHostCommand, type NativeHostEvent, type NativeHostHello, type PaneId, type TerminalSessionLaunch } from "../workspace-contracts/index.js";
+import { type CorrelationId, type NativeHostCommand, type NativeHostEvent, type NativeHostHello, type PaneId, type TerminalSessionLaunch } from "../../contracts/workspace/index.js";
 export declare const NATIVE_HOST_PROTOCOL_NAME: string;
 export declare const MAX_NATIVE_HOST_MESSAGE_BYTES: number;
 export type NativeHostProofMessage = {

package/dist/{src/foundation → foundation}/native-host-protocol/messages.js

@@ -1,4 +1,4 @@
-import { NATIVE_HOST_PROTOCOL_VERSION, assertNativeHostCommand, assertTerminalSessionLaunch, } from "../workspace-contracts/index.js";
+import { NATIVE_HOST_PROTOCOL_VERSION, assertNativeHostCommand, assertTerminalSessionLaunch, } from "../../contracts/workspace/index.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 export const NATIVE_HOST_PROTOCOL_NAME = PRODUCT_IDENTITY.protocol.nativeHostSchema;
 export const MAX_NATIVE_HOST_MESSAGE_BYTES = 1024 * 1024;

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/{src/foundation → foundation}/process-containment/index.d.ts

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

package/dist/{src/foundation → foundation}/process-containment/index.js

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

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

@@ -1,5 +1,6 @@
 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>;

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

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+/** Verifies Linux process identity from the PID and kernel start-time field in procfs. */
 export class LinuxNativeProcessInspector {
     async observe(pid) {
         if (!Number.isSafeInteger(pid) || pid <= 0)

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

@@ -1,5 +1,6 @@
 import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
 import type { ContainedProcessHandle, ContainedSpawnOptions, ProcessContainment } from "./contracts.js";
+/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
 export declare class NativeGuardianContainment implements ProcessContainment {
     #private;
     readonly instanceId: string;

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

@@ -2,6 +2,7 @@ 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";
+/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
 export class NativeGuardianContainment {
     instanceId;
     helperPath;

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

@@ -8,10 +8,12 @@ export interface InspectorCommandResult {
 export interface InspectorCommandRunner {
     run(executable: string, arguments_: readonly string[]): Promise<InspectorCommandResult>;
 }
+/** Verifies Windows process identity through the bounded process-guardian inspection command. */
 export declare class WindowsNativeProcessInspector implements NativeProcessInspector {
     readonly helperPath: string;
     private readonly runner;
-    constructor(helperPath: string, runner?: InspectorCommandRunner);
+    private readonly identityPrefix;
+    constructor(helperPath: string, runner?: InspectorCommandRunner, identityPrefix?: string);
     observe(pid: number): Promise<NativeProcessIdentity | null>;
     matches(identity: NativeProcessIdentity): Promise<boolean>;
 }

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

@@ -1,10 +1,13 @@
 import { execFile } from "node:child_process";
+/** Verifies Windows process identity through the bounded process-guardian inspection command. */
 export class WindowsNativeProcessInspector {
     helperPath;
     runner;
-    constructor(helperPath, runner = defaultRunner) {
+    identityPrefix;
+    constructor(helperPath, runner = defaultRunner, identityPrefix = "windows-filetime:") {
         this.helperPath = helperPath;
         this.runner = runner;
+        this.identityPrefix = identityPrefix;
         if (!helperPath || helperPath.includes("\0"))
             throw new TypeError("process guardian helper path is invalid");
     }
@@ -25,7 +28,7 @@ export class WindowsNativeProcessInspector {
         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:")) {
+        if (!isIdentity(value) || value.pid !== pid || !value.startIdentity.startsWith(this.identityPrefix)) {
             throw Object.assign(new Error("process guardian returned mismatched identity data"), { code: "PROCESS_INSPECTION_INVALID" });
         }
         return value;

package/dist/{src/foundation → foundation}/protocol/client.d.ts

@@ -5,6 +5,7 @@ interface ClientEvents {
     stopIntent: [LaunchInstanceStopIntent];
     disconnect: [];
 }
+/** Maintains one negotiated supervisor connection and rejects all pending commands on disconnect. */
 export declare class SupervisorClient extends EventEmitter<ClientEvents> {
     #private;
     readonly clientId: `${string}-${string}-${string}-${string}-${string}`;

package/dist/{src/foundation → foundation}/protocol/client.js

@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
 import { connect } from "node:net";
 import { randomUUID } from "node:crypto";
 import { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, encodeFrame, LineFrameDecoder, localControlHello, negotiateControlFeatures } from "./messages.js";
+/** Maintains one negotiated supervisor connection and rejects all pending commands on disconnect. */
 export class SupervisorClient extends EventEmitter {
     clientId = randomUUID();
     releaseId;

package/dist/{src/foundation → foundation}/protocol/messages.d.ts

@@ -76,6 +76,7 @@ export interface ControlNegotiation {
 export declare function localControlHello(releaseId?: string): ControlHello;
 export declare function negotiateControlFeatures(client: ControlHello, server?: ControlHello): ControlNegotiation;
 export declare function encodeFrame(message: ClientMessage | ServerMessage | Readonly<Record<string, unknown>>): string;
+/** Incrementally decodes size-bounded newline-delimited control frames from arbitrary chunks. */
 export declare class LineFrameDecoder {
     #private;
     push(chunk: Buffer | string): unknown[];

package/dist/{src/foundation → foundation}/protocol/messages.js

@@ -58,6 +58,7 @@ export function negotiateControlFeatures(client, server = localControlHello()) {
 export function encodeFrame(message) {
     return `${JSON.stringify(message)}\n`;
 }
+/** Incrementally decodes size-bounded newline-delimited control frames from arbitrary chunks. */
 export class LineFrameDecoder {
     #buffer = "";
     push(chunk) {

package/dist/foundation/release/bootstrap.d.ts

@@ -0,0 +1,55 @@
+import { type OwnershipProbe } from "./cohort-selection.js";
+import { type SupervisorEndpointMetadata } from "./cohort-state.js";
+import { resolveProductPaths, type SessionSelection, type LaunchProfileId, type SupervisorStartupAttemptIdentity } from "../lifecycle/index.js";
+import { cleanupProvenIdleOwner } from "./process-cleanup.js";
+import { type MaterializedRelease, type VerifyMaterializedReleaseOptions } from "./release-store.js";
+export interface BootstrapOptions {
+    readonly packageRoot: string;
+    readonly launchIntent?: {
+        readonly kind: "interactive";
+        readonly profileId: LaunchProfileId;
+        readonly sessionSelection?: SessionSelection;
+    };
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly output?: Pick<NodeJS.WriteStream, "write">;
+    /**
+     * Whether a materialized release copy is fit to launch. The active release
+     * is normally reused while its version matches the installation, but a copy
+     * can be broken in ways a version cannot see — materialized from a tree a
+     * blocked postinstall never finished repairing. The probe is injected from
+     * the bin entry because deciding it requires inspecting dependency
+     * resolution, which stays out of production code. Absent means every
+     * release is fit.
+     */
+    readonly releaseIsLaunchable?: (releaseRoot: string) => boolean;
+    /** Test seam for bounded maintenance scheduled after stale endpoint sweeping. */
+    readonly scheduleMaintenance?: (dataDir: string, paths: ReturnType<typeof resolveProductPaths>) => Promise<void>;
+}
+export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
+export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;
+/** Persist current-format evidence after an authenticated parent has certified the exact release. */
+export declare function recordParentCertifiedRelease(release: MaterializedRelease, dataDir: string): Promise<string>;
+export interface SupervisorStartupAttempt extends SupervisorStartupAttemptIdentity {
+    readonly childOutcome: Promise<{
+        readonly exitCode: number | null;
+        readonly signal: NodeJS.Signals | null;
+    }>;
+}
+/** Reuse a verified owner, or join the winner if another launch starts the same cohort first. */
+export declare function ensureSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<void>;
+export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<SupervisorStartupAttempt>;
+/**
+ * Hand a release the key set its own build reads. A retained pre-cutover release is
+ * still startable this way, which is what lets a launch fall back to the previous
+ * version instead of failing while an installation is being replaced.
+ */
+export declare function releaseEnvironment(environment: NodeJS.ProcessEnv, release: MaterializedRelease, profile?: LaunchProfileId): NodeJS.ProcessEnv;
+export declare function waitForVerifiedEndpoint(path: string, release: MaterializedRelease, timeoutMs: number, startup?: SupervisorStartupAttempt): Promise<void>;
+export declare function readEndpointMetadata(path: string): Promise<SupervisorEndpointMetadata | null>;
+export declare function probeOwnership(metadata: SupervisorEndpointMetadata): Promise<OwnershipProbe>;
+export declare function releaseVerifiedIdleOwner(metadata: SupervisorEndpointMetadata, dataDir: string, operations?: {
+    readonly waitForExit?: typeof waitForProcessExit;
+    readonly cleanup?: typeof cleanupProvenIdleOwner;
+}): Promise<boolean>;
+export declare function waitForProcessExit(pid: number, timeoutMs: number): Promise<void>;
+export declare function removeEndpointArtifacts(metadataPath: string, endpoint: string): Promise<void>;