fix(chat): keep open artifacts in sync with disk, with calm stale-state handling

[matt2e]

Category: fix
User Impact: Documents and images open in the artifact viewer now track what's actually on disk — external edits, shell writes, and subagent output appear automatically — and when the view genuinely can't match the file, the viewer says exactly why (changed-but-unreadable vs deleted), dims the stale content, and recovers on its own when the file settles.

Problem: The artifact viewer rendered a one-shot snapshot. Files rewritten by shell commands, external editors, or delegated subagents drifted silently out of date, images stayed cached at their old bytes, and there was no signal that the preview no longer matched disk. Early iterations of polling then overcorrected: a single mid-rewrite race or transient I/O error instantly branded the view stale, one message covered every failure mode, and deleted files offered a Reload button that could never succeed.

Solution: The viewer polls the open file's metadata fingerprint (size + mtime + ctime, including the Windows change time) every 1.5s in the foreground and 10s in the background, checking immediately on focus and pausing while hidden. Content swaps use a stat → read → stat-confirm cycle so torn writes are never rendered or judged — a mismatched confirm is treated as "no verdict" and the next cycle retries. Images preload the cache-busted URL off-screen and swap only after decode, so the rendered image never flashes broken. Real failures get a two-strike grace period before the warning shows; a user-initiated Reload bypasses it for an immediate answer, and any successful cycle clears the warning and resets the streak. stat_file now returns a structured error distinguishing a missing file from other failures: deletion shows "File deleted from disk." with no Reload button (polling self-heals if it reappears), other failures show "File changed but can't be read." with Reload, and diverged content dims to 60% opacity beneath the strip.

Product behavior

• Externally changed text and images refresh in place, preserving scroll and without spinner flashes.
• One transient failed check changes nothing; two consecutive failures surface the warning strip and dim the content.
• Mid-rewrite (torn-write) races never flag the view; the next cycle retries the settled file.
• Deleted files get deletion-specific copy and no Reload; unreadable files keep the Reload action.
• Reload answers immediately, even on failure; recovery clears the strip and dim automatically.
• Polling slows to 10s while Berd is unfocused and stops while hidden.

Warning-strip copy is easy to change — happy to bikeshed the exact wording in review.

Verification

• just check, just test (6,900 passed, 1 skipped), just tauri-check, just tauri-test, just clippy, just tauri-fmt-check
• Manual verification on macOS (screenshots in comments)

Context: reported and root-caused in BOT-1675.

File changes

src-tauri/src/commands/system.rs
Add the stat_file command returning the file's metadata fingerprint (size, mtime, ctime — via FILE_BASIC_INFO on Windows) off the async command thread, with a structured FileStatError { kind: missing | other, message } so deletion survives the IPC boundary.

src-tauri/Cargo.toml
Adds the Windows filesystem API feature needed to read file change-time metadata.

src-tauri/src/lib.rs
Registers the new stat_file command with the Tauri invoke handler.

src/shared/api/system.ts
Add statFile(), the FileStatPayload/FileStatError types, and the fileStatErrorKind() rejection-narrowing helper.

src/features/chat/ui/ArtifactViewer.tsx
Poll the open artifact with visibility/focus-aware intervals; detect changes by fingerprint with stat → read → stat-confirm torn-write protection; preload-swap images; apply the two-strike grace period with immediate user-reload bypass; dim diverged content; show deleted vs unreadable warning strips.

src/features/chat/ui/tests/ArtifactViewer.test.tsx
Cover polling swap, background/focus timing, ctime-only rewrites, image preload/decode races, the grace period, torn-write healing, deleted vs unreadable copy and Reload visibility, immediate user-reload flagging, and recovery.

src/shared/i18n/locales/en/chat.json / src/shared/i18n/locales/es/chat.json
Add artifactViewer.fileDeleted, fileUnreadable, and reload strings in both locales.

[badideasforsale]

🤖 (posted by Brandon's agent; verification run by the agent, reviewed by Brandon)

Manual verification of this branch (599ec74) on macOS via just dev, exercising every stale-state path against a live artifact:

#	Scenario	Result
1	Raw shell write to the open file	✅ auto-refreshed within one poll cycle (~1.5s), no flicker, scroll preserved
2	File deleted	✅ "File deleted from disk." strip, no Reload button, last-good content kept + dimmed
3	File restored after deletion	✅ self-healed: strip cleared, fresh content rendered
4	File made unreadable (chmod 000)	✅ "File changed but can't be read." strip with Reload, content dimmed
5	Permissions restored	✅ strip + dim cleared automatically

Screenshots of each state are on the Linear ticket (BOT-1675, latest comment) — Linear-hosted images don't render cross-origin here.

One observation for review: the opacity-60 dim is subtle on the dark theme — visible side-by-side, but not loud. The strip carries the message, so we left it as-is; happy to tune the value (or the strip copy — see PR description) per taste.

[morgmart]

🤖 Automated code review

REQUEST_CHANGES: one blocking lifecycle issue remains. The new refresh/poll pipeline has no presentation timeout, so a metadata or content request that never settles can leave an initial viewer loading forever or permanently stop an already-open viewer from polling. Supplied GitHub evidence was inspected: all eight reported check runs completed successfully; required checks still independently govern merge readiness.

Deterministic publication result: 1 blocking and 0 non-blocking finding(s) publishable; 0 duplicate(s) suppressed.

[morgmart]

🤖 P1 · Bound filesystem waits (blocking)

The forced refresh awaits statFile/readTextFile without any presentation timeout. The native implementation explicitly moves metadata work off-thread because remote or removable filesystems may wait, but spawn_blocking does not bound that wait. If any invoke never settles, forcedRefreshInFlightRef remains true and suppresses every poll; similarly, a never-settling poll never reaches its finally/scheduleNextPoll chain. This creates a permanent stuck state rather than the promised degraded stale/error path.

User effect: Opening an artifact on a stalled filesystem can show the loading spinner forever, while an already-open artifact can silently stop checking for changes forever with no warning or recovery action.

Recommended fix: Add a presentation timeout around each stat/read/decode cycle. On initial load, leave the blocking state and show the existing load/error fallback; with last-good content, count the timeout as a divergence failure while allowing later poll cycles or a manual reload to proceed. Invalidate late results by generation so timed-out work cannot overwrite newer state.

Test: Add fake-timer tests where statFile and readTextFile each return a never-resolving promise; assert initial loading degrades to an actionable error, last-good content becomes stale after the intended grace period, subsequent polling continues, and a late completion cannot replace newer content.

[badideasforsale]

🤖 Fixed in d97bde3. Every stat/read/decode step in both the forced-refresh and poll effects is now bounded by withPresentationTimeout (PRESENTATION_TIMEOUT_MS = 10s), which rejects with a PresentationTimeoutError that flows through the existing catch/finally paths — so a hang gets the same treatment as a read failure (error state on initial load, divergence strikes against last-good content), and the finally blocks clear forcedRefreshInFlightRef/checkInFlight and reach scheduleNextPoll, so polling can no longer wedge.

Late settlement of a timed-out invoke is inert by construction: it merely re-settles an already-rejected wrapper (a no-op under settle-once semantics), so the abandoned cycle's continuation never runs and stale bytes can't overwrite newer state — the existing generation guards stay in place as a second line of defense.

Covered by four new fake-timer tests, including one that resolves the hung promise after a newer successful cycle and asserts the newer content stands.

[morgmart]

🤖 Automated code review

APPROVE: the prior presentation-stall defect is addressed with bounded renderer waits, recovery scheduling, late-result isolation, and discriminating tests. No new publishable findings remain after full review. One residual concern about repeated native operations after renderer timeouts is suppressed because it is the same underlying issue as the existing unresolved automation thread, which has a substantive human-account reply. Supplied GitHub evidence was inspected: six checks succeeded and two checks (Frontend build smoke and Transcript virtualization) were still in progress; required checks independently govern merge readiness.

Deterministic publication result: 0 blocking and 0 non-blocking finding(s) publishable; 1 duplicate(s) suppressed.

Pending checks: 1 check(s) are not complete.

This approval reflects the completed code review only; merge readiness remains governed by the repository's required checks.