@timurproko/a1 0.2.7-dev.792 → 0.2.7-dev.794

package/dist/app/session-shell/session-shell-root.d.ts

@@ -46,6 +46,7 @@ export interface OwnedUiShellEngineOptions {
     /** Resident tab quit routes detach the outer client without stopping this engine session. */
     readonly residentTab?: {
         requestDetach(): Promise<boolean>;
+        closeOwnedRoute?(route: string): void;
         reportStatus?(status: "working" | "idle" | "stalled"): void;
         readonly stallNoticeSeconds?: number;
         admit?(input: {
@@ -191,6 +192,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly requestHyperlinkCleanup?: (rows?: readonly number[]) => void;
         readonly enableDockInputReuse?: boolean;
         readonly persistentHistory?: boolean;
+        readonly hideSettingsCommand?: boolean;
         readonly historyEditor?: import("../../integrations/pi/components/index.js").HistoryEditorConstructor;
         readonly onSubmit: (text: string) => void;
         readonly onPasteRejected?: (error: unknown) => void;

package/dist/app/session-shell/session-shell.d.ts

@@ -72,6 +72,7 @@ export declare class OwnedUiSessionPresenter implements OwnedUiHostedPresenter {
         readonly mode: "regular" | "fullscreen";
         readonly columns: number;
     }): OwnedUiPresenterRelease;
+    openOwnedRoute(route: string): void;
     hotkeysPresentation(): PiShellHotkeysPresentation;
 }
 /**

package/dist/app/session-shell/session-shell.js

@@ -189,6 +189,7 @@ export class OwnedUiSessionPresenter {
                 }),
                 enableDockInputReuse: inputPresentation?.viewportReuse !== false,
                 footerSessionName: this.#residentTabOptions === undefined,
+                hideSettingsCommand: this.#residentTabOptions !== undefined,
                 persistentHistory: this.#customViewport && promptHistory !== undefined,
                 ...(promptHistory === undefined ? {} : { historyEditor: promptHistory.editor }),
                 onSubmit: text => { void this.submit(text).catch(() => this.#reportSubmissionError()); },
@@ -1343,6 +1344,8 @@ export class OwnedUiSessionPresenter {
             return { outcome: "completed", diagnostic: null };
         }
         if (request.command === "settings" && request.selection === undefined && request.confirmed === undefined) {
+            if (this.#residentTabOptions !== undefined)
+                return rejected("Settings is available from the global Settings tab.");
             this.showSettingsSelector();
             return { outcome: "completed", diagnostic: null };
         }
@@ -1717,6 +1720,7 @@ export class OwnedUiSessionPresenter {
                         void onClosed?.()?.catch(() => undefined);
                     }
                     catch { /* Rationale: a failed acknowledgement stays pending. */ }
+                    this.#residentTabOptions?.closeOwnedRoute?.(route);
                 }
             },
         });
@@ -1764,6 +1768,9 @@ export class OwnedUiSessionPresenter {
         });
         this.#dialogId = dialog.id;
     }
+    openOwnedRoute(route) {
+        this.#openOwnedRoute(route);
+    }
     hotkeysPresentation() {
         const presentation = this.root.hotkeysPresentation();
         return this.#residentTabOptions === undefined ? presentation : { ...presentation, residentTabs: true };
@@ -1773,6 +1780,9 @@ export class OwnedUiSessionPresenter {
         const separator = body.search(/\s/);
         const name = separator < 0 ? body : body.slice(0, separator);
         const argument = separator < 0 ? "" : body.slice(separator + 1).trimStart();
+        if (name === "settings" && this.#residentTabOptions !== undefined) {
+            return rejected("Settings is available from the global Settings tab.");
+        }
         if (this.#routeHost?.claims(name))
             return this.#openOwnedRoute(name);
         if (this.#isWorkflowRoute(name))

package/dist/cli/tabs.js

@@ -30,7 +30,7 @@ export async function runTabsCommand(request, options = {}) {
             stateDir: report.stateDir,
             hostStatus: report,
             releaseRoots,
-            settings: { tabsMax: settings.tabsMax, tabsAutoName: settings.tabsAutoName },
+            settings: { tabsAutoName: settings.tabsAutoName },
         });
         if (request.json)
             stdout(`${JSON.stringify({ schema: "a1-tabs-doctor-v1", path: bundle.path, bytes: bundle.bytes, dropped: bundle.dropped })}\n`);

package/dist/composition/owned-ui.d.ts

@@ -87,5 +87,6 @@ export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOp
 export declare function composeOwnedUi(options?: OwnedUiCompositionOptions): Promise<OwnedUiComposition>;
 export declare function bindResidentTabBridge(tabBridge: TabBridgeClient, backend: Pick<ComposedSessionBackend, "identity" | "session" | "workflows" | "generateResidentTabName">, recovery?: Pick<ResidentTabRecovery, "settled"> | null, options?: {
     readonly autoName?: boolean;
+    readonly openRoute?: (route: "settings") => void;
 }): Promise<() => void>;
 export declare function correlateResidentTabSubmission(recovery: Pick<ResidentTabRecovery, "correlated" | "settled">, backend: Pick<ComposedSessionBackend, "identity" | "session">, submissionId: string, entryId: string): Promise<void>;

package/dist/composition/owned-ui.js

@@ -102,7 +102,7 @@ export async function composeOwnedUi(options = {}) {
             namespace: PRODUCT_IDENTITY.commandName,
             legacyConfigDir: productPaths.configDir,
             agentProvider: () => backend.settingsPort(),
-            ...(options.hideTabSettings ? { hiddenOwnedSettingIds: ["tabsMax", "tabsAutoName"] } : {}),
+            ...(options.hideTabSettings ? { hiddenOwnedSettingIds: ["tabsAutoName"] } : {}),
             hiddenAgentSettingIds: ["fullscreenWheelScrollLines"],
             agentSettingLabelOverrides: { fullscreenCopyOnSelect: "Copy on select" },
         });
@@ -167,7 +167,7 @@ export async function composeOwnedUi(options = {}) {
     if (tabBridge !== null && settings !== null && ownedSurfaces)
         tabBridge.accent(settings.value("accentColor"));
     let removeControllerBoundaryInput = () => { };
-    const unsubscribeTabBridge = tabBridge === null ? () => { } : await bindResidentTabBridge(tabBridge, backend, tabRecovery, { autoName: settings?.value("tabsAutoName") ?? true });
+    let unsubscribeTabBridge = () => { };
     let releaseNotes = null;
     let releaseNotesFailure;
     if (ownedSurfaces) {
@@ -293,6 +293,10 @@ export async function composeOwnedUi(options = {}) {
                 ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),
                 ...(tabBridge === null || tabRecovery === null ? {} : { residentTab: {
                         requestDetach: () => tabBridge.requestDetach(),
+                        closeOwnedRoute: route => {
+                            if (tabBridge.tabId.startsWith("settings-") && route === "settings")
+                                void tabBridge.requestClose();
+                        },
                         reportStatus: status => tabBridge.status(status),
                         stallNoticeSeconds: 300,
                         admit: input => tabRecovery.admit({ ...input, incarnation: options.tab.incarnation }),
@@ -344,6 +348,12 @@ export async function composeOwnedUi(options = {}) {
         if (recoveryDegraded)
             presentRecoveryDegraded(true);
         terminalHost.attach(presenter);
+        if (tabBridge !== null) {
+            unsubscribeTabBridge = await bindResidentTabBridge(tabBridge, backend, tabRecovery, {
+                autoName: settings?.value("tabsAutoName") ?? true,
+                openRoute: route => presenter.openOwnedRoute(route),
+            });
+        }
     }
     catch (error) {
         await createdTerminalHost?.dispose().catch(() => undefined);
@@ -477,7 +487,10 @@ export async function bindResidentTabBridge(tabBridge, backend, recovery = null,
             void backend.workflows.executeWorkflow({ command: "name", argument: command.name }).catch(() => { });
         }
         else if (command.type === "route") {
-            void backend.workflows.executeWorkflow({ command: command.route, argument: "" }).catch(() => { });
+            if (options.openRoute !== undefined)
+                options.openRoute(command.route);
+            else
+                void backend.workflows.executeWorkflow({ command: command.route, argument: "" }).catch(() => { });
         }
         else if (command.type === "stop") {
             void backend.session.dispose().catch(() => { });

package/dist/features/resident-tab/shortcut-declarations.d.ts

@@ -1,4 +1,4 @@
-export type ResidentTabAction = "tabs.new" | "tabs.close" | "tabs.rename" | "tabs.retry" | "tabs.fresh" | "tabs.next" | "tabs.previous" | "tabs.moveRight" | "tabs.moveLeft" | `tabs.jump${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10}`;
+export type ResidentTabAction = "tabs.new" | "tabs.close" | "tabs.rename" | "tabs.settings" | "tabs.retry" | "tabs.fresh" | "tabs.next" | "tabs.previous" | "tabs.moveRight" | "tabs.moveLeft" | `tabs.jump${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10}`;
 export interface ResidentTabShortcut {
     readonly id: ResidentTabAction;
     readonly defaultKey: string | null;

package/dist/features/resident-tab/shortcut-declarations.js

@@ -13,6 +13,7 @@ export const RESIDENT_TAB_SHORTCUTS = Object.freeze([
     { id: "tabs.new", defaultKey: "alt+a", scope: "global", description: "New A1 tab" },
     { id: "tabs.close", defaultKey: "alt+w", scope: "global", description: "Close A1 tab" },
     { id: "tabs.rename", defaultKey: "f2", scope: "global", description: "Rename A1 tab" },
+    { id: "tabs.settings", defaultKey: "alt+.", scope: "global", description: "Open Settings tab" },
     ...jumps,
     { id: "tabs.next", defaultKey: null, scope: "global", description: "View next A1 tab" },
     { id: "tabs.previous", defaultKey: null, scope: "global", description: "View previous A1 tab" },

package/dist/foundation/launch-guardian/exit-watcher.d.ts

@@ -0,0 +1,14 @@
+import { type ProcessGuardianAddon } from "../process-containment/index.js";
+interface ExitWatcherOptions {
+    readonly guardianPid: number;
+    readonly noticePath: string;
+    readonly encodedModes: string;
+    readonly addonPath: string;
+    readonly runtimePid: number;
+    readonly processGroup: number | null;
+    readonly foregroundGroup: number | null;
+}
+/** Waits outside launch containment, then performs the cleanup its dead guardian could not. */
+export declare function runExitWatcher(arguments_: readonly string[], platform?: NodeJS.Platform, loadAddon?: (path: string) => ProcessGuardianAddon): Promise<number>;
+export declare function exitWatcherArguments(options: ExitWatcherOptions): string[];
+export {};

package/dist/foundation/launch-guardian/exit-watcher.js

@@ -0,0 +1,94 @@
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { loadProcessGuardianAddon } from "../process-containment/index.js";
+/** Waits outside launch containment, then performs the cleanup its dead guardian could not. */
+export async function runExitWatcher(arguments_, platform = process.platform, loadAddon = loadProcessGuardianAddon) {
+    const options = parseArguments(arguments_);
+    const addon = loadAddon(options.addonPath);
+    if (platform === "win32")
+        addon.ignoreConsoleControl();
+    else {
+        process.on("SIGINT", ignoreSignal);
+        process.on("SIGTTOU", ignoreSignal);
+    }
+    try {
+        await addon.waitForProcessExit(options.guardianPid);
+        if (platform === "win32") {
+            // Rationale: job termination is asynchronous; keep the runtime's final frame ahead of the notice.
+            await Promise.race([
+                addon.waitForProcessExit(options.runtimePid),
+                delay(2_000),
+            ]);
+        }
+        else if (options.processGroup !== null) {
+            addon.stopProcessGroup(options.processGroup);
+            if (options.foregroundGroup !== null)
+                addon.restoreForegroundGroup(options.foregroundGroup);
+        }
+        addon.deliverExitNotice(options.noticePath, options.encodedModes);
+        return 0;
+    }
+    finally {
+        if (platform !== "win32") {
+            process.off("SIGINT", ignoreSignal);
+            process.off("SIGTTOU", ignoreSignal);
+        }
+    }
+}
+export function exitWatcherArguments(options) {
+    return [
+        "--guardian-pid", String(options.guardianPid),
+        "--notice", options.noticePath,
+        "--modes", options.encodedModes,
+        "--addon", options.addonPath,
+        "--runtime-pid", String(options.runtimePid),
+        ...(options.processGroup === null ? [] : ["--process-group", String(options.processGroup)]),
+        ...(options.foregroundGroup === null ? [] : ["--foreground-group", String(options.foregroundGroup)]),
+    ];
+}
+function parseArguments(arguments_) {
+    const values = new Map();
+    for (let index = 0; index < arguments_.length; index += 2) {
+        const name = arguments_[index];
+        const value = arguments_[index + 1];
+        if (!name?.startsWith("--") || value === undefined || values.has(name))
+            throw new TypeError("exit watcher arguments are malformed");
+        values.set(name, value);
+    }
+    const guardianPid = positiveInteger(values.get("--guardian-pid"), "guardian PID");
+    const runtimePid = positiveInteger(values.get("--runtime-pid"), "runtime PID");
+    const noticePath = boundedValue(values.get("--notice"), "notice path");
+    const encodedModes = boundedValue(values.get("--modes"), "terminal modes", 32_768);
+    const addonPath = boundedValue(values.get("--addon"), "addon path");
+    const processGroup = optionalPositiveInteger(values.get("--process-group"), "process group");
+    const foregroundGroup = optionalPositiveInteger(values.get("--foreground-group"), "foreground group");
+    const expected = 5 + (processGroup === null ? 0 : 1) + (foregroundGroup === null ? 0 : 1);
+    if (values.size !== expected)
+        throw new TypeError("exit watcher received an unknown argument");
+    return { guardianPid, noticePath, encodedModes, addonPath, runtimePid, processGroup, foregroundGroup };
+}
+function positiveInteger(value, name) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new TypeError(`exit watcher ${name} must be a positive safe integer`);
+    return parsed;
+}
+function optionalPositiveInteger(value, name) {
+    return value === undefined ? null : positiveInteger(value, name);
+}
+function boundedValue(value, name, limit = 4_096) {
+    if (!value || value.length > limit || value.includes("\0"))
+        throw new TypeError(`exit watcher ${name} is invalid`);
+    return value;
+}
+function delay(milliseconds) {
+    return new Promise(resolvePromise => setTimeout(resolvePromise, milliseconds));
+}
+function ignoreSignal() { }
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+    void runExitWatcher(process.argv.slice(2)).then(code => process.exit(code), error => {
+        process.stderr.write(`a1 exit watcher: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(2);
+    });
+}

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

@@ -1,6 +1,6 @@
 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";
+import { type NativeProcessInspector, type ProcessContainment, type ProcessGuardianAddon } from "../process-containment/index.js";
 interface GuardianControl {
     connect(endpoint: string, timeoutMs?: number): Promise<unknown>;
     command(command: SupervisorCommand): Promise<{
@@ -32,6 +32,7 @@ export interface LaunchGuardianOptions {
     readonly inspector?: NativeProcessInspector;
     readonly control?: GuardianControl;
     readonly containment?: ProcessContainment;
+    readonly addon?: ProcessGuardianAddon;
     readonly ensureHelper?: (path: string) => Promise<void>;
 }
 export declare function runLaunchGuardian(options: LaunchGuardianOptions): Promise<number>;

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,14 +50,26 @@ export async function runLaunchGuardian(options) {
             guardianIdentity,
         });
         let handle;
+        let encodedModes = null;
         try {
             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(),
@@ -89,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);
@@ -104,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/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);
+}