From 1d699c5c1dd84ced13b626b5afe56ea0f446e95b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 29 Jul 2026 17:40:19 +0000
Subject: [PATCH 1/6] chore: sync package-lock.json with MIT license field

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfjQjysq5JF7gQCJB3RQtP
---
 package-lock.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package-lock.json b/package-lock.json
index ac1c946..207383d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,6 +7,7 @@
     "": {
       "name": "agentbox",
       "version": "0.1.0",
+      "license": "MIT",
       "bin": {
         "agentbox": "bin/agentbox.mjs"
       },

From 409cec0206e7d3fb882ac178d1f11cf37a7abb0f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 29 Jul 2026 17:43:18 +0000
Subject: [PATCH 2/6] =?UTF-8?q?chore:=20release=20readiness=20=E2=80=94=20?=
 =?UTF-8?q?scoped=20npm=20name,=20community=20files,=20CI=20matrix=20+=20p?=
 =?UTF-8?q?ack=20smoke=20test?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename package to @liohtml/agentbox (bare 'agentbox' on npm is a security
  placeholder and cannot be claimed); bin command stays 'agentbox'.
- Move tsx to dependencies so the published package runs via npx/global
  install without dev setup; add prepublishOnly guard + publishConfig
  (public access, provenance).
- CI: Node 22+24 matrix, npm pack smoke test that installs the tarball and
  runs the CLI as an end user; narrow push triggers to main.
- Add tag-triggered release workflow (npm publish --provenance).
- Add SECURITY.md (threat model + private reporting), CODE_OF_CONDUCT.md,
  PR template, issue-template config, dependabot config, CHANGELOG.md.
- Replace one-time PUBLISH.md (contained personal email) with generic
  RELEASING.md; README: badges + corrected npx instructions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfjQjysq5JF7gQCJB3RQtP
---
 .github/ISSUE_TEMPLATE/config.yml |   5 ++
 .github/PULL_REQUEST_TEMPLATE.md  |  26 ++++++++
 .github/dependabot.yml            |  13 ++++
 .github/workflows/ci.yml          |  39 ++++++++++--
 .github/workflows/release.yml     |  41 ++++++++++++
 CHANGELOG.md                      |  35 +++++++++++
 CODE_OF_CONDUCT.md                |  38 +++++++++++
 PUBLISH.md                        | 101 ------------------------------
 README.md                         |  11 +++-
 RELEASING.md                      |  36 +++++++++++
 SECURITY.md                       |  33 ++++++++++
 package-lock.json                 |  37 ++---------
 package.json                      |  13 +++-
 13 files changed, 287 insertions(+), 141 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/dependabot.yml
 create mode 100644 .github/workflows/release.yml
 create mode 100644 CHANGELOG.md
 create mode 100644 CODE_OF_CONDUCT.md
 delete mode 100644 PUBLISH.md
 create mode 100644 RELEASING.md
 create mode 100644 SECURITY.md

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..eef0376
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/Liohtml/agentbox/security/advisories/new
+    about: Please report security issues privately via GitHub Security Advisories.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..1a13725
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,26 @@
+# What & why
+
+<!-- What does this PR change, and why? -->
+
+## Scope
+
+<!-- Which module does this touch? Keep PRs scoped to one module/concern
+     where possible (see CONTRIBUTING.md → Module ownership). -->
+
+- [ ] `src/cli/` — arg parsing, help, config, command router
+- [ ] `src/docker/` — image build, container run/exec, mounts
+- [ ] `src/session/` — tmux entry script, TTY sizing
+- [ ] `assets/` — Dockerfile / Observer
+- [ ] `src/types.ts` / `CONTRACT.md` — contract change (explain below!)
+- [ ] Docs / CI / meta
+
+## Checklist
+
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes
+- [ ] No build step, no new runtime dependencies (see CONTRIBUTING.md)
+- [ ] Contract friction with `CONTRACT.md` / `src/types.ts` is described below (or n/a)
+
+## Notes
+
+<!-- What works, what's stubbed, any contract friction. -->
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..be9972b
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      dev-dependencies:
+        dependency-type: development
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6cbd1bb..cb52dd2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: ["**"]
+    branches: [main]
   pull_request:
 
 permissions:
@@ -14,16 +14,20 @@ concurrency:
 
 jobs:
   build:
-    name: typecheck & test (Node 22)
+    name: typecheck & test (Node ${{ matrix.node }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [22, 24]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup Node 22
+      - name: Setup Node ${{ matrix.node }}
         uses: actions/setup-node@v4
         with:
-          node-version: "22"
+          node-version: ${{ matrix.node }}
           cache: npm
 
       - name: Install dependencies
@@ -34,3 +38,30 @@ jobs:
 
       - name: Test
         run: npm test
+
+  pack-smoke:
+    name: npm pack smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Pack tarball
+        run: npm pack --pack-destination "$RUNNER_TEMP"
+
+      - name: Install tarball into a fresh project and run the CLI
+        run: |
+          mkdir -p "$RUNNER_TEMP/consumer"
+          cd "$RUNNER_TEMP/consumer"
+          npm init -y >/dev/null
+          npm install "$RUNNER_TEMP"/liohtml-agentbox-*.tgz
+          # The installed bin must run without any repo-local dev setup.
+          npx agentbox --help
+          npx agentbox doctor || true  # doctor exits non-zero without Docker; it must still *run*
+          npx agentbox doctor 2>&1 | grep -q "agentbox doctor"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..088af25
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: typecheck & test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
+
+  publish:
+    name: npm publish (provenance)
+    needs: checks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..10fd242
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Changed
+- Package renamed to the scoped **`@liohtml/agentbox`** for npm publishing
+  (the bare name `agentbox` is an npm security placeholder). The installed
+  command is still `agentbox`.
+- `tsx` moved from devDependencies to dependencies so the published package
+  runs via `npx`/global install without extra setup.
+- CI: Node 22 + 24 matrix, plus an `npm pack` smoke test that installs the
+  tarball and runs the CLI as an end user would.
+
+### Added
+- `SECURITY.md`, `CODE_OF_CONDUCT.md`, PR template, issue-template config,
+  Dependabot config, `RELEASING.md`, this changelog.
+- Tag-triggered release workflow with npm provenance.
+
+### Removed
+- `PUBLISH.md` (one-time bootstrap doc) — replaced by `RELEASING.md`.
+
+## [0.1.0] — 2026-07-29
+
+### Added
+- Initial release: `agentbox up | shell | rebuild | doctor | down`.
+- Docker image (Ubuntu 24.04 + Node 22 + Python 3 + Rust + Claude Code + tsx),
+  non-root `agent` user, no baked-in credentials.
+- Host bind mounts for workspace + Claude auth reuse (`~/.claude`,
+  `~/.claude.json`).
+- tmux session with Claude lead (Agent Teams) + Observer dashboard window.
+- Zero-dependency Observer web server on `127.0.0.1:4317`.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..2ed53ca
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,38 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Our pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, caste, color, religion, or
+sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+
+Examples of unacceptable behavior:
+
+- Sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers via a GitHub issue (for non-sensitive matters) or
+privately via [GitHub Security Advisories](https://github.com/Liohtml/agentbox/security/advisories/new).
+All complaints will be reviewed and investigated promptly and fairly.
+
+For the full text including enforcement guidelines, see the
+[Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
diff --git a/PUBLISH.md b/PUBLISH.md
deleted file mode 100644
index 6d7ef2a..0000000
--- a/PUBLISH.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Publishing `agentbox` to GitHub
-
-Step-by-step to publish this directory as the **public** repo
-`Liohtml/agentbox`. Run everything from the repo root:
-
-```bash
-cd ~/sandbox/workspace/agentbox
-```
-
-Requirements: `git`, and the GitHub CLI `gh` (v2.87+) authenticated as
-`Liohtml` (`gh auth status` should show ✓ Logged in). All these tools are
-already present and authenticated on this machine.
-
----
-
-## 0. Prerequisite: git identity (only if unset)
-
-The publish creates a commit, so git needs a name and email. Check, and set if
-blank:
-
-```bash
-git config user.name   # if empty, set it:
-git config user.email  # if empty, set it:
-
-git config user.name  "Lio"
-git config user.email "lionel.machire@googlemail.com"
-```
-
-(Use `--global` instead of bare flags if you want it applied for all repos.)
-
----
-
-## 1. Publish (primary path)
-
-### 1a. If this is NOT yet a git repo
-
-```bash
-git init -b main
-git add -A
-git commit -m "Initial commit: agentbox CLI"
-```
-
-### 1b. If it IS already a git repo
-
-This directory is already initialized (branch `master`, with an initial
-commit). Just rename the branch to `main` and capture any uncommitted work:
-
-```bash
-git branch -M main
-git add -A
-git commit -m "Add project metadata: license, CI, contributing, gitignore" || echo "nothing to commit"
-```
-
-### 1c. Create the remote repo and push (one command)
-
-```bash
-gh repo create Liohtml/agentbox \
-  --public \
-  --source=. \
-  --remote=origin \
-  --description "One-command, Docker-isolated agentic coding sandbox: tmux + Claude Code (Agent Teams) + web Observer." \
-  --push
-```
-
-This creates `github.com/Liohtml/agentbox`, wires it up as the `origin`
-remote, and pushes the current branch in a single step.
-
----
-
-## 2. Fallback (if `gh repo create --push` fails partway)
-
-Create the empty repo, then add the remote and push manually:
-
-```bash
-# Create the empty public repo (no push):
-gh repo create Liohtml/agentbox \
-  --public \
-  --description "One-command, Docker-isolated agentic coding sandbox: tmux + Claude Code (Agent Teams) + web Observer."
-
-# Wire up origin (only if it isn't already set):
-git remote add origin https://github.com/Liohtml/agentbox.git
-# If origin already exists, update it instead:
-#   git remote set-url origin https://github.com/Liohtml/agentbox.git
-
-# Push and set upstream:
-git push -u origin main
-```
-
----
-
-## 3. Verify
-
-```bash
-git remote -v                 # origin → github.com/Liohtml/agentbox
-git log --oneline -1          # the commit you just pushed
-gh repo view Liohtml/agentbox # repo summary in the terminal
-gh repo view --web            # open the repo in a browser
-```
-
-You should see the public repo at <https://github.com/Liohtml/agentbox> with
-`node_modules/` excluded (via `.gitignore`) and `package-lock.json` tracked.
diff --git a/README.md b/README.md
index fc80395..42bf2a8 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 # agentbox
 
+[![CI](https://github.com/Liohtml/agentbox/actions/workflows/ci.yml/badge.svg)](https://github.com/Liohtml/agentbox/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node >= 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
+
 > One command spins up a Docker-isolated agentic coding sandbox — tmux + Claude Code (Agent Teams) + a live web Observer.
 
 `agentbox up` boots a disposable Ubuntu container preloaded with Node 22, Python 3, Rust, and Claude Code, bind-mounts your project **and your host Claude login** into it, and drops you into a tmux session: the Claude **lead** runs on the left, its **teammates** spawn on the right, and a live **Observer** dashboard runs in its own window — reachable from your host browser at <http://localhost:4317>.
@@ -60,9 +64,14 @@ agentbox            # 'up' is the default command — runs in the current dir
 You can also invoke it without linking via `npx`:
 
 ```bash
-npx agentbox up          # from within the cloned repo
+npx . up                 # from within the cloned repo
 ```
 
+> Note: the package name on npm is **`@liohtml/agentbox`** (the bare name
+> `agentbox` on the registry is an unrelated npm security placeholder — don't
+> `npx agentbox` outside the cloned repo). Once published, use
+> `npx @liohtml/agentbox up`; the installed command is still `agentbox`.
+
 ---
 
 ## Commands
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 0000000..f1d6f5e
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,36 @@
+# Releasing
+
+How to cut a release of `@liohtml/agentbox`. npm publishing is intended to be
+done from CI via the tag-triggered release workflow — not from a laptop.
+
+## Checklist
+
+1. **Ensure `main` is green.** CI (typecheck, tests, pack smoke test) must pass.
+2. **Bump the version** in `package.json` (semver) and update the lockfile:
+
+   ```bash
+   npm version <patch|minor|major> --no-git-tag-version
+   ```
+
+3. **Update `CHANGELOG.md`:** move entries from *Unreleased* into a new
+   `## [x.y.z] — YYYY-MM-DD` section.
+4. **Commit and push** the version bump + changelog on `main` (via PR).
+5. **Tag and push the tag:**
+
+   ```bash
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+6. The `release.yml` workflow runs on the `v*` tag: it re-runs all checks and
+   publishes to npm with `--provenance --access public`.
+7. **Create a GitHub Release** from the tag, pasting the changelog section.
+
+## npm notes
+
+- The package is published **scoped** as `@liohtml/agentbox` (the bare name
+  `agentbox` is an npm security placeholder and cannot be claimed). The
+  installed command is still `agentbox`.
+- Publishing requires the `NPM_TOKEN` repository secret (or npm Trusted
+  Publishing configured for this repo), plus `id-token: write` for provenance.
+- `prepublishOnly` re-runs typecheck + tests as a local safety net.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..147ab62
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest release (and `main`) receive security fixes.
+
+## Reporting a vulnerability
+
+Please report vulnerabilities **privately** via
+[GitHub Security Advisories](https://github.com/Liohtml/agentbox/security/advisories/new)
+— do not open a public issue for security-sensitive reports. You should
+receive a response within a few days.
+
+## Threat model — read before reporting
+
+agentbox is a **workbench, not a jail**. By design:
+
+- Your host `~/.claude` directory and `~/.claude.json` are bind-mounted
+  **read-write** into the container. They contain your OAuth token, the list
+  of project paths you've opened, and full session transcripts. Anything
+  running inside the box can read or modify them. Only run workloads you
+  trust.
+- The container isolates *resources* (CPU/memory caps, `--rm`, non-root
+  `agent` user) — it is **not** a security boundary against malicious code.
+- The Observer dashboard is unauthenticated by design; its port is published
+  to `127.0.0.1` **only** and must never be exposed to the LAN.
+
+Reports that reduce to "code inside the container can access the mounted
+credentials" describe documented, intended behavior. Reports we absolutely
+want: anything that breaks the documented guarantees above — e.g. the
+Observer becoming reachable from non-loopback interfaces, container escape
+paths agentbox introduces, injection via agentbox's own CLI/entry-script
+generation, or credential exposure *beyond* the documented mounts.
diff --git a/package-lock.json b/package-lock.json
index 207383d..65f6e4f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,19 +1,21 @@
 {
-  "name": "agentbox",
+  "name": "@liohtml/agentbox",
   "version": "0.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "agentbox",
+      "name": "@liohtml/agentbox",
       "version": "0.1.0",
       "license": "MIT",
+      "dependencies": {
+        "tsx": "^4.19.0"
+      },
       "bin": {
         "agentbox": "bin/agentbox.mjs"
       },
       "devDependencies": {
         "@types/node": "^22.0.0",
-        "tsx": "^4.19.0",
         "typescript": "^5.6.0"
       },
       "engines": {
@@ -27,7 +29,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -44,7 +45,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -61,7 +61,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -78,7 +77,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -95,7 +93,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -112,7 +109,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -129,7 +125,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -146,7 +141,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -163,7 +157,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -180,7 +173,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -197,7 +189,6 @@
       "cpu": [
         "ia32"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -214,7 +205,6 @@
       "cpu": [
         "loong64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -231,7 +221,6 @@
       "cpu": [
         "mips64el"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -248,7 +237,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -265,7 +253,6 @@
       "cpu": [
         "riscv64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -282,7 +269,6 @@
       "cpu": [
         "s390x"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -299,7 +285,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -316,7 +301,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -333,7 +317,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -350,7 +333,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -367,7 +349,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -384,7 +365,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -401,7 +381,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -418,7 +397,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -435,7 +413,6 @@
       "cpu": [
         "ia32"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -452,7 +429,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -476,7 +452,6 @@
       "version": "0.28.0",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
       "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
-      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "bin": {
@@ -518,7 +493,6 @@
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
       "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
-      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
@@ -533,7 +507,6 @@
       "version": "4.22.4",
       "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.22.4.tgz",
       "integrity": "sha512-X8EX+XV4QR5xCsrgxaED954zTDfY8KqlDtskKEL0cHhyS/P8b4IFOvGDQpsC9Q1XnLq915wEfwwY/zzskCtmhg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "esbuild": "~0.28.0"
diff --git a/package.json b/package.json
index 222953a..1e00673 100644
--- a/package.json
+++ b/package.json
@@ -1,8 +1,12 @@
 {
-  "name": "agentbox",
+  "name": "@liohtml/agentbox",
   "version": "0.1.0",
   "description": "One-command, Docker-isolated agentic coding sandbox: tmux + Claude Code (Agent Teams) + web Observer.",
   "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "bin": {
     "agentbox": "bin/agentbox.mjs"
   },
@@ -16,7 +20,8 @@
     "agentbox": "tsx src/index.ts",
     "doctor": "tsx src/index.ts doctor",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test tests/*.test.ts"
+    "test": "node --import tsx --test tests/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test"
   },
   "engines": {
     "node": ">=22"
@@ -43,8 +48,10 @@
   },
   "author": "Liohtml",
   "license": "MIT",
+  "dependencies": {
+    "tsx": "^4.19.0"
+  },
   "devDependencies": {
-    "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "@types/node": "^22.0.0"
   }

From 9738e8be84b2b2fe67e759acd71af30b93458963 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 29 Jul 2026 17:57:23 +0000
Subject: [PATCH 3/6] fix: sandbox lifecycle, teammate panes, input validation,
 observer + launcher hardening
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Consolidated fixes from a code audit + upstream research:

- Run the container detached with the entry script as PID 1 and attach via
  'docker exec tmux attach'. Previously the tmux attach client was PID 1, so
  Ctrl+b d (detach) killed the lead, all teammates and the Observer, and
  --rm deleted the container — the opposite of the documented behavior.
- Launch the lead with --teammate-mode tmux: since Claude Code v2.1.179 the
  default teammateMode is 'in-process', which silently disabled the
  split-pane team layout agentbox is built around.
- Fail fast with clear errors on invalid --port/--memory/--cpus, unknown
  flags, stray positionals, ':' in mount paths, and a nonexistent explicitly
  requested workspace (no more silently created empty mounts).
- rebuild refuses while the box is running (used to rebuild then silently
  reattach to the old container); reattach warns when tuning flags are
  ignored; stale stopped containers are removed before docker run.
- down surfaces real 'docker rm -f' failures instead of claiming success.
- ensureHostMounts: clear error when ~/.claude.json is a directory; follow
  symlinked configs (dotfile managers); benign EEXIST race handling.
- Entry script moves to a per-user 0700 temp subdir (was a fixed
  world-shared /tmp path: tamper/TOCTOU + collision); never write through a
  pre-existing symlink.
- Observer: HTML-escape project/session names (stored XSS), handle
  EADDRINUSE with a readable message, remain-on-exit for the observer tmux
  window, port sanity fallback, drop dead tail() code.
- Launcher: invoke local tsx via node directly (no shell) — survives paths
  with spaces, removes cmd.exe metacharacter injection on Windows.
- doctor: warn on host uid != 1000 (bind-mount write failures).
- Dockerfile: CLAUDE_CODE_VERSION/TSX_VERSION build args for reproducible
  builds.
- Contract & README updated; tests: 45 → 65 (new cli router suite, config
  validation, observer + session assertions).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfjQjysq5JF7gQCJB3RQtP
---
 CHANGELOG.md           |  36 ++++++++++
 CONTRACT.md            |  14 +++-
 README.md              |   8 ++-
 ROADMAP.md             |  73 +++++++++++++++++++
 SECURITY.md            |   7 +-
 assets/Dockerfile      |   7 +-
 assets/observer.mjs    |  32 +++++----
 bin/agentbox.mjs       |  33 ++++-----
 src/cli/config.ts      |  57 ++++++++++++++-
 src/cli/index.ts       | 156 ++++++++++++++++++++++++++++++++++++++---
 src/docker/index.ts    |  72 +++++++++++++++----
 src/session/index.ts   |  83 +++++++++++++++-------
 src/types.ts           |  26 ++++---
 tests/cli.test.ts      |  79 +++++++++++++++++++++
 tests/config.test.ts   |  51 +++++++++++++-
 tests/observer.test.ts |  18 +++++
 tests/session.test.ts  |  22 +++++-
 17 files changed, 673 insertions(+), 101 deletions(-)
 create mode 100644 ROADMAP.md
 create mode 100644 tests/cli.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 10fd242..f97e1b9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,7 +6,43 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Fixed
+- **Detaching no longer destroys the sandbox.** The container now runs
+  detached with the entry script as PID 1 and your terminal attaches via
+  `docker exec`, so `Ctrl+b d` behaves as documented (box keeps running).
+  Previously the tmux attach client was PID 1: detach killed every agent and
+  `--rm` deleted the container.
+- **Teammates appear as tmux panes again.** The lead is launched with
+  `--teammate-mode tmux`; since Claude Code v2.1.179 the upstream default is
+  `in-process`, which silently disabled agentbox's split-pane layout.
+- Observer: project/session names are HTML-escaped before rendering
+  (stored-XSS guard), the server handles bind errors (`EADDRINUSE`) with a
+  readable message, the observer tmux window keeps crash output visible
+  (`remain-on-exit`), and dead code was removed.
+- CLI: invalid `--port`/`--memory`/`--cpus` values, unknown flags, stray
+  positionals, and `:` in mount paths fail fast with clear errors instead of
+  surfacing as cryptic Docker failures after a minutes-long build; a
+  `--workspace` typo no longer silently creates and mounts an empty
+  directory.
+- `rebuild` refuses to run while the box is up (it used to rebuild the image
+  and then silently reattach to the old container); reattaching with tuning
+  flags now warns that they are ignored; stale stopped containers are removed
+  before `docker run` instead of causing a name-conflict error.
+- `down` no longer reports success when `docker rm -f` actually failed.
+- `~/.claude.json` edge cases: a directory there is now a clear error (was: a
+  broken mount), and symlinked configs (dotfile managers) are followed
+  correctly.
+- The generated entry script lives in a per-user `0700` temp subdirectory
+  instead of a fixed world-shared `/tmp` path (tamper/TOCTOU + collision).
+- Launcher: local `tsx` is invoked via `node` directly — no shell, so paths
+  with spaces work and `cmd.exe` metacharacters can't inject on Windows.
+- `doctor` warns when the host uid differs from the container's `agent`
+  (1000), which breaks writes to the bind mounts.
+
 ### Changed
+- Dockerfile: `@anthropic-ai/claude-code` and `tsx` versions are overridable
+  via build args (`CLAUDE_CODE_VERSION`, `TSX_VERSION`) for reproducible
+  builds.
 - Package renamed to the scoped **`@liohtml/agentbox`** for npm publishing
   (the bare name `agentbox` is an npm security placeholder). The installed
   command is still `agentbox`.
diff --git a/CONTRACT.md b/CONTRACT.md
index 2ee3166..622b244 100644
--- a/CONTRACT.md
+++ b/CONTRACT.md
@@ -66,7 +66,9 @@ Defaults (`DEFAULTS` in types):
 - `claudeDir` default = `~/.claude`, `claudeJson` default = `~/.claude.json`
 - `dockerfile` = `assets/Dockerfile`, `buildContext` = `assets/`
 - `observerAsset` = `assets/observer.mjs`
-- `entryScriptPath` = a host temp path (e.g. `os.tmpdir()/agentbox-entry.sh`)
+- `entryScriptPath` = a host temp path in a per-user 0700 subdir
+  (`os.tmpdir()/agentbox-<uid>/entry.sh`) — never a fixed path in the shared
+  temp dir (tamper/TOCTOU on multi-user hosts)
 
 ---
 
@@ -117,8 +119,16 @@ export const session: SessionModule; // see src/types.ts
    `main`.
 4. **Launch the entry script via `bash /agentbox/entry.sh`** so a missing
    execute bit never blocks startup.
-5. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in the `main` window.
+5. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in the `main` window, and
+   launch the lead with `--teammate-mode tmux`: since Claude Code v2.1.179
+   the default teammateMode is `in-process`, which silently disables the
+   split-pane layout.
 6. Read the real TTY size via `stty size` so tmux isn't stuck at 80×24.
+7. **The tmux attach client must NEVER be container PID 1.** The container
+   runs detached (`docker run -d`); the entry script sets the session up and
+   idles while it exists, and clients attach via `docker exec … tmux attach`.
+   Otherwise `C-b d` (detach) exits PID 1, kills every agent, and `--rm`
+   deletes the container.
 
 ---
 
diff --git a/README.md b/README.md
index 42bf2a8..4e61def 100644
--- a/README.md
+++ b/README.md
@@ -122,7 +122,7 @@ WORKSPACE=~/code/myapp MEM=8g CPUS=6 agentbox up --port 5000
 1. **Builds the image** from `assets/Dockerfile` if it's missing — Ubuntu 24.04 with Node 22, Python 3, Rust (rustup), git, tmux, and Claude Code + `tsx` installed globally. It runs as the non-root user **`agent`** and never contains credentials.
 2. **Prepares the host bind mounts** (below), touching `~/.claude.json` first so Docker mounts a *file*, not a directory.
 3. **Generates a tmux entry script** sized to your real terminal (read via `stty size`, so tmux isn't stuck at 80×24).
-4. **Runs the container** (`docker run -it`, with `--memory`/`--cpus` limits and the Observer port published), launching the entry script via **`bash /agentbox/entry.sh`** — using `bash` so a missing execute bit can never block startup. If the container is already running, it reattaches instead of starting a second session.
+4. **Runs the container detached** (`docker run -d --rm`, with `--memory`/`--cpus` limits and the Observer port published), launching the entry script via **`bash /agentbox/entry.sh`** — using `bash` so a missing execute bit can never block startup. The entry script sets the tmux session up and stays alive as PID 1; agentbox then attaches your terminal via `docker exec … tmux attach`. Detaching (`Ctrl+b d`) only ends that client — the box, the lead, and all teammates keep running. If the container is already running, `up` just reattaches.
 
 ### Bind mounts (host → container)
 
@@ -138,7 +138,7 @@ WORKSPACE=~/code/myapp MEM=8g CPUS=6 agentbox up --port 5000
 
 Two windows:
 
-- **`main`** — the Claude Code lead, launched with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. Teammates the lead spawns appear as panes here.
+- **`main`** — the Claude Code lead, launched with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` and `--teammate-mode tmux` (required since Claude Code v2.1.179, where the default became `in-process` — without it teammates would not appear as panes). Teammates the lead spawns appear as panes here.
 - **`observer`** — the Observer web server (its own window, never a pane in `main`).
 
 | Keys      | Action                                                              |
@@ -163,7 +163,7 @@ The `main` window starts the Claude Code lead with Agent Teams enabled. Just tal
 
 agentbox isolates **resources** (CPU/memory caps, a throwaway `--rm` container, a non-root `agent` user) — but it is **not a security sandbox for untrusted code**. Two things to be clear about:
 
-- **Your host Claude credentials are mounted read-write.** `~/.claude` and `~/.claude.json` carry your OAuth token, the list of every project path you've opened, and full session transcripts under `~/.claude/projects`. Anything running inside the box can read or modify them. Only run workloads you trust.
+- **Your host Claude credentials are mounted read-write.** `~/.claude` and `~/.claude.json` carry your OAuth token, the list of every project path you've opened, and full session transcripts under `~/.claude/projects`. Anything running inside the box can read or modify them. That includes `~/.claude/settings.json` and hooks — code in the box could plant a hook that your **host** Claude Code executes later, i.e. the mount is a container-to-host escape channel for untrusted workloads. Only run workloads you trust. (Narrowing this mount to just credentials is on the [roadmap](ROADMAP.md).)
 - **The container is a workbench, not a jail.** Treat it as a clean, disposable, resource-capped place for *your own* agentic workflows — not as a barrier against malicious code. (The Observer is published to `127.0.0.1` only, so its unauthenticated dashboard never leaks to the LAN.)
 
 ---
@@ -215,6 +215,8 @@ Baked into the implementation and the [contract](CONTRACT.md):
 3. **The Observer lives in its own window**, never a pane in `main` — Claude's tmux teammate mode only splits the lead's window into panes if that window is otherwise empty.
 4. **The entry script is launched via `bash`**, so a missing execute bit can't block startup.
 5. **TTY size is read with `stty size`** so tmux opens at your real terminal dimensions instead of the 80×24 default.
+6. **The tmux attach client is never container PID 1.** The container runs detached and your terminal attaches via `docker exec`, so `Ctrl+b d` detaches without tearing down the sandbox. (If the attach client were PID 1, a detach would kill every agent and `--rm` would delete the container.)
+7. **The lead is launched with `--teammate-mode tmux`** — since Claude Code v2.1.179 the default is `in-process`, which would silently disable the split-pane team layout agentbox is built around.
 
 ---
 
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 0000000..9b885ce
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,73 @@
+# Roadmap
+
+Prioritized improvement backlog, curated from ecosystem research
+(comparable sandboxes: textcortex/claude-code-sandbox, claude-pod, ai-pod,
+claudeman; Anthropic's devcontainer reference; Agent Teams docs, 2026-07).
+Ordered by impact-to-effort. PRs welcome — please open an issue first for
+anything marked M/L effort.
+
+## Now (small effort, high impact)
+
+1. **Force split-pane teammate mode** *(S, high — bug-level)* —
+   Since Claude Code v2.1.179 the default `teammateMode` is `in-process`,
+   so teammates no longer appear as tmux panes — agentbox's signature
+   layout. Launch the lead with `--teammate-mode tmux`.
+2. **`--yolo` flag** *(S, high)* — opt-in
+   `--dangerously-skip-permissions` for the lead (teammates inherit it). A
+   disposable, resource-capped container is exactly the environment this
+   flag exists for; teammate permission prompts otherwise bubble up to the
+   lead and multiply friction.
+3. **Persistent tool-cache volumes** *(S, high)* — named Docker volumes
+   for `~/.npm`, `~/.cargo/registry`, and pip's cache. The box stays
+   `--rm`-disposable; only caches survive, killing the cold-start tax.
+4. **Git identity + `gh` auth forwarding** *(S, high)* — mount
+   `~/.gitconfig` (read-only) and forward `gh` auth so agents can commit
+   and open PRs. Same philosophy as Claude auth reuse: borrow host
+   identity, never store it.
+
+## Next (medium effort)
+
+5. **Named boxes / one container per project** *(M, high)* — derive
+   container name, tmux session, and Observer port from the workspace path
+   (plus `--name` override) so two projects never share/steal one box.
+   Removes the biggest documented footgun.
+6. **Credential isolation** *(M, high)* — mount only
+   `.credentials.json` + a minimal `.claude.json` into a per-box dir
+   instead of all of `~/.claude` (which carries transcripts and every
+   project path). Also fixes the Observer showing other projects'
+   sessions.
+7. **Per-project config** *(M, high)* — optional `agentbox.json` (extra
+   apt packages, setup commands, env, mounts, resource defaults) or a
+   custom Dockerfile `FROM agentbox:latest`. Explicitly *not* full
+   devcontainer.json compatibility.
+8. **Session git-branch safety net** *(M, med-high)* — opt-in: create
+   `agentbox/<timestamp>` branch on `up`, print a diff summary on `down`.
+9. **Podman support** *(M, med)* — detect `podman` when `docker` is
+   absent; rootless-by-default strengthens the isolation story.
+10. **Headless mode: `agentbox run "<prompt>"`** *(M, med)* — run
+    `claude -p` in the box without tmux/TTY, stream output, exit with
+    Claude's status. Makes agentbox scriptable for cron/CI.
+
+## Later
+
+11. **Opt-in egress firewall (`--restrict-network`)** *(M-L, med-high)* —
+    port Anthropic's devcontainer `init-firewall.sh` (default-deny outbound,
+    allowlist api.anthropic.com/npm/GitHub; `NET_ADMIN` for init, then drop).
+12. **Observer: Agent-Teams hook feed** *(M, med)* — register
+    `TeammateIdle`/`TaskCreated`/`TaskCompleted` hooks that POST to the
+    Observer for an authoritative live task board instead of inferred
+    JSONL activity.
+13. **ARM64 / Apple Silicon polish** *(S, med)* — `doctor` reports host
+    arch, `up` warns on image/host arch mismatch (qemu emulation is slow),
+    `--platform` pass-through.
+14. **`doctor`/`down` polish** *(S, low-med)* — sweep orphaned tmux
+    sessions on `down`; auto-pick the next free Observer port on `up`.
+15. **`--gpus` pass-through** *(S, low)* — thin mapping to
+    `docker run --gpus` (Linux/NVIDIA), consistent with `--memory`/`--cpus`.
+
+## Non-goals
+
+- Full devcontainer.json compatibility (enterprise-bloat path).
+- Being a security jail — see SECURITY.md; the egress firewall is
+  hardening, not a sandbox guarantee.
+- Baking credentials or per-user state into the image. Ever.
diff --git a/SECURITY.md b/SECURITY.md
index 147ab62..822e35b 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -18,8 +18,11 @@ agentbox is a **workbench, not a jail**. By design:
 - Your host `~/.claude` directory and `~/.claude.json` are bind-mounted
   **read-write** into the container. They contain your OAuth token, the list
   of project paths you've opened, and full session transcripts. Anything
-  running inside the box can read or modify them. Only run workloads you
-  trust.
+  running inside the box can read or modify them — including
+  `~/.claude/settings.json` and hooks, which your **host** Claude Code
+  executes. In other words, for untrusted workloads this mount is a
+  container-to-host escape channel. Only run workloads you trust.
+  (Narrowing the mount to just credentials is on the roadmap.)
 - The container isolates *resources* (CPU/memory caps, `--rm`, non-root
   `agent` user) — it is **not** a security boundary against malicious code.
 - The Observer dashboard is unauthenticated by design; its port is published
diff --git a/assets/Dockerfile b/assets/Dockerfile
index 04e45ef..77f980a 100644
--- a/assets/Dockerfile
+++ b/assets/Dockerfile
@@ -34,8 +34,11 @@ RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && node --version && npm --version
 
 # ── Global npm tools: Claude Code + tsx ───────────────────────────────────────
-# Pinned to global prefix; no auth baked in.
-RUN npm install -g @anthropic-ai/claude-code tsx \
+# No auth baked in. Versions overridable for reproducible builds:
+#   docker build --build-arg CLAUDE_CODE_VERSION=2.1.180 --build-arg TSX_VERSION=4.19.2 …
+ARG CLAUDE_CODE_VERSION=latest
+ARG TSX_VERSION=latest
+RUN npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" "tsx@${TSX_VERSION}" \
     && npm cache clean --force
 
 # ── Non-root user `agent` ─────────────────────────────────────────────────────
diff --git a/assets/observer.mjs b/assets/observer.mjs
index acf518a..8885f2e 100644
--- a/assets/observer.mjs
+++ b/assets/observer.mjs
@@ -10,10 +10,11 @@
  * It surfaces live agent-team activity by tailing the Claude projects dir.
  */
 import { createServer } from "node:http";
-import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { readdirSync, statSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-const PORT = Number(process.env.OBSERVER_PORT || 4317);
+const RAW_PORT = Number(process.env.OBSERVER_PORT || 4317);
+const PORT = Number.isInteger(RAW_PORT) && RAW_PORT > 0 && RAW_PORT <= 65535 ? RAW_PORT : 4317;
 const HOST = "0.0.0.0";
 const PROJECTS_DIR = process.env.CLAUDE_PROJECTS_DIR || "/home/agent/.claude/projects";
 
@@ -49,15 +50,6 @@ function collectSessions() {
   return out.slice(0, 50);
 }
 
-function tail(file, n) {
-  try {
-    const lines = readFileSync(file, "utf8").trim().split("\n");
-    return lines.slice(-n);
-  } catch {
-    return [];
-  }
-}
-
 const PAGE = `<!doctype html><html><head><meta charset="utf-8">
 <title>agentbox observer</title>
 <meta name="viewport" content="width=device-width,initial-scale=1">
@@ -81,6 +73,10 @@ const PAGE = `<!doctype html><html><head><meta charset="utf-8">
   <tbody id="rows"><tr><td colspan="4" class="muted">loading…</td></tr></tbody></table>
 </main>
 <script>
+// Project/session names come from filesystem paths that in-container code can
+// create — always HTML-escape before rendering (stored-XSS guard).
+const esc = (v) => String(v).replace(/[&<>"']/g, (c) =>
+  ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
 async function refresh(){
   try{
     const r = await fetch('/api/sessions'); const data = await r.json();
@@ -88,7 +84,7 @@ async function refresh(){
     if(!data.sessions.length){ rows.innerHTML='<tr><td colspan="4" class="muted">no active sessions yet</td></tr>'; return; }
     rows.innerHTML = data.sessions.map(s=>{
       const ago = Math.max(0, Math.round((data.now - s.mtime)/1000));
-      return '<tr><td>'+s.project+'</td><td>'+s.session.slice(0,8)+'…</td><td>'+(s.size/1024|0)+' KB</td><td>'+ago+'s ago</td></tr>';
+      return '<tr><td>'+esc(s.project)+'</td><td>'+esc(s.session.slice(0,8))+'…</td><td>'+(s.size/1024|0)+' KB</td><td>'+ago+'s ago</td></tr>';
     }).join('');
   }catch(e){ /* ignore transient */ }
 }
@@ -111,6 +107,18 @@ const server = createServer((req, res) => {
   res.end(PAGE);
 });
 
+server.on("error", (err) => {
+  // Without this handler a bind failure (e.g. EADDRINUSE) is an unhandled
+  // exception and the observer tmux window dies with an unreadable stack.
+  if (err && err.code === "EADDRINUSE") {
+    console.error(`[observer] port ${PORT} is already in use inside the container.`);
+    console.error(`[observer] stop the other process or restart agentbox with --port <n>.`);
+  } else {
+    console.error(`[observer] server error: ${err && err.message ? err.message : err}`);
+  }
+  process.exitCode = 1;
+});
+
 server.listen(PORT, HOST, () => {
   console.log(`[observer] listening on http://${HOST}:${PORT} (open http://localhost:${PORT} on the host)`);
 });
diff --git a/bin/agentbox.mjs b/bin/agentbox.mjs
index d154a85..1dbbaf3 100644
--- a/bin/agentbox.mjs
+++ b/bin/agentbox.mjs
@@ -11,24 +11,25 @@ import { dirname, resolve } from "node:path";
 const here = dirname(fileURLToPath(import.meta.url));
 const entry = resolve(here, "..", "src", "index.ts");
 
-// Prefer the locally-installed tsx (node_modules/.bin) so a fresh clone works
-// after just `npm install`, with no global tsx required. Fall back to PATH.
+// Prefer the locally-installed tsx so a fresh clone (or the published
+// package, where tsx is a runtime dependency) works with no global tsx.
+// Invoke tsx's JS entry with the current node binary instead of the .bin
+// shim: no shell involved, so paths with spaces and cmd.exe metacharacters
+// can never break or inject (the .cmd shim needed shell:true on Windows).
 const isWin = process.platform === "win32";
-const localTsx = resolve(
-  here,
-  "..",
-  "node_modules",
-  ".bin",
-  isWin ? "tsx.cmd" : "tsx",
-);
-const useLocal = existsSync(localTsx);
-const tsxCmd = useLocal ? localTsx : "tsx";
+const localTsxCli = resolve(here, "..", "node_modules", "tsx", "dist", "cli.mjs");
+const useLocal = existsSync(localTsxCli);
 
-const child = spawn(tsxCmd, [entry, ...process.argv.slice(2)], {
-  stdio: "inherit",
-  env: process.env,
-  shell: isWin && useLocal, // a .cmd shim needs a shell on Windows
-});
+const child = useLocal
+  ? spawn(process.execPath, [localTsxCli, entry, ...process.argv.slice(2)], {
+      stdio: "inherit",
+      env: process.env,
+    })
+  : spawn("tsx", [entry, ...process.argv.slice(2)], {
+      stdio: "inherit",
+      env: process.env,
+      shell: isWin, // PATH fallback: a global tsx is a .cmd shim on Windows
+    });
 
 child.on("error", (err) => {
   if (err && err.code === "ENOENT") {
diff --git a/src/cli/config.ts b/src/cli/config.ts
index dc82826..f00b5f6 100644
--- a/src/cli/config.ts
+++ b/src/cli/config.ts
@@ -18,6 +18,18 @@ function str(v: string | boolean | undefined): string | undefined {
   return typeof v === "string" ? v : undefined;
 }
 
+/**
+ * Per-user temp directory for the generated entry script. A fixed path in the
+ * shared, world-writable temp dir would let another local user pre-create or
+ * swap the script that gets bind-mounted (and executed) inside the container;
+ * a user-owned subdirectory (created 0700 by the session module) closes that.
+ */
+function entryScriptDir(): string {
+  const info = os.userInfo();
+  const who = info.uid >= 0 ? String(info.uid) : info.username.replace(/[^\w.-]/g, "_");
+  return path.join(os.tmpdir(), `agentbox-${who}`);
+}
+
 export function resolveConfig(
   env: NodeJS.ProcessEnv,
   flags: Record<string, string | boolean>,
@@ -48,6 +60,49 @@ export function resolveConfig(
     dockerfile: path.join(REPO_ROOT, "assets", "Dockerfile"),
     buildContext: path.join(REPO_ROOT, "assets"),
     observerAsset: path.join(REPO_ROOT, "assets", "observer.mjs"),
-    entryScriptPath: path.join(os.tmpdir(), "agentbox-entry.sh"),
+    entryScriptPath: path.join(entryScriptDir(), "entry.sh"),
   };
 }
+
+/**
+ * Validate a resolved config before any Docker work happens, so bad input
+ * fails fast with a clear message instead of surfacing as a cryptic docker
+ * error after a minutes-long image build. Returns a list of problems
+ * (empty = valid).
+ */
+export function validateConfig(config: AgentboxConfig): string[] {
+  const problems: string[] = [];
+
+  if (
+    !Number.isInteger(config.observerPort) ||
+    config.observerPort < 1 ||
+    config.observerPort > 65535
+  ) {
+    problems.push(
+      `--port must be an integer between 1 and 65535 (got '${config.observerPort}')`,
+    );
+  }
+
+  // Docker accepts e.g. "4g", "512m", "1024k", "1000000b" or plain bytes.
+  if (!/^\d+(\.\d+)?[bkmg]?$/i.test(config.memory)) {
+    problems.push(`--memory must look like '4g', '512m' or a byte count (got '${config.memory}')`);
+  }
+
+  if (!/^\d+(\.\d+)?$/.test(config.cpus)) {
+    problems.push(`--cpus must be a number, e.g. '4' or '1.5' (got '${config.cpus}')`);
+  }
+
+  // ':' is Docker's -v field delimiter; a mount source containing it would
+  // silently produce a wrong/invalid mount spec.
+  for (const [label, p] of [
+    ["workspace", config.workspace],
+    ["claude dir", config.claudeDir],
+    ["claude config file", config.claudeJson],
+  ] as const) {
+    if (p.includes(":")) {
+      problems.push(`${label} path must not contain ':' (Docker mount delimiter): ${p}`);
+    }
+  }
+
+  return problems;
+}
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 9543195..6c09eb7 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -13,13 +13,24 @@ import type { AgentboxConfig } from "../types.ts";
 import { docker } from "../docker/index.ts";
 import { session } from "../session/index.ts";
 import { parseArgs } from "./parser.ts";
-import { resolveConfig } from "./config.ts";
+import { resolveConfig, validateConfig } from "./config.ts";
 import { commandHelp, topHelp } from "./help.ts";
 
 // Re-export so the contract's `export function resolveConfig` is satisfied here.
 export { resolveConfig } from "./config.ts";
 
 const KNOWN_COMMANDS = ["up", "shell", "rebuild", "doctor", "down", "help"];
+/** Flags any command accepts. Anything else is a hard error (likely a typo). */
+const KNOWN_FLAGS = new Set([
+  "workspace",
+  "memory",
+  "cpus",
+  "port",
+  "network",
+  "no-cache",
+  "help",
+  "h",
+]);
 
 /** Entry point invoked by src/index.ts. Always resolves with an exit code. */
 export async function run(argv: string[]): Promise<number> {
@@ -46,15 +57,70 @@ export async function run(argv: string[]): Promise<number> {
     return 1;
   }
 
+  // Reject typo'd flags instead of silently ignoring them (`--no-cahce`
+  // silently doing a cached build is worse than an error).
+  const unknownFlags = Object.keys(parsed.flags).filter((f) => !KNOWN_FLAGS.has(f));
+  if (unknownFlags.length > 0) {
+    console.error(
+      `agentbox: unknown flag${unknownFlags.length > 1 ? "s" : ""}: ` +
+        unknownFlags.map((f) => `--${f}`).join(", "),
+    );
+    console.error(`Run 'agentbox help ${parsed.command}' for accepted flags.`);
+    return 1;
+  }
+
+  // Commands take no extra positionals (only `help <command>` does).
+  if (parsed.positionals.length > 1) {
+    console.error(
+      `agentbox: unexpected argument '${parsed.positionals[1]}' after '${parsed.command}'.`,
+    );
+    return 1;
+  }
+
   const config = resolveConfig(process.env, parsed.flags);
   const forceNoCache = parsed.flags["no-cache"] === true;
 
+  // Fail fast on invalid input — before any (potentially minutes-long) Docker
+  // work. `doctor` is exempt: it reports problems as its ✓/✗ checklist.
+  if (parsed.command !== "doctor") {
+    const problems = validateConfig(config);
+    if (problems.length > 0) {
+      for (const p of problems) console.error(`agentbox: ${p}`);
+      return 1;
+    }
+    // An explicitly requested workspace must already exist — auto-creating it
+    // would turn a typo (--workspace ~/projcts) into an empty mounted dir.
+    const workspaceRequested =
+      typeof parsed.flags.workspace === "string" || process.env.WORKSPACE !== undefined;
+    if (workspaceRequested && !isDir(config.workspace)) {
+      console.error(
+        `agentbox: workspace directory does not exist: ${config.workspace}\n` +
+          `Create it first, or check the --workspace / WORKSPACE value for typos.`,
+      );
+      return 1;
+    }
+  }
+
+  // Reattaching ignores per-invocation flags (the box is shared); make that
+  // visible instead of silent.
+  const tuningFlagsGiven = ["workspace", "port", "memory", "cpus"].some(
+    (f) => typeof parsed.flags[f] === "string",
+  );
+
   try {
     switch (parsed.command) {
       case "up":
-        return await cmdUp(config, { force: false, noCache: forceNoCache });
+        return await cmdUp(config, {
+          force: false,
+          noCache: forceNoCache,
+          warnOnReattach: tuningFlagsGiven,
+        });
       case "rebuild":
-        return await cmdUp(config, { force: true, noCache: true });
+        return await cmdUp(config, {
+          force: true,
+          noCache: true,
+          warnOnReattach: tuningFlagsGiven,
+        });
       case "shell":
         return await cmdShell(config);
       case "doctor":
@@ -79,13 +145,43 @@ export async function run(argv: string[]): Promise<number> {
 /** `up` (and the tail of `rebuild`): build-if-needed, mount, write script, run. */
 async function cmdUp(
   config: AgentboxConfig,
-  opts: { force: boolean; noCache: boolean },
+  opts: { force: boolean; noCache: boolean; warnOnReattach?: boolean },
 ): Promise<number> {
   if (!(await docker.available())) {
     console.error(dockerUnavailableMessage());
     return 1;
   }
 
+  const running = await docker.containerRunning(config.containerName);
+
+  if (running && opts.force) {
+    // Rebuilding the image while the old container is up would silently
+    // reattach to the OLD image afterwards — refuse instead.
+    console.error(
+      `agentbox: container '${config.containerName}' is running — a rebuild would not apply to it.\n` +
+        `Stop it first:  agentbox down   (then: agentbox rebuild)`,
+    );
+    return 1;
+  }
+
+  if (running) {
+    if (opts.warnOnReattach) {
+      console.error(
+        `agentbox: note — the box is already running; --workspace/--port/--memory/--cpus are ignored on reattach.\n` +
+          `Use 'agentbox down' first to start a fresh box with new settings.`,
+      );
+    }
+    console.log(`agentbox: reattaching to running container '${config.containerName}'…`);
+    return await docker.execAttach(config, session.attachCommand(config));
+  }
+
+  // A stopped-but-present container (e.g. an --rm corpse after a daemon
+  // restart) would make `docker run --name` fail with a name conflict.
+  if (await docker.containerExists(config.containerName)) {
+    console.log(`agentbox: removing stale container '${config.containerName}'…`);
+    await docker.removeContainer(config.containerName);
+  }
+
   await docker.ensureHostMounts(config);
 
   const needBuild = opts.force || !(await docker.imageExists(config.image));
@@ -99,13 +195,43 @@ async function cmdUp(
   const tty = session.readTtySize();
   session.writeEntryScript(config, tty);
 
-  if (await docker.containerRunning(config.containerName)) {
-    console.log(`agentbox: reattaching to running container '${config.containerName}'…`);
-    return await docker.execAttach(config);
+  console.log(`agentbox: starting sandbox — Observer at http://localhost:${config.observerPort}…`);
+  const started = await docker.runContainer(config, tty);
+  if (started !== 0) {
+    console.error(`agentbox: docker run failed (exit ${started}).`);
+    return started;
   }
 
-  console.log(`agentbox: starting sandbox — Observer at http://localhost:${config.observerPort}…`);
-  return await docker.runContainer(config, tty);
+  // The container is detached; wait for the entry script to create the tmux
+  // session, then attach a client. Detaching later only ends the client.
+  const ready = await waitForSession(config, 15000);
+  if (!ready) {
+    console.error(
+      `agentbox: the tmux session did not come up in time.\n` +
+        `Inspect the container with:  docker logs ${config.containerName}`,
+    );
+    return 1;
+  }
+  return await docker.execAttach(config, session.attachCommand(config));
+}
+
+/** Poll until the in-container tmux session exists (or the timeout passes). */
+async function waitForSession(config: AgentboxConfig, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (
+      await docker.execOk(config.containerName, [
+        "tmux",
+        "has-session",
+        "-t",
+        config.sessionName,
+      ])
+    ) {
+      return true;
+    }
+    if (Date.now() >= deadline) return false;
+    await new Promise((r) => setTimeout(r, 250));
+  }
 }
 
 /** `shell`: attach a bash shell to a running container. */
@@ -155,6 +281,18 @@ async function cmdDoctor(config: AgentboxConfig): Promise<number> {
       (isFile(config.claudeJson) ? "" : "  (auto-created on 'up')"),
   );
 
+  // Bind-mount permissions: the in-container `agent` user is uid 1000. A
+  // different host uid means the mounted ~/.claude and workspace may not be
+  // writable inside the box. Soft warning only.
+  if (typeof process.getuid === "function") {
+    const uid = process.getuid();
+    line(
+      uid === 1000,
+      `Host uid matches the container 'agent' user (1000): uid ${uid}` +
+        (uid === 1000 ? "" : "  (writes to mounted dirs may fail inside the box)"),
+    );
+  }
+
   // Observer port validity.
   const portOk = Number.isInteger(config.observerPort) && config.observerPort > 0 &&
     config.observerPort <= 65535;
diff --git a/src/docker/index.ts b/src/docker/index.ts
index 570f755..ec8f97f 100644
--- a/src/docker/index.ts
+++ b/src/docker/index.ts
@@ -150,8 +150,15 @@ export const docker: DockerModule = {
   },
 
   async removeContainer(name: string): Promise<void> {
-    // `rm -f` stops + removes. Ignore "no such container" (benign / idempotent).
-    await capture(["rm", "-f", name]);
+    // `rm -f` stops + removes. Ignore "no such container" (benign / idempotent),
+    // but surface every other failure — otherwise `down` reports success while
+    // the container still exists.
+    const { code, stderr } = await capture(["rm", "-f", name]);
+    if (code !== 0 && !/no such container/i.test(stderr)) {
+      throw new Error(
+        `docker rm -f ${name} failed (exit ${code})${stderr ? `: ${stderr.trim()}` : ""}`,
+      );
+    }
   },
 
   async ensureHostMounts(config: AgentboxConfig): Promise<void> {
@@ -160,28 +167,54 @@ export const docker: DockerModule = {
     fs.mkdirSync(config.claudeDir, { recursive: true });
 
     // claudeJson must be a FILE so Docker bind-mounts a file (not a dir).
-    // Edge case: a prior bad mount may have created it as a directory — leave
-    // that alone (can't safely rm), but ensure a file exists if nothing does.
-    let needsTouch = true;
+    let target: fs.Stats | undefined;
     try {
-      const st = fs.statSync(config.claudeJson);
-      if (st.isFile()) needsTouch = false;
-      // If it's a directory we cannot turn it into a file here; leave as-is.
-      else if (st.isDirectory()) needsTouch = false;
+      target = fs.lstatSync(config.claudeJson);
     } catch {
       // Does not exist yet → create it below.
     }
-    if (needsTouch) {
+
+    if (target?.isDirectory()) {
+      // A prior bad mount can leave a directory here; Docker would happily
+      // mount it and Claude Code would fail opaquely inside the container.
+      throw new Error(
+        `${config.claudeJson} is a directory, but Claude Code needs a file there.\n` +
+          `Remove it (rmdir '${config.claudeJson}') and run agentbox again.`,
+      );
+    }
+
+    if (target?.isSymbolicLink()) {
+      // Dotfile managers often symlink ~/.claude.json. Follow it: if the
+      // target exists we're done; if it dangles, create the target through
+      // the symlink (flag "w" — "wx" would fail with a confusing EEXIST on
+      // the link itself).
+      try {
+        fs.statSync(config.claudeJson);
+      } catch {
+        fs.writeFileSync(config.claudeJson, "{}\n", { flag: "w" });
+      }
+      return;
+    }
+
+    if (!target) {
       fs.mkdirSync(path.dirname(config.claudeJson), { recursive: true });
-      // Create an empty JSON object so Claude Code reads valid JSON.
-      fs.writeFileSync(config.claudeJson, "{}\n", { flag: "wx" });
+      // Create an empty JSON object so Claude Code reads valid JSON. "wx" +
+      // ignored EEXIST keeps a concurrent create benign.
+      try {
+        fs.writeFileSync(config.claudeJson, "{}\n", { flag: "wx" });
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      }
     }
   },
 
   async runContainer(config: AgentboxConfig, tty: TtySize): Promise<number> {
+    // Detached (-d): the entry script — not a tmux attach client — is PID 1,
+    // so detaching a client can never tear the sandbox down. Attaching is a
+    // separate `docker exec` (execAttach).
     const args = [
       "run",
-      "-it",
+      "-d",
       "--rm",
       "--name",
       config.containerName,
@@ -222,9 +255,18 @@ export const docker: DockerModule = {
   },
 
   async execAttach(config: AgentboxConfig, command?: string[]): Promise<number> {
-    const cmd =
-      command ?? ["bash", "-lc", `tmux attach -t '${config.sessionName}'`];
+    const cmd = command ?? [
+      "bash",
+      "-lc",
+      // Same '\'' single-quote escaping the session module uses — keeps a
+      // future configurable session name injection-safe.
+      `tmux attach -t '${config.sessionName.replace(/'/g, `'\\''`)}'`,
+    ];
     const args = ["exec", "-it", config.containerName, ...cmd];
     return inherit(args);
   },
+
+  async execOk(containerName: string, command: string[]): Promise<boolean> {
+    return ok(["exec", containerName, ...command]);
+  },
 };
diff --git a/src/session/index.ts b/src/session/index.ts
index 90478b4..6038932 100644
--- a/src/session/index.ts
+++ b/src/session/index.ts
@@ -8,7 +8,8 @@
  * Import style: ESM with explicit `.ts` extensions.
  */
 import { execSync } from "node:child_process";
-import { writeFileSync, chmodSync } from "node:fs";
+import { writeFileSync, chmodSync, mkdirSync, lstatSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
 
 import {
   CONTAINER_OBSERVER,
@@ -57,7 +58,16 @@ function readTtySize(): TtySize {
 }
 
 /**
- * Build the bash entry script that runs INSIDE the container.
+ * Build the bash entry script that runs INSIDE the container as PID 1.
+ *
+ * CRITICAL lifecycle fact: the tmux *client* must never be the container's
+ * main process. If it were (the old `exec tmux attach` design), a plain
+ * `C-b d` detach would exit PID 1, tear down the whole PID namespace (lead,
+ * teammates, Observer) and — with `--rm` — delete the container. Instead this
+ * script sets the session up detached and then idles while the tmux SERVER
+ * has the session; clients attach via `docker exec` (see cli/docker modules).
+ * Detach only ends the exec'd client; ending the tmux session ends PID 1 and
+ * therefore the container.
  */
 function buildEntryScript(config: AgentboxConfig, tty: TtySize): string {
   const session = config.sessionName;
@@ -67,7 +77,12 @@ function buildEntryScript(config: AgentboxConfig, tty: TtySize): string {
   const observerPort = config.observerPort;
 
   // Command run in the `main` window: enable Agent Teams, launch Claude lead.
-  const leadCmd = "export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; claude";
+  // `--teammate-mode tmux` is required for teammates to appear as split
+  // panes: since Claude Code v2.1.179 the default teammateMode is
+  // "in-process", which silently disables the split-pane layout agentbox is
+  // built around.
+  const leadCmd =
+    "export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; claude --teammate-mode tmux";
   // Command run in the `observer` window: the dashboard web server.
   const observerCmd = `OBSERVER_PORT=${observerPort} node ${shSingleQuote(
     CONTAINER_OBSERVER,
@@ -75,46 +90,64 @@ function buildEntryScript(config: AgentboxConfig, tty: TtySize): string {
 
   return `#!/usr/bin/env bash
 # agentbox entry script — generated; run via: bash /agentbox/entry.sh
+# Runs as container PID 1: sets the tmux session up, then idles while the
+# session exists. Attach happens via 'docker exec … tmux attach'.
 set -euo pipefail
 
 SESSION=${sessionQ}
 
-# Reattach if the session already exists.
-if tmux has-session -t "$SESSION" 2>/dev/null; then
-  exec tmux attach -t "$SESSION"
-fi
-
-# Create a new detached session sized to the real TTY. Window 'main' will host
-# the Claude lead (Agent Teams enabled).
-tmux new-session -d -s "$SESSION" -n main -x ${cols} -y ${rows}
+if ! tmux has-session -t "$SESSION" 2>/dev/null; then
+  # Create a new detached session sized to the real TTY. Window 'main' will
+  # host the Claude lead (Agent Teams enabled).
+  tmux new-session -d -s "$SESSION" -n main -x ${cols} -y ${rows}
 
-# Launch the Claude lead in the 'main' window with Agent Teams enabled.
-tmux send-keys -t "$SESSION":main ${shSingleQuote(leadCmd)} C-m
+  # Launch the Claude lead in the 'main' window with Agent Teams enabled.
+  tmux send-keys -t "$SESSION":main ${shSingleQuote(leadCmd)} C-m
 
-# Observer dashboard in its OWN window (NEVER a pane in main: teammateMode tmux
-# only splits panes if the lead window is otherwise empty).
-tmux new-window -t "$SESSION" -n observer ${shSingleQuote(observerCmd)}
+  # Observer dashboard in its OWN window (NEVER a pane in main: teammateMode
+  # tmux only splits panes if the lead window is otherwise empty). Keep the
+  # window around if the server crashes so the error output stays readable.
+  tmux new-window -t "$SESSION" -n observer ${shSingleQuote(observerCmd)}
+  tmux set-option -w -t "$SESSION":observer remain-on-exit on
 
-# C-b t → main-vertical layout (lead left, teammates right).
-tmux bind-key -T prefix t select-layout main-vertical
+  # C-b t → main-vertical layout (lead left, teammates right).
+  tmux bind-key -T prefix t select-layout main-vertical
 
-# Land the user on the Claude lead.
-tmux select-window -t "$SESSION":main
+  # Land the user on the Claude lead.
+  tmux select-window -t "$SESSION":main
+fi
 
-# Attach.
-exec tmux attach -t "$SESSION"
+# Keep PID 1 alive for as long as the tmux session lives. When the user ends
+# the session (kills the last window / 'tmux kill-session'), this loop exits
+# and '--rm' removes the container.
+while tmux has-session -t "$SESSION" 2>/dev/null; do
+  sleep 2
+done
 `;
 }
 
 /**
  * Write the entry script to config.entryScriptPath and return that path.
+ * The parent directory is created user-only (0700) — see cli/config.ts for
+ * why the script must not live at a fixed path in the shared temp dir.
  */
 function writeEntryScript(config: AgentboxConfig, tty: TtySize): string {
   const script = buildEntryScript(config, tty);
+  mkdirSync(dirname(config.entryScriptPath), { recursive: true, mode: 0o700 });
+  // Never write through a pre-existing symlink at the target path.
+  try {
+    if (lstatSync(config.entryScriptPath).isSymbolicLink()) {
+      rmSync(config.entryScriptPath);
+    }
+  } catch {
+    // does not exist — fine
+  }
   writeFileSync(config.entryScriptPath, script, { encoding: "utf8" });
   try {
-    // Execute bit is irrelevant (launched via `bash`), but harmless.
-    chmodSync(config.entryScriptPath, 0o755);
+    // World-readable so the in-container 'agent' user (uid 1000) can read the
+    // bind-mounted file even when the host uid differs; the 0700 parent dir
+    // keeps other host users out. Execute bit irrelevant (launched via bash).
+    chmodSync(config.entryScriptPath, 0o644);
   } catch {
     // non-fatal
   }
@@ -122,7 +155,7 @@ function writeEntryScript(config: AgentboxConfig, tty: TtySize): string {
 }
 
 /**
- * The argv to reattach an existing in-container tmux session.
+ * The argv to attach to the in-container tmux session (via docker exec).
  */
 function attachCommand(config: AgentboxConfig): string[] {
   return ["bash", "-lc", `tmux attach -t ${shSingleQuote(config.sessionName)}`];
diff --git a/src/types.ts b/src/types.ts
index 4723ae7..5011ab9 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -111,10 +111,11 @@ export interface DockerModule {
    */
   ensureHostMounts(config: AgentboxConfig): Promise<void>;
   /**
-   * Run a fresh container interactively (inherits stdio), with bind mounts,
-   * published observer port, and --memory/--cpus limits. Launches the entry
-   * script via `bash CONTAINER_ENTRY` (never relies on an execute bit).
-   * Resolves with the container's exit code when the user detaches/exits.
+   * Run a fresh container DETACHED (-d), with bind mounts, published observer
+   * port, and --memory/--cpus limits. Launches the entry script via
+   * `bash CONTAINER_ENTRY` (never relies on an execute bit) as container
+   * PID 1 — never a tmux attach client, so detaching a client cannot tear
+   * down the sandbox. Resolves with `docker run`'s exit code.
    */
   runContainer(config: AgentboxConfig, tty: TtySize): Promise<number>;
   /**
@@ -123,6 +124,11 @@ export interface DockerModule {
    * the exit code. `command` overrides the exec command (default: reattach tmux).
    */
   execAttach(config: AgentboxConfig, command?: string[]): Promise<number>;
+  /**
+   * Run a non-interactive command in the running container and report whether
+   * it exited 0 (used to poll tmux session readiness after `runContainer`).
+   */
+  execOk(containerName: string, command: string[]): Promise<boolean>;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -132,14 +138,18 @@ export interface SessionModule {
   /** Read the real terminal size via `stty size`; falls back to DEFAULT_TTY. */
   readTtySize(): TtySize;
   /**
-   * Build the bash entry script (runs INSIDE the container). It must:
-   *   - reattach if the session already exists (tmux has-session)
-   *   - else create session sized to `tty` with two windows:
+   * Build the bash entry script (runs INSIDE the container as PID 1). It must:
+   *   - skip setup if the session already exists (tmux has-session)
+   *   - else create a DETACHED session sized to `tty` with two windows:
    *       window `main`     → Claude lead, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+   *                           + `--teammate-mode tmux` (split panes are no
+   *                           longer the upstream default since v2.1.179)
    *       window `observer` → `node CONTAINER_OBSERVER` (the dashboard)
    *   - bind `C-b t` to `select-layout main-vertical`
    *   - keep `observer` in its OWN window (never a pane in `main`)
-   *   - finally `exec tmux attach -t <session>`
+   *   - finally idle while the session exists (NEVER `exec tmux attach`: an
+   *     attach client as PID 1 means a detach kills the whole sandbox).
+   *     Clients attach via `docker exec` (attachCommand).
    */
   buildEntryScript(config: AgentboxConfig, tty: TtySize): string;
   /** Write buildEntryScript output to config.entryScriptPath; return that path. */
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
new file mode 100644
index 0000000..fda8fcb
--- /dev/null
+++ b/tests/cli.test.ts
@@ -0,0 +1,79 @@
+/**
+ * Tests for src/cli/index.ts — run()'s input rejection paths. All of these
+ * return before any docker call, so they are Docker-free by construction:
+ * help, unknown commands, unknown flags, stray positionals, and invalid
+ * config values must fail fast with exit code 1 (0 for help).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { run } from "../src/cli/index.ts";
+
+/** Capture console output while running argv through the router. */
+async function runCapture(argv: string[]): Promise<{ code: number; out: string; err: string }> {
+  const logs: string[] = [];
+  const errs: string[] = [];
+  const origLog = console.log;
+  const origErr = console.error;
+  console.log = (...a: unknown[]) => logs.push(a.join(" "));
+  console.error = (...a: unknown[]) => errs.push(a.join(" "));
+  try {
+    const code = await run(argv);
+    return { code, out: logs.join("\n"), err: errs.join("\n") };
+  } finally {
+    console.log = origLog;
+    console.error = origErr;
+  }
+}
+
+test("--help exits 0 and prints usage", async () => {
+  const { code, out } = await runCapture(["--help"]);
+  assert.equal(code, 0);
+  assert.match(out, /agentbox/);
+});
+
+test("help <command> exits 0", async () => {
+  const { code, out } = await runCapture(["help", "up"]);
+  assert.equal(code, 0);
+  assert.match(out, /up/);
+});
+
+test("unknown command exits 1 with a message", async () => {
+  const { code, err } = await runCapture(["frobnicate"]);
+  assert.equal(code, 1);
+  assert.match(err, /unknown command 'frobnicate'/);
+});
+
+test("a typo'd flag is a hard error, not silently ignored", async () => {
+  const { code, err } = await runCapture(["rebuild", "--no-cahce"]);
+  assert.equal(code, 1);
+  assert.match(err, /unknown flag/);
+  assert.match(err, /--no-cahce/);
+});
+
+test("stray positionals after the command are rejected", async () => {
+  const { code, err } = await runCapture(["up", "extra"]);
+  assert.equal(code, 1);
+  assert.match(err, /unexpected argument 'extra'/);
+});
+
+test("an invalid --port fails fast before any docker work", async () => {
+  const { code, err } = await runCapture(["up", "--port", "abc"]);
+  assert.equal(code, 1);
+  assert.match(err, /--port must be an integer/);
+});
+
+test("an invalid --memory fails fast before any docker work", async () => {
+  const { code, err } = await runCapture(["up", "--memory", "banana"]);
+  assert.equal(code, 1);
+  assert.match(err, /--memory/);
+});
+
+test("an explicitly requested workspace that does not exist is rejected", async () => {
+  const { code, err } = await runCapture([
+    "up",
+    "--workspace",
+    "/nonexistent/agentbox-test-dir-che3aihe",
+  ]);
+  assert.equal(code, 1);
+  assert.match(err, /workspace directory does not exist/);
+});
diff --git a/tests/config.test.ts b/tests/config.test.ts
index 2ca08f9..881077d 100644
--- a/tests/config.test.ts
+++ b/tests/config.test.ts
@@ -6,7 +6,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import os from "node:os";
 import path from "node:path";
-import { resolveConfig } from "../src/cli/config.ts";
+import { resolveConfig, validateConfig } from "../src/cli/config.ts";
 import { DEFAULTS } from "../src/types.ts";
 
 /** A clean env with none of the agentbox override vars set. */
@@ -96,7 +96,52 @@ test("asset paths point at the repo's assets dir and Dockerfile", () => {
   assert.equal(path.basename(c.observerAsset), "observer.mjs");
 });
 
-test("entryScriptPath lives under the OS temp dir", () => {
+test("entryScriptPath lives in a per-user subdir of the OS temp dir (not a fixed shared path)", () => {
   const c = resolveConfig(emptyEnv(), {});
-  assert.equal(c.entryScriptPath, path.join(os.tmpdir(), "agentbox-entry.sh"));
+  const dir = path.dirname(c.entryScriptPath);
+  assert.equal(path.dirname(dir), os.tmpdir());
+  assert.match(path.basename(dir), /^agentbox-/);
+  assert.equal(path.basename(c.entryScriptPath), "entry.sh");
+  // Must not be the old world-shared fixed path.
+  assert.notEqual(c.entryScriptPath, path.join(os.tmpdir(), "agentbox-entry.sh"));
+});
+
+// ── validateConfig ──────────────────────────────────────────────────────────
+
+test("validateConfig passes a default config", () => {
+  assert.deepEqual(validateConfig(resolveConfig(emptyEnv(), {})), []);
+});
+
+test("validateConfig rejects a non-numeric port", () => {
+  const problems = validateConfig(resolveConfig(emptyEnv(), { port: "abc" }));
+  assert.equal(problems.length, 1);
+  assert.match(problems[0], /--port/);
+});
+
+test("validateConfig rejects out-of-range ports", () => {
+  assert.equal(validateConfig(resolveConfig(emptyEnv(), { port: "0" })).length, 1);
+  assert.equal(validateConfig(resolveConfig(emptyEnv(), { port: "70000" })).length, 1);
+  assert.equal(validateConfig(resolveConfig(emptyEnv(), { port: "4317.5" })).length, 1);
+});
+
+test("validateConfig rejects malformed --memory and --cpus", () => {
+  assert.match(validateConfig(resolveConfig(emptyEnv(), { memory: "banana" }))[0], /--memory/);
+  assert.match(validateConfig(resolveConfig(emptyEnv(), { cpus: "four" }))[0], /--cpus/);
+});
+
+test("validateConfig accepts common docker resource formats", () => {
+  for (const memory of ["4g", "512m", "1024K", "2000000"]) {
+    assert.deepEqual(validateConfig(resolveConfig(emptyEnv(), { memory })), [], memory);
+  }
+  for (const cpus of ["4", "1.5", "0.5"]) {
+    assert.deepEqual(validateConfig(resolveConfig(emptyEnv(), { cpus })), [], cpus);
+  }
+});
+
+test("validateConfig rejects ':' in mount source paths (docker -v delimiter)", () => {
+  const problems = validateConfig(
+    resolveConfig(emptyEnv(), { workspace: "/home/u/proj:v2" }),
+  );
+  assert.equal(problems.length, 1);
+  assert.match(problems[0], /workspace/);
 });
diff --git a/tests/observer.test.ts b/tests/observer.test.ts
index 3ce1768..c76053d 100644
--- a/tests/observer.test.ts
+++ b/tests/observer.test.ts
@@ -42,3 +42,21 @@ test("reads the port from OBSERVER_PORT with a 4317 default", () => {
 test("exposes a /healthz endpoint", () => {
   assert.match(src, /["']\/healthz["']/);
 });
+
+test("HTML-escapes project and session names before innerHTML (stored-XSS guard)", () => {
+  // The client script must define an escaper and route both interpolated
+  // fields through it — project/session names are attacker-influencable
+  // filesystem names from inside the container.
+  assert.match(src, /const esc\s*=/);
+  assert.match(src, /esc\(s\.project\)/);
+  assert.match(src, /esc\(s\.session/);
+});
+
+test("handles server 'error' events instead of dying with an unhandled exception", () => {
+  assert.match(src, /server\.on\(\s*["']error["']/);
+  assert.match(src, /EADDRINUSE/);
+});
+
+test("falls back to the default port when OBSERVER_PORT is not a valid port", () => {
+  assert.match(src, /Number\.isInteger\(RAW_PORT\)/);
+});
diff --git a/tests/session.test.ts b/tests/session.test.ts
index 8ba7619..3f33414 100644
--- a/tests/session.test.ts
+++ b/tests/session.test.ts
@@ -46,6 +46,11 @@ test("enables CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the main window", () =>
   assert.match(s, /send-keys -t "\$SESSION":main .*claude/);
 });
 
+test("launches the lead with --teammate-mode tmux (split panes are no longer the upstream default)", () => {
+  const s = session.buildEntryScript(baseConfig(), TTY);
+  assert.match(s, /claude --teammate-mode tmux/);
+});
+
 test("creates the observer in its OWN window (not a pane in main)", () => {
   const s = session.buildEntryScript(baseConfig(), TTY);
   // A dedicated `new-window -n observer` — never `split-window`.
@@ -75,10 +80,21 @@ test("binds C-b t to select-layout main-vertical", () => {
   assert.match(s, /tmux bind-key -T prefix t select-layout main-vertical/);
 });
 
-test("reattaches if the session already exists", () => {
+test("skips setup when the session already exists (idempotent re-run)", () => {
+  const s = session.buildEntryScript(baseConfig(), TTY);
+  assert.match(s, /if ! tmux has-session -t "\$SESSION"/);
+});
+
+test("PID 1 idles while the session lives — NEVER 'exec tmux attach' (a detach would kill the sandbox)", () => {
+  const s = session.buildEntryScript(baseConfig(), TTY);
+  assert.doesNotMatch(s, /exec tmux attach/);
+  // Keep-alive loop bound to the tmux session's lifetime.
+  assert.match(s, /while tmux has-session -t "\$SESSION"/);
+});
+
+test("observer window keeps its output readable after a crash (remain-on-exit)", () => {
   const s = session.buildEntryScript(baseConfig(), TTY);
-  assert.match(s, /tmux has-session -t "\$SESSION"/);
-  assert.match(s, /exec tmux attach -t "\$SESSION"/);
+  assert.match(s, /set-option -w -t "\$SESSION":observer remain-on-exit on/);
 });
 
 test("uses a bash shebang and strict mode", () => {

From f97c3867a0b6a5e2cbd79e968d337200fcf596da Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 29 Jul 2026 20:14:19 +0000
Subject: [PATCH 4/6] =?UTF-8?q?feat:=20roadmap=20wave=201=20=E2=80=94=20--?=
 =?UTF-8?q?yolo,=20persistent=20tool=20caches,=20git/gh=20auth=20forwardin?=
 =?UTF-8?q?g,=20--gpus,=20arch=20check?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- --yolo: launch the lead with --dangerously-skip-permissions (teammates
  inherit it). Strictly opt-in with a visible warning; documented under
  Security & trust.
- Persistent tool-cache named volumes (agentbox-npm-cache,
  agentbox-cargo-registry, agentbox-pip-cache): boxes stay --rm-disposable,
  package downloads survive. Mount points pre-created agent-owned in the
  image so first use isn't root-owned.
- Host identity forwarding: ~/.gitconfig and ~/.config/gh bind-mounted
  READ-ONLY when present; gh CLI installed in the image. Same philosophy as
  Claude auth: borrow host identity, never store it.
- --gpus passthrough to docker run.
- doctor: image-vs-host architecture check (warns about qemu-emulated
  images on e.g. Apple Silicon).
- docker run argv construction extracted as pure buildRunArgs() and covered
  by a new Docker-free test suite (the audit's top missing-coverage item).
- Docs: README flags/mounts/security, CONTRACT mounts + cache volumes,
  ROADMAP wave 1 marked done, CHANGELOG. Tests: 65 → 76, all green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfjQjysq5JF7gQCJB3RQtP
---
 CHANGELOG.md          |  15 ++++-
 CONTRACT.md           |   7 ++
 README.md             |  11 +++
 ROADMAP.md            |  58 +++++++---------
 assets/Dockerfile     |  13 ++++
 src/cli/config.ts     |   8 +++
 src/cli/help.ts       |  20 ++++--
 src/cli/index.ts      |  31 ++++++++-
 src/cli/parser.ts     |   2 +-
 src/docker/index.ts   | 153 ++++++++++++++++++++++++++++++------------
 src/session/index.ts  |   6 +-
 src/types.ts          |  38 +++++++++++
 tests/config.test.ts  |  14 ++++
 tests/docker.test.ts  | 113 +++++++++++++++++++++++++++++++
 tests/session.test.ts |  10 +++
 15 files changed, 411 insertions(+), 88 deletions(-)
 create mode 100644 tests/docker.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f97e1b9..ff076c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -52,8 +52,21 @@ adheres to [Semantic Versioning](https://semver.org/).
   tarball and runs the CLI as an end user would.
 
 ### Added
+- **`--yolo` flag**: the Claude lead runs with
+  `--dangerously-skip-permissions` (teammates inherit it). Opt-in per
+  invocation, never the default — see README → Security & trust.
+- **Persistent tool-cache volumes**: named Docker volumes for `~/.npm`,
+  `~/.cargo/registry` and pip's cache. Boxes stay `--rm`-disposable; only
+  downloaded packages survive.
+- **Git identity + `gh` auth forwarding**: `~/.gitconfig` and `~/.config/gh`
+  are bind-mounted read-only when present, and the `gh` CLI is installed in
+  the image — agents can commit and open PRs as you, without any credential
+  ever entering the image.
+- **`--gpus` passthrough** to `docker run --gpus` (e.g. `all`, `device=0`).
+- `doctor` warns when the local image architecture doesn't match the host
+  (emulated images are painfully slow under qemu).
 - `SECURITY.md`, `CODE_OF_CONDUCT.md`, PR template, issue-template config,
-  Dependabot config, `RELEASING.md`, this changelog.
+  Dependabot config, `RELEASING.md`, `ROADMAP.md`, this changelog.
 - Tag-triggered release workflow with npm provenance.
 
 ### Removed
diff --git a/CONTRACT.md b/CONTRACT.md
index 622b244..e7719ab 100644
--- a/CONTRACT.md
+++ b/CONTRACT.md
@@ -101,6 +101,13 @@ export const session: SessionModule; // see src/types.ts
 | `config.claudeJson` (`~/.claude.json`) | `/home/agent/.claude.json` | **touch first** so Docker mounts a file, not a dir |
 | `config.entryScriptPath`   | `/agentbox/entry.sh`         | run via `bash` (no execute-bit reliance) |
 | `config.observerAsset`     | `/agentbox/observer.mjs`     | the dashboard                          |
+| `config.gitconfigPath` *(if present)* | `/home/agent/.gitconfig` | **read-only** — git identity reuse |
+| `config.ghConfigDir` *(if present)*   | `/home/agent/.config/gh` | **read-only** — gh CLI auth reuse  |
+
+Named cache volumes (`CACHE_VOLUMES` in types.ts): `agentbox-npm-cache`,
+`agentbox-cargo-registry`, `agentbox-pip-cache` → the box stays `--rm`,
+only tool downloads persist. Host identity mounts are read-only, existence-
+gated, and NEVER copied into the image.
 
 - Publish `-p <observerPort>:<observerPort>`.
 - Apply `--memory <config.memory>` and `--cpus <config.cpus>`.
diff --git a/README.md b/README.md
index 4e61def..2ab9ab1 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,8 @@ Run `agentbox help <command>` for details on any command.
 | `--cpus <val>`      | Docker `--cpus` limit, e.g. `4`.                      | `CPUS`           |
 | `--port <n>`        | Observer web port (default `4317`).                   | —                |
 | `--network <mode>`  | `docker build --network` mode, e.g. `host`.           | `DOCKER_NETWORK` |
+| `--gpus <val>`      | `docker run --gpus` passthrough, e.g. `all` (Linux/NVIDIA). | —           |
+| `--yolo`            | Lead runs with `--dangerously-skip-permissions`; teammates inherit it. Opt-in — only for workloads you trust. | — |
 | `--no-cache`        | Force a clean image build (`up` / `rebuild`).         | —                |
 
 ### Env overrides
@@ -133,6 +135,14 @@ WORKSPACE=~/code/myapp MEM=8g CPUS=6 agentbox up --port 5000
 | `~/.claude.json`      | `/home/agent/.claude.json` | Claude config file (touched first so Docker mounts a file)     |
 | generated `entry.sh`  | `/agentbox/entry.sh`       | the tmux bootstrap, run via `bash`                            |
 | `assets/observer.mjs` | `/agentbox/observer.mjs`   | the Observer dashboard                                         |
+| `~/.gitconfig` *(if present)* | `/home/agent/.gitconfig` **(read-only)** | git identity — agents can commit as you |
+| `~/.config/gh` *(if present)* | `/home/agent/.config/gh` **(read-only)** | `gh` CLI auth — agents can open PRs      |
+
+Additionally, three **named Docker volumes** persist tool caches across boxes
+(`agentbox-npm-cache` → `~/.npm`, `agentbox-cargo-registry` → `~/.cargo/registry`,
+`agentbox-pip-cache` → `~/.cache/pip`). The box itself stays disposable
+(`--rm`); only downloaded packages survive, so fresh boxes skip the
+cold-start tax. Remove them any time with `docker volume rm`.
 
 ### The tmux layout
 
@@ -165,6 +175,7 @@ agentbox isolates **resources** (CPU/memory caps, a throwaway `--rm` container,
 
 - **Your host Claude credentials are mounted read-write.** `~/.claude` and `~/.claude.json` carry your OAuth token, the list of every project path you've opened, and full session transcripts under `~/.claude/projects`. Anything running inside the box can read or modify them. That includes `~/.claude/settings.json` and hooks — code in the box could plant a hook that your **host** Claude Code executes later, i.e. the mount is a container-to-host escape channel for untrusted workloads. Only run workloads you trust. (Narrowing this mount to just credentials is on the [roadmap](ROADMAP.md).)
 - **The container is a workbench, not a jail.** Treat it as a clean, disposable, resource-capped place for *your own* agentic workflows — not as a barrier against malicious code. (The Observer is published to `127.0.0.1` only, so its unauthenticated dashboard never leaks to the LAN.)
+- **`--yolo` removes the last human checkpoint.** With it, the lead (and every teammate) runs `--dangerously-skip-permissions` — no permission prompts inside the box. That's exactly what a disposable container is for, but combined with the mounted credentials and read-only `gh` auth it means agents can do anything *you* can. Opt-in per invocation; never the default.
 
 ---
 
diff --git a/ROADMAP.md b/ROADMAP.md
index 9b885ce..08d6aab 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -6,64 +6,56 @@ claudeman; Anthropic's devcontainer reference; Agent Teams docs, 2026-07).
 Ordered by impact-to-effort. PRs welcome — please open an issue first for
 anything marked M/L effort.
 
-## Now (small effort, high impact)
+## Done
 
-1. **Force split-pane teammate mode** *(S, high — bug-level)* —
-   Since Claude Code v2.1.179 the default `teammateMode` is `in-process`,
-   so teammates no longer appear as tmux panes — agentbox's signature
-   layout. Launch the lead with `--teammate-mode tmux`.
-2. **`--yolo` flag** *(S, high)* — opt-in
-   `--dangerously-skip-permissions` for the lead (teammates inherit it). A
-   disposable, resource-capped container is exactly the environment this
-   flag exists for; teammate permission prompts otherwise bubble up to the
-   lead and multiply friction.
-3. **Persistent tool-cache volumes** *(S, high)* — named Docker volumes
-   for `~/.npm`, `~/.cargo/registry`, and pip's cache. The box stays
-   `--rm`-disposable; only caches survive, killing the cold-start tax.
-4. **Git identity + `gh` auth forwarding** *(S, high)* — mount
-   `~/.gitconfig` (read-only) and forward `gh` auth so agents can commit
-   and open PRs. Same philosophy as Claude auth reuse: borrow host
-   identity, never store it.
+1. ✅ **Force split-pane teammate mode** — the lead launches with
+   `--teammate-mode tmux` (since Claude Code v2.1.179 the default is
+   `in-process`, which silently disabled agentbox's signature layout).
+2. ✅ **`--yolo` flag** — opt-in `--dangerously-skip-permissions` for the
+   lead (teammates inherit it). Off by default; see README → Security.
+3. ✅ **Persistent tool-cache volumes** — named volumes for `~/.npm`,
+   `~/.cargo/registry`, and pip's cache. The box stays `--rm`-disposable.
+4. ✅ **Git identity + `gh` auth forwarding** — `~/.gitconfig` and
+   `~/.config/gh` are mounted read-only when present; `gh` is installed in
+   the image. Borrow host identity, never store it.
+5. ✅ **ARM64 / Apple Silicon check** — `doctor` warns on image/host arch
+   mismatch (qemu emulation); `--gpus` passthrough shipped alongside.
 
 ## Next (medium effort)
 
-5. **Named boxes / one container per project** *(M, high)* — derive
+6. **Named boxes / one container per project** *(M, high)* — derive
    container name, tmux session, and Observer port from the workspace path
    (plus `--name` override) so two projects never share/steal one box.
    Removes the biggest documented footgun.
-6. **Credential isolation** *(M, high)* — mount only
+7. **Credential isolation** *(M, high)* — mount only
    `.credentials.json` + a minimal `.claude.json` into a per-box dir
    instead of all of `~/.claude` (which carries transcripts and every
    project path). Also fixes the Observer showing other projects'
    sessions.
-7. **Per-project config** *(M, high)* — optional `agentbox.json` (extra
+8. **Per-project config** *(M, high)* — optional `agentbox.json` (extra
    apt packages, setup commands, env, mounts, resource defaults) or a
    custom Dockerfile `FROM agentbox:latest`. Explicitly *not* full
    devcontainer.json compatibility.
-8. **Session git-branch safety net** *(M, med-high)* — opt-in: create
+9. **Session git-branch safety net** *(M, med-high)* — opt-in: create
    `agentbox/<timestamp>` branch on `up`, print a diff summary on `down`.
-9. **Podman support** *(M, med)* — detect `podman` when `docker` is
-   absent; rootless-by-default strengthens the isolation story.
-10. **Headless mode: `agentbox run "<prompt>"`** *(M, med)* — run
+10. **Podman support** *(M, med)* — detect `podman` when `docker` is
+    absent; rootless-by-default strengthens the isolation story.
+11. **Headless mode: `agentbox run "<prompt>"`** *(M, med)* — run
     `claude -p` in the box without tmux/TTY, stream output, exit with
     Claude's status. Makes agentbox scriptable for cron/CI.
 
 ## Later
 
-11. **Opt-in egress firewall (`--restrict-network`)** *(M-L, med-high)* —
+12. **Opt-in egress firewall (`--restrict-network`)** *(M-L, med-high)* —
     port Anthropic's devcontainer `init-firewall.sh` (default-deny outbound,
     allowlist api.anthropic.com/npm/GitHub; `NET_ADMIN` for init, then drop).
-12. **Observer: Agent-Teams hook feed** *(M, med)* — register
+13. **Observer: Agent-Teams hook feed** *(M, med)* — register
     `TeammateIdle`/`TaskCreated`/`TaskCompleted` hooks that POST to the
     Observer for an authoritative live task board instead of inferred
     JSONL activity.
-13. **ARM64 / Apple Silicon polish** *(S, med)* — `doctor` reports host
-    arch, `up` warns on image/host arch mismatch (qemu emulation is slow),
-    `--platform` pass-through.
-14. **`doctor`/`down` polish** *(S, low-med)* — sweep orphaned tmux
-    sessions on `down`; auto-pick the next free Observer port on `up`.
-15. **`--gpus` pass-through** *(S, low)* — thin mapping to
-    `docker run --gpus` (Linux/NVIDIA), consistent with `--memory`/`--cpus`.
+14. **`doctor`/`down` polish** *(S, low-med)* — auto-pick the next free
+    Observer port on `up` (pairs with named boxes, #6); `--platform`
+    pass-through for cross-arch builds.
 
 ## Non-goals
 
diff --git a/assets/Dockerfile b/assets/Dockerfile
index 77f980a..70d70a3 100644
--- a/assets/Dockerfile
+++ b/assets/Dockerfile
@@ -33,6 +33,15 @@ RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && rm -rf /var/lib/apt/lists/* \
     && node --version && npm --version
 
+# ── GitHub CLI (auth is NEVER baked in — ~/.config/gh is bind-mounted ro) ─────
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+        -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list \
+    && apt-get update && apt-get install -y --no-install-recommends gh \
+    && rm -rf /var/lib/apt/lists/* \
+    && gh --version
+
 # ── Global npm tools: Claude Code + tsx ───────────────────────────────────────
 # No auth baked in. Versions overridable for reproducible builds:
 #   docker build --build-arg CLAUDE_CODE_VERSION=2.1.180 --build-arg TSX_VERSION=4.19.2 …
@@ -47,6 +56,10 @@ RUN npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" "tsx@${TSX
 RUN userdel -r ubuntu 2>/dev/null || true \
     && useradd --create-home --shell /bin/bash --uid 1000 agent \
     && mkdir -p /agentbox /workspace \
+    # Pre-create the cache-volume mount points OWNED BY agent — a named
+    # volume materializing a missing dir would otherwise be root-owned and
+    # break npm/cargo/pip inside the box.
+    && mkdir -p /home/agent/.npm /home/agent/.cargo/registry /home/agent/.cache/pip /home/agent/.config \
     && chown -R agent:agent /home/agent /agentbox /workspace \
     && chmod 755 /agentbox
 
diff --git a/src/cli/config.ts b/src/cli/config.ts
index f00b5f6..5e3d082 100644
--- a/src/cli/config.ts
+++ b/src/cli/config.ts
@@ -46,6 +46,10 @@ export function resolveConfig(
   // Optional build network (e.g. "host"). Unset → Docker's default.
   const buildNetwork = str(flags.network) ?? env.DOCKER_NETWORK ?? undefined;
 
+  // Opt-in only — never default a permission bypass on.
+  const yolo = flags.yolo === true;
+  const gpus = str(flags.gpus);
+
   return {
     workspace: path.resolve(workspace),
     claudeDir: path.join(home, ".claude"),
@@ -57,6 +61,10 @@ export function resolveConfig(
     memory,
     cpus,
     buildNetwork,
+    yolo,
+    gpus,
+    gitconfigPath: path.join(home, ".gitconfig"),
+    ghConfigDir: path.join(home, ".config", "gh"),
     dockerfile: path.join(REPO_ROOT, "assets", "Dockerfile"),
     buildContext: path.join(REPO_ROOT, "assets"),
     observerAsset: path.join(REPO_ROOT, "assets", "observer.mjs"),
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 468d77d..7ac0eea 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -26,6 +26,10 @@ FLAGS
       --cpus <val>      Docker --cpus limit, e.g. 4             (env: CPUS)
       --port <n>        Observer web port (default 4317)
       --network <mode>  docker build --network (e.g. host)     (env: DOCKER_NETWORK)
+      --gpus <val>      docker run --gpus passthrough (e.g. all, device=0)
+      --yolo            Lead runs with --dangerously-skip-permissions
+                        (teammates inherit it). Opt-in; use only for
+                        workloads you trust.
       --no-cache        Force a clean image build (up / rebuild).
 
 ENV OVERRIDES (precedence: flag > env > default)
@@ -45,14 +49,18 @@ const PER_COMMAND: Record<string, string> = {
 
 USAGE
   agentbox up [--workspace <dir>] [--memory <val>] [--cpus <val>]
-              [--port <n>] [--network <mode>] [--no-cache]
+              [--port <n>] [--network <mode>] [--gpus <val>] [--yolo]
+              [--no-cache]
 
 Builds the image if it is missing, ensures the host mount sources exist,
-writes the tmux entry script, and runs the container interactively. If the
-container is already running, it reattaches to the existing tmux session
-instead of starting a second one. Pass --no-cache to force a clean rebuild.
-Pass --network host if the build can't reach the internet on the default
-bridge (runs build steps in the host network namespace).`,
+writes the tmux entry script, starts the container detached, and attaches
+your terminal to its tmux session. Detaching (Ctrl+b d) leaves the box
+running; if the container is already running, 'up' just reattaches. Your
+~/.gitconfig and ~/.config/gh are mounted read-only when present so agents
+can commit and use gh. npm/cargo/pip caches persist in named volumes.
+Pass --no-cache to force a clean rebuild, --network host if the build can't
+reach the internet on the default bridge, --yolo to let the lead (and its
+teammates) skip permission prompts — only for workloads you trust.`,
 
   shell: `agentbox shell — open a bash shell in the running box
 
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 6c09eb7..9fb8fa7 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -27,6 +27,8 @@ const KNOWN_FLAGS = new Set([
   "cpus",
   "port",
   "network",
+  "gpus",
+  "yolo",
   "no-cache",
   "help",
   "h",
@@ -103,9 +105,16 @@ export async function run(argv: string[]): Promise<number> {
 
   // Reattaching ignores per-invocation flags (the box is shared); make that
   // visible instead of silent.
-  const tuningFlagsGiven = ["workspace", "port", "memory", "cpus"].some(
-    (f) => typeof parsed.flags[f] === "string",
-  );
+  const tuningFlagsGiven =
+    ["workspace", "port", "memory", "cpus", "gpus"].some(
+      (f) => typeof parsed.flags[f] === "string",
+    ) || parsed.flags.yolo === true;
+
+  if (config.yolo && (parsed.command === "up" || parsed.command === "rebuild")) {
+    console.error(
+      "agentbox: --yolo — the Claude lead (and its teammates) will skip ALL permission prompts inside the box.",
+    );
+  }
 
   try {
     switch (parsed.command) {
@@ -272,6 +281,22 @@ async function cmdDoctor(config: AgentboxConfig): Promise<number> {
     line(false, `Image '${config.image}' — skipped (Docker unavailable)`);
   }
 
+  // Image/host architecture match — an emulated image (e.g. amd64 on Apple
+  // Silicon) works but is painfully slow under qemu. Soft warning.
+  if (imageOk) {
+    const imgArch = await safe(() => docker.imageArchitecture(config.image), undefined);
+    const hostArch = ({ x64: "amd64", arm64: "arm64" } as Record<string, string>)[
+      process.arch
+    ] ?? process.arch;
+    if (imgArch) {
+      line(
+        imgArch === hostArch,
+        `Image arch matches host: image ${imgArch}, host ${hostArch}` +
+          (imgArch === hostArch ? "" : "  (emulated — expect slow agents; rebuild on this machine)"),
+      );
+    }
+  }
+
   // Host mount sources.
   line(isDir(config.workspace), `Workspace dir exists: ${config.workspace}`);
   line(isDir(config.claudeDir), `Claude dir exists: ${config.claudeDir}`);
diff --git a/src/cli/parser.ts b/src/cli/parser.ts
index 105e46a..2ed1355 100644
--- a/src/cli/parser.ts
+++ b/src/cli/parser.ts
@@ -8,7 +8,7 @@
  */
 
 /** Long-form flags that consume a following value. */
-const VALUE_FLAGS = new Set(["workspace", "memory", "cpus", "port", "network"]);
+const VALUE_FLAGS = new Set(["workspace", "memory", "cpus", "port", "network", "gpus"]);
 
 export interface ParsedArgs {
   /** First positional, or "up" when none is supplied. */
diff --git a/src/docker/index.ts b/src/docker/index.ts
index ec8f97f..e2fce5a 100644
--- a/src/docker/index.ts
+++ b/src/docker/index.ts
@@ -16,10 +16,13 @@ import {
   type AgentboxConfig,
   type DockerModule,
   type TtySize,
+  CACHE_VOLUMES,
   CONTAINER_WORKSPACE,
   CONTAINER_CLAUDE_DIR,
   CONTAINER_CLAUDE_JSON,
   CONTAINER_ENTRY,
+  CONTAINER_GH_CONFIG,
+  CONTAINER_GITCONFIG,
   CONTAINER_OBSERVER,
 } from "../types.ts";
 
@@ -89,6 +92,98 @@ async function ok(args: string[]): Promise<boolean> {
   return code === 0;
 }
 
+function isFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the full `docker run` argv. Exported (and pure — host-fs facts are
+ * injected via `present`) so tests can assert the exact argv without Docker.
+ *
+ * Detached (-d): the entry script — not a tmux attach client — is PID 1, so
+ * detaching a client can never tear the sandbox down. Attaching is a separate
+ * `docker exec` (execAttach).
+ */
+export function buildRunArgs(
+  config: AgentboxConfig,
+  tty: TtySize,
+  present: { gitconfig: boolean; ghConfig: boolean },
+): string[] {
+  const args = [
+    "run",
+    "-d",
+    "--rm",
+    "--name",
+    config.containerName,
+    // ── bind mounts ──────────────────────────────────────────────────────
+    "-v",
+    `${config.workspace}:${CONTAINER_WORKSPACE}`,
+    "-v",
+    `${config.claudeDir}:${CONTAINER_CLAUDE_DIR}`,
+    "-v",
+    `${config.claudeJson}:${CONTAINER_CLAUDE_JSON}`,
+    "-v",
+    `${config.entryScriptPath}:${CONTAINER_ENTRY}`,
+    "-v",
+    `${config.observerAsset}:${CONTAINER_OBSERVER}`,
+  ];
+
+  // ── host identity, read-only, only when present (git commits + gh auth) ──
+  if (present.gitconfig) {
+    args.push("-v", `${config.gitconfigPath}:${CONTAINER_GITCONFIG}:ro`);
+  }
+  if (present.ghConfig) {
+    args.push("-v", `${config.ghConfigDir}:${CONTAINER_GH_CONFIG}:ro`);
+  }
+
+  // ── persistent tool caches (named volumes; the box itself stays --rm) ───
+  for (const [volume, target] of CACHE_VOLUMES) {
+    args.push("-v", `${volume}:${target}`);
+  }
+
+  args.push(
+    // ── published observer port (loopback only — never expose to the LAN) ─
+    "-p",
+    `127.0.0.1:${config.observerPort}:${config.observerPort}`,
+    // ── resource limits ─────────────────────────────────────────────────
+    "--memory",
+    config.memory,
+    "--cpus",
+    config.cpus,
+  );
+
+  if (config.gpus) {
+    args.push("--gpus", config.gpus);
+  }
+
+  args.push(
+    // ── env ─────────────────────────────────────────────────────────────
+    "-e",
+    `OBSERVER_PORT=${config.observerPort}`,
+    "-e",
+    `COLUMNS=${tty.cols}`,
+    "-e",
+    `LINES=${tty.rows}`,
+    config.image,
+    // Launch via bash so a missing execute bit never blocks startup.
+    "bash",
+    CONTAINER_ENTRY,
+  );
+  return args;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Module implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -209,48 +304,10 @@ export const docker: DockerModule = {
   },
 
   async runContainer(config: AgentboxConfig, tty: TtySize): Promise<number> {
-    // Detached (-d): the entry script — not a tmux attach client — is PID 1,
-    // so detaching a client can never tear the sandbox down. Attaching is a
-    // separate `docker exec` (execAttach).
-    const args = [
-      "run",
-      "-d",
-      "--rm",
-      "--name",
-      config.containerName,
-      // ── bind mounts ──────────────────────────────────────────────────────
-      "-v",
-      `${config.workspace}:${CONTAINER_WORKSPACE}`,
-      "-v",
-      `${config.claudeDir}:${CONTAINER_CLAUDE_DIR}`,
-      "-v",
-      `${config.claudeJson}:${CONTAINER_CLAUDE_JSON}`,
-      "-v",
-      `${config.entryScriptPath}:${CONTAINER_ENTRY}`,
-      "-v",
-      `${config.observerAsset}:${CONTAINER_OBSERVER}`,
-      // ── published observer port (loopback only — never expose to the LAN) ─
-      "-p",
-      `127.0.0.1:${config.observerPort}:${config.observerPort}`,
-      // ── resource limits ─────────────────────────────────────────────────
-      "--memory",
-      config.memory,
-      "--cpus",
-      config.cpus,
-      // ── env ─────────────────────────────────────────────────────────────
-      "-e",
-      `OBSERVER_PORT=${config.observerPort}`,
-      "-e",
-      `COLUMNS=${tty.cols}`,
-      "-e",
-      `LINES=${tty.rows}`,
-    ];
-    args.push(
-      config.image,
-      // Launch via bash so a missing execute bit never blocks startup.
-      "bash",
-      CONTAINER_ENTRY,
-    );
+    const args = buildRunArgs(config, tty, {
+      gitconfig: isFile(config.gitconfigPath),
+      ghConfig: isDir(config.ghConfigDir),
+    });
     return inherit(args);
   },
 
@@ -269,4 +326,16 @@ export const docker: DockerModule = {
   async execOk(containerName: string, command: string[]): Promise<boolean> {
     return ok(["exec", containerName, ...command]);
   },
+
+  async imageArchitecture(image: string): Promise<string | undefined> {
+    const { code, stdout } = await capture([
+      "image",
+      "inspect",
+      "--format",
+      "{{.Architecture}}",
+      image,
+    ]);
+    const arch = stdout.trim();
+    return code === 0 && arch.length > 0 ? arch : undefined;
+  },
 };
diff --git a/src/session/index.ts b/src/session/index.ts
index 6038932..be39c5f 100644
--- a/src/session/index.ts
+++ b/src/session/index.ts
@@ -80,9 +80,11 @@ function buildEntryScript(config: AgentboxConfig, tty: TtySize): string {
   // `--teammate-mode tmux` is required for teammates to appear as split
   // panes: since Claude Code v2.1.179 the default teammateMode is
   // "in-process", which silently disables the split-pane layout agentbox is
-  // built around.
+  // built around. --yolo opts into skipping permission prompts (teammates
+  // inherit the lead's permission mode).
   const leadCmd =
-    "export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; claude --teammate-mode tmux";
+    "export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; claude --teammate-mode tmux" +
+    (config.yolo ? " --dangerously-skip-permissions" : "");
   // Command run in the `observer` window: the dashboard web server.
   const observerCmd = `OBSERVER_PORT=${observerPort} node ${shSingleQuote(
     CONTAINER_OBSERVER,
diff --git a/src/types.ts b/src/types.ts
index 5011ab9..f0916fc 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -28,6 +28,20 @@ export const CONTAINER_CLAUDE_JSON = "/home/agent/.claude.json";
 export const CONTAINER_ENTRY = "/agentbox/entry.sh";
 /** Observer server (bundled asset) bind-mounted to this path. */
 export const CONTAINER_OBSERVER = "/agentbox/observer.mjs";
+/** Host git identity, mounted read-only (only when present on the host). */
+export const CONTAINER_GITCONFIG = "/home/agent/.gitconfig";
+/** Host gh CLI auth, mounted read-only (only when present on the host). */
+export const CONTAINER_GH_CONFIG = "/home/agent/.config/gh";
+
+/**
+ * Named Docker volumes for tool caches: the box stays --rm-disposable, but
+ * npm/cargo/pip downloads survive between boxes (kills the cold-start tax).
+ */
+export const CACHE_VOLUMES: ReadonlyArray<readonly [volume: string, target: string]> = [
+  ["agentbox-npm-cache", "/home/agent/.npm"],
+  ["agentbox-cargo-registry", "/home/agent/.cargo/registry"],
+  ["agentbox-pip-cache", "/home/agent/.cache/pip"],
+];
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Config schema. Built by cli.resolveConfig() from env + flags + defaults.
@@ -58,6 +72,24 @@ export interface AgentboxConfig {
    * Unset → Docker's default build network. env: DOCKER_NETWORK / flag: --network.
    */
   buildNetwork?: string;
+  /**
+   * Launch the Claude lead with --dangerously-skip-permissions (teammates
+   * inherit it). Opt-in via --yolo — the disposable, resource-capped box is
+   * the environment that flag exists for, but it stays off by default.
+   */
+  yolo: boolean;
+  /** Optional `docker run --gpus` value (e.g. "all", "device=0"). flag: --gpus. */
+  gpus?: string;
+  /**
+   * Host ~/.gitconfig candidate path. Mounted READ-ONLY into the container
+   * (git identity reuse) only if it exists at run time.
+   */
+  gitconfigPath: string;
+  /**
+   * Host ~/.config/gh candidate dir. Mounted READ-ONLY into the container
+   * (gh CLI auth reuse) only if it exists at run time.
+   */
+  ghConfigDir: string;
   /** Path to the Dockerfile (assets/Dockerfile). */
   dockerfile: string;
   /** Build context dir for `docker build` (the assets dir). */
@@ -129,6 +161,12 @@ export interface DockerModule {
    * it exited 0 (used to poll tmux session readiness after `runContainer`).
    */
   execOk(containerName: string, command: string[]): Promise<boolean>;
+  /**
+   * The local image's Architecture (e.g. "amd64", "arm64"), or undefined if
+   * the image is missing / docker is unavailable. Used by doctor to warn
+   * about emulated (slow) image/host arch mismatches.
+   */
+  imageArchitecture(image: string): Promise<string | undefined>;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/tests/config.test.ts b/tests/config.test.ts
index 881077d..aa71e61 100644
--- a/tests/config.test.ts
+++ b/tests/config.test.ts
@@ -81,6 +81,20 @@ test("buildNetwork: flag > env, unset → undefined", () => {
   );
 });
 
+test("yolo is opt-in only (boolean flag), gpus passes through", () => {
+  assert.equal(resolveConfig(emptyEnv(), {}).yolo, false);
+  assert.equal(resolveConfig(emptyEnv(), { yolo: true }).yolo, true);
+  assert.equal(resolveConfig(emptyEnv(), {}).gpus, undefined);
+  assert.equal(resolveConfig(emptyEnv(), { gpus: "all" }).gpus, "all");
+});
+
+test("git identity / gh auth candidate paths default under home", () => {
+  const home = os.homedir();
+  const c = resolveConfig(emptyEnv(), {});
+  assert.equal(c.gitconfigPath, path.join(home, ".gitconfig"));
+  assert.equal(c.ghConfigDir, path.join(home, ".config", "gh"));
+});
+
 test("claude paths default under the home directory", () => {
   const home = os.homedir();
   const c = resolveConfig(emptyEnv(), {});
diff --git a/tests/docker.test.ts b/tests/docker.test.ts
new file mode 100644
index 0000000..00c55d4
--- /dev/null
+++ b/tests/docker.test.ts
@@ -0,0 +1,113 @@
+/**
+ * Tests for src/docker/index.ts — buildRunArgs, the pure `docker run` argv
+ * builder. Host-filesystem facts (gitconfig / gh config presence) are
+ * injected, so these tests need no Docker daemon and no real files.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildRunArgs } from "../src/docker/index.ts";
+import {
+  CACHE_VOLUMES,
+  CONTAINER_ENTRY,
+  CONTAINER_GH_CONFIG,
+  CONTAINER_GITCONFIG,
+  CONTAINER_WORKSPACE,
+  type AgentboxConfig,
+  type TtySize,
+} from "../src/types.ts";
+
+function baseConfig(over: Partial<AgentboxConfig> = {}): AgentboxConfig {
+  return {
+    workspace: "/home/u/proj",
+    claudeDir: "/home/u/.claude",
+    claudeJson: "/home/u/.claude.json",
+    image: "agentbox:latest",
+    containerName: "agentbox",
+    sessionName: "agentbox",
+    observerPort: 4317,
+    memory: "4g",
+    cpus: "4",
+    yolo: false,
+    gitconfigPath: "/home/u/.gitconfig",
+    ghConfigDir: "/home/u/.config/gh",
+    dockerfile: "/repo/assets/Dockerfile",
+    buildContext: "/repo/assets",
+    observerAsset: "/repo/assets/observer.mjs",
+    entryScriptPath: "/tmp/agentbox-1000/entry.sh",
+    ...over,
+  };
+}
+
+const TTY: TtySize = { cols: 120, rows: 40 };
+const NONE = { gitconfig: false, ghConfig: false };
+
+/** The value following a given -v/-p/... occurrence of `flag`. */
+function valuesOf(args: string[], flag: string): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length - 1; i++) {
+    if (args[i] === flag) out.push(args[i + 1]);
+  }
+  return out;
+}
+
+test("runs detached (-d), never interactive: the entry script must be PID 1", () => {
+  const args = buildRunArgs(baseConfig(), TTY, NONE);
+  assert.ok(args.includes("-d"));
+  assert.ok(!args.includes("-it"));
+});
+
+test("mounts workspace, claude dir/json, entry script and observer", () => {
+  const mounts = valuesOf(buildRunArgs(baseConfig(), TTY, NONE), "-v");
+  assert.ok(mounts.includes(`/home/u/proj:${CONTAINER_WORKSPACE}`));
+  assert.ok(mounts.includes("/home/u/.claude:/home/agent/.claude"));
+  assert.ok(mounts.includes("/home/u/.claude.json:/home/agent/.claude.json"));
+  assert.ok(mounts.includes(`/tmp/agentbox-1000/entry.sh:${CONTAINER_ENTRY}`));
+});
+
+test("publishes the observer port on loopback ONLY", () => {
+  const ports = valuesOf(buildRunArgs(baseConfig({ observerPort: 5000 }), TTY, NONE), "-p");
+  assert.deepEqual(ports, ["127.0.0.1:5000:5000"]);
+});
+
+test("mounts the tool-cache named volumes", () => {
+  const mounts = valuesOf(buildRunArgs(baseConfig(), TTY, NONE), "-v");
+  for (const [volume, target] of CACHE_VOLUMES) {
+    assert.ok(mounts.includes(`${volume}:${target}`), `${volume} must be mounted`);
+  }
+});
+
+test("mounts git identity and gh auth READ-ONLY, and only when present", () => {
+  const none = valuesOf(buildRunArgs(baseConfig(), TTY, NONE), "-v");
+  assert.ok(!none.some((m) => m.includes(".gitconfig")));
+  assert.ok(!none.some((m) => m.includes("/gh")));
+
+  const both = valuesOf(
+    buildRunArgs(baseConfig(), TTY, { gitconfig: true, ghConfig: true }),
+    "-v",
+  );
+  assert.ok(both.includes(`/home/u/.gitconfig:${CONTAINER_GITCONFIG}:ro`));
+  assert.ok(both.includes(`/home/u/.config/gh:${CONTAINER_GH_CONFIG}:ro`));
+});
+
+test("applies resource limits and env", () => {
+  const args = buildRunArgs(baseConfig({ memory: "8g", cpus: "2" }), TTY, NONE);
+  assert.deepEqual(valuesOf(args, "--memory"), ["8g"]);
+  assert.deepEqual(valuesOf(args, "--cpus"), ["2"]);
+  const env = valuesOf(args, "-e");
+  assert.ok(env.includes("OBSERVER_PORT=4317"));
+  assert.ok(env.includes("COLUMNS=120"));
+  assert.ok(env.includes("LINES=40"));
+});
+
+test("--gpus is passed through only when set", () => {
+  assert.deepEqual(valuesOf(buildRunArgs(baseConfig(), TTY, NONE), "--gpus"), []);
+  assert.deepEqual(
+    valuesOf(buildRunArgs(baseConfig({ gpus: "all" }), TTY, NONE), "--gpus"),
+    ["all"],
+  );
+});
+
+test("image and entry command come last: … <image> bash /agentbox/entry.sh", () => {
+  const args = buildRunArgs(baseConfig(), TTY, NONE);
+  assert.deepEqual(args.slice(-3), ["agentbox:latest", "bash", CONTAINER_ENTRY]);
+});
diff --git a/tests/session.test.ts b/tests/session.test.ts
index 3f33414..123983c 100644
--- a/tests/session.test.ts
+++ b/tests/session.test.ts
@@ -24,6 +24,9 @@ function baseConfig(over: Partial<AgentboxConfig> = {}): AgentboxConfig {
     observerPort: 4317,
     memory: "4g",
     cpus: "4",
+    yolo: false,
+    gitconfigPath: "/home/u/.gitconfig",
+    ghConfigDir: "/home/u/.config/gh",
     dockerfile: "/repo/assets/Dockerfile",
     buildContext: "/repo/assets",
     observerAsset: "/repo/assets/observer.mjs",
@@ -51,6 +54,13 @@ test("launches the lead with --teammate-mode tmux (split panes are no longer the
   assert.match(s, /claude --teammate-mode tmux/);
 });
 
+test("--yolo adds --dangerously-skip-permissions to the lead; default does not", () => {
+  const on = session.buildEntryScript(baseConfig({ yolo: true }), TTY);
+  assert.match(on, /--dangerously-skip-permissions/);
+  const off = session.buildEntryScript(baseConfig(), TTY);
+  assert.doesNotMatch(off, /--dangerously-skip-permissions/);
+});
+
 test("creates the observer in its OWN window (not a pane in main)", () => {
   const s = session.buildEntryScript(baseConfig(), TTY);
   // A dedicated `new-window -n observer` — never `split-window`.

From 51c1d77e8278427242c3befd71457b2eaf2e87b5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 30 Jul 2026 06:20:32 +0000
Subject: [PATCH 5/6] =?UTF-8?q?fix:=20address=20CodeRabbit=20review=20?=
 =?UTF-8?q?=E2=80=94=20release-workflow=20hardening,=20container=20lifecyc?=
 =?UTF-8?q?le,=20remaining=20edge=20cases?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Release workflow:
- persist-credentials: false on every checkout (ci.yml, release.yml).
- release.yml: verify the pushed tag matches package.json's version before
  publishing; run the npm-pack tarball smoke test as a gate before publish;
  drop dependency caching (a poisoned cache must never influence what gets
  published — CI keeps caching, only the sensitive publish workflow doesn't).
- RELEASING.md: stop implying npm Trusted Publishing is configured — the
  workflow authenticates with NODE_AUTH_TOKEN only.
- Dockerfile: pin CLAUDE_CODE_VERSION/TSX_VERSION defaults to reviewed exact
  versions instead of `latest`, so a plain rebuild is reproducible.
- Launcher: drop the shell-based global-tsx-on-PATH fallback — it forwarded
  raw argv through a shell (cmd.exe metacharacter risk on Windows); tsx is a
  runtime dependency now, so a missing local install is a clear error instead.

Container lifecycle:
- Stop using --rm: a container that exits early (entry-script crash) now
  stays around for `docker logs` to inspect instead of vanishing instantly.
  `up` removes a stale stopped container before starting fresh (already
  implemented); `down` still removes it explicitly; waitForSession also
  gives up early if the container itself exits, instead of polling the full
  timeout.
- Reattaching now reports the RUNNING container's actual --yolo state via a
  container label, instead of echoing the current invocation's flag (which
  is ignored on reattach and could claim the wrong thing in either direction).

Input handling:
- A value flag given with no value (e.g. trailing --gpus) is now a hard
  error instead of silently doing nothing.
- validateConfig (+ workspace-must-exist) now gates only up/rebuild — down/
  shell stay usable with a currently-invalid MEM/CPUS/workspace. doctor
  reports every validateConfig problem explicitly in its checklist instead
  of a narrower, separate ad hoc port check.

Other fixes:
- ~/.claude.json symlinked to a directory is now a clear error (previously
  it passed through silently and Docker mounted a directory).
- The entry-script temp directory's ownership/permissions are verified after
  creation (mkdirSync's mode arg is a no-op on a pre-existing dir), closing
  a race where another local user could pre-create it.
- CODE_OF_CONDUCT: separate conduct-report contact from the security channel.
- Doc wording fixes (CHANGELOG credential-mount phrasing; all --rm mentions
  updated to match the new lifecycle).

Tests: 76 → 87, all green; typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfjQjysq5JF7gQCJB3RQtP
---
 .github/workflows/ci.yml      |  4 ++
 .github/workflows/release.yml | 42 ++++++++++++++++++--
 CHANGELOG.md                  | 45 +++++++++++++++++++--
 CODE_OF_CONDUCT.md            | 10 +++--
 CONTRACT.md                   | 20 ++++++----
 README.md                     | 13 ++++---
 RELEASING.md                  | 15 +++++--
 ROADMAP.md                    |  3 +-
 SECURITY.md                   | 13 ++++++-
 assets/Dockerfile             |  9 +++--
 bin/agentbox.mjs              | 46 ++++++++++------------
 src/cli/index.ts              | 73 ++++++++++++++++++++++++++---------
 src/cli/parser.ts             | 23 ++++++++++-
 src/docker/index.ts           | 43 +++++++++++++++++----
 src/session/index.ts          | 33 +++++++++++++---
 src/types.ts                  | 20 ++++++++--
 tests/cli.test.ts             | 35 +++++++++++++++++
 tests/docker.test.ts          | 15 +++++++
 tests/observer.test.ts        | 30 +++++++++++++-
 tests/parser.test.ts          | 22 ++++++++++-
 tests/session.test.ts         | 32 +++++++++++++++
 21 files changed, 444 insertions(+), 102 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cb52dd2..d575301 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,6 +23,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Setup Node ${{ matrix.node }}
         uses: actions/setup-node@v4
@@ -45,6 +47,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Setup Node 22
         uses: actions/setup-node@v4
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 088af25..e8cf71a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -9,31 +9,65 @@ permissions:
 
 jobs:
   checks:
-    name: typecheck & test
+    name: typecheck, test & tag/version match
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: actions/setup-node@v4
         with:
           node-version: "22"
-          cache: npm
       - run: npm ci
       - run: npm run typecheck
       - run: npm test
 
+      - name: Tag must match package.json version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(node -p "require('./package.json').version")"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag v$tag does not match package.json version $pkg — refusing to publish a mismatched release."
+            exit 1
+          fi
+
+  pack-smoke:
+    name: npm pack smoke test
+    needs: checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+
+      - name: Pack tarball and run it as an end user would
+        run: |
+          npm pack --pack-destination "$RUNNER_TEMP"
+          mkdir -p "$RUNNER_TEMP/consumer"
+          cd "$RUNNER_TEMP/consumer"
+          npm init -y >/dev/null
+          npm install "$RUNNER_TEMP"/liohtml-agentbox-*.tgz
+          npx agentbox --help
+          npx agentbox doctor 2>&1 | grep -q "agentbox doctor"
+
   publish:
     name: npm publish (provenance)
-    needs: checks
+    needs: pack-smoke
     runs-on: ubuntu-latest
     permissions:
       contents: read
       id-token: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: actions/setup-node@v4
         with:
           node-version: "22"
-          cache: npm
           registry-url: "https://registry.npmjs.org"
       - run: npm ci
       - run: npm publish --provenance --access public
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ff076c2..5ceb3fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,41 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Fixed (review follow-up)
+- The container no longer runs with `--rm`: a container that exits early
+  (entry-script crash) now stays around for `docker logs` to inspect instead
+  of vanishing immediately. `up` removes a stale stopped container before
+  starting fresh; `down` still removes it explicitly; `waitForSession` now
+  also gives up early if the container itself exits instead of polling out
+  the full timeout.
+- Reattaching now reports the **running container's actual** `--yolo` state
+  (via a container label) instead of echoing back the current invocation's
+  flag, which is ignored on reattach and could previously claim the wrong
+  thing in either direction.
+- A value flag given with no value (e.g. a trailing `--gpus`) is now a hard
+  error instead of silently being dropped.
+- `validateConfig` (and the "workspace must exist" check) now only gate
+  `up`/`rebuild`; `shell`/`down` stay usable even with a currently-invalid
+  `MEM`/`CPUS`/workspace. `doctor` now reports every `validateConfig`
+  problem explicitly instead of a separate, narrower ad hoc port check.
+- `~/.claude.json` symlinked to a directory is now a clear error (previously
+  it silently passed through and Docker mounted a directory).
+- The generated entry script's temp directory is verified (owner uid + no
+  group/other permissions) after creation, closing a race where another
+  local user could pre-create it to intercept the mounted script.
+- Launcher: dropped the shell-based global-`tsx`-on-PATH fallback (it forwarded
+  raw argv through a shell, letting metacharacters be interpreted on
+  Windows); `tsx` is a runtime dependency now, so a missing local install is
+  a clear, actionable error instead.
+- CI/release workflows: `persist-credentials: false` on all checkouts; the
+  release workflow now verifies the pushed tag matches `package.json`'s
+  version, runs the `npm pack` tarball smoke test as a publish gate, and
+  disables dependency caching (a compromised cache must never influence what
+  gets published).
+- Dockerfile: `CLAUDE_CODE_VERSION`/`TSX_VERSION` build-arg defaults are now
+  pinned exact versions instead of `latest`, so a plain rebuild is
+  reproducible; override the args for an intentional upgrade.
+
 ### Fixed
 - **Detaching no longer destroys the sandbox.** The container now runs
   detached with the entry script as PID 1 and your terminal attaches via
@@ -56,12 +91,14 @@ adheres to [Semantic Versioning](https://semver.org/).
   `--dangerously-skip-permissions` (teammates inherit it). Opt-in per
   invocation, never the default — see README → Security & trust.
 - **Persistent tool-cache volumes**: named Docker volumes for `~/.npm`,
-  `~/.cargo/registry` and pip's cache. Boxes stay `--rm`-disposable; only
-  downloaded packages survive.
+  `~/.cargo/registry` and pip's cache. The box itself stays disposable
+  (`down` / `up`'s stale-container cleanup); only downloaded packages
+  survive.
 - **Git identity + `gh` auth forwarding**: `~/.gitconfig` and `~/.config/gh`
   are bind-mounted read-only when present, and the `gh` CLI is installed in
-  the image — agents can commit and open PRs as you, without any credential
-  ever entering the image.
+  the image — agents can commit and open PRs as you. Credentials are never
+  baked into the image, but note they *are* readable at runtime by anything
+  running inside the container, same as the existing Claude credential mount.
 - **`--gpus` passthrough** to `docker run --gpus` (e.g. `all`, `device=0`).
 - `doctor` warns when the local image architecture doesn't match the host
   (emulated images are painfully slow under qemu).
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 2ed53ca..6a0a015 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -30,9 +30,13 @@ Examples of unacceptable behavior:
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the maintainers via a GitHub issue (for non-sensitive matters) or
-privately via [GitHub Security Advisories](https://github.com/Liohtml/agentbox/security/advisories/new).
-All complaints will be reviewed and investigated promptly and fairly.
+reported via a GitHub issue (for non-sensitive matters) or, for anything you'd
+rather not post publicly, by contacting the maintainer directly:
+[@Liohtml](https://github.com/Liohtml). All complaints will be reviewed and
+investigated promptly and fairly.
+
+(Security vulnerabilities have their own private channel — see
+[SECURITY.md](SECURITY.md); please don't use it for conduct reports.)
 
 For the full text including enforcement guidelines, see the
 [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
diff --git a/CONTRACT.md b/CONTRACT.md
index e7719ab..36ac775 100644
--- a/CONTRACT.md
+++ b/CONTRACT.md
@@ -45,6 +45,8 @@ Invoked as `agentbox <command> [flags]` (via `bin/agentbox.mjs` or
 - `--cpus <val>` — docker cpu limit, e.g. `4` (also env `CPUS`).
 - `--port <n>` — observer port (default 4317).
 - `--network <mode>` — `docker build --network` mode, e.g. `host` (also env `DOCKER_NETWORK`). Unset → Docker's default build network.
+- `--gpus <val>` — `docker run --gpus` passthrough, e.g. `all` (Linux/NVIDIA).
+- `--yolo` — launch the lead with `--dangerously-skip-permissions` (teammates inherit it). Opt-in only; recorded as a `agentbox.yolo` container label so reattach can report the box's actual mode.
 - `--no-cache` — (rebuild/up) force a clean image build.
 
 ### Env overrides (precedence: **flag > env > default**)
@@ -105,9 +107,10 @@ export const session: SessionModule; // see src/types.ts
 | `config.ghConfigDir` *(if present)*   | `/home/agent/.config/gh` | **read-only** — gh CLI auth reuse  |
 
 Named cache volumes (`CACHE_VOLUMES` in types.ts): `agentbox-npm-cache`,
-`agentbox-cargo-registry`, `agentbox-pip-cache` → the box stays `--rm`,
-only tool downloads persist. Host identity mounts are read-only, existence-
-gated, and NEVER copied into the image.
+`agentbox-cargo-registry`, `agentbox-pip-cache` → the box itself stays
+disposable (removed via `down`, or replaced by `up`'s stale-container
+cleanup — see §6.7), only tool downloads persist. Host identity mounts are
+read-only, existence-gated, and NEVER copied into the image.
 
 - Publish `-p <observerPort>:<observerPort>`.
 - Apply `--memory <config.memory>` and `--cpus <config.cpus>`.
@@ -132,10 +135,13 @@ gated, and NEVER copied into the image.
    split-pane layout.
 6. Read the real TTY size via `stty size` so tmux isn't stuck at 80×24.
 7. **The tmux attach client must NEVER be container PID 1.** The container
-   runs detached (`docker run -d`); the entry script sets the session up and
-   idles while it exists, and clients attach via `docker exec … tmux attach`.
-   Otherwise `C-b d` (detach) exits PID 1, kills every agent, and `--rm`
-   deletes the container.
+   runs detached (`docker run -d`, deliberately NOT `--rm`); the entry script
+   sets the session up and idles while it exists, and clients attach via
+   `docker exec … tmux attach`. Otherwise `C-b d` (detach) exits PID 1 and
+   kills every agent. Not using `--rm` means a container that exits early
+   (entry-script crash) stays inspectable via `docker logs`; `up` removes a
+   stale stopped container before starting fresh, and `down` removes it
+   explicitly.
 
 ---
 
diff --git a/README.md b/README.md
index 2ab9ab1..6fb3b70 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,7 @@ node bin/agentbox.mjs doctor
 node bin/agentbox.mjs up --workspace ~/code/myapp
 ```
 
-First run builds the image (a few minutes). Later runs reuse it and start instantly. When you exit, the container is removed (`--rm`); your work and credentials persist on the host.
+First run builds the image (a few minutes). Later runs reuse it and start instantly. Your work and credentials always live on the host (bind-mounted, never baked in) — the container itself is disposable: `agentbox down` removes it explicitly, and `agentbox up` cleans up a leftover stopped container automatically before starting a fresh one.
 
 ### Install it on your PATH (recommended)
 
@@ -124,7 +124,7 @@ WORKSPACE=~/code/myapp MEM=8g CPUS=6 agentbox up --port 5000
 1. **Builds the image** from `assets/Dockerfile` if it's missing — Ubuntu 24.04 with Node 22, Python 3, Rust (rustup), git, tmux, and Claude Code + `tsx` installed globally. It runs as the non-root user **`agent`** and never contains credentials.
 2. **Prepares the host bind mounts** (below), touching `~/.claude.json` first so Docker mounts a *file*, not a directory.
 3. **Generates a tmux entry script** sized to your real terminal (read via `stty size`, so tmux isn't stuck at 80×24).
-4. **Runs the container detached** (`docker run -d --rm`, with `--memory`/`--cpus` limits and the Observer port published), launching the entry script via **`bash /agentbox/entry.sh`** — using `bash` so a missing execute bit can never block startup. The entry script sets the tmux session up and stays alive as PID 1; agentbox then attaches your terminal via `docker exec … tmux attach`. Detaching (`Ctrl+b d`) only ends that client — the box, the lead, and all teammates keep running. If the container is already running, `up` just reattaches.
+4. **Runs the container detached** (`docker run -d`, with `--memory`/`--cpus` limits and the Observer port published), launching the entry script via **`bash /agentbox/entry.sh`** — using `bash` so a missing execute bit can never block startup. The entry script sets the tmux session up and stays alive as PID 1; agentbox then attaches your terminal via `docker exec … tmux attach`. Detaching (`Ctrl+b d`) only ends that client — the box, the lead, and all teammates keep running. If the container is already running, `up` just reattaches. Deliberately not `--rm`: if the entry script fails, the container stays around so `docker logs` can show you why; agentbox removes any stale stopped container itself before the next `up`, and `agentbox down` removes it explicitly.
 
 ### Bind mounts (host → container)
 
@@ -141,8 +141,9 @@ WORKSPACE=~/code/myapp MEM=8g CPUS=6 agentbox up --port 5000
 Additionally, three **named Docker volumes** persist tool caches across boxes
 (`agentbox-npm-cache` → `~/.npm`, `agentbox-cargo-registry` → `~/.cargo/registry`,
 `agentbox-pip-cache` → `~/.cache/pip`). The box itself stays disposable
-(`--rm`); only downloaded packages survive, so fresh boxes skip the
-cold-start tax. Remove them any time with `docker volume rm`.
+(`agentbox down` / `up`'s stale-container cleanup); only downloaded packages
+survive, so fresh boxes skip the cold-start tax. Remove the caches any time
+with `docker volume rm`.
 
 ### The tmux layout
 
@@ -171,7 +172,7 @@ The `main` window starts the Claude Code lead with Agent Teams enabled. Just tal
 
 ## Security & trust
 
-agentbox isolates **resources** (CPU/memory caps, a throwaway `--rm` container, a non-root `agent` user) — but it is **not a security sandbox for untrusted code**. Two things to be clear about:
+agentbox isolates **resources** (CPU/memory caps, a disposable container, a non-root `agent` user) — but it is **not a security sandbox for untrusted code**. Two things to be clear about:
 
 - **Your host Claude credentials are mounted read-write.** `~/.claude` and `~/.claude.json` carry your OAuth token, the list of every project path you've opened, and full session transcripts under `~/.claude/projects`. Anything running inside the box can read or modify them. That includes `~/.claude/settings.json` and hooks — code in the box could plant a hook that your **host** Claude Code executes later, i.e. the mount is a container-to-host escape channel for untrusted workloads. Only run workloads you trust. (Narrowing this mount to just credentials is on the [roadmap](ROADMAP.md).)
 - **The container is a workbench, not a jail.** Treat it as a clean, disposable, resource-capped place for *your own* agentic workflows — not as a barrier against malicious code. (The Observer is published to `127.0.0.1` only, so its unauthenticated dashboard never leaks to the LAN.)
@@ -226,7 +227,7 @@ Baked into the implementation and the [contract](CONTRACT.md):
 3. **The Observer lives in its own window**, never a pane in `main` — Claude's tmux teammate mode only splits the lead's window into panes if that window is otherwise empty.
 4. **The entry script is launched via `bash`**, so a missing execute bit can't block startup.
 5. **TTY size is read with `stty size`** so tmux opens at your real terminal dimensions instead of the 80×24 default.
-6. **The tmux attach client is never container PID 1.** The container runs detached and your terminal attaches via `docker exec`, so `Ctrl+b d` detaches without tearing down the sandbox. (If the attach client were PID 1, a detach would kill every agent and `--rm` would delete the container.)
+6. **The tmux attach client is never container PID 1.** The container runs detached and your terminal attaches via `docker exec`, so `Ctrl+b d` detaches without tearing down the sandbox. (If the attach client were PID 1, a detach would kill every agent and stop the container outright.)
 7. **The lead is launched with `--teammate-mode tmux`** — since Claude Code v2.1.179 the default is `in-process`, which would silently disable the split-pane team layout agentbox is built around.
 
 ---
diff --git a/RELEASING.md b/RELEASING.md
index f1d6f5e..f7b9810 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -22,8 +22,10 @@ done from CI via the tag-triggered release workflow — not from a laptop.
    git push origin vX.Y.Z
    ```
 
-6. The `release.yml` workflow runs on the `v*` tag: it re-runs all checks and
-   publishes to npm with `--provenance --access public`.
+6. The `release.yml` workflow runs on the `v*` tag: it verifies the tag matches
+   `package.json`'s version, re-runs typecheck/test, runs the `npm pack`
+   tarball smoke test, then publishes to npm with
+   `--provenance --access public`. Any of those failing blocks the publish.
 7. **Create a GitHub Release** from the tag, pasting the changelog section.
 
 ## npm notes
@@ -31,6 +33,11 @@ done from CI via the tag-triggered release workflow — not from a laptop.
 - The package is published **scoped** as `@liohtml/agentbox` (the bare name
   `agentbox` is an npm security placeholder and cannot be claimed). The
   installed command is still `agentbox`.
-- Publishing requires the `NPM_TOKEN` repository secret (or npm Trusted
-  Publishing configured for this repo), plus `id-token: write` for provenance.
+- Publishing authenticates with the `NPM_TOKEN` repository secret
+  (`NODE_AUTH_TOKEN` in the workflow), plus `id-token: write` for provenance.
+  Migrating to npm Trusted Publishing (OIDC, no long-lived token) is a good
+  follow-up but isn't configured yet — don't assume it's active.
 - `prepublishOnly` re-runs typecheck + tests as a local safety net.
+- Dependency caching is deliberately **off** in the release workflow (unlike
+  CI): a compromised or poisoned npm/GitHub Actions cache must never be able
+  to influence what gets published.
diff --git a/ROADMAP.md b/ROADMAP.md
index 08d6aab..a5335f9 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -14,7 +14,8 @@ anything marked M/L effort.
 2. ✅ **`--yolo` flag** — opt-in `--dangerously-skip-permissions` for the
    lead (teammates inherit it). Off by default; see README → Security.
 3. ✅ **Persistent tool-cache volumes** — named volumes for `~/.npm`,
-   `~/.cargo/registry`, and pip's cache. The box stays `--rm`-disposable.
+   `~/.cargo/registry`, and pip's cache. The box itself stays disposable
+   (`down` / `up`'s stale-container cleanup).
 4. ✅ **Git identity + `gh` auth forwarding** — `~/.gitconfig` and
    `~/.config/gh` are mounted read-only when present; `gh` is installed in
    the image. Borrow host identity, never store it.
diff --git a/SECURITY.md b/SECURITY.md
index 822e35b..0ba666c 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -23,8 +23,17 @@ agentbox is a **workbench, not a jail**. By design:
   executes. In other words, for untrusted workloads this mount is a
   container-to-host escape channel. Only run workloads you trust.
   (Narrowing the mount to just credentials is on the roadmap.)
-- The container isolates *resources* (CPU/memory caps, `--rm`, non-root
-  `agent` user) — it is **not** a security boundary against malicious code.
+- The container isolates *resources* (CPU/memory caps, a disposable
+  container, non-root `agent` user) — it is **not** a security boundary
+  against malicious code.
+- `~/.gitconfig` and `~/.config/gh` are bind-mounted **read-only** when
+  present so agents can commit and open PRs as you. Read-only stops the
+  container from *modifying* them, but anything inside can still *read*
+  your `gh` token and use it — same trust model as the Claude credentials.
+- `--yolo` runs the lead (and every teammate) with
+  `--dangerously-skip-permissions` — no human checkpoint before an agent
+  acts. Combined with the mounts above, that means an agent can do anything
+  you can. Opt-in per invocation; never the default.
 - The Observer dashboard is unauthenticated by design; its port is published
   to `127.0.0.1` **only** and must never be exposed to the LAN.
 
diff --git a/assets/Dockerfile b/assets/Dockerfile
index 70d70a3..a1334f9 100644
--- a/assets/Dockerfile
+++ b/assets/Dockerfile
@@ -43,10 +43,11 @@ RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
     && gh --version
 
 # ── Global npm tools: Claude Code + tsx ───────────────────────────────────────
-# No auth baked in. Versions overridable for reproducible builds:
-#   docker build --build-arg CLAUDE_CODE_VERSION=2.1.180 --build-arg TSX_VERSION=4.19.2 …
-ARG CLAUDE_CODE_VERSION=latest
-ARG TSX_VERSION=latest
+# No auth baked in. Pinned defaults for reproducible builds; override for an
+# intentional upgrade:
+#   docker build --build-arg CLAUDE_CODE_VERSION=2.1.221 --build-arg TSX_VERSION=4.24.0 …
+ARG CLAUDE_CODE_VERSION=2.1.220
+ARG TSX_VERSION=4.23.1
 RUN npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" "tsx@${TSX_VERSION}" \
     && npm cache clean --force
 
diff --git a/bin/agentbox.mjs b/bin/agentbox.mjs
index 1dbbaf3..2b80aff 100644
--- a/bin/agentbox.mjs
+++ b/bin/agentbox.mjs
@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 /**
  * agentbox launcher. Runs the TypeScript CLI through tsx without a build step.
- * Works whether tsx is installed locally (node_modules) or globally on PATH.
  */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -10,35 +9,30 @@ import { dirname, resolve } from "node:path";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const entry = resolve(here, "..", "src", "index.ts");
-
-// Prefer the locally-installed tsx so a fresh clone (or the published
-// package, where tsx is a runtime dependency) works with no global tsx.
-// Invoke tsx's JS entry with the current node binary instead of the .bin
-// shim: no shell involved, so paths with spaces and cmd.exe metacharacters
-// can never break or inject (the .cmd shim needed shell:true on Windows).
-const isWin = process.platform === "win32";
 const localTsxCli = resolve(here, "..", "node_modules", "tsx", "dist", "cli.mjs");
-const useLocal = existsSync(localTsxCli);
 
-const child = useLocal
-  ? spawn(process.execPath, [localTsxCli, entry, ...process.argv.slice(2)], {
-      stdio: "inherit",
-      env: process.env,
-    })
-  : spawn("tsx", [entry, ...process.argv.slice(2)], {
-      stdio: "inherit",
-      env: process.env,
-      shell: isWin, // PATH fallback: a global tsx is a .cmd shim on Windows
-    });
+if (!existsSync(localTsxCli)) {
+  // tsx is a runtime dependency of agentbox (package.json), so this should
+  // always be present after install. No shell-based global-PATH fallback:
+  // that used to run `tsx` via a shell (required for the Windows .cmd shim),
+  // which forwarded raw argv through cmd.exe with no metacharacter escaping.
+  console.error(
+    "agentbox: 'tsx' is missing from node_modules (expected at " +
+      `${localTsxCli}).\n` +
+      "Run 'npm install' to reinstall agentbox's dependencies.",
+  );
+  process.exit(127);
+}
+
+// Invoke tsx's JS entry with the current node binary directly — no shell, so
+// paths with spaces are safe and no shell can interpret metacharacters in
+// forwarded argv.
+const child = spawn(process.execPath, [localTsxCli, entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env,
+});
 
 child.on("error", (err) => {
-  if (err && err.code === "ENOENT") {
-    console.error(
-      "agentbox: 'tsx' not found. Run 'npm install' in the agentbox repo, " +
-        "or install it globally: npm i -g tsx",
-    );
-    process.exit(127);
-  }
   console.error("agentbox:", err.message);
   process.exit(1);
 });
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 9fb8fa7..87167a4 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -9,7 +9,7 @@
  * modules. It owns NO docker/tmux logic itself — it only sequences calls.
  */
 import fs from "node:fs";
-import type { AgentboxConfig } from "../types.ts";
+import { type AgentboxConfig, LABEL_YOLO } from "../types.ts";
 import { docker } from "../docker/index.ts";
 import { session } from "../session/index.ts";
 import { parseArgs } from "./parser.ts";
@@ -71,6 +71,18 @@ export async function run(argv: string[]): Promise<number> {
     return 1;
   }
 
+  // A value flag given with no value (e.g. a trailing `--gpus`) must not
+  // silently fall back to "not requested" — that already burned --port/
+  // --memory/--cpus before validateConfig existed, and would otherwise still
+  // silently disable --gpus today.
+  if (parsed.missingValueFlags.length > 0) {
+    console.error(
+      `agentbox: flag${parsed.missingValueFlags.length > 1 ? "s" : ""} require a value: ` +
+        parsed.missingValueFlags.map((f) => `--${f}`).join(", "),
+    );
+    return 1;
+  }
+
   // Commands take no extra positionals (only `help <command>` does).
   if (parsed.positionals.length > 1) {
     console.error(
@@ -83,8 +95,11 @@ export async function run(argv: string[]): Promise<number> {
   const forceNoCache = parsed.flags["no-cache"] === true;
 
   // Fail fast on invalid input — before any (potentially minutes-long) Docker
-  // work. `doctor` is exempt: it reports problems as its ✓/✗ checklist.
-  if (parsed.command !== "doctor") {
+  // work. Scoped to up/rebuild only: `shell`/`down` must stay usable to tear
+  // down or inspect a box even if MEM/CPUS/workspace are currently bogus, and
+  // `doctor` reports the same validateConfig() problems as part of its
+  // checklist instead of hard-failing here.
+  if (parsed.command === "up" || parsed.command === "rebuild") {
     const problems = validateConfig(config);
     if (problems.length > 0) {
       for (const p of problems) console.error(`agentbox: ${p}`);
@@ -110,12 +125,6 @@ export async function run(argv: string[]): Promise<number> {
       (f) => typeof parsed.flags[f] === "string",
     ) || parsed.flags.yolo === true;
 
-  if (config.yolo && (parsed.command === "up" || parsed.command === "rebuild")) {
-    console.error(
-      "agentbox: --yolo — the Claude lead (and its teammates) will skip ALL permission prompts inside the box.",
-    );
-  }
-
   try {
     switch (parsed.command) {
       case "up":
@@ -176,16 +185,25 @@ async function cmdUp(
   if (running) {
     if (opts.warnOnReattach) {
       console.error(
-        `agentbox: note — the box is already running; --workspace/--port/--memory/--cpus are ignored on reattach.\n` +
+        `agentbox: note — the box is already running; --workspace/--port/--memory/--cpus/--gpus/--yolo are ignored on reattach.\n` +
           `Use 'agentbox down' first to start a fresh box with new settings.`,
       );
     }
-    console.log(`agentbox: reattaching to running container '${config.containerName}'…`);
+    // Report the RUNNING container's actual startup mode (via its label),
+    // never the current invocation's --yolo flag: that flag is ignored on
+    // reattach, so echoing it back would be wrong in either direction (claim
+    // prompts are disabled when they aren't, or vice versa).
+    const labels = await safe(() => docker.containerLabels(config.containerName), {});
+    const actualYolo = labels[LABEL_YOLO] === "true";
+    console.log(
+      `agentbox: reattaching to running container '${config.containerName}' ` +
+        `(${actualYolo ? "started with --yolo — permission prompts are disabled" : "permission prompts active"})…`,
+    );
     return await docker.execAttach(config, session.attachCommand(config));
   }
 
-  // A stopped-but-present container (e.g. an --rm corpse after a daemon
-  // restart) would make `docker run --name` fail with a name conflict.
+  // A stopped-but-present container (from a previous run that exited, or a
+  // daemon restart) would make `docker run --name` fail with a name conflict.
   if (await docker.containerExists(config.containerName)) {
     console.log(`agentbox: removing stale container '${config.containerName}'…`);
     await docker.removeContainer(config.containerName);
@@ -204,6 +222,12 @@ async function cmdUp(
   const tty = session.readTtySize();
   session.writeEntryScript(config, tty);
 
+  if (config.yolo) {
+    console.error(
+      "agentbox: --yolo — the Claude lead (and its teammates) will skip ALL permission prompts inside the box.",
+    );
+  }
+
   console.log(`agentbox: starting sandbox — Observer at http://localhost:${config.observerPort}…`);
   const started = await docker.runContainer(config, tty);
   if (started !== 0) {
@@ -213,6 +237,8 @@ async function cmdUp(
 
   // The container is detached; wait for the entry script to create the tmux
   // session, then attach a client. Detaching later only ends the client.
+  // Not --rm (see docker/index.ts): if the entry script crashes and the
+  // container exits early, it stays around for `docker logs` to inspect.
   const ready = await waitForSession(config, 15000);
   if (!ready) {
     console.error(
@@ -224,7 +250,11 @@ async function cmdUp(
   return await docker.execAttach(config, session.attachCommand(config));
 }
 
-/** Poll until the in-container tmux session exists (or the timeout passes). */
+/**
+ * Poll until the in-container tmux session exists, the container exits
+ * early (entry-script crash — no point waiting out the full timeout), or the
+ * timeout passes.
+ */
 async function waitForSession(config: AgentboxConfig, timeoutMs: number): Promise<boolean> {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
@@ -238,6 +268,7 @@ async function waitForSession(config: AgentboxConfig, timeoutMs: number): Promis
     ) {
       return true;
     }
+    if (!(await docker.containerRunning(config.containerName))) return false;
     if (Date.now() >= deadline) return false;
     await new Promise((r) => setTimeout(r, 250));
   }
@@ -318,11 +349,15 @@ async function cmdDoctor(config: AgentboxConfig): Promise<number> {
     );
   }
 
-  // Observer port validity.
-  const portOk = Number.isInteger(config.observerPort) && config.observerPort > 0 &&
-    config.observerPort <= 65535;
-  line(portOk, `Observer port is valid: ${config.observerPort}`);
-  if (!portOk) hardFailure = true;
+  // Config validity — the same checks `up`/`rebuild` fail fast on, reported
+  // here as part of doctor's checklist instead of a hard-fail.
+  const configProblems = validateConfig(config);
+  if (configProblems.length === 0) {
+    line(true, "Config values are valid (port/memory/cpus/paths)");
+  } else {
+    for (const p of configProblems) line(false, p);
+    hardFailure = true;
+  }
 
   // tmux-in-image: docker module exposes no exec-into-image helper, so we note
   // that tmux is provided by the Dockerfile and exercised at container start.
diff --git a/src/cli/parser.ts b/src/cli/parser.ts
index 2ed1355..27d9b3c 100644
--- a/src/cli/parser.ts
+++ b/src/cli/parser.ts
@@ -21,11 +21,19 @@ export interface ParsedArgs {
   helpRequested: boolean;
   /** True when the command was given explicitly (vs. defaulted to "up"). */
   hasExplicitCommand: boolean;
+  /**
+   * Value flags (e.g. --port) given with no following value, in order
+   * encountered. The router treats this as a hard error rather than
+   * silently falling back to a default (a bare `--gpus` should not
+   * silently run without a GPU).
+   */
+  missingValueFlags: string[];
 }
 
 export function parseArgs(argv: string[]): ParsedArgs {
   const flags: Record<string, string | boolean> = {};
   const positionals: string[] = [];
+  const missingValueFlags: string[] = [];
 
   for (let i = 0; i < argv.length; i++) {
     const tok = argv[i];
@@ -51,8 +59,12 @@ export function parseArgs(argv: string[]): ParsedArgs {
           flags[body] = next;
           i++;
         } else {
-          // Missing value — record presence; validation happens downstream.
+          // Missing value — record presence for backward-compat, but flag it
+          // as an error too: silently falling back to a default (e.g. --gpus
+          // with no value quietly running without a GPU) is worse than
+          // failing fast.
           flags[body] = true;
+          missingValueFlags.push(body);
         }
       } else {
         flags[body] = true;
@@ -78,5 +90,12 @@ export function parseArgs(argv: string[]): ParsedArgs {
   const command = hasExplicitCommand ? positionals[0] : "up";
   const helpRequested = flags.help === true || flags.h === true;
 
-  return { command, flags, positionals, helpRequested, hasExplicitCommand };
+  return {
+    command,
+    flags,
+    positionals,
+    helpRequested,
+    hasExplicitCommand,
+    missingValueFlags,
+  };
 }
diff --git a/src/docker/index.ts b/src/docker/index.ts
index e2fce5a..55f8678 100644
--- a/src/docker/index.ts
+++ b/src/docker/index.ts
@@ -24,6 +24,7 @@ import {
   CONTAINER_GH_CONFIG,
   CONTAINER_GITCONFIG,
   CONTAINER_OBSERVER,
+  LABEL_YOLO,
 } from "../types.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -114,7 +115,9 @@ function isDir(p: string): boolean {
  *
  * Detached (-d): the entry script — not a tmux attach client — is PID 1, so
  * detaching a client can never tear the sandbox down. Attaching is a separate
- * `docker exec` (execAttach).
+ * `docker exec` (execAttach). Deliberately NOT --rm: see runContainer's doc
+ * comment in types.ts — a container that exits early stays inspectable via
+ * `docker logs`, and agentbox removes stale stopped containers itself.
  */
 export function buildRunArgs(
   config: AgentboxConfig,
@@ -124,9 +127,10 @@ export function buildRunArgs(
   const args = [
     "run",
     "-d",
-    "--rm",
     "--name",
     config.containerName,
+    "--label",
+    `${LABEL_YOLO}=${config.yolo}`,
     // ── bind mounts ──────────────────────────────────────────────────────
     "-v",
     `${config.workspace}:${CONTAINER_WORKSPACE}`,
@@ -148,7 +152,7 @@ export function buildRunArgs(
     args.push("-v", `${config.ghConfigDir}:${CONTAINER_GH_CONFIG}:ro`);
   }
 
-  // ── persistent tool caches (named volumes; the box itself stays --rm) ───
+  // ── persistent tool caches (named volumes; the box itself stays disposable) ─
   for (const [volume, target] of CACHE_VOLUMES) {
     args.push("-v", `${volume}:${target}`);
   }
@@ -280,13 +284,22 @@ export const docker: DockerModule = {
 
     if (target?.isSymbolicLink()) {
       // Dotfile managers often symlink ~/.claude.json. Follow it: if the
-      // target exists we're done; if it dangles, create the target through
-      // the symlink (flag "w" — "wx" would fail with a confusing EEXIST on
-      // the link itself).
+      // target exists it must be a FILE (a symlink to a directory would
+      // otherwise sail through and Docker would mount a directory); if it
+      // dangles, create the target through the symlink (flag "w" — "wx"
+      // would fail with a confusing EEXIST on the link itself).
+      let followed: fs.Stats | undefined;
       try {
-        fs.statSync(config.claudeJson);
+        followed = fs.statSync(config.claudeJson);
       } catch {
         fs.writeFileSync(config.claudeJson, "{}\n", { flag: "w" });
+        return;
+      }
+      if (!followed.isFile()) {
+        throw new Error(
+          `${config.claudeJson} is a symlink to something other than a file.\n` +
+            `Fix or remove the symlink and run agentbox again.`,
+        );
       }
       return;
     }
@@ -338,4 +351,20 @@ export const docker: DockerModule = {
     const arch = stdout.trim();
     return code === 0 && arch.length > 0 ? arch : undefined;
   },
+
+  async containerLabels(name: string): Promise<Record<string, string>> {
+    const { code, stdout } = await capture([
+      "inspect",
+      "--format",
+      "{{json .Config.Labels}}",
+      name,
+    ]);
+    if (code !== 0) return {};
+    try {
+      const parsed = JSON.parse(stdout.trim());
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch {
+      return {};
+    }
+  },
 };
diff --git a/src/session/index.ts b/src/session/index.ts
index be39c5f..32010a9 100644
--- a/src/session/index.ts
+++ b/src/session/index.ts
@@ -62,10 +62,10 @@ function readTtySize(): TtySize {
  *
  * CRITICAL lifecycle fact: the tmux *client* must never be the container's
  * main process. If it were (the old `exec tmux attach` design), a plain
- * `C-b d` detach would exit PID 1, tear down the whole PID namespace (lead,
- * teammates, Observer) and — with `--rm` — delete the container. Instead this
- * script sets the session up detached and then idles while the tmux SERVER
- * has the session; clients attach via `docker exec` (see cli/docker modules).
+ * `C-b d` detach would exit PID 1 and tear down the whole PID namespace
+ * (lead, teammates, Observer). Instead this script sets the session up
+ * detached and then idles while the tmux SERVER has the session; clients
+ * attach via `docker exec` (see cli/docker modules).
  * Detach only ends the exec'd client; ending the tmux session ends PID 1 and
  * therefore the container.
  */
@@ -121,7 +121,7 @@ fi
 
 # Keep PID 1 alive for as long as the tmux session lives. When the user ends
 # the session (kills the last window / 'tmux kill-session'), this loop exits
-# and '--rm' removes the container.
+# and the container stops (agentbox removes it on the next 'up', or 'down').
 while tmux has-session -t "$SESSION" 2>/dev/null; do
   sleep 2
 done
@@ -135,7 +135,28 @@ done
  */
 function writeEntryScript(config: AgentboxConfig, tty: TtySize): string {
   const script = buildEntryScript(config, tty);
-  mkdirSync(dirname(config.entryScriptPath), { recursive: true, mode: 0o700 });
+  const dir = dirname(config.entryScriptPath);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  // mkdirSync's `mode` only applies when IT creates the directory — if the
+  // dir already existed (e.g. another local user pre-created it to race us),
+  // the mode is silently ignored and left as whatever the pre-existing dir
+  // had. Verify ownership + permissions after the fact and refuse to write
+  // into a directory we don't fully control (POSIX only; Windows has no
+  // comparable multi-user /tmp attack surface here).
+  if (typeof process.getuid === "function") {
+    const st = lstatSync(dir);
+    const mode = st.mode & 0o777;
+    if (st.uid !== process.getuid() || (mode & 0o077) !== 0) {
+      throw new Error(
+        `refusing to write the entry script into ${dir}: it is owned by uid ` +
+          `${st.uid} (expected ${process.getuid()}) or is group/other-accessible ` +
+          `(mode ${mode.toString(8)}). Remove it and re-run agentbox:\n` +
+          `  rm -rf '${dir}'`,
+      );
+    }
+  }
+
   // Never write through a pre-existing symlink at the target path.
   try {
     if (lstatSync(config.entryScriptPath).isSymbolicLink()) {
diff --git a/src/types.ts b/src/types.ts
index f0916fc..bba06b2 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -33,9 +33,13 @@ export const CONTAINER_GITCONFIG = "/home/agent/.gitconfig";
 /** Host gh CLI auth, mounted read-only (only when present on the host). */
 export const CONTAINER_GH_CONFIG = "/home/agent/.config/gh";
 
+/** Container label recording whether the box was started with --yolo. */
+export const LABEL_YOLO = "agentbox.yolo";
+
 /**
- * Named Docker volumes for tool caches: the box stays --rm-disposable, but
- * npm/cargo/pip downloads survive between boxes (kills the cold-start tax).
+ * Named Docker volumes for tool caches: npm/cargo/pip downloads survive
+ * between boxes even though the container itself is not auto-removed on
+ * exit (see DockerModule.runContainer).
  */
 export const CACHE_VOLUMES: ReadonlyArray<readonly [volume: string, target: string]> = [
   ["agentbox-npm-cache", "/home/agent/.npm"],
@@ -147,7 +151,10 @@ export interface DockerModule {
    * port, and --memory/--cpus limits. Launches the entry script via
    * `bash CONTAINER_ENTRY` (never relies on an execute bit) as container
    * PID 1 — never a tmux attach client, so detaching a client cannot tear
-   * down the sandbox. Resolves with `docker run`'s exit code.
+   * down the sandbox. Deliberately NOT --rm: a container that exits early
+   * (entry script crash) stays inspectable via `docker logs`; `up` removes
+   * a stale stopped container before starting a fresh one, and `down`
+   * removes it explicitly. Resolves with `docker run`'s exit code.
    */
   runContainer(config: AgentboxConfig, tty: TtySize): Promise<number>;
   /**
@@ -167,6 +174,13 @@ export interface DockerModule {
    * about emulated (slow) image/host arch mismatches.
    */
   imageArchitecture(image: string): Promise<string | undefined>;
+  /**
+   * Labels of a container (e.g. LABEL_YOLO), or {} if the container is
+   * missing / docker is unavailable. Used on reattach to report the
+   * RUNNING container's actual startup mode instead of the current
+   * invocation's flags, which are ignored on reattach.
+   */
+  containerLabels(name: string): Promise<Record<string, string>>;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
index fda8fcb..04d5027 100644
--- a/tests/cli.test.ts
+++ b/tests/cli.test.ts
@@ -77,3 +77,38 @@ test("an explicitly requested workspace that does not exist is rejected", async
   assert.equal(code, 1);
   assert.match(err, /workspace directory does not exist/);
 });
+
+test("a value flag with no value (e.g. --gpus) is a hard error, not silently disabled", async () => {
+  const { code, err } = await runCapture(["up", "--gpus"]);
+  assert.equal(code, 1);
+  assert.match(err, /--gpus/);
+  assert.match(err, /require a value/);
+});
+
+test("down stays usable even when MEM/CPUS are currently invalid (validateConfig is scoped to up/rebuild)", async () => {
+  const prevMem = process.env.MEM;
+  process.env.MEM = "not-a-valid-memory-value";
+  try {
+    const { err } = await runCapture(["down"]);
+    // Whatever docker.available() resolves to in this environment, `down`
+    // must never be blocked by a --memory-shaped validation error.
+    assert.doesNotMatch(err, /--memory/);
+  } finally {
+    if (prevMem === undefined) delete process.env.MEM;
+    else process.env.MEM = prevMem;
+  }
+});
+
+test("doctor reports an invalid config value in its checklist instead of hard-failing before it can run", async () => {
+  const prevMem = process.env.MEM;
+  process.env.MEM = "not-a-valid-memory-value";
+  try {
+    const { code, out, err } = await runCapture(["doctor"]);
+    assert.match(out, /--memory/);
+    assert.match(err, /doctor found a hard failure/);
+    assert.equal(code, 1);
+  } finally {
+    if (prevMem === undefined) delete process.env.MEM;
+    else process.env.MEM = prevMem;
+  }
+});
diff --git a/tests/docker.test.ts b/tests/docker.test.ts
index 00c55d4..7f31e52 100644
--- a/tests/docker.test.ts
+++ b/tests/docker.test.ts
@@ -11,7 +11,9 @@ import {
   CONTAINER_ENTRY,
   CONTAINER_GH_CONFIG,
   CONTAINER_GITCONFIG,
+  CONTAINER_OBSERVER,
   CONTAINER_WORKSPACE,
+  LABEL_YOLO,
   type AgentboxConfig,
   type TtySize,
 } from "../src/types.ts";
@@ -56,12 +58,25 @@ test("runs detached (-d), never interactive: the entry script must be PID 1", ()
   assert.ok(!args.includes("-it"));
 });
 
+test("does NOT use --rm: a container that exits early must stay inspectable via docker logs", () => {
+  const args = buildRunArgs(baseConfig(), TTY, NONE);
+  assert.ok(!args.includes("--rm"));
+});
+
 test("mounts workspace, claude dir/json, entry script and observer", () => {
   const mounts = valuesOf(buildRunArgs(baseConfig(), TTY, NONE), "-v");
   assert.ok(mounts.includes(`/home/u/proj:${CONTAINER_WORKSPACE}`));
   assert.ok(mounts.includes("/home/u/.claude:/home/agent/.claude"));
   assert.ok(mounts.includes("/home/u/.claude.json:/home/agent/.claude.json"));
   assert.ok(mounts.includes(`/tmp/agentbox-1000/entry.sh:${CONTAINER_ENTRY}`));
+  assert.ok(mounts.includes(`/repo/assets/observer.mjs:${CONTAINER_OBSERVER}`));
+});
+
+test("labels the container with its --yolo startup state (for accurate reattach reporting)", () => {
+  const off = valuesOf(buildRunArgs(baseConfig(), TTY, NONE), "--label");
+  assert.deepEqual(off, [`${LABEL_YOLO}=false`]);
+  const on = valuesOf(buildRunArgs(baseConfig({ yolo: true }), TTY, NONE), "--label");
+  assert.deepEqual(on, [`${LABEL_YOLO}=true`]);
 });
 
 test("publishes the observer port on loopback ONLY", () => {
diff --git a/tests/observer.test.ts b/tests/observer.test.ts
index c76053d..1e3e174 100644
--- a/tests/observer.test.ts
+++ b/tests/observer.test.ts
@@ -57,6 +57,32 @@ test("handles server 'error' events instead of dying with an unhandled exception
   assert.match(src, /EADDRINUSE/);
 });
 
-test("falls back to the default port when OBSERVER_PORT is not a valid port", () => {
-  assert.match(src, /Number\.isInteger\(RAW_PORT\)/);
+/**
+ * Actually EXECUTE the two-line RAW_PORT/PORT derivation extracted from the
+ * real source (not a reimplementation) for a given raw OBSERVER_PORT value,
+ * without starting the HTTP server. This exercises the real bounds logic —
+ * a single "does it mention Number.isInteger" regex wouldn't catch a broken
+ * `> 0` or `<= 65535` bound, or a broken 4317 fallback.
+ */
+function resolvePort(rawEnvValue: string | undefined): number {
+  const match = src.match(/const RAW_PORT[^\n]+\nconst PORT[^\n]+/);
+  assert.ok(match, "expected RAW_PORT/PORT derivation lines in observer.mjs");
+  const code = match[0].replace("process.env.OBSERVER_PORT", "envValue");
+  const fn = new Function("envValue", `${code}\nreturn PORT;`);
+  return fn(rawEnvValue);
+}
+
+test("port resolution: valid in-range values pass through", () => {
+  assert.equal(resolvePort("5000"), 5000);
+  assert.equal(resolvePort("1"), 1);
+  assert.equal(resolvePort("65535"), 65535);
+});
+
+test("port resolution: unset/invalid/out-of-range values fall back to 4317", () => {
+  assert.equal(resolvePort(undefined), 4317, "unset → default");
+  assert.equal(resolvePort("0"), 4317, "zero is out of range");
+  assert.equal(resolvePort("-1"), 4317, "negative is out of range");
+  assert.equal(resolvePort("70000"), 4317, "above 65535 is out of range");
+  assert.equal(resolvePort("abc"), 4317, "non-numeric");
+  assert.equal(resolvePort("4317.5"), 4317, "non-integer");
 });
diff --git a/tests/parser.test.ts b/tests/parser.test.ts
index 2f86a81..0fa2422 100644
--- a/tests/parser.test.ts
+++ b/tests/parser.test.ts
@@ -45,17 +45,35 @@ test("boolean flags take no value", () => {
   assert.equal(p.flags["no-cache"], true);
 });
 
-test("a value flag missing its value records boolean presence", () => {
+test("a value flag missing its value records boolean presence AND is reported as missing", () => {
   // --workspace at the end with no following token.
   const p = parseArgs(["up", "--workspace"]);
   assert.equal(p.flags.workspace, true);
+  assert.deepEqual(p.missingValueFlags, ["workspace"]);
 });
 
-test("a value flag followed by another flag does not consume it", () => {
+test("a value flag followed by another flag does not consume it, and is reported as missing", () => {
   const p = parseArgs(["up", "--workspace", "--port", "4000"]);
   // workspace had no real value (next token is a flag) → boolean presence.
   assert.equal(p.flags.workspace, true);
   assert.equal(p.flags.port, "4000");
+  assert.deepEqual(p.missingValueFlags, ["workspace"]);
+});
+
+test("a bare --gpus with no value is reported as missing (must not silently disable the GPU request)", () => {
+  const p = parseArgs(["up", "--gpus"]);
+  assert.equal(p.flags.gpus, true);
+  assert.deepEqual(p.missingValueFlags, ["gpus"]);
+});
+
+test("missingValueFlags is empty when every value flag got a real value", () => {
+  const p = parseArgs(["up", "--workspace", "/tmp/proj", "--port", "5000"]);
+  assert.deepEqual(p.missingValueFlags, []);
+});
+
+test("a boolean-only flag (--yolo, --no-cache) is never reported as missing a value", () => {
+  const p = parseArgs(["up", "--yolo", "--no-cache"]);
+  assert.deepEqual(p.missingValueFlags, []);
 });
 
 test("-h sets help and helpRequested", () => {
diff --git a/tests/session.test.ts b/tests/session.test.ts
index 123983c..4649a1d 100644
--- a/tests/session.test.ts
+++ b/tests/session.test.ts
@@ -6,6 +6,9 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import { session } from "../src/session/index.ts";
 import {
   CONTAINER_OBSERVER,
@@ -143,3 +146,32 @@ test("main window is selected last so the user lands on the lead", () => {
     "observer window is created before selecting main",
   );
 });
+
+// ── writeEntryScript: temp-dir ownership/permission hardening ──────────────
+// mkdirSync's `mode` only applies when it CREATES the directory; if another
+// local process pre-created it (predictable path: agentbox-<uid>), the mode
+// is silently ignored. writeEntryScript must verify ownership/permissions
+// itself rather than trusting a pre-existing directory. POSIX-only (no
+// process.getuid on Windows).
+const posixOnly = typeof process.getuid === "function" ? test : test.skip;
+
+posixOnly("writeEntryScript succeeds when it creates the temp dir itself", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agentbox-test-"));
+  fs.rmSync(dir, { recursive: true, force: true }); // let writeEntryScript create it fresh
+  const scriptPath = path.join(dir, "entry.sh");
+  const written = session.writeEntryScript(baseConfig({ entryScriptPath: scriptPath }), TTY);
+  assert.equal(written, scriptPath);
+  assert.ok(fs.existsSync(scriptPath));
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+posixOnly("writeEntryScript refuses a pre-existing world-writable temp dir", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agentbox-test-"));
+  fs.chmodSync(dir, 0o777); // simulate another local user's permissive pre-created dir
+  const scriptPath = path.join(dir, "entry.sh");
+  assert.throws(
+    () => session.writeEntryScript(baseConfig({ entryScriptPath: scriptPath }), TTY),
+    /refusing to write the entry script/,
+  );
+  fs.rmSync(dir, { recursive: true, force: true });
+});

From e3433545fd9d61186c8d180411eed558ad384da3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 30 Jul 2026 06:22:52 +0000
Subject: [PATCH 6/6] fix: launcher resolves tsx via Node's module resolution,
 not a hardcoded path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI's npm-pack smoke test failed: when the tarball is installed as a
dependency in another project, npm hoists tsx to the CONSUMER's top-level
node_modules instead of nesting it under agentbox's own node_modules, so
the previous `<here>/../node_modules/tsx/dist/cli.mjs` path didn't exist.

Fix: use createRequire().resolve() to locate tsx the way Node itself would
(walking up node_modules, handling hoisting correctly in every install
shape — repo clone, hoisted consumer install, or nested global install).
Resolves "tsx/package.json" rather than "tsx/dist/cli.mjs" directly: tsx's
package.json declares an `exports` map that only allows a few subpaths, and
"./dist/cli.mjs" isn't one of them, so resolving it by specifier would throw
ERR_PACKAGE_PATH_NOT_EXPORTED even though the file exists on disk. Deriving
the cli.mjs path from the resolved package.json's directory sidesteps that:
it's a plain filesystem join, not a specifier resolution.

Verified locally by reproducing the CI job exactly: npm pack, install the
tarball into a scratch consumer project, run npx agentbox --help/doctor.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RfjQjysq5JF7gQCJB3RQtP
---
 bin/agentbox.mjs | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/bin/agentbox.mjs b/bin/agentbox.mjs
index 2b80aff..04c2fab 100644
--- a/bin/agentbox.mjs
+++ b/bin/agentbox.mjs
@@ -3,22 +3,38 @@
  * agentbox launcher. Runs the TypeScript CLI through tsx without a build step.
  */
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
+import { dirname, resolve, join } from "node:path";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const entry = resolve(here, "..", "src", "index.ts");
-const localTsxCli = resolve(here, "..", "node_modules", "tsx", "dist", "cli.mjs");
 
-if (!existsSync(localTsxCli)) {
+// Locate tsx's cli entry via Node's real module resolution (createRequire),
+// not a hand-constructed path: npm may hoist tsx to the CONSUMER project's
+// top-level node_modules instead of nesting it under agentbox's own
+// node_modules (e.g. `npm install <agentbox tarball>` in another project),
+// so `<here>/../node_modules/tsx/...` doesn't always exist even though tsx
+// is installed. require.resolve() walks up node_modules the same way Node
+// itself does, so it finds tsx wherever it actually landed. Resolving
+// "tsx/package.json" (not "tsx/dist/cli.mjs") because tsx's `exports` map
+// only allows that subpath — deep-importing dist/cli.mjs by specifier would
+// throw ERR_PACKAGE_PATH_NOT_EXPORTED even though the file exists on disk.
+const require = createRequire(import.meta.url);
+let localTsxCli;
+try {
+  localTsxCli = join(dirname(require.resolve("tsx/package.json")), "dist", "cli.mjs");
+} catch {
+  localTsxCli = undefined;
+}
+
+if (!localTsxCli) {
   // tsx is a runtime dependency of agentbox (package.json), so this should
-  // always be present after install. No shell-based global-PATH fallback:
+  // always be resolvable after install. No shell-based global-PATH fallback:
   // that used to run `tsx` via a shell (required for the Windows .cmd shim),
   // which forwarded raw argv through cmd.exe with no metacharacter escaping.
   console.error(
-    "agentbox: 'tsx' is missing from node_modules (expected at " +
-      `${localTsxCli}).\n` +
+    "agentbox: could not resolve 'tsx' (a runtime dependency of agentbox).\n" +
       "Run 'npm install' to reinstall agentbox's dependencies.",
   );
   process.exit(127);