@timurproko/a1 0.1.0 → 0.1.1-dev.10

package/dist/src/foundation/pi-tui-runtime-adapter/conformance.d.ts

@@ -1,14 +1,18 @@
-import { PI_TUI_PACKAGE_VERSION } from "./contracts.js";
+export interface PiTuiRuntimeConformanceOptions {
+    readonly packageVersion: string;
+}
 export interface PiTuiRuntimeConformanceReport {
     readonly packageName: "@earendil-works/pi-tui";
-    readonly packageVersion: typeof PI_TUI_PACKAGE_VERSION;
+    readonly packageVersion: string;
     readonly mode: "regular" | "fullscreen";
+    readonly constructedModes: readonly ("regular" | "fullscreen")[];
     readonly lifecycleRestored: boolean;
     readonly inputRouted: boolean;
     readonly overlayRouted: boolean;
+    readonly focusRouted: boolean;
+    readonly widthBounded: boolean;
     readonly differentialRendering: boolean;
     readonly resizeRedraw: boolean;
     readonly terminalNativeSelection: boolean;
 }
-export declare function runPiTuiRuntimeConformance(): Promise<PiTuiRuntimeConformanceReport>;
-//# sourceMappingURL=conformance.d.ts.map
+export declare function runPiTuiRuntimeConformance(options: PiTuiRuntimeConformanceOptions): Promise<PiTuiRuntimeConformanceReport>;

package/dist/src/foundation/pi-tui-runtime-adapter/conformance.js

@@ -1,6 +1,8 @@
-import { PI_TUI_PACKAGE_VERSION } from "./contracts.js";
 import { PiTuiRuntimeAdapter, PiTuiRuntimeError } from "./adapter.js";
-export async function runPiTuiRuntimeConformance() {
+export async function runPiTuiRuntimeConformance(options) {
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(options.packageVersion)) {
+        throw new TypeError("Pi TUI conformance requires an exact package version from compatibility authority");
+    }
     const terminal = new ConformanceTerminal();
     const root = new ConformanceComponent(["stable row", "before"]);
     const overlay = new ConformanceComponent(["overlay"]);
@@ -24,20 +26,26 @@ export async function runPiTuiRuntimeConformance() {
         terminal.resize(60, 10);
         runtime.renderNow();
         const resizeRedraw = runtime.fullRedraws > redrawsBeforeResize && runtime.viewport().columns === 60;
+        const fullscreenConstructed = runtime.switchMode("fullscreen");
+        runtime.renderNow(true);
+        const regularRestored = runtime.switchMode("regular");
+        runtime.renderNow(true);
         await runtime.stop({ drainMaxMs: 1, drainIdleMs: 1 });
         const emitted = terminal.writes.join("");
         return {
             packageName: "@earendil-works/pi-tui",
-            packageVersion: PI_TUI_PACKAGE_VERSION,
+            packageVersion: options.packageVersion,
             mode: runtime.mode,
-            lifecycleRestored: terminal.startCount === 1
-                && terminal.stopCount === 1
+            constructedModes: fullscreenConstructed && regularRestored ? ["regular", "fullscreen"] : ["regular"],
+            lifecycleRestored: terminal.startCount >= 1
+                && terminal.startCount === terminal.stopCount
                 && terminal.drainCount === 1
-                && !emitted.includes("\x1b[?1049h")
-                && !emitted.includes("\x1b[?1049l")
+                && (emitted.match(/\x1b\[\?1049h/g)?.length ?? 0) === (emitted.match(/\x1b\[\?1049l/g)?.length ?? 0)
                 && root.disposed,
             inputRouted: root.inputs.includes("root-input"),
             overlayRouted,
+            focusRouted: root.focusChanges.includes(true) && overlay.focusChanges.includes(true),
+            widthBounded: root.widths.every(width => width <= terminal.columns) && overlay.widths.every(width => width <= 12),
             differentialRendering: differentialFrame.includes("after") && !differentialFrame.includes("stable row"),
             resizeRedraw,
             terminalNativeSelection: !emitted.includes("\x1b[?1000h") && !emitted.includes("\x1b[?1006h"),
@@ -54,13 +62,19 @@ export async function runPiTuiRuntimeConformance() {
 class ConformanceComponent {
     lines;
     inputs = [];
+    focusChanges = [];
+    widths = [];
     disposed = false;
     constructor(lines) {
         this.lines = lines;
     }
-    render() {
+    render(width) {
+        this.widths.push(width);
         return this.lines;
     }
+    setFocused(focused) {
+        this.focusChanges.push(focused);
+    }
     handleInput(data) {
         this.inputs.push(data);
     }
@@ -129,4 +143,3 @@ class ConformanceTerminal {
         this.write(`progress:${active}`);
     }
 }
-//# sourceMappingURL=conformance.js.map

package/dist/src/foundation/pi-tui-runtime-adapter/contracts.d.ts

@@ -1,4 +1,3 @@
-export declare const PI_TUI_PACKAGE_VERSION: "0.84.2";
 export type PiTuiRuntimeState = "idle" | "running" | "stopping" | "stopped" | "failed";
 export interface PiTuiViewport {
     readonly columns: number;
@@ -119,4 +118,3 @@ export interface PiTuiStopOptions {
     readonly drainMaxMs?: number;
     readonly drainIdleMs?: number;
 }
-//# sourceMappingURL=contracts.d.ts.map

package/dist/src/foundation/pi-tui-runtime-adapter/contracts.js

@@ -1,2 +1 @@
-export const PI_TUI_PACKAGE_VERSION = "0.84.2";
-//# sourceMappingURL=contracts.js.map
+export {};

package/dist/src/foundation/pi-tui-runtime-adapter/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./contracts.js";
 export * from "./adapter.js";
 export * from "./conformance.js";
-//# sourceMappingURL=index.d.ts.map
+export * from "./presentation-adapter.js";

package/dist/src/foundation/pi-tui-runtime-adapter/index.js

@@ -1,4 +1,4 @@
 export * from "./contracts.js";
 export * from "./adapter.js";
 export * from "./conformance.js";
-//# sourceMappingURL=index.js.map
+export * from "./presentation-adapter.js";

package/dist/src/foundation/pi-tui-runtime-adapter/presentation-adapter.d.ts

@@ -0,0 +1,4 @@
+import type { PresentationComponentPort, PresentationRuntimePort, PresentationTerminalPort } from "../presentation-contracts/index.js";
+import type { PiTuiTerminalPort } from "./contracts.js";
+export declare function createPiPresentationRuntime(root: PresentationComponentPort, terminal: PresentationTerminalPort): PresentationRuntimePort;
+export declare function createPiTerminalBridge(terminal: PresentationTerminalPort): PiTuiTerminalPort;

package/dist/src/foundation/pi-tui-runtime-adapter/presentation-adapter.js

@@ -0,0 +1,48 @@
+import { PiTuiRuntimeAdapter } from "./adapter.js";
+export function createPiPresentationRuntime(root, terminal) {
+    return new PresentationRuntimeAdapter(root, terminal);
+}
+class PresentationRuntimeAdapter {
+    terminal;
+    #runtime;
+    constructor(root, terminal) {
+        this.terminal = terminal;
+        this.#runtime = new PiTuiRuntimeAdapter({ root, terminal: createPiTerminalBridge(terminal), mouse: false });
+    }
+    get state() { return this.#runtime.state; }
+    start() { this.#runtime.start(); }
+    render(force) { this.#runtime.renderNow(force); }
+    showOverlay(component, options) {
+        const handle = this.#runtime.showOverlay(component, {
+            anchor: options.anchor === "top" ? "top-center" : options.anchor === "bottom" ? "bottom-center" : "center",
+            ...(options.width === undefined ? {} : { width: options.width }),
+        });
+        return {
+            get visible() { return !handle.isHidden(); },
+            hide: () => handle.hide(),
+            show: () => handle.setHidden(false),
+            focus: () => handle.focus(),
+            dispose: () => handle.hide(),
+        };
+    }
+    async stop() { await this.#runtime.stop(); }
+}
+export function createPiTerminalBridge(terminal) {
+    return {
+        get columns() { return terminal.columns; },
+        get rows() { return terminal.rows; },
+        get kittyProtocolActive() { return terminal.enhancedKeyboard; },
+        start: (input, resize) => terminal.start(input, resize),
+        stop: () => terminal.stop(),
+        drainInput: (max, idle) => terminal.drainInput(max, idle),
+        write: data => terminal.write(data),
+        moveBy: lines => terminal.moveBy(lines),
+        hideCursor: () => terminal.hideCursor(),
+        showCursor: () => terminal.showCursor(),
+        clearLine: () => terminal.clearLine(),
+        clearFromCursor: () => terminal.clearFromCursor(),
+        clearScreen: () => terminal.clearScreen(),
+        setTitle: title => terminal.setTitle(title),
+        setProgress: active => terminal.setProgress(active),
+    };
+}

package/dist/src/foundation/presentation-contracts/index.d.ts

@@ -0,0 +1,96 @@
+export type PresentationRuntimeState = "idle" | "running" | "stopping" | "stopped" | "failed";
+export interface PresentationComponentPort {
+    render(width: number): readonly string[];
+    invalidate(): void;
+    handleInput?(data: string): void;
+    setFocused?(focused: boolean): void;
+    dispose?(): void;
+}
+export interface PresentationEditorPort extends PresentationComponentPort {
+    getText(): string;
+    setText(text: string): void;
+    submit(): Promise<void> | void;
+}
+export interface PresentationSelectorItem {
+    readonly id: string;
+    readonly label: string;
+    readonly detail?: string;
+}
+export interface PresentationSelectorPort extends PresentationComponentPort {
+    setItems(items: readonly PresentationSelectorItem[]): void;
+    readonly selectedId: string | null;
+}
+export interface PresentationDialogPort extends PresentationComponentPort {
+    readonly dialogId: string;
+    close(outcome: "accepted" | "cancelled"): void;
+}
+export interface PresentationExtensionUiPort {
+    mount(slot: PresentationContributionSlot, component: PresentationComponentPort): () => void;
+}
+export type PresentationContributionSlot = "transcript" | "tool" | "editor" | "status" | "dialog" | "overlay";
+export type PresentationFocusTarget = "transcript" | "editor" | "dialog" | "overlay" | "status";
+export interface PresentationFocusPort {
+    readonly focused: PresentationFocusTarget;
+    focus(target: PresentationFocusTarget): void;
+}
+export interface PresentationTerminalPort {
+    readonly columns: number;
+    readonly rows: number;
+    readonly enhancedKeyboard: boolean;
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    write(data: string): void;
+    moveBy(lines: number): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+    showCursor(): void;
+    hideCursor(): void;
+}
+export type PresentationLayoutNode = {
+    readonly type: "component";
+    readonly component: PresentationComponentPort;
+} | {
+    readonly type: "stack";
+    readonly direction: "vertical" | "horizontal";
+    readonly children: readonly PresentationLayoutNode[];
+    readonly gap?: number;
+} | {
+    readonly type: "scroll";
+    readonly id: string;
+    readonly child: PresentationLayoutNode;
+    readonly follow: "none" | "end";
+};
+export interface PresentationOverlayOptions {
+    readonly anchor: "center" | "top" | "bottom";
+    readonly width?: number | `${number}%`;
+    readonly modal: boolean;
+}
+export interface PresentationOverlayHandle {
+    readonly visible: boolean;
+    hide(): void;
+    show(): void;
+    focus(): void;
+    dispose(): void;
+}
+export interface OwnedUiApplicationPort {
+    readonly disposed: boolean;
+    start(): void;
+    flush(): Promise<void>;
+    waitUntilStopped(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface PresentationRuntimePort {
+    readonly state: PresentationRuntimeState;
+    readonly terminal: PresentationTerminalPort;
+    start(): void;
+    render(force?: boolean): void;
+    showOverlay(component: PresentationComponentPort, options: PresentationOverlayOptions): PresentationOverlayHandle;
+    stop(): Promise<void>;
+}
+export declare function assertPresentationComponent(component: PresentationComponentPort): void;
+export declare function assertPresentationRuntime(runtime: PresentationRuntimePort): void;
+export declare function probePresentationLifecycle(runtime: PresentationRuntimePort): Promise<void>;

package/dist/src/foundation/presentation-contracts/index.js

@@ -0,0 +1,38 @@
+export function assertPresentationComponent(component) {
+    requiredFunctions(component, ["render", "invalidate"], "presentation component");
+    const lines = component.render(80);
+    if (!Array.isArray(lines) || lines.some(line => typeof line !== "string" || line.includes("\n") || line.includes("\r"))) {
+        throw new TypeError("presentation component render must return newline-free string rows");
+    }
+}
+export function assertPresentationRuntime(runtime) {
+    requiredFunctions(runtime, ["start", "render", "showOverlay", "stop"], "presentation runtime");
+    if (!new Set(["idle", "running", "stopping", "stopped", "failed"]).has(runtime.state))
+        throw new TypeError("presentation runtime state is invalid");
+    const terminal = runtime.terminal;
+    requiredFunctions(terminal, ["start", "stop", "drainInput", "write", "moveBy", "clearLine", "clearFromCursor", "clearScreen", "setTitle", "setProgress", "showCursor", "hideCursor"], "presentation terminal");
+    if (!Number.isSafeInteger(terminal.columns) || terminal.columns < 1 || !Number.isSafeInteger(terminal.rows) || terminal.rows < 1)
+        throw new TypeError("presentation terminal geometry is invalid");
+}
+export async function probePresentationLifecycle(runtime) {
+    assertPresentationRuntime(runtime);
+    if (runtime.state !== "idle")
+        throw new TypeError("presentation runtime must begin idle");
+    runtime.start();
+    if (runtime.state !== "running")
+        throw new TypeError("presentation runtime did not enter running state");
+    runtime.render(true);
+    await runtime.stop();
+    if (runtime.state !== "stopped")
+        throw new TypeError("presentation runtime did not enter stopped state");
+    await runtime.stop();
+    if (runtime.state !== "stopped")
+        throw new TypeError("presentation runtime stop is not idempotent");
+}
+function requiredFunctions(value, names, label) {
+    if (!value)
+        throw new TypeError(`${label} is required`);
+    for (const name of names)
+        if (typeof value[name] !== "function")
+            throw new TypeError(`${label} requires ${name}`);
+}

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

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

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

@@ -0,0 +1,34 @@
+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");
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    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
+        || manifest.platform !== platform || manifest.architecture !== architecture
+        || manifest.artifact?.filename !== basename(helperPath)) {
+        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 => {
+        throw artifactError(`process guardian artifact is unavailable: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_MISSING");
+    });
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (metadata.size !== manifest.artifact.size || digest !== manifest.artifact.sha256) {
+        throw artifactError("process guardian artifact integrity verification failed", "CONTAINMENT_ARTIFACT_TAMPERED");
+    }
+}
+function artifactError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,31 @@
+import type { LaunchInstanceOutcome, LaunchInstanceStopReason, NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+export interface ContainedSpawnOptions {
+    readonly cwd: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly terminalType?: string;
+}
+export interface ContainedProcessHandle {
+    readonly identity: NativeProcessIdentity;
+    readonly outcome: Promise<LaunchInstanceOutcome>;
+}
+export interface NativeProcessInspector {
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}
+export interface ProcessContainment {
+    readonly identity: ProcessContainmentIdentity;
+    spawn(executable: string, arguments_: readonly string[], options: ContainedSpawnOptions): Promise<ContainedProcessHandle>;
+    contains(identity: NativeProcessIdentity): Promise<boolean>;
+    stop(force: boolean): Promise<void>;
+    waitForEmpty(timeoutMs: number): Promise<boolean>;
+    close(): Promise<void>;
+}
+export interface ProcessContainmentFactory {
+    create(instanceId: string): Promise<ProcessContainment>;
+}
+export interface ContainmentCloseResult {
+    readonly outcome: LaunchInstanceOutcome;
+    readonly graceful: boolean;
+    readonly forced: boolean;
+}
+export declare function closeVerifiedContainment(containment: ProcessContainment, inspector: NativeProcessInspector, rootIdentity: NativeProcessIdentity, reason: LaunchInstanceStopReason, deadlineMs?: number): Promise<ContainmentCloseResult>;

package/dist/src/foundation/process-containment/contracts.js

@@ -0,0 +1,35 @@
+export async function closeVerifiedContainment(containment, inspector, rootIdentity, reason, deadlineMs = 1_500) {
+    if (!await ownershipMatches(containment, inspector, rootIdentity)) {
+        return ownershipMismatch("refusing graceful cleanup because launch-instance ownership changed");
+    }
+    await containment.stop(false);
+    if (await containment.waitForEmpty(deadlineMs)) {
+        return { outcome: { kind: "stopped", reason }, graceful: true, forced: false };
+    }
+    if (!await ownershipMatches(containment, inspector, rootIdentity)) {
+        return ownershipMismatch("refusing forced cleanup because launch-instance ownership changed");
+    }
+    await containment.stop(true);
+    if (await containment.waitForEmpty(deadlineMs)) {
+        return { outcome: { kind: "stopped", reason }, graceful: false, forced: true };
+    }
+    return {
+        outcome: {
+            kind: "cleanup-error",
+            message: "launch-instance process tree did not exit within the bounded cleanup deadline",
+            code: "CONTAINMENT_CLEANUP_TIMEOUT",
+        },
+        graceful: false,
+        forced: true,
+    };
+}
+async function ownershipMatches(containment, inspector, rootIdentity) {
+    return await inspector.matches(rootIdentity) && await containment.contains(rootIdentity);
+}
+function ownershipMismatch(message) {
+    return {
+        outcome: { kind: "cleanup-error", message, code: "PROCESS_IDENTITY_MISMATCH" },
+        graceful: false,
+        forced: false,
+    };
+}

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

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

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

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

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

@@ -0,0 +1,6 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+export declare class LinuxNativeProcessInspector implements NativeProcessInspector {
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

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

@@ -0,0 +1,26 @@
+import { readFile } from "node:fs/promises";
+export class LinuxNativeProcessInspector {
+    async observe(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new TypeError("inspected PID must be a positive safe integer");
+        let stat;
+        try {
+            stat = await readFile(`/proc/${pid}/stat`, "utf8");
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+        const commandEnd = stat.lastIndexOf(")");
+        const fields = commandEnd >= 0 ? stat.slice(commandEnd + 1).trim().split(/\s+/) : [];
+        const startTicks = fields[19];
+        if (!startTicks || !/^\d+$/.test(startTicks))
+            throw new Error("process stat has no valid start-time field");
+        return { pid, startIdentity: `linux-proc-start:${startTicks}` };
+    }
+    async matches(identity) {
+        const observed = await this.observe(identity.pid);
+        return observed !== null && observed.startIdentity === identity.startIdentity;
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+import type { ContainedProcessHandle, ContainedSpawnOptions, ProcessContainment } from "./contracts.js";
+export declare class NativeGuardianContainment implements ProcessContainment {
+    #private;
+    readonly instanceId: string;
+    readonly helperPath: string;
+    readonly statusPath: string;
+    constructor(instanceId: string, helperPath: string, statusPath: string);
+    get identity(): ProcessContainmentIdentity;
+    spawn(executable: string, arguments_: readonly string[], options: ContainedSpawnOptions): Promise<ContainedProcessHandle>;
+    contains(identity: NativeProcessIdentity): Promise<boolean>;
+    stop(force: boolean): Promise<void>;
+    waitForEmpty(timeoutMs: number): Promise<boolean>;
+    close(): Promise<void>;
+}
+export declare function resolveProcessGuardianPath(releaseRoot: string, environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, architecture?: string): string;

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

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export class NativeGuardianContainment {
+    instanceId;
+    helperPath;
+    statusPath;
+    #identity;
+    #helper = null;
+    #rootIdentity = null;
+    #outcome = null;
+    constructor(instanceId, helperPath, statusPath) {
+        this.instanceId = instanceId;
+        this.helperPath = helperPath;
+        this.statusPath = statusPath;
+        this.#identity = { provider: "native-guardian-pending", token: instanceId };
+    }
+    get identity() {
+        return this.#identity;
+    }
+    async spawn(executable, arguments_, options) {
+        if (this.#helper)
+            throw new Error("process containment already has a root runtime");
+        await mkdir(dirname(this.statusPath), { recursive: true, mode: 0o700 });
+        await rm(this.statusPath, { force: true });
+        const helper = spawn(this.helperPath, [
+            "--parent-pid", String(process.pid),
+            "--instance", this.instanceId,
+            "--status-file", this.statusPath,
+            "--", executable, ...arguments_,
+        ], {
+            cwd: options.cwd,
+            env: { ...options.environment, ...(options.terminalType ? { TERM: options.terminalType } : {}) },
+            shell: false,
+            stdio: "inherit",
+            windowsHide: false,
+        });
+        this.#helper = helper;
+        this.#outcome = helperOutcome(helper);
+        const status = await waitForReadyStatus(this.statusPath, this.#outcome, 5_000);
+        this.#rootIdentity = { pid: status.pid, startIdentity: status.startIdentity };
+        this.#identity = { provider: status.containmentProvider, token: status.containmentToken };
+        return { identity: this.#rootIdentity, outcome: this.#outcome };
+    }
+    async contains(identity) {
+        return this.#rootIdentity !== null
+            && identity.pid === this.#rootIdentity.pid
+            && identity.startIdentity === this.#rootIdentity.startIdentity;
+    }
+    async stop(force) {
+        const root = this.#rootIdentity;
+        if (!root)
+            return;
+        try {
+            process.kill(root.pid, force ? "SIGKILL" : "SIGTERM");
+        }
+        catch { }
+    }
+    async waitForEmpty(timeoutMs) {
+        if (!this.#helper || this.#helper.exitCode !== null || this.#helper.signalCode !== null)
+            return true;
+        return await new Promise(resolvePromise => {
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            timer.unref();
+            const finish = (empty) => {
+                clearTimeout(timer);
+                this.#helper?.off("close", onClose);
+                resolvePromise(empty);
+            };
+            const onClose = () => finish(true);
+            this.#helper?.once("close", onClose);
+        });
+    }
+    async close() {
+        const helper = this.#helper;
+        if (helper && helper.exitCode === null && helper.signalCode === null)
+            helper.kill("SIGKILL");
+        await this.waitForEmpty(1_500);
+        await rm(this.statusPath, { force: true });
+    }
+}
+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);
+    const executable = platform === "win32"
+        ? `${PRODUCT_IDENTITY.artifacts.processGuardianExecutable}.exe`
+        : PRODUCT_IDENTITY.artifacts.processGuardianExecutable;
+    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, executable);
+}
+function helperOutcome(helper) {
+    return new Promise(resolvePromise => {
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise(outcome);
+        };
+        helper.once("error", error => settle({ kind: "guardian-error", message: error.message, code: errorCode(error) }));
+        helper.once("close", (code, signal) => {
+            if (signal)
+                settle({ kind: "signaled", signal });
+            else
+                settle({ kind: "exited", exitCode: code ?? 1 });
+        });
+    });
+}
+async function waitForReadyStatus(path, outcome, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let terminalOutcome = null;
+    void outcome.then(value => { terminalOutcome = value; });
+    while (Date.now() < deadline) {
+        try {
+            const value = JSON.parse(await readFile(path, "utf8"));
+            if (isReadyStatus(value))
+                return value;
+            throw new Error("process guardian published invalid ready status");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        if (terminalOutcome)
+            throw new Error(`process guardian exited before readiness: ${JSON.stringify(terminalOutcome)}`);
+        await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
+    }
+    throw new Error(`process guardian did not publish readiness within ${timeoutMs}ms`);
+}
+function isReadyStatus(value) {
+    return Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+        && typeof value.startIdentity === "string" && value.startIdentity.length > 0
+        && typeof value.containmentProvider === "string" && value.containmentProvider.length > 0
+        && typeof value.containmentToken === "string" && value.containmentToken.length > 0;
+}
+function errorCode(error) {
+    return "code" in error && typeof error.code === "string" ? error.code : null;
+}

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

@@ -0,0 +1,17 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+export interface InspectorCommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface InspectorCommandRunner {
+    run(executable: string, arguments_: readonly string[]): Promise<InspectorCommandResult>;
+}
+export declare class WindowsNativeProcessInspector implements NativeProcessInspector {
+    readonly helperPath: string;
+    private readonly runner;
+    constructor(helperPath: string, runner?: InspectorCommandRunner);
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}