@timurproko/a1 0.2.6-dev.736 → 0.2.7-dev.1221

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

@@ -1,11 +1,14 @@
+import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { PRODUCT_TEXT } from "../../product-identity.js";
 import { readLaunchContext } from "../launch-context/index.js";
 import { resolve } from "node:path";
 import { assertLaunchProfileId, resolveCohortEndpoint, resolveProductPaths, sessionSelectionArguments } from "../lifecycle/index.js";
-import { closeVerifiedContainment, DarwinNativeProcessInspector, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
+import { AddonContainment, AddonProcessInspector, closeVerifiedContainment, LinuxNativeProcessInspector, loadProcessGuardianAddon, resolveProcessGuardianPath, verifyProcessGuardianArtifact, } from "../process-containment/index.js";
 import { SupervisorClient } from "../protocol/index.js";
 import { markStartupPhase } from "../startup/index.js";
+import { exitWatcherArguments } from "./exit-watcher.js";
 export async function runLaunchGuardian(options) {
     assertLaunchProfileId(options.profileId);
     const sessionArgs = sessionSelectionArguments(options.sessionSelection);
@@ -15,8 +18,11 @@ export async function runLaunchGuardian(options) {
     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);
+    // Rationale: tests that inject both process boundaries need no native module; every production
+    // path loads the exact artifact only after its manifest and digest have been verified.
+    const addon = options.addon ?? (options.containment && options.inspector ? null : loadProcessGuardianAddon(helperPath));
+    const inspector = options.inspector ?? platformInspector(requireAddon(addon));
     const guardianIdentity = await inspector.observe(process.pid);
     if (!guardianIdentity)
         throw diagnosticError("launch guardian cannot verify its own native process identity", "PROCESS_IDENTITY_UNAVAILABLE");
@@ -30,7 +36,8 @@ export async function runLaunchGuardian(options) {
         : 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`), resolve(paths.runtimeDir, "launch-instances", `${instanceId}.exit-notice`));
+    const exitNoticePath = resolve(paths.runtimeDir, "launch-instances", `${instanceId}.exit-notice`);
+    const containment = options.containment ?? new AddonContainment(instanceId, helperPath, exitNoticePath, requireAddon(addon));
     const stop = stopRequests(client, instanceId);
     let rootIdentity = null;
     try {
@@ -43,13 +50,26 @@ export async function runLaunchGuardian(options) {
             guardianIdentity,
         });
         let handle;
+        let encodedModes = null;
         try {
-            handle = await containment.spawn(process.execPath, [options.uiEntry, ...sessionArgs], {
+            const rootCommand = options.rootCommand ?? { executable: process.execPath, arguments: [options.uiEntry, ...sessionArgs] };
+            encodedModes = addon?.captureTerminalModes() ?? null;
+            handle = await containment.spawn(rootCommand.executable, [...rootCommand.arguments], {
                 cwd: options.cwd ?? process.cwd(),
                 environment: environmentEntries(environment),
                 ...(environment.TERM ? { terminalType: environment.TERM } : {}),
             });
             rootIdentity = handle.identity;
+            if (addon && encodedModes !== null) {
+                await startExitWatcher(addon, {
+                    addonPath: helperPath,
+                    noticePath: exitNoticePath,
+                    encodedModes,
+                    runtimePid: handle.identity.pid,
+                    processGroup: handle.processGroup ?? null,
+                    foregroundGroup: handle.foregroundGroup ?? null,
+                });
+            }
             await requireAccepted(client, {
                 type: "activate-launch-instance",
                 requestId: randomUUID(),
@@ -88,6 +108,10 @@ export async function runLaunchGuardian(options) {
                 return result.outcome;
             }),
         ]);
+        // Invariant: the root removes a clean notice. If it left the notice armed, the guardian claims,
+        // restores, and prints it before closing the native containment handle.
+        if (addon && encodedModes !== null)
+            addon.deliverExitNotice(exitNoticePath, encodedModes);
         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);
@@ -103,15 +127,44 @@ export async function runLaunchGuardian(options) {
         client.close();
     }
 }
-function platformInspector(helperPath) {
+async function startExitWatcher(addon, options) {
+    const entry = fileURLToPath(new URL("./exit-watcher.js", import.meta.url));
+    const arguments_ = [entry, ...exitWatcherArguments({
+            guardianPid: process.pid,
+            ...options,
+        })];
+    if (process.platform === "win32") {
+        addon.spawnWatcher({ executable: process.execPath, arguments: arguments_ });
+        return;
+    }
+    await new Promise((resolvePromise, rejectPromise) => {
+        const watcher = spawn(process.execPath, arguments_, {
+            stdio: "inherit",
+            detached: false,
+            windowsHide: false,
+        });
+        watcher.once("error", rejectPromise);
+        watcher.once("spawn", () => {
+            watcher.off("error", rejectPromise);
+            watcher.unref();
+            resolvePromise();
+        });
+    });
+}
+function platformInspector(addon) {
     if (process.platform === "win32")
-        return new WindowsNativeProcessInspector(helperPath);
+        return new AddonProcessInspector(addon, "windows-filetime:");
     if (process.platform === "linux")
         return new LinuxNativeProcessInspector();
     if (process.platform === "darwin")
-        return new DarwinNativeProcessInspector(helperPath);
+        return new AddonProcessInspector(addon, "darwin-proc-start:");
     throw diagnosticError(`launch-instance process containment is unsupported on ${process.platform}`, "CONTAINMENT_UNSUPPORTED");
 }
+function requireAddon(addon) {
+    if (!addon)
+        throw diagnosticError("process guardian addon is unavailable", "CONTAINMENT_ARTIFACT_MISSING");
+    return addon;
+}
 function stopRequests(client, instanceId) {
     let resolveStop;
     let settled = false;

package/dist/foundation/lifecycle/session-repository-context.js

@@ -143,6 +143,10 @@ export async function listSessionRepositoryWorktrees(identity, options = {}) {
     const contended = await mutationLockExists(options);
     const entries = [];
     for (const selected of worktrees) {
+        if ("stale" in selected) {
+            entries.push({ cwd: selected.root, branch: selected.branch ?? "(detached)", status: "unverifiable", agentId: null });
+            continue;
+        }
         if (selected.branch === null) {
             entries.push({ cwd: selected.root, branch: "(detached)", status: "unverifiable", agentId: null });
             continue;
@@ -407,9 +411,15 @@ async function listGitWorktrees(cwd, commonDir, signal) {
     if (current !== null)
         records.push(current);
     return await Promise.all(records.map(async (record) => {
-        const root = await realpath(record.root);
+        const root = await realpath(record.root).catch(error => { if (isMissingPathError(error))
+            return null; throw error; });
+        if (root === null)
+            return { stale: true, root: resolve(record.root), branch: record.branch };
         const dotGit = join(root, ".git");
-        const metadata = await lstat(dotGit);
+        const metadata = await lstat(dotGit).catch(error => { if (isMissingPathError(error))
+            return null; throw error; });
+        if (metadata === null)
+            return { stale: true, root, branch: record.branch };
         let gitDir;
         if (metadata.isDirectory() && !metadata.isSymbolicLink())
             gitDir = await realpath(dotGit);
@@ -424,6 +434,10 @@ async function listGitWorktrees(cwd, commonDir, signal) {
         return { root, commonDir, gitDir, branch: record.branch };
     }));
 }
+/** True for the errors a deleted directory or file produces, which mark a registered worktree as stale rather than broken. */
+function isMissingPathError(error) {
+    return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}
 async function executeGit(arguments_, cwd, maxBuffer, signal) {
     const { execFile } = await import("node:child_process");
     const execute = promisify(execFile);

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

@@ -1,13 +1,15 @@
 import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+import { type ProcessGuardianAddon } from "./addon.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 {
+/** Owns one native containment object in the launch guardian's Node process. */
+export declare class AddonContainment implements ProcessContainment {
     #private;
     readonly instanceId: string;
-    readonly helperPath: string;
-    readonly statusPath: string;
+    readonly addonPath: string;
     readonly exitNoticePath: string | null;
-    constructor(instanceId: string, helperPath: string, statusPath: string, exitNoticePath?: string | null);
+    readonly addon: ProcessGuardianAddon;
+    private readonly platform;
+    constructor(instanceId: string, addonPath: string, exitNoticePath?: string | null, addon?: ProcessGuardianAddon, platform?: NodeJS.Platform);
     get identity(): ProcessContainmentIdentity;
     spawn(executable: string, arguments_: readonly string[], options: ContainedSpawnOptions): Promise<ContainedProcessHandle>;
     contains(identity: NativeProcessIdentity): Promise<boolean>;

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

@@ -0,0 +1,139 @@
+import { constants } from "node:os";
+import { mkdir, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { loadProcessGuardianAddon } from "./addon.js";
+/** Owns one native containment object in the launch guardian's Node process. */
+export class AddonContainment {
+    #identity;
+    #rootIdentity = null;
+    #runtime = null;
+    #outcome = null;
+    #settled = false;
+    instanceId;
+    addonPath;
+    exitNoticePath;
+    addon;
+    platform;
+    constructor(instanceId, addonPath, exitNoticePath = null, addon = loadProcessGuardianAddon(addonPath), platform = process.platform) {
+        this.instanceId = instanceId;
+        this.addonPath = addonPath;
+        this.exitNoticePath = exitNoticePath;
+        this.addon = addon;
+        this.platform = platform;
+        this.#identity = { provider: "native-addon-pending", token: instanceId };
+    }
+    get identity() {
+        return this.#identity;
+    }
+    async spawn(executable, arguments_, options) {
+        if (this.#runtime)
+            throw new Error("process containment already has a root runtime");
+        if (this.exitNoticePath) {
+            await mkdir(dirname(this.exitNoticePath), { recursive: true, mode: 0o700 });
+            await rm(this.exitNoticePath, { force: true });
+        }
+        const runtime = this.addon.spawnContained({
+            executable,
+            arguments: [...arguments_],
+            cwd: options.cwd,
+            environment: {
+                ...options.environment,
+                ...(options.terminalType ? { TERM: options.terminalType } : {}),
+                ...(this.exitNoticePath ? { [PRODUCT_IDENTITY.environment.exitNoticePath]: this.exitNoticePath } : {}),
+            },
+            instanceId: this.instanceId,
+        });
+        assertRuntime(runtime);
+        this.#runtime = runtime;
+        this.#rootIdentity = { pid: runtime.pid, startIdentity: runtime.startIdentity };
+        this.#identity = { provider: runtime.containmentProvider, token: runtime.containmentToken };
+        const outcome = runtime.wait().then(exitCode => outcomeFromExitCode(exitCode, this.platform), error => ({
+            kind: "guardian-error",
+            message: errorMessage(error),
+            code: errorCode(error),
+        })).finally(() => { this.#settled = true; });
+        this.#outcome = outcome;
+        return {
+            identity: this.#rootIdentity,
+            outcome,
+            ...(runtime.processGroup === null ? {} : { processGroup: runtime.processGroup }),
+            ...(runtime.foregroundGroup === null ? {} : { foregroundGroup: runtime.foregroundGroup }),
+        };
+    }
+    async contains(identity) {
+        return this.#rootIdentity !== null
+            && identity.pid === this.#rootIdentity.pid
+            && identity.startIdentity === this.#rootIdentity.startIdentity;
+    }
+    async stop(force) {
+        const runtime = this.#runtime;
+        if (!runtime || this.#settled)
+            return;
+        try {
+            if (force)
+                runtime.terminate(137);
+            else if (this.platform === "win32")
+                process.kill(runtime.pid, "SIGTERM");
+            else
+                runtime.stop();
+        }
+        catch (error) {
+            if (errorCode(error) !== "ESRCH")
+                throw error;
+        }
+    }
+    async waitForEmpty(timeoutMs) {
+        if (this.#settled || !this.#outcome)
+            return true;
+        return await Promise.race([
+            this.#outcome.then(() => true),
+            new Promise(resolvePromise => {
+                const timer = setTimeout(() => resolvePromise(false), timeoutMs);
+                timer.unref();
+            }),
+        ]);
+    }
+    async close() {
+        const runtime = this.#runtime;
+        if (!runtime)
+            return;
+        runtime.close();
+        await this.waitForEmpty(1_500);
+    }
+}
+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);
+    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, `${PRODUCT_IDENTITY.artifacts.processGuardianAddon}.node`);
+}
+function assertRuntime(runtime) {
+    if (!Number.isSafeInteger(runtime.pid) || runtime.pid <= 0
+        || typeof runtime.startIdentity !== "string" || runtime.startIdentity.length === 0
+        || typeof runtime.containmentProvider !== "string" || runtime.containmentProvider.length === 0
+        || typeof runtime.containmentToken !== "string" || runtime.containmentToken.length === 0
+        || (runtime.processGroup !== null && (!Number.isSafeInteger(runtime.processGroup) || runtime.processGroup <= 0))
+        || (runtime.foregroundGroup !== null && (!Number.isSafeInteger(runtime.foregroundGroup) || runtime.foregroundGroup <= 0))) {
+        runtime.close();
+        throw Object.assign(new Error("process guardian addon returned invalid containment identity"), { code: "CONTAINMENT_ARTIFACT_INCOMPATIBLE" });
+    }
+}
+function outcomeFromExitCode(exitCode, platform) {
+    if (!Number.isSafeInteger(exitCode) || exitCode < 0 || exitCode > 255) {
+        return { kind: "guardian-error", message: "process guardian addon returned an invalid exit code", code: "CONTAINMENT_OUTCOME_INVALID" };
+    }
+    if (platform !== "win32" && exitCode >= 128) {
+        const signalNumber = exitCode - 128;
+        const signal = Object.entries(constants.signals).find(([, value]) => value === signalNumber)?.[0];
+        if (signal)
+            return { kind: "signaled", signal };
+    }
+    return { kind: "exited", exitCode };
+}
+function errorCode(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,11 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { ProcessGuardianAddon } from "./addon.js";
+import type { NativeProcessInspector } from "./contracts.js";
+/** Verifies native process identity through the process-guardian addon's bounded inspection call. */
+export declare class AddonProcessInspector implements NativeProcessInspector {
+    readonly addon: Pick<ProcessGuardianAddon, "inspectProcessStart">;
+    readonly identityPrefix: string;
+    constructor(addon: Pick<ProcessGuardianAddon, "inspectProcessStart">, identityPrefix: string);
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

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

@@ -0,0 +1,36 @@
+/** Verifies native process identity through the process-guardian addon's bounded inspection call. */
+export class AddonProcessInspector {
+    addon;
+    identityPrefix;
+    constructor(addon, identityPrefix) {
+        if (!identityPrefix || identityPrefix.includes("\0"))
+            throw new TypeError("process identity prefix is invalid");
+        this.addon = addon;
+        this.identityPrefix = identityPrefix;
+    }
+    async observe(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new TypeError("inspected PID must be a positive safe integer");
+        let startIdentity;
+        try {
+            startIdentity = this.addon.inspectProcessStart(pid);
+        }
+        catch (error) {
+            throw Object.assign(new Error(`cannot inspect native process identity: ${errorMessage(error)}`), { code: "PROCESS_INSPECTION_FAILED" });
+        }
+        if (startIdentity === null)
+            return null;
+        if (typeof startIdentity !== "string" || startIdentity.length === 0 || startIdentity.length > 512
+            || startIdentity.includes("\0") || !startIdentity.startsWith(this.identityPrefix)) {
+            throw Object.assign(new Error("process guardian returned mismatched identity data"), { code: "PROCESS_INSPECTION_INVALID" });
+        }
+        return { pid, startIdentity };
+    }
+    async matches(identity) {
+        const observed = await this.observe(identity.pid);
+        return observed !== null && observed.startIdentity === identity.startIdentity;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,42 @@
+export interface ProcessGuardianVersion {
+    readonly crateVersion: string;
+    readonly protocolVersion: 2;
+    readonly target: string;
+}
+export interface ProcessGuardianRuntime {
+    readonly pid: number;
+    readonly startIdentity: string;
+    readonly containmentProvider: string;
+    readonly containmentToken: string;
+    readonly processGroup: number | null;
+    readonly foregroundGroup: number | null;
+    wait(): Promise<number>;
+    terminate(code: number): void;
+    stop(): void;
+    close(): void;
+}
+export interface SpawnContainedOptions {
+    readonly executable: string;
+    readonly arguments: readonly string[];
+    readonly cwd: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly instanceId: string;
+}
+export interface ProcessGuardianAddon {
+    version(): ProcessGuardianVersion;
+    inspectProcessStart(pid: number): string | null;
+    captureTerminalModes(): string;
+    restoreTerminalModes(encoded: string): void;
+    deliverExitNotice(path: string, encodedModes: string): void;
+    spawnContained(options: SpawnContainedOptions): ProcessGuardianRuntime;
+    spawnWatcher(options: {
+        readonly executable: string;
+        readonly arguments: readonly string[];
+    }): number;
+    waitForProcessExit(pid: number): Promise<void>;
+    stopProcessGroup(processGroup: number): void;
+    restoreForegroundGroup(processGroup: number): void;
+    ignoreConsoleControl(): void;
+}
+/** Loads one verified Node-API guardian instance per exact addon path. */
+export declare function loadProcessGuardianAddon(path: string): ProcessGuardianAddon;

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

@@ -0,0 +1,57 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+const require = createRequire(import.meta.url);
+const cache = new Map();
+/** Loads one verified Node-API guardian instance per exact addon path. */
+export function loadProcessGuardianAddon(path) {
+    if (!path || path.includes("\0"))
+        throw new TypeError("process guardian addon path is invalid");
+    const exactPath = resolve(path);
+    const cached = cache.get(exactPath);
+    if (cached)
+        return cached;
+    let value;
+    try {
+        value = require(exactPath);
+    }
+    catch (error) {
+        const code = errorCode(error) === "MODULE_NOT_FOUND" || errorCode(error) === "ENOENT"
+            ? "CONTAINMENT_ARTIFACT_MISSING"
+            : "CONTAINMENT_ARTIFACT_INCOMPATIBLE";
+        throw diagnosticError(`process guardian addon could not be loaded: ${errorMessage(error)}`, code);
+    }
+    if (!isProcessGuardianAddon(value)) {
+        throw diagnosticError("process guardian addon exports are incompatible", "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
+    }
+    let report;
+    try {
+        report = value.version();
+    }
+    catch (error) {
+        throw diagnosticError(`process guardian addon identity failed: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
+    }
+    if (report.protocolVersion !== 2 || typeof report.crateVersion !== "string" || report.crateVersion.length === 0 || typeof report.target !== "string") {
+        throw diagnosticError("process guardian addon protocol is incompatible", "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
+    }
+    cache.set(exactPath, value);
+    return value;
+}
+function isProcessGuardianAddon(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return [
+        "version", "inspectProcessStart", "captureTerminalModes", "restoreTerminalModes",
+        "deliverExitNotice", "spawnContained", "spawnWatcher", "waitForProcessExit",
+        "stopProcessGroup", "restoreForegroundGroup", "ignoreConsoleControl",
+    ].every(name => typeof candidate[name] === "function");
+}
+function diagnosticError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+function errorCode(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -1 +1 @@
-export declare function verifyProcessGuardianArtifact(helperPath: string, platform?: NodeJS.Platform, architecture?: string): Promise<void>;
+export declare function verifyProcessGuardianArtifact(addonPath: string, platform?: NodeJS.Platform, architecture?: string): Promise<void>;

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

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
-export async function verifyProcessGuardianArtifact(helperPath, platform = process.platform, architecture = process.arch) {
-    const manifestPath = resolve(dirname(helperPath), "manifest.json");
+export async function verifyProcessGuardianArtifact(addonPath, platform = process.platform, architecture = process.arch) {
+    const manifestPath = resolve(dirname(addonPath), "manifest.json");
     let manifest;
     try {
         manifest = JSON.parse(await readFile(manifestPath, "utf8"));
@@ -10,15 +10,16 @@ export async function verifyProcessGuardianArtifact(helperPath, platform = proce
     catch (error) {
         throw artifactError(`process guardian manifest is missing or malformed: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_MISSING");
     }
-    if (manifest.schema !== "a1-process-guardian-artifact-v1" || manifest.protocolVersion !== 1
+    if (manifest.schema !== "a1-process-guardian-artifact-v2" || manifest.kind !== "node-addon"
+        || manifest.nodeApi !== 9 || manifest.protocolVersion !== 2
         || manifest.platform !== platform || manifest.architecture !== architecture
-        || manifest.artifact?.filename !== basename(helperPath)) {
+        || manifest.artifact?.filename !== basename(addonPath)) {
         throw artifactError("process guardian manifest is incompatible with this platform or protocol", "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
     }
     if (manifest.capability !== "supported") {
         throw artifactError(`process containment is not certified for ${platform}-${architecture}`, "CONTAINMENT_UNSUPPORTED");
     }
-    const [bytes, metadata] = await Promise.all([readFile(helperPath), stat(helperPath)]).catch(error => {
+    const [bytes, metadata] = await Promise.all([readFile(addonPath), stat(addonPath)]).catch(error => {
         throw artifactError(`process guardian artifact is unavailable: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_MISSING");
     });
     const digest = createHash("sha256").update(bytes).digest("hex");

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

@@ -7,6 +7,8 @@ export interface ContainedSpawnOptions {
 export interface ContainedProcessHandle {
     readonly identity: NativeProcessIdentity;
     readonly outcome: Promise<LaunchInstanceOutcome>;
+    readonly processGroup?: number;
+    readonly foregroundGroup?: number;
 }
 export interface NativeProcessInspector {
     observe(pid: number): Promise<NativeProcessIdentity | null>;

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

@@ -1,9 +1,9 @@
+export { loadProcessGuardianAddon } from "./addon.js";
+export type { ProcessGuardianAddon, ProcessGuardianRuntime, ProcessGuardianVersion } from "./addon.js";
+export { AddonContainment, resolveProcessGuardianPath } from "./addon-containment.js";
+export { AddonProcessInspector } from "./addon-process-inspector.js";
 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 { createNativeProcessInspector } from "./native-process-inspector.js";
-export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";
-export type { InspectorCommandResult, InspectorCommandRunner } from "./windows-process-inspector.js";

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

@@ -1,7 +1,7 @@
+export { loadProcessGuardianAddon } from "./addon.js";
+export { AddonContainment, resolveProcessGuardianPath } from "./addon-containment.js";
+export { AddonProcessInspector } from "./addon-process-inspector.js";
 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 { createNativeProcessInspector } from "./native-process-inspector.js";
-export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";

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

@@ -1,3 +1,4 @@
+import type { ProcessGuardianAddon } from "./addon.js";
 import type { NativeProcessInspector } from "./contracts.js";
 /** Resolve only the platform's exact-process inspector used by cooperative session ownership. */
-export declare function createNativeProcessInspector(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, releaseRoot?: string): Promise<NativeProcessInspector>;
+export declare function createNativeProcessInspector(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, releaseRoot?: string, loadAddon?: (path: string) => ProcessGuardianAddon): Promise<NativeProcessInspector>;

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

@@ -1,6 +1,6 @@
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 /** Resolve only the platform's exact-process inspector used by cooperative session ownership. */
-export async function createNativeProcessInspector(environment = process.env, platform = process.platform, releaseRoot) {
+export async function createNativeProcessInspector(environment = process.env, platform = process.platform, releaseRoot, loadAddon) {
     if (platform === "linux") {
         const { LinuxNativeProcessInspector } = await import("./linux-process-inspector.js");
         return new LinuxNativeProcessInspector();
@@ -8,14 +8,14 @@ export async function createNativeProcessInspector(environment = process.env, pl
     if (platform !== "win32" && platform !== "darwin")
         throw new Error(`native process identity is unsupported on ${platform}`);
     if (releaseRoot === undefined && !environment[PRODUCT_IDENTITY.environment.processGuardianPath]) {
-        throw new Error("native process identity helper is unavailable");
+        throw new Error("native process identity addon is unavailable");
     }
-    const { resolveProcessGuardianPath } = await import("./native-guardian-containment.js");
-    const helper = resolveProcessGuardianPath(releaseRoot ?? process.cwd(), environment, platform);
-    if (platform === "win32") {
-        const { WindowsNativeProcessInspector } = await import("./windows-process-inspector.js");
-        return new WindowsNativeProcessInspector(helper);
-    }
-    const { DarwinNativeProcessInspector } = await import("./darwin-process-inspector.js");
-    return new DarwinNativeProcessInspector(helper);
+    const [{ resolveProcessGuardianPath }, { loadProcessGuardianAddon }, { AddonProcessInspector }] = await Promise.all([
+        import("./addon-containment.js"),
+        import("./addon.js"),
+        import("./addon-process-inspector.js"),
+    ]);
+    const addonPath = resolveProcessGuardianPath(releaseRoot ?? process.cwd(), environment, platform);
+    const addon = (loadAddon ?? loadProcessGuardianAddon)(addonPath);
+    return new AddonProcessInspector(addon, platform === "win32" ? "windows-filetime:" : "darwin-proc-start:");
 }

package/dist/foundation/release/automatic-update.d.ts

@@ -0,0 +1,37 @@
+import { type AvailableRelease, type ReleaseChannel } from "./latest-release.js";
+export declare const AUTOMATIC_UPDATE_STATE_SCHEMA = 1;
+export declare const AUTOMATIC_UPDATE_RETRY_MS: number;
+export interface AutomaticUpdateState {
+    readonly schema: typeof AUTOMATIC_UPDATE_STATE_SCHEMA;
+    readonly channel: ReleaseChannel;
+    readonly targetVersion: string;
+    readonly status: "running" | "installed" | "failed";
+    readonly attemptedAt: number;
+    readonly updatedAt: number;
+    readonly installedVersion: string | null;
+    readonly failure: string | null;
+}
+export declare class AutomaticUpdateStateStore {
+    readonly path: string;
+    constructor(dataDir: string);
+    read(): Promise<AutomaticUpdateState | null>;
+    write(value: AutomaticUpdateState): Promise<void>;
+}
+export interface AutomaticUpdateRequestOptions {
+    readonly release: AvailableRelease;
+    readonly runningVersion: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+    readonly now?: () => number;
+    readonly spawnWorker?: (entry: string, arguments_: readonly string[], environment: NodeJS.ProcessEnv) => Promise<void>;
+    readonly sleep?: (durationMs: number) => Promise<void>;
+    /** Focused-test seams; production resolves both from the certified launch cohort. */
+    readonly worker?: {
+        readonly entry: string;
+        readonly packageRoot: string;
+    };
+    readonly activeVersion?: () => Promise<string | null>;
+}
+/** Start or observe one silent update and resolve with the active newer version once restart is useful. */
+export declare function requestAutomaticUpdate(options: AutomaticUpdateRequestOptions): Promise<string | null>;
+export declare function runAutomaticUpdateWorker(argv: readonly string[], environment?: NodeJS.ProcessEnv): Promise<number>;