@timurproko/a1 0.2.6 → 0.2.7-dev.746

package/bin/guardian.js

@@ -16,8 +16,13 @@ const profileId = readLaunchContext(process.env, "profile").launchProfile;
 if (releaseRoot === undefined || profileId === undefined) throw new Error("A1 launch context is incomplete");
 
 const sessionSelection = parseSessionSelection(process.argv.slice(2));
+const rootCommand = launchContext.residentRootExecutable === undefined ? undefined : {
+  executable: launchContext.residentRootExecutable,
+  arguments: JSON.parse(launchContext.residentRootArguments ?? "[]"),
+};
 Promise.resolve().then(() => runLaunchGuardian({
   ...(sessionSelection === undefined ? {} : { sessionSelection }),
+  ...(rootCommand === undefined ? {} : { rootCommand }),
   profileId,
   releaseRoot,
   uiEntry: resolve(releaseRoot, "bin", "ui.js"),

package/bin/tab-launch-context.d.ts

@@ -0,0 +1,18 @@
+export interface TabLaunchCredentials {
+  readonly tabId: string;
+  readonly token: string;
+  readonly endpoint: string;
+}
+
+export function formatResidentFallbackNotice(reason: string): string;
+
+export function assignFreshSessionRuntimeId(
+  environment: Record<string, string | undefined>,
+  name: string,
+  createId: () => string,
+): string;
+
+export function consumeTabLaunchContext(
+  arguments_: readonly string[],
+  environment: Record<string, string | undefined>,
+): { readonly uiArguments: string[]; readonly tabCredentials: TabLaunchCredentials | undefined };

package/bin/tab-launch-context.js

@@ -0,0 +1,36 @@
+const TAB_ENVIRONMENT_NAMES = ["A1_TAB_ID", "A1_TAB_TOKEN", "A1_TAB_ENDPOINT"];
+
+/** @param {string} reason */
+export function formatResidentFallbackNotice(reason) {
+  return `Resident tabs unavailable (${reason}); running a single agent.`;
+}
+
+/**
+ * @param {Record<string, string | undefined>} environment
+ * @param {string} name
+ * @param {() => string} createId
+ */
+export function assignFreshSessionRuntimeId(environment, name, createId) {
+  const id = createId();
+  if (typeof id !== "string" || id.length === 0 || id.includes("\0")) throw new Error("Session runtime identity generation failed");
+  environment[name] = id;
+  return id;
+}
+
+/**
+ * Security: consume bridge credentials into caller-private memory and erase their inheritable
+ * environment entries before any extension-capable module loads.
+ * @param {readonly string[]} arguments_
+ * @param {Record<string, string | undefined>} environment
+ */
+export function consumeTabLaunchContext(arguments_, environment) {
+  const uiArguments = [...arguments_];
+  const tabArgument = uiArguments.indexOf("--tab");
+  const tabMode = tabArgument !== -1;
+  if (tabMode) uiArguments.splice(tabArgument, 1);
+  const [tabId, token, endpoint] = TAB_ENVIRONMENT_NAMES.map(name => environment[name]);
+  for (const name of TAB_ENVIRONMENT_NAMES) delete environment[name];
+  if (!tabMode) return { uiArguments, tabCredentials: undefined };
+  if (!tabId || !token || !endpoint) throw new Error("A1 tab mode requires bridge credentials");
+  return { uiArguments, tabCredentials: { tabId, token, endpoint } };
+}

package/bin/ui.js

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
 
+// Security: this helper has no A1, Pi, tool, or extension dependency and erases credentials before those modules load.
+const { assignFreshSessionRuntimeId, consumeTabLaunchContext, formatResidentFallbackNotice } = await import("./tab-launch-context.js");
+const { uiArguments, tabCredentials } = consumeTabLaunchContext(process.argv.slice(2), process.env);
+
 // Invariant: one terminal module identity per process, decided before any A1 or Pi module loads.
 const { installPinnedPiTuiResolver } = await import("./module-resolver.js");
 installPinnedPiTuiResolver(new URL("..", import.meta.url).pathname.replace(/^\/(.:)/, "$1").replace(/\/$/, ""));
@@ -14,7 +18,7 @@ if (profile === "a1") {
     import("node:crypto"),
     import("../dist/product-identity.js"),
   ]);
-  process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] = randomUUID();
+  assignFreshSessionRuntimeId(process.env, PRODUCT_IDENTITY.environment.sessionRuntimeId, randomUUID);
 }
 const { installFatalExit } = await import("../dist/foundation/terminal-cleanup/fatal-exit.js");
 const { resolveProductPaths } = await import("../dist/foundation/lifecycle/paths.js");
@@ -51,8 +55,11 @@ const [
 identity.assertSinglePiTuiModuleAtLaunch(packageRootPath, (/** @type {string} */ message) => process.stderr.write(message));
 await startup.markStartupPhase(process.env, "ui-modules-loaded");
 
-const sessionSelection = parseSessionSelection(process.argv.slice(2));
-Promise.resolve().then(() => {
+const sessionSelection = parseSessionSelection(uiArguments);
+Promise.resolve().then(async () => {
+  const tab = tabCredentials === undefined ? undefined : {
+    bridge: new (await import("../dist/foundation/resident-tabs/bridge-client.js")).TabBridgeClient({ credentials: tabCredentials }),
+  };
   if (sessionSelection && profile !== "a1") throw new Error("session selection requires the normal A1 profile");
   return runSelectedInteractiveRuntime(profile, {
     ownedUi: async (profileId, ownedSurfaces) => {
@@ -69,6 +76,10 @@ Promise.resolve().then(() => {
         projectTrustPrompt: createConsoleProjectTrustPrompt({ presentation: profile === "a1" ? "bare" : "comparison" }),
         sessionForkPrompt: createConsoleSessionForkPrompt(),
         ...(sessionSelection === undefined ? {} : { sessionSelection }),
+        ...(tab === undefined ? {} : { tab }),
+        ...(launchContext.residentFallback === undefined ? {} : {
+          residentFallbackNotice: formatResidentFallbackNotice(launchContext.residentFallback),
+        }),
       });
       runningApplication = application;
       return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });

package/dist/app/session-shell/helper-pool.d.ts

@@ -12,16 +12,14 @@ export interface HelperPoolOptions {
     readonly stop: (child: ChildProcess) => void;
     readonly idleMs?: number;
 }
-/**
- * Keeps one forked IPC helper ready so a request takes a live child instead of paying fork and module
- * load on its own critical path. The spare stays idle on its channel until it is taken; a spare that
- * exits or idles too long is dropped, and the next request forks cold and warms a replacement afterwards.
- */
+/** Holds one idle IPC helper; requests take it, and exits, expiry, or use trigger replacement. */
 export declare class HelperPool {
     #private;
     constructor(options: HelperPoolOptions);
     /** Whether a spare is currently held (ready or still starting). */
     get warmed(): boolean;
+    /** Whether the held spare has announced that module loading is complete. */
+    get ready(): boolean;
     /** Opts the pool in and forks the first spare; from here on `replenish` keeps one ready after each request. */
     warm(): void;
     /** Forks the next spare after a request released its child; a no-op until the owner warmed the pool. A fork failure leaves the pool empty. */

package/dist/app/session-shell/helper-pool.js

@@ -1,10 +1,6 @@
 /** How long an unused spare helper may idle before it is stopped so a background session holds no extra process. */
 export const HELPER_SPARE_IDLE_MS = 5 * 60_000;
-/**
- * Keeps one forked IPC helper ready so a request takes a live child instead of paying fork and module
- * load on its own critical path. The spare stays idle on its channel until it is taken; a spare that
- * exits or idles too long is dropped, and the next request forks cold and warms a replacement afterwards.
- */
+/** Holds one idle IPC helper; requests take it, and exits, expiry, or use trigger replacement. */
 export class HelperPool {
     #fork;
     #stop;
@@ -19,6 +15,8 @@ export class HelperPool {
     }
     /** Whether a spare is currently held (ready or still starting). */
     get warmed() { return this.#spare !== undefined; }
+    /** Whether the held spare has announced that module loading is complete. */
+    get ready() { return this.#spare?.ready === true; }
     /** Opts the pool in and forks the first spare; from here on `replenish` keeps one ready after each request. */
     warm() {
         if (this.#disposed)

package/dist/app/session-shell/session-shell-root.d.ts

@@ -43,6 +43,11 @@ export interface OwnedUiShellEngineOptions {
     };
     /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
     readonly sessionLayout?: "pinned" | "custom-viewport";
+    /** Resident tab quit routes detach the outer client without stopping this engine session. */
+    readonly residentTab?: {
+        requestDetach(): Promise<boolean>;
+        readonly unavailableNotice?: string;
+    };
 }
 /** Terminal, startup, viewport, and presentation-cadence seams; production leaves most at their defaults. */
 export interface OwnedUiShellPresentationOptions {
@@ -182,7 +187,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly onPromptSuggestionAccepted?: (text: string) => void;
         readonly onInputSurfaceChanged?: () => void;
         readonly onPromptSuggestionEligibilityChanged?: () => void;
-        readonly onCopyText?: (text: string) => void;
+        readonly onCopyText?: (text: string, cut: boolean) => void;
         readonly readClipboardContent?: (signal?: AbortSignal) => Promise<PiShellClipboardContent | null>;
         readonly captureClipboardPaste?: () => PasteSource;
         readonly pasteDiagnostics?: (event: PasteEvent) => void;

package/dist/app/session-shell/session-shell-root.js

@@ -458,7 +458,7 @@ export class OwnedUiSessionShellRoot {
             && snapshot.inputSurface === inputSurface
             && snapshot.viewportRevision === viewportRevision
             && snapshot.selectionRevision === selectionRevision
-            ? this.#viewportController.composeDockOnly(dockRows, width, height)
+            ? this.#viewportController.composeDockOnly(dockRows, width, height, dock.footerRows)
             : null;
         if (frame === null) {
             frame = this.#viewportController.compose({
@@ -474,6 +474,7 @@ export class OwnedUiSessionShellRoot {
                 ...(document.liveTailStartRow === undefined ? {} : { liveTailStartRow: document.liveTailStartRow }),
                 bottomAlignedTailRowCount: steeringRows.length + statusRows.length,
                 dockRows,
+                explicitCopyDockRows: dock.footerRows,
                 promptAnchors: document.promptAnchors,
                 width,
                 height,
@@ -603,7 +604,6 @@ export class OwnedUiSessionShellRoot {
         const transientRows = [...queued, ...statusRows, ...this.#renderDockNotice(width)];
         const aboveWidgets = this.#renderWidgets("aboveEditor", width);
         const input = this.#inputSurface.render(width);
-        // Invariant: pointer rows describe the body, not the autocomplete block now preceding it.
         const body = this.usesDefaultInputSurface() ? this.editor.bodyGeometry?.() : undefined;
         const belowWidgets = this.#renderWidgets("belowEditor", width);
         const footer = this.#renderFooter(width);
@@ -614,6 +614,7 @@ export class OwnedUiSessionShellRoot {
             inputOffset,
             editorOffset: inputOffset + (body?.rowOffset ?? 0),
             inputRows: body?.rowCount ?? input.length,
+            footerRows: footer.length,
         };
     }
     #renderCopyAcknowledgement(width) {

package/dist/app/session-shell/session-shell.js

@@ -3,7 +3,7 @@ import { createResponseCopyExecutor, hasAsyncClipboardOutput, responseCopyDestin
 import { MAX_COPY_CONTROL_BYTES } from "./response-copy-protocol.js";
 import { PromptHistoryController } from "./prompt-history-controller.js";
 import { PRODUCT_TEXT } from "../../product-identity.js";
-import { boundedCleanup } from "../../foundation/terminal-cleanup/terminal-reset.js";
+import { CLEAR_EXIT_INTERVAL_MS, boundedCleanup } from "../../foundation/terminal-cleanup/terminal-reset.js";
 import { assertOwnedUiCommand, OWNED_UI_HIDDEN_COMMAND_NAMES } from "../../contracts/owned-ui/index.js";
 import { assertPromptImages, ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 import { ContextualPromptSuggestionController } from "./prompt-suggestion-controller.js";
@@ -34,6 +34,7 @@ export class OwnedUiSessionPresenter {
     #host;
     #terminal;
     #cwd;
+    #residentTabOptions;
     #listeners = new Set();
     #unsubscribe;
     #unsubscribePromptSuggestions;
@@ -104,6 +105,7 @@ export class OwnedUiSessionPresenter {
         this.#sessionBindingGeneration = this.backend.identity.sessionBindingGeneration;
         this.#suggestionModelKey = modelKey(this.backend.session.view());
         this.#cwd = cwd;
+        this.#residentTabOptions = options.engine.residentTab;
         this.#routeHost = routeHost ?? null;
         this.#startupRoute = options.engine.startupRoute;
         this.#customViewport = sessionLayout === "custom-viewport";
@@ -218,9 +220,9 @@ export class OwnedUiSessionPresenter {
                     promptSuggestionController?.invalidate();
                     this.#promptHistory?.synchronize();
                 },
-                onCopyText: text => {
+                onCopyText: (text, cut) => {
                     if (this.#responseCopy !== null) {
-                        void this.#responseCopy.submitText(text);
+                        this.#trackCopy(this.#responseCopy.submitText(text), cut ? undefined : text.length);
                         return;
                     }
                     const write = () => {
@@ -626,21 +628,21 @@ export class OwnedUiSessionPresenter {
         const routed = this.root.handleViewportPreInput(data, true, Date.now(), this.root.usesDefaultInputSurface() && !this.#terminal.hasFocusedOverlay());
         if (routed.copySelection !== undefined) {
             const snapshot = routed.copySelection;
-            const acknowledgement = copyAcknowledgement(snapshot);
-            const intent = ++this.#copyIntentSequence;
-            void this.#responseCopy?.submit(snapshot, this.#pendingClipboardWrite).then(result => {
-                if (this.#disposed || !this.#terminal.running || intent !== this.#copyIntentSequence
-                    || result.outcome !== "delivered" && result.outcome !== "submitted-unverified")
-                    return;
-                if (acknowledgement.hasNonWhitespace) {
-                    this.root.showCopyAcknowledgement(`copied ${acknowledgement.characters} chars to clipboard`);
-                }
-            });
+            this.#trackCopy(this.#responseCopy?.submit(snapshot, this.#pendingClipboardWrite), copyCharacters(snapshot));
         }
         if (!routed.consumed)
             return routed.data === data ? undefined : { data: routed.data };
         return routed.data.length === 0 ? { consume: true } : { data: routed.data };
     }
+    #trackCopy(delivery, count) {
+        const intent = ++this.#copyIntentSequence;
+        void delivery?.then(({ outcome }) => {
+            if (count === undefined || this.#disposed || !this.#terminal.running || intent !== this.#copyIntentSequence
+                || outcome !== "delivered" && outcome !== "submitted-unverified")
+                return;
+            this.root.showCopyAcknowledgement(`copied ${count} chars to clipboard`);
+        });
+    }
     #promptSuggestionPresentationBlockReason(identity) {
         const view = this.view();
         if (this.#disposed)
@@ -795,7 +797,7 @@ export class OwnedUiSessionPresenter {
     }
     async clearOrExit(now = Date.now()) {
         this.#promptSuggestions?.abortPending();
-        if (now - this.#lastClearTime < 500)
+        if (now - this.#lastClearTime < CLEAR_EXIT_INTERVAL_MS)
             return this.shutdown();
         this.root.editor.setText("");
         this.#lastClearTime = now;
@@ -1149,10 +1151,23 @@ export class OwnedUiSessionPresenter {
         this.#presenters.openSettingsSelector(this.#dialogHost);
     }
     shutdown() {
-        this.#shutdownPromise ??= this.#shutdown();
+        this.#shutdownPromise ??= this.#shutdown().finally(() => {
+            // Invariant: a rejected resident detach is retryable; ordinary shutdown has disposed the shell already.
+            if (!this.#disposed)
+                this.#shutdownPromise = undefined;
+        });
         return this.#shutdownPromise;
     }
     async #shutdown() {
+        const residentTab = this.#residentTab();
+        if (residentTab !== undefined) {
+            const detached = await residentTab.requestDetach().catch(() => false);
+            if (detached)
+                return { outcome: "completed", diagnostic: null };
+            this.root.appendWorkflowStatus(residentTab.unavailableNotice ?? "Press Ctrl+C twice to leave; this agent keeps running.");
+            this.#terminal.requestRender();
+            return rejected("resident tab detach is unavailable");
+        }
         try {
             const quit = this.backend.workflows.executeWorkflow({ command: "quit", argument: "" });
             // Invariant: a slow or hung engine quit never holds the terminal past the cleanup deadline. The
@@ -1168,6 +1183,9 @@ export class OwnedUiSessionPresenter {
             this.#resolveStoppedLifecycle();
         }
     }
+    #residentTab() {
+        return this.#residentTabOptions;
+    }
     async runWorkflow(request) {
         if (request.command === "quit")
             return this.shutdown();
@@ -1920,16 +1938,15 @@ export class OwnedUiSessionShell extends OwnedUiSessionPresenter {
 function isCoalescedStreamBlock(kind) {
     return kind === "assistant" || kind === "thinking" || kind === "tool-call" || kind === "tool-result";
 }
-function copyAcknowledgement(snapshot) {
+function copyCharacters(snapshot) {
     if (snapshot.literal !== true)
-        return { characters: snapshot.sourceUnits, hasNonWhitespace: true };
-    let characters = Math.max(0, snapshot.rows.length - 1);
-    let hasNonWhitespace = false;
-    for (const row of snapshot.rows) {
-        characters += row.text.length;
-        hasNonWhitespace ||= /\S/u.test(row.text);
-    }
-    return { characters, hasNonWhitespace };
+        return snapshot.sourceUnits;
+    let count = Math.max(0, snapshot.rows.length - 1), hasContent = false;
+    for (const { text } of snapshot.rows) {
+        count += text.length;
+        hasContent ||= /\S/u.test(text);
+    }
+    return hasContent ? count : undefined;
 }
 export function formatSessionResumeCommand(metadata) {
     const args = [PRODUCT_TEXT.commandName];

package/dist/app/session-shell/session-viewport-controller.d.ts

@@ -64,7 +64,7 @@ export declare class SessionViewportController {
     setOverlaySurfaces(surfaces: readonly PiTuiPointerSurface[] | null): void;
     get inputGeometryReady(): boolean;
     compose(input: Omit<TranscriptViewportFrameInput, "pointerPosition">): TranscriptViewportFrame;
-    composeDockOnly(dockRows: readonly string[], width: number, height: number): TranscriptViewportFrame | null;
+    composeDockOnly(dockRows: readonly string[], width: number, height: number, explicitCopyDockRows?: number): TranscriptViewportFrame | null;
     /** Returns true when document wrapping may have changed. */
     setConfig(config: OwnedUiViewportSettings): boolean;
     resumeFollowing(): void;

package/dist/app/session-shell/session-viewport-controller.js

@@ -165,8 +165,8 @@ export class SessionViewportController {
         }
         return frame;
     }
-    composeDockOnly(dockRows, width, height) {
-        return this.#viewport.composeDockOnly(dockRows, width, height);
+    composeDockOnly(dockRows, width, height, explicitCopyDockRows = 0) {
+        return this.#viewport.composeDockOnly(dockRows, width, height, explicitCopyDockRows);
     }
     /** Returns true when document wrapping may have changed. */
     setConfig(config) {
@@ -307,7 +307,7 @@ export class SessionViewportController {
                     this.#requestRender();
             }
             else if (this.#viewport.hasSelection) {
-                const copySelection = this.#viewport.captureSelectedText();
+                const copySelection = this.#viewport.captureSelectedText("explicit");
                 this.#viewport.clearSelection();
                 this.#stopSelectionAutoScroll();
                 this.#requestRender();

package/dist/composition/owned-ui.d.ts

@@ -10,6 +10,7 @@ import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contra
 import type { AgentSettingsPort } from "../contracts/agent-engine/index.js";
 import type { OwnedUiPromptSuggestionGeneratorPort, UiAccentColor } from "../contracts/owned-ui/index.js";
 import type { ReleaseNoteCatalog } from "../features/owned-ui/release-notes.js";
+import type { TabBridgeClient } from "../foundation/resident-tabs/bridge-client.js";
 /**
  * The session backend composition wires: the owned-UI port, the prompt-suggestion generator, and
  * the agent settings port. `settingsPort` stays outside the owned-UI contract because its type
@@ -55,11 +56,27 @@ export interface OwnedUiCompositionOptions {
     readonly checkForNewerRelease?: (options: StartupReleaseCheckOptions) => Promise<AvailableRelease | null>;
     /** Exact native process inspection injected by the shipped entry; absent SDK seams do not publish claims. */
     readonly inspectProcess?: (pid: number) => Promise<NativeProcessIdentity | null>;
+    /** Private credentials were consumed by the entry before composition or extensions loaded. */
+    readonly tab?: {
+        readonly bridge: TabBridgeClient;
+    };
+    /** One prompt-adjacent notice explaining why an opted-in resident launch fell back. */
+    readonly residentFallbackNotice?: string;
 }
 export interface OwnedUiComposition {
     readonly application: OwnedUiApplicationPort;
     /** Present when a profile was supplied, so the caller can resolve settings before start. */
     readonly settings: OwnedSettingsManager | null;
 }
+export declare function residentStartupPresentation(resident: boolean, fallbackNotice?: string): {
+    readonly startup?: {
+        readonly quiet?: boolean;
+        readonly notices?: readonly [{
+            readonly kind: "warning";
+            readonly message: string;
+        }];
+    };
+};
 export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOptions): Promise<OwnedUiApplicationPort>;
 export declare function composeOwnedUi(options?: OwnedUiCompositionOptions): Promise<OwnedUiComposition>;
+export declare function bindResidentTabBridge(tabBridge: TabBridgeClient, backend: Pick<ComposedSessionBackend, "identity" | "session">): Promise<() => void>;

package/dist/composition/owned-ui.js

@@ -19,6 +19,11 @@ import { createOwnedRouteHost } from "./settings-route-host.js";
 import { renderPiShellChangelogLines } from "../integrations/pi/components/shell-presenters-info.js";
 import { nativeHyperlinkStyle } from "../ui/components/spans.js";
 const SESSION_RUNTIME_REFRESH_MS = 30_000;
+export function residentStartupPresentation(resident, fallbackNotice) {
+    if (resident)
+        return { startup: { quiet: true } };
+    return fallbackNotice === undefined ? {} : { startup: { notices: [{ kind: "warning", message: fallbackNotice }] } };
+}
 export async function composeOwnedUiApplication(options = {}) {
     return (await composeOwnedUi(options)).application;
 }
@@ -120,6 +125,8 @@ export async function composeOwnedUi(options = {}) {
         await host.dispose();
         throw error;
     }
+    const tabBridge = options.tab?.bridge ?? null;
+    const unsubscribeTabBridge = tabBridge === null ? () => { } : await bindResidentTabBridge(tabBridge, backend);
     let releaseNotes = null;
     let releaseNotesFailure;
     if (ownedSurfaces) {
@@ -228,13 +235,15 @@ export async function composeOwnedUi(options = {}) {
                     },
                 }),
                 ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),
+                ...(tabBridge === null ? {} : { residentTab: { requestDetach: () => tabBridge.requestDetach() } }),
             },
             presentation: {
                 ...(options.terminal === undefined ? {} : { terminal: createPiTerminalBridge(options.terminal) }),
+                ...residentStartupPresentation(tabBridge !== null, options.residentFallbackNotice),
                 ...(clipboardDiagnostics === null ? {} : { input: { onEvent: event => clipboardDiagnostics.runtime(event) } }),
                 ...(viewportSettings === null ? {} : { viewportSettings }),
                 ...(backgroundSettings === null ? {} : { backgroundSettings }),
-                ...(settings === null || !ownedSurfaces ? {} : {
+                ...(settings === null || !ownedSurfaces || tabBridge !== null ? {} : {
                     quitOutro: { snapshot: () => quitOutroSettingsSnapshot(settings), interactive: process.stdout.isTTY === true },
                 }),
             },
@@ -323,6 +332,8 @@ export async function composeOwnedUi(options = {}) {
                 await releaseNoteClaim?.release();
                 suggestionDiagnostics?.dispose();
                 clipboardDiagnostics?.dispose();
+                unsubscribeTabBridge();
+                tabBridge?.close();
                 // Invariant: the host outlives the application; disposing it cancels host-level probes last.
                 await host.dispose();
             }
@@ -330,6 +341,22 @@ export async function composeOwnedUi(options = {}) {
     };
     return { application, settings };
 }
+export async function bindResidentTabBridge(tabBridge, backend) {
+    await tabBridge.start().catch(() => false);
+    tabBridge.status("starting");
+    const announceSession = () => {
+        const resume = backend.identity.currentSessionResumeMetadata();
+        tabBridge.session(resume === null ? null : `${resume.sessionDir}/${resume.sessionId}`, backend.session.view().status.footer?.sessionName ?? null);
+    };
+    announceSession();
+    return backend.session.onEvent(event => {
+        if (event.type === "session-lifecycle") {
+            tabBridge.status(event.lifecycle === "busy" ? "working" : event.lifecycle === "starting" ? "starting" : "idle");
+        }
+        if (event.type === "session-view")
+            announceSession();
+    });
+}
 async function readPackageVersion() {
     const manifest = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
     const version = manifest?.version;

package/dist/foundation/launch-context/index.d.ts

@@ -7,6 +7,9 @@ export declare const PRIVATE_ENVIRONMENT: Readonly<{
     releaseLayers: "LAUNCH_CONTEXT_RELEASE_LAYERS";
     launchProfile: "LAUNCH_CONTEXT_PROFILE";
     immutableWarmup: "LAUNCH_CONTEXT_WARMUP";
+    residentRootExecutable: "LAUNCH_CONTEXT_RESIDENT_ROOT_EXECUTABLE";
+    residentRootArguments: "LAUNCH_CONTEXT_RESIDENT_ROOT_ARGUMENTS";
+    residentFallback: "LAUNCH_CONTEXT_RESIDENT_FALLBACK";
 }>;
 /**
  * Keys published by releases that predate the neutral cutover. They are read when
@@ -31,6 +34,9 @@ export interface LaunchContext {
     readonly releaseLayers?: string;
     readonly launchProfile?: "a1" | "pi";
     readonly immutableWarmup?: "1";
+    readonly residentRootExecutable?: string;
+    readonly residentRootArguments?: string;
+    readonly residentFallback?: string;
 }
 export type LaunchContextRequirement = "optional" | "profile" | "release" | "warmup";
 /** Read current keys, fall back to superseded keys per field, with bounded diagnostics. */

package/dist/foundation/launch-context/index.js

@@ -7,6 +7,9 @@ export const PRIVATE_ENVIRONMENT = Object.freeze({
     releaseLayers: "LAUNCH_CONTEXT_RELEASE_LAYERS",
     launchProfile: "LAUNCH_CONTEXT_PROFILE",
     immutableWarmup: "LAUNCH_CONTEXT_WARMUP",
+    residentRootExecutable: "LAUNCH_CONTEXT_RESIDENT_ROOT_EXECUTABLE",
+    residentRootArguments: "LAUNCH_CONTEXT_RESIDENT_ROOT_ARGUMENTS",
+    residentFallback: "LAUNCH_CONTEXT_RESIDENT_FALLBACK",
 });
 /**
  * Keys published by releases that predate the neutral cutover. They are read when
@@ -63,6 +66,18 @@ export function readLaunchContext(environment, requirement = "optional", platfor
     }
     if (values.immutableWarmup !== undefined && values.immutableWarmup !== "1")
         throw invalidContext("immutableWarmup", "invalid permission flag");
+    if ((values.residentRootExecutable === undefined) !== (values.residentRootArguments === undefined))
+        throw invalidContext("residentRootExecutable", "resident root command is incomplete");
+    if (values.residentRootArguments !== undefined) {
+        try {
+            const argumentsValue = JSON.parse(values.residentRootArguments);
+            if (!Array.isArray(argumentsValue) || argumentsValue.some(value => typeof value !== "string"))
+                throw new Error("not string arguments");
+        }
+        catch {
+            throw invalidContext("residentRootArguments", "invalid JSON argument list");
+        }
+    }
     if (values.releaseDigest !== undefined && !/^[a-f0-9]{64}$/.test(values.releaseDigest))
         throw invalidContext("releaseDigest", "invalid digest");
     if (requirement === "profile")

package/dist/foundation/launch-guardian/main.d.ts

@@ -16,11 +16,16 @@ interface GuardianControl {
     off(event: "disconnect", listener: () => void): unknown;
     close(): void;
 }
+export interface LaunchGuardianRootCommand {
+    readonly executable: string;
+    readonly arguments: readonly string[];
+}
 export interface LaunchGuardianOptions {
     readonly profileId: LaunchProfileId;
     readonly releaseRoot: string;
     readonly uiEntry: string;
     readonly sessionSelection?: SessionSelection;
+    readonly rootCommand?: LaunchGuardianRootCommand;
     readonly environment?: NodeJS.ProcessEnv;
     readonly cwd?: string;
     readonly helperPath?: string;

package/dist/foundation/launch-guardian/main.js

@@ -44,7 +44,8 @@ export async function runLaunchGuardian(options) {
         });
         let handle;
         try {
-            handle = await containment.spawn(process.execPath, [options.uiEntry, ...sessionArgs], {
+            const rootCommand = options.rootCommand ?? { executable: process.execPath, arguments: [options.uiEntry, ...sessionArgs] };
+            handle = await containment.spawn(rootCommand.executable, [...rootCommand.arguments], {
                 cwd: options.cwd ?? process.cwd(),
                 environment: environmentEntries(environment),
                 ...(environment.TERM ? { terminalType: environment.TERM } : {}),

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

@@ -2,6 +2,7 @@ import { type SupervisorEndpointMetadata } from "./cohort-state.js";
 import { resolveProductPaths, type SessionSelection, type LaunchProfileId, type SupervisorStartupAttemptIdentity } from "../lifecycle/index.js";
 import { cleanupProvenIdleOwner } from "./process-cleanup.js";
 import { type MaterializedRelease, type VerifyMaterializedReleaseOptions } from "./release-store.js";
+import { type EnsureTerminalHostOptions, type EnsureTerminalHostResult } from "../resident-tabs/index.js";
 export interface BootstrapOptions {
     readonly packageRoot: string;
     readonly launchIntent?: {
@@ -23,6 +24,9 @@ export interface BootstrapOptions {
     readonly releaseIsLaunchable?: (releaseRoot: string) => boolean;
     /** Test seam for bounded maintenance scheduled after stale endpoint sweeping. */
     readonly scheduleMaintenance?: (dataDir: string, paths: ReturnType<typeof resolveProductPaths>) => Promise<void>;
+    /** Test seams for resident launch routing before the guardian starts. */
+    readonly readResidentTabs?: (configDir: string, profileId: string) => Promise<boolean>;
+    readonly ensureTerminalHost?: (options: EnsureTerminalHostOptions) => Promise<EnsureTerminalHostResult>;
 }
 export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
 export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;