@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/dist/features/resident-tab/auto-name.js

@@ -0,0 +1,44 @@
+export const AUTO_NAME_MAX_LENGTH = 16;
+export const AUTO_NAME_TIMEOUT_MS = 30_000;
+// Rationale: reasoning models can spend a small ceiling on hidden thinking and emit no title, so an
+// answerless attempt retries with a larger bound; budgets stay strictly increasing, as in v2.
+export const AUTO_NAME_TOKEN_BUDGETS = [4_096, 32_768];
+export function normalizeAutoName(value) {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
+    if (!normalized)
+        return null;
+    if (normalized.length <= AUTO_NAME_MAX_LENGTH)
+        return normalized;
+    const clipped = normalized.slice(0, AUTO_NAME_MAX_LENGTH + 1);
+    const boundary = clipped.lastIndexOf("-");
+    const result = (boundary >= 4 ? clipped.slice(0, boundary) : normalized.slice(0, AUTO_NAME_MAX_LENGTH)).replace(/-+$/g, "");
+    return result || null;
+}
+export function fallbackAutoName(prompt) {
+    const words = prompt.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+    return normalizeAutoName(words.slice(0, 3).join("-")) ?? "new-task";
+}
+export async function generateAutoName(firstPrompt, complete, timeoutMs = AUTO_NAME_TIMEOUT_MS) {
+    for (const maxTokens of AUTO_NAME_TOKEN_BUDGETS) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        timer.unref?.();
+        try {
+            const response = await complete({
+                prompt: `Name this coding task with a lowercase hyphenated title of at most ${AUTO_NAME_MAX_LENGTH} characters. Reply only with the title.\n\n${firstPrompt.slice(0, 500)}`,
+                maxTokens,
+                signal: controller.signal,
+            });
+            const name = response === null ? null : normalizeAutoName(response);
+            if (name !== null)
+                return name;
+        }
+        catch {
+            // Rationale: naming is best effort; the larger bounded attempt precedes the deterministic fallback.
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return fallbackAutoName(firstPrompt);
+}

package/dist/features/resident-tab/index.d.ts

@@ -0,0 +1,5 @@
+export { AUTO_NAME_MAX_LENGTH, AUTO_NAME_TIMEOUT_MS, AUTO_NAME_TOKEN_BUDGETS, fallbackAutoName, generateAutoName, normalizeAutoName, type AutoNameCompletion, } from "./auto-name.js";
+export { RESIDENT_TAB_SHORTCUTS, type ResidentTabAction, type ResidentTabShortcut, } from "./shortcut-declarations.js";
+export { projectResidentTabShortcuts, RESIDENT_TAB_GLOBAL_SHORTCUTS, type ResidentTabGlobalAction, type ResidentTabShortcutConflict, type ResidentTabShortcutProjection, type ShortcutBindings, } from "./shortcut-projection.js";
+export { readShortcutBindingsFile } from "./shortcut-bindings-file.js";
+export { deriveResidentTabStatus, type ResidentTabDerivedStatus, type ResidentTabFacts, } from "./status-deriver.js";

package/dist/features/resident-tab/index.js

@@ -0,0 +1,7 @@
+export { AUTO_NAME_MAX_LENGTH, AUTO_NAME_TIMEOUT_MS, AUTO_NAME_TOKEN_BUDGETS, fallbackAutoName, generateAutoName, normalizeAutoName, } from "./auto-name.js";
+// Performance: the registry builder lives in `shortcuts.ts`, outside this barrel, so startup
+// presentation can read the declarations without loading the component registry.
+export { RESIDENT_TAB_SHORTCUTS, } from "./shortcut-declarations.js";
+export { projectResidentTabShortcuts, RESIDENT_TAB_GLOBAL_SHORTCUTS, } from "./shortcut-projection.js";
+export { readShortcutBindingsFile } from "./shortcut-bindings-file.js";
+export { deriveResidentTabStatus, } from "./status-deriver.js";

package/dist/features/resident-tab/shortcut-bindings-file.d.ts

@@ -0,0 +1,8 @@
+import type { ShortcutBindings } from "./shortcut-projection.js";
+/** Largest `keybindings.json` the projection reads; a larger file counts as absent. */
+export declare const MAX_SHORTCUT_BINDINGS_BYTES: number;
+/**
+ * Reads the user's `keybindings.json` as shortcut bindings, keeping `null` entries so an
+ * explicit unbind survives, and treating any unreadable or malformed file as empty.
+ */
+export declare function readShortcutBindingsFile(agentDir: string): ShortcutBindings;

package/dist/features/resident-tab/shortcut-bindings-file.js

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Largest `keybindings.json` the projection reads; a larger file counts as absent. */
+export const MAX_SHORTCUT_BINDINGS_BYTES = 256 * 1024;
+/**
+ * Reads the user's `keybindings.json` as shortcut bindings, keeping `null` entries so an
+ * explicit unbind survives, and treating any unreadable or malformed file as empty.
+ */
+export function readShortcutBindingsFile(agentDir) {
+    let text;
+    try {
+        text = readFileSync(join(agentDir, "keybindings.json"), "utf8");
+    }
+    catch {
+        return {};
+    }
+    if (text.length > MAX_SHORTCUT_BINDINGS_BYTES)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(text.replace(/^/u, ""));
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return {};
+    const bindings = {};
+    for (const [action, value] of Object.entries(parsed)) {
+        if (action === "$schema")
+            continue;
+        if (value === null || typeof value === "string") {
+            bindings[action] = value;
+            continue;
+        }
+        if (Array.isArray(value))
+            bindings[action] = value.filter((key) => typeof key === "string");
+    }
+    return bindings;
+}

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

@@ -0,0 +1,13 @@
+export type ResidentTabAction = "tabs.new" | "tabs.close" | "tabs.rename" | "tabs.settings" | "tabs.changelog" | "tabs.commands" | "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;
+    readonly scope: "global" | "failed-banner";
+    readonly description: string;
+}
+/**
+ * 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 declare const RESIDENT_TAB_SHORTCUTS: readonly ResidentTabShortcut[];

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

@@ -0,0 +1,26 @@
+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" },
+    { id: "tabs.changelog", defaultKey: null, scope: "global", description: "Open Changelog tab" },
+    { id: "tabs.commands", defaultKey: "alt+/", scope: "global", description: "Open command palette" },
+    ...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" },
+    { id: "tabs.moveRight", defaultKey: null, scope: "global", description: "Move A1 tab right" },
+    { id: "tabs.moveLeft", defaultKey: null, scope: "global", description: "Move A1 tab left" },
+    { 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" },
+]);

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/features/resident-tab/status-deriver.d.ts

@@ -0,0 +1,10 @@
+/** How the tab's last agent turn settled; it persists until the next turn starts. */
+export type ResidentTabTurnSettlement = "done" | "aborted" | "error";
+export type ResidentTabDerivedStatus = "starting" | "working" | "needs-input" | "idle" | "failed" | ResidentTabTurnSettlement;
+export interface ResidentTabFacts {
+    readonly lifecycle: string;
+    readonly pendingRequests: number;
+    readonly queuedInput: number;
+    readonly lastTurn?: ResidentTabTurnSettlement;
+}
+export declare function deriveResidentTabStatus(facts: ResidentTabFacts): ResidentTabDerivedStatus;

package/dist/features/resident-tab/status-deriver.js

@@ -0,0 +1,12 @@
+// Invariant: `failed` is reserved for a failed tab lifecycle; a turn that errored reports `error`.
+export function deriveResidentTabStatus(facts) {
+    if (facts.lifecycle === "failed")
+        return "failed";
+    if (facts.pendingRequests > 0)
+        return "needs-input";
+    if (facts.lifecycle === "busy" || facts.queuedInput > 0)
+        return "working";
+    if (facts.lifecycle === "starting")
+        return "starting";
+    return facts.lastTurn ?? "idle";
+}

package/dist/foundation/launch-context/index.d.ts

@@ -6,7 +6,12 @@ export declare const PRIVATE_ENVIRONMENT: Readonly<{
     releaseDigest: "LAUNCH_CONTEXT_RELEASE_DIGEST";
     releaseLayers: "LAUNCH_CONTEXT_RELEASE_LAYERS";
     launchProfile: "LAUNCH_CONTEXT_PROFILE";
+    launchMode: "LAUNCH_CONTEXT_MODE";
+    updateVersion: "LAUNCH_CONTEXT_UPDATE_VERSION";
     immutableWarmup: "LAUNCH_CONTEXT_WARMUP";
+    residentRootExecutable: "LAUNCH_CONTEXT_RESIDENT_ROOT_EXECUTABLE";
+    residentRootArguments: "LAUNCH_CONTEXT_RESIDENT_ROOT_ARGUMENTS";
+    residentFallback: "LAUNCH_CONTEXT_RESIDENT_FALLBACK";
 }>;
 /**
  * Keys published by releases that predate the neutral cutover. They are read when
@@ -30,8 +35,15 @@ export interface LaunchContext {
     readonly releaseDigest?: string;
     readonly releaseLayers?: string;
     readonly launchProfile?: "a1" | "pi";
+    readonly launchMode?: "tabs" | "solo";
+    readonly updateVersion?: string;
     readonly immutableWarmup?: "1";
+    readonly residentRootExecutable?: string;
+    readonly residentRootArguments?: string;
+    readonly residentFallback?: string;
 }
+/** The Tabs settings configure resident tabs; a direct-route launch, by `a1 solo` or by a fallback, hides them. */
+export declare function hidesTabSettings(context: Pick<LaunchContext, "launchMode" | "residentFallback">): boolean;
 export type LaunchContextRequirement = "optional" | "profile" | "release" | "warmup";
 /** Read current keys, fall back to superseded keys per field, with bounded diagnostics. */
 export declare function readLaunchContext(environment: NodeJS.ProcessEnv, requirement?: LaunchContextRequirement, platform?: NodeJS.Platform): LaunchContext;

package/dist/foundation/launch-context/index.js

@@ -6,7 +6,12 @@ export const PRIVATE_ENVIRONMENT = Object.freeze({
     releaseDigest: "LAUNCH_CONTEXT_RELEASE_DIGEST",
     releaseLayers: "LAUNCH_CONTEXT_RELEASE_LAYERS",
     launchProfile: "LAUNCH_CONTEXT_PROFILE",
+    launchMode: "LAUNCH_CONTEXT_MODE",
+    updateVersion: "LAUNCH_CONTEXT_UPDATE_VERSION",
     immutableWarmup: "LAUNCH_CONTEXT_WARMUP",
+    residentRootExecutable: "LAUNCH_CONTEXT_RESIDENT_ROOT_EXECUTABLE",
+    residentRootArguments: "LAUNCH_CONTEXT_RESIDENT_ROOT_ARGUMENTS",
+    residentFallback: "LAUNCH_CONTEXT_RESIDENT_FALLBACK",
 });
 /**
  * Keys published by releases that predate the neutral cutover. They are read when
@@ -27,6 +32,10 @@ const SUPERSEDED_ENTRIES = Object.entries(SUPERSEDED_ENVIRONMENT);
 const PRIVATE_KEYS = new Set([...Object.values(PRIVATE_ENVIRONMENT), ...Object.values(SUPERSEDED_ENVIRONMENT)]);
 const LOGICAL_KEYS = new Map(PRIVATE_ENTRIES.map(([logical, key]) => [key, logical]));
 const SUPERSEDED_LOGICAL_KEYS = new Map(SUPERSEDED_ENTRIES.map(([logical, key]) => [key, logical]));
+/** The Tabs settings configure resident tabs; a direct-route launch, by `a1 solo` or by a fallback, hides them. */
+export function hidesTabSettings(context) {
+    return context.launchMode === "solo" || context.residentFallback !== undefined;
+}
 /** Read current keys, fall back to superseded keys per field, with bounded diagnostics. */
 export function readLaunchContext(environment, requirement = "optional", platform = process.platform) {
     const values = {};
@@ -61,8 +70,25 @@ export function readLaunchContext(environment, requirement = "optional", platfor
     if (values.launchProfile !== undefined && values.launchProfile !== "a1" && values.launchProfile !== "pi") {
         throw invalidContext("launchProfile", "unsupported profile");
     }
+    if (values.launchMode !== undefined && values.launchMode !== "tabs" && values.launchMode !== "solo") {
+        throw invalidContext("launchMode", "unsupported launch mode");
+    }
+    if (values.launchProfile === "pi" && values.launchMode === "tabs")
+        throw invalidContext("launchMode", "Pi comparison cannot use tabs");
     if (values.immutableWarmup !== undefined && values.immutableWarmup !== "1")
         throw invalidContext("immutableWarmup", "invalid permission flag");
+    if ((values.residentRootExecutable === undefined) !== (values.residentRootArguments === undefined))
+        throw invalidContext("residentRootExecutable", "resident root command is incomplete");
+    if (values.residentRootArguments !== undefined) {
+        try {
+            const argumentsValue = JSON.parse(values.residentRootArguments);
+            if (!Array.isArray(argumentsValue) || argumentsValue.some(value => typeof value !== "string"))
+                throw new Error("not string arguments");
+        }
+        catch {
+            throw invalidContext("residentRootArguments", "invalid JSON argument list");
+        }
+    }
     if (values.releaseDigest !== undefined && !/^[a-f0-9]{64}$/.test(values.releaseDigest))
         throw invalidContext("releaseDigest", "invalid digest");
     if (requirement === "profile")

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<{
@@ -16,17 +16,23 @@ interface GuardianControl {
     off(event: "disconnect", listener: () => void): unknown;
     close(): void;
 }
+export interface LaunchGuardianRootCommand {
+    readonly executable: string;
+    readonly arguments: readonly string[];
+}
 export interface LaunchGuardianOptions {
     readonly profileId: LaunchProfileId;
     readonly releaseRoot: string;
     readonly uiEntry: string;
     readonly sessionSelection?: SessionSelection;
+    readonly rootCommand?: LaunchGuardianRootCommand;
     readonly environment?: NodeJS.ProcessEnv;
     readonly cwd?: string;
     readonly helperPath?: string;
     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,13 +50,26 @@ export async function runLaunchGuardian(options) {
             guardianIdentity,
         });
         let handle;
+        let encodedModes = null;
         try {
-            handle = await containment.spawn(process.execPath, [options.uiEntry, ...sessionArgs], {
+            const rootCommand = options.rootCommand ?? { executable: process.execPath, arguments: [options.uiEntry, ...sessionArgs] };
+            encodedModes = addon?.captureTerminalModes() ?? null;
+            handle = await containment.spawn(rootCommand.executable, [...rootCommand.arguments], {
                 cwd: options.cwd ?? process.cwd(),
                 environment: environmentEntries(environment),
                 ...(environment.TERM ? { terminalType: environment.TERM } : {}),
             });
             rootIdentity = handle.identity;
+            if (addon && encodedModes !== null) {
+                await startExitWatcher(addon, {
+                    addonPath: helperPath,
+                    noticePath: exitNoticePath,
+                    encodedModes,
+                    runtimePid: handle.identity.pid,
+                    processGroup: handle.processGroup ?? null,
+                    foregroundGroup: handle.foregroundGroup ?? null,
+                });
+            }
             await requireAccepted(client, {
                 type: "activate-launch-instance",
                 requestId: randomUUID(),
@@ -88,6 +108,10 @@ export async function runLaunchGuardian(options) {
                 return result.outcome;
             }),
         ]);
+        // Invariant: the root removes a clean notice. If it left the notice armed, the guardian claims,
+        // restores, and prints it before closing the native containment handle.
+        if (addon && encodedModes !== null)
+            addon.deliverExitNotice(exitNoticePath, encodedModes);
         await containment.close();
         if (outcome.kind !== "interrupted" || outcome.reason !== "supervisor-disconnect") {
             await completeBestEffort(client, instanceId, outcome.kind === "interrupted" || outcome.kind === "cleanup-error" ? "interrupted" : "completed", outcome);
@@ -103,15 +127,44 @@ export async function runLaunchGuardian(options) {
         client.close();
     }
 }
-function platformInspector(helperPath) {
+async function startExitWatcher(addon, options) {
+    const entry = fileURLToPath(new URL("./exit-watcher.js", import.meta.url));
+    const arguments_ = [entry, ...exitWatcherArguments({
+            guardianPid: process.pid,
+            ...options,
+        })];
+    if (process.platform === "win32") {
+        addon.spawnWatcher({ executable: process.execPath, arguments: arguments_ });
+        return;
+    }
+    await new Promise((resolvePromise, rejectPromise) => {
+        const watcher = spawn(process.execPath, arguments_, {
+            stdio: "inherit",
+            detached: false,
+            windowsHide: false,
+        });
+        watcher.once("error", rejectPromise);
+        watcher.once("spawn", () => {
+            watcher.off("error", rejectPromise);
+            watcher.unref();
+            resolvePromise();
+        });
+    });
+}
+function platformInspector(addon) {
     if (process.platform === "win32")
-        return new WindowsNativeProcessInspector(helperPath);
+        return new AddonProcessInspector(addon, "windows-filetime:");
     if (process.platform === "linux")
         return new LinuxNativeProcessInspector();
     if (process.platform === "darwin")
-        return new DarwinNativeProcessInspector(helperPath);
+        return new AddonProcessInspector(addon, "darwin-proc-start:");
     throw diagnosticError(`launch-instance process containment is unsupported on ${process.platform}`, "CONTAINMENT_UNSUPPORTED");
 }
+function requireAddon(addon) {
+    if (!addon)
+        throw diagnosticError("process guardian addon is unavailable", "CONTAINMENT_ARTIFACT_MISSING");
+    return addon;
+}
 function stopRequests(client, instanceId) {
     let resolveStop;
     let settled = false;