Complete terminal management workflow

docs/PROJECT_LAYOUT.md

@@ -1,12 +1,19 @@
 # Project Layout
 
-Read this document when creating or reorganizing modules. The paths below are planned until implemented.
+Read this document when creating or reorganizing modules. The layout below
+reflects the current package; sections marked planned describe later test and
+integration work only.
 
 ## Target project layout
 
-Start with one Cargo package containing a binary (`src/main.rs`) and a library (`src/lib.rs`). Keep startup, argument handling, and process exit in `main.rs`; place testable application logic in library modules. A library target does not require publishing a separate library package. Introduce a workspace only when independently reusable or separately built components justify it.
+The repository has one Cargo package with a binary (`src/main.rs`) and a
+library (`src/lib.rs`). Startup and process exit remain in `main.rs`; testable
+application logic and the management TUI are library modules. A library target
+does not require publishing a separate library package. Introduce a workspace
+only when independently reusable or separately built components justify it.
 
-The following is the intended layout, not a claim that these files already exist. Create modules and directories as implementation requires them; do not generate empty scaffolding for the entire tree.
+Implemented modules include the following. Add modules as implementation
+requires them; do not generate empty scaffolding for future integration work.
 
 ```text
 Cargo.toml
@@ -36,12 +43,14 @@ src/
   tui/
     state.rs               # Screen state and navigation
     events.rs              # Keyboard and background events
+    forms.rs               # Short-lived forms and secret owners
     render.rs              # Rendering
     terminal.rs            # Terminal setup and cleanup
 tests/
   config_preservation.rs   # Untouched server configuration remains identical
   commit_restore.rs        # Persistence, backups, restore, runtime isolation
   client_lifecycle.rs      # Import, creation, delivery, deletion, state transitions
+  tui_workflow.rs          # Synthetic worker-level TUI workflows
   fixtures/                # Synthetic configuration and archive inputs
   support/
     mod.rs                 # Shared test adapters and helpers

docs/TESTING.md

@@ -17,6 +17,21 @@ cargo build --locked --release
 
 Use only supported feature combinations; do not assume `--all-features` is valid. Keep privileged integration tests out of the default test suite. If a check cannot run, report the exact limitation rather than claiming success. Documentation-only edits do not require rebuilding the application.
 
+The unprivileged TUI fixture commands currently available are:
+
+```sh
+cargo test --locked --test tui_workflow
+cargo test --locked tui::
+```
+
+`tui_workflow` runs setup with a redacted invalid-source anomaly, client
+creation/rename, Commit, first-file and QR delivery, manual backup/list, and
+preview/cancel/confirm restore through the serialized application worker. It
+uses temporary settings/server/source files and a fake statistics reader; it
+does not invoke service or runtime mutation.
+The `tui::` filter covers forms, rendering, worker responsiveness/staleness,
+QR fit, and terminal cleanup/error seams. It does not require root or a PTY.
+
 Prioritize meaningful behavioral checks:
 
 - Configuration round trips preserve untouched bytes, unknown fields, and administrator comments; managed metadata cannot escape its comment block.
@@ -30,6 +45,33 @@ Prioritize meaningful behavioral checks:
 
 Test externally observable behavior and high-impact failure paths. Avoid tests that merely repeat implementation details, introduce root requirements, or assert real secrets in snapshots. Broaden testing when failures or new risks justify it.
 
+### Terminal smoke coverage
+
+`cargo test --locked --test tui_workflow terminal_pty_smoke -- --nocapture`
+launches the terminal loop through `script` with a synthetic `Application` and
+an injected fake unavailable-statistics reader. It enters at 80×24, changes to
+40×8 and back to 80×24, sends Ctrl-C (handled as the normal exit request), and
+asserts the alternate screen and cursor are restored. The setup is not root
+management startup and does not read host settings or query host WireGuard.
+The test reports itself incomplete if the
+`script` utility is unavailable. In the workflow test, an actual first-delivery
+QR result is transferred into the disclosure owner and Esc clears it; the
+renderer fit test separately checks complete quiet-zone dimensions. These
+checks are synthetic PTY/UI evidence, not phone/decoder interoperability.
+The PTY test exercises handled interruption and normal terminal restoration;
+`cargo test --locked tui::terminal::tests::lifecycle_failures_restore_terminal_modes_in_isolated_pty -- --nocapture`
+uses `script` to launch five isolated child probes at 80×24. The probes stop
+after raw-mode setup, stop after alternate-screen setup, return synthetic
+render and input I/O errors after full setup, and panic after full setup. Each
+child checks raw mode is off on return; the parent checks that alternate-screen
+and cursor enter/restore sequences match the resources reached. The panic case
+also checks that the panic hook emits its generic internal-failure diagnostic
+without the synthetic panic payload. These probes use the same private lifecycle
+guard and setup methods as production, without an environment-controlled
+production path or application/service adapters. The test reports itself
+incomplete if `script` is unavailable. PTY evidence remains synthetic; it does
+not test terminal-emulator behavior beyond the emitted control sequences.
+
 ## Integration testing with Alpine Testcontainers
 
 Production access is limited and experimentation on the production VPN is prohibited. Use three complementary levels: ordinary unit/fixture tests, explicitly selected Alpine container integration tests, and a separate disposable Linux VM for real systemd/D-Bus acceptance. No level authorizes using production as a test environment.