Add cell start/stop, Windows VM engine, WireGuard tunnels, and declarative packages

.claude/rules/testing.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "test/**"
+---
+
+# Test buckets — short vs long
+
+Integration tests in `test/` split by image-build cost.
+
+**Short tests** assume a test image already exists (`DEVCELL_TEST_*_IMAGE`, or a local `devcell-user:*-thin`) and skip cleanly when it doesn't. They must NEVER call `buildLocalImage()`. The inner loop and per-PR CI run only these.
+
+**Long tests** call `buildLocalImage(...)` to provision their own image (~5–10 min per stack) and MUST gate at the top:
+
+```go
+if testing.Short() { t.Skip("long: builds its own image") }
+```
+
+Nightly and release CI run these.
+
+## Run modes
+
+| Command | What runs | When |
+|---|---|---|
+| `go test -short ./test` | Short only | Inner loop, pre-commit, PR CI |
+| `DEVCELL_TEST_THIN_IMAGE=<tag> go test ./test` | All, against a pinned tag, no build | PR CI after `docker pull` |
+| `DEVCELL_TEST_BUILD_THIN=1 go test ./test` | `TestMain` builds ultimate-thin once, shared by all | Nightly, release |
+
+## Rules
+
+- Only `TestMain` and long tests may call `buildLocalImage`.
+- Long tests start with the `testing.Short()` skip — no exceptions.
+- Skip messages must name both the missing artifact and the command that supplies it, e.g. ``"set DEVCELL_TEST_DEV_IMAGE or run `cell build --stack dev --thin`"``.

.claude/rules/vocabulary.md

@@ -0,0 +1,16 @@
+# Vocabulary
+
+The runtime model has five entities. Use these words consistently in code, comments, error messages, log output, docs, and prose — a rename in one layer without the others is what made the old naming ambiguous.
+
+- **cell** — a named, persistent identity, and a boundary: one shared `$HOME` (`~/.devcell/<cellName>/`), one network, one secrets scope. May host many projects. May be running or stopped. Defaults to `main`; override with `DEVCELL_CELL_NAME`, or inherit from `TMUX_SESSION_NAME`.
+- **project** — a host directory with code, mounted into a container.
+- **container** — the running docker instance for one (cell, project) pair. Ephemeral.
+- **stack** — the image variant a container is built from.
+- **module** — a toggleable Nix capability composed into a stack.
+
+## Retired words
+
+Do not use these as devcell-layer terms:
+
+- ~~**session**~~ — tmux owns this word.
+- ~~**workspace**~~ — survives only in `internal/serve/` for the MS-TSWP RDP protocol, where it is the protocol's own term. `WorkspaceResource` is still pending a rename to `Cell`.

.dockerignore

@@ -18,3 +18,12 @@ web/.context
 docs/
 test/js/
 test/results/
+.workspaces/
+.worktrees/
+.gocache/
+.gomodcache/
+.venv/
+.vagrant/
+.playwright-mcp/
+Vagrantfile.local
+.scratch/CONTINUE.md

.github/workflows/build.dev.yml

@@ -116,7 +116,7 @@ jobs:
       - name: Hydrate /nix volume from GHCR cache
         if: inputs.skip_nix_cache != true
         run: |
-          HASH=${{ hashFiles('nixhome/**') }}
+          HASH=${{ github.sha }}
           ./bin/cell nix-store pull \
             --image "${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:nix-cache-${{ matrix.arch }}-${HASH}" \
             --fallback "${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:nix-cache-${{ matrix.arch }}-latest" \
@@ -125,17 +125,16 @@ jobs:
 
       # Build both stacks sequentially in the same job so the nix-store
       # volume accumulates derivations from both — single tar dump at job
-      # end carries everything needed by docker-test. `cell build --thin`
+      # end carries everything needed by docker-test. `cell build`
       # reuses store paths across the two invocations (nix is
       # content-addressed), so ultimate after base is incremental.
       - name: Build thin image (base stack)
         env:
           DEVCELL_NIX_VOLUME: devcell-nix-store-${{ matrix.arch }}
-          DEVCELL_NIXHOME_PATH: ${{ github.workspace }}/nixhome
           DEVCELL_NIX_MAX_JOBS: "4"
         run: |
           BASE_TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:v0.0.0-${{ matrix.arch }}-base"
-          ./bin/cell build --thin --stack base --image "$BASE_TAG" --debug
+          ./bin/cell build --stack base --image "$BASE_TAG" --debug
           echo "BASE_TAG=$BASE_TAG" >> "$GITHUB_ENV"
 
       # Interim publish: lock in the base-stack derivations as a usable
@@ -149,19 +148,18 @@ jobs:
         timeout-minutes: 45
         env:
           ARCH: ${{ matrix.arch }}
-          HASH: ${{ hashFiles('nixhome/**') }}
+          HASH: ${{ github.sha }}
           STAGE: post-base
           DEVCELL_NIX_PUSH_DEBUG: "1"
         run: task nix-cache:publish
 
       - name: Build thin image (ultimate stack)
         env:
           DEVCELL_NIX_VOLUME: devcell-nix-store-${{ matrix.arch }}
-          DEVCELL_NIXHOME_PATH: ${{ github.workspace }}/nixhome
           DEVCELL_NIX_MAX_JOBS: "4"
         run: |
           ULT_TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:v0.0.0-${{ matrix.arch }}-ultimate"
-          ./bin/cell build --thin --stack ultimate --image "$ULT_TAG" --debug
+          ./bin/cell build --stack ultimate --image "$ULT_TAG" --debug
           echo "ULT_TAG=$ULT_TAG" >> "$GITHUB_ENV"
 
       - name: Push to GHCR (both stacks)
@@ -177,7 +175,7 @@ jobs:
         timeout-minutes: 120
         env:
           ARCH: ${{ matrix.arch }}
-          HASH: ${{ hashFiles('nixhome/**') }}
+          HASH: ${{ github.sha }}
           STAGE: post-ultimate
           DEVCELL_NIX_PUSH_DEBUG: "1"
         run: task nix-cache:publish
@@ -228,7 +226,7 @@ jobs:
 
       - name: Hydrate /nix volume from GHCR cache
         run: |
-          HASH=${{ hashFiles('nixhome/**') }}
+          HASH=${{ github.sha }}
           ./bin/cell nix-store pull \
             --image "${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:nix-cache-${{ matrix.arch }}-${HASH}" \
             --fallback "${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:nix-cache-${{ matrix.arch }}-latest" \
@@ -384,8 +382,6 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Run cell claude --version (full pipeline)
-        env:
-          DEVCELL_NIXHOME_PATH: ${{ github.workspace }}/nixhome
         run: |
           # Simulate a new user in a fresh project dir
           mkdir -p /tmp/e2e-project && cd /tmp/e2e-project

.github/workflows/build.release.yml

@@ -87,12 +87,12 @@ jobs:
 
       # Hydrate /nix volume from the GHCR cache image populated by
       # build.dev.yml (same `nix-cache-${arch}-*` tag scheme). Release
-      # builds reuse the same nixhome closure as dev builds for any
-      # given `hashFiles('nixhome/**')`, so the cache is interchangeable.
+      # builds reuse the same nixhome closure as dev builds, so the
+      # cache is interchangeable.
       - name: Hydrate /nix volume from GHCR cache
         if: inputs.skip_nix_cache != true
         run: |
-          HASH=${{ hashFiles('nixhome/**') }}
+          HASH=${{ github.sha }}
           ./bin/cell nix-store pull \
             --image "${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:nix-cache-${{ matrix.arch }}-${HASH}" \
             --fallback "${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:nix-cache-${{ matrix.arch }}-latest" \
@@ -103,10 +103,9 @@ jobs:
         id: build
         env:
           DEVCELL_NIX_VOLUME: devcell-nix-store-${{ matrix.arch }}
-          DEVCELL_NIXHOME_PATH: ${{ github.workspace }}/nixhome
         run: |
           TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME_LC }}:${{ env.VERSION }}-${{ matrix.arch }}"
-          ./bin/cell build --thin --image "$TAG" --debug
+          ./bin/cell build --image "$TAG" --debug
           echo "tag=$TAG" >> "$GITHUB_OUTPUT"
 
       - name: Push to GHCR
@@ -120,7 +119,7 @@ jobs:
         timeout-minutes: 45
         env:
           ARCH: ${{ matrix.arch }}
-          HASH: ${{ hashFiles('nixhome/**') }}
+          HASH: ${{ github.sha }}
           STAGE: release
         run: task nix-cache:publish
 
@@ -236,8 +235,6 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Run cell claude --version (full pipeline)
-        env:
-          DEVCELL_NIXHOME_PATH: ${{ github.workspace }}/nixhome
         run: |
           # Simulate a new user in a fresh project dir
           mkdir -p /tmp/e2e-project && cd /tmp/e2e-project

.gitignore

@@ -1,6 +1,5 @@
 .workspaces
 .worktrees
-nixhome/user.nix
 .venv
 .env.devcell
 *.egg-info
@@ -18,20 +17,46 @@ web/src/content/cell/
 bin/
 .playwright-mcp
 test/testdata/**/nixhome
+test/testdata/windows-arm64.*
+# Versioned ssh-able base images (13+ GB each) the dev-env test builds on.
+test/testdata/windows-sshable-*.qcow
+# WSL-ready checkpoints (drivers + share + WSL engine baked in).
+test/testdata/windows-wsl-*.qcow
+# Nix-provisioned checkpoints (WSL checkpoint + home-manager activated).
+test/testdata/windows-nix-*.qcow
+# UTM bundle: the debug VM's full disk + EFI vars + config (~24 GB).
+test/testdata/Windows.utm/
+# Kernel-bootable firmware shared with the host for task debug:windows:start.
+test/testdata/QEMU_EFI.kernel.fd
+# Stable $HOME for the CLI-driven Windows build test: holds the cached ISOs and
+# the installed template, so a rerun is a boot rather than a 2h47m reinstall.
+test/testdata/cellhome/
 test/results
+test/results_archive
 .devcell
 .devcell.toml
 .gocache
 .gomodcache
 docs/
 .nixhome-tmp/
+.rendered-ps1/
 
 # macOS
 .DS_Store
 
-# Personal dev config / scratch (not project state)
-.claude/
+# Personal dev config / scratch (not project state).
+# `.claude/*` (not `.claude/`) so the shared subdirs below can be re-included —
+# git cannot un-ignore a path inside an excluded directory.
+.claude/*
+!.claude/rules/
 .context/
+.scratch/
 .envrc
 .idea/
-CLAUDE.md
+CLAUDE.local.md
+# task debug:windows runtime state
+.tmp/
+
+# local multi-repo workspace
+go.work
+go.work.sum

.mise.toml

@@ -5,8 +5,10 @@
 # git hooks land automatically.
 #
 # Nix-native contributors get the same behavior from the shellHook
-# in flake.nix; `.tool-versions` handles Go pinning for asdf users.
+# in flake.nix.
 [tools]
+# Keep in sync with the `go` directive in go.mod.
+go = "1.26"
 pre-commit = "4.0.1"
 
 [hooks]

.pre-commit-config.yaml

@@ -14,18 +14,13 @@ repos:
 
   - repo: local
     hooks:
-      # Keep flake.nix `vendorHash` in sync with go.mod / go.sum.
-      # Fires only when the Go module surface changes; delegates to
-      # `task nix:update-vendor-hash`, which builds .#cell with a fake
-      # hash, extracts the real hash from the mismatch error, and
-      # rewrites flake.nix in place. If the hash actually changed,
-      # pre-commit aborts the commit so the user reviews the diff and
-      # re-stages flake.nix — that guarantees any tag pointing at the
-      # commit has the correct hash baked in.
+      # Warn (non-blocking) when go.mod/go.sum change and vendorHash
+      # may be stale. Run `task nix:sync` to fix before pushing.
       - id: nix-vendor-hash
-        name: Sync flake.nix vendorHash with go.mod/go.sum
-        entry: task nix:update-vendor-hash
+        name: Check flake.nix vendorHash matches go.mod/go.sum
+        entry: task nix:check-vendor-hash
         language: system
         files: ^(go\.mod|go\.sum)$
         pass_filenames: false
         require_serial: true
+        verbose: true

AGENTS.md

@@ -0,0 +1,59 @@
+# devcell — Project Instructions
+
+## Terminology
+
+cell, project, container, stack, module — defined in `.claude/rules/vocabulary.md`, which loads every session. Do NOT use *session* or *workspace* as devcell-layer terms.
+
+## Git Policy
+
+- Do NOT create commits automatically. Always ask the user to commit.
+- Do NOT push to remote unless the user explicitly asks.
+
+## TDD
+
+Every behavioral change to `cmd/`, `internal/`, or `nixhome/modules/llm/*.nix` lands with a test that was failing before the change. Write the failing test first, implement the minimum to pass, then refactor.
+
+Applies to: a new flag, env var, TOML key, or CLI subcommand (`cmd/*_test.go`); a new `internal/*` function with observable behavior (same package); a new MCP server, system-prompt source, or runner argv field (`internal/runner/*_test.go`).
+
+No new test required for: pure refactors, docs, dependency bumps, nix module additions (nixhome now lives in `devcell-sh/community-home`), or entrypoint shell fragments (covered by `test/`).
+
+## Nix environment layout
+
+- Nix is owned by the `devcell` user, home at `/opt/devcell` — stable, never remounted.
+- The session user is `$HOST_USER`, home at `/home/$HOST_USER`, created at startup by the entrypoint.
+- Nix profile path is `/opt/devcell/.local/state/nix/profiles/profile` — home-manager's native path, updated on every `home-manager switch`.
+- The entrypoint copies `/opt/devcell/` dotfiles to `/home/$HOST_USER/` with `sed "s|/opt/devcell|$HOME|g"` to redirect write paths.
+- Use `ln -sfT` (not `ln -sf`) when replacing a symlink-to-directory; `-T` prevents creating the link *inside* the target.
+- `ENV USER=devcell` is required in the nix stage — `nix.sh` checks `[ -n "$USER" ]` and silently no-ops if empty.
+- `$HOME/.config/nix/nix.conf` must carry `experimental-features = nix-command flakes` at BUILD time.
+
+## Architecture detection in Dockerfiles
+
+Do NOT use `ARG TARGETARCH=amd64` — the docker driver doesn't set it for host-platform builds. Use `ARCH=$(uname -m)` in `RUN` steps.
+
+## Nix module edits
+
+Nix modules (nixhome) now live in the standalone `devcell-sh/community-home` repo. Edits to `.nix` files in this repo are limited to `flake.nix` (the Go package build).
+
+Escaping inside `writeShellScriptBin` (`''...''` strings) is the usual culprit:
+
+- `${VAR}` must be `''${VAR}` (otherwise Nix interpolates it)
+- `''` (empty shell string) must be `''''`
+- `$VAR` without braces passes through as-is
+
+## Go module and generated-docs hygiene
+
+The CI **Deploy Site** workflow compiles all `cmd/*.go` together with `cmd/gendoc.go`. Three things must hold or `go build` exits 1:
+
+1. Run `go mod tidy && go build ./...` after any dependency or import change, and commit the result. A green local build is NOT enough — CI starts from a clean module cache, so a missing `go.sum` entry only surfaces there.
+2. Build-time-only tooling deps must stay anchored in `cmd/tools.go` (`//go:build tools`). `cmd/gendoc.go` is `//go:build ignore`, so `go mod tidy` can't see its `cobra/doc` import and would prune the transitive deps. Anchor any other build-ignored tool's deps there too.
+3. `docs/` is gitignored (swagger output) but `cmd/serve.go` imports it, so any workflow compiling `serve.go` must run `task swagger:generate` first.
+
+After changing `go.mod`/`go.sum`, run `task nix:sync` — it resolves `flake.nix`'s `vendorHash` and stages it. The pre-commit hook only verifies.
+
+## Disk space
+
+If a build fails with "no space left on device":
+
+1. Prune build cache first (safe): `docker buildx prune -af`
+2. If still insufficient, **ask the user to stop old containers — never stop them yourself.** Each pins a ~13 GB untagged image with almost no layer sharing, so 2–3 usually frees ~20 GB. Then `docker image prune`.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md