test: add feature-final stack verification

Author: TrentBrown

.github/workflows/release.yml

@@ -66,6 +66,9 @@ jobs:
           path: dist/release
       - name: Restore executable artifact modes
         run: chmod 755 dist/release/portreeve-v*
+      - if: startsWith(matrix.platform, 'linux-')
+        name: Verify a real mixed process and Docker stack
+        run: bun run stacks:verify
       - run: bun run release:verify -- --native --lifecycle
       - if: startsWith(matrix.platform, 'macos-')
         run: bun run release:verify -- --homebrew

README.md

@@ -51,6 +51,8 @@ const running = await portreeve.withPort(
 - [Socket protocol](docs/protocol.md)
 - [CLI automation contract](docs/cli-contract.md)
 - [Stack definitions](docs/stacks.md)
+- [Desktop application](docs/desktop.md)
+- [Mixed process and Docker example](examples/mixed-stack/README.md)
 - [Migration from project-local remapping](docs/migration.md)
 - [Safety model](docs/safety.md)
 - [Troubleshooting](docs/troubleshooting.md)

apps/desktop/README.md

@@ -1,5 +1,8 @@
 # Portreeve Desktop engineering slice
 
+For the operator-facing behavior and security boundary, see the public
+[`docs/desktop.md`](../../docs/desktop.md) guide.
+
 This private workspace contains the non-shipping Electron MVP for Portreeve Desktop. It
 displays lifecycle evidence from an exact Portreeve CLI executable, global inventory and
 stack coordination evidence from the official JavaScript client, and confirmed

docs/desktop.md

@@ -0,0 +1,97 @@
+# Desktop application
+
+Portreeve Desktop is the graphical inspection and coordination surface for the same
+per-user Portreeve installation managed by the CLI. It does not install a second server,
+keep a separate registry, or bypass the HTTP/JSON Unix-socket protocol. The application
+bundles a verified CLI artifact and can install that artifact into the one managed
+per-user location used by native supervision.
+
+## Overview and lifecycle
+
+The Overview tab reports the desktop, bundled CLI, managed CLI, running-server,
+supervisor, and socket layers independently. Lifecycle actions invoke an exact bundled
+or managed executable from the Electron main process; the renderer cannot choose an
+executable, run a shell command, or search `PATH`.
+
+Available actions follow current evidence:
+
+- install and start the managed Portreeve service;
+- start, stop, or restart native per-user supervision;
+- stop an explicitly manual `portreeve serve` process without adopting it;
+- upgrade the managed CLI after version and artifact verification;
+- uninstall supervision while retaining Portreeve data;
+- preview and confirm a complete Portreeve data reset.
+
+Install, reset, and upgrade decisions remain explicit. Update discovery only reports a
+new desktop release and opens one fixed project download page after confirmation; it
+does not download or install updates automatically.
+
+Lifecycle operations display a stable outcome plus safe structured error codes and
+messages. For example, an unsafe supervisor log mode is shown as an actionable
+permission failure rather than only `internal`. Unstructured errors are generalized so
+arbitrary exception detail does not become renderer content.
+
+## Ports
+
+The Ports tab uses the official JavaScript client to show global claimed and unclaimed
+TCP listeners. The main process reduces inventory before publishing it to the renderer.
+Claims show project, component, endpoint, worktree basename, mode, and timing; listeners
+show reduced ownership and process evidence. Lease tokens, internal database fields, and
+arbitrary executable paths are not exposed.
+
+## Stacks
+
+The Stacks tab reads definitions and current generation, activation, resolution, and
+fresh provider evidence through the official client. It supports:
+
+- selecting and applying a checked-in `portreeve.stack.json` through the native file
+  picker;
+- preparing or reusing one complete allocation generation;
+- inspecting components, endpoints, dependencies, placements, host addresses,
+  Docker-network addresses, and provider evidence;
+- copying individual addresses and previewing a component-scoped sandbox discovery
+  document for a launcher-supplied gateway;
+- explicitly reconciling provider evidence after launcher loss;
+- requesting evidence-gated activation ending after the project launcher stops its
+  providers;
+- previewing seven-day missing-worktree stack pruning and typing `PRUNE` before
+  execution.
+
+Portreeve Desktop never starts or stops a project process or container, invokes Docker
+Compose, owns application startup order, maps project environment variables, or asserts
+application health. Those remain responsibilities of the project launcher. Stale stack
+evidence remains visible for diagnosis but withholds stack mutation controls until
+current evidence returns; the server revalidates every requested action as final
+authority.
+
+## Trust and data boundary
+
+Electron runs a sandboxed renderer with context isolation, Node integration disabled,
+and a restrictive local content policy. The preload exposes only named, schema-validated
+capabilities. The main process accepts IPC only from the primary `app://portreeve`
+renderer frame and owns the native file picker, clipboard write, fixed download-page
+navigation, exact CLI execution, and official client connection.
+
+The desktop receives no general filesystem, shell, network-navigation, SQLite, Docker,
+or Portreeve-socket capability. Stack view models omit full worktree paths, claim and
+lease identifiers, run identifiers, Docker labels, and credentials. Discovery previews
+contain only their documented component-scoped address contract.
+
+## Local package
+
+Build and open an unsigned local macOS application bundle with the repository-pinned Bun
+toolchain:
+
+```sh
+PORTREEVE_HOMEPAGE_URL=https://github.com/TrentBrown/portreeve \
+PORTREEVE_RELEASE_BASE_URL=https://github.com/TrentBrown/portreeve/releases/download \
+bun run release:build
+
+bun run desktop:package
+open dist/desktop/Portreeve-darwin-arm64/Portreeve.app
+```
+
+The packaging script selects the physical host architecture and verifies the bundled
+CLI against the generated release manifest and SHA-256 digest. This local bundle is a
+release candidate for manual verification, not a signed or notarized public desktop
+distribution.

docs/installation.md

@@ -58,8 +58,18 @@ bun run release:build
 
 bun run release:verify -- --native --lifecycle
 bun run release:verify -- --homebrew
+bun run stacks:verify
 ```
 
+`stacks:verify` is a destructive-only-to-its-own-fixtures native integration smoke. It
+creates one uniquely named disposable Docker container and one temporary process
+listener, drives a mixed stack through the official JavaScript client, and removes its
+container, worktree, Portreeve home, and runtime files in `finally` cleanup. It pulls
+`node:22.17.0-bookworm` when that default image is absent. Override the trusted Docker
+CLI, image, or launcher-rendered sandbox gateway with
+`PORTREEVE_DOCKER_EXECUTABLE`, `PORTREEVE_DOCKER_SMOKE_IMAGE`, or
+`PORTREEVE_SANDBOX_GATEWAY`.
+
 `release:verify -- --native` verifies every artifact's checksum and executable
 header, validates the formula syntax, and actually runs the artifact matching
 the current machine. Adding `--lifecycle` uses a unique temporary native
@@ -71,7 +81,9 @@ gate and both native release smokes before publication. Cross-compilation alone
 is not release evidence. Native jobs require Node.js 22, Bun 1.3.14, Git,
 `lsof`, `ps`, Ruby, and a non-root login session. Linux runners must provide a
 working `systemd --user` manager. The Linux ARM64 job runs natively on GitHub's
-hosted `ubuntu-24.04-arm` image.
+hosted `ubuntu-24.04-arm` image. Both Linux release jobs also run the real mixed-stack
+Docker smoke. Docker Desktop on macOS is verified manually because hosted macOS runners
+do not provide the product's Docker Desktop environment.
 
 Development may occur while a GitHub repository is private, and branch or
 manual Actions runs still work. The Portreeve repository is public before its

docs/issues/tb-portreeve-stacks/issues.md

@@ -108,7 +108,7 @@ human review and merge.
 
 ## I-5 - Complete activation recovery and safe stack pruning
 
-- **Status:** in-review
+- **Status:** closed
 - **Estimate:** 2d
 - **Plan steps:** P6
 - **Rubric criteria:** R6
@@ -161,9 +161,12 @@ stack-status contract for trusted inspection surfaces, and packaged macOS verifi
 The desktop remains a Portreeve coordinator rather than a project process or container
 orchestrator.
 
+**Merged 2026-08-07.** PR #12 merged to `main` as `0fc3865` after the complete
+desktop, protocol, client, CLI, package, and boundary gates passed.
+
 ## I-7 - Complete integrated verification and feature evidence
 
-- **Status:** open
+- **Status:** in-progress
 - **Estimate:** 2d
 - **Plan steps:** P8
 - **Rubric criteria:** R1, R2, R3, R4, R5, R6, R7, R8
@@ -173,3 +176,6 @@ orchestrator.
 Finish public documentation and representative examples, run mixed-stack and legacy
 end-to-end matrices on supported native environments and the packaged desktop, execute
 every workflow gate, and preserve the feature-final evidence and completion report.
+
+**Started 2026-08-07.** Final sequential delivery branch
+`tb-portreeve-stacks-07-feature-final` begins from merged `main` at `0fc3865`.

docs/issues/tb-portreeve-stacks/scratchpad.md

@@ -225,3 +225,18 @@ Add a read-only stack status operation under the existing stack-activations-v1 c
 
 **Alternatives considered:**
 Reconstruct status from history in the desktop - rejected because history is an audit trail rather than a current-state index; add database access to the desktop - rejected by the existing trust boundary; show only definitions and prepared results from the current desktop session - rejected because the desktop must inspect stacks created by project launchers and survive restarts.
+
+## [11] Make the assembled mixed-stack smoke launcher-owned and release-gated
+
+[ ] **Promote**
+
+**Confidence:** HIGH
+
+**Blast Radius:** Native verification script, package scripts, Linux release jobs, mixed-stack example, and feature-final evidence
+
+Add one explicit native verification harness that acts as a temporary trusted project launcher. It starts a disposable process listener and a uniquely named disposable Docker container, but it drives Portreeve exclusively through the official client and validates apply, prepare, mixed activation confirmation, scoped resolution, redacted snapshot publication and reading, current status, live-provider refusal, reconciliation, ending, pruning, and retained history. It owns exact cleanup for everything it creates. Run it manually on macOS Docker Desktop and in both Linux native release jobs; keep it out of the ordinary source test command because Docker is an optional runtime capability.
+
+**Triggered by:** P8 requires one representative process-plus-Docker lifecycle across every public coordination phase without transferring project lifecycle authority to Portreeve
+
+**Alternatives considered:**
+Extend Portreeve itself with a stack launcher - rejected because application lifecycle remains project-owned; rely only on isolated deterministic tests - rejected because P8 requires assembled native evidence; run the native smoke on every macOS GitHub runner - rejected because hosted macOS runners do not provide the Docker Desktop environment required by the product contract

docs/issues/tb-portreeve-stacks/tracker.md

@@ -103,7 +103,7 @@ Append PR boundary entries here.
 ### PR #12 - Desktop stack coordination
 
 - **PR:** [#12](https://github.com/TrentBrown/portreeve/pull/12)
-- **Status:** in review
+- **Status:** merged
 - **Scope:** P7 desktop Stacks views, definition apply, preparation, reconciliation,
   evidence-gated activation ending, snapshot/address copy, previewed confirmed pruning,
   actionable failures, and the aggregate read-only stack-status surface used by the
@@ -115,3 +115,4 @@ Append PR boundary entries here.
   test stack and claims were pruned. Independent judge: PASS WITH CONCERNS; code review:
   PASS with no remaining findings. Native Linux and assembled mixed-stack release
   verification remain I-7/P8.
+- **Merged:** `0fc3865` on 2026-08-07.

docs/stacks.md

@@ -34,6 +34,10 @@ The checked-in definition is `portreeve.stack.json` at the worktree root:
 }
 ```
 
+The repository includes a complete
+[mixed process and Docker launcher example](../examples/mixed-stack/README.md) that
+shows how one project-owned launcher consumes the returned leases and addresses.
+
 The schema is strict. Unknown fields are rejected. Component and endpoint names are
 stable logical identities. An omitted dependency endpoint means `default`. Endpoint
 defaults are TCP, published, and required. Use `publish: false` for an endpoint that

examples/mixed-stack/README.md

@@ -0,0 +1,82 @@
+# Mixed process and Docker stack
+
+This example models a process-backed `website` and Docker-backed `api` as one
+independently runnable worktree stack. Portreeve allocates both host publications and
+verifies their evidence. The project launcher still owns the website child process,
+Docker or Compose invocation, environment injection, startup order, health checks, and
+shutdown.
+
+Copy [`portreeve.stack.json`](portreeve.stack.json) to the root of a disposable worktree
+or adapt its project and component names there. The file declares topology and preferred
+ports only; it contains no command, secret, environment value, or lease credential.
+
+## Launcher sequence
+
+1. Apply and prepare before deriving any environment or Compose override:
+
+   ```sh
+   portreeve stacks apply --json
+   portreeve stacks prepare STACK_ID --json
+   ```
+
+2. Begin one mixed activation. The API receives a Docker lease and the website receives
+   a process lease:
+
+   ```sh
+   portreeve stacks begin GENERATION_ID --docker-component api --json
+   ```
+
+3. The trusted launcher writes private lease output to a mode-`0600` runtime file. It
+   starts the API container with every returned `requiredLabels` entry and publishes
+   `127.0.0.1:API_HOST_PORT:3000`. It confirms the exact container ID with
+   `stacks confirm-docker`.
+
+4. The launcher starts the website on its returned host port, sets its backend URL from
+   the resolved `backend` alias, and confirms the website root PID with
+   `stacks confirm`:
+
+   ```sh
+   portreeve stacks resolve ACTIVATION_ID --component website --json
+   ```
+
+   A typical environment mapping is:
+
+   ```text
+   PORT=website.own.http.host.port
+   API_URL=http://website.dependencies.backend.host.host:website.dependencies.backend.host.port
+   ```
+
+   Resolution describes network addresses, not startup readiness. The launcher decides
+   when the API is healthy enough to start the website.
+
+5. For a Docker or Codex sandbox, the host launcher renders a separate read-only
+   discovery file instead of mounting the Portreeve socket:
+
+   ```sh
+   portreeve stacks snapshot ACTIVATION_ID \
+     --component website \
+     --gateway-host host.docker.internal \
+     --file .portreeve/runtime/website-endpoints.json
+   ```
+
+   Linux launchers supply their configured host-gateway name or address. Sandboxed code
+   reads the mounted file through `readEndpointSnapshot` or `PORTREEVE_ENDPOINTS_FILE`.
+
+6. On shutdown, the launcher stops the website process and API container first, then
+   requests `stacks end`. After a launcher crash, its replacement runs
+   `stacks reconcile` and acts on `active`, `gone`, or `unknown` provider evidence
+   rather than trusting the old launcher PID.
+
+## Native assembled verification
+
+Repository contributors with Docker available can run:
+
+```sh
+bun run stacks:verify
+```
+
+That harness creates a uniquely named disposable container and process listener and
+drives this complete lifecycle through the official JavaScript client: apply, prepare,
+begin, both confirmations, status, resolution, sandbox snapshot write/read, live end
+refusal, reconciliation, end, missing-worktree prune, and retained-history inspection.
+It removes every process, container, worktree, and Portreeve data path it creates.