MaceWindu
diff --git a/‎README.md‎
Lines changed: 1 addition & 0 deletions b/‎README.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎claudearium.ps1‎
Lines changed: 338 additions & 39 deletions b/‎claudearium.ps1‎
Lines changed: 338 additions & 39 deletions
diff --git a/‎docs/cookbook.md‎
Lines changed: 65 additions & 0 deletions b/‎docs/cookbook.md‎
Lines changed: 65 additions & 0 deletions
diff --git a/‎docs/design-decisions.md‎
Lines changed: 63 additions & 0 deletions b/‎docs/design-decisions.md‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎docs/usage.md‎
Lines changed: 26 additions & 10 deletions b/‎docs/usage.md‎
Lines changed: 26 additions & 10 deletions
diff --git a/‎docs/wsl2-gotchas.md‎
Lines changed: 40 additions & 0 deletions b/‎docs/wsl2-gotchas.md‎
Lines changed: 40 additions & 0 deletions
@@ -10,6 +10,7 @@ A PowerShell-managed WSL2 sandbox for running [Claude Code](https://docs.claude.
 - **Optional:** all sandbox traffic routed through a user-supplied WireGuard tunnel, with an nftables killswitch that drops anything not going through the VPN — **except** host-subnet traffic, so local services like a host-side Seq instance remain reachable.
 - **Optional:** Windows-only utilities (e.g. Claudelk for BLE LED strips) reachable from inside the sandbox via WSL's Windows-interop bridge — no `usbipd` passthrough required, no host-side listener daemon needed.
 - **Optional:** already-authenticated host CLIs (`gh`, `glab`, `acli`, `seqcli`) attachable as drop-in wrappers so you keep your Windows-side browser OAuth instead of re-authenticating inside WSL.
+- **Optional:** Windows-specific repos (PowerShell, .NET-on-Windows — including Claudearium itself) registerable as **hostProjects**, with sessions backed by host-side `git worktree` paths and a per-session PATH that exposes host `pwsh` / `git` without disturbing parallel distroProject sessions.
 - **Project-agnostic:** the same script bootstraps sandboxes for any project. Project layout, repo URL, mounts, tools, and Claude Code settings are all per-project configuration in a single declarative profile file.
 
 ## What this is *not*
 
@@ -165,6 +165,71 @@ The cwd is auto-translated by WSL interop, so `gh pr view` from a `cd`-ed repo j
 
 **Claude sees the gotcha automatically.** If you have `profile.claudeFile` set (caveman-lite / host-copy / custom-path), the attach also writes `~/.claude/host-tools/gh.md` with the full recipe and appends a one-line caveat block to `~/.claude/CLAUDE.md`. So Claude in WSL knows from the first session: "argv paths need `wslpath -w`; see the per-tool file for details."
 
+## Work on a Windows-specific project (e.g. Claudearium itself) as a hostProject
+
+Some repos can't be developed entirely from inside the distro — their tests
+need PowerShell on Windows, or they invoke `wsl.exe`, or they target
+.NET-on-Windows. Claudearium handles these as **hostProjects**: the
+checkout lives on Windows, sessions are host-side `git worktree add` paths
+mounted into the distro, and selected host tools (`pwsh`, `git`) are
+exposed in the session via a per-project bin dir on `PATH`. Claude Code
+edits files in the mount, but `pwsh -File .\test-foo.ps1` actually runs on
+the host.
+
+```powershell
+# 1. Register Claudearium itself as a hostProject.
+.\claudearium.ps1 project add Claudearium `
+    -HostProject `
+    -HostCheckout C:\GitHub\Claudearium `
+    -HostShadows pwsh,git
+
+# 2. Create a session. The worktree appears at C:\GitHub\Claudearium-sessions\dev
+# on the host, and at /host/Claudearium/dev inside the distro.
+.\claudearium.ps1 session new dev -Project Claudearium -Branch master
+
+# 3. Launch.
+.\open-claudearium.ps1 -Project Claudearium -Session dev
+```
+
+Inside the new tab:
+
+```bash
+pwd                                # /host/Claudearium/dev
+which pwsh                         # /home/claude/host-projects/Claudearium/bin/pwsh
+which git                          # /home/claude/host-projects/Claudearium/bin/git
+echo "$PATH" | tr ':' '\n' | head  # bin dir first, then the usual /usr/local/bin, /usr/bin, ...
+
+# Run the host-side test suite without leaving the session:
+pwsh -File ./test-claudearium.ps1 -Auto -Only pure -CI
+```
+
+A parallel distroProject session opened in another wt tab still resolves
+`pwsh` and `git` to the distro's `/usr/bin` copies — the bin-dir prepend
+is bash-local to the host session.
+
+Cleanup:
+
+```powershell
+.\claudearium.ps1 session remove dev -Project Claudearium
+# C:\GitHub\Claudearium-sessions\dev is gone; the mount is gone.
+
+.\claudearium.ps1 project remove Claudearium -Force
+# Per-project bin dir is gone. C:\GitHub\Claudearium itself is untouched.
+```
+
+A few practical notes:
+
+- The session's working directory in the distro maps to a path on `/mnt/c`-style
+  drvfs storage. Git operations are slower than against a Linux-native worktree.
+  For Claudearium that's fine — the repo is small.
+- The `hostShadows` PATH prepend doesn't auto-translate path arguments.
+  When passing `.ps1` paths to host `pwsh`, the cwd is auto-translated by
+  WSL interop (so relative paths just work), but absolute Linux paths to
+  files need `wslpath -w` first. See `templates/host-tool-notes/pwsh.md`.
+- Don't list a shadow in `hostShadows` AND install the same tool inside the
+  distro via `tools.<name>` — the per-session bin dir wins on PATH for that
+  session, so you'd silently never use the distro copy. Pick one home.
+
 ## Stay current with the latest release
 
 ```powershell
 
@@ -456,3 +456,66 @@ limits the notes set to tools claudearium itself opts into
 host-attach via `HostExeNames`. The pure test `has a shipped template
 for every catalog tool that opts in to host-attach` keeps the templates
 in lockstep with the catalog automatically.
+
+## 22. hostProjects: host-side worktrees + per-session PATH shadowing
+
+**Decision:** project entries carry a `type` field. `distroProject`
+(default) keeps the existing bare-mirror-inside-the-distro model.
+`hostProject` is a Windows-resident variant: the project owns no mirror
+inside the distro; sessions are `git worktree add` paths created on the
+host at `<hostCheckout>-sessions\<session>` and auto-mounted into the
+distro at `/host/<project>/<session>` via the fstab managed block.
+Host tools the project needs (`pwsh`, `git`, ...) are wrapped into a
+per-project bin dir at `/home/claude/host-projects/<project>/bin/`,
+which open-claudearium prepends to `PATH` only when launching sessions
+of that hostProject.
+
+**Why a new project type rather than reusing `hostMounts` + global
+`hostTools`:** the user originally had to choose between
+
+1. **Distro-resident worktree, mount the host checkout read-write.** Edits
+   work, but tests still have to invoke host PowerShell somehow, and the
+   global `hostTools` wrappers live in `/usr/local/bin` — they'd be on
+   PATH for every other distroProject session too, silently shadowing the
+   distro's `git` / `pwsh`. That's the conflict mode we promised to avoid.
+2. **Just run Claude Code on Windows.** Loses the session model, the
+   killswitch, the central dashboard, the per-project claudeSettings —
+   everything claudearium gives you for free.
+
+The new `hostProject` type lets the same distro host both kinds of
+projects in parallel. Per-session PATH shadowing (option 1's failure mode
+inverted) is the key invariant: distro-installed `git`/`pwsh` remain
+authoritative for every shell *except* sessions belonging to a
+hostProject that declared them as `hostShadows`.
+
+**Why per-project (not global, not per-session) bin dirs:** global would
+cross-talk into other projects; per-session would mean N copies of the
+same wrapper for one project's N parallel sessions, plus a setup tax on
+every session-create. Per-project is the natural scope — every session of
+project X wants the same shadows — and the bin dir is wiped + rewritten
+on `project add` / `reconcile`, so a profile edit (add/remove a shadow)
+costs O(1) regardless of how many sessions of that project exist.
+
+**Why PATH prepend lives in a per-project `init.sh` sourced by the
+launcher, not in the wsl.exe argv directly:** `wsl.exe ... -- bash -lc
+"export PATH=<bin>:$PATH; exec claude"` looks like the obvious form, but
+gotcha #20 (variant of gotcha #1) silently mangles the literal `$PATH`
+to an empty string before bash sees it. Routing the prepend through a
+file bash reads from disk sidesteps the mangling entirely. Same
+philosophy as `Invoke-InDistroScript`'s base64 transport.
+
+**Why a `git worktree add` sibling to `hostCheckout` rather than under
+`%LOCALAPPDATA%`:** the user asked for proximity ("will it work nice
+with claude project permissions?"). Sibling worktrees show up in
+Explorer next to the main checkout, are obvious to clean up by hand if
+needed, and inherit the same Claude Code trust-prompt semantics as
+distroProject sessions (each session worktree is a distinct directory
+from Claude's POV, but profile-level `claudeSettings.permissions`
+propagates uniformly).
+
+**Why `hostTools` (the global block) is rejected at the project level
+for hostProjects:** Test-Profile refuses a hostProject entry that
+carries `hostTools: [...]`. The intent of `hostTools` is global
+wrappers in `/usr/local/bin` — exactly the cross-talk vector we're
+designing around. `hostShadows` is the project-scoped replacement.
+Failing fast keeps users from accidentally building the conflict mode.
@@ -52,46 +52,62 @@ Reads the profile, diffs it against the recorded state, prints the diff, and pro
 
 ## `project <subverb?>`
 
+Projects come in two flavors. **distroProjects** (the default) clone a bare mirror inside the distro and run all git work in Linux; sessions are distro-side worktrees. **hostProjects** (`-HostProject`) skip the mirror entirely — the user's Windows checkout is the source of truth, sessions are host-side `git worktree add` paths mounted into the distro, and a per-project bin dir on the session's `PATH` makes selected host tools (`pwsh`, `git`, …) callable as bare commands. Use hostProjects for Windows-specific repos (PowerShell, .NET-on-Windows) where tests have to run on the host anyway.
+
 **`project`** (no subverb) — interactive dashboard listing projects with row-actions (`+` add, `s <n>` show, `d <n>` remove, `q` quit).
 
-**`project add [<name>]`** — adds a project to the profile and clones its bare mirror inside the distro. Smart defaults pull from `-HostCheckout`'s `origin` URL (or the current working directory if it's a git checkout). Falls back to `master` for the default branch. The repo name is derived from the URL's last path segment.
+**`project add [<name>]`** — adds a project to the profile.
 
 ```powershell
-# Auto-detect from the host checkout (recommended; the wizard's defaults are pre-filled).
+# distroProject: auto-detect remote/branch from a host checkout, clone a bare mirror.
 .\claudearium.ps1 project add -HostCheckout C:\src
 
-# Fully scripted.
+# distroProject: fully scripted.
 .\claudearium.ps1 project add acme `
   -Remote git@gitlab.example.com:acme/acme.git `
   -DefaultBranch master `
   -NonInteractive
+
+# hostProject: register C:\GitHub\Claudearium directly; sessions live on the host.
+.\claudearium.ps1 project add Claudearium `
+  -HostProject `
+  -HostCheckout C:\GitHub\Claudearium `
+  -HostShadows pwsh,git
 ```
 
+Smart defaults pull from `-HostCheckout`'s `origin` URL (or the current working directory if it's a git checkout). distroProjects fall back to `master` for the default branch. The repo name is derived from the URL's last path segment.
+
+`-HostShadows` accepts a list of names known to the built-in catalog (currently `pwsh`, `git`) — each resolved via `where.exe` first, then well-known install paths. To pin an exact binary, use the explicit form in the profile: `hostShadows: [{ name: "pwsh", windowsExe: "C:\\Custom\\pwsh.exe" }]`. The default when `-HostProject` is passed without `-HostShadows` is `pwsh,git`.
+
 **`project list`** — table of projects with profile-vs-materialized status. Useful for noticing drift (mirror present but not in profile, or vice-versa — both nudge you toward `reconcile`).
 
 **`project show <name>`** — detailed view of one project, including any sessions tracked against it.
 
-**`project remove <name>`** — deletes bare mirror, every session of this project, and the profile entry. Asks for confirmation unless `-Force`.
+**`project remove <name>`** — deletes the bare mirror (distroProject) or the per-project bin dir (hostProject), every session of the project, and the profile entry. For hostProjects, the `hostCheckout` itself is **never** deleted. Asks for confirmation unless `-Force`.
 
 ## `session <subverb?>`
 
 **`session`** (no subverb) — interactive dashboard of all sessions across all projects (filter with `-Project`). Row-actions: `d <n>` remove, `q` quit.
 
-**`session new <name>`** — creates a git worktree under the project's bare mirror.
+**`session new <name>`** — creates a git worktree. The wiring depends on the project's type (recorded in the profile):
+
+- **distroProject** — `git worktree add` runs inside the distro off the project's bare mirror. The worktree lives at `/home/claude/projects/<project>/sessions/<session>` and shares the mirror at `/home/claude/mirrors/<project>.git` with every other session. Subsequent `git fetch`es from any session populate the mirror once for all of them.
+- **hostProject** — `git worktree add` runs on the Windows side against the project's `hostCheckout`. The worktree lands at `<hostCheckout>-sessions\<session>` (e.g. `C:\GitHub\Claudearium-sessions\dev`). The distro auto-mounts that Windows path at `/host/<project>/<session>` via the fstab managed block, and `open-claudearium.ps1` opens the session with that mount as the working directory.
 
 ```powershell
-# Check out an existing branch:
+# distroProject: existing branch
 .\claudearium.ps1 session new mainline -Project Claudelk -Branch master
 
-# Create a new branch off the project's default branch:
+# distroProject: new branch off master
 .\claudearium.ps1 session new feat-1234 -Project acme -Branch feature/PROJ-1234-some-feature -NewBranch -BaseBranch master
-```
 
-Sessions live at `/home/claude/projects/<project>/sessions/<session>` inside the distro and share the bare mirror at `/home/claude/mirrors/<project>.git` with every other session of the same project. Subsequent `git fetch`es from any session populate the mirror once for all of them.
+# hostProject: existing branch (the worktree shows up on Windows at C:\GitHub\Claudearium-sessions\dev)
+.\claudearium.ps1 session new dev -Project Claudearium -Branch master
+```
 
 **`session list [-Project <p>]`** — table with project / session / branch / dirty state / created-at.
 
-**`session remove <name> -Project <p>`** — removes the worktree (and prunes the bare mirror's worktree metadata). Refuses if the worktree has uncommitted files unless `-Force`.
+**`session remove <name> -Project <p>`** — removes the worktree (and prunes the bare mirror's worktree metadata for distroProjects, or unmounts + removes the host worktree for hostProjects). Refuses if there are uncommitted files unless `-Force`.
 
 See [sessions.md](./sessions.md) for the parallel-sessions deep dive (model, isolation table, launcher, `wt` integration).
 
 
@@ -528,6 +528,45 @@ A pure regression test in `tests/pure/Profile.Tests.ps1` exercises the
 
 ---
 
+## 20. Putting `$PATH` in the `wsl.exe -- bash -lc <cmd>` argv makes PATH empty
+
+**Symptom:** A hostProject session's `open-claudearium.ps1` tab launches but
+`claude` can't be found, or any tool invocation fails with "command not
+found." Tracing shows `echo "$PATH"` inside the new shell prints just
+`/home/claude/host-projects/<project>/bin:` — no `/usr/bin`, no `/bin`, no
+anything else.
+
+**Cause:** This is gotcha #1 striking again under a new disguise. The session
+launcher built the bash command as a single argv string —
+`export PATH='/home/claude/host-projects/<p>/bin':$PATH; exec claude` — then
+passed it to `wsl.exe -d <distro> -u claude --cd <wt> -- bash -lc <cmd>`.
+The `$PATH` substring goes through the same `pwsh → wsl.exe → WSL VM → bash`
+argv chain as gotcha #1, so it is silently pre-expanded to an empty Windows
+environment variable before bash ever reads it. Result: the prepend wins
+against an empty tail, and the entire system PATH disappears.
+
+**Fix as applied:** the PATH prepend lives in a per-project file inside the
+distro, written by `Install-HostShadowsForProject`:
+
+```bash
+# /home/claude/host-projects/<project>/init.sh
+export PATH='/home/claude/host-projects/<project>/bin':$PATH
+```
+
+`open-claudearium.ps1`'s `Resolve-SessionBashCommand` returns a string that
+*sources* that file: `source '/home/claude/host-projects/<p>/init.sh'; exec
+claude`. No `$VAR` in the wsl.exe argv. Bash reads the script from disk —
+where `$PATH` is just text bytes — so the prepend composes correctly with
+whatever PATH the login shell set up. Same fix philosophy as gotcha #1:
+keep argv pure-ASCII and route the dynamic content through a file/pipe.
+
+A regression test in `tests/pure/HostShadows.Tests.ps1` pins
+`Get-HostShadowInitScriptPath` to the on-disk path the launcher expects;
+the distro lane (`tests/distro/HostProjects.Tests.ps1`) end-to-end verifies
+PATH contains both the bin dir and `/usr/bin` after a host-session open.
+
+---
+
 ## Quick-reference table
 
 | If you see... | Look at gotcha |
@@ -551,3 +590,4 @@ A pure regression test in `tests/pure/Profile.Tests.ps1` exercises the
 | `host.internal` resets to nothing on reboot | [#6](#6-wsls-network-generatehosts--true-overwrites-etchosts-at-boot) |
 | `setup -Name foo` wipes the wrong distro | [#18](#18-psboundparameters-inside-a-function-is-the-functions-bound-params-not-the-scripts) |
 | `Could not find a part of the path` from `New-Item` on a `[bracket]` dir | [#19](#19-new-item--itemtype-directory--path-dir-interprets-wildcards-in-the-directory-name) |
+| Host session opens with PATH = just the bin dir (no /usr/bin) | [#20](#20-putting-path-in-the-wslexe----bash-lc-cmd-argv-makes-path-empty) |