treebox 0.1.0__tar.gz → 0.2.0__tar.gz

treebox-0.2.0/.github/workflows/auto-release.yml

@@ -0,0 +1,155 @@
+name: Auto release
+
+# After CI succeeds on a push to main: read the Conventional Commit subjects
+# since the last `v*` tag, derive the semver bump (`!`/BREAKING CHANGE ->
+# major, feat -> minor, fix/perf -> patch), push the new `vX.Y.Z` tag, publish
+# to PyPI, and create a GitHub Release. Merges with no release-worthy commits
+# (docs, chore, refactor, ...) are a no-op — no tag, no upload. A red CI run
+# never releases: the tag job only fires via workflow_run when CI concluded
+# successfully, and it tags the exact commit CI validated (head_sha), not
+# whatever main points at by then.
+#
+# While the major version is 0, breaking changes bump the minor instead
+# (0.4.x -> 0.5.0), matching cargo/semantic-release conventions.
+#
+# Publishing uses PyPI Trusted Publishing (OIDC) like release.yml — no API
+# tokens. One-time setup on https://pypi.org:
+#   Account -> Publishing -> add a "pending" trusted publisher with:
+#     owner = Seth-Peters, repo = treebox,
+#     workflow = auto-release.yml, environment = pypi
+#
+# The tag is pushed with the workflow's GITHUB_TOKEN, which GitHub
+# deliberately does not let trigger other workflows — so release.yml does NOT
+# fire and nothing publishes twice. release.yml stays as the manual /
+# TestPyPI path.
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches:
+      - main
+
+# Serialize runs so back-to-back merges tag sequentially instead of racing.
+concurrency:
+  group: auto-release
+  cancel-in-progress: false
+
+jobs:
+  tag:
+    name: Compute version bump
+    # Only a green CI run on a push to main releases; the branches filter above
+    # matches head_branch, so the event guard keeps PR runs from a branch that
+    # happens to be named main from slipping through.
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # push the version tag
+    outputs:
+      released: ${{ steps.bump.outputs.released }}
+      tag: ${{ steps.bump.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }} # the commit CI validated
+          fetch-depth: 0 # full history + tags to find the last release and scan commits
+
+      - name: Derive next version from Conventional Commits
+        id: bump
+        run: |
+          last=$(git describe --tags --abbrev=0 --match 'v[0-9]*')
+          echo "last release: $last"
+
+          rank=0 # 0 none · 1 patch · 2 minor · 3 major
+          for sha in $(git rev-list "$last"..HEAD); do
+            subject=$(git log -1 --format=%s "$sha")
+            body=$(git log -1 --format=%b "$sha")
+            if [[ "$subject" =~ ^[a-z]+(\(.+\))?!: ]] || grep -q '^BREAKING CHANGE' <<<"$body"; then
+              rank=3
+            elif [[ "$subject" =~ ^feat(\(.+\))?: ]]; then
+              ((rank < 2)) && rank=2
+            elif [[ "$subject" =~ ^(fix|perf)(\(.+\))?: ]]; then
+              ((rank < 1)) && rank=1
+            fi
+          done
+
+          ver=${last#v}
+          IFS=. read -r maj min pat <<<"$ver"
+          case $rank in
+            3) if ((maj == 0)); then new="0.$((min + 1)).0"; else new="$((maj + 1)).0.0"; fi ;;
+            2) new="$maj.$((min + 1)).0" ;;
+            1) new="$maj.$min.$((pat + 1))" ;;
+            0)
+              echo "no release-worthy commits since $last — skipping release"
+              echo "released=false" >>"$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
+
+          echo "tagging v$new"
+          git tag "v$new"
+          git push origin "v$new"
+          echo "released=true" >>"$GITHUB_OUTPUT"
+          echo "tag=v$new" >>"$GITHUB_OUTPUT"
+
+  build:
+    name: Build distributions
+    needs: tag
+    if: needs.tag.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.tag.outputs.tag }}
+          fetch-depth: 0 # full history + tags so hatch-vcs can derive the version
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Show version being published
+        run: ls -1 dist/
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub Release
+    needs: [tag, publish-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v3
+        with:
+          tag_name: ${{ needs.tag.outputs.tag }}
+          generate_release_notes: true
+          files: dist/*

{treebox-0.1.0 → treebox-0.2.0}/.github/workflows/release.yml

@@ -2,17 +2,14 @@ name: Release
 
 # Build and publish treebox.
 #
-#   * Push a tag like `v0.4.0`        -> clean release version (0.4.0), publish to
-#                                        TestPyPI + PyPI, then create GitHub Release.
-#   * Manually run via "Run workflow" -> build current commit as a dev version and
-#                                        publish to TestPyPI only.
+#   * Push a tag like `v0.4.0`            -> clean release version (0.4.0), publish to PyPI + GitHub Release.
+#   * Manually run via "Run workflow"     -> builds the current commit as a dev version, publishes to TestPyPI.
 #
 # Publishing uses PyPI Trusted Publishing (OIDC) — there are NO API tokens or
-# secrets to manage. One-time setup:
-#   test.pypi.org project -> Publishing -> GitHub publisher:
-#     owner = Seth-Peters, repo = treebox, workflow = release.yml, environment = testpypi
-#   pypi.org project -> Publishing -> GitHub publisher:
+# secrets to manage. One-time setup, once per index:
+#   https://pypi.org      -> Account -> Publishing -> add a "pending" trusted publisher:
 #     owner = Seth-Peters, repo = treebox, workflow = release.yml, environment = pypi
+#   https://test.pypi.org -> same, with environment = testpypi
 
 on:
   push:
@@ -43,11 +40,12 @@ jobs:
           name: dist
           path: dist/
 
-  publish-testpypi:
-    name: Publish to TestPyPI
+  publish-pypi:
+    name: Publish to PyPI
     needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
-    environment: testpypi
+    environment: pypi
     permissions:
       id-token: write # required for trusted publishing (OIDC)
     steps:
@@ -58,15 +56,13 @@ jobs:
 
       - name: Publish
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          repository-url: https://test.pypi.org/legacy/
 
-  publish-pypi:
-    name: Publish to PyPI
+  publish-testpypi:
+    name: Publish dev build to TestPyPI
     needs: build
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
-    environment: pypi
+    environment: testpypi
     permissions:
       id-token: write # required for trusted publishing (OIDC)
     steps:
@@ -77,11 +73,12 @@ jobs:
 
       - name: Publish
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
 
   github-release:
     name: GitHub Release
-    needs: [publish-testpypi, publish-pypi]
-    if: startsWith(github.ref, 'refs/tags/v')
+    needs: publish-pypi
     runs-on: ubuntu-latest
     permissions:
       contents: write

{treebox-0.1.0 → treebox-0.2.0}/.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 .treebox/
+.ai/
 *.log
 tmp/
 

{treebox-0.1.0 → treebox-0.2.0}/CLAUDE.md

@@ -41,20 +41,22 @@ run (pluggable)**.
   record lockfile hash → hand to runner`. Every branch treebox creates is a
   `treebox/<name>` placeholder made un-pushable by a per-worktree pre-push
   hook (`extensions.worktreeConfig` + `core.hooksPath` into the private git
-  dir); `create -b <existing-branch>` is the only path that skips it.
+  dir); `create --checkout <existing-branch>` is the only path that skips it.
 - **`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). `TOOL_COMMANDS` maps `claude`/`codex` to their
+  git just works). `HARNESS_COMMANDS` maps `claude`/`codex` to their
   fully-autonomous launch argv.
 - **`cli.py`** (Typer) is the entry point: `create [NAME] / enter <ref> /
-  list / teardown <ref>... / doctor`. `enter`/`teardown` resolve a ref as
+  list / teardown <ref>... / doctor` (`ls`/`rm` are hidden aliases of
+  list/teardown). `enter`/`teardown` resolve a ref as
   name → live branch → unique substring (`resolve.py`); ambiguity exits 2.
   It enforces **stable exit codes** (`0` ok · `2` usage · `3` not-found · `4`
   auth/fetch · `5` conflict) and **`--json`** output carrying a
-  `schemaVersion` that only gains fields (git-porcelain discipline). Agents
+  `schemaVersion` that only gains fields within a version — a breaking reshape
+  bumps it (git-porcelain discipline). Agents
   branch on these, so don't change their meanings casually.
 - **`ecosystems.py`** detects package managers (uv, npm, pnpm, go, cargo),
   drives their cache-backed setup, and defines which manifest files feed the
@@ -66,7 +68,7 @@ run (pluggable)**.
 - **`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`). `create -b feature/auth` derives the name by
+  with `git branch -m`). `create --checkout feature/auth` derives the name by
   flattening slashes to `--` (`feature--auth`); generated names come from
   `names.py`.
 - **`config.py`** is **user-level TOML only**, never read from the target repo —

{treebox-0.1.0 → treebox-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treebox
-Version: 0.1.0
+Version: 0.2.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/
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.11
+Requires-Dist: questionary<3,>=2
 Requires-Dist: typer<1.0,>=0.12
 Provides-Extra: dev
 Requires-Dist: mypy>=1.14; extra == 'dev'
@@ -69,10 +70,10 @@ on a laptop or over plain SSH.
 
 Built by [Seth Peters](https://github.com/Seth-Peters) as a small, operator-focused layer for AI agent infrastructure: git worktrees, sandbox boundaries, subscription auth, and repeatable developer environments. If that is the kind of problem you are solving, the [docs](https://seth-peters.github.io/treebox/) go deeper on the design tradeoffs.
 
-Provisioning is identical everywhere; a pluggable **runner** decides where the
-agent runs:
+Provisioning is identical everywhere; a pluggable **isolation mode** decides
+where the agent runs:
 
-| Runner           | Isolation | Agent runs in                                         |
+| `--isolation`    | Sandbox   | Agent runs in                                         |
 | ---------------- | --------- | ----------------------------------------------------- |
 | `host` (default) | none      | the worktree shell                                    |
 | `docker`         | sandboxed | a docker container, with your `.env` + caches mounted |
@@ -111,8 +112,8 @@ your back. Or install directly:
 uv tool install git+https://github.com/Seth-Peters/treebox
 ```
 
-The host runner needs only `git` and a logged-in agent CLI (`claude` /
-`codex`); the docker runner additionally needs just `docker` — no Node.js, no
+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
 [install guide](https://seth-peters.github.io/treebox/install/) for
 requirements and installer overrides.
@@ -137,8 +138,8 @@ launches the agent:
 ```bash
 treebox create                          # generated name (brave-otter), host-native
 treebox create fix-auth                 # named up front
-treebox create fix-auth --runner docker # sandboxed
-treebox create -b feature/auth          # exact existing branch (resume, PR review)
+treebox create fix-auth --isolation docker   # sandboxed
+treebox create --checkout feature/auth       # exact existing branch (resume, PR review)
 treebox create auth-fixes --base feature/auth   # stack on any base branch
 ```
 
@@ -161,8 +162,8 @@ unique substring of either. Dependencies re-sync only if the lockfile changed
 since last time:
 
 ```bash
-treebox enter fix-auth --tool claude
-treebox enter fix-auth --tool codex -- --resume   # args after -- go to the agent
+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
@@ -174,15 +175,19 @@ treebox list
 ```
 
 **Tear down.** Remove one or more worktrees — and, when you're done, their
-branches. Refuses to delete uncommitted work unless forced:
+branches. Refuses to delete uncommitted work unless forced. Run it with no
+refs and treebox walks you through an arrow-key picker, each worktree
+annotated with a "will I lose work?" badge (dirty/ahead/merged, plus PR state
+when `gh`/`glab` is present):
 
 ```bash
 treebox teardown fix-auth brave-otter --delete-branch
+treebox teardown                        # pick interactively
 ```
 
 treebox is built to be scripted, including by agents: every command takes
 `--json` (data to stdout, diagnostics to stderr, a schema that only gains
-fields), `--dry-run` prints the exact commands without running them, and exit
+fields within a version), `--dry-run` prints the exact commands without running them, and exit
 codes are stable (`0` ok · `2` usage · `3` not found · `4` auth · `5`
 conflict). Full reference in the
 [usage guide](https://seth-peters.github.io/treebox/usage/).
@@ -212,8 +217,8 @@ Optional, and user-level only (`~/.config/treebox/config.toml`) — treebox
 never reads config from the target repo:
 
 ```toml
-runner = "docker"   # host | docker
-tool   = "claude"   # claude | codex
+isolation = "docker"  # host | docker
+harness = "claude"  # claude | codex
 base   = "main"
 ```
 

{treebox-0.1.0 → treebox-0.2.0}/README.md

@@ -35,10 +35,10 @@ on a laptop or over plain SSH.
 
 Built by [Seth Peters](https://github.com/Seth-Peters) as a small, operator-focused layer for AI agent infrastructure: git worktrees, sandbox boundaries, subscription auth, and repeatable developer environments. If that is the kind of problem you are solving, the [docs](https://seth-peters.github.io/treebox/) go deeper on the design tradeoffs.
 
-Provisioning is identical everywhere; a pluggable **runner** decides where the
-agent runs:
+Provisioning is identical everywhere; a pluggable **isolation mode** decides
+where the agent runs:
 
-| Runner           | Isolation | Agent runs in                                         |
+| `--isolation`    | Sandbox   | Agent runs in                                         |
 | ---------------- | --------- | ----------------------------------------------------- |
 | `host` (default) | none      | the worktree shell                                    |
 | `docker`         | sandboxed | a docker container, with your `.env` + caches mounted |
@@ -77,8 +77,8 @@ your back. Or install directly:
 uv tool install git+https://github.com/Seth-Peters/treebox
 ```
 
-The host runner needs only `git` and a logged-in agent CLI (`claude` /
-`codex`); the docker runner additionally needs just `docker` — no Node.js, no
+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
 [install guide](https://seth-peters.github.io/treebox/install/) for
 requirements and installer overrides.
@@ -103,8 +103,8 @@ launches the agent:
 ```bash
 treebox create                          # generated name (brave-otter), host-native
 treebox create fix-auth                 # named up front
-treebox create fix-auth --runner docker # sandboxed
-treebox create -b feature/auth          # exact existing branch (resume, PR review)
+treebox create fix-auth --isolation docker   # sandboxed
+treebox create --checkout feature/auth       # exact existing branch (resume, PR review)
 treebox create auth-fixes --base feature/auth   # stack on any base branch
 ```
 
@@ -127,8 +127,8 @@ unique substring of either. Dependencies re-sync only if the lockfile changed
 since last time:
 
 ```bash
-treebox enter fix-auth --tool claude
-treebox enter fix-auth --tool codex -- --resume   # args after -- go to the agent
+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
@@ -140,15 +140,19 @@ treebox list
 ```
 
 **Tear down.** Remove one or more worktrees — and, when you're done, their
-branches. Refuses to delete uncommitted work unless forced:
+branches. Refuses to delete uncommitted work unless forced. Run it with no
+refs and treebox walks you through an arrow-key picker, each worktree
+annotated with a "will I lose work?" badge (dirty/ahead/merged, plus PR state
+when `gh`/`glab` is present):
 
 ```bash
 treebox teardown fix-auth brave-otter --delete-branch
+treebox teardown                        # pick interactively
 ```
 
 treebox is built to be scripted, including by agents: every command takes
 `--json` (data to stdout, diagnostics to stderr, a schema that only gains
-fields), `--dry-run` prints the exact commands without running them, and exit
+fields within a version), `--dry-run` prints the exact commands without running them, and exit
 codes are stable (`0` ok · `2` usage · `3` not found · `4` auth · `5`
 conflict). Full reference in the
 [usage guide](https://seth-peters.github.io/treebox/usage/).
@@ -178,8 +182,8 @@ Optional, and user-level only (`~/.config/treebox/config.toml`) — treebox
 never reads config from the target repo:
 
 ```toml
-runner = "docker"   # host | docker
-tool   = "claude"   # claude | codex
+isolation = "docker"  # host | docker
+harness = "claude"  # claude | codex
 base   = "main"
 ```
 

{treebox-0.1.0 → treebox-0.2.0}/docs/agents.md

@@ -54,7 +54,7 @@ whichever agent you launch:
 
     ---
 
-    `~/.config/treebox/config.toml` picks the runner, tool, base, caches, and
+    `~/.config/treebox/config.toml` picks the isolation mode, harness, base, caches, and
     sandbox template. It's the single source of truth, and it's never read
     from the target repo.
 
@@ -62,7 +62,7 @@ whichever agent you launch:
 
     ---
 
-    `treebox enter feature/auth --tool claude` and `--tool codex` launch into
+    `treebox enter feature/auth --harness claude` and `--harness codex` launch into
     the *same* provisioned, isolated tree. The isolation doesn't change when
     the agent does.
 
@@ -75,7 +75,7 @@ are added. You learn treebox once — not each agent's cage.
 !!! note "treebox complements these systems, it doesn't replace them"
     An agent's own permission rules still apply inside the box. treebox's job
     is the layer they all leave to you: a consistent isolated worktree and,
-    with the `docker` runner, a consistent sandbox — defined by *your*
+    with `docker` isolation, a consistent sandbox — defined by *your*
     template, [rendered outside the box](how-it-works.md#the-sandbox-config-lives-outside-the-box)
     so the agent can't edit its own cage.
 

{treebox-0.1.0 → treebox-0.2.0}/docs/configuration.md

@@ -10,12 +10,12 @@ Lives at `$TREEBOX_CONFIG` if set, else `$XDG_CONFIG_HOME/treebox/config.toml`
 (defaulting to `~/.config/treebox/config.toml`). All keys optional:
 
 ```toml
-runner   = "host"      # host | docker
-tool     = "claude"    # claude | codex
+isolation = "host"     # host | docker
+harness  = "claude"    # claude | codex
 base     = "main"      # default base branch
 root     = ".treebox/worktrees"
 env_file = ".env"      # canonical secrets path, copied into each worktree
-firewall = false       # container firewall (docker runner)
+firewall = false       # container firewall (docker isolation)
 template = "default"   # sandbox template name
 
 # Replace auto-detected dependency setup with your own shell commands,
@@ -24,7 +24,7 @@ setup_hook = ["uv sync --frozen", "uv run python -m scripts.seed"]
 
 # Override where shared package caches live, per ecosystem
 # (uv, npm, pnpm, go, cargo). Defaults honor the standard env vars
-# (UV_CACHE_DIR, GOMODCACHE, …); the docker runner bind-mounts
+# (UV_CACHE_DIR, GOMODCACHE, …); docker isolation bind-mounts
 # these into the container.
 [caches]
 uv  = "/mnt/fast/cache/uv"
@@ -39,12 +39,12 @@ command-line flag  >  config.toml  >  built-in default
 
 | Key        | Default              | What it controls                                          |
 | ---------- | -------------------- | --------------------------------------------------------- |
-| `runner`   | `host`               | Where agents run: the worktree shell, or a docker sandbox. |
-| `tool`     | `claude`             | Which agent `create`/`enter` launch by default.           |
+| `isolation`| `host`               | Where agents run: the worktree shell, or a docker sandbox. |
+| `harness`  | `claude`             | Which agent `create`/`enter` launch by default.           |
 | `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.          |
-| `firewall` | `false`              | Restrict container egress (docker runner).                |
+| `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. |
 | `caches`   | *(standard env vars)* | Per-ecosystem shared cache locations treebox installs from and mounts. |

{treebox-0.1.0 → treebox-0.2.0}/docs/how-it-works.md

@@ -6,7 +6,7 @@ than reimplementing them. The whole tool is organized around one seam:
 
 ## The provisioning pipeline
 
-Every `create` walks the same host-side pipeline, regardless of runner:
+Every `create` walks the same host-side pipeline, regardless of isolation mode:
 
 ```text
 fetch origin                 # required — a failure exits 4, loudly
@@ -20,14 +20,15 @@ fetch origin                 # required — a failure exits 4, loudly
                                      └─ hand off to the runner
 ```
 
-The runner only decides **where** the last two steps happen:
+The runner — picked with `--isolation` — only decides **where** the last two
+steps happen:
 
-| Runner   | `setup` runs…                   | Agent runs…                             |
+| `--isolation` | `setup` runs…              | Agent runs…                             |
 | -------- | ------------------------------- | --------------------------------------- |
 | `host`   | in the worktree shell           | in the worktree shell                   |
 | `docker` | inside the container, on create | via `docker exec`, inside the sandbox   |
 
-The docker runner builds and starts the sandbox with plain `docker build` /
+Docker isolation builds and starts the sandbox with plain `docker build` /
 `docker run`. The worktree and the repo's git dir are bind-mounted at their
 host paths — mirrored 1:1 — so in-container `git` resolves the worktree's
 pointers exactly as the host does, with no extra tooling.
@@ -35,7 +36,7 @@ pointers exactly as the host does, with no extra tooling.
 ## Names are identity; branches are mutable
 
 The worktree **name** (the directory leaf) is the permanent identity: the
-docker runner bind-mounts the absolute path and a live agent's CWD sits in
+docker sandbox bind-mounts the absolute path and a live agent's CWD sits in
 it, so the directory is never renamed. The **branch** is just an attribute —
 created as a `treebox/<name>` placeholder and expected to be renamed
 (`git branch -m`) once the work has a shape. `list`, `enter`, and `teardown`
@@ -75,7 +76,7 @@ re-download. `--cold` bypasses the caches when you want a from-source build.
 
 ## The sandbox config lives outside the box
 
-The docker runner's threat model is simple: **an agent must not be able to
+Docker isolation's threat model is simple: **an agent must not be able to
 edit the config that defines its own sandbox.**
 
 - The container template (Dockerfile, `container.json`, firewall setup) is
@@ -100,7 +101,7 @@ treebox assumes the caller is often another program:
   automatically when stderr isn't a TTY.
 - **Stable exit codes** — `0` ok · `2` usage · `3` not-found · `4` auth ·
   `5` conflict — so callers can branch without parsing prose.
-- **`--json` with a `schemaVersion`** that only ever gains fields
+- **`--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.
 - **Per-worktree locking**, so two concurrent `create fix-auth` calls

{treebox-0.1.0 → treebox-0.2.0}/docs/index.md

@@ -34,7 +34,7 @@ sandbox.
 <div class="t-line" style="--d:1.8s"> </div>
 <div class="t-line" style="--d:1.8s">    <span class="c-dim">branch</span>     treebox/brave-otter  <span class="c-dim">·  placeholder — rename before push</span></div>
 <div class="t-line" style="--d:1.9s">    <span class="c-dim">base</span>       main</div>
-<div class="t-line" style="--d:2.0s">    <span class="c-dim">runner</span>     host  <span class="c-dim">→</span>  claude</div>
+<div class="t-line" style="--d:2.0s">    <span class="c-dim">isolation</span>     host  <span class="c-dim">→</span>  claude</div>
 <div class="t-line" style="--d:2.2s"> </div>
 <div class="t-line" style="--d:2.2s;--run:.8s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> fetch      <span class="c-dim">origin up to date</span></div>
 <div class="t-line" style="--d:3.0s;--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>
@@ -86,23 +86,23 @@ collisions — on a laptop or over plain SSH.
 
 </div>
 
-## Two runners, one pipeline
+## Two isolation modes, one pipeline
 
-Provisioning is identical either way; a pluggable **runner** decides where the
-agent runs:
+Provisioning is identical either way; a pluggable **isolation mode** decides
+where the agent runs:
 
-| Runner           | Isolation | Agent runs in                                         |
+| `--isolation`    | Sandbox   | Agent runs in                                         |
 | ---------------- | --------- | ----------------------------------------------------- |
 | `host` (default) | none      | the worktree shell                                    |
 | `docker`         | sandboxed | a docker container, with your `.env` + caches mounted |
 
 ```bash
 treebox create fix-auth                    # placeholder branch off fresh origin/main
-treebox create fix-auth --runner docker    # same provisioning, sandboxed
+treebox create fix-auth --isolation docker   # same provisioning, sandboxed
 ```
 
-The docker runner needs exactly one extra thing: Docker — see
-[what the runners need](install.md#what-the-runners-need).
+Docker isolation needs exactly one extra thing: Docker — see
+[what each isolation mode needs](install.md#what-each-isolation-mode-needs).
 
 ## What it is — and isn't
 
@@ -127,7 +127,7 @@ The docker runner needs exactly one extra thing: Docker — see
 - :material-close:{ .tx-no } Manage API keys — it never uses `ANTHROPIC_API_KEY`
 - :material-close:{ .tx-no } Review, merge, or push your branches
 - :material-close:{ .tx-no } Trust the target repo's config — its container config and hooks are ignored
-- :material-close:{ .tx-no } Isolate anything on the `host` runner — that's what `docker` is for
+- :material-close:{ .tx-no } Isolate anything in `host` isolation — that's what `docker` is for
 - :material-close:{ .tx-no } Replace CI, or orchestrate fleets of agents
 - :material-close:{ .tx-no } Install a package manager behind your back
 
@@ -139,7 +139,7 @@ The docker runner needs exactly one extra thing: Docker — see
 ```bash
 treebox doctor                       # verify the host is ready
 treebox create                       # provision + launch claude (name generated)
-treebox enter brave-otter --tool codex   # re-enter later, pick agent per entry
+treebox enter brave-otter --harness codex   # re-enter later, pick agent per entry
 treebox list                         # what exists, what's stale
 treebox teardown brave-otter --delete-branch
 ```