Peekaboo/docs/restore.md

summary	read_when
Checklist for recreating the lost CLI/Visualizer refactor	Repo changes vanished after a reset Coordinating manual restoration of CLI runtime refactor Hunting for the Visualizer resiliency patches

Restoration Checklist (Nov 10, 2025)

A git reset --hard wiped the in-progress CLI runtime refactor + visualizer hardening. This file records what needs to be re-applied manually so we can recover without guessing. Reapply each section and tick it off in this doc when finished.

1. Visualizer Client Hardening

• VisualizationClient imports AppKit and checks NSRunningApplication to see if Peekaboo.app is running before connecting.
• Connection retries no longer stop after 3 attempts; instead we back off (capped at 30 s) and keep retrying indefinitely, logging the “Peekaboo.app is not running” message only once per outage.
• Every show* visual-feedback method re-calls connect() when invoked while disconnected.
• docs/visualization.md reflects the new reconnect behavior.

2. CLI Runtime Pattern (representative commands)

• Dock command + all subcommands use plain structs with @RuntimeStorage, service bridges, nonisolated(unsafe) configurations, and runtime loggers instead of singletons.
• Menu/MenuBar/System/Interaction commands follow the same shape (run(using:) marked @MainActor, outputLogger derived from the runtime, no @MainActor struct).
• FocusCommandOptions, WindowIdentificationOptions, and helper bridges use MainActor.assumeIsolated where needed instead of reaching for shared singletons.

3. Shared Helpers & Docs

• CommandUtilities.requireScreenRecordingPermission and selectWindow are @MainActor.
• docs/archive/refactor/runtime-visualizer-2025-11.md logs the new tmux build IDs after each restoration batch.
• Core/*/Package.swift files point to Vendor/swift-argument-parser so SwiftPM stops warning about duplicate IDs.

Add more sections as we rediscover missing edits. Update the checkboxes (or add short notes) once each item is restored so future contributors know what’s still outstanding.