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

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

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

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

@@ -1,4 +1,4 @@
-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 TerminalHostFallbackReason = "unsupported platform" | "no interactive terminal" | "terminal host not installed" | "terminal host not verified" | "host probe failed" | "incompatible generation" | "registry unreadable" | "recovery blocked" | "launch not verified" | "host startup timed out";
 export type EnsureTerminalHostResult = {
     readonly status: "ready";
     readonly executable: string;
@@ -24,6 +24,7 @@ export interface EnsureTerminalHostOptions {
     readonly maxConcurrentStarts?: number;
     readonly unresponsiveRestartSeconds?: number;
     readonly run?: (executable: string, arguments_: readonly string[], environment: NodeJS.ProcessEnv, timeoutMs: number) => Promise<HostCommandResult>;
+    readonly verify?: (executable: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
 }
 export declare function resolveTerminalHostPath(releaseRoot: string, environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, architecture?: string): string;
 export declare function ensureTerminalHost(options: EnsureTerminalHostOptions): Promise<EnsureTerminalHostResult>;

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

@@ -3,24 +3,41 @@ import { access } from "node:fs/promises";
 import { constants } from "node:fs";
 import { resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { TerminalHostArtifactError, verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
 export function resolveTerminalHostPath(releaseRoot, environment = process.env, platform = process.platform, architecture = process.arch) {
-    const override = environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim();
+    const override = developmentOverride(environment);
     if (override)
         return resolve(override);
-    const executable = platform === "win32" ? "a1-terminal-host.exe" : "a1-terminal-host";
+    const executable = platform === "win32" ? `${PRODUCT_IDENTITY.artifacts.nativeExecutable}.exe` : PRODUCT_IDENTITY.artifacts.nativeExecutable;
     return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, executable);
 }
+/** The terminal-host override is a development aid; installed releases always run their own verified artifact. */
+function developmentOverride(environment) {
+    if (!environment[PRODUCT_IDENTITY.environment.developmentInstanceId])
+        return undefined;
+    return environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim() || undefined;
+}
 export async function ensureTerminalHost(options) {
     const platform = options.platform ?? process.platform;
     const architecture = options.architecture ?? process.arch;
     if (!supported(platform, architecture))
         return { status: "fallback", reason: "unsupported platform" };
     const executable = resolveTerminalHostPath(options.releaseRoot, options.environment, platform, architecture);
-    try {
-        await access(executable, constants.R_OK | (platform === "win32" ? 0 : constants.X_OK));
+    if (developmentOverride(options.environment)) {
+        try {
+            await access(executable, constants.R_OK | (platform === "win32" ? 0 : constants.X_OK));
+        }
+        catch {
+            return { status: "fallback", reason: "terminal host not installed" };
+        }
     }
-    catch {
-        return { status: "fallback", reason: "terminal host not installed" };
+    else {
+        try {
+            await (options.verify ?? verifyTerminalHostArtifact)(executable, platform, architecture);
+        }
+        catch (error) {
+            return { status: "fallback", reason: verificationReason(error) };
+        }
     }
     const run = options.run ?? runHostCommand;
     const timeoutMs = options.timeoutMs ?? 8_000;
@@ -79,7 +96,16 @@ export async function ensureTerminalHost(options) {
 }
 function supported(platform, architecture) {
     return (platform === "win32" || platform === "linux") && architecture === "x64"
-        || platform === "darwin" && architecture === "arm64";
+        || platform === "darwin" && (architecture === "arm64" || architecture === "x64");
+}
+function verificationReason(error) {
+    if (!(error instanceof TerminalHostArtifactError))
+        return "terminal host not verified";
+    if (error.code === "TERMINAL_HOST_ARTIFACT_MISSING")
+        return "terminal host not installed";
+    if (error.code === "TERMINAL_HOST_ARTIFACT_UNSUPPORTED")
+        return "unsupported platform";
+    return "terminal host not verified";
 }
 function parseResult(output) {
     const line = output.trim().split(/\r?\n/).filter(Boolean).at(-1);

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

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

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

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

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

@@ -0,0 +1,42 @@
+export type MaintenanceAction = "list" | "stop" | "stop-all" | "host-status" | "host-stop";
+export type MaintenanceHostState = "none" | "running" | "stopped" | "unresponsive" | "incompatible" | "refused" | "unverifiable" | "unavailable";
+/** The versioned `a1 tabs` report: `a1-tabs-maintenance-v1`, as printed by the terminal host. */
+export interface MaintenanceReport {
+    readonly schema: "a1-tabs-maintenance-v1";
+    readonly command: string;
+    readonly host: MaintenanceHostState;
+    readonly stateDir?: string;
+    readonly result?: Record<string, unknown>;
+    readonly pid?: number;
+    readonly message?: string;
+    readonly releaseRoot?: string | null;
+    readonly terminatedUnresponsive?: number;
+    /** The terminal host's exit status: 0 success, 3 refused or failed, 4 another generation. */
+    readonly exitCode: number;
+}
+export interface MaintenanceOptions {
+    readonly action: MaintenanceAction;
+    readonly tabId?: string;
+    readonly profileRoot: string;
+    readonly dataDir: string;
+    readonly runtimeDir: string;
+    /** Installed release roots whose verified terminal host may run maintenance, in preference order. */
+    readonly releaseRoots: readonly string[];
+    readonly environment: NodeJS.ProcessEnv;
+    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;
+    }>;
+}
+/**
+ * Runs one maintenance form through a verified terminal host. When the running host speaks
+ * another protocol generation, it retries once with the binary from the release that host
+ * recorded, after verifying that release's manifest; it never runs an unverified binary.
+ */
+export declare function runTerminalHostMaintenance(options: MaintenanceOptions): Promise<MaintenanceReport>;
+/** The largest maintenance report accepted from the terminal host. */
+export declare const MAX_MAINTENANCE_REPORT_BYTES: number;

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

@@ -0,0 +1,78 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { runBoundedHostCommand } from "./bounded-host-command.js";
+import { resolveTerminalHostPath } from "./ensure-terminal-host.js";
+import { verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
+const INCOMPATIBLE_EXIT = 4;
+/**
+ * Runs one maintenance form through a verified terminal host. When the running host speaks
+ * another protocol generation, it retries once with the binary from the release that host
+ * recorded, after verifying that release's manifest; it never runs an unverified binary.
+ */
+export async function runTerminalHostMaintenance(options) {
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    const executable = await firstVerifiedHost(options, options.releaseRoots, platform, architecture);
+    if (executable === undefined)
+        return unavailable(options.action, "no verified terminal host is installed");
+    const report = await invoke(options, executable);
+    if (report.exitCode !== INCOMPATIBLE_EXIT || typeof report.releaseRoot !== "string")
+        return report;
+    const cohort = await firstVerifiedHost({ ...options, environment: {} }, [report.releaseRoot], platform, architecture);
+    if (cohort === undefined || cohort === executable) {
+        return { ...report, message: "the running tabs use another version whose terminal host cannot be verified" };
+    }
+    return await invoke(options, cohort);
+}
+function arguments_(options) {
+    const command = options.action === "stop" ? ["stop", options.tabId ?? ""] : [options.action];
+    return ["tabs", ...command, "--profile", options.profileRoot, "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir];
+}
+async function invoke(options, executable) {
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    try {
+        const result = await (options.run ?? runHost)(executable, arguments_(options), timeoutMs);
+        const line = result.stdout.trim().split(/\r?\n/u).at(-1) ?? "";
+        const parsed = JSON.parse(line);
+        if (parsed.schema !== "a1-tabs-maintenance-v1" || typeof parsed.host !== "string")
+            throw new Error("malformed maintenance report");
+        return { ...parsed, exitCode: result.code };
+    }
+    catch (error) {
+        return unavailable(options.action, `terminal host maintenance failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function firstVerifiedHost(options, roots, platform, architecture) {
+    const override = options.environment[PRODUCT_IDENTITY.environment.developmentInstanceId]
+        ? options.environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim()
+        : undefined;
+    if (override) {
+        try {
+            await access(override, constants.R_OK | (platform === "win32" ? 0 : constants.X_OK));
+            return override;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    for (const root of roots) {
+        const candidate = resolveTerminalHostPath(root, {}, platform, architecture);
+        try {
+            await (options.verify ?? verifyTerminalHostArtifact)(candidate, platform, architecture);
+            return candidate;
+        }
+        catch {
+            // Rationale: an older retained release may predate the packaged host; try the next one.
+        }
+    }
+    return undefined;
+}
+function unavailable(action, message) {
+    return { schema: "a1-tabs-maintenance-v1", command: action, host: "unavailable", message, exitCode: 3 };
+}
+/** The largest maintenance report accepted from the terminal host. */
+export const MAX_MAINTENANCE_REPORT_BYTES = 4 * 1024 * 1024;
+async function runHost(executable, arguments_, timeoutMs) {
+    return await runBoundedHostCommand(executable, arguments_, { maxStdoutBytes: MAX_MAINTENANCE_REPORT_BYTES, timeoutMs, label: "terminal host maintenance" });
+}

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

@@ -1,10 +1,11 @@
 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 solo: boolean;
+    /** Both standard input and standard output are terminals the attach client can own. */
+    readonly interactive: boolean;
     readonly ensureHost: () => Promise<EnsureTerminalHostResult>;
 }
-/** Invariant: every non-bare or default-off launch stays outside resident discovery and startup. */
+/** 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

@@ -1,8 +1,10 @@
-/** Invariant: every non-bare or default-off launch stays outside resident discovery and startup. */
+/** Invariant: comparison, solo, and superseded launches stay outside resident discovery and startup. */
 export async function selectResidentHost(options) {
-    if (options.profileId !== "a1" || options.hasSessionSelection || !options.currentLaunchContract)
-        return null;
-    if (!await options.readSetting())
+    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/settings.d.ts

@@ -1,9 +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 residentTabs: boolean;
+    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>;
-export declare function readResidentTabsSetting(profileDir: string, namespace?: string, legacyConfigDir?: string, profileId?: string): Promise<boolean>;

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

@@ -2,9 +2,15 @@ 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({
-    residentTabs: false,
-    maxConcurrentStarts: 2,
+    tabsMax: 10,
+    tabsAutoName: true,
+    maxConcurrentStarts: RESIDENT_TABS_MAX_CONCURRENT_STARTS,
+    prewarmCount: RESIDENT_TABS_PREWARM_COUNT,
     unresponsiveRestartSeconds: 120,
     stallNoticeSeconds: 300,
 });
@@ -38,28 +44,23 @@ export async function readResidentTabLaunchSettings(profileDir, namespace = "a1"
         return DEFAULTS;
     }
 }
-export async function readResidentTabsSetting(profileDir, namespace = "a1", legacyConfigDir, profileId = namespace) {
-    return (await readResidentTabLaunchSettings(profileDir, namespace, legacyConfigDir, profileId)).residentTabs;
-}
 function resolveLaunchValues(document, migrations) {
     const resolution = resolveOwnedUiSettings({
         declarations: [
-            OWNED_SETTING_DECLARATIONS.residentTabs,
-            OWNED_SETTING_DECLARATIONS.tabsMaxConcurrentStarts,
-            OWNED_SETTING_DECLARATIONS.tabsUnresponsiveRestartSeconds,
-            OWNED_SETTING_DECLARATIONS.tabsStallNoticeSeconds,
+            OWNED_SETTING_DECLARATIONS.tabsMax,
+            OWNED_SETTING_DECLARATIONS.tabsAutoName,
         ],
         migrations,
         document,
         currentVersion: OWNED_UI_SETTINGS_VERSION,
     });
-    const maximum = settingValue(resolution, "tabsMaxConcurrentStarts");
-    const unresponsive = settingValue(resolution, "tabsUnresponsiveRestartSeconds");
-    const stall = settingValue(resolution, "tabsStallNoticeSeconds");
+    const tabsMax = document.values?.["tabsMax"] ?? settingValue(resolution, "tabsMax");
     return {
-        residentTabs: settingValue(resolution, "residentTabs") === true,
-        maxConcurrentStarts: typeof maximum === "number" ? maximum : DEFAULTS.maxConcurrentStarts,
-        unresponsiveRestartSeconds: typeof unresponsive === "number" ? unresponsive : DEFAULTS.unresponsiveRestartSeconds,
-        stallNoticeSeconds: typeof stall === "number" ? stall : DEFAULTS.stallNoticeSeconds,
+        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>;