An auto tiler for macOS
parcel Tests Reality
72 files

AccessibilitySettingsGuard.swift
ActivityReality.swift
ApplicationRuleReality.swift
BrowserProfileCleanup.swift
CapacityReality.swift
ConfigReloadReality.swift
CoverageOracle.swift
CoverageReadiness.swift
DefaultArrowAcceptance.swift
FrameOracle.swift
InputAudit.swift
InputDefaults.swift
LanguagePreferenceBackup.swift
LanguagePreferenceReadback.swift
LanguagePreferenceSnapshot.swift
LanguageRestartOracle.swift
LanguageRestartReality.swift
LayoutPresetReality.swift
LayoutSizeOracle.swift
MenuSizesReality.swift
MixedAppChurnReality.swift
ModalDialogReality.swift
MotionSpeedReality.swift
MouseCoverageReality.swift
NativeArrangementReality.swift
NativeFocusFrameOracle.swift
NativeFocusReality.swift
OwnedAppDiscard.swift
OwnedMovie.swift
PositionRefusal.swift
PreferenceSnapshot.swift
README.md
RealApps.swift
RealDesktopAudit.swift
RealDesktopEvidence.swift
RealDesktopFirstRun.swift
RealDesktopState.swift
RealityApplicationChild.swift
RealityConfigTransaction.swift
RealityDisplays.swift
RealityDriver.swift
RealityEditorProfile.swift
RealityFixture.swift
RealityMain.swift
RealityProcess.swift
RealityRecovery.swift
RealityScenarios.swift
RealitySession.swift
RecoveryCoverageReality.swift
ReservedEdgesReality.swift
ResizeIncrements.swift
RetileMovementOracle.swift
SettingsColumnReality.swift
SetupReality.swift
SetupVisibility.swift
ShortcutParity.swift
ShortcutsOffReality.swift
StackCycleReality.swift
SystemVideoPlayerReality.swift
TabViewConsoleSession.swift
TabViewIgnored.swift
TabViewLatency.swift
TabViewReality.swift
TabViewVoiceOver.swift
TourFirstRunReality.swift
TourNativeAcceptance.swift
TourRollbackReality.swift
VisualOracle.swift
VoiceOverAcceptance.swift
VoiceOverPreference.swift
VoiceOverSessionEvidence.swift
WindowModeStabilityReality.swift
README.md

Reality #

mise run reality builds or reuses a content-stamped reality-only debug build/Parcel.app, takes the shared screen lock, and runs ParcelRealityTests under caffeinate -dimsu. Direct use requires PARCEL_REALITY=1 and the lock wrapper. Without opt-in, no apps launch. This lane uses real apps; a separate FixtureApp check covers the driver. Unit lanes run only pure harness and protocol tests.

The wrapper logs reuse and rebuilds only changed stages: signed driver, bundle, harness, or FixtureApp. Stamps cover source/resource bytes, package and toolchain inputs, signing identity fingerprints, and output contents; timestamps do not matter. mise run reality -- --no-build --scenario launch never compiles or signs. It rejects missing, unstamped, stale, or modified outputs before launching apps, including a bundle replaced by an ordinary debug or release build. Omit --no-build to rebuild; it does not bypass opt-in or existing-permission checks.

Existing permission #

Only build/Parcel.app needs Privacy & Security → Accessibility. No separate helper or harness grant is needed. The local Parcel Development identity and Parcel's designated requirement must stay stable; ad-hoc reality builds are rejected. Run Scripts/make-dev-cert.sh in a terminal only if that identity is missing.

mise run reality -- --preflight-only launches a host-only Parcel instance through Launch Services. It directly spawns Contents/Helpers/ParcelRealityDriver, which inherits Parcel's TCC responsibility. The host never starts the product runtime or changes preferences; it forwards only the private socket path. The harness checks peer PID, direct-child ancestry, Accessibility, and HID posting without a consent prompt. Missing inherited access fails clearly before scenario windows open.

The launcher exists only under DEBUG && PARCEL_REALITY, enabled by Scripts/bundle.sh debug --reality. Ordinary debug and release bundles contain neither the helper nor its launcher; bundling checks binary strings and symbols.

Frame checks need no Screen Recording. Optional pixel checks require both PARCEL_REALITY_SCREEN_CAPTURE=1 and an existing Screen Recording grant for the responsible Parcel bundle. Only the helper calls ScreenCaptureKit; the capture request carries explicit opt-in rather than forwarding the harness environment. This lane never requests a new grant. Captures remain private and may include other visible apps; inspect them before sharing. Without opt-in, visual rows explicitly need Screen Recording. CG overlay metadata cannot prove panel pixels.

A rebuilt reality app needs direct-capture consent once, even with its existing Screen Recording grant. Click Allow when macOS asks during an opted-in pixel check. Reusing the stamped bundle avoids rebuilding into another consent request; --no-build keeps that binary unchanged. System-scheduled privacy reminders can still appear.

For one scenario: mise run reality -- --scenario launch. --list lists scenarios without opening apps when used directly on the executable. --report PATH writes the feature table there; otherwise it stays beside build/reality/<run>/results.json. A red feature exits 1. Missing hardware or opt-in for display, Space, VoiceOver, and pixel rows reports unsupported-host in both default and explicit runs; this is not a product pass. The pre-start shortcuts-off interception requirement uses the same status. Other supported scenarios requested with --scenario fail if they cannot run. Unsupported rows and skips do not stop later scenarios after verified cleanup. Permanent unsupported native-tabs and secure-input-pause rows are listed by --list, but excluded from default runs; explicitly selecting them reports their declared coverage gap without launching apps.

Conditional unsupported host row Required evidence
shortcuts-off: default shortcut delivery Before the tiler starts, the same tagged default chord fails exact owned FixtureApp delivery with a driver interception receipt. The chord, flags and native evidence are retained. This host result is unsupported-host, never a product pass; the row stays in default runs.
app-vscode: launch ownership The direct editor adapter received matching kernel child, bundle and GUI identity but no required launch date on this host. Its receipts prove owned cleanup and isolated storage; the case remains visible as unsupported-host without further editor launches. No editor tiling pass is claimed.

Interception after startup or reload still fails, as do other prerequisite and safety errors. The lane never quits another app or changes its shortcuts to manufacture a pass.

voiceover-shortcuts uses fresh ledger-owned FixtureApp processes with native keyboard receipts, never document-app pass-through. Global Command-F5 is forbidden. Both VoiceOver rows can own a temporary session through Launch Services with PARCEL_REALITY_VOICEOVER=1, then stop the owned process and verify the original preference through readback. The lane never writes accessibility preferences. A stale voiceOverOnOffKey=1 without a running VoiceOver app is reported at lane start and blocks an owned session; it is never retained as an original to restore on. If macOS leaves the flag changed after stopping, the lane fails closed rather than rewriting it. Do not opt in during someone's screen-reader session. Normal Control Option checks skip while the actual VoiceOver application is running; they never turn an existing session off. A skip is not a live accessibility pass.

Scenarios #

Scenario Feature proved by real observation
real-desktop-first-run Explicit opt-in only: first-run Tidy on the current desktop, native Space invariance, and graceful-quit rollback
launch Three fresh documents tile within two seconds of the NSWorkspace launch request
layout-grid Grid bounds, non-overlap, gaps, and usable-area coverage
layout-columns Full-height columns with configured gaps and preserved divider weights
layout-rows Full-width rows with configured gaps and preserved divider weights
layout-side Primary/sidebar bounds, gaps, and non-overlap
layout-tree Tree partition bounds, gaps, and non-overlap
layout-bsp BSP partition bounds, gaps, and non-overlap
layout-accordion Accordion partition bounds, gaps, and non-overlap
app-textEdit Fresh owned TextEdit document is tiled
app-finder Fresh owned Finder folder window is tiled
app-safari Fresh owned local-page Safari window is tiled
app-firefox Fresh local-page browser window in an isolated temporary profile is tiled
app-chromium Fresh local-page Chromium window with a separate user-data directory and disabled extensions/background networking is tiled
mixed-app-churn Chromium, Firefox, TextEdit, Finder and Terminal share two independently verified columns; paused manual movement, creation and native closure preserve other frames; resume and repeated Retile settle all survivors; quit restores original and paused-arrival frames
app-vscode Explicit unsupported-host row: the direct editor launch adapter cannot prove its required launch-date ownership metadata; no further editor launch or tiling proof is attempted
position-refusal A shifted browser frame returns inside its column with no one-point overflow
app-terminal Fresh owned Terminal fits its measured resize grid across gap changes; repeated Retile preserves the same CG frame, samples no one-point collapse, and checks the eight-setter receipt
app-notes Notes window from a newly launched process is tiled
app-calculator Default exclusion preserves Calculator's real frame
app-systemSettings The standard System Settings window tiles within usable bounds; dialogs and fixed-size auxiliaries keep their native floating behavior
app-quickTime Fresh owned local video keeps the player's native frame through Retile; prcl why identifies its default floating rule
cap-stack Four windows occupy two frames; closing both singleton anchors at cap 3 immediately refills three fitting slots, preserved through a fresh arrival
float-when-full Overflow centers as a float, survives Retile, and rejoins after a tile closes and Float is toggled
app-minimum-stack Three fresh native apps expose CG-measured minimum widths; two fitting tiles retain all three windows
phantom-gap Drops one native destruction notification; activity or acknowledged simulated wake restores exact real columns
native-tabs Explicit unsupported row: owned Finder/Safari tab lifecycle controls are not available
stack-cycle Next/previous stack shortcuts preserve real frames; closing the visible member raises its most recently used survivor
new-window New document joins and existing windows change frames
close-window Exact closed ID disappears and remaining tiles expand
swap Two owned window IDs exchange real frames
motion-speed Fast and slow swaps have independently sampled CG intermediate frames and different transition durations
focus-next-prev Window-server ordering changes focus without changing frames
tab-view Default shortcut and arrows select another tile; minimized restore returns to its saved tile or the focused workspace after a layout change
tab-view-off With Automatic tiling off, switching and minimized restore work while other windows retain their real frames
tab-view-latency Thirty real HID openings measure original key-event timestamp → first panel display link; p50/p95 and raw samples are retained
tab-view-ignored Ignored visible and minimized windows cannot be selected or restored
tab-view-voiceover Opt-in VoiceOver session keeps bare and Control–Option arrows in Parcel and restores the original app on cancel
make-primary Native focus drives both IPC and the default promotion shortcut; exact primary/secondary frames exchange and other frames stay unchanged
sizes Grow, shrink, and reset change/restore real divider dimensions
sizes-grid / sizes-columns / sizes-rows / sizes-side / sizes-tree / sizes-bsp / sizes-accordion Default size shortcuts enlarge, shrink, and reset the main real window in every layout
menu-sizes-grid / menu-sizes-columns / menu-sizes-rows / menu-sizes-side / menu-sizes-tree / menu-sizes-bsp Menu preset and reset command paths change and restore real frames; menu interaction is checked separately
preset-grid / preset-columns / preset-rows / preset-side / preset-tree / preset-bsp Saved main size applies on arrival, and configuration reload changes real frames for each preset
settings-main-size Settings reselects saved Half/60% after native shared-edge resize to 70%; exact CG frames return without rewriting config, including failed-apply retry and reverse
application-rule Adding an application-wide floating rule preserves the chosen app’s real frame and expands the remaining tile
reserved-edges Settings sharing replaces distinct display edges, Undo restores the same owned CG frame, and sharing off seeds independently editable edges for every connected display
float Float survives retile; toggle returns the window to tiling
always-float Reopened document remains floating
minimum-size Explicitly tiled System Settings stays within usable bounds without overlapping neighbors
fixed-size Calculator keeps its size while neighbors tile without it
shortcuts All four default swap/focus arrows, next/previous window brackets, and layout/float chords posted by the driver
voiceover-shortcuts Opt-in VoiceOver session preserves real frames for Control Option chords, then checks shortcut recovery
modifier-drag Command-drag exchanges actual frames
modifier-stack-drag Option Command drop merges two native documents into a full-size stack; either member can be raised
edge-resize Native shared-edge drag grows/shrinks both real columns, preserves outer bounds, and reverses
native-drag-rearrange Plain title-bar dragging exchanges two of three real columns, then swaps a whole two-member source tile with an occupied different-app target; CG frames, ordered membership and selected members survive focus changes and one Undo restores each baseline
native-three-divider Main-divider resizing grows the full-height primary and shrinks both stacked neighbors, preserves their vertical split and outer bounds, and reverses with one Undo
native-full-height A native drag to the full-height target creates a primary tile, keeps every window managed, remains stable, and reverses with one Undo
native-outer-resize A native outer-edge resize changes two real column proportions without moving outer bounds; membership and Automatic tiling remain on, focus changes preserve the ratio, and one Undo restores both frames
shortcuts-off Off at startup and reload delivers default chords only to owned FixtureApp windows; enabling recovers a real swap
secure-input-pause Explicit unsupported row: no owned Secure Input actuator/restoration; automatic tiling and Carbon shortcuts are not paused
focus-mode Focus expands the real window and toggle restores the prior layout
window-mode-stability Float and Focus retain independently read CG parent and neighbor frames through title changes and an exact owned NSOpenPanel open/focus/Cancel cycle; default auxiliary classification, unchanged picker write counters and bounded engine window/focus receipts precede negative assertions; CG sampling runs throughout the native popup lifecycle, until modes are explicitly toggled off
no-peek Driver opt-in pixels follow exact native focus across all three owned documents; background blurs+dims, or dims with NO blur under Reduce Transparency/Increase Contrast; focused pixels and CG frames stay unchanged
clean-space Driver opt-in pixels follow native focus and prove the configured backdrop; toggling off restores document pixels
clean-space-sleep Token sleep removes exact CG backdrop IDs; receipt-acknowledged wake keeps them off, then explicit re-enable recreates display-bounded surfaces; pixels optional, not physical sleep
automatic-tiling-shortcut Default toggle preserves disturbed frames and newly opened documents while off, then resumes tiling
display-full-swap / display-full-stack With two displays, an arrow exchanges or stacks real windows onto a capped display and reverses the operation
pause-resume Real frames stay disturbed while paused; resume tiles a new document
retile Explicit retile repairs balanced columns while Automatic tiling stays off; feedback equals CG-observed movement, then zero on an unchanged retile
config-reload Real watcher on an isolated config returns gaps and reserved edges to earlier values; owned document and resize-grid frames converge without reload or Retile commands
activity Automatic, keyboard and mouse placement counts match independent CG movement; unchanged Retile adds zero; quit flushes and collection off removes the isolated file
relaunch-memory Reopened IDs regain saved layout/cap/ratio/stack frames; reopening only overflow members restores available tiles rather than a collapsed stack
language-restart Settings saves an isolated language choice; product restart restores real frames and retains that owned suite/config/state; cleanup removes the suite
tour-native-automatic / tour-native-empty / tour-native-stacked Rendered Get started, Back, Continue and Tidy preserve held CG frames, then complete with real placement; empty and capped layouts are explicit variants
tour-native-automatic: persisted recovery An incomplete deferred recovery checkpoint automatically reopens Ready; Keep current arrangement preserves owned fixture frames and Automatic off, then a separate native Tidy completes setup and tiles those frames
tour-native-manual Native mode disclosure/radio and Finish setup preserve current/new frames through relaunch; explicit IPC Retile works while Automatic stays off
tour-native-replay-on / tour-native-replay-off Fixture IPC opens replay; rendered Set up later preserves held CG frames through quit, relaunch and repeated deferral
tour-native-german German controls and owned-window captures after an isolated saved language choice
tour-busy-desktop First-run Tidy handles six owned windows, including an unknown height clamp and a one-time frame adjustment; CG verifies bounds, separated layout slots, and matching stack frames, and fixture counters prove both constraints ran
tour-modal-dialogs An exclusively owned fixture uses default classification for a sheet, floating panel and real NSOpenPanel beside TextEdit/Finder documents; Tidy keeps the parent tiled, native picker open/Retile/Cancel preserves CG frames and records no picker writes, and quit restores original document frames
tour-first-run-unresponsive Rendered navigation and Tidy preserve owned populated native windows while discovery is unknown; exact failure copy keeps Automatic off, then explicit recovery arranges all five windows in four CG slots
tour-rollback / tour-rollback-paused Token-scoped failed Tidy after a layout change restores three owned native documents' exact CG frames and config, holds them, then retries; paused variant starts with a hand placement
setups Without hiding, saved TextEdit/Notes columns reopen a freshly owned Notes process and restore both apps' saved CG tile positions
setups-hide With hiding on, the same restoration hides only a fresh owned Calculator process; CG confirms its disappearance and cleanup restores its visibility
spaces Explicit skip until two owned Spaces and Mission Control bindings are established
displays Skip on one display; otherwise real source/destination frames prove movement and return

Safety and evidence #

The lane records Reduce Transparency, Increase Contrast, Reduce Motion, Differentiate Without Color, dark/light appearance, voiceOverOnOffKey, and the live VoiceOver state before preflight. accessibility-settings.json and the run report retain that baseline and checkpoints before/after every scenario, after cleanup, and at lane end. Unowned drift names the setting and stops later scenarios, even if cleanup restores the value. No current scenario owns a lasting change; temporary VoiceOver sessions must return to the baseline through readback. No Peek records its branch and settings in no-peek-branch.json; dim-only requires preserved luminance-normalized edges, not just a darker image. The lane never writes an accessibility or appearance preference to exercise either branch.

Each scenario first records combined session key/flag state, releases tracked driver and VoiceOver keys, then stops its Parcel instance before discarding exactly its owned apps. The lane captures one neutral input baseline before scenario setup; preheld keys or modifiers block the lane until explicitly recovered. Caps Lock is retained. Cleanup and lane end require no held keys, no new modifiers, and unchanged Caps Lock. input-baseline.json and input-restoration.json retain those observations; scenario restoration receipts record state before release, after release, and after teardown. A leak names the held key and stops the lane even if cleanup later releases it. Live native app processes are checked against their launch receipts (including launch date), then force-terminated without requesting a graceful quit that could open save sheets. Discard retries missing lookups or incomplete metadata within its five-second deadline; a recovered full live identity issues exactly one request. Waiting for identity is not a termination request. Exit readback waits through missing metadata before or after the termination flag updates, rejecting any still-available field that differs from the launch receipt. Partial metadata never authorizes focus or termination. Completion requires the exact retained PID, a terminated retained handle, kernel absence, no live application lookup, and all-layer CG disappearance. Cleanup accepts an owned app that already quit without sending another termination request; unexpected exit during a scenario still fails closed. Directly spawned FixtureApp children use their exact retained Process handle and executable path, not the unavailable application launch date. Discard receipts include timestamped retained/current identities and PID presence before the request and during exit readback, plus start/request/finish times and native-app poll actions (waitForIdentity, requestDiscard, waitForExit, complete). An absent requestAt means no discard attempt was reached; requestAccepted records the API return, not exit proof. This closes owned documents and any print/save/open panels without saving. Before focus, an unavailable live application lookup retries for at most 500 ms only while the retained launch identity, kernel PID, and exact owned CG window agree. A fresh full identity must revalidate before activation or input; missing PID/window, changed identity, or exhausted retries still stop the lane. focus-launch-identity-<id>-<token>.json records each attempt. close-window keeps its explicit force-discard stimulus, not native window-close coverage; its request is recorded before PID disappearance is accepted. Native AX close requests retain an exact owned launch/window and neutral-input receipt; only an acknowledged close of the last owned window can authorize its app's exit. A verified requested exit and failed survivor expansion are scenario-local; input leaks, unknown disappearance, and PID reuse remain safety stops. PID and all-layer CG disappearance are verified before exact owned files and isolated profiles are removed. Browser profile cleanup also checks fresh native application identities against each launch boundary. An unclaimed matching browser or an ambiguous bundle path stops cleanup and preserves every artifact; it is never adopted or terminated from a process-list difference. browser-profile-cleanup.json retains those identities. VS Code uses a short private /tmp/parcel-e-<UUID> profile because its macOS IPC socket must fit Darwin's path limit. Its separate editor-profile-scopes.json receipt records the exact owner, device and inode; cleanup rejects replacement directories, changed permissions and symlinks. owned-cleanup.json records what remains; cleanup failures stop the lane and preserve evidence. Scenario-local verification failures, including missing fence acknowledgement, unconsumed shortcuts, or missing observed effects, fail that scenario, clean up, and continue to the next one. Unknown external state, unknown foreground identity, unowned movement, and input leaks remain safety stops; later scenarios are reported as not run, never as failed feature proofs. Existing app windows are ignored by bundle rules; owned documents are matched by a unique title token. Documents open through Launch Services in fresh instances, with saved window restoration disabled. Ownership comes from that request's returned process, checked against the requested bundle and pre-existing PIDs. Finder folders open with open <owned-folder>; cleanup closes only the new CG ID through AX and never quits Finder. Apps with shared native state, including Safari, skip if already running. A fresh browser process can still resize an existing browser window during teardown; a launch receipt alone does not isolate that state. No user documents are edited or saved. If a fresh process also has auxiliary CG windows, AX standard-window identity narrows the candidates. Two standard windows remain ambiguous; geometry and three-poll convergence tolerances are unchanged. Role-probe receipts are retained in standard-window-identities-<pid>.json.

The socket-driven helper registers only ledger-owned PID/CG ID pairs, identifies the corresponding AX element at runtime, and rechecks ownership before every operation. AX calls stay on one owning thread per app with a 500 ms messaging timeout. An unrelated AX element without window identification does not hide a uniquely identified target; that unsupported candidate is recorded in driver-identification-warnings.json. Other AX failures and ambiguous identities still fail. Starting frames and pause/retile disturbances use AX, with CG readback as the only truth. No Automation grant is used. Current keyboard and mouse chords come directly from ParcelConfig's defaults table, not a separate harness defaults table. Modified input uses balanced modifier key-down/up pairs and verifies released key/button state. Tab View holds modifiers only within one bounded driver request; minimize uses AX on a registered owned window and verifies the attribute before checking window-server metadata. Held unowned modifiers block injection; Caps Lock is preserved rather than toggled. Before every key-down and drag event, the driver verifies the active unlocked console and exact foreground AX/CG identity. Only registered test windows and the matching Parcel bundle's panel may receive input. A tail event fence sinks escaped synthetic keys before document delivery and acknowledges a zero-delta scroll barrier posted after key-up. Unlike pointer motion, that marker is not coalescible; it never scrolls a document. A native VoiceOver key receipt does not substitute for the barrier. Missing acknowledgement or an unconsumed shortcut fails the step. Parcel effects are still required: an upstream interception alone is not proof of success. RealitySession.expect attaches the independently observed effect to the input receipt. Another stimulus, or scenario completion, refuses an unverified effect. Expected pass-through is explicit and limited to registered FixtureApp windows; its bounded native keyboard recorder supplies the receipt. input-audit.json and the run report retain every key/drag command, target, and driver outcome. Ordinary key requests cannot press modifier keys, Command-P, or Command-F5. Drags require a registered PID/CG ID, start away from the centered document proxy, and carry native movement metadata. The owning app thread verifies the actual AX hit element's PID and window ID plus the CG owner/frame before mouse-down. Full-display system canvases are not treated as full-display input regions. Unknown or unowned native hits still stop the drag. driver-drag-frames.json records the source's CG bounds before mouse-up, independently of the final exchange assertion. Always Float reopens the same document under a new CG ID; a different title is not a match for an exact title rule.

Tab View rows refuse a locked or inactive console before scenario setup, and recheck before posting input. Normal selection, ignored-window, and latency rows require VoiceOver off; they skip rather than change an existing session. PARCEL_REALITY_VOICEOVER=1 explicitly owns a temporary VoiceOver session only when VoiceOver starts off, then restores it. This proves native foreground routing, not spoken output or the physical Caps Lock modifier; those remain owner checks.

The latency row brackets input dispatch with Tab View key to frame signposts and ends at the first panel display link after drawing and flushing Core Animation. key-to-first-frame.json retains 30 raw samples and nearest-rank p50/p95. The original CG key timestamp includes event delivery delay; offscreen bitmap timing and orderFront return time are not substitutes. This endpoint is a display-link presentation boundary, not a measurement of physical screen photons.

The oracle uses CGWindowListCopyWindowInfo layer 0, numeric metadata only, plus NSScreen.visibleFrame. It never reads window names, screen pixels, Parcel's model, or query output to decide frame success. Frames must converge for three polls. Retile preserves each owned ID's column rank from before the disturbance; app-opening order is not tile order. Size shortcuts track the CG-observed leading tile (expanded tile for Accordion), not the first opened document. Both baselines stay in the artifacts. Terminal's accepted resize steps are read through AX or explicitly inferred from CG-observed resize probes before Parcel launches. The allowance is one increment inside the tile only; even one point of overflow fails. All-layer CG metadata is corroboration for visual rows; opt-in driver pixels remain their visual oracle. Pre-existing window frames are checked for accidental movement; any change stops the run.

Recovery rows enable only the existing token-scoped test hooks in their own Parcel launch. Inherited E2E switches are cleared. Recovery hooks use a UUID separate from document title tokens, with an owned preference domain removed on cleanup. phantom-gap closes an exact owned window without terminating its app and requires a product dropped-destroy receipt matching the token, PID and CG ID. A missing receipt fails the prerequisite, never skips. Earlier event-driven repair is a pass only after the same exact configured-gap CG columns converge; it is recorded separately from wake-triggered recovery. Every run acknowledges wake and rechecks those frames. Query output describes membership, never proves geometry or recovery. clean-space-sleep needs no Screen Recording: it checks CG surfaces through sleep and receipt-acknowledged wake, the kept-off contract, and explicit re-enable. Opt-in pixels remain supplemental. It sends no system sleep or lock request. Physical sleep and owned native tab/Secure Input actuators remain separate checks; unsupported rows skip before opening apps.

app-minimum-stack probes each fresh Safari, Notes, and System Settings window twice before Parcel starts. It uses bounded isolated reserved edges only when the measured widths establish room for two tiles but not three. Existing app instances or an unsuitable display skip; unstable minimum refusal readback fails. shortcuts-off first requires each default chord to reach an owned FixtureApp before Parcel starts, then checks startup and reload delivery. Unknown upstream interception fails closed and is reported as a prerequisite, not product failure. Native FixtureApp key receipts remain mandatory because document-app pass-through is forbidden. Its off-state frames are sampled for a full second after every chord, not just three convergence polls.

Each scenario retains its ownership ledger, real frames, expected conditions, and poll history. Failures also retain the four prcl query --json resources, diagnostics, and the preceding 30 seconds of unified logs. Command stdout/stderr and failed artifact captures remain visible. A setup failure is not proof that the downstream feature is broken; its action did not run. Relaunch memory closes and reopens the same owned documents to test changed window IDs without Automation. Both setup rows skip if Notes is already running or an existing TextEdit instance is hidden. setups saves with prcl setup --json save NAME --no-hide; setups-hide omits that flag and requires a fresh exclusive Calculator process. A scenario-local ignore rule excludes Calculator from management; its default floating classification would otherwise include it in the saved setup. The isolated catalog must retain the exact expected hiding setting and only TextEdit/Notes membership, so Calculator stays outside the saved tiles. Both rows discard only their original ledger-owned Notes process and change TextEdit's layout/frame. prcl setup --json open NAME must return exactly one actual launch-request receipt for Notes. The harness checks the requested and live bundle paths, PID, launch date, pre-open process baseline, and all previously owned PIDs before claiming that process; it rechecks identity before registering its fresh window. Missing, stale, ambiguous, or mismatched provenance stops the lane without adopting or terminating an unowned process. Saved and restored tile positions come only from CG readback; unrelated app visibility must remain unchanged, including on cleanup after a failed scenario.

Every Parcel launch overrides PARCEL_REALITY_SETUP_HIDE_ALLOWLIST with JSON [{"pid":123,"launchDate":1234567890.5}]: normally [], or exactly the fresh ledger-owned Calculator's PID and Unix launch timestamp for setups-hide. A plain PID cannot authorize hiding after PID reuse. The compile-gated reality runtime refuses missing or malformed allowlists before hiding; ordinary builds do not use this test restriction. The harness never lists unrelated user apps. Calculator must first be visibly unchanged at its native CG frame. After setup opening, both its revalidated isHidden property and absence of onscreen layer-0 CG windows must converge for three polls while TextEdit/Notes occupy their saved columns. Undo must then restore Calculator at its original CG frame and move TextEdit out of its saved column, without changing unrelated app visibility. Cleanup first stops Parcel, then requests unhide only for that exact owned launch identity and confirms the original CG window/frame over three polls within 500 ms before normal owned-process discard. It never unhides an unrelated app to repair a safety violation. setup-hide-allowlist.json, setup-owned-hidden-readback.json, setup-hidden-cg-windows.json, and setup-owned-visibility-restoration.json and setup-undo-cg-frames.json retain evidence. The Calculator row checks hide and Undo-driven unhide, not removal of a previously tiled app; rollback/cancellation remain separate behavioral checks.

Each Parcel launch receives PARCEL_SETUPS_PATH pointing to its scenario's setups.json, never the production catalog.

Every scenario uses a new UUID preference suite and a private parcel-reality-<UUID> state directory under its evidence directory. parcel.toml, workspace memory, minimum sizes, learned rule-to-Space moves, Activity and Setups all stay there. The debug product requires both --reality-isolated and a valid owned directory/token before starting; missing arguments, malformed isolation, redirected files and shared files fail closed. Ordinary builds reject this launch mode rather than falling back to real state. Host-only driver launches have their own private directory and explicit host argument; they never initialize localization/preferences or the product runtime.

config-reload atomically edits only that owned parcel.toml. The real filesystem watcher still performs each reload, including returns to earlier values; production configuration is neither read nor backed up. Only the explicitly selected real-desktop-first-run scenario backs up, resets, and restores production state; see below. Inherited product path/test overrides are removed before each product launch.

An explicit harness stop/start copies only owned regular state files and that suite's persistent domain into a fresh UUID directory/suite/config path. The product-driven language restart intentionally retains its current owned scope to check saved-language persistence; its helper validates isolation before readiness and before replacement, and preserves the isolated launch argument. storage-launch-*.json records scopes; storage-cleanup.json records removal of all owned suites after Parcel and its driver host stop. Owned state files remain as private evidence. Created-window history stays in created-windows.json.

cap-stack covers automatic slot refill after closing singleton anchors, and relaunch-memory covers partial identity restoration of overflow members. Neither claims to reproduce an unknown historical event sequence or prove wide-minimum incremental-layout rescue; that separate mechanism still needs a native fitting check. First-launch/replayed-tour fixture write counters live in the fixture tour e2e suite. tour-first-run-unresponsive separately exercises the actual first-run tour with four owned native windows and a FixtureApp child registered before SIGSTOP. Kernel PID, parent, executable and stopped-state readback prove that child cannot answer AX throughout startup and Tidy; cleanup kills the exact retained child. The external driver presses allowlisted rendered tour controls in the exact owned Parcel launch and visible window. An AX receipt is not geometry proof. Unknown discovery must fail before writing, with unchanged-window safety copy; after explicit owned-child recovery, CG must fill four slots with one stack and Terminal's measured resize increment contained inside its slot. Startup IPC, Finder contents and all original/final frames remain in the artifacts.

Native tour captures use ScreenCaptureKit's exact owned-window filter, with existing Screen Recording and PARCEL_REALITY_SCREEN_CAPTURE=1. Light/dark changes are app-local and restored before continuing; system appearance is untouched. These rows do not certify pointer/keyboard traversal, spoken VoiceOver, every fault outcome, all locales, or already-running manual motion at tour entry. The Manual and replay native recipes remain compiled coverage gaps until their radio/exit-control locators are verified; default runs do not count them as passes. Replay recipes use fixture IPC begin to open the tour; repeated begin or show is not used as an observation because either can restart it.

If teardown leaves one owned Finder window, run mise run reality -- --recover-owned build/reality/<run>/app-finder. Recovery accepts exactly one active Finder entry from this worktree's ownership ledger, rechecks the PID/CG ID, and records disappearance plus recovery.json. It never quits Finder or resets Parcel state. Missing, broad, or outside ledgers fail.

Motion-speed checks and key recovery require verified ownership of the shared screen lock and an active, unlocked console. A missing scenario precondition is a visible skip for that scenario, not a reason to stop later scenarios. Any external screen-availability marker is an orchestration convention, not a lane requirement.

For an explicitly approved stuck virtual key, mise run reality -- --recover-key 123 opens one fresh owned FixtureApp window, posts exactly one key-up, reads the combined session state back, and closes its fixture. Physical-down keys, modifiers, and unowned targets are refused. Recovery runs alone, before capturing a new lane baseline. Its evidence stays under build/reality/key-recovery-*.

Driver regression #

After mise run reality -- --preflight-only builds the reality bundle, run the real FixtureApp check while holding the same screen lock:

Scripts/screen-lock.sh env PARCEL_E2E=1 \
  caffeinate -dimsu swift test --no-parallel \
  --filter 'realityDriver|realityHost'

Quit your running Parcel first, as for every fixture e2e run. Ordinary unit lanes still launch no apps. make e2e now builds the signed helper for debug, takes the screen lock, runs the FixtureApp proofs, then runs this owned-real-app lane. A focused e2e filter runs only its fixture checks. Release and inspectable bundles exclude the helper and its tests; use debug e2e for the full native-input proof. The separate existing-window opt-in stays manual because it can arrange windows the harness does not own; it is not used by the standard lane.

Current desktop first run #

Run this deliberately on the desktop being checked:

PARCEL_REAL_DESKTOP=1 mise run reality -- --scenario real-desktop-first-run

To reproduce a delayed, physical-button Tidy, opt into native mouse delivery and hold Ready for up to 300 seconds:

PARCEL_REAL_DESKTOP=1 PARCEL_REAL_DESKTOP_TIDY_INPUT=mouse \
  PARCEL_REAL_DESKTOP_TIDY_DELAY_SECONDS=300 \
  mise run reality -- --scenario real-desktop-first-run

PARCEL_REAL_DESKTOP_TIDY_INPUT accepts ax (default) or mouse; the delay accepts whole seconds from 0 (default) through 300. The report records both. The dwell checks cancellation and verifies that the original frames stayed unchanged before Tidy. Mouse delivery discovers the exact enabled Tidy button through AX, verifies its center hits that button in the owned frontmost Parcel window, then posts native mouse-down/up events. Its receipt records mouse delivery and the verified button frame. It never substitutes AXPress for the requested mouse click. Both paths retain the independent frame assertions and verified rollback below.

Add --no-build for repeated unchanged binaries after the first successful build; stale inputs are rejected rather than silently reusing an old app.

It is excluded from default runs, even with the opt-in set. Quit Parcel first; keep the console unlocked. The wrapper takes the shared screen lock. Accessibility must already be granted to build/Parcel.app; Screen Recording belongs to the terminal harness. Screenshots use /usr/sbin/screencapture -x, never the Parcel-hosted driver, so this scenario cannot request direct-capture consent for Parcel. It presses only Parcel's AX tour controls: Automatic, Continue, Tidy. It never posts input to, quits, or closes other apps.

Before launching the product, it records every on-screen CG window, including owner, available title, PID, frame, layer and read-only native Space memberships. It copies the production defaults domain, Application Support directory and .config/parcel into state-backup, then resets them. Redirected state paths are refused. Production defaults/configuration are used for the first-run launch; login-item registration is simulated in this debug audit so the system login item is left alone. Only read-only tour status is exposed by the additional IPC guard.

Full-screen screencapture images follow each tour step, settling and rollback. CG frames and native Space reads verify bounds, distinct tile separation and restoration within one point. Every regular, normal-size, onscreen layer-0 window on an active Space receives an independent AX role probe and prcl why receipt. Unknown AX identities remain candidates; window_not_found is recorded as unmanaged, not skipped. Except for known-floating classes identified by why, each candidate must be tiled or have an explicit application skip in the Tidy outcome. All candidate overlaps fail, including explicitly skipped windows; only members of the same tile may overlap. Any owned Parcel appUnavailable or appThread failure line within the run fails, even if the final frames fit. Fixture mode audits only owned fixture windows while protecting existing apps. The harness samples requested frames, actual CG frames and learned minimum sizes; a transient mismatch is reported as a readback, not asserted to be a refusal. Vanished windows, changed ownership, Space changes and off-screen transitions fail.

Rollback uses Parcel's normal graceful quit and verifies every original window's frame and Space. This also runs after failure or interruption. It does not use the per-window Undo command. Saved state is restored only after the owned Parcel has stopped. PARCEL_REAL_DESKTOP_KEEP_STATE=1 keeps the new state instead; it does not skip window rollback. If the process is killed before cleanup, the backup remains with manifest.json, defaults.plist (when originally present), and files-0 / files-1. Quit Parcel before restoring those paths from the manifest. Import the saved defaults with defaults import dev.vinnymac.parcel <backup>/defaults.plist, or delete that domain if hadDefaults is false. Preserve originally absent paths.

Markdown, JSON, PNGs, run-window unified logs and the state backup stay outside the repository, under the sibling private notes directory's qa/real-desktop/<timestamp>/. Treat them as private desktop evidence. The ordinary lane report links to that directory. No private notes are copied into the repo.

Fixture proof uses the same tour/readback path, eight owned fixture windows, 620/600/452/552-point minimum heights and a one-time self-adjustment. It uses isolated configuration, preferences and backup paths; existing user apps remain protected. Every fixture counter must confirm its constraint ran. Run only with /tmp/parcel-m3-free present and the console unlocked:

PARCEL_REAL_DESKTOP=1 PARCEL_REAL_DESKTOP_FIXTURES=1 \
  mise run reality -- --scenario real-desktop-first-run

Add PARCEL_REAL_DESKTOP_INJECT_UNMANAGED=1 for negative proof. It creates a ninth standard fixture window outside the isolated title rule; ordinary membership/overlap assertions must make that run fail. Injection is refused without fixture mode and the sentinel. It never targets a real app.

The report starts with tiled/floating/unmanaged counts, tile member IDs, size refusal receipts with final CG frames, and sampled Parcel notices/prompts. Untitled system prompts still need manual screenshot review; the report does not claim continuous notification observation.

A private JSON array of competing utility bundle IDs can live at qa/real-desktop/window-manager-bundle-ids.json in the private notes directory, or set PARCEL_REAL_DESKTOP_MANAGER_BUNDLE_IDS to an absolute JSON file path. Matches are noted without changing or quitting those apps. Without a list, detection is explicitly incomplete; all running bundle IDs are retained privately. Never put that list or utility names in this repository.

The fixture variant proves the harness, not success on the user's actual desktop.

tour-simultaneous-launch starts three owned FixtureApp processes alongside Parcel, presses the rendered first-run Tidy control, and requires every window to fill a distinct column with CG frame readback. tour-native-automatic checks the same three-window arrangement with fixtures already running before Parcel launches.