@timurproko/a1 0.2.4 → 0.2.5-dev.698

package/dist/app/session-shell/prompt-suggestion-controller.d.ts

@@ -31,6 +31,8 @@ export declare class ContextualPromptSuggestionController {
     invalidate(): void;
     /** Retires only a generating request; a prepared or available suggestion survives the draft edit. */
     abortPending(): void;
+    /** Reasserts retained ghost text after an editor mutation makes the prompt eligible again. */
+    restoreAvailable(): void;
     dispose(): void;
 }
 export declare function samePromptSuggestionIdentity(left: OwnedUiPromptSuggestionIdentity, right: OwnedUiPromptSuggestionIdentity): boolean;

package/dist/app/session-shell/prompt-suggestion-controller.js

@@ -100,6 +100,16 @@ export class ContextualPromptSuggestionController {
         this.#finish(request, "cancelled");
         request.abort.abort();
     }
+    /** Reasserts retained ghost text after an editor mutation makes the prompt eligible again. */
+    restoreAvailable() {
+        if (this.#disposed || !this.#enabled || this.#state.status !== "available")
+            return;
+        const reason = this.options.surface.presentationBlockReason?.(this.#state.identity)
+            ?? (this.options.surface.canPresent(this.#state.identity) ? null : "presentation-unavailable");
+        if (reason !== null || !this.options.surface.present(this.#state.text))
+            return;
+        this.options.surface.requestRender();
+    }
     dispose() {
         this.#disposed = true;
         this.invalidate();

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

@@ -257,6 +257,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     setViewportOverlaySurfaces(surfaces: readonly PiTuiPointerSurface[] | null): void;
     viewportInputGeometryReady(width: number, height: number): boolean;
     handleViewportPreInput(data: string, allowWheel?: boolean, now?: number, editorActive?: boolean): SessionViewportInputResult;
+    dismissNotice(): void;
     layoutRoot(): PiTuiLayoutNode;
     transcriptComponent(id: string): PiShellTranscriptComponentPort | undefined;
     exitTranscript(width: number): string;

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

@@ -9,7 +9,7 @@ import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES } from
 import { createPiExtensionUiBridge } from "../../integrations/pi/components/shell-extension-ui.js";
 import { createPiShellEditor } from "../../integrations/pi/components/shell-editor-autocomplete.js";
 import { createPiQueuedInputStatus, createPiShellFooter, createPiShellHeader, createPiShellLoadedResources, createPiShellStatus, } from "../../integrations/pi/components/shell-footer-status.js";
-import { createPiShellArmin, createPiShellAuthProviderSelector, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellExtensionSelector, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, } from "../../integrations/pi/components/shell-selectors-dialogs.js";
+import { createPiShellArmin, createPiShellAuthProviderSelector, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellExtensionSelector, createPiShellLoginDialog, createPiShellModelSelector, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, } from "../../integrations/pi/components/shell-selectors-dialogs.js";
 import { createPiShellChangelog, createPiShellCollapsedChangelog, createPiShellHotkeys, createPiShellSessionInfo, renderPiShellCommandMessage, renderPiShellPackageUpdateNotice, renderPiShellReleaseUpdateBanner, renderPiShellReleaseUpdateNotice, renderPiShellStatusText, } from "../../integrations/pi/components/shell-presenters-info.js";
 import { createPiShellTranscriptComponent, isPiPromptStyleCompaction, paintPiSubmittedPromptTimestamp, renderPiShellStartupDiagnostic, renderPiShellTranscriptBlock, } from "../../integrations/pi/components/shell-presenters-transcript.js";
 import { onPiThemeChange, PINNED_PI_LAYOUT, piTheme } from "../../integrations/pi/components/upstream/theme/theme.js";
@@ -286,7 +286,7 @@ export class OwnedUiSessionShellRoot {
     reconcilePromptImageLimitNotice(text = this.editor.getText()) {
         if (this.#dockNotice?.errorCode !== "image-count" || !this.#promptChips.imageLimitState(text).corrected)
             return false;
-        this.#dismissDockNotice();
+        this.dismissNotice();
         return true;
     }
     hasPendingPastes(text) { return this.#promptChips.hasPending(text); }
@@ -333,6 +333,10 @@ export class OwnedUiSessionShellRoot {
         }
         const promptAccepted = this.#view.lifecycle !== "busy" && view.lifecycle === "busy";
         this.#view = view;
+        // Invariant: the idle new-session confirmation yields to the first truthful live status;
+        // ordinary dock notices deliberately remain visible below Working during a run.
+        if (promptAccepted && this.#dockNotice?.kind === "new-session")
+            this.#dockNotice = undefined;
         if (promptAccepted && this.#imageSubmissionsSending > 0) {
             this.#imageSubmissionsSending = 0;
             this.#syncWorkingOverride();
@@ -375,7 +379,7 @@ export class OwnedUiSessionShellRoot {
         // Invariant: the notice answers the reader's last command, so only their next prompt or
         // shell command retires it; assistant, tool, and compaction blocks streaming in keep it.
         if (block.kind === "user" || block.kind === "bash")
-            this.#dismissDockNotice();
+            this.dismissNotice();
         const created = createPiShellTranscriptComponent(block, this.#cwd, this.#extensionRenderers, this.#submittedPromptComposer, this.#outputPad, !this.#thinkingVisible, this.#mermaidRenderingMode, this.#showImages, this.#imageWidthCells, this.#imageAssets, { ...this.#componentRuntime, changed: () => {
                 if (this.#transcript.get(block.id) !== created)
                     return;
@@ -657,9 +661,12 @@ export class OwnedUiSessionShellRoot {
             // Compatibility: Pi pads its status text by one cell regardless of the output pad setting.
             return ["", ...renderPiShellStatusText(notice.message, width, PINNED_PI_LAYOUT.outputPad)];
         }
-        return renderPiShellCommandMessage({ kind: notice.kind, message: notice.message }, width, this.#outputPad);
+        return renderPiShellCommandMessage({
+            kind: notice.kind === "new-session" ? "accent" : notice.kind,
+            message: notice.message,
+        }, width, this.#outputPad);
     }
-    #dismissDockNotice() {
+    dismissNotice() {
         if (this.#dockNotice === undefined)
             return;
         this.#dockNotice = undefined;
@@ -960,6 +967,12 @@ export class OwnedUiSessionShellRoot {
         }
         if (result.outcome === "completed" && (result.command === "quit" || result.command === "compact"))
             return;
+        if (result.outcome === "completed" && result.command === "new" && this.#customViewport) {
+            // Rationale: bare A1 keeps the replacement session visually empty while preserving Pi's accent notice shape.
+            this.#dockNotice = { kind: "new-session", message: result.message };
+            this.#invalidateChrome();
+            return;
+        }
         if (result.outcome === "completed" && (result.command === "new" || result.command === "name" || result.command === "debug")) {
             this.#lastWorkflowStatusId = undefined;
             const presentation = { kind: result.command, message: result.message, ...(result.detail === undefined ? {} : { detail: result.detail }) };
@@ -1247,7 +1260,7 @@ export class OwnedUiSessionShellRoot {
     }
     #appendAnchoredWorkflowComponent(render, dispose) {
         // Invariant: transcript-bound workflow output supersedes a pending acknowledgement.
-        this.#dismissDockNotice();
+        this.dismissNotice();
         this.#workflowTranscriptSequence += 1;
         const id = `workflow-status-${this.#workflowTranscriptSequence}`;
         const component = {

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

@@ -14,7 +14,7 @@ import { createPiExtensionUiBridge } from "../../integrations/pi/components/shel
 import { createPiShellEditor } from "../../integrations/pi/components/shell-editor-autocomplete.js";
 import { SKILLS_COMMAND_NAME, findSkillByArgument, rewriteSkillsTunnelSubmission, skillPrompt, skillsFromCommands, } from "../../integrations/pi/components/skills-command.js";
 import { createPiQueuedInputStatus, createPiShellFooter, createPiShellHeader, createPiShellLoadedResources, createPiShellStatus, } from "../../integrations/pi/components/shell-footer-status.js";
-import { createPiShellArmin, createPiShellAuthProviderSelector, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellExtensionSelector, createPiShellLoginDialog, createPiShellModelSelector, createPiShellModelsDialog, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellSkillsSelector, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, } from "../../integrations/pi/components/shell-selectors-dialogs.js";
+import { createPiShellArmin, createPiShellAuthProviderSelector, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellExtensionSelector, createPiShellLoginDialog, createPiShellModelSelector, createPiShellModelsDialog, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellSkillsSelector, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, } from "../../integrations/pi/components/shell-selectors-dialogs.js";
 import { createPiShellChangelog, createPiShellHotkeys, createPiShellSessionInfo, renderPiShellPackageUpdateNotice, renderPiShellStatusText, } from "../../integrations/pi/components/shell-presenters-info.js";
 import { createPiShellTranscriptComponent, renderPiShellStartupDiagnostic, renderPiShellTranscriptBlock, } from "../../integrations/pi/components/shell-presenters-transcript.js";
 import { onPiThemeChange, piTheme } from "../../integrations/pi/components/upstream/theme/theme.js";
@@ -188,6 +188,11 @@ export class OwnedUiSessionShell {
             onEditorChange: text => {
                 this.#editorRevision++;
                 promptSuggestionController?.abortPending();
+                if (text.length === 0) {
+                    // Concurrency: the editor synchronizes deletion-owned autocomplete after onChange.
+                    // Reassert retained ghost text in the microtask before Pi emits its scheduled frame.
+                    queueMicrotask(() => promptSuggestionController?.restoreAvailable());
+                }
                 this.root.reconcilePromptImageLimitNotice(text);
             },
             onPromptSuggestionAccepted: () => promptSuggestionController?.accept(),
@@ -358,12 +363,20 @@ export class OwnedUiSessionShell {
             ? this.runtime.addPreInputListener(data => {
                 if (inputPresentation?.coordination === false)
                     this.#streamPresentation.noteImmediatePresentation();
-                // Compatibility: Pi's fullscreen renderer also intercepts plain Home/End.
-                // Deliver them to the focused owned input before that outer scroll handler;
-                // overlays retain Pi's normal dispatch, and comparison profiles never enter here.
+                // Compatibility: route modal paging and boundary keys before Pi's fullscreen handlers.
+                const isDefault = this.root.usesDefaultInputSurface();
+                if (!this.runtime.hasOverlay() && !isDefault
+                    && (this.root.editor.matchesTerminalKey(data, "pageUp")
+                        || this.root.editor.matchesTerminalKey(data, "pageDown"))) {
+                    this.root.handleInput(data);
+                    this.runtime.requestRender();
+                    return { consume: true };
+                }
                 if (!this.runtime.hasOverlay() && (this.root.editor.matchesTerminalKey(data, "home")
-                    || this.root.editor.matchesTerminalKey(data, "end"))) {
-                    if (this.root.usesDefaultInputSurface())
+                    || this.root.editor.matchesTerminalKey(data, "end")
+                    || !isDefault && (this.root.editor.matchesTerminalKey(data, "ctrl+home")
+                        || this.root.editor.matchesTerminalKey(data, "ctrl+end")))) {
+                    if (isDefault)
                         this.root.handleViewportPreInput(data, true);
                     this.root.handleInput(data);
                     this.runtime.requestRender();
@@ -1064,12 +1077,14 @@ export class OwnedUiSessionShell {
             },
             onCancel: close,
             onSelect: entryId => {
-                close();
                 if (entryId === context.currentLeafId) {
+                    close();
                     this.root.appendWorkflowStatus("Already at this point");
                     this.runtime.requestRender();
                     return;
                 }
+                if (context.skipSummaryPrompt)
+                    close();
                 void this.#completeTreeSelection(entryId, context.skipSummaryPrompt);
             },
         });
@@ -1205,6 +1220,19 @@ export class OwnedUiSessionShell {
     async runWorkflow(request) {
         if (request.command === "quit")
             return this.shutdown();
+        if (this.#customViewport && request.command === "name" && request.argument.trim().length === 0) {
+            void this.#extensionBridge.input("Session Name", "Enter name").then(value => {
+                if (this.#disposed || value === undefined || value.trim().length === 0)
+                    return;
+                return this.runWorkflow({ ...request, argument: value });
+            }).catch(error => {
+                if (this.#disposed)
+                    return;
+                this.root.appendWorkflowResult({ command: "name", outcome: "failed", message: error instanceof Error ? error.message : String(error) });
+                this.runtime.requestRender();
+            });
+            return { outcome: "completed", diagnostic: null };
+        }
         const copyGeneration = request.command === "copy" ? this.backend.sessionBindingGeneration : undefined;
         if (request.command === "login" && request.selection !== undefined) {
             const setup = this.backend.pinnedAmbientAuthentication(request.selection);
@@ -1280,13 +1308,15 @@ export class OwnedUiSessionShell {
             }
             this.root.resetExtensionUi();
         }
-        const shareSurface = request.command === "share"
-            ? createPiShellOperationLoader({
+        const shareDialog = request.command === "share"
+            ? await import("./share-operation.js")
+            : undefined;
+        const shareSurface = shareDialog === undefined ? undefined
+            : (this.#customViewport ? shareDialog.createPiShellShareOperationDialog : shareDialog.createPiShellOperationLoader)({
                 getColumns: () => this.runtime.viewport().columns,
                 getRows: () => this.runtime.viewport().rows,
                 requestRender: () => this.runtime.requestRender(),
-            }, "Creating gist...")
-            : undefined;
+            }, "Creating gist…");
         const operationSurface = shareSurface ?? (request.command === "reload" ? createPiShellReloadBox() : undefined);
         const now = this.#reloadPresentation?.now ?? Date.now;
         const shownAt = now();
@@ -1342,7 +1372,17 @@ export class OwnedUiSessionShell {
             this.root.editor.reloadKeybindings();
             this.#installAutocompleteCommands();
         }
-        this.root.appendWorkflowResult(result);
+        if (request.command === "tree" && result.outcome === "completed") {
+            if (result.detail && !this.root.editor.getText().trim())
+                this.root.editor.setText(result.detail);
+            this.root.resumeViewportFollowing();
+        }
+        if (shareDialog !== undefined && this.#customViewport && result.outcome === "completed" && result.detail !== undefined) {
+            this.root.appendWorkflowStatus(shareDialog.renderPiShellShareResult(result.message, result.detail));
+        }
+        else {
+            this.root.appendWorkflowResult(result);
+        }
         this.runtime.requestRender();
         return workflowAdapterResult(result);
     }
@@ -1768,6 +1808,7 @@ export class OwnedUiSessionShell {
             return { outcome: "failed", diagnostic: `route is unavailable: ${route}` };
         if (!this.runtime.active)
             return { outcome: "failed", diagnostic: "runtime is not active" };
+        this.root.dismissNotice();
         this.#dialogHandle?.hide();
         this.#dialogSource = "route";
         // Protocol: any-event reporting: hover and drag are what the screen is driven by, and
@@ -1780,6 +1821,19 @@ export class OwnedUiSessionShell {
         const removeInterruptWatch = this.runtime.addInputListener(data => {
             if (!data.includes(INTERRUPT))
                 return undefined;
+            // Protocol: route hosts decide whether one interrupt closes their app. Raw-input forwarding
+            // is required because Pi handles Ctrl+C before the fullscreen overlay receives normal input.
+            const consumedBySurface = surface.handleInput(INTERRUPT);
+            if (surface.isClosed()) {
+                armedAt = 0;
+                closeSurface();
+                return { consume: true };
+            }
+            if (consumedBySurface) {
+                armedAt = 0;
+                this.runtime.requestRender();
+                return { consume: true };
+            }
             const now = Date.now();
             if (armedAt !== 0 && now - armedAt <= INTERRUPT_CHORD_MS) {
                 armedAt = 0;
@@ -1968,7 +2022,7 @@ export class OwnedUiSessionShell {
         }
         return this.#submitSkillPrompt(skillPrompt(skill.name, separator < 0 ? "" : trimmed.slice(separator + 1)), text);
     }
-    // Rationale: the engine expands "/skill:<name> args" itself; history keeps the form the user typed so recall restores the invocation.
+    // Rationale: engine expands skill arguments; history retains typed input for recall.
     #submitSkillPrompt(prompt, typed) {
         this.#rememberInput(typed, "slash");
         this.root.resumeViewportFollowing();
@@ -1979,29 +2033,33 @@ export class OwnedUiSessionShell {
             text: prompt,
         });
     }
+    #treeSummary() {
+        return new Promise(resolve => {
+            this.root.setInputSurface(createPiShellExtensionSelector("Summarize Branch?", ["No summary", "Summarize", "Summarize with custom prompt"], resolve, () => resolve(undefined)), true, "opaque");
+            this.runtime.requestRender();
+        });
+    }
     async #completeTreeSelection(entryId, skipSummaryPrompt) {
         let summarize = false;
         let customInstructions;
         if (!skipSummaryPrompt) {
             while (true) {
-                const choice = await this.#extensionBridge.context.select("Summarize branch?", [
-                    "No summary",
-                    "Summarize",
-                    "Summarize with custom prompt",
-                ]);
+                const choice = await this.#treeSummary();
                 if (choice === undefined) {
                     await this.showTreeSelector(entryId);
                     return;
                 }
                 summarize = choice !== "No summary";
                 if (choice === "Summarize with custom prompt") {
-                    customInstructions = await this.#extensionBridge.context.editor("Custom summarization instructions", "");
+                    customInstructions = await this.#extensionBridge.input("Custom Summarization Instructions", "", { retainSurfaceOnSettle: true });
                     if (customInstructions === undefined)
                         continue;
                 }
                 break;
             }
         }
+        this.root.setInputSurface(null);
+        this.runtime.requestRender();
         const result = await this.runWorkflow({
             command: "tree",
             argument: "",

package/dist/app/session-shell/share-operation.d.ts

@@ -0,0 +1,3 @@
+import { createPiShellOperationLoader, createPiShellShareOperationDialog } from "../../integrations/pi/components/index.js";
+export { createPiShellOperationLoader, createPiShellShareOperationDialog };
+export declare function renderPiShellShareResult(message: string, gistUrl: string): string;

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

@@ -0,0 +1,11 @@
+import { createPiShellOperationLoader, createPiShellShareOperationDialog, piShellHyperlink, piTheme, } from "../../integrations/pi/components/index.js";
+import { nativeHyperlinkStyle } from "../../ui/components/index.js";
+export { createPiShellOperationLoader, createPiShellShareOperationDialog };
+export function renderPiShellShareResult(message, gistUrl) {
+    const theme = piTheme();
+    const match = /^Share URL: (\S+)$/u.exec(message);
+    const linked = match === null
+        ? theme.fg("dim", message)
+        : `${theme.fg("dim", "Share URL: ")}${piShellHyperlink(match[1])}`;
+    return nativeHyperlinkStyle(`${linked}\n${theme.fg("dim", "Gist: ")}${piShellHyperlink(gistUrl)}`, text => theme.fg("mdLink", text));
+}

package/dist/composition/owned-ui.js

@@ -82,6 +82,7 @@ export async function composeOwnedUi(options = {}) {
             const { renderPiShellHotkeySections } = await import("../integrations/pi/components/shell-hotkey-sections.js");
             return { sections: width => renderPiShellHotkeySections(presentation, width) };
         },
+        session: () => import("./session-info-reference.js").then(m => m.loadSessionInfoReference(adapter)),
     };
     const routeHost = settings === null || !ownedSurfaces ? null : createOwnedRouteHost(settings, references);
     const viewportSettings = settings === null || !ownedSurfaces ? null : {

package/dist/composition/session-info-reference.d.ts

@@ -0,0 +1,4 @@
+import type { ReferenceDocumentProvider } from "../features/owned-ui/reference-screen-app.js";
+import type { PiEngineAdapter } from "../integrations/pi/engine/adapter.js";
+/** Captures one current session snapshot and adapts it to the neutral reference document. */
+export declare function loadSessionInfoReference(adapter: PiEngineAdapter): Promise<ReferenceDocumentProvider>;

package/dist/composition/session-info-reference.js

@@ -0,0 +1,20 @@
+import { renderPiShellSessionInfoReferenceDocument } from "../integrations/pi/components/shell-session-info-reference.js";
+/** Captures one current session snapshot and adapts it to the neutral reference document. */
+export async function loadSessionInfoReference(adapter) {
+    const result = await adapter.executeWorkflow({ command: "session", argument: "" });
+    if (result.outcome !== "completed")
+        throw new Error(result.message);
+    if (result.presentation?.kind !== "session-info")
+        throw new Error("Session workflow returned no structured information");
+    const presentation = result.presentation;
+    let cached = null;
+    const document = (width) => {
+        if (cached?.width !== width)
+            cached = { width, document: renderPiShellSessionInfoReferenceDocument(presentation, width) };
+        return cached.document;
+    };
+    return {
+        preamble: width => document(width).preamble,
+        sections: width => document(width).sections,
+    };
+}

package/dist/composition/settings-route-host.d.ts

@@ -7,10 +7,7 @@ export type OwnedReferenceRows = NonNullable<ReferenceDocumentProvider["rows"]>;
 export interface OwnedReferenceProviders {
     changelog(input?: UiRouteInput): Promise<ReferenceDocumentProvider>;
     hotkeys(): Promise<ReferenceDocumentProvider>;
+    session(): Promise<ReferenceDocumentProvider>;
 }
-/**
- * Declares the A1-owned settings route, and the changelog and hotkeys reference
- * routes when their documents are supplied, without evaluating their presentation
- * graphs during startup. Opening a route retains input while the optional module loads.
- */
+/** Declares settings and lazy document routes. */
 export declare function createOwnedRouteHost(settings: OwnedSettingsManager, references?: OwnedReferenceProviders): UiRouteHost;

package/dist/composition/settings-route-host.js

@@ -1,14 +1,10 @@
-import { CHANGELOG_APP_ID, CHANGELOG_ROUTE, CHANGELOG_TITLE, HOTKEYS_APP_ID, HOTKEYS_ROUTE, HOTKEYS_TITLE, } from "../features/owned-ui/reference-routes.js";
+import { CHANGELOG_ROUTE, CHANGELOG_TITLE, HOTKEYS_ROUTE, HOTKEYS_TITLE, } from "../features/owned-ui/reference-routes.js";
 import { SETTINGS_APP_ID, SETTINGS_ROUTE } from "../features/owned-ui/settings-route.js";
 import { piTheme } from "../integrations/pi/components/upstream/theme/theme.js";
 import { faint } from "../ui/components/text.js";
-/**
- * Declares the A1-owned settings route, and the changelog and hotkeys reference
- * routes when their documents are supplied, without evaluating their presentation
- * graphs during startup. Opening a route retains input while the optional module loads.
- */
+/** Declares settings and lazy document routes. */
 export function createOwnedRouteHost(settings, references) {
-    const routes = new Set([SETTINGS_ROUTE, ...(references === undefined ? [] : [CHANGELOG_ROUTE, HOTKEYS_ROUTE])]);
+    const routes = new Set([SETTINGS_ROUTE, ...(references === undefined ? [] : [CHANGELOG_ROUTE, HOTKEYS_ROUTE, "session"])]);
     return {
         claims: route => routes.has(route),
         open: (route, input) => {
@@ -18,10 +14,10 @@ export function createOwnedRouteHost(settings, references) {
                 return deferredSurface(SETTINGS_APP_ID, "settings", () => loadSettingsSurface(settings));
             }
             const changelog = route === CHANGELOG_ROUTE;
-            const id = changelog ? CHANGELOG_APP_ID : HOTKEYS_APP_ID;
-            const title = changelog ? CHANGELOG_TITLE : HOTKEYS_TITLE;
-            const document = changelog ? references.changelog(input) : references.hotkeys();
-            return deferredSurface(id, title, () => loadReferenceSurface(settings, id, route, title, document));
+            const session = route === "session";
+            const title = session ? "Session Info" : changelog ? CHANGELOG_TITLE : HOTKEYS_TITLE;
+            const document = session ? references.session() : changelog ? references.changelog(input) : references.hotkeys();
+            return deferredSurface(route, title, () => loadReferenceSurface(settings, route, route, title, document));
         },
     };
 }
@@ -135,7 +131,7 @@ function pinnedTheme() {
         bold: (text) => piTheme().bold(text),
         plain: (text) => text,
         disabled: (text) => faint(piTheme().fg("dim", text)),
-        highlight: (text) => `\u001b[48;2;82;82;82m\u001b[97m${text}\u001b[39m\u001b[49m`,
+        highlight: (text) => piTheme().bg("selectedBg", text),
         panel: (text) => `\u001b[48;2;55;55;55m${text}\u001b[49m`,
     };
 }

package/dist/contracts/presentation/index.d.ts

@@ -4,6 +4,11 @@ export interface SemanticShortcutHint {
     readonly action: string;
     readonly actionFirst?: boolean;
 }
+/** Canonical dismissal guidance for every A1-rendered dialog surface. */
+export declare const DIALOG_CLOSE_SHORTCUT_HINT: Readonly<{
+    key: string;
+    action: string;
+}>;
 export interface ShortcutHintRoles {
     key(label: string): string;
     action(name: string): string;

package/dist/contracts/presentation/index.js

@@ -1,3 +1,5 @@
+/** Canonical dismissal guidance for every A1-rendered dialog surface. */
+export const DIALOG_CLOSE_SHORTCUT_HINT = Object.freeze({ key: "esc", action: "close" });
 const SHORTCUT_KEY_NAMES = Object.freeze({
     alt: "Alt", backspace: "Backspace", cmd: "Cmd", ctrl: "Ctrl", delete: "Delete", down: "Down", end: "End",
     enter: "Enter", esc: "Esc", escape: "Escape", home: "Home", insert: "Insert", left: "Left", meta: "Meta",

package/dist/features/owned-ui/project-trust-dialog.js

@@ -1,7 +1,8 @@
-const ACCENT = "\u001b[38;2;138;190;183m";
-const BORDER = "\u001b[38;2;95;135;255m";
-const MUTED = "\u001b[38;2;128;128;128m";
-const DIM = "\u001b[38;2;102;102;102m";
+import { DIALOG_CLOSE_SHORTCUT_HINT, displayShortcutKeyLabel } from "../../contracts/presentation/index.js";
+const ACCENT = "\u001b[38;2;167;152;215m";
+const BORDER = "\u001b[38;2;97;133;204m";
+const MUTED = "\u001b[38;2;157;165;169m";
+const DIM = "\u001b[38;2;126;136;142m";
 const RESET_FG = "\u001b[39m";
 const BOLD = "\u001b[1m";
 const RESET_BOLD = "\u001b[22m";
@@ -13,7 +14,8 @@ export function renderProjectTrustDialog(cwd, options, selected, terminalWidth,
     const title = ` ${BOLD}${ACCENT}Trust project folder?${RESET_FG}${RESET_BOLD}`;
     const path = ` ${MUTED}${sanitize(cwd)}${RESET_FG}`;
     const choices = options.map((label, index) => choice(label, selected === index));
-    const hint = ` ${DIM}↑/↓${MUTED} to navigate  ${DIM}Enter${MUTED} to select  ${DIM}Esc${MUTED} to exit${RESET_FG}`;
+    const closeKey = displayShortcutKeyLabel(DIALOG_CLOSE_SHORTCUT_HINT.key);
+    const hint = ` ${DIM}↑↓${MUTED} navigate  ${DIM}Enter${MUTED} select  ${DIM}${closeKey}${MUTED} ${DIALOG_CLOSE_SHORTCUT_HINT.action}${RESET_FG}`;
     const explanation = wrap(EXPLANATION, Math.max(1, width - 2)).map(line => ` ${line}`);
     const preferred = [rule, title, path, "", ...explanation, "", ...choices, "", hint, rule];
     if (preferred.length <= terminalRows)

package/dist/features/owned-ui/reference-screen-app.d.ts

@@ -11,6 +11,8 @@ export interface ReferenceDocumentSection {
 export interface ReferenceDocumentProvider {
     /** Flat rows for this width, or null while the document is not available yet. */
     readonly rows?: (width: number) => readonly string[] | null;
+    /** Rows between the screen title and structured groups, absent for group-only documents. */
+    readonly preamble?: (width: number) => readonly string[] | null;
     /** Structured groups opt into shared Settings-style headers and pinning. */
     readonly sections?: (width: number) => readonly ReferenceDocumentSection[] | null;
     /** Settles once the selected content provider answers; absent when available at once. */
@@ -27,8 +29,8 @@ export interface ReferenceScreenOptions {
  * Presents one read-only document full screen between two accent rules: the bold
  * title leads the scrolled rows, the shared scrollbar rail runs beside them, and
  * the hint line closes the frame. Rows come from a provider per content width and
- * are cached until the width changes; the screen closes on Escape and leaves the
- * interrupt chord to its host.
+ * are cached until the width changes; Escape closes locally, while an opted-in
+ * host closes on Ctrl+C before dispatching it into the screen.
  */
 export declare class ReferenceScreenApp implements UiApp {
     #private;

package/dist/features/owned-ui/reference-screen-app.js

@@ -1,4 +1,5 @@
-import { GLOBAL_SCOPE, PLAIN_THEME, RAIL_COLUMNS, ShortcutRegistry, ScrollbarRails, assertNoShortcutConflicts, displayWidth, layoutList, padToWidth, renderGroupHeader, renderShortcutHints, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarWheelRows, truncateToWidth, withScrollbarRail, } from "../../ui/components/index.js";
+import { DIALOG_CLOSE_SHORTCUT_HINT } from "../../contracts/presentation/index.js";
+import { GLOBAL_SCOPE, PLAIN_THEME, RAIL_COLUMNS, ShortcutRegistry, ScrollbarRails, assertNoShortcutConflicts, displayWidth, layoutList, padToWidth, renderGroupHeader, renderShortcutHintsWithClose, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarWheelRows, truncateToWidth, withScrollbarRail, } from "../../ui/components/index.js";
 const SCOPE = "reference-screen";
 /** Rows above the document: the top rule. */
 const HEADER_ROWS = 1;
@@ -9,14 +10,17 @@ const SCROLL_LINGER_MS = 900;
 const SCROLL_LINGER_REPAINT_MS = 925;
 const LOADING_NOTICE = "Loading…";
 export const REFERENCE_SCREEN_SHORTCUTS = new ShortcutRegistry();
-// Compatibility: Ctrl+C remains the A1 interrupt chord here rather than a close key.
-REFERENCE_SCREEN_SHORTCUTS.declare({ key: "escape", scope: GLOBAL_SCOPE, description: "Close", section: "Screen", hint: { keys: "esc", does: "close" } }, "close");
 REFERENCE_SCREEN_SHORTCUTS.declare({ key: "up", scope: SCOPE, description: "Scroll up", section: "Navigate", hint: { keys: "↑↓", does: "scroll" } }, "up");
 REFERENCE_SCREEN_SHORTCUTS.declare({ key: "down", scope: SCOPE, description: "Scroll down", section: "Navigate", hint: { keys: "↑↓", does: "scroll" } }, "down");
 REFERENCE_SCREEN_SHORTCUTS.declare({ key: "pageUp", scope: SCOPE, description: "Up a page", section: "Navigate" }, "page-up");
 REFERENCE_SCREEN_SHORTCUTS.declare({ key: "pageDown", scope: SCOPE, description: "Down a page", section: "Navigate" }, "page-down");
 REFERENCE_SCREEN_SHORTCUTS.declare({ key: "home", scope: SCOPE, description: "First row", section: "Navigate" }, "first");
 REFERENCE_SCREEN_SHORTCUTS.declare({ key: "end", scope: SCOPE, description: "Last row", section: "Navigate" }, "last");
+// Compatibility: Ctrl+C remains the A1 interrupt chord here rather than a visible close key.
+REFERENCE_SCREEN_SHORTCUTS.declare({
+    key: "escape", scope: GLOBAL_SCOPE, description: "Close", section: "Screen",
+    hint: { keys: DIALOG_CLOSE_SHORTCUT_HINT.key, does: DIALOG_CLOSE_SHORTCUT_HINT.action },
+}, "close");
 assertNoShortcutConflicts(REFERENCE_SCREEN_SHORTCUTS.assemble());
 const KEYS = {
     "\u001b[A": "up",
@@ -36,8 +40,8 @@ const KEYS = {
  * Presents one read-only document full screen between two accent rules: the bold
  * title leads the scrolled rows, the shared scrollbar rail runs beside them, and
  * the hint line closes the frame. Rows come from a provider per content width and
- * are cached until the width changes; the screen closes on Escape and leaves the
- * interrupt chord to its host.
+ * are cached until the width changes; Escape closes locally, while an opted-in
+ * host closes on Ctrl+C before dispatching it into the screen.
  */
 export class ReferenceScreenApp {
     id;
@@ -135,7 +139,7 @@ export class ReferenceScreenApp {
         const withRail = withScrollbarRail(body.slice(0, bodyHeight), geometry, contentWidth, theme, { presentation });
         const hint = this.#interruptArmed
             ? theme.fg("dim", " press ctrl+c again to exit a1")
-            : renderShortcutHints(REFERENCE_SCREEN_SHORTCUTS.hintEntries(SCOPE), theme, 1);
+            : renderShortcutHintsWithClose(REFERENCE_SCREEN_SHORTCUTS.hintEntries(SCOPE), theme, rect.width, 1);
         // Compatibility: the v2 reference screen frames its document between two border-coloured rules.
         const rule = theme.fg("border", "─".repeat(rect.width));
         // Invariant: dialog chrome shares the title's one-cell inset; document content keeps its own layout.
@@ -222,10 +226,16 @@ export class ReferenceScreenApp {
         if (cached !== null && cached.width === width)
             return this.#withTitle(cached.content, title);
         const sections = this.#document.sections?.(width);
-        if (sections === null)
+        const preamble = sections === undefined ? undefined : this.#document.preamble?.(width);
+        if (sections === null || preamble === null)
             return { kind: "flat", rows: [title, "", LOADING_NOTICE] };
         if (sections !== undefined) {
             const rows = [];
+            if (preamble !== undefined && preamble.length > 0) {
+                for (const row of preamble)
+                    rows.push({ kind: "note", group: "", text: row });
+                rows.push({ kind: "spacer" });
+            }
             sections.forEach((section, sectionIndex) => {
                 if (sectionIndex > 0)
                     rows.push({ kind: "spacer" });

package/dist/features/owned-ui/settings-app.js

@@ -1,4 +1,5 @@
-import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderListRow, renderNote, renderShortcutHints, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, truncateToWidth, valueColumnFor, valueMenuFrame, blockRowSpan, displayWidth, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, ScrollbarRails, scrollbarWheelRows, selectableIndexes, } from "../../ui/components/index.js";
+import { DIALOG_CLOSE_SHORTCUT_HINT } from "../../contracts/presentation/index.js";
+import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderListRow, renderNote, renderShortcutHintsWithClose, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, truncateToWidth, valueColumnFor, valueMenuFrame, blockRowSpan, displayWidth, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, ScrollbarRails, scrollbarWheelRows, selectableIndexes, } from "../../ui/components/index.js";
 import { SETTINGS_APP_ID, SETTINGS_ROUTE } from "./settings-route.js";
 export { SETTINGS_APP_ID, SETTINGS_ROUTE } from "./settings-route.js";
 const SCOPE = SETTINGS_APP_ID;
@@ -35,13 +36,16 @@ SETTINGS_SHORTCUTS.declare({ key: "enter", scope: SCOPE, description: "Change va
 SETTINGS_SHORTCUTS.declare({ key: "space", scope: SCOPE, description: "Change value", section: "Change", hint: { keys: "Enter/Space", does: "to change" } }, "activate");
 SETTINGS_SHORTCUTS.declare({ key: "left", scope: SCOPE, description: "Previous value", section: "Change", hint: { keys: "←→", does: "to adjust" } }, "previous-value");
 SETTINGS_SHORTCUTS.declare({ key: "right", scope: SCOPE, description: "Next value", section: "Change", hint: { keys: "←→", does: "to adjust" } }, "next-value");
-SETTINGS_SHORTCUTS.declare({ key: "escape", scope: GLOBAL_SCOPE, description: "Close", section: "Screen", hint: { keys: "Esc", does: "to cancel" } }, "close");
 SETTINGS_SHORTCUTS.declare({ key: "enter", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts", hint: { keys: "Enter/Space", does: "to change" } }, "part-change");
 SETTINGS_SHORTCUTS.declare({ key: "space", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts", hint: { keys: "Enter/Space", does: "to change" } }, "part-change");
 SETTINGS_SHORTCUTS.declare({ key: "left", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts" }, "part-change");
 SETTINGS_SHORTCUTS.declare({ key: "right", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts" }, "part-change");
 SETTINGS_SHORTCUTS.declare({ key: "up", scope: DIALOG_SCOPE, description: "Previous part", section: "Parts" }, "part-previous");
 SETTINGS_SHORTCUTS.declare({ key: "down", scope: DIALOG_SCOPE, description: "Next part", section: "Parts" }, "part-next");
+SETTINGS_SHORTCUTS.declare({
+    key: "escape", scope: GLOBAL_SCOPE, description: "Close", section: "Screen",
+    hint: { keys: DIALOG_CLOSE_SHORTCUT_HINT.key, does: DIALOG_CLOSE_SHORTCUT_HINT.action },
+}, "close");
 assertNoShortcutConflicts(SETTINGS_SHORTCUTS.assemble());
 const KEYS = {
     "\u001b[A": "up",
@@ -451,8 +455,9 @@ export class SettingsApp {
             return;
         }
         const current = shown === null ? 0 : Math.max(0, entry.choices.indexOf(shown));
-        // Compatibility: pinned SelectList opens on the value currently in effect.
-        this.#menu = { entry, current, anchorKey: `${entry.backend}:${entry.id}`, choices: entry.choices, index: current };
+        // Invariant: the opening press targeted the setting value, not an option. Keep the
+        // effective value as the keyboard origin without painting it as pointer-picked.
+        this.#menu = { entry, current, anchorKey: `${entry.backend}:${entry.id}`, choices: entry.choices, index: -1 };
     }
     // Rationale: a structured setting opens as its own flag list rather than a value menu.
     #openStructured(entry) {
@@ -797,7 +802,7 @@ export class SettingsApp {
             ? notice
             : this.#interruptArmed ? "press ctrl+c again to exit a1" : null;
         const status = plainStatus === null
-            ? truncateToWidth(renderShortcutHints(SETTINGS_SHORTCUTS.hintEntries(SCOPE), theme, width > 0 ? 1 : 0), width)
+            ? renderShortcutHintsWithClose(SETTINGS_SHORTCUTS.hintEntries(SCOPE), theme, width, width > 0 ? 1 : 0)
             : truncateToWidth(`${width > 0 ? " " : ""}${theme.fg("dim", plainStatus)}`, width);
         const input = this.#filter;
         if (input === null)

package/dist/foundation/release/progress-palette.generated.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generated by scripts/pi/sync-progress-palette.ts from @earendil-works/pi-coding-agent 1.0.2
- * (MIT), commit cd32f7725fdbddbaecdff5b1e68491563394e0ca. Do not edit directly.
+ * Generated by scripts/pi/sync-progress-palette.ts from @earendil-works/pi-coding-agent 1.0.4
+ * (MIT), commit 7c10bd4337495ee613f2224843ecdf349b80d1df. Do not edit directly.
  */
 export declare const SHARED_PROGRESS_ACCENT_ANSI = "\u001B[38;2;167;152;215m";

package/dist/foundation/release/progress-palette.generated.js

@@ -1,5 +1,5 @@
 /**
- * Generated by scripts/pi/sync-progress-palette.ts from @earendil-works/pi-coding-agent 1.0.2
- * (MIT), commit cd32f7725fdbddbaecdff5b1e68491563394e0ca. Do not edit directly.
+ * Generated by scripts/pi/sync-progress-palette.ts from @earendil-works/pi-coding-agent 1.0.4
+ * (MIT), commit 7c10bd4337495ee613f2224843ecdf349b80d1df. Do not edit directly.
  */
 export const SHARED_PROGRESS_ACCENT_ANSI = "\u001b[38;2;167;152;215m";