@timurproko/a1 0.2.7-dev.806 → 0.2.7-dev.809

package/dist/integrations/pi/engine/command-dispatch.d.ts

@@ -1,5 +1,7 @@
 import { type OwnedUiCommand, type OwnedUiCommandResult, type OwnedUiDiagnostics } from "../../../contracts/owned-ui/index.js";
 import type { PiEmittedEvent } from "./event-delivery.js";
+import type { PiEngineRuntime } from "./session-runtime.js";
+import type { EngineViewState } from "./view-state.js";
 export type AdapterCommandResult = OwnedUiCommandResult;
 export interface PiCommandDispatchPorts {
     sessionId(): string;
@@ -36,3 +38,14 @@ export declare class PiCommandDispatch {
     reset(): void;
     execute(command: OwnedUiCommand): Promise<AdapterCommandResult>;
 }
+/** What carrying out a command reaches: the running engine, the view state it updates, and disposal. */
+export interface EngineCommandContext {
+    readonly engine: Pick<PiEngineRuntime, "runtime" | "session" | "generation" | "sessionCommands">;
+    readonly state: Pick<EngineViewState, "activeModel" | "thinkingLevel" | "setTerminal" | "terminal">;
+    /** False while delivery is overloaded or admission is stopped; a late model change then stays unpublished. */
+    admissionOpen(): boolean;
+    emit(value: PiEmittedEvent): void;
+    dispose(): Promise<void>;
+}
+/** Carries out one admitted command against the running engine; throws when no session runs or the command fails. */
+export declare function performEngineCommand(command: OwnedUiCommand, context: EngineCommandContext): Promise<void>;

package/dist/integrations/pi/engine/command-dispatch.js

@@ -123,3 +123,60 @@ export class PiCommandDispatch {
         return { outcome, diagnostic };
     }
 }
+// Invariant: prompt input and session controls run through the engine's own session commands, which own queuing and images.
+async function runSessionCommand(request, context) {
+    const result = await context.engine.sessionCommands?.execute(request);
+    if (!result || result.outcome === "rejected" || result.outcome === "failed") {
+        throw new Error(request.type === "retry" ? "no previous prompt is available to retry" : `Pi session command failed: ${request.type}`);
+    }
+}
+function runPromptCommand(command, context) {
+    return runSessionCommand({
+        type: command.type,
+        text: command.text,
+        ...(command.images === undefined ? {} : { images: [...command.images] }),
+    }, context);
+}
+const ownedUiStateCommand = () => {
+    throw new Error("owned UI state commands belong to the owned UI layer, not the Pi engine adapter");
+};
+// Invariant: one handler per command type; the table is exhaustive, so a new command type cannot be silently ignored.
+const ENGINE_COMMANDS = {
+    "prompt": (command, context) => runPromptCommand(command, context),
+    "steer": (command, context) => runPromptCommand(command, context),
+    "follow-up": (command, context) => runPromptCommand(command, context),
+    "abort": (_command, context) => runSessionCommand({ type: "abort" }, context),
+    "retry": (_command, context) => runSessionCommand({ type: "retry" }, context),
+    "compact": (_command, context) => runSessionCommand({ type: "compact" }, context),
+    "set-model": async (command, context, { runtime, session, generation }) => {
+        const model = runtime.services.modelRuntime.getModel(command.model.providerId, command.model.modelId);
+        if (!model)
+            throw new Error(`model is unavailable: ${command.model.providerId}/${command.model.modelId}`);
+        await session.setModel(model);
+        if (generation === context.engine.generation && context.admissionOpen())
+            context.state.activeModel = { ...command.model };
+    },
+    "set-thinking-level": (command, context, { session }) => {
+        session.setThinkingLevel(command.thinkingLevel);
+        context.state.thinkingLevel = command.thinkingLevel;
+    },
+    "new-session": async (_command, _context, { runtime }) => { await runtime.newSession(); },
+    "resume-session": async (command, _context, { runtime }) => { await runtime.switchSession(command.sessionPath); },
+    "resize-surface": (command, context) => {
+        context.state.setTerminal(command.surface);
+        context.emit({ type: "terminal-surface", surface: context.state.terminal });
+    },
+    "shutdown": (_command, context) => context.dispose(),
+    "set-setting": ownedUiStateCommand,
+    "apply-customization": ownedUiStateCommand,
+    "remove-customization": ownedUiStateCommand,
+};
+/** Carries out one admitted command against the running engine; throws when no session runs or the command fails. */
+export async function performEngineCommand(command, context) {
+    const { runtime, session, generation } = context.engine;
+    if (!runtime || !session)
+        throw new Error("engine session is unavailable");
+    // Invariant: the table maps each type to the handler for exactly that command, so the command fits its own handler.
+    const handler = ENGINE_COMMANDS[command.type];
+    await handler(command, context, { runtime, session, generation });
+}

package/dist/integrations/pi/engine/host.js

@@ -86,7 +86,7 @@ class ProcessPiEngineHost {
             return;
         this.#disposed = true;
         this.#abort.abort();
-        const live = [...this.#sessions.values()].filter(session => !session.disposed);
+        const live = [...this.#sessions.values()].filter(session => !session.identity.disposed);
         this.#sessions.clear();
         await Promise.all(live.map(session => session.dispose()));
     }
@@ -107,7 +107,7 @@ class ProcessPiEngineHost {
     }
     #forgetDisposedSessions() {
         for (const [sessionId, session] of this.#sessions)
-            if (session.disposed)
+            if (session.identity.disposed)
                 this.#sessions.delete(sessionId);
     }
     // Rationale: the profile's timeout is installed once, by whichever session loads it first; a written

package/dist/integrations/pi/engine/ports.d.ts

@@ -0,0 +1,56 @@
+import type { AgentSession } from "../startup-public.js";
+import type { OwnedUiExtensionPort, OwnedUiImageAttachment, OwnedUiReleaseUpdate, OwnedUiSessionCatalogPort, OwnedUiSessionIdentityPort, OwnedUiSessionPort, OwnedUiSessionSettingsPort, OwnedUiWorkflowPort } from "../../../contracts/owned-ui/index.js";
+import type { PiPinnedSettingsCallback, PiPinnedSettingsSnapshot, PiSessionSelectorContext, PiTreeSelectorContext, PiWorkflowInteractionHost, PiWorkflowRequest, PiWorkflowResult } from "./workflows.js";
+import type { PiExtensionUiBinding } from "./extension-ui-binding.js";
+import type { PiResourceCatalog } from "./resource-catalog.js";
+import type { PiEngineRuntime } from "./session-runtime.js";
+import type { PiEngineSettings } from "./settings-port.js";
+import type { PiWorkflowContexts } from "./workflow-contexts.js";
+import type { PiWorkflowRunner } from "./workflow-runner.js";
+/**
+ * The Pi objects pinned selectors and transcript renderers are built from. They are not part of the
+ * session backend contract; only the session presenters owner reads them.
+ */
+export interface PiSessionPresentationSource {
+    pinnedModelSelectorContext(): ReturnType<PiWorkflowContexts["pinnedModelSelectorContext"]>;
+    pinnedSessionSelectorContext(): PiSessionSelectorContext;
+    pinnedTreeSelectorContext(): PiTreeSelectorContext;
+    pinnedMessageRenderer(customType: string): unknown;
+    pinnedToolRenderers(toolName: string): unknown;
+    pinnedShortcutDescriptions(bindings: Parameters<AgentSession["extensionRunner"]["getShortcuts"]>[0]): readonly {
+        readonly key: string;
+        readonly description: string;
+    }[];
+    pinnedSettingsModels(): Pick<PiPinnedSettingsSnapshot, "currentModel" | "availableDefaultModels">;
+    applyPinnedSettingValue(callback: PiPinnedSettingsCallback, value: unknown): Promise<PiWorkflowResult>;
+}
+export interface PiEngineAdapterPorts {
+    readonly identity: OwnedUiSessionIdentityPort;
+    readonly session: OwnedUiSessionPort;
+    readonly workflows: OwnedUiWorkflowPort;
+    readonly settings: OwnedUiSessionSettingsPort;
+    readonly catalog: OwnedUiSessionCatalogPort;
+    readonly extensions: OwnedUiExtensionPort;
+    readonly presentation: PiSessionPresentationSource;
+}
+/** The adapter's collaborators and its own session operations, which every port member reaches at call time. */
+export interface EnginePortParts {
+    readonly sessionId: string;
+    readonly agentDir: string;
+    readonly engine: Pick<PiEngineRuntime, "cwd" | "generation" | "bindingGeneration" | "currentSessionResumeMetadata" | "currentSessionFile">;
+    readonly contexts: PiWorkflowContexts;
+    readonly workflows: PiWorkflowRunner;
+    readonly settings: PiEngineSettings;
+    readonly resources: PiResourceCatalog;
+    readonly extensions: PiExtensionUiBinding;
+    readonly session: OwnedUiSessionPort;
+    disposed(): boolean;
+    executeWorkflow(request: PiWorkflowRequest): Promise<PiWorkflowResult>;
+    clearQueuedWorkflows(): readonly string[];
+    setWorkflowInteractionHost(interaction: PiWorkflowInteractionHost): void;
+    announceReleaseUpdate(release: OwnedUiReleaseUpdate): void;
+    resolveTranscriptImage(assetId: string): OwnedUiImageAttachment | null;
+    /** The running session's extension runner; throws when no session runs. */
+    extensionRunner(): AgentSession["extensionRunner"] | undefined;
+}
+export declare function createEnginePorts(parts: EnginePortParts): PiEngineAdapterPorts;

package/dist/integrations/pi/engine/ports.js

@@ -0,0 +1,89 @@
+// Invariant: every port member delegates at call time, so ports built once follow session replacement.
+export function createEnginePorts(parts) {
+    const { engine, contexts, workflows, settings, resources, extensions } = parts;
+    return {
+        identity: {
+            sessionId: parts.sessionId,
+            agentDir: parts.agentDir,
+            get cwd() { return engine.cwd; },
+            get sessionGeneration() { return engine.generation; },
+            get sessionBindingGeneration() { return engine.bindingGeneration; },
+            get disposed() { return parts.disposed(); },
+            currentSessionResumeMetadata: () => engine.currentSessionResumeMetadata(),
+            currentSessionFile: () => engine.currentSessionFile(),
+        },
+        session: parts.session,
+        workflows: {
+            executeWorkflow: request => parts.executeWorkflow(request),
+            executeBashWorkflow: (command, excludeFromContext) => workflows.executeBashWorkflow(command, excludeFromContext),
+            cycleModelWorkflow: direction => workflows.cycleModelWorkflow(direction),
+            workflowAutocompleteCommands: () => resources.workflowAutocompleteCommands(),
+            clearQueuedWorkflows: () => parts.clearQueuedWorkflows(),
+            reloadBlockedResult: () => workflows.reloadBlockedResult(),
+            copyWorkflowText: text => workflows.copyWorkflowText(text),
+            setWorkflowInteractionHost: interaction => { parts.setWorkflowInteractionHost(interaction); },
+        },
+        settings: {
+            get productMode() { return settings.productMode; },
+            snapshot: () => {
+                // Invariant: the selector-only model values travel on the presentation source, not in the neutral snapshot.
+                const { currentModel: _currentModel, availableDefaultModels: _availableDefaultModels, ...snapshot } = settings.pinnedSettingsSnapshot();
+                return snapshot;
+            },
+            bindOwner: (owner, handlers) => settings.bindSettingsOwner(owner, handlers),
+            setDefaultThinkingLevel: level => { settings.setDefaultThinkingLevel(level); },
+            configuredTheme: () => settings.configuredTheme(),
+        },
+        catalog: {
+            modelsContext: () => contexts.modelsContext(),
+            setSessionModelScope: scopeIds => { contexts.setSessionModelScope(scopeIds); },
+            persistModelScope: scopeIds => { contexts.persistModelScope(scopeIds); },
+            refreshModels: signal => contexts.refreshModels(signal),
+            pinnedScopedModelsContext: () => contexts.pinnedScopedModelsContext(),
+            updateScopedModels: enabledModelIds => { contexts.updateScopedModels(enabledModelIds); },
+            persistScopedModels: enabledModelIds => { contexts.persistScopedModels(enabledModelIds); },
+            refreshScopedModels: signal => contexts.refreshScopedModels(signal),
+            pinnedProjectTrustContext: () => contexts.pinnedProjectTrustContext(),
+            persistProjectTrust: updates => { contexts.persistProjectTrust(updates); },
+            pinnedLoginOptions: authType => contexts.loginOptions(authType),
+            pinnedLoginMethodOptions: providerReference => contexts.pinnedLoginMethodOptions(providerReference),
+            pinnedAmbientAuthentication: selection => contexts.pinnedAmbientAuthentication(selection),
+            pinnedLogoutOptions: () => contexts.logoutOptions(),
+            pinnedForkOptions: () => contexts.pinnedForkOptions(),
+        },
+        extensions: {
+            nonVisualResources: () => resources.nonVisualResources(),
+            extensionResources: () => resources.extensionResources(),
+            resolveTranscriptImage: assetId => parts.resolveTranscriptImage(assetId),
+            visualExtensionSupport: () => extensions.support(),
+            bindExtensionUi: (ui, shutdown) => extensions.bind(ui, shutdown),
+            unbindExtensionUi: () => extensions.unbind(),
+            bindClipboardWriter: writer => workflows.bindClipboardWriter(writer),
+            announceReleaseUpdate: release => { parts.announceReleaseUpdate(release); },
+        },
+        presentation: {
+            pinnedModelSelectorContext: () => contexts.pinnedModelSelectorContext(),
+            pinnedSessionSelectorContext: () => contexts.pinnedSessionSelectorContext(),
+            pinnedTreeSelectorContext: () => contexts.pinnedTreeSelectorContext(),
+            pinnedMessageRenderer: customType => parts.extensionRunner()?.getMessageRenderer?.(customType),
+            pinnedToolRenderers: toolName => {
+                const runner = parts.extensionRunner();
+                if (runner === undefined)
+                    return undefined;
+                if (typeof runner.resolveToolRenderers === "function") {
+                    return runner.resolveToolRenderers(toolName, () => runner.getToolDefinition?.(toolName));
+                }
+                return runner.getToolDefinition?.(toolName);
+            },
+            pinnedShortcutDescriptions: bindings => {
+                const shortcuts = parts.extensionRunner()?.getShortcuts?.(bindings);
+                return shortcuts === undefined ? [] : [...shortcuts].map(([key, shortcut]) => ({ key, description: shortcut.description ?? shortcut.extensionPath }));
+            },
+            pinnedSettingsModels: () => {
+                const { currentModel, availableDefaultModels } = settings.pinnedSettingsSnapshot();
+                return { ...(currentModel === undefined ? {} : { currentModel }), availableDefaultModels };
+            },
+            applyPinnedSettingValue: (callback, value) => settings.applyPinnedSettingValue(callback, value),
+        },
+    };
+}

package/dist/integrations/pi/engine/session-runtime.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { promisify } from "node:util";
 import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+import { residentProgressObserver } from "../../../foundation/resident-tabs/progress-observation.js";
 import { observeCompactionProgress } from "./compaction-progress.js";
 import { createPiRuntimeIntegration } from "./runtime-integration.js";
 import { PiSessionCommandIntegration } from "./session-integration.js";
@@ -369,8 +370,10 @@ export class PiEngineRuntime {
             return;
         const generation = this.#sessionGeneration;
         this.#unsubscribe = session.subscribe(event => {
-            if (generation === this.#sessionGeneration && !this.#ports.disposed())
-                this.#ports.event(event);
+            if (generation !== this.#sessionGeneration || this.#ports.disposed())
+                return;
+            residentProgressObserver()?.engineDelivery(event);
+            this.#ports.event(event);
         });
     }
     /**

package/dist/integrations/pi/engine/view-state.d.ts

@@ -0,0 +1,42 @@
+import type { OwnedUiDiagnostics, OwnedUiEditorState, OwnedUiModelInfo, OwnedUiSessionViewModel, OwnedUiStatusView, OwnedUiTerminalSurface, OwnedUiThinkingLevel, OwnedUiUsageView } from "../../../contracts/owned-ui/index.js";
+/**
+ * The engine adapter's own view-model state: lifecycle, editor, status, terminal surface, active
+ * model, thinking level, the usage cache, diagnostics, and the view revision. Every change that
+ * touches more than one field is one named mutator, so the adapter and its collaborators never
+ * rebuild these objects inline.
+ */
+export declare class EngineViewState {
+    #private;
+    lifecycle: OwnedUiSessionViewModel["lifecycle"];
+    activeModel: OwnedUiModelInfo | null;
+    thinkingLevel: OwnedUiThinkingLevel;
+    get revision(): number;
+    get editor(): OwnedUiEditorState;
+    get status(): OwnedUiStatusView;
+    get terminal(): OwnedUiTerminalSurface;
+    get diagnostics(): readonly OwnedUiDiagnostics[];
+    /** Any emitted event advances the revision. */
+    advance(): void;
+    /** A full view is about to be published: usage is recomputed and the revision advances. */
+    invalidate(): void;
+    invalidateUsage(): void;
+    /** The cached usage view, computed once per published view. */
+    usage(read: () => OwnedUiUsageView): OwnedUiUsageView;
+    /** The engine started: the session is ready and accepts submissions. */
+    markReady(): void;
+    /** A run started with `message` as its working status; true when the session was already busy. */
+    enterWork(message: string): boolean;
+    leaveWork(): void;
+    /** Records compaction or retry progress; false when it did not change. */
+    setWorkProgress(percent: Exclude<OwnedUiStatusView["workingProgress"], undefined>): boolean;
+    setQueuedSubmissions(queuedSubmissions: readonly string[]): void;
+    /** Fills an empty editor with `text`, as tree navigation does for the selected branch's prompt. */
+    offerEditorText(text: string): void;
+    setHardwareCursor(hardwareCursor: boolean): void;
+    setTerminal(surface: OwnedUiTerminalSurface): void;
+    /** A replaced session starts with an empty editor that accepts submissions and no working status. */
+    replaceSession(): void;
+    /** Delivery overload ended the run: ready when it can resume, stopped once disposed, otherwise failed. */
+    settleOverload(canResume: boolean, disposed: boolean): void;
+    recordDiagnostic(severity: OwnedUiDiagnostics["severity"], code: string, message: string, recoverable: boolean): OwnedUiDiagnostics;
+}

package/dist/integrations/pi/engine/view-state.js

@@ -0,0 +1,126 @@
+const DEFAULT_SURFACE = {
+    columns: 100,
+    rows: 32,
+    focusedRegion: "editor",
+    hardwareCursor: false,
+};
+const MAX_DIAGNOSTICS = 100;
+const MAX_STATUS_DIAGNOSTICS = 8;
+/**
+ * The engine adapter's own view-model state: lifecycle, editor, status, terminal surface, active
+ * model, thinking level, the usage cache, diagnostics, and the view revision. Every change that
+ * touches more than one field is one named mutator, so the adapter and its collaborators never
+ * rebuild these objects inline.
+ */
+export class EngineViewState {
+    #revision = 0;
+    #editor = {
+        text: "",
+        queuedSubmissions: [],
+        selection: null,
+        cursorOffset: 0,
+        historyRevision: 0,
+        submitEnabled: false,
+    };
+    #status = {
+        title: "Pi",
+        workingMessage: null,
+        diagnostics: [],
+        badges: [],
+    };
+    #terminal = DEFAULT_SURFACE;
+    lifecycle = "starting";
+    activeModel = null;
+    thinkingLevel = "medium";
+    #usage;
+    #diagnostics = [];
+    get revision() { return this.#revision; }
+    get editor() { return this.#editor; }
+    get status() { return this.#status; }
+    get terminal() { return this.#terminal; }
+    get diagnostics() { return this.#diagnostics; }
+    /** Any emitted event advances the revision. */
+    advance() {
+        this.#revision += 1;
+    }
+    /** A full view is about to be published: usage is recomputed and the revision advances. */
+    invalidate() {
+        this.#usage = undefined;
+        this.#revision += 1;
+    }
+    invalidateUsage() {
+        this.#usage = undefined;
+    }
+    /** The cached usage view, computed once per published view. */
+    usage(read) {
+        return this.#usage ??= read();
+    }
+    /** The engine started: the session is ready and accepts submissions. */
+    markReady() {
+        this.lifecycle = "ready";
+        this.#editor = { ...this.#editor, submitEnabled: true };
+    }
+    /** A run started with `message` as its working status; true when the session was already busy. */
+    enterWork(message) {
+        const wasBusy = this.lifecycle === "busy";
+        this.lifecycle = "busy";
+        this.#status = { ...this.#status, workingMessage: message, workingProgress: null };
+        return wasBusy;
+    }
+    leaveWork() {
+        this.lifecycle = "ready";
+        this.#status = { ...this.#status, workingMessage: null, workingProgress: null };
+    }
+    /** Records compaction or retry progress; false when it did not change. */
+    setWorkProgress(percent) {
+        if (this.#status.workingProgress === percent)
+            return false;
+        this.#status = { ...this.#status, workingProgress: percent };
+        return true;
+    }
+    setQueuedSubmissions(queuedSubmissions) {
+        this.#editor = { ...this.#editor, queuedSubmissions: [...queuedSubmissions], historyRevision: this.#editor.historyRevision + 1 };
+    }
+    /** Fills an empty editor with `text`, as tree navigation does for the selected branch's prompt. */
+    offerEditorText(text) {
+        if (!this.#editor.text.trim()) {
+            this.#editor = { ...this.#editor, text, selection: null, cursorOffset: text.length };
+        }
+    }
+    setHardwareCursor(hardwareCursor) {
+        this.#terminal = { ...this.#terminal, hardwareCursor };
+    }
+    setTerminal(surface) {
+        this.#terminal = { ...surface };
+    }
+    /** A replaced session starts with an empty editor that accepts submissions and no working status. */
+    replaceSession() {
+        this.#editor = {
+            text: "",
+            queuedSubmissions: [],
+            selection: null,
+            cursorOffset: 0,
+            historyRevision: this.#editor.historyRevision + 1,
+            submitEnabled: true,
+        };
+        this.#status = { ...this.#status, workingMessage: null, workingProgress: null, badges: [] };
+    }
+    /** Delivery overload ended the run: ready when it can resume, stopped once disposed, otherwise failed. */
+    settleOverload(canResume, disposed) {
+        this.#status = { ...this.#status, workingMessage: null, workingProgress: null };
+        this.lifecycle = disposed ? "stopped" : canResume ? "ready" : "failed";
+        this.#editor = { ...this.#editor, submitEnabled: canResume && !disposed };
+        this.#revision += 1;
+    }
+    recordDiagnostic(severity, code, message, recoverable) {
+        const diagnostic = { sequence: this.#diagnostics.length, code, severity, message, recoverable };
+        this.#diagnostics.push(diagnostic);
+        if (this.#diagnostics.length > MAX_DIAGNOSTICS)
+            this.#diagnostics.shift();
+        this.#status = {
+            ...this.#status,
+            diagnostics: [...this.#status.diagnostics, message].slice(-MAX_STATUS_DIAGNOSTICS),
+        };
+        return diagnostic;
+    }
+}

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

@@ -1,5 +1,11 @@
 import { type ProgramStatus, type WheelScrollLines } from "@earendil-works/pi-tui";
 import type { PiTuiComponentPort, PiTuiInputListener, PiTuiOverlayHandle, PiTuiOverlayOptions, PiTuiPreInputListener, PiTuiRuntimeAdapterOptions, PiTuiRuntimeState, PiTuiScrollState, PiTuiStopOptions, PiTuiViewport } from "./contracts.js";
+/**
+ * Re-encodes one key report decoded by pi-tui in the legacy form, so a kitty-keyboard child
+ * (resident tabs) and a legacy terminal produce the same owned-screen action. Releases decode
+ * to nothing; mouse reports, paste, and unknown sequences pass through unchanged.
+ */
+export declare function legacyKeyInput(data: string): string;
 export type PiTuiRuntimeErrorStage = "construction" | "start" | "input-drain" | "restoration";
 /** Identifies the Pi TUI lifecycle stage that failed while preserving the original cause. */
 export declare class PiTuiRuntimeError extends Error {

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

@@ -1,8 +1,35 @@
-import { HStack, ProcessTerminal, ScrollView, TuiAltScreen, TuiMainScreen, VStack, visibleWidth, } from "@earendil-works/pi-tui";
+import { HStack, ProcessTerminal, ScrollView, TuiAltScreen, TuiMainScreen, VStack, decodeKittyPrintable, isKeyRelease, parseKey, visibleWidth, } from "@earendil-works/pi-tui";
 import { MouseReportInput, stripSgrMouseReports } from "./mouse-report-input.js";
 import { GeometryObservedAltScreen, OverlayGeometryTracker } from "./overlay-geometry.js";
 import { boundedCleanup, EMERGENCY_TERMINAL_RESET } from "../../../foundation/terminal-cleanup/terminal-reset.js";
 import { InputPresentationCoordinator, } from "./input-presentation-coordinator.js";
+// Protocol: the legacy bytes owned screens and their key tables compare against.
+const LEGACY_KEY_BYTES = {
+    escape: "\u001b", up: "\u001b[A", down: "\u001b[B", right: "\u001b[C", left: "\u001b[D",
+    "shift+up": "\u001b[1;2A", "shift+down": "\u001b[1;2B", pageUp: "\u001b[5~", pageDown: "\u001b[6~",
+    home: "\u001b[H", end: "\u001b[F", "ctrl+home": "\u001b[1;5H", "ctrl+end": "\u001b[1;5F",
+    enter: "\r", tab: "\t", "shift+tab": "\u001b[Z", backspace: "\u007f", delete: "\u001b[3~",
+    space: " ", "ctrl+c": "\u0003", "ctrl+z": "\u001a",
+};
+/**
+ * Re-encodes one key report decoded by pi-tui in the legacy form, so a kitty-keyboard child
+ * (resident tabs) and a legacy terminal produce the same owned-screen action. Releases decode
+ * to nothing; mouse reports, paste, and unknown sequences pass through unchanged.
+ */
+export function legacyKeyInput(data) {
+    if (data.length <= 1 || !data.startsWith("\u001b"))
+        return data;
+    const key = parseKey(data);
+    if (key === undefined)
+        return data;
+    if (isKeyRelease(data))
+        return "";
+    const legacy = LEGACY_KEY_BYTES[key];
+    if (legacy !== undefined)
+        return legacy;
+    const printable = decodeKittyPrintable(data);
+    return printable !== undefined && printable >= " " && printable !== "\u007f" ? printable : data;
+}
 /** Identifies the Pi TUI lifecycle stage that failed while preserving the original cause. */
 export class PiTuiRuntimeError extends Error {
     stage;

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

@@ -52,6 +52,17 @@ export interface DamageAwareTerminalOptions {
     };
     readonly onResize?: () => void;
     readonly onHyperlinkCleanupRequired?: () => void;
+    /** Exact-artifact fault controls evaluated before physical writes; absent in ordinary sessions. */
+    readonly allowWrite?: () => boolean;
+    readonly writeChunks?: (data: string) => readonly string[];
+    /** Optional payload-free observation after a terminal write returns. */
+    readonly onWrite?: (metadata: {
+        readonly bytes: number;
+        readonly fragments: number;
+        readonly transaction: "synchronized-output" | "ordinary";
+        readonly frameId?: number;
+        readonly cause?: string;
+    }) => void;
 }
 /**
  * A fail-closed adapter for one pinned Pi fullscreen write grammar. Semantic

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

@@ -166,7 +166,36 @@ export class DamageAwareTerminalAdapter {
         const forwarded = this.#canvasBackgroundAnsi === null
             ? output
             : paintTerminalCanvasFrame(output, this.#canvasBackgroundAnsi);
-        this.inner.write(forwarded);
+        let writeAllowed = true;
+        try {
+            writeAllowed = this.options.allowWrite?.() ?? true;
+        }
+        catch { /* Invariant: fixture controls fail open. */ }
+        if (!writeAllowed)
+            return;
+        let chunks = [forwarded];
+        try {
+            const controlled = this.options.writeChunks?.(forwarded);
+            if (controlled !== undefined && controlled.length > 0 && controlled.length <= 4_096
+                && controlled.join("") === forwarded)
+                chunks = controlled;
+        }
+        catch { /* Invariant: fixture controls fail open without corrupting the renderer write. */ }
+        for (const chunk of chunks)
+            this.inner.write(chunk);
+        try {
+            this.options.onWrite?.({
+                bytes: Buffer.byteLength(forwarded),
+                fragments: chunks.length,
+                transaction: forwarded.startsWith(BEGIN_SYNCHRONIZED_OUTPUT) && forwarded.endsWith(END_SYNCHRONIZED_OUTPUT)
+                    ? "synchronized-output" : "ordinary",
+                ...(armed === undefined ? {} : {
+                    frameId: armed.descriptor.frameId,
+                    cause: armed.descriptor.cause,
+                }),
+            });
+        }
+        catch { /* Invariant: observation never changes rendering or write completion. */ }
         if (epoch !== this.#epoch
             || (armed !== undefined && this.#lastConsumedFrameId !== armed.descriptor.frameId))
             return;

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

@@ -7,7 +7,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-10-19T04:50:42.711Z",
+  "builtAt": "2026-10-20T08:53:57.218Z",
   "artifact": {
     "filename": "process-guardian.node",
     "sha256": "a87eaaffcd986b624c8b044b756446cc1bdaf4334a1775b97820542fe34f9fb7",

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

@@ -9,11 +9,11 @@
   "architecture": "arm64",
   "target": "aarch64-apple-darwin",
   "capability": "supported",
-  "builtAt": "2026-10-19T04:52:31.538Z",
+  "builtAt": "2026-10-20T08:57:24.837Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "af7b9fee2efa8478c728465031e73fb316b6b7012d11de0364130b0acd1b6e62",
-    "size": 5173904
+    "sha256": "1885cc705611eb1b5a06148d77cb3e85dc99321124b7fec4be382630292555c6",
+    "size": 5747616
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

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

@@ -7,7 +7,7 @@
   "platform": "darwin",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-19T04:50:48.870Z",
+  "builtAt": "2026-10-20T08:54:05.958Z",
   "artifact": {
     "filename": "process-guardian.node",
     "sha256": "783a65f0de287a1c02cd5429dbe97bc8633f4cc8a7b92e3e961180b9bdcff814",

package/dist/native/darwin-x64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "x64",
   "target": "x86_64-apple-darwin",
   "capability": "supported",
-  "builtAt": "2026-10-19T04:54:11.822Z",
+  "builtAt": "2026-10-20T09:00:09.786Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "1a5465ea12ecfe76d5f0c8fd5c11dee99597b4206a7e9ece01b37fc5c477c211",
-    "size": 5656912
+    "sha256": "a34271e9cc5ec28a638dd4bcaff97a7fb33ac0856f4cd5b18814400d540e8da7",
+    "size": 6263000
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

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

@@ -7,7 +7,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-19T04:50:20.956Z",
+  "builtAt": "2026-10-20T08:53:35.318Z",
   "artifact": {
     "filename": "process-guardian.node",
     "sha256": "118e5954e3864672bd8482ab7edf419cb27dcdf2533720316979b7f5cc5a53a5",

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

@@ -9,11 +9,11 @@
   "architecture": "x64",
   "target": "x86_64-unknown-linux-gnu",
   "capability": "supported",
-  "builtAt": "2026-10-19T04:53:24.471Z",
+  "builtAt": "2026-10-20T08:55:32.085Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "843b10ab29eddf859a74a97875ba646a90917d9ec78445474895bb64f6e0772a",
-    "size": 6353496
+    "sha256": "5c7b589cd36b901a4a02d172f84d70111f7f4cec5ad796a6ea13524109fa4b50",
+    "size": 6988960
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",