phoebus_os/docs/HANDOFF.md

604 lines
41 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Handoff
Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail.
- **System-wide stability audit & zero-panic hardening (2026-09-30, IMPLEMENTED + TESTED):**
Completed an exhaustive audit across all production crates to eliminate unexpected panics, fix subtle edge-case race conditions, and harden userspace agent protocols:
1. Eliminated all `unwrap()`/`expect()` panics in production code paths (`phoebus-installer::release`, `phoebus-installer::service::plan`, `phoebus-core::brand`, `phoebus-executor::chooser`, `phoebus-ai`, and `phoebus-executor::rollback`).
2. Fixed desktop checkpoint collision when mutations occur within the same second by using microsecond resolution and sequence counters (`desktop_config.rs`).
3. Fixed asymmetric undo: `undo_latest_checkpoint` now records whether files existed prior to mutation and removes newly created files when rolling back to an initially absent state.
4. Structured TOML serialization for MangoWM keybindings to prevent syntax breakage from unescaped quotes in actions.
5. JSON-RPC 2.0 error conformance for `phoebus-mcp` (handling parse errors and missing params with proper error frames).
6. Sanitized Bubblewrap `agent_jail` paths to filter out directory traversal (`..`) attacks.
7. Btrfs swapfile hardening: executed `chattr +C` on directory and on 0-byte file prior to truncation, avoiding Btrfs extent errors; enforced mode `0600`.
8. Inter-process lock drop safety: verified PID ownership prior to unlinking lockfile on drop.
Quality gates: `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace` all passed cleanly with 0 warnings and 0 errors.
- **System stability & reliability hardening (2026-09-30, IMPLEMENTED + TESTED):**
Implemented concurrency protection, package database consistency, and intuitive user workflows:
1. Inter-Process System Mutation Lock (`SystemLock`): Added PID-liveness-backed file lock at `/run/phoebus/sys.lock` (safe `/proc/<pid>` liveness check with automatic recovery of stale locks from dead processes) to prevent concurrent mutation collisions.
2. Coordinated Snapshot Pairing: High-risk mutations in `actions.rs` now invoke `snapshot::create_set_and_record` to create atomic paired `@` and `@var` Btrfs snapshots, preventing `/var/db/pkg` Portage database drift during rollbacks.
3. Atomic Transaction Persistence: Updated `transaction.rs` to write `transactions.toml` via tempfile + `sync_all` + atomic rename, eliminating partial/truncated file risk on sudden power loss.
4. System Health Overview: Implemented `SystemAction::SystemStatus` (`sys status`, `sys health`, `sys check`) querying BLS boot assessment states, reboot requirement, storage headroom vs the 10 GiB gate, Btrfs snapshots, and package lane readiness.
5. Intuitive CLI & Context-Aware Guidance: Unified `update`/`updates` -> `CheckUpdates` and `upgrade` -> `ApplyUpdates`; `sys install <app> --legacy` without a backend now dynamically resolves candidates across lanes via `chooser::resolve_candidates` to suggest exact copy-pasteable commands.
Gates: `cargo fmt`, `clippy --workspace --all-targets`, `cargo test --workspace` all pass.
- **Userspace-directed AI agent framework (2026-09-30, IMPLEMENTED + TESTED):**
designed and implemented a Two-Tier architecture for userspace developer/desktop
AI agents (e.g., Claude Code, OpenCode, Cursor, Codex). Added `agent_jail` +
`phoebus-agent-run` (Bubblewrap isolation with private tmpfs masking over `~/.ssh`,
`~/.gnupg`, keyrings, `.aws`, `.config/gh`), `desktop_config` + `phoebus-desktop`
(schema-validated MangoWM keybinding & DarkMaterialShell theme mutations with
automatic snapshot checkpoints and one-click `undo`), `phoebus-mcp` (standardized
Model Context Protocol stdio server), and `sys propose` (unprivileged plan
staging for Polkit elevation review). Fixed parent directory creation race
condition in `phoebus-executor::personal`. Workspace tests: 124+ passed, 0 failed.
- **Live real-agent call (2026-09-28, host, real model):** with a real
`opencode serve` (v1.18.32) on `127.0.0.1:4096` and the `opencode-go`
provider, `sys ask "list installed packages" --ai-backend opencode
--opencode-provider opencode-go --opencode-model deepseek-v4.1-flash`
returned a valid assistant plan + approval digest (read-only `list_packages`,
exit 0). A hostile instruction to read `/etc/shadow` and `~/.ssh` and run a
shell command was refused and downgraded to the read-only inventory; the
phoebus transport disables every OpenCode tool in the session, so the agent
has no shell/file access. No provider credential appeared in the sys log.
This is host-level live evidence (not VM); a VM/live-provider run with the
direct sandboxed transport remains NotRun.
- **End-to-end AI-path test (2026-09-28, IMPLEMENTED + UNIT-TESTED, no live
model):** new `installer-rs/crates/phoebus-installer/tests/sys_ai_e2e.rs`
drives the real `sys` binary against a real local OpenAI-compatible TCP stub
and the real curl transport (`--no-sandbox`, no seat). Four cases: a valid
model plan executes end-to-end; the request sent contains no `/home/` path and
no credential; a model `run_shell` fails closed after one corrective retry;
a `depclean` with a smuggled `shell` key is refused by the exact schema; and
malformed output fails closed after one correction. This is not a live-model
call (`sys ask` with a real provider is still VM/live NotRun) but it closes
the "connected-model path only tested with fake transports" gap. Gates:
`cargo test --workspace` 841 passed / 0 failed.
- **Three kernel choices + VM-found kernel bugs (2026-09-29):** added a
first-class three-way kernel choice (`bin` default, `balanced` source kernel
with broad hot-plug coverage, `tuned` source kernel) via the new
`BuildBalancedKernel` action / `sys build balanced kernel`; both source
choices keep `gentoo-kernel-bin` as the known-good fallback and create a
separate BLS entry. The first VM journey started the balanced build and found
two real bugs, both fixed: `vdb_has_atom("sys-kernel/gentoo-kernel")` matched
the sibling `gentoo-kernel-bin` record (prefix overlap), and the separate BLS
entry was looked up in `EFI/Linux` instead of the real `loader/entries`
directory. The build is in progress on a disposable overlay with
`MAKEOPTS="-j10 -l14"` (the installed default `-j3 -l8` is memory-derived and
too slow for a test build). Source conversion remains to be started.
**Result:** the full distribution config did **not** finish in 3 h (guest
`timeout` killed it at `RC=124`; 7.7 GiB build artifacts, no system change —
build-only is fail-safe). The review text now says "allow several hours"
instead of the earlier "20–60 min". Completing this journey needs a multi-hour
build window; the separate BLS entry path is unit-tested with the corrected
`loader/entries` directory.
- **OpenCode transport standardized (2026-09-29, VM-VERIFIED):** the OpenCode
backend no longer runs outside the model sandbox and no longer has a stricter
endpoint policy than the direct provider. It is sandboxed by default (curl
body inlined on stdin because `PrivateTmp` hides a temp file); `https` servers
on the network work as before, and remote plain `http` is allowed only with
`--opencode-insecure-http` / `PHOEBUS_OPENCODE_INSECURE_HTTP=1`. Re-verified in
the VM with the real host agent (`serial-boot-20260929T114319Z-c43c2a92`,
driver PASS=8). Next confidence work: VM-prove the approval-ledger/effect-binding
paths, source-conversion/tuned-kernel journeys (multi-hour), a physical-seat
desktop pass, and configure a CI runner for the release gates.
- **VM live AI (2026-09-29, VM-VERIFIED):** from inside the installed guest,
the host's real `opencode` agent was reached through the loopback tunnel and
`sys ask` produced a valid plan (`live-agent`), with a hostile instruction
refused/downgraded (`live-agent-hostile-rejected`)
(`serial-boot-20260929T102703Z-ffd1ec25`). A real local model (Qwen2.5-1.5B
GGUF via `llama-server`) was also driven through the direct sandbox in both
scopes; it reached the model but failed closed on schema-noncompliant output.
The assistant prompt now shows a concrete action-object example
(`{"action":"list_packages"}`), which made the small model emit action
objects; a capable model is still required, and a 4096-token local context
can be exceeded by the one-shot correction turn. Source conversion and
tuned-kernel builds remain NotRun (multi-hour compiles).
- **Real powerful model via the host agent, `sys` in the VM (2026-09-29,
VM-VERIFIED):** four requests through `opencode`/`deepseek-v4.1-flash`:
`list` and `search firefox` return valid grounded plans; `install firefox
--flatpak` as the user stops before mutation; hostile shell/private-file
instruction refused (`serial-boot-20260929T111941Z-2be30b89`, PASS=8, zero
auth prompts). A read-only Flatpak probe had hung on Flatpak's interactive
`appstream-update` (pkttyagent) on the headless console; `CommandSpec::detached()`
now runs host-root Flatpak commands with no controlling terminal. The install
prompt now enumerates the allowed `kind` values (a capable model had guessed
`kind:"gui"`). The install investigation itself still stops on the model's own
request-count/formatting limits and fails closed (no `sys` defect).
- **First VM test loop on the golden image (2026-09-28, VM-VERIFIED):** booted a
fresh overlay of the installed `phoebus-headless-80g.qcow2` with the static
`sys` from HEAD and found two real defects, both fixed. (1) Unprivileged
`sys ask` hung on a polkit `manage-units` prompt because the model sandbox
used the **system** `systemd-run`; it now uses `systemd-run --user` with the
user-manager property subset for non-root callers, full system sandbox for
root. (2) An unprivileged read-only AI plan exited 1 after printing the plan
because the service layer required the root-owned transaction log; recording
is now best-effort for non-root plans and mandatory for privileged mutations.
VM evidence (`serial-boot-20260929T092147Z-6f88907a`, PASS=8): system sandbox
`AI_ROOT_RC=0`, user sandbox `AI_USER_RC=0` (was 124/timeout), no-sandbox
`AI_NOSANDBOX_RC=0`, hostile reply `AI_SHELL_RC=1`, and
`sys-acceptance.sh` `SUMMARY PASS=49 FAIL=0`. Hypothesis recorded (not
changed): headless/inactive-session `flatpak search` can trigger Flatpak's
interactive `appstream-update` polkit prompt; the unattended acceptance runs
detached to avoid the hang. Additional loops on the same golden overlay with
the fixed binary: mutating acceptance as root `SUMMARY PASS=42 FAIL=0`
(`serial-boot-20260929T093329Z-4ef893cf`), rollback `PASS=11`
(`serial-rollback-20260929T094640Z-256c2ba1`), Snap journey `PASS=11`
(`serial-boot-20260929T094957Z-3d4a9211`). Next: source conversion / tuned
kernel (multi-hour compiles) and a live direct-provider model in the VM remain
NotRun.
- **Boundary-hardening pass (2026-09-28, IMPLEMENTED + UNIT-TESTED, VM NOT
RUN):** six host-provable defects fixed with regression tests. (1) Removed
the `PHOEBUS_ALLOW_UNPRIVILEGED_EXEC=1` env backdoor: it made
`service::effective_uid()` report uid 0, letting a non-root desktop-assistant
client skip `pkexec` + the approval ledger and run a root-requiring plan
in-process. (2) `load_api_key` now refuses a credential containing `"`, `\`,
whitespace or a control character (it is interpolated into a curl config
`header = "..."`). (3) The OpenCode base64 Basic/Bearer token is now
registered with the redactor (only the plaintext was). (4)
`SystemFacts::validate_no_forbidden` now scans `cpu_features` (it was
omitted). (5) `validate_endpoint` refuses userinfo
(`https://user:pass@host/...`). (6) The AI assistant/install parsers now use
`phoebus-core::action::validate_action_value`, closing a unit-variant
`deny_unknown_fields` bypass (`{"action":"depclean","shell":"sh"}` was
accepted on the AI path). Gates: fmt clean, `clippy --workspace
--all-targets -- -D warnings` clean, `cargo test --workspace` 837 passed / 0
failed, release build. **NotRun:** VM `systemd-run` sandbox exercise — host
probe shows system `manage-units` requires polkit auth and the full property
set is invalid for `--user` (DynamicUser unsupported; PrivateDevices fails);
a VM run as the `phoebus` user on a seat is required to settle whether the
sandbox is usable unprivileged or must switch to `--user` with a reduced
property set. Also NotRun: source-conversion/tuned-kernel journeys (need a
disposable install + reboot); Snap changed-revision/strict confinement
(external prerequisite). Identified but deliberately unchanged: Flatpak/Snap
**install** drift binds the human version only (no commit/revision);
`SnapRefresh` has no review binding; `UpdateSystem`/world-update has no
post-verification; `PrepareUpdates` records `ok` with a truthful
"prebuild skipped" note. Recorded as hypotheses, not reported holes.
- **`sys` adversarial battery + hardening (2026-09-28, IMPLEMENTED +
UNIT-TESTED, VM NOT RUN):** new `installer-rs/crates/phoebus-installer/tests/
sys_adversarial.rs` (54 cases: shell injection per operand, empty/NUL,
lengths, Unicode/homoglyphs, traversal, option injection, malformed/nested
JSON, CLI flag conflicts, natural-language edges, boundaries, privilege
gates) exercising the `phoebus-core` validators and the `sys` binary under
`PATH=/nonexistent`. Found and fixed 5 real gaps, each regression-tested:
`valid_file_path` shell metacharacters + `..` (doc contract previously
unimplemented); `valid_application_name` `..`/empty components + leading
slash; `valid_ebuild_atom` `.`-leading components, closing a real overlay
path traversal (`../pkg`), plus `ebuild::package_dir` re-validation;
`valid_flatpak_app_id` empty reverse-DNS element; `valid_nix_attribute`
leading dash. Gates: `cargo fmt --all -- --check` clean, `clippy
--workspace --all-targets -- -D warnings` clean, `cargo test --workspace`
828 passed / 0 failed. VM rerun of the acceptance matrix remains NotRun.
- **`sys` flaw-fix battery (2026-09-28, IMPLEMENTED + UNIT-TESTED, VM NOT RUN):**
fixed 6 audited flaws: versioned/slotted/repo atoms now validate
(`valid_package_spec`), quoted multi-word app names parse in legacy
install/remove, `vdb_has_atom` normalizes (executor + kernel), Flatpak
install/remove pin `--system --noninteractive`, and `who owns <relative path>`
is normalized. Added host battery `installer-rs/crates/phoebus-installer/tests/
sys_flaws.rs` (9 tests) and `sys-acceptance.sh` service-lifecycle / versioned-
atom / who-owns cases. Gates: `cargo fmt --all -- --check`, `clippy
--workspace --all-targets`, `cargo test --workspace` 773 passed, `bash -n` +
`shellcheck` clean. VM rerun of the expanded acceptance matrix is NotRun.
- **Headless stabilization run (SELF-HEALING LOOP ACTIVE, run 10 IN FLIGHT):**
Failures so far, each fixed + committed + verified green (761 tests) + rerun:
1. Brave overlay pin missing → recorded reviewed pin `d3a97f22…` (`0aa31a3`).
2. `/bin/zsh` missing at `users_configure` (Zsh lane only in desktop, which
runs later) → shell lane moved to `base_packages` (`5ea4bb1`).
3. `zsh-autosuggestions` masked `~amd64` → `accept_keywords_shell()` wired
into the GURU block (`ff104dd`).
4. GURU `zsh-autosuggestions` needs `>=zsh-5.9.1`, stable is `5.9-r7` →
keyworded `app-shells/zsh` itself (`6972511`).
5. `swayimg` REQUIRED_USE `exactly-one-of lua_single_target_*` (profile
enables none) → `media-gfx/swayimg lua_single_target_luajit` (`3abdc87`).
6. `gui-apps/matugen` does not exist (GURU sparse-index proof) → corrected
to `x11-misc/matugen` (`f480c9c`).
7. `nemo` needs `libxmlb[introspection]`, binhost lacks it → scoped
`dev-libs/libxmlb introspection` (`0036529`).
8. Same class: `xapp[introspection]` → scoped xapp + pre-emptive libsecret/
cinnamon-desktop introspection + mpv luajit (`8a0dfdf`).
9. Same class: `libdbusmenu[gtk3]` (xapp dep) → scoped it plus the rest of
the ebuild-read closure: `gdk-pixbuf`/`gtk+` introspection (`233a3e2`;
closure read from gentoo.git tree, no checkout).
10. Run 10 reached 285/346 desktop then the DRIVER (not the guest) gave up:
`serial-driver.py` install expect timeout was 9000 s (2.5 h) but full
Mango needs ~3.5 h; QEMU was killed with the guest mid-emerge →
`24b11eb` raises it to 19800 s (5.5 h).
11. Run 11 reached 346/346 then failed enabling seatd: Gentoo's seatd
ships its systemd unit only with USE=`server`; our package.use set
flags on libseat but not on seatd itself → `add7dfc` adds
`sys-auth/seatd server systemd builtin`.
12. Run 12 reached `finalize` then failed its own check: the VDB verify
matched a literal `category/name` directory, but VDB entries are
`category/name-version` → `has_vdb_record()` prefix match + regression
test (`2b8559f`).
13. Run 13 COMPLETED GOLDEN (`===INSTALL-RC=0===`, `NO_SECRET_LEAK`,
serial dir `serial-install-20260928T002557Z-e39d1934`). All 12 stages
passed, 347 desktop packages emerged, 588 compile times recorded into
metrics, coordinated snapshots `@-20260928T060439-initial-known-good`
and `@var` created.
- **Detached boot proven (`serial-boot-20260928T075316Z-c1918e9c`):**
Booted detached disk with `-boot order=c` (no ISO). LUKS2 decrypted,
systemd running with 0 failed units. `seatd.service` active and running
(`/run/seatd.sock` 0660 root:seat, `phoebus` in group `seat`). Fast-defaults
verified in Gentoo VDB (`firefox-bin`, `libreoffice-bin`, `thunderbird-bin`,
`brave-browser`) and Flatpak (`calibre`, `gimp`, `flatseal`). Acceptance
suite passed 40/40.
- **Next:** `scripts/publish.sh` to push commits to `origin/main`.
- **Run 14 (IN FLIGHT, pristine record with all fixes):** new static
binaries from HEAD (`phoebus-installer` `183ec40b…`, `sys` `d5f7a46f…`);
driver pid 2485744, serial dir
`serial-install-20260928T091251Z-8e9c8076`, chain pid 2494536. Includes
the nix file-perm fix (`c806c98`), opencode Local default (`2261c54`),
zsh-prompt + equals fixes, setsid acceptance, and the guest loopback
tunnel (`fwd.py`, with the `settimeout(None)` long-reply fix).
- **Run 15 (COMPLETE GOLDEN, 2026-09-28):** `INSTALL-RC=0` (driver 4/4,
serial `serial-install-20260928T132731Z-b5f8629a`), no leak; detached
boot driver 4/4 (`serial-boot-20260928T183131Z-953e4677`: systemd
running, 0 failed, seatd active, clean poweroff); 40/40 acceptance; nix
per-user hello enumerated from install perms alone (`/etc/nix*`
world-readable — the `bc0c4b8` ordering fix proven); `AI_LIVE_RC=0`
(valid plan + digest, muse-spark-1.3-contributor). Evidence in
VM-BOOT-VERIFICATION.md / STATUS.md / CHANGELOG.md. Next: publish.
- **Seat/thunderbird/AI-timeout session (IMPLEMENTED + UNIT-TESTED, VM NOT RUN):**
P0 seat fix (seatd pkg + enabled before greetd, libseat systemd/builtin/
server USE, `seat` in default groups, greeter `-G video,input,render,seat`,
3 s bounded seat wait in the session script, `LIBSEAT_BACKEND` deliberately
unset), thunderbird-bin fast default + `SOURCE_CONVERSIONS` entry + welcome
text (all lanes untouched; mandatory-AI requirement unchanged), and
`CurlTransport` timeout 120 s → 300 s default via `PHOEBUS_AI_TIMEOUT`
(fail-closed parsing). Gates: fmt, clippy `--workspace --all-targets -- -D
warnings`, 759/759 tests (was 757), `bash -n` session script. Seat-VM
reverification, thunderbird installed-identity/conversion journey, and live
CPU-inference timeout proof are NotRun (no VM run this session).
- **Zsh modernization (2026-09-26, IMPLEMENTED + UNIT-TESTED, VM NOT RUN):**
rewrote `ZSH_SKEL_RC` (color fix, cached compinit, Kitty keybindings,
`INC_APPEND_HISTORY`, vcs_info git branch, exit-status prompt) and added
`ZSH_ZPROFILE` (`/etc/profile` bridge + `~/.local/bin`); `seed_default_zsh`
uses the new const. Gates: fmt, clippy `--workspace --all-targets -- -D
warnings`, 757/757 tests, `zsh -n` + interactive startup smoke on host zsh
5.9. Seeding is once-only (existing `~/.zshrc` preserved). Installed-session
behavior (login env, Nix paths, prompt/git/keys in Kitty) awaits the
disposable VM. Uncommitted; `docs/DUAL-BOOT.md` from the prior session also
still uncommitted.
- **Fast-defaults follow-up (2026-09-26, ISO BUILT + CONTENT-VERIFIED, VM NOT RUN):**
audited the `e747baf` fast-defaults tree against the prompt (all lanes
covered, no code changes needed), re-ran gates green (fmt, clippy -D,
757/757 tests, release build, vmsafety 18/18, shellcheck info-only),
rebuilt the static binaries from `e747baf` (`phoebus-installer`
`8cf90d0f…`, `sys` `c87557…`), and built a fresh ISO
`phoebus-installer-amd64-fastdefaults.iso` (1.6 GiB, `ad9cddb2…`, build
`20260926T145700Z`, `PHOEBUS_REUSE_ROOTFS=1`; git-ignored) with
content verification (embedded binaries hash-match, Gentoo key both
fingerprints, Mango/DMS + installer UI present). NO install/boot this
session — wall-clock blocker (full Mango install ~165 min; host ready:
doctor 20 ok, ~103 GiB free); all install/boot/graphical/source/tuned
gates NotRun with exact unblock in VM-BOOT-VERIFICATION.md. Next:
disposable 80 GiB install of the `ad9cddb2…` ISO + detached boot, 37-case
acceptance, graphical/file/device/source/tuned gates.
- **Interface contract (unchanged):** ordinary requests use AI; only explicit
`--legacy` selects deterministic handling; source flags constrain the AI and
never bypass it; a missing model stops the workflow and offers the exact
`--legacy` command without executing it.
- **Fast-defaults session (2026-09-26, IMPLEMENTED + UNIT-TESTED, VM NOT RUN):**
Firefox/LibreOffice as `-bin`, Calibre/GIMP/Flatseal as target-only
system-wide Flatpaks (no Portage duplicates), single generic kernel,
delivery section in plan review + progress log, install metrics hooks,
preference neutrality guard, `convert_to_source` (Firefox/LibreOffice/
Calibre/GIMP; Brave refused with reason) + `build_tuned_kernel`
(separate BLS, fallback kept, default only after test boot) typed actions
with full reviews through the existing approval/broker path, installed
once-per-user reopenable non-blocking welcome + DMS skel seed, portal/MIME
defaults with no sandbox overrides. Gates: fmt, clippy -D, 757 tests
(was 736), release build, vmsafety 18/18, shellcheck clean. NO new ISO,
NO install/boot this session — session-time blocker (host ready: doctor
20 ok, 104 GiB free); all VM gates NotRun with exact unblock in STATUS.
Next: build ISO, disposable 80 GiB install + detached boot, 37-case
acceptance, graphical/file/device/source/tuned gates per
VM-BOOT-VERIFICATION.md.
- **Interface contract (unchanged):** ordinary requests use AI; only explicit
`--legacy` selects deterministic handling; source flags constrain the AI and
never bypass it; a missing model stops the workflow and offers the exact
`--legacy` command without executing it.
- **Workstation experience session (2026-09-26, IMPLEMENTED + UNIT-TESTED, VM BLOCKED):**
Mango workstation atoms (22 apps, exact, no substitute; Kitty kept, Nemo
default, CUPS local-only, sshd installed/disabled), Brave stable scoped
overlay (pin pre-network fail-closed; no pin recorded yet), Zsh-by-default
+ packaged plugins, Vanilla-DMZ 24 cursors, default ccache 2G, AI reuse
handoff (per-user 0600 key, truthful status, no Approve&Execute on errors),
startup-check model (blur optional, PPD+D-Bus, matugen, cava) with truthful
summary, assistant dark-default + light + responsive + token-drift guard,
60/20 GiB disk gates. Gates: fmt, clippy -D, 736/736 tests, release build,
vmsafety 18/18, shellcheck info-only. NO new ISO (8 GiB free, needs ≥20;
target needs 60–80), NO install/boot this session — all VM gates NotRun
with exact unblock in STATUS. Next: free ≥80 GiB, pin Brave commit, build
ISO, disposable 80 GiB install + detached boot, seat-VM compositor/cursor/
DMS/theme checks, fixture + live-AI handoff, local CUPS job, sshd-disabled
+ PPD D-Bus recheck after reboot.
- **Interface contract (unchanged):** ordinary requests use AI; only explicit
`--legacy` selects deterministic handling; source flags constrain the AI and
never bypass it; a missing model stops the workflow and offers the exact
`--legacy` command without executing it.
- **ISO rebuild + verification session (2026-09-26, DONE except seat-compositor):**
new ISO `installer/live/phoebus-installer-amd64-20260926.iso` (1.6 GiB,
`250dbe9a…`, build `20260926T041500Z`, HEAD `11c0ee0` + `0b41781`) built
via `PHOEBUS_REUSE_ROOTFS=1`, content-verified (embedded hashes match,
Gentoo key both fingerprints, UI payload present); old Sep-24 ISO kept.
Interactive VM RUNNING (KVM/GTK, `phoebus-interactive-20260926.qcow2` +
private vars in `/var/tmp/phoebus-interactive/`, screenshot at welcome,
undisturbed). Unpinned signed-DIGESTS full install PASSED
(`gui-install-20260926T040728Z-f3ae68f4`, `INSTALL-RC=0`,
`NO_SECRET_LEAK`, ~165 min) + detached boot (running, 0 failed units,
`sys --legacy` + snapshot). Tamper refusals PASSED (placeholder pin
pre-network, hash mismatch post-download, both `RC=1` + no leak).
Recovery-entry boot PASSED (snapshot cmdline/findmnt, login, `sys
--legacy`, truthful `ask` failure, systemd degraded). Seat desktop
PARTIAL: seat0/DRM/greeter/auth verified, Mango dies in <1s (libseat, no
seatd) — the blocker. Snap: no Store revision, still partial confinement.
Nix: GC-dangling NOT reproduced; **new gap: modern per-user Nix profiles
invisible to `sys`** (follow-up). Live AI: still no credential/model
(NotRun). `gui-driver.py` boot sys-check fixed (`--legacy`).
`gates --execute`: 0/0/6 NotRun, no publish. Quality gates green
(717/717, clippy -D, vmsafety 18/18). Evidence disk
`disks/unpinned-accept-1.qcow2` KEPT; scratch overlays removed.
Next: seatd-or-logind fix for Mango (design+rebuild+retest), per-user Nix
enumeration, live AI credential, snap revision/strict, NVIDIA.
- **Security/readiness follow-up (2026-09-26):** trust anchor + executable
gates + strengthened rollback PASS.
1. **Stage3 trust anchor (fixed):** `release_key_path()` ignores
`PHOEBUS_GENTOO_RELEASE_KEY`; production always uses the provisioned
key, test injection only via explicit `verify_digests_with_key`.
Host-level Good-signature check of the real DIGESTS passes (not VM
evidence). VM proof blocked: needs a rebuilt live ISO + disposable
install (exact prerequisites in `docs/VM-BOOT-VERIFICATION.md`).
2. **Release gates executable:** invalid `checks`/`desktop` modes fixed
(real `boot` modes), `--execute` runs each argv and reports
Passed/Failed/NotRun from evidence (unconfigured host: 0/0/6, publish
refuses). Found and fixed a `gui-driver.py` SyntaxError. 6 new tests.
3. **Strengthened rollback rerun PASSED**
(`serial-rollback-20260926T034218Z-7fab51ef`, PASS=11 FAIL=0, exit 0,
no leak, overlay `rollback-accept-8.qcow2`): mandatory
`===ROLLBACK-MARKER present===` before undo, DB `ca398d71…`→`fda3780a…`
→restored, marker absent after detached reboot, `/home` survives,
systemd running. `SERVE` shellcheck fix included.
4. **Recovery-entry boot** is now a distinct manual gate with its own
procedure (NOT RUN). Roadmap no longer lists passed `sys undo` as
unfinished; Secure Boot filed as a separate opt-in milestone.
5. Quality gates: `cargo fmt --check`, `clippy --workspace --all-targets
-- -D warnings`, `cargo test --workspace` 717/717 (one
`assistant_bridge` flake under parallel load, green in isolation and
on rerun), release + static-pie builds, `test_vmsafety.py` 18/18,
`shellcheck` clean. Seat desktop, live AI, Snap revision/strict, and
NVIDIA stay open with exact prerequisites (STATUS).
- **Interface contract (unchanged):** ordinary requests use AI; only explicit
`--legacy` selects deterministic handling; source flags constrain the AI and
never bypass it; a missing model stops the workflow and offers the exact
`--legacy` command without executing it.
- **Hardening pass (2026-09-26):** stage3 fail-closed + truthful boot
security + rollback acceptance PASS.
1. **Stage3 (security defect, fixed):** the unpinned path warned and
continued on DIGESTS-download failure, missing SHA-512 entry, missing
gpg/key, failed key import, and gpg launch errors. All stop the install
before extraction now; bad signature/hash also stop it. The pinned path
requires a valid 64-hex pin (placeholder refused) before any network
use. `stage_install` checks for `gpg`/`sha256sum`/`sha512sum` first.
16 new regression tests (every failure branch, nonzero-exit and
cannot-start doubles, both positive paths). The live image ships `gnupg`
plus the Gentoo release key, fingerprint-checked at build time against
Gentoo's published fingerprints (`13EB…2910` weekly, `D99E…2058`
signing). Commits `2162670`, `744059b`.
2. **Boot security (fixed):** `uki=true`/`secureboot=true` are rejected at
`validate_config` (shared by CLI/TUI/GUI bridge); the plan preview
always reports unsigned BLS. Parsing/validation/rendering regressions +
golden updated. Commit `95e0d05`. Authenticated boot stays an open
limitation (STATUS).
3. **Rollback acceptance PASSED for real**
(`serial-rollback-20260926T030237Z-912f6386`, PASS=11 FAIL=0, exit 0, no
secret leak): fresh overlay `rollback-accept-7.qcow2` on
`fresh-install-1.qcow2` — snapshot → `app-misc/hello` install (DB
`ca39…`→`fda3…`) → `sys undo <id>` rc=0 → detached reboot (DB restored,
root marker absent, `/home` survives, systemd running, recovery entry
present). The 2026-09-25 pass claim had no transcript and did not
reproduce; fixed harness defects: sudo auth (stale-prompt match bug
found and fixed with unique markers), root phases, explicit `--legacy`,
verified break (`nano` was pre-installed), targeted undo, marker-absent
assertion, preserved phase-1 log. Commits `744059b`, `5f69996`.
4. **Release candidate (local, isolated):** manifest (2 artifacts), verify,
tamper refusal, and publish refusal against the NotRun report all behave;
`gates --execute` is 0 passed / 6 NotRun (every gate needs VM/seat/model;
`run_gates` never executes gate commands itself). Nothing published.
5. Quality gates: `cargo fmt --check`, `cargo clippy --workspace
--all-targets -- -D warnings`, `cargo test --workspace` 712/712,
release + static-pie builds, `test_vmsafety.py` 18/18, `make doctor`
19 ok / 1 disk-space warning.
- **Interface contract (unchanged):** ordinary requests use AI; only explicit
`--legacy` selects deterministic handling; source flags constrain the AI and
never bypass it; a missing model stops the workflow and offers the exact
`--legacy` command without executing it.
- **Quality pass (2026-09-26):** boxed `ExecError::Command` details
(`CommandFailure`, 128 → 96 bytes, measured with a path-dependent probe crate;
constructor + all match sites updated, error text/redaction/stderr-tail
preserved, 4 regression tests), cleared `cargo clippy --workspace --all-targets
-- -D warnings` with no blanket allows (type alias, `CommandRecord` params
struct, `DiskPhase` renames), and split `service.rs` (4218 lines →
`service/mod,plan,validation,execution,tests`) and `gui_bridge.rs`
(2763 lines → `gui_bridge/mod,protocol,bridge,tests`) as structural refactors
with explicit re-exports and `pub(super)` seams — no `service.rs` left
alongside `service/mod.rs`. `make test` green (692/692, unchanged across the
splits). Release + static-pie builds pass. The disposable VM re-ran the
current 38-case `sys` acceptance matrix against the new static `sys`
(`70f0a72b…`): guest `PASS=38 FAIL=0`, driver `PASS=41 FAIL=0`
(`serial-boot-20260926T014746Z-3089a820`, overlay
`sys-acceptance-refactor.qcow2`). Commits `e69bfb9`, `1bf31c5`, `2dd48d1`.
- **Interface contract (unchanged):** ordinary requests use AI; only explicit
`--legacy` selects deterministic handling; source flags constrain the AI and
never bypass it; a missing model stops the workflow and offers the exact
`--legacy` command without executing it.
- **Snap first-use follow-up (2026-09-25):** the previous "no snapd" note was a
real integration gap. The normal `sys install … --legacy --snap` resolver needs
snapd to confirm a Store candidate before approval, while a raw typed
`snap_install` silently added it during execution. First-use setup is now a
separately reviewed Portage install plus socket enable/start, with exact
guidance when absent. Fresh installs set scoped
`sys-fs/squashfs-tools lzma lzo`, which Gentoo's snapd ebuild requires.
A disposable VM exposed a second bug: Portage candidate resolution picked
the first dependency (`dev-lang/go-bootstrap`) instead of the requested
`app-containers/snapd`; it now matches the requested atom. Snap confinement
is reported from the daemon rather than assumed strict. The disposable VM
completed setup, Store install, refresh and remove (`PASS=10 FAIL=0`), with
partial confinement. A fresh overlay and a clean reboot repeat with the final
static binary each passed `PASS=11 FAIL=0`, including clean poweroff. Refresh
found no newer revision.
- **Previous session:** second-round `sys` review fixes.
Follow-up to `d3f676a`. Three further confirmed defects are fixed with
regression tests: unsafe cleanup previews, non-exact Flatpak/Snap update
execution, and reverse-dependency self-reference. `make test` is green
(661 → 683 tests). This corrects the earlier blanket claim that every review
finding was already fixed.
- **Interface contract (unchanged):** ordinary requests use AI; only explicit
`--legacy` selects deterministic handling; source flags constrain the AI and
never bypass it; a missing model stops the workflow and offers the exact
`--legacy` command without executing it.
## Snap first-use changes
- `phoebus-core::system` generates scoped SquashFS USE flags for new installs.
- Portage candidate resolution selects the requested atom from the pretend
plan, even when dependencies precede it. A multi-package regression covers
the bug found by the VM.
- The Snap install path gives exact setup commands when snapd is absent; the
typed action no longer adds an unreviewed Portage dependency. Candidate
sandbox levels and missing `snap info` fields are treated conservatively.
- `installer/tests/vm/snap-guest.sh` drives the installed-system journey. The
serial driver can authenticate for boot checks and logs only guest output,
keeping sent test passwords out of its transcript.
## Previous sys review work
1. **Cleanup previews are non-destructive (finding 1).** `eclean-dist`/
`eclean-pkg` delete by default, so `portage_cleaners` now previews with
`--pretend --deep` (same selection policy as execution) and executes with
`--deep`; the Nix preview uses the documented `nix-store --gc --print-dead`.
Items are read from stdout+stderr, sorted and bound. Tests prove a cleaner
never runs destructively during planning, revalidation or cancelled approval.
2. **Exact Flatpak/Snap update transactions (finding 2).**
`ResolvedPlan.updates` carries `UpdateTransaction`s: full Flatpak ref + full
installed/remote commits (via `flatpak info`, since the `commit` column is
abbreviated), or snap name + old/new revisions + channel. Execution consumes
the reviewed transaction (`add_executable`… `flatpak update --commit=<c>`),
revalidates each source immediately before its mutation, verifies the
resulting commit/revision, and refuses non-exact transactions. A source whose
resolution failed is never re-discovered. `PlanStore` aggregation includes
`updates`.
3. **Reverse dependencies (finding 3).** The reverse branch no longer drops
valid matches; it excludes only a genuine self-reference (the *dependent* is
the queried package).
4. **Determinism.** `All selected packages:` removals are sorted (depclean
previews are now order-independent); `emerge --depclean --ask=n`.
## Verified in disposable VMs
- **Cache cleanup + depclean (real tools):** `eclean` upstream preview is
non-destructive; `sys clean cache` preview/cancelled/approved/drift/failed all
behave correctly; depclean cancel/approve with transaction history and
preserved `/home`.
- **Reverse dependencies:** `sys-libs/glibc` and `sys-libs/zlib` report real
dependents (conditional/versioned included).
- **Flatpak:** installed via Portage (`sys-apps/flatpak`, enabling
`media-libs/freetype[harfbuzz]`), flathub added, an app installed and
downgraded, then `sys apply updates --flatpak` resolved full ref+commits,
deployed the pinned commit, and verified it.
- **Custom ebuild:** stage → build/install (VDB entry + installed file) →
remove.
- **Managed AppImage:** acquire with pinned SHA-256, list, run the managed ELF,
remove; a placeholder SHA is refused.
- **Nix:** a `NIX_ENABLED=yes` install bootstraps Nix; `nix profile install
nixpkgs#nodejs-slim` into `/nix/var/nix/profiles/profile` is enumerated by
`sys list --nix` and found by `sys list nodejs --nix`, with store paths and
generations reported separately.
- **Non-root `pkexec sys --broker`:** with the shipped polkit action and the
standard wheel-admin rule installed on the disposable image, a wheel user
authenticated through a terminal agent; cancellations changed nothing, the
approved removal returned the broker JSON outcome, and the replay was
rejected. The shipped privilege policy is unchanged.
- **Read-only acceptance:** `installer/tests/vm/sys-acceptance.sh` `PASS=38
FAIL=0` re-run against the final static `sys` (`dd61c610…`), including the new
`rdeps-legacy` reverse-dependency regression.
- **Snap first use:** the disposable VM installed `app-containers/snapd` through
the reviewed Portage plan (six effects), enabled and started `snapd.socket`,
installed Snap Store `hello-world` 6.4 revision 29, ran refresh, then removed
it. The daemon reported `partial` confinement and the install review agreed.
The harness reported `PASS=10 FAIL=0`
(`serial-boot-20260926T001830Z-107996de`).
Final-binary runs on a fresh overlay passed `PASS=11 FAIL=0` on first boot
(`serial-boot-20260926T005327Z-c024cc43`) and after a clean reboot
(`serial-boot-20260926T010605Z-e6193c3a`); both shut down cleanly.
## Not completed / blocked
- **Stage3 VM proof with the new binary:** unit-tested (19 stage3 tests) and
the pinned path is unchanged for real pins, but no full install has run
with the fail-closed binary yet; the next disposable install is the proof.
The unpinned (signed-DIGESTS) VM proof additionally needs a rebuilt live
ISO carrying the provisioned key (`installer/live/build.sh` now provisions
it; no ISO was rebuilt in this session).
- **Installed Mango + DMS session under a seat:** still needs a
seat-providing graphical VM (or physical VT): login, kitty, DMS
spotlight, lock/idle, polkit agent, logout, reboot
(`docs/DEVELOPMENT.md` physical-VT procedure).
- **Snap update to a different revision / strict confinement:** refresh with no
newer revision and partial confinement were VM-verified. A revision-changing
refresh and AppArmor-backed strict confinement were not (need an
AppArmor-ready guest kernel with loaded policy, and a Store snap that
actually has a newer revision than installed).
- **Live AI:** a local OpenAI-compatible model (`llama-server` + a GGUF model)
was served on the host; the AI workflow reached the model, but the sandboxed
call exceeded the 120 s transport timeout on CPU (`curl` exit 28). Needs a
faster model/GPU or a remote provider credential. Fixture-backed routing and
failure tests pass (`ask-offline`, missing-model offer, source constraint).
- **Recovery boot (distinct from rollback):** the recovery BLS entry is present
and asserted in the rollback acceptance, but booting it interactively was not
automated. Method: select "Phoebus Recovery (known-good snapshot)" in the
systemd-boot menu with no network.
- **Nix re-run flakiness:** a later `sys list --nix` re-run reported the profile
link dangling (the profile store path was gone) and correctly listed no
packages; the first run with a real profile is the positive evidence.
## Known blockers / risks
- VM serial login is occasionally flaky; retry the boot when `detached-boot-login`
fails.
- `make doctor` passes (KVM accessible via an ACL). Disk is shared by build and
VM; watch free space.
- The pre-existing `test-disk.qcow2` cannot be unlocked (unknown passphrase); do
not guess or brute-force it.
## Next actions (in order)
1. **Stage3 install proof:** next disposable install with the fail-closed
binary (pinned path), then a rebuilt live ISO (with the provisioned
Gentoo key) proving the signed-DIGESTS path in the VM.
2. **Recovery boot** by selecting the recovery BLS entry with the network down.
3. **Live AI** with a faster local model/GPU or an authorized provider
credential (natural-language discovery, source constraints, reviewed install).
4. **Installed desktop under a seat** (Mango + DMS login through reboot).
5. **Nix profile GC stability** if the dangling re-run is reproducible.
6. **Snap strict confinement and changed-revision update** in a disposable VM
when an AppArmor-ready kernel and a revision-changing Store test are available.
## Definition of a good stopping point
- `make test` passes; `docs/STATUS.md`, `docs/CHANGELOG.md` and this file
updated; committed (`scripts/agent-commit.sh`) and pushed
(`scripts/publish.sh`).