@timurproko/a1 0.2.7-dev.792 → 0.2.7-dev.806

package/dist/foundation/release/bootstrap.js

@@ -12,7 +12,7 @@ import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
 import { probeOwnership, readEndpointMetadata, removeEndpointArtifacts, sweepDeadEndpoints } from "./endpoints.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 import { selectUpdateLaunchRelease } from "./update-launch.js";
-import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
+import { assertCertifiedFilesPresent, consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, repairMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
@@ -61,10 +61,10 @@ async function runBootstrapAttempt(options, retriesRemaining) {
         });
         if (resident !== null) {
             residentContext = resident.status === "ready" ? {
-                residentRootExecutable: resident.executable,
+                residentRootExecutable: resident.executable.executable,
                 residentRootArguments: JSON.stringify([
+                    resident.executable.entry,
                     "attach", "--endpoint", resident.endpoint, "--cwd", process.cwd(), "--clear-exit-ms", String(CLEAR_EXIT_INTERVAL_MS),
-                    "--tabs-max", String((await residentLaunchSettings).tabsMax),
                     "--profile", environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
                     "--settings-file", resolve(agentProfileDir, "settings.json"),
                     "--data-dir", paths.dataDir, "--runtime-dir", paths.runtimeDir,
@@ -126,7 +126,23 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     const installedVersion = await readInstalledVersion(options.packageRoot);
     const activeId = state.references.active;
     const active = activeId === null ? undefined : state.releases[activeId];
-    const activeIsLaunchable = active === undefined || (options.releaseIsLaunchable?.(active.releaseRoot) ?? true);
+    let activeIsLaunchable = active === undefined || (options.releaseIsLaunchable?.(active.releaseRoot) ?? true);
+    let excludedRetainedReleaseId;
+    if (activeIsLaunchable && active?.approval === "approved" && active.packageVersion === installedVersion) {
+        try {
+            await assertCertifiedFilesPresent(active.releaseRoot);
+        }
+        catch {
+            try {
+                await repairApprovedRelease(options.packageRoot, active, paths.dataDir);
+            }
+            catch {
+                // Security: a damaged certified release is no longer a fallback when package bytes cannot restore it.
+                activeIsLaunchable = false;
+                excludedRetainedReleaseId = active.releaseId;
+            }
+        }
+    }
     if (activeIsLaunchable && active?.approval === "approved" && active.packageVersion === installedVersion) {
         const endpointMatches = endpoint?.releaseId === active.releaseId
             && endpoint.releaseRoot === active.releaseRoot
@@ -140,18 +156,27 @@ async function runBootstrapAttempt(options, retriesRemaining) {
                 await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
             await markStartupPhase(environment, "durable-validation-start");
             const retained = await readRestartCertifiedRelease(active, paths.dataDir).catch(async () => {
-                const verified = await readMaterializedRelease(active.releaseRoot, resolve(paths.dataDir, "releases"));
-                if (verified.releaseId !== active.releaseId || verified.contentDigest !== active.contentDigest || verified.packageVersion !== active.packageVersion) {
-                    throw new Error("completely verified release differs from the approved active record");
+                let verified;
+                try {
+                    verified = await readMaterializedRelease(active.releaseRoot, resolve(paths.dataDir, "releases"));
+                }
+                catch {
+                    verified = await repairApprovedRelease(options.packageRoot, active, paths.dataDir);
+                    return verified;
                 }
+                assertApprovedReleaseMatches(verified, active);
                 await certifyMaterializedRelease(verified, paths.dataDir);
                 return verified;
-            });
-            await markStartupPhase(environment, "durable-validation-complete");
-            await markStartupPhase(environment, "replacement-supervisor-start");
-            await ensureSupervisor(retained, environment);
-            await markStartupPhase(environment, "replacement-supervisor-ready");
-            return await launchSelected(retained);
+            }).catch(() => null);
+            if (retained !== null) {
+                await markStartupPhase(environment, "durable-validation-complete");
+                await markStartupPhase(environment, "replacement-supervisor-start");
+                await ensureSupervisor(retained, environment);
+                await markStartupPhase(environment, "replacement-supervisor-ready");
+                return await launchSelected(retained);
+            }
+            activeIsLaunchable = false;
+            excludedRetainedReleaseId = active.releaseId;
         }
     }
     // Concurrency: an installation being replaced is not a reason to refuse a launch. While
@@ -163,7 +188,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
         candidate = await materializeRelease(options.packageRoot, paths.dataDir);
     }
     catch (error) {
-        const fallback = await launchRetainedActive(state, paths, environment, launchSelected);
+        const fallback = await launchRetainedActive(state, paths, environment, launchSelected, excludedRetainedReleaseId);
         if (fallback === null)
             throw error;
         return fallback;
@@ -290,10 +315,10 @@ async function runBootstrapAttempt(options, retriesRemaining) {
  * certifying anything new, and reports no selection when there is nothing safe
  * to fall back to.
  */
-async function launchRetainedActive(state, paths, environment, launch) {
+async function launchRetainedActive(state, paths, environment, launch, excludedReleaseId) {
     const activeId = state.references.active;
     const active = activeId === null ? undefined : state.releases[activeId];
-    if (!active || active.approval !== "approved")
+    if (!active || active.approval !== "approved" || active.releaseId === excludedReleaseId)
         return null;
     try {
         const retained = await readCertifiedReleaseManifest(active, resolve(paths.dataDir, "releases"));
@@ -304,6 +329,18 @@ async function launchRetainedActive(state, paths, environment, launch) {
         return null;
     }
 }
+async function repairApprovedRelease(packageRoot, active, dataDir) {
+    const repaired = await repairMaterializedRelease(packageRoot, active.releaseRoot);
+    assertApprovedReleaseMatches(repaired, active);
+    await recordParentCertifiedRelease(repaired, dataDir);
+    return repaired;
+}
+function assertApprovedReleaseMatches(release, active) {
+    if (release.releaseId !== active.releaseId || release.contentDigest !== active.contentDigest
+        || (active.packageVersion !== undefined && release.packageVersion !== active.packageVersion)) {
+        throw new Error("completely verified release differs from the approved active record");
+    }
+}
 async function readInstalledVersion(packageRoot) {
     const manifest = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
     if (typeof manifest.version !== "string" || manifest.version.length === 0) {

package/dist/foundation/release/index.d.ts

@@ -15,7 +15,7 @@ export { PRODUCT_PACKAGE_NAME, createReleaseIdentity, deriveReleaseIdentity, dig
 export type { DiscoverReleasePayloadOptions, DiscoveredReleasePayload, ReleaseFileIdentity, ReleaseIdentity } from "./release.js";
 export { collectRelease, prepareReleaseCleanup, runBoundedReleaseCleanup, runReleaseCleanupWorker, scheduleReleaseCleanup } from "./release-gc.js";
 export type { ReleaseCleanupLimits, ReleaseCleanupOperations, ReleaseCleanupOptions, ReleaseCleanupResult, ReleaseCleanupWorkerOptions } from "./release-gc.js";
-export { RELEASE_MANIFEST_FILENAME, assertImmutableExecutionRoot, consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease, } from "./release-store.js";
+export { RELEASE_MANIFEST_FILENAME, ReleaseRepairUnavailableError, assertCertifiedFilesPresent, assertImmutableExecutionRoot, consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, repairMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease, } from "./release-store.js";
 export type { CertifiedReleaseRecord, MaterializeReleaseOptions, MaterializedRelease, ReadCertifiedReleaseManifestOptions, ReleaseContentOperation, ReleaseContentOperationEvent, VerifyMaterializedReleaseOptions, } from "./release-store.js";
 export { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument, restartSealDigest } from "./restart-certification.js";
 export type { RestartSeal, RestartValidationEvent } from "./restart-certification.js";

package/dist/foundation/release/index.js

@@ -7,7 +7,7 @@ export { listRecordedEndpoints, liveReleaseIds, probeOwnership, readEndpointMeta
 export { cleanupProvenIdleOwner, cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
 export { PRODUCT_PACKAGE_NAME, createReleaseIdentity, deriveReleaseIdentity, digestManifestFiles, discoverReleasePayload, packageRootFromModule, releaseFileIdentity, resolveWithin, } from "./release.js";
 export { collectRelease, prepareReleaseCleanup, runBoundedReleaseCleanup, runReleaseCleanupWorker, scheduleReleaseCleanup } from "./release-gc.js";
-export { RELEASE_MANIFEST_FILENAME, assertImmutableExecutionRoot, consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease, } from "./release-store.js";
+export { RELEASE_MANIFEST_FILENAME, ReleaseRepairUnavailableError, assertCertifiedFilesPresent, assertImmutableExecutionRoot, consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, repairMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease, } from "./release-store.js";
 export { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument, restartSealDigest } from "./restart-certification.js";
 export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistry } from "./stable-release.js";
 export { PACKAGE_UNLOCK_PATIENCE_MS, PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, isPackageLockError, lockedPackageDiagnostic, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";

package/dist/foundation/release/release-store.d.ts

@@ -31,12 +31,24 @@ export interface CertifiedReleaseRecord {
     /** Absent on records written before releases declared a handoff contract. */
     readonly launchContract?: string;
 }
+/** Reports that installed package bytes cannot safely reproduce an approved release. */
+export declare class ReleaseRepairUnavailableError extends Error {
+    readonly code: "RELEASE_REPAIR_UNAVAILABLE";
+    constructor(message: string, options?: ErrorOptions);
+}
 /** Process-authority compatibility controls for metadata-only release loading. */
 export type ReadCertifiedReleaseManifestOptions = ReadCertifiedDependencyLayerOptions;
 export declare function materializeRelease(packageRoot: string, dataDir: string, options?: MaterializeReleaseOptions): Promise<MaterializedRelease>;
 /** Consume proof that this exact object was freshly materialized or fully verified in this process. */
 export declare function consumeMaterializationProof(release: MaterializedRelease): boolean;
 export declare function readMaterializedRelease(releaseRoot: string, selectedStoreRoot?: string): Promise<MaterializedRelease>;
+/** Fast presence check before trusted certification permits a release to skip full verification. */
+export declare function assertCertifiedFilesPresent(releaseRoot: string): Promise<void>;
+/**
+ * Restore changed or missing product payload files from the installed package without replacing the
+ * immutable release directory. Dependency layers retain their own verification and repair policy.
+ */
+export declare function repairMaterializedRelease(packageRoot: string, releaseRoot: string): Promise<MaterializedRelease>;
 /**
  * Load metadata for a release whose bytes were already certified by the
  * current parent process or an authenticated live supervisor. Callers must

package/dist/foundation/release/release-store.js

@@ -10,6 +10,14 @@ import { dependencyReference, materializeDependencyLayer, readCertifiedDependenc
 const RELEASE_FILE_IO_CONCURRENCY = 32;
 const certificationReady = new WeakSet();
 export const RELEASE_MANIFEST_FILENAME = PRODUCT_IDENTITY.manifest.releaseFilename;
+/** Reports that installed package bytes cannot safely reproduce an approved release. */
+export class ReleaseRepairUnavailableError extends Error {
+    code = "RELEASE_REPAIR_UNAVAILABLE";
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "ReleaseRepairUnavailableError";
+    }
+}
 export async function materializeRelease(packageRoot, dataDir, options = {}) {
     const payload = await discoverReleasePayload(packageRoot, {
         onSourceRead: (path, bytes) => options.onOperation?.({ operation: "source-read", path, bytes }),
@@ -71,7 +79,7 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
         const releaseRoot = resolveWithin(storeRoot, identity.releaseId);
         if (await lstat(releaseRoot).catch(() => null)) {
             await rm(candidate, { recursive: true, force: true });
-            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
+            return certificationReadyRelease(await verifyOrRepairMaterializedRelease(payload.packageRoot, releaseRoot, identity));
         }
         await writeFile(resolve(candidate, RELEASE_MANIFEST_FILENAME), JSON.stringify(identity, null, 2), { mode: 0o400, flag: "wx" });
         try {
@@ -81,7 +89,7 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
             if (!await lstat(releaseRoot).catch(() => null))
                 throw error;
             await rm(candidate, { recursive: true, force: true });
-            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
+            return certificationReadyRelease(await verifyOrRepairMaterializedRelease(payload.packageRoot, releaseRoot, identity));
         }
         return certificationReadyRelease({ ...identity, releaseRoot: await realpath(releaseRoot) });
     }
@@ -102,6 +110,61 @@ export async function readMaterializedRelease(releaseRoot, selectedStoreRoot) {
     const manifest = JSON.parse(await readFile(resolve(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
     return certificationReadyRelease(await verifyMaterializedRelease(canonical, manifest, selectedStoreRoot));
 }
+/** Fast presence check before trusted certification permits a release to skip full verification. */
+export async function assertCertifiedFilesPresent(releaseRoot) {
+    const canonical = await realpath(releaseRoot);
+    const manifest = await readReleaseManifest(canonical);
+    await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
+        const metadata = await lstat(resolveWithin(canonical, file.path));
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            throw new Error(`certified release file is missing: ${file.path}`);
+    });
+}
+/**
+ * Restore changed or missing product payload files from the installed package without replacing the
+ * immutable release directory. Dependency layers retain their own verification and repair policy.
+ */
+export async function repairMaterializedRelease(packageRoot, releaseRoot) {
+    const canonical = await realpath(releaseRoot);
+    let manifest;
+    let payload;
+    try {
+        manifest = await readReleaseManifest(canonical);
+        payload = await discoverReleasePayload(packageRoot);
+        assertCurrentLaunchContract(payload);
+    }
+    catch (error) {
+        throw repairUnavailable("release repair metadata is unavailable", error);
+    }
+    if (payload.packageVersion !== manifest.packageVersion) {
+        throw repairUnavailable(`installed package version ${payload.packageVersion} does not match release ${manifest.packageVersion}`);
+    }
+    const payloadPaths = new Set(payload.paths.filter(path => !path.startsWith("node_modules/")));
+    try {
+        await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
+            const destination = resolveWithin(canonical, file.path);
+            if (!await certifiedFileDiffers(destination, file))
+                return;
+            if (!payloadPaths.has(file.path))
+                throw repairUnavailable(`installed package does not carry ${file.path}`);
+            const source = resolveWithin(payload.packageRoot, file.path);
+            const sourceMetadata = await lstat(source);
+            if (!sourceMetadata.isFile() || sourceMetadata.isSymbolicLink())
+                throw repairUnavailable(`installed package file is not regular: ${file.path}`);
+            const bytes = payload.cachedFiles.get(file.path) ?? await readFile(source);
+            if (bytes.length !== file.bytes || createHash("sha256").update(bytes).digest("hex") !== file.sha256) {
+                throw repairUnavailable(`installed package bytes do not match release file ${file.path}`);
+            }
+            await replaceReleaseFile(destination, bytes, file);
+        });
+        return await verifyMaterializedRelease(canonical, manifest);
+    }
+    catch (error) {
+        if (error instanceof ReleaseRepairUnavailableError)
+            throw error;
+        throw repairUnavailable("release repair could not restore the certified payload", error);
+    }
+}
 /**
  * Load metadata for a release whose bytes were already certified by the
  * current parent process or an authenticated live supervisor. Callers must
@@ -197,6 +260,65 @@ async function verifyFile(root, file, options) {
     if (digest !== file.sha256)
         throw new Error(`release file digest mismatch: ${file.path}`);
 }
+async function verifyOrRepairMaterializedRelease(packageRoot, releaseRoot, expected) {
+    try {
+        return await verifyMaterializedRelease(releaseRoot, expected);
+    }
+    catch {
+        await repairMaterializedRelease(packageRoot, releaseRoot);
+        return await verifyMaterializedRelease(releaseRoot, expected);
+    }
+}
+async function readReleaseManifest(releaseRoot) {
+    const manifest = JSON.parse(await readFile(resolveWithin(releaseRoot, RELEASE_MANIFEST_FILENAME), "utf8"));
+    validateManifest(manifest);
+    if (releaseRoot.split(sep).at(-1) !== manifest.releaseId)
+        throw new Error(`release directory does not match identity ${manifest.releaseId}`);
+    return manifest;
+}
+async function certifiedFileDiffers(path, file) {
+    const metadata = await lstat(path).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (metadata === null || !metadata.isFile() || metadata.isSymbolicLink() || metadata.size !== file.bytes)
+        return true;
+    if ((metadata.mode & 0o222) !== 0 || ((metadata.mode & 0o111) !== 0) !== file.executable)
+        return true;
+    return createHash("sha256").update(await readFile(path)).digest("hex") !== file.sha256;
+}
+async function replaceReleaseFile(path, bytes, file) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = resolve(dirname(path), `.a1-repair-${randomUUID()}`);
+    const mode = file.executable ? 0o500 : 0o400;
+    let existing = null;
+    try {
+        await writeFile(temporary, bytes, { flag: "wx", mode: 0o600 });
+        existing = await lstat(path).catch((error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (existing !== null) {
+            if (!existing.isFile() || existing.isSymbolicLink())
+                throw repairUnavailable(`release file cannot be safely replaced: ${file.path}`);
+            // Platform: Windows refuses rename-over for a read-only destination.
+            await chmod(path, 0o600);
+        }
+        await rename(temporary, path);
+        await chmod(path, mode);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => { });
+        if (existing !== null)
+            await chmod(path, mode).catch(() => { });
+        throw error;
+    }
+}
+function repairUnavailable(message, cause) {
+    return new ReleaseRepairUnavailableError(message, cause === undefined ? {} : { cause });
+}
 function certificationReadyRelease(release) {
     certificationReady.add(release);
     return release;

package/dist/foundation/resident-tabs/bounded-host-command.d.ts

@@ -1,3 +1,4 @@
+import type { TerminalHostCommand } from "./ensure-terminal-host.js";
 export interface BoundedHostCommandResult {
     readonly code: number;
     readonly stdout: string;
@@ -8,9 +9,10 @@ export interface BoundedHostCommandLimits {
     readonly timeoutMs: number;
     /** Names the exchange in the timeout error. */
     readonly label: string;
+    readonly environment?: NodeJS.ProcessEnv;
 }
 /**
  * Runs one terminal-host command whose report is small. An oversized report kills the command and
  * reports a failed exchange; a command that outlives its deadline is killed and rejected.
  */
-export declare function runBoundedHostCommand(executable: string, arguments_: readonly string[], limits: BoundedHostCommandLimits): Promise<BoundedHostCommandResult>;
+export declare function runBoundedHostCommand(command: TerminalHostCommand, arguments_: readonly string[], limits: BoundedHostCommandLimits): Promise<BoundedHostCommandResult>;

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

@@ -3,9 +3,13 @@ import { spawn } from "node:child_process";
  * Runs one terminal-host command whose report is small. An oversized report kills the command and
  * reports a failed exchange; a command that outlives its deadline is killed and rejected.
  */
-export async function runBoundedHostCommand(executable, arguments_, limits) {
+export async function runBoundedHostCommand(command, arguments_, limits) {
     return await new Promise((resolvePromise, rejectPromise) => {
-        const child = spawn(executable, [...arguments_], { windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+        const child = spawn(command.executable, [command.entry, ...arguments_], {
+            env: limits.environment,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
         const stdout = [];
         let size = 0;
         let overflowed = false;

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

@@ -42,6 +42,7 @@ export interface TabBridgeOptions {
 export declare class TabBridgeClient {
     #private;
     constructor(options: TabBridgeOptions);
+    get tabId(): string;
     get available(): boolean;
     captureAttachment(): TabAttachment | null;
     onCommand(listener: (command: TabBridgeCommand) => void): () => void;
@@ -55,6 +56,7 @@ export declare class TabBridgeClient {
     shortcuts(assignments: Readonly<Record<string, string | null>>): void;
     requestDetach(origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
     requestRestart(origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
+    requestClose(origin?: TabAttachment | null, timeoutMs?: number): Promise<boolean>;
     consumeControllerBoundaryInput(data: string): string;
     close(): void;
 }

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

@@ -20,12 +20,16 @@ export class TabBridgeClient {
     #pending = new Map();
     #startWaiter = null;
     #commandListeners = new Set();
+    #pendingCommands = [];
     #boundaryInputRemainder = "";
     constructor(options) { this.#options = options; }
+    get tabId() { return this.#options.credentials.tabId; }
     get available() { return this.#available && this.#connected; }
     captureAttachment() { return this.#attachment === null ? null : { ...this.#attachment }; }
     onCommand(listener) {
         this.#commandListeners.add(listener);
+        for (const command of this.#pendingCommands.splice(0))
+            listener(command);
         return () => this.#commandListeners.delete(listener);
     }
     async start(timeoutMs = 4_000) {
@@ -119,6 +123,9 @@ export class TabBridgeClient {
     requestRestart(origin = this.captureAttachment(), timeoutMs = 1_000) {
         return this.#requestAction("restart", origin, timeoutMs);
     }
+    requestClose(origin = this.captureAttachment(), timeoutMs = 1_000) {
+        return this.#requestAction("close", origin, timeoutMs);
+    }
     consumeControllerBoundaryInput(data) {
         const prefix = "\x1bP+a1;controller=";
         const suffix = "\x1b\\";
@@ -176,6 +183,12 @@ export class TabBridgeClient {
         this.#fail(false);
     }
     #emitCommand(command) {
+        if (this.#commandListeners.size === 0) {
+            if (this.#pendingCommands.length >= 16)
+                this.#pendingCommands.shift();
+            this.#pendingCommands.push(command);
+            return;
+        }
         for (const listener of this.#commandListeners)
             listener(command);
     }

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

@@ -6,7 +6,6 @@ export interface DoctorOptions {
     readonly hostStatus: MaintenanceReport;
     readonly releaseRoots: readonly string[];
     readonly settings: {
-        readonly tabsMax: number;
         readonly tabsAutoName: boolean;
     };
     readonly home?: string;

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

@@ -33,7 +33,7 @@ export async function writeDoctorBundle(options) {
             node: process.version,
             detachmentMode: options.hostStatus.result?.detachmentMode ?? null,
         }),
-        json("settings.json", { tabsMax: options.settings.tabsMax, tabsAutoName: options.settings.tabsAutoName }),
+        json("settings.json", { tabsAutoName: options.settings.tabsAutoName }),
     ];
     const crashes = [];
     for (const name of names.filter(name => CRASH_NAME.test(name)).sort()) {
@@ -153,11 +153,11 @@ async function redactedMarker(path, redact) {
 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")
+        const addon = resolveTerminalHostPath(root, {}, platform, architecture);
+        const manifest = await readFile(resolve(dirname(addon), TERMINAL_HOST_MANIFEST_FILENAME), "utf8")
             .then(text => JSON.parse(text))
             .catch(() => null);
-        const verification = await verifyTerminalHostArtifact(executable, platform, architecture)
+        const verification = await verifyTerminalHostArtifact(addon, platform, architecture)
             .then(() => "verified")
             .catch((error) => error instanceof Error && "code" in error ? String(error.code) : "failed");
         facts.push({ releaseRoot: redact(root), verification, manifest });

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

@@ -1,7 +1,11 @@
 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 interface TerminalHostCommand {
+    readonly executable: string;
+    readonly entry: string;
+}
 export type EnsureTerminalHostResult = {
     readonly status: "ready";
-    readonly executable: string;
+    readonly executable: TerminalHostCommand;
     readonly endpoint: string;
 } | {
     readonly status: "fallback";
@@ -24,8 +28,9 @@ 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>;
+    readonly verify?: (addon: 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 resolveTerminalHostEntryPath(releaseRoot: string): string;
 export declare function ensureTerminalHost(options: EnsureTerminalHostOptions): Promise<EnsureTerminalHostResult>;
 export {};

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

@@ -8,8 +8,10 @@ export function resolveTerminalHostPath(releaseRoot, environment = process.env,
     const override = developmentOverride(environment);
     if (override)
         return resolve(override);
-    const executable = platform === "win32" ? `${PRODUCT_IDENTITY.artifacts.nativeExecutable}.exe` : PRODUCT_IDENTITY.artifacts.nativeExecutable;
-    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, executable);
+    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`);
+}
+export function resolveTerminalHostEntryPath(releaseRoot) {
+    return resolve(releaseRoot, "dist", "foundation", "resident-tabs", `${PRODUCT_IDENTITY.artifacts.terminalHostEntry}.js`);
 }
 /** The terminal-host override is a development aid; installed releases always run their own verified artifact. */
 function developmentOverride(environment) {
@@ -22,10 +24,11 @@ export async function ensureTerminalHost(options) {
     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);
+    const addon = resolveTerminalHostPath(options.releaseRoot, options.environment, platform, architecture);
+    const command = { executable: process.execPath, entry: resolveTerminalHostEntryPath(options.releaseRoot) };
     if (developmentOverride(options.environment)) {
         try {
-            await access(executable, constants.R_OK | (platform === "win32" ? 0 : constants.X_OK));
+            await Promise.all([access(addon, constants.R_OK), access(command.entry, constants.R_OK)]);
         }
         catch {
             return { status: "fallback", reason: "terminal host not installed" };
@@ -33,7 +36,7 @@ export async function ensureTerminalHost(options) {
     }
     else {
         try {
-            await (options.verify ?? verifyTerminalHostArtifact)(executable, platform, architecture);
+            await (options.verify ?? verifyTerminalHostArtifact)(addon, platform, architecture);
         }
         catch (error) {
             return { status: "fallback", reason: verificationReason(error) };
@@ -43,12 +46,13 @@ export async function ensureTerminalHost(options) {
     const timeoutMs = options.timeoutMs ?? 8_000;
     const common = ["--profile", options.profileRoot, "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir];
     const environment = { ...options.environment };
+    const invoke = async (arguments_, commandTimeoutMs) => await run(command.executable, [command.entry, ...arguments_], environment, commandTimeoutMs);
     try {
-        const probe = await run(executable, ["probe", ...common], environment, Math.min(4_000, timeoutMs));
+        const probe = await invoke(["probe", ...common], 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: "ready", executable: command, endpoint: existing.endpoint };
             }
             return {
                 status: "fallback",
@@ -61,11 +65,11 @@ export async function ensureTerminalHost(options) {
             return { status: "fallback", reason: classifiedReason(existing?.reason, "host probe failed") };
         const maximum = Math.max(1, Math.min(8, Math.trunc(options.maxConcurrentStarts ?? 2)));
         const unresponsiveRestartSeconds = Math.max(30, Math.min(600, Math.trunc(options.unresponsiveRestartSeconds ?? 120)));
-        const start = await run(executable, [
+        const start = await invoke([
             "server", "--detach", ...common,
             "--max-concurrent-starts", String(maximum),
             "--unresponsive-restart-seconds", String(unresponsiveRestartSeconds),
-        ], environment, timeoutMs);
+        ], timeoutMs);
         const started = parseResult(start.stdout);
         if (start.code !== 0)
             return { status: "fallback", reason: classifiedReason(started?.reason, "launch not verified") };
@@ -73,11 +77,11 @@ export async function ensureTerminalHost(options) {
             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 result = await invoke(["probe", ...common], 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: "ready", executable: command, endpoint: ready.endpoint };
                 }
                 return {
                     status: "fallback",

package/dist/foundation/resident-tabs/host-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/foundation/resident-tabs/host-entry.js

@@ -0,0 +1,17 @@
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+const filename = fileURLToPath(import.meta.url);
+const target = `${process.platform}-${process.arch}`;
+const development = process.env[PRODUCT_IDENTITY.environment.developmentInstanceId]?.trim();
+const override = development ? process.env[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim() : undefined;
+const addonPath = resolve(override || resolve(dirname(filename), "../../native", target, `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`));
+const addon = createRequire(import.meta.url)(addonPath);
+if (typeof addon.runRole !== "function")
+    throw new Error("terminal host addon exports are incompatible");
+// Invariant: runRole blocks Node's main thread, so this entry must not register JavaScript signal
+// listeners whose callbacks cannot run until the native role has already returned. Default process
+// signal handling keeps attach clients and identity-verified resident roles externally stoppable.
+process.env[PRODUCT_IDENTITY.environment.terminalHostPath] = addonPath;
+process.exitCode = addon.runRole(process.argv.slice(2), { executable: process.execPath, entry: filename, artifact: addonPath });

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

@@ -1,5 +1,5 @@
-export { ensureTerminalHost, resolveTerminalHostPath } from "./ensure-terminal-host.js";
-export type { EnsureTerminalHostOptions, EnsureTerminalHostResult, TerminalHostFallbackReason } from "./ensure-terminal-host.js";
+export { ensureTerminalHost, resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+export type { EnsureTerminalHostOptions, EnsureTerminalHostResult, TerminalHostCommand, TerminalHostFallbackReason } from "./ensure-terminal-host.js";
 export { readResidentTabLaunchSettings } from "./settings.js";
 export type { ResidentTabLaunchSettings } from "./settings.js";
 export { selectResidentHost } from "./routing.js";

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

@@ -1,4 +1,4 @@
-export { ensureTerminalHost, resolveTerminalHostPath } from "./ensure-terminal-host.js";
+export { ensureTerminalHost, resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
 export { readResidentTabLaunchSettings } from "./settings.js";
 export { selectResidentHost } from "./routing.js";
 export { readResidentReleaseHolds } from "./release-holds.js";

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

@@ -1,3 +1,4 @@
+import { type TerminalHostCommand } from "./ensure-terminal-host.js";
 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. */
@@ -26,16 +27,16 @@ export interface MaintenanceOptions {
     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 verify?: (addon: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
+    readonly run?: (command: TerminalHostCommand, arguments_: readonly string[], timeoutMs: number) => Promise<{
         readonly code: number;
         readonly stdout: string;
     }>;
 }
 /**
  * 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.
+ * another protocol generation, it retries once with the addon from the release that host
+ * recorded, after verifying that release's manifest; it never loads an unverified addon.
  */
 export declare function runTerminalHostMaintenance(options: MaintenanceOptions): Promise<MaintenanceReport>;
 /** The largest maintenance report accepted from the terminal host. */