@timurproko/a1 0.2.6 → 0.2.7-dev.1222

package/dist/foundation/resident-tabs/bounded-host-command.js

@@ -0,0 +1,39 @@
+import { spawn } from "node:child_process";
+/**
+ * Runs one terminal-host command whose report is small. An oversized report kills the command and
+ * reports a failed exchange; a command that outlives its deadline is killed and rejected.
+ */
+export async function runBoundedHostCommand(command, arguments_, limits) {
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(command.executable, [command.entry, ...arguments_], {
+            env: limits.environment,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const stdout = [];
+        let size = 0;
+        let overflowed = false;
+        child.stdout.on("data", chunk => {
+            size += chunk.length;
+            // Security: an oversized answer is a failed exchange, never a truncated report to parse.
+            if (size > limits.maxStdoutBytes) {
+                overflowed = true;
+                child.kill("SIGKILL");
+            }
+            else
+                stdout.push(Buffer.from(chunk));
+        });
+        child.once("error", rejectPromise);
+        child.once("close", code => {
+            clearTimeout(timer);
+            resolvePromise(overflowed
+                ? { code: code === 0 || code === null ? 1 : code, stdout: "" }
+                : { code: code ?? 1, stdout: Buffer.concat(stdout).toString("utf8") });
+        });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            rejectPromise(new Error(`${limits.label} timed out`));
+        }, limits.timeoutMs);
+        timer.unref();
+    });
+}

package/dist/foundation/resident-tabs/bridge-client.d.ts

@@ -0,0 +1,70 @@
+import { type ResidentTabRoute } from "./routes.js";
+export type ResidentTabStatus = "starting" | "working" | "needs-input" | "done-unseen" | "done" | "aborted" | "error" | "idle" | "unresponsive" | "crashed" | "restarting" | "failed";
+export { residentUtilityRoute, type ResidentTabRoute } from "./routes.js";
+export interface TabBridgeCredentials {
+    readonly tabId: string;
+    readonly token: string;
+    readonly endpoint: string;
+    readonly releaseId?: string;
+}
+export interface TabAttachment {
+    readonly clientId: string;
+    readonly controllerRevision: number;
+}
+export type TabBridgeCommand = {
+    readonly type: "visibility";
+    readonly visible: boolean;
+} | {
+    readonly type: "rename";
+    readonly name: string;
+    readonly nameSource: "default" | "user" | "auto";
+} | {
+    readonly type: "route";
+    readonly route: ResidentTabRoute;
+} | {
+    readonly type: "stop";
+    readonly deadlineMs: number;
+};
+interface BridgeTransport {
+    write(bytes: Uint8Array): boolean;
+    destroy(): void;
+    once(event: "connect" | "error" | "close", listener: (...args: unknown[]) => void): unknown;
+    on(event: "data", listener: (bytes: Buffer) => void): unknown;
+}
+export interface TabBridgeOptions {
+    readonly credentials: TabBridgeCredentials;
+    readonly pid?: number;
+    readonly startIdentity?: string;
+    readonly build?: string;
+    readonly connect?: (endpoint: string) => BridgeTransport;
+    readonly heartbeatIntervalMs?: number;
+    readonly setInterval?: (callback: () => void, milliseconds: number) => unknown;
+    readonly clearInterval?: (timer: unknown) => void;
+}
+/** Metadata-only advisory bridge. Terminal input and transcript bytes have no API here. */
+export declare class TabBridgeClient {
+    #private;
+    constructor(options: TabBridgeOptions);
+    get tabId(): string;
+    get available(): boolean;
+    captureAttachment(): TabAttachment | null;
+    onCommand(listener: (command: TabBridgeCommand) => void): () => void;
+    start(timeoutMs?: number): Promise<boolean>;
+    status(state: ResidentTabStatus, degraded?: boolean, pendingRequests?: number, queuedInput?: number): void;
+    degraded(degraded: boolean): void;
+    accent(accent: string): void;
+    session(file: string | null, name: string | null, nameSource?: "default" | "user" | "auto"): void;
+    prompt(interrupted: boolean): void;
+    /** Publishes the effective tab shortcut assignments so the host dispatches and labels the same keys. */
+    shortcuts(assignments: Readonly<Record<string, string | null>>): void;
+    requestDetach(origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
+    requestRestart(origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
+    requestClose(origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
+    consumeControllerBoundaryInput(data: string): string;
+    close(): void;
+    /**
+     * Asks the server to act for the client that controls this tab, as `origin`: leave it, restart or close the tab,
+     * or open the tab bar's Plus Menu dialog (`configure-plus`).
+     */
+    requestAction(action: "detach" | "restart" | "close" | "configure-plus", origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
+}

package/dist/foundation/resident-tabs/bridge-client.js

@@ -0,0 +1,321 @@
+import { connect } from "node:net";
+import { encodeResidentFrame, ResidentFrameDecoder } from "./protocol.js";
+import { RESIDENT_TAB_ROUTES } from "./routes.js";
+export { residentUtilityRoute } from "./routes.js";
+const RESIDENT_TAB_ROUTE_SET = new Set(RESIDENT_TAB_ROUTES);
+/** Metadata-only advisory bridge. Terminal input and transcript bytes have no API here. */
+export class TabBridgeClient {
+    #options;
+    #transport = null;
+    #connected = false;
+    #available = true;
+    #features = new Set();
+    #sequence = 0;
+    #request = 0;
+    #attachment = null;
+    #closed = false;
+    #retry = null;
+    #latestStatus = null;
+    #accent = null;
+    #latestSession = null;
+    #latestShortcuts = null;
+    #heartbeat = null;
+    #pending = new Map();
+    #startWaiter = null;
+    #commandListeners = new Set();
+    #pendingCommands = [];
+    #boundaryInputRemainder = "";
+    constructor(options) { this.#options = options; }
+    get tabId() { return this.#options.credentials.tabId; }
+    get available() { return this.#available && this.#connected; }
+    captureAttachment() { return this.#attachment === null ? null : { ...this.#attachment }; }
+    onCommand(listener) {
+        this.#commandListeners.add(listener);
+        for (const command of this.#pendingCommands.splice(0))
+            listener(command);
+        return () => this.#commandListeners.delete(listener);
+    }
+    async start(timeoutMs = 4_000) {
+        if (this.#closed || this.#transport !== null)
+            return this.available;
+        const transport = (this.#options.connect ?? (endpoint => connect(endpoint)))(this.#options.credentials.endpoint);
+        this.#transport = transport;
+        const decoder = new ResidentFrameDecoder();
+        transport.on("data", bytes => {
+            try {
+                for (const message of decoder.push(bytes))
+                    this.#receive(message);
+            }
+            catch {
+                if (this.#transport === transport)
+                    this.#fail();
+            }
+        });
+        transport.once("close", () => { if (this.#transport === transport)
+            this.#fail(); });
+        transport.once("error", () => { if (this.#transport === transport)
+            this.#fail(); });
+        return await new Promise(resolvePromise => {
+            let settled = false;
+            let timer;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                this.#startWaiter = null;
+                resolvePromise(value);
+            };
+            this.#startWaiter = finish;
+            transport.once("connect", () => {
+                this.#send("hello", {
+                    role: "bridge", generation: 1, build: this.#options.build ?? "a1", releaseId: this.#options.credentials.releaseId,
+                    features: ["bridge-status", "bridge-detach", "bridge-heartbeat", "bridge-restart", "bridge-visibility", "bridge-rename", "bridge-route", "bridge-stop", "bridge-shortcuts", "controller-boundary", "recovery-journal"],
+                    token: [...Buffer.from(this.#options.credentials.token, "base64")], tabId: this.#options.credentials.tabId,
+                    pid: this.#options.pid ?? process.pid, startIdentity: this.#options.startIdentity ?? `${process.pid}:node`,
+                }, ++this.#request);
+            });
+            transport.once("error", () => finish(false));
+            timer = setTimeout(() => { this.#fail(); finish(false); }, timeoutMs);
+            timer.unref();
+        });
+    }
+    status(state, degraded = false, pendingRequests = 0, queuedInput = 0) {
+        this.#latestStatus = { state, degraded, accent: this.#accent, pendingRequests, queuedInput };
+        const recoveryState = state === "unresponsive" || state === "crashed" || state === "restarting" || state === "failed";
+        if (recoveryState && !this.#supports("recovery-status"))
+            return;
+        this.#send("bridge.status", {
+            seq: ++this.#sequence,
+            state,
+            pendingRequests: Math.max(0, Math.trunc(pendingRequests)),
+            queuedInput: Math.max(0, Math.trunc(queuedInput)),
+            ...(this.#accent === null ? {} : { accent: this.#accent }),
+            ...(degraded && this.#supports("recovery-status") ? { degraded: true } : {}),
+        });
+    }
+    degraded(degraded) {
+        this.status(this.#latestStatus?.state ?? "idle", degraded);
+    }
+    accent(accent) {
+        this.#accent = accent;
+        if (this.#latestStatus !== null)
+            this.status(this.#latestStatus.state, this.#latestStatus.degraded, this.#latestStatus.pendingRequests, this.#latestStatus.queuedInput);
+    }
+    session(file, name, nameSource = "default") {
+        this.#latestSession = { file, name, nameSource };
+        this.#send("bridge.session", { file, name, nameSource });
+    }
+    prompt(interrupted) {
+        this.#send("bridge.prompt", { interrupted });
+    }
+    /** Publishes the effective tab shortcut assignments so the host dispatches and labels the same keys. */
+    shortcuts(assignments) {
+        this.#latestShortcuts = Object.entries(assignments).map(([action, key]) => [action, key]);
+        this.#sendShortcuts();
+    }
+    #sendShortcuts() {
+        if (this.#latestShortcuts === null || !this.#supports("bridge-shortcuts"))
+            return;
+        this.#send("bridge.shortcuts", { assignments: this.#latestShortcuts.map(([action, key]) => [action, key]) });
+    }
+    requestDetach(origin = this.captureAttachment(), timeoutMs = 1_000) {
+        return this.requestAction("detach", origin, timeoutMs);
+    }
+    requestRestart(origin = this.captureAttachment(), timeoutMs = 1_000) {
+        return this.requestAction("restart", origin, timeoutMs);
+    }
+    requestClose(origin = this.captureAttachment(), timeoutMs = 1_000) {
+        return this.requestAction("close", origin, timeoutMs);
+    }
+    consumeControllerBoundaryInput(data) {
+        const prefix = "\x1bP+a1;controller=";
+        const suffix = "\x1b\\";
+        let pending = this.#boundaryInputRemainder + data;
+        this.#boundaryInputRemainder = "";
+        let output = "";
+        while (pending.length > 0) {
+            const start = pending.indexOf(prefix);
+            if (start === -1) {
+                let retained = 0;
+                const maximum = Math.min(prefix.length - 1, pending.length);
+                // Invariant: a lone trailing Esc is a user key and passes at once; only `\x1bP` or more is withheld.
+                for (let length = maximum; length > 1; length--) {
+                    if (pending.endsWith(prefix.slice(0, length))) {
+                        retained = length;
+                        break;
+                    }
+                }
+                const split = pending.length - retained;
+                output += pending.slice(0, split);
+                this.#boundaryInputRemainder = pending.slice(split);
+                break;
+            }
+            output += pending.slice(0, start);
+            const end = pending.indexOf(suffix, start + prefix.length);
+            if (end === -1) {
+                this.#boundaryInputRemainder = pending.slice(start);
+                break;
+            }
+            const body = pending.slice(start + prefix.length, end);
+            const separator = body.indexOf(";");
+            const generation = Number(body.slice(0, separator));
+            const nonceHex = body.slice(separator + 1);
+            if (separator > 0 && Number.isSafeInteger(generation) && generation > 0 && /^[0-9a-f]{32}$/u.test(nonceHex)) {
+                this.#send("bridge.boundary", {
+                    generation,
+                    nonce: [...Buffer.from(nonceHex, "hex")],
+                });
+            }
+            else {
+                output += pending.slice(start, end + suffix.length);
+            }
+            pending = pending.slice(end + suffix.length);
+        }
+        return output;
+    }
+    close() {
+        this.#closed = true;
+        if (this.#retry !== null)
+            clearTimeout(this.#retry);
+        this.#retry = null;
+        this.#stopHeartbeat();
+        const transport = this.#transport;
+        this.#transport = null;
+        transport?.destroy();
+        this.#fail(false);
+    }
+    #emitCommand(command) {
+        if (this.#commandListeners.size === 0) {
+            if (this.#pendingCommands.length >= 16)
+                this.#pendingCommands.shift();
+            this.#pendingCommands.push(command);
+            return;
+        }
+        for (const listener of this.#commandListeners)
+            listener(command);
+    }
+    #send(type, body, requestId) {
+        if (this.#transport === null || (!this.#connected && type !== "hello"))
+            return;
+        try {
+            this.#transport.write(encodeResidentFrame({ type, ...(requestId === undefined ? {} : { requestId }), body }));
+        }
+        catch {
+            this.#fail();
+        }
+    }
+    #receive(message) {
+        if (message.type === "welcome" && message.body["generation"] === 1) {
+            const id = this.#options.credentials.releaseId;
+            if (id !== undefined && message.body["releaseId"] !== id) {
+                this.#fail(false);
+                return;
+            }
+            const advertised = message.body["features"];
+            this.#features = new Set(Array.isArray(advertised) ? advertised.filter((feature) => typeof feature === "string") : []);
+            this.#connected = true;
+            this.#available = true;
+            this.#startWaiter?.(true);
+            if (this.#supports("bridge-heartbeat"))
+                this.#startHeartbeat();
+            if (this.#latestStatus !== null)
+                this.status(this.#latestStatus.state, this.#latestStatus.degraded, this.#latestStatus.pendingRequests, this.#latestStatus.queuedInput);
+            if (this.#latestSession !== null)
+                this.#send("bridge.session", this.#latestSession);
+            this.#sendShortcuts();
+            return;
+        }
+        if (message.type === "incompatible-generation") {
+            this.#fail();
+            return;
+        }
+        if (message.type === "bridge.visibility" && typeof message.body["visible"] === "boolean") {
+            this.#emitCommand({ type: "visibility", visible: message.body["visible"] });
+            return;
+        }
+        if (message.type === "bridge.rename" && typeof message.body["name"] === "string") {
+            const source = message.body["nameSource"];
+            this.#emitCommand({ type: "rename", name: message.body["name"], nameSource: source === "auto" || source === "default" ? source : "user" });
+            return;
+        }
+        if (message.type === "bridge.route" && RESIDENT_TAB_ROUTE_SET.has(message.body["route"])) {
+            this.#emitCommand({ type: "route", route: message.body["route"] });
+            return;
+        }
+        if (message.type === "bridge.stop" && typeof message.body["deadlineMs"] === "number") {
+            this.#emitCommand({ type: "stop", deadlineMs: message.body["deadlineMs"] });
+            return;
+        }
+        if (message.type === "attachment") {
+            const clientId = message.body["clientId"];
+            const revision = message.body["controllerRevision"];
+            if (typeof clientId === "string" && typeof revision === "number")
+                this.#attachment = { clientId, controllerRevision: revision };
+            return;
+        }
+        if ((message.type === "bridge.result" || message.type === "result") && typeof message.requestId === "number") {
+            const resolvePromise = this.#pending.get(message.requestId);
+            if (resolvePromise) {
+                this.#pending.delete(message.requestId);
+                resolvePromise(message.body["accepted"] === true);
+            }
+        }
+    }
+    /**
+     * Asks the server to act for the client that controls this tab, as `origin`: leave it, restart or close the tab,
+     * or open the tab bar's Plus Menu dialog (`configure-plus`).
+     */
+    async requestAction(action, origin = this.captureAttachment(), timeoutMs = 1_000) {
+        if (!this.available || origin === null || (action === "restart" && !this.#supports("bridge-restart")))
+            return false;
+        const requestId = ++this.#request;
+        const result = new Promise(resolvePromise => this.#pending.set(requestId, resolvePromise));
+        this.#send("bridge.request", { action, clientId: origin.clientId, controllerRevision: origin.controllerRevision }, requestId);
+        const timeout = new Promise(resolvePromise => {
+            const timer = setTimeout(() => { this.#pending.delete(requestId); resolvePromise(false); }, timeoutMs);
+            timer.unref();
+        });
+        return await Promise.race([result, timeout]);
+    }
+    #startHeartbeat() {
+        if (this.#heartbeat !== null)
+            return;
+        const schedule = this.#options.setInterval ?? ((callback, milliseconds) => setInterval(callback, milliseconds));
+        this.#heartbeat = schedule(() => this.#send("bridge.heartbeat", { seq: ++this.#sequence }), this.#options.heartbeatIntervalMs ?? 5_000);
+        this.#heartbeat.unref?.();
+    }
+    #stopHeartbeat() {
+        if (this.#heartbeat === null)
+            return;
+        (this.#options.clearInterval ?? (timer => clearInterval(timer)))(this.#heartbeat);
+        this.#heartbeat = null;
+    }
+    #supports(feature) {
+        return this.#features.has("crash-recovery") || this.#features.has(feature);
+    }
+    #fail(retry = true) {
+        const transport = this.#transport;
+        this.#stopHeartbeat();
+        this.#available = false;
+        this.#connected = false;
+        this.#features.clear();
+        this.#attachment = null;
+        this.#transport = null;
+        transport?.destroy();
+        this.#startWaiter?.(false);
+        this.#startWaiter = null;
+        for (const resolvePromise of this.#pending.values())
+            resolvePromise(false);
+        this.#pending.clear();
+        if (retry && !this.#closed && this.#retry === null) {
+            this.#retry = setTimeout(() => {
+                this.#retry = null;
+                void this.start().then(connected => { if (!connected)
+                    this.#fail(); });
+            }, 250);
+            this.#retry.unref();
+        }
+    }
+}

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

@@ -0,0 +1,28 @@
+import type { MaintenanceReport } from "./maintenance.js";
+export declare const DOCTOR_MAX_BYTES: number;
+export interface DoctorOptions {
+    /** The profile's resident state directory, as reported by the terminal host. */
+    readonly stateDir: string;
+    readonly hostStatus: MaintenanceReport;
+    readonly releaseRoots: readonly string[];
+    readonly settings: {
+        readonly tabsAutoName: boolean;
+    };
+    readonly home?: string;
+    readonly platform?: NodeJS.Platform;
+    readonly architecture?: string;
+    readonly now?: Date;
+    readonly maxBytes?: number;
+}
+export interface DoctorBundle {
+    readonly path: string;
+    readonly bytes: number;
+    readonly dropped: readonly string[];
+}
+/**
+ * Writes an owner-only diagnostic bundle by allowlist: structured logs, crash records, host
+ * status, a redacted registry, the owner marker without secrets, artifact verification, platform
+ * facts, and the Tabs settings. Secrets, tokens, environment values, prompt journals, drafts,
+ * last screens, the private child-stderr sink, and terminal content are never read.
+ */
+export declare function writeDoctorBundle(options: DoctorOptions): Promise<DoctorBundle>;

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

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { homedir, release as osRelease } from "node:os";
+import { basename, dirname, resolve, sep } from "node:path";
+import { resolveTerminalHostPath } from "./ensure-terminal-host.js";
+import { TERMINAL_HOST_MANIFEST_FILENAME, verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
+import { encodeZip } from "./zip-archive.js";
+export const DOCTOR_MAX_BYTES = 25 * 1024 * 1024;
+const LOG_NAME = /^terminal-host-[a-z0-9-]+\.log(?:\.(\d{1,2}))?$/u;
+const CRASH_NAME = /^crash-[a-z0-9-]+\.json$/u;
+/**
+ * Writes an owner-only diagnostic bundle by allowlist: structured logs, crash records, host
+ * status, a redacted registry, the owner marker without secrets, artifact verification, platform
+ * facts, and the Tabs settings. Secrets, tokens, environment values, prompt journals, drafts,
+ * last screens, the private child-stderr sink, and terminal content are never read.
+ */
+export async function writeDoctorBundle(options) {
+    const home = options.home ?? homedir();
+    const redact = (value) => homeRelative(value, home);
+    const now = options.now ?? new Date();
+    const maxBytes = options.maxBytes ?? DOCTOR_MAX_BYTES;
+    const diagnostics = resolve(options.stateDir, "diagnostics");
+    const names = await readdir(diagnostics).catch(() => []);
+    const fixed = [
+        json("host-status.json", redactHostStatus(options.hostStatus, redact)),
+        json("registry.json", await redactedRegistry(resolve(options.stateDir, "registry.json"), redact)),
+        json("server-marker.json", await redactedMarker(resolve(options.stateDir, "server.json"), redact)),
+        json("artifacts.json", await artifactFacts(options.releaseRoots, options.platform ?? process.platform, options.architecture ?? process.arch, redact)),
+        json("platform.json", {
+            platform: options.platform ?? process.platform,
+            architecture: options.architecture ?? process.arch,
+            osRelease: osRelease(),
+            node: process.version,
+            detachmentMode: options.hostStatus.result?.detachmentMode ?? null,
+        }),
+        json("settings.json", { tabsAutoName: options.settings.tabsAutoName }),
+    ];
+    const crashes = [];
+    for (const name of names.filter(name => CRASH_NAME.test(name)).sort()) {
+        crashes.push({ name: `crashes/${name}`, data: await readFile(resolve(diagnostics, name)) });
+    }
+    // Rationale: when the bundle would exceed its cap, the oldest log generations go first.
+    const logs = names
+        .filter(name => LOG_NAME.test(name))
+        .map(name => ({ name, generation: Number(LOG_NAME.exec(name)?.[1] ?? 0) }))
+        .sort((left, right) => left.generation - right.generation || left.name.localeCompare(right.name));
+    const dropped = [];
+    const included = [...fixed, ...crashes];
+    let budget = maxBytes - 64 * 1024 - included.reduce((total, entry) => total + entry.data.length, 0);
+    for (const log of logs) {
+        const size = (await stat(resolve(diagnostics, log.name))).size;
+        if (size > budget) {
+            dropped.push(log.name);
+            continue;
+        }
+        budget -= size;
+        included.push({ name: `logs/${log.name}`, data: await readFile(resolve(diagnostics, log.name)) });
+    }
+    const manifest = [
+        "a1 tabs doctor bundle",
+        `created: ${now.toISOString()}`,
+        ...included.map(entry => `included: ${entry.name}`),
+        ...dropped.map(name => `dropped to stay within ${maxBytes} bytes: logs/${name}`),
+        "",
+    ].join("\n");
+    const archive = encodeZip([{ name: "manifest.txt", data: Buffer.from(manifest, "utf8") }, ...included], now);
+    const directory = resolve(options.stateDir, "doctor");
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = resolve(directory, `a1-tabs-doctor-${now.toISOString().replace(/[:.]/gu, "-")}.zip`);
+    await writeFile(path, archive, { mode: 0o600, flag: "wx" });
+    return { path, bytes: archive.length, dropped };
+}
+function json(name, value) {
+    return { name, data: Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8") };
+}
+function stableHash(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function homeRelative(value, home) {
+    const normalized = resolve(value);
+    const root = resolve(home);
+    const comparable = (path) => process.platform === "win32" ? path.toLowerCase() : path;
+    if (comparable(normalized) === comparable(root))
+        return "~";
+    return comparable(normalized).startsWith(comparable(`${root}${sep}`)) ? `~${normalized.slice(root.length).replaceAll("\\", "/")}` : normalized;
+}
+function redactHostStatus(report, redact) {
+    const result = report.result ? { ...report.result } : undefined;
+    if (result && Array.isArray(result.logs))
+        result.logs = result.logs.map(path => typeof path === "string" ? basename(path) : null);
+    if (result && typeof result.release === "string")
+        result.release = redact(result.release);
+    return {
+        host: report.host,
+        pid: report.pid ?? null,
+        exitCode: report.exitCode,
+        result: result ?? null,
+    };
+}
+async function redactedRegistry(path, redact) {
+    let document;
+    try {
+        document = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        return { readable: false, reason: error instanceof Error && "code" in error ? String(error.code) : "unparseable" };
+    }
+    const tabs = Array.isArray(document.tabs) ? document.tabs : [];
+    const text = (value) => typeof value === "string" ? value : null;
+    return {
+        readable: true,
+        registryRevision: document.registryRevision ?? null,
+        epoch: document.epoch ?? null,
+        tabs: tabs.map(tab => {
+            const sessionFile = text(tab.sessionFile);
+            return {
+                tabId: text(tab.tabId),
+                // Security: names can be generated from prompts, so only a stable hash is kept.
+                nameHash: text(tab.displayName) === null ? null : stableHash(text(tab.displayName)),
+                nameSource: text(tab.nameSource),
+                order: tab.order ?? null,
+                cwd: text(tab.cwd) === null ? null : redact(text(tab.cwd)),
+                sessionDirectory: sessionFile === null ? null : redact(dirname(sessionFile)),
+                sessionFileHash: sessionFile === null ? null : stableHash(basename(sessionFile)),
+                desired: text(tab.desired),
+                lifecycle: text(tab.lifecycle),
+                incarnation: tab.incarnation ?? null,
+                holderPid: tab.holderPid ?? null,
+                childPid: tab.childPid ?? null,
+                release: text(tab.release) === null ? null : redact(text(tab.release)),
+                lastExit: text(tab.lastExit),
+                restarts: tab.restarts ?? null,
+            };
+        }),
+    };
+}
+async function redactedMarker(path, redact) {
+    try {
+        const marker = JSON.parse(await readFile(path, "utf8"));
+        return {
+            present: true,
+            pid: marker.pid ?? null,
+            generation: marker.generation ?? null,
+            verified: marker.verified ?? null,
+            detachmentMode: marker.detachmentMode ?? null,
+            releaseRoot: typeof marker.releaseRoot === "string" ? redact(marker.releaseRoot) : null,
+        };
+    }
+    catch {
+        return { present: false };
+    }
+}
+async function artifactFacts(roots, platform, architecture, redact) {
+    const facts = [];
+    for (const root of roots) {
+        const addon = resolveTerminalHostPath(root, {}, platform, architecture);
+        const manifest = await readFile(resolve(dirname(addon), TERMINAL_HOST_MANIFEST_FILENAME), "utf8")
+            .then(text => JSON.parse(text))
+            .catch(() => null);
+        const verification = await verifyTerminalHostArtifact(addon, platform, architecture)
+            .then(() => "verified")
+            .catch((error) => error instanceof Error && "code" in error ? String(error.code) : "failed");
+        facts.push({ releaseRoot: redact(root), verification, manifest });
+    }
+    return facts;
+}

package/dist/foundation/resident-tabs/draft-checkpoint.d.ts

@@ -0,0 +1,27 @@
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+export interface DraftCheckpointState {
+    readonly text: string;
+    readonly savedAt: string;
+}
+export interface DraftCheckpointOptions {
+    readonly intervalMs?: number;
+    readonly maximumDirtyMs?: number;
+    readonly faults?: ResidentTabFaultInjection;
+    readonly now?: () => number;
+    readonly onDegraded?: (degraded: boolean) => void;
+    readonly write?: (path: string, text: string) => Promise<void>;
+    readonly move?: (from: string, to: string) => Promise<void>;
+    readonly schedule?: (callback: () => void | Promise<void>, delayMs: number) => unknown;
+    readonly cancel?: (timer: unknown) => void;
+}
+/** Periodic rather than inactivity-debounced: continuous input still checkpoints every interval. */
+export declare class DraftCheckpointer {
+    #private;
+    readonly path: string;
+    constructor(path: string, options?: DraftCheckpointOptions);
+    get degraded(): boolean;
+    change(text: string): void;
+    restore(): Promise<DraftCheckpointState | null>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}