@timurproko/a1 0.2.7-dev.788 → 0.2.7-dev.794

package/dist/foundation/process-containment/addon.js

@@ -0,0 +1,57 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+const require = createRequire(import.meta.url);
+const cache = new Map();
+/** Loads one verified Node-API guardian instance per exact addon path. */
+export function loadProcessGuardianAddon(path) {
+    if (!path || path.includes("\0"))
+        throw new TypeError("process guardian addon path is invalid");
+    const exactPath = resolve(path);
+    const cached = cache.get(exactPath);
+    if (cached)
+        return cached;
+    let value;
+    try {
+        value = require(exactPath);
+    }
+    catch (error) {
+        const code = errorCode(error) === "MODULE_NOT_FOUND" || errorCode(error) === "ENOENT"
+            ? "CONTAINMENT_ARTIFACT_MISSING"
+            : "CONTAINMENT_ARTIFACT_INCOMPATIBLE";
+        throw diagnosticError(`process guardian addon could not be loaded: ${errorMessage(error)}`, code);
+    }
+    if (!isProcessGuardianAddon(value)) {
+        throw diagnosticError("process guardian addon exports are incompatible", "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
+    }
+    let report;
+    try {
+        report = value.version();
+    }
+    catch (error) {
+        throw diagnosticError(`process guardian addon identity failed: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
+    }
+    if (report.protocolVersion !== 2 || typeof report.crateVersion !== "string" || report.crateVersion.length === 0 || typeof report.target !== "string") {
+        throw diagnosticError("process guardian addon protocol is incompatible", "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
+    }
+    cache.set(exactPath, value);
+    return value;
+}
+function isProcessGuardianAddon(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return [
+        "version", "inspectProcessStart", "captureTerminalModes", "restoreTerminalModes",
+        "deliverExitNotice", "spawnContained", "spawnWatcher", "waitForProcessExit",
+        "stopProcessGroup", "restoreForegroundGroup", "ignoreConsoleControl",
+    ].every(name => typeof candidate[name] === "function");
+}
+function diagnosticError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+function errorCode(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/foundation/process-containment/artifact.d.ts

@@ -1 +1 @@
-export declare function verifyProcessGuardianArtifact(helperPath: string, platform?: NodeJS.Platform, architecture?: string): Promise<void>;
+export declare function verifyProcessGuardianArtifact(addonPath: string, platform?: NodeJS.Platform, architecture?: string): Promise<void>;

package/dist/foundation/process-containment/artifact.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
-export async function verifyProcessGuardianArtifact(helperPath, platform = process.platform, architecture = process.arch) {
-    const manifestPath = resolve(dirname(helperPath), "manifest.json");
+export async function verifyProcessGuardianArtifact(addonPath, platform = process.platform, architecture = process.arch) {
+    const manifestPath = resolve(dirname(addonPath), "manifest.json");
     let manifest;
     try {
         manifest = JSON.parse(await readFile(manifestPath, "utf8"));
@@ -10,15 +10,16 @@ export async function verifyProcessGuardianArtifact(helperPath, platform = proce
     catch (error) {
         throw artifactError(`process guardian manifest is missing or malformed: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_MISSING");
     }
-    if (manifest.schema !== "a1-process-guardian-artifact-v1" || manifest.protocolVersion !== 1
+    if (manifest.schema !== "a1-process-guardian-artifact-v2" || manifest.kind !== "node-addon"
+        || manifest.nodeApi !== 9 || manifest.protocolVersion !== 2
         || manifest.platform !== platform || manifest.architecture !== architecture
-        || manifest.artifact?.filename !== basename(helperPath)) {
+        || manifest.artifact?.filename !== basename(addonPath)) {
         throw artifactError("process guardian manifest is incompatible with this platform or protocol", "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
     }
     if (manifest.capability !== "supported") {
         throw artifactError(`process containment is not certified for ${platform}-${architecture}`, "CONTAINMENT_UNSUPPORTED");
     }
-    const [bytes, metadata] = await Promise.all([readFile(helperPath), stat(helperPath)]).catch(error => {
+    const [bytes, metadata] = await Promise.all([readFile(addonPath), stat(addonPath)]).catch(error => {
         throw artifactError(`process guardian artifact is unavailable: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_MISSING");
     });
     const digest = createHash("sha256").update(bytes).digest("hex");

package/dist/foundation/process-containment/contracts.d.ts

@@ -7,6 +7,8 @@ export interface ContainedSpawnOptions {
 export interface ContainedProcessHandle {
     readonly identity: NativeProcessIdentity;
     readonly outcome: Promise<LaunchInstanceOutcome>;
+    readonly processGroup?: number;
+    readonly foregroundGroup?: number;
 }
 export interface NativeProcessInspector {
     observe(pid: number): Promise<NativeProcessIdentity | null>;

package/dist/foundation/process-containment/index.d.ts

@@ -1,9 +1,9 @@
+export { loadProcessGuardianAddon } from "./addon.js";
+export type { ProcessGuardianAddon, ProcessGuardianRuntime, ProcessGuardianVersion } from "./addon.js";
+export { AddonContainment, resolveProcessGuardianPath } from "./addon-containment.js";
+export { AddonProcessInspector } from "./addon-process-inspector.js";
 export { verifyProcessGuardianArtifact } from "./artifact.js";
 export { closeVerifiedContainment } from "./contracts.js";
 export type { ContainedProcessHandle, ContainedSpawnOptions, ContainmentCloseResult, NativeProcessInspector, ProcessContainment, ProcessContainmentFactory, } from "./contracts.js";
-export { DarwinNativeProcessInspector } from "./darwin-process-inspector.js";
 export { LinuxNativeProcessInspector } from "./linux-process-inspector.js";
-export { NativeGuardianContainment, resolveProcessGuardianPath } from "./native-guardian-containment.js";
 export { createNativeProcessInspector } from "./native-process-inspector.js";
-export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";
-export type { InspectorCommandResult, InspectorCommandRunner } from "./windows-process-inspector.js";

package/dist/foundation/process-containment/index.js

@@ -1,7 +1,7 @@
+export { loadProcessGuardianAddon } from "./addon.js";
+export { AddonContainment, resolveProcessGuardianPath } from "./addon-containment.js";
+export { AddonProcessInspector } from "./addon-process-inspector.js";
 export { verifyProcessGuardianArtifact } from "./artifact.js";
 export { closeVerifiedContainment } from "./contracts.js";
-export { DarwinNativeProcessInspector } from "./darwin-process-inspector.js";
 export { LinuxNativeProcessInspector } from "./linux-process-inspector.js";
-export { NativeGuardianContainment, resolveProcessGuardianPath } from "./native-guardian-containment.js";
 export { createNativeProcessInspector } from "./native-process-inspector.js";
-export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";

package/dist/foundation/process-containment/native-process-inspector.d.ts

@@ -1,3 +1,4 @@
+import type { ProcessGuardianAddon } from "./addon.js";
 import type { NativeProcessInspector } from "./contracts.js";
 /** Resolve only the platform's exact-process inspector used by cooperative session ownership. */
-export declare function createNativeProcessInspector(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, releaseRoot?: string): Promise<NativeProcessInspector>;
+export declare function createNativeProcessInspector(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, releaseRoot?: string, loadAddon?: (path: string) => ProcessGuardianAddon): Promise<NativeProcessInspector>;

package/dist/foundation/process-containment/native-process-inspector.js

@@ -1,6 +1,6 @@
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 /** Resolve only the platform's exact-process inspector used by cooperative session ownership. */
-export async function createNativeProcessInspector(environment = process.env, platform = process.platform, releaseRoot) {
+export async function createNativeProcessInspector(environment = process.env, platform = process.platform, releaseRoot, loadAddon) {
     if (platform === "linux") {
         const { LinuxNativeProcessInspector } = await import("./linux-process-inspector.js");
         return new LinuxNativeProcessInspector();
@@ -8,14 +8,14 @@ export async function createNativeProcessInspector(environment = process.env, pl
     if (platform !== "win32" && platform !== "darwin")
         throw new Error(`native process identity is unsupported on ${platform}`);
     if (releaseRoot === undefined && !environment[PRODUCT_IDENTITY.environment.processGuardianPath]) {
-        throw new Error("native process identity helper is unavailable");
+        throw new Error("native process identity addon is unavailable");
     }
-    const { resolveProcessGuardianPath } = await import("./native-guardian-containment.js");
-    const helper = resolveProcessGuardianPath(releaseRoot ?? process.cwd(), environment, platform);
-    if (platform === "win32") {
-        const { WindowsNativeProcessInspector } = await import("./windows-process-inspector.js");
-        return new WindowsNativeProcessInspector(helper);
-    }
-    const { DarwinNativeProcessInspector } = await import("./darwin-process-inspector.js");
-    return new DarwinNativeProcessInspector(helper);
+    const [{ resolveProcessGuardianPath }, { loadProcessGuardianAddon }, { AddonProcessInspector }] = await Promise.all([
+        import("./addon-containment.js"),
+        import("./addon.js"),
+        import("./addon-process-inspector.js"),
+    ]);
+    const addonPath = resolveProcessGuardianPath(releaseRoot ?? process.cwd(), environment, platform);
+    const addon = (loadAddon ?? loadProcessGuardianAddon)(addonPath);
+    return new AddonProcessInspector(addon, platform === "win32" ? "windows-filetime:" : "darwin-proc-start:");
 }

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,11 +61,12 @@ 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,
                     "--release-root", release.releaseRoot, "--node-executable", process.execPath,
                 ]),
@@ -125,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
@@ -139,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
@@ -162,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;
@@ -289,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"));
@@ -303,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

@@ -15,6 +15,9 @@ export type TabBridgeCommand = {
     readonly type: "rename";
     readonly name: string;
     readonly nameSource: "default" | "user" | "auto";
+} | {
+    readonly type: "route";
+    readonly route: "settings";
 } | {
     readonly type: "stop";
     readonly deadlineMs: number;
@@ -39,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;
@@ -48,8 +52,11 @@ export declare class TabBridgeClient {
     accent(accent: string): void;
     session(file: string | null, name: string | null, nameSource?: "default" | "user" | "auto"): void;
     prompt(interrupted: boolean): void;
+    /** Publishes the effective tab shortcut assignments so the host dispatches and labels the same keys. */
+    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;
 }