v4.8.0

4.8.0 - 2026-10-03

Highlights: Add exact-window background drag, text selection, and coordinate scrolling to the CLI and MCP, make background rich paste work in freshly launched windows and fence it against concurrent clipboard changes, extend background scrolling to Safari, add opt-in fresh Accessibility reads to see, and recover capture readiness after slow startup checks.

• Add bounded exact-window background drag to CLI and MCP using one held-pointer owner, generation-bound last-point cleanup, and protocol-1.39 receipts; preserve explicit foreground gestures and report unverified retry-unsafe delivery without claiming the drop succeeded.
• Report missing background-drag source and destination IDs as explicit retry-safe, zero-dispatch ELEMENT_NOT_FOUND refusals without inventing receiver receipts or changing foreground error semantics.
• Preserve captured focused-element evidence in signed background-drag target attribution, avoiding false receipt failures while retaining unverified delivery and retry-unsafe outcomes.
• Prepare exact standard background windows for temporary rich/binary paste using observed blank chrome and retained editor state, preserving clipboard ownership, foreground isolation, owed releases, and truthful composite receipts through Bridge protocol 1.41. #877.
• Fence temporary exact-window background paste with the retained clipboard write generation, refusing unsupported hosts before writing and stopping new key-downs after another copy while preserving owed key releases and newer clipboard contents.
• Report failed background rich-paste preparation observations as no-input refusals, preserving earlier clipboard/preparation effects and avoiding misleading claims that a focus request was sent.
• Add explicit --allow-temporary-clipboard authority for Agent and public MCP to paste bounded base64 payloads through fresh exact-window snapshots while keeping UI background-only, requiring fresh resume opt-in, preserving ownership-aware cleanup and retry-unsafe receipts, and retaining nested/managed Agent attenuation.
• Preserve input-delivery and message-only refusal causes across composed background preparation outcomes, including content-free native chrome observation diagnostics, without changing dispatch or retry safety.
• Preserve the underlying cause of failed background paste preparation reads, without changing input dispatch, deadlines, or retry safety.
• Add background select-text / MCP select_text for literal, context-disambiguated selections and caret placement, including unfocused native fields, with UTF-16 source-drift checks, unchanged-text verification, and protocol-1.42 receipts without keyboard or clipboard fallback.
• Add exact-window background coordinate scrolling via CLI --at / --global and MCP coords, preferring the nearest proven AX scroll owner and allowing pixel-authorized native-WebKit wheel delivery without an exposed owner, preserving the requested point and retry-unsafe receipts, and refusing older hosts through protocol 1.43.
• Recognize Safari's framework-linked executable and scroll-area containers for eligible exact-window background wheel dispatch, preserving hidden-app exclusions, exact receipt checks, and unverified retry-unsafe outcomes.
• Add opt-in see --fresh and MCP see / inspect_ui freshness with uncached AX evidence, truthful used_cache metadata, and fail-closed host compatibility while preserving default caching and partial-tree limits.
• Preserve native Accessibility date values as ISO-8601 UTC timestamps in UI observations instead of silently omitting them, including Calendar's date-valued controls.
• Recover ScreenCaptureKit readiness when a slow startup safety scan later completes, preserving fail-closed capture while pending or failed and the existing per-capture ownership checks.
• Validate Bridge Agent and live certification-producer executables against the running universal-binary slice, avoiding false identity refusals while preserving exact code, path, process-generation, file, and peer-trust checks.
• Redact inline base64 payloads from Agent live tool-call previews, including nested and partially streamed values, without changing authorized tool input.
• Remove proven duplicate see / inspect_ui element listings from Agent provider requests while preserving observation evidence, raw MCP/CLI output, and saved history.
• Preserve known clipboard cleanup status through Agent paste errors and public MCP metadata, keeping provider claims isolated and canonical dispatch, target, and retry semantics unchanged.
• Preserve plain and attributed Accessibility value labels in menu listing, path selection, and menu-extra matching, keeping title precedence and ambiguous-name refusals unchanged.
• Preserve a native text field's coherently observed post-value selection for the dependent caret update, while refusing later state or focus drift without rebasing or replay and retaining nested typing failure diagnostics.
• Preserve retry-safe no-dispatch outcomes for background wheel failures before the first event, including stale or out-of-window geometry, without weakening accepted-prefix or uncertain-delivery failures.
• Preserve unsupported background scrolls as exact-target, retry-safe no-dispatch refusals through Bridge instead of reporting a possible mutation or implying all background scroll is Accessibility-only.
• Preserve reported receiver receipts in MCP background scroll errors without changing retry safety, snapshot invalidation, or foreground global-input attribution.
• Preserve reported process-generation and exact-window receipts in CLI and MCP paste errors after unconfirmed targeted input, without changing retry safety or attributing shared clipboard effects to a window.
• Report conflicting concrete snapshot and target selectors in set-value and action as retry-safe, non-dispatched INVALID_INPUT refusals instead of unknown, unverifiable errors; clarify the targeting alternatives.
• Preserve Bridge route, reported target receipts, hints, and causes on typed stale-snapshot CLI refusals instead of replacing them with local errors; keep snapshot-consumption and finalization safeguards unchanged.
• Keep app-launch bundle paths and selector proofs consistent across canonical spellings, fixing background verification under /private/tmp while preserving process-generation, ambiguity, and caller-local alias checks.
• Fix Bridge verification when macOS hides the caller's window title, preserving exact process/window identity, fresh Accessibility reads, and strict signed-receipt validation.
• Distinguish unreadable exact-window focus evidence from actual window mismatches, retaining the AX observation stage and native error without changing background input guards or retry safety.
• Reuse normalized Agent tool-result claims when building execution traces, eliminating duplicate canonical validation while preserving failure, dispatch, and redaction semantics.
• Clarify that see pixels and Accessibility metadata are not acquired atomically, and explain how to verify an asynchronous action without replaying it.
• Explain when listed windows are rejected by coordinate-target eligibility without exposing their titles or changing the filters, and preserve already-completed setup focus plus the later refusal diagnostic in cursor-move errors. #869.
• Explain that exact-window paste capability refusals can result from custom-socket Bridge trust limits, not only an outdated host, without changing trust or retry behavior.
• Clarify that deprecated app launch --no-focus is a compatibility no-op: default launch only verifies an already-running app, while cold launch still requires explicit foreground consent.
• Clarify that foreground paste does not confirm receiver consumption, explain how to inspect an unconfirmed paste outcome instead of replaying it, and add a charset-safe HTML hyperlink paste example. Thanks @marcoantoniofassa! #885.
• Clarify backward versus forward Delete key names and supported Command modifiers in press help and docs, without changing key mappings.
• Refresh Playground testing guidance for v4 inventories, signed fixtures, fresh exact-window snapshots, and background outcome verification without input replay.
• Bind companion-app installation and rollback quits to verified exact-path process generations, refusing ambiguous targets, inspection failures, and uncertain retries without raw PID signals. #874.
• Bound ScreenCaptureKit process-safety signing inspections to two concurrent workers across censuses, preserving complete blocker collection, identity checks, registration retries, and fail-closed readiness.
• Sign debug CLI builds with the canonical Peekaboo CLI identifier so they satisfy existing GUI Bridge and deployment healthcheck identity checks.
• Repair first-party GUI qualification by admitting the signed controller and validating canonical global/window receipt scopes; preserve exact authenticated inventory binding and avoid repeating an acknowledged owner disconnect after an evidence error.
• Remove idle certification-coordinator exit delays by clearing completed child-wait timers and their listeners, preserving normal output draining and bounded TERM/KILL cleanup.

Compatibility

• Exact-window background drag requires a GUI Bridge host at protocol 1.39, exact-window background rich/binary paste requires the clipboard-fenced protocol 1.40 path (cold-window preparation uses 1.41), background text selection requires protocol 1.42, and exact-window background coordinate scrolling requires protocol 1.43. Screenshot-backed see --fresh through a Bridge host requires its fresh Accessibility tree capability. With an older Peekaboo app as the Bridge host, these fail closed before any clipboard write or input; update the app together with the CLI.

Verification

• Source commit: 4d43dc9d80cd2aa3787a27f54b76d692db1dcf8f
• Release plan SHA-256: e70a17b5d8af944a0da809e481ad2b38df007976cf2fd881b0a9bfb1bd326059
• Checksums SHA-256: 05a88dd82e35a007ae2d049aad5973ce8a56e2ece0e402829827af2bf10b3522
• npm version: 4.8.0
• npm tarball: https://registry.npmjs.org/@steipete/peekaboo/-/peekaboo-4.8.0.tgz
• npm integrity: sha512-lC4CcWlaFvpUqUQu8G4iVWib5YEw9oMBu70cmv+zj2fY84DrY0Vb3c37y1ic1puh7Q1v4caXya/Brax/0H5C7w==
• npm published: 2026-10-04T22:52:47.202Z

Proof

Peekaboo 4.8.0 is built from the frozen source commit recorded in release-plan.json: 4d43dc9d80cd2aa3787a27f54b76d692db1dcf8f.

• Release preparation: 4.8.0 publishes from release/4.8.0 (#917), created from main at 513594a6b after chore(release): prepare Peekaboo 4.8.0 and its follow-ups (test(release): keep runtime-library fixtures independent of the release signer, the #905/#906/#907 changelog folds, and test(agent): isolate resume-model continuity from synthetic provider configuration). The branch adds feat(release): publish from an explicit release branch and chore(release): include #908-#915 in Peekaboo 4.8.0. Independent Codex P0–P2 reviews passed with no findings: all 43 root changelog entries survive verbatim with contributor credits, the release notes equal the root 4.8.0 section, the CLI changelog is a consistent 36-entry section that keeps its existing entries, and the highlights, README, and Compatibility note are supported by the entries, the Bridge protocol constants (drag 1.39, clipboard-fenced exact-window paste 1.40, cold-window preparation 1.41, text selection 1.42, coordinate scrolling 1.43), and the documented fresh Accessibility tree host capability. The changelog, tracked release-notes, and documentation contracts were run directly against the branch; the publication preflight runs the complete prepare-release, including CLI command/help/inventory contracts, against the freshly built CLI.
• Native publication toolchain: Xcode 27.2 (27B5019j), Swift 6.4, macOS SDK 27.2, Node 26.10.0, pnpm 11.27.1, on macOS 27.0, at normal scheduling priority.
• The publication driver runs the complete native preflight on the frozen source before packaging: formatting, lint, documentation contracts, safe script/artifact contracts, public SwiftPM consumer build, browser connection contracts, background certification, Foundation tests, CLI tests, and CLI command/help/inventory contracts, then builds, signs, and notarizes the universal CLI, app, and DMG.
• Earlier publication attempts stopped before any packaging or public action. (1) The runtime-import fixture test inherited the driver's MAC_RELEASE_CODESIGN_IDENTITY and rejected its ad-hoc-signed fixture library; the test now clears both release-signer variables (fails before, passes after with them exported), and the remaining safe-suite script tests were rerun with the same variables exported and passed. (2) On a host with a load average near 90 on 32 cores, a reduced-priority run starved the TTY credential test's 5-second child-startup window; the suite passed in isolation, and this run uses normal priority. #905 and #906 landed during that window and ship in this release. (3) The exact-source supplemental full-package run for that candidate failed five resume-model continuity cases: #905's synthetic Agent test support replaces the process-wide Tachikoma configuration with a provider-forbidding one, and the continuity suite, which resolves real local Ollama and LM Studio providers, inherited it in the serial single-process run. The suite now owns an environment-free configuration and restores the previous one (fails before, passes after in one serial process together with a polluting suite); production code never writes that configuration and was unchanged. That attempt was stopped during its preflight. (4) On a host saturated by unrelated TypeScript builds, two wall-clock-bounded cases of the live multi-target certification coordinator test timed out during the preflight; no test or script had changed since the passing candidate, and the same file then passed 36/36 in isolation against that source with the publication Node 26.10.0. #907 landed during that run and ships in this release. (5) A further run on the same saturated host hit a different load-bound case (a qualification-tools managed launcher whose guardian exceeded its protocol deadline before acknowledgement). Because main kept moving during each multi-hour preflight, the release now runs from release/4.8.0 with the driver's new --release-branch mode, which forwards the preflight's documented non-main --force only when exactly that branch is checked out (covered by the driver fixture and release-preflight contract tests, each failing with the forwarding removed). #908-#915 landed in that window and ship in this release.
• npm publication runs through the Publish npm release tarball workflow, the registered npm trusted publisher for @steipete/peekaboo. It publishes the exact tarball uploaded to this release after checking it against checksums.txt and its embedded name/version, with signed provenance, and the driver's resume verifies the registry integrity against the retained tarball. This route first published 4.7.0 on 2026-10-03.

Older-runtime qualification

• The driver's Swift runtime import audit verifies every CLI slice against the macOS 26.5 SDK runtime baseline (minimum macOS 15.0) and rejects unsupported strong runtime imports, including _swift_initBorrow, before packaging.
• Before publication is confirmed, the packaged arm64, x86_64, and universal archives are independently audited against the same SDK's Swift runtime export lists (following re-exports) and launched with all Xcode, Command Line Tools, and cryptex toolchain paths denied; results are recorded with the release closeout. During 4.7.0 qualification this audit flagged exactly _swift_initBorrow in the published 4.6.0 binary.

Exact-source hosted validation

• macOS CI (pull request for the release branch; its merge with main at 513594a6b has the same tree as the release commit): https://github.com/openclaw/Peekaboo/actions/runs/37229109704
• Swift/JavaScript/Actions analysis (dispatched on release/4.8.0): https://github.com/openclaw/Peekaboo/actions/runs/37229111869
• Supplemental release validation: https://github.com/openclaw/Peekaboo/actions/runs/37229109436
• macOS 26 extracted-artifact smoke (hosted macOS 26 runner, Xcode 26.x build of the same source): https://github.com/openclaw/Peekaboo/actions/runs/37229114220

Coverage limits: no physical macOS 26 or macOS 15 machine executed the 4.8.0 bytes. SwiftLint reports existing non-serious violations (mostly multiline_arguments in tests, plus size/complexity limits); the hosted SwiftLint gate passes. The previous publication candidate's supplemental validation needed one rerun of an AXorcist timing test (AXTimeoutHelper 200 ms deadline) on a loaded hosted runner. No task-owned isolated desktop was available for live desktop/provider integration proof of background drag, cold-window paste, temporary-clipboard Agent paste, background text selection, or coordinate scrolling; synthetic certification and hosted tests are not claimed as live desktop proof.

Publication source: 4d43dc9d80cd2aa3787a27f54b76d692db1dcf8f. Publication requires successful completion of the linked exact-source workflows.