§37 Loams Desktop and Mobile Apps: a cordis Console, a Tauri Shell, Native Phones

Status: Proposed · 2026-10-01, revised 2026-10-02 (the Authentik and D220 rulings). The direction is the owner's, given on 2026-10-01 in two messages:

1. "I downloaded the DeepSeek Harness desktop and mobile app repos. They serve as the base for the Loams desktop app and mobile app, with Connect-RPC. The harness desktop's Rust backend is Tauri, so adapt our control-plane React to Tauri. Mobile is Kotlin, so use Connect-RPC natively in Swift (iOS) and Jetpack Compose (Android)."
2. The same day's correction: "cordis" is the JavaScript meta-framework the harness is built on (contexts, services, a plugin lifecycle with scoped disposal and hot reload), not Tauri. The intent is to adapt Loams's control-plane React to cordis so that any code can be loaded as a plugin: console pages, panels, engine adapters, connectors, agent tools, and the integrations of §26, §30, §32–§34, each a cordis plugin with declared services and dependencies, loaded from a catalog like the harness's cordis.yml, in the browser and inside Tauri. Tauri stays the desktop shell; cordis is the application architecture inside it. "Native Connect-RPC" on mobile means connect-swift and connect-kotlin generated from the shared protos, with no web view or bridge, in native SwiftUI and Compose.

Amended 2026-10-02 (the zeron ruling). The owner ruled: "instead of Tauri go native for desktop apps also: https://github.com/zeronsh/zeron". The desktop is no longer a Tauri shell around the cordis console; it is a native app on a fork of zeron (§18, D480–D499, plan AP1n, which replaces AP1). Superseded by §18, kept below for history and marked in place: D420's "Tauri 2", D429–D432, D439's desktop layout, §3.1, §4's desktop half, §6 in full, §9's desktop rows, §12's tauri-driver tests, §13's AP1 row, risks 7, 9 and 10, Q428–Q430 and Q437 (as noted). Unchanged: the web console on cordis in the browser (D422–D428, AP1a), the phones and the app protos (D433–D438), AP0 and AP2/AP3. Later the same day the owner added: "do not drop Tauri; add it as a bridge to control websites": Tauri returns, not as the desktop shell but as a separate web bridge that agents drive as MCP tools (§18.14, D500–D512, plan AP1b). The names are the owner's: Loams Bot and Loams Software Factory (§39).

The owner's standing rulings that apply: Connect-RPC everywhere (connect-es, connect-swift, connect-kotlin, all from the protos connect-rust serves, D128); the package namespace loams (crates.io, PyPI, npm @loams), Go paths loams.dev/..., the domain loams.dev, CloudEvents types io.loams.dev.*; the repository moving to the GitHub organisation ostrium-labs; mobile native per platform, not Kotlin Multiplatform UI. Two further rulings arrived while this document was written (2026-10-01 and 2026-10-02): the identity provider is Authentik, open-source edition only (Clerk and Keycloak are gone), so every app sign-in flow targets Authentik (§6.5, §7.2); and D220's open-core split stands: the console's multi-tenant, hosted and billing parts stay in the private loam-cloud and loam-platform repositories, loaded as private plugins from a private registry. This document designs only the open side and names the extension points the private side uses (§5.8); it contains no design for hosted or billing plugins.

This document turns that direction into decisions D420–D439 and open questions Q420–Q439. Every choice beyond the direction (formats, trust tiers, flows, phasing) is a proposal until the owner confirms it. No code is written by this document. The plans are AP0, AP1a, AP1, AP2 and AP3.

Markers: (verified 2026-10-01) means checked against a primary source on that date (§17). (verify) means the plan that builds it checks it first. (estimate) means computed, not measured. Paths of the form harness-desktop/… point into dina-kar/deepseek-harness-desktop at 2d1b505 (2026-08-15); harness-mobile/… into dina-kar/deepseek-harness-mobile at 68b6c2f.

Naming. This document writes loams for the CLI binary and @loams/* for npm packages, following the owner's namespace rulings (D400, D401; the binary loams answers §30's Q284). Until D33's rename PR, everything builds under the working names (operon, @loam/console, @loam/ui).

1. SummaryCopy Anchor Link

2. Goals, non-goals and personasCopy Anchor Link

2.1 PersonasCopy Anchor Link

2.2 GoalsCopy Anchor Link

1. The console is extensible without a fork. Any page, panel, engine view, connector form, approval renderer or agent-tool view is a plugin with a manifest, declared services and declared permissions (D422–D427).
2. One console in three places. The engine's /ui, the desktop window and (when Q436 says so) Loams Cloud run the same host with different plugin sets (D428).
3. A desktop app that is a better local stack manager than the terminal, built on the CLI rather than beside it (D429).
4. Phones that are safe approvers. A decision proves a person on a known device; notifications reveal nothing to Apple, Google or the gateway (D434–D436).
5. One contract. Protos generate the server and all three clients; one mock and one scenario set test all of them (D433, D438).
6. Open by default (D220): every app, the plugin host, the first-party plugins and the push gateway's code are Apache-2.0 here or in loams-mobile.

2.3 Non-goalsCopy Anchor Link

• No Electron, no React Native, no Flutter, no Tauri mobile, no KMP UI. The owner chose Tauri for the desktop and native UI on phones. Tauri's own mobile targets shipped in 2.0 but its team calls the developer experience unfinished (verified 2026-10-01); they stay a fallback only.
• No Node server. §19 P8 rules out a Node service beside the binary. The harness's cordis host half (Node) is not used: Loams's host side is the Rust engine (Connect services) and, on the desktop, the Tauri host.
• No model-written plugins at run time. The harness's cordis_define lets an agent submit code that runs in the console after a click. Loams does not ship that: agents act through MCP and tokens (§15, §19 §5), not by injecting UI code.
• No full console on phones. Phones show environments, approvals, operations, jobs, runs and the inbox. Identity administration, keys and collection editing stay on the console and desktop.
• No relay in track AP. Phones reach instances that are reachable: Loams Cloud, or a self-hosted gateway exposed with TLS after the auth plan (Q425).
• No offline decisions (D435).

3. What we take from the harness repositories (D421)Copy Anchor Link

3.1 The desktop harnessCopy Anchor Link

Superseded 2026-10-02: the Tauri host pattern below is not used by the native desktop (§18.1, D480). Kept as a record of what was studied.

harness-desktop is upstream DeepSeek Harness (about 12 000 commits by its authors) plus a Tauri 2 host added on 2026-08-14 by fendouai. The host is apps/desktop/src-tauri/src/lib.rs (164 lines) and a capability file.

Gaps we fix rather than copy: no per-launch token, no supervision after readiness (a crash leaves a dead page), logs discarded after readiness, a hard kill with no process group, no single-instance guard, no CSP on the loopback UI, no updater, no signing or CI, and bundle targets that contradict each other ("all" with a macOS ["app"] override).

3.2 The mobile harnessCopy Anchor Link

harness-mobile is an Android client (Kotlin 2.0, Compose, Hilt, OkHttp, one multiplexed WebSocket) by sorsama and contributors, talking to a harness through the dsh-relay plugin (TypeScript, in a separate repository not studied here).

Gaps we fix: the relay terminates TLS and sees all plaintext; no token refresh; notifications only while a foreground service holds the socket, and no approving from a notification; approvals show only a tool name and a reason; cleartextTrafficPermitted="true" and user CAs trusted app-wide; a plaintext session cookie in DataStore with allowBackup="true"; a 2 000-line singleton store; no iOS.

3.3 Licences and attributionCopy Anchor Link

4. ArchitectureCopy Anchor Link

Superseded 2026-10-02: the right-hand "Tauri host" box below is replaced by the native app of §18.3 (zeron engine, loams-link, three seams); the console and the phones are as drawn.

                         ┌────────────────────── one console host (cordis v4) ─────────────────────────┐
                         │ boot: Context + Loader + browser module table + boot manifest (loams.yml)    │
  browser at /ui ───────▶│ services: transport · rpc.* (Connect) · api (OpenAPI) · session · platform   │
  (engine-served)        │           slots · router · settings · flags · i18n                           │
                         │ plugins:  shell · identity · collections · jobs · durable · approvals ·      │
  Tauri webview ────────▶│           devices · connectors · flow · gateway · live · (desktop) stacks ·  │
  (bundled, desktop set) │           mcp · (hosted: private plugins from a private registry, D220)     │
                         │ third-party plugins ──▶ sandboxed iframes ◀──bridge──▶ attenuated tokens     │
                         └───────────────┬───────────────────────────────┬──────────────────────────────┘
                                         │ fetch (browser)               │ net_fetch over IPC + Channel (desktop)
                                         ▼                               ▼
   ┌──────────── Tauri host (Rust, desktop only) ────────────┐   ┌──────── Loams instance (Rust) ─────────────────┐
   │ cli: `loams … --output json` (D283) ── stacks (D285)    │   │ connect-rust: Connect + gRPC + gRPC-Web       │
   │ net: bridge, origin allowlist, bearer injection         │──▶│ loam.instance/devices/approvals/operations/    │
   │ auth: PKCE loopback, keychain (keyring)                 │   │   notifications.v1 (AP0, AP4) · loams.jobs.v1   │
   │ tray · single instance · deep links · updater · logs    │   │   (J1) · loams.live.v1 · /api/v1 (OpenAPI, P9)  │
   └──────────────┬──────────────────────────────────────────┘   │ approvals = §21 approval promises             │
                  │ spawns via CLI (setsid, detached)            │ notifier: io.loams.dev.* → inbox → seal ──┐   │
                  ▼                                              └───────────────────────────────────────────┼───┘
         local stacks under ~/.loams/stacks/<name>                                                            │ sealed
                                                                                                             ▼
   ┌── Loams for iOS (SwiftUI) ──┐  ┌── Loams for Android (Compose) ──┐        ┌── loams-push gateway ─────────────┐
   │ connect-swift (URLSession)  │  │ connect-kotlin (OkHttp)         │◀──────▶│ APNs / FCM credentials of the     │
   │ Secure Enclave keys         │  │ StrongBox / TEE keys            │  push  │ store apps; sees ciphertext only  │
   │ NSE unseals HPKE payloads   │  │ FCM or UnifiedPush, Tink HPKE   │        │ (UnifiedPush: instance → endpoint)│
   └─────────────────────────────┘  └─────────────────────────────────┘        └───────────────────────────────────┘

5. The console as a cordis application (D422–D428)Copy Anchor Link

5.1 Why cordis, and what it givesCopy Anchor Link

cordis (MIT, cordiverse/cordis, by Shigma, the framework under Koishi and DeepSeek Harness) is a dependency-injection and lifecycle framework: a Context whose services are declared and injected, plugins with an apply function, an inject list and a config schema, and fibers (v4's scopes) whose side effects are all registered through ctx.effect or ctx.on and undone when the fiber is disposed. A plugin whose injected services are missing stays pending and activates when they appear; when a provider is replaced, its dependents reload. That is exactly what an extensible console needs: a page can depend on rpc.jobs and appear only on instances that serve loams.jobs.v1; disabling a plugin removes its routes, slot entries and streams without a page reload.

What exists today (verified 2026-10-01): cordis 4.0.0-rc.10 (2026-09-08; release candidates every 2–4 weeks; the README says the API "is not yet stable"), @cordisjs/plugin-loader 1.0.0-rc.7, @cordisjs/plugin-include 1.1.0, @cordisjs/plugin-hmr 1.1.0. The core imports no node: module, so it runs in browsers and in Tauri's webview; the harness runs the stock loader in the browser by stubbing node:module and process in Vite. The maintainer bus factor is one (548 of about 560 commits). §14 risk 1 covers it.

The harness proves the browser half at scale: about 40 client plugins in its web bundle, a boot manifest the server injects (window.__DSH_BOOT__), per-plugin bundles that may not import each other's values, a slot system for React, and fiber-by-fiber reload. Loams takes that half. The harness's Node host half (the loader on the server, Typert RPC over POST /api/<ns>/<method> and downlink WebSockets) does not apply: Loams's host side is Rust, and its RPC is Connect, which adds typed server streaming that Typert lacks.

5.2 The hostCopy Anchor Link

@loams/console-host (in web/packages/console-host) is the only code that is not a plugin. It:

1. reads the boot manifest: GET /ui/plugins/manifest.json from the engine in a browser, or the bundled plugins/manifest.json in Tauri. Each row is {id, name, url, integrity, rev, tier, inject, slots};
2. creates new Context(), installs @cordisjs/plugin-loader with loader.internal set to a browser module table that resolves rows to import(url) with Subresource Integrity checks, and loads the catalog (loams.yml, §5.3);
3. provides the core services (§5.4) and renders the React root, which renders only the root slot;
4. finishes boot with an all-fibers sweep: any fiber still pending after 10 s is reported in a "plugins" diagnostics page with the services it waits for (the harness's boot check).

Shared platform modules (React, React DOM, React Router, cordis, @loams/ui, @loams/slots, @bufbuild/protobuf, @connectrpc/connect, @loams/proto) are provided once through an import map; plugin bundles mark them external. A plugin that bundles its own React fails the build (AP1a Task 2).

5.3 The manifest and the catalog (D423)Copy Anchor Link

A plugin's manifest is a block in its package.json:

{
  "name": "@loams/plugin-jobs",
  "version": "0.1.0",
  "type": "module",
  "exports": { "./client": "./dist/client.js" },
  "loams": {
    "plugin": {
      "kind": "console",
      "entry": "./client",
      "tier": "first-party",
      "inject": ["rpc.jobs", "router", "slots", "session"],
      "provides": [],
      "slots": ["console.nav", "console.page", "environment.overview.card", "engine.view"],
      "permissions": ["jobs:read", "jobs:admin"],
      "requires": { "console": "^1.0.0", "api": ["loams.jobs.v1"] },
      "editions": ["oss", "desktop", "cloud"],
      "config": "./dist/config.schema.json",
      "server": null
    }
  }
}

The catalog is a cordis v4 loader entry list, the format the harness's cordis.yml uses (- id, name, config, group, disabled, inject). Loams names it loams.yml and composes it the harness's way: a base list, then patch lists per bundle and per edition (- id: x patches replace a row's config; - insert: adds rows):

# web/apps/console/catalog/base.yml   (the oss set)
- id: shell
  name: '@loams/plugin-shell'
- id: identity
  name: '@loams/plugin-identity'
- id: collections
  name: '@loams/plugin-collections'
- id: jobs
  name: '@loams/plugin-jobs'
  config: { pageSize: 50 }
- id: approvals
  name: '@loams/plugin-approvals'
- id: connectors
  name: '@loams/plugin-connectors'
# web/apps/desktop/catalog/desktop.patch.yml
- insert:
    - id: platform-tauri
      name: '@loams/platform-tauri'
    - id: stacks
      name: '@loams/plugin-stacks'
      inject: [platform.stacks]

!!js is not allowed in any Loams catalog. The harness evaluates !!js config with new Function, which needs unsafe-eval and is a code-execution path through configuration. Loams's console CSP has no unsafe-eval (§6.3), and the AP1a loader rejects a catalog that contains the tag. Dynamic values come from services (flags, session) inside apply, not from the catalog.

5.4 Service contracts (D424)Copy Anchor Link

The rule from the harness holds: a value import from one plugin into another is a build error. Plugins share types through @loams/proto and declare module merges on the Context and SlotMap interfaces, and behaviour only through services.

5.5 Slots (D425)Copy Anchor Link

The integrations of the other designs land as plugins in these slots:

5.6 Trust tiers, isolation and permissions (D426)Copy Anchor Link

cordis has no sandbox: its isolate and intercept only give scopes separate service names, and the harness says plainly that its plugins are as trusted as shell access. Loams needs a boundary for code its users did not write.

Server-side enforcement. A third-party plugin's calls do not carry the user's token. When the plugin activates, the host asks the gateway for a vended token (§19 §5.2 flow 3) with scp = the manifest's permissions ∩ the user's rights, act = {"sub": "plugin:<id>@<version>"} in the actor chain, one environment, and a 15-minute TTL, renewed while the plugin is active. The server's Authorizer decides as for any token, and the audit log shows the plugin as the actor. Client-side checks only shorten the path to a refusal.

Consequences:

• Before the unified auth plan (D111) there is nothing to vend, so third-party plugins are disabled in every build, and local-path plugins in development run as first-party with a red "unverified plugin" banner.
• A third-party plugin cannot render outside its frame (no overlays across the console, no access to other plugins' DOM), and cannot read the clipboard; ui:clipboard-write and ui:notifications go through the bridge with a visible host prompt the first time.
• On the desktop, third-party frames load from the loams-plugin:// custom scheme, a different origin from the app's; AP1a Task 6 verifies that frames get no Tauri IPC (verify).
• Installing a plugin on an instance is an org-owner action, and in a protected environment it goes through an approval gate (D435). The install screen shows the permissions, the publisher, and whether npm provenance links it to a public repository.

5.7 Sources, distribution and reload (D427)Copy Anchor Link

Reload. In development, Vite's HMR replaces React components in place; a change to a plugin's apply triggers the harness's fiber refresh (invalidate the module, dispose the fiber, which undoes its slot entries, routes and streams, then load it again). React state inside that plugin is lost, as in the harness. In production, the host subscribes to PluginService.WatchManifest; an install, upgrade, enable or disable becomes a fiber add, replace or dispose, with no page reload. Desktop updates replace the whole bundle on restart (§6.6).

Versioning. The host exposes console (semver) and the plugin declares requires.console. Breaking changes to a core service or slot's props bump the host's major version; the slot catalog and SlotMap types are generated into docs (the harness's catalog generator pattern), and a CI check fails if a slot's props change without a version bump.

5.8 Editions as plugin sets (D428)Copy Anchor Link

D220 stands: everything a single organisation needs to self-host is open, and the console's multi-tenant, hosted and billing parts stay in the private loam-cloud and loam-platform repositories. In plugin terms:

The extension points the open host offers, and the only things this document fixes about the hosted set:

The open host has no knowledge of the private plugins, and this repository never depends on them. Today's loam-cloud console is a separate Next.js app (with Clerk, which the Authentik ruling retires) and placeholder pages; whether it moves onto this host as a set of private plugins is Q436.

5.9 What the browser console needs to changeCopy Anchor Link

The console on main (web/apps/console, Vite 8, React 19, React Router 8, openapi-fetch) is already a static SPA, so it embeds in Tauri. AP1a turns it into the host plus plugins and fixes what blocks the desktop: baseUrl: window.location.origin in src/api/client.ts and the raw fetch('/v1/…') become the api and transport services; the hard-coded /ui in window.location.assign calls (pages/auth.tsx) becomes router navigation; the /ui basename and Vite base become build options; the cookie-and-CSRF session stays for the browser, and the desktop uses bearer tokens through the bridge (which needs GET /api/v1/session to accept a bearer and return the principal; an auth-plan item, §16).

6. The desktop shell (D429–D432)Copy Anchor Link

Superseded 2026-10-02: this whole section describes the Tauri design and is superseded by §18 (D480–D499). Stack supervision through the CLI (§6.2) survives as D488 (§18.3); sign-in (§6.5) as D486 (§18.7); the capability lockdown and net_fetch bridge (§6.3, §6.4) are retired by D489; updates and signing (§6.6) are replaced by D490 (§18.8); deep links (§6.7) stand, navigation only. Kept for history.

6.1 ShapeCopy Anchor Link

One Tauri 2.12 window (verified 2026-10-01) loads the bundled console with the desktop set. The Rust host (loams-desktop, its own Cargo workspace under web/apps/desktop/src-tauri, not part of the engine workspace) owns everything privileged: the CLI, the network, credentials, the tray, deep links, updates and logs. It exposes them to the console only as typed commands, which @loams/platform-tauri turns into cordis services.

6.2 Stacks through the CLI (D429)Copy Anchor Link

The harness's host spawns one fixed runtime. Loams's desktop manages any number of stacks, and the CLI already does that well: stack.toml, the engine registry, port blocks, /ready polling, setsid, log rotation (§30 §8). Re-implementing it in the app would give two supervisors of the same directories. So:

• The sidecar is the loams binary, the standard variant (§30 D286), bundled as externalBin (binaries/loams-<target-triple>). Bundling costs tens of MB (estimate; Q428 asks whether to download it on first run instead).
• Every stack action is loams stack <verb> --output json, parsed by D283's contract: one JSON document on stdout, one error object on stderr, the exit code classified (0 ok … 9 integrity, 130 interrupted). Children run in their own process group with no TTY, LOAMS_NO_UPDATE_CHECK=1 and a timeout.
• LOAMS_HOME is shared (default ~/.loams), so a stack created in a terminal appears in the app within one poll, and the other way round.
• Stacks outlive the app, as they outlive a terminal. The tray lists running stacks. A setting stops the stacks the app started on quit (default off, Q429).
• The app adds a restart policy the CLI lacks: a keep_running stack reported crashed restarts with backoff 1 s … 30 s, at most 5 times in 10 minutes, then stays crashed with its log tail.
• Creation and deletion stay in the terminal in AP1. stack create (it can download variants and touch disks) and stack delete --yes are shown as exact commands to copy. Start, stop, restart, upgrade and logs are buttons.
• "Add loams to PATH" links ~/.loams/bin/loams to the bundled binary and writes receipt.json with install_method: "desktop". loams self-update refuses that install (exit 6 managed_install, hint "update Loams Desktop"), which amends D294.

Windows has no server variant (§30 Q285), so the desktop on Windows is remote-only: it signs in to Cloud or self-hosted instances and has no stacks page (Q437).

6.3 Capability lockdown (D430)Copy Anchor Link

6.4 The network bridge (D430)Copy Anchor Link

Three ways a webview can reach a Loams instance were considered:

tauriFetch implements the standard fetch signature, so connect-es (createConnectTransport({ fetch: tauriFetch })) and openapi-fetch use it unchanged. The Rust side allows only origins in the active environment's endpoint set, adds Authorization: Bearer (and a DPoP proof once Q438 lands), strips Cookie, Authorization and Proxy-* headers set by JavaScript, uses HTTP/2 when the server offers it, and pins the TLS key for environments that came from a pairing (§7.2.3). Credentials travel only over HTTPS: a request to a non-loopback origin over plain http is refused before any credential is attached; unauthenticated http to loopback (local stacks, D111) keeps working. Redirects never carry credentials to a new origin: a 3xx to the same origin and scheme is followed at most 3 times; a redirect to another origin, or from https to http, is not followed and reaches JavaScript as an error, so no bearer or DPoP proof is ever sent to a location the allowlist did not admit. The phones' clients do the same (followRedirects(false) on OkHttp, a refusing redirect delegate on URLSession). AP1 Task 0's spike measures throughput and memory.

6.5 Sign-in and credentials (D431)Copy Anchor Link

• Identity provider: Authentik, open-source edition (owner ruling, 2026-10-01). GetInstance names the instance's Authentik issuer and the Loams gateway's token endpoint.
• Flow: OIDC authorization code with PKCE at Authentik, started from the desktop and completed in the system browser, so whatever Authentik is configured with (passwords, TOTP, WebAuthn, upstream SSO) works; redirect to http://127.0.0.1:<port 0>/callback (RFC 8252 §7.3), one request accepted, state and nonce checked. Public client id loams-desktop, registered as an Authentik application for the instance. The desktop then exchanges Authentik's token at the Loams gateway (RFC 8693, §19 §5.2) for Loams's access and refresh tokens; Authentik's own tokens are not kept. tauri-plugin-oauth 2.1 provides the loopback listener if its licence passes deny.toml (verify); otherwise it is about 60 lines.
• Storage: the refresh token in the OS keychain through keyring 4.2 (macOS Keychain, Windows Credential Manager, Linux Secret Service), one entry per (instance_id, principal_id); the access token in memory; rotation on every refresh. tauri-plugin-stronghold is deprecated and will not exist in Tauri v3 (plugins-workspace#3494, verified 2026-10-01). Without a Secret Service on Linux, sign-in lasts the session only and the UI says so.
• Local stacks before the auth plan report auth: none (D111) and need no sign-in. After it, a local stack is signed in to like any instance.
• Approvals on the desktop use step-up SESSION: a session older than 5 minutes re-authenticates at Authentik in the browser (max_age=0) before a decision is sent (D435). A desktop device key with OS user presence (Touch ID through Keychain access control, Windows Hello) is a later option.

6.6 Updates, signing and packaging (D432)Copy Anchor Link

6.7 Deep links, single instance, tray and logs (D432)Copy Anchor Link

• loams:// links: open/<env>/<console path>, approvals/<id>, stacks/<name>. Rust parses them against an allowlist and hands the console a typed route through the desktop/deeplink event. No deep link performs an action; it can only navigate. tauri-plugin-deep-link 2.6 registers the scheme at install (macOS has no runtime registration), and tauri-plugin-single-instance 2.5 with its deep-link feature forwards links to the running instance.
• The tray shows stacks with their state and the number of pending approvals.
• Logs go to the app log directory, rotating at 10 MB, 5 files, and the startup failure page names that path.

7. The mobile apps (D433–D437)Copy Anchor Link

7.1 Shared rulesCopy Anchor Link

• Native UI and native clients. SwiftUI (iOS 17+) with connect-swift 1.2 (stable; URLSessionHTTPClient), and Compose with connect-kotlin 0.9 (beta; ConnectOkHttpClient, javalite). Neither app uses a web view except the system browser for sign-in.
• Protocol: Connect, binary codec, unary and server-streaming only (§8.3). gRPC would need trailers, which URLSession lacks (connect-swift's gRPC needs ConnectNIO); nothing requires it.
• Module split from the harness (§3.2): a pure core (pairing payload, decision canonicalization, watch resume, unsealing, error reasons) testable without a device; a data layer (clients, trust, keys, tokens, cache); push; UI; conformance.
• Same screens on both: environments, approvals (list and detail), operations, jobs and runs (when loams.jobs.v1 is served), the inbox, devices and settings. No identity administration.

7.2 Pairing and identity (D434)Copy Anchor Link

Mapping the harness onto §19. The harness's relay issued its own per-device bearer token and pinned its own TLS key. Loams already has an identity system: people sign in at the instance's Authentik (the identity provider, owner ruling 2026-10-01), and the Loams gateway issues Loams tokens signed by the instance's Ed25519 key, with a JWKS and revocation through the ControlStore change feed (§19 §5). So:

7.2.1 The QR payload (v1)Copy Anchor Link

{"v":1,"kind":"loams-pair","issuer":"https://loam.acme.example","instance_id":"01J9Z3…",
 "spki":["Rk9PQkFSLi4u…"],"jkt":"NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
 "code":"7JQ2KX4M2ZB6V3NAQ6E5RW2HCA","user_code":"48213977","exp":1790899500}

issuer is the Loams gateway (the authorization server for Loams tokens), not Authentik. spki is null for instances with publicly trusted certificates. code is 128 random bits, single use, valid 5 minutes, bound to the user who created it (DeviceService.CreatePairing); the example's exp is 2026-10-02 00:05 UTC. user_code is the typed alternative to code for the same pairing: the pairing grant accepts either code or user_code (never both), and a pairing is burned after 5 failed user_code attempts, so 8 digits within 5 minutes cannot be guessed (AP0 Task 2). A reader refuses v other than 1, another kind, an expired payload or a non-https issuer.

7.2.2 Three ways to pairCopy Anchor Link

1. QR (primary). The signed-in user opens "Pair a phone" in the console or desktop. The phone scans, pins spki before sending a byte, calls GetInstance, checks instance_id and that the JWKS contains jkt, creates two hardware keys (§7.6, §7.7), and redeems the pairing: POST {issuer}/api/v1/oauth/token with grant_type=urn:loams:params:oauth:grant-type:pairing (an extension grant, RFC 6749 §4.5), code, client_id (loams-ios or loams-android), device_name, platform, decision_jwk (the public key of the decision key), an optional key attestation, and a DPoP header. The answer is {access_token, token_type: "DPoP", expires_in: 3600, refresh_token, device_id}.
2. Browser sign-in at Authentik. ASWebAuthenticationSession or Custom Tabs with PKCE at the instance's Authentik, returning through https://loams.dev/app/auth/callback (universal and app links, Q281). The phone then exchanges Authentik's token at the Loams gateway (RFC 8693) with a DPoP proof and the same device fields, and receives the same DPoP-bound Loams tokens as the QR path.
3. Device code at Authentik (no camera, or a phone that cannot open the browser flow). The phone starts Authentik's device authorization flow (RFC 8628, verify the version that ships it) and shows the user code; the user enters it on the desktop or console, already signed in. Before that the phone connects trusting on first use, shows the gateway's key fingerprint as six words, and the console shows the same six words for the user to compare; the app says this pairing was not pinned in advance (the harness's honesty rule). The result is exchanged at the gateway as in path 2.

All three produce the same Device record. Authentik authenticates the person; the Loams gateway issues and binds the tokens, because DPoP binding, the dev and env claims and revocation are Loams's (§19 §5.3–§5.4). The unified auth plan implements the pairing grant, the exchange, the device record and DPoP binding (Q438); AP0 fixes the contract.

7.2.3 Pins that rotate without re-pairingCopy Anchor Link

The harness's relay minted a new TLS key whenever its addresses changed, which forced every phone to pair again. Loams separates the anchor from the transport key:

• The anchor is jkt. GetInstance returns tls_pins: a JWS signed by that key listing the current and next SPKI hashes. A phone accepts a new TLS key only if a pin set signed by the anchored key announced it.
• When the instance rotates its signing key, its JWKS lists both keys for an overlap period, and GetInstance.key_rotation carries the new key's thumbprint signed by the old key. A phone moves its anchor only along that chain.
• A mismatch is a hard stop ("this server's identity changed"), never a fallback to CA validation.

7.2.4 No relay in track APCopy Anchor Link

dsh-relay terminates TLS on the user's network and sees everything. A hosted relay for Loams would have to be end-to-end (TLS passthrough by SNI, so the relay sees ciphertext only) and is a service with abuse and cost questions of its own. Phones in track AP reach instances that are reachable on the internet: Loams Cloud, or a self-hosted gateway with TLS after the auth plan (D111 keeps M1 listeners on loopback). Teams that keep instances private can use their VPN or a tunnel (Tailscale, Cloudflare Tunnel). Q425 asks whether to build a relay.

7.3 Approvals (D435)Copy Anchor Link

§21 §6.5 defines approval gates: a destructive operation (collection or namespace drop, erasure, restore over live data) or a requires_approval agent action becomes an operation whose first step waits on an approval promise, settled by an approver, timing out after 72 hours. loams.approvals.v1 makes that a service every app shares:

• What an approval shows: a server-rendered summary and detail_lines in the user's locale (so iOS, Android, desktop and push show the same words and new kinds need no app release), the environment and whether it is protected, the requester and the actor chain (an agent acting for a user shows both), the risk, the policy's progress (1 of 2), and the time left.
• Who may decide: the org's approval policy through the Authorizer (§21 §6.5); the requester, or the user an agent acts for, cannot approve their own request by default (Q432).
• A decision needs a proof. DecideApproval carries decision_proof, a compact JWS (ES256 from the Secure Enclave or StrongBox; EdDSA allowed for software keys) over {approval_id, revision, decision, iat, jti}, signed by the device's decision key, which needs biometrics or the device passcode for every signature. The server verifies it against the key registered at pairing, checks revision (a stale card cannot be approved) and jti (no replay). A desktop or browser decision without a device key is accepted when the session is younger than 5 minutes, or when the policy says step_up: none.
• Typed confirmation for the worst cases. A DESTRUCTIVE approval requires typing the target's name, carrying §19 §4's protected-environment rule to the phone. Rejecting requires a reason.
• Not offered: "always allow" (policy changes are console actions, themselves approval-gated in protected environments), decisions from the lock screen without the app, and queued decisions.

7.4 Push notifications (D436)Copy Anchor Link

The constraint. An APNs token-signing key belongs to one Apple developer team (Apple offers team-scoped and topic-specific keys), and a push is accepted only for a topic, the app's bundle id, that the key may send to. A team-scoped key can authorize pushes to every app of that team, so loams-push uses a topic-specific key limited to the Loams app's topics, held only by the gateway; FCM credentials belong to the app's Firebase project. Only the publisher of the store apps can push to them, so a self-hosted instance cannot push directly. Matrix (Sygnal), Mattermost (its push proxy), ntfy (upstream poll_request) and Home Assistant all solve this with a push gateway that the publisher runs (verified 2026-10-01). Loams does the same, with the gateway blind to content:

 engine: CloudEvent io.loams.dev.approval.requested.v1 (or …operation.failed.v1, …job.dead_lettered.v1)
   └─ notifier (a durable function in the engine): per-user projection, preferences, quiet hours
        ├─ inbox row (loams.notifications.v1, kept 30 days, estimate)
        └─ per device push target: seal(Notification) with HPKE to the device's X25519 key,
             AAD = instance_id ‖ notification_id  →  POST https://push.loams.dev/v1/notify
                                                      {target, app_id, sealed, collapse_id, priority, ttl}
 loams-push gateway: instance credential check, per-instance rate limit → APNs (token auth) / FCM HTTP v1
 device: NSE (iOS) or FirebaseMessagingService (Android) unseals → shows title and body → tap → app fetches details over Connect

• What the gateway sees: the device token, the app id, the instance id, sizes and timing. Not the title, body, environment or approval.
• What Apple and Google see: the same, plus a generic alert text ("New activity in Loams") that the extension replaces after unsealing. If unsealing fails, the generic text stays and the app syncs its inbox.
• HPKE (RFC 9180, DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20-Poly1305): CryptoKit's HPKE on iOS 17 and Tink on Android. The sealed body stays under 2 KB to fit APNs' 4 KB limit; details are fetched.
• The gateway is open source (loams-push, a small Rust service in this repository, AP4) and Loams operates the instance the store apps use (an operational service in loam-platform, D220). Self-hosters who publish their own app builds run their own gateway with their own keys, as Mattermost requires. Instances register with the gateway for a credential; abuse limits are per instance (Q424).
• Android without Google services: a unifiedpush flavor; the instance posts the same sealed payload to the user's UnifiedPush endpoint (RFC 8030), with no gateway (Q439).
• Desktop: no push service; the running app holds WatchApprovals and raises native notifications (AP1 Task 8).
• Categories: approvals (high priority; actionable with Review, which opens the approval and asks for biometrics), operations, jobs, runs, security (device added, device revoked). Approvals may bypass quiet hours (a user preference, default on).

7.5 Offline and background (D437)Copy Anchor Link

7.6 Android specificsCopy Anchor Link

Keystore keys per instance, EC P-256, StrongBox when present: dpop-<instance> without user authentication (background refresh works) and decide-<instance> with setUserAuthenticationRequired(true), strong biometrics or device credential for every use, and invalidation on biometric enrolment changes; signing through BiometricPrompt with a CryptoObject. The refresh token is AES-GCM-encrypted with a Keystore key in DataStore (the harness's RelayCredentialStore pattern). cleartextTrafficPermitted="false", no user CAs, allowBackup="false", FLAG_SECURE on approval and pairing screens. Flavors fcm and unifiedpush. Details: AP2.

7.7 iOS specificsCopy Anchor Link

Secure Enclave P-256 keys per instance: dpop (.privateKeyUsage) and decide (.privateKeyUsage + .biometryCurrentSet, or .userPresence without biometry), so DPoP and decision proofs are ES256. Keychain items AfterFirstUnlockThisDeviceOnly, never synchronizable, shared with the Notification Service Extension through an access group. ATS on with no exceptions outside Debug; pins evaluated in the URLSession delegate. Categories with a REVIEW action that opens the app (.foreground, .authenticationRequired). Details: AP3.

7.8 Kotlin Multiplatform: evaluated, not recommended (D433)Copy Anchor Link

Recommendation: no KMP. The protos are the shared contract; golden fixtures (canonical DecisionClaims bytes, pairing payloads, sealed notifications) and the conformance scenarios keep the two cores equal, and LoamsCore also builds on Linux so the fixtures run in Linux CI (AP3 Ruling 6). Revisit if connect-kotlin gains KMP support and the shared logic grows past roughly a third of either app.

8. The proto surface (D438)Copy Anchor Link

8.1 What each app needs, and what existsCopy Anchor Link

8.2 The new packages (AP0)Copy Anchor Link

Package names stay loam.* to match loams.live.v1 and loams.stream.v1; whether the rename moves every proto package to loams.* before the first app release is Q422 (Connect URL paths contain the package, so it is cheap before a release and breaking after one).

8.3 Protocol choicesCopy Anchor Link

8.4 GenerationCopy Anchor Link

buf generates every client from proto/: protobuf-es 2 (@bufbuild/protobuf 2.16, used by @connectrpc/connect 2.2) into web/packages/proto (@loams/proto, committed, checked for drift in CI); buf.build/apple/swift + buf.build/connectrpc/swift (GenerateAsyncMethods) and buf.build/protocolbuffers/java (lite) + buf.build/connectrpc/kotlin for the mobile repository, which generates at build time from a pinned git ref of this repository. The server keeps D128's generation (buffa and connectrpc-build in build.rs). buf breaking is enforced for the new packages.

9. Repository layout (D439)Copy Anchor Link

Superseded 2026-10-02: the desktop rows (web/apps/desktop/, src-tauri, @loams/platform-tauri) are superseded by D493: the desktop lives in ostrium-labs/loams-desktop (§18.9). Everything else in this layout stands.

Recommendation: desktop and console in this repository; both phone apps in one new repository, ostrium-labs/loams-mobile.

ostrium-labs/loams (this repository)
├── proto/loams/{instance,devices,approvals,operations,notifications,errors}/v1/   (AP0)
├── crates/operon-apps-mock/                       (AP0; scenarios shared by every app)
├── crates/loams-push/                             (AP4, not yet planned)
├── web/packages/{console-host,slots,forms,proto,platform-web,platform-tauri,ui}/
├── web/plugins/{shell,identity,agents,keys,audit,collections,jobs,durable,live,flow,connectors,gateway,approvals,devices,stacks,mcp,plugins}/
├── web/apps/console/                              (the browser build the engine embeds at /ui)
└── web/apps/desktop/ + src-tauri/                 (its own Cargo workspace and lockfile)

ostrium-labs/loams-mobile
├── android/  (core, proto, data, push, app, conformance)
├── ios/      (Packages/LoamsCore, LoamsProto, LoamsData; Loams app; LoamsNotificationService; LoamsConformance)
├── conformance/proto-ref.lock                     (this repository's git ref both apps generate from)
└── buf.gen.swift.yaml, buf.gen.kotlin.yaml        (copies of AP0's templates)

10. Open-core placement (D220)Copy Anchor Link

Nothing here makes this repository depend on loam-platform. A self-hoster gets every app, every open plugin and the gateway code; what they cannot get from us is our APNs key, which no one can share.

11. Security modelCopy Anchor Link

12. TestingCopy Anchor Link

Superseded 2026-10-02: the tauri-driver and WebdriverIO desktop tests below are superseded by D495 (§18.11): native tests, a mock smoke test of the built binary, and upstream's suites.

The harness's three layers, shared across apps:

1. Pure cores with golden fixtures. Android :core and iOS LoamsCore test pairing payloads, error reasons, watch resume, decision canonicalization and unsealing against the same fixture files, which loams-apps-mock also uses. A descriptor-set hash test ties each app to conformance/proto-ref.lock.
2. A shared, scriptable mock. loams-apps-mock (AP0) serves every AP0 service over Connect, gRPC and gRPC-Web, is stateful, verifies decision proofs for real, and replays YAML scenarios (approvals-basic, approval-expiry, stream-drop-and-resume, device-revoked, operation-progress, notification-burst). Its validation is the server's acceptance module, so it refuses what the server will refuse.
3. Conformance per app. Each app runs every scenario and an endpoint catalogue (a typed business error counts as a pass) on the JVM or the macOS host, with no emulator or simulator for the network layer.

Plus, per surface: Vitest for plugins with fake services, Playwright for the browser console, tauri-driver with WebdriverIO on Linux and Windows for the desktop, Compose UI tests and screenshots, XCUITest. Security tests are named in each plan's Review Focus: the capability allowlist, the secret canary, deep-link property tests, pin bypass tests, and iframe_cannot_reach_network.

13. Roadmap: track AP (D439)Copy Anchor Link

Order: AP0 first; AP1a and the two phone plans in parallel; AP1 after AP1a's host. Everything runs against the mock until AP4; nothing is published before D33's rename and the move to ostrium-labs.

14. RisksCopy Anchor Link

15. Open questionsCopy Anchor Link

16. Contradictions with earlier decisions, and how they are resolvedCopy Anchor Link

17. SourcesCopy Anchor Link

Read on 2026-10-01 and 2026-10-02.

• Harness desktop (dina-kar/deepseek-harness-desktop at 2d1b505): LICENSE, README.md, AGENTS.md, THIRD_PARTY_NOTICES.md, apps/desktop/src-tauri/{src/lib.rs,tauri.conf.json,tauri.macos.conf.json,capabilities/default.json,Cargo.toml}, apps/desktop/scripts/prepare-runtime.mjs, .agents/notes/implemented/architecture/2026-08-14-tauri-desktop-sidecar-host.md and 2026-07-23-client-plugin-loading-model.md, packages/client/connection/src/api-request-trust.ts, packages/client/web/src/boot.tsx, packages/client/ui-slots, packages/bundle/web-app/cordis.patch.yml, packages/boot/app-boot/src/profile.ts, vendor/README.md, vendor/loader/src/config/{entry.ts,tree.ts,utils.ts,isolate.ts}, vendor/cordis/src/registry.ts, scripts/gen-cordis-catalog.ts, docs/api-gateway.md, tsconfig*.json.
• Harness mobile (dina-kar/deepseek-harness-mobile at 68b6c2f): LICENSE, README.md, THIRD_PARTY_NOTICES.md, settings.gradle.kts, gradle/libs.versions.toml, docs/{PROTOCOL.md,SECURITY.md,COMPATIBILITY.md}, core/.../wire/{RelayPairing.kt,RelayTls.kt,ConnectionLoop.kt,RemoteStreamMux.kt}, app/.../data/{SessionStore.kt,RelayCredentialStore.kt,HarnessSessionStore.kt}, app/.../notify/*, app/src/main/res/xml/network_security_config.xml, mock-harness/, conformance/, .github/workflows/ci.yml.
• cordis: github.com/cordiverse/cordis (licence, releases v4.0.0-rc.7 to rc.10, contributors); npm cordis, @cordisjs/plugin-loader, @cordisjs/plugin-include, @cordisjs/plugin-hmr, @cordisjs/plugin-webui, @koishijs/plugin-console (licence metadata).
• Connect: github.com/connectrpc/connect-es (2.2.0), connectrpc.com/docs/{faq,node/using-clients,swift/using-clients,kotlin/using-clients,kotlin/getting-started}; github.com/connectrpc/connect-swift (1.2.3, Package.swift, conformance configs); github.com/connectrpc/connect-kotlin (0.9.0, issue #140); github.com/connectrpc/connect-rust and buf.build/blog/connect-rust-joins-the-connect-project; connectrpc 0.9.1 on crates.io; github.com/connectrpc/connect-query-es (2.3.1); npm @bufbuild/protobuf 2.16.0.
• Tauri: github.com/tauri-apps/tauri releases (2.12.1); v2.tauri.app/plugin/{updater,deep-linking,single-instance}, v2.tauri.app/develop/sidecar, v2.tauri.app/distribute/sign/{macos,windows}, v2.tauri.app/blog/tauri-20; tauri-apps/plugins-workspace#3494 (Stronghold); github.com/tauri-apps/tauri-action (1.0.0); github.com/FabianLars/tauri-plugin-oauth (2.1.0); crates.io keyring (4.2.0).
• Mobile platform: Apple's "Establishing a token-based connection to APNs", the Apple developer forum thread on URLSession trailers; github.com/square/okhttp; kotlinlang.org/docs/{components-stability,native-swift-export}; github.com/touchlab/SKIE releases; unifiedpush.org (spec).
• Push gateways: github.com/element-hq/sygnal; docs.mattermost.com/deploy/mobile/host-your-own-push-proxy-service; docs.ntfy.sh/config; companion.home-assistant.io/docs/notifications/{notification-details,notification-local}.
• Proxies: developers.cloudflare.com/fundamentals/reference/connection-limits and the 524 error page; docs.aws.amazon.com/elasticloadbalancing/latest/application/edit-load-balancer-attributes.
• Loams: §19, §21 (§6.4, §6.5), §26 (D206, §6.6), docs/open-core.md (D220, D221), §30 and its pending log (branch cli-design), §32–§33 and their pending log (branch flow-fabric-house-design), §34 (branch gateway-runtime-design); web/ on main at 9eaddae (apps/console/{vite.config.ts,src/main.tsx,src/api/client.ts,src/session.tsx,src/pages/auth.tsx}, packages/ui), api/console/openapi.json, crates/operon-console-mock, buf.yaml, buf.gen.yaml, proto/loams/live/v1/live.proto, crates/operon-stream-grpc/proto/loams/stream/v1/stream.proto; loam-cloud at c738de7 (next.config.*, proxy.ts, app/(console)/, lib/console.ts, lib/integrations.ts; read only).

18. Native desktop on a zeron fork (supersedes the Tauri desktop)Copy Anchor Link

Status: Proposed · 2026-10-02. The direction is the owner's, given on 2026-10-02: "instead of Tauri go native for desktop apps also: https://github.com/zeronsh/zeron", with the product names Loams Bot and Loams Software Factory. This section turns that ruling into decisions D480–D499 and open questions Q480–Q499, staged in _pending/37b-log.md (not yet in the decision log). Everything beyond the ruling is a proposal until the owner confirms it. The plan is AP1n; the scaffold is the branch loams-scaffold of ostrium-labs/loams-desktop (§18.12).

Markers: (verified 2026-10-02) means read in zeron's tree at 80b946b (2026-10-01) or on GitHub that day. (verify) means the plan task that builds it checks it first. (estimate) means computed, not measured.

18.0 What this supersedes, and where it still pointsCopy Anchor Link

Unchanged: D422–D428 (the web console on cordis, in the browser at /ui), D433–D438 (the phones and the app protos), §10's open-core placement for everything except the desktop's repository.

18.1 The ruling, and what zeron is (verified 2026-10-02)Copy Anchor Link

What zeron does not have: an extension or plugin runtime (its extension points are MCP servers, ACP agents, skills and themes), an organisation or identity model, an approvals concept, or any notion of a server. It is a very good single-user agent cockpit; Loams adds the server-connected half.

18.2 What to keep, change, add and drop (D481)Copy Anchor Link

18.3 The engines and the loams binary (D482, D488)Copy Anchor Link

  ┌──────────────────────────── Loams Desktop (zeron fork, one binary `zeron`) ───────────────────────────┐
  │  gpui UI ──── typed RPC (in-process or ws://127.0.0.1:27654) ──── zeron engine                       │
  │   · transcript, composer, terminals, diffs                       · sessions, run journals, worktrees  │
  │   · harness picker: Claude Code, Codex, … , Loams Bot            · agent subprocesses (user's rights) │
  │   · loams-panels (later): approvals, stacks, operations, collab                                       │
  │                                                                                                      │
  │  loams-link (no GPUI)                                                                                 │
  │   · Connect clients (buf-generated)  · Authentik OIDC + keychain  · stack supervisor (CLI JSON)      │
  │   · `zeron loams bot-acp`: ACP agent ⇄ A2A (stub) / loams.bot.v1 (SF3)                               │
  └──────┬──────────────────────────┬────────────────────────────────────────────────┬───────────────────┘
         │ (1) supervise            │ (2) Connect-RPC                                │ (3) spawn, ACP on stdio
         ▼                          ▼                                                ▼
   `loams` CLI  ─ stacks      loams server (local stack or remote)            Loams Bot ACP shim (same binary)
   `loams stack … --output json`   loams.instance / approvals / operations /        └─ production: loams.bot.v1 (Connect) to the
                                                                                      server-side Loams Bot, which speaks A2A to
                                                                                      Plane, Zulip, Forgejo, GlitchTip, analytics
   shared LOAMS_HOME                 collab / bot .v1                                      (scaffold stub only)

Three seams, and no fourth.

1. Supervise. Stacks are managed by running loams stack <verb> --output json (§30 D283, D285) with no TTY, LOAMS_NO_UPDATE_CHECK=1 and a timeout, parsing the one JSON document on stdout. LOAMS_HOME is shared with the terminal, so a stack created either way appears in the other. Stacks outlive the app. stack create and stack delete stay copy-paste commands in the first release. The restart policy AP1 specified (keep_running, backoff 1 s to 30 s, five tries in ten minutes) moves into loams-link. Windows stays remote-only (Q437), because no Windows server variant exists.
2. Connect. The app calls a running loams server with connect-rust clients generated by buf from the same protos the server, the console and the phones use (D128, D438). The scaffold has loams.instance.v1 (GetInstance, WhoAmI); approvals, operations, notifications, collab and bot arrive as AP0 and the SF plans land. Remote HTTPS needs connect-rust's client-tls and the pinning of §7.2.3 (AP1n Task 4).
3. Spawn. Loams Bot is an ACP agent the zeron engine launches like any other (D483).

Why not embed the loams engine in the app. It is Rust, so it is tempting. Against it: the engine workspace is about 950 crates (DataFusion, Arrow, Lance, TiKV clients), and linking it beside GPUI in one binary would multiply link time and memory on a build machine already at its limit; an engine crash or a stuck compaction would take the window down; the app and the engine could no longer release independently; and the CLI already owns stack supervision (stack.toml, port blocks, readiness, setsid, log rotation). Embedding would also give two supervisors of one directory. Why not run stacks inside zeron's engine: it has no notion of one, and teaching it would be a large patch to a file set that changes daily.

Open: where the bundled loams binary lives and whether one updater may touch both it and zeron's ~/.zeron/app layout (Q488); a native Stacks panel versus CLI-only buttons first (Q497, which turns on whether a stack is a zeron "space").

18.4 Loams Bot as zeron's chat and agents surface (D483, D497)Copy Anchor Link

Zeron's chat surface already gives Loams Bot threads, an attention-sorted sidebar, drafts, a durable queue, steering, interrupts, attachments, tool cards, a question panel and local persistence. The cheapest faithful way to put Loams Bot on it is the way zeron puts Devin and Hermes on it: as an ACP agent.

Who speaks A2A. §39 D465 stands: clients speak Connect to Loams Bot, and Loams Bot speaks A2A to the five platform agents. In production the ACP shim therefore talks to loams.bot.v1 (a Connect stream, SF3), not to agents. The A2A client in loams-link is a stub: a small JSON-RPC client (SendMessage, CancelTask) with a mock agent, so the chat path runs end to end before SF2 and SF3 exist, and so a developer can point LOAMS_BOT_URL at one agent. It follows A2A 1.0's JSON-RPC binding as §39 §5.3 records it and must be re-checked against a2a.proto in SF2 Task 0 (Q466).

This amends D478 for the desktop only. §39 planned to port the harness's conversation UI as cordis plugins (@loams/plugin-bot, rpc.bot). On the native desktop the conversation UI is zeron's, so that port is not built. Mobile is unchanged: native SwiftUI and Compose chat over loams.bot.v1. The server keeps the durable execution (a thread survives a locked phone or a closed laptop); the desktop keeps the transcript it shows. Which is the source of truth when they disagree is Q496. First-run default harness (Claude Code as upstream has it, or Loams Bot once an instance is configured) is Q484.

The Loams Software Factory on the desktop is the loop of §39 §10 seen from this chat: runs, stages, approvals and the kill switch are native panels over loams.collab.v1 and loams.factory.v1 (AP1n Task 8), plus Loams Bot's cards. Zeron's own zeron mcp server and its headless engine are an opportunity for the loop's coding step: a VPS running zeron headless could be the worker for the Forgejo agent's propose_patch sessions (§39 D477) instead of Loams' sandbox (Q498).

18.5 How the app UIs appear (D484)Copy Anchor Link

§39 §3.2 fixed the rule: native, API-driven panels for the objects the loop reads and writes, and the app's own web UI, unmodified, for everything deeper. D464 implemented "deeper" as isolated Tauri child webviews. On a zeron fork that mechanism does not exist, and the verified state of zeron's browser changes the answer:

The web bridge of §18.14 now supplies the third column's missing piece: a managed webview with persistent per-profile stores on all three operating systems ("Open in Loams Web"). So the defaults are: panels first, "Open in browser" for the full app, and the sidebar browser as an opt-in that is on only where a spike proves it good enough. Specifically:

• Zulip, Plane, Forgejo, GlitchTip: a native panel for the objects (from loams.collab.v1, SF1), and Open in browser to the app's own URL, where the person is already signed in at Authentik.
• OpenPanel: tiles in a panel, "Open" for the full UI. Langfuse, OpenObserve: links, never embeds (§39 D461).
• The browser console itself (/ui on the instance, with its cordis plugins) opens the same way: it is the place for administration, and it is where cordis plugins live (§18.6).
• The sidebar browser is a top-level browsing context, not a frame, so D462's edge changes are not needed for it: no X-Frame-Options removal and no frame-ancestors for tauri://localhost. A page that cannot be framed works fine here.
• What the spike (AP1n Task 7, Q482) must prove: a persistent data store on the Linux helper and on macOS, so that signing in to Authentik once lasts; passkeys and WebAuthn on each OS; a Windows browser on wry (WebView2); and whether gpui-wry (Apache-2.0, longbridge/gpui-kit, 0.7.0) can sit on zeron's pinned GPUI fork at all, since it targets Zed's own GPUI (unverified; it may need a patch). Everything the spike produces is generally useful and goes upstream first (D491).
• Mobile does not embed (§39 D461, unchanged): native views, sealed push, deep links to the system browser.

18.6 The plugin story (D485)Copy Anchor Link

Cordis no longer runs inside the desktop, because there is no webview. The extension story is therefore three tiers, each with a different trust level, and none of them needs a fork of zeron's UI to extend it.

Why not Zed's extension host: Zed's extension runtime is built into editor crates that are GPL; only the extension API crate is Apache-2.0, and zeron has deliberately kept every GPL crate out. A host of our own on wasmtime is small, because Loams already chose wasmtime for functions (§24), and a declarative UI keeps third parties out of the render loop. Whether tier 3 is worth building at all, and whether third-party desktop plugins are allowed in the open edition, are Q486 and Q487; tiers 1 and 2 need neither.

The web console's plugins (D422–D428) are unaffected: they run in the browser console, which the desktop opens like any other app. There is one console, in a browser, and one native cockpit beside it.

18.7 Sign-in, sync and credentials (D486, D487, D489)Copy Anchor Link

• Sign-in. OIDC authorization code with PKCE (S256) at the instance's Authentik, in the system browser, redirect to http://127.0.0.1:<ephemeral>/callback (RFC 8252 §7.3), one request accepted, state and nonce checked, public client loams-desktop. The issuer and client id come from GetInstance.sign_in_methods. The refresh token is stored in the OS keychain (macOS Keychain, Windows Credential Manager, the Linux Secret Service) through the keyring crate, one entry per instance, and rotates on every refresh; the access token lives in memory only. Where no keychain exists, sign-in lasts the session and the app says so. The RFC 8693 exchange of the Authentik token for Loams tokens at the gateway (D431) is added with the unified auth plan (Q438). The scaffold implements the flow end to end against a fake provider in tests; it has not been run against a real Authentik.
• Zeron's login is not used. The fork's default WorkOS client id is a non-zeron placeholder and its default edge host cannot resolve (edge.loams.invalid), so zeron's login and sync paths are compiled but unreachable. Upstream's zeron login would otherwise send a Loams user to zeron's WorkOS tenant.
• Sync (D487). Zeron's multi-device sync is Loro documents through zeron's Cloudflare edge. Loams does not depend on another company's backend. The desktop is local-first on its device; continuity across devices is the server's: a Loams Bot thread is a durable execution visible from every device (§39 §13). Whether the Loro document layer is worth giving a Loams transport (streams over Connect) is Q483.
• The credential rule (D489). The Tauri design defended against JavaScript holding tokens. A native app has a different adversary: the agents it launches, which are subprocesses with the user's rights, and the sidebar browser. So: Loams tokens exist only in loams-link's memory and the keychain; no agent subprocess and no browser receives one, not even through an inherited socket or pipe (calls an agent needs are made by loams-link on its behalf and only the result is returned); the injected zeron mcp server carries chat identity and nothing else; and when an agent must call Loams, it does so through the credential broker with an attenuated, audience-bound token (§39 §6), never the user's. Local stacks before the auth plan report auth: none (D111) and need no token.

18.8 Updates and signing (D490)Copy Anchor Link

18.9 Upstream tracking, licensing and the repository (D491–D493)Copy Anchor Link

Cadence. Zeron ships about two releases a day and moved 670 commits in September. Merging its main would be a permanent job, so the fork rebases onto upstream release tags, not main, at least every two weeks (Q480). A scheduled agent opens the rebase PR; CI is the judge. Conflicts are rare by construction.

Patch discipline. Loams changes are (a) additive crates and files (loams-brand, loams-link, dist/loams, scripts/loams, one workflow), (b) one-line hooks marked // loams: in inherited files, and (c) the match arms the compiler demands when HarnessId grows. LOAMS.md keeps a patch ledger of every inherited file touched and why; a CI job (AP1n Task 1) fails when an inherited file changes with no ledger line. The scaffold touches 20 inherited files (and Cargo.lock), almost all single lines (§18.12); the check itself is AP1n Task 1.

What goes upstream first (Q481): a config-driven custom ACP agent (which would delete the HarnessId patch), signed manifests, a persistent browser store, the Windows browser, an "ask" mode for permission requests. These are the changes zeron's other users also want, and each one that lands removes a patch from the ledger. What stays in the fork: anything that names Loams, Authentik or A2A.

Licensing and attribution (D492). LICENSE (MIT, "Copyright (c) 2026 Wing") is untouched. A root NOTICE records the fork, links upstream, and states that Loams-added crates are Apache-2.0 (D220). THIRD_PARTY_NOTICES.md stays upstream's (tree-sitter grammars, GPUI, gpui-component, Symbols icons) and gains nothing until Loams adds a bundled asset. A cargo deny licence job (AP1n Task 1) guards the dependency tree, and zeron's own statement that it uses no GPL Zed crate is kept true by it. The name "Zeron" is never used as a product name.

Repository (D493). ostrium-labs/loams-desktop, a public fork with upstream history, created with gh repo fork zeronsh/zeron --org ostrium-labs --fork-name loams-desktop on 2026-10-02. It vendors the protos it uses by pinned ref (crates/loams-link/proto/PIN, scripts/loams/sync-protos.sh), the pattern loams-mobile uses (§9). The monorepo keeps AP0, AP1a and the CLI. D439's layout row changes accordingly.

18.10 RisksCopy Anchor Link

18.11 Testing, platforms and phasing (D494, D495, D499)Copy Anchor Link

• Platforms (D494): Linux x86_64 and aarch64 (Wayland and X11), macOS on Apple silicon, Windows x86_64 (the set zeron's workflows build). Stacks on macOS and Linux; Windows is remote-only.
• Tests (D495): loams-brand and loams-link have no GPUI dependency and run in seconds on all three operating systems (the scaffold has 33 tests: PKCE against the RFC 7636 vector, the loopback listener, the full sign-in against a fake provider, the Connect client against the in-process mock, the A2A JSON-RPC client, and the ACP agent over an in-memory pipe). A smoke script drives zeron loams status, bot and bot-acp against the mock in the built binary on Linux and Windows. Generated code is regenerated and diffed in CI. Upstream's UI, engine and Windows suites run on every change because the shared crates changed. The Tauri plan's tauri-driver tests and risk 10 disappear.
• Phasing (D499): AP1n replaces AP1. AP1a drops its desktop catalog patch and @loams/platform-tauri. AP0 is unchanged (the desktop consumes its protos by pinned ref). SF1's Tauri child-webview tasks become panels and the spike of §18.5; SF3's desktop task becomes the harness shim of §18.4.
• Stacks and approvals on the desktop: approvals are a native panel over loams.approvals.v1 with step-up through the system browser (max_age=0) and native notifications from zeron's notifier (D435, AP1n Task 6). Pairing a phone stays in the console first and gets a native QR panel in AP1n Task 8.

18.12 The scaffold (what the fork's first pull request contains)Copy Anchor Link

Branch loams-scaffold of ostrium-labs/loams-desktop, on zeron 80b946b, 2026-10-02. It is deliberately small and mostly additive.

CI added: the Loams crates on Linux, Windows and macOS; a build of the real binary with the mock smoke test on Linux and Windows; and the generated-code drift check. Zeron's own workflows already build the app on Linux and Windows for every crates/** change and on macOS in the release workflow, so they are not duplicated.

Not in the scaffold (each is an AP1n task): the stack supervisor, native panels, TLS to remote instances, the RFC 8693 exchange, loams.bot.v1, the signed update manifest and the feed, packaging overlays and signing, the sidebar-browser spike, the WASM host, deep links, and the rebase automation.

18.13 Contradictions with earlier decisions, and how they are resolvedCopy Anchor Link

18.14 The Tauri web bridge (D500–D512)Copy Anchor Link

Status: Proposed · 2026-10-02. The direction is the owner's, given the same day, after the native ruling: "do not drop Tauri; add it as a bridge to control websites, efficiently, like the Chrome MCP toolbox." This subsection adds decisions D500–D512 and questions Q500–Q511. The D480–D499 block is full, so the numbers continue at D500 (renumber at merge if another branch took them). They are staged in _pending/37b-log.md. The plan is AP1b. Markers are as in §18: (verified 2026-10-02) means read in the named source that day, (verify) means the plan task that builds it checks it first, (estimate) means computed, not measured.

What changes and what does not. D480 stands: the desktop is the native zeron fork, and Tauri does not come back as the desktop shell, so D429–D432 and D439 stay superseded. Tauri 2 returns in a different role: a separate web bridge process, a managed webview host that opens and keeps sessions for websites and that agents drive as MCP tools. It also answers the two gaps §18.5 found in zeron's sidebar browser: none on Windows, and no persistent store on Linux.

18.14.1 Role and shape (D500–D502)Copy Anchor Link

  agents: Loams Bot (ACP shim)  ·  Claude Code, Codex, Cursor … in zeron  ·  any MCP client
        │ MCP over stdio                                    │ (never a Loams token; a scoped session handle)
        ▼                                                   │
  `loams-web-bridge mcp`  (thin stdio shim, one per agent session)
        │ local IPC: Unix socket 0600 / Windows named pipe with an owner-only ACL
        ▼
  ┌──────────────── loams-web-bridge daemon (Tauri 2, one per user) ────────────────────────────┐
  │ MCP tool registry · policy and approvals · redaction · audit · profile manager                │
  │ windows: one webview per page, one data store per profile (WebView2 · WebKitGTK · WKWebView)  │
  │ injected script (isolated world) ⇄ eval · native hooks per OS · CDP in-process on Windows     │
  └───────▲──────────────────────────────────────────────▲───────────────────────────────────────┘
          │ launch, supervise, approvals                  │ OTLP (content-free; content to Langfuse only, §39 D470)
   Loams Desktop (zeron fork, loams-link)         collector → OpenObserve, Loams, Langfuse

• D500, the role. Loams Desktop stays native. loams-web-bridge is a separate Tauri 2 application whose job is to host webviews for websites (Zulip, Plane, Forgejo, GlitchTip, Langfuse, OpenObserve, any site) with persistent, isolated sessions, and to expose them as tools. A person can also use its windows by hand ("Open in Loams Web", §18.14.6).
• D501, the repository. Its own repository, ostrium-labs/loams-web-bridge, Apache-2.0, not a fork, with its own Cargo workspace. Reasons: Tauri's dependency tree and per-OS webview libraries (webkit2gtk-4.1, WebView2, WKWebView) must stay out of the engine's Cargo.lock (the reason D439 gave for a separate workspace); the three-OS CI and signing are heavy and independent of the engine; and any MCP client may use it without Loams Desktop. It vendors the few protos it needs by pinned ref, as loams-desktop does (D493). Q500 asks whether to keep it in the monorepo instead.
• D502, processes and transport. A daemon (single instance per user, a lock file) owns the webviews, profiles and policy. Agents never speak to it directly: each agent session spawns the thin stdio shim loams-web-bridge mcp, which proxies MCP over local IPC to the daemon, exactly as zeron's zeron mcp proxies to the engine (§18.1). Callers are identified by a session handle minted by Loams Desktop, or, for a standalone client with no Loams Desktop, by the user running loams-web-bridge handle new --profile … --class … --origin … --ttl … over the owner-only control channel (the same endpoint Desktop uses, authenticated by OS user identity), which prints the handle for the client's MCP configuration. A handle is random, scoped to a chat, a profile set, tool classes and an expiry, revocable, and passed in the shim's environment. A handle is not a Loams token and opens nothing off the machine, so D489 stands. A loopback Streamable-HTTP listener for clients that cannot spawn a process is off by default and needs a per-launch bearer.

18.14.2 The toolbox (D503, D504)Copy Anchor Link

Studied on 2026-10-02: ChromeDevTools/chrome-devtools-mcp (Apache-2.0 (verified), about 53 k stars, 59 tools in docs/tool-reference.md, plus a three-tool --slim mode) and microsoft/playwright-mcp (Apache-2.0 (verified), about 38 k stars, 72 browser_* tools, of which storage, routing, tracing and video sit behind capability flags). Their lists overlap on the core, which is the part Loams takes.

Capabilities group the tools as Playwright's --caps does: core (default, no script, no network detail), network, script, and a slim set (navigate_page, take_snapshot, click, fill) for small models, as chrome-devtools-mcp's --slim does with three tools.

Efficiency rules (D504). These are the token-saving tricks of the two projects, plus two of ours. Cited to their sources: chrome-devtools-mcp's docs/design-principles.md ("Token-optimized: return semantic summaries", "Reference over value: for heavy assets return a file path"), its take_snapshot with verbose and uids of the form <snapshotId>_<n> (src/TextSnapshot.ts), its pageSize and pageIdx on list tools; Playwright MCP's README ("accessibility snapshot … better than screenshot", --snapshot-mode, depth, filename, browser_find).

1. Snapshot, not screenshot. A compact accessibility-style text tree (role, name, state, uid) is the default way to see a page. A screenshot is an explicit tool call and returns a file path.
2. Uids carry their snapshot id (s12_34). A uid from an older snapshot returns a self-healing error ("snapshot s12 is stale; call take_snapshot"), never a click on the wrong element.
3. Actions answer small. After click or fill the result is a one-line outcome plus a change summary (navigated to, dialog opened, N nodes added or removed, a download started), with snapshot: "none" | "diff" | "full" per call and a server default of diff. Playwright MCP returns a full snapshot after every action by default (--snapshot-mode full); that is the main cost Loams avoids.
4. Search before dumping. find returns matching nodes with a few lines of context, as Playwright MCP's browser_find does, so an agent asks "the Save button" and does not read the page.
5. Scope and depth. take_snapshot takes a uid to scope to and a depth; the default prunes ignored and presentational nodes, collapses single-child chains, truncates text at 200 characters, and folds repeated siblings ("… 37 more similar rows").
6. Paginate lists. Console and network tools take pageSize and pageIdx and default to short, summarised rows; bodies come from get_network_request by id.
7. Reference over value. Screenshots, downloads, large snapshots (filename) and network bodies go to the profile's session directory and return a path.
8. A token budget per result (default 6 000 tokens, an estimate to be tuned in AP1b Task 11), with a clear truncation marker and the call to continue.
9. Errors say what to do next (design principle "self-healing errors").

None of this is measured yet. AP1b Task 11 benchmarks snapshot size and steps per task against both projects on the pages of the apps in §39.

18.14.3 Mechanism per platform (D505)Copy Anchor Link

What Tauri 2.12.1 exposes (verified in tauri-apps/tauri at 2.12.1, 2026-09-30): WebviewBuilder::initialization_script and initialization_script_for_all_frames (run at document start, on every navigation); Webview::eval and eval_with_callback (the result comes back as a JSON string; a thrown exception is ignored on Windows, so scripts wrap their own try); data_directory (Windows and Linux), data_store_identifier (macOS 14 and later, 16 bytes), incognito, proxy_url; Webview::cookies, cookies_for_url, set_cookie (including HTTP-only cookies, http and https URLs only) and clear_all_browsing_data; on_navigation, on_new_window, on_download, on_page_load; additional_browser_args (Windows only); and with_webview, which hands over the platform's native webview handle. Tauri's own end-to-end tests drive Windows through msedgedriver and --remote-debugging-port, Linux through WebKitWebDriver, and macOS through a commercial CrabNebula driver and plugin, which Loams does not use.

• Uniform layer. The accessibility-style snapshot is computed by an injected script from the DOM and ARIA attributes, the way Playwright builds its aria snapshot in packages/injected/src/ariaSnapshot.ts (Apache-2.0 (verified)), which Loams may port with attribution (Q510). Results return by eval_with_callback; there is no page-to-Rust channel.
• No Tauri IPC for remote pages. The webviews load remote origins and are granted no capability: window.__TAURI__ and invoke are unreachable from a website, so a page cannot call the bridge or the host. Control is Rust-initiated (eval and native callbacks) only. This is the property D430 had to engineer; here it is the default.
• CDP, where the engine has it. On Windows the bridge uses in-process CDP through the WebView2 handle (CallDevToolsProtocolMethod and the event receivers, reached through with_webview (verify)), which gives the real AX tree, network and console without opening a port. WebKit has no CDP; its inspector protocol is different and its remote inspector is a human tool, so Linux and macOS use the injected layer plus native hooks.
• Remote debugging ports. No listening debug port in the default build. A development flag (Windows only, loopback, off by default, a warning in the title) may expose WebView2's --remote-debugging-port so that chrome-devtools-mcp --browser-url can attach, but CDP has no authentication and any local process could then drive a signed-in session, so it is never used in production (Q504).
• Degradations, stated. On Linux and macOS the network list covers what the hooks and signals see, not every sub-resource; there is no heap, trace or Lighthouse tooling; and the accessibility names are an approximation of the browser's. Q509 asks whether that is acceptable.

18.14.4 Security (D506–D510)Copy Anchor Link

Profiles (D506). One profile per site or tenant, named <environment>/<site> (for example acme-staging/zulip). Each is a separate persistent store, so signing in to Authentik at one app does not leak into another, and an agent granted acme-staging/plane cannot read acme-staging/zulip. Persistence is what makes Authentik single sign-on last across restarts (the gap in zeron's Linux browser). Ephemeral profiles (incognito) exist for one-off visits. Clearing a store is a human-only action.

Secrets (D507, the §30 D288 rule applied to the web). No credential reaches an agent-visible output.

• fill takes a secret_ref (for example loams:acme-staging/zulip#password) that the bridge resolves from the OS keychain or the credential broker (§39 §6); the value never appears in a tool argument, result, snapshot, error or log.
• Snapshots elide the values of password, one-time-code and payment fields and of anything with an autocomplete credential token; network results redact Authorization, Cookie and Set-Cookie and the bodies of authentication endpoints; console text is scrubbed for token-shaped strings.
• No cookie or storage tools exist (Playwright MCP's browser_cookie_* and browser_localstorage_* are deliberately not taken).
• A login, a captcha or a second factor is handed to the person: request_human shows the window, the tool blocks, and the person finishes. The bridge never types a human secret on the model's behalf.

Approvals and policy (D508). Every tool has a class: read (list, snapshot, find, screenshot, console, network), interact (click, fill without submit, hover, select, press, type, wait), commit (a form submit, a non-GET request the page makes right after an agent action, upload_file, a download; and any click, press_key or fill_form that may cause one, which is classified commit before it runs: a click on a submit control, a control inside a form, a link or button the snapshot marks as submitting, or Enter in a form field, so approval is asked before the action starts and a request is never released late), and dangerous (evaluate_script, navigating off the allowlist, enabling a capability). Policy maps (agent, tool class, origin) to allow, approve or deny; commit and dangerous default to approve, as the factory policy of §39 §8 (D468) does for destructive skills. An approval is a Loams approval (§19, §21) raised through Loams Desktop and decided by a person with the proof of D435, never auto-approved and never decided by the agent (D497). The origin allowlist defaults to the origins of the environment's apps (from the instance and collab configuration); off-list navigation is denied unless approved. The origin check is enforced at on_navigation, on_new_window and the request hooks, and again at the tool; like Playwright's own --allowed-origins, it is a guard against mistakes, not a security boundary against a hostile page, which is why the controls below exist. (verify) how reliably a form submit can be intercepted before it leaves on each engine; the fallback is gating the click or key that causes it.

Untrusted content (D509). Everything derived from a page (text, names, console lines, network rows) is untrusted data. Results wrap it in a marker the harness and the policy can see (escaped so that page text cannot close it), the bridge never follows instructions found in a page, and Loams Bot's rule stands that an approval or a question it did not raise cannot be answered by page content (§39 D468). Pages cannot call the bridge (no IPC), cannot read other profiles, and run in webviews with the user's permissions prompts routed to the bridge window, not auto-granted.

Audit and observability (D510). Every tool call emits an OpenTelemetry span (loams.web.tool) with the tool, class, profile, origin (path and query redacted), agent principal, chat or run id, approval id, snapshot id, result size and outcome, joined to the agent's trace by the W3C traceparent that the shim receives. Spans go to the collector of §39 §9.1: content-free to OpenObserve and Loams' own ingest; snapshots and page text only to Langfuse 4, under the masking and retention policy of §39 §9.2 (Q476). A local hash-chained JSONL audit log in the profile directory (0600) survives a collector outage. The §39 D473 kill switch maps to a pause-all command that closes sessions' handles and blocks new calls.

18.14.5 Platform and licence notesCopy Anchor Link

Licences (verified 2026-10-02): Tauri 2 and wry: Apache-2.0 or MIT; chrome-devtools-mcp, Playwright MCP and Playwright (the source of the aria snapshot): Apache-2.0. The bridge does not ship either MCP server: it reimplements the tool contract in Rust, and ports only the injected snapshot code, with attribution in NOTICE. This also avoids chrome-devtools-mcp's usage statistics, which are on by default (--no-usage-statistics), in conflict with D284.

18.14.6 Integration with Loams Desktop and the Factory (D511, D512)Copy Anchor Link

• Launch and supervision (D511). loams-link gains a bridge module: start the daemon on first use (loams-web-bridge daemon), health-check it over IPC, restart it with the policy of §18.3 (backoff, five tries in ten minutes), stop it on request. Version skew is a handshake (bridge_api_version), not a shared binary.
• Agents. Loams Bot's ACP shim gets the bridge through ACP mcpServers in session/new (zeron's engine already passes MCP servers to ACP agents); coding agents in zeron get it through the same stamping that adds zeron mcp, or through loams mcp install (§30 D290). Each gets its own handle.
• Windows. Bridge windows are separate native windows with a persistent banner ("controlled by Loams Bot", a Pause and a Stop button) and a taskbar entry. Embedding them into zeron's window (an NSView, an HWND or an X11 reparent) is deferred (Q508). Background profiles may run with the window minimized or hidden; some sites throttle hidden pages, so the bridge keeps pages visible but off-screen where it must.
• Open in Loams Web. The "Open in browser" action of §18.5's panels gains a second choice: open the app in a bridge window of its profile, with a persistent Authentik session on Windows and Linux too. The system browser stays the default where passkeys matter.
• Relation to SF1 (collab panels). Panels are API-driven and remain the primary view of Zulip, Plane, Forgejo and GlitchTip objects (§39 §3.2). The bridge is the fallback for what an app's API does not offer.
• Relation to SF2 (agents). The platform agents are server-side services and cannot reach a person's desktop. Two ways to give them web reach when an API lacks a feature are open (Q507): a client-tool relay, where Loams Bot on the server asks the person's Loams Desktop to run a bridge tool through loams.bot.v1 and returns the result (the desktop executes, the server orchestrates), or a headless bridge on the factory host (a Playwright MCP container is the buy option, Apache-2.0). The first keeps credentials on the user's machine; the second suits unattended runs. Desktop-local agents use the bridge directly either way.
• D512, buy over build. The toolbox is a small contract, so Loams builds it; the browser is the platform's. No Node runtime ships. Playwright MCP stays the choice for headless, server-side and CI automation.

18.14.7 RisksCopy Anchor Link

Sources read for this subsection (2026-10-02): ChromeDevTools/chrome-devtools-mcp (README.md, docs/{tool-reference,slim-tool-reference,design-principles,configuration}.md, src/TextSnapshot.ts, src/formatters/SnapshotFormatter.ts); microsoft/playwright-mcp (README.md); microsoft/playwright (packages/injected/src listing); tauri-apps/tauri at 2.12.1 (crates/tauri/src/webview/mod.rs, packages/api-e2e/README.md); GitHub licence and star metadata for all of them. Platform behaviours marked (verify) are not yet tested.

18.15 SourcesCopy Anchor Link

Read on 2026-10-02. Zeron (github.com/zeronsh/zeron, 80b946b, 2026-10-01): README.md, ARCHITECTURE.md, CONTEXT.md, docs/mcp.md, docs/reference/{linux-browser,windows-development}.md, docs/PARITY.md, Cargo.toml, apps/zeron/src/{main,update_cli,auth_cli}.rs, crates/engine/src/{auth,registry,harness_updates}.rs, crates/harness/src/acp/{mod,normalize}.rs, crates/update/src/lib.rs, crates/ui/src/{lib,browser/mod,icons,pickers}.rs, crates/ui/Cargo.toml, .github/workflows/{release,windows,ui-tests}.yml, .github/actions/*, dist/, LICENSE, THIRD_PARTY_NOTICES.md; GitHub metadata (stars, contributors, release and commit counts). Loams: §19, §30, §37 (this document), §38, §39 and its pending log (branch software-factory-design, PR #192), the AP0 branch's proto/loams/{instance,errors}/v1 (commit bc3e559, not yet on main) and loams-apps-mock, docs/open-core.md. Libraries: connect-rust 0.9.1 (connectrpc, connectrpc-codegen), buffa 0.9.2, keyring 4.2.0, gpui-wry 0.7.0 (crates.io metadata only). Protocols: RFC 7636, RFC 8252, RFC 8693, A2A 1.0 as recorded in §39 §5.