@timurproko/a1 0.2.6 → 0.2.7-dev.1221

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

@@ -0,0 +1,205 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { DraftCheckpointer } from "./draft-checkpoint.js";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+import { PromptJournal } from "./prompt-journal.js";
+import { SettledTurnSynchronizer, synchronizeSessionFile } from "./session-sync.js";
+export class ResidentTabRecovery {
+    #journal;
+    #draft;
+    #synchronizer;
+    #faults;
+    #onDegraded;
+    #active = [];
+    #recovered = { prompts: [], draft: null };
+    constructor(dataDir, options = {}) {
+        const faults = options.faults ?? new ResidentTabFaultInjection();
+        this.#faults = faults;
+        this.#onDegraded = options.onDegraded ?? (() => { });
+        this.#journal = new PromptJournal(join(dataDir, "journal.jsonl"), { faults });
+        this.#draft = new DraftCheckpointer(join(dataDir, "draft.json"), { faults, onDegraded: this.#onDegraded });
+        this.#synchronizer = new SettledTurnSynchronizer(this.#journal, faults);
+    }
+    get recovered() { return this.#recovered; }
+    async initialize(currentSessionFile = null, currentSessionId = null) {
+        await this.#journal.initialize();
+        await adoptHistoricalJournals(dirname(dirname(this.#journal.path)), this.#journal, currentSessionFile, currentSessionId);
+        const records = await this.#journal.read();
+        const sessionFiles = new Set(records.flatMap(record => record.type === "submitted" && record.sessionFile !== null ? [record.sessionFile] : []));
+        if (currentSessionFile !== null)
+            sessionFiles.add(currentSessionFile);
+        const sessionEntries = (await Promise.all([...sessionFiles].map(readSessionJournal))).flat();
+        const [pending, draft] = await Promise.all([
+            this.#journal.pending(sessionEntries),
+            this.#draft.restore(),
+        ]);
+        this.#recovered = { prompts: pending.map(value => value.submitted), draft: draft?.text ?? null };
+        return this.#recovered;
+    }
+    async admit(input, timeoutMs = 2_000) {
+        const fileExisted = input.sessionFile === null ? false : await stat(input.sessionFile).then(() => true, error => {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        });
+        let timer;
+        try {
+            return await Promise.race([
+                this.#journal.submit({ ...input, fileExisted }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error("resident prompt journal admission timed out")), timeoutMs);
+                    timer.unref();
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    dispatched() { this.#faults.at("journal-after-dispatch"); }
+    async correlated(submissionId, entryId) {
+        await this.#journal.correlate(submissionId, entryId);
+        this.#active.push({ id: submissionId, entryId });
+    }
+    checkpoint(text) { this.#draft.change(text); }
+    async settled(sessionFile) {
+        const active = this.#active.splice(0);
+        if (active.length === 0 || sessionFile === null)
+            return;
+        await this.#synchronizer.settleMany(sessionFile, active);
+        for (const entry of active)
+            await this.#journal.retire(entry.id);
+        await this.#journal.compactIfRetired();
+    }
+    async gracefulStop(sessionFile) {
+        await this.#draft.flush();
+        if (sessionFile !== null)
+            await synchronizeSessionFile(sessionFile);
+        await this.#synchronizer.flush();
+    }
+}
+const MAX_SESSION_RECONCILE_BYTES = 64 * 1024 * 1024;
+const MAX_ADOPTION_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+async function adoptHistoricalJournals(profileTabsRoot, target, currentSessionFile, currentSessionId) {
+    if (currentSessionFile === null && currentSessionId === null)
+        return;
+    const history = join(profileTabsRoot, "registry-history");
+    const names = await readdir(history).catch(() => []);
+    for (const name of names.filter(value => /^tabset-.+\.json$/.test(value)).sort().reverse()) {
+        const path = join(history, name);
+        const metadata = await stat(path).catch(() => null);
+        if (metadata === null || Date.now() - metadata.mtimeMs > MAX_ADOPTION_AGE_MS)
+            continue;
+        let document;
+        try {
+            document = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const tabs = typeof document === "object" && document !== null && Array.isArray(document.tabs)
+            ? document.tabs : [];
+        for (const value of tabs) {
+            if (typeof value !== "object" || value === null)
+                continue;
+            const tab = value;
+            if (typeof tab.tabId !== "string")
+                continue;
+            const fileMatches = currentSessionFile !== null && typeof tab.sessionFile === "string"
+                && resolve(tab.sessionFile) === resolve(currentSessionFile);
+            const sourcePath = join(profileTabsRoot, tab.tabId, "journal.jsonl");
+            if (resolve(sourcePath) === resolve(target.path))
+                continue;
+            if (!await stat(sourcePath).then(() => true, () => false))
+                continue;
+            const source = new PromptJournal(sourcePath);
+            await source.initialize();
+            const records = await source.read();
+            const submitted = records.filter((record) => record.type === "submitted");
+            const idMatches = currentSessionId !== null && submitted.some(record => record.sessionId === currentSessionId);
+            if (!fileMatches && !idMatches)
+                continue;
+            const pending = await source.pending(currentSessionFile === null ? [] : await readSessionJournal(currentSessionFile));
+            for (const entry of pending) {
+                await target.adopt(entry.submitted);
+                await source.retire(entry.submitted.id);
+            }
+        }
+    }
+}
+/** Reconcile only durable user/assistant ancestry; a torn final JSONL record is not authority. */
+export async function readSessionJournal(path) {
+    let text;
+    try {
+        const metadata = await stat(path);
+        if (metadata.size > MAX_SESSION_RECONCILE_BYTES)
+            throw new Error("resident session exceeds the recovery scan limit");
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const raw = [];
+    const lines = text.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.length === 0)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch (error) {
+            if (index === lines.length - 1 && !text.endsWith("\n"))
+                break;
+            throw error;
+        }
+        if (typeof value !== "object" || value === null)
+            continue;
+        const record = value;
+        const message = typeof record.message === "object" && record.message !== null
+            ? record.message
+            : null;
+        if (record.type !== "message" || typeof record.id !== "string" || message === null
+            || typeof message.role !== "string")
+            continue;
+        const content = message.content;
+        const promptText = typeof content === "string" ? content : Array.isArray(content)
+            ? content.flatMap(part => typeof part === "object" && part !== null
+                && part.type === "text"
+                && typeof part.text === "string"
+                ? [part.text] : []).join("")
+            : "";
+        raw.push({
+            id: record.id,
+            parentId: typeof record.parentId === "string" ? record.parentId : null,
+            role: message.role,
+            text: promptText,
+        });
+    }
+    const byId = new Map(raw.map(record => [record.id, record]));
+    const settled = new Set();
+    for (const record of raw) {
+        if (record.role !== "assistant")
+            continue;
+        let parent = record.parentId;
+        const visited = new Set();
+        while (parent !== null && !visited.has(parent)) {
+            visited.add(parent);
+            const ancestor = byId.get(parent);
+            if (ancestor === undefined)
+                break;
+            if (ancestor.role === "user") {
+                settled.add(ancestor.id);
+                break;
+            }
+            parent = ancestor.parentId;
+        }
+    }
+    return raw
+        .filter(record => record.role === "user")
+        .map(record => ({ entryId: record.id, text: record.text, settled: settled.has(record.id) }));
+}

package/dist/foundation/resident-tabs/release-holds.d.ts

@@ -0,0 +1,28 @@
+import { type TerminalHostCommand } from "./ensure-terminal-host.js";
+export interface ResidentReleaseHoldReport {
+    /** False when any resident record or identity could not be verified; callers then keep every release. */
+    readonly complete: boolean;
+    readonly releaseRoots: readonly string[];
+    readonly uncertain: readonly string[];
+}
+export interface ResidentReleaseHoldOptions {
+    readonly dataDir: string;
+    /** Installed release roots whose terminal host may answer, in preference order. */
+    readonly releaseRoots: readonly string[];
+    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;
+    }>;
+}
+/**
+ * Reports the releases that live resident processes run from, read-only. The verified terminal
+ * host inspects its own records, so pid reuse and identity formats are judged exactly as the
+ * server judges them. No records means nothing to hold; any doubt yields an incomplete report.
+ */
+export declare function readResidentReleaseHolds(options: ResidentReleaseHoldOptions): Promise<ResidentReleaseHoldReport>;
+/** The largest release-hold report accepted from the terminal host. */
+export declare const MAX_RELEASE_HOLD_REPORT_BYTES: number;

package/dist/foundation/resident-tabs/release-holds.js

@@ -0,0 +1,75 @@
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+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";
+const COMPLETE_EMPTY = Object.freeze({ complete: true, releaseRoots: Object.freeze([]), uncertain: Object.freeze([]) });
+/**
+ * Reports the releases that live resident processes run from, read-only. The verified terminal
+ * host inspects its own records, so pid reuse and identity formats are judged exactly as the
+ * server judges them. No records means nothing to hold; any doubt yields an incomplete report.
+ */
+export async function readResidentReleaseHolds(options) {
+    if (!await hasResidentRecords(options.dataDir))
+        return COMPLETE_EMPTY;
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    const verify = options.verify ?? verifyTerminalHostArtifact;
+    let command;
+    for (const root of options.releaseRoots) {
+        const candidate = resolveTerminalHostPath(root, {}, platform, architecture);
+        try {
+            await verify(candidate, platform, architecture);
+            command = { executable: process.execPath, entry: resolveTerminalHostEntryPath(root) };
+            break;
+        }
+        catch {
+            // Rationale: an older release may predate the packaged host; another retained release may still carry it.
+        }
+    }
+    if (!command)
+        return incomplete("no verified terminal host is installed to inspect resident records");
+    try {
+        const result = await (options.run ?? runHost)(command, ["release-holds", "--data-dir", options.dataDir], options.timeoutMs ?? 5_000);
+        const report = JSON.parse(result.stdout.trim().split(/\r?\n/u).at(-1) ?? "");
+        if (result.code !== 0 || report.schema !== "a1-resident-release-holds-v1" || typeof report.complete !== "boolean"
+            || !isStringArray(report.releaseRoots) || !isStringArray(report.uncertain)) {
+            return incomplete("terminal host returned no valid release-hold report");
+        }
+        return { complete: report.complete, releaseRoots: report.releaseRoots, uncertain: report.uncertain };
+    }
+    catch {
+        return incomplete("terminal host release-hold inspection failed");
+    }
+}
+async function hasResidentRecords(dataDir) {
+    let profiles;
+    try {
+        profiles = await readdir(resolve(dataDir, "tabs"));
+    }
+    catch (error) {
+        return !(error instanceof Error && "code" in error && error.code === "ENOENT");
+    }
+    // Invariant: native inspection, not a following stat, judges unknown or linked namespace entries.
+    return profiles.length > 0;
+}
+function incomplete(reason) {
+    return { complete: false, releaseRoots: [], uncertain: [reason] };
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === "string");
+}
+/** The largest release-hold report accepted from the terminal host. */
+export const MAX_RELEASE_HOLD_REPORT_BYTES = 1024 * 1024;
+async function runHost(command, arguments_, timeoutMs) {
+    const environment = { ...process.env };
+    delete environment[PRODUCT_IDENTITY.environment.developmentInstanceId];
+    delete environment[PRODUCT_IDENTITY.environment.terminalHostPath];
+    return await runBoundedHostCommand(command, arguments_, {
+        environment,
+        maxStdoutBytes: MAX_RELEASE_HOLD_REPORT_BYTES,
+        timeoutMs,
+        label: "terminal host release-hold inspection",
+    });
+}

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

@@ -0,0 +1,5 @@
+/** The owned screens the server opens in a utility tab; each names its tab id stem, `<route>-…`. */
+export type ResidentTabRoute = "settings" | "changelog";
+export declare const RESIDENT_TAB_ROUTES: readonly ResidentTabRoute[];
+/** The utility route whose screen is the resident tab `tabId`, or `null` for an Agent tab. */
+export declare function residentUtilityRoute(tabId: string): ResidentTabRoute | null;

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

@@ -0,0 +1,5 @@
+export const RESIDENT_TAB_ROUTES = ["settings", "changelog"];
+/** The utility route whose screen is the resident tab `tabId`, or `null` for an Agent tab. */
+export function residentUtilityRoute(tabId) {
+    return RESIDENT_TAB_ROUTES.find(route => tabId.startsWith(`${route}-`)) ?? null;
+}

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

@@ -0,0 +1,11 @@
+import type { EnsureTerminalHostResult } from "./ensure-terminal-host.js";
+export interface ResidentHostSelectionOptions {
+    readonly profileId: "a1" | "pi";
+    readonly currentLaunchContract: boolean;
+    readonly solo: boolean;
+    /** Both standard input and standard output are terminals the attach client can own. */
+    readonly interactive: boolean;
+    readonly ensureHost: () => Promise<EnsureTerminalHostResult>;
+}
+/** Invariant: comparison, solo, and superseded launches stay outside resident discovery and startup. */
+export declare function selectResidentHost(options: ResidentHostSelectionOptions): Promise<EnsureTerminalHostResult | null>;

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

@@ -0,0 +1,10 @@
+/** Invariant: comparison, solo, and superseded launches stay outside resident discovery and startup. */
+export async function selectResidentHost(options) {
+    if (options.profileId !== "a1" || options.solo || !options.currentLaunchContract)
+        return null;
+    // Platform: the attach client reads the outer terminal's size and owns its raw input, so piped
+    // or redirected launches run the direct UI, which already serves non-terminal streams.
+    if (!options.interactive)
+        return { status: "fallback", reason: "no interactive terminal" };
+    return await options.ensureHost();
+}

package/dist/foundation/resident-tabs/session-sync.d.ts

@@ -0,0 +1,14 @@
+import type { PromptJournal } from "./prompt-journal.js";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+export declare function synchronizeSessionFile(path: string, faults?: ResidentTabFaultInjection): Promise<void>;
+/** Serializes settled-turn sync and journal ordering off the input path. */
+export declare class SettledTurnSynchronizer {
+    #private;
+    constructor(journal: PromptJournal, faults?: ResidentTabFaultInjection);
+    settle(sessionFile: string, submissionId: string, entryId: string): Promise<void>;
+    settleMany(sessionFile: string, entries: readonly {
+        readonly id: string;
+        readonly entryId: string;
+    }[]): Promise<void>;
+    flush(): Promise<void>;
+}

package/dist/foundation/resident-tabs/session-sync.js

@@ -0,0 +1,37 @@
+import { open } from "node:fs/promises";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+export async function synchronizeSessionFile(path, faults = new ResidentTabFaultInjection()) {
+    const handle = await open(path, "r+");
+    try {
+        faults.at("session-before-sync");
+        await handle.sync();
+        faults.at("session-after-sync");
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Serializes settled-turn sync and journal ordering off the input path. */
+export class SettledTurnSynchronizer {
+    #journal;
+    #faults;
+    #queue = Promise.resolve();
+    constructor(journal, faults = new ResidentTabFaultInjection()) {
+        this.#journal = journal;
+        this.#faults = faults;
+    }
+    settle(sessionFile, submissionId, entryId) {
+        return this.settleMany(sessionFile, [{ id: submissionId, entryId }]);
+    }
+    settleMany(sessionFile, entries) {
+        const operation = this.#queue.then(async () => {
+            await synchronizeSessionFile(sessionFile, this.#faults);
+            this.#faults.at("journal-after-settle-sync");
+            for (const entry of entries)
+                await this.#journal.settle(entry.id, entry.entryId);
+        });
+        this.#queue = operation.catch(() => undefined);
+        return operation;
+    }
+    flush() { return this.#queue; }
+}

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

@@ -0,0 +1,12 @@
+export declare const RESIDENT_TABS_MAX_CONCURRENT_STARTS = 2;
+export declare const RESIDENT_TABS_MAX_CONCURRENT_STARTS_CAP = 8;
+export declare const RESIDENT_TABS_PREWARM_COUNT = 1;
+export declare const RESIDENT_TABS_PREWARM_CAP = 1;
+export interface ResidentTabLaunchSettings {
+    readonly tabsAutoName: boolean;
+    readonly maxConcurrentStarts: number;
+    readonly prewarmCount: number;
+    readonly unresponsiveRestartSeconds: number;
+}
+/** Read only resident-launch values before any UI or extension module is loaded. */
+export declare function readResidentTabLaunchSettings(profileDir: string, namespace?: string, legacyConfigDir?: string, profileId?: string): Promise<ResidentTabLaunchSettings>;

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

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_MIGRATIONS, OWNED_UI_SETTINGS_VERSION, normalizeOwnedUiSettingsValues, parseOwnedUiSettingsDocument, readProfileSettingsNamespace, repairProfileSettingsDocument, resolveOwnedUiSettings, settingValue, } from "../../ui/settings/index.js";
+const MAX_SETTINGS_BYTES = 256 * 1024;
+export const RESIDENT_TABS_MAX_CONCURRENT_STARTS = 2;
+export const RESIDENT_TABS_MAX_CONCURRENT_STARTS_CAP = 8;
+export const RESIDENT_TABS_PREWARM_COUNT = 1;
+export const RESIDENT_TABS_PREWARM_CAP = 1;
+const DEFAULTS = Object.freeze({
+    tabsAutoName: true,
+    maxConcurrentStarts: RESIDENT_TABS_MAX_CONCURRENT_STARTS,
+    prewarmCount: RESIDENT_TABS_PREWARM_COUNT,
+    unresponsiveRestartSeconds: 120,
+});
+/** Read only resident-launch values before any UI or extension module is loaded. */
+export async function readResidentTabLaunchSettings(profileDir, namespace = "a1", legacyConfigDir, profileId = namespace) {
+    const sharedFile = resolve(profileDir, "settings.json");
+    try {
+        repairProfileSettingsDocument(sharedFile);
+    }
+    catch {
+        // Compatibility: recovery is opportunistic; resident launch falls back when bytes stay invalid.
+    }
+    const shared = readProfileSettingsNamespace(sharedFile, namespace);
+    if (shared.status === "invalid")
+        return DEFAULTS;
+    if (shared.status === "available") {
+        const compatibility = normalizeOwnedUiSettingsValues(shared.value);
+        return compatibility.values === null
+            ? DEFAULTS
+            : resolveLaunchValues({ version: OWNED_UI_SETTINGS_VERSION, values: compatibility.values }, []);
+    }
+    const file = resolve(legacyConfigDir ?? profileDir, "settings", `${profileId}.json`);
+    try {
+        const raw = await readFile(file, "utf8");
+        if (Buffer.byteLength(raw, "utf8") > MAX_SETTINGS_BYTES)
+            return DEFAULTS;
+        const document = parseOwnedUiSettingsDocument(raw);
+        return document === null ? DEFAULTS : resolveLaunchValues(document, OWNED_UI_SETTINGS_MIGRATIONS);
+    }
+    catch {
+        return DEFAULTS;
+    }
+}
+function resolveLaunchValues(document, migrations) {
+    const resolution = resolveOwnedUiSettings({
+        declarations: [OWNED_SETTING_DECLARATIONS.tabsAutoName],
+        migrations,
+        document,
+        currentVersion: OWNED_UI_SETTINGS_VERSION,
+    });
+    return {
+        tabsAutoName: settingValue(resolution, "tabsAutoName") === true,
+        maxConcurrentStarts: RESIDENT_TABS_MAX_CONCURRENT_STARTS,
+        prewarmCount: RESIDENT_TABS_PREWARM_COUNT,
+        unresponsiveRestartSeconds: DEFAULTS.unresponsiveRestartSeconds,
+    };
+}

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

@@ -0,0 +1,14 @@
+export declare const TERMINAL_HOST_MANIFEST_FILENAME = "terminal-host.manifest.json";
+export type TerminalHostArtifactErrorCode = "TERMINAL_HOST_ARTIFACT_MISSING" | "TERMINAL_HOST_ARTIFACT_TAMPERED" | "TERMINAL_HOST_ARTIFACT_INCOMPATIBLE" | "TERMINAL_HOST_ARTIFACT_UNSUPPORTED";
+export declare class TerminalHostArtifactError extends Error {
+    readonly code: TerminalHostArtifactErrorCode;
+    readonly manifestPath: string;
+    constructor(code: TerminalHostArtifactErrorCode, manifestPath: string, message: string);
+}
+export interface VerifiedTerminalHostArtifact {
+    readonly addon: string;
+    readonly entry: string;
+    readonly generation: 1;
+}
+/** Verifies every runtime file certified by the terminal-host v2 manifest before Node loads it. */
+export declare function verifyTerminalHostArtifact(addonPath: string, platform?: NodeJS.Platform, architecture?: string): Promise<VerifiedTerminalHostArtifact>;

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

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export const TERMINAL_HOST_MANIFEST_FILENAME = "terminal-host.manifest.json";
+const SCHEMA = "a1-terminal-host-artifact-v2";
+const GENERATION = 1;
+const NODE_API = 9;
+const NOTICES_NAME = "terminal-host-THIRD-PARTY-NOTICES.txt";
+export class TerminalHostArtifactError extends Error {
+    code;
+    manifestPath;
+    constructor(code, manifestPath, message) {
+        super(message);
+        this.name = "TerminalHostArtifactError";
+        this.code = code;
+        this.manifestPath = manifestPath;
+    }
+}
+/** Verifies every runtime file certified by the terminal-host v2 manifest before Node loads it. */
+export async function verifyTerminalHostArtifact(addonPath, platform = process.platform, architecture = process.arch) {
+    const directory = dirname(addonPath);
+    const releaseRoot = resolve(directory, "../../..");
+    const manifestPath = resolve(directory, TERMINAL_HOST_MANIFEST_FILENAME);
+    let manifest;
+    try {
+        const parsed = JSON.parse(await readFile(manifestPath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new TypeError("terminal host manifest is not an object");
+        manifest = parsed;
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error && error.code === "ENOENT"
+            ? "TERMINAL_HOST_ARTIFACT_MISSING"
+            : "TERMINAL_HOST_ARTIFACT_INCOMPATIBLE";
+        throw new TerminalHostArtifactError(code, manifestPath, "terminal host manifest is missing or invalid");
+    }
+    if (manifest.capability === "unsupported") {
+        throw new TerminalHostArtifactError("TERMINAL_HOST_ARTIFACT_UNSUPPORTED", manifestPath, "terminal host is unsupported on this platform");
+    }
+    if (manifest.schema !== SCHEMA || manifest.kind !== "node-addon" || manifest.nodeApi !== NODE_API
+        || manifest.protocolVersion !== 1 || manifest.generation !== GENERATION
+        || manifest.platform !== platform || manifest.architecture !== architecture || manifest.capability !== "supported"
+        || !validRecord(manifest.artifact) || !validRecord(manifest.entry) || !validRecord(manifest.notices)
+        || manifest.artifact.filename !== `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`
+        || manifest.entry.filename !== `dist/foundation/resident-tabs/${PRODUCT_IDENTITY.artifacts.terminalHostEntry}.js`
+        || manifest.notices.filename !== NOTICES_NAME
+        || basename(addonPath) !== manifest.artifact.filename) {
+        throw new TerminalHostArtifactError("TERMINAL_HOST_ARTIFACT_INCOMPATIBLE", manifestPath, "terminal host manifest is incompatible");
+    }
+    const entry = resolve(releaseRoot, manifest.entry.filename);
+    await verifyFile(addonPath, manifest.artifact, manifestPath);
+    await verifyFile(entry, manifest.entry, manifestPath);
+    await verifyFile(resolve(directory, manifest.notices.filename), manifest.notices, manifestPath);
+    return { addon: addonPath, entry, generation: 1 };
+}
+function validRecord(value) {
+    return typeof value === "object" && value !== null
+        && typeof value.filename === "string"
+        && /^[a-f0-9]{64}$/u.test(value.sha256)
+        && Number.isSafeInteger(value.size) && value.size >= 0;
+}
+async function verifyFile(path, record, manifestPath) {
+    let bytes;
+    let metadata;
+    try {
+        [bytes, metadata] = await Promise.all([readFile(path), stat(path)]);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            throw new TerminalHostArtifactError("TERMINAL_HOST_ARTIFACT_MISSING", manifestPath, `certified terminal host file is missing: ${record.filename}`);
+        }
+        throw error;
+    }
+    if (!metadata.isFile() || bytes.byteLength !== record.size || createHash("sha256").update(bytes).digest("hex") !== record.sha256) {
+        throw new TerminalHostArtifactError("TERMINAL_HOST_ARTIFACT_TAMPERED", manifestPath, `certified terminal host file failed verification: ${record.filename}`);
+    }
+}

package/dist/foundation/resident-tabs/zip-archive.d.ts

@@ -0,0 +1,9 @@
+export interface ZipEntry {
+    readonly name: string;
+    readonly data: Buffer;
+}
+/**
+ * Encodes a small deflated zip archive. Names are forward-slash relative paths; there are no
+ * directories, extra fields, or encryption, so any standard unzip tool reads it.
+ */
+export declare function encodeZip(entries: readonly ZipEntry[], modified?: Date): Buffer;

package/dist/foundation/resident-tabs/zip-archive.js

@@ -0,0 +1,56 @@
+import { crc32, deflateRawSync } from "node:zlib";
+/**
+ * Encodes a small deflated zip archive. Names are forward-slash relative paths; there are no
+ * directories, extra fields, or encryption, so any standard unzip tool reads it.
+ */
+export function encodeZip(entries, modified = new Date()) {
+    const time = ((modified.getHours() << 11) | (modified.getMinutes() << 5) | Math.floor(modified.getSeconds() / 2)) & 0xffff;
+    const date = (((modified.getFullYear() - 1980) << 9) | ((modified.getMonth() + 1) << 5) | modified.getDate()) & 0xffff;
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const segments = entry.name.split("/");
+        if (segments.some(segment => !/^[A-Za-z0-9._-]+$/u.test(segment) || segment === "." || segment === "..")) {
+            throw new Error(`zip entry name is unsafe: ${entry.name}`);
+        }
+        const name = Buffer.from(entry.name, "utf8");
+        const compressed = deflateRawSync(entry.data);
+        const checksum = crc32(entry.data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6);
+        local.writeUInt16LE(8, 8);
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(date, 12);
+        local.writeUInt32LE(checksum, 14);
+        local.writeUInt32LE(compressed.length, 18);
+        local.writeUInt32LE(entry.data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        locals.push(local, name, compressed);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0x0800, 8);
+        central.writeUInt16LE(8, 10);
+        central.writeUInt16LE(time, 12);
+        central.writeUInt16LE(date, 14);
+        central.writeUInt32LE(checksum, 16);
+        central.writeUInt32LE(compressed.length, 20);
+        central.writeUInt32LE(entry.data.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt32LE(offset, 42);
+        centrals.push(central, name);
+        offset += local.length + name.length + compressed.length;
+    }
+    const directory = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, directory, end]);
+}