SouveraineOS/docs/tasks/73-self-dashboard.md

73 — The self-dashboard: one spine, two skins (Gatehouse)

Status: designed 2026-08-10/11, nothing built. Working name for the house skin: Gatehouse — name decision is Casey's, still open. Owner: Rook, under Casey's direction.

Origin: the 2026-08-10 session (exported to clipboard) opened with Casey: "I was building a local desktop app vewsion" of RedFlag, and then, on sshbool: "we're stealing it for RedFlag and SouveraineOS's implementation of the self-dashboard. It'll need to include 'Agent Health' as well Federated Agents. So massive expansion and we're stealing what we want from it into our own desktop app."

The shape — decided

One spine, two skins. The UI is a view, never a state writer — both skins are thin clients of the local agent; the authority stays in the agent/helper.

• Skin 1 — RedFlag Desktop (public, MIT, Codeberg): stays Tauri v2, already the stack in RedFlag/desktop/. Tauri's value is for machines Casey doesn't own: installers, updater, plugin ecosystem, a security model someone else audits. Tray lives here. FEAT-007 owns it and is mostly built.
• Skin 2 — House Gatehouse (private): the wry way, souveraine-lens's skeleton — wry 0.56 + tao 0.36, ~317-byte manifest, LTO/strip. No tray code at all: Casey, 2026-08-11: "we have QML we can build whatever we want so tray is irrelevant as argument." Presence is the shell's. Two affordances:
  • The glance — agent health, gate badges, pending approvals. A native QML widget in the shell (surfaces/quickshell/services/), one socket payload, no webview, no window.
  • The workbench — SFTP panes, terminal, Monaco, fleet graph: the sshbool frontend steal, in a wry window summoned by the shell over a unix socket (the lens's own pattern: --ipc $XDG_RUNTIME_DIR/souveraine/lens.sock, one JSON object per line, both ways).
• The wall: gatedLocalApproval hard-gates dnf/apt only — agent/internal/handlers/local_approve.go:52, mirrored at LocalAgentApp.tsx:151. SouveraineOS is Arch; the Pixel 3 is Arch ARM. So RedFlag-as-self-dashboard, today, lists every update on the house machines and can install none — which is exactly why souveraine-updater exists (Rust + 16 QML, updater-core/src/auth.rs:50: pkexec /usr/bin/pacman -S --noconfirm — no token, no closure, no gate).
• The spine: teach the closure resolver pacman. Signed repo metadata plus -Sp --print-format gives the artifact set — tractable, and untracked (no GATE-* covers it; GATE-006 is Docker). When the spine lands, souveraine-updater's pkexec path becomes deletable rather than defended.
• License flow is one-way: MIT shell flows into the house freely; house-specific never reaches the public mirror (the gitignored-docs/tasks/ trick). sshbool is Apache-2.0 — clean, decision settled 2026-08-10.

Acceptance

• The pacman closure spine exists in the agent and resolves an update set from signed repo metadata; a RedFlag gate verdict covers Arch packages.
• pkexec pacman --noconfirm is gone; souveraine-updater retired; update approval on house machines goes through the gated flow.
• House Gatehouse repo exists: lens skeleton, socket IPC to the agent/substrate, pacman-owned delivery (no updater, no second channel).
• The glance renders agent health and gate verdicts on the shell from the socket; the workbench opens/summons from the shell and shows the same payloads as a deep seat (SFTP, terminal, fleet graph).
• sshbool frontend pieces ported into the workbench; Agent Health and Federated Agents views present.
• Public skin: FEAT-007 remainder lands (journal read endpoint, fleet-join transition, live e2e) and ships as RedFlag Desktop.
• Verified on hardware: laptop, ArchDev, and the Pixel 3 agent through the gated path — update listed, approved, installed.

Evidence

• Origin session quotes and dates above; the thread was exported, no task file existed until this one.
• RedFlag public branch is clean at 1f75bfd2 (v0.2.9.3) with four uncommitted desktop files: desktop/tauri.conf.json, web/vite.desktop.config.ts, helper/src/main.rs, agent/internal/handlers/upgrade_healthcheck.go — launcher plumbing to make the tray appear at all in compositor-only sessions (Hyprland/Sway/River), untouched since Jul 27.
• FEAT-007 is ~two-thirds built: LocalAgentApp.tsx rewritten Jul 1 20:03 — update list, scan trigger, approve, override-reason on a blocked gate, verdict rendering, standalone-vs-fleet branching. Missing: journal read endpoint, fleet-join transition, live e2e.
• sshbool audit (2026-08-10): v0.1.4, Apache-2.0, Tauri v2 + React 19 + russh; ships tauri-plugin-single-instance — the dep RedFlag's tray lacks. README overclaims: SQLCipher absent (plain sqlite, plaintext host rows at crates/infrastructure/src/ssh/manager.rs:120), FIDO2 absent (no ctap/webauthn anywhere). Real hole to know about: first-contact host keys accepted at manager.rs:23 and the pin written after authenticate(). The clone lived only in the session scratchpad — needs re-pull.
• souveraine-lens is the house precedent: README.md seam sentence — "the lens is a surface over them, not a home for them" — and the shell-over- socket drive pattern.

Remaining work

1. Re-pull sshbool into the workspace (it is not on disk anywhere).
2. Decide the name — Casey's call (Gatehouse / The Watch / The Ward).
3. Decide where the shared shell/spine physically lives: crate in RedFlag consumed by the house, a shared repo, or vendoring. Two skins, zero duplicated state writers — do not fork the spine.
4. File the pacman-closure task (new GATE-* under RedFlag's docs/tasks).
5. House skeleton: lens skeleton + socket to the agent/substrate.
6. The glance: QML service in surfaces/quickshell/services/.
7. Port the sshbool frontend pieces into the wry workbench.
8. Wire gate verdict rendering to the spine.
9. Delete the pkexec path; retire souveraine-updater.
10. FEAT-007 remainder on the public skin; ship RedFlag Desktop.

Open questions the audit session should ask

• The name.
• Home repo for the house skin: new souveraine-gatehouse vs a directory in souveraine (lens is its own repo).
• On a house box both agents live: does the workbench speak to the RedFlag agent over localhost HTTP and to the substrate over the socket — or is one agent enough on the x86 seats?
• What "Federated Agents" means at house scale: the fleet graph across ArchDev / .19 / Pixel 3 / laptop, rendering the same payloads the glance shows per-box.
• Scope of the glance vs the workbench: which payloads stay native QML and which wake the webview.

Connections

• RedFlag/docs/tasks/FEAT-007-desktop-tray-standalone-ui.md — public-skin owner; this task owns the structure around it.
• 29-souveraine-updater — the task this design replaces.
• 68-shared-household-state — the dashboard renders household state; the first slice (admitted task trail + QML view) overlaps the glance.
• 69-agent-usage-session-daemon — "shell services become projections of one socket" is the same shape as the glance.
• RedFlag RAF §11 — the gate only gates what routes through it; the pacman spine is the helper pointed inward.
• 66-souveraineai-overhaul — the public face; the Gatehouse is the private seat of the same house.