Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Tauri Desktop Vertical Slice
Status
- Owner: Avibe core
- Target platforms: macOS and native Windows
- Mobile: deferred until the desktop shell and shared WebView constraints are proven
- Delivery strategy: a retained product scaffold, not a disposable prototype
- Integration branch: every desktop PR targets
desktop; only an owner-authorized final integration PR may targetmaster
The first credible native Windows closure is intentionally narrow:
Windows x64 + uv-managed system Python + Tauri WebView2 + Codex only + a native
C:\...workspace + authenticated loopback Controller IPC + Windows ProcessHost + pywinpty/ConPTY.
Vault, Show Runtime, askill, OpenCode, Claude, ARM64, private Python, NSIS, and signing remain product requirements, but none blocks the first D07/D12 proof.
Background
Avibe already has the right high-level split for a desktop application:
- the React Workbench is the primary user interface;
- the Python service owns agents, sessions, local state, Show Pages, Vault orchestration, terminal transport, and IM integrations;
- the browser talks to the service over loopback HTTP, SSE, and WebSocket.
The first desktop release should preserve this split. Tauri should own native application lifecycle and distribution, while the existing Avibe service remains the single business-logic and data authority.
Windows is a first-class native target. WSL remains a compatibility option, not the architecture or the default path.
Goals
- Prove that the complete Workbench runs reliably inside Tauri on macOS WKWebView and Windows WebView2.
- Start or adopt one local Avibe Runtime without creating duplicate daemons.
- Keep long-running Avibe work independent from the desktop window lifecycle.
- Make native Windows capable of running a real agent session without invoking WSL.
- Preserve Show Pages, Vault, Monaco, xterm, files, clipboard, drag and drop, HTTP streaming, and WebSocket behavior.
- Keep the shell replaceable: if Tauri fails the gate, Electron can replace the native shell without rewriting Workbench or Runtime.
Non-Goals
- Rewriting Workbench in Rust, Swift, Kotlin, or native widgets.
- Moving business logic or persistent data into Tauri commands.
- Bundling a private Python Runtime in the first host-capability milestone.
- Implementing auto-update before startup, lifecycle, and packaging are stable.
- Removing or weakening Show Pages to reduce WebView surface area.
- Delivering mobile applications in this milestone.
- Reproducing every tmux persistence feature on Windows before ConPTY is proven.
- Making Vault, Show Runtime, askill, OpenCode, Claude, ARM64, private Python, NSIS, or signing prerequisites for the first native Windows Agent/terminal closure.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Tauri Desktop Shell │
│ │
│ bootstrap/error UI window/tray single instance │
│ Runtime discovery process start native integration │
└──────────────────────────────┬──────────────────────────────┘
│ loopback URL
▼
┌─────────────────────────────────────────────────────────────┐
│ Existing React Workbench │
│ │
│ Chat Sessions Show Pages Vault Monaco xterm Settings │
└──────────────────────────────┬──────────────────────────────┘
│ HTTP + SSE + WebSocket
▼
┌─────────────────────────────────────────────────────────────┐
│ Avibe Python Runtime │
│ │
│ Agents Harness state files terminal IM Show Runtime │
└─────────────────────────────────────────────────────────────┘
Ownership Rules
| Concern | Owner | Contract |
|---|---|---|
| Native window, tray, single instance | Tauri shell | No business state |
| Runtime endpoint discovery | Python Runtime | Versioned descriptor derived from effective UI binding |
| Runtime launch | Tauri shell | Resolve installed CLI, probe first, start second, adopt after readiness |
| Workbench UI and navigation | React Workbench | Browser-compatible HTTP origin |
| Sessions, agents, tasks, watches | Python Runtime | Existing APIs and durable state |
| Show Pages | Python and Show Runtime | Full capability preserved |
| Terminal bytes and resize events | Runtime platform adapter | Existing WebSocket protocol |
| Credentials and custody | Vault / platform adapter | Tauri never receives secret values |
| Long-running background work | Python Runtime / Harness | Survives window close and shell crash |
Security Boundary
The Workbench loads from a dedicated loopback Avibe origin. Tauri commands are available only to the bootstrap shell code that needs native lifecycle operations. Normal Workbench routes and Show Page content must not inherit filesystem, shell, process, or unrestricted Tauri capabilities.
This boundary preserves Show Pages as a core feature without turning page content into native application code.
M1 uses one WebView in two phases:
- the bundled Tauri-origin bootstrap page may call only the fixed, argument-free Runtime bootstrap and installation-help commands;
- after readiness, Rust navigates that WebView to the loopback Workbench.
The loopback origin is never listed in a Tauri capability remote.urls rule.
Every application command also verifies that its caller is still on the bundled
bootstrap origin. Single-instance, focus, window, and process lifecycle remain
Rust-owned after navigation; Workbench does not need Tauri IPC.
M1 has no privileged postMessage bridge. If the Workbench later needs a
native operation, it must not be enabled by adding the loopback origin to
remote.urls. That change requires a separate architecture contract: a
Tauri-origin privileged surface, a narrow schema-validated message protocol,
and exact checks of message source and origin before any native command runs.
Agent-authored content is never an allowed bridge caller.
The Python server's existing Host-header validation is a frozen security invariant, but it must preserve Avibe's authenticated remote-access product:
- the desktop loopback listener grants local trust only when the request has
both a loopback peer and a syntactic loopback Host (
localhostor an address parsed byipaddressas loopback); - an untrusted forwarded header must prevent local classification;
- a non-loopback Host must enter the configured remote-auth path or fail closed; it must never inherit local trust merely because its peer is loopback.
The existing configured setup-host trust and trusted public-origin exceptions remain valid for their matching LAN, Tailscale, and Avibe Cloud request paths. The desktop contract adds a stricter loopback path; it does not redefine every server request as loopback-only.
The named contract
test_desktop_runtime_host_header_contract_rejects_non_loopback_local_trust
must cover the loopback-peer/arbitrary-Host, remote-peer/loopback-Host, malformed
127.* hostname, and untrusted-forwarding cases. The desktop shell is stricter:
it navigates only to the exact literal IP whose readiness probe succeeded
(127.0.0.1 or [::1]), never the hostname localhost.
Show Pages keep their existing product capability. D04 must include a negative assertion that Show Page JavaScript cannot invoke a Tauri command. Existing same-origin Show Page access remains a browser/server risk, but it cannot cross the native boundary because neither the Workbench nor Show Page origin has Tauri capabilities.
Two pre-existing server hardening items remain explicit:
/api/eventscurrently has no explicit Origin gate. Browser same-origin/CORS enforcement prevents a cross-origin page from reading the stream in the current deployment, so this is not equivalent to granting native capability or demonstrated data exfiltration. Before desktop security sign-off, add exact-Origin validation or a short-lived connection token issued through an authenticated same-origin mutation, and test the chosen contract./p/{share_id}/__vite_hmrmust validate the WebSocket Origin against the public page's effective origin. Public visibility is not authorization to accept a cross-site WebSocket. This hardening must retain public Show Page HMR.
Neither item is solved by disabling or reducing Show Pages, and neither is allowed to support a claim that the desktop release adds no attack surface until its focused server PR has landed.
Runtime Discovery
M1 assumes an installed vibe executable and resolves it in this order:
- the explicit development/test
AVIBE_DESKTOP_VIBE_PATHoverride; - the inherited process
PATH; UV_TOOL_BIN_DIRwhen configured;- uv's default
$HOME/.local/binor%USERPROFILE%\.local\bin; - platform fallbacks:
$HOME/bin,$HOME/.cargo/bin,/opt/homebrew/bin, and/usr/local/binon macOS/POSIX, and%APPDATA%\Python\Scriptson Windows; - the app-private Runtime path only after M3 introduces one.
Candidates resolve directly to vibe on macOS and vibe.exe on Windows.
Failure produces a retryable bootstrap error with an install-docs action; it
never falls back to a shell command or exposes candidate paths to the WebView.
A macOS application bundle cannot assume the interactive shell's rc files were
loaded.
vibe start --no-open-browser is a short-lived launcher that starts or adopts
the background service and UI processes, then exits. Tauri does not retain or
kill that launcher or the daemons it creates.
Frozen Desktop Bootstrap Contract
Python, not Rust, owns the effective UI binding and desktop endpoint:
vibe desktop endpoint --jsonloads the same V2 config asvibe startand emits exactly one JSON object on stdout:{ "schema_version": 1, "origin": "http://127.0.0.1:5123" }originis produced fromeffective_ui_bind_host()andui.setup_port. It contains a literal127.0.0.1or bracketed::1address, neverlocalhost, a configured LAN/Tailscale address, a wildcard, or a public URL.The UI process always serves that origin. When the existing primary listener is bound to a specific non-loopback address, the same UI process and ASGI app add a same-port loopback listener of the matching address family. Wildcard and loopback bindings already cover loopback and do not add another socket. A second UI process or a local reverse proxy is forbidden.
The primary listener and remote-access authentication remain unchanged. Requests to the additional listener receive local trust only when both the peer and Host are syntactic loopback values.
Rust treats the descriptor as untrusted process output: stdout has a small size bound, stderr is never exposed to the WebView, the schema version must be exactly
1, there must be no unknown fields, andoriginmust pass the existing literal-loopback validator.
GET /ready is the one desktop readiness contract:
UI route reachable
AND resolve_service_owner_pid(include_starting=False) is present
AND await internal_client.health_identity() returns the Controller identity
AND the same service owner still holds the lock after that health check
It returns
200 {"schema_version": 1, "product": "avibe", "ready": true} only when all
conditions hold. A desktop-managed Runtime adds its full archive SHA-256 as
desktop_runtime_id; an external installed Runtime omits that field. The
Controller process owns this identity in /internal/health; the UI only
forwards the validated Controller value after the same service owner survives
the probe. It never derives the identity from the UI process environment. The
exact product marker prevents accidental adoption of an unrelated service that
happens to occupy the configured loopback port. It returns
503 {"schema_version": 1, "product": "avibe", "ready": false, "code": ...}
with one of service_starting, service_unavailable,
controller_unavailable, ownership_lost, or owner_probe_failed otherwise.
IM login, Agent credentials, terminal capability, Vault, and Show Runtime are
feature states, not shell readiness gates. /health proves only the UI HTTP
process; /status cannot prove that Controller initialization and control IPC
completed. Neither is sufficient for adoption or navigation.
The first implementation uses a small state machine:
probing -> ready
-> starting -> ready
-> failed
probing -> failed
The shell produces these states:
| Field | Producer | Consumer | Meaning |
|---|---|---|---|
phase |
Rust Runtime host | Bootstrap UI | probing, starting, ready, or failed |
origin |
Python descriptor, validated by Rust | WebView navigation | Validated loopback HTTP origin |
attempt |
Rust Runtime host | Bootstrap UI | Current readiness probe attempt |
notice |
Rust Runtime host | Bootstrap UI | Typed code plus bounded typed arguments; never display prose |
retryable |
Rust Runtime host | Bootstrap UI | Whether the user may retry safely |
Behavior:
- Resolve one installed
vibeexecutable. - Unless the explicit development/test origin override is set, execute
vibe desktop endpoint --jsondirectly and validate its descriptor. - Accept only literal
http://127.0.0.1orhttp://[::1]loopback origins. - Probe
GET /ready. - If ready, adopt the existing Runtime and navigate to Workbench.
- If absent, launch the same executable with
vibe start --no-open-browser, without a shell. - Poll
/readywith a bounded timeout. - Navigate only after a successful combined readiness response.
- After navigation, Rust probes
/readyevery two seconds. A single transient failure does nothing. After three consecutive failures, Rust returns the same WebView to the bundled bootstrap origin, releases only its stale launch-attempt guard, and runs the normal probe/adopt/launch state machine. It never stops the Runtime. - Never kill an adopted Runtime when a window closes or the shell exits.
- Never expose command strings, environment variables, or secret-bearing process output to the WebView.
The initial shell assumes vibe is installed. Private Runtime bundling belongs
to the distribution milestone.
Bootstrap copy is represented by stable message codes and localized in bundled offline English and Chinese catalogs selected from the WebView locale. Rust does not emit user-facing prose, and the bootstrap does not depend on the loopback Workbench being reachable to load translations.
The exact notice shape is
{"code": "<enum>", "seconds": <optional positive integer>}. M1 freezes the
codes probing, adopted, starting, ready, invalid_origin,
runtime_not_found, runtime_discovery_failed, runtime_spawn_failed,
launcher_exited, and ready_timeout. The UI must exhaustively map them to
ui/src/i18n/en.json and ui/src/i18n/zh.json; an unknown value maps to a
localized generic failure and is never rendered as raw text. The desktop Vite
build extracts only the desktopBootstrap subtree into the offline bundle.
Locale selection uses navigator.languages (zh-* selects Chinese, all other
values fall back to English) and updates the document lang.
Native Windows Runtime Contract
Windows support must be expressed behind platform interfaces rather than
scattered os.name branches. core/platforms/__init__.py selects an
implementation once; callers depend only on the narrow protocols:
ControlIpcHost
├── PosixUnixSocketHost
└── WindowsLoopbackHost
ProcessHost
├── PosixProcessHost
└── WindowsProcessHost
TerminalHost
├── PosixPtyTmuxHost
└── WindowsConPtyHost
CredentialIpcHost
├── PosixSocketHost
└── WindowsNamedPipeHost
DependencyHost
├── PosixDependencyHost
└── WindowsDependencyHost
The interfaces preserve current product behavior while allowing different platform mechanisms:
- Controller IPC keeps its current HTTP/SSE behavior. POSIX retains the Unix
domain socket; Windows uses an ephemeral loopback listener with an atomically
written endpoint descriptor, instance nonce, and bearer credential. It does
not invent a custom named-pipe HTTP stack. The descriptor must have a
user-and-SYSTEM-only DACL even when
AVIBE_HOMEis inherited from a permissive directory; readers validate the file owner and ACL before accepting it. Startup rotates the nonce and bearer, and graceful or forced shutdown removes the descriptor. ProcessHostmodels three explicit ownership classes:DAEMON,OWNED_TREE, andADOPTABLE_DAEMON. The Runtime service is independent from Tauri; service-owned workers enter a Windows Job Object only after the service owns their lifecycle. Graceful control shutdown precedes forced whole-tree termination.- daemon launch never passes POSIX-only
start_new_sessionsemantics on Windows; Controller internal-server startup failure must make the service unhealthy, and UI restart treatsWSAEADDRINUSE(10048) as the Windows equivalent of the existing POSIX address-in-use errors. - Windows terminal sessions use ConPTY through a maintained binding and retain
the existing xterm WebSocket protocol.
TerminalServicecontinues to own session state; the host owns onlyopen,read,write,resize,wait, andclose. - Process stop/restart uses native process-tree semantics and never calls
wsl.exe. - Vault credential IPC uses a Windows named-pipe byte stream only after the matching avault CLI transport contract exists. Avibe must not invent one unilaterally.
- dependency installation resolves native PowerShell and Windows assets;
POSIX-only dependencies such as tmux return
not_applicableon Windows rather than failing startup. - paths are native Windows paths end to end;
/mnt/ctranslation is forbidden.
Milestones
M1: Tauri Host Capability
Deliver a buildable Tauri v2 shell that:
- probes and adopts an existing Runtime;
- launches an installed Runtime when absent;
- shows a compact startup/error state with retry;
- navigates the main WebView to Workbench after readiness;
- monitors combined Runtime readiness after navigation and returns to bootstrap after confirmed loss;
- prevents duplicate shell instances;
- keeps Runtime lifecycle independent from window lifecycle;
- includes unit tests for origin validation and state transitions;
- builds on macOS and Windows CI.
No updater or bundled Python is required.
M2: Native Windows Runtime Slice
The first native target is Windows x64 with a uv-managed system Python and the Codex backend. ARM64, bundled Python, Vault, Show Runtime, askill, OpenCode, and Claude do not block the first D07/D12 proof. They remain required product follow-ups; they are not removed or weakened.
Deliver the slice through six ordered contracts. A PR must not combine adjacent contracts merely because they share the Windows target:
- replace the Controller's fixed Unix-socket assumption with
ControlIpcHostwhile preserving the existing HTTP routes, SSE ordering, and authentication; - add Windows process ownership, graceful stop, and whole-tree cleanup without
making Tauri the owner of the Runtime process tree. Before this contract may
claim M2 lifecycle support,
_spawn_runtime_log_sink,spawn_background, andspawn_service_background_processinvibe/runtime.py, plus the long-lived supervisor spawn invibe/restart_supervisor.py, must useisolated_subprocess_kwargs()or the selectedProcessHost, never rawstart_new_session=True; Windows CI must execute the shared spawn abstraction tests; - complete one real Codex session in a native
C:\...workspace, including.cmd/.exeargument fidelity, streamed output, a file modification, and nowsl.exeor/mnt/path in the process lineage; - extract a
TerminalHostconformance seam around the existing POSIX PTY/tmux behavior without changing the WebSocket orTerminalViewcontract; - implement the same contract on Windows with
pywinpty>=3.0.5,<4; sys_platform == "win32"and pin the wheel inuv.lock; - follow with Vault named-pipe work across Avibe/avault, Show Runtime and dependency proofs, then private Runtime packaging, installers, signing, and ARM64.
The resulting product workflow is:
- install Avibe in Windows without WSL;
- start the service from PowerShell;
- open the Tauri Workbench;
- start one real agent backend;
- stream its output;
- read and modify a file in a
C:\...working directory; - open a ConPTY terminal, send Unicode input, resize, and interrupt;
- stop and restart cleanly without orphaning the process tree.
The first slice may omit detached terminal persistence across a full machine reboot. That behavior must be designed after ConPTY lifecycle evidence exists.
The Windows terminal implementation uses dedicated reader and writer workers,
not the shared asyncio executor. Its close path must drain or close the output
pipe before ClosePseudoConsole, which can otherwise block on older Windows
releases. The supported floor is Windows 10 version 1809; release CI installs
pywinpty wheel-only.
Vault and Show Pages remain in the desktop acceptance catalog. Their native Windows proof follows the first Agent/terminal slice because Vault requires a matching avault transport contract and Show Runtime already has Windows bundle assets but lacks a native lifecycle CI proof.
M3: Product Distribution
- macOS signed and notarized DMG;
- Windows NSIS x64 installer first, ARM64 after the x64 gate;
- app-private CPython, Avibe wheel, Node, and npm;
uvis build-time only and is not shipped or required on the user's machine; - Agent backends are detected externally first and otherwise installed lazily into app-private storage;
- versioned Runtime directories with rollback;
- uninstall preserves user data under the Avibe home;
- updater only after cold start, upgrade, rollback, and process lifecycle pass.
Self-contained Runtime contract
A Desktop product package is not allowed to resolve its primary Runtime from
the system PATH. Each architecture-specific installer embeds one immutable
runtime.zip and one runtime-manifest.json as Tauri resources. The manifest
pins and records:
- the target OS and architecture;
- the CPython and Node source URLs plus SHA-256 digests;
- the exact Avibe wheel name and SHA-256 digest;
- the archive's compressed and uncompressed sizes, entry count, SHA-256 digest, extracted-tree SHA-256 digest, and the relative Python, Node, and npm entrypoints.
Release CI builds the wheel from the same checkout and installs its
hash-locked dependencies into the pinned standalone CPython distribution.
Binary wheels are mandatory except for the explicit audited sdist allowlist in
desktop/runtime-sources.json. http-ece does not publish wheels;
claude-agent-sdk is intentionally built from its pure-Python sdist because its
platform wheels embed a Claude Code executable, which belongs to the lazy
backend lifecycle instead of the immutable Runtime. CI builds those dependencies
on the target runner. The
builder then copies native Node plus its complete npm package. The private
launch environment exports the exact Node and npm CLI paths. A fully isolated
AVIBE_HOME proves the real start --no-open-browser -> /ready -> stop
lifecycle as well as Node-driven npm execution. Source downloads and the
completed archive are both hash-verified. The package also contains the Python
distribution inventory and third-party license material.
On first launch the Rust host validates the bounded manifest and exact target, checks the archive length and SHA-256 digest, rejects path traversal, symlinks, oversized expansion, and entry-count mismatches, and extracts into a private staging directory. Only a complete install with the Python, Node, and npm entrypoints and a durable marker is atomically renamed to:
<OS application data>/runtime/<avibe-version>/<archive-sha-prefix>/ (Windows)
<OS application data>/runtime/trees.noindex/<avibe-version>/<archive-sha-prefix>/ (macOS)
On macOS the .noindex directory keeps Spotlight from importing a freshly
written tree, which otherwise evicts it from the page cache just before the
next launch hashes it (#2283). Trees that earlier releases installed directly
under runtime/ are pruned like any other superseded tree.
Every later launch recomputes the extracted file-tree digest before executing the Runtime, rejects symlinks and extra/missing files, and may install one separate repair slot from the immutable archive when the primary slot is corrupt. If both slots fail validation, startup fails closed rather than executing user-writable modified code.
The application bundle is read-only after installation. Content-addressed,
versioned directories let an update install a successor while an older daemon
is still using its files. The archive SHA-256 is passed into the private
Runtime. Its Controller returns that identity through internal health and the
UI forwards the Controller-owned value through /ready. A matching Runtime is
adopted. Before vibe start reuses an existing service, a different
desktop-managed Controller is stopped gracefully; the shell also performs this
handover when a predecessor UI is still reachable. Superseded trees are pruned
only after the successor Controller proves the expected identity. Reopening an
older package reinstalls its own immutable archive, so rollback does not depend
on retaining every historical extraction.
The shell launches the private interpreter directly as python -I -m vibe; it
supplies the exact Node and npm CLI paths plus a separate mutable backend root.
It marks the process as desktop-managed: Python package checks and in-place
vibe upgrade are disabled, while Codex, Claude Code, and OpenCode can be
installed or updated independently through the Workbench. Backend installation
invokes bundled npm through bundled Node without a shell or global prefix. The
Runtime launch itself does not invoke a shell, system Python, uv, or an
interactive shell startup file.
Development builds retain the installed-vibe resolver. A distributable build
must enable the Rust bundled-runtime feature; producing a consumer installer
without it is a release failure. desktop-self-contained-package builds the
artifacts. Every macOS tag build signs executable code inside the private
Runtime before archiving it, then the Cua Driver helper and the app, with the
Team's Developer ID under the hardened runtime; it notarizes and staples the app
and the outer DMG and verifies each pinned code identity. A tag build without
the complete Apple credential set fails. A manual build signs the same way with
the complete set and otherwise stays ad-hoc, and its .SIGNATURE names what it
produced. The manual workflow requires a SemVer input and stamps it into Tauri
metadata and artifact names. Authenticode coverage on Windows remains a tracked
release gate (#1976). Signing, notarization, and publication are separate
release gates.
The D11 clean-install gate uses a fresh VM with Python, uv, Node, npm, and all
Agent backends absent from PATH. It must prove:
- the installer completes without downloading prerequisites;
- first launch reaches Workbench and starts exactly one Runtime;
- the private Runtime answers
vibe desktop endpoint --json; - bundled Node and npm execute, Workbench loads without a backend, and one selected backend can be installed lazily without system package managers;
- closing and reopening the shell adopts the same daemon;
- a second package version installs beside the first, cuts over only after
readiness, and can roll back without changing
~/.avibe; - uninstall removes application/runtime/private-backend files but preserves
~/.avibeand external backend installations.
M4: Mobile Reassessment
Re-evaluate Tauri mobile using the proven Workbench compatibility results. Mobile work must have mobile-specific navigation, input, safe-area, keyboard, and gesture design; it is not a desktop viewport shrink.
Acceptance Scenarios
| ID | Scenario | Required evidence |
|---|---|---|
| D01 | Cold launch with no Runtime | one Runtime starts and Workbench loads |
| D02 | Launch with existing Runtime | Runtime is adopted; no duplicate daemon |
| D03 | Streaming chat | SSE streams and reconnects after transient loss |
| D04 | Show Page | page renders, hot reloads, and remains interactive |
| D05 | Files | upload, download, drag/drop, and clipboard work |
| D06 | Vault | WebAuthn/PRF flow completes without secrets entering Tauri |
| D07 | Terminal | PTY/tmux on macOS and ConPTY on Windows use the same UI protocol |
| D08 | Sleep and wake | UI reconnects without duplicate Runtime |
| D09 | Window lifecycle | close/reopen and single-instance behavior are deterministic |
| D10 | Runtime crash | after consecutive /ready failures, shell returns to bootstrap and reconnects without duplicate launch |
| D11 | Clean install | application starts without system Python |
| D12 | Native Windows | real agent task completes with no WSL process or path |
D03 also verifies that the loopback origin sets its CSRF cookie on first load and that subsequent mutations still succeed in both WKWebView and WebView2 after an ordinary reload, WebView/window recreation, sleep/wake recovery, and a history back/return cycle where the platform exposes one. The cookie belongs to the loopback origin; the bootstrap Tauri origin neither reads nor writes it.
Verification Matrix
| Scenario | First-pass automation | Residual evidence |
|---|---|---|
| D01, D02 | Tauri integration: cold start and adopt without duplicate launch | packaged-app smoke on both OSes |
| D03 | SSE unit/integration plus WebView cookie and reconnect instrumentation | sleep/wake cookie continuity |
| D04 | shell-boundary assertion that Show JS has no Tauri IPC; Show proxy integration | live Show Runtime HMR in packaged app |
| D05 | API and browser integration where supported | OS drag/drop and clipboard automation |
| D06 | browser contract with a virtual authenticator where supported | physical/passkey evidence on both OSes |
| D07 | POSIX PTY integration now; Windows ConPTY gate in M2 | Unicode, resize, Ctrl-C, disconnect |
| D08 | reconnect state-machine tests | OS power-event evidence |
| D09, D10 | Tauri lifecycle integration: close/reopen and Runtime crash/recovery | packaged-app process inspection |
| D11 | clean macOS/Windows CI image | signed installer proof in M3 |
| D12 | Windows x64 workflow with fake Codex; protected real-backend job | real credential and native C:\... edit |
The shell PR may automate only the rows it owns. Manual-first rows stay open acceptance evidence; they are not silently counted as passing because the underlying browser code has unit coverage.
Required Windows Gates
| Gate | Coverage |
|---|---|
windows-runtime-contract |
isolated AVIBE_HOME, wheel install, service and authenticated control IPC, fake Codex, graceful stop/restart, no orphan tree |
windows-terminal-e2e |
real ConPTY with PowerShell Unicode, resize, \x03, exit, disconnect, and idempotent terminate; no bash or WSL |
windows-agent-e2e |
protected/nightly real Codex credential, stream and native file edit, no wsl.exe, no /mnt/ |
desktop-windows-build |
required Windows x64 Tauri/WebView2 build |
ARM64 remains off the required matrix until the Claude SDK wheel constraint is
removed. D12 file proof covers drive roots and a native read/edit/rename in a
C:\... workspace; no Windows path translation layer is added.
Go / No-Go Gate
Proceed with Tauri when all are true:
- no core Workbench feature has an unworkable WKWebView or WebView2 blocker;
- browser and desktop behavior remain materially equivalent;
- a native Windows agent session completes end to end;
- background tasks survive window close, shell restart, and WebView crash;
- platform differences remain inside the defined adapters;
- macOS and Windows have automated build and focused lifecycle verification.
Replace only the shell with Electron if any are true:
- Vault, Show Pages, terminal, or streaming requires a long-lived WebView fork;
- reliable lifecycle behavior cannot be tested or reproduced;
- Wry/Tauri must be permanently patched to ship core flows;
- business components accumulate Tauri-specific branches;
- OS WebView differences create recurring release-blocking regressions.
Implementation Sequence
- Land this plan and the
desktopintegration-branch policy in a documentation PR targetingdesktop. - Land the small
vibe start --no-open-browserlauncher contract in its own Python PR. - Land the Python-owned desktop endpoint contract: versioned descriptor,
same-process loopback listener, combined
/ready, and Host/auth regression tests. - Land the desktop-host PR containing
desktop/**, its two central locale catalog sections, and the desktop workflow: frozen probe/adopt/launch state machine, capability boundary, combined readiness/recovery, unit tests, and macOS/Windows build jobs. - Exercise D01-D05 and D08-D10 locally where the host permits.
- Land the Windows Controller IPC contract and cross-platform conformance tests.
- Land
ProcessHost: graceful control request, daemon ownership, Job Object worker cleanup, PID birth identity, restart, and UI port recovery. - Prove D12 with Codex on Windows x64 and a real native workspace.
- Extract the POSIX terminal seam and shared conformance suite without changing product behavior.
- Land pywinpty/ConPTY and prove D07.
- Prove Vault and Show Runtime on Windows without reducing their capability.
- Reuse the existing managed-Runtime parsing, validation, caching, and asset resolution for private Python/installer work; do not create a parallel Windows downloader.
- Add packaging and signing only after M1 and M2 pass.
Every implementation PR is non-draft, targets desktop, and requires GitHub
Codex review on its current head, zero unresolved review threads, and green
required CI before merge.
Desktop Host PR Scope
Included:
desktop/**Tauri v2 scaffold and bootstrap contract;- the exact
desktopBootstrapkeys in the central English and Chinese frontend catalogs; no other Workbench code; - consumption and strict validation of the Python-owned desktop descriptor;
- safe loopback Runtime discovery, combined readiness, launch, and recovery;
- bootstrap status/error/retry UI;
- unit tests for the Rust host logic;
.github/workflows/desktop-shell.ymlfor macOS and Windows.
Excluded:
- this plan and repository workflow policy, which land separately;
- Python Runtime or CLI changes, including the headless launcher and desktop endpoint contracts;
- ConPTY and Windows credential IPC;
- bundled Python and installer artifacts;
- tray and updater polish beyond what D01/D02/D09 require;
- any reduction of Show Page functionality;
- mobile projects.