@timurproko/a1 0.1.8-dev.226 → 0.1.8-dev.259

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

@@ -1,5 +1,5 @@
 import { PRODUCT_TEXT } from "../../../product-identity.js";
-import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput } from "../../../ui/components/index.js";
+import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput, readVisibleHyperlinks } from "../../../ui/components/index.js";
 import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "../engine/index.js";
 import { createPiExtensionUiBridge, createPiQueuedInputStatus, createPiShellArmin, createPiShellAuthProviderSelector, createPiShellChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, onPiThemeChange, piTheme, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../components/index.js";
 import { DamageAwareTerminalAdapter, PiTuiRuntimeAdapter, classifyPiTuiInput, } from "../tui-runtime/index.js";
@@ -63,6 +63,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(),
             onViewportFrame: frame => damageTerminal?.arm(frame.descriptor, {
                 overlayActive: runtime?.hasOverlay() ?? false,
                 selectionActive: this.root.hasActiveSelection(),
@@ -129,7 +130,9 @@ export class OwnedUiSessionShell {
                 decorateTerminal: (terminal) => {
                     damageTerminal = new DamageAwareTerminalAdapter(terminal, {
                         regionalScroll: process.env.TERM !== "dumb",
+                        inspectHyperlinks: readVisibleHyperlinks,
                         onResize: () => streamPresentation?.noteImmediatePresentation(),
+                        onHyperlinkCleanupRequired: () => runtime?.requestRender(true),
                     });
                     return damageTerminal;
                 },
@@ -294,6 +297,10 @@ export class OwnedUiSessionShell {
             startLogin: request => this.#startWorkflowLogin(request),
             prompt: request => this.#requestWorkflowInput(request),
             notify: event => this.#notifyWorkflowLogin(event),
+            publish: message => {
+                this.root.appendWorkflowMessage(message);
+                this.runtime.requestRender();
+            },
             finishLogin: () => this.#finishWorkflowLogin(),
         });
         this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
@@ -541,7 +548,7 @@ export class OwnedUiSessionShell {
         this.#dialogHandle = handle;
         return handle;
     }
-    showModelSelector() {
+    showModelSelector(initialSearchInput) {
         const context = this.backend.pinnedModelSelectorContext();
         const close = () => {
             this.root.setInputSurface(null);
@@ -554,6 +561,7 @@ export class OwnedUiSessionShell {
                 getRows: () => this.runtime.viewport().rows,
                 requestRender: () => this.runtime.requestRender(),
             },
+            ...(initialSearchInput === undefined ? {} : { initialSearchInput }),
             onSelect: model => {
                 close();
                 void this.runWorkflow({ command: "model", argument: "", selection: modelReference(model) });
@@ -566,7 +574,7 @@ export class OwnedUiSessionShell {
     showForkSelector() {
         const options = this.backend.pinnedForkOptions();
         if (options.length === 0) {
-            this.root.appendWorkflowResult({ command: "fork", outcome: "failed", message: "No user messages available to fork from" });
+            this.root.appendWorkflowResult({ command: "fork", outcome: "completed", message: "No messages to fork from", messageKind: "status" });
             this.runtime.requestRender();
             return;
         }
@@ -582,9 +590,21 @@ export class OwnedUiSessionShell {
         this.runtime.requestRender();
     }
     async showLogoutSelector() {
-        const options = await this.backend.pinnedLogoutOptions();
+        let options;
+        try {
+            options = await this.backend.pinnedLogoutOptions();
+        }
+        catch (error) {
+            this.root.appendWorkflowResult({
+                command: "logout",
+                outcome: "failed",
+                message: `Could not read stored credentials: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            this.runtime.requestRender();
+            return;
+        }
         if (options.length === 0) {
-            this.root.appendWorkflowStatus("No authenticated providers available.");
+            this.root.appendWorkflowStatus("No stored credentials to remove. /logout only removes credentials saved by /login; environment variables and models.json config are unchanged.");
             this.runtime.requestRender();
             return;
         }
@@ -805,10 +825,6 @@ export class OwnedUiSessionShell {
             await this.showLogoutSelector();
             return { outcome: "completed", diagnostic: null };
         }
-        if (request.command === "import" && request.confirmed === undefined && request.argument.trim().length > 0) {
-            const confirmed = await this.#extensionBridge.context.confirm("Import session", `Replace current session with ${request.argument.trim()}?`);
-            return this.runWorkflow({ ...request, confirmed: confirmed === true });
-        }
         if (request.command === "tree" && request.selection === undefined && request.confirmed === undefined && request.argument.trim().length === 0) {
             this.showTreeSelector();
             return { outcome: "completed", diagnostic: null };
@@ -817,22 +833,21 @@ export class OwnedUiSessionShell {
             this.root.resetExtensionUi();
             this.root.resetWorkflowPresentation();
         }
-        const operationSurface = request.command === "share"
+        const shareSurface = request.command === "share"
             ? createPiShellOperationLoader({
                 getColumns: () => this.runtime.viewport().columns,
                 getRows: () => this.runtime.viewport().rows,
                 requestRender: () => this.runtime.requestRender(),
             }, "Creating gist...")
-            : request.command === "reload"
-                ? createPiShellReloadBox()
-                : undefined;
+            : undefined;
+        const operationSurface = shareSurface ?? (request.command === "reload" ? createPiShellReloadBox() : undefined);
         if (operationSurface) {
             this.root.setInputSurface(operationSurface);
             this.runtime.requestRender();
         }
         let result;
         try {
-            result = await this.backend.executeWorkflow(request);
+            result = await this.backend.executeWorkflow(shareSurface === undefined ? request : { ...request, signal: shareSurface.signal });
         }
         finally {
             if (operationSurface) {
@@ -840,10 +855,27 @@ export class OwnedUiSessionShell {
                 this.runtime.requestRender();
             }
         }
+        if (result.outcome === "requires-selection" && request.command === "model") {
+            if (result.messages !== undefined) {
+                for (const message of result.messages)
+                    this.root.appendWorkflowMessage(message);
+            }
+            this.showModelSelector((result.detail ?? request.argument.trim()) || undefined);
+            return { outcome: "completed", diagnostic: null };
+        }
         if (result.outcome === "requires-confirmation" && request.command === "resume") {
             const confirmed = await this.#extensionBridge.context.confirm("Session cwd not found", result.message);
             return this.runWorkflow({ ...request, confirmed: confirmed === true });
         }
+        if (result.outcome === "requires-confirmation" && request.command === "import") {
+            const recoveringCwd = result.detail !== undefined;
+            const confirmed = await this.#extensionBridge.context.confirm(recoveringCwd ? "Session cwd not found" : "Import session", result.message);
+            return this.runWorkflow({
+                ...request,
+                confirmed: confirmed === true,
+                ...(confirmed === true && result.detail ? { cwdOverride: result.detail } : {}),
+            });
+        }
         if (result.outcome === "requires-selection" || result.outcome === "requires-confirmation") {
             this.root.appendWorkflowResult({ command: request.command, outcome: "failed", message: `Owned controller missing for ${request.command}` });
             this.runtime.requestRender();

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

@@ -5,6 +5,7 @@ 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 hasEditorLinks?: () => boolean;
 }
@@ -32,7 +33,7 @@ export declare class SessionViewportController {
         readonly rowStart: number;
         readonly rowEnd: number;
     } | undefined): void;
-    compose(input: TranscriptViewportFrameInput): TranscriptViewportFrame;
+    compose(input: Omit<TranscriptViewportFrameInput, "pointerPosition">): TranscriptViewportFrame;
     composeDockOnly(dockRows: readonly string[], width: number, height: number): TranscriptViewportFrame | null;
     /** Returns true when document wrapping may have changed. */
     setConfig(config: OwnedUiViewportSettings): boolean;

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

@@ -1,4 +1,4 @@
-import { TranscriptViewport, hyperlinkTargetAtColumn, routeMouseInput, scrollForTrackPage, scrollForThumbRow, scrollbarSelectionRows, scrollbarWheelRows, } from "../../../ui/components/index.js";
+import { TranscriptViewport, readVisibleHyperlinks, routeMouseInput, scrollForTrackPage, scrollForThumbRow, scrollbarSelectionRows, scrollbarWheelRows, } from "../../../ui/components/index.js";
 /**
  * Owns the stateful interaction policy of the bare-A1 session viewport. The
  * shell root supplies semantic rows and dock geometry; this controller owns
@@ -9,6 +9,7 @@ export class SessionViewportController {
     #editor;
     #requestRender;
     #hasEditorLinks;
+    #requestHyperlinkCleanup;
     #viewport = new TranscriptViewport();
     #config = {
         scrollbarAppearance: "auto",
@@ -18,6 +19,8 @@ export class SessionViewportController {
     #dragGrabOffset = null;
     // Invariant: a left-button sequence begun in dock chrome remains owned by the dock.
     #dockPointerSuppressed = false;
+    // Invariant: a left-button sequence begun in non-selectable transcript tail chrome is held there.
+    #tailPointerSuppressed = false;
     // Invariant: editor selection remains true only while its left button is held.
     #editorPointerSelecting = false;
     // Invariant: pointer routing uses the most recently composed editor rows.
@@ -37,6 +40,7 @@ export class SessionViewportController {
             options.requestRender(force);
         };
         this.#hasEditorLinks = options.hasEditorLinks ?? (() => false);
+        this.#requestHyperlinkCleanup = options.requestHyperlinkCleanup ?? (() => { });
     }
     get config() {
         return this.#config;
@@ -65,7 +69,10 @@ export class SessionViewportController {
     compose(input) {
         this.#viewport.setConfig(this.#config);
         const selectionRevision = this.#viewport.selectionRevision;
-        const frame = this.#viewport.compose(input);
+        const frame = this.#viewport.compose({
+            ...input,
+            ...(this.#pointerPosition === undefined ? {} : { pointerPosition: this.#pointerPosition }),
+        });
         // Concurrency: if selection changed during composition, this frame truthfully carries
         // the older revision and exactly one ordinary follow-up render publishes the latest.
         if (this.#viewport.selectionRevision !== selectionRevision
@@ -78,6 +85,7 @@ 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.#hoveredHyperlinkKey = next;
@@ -126,6 +134,7 @@ export class SessionViewportController {
         this.#clearActivityTimer();
         this.#dragGrabOffset = null;
         this.#dockPointerSuppressed = false;
+        this.#tailPointerSuppressed = false;
         this.#editorPointerSelecting = false;
         this.#editorPointerFrame = undefined;
         this.#pointerPosition = undefined;
@@ -146,8 +155,10 @@ export class SessionViewportController {
             return { data: "", consumed: true };
         }
         // Platform: URL chip deletion must overwrite terminal link cells in the same frame.
-        if (EDITOR_LINK_DELETION_INPUTS.has(data) && this.#hasEditorLinks())
+        if (EDITOR_LINK_DELETION_INPUTS.has(data) && this.#hasEditorLinks()) {
+            this.#requestHyperlinkCleanup();
             this.#requestRender(true);
+        }
         if (this.#viewport.frame === null)
             return { data, consumed: false };
         if (data === "\u0003") {
@@ -205,20 +216,27 @@ export class SessionViewportController {
             const overSticky = hits.sticky !== null && event.row === hits.sticky.row && event.column <= hits.sticky.width;
             const overBottom = hits.bottom !== null && event.row === hits.bottom.row
                 && event.column >= hits.bottom.columnStart && event.column <= hits.bottom.columnEnd;
-            if (event.kind === "motion") {
-                this.#pointerPosition = { column: event.column, row: event.row };
-                if (!this.#viewport.selectionActive && !this.#editorPointerSelecting) {
-                    const nextHyperlink = this.#hyperlinkKeyAt(frame, event.column, event.row);
-                    if (this.#hoveredHyperlinkKey !== undefined && nextHyperlink !== this.#hoveredHyperlinkKey) {
-                        // Platform: a forced redraw overwrites Windows Terminal's cached solid hover
-                        // underline exactly once when the pointer leaves or changes links.
-                        forceRepaint = true;
-                    }
-                    this.#hoveredHyperlinkKey = nextHyperlink;
+            const previousPointer = this.#pointerPosition;
+            const wasOverBottom = hits.bottom !== null && previousPointer !== undefined
+                && previousPointer.row === hits.bottom.row
+                && previousPointer.column >= hits.bottom.columnStart && previousPointer.column <= hits.bottom.columnEnd;
+            // Invariant: every report locates the pointer, independently of which surface owns the action.
+            // Keep this location while the control is hidden; composition resolves its next hit region.
+            this.#pointerPosition = { column: event.column, row: event.row };
+            repaint ||= wasOverBottom !== overBottom;
+            if (!this.#viewport.selectionActive && !this.#editorPointerSelecting) {
+                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;
+                    repaint = true;
                 }
+                this.#hoveredHyperlinkKey = nextHyperlink;
+            }
+            if (event.kind === "motion") {
                 this.#viewport.setRailHovered(overRail);
                 this.#viewport.setStickyHovered(overSticky);
-                this.#viewport.setBottomHovered(overBottom);
                 repaint = true;
                 if (this.#editor.ownsPointer() && this.#editorPointerFrame !== undefined) {
                     this.#editor.handlePointer({
@@ -229,7 +247,7 @@ export class SessionViewportController {
                     });
                     return true;
                 }
-                if (this.#dockPointerSuppressed)
+                if (this.#dockPointerSuppressed || this.#tailPointerSuppressed)
                     return true;
                 if (this.#viewport.selectionActive) {
                     this.#viewport.extendSelection(event.column, event.row, now, false);
@@ -316,7 +334,13 @@ export class SessionViewportController {
                     return true;
                 }
                 if (event.row >= 1 && event.row <= hits.viewportHeight && event.column <= frame.contentWidth) {
-                    this.#viewport.pressSelection(event.column, event.row, now);
+                    if (!this.#viewport.pressSelection(event.column, event.row, now)) {
+                        // Invariant: a full drag begun on transient tail rows cannot become transcript selection.
+                        if (hits.transientTail.includes(event.row))
+                            this.#tailPointerSuppressed = true;
+                        repaint = true;
+                        return this.#tailPointerSuppressed;
+                    }
                     repaint = true;
                     return true;
                 }
@@ -354,6 +378,10 @@ export class SessionViewportController {
                     this.#dockPointerSuppressed = false;
                     return true;
                 }
+                if (this.#tailPointerSuppressed) {
+                    this.#tailPointerSuppressed = false;
+                    return true;
+                }
             }
             return false;
         });
@@ -368,8 +396,9 @@ export class SessionViewportController {
     #hyperlinkKeyAt(frame, column, row) {
         if (row < 1 || row > frame.rows.length || column < 1)
             return undefined;
-        const target = hyperlinkTargetAtColumn(frame.rows[row - 1] ?? "", column - 1);
-        return target === undefined ? undefined : `${row}\u0000${target}`;
+        const range = readVisibleHyperlinks(frame.rows[row - 1] ?? "").ranges
+            .find(candidate => column - 1 >= candidate.from && column - 1 < candidate.to);
+        return range === undefined ? undefined : JSON.stringify([row, range]);
     }
     #updateSelectionAutoScroll(column, row, viewportHeight) {
         const beyondEdge = row <= 1 || row > viewportHeight;

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

@@ -21,7 +21,7 @@ export interface PiTuiDamageFrameSafety {
     readonly selectionActive: boolean;
     readonly replacementSurfaceActive: boolean;
 }
-export type PiTuiDamageDecisionReason = "transformed" | "suppressed-redundant-clear" | "not-armed" | "unsafe-frame" | "stale-frame" | "unsupported-region-scroll" | "geometry-mismatch" | "grammar-mismatch" | "unsafe-terminal-content" | "incomplete-prior-frame" | "excessive-real-damage";
+export type PiTuiDamageDecisionReason = "transformed" | "suppressed-redundant-clear" | "hyperlink-cleanup" | "pending-hyperlink-cleanup" | "not-armed" | "unsafe-frame" | "stale-frame" | "unsupported-region-scroll" | "geometry-mismatch" | "grammar-mismatch" | "unsafe-terminal-content" | "incomplete-prior-frame" | "excessive-real-damage";
 export interface PiTuiDamageDecision {
     readonly frameId: number | null;
     readonly transformed: boolean;
@@ -31,7 +31,15 @@ export interface PiTuiDamageDecision {
 }
 export interface DamageAwareTerminalOptions {
     readonly regionalScroll: boolean;
+    /** The shell supplies visible-row analysis; the terminal layer owns no UI parser. */
+    readonly inspectHyperlinks: (content: string) => {
+        readonly ranges: readonly unknown[];
+        readonly signature: string;
+        readonly replaySafe: boolean;
+        readonly width: number;
+    };
     readonly onResize?: () => void;
+    readonly onHyperlinkCleanupRequired?: () => void;
 }
 /**
  * A fail-closed adapter for one pinned Pi fullscreen write grammar. Semantic
@@ -47,6 +55,9 @@ export declare class DamageAwareTerminalAdapter implements PiTuiTerminalPort {
     get rows(): number;
     get kittyProtocolActive(): boolean;
     get lastDecision(): PiTuiDamageDecision;
+    get hyperlinkCleanupPending(): boolean;
+    /** Latches cleanup through composition/coalescing until a complete write covers it. */
+    requestHyperlinkCleanup(): 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

@@ -2,8 +2,8 @@ export const PINNED_PI_TUI_DAMAGE_GRAMMAR = "@earendil-works/pi-tui@0.84.2:tui-a
 const BEGIN_SYNCHRONIZED_OUTPUT = "\u001b[?2026h";
 const END_SYNCHRONIZED_OUTPUT = "\u001b[?2026l";
 const ROW_MARKER = /\u001b\[(\d+);1H\u001b\[2K/gu;
-const CURSOR_SUFFIX = /\u001b\[(\d+);(\d+)H\u001b\[\?25[hl]\u001b\[\?2026l$/u;
-const OSC8 = /\u001b\]8;[^;\u0007\u001b]*;([^\u0007\u001b]*)(?:\u0007|\u001b\\)/gu;
+const CURSOR_SUFFIX = /(?:\u001b\[(\d+);(\d+)H)?\u001b\[\?25[hl]\u001b\[\?2026l$/u;
+const OUT_OF_BAND = /^(?:\u001b\](?:0|2|9|52);[^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[\?25[hl])+$/u;
 /**
  * A fail-closed adapter for one pinned Pi fullscreen write grammar. Semantic
  * viewport metadata authorizes a shift; bytes are inspected only to validate
@@ -13,6 +13,11 @@ export class DamageAwareTerminalAdapter {
     inner;
     options;
     #rows = new Map();
+    #links = new Map();
+    #cleanupRevision = 0;
+    #cleanedRevision = 0;
+    #recoveryRevision = 0;
+    #epoch = 0;
     #armed;
     #lastConsumedFrameId = 0;
     #cacheWidth = 0;
@@ -32,18 +37,26 @@ export class DamageAwareTerminalAdapter {
     get rows() { return this.inner.rows; }
     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; }
     arm(descriptor, safety) {
         this.#armed = { descriptor, safety };
     }
     start(onInput, onResize) {
         this.inner.start(onInput, () => {
-            this.#invalidateRows();
+            this.#epoch += 1;
+            this.#recoveryRevision = 0;
+            this.#invalidatePresentation();
             this.options.onResize?.();
             onResize();
         });
     }
     stop() {
+        this.#epoch += 1;
         this.#armed = undefined;
+        this.#cleanupRevision = this.#cleanedRevision = this.#recoveryRevision = 0;
+        this.#lastConsumedFrameId = 0;
         this.#invalidateRows();
         this.inner.stop();
     }
@@ -52,25 +65,71 @@ export class DamageAwareTerminalAdapter {
         const armed = this.#armed;
         this.#armed = undefined;
         const parsed = parsePinnedFullscreenWrite(data);
-        const decision = this.#decide(armed, parsed);
-        this.#decision = decision;
-        if (decision.reason === "suppressed-redundant-clear" && parsed !== null) {
-            this.inner.write(buildClearlessWrite(parsed));
+        if (armed !== undefined && armed.descriptor.frameId <= this.#lastConsumedFrameId) {
+            // Concurrency: a recognized obsolete frame must never repaint newer cells,
+            // acknowledge cleanup, or become the reference for a subsequent differential.
+            this.#decision = this.#decide(armed, parsed);
+            return;
+        }
+        const sameGeometry = this.#cacheWidth === this.columns && this.#cacheHeight === this.rows;
+        const unknownPaint = parsed === null && !OUT_OF_BAND.test(data);
+        if (!sameGeometry || unknownPaint)
+            this.#invalidatePresentation();
+        if (unknownPaint && !this.hyperlinkCleanupPending && this.options.inspectHyperlinks(data).ranges.length > 0) {
+            this.requestHyperlinkCleanup();
         }
-        else if (decision.transformed && armed !== undefined && parsed !== null) {
-            this.inner.write(buildDamageWrite(parsed, armed.descriptor, new Set(decision.paintedRows), this.#rows));
+        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;
+                }
+            }
+        }
+        const decision = this.#decide(armed, parsed);
+        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;
+        const epoch = this.#epoch;
+        let output = data;
+        if (cleanup !== null) {
+            output = buildCompleteWrite(cleanup);
+            this.#decision = {
+                frameId: armed?.descriptor.frameId ?? null, transformed: output !== data,
+                reason: "hyperlink-cleanup", shiftRows: 0, paintedRows: cleanup.rows.map(row => row.row),
+            };
         }
         else {
-            this.inner.write(data);
+            this.#decision = decision;
+            if (decision.reason === "suppressed-redundant-clear" && parsed !== null)
+                output = buildClearlessWrite(parsed);
+            else if (decision.transformed && armed !== undefined && parsed !== null) {
+                output = buildDamageWrite(parsed, armed.descriptor, new Set(decision.paintedRows), this.#rows);
+            }
         }
-        this.#rememberFrame(armed?.descriptor, parsed, data);
+        this.inner.write(output);
+        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.
+        this.#rememberFrame(armed?.descriptor, cleanup ?? parsed, output);
+        if (cleanup !== null)
+            this.#cleanedRevision = Math.max(this.#cleanedRevision, coveredRevision);
+        this.#scheduleCleanupRecovery();
     }
     moveBy(lines) { this.inner.moveBy(lines); }
     hideCursor() { this.inner.hideCursor(); }
     showCursor() { this.inner.showCursor(); }
-    clearLine() { this.#invalidateRows(); this.inner.clearLine(); }
-    clearFromCursor() { this.#invalidateRows(); this.inner.clearFromCursor(); }
-    clearScreen() { this.#invalidateRows(); this.inner.clearScreen(); }
+    clearLine() { this.#invalidatePresentation(); this.inner.clearLine(); }
+    clearFromCursor() { this.#invalidatePresentation(); this.inner.clearFromCursor(); }
+    clearScreen() { this.#invalidatePresentation(); this.inner.clearScreen(); }
     setTitle(title) { this.inner.setTitle(title); }
     setProgress(active) { this.inner.setProgress(active); }
     #decide(armed, parsed) {
@@ -87,9 +146,12 @@ export class DamageAwareTerminalAdapter {
         if (descriptor.frameId <= this.#lastConsumedFrameId)
             return { ...base, reason: "stale-frame" };
         this.#lastConsumedFrameId = descriptor.frameId;
+        if (this.hyperlinkCleanupPending)
+            return { ...base, reason: "pending-hyperlink-cleanup" };
         if (parsed !== null && parsed.structuralPrefix === "\u001b[2J"
             && this.#cacheWidth === descriptor.width && this.#cacheHeight === descriptor.height
-            && hasCompleteScreenRows(parsed.rows, descriptor.height) && !hasUnsafeTerminalContent(parsed)) {
+            && descriptor.width === this.columns && descriptor.height === this.rows
+            && hasCompleteScreenRows(parsed.rows, descriptor.height) && this.#hasSameHyperlinkState(parsed.rows)) {
             return {
                 frameId: descriptor.frameId,
                 transformed: true,
@@ -111,7 +173,9 @@ export class DamageAwareTerminalAdapter {
         }
         if (parsed === null)
             return { ...base, reason: "grammar-mismatch" };
-        if (parsed.structuralPrefix.length > 0 || hasUnsafeTerminalContent(parsed)) {
+        if (parsed.structuralPrefix.length > 0
+            || hasUnsafeTerminalContent(parsed, this.options.inspectHyperlinks, descriptor.transcript)
+            || this.#hasLinkRisk(descriptor.transcript) || this.#hasUnsafeRows(descriptor.transcript)) {
             return { ...base, reason: "unsafe-terminal-content" };
         }
         const { rowStart, rowEnd } = descriptor.transcript;
@@ -160,16 +224,85 @@ export class DamageAwareTerminalAdapter {
         }
         if (parsed === null)
             return;
-        if (descriptor !== undefined && (descriptor.width !== this.#cacheWidth || descriptor.height !== this.#cacheHeight)) {
+        const width = descriptor?.width ?? this.columns;
+        const height = descriptor?.height ?? this.rows;
+        if (width !== this.#cacheWidth || height !== this.#cacheHeight) {
             this.#invalidateRows();
-            this.#cacheWidth = descriptor.width;
-            this.#cacheHeight = descriptor.height;
+            this.#cacheWidth = width;
+            this.#cacheHeight = height;
         }
-        for (const row of parsed.rows)
+        if (parsed.rows.some(row => row.row > this.rows)) {
+            this.#invalidatePresentation();
+            return;
+        }
+        for (const row of parsed.rows) {
+            if (this.#rows.get(row.row) !== row.content)
+                this.#links.set(row.row, this.options.inspectHyperlinks(row.content));
             this.#rows.set(row.row, row.content);
+        }
+    }
+    #hasSameHyperlinkState(rows) {
+        return rows.every(row => {
+            const previous = this.#links.get(row.row);
+            const next = row.content === this.#rows.get(row.row) ? previous : this.options.inspectHyperlinks(row.content);
+            return next?.replaySafe === true && (previous?.signature ?? "") === next.signature;
+        });
+    }
+    #hasLinkRisk(region) {
+        for (const [row, state] of this.#links) {
+            if (region !== undefined && (row < region.rowStart || row > region.rowEnd))
+                continue;
+            if (state.ranges.length > 0)
+                return true;
+        }
+        return false;
+    }
+    #hasUnsafeRows(region) {
+        for (const [row, state] of this.#links) {
+            if (row >= region.rowStart && row <= region.rowEnd && !state.replaySafe)
+                return true;
+        }
+        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)
+            return null;
+        const rows = [];
+        for (let row = 1; row <= this.rows; row += 1) {
+            const content = desired.get(row);
+            if (content === undefined)
+                return null;
+            const state = content === this.#rows.get(row) ? this.#links.get(row) : this.options.inspectHyperlinks(content);
+            if (state?.replaySafe !== true || state.width > this.columns)
+                return null;
+            rows.push({ row, content, segment: `\u001b[${row};1H\u001b[2K${content}` });
+        }
+        return { structuralPrefix: "\u001b[2J", rows, cursorSuffix: parsed.cursorSuffix };
+    }
+    #scheduleCleanupRecovery() {
+        if (!this.hyperlinkCleanupPending || this.#recoveryRevision === this.#cleanupRevision
+            || this.options.onHyperlinkCleanupRequired === undefined)
+            return;
+        this.#recoveryRevision = this.#cleanupRevision;
+        const epoch = this.#epoch;
+        // Concurrency: force only after Pi finishes updating its previous-screen
+        // state. One recovery per revision avoids loops on unsupported image frames.
+        queueMicrotask(() => {
+            if (epoch === this.#epoch && this.hyperlinkCleanupPending)
+                this.options.onHyperlinkCleanupRequired?.();
+        });
+    }
+    #invalidatePresentation() {
+        if (this.#hasLinkRisk() && !this.hyperlinkCleanupPending)
+            this.requestHyperlinkCleanup();
+        this.#invalidateRows();
     }
     #invalidateRows() {
         this.#rows.clear();
+        this.#links.clear();
         this.#cacheWidth = 0;
         this.#cacheHeight = 0;
     }
@@ -183,7 +316,8 @@ function parsePinnedFullscreenWrite(data) {
     const body = data.slice(BEGIN_SYNCHRONIZED_OUTPUT.length, suffix.index);
     const matches = [...body.matchAll(ROW_MARKER)];
     if (matches.length === 0)
-        return null;
+        return body.length === 0
+            ? { structuralPrefix: "", rows: [], cursorSuffix: data.slice(suffix.index) } : null;
     const structuralPrefix = body.slice(0, matches[0].index);
     if (structuralPrefix !== "" && structuralPrefix !== "\u001b[2J")
         return null;
@@ -203,14 +337,16 @@ function parsePinnedFullscreenWrite(data) {
     }
     return { structuralPrefix, rows, cursorSuffix: data.slice(suffix.index) };
 }
-function hasUnsafeTerminalContent(parsed) {
+function hasUnsafeTerminalContent(parsed, inspect, linkRegion) {
     const data = parsed.rows.map(row => row.content).join("");
     if (data.includes("\u001b_G") || data.includes("\u001bPq") || data.includes("\u001b[2J"))
         return true;
-    for (const match of data.matchAll(OSC8))
-        if ((match[1] ?? "").length > 0)
-            return true;
-    return false;
+    return parsed.rows.some(row => {
+        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;
+    });
 }
 function buildDamageWrite(parsed, descriptor, paintedRows, previousRows) {
     const transcript = descriptor.transcript;
@@ -227,6 +363,10 @@ 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. */
+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}`;
 }