fix(image-paste): preserve attachment identity across draft restoration (integrate #688)

[tt-a1i]

Problem

Image queue restoration can collide with literal [Image #1] text, and native Undo can restore a token without its attachment mapping. Current main also reclaims deleted direct-draft files, so restoring only the mapping can point to a missing image.

Value

Preserve literal text and real readable attachments across native Undo and queue restoration while retaining main's cleanup of abandoned direct files.

Approach

Integrate original #688 by ooiuuii, preserving original commit 1291d0baa621323c10cc3bba8a498c4301d21e03 and companion history. Merge fixed main f98d6a4737461ba8d8ee100f113b5a7c3a0001a0, retaining its direct-file ownership cleanup and Session-start reset.

Reserve literal IDs and recover unique mappings only through native Undo, using the existing 128-entry removed window. Count active and eligible removed mappings as file references, with device/inode/birth-time physical identity while preserving display/submission strings. Unlink requires an unchanged regular-file identity snapshot; unresolved identities, foreign leaf symlinks, replacements, and external modifications are preserved. Reclaim only extension-owned, unreferenced direct files. Transfer the actual submitted snapshot paths before clearing old removed references; defer reclamation only within native input's clear-before-submit callback order. Keep getExpandedText a pure query. Adoption and main's ambiguous active setText("") handoff release ownership conservatively; removed-only abandoned files are reclaimed.

Validation

Frozen head: 43884820e865e439e0e4231f5c5f787ca2d77627; tree a204db6ec0a9cdb3acec115bf06a675e2dd993b1. Local Node v26.8.1 / Bun 1.3.14:

• bun install --frozen-lockfile: passed.
• Focused image-paste/store/native-editor/editor-layer tests: 62 passed; scoped lint and git diff --check passed.
• Native Pi SDK/TUI 1.2.0 Editor and queue hooks exercised real temporary PNG files and byte readback: Ctrl+U/Undo, typed/duplicate revocation, 128 eviction, shared/aliased paths, Session boundaries, plain Enter snapshot order, 129-active submission, queue and history recall, and pure expansion.
• bun run check: passed on the frozen head.
• bun run test: passed on the frozen head: Node 2473 passed, 9 skipped, 0 failed; UI 1338 passed across 88 files.

An independent physical-alias prefinal review found a further unsafe lexical-only identity case; device/inode/birth-time identity and final path/fingerprint verification repaired both directory and case/hardlink aliases, with additional RED/GREEN PNG alias/replacement/unknown/symlink controls. RED PNG read failures were retained before the ownership repair, including normal Undo, normalized aliases, and submission above the recovery window. This native acceptance uses in-process real Editor/queue hooks; manual whole-package TUI/OS clipboard and provider/model execution were not performed. Two independent final source reviews passed on this exact head. Exact-head GitHub CI passed; all 18 current checks are successful. Independent last-push approval remains a merge gate.

Impact

• User-visible behavior: Undo restores eligible attachments with readable files; literal and duplicate tokens stay literal. Queue/history restoration preserves delivery paths.
• Model-visible context/tools: no schema/tool change; submissions retain real image paths.
• Runtime/lifecycle: direct file reclamation follows the union of active and eligible removed references; submitted/adopted files remain Pi-owned. Main's conservative ambiguous active handoff stays intact.
• Persisted config/data: no configuration or Session format change. Up to 128 removed mappings can retain direct-image files longer than immediate deletion; total retained bytes are not capped and there is no new TTL. Eviction, revocation, reset, and completed delivery retire abandoned owned references.
• Compatibility/risk: no second undo stack, new setting, global cache, or cleanup of paths inferred merely from token syntax. File reclamation remains best effort. The original and companion PRs remain separate review records.

[tt-a1i]

Reviewed fixed head b3590807932338e0ca36ceb90ea290bf476806b0 against frozen main a18f457687b45c877bc8a15d689a7580c4f0659a. This COMMENT records the independent source review of the integration of original PR #688; it is not an APPROVE or a merge authorization. The original commit is preserved, and the scoped source/test patch is byte-identical.

Standards: 0 actionable findings. Pi retains editor/Undo ownership; recovery metadata is bounded and cleared at submission/reset/session boundaries.

Spec: 0 actionable findings. Literal IDs, explicit Undo, ambiguity revocation, 128-entry eviction and native queue/editor regressions match the original attachment-identity requirements.

Local validation at this head: node --test --experimental-strip-types tests/extensions/image-paste/index.test.ts tests/extensions/image-paste/native-editor.test.ts exited 0 (42 passed, 0 failed, 0 skipped); bun run check and git diff --check exited 0. Full-test receipt: bun run test exits 0 at b3590807: Node 2,321 passed / 9 skipped / 0 failed; UI 1,158 passed across 82 files.

Remote CI is a separate current-head gate: CI run 38353110690 is terminal SUCCESS on checkout merge 4f11d0b3; 17/17 CI jobs succeeded. E2E and Plan-provider fixture checks pass. The integration remains draft and needs eligible maintainer review.. No result is inferred from the original PR’s older checks. Installed Pi, live providers/models, manual clipboard/picker use, visual and release acceptance are outside this receipt. Protected main merge and closing the original PR remain pending human selection.