pi-microsandbox 0.2.0 → 0.3.0

package/README.md

@@ -2,48 +2,71 @@
 
 **Let your agents work. Stop babysitting every command.**
 
-Give an agent a task and get on with your day. Give a few agents different tasks
-and let them work in parallel. Come back to review the results.
-
-pi-microsandbox uses [Microsandbox](https://microsandbox.dev/) to run
+Give an agent a task and get on with your day. pi-microsandbox uses
+[Microsandbox](https://microsandbox.dev/) to run
 [Pi](https://github.com/earendil-works/pi)'s file and shell tools in lightweight
 microVMs. Microsandbox is an open-source, local-first runtime for isolating
 untrusted workloads, with a separate Linux kernel for each sandbox.
 
-In Git mode, each separate Pi session gets its own workspace instead of editing
-your host checkout. Each project can define its own environment and safety
-boundaries. Set them up once, then let the agents get to work.
+Each project can define its own environment and safety boundaries. Set them up
+once, then let the agent get to work.
 
 [Get started](#get-started) · [Documentation](#documentation) · [Releases](https://github.com/hcohe/pi-microsandbox/releases)
 
+## Try it
+
+Run Pi with pi-microsandbox for one session, without installing it:
+
+```sh
+pi -e npm:pi-microsandbox
+```
+
 ## Less supervision. More work getting done.
 
-- Run multiple agents in separate Pi sessions. Git mode keeps their workspaces apart, so ordinary sandboxed edits don't collide in your host checkout.
-- Let routine file and shell work happen inside the sandbox. Host execution stays an explicit escape, with approval required while the sandbox is active.
-- Step away without throwing away the work. Git-mode files survive sandbox shutdown, ready when you resume the matching session.
-- If the sandbox can't start, routed tools stop by default. They don't quietly run on your host instead.
+- Let routine file and shell work happen inside the sandbox. Host execution
+  stays an explicit escape, with approval required while the sandbox is active.
+- Work at the same path inside and outside the VM. Sandboxed writes appear in
+  the host checkout immediately, with no export step.
+- If the sandbox cannot start, routed tools stop by default. They do not quietly
+  run on your host instead.
+
+You still review what the agent produces. The point is to spend your attention
+on the results rather than supervise every step along the way.
+
+## One workspace behavior
 
-You still review what the agents produce. The point is to spend your attention
-on the results, rather than supervise every step along the way.
+There are no workspace modes. If Pi starts inside a Git worktree,
+pi-microsandbox mounts the whole worktree root read/write at the same lexical
+path in the guest. If Pi starts outside Git, it mounts the current working
+directory itself. Commands start in the original current working directory.
+
+This is a VM boundary, not checkout isolation. The selected root is fully
+visible, including `.git`, secrets such as `.env`, untracked files, and sibling
+directories. Writes change the host immediately. Multiple sessions using the
+same checkout share those files and can conflict; use separate host worktrees
+or checkouts when you need independent changes. Containers started inside the
+microVM can also reach the mounted workspace.
+
+[Understand workspace storage and legacy-volume recovery →](docs/storage.md)
 
 ## Every project gets its own boundaries
 
-Your frontend app and your internal service don't need the same sandbox.
+Your frontend app and your internal service do not need the same sandbox.
 Choose a [published variant or custom image](docs/images.md) with the tools a
 project needs, allow only the network hosts it should reach, and configure its
-file mounts and secrets. Another project can have a completely different setup,
+extra file mounts and secrets. Another project can have a different setup,
 including no network access.
 
-Keep your everyday defaults in global config and project-specific settings in
+Keep everyday defaults in global config and project-specific settings in
 `.pi-msb.toml`. Trusted project config layers over those defaults; environment
-variables and session overrides let you adjust a particular run without
-rewriting the project's setup.
+variables and session overrides let you adjust a run without rewriting the
+project setup.
 
 The agent gets an environment built for the job. Image cohorts built from this
 version include Docker Engine 29.8.0, Buildx 0.37.1, and Compose 5.5.1. The
-daemon and its containers run inside the microVM; pi-microsandbox never connects them to the
-host Docker socket. You don't have to make the same decisions every time you
-start it.
+daemon and its containers run inside the microVM; pi-microsandbox never connects
+them to the host Docker socket. Nested containers can still access the mounted
+workspace and remain subject to the outer network policy.
 
 [Configure your project's sandbox →](docs/configuration.md)
 
@@ -73,46 +96,36 @@ binary with `MSB_PATH`. See the official
 installation and runtime troubleshooting. The documentation in this repository
 covers the Pi integration.
 
-From a Git repository, start Pi with its own isolated workspace:
+Start Pi from the directory where you want to work:
 
 ```sh
-PI_MSB_MODE=git pi
+cd /path/to/project
+pi
 ```
 
-Git mode starts from committed `HEAD`. Commit any changes you want the agent to
-see first; untracked files such as `.env` and uncommitted edits stay out of the
-initial copy. An existing retained workspace is reused for a matching session.
-
-Once you're in Pi:
+Once you're in Pi, inspect the selected workspace root:
 
 ```text
 /msb status
 ```
 
-Give Pi a task. To work on another task in parallel, start a separate Pi session
-with the same command in another terminal. Each session gets its own Git-mode
-workspace.
-
-When you're ready to review an agent's work, export a file to a new destination:
-
-```text
-/msb export src/example.ts --to ../sandbox-review
-```
-
-Exports ask for confirmation and won't overwrite existing destinations.
-See [storage and retained work](docs/storage.md) for the details.
+> **Host execution is separate.** `/msb off` explicitly hands tools to the
+> host. `fallback_mode = "host"` opts into automatic host execution after a
+> sandbox failure. Neither control changes the workspace mount, and neither is
+> sandboxed. The default fallback blocks tools when startup fails.
 
-> **Choose your boundary.** The default storage mode is `direct`, which writes
-> to your host directory. The command above explicitly selects `git` isolation.
-> `/msb off` turns sandboxing off; `fallback_mode = "host"` opts into automatic
-> host execution after a failure. Neither is sandboxed.
+Upgrading from a release that used named Git volumes requires a manual recovery
+check. Before upgrading, use the old `/msb volumes` and `/msb export` commands
+to inventory and copy retained work. After upgrading, use Microsandbox's own
+tooling to recover or remove legacy volumes; they are never deleted
+automatically. See [workspace storage](docs/storage.md).
 
 ## Documentation
 
 | When you want to… | Read |
 | --- | --- |
 | Install or check host support | [Getting started](docs/getting-started.md) |
-| Choose a workspace mode or recover retained work | [Storage](docs/storage.md) |
+| Understand the workspace mount or recover legacy volumes | [Storage](docs/storage.md) |
 | Choose an image variant or build a custom image | [Images](docs/images.md) |
 | Set up networking, secrets, mounts, or other options | [Configuration](docs/configuration.md) |
 | Look up an `/msb` command | [Command reference](docs/commands.md) |

package/SECURITY.md

@@ -26,7 +26,7 @@ public channel.
 A useful report includes the affected pi-microsandbox version or commit, Pi and
 Node.js versions, host operating system and architecture, virtualization setup,
 impact, and minimal reproduction steps. State whether the behavior requires a
-particular storage mode, network policy, fallback setting, or host-execution
+particular workspace layout, network policy, fallback setting, or host-execution
 approval.
 
 ## Keep sensitive data out of reports
@@ -39,13 +39,17 @@ not include:
 - resolved secret values from `$ENV:` or `$FILE:` references;
 - complete sandbox logs, configuration dumps, session files, or command output
   that may contain secrets;
-- retained-volume contents, source code, `.env` files, or other private user
-  data that is not essential to the report.
-
-If a real secret may have been exposed, revoke or rotate it first. Use synthetic
-values in the reproduction and describe omitted material rather than attaching
-it. Remember that GitHub advisory participants can read uploaded artifacts, so
-a private report is not a reason to include unnecessary secrets.
+- workspace or legacy-volume contents, source code, `.env` files, or other
+  private user data that is not essential to the report.
+
+If a real secret may have been exposed, revoke or rotate it first. The selected
+workspace is mounted read/write: inside Git it includes the entire worktree,
+including `.git`, secrets, untracked files, and sibling directories; outside
+Git it is the current directory. Writes reach the host immediately, concurrent
+sessions share the checkout, and nested containers can access the mount. Use
+synthetic values in the reproduction and describe omitted material rather than
+attaching it. Remember that GitHub advisory participants can read uploaded
+artifacts, so a private report is not a reason to include unnecessary secrets.
 
 ## What happens next
 

package/docs/commands.md

@@ -8,9 +8,6 @@ The extension registers `/msb`:
 /msb status
 /msb on | off | reload
 /msb prune
-/msb volumes ls
-/msb volumes rm <managed-name> [--yes]
-/msb export <paths...> [--to dir] [--yes]
 /msb logs [tail-lines]
 /msb config
 /msb set <key> <value>
@@ -23,17 +20,23 @@ The extension registers `/msb`:
 /msb help
 ```
 
-`/msb status` reports the full sandbox name, mode, image, PID, age, Docker
-mode/readiness/version/storage driver, branch/SHA, and retained volume metadata
-when available. Six-character IDs in UI text are
-display abbreviations only. `/msb prune` walks all SDK list pages and reports
-removed, kept, and error entries; **volumes are never pruned**.
+`/msb status` reports the full sandbox name, mounted workspace root, image, PID,
+age, and Docker mode, readiness, version, and storage driver. Six-character IDs
+in UI text are display abbreviations only. There are no workspace modes.
 
-Volume removal is the sole destructive volume path. It requires a managed,
-unmounted volume and an owner lock. Confirmation displays path, branch, last
-commit, and dirty-count metadata; use `--yes` only when the command is running
-without UI and the target has already been verified. Export rejects paths outside
-the project and existing destinations; it also requires confirmation or
-`--yes`.
+`/msb prune` walks all SDK list pages and reports removed, kept, and error
+entries. It can remove guarded stale sandboxes, including old-schema managed
+sandboxes, but it never removes legacy named volumes.
 
-For the narrow exceptions to sandboxed file reads, see [host-read exceptions](safety.md#host-read-exceptions).
+`/msb off` explicitly switches to unsandboxed host execution. It is separate
+from `fallback_mode = "host"`, which opts into automatic host execution after a
+sandbox failure. With the default blocking fallback, startup failures fail
+closed and routed tools do not silently run on the host.
+
+The former `/msb volumes` and `/msb export` commands are not available. Files in
+the current workspace already live on the host. Legacy named volumes from older
+releases require manual inspection, recovery, and removal with Microsandbox's
+own tooling; see [workspace storage](storage.md#upgrading-from-named-git-volumes).
+
+For the narrow exceptions to sandboxed file reads, see
+[host-read exceptions](safety.md#host-read-exceptions).

package/docs/configuration.md

@@ -7,14 +7,14 @@ CLI overrides. Global configuration is `$XDG_CONFIG_HOME/pi-msb/config.toml`
 (or `~/.config/pi-msb/config.toml`) plus the optional `PI_MSB_CONFIG_FILE` in
 the same layer. A trusted project may use the nearest `.pi-msb.toml` or
 `<Pi CONFIG_DIR_NAME>/msb.toml`, stopping at the Git root. Untrusted project
-configuration is ignored with a warning.
+configuration is ignored with a warning, except that removed workspace settings
+still stop startup before any direct host write can occur.
 
 TOML uses snake_case; environment variables use `PI_MSB_` with `__` for nesting.
 The following is a small project example:
 
 ```toml
 # .pi-msb.toml
-mode = "git"
 image = "ghcr.io/hcohe/pi-microsandbox:1.1.0@sha256:ab4e99d4232f827b3f295ff3210437e01446dbb672ef0d0c78358566170ac86c"
 pull_policy = "if-missing"
 bootstrap_tools = "auto"
@@ -41,15 +41,22 @@ allow_hosts = ["registry.npmjs.org"]
 
 Important configuration behavior:
 
+- There are no workspace modes or storage selection settings. Inside a Git
+  worktree, the whole worktree root is mounted read/write at the same lexical
+  guest path; elsewhere, the current directory is mounted. Commands retain the
+  original cwd, and writes reach the host immediately. The removed `mode`,
+  `clone_branch`, `clone_depth`, `shallow_archive`, and `volume_quota_mib`
+  settings, including `PI_MSB_MODE`, are startup errors rather than ignored
+  compatibility options.
 - `show_footer = true` uses Pi's single custom-footer slot so the MSB status can
   appear in the upper-right corner. It replaces Pi's built-in footer (or another
   extension's custom footer), preserves the standard location, usage, model,
   and shared status fields, but cannot show Pi-only indicators such as the
   auto-compaction and experimental-feature markers.
-- The default image is the complete Node.js, Python, Rust, and Go `1.0.0`
+- The default image is the complete Node.js, Python, Rust, and Go `1.1.0`
   variant, pinned to its immutable multi-platform digest. Image releases have
-  an independent version stream; the initial package remains `0.1.0`. The
-  default `pull_policy = "if-missing"` pulls only when that exact reference is
+  an independent version stream from package releases. The default
+  `pull_policy = "if-missing"` pulls only when that exact reference is
   absent from the Microsandbox cache. `"always"` and `"never"` are also
   supported.
   See [Images](images.md) for all published variants, exact tag patterns,
@@ -84,8 +91,9 @@ Important configuration behavior:
   `BASH_ENV`, and `LD_PRELOAD` cannot be forwarded with `host_env` or injected
   as secrets.
 - Directory/file mounts have absolute guest paths. Project mounts outside the
-  repository must be read-only unless a global/session policy authorizes the
-  write. Mounts may not overlap or shadow the project mount, reserved `/tmp`,
+  selected workspace root must be read-only unless a global/session policy
+  authorizes the write. Mounts may not overlap or shadow the project mount,
+  reserved `/tmp`,
   protected guest system trees such as `/usr`, `/bin`, `/proc`, and `/sys`, or
   Docker runtime paths such as `/run`, `/var/run`, and `/var/lib/docker`.
   Host mount sources are canonicalized before use; socket targets, including
@@ -97,7 +105,6 @@ Useful environment controls include:
 
 ```sh
 PI_MSB_DISABLE=1                 # explicit host/off mode
-PI_MSB_MODE=none                 # nested scalar example
 PI_MSB_PULL_POLICY=always        # recheck mutable custom image tags on creation
 PI_MSB_NETWORK__MODE=deny        # nested environment key
 PI_MSB_DOCKER__MODE=require      # require a working guest Docker daemon

package/docs/development.md

@@ -103,9 +103,9 @@ just test-boot-speed
 ```
 
 The tool performs one unmeasured warm-up, then three fresh boots using the
-default prepared image. It forces direct mode, disables guest networking and
-stale-resource pruning, and sets `bootstrap_tools = false` so the result
-measures repeat boot and readiness rather than an image pull or package install.
+default prepared image. It disables guest networking and stale-resource
+pruning, and sets `bootstrap_tools = false` so the result measures repeat boot
+and readiness rather than an image pull or package install.
 The p95 must be at most 2,000 ms. Every sandbox is shut down and removed. If
 lifecycle cleanup fails, the test fails and retains its reported `.tmp` directory
 for recovery instead of claiming success.
@@ -127,9 +127,9 @@ as the live matrix.
 ## Live test matrix
 
 From a source checkout, the live matrix is opt-in because it can pull an image,
-start VMs, create retained resources, and use network and disk capacity. Run it
-only from a trusted checkout on a disposable test host after reviewing the
-script:
+start VMs, write through the host workspace mount, and use network and disk
+capacity. Run it only from a trusted checkout on a disposable test host after
+reviewing the script:
 
 ```sh
 PI_MSB_LIVE_TEST=1 ./scripts/e2e-smoke.sh
@@ -149,10 +149,14 @@ The prepared-image scenario boots all six latest variant tags under
 legacy singular `PI_MSB_LIVE_PREPARED_IMAGE` to test one image. The live matrix
 uses `pull_policy = "always"` intentionally so mutable development tags cannot
 remain stale on the self-hosted runner. Review the output to confirm that every scenario reports `PASS`, not `SKIP`.
-Docker release validation must cover daemon readiness, bridge DNS and HTTPS,
-user-defined networking, Buildx, Compose, idle wake, double port publishing,
-and nested-container enforcement for deny and allowlist policies. A skipped
-Docker scenario is not release evidence.
+The workspace scenarios must show that a Git subdirectory mounts the whole
+worktree, a non-Git cwd mounts itself, and routed writes appear immediately on
+the host. They also cover off/on and reload, stale-sandbox pruning, fail-closed
+boot errors, and approved host execution. Docker release validation must cover
+daemon readiness, bridge DNS and HTTPS, user-defined networking, Buildx,
+Compose, idle wake, double port publishing, nested-container access to the
+workspace, and network enforcement for deny and allowlist policies. A skipped
+scenario is not release evidence.
 
 ## Image development
 

package/docs/getting-started.md

@@ -64,7 +64,19 @@ blocks routed tools rather than silently running them on the host. Keep that
 default for a fail-closed setup. `fallback_mode = "host"` is an explicit,
 visibly labelled opt-in to automatic unsandboxed execution.
 
-The public package is named `pi-microsandbox`. Existing technical interfaces
-retain the shorter `msb` name for compatibility, including `/msb`,
-`PI_MSB_*`, `.pi-msb.toml`, configuration directories, and managed-resource
-labels. Existing configuration and retained resources therefore keep working.
+The public package is named `pi-microsandbox`. Current technical interfaces
+retain the shorter `msb` name, including `/msb`, `PI_MSB_*`, `.pi-msb.toml`,
+configuration directories, and managed-resource labels.
+
+There are no workspace modes. Starting inside Git mounts the entire worktree
+root read/write; starting elsewhere mounts the cwd. The mount uses the same
+lexical guest path, commands retain their original cwd, and writes reach the
+host immediately. This exposes `.git`, secrets, untracked files, and sibling
+directories. Concurrent sessions share a checkout, and nested containers can
+reach the mount.
+
+Before upgrading from a release with named Git workspaces, use its `/msb
+volumes` and `/msb export` commands to inventory and copy retained work. The new
+release neither reconnects nor deletes legacy volumes. Recover or remove them
+manually with Microsandbox tooling after confirming their contents. Removed
+settings such as `mode` and `PI_MSB_MODE` are errors, not compatibility aliases.

package/docs/images.md

@@ -66,12 +66,13 @@ can install current packages at runtime.
 
 ## Build a custom image
 
-A custom image must provide `bash`, `sh`, `git`, `rg`, `file`, `cat`, `mkdir`,
-and `rm`. Docker is optional for custom images. The default `docker.mode =
-"auto"` records it as missing and continues; use `docker.mode = "require"` when
-the image contract must include a working daemon. pi-microsandbox does not
-install Docker during sandbox startup. Install CA certificates if the guest
-will use Git over HTTPS. With
+A custom image must provide `bash`, `sh`, `rg`, `file`, `cat`, `mkdir`, and
+`rm`. Git is a useful developer tool and remains in the published images, but
+workspace setup no longer requires it inside the guest. Docker is optional for
+custom images. The default `docker.mode = "auto"` records it as missing and
+continues; use `docker.mode = "require"` when the image contract must include a
+working daemon. pi-microsandbox does not install Docker during sandbox startup.
+Install Git and CA certificates if guest commands need Git over HTTPS. With
 `bootstrap_tools = "auto"`, pi-microsandbox can install missing required
 commands through `apt-get` when the network policy permits it. A prepared image
 is required when bootstrap is disabled or package repositories are unavailable.

package/docs/safety.md

@@ -4,24 +4,35 @@
 
 The default is fail-closed:
 
-- A valid, trusted project configuration is resolved before a sandbox is
-  started. A boot or image/tool failure blocks the seven routed tools (`read`,
-  `write`, `edit`, `ls`, `find`, `grep`, and `bash`).
-- `mode = "auto"` is retained as an alias for `"direct"`; both use a
-  same-absolute-path read/write bind. `mode = "git"`, `"direct"`, and
-  `"none"` select those behaviors explicitly.
+- A valid, trusted project configuration is resolved before a sandbox starts. A
+  boot, image, configuration, or tool failure blocks the seven routed tools
+  (`read`, `write`, `edit`, `ls`, `find`, `grep`, and `bash`). Failure never
+  silently falls back to host execution.
 - `execution_target = "host"` is an opt-in escape for routed tool calls. While
-  a sandbox is active it requires an interactive approval for the exact tool,
-  working directory, and recursively sorted arguments. It is not available in
+  a sandbox is active it requires interactive approval for the exact tool,
+  working directory, and recursively sorted arguments. It is unavailable in
   headless operation and is never silently selected.
 - `/msb off` is an explicit host-mode handoff and does not prompt. This is
   different from `fallback_mode = "host"`, which automatically uses host tools
-  after a sandbox failure and is shown as `MSB host fallback`.
+  after a sandbox failure and is shown as `MSB host fallback`. Both are
+  unsandboxed controls, not workspace settings.
 - A project cannot replace another process's sandbox: ownership is a
-  non-blocking kernel `flock` acquired before any sandbox or volume mutation.
-  The small bundled POSIX addon is loaded lazily, has no install script, and
-  never falls back to a racy PID check. Stale sandbox pruning never removes
-  volumes.
+  non-blocking kernel `flock` acquired before sandbox mutation. The small
+  bundled POSIX addon is loaded lazily, has no install script, and never falls
+  back to a racy PID check.
+
+There are no workspace modes. Inside a Git worktree, pi-microsandbox
+bind-mounts the entire worktree root read/write at the same lexical guest path.
+Outside Git, it bind-mounts the current directory. Commands start in the
+original current directory, but their path boundary is the selected root.
+
+This mount deliberately exposes host files. A Git worktree mount includes
+`.git`, untracked files, secrets such as `.env`, and sibling directories even
+when Pi starts in a subdirectory. Writes are immediately visible on the host,
+and separate sessions using the same checkout can read or overwrite one
+another's work. Use separate host worktrees or checkouts for isolation between
+sessions. Unsafe root mappings fail startup rather than falling back to a
+narrower mount.
 
 The extension entry point does not import the native SDK or load the flock
 addon. Unsupported hosts can still load Pi and remain blocked or explicitly
@@ -35,15 +46,15 @@ socket. Access to that socket is root-equivalent inside the guest, not on the
 host. Readiness probes explicitly select that socket and reject unverified
 socket ownership. Docker and process-control environment variables are cleared
 for preparation, and configuration cannot forward them. Mounts that shadow
-protected guest executables or Docker runtime paths are rejected. The extension never mounts the host Docker
-socket, starts a host daemon, or copies host Docker configuration and registry
-credentials into the guest.
+protected guest executables or Docker runtime paths are rejected. The extension
+never mounts the host Docker socket, starts a host daemon, or copies host Docker
+configuration and registry credentials into the guest.
 
-A container can still reach anything already mounted into the microVM. In
-`direct` mode that includes the host project directory; in Git mode it includes
-the retained workspace; explicitly configured mounts are visible too. Treat a
-Dockerfile or Compose file as guest-root code and use read-only mounts where
-possible. Container egress remains behind the Microsandbox network policy.
+A nested container can still reach anything mounted into the microVM, including
+the entire selected workspace and explicitly configured mounts. Treat a
+Dockerfile or Compose file as guest-root code and use read-only extra mounts
+where possible. Container egress remains behind the Microsandbox network
+policy.
 
 ## Host-read exceptions
 
@@ -56,4 +67,5 @@ become readable.
 
 ## Reporting vulnerabilities
 
-Report suspected vulnerabilities privately. See the [security policy](../SECURITY.md); do not open a public issue.
+Report suspected vulnerabilities privately. See the
+[security policy](../SECURITY.md); do not open a public issue.

package/docs/storage.md

@@ -1,19 +1,31 @@
-# Storage modes and retained work
+# Workspace storage
 
 [Back to README](../README.md)
 
-## Storage modes
+## One read/write workspace
 
-| Mode | Guest view | Host effect of routed writes |
-| --- | --- | --- |
-| `git` | A named volume at the repository root, with the same absolute path | Volume only |
-| `direct` | The current directory bind-mounted at the same absolute path | Host directory |
-| `none` | An empty tmpfs at the same absolute path | No host files; changes disappear with the sandbox |
-| `auto` | Same as `direct` | Host directory |
+There are no workspace modes. pi-microsandbox selects one workspace root when
+it starts:
 
-`direct` is intentionally a warning-level escape from the Git isolation model:
-routed edits modify the live host directory. `none` is useful for testing path
-behavior and starts empty; it is not a retained workspace.
+- If the current working directory is inside a Git worktree, it mounts the
+  entire worktree root.
+- Otherwise, it mounts the current working directory itself.
+
+The selected root is bind-mounted read/write at the same lexical path inside
+the guest. Commands still start in the original current working directory.
+Writes are immediately visible in the host directory; there is no export or
+synchronization step.
+
+Starting Pi below a Git worktree root does not narrow the boundary. The sandbox
+can see the whole worktree, including `.git`, untracked files, sibling
+directories, and files such as `.env`. Separate Pi sessions that use the same
+checkout also use the same files, so their edits can conflict. Use separate
+host worktrees or checkouts when tasks need independent workspaces.
+
+The extension creates one project bind mount. Linked-worktree or submodule Git
+metadata stored outside the selected worktree root is not mounted separately.
+An unsupported path or symlink layout fails startup instead of silently
+mounting a narrower directory.
 
 ## Inner Docker state
 
@@ -21,51 +33,38 @@ Docker stores images, layers, containers, and build cache under
 `/var/lib/docker` on the sandbox root filesystem. It uses the `vfs` storage
 driver because nested overlay filesystems and project-backed mounts cannot be
 assumed to support `overlay2`. This state disappears when the sandbox is
-removed. It is not written to the project mount or retained Git volume, and
-separate sessions do not share an inner Docker cache.
-
-A stopped sandbox may retain that state until it is restarted or removed, but a
-retained Git workspace does not preserve it. Do not move Docker's data root
-onto the Git volume. A persistent Docker cache would need a separate managed
-volume and cleanup policy.
-
-## Git and retained volumes
-
-Git mode never bind-mounts the host checkout. On boot, pi-microsandbox captures the
-committed `HEAD` (and selected branch) into a temporary verified Git bundle,
-copies it into the guest, and seeds a named volume mounted at the repository's
-absolute root. Untracked files, including `.env`, and working-tree edits are
-not in that bundle. The temporary host and guest bundle files are removed after
-seeding, including failure paths.
-
-Edits and commits made in Git mode land in the retained volume. The host
-checkout is not changed by ordinary routed tools. A normal Pi session shutdown
-removes the sandbox but keeps the managed volume; the next boot reuses it only
-when the complete session/schema/mode/cwd identity matches. A copied or forked
-session state is rejected by the full session ID and gets a different resource
-identity.
-
-The SDK's `VolumeHandle` returned by `Volume.get()` does not expose a host
-path. pi-microsandbox therefore refuses to fabricate one: a newly created volume
-may show its path, while a later retained-volume lookup may not support
-`/msb volumes ls` or volume enrichment. The volume remains mountable by name
-and is never automatically deleted. Use the path recorded at creation time or
-the microsandbox volume tooling when host-side inspection is required.
-
-To manually synchronize a retained checkout, use a host-side fetch deliberately
-(the command is not performed automatically by pi-microsandbox):
+removed and is not written to the project mount. Separate sessions do not share
+an inner Docker cache.
+
+Containers started inside the microVM can reach the mounted workspace. Treat
+Dockerfiles and Compose files as code with access to the entire selected root.
+
+## Upgrading from named Git volumes
+
+Older releases could keep Git workspaces in named `pi-msb-vol-*` volumes. The
+new workspace behavior does not reconnect, migrate, or delete those volumes.
+They may contain the only copy of unexported work.
+
+Before upgrading, while the old `/msb volumes` and `/msb export` commands are
+still available, inventory every retained volume and export or copy any work
+you need. After upgrading, use Microsandbox itself:
+
+```sh
+msb volume ls
+mkdir -p ./legacy-workspace-recovery
+msb run --name pi-msb-recovery \
+  --mount-named pi-msb-vol-REPLACE_ME:/legacy:ro \
+  --mount-dir "$PWD/legacy-workspace-recovery:/recovery:rw" \
+  alpine -- sh -c 'cp -a /legacy/. /recovery/'
+msb rm pi-msb-recovery
+```
+
+Verify the copied files, then remove the old volume with:
 
 ```sh
-REPO=/absolute/path/to/checkout
-VOLUME_PATH=/path/returned-for-the-managed-volume
-BRANCH=$(git -C "$REPO" branch --show-current)
-
-git -C "$VOLUME_PATH" remote remove host 2>/dev/null || true
-git -C "$VOLUME_PATH" remote add host "$REPO"
-git -C "$VOLUME_PATH" fetch --no-tags host "$BRANCH"
-# Review before changing the retained checkout:
-git -C "$VOLUME_PATH" log --oneline --decorate --all -10
+msb volume rm pi-msb-vol-REPLACE_ME
 ```
 
-The host repository is an input to this explicit sync operation. Do not add a
-host checkout bind mount to Git mode.
+Copy the exact name from `msb volume ls`: a mistyped named mount can create a
+new empty volume. Choose an already-cached recovery image if `alpine` is
+unavailable. pi-microsandbox no longer lists, removes, or exports volumes.