treebox 0.6.0__tar.gz → 0.7.0__tar.gz

{treebox-0.6.0 → treebox-0.7.0}/.agents/skills/treebox/SKILL.md

@@ -26,7 +26,7 @@ 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`, re-syncs deps only if the lockfile changed. Flags: `--isolation` `--harness` `--template <name>` `--cold` `--print` `--json` `--repo` `--root` `--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`.
 - `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`.
 - `doctor` — check git, login credentials, UID/GID, and isolation deps. Flags: `--isolation` `--repo` `--json`.
@@ -81,7 +81,7 @@ With `--json`, a failure prints **one object on stderr**: `{"schemaVersion":3,"e
 - `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.
 - **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`. Pass extra agent args after `--`. `--cold` bypasses the shared cache.
+- `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.
 - `--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.
 - 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.

{treebox-0.6.0 → treebox-0.7.0}/.github/workflows/ci.yml

@@ -50,7 +50,8 @@ jobs:
         with:
           enable-cache: true
 
-      # Full reproducible validation: lint, tests, and a live `treebox create`
-      # against a throwaway local git remote.
+      # Full reproducible validation: lint, type checks, shell asset checks,
+      # tests, golden CLI snapshots, and a live `treebox create` against a
+      # throwaway local git remote.
       - name: validate.sh
         run: ./scripts/validate.sh

{treebox-0.6.0 → treebox-0.7.0}/CLAUDE.md

@@ -25,19 +25,34 @@ uv run --extra dev ruff check src tests # lint
 uv run --extra dev ruff format --check src tests   # format check (drop --check to apply)
 uv run --extra dev mypy                 # strict type check (config in pyproject.toml)
 uv run --extra dev pre-commit install   # install lint/format/strict type-check hooks (see CONTRIBUTING.md)
-./scripts/validate.sh                   # lint + format + tests + live host-runner smoke (real uv, throwaway local remote)
+scripts/golden-diff.sh                  # diff CLI output against tests/golden snapshots
+./scripts/validate.sh                   # full gate: lint + typecheck + shell assets + tests + snapshots + smoke
 uv pip install -e ".[dev]"              # editable dev environment
 uv run --extra docs mkdocs serve        # docs site (docs/ + mkdocs.yml), live-reloading
 uv run --extra docs mkdocs build --strict   # build docs to site/ (gitignored)
 ```
 
 Run `validate.sh` before changes that affect provisioning, runners, git
-handling, or CLI output; `pytest` is enough for smaller changes.
+handling, shell assets, or CLI output; it includes the golden CLI-output
+snapshots and shell asset checks. Use `scripts/golden-diff.sh --update` only
+after an intentional output change has been agreed. `pytest` is enough for
+smaller changes.
 
 ## Architecture
 
 The whole tool is organized around one seam: **provision (always host-side) vs.
-run (pluggable)**.
+run (pluggable)** — with three registries that define everything swappable.
+
+**The three-seam glossary** (each term is one axis, one module, one registry):
+
+- **Harness** — *which agent CLI launches* (`claude`, `codex`).
+  `harnesses.py`: the `Harness` dataclass + `HARNESSES` registry.
+- **Runner / isolation** — *where it executes* (`host`, `docker`).
+  `runners/`: the `Runner` protocol + `RUNNERS` registry.
+- **Ecosystem** — *what setup runs* (uv, npm, pnpm, go, cargo).
+  `ecosystems.py`: the `Ecosystem` dataclass + `ECOSYSTEMS` registry.
+
+Module map:
 
 - **`provision.py`** owns the host-side half, identical for every runner:
   `fetch → resolve branch → git worktree add → install pre-push guard
@@ -46,17 +61,32 @@ run (pluggable)**.
   `treebox/<name>` placeholder made un-pushable by a per-worktree pre-push
   hook (`extensions.worktreeConfig` + `core.hooksPath` into the private git
   dir); `create --checkout <existing-branch>` is the only path that skips it.
+- **`harnesses.py`** is the one place agent-CLI wiring lives: each `Harness`
+  hides its autonomous launch argv, host login dir, staged login files, and
+  login advice behind a small method interface; `VALID_HARNESSES` and the
+  doctor login rows derive from `HARNESSES`. Boundary values (CLI/TOML/state)
+  stay `str` and are resolved to the object once, in `cli.py`.
 - **`runners/base.py`** defines the `Runner` protocol — the *only* thing that
   differs between modes — implemented by **`runners/host.py`** (setup + agent in
   the worktree shell) and **`runners/docker.py`** (plain `docker build/run`,
   setup via a baked-in `post-create.sh`, agent via `docker exec`; the worktree
   and its git common dir are bind-mounted at their host paths so in-container
-  git just works). `HARNESS_COMMANDS` maps `claude`/`codex` to their
-  fully-autonomous launch argv.
+  git just works). `runners/__init__.py` holds the `RUNNERS` registry;
+  `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.
 - **`cli.py`** (Typer) is the entry point: `create [NAME] / enter <ref> /
   list / teardown <ref>... / doctor / version` (`ls`/`rm` are hidden aliases
   of list/teardown). `enter`/`teardown` resolve a ref as
   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
+  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
+  existing worktree from config-default drift.
   It enforces **stable exit codes** (`0` ok · `1` runtime/doctor hard-check ·
   `2` usage · `3` not-found · `4` auth/fetch · `5` conflict) and **`--json`**
   output carrying a `schemaVersion` that only gains fields within a version —
@@ -68,7 +98,9 @@ run (pluggable)**.
 - **`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.
+  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.
 - **`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
@@ -84,6 +116,73 @@ run (pluggable)**.
   and rendered into a host-side dir *beside* the worktree, never inside the
   mount, so a boxed agent cannot edit the config that defines its own sandbox.
 
+## Extending treebox
+
+**Adding a harness** (a new agent CLI):
+
+1. One `Harness` entry in `harnesses.py`'s `HARNESSES` registry — name,
+   autonomous argv, host login dir, staged login files. If the new CLI's
+   credentials are *behavior* rather than plain files (generated settings, a
+   non-file auth store), override the relevant methods instead of growing
+   branches in callers.
+2. Add the harness name to `config.py`'s hard-coded `Harness` Literal alias.
+   The drift test `test_registry_vocabularies_cannot_drift` must keep passing:
+   the alias, `HARNESSES`, and `VALID_HARNESSES` must name the same set.
+3. One operator-template stanza — a `Dockerfile` install line and a
+   config-dir env line in `container.json`. This half is deliberately
+   template territory (see the `assets.py` security model): treebox never
+   derives sandbox contents from code paths the target repo can influence.
+
+Runtime config validation, `--harness` help, doctor login rows, the no-login
+advice, credential staging, and sandbox mounts derive from the registry.
+
+**Adding a runner** (a new isolation backend):
+
+1. One `Runner` implementation (see the protocol in `runners/base.py` and
+   the contract below).
+2. One entry in `runners/__init__.py`'s `RUNNERS` registry — the factory
+   declares which generic options the adapter consumes.
+3. Add the isolation name to `config.py`'s hard-coded `Isolation` Literal
+   alias. The drift test `test_registry_vocabularies_cannot_drift` must keep
+   passing: the alias, `RUNNERS`, and `VALID_ISOLATION` must name the same set.
+
+Runtime config validation and the `--isolation` help derive from
+`VALID_ISOLATION`, which derives from the registry.
+
+### The isolation contract
+
+The `Runner` seam abstracts **where the agent process runs** — it does *not*
+abstract **where the workspace lives**. Host locality binds every backend;
+the security invariants bind sandboxed backends. `HostRunner` is the deliberate
+non-sandbox exception: it launches directly on the host with live
+`~/.claude` / `~/.codex` login dirs and normal host repo access.
+
+What a sandboxed backend must **guarantee** (the security invariants):
+
+- Staged credential *copies* only — the live `~/.claude` / `~/.codex` are
+  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.
+- 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).
+- Only user-level treebox config is ever read — never the target repo's.
+
+What a backend may **assume** (host locality):
+
+- Provisioning already happened host-side (`provision.py` writes the
+  worktree, guard, submodules, `.env` before the runner sees it).
+- The host filesystem is visible *at identical absolute paths*: docker
+  bind-mounts the worktree and its git common dir 1:1, state lives in the
+  host-side private git dir, the lockfile hash stats host files, and the
+  name-is-permanent rule in `models.py` presumes the absolute-path mount.
+
+Consequence: OCI-compatible engines (podman, etc.) and bind-mount sandboxes
+(bubblewrap/nsjail-style) fit this seam as-is. SSH-remote, VM, or cloud
+backends — anywhere the agent's filesystem ≠ the host's — would first need a
+filesystem-transport seam that deliberately does not exist yet (no adapter
+needs path translation today, so building it would be indirection).
+
 ## Invariants to preserve
 
 - **Code is never silently stale.** `create` requires a successful

{treebox-0.6.0 → treebox-0.7.0}/CONTRIBUTING.md

@@ -44,6 +44,23 @@ uv run --extra dev ruff format --check src tests
 uv run --extra dev mypy
 ```
 
+For changes that touch provisioning, runners, git handling, or CLI output, run
+the full validation gate: lint, type checks, shell asset checks, tests, the
+golden CLI-output snapshots in `tests/golden/`, and a live host-runner smoke
+test against a throwaway local remote:
+
+```bash
+./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.
+
+```bash
+scripts/golden-diff.sh
+```
+
 For docs-only changes, this is enough:
 
 ```bash

{treebox-0.6.0 → treebox-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treebox
-Version: 0.6.0
+Version: 0.7.0
 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/
@@ -97,9 +97,10 @@ your back. Or install directly:
 uv tool install treebox
 ```
 
-Host isolation needs only `git` and a logged-in agent CLI (`claude` /
-`codex`); docker isolation additionally needs just `docker` — no Node.js, no
-extra CLIs. See the
+Host isolation needs `git` plus the selected agent CLI on PATH and logged in.
+Docker isolation additionally needs `docker`; the default template supplies the
+agent CLI, and treebox copies scoped login files from your `~/.claude` /
+`~/.codex` subscription login. See the
 [install guide](https://seth-peters.github.io/treebox/install/) for
 requirements and installer overrides.
 
@@ -279,7 +280,7 @@ uv run treebox ...                    # run the CLI from the working tree
 uv run --extra dev pre-commit install # lint/format/strict type-check hooks (see CONTRIBUTING.md)
 uv run --extra dev python -m pytest   # unit + integration suite
 uv run --extra dev mypy               # strict type check
-./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
+./scripts/validate.sh                 # full gate: lint + typecheck + shell assets + tests + snapshots + smoke
 ```
 
 ## Contributing

{treebox-0.6.0 → treebox-0.7.0}/README.md

@@ -60,9 +60,10 @@ your back. Or install directly:
 uv tool install treebox
 ```
 
-Host isolation needs only `git` and a logged-in agent CLI (`claude` /
-`codex`); docker isolation additionally needs just `docker` — no Node.js, no
-extra CLIs. See the
+Host isolation needs `git` plus the selected agent CLI on PATH and logged in.
+Docker isolation additionally needs `docker`; the default template supplies the
+agent CLI, and treebox copies scoped login files from your `~/.claude` /
+`~/.codex` subscription login. See the
 [install guide](https://seth-peters.github.io/treebox/install/) for
 requirements and installer overrides.
 
@@ -242,7 +243,7 @@ uv run treebox ...                    # run the CLI from the working tree
 uv run --extra dev pre-commit install # lint/format/strict type-check hooks (see CONTRIBUTING.md)
 uv run --extra dev python -m pytest   # unit + integration suite
 uv run --extra dev mypy               # strict type check
-./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
+./scripts/validate.sh                 # full gate: lint + typecheck + shell assets + tests + snapshots + smoke
 ```
 
 ## Contributing

{treebox-0.6.0 → treebox-0.7.0}/ROADMAP.md

@@ -4,8 +4,8 @@ treebox is intentionally small: isolated git worktrees, cache-backed setup, and
 host or Docker runners for AI coding agents. A few directions we'd like to grow in,
 roughly in priority order:
 
-1. **Support more coding-agent CLIs.** Broaden `HARNESS_COMMANDS` beyond
-   `claude`/`codex` so more agents can launch in a provisioned worktree.
+1. **Support more coding-agent CLIs.** Extend the `harnesses.py` registry
+   beyond `claude`/`codex` so more agents can launch in a provisioned worktree.
 2. **Support more isolation environments.** Add runners beyond host and Docker —
    Podman first, as a rootless, daemonless drop-in.
 3. **Wider support and testing for different git services.** Exercise and harden

{treebox-0.6.0 → treebox-0.7.0}/docs/configuration.md

@@ -38,12 +38,19 @@ uv  = "/mnt/fast/cache/uv"
 npm = "/mnt/fast/cache/npm"
 ```
 
-Precedence is what you'd expect:
+For a new `create`, precedence is what you'd expect:
 
 ```text
 command-line flag  >  config.toml  >  built-in default
 ```
 
+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.
+
 | Key        | Default              | What it controls                                          |
 | ---------- | -------------------- | --------------------------------------------------------- |
 | `isolation`| `host`               | Where agents run: the worktree shell, or a docker sandbox. |
@@ -156,5 +163,6 @@ container config in the target repo itself is deliberately ignored — see
 | `XDG_CACHE_HOME`  | Standard XDG base for the shared package caches treebox mounts. |
 
 Secrets stay in files: treebox copies your repo's `.env` (or the configured
-`env_file`) into each worktree and mounts it into containers. Agents
-authenticate with your subscription login.
+`env_file`) into each worktree and mounts it into containers. Host isolation
+uses your live subscription login; docker isolation mounts scoped copies of the
+login files each harness declares and refreshes them on every entry.

{treebox-0.6.0 → treebox-0.7.0}/docs/how-it-works.md

@@ -4,6 +4,12 @@ treebox is orchestration glue — it shells out to `git` and `docker` rather
 than reimplementing them. The whole tool is organized around one seam:
 **provisioning always happens on the host; running is pluggable.**
 
+Three closed vocabularies sit on top of that seam:
+
+- **Harness** — which agent CLI launches (`claude`, `codex`).
+- **Runner / isolation** — where it executes (`host`, `docker`).
+- **Ecosystem** — what setup runs (uv, npm, pnpm, go, cargo).
+
 ## The provisioning pipeline
 
 Every `create` walks the same host-side pipeline, regardless of isolation mode:
@@ -66,6 +72,14 @@ 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.
 
+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.
+An explicit `--isolation` that disagrees with the recorded mode is a conflict,
+not an override.
+
 ## Warmth lives in the cache, not the tree
 
 treebox detects the package manager from the repo — **uv, npm, pnpm, go, or
@@ -98,8 +112,10 @@ agent's own in-container `git` remains normal, but config it writes into the
 shared git dir cannot make the next host-side treebox call execute
 repo-controlled hooks or monitors.
 
-Your `.env` and shared caches are mounted in; the agent authenticates with
-your existing `~/.claude` / `~/.codex` subscription login.
+Your `.env`, shared caches, and scoped credential copies are mounted in. Host
+isolation uses your live `~/.claude` / `~/.codex` login dirs; docker isolation
+never mounts those live dirs. Instead, each harness declares which login files
+to copy into a per-worktree credentials dir, refreshed on every `enter`.
 
 ## Built to be scripted
 

{treebox-0.6.0 → treebox-0.7.0}/docs/index.md

@@ -41,7 +41,8 @@ Docker sandbox.
 <div class="t-line" style="--d:3.2s;--run:.5s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> worktree   <span class="c-dim">.treebox/worktrees/brave-otter</span></div>
 <div class="t-line" style="--d:3.7s;--run:.3s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> secrets    <span class="c-dim">copied</span></div>
 <div class="t-line" style="--d:4.0s;--run:.4s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> sandbox    <span class="c-dim">templates written (outside worktree)</span></div>
-<div class="t-line" style="--d:4.4s;--run:1.9s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> image      <span class="c-dim">building container image…</span></div>
+<div class="t-line" style="--d:4.4s;--run:.3s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> credentials <span class="c-dim">scoped copies staged</span></div>
+<div class="t-line" style="--d:4.8s;--run:1.5s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> image      <span class="c-dim">building container image…</span></div>
 <div class="t-line" style="--d:6.3s;--run:.5s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> container  <span class="c-dim">started · agent execs via docker exec</span></div>
 <div class="t-line" style="--d:6.9s"> </div>
 <div class="t-line" style="--d:6.9s">  <span class="c-ok">Ready</span> <span class="c-dim">in 22.6s — launching</span> claude</div>
@@ -54,9 +55,10 @@ Docker sandbox.
 <div class="t-line" style="--d:1.9s">    <span class="c-dim">isolation</span>  docker  <span class="c-dim">→</span>  codex</div>
 <div class="t-line" style="--d:2.1s"> </div>
 <div class="t-line" style="--d:2.2s;--run:.3s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> secrets    <span class="c-dim">copied</span></div>
-<div class="t-line" style="--d:2.7s">    <span class="c-dim">· deps       unchanged · skipping setup</span></div>
-<div class="t-line" style="--d:2.9s"> </div>
-<div class="t-line" style="--d:3.0s">  <span class="c-ok">Ready</span> <span class="c-dim">in 1.4s — launching</span> codex</div>
+<div class="t-line" style="--d:2.6s;--run:.3s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> credentials <span class="c-dim">scoped copies refreshed</span></div>
+<div class="t-line" style="--d:3.0s">    <span class="c-dim">· deps       unchanged · skipping setup</span></div>
+<div class="t-line" style="--d:3.2s"> </div>
+<div class="t-line" style="--d:3.3s">  <span class="c-ok">Ready</span> <span class="c-dim">in 1.4s — launching</span> codex</div>
 <div class="t-line" style="--d:4.4s"> </div>
 <div class="t-line" style="--d:4.5s">^C</div>
 </div>
@@ -68,9 +70,10 @@ Docker sandbox.
 <div class="t-line" style="--d:2.0s">    <span class="c-dim">isolation</span>  docker  <span class="c-dim">→</span>  claude</div>
 <div class="t-line" style="--d:2.2s"> </div>
 <div class="t-line" style="--d:2.3s;--run:.3s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> secrets    <span class="c-dim">copied</span></div>
-<div class="t-line" style="--d:2.8s">    <span class="c-dim">· deps       unchanged · skipping setup</span></div>
-<div class="t-line" style="--d:3.0s"> </div>
-<div class="t-line" style="--d:3.1s">  <span class="c-ok">Ready</span> <span class="c-dim">in 1.2s — launching</span> claude</div>
+<div class="t-line" style="--d:2.7s;--run:.3s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> credentials <span class="c-dim">scoped copies refreshed</span></div>
+<div class="t-line" style="--d:3.1s">    <span class="c-dim">· deps       unchanged · skipping setup</span></div>
+<div class="t-line" style="--d:3.3s"> </div>
+<div class="t-line" style="--d:3.4s">  <span class="c-ok">Ready</span> <span class="c-dim">in 1.2s — launching</span> claude</div>
 </div>
 <div class="t-scene" data-dur="4800">
 <div class="t-line" style="--d:0s;--n:10"><span class="c-ok">$ </span><span class="t-type">treebox ls</span></div>

{treebox-0.6.0 → treebox-0.7.0}/docs/install.md

@@ -39,20 +39,25 @@ curl -fsSL https://raw.githubusercontent.com/Seth-Peters/treebox/main/install.sh
 
 ## What each isolation mode needs
 
-| Requirement                                    | `host`        | `docker`        |
-| ---------------------------------------------- | :-----------: | :-------------: |
-| `git`                                          | ✓             | ✓               |
-| Agent CLI (`claude` / `codex`), logged in once | ✓             | ✓               |
-| `docker`                                       | —             | ✓               |
+| Requirement                                      | `host`        | `docker`        |
+| ------------------------------------------------ | :-----------: | :-------------: |
+| `git`                                            | ✓             | ✓               |
+| Subscription login (`~/.claude` / `~/.codex`)    | ✓             | ✓               |
+| Host agent CLI on PATH (`claude` / `codex`)      | ✓             | — (template-provided) |
+| `docker`                                         | —             | ✓               |
 
 That's the whole table: docker isolation speaks plain `docker build` /
-`docker run` / `docker exec`, so there is no Node.js and no extra CLI to
-install. The worktree and its git dir are mounted at their host paths, so
-in-container `git` just works — with no special git version requirement.
-
-Agents launch via your `~/.claude` / `~/.codex` **subscription login**. The
-sandbox template docker isolation provisions is pinned to CPython 3.14.6,
-independent of whatever runs treebox itself.
+`docker run` / `docker exec`, so there is no Node.js and no dev-container CLI
+to install. The default template installs the agent CLIs in the image; the host
+supplies scoped subscription-login copies. The worktree and its git dir are
+mounted at their host paths, so in-container `git` just works — with no special
+git version requirement.
+
+Host isolation launches against your live `~/.claude` / `~/.codex`
+**subscription login**. Docker isolation stages scoped copies of those login
+files and never mounts the live dirs. The sandbox template docker isolation
+provisions is pinned to CPython 3.14.6, independent of whatever runs treebox
+itself.
 
 ## Verify
 
@@ -120,5 +125,5 @@ uv run treebox ...                    # run the CLI from the working tree
 uv run --extra dev pre-commit install # lint/format/strict type-check hooks (see CONTRIBUTING.md)
 uv run --extra dev python -m pytest   # unit + integration suite
 uv run --extra dev mypy               # strict type check
-./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
+./scripts/validate.sh                 # full gate: lint + typecheck + shell assets + tests + snapshots + smoke
 ```

{treebox-0.6.0 → treebox-0.7.0}/docs/usage.md

@@ -138,7 +138,12 @@ harness the worktree was **provisioned with** (`create -H codex` then plain
 per-session override that launches that agent this time without changing what's
 recorded on disk. The sandbox **template** is reused the same way: a worktree
 created with `--template node` re-renders that template on `enter`, not the
-config default, and an explicit `--template` is a per-session override.
+config default, and an explicit `--template` is a per-session override. The
+recorded **isolation** mode also wins over the config default; a conflicting
+explicit `--isolation` exits `5` instead of entering the wrong kind of
+worktree. For docker worktrees, the recorded firewall choice is reused too, so
+`create --no-firewall` keeps entering cleanly even under a `firewall = true`
+config.
 Dependencies re-sync **only if the lockfile changed** since the last setup
 (treebox stores the hash in the worktree's private git dir, so it never shows
 up in `git status`); a re-sync preserves the recorded harness and template

treebox-0.7.0/scripts/golden-diff.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# Golden output snapshots for the CLI's observable surface (issue #141, PR 0).
+#
+# Runs a fixed matrix of commands — doctor, create --print/--dry-run,
+# enter --print, and their --json forms, for both isolations — against a
+# hermetic throwaway repo, normalizes the machine-specific bits (paths,
+# uid/gid, git version, container-name digests), and diffs the result against
+# the committed snapshots in tests/golden/. The refactor PRs under issue #141
+# must leave every snapshot byte-identical: the "output identical" gate is
+# mechanical, not eyeballed.
+#
+#   scripts/golden-diff.sh            # compare against tests/golden/ (CI gate)
+#   scripts/golden-diff.sh --update   # regenerate the snapshots (review the diff!)
+#
+# Docker is replaced by a no-op shim on PATH so the docker-isolation cases are
+# deterministic and run on hosts without a daemon: `docker ps -aq` reports no
+# containers and every other subcommand succeeds silently, which drives the
+# fresh-create path (render config -> stage credentials -> build -> run ->
+# post-create) end to end without a real container.
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+MODE="diff"
+[[ "${1:-}" == "--update" ]] && MODE="update"
+
+GOLDEN_DIR="tests/golden"
+ROOT_PARENT="${TREEBOX_GOLDEN_ROOT:-/tmp}"
+ROOT_PARENT="${ROOT_PARENT%/}"
+[[ -n "$ROOT_PARENT" ]] || { echo "FATAL: TREEBOX_GOLDEN_ROOT must not be /" >&2; exit 1; }
+mkdir -p "$ROOT_PARENT"
+ROOT="$(mktemp -d "$ROOT_PARENT/treebox-golden.XXXXXX")"
+ROOT="$(cd "$ROOT" && pwd -P)"
+WORK="$ROOT/out"
+trap 'rm -rf "$ROOT"' EXIT
+
+TREEBOX="$PWD/.venv/bin/treebox"
+[[ -x "$TREEBOX" ]] || uv sync --quiet
+[[ -x "$TREEBOX" ]] || { echo "FATAL: $TREEBOX not found after uv sync" >&2; exit 1; }
+
+mkdir -p "$WORK" "$ROOT/tbhome" "$ROOT/home-empty"
+
+# --- fake HOME with both subscription logins staged --------------------------
+HOME_FAKE="$ROOT/home"
+mkdir -p "$HOME_FAKE/.claude" "$HOME_FAKE/.codex"
+printf '{"token": "golden"}\n' > "$HOME_FAKE/.claude/.credentials.json"
+printf '{}\n' > "$HOME_FAKE/.claude/settings.json"
+printf '{}\n' > "$HOME_FAKE/.codex/auth.json"
+printf '\n' > "$HOME_FAKE/.codex/config.toml"
+
+# --- docker shim: no containers exist; every subcommand succeeds -------------
+SHIM="$ROOT/shim"
+mkdir -p "$SHIM"
+printf '#!/bin/sh\nexit 0\n' > "$SHIM/docker"
+chmod +x "$SHIM/docker"
+
+# --- hermetic config: setup is a marker-writing hook, never a real installer -
+CFG="$ROOT/config.toml"
+printf 'setup_hook = ["echo ran >> setup.log"]\n' > "$CFG"
+
+# --- fixture repo: a working clone of a local bare origin --------------------
+git_q() { git -c init.defaultBranch=main "$@" >/dev/null; }
+export GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@e GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@e
+git_q init --bare -b main "$ROOT/origin.git"
+git_q clone "$ROOT/origin.git" "$ROOT/repo" 2>/dev/null
+REPO="$ROOT/repo"
+printf '[project]\nname="golden"\nversion="0"\n' > "$REPO/pyproject.toml"
+printf 'version = 1\n' > "$REPO/uv.lock"
+printf 'SECRET=golden\n' > "$REPO/.env"
+git_q -C "$REPO" add -A
+git_q -C "$REPO" commit -qm init
+git_q -C "$REPO" push -q origin main
+WTS="$ROOT/wts"
+
+GITVER="$(git --version | awk '{print $3}')"
+GITVER_PARSED="$(git --version | perl -lane 'my $s = $F[-1]; my @parts = split /\./, $s; my @nums; for my $p (@parts[0..2]) { $p //= ""; $p =~ s/\D//g; push @nums, length($p) ? $p : 0; } push @nums, 0 while @nums < 3; print join ".", @nums[0..2]')"
+export GD_ROOT="$ROOT" GD_PRIVROOT="/private$ROOT" GD_GITVER="$GITVER" GD_GITVER_PARSED="$GITVER_PARSED"
+# Literal (not pattern) uid/gid substitutions, so a regression that changed
+# one number into another is a snapshot diff, not silently normalized away.
+GD_UID="$(id -u)"
+GD_GID="$(id -g)"
+export GD_UID GD_GID
+
+normalize() {
+  perl -pe '
+    s/\Q$ENV{GD_PRIVROOT}\E/__ROOT__/g;
+    s/\Q$ENV{GD_ROOT}\E/__ROOT__/g;
+    s/\Q$ENV{GD_GITVER_PARSED}\E/__GITVER__/g;
+    s/\Q$ENV{GD_GITVER}\E/__GITVER__/g;
+    s/\bUSER_UID=\Q$ENV{GD_UID}\E\b/USER_UID=__UID__/g;
+    s/\bUSER_GID=\Q$ENV{GD_GID}\E\b/USER_GID=__GID__/g;
+    s/\b\Q$ENV{GD_UID}\E:\Q$ENV{GD_GID}\E\b/__UID__:__GID__/g;
+    s/\btreebox-([a-z0-9._-]+)-[0-9a-f]{10}\b/treebox-$1-__HASH__/g;
+  '
+}
+
+FAILED=0
+
+# run_case <name> <home-dir> <treebox args...>
+run_case() {
+  local name="$1" home="$2"
+  shift 2
+  local rc=0
+  set +e
+  env -u TZ -u XDG_CACHE_HOME -u PNPM_HOME -u UV_CACHE_DIR -u npm_config_cache \
+      -u npm_config_store_dir -u GOMODCACHE -u CARGO_HOME -u TREEBOX_TEMPLATE_DIR \
+      -u NO_COLOR -u FORCE_COLOR -u CLICOLOR_FORCE \
+      HOME="$home" TREEBOX_CONFIG="$CFG" TREEBOX_HOME="$ROOT/tbhome" \
+      PATH="$SHIM:$PATH" COLUMNS=80 \
+      "$TREEBOX" "$@" >"$WORK/$name.stdout" 2>"$WORK/$name.stderr"
+  rc=$?
+  set -e
+  {
+    echo "# treebox $*" | normalize
+    echo "# exit: $rc"
+    echo "# --- stdout ---"
+    normalize < "$WORK/$name.stdout"
+    echo "# --- stderr ---"
+    normalize < "$WORK/$name.stderr"
+  } > "$WORK/$name.txt"
+  rm -f "$WORK/$name.stdout" "$WORK/$name.stderr"
+
+  if [[ "$MODE" == "update" ]]; then
+    cp "$WORK/$name.txt" "$GOLDEN_DIR/$name.txt"
+    echo "updated  $name"
+  elif [[ ! -f "$GOLDEN_DIR/$name.txt" ]]; then
+    echo "MISSING snapshot: $GOLDEN_DIR/$name.txt (run with --update on main first)" >&2
+    FAILED=1
+  elif ! diff -u "$GOLDEN_DIR/$name.txt" "$WORK/$name.txt"; then
+    echo "DIFF     $name" >&2
+    FAILED=1
+  else
+    echo "ok       $name"
+  fi
+}
+
+mkdir -p "$GOLDEN_DIR"
+R=(--repo "$REPO")
+RW=(--repo "$REPO" --root "$WTS")
+
+# --- host isolation -----------------------------------------------------------
+run_case doctor-host          "$HOME_FAKE" doctor "${R[@]}"
+run_case doctor-host-json     "$HOME_FAKE" doctor "${R[@]}" --json
+run_case doctor-no-login      "$ROOT/home-empty" doctor "${R[@]}"
+run_case create-dryrun-host       "$HOME_FAKE" create golden-host "${RW[@]}" --dry-run
+run_case create-dryrun-host-json  "$HOME_FAKE" create golden-host "${RW[@]}" --dry-run --json
+run_case create-host-print    "$HOME_FAKE" create golden-host "${RW[@]}" --print
+run_case create-host-json     "$HOME_FAKE" create golden-host-json "${RW[@]}" --json
+run_case enter-host-print     "$HOME_FAKE" enter golden-host "${RW[@]}" --print
+run_case enter-host-json      "$HOME_FAKE" enter golden-host "${RW[@]}" --json
+
+# --- docker isolation (through the shim) ---------------------------------------
+run_case doctor-docker        "$HOME_FAKE" doctor "${R[@]}" --isolation docker
+run_case doctor-docker-json   "$HOME_FAKE" doctor "${R[@]}" --isolation docker --json
+run_case create-dryrun-docker      "$HOME_FAKE" create golden-docker "${RW[@]}" --isolation docker --dry-run
+run_case create-dryrun-docker-json "$HOME_FAKE" create golden-docker "${RW[@]}" --isolation docker --dry-run --json
+run_case create-docker-print  "$HOME_FAKE" create golden-docker "${RW[@]}" --isolation docker --print
+run_case create-docker-json   "$HOME_FAKE" create golden-docker-json "${RW[@]}" --isolation docker --json
+run_case enter-docker-print   "$HOME_FAKE" enter golden-docker "${RW[@]}" --print
+run_case enter-docker-json    "$HOME_FAKE" enter golden-docker "${RW[@]}" --json
+
+if [[ "$MODE" == "diff" && "$FAILED" -ne 0 ]]; then
+  echo >&2
+  echo "golden-diff: OUTPUT CHANGED — the stability contract (issue #141) requires" >&2
+  echo "byte-identical CLI output. If the change is intentional, discuss on the" >&2
+  echo "issue first; only regenerate with --update after that decision." >&2
+  exit 1
+fi
+echo "golden-diff: all snapshots match"