@timurproko/a1 0.2.6-dev.727 → 0.2.6-dev.734

package/dist/integrations/pi/session-presenters/presenters.js

@@ -0,0 +1,341 @@
+import { createPiShellModelSelector, createPiShellModelsDialog, createPiShellScopedModelsSelector, createPiShellSessionSelector, createPiShellSettingsSelector, } from "../components/shell-selectors-dialogs.js";
+const MODEL_REFRESH_TIMEOUT_MS = 15_000;
+const MODEL_REFRESH_TIMED_OUT = "Model refresh timed out; showing cached models.";
+/**
+ * Builds the selectors and transcript renderers whose inputs are Pi engine objects. This owner is the one place
+ * that sees both the engine adapter and the Pi components, so the shell only ever holds the neutral port.
+ */
+export function createPiSessionPresenters(adapter, options = {}) {
+    const source = () => adapter.presentationSource();
+    let lazySelectors = options.lazySelectors;
+    let lazySelectorsPromise;
+    // Performance: the tree selector module stays out of the startup graph and loads on first use.
+    const loadLazySelectors = () => {
+        if (lazySelectors !== undefined)
+            return Promise.resolve(lazySelectors);
+        return lazySelectorsPromise ??= import("../components/lazy-selectors.js").then(module => {
+            lazySelectors = module.piShellLazySelectors;
+            return module.piShellLazySelectors;
+        });
+    };
+    const renderers = {
+        getMessageRenderer: customType => opaqueRenderer(source().pinnedMessageRenderer(customType)),
+        getToolRenderers: toolName => opaqueRenderer(source().pinnedToolRenderers(toolName)),
+        // Compatibility: the component adapter passes Pi's own keybinding config through the neutral port.
+        getShortcuts: bindings => source().pinnedShortcutDescriptions(bindings),
+    };
+    return {
+        transcriptRenderers: () => renderers,
+        openModelSelector(host, initialSearchInput) {
+            const context = source().pinnedModelSelectorContext();
+            const close = closeSurface(host);
+            const component = createPiShellModelSelector({
+                ...context,
+                runtime: {
+                    getColumns: () => host.viewport().columns,
+                    getRows: () => host.viewport().rows,
+                    requestRender: () => host.requestRender(),
+                },
+                ...(initialSearchInput === undefined ? {} : { initialSearchInput }),
+                onSelect: model => {
+                    close();
+                    void host.runWorkflow({ command: "model", argument: "", selection: modelReference(model) });
+                },
+                onSelectAsDefault: model => {
+                    close();
+                    void host.runWorkflow({ command: "model", argument: "", selection: modelReference(model), persist: true });
+                },
+                onCancel: close,
+            });
+            host.setInputSurface(component);
+            host.requestRender();
+        },
+        async openSessionSelector(host, onExit) {
+            const context = source().pinnedSessionSelectorContext();
+            const close = closeSurface(host);
+            const component = await createPiShellSessionSelector({
+                currentSessionsLoader: context.loadCurrentSessions,
+                allSessionsLoader: context.loadAllSessions,
+                currentSessionFilePath: context.currentSessionFilePath,
+                renameSession: context.renameSession,
+                requestRender: () => host.requestRender(),
+                onSelect: sessionPath => {
+                    close();
+                    void host.runWorkflow({ command: "resume", argument: sessionPath });
+                },
+                onCancel: close,
+                onExit: () => {
+                    close();
+                    onExit();
+                },
+            });
+            host.setInputSurface(component);
+            host.requestRender();
+        },
+        async openTreeSelector(host, navigate, initialSelectedId) {
+            const context = source().pinnedTreeSelectorContext();
+            if (context.tree.length === 0) {
+                host.appendWorkflowStatus("No entries in session");
+                host.requestRender();
+                return;
+            }
+            const close = closeSurface(host);
+            const releasePresentation = host.beginPresentationHold?.();
+            try {
+                const selectors = await loadLazySelectors();
+                const component = await selectors.createTree({
+                    tree: context.tree,
+                    currentLeafId: context.currentLeafId,
+                    terminalHeight: host.viewport().rows,
+                    initialFilterMode: context.filterMode,
+                    ...(initialSelectedId === undefined ? {} : { initialSelectedId }),
+                    onLabelChange: context.appendLabelChange,
+                    onCopy: text => {
+                        if (!text) {
+                            host.appendWorkflowResult({ command: "tree", outcome: "failed", message: "Selected entry has no text to copy" });
+                            host.requestRender();
+                            return;
+                        }
+                        const generation = adapter.identity.sessionBindingGeneration;
+                        const stale = () => host.disposed || generation !== adapter.identity.sessionBindingGeneration;
+                        void adapter.workflows.copyWorkflowText(text).then(acknowledged => {
+                            if (stale())
+                                return;
+                            host.appendWorkflowStatus(acknowledged ? "Copied selected message to clipboard" : "Submitted selected message to clipboard");
+                            host.requestRender();
+                        }).catch(error => {
+                            if (stale())
+                                return;
+                            host.appendWorkflowResult({ command: "tree", outcome: "failed", message: error instanceof Error ? error.message : String(error) });
+                            host.requestRender();
+                        });
+                    },
+                    onCancel: close,
+                    onSelect: entryId => {
+                        if (entryId === context.currentLeafId) {
+                            close();
+                            host.appendWorkflowStatus("Already at this point");
+                            host.requestRender();
+                            return;
+                        }
+                        if (context.skipSummaryPrompt)
+                            close();
+                        navigate(entryId, context.skipSummaryPrompt);
+                    },
+                });
+                if (host.disposed)
+                    return;
+                host.setInputSurface(component);
+                host.requestRender();
+            }
+            finally {
+                releasePresentation?.();
+            }
+        },
+        openSettingsSelector(host) {
+            const snapshot = adapter.settings.snapshot();
+            const { currentModel, availableDefaultModels } = source().pinnedSettingsModels();
+            const close = closeSurface(host);
+            const component = createPiShellSettingsSelector({
+                config: {
+                    ...snapshot,
+                    availableThinkingLevels: [...snapshot.availableThinkingLevels],
+                    availableThemes: [...snapshot.availableThemes],
+                    warnings: { ...snapshot.warnings },
+                    modelThinkingLevels: { ...snapshot.modelThinkingLevels },
+                    ...(currentModel === undefined ? {} : { currentModel: currentModel }),
+                    availableDefaultModels: availableDefaultModels,
+                },
+                onChange: (callback, value) => {
+                    if (callback === "onCancel") {
+                        close();
+                        return;
+                    }
+                    if (callback === "onTuiModeChange") {
+                        // Invariant: a surface that cannot change TUI mode (bare A1 is permanently fullscreen) ignores this callback.
+                        if (host.switchTuiMode === undefined)
+                            return;
+                        if (value !== "regular" && value !== "fullscreen")
+                            return;
+                        if (!host.switchTuiMode(value)) {
+                            host.appendWorkflowStatus("Close active overlays before changing TUI mode");
+                            host.requestRender();
+                            return;
+                        }
+                    }
+                    void source().applyPinnedSettingValue(callback, value).then(result => {
+                        if (result.outcome === "failed")
+                            host.appendWorkflowResult(result);
+                        else if (callback === "onTuiModeChange")
+                            host.appendWorkflowStatus(`TUI mode: ${value}`);
+                        host.requestRender();
+                    });
+                },
+                onCancel: close,
+            });
+            host.setInputSurface(component);
+            host.requestRender();
+        },
+        /** The bare-A1 unified Models dialog: switch on Enter, scope on Space, persist on Ctrl+S, all through the engine. */
+        openModelsDialog(host, initialQuery) {
+            const catalog = adapter.catalog;
+            const context = catalog.modelsContext();
+            const available = new Set(context.models.map(model => `${model.provider}/${model.id}`));
+            const savedScopeIds = context.persistedScopeIds.filter(id => available.has(id));
+            // Invariant: an explicit session scope wins; otherwise the dialog starts from what is persisted, never from "all rows scoped".
+            const scopeIds = context.sessionScopeIds.length > 0 ? context.sessionScopeIds : savedScopeIds;
+            const refresh = new ModelCatalogRefresh();
+            const close = () => {
+                refresh.stop();
+                host.setInputSurface(null);
+                host.requestRender();
+            };
+            const dialog = createPiShellModelsDialog({
+                models: context.models,
+                activeModelId: context.activeModelId,
+                scopeIds,
+                savedScopeIds,
+                ...(initialQuery === undefined ? {} : { initialQuery }),
+                refreshStatus: "Refreshing model catalogs…",
+                requestRender: () => host.requestRender(),
+                onSelect: modelId => {
+                    void host.runWorkflow({ command: "models", argument: "", selection: modelId }).then(result => {
+                        if (!refresh.stopped && result.outcome === "completed")
+                            close();
+                    });
+                },
+                onScopeChange: ids => {
+                    catalog.setSessionModelScope(ids);
+                    host.requestRender();
+                },
+                onSave: ids => {
+                    try {
+                        catalog.persistModelScope(ids);
+                    }
+                    catch (error) {
+                        host.appendWorkflowResult({ command: "models", outcome: "failed", message: error instanceof Error ? error.message : String(error) });
+                        host.requestRender();
+                        throw error;
+                    }
+                    host.appendWorkflowStatus("Model selection saved to settings");
+                    host.requestRender();
+                },
+                onCancel: close,
+            });
+            const component = {
+                ...dialog,
+                dispose: () => {
+                    refresh.stop();
+                    dialog.dispose?.();
+                },
+            };
+            host.setInputSurface(component);
+            host.requestRender();
+            refresh.run(host, component, signal => catalog.refreshModels(signal), refreshed => component.updateModels(refreshed.models));
+        },
+        openScopedModelsSelector(host) {
+            const catalog = adapter.catalog;
+            const initial = catalog.pinnedScopedModelsContext();
+            let currentEnabledIds = initial.enabledModelIds === null ? null : [...initial.enabledModelIds];
+            let selectionChanged = false;
+            const refresh = new ModelCatalogRefresh();
+            const close = () => {
+                refresh.stop();
+                host.setInputSurface(null);
+                host.requestRender();
+            };
+            const selector = createPiShellScopedModelsSelector({
+                models: initial.models,
+                enabledModelIds: currentEnabledIds,
+                refreshStatus: "Refreshing model catalogs…",
+                onChange: enabledIds => {
+                    selectionChanged = true;
+                    currentEnabledIds = enabledIds === null ? null : [...enabledIds];
+                    catalog.updateScopedModels(currentEnabledIds);
+                    host.requestRender();
+                },
+                onPersist: enabledIds => {
+                    currentEnabledIds = enabledIds === null ? null : [...enabledIds];
+                    catalog.persistScopedModels(currentEnabledIds);
+                    host.appendWorkflowStatus("Model selection saved to settings");
+                    host.requestRender();
+                },
+                onCancel: close,
+            });
+            const component = {
+                ...selector,
+                dispose: () => {
+                    refresh.stop();
+                    selector.dispose?.();
+                },
+            };
+            host.setInputSurface(component);
+            host.requestRender();
+            refresh.run(host, component, signal => catalog.refreshScopedModels(signal), refreshed => {
+                if (!selectionChanged) {
+                    currentEnabledIds = refreshed.enabledModelIds === null ? null : [...refreshed.enabledModelIds];
+                    component.updateModels(refreshed.models, currentEnabledIds);
+                }
+                else {
+                    component.updateModels(refreshed.models);
+                    catalog.updateScopedModels(currentEnabledIds);
+                }
+            });
+        },
+    };
+}
+/**
+ * One model-catalog refresh owned by an open dialog: it aborts after fifteen seconds or when the dialog
+ * closes, and a result that arrives after the dialog closed is dropped.
+ */
+class ModelCatalogRefresh {
+    #controller = new AbortController();
+    #timeout;
+    #stopped = false;
+    #timedOut = false;
+    constructor() {
+        this.#timeout = setTimeout(() => {
+            this.#timedOut = true;
+            this.#controller.abort();
+        }, MODEL_REFRESH_TIMEOUT_MS);
+    }
+    get stopped() { return this.#stopped; }
+    stop() {
+        this.#stopped = true;
+        clearTimeout(this.#timeout);
+        this.#controller.abort();
+    }
+    run(host, dialog, refresh, apply) {
+        void refresh(this.#controller.signal).then(refreshed => {
+            if (this.#stopped)
+                return;
+            apply(refreshed);
+            dialog.setRefreshStatus(this.#timedOut ? MODEL_REFRESH_TIMED_OUT : refreshed.status, this.#timedOut ? "warning" : refreshed.statusKind);
+            host.requestRender();
+        }).catch(error => {
+            if (this.#stopped)
+                return;
+            dialog.setRefreshStatus(this.#timedOut
+                ? MODEL_REFRESH_TIMED_OUT
+                : `Could not refresh model catalogs: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            host.requestRender();
+        }).finally(() => clearTimeout(this.#timeout));
+    }
+}
+function closeSurface(host) {
+    return () => {
+        host.setInputSurface(null);
+        host.requestRender();
+    };
+}
+function opaqueRenderer(value) {
+    return (typeof value === "object" && value !== null) || typeof value === "function" ? value : undefined;
+}
+function modelReference(model) {
+    if (typeof model !== "object" || model === null)
+        return "";
+    const value = model;
+    const provider = typeof value.provider === "string" ? value.provider : "";
+    const id = typeof value.id === "string" ? value.id : typeof value.modelId === "string" ? value.modelId : "";
+    return provider && id ? `${provider}/${id}` : "";
+}

package/dist/integrations/pi/tui-runtime/adapter.js

@@ -95,7 +95,6 @@ export class PiTuiRuntimeAdapter {
     #terminal;
     #tuiTerminal;
     #tui;
-    #root;
     #layoutRoot;
     #tuiOptions;
     #logDirectory;
@@ -120,7 +119,6 @@ export class PiTuiRuntimeAdapter {
     #presentationFrozen = false;
     #presentationHolds = new Set();
     constructor(options) {
-        this.#root = options.root;
         this.#overlayGeometry = options.onOverlayGeometry === undefined ? undefined : new OverlayGeometryTracker(options.onOverlayGeometry);
         this.#terminal = options.terminal ?? new ProcessTerminal();
         this.#consumeUnhandledMouse = options.consumeUnhandledMouse ?? false;

package/dist/integrations/pi/tui-runtime/damage-aware-terminal.d.ts

@@ -63,6 +63,9 @@ export declare class DamageAwareTerminalAdapter implements PiTuiTerminalPort {
     get kittyProtocolActive(): boolean;
     get lastDecision(): PiTuiDamageDecision;
     get hyperlinkCleanupPending(): boolean;
+    get canvasBackgroundAnsi(): string | null;
+    /** Invalidates remembered terminal cells before the shell forces one complete canvas repaint. */
+    setCanvasBackground(ansi: string | null): boolean;
     /**
      * The rows as last forwarded to the terminal, top to bottom, with styling
      * intact. A row the adapter has not seen since its last invalidation is empty.
@@ -86,3 +89,7 @@ export declare class DamageAwareTerminalAdapter implements PiTuiTerminalPort {
     setTitle(title: string): void;
     setProgress(active: boolean): void;
 }
+/** Makes SGR background resets return to A1's canvas while preserving explicit backgrounds. */
+export declare function rebaseTerminalDefaultBackground(content: string, backgroundAnsi: string): string;
+/** Paints only synchronized fullscreen rows; clipboard/title/progress controls remain byte-identical. */
+export declare function paintTerminalCanvasFrame(data: string, backgroundAnsi: string): string;

package/dist/integrations/pi/tui-runtime/damage-aware-terminal.js

@@ -8,6 +8,7 @@ const ROW_MARKER = /\u001b\[(\d+);1H\u001b\[2K/gu;
 const ROW_CONTENT_CURSOR = /\u001b\[\d+;1H/u;
 const CURSOR_SUFFIX = /(?:\u001b\[(\d+);(\d+)H)?\u001b\[\?25[hl]\u001b\[\?2026l$/u;
 const OUT_OF_BAND = /^(?:\u001b\](?:0|2|9|52);[^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[\?25[hl])+$/u;
+const SGR_SEQUENCE = /\u001b\[([0-9:;]*)m/gu;
 /**
  * A fail-closed adapter for one pinned Pi fullscreen write grammar. Semantic
  * viewport metadata authorizes a shift; bytes are inspected only to validate
@@ -26,6 +27,7 @@ export class DamageAwareTerminalAdapter {
     #lastConsumedFrameId = 0;
     #cacheWidth = 0;
     #cacheHeight = 0;
+    #canvasBackgroundAnsi = null;
     #decision = {
         frameId: null,
         transformed: false,
@@ -41,6 +43,15 @@ export class DamageAwareTerminalAdapter {
     get kittyProtocolActive() { return this.inner.kittyProtocolActive; }
     get lastDecision() { return this.#decision; }
     get hyperlinkCleanupPending() { return this.#cleanupRevision > this.#cleanedRevision; }
+    get canvasBackgroundAnsi() { return this.#canvasBackgroundAnsi; }
+    /** Invalidates remembered terminal cells before the shell forces one complete canvas repaint. */
+    setCanvasBackground(ansi) {
+        if (this.#canvasBackgroundAnsi === ansi)
+            return false;
+        this.#canvasBackgroundAnsi = ansi;
+        this.#invalidatePresentation();
+        return true;
+    }
     /**
      * The rows as last forwarded to the terminal, top to bottom, with styling
      * intact. A row the adapter has not seen since its last invalidation is empty.
@@ -140,7 +151,10 @@ export class DamageAwareTerminalAdapter {
                 output = buildDamageWrite(parsed, armed.descriptor, new Set(decision.paintedRows), this.#rows);
             }
         }
-        this.inner.write(output);
+        const forwarded = this.#canvasBackgroundAnsi === null
+            ? output
+            : paintTerminalCanvasFrame(output, this.#canvasBackgroundAnsi);
+        this.inner.write(forwarded);
         if (epoch !== this.#epoch
             || (armed !== undefined && this.#lastConsumedFrameId !== armed.descriptor.frameId))
             return;
@@ -363,6 +377,57 @@ export class DamageAwareTerminalAdapter {
         this.#cacheHeight = 0;
     }
 }
+/** Makes SGR background resets return to A1's canvas while preserving explicit backgrounds. */
+export function rebaseTerminalDefaultBackground(content, backgroundAnsi) {
+    return content.replace(SGR_SEQUENCE, (sequence, parameters) => (sgrLeavesDefaultBackground(parameters) ? `${sequence}${backgroundAnsi}` : sequence));
+}
+/** Paints only synchronized fullscreen rows; clipboard/title/progress controls remain byte-identical. */
+export function paintTerminalCanvasFrame(data, backgroundAnsi) {
+    if (!data.startsWith(BEGIN_SYNCHRONIZED_OUTPUT) || !data.endsWith(END_SYNCHRONIZED_OUTPUT)
+        || !ROW_MARKER.test(data)) {
+        ROW_MARKER.lastIndex = 0;
+        return data;
+    }
+    ROW_MARKER.lastIndex = 0;
+    const rows = data.replace(ROW_MARKER, (_marker, row) => (`\u001b[${row};1H${backgroundAnsi}\u001b[2K${backgroundAnsi}`));
+    ROW_MARKER.lastIndex = 0;
+    const rebased = rebaseTerminalDefaultBackground(rows, backgroundAnsi);
+    return `${rebased.slice(0, -END_SYNCHRONIZED_OUTPUT.length)}\u001b[49m${END_SYNCHRONIZED_OUTPUT}`;
+}
+function sgrLeavesDefaultBackground(parameters) {
+    if (parameters.length === 0)
+        return true;
+    const values = parameters.split(";");
+    let defaultBackground;
+    for (let index = 0; index < values.length; index += 1) {
+        const token = values[index];
+        const code = Number.parseInt(token.split(":", 1)[0] || "0", 10);
+        if (!Number.isFinite(code))
+            continue;
+        if (code === 0 || code === 49) {
+            defaultBackground = true;
+            continue;
+        }
+        if (code >= 40 && code <= 47 || code >= 100 && code <= 107) {
+            defaultBackground = false;
+            continue;
+        }
+        if (code !== 38 && code !== 48 && code !== 58)
+            continue;
+        if (code === 48)
+            defaultBackground = false;
+        if (token.includes(":"))
+            continue;
+        const mode = Number.parseInt(values[index + 1] ?? "", 10);
+        if (mode === 5)
+            index += 2;
+        else if (mode === 2)
+            index += 4;
+        else
+            index += 1;
+    }
+    return defaultBackground === true;
+}
 function parsePinnedFullscreenWrite(data) {
     if (!data.startsWith(BEGIN_SYNCHRONIZED_OUTPUT) || !data.endsWith(END_SYNCHRONIZED_OUTPUT))
         return null;

package/dist/integrations/pi/tui-runtime/index.d.ts

@@ -1,6 +1,6 @@
 export type { PiTuiComponentPort, PiTuiInputDiagnosticsEvent, PiTuiInputDiagnosticsPhase, PiTuiInputListener, PiTuiInputListenerResult, PiTuiLayoutEntry, PiTuiLayoutNode, PiTuiOverlayAnchor, PiTuiOverlayHandle, PiTuiOverlayMargin, PiTuiOverlayOptions, PiTuiOverlayUnfocusOptions, PiTuiPointerSurface, PiTuiPreInputListener, PiTuiRuntimeAdapterOptions, PiTuiRuntimeState, PiTuiScrollState, PiTuiSizeValue, PiTuiStopOptions, PiTuiTerminalPort, PiTuiViewport, } from "./contracts.js";
 export { samePointerSurfaces } from "./overlay-geometry.js";
-export { DamageAwareTerminalAdapter, PINNED_PI_TUI_DAMAGE_GRAMMAR } from "./damage-aware-terminal.js";
+export { DamageAwareTerminalAdapter, PINNED_PI_TUI_DAMAGE_GRAMMAR, paintTerminalCanvasFrame, rebaseTerminalDefaultBackground, } from "./damage-aware-terminal.js";
 export type { DamageAwareTerminalOptions, PiTuiDamageDecision, PiTuiDamageDecisionReason, PiTuiDamageFrameDescriptor, PiTuiDamageFrameSafety, } from "./damage-aware-terminal.js";
 export { InputPresentationCoordinator, classifyPiTuiInput } from "./input-presentation-coordinator.js";
 export type { InputPresentationCoordinatorOptions, PiTuiInputCoordinationDecision, PiTuiInputCoordinationScheduler, PiTuiInputCoordinationTrace, PiTuiInputSurfaceKind, } from "./input-presentation-coordinator.js";

package/dist/integrations/pi/tui-runtime/index.js

@@ -1,5 +1,5 @@
 export { samePointerSurfaces } from "./overlay-geometry.js";
-export { DamageAwareTerminalAdapter, PINNED_PI_TUI_DAMAGE_GRAMMAR } from "./damage-aware-terminal.js";
+export { DamageAwareTerminalAdapter, PINNED_PI_TUI_DAMAGE_GRAMMAR, paintTerminalCanvasFrame, rebaseTerminalDefaultBackground, } from "./damage-aware-terminal.js";
 export { InputPresentationCoordinator, classifyPiTuiInput } from "./input-presentation-coordinator.js";
 export { PiTuiRuntimeAdapter, PiTuiRuntimeError } from "./adapter.js";
 export { createPiPresentationRuntime, createPiTerminalBridge } from "./presentation-adapter.js";

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-10-09T06:37:13.333Z",
+  "builtAt": "2026-10-10T06:00:13.890Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "51b0b2dc1c9ae577f2586c4217066929278726c2c15308d9144eb6f538e118ff",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-09T06:37:02.979Z",
+  "builtAt": "2026-10-10T06:00:04.832Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "ef62679e83bc1fad3d38f9f21675d9256f08d20e67fd4791571032115ca1b0e9",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-09T06:37:43.630Z",
+  "builtAt": "2026-10-10T06:00:51.067Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "63c2b95f4d07de25f9b25da06e7386f681474967118bf034ef4b02f0259cc9a3",
+    "sha256": "e9c6d7e4596a7cd2634bb74b67925499fe6817cbfb667b574d27ff1b7cb33d93",
     "size": 288256
   },
   "provenance": {

package/dist/ui/settings/declarations.d.ts

@@ -1,4 +1,4 @@
-export declare const OWNED_UI_SETTINGS_VERSION = 12;
+export declare const OWNED_UI_SETTINGS_VERSION = 13;
 export type OwnedUiSettingValue = string | number | boolean;
 export type OwnedUiSettingApplication = "live" | "restart";
 export interface OwnedUiSettingDeclaration {
@@ -44,6 +44,18 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
         defaultValue: "purple";
         allowedValues: readonly ["purple", "blue", "cyan", "green", "orange", "pink"];
     }>;
+    readonly backgroundStyle: Readonly<{
+        id: "backgroundStyle";
+        label: "Background";
+        section: Readonly<{
+            id: "appearance";
+            title: "Appearance";
+        }>;
+        description: "Fullscreen canvas background: terminal transparency, a dark accent tint, or fixed neutral dark.";
+        application: "live";
+        defaultValue: "transparent";
+        allowedValues: readonly ["transparent", "accent", "dark"];
+    }>;
     readonly quitAnimation: Readonly<{
         id: "quitAnimation";
         label: "Quit animation";

package/dist/ui/settings/declarations.js

@@ -1,4 +1,4 @@
-export const OWNED_UI_SETTINGS_VERSION = 12;
+export const OWNED_UI_SETTINGS_VERSION = 13;
 const UI_ACCENT_COLOR_CHOICES = Object.freeze([
     "purple", "blue", "cyan", "green", "orange", "pink",
 ]);
@@ -32,6 +32,17 @@ export const OWNED_SETTING_DECLARATIONS = Object.freeze({
         defaultValue: "purple",
         allowedValues: UI_ACCENT_COLOR_CHOICES,
     }),
+    backgroundStyle: Object.freeze({
+        id: "backgroundStyle",
+        label: "Background",
+        section: APPEARANCE_SECTION,
+        description: "Fullscreen canvas background: terminal transparency, a dark accent tint, or fixed neutral dark.",
+        application: "live",
+        defaultValue: "transparent",
+        allowedValues: Object.freeze([
+            "transparent", "accent", "dark",
+        ]),
+    }),
     quitAnimation: Object.freeze({
         id: "quitAnimation",
         label: "Quit animation",

package/dist/ui/settings/migrations.js

@@ -97,6 +97,13 @@ export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([
                 : { ...values };
         },
     }),
+    Object.freeze({
+        to: 13,
+        description: "Introduce the transparent fullscreen background default.",
+        migrate(values) {
+            return { ...values };
+        },
+    }),
 ]);
 export function assertOwnedUiSettingsMigrations(migrations, currentVersion = OWNED_UI_SETTINGS_VERSION) {
     const firstProduced = currentVersion - migrations.length + 1;

package/docs/architecture/boundaries.md

@@ -30,7 +30,7 @@ The owned Pi-backed surface is not an arbitrary-CLI terminal multiplexer. A feat
 - `prompt-suggestions`: opt-in bounded diagnostic snapshots of neutral suggestion lifecycle metadata. Composition supplies an explicit local destination; this feature never imports Pi, generates suggestions, stores conversation text, or owns the editor. See [prompt suggestion diagnostics](prompt-suggestions.md).
 - `storage`: SQLite migrations, prior-boot reconciliation, and plural launch-instance persistence. Legacy foreground rows are historical migration input and never authorize current ownership.
 - `supervisor`: endpoint identity, plural cohort ownership, per-instance reconciliation, and aggregate release shutdown coordination. It owns no terminal surface.
-- `pi-engine-adapter`, `pi-component-adapter`, and `pi-tui-runtime-adapter`: isolate pinned Pi engine and presentation knowledge behind neutral contracts; product features do not import them directly.
+- `pi-engine-adapter`, `pi-component-adapter`, and `pi-tui-runtime-adapter`: isolate pinned Pi engine and presentation knowledge behind neutral contracts; product features do not import them directly. Inside the engine adapter, one process-level engine host owns what is process-wide (the HTTP dispatcher, the theme singletons, the one-time changelog and package-update announcements, the startup trace) and is the only place sessions are created, so every session id is unique per process.
 - `session-shell` (`src/app/session-shell`): the application layer that composes the feature owners, the UI foundations, and the three Pi adapters into the interactive session; only composition imports it. Its render root assembles semantic document and dock rows, while its focused viewport controller owns follow state, pointer routing, selection, and interaction timers. Owned-app route lifecycle belongs to the neutral `ui-apps` owner and is only hosted by the session shell.
 - release/update/bootstrap: package-derived immutable release identity, process-guardian integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry. After an unsuccessful bare-A1 child exit, the bootstrap restores owned terminal modes; neither guardian emits terminal controls.
 - `terminal-cleanup`: bounded, idempotent emergency restoration and fatal-exit diagnostics for an explicitly owned terminal. It does not inspect commands, relay terminal input/output, or emulate terminal state. The owned UI installs its fatal boundary before terminal activation; packaged bootstrap and checkout launch provide the surviving-owner fallback. Fatal records retain at most ten 16 KiB records with trusted classifications and code locations, never prompts, attachments, raw input, credentials, or arbitrary exception messages.
@@ -43,6 +43,14 @@ The JavaScript product path has no PTY or terminal-emulator dependency. Reintrod
 
 `scripts/governance/check-architecture.mjs` enforces the structural parts of these boundaries. Cross-cutting rationale belongs here; implementation history belongs in Git and archived OpenSpec changes.
 
+## Multi-session limits of the pinned engine
+
+The engine host removes A1's own obstacles to several Pi sessions in one process, but three remain in the pinned Pi SDK and must be planned around, not discovered:
+
+- The extension cache is keyed by one working directory and cleared on reload (`core/extensions/loader.js`), so sessions in different directories reload each other's extensions.
+- `SettingsManager` writes under a lockfile but never re-reads the file, so a second in-memory copy goes stale after another session writes a setting (`core/settings-manager.js`). The host keeps the one process-wide effect, the HTTP dispatcher, consistent itself.
+- `AgentSessionRuntime.dispose()` releases the session but not the model runtime or the resource loader it was created with (`core/agent-session-runtime.js`), so a session's services outlive it until the process ends.
+
 ## Planned multi-agent boundaries
 
 The multi-agent workspace feature, its dependency-free contracts, the structured-agent runtime, and the Node side of the terminal-host protocol were removed from `develop` while the multi-agent plan is on hold; their last state is preserved on the `archive/multi-agent-workspace` branch. A future implementation starts from the current codebase rather than from that copy. The boundary rules below remain the design intent for that work.

package/docs/architecture/project-structure.md

@@ -18,13 +18,14 @@ src/
     prompt-history/                profile-isolated prompt retention and bounded SQLite worker lifecycle
     prompt-suggestions/            opt-in bounded metadata capture and local diagnostic snapshots
   contracts/
-    agent-engine/                  dependency-free agent engine, session, package, and capability ports
+    agent-engine/                  dependency-free agent settings and package contracts
     owned-ui/                      dependency-free owned-session and extension UI contracts
     presentation/                  dependency-free component, terminal, and runtime ports
   integrations/
     pi/
       components/                  pinned Pi component and theme adaptation
       engine/                      pinned Pi engine, settings, resource, package, and workflow integration
+      session-presenters/          pinned Pi selectors and transcript renderers built from engine objects
       tui-runtime/                 neutral presentation runtime over pinned Pi TUI
   foundation/
     launch-guardian/               authenticated launch-instance coordination
@@ -42,7 +43,7 @@ src/
 
 Each directory owner exposes `index.ts`, which lists its named exports; `export *` is rejected there so a public contract is readable in one place. Imports within one owner may use private files. Imports crossing owners must use the provider's public entry and follow the dependency DAG declared by `PROJECT_OWNERS`. Two exceptions exist: `src/composition` is the dependency-injection root and may reach past any public entry, and a module on the eager startup path may import a leaf of a provider whose public entry is a prohibited startup entry (`PROHIBITED_STARTUP_ENTRIES` in `startup-graph-policy.mjs`), because loading that barrel would pull the provider's whole graph into startup. `product-identity` is the sole exception to the directory-entry convention because its public entry is `src/product-identity.ts`.
 
-Three layer boundaries hold regardless of the DAG: `src/contracts/*` import nothing outside their own contract; `src/ui/components` imports only contracts; only `src/integrations/pi/*` and the shipped `bin/` entries import the pinned Pi packages. The session shell under `src/app` is the application layer: it may import the contracts, the UI foundations, the three Pi adapters, and the feature owners, and only composition imports it.
+Three layer boundaries hold regardless of the DAG: `src/contracts/*` import nothing outside their own contract; `src/ui/components` imports only contracts; only `src/integrations/pi/*` and the shipped `bin/` entries import the pinned Pi packages. The session shell under `src/app` is the application layer: it may import the contracts, the UI foundations, the three Pi adapters, and the feature owners, and only composition imports it. The shell never holds a Pi engine object: selectors and transcript renderers built from one live in `src/integrations/pi/session-presenters`, the only owner besides composition that may import both the engine and the component adapters, and the shell opens them through the `OwnedUiSessionPresenters` contract.
 
 `src/cli` contains command policy but delegates runtime work. `src/composition` is the concrete dependency-injection boundary: it may know both neutral contracts and Pi implementations, while product features receive vendor-neutral ports. Foundation modules never import product features. Pi package knowledge remains inside the Pi adapter owners.