@timurproko/a1 0.2.7-dev.754 → 0.2.7-dev.767

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,23 @@
+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;
+  readonly tabDataDir?: string;
+  readonly tabIncarnation?: number;
+};

package/bin/tab-launch-context.js

@@ -0,0 +1,45 @@
+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 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] = 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 || !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 }, tabDataDir, tabIncarnation };
+}

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, tabDataDir, tabIncarnation } = 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,15 +18,17 @@ 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;
@@ -51,8 +57,13 @@ 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 }),
+    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) => {
@@ -69,6 +80,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,34 @@ 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>;
+        requestRestart?(): Promise<boolean>;
+        reportStatus?(status: "working" | "idle" | "stalled"): void;
+        readonly stallNoticeSeconds?: number;
+        admit?(input: {
+            readonly sessionId: string;
+            readonly sessionFile: string | null;
+            readonly kind: "prompt" | "steer" | "follow-up";
+            readonly text: string;
+            readonly images?: readonly unknown[];
+        }): Promise<{
+            readonly id: string;
+        }>;
+        dispatched?(): void;
+        correlated?(submissionId: string, entryId: string): Promise<void>;
+        checkpoint?(text: string): void;
+        gracefulStop?(sessionFile: string | null): Promise<void>;
+        readonly recovered?: {
+            readonly prompts: readonly {
+                readonly id: string;
+                readonly text: string;
+            }[];
+            readonly draft: string | null;
+        };
+        readonly unavailableNotice?: string;
+    };
 }
 /** Terminal, startup, viewport, and presentation-cadence seams; production leaves most at their defaults. */
 export interface OwnedUiShellPresentationOptions {
@@ -182,7 +210,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;
@@ -53,6 +54,9 @@ export class OwnedUiSessionPresenter {
     #routeHost;
     #startupRoute;
     #startupRouteTimer;
+    #residentProgressTimer;
+    #residentWorking = false;
+    #residentStalled = false;
     #dialogHandle;
     #sequence = 0;
     #editorRevision = 0;
@@ -104,6 +108,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";
@@ -202,6 +207,7 @@ export class OwnedUiSessionPresenter {
                 onDequeue: () => this.restoreQueuedInput(),
                 onEditorChange: text => {
                     this.#editorRevision++;
+                    this.#residentTabOptions?.checkpoint?.(text);
                     promptSuggestionController?.abortPending();
                     if (text.length === 0) {
                         // Concurrency: the editor synchronizes deletion-owned autocomplete after onChange.
@@ -218,9 +224,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 = () => {
@@ -263,6 +269,7 @@ export class OwnedUiSessionPresenter {
             // Invariant: the presenter owns its root (theme subscription and helper clients) and disposes it once the
             // terminal no longer renders it.
             constructed.push(() => this.root.dispose());
+            this.#restoreResidentInput();
             const initialPiSettings = this.backend.settings.snapshot();
             this.#programStatus = new ProgramStatusReporter(status => this.#terminal.setProgramStatus(status), () => this.view().status.footer?.sessionName ?? undefined);
             this.#reloadPresentation = reloadPresentation;
@@ -474,6 +481,7 @@ export class OwnedUiSessionPresenter {
                         this.#settleStoppedLifecycle();
                     return;
                 }
+                this.#observeResidentProgress(event);
                 // Performance: a streamed chunk names one block, and touching only that block is what keeps the
                 // cost of a chunk the same in a long session as in a new one. Everything else
                 // resynchronizes the view, which is cheap next to re-reading the transcript.
@@ -626,21 +634,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)
@@ -779,15 +787,38 @@ export class OwnedUiSessionPresenter {
         const type = this.view().lifecycle === "busy" ? "steer" : "prompt";
         this.#rememberInput(this.root.omitUnsentPromptImages(displayInput).trim(), type);
         this.root.resumeViewportFollowing();
-        const finishSending = prepared.images.length === 0 ? () => { } : this.root.beginImageSubmissionStatus();
+        const command = {
+            type,
+            correlationId: this.#correlation(type),
+            sessionId: this.backend.identity.sessionId,
+            text: input,
+            ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
+        };
+        let submission;
         try {
-            return await this.#execute({
-                type,
-                correlationId: this.#correlation(type),
-                sessionId: this.backend.identity.sessionId,
+            submission = await this.#residentTabOptions?.admit?.({
+                sessionId: command.sessionId,
+                sessionFile: this.#currentSessionFile(),
+                kind: type,
                 text: input,
                 ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
-            }, displayInput);
+            });
+        }
+        catch {
+            if (this.root.editor.getText().length === 0)
+                this.root.editor.setText(displayInput);
+            const message = "Prompt was not sent because its recovery journal could not be synchronized.";
+            this.#reportSubmissionError(undefined, message);
+            return rejected(message);
+        }
+        const finishSending = prepared.images.length === 0 ? () => { } : this.root.beginImageSubmissionStatus();
+        try {
+            const result = await this.#execute(command, displayInput);
+            if (submission !== undefined && result.outcome !== "rejected") {
+                this.#residentTabOptions?.dispatched?.();
+                await this.#residentTabOptions?.correlated?.(submission.id, command.correlationId).catch(() => undefined);
+            }
+            return result;
         }
         finally {
             finishSending();
@@ -795,7 +826,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 +1180,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 +1212,75 @@ export class OwnedUiSessionPresenter {
             this.#resolveStoppedLifecycle();
         }
     }
+    #restoreResidentInput() {
+        const recovered = this.#residentTabOptions?.recovered;
+        if (recovered === undefined)
+            return;
+        const prompts = recovered.prompts.map(prompt => prompt.text).filter(Boolean);
+        if (prompts.length > 0) {
+            this.root.editor.setText(prompts[0]);
+            if (recovered.draft)
+                this.root.editor.addToHistory(recovered.draft);
+            for (const additional of prompts.slice(1))
+                this.root.editor.addToHistory(additional);
+            this.root.appendWorkflowStatus(recovered.draft
+                ? `Recovered an unfinished prompt; the prior draft and ${Math.max(0, prompts.length - 1)} additional prompt${prompts.length === 2 ? "" : "s"} are in editor history.`
+                : `Recovered an unfinished prompt${prompts.length > 1 ? `; ${prompts.length - 1} additional prompts are in editor history` : ""}.`);
+        }
+        else if (recovered.draft) {
+            this.root.editor.setText(recovered.draft);
+            this.root.appendWorkflowStatus("Recovered the editor draft from the previous tab process.");
+        }
+    }
+    #currentSessionFile() {
+        const direct = this.backend.identity.currentSessionFile?.();
+        if (direct !== undefined && direct !== null)
+            return direct;
+        const resume = this.backend.identity.currentSessionResumeMetadata();
+        return resume === null ? null : `${resume.sessionDir}/${resume.sessionId}`;
+    }
+    #residentTab() {
+        return this.#residentTabOptions;
+    }
+    #observeResidentProgress(event) {
+        const resident = this.#residentTabOptions;
+        const seconds = resident?.stallNoticeSeconds;
+        if (resident === undefined || seconds === undefined)
+            return;
+        if (event.type === "session-lifecycle") {
+            this.#residentWorking = event.lifecycle === "busy";
+            if (!this.#residentWorking) {
+                if (this.#residentProgressTimer !== undefined)
+                    clearTimeout(this.#residentProgressTimer);
+                this.#residentProgressTimer = undefined;
+                this.#residentStalled = false;
+                resident.reportStatus?.("idle");
+                return;
+            }
+        }
+        else if (!this.#residentWorking || ![
+            "transcript-block", "session-view", "assistant-message-completed", "agent-run-started",
+        ].includes(event.type)) {
+            return;
+        }
+        if (this.#residentStalled) {
+            this.#residentStalled = false;
+            resident.reportStatus?.("working");
+        }
+        if (this.#residentProgressTimer !== undefined)
+            clearTimeout(this.#residentProgressTimer);
+        this.#residentProgressTimer = setTimeout(() => {
+            this.#residentProgressTimer = undefined;
+            if (this.#disposed || !this.#residentWorking)
+                return;
+            this.#residentStalled = true;
+            resident.reportStatus?.("stalled");
+            const minutes = Math.max(1, Math.round(seconds / 60));
+            this.root.appendWorkflowStatus(`No progress for ${minutes} min — Esc interrupts · /restart-tab restarts`);
+            this.#terminal.requestRender();
+        }, seconds * 1_000);
+        this.#residentProgressTimer.unref?.();
+    }
     async runWorkflow(request) {
         if (request.command === "quit")
             return this.shutdown();
@@ -1425,6 +1538,9 @@ export class OwnedUiSessionPresenter {
             if (this.#startupRouteTimer !== undefined)
                 clearTimeout(this.#startupRouteTimer);
             this.#startupRouteTimer = undefined;
+            if (this.#residentProgressTimer !== undefined)
+                clearTimeout(this.#residentProgressTimer);
+            this.#residentProgressTimer = undefined;
         });
         attempt(() => this.#promptSuggestions?.dispose());
         attempt(() => this.#unsubscribePromptSuggestions());
@@ -1461,6 +1577,8 @@ export class OwnedUiSessionPresenter {
             }
             await historyCleanup.catch(() => false); // Security: background durability outcomes never enter terminal output.
             await boundedCleanup(() => pasteCleanup).catch(error => settled.push(error));
+            await boundedCleanup(() => this.#residentTabOptions?.gracefulStop?.(this.#currentSessionFile()) ?? Promise.resolve())
+                .catch(error => settled.push(error));
             await boundedCleanup(() => this.backend.extensions.unbindExtensionUi()).catch(error => settled.push(error));
             return settled;
         };
@@ -1650,6 +1768,12 @@ export class OwnedUiSessionPresenter {
         const argument = separator < 0 ? "" : body.slice(separator + 1).trimStart();
         if (this.#routeHost?.claims(name))
             return this.#openOwnedRoute(name);
+        if (name === "restart-tab" && this.#residentTabOptions?.requestRestart !== undefined) {
+            const accepted = await this.#residentTabOptions.requestRestart().catch(() => false);
+            this.root.appendWorkflowStatus(accepted ? "Restarting resident tab…" : "Resident tab restart is unavailable.");
+            this.#terminal.requestRender();
+            return accepted ? { outcome: "completed", diagnostic: null } : rejected("resident tab restart is unavailable");
+        }
         if (this.#isWorkflowRoute(name))
             return this.runWorkflow({ command: name, argument });
         if (this.#skillsCollapsed()) {
@@ -1920,16 +2044,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,8 @@ 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";
+import { ResidentTabRecovery } from "../foundation/resident-tabs/recovery.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 +57,29 @@ 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;
+        readonly dataDir: string;
+        readonly incarnation: number;
+    };
+    /** 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">, recovery?: Pick<ResidentTabRecovery, "settled"> | null): Promise<() => void>;