treebox 1.0.0__tar.gz → 1.0.2__tar.gz

{treebox-1.0.0 → treebox-1.0.2}/.agents/skills/treebox/SKILL.md

@@ -26,11 +26,11 @@ Provisioning (fetch → resolve branch → worktree add → copy submodules →
 ## Command reference
 
 - `create [NAME]` — provision and launch. Flags: `--base <branch>` `--checkout <existing-branch>` `--isolation host|docker` `--harness claude|codex` `--template <name>` `--cold` `--no-fetch` `--firewall/--no-firewall` `--dry-run` `--print` `--json` `--repo <path>` `--root <dir>` `--quiet` `--verbose`.
-- `enter REF [-- AGENT_ARGS…]` — re-launch in an existing worktree; refreshes `.env`, reuses recorded isolation/firewall/harness/template defaults, and re-syncs deps only if the lockfile changed. Flags: `--isolation` `--harness` `--template <name>` `--cold` `--print` `--json` `--repo` `--root` `--quiet` `--verbose`.
-- `list` (alias `ls`) — table of worktrees (branch · isolation · deps freshness · `.env` presence · directory). Flags: `--repo` `--root` `--json`.
+- `enter REF [-- AGENT_ARGS…]` — re-launch in an existing worktree; refreshes `.env`, reuses recorded isolation/firewall/harness/template defaults, and re-syncs deps only if the lockfile changed (an interrupted setup is finished rather than skipped). Flags: `--isolation` `--harness` `--template <name>` `--cold` `--print` `--json` `--repo` `--root` `--quiet` `--verbose`.
+- `list` (alias `ls`) - table of worktrees (branch · recorded isolation · deps freshness · `.env` presence), with a root footer that combines with each stable name to identify its directory. Missing legacy state is shown honestly as `unknown`; `--json` includes each full `path`. Flags: `--repo` `--root` `--json`.
 - `teardown [REF...]` (alias `rm`) — remove selected worktrees; caches are left intact. Flags: `--force` `--delete-branch` `--remove-volumes` `--skip-container` `--json` `--isolation` `--repo` `--root` `--quiet` `--verbose`.
 - `template init NAME` — scaffold an operator-owned sandbox template into `$TREEBOX_HOME/templates/<name>` (copies the full required file set from the default). Flags: `--from <template>` `--force` `--json`. Then edit its `Dockerfile`/`container.json` and select with `--template <name>`.
-- `template list` (alias `ls`) — table of templates (name · source · status) with the configured default flagged; when `default` still resolves to the bundled image, also highlights what that image ships. Flags: `--json`.
+- `template list` (alias `ls`) — table of templates (name · source · firewall · status; status flags missing required files and malformed JSON, firewall shows whether the template can serve `--firewall`) with the configured default flagged; when `default` still resolves to the bundled image, also highlights what that image ships. Flags: `--json`.
 - `template path [NAME]` — print a template's resolved directory (for scripting: `cd "$(treebox template path <name>)"`).
 - `doctor` — check git, login credentials, UID/GID, and isolation deps. Flags: `--isolation` `--repo` `--json`.
 - `version` / `--version` / `-V` — print the version.
@@ -54,7 +54,7 @@ treebox teardown fix-auth --force --delete-branch
 Provision without launching the agent (for scripting / over SSH / when you only need the worktree prepared):
 
 ```bash
-treebox create fix-auth --dry-run  # print the git/setup commands it would run; change nothing
+treebox create fix-auth --dry-run  # print the git/setup commands it would run; change nothing (fails like a real create on conflicts)
 treebox create fix-auth --print    # prints the launch command (self-contained: carries the worktree dir, runnable from anywhere), no launch
 treebox create fix-auth --json     # JSON {schemaVersion, name, worktree_path, branch, base, entry_command, created}
 treebox list --json                     # JSON {schemaVersion, worktrees:[…]}
@@ -70,7 +70,7 @@ Branch on the **exit code**, not the text:
 | `0` | success |
 | `1` | runtime failure, missing runner dependency, or failed doctor hard check |
 | `2` | usage — bad name/branch/config/ref or option |
-| `3` | not-found — the worktree the command needs doesn't exist |
+| `3` | not-found — the worktree, branch, or template the command needs doesn't exist |
 | `4` | auth/permission — `origin` fetch failed |
 | `5` | conflict — already exists / worktree lock held / uncommitted changes |
 
@@ -84,10 +84,11 @@ With `--json`, a failure prints **one object on stderr**: `{"schemaVersion":1,"e
 - Every worktree gets a pre-push guard that blocks pushing any `treebox/*` ref: generated placeholder branches must be renamed (`git branch -m <type>/<short-name>`) before push; explicitly named branches push as-is.
 - `create` launches the agent (Claude by default) after provisioning and exits with the agent process's exit code. Use `--harness codex`, or `--print` / `--json` / `--dry-run` to avoid launching.
 - Re-running `create` on a fully provisioned same-name worktree is a `SLUG_CONFLICT` (exit `5`), not an idempotent enter. Use `enter` to re-launch. If the dir exists but setup never finished (a prior run died mid-provision), `create` resumes setup instead of launching into a half-built tree.
+- `--dry-run` enforces the same read-only preconditions as a real `create` with the same exit codes and JSON errors (`BRANCH_EXISTS`, `SLUG_CONFLICT`, `NOT_FOUND` for a missing `--checkout`/base branch, `BRANCH_IN_USE`, `TEMPLATE_NOT_FOUND` for a docker `--template` that doesn't resolve, `TEMPLATE_INVALID` for one that resolves but whose `container.json`, or `firewall.json` with `--firewall`, is broken), so it doubles as a safe preflight; the half-provisioned same-name case previews resuming setup instead of a fresh `worktree add`. Verdicts reflect the refs already available locally (a dry run never fetches); run `git fetch origin` first when exact parity with create's fetch is required. Nothing changes on disk or in git either way.
 - **Freshness is enforced.** `create` *requires* a successful `git fetch origin` and branches from the freshly-fetched `origin/<base>` (preferred over a stale local branch). If the fetch fails it exits `4` and does **not** fall back to stale refs. In a terminal, git/ssh will prompt for credentials (no pre-loaded ssh-agent needed); headless/`--json` runs need working non-interactive auth. Pass `--no-fetch` only when the user explicitly accepts possibly-stale local refs (e.g. offline). A repo with no `origin` skips the fetch. Run `doctor` to check origin reachability up front.
-- `enter` recomputes the dependency-manifest hash and re-syncs only when deps changed; it always refreshes `.env`. It reuses the worktree's recorded isolation/firewall/harness/template defaults, so config changes do not silently change an existing worktree. A mismatched explicit `--isolation` is a conflict; explicit `--harness` and `--template` are per-session overrides. Pass extra agent args after `--`. `--cold` bypasses the shared cache.
+- `enter` recomputes the dependency-manifest hash and re-syncs only when deps changed; if a prior run died before setup completed, it finishes setup even when the hash is unchanged. It always refreshes `.env`. It reuses the worktree's recorded isolation/firewall/harness/template defaults, so config changes do not silently change an existing worktree. A mismatched explicit `--isolation` is a conflict; explicit `--harness` and `--template` are per-session overrides. Pass extra agent args after `--`. `--cold` bypasses the shared cache. For a docker worktree whose container stopped (host reboot, manual `docker stop`), the container is restarted and the firewall re-applied before the agent launches - and before a `--print`/`--json` command is emitted, so the emitted command is never dead on replay.
 - `--cold` is the escape hatch for a corrupted cache: from-source dependency resolution.
-- `teardown` confirms interactively. Without a TTY (scripts/agents) or with `--json` it refuses unless `--force` (exit `5`); `--force` is also required to remove a worktree with uncommitted changes. `--json` prints a record of what was removed to stdout. `--skip-container` leaves containers/images alone; cleanup failures are best-effort (`container: "failed"`) and do not undo worktree removal. With host isolation there are no containers/volumes to remove.
+- `teardown` confirms interactively. Without a TTY (scripts/agents) or with `--json` it refuses unless `--force` (exit `5`); `--force` is also required to remove a worktree with uncommitted changes. A corrupt worktree (its `.git` pointer file missing) is never misreported as `DIRTY_WORKTREE` from the main checkout's uncommitted changes: it takes the normal confirmation path (`NEEDS_CONFIRMATION` under `--json`/non-TTY; `--force` removes the directory and git's stale registration without touching the main checkout; container cleanup still follows the recorded isolation, recovered from git's own registration rather than the missing pointer). `--json` prints a record of what was removed to stdout. `--skip-container` leaves containers/images alone; cleanup failures are best-effort (a failed container/image removal is `container: "failed"`, every remaining cleanup step is still attempted) and do not undo worktree removal. A failed volume removal alone reports `volumes_removed: false` without marking the container `failed`. If Docker is unavailable, the worktree is still removed and the record reports `container: "skipped"` with `volumes_removed: false`; `volumes_removed` is `true` only when docker volumes were actually removed. With host isolation there are no containers/volumes to remove (`volumes_removed` is always `false`).
 - Only one `create`/`enter`/`teardown` may operate on a given worktree name at a time (a per-name lock, exit `5` if held). Wait rather than retrying immediately.
 - Output: a compact spinner + green checkmarks with right-aligned timings on stderr, degrading gracefully off-TTY and under `NO_COLOR` (no color/animation). `--verbose` streams raw command output; `--quiet` suppresses progress. `--json` success payloads and `--print` commands write to stdout; human `--dry-run` writes its plan to stderr, while `--dry-run --json` writes JSON to stdout.
 - The container firewall is off by default; pass `--firewall` to merge in the generated outbound allowlist. `--firewall`/`--no-firewall` is a tri-state override — an explicit flag wins in either direction and absence falls through to the `firewall` config default (so `--no-firewall` opts a single run out of a `firewall = true` config). The created-time choice is recorded, so `enter` reuses it rather than re-resolving the config.
@@ -95,6 +96,6 @@ With `--json`, a failure prints **one object on stderr**: `{"schemaVersion":1,"e
 ## Notes
 
 - Authentication is **subscription-login only**: a one-time `claude` / `codex` login on the host (`~/.claude`, `~/.codex`) is reused everywhere. `doctor` verifies those dirs. `ANTHROPIC_API_KEY` is never used.
-- Defaults (`isolation`, `harness`, `base`, `root`, `env_file`, `firewall`, caches, custom setup hook) are configurable via a user-level TOML at `$TREEBOX_CONFIG`, else `$TREEBOX_HOME/config.toml` (default `~/.treebox/config.toml`). There is no repo-level config (a repo you don't trust must not run host commands).
+- Defaults (`isolation`, `harness`, `base`, `root`, `env_file`, `firewall`, caches, custom setup hook) are configurable via a user-level TOML at `$TREEBOX_CONFIG`, else `$TREEBOX_HOME/config.toml` (default `~/.treebox/config.toml`). There is no repo-level config (a repo you don't trust must not run host commands). Path-valued settings (`root`, `env_file`, `caches` entries, the `TREEBOX_*` env vars) and the `--repo`/`--root` flags expand a leading `~`; plain relative `root`/`env_file` values stay repo-relative.
 - The sandbox container is always defined by the operator template, never by anything in the target repo. Templates are named (`--template <name>`, default `default`): resolved from `$TREEBOX_TEMPLATE_DIR`, then `$TREEBOX_HOME/templates/<name>/` (default `~/.treebox/templates/<name>/`), then the bundled default (only for `default`). An unknown name is a loud error, not a fallback. The rendered config + build context live *outside* the mounted worktree (`<root>/.containers/<branch>/`) and are never mounted in, so the boxed agent can't read or edit its own cage.
 - Shared package caches live on the host and are reused across worktrees (and bind-mounted into containers), so a fresh worktree sets up at near warm-tree speed.

{treebox-1.0.0 → treebox-1.0.2}/.agents/skills/treebox-e2e/SKILL.md

@@ -99,7 +99,7 @@ scenario you add.
 e2e_cleanup   # reaps treebox-e2e-* docker containers/images, then removes $SBX
 ```
 
-`e2e_cleanup` is one pass: it reaps every `treebox-e2e-*` docker artifact — so H5's
+`e2e_cleanup` is one pass: it reaps every `treebox-e2e-*` docker artifact — so H6's
 intentional `--skip-container` leftover and any containers from a crashed run go
 too — and then removes the sandbox dir. If a run died before you could call it,
 `e2e_reap_docker` alone clears the docker side; it only ever touches

{treebox-1.0.0 → treebox-1.0.2}/.agents/skills/treebox-e2e/references/scenarios.md

@@ -42,7 +42,10 @@ Conventions used below:
       no literal to match; a `0.7.1.dev12`-style value is normal off a tag.)
 - [ ] **A2 doctor human** — `tb doctor --repo "$REPO"`
       Expect: exit 0 when git + at least one harness login are healthy; check
-      rows on stderr are readable off-TTY (no raw ANSI garbage when piped).
+      rows on stdout are readable off-TTY (no raw ANSI garbage when piped).
+      Against a repo with no `.env`, the `.env` row is a muted `·` note ending
+      in `· optional` (still showing the configured path), never a red `✗`,
+      and the exit code stays 0.
 - [ ] **A3 doctor json** — `tb doctor --repo "$REPO" --json`
       Expect: exit 0; JSON on stdout with `ok`, `isolation`, `checks[]`,
       `advisories`; `ok` true iff every hard check passed.
@@ -94,6 +97,16 @@ Conventions used below:
       on **stderr**, stdout empty. JSON mode: object on **stdout** with
       `"dry_run": true` and a `commands` array. Both: exit 0 and
       `$ROOT/plan-x` does not exist.
+- [ ] **B10b --dry-run preflights like a real create** -
+      `tb create fix-auth --repo "$REPO" --root "$SBX/wts2" --dry-run --json`
+      (branch `fix-auth` exists from B1)
+      Expect: exit 5; JSON error `BRANCH_EXISTS` on stderr, stdout empty;
+      `$SBX/wts2/fix-auth` not created and `git -C "$REPO" worktree list`
+      unchanged - a dry run fails with the same error a real create would,
+      never printing a plan a real run refuses. Same parity for
+      `SLUG_CONFLICT` (existing dir), `NOT_FOUND` (missing `--checkout`/base
+      branch, exit 3), and `BRANCH_IN_USE` (`--checkout` of a checked-out
+      branch).
 - [ ] **B11 --print** — `tb create print-x --repo "$REPO" --root "$ROOT" --print`
       Expect: exit 0; stdout is exactly one runnable launch command that carries
       the worktree dir (self-contained — no reliance on cwd) and the harness
@@ -149,8 +162,10 @@ Prereq: `fix-auth` worktree from B1 exists.
 
 - [ ] **D1 human table** — `tb list --repo "$REPO" --root "$ROOT"`
       Expect: exit 0; one row per worktree with name, live branch, isolation,
-      deps freshness, `.env` presence; renamed branches (C4) show the new
-      branch under the stable name.
+      deps freshness, `.env` presence, plus one worktree-root footer; renamed
+      branches (C4) show the new branch under the stable name. A registration
+      without readable Treebox state shows isolation as `unknown`, never the
+      current config default.
 - [ ] **D2 json shape** — `tb list --repo "$REPO" --root "$ROOT" --json`
       Expect: exit 0; `worktrees[]` where each entry has `name`, `branch`,
       `unnamed`, `missing`, `path`, `base`, `isolation`, `harness`, `deps`
@@ -183,6 +198,15 @@ Prereq: `fix-auth` worktree from B1 exists.
 - [ ] **E6 teardown resolves original name after rename** — covered by tearing
       down `fix-auth` (E1–E3) *after* C4 renamed its branch: the original name
       must still resolve.
+- [ ] **E7 corrupt worktree is not "dirty"** - create a throwaway `e2e-corrupt`,
+      remove its pointer file (`rm "$ROOT/e2e-corrupt/.git"`), dirty the main
+      checkout (`touch "$REPO/main-dirt.txt"`), then teardown without `--force`
+      (`--json`)
+      Expect: exit 5 with `NEEDS_CONFIRMATION`, *not* `DIRTY_WORKTREE` (the main
+      checkout's dirt must not be attributed to the corrupt tree); then with
+      `--force --json`: exit 0, directory gone, registration pruned from
+      `git -C "$REPO" worktree list`, and `$REPO/main-dirt.txt` untouched
+      (clean it up afterwards).
 
 ## F. template
 
@@ -227,7 +251,7 @@ Each writes `$TREEBOX_CONFIG`, runs, then restores the empty file (`: > "$TREEBO
 
 **Name every worktree here with the `e2e-` prefix** (see the docker naming marker
 in the preamble): the container/image become `treebox-e2e-*`, so `e2e_cleanup` /
-`e2e_reap_docker` remove them even when a scenario (H5's `--skip-container`) leaves
+`e2e_reap_docker` remove them even when a scenario (H6's `--skip-container`) leaves
 one behind on purpose.
 
 - [ ] **H1 docker create** — `tb create e2e-dockered --repo "$REPO" --root "$ROOT" --isolation docker --print`
@@ -255,7 +279,14 @@ one behind on purpose.
       `--isolation` flag
       Expect: exit 0; still docker (recorded at create), even if the config
       default says host.
-- [ ] **H5 docker teardown** — `tb teardown e2e-dockered … --force --json`; then
+- [ ] **H5 stopped container revived on enter** — `docker stop` the
+      `treebox-e2e-dockered-*` container, then `tb enter e2e-dockered … --print`
+      Expect: exit 0; the container is running again (`docker ps`) *before* the
+      command is printed, so the emitted `docker exec …` replays cleanly — a
+      stopped sandbox never yields a dead entry command. With a `--firewall`
+      worktree, egress lockdown is re-applied on the restart (iptables rules
+      don't survive a container restart).
+- [ ] **H6 docker teardown** — `tb teardown e2e-dockered … --force --json`; then
       `--remove-volumes` on a fresh `e2e-dockered2`; then `--skip-container` on a
       fresh `e2e-dockered3`
       Expect: exit 0 each; `--remove-volumes` reports `volumes_removed: true`;

treebox-1.0.2/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to treebox will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.1] - 2026-07-10
+
+### Fixed
+
+- Path-valued configuration now expands a leading `~` consistently for
+  `root`, `env_file`, cache paths, `TREEBOX_*` environment variables, and the
+  `--repo` / `--root` CLI flags. Relative `root` and `env_file` values remain
+  repository-relative (#6).
+
+- `create --dry-run` now enforces the same read-only preconditions as a real
+  `create` - `BRANCH_EXISTS` for a name whose branch already exists,
+  `SLUG_CONFLICT` for an occupied worktree directory, `NOT_FOUND` (exit 3) for
+  a missing `--checkout` or base branch, `BRANCH_IN_USE` for a `--checkout`
+  branch already backing another worktree - failing with the same exit codes
+  and JSON errors instead of printing a plan a real run would refuse (#4).
+  A half-provisioned same-name worktree previews finishing setup, mirroring
+  real `create`; a dry run still changes nothing on disk or in git.
+
+- `teardown` no longer misreports a corrupt worktree (a registered directory
+  whose `.git` pointer file is missing) as `DIRTY_WORKTREE` when the *main*
+  checkout has uncommitted changes: git linkage is verified before the
+  dirtiness check, so the corrupt tree takes the normal confirmation path
+  instead (`NEEDS_CONFIRMATION` under `--json` / non-TTY), and `--force`
+  removes the directory and git's stale registration without touching the
+  main checkout's files (#3). Container cleanup survives the corruption too:
+  the recorded isolation and template are recovered through git's own worktree
+  registration rather than the missing `.git` pointer, so a corrupt docker
+  worktree is still torn down with the runner it was created with.
+
+- `doctor` no longer renders a missing (optional) `.env` as a red `✗` failure
+  row before concluding all-good: the row is now a muted `·` note marked
+  `optional`, still showing the configured path (#5). Exit codes and the
+  `--json` payload are unchanged.
+
+- `treebox enter` now finishes an interrupted setup: when a prior run died
+  before setup completed, `enter` re-runs setup (reporting "setup never
+  completed") instead of skipping it as up-to-date because the lockfile hash
+  is unchanged, and records the worktree as provisioned once it succeeds (#7).
+
+- `teardown --json` now reports what runner cleanup actually did: when Docker
+  is unavailable the worktree is still removed but the record says
+  `container: "skipped"` with `volumes_removed: false` (even under
+  `--remove-volumes`), and `volumes_removed` is `true` only when docker
+  volumes were really removed - never on host isolation (#2).
+
+## [1.0.0] - 2026-07-06
+
+First stable release. treebox is Apache-2.0 licensed and ready for production
+use: isolated, ready-to-run git worktrees for AI coding agents, run host-native
+or inside a docker sandbox.
+
+### Added
+
+- `treebox template init|list|path` — scaffold and inspect operator-owned docker
+  sandbox templates from any install (`uv tool` / pipx included), so customizing
+  a sandbox no longer means hand-copying the shipped template directory or
+  reaching into the package internals (#155).
+
+### Changed
+
+- **Breaking:** `treebox create NAME` now uses `NAME` directly as the branch
+  name, created fresh from `origin/<base>` — no more `treebox/NAME`
+  placeholder or forced rename for explicitly named work (#153). Names may
+  contain slashes (`feature/auth`); the directory flattens them to `--`
+  (`feature--auth`). Scripts that expected the guarded `treebox/<NAME>`
+  placeholder get a directly pushable `NAME` branch instead. The `treebox/`
+  prefix is rejected as a name (`INVALID_NAME`), and naming a branch that
+  already exists locally or on origin is a new `BRANCH_EXISTS` conflict
+  (exit 5) pointing at `--checkout`.
+- The pre-push guard is now installed in **every** worktree (including
+  explicit names and `--checkout`): pushing any `treebox/*` ref is always
+  blocked, so generated placeholder branches must still be renamed before
+  push. Nameless `create` behavior is unchanged.
+- `enter REF` for a branch that exists but has no worktree now hints
+  `treebox create --checkout REF` instead of the generic not-found advice.

{treebox-1.0.0 → treebox-1.0.2}/CLAUDE.md

@@ -78,7 +78,10 @@ Module map:
   `get_runner` and `VALID_ISOLATION` derive from it. Doctor-facing vocabulary
   (preflight detail, whether a login is a hard gate) lives in `RunnerFacts`,
   not in the run methods; teardown options (docker's `remove_volumes`) arrive
-  at the runner's constructor, never through the protocol.
+  at the runner's constructor, never through the protocol. Docker image and
+  volume ownership lives in the runner-owned
+  `.containers/<worktree>/treebox-resources.json` manifest outside the
+  sandbox mount, never in sandbox-writable worktree state.
 - **`cli.py`** (Typer) is the entry point: `create [NAME] / enter <ref> /
   list / teardown <ref>... / template <init|list|path> / doctor / version`
   (`ls`/`rm` are hidden aliases of list/teardown, `template ls` of
@@ -89,7 +92,9 @@ Module map:
   name → live branch → unique substring (`resolve.py`); ambiguity exits 2.
   `create` and `enter` share `_run_session` for runner preflight, the
   per-name lock, provision error classification, and the final
-  `--json`/`--print`/launch fork. `_reconcile_with_state` folds recorded
+  `--json`/`--print`/launch fork (the emit fork calls `runner.prepare_entry`
+  so the printed `entry_command` is never dead on replay).
+  `_reconcile_with_state` folds recorded
   creation-time choices into existing-worktree sessions before the runner and
   harness objects are resolved: recorded isolation conflicts with a mismatched
   explicit `--isolation`, while recorded firewall/harness/template protect an
@@ -105,15 +110,23 @@ Module map:
 - **`state.py`** stores per-worktree state (lockfile hash + provisioning
   choices) inside the worktree's private git dir (`.git/worktrees/<id>/`), so it
   never appears in `git status` and is pruned with the worktree. The lockfile
-  hash is what lets `enter` re-sync only when deps changed; the recorded
-  choices are what let `enter`/`teardown` recover the worktree's created-time
-  isolation, firewall, harness, and template defaults.
+  hash is what lets `enter` re-sync only when deps changed (the recorded
+  `provisioned` flag makes `enter` finish an interrupted setup even when the
+  hash matches); the recorded choices are what let `enter`/`teardown` recover
+  the worktree's created-time isolation, firewall, harness, and template
+  defaults. This state is sandbox-writable and therefore never authorizes
+  destructive host cleanup. `teardown` reads the non-destructive choices
+  through the repo's own worktree
+  registration (`load_registered`) rather than the worktree's `.git` pointer,
+  so a corrupt tree's recorded choices still drive container cleanup.
 - **`models.py`** holds the `Worktree` value object and the name-as-identity
   rule: the *name* is the directory leaf and lock key, never renamed; the
   *branch* is a mutable attribute read live from git (the agent renames it
   with `git branch -m`). Branch-shaped inputs (`create feature/auth`,
   `create --checkout feature/auth`) derive the name by flattening slashes to
-  `--` (`feature--auth`); generated names come from `names.py`.
+  `--` (`feature--auth`); generated names come from `names.py`. Also home to
+  `expand_user`, the tolerant `~`-expansion helper every path-consuming module
+  shares (an unresolvable `~user` stays literal instead of raising).
 - **`config.py`** is **user-level TOML only** (`$TREEBOX_CONFIG`, else
   `$TREEBOX_HOME/config.toml`, default `~/.treebox/config.toml`), never read
   from the target repo — a repo-level config could run arbitrary host commands.
@@ -170,9 +183,13 @@ What a sandboxed backend must **guarantee** (the security invariants):
   never exposed to the sandbox (they hold host-executed config).
 - The sandbox-defining config is rendered outside the mount, so a boxed
   agent cannot edit the definition of its own box.
+- Destructive cleanup trusts only runner-owned metadata outside the mount;
+  sandbox-writable worktree state never records Docker volume ownership.
 - The shared `.git/hooks` is presented read-only (host git executes it).
 - Egress lockdown, when enabled, exists before any workspace-derived code
-  runs (firewall-before-post-create).
+  runs (firewall-before-post-create), and is re-established when
+  `prepare_entry` restarts a stopped sandbox (iptables rules don't survive
+  a container restart).
 - Only user-level treebox config is ever read — never the target repo's.
 
 What a backend may **assume** (host locality):

{treebox-1.0.0 → treebox-1.0.2}/CONTRIBUTING.md

@@ -53,9 +53,9 @@ test against a throwaway local remote:
 ./scripts/validate.sh
 ```
 
-For issue #141 behavior-preserving refactors, `scripts/golden-diff.sh` is the
-focused snapshot-only gate. Refresh snapshots only after the issue explicitly
-accepts a behavior change.
+For behavior-preserving refactors, `scripts/golden-diff.sh` is the focused
+snapshot-only gate. Refresh snapshots only after you've deliberately accepted a
+behavior change.
 
 ```bash
 scripts/golden-diff.sh
@@ -67,6 +67,25 @@ For docs-only changes, this is enough:
 uv run --extra docs mkdocs build --strict
 ```
 
+## Commit messages
+
+treebox uses [Conventional Commits](https://www.conventionalcommits.org/):
+`type(scope): summary`, imperative and lowercase. Common types are `feat`,
+`fix`, `docs`, `refactor`, `test`, and `chore`.
+
+```
+fix: copy .env before the runner setup step
+feat(runners): add a podman isolation backend
+docs: document the template command
+```
+
+**Breaking changes** take a `!` (`feat!:`, `fix!:`) or a `BREAKING CHANGE:`
+footer. treebox's public contract is its CLI surface, its `--json` payloads
+(which carry a `schemaVersion`), and its exit codes: if you change that
+observable output, bump `SCHEMA_VERSION` when the JSON shape changes and
+regenerate the golden snapshots with `scripts/golden-diff.sh --update`. Note
+user-facing changes under `[Unreleased]` in `CHANGELOG.md`.
+
 ## Boundaries
 
 Please preserve the basics: fresh refs by default, no trust in target-repo sandbox config, and stable CLI output for scripts.

{treebox-1.0.0 → treebox-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treebox
-Version: 1.0.0
+Version: 1.0.2
 Summary: Isolated, ready-to-run git worktrees for AI coding agents — host-native or docker-sandboxed.
 Project-URL: Homepage, https://github.com/Seth-Peters/treebox
 Project-URL: Documentation, https://seth-peters.github.io/treebox/
@@ -49,6 +49,7 @@ Description-Content-Type: text/markdown
   <a href="https://github.com/Seth-Peters/treebox/actions/workflows/ci.yml"><img src="https://github.com/Seth-Peters/treebox/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://seth-peters.github.io/treebox/"><img src="https://img.shields.io/badge/docs-seth--peters.github.io%2Ftreebox-2f6f4f" alt="Documentation"></a>
   <img src="https://img.shields.io/badge/python-3.11%2B-3776ab" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-2f6f4f" alt="Platform: macOS and Linux">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-2f6f4f" alt="Apache 2.0 License"></a>
   <a href="https://www.linkedin.com/in/seth-peters/"><img src="https://img.shields.io/badge/LinkedIn-Seth%20Peters-0a66c2?logo=linkedin&logoColor=white" alt="Seth Peters on LinkedIn"></a>
 </p>
@@ -111,8 +112,8 @@ The core worktree lifecycle is five commands (`template` scaffolds docker
 sandbox templates and `version` prints the version alongside them).
 
 **Check the host.** `doctor` verifies exactly what `create` will need — git,
-agent logins, `.env`, credentials for the required fetch — and prints the fix
-for anything missing:
+agent logins, the (optional) `.env`, credentials for the required fetch — and
+prints the fix for anything missing:
 
 ```bash
 treebox doctor
@@ -150,16 +151,19 @@ so push the base first if its latest commits only exist locally.
 the worktree was created with; an explicit `--harness` overrides it for that
 session only, without changing what's recorded on disk. The ref is the name,
 the *current* branch (renames are followed live), or a unique substring of
-either. Dependencies re-sync only if the lockfile changed since last time:
+either. Dependencies re-sync only if the lockfile changed since last time; a
+setup that never completed (a prior run died mid-provision) is finished rather
+than skipped:
 
 ```bash
 treebox enter fix-auth --harness claude
 treebox enter fix-auth --harness codex -- --resume   # args after -- go to the agent
 ```
 
-**List.** See what exists, what each worktree was last doing, and what has
-gone stale — sorted by recency, with `treebox/*` placeholders flagged
-`⚠ unnamed`:
+**List.** See what exists, each worktree's recorded isolation, what it was
+last doing, and what has gone stale. Results are sorted by recency, with
+`treebox/*` placeholders flagged `⚠ unnamed`; the root footer plus each stable
+name identifies the directory without a wide path column:
 
 ```bash
 treebox list
@@ -179,7 +183,8 @@ treebox teardown                        # pick interactively
 treebox is built to be scripted, including by agents: the worktree commands and
 `doctor` take `--json` (data to stdout, diagnostics to stderr, a schema that
 only gains fields within a version), `--dry-run` prints the exact commands
-without running them, and exit codes are stable (`0` ok · `1` runtime/doctor
+without running them (and fails with the same errors a real run would, so it
+doubles as a preflight), and exit codes are stable (`0` ok · `1` runtime/doctor
 blocked · `2` usage · `3` not found · `4` auth · `5` conflict). Full
 reference in the [usage guide](https://seth-peters.github.io/treebox/usage/).
 
@@ -251,7 +256,7 @@ one per stack:
 
 ```bash
 treebox template init node          # copies from the built-in default
-treebox template list               # names, source, status, default + what the default bundles (`ls` works too)
+treebox template list               # names, source, firewall, status, default + what the default bundles (`ls` works too)
 treebox template path node          # where it lives: cd "$(treebox template path node)"
 ```
 

{treebox-1.0.0 → treebox-1.0.2}/README.md

@@ -12,6 +12,7 @@
   <a href="https://github.com/Seth-Peters/treebox/actions/workflows/ci.yml"><img src="https://github.com/Seth-Peters/treebox/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://seth-peters.github.io/treebox/"><img src="https://img.shields.io/badge/docs-seth--peters.github.io%2Ftreebox-2f6f4f" alt="Documentation"></a>
   <img src="https://img.shields.io/badge/python-3.11%2B-3776ab" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-2f6f4f" alt="Platform: macOS and Linux">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-2f6f4f" alt="Apache 2.0 License"></a>
   <a href="https://www.linkedin.com/in/seth-peters/"><img src="https://img.shields.io/badge/LinkedIn-Seth%20Peters-0a66c2?logo=linkedin&logoColor=white" alt="Seth Peters on LinkedIn"></a>
 </p>
@@ -74,8 +75,8 @@ The core worktree lifecycle is five commands (`template` scaffolds docker
 sandbox templates and `version` prints the version alongside them).
 
 **Check the host.** `doctor` verifies exactly what `create` will need — git,
-agent logins, `.env`, credentials for the required fetch — and prints the fix
-for anything missing:
+agent logins, the (optional) `.env`, credentials for the required fetch — and
+prints the fix for anything missing:
 
 ```bash
 treebox doctor
@@ -113,16 +114,19 @@ so push the base first if its latest commits only exist locally.
 the worktree was created with; an explicit `--harness` overrides it for that
 session only, without changing what's recorded on disk. The ref is the name,
 the *current* branch (renames are followed live), or a unique substring of
-either. Dependencies re-sync only if the lockfile changed since last time:
+either. Dependencies re-sync only if the lockfile changed since last time; a
+setup that never completed (a prior run died mid-provision) is finished rather
+than skipped:
 
 ```bash
 treebox enter fix-auth --harness claude
 treebox enter fix-auth --harness codex -- --resume   # args after -- go to the agent
 ```
 
-**List.** See what exists, what each worktree was last doing, and what has
-gone stale — sorted by recency, with `treebox/*` placeholders flagged
-`⚠ unnamed`:
+**List.** See what exists, each worktree's recorded isolation, what it was
+last doing, and what has gone stale. Results are sorted by recency, with
+`treebox/*` placeholders flagged `⚠ unnamed`; the root footer plus each stable
+name identifies the directory without a wide path column:
 
 ```bash
 treebox list
@@ -142,7 +146,8 @@ treebox teardown                        # pick interactively
 treebox is built to be scripted, including by agents: the worktree commands and
 `doctor` take `--json` (data to stdout, diagnostics to stderr, a schema that
 only gains fields within a version), `--dry-run` prints the exact commands
-without running them, and exit codes are stable (`0` ok · `1` runtime/doctor
+without running them (and fails with the same errors a real run would, so it
+doubles as a preflight), and exit codes are stable (`0` ok · `1` runtime/doctor
 blocked · `2` usage · `3` not found · `4` auth · `5` conflict). Full
 reference in the [usage guide](https://seth-peters.github.io/treebox/usage/).
 
@@ -214,7 +219,7 @@ one per stack:
 
 ```bash
 treebox template init node          # copies from the built-in default
-treebox template list               # names, source, status, default + what the default bundles (`ls` works too)
+treebox template list               # names, source, firewall, status, default + what the default bundles (`ls` works too)
 treebox template path node          # where it lives: cd "$(treebox template path node)"
 ```
 

{treebox-1.0.0 → treebox-1.0.2}/docs/configuration.md

@@ -38,6 +38,18 @@ uv  = "/mnt/fast/cache/uv"
 npm = "/mnt/fast/cache/npm"
 ```
 
+Every key is optional, but the vocabulary is closed: an unknown top-level key
+(a typo like `isolatoin`) is a loud error (exit `2`, with a did-you-mean
+suggestion), never silently ignored - a typo'd `isolation` or `firewall` would
+otherwise drop your security posture without warning. Only the subkeys inside
+`[caches]` are open-ended (ecosystem cache names).
+
+Path-valued keys understand a leading `~`: `root`, `env_file`, and every
+`caches` entry expand `~/…` to your home directory before use, as do quoted
+`--root '~/trees'` and `--repo '~/proj'` on the command line. Ordinary
+relative paths keep their meaning: `root` and `env_file` stay relative to the
+repo.
+
 For a new `create`, precedence is what you'd expect:
 
 ```text
@@ -48,16 +60,21 @@ For an existing worktree, `enter` and `teardown` also read the worktree's
 recorded creation-time state. Recorded isolation wins over the config default,
 and a conflicting explicit `--isolation` exits `5`; `enter` always reuses the
 recorded firewall, while recorded harness and template beat config defaults
-unless `--harness` or `--template` is passed. `teardown` uses the recorded
-template for docker volume cleanup because it has no `--template` flag.
+unless `--harness` or `--template` is passed. `teardown` removes the docker
+volumes recorded in the runner-owned
+`<worktree-root>/.containers/<worktree>/treebox-resources.json` manifest at create time.
+Worktree state under `.git` is sandbox-writable and never authorizes volume
+deletion. Older worktrees without a manifest, or worktrees whose
+`<worktree-root>/.containers/<worktree>` directory was manually deleted, skip volume removal
+with a warning instead of guessing.
 
 | Key        | Default              | What it controls                                          |
 | ---------- | -------------------- | --------------------------------------------------------- |
 | `isolation`| `host`               | Where agents run: the worktree shell, or a docker sandbox. |
 | `harness`  | `claude`             | Which agent `create` launches by default; `enter` reuses the harness the worktree was created with unless `--harness` overrides it. |
 | `base`     | `main`               | Base branch for new branches (resolved as `origin/<base>`). |
-| `root`     | `.treebox/worktrees` | Where worktree directories are created, relative to the repo. |
-| `env_file` | `.env`               | The secrets file copied into every new worktree.          |
+| `root`     | `.treebox/worktrees` | Where worktree directories are created: repo-relative, absolute, or `~`-prefixed. |
+| `env_file` | `.env`               | The secrets file copied into every new worktree; repo-relative unless absolute or `~`-prefixed. |
 | `firewall` | `false`              | Restrict container egress (docker isolation).              |
 | `template` | `default`            | Which operator template defines the sandbox.              |
 | `setup_hook` | *(auto-detect)*    | Your own setup commands instead of the detected package manager's. |
@@ -101,7 +118,7 @@ It always writes the full required file set, so a later `create` never fails
 with "*file* not found in template dir". Inspect what you have any time:
 
 ```bash
-treebox template list               # names, source, status, default + what the default bundles (`ls` works too)
+treebox template list               # names, source, firewall, status, default + what the default bundles (`ls` works too)
 treebox template path node          # where it lives: cd "$(treebox template path node)"
 ```
 
@@ -170,6 +187,9 @@ container config in the target repo itself is deliberately ignored — see
 | `TREEBOX_TEMPLATE_DIR` | Explicit template dir; wins for any `--template` name. |
 | `XDG_CACHE_HOME`  | Standard XDG base for the shared package caches treebox mounts. |
 
+All four expand a leading `~` to your home directory, like the path-valued
+config keys above.
+
 Secrets stay in files: treebox copies your repo's `.env` (or the configured
 `env_file`) into each worktree and mounts it into containers. Host isolation
 uses your live subscription login; docker isolation mounts scoped copies of the

{treebox-1.0.0 → treebox-1.0.2}/docs/how-it-works.md

@@ -72,16 +72,33 @@ files (lockfiles) at setup time and stores the hash in the worktree's private
 git dir (`.git/worktrees/<id>/`). That state never appears in `git status`,
 is pruned together with the worktree, and is what lets `enter` re-sync
 dependencies only when they actually changed — and `list` show `fresh` /
-`stale` at a glance.
+`stale` at a glance. It also records whether setup ever completed: `enter`
+finishes an interrupted setup instead of skipping it as unchanged.
 
 The same private state records the worktree's creation-time choices. For an
 existing worktree, `enter` and `teardown` recover the recorded isolation and
 template instead of drifting to today's config defaults; `enter` also reuses the
 recorded firewall, and it reuses the recorded harness unless a per-session
-harness override is passed.
+harness override is passed. That state is sandbox-writable because the Docker
+runner mounts the git common directory, so it never authorizes destructive
+host cleanup. Before first Docker setup, the runner writes exact per-workspace
+image and volume ownership to
+`<worktree-root>/.containers/<worktree>/treebox-resources.json`, outside every
+sandbox mount. `teardown --remove-volumes` validates and trusts only that
+manifest, so it can still remove volumes when the container and user template
+are both gone.
+`teardown` reads that record through the repo's own worktree registration
+rather than the worktree's `.git` pointer, so the recorded choices survive
+even a corrupt worktree whose pointer file is gone.
 An explicit `--isolation` that disagrees with the recorded mode is a conflict,
 not an override.
 
+Older worktrees without a resource manifest remain tear-downable, but volume
+removal is skipped with a warning. The same safe behavior applies if an
+operator manually deletes the `.containers/<worktree>` directory: treebox
+does not guess ownership from volume names, current templates, container
+mounts, or sandbox-writable state.
+
 ## Warmth lives in the cache, not the tree
 
 treebox detects the package manager from the repo — **uv, npm, pnpm, go, or
@@ -130,7 +147,9 @@ treebox assumes the caller is often another program:
   without parsing prose.
 - **`--json` with a `schemaVersion`** that only gains fields within a version
   (git-porcelain discipline), plus `--print` and `--dry-run` for scripts that
-  want the commands, not the side effects.
+  want the commands, not the side effects. An emitted entry command is
+  entry-ready: a stopped docker sandbox is restarted (firewall re-applied)
+  before the command is printed, never dead on replay.
 - **Per-worktree locking**, held by `create`, `enter`, and `teardown` alike,
   so racing operations on one name — two `create fix-auth` calls, or a
   `teardown fix-auth` against a concurrent provision — conflict cleanly (`5`)

{treebox-1.0.0 → treebox-1.0.2}/docs/index.md

@@ -59,7 +59,8 @@ plain SSH.
     ---
 
     Installs hardlink from shared caches (`~/.cache/uv`, the pnpm store, …).
-    `enter` re-syncs only when the lockfile changed.
+    `enter` re-syncs only when the lockfile changed (an interrupted setup
+    is finished rather than skipped).
 
 - :material-cube-outline:{ .lg .middle } **The sandbox config lives outside the box**