Git browser: M4 polish

- Add **Settings > General > Git** section (`GitSection.svelte`) with three live toggles for repo chip, status column, and virtual portal. Refresh the helper text per the M4 spec; the existing chip/column descriptions get clearer wording too.
- Wire `fileExplorer.git.showVirtualGitPortal` end-to-end: new Tauri command `set_show_virtual_git_portal` flips a process-global `AtomicBool` consulted on every git volume hook, so toggling makes `cd .git` switch instantly between virtual portal and raw on-disk listing. Seeded at startup from `Settings::show_virtual_git_portal`.
- Plumb `FriendlyGitError` end-to-end. Three new variants (`ShallowBoundary`, `MissingObject`, `GitDirPermissionDenied`) plus the existing seven each map to the right `ErrorCategory` and carry warm copy. New `to_friendly_error()` builds a `volume::FriendlyError`; `encode_for_volume_error()` + `try_decode_git_friendly()` carry the structured payload through `VolumeError::IoError` so the streaming pipeline rebuilds it on the way out, and `ErrorPane` renders it directly.
- Extend the existing `error_messages_never_contain_error_or_failed` rule to every git variant.
- Add a Playwright spec (`git-portal.spec.ts`) that synthesizes a tiny git repo at test time and exercises the four key scenarios from the plan: `.git` shows virtual entries, `branches/main/` browses tree at HEAD, history-pane file preserves executable bit on disk, and toggling the portal off reveals raw `.git` contents.
- Refactor `settings-applier.ts` to keep the cyclomatic complexity under the 15 cap by table-driving the passthrough handlers.
- Update `CHANGELOG.md`: replace the M1-M3 stubs with a single user-facing block under `[Unreleased]` describing the five new things users can do.
- Update every git-touching `CLAUDE.md` (`file_system/git/`, `file_system/volume/`, `file-explorer/git/`) and mark the git module complete in `docs/architecture.md`.

`./scripts/check.sh` clean (Rust + Svelte + scripts + website + API). 1545 Svelte tests + 1465 Rust unit tests + 26 Rust integration tests pass; the new portal-toggle test and friendly-error sentinel round-trip test pass too.

Author: vdavid

CHANGELOG.md

@@ -9,28 +9,28 @@ The format is based on [keep a changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
-- **Git repo chip in the breadcrumb.** Open a folder inside a git clone and the breadcrumb shows a chip with the current
-  branch, ahead/behind counts vs the upstream, and a "dirty" indicator when the worktree has uncommitted changes.
-  Detached HEAD shows the short SHA; freshly-initialized repos show "no commits yet". Updates live as you commit, fetch,
-  or branch from the terminal — no polling, no refresh button. Toggle via **Settings > General > Git > Show repo chip**.
-  Foundation for the upcoming `.git` virtual portal (next milestone).
-- **Optional Git status column in Full mode.** Adds a single-glyph column (`M`, `A`, `D`, `?`, `!`) showing each file's
-  git status. Hidden by default; enable in **Settings > General > Git > Show git status column**.
-- **Virtual `.git` portal.** Step into the `.git` folder of any clone and instead of seeing libgit internals, you'll see
-  `branches/`, `tags/`, and a `raw/` escape hatch. Drill into a ref like `branches/main/` and you're browsing the
-  working tree at that commit — preview files, sort, copy. Cross-volume copy works too: drag a file from
-  `.git/branches/feature-x/src/foo.rs` into the working tree to pluck a single file from another branch, no
-  `git checkout` needed. Breadcrumb segments inside the portal pick up a dedicated git-portal color so it's clear you're
-  in history-land. Refs with slashes (like `feature/foo`) render as one entry, not nested folders. Read-only — writes
-  are blocked at the volume layer.
-- **Commits, stash, worktrees, and submodules in the `.git` portal.** The portal now also exposes `commits/`, `stash/`,
-  `worktrees/`, and `submodules/`. Open `commits/` to browse HEAD-reachable history (newest first, capped at 5000 with a
-  "Load more" entry); each entry's name shows the short SHA plus the subject, and dates drive the date-sort. You can
-  also type or paste any commit SHA directly — `.git/commits/<sha>/...` resolves even for unreachable commits in shallow
-  clones. Stash entries appear as `stash/0/`, `stash/1/`, … browsing the working-tree state at stash time. Linked
-  worktrees and submodules show as redirect entries: opening one navigates straight to its working dir (which is itself
-  a git portal — turtles all the way down). The chip and listings stay live as you commit, stash, or `git worktree add`
-  from the terminal.
+- **Git browser.** Cmdr now treats every git repo as first-class. Five things you can do that you couldn't before:
+  - **See branch + dirty state at a glance.** Open a folder inside a git clone and the breadcrumb shows a pill with the
+    current branch, ahead/behind counts vs upstream, and a dirty indicator. Detached HEAD shows the short SHA; brand-new
+    repos show "no commits yet". The pill updates live as you commit, fetch, or branch from a terminal — no polling, no
+    refresh button.
+  - **Browse history as folders.** Step into `.git` and see `branches/`, `tags/`, `commits/`, `stash/`, `worktrees/`,
+    `submodules/`, plus a `raw/` escape hatch. Drill into `branches/main/` (or `commits/<sha>/`) and you're browsing the
+    working tree at that point in history. Refs with slashes like `feature/foo` render as one entry, not nested folders.
+    Breadcrumb segments inside the portal use a dedicated git-portal color so it's clear you're in history-land.
+  - **Pluck a single file from another branch or commit.** Drag a file out of the history pane into the working tree.
+    Cmdr preserves the bytes and the executable bit. No `git checkout`, no risk of touching anything else. Type or paste
+    any SHA directly to reach unreachable commits, even in shallow clones.
+  - **Open linked worktrees and submodules with one keypress.** Each shows as a redirect entry — opening it jumps
+    straight to its working dir, which is itself a git portal. Turtles all the way down.
+  - **Show per-file git status in Full mode.** Optional column with single-glyph codes (`M`, `A`, `D`, `?`, `!`) and
+    long-form `aria-label`s for screen readers. Off by default; enable in **Settings > General > Git**.
+- **Friendly errors for the git browser.** Whatever goes wrong — the repo's damaged, the worktree's orphaned, the
+  commit's beyond a shallow boundary, the `.git` folder isn't readable, the file's too big to load from history, another
+  git command holds the index — Cmdr shows a warm, plain-language explanation in the error pane plus a concrete next
+  step, not a raw stack trace.
+- **Toggle each piece independently.** Three switches in **Settings > General > Git**: show the repo chip, show the
+  status column, and show the virtual portal. Disabling the portal lets `.git` browse like any other folder.
 
 ## [0.14.0] - 2026-04-26
 

apps/desktop/src-tauri/src/commands/settings.rs

@@ -108,6 +108,15 @@ pub fn set_error_reports_enabled(value: bool) {
     crate::error_reporter::auto_dispatcher::set_enabled(value);
 }
 
+/// Enable or disable the virtual `.git` portal. When off, navigating into
+/// `.git` shows the raw on-disk contents instead of the branches/tags/commits
+/// virtual folders. Pushed live from the frontend whenever
+/// `fileExplorer.git.showVirtualGitPortal` changes.
+#[tauri::command]
+pub fn set_show_virtual_git_portal(enabled: bool) {
+    crate::file_system::git::set_virtual_portal_enabled(enabled);
+}
+
 /// Update menu accelerator for a command.
 /// Called from frontend when keyboard shortcuts are changed.
 #[tauri::command]

apps/desktop/src-tauri/src/file_system/git/CLAUDE.md

@@ -1,15 +1,19 @@
-# File system › git (M1 foundation + M2 virtual portal + M3 history)
-
-Backend module for the git browser. M1 ships repo discovery, repo info,
-status, the watcher, and friendly errors. M2 adds the virtual `.git`
-portal — `branches/`, `tags/`, `raw/` browsable as virtual trees, with
-cross-volume copy "for free" because git blobs flow through the existing
-`VolumeReadStream` abstraction. **M3 (this milestone) fills in commits,
-stash, worktrees, and submodules. The first two browse a commit tree
-just like branches/tags. The latter two surface `redirectToPath` so the
-frontend opens the worktree's / submodule's working dir directly — those
-working dirs are themselves git portals, so the experience cascades for
-free.**
+# File system › git (complete: M1 + M2 + M3 + M4)
+
+Backend module for the git browser. M1 shipped repo discovery, repo
+info, status, the watcher, and the friendly-error skeleton. M2 added
+the virtual `.git` portal — `branches/`, `tags/`, `raw/` browsable as
+virtual trees, with cross-volume copy "for free" because git blobs flow
+through the existing `VolumeReadStream` abstraction. M3 filled in
+commits, stash, worktrees, and submodules: the first two browse a
+commit tree just like branches/tags; the latter two surface
+`redirectToPath` so the frontend opens the worktree's / submodule's
+working dir directly. **M4 (this milestone) adds three things: a live
+toggle for the portal so `cd .git` can fall through to raw on-disk
+contents, FriendlyError integration end-to-end so every git failure
+reaches `ErrorPane` with a warm title + explanation + suggestion, and
+three new error variants (`ShallowBoundary`, `MissingObject`,
+`GitDirPermissionDenied`).**
 
 ## File map
 
@@ -27,7 +31,7 @@ free.**
 | `read_blob.rs` | `GitBlobReadStream` — owns the full `Vec<u8>` and yields 256 KB chunks. See *Honest blob streaming* below |
 | `status.rs` | `list_status(repo, dir)` shells out to `git status --porcelain=v2 -z`. Parses the output into a `Vec<EntryStatus>` |
 | `watcher.rs` | `GitWatcherRegistry` — per-repo notify-rs debouncer. `subscribe(app, root)` returns the current `RepoInfo` synchronously and emits `git-state-changed` on relevant `.git/*` mutations. 200 ms debounce. M2: also calls `notify_directory_changed(.., FullRefresh)` for any cached `.git/{branches,tags}/` listings on the local volume |
-| `friendly.rs` | `FriendlyGitError`, `FriendlyGitErrorKind` — seven variants (M1's six + `BlobTooLarge`). Active-voice copy, no "error" / "failed" |
+| `friendly.rs` | `FriendlyGitError`, `FriendlyGitErrorKind` — ten variants (M1's six, `BlobTooLarge` from M2, plus M4's `ShallowBoundary`, `MissingObject`, `GitDirPermissionDenied`). Active-voice copy, no "error" / "failed". `to_friendly_error()` builds a `volume::FriendlyError` for `ErrorPane`; `encode_for_volume_error()` + `try_decode_git_friendly()` carry the structured payload through `VolumeError::IoError` so the streaming pipeline rebuilds it on the way out |
 | `tests.rs` | M1 tests: discover, repo_info, status, friendly errors |
 | `m2_tests.rs` | M2 tests: classify, list_branches/tags/root, list_tree, blob-read parity with `git show`, cross-volume copy round-trip |
 | `m3_tests.rs` | M3 tests: list_commits + sha browsing + cancellation + 1000-commit walk (`#[ignore]`), list_stashes, list_worktrees + redirect, list_submodules + redirect, watcher invalidation for `commits/` |
@@ -41,6 +45,7 @@ Wired from `commands/file_system/git.rs`:
 - `subscribe_git_state(repo_root) -> RepoInfo` — registers a subscriber, returns current `RepoInfo` synchronously, then emits `git-state-changed` events
 - `unsubscribe_git_state(repo_root) -> ()` — drops one subscriber; tears down the watcher when refcount hits zero
 - `get_git_status_for_paths(repo_root, dir) -> TimedOut<Vec<EntryStatus>>` — porcelain v2 walk, 5 s timeout
+- `set_show_virtual_git_portal(enabled)` (in `commands::settings`) — flips the live portal toggle. Pushed by `settings-applier.ts` whenever `fileExplorer.git.showVirtualGitPortal` changes
 
 ## Watcher path set
 
@@ -110,6 +115,31 @@ Branches like `feature/foo` show as a single entry called `feature/foo`, not nes
 
 ## Decisions
 
+**Decision (M4)**: Live-toggleable portal via a process-global `AtomicBool`
+**Why**: `try_route_listing` / `try_route_metadata` / `try_open_blob_stream`
+each early-return `None` when the toggle is off, falling through to the
+real-FS path. This keeps the toggle a no-op cost (one atomic load per
+hook call) and makes "show me the raw `.git`" instant — no listing
+cache invalidation, no IPC dance. The setter is wired live from the
+frontend (`set_show_virtual_git_portal`) and seeded at startup from
+`Settings::show_virtual_git_portal`. Mutation guards (`is_virtual` in
+`local_posix`) intentionally don't consult the toggle: even with the
+portal off we don't want Cmdr to write to `.git/HEAD` from a copy
+dialog. Power users who really want to mutate `.git` use a terminal.
+
+**Decision (M4)**: Carry git-friendly payloads through `VolumeError::IoError`
+**Why**: `volume_hooks` return `Result<_, VolumeError>` (the contract is
+fixed), but the streaming pipeline calls `friendly_error_from_volume_error`
+to compute the `ErrorPane` payload — and that function previously knew
+nothing about git. Adding a `Friendly(FriendlyError)` variant to
+`VolumeError` would ripple through ~12 call sites. Instead, we serialize
+`FriendlyGitError` into the `IoError::message` field with a sentinel
+prefix (`__GIT_FRIENDLY__:<token>:<path>:<title>: <explanation>`) and
+have `friendly_error_from_volume_error` recognize and decode it
+up-front. Round-trip tested in `friendly::tests`. The encoded form
+also reads naturally in logs (`grep "__GIT_FRIENDLY__"` finds every
+git failure that bubbled to the user).
+
 **Decision (M3)**: Shell out to `git stash list` rather than driving gix
 **Why**: gix 0.81 doesn't expose a public stash-list API. We could parse
 the `refs/stash` reflog by hand, but `git stash list -z --format=%H%x09%gd%x09%s%x09%ct`