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

package/dist/features/resident-tab/{shortcuts.js → shortcut-declarations.js}

@@ -1,14 +1,19 @@
-import { GLOBAL_SCOPE, ShortcutRegistry } from "../../ui/components/index.js";
 const jumps = Array.from({ length: 10 }, (_, index) => ({
     id: `tabs.jump${index + 1}`,
     defaultKey: `alt+${(index + 1) % 10}`,
     scope: "global",
     description: `View A1 tab ${index + 1}`,
 }));
+/**
+ * The tab shortcut declarations, in the order that decides which action keeps a duplicated key.
+ * This module stays dependency-free so startup presentation and the resident projection can
+ * read it without loading the component registry.
+ */
 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" },
@@ -17,19 +22,3 @@ export const RESIDENT_TAB_SHORTCUTS = Object.freeze([
     { id: "tabs.retry", defaultKey: "r", scope: "failed-banner", description: "Retry failed A1 tab" },
     { id: "tabs.fresh", defaultKey: "f", scope: "failed-banner", description: "Start failed A1 tab fresh" },
 ]);
-export function residentTabShortcutRegistry(assignments = {}) {
-    const registry = new ShortcutRegistry();
-    for (const shortcut of RESIDENT_TAB_SHORTCUTS) {
-        const key = assignments[shortcut.id] === undefined ? shortcut.defaultKey : assignments[shortcut.id];
-        if (!key)
-            continue;
-        const declaration = {
-            key,
-            scope: shortcut.scope === "global" ? GLOBAL_SCOPE : shortcut.scope,
-            section: "Tabs",
-            description: shortcut.description,
-        };
-        registry.declare(declaration, shortcut.id);
-    }
-    return registry;
-}

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

@@ -0,0 +1,29 @@
+import { type ResidentTabAction } from "./shortcut-declarations.js";
+/** Key assignments as `keybindings.json` and the keybinding manager express them. */
+export type ShortcutBindings = Readonly<Record<string, string | readonly string[] | null | undefined>>;
+export type ResidentTabGlobalAction = Exclude<ResidentTabAction, "tabs.retry" | "tabs.fresh">;
+export interface ResidentTabShortcutConflict {
+    readonly id: ResidentTabGlobalAction;
+    readonly key: string;
+    /** `reserved` keys belong to an A1 action; `duplicate` keys were claimed by an earlier tab action. */
+    readonly reason: "reserved" | "duplicate";
+}
+/** The effective tab shortcuts the resident shell dispatches and every presentation shows. */
+export interface ResidentTabShortcutProjection {
+    readonly assignments: Readonly<Record<ResidentTabGlobalAction, string | null>>;
+    readonly conflicts: readonly ResidentTabShortcutConflict[];
+}
+export interface ResidentTabShortcutInput {
+    /** The user's `keybindings.json`, including any `tabs.*` entries; `null` unbinds an action. */
+    readonly configured?: ShortcutBindings | undefined;
+    /** The effective A1 declarations (defaults plus customization) whose keys tab actions may not take. */
+    readonly reserved?: ShortcutBindings | undefined;
+}
+/** The declarations the projection covers, in the order that decides duplicate claims. */
+export declare const RESIDENT_TAB_GLOBAL_SHORTCUTS: import("./shortcut-declarations.js").ResidentTabShortcut[];
+/**
+ * Projects the effective A1 declarations and the user's customization into one tab shortcut
+ * assignment per action. A key an A1 action holds after customization never becomes a tab
+ * shortcut; between tab actions the earlier declaration keeps a duplicated key.
+ */
+export declare function projectResidentTabShortcuts(input?: ResidentTabShortcutInput): ResidentTabShortcutProjection;

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

@@ -0,0 +1,64 @@
+import { RESIDENT_TAB_SHORTCUTS } from "./shortcut-declarations.js";
+/** The declarations the projection covers, in the order that decides duplicate claims. */
+export const RESIDENT_TAB_GLOBAL_SHORTCUTS = RESIDENT_TAB_SHORTCUTS.filter(shortcut => shortcut.scope === "global");
+function normalizeKey(key) {
+    return key.trim().toLowerCase();
+}
+function keysOf(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "string")
+        return [value];
+    return value.filter((key) => typeof key === "string");
+}
+/**
+ * Projects the effective A1 declarations and the user's customization into one tab shortcut
+ * assignment per action. A key an A1 action holds after customization never becomes a tab
+ * shortcut; between tab actions the earlier declaration keeps a duplicated key.
+ */
+export function projectResidentTabShortcuts(input = {}) {
+    const configured = input.configured ?? {};
+    const claimedByOwnedActions = new Map();
+    for (const [action, value] of Object.entries(input.reserved ?? {})) {
+        if (action.startsWith("tabs."))
+            continue;
+        claimedByOwnedActions.set(action, keysOf(value) ?? []);
+    }
+    for (const [action, value] of Object.entries(configured)) {
+        if (action.startsWith("tabs.") || action === "$schema")
+            continue;
+        claimedByOwnedActions.set(action, keysOf(value) ?? []);
+    }
+    const reserved = new Set();
+    for (const keys of claimedByOwnedActions.values())
+        for (const key of keys)
+            reserved.add(normalizeKey(key));
+    const claimed = new Set();
+    const conflicts = [];
+    const assignments = {};
+    for (const shortcut of RESIDENT_TAB_GLOBAL_SHORTCUTS) {
+        const id = shortcut.id;
+        const custom = configured[id];
+        const candidates = custom === undefined
+            ? (shortcut.defaultKey === null ? [] : [shortcut.defaultKey])
+            : (keysOf(custom) ?? []);
+        let assigned = null;
+        for (const candidate of candidates.map(normalizeKey)) {
+            if (candidate.length === 0)
+                continue;
+            if (reserved.has(candidate)) {
+                conflicts.push({ id, key: candidate, reason: "reserved" });
+                continue;
+            }
+            if (claimed.has(candidate)) {
+                conflicts.push({ id, key: candidate, reason: "duplicate" });
+                continue;
+            }
+            assigned = candidate;
+            claimed.add(candidate);
+            break;
+        }
+        assignments[id] = assigned;
+    }
+    return { assignments, conflicts };
+}

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);
+}

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;