@timurproko/a1 0.2.6 → 0.2.7-dev.1222

package/dist/foundation/resident-tabs/draft-checkpoint.js

@@ -0,0 +1,145 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+/** Periodic rather than inactivity-debounced: continuous input still checkpoints every interval. */
+export class DraftCheckpointer {
+    path;
+    #intervalMs;
+    #maximumDirtyMs;
+    #faults;
+    #now;
+    #onDegraded;
+    #write;
+    #move;
+    #scheduleTimer;
+    #cancelTimer;
+    #text = "";
+    #dirtySince = null;
+    #timer = null;
+    #degradedTimer = null;
+    #writing = null;
+    #closed = false;
+    #degraded = false;
+    constructor(path, options = {}) {
+        this.path = path;
+        this.#intervalMs = options.intervalMs ?? 500;
+        this.#maximumDirtyMs = options.maximumDirtyMs ?? 1_000;
+        this.#faults = options.faults ?? new ResidentTabFaultInjection();
+        this.#now = options.now ?? Date.now;
+        this.#onDegraded = options.onDegraded ?? (() => { });
+        this.#write = options.write ?? (async (target, text) => writeFile(target, text, { encoding: "utf8", mode: 0o600, flag: "wx" }));
+        this.#move = options.move ?? rename;
+        this.#scheduleTimer = options.schedule ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+        this.#cancelTimer = options.cancel ?? (timer => clearTimeout(timer));
+    }
+    get degraded() { return this.#degraded; }
+    change(text) {
+        if (this.#closed)
+            return;
+        this.#text = text;
+        this.#dirtySince ??= this.#now();
+        this.#schedule();
+        this.#armDegradedDeadline();
+    }
+    async restore() {
+        try {
+            const value = JSON.parse(await readFile(this.path, "utf8"));
+            if (typeof value !== "object" || value === null || typeof value.text !== "string"
+                || typeof value.savedAt !== "string")
+                return null;
+            return value;
+        }
+        catch (error) {
+            if (error.code === "ENOENT" || error instanceof SyntaxError)
+                return null;
+            throw error;
+        }
+    }
+    async flush() {
+        if (this.#timer !== null) {
+            this.#cancelTimer(this.#timer);
+            this.#timer = null;
+        }
+        await this.#writing;
+        if (this.#dirtySince !== null)
+            await this.#checkpoint();
+    }
+    async close() {
+        await this.flush();
+        this.#closed = true;
+    }
+    #armDegradedDeadline() {
+        if (this.#degradedTimer !== null || this.#dirtySince === null || this.#closed)
+            return;
+        const delay = Math.max(0, this.#maximumDirtyMs - (this.#now() - this.#dirtySince));
+        this.#degradedTimer = this.#scheduleTimer(() => {
+            this.#degradedTimer = null;
+            if (this.#dirtySince !== null && this.#now() - this.#dirtySince >= this.#maximumDirtyMs) {
+                this.#setDegraded(true);
+            }
+            else if (this.#dirtySince !== null) {
+                this.#armDegradedDeadline();
+            }
+        }, delay);
+    }
+    #clearDegradedDeadline() {
+        if (this.#degradedTimer !== null)
+            this.#cancelTimer(this.#degradedTimer);
+        this.#degradedTimer = null;
+    }
+    #schedule() {
+        if (this.#timer !== null || this.#writing !== null || this.#closed)
+            return;
+        const age = this.#dirtySince === null ? 0 : this.#now() - this.#dirtySince;
+        if (age > this.#maximumDirtyMs)
+            this.#setDegraded(true);
+        this.#timer = this.#scheduleTimer(async () => {
+            this.#timer = null;
+            this.#writing = this.#checkpoint().finally(() => {
+                this.#writing = null;
+                if (this.#dirtySince !== null)
+                    this.#schedule();
+            });
+            await this.#writing.catch(() => undefined);
+        }, this.#intervalMs);
+    }
+    async #checkpoint() {
+        if (this.#dirtySince === null)
+            return;
+        const snapshot = this.#text;
+        const temporary = `${this.path}.tmp-${process.pid}-${randomUUID()}`;
+        try {
+            await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+            if (process.platform !== "win32")
+                await chmod(dirname(this.path), 0o700);
+            this.#faults.at("draft-during-temp-write");
+            await this.#write(temporary, `${JSON.stringify({ text: snapshot, savedAt: new Date(this.#now()).toISOString() })}\n`);
+            this.#faults.at("draft-before-rename");
+            await this.#move(temporary, this.path);
+            this.#faults.at("draft-after-rename");
+            if (process.platform !== "win32")
+                await chmod(this.path, 0o600);
+            if (this.#text === snapshot)
+                this.#dirtySince = null;
+            else
+                this.#dirtySince = this.#now();
+            this.#clearDegradedDeadline();
+            if (this.#dirtySince !== null)
+                this.#armDegradedDeadline();
+            this.#setDegraded(false);
+        }
+        catch (error) {
+            await unlink(temporary).catch(() => undefined);
+            this.#clearDegradedDeadline();
+            this.#setDegraded(true);
+            throw error;
+        }
+    }
+    #setDegraded(value) {
+        if (this.#degraded === value)
+            return;
+        this.#degraded = value;
+        this.#onDegraded(value);
+    }
+}

package/dist/foundation/resident-tabs/ensure-terminal-host.d.ts

@@ -0,0 +1,36 @@
+export type TerminalHostFallbackReason = "unsupported platform" | "no interactive terminal" | "terminal host not installed" | "terminal host not verified" | "host probe failed" | "incompatible generation" | "registry unreadable" | "recovery blocked" | "launch not verified" | "host startup timed out";
+export interface TerminalHostCommand {
+    readonly executable: string;
+    readonly entry: string;
+}
+export type EnsureTerminalHostResult = {
+    readonly status: "ready";
+    readonly executable: TerminalHostCommand;
+    readonly endpoint: string;
+} | {
+    readonly status: "fallback";
+    readonly reason: TerminalHostFallbackReason;
+};
+interface HostCommandResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface EnsureTerminalHostOptions {
+    readonly releaseRoot: string;
+    readonly profileRoot: string;
+    readonly dataDir: string;
+    readonly runtimeDir: string;
+    readonly environment: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly architecture?: string;
+    readonly timeoutMs?: number;
+    readonly maxConcurrentStarts?: number;
+    readonly unresponsiveRestartSeconds?: number;
+    readonly run?: (executable: string, arguments_: readonly string[], environment: NodeJS.ProcessEnv, timeoutMs: number) => Promise<HostCommandResult>;
+    readonly verify?: (addon: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
+}
+export declare function resolveTerminalHostPath(releaseRoot: string, environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, architecture?: string): string;
+export declare function resolveTerminalHostEntryPath(releaseRoot: string): string;
+export declare function ensureTerminalHost(options: EnsureTerminalHostOptions): Promise<EnsureTerminalHostResult>;
+export {};

package/dist/foundation/resident-tabs/ensure-terminal-host.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { TerminalHostArtifactError, verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
+export function resolveTerminalHostPath(releaseRoot, environment = process.env, platform = process.platform, architecture = process.arch) {
+    const override = developmentOverride(environment);
+    if (override)
+        return resolve(override);
+    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`);
+}
+export function resolveTerminalHostEntryPath(releaseRoot) {
+    return resolve(releaseRoot, "dist", "foundation", "resident-tabs", `${PRODUCT_IDENTITY.artifacts.terminalHostEntry}.js`);
+}
+/** The terminal-host override is a development aid; installed releases always run their own verified artifact. */
+function developmentOverride(environment) {
+    if (!environment[PRODUCT_IDENTITY.environment.developmentInstanceId])
+        return undefined;
+    return environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim() || undefined;
+}
+export async function ensureTerminalHost(options) {
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    if (!supported(platform, architecture))
+        return { status: "fallback", reason: "unsupported platform" };
+    const addon = resolveTerminalHostPath(options.releaseRoot, options.environment, platform, architecture);
+    const command = { executable: process.execPath, entry: resolveTerminalHostEntryPath(options.releaseRoot) };
+    if (developmentOverride(options.environment)) {
+        try {
+            await Promise.all([access(addon, constants.R_OK), access(command.entry, constants.R_OK)]);
+        }
+        catch {
+            return { status: "fallback", reason: "terminal host not installed" };
+        }
+    }
+    else {
+        try {
+            await (options.verify ?? verifyTerminalHostArtifact)(addon, platform, architecture);
+        }
+        catch (error) {
+            return { status: "fallback", reason: verificationReason(error) };
+        }
+    }
+    const run = options.run ?? runHostCommand;
+    const timeoutMs = options.timeoutMs ?? 8_000;
+    const common = ["--profile", options.profileRoot, "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir];
+    const environment = { ...options.environment };
+    const invoke = async (arguments_, commandTimeoutMs) => await run(command.executable, [command.entry, ...arguments_], environment, commandTimeoutMs);
+    try {
+        const probe = await invoke(["probe", ...common], Math.min(4_000, timeoutMs));
+        const existing = parseResult(probe.stdout);
+        if (probe.code === 0) {
+            if (existing?.generation === 1 && typeof existing.endpoint === "string") {
+                return { status: "ready", executable: command, endpoint: existing.endpoint };
+            }
+            return {
+                status: "fallback",
+                reason: typeof existing?.generation === "number" ? "incompatible generation" : "host probe failed",
+            };
+        }
+        if (probe.code === 4 || existing?.outcome === "incompatible-generation")
+            return { status: "fallback", reason: "incompatible generation" };
+        if (existing?.outcome !== "not-running" && probe.code !== 3)
+            return { status: "fallback", reason: classifiedReason(existing?.reason, "host probe failed") };
+        const maximum = Math.max(1, Math.min(8, Math.trunc(options.maxConcurrentStarts ?? 2)));
+        const unresponsiveRestartSeconds = Math.max(30, Math.min(600, Math.trunc(options.unresponsiveRestartSeconds ?? 120)));
+        const start = await invoke([
+            "server", "--detach", ...common,
+            "--max-concurrent-starts", String(maximum),
+            "--unresponsive-restart-seconds", String(unresponsiveRestartSeconds),
+        ], timeoutMs);
+        const started = parseResult(start.stdout);
+        if (start.code !== 0)
+            return { status: "fallback", reason: classifiedReason(started?.reason, "launch not verified") };
+        if (started?.verified !== true || typeof started.endpoint !== "string")
+            return { status: "fallback", reason: "launch not verified" };
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const result = await invoke(["probe", ...common], Math.min(1_000, Math.max(1, deadline - Date.now())));
+            const ready = parseResult(result.stdout);
+            if (result.code === 0) {
+                if (ready?.generation === 1 && typeof ready.endpoint === "string") {
+                    return { status: "ready", executable: command, endpoint: ready.endpoint };
+                }
+                return {
+                    status: "fallback",
+                    reason: typeof ready?.generation === "number" ? "incompatible generation" : "host probe failed",
+                };
+            }
+            if (result.code === 4 || ready?.outcome === "incompatible-generation")
+                return { status: "fallback", reason: "incompatible generation" };
+            await new Promise(resolvePromise => setTimeout(resolvePromise, 40));
+        }
+        return { status: "fallback", reason: "host startup timed out" };
+    }
+    catch (error) {
+        return { status: "fallback", reason: isTimeout(error) ? "host startup timed out" : "host probe failed" };
+    }
+}
+function supported(platform, architecture) {
+    return (platform === "win32" || platform === "linux") && architecture === "x64"
+        || platform === "darwin" && (architecture === "arm64" || architecture === "x64");
+}
+function verificationReason(error) {
+    if (!(error instanceof TerminalHostArtifactError))
+        return "terminal host not verified";
+    if (error.code === "TERMINAL_HOST_ARTIFACT_MISSING")
+        return "terminal host not installed";
+    if (error.code === "TERMINAL_HOST_ARTIFACT_UNSUPPORTED")
+        return "unsupported platform";
+    return "terminal host not verified";
+}
+function parseResult(output) {
+    const line = output.trim().split(/\r?\n/).filter(Boolean).at(-1);
+    if (!line)
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function classifiedReason(value, fallback) {
+    if (value === "registry-unreadable")
+        return "registry unreadable";
+    if (value === "blocked")
+        return "recovery blocked";
+    if (value === "incompatible-generation")
+        return "incompatible generation";
+    return fallback;
+}
+function isTimeout(error) { return error instanceof Error && "code" in error && error.code === "ETIMEDOUT"; }
+async function runHostCommand(executable, arguments_, environment, timeoutMs) {
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(executable, [...arguments_], { env: environment, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", chunk => stdout.push(Buffer.from(chunk)));
+        child.stderr.on("data", chunk => stderr.push(Buffer.from(chunk)));
+        child.once("error", rejectPromise);
+        child.once("close", code => { clearTimeout(timer); resolvePromise({ code: code ?? 1, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8") }); });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            rejectPromise(Object.assign(new Error("terminal host command timed out"), { code: "ETIMEDOUT" }));
+        }, timeoutMs);
+        timer.unref();
+    });
+}

package/dist/foundation/resident-tabs/fault-injection.d.ts

@@ -0,0 +1,8 @@
+export declare const RESIDENT_TAB_FAULT_ENVIRONMENT: readonly ["A1_TABS_FAULT_CRASH_POINT", "A1_TABS_HERMETIC_TEST"];
+export declare function residentTabFaultEnvironment(point: string, hermetic?: boolean): NodeJS.ProcessEnv;
+/** Test-only crash points are inert unless the caller explicitly marks a hermetic process. */
+export declare class ResidentTabFaultInjection {
+    #private;
+    constructor(environment?: NodeJS.ProcessEnv, crash?: (point: string) => never);
+    at(point: string): void;
+}

package/dist/foundation/resident-tabs/fault-injection.js

@@ -0,0 +1,26 @@
+const CRASH_POINT = "A1_TABS_FAULT_CRASH_POINT";
+const HERMETIC = "A1_TABS_HERMETIC_TEST";
+export const RESIDENT_TAB_FAULT_ENVIRONMENT = Object.freeze([CRASH_POINT, HERMETIC]);
+export function residentTabFaultEnvironment(point, hermetic = true) {
+    return Object.fromEntries(hermetic ? [[CRASH_POINT, point], [HERMETIC, "1"]] : [[CRASH_POINT, point]]);
+}
+/** Test-only crash points are inert unless the caller explicitly marks a hermetic process. */
+export class ResidentTabFaultInjection {
+    #point;
+    #crash;
+    constructor(environment = process.env, crash = point => {
+        process.stderr.write(`resident tab injected crash: ${point}\n`);
+        process.abort();
+    }) {
+        const point = environment[CRASH_POINT];
+        if (point !== undefined && environment[HERMETIC] !== "1") {
+            throw new Error(`${CRASH_POINT} is available only in a hermetic resident-tab test`);
+        }
+        this.#point = point;
+        this.#crash = crash;
+    }
+    at(point) {
+        if (this.#point === point)
+            this.#crash(point);
+    }
+}

package/dist/foundation/resident-tabs/fixture-control.d.ts

@@ -0,0 +1,7 @@
+export type ResidentFixtureStoppedStage = "child-render-write";
+export interface ResidentFixtureControlPort {
+    stopped(stage: ResidentFixtureStoppedStage): boolean;
+    fragmentChildWrite(data: string): readonly string[];
+}
+/** Returns the exact-artifact fixture control, or null for every ordinary resident child. */
+export declare function residentFixtureControl(environment?: NodeJS.ProcessEnv): ResidentFixtureControlPort | null;

package/dist/foundation/resident-tabs/fixture-control.js

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { residentProgressObserver } from "./progress-observation.js";
+/** Returns the exact-artifact fixture control, or null for every ordinary resident child. */
+export function residentFixtureControl(environment = process.env) {
+    const directory = environment[PRODUCT_IDENTITY.environment.residentFixtureControlDir];
+    if (environment === process.env)
+        delete process.env[PRODUCT_IDENTITY.environment.residentFixtureControlDir];
+    // Invariant: launch erases the bridge tab identity; the observer retains the observed one.
+    const tabId = residentProgressObserver(environment)?.tabId;
+    if (!directory || !tabId || !/^[a-z0-9-]{1,128}$/iu.test(tabId))
+        return null;
+    return {
+        stopped: stage => existsSync(join(directory, `${tabId}.${stage}.stop`)),
+        fragmentChildWrite: data => existsSync(join(directory, `${tabId}.child-render-fragments.enable`))
+            ? boundedFragments(data)
+            : [data],
+    };
+}
+function boundedFragments(data) {
+    const points = [...data];
+    if (points.length <= 1)
+        return [data];
+    if (points.length <= 16)
+        return points;
+    const fragments = points.slice(0, 8);
+    const middle = points.slice(8, -8);
+    const chunkSize = Math.max(1, Math.ceil(middle.length / 48));
+    for (let index = 0; index < middle.length; index += chunkSize) {
+        fragments.push(middle.slice(index, index + chunkSize).join(""));
+    }
+    fragments.push(...points.slice(-8));
+    return fragments;
+}

package/dist/foundation/resident-tabs/host-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/foundation/resident-tabs/host-entry.js

@@ -0,0 +1,17 @@
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+const filename = fileURLToPath(import.meta.url);
+const target = `${process.platform}-${process.arch}`;
+const development = process.env[PRODUCT_IDENTITY.environment.developmentInstanceId]?.trim();
+const override = development ? process.env[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim() : undefined;
+const addonPath = resolve(override || resolve(dirname(filename), "../../native", target, `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`));
+const addon = createRequire(import.meta.url)(addonPath);
+if (typeof addon.runRole !== "function")
+    throw new Error("terminal host addon exports are incompatible");
+// Invariant: runRole blocks Node's main thread, so this entry must not register JavaScript signal
+// listeners whose callbacks cannot run until the native role has already returned. Default process
+// signal handling keeps attach clients and identity-verified resident roles externally stoppable.
+process.env[PRODUCT_IDENTITY.environment.terminalHostPath] = addonPath;
+process.exitCode = addon.runRole(process.argv.slice(2), { executable: process.execPath, entry: filename, artifact: addonPath });

package/dist/foundation/resident-tabs/index.d.ts

@@ -0,0 +1,12 @@
+export { ensureTerminalHost, resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+export type { EnsureTerminalHostOptions, EnsureTerminalHostResult, TerminalHostCommand, TerminalHostFallbackReason } from "./ensure-terminal-host.js";
+export { readResidentTabLaunchSettings } from "./settings.js";
+export type { ResidentTabLaunchSettings } from "./settings.js";
+export { selectResidentHost } from "./routing.js";
+export type { ResidentHostSelectionOptions } from "./routing.js";
+export { readResidentReleaseHolds } from "./release-holds.js";
+export type { ResidentReleaseHoldReport } from "./release-holds.js";
+export { runTerminalHostMaintenance } from "./maintenance.js";
+export type { MaintenanceAction, MaintenanceHostState, MaintenanceOptions, MaintenanceReport } from "./maintenance.js";
+export { DOCTOR_MAX_BYTES, writeDoctorBundle } from "./doctor.js";
+export type { DoctorBundle, DoctorOptions } from "./doctor.js";

package/dist/foundation/resident-tabs/index.js

@@ -0,0 +1,6 @@
+export { ensureTerminalHost, resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+export { readResidentTabLaunchSettings } from "./settings.js";
+export { selectResidentHost } from "./routing.js";
+export { readResidentReleaseHolds } from "./release-holds.js";
+export { runTerminalHostMaintenance } from "./maintenance.js";
+export { DOCTOR_MAX_BYTES, writeDoctorBundle } from "./doctor.js";

package/dist/foundation/resident-tabs/maintenance.d.ts

@@ -0,0 +1,39 @@
+import { type TerminalHostCommand } from "./ensure-terminal-host.js";
+export type MaintenanceAction = "list" | "stop" | "stop-all" | "host-status" | "host-stop";
+export type MaintenanceHostState = "none" | "running" | "stopped" | "unresponsive" | "incompatible" | "refused" | "unverifiable" | "unavailable";
+/** The versioned `a1 tabs` report: `a1-tabs-maintenance-v1`, as printed by the terminal host. */
+export interface MaintenanceReport {
+    readonly schema: "a1-tabs-maintenance-v1";
+    readonly command: string;
+    readonly host: MaintenanceHostState;
+    readonly stateDir?: string;
+    readonly result?: Record<string, unknown>;
+    readonly pid?: number;
+    readonly message?: string;
+    readonly releaseRoot?: string | null;
+    readonly terminatedUnresponsive?: number;
+    /** The terminal host's exit status: 0 success, 3 refused or failed, 4 another generation. */
+    readonly exitCode: number;
+}
+export interface MaintenanceOptions {
+    readonly action: MaintenanceAction;
+    readonly tabId?: string;
+    readonly profileRoot: string;
+    readonly dataDir: string;
+    readonly runtimeDir: string;
+    /** The first root is the invoking release; other roots never substitute for it. */
+    readonly releaseRoots: readonly string[];
+    readonly environment: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly architecture?: string;
+    readonly timeoutMs?: number;
+    readonly verify?: (addon: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
+    readonly run?: (command: TerminalHostCommand, arguments_: readonly string[], timeoutMs: number) => Promise<{
+        readonly code: number;
+        readonly stdout: string;
+    }>;
+}
+/** Runs maintenance only through the invoking release; another cohort is never a retry target. */
+export declare function runTerminalHostMaintenance(options: MaintenanceOptions): Promise<MaintenanceReport>;
+/** The largest maintenance report accepted from the terminal host. */
+export declare const MAX_MAINTENANCE_REPORT_BYTES: number;

package/dist/foundation/resident-tabs/maintenance.js

@@ -0,0 +1,75 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { runBoundedHostCommand } from "./bounded-host-command.js";
+import { resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+import { verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
+/** Runs maintenance only through the invoking release; another cohort is never a retry target. */
+export async function runTerminalHostMaintenance(options) {
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    const command = await firstVerifiedHost(options, options.releaseRoots.slice(0, 1), platform, architecture);
+    if (command === undefined)
+        return unavailable(options.action, "the invoking release has no verified terminal host");
+    return await invoke(options, command);
+}
+function arguments_(options) {
+    const command = options.action === "stop" ? ["stop", options.tabId ?? ""] : [options.action];
+    return ["tabs", ...command, "--profile", options.profileRoot, "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir];
+}
+async function invoke(options, command) {
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    try {
+        const run = options.run ?? ((host, argumentsValue, limit) => runHost(host, argumentsValue, limit, options.environment));
+        const result = await run(command, arguments_(options), timeoutMs);
+        const line = result.stdout.trim().split(/\r?\n/u).at(-1) ?? "";
+        const parsed = JSON.parse(line);
+        if (parsed.schema !== "a1-tabs-maintenance-v1" || typeof parsed.host !== "string")
+            throw new Error("malformed maintenance report");
+        return { ...parsed, exitCode: result.code };
+    }
+    catch (error) {
+        return unavailable(options.action, `terminal host maintenance failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function firstVerifiedHost(options, roots, platform, architecture) {
+    const override = options.environment[PRODUCT_IDENTITY.environment.developmentInstanceId]
+        ? options.environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim()
+        : undefined;
+    if (override) {
+        const entry = roots[0] === undefined ? undefined : resolveTerminalHostEntryPath(roots[0]);
+        if (entry === undefined)
+            return undefined;
+        try {
+            await Promise.all([access(override, constants.R_OK), access(entry, constants.R_OK)]);
+            return { executable: process.execPath, entry };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    for (const root of roots) {
+        const addon = resolveTerminalHostPath(root, {}, platform, architecture);
+        try {
+            await (options.verify ?? verifyTerminalHostArtifact)(addon, platform, architecture);
+            return { executable: process.execPath, entry: resolveTerminalHostEntryPath(root) };
+        }
+        catch {
+            // Invariant: a missing or altered invoking artifact fails closed.
+        }
+    }
+    return undefined;
+}
+function unavailable(action, message) {
+    return { schema: "a1-tabs-maintenance-v1", command: action, host: "unavailable", message, exitCode: 3 };
+}
+/** The largest maintenance report accepted from the terminal host. */
+export const MAX_MAINTENANCE_REPORT_BYTES = 4 * 1024 * 1024;
+async function runHost(command, arguments_, timeoutMs, environment) {
+    return await runBoundedHostCommand(command, arguments_, {
+        environment,
+        maxStdoutBytes: MAX_MAINTENANCE_REPORT_BYTES,
+        timeoutMs,
+        label: "terminal host maintenance",
+    });
+}

package/dist/foundation/resident-tabs/progress-observation-schema.d.ts

@@ -0,0 +1,34 @@
+/** Payload-free fixture schema; type-only imports keep it outside the evaluated startup graph. */
+export type ResidentInputPhase = "receipt" | "semantic-start" | "semantic-end" | "composition-start" | "composition-end" | "write-start" | "write-end";
+export interface ProgressFields {
+    readonly eventSequence?: number;
+    readonly revision?: number;
+    readonly geometryGeneration?: number;
+    readonly bytes?: number;
+    readonly count?: number;
+    readonly eventKind?: string;
+    readonly frameId?: number;
+    readonly renderCause?: string;
+    readonly fragmentCount?: number;
+    readonly transactionKind?: "synchronized-output" | "ordinary";
+}
+export interface ProgressRecord extends ProgressFields {
+    readonly schema: "a1-resident-progress-observation-v1";
+    readonly runId: string;
+    readonly role: "child";
+    readonly stage: "engine-delivery" | "child-render-write" | "child-input-phase";
+    readonly pid: number;
+    readonly processInstance: string;
+    readonly timestampUnixUs: number;
+    readonly clockErrorUs: number;
+    readonly sequence: number;
+    readonly tabId: string;
+    readonly incarnation: number;
+    readonly lostBefore: number;
+}
+export interface ResidentProgressObserverPort {
+    readonly tabId: string;
+    engineDelivery(event: unknown): void;
+    inputPhase?(phase: ResidentInputPhase, revision: number): void;
+    childRenderWrite(bytes: number, fragments: number, transaction: "synchronized-output" | "ordinary", frameId?: number, renderCause?: string): void;
+}

package/dist/foundation/resident-tabs/progress-observation-schema.js

@@ -0,0 +1 @@
+export {};

package/dist/foundation/resident-tabs/progress-observation.d.ts

@@ -0,0 +1,4 @@
+import type { ResidentProgressObserverPort } from "./progress-observation-schema.js";
+export type { ResidentProgressObserverPort } from "./progress-observation-schema.js";
+/** Opt-in payload-free child observer; ordinary launches return null. */
+export declare function residentProgressObserver(environment?: NodeJS.ProcessEnv): ResidentProgressObserverPort | null;