@timurproko/a1 0.2.6 → 0.2.7-dev.746

package/dist/foundation/release/bootstrap.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
+import { CLEAR_EXIT_INTERVAL_MS, restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { connect } from "node:net";
 import { resolve } from "node:path";
@@ -15,9 +15,10 @@ import { selectUpdateLaunchRelease } from "./update-launch.js";
 import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
-import { PRODUCT_TEXT } from "../../product-identity.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { markStartupPhase } from "../startup/index.js";
-import { launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
+import { isCurrentLaunchContract, launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
+import { ensureTerminalHost, readResidentTabsSetting, selectResidentHost } from "../resident-tabs/index.js";
 const RELEASE_RESELECTION_MESSAGE = "a1-release-reselection";
 export async function runBootstrap(options) {
     return await runBootstrapAttempt(options, 1);
@@ -34,7 +35,31 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     const paths = resolveProductPaths(environment);
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const launchSelected = async (release) => {
-        const result = await launchUi(release, environment, sessionArgs);
+        let residentContext = {};
+        const resident = await selectResidentHost({
+            profileId: launchProfileId,
+            hasSessionSelection: sessionArgs.length > 0,
+            currentLaunchContract: isCurrentLaunchContract(release),
+            readSetting: () => (options.readResidentTabs ?? readResidentTabsSetting)(paths.configDir, launchProfileId),
+            ensureHost: () => (options.ensureTerminalHost ?? ensureTerminalHost)({
+                releaseRoot: release.releaseRoot,
+                profileRoot: environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
+                dataDir: paths.dataDir,
+                runtimeDir: paths.runtimeDir,
+                environment,
+            }),
+        });
+        if (resident !== null) {
+            residentContext = resident.status === "ready" ? {
+                residentRootExecutable: resident.executable,
+                residentRootArguments: JSON.stringify([
+                    "attach", "--endpoint", resident.endpoint, "--cwd", process.cwd(), "--clear-exit-ms", String(CLEAR_EXIT_INTERVAL_MS),
+                    "--profile", environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
+                    "--data-dir", paths.dataDir, "--release-root", release.releaseRoot, "--node-executable", process.execPath,
+                ]),
+            } : { residentFallback: resident.reason };
+        }
+        const result = await launchUi(release, environment, sessionArgs, residentContext);
         if (!result.releaseSuperseded)
             return result.code;
         if (retriesRemaining > 0)
@@ -327,13 +352,15 @@ export async function startSupervisor(release, environment) {
     child.unref();
     return { ...attempt, childOutcome };
 }
-async function launchUi(release, environment, sessionArgs) {
+async function launchUi(release, environment, sessionArgs, residentContext = {}) {
     await markStartupPhase(environment, "bootstrap-selected");
     const entry = await resolveReleaseEntryPoint(release, "bin/guardian.js");
     return await new Promise((resolvePromise, rejectPromise) => {
         let releaseSuperseded = false;
+        const releaseEnv = releaseEnvironment(environment, release, readLaunchContext(environment, "profile").launchProfile);
+        const launchEnvironment = Object.keys(residentContext).length === 0 ? releaseEnv : withLaunchContext(releaseEnv, { ...readLaunchContext(releaseEnv), ...residentContext }, process.platform, launchContractTarget(release));
         const child = spawn(process.execPath, [entry, ...sessionArgs], {
-            env: releaseEnvironment(environment, release, readLaunchContext(environment, "profile").launchProfile),
+            env: launchEnvironment,
             stdio: ["inherit", "inherit", "inherit", "ipc"],
             windowsHide: false,
         });

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

@@ -0,0 +1,36 @@
+export type ResidentTabStatus = "starting" | "working" | "idle";
+export interface TabBridgeCredentials {
+    readonly tabId: string;
+    readonly token: string;
+    readonly endpoint: string;
+}
+export interface TabAttachment {
+    readonly clientId: string;
+    readonly controllerRevision: 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;
+}
+/** Metadata-only advisory bridge. Terminal input and transcript bytes have no API here. */
+export declare class TabBridgeClient {
+    #private;
+    constructor(options: TabBridgeOptions);
+    get available(): boolean;
+    captureAttachment(): TabAttachment | null;
+    start(timeoutMs?: number): Promise<boolean>;
+    status(state: ResidentTabStatus): void;
+    session(file: string | null, name: string | null): void;
+    requestDetach(origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
+    close(): void;
+}
+export {};

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

@@ -0,0 +1,157 @@
+import { connect } from "node:net";
+import { encodeResidentFrame, ResidentFrameDecoder } from "./protocol.js";
+/** Metadata-only advisory bridge. Terminal input and transcript bytes have no API here. */
+export class TabBridgeClient {
+    #options;
+    #transport = null;
+    #connected = false;
+    #available = true;
+    #sequence = 0;
+    #request = 0;
+    #attachment = null;
+    #closed = false;
+    #retry = null;
+    #latestStatus = null;
+    #latestSession = null;
+    #pending = new Map();
+    #startWaiter = null;
+    constructor(options) { this.#options = options; }
+    get available() { return this.#available && this.#connected; }
+    captureAttachment() { return this.#attachment === null ? null : { ...this.#attachment }; }
+    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", features: ["bridge-status", "bridge-detach"],
+                    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) {
+        this.#latestStatus = state;
+        this.#send("bridge.status", { seq: ++this.#sequence, state });
+    }
+    session(file, name) {
+        this.#latestSession = { file, name };
+        this.#send("bridge.session", { file, name });
+    }
+    async requestDetach(origin = this.captureAttachment(), timeoutMs = 1_000) {
+        if (!this.available || origin === null)
+            return false;
+        const requestId = ++this.#request;
+        const result = new Promise(resolvePromise => this.#pending.set(requestId, resolvePromise));
+        this.#send("bridge.request", { action: "detach", 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]);
+    }
+    close() {
+        this.#closed = true;
+        if (this.#retry !== null)
+            clearTimeout(this.#retry);
+        this.#retry = null;
+        const transport = this.#transport;
+        this.#transport = null;
+        transport?.destroy();
+        this.#fail(false);
+    }
+    #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) {
+            this.#connected = true;
+            this.#available = true;
+            this.#startWaiter?.(true);
+            if (this.#latestStatus !== null)
+                this.#send("bridge.status", { seq: ++this.#sequence, state: this.#latestStatus });
+            if (this.#latestSession !== null)
+                this.#send("bridge.session", this.#latestSession);
+            return;
+        }
+        if (message.type === "incompatible-generation") {
+            this.#fail();
+            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);
+            }
+        }
+    }
+    #fail(retry = true) {
+        const transport = this.#transport;
+        this.#available = false;
+        this.#connected = false;
+        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/ensure-terminal-host.d.ts

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

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

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export function resolveTerminalHostPath(releaseRoot, environment = process.env, platform = process.platform, architecture = process.arch) {
+    const override = environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim();
+    if (override)
+        return resolve(override);
+    const executable = platform === "win32" ? "a1-terminal-host.exe" : "a1-terminal-host";
+    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, executable);
+}
+export async function ensureTerminalHost(options) {
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    if (!supported(platform, architecture))
+        return { status: "fallback", reason: "unsupported platform" };
+    const executable = resolveTerminalHostPath(options.releaseRoot, options.environment, platform, architecture);
+    try {
+        await access(executable, constants.R_OK | (platform === "win32" ? 0 : constants.X_OK));
+    }
+    catch {
+        return { status: "fallback", reason: "terminal host not installed" };
+    }
+    const run = options.run ?? runHostCommand;
+    const timeoutMs = options.timeoutMs ?? 8_000;
+    const common = ["--profile", options.profileRoot, "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir];
+    const environment = { ...options.environment };
+    try {
+        const probe = await run(executable, ["probe", ...common], environment, Math.min(4_000, timeoutMs));
+        const existing = parseResult(probe.stdout);
+        if (probe.code === 0) {
+            if (existing?.generation === 1 && typeof existing.endpoint === "string") {
+                return { status: "ready", executable, endpoint: existing.endpoint };
+            }
+            return {
+                status: "fallback",
+                reason: typeof existing?.generation === "number" ? "incompatible generation" : "host probe failed",
+            };
+        }
+        if (probe.code === 4 || existing?.outcome === "incompatible-generation")
+            return { status: "fallback", reason: "incompatible generation" };
+        if (existing?.outcome !== "not-running" && probe.code !== 3)
+            return { status: "fallback", reason: classifiedReason(existing?.reason, "host probe failed") };
+        const start = await run(executable, ["server", "--detach", ...common], environment, timeoutMs);
+        const started = parseResult(start.stdout);
+        if (start.code !== 0)
+            return { status: "fallback", reason: classifiedReason(started?.reason, "launch not verified") };
+        if (started?.verified !== true || typeof started.endpoint !== "string")
+            return { status: "fallback", reason: "launch not verified" };
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const result = await run(executable, ["probe", ...common], environment, Math.min(1_000, Math.max(1, deadline - Date.now())));
+            const ready = parseResult(result.stdout);
+            if (result.code === 0) {
+                if (ready?.generation === 1 && typeof ready.endpoint === "string") {
+                    return { status: "ready", executable, endpoint: ready.endpoint };
+                }
+                return {
+                    status: "fallback",
+                    reason: typeof ready?.generation === "number" ? "incompatible generation" : "host probe failed",
+                };
+            }
+            if (result.code === 4 || ready?.outcome === "incompatible-generation")
+                return { status: "fallback", reason: "incompatible generation" };
+            await new Promise(resolvePromise => setTimeout(resolvePromise, 40));
+        }
+        return { status: "fallback", reason: "host startup timed out" };
+    }
+    catch (error) {
+        return { status: "fallback", reason: isTimeout(error) ? "host startup timed out" : "host probe failed" };
+    }
+}
+function supported(platform, architecture) {
+    return (platform === "win32" || platform === "linux") && architecture === "x64"
+        || platform === "darwin" && architecture === "arm64";
+}
+function parseResult(output) {
+    const line = output.trim().split(/\r?\n/).filter(Boolean).at(-1);
+    if (!line)
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function classifiedReason(value, fallback) {
+    if (value === "registry-unreadable")
+        return "registry unreadable";
+    if (value === "blocked")
+        return "recovery blocked";
+    if (value === "incompatible-generation")
+        return "incompatible generation";
+    return fallback;
+}
+function isTimeout(error) { return error instanceof Error && "code" in error && error.code === "ETIMEDOUT"; }
+async function runHostCommand(executable, arguments_, environment, timeoutMs) {
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(executable, [...arguments_], { env: environment, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", chunk => stdout.push(Buffer.from(chunk)));
+        child.stderr.on("data", chunk => stderr.push(Buffer.from(chunk)));
+        child.once("error", rejectPromise);
+        child.once("close", code => { clearTimeout(timer); resolvePromise({ code: code ?? 1, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8") }); });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            rejectPromise(Object.assign(new Error("terminal host command timed out"), { code: "ETIMEDOUT" }));
+        }, timeoutMs);
+        timer.unref();
+    });
+}

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

@@ -0,0 +1,5 @@
+export { ensureTerminalHost, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+export type { EnsureTerminalHostOptions, EnsureTerminalHostResult, TerminalHostFallbackReason } from "./ensure-terminal-host.js";
+export { readResidentTabsSetting } from "./settings.js";
+export { selectResidentHost } from "./routing.js";
+export type { ResidentHostSelectionOptions } from "./routing.js";

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

@@ -0,0 +1,3 @@
+export { ensureTerminalHost, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+export { readResidentTabsSetting } from "./settings.js";
+export { selectResidentHost } from "./routing.js";

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

@@ -0,0 +1,12 @@
+export interface ResidentEnvelope<T = Readonly<Record<string, unknown>>> {
+    readonly type: string;
+    readonly requestId?: number;
+    readonly body: T;
+}
+/** Generation-1 MessagePack named-map codec. It intentionally supports only bridge-safe values. */
+export declare function encodeResidentFrame(value: ResidentEnvelope): Buffer;
+export declare function decodeResidentPayload(payload: Uint8Array): ResidentEnvelope;
+export declare class ResidentFrameDecoder {
+    #private;
+    push(chunk: Uint8Array): readonly ResidentEnvelope[];
+}

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

@@ -0,0 +1,195 @@
+const MAX_FRAME_BYTES = 2 * 1024 * 1024;
+const MAX_DEPTH = 64;
+/** Generation-1 MessagePack named-map codec. It intentionally supports only bridge-safe values. */
+export function encodeResidentFrame(value) {
+    const payload = Buffer.from(encodeValue(value, 0));
+    if (payload.length > MAX_FRAME_BYTES)
+        throw new Error("resident frame exceeds 2 MiB");
+    const frame = Buffer.allocUnsafe(payload.length + 4);
+    frame.writeUInt32LE(payload.length, 0);
+    payload.copy(frame, 4);
+    return frame;
+}
+export function decodeResidentPayload(payload) {
+    if (payload.byteLength > MAX_FRAME_BYTES)
+        throw new Error("resident frame exceeds 2 MiB");
+    const state = { bytes: payload, offset: 0 };
+    const value = decodeValue(state, 0);
+    if (state.offset !== payload.byteLength || !isRecord(value) || typeof value.type !== "string" || !isRecord(value.body)) {
+        throw new Error("invalid resident envelope");
+    }
+    return value;
+}
+export class ResidentFrameDecoder {
+    #buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        const messages = [];
+        while (this.#buffer.length >= 4) {
+            const length = this.#buffer.readUInt32LE(0);
+            if (length > MAX_FRAME_BYTES)
+                throw new Error("resident frame exceeds 2 MiB");
+            if (this.#buffer.length < length + 4)
+                break;
+            messages.push(decodeResidentPayload(this.#buffer.subarray(4, length + 4)));
+            this.#buffer = this.#buffer.subarray(length + 4);
+        }
+        return messages;
+    }
+}
+function encodeValue(value, depth) {
+    if (depth > MAX_DEPTH)
+        throw new Error("resident value exceeds nesting limit");
+    if (value === null)
+        return [0xc0];
+    if (value === false)
+        return [0xc2];
+    if (value === true)
+        return [0xc3];
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return encodeInteger(value);
+    if (typeof value === "string") {
+        const bytes = [...Buffer.from(value, "utf8")];
+        if (bytes.length < 32)
+            return [0xa0 | bytes.length, ...bytes];
+        if (bytes.length <= 0xff)
+            return [0xd9, bytes.length, ...bytes];
+        if (bytes.length <= 0xffff)
+            return [0xda, bytes.length >>> 8, bytes.length & 0xff, ...bytes];
+        return [0xdb, ...u32(bytes.length), ...bytes];
+    }
+    if (value instanceof Uint8Array) {
+        const bytes = [...value];
+        if (bytes.length <= 0xff)
+            return [0xc4, bytes.length, ...bytes];
+        if (bytes.length <= 0xffff)
+            return [0xc5, bytes.length >>> 8, bytes.length & 0xff, ...bytes];
+        return [0xc6, ...u32(bytes.length), ...bytes];
+    }
+    if (Array.isArray(value)) {
+        const head = value.length < 16 ? [0x90 | value.length] : value.length <= 0xffff ? [0xdc, value.length >>> 8, value.length & 0xff] : [0xdd, ...u32(value.length)];
+        return [...head, ...value.flatMap(entry => encodeValue(entry, depth + 1))];
+    }
+    if (isRecord(value)) {
+        const entries = Object.entries(value).filter(([, child]) => child !== undefined);
+        const head = entries.length < 16 ? [0x80 | entries.length] : entries.length <= 0xffff ? [0xde, entries.length >>> 8, entries.length & 0xff] : [0xdf, ...u32(entries.length)];
+        return [...head, ...entries.flatMap(([key, child]) => [...encodeValue(key, depth + 1), ...encodeValue(child, depth + 1)])];
+    }
+    throw new Error(`unsupported resident value: ${typeof value}`);
+}
+function encodeInteger(value) {
+    if (value >= 0 && value <= 0x7f)
+        return [value];
+    if (value < 0 && value >= -32)
+        return [0x100 + value];
+    if (value >= 0 && value <= 0xff)
+        return [0xcc, value];
+    if (value >= 0 && value <= 0xffff)
+        return [0xcd, value >>> 8, value & 0xff];
+    if (value >= -0x80 && value < 0)
+        return [0xd0, value & 0xff];
+    if (value >= -0x8000 && value < 0)
+        return [0xd1, (value >>> 8) & 0xff, value & 0xff];
+    if (value >= 0 && value <= 0xffffffff)
+        return [0xce, ...u32(value)];
+    return [0xd3, ...i64(value)];
+}
+function decodeValue(state, depth) {
+    if (depth > MAX_DEPTH)
+        throw new Error("resident value exceeds nesting limit");
+    const marker = byte(state);
+    if (marker <= 0x7f)
+        return marker;
+    if (marker >= 0xe0)
+        return marker - 0x100;
+    if ((marker & 0xe0) === 0xa0)
+        return string(state, marker & 0x1f);
+    if ((marker & 0xf0) === 0x90)
+        return array(state, marker & 0x0f, depth);
+    if ((marker & 0xf0) === 0x80)
+        return map(state, marker & 0x0f, depth);
+    switch (marker) {
+        case 0xc0: return null;
+        case 0xc2: return false;
+        case 0xc3: return true;
+        case 0xc4: return binary(state, uint(state, 1));
+        case 0xc5: return binary(state, uint(state, 2));
+        case 0xc6: return binary(state, uint(state, 4));
+        case 0xcc: return uint(state, 1);
+        case 0xcd: return uint(state, 2);
+        case 0xce: return uint(state, 4);
+        case 0xcf: return safeInteger(state, false);
+        case 0xd0: return signed(state, 1);
+        case 0xd1: return signed(state, 2);
+        case 0xd2: return signed(state, 4);
+        case 0xd3: return safeInteger(state, true);
+        case 0xd9: return string(state, uint(state, 1));
+        case 0xda: return string(state, uint(state, 2));
+        case 0xdb: return string(state, uint(state, 4));
+        case 0xdc: return array(state, uint(state, 2), depth);
+        case 0xdd: return array(state, uint(state, 4), depth);
+        case 0xde: return map(state, uint(state, 2), depth);
+        case 0xdf: return map(state, uint(state, 4), depth);
+        default: throw new Error(`unsupported resident MessagePack marker 0x${marker.toString(16)}`);
+    }
+}
+function byte(state) {
+    const value = state.bytes[state.offset++];
+    if (value === undefined)
+        throw new Error("incomplete resident value");
+    return value;
+}
+function uint(state, width) {
+    let value = 0;
+    for (let index = 0; index < width; index++)
+        value = value * 256 + byte(state);
+    return value;
+}
+function signed(state, width) {
+    const value = uint(state, width);
+    return value >= 2 ** (width * 8 - 1) ? value - 2 ** (width * 8) : value;
+}
+function safeInteger(state, signedValue) {
+    const high = uint(state, 4);
+    const low = uint(state, 4);
+    const value = high * 0x1_0000_0000 + low;
+    const resolved = signedValue && high >= 0x80000000 ? value - 0x1_0000_0000_0000_0000 : value;
+    if (!Number.isSafeInteger(resolved))
+        throw new Error("resident integer exceeds JavaScript safe range");
+    return resolved;
+}
+function string(state, length) {
+    return Buffer.from(binary(state, length)).toString("utf8");
+}
+function binary(state, length) {
+    const end = state.offset + length;
+    if (end > state.bytes.byteLength)
+        throw new Error("incomplete resident value");
+    const value = state.bytes.slice(state.offset, end);
+    state.offset = end;
+    return value;
+}
+function array(state, length, depth) {
+    if (length > 65_536)
+        throw new Error("resident collection exceeds limit");
+    return Array.from({ length }, () => decodeValue(state, depth + 1));
+}
+function map(state, length, depth) {
+    if (length > 65_536)
+        throw new Error("resident collection exceeds limit");
+    const value = {};
+    for (let index = 0; index < length; index++) {
+        const key = decodeValue(state, depth + 1);
+        if (typeof key !== "string" || Object.hasOwn(value, key))
+            throw new Error("invalid resident map key");
+        value[key] = decodeValue(state, depth + 1);
+    }
+    return value;
+}
+function u32(value) { return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff]; }
+function i64(value) {
+    const integer = BigInt(value);
+    const encoded = integer < 0 ? (1n << 64n) + integer : integer;
+    return Array.from({ length: 8 }, (_, index) => Number((encoded >> BigInt((7 - index) * 8)) & 0xffn));
+}
+function isRecord(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }

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

@@ -0,0 +1,10 @@
+import type { EnsureTerminalHostResult } from "./ensure-terminal-host.js";
+export interface ResidentHostSelectionOptions {
+    readonly profileId: "a1" | "pi";
+    readonly hasSessionSelection: boolean;
+    readonly currentLaunchContract: boolean;
+    readonly readSetting: () => Promise<boolean>;
+    readonly ensureHost: () => Promise<EnsureTerminalHostResult>;
+}
+/** Invariant: every non-bare or default-off launch stays outside resident discovery and startup. */
+export declare function selectResidentHost(options: ResidentHostSelectionOptions): Promise<EnsureTerminalHostResult | null>;

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

@@ -0,0 +1,8 @@
+/** Invariant: every non-bare or default-off launch stays outside resident discovery and startup. */
+export async function selectResidentHost(options) {
+    if (options.profileId !== "a1" || options.hasSessionSelection || !options.currentLaunchContract)
+        return null;
+    if (!await options.readSetting())
+        return null;
+    return await options.ensureHost();
+}

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

@@ -0,0 +1,2 @@
+/** Read only the routing flag before any UI or extension module is loaded. */
+export declare function readResidentTabsSetting(configDir: string, profileId?: string): Promise<boolean>;