@timurproko/a1 0.2.7-dev.1232 → 0.2.7-dev.1233

package/dist/composition/owned-ui.js

@@ -1,4 +1,3 @@
-import { SuggestionDiagnosticCapture } from "../features/prompt-suggestions/diagnostics.js";
 import { PRODUCT_IDENTITY } from "../product-identity.js";
 import { PromptHistoryService } from "../features/prompt-history/service.js";
 import { PromptImageSidecar } from "../features/prompt-history/image-sidecar.js";
@@ -19,9 +18,9 @@ import { createOwnedRouteHost } from "./settings-route-host.js";
 import { renderPiShellChangelogLines } from "../integrations/pi/components/shell-presenters-info.js";
 import { nativeHyperlinkStyle } from "../ui/components/spans.js";
 import { ResidentTabRecovery } from "../foundation/resident-tabs/recovery.js";
-import { bindResidentTabBridge, closeResidentUtilityRoute, correlateResidentTabSubmission, currentBackendSessionFile, residentRouteHostOptions, residentTabKeybindings } from "./resident-tab-bridge.js";
+import { bindResidentPresentation, createResidentClientIdentity, closeResidentUtilityRoute, correlateResidentTabSubmission, currentBackendSessionFile, residentRouteHostOptions, residentTabKeybindings } from "./resident-tab-bridge.js";
 import { SessionRuntimeRegistry } from "./session-runtime-registry.js";
-import { readPackageVersion, StartupReleaseNote } from "./startup-route.js";
+import { deferStartupReleaseUpdateObservation, readPackageVersion, StartupReleaseNote } from "./startup-route.js";
 import { createOwnedSettingsManager, watchSharedSettings } from "./owned-settings.js";
 export { bindResidentTabBridge, correlateResidentTabSubmission } from "./resident-tab-bridge.js";
 export function residentStartupPresentation(resident, fallbackNotice) {
@@ -97,6 +96,7 @@ export async function composeOwnedUi(options = {}) {
         await host.dispose();
         throw error;
     }
+    const clientIdentity = createResidentClientIdentity(update => backend.extensions.announceReleaseUpdate(update));
     let recoveryDegraded = false;
     let presentRecoveryDegraded = (_degraded) => { };
     const tabRecovery = options.tab === undefined ? null : new ResidentTabRecovery(options.tab.dataDir, {
@@ -162,7 +162,7 @@ export async function composeOwnedUi(options = {}) {
     };
     const diagnosticDestination = options.suggestionDiagnosticsPath ?? process.env[PRODUCT_IDENTITY.environment.suggestionDiagnostics];
     const suggestionDiagnostics = settings !== null && ownedSurfaces && diagnosticDestination?.trim()
-        ? new SuggestionDiagnosticCapture({ enabled: true, destination: diagnosticDestination }) : null;
+        ? await import("../features/prompt-suggestions/diagnostics.js").then(module => new module.SuggestionDiagnosticCapture({ enabled: true, destination: diagnosticDestination })) : null;
     const promptSuggestions = settings === null || !ownedSurfaces ? null : {
         ...(suggestionDiagnostics === null ? {} : { diagnostics: suggestionDiagnostics }),
         generator: backend,
@@ -234,11 +234,6 @@ export async function composeOwnedUi(options = {}) {
         // Invariant: one terminal host owns the process terminal; the session presenter reaches it only through
         // the host and paints once attached.
         terminalHost = createdTerminalHost = new OwnedUiTerminalHost(sessionTerminalHostOptions(presenterOptions));
-        if (tabBridge !== null) {
-            removeControllerBoundaryInput = terminalHost.runtime.addPreInputListener(data => ({
-                data: tabBridge.consumeControllerBoundaryInput(data),
-            }));
-        }
         presenter = new OwnedUiSessionPresenter(terminalHost, presenterOptions);
         presentRecoveryDegraded = degraded => {
             if (!degraded)
@@ -249,12 +244,11 @@ export async function composeOwnedUi(options = {}) {
         if (recoveryDegraded)
             presentRecoveryDegraded(true);
         terminalHost.attach(presenter);
-        if (tabBridge !== null) {
-            unsubscribeTabBridge = await bindResidentTabBridge(tabBridge, backend, tabRecovery, {
-                autoName: settings?.value("tabsAutoName") ?? true,
-                openRoute: route => presenter.openOwnedRoute(route),
-            });
-        }
+        ({ unsubscribeTabBridge, removeControllerBoundaryInput } = await bindResidentPresentation(tabBridge, backend, tabRecovery, {
+            autoName: settings?.value("tabsAutoName") ?? true,
+            openRoute: route => presenter.openOwnedRoute(route),
+            onClientVersion: clientIdentity.observe,
+        }, terminalHost.runtime));
     }
     catch (error) {
         await createdTerminalHost?.dispose().catch(() => undefined);
@@ -269,13 +263,15 @@ export async function composeOwnedUi(options = {}) {
     // Rationale: pinned Pi's version check is unreachable because the owned shell never runs its
     // InteractiveMode, so A1 checks its own channel. The result is never awaited on the startup path;
     // settings are read here because the runner resolves them only just before start.
-    const releaseUpdates = createStartupReleaseUpdateObservation({
+    const releaseUpdates = deferStartupReleaseUpdateObservation({
         backend,
         configDir: productPaths.configDir,
         mode: settings === null || !ownedSurfaces ? "auto" : settings.value("updateCheck"),
-        packageVersion: releaseNote.packageVersion, notificationVersion: options.notificationVersion,
+        packageVersion: releaseNote.packageVersion, readPackageVersion, notificationVersion: options.notificationVersion,
         checkForNewerRelease: options.checkForNewerRelease,
+        clientVersion: clientIdentity.current,
     });
+    clientIdentity.onChange(releaseUpdates.clientChanged);
     const exitNoticePath = process.env[PRODUCT_IDENTITY.environment.exitNoticePath];
     // Security: tools the agent runs must never see, or rewrite, this instance's notice.
     delete process.env[PRODUCT_IDENTITY.environment.exitNoticePath];
@@ -343,68 +339,6 @@ function createPromptHistoryConfiguration(settings, backend, ownedSurfaces) {
         ...forScope(scope, sessionId),
     };
 }
-function createStartupReleaseUpdateObservation(input) {
-    const controller = new AbortController();
-    let timer;
-    let announcedVersion = null;
-    let eligible = input.mode === "auto";
-    let cadence = null;
-    let nextDelay = null;
-    let started = false;
-    const observe = async () => {
-        // Performance: registry code and its locks stay outside the first-frame startup graph.
-        const releases = await import("../foundation/release/latest-release.js");
-        cadence = releases.UPDATE_CHECK_INTERVAL_MS;
-        nextDelay = cadence;
-        const check = input.checkForNewerRelease ?? releases.checkForNewerRelease;
-        const runningVersion = input.packageVersion ?? await readPackageVersion();
-        const discoveryVersion = input.mode === "notify" ? input.notificationVersion ?? runningVersion : runningVersion;
-        const options = {
-            runningVersion: discoveryVersion,
-            configDir: input.configDir,
-            interactive: process.stdout.isTTY === true,
-            settingMode: input.mode,
-            signal: controller.signal,
-            onNextCheckDelay: milliseconds => { nextDelay = milliseconds; },
-        };
-        // Invariant: opt-outs never arm a recurring timer, nor read the cache or probe the registry.
-        if (input.checkForNewerRelease === undefined && releases.startupReleaseCheckSkipReason(options) !== null) {
-            eligible = false;
-            return;
-        }
-        const release = await check(options);
-        if (release === null || controller.signal.aborted)
-            return;
-        if (input.mode === "notify") {
-            input.backend.extensions.announceReleaseUpdate(release);
-            return;
-        }
-        if (input.mode === "auto") {
-            const installed = await import("../foundation/release/automatic-update.js")
-                .then(module => module.requestAutomaticUpdate({ release, runningVersion, signal: controller.signal }));
-            if (installed !== null && installed !== announcedVersion && !controller.signal.aborted) {
-                announcedVersion = installed;
-                input.backend.extensions.announceReleaseUpdate({ status: "installed", version: installed });
-            }
-        }
-    };
-    const run = async () => {
-        try {
-            await observe();
-        }
-        catch { /* Rationale: best effort; retry on the next interval. */ }
-        if (eligible && cadence !== null && !controller.signal.aborted) {
-            timer = setTimeout(() => { void run(); }, nextDelay ?? cadence);
-            timer.unref?.();
-        }
-    };
-    return {
-        start() { if (started || controller.signal.aborted)
-            return; started = true; void run(); },
-        stop() { controller.abort(); if (timer !== undefined)
-            clearTimeout(timer); },
-    };
-}
 export { watchSharedSettings } from "./owned-settings.js";
 function settingsRouteOptions(tabBridge, keybindings, agentDir, cwd) {
     return {

package/dist/composition/release-update-observation.d.ts

@@ -0,0 +1,22 @@
+import type { AvailableRelease, StartupReleaseCheckOptions, StartupUpdateMode } from "../foundation/release/latest-release.js";
+import type { ComposedSessionBackend } from "./session-backend.js";
+export interface StartupReleaseUpdateObservationOptions {
+    readonly backend: Pick<ComposedSessionBackend, "extensions">;
+    readonly configDir: string;
+    readonly mode: StartupUpdateMode;
+    readonly packageVersion: string | null;
+    readonly readPackageVersion: () => Promise<string>;
+    readonly notificationVersion: string | undefined;
+    readonly checkForNewerRelease: ((options: StartupReleaseCheckOptions) => Promise<AvailableRelease | null>) | undefined;
+    readonly clientVersion?: () => string | null;
+}
+/** Client readiness is unrelated to the retained Agent's engine version or execution lifecycle. */
+declare class ReleaseUpdateObservation {
+    #private;
+    constructor(input: StartupReleaseUpdateObservationOptions);
+    start(): void;
+    stop(): void;
+    clientChanged(): void;
+}
+export declare function createStartupReleaseUpdateObservation(input: StartupReleaseUpdateObservationOptions): ReleaseUpdateObservation;
+export {};

package/dist/composition/release-update-observation.js

@@ -0,0 +1,91 @@
+/** Client readiness is unrelated to the retained Agent's engine version or execution lifecycle. */
+class ReleaseUpdateObservation {
+    #input;
+    #controller = new AbortController();
+    #timer;
+    #announced = null;
+    #eligible;
+    #cadence = null;
+    #nextDelay = null;
+    #started = false;
+    #running = false;
+    #refresh = false;
+    constructor(input) { this.#input = input; this.#eligible = input.mode === "auto"; }
+    async #observe() {
+        // Performance: registry modules and their locks stay outside the first-frame startup graph.
+        const releases = await import("../foundation/release/latest-release.js");
+        this.#cadence = releases.UPDATE_CHECK_INTERVAL_MS;
+        this.#nextDelay = this.#cadence;
+        const input = this.#input;
+        const check = input.checkForNewerRelease ?? releases.checkForNewerRelease;
+        const client = input.clientVersion?.();
+        const runningVersion = client ?? input.packageVersion ?? await input.readPackageVersion();
+        const options = {
+            runningVersion: client ?? (input.mode === "notify" ? input.notificationVersion ?? runningVersion : runningVersion),
+            configDir: input.configDir, interactive: process.stdout.isTTY === true, settingMode: input.mode,
+            signal: this.#controller.signal, onNextCheckDelay: delay => { this.#nextDelay = delay; },
+        };
+        if (input.checkForNewerRelease === undefined && releases.startupReleaseCheckSkipReason(options) !== null) {
+            this.#eligible = false;
+            return;
+        }
+        const release = await check(options);
+        if (release === null || this.#controller.signal.aborted)
+            return;
+        const current = input.clientVersion?.();
+        if (current && !releases.isNewerRelease(release.version, current))
+            return;
+        if (input.mode === "notify") {
+            input.backend.extensions.announceReleaseUpdate(release);
+            return;
+        }
+        if (input.mode !== "auto")
+            return;
+        const installed = await import("../foundation/release/automatic-update.js")
+            .then(module => module.requestAutomaticUpdate({ release, runningVersion, signal: this.#controller.signal }));
+        const actual = input.clientVersion?.();
+        if (installed === null || installed === this.#announced || this.#controller.signal.aborted
+            || actual && !releases.isNewerRelease(installed, actual))
+            return;
+        this.#announced = installed;
+        input.backend.extensions.announceReleaseUpdate({ status: "installed", version: installed });
+    }
+    async #run() {
+        if (this.#running) {
+            this.#refresh = true;
+            return;
+        }
+        this.#running = true;
+        try {
+            await this.#observe();
+        }
+        catch { /* Rationale: observation is best effort and never interrupts execution. */ }
+        this.#running = false;
+        if (this.#refresh && !this.#controller.signal.aborted) {
+            this.#refresh = false;
+            void this.#run();
+            return;
+        }
+        if (this.#eligible && this.#cadence !== null && !this.#controller.signal.aborted) {
+            this.#timer = setTimeout(() => { void this.#run(); }, this.#nextDelay ?? this.#cadence);
+            this.#timer.unref?.();
+        }
+    }
+    start() {
+        if (this.#started || this.#controller.signal.aborted)
+            return;
+        this.#started = true;
+        void this.#run();
+    }
+    stop() { this.#controller.abort(); if (this.#timer !== undefined)
+        clearTimeout(this.#timer); }
+    clientChanged() {
+        this.#announced = null;
+        if (!this.#started || this.#controller.signal.aborted || this.#input.mode === "no")
+            return;
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        void this.#run();
+    }
+}
+export function createStartupReleaseUpdateObservation(input) { return new ReleaseUpdateObservation(input); }

package/dist/composition/resident-tab-bridge.d.ts

@@ -1,3 +1,4 @@
+import type { OwnedUiReleaseUpdate } from "../contracts/owned-ui/index.js";
 import type { TabBridgeClient } from "../foundation/resident-tabs/bridge-client.js";
 import { type ResidentTabRoute } from "../foundation/resident-tabs/routes.js";
 import type { ResidentTabRecovery } from "../foundation/resident-tabs/recovery.js";
@@ -20,6 +21,21 @@ export declare function closeResidentUtilityRoute(tabBridge: Pick<TabBridgeClien
 export declare function bindResidentTabBridge(tabBridge: TabBridgeClient, backend: Pick<ComposedSessionBackend, "identity" | "session" | "workflows" | "generateResidentTabName">, recovery?: Pick<ResidentTabRecovery, "settled"> | null, options?: {
     readonly autoName?: boolean;
     readonly openRoute?: (route: ResidentTabRoute) => void;
+    readonly onClientVersion?: (version: string) => void;
 }): Promise<() => void>;
+export declare function createResidentClientIdentity(announce: (update: OwnedUiReleaseUpdate) => void): {
+    current: () => string | null;
+    onChange: (listener: () => void) => void;
+    observe: (next: string) => void;
+};
+/** Input ownership is established before the presenter starts, and released if bridge binding fails. */
+export declare function bindResidentPresentation(bridge: TabBridgeClient | null, backend: Parameters<typeof bindResidentTabBridge>[1], recovery: Parameters<typeof bindResidentTabBridge>[2], options: Parameters<typeof bindResidentTabBridge>[3], input: {
+    addPreInputListener(listener: (data: string) => {
+        data: string;
+    }): () => void;
+}): Promise<{
+    unsubscribeTabBridge: () => void;
+    removeControllerBoundaryInput: () => void;
+}>;
 export declare function correlateResidentTabSubmission(recovery: Pick<ResidentTabRecovery, "correlated" | "settled">, backend: Pick<ComposedSessionBackend, "identity" | "session">, submissionId: string, entryId: string): Promise<void>;
 export declare function currentBackendSessionFile(backend: Pick<ComposedSessionBackend, "identity">): string | null;

package/dist/composition/resident-tab-bridge.js

@@ -112,22 +112,8 @@ export async function bindResidentTabBridge(tabBridge, backend, recovery = null,
         }), false, pendingRequests, queuedInput);
     };
     announceSession();
-    const unsubscribeCommands = typeof tabBridge.onCommand === "function" ? tabBridge.onCommand(command => {
-        // Invariant: visibility stays decoded for generation-1 peers but never pauses rendering; a hidden tab
-        // keeps its resident terminal current while the holder withholds only its client surfaces.
-        if (command.type === "rename") {
-            void backend.workflows.executeWorkflow({ command: "name", argument: command.name }).catch(() => { });
-        }
-        else if (command.type === "route") {
-            if (options.openRoute !== undefined)
-                options.openRoute(command.route);
-            else
-                void backend.workflows.executeWorkflow({ command: command.route, argument: "" }).catch(() => { });
-        }
-        else if (command.type === "stop") {
-            void backend.session.dispose().catch(() => { });
-        }
-    }) : () => { };
+    const unsubscribeCommands = typeof tabBridge.onCommand === "function"
+        ? tabBridge.onCommand(command => applyBridgeCommand(command, backend, options)) : () => { };
     const unsubscribeEvents = backend.session.onEvent(event => {
         if (event.type === "session-lifecycle") {
             const wasWorking = working;
@@ -163,6 +149,49 @@ export async function bindResidentTabBridge(tabBridge, backend, recovery = null,
         unsubscribeEvents();
     };
 }
+function applyBridgeCommand(command, backend, options) {
+    // Invariant: visibility never pauses resident rendering or autonomous work.
+    if (command.type === "client")
+        options.onClientVersion?.(command.version);
+    else if (command.type === "rename")
+        void backend.workflows.executeWorkflow({ command: "name", argument: command.name }).catch(() => { });
+    else if (command.type === "route") {
+        if (options.openRoute !== undefined)
+            options.openRoute(command.route);
+        else
+            void backend.workflows.executeWorkflow({ command: command.route, argument: "" }).catch(() => { });
+    }
+    else if (command.type === "stop")
+        void backend.session.dispose().catch(() => { });
+}
+export function createResidentClientIdentity(announce) {
+    let version = null;
+    let changed;
+    return {
+        current: () => version,
+        onChange: (listener) => { changed = listener; },
+        observe: (next) => {
+            if (next === version)
+                return;
+            version = next;
+            announce({ status: "client-connected", version: next });
+            changed?.();
+        },
+    };
+}
+/** Input ownership is established before the presenter starts, and released if bridge binding fails. */
+export async function bindResidentPresentation(bridge, backend, recovery, options, input) {
+    if (bridge === null)
+        return { unsubscribeTabBridge() { }, removeControllerBoundaryInput() { } };
+    const removeControllerBoundaryInput = input.addPreInputListener(data => ({ data: bridge.consumeControllerBoundaryInput(data) }));
+    try {
+        return { unsubscribeTabBridge: await bindResidentTabBridge(bridge, backend, recovery, options), removeControllerBoundaryInput };
+    }
+    catch (error) {
+        removeControllerBoundaryInput();
+        throw error;
+    }
+}
 export async function correlateResidentTabSubmission(recovery, backend, submissionId, entryId) {
     await recovery.correlated(submissionId, entryId);
     // Concurrency: a normal prompt command can resolve after the ready transition already fired.

package/dist/composition/startup-route.d.ts

@@ -1,5 +1,6 @@
 import type { OwnedUiShellEngineOptions } from "../app/session-shell/index.js";
 import type { ReleaseNoteCatalog } from "../features/owned-ui/release-notes.js";
+import type { StartupReleaseUpdateObservationOptions } from "./release-update-observation.js";
 type StartupRoute = NonNullable<OwnedUiShellEngineOptions["startupRoute"]>;
 export interface StartupReleaseNoteOptions {
     readonly ownedSurfaces: boolean;
@@ -11,6 +12,13 @@ export interface StartupReleaseNoteOptions {
     readonly configDir: string;
 }
 export declare function readPackageVersion(): Promise<string>;
+type UpdateObservationModule = Pick<typeof import("./release-update-observation.js"), "createStartupReleaseUpdateObservation">;
+/** Optional update checks load after first paint; disposal also fences an unfinished module load. */
+export declare function deferStartupReleaseUpdateObservation(options: StartupReleaseUpdateObservationOptions, load?: () => Promise<UpdateObservationModule>): {
+    start(): void;
+    stop(): void;
+    clientChanged(): void;
+};
 /**
  * The release notes bare A1 ships and the one note this version shows once per profile on startup:
  * the packaged catalog (or why it could not be read), the running version, and the claim that

package/dist/composition/startup-route.js

@@ -6,6 +6,26 @@ export async function readPackageVersion() {
         throw new Error("A1 package version is unavailable");
     return version;
 }
+/** Optional update checks load after first paint; disposal also fences an unfinished module load. */
+export function deferStartupReleaseUpdateObservation(options, load = () => import("./release-update-observation.js")) {
+    let observation;
+    let started = false, stopped = false;
+    return {
+        start() {
+            if (started || stopped)
+                return;
+            started = true;
+            void load().then(module => {
+                if (stopped)
+                    return;
+                observation = module.createStartupReleaseUpdateObservation(options);
+                observation.start();
+            }).catch(() => { });
+        },
+        stop() { stopped = true; observation?.stop(); },
+        clientChanged() { observation?.clientChanged(); },
+    };
+}
 /**
  * The release notes bare A1 ships and the one note this version shows once per profile on startup:
  * the packaged catalog (or why it could not be read), the running version, and the claim that

package/dist/contracts/owned-ui/session-workflows.d.ts

@@ -339,6 +339,9 @@ export interface OwnedUiVisualExtensionSupport {
 }
 /** A newer release found by the startup check, or one installed for the next restart. */
 export type OwnedUiReleaseUpdate = {
+    readonly status: "client-connected";
+    readonly version: string;
+} | {
     readonly status?: "available";
     readonly version: string;
     readonly command: string;

package/dist/foundation/release/bootstrap.js

@@ -19,7 +19,7 @@ import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDoc
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { markStartupPhase } from "../startup/index.js";
 import { PRIVATE_ENVIRONMENT, isCurrentLaunchContract, launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
-import { ensureTerminalHost, readResidentTabLaunchSettings, selectResidentHost } from "../resident-tabs/index.js";
+import { assertResidentContinuity, ensureTerminalHost, readResidentTabLaunchSettings, selectResidentHost } from "../resident-tabs/index.js";
 const RELEASE_RESELECTION_MESSAGE = "a1-release-reselection";
 export async function runBootstrap(options) {
     return await runBootstrapAttempt(options, 1);
@@ -38,41 +38,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     const paths = resolveProductPaths(environment);
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const launchSelected = async (release) => {
-        let residentContext = {};
-        // Compatibility: public launch preparation supplies PI_CODING_AGENT_DIR; the fallback keeps
-        // direct SDK/bootstrap callers hermetic while retaining their former config-root read.
-        const agentProfileDir = environment.PI_CODING_AGENT_DIR ?? paths.configDir;
-        const residentLaunchSettings = launchProfileId === "a1"
-            ? readResidentTabLaunchSettings(agentProfileDir, PRODUCT_IDENTITY.commandName, paths.configDir, launchProfileId)
-            : null;
-        const resident = await selectResidentHost({
-            profileId: launchProfileId,
-            currentLaunchContract: isCurrentLaunchContract(release),
-            solo: launchMode === "solo",
-            interactive: options.interactiveTerminal ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
-            ensureHost: async () => (options.ensureTerminalHost ?? ensureTerminalHost)({
-                releaseRoot: release.releaseRoot,
-                profileRoot: environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
-                dataDir: paths.dataDir,
-                runtimeDir: paths.runtimeDir,
-                environment,
-                maxConcurrentStarts: (await residentLaunchSettings).maxConcurrentStarts,
-                unresponsiveRestartSeconds: (await residentLaunchSettings).unresponsiveRestartSeconds,
-            }),
-        });
-        if (resident !== null) {
-            residentContext = resident.status === "ready" ? {
-                residentRootExecutable: resident.executable.executable,
-                residentRootArguments: JSON.stringify([
-                    resident.executable.entry,
-                    "attach", "--endpoint", resident.endpoint, "--cwd", process.cwd(), "--clear-exit-ms", String(RESIDENT_DETACH_INTERVAL_MS),
-                    "--profile", environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
-                    "--settings-file", resolve(agentProfileDir, "settings.json"), "--accent-color", (await residentLaunchSettings).accentColor,
-                    "--data-dir", paths.dataDir, "--runtime-dir", paths.runtimeDir,
-                    "--release-root", release.releaseRoot, "--node-executable", process.execPath,
-                ]),
-            } : { residentFallback: resident.reason };
-        }
+        const residentContext = await residentLaunchContext(options, release, environment);
         const result = await launchUi(release, environment, sessionArgs, residentContext);
         if (!result.releaseSuperseded)
             return result.code;
@@ -218,6 +184,16 @@ async function runBootstrapAttempt(options, retriesRemaining) {
         const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
         await stateStore.approve(candidate.releaseId, diagnosticsPath);
     }
+    try {
+        await assertResidentContinuity({ releaseRoot: candidate.releaseRoot, dataDir: paths.dataDir, environment,
+            profileRoot: environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir, runtimeDir: paths.runtimeDir });
+    }
+    catch (error) {
+        const fallback = await launchRetainedActive(await stateStore.read(), paths, environment, launchSelected, excludedRetainedReleaseId);
+        if (fallback !== null)
+            return fallback;
+        throw error;
+    }
     state = await stateStore.activateForLaunch(candidate.releaseId, !activeIsLaunchable ? activeId ?? undefined : undefined);
     if (state.references.active !== candidate.releaseId) {
         const retainedRecord = state.references.active === null ? undefined : state.releases[state.references.active];
@@ -312,6 +288,38 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     await ensureSupervisor(selected, environment);
     return await launchSelected(selected);
 }
+/** Select only client routing; a resident reconnect never asks execution to restart. */
+async function residentLaunchContext(options, release, environment) {
+    const paths = resolveProductPaths(environment);
+    const profileId = options.launchIntent?.profileId ?? "a1";
+    const mode = options.launchIntent?.launchMode ?? (profileId === "a1" ? "tabs" : "solo");
+    const agentProfileDir = environment.PI_CODING_AGENT_DIR ?? paths.configDir;
+    const residentLaunchSettings = profileId === "a1" ? readResidentTabLaunchSettings(agentProfileDir, PRODUCT_IDENTITY.commandName, paths.configDir, profileId) : null;
+    const resident = await selectResidentHost({
+        profileId, currentLaunchContract: isCurrentLaunchContract(release), solo: mode === "solo",
+        interactive: options.interactiveTerminal ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
+        ensureHost: async () => (options.ensureTerminalHost ?? ensureTerminalHost)({
+            releaseRoot: release.releaseRoot, profileRoot: environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
+            dataDir: paths.dataDir, runtimeDir: paths.runtimeDir, environment,
+            maxConcurrentStarts: (await residentLaunchSettings).maxConcurrentStarts, unresponsiveRestartSeconds: (await residentLaunchSettings).unresponsiveRestartSeconds,
+        }),
+    });
+    if (resident === null)
+        return {};
+    if (resident.status !== "ready")
+        return { residentFallback: resident.reason };
+    return {
+        residentRootExecutable: resident.executable.executable,
+        residentRootArguments: JSON.stringify([
+            resident.executable.entry, "attach", "--workspace", "--endpoint", resident.endpoint,
+            "--cwd", process.cwd(), "--clear-exit-ms", String(RESIDENT_DETACH_INTERVAL_MS),
+            "--profile", environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir,
+            "--settings-file", resolve(agentProfileDir, "settings.json"), "--accent-color", (await residentLaunchSettings).accentColor,
+            "--data-dir", paths.dataDir, "--runtime-dir", paths.runtimeDir,
+            "--release-root", release.releaseRoot, "--node-executable", process.execPath,
+        ]),
+    };
+}
 /**
  * Start the retained active cohort when the installed payload cannot be taken. The
  * release already carries certified evidence, so this reuses it rather than
@@ -493,6 +501,8 @@ async function activatePendingAfterBlockerExit(candidate, stateStore, paths, env
         return;
     const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
     await stateStore.approve(candidate.releaseId, diagnosticsPath);
+    await assertResidentContinuity({ releaseRoot: candidate.releaseRoot, dataDir: paths.dataDir, environment,
+        profileRoot: environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir, runtimeDir: paths.runtimeDir });
     if (!await requestIdleOwnershipRelease(endpoint, candidate.releaseId, 2_000))
         return;
     if (!await releaseVerifiedIdleOwner(endpoint, paths.dataDir))

package/dist/foundation/release/update-activation.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { PRODUCT_TEXT } from "../../product-identity.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { certifyMaterializedRelease, ensureSupervisor } from "./bootstrap.js";
 import { CohortStateStore } from "./cohort-state.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
@@ -51,8 +51,14 @@ export async function activateInstalledRelease(request, callbacks) {
     callbacks.onWarmup?.("started");
     await warmMaterializedRelease(candidate, request.environment);
     callbacks.onWarmup?.("completed");
+    const { assertResidentContinuity } = await import("../resident-tabs/index.js");
+    const paths = resolveProductPaths(request.environment);
+    const continuity = { releaseRoot: candidate.releaseRoot, dataDir: request.dataDir, environment: request.environment,
+        profileRoot: request.environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir, runtimeDir: paths.runtimeDir };
+    await assertResidentContinuity(continuity);
     await ensureSupervisor(candidate, request.environment);
-    // Invariant: warmup and authenticated readiness precede changing the active reference.
+    // Invariant: revalidate after supervision, before committing client activation or restart readiness.
+    await assertResidentContinuity(continuity);
     await stateStore.activate(candidate.releaseId);
     await callbacks.phase("active-reference-committed");
 }

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

@@ -14,6 +14,9 @@ export interface TabAttachment {
 export type TabBridgeCommand = {
     readonly type: "visibility";
     readonly visible: boolean;
+} | {
+    readonly type: "client";
+    readonly version: string;
 } | {
     readonly type: "rename";
     readonly name: string;

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

@@ -71,7 +71,7 @@ export class TabBridgeClient {
             transport.once("connect", () => {
                 this.#send("hello", {
                     role: "bridge", generation: 1, build: this.#options.build ?? "a1", releaseId: this.#options.credentials.releaseId,
-                    features: ["bridge-status", "bridge-detach", "bridge-heartbeat", "bridge-restart", "bridge-visibility", "bridge-rename", "bridge-route", "bridge-stop", "bridge-shortcuts", "controller-boundary", "recovery-journal"],
+                    features: ["bridge-status", "bridge-detach", "bridge-heartbeat", "bridge-restart", "bridge-visibility", "bridge-rename", "bridge-route", "bridge-stop", "bridge-shortcuts", "controller-boundary", "recovery-journal", "client-identity"],
                     token: [...Buffer.from(this.#options.credentials.token, "base64")], tabId: this.#options.credentials.tabId,
                     pid: this.#options.pid ?? process.pid, startIdentity: this.#options.startIdentity ?? `${process.pid}:node`,
                 }, ++this.#request);
@@ -231,6 +231,12 @@ export class TabBridgeClient {
             this.#fail();
             return;
         }
+        if (message.type === "bridge.client" && typeof message.body["version"] === "string") {
+            const version = message.body["version"];
+            if (version.length <= 128 && /^\d+\.\d+\.\d+(?:[-+][a-z0-9.+-]+)?$/iu.test(version))
+                this.#emitCommand({ type: "client", version });
+            return;
+        }
         if (message.type === "bridge.visibility" && typeof message.body["visible"] === "boolean") {
             this.#emitCommand({ type: "visibility", visible: message.body["visible"] });
             return;

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

@@ -0,0 +1,12 @@
+export interface ContinuityOptions {
+    readonly releaseRoot: string;
+    readonly dataDir: string;
+    readonly profileRoot: string;
+    readonly runtimeDir: string;
+    readonly environment: NodeJS.ProcessEnv;
+    readonly inspect?: (options: Omit<ContinuityOptions, "inspect">) => Promise<string>;
+}
+/** Activation authority requires a stable authenticated source-contract set, never an idle Agent. */
+export declare function assertResidentContinuity(options: ContinuityOptions): Promise<void>;
+/** Native inspection/import is read-only toward execution and never starts or stops a source. */
+export declare function inspectResidentContinuity(options: Omit<ContinuityOptions, "inspect">): Promise<string>;