# Changelog All notable changes are recorded here. The authoritative history is `git log`; this file is the curated, human-readable summary. ## 2026-09-24 — AI-first package installation - **Shared installation workflow (`phoebus-executor::install`, ADR 0013):** `sys install `, `sys ask install ` and the explicit backend flags all run one flow: identify → evidence → AI investigation → deterministic validation + effects → review → approval → execute → verify → history. The AI only recommends; the resolver re-checks every proposal against real backend metadata and maps it to the existing broker action. - **Bounded investigation (`phoebus-ai::install`):** the model may request typed, read-only evidence (`discover_candidates`, `inspect_candidate`, `check_backend`, `inspect_installation`) and ask one bounded question about intent before proposing a structured `InstallProposal`. Bounds: turn, per-turn request and evidence-size limits plus repeated-request detection. A rejected proposal is fed back for a bounded revision. - **Friendly-name resolution and validation:** per-lane resolution (`chooser::resolve_for_backend`) maps friendly names to real identifiers, reports ambiguity, and never fabricates a candidate. Duplicate installs, stale versions and changed effects are refused; approval is bound to a digest and revalidated before execution. - **Explicit backend flags are authoritative:** `--portage`, `--flatpak`, `--nix`, `--snap`, `--appimage`, `--ebuild` bypass the model, are mutually exclusive, and never fall back to another lane. - **No-model path:** an unqualified install with no provider prints the deterministic selection and the explicit commands and installs nothing; provider failure is never permission to install. - **Install facts are real:** `sys` now loads the installed `/etc/phoebus/install.toml` instead of assuming defaults, and the bounded facts include free space, Wayland, the usable lanes, saved preferences and recovery capability. - **Transaction engine:** installs record an in-progress transaction before the mutation (`transaction::begin`/`finish`), verify installed identity/version afterwards, and record failures truthfully. - **ADRs/docs:** new `docs/adr/0013-ai-first-installation.md`; `docs/SYS.md` updated with the install workflow and acceptance cases 23–31. ### Verified (host) - `cargo fmt`, `cargo clippy --workspace --all-targets` (no new warnings) and `cargo test --workspace` pass. New tests cover: the AI loop (steps, bounds, repetition, revision, provider failure), resolver fabrication/ambiguity/ duplicate/changed-evidence, action mapping, transaction begin/finish, CLI flag conflicts/no-fallback/no-model, and target-vs-host facts. ### Not yet verified - Real VM installation journeys through `sys install` (AI-selected and explicit-backend) are the next gate; see `docs/HANDOFF.md`. ## 2026-09-24 — Hardware-aware software selection, Snap/AppImage/custom ebuild, `sys` lifecycle - **Shared selection policy (`phoebus-core::selection`, ADR 0006 revised):** replaced the fixed category routing (GUI→Flatpak, dev→Nix) with a single, inspectable, deterministic policy over resolved candidates from **every** lane (Portage source/binary/vendor, Nix, Flatpak, Snap, AppImage, custom ebuild). It separates hard constraints (architecture, required sandbox, storage, GPU, required proprietary, unavailable backend) from preferences; keeps kernel, drivers, systemd, graphics/audio and boot under Portage; honours and persists explicit compatible choices; errors instead of silently switching lanes; and reuses an already-installed lane to avoid duplication. Uncertainties are labelled (measured vs estimated compile time). - **Candidate resolution (`phoebus-executor::chooser`):** gathers real backend metadata (`emerge --pretend`, `flatpak search`, `snap find`, local Nix/AppImage records, the Phoebus overlay), assembles hardware facts (arch, cores, RAM, free space, GPUs, Wayland, compile history) and applies the policy. Unreachable metadata is reported as an unavailable candidate, never invented. - **Snap lane (`phoebus-executor::snap`):** detection of the client, daemon readiness and confinement; `find`/`info`/`list`/`install`/`remove`/`refresh`/ `connections`. `app-containers/snapd` is installed and `snapd.socket` enabled **through Portage**; classic confinement is explicit; automatic refresh is disclosed. - **AppImage lane (`phoebus-executor::appimage`):** managed import/acquisition with a pinned SHA-256 (placeholders and mismatches refused), ELF-architecture checks **without executing the image**, atomic adoption, desktop entry and optional icon extraction via `unsquashfs`, version/integrity records, and removal that preserves user data by default. AppImage is never called a sandbox. - **Custom ebuild lane (`phoebus-executor::ebuild`):** a dedicated `/var/db/repos/phoebus` overlay with recorded rationale and a content SHA-256. Staging never runs the ebuild; install requires the reviewed digest, generates the `Manifest` and builds through Portage with its sandbox enabled. Editing the staged ebuild invalidates approval. - **Typed actions + `sys` surface (`phoebus-core::action`, `phoebus-installer`):** `choose_package`, `set_package_preference`, `snap_*`, `appimage_*` and `custom_ebuild_*`, with strict validators (option-like operands, path traversal, placeholder hashes and bad names fail closed). Deterministic phrases cover the common cases; `custom_ebuild` staging/install stay JSON-only because they carry a full artifact. - **`sys` in the installed target:** the installer locates the trusted static `sys` beside itself, installs it to `/usr/local/bin/sys`, proves it runs in the target chroot before the recovery snapshot, and fails the install closed if it is missing. The VM install harness now fetches `sys`, and the rollback guest uses the installed binary. - **Assistant prompt reconciled:** the closed action set now includes the new actions and instructs the model not to route by category, to use `choose_package`, and to treat a custom ebuild as untrusted. - **Docs:** new `docs/SYS.md` command reference and acceptance matrix; revised ADR 0006. ### Verified (host) - `cargo fmt`, `cargo clippy --workspace --all-targets` (no new warnings) and `cargo test --workspace` pass; the new policy, backend and CLI tests run on the host. `installer/tests/vm/test_vmsafety.py` (18 tests) passes with the new `sys-acceptance.sh`. ### Not yet verified - The new lanes and the installed-`sys` lifecycle are unit/integration tested but **not yet exercised in a booted VM** in this session: a full GUI install was occupying the only disposable disk. The exact VM commands are in `docs/SYS.md` and `docs/HANDOFF.md`. ## 2026-09-23 — NVIDIA reliability, verification and harness repair - **Deterministic live GPU decision (`phoebus-core`, `phoebus-installer`):** `--live-gpu-plan` classifies the PCI display controllers (class `0x03`, vendor `0x10de`) against the generated device table and the bundled branch's capabilities, returning `load-nvidia`, `nouveau-fallback`, `no-device` or `disabled`. The live `phoebus-nvidia-load` script consumes it: a supported GPU loads the accelerated stack, an unsupported GPU (or a failed load) explicitly `modprobe`s `nouveau`, and a machine without an NVIDIA display device is left alone. `build.sh` now creates `etc/modprobe.d/phoebus-nvidia.conf` (the file the old build required but never produced) and replaces Debian's unconditional nouveau configuration. The fail-safe entry sets `nomodeset phoebus.nvidia=off`, which the script and the unit both honour. - **Legacy branch boundary corrected (`phoebus-core`):** Maxwell/Pascal/Volta are capped at NVIDIA's last supporting series (580) with `>=x11-drivers/nvidia-drivers-581` masked; a Blackwell plus proprietary-only GPU set is now reported as an explicit incompatibility instead of installing a single driver that cannot serve both. - **Payload verifier hardened (`phoebus-executor`):** `--verify-live-nvidia` now rejects placeholder modules/libraries, requires every module to be registered in the live kernel's `modules.dep`, normalises the dpkg revision and matches userspace/firmware versions to the bundled driver, infers and checks the module flavor, and requires the exact `phoebus-nvidia.conf`. All reads stay rooted inside the build root. - **Installed lifecycle fixed (`phoebus-executor`, `phoebus-installer`):** the NVIDIA dracut `force_drivers` fragment is written only in the NVIDIA stage, after the driver exists, and the final initramfs is regenerated then. The installer proves the modules were built for a kernel (or fails) and records the real resolved version, kernel and module names. The update path verifies the rebuilt modules before reporting success. - **GUI acceptance harness repaired (`installer/tests/vm/gui-driver.py`):** state-based step navigation replaces the step-0 keystroke count; the real account fields and the default single-password encryption are driven; the direct "Install now" action replaces ERASE typing and the (never-assigned) confirmation toggle; duplicate submission is exercised; install timeouts report stage, elapsed time and last state; the detached boot unlocks with the single-password passphrase and falls back to the separate one. - **Rollback acceptance automated (`installer/tests/vm/`):** a new `serial-driver.py rollback` mode with `rollback-guest.sh` / `rollback-verify.sh` records the package-database fingerprint and a `/home` marker, creates a recovery point with `sys snapshot`, performs a controlled reversible package install, runs `sys undo`, reboots detached and compares package state and `/home`. The destructive VM gate is written but unrun. - **Live privilege scoped (`phoebus-core`, `installer/live`):** the live `NOPASSWD: ALL` rule is replaced by an emitted, `visudo`-validated policy that grants unattended escalation only to the typed brokers (`phoebus-installer`, `sys`) and `systemctl` power actions. The recovery console is preserved via the password-authenticated live credential. - Docs: ADR 0012 updated; the stale "`gui_bridge` tests hang" handoff claim withdrawn (the workspace suite passes). ## 2026-09-23 — Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI - **Streamlined 6-Step Flow (`phoebus-install`, QML):** Eliminated the duplicate Step 0 welcome screen from the installer wizard; launch starts directly at "Step 1 of 6 · Language and keyboard" with an accurate 6-step progress indicator. The "Back" button is hidden on Step 1 and disabled for step 0 so back-navigation stays bounded. - **Friendly Keyboard & Locale Pickers (`phoebus-installer::gui_bridge`, `PhoebusCombo`):** Replaced raw two-letter codes (`al`, `dz`, `brai`) and arbitrary sorting with full layout names parsed directly from `/usr/share/X11/xkb/rules/evdev.lst`, sorting the top 30 world keyboard layouts and system locales first (e.g. `English (US) — us`, `German — de`). Selecting a layout dynamically switches the live Wayland keymap via `localectl set-x11-keymap`. - **Searchable Timezone Picker (`gui_bridge`, QML):** Populated the timezone dropdown directly from system zoneinfo, auto-detecting `/etc/localtime`. - **Welcome App Cleanup (`phoebus-welcome`):** Removed the redundant "Keyboard test" button and modal from the live welcome app. - **Single-Password Disk Encryption (`phoebus-install`):** Default-enabled "Use same password to encrypt disk" toggle with LUKS2, reducing credentials to username and password only without redundant confirmation prompts. Removed arbitrary 8-character minimum password restriction to accept any valid password. - **Direct Installation Confirmation:** Eliminated the requirement to type "ERASE" in all caps or check confirmation boxes; replaced with a direct, unambiguous "Install now" button on the review screen. - **Invariants Enforced Against AI Mutation (`phoebus-ai`):** Enforced Mango + DankMaterialShell desktop, Btrfs filesystem, and Flatpak/Nix core subsystems inside both the AI system prompt and semantic change validation; non-conforming AI proposals are automatically rejected. - **Loopback AI Auto-Detection & Clear Guidance:** Auto-probes loopback ports 4096 (OpenCode) and 11434 (Ollama) upon reaching the AI step, defaulting to detected local instances and replacing technical jargon with clear user guidance. - **Humanized Failure Reporting & Details Viewer:** Replaced raw curl/JSON dumps with clear humanized error summaries (e.g. package verification or network connection issues) alongside "[Retry]" and "[View technical details]" toggles. The live details terminal box properly fetches log lines and auto-scrolls to the latest activity. ## 2026-09-23 — Responsive display layout, resolution modal & hotkeys, and fullscreen installer - **Display Resolution Switcher & Hotkeys (`phoebus-welcome`, Mango config):** Added a dedicated 1-click Display Resolution dialog in `phoebus-welcome` allowing instant switching between 1920×1080 (Full HD), 1440×900, 1280×768 (Standard), 1024×768, and 800×600 modes without blurry bilinear scaling. Mapped global Mango hotkeys (`Super+Shift+F12` for 1080p, `Super+Shift+F11` for 900p, `Super+Shift+F10` for 768p, `Super+Shift+F9` for 1024x768) and set virtual display auto-probe to prioritize widescreen (1280x768) on initial boot. - **Low-Resolution Responsiveness & Scrollability (QML):** Wrapped both `phoebus-welcome` and `phoebus-install` form/progress views in bounded `Flickable` containers with `ScrollBar.vertical`. Added compact view adaptation (< 760px) in `phoebus-welcome` so the primary action stacks cleanly with flow-wrapped readiness chips, eliminating text clipping and ensuring all recovery tools and form controls are reachable on 800×600 and 640×480 screens. - **Fullscreen Installer Enforcement:** Closed the welcome window on launching the installer and set compositor fullscreen rules, eliminating any 50/50 window tiling splits. ## 2026-09-23 — Installer GUI usability, OpenCode model variants, and GURU mirror fix - **Gentoo GURU Official Mirror (`phoebus-core::system`):** Updated `GURU_REPO_URI` from the broken GitHub mirror to `https://anongit.gentoo.org/git/repo/proj/guru.git`, resolving the HTTP 404 failure that caused `emaint sync -r guru` to exit with code 1 during `portage_configure` in chroot. - **OpenCode Model Catalog & Variant Picker (`phoebus-executor`, `phoebus-installer`, QML):** OpenCode model selection now displays human-readable model titles alongside raw IDs (e.g., `DeepSeek V4.1 Flash (deepseek-flash)`). Added model variant selection supporting `default`, `low`, `high`, and `max` levels, defaulting cleanly to `default` and properly passing the variant into OpenCode session prompts. - **Live Terminal Output Streaming (`phoebus-executor::log`, `gui_bridge`, QML):** `Logger` and command execution runner now support subscriber sinks that stream stdout/stderr line-by-line in real time. The GUI bridge dispatches `log` events to the frontend over JSON-RPC, populating the "Show details" terminal box with live Portage compilation and command output rather than a static placeholder. - **Desktop Defaults & Keybindings:** Enforced Mango + DankMaterialShell as the default desktop configuration, standardized Btrfs and Flatpak defaults, simplified user account creation, streamlined confirmation workflow, and mapped standard DWM keybindings in Mango. ## 2026-09-23 — NVIDIA accelerated driver policy, live payload and installed integration - **Hardware-driven driver policy (`phoebus-core::nvidia`):** a deterministic, testable decision from the PCI display device IDs, backed by a generated table (`nvidia_devices.rs`) derived from the public PCI ID database via each device's NVIDIA chip codename. Turing/Ampere/Ada/Hopper/Blackwell use the current `x11-drivers/nvidia-drivers` branch with NVIDIA's **open** kernel modules (`kernel-open`); Maxwell/Pascal/Volta use the proprietary branch with `-kernel-open` and are masked `>=x11-drivers/nvidia-drivers-595`; Fermi/Kepler and older fall back to the in-tree `nouveau` and are reported, never claimed as NVIDIA success. Unknown NVIDIA device IDs are reported as unknown. - **Probe captures PCI identity:** display devices now carry `pci_id` (`vendor:device`) and `pci_address`; `VIDEO_CARDS` uses the resolved plan (`nvidia` only when a branch can serve the GPU, otherwise `nouveau`), while hybrid Intel/AMD GPUs are preserved. - **Installed Gentoo system:** scoped `package.use` (`dist-kernel`, `kernel-open`/`-kernel-open`), a scoped `~amd64` keyword for the driver atom, a scoped `package.mask` for the legacy branch, a `modprobe.d` policy (nouveau blacklist, `nvidia_drm.modeset=1`, `nvidia-uvm` softdep) and a dracut `force_drivers` fragment written **before** the kernel is built. A new `nvidia_drivers` install stage (after the kernel, before boot) emerges the driver and regenerates the initramfs so the modules are embedded; its failure fails the install and the resolved choice is recorded in `/etc/phoebus/nvidia` and shown in the plan. `sys update system` now runs `@module-rebuild` and `kernel-install add-all` on NVIDIA systems so kernel/module/initramfs updates stay coherent. - **AI boundary:** the model cannot change the driver branch or module flavor; a `set_package_use` change touching `x11-drivers/nvidia-drivers` is refused by the fixed-policy check and the advisor prompt says so. - **Live ISO:** the signed `contrib`/`non-free`/`non-free-firmware` components are enabled and the NVIDIA driver, firmware and Wayland/EGL/GBM userspace are bundled (`live-packages.list`). The live kernel is **pinned to Debian stable (trixie, 6.12 LTS)** because testing's newer kernel (7.2) removed the `strncpy` declaration the 550 driver still uses; installing the rolling kernel metas would make `nvidia-kernel-dkms` unbuildable. `livefs-hook.sh` builds the DKMS modules for that exact kernel (`nvidia-current*` on Debian) and fails if any module is missing. Nouveau blacklisting and module options come from Debian's own `nvidia-kernel-common`; its unconditional modules-load entry is replaced by a gated `phoebus-nvidia.service` that loads the driver before greetd/Mango only when an NVIDIA device is present. The documented fail-safe entry disables modesetting and blacklists the NVIDIA modules. `build.sh` verifies the assembled rootfs on **every** build (including `PHOEBUS_REUSE_ROOTFS=1`) with `--verify-live-nvidia` and records the bundled driver version, module flavor and kernel in `/etc/phoebus/nvidia`; a missing module, library or firmware file fails the build. - **Proven this session:** a minimal live rootfs (stable kernel + NVIDIA) was built with `mmdebstrap` and the payload verified end to end: driver `550.163.01`, kernel `6.12.107+deb13-amd64`, modules `nvidia-current`, `-modeset`, `-uvm`, `-drm`. The full desktop ISO was **not** assembled here (the host has ~10 GiB free and the build wants more), and no NVIDIA hardware was available, so acceleration is unverified. - **Not verified:** actual NVIDIA acceleration cannot be exercised on this host (no NVIDIA GPU; QEMU's virtual GPU does not establish it). No NVIDIA hardware passthrough setup is available or authorized. The live/installed NVIDIA boot gates are **unverified** here (see `docs/STATUS.md`); this is implementation + unit/integration tests + a proven payload build, not a claim of working hardware acceleration. ## 2026-09-22 — Installer UX streamlining and DWM keybindings in Mango - **Flatpak non-removable invariant:** Flatpak is a defining, required subsystem of Phoebus OS. Removed `set_flatpak` from the AI advisor action prompt and examples so models never propose toggling it; enforced in `fixed_policy_violation` and config validation that Flatpak cannot be disabled or removed; filtered redundant Flatpak proposals from the GUI review card; and locked Flatpak to 'yes (required)' in the TUI. - **DWM / DWL keybindings in Mango:** Packaged `MANGO_CONFIG_DEFAULT` now ships with standard dwm / dwl bindings for tiling and window management: `Mod+Shift+Return` (terminal), `Mod+Return` (zoom / promote to master), `Mod+j`/`Mod+k` (focus stack next/prev), `Mod+Shift+j`/`Mod+Shift+k` (exchange client), `Mod+h`/`Mod+l` (`setmfact` master area sizing), `Mod+i`/`Mod+d` (`incnmaster` master count), `Mod+Shift+c`/`Mod+Shift+q` (`killclient`), `Mod+t`/`Mod+m`/`Mod+f` (tile, monocle, fullscreen), `Mod+Shift+Space` (toggle floating), `Mod+Tab` (view previous tag), `Mod+1..9` (tag switching), `Mod+Shift+1..9` (tag moving), and `Mod+left/right/middle click` for window dragging, resizing and floating toggling. - **Full-screen installer window:** Closing the Welcome window when starting the installer allows Mango's tiling layout to present the installer full-screen. - **Scrollable dropdown menus:** Replaced the combo box with `PhoebusCombo`, a true dropdown menu with a clickable chevron, instant search filtering, and a scrollable `ListView` with vertical scrollbar that handles large lists without cutting off choices or destroying pre-filled selections. - **Desktop keyboard layouts:** Keyboard options now parse XKB rules (`/usr/share/X11/xkb/rules/evdev.lst` and `base.lst`) for clean desktop layouts with human-readable labels, replacing the ancient console keymap tree. - **Streamlined defaults:** Removed the manual desktop profile selector, filesystem selector, and Nix/Flatpak toggles from the UI; the installer now consistently defaults to Mango + DankMaterialShell, Btrfs with snapshots, and both Flatpak and Nix enabled. - **Account & password simplification:** Removed the redundant "Full name" field (username only). Removed the artificial 8-character password length limit. Added a "Use same password to encrypt disk" toggle (enabled by default) so users do not have to re-enter a separate disk passphrase across four fields. - **Direct confirmation:** Removed typing "ERASE" and the confirmation checkbox from the review screen; the overview screen clearly highlights the target disk and clicking "Install now" proceeds directly. - **Live progress log details:** The "Show details" button during installation now opens a dedicated scrollable log viewer that polls every 1.5 seconds and auto-scrolls to the newest output. ## 2026-09-22 — Event-driven analysis of a first-time user's journey The graphical installer was audited against a first-time user's journey and rebuilt around a fixed, explained sequence: Welcome, Language and keyboard, Internet and readiness, AI connection, Destination disk, Account and encryption, Review and confirmation, Installation, Completion. Configuration, validation, plans, approval and execution stay authoritative in Rust. ### Fixed - **Network "Re-check" no longer resets the wizard.** The readiness refresh is a separate, read-only bridge op (`readiness`) that updates the probe result only; it cannot change the step or clear the selected disk. The first handshake is the only path that initialises the form. - **AI catalogs are fetched for the connection on screen.** "Load model list" now pushes the edited configuration and credentials before requesting the catalog, classifies authentication/unreachable/model failures with a stable `error_kind`, and ignores a stale reply that a newer request superseded. - **The AI connection indicator is invalidated when it should be.** Editing the provider, model, endpoint, server or a credential clears the green "Validated" state and requires revalidation; irrelevant account or disk edits preserve it. A regression assert in the VM harness edits the model and checks the state flips. - **Suggestion lists are keyboard-operable.** Arrow keys move a visible highlight, Enter selects it, Escape dismisses the list, and the highlight is exposed through `Accessible` roles. Enter in an open list is consumed so it cannot also advance the wizard. - **Busy work always completes.** The bridge now fails every outstanding request when the backend exits, so no spinner can hang; AI connect/test and catalog loads are single-flight; every failure path clears its busy state and shows an actionable retry. - **Keyboard focus is scrolled into view**, so a keyboard user never tabs to an off-screen control, and the `PhoebusToggle` Return handler is fixed (it previously called a signal handler as a function). ### Changed - **Human-readable language, keyboard and time-zone names** (e.g. "English (United States) — en_US.UTF-8", "German — de") are returned by the backend; the stable identifier is still what is validated and written. - **The keyboard step tells the truth about the live session.** The live session keeps its own layout; the selected layout is applied to the installed system, and the typing test is labelled as testing the live keyboard. A live Wayland layout switch is not implemented. - **Internet readiness distinguishes a local link from reachable installation services** and re-checks on demand without disturbing the form. - **AI setup explains why a model is required and what is shared** (hardware and storage facts; never passwords, passphrases, keys, names or files), shows the proposed changes, and requires an explicit Accept or Discard before the step can advance. - **Disk selection prominently shows model, capacity and device identity**, and states exactly which disk will be erased; protected disks explain why they cannot be selected. The ERASE confirmation and approval binding are unchanged. - **The account step explains login password versus encryption passphrase**, and password reveal controls are keyboard-focusable. Technical settings moved behind Advanced. - **Progress shows real stages, elapsed time and activity**, with a redacted Details log; the failure screen explains whether disk changes occurred and what is safe to do next; completion explains restart, media removal, unlock and first login. - **The graphical harness gained a `gui-install` mode** that presses the real controls through the whole journey (AI connect, disk, account, ERASE, install) on a disposable disk, plus regression checks for readiness refresh, disk survival and AI invalidation. `PHOEBUS_GUI_CONFIG`/`/etc/phoebus/install.conf` let a live medium preseed wizard defaults without weakening any check. ### Verified - `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets` clean (pre-existing `result_large_err` advisories unchanged); the Rust workspace tests are green and `make test` (Rust + 16 harness tests) passes. - Disposable graphical VM: `gui` 28/28 PASS (welcome, launcher, duplicate prevention, keyboard suggestion selection, network, AI gate blocked and reported, no bridge errors) and `opencode` 18/18 PASS (real model response, validated proposal, model edit invalidates the connection). - `gui-install` passed every journey assertion on a fresh 30 GiB qcow2, including `gui-install-erase-confirmed`; the backend then reported real progress (disk prepare, stage3 download, fstab, Portage sync, base packages, kernel) with elapsed time and categories, and no fabricated percentage. The completed install itself timed out in the harness after four hours during a >100-minute kernel compile (see `docs/VM-BOOT-VERIFICATION.md`); the completed install + detached boot gate remains **BLOCKED on host build time**, not on any code defect. ## 2026-09-22 — `sys` administration hardening Correctness work on the deterministic `sys` broker and the assistant path that shares it. Every change is covered by unit tests (368 Rust tests pass); the destructive rollback VM acceptance remains unverified (see below). ### Fixed - **Alternate-root execution now targets the requested system.** Package execution, service enable/disable and Flatpak operations previously ignored `--root` and ran against the host, while `emerge --pretend` previews already ran in the target. All of them now go through one `target_spec`/chroot path, and operations that cannot be confined to a non-running root (service status, start, stop, restart) are **rejected before any command is built**. `systemctl --root` is used for offline enable/disable. Regression tests prove preview and execution both emit a chroot confined to the same root, and that a rejected operation invokes nothing. - **Validation at the execution boundary.** `parse_natural` emitted actions that were never validated, so a manual `sys install --color=n` could pass an option through. `parse_natural` now validates its own output, `resolve_effects` and `execute` validate every action before touching a command, and option-like operands (leading `-`) are rejected for services, packages and search. `emerge`/`flatpak` operands are passed after an explicit `--` separator. Manual, JSON and AI entry paths are all covered. - **`sys ask` reports failure truthfully.** A failing action now stops the plan, records the completed/failed/unattempted actions, and exits nonzero instead of returning success. - **Complete transaction history.** Ordinary mutating `sys` commands are recorded (previously only assistant plans were), the protective snapshot id created by the generic high-risk path is preserved and recorded, and a recording failure is surfaced instead of being swallowed. - **Reliable package approval.** `emerge --pretend` output is now classified as *established* (a real plan, including a genuine `0 packages`) or *unestablished*; `sys` refuses to proceed when the effects cannot be established rather than treating unparseable output as "nothing to do". A material change between review and execution still aborts. ### Added - Typed service lifecycle actions `start_service`, `stop_service`, `restart_service`, and ordinary commands for the existing bounded verbs: `sys flatpak install|remove|list`, `sys nix prepare …`, `sys snapshot [op]`, `sys start|stop|restart `. The AI prompt exposes the new verbs, so the manual and AI interfaces share one validated execution path. - `phoebus-executor::actions::execute_plan` runs a reviewed multi-action plan, stopping at the first failure and marking the rest unattempted, so the assistant and any multi-step caller report partial failure consistently. - CLI integration tests (`tests/sys_cli.rs`) cover the manual and JSON entry paths and exit codes. ## Unreleased ### Added - **Real OpenCode agent-server adapter.** `phoebus-executor::opencode_client` implements the OpenCode session/message protocol over the project's curl transport and the `ModelTransport` trait, so the strict proposal parser, evidence review, bounded facts and executor are reused unchanged. The GUI ("OpenCode agent"), the installer CLI (`--ai-backend opencode`, `--opencode-server/-provider/-model/-password-file`) and `sys ask` all use it. It creates a transient session per request, accepts only the completed assistant text parts, disables tools per message, and deletes the session. A JSON schema output mode is available in the protocol but is not used: the shipped DeepSeek models reject it, and the prompt carries an explicit change shape instead. The `opencode 1.18.32` contract was verified directly: session creation rejects a `model` field, `/provider` metadata can contain a credential and is reduced to ids/model names, and auth is HTTP Basic (`opencode` / `OPENCODE_SERVER_PASSWORD`). - **`--opencode-test`** obtains and validates a real model response (exit nonzero on failure), distinct from the read-only `--opencode-probe`. A live acceptance test (`make opencode-acceptance`) fails as BLOCKED when no server is configured, so it cannot pass by not running. - **Truthful OpenCode connection states** (`insecure_transport`, `unreachable`, `authentication_required`, `authentication_rejected`, `incompatible`, `reachable`, `model_catalog`, `selected_model_unavailable`); `ready` is reserved for a validated response and is never returned by the probe. - **GUI "Test connection"** and OpenCode connection controls, plus a backend selection (`ai.backend`) in canonical configuration. ### Security - **The mandatory-AI gate now requires a validated interaction.** Both the GUI bridge and the installer CLI refuse to install when only a provider name is configured; a successful, validated model interaction bound to the current configuration (and credential) is required. Changing the model, endpoint, server or a secret invalidates it. A direct provider or `--no-ai` remains the fallback. - **OpenCode transport policy is enforced.** Plain `http://` is accepted only when the resolved destination is loopback and the connection is pinned to the checked address; remote access is `https://` with certificate verification or an authenticated tunnel to loopback. Redirects, unsafe schemes and oversized or trickled bodies are bounded, and credentials travel only on curl's stdin. - **Credentials never surface.** The catalog is reduced to ids/model names; server responses that echo credentials are not retained, and tests feed credential-bearing bodies and assert they do not appear in errors or state. ### Verified - **The graphical installer uses the OpenCode adapter.** In a disposable graphical VM the wizard selected "OpenCode agent", entered the server, provider and model through the UI, obtained a real model response (Test connection) and a validated proposal (Connect and validate, green "Validated"). The `opencode` harness run passed 17/17 and the GUI regression 25/25. A password-protected server was reached through authentication as well. The full graphical installation beyond the AI gate is still not run. ### Fixed - **A malformed model proposal now gets one bounded corrective retry** before the strict parser rejects the interaction (the shipped DeepSeek models occasionally keyed the change or rationale wrongly). The parser remains the final authority; a retry that still fails is still rejected. - **OpenCode client/probe defects found by testing:** the handwritten HTTP reader (no total deadline, UTF-8-unsafe chunk fallback) was removed in favour of the curl transport; the catalog is no longer parsed on a non-2xx status; a provider-shaped 500 can no longer look like a catalog; the duplicate-session harness check requires exactly one session; and GUI navigation is asserted from secret-free frontend state lines rather than inferred from a screenshot. ### Added - **OpenCode connection workflow and capability probe.** New ADR 0011 and `docs/OPENCODE.md` separate the four components (client, server, model service, Phoebus broker) and document host-local and tunnelled remote use. `phoebus-executor::opencode_server` probes `/global/health` and `/config/providers` and reports a typed state (`disconnected`, `authentication_required`, `incompatible`, `reachable_no_model`, `ready`) instead of assuming a TCP connect or HTTP 200 means compatibility. Exposed as `phoebus-installer --opencode-probe ` (read-only, nonzero unless a model is available). Never returns provider credentials. Verified against the installed `opencode 1.18.32` (ready) and a deliberate unauthenticated LAN bind (`authentication_required`). ### Security - **The target disk is revalidated immediately before partitioning.** An approval now binds to a verified device, not a name: `storage_prepare` re-probes and refuses if the disk disappeared, became protected (mounted/read-only/live), or changed size/model since it was selected. Regression tests cover each case. - **The GUI bridge refuses replayed and overlapping installs.** An approval is single-use and consumed before destructive work; a second `start_install`, a retry or a reconnected frontend cannot start a second installation. Request lines and secret values are length-bounded; deeply nested JSON is rejected. - **Provider transport hardened.** Only `http(s)` endpoints are accepted, URLs with characters that could inject curl config directives are refused, the transfer is restricted to `http,https`, redirects stay disabled (so an `Authorization` header cannot follow a redirect to another origin), and the response is size-bounded (`max-filesize`). - **`TargetRoot` refuses symlink escapes.** `write`/`ensure_dir` reject a symlinked path component inside the target instead of following it, so a planted symlink cannot redirect an installer write to the host. - **Unauthenticated OpenCode endpoints are not treated as usable.** The probe reports `authentication_required` for a passwordless LAN bind rather than `ready`. ### Fixed - **Disk sizes are no longer reported as `0 B`.** `probe_disks` invoked `lsblk` without `-b`, so human-readable sizes (`30G`) failed the byte parse and every disk displayed `0 B`; the size-based disk-identity check was also blind. The `-b` flag is now used and pinned by a test. - **The welcome window's primary action is keyboard-reachable.** It now requests activation and force-focuses "Install Phoebus OS", so Return launches the installer (previously no focus ring was shown and Return did nothing). A regression test also rejects the non-existent `FloatingWindow.onActiveChanged`. - **The installer cannot be abandoned mid-install without explanation.** Escape during the destructive phase is refused and the UI states that the operation cannot be cancelled safely; the AI step shows its "connect and validate" guidance inline, beside the controls. ### Changed - **The VM harness enforces its own safety rules and reports structured results.** `installer/tests/vm/vmsafety.py` validates every writable drive (qcow2, inside `PHOEBUS_VM_DISKS`, no `/dev/*`, block/char devices, raw images, escaping symlinks or outside backing chains), gives each run its own OVMF variable file and QMP socket, uses structured QMP and argument arrays (no `os.system`), and returns nonzero on any failed assertion, timeout, EOF or missing result. Statuses are `PASS`/`FAIL`/`BLOCKED`/`SKIPPED`/`NOT RUN`. `make test` now runs the harness unit tests; `installer/tests/vm/report.py` builds a browsable run report. ### Added - **Graphical installation experience.** The live ISO now boots into a branded Phoebus welcome window (`phoebus-welcome`) that makes "Install Phoebus OS" the dominant action, shows ISO version and readiness (network, firmware, memory, cores) and keeps network/display/accessibility/help/keyboard-test/power tools available, with troubleshooting tools under Advanced. A full graphical setup wizard (`phoebus-install`) guides language and keyboard, network and prerequisites, AI model connection, destination disk (with protected disks and the installer medium identified), account and encryption, review, `ERASE` authorization, progress and completion. Duplicate installer sessions are prevented. The TUI/CLI remains the fallback. See ADR 0010 and `docs/VM-BOOT-VERIFICATION.md`. - **Typed JSON GUI bridge.** `phoebus-installer --gui-bridge` exposes a narrow, fail-closed protocol over stdin/stdout that reuses the same `InstallConfig`, validation, plan, `DestructiveAuthorization` and staged executor as the TUI. Approval is bound to a plan digest, secrets travel only over the stdin pipe, and real backend stages are reported with categories (no invented percentages). `Installer::install_observed` and an `InstallObserver` trait were added; `Installer::install` is unchanged. - **Phoebus brand system.** `phoebus-core::brand` provides charcoal/warm white/amber tokens plus a sun emblem, wordmark and wallpaper as deterministic SVG (emitted via `--emit-asset`, shared with the QML frontend), applied to the GRUB menu, live wallpaper, welcome window, installer, application icon and completion screen. Readable contrast and the QML/Rust palette are pinned by tests. ### Fixed - **Installed systems no longer default into recovery.** `loader.conf` now pins the newest real kernel entry, and the snapshot recovery entry carries a `sort-key` that keeps it after every kernel, so a low machine-id can never make systemd-boot select the recovery entry by filename tie-break. Previously an installed system could boot `systemd.unit=rescue.target` after reboot. - **DMS first-run dialogs are suppressed on the live medium** by pre-seeding DMS's own onboarding and changelog markers, so the installer is the first thing the user sees. - **The live-medium device is now identified.** `probe_disks` also inspects `/run/live/medium` and `/run/live/rootfs`, so the ISO is labelled as the installation medium (and remains protected). - **The installer shortcut is live-only.** `phoebus-install` and its desktop entry are no longer written to an installed system. ### Changed - **Mango + DankMaterialShell is now the default desktop** for both the installation ISO and the installed system (explicit owner decision). Omitted `desktop.profile` selects `mango`; Flatpak and PipeWire are on by default. Explicit `none`, `minimal`, `dwl` and `full` continue to work unchanged (ADR 0009). - **Installed login uses greetd + tuigreet.** Authentication is always required; the default session is Mango and the dwl entry remains selectable (`--sessions /usr/share/wayland-sessions`). Live autologin is a separate, live-only configuration and is never written to an installed system. ### Added - **Live desktop ISO**: `installer/live/build.sh` now builds a rootless Debian testing rootfs containing Mango (built from a pinned source release), DankMaterialShell (pinned, SHA-256-verified release tarball), Quickshell, scenefx, wlroots 0.20, greetd/tuigreet and the desktop integration, then splices it into the base Debian-Live boot equipment. The live user autologins into Mango, an "Install Phoebus" launcher opens the unchanged installer UI, and a serial/VT recovery console is retained. The build fails clearly if a required desktop component is missing. Debian packages never enter the Gentoo target. The built ISO was booted in a graphical, seat-providing VM: Mango + DankMaterialShell + Quickshell ran and a `screendump` captured the DMS panel and welcome window (`docs/VM-BOOT-VERIFICATION.md`). - Shared desktop assets are emitted from one source of truth by `phoebus-installer --emit-asset` and used by both the installer and the live build. Regression tests cover the default/overrides, login configuration, live/installed separation, session entries, pinned checksums and the live ISO desktop-payload guards. ### Added - **Mango + DankMaterialShell desktop option** (`desktop.profile = "mango"`): `gui-wm/mangowm` 0.17.2 (wlroots 0.20) plus `gui-apps/dankmaterialshell` 1.5.3 / Quickshell 0.3.1 / scenefx 0.5, installed through the GURU community overlay with scoped `~amd64` keywords (never global). The installer writes GURU's `repos.conf`, bootstraps `dev-vcs/git`, and syncs the overlay. A `phoebus-session-mango` entry point, a packaged Mango config seeded once into the user's config, DMS keybindings, a `mango-session.target` binding for DMS, and `phoebus-mango.desktop`/`phoebus-dwl.desktop` session entries are generated. dwl remains the fallback session and is installed alongside. The profile is selectable but **not promoted to default** pending graphical-VM verification (ADR 0009). ## 2026-09-21 — Coherent rollback, installed assistant, Nix isolation ### Added - **Coherent rollback and recovery** (`phoebus-core::rollback`, `phoebus-executor::rollback`): a recovery point now captures `@` **and** the separately mounted `@var` (Portage state) under one name; rollback creates a writable root generation, rewrites the restored root's fstab **and** the BLS `rootflags=subvol=`, selects a boot entry whose kernel modules match the restored `/lib/modules`, and writes "previous" and snapshot-based "recovery" entries. A persisted `rollback-state.toml` makes interruption safe and resumable; retention prunes old snapshots and protects in-flight targets; a 1 GiB free-space check gates the operation. See ADR 0007. - `sys undo` / `sys undo ` / `sys undo status` and the high-risk `undo` typed action. The installer now records a snapshot-based "Phoebus Recovery" entry at install time, so recovery does not depend on the live root. - **Installed conversational assistant** (`phoebus-ai::assistant`, `sys ask `): bounded facts -> typed plan -> concrete resolved effects -> approval/authentication -> deterministic execution -> transaction record. No model is required: `sys ask` falls back to the deterministic parser. - **OS-level model sandbox** (`phoebus-executor::sandbox`): the network call runs in a hardened, unprivileged transient systemd unit (`DynamicUser`, `ProtectHome`, `ProtectSystem=strict`, `NoNewPrivileges`, syscall and address-family filters). It fails closed when `systemd-run` is unavailable. - **Resolved package effects and approval binding** (`phoebus-core::effects`): `emerge --pretend` is parsed into additions/upgrades/downgrades/removals with source-vs-binary provenance and download size; a plan digest binds approval, and a material change between review and execution aborts. New bounded typed actions `flatpak_install`/`flatpak_remove`/`flatpak_list` and `nix_prepare`. - **Transaction log** (`phoebus-core::transaction`): assistant and `sys` actions record their actions, result and recovery point; `sys history` shows snapshots and transactions. - **Desktop completeness**: `phoebus-menu` (wofi drun launcher + power menu), `phoebus-lock` (swaylock), `phoebus-idle` (swayidle: lock, suspend, before-sleep lock) and a system-wide Waybar config with network, audio, battery, clock and power controls. - **Release gates** (`phoebus-installer::release`): a registry of the real candidate checks (install, detached boot, desktop, updates/rollback, no-model), a gate report that never records an unexecuted check as passed, atomic publication that preserves the last known-good `latest.iso.prev`, and signing/verification command helpers. - New VM harness for the Debian-Live appliance: `installer/tests/vm/appliance-driver.py`, `appliance-guest.sh` and `appliance-test.conf.example`. ### Changed - **Nix build isolation is enforced**: `sandbox = true`, `sandbox-fallback = false`, with store bounds (`min-free`/`max-free`) and `auto-optimise-store`. Lifecycle operations (remove/purge, gc) and a bounded `nix_prepare` action were added; the Portage-owned ebuild approach is documented in ADR 0008. See ADR 0006. - Desktops install `swayidle`/`swaylock` session helpers and a Waybar configuration; `phoebus-session` starts the idle daemon. ### Added - **Nix bootstrap (on by default, VM-verified).** `phoebus-executor::nix` fetches the pinned, SHA-256-verified official Nix release and bootstraps it into the target with discrete commands (store copy, `nix-store --load-db`, `nixbld` users, state dirs, profile and daemon units). A desktop VM confirmed `nix-daemon.service` active and `nix shell nixpkgs#hello` printing `Hello, world!`. A binary ebuild was ruled out: the upstream installer has no `DESTDIR` and runs `nix-store --load-db` against the real root. - `finalize` now flushes the target (`sync`) before unmounting, so late writes such as `/usr/local/bin/phoebus-session` and the exported installer log are on disk even after a forced poweroff. ### Changed - **Installing Phoebus now requires an AI.** The installer refuses an install with no provider unless the explicit break-glass `--no-ai` (alias `--legacy`, or `PHOEBUS_NO_AI=1`) is used. A new `local` provider (Ollama/llama.cpp/ LM Studio) and `--ai-endpoint` support a model the user downloaded; no model is shipped. - Desktop installs now include `sys-apps/xdg-desktop-portal`, `xdg-desktop-portal-gtk` and `xdg-desktop-portal-wlr`, so Flatpak and Wayland apps get file choosers and screencast support. ### Added - `sys` offline package commands: `sys install `, `sys remove `, `sys search ` (plus the `remove_package`/`search_packages` typed actions). They are deterministic Portage operations with no model involved — `emerge` resolves a bare name or a full atom — so the system stays fully administrable offline and without the assistant. - **Debian-Live installer appliance** (`installer/live/build.sh`, no root): a bootable Phoebus installer ISO built by overlaying the static installer, the OpenCode manifest and the Debian tools the live image lacks onto a Debian-Live stable base, with a serial-visible auto-booting grub config. The target stays Gentoo. See `docs/PLAN-DEBIAN-LIVE.md` and ADR 0005. - Git workflow: committed hooks (`.githooks/`), `scripts/check-secrets.sh`, `scripts/agent-commit.sh`, `scripts/publish.sh`, `scripts/setup-hooks.sh`. - Documentation set: `docs/OBJECTIVES.md`, `ROADMAP.md`, `STATUS.md`, `ARCHITECTURE.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`, `GIT-WORKFLOW.md`, `CHANGELOG.md`, and the top-level `AGENTS.md`. - `.gitignore` covering the ISO, build output, transcripts and secrets. ## 2026-09-20 — AI guidance, desktop reliability, snapshots ### Added - AI-assisted install guidance: an OpenAI-compatible provider layer for **DeepSeek** and **OpenAI** plus a test transport (`phoebus-ai::provider`), credential loading and a curl transport that keeps the API key out of argv, config and logs (`phoebus-executor::ai`), and CLI flags `--ai`, `--ai-provider`, `--ai-model`, `--ai-api-key-file`, `--ai-proposal-file`, `--ai-facts`. The TUI offers DeepSeek/ChatGPT/without-AI. - Typed proposal extensions: scoped `package.use`, explicit build jobs and binary-package preference. Every proposal now requires a non-empty reason and duplicate/conflicting changes are rejected before anything is applied. - `sys` history and update preparation are VM-verified on a Btrfs install. ### Changed - `phoebus-session` now starts `dwl` first, waits for the Wayland socket before launching waybar/mako/swaybg, establishes `XDG_RUNTIME_DIR` and a session bus, starts the polkit authentication agent, and reaps helpers on logout. - Portage policy: the unused `installkernel uki` flag is no longer forced, the duplicate/empty PipeWire/WirePlumber lines are gone, and the signed binhost is derived from the selected profile when unset. - Update preparation records a successful distfile fetch as ready even when `--buildpkgonly` is skipped because dependencies must be merged first, and the state note now includes the redacted Portage reason. ### Fixed - A high-risk `sys` action now creates its protective snapshot inside `actions::execute` and **fails closed** if the `.snapshots` subvolume exists but the snapshot cannot be created; corrupt snapshot history is surfaced instead of being hidden as empty. ## 2026-09-20 — Retire the Bash installer (migration Phases 0–4) ### Added - `phoebus-executor::opencode`: pinned-manifest parsing, architecture detection, fetch through `Exec`, SHA-256 verification, fail-closed placeholder checks, extraction and config writer (7 unit tests). - `--bootstrap-opencode` on the CLI; `PHOEBUS_OPENCODE_MANIFEST` overrides the embedded manifest for fixture verification. - `cli_coverage` and golden plan tests (`plan_golden.rs`, `tests/golden/`). - `docs/BASH-MIGRATION.md`: the evidence-gated retirement plan and ledger. ### Changed - The disposable VM harness installs with the static Rust binary; full encrypted install + detached boot re-verified (systemd PID 1, `running`, 0 failed units, LUKS, login). - CI, the pre-commit hook, the Makefile and the commit/publish scripts gate on Rust only (`cargo fmt`, `clippy`, `test`). - `installer/doc/VM-BOOT-VERIFICATION.md` and `installer/doc/FINDINGS.md` moved to `docs/`. ### Removed - The Bash installer tree (entry point, libraries, TUI, configuration, shell test suite and README), retired in favour of `installer-rs/`. The Bash reference remains tagged `v0.1.0-bash-reference`. The disposable VM harness under `installer/tests/vm/` is retained. ## 2026-09-20 — Rust installer parity, desktop, and foundations ### Added - Rust workspace (`installer-rs/`): `phoebus-core`, `phoebus-executor`, `phoebus-ai`, `phoebus-tui`, `phoebus-installer` (~9.4k LOC, 45 files). - Typed `InstallConfig` supporting TOML and the legacy flat format. - `TargetRoot` (host/target path safety), `SecretString`/`Redactor`, `DestructiveAuthorization`, central `Exec` command layer with dry-run. - Storage backend: GPT, ESP, LUKS2, Btrfs layout, fstab/crypttab, swapfile. - Stage3 fetch with pinned SHA-256 (or signed DIGESTS), Portage configuration, signed binary use, source builds, kernel, dracut, systemd-boot BLS. - Desktop/Flatpak: selects `default/linux/amd64/23.0/desktop/systemd`, writes `/usr/local/bin/phoebus-session`; flathub remote configured. - Package policy instrumentation: measured compile times parsed from `emerge.log` (326 entries recorded in the desktop run), persisted to `/var/lib/phoebus/compile-times.tsv`. - Snapshots: read-only Btrfs snapshots + TOML transaction history. - Background update preparation (`--fetchonly` + `--buildpkgonly`). - Typed `SystemAction` schema, privileged broker, and the `sys` command. - AI privacy boundary (`PrivacyPolicy`, `ContextBundle`, forbidden paths). - Release tooling: `phoebus-release` manifest/verify/sha256/assemble. - ratatui TUI with plan review and ERASE confirmation. - Recovery BLS entry booting `rescue.target`. ### Fixed - Subvolumes mounted before creation. - fstab/crypttab overwritten by stage3 extraction (moved to `fstab_generate`). - Missing `/var/tmp` breaking `kernel-install`. - `installkernel` requiring `uki_generator` even for BLS. - dracut `crypt` module and `systemd-cryptsetup` missing. - LUKS cmdline using `rd.luks.uuid` instead of `rd.luks.name`. - dracut UKI missing the kernel command line (BLS adopted). - `@swap` not mounted, breaking swap activation. - Portage GPG verify user unable to read the getuto keyring. - Transient rsync mirror quarantine (sync retries). - Pillow/HarfBuzz documentation circular dependency. - Legacy config silently parsed as TOML with defaults. ### Verified - Full encrypted UEFI install and boot with the ISO detached: `systemd` PID 1, `is-system-running = running`, 0 failed units, 10.73 s boot. - Desktop stack headless: dwl, waybar, mako, swaybg, `grim` screenshot, `wl-copy`/`wl-paste`, `wpctl`, `flatpak 1.18.1` + flathub. - No secret leakage in the installer log. ## 2026-09-19 — Bash installer prototype and first VM boot ### Added - Bash + `dialog` installer (`installer/`) with deterministic backend, TUI, plan/review, dry-run, logging, and destructive confirmation. - Read-only hardware/disk discovery with live-medium protection. - GPT/LUKS2/Btrfs backend, systemd stage3, Portage, kernel, systemd-boot, users/services/desktop modules. - Unit/regression suite and a disposable VM harness. ### Verified - First complete encrypted UEFI VM install and boot with the Bash installer. ### Fixed - The subvolume-ordering, fstab-timing, `/var/tmp`, `rd.luks.name`, `uki_generator`, cryptsetup, `@swap`, and `local root="$1" dir=...` bugs (these are the class of bug the Rust port is designed to prevent).