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.