@timurproko/a1 0.1.8-dev.299 → 0.1.8-dev.332

package/dist/integrations/pi/session-ui/session-shell.js

@@ -53,10 +53,12 @@ export class OwnedUiSessionShell {
     #lastEscapeTime = 0;
     #activeLoginDialog;
     #sessionGeneration;
+    #sessionBindingGeneration;
     #suggestionModelKey;
     constructor(options) {
         this.backend = options.backend;
         this.#sessionGeneration = this.backend.sessionGeneration;
+        this.#sessionBindingGeneration = this.backend.sessionBindingGeneration;
         this.#suggestionModelKey = modelKey(this.backend.view());
         this.#cwd = options.cwd;
         this.#routeHost = options.routeHost ?? null;
@@ -73,7 +75,7 @@ export class OwnedUiSessionShell {
             getColumns: () => runtime?.viewport().columns ?? options.terminal?.columns ?? 80,
             getRows: () => runtime?.viewport().rows ?? options.terminal?.rows ?? 24,
             requestRender: force => runtime?.requestRender(force),
-            requestHyperlinkCleanup: () => damageTerminal?.requestHyperlinkCleanup(),
+            requestHyperlinkCleanup: rows => damageTerminal?.requestHyperlinkCleanup(rows),
             onViewportFrame: frame => damageTerminal?.arm(frame.descriptor, {
                 overlayActive: runtime?.hasOverlay() ?? false,
                 selectionActive: this.root.hasActiveSelection(),
@@ -139,6 +141,7 @@ export class OwnedUiSessionShell {
         }, this.backend.agentDir, {
             getMessageRenderer: customType => this.backend.pinnedMessageRenderer(customType),
             getToolDefinition: toolName => this.backend.pinnedToolDefinition(toolName),
+            getShortcuts: bindings => this.backend.pinnedShortcutDescriptions(bindings),
         }, options.sessionLayout, {
             resolve: assetId => this.backend.resolveTranscriptImage(assetId),
         });
@@ -237,6 +240,17 @@ export class OwnedUiSessionShell {
             ? this.runtime.addPreInputListener(data => {
                 if (options.inputPresentation?.coordination === false)
                     this.#streamPresentation.noteImmediatePresentation();
+                // Compatibility: Pi's fullscreen renderer also intercepts plain Home/End.
+                // Deliver them to the focused owned input before that outer scroll handler;
+                // overlays retain Pi's normal dispatch, and comparison profiles never enter here.
+                if (!this.runtime.hasOverlay() && (this.root.editor.matchesTerminalKey(data, "home")
+                    || this.root.editor.matchesTerminalKey(data, "end"))) {
+                    if (this.root.usesDefaultInputSurface())
+                        this.root.handleViewportPreInput(data, true);
+                    this.root.handleInput(data);
+                    this.runtime.requestRender();
+                    return { consume: true };
+                }
                 // Invariant: an overlay or editor-replacement screen owns its entire pointer
                 // surface. Letting the transcript pre-router inspect those reports
                 // steals settings value menus and numeric +/- controls before the
@@ -322,7 +336,6 @@ export class OwnedUiSessionShell {
                 fallback: this.view().transcript.flatMap(block => block.kind === "user" ? [block.text] : []),
                 active: () => this.root.usesDefaultInputSurface(),
                 render: () => this.runtime.requestRender(),
-                failure: message => this.root.addExtensionNotification(message, "warning"),
             });
         }
         this.#extensionBridge = createPiExtensionUiBridge({
@@ -793,8 +806,7 @@ export class OwnedUiSessionShell {
     showLoginMethodSelector(providerReference) {
         const method = this.backend.pinnedLoginMethodOptions(providerReference);
         if (method.options.length === 0) {
-            this.root.appendWorkflowResult({ command: "login", outcome: "failed", message: `No authentication methods available for ${providerReference}` });
-            this.runtime.requestRender();
+            this.showLoginProviderSelector(undefined, providerReference);
             return;
         }
         if (method.options.length === 1) {
@@ -836,6 +848,20 @@ export class OwnedUiSessionShell {
             initialFilterMode: context.filterMode,
             ...(initialSelectedId === undefined ? {} : { initialSelectedId }),
             onLabelChange: context.appendLabelChange,
+            onCopy: text => {
+                if (!text) {
+                    this.root.appendWorkflowResult({ command: "tree", outcome: "failed", message: "Selected entry has no text to copy" });
+                    this.runtime.requestRender();
+                    return;
+                }
+                void this.backend.copyWorkflowText(text).then(() => {
+                    this.root.appendWorkflowStatus("Copied selected message to clipboard");
+                    this.runtime.requestRender();
+                }).catch(error => {
+                    this.root.appendWorkflowResult({ command: "tree", outcome: "failed", message: error instanceof Error ? error.message : String(error) });
+                    this.runtime.requestRender();
+                });
+            },
             onCancel: close,
             onSelect: entryId => {
                 close();
@@ -863,10 +889,10 @@ export class OwnedUiSessionShell {
         this.root.setInputSurface(component);
         this.runtime.requestRender();
     }
-    showLoginProviderSelector(authType) {
+    showLoginProviderSelector(authType, initialSearchInput) {
         const options = this.backend.pinnedLoginOptions(authType);
         if (options.length === 0) {
-            this.root.appendWorkflowStatus(authType === "oauth" ? "No subscription providers available." : "No API key providers available.");
+            this.root.appendWorkflowStatus(authType === "oauth" ? "No subscription providers available." : authType === "api_key" ? "No API key providers available." : "No login providers available.");
             this.runtime.requestRender();
             return;
         }
@@ -879,8 +905,9 @@ export class OwnedUiSessionShell {
             void this.runWorkflow({ command: "login", argument: "", selection: id });
         }, () => {
             close();
-            this.showLoginAuthTypeSelector();
-        });
+            if (authType !== undefined)
+                this.showLoginAuthTypeSelector();
+        }, initialSearchInput);
         this.root.setInputSurface(component);
         this.runtime.requestRender();
     }
@@ -961,6 +988,24 @@ export class OwnedUiSessionShell {
         return this.runWorkflow({ command: "quit", argument: "" });
     }
     async runWorkflow(request) {
+        if (request.command === "login" && request.selection !== undefined) {
+            const setup = this.backend.pinnedAmbientAuthentication(request.selection);
+            if (setup) {
+                const close = () => {
+                    this.root.setInputSurface(null);
+                    this.runtime.requestRender();
+                };
+                const dialog = createPiShellLoginDialog({
+                    getColumns: () => this.runtime.viewport().columns,
+                    getRows: () => this.runtime.viewport().rows,
+                    requestRender: () => this.runtime.requestRender(),
+                }, setup.providerId, close, setup.providerName, setup.title);
+                dialog.showInfo(setup.message, [], true);
+                this.root.setInputSurface(dialog);
+                this.runtime.requestRender();
+                return { outcome: "completed", diagnostic: null };
+            }
+        }
         if (request.command === "scoped-models" && request.selection === undefined && request.confirmed === undefined) {
             this.showScopedModelsSelector();
             return { outcome: "completed", diagnostic: null };
@@ -1001,8 +1046,13 @@ export class OwnedUiSessionShell {
             return { outcome: "completed", diagnostic: null };
         }
         if (request.command === "reload") {
+            const blocked = this.backend.reloadBlockedResult();
+            if (blocked) {
+                this.root.appendWorkflowResult(blocked);
+                this.runtime.requestRender();
+                return workflowAdapterResult(blocked);
+            }
             this.root.resetExtensionUi();
-            this.root.resetWorkflowPresentation();
         }
         const shareSurface = request.command === "share"
             ? createPiShellOperationLoader({
@@ -1053,6 +1103,8 @@ export class OwnedUiSessionShell {
             return { outcome: "failed", diagnostic: `Owned controller missing for ${request.command}` };
         }
         if (request.command === "reload" && result.outcome === "completed") {
+            this.root.resetWorkflowPresentation();
+            this.root.editor.reloadKeybindings();
             this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
         }
         this.root.appendWorkflowResult(result);
@@ -1211,9 +1263,7 @@ export class OwnedUiSessionShell {
         attempt(() => this.#extensionBridge.dispose());
         // Invariant: terminal restoration precedes any potentially stalled backend teardown.
         await this.runtime.dispose().catch(error => failures.push(error));
-        const historySaved = await historyCleanup.catch(() => false);
-        if (!historySaved)
-            this.runtime.writeAfterStop("Prompt history could not finish saving before exit.\n");
+        await historyCleanup.catch(() => false); // Security: background durability outcomes never enter terminal output.
         await boundedCleanup(() => pasteCleanup).catch(error => failures.push(error));
         await boundedCleanup(() => this.backend.unbindExtensionUi()).catch(error => failures.push(error));
         if (failures.length > 0)
@@ -1251,7 +1301,11 @@ export class OwnedUiSessionShell {
             this.root.resetPendingPastes();
             this.#promptSuggestions?.invalidate();
             this.#sessionGeneration = this.backend.sessionGeneration;
-            this.#promptHistory?.reset(view.transcript.flatMap(block => block.kind === "user" ? [block.text] : []));
+            // Invariant: delivery recovery invalidates callbacks, not same-session local recall or its draft.
+            if (this.#sessionBindingGeneration !== this.backend.sessionBindingGeneration) {
+                this.#sessionBindingGeneration = this.backend.sessionBindingGeneration;
+                this.#promptHistory?.reset(view.transcript.flatMap(block => block.kind === "user" ? [block.text] : []));
+            }
             this.#activeLoginDialog = undefined;
             this.#extensionBridge.reset();
             // Invariant: a replaced session takes its transient viewport and owned-route state with it.

package/dist/integrations/pi/session-ui/session-viewport-controller.d.ts

@@ -5,8 +5,8 @@ export interface SessionViewportControllerOptions {
     readonly enabled: boolean;
     readonly editor: PiShellEditorPort;
     readonly requestRender: (force?: boolean) => void;
-    readonly requestHyperlinkCleanup?: () => void;
-    /** Whether mutable editor URL chips need an immediate forced repaint on deletion. */
+    readonly requestHyperlinkCleanup?: (rows?: readonly number[]) => void;
+    /** Whether mutable editor URL chips need targeted link-cell cleanup on deletion. */
     readonly hasEditorLinks?: () => boolean;
 }
 export interface SessionViewportInputResult {
@@ -28,6 +28,11 @@ export declare class SessionViewportController {
     get hasSelection(): boolean;
     get selectionRevision(): number;
     get presentationRevision(): number;
+    /** Latest reported coordinates; exposed without rendering for frame provenance and evidence. */
+    get pointerPosition(): {
+        readonly column: number;
+        readonly row: number;
+    } | undefined;
     get frame(): TranscriptViewportFrame | null;
     setEditorPointerFrame(frame: {
         readonly rowStart: number;

package/dist/integrations/pi/session-ui/session-viewport-controller.js

@@ -60,6 +60,10 @@ export class SessionViewportController {
     get presentationRevision() {
         return this.#presentationRevision;
     }
+    /** Latest reported coordinates; exposed without rendering for frame provenance and evidence. */
+    get pointerPosition() {
+        return this.#pointerPosition;
+    }
     get frame() {
         return this.#viewport.frame;
     }
@@ -85,8 +89,8 @@ export class SessionViewportController {
             if (this.#hoveredHyperlinkKey !== undefined && next !== this.#hoveredHyperlinkKey) {
                 // Platform: Windows Terminal can leave its solid native-hover underline behind
                 // when a following viewport moves the link away from a stationary pointer.
-                this.#requestHyperlinkCleanup();
-                this.#requestRender(true);
+                this.#requestHyperlinkCleanup([this.#pointerPosition.row]);
+                this.#requestRender();
             }
             this.#hoveredHyperlinkKey = next;
         }
@@ -157,7 +161,24 @@ export class SessionViewportController {
         // Platform: URL chip deletion must overwrite terminal link cells in the same frame.
         if (EDITOR_LINK_DELETION_INPUTS.has(data) && this.#hasEditorLinks()) {
             this.#requestHyperlinkCleanup();
-            this.#requestRender(true);
+            this.#requestRender();
+        }
+        // Invariant: content shortcuts never reach the prompt, even before the first frame
+        // or when scrolling is a no-op. Plain Home/End remain editor line navigation.
+        if (allowWheel && this.#editor.matchesTerminalKey(data, "ctrl+home")) {
+            if (this.#viewport.scrollTo(0, now)) {
+                this.#scheduleActivityExpiry();
+                this.#requestRender();
+            }
+            return { data: "", consumed: true };
+        }
+        if (allowWheel && this.#editor.matchesTerminalKey(data, "ctrl+end")) {
+            if (!this.#viewport.followingEnd) {
+                this.#viewport.scrollToEnd(now);
+                this.#scheduleActivityExpiry();
+                this.#requestRender();
+            }
+            return { data: "", consumed: true };
         }
         if (this.#viewport.frame === null) {
             // Invariant: a not-yet-painted A1 screen is not Pi's selection surface.
@@ -183,21 +204,6 @@ export class SessionViewportController {
                 }
             }
         }
-        if (allowWheel && this.#editor.matchesTerminalKey(data, "home")) {
-            if (this.#viewport.scrollTo(0, now)) {
-                this.#scheduleActivityExpiry();
-                this.#requestRender();
-            }
-            return { data: "", consumed: true };
-        }
-        if (allowWheel && this.#editor.matchesTerminalKey(data, "end")) {
-            if (!this.#viewport.followingEnd) {
-                this.#viewport.scrollToEnd(now);
-                this.#scheduleActivityExpiry();
-                this.#requestRender();
-            }
-            return { data: "", consumed: true };
-        }
         if (allowWheel && (SHIFT_UP_INPUTS.has(data) || SHIFT_DOWN_INPUTS.has(data))) {
             const scrolled = SHIFT_UP_INPUTS.has(data)
                 ? this.#viewport.scrollToPreviousPrompt(now)
@@ -236,8 +242,7 @@ export class SessionViewportController {
                 const nextHyperlink = this.#hyperlinkKeyAt(frame, event.column, event.row);
                 if (this.#hoveredHyperlinkKey !== undefined && nextHyperlink !== this.#hoveredHyperlinkKey) {
                     // Platform: overwrite Windows Terminal's cached native-hover underline exactly once.
-                    this.#requestHyperlinkCleanup();
-                    forceRepaint = true;
+                    this.#requestHyperlinkCleanup(previousPointer === undefined ? undefined : [previousPointer.row]);
                     repaint = true;
                 }
                 this.#hoveredHyperlinkKey = nextHyperlink;

package/dist/integrations/pi/session-ui/text-paste.d.ts

@@ -0,0 +1,5 @@
+/** Normalize clipboard text and classify its compact label using the pinned Pi 0.84.2 paste policy. */
+export declare function prepareTextPaste(source: string): {
+    readonly text: string;
+    readonly label?: string;
+};

package/dist/integrations/pi/session-ui/text-paste.js

@@ -0,0 +1,16 @@
+/** Normalize clipboard text and classify its compact label using the pinned Pi 0.84.2 paste policy. */
+export function prepareTextPaste(source) {
+    // Compatibility: extended-key terminals can encode literal controls inside bracketed paste.
+    const decoded = source.replace(/\x1b\[(\d+);5u/g, (sequence, value) => {
+        const code = Number(value);
+        if (code >= 65 && code <= 90)
+            return String.fromCharCode(code - 64);
+        if (code >= 97 && code <= 122)
+            return String.fromCharCode(code - 96);
+        return sequence;
+    });
+    const text = decoded.replace(/\r\n?/g, "\n").replace(/\t/g, "    ").replace(/[\x00-\x09\x0b-\x1f]/g, "");
+    const lines = text.split("\n").length;
+    const label = lines > 10 ? `+${lines} lines` : text.length > 1000 ? `${text.length} chars` : undefined;
+    return { text, ...(label === undefined ? {} : { label }) };
+}

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

@@ -12,6 +12,12 @@ export interface PiTuiDamageFrameDescriptor {
         readonly rowStart: number;
         readonly rowEnd: number;
     } | null;
+    /**
+     * Visible rows owned by the block that is currently streaming. A live block repaints
+     * every row it owns when it reflows, so the allowed damage follows the declared tail
+     * instead of assuming a one-row tail.
+     */
+    readonly liveTailRows?: number;
     readonly verticalShiftRows: number;
     readonly safeVerticalShift: boolean;
     readonly cause: string;
@@ -34,6 +40,7 @@ export interface DamageAwareTerminalOptions {
     /** The shell supplies visible-row analysis; the terminal layer owns no UI parser. */
     readonly inspectHyperlinks: (content: string) => {
         readonly ranges: readonly unknown[];
+        readonly hasExplicitLink: boolean;
         readonly signature: string;
         readonly replaySafe: boolean;
         readonly width: number;
@@ -56,8 +63,8 @@ export declare class DamageAwareTerminalAdapter implements PiTuiTerminalPort {
     get kittyProtocolActive(): boolean;
     get lastDecision(): PiTuiDamageDecision;
     get hyperlinkCleanupPending(): boolean;
-    /** Latches cleanup through composition/coalescing until a complete write covers it. */
-    requestHyperlinkCleanup(): void;
+    /** Latches the former link rows, including rows whose replacement contains no link. */
+    requestHyperlinkCleanup(rows?: readonly number[]): void;
     arm(descriptor: PiTuiDamageFrameDescriptor, safety: PiTuiDamageFrameSafety): void;
     start(onInput: (data: string) => void, onResize: () => void): void;
     stop(): void;

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

@@ -15,6 +15,8 @@ export class DamageAwareTerminalAdapter {
     #rows = new Map();
     #links = new Map();
     #cleanupRevision = 0;
+    #cleanupRows = new Set();
+    #cleanupNeedsCompleteFrame = false;
     #cleanedRevision = 0;
     #recoveryRevision = 0;
     #epoch = 0;
@@ -38,8 +40,23 @@ export class DamageAwareTerminalAdapter {
     get kittyProtocolActive() { return this.inner.kittyProtocolActive; }
     get lastDecision() { return this.#decision; }
     get hyperlinkCleanupPending() { return this.#cleanupRevision > this.#cleanedRevision; }
-    /** Latches cleanup through composition/coalescing until a complete write covers it. */
-    requestHyperlinkCleanup() { this.#cleanupRevision += 1; }
+    /** Latches the former link rows, including rows whose replacement contains no link. */
+    requestHyperlinkCleanup(rows) {
+        this.#cleanupRevision += 1;
+        if (rows !== undefined) {
+            for (const row of rows) {
+                if (Number.isSafeInteger(row) && row >= 1 && row <= this.rows)
+                    this.#cleanupRows.add(row);
+            }
+        }
+        else {
+            // Invariant: no known pointer is not proof of no host-hover decoration. Unscoped
+            // removal/invalidation repairs every previously linked row, not every screen row.
+            for (const [row, state] of this.#links)
+                if (state.ranges.length > 0)
+                    this.#cleanupRows.add(row);
+        }
+    }
     arm(descriptor, safety) {
         this.#armed = { descriptor, safety };
     }
@@ -56,6 +73,8 @@ export class DamageAwareTerminalAdapter {
         this.#epoch += 1;
         this.#armed = undefined;
         this.#cleanupRevision = this.#cleanedRevision = this.#recoveryRevision = 0;
+        this.#cleanupRows.clear();
+        this.#cleanupNeedsCompleteFrame = false;
         this.#lastConsumedFrameId = 0;
         this.#invalidateRows();
         this.inner.stop();
@@ -77,25 +96,19 @@ export class DamageAwareTerminalAdapter {
             this.#invalidatePresentation();
         if (unknownPaint && !this.hyperlinkCleanupPending && this.options.inspectHyperlinks(data).ranges.length > 0) {
             this.requestHyperlinkCleanup();
+            this.#cleanupNeedsCompleteFrame = true;
         }
-        if (parsed !== null && !this.hyperlinkCleanupPending) {
-            for (const row of parsed.rows) {
-                const previous = this.#links.get(row.row);
-                if (previous === undefined || this.#rows.get(row.row) === row.content
-                    || (previous.replaySafe && previous.ranges.length === 0))
-                    continue;
-                const next = this.options.inspectHyperlinks(row.content);
-                if (previous.ranges.length > 0 && previous.signature !== next.signature) {
-                    this.requestHyperlinkCleanup();
-                    break;
-                }
-            }
-        }
+        // Invariant: a deliberate same-geometry reset discards presented link state. Ordinary streamed
+        // row changes are not cleanup requests: candidate-looking text is not terminal state.
+        if (sameGeometry && parsed?.structuralPrefix === "\u001b[2J"
+            && hasCompleteScreenRows(parsed.rows, this.rows) && !this.hyperlinkCleanupPending
+            && !this.#hasSameHyperlinkState(parsed.rows))
+            this.requestHyperlinkCleanup();
         const decision = this.#decide(armed, parsed);
+        const coveredRevision = this.#cleanupRevision;
         const cleanup = this.hyperlinkCleanupPending && parsed !== null
             && (armed === undefined || (armed.descriptor.width === this.columns && armed.descriptor.height === this.rows))
-            ? this.#completeCleanupFrame(parsed) : null;
-        const coveredRevision = this.#cleanupRevision;
+            ? this.#boundedCleanupFrame(parsed) : null;
         const epoch = this.#epoch;
         let output = data;
         if (cleanup !== null) {
@@ -107,8 +120,9 @@ export class DamageAwareTerminalAdapter {
         }
         else {
             this.#decision = decision;
-            if (decision.reason === "suppressed-redundant-clear" && parsed !== null)
-                output = buildClearlessWrite(parsed);
+            if (decision.reason === "suppressed-redundant-clear" && parsed !== null) {
+                output = buildClearlessWrite(parsed, this.#rows);
+            }
             else if (decision.transformed && armed !== undefined && parsed !== null) {
                 output = buildDamageWrite(parsed, armed.descriptor, new Set(decision.paintedRows), this.#rows);
             }
@@ -117,11 +131,16 @@ export class DamageAwareTerminalAdapter {
         if (epoch !== this.#epoch
             || (armed !== undefined && this.#lastConsumedFrameId !== armed.descriptor.frameId))
             return;
-        // Invariant: cache invalidation follows forwarded bytes, not a clear which
-        // was stripped from the input. A synthesized cleanup publishes every row.
+        // Invariant: cache invalidation follows forwarded bytes, not a suppressed clear.
+        // A bounded cleanup preserves prior rows and publishes all changed or invalidated rows.
         this.#rememberFrame(armed?.descriptor, cleanup ?? parsed, output);
-        if (cleanup !== null)
+        if (cleanup !== null) {
             this.#cleanedRevision = Math.max(this.#cleanedRevision, coveredRevision);
+            if (this.#cleanupRevision === coveredRevision) {
+                this.#cleanupRows.clear();
+                this.#cleanupNeedsCompleteFrame = false;
+            }
+        }
         this.#scheduleCleanupRecovery();
     }
     moveBy(lines) { this.inner.moveBy(lines); }
@@ -175,7 +194,7 @@ export class DamageAwareTerminalAdapter {
             return { ...base, reason: "grammar-mismatch" };
         if (parsed.structuralPrefix.length > 0
             || hasUnsafeTerminalContent(parsed, this.options.inspectHyperlinks, descriptor.transcript)
-            || this.#hasLinkRisk(descriptor.transcript) || this.#hasUnsafeRows(descriptor.transcript)) {
+            || this.#hasExplicitLinkRisk(descriptor.transcript) || this.#hasUnsafeRows(descriptor.transcript)) {
             return { ...base, reason: "unsafe-terminal-content" };
         }
         const { rowStart, rowEnd } = descriptor.transcript;
@@ -204,10 +223,11 @@ export class DamageAwareTerminalAdapter {
             if (descriptor.dock !== null && row.row >= descriptor.dock.rowStart && row.row <= descriptor.dock.rowEnd)
                 painted.add(row.row);
         }
-        // Rationale: ordinary followed prose may change one active tail source row, expose
-        // the shifted suffix, and restyle one sticky boundary row. Larger changes indicate
-        // Markdown/theme/overlay reflow and fail closed.
-        if (painted.size > descriptor.verticalShiftRows + 2 + countDockRows(parsed.rows, descriptor.dock)) {
+        // Rationale: a followed frame may repaint the live tail it declares, expose the shifted
+        // suffix, and restyle one sticky boundary row. A frame that declares no tail keeps the
+        // historical one-row allowance. Anything beyond that reaches settled rows and fails closed.
+        const liveTailRows = Math.max(1, descriptor.liveTailRows ?? 1);
+        if (painted.size > descriptor.verticalShiftRows + liveTailRows + 1 + countDockRows(parsed.rows, descriptor.dock)) {
             return { ...base, reason: "excessive-real-damage" };
         }
         return {
@@ -248,11 +268,9 @@ export class DamageAwareTerminalAdapter {
             return next?.replaySafe === true && (previous?.signature ?? "") === next.signature;
         });
     }
-    #hasLinkRisk(region) {
+    #hasExplicitLinkRisk(region) {
         for (const [row, state] of this.#links) {
-            if (region !== undefined && (row < region.rowStart || row > region.rowEnd))
-                continue;
-            if (state.ranges.length > 0)
+            if (row >= region.rowStart && row <= region.rowEnd && state.hasExplicitLink)
                 return true;
         }
         return false;
@@ -264,14 +282,33 @@ export class DamageAwareTerminalAdapter {
         }
         return false;
     }
-    #completeCleanupFrame(parsed) {
-        const desired = parsed.structuralPrefix.length === 0 ? new Map(this.#rows) : new Map();
-        for (const row of parsed.rows)
-            desired.set(row.row, row.content);
-        if (desired.size !== this.rows)
+    #boundedCleanupFrame(parsed) {
+        const sameGeometry = this.#cacheWidth === this.columns && this.#cacheHeight === this.rows;
+        const complete = hasCompleteScreenRows(parsed.rows, this.rows);
+        if (this.#cleanupNeedsCompleteFrame && !complete)
             return null;
+        const suppressReset = sameGeometry && !this.#cleanupNeedsCompleteFrame
+            && parsed.structuralPrefix === "\u001b[2J" && complete;
+        const structuralPrefix = suppressReset ? "" : parsed.structuralPrefix;
+        const desired = structuralPrefix.length === 0 ? new Map(this.#rows) : new Map();
+        const dirty = new Set([...this.#cleanupRows].filter(row => row <= this.rows));
+        for (const row of parsed.rows) {
+            if (row.row > this.rows)
+                return null;
+            desired.set(row.row, row.content);
+            if (structuralPrefix.length > 0 || this.#cleanupNeedsCompleteFrame
+                || this.#rows.get(row.row) !== row.content)
+                dirty.add(row.row);
+        }
+        // Invariant: validate all incoming rows before dropping an apparent redundant reset. Unknown
+        // content must pass through unchanged, never become a partially transformed frame.
+        for (const row of parsed.rows) {
+            const state = row.content === this.#rows.get(row.row) ? this.#links.get(row.row) : this.options.inspectHyperlinks(row.content);
+            if (state?.replaySafe !== true || state.width > this.columns)
+                return null;
+        }
         const rows = [];
-        for (let row = 1; row <= this.rows; row += 1) {
+        for (const row of [...dirty].sort((left, right) => left - right)) {
             const content = desired.get(row);
             if (content === undefined)
                 return null;
@@ -280,7 +317,8 @@ export class DamageAwareTerminalAdapter {
                 return null;
             rows.push({ row, content, segment: `\u001b[${row};1H\u001b[2K${content}` });
         }
-        return { structuralPrefix: "\u001b[2J", rows, cursorSuffix: parsed.cursorSuffix };
+        // Invariant: only preserve a structural clear supplied by Pi; cleanup never manufactures one.
+        return { structuralPrefix, rows, cursorSuffix: parsed.cursorSuffix };
     }
     #scheduleCleanupRecovery() {
         if (!this.hyperlinkCleanupPending || this.#recoveryRevision === this.#cleanupRevision
@@ -296,8 +334,13 @@ export class DamageAwareTerminalAdapter {
         });
     }
     #invalidatePresentation() {
-        if (this.#hasLinkRisk() && !this.hyperlinkCleanupPending)
+        if ([...this.#links.values()].some(state => state.ranges.length > 0) && !this.hyperlinkCleanupPending) {
             this.requestHyperlinkCleanup();
+        }
+        // Invariant: after unknown paint or geometry loss, exact former row locations are no longer
+        // authoritative. Wait for a complete safe frame instead of guessing a partial repair.
+        if (this.hyperlinkCleanupPending)
+            this.#cleanupNeedsCompleteFrame = true;
         this.#invalidateRows();
     }
     #invalidateRows() {
@@ -345,7 +388,7 @@ function hasUnsafeTerminalContent(parsed, inspect, linkRegion) {
         if (linkRegion !== undefined && (row.row < linkRegion.rowStart || row.row > linkRegion.rowEnd))
             return false;
         const state = inspect(row.content);
-        return !state.replaySafe || state.ranges.length > 0;
+        return !state.replaySafe || state.hasExplicitLink;
     });
 }
 function buildDamageWrite(parsed, descriptor, paintedRows, previousRows) {
@@ -363,12 +406,13 @@ function buildDamageWrite(parsed, descriptor, paintedRows, previousRows) {
     }).join("");
     return `${BEGIN_SYNCHRONIZED_OUTPUT}${regionShift}${rowPaint}${parsed.cursorSuffix}`;
 }
-/** Keeps the clear and all current rows in the same synchronized transaction. */
+/** Keeps required cleanup rows and current content in one synchronized transaction. */
 function buildCompleteWrite(parsed) {
     return `${BEGIN_SYNCHRONIZED_OUTPUT}${parsed.structuralPrefix}${parsed.rows.map(row => row.segment).join("")}${parsed.cursorSuffix}`;
 }
-function buildClearlessWrite(parsed) {
-    return `${BEGIN_SYNCHRONIZED_OUTPUT}${parsed.rows.map(row => row.segment).join("")}${parsed.cursorSuffix}`;
+function buildClearlessWrite(parsed, previousRows) {
+    const changed = parsed.rows.filter(row => previousRows.get(row.row) !== row.content);
+    return `${BEGIN_SYNCHRONIZED_OUTPUT}${changed.map(row => row.segment).join("")}${parsed.cursorSuffix}`;
 }
 function hasCompleteScreenRows(rows, height) {
     return rows.length === height && rows.every((row, index) => row.row === index + 1);

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

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-09-11T15:30:41.585Z",
+  "builtAt": "2026-09-12T13:59:03.140Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "9db1726bbe3fc2e8292f2ead1e7e9d0fd4d7d0dc9217b372582bf354b0f565dc",

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

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-11T15:30:45.869Z",
+  "builtAt": "2026-09-12T13:58:54.058Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "d8cda6b0c7cb36c0cc41e90802aceebf6c02eaebbc08a83d7d963d2e918dbd7a",

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

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-11T15:31:16.823Z",
+  "builtAt": "2026-09-12T13:59:34.009Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "78359342ae74e12b31ce05aff4a6b06f25d6e9777b081822c860604d674ec08d",
+    "sha256": "15e00144629345d7f00b110494775b80c65e6e575e6758d88b533c25b57d35d5",
     "size": 177664
   },
   "provenance": {

package/dist/product-identity.d.ts

@@ -1,4 +1,4 @@
-declare const ENVIRONMENT_KEYS: readonly ["certificationTarball", "configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "fixture", "fixtureInput", "fixtureToken", "inputAcknowledgement", "immutableWarmup", "internalPackaging", "launchProfile", "nativePi", "paneId", "piParityIntentionalMutation", "piPortRoot", "piSourceLedgerPath", "piSourceScanRoot", "probeTrace", "processGuardianPath", "profileHome", "protocolVersion", "releaseDigest", "releaseId", "releaseLayers", "releaseRoot", "releaseRunnerLabel", "runtimeDir", "structuredFlowLimits", "startupTrace", "terminalArgumentsJson", "terminalExecutable", "terminalSessionId"];
+declare const ENVIRONMENT_KEYS: readonly ["configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "paneId", "probeTrace", "processGuardianPath", "profileHome", "runtimeDir", "startupTrace", "terminalSessionId"];
 declare const FILESYSTEM_KEYS: readonly ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
 declare const STATE_KEYS: readonly ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile"];
 declare const ENDPOINT_KEYS: readonly ["windowsPipeStem", "unixSocketFilename", "metadataFilename", "supervisorLogFilename", "databaseFilename"];