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

package/dist/integrations/pi/session-ui/prompt-chips.js

@@ -5,13 +5,16 @@ import { fileURLToPath } from "node:url";
 import { canonicalizeClipboardImage } from "./clipboard-image.js";
 import { assertImageEncodedSize, assertPromptImages, ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
 import { ImagePreparationClient } from "./image-preparation-client.js";
-const CHIP_PATTERN = /\[(?:📷 [^\]]+|📁 [^\]]+|📄 [^\]]+|🖼 {1,2}[^\]]+|🔗 [^\]]+)\]/gu;
+import { prepareTextPaste } from "./text-paste.js";
+const CHIP_PATTERN = /\[(?:paste #\d+ (?:\+\d+ lines|\d+ chars)|📷 [^\]]+|📁 [^\]]+|📄 [^\]]+|🖼 {1,2}[^\]]+|🔗 [^\]]+)\]/gu;
 const IMAGE_EXTENSION = /\.(?:jpe?g|png|webp|gif|bmp|tiff?)$/iu;
 const URL_PATTERN = /^https?:\/\/[^\s\u0000-\u001f\u007f]+$/iu;
 const URL_DISPLAY_LENGTH = 40;
 /** Owns semantic chips and bounded pending paste references; cancels background work on reset or disposal. */
 export class PromptChipStore {
     #chips = new Map();
+    // Invariant: clearing the editor never recycles a recoverable text chip's identity.
+    #textCounter = 0;
     #pending = new Map();
     #preparation = new ImagePreparationClient();
     #stopping = new Set();
@@ -98,7 +101,11 @@ export class PromptChipStore {
                 entry.job.cancel();
         return remaining;
     }
-    async dispose() { await Promise.all([this.#preparation.dispose(), ...this.#stopping]); }
+    async dispose() {
+        await Promise.all([this.#preparation.dispose(), ...this.#stopping]);
+        this.#chips.clear();
+        this.#pending.clear();
+    }
     #imageCount(text) {
         const tags = new Set([...this.#chips.values()].filter(chip => chip.kind === "image" && text.includes(chip.tag)).map(chip => chip.tag));
         for (const entry of this.#pending.values()) {
@@ -141,8 +148,14 @@ export class PromptChipStore {
             return this.#recordUnique({ kind: "url", tag: `[🔗 ${label}]`, label, url });
         }
         const paths = pathsFromClipboard(text);
-        if (paths.length === 0)
-            return text;
+        if (paths.length === 0) {
+            const paste = prepareTextPaste(text);
+            if (paste.label === undefined)
+                return paste.text;
+            const tag = `[paste #${++this.#textCounter} ${paste.label}]`;
+            this.#chips.set(tag, Object.freeze({ kind: "text", tag, text: paste.text }));
+            return tag;
+        }
         return paths.map(item => {
             const label = pathLabel(item.fullPath);
             if (item.kind === "folder") {
@@ -167,7 +180,7 @@ export class PromptChipStore {
         return ranges.sort((left, right) => left.start - right.start);
     }
     atomicRanges(line) {
-        return [...line.matchAll(CHIP_PATTERN)].map(match => ({
+        return [...line.matchAll(CHIP_PATTERN)].filter(match => !match[0].startsWith("[paste #") || this.#chips.has(match[0])).map(match => ({
             start: match.index,
             end: match.index + match[0].length,
         }));
@@ -196,41 +209,41 @@ export class PromptChipStore {
         return this.#replaceResolvable(text, false).text;
     }
     prepareHistoryText(text) {
-        return this.#replaceResolvable(text, false).text.replace(CHIP_PATTERN, tag => this.#chips.get(tag)?.kind === "image" ? "" : tag).trim();
+        return this.#replaceResolvable(text, false, true).text.trim();
     }
     prepareSubmission(text) {
         const expanded = this.#replaceResolvable(text, true);
         return { text: expanded.text, images: expanded.images };
     }
-    #replaceResolvable(text, includeImages) {
-        let expanded = text;
-        for (const entry of this.#pending.values()) {
-            if (!expanded.includes(entry.marker) && !expanded.includes(entry.marker.replace("screenshot-", "failed-")))
-                continue;
-            if (includeImages && entry.error !== undefined)
-                throw entry.error;
-            if (includeImages && entry.replacement === undefined)
-                throw new ImageAttachmentError("image-pending");
-            if (entry.replacement !== undefined)
-                expanded = expanded.replaceAll(entry.marker, entry.replacement);
-        }
+    #replaceResolvable(text, includeImages, omitImages = false) {
         const images = [];
         const seenImages = new Set();
-        for (const match of expanded.matchAll(CHIP_PATTERN)) {
-            const tag = match[0];
+        const resolveChip = (tag) => {
             const chip = this.#chips.get(tag);
             if (chip === undefined)
-                continue;
+                return tag;
+            if (chip.kind === "text")
+                return chip.text;
             if (chip.kind === "image") {
                 if (includeImages && !seenImages.has(tag)) {
                     images.push(chip.image);
                     seenImages.add(tag);
                 }
-                continue;
+                return omitImages ? "" : tag;
             }
-            const value = chip.kind === "url" ? chip.url : chip.path;
-            expanded = expanded.replaceAll(tag, value);
-        }
+            return chip.kind === "url" ? chip.url : chip.path;
+        };
+        // Invariant: scan only draft tokens (and resolved reservation tokens), never emitted payloads.
+        const expanded = text.replace(CHIP_PATTERN, tag => {
+            const entry = this.#pending.get(tag) ?? this.#pending.get(tag.replace("failed-", "screenshot-"));
+            if (entry === undefined)
+                return resolveChip(tag);
+            if (includeImages && entry.error !== undefined)
+                throw entry.error;
+            if (includeImages && entry.replacement === undefined)
+                throw new ImageAttachmentError("image-pending");
+            return entry.replacement === undefined ? tag : entry.replacement.replace(CHIP_PATTERN, resolveChip);
+        });
         return { text: expanded, images };
     }
     #recordUnique(chip) {

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

@@ -10,7 +10,6 @@ export declare class PromptHistoryController {
         fallback: readonly string[];
         active(): boolean;
         render(): void;
-        failure(message: string): void;
     };
     constructor(options: {
         editor: PiShellEditorPort;
@@ -19,7 +18,6 @@ export declare class PromptHistoryController {
         fallback: readonly string[];
         active(): boolean;
         render(): void;
-        failure(message: string): void;
     });
     start(): void;
     capture(text: string, kind: PromptHistoryKind, cwd: string, sessionId: string): void;

package/dist/integrations/pi/session-ui/prompt-history-controller.js

@@ -20,11 +20,9 @@ export class PromptHistoryController {
         this.#snapshot = { revision: 0, limit: options.limit, entries: [] };
         this.#fallback = boundedTexts([...options.fallback].reverse(), options.limit);
         this.#unsubscribeSnapshot = this.#subscribeSnapshot();
-        this.#unsubscribeFailure = options.store.onFailure(code => {
+        this.#unsubscribeFailure = options.store.onFailure(() => {
             if (this.#disposed)
                 this.#closeFailed = true;
-            else
-                options.failure(`Prompt history ${code}; current-session recall remains available.`);
         });
         this.#unsubscribe = [
             options.editor.recall.observe(() => {
@@ -57,10 +55,7 @@ export class PromptHistoryController {
             if (this.#snapshot.entries.some(entry => entry.submissionId === id))
                 this.#local.delete(id);
             this.synchronize();
-        }).catch(() => {
-            if (!this.#disposed)
-                this.options.failure("Prompt history unavailable; current-session recall remains available.");
-        });
+        }).catch(() => { });
     }
     rememberRecovery(text) {
         if (this.#disposed || !text.trim())
@@ -111,7 +106,7 @@ export class PromptHistoryController {
                 return;
             this.#snapshot = snapshot;
             for (const [id, entry] of this.#local) {
-                if (entry.committed)
+                if (entry.committed || snapshot.entries.some(saved => saved.submissionId === id))
                     this.#local.delete(id);
             }
             this.synchronize();

package/dist/integrations/pi/session-ui/session-shell-root.d.ts

@@ -70,7 +70,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly getRows: () => number;
         readonly requestRender: (force?: boolean) => void;
         readonly onViewportFrame?: (frame: TranscriptViewportFrame) => void;
-        readonly requestHyperlinkCleanup?: () => void;
+        readonly requestHyperlinkCleanup?: (rows?: readonly number[]) => void;
         readonly enableDockInputReuse?: boolean;
         readonly persistentHistory?: boolean;
         readonly historyEditor?: import("../components/index.js").HistoryEditorConstructor;

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

@@ -138,7 +138,7 @@ export class OwnedUiSessionShellRoot {
             enabled: this.#customViewport,
             editor: this.editor,
             requestRender: force => this.#componentRuntime.requestRender(force),
-            requestHyperlinkCleanup: () => handlers.requestHyperlinkCleanup?.(),
+            requestHyperlinkCleanup: rows => handlers.requestHyperlinkCleanup?.(rows),
             hasEditorLinks: () => this.#promptChips.hyperlinkRanges(this.editor.getText()).length > 0,
         });
         // Performance: stable painter identities let the neutral viewport retain row-level
@@ -258,6 +258,10 @@ export class OwnedUiSessionShellRoot {
      * walk of the whole transcript.
      */
     applyTranscriptBlock(block) {
+        const current = this.#blocksById.get(block.id);
+        // Invariant: a full-view/final presentation may preempt queued partials. Never revive an older revision.
+        if (current !== undefined && (current.revision > block.revision || current.status === "finalized" && block.status === "live"))
+            return;
         this.#blocksById.set(block.id, block);
         const component = this.#transcript.get(block.id);
         if (component === undefined) {

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(),
@@ -334,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({
@@ -1262,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)
@@ -1302,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 {

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

@@ -89,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;
         }
@@ -161,7 +161,7 @@ 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.
@@ -242,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

@@ -63,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;
@@ -249,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.hasExplicitLink || state.ranges.length > 0)
+            if (row >= region.rowStart && row <= region.rowEnd && state.hasExplicitLink)
                 return true;
         }
         return false;
@@ -265,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;
@@ -281,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
@@ -297,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() {
@@ -346,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.hasExplicitLink || state.ranges.length > 0;
+        return !state.replaySafe || state.hasExplicitLink;
     });
 }
 function buildDamageWrite(parsed, descriptor, paintedRows, previousRows) {
@@ -364,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-12T11:45:08.507Z",
+  "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-12T11:45:14.951Z",
+  "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-12T11:45:38.237Z",
+  "builtAt": "2026-09-12T13:59:34.009Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "ae2bf5d92411273a936b89376077bc13db6f73d16707a2bace8a8f048523891e",
+    "sha256": "15e00144629345d7f00b110494775b80c65e6e575e6758d88b533c25b57d35d5",
     "size": 177664
   },
   "provenance": {

package/dist/product-identity.json

@@ -1,6 +1,6 @@
 {
     "schema": "a1-product-identity-v1",
-    "displayName": "A1",
+    "displayName": "a1",
     "commandName": "a1",
     "packageName": "@timurproko/a1",
     "filesystem": {

package/docs/architecture/internal-naming.md

@@ -71,11 +71,13 @@ The old environment registry included `fixture` and `inputAcknowledgement`, but
 
 `certificationTarball`, `internalPackaging`, `nativePi`, `piParityIntentionalMutation`, `protocolVersion`, `structuredFlowLimits`, `terminalArgumentsJson`, and `terminalExecutable` had no active runtime consumer in the reviewed tree. They are removed from the current environment authority, not renamed into new settings. Rejection patterns and immutable historical evidence remain factual.
 
-## Clean cutover and protected state
+## Negotiated handoff and protected state
 
-The first new-contract installation is intentionally not an old-to-new `a1 update` path. Stop existing A1 sessions, supervisors, and workers first. Install the **accepted published version** explicitly with `npm install --global @timurproko/a1@<accepted-version>`; the implementation/release handoff must replace the placeholder with the actual accepted version. Do not execute an old recovery launcher to bridge the cutover.
+An update is performed by the release that is already installed, so the contract is negotiated rather than cut over. `neutral-launch-v1` is the only contract this build **writes** for its own releases, and the superseded `A1_RELEASE_*`/`A1_IMMUTABLE_WARMUP` keys are still **read** when an older launcher starts this build, and still **written** when this build starts a retained release that declares no contract. An installation therefore stays launchable across the cutover in both directions, and no user is asked to stop processes and reinstall by hand.
 
-Old-contract targets are rejected with a cutover diagnostic. No reset or migration runs automatically. If disposable state blocks installation, inspect its resolved paths and obtain separate approval before removal. A supported rollback must also use `neutral-launch-v1`; no eligible target means an explicit unavailable rollback, not a fallback to older code.
+Metadata that predates contract declaration is stale, never fatal. A pre-cutover active record does not stop a launch: it is ignored, the installed payload is materialized, and ordinary cohort selection activates it. A launch that cannot take the installed payload at all — an installation being replaced right now — starts the retained active release instead of failing, and leaves activation to the next launch. What still requires `neutral-launch-v1` outright is narrow and never blocks a launch: the installed package's own manifest must declare it, and an update recovery capsule is never translated.
+
+`test/foundation/release/update-predecessor.integration.test.ts` is the gate for this. It installs each of the most recent published releases and drives the candidate through **that release's own** materialization and warmup, because a fixture built from the candidate would only prove the candidate agrees with itself. No reset or migration runs automatically. If disposable state blocks installation, inspect its resolved paths and obtain separate approval before removal.
 
 | State | Treatment |
 | --- | --- |