Repository navigation
Description
Current status - 2026-11-09
Implementation for F1-F5, F7, F8, 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
- F7: Enforce application-neutral desktop package boundaries #4454
- F8: Add bounded authorized persisted desktop run queries #4457
- F12: Isolate MCP connection authority and await descendant grant drains #4456
- F16: Desktop testing: enforce session input policy #4468
Their remaining native acceptance evidence now lives in the open issues below, mainly F15 #4441, rather than on the implementation issues. Also merged since the last update:
- Input-lane selection and story migration (Desktop testing: declare and select WDIO cases by input lane, platform and scope #4464, Desktop testing: migrate stories and split CI input lanes #4466)
- Windows Job Object containment and connected physical-input qualification (Qualify Windows desktop-driver ownership and physical input #4469)
- Logging improvements (Improve desktop-test and storybook-desktop logging output #4470)
Closing the implementation issues does not complete the desktop program.
The committed qualification ledger records two runs:
- 2026-11-08, disconnected console: Windows Fabric 22 Pass, 1 Partial, 1 Fail; Win32 Paper 22 Pass, 2 Partial.
- Later, at
fec94cec4with the console connected: physical-input smokes passed on both endpoints (Windows Fabric 203/203, Win32 Paper 177/177), as did the real MCP physical checkbox and capture path. The matrix was not re-tallied.
macOS's latest recorded run remains at a19fd3e1 (Fabric 4 Pass/5 Partial/15 Not run; Paper 2 Pass/2 Partial/20 Not run). These are per-probe endpoint records at their own source revisions, not a requalification of the latest main.
Remaining work has explicit owners:
- F15 Infrastructure: Live-qualify the desktop driver and MCP foundation on macOS, Windows, and Win32 #4441 (also carries the remaining F1-F5 and F16 native evidence):
- Secondary windows and Win32 fresh-preview fencing
- Settlement after a console Ctrl+C
- Broader Windows interactive/environment/capture subcases
- Strict native clear
- macOS requalification
- Remaining MCP measurements and client qualification
- F6 Infrastructure: Tighten Storybook manifest provenance and native helper trust handoff #4445: manifest trust and attach-credential/bridge-nonce separation. Unblocked.
- F10-M Infrastructure: Implement neutral macOS desktop application ownership and identity recovery #4446 / F10-W Infrastructure: Implement neutral Windows desktop application ownership and containment #4447: neutral native application ownership, exit identity and containment, including cross-service exact-application exclusion. Packaged Windows launches remain
uncontainedand fenced. Unblocked. - F11 Infrastructure: Add scoped runner grants and drain-confirmed desktop controller handoff #4448: a handoff between agent-served mode and WDIO that drains in-flight work before switching (busy, relinquish, preempt). Unblocked for the generic phase.
- F9 Infrastructure: Convert Storybook lifecycle takeover into desktop-test resource contributions #4449: replaces Storybook's transitional lifecycle takeover. Blocked by F6.
- F13 Infrastructure: Add the generalized desktop-mcp management facet #4450: bounded management tools. Blocked by generic F11 and the transport/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: support/reliability baseline, including the serialized
--input allrun moved from F16. Blocked by F15. - 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 ledgers, 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 is F1, F2, F3, F6, F9, then the Storybook phases of F11 and F13. F1-F3 are merged (#4455, #4463); the critical path now runs through F6, then F9.
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) | F11 Storybook phase; 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).
The implementation items in waves 1 and 2 are delivered; F15 #4441 qualification remains open. Wave 3 (F6, F10-M, F10-W and generic F11) is now unblocked.
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 active 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, #4446/#4447 and #4451 | None |
| F2 | #4442 | Closed; merged in #4463. Native evidence moved to #4441, #4446/#4447 and #4451 | None |
| F3 | #4444 | Closed; merged in #4463 (Windows Job Object in #4469). macOS survivors moved to #4441, Windows containment to #4447 | 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 |
| F7 | #4438 | Closed; merged in #4454 | None |
| F8 | #4439 | Closed; merged in #4457 | None |
| F12 | #4440 | Closed; merged in #4456 | None |
| F16 | #4467 | Closed; merged in #4468. --input all moved to #4451, managed macOS lanes to #4349, strict native clear to #4441 |
None |
| F15 | #4441 | Open; partial native qualification, now also owning the F1-F5/F16 native evidence | None globally; per-case gates are in #4441 |
| F6 | #4445 | Open; unblocked | None; F2 contract is available |
| F10-M | #4446 | Open; unblocked | None; F2 contract is available |
| F10-W | #4447 | Open; unblocked; Job Object containment delivered in #4469 | None; F2 contract is available |
| F11 | #4448 | Open; generic handoff unblocked | None for generic handoff; Storybook phase additionally F9, retained-app option F10-M/W |
| F9 | #4449 | Blocked | F6 #4445; F1/F2/F3/F7 contracts are available |
| F13 | #4450 | Blocked | Generic F11 #4448 and reviewed transport/scope decision; Storybook facet additionally F9 (F4/F5 delivered) |
| F14 | #4451 | Blocked for support-baseline completion | F15 #4441; evidence collection can continue |
Only the still-blocked issues (F9, F13, F14) carry 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 | Scope enforcement, incarnation and discovery, cancellation, and compatibility design |
| App survival across handoff | Preserve existing semantics; opt-in host ownership | 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.
- Current status ledgers:
references/current-status.mdinpackages/agentic/desktop-driver,packages/agentic/desktop-test, andpackages/agentic/desktop-driver-mcp. - 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)
- Qualify Windows desktop-driver ownership and physical input #4469: Windows ownership and physical input
- Improve desktop-test and storybook-desktop logging output #4470: logging
Activity
1 remaining item
Retire driver-next.md in favor of tracked follow-up issues
Desktop driver: bounded agent operations, protected service, and MCP …
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)