@timurproko/a1 0.2.6 → 0.2.7-dev.1222

package/README.md

@@ -57,6 +57,12 @@ Launch A1 (profile: `~/.a1/agent`):
 a1
 ```
 
+Launch A1 in single agent mode:
+
+```text
+a1 solo
+```
+
 Show all commands:
 
 ```text
@@ -77,6 +83,30 @@ a1 pi
 
 <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
 
+## Tabs
+
+Tabs keep running after their terminal closes. List them, or stop one; its session stays resumable:
+
+```text
+a1 tabs
+a1 tabs stop <id>
+```
+
+Stop every tab and the resident host, for example before going back to single agent mode with `a1 solo`:
+
+```text
+a1 tabs host stop
+```
+
+Show host health, or write a redacted diagnostic bundle:
+
+```text
+a1 tabs host status
+a1 tabs doctor
+```
+
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
+
 ## Update
 
 Install the release:
@@ -115,7 +145,13 @@ Stuck on `0.2.2` and `a1 update` fails? Run the installer once, then use `a1 upd
 npm x -y -- @timurproko/a1-install
 ```
 
-A1 shows an `Update Available` notice at most once a day and never installs anything by itself. Turn it off in Settings (`Update check`) or with `A1_SKIP_VERSION_CHECK=1`.
+The **Update** setting controls the at-most-daily startup check:
+
+- **Auto** (default) silently installs a verified update for the running channel, then shows `Update installed · Restart to update`.
+- **Notify** keeps the `Update Available` notice and leaves installation manual.
+- **No** performs no startup update check; updates remain available through the commands above.
+
+`A1_SKIP_VERSION_CHECK=1` also disables the startup check. Manual stable, development, and exact-version update commands remain available in every mode.
 
 <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
 
@@ -155,13 +191,15 @@ a1 update npm:pi-mcp-adapter
 
 ## Develop
 
+A source build needs Node.js, npm, git, and Rustup. Windows additionally needs Visual Studio or Visual Studio Build Tools with the **Desktop development with C++** workload, MSVC x64/x86 tools, and a Windows SDK; Visual Studio Code is not required. A1 discovers installed Rustup and Visual Studio tools and initializes them for build children, so Git Bash and ordinary PowerShell do not need manual `PATH` or developer-shell setup. It never installs these tools or accepts their licenses automatically.
+
 Install exact locked dependencies:
 
 ```text
 npm ci
 ```
 
-Compile TypeScript and the process guardian into `dist`:
+Compile TypeScript and the native addons into `dist`:
 
 ```text
 npm run build
@@ -191,7 +229,7 @@ Complete non-physical suite:
 npm run test:full
 ```
 
-Report Node, npm, git, Rust, and dependency readiness:
+Report Node, npm, git, Rust, dependency, and Windows C++ readiness. Missing Windows tools are listed in setup order; after installing them, rerun the same build command:
 
 ```text
 npm run doctor

package/bin/automatic-update.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import("../dist/foundation/release/automatic-update.js").then(async ({ runAutomaticUpdateWorker }) => {
+  process.exitCode = await runAutomaticUpdateWorker(process.argv.slice(2));
+}).catch(() => {
+  process.exitCode = 1;
+});

package/bin/cli.js

@@ -69,6 +69,10 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
       },
     });
   },
+  tabs: async request => {
+    const { runTabsCommand } = await import("../dist/cli/tabs.js");
+    return await runTabsCommand(request, { packageRoot: fileURLToPath(packageRoot) });
+  },
 }, {
   stdout: message => process.stdout.write(message),
   stderr: message => process.stderr.write(message),

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,27 @@
+export interface TabLaunchCredentials {
+  readonly tabId: string;
+  readonly token: string;
+  readonly endpoint: string;
+  readonly releaseId?: string;
+}
+
+export function formatResidentFallbackNotice(reason: string): string;
+
+export function assignFreshSessionRuntimeId(
+  environment: Record<string, string | undefined>,
+  name: string,
+  createId: () => string,
+): string;
+
+export function waitForStandbyPromotion(input: NodeJS.ReadStream, promotionFile?: string): Promise<void>;
+
+export function consumeTabLaunchContext(
+  arguments_: readonly string[],
+  environment: Record<string, string | undefined>,
+): {
+  readonly uiArguments: string[];
+  readonly tabCredentials: TabLaunchCredentials | undefined;
+  readonly tabDataDir?: string;
+  readonly tabIncarnation?: number;
+  readonly tabStandby: boolean;
+};

package/bin/tab-launch-context.js

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+
+const TAB_ENVIRONMENT_NAMES = ["A1_TAB_ID", "A1_TAB_TOKEN", "A1_TAB_ENDPOINT", "A1_TAB_RELEASE_ID"];
+
+/** @param {string} reason */
+export function formatResidentFallbackNotice(reason) {
+  // Protocol: a host of another generation is never replaced automatically; only the user stops it.
+  if (reason === "incompatible generation") {
+    return "A1 normal mode unavailable (running tabs use another version); running in single agent mode. Run `a1 tabs host stop` to restart them on this version.";
+  }
+  return `A1 normal mode unavailable (${reason}); running in single agent mode.`;
+}
+
+/**
+ * @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;
+}
+
+/**
+ * Keep the standby below the session/runtime boundary until its authenticated holder promotes it.
+ * Platform: Windows ConPTY may drop the in-band marker, so the holder also creates the promotion
+ * file inside the tab's private data directory; whichever arrives first promotes the standby.
+ * @param {NodeJS.ReadStream} input
+ * @param {string} [promotionFile]
+ */
+export function waitForStandbyPromotion(input, promotionFile) {
+  return /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+    const marker = Buffer.from("\x1b]a1;standby-promote\x07");
+    let buffered = Buffer.alloc(0);
+    /** @type {NodeJS.Timeout | undefined} */
+    let poll;
+    const cleanup = () => {
+      if (poll !== undefined) clearInterval(poll);
+      input.off("data", onData);
+      input.off("error", onError);
+      input.pause();
+      if (input.isTTY) input.setRawMode(false);
+    };
+    /** @param {Error} error */
+    const onError = error => { cleanup(); reject(error); };
+    /** @param {Buffer | string} chunk */
+    const onData = chunk => {
+      const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+      buffered = Buffer.concat([buffered, bytes]).subarray(-marker.length);
+      if (buffered.equals(marker)) { cleanup(); resolve(undefined); }
+    };
+    if (input.isTTY) input.setRawMode(true);
+    input.on("data", onData);
+    input.on("error", onError);
+    input.resume();
+    if (promotionFile !== undefined) {
+      poll = setInterval(() => {
+        if (existsSync(promotionFile)) { cleanup(); resolve(undefined); }
+      }, 10);
+    }
+  }));
+}
+
+/**
+ * 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 standbyArgument = uiArguments.indexOf("--tab-standby");
+  const tabStandby = standbyArgument !== -1;
+  if (tabStandby) uiArguments.splice(standbyArgument, 1);
+  const dataArgument = uiArguments.indexOf("--tab-data-dir");
+  const tabDataDir = dataArgument === -1 ? undefined : uiArguments[dataArgument + 1];
+  if (dataArgument !== -1) uiArguments.splice(dataArgument, 2);
+  const incarnationArgument = uiArguments.indexOf("--tab-incarnation");
+  const tabIncarnation = incarnationArgument === -1 ? undefined : Number(uiArguments[incarnationArgument + 1]);
+  if (incarnationArgument !== -1) uiArguments.splice(incarnationArgument, 2);
+  const [tabId, token, endpoint, releaseId] = TAB_ENVIRONMENT_NAMES.map(name => environment[name]);
+  for (const name of TAB_ENVIRONMENT_NAMES) delete environment[name];
+  if (!tabMode) return { uiArguments, tabCredentials: undefined, tabStandby: false };
+  if (!tabId || !token || !endpoint || !tabDataDir || tabDataDir.includes("\0")
+    || typeof tabIncarnation !== "number" || !Number.isSafeInteger(tabIncarnation) || tabIncarnation < 1) {
+    throw new Error("A1 tab mode requires bridge credentials, recovery directory, and incarnation");
+  }
+  return { uiArguments, tabCredentials: { tabId, token, endpoint, ...(releaseId === undefined ? {} : { releaseId }) }, tabDataDir, tabIncarnation, tabStandby };
+}

package/bin/ui.js

@@ -1,11 +1,18 @@
 #!/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, waitForStandbyPromotion } = await import("./tab-launch-context.js");
+const { uiArguments, tabCredentials, tabDataDir, tabIncarnation, tabStandby } = 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(/\/$/, ""));
+const utilityRoute = tabCredentials === undefined
+  ? null
+  : (await import("../dist/foundation/resident-tabs/routes.js")).residentUtilityRoute(tabCredentials.tabId);
 const startup = await import("../dist/foundation/startup/startup-runtime.js");
 startup.enableEnvironmentCompileCache(process.env);
-const { readLaunchContext } = await import("../dist/foundation/launch-context/index.js");
+const { hidesTabSettings, readLaunchContext } = await import("../dist/foundation/launch-context/index.js");
 const launchContext = readLaunchContext(process.env, "profile");
 const profile = launchContext.launchProfile;
 if (profile === undefined) throw new Error("A1 launch profile is missing");
@@ -14,78 +21,119 @@ 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");
-const { join } = await import("node:path");
+const { dirname, join } = await import("node:path");
 /** @type {{ dispose(): void | Promise<unknown> } | undefined} */
 let runningApplication;
 const fatal = profile === "a1" ? installFatalExit({
-  directory: join(resolveProductPaths().runtimeDir, "crashes"),
+  directory: tabDataDir === undefined
+    ? join(resolveProductPaths().runtimeDir, "crashes")
+    : join(dirname(tabDataDir), "diagnostics"),
   ...(launchContext.releaseId === undefined ? {} : { releaseId: launchContext.releaseId }),
   dispose: () => runningApplication?.dispose(),
 }) : undefined;
-const [{ fileURLToPath }, identity, descriptor] = await Promise.all([
+const [{ fileURLToPath }, identity] = await Promise.all([
   import("node:url"),
   import("./module-identity.js"),
-  import("../dist/foundation/startup/startup-descriptor.js"),
 ]);
 const packageRootPath = fileURLToPath(new URL("..", import.meta.url));
 identity.configurePinnedPiPublicPackage(packageRootPath);
-// Performance: begin the exact launch graph together while the trace write is pending.
-// Direct owned-module entries avoid evaluating unrelated barrel exports before first paint.
-const modules = descriptor.loadDeclaredStartupGraph();
-await startup.markStartupPhase(process.env, "ui-entry");
-const [
-  { runSelectedInteractiveRuntime },
-  { parseSessionSelection },
-  { createConsoleProjectTrustPrompt },
-  { createConsoleSessionForkPrompt },
-  { runOwnedUi, terminateOwnedUiProcess },
-  { composeOwnedUi },
-] = await modules;
 
-// Compatibility: before the composition uses pinned Pi's terminal stack: confirm A1 and Pi
-// resolve it to the same copy, so extensions and the owned UI share one module identity.
-identity.assertSinglePiTuiModuleAtLaunch(packageRootPath, (/** @type {string} */ message) => process.stderr.write(message));
-await startup.markStartupPhase(process.env, "ui-modules-loaded");
+// Compatibility: before either composition uses pinned Pi's terminal stack, confirm A1 and Pi
+// resolve it to the same copy so every owned screen shares one module identity.
+const assertPiTuiIdentity = () => identity.assertSinglePiTuiModuleAtLaunch(
+  packageRootPath,
+  (/** @type {string} */ message) => process.stderr.write(message),
+);
+
+if (utilityRoute !== null) {
+  if (profile !== "a1" || tabCredentials === undefined) throw new Error("utility tabs require the normal A1 tab profile");
+  await startup.markStartupPhase(process.env, "ui-entry");
+  assertPiTuiIdentity();
+  const utility = await import("../dist/composition/utility-tab.js");
+  await startup.markStartupPhase(process.env, "ui-modules-loaded");
+  const bridge = new (await import("../dist/foundation/resident-tabs/bridge-client.js")).TabBridgeClient({ credentials: tabCredentials });
+  completeRun(utility.runUtilityTab({
+    route: utilityRoute,
+    bridge,
+    cwd: process.cwd(),
+    profileId: profile,
+    onApplication: application => { runningApplication = application; },
+  }), utility.terminateOwnedUiProcess);
+} else {
+  const descriptor = await import("../dist/foundation/startup/startup-descriptor.js");
+  // Performance: begin the exact Agent launch graph together while the trace write is pending.
+  // Direct owned-module entries avoid evaluating unrelated barrel exports before first paint.
+  const modules = descriptor.loadDeclaredStartupGraph();
+  await startup.markStartupPhase(process.env, "ui-entry");
+  const [
+    { runSelectedInteractiveRuntime },
+    { parseSessionSelection },
+    { createConsoleProjectTrustPrompt },
+    { createConsoleSessionForkPrompt },
+    { runOwnedUi, terminateOwnedUiProcess },
+    { composeOwnedUi },
+  ] = await modules;
 
-const sessionSelection = parseSessionSelection(process.argv.slice(2));
-Promise.resolve().then(() => {
-  if (sessionSelection && profile !== "a1") throw new Error("session selection requires the normal A1 profile");
-  return runSelectedInteractiveRuntime(profile, {
-    ownedUi: async (profileId, ownedSurfaces) => {
-      const processInspector = ownedSurfaces
-        ? await import("../dist/foundation/process-containment/native-process-inspector.js")
-          .then(module => module.createNativeProcessInspector(process.env, process.platform, launchContext.releaseRoot))
-          .catch(() => null)
-        : null;
-      const { application, settings } = await composeOwnedUi({
-        cwd: process.cwd(),
-        profileId,
-        ownedSurfaces,
-        ...(processInspector === null ? {} : { inspectProcess: pid => processInspector.observe(pid) }),
-        projectTrustPrompt: createConsoleProjectTrustPrompt({ presentation: profile === "a1" ? "bare" : "comparison" }),
-        sessionForkPrompt: createConsoleSessionForkPrompt(),
-        ...(sessionSelection === undefined ? {} : { sessionSelection }),
-      });
-      runningApplication = application;
-      return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
+  if (tabStandby) await waitForStandbyPromotion(process.stdin, tabDataDir === undefined ? undefined : join(tabDataDir, "standby-promote"));
+  assertPiTuiIdentity();
+  await startup.markStartupPhase(process.env, "ui-modules-loaded");
+
+  const sessionSelection = parseSessionSelection(uiArguments);
+  completeRun(Promise.resolve().then(async () => {
+    const tab = tabCredentials === undefined ? undefined : {
+      bridge: new (await import("../dist/foundation/resident-tabs/bridge-client.js")).TabBridgeClient({ credentials: tabCredentials }),
+      dataDir: /** @type {string} */ (tabDataDir),
+      incarnation: /** @type {number} */ (tabIncarnation),
+    };
+    if (sessionSelection && profile !== "a1") throw new Error("session selection requires the normal A1 profile");
+    return runSelectedInteractiveRuntime(profile, {
+      ownedUi: async (profileId, ownedSurfaces) => {
+        const processInspector = ownedSurfaces
+          ? await import("../dist/foundation/process-containment/native-process-inspector.js")
+            .then(module => module.createNativeProcessInspector(process.env, process.platform, launchContext.releaseRoot))
+            .catch(() => null)
+          : null;
+        const { application, settings } = await composeOwnedUi({
+          cwd: process.cwd(),
+          profileId,
+          ownedSurfaces,
+          notificationVersion: launchContext.updateVersion,
+          ...(hidesTabSettings(launchContext) ? { hideTabSettings: true } : {}),
+          ...(processInspector === null ? {} : { inspectProcess: pid => processInspector.observe(pid) }),
+          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 }) });
+      },
+    });
+  }), terminateOwnedUiProcess);
+}
+
+/** @param {Promise<number>} run @param {(code: number) => Promise<never>} terminate */
+function completeRun(run, terminate) {
+  run.then(
+    code => {
+      fatal?.remove();
+      return terminate(code);
     },
-  });
-}).then(
-  code => {
-    fatal?.remove();
-    return terminateOwnedUiProcess(code);
-  },
-  error => {
-    const sessionSelectionError = error?.name === "PiSessionSelectionError";
-    const trustExit = error?.name === "ProjectTrustPromptExitError";
-    if (fatal && !sessionSelectionError && !trustExit) { fatal.fail(error); return; }
-    fatal?.remove();
-    if (trustExit) return terminateOwnedUiProcess(error.exitCode);
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = sessionSelectionError ? error.exitCode : 1;
-  },
-);
+    error => {
+      const sessionSelectionError = error?.name === "PiSessionSelectionError";
+      const trustExit = error?.name === "ProjectTrustPromptExitError";
+      if (fatal && !sessionSelectionError && !trustExit) { fatal.fail(error); return; }
+      fatal?.remove();
+      if (trustExit) return terminate(error.exitCode);
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = sessionSelectionError ? error.exitCode : 1;
+    },
+  );
+}

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

@@ -39,7 +39,7 @@ export class ClipboardDiagnosticCapture {
         // Security: project only declared scalar fields. Never serialize the supplied event object or raw errors.
         this.#records.push({ source, phase: event.phase, atMs: scalar(event.atMs), request: event.request !== undefined && event.request < 0 ? -scalar(-event.request) : scalar(event.request), pending: scalar(event.pending), bytes: scalar(event.bytes), elapsedMs: scalar(event.elapsedMs),
             sourceUnits: scalar(event.sourceUnits), pendingBytes,
-            transport: ["native", "terminal", "provided", "injected"].includes(event.transport ?? "") ? event.transport : "none",
+            transport: ["native", "terminal", "platform", "provided", "injected"].includes(event.transport ?? "") ? event.transport : "none",
             outcome: ["ready", "failed", "canceled", "delivered", "submitted-unverified", "timed-out", "superseded"].includes(event.outcome ?? "") ? event.outcome : "none" });
         if (this.#records.length > 128)
             this.#records.shift();

package/dist/app/session-shell/dialog-coordinator.d.ts

@@ -0,0 +1,42 @@
+import type { OwnedUiCommandResult, OwnedUiDialog } from "../../contracts/owned-ui/index.js";
+import type { UiRouteHost, UiRouteInput } from "../../ui/apps/contracts.js";
+import type { PiShellSelectorOption } from "../../integrations/pi/components/shell-shared-facade.js";
+import type { PiTuiOverlayHandle } from "../../integrations/pi/tui-runtime/contracts.js";
+import type { OwnedUiPresenterTerminal } from "./shell-host.js";
+import type { OwnedUiSessionShellOptions, OwnedUiSessionShellRoot } from "./session-shell-root.js";
+type StartupRoute = NonNullable<OwnedUiSessionShellOptions["engine"]["startupRoute"]>;
+export interface SessionDialogPorts {
+    readonly terminal: Pick<OwnedUiPresenterTerminal, "running" | "hasOverlay" | "showOverlay" | "openRoute" | "requestRender">;
+    readonly root: Pick<OwnedUiSessionShellRoot, "dismissNotice" | "setInputSurface" | "usesDefaultInputSurface">;
+    readonly routeHost: UiRouteHost | null;
+    readonly disposed: () => boolean;
+    /** A route, or the interrupt chord over it, asked to leave A1. */
+    readonly exit: () => void;
+    /** A rendered route closed itself. */
+    readonly routeClosed?: (route: string) => void;
+    readonly startupRoute?: StartupRoute;
+}
+/**
+ * Owns the one modal overlay a session shows at a time, whichever source opened it: an owned route,
+ * a local selector, or a backend dialog. Opening one hides the previous one, and every close path
+ * clears the same state.
+ */
+export declare class SessionDialogCoordinator {
+    #private;
+    constructor(ports: SessionDialogPorts);
+    /** Clears the replacement input surface a selector put in the dock; the shared close action of every dock selector. */
+    readonly closeInputSurface: () => void;
+    showSelector(title: string, options: readonly PiShellSelectorOption[], onSelect: (id: string) => void, onCancel?: () => void): PiTuiOverlayHandle;
+    /** Mirrors the backend's pending dialog; locally owned routes and selectors are left alone when it has none. */
+    syncBackend(dialog: OwnedUiDialog | null): void;
+    openRoute(route: string, input?: UiRouteInput, onClosed?: () => void | Promise<void>): OwnedUiCommandResult;
+    claimsRoute(name: string): boolean;
+    /** Retains a route requested before the runtime runs; the latest request wins. */
+    retainStartupRoute(route: string): void;
+    /** Opens the retained startup route once no overlay or replacement input surface holds the screen. */
+    presentStartupRoute(): void;
+    /** A replaced session takes its dialog with it; a retained startup route still opens. */
+    onSessionReplaced(): void;
+    dispose(): void;
+}
+export {};

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

@@ -0,0 +1,133 @@
+import { createPiShellDialog, createPiShellSelector } from "../../integrations/pi/components/shell-selectors-dialogs.js";
+const OVERLAY_OPTIONS = { width: "70%", maxHeight: "80%", anchor: "center", inputCoordination: "owned" };
+const STARTUP_ROUTE_RETRY_MS = 25;
+/**
+ * Owns the one modal overlay a session shows at a time, whichever source opened it: an owned route,
+ * a local selector, or a backend dialog. Opening one hides the previous one, and every close path
+ * clears the same state.
+ */
+export class SessionDialogCoordinator {
+    #ports;
+    #handle;
+    #id;
+    #source;
+    #startupRoute;
+    #startupRouteTimer;
+    constructor(ports) {
+        this.#ports = ports;
+        this.#startupRoute = ports.startupRoute;
+    }
+    /** Clears the replacement input surface a selector put in the dock; the shared close action of every dock selector. */
+    closeInputSurface = () => {
+        this.#ports.root.setInputSurface(null);
+        this.#ports.terminal.requestRender();
+    };
+    showSelector(title, options, onSelect, onCancel) {
+        this.#handle?.hide();
+        this.#source = "local";
+        this.#id = undefined;
+        const component = createPiShellSelector({
+            title,
+            options,
+            onSelect: id => {
+                onSelect(id);
+                this.#close();
+            },
+            onCancel: () => {
+                this.#close();
+                onCancel?.();
+            },
+        });
+        const handle = this.#ports.terminal.showOverlay(component, OVERLAY_OPTIONS);
+        this.#handle = handle;
+        return handle;
+    }
+    /** Mirrors the backend's pending dialog; locally owned routes and selectors are left alone when it has none. */
+    syncBackend(dialog) {
+        if (!this.#ports.terminal.running)
+            return;
+        if (dialog === null) {
+            // Invariant: locally owned routes (notably /settings) are independent of backend
+            // lifecycle/status events and remain open while an agent is working.
+            if (this.#source === "backend")
+                this.#close();
+            return;
+        }
+        if (this.#source === "backend" && this.#id === dialog.id)
+            return;
+        this.#handle?.hide();
+        this.#source = "backend";
+        const component = createPiShellDialog(dialog, { onSelect: () => this.#close(), onCancel: () => this.#close() });
+        this.#handle = this.#ports.terminal.showOverlay(component, OVERLAY_OPTIONS);
+        this.#id = dialog.id;
+    }
+    openRoute(route, input, onClosed) {
+        const surface = this.#ports.routeHost?.open(route, input) ?? null;
+        if (surface === null)
+            return { outcome: "failed", diagnostic: `route is unavailable: ${route}` };
+        if (!this.#ports.terminal.running)
+            return { outcome: "failed", diagnostic: "runtime is not active" };
+        this.#ports.root.dismissNotice();
+        this.#handle?.hide();
+        this.#source = "route";
+        const handle = this.#ports.terminal.openRoute(surface, {
+            exit: () => this.#ports.exit(),
+            closed: rendered => {
+                if (this.#handle === handle)
+                    this.#clear();
+                if (rendered) {
+                    try {
+                        void onClosed?.()?.catch(() => undefined);
+                    }
+                    catch { /* Rationale: a failed acknowledgement stays pending. */ }
+                    this.#ports.routeClosed?.(route);
+                }
+            },
+        });
+        this.#handle = handle;
+        this.#id = surface.id;
+        return { outcome: "completed", diagnostic: null };
+    }
+    claimsRoute(name) {
+        return this.#ports.routeHost?.claims(name) ?? false;
+    }
+    /** Retains a route requested before the runtime runs; the latest request wins. */
+    retainStartupRoute(route) {
+        this.#startupRoute = { route };
+    }
+    /** Opens the retained startup route once no overlay or replacement input surface holds the screen. */
+    presentStartupRoute() {
+        const pending = this.#startupRoute;
+        if (pending === undefined || this.#ports.disposed() || !this.#ports.terminal.running)
+            return;
+        if (this.#ports.terminal.hasOverlay() || !this.#ports.root.usesDefaultInputSurface()) {
+            this.#startupRouteTimer = setTimeout(() => {
+                this.#startupRouteTimer = undefined;
+                this.presentStartupRoute();
+            }, STARTUP_ROUTE_RETRY_MS);
+            this.#startupRouteTimer.unref?.();
+            return;
+        }
+        this.#startupRoute = undefined;
+        this.openRoute(pending.route, pending.input, pending.onClosed);
+    }
+    /** A replaced session takes its dialog with it; a retained startup route still opens. */
+    onSessionReplaced() {
+        this.#close();
+    }
+    dispose() {
+        if (this.#startupRouteTimer !== undefined)
+            clearTimeout(this.#startupRouteTimer);
+        this.#startupRouteTimer = undefined;
+        this.#handle?.hide();
+    }
+    #close() {
+        this.#handle?.hide();
+        this.#clear();
+    }
+    #clear() {
+        this.#handle = undefined;
+        this.#id = undefined;
+        this.#source = undefined;
+    }
+}