Infrastructure: Desktop driver improvements for workload hosting, lifecycle, and agent orchestration #4435

Current status - 2026-11-07

PR #4463 integrates F2/F3/F4/F5 implementation and the F15 Windows follow-up. F1, F7, F8, and F12 implementation is already merged. Readiness for review is not completion of the full desktop program, and the acceptance-incomplete issues remain open.

The committed qualification ledger records Windows Fabric 21 Pass, 2 Partial, 1 Fail and Win32 Paper 21 Pass, 3 Partial, with per-probe source revisions, failed attempts, run IDs and cleanup. macOS's latest recorded combined-candidate run remains at a19fd3e1 (Fabric 4 Pass/5 Partial/15 Not run; Paper 2 Pass/2 Partial/20 Not run). These are historical endpoint records, not requalification of the new main merge.

Remaining work has explicit owners:

• Infrastructure: Live-qualify the desktop driver and MCP foundation on macOS, Windows, and Win32 #4441: Windows physical foreground/input failure, launch-capable discovery, full interactive/environment/capture qualification, macOS descriptor gaps, and missing Windows/Paper discovery/text/latency measurements.
• Infrastructure: Settle Storybook story-provider cancellation and reconnect epochs #4437: Win32 fresh-preview lost-context fencing, separately registered secondary windows on both Windows endpoints, macOS cancellation/fault coverage, and explicit relaunch rather than transparent reconnect.
• Infrastructure: Implement settled desktop lifecycle supervision and fenced ownership records #4442 / Infrastructure: Add owned-process lifelines and typed desktop service readiness #4444: retained failed-cleanup claims, exact-resource/operator reconciliation, remaining macOS survivor evidence, and no automatic reclaim.
• Infrastructure: Tighten Storybook manifest provenance and native helper trust handoff #4445 / Infrastructure: Implement neutral macOS desktop application ownership and identity recovery #4446 / Infrastructure: Implement neutral Windows desktop application ownership and containment #4447 / Infrastructure: Convert Storybook lifecycle takeover into desktop-test resource contributions #4449: manifest trust and nonce separation, neutral native ownership/containment, and replacing Storybook's transitional lifecycle takeover.
• Infrastructure: Add scoped runner grants and drain-confirmed desktop controller handoff #4448 / Infrastructure: Add the generalized desktop-mcp management facet #4450: drain-confirmed MCP/WDIO handoff and bounded management tools. Cross-connection resume and automatic mutation replay are not supported.
• Infrastructure: Qualify desktop lifecycle failure paths and maintain a support matrix #4451, 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: support/reliability baseline, production/signing gates, capture fidelity and authoritative native CI. Hosted input/capture skips are not passes.
• Infrastructure: Enforce session input policy and attribute delivered input mechanisms #4467 (F16): driver-enforced session input policy and delivered-input mechanism receipts. It follows input-selection Part 1 (Desktop testing: declare and select WDIO cases by input lane, platform and scope #4464, merged; Desktop testing: migrate stories and split CI input lanes #4466, in review) and shares driver route files with Desktop driver: typed resources, process lifelines, story lifetimes, exclusive agent ingress, and native qualification runbook #4463.

Protected story args remain intentionally refused; non-agent smoke remains explicitly legacy/unprotected. New input-lane declarations from merged #4464 do not erase earlier failures or qualify a disabled physical lane.

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-test is the application-neutral workload host and composition root, for one-shot CI runs and the long-lived serve host 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-driver stays 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-mcp only when real management tools land (F13), keeping a driver-only mode.
• storybook-desktop provides optional catalog, channel, context, and CSF runner integration; its full CLI lifecycle takeover is transitional. storybook-desktop-runtime stays 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:

• 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 implementation is merged; the current landing gate is the F2/F3 integration in #4463, followed by F6 and F9.

Waves of parallel work

F16 #4467 sits outside these waves. It starts once input-selection Part 1 (#4466) lands, and apart from the shared driver files below it does not depend on F2-F13.

Shared-file scheduling

These are scheduling constraints, not functional dependencies:

• desktop-test/src/supervisor.ts, integration.ts, and config.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.ts and grant routing: drain (F11), exit and identity (F10), attenuation (F12), and session input policy (F16) share an integration owner.
• desktop-driver/src/server/createDesktopDriverServer.ts element and Actions routes, and operations/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 touch neighboring lines. Keep both sets of edits surgical, and whichever lands second rebases.
• 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.

The blocked issues carry Status: Blocked; their native GitHub blocked-by relationships retain the active prerequisites above (and any already-closed historical prerequisites). F3/F5 can co-land with their prerequisite in #4463. Later-phase/optional gates are not promoted into global hard blockers.

Decision gates

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, and yarn test, then yarn clean-lage-cache and yarn lage buildci, plus yarn lage test-links for 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.md in packages/agentic/desktop-driver, packages/agentic/desktop-test, and packages/agentic/desktop-driver-mcp.
• Retired plan: driver-next.md at 0569e1b86, 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: Reject all-skipped WDIO runs as completed coverage #4342 (all-skipped WDIO runs), Infrastructure: Qualify Windows/Win32 capture fidelity and provenance #4348 (capture qualification), Infrastructure: Qualify and require native Storybook CI coverage #4349 (required native CI), and input selection Part 1: 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).