@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.407

package/dist/{src/foundation → foundation}/supervision/server.js

@@ -1,25 +1,60 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createConnection, createServer } from "node:net";
 import { platform } from "node:os";
+import { dirname } from "node:path";
 import { assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
 import { encodeFrame, isCommandMessage, isControlHello, LineFrameDecoder, localControlHello, MAX_CONTROL_FRAME_BYTES, negotiateControlFeatures } from "../protocol/index.js";
 import { processIsAlive } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveProductPaths } from "./paths.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+const WINDOWS_METADATA_REPLACE_RETRY_DELAYS_MS = [5, 10, 20, 40, 80, 160];
+/** Atomically replaces endpoint metadata while tolerating bounded Windows reader sharing. */
+export async function commitEndpointMetadata(path, source, operations = {}) {
+    const temporary = `${path}.${process.pid}.tmp`;
+    const write = operations.write ?? writeFile;
+    const replace = operations.replace ?? rename;
+    const remove = operations.remove ?? rm;
+    const wait = operations.wait ?? (delayMs => new Promise(resolvePromise => setTimeout(resolvePromise, delayMs)));
+    let committed = false;
+    try {
+        await write(temporary, source, { mode: 0o600 });
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await replace(temporary, path);
+                committed = true;
+                return;
+            }
+            catch (error) {
+                const delayMs = WINDOWS_METADATA_REPLACE_RETRY_DELAYS_MS[attempt];
+                if ((operations.platform ?? platform()) !== "win32" || delayMs === undefined || !isWindowsSharingViolation(error))
+                    throw error;
+                await wait(delayMs);
+            }
+        }
+    }
+    finally {
+        if (!committed)
+            await remove(temporary, { force: true }).catch(() => undefined);
+    }
+}
+/** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
 export class SupervisorServer {
     store;
     release;
     terminateProcess;
     reconciliationDeadlineMs;
     shutdownDeadlineMs;
+    readActiveReleaseId;
+    supersededPollMs;
     id = randomUUID();
     bootNonce;
     pidStartIdentity = `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
     startedAt = new Date().toISOString();
     paths;
     #server = null;
+    #ownsEndpoint = false;
     #instances = new Map();
     #instanceOwners = new Map();
     #clientIds = new Map();
@@ -31,12 +66,22 @@ export class SupervisorServer {
     #results = new Map();
     #metadataWrites = Promise.resolve();
     #closing = false;
-    constructor(store, paths = resolveProductPaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code), reconciliationDeadlineMs = 3_000, shutdownDeadlineMs = 1_500) {
+    #superseded = false;
+    #supersededPoll = null;
+    constructor(store, paths = resolveProductPaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code), reconciliationDeadlineMs = 3_000, shutdownDeadlineMs = 1_500, 
+    /**
+     * Which release new sessions start on. A cohort that is no longer that release keeps
+     * serving the instances it already has, takes no new ones, and exits when its last one
+     * leaves. Absent, this supervisor never considers itself superseded.
+     */
+    readActiveReleaseId = null, supersededPollMs = 1_000) {
         this.store = store;
         this.release = release;
         this.terminateProcess = terminateProcess;
         this.reconciliationDeadlineMs = reconciliationDeadlineMs;
         this.shutdownDeadlineMs = shutdownDeadlineMs;
+        this.readActiveReleaseId = readActiveReleaseId;
+        this.supersededPollMs = supersededPollMs;
         this.bootNonce = bootNonce;
         this.paths = paths;
         for (const instance of store.loadActiveLaunchInstances())
@@ -56,37 +101,93 @@ export class SupervisorServer {
         if (this.#server)
             throw new Error("supervisor is already listening");
         await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
+        await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
         if (platform() !== "win32") {
-            if (await endpointIsLive(this.paths.endpoint))
-                throw new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`));
-            await rm(this.paths.endpoint, { force: true });
+            if (this.paths.endpointDirectory)
+                await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
+            const existing = await lstat(this.paths.endpoint).catch(error => {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            });
+            if (existing) {
+                if (await endpointIsLive(this.paths.endpoint)) {
+                    throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`)), { code: "EADDRINUSE" });
+                }
+                await rm(this.paths.endpoint, { force: true });
+            }
         }
         const server = createServer(socket => this.#attach(socket));
         this.#server = server;
         await new Promise((resolve, reject) => {
             server.once("error", reject);
             server.listen(this.paths.endpoint, () => {
+                this.#ownsEndpoint = true;
                 server.off("error", reject);
                 resolve();
             });
         });
         await this.#writeEndpointMetadata();
+        if (this.readActiveReleaseId) {
+            const poll = setInterval(() => void this.#refreshCohortRole(), this.supersededPollMs);
+            poll.unref();
+            this.#supersededPoll = poll;
+        }
+    }
+    // Invariant: superseding a cohort never interrupts its held instances; it retires only when empty.
+    async #refreshCohortRole() {
+        if (this.#closing || !this.readActiveReleaseId)
+            return;
+        const active = await this.readActiveReleaseId().catch(() => null);
+        if (active === null)
+            return;
+        this.#superseded = active !== this.release.releaseId;
+        if (this.#superseded && this.#instances.size === 0)
+            await this.retire();
+    }
+    /** Whether new sessions start on some other release. */
+    get superseded() {
+        return this.#superseded;
+    }
+    /** Leaves, taking this cohort's own endpoint artifacts with it. */
+    async retire() {
+        if (this.#closing)
+            return;
+        await this.close(false);
     }
     async close(stopAgents = false) {
-        if (stopAgents && !await this.#drainInstances("update", this.shutdownDeadlineMs)) {
+        if (this.#closing)
+            return;
+        if (stopAgents && this.#ownsEndpoint && !await this.#drainInstances("update", this.shutdownDeadlineMs)) {
             throw new Error("active launch instances did not release ownership within the shutdown deadline");
         }
         this.#closing = true;
+        if (this.#supersededPoll)
+            clearInterval(this.#supersededPoll);
+        this.#supersededPoll = null;
         for (const client of this.#clients)
             client.destroy();
-        if (this.#server)
-            await new Promise(resolve => this.#server?.close(() => resolve()));
-        this.#server = null;
-        this.store.close();
-        await this.#metadataWrites;
-        await rm(this.paths.endpointMetadataPath, { force: true });
-        if (platform() !== "win32")
-            await rm(this.paths.endpoint, { force: true });
+        try {
+            await this.#metadataWrites.catch(() => undefined);
+            if (this.#ownsEndpoint) {
+                // Concurrency: remove only our publication, before releasing the listening endpoint.
+                // A contender that failed to bind must never erase the successful owner's discovery file.
+                const metadata = await readFile(this.paths.endpointMetadataPath, "utf8").then(source => JSON.parse(source)).catch(() => null);
+                if (metadata?.supervisorId === this.id && metadata.bootNonce === this.bootNonce) {
+                    await rm(this.paths.endpointMetadataPath, { force: true });
+                }
+                // Platform: Node unlinks its Unix socket when the server closes; unlinking it early would
+                // let a replacement bind before the old server finishes releasing that path.
+            }
+        }
+        finally {
+            // Platform: a metadata sharing error must not leave a bound but undiscoverable listener.
+            if (this.#server)
+                await new Promise(resolve => this.#server?.close(() => resolve()));
+            this.#server = null;
+            this.#ownsEndpoint = false;
+            this.store.close();
+        }
     }
     async closeForReleaseReplacement(stopAgents) {
         await this.close(stopAgents);
@@ -197,6 +298,9 @@ export class SupervisorServer {
     #createLaunchInstance(command, socket, clientId) {
         assertNativeProcessIdentity(command.guardianIdentity);
         const existing = this.store.loadLaunchInstance(command.instanceId);
+        if (this.#superseded && !existing) {
+            throw new Error(PRODUCT_TEXT.diagnostic(`release ${this.release.releaseId} is no longer the release new sessions start on`));
+        }
         if (existing) {
             if (existing.ownerClientId !== clientId
                 || existing.profileId !== command.profileId
@@ -279,6 +383,9 @@ export class SupervisorServer {
         this.#uncertainInstances.delete(stored.id);
         this.#unbindOwner(stored.id, socket);
         this.#mutated();
+        // Invariant: the last session on a superseded cohort has left; there is nothing here to keep.
+        if (this.#superseded && this.#instances.size === 0)
+            void this.retire();
     }
     #ownedInstance(instanceId, socket, clientId) {
         const instance = this.#instances.get(instanceId) ?? this.store.loadLaunchInstance(instanceId);
@@ -370,7 +477,7 @@ export class SupervisorServer {
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             if (this.#instances.size === 0) {
-                // Let the terminal command result flush before closing owner sockets.
+                // Concurrency: allow the terminal command result to flush before closing owner sockets.
                 await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
                 return this.#instances.size === 0;
             }
@@ -391,6 +498,8 @@ export class SupervisorServer {
         return [...this.#instances.keys()];
     }
     #writeEndpointMetadata() {
+        if (this.#closing)
+            return Promise.resolve();
         const liveInstanceIds = this.#liveInstanceIds();
         const metadata = {
             schema: PRODUCT_IDENTITY.protocol.supervisorSchema,
@@ -412,11 +521,10 @@ export class SupervisorServer {
                 uncertainInstanceIds: [...this.#uncertainInstances],
             },
         };
-        const temporary = `${this.paths.endpointMetadataPath}.${process.pid}.tmp`;
-        this.#metadataWrites = this.#metadataWrites.then(async () => {
-            await writeFile(temporary, JSON.stringify(metadata, null, 2), { mode: 0o600 });
-            await rename(temporary, this.paths.endpointMetadataPath);
-        });
+        const commit = () => commitEndpointMetadata(this.paths.endpointMetadataPath, JSON.stringify(metadata, null, 2));
+        // Platform: one exhausted filesystem replacement must fail its command, but it must not
+        // poison every later ownership revision after the sharing condition has cleared.
+        this.#metadataWrites = this.#metadataWrites.then(commit, commit);
         return this.#metadataWrites;
     }
     #send(socket, message) {
@@ -440,6 +548,20 @@ function sameContainmentIdentity(left, right) {
 function isMessageType(value, type) {
     return typeof value === "object" && value !== null && "type" in value && value.type === type;
 }
+function isWindowsSharingViolation(error) {
+    return error instanceof Error && "code" in error
+        && (error.code === "EPERM" || error.code === "EACCES" || error.code === "EBUSY");
+}
+async function ensureManagedEndpointDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const metadata = await lstat(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error(`managed endpoint path is not a directory: ${path}`);
+    const currentUser = process.getuid?.();
+    if (currentUser !== undefined && metadata.uid !== currentUser)
+        throw new Error(`managed endpoint directory has another owner: ${path}`);
+    await chmod(path, 0o700);
+}
 async function endpointIsLive(endpoint) {
     return await new Promise(resolve => {
         const socket = createConnection(endpoint);

package/dist/foundation/terminal-cleanup/fatal-exit.d.ts

@@ -0,0 +1,12 @@
+export interface FatalExitOptions {
+    readonly directory: string;
+    readonly releaseId?: string;
+    readonly restore?: () => void;
+    readonly dispose?: () => Promise<unknown> | void;
+    readonly timeoutMs?: number;
+}
+export declare function writeFatalDiagnostic(directory: string, origin: string, error: unknown, releaseId?: string): Promise<string | null>;
+export declare function installFatalExit(options: FatalExitOptions): {
+    fail(error: unknown): void;
+    remove(): void;
+};

package/dist/foundation/terminal-cleanup/fatal-exit.js

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, unlink, writeFile } from "node:fs/promises";
+import { writeSync } from "node:fs";
+import { join } from "node:path";
+import { boundedCleanup, restoreProcessTerminal } from "./terminal-reset.js";
+export async function writeFatalDiagnostic(directory, origin, error, releaseId) {
+    try {
+        // Security: only known classifications and code locations are retained. Error messages,
+        // function names, arbitrary paths, and request objects are never persisted.
+        const cleanupFailed = error instanceof AggregateError && error.cause instanceof Error;
+        const primary = cleanupFailed ? error.cause : error;
+        const classification = primary instanceof TypeError ? "TypeError" : primary instanceof RangeError ? "RangeError" : "Error";
+        const stack = primary instanceof Error && typeof primary.stack === "string" ? primary.stack.slice(0, 32768) : "";
+        const locations = stack.split("\n").slice(1).flatMap(line => {
+            const match = /\/(?:dist|src)\/([a-zA-Z0-9_./-]+\.[cm]?[jt]s):(\d+):(\d+)\)?$/.exec(line.replaceAll("\\", "/"));
+            return match ? [{ file: match[1].slice(0, 160), line: Number(match[2]), column: Number(match[3]) }] : [];
+        }).slice(0, 16);
+        const record = {
+            timestamp: new Date().toISOString(),
+            origin: ["uncaughtException", "unhandledRejection", "entry"].includes(origin) ? origin : "entry",
+            classification, cleanupFailed, locations, node: process.version, platform: process.platform,
+            releaseId: releaseId && /^[a-zA-Z0-9._-]{1,128}$/.test(releaseId) ? releaseId : "unknown",
+        };
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const name = `fatal-${Date.now()}-${randomUUID()}.json`;
+        const path = join(directory, name);
+        const text = JSON.stringify(record, null, 2);
+        if (Buffer.byteLength(text) > 16 * 1024)
+            return null;
+        await writeFile(path, text, { flag: "wx", mode: 0o600 });
+        const names = (await readdir(directory)).filter(file => /^fatal-\d+-[a-f0-9-]+\.json$/.test(file)).sort().reverse();
+        await Promise.all(names.slice(10).map(file => unlink(join(directory, file)).catch(() => undefined)));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+export function installFatalExit(options) {
+    let failing = false;
+    const restore = () => { try {
+        (options.restore ?? restoreProcessTerminal)();
+    }
+    catch { } };
+    const terminate = (origin, error) => {
+        if (failing)
+            return;
+        failing = true;
+        process.exitCode = 1;
+        // Security: stop accepting input immediately; fatal errors never resume normal work.
+        try {
+            process.stdin.pause();
+            process.stdin.removeAllListeners("data");
+        }
+        catch { }
+        restore();
+        let record = null;
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            restore();
+            try {
+                const location = record?.replace(/[\x00-\x1f\x7f]/g, "").slice(0, 512);
+                writeSync(2, `A1 stopped after an unexpected error.${location ? ` Diagnostic: ${location}` : " Diagnostic storage unavailable."}\n`);
+            }
+            catch { }
+            process.exit(1);
+        };
+        const deadline = setTimeout(finish, options.timeoutMs ?? 1000);
+        void Promise.all([
+            writeFatalDiagnostic(options.directory, origin, error, options.releaseId).then(path => { record = path; }),
+            boundedCleanup(() => options.dispose?.(), options.timeoutMs ?? 1000).catch(() => undefined),
+        ]).then(() => { clearTimeout(deadline); finish(); }, finish);
+    };
+    const exception = (error) => terminate("uncaughtException", error);
+    const rejection = (error) => terminate("unhandledRejection", error);
+    process.on("uncaughtException", exception);
+    process.on("unhandledRejection", rejection);
+    return {
+        fail: error => terminate("entry", error),
+        remove() { process.off("uncaughtException", exception); process.off("unhandledRejection", rejection); },
+    };
+}

package/dist/foundation/terminal-cleanup/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./terminal-reset.js";
+export * from "./fatal-exit.js";

package/dist/foundation/terminal-cleanup/index.js

@@ -0,0 +1,2 @@
+export * from "./terminal-reset.js";
+export * from "./fatal-exit.js";

package/dist/foundation/terminal-cleanup/terminal-reset.d.ts

@@ -0,0 +1,4 @@
+export declare const EMERGENCY_TERMINAL_RESET: string;
+export declare function restoreProcessTerminal(): void;
+export declare function restoreAfterOwnedExit(ownsTerminal: boolean, code: number | null, signal: string | null, restore?: () => void): number;
+export declare function boundedCleanup(cleanup: () => Promise<unknown> | void, timeoutMs?: number): Promise<void>;

package/dist/foundation/terminal-cleanup/terminal-reset.js

@@ -0,0 +1,40 @@
+import { writeSync } from "node:fs";
+// Protocol: reset modes on both screens; setting keyboard flags to zero is idempotent,
+// unlike repeatedly popping a keyboard-protocol stack owned by a parent application.
+export const EMERGENCY_TERMINAL_RESET = "\x1b[?2026l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1004l\x1b[?1006l"
+    + "\x1b[?2004l\x1b[=0u\x1b[>4;0m\x1b]8;;\x1b\\\x1b[0m\x1b[r\x1b[?7h\x1b[?25h"
+    + "\x1b[?1049l\x1b[r\x1b[?7h\x1b[?25h\x1b]9;4;0\x07";
+export function restoreProcessTerminal() {
+    try {
+        if (process.stdout.isTTY)
+            writeSync(process.stdout.fd, EMERGENCY_TERMINAL_RESET);
+    }
+    catch { }
+    try {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(false);
+    }
+    catch { }
+}
+export function restoreAfterOwnedExit(ownsTerminal, code, signal, restore = restoreProcessTerminal) {
+    const outcome = code ?? (signal ? 1 : 0);
+    if (ownsTerminal && outcome !== 0) {
+        try {
+            restore();
+        }
+        catch { }
+    }
+    return outcome;
+}
+export async function boundedCleanup(cleanup, timeoutMs = 1000) {
+    let timer;
+    try {
+        await Promise.race([
+            Promise.resolve().then(cleanup),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Cleanup deadline exceeded")), timeoutMs); }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/components.d.ts

@@ -1,4 +1,4 @@
-import type { OwnedUiTranscriptBlock } from "../owned-ui-contracts/index.js";
+import type { OwnedUiTranscriptBlock } from "../../../contracts/owned-ui/index.js";
 export declare function adaptPiUserMessage(block: OwnedUiTranscriptBlock, width: number): readonly string[];
 export declare function adaptPiAssistantMessage(block: OwnedUiTranscriptBlock, width: number): readonly string[];
 export declare function adaptPiToolExecution(block: OwnedUiTranscriptBlock, width: number, cwd: string): readonly string[];

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/conformance.d.ts

@@ -10,6 +10,7 @@ export interface PiComponentConformanceReport {
     readonly componentResults: readonly PiComponentConformanceResult[];
     readonly componentFamilies: readonly string[];
 }
+/** Identifies the Pi presentation-conformance stage that failed against the pinned component surface. */
 export declare class PiComponentConformanceError extends Error {
     readonly stage: "theme" | "components";
     constructor(stage: "theme" | "components", cause: unknown);

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/conformance.js

@@ -2,9 +2,10 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AssistantMessageComponent, ExtensionSelectorComponent, initTheme, LoginDialogComponent, ModelSelectorComponent, SettingsSelectorComponent, ThemeSelectorComponent, ThinkingSelectorComponent, ToolExecutionComponent, UserMessageComponent, UserMessageSelectorComponent, VERSION, } from "@earendil-works/pi-coding-agent";
-import { OWNED_UI_CONTRACT_VERSION } from "../owned-ui-contracts/index.js";
+import { OWNED_UI_CONTRACT_VERSION } from "../../../contracts/owned-ui/index.js";
 import { createTuiFacade, validatedAssistantMessage } from "./shell-components.js";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+/** Identifies the Pi presentation-conformance stage that failed against the pinned component surface. */
 export class PiComponentConformanceError extends Error {
     stage;
     constructor(stage, cause) {

package/dist/integrations/pi/components/editor-interaction.d.ts

@@ -0,0 +1,38 @@
+import type { Editor } from "#pi-tui";
+export interface EditorInteractionState {
+    lines: string[];
+    cursorLine: number;
+    cursorCol: number;
+}
+export interface EditorInteractionPort {
+    snapshot(): EditorInteractionState;
+    setCursor(line: number, col: number): void;
+    replaceLines(lines: readonly string[]): void;
+    updateUndoStates(update: (state: EditorInteractionState) => void): void;
+    scrollOffset(): number;
+    visualLines(width: number): Array<{
+        logicalLine: number;
+        startCol: number;
+        length: number;
+    }>;
+    setSegmentTransform(transform: (text: string, mode: "word" | "grapheme", segments: Iterable<Intl.SegmentData>) => Iterable<Intl.SegmentData>): void;
+}
+export interface EditorRecallPort {
+    replace(entries: readonly string[]): void;
+    position(): {
+        readonly index: number;
+        readonly total: number;
+    };
+    observe(listener: () => void): () => void;
+    reset(): void;
+}
+export interface EditorSurface extends Pick<Editor, Exclude<keyof Editor, "setText" | "render" | "handleInput">> {
+    setText(text: string): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    readonly interaction?: EditorInteractionPort;
+    readonly recall?: EditorRecallPort;
+}
+export type SelectionEditor = Pick<Editor, "getText" | "getCursor" | "setText" | "insertTextAtCursor" | "invalidate" | "onChange" | "getPaddingX" | "isShowingAutocomplete"> & {
+    readonly interaction?: EditorInteractionPort;
+};

package/dist/integrations/pi/components/history-editor-loader.d.ts

@@ -0,0 +1,5 @@
+import { type ShellEditorInstance, type OwnedEditorOptions } from "./upstream/components/owned-editor.js";
+import type { EditorTheme, TUI } from "#pi-tui";
+import type { KeybindingsManager } from "./upstream/adjacent/core/keybindings.js";
+export type HistoryEditorConstructor = new (tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, options?: OwnedEditorOptions) => ShellEditorInstance;
+export declare function loadHistoryEditor(): Promise<HistoryEditorConstructor>;

package/dist/integrations/pi/components/history-editor-loader.js

@@ -0,0 +1,5 @@
+import { createOwnedEditorClass } from "./upstream/components/owned-editor.js";
+export async function loadHistoryEditor() {
+    const { HistoryEditorCore } = await import("./upstream/history/editor-core.js");
+    return createOwnedEditorClass(HistoryEditorCore);
+}

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/index.d.ts

@@ -1,9 +1,10 @@
 export * from "./components.js";
+export { loadHistoryEditor, type HistoryEditorConstructor } from "./history-editor-loader.js";
 export * from "./conformance.js";
 export * from "./shell-components.js";
 export * from "./theme.js";
 export * from "./upstream/theme/theme-controller.js";
-export { applyConfiguredPiTheme, getAvailablePiThemes } from "./upstream/theme/theme.js";
+export { applyConfiguredPiTheme, getAvailablePiThemes, onPiThemeChange } from "./upstream/theme/theme.js";
 export * from "./upstream/components/countdown-timer.js";
 export * from "./upstream/components/extension-editor.js";
 export * from "./upstream/components/session-selector.js";

package/dist/{src/foundation/pi-component-adapter → integrations/pi/components}/index.js

@@ -1,9 +1,10 @@
 export * from "./components.js";
+export { loadHistoryEditor } from "./history-editor-loader.js";
 export * from "./conformance.js";
 export * from "./shell-components.js";
 export * from "./theme.js";
 export * from "./upstream/theme/theme-controller.js";
-export { applyConfiguredPiTheme, getAvailablePiThemes } from "./upstream/theme/theme.js";
+export { applyConfiguredPiTheme, getAvailablePiThemes, onPiThemeChange } from "./upstream/theme/theme.js";
 export * from "./upstream/components/countdown-timer.js";
 export * from "./upstream/components/extension-editor.js";
 export * from "./upstream/components/session-selector.js";

package/dist/integrations/pi/components/owned-editor-ux.d.ts

@@ -0,0 +1,74 @@
+import type { SelectionEditor as Editor } from "./editor-interaction.js";
+import type { KeybindingsManager } from "./upstream/adjacent/core/keybindings.js";
+import type { PiShellClipboardContent, PiShellEditorTextRange, PiShellPasteReservation } from "./shell-shared-facade.js";
+/**
+ * Middleware boundary around Pi's editor. Interceptors may claim an input or
+ * delegate to the next interceptor/vanilla editor, and may decorate the rows
+ * vanilla Pi renders. This keeps owned UX additions out of the synchronized
+ * Pi editor port and gives future interactions one registration point.
+ */
+export interface OwnedEditorUxInterceptor {
+    handleInput(data: string, next: (data?: string) => void): void;
+    render(width: number, next: () => string[]): string[];
+    reset(): void;
+    handlePointer?(event: OwnedEditorPointerEvent): boolean;
+    hasSelection?(): boolean;
+    ownsPointer?(): boolean;
+    pasteClipboard?(): boolean;
+    cancelPendingPastes?(): void;
+}
+export interface OwnedEditorPointerEvent {
+    readonly kind: "press" | "motion" | "release";
+    readonly button: number;
+    readonly column: number;
+    /** One-based row relative to the top of the editor component. */
+    readonly row: number;
+}
+export declare class OwnedEditorUxInterception {
+    readonly interceptors: readonly OwnedEditorUxInterceptor[];
+    readonly fallback: {
+        handleInput(data: string): void;
+        render(width: number): string[];
+    };
+    constructor(interceptors: readonly OwnedEditorUxInterceptor[], fallback: {
+        handleInput(data: string): void;
+        render(width: number): string[];
+    });
+    handleInput(data: string): void;
+    render(width: number): string[];
+    reset(): void;
+    cancelPendingPastes(): void;
+    handlePointer(event: OwnedEditorPointerEvent): boolean;
+    hasSelection(): boolean;
+    ownsPointer(): boolean;
+    pasteClipboard(): boolean;
+}
+export interface PromptSelectionUxOptions {
+    readonly copyText: (text: string) => void;
+    readonly readClipboardContent: () => Promise<PiShellClipboardContent | null>;
+    readonly beginClipboardPaste?: () => PiShellPasteReservation;
+    readonly beginTextPaste?: (text: string) => PiShellPasteReservation;
+    readonly deferTextPaste?: (text: string) => boolean;
+    readonly onPasteRejected?: (error: unknown) => void;
+    readonly onPasteInput?: (bytes: number) => void;
+    readonly transformPastedContent: (content: PiShellClipboardContent) => string;
+    readonly atomicRanges: (line: string) => readonly PiShellEditorTextRange[];
+    readonly hiddenRanges?: (line: string) => readonly PiShellEditorTextRange[];
+    readonly expandCopiedText: (text: string) => string;
+    readonly paintSelection: (line: string, from: number, to: number, atomic: boolean) => string;
+    /** Row indices restart at zero for each complete decoration pass. */
+    readonly decorateRow: (row: string, width: number, rowIndex: number) => string;
+    readonly requestRender: () => void;
+    readonly getRows: () => number;
+    /** Presentation-only columns reserved before semantic editor text. */
+    readonly promptGeometry?: (width: number, padding: number) => {
+        readonly prefixWidth: number;
+        readonly innerWidth: number;
+        readonly paddingX: number;
+        readonly contentWidth: number;
+        readonly layoutWidth: number;
+    };
+}
+export declare function createPromptSelectionInterceptor(editor: Editor, keybindings: KeybindingsManager, options: PromptSelectionUxOptions): OwnedEditorUxInterceptor;
+/** Shares the existing atomic-aware body layout with prompt/menu composition. */
+export declare function editorVisualLineCount(editor: Editor, width: number): number | undefined;