Repository navigation
Description
Current status - 2026-11-16
Implementation for F1-F8, F10-M, F10-W, F11 (generic handoff), F12 and F16 is merged, and those issues are closed. The PRs are:
- F1: Unify desktop driver-service composition and wire durable recovery #4455
- F2-F5: Desktop driver: typed resources, process lifelines, story lifetimes, exclusive agent ingress, and native qualification runbook #4463
- F6: Tighten Storybook manifest provenance and credential isolation #4490
- F7: Enforce application-neutral desktop package boundaries #4454
- F8: Add bounded authorized persisted desktop run queries #4457
- F10-M: Add neutral macOS application ownership with exact workload identity #4492 (macOS evidence in Record permission-enabled macOS evidence and qualification gaps #4493)
- F10-W: feat(desktop-test): qualify Windows application ownership and containment #4494 (Windows evidence in fix: qualify Windows activation and Win32 secondary content windows #4498; Job Object containment first landed in Qualify Windows desktop-driver ownership and physical input #4469)
- F11: Add scoped attach-only runner grants and drain-confirmed desktop handoff #4491 (generic attach-only handoff)
- F12: Isolate MCP connection authority and await descendant grant drains #4456
- F16: Desktop testing: enforce session input policy #4468 (macOS physical-input postconditions and an advisory physical CI lane followed in Fix macOS physical-input postconditions and add an advisory physical CI lane #4500)
Also merged: input-lane selection and story migration (#4464, #4466), logging (#4470), direct story selection and per-case E2E time (#4496), Windows activation refusal and Win32 secondary popups (#4498), and the react-native-macos Fabric backport (#4499). Closing the implementation issues does not complete the desktop program: native qualification is partial and per endpoint, and Storybook's lifecycle takeover is still in place.
Remaining work has explicit owners:
- F15 Infrastructure: Live-qualify the desktop driver and MCP foundation on macOS, Windows, and Win32 #4441 (open): partial native qualification; also carries the remaining F1-F5 and F16 native evidence. Per-run evidence is in the PR descriptions (for example Record permission-enabled macOS evidence and qualification gaps #4493 for permission-enabled macOS partial qualification, fix: qualify Windows activation and Win32 secondary content windows #4498 for Windows, Fix macOS physical-input postconditions and add an advisory physical CI lane #4500 for macOS physical input). macOS Fabric and Paper still need a single-revision requalification, and Windows secondary-window and broader interactive/capture subcases, console Ctrl+C settlement and strict native clear remain open. Each package's
references/current-status.mdkeeps the latest result per endpoint with a link; historical results do not qualify a later revision. - F9 Infrastructure: Convert Storybook lifecycle takeover into desktop-test resource contributions #4449 (open, ready; unblocked by Tighten Storybook manifest provenance and credential isolation #4490): replaces Storybook's transitional lifecycle takeover, then enables the Storybook runner handoff, the retained supervisor-launched application option, and relocation of the macOS attach-lease duties.
- F13 Infrastructure: Add the generalized desktop-mcp management facet #4450 (open, ready; unblocked by Add scoped attach-only runner grants and drain-confirmed desktop handoff #4491): bounded management tools. The first task is the reviewed transport and scope decision. Cross-connection resume and automatic mutation replay are not supported.
- F14 Infrastructure: Qualify desktop lifecycle failure paths and maintain a support matrix #4451 (open, blocked by F15 Infrastructure: Live-qualify the desktop driver and MCP foundation on macOS, Windows, and Win32 #4441): support/reliability baseline, including the serialized
--input allrun moved from F16, ownership reliability cases from Add neutral macOS application ownership with exact workload identity #4492/feat(desktop-test): qualify Windows application ownership and containment #4494, and the unsupported automatic-reclaim gate. - Infrastructure: Complete Desktop Driver production release qualification #4345, Infrastructure: Qualify Windows/Win32 capture fidelity and provenance #4348 and Infrastructure: Qualify and require native Storybook CI coverage #4349: production/signing gates, capture fidelity, and authoritative native CI. Infrastructure: Qualify and require native Storybook CI coverage #4349 also covers the managed macOS input lanes moved from F16. Hosted input/capture skips are not passes.
Protected story args remain intentionally refused, and non-agent smoke remains explicitly legacy/unprotected. Failed-cleanup claims stay fenced and need exact-resource/operator reconciliation; nothing reclaims them automatically.
Goal
Evolve the desktop automation packages (desktop-driver, desktop-test, desktop-driver-mcp, storybook-desktop, and storybook-desktop-runtime) so standalone desktop applications and Storybook applications share one workload and resource owner, one native execution authority, and one bounded agent interface, with reliable recovery, verified ownership, and per-endpoint evidence. The desktop layers must remain usable without Storybook, and everything must work well when Storybook is connected.
Part of #4275. The foundation landed in #4434: MCP lifetime safety, truthful contracts and package status references, and bounded fail-closed safeguards. The sub-issues below track the remaining work.
Approved architecture
A dual-model architecture review compared three approaches. Approach A was approved.
desktop-testis the application-neutral workload host and composition root, for one-shot CI runs and the long-livedservehost alike. Storybook contributes resources and context; WDIO and CSF contribute workload runners. The channel/driver child can remain a supervised child process: one resource owner does not require one process.desktop-driverstays the native execution authority: hosts, targets, sessions, operations, references, settlement, and quarantine. It has no lifecycle, Storybook, or React imports.- The MCP adapter is a verified client. It never evaluates config, launches services, builds helpers, or accepts commands, paths, environment values, grants, or URLs from the model. It is renamed
desktop-mcponly when real management tools land (F13), keeping a driver-only mode. storybook-desktopprovides optional catalog, channel, context, and CSF runner integration; its full CLI lifecycle takeover is transitional.storybook-desktop-runtimestays on-device only, with no Node harness dependency.- Contributions are static and typed (launch, Metro or other resources, Storybook, WDIO/CSF runners, driver service). No dynamic plugin loader, coordinator package, or per-user daemon is added until a decision gate below is met.
Alternatives considered and deferred:
- B. Extract a dedicated coordinator package with typed plugins. Revisit when a second independent production consumer appears, or when lifecycle dependencies conflict with the harness's WDIO and reporting dependency profile.
- C. Federated, protocol-first controllers. Revisit only when independent deployment is a real requirement.
- Rejected: making the MCP adapter a supervisor, or moving app, Metro, or test lifecycle into the driver because it already has a listener.
Design invariants
Every sub-issue must keep these identities and lifetimes distinct:
| Class | Authority and release rule |
|---|---|
| Workload claim | Supervisor. Release only after resource and effect accounting; otherwise retain a fenced recovery state. |
| Resource handle | Recorded owner. Owned and borrowed are distinct; never stop or adopt borrowed resources implicitly. |
| Service identity and grant | Verified service incarnation and attenuated permission scope; invalidated on replacement or revocation. |
| Target reservation and controller session | Driver. One session per registered target, retained through acquisition, drain, and settlement. |
| Application ownership | Session, supervisor, or external launcher. Exact process incarnation and causal ownership determine cleanup. |
| Physical input turn | Native lock that serializes settled input across processes. Not an application or controller reservation. |
| Settlement and quarantine record | Driver plus trusted durable storage. Uncertain effects outlive transport or service death. |
| Attach credential | Exact application identity proof; never the same secret as a runtime bridge nonce. |
| Context epoch | Driver and provider agreement. Stale render messages and preview references cannot establish current readiness. |
- Readiness tiers stay separate: service ready (verified listener, descriptor published), target acquirable, application ready (the controlling session verified the app), and context ready (authenticated runtime, correlated render, verified marker). A port that answers is not application readiness.
- Handoff defaults to
busy. An explicit relinquish or preempt stops new work, awaits settlement, confirms session deletion, and invalidates references before authorizing a new runner session. Revocation callbacks are not a drain barrier. - Cancellation: before dispatch it can have no effect; after dispatch, preserve applied, rejected, or indeterminate outcomes. A response deadline is not proof of settlement.
- Reclaim: never reclaim only because a supervisor PID exited. Prove recorded resources are gone or safely recovered, reconcile unresolved effects, and handle PID reuse, concurrent reclaimers, interrupted writes, and late cleanup.
- Reconnection: reconnecting a socket never restores native session or preview state. MCP transport loss keeps deletion responsibility and never replays a mutation; a bridge reconnect starts a new authenticated epoch; Metro reuse requires reverified runtime, catalog, and config identity.
Staging plan
Dependency graph
Solid arrows are blocking prerequisites, recorded as GitHub "blocked by" relationships. Dotted arrows gate only a later phase or option of the target item.
flowchart LR
F1[F1 shared service and recovery] --> F2[F2 settled lifecycle and ledger]
F1 --> F3[F3 lifelines and typed readiness]
F2 --> F3
F2 --> F6[F6 manifest trust]
F2 --> F10M[F10-M macOS ownership]
F2 --> F10W[F10-W Windows ownership]
F1 --> F11[F11 runner handoff]
F2 --> F11
F4[F4 story epochs] --> F5[F5 controlled ingress]
F1 --> F9[F9 Storybook contributions]
F2 --> F9
F3 --> F9
F6 --> F9
F7[F7 boundary guards] --> F9
F8[F8 run queries] --> F13[F13 desktop-mcp management]
F11 --> F13
F12[F12 attenuated grants] --> F13
F15[F15 foundation qualification] --> F14[F14 support matrix]
IS[Input selection #4464 and #4466] --> F16[F16 input policy and receipts]
F16 -.->|delivered-input evidence| F14
F9 -.->|Storybook phase| F11
F10M -.->|retained app option| F11
F10W -.->|retained app option| F11
F9 -.->|Storybook facet| F13
F4 -.->|Storybook facet| F13
F5 -.->|Storybook facet| F13
The original critical path was F1, F2, F3, F6, F9, then the Storybook phases of F11 and F13. F1-F3 (#4455, #4463) and F6 (#4490) are merged, and F11 closed with its generic phase (#4491); the critical path now runs through F9, which also owns the Storybook phase of the handoff, then the Storybook facet of F13.
Waves of parallel work
| Wave | Starts when | Items that can run in parallel | Coordination |
|---|---|---|---|
| 1 | Now | F1 #4436, F4 #4437, F7 #4438, F8 #4439, F12 #4440, F15 #4441 | F12 server integration must not collide with F1 recovery exports or later F5 routes. F15 runs in parallel per OS machine. |
| 2 | F1 lands; F4 lands | F2 #4442; F5 #4443; F3 #4444 process work prepared against F1 | Only one editor of supervisor.ts at a time. F3 integrates typed handles only after F2. |
| 3 | F2 lands | F3 integration, F6 #4445, F10-M #4446, F10-W #4447, F11 #4448 generic handoff | Native backends own separate files. Order the server.cjs commits F3, F5, F6. |
| 4 | F1, F2, F3, F6, and F7 land | F9 #4449; F13 #4450 generic once F8, F11 generic, F12, and the transport decision are done | One owner for supervisor and Storybook CLI integration; no parallel wholesale CLI rewrites. |
| 5 | F9 lands (plus F4 and F5 for the facet) | F9 follow-through (Storybook runner handoff, retained-app option); F13 Storybook facet; F14 #4451 consolidation | Enable the Storybook facet only after its safety dependencies. |
F16 #4467 sat outside these waves. It landed in #4468 after input-selection Part 1 (#4464, #4466).
Waves 1-3 are delivered (F6 #4490, F10-M #4492, F10-W #4494, generic F11 #4491); F15 #4441 qualification remains open. Wave 4 is unblocked: F9 is ready, and F13 is ready with its transport and scope decision as the first task.
Shared-file scheduling
These are scheduling constraints, not functional dependencies:
desktop-test/src/supervisor.ts,integration.ts, andconfig.ts: one lifecycle integration owner. Platform contributors propose shared changes instead of editing concurrently.storybook-desktop/config/server.cjs: ordered integration commits from F1 (factory switch), F3 (lifeline and readiness), F5 (ingress), F6 (trust), then F9 (simplification).storybook-desktop/src/driver/StorybookChannelOrchestrator.ts: F4 owns epochs and cancellation; F5 applies ingress afterward.storybook-desktop/src/cli/DesktopStorybookCli.ts: F6 and F9 own their phases; later lease and handoff integration is coordinated.desktop-driver/src/server/SessionManager.tsand grant routing: drain (F11), exit and identity (F10), attenuation (F12), and session input policy (F16) share an integration owner.desktop-driver/src/server/createDesktopDriverServer.tselement and Actions routes, andoperations/act.ts: F4/F5 preview-context checks (Desktop driver: typed resources, process lifelines, story lifetimes, exclusive agent ingress, and native qualification runbook #4463) and F16 input-policy enforcement (Desktop testing: enforce session input policy #4468) have both landed on neighboring lines. Later edits must preserve both checks.- Export maps, native wire schemas, root TypeScript references, the lockfile, changesets, and aggregate guidance use coordinated commits.
- Physical-input qualification is serialized per interactive desktop; different OS machines can run in parallel.
Sub-issues
The original graph/waves above retain the design's ordering. This table records the current landing gates. A delivered prerequisite is not kept as an active blocker just because its issue retains native acceptance work.
| Item | Issue | Current status | Active blockers / later phase gates |
|---|---|---|---|
| F1 | #4436 | Closed; merged in #4455. Native evidence moved to #4441 and #4451 | None |
| F2 | #4442 | Closed; merged in #4463. Native evidence moved to #4441 and #4451 | None |
| F3 | #4444 | Closed; merged in #4463 (Windows Job Object in #4469). macOS survivors moved to #4441 | None |
| F4 | #4437 | Closed; merged in #4463. Endpoint gaps moved to #4441 | None |
| F5 | #4443 | Closed; merged in #4463. macOS ingress/manifest evidence moved to #4441 | None |
| F6 | #4445 | Closed; merged in #4490 | None |
| F7 | #4438 | Closed; merged in #4454 | None |
| F8 | #4439 | Closed; merged in #4457 | None |
| F10-M | #4446 | Closed; merged in #4492 (evidence #4493). Residual unqualified cases moved to #4441 and #4451; attach-lease relocation to #4449 | None |
| F10-W | #4447 | Closed; merged in #4494 (evidence #4498; Job Object containment first in #4469). Residual cases moved to #4441 and #4451 | None |
| F11 | #4448 | Closed; generic attach-only handoff merged in #4491. Storybook runner handoff and the retained-app option moved to #4449 | None |
| F12 | #4440 | Closed; merged in #4456 | None |
| F16 | #4467 | Closed; merged in #4468 (macOS physical-input fixes in #4500). --input all moved to #4451, managed macOS lanes to #4349, strict native clear to #4441 |
None |
| F15 | #4441 | Open; partial native qualification, also owning the F1-F5/F16 native evidence | None globally; per-case gates are in #4441 |
| F9 | #4449 | Open; ready (unblocked by #4490) | None |
| F13 | #4450 | Open; ready (unblocked by #4491); the transport and scope decision is the first task | None; Storybook facet additionally F9 (F4/F5 delivered) |
| F14 | #4451 | Open; blocked for support-baseline completion | F15 #4441; evidence collection can continue |
Only F14 carries Status: Blocked. Native GitHub blocked-by relationships keep their closed historical prerequisites along with the active ones above. Later-phase/optional gates are not promoted into global hard blockers.
Decision gates
| Decision | Default now | Evidence needed before changing it |
|---|---|---|
| Coordinator extraction | Existing host; no new package | A second independent consumer or a dependency-profile conflict |
| Management transport | Decide one listener or a verified second endpoint in F13 (first task) | Scope enforcement, incarnation and discovery, cancellation, and compatibility design |
| App survival across handoff | Preserve existing semantics; opt-in host ownership (tracked in F9 #4449) | Exact native ownership and cleanup evidence |
| Session continuity | Connection-bound; no automatic resume | A reviewed lease and grace protocol with ambiguous-response handling |
| Storybook ingress and reconnect | Gate unsupported protection; no transparent-recovery promise | Supported interception plus endpoint and renderer reconnect evidence |
| Multi-workspace concurrency | Conservative workload exclusion | Verified cross-service application claims and measured contention |
| Process co-location | Keep the supervised child | Measured benefit plus macOS responsibility and Windows containment qualification |
| Plugin generalization | Static typed contributions | A real second provider and a stable, exercised extension seam |
Validation expectations
- Each item owns its tests, owning references, changesets, and native or consumer evidence. Qualify with each item, not only at the end; F14 consolidates.
- Run focused tests while iterating, each changed package's
yarn format,yarn lint,yarn build, andyarn test, thenyarn clean-lage-cacheandyarn lage buildci, plusyarn lage test-linksfor markdown changes. - JavaScript tests and bundles do not qualify native behavior. Hosted capability skips are not passes. Report passed, failed, skipped, not run, or unsupported per endpoint and revision.
Evidence
- Foundation: Desktop driver: bounded agent operations, protected service, and MCP adapter #4434.
- Evidence policy: per-run evidence lives in pull request descriptions and issues. Each package's
references/current-status.md(desktop-driver,desktop-test,desktop-driver-mcp,storybook-desktop) keeps a status overview, stable topic sections, and only the latest result per native endpoint with a link. - Retired plan:
driver-next.mdat0569e1b86, the dual-model (GPT-6 Astra and Claude Opus 5.5) architecture review with alternatives, evidence citations, and reviewer reconciliation. - Related:
- Infrastructure: Complete Desktop Driver production release qualification #4345: driver production release qualification
- Infrastructure: Qualify Windows/Win32 capture fidelity and provenance #4348: capture qualification
- Infrastructure: Qualify and require native Storybook CI coverage #4349: required native CI, including managed macOS input lanes
- Infrastructure: Reject all-skipped WDIO runs as completed coverage #4342: all-skipped WDIO runs; closed via Desktop testing: declare and select WDIO cases by input lane, platform and scope #4464
- Input selection Part 1, both merged: Desktop testing: declare and select WDIO cases by input lane, platform and scope #4464 (declare and select) and Desktop testing: migrate stories and split CI input lanes #4466 (migrate and split lanes), plus direct story selection (Select desktop stories directly and attribute per-case E2E time #4496)
- Qualify Windows desktop-driver ownership and physical input #4469: Windows ownership and physical input
- Improve desktop-test and storybook-desktop logging output #4470: logging
- fix: qualify Windows activation and Win32 secondary content windows #4498, Backport upstream Fabric native-props synchronization to react-native-macos 0.81.9 #4499, Fix macOS physical-input postconditions and add an advisory physical CI lane #4500: Windows activation and secondary popups, react-native-macos backport, macOS physical-input fixes
Activity
4 remaining items
test(desktop): cover Windows runner and agent interruption
Attribute desktop story case timing and lifecycle observations
Record macOS activation boundaries and flashing experiment gate
Select driver-owned stories directly and cache extracted test maps pe…
Record paired desktop navigation measurements and qualification
Fix desktop extraction cache and diagnostic review findings
test(desktop): cover Windows runner and agent interruption
feat(desktop): extend exact application ownership to Windows
Add scoped attach-only runner grants and drain-confirmed desktop hand…
feat(desktop-test): qualify Windows application ownership and contain…
Select desktop stories directly and attribute per-case E2E time (#4496)
Fix macOS physical-input postconditions and add an advisory physical …
JasonVMo commentedon Nov 16, 2026
Status refresh. #4445, #4446, #4447 and #4448 are closed (#4490, #4492/#4493, #4494/#4498, #4491). Open: #4441 (partial native qualification), #4449 and #4450 (both ready,
Status: Blockedremoved), and #4451 (blocked by #4441). The sub-issues table, staging plan and evidence policy are updated. Per-run evidence lives in PR descriptions and issues; each package'sreferences/current-status.mdkeeps only the latest result per native endpoint with a link.JasonVMo commentedon Nov 19, 2026
Desktop preview review handoff — #4515
The preview targets
desktop-driver0.5.4,desktop-test0.4.0,desktop-mcp0.1.1 and the driver-only compatibility wrapper 0.1.5. Both local clean-cache builds, four fresh tarball installs, installed-source helper checks, native handoff and packed MCP qualification passed. Atce084180a, Windows Fabric physical smoke passed 121/121 callbacks and the changed Input FocusTreatment callback passed with real input on macOS Fabric, macOS Paper and Win32 Paper. #4515 records exact revisions, cleanup and prior failures. Hosted CI is rechecking5c8a51e12, which only removes the temporary plans.The preview explicitly defers full mixed Win32 Storybook crash recovery to #4441. Package follow-ups remain #4517, #4518 and #4516. #4435 remains open; this is a preview PR, not completion of the wider workstream. Version Packages #4509 was not edited and will regenerate after the source PR lands; actual versioned CI packing and post-publication smoke are still required.