@timurproko/a1 0.2.7-dev.754 → 0.2.7-dev.772

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,27 @@
+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?: (executable: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
+    readonly run?: (executable: string, 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,77 @@
+import { readdir, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { runBoundedHostCommand } from "./bounded-host-command.js";
+import { 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 executable;
+    for (const root of options.releaseRoots) {
+        const candidate = resolveTerminalHostPath(root, {}, platform, architecture);
+        try {
+            await verify(candidate, platform, architecture);
+            executable = candidate;
+            break;
+        }
+        catch {
+            // Rationale: an older release may predate the packaged host; another retained release may still carry it.
+        }
+    }
+    if (!executable)
+        return incomplete("no verified terminal host is installed to inspect resident records");
+    try {
+        const result = await (options.run ?? runHost)(executable, ["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");
+    }
+    for (const profile of profiles) {
+        for (const record of ["server.json", "registry.json"]) {
+            try {
+                await stat(resolve(dataDir, "tabs", profile, record));
+                return true;
+            }
+            catch (error) {
+                if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+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(executable, arguments_, timeoutMs) {
+    return await runBoundedHostCommand(executable, arguments_, { maxStdoutBytes: MAX_RELEASE_HOLD_REPORT_BYTES, timeoutMs, label: "terminal host release-hold inspection" });
+}

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,14 @@
+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 tabsMax: number;
+    readonly tabsAutoName: boolean;
+    readonly maxConcurrentStarts: number;
+    readonly prewarmCount: number;
+    readonly unresponsiveRestartSeconds: number;
+    readonly stallNoticeSeconds: 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,66 @@
+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({
+    tabsMax: 10,
+    tabsAutoName: true,
+    maxConcurrentStarts: RESIDENT_TABS_MAX_CONCURRENT_STARTS,
+    prewarmCount: RESIDENT_TABS_PREWARM_COUNT,
+    unresponsiveRestartSeconds: 120,
+    stallNoticeSeconds: 300,
+});
+/** 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.tabsMax,
+            OWNED_SETTING_DECLARATIONS.tabsAutoName,
+        ],
+        migrations,
+        document,
+        currentVersion: OWNED_UI_SETTINGS_VERSION,
+    });
+    const tabsMax = document.values?.["tabsMax"] ?? settingValue(resolution, "tabsMax");
+    return {
+        tabsMax: typeof tabsMax === "number" && Number.isFinite(tabsMax) ? Math.max(1, Math.min(50, Math.trunc(tabsMax))) : DEFAULTS.tabsMax,
+        tabsAutoName: settingValue(resolution, "tabsAutoName") === true,
+        maxConcurrentStarts: RESIDENT_TABS_MAX_CONCURRENT_STARTS,
+        prewarmCount: RESIDENT_TABS_PREWARM_COUNT,
+        unresponsiveRestartSeconds: DEFAULTS.unresponsiveRestartSeconds,
+        stallNoticeSeconds: DEFAULTS.stallNoticeSeconds,
+    };
+}

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

@@ -0,0 +1,18 @@
+export declare const TERMINAL_HOST_MANIFEST_FILENAME = "terminal-host.manifest.json";
+export declare const TERMINAL_HOST_GENERATION = 1;
+export type TerminalHostArtifactCode = "TERMINAL_HOST_ARTIFACT_MISSING" | "TERMINAL_HOST_ARTIFACT_INCOMPATIBLE" | "TERMINAL_HOST_ARTIFACT_UNSUPPORTED" | "TERMINAL_HOST_ARTIFACT_TAMPERED";
+export interface VerifiedTerminalHostArtifact {
+    readonly executable: string;
+    readonly sessionLock: string;
+    readonly generation: number;
+}
+export declare class TerminalHostArtifactError extends Error {
+    readonly code: TerminalHostArtifactCode;
+    constructor(message: string, code: TerminalHostArtifactCode);
+}
+/**
+ * Verifies a release's terminal host and its session-writer lock against their manifest before
+ * anything executes or loads them: schema, generation, platform, architecture, file names, sizes,
+ * and SHA-256 digests.
+ */
+export declare function verifyTerminalHostArtifact(executable: string, platform?: NodeJS.Platform, architecture?: string, generation?: number): Promise<VerifiedTerminalHostArtifact>;

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

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+export const TERMINAL_HOST_MANIFEST_FILENAME = "terminal-host.manifest.json";
+export const TERMINAL_HOST_GENERATION = 1;
+export class TerminalHostArtifactError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "TerminalHostArtifactError";
+        this.code = code;
+    }
+}
+/**
+ * Verifies a release's terminal host and its session-writer lock against their manifest before
+ * anything executes or loads them: schema, generation, platform, architecture, file names, sizes,
+ * and SHA-256 digests.
+ */
+export async function verifyTerminalHostArtifact(executable, platform = process.platform, architecture = process.arch, generation = TERMINAL_HOST_GENERATION) {
+    const directory = dirname(executable);
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(resolve(directory, TERMINAL_HOST_MANIFEST_FILENAME), "utf8"));
+    }
+    catch (error) {
+        throw new TerminalHostArtifactError(`terminal host manifest is missing or malformed: ${errorMessage(error)}`, "TERMINAL_HOST_ARTIFACT_MISSING");
+    }
+    if (manifest.schema !== "a1-terminal-host-artifact-v1" || manifest.protocolVersion !== 1 || manifest.generation !== generation
+        || manifest.platform !== platform || manifest.architecture !== architecture
+        || manifest.artifact?.filename !== basename(executable) || typeof manifest.sessionLock?.filename !== "string"
+        || basename(manifest.sessionLock.filename) !== manifest.sessionLock.filename) {
+        throw new TerminalHostArtifactError("terminal host manifest is incompatible with this platform or generation", "TERMINAL_HOST_ARTIFACT_INCOMPATIBLE");
+    }
+    if (manifest.capability !== "supported") {
+        throw new TerminalHostArtifactError(`resident tabs are not supported on ${platform}-${architecture}`, "TERMINAL_HOST_ARTIFACT_UNSUPPORTED");
+    }
+    const sessionLock = resolve(directory, manifest.sessionLock.filename);
+    await verifyFile(executable, manifest.artifact, "terminal host");
+    await verifyFile(sessionLock, manifest.sessionLock, "session-writer lock");
+    return { executable, sessionLock, generation: manifest.generation };
+}
+async function verifyFile(path, expected, label) {
+    const [bytes, metadata] = await Promise.all([readFile(path), stat(path)]).catch((error) => {
+        throw new TerminalHostArtifactError(`${label} artifact is unavailable: ${errorMessage(error)}`, "TERMINAL_HOST_ARTIFACT_MISSING");
+    });
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (metadata.size !== expected.size || digest !== expected.sha256) {
+        throw new TerminalHostArtifactError(`${label} artifact integrity verification failed`, "TERMINAL_HOST_ARTIFACT_TAMPERED");
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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]);
+}

package/dist/foundation/session-writer-lock/index.d.ts

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+export interface NativeLock {
+    readonly bound: boolean;
+    bindCreated(path: string): void;
+    release(): void;
+}
+export interface LockBackend {
+    acquire(path: string): NativeLock;
+}
+/** Reports that a canonical session identity already has a live writer. */
+export declare class SessionWriterConflict extends Error {
+    readonly path: string;
+    readonly holderKind: string;
+    constructor(path: string, holderKind?: string);
+}
+export interface SessionWriterHandle {
+    readonly path: string;
+    readonly bound: boolean;
+    bind(createdPath?: string): void;
+    release(): void;
+}
+/** Development-only override naming a native lock addon to load first. */
+export declare const SESSION_LOCK_OVERRIDE_ENVIRONMENT = "A1_SESSION_LOCK_PATH";
+/** Security: a release that carries its own lock never loads an addon chosen by the environment or cwd. */
+export declare function nativeCandidates(moduleUrl?: string, env?: NodeJS.ProcessEnv, cwd?: string, exists?: typeof existsSync): string[];
+export declare function acquireExisting(path: string): SessionWriterHandle;
+export declare function reserveNew(parent: string, name: string): SessionWriterHandle;
+export declare function acquireSessionWriter(path: string): SessionWriterHandle;
+export declare function bind(handle: SessionWriterHandle, createdPath?: string): void;
+export declare function release(handle: SessionWriterHandle): void;
+/** Test-only backend seam; passing undefined restores native discovery. */
+export declare function setSessionWriterLockBackendForTest(value: LockBackend | undefined): void;