feat(screen-hash): stable content hash on snapshot and render-wait results

[ThomasK33]

Summary

Adds an optional screenHash to snapshot and render-wait results — a lowercase 64-char SHA-256 of the canonical visible-screen text — giving a caller (typically an AI coding agent) a stable token to tell whether the rendered screen content actually changed between two observations, without diffing full text. Unlike the event-log sequence it does not advance on cursor moves or no-op repaints; unlike the screenshot pixel sha256 it is the semantic (text) counterpart.

Implements the screen-hash PRD (docs/prd/screen-hash/PRD.md). Closes #125.

What's included

screenHash field

• Optional screenHash on the structured + text snapshot results and on render-wait results, validated by the existing (now consolidated, single-source) Sha256HexSchema.
• Hash = SHA-256 (UTF-8) of visibleLines[].text joined by \n — visible screen only (no scrollback, cursor, or styles).
• One shared canonical-visible-text helper (src/renderer/canonicalScreen.ts) feeds the Screen Hash, the host Screen Stability compare, and the text Render Wait matcher, so the three can never disagree about "the screen".

Key decisions (settled during planning)

• Hash any observed snapshot: matched live waits, snapshot captures, and the offline host-unreachable matched:false fallback all carry it; only results that observed no snapshot (live timeout, consecutive-failure giveup, replay-error throw) omit it — so "absent hash ⇔ no screen observed" holds literally.
• Batch: matched batch wait-step records carry it too.
• Renderer convergence: both backends are aligned on one canonical screen form (exactly rows lines; full grapheme clusters; interior blank cells as spaces; ASCII-only trailing trim) so the hash is renderer-independent. This intentionally changes the default ghostty-web stability/text-wait comparand on grapheme / interior-gap / non-ASCII-trailing screens — a deliberate, narrow change pinned by characterization + cross-backend tests (see PRD §Out of Scope and user-story feat: Week 7 — contract ratification, test locks, proof bundles, and docs sync #10).

CI / test hardening (separate commit ci: …, independent of the feature)

• test:integration, test:e2e, and the combined test now retry transient failures (--retry=2); test:unit stays strict. Browser/host/PTY e2e tests can flake under machine load (a screenshot-render/RPC hiccup that passes on retry and in isolation) — this keeps such flakes from spuriously failing CI while a genuine failure still fails all three attempts. Documented in CONTRIBUTING + CI.

Verification

• Green locally: typecheck, lint, oxfmt, unit (1334 tests), build, workflow-lint (zizmor).
• The cross-backend equality test and the CLI envelope integration test are host/native-dependent (need a live PTY host + the optional @coder/libghostty-vt-node addon) and run in CI; the convergence's pure decode logic is unit-tested via exported twins (assembleCanonicalLine / stripTrailingAsciiSpaces).

Notes for reviewers

• screenHash lives on the result, not on SemanticSnapshot (the snapshot shape is unchanged).
• The deliberate cells[] (blank = '') vs visibleLines[].text (blank = ' ', spacer dropped) asymmetry is documented inline in ghosttyWeb/backend.ts; the hash sources visibleLines[].text only.
• No ScreenshotResult change — screenshots keep only their pixel sha256.

🤖 Generated with Claude Code