Keep the stored GitHub token when setup runs again

The secret store outlives the sandbox, so recreating one to change its image or add a profile does not lose the token. Prompting for a replacement anyway made --replace impractical and trained the habit of minting tokens that are never revoked. Only a token scoped to this sandbox counts. A global one would authenticate the agent too, but reaching every repository it can reach is what this task exists to prevent. The token command still always prompts; it is the way to replace an expired or revoked token.
Give the sandbox a UTF-8 locale
2026-08-03 16:09:44 -05:00 · 2026-08-03 15:26:41 -05:00 · 2026-08-03 13:49:24 -05:00 · 2026-08-03 12:37:53 -05:00 · 2026-08-03 10:42:56 -05:00 · 2026-07-31 12:09:56 -05:00
14 changed files with 2094 additions and 62 deletions
@@ -119,8 +119,9 @@ Optional personal defaults:

 ```toml
 [env]
-AI_SBX_AGENT = "codex"
+AI_SBX_AGENT = "claude"
 AI_SBX_MODE = "clone"
+# AI_SBX_TEMPLATE = "git.mroberts.dev/you/claude-sbx:v1"   # unset = stock image
 ```

 Confirm it loaded:
@@ -182,15 +183,33 @@ target_name   CareEvolution
 expires_in    30
 metadata=read  contents=write  pull_requests=write  issues=write
 workflows=write  actions=write  statuses=read  security_events=write
+secret_scanning_alerts=read  vulnerability_alerts=read
 ```

-Two things the form cannot pre-fill, so the task prints them as a checklist:
+One thing the form cannot pre-fill: **Repository access → Only select repositories
+→ `api-portal`.** GitHub has no query parameter for repository selection.

-1. **Repository access → Only select repositories → `api-portal`.** GitHub has no
-   query parameter for repository selection.
-2. **Checks: Read, Dependabot alerts: Read, Secret scanning alerts: Read.** These
-   three are absent from GitHub's pre-fill parameter list. Skip them if the agent
-   does not need to read CI status or triage security alerts.
+### The Checks API is out of reach
+
+Fine-grained tokens cannot read check runs. This is not a permission you forgot to
+grant — GitHub's permission reference has no Checks section and lists no check-run
+endpoint, so there is no box to tick. Inside the sandbox:
+
+| Command | Behaviour |
+| --- | --- |
+| `gh pr checks` | shows commit statuses only, not check runs |
+| `gh run view` | returns no annotations |
+| `gh run view --log` | works — job logs fall under Actions |
+
+Both degrade to empty output rather than a permission error, so they read as a broken
+CI integration unless you know why. A 403 names what it wanted in the
+`X-Accepted-GitHub-Permissions` response header.
+
+Only an installation token from a GitHub App can reach the Checks API. That was
+evaluated and rejected for this workflow: minting one requires the App private key on
+every developer's machine, and device-flow user tokens — the alternative that needs no
+key — were measured and do **not** honour `repository_id`, so they reach every
+repository in the installation.

 Generate the token and paste it at the prompt. It is read with the terminal echo off
 and piped straight into the `sbx` secret store, so it never reaches your shell history.
@@ -244,11 +263,11 @@ provider "aws" {

 | Command | Effect |
 | --- | --- |
-| `setup [options]` | Configure the repository, create the sandbox, open the token form, install AWS profiles, Claude configuration and plugins, and mise |
-| `token` | Replace the GitHub token for this repository — expiry, revocation, permission change |
-| `run [-- args...]` | Refresh AWS credentials and the repository's mise tools, then attach to the agent |
+| `setup [options]` | Configure the repository, create the sandbox, open the token form if no token is stored yet, install AWS profiles, Claude configuration and plugins, and mise |
+| `token` | Replace the GitHub token for this repository — expiry, revocation, permission change. Always prompts |
+| `run [--launch MODE] [-- args...]` | Refresh AWS credentials and the repository's mise tools, then attach to the agent or to a tmux workspace |
 | `refresh` | Refresh AWS credentials, without attaching |
-| `config` | Re-apply your Claude configuration and plugins after the host changes, without recreating the sandbox |
+| `config` | Re-apply your Claude configuration, plugins and dotfiles after the host changes, without recreating the sandbox |
 | `status` | Show repository, sandbox, agent, mode, token expiry setting, profile mapping, stored secrets |
 | `remove` | Remove the sandbox and this repository's local configuration |

@@ -257,7 +276,7 @@ provider "aws" {
 | Option | Default | Effect |
 | --- | --- | --- |
 | `--aws-profile NAME` | none | Host profile to expose. Repeatable. Trailing `-readonly` stripped inside the sandbox |
-| `--agent NAME` | `codex` | Sandbox agent. See `sbx create --help` for the list |
+| `--agent NAME` | `claude` | Sandbox agent. See `sbx create --help` for the list |
 | `--clone` | on | Give the agent a private in-container clone; its commits reach the host via the `sandbox-<name>` git remote |
 | `--template REF` | `AI_SBX_TEMPLATE` | Custom sandbox image |
 | `--stock-template` | off | Ignore `AI_SBX_TEMPLATE` for this repository |
@@ -269,10 +288,73 @@ provider "aws" {

 | Variable | Default | Overrides |
 | --- | --- | --- |
-| `AI_SBX_AGENT` | `codex` | `--agent` |
+| `AI_SBX_AGENT` | `claude` | `--agent` |
 | `AI_SBX_MODE` | `clone` | `--clone` / `--direct` |
 | `AI_SBX_TOKEN_DAYS` | `30` | token expiry pre-filled on the form (1–366, or `none`) |
 | `AI_SBX_TEMPLATE` | unset | `--template` / `--stock-template` |
+| `AI_SBX_TOOLS` | `bun` | mise tools installed globally in the sandbox; empty installs none |
+| `AI_SBX_NETWORK` | unset | hosts to allow through the sandbox network policy, comma or space separated |
+| `AI_SBX_LAUNCH` | `agent` | `run --launch agent\|tmux` |
+| `AI_SBX_DOTFILES` | unset | `chezmoi` renders the host's dotfiles into the sandbox |
+
+## The tmux workspace
+
+`AI_SBX_LAUNCH=tmux`, or `run --launch tmux`, attaches to a three-window tmux session
+inside the sandbox instead of the bare agent:
+
+| Window | Contents |
+| --- | --- |
+| `agent` | The agent, started the same way `sbx run` starts it |
+| `edit` | `nvim .` |
+| `shell` | A prompt |
+
+All three start in the workspace root and inherit the sandbox environment, so AWS
+profiles and injected registry credentials work in every one of them.
+
+The session is named `ai-sbx` and is attached to rather than recreated, so detaching
+and re-running lands back in the same place with the agent's context intact. That also
+means closing the terminal no longer ends the session — the agent keeps running inside
+the sandbox until it is stopped.
+
+Agent arguments (`run -- --resume`) apply to `agent` mode only; passing them with
+`--launch tmux` is an error rather than a silent no-op.
+
+The sandbox image must provide `tmux` and `nvim`. The stock image provides neither,
+so add them with mise:
+
+```toml
+AI_SBX_TOOLS = "bun tmux neovim"
+```
+
+Without `tmux` the launcher says so and starts the agent directly.
+
+## Carrying your dotfiles into the sandbox
+
+`AI_SBX_DOTFILES=chezmoi` renders your chezmoi target state **on the host** — where the
+age identity already lives — and unpacks the resulting tar into the sandbox home. The
+sandbox needs no dotfiles repository, no decryption key and no network for this, and
+`DEV_CONTAINER=1` is set so `git.autoCommit` and `git.autoPush` stay off.
+
+Which files travel is an allowlist of target paths, one per line, in
+`~/.config/ai-sbx/dotfiles`:
+
+```text
+.config/nvim
+.tmux.conf
+.gitconfig
+```
+
+The allowlist is a security control, not a convenience. `chezmoi archive` **decrypts as
+it renders**, so a full archive contains your `gh` tokens, `.npmrc`, NuGet credentials
+and `.ssh/config` in plaintext — precisely what the proxy-injected GitHub token exists
+to keep away from the agent. Two checks enforce this:
+
+- every `encrypted_*` source file is resolved to its target, and setup fails if any
+  lands inside the allowlist;
+- the rendered archive is scanned for credential shapes before it enters the sandbox.
+
+Neither can infer intent from a filename, so review what you list once. A file named
+`tokens.fish` that happens not to be encrypted is still a file full of tokens.

 ## Carrying your Claude configuration into the sandbox

@@ -291,6 +373,22 @@ Copies each skill directory from `~/.claude/skills` (and `~/.agents/skills`,
 mounted into every new sandbox. Symlinks and loose top-level files are skipped. Skills
 under `~/.claude/plugins/` are **not** scanned — only the top-level skills directory.

+**Plugin runtimes.** Plugins bring their own dependencies: several — claude-mem among
+them — run their hooks under `bun`, which the sandbox image does not carry. A missing
+runtime shows up as a hook error on *every* prompt rather than at install time:
+
+```text
+SessionStart:startup hook error
+Failed with non-blocking status code: Error: Bun not found.
+```
+
+`AI_SBX_TOOLS` installs tools globally in the sandbox with mise, and defaults to `bun`
+for exactly this reason. Add to it for other runtimes:
+
+```toml
+AI_SBX_TOOLS = "bun deno"
+```
+
 **Kits — for tools, env vars, network rules, and startup commands:**

 ```bash
@@ -361,6 +459,94 @@ It is copied to the workspace root on every run. This matters under `--clone`, w
 the agent gets a fresh git clone and an untracked `mise.local.toml` on the host would
 not reach it. Repositories with no mise configuration are left alone.

+## Registry credentials
+
+Repositories often need registry tokens — npm, NuGet — to install dependencies. The
+task resolves them on the host, where 1Password and your keychain live, and provisions
+them so the value never enters the sandbox.
+
+Declare them per repository in your **own** config, not the repository's:
+
+```text
+~/.config/ai-sbx/repos/<digest>/secrets
+```
+
+```text
+# VAR | host[,host...] | command printing the value, run from the repository root
+FONTAWESOME_API_KEY | npm.fontawesome.com      | scripts/npm-auth.sh print FONTAWESOME_API_KEY
+PROGET_NPM_TOKEN    | proget.careevolution.com | scripts/npm-auth.sh print PROGET_NPM_TOKEN
+```
+
+The `<digest>` is the suffix of the sandbox name, so read it off
+`mise run ai:sbx -- status`.
+
+**The value is never in the sandbox.** Each entry becomes an `sbx` custom secret: the
+sandbox environment variable is set to a *placeholder*, and the proxy substitutes the
+real secret into outbound request headers for the listed hosts. A committed `.npmrc`
+using `${FONTAWESOME_API_KEY}` interpolation therefore works unchanged, while an agent
+reading the variable sees only `sbx-cs-…`.
+
+The declaration lives in user config for the same reason AWS profile approval does: a
+repository must not be able to choose which host commands run or which credentials get
+resolved. The command runs on your host, with your credentials.
+
+Point it at whatever the repository already uses. A resolver that collapses several
+sources into one `print <VAR>` interface is ideal, because the search order stays in
+the repository where it belongs. If resolution fails, the command's own stderr is
+surfaced — it names the variable and where to obtain it — and the remaining secrets
+still provision.
+
+Placeholders are derived from the repository and variable name, so re-running `setup`
+does not invalidate a value already exported inside a running sandbox.
+
+### Network policy
+
+Sandboxes default to Docker's `Balanced` policy: deny everything except common
+development hosts. That already covers more than it appears to — `github.com`,
+`codeload.github.com`, `raw` and `objects.githubusercontent.com`,
+`registry.npmjs.org`, `pypi.org`, `files.pythonhosted.org`, `crates.io`,
+`proxy.golang.org` are all permitted, so npm, pip, cargo, go, and a plugin-managed
+Neovim config need nothing added.
+
+Private registries do not. Declare them once:
+
+```toml
+AI_SBX_NETWORK = "artifactory.example.com, *.internal.example.com"
+```
+
+**Hosts backing a provisioned secret are allowed automatically.** A credential for a
+denied host is dead weight — the request never leaves the sandbox, so the proxy never
+substitutes anything, and the failure looks like a hang or a connection error rather
+than a policy decision.
+
+Check any host against the effective policy with:
+
+```bash
+sbx policy check network --sandbox <sandbox> npm.fontawesome.com
+```
+
+### Host-wide credentials
+
+Some credentials are worth provisioning everywhere rather than declaring per
+repository. These are taken from your host environment automatically:
+
+| Variable | Hosts | Provisioned when |
+| --- | --- | --- |
+| `LOCALSTACK_AUTH_TOKEN` | `localstack.cloud`, `*.localstack.cloud` | the variable is set **and** the sandbox has Docker |
+
+The Docker condition matters: LocalStack runs as a container, so on a sandbox created
+from a non-`-docker` template the token would be dead weight. It is skipped there with
+a message rather than stored.
+
+Nothing happens if the variable is unset, so this costs nothing on a machine that
+does not use LocalStack.
+
+> **Unverified.** LocalStack runs as a *nested* container inside the sandbox's own
+> Docker daemon. Whether its outbound activation request traverses the `sbx` proxy —
+> and therefore gets the placeholder substituted — has not been tested. If activation
+> fails reporting an invalid token, the placeholder is reaching LocalStack literally,
+> and the token needs exporting as a real value instead.
+
 ## AWS profile naming

 Only a trailing `-readonly` is removed. Everything else passes through:
@@ -419,10 +605,8 @@ Inspect the current repository's state with `mise run ai:sbx -- status`.
 ## Development

 ```bash
-bash tests/profile-mapping.test.sh
-bash tests/token-url.test.sh
-bash tests/invocation-directory.test.sh
-shellcheck -x tasks/ai/sbx tests/*.sh
+for test in tests/*.test.sh; do bash "$test"; done
+shellcheck -x tasks/ai/sbx tasks/ai/workspace tests/*.sh
 ```

 The token test checks URL encoding, that `target_name` carries the owner rather than
@@ -0,0 +1,343 @@
+# Plan: launch a tmux workspace instead of the bare agent
+
+Give `ai:sbx` an option to attach to a tmux session with three windows — agent, editor,
+shell — rather than dropping straight into the agent.
+
+Spans two repositories: the option and launch logic here, the tools and dotfiles in
+the base image (`mroberts/claude-sbx`).
+
+## What was established
+
+Measured against `sbx` 0.37.0 and a live sandbox, not assumed:
+
+| Finding | Consequence |
+| --- | --- |
+| PID 1 is `tini -- sh -c … sleep infinity`; no agent process runs until attach | `sbx run` execs the agent on attach. Launching tmux instead displaces nothing |
+| `sbx exec -it SANDBOX CMD` allocates a TTY and keeps stdin open | A tmux session can be attached without a kit or a custom image |
+| `sandbox.entrypoint.run` in a `kind: sandbox` kit replaces the image entrypoint | The alternative route: `sbx run` itself opens tmux |
+| `tmux`, `nvim`, `vim` are all absent from `claude-code-docker` | Something must supply them |
+| mise resolves `tmux` 3.7b (aqua/asdf) and `neovim` 0.12.4 (aqua) | `AI_SBX_TOOLS` can supply both with no image work |
+| `files/home/` in a kit maps to `/home/agent/` | Dotfiles can ship without an image rebuild too |
+| `/etc/sandbox-persistent.sh` carries PATH, AWS, and secret placeholders | Any window started via a **login** shell inherits the environment |
+
+That last row is load-bearing: tmux windows must start login shells (`bash -l`), or
+they lose mise shims, AWS credentials, and every secret placeholder.
+
+## Two decisions
+
+### How to launch
+
+**Recommended: `sbx exec -it`, from `run_command`.**
+
+```bash
+exec sbx exec -it -w "$REPO_ROOT" "$SANDBOX_NAME" \
+    bash -lc 'ai-sbx-workspace'
+```
+
+No kit, no custom image, no change to how the sandbox is created. Reversible per run.
+`sbx run` remains available untouched for anyone who wants the plain agent.
+
+The alternative — a `kind: sandbox` kit with `entrypoint.run` — makes `sbx run`
+itself open tmux, which is tidier semantically. It costs more: the kit must declare
+the whole agent (image and entrypoint), the image must satisfy the base image
+contract (non-root `agent` at UID 1000, passwordless sudo, proxy variables preserved
+across sudo), and the agent's own launch flags must be reproduced. Not worth it for a
+launch preference.
+
+### Where tmux and neovim come from
+
+**Recommended: start with `AI_SBX_TOOLS`, move to the image once it settles.**
+
+```toml
+AI_SBX_TOOLS = "bun tmux neovim"
+```
+
+Already implemented and needs no new code. Costs a per-sandbox install on first
+`setup`, which is why the image is the eventual home — but proving the layout is
+worth more than saving that minute, and the image cannot be iterated on as quickly.
+
+## Part 1 — changes here
+
+### 1. `AI_SBX_LAUNCH`
+
+Follows the existing `AI_SBX_AGENT` / `AI_SBX_TEMPLATE` / `AI_SBX_TOOLS` pattern:
+an environment variable read at the top of the task, overridable per invocation.
+
+| Value | Behaviour |
+| --- | --- |
+| `agent` | Current behaviour: `sbx run`. **Default** |
+| `tmux` | Attach to the workspace session |
+
+Plus `--launch agent|tmux` on `run` for a one-off override. Persisting it per
+repository in `save_config` is the wrong call — it is a preference about *this*
+session, not a property of the repository, and the environment variable already
+covers the durable case.
+
+### 2. The launcher
+
+A script the task installs into the sandbox, not an inline `sbx exec` string. Three
+reasons: it must be idempotent, it needs real logic, and quoting a multi-window tmux
+invocation through two shells is how mistakes happen.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+session=ai-sbx
+
+if tmux has-session -t "$session" 2>/dev/null; then
+    exec tmux attach-session -t "$session"
+fi
+
+tmux new-session  -d -s "$session" -n agent -c "$PWD"
+tmux new-window   -t "$session:" -n edit  -c "$PWD"
+tmux new-window   -t "$session:" -n shell -c "$PWD"
+
+tmux send-keys -t "$session:agent" "$AGENT_COMMAND" C-m
+tmux send-keys -t "$session:edit"  "nvim ."         C-m
+
+tmux select-window -t "$session:agent"
+exec tmux attach-session -t "$session"
+```
+
+Attach-or-create matters: detaching and re-running must land back in the same session
+with the agent's context intact, which is most of the point.
+
+Install it the way `mise` already is — copied to `~/.local/bin/` inside the sandbox
+during `install_sandbox_mise`, or a sibling `install_sandbox_workspace`.
+
+### 3. Resolve the agent command — do this first
+
+**The one real unknown.** `sbx run` execs the agent with flags this project has never
+seen, because the container only sleeps until attach. Claude Code is very likely
+started with `--dangerously-skip-permissions` — the Sandboxes FAQ describes a kit
+that exists specifically to *drop* that flag — but that is inference, not
+observation.
+
+Determine it before writing the launcher:
+
+```bash
+sbx run --name <sandbox> &
+sbx exec <sandbox> ps -eo args | grep -i claude
+```
+
+If it cannot be recovered, fall back to `claude` plain and document the difference,
+because silently changing the agent's permission model would be worse than the
+inconvenience.
+
+### 4. Tests
+
+Consistent with the existing suite — pure functions and source-level assertions, no
+sandbox required:
+
+- `AI_SBX_LAUNCH` defaults to `agent`; `--launch` overrides it; an unknown value is
+  rejected rather than silently treated as `agent`.
+- `run_command` dispatches to `sbx run` for `agent` and `sbx exec -it` for `tmux`,
+  asserted with a stubbed `sbx`, as `create_sandbox` already is.
+- The launcher script is syntax-checked and shellcheck-clean.
+- The launcher uses a **login** shell, since a non-login shell loses the whole
+  environment. Assert `bash -lc` appears.
+
+## Part 2 — what to bake into the base image
+
+Once the layout settles, move it out of `AI_SBX_TOOLS` and into
+`mroberts/claude-sbx`, per `docs/HANDOFF.md` there.
+
+### Packages
+
+```dockerfile
+USER root
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends tmux \
+ && rm -rf /var/lib/apt/lists/*
+```
+
+Neovim is the awkward one: Ubuntu ships an old version, and a modern config will
+expect ≥ 0.10. Prefer the upstream tarball or keep it on mise rather than `apt`.
+
+### Dotfiles
+
+`files/home/` in a kit, or `COPY --chown=agent:agent` in the template:
+
+```
+.tmux.conf          mouse on, sane scrollback, obvious status line
+.config/nvim/       the smallest config that is pleasant on a fresh machine
+```
+
+Ship the **full** config. The network objection that would have argued for trimming it
+does not survive measurement — see below — so the only real cost is a slower first
+launch while plugins and LSP servers download.
+
+### The launcher
+
+Bake the same script at `/usr/local/bin/ai-sbx-workspace` so the task can call it
+without installing anything. Keep the task's copy as the fallback for stock images —
+the two must not drift, so it should live in one place here and be copied into the
+image build rather than maintained twice.
+
+### Verify
+
+Check what the base image already provides before adding anything:
+
+```bash
+docker run --rm docker/sandbox-templates:claude-code-docker \
+  bash -lc 'for c in tmux nvim vim git node python3; do printf "%-8s %s\n" "$c" "$(command -v $c || echo MISSING)"; done'
+```
+
+## Dotfiles (chezmoi)
+
+Short answer: **mise supplies the binary, but not the dotfiles, and baking them into
+the image is the wrong home for them.** A third path fits better — render on the host,
+copy the result in — which is how `~/.claude` is already handled.
+
+### Why not mise alone
+
+`mise` installs chezmoi fine (`aqua:twpayne/chezmoi`, 2.71.1), so
+`AI_SBX_TOOLS = "bun tmux neovim chezmoi"` puts the binary in every sandbox. Getting
+the *content* in is where it stops, for two independent reasons:
+
+| Blocker | Detail |
+| --- | --- |
+| The repo is private | `github.com/mickeyr/DotFiles` returns 404 anonymously. The sandbox's GitHub token is a fine-grained PAT scoped to the repository being worked on, so it cannot clone a personal repo |
+| Six files are age-encrypted | The identity lives at `~/.config/chezmoi/key.txt` on the host. `chezmoi apply` in the sandbox would need that private key copied in |
+
+So `chezmoi init --apply github.com/mickeyr/DotFiles` inside a sandbox fails twice
+over. Fixing it by copying an age private key into an environment an agent can read is
+worse than the problem.
+
+### Why not the image
+
+Dotfiles are personal and change often; the image is shared and slow to rebuild. Every
+nvim tweak would mean a rebuild and a registry push. Worse, the image is pushed to a
+registry — anything baked in travels with it.
+
+### Recommended: `chezmoi archive` on the host, allowlisted
+
+`chezmoi archive` renders the target state on the host, where the age key already is,
+and emits a tar. No repo access, no key, and no network needed inside the sandbox.
+
+```bash
+DEV_CONTAINER=1 chezmoi archive --format tar <target>... |
+    sbx exec -i "$SANDBOX_NAME" tar -x -C "$sandbox_home"
+```
+
+Measured: 241 entries, 542 KB for the full set; `chezmoi archive ~/.config/nvim`
+scopes it to 62.
+
+**`DEV_CONTAINER=1` is required, not cosmetic.** The existing `.chezmoi.toml.tmpl`
+already branches on it, and setting it disables `git.autoCommit` and `git.autoPush` —
+without it, an agent operating in the sandbox could push to the dotfiles repo.
+
+### The part that must not be got wrong
+
+`chezmoi archive` **decrypts** as it renders. A full archive therefore contains, in
+plaintext:
+
+```text
+.config/gh/hosts.yml            GitHub CLI auth tokens
+.npmrc                          npm registry tokens
+.nuget/NuGet/NuGet.Config       NuGet credentials
+.ssh/config
+.config/fish/conf.d/tokens.fish
+.mcp.json
+.aider.conf.yml
+```
+
+Copying that in would hand the agent the very credentials this project spends its
+effort keeping out — the GitHub token is proxy-injected as a placeholder precisely so
+it is unreadable, and `.config/gh/hosts.yml` would undo that in one step.
+
+So the copy must be an **allowlist of targets**, matching `CLAUDE_CONFIG_ALLOW`:
+
+```bash
+CHEZMOI_TARGET_ALLOW=(
+    .config/nvim
+    .config/fish        # audit: conf.d/tokens.fish must not be included
+    .tmux.conf
+    .gitconfig
+)
+```
+
+A denylist is not good enough. New encrypted files appear over time, and the failure
+mode is silent credential exfiltration into an agent's environment.
+
+Two mechanical checks worth building in, since both are cheap:
+
+- Enumerate encrypted targets and refuse to proceed if any is inside the allowlist:
+  `chezmoi target-path` resolves each `encrypted_*` source file to its target, and all
+  six mapped correctly when tested.
+- Scan the rendered archive for credential shapes before it enters the sandbox — the
+  same guard the template build script already uses.
+
+### Where it goes
+
+A `install_sandbox_dotfiles` alongside `install_sandbox_claude_config`, gated on
+`AI_SBX_DOTFILES` (unset = off). It runs on the host, so it needs no chezmoi in the
+sandbox at all — which makes the mise entry optional, useful only if the agent should
+be able to run `chezmoi` itself.
+
+## Risks
+
+**Environment loss.** Any window not started as a login shell loses PATH, AWS
+credentials, and secret placeholders. This will look like "npm suddenly cannot
+authenticate" rather than anything to do with tmux.
+
+**Detach semantics.** `sbx exec -it` with a detached tmux session leaves the agent
+running inside the sandbox after the terminal closes. Desirable, but different from
+today, where closing the terminal ends the session. Worth stating in the README.
+
+**Nested tmux.** A developer already inside tmux on the host gets a nested session.
+Setting a distinct prefix in the sandbox `.tmux.conf` avoids a confusing fight over
+`C-b`.
+
+**Terminal type.** `TERM` must survive into the sandbox or nvim renders badly.
+`sbx exec -t` should handle it; confirm rather than assume.
+
+**Plugin bootstrap — measured host by host with `sbx policy check network`.**
+
+Already permitted by `Balanced`, so nothing to declare:
+
+```text
+github.com  codeload.github.com  raw/objects.githubusercontent.com
+registry.npmjs.org  pypi.org  files.pythonhosted.org
+crates.io  static.crates.io  proxy.golang.org  sum.golang.org
+nodejs.org  deb.debian.org  archive/security.ubuntu.com
+releases.hashicorp.com  checkpoint-api.hashicorp.com
+api.githubcopilot.com  copilot-proxy.githubusercontent.com
+api.anthropic.com  api.openai.com
+```
+
+That covers all 93 pinned lazy.nvim plugins, both mason registries (`mason-org` and
+`crashdummyy`, both `github:`), all 55 mason packages, Copilot, and codecompanion.
+
+Denied, and therefore declared in `AI_SBX_NETWORK`:
+
+| Host | Needed by |
+| --- | --- |
+| `*.nuget.org` | roslyn, easy-dotnet, NuGet restore |
+| `pkgs.dev.azure.com` | Azure-hosted NuGet feeds |
+| `builds.dotnet.microsoft.com`, `dotnetcli.azureedge.net`, `dotnetbuilds.azureedge.net`, `dotnetcli.blob.core.windows.net`, `ci.dot.net` | .NET SDK downloads |
+| `registry.terraform.io` | provider downloads for terragrunt |
+| `mise.jdx.dev` | mise self-resolution |
+| `default.exp-tas.com` | Copilot feature flags |
+
+Confirmed reachable from inside the sandbox afterwards: `api.nuget.org` and
+`registry.terraform.io` both return HTTP 200.
+
+Wildcards match a single label: `*.nuget.org` covers `api.`, `www.`, `globalcdn.` and
+the bare domain, but `*.azureedge.net` does **not** reach
+`dotnetcli.blob.core.windows.net`. Prefer explicit hosts over a broad CDN wildcard —
+`*.azureedge.net` would admit every Azure CDN customer, not just Microsoft's.
+
+The work registries — `npm.fontawesome.com`, `proget.careevolution.com`,
+`localstack.cloud` — are allowed automatically, since they back provisioned secrets.
+
+## Acceptance
+
+1. `AI_SBX_LAUNCH` unset → `mise run ai:sbx -- run` behaves exactly as today.
+2. `AI_SBX_LAUNCH=tmux` → three windows, agent running in the first, all three in the
+   repository root.
+3. Detach and re-run → reattaches to the same session, agent context intact.
+4. Inside the shell window, `npm ci` in `webui/` still authenticates — proving the
+   environment survived.
+5. `--launch agent` overrides the variable for one run.
@@ -0,0 +1,187 @@
+# Spec: tmux workspace and dotfiles — `ai-sandbox`
+
+Implementation spec for the task side. Background and the decisions behind it are in
+[`tmux-workspace-plan.md`](tmux-workspace-plan.md); the image side is
+`mroberts/claude-sbx` → `docs/base-image-spec.md`.
+
+## Scope
+
+1. `AI_SBX_LAUNCH` — attach to a tmux workspace instead of the bare agent.
+2. `AI_SBX_DOTFILES` — render the host's chezmoi dotfiles into the sandbox.
+
+Both default to off. With neither set, behaviour is byte-for-byte what it is today.
+
+## 1. Launch mode
+
+### Configuration
+
+| Surface | Values | Default |
+| --- | --- | --- |
+| `AI_SBX_LAUNCH` | `agent`, `tmux` | `agent` |
+| `run --launch MODE` | same | overrides the variable for one run |
+
+Read as `DEFAULT_LAUNCH="${AI_SBX_LAUNCH:-agent}"`, matching the existing
+`AI_SBX_AGENT` / `AI_SBX_TEMPLATE` / `AI_SBX_TOOLS` / `AI_SBX_NETWORK` pattern.
+
+An unrecognised value must `die`, not fall through to `agent`. A typo that silently
+does the wrong thing is worse than a stopped run.
+
+Not persisted in the per-repository config. It is a property of this session, not of
+the repository; the environment variable already covers the durable case.
+
+### Dispatch
+
+`run_command` keeps its current preamble — `load_config`, `sandbox_exists`,
+`install_sandbox_aws_files`, `install_sandbox_mise` — and then branches:
+
+```bash
+case "$launch" in
+    agent)
+        exec sbx run "$SANDBOX_NAME" ${1:+-- "$@"}
+        ;;
+    tmux)
+        exec sbx exec -it -w "$REPO_ROOT" "$SANDBOX_NAME" \
+            bash -lc 'ai-sbx-workspace'
+        ;;
+esac
+```
+
+`bash -lc` is mandatory. `/etc/sandbox-persistent.sh` is where PATH, the mise shims,
+the AWS credentials and every secret placeholder live; a non-login shell loses all of
+it, and the symptom is "npm cannot authenticate", nothing that points at tmux.
+
+Agent arguments (`run -- --foo`) apply to `agent` mode only. In `tmux` mode they are
+rejected with an explanatory error rather than silently dropped.
+
+### The launcher
+
+Shipped as a file in this repository at `tasks/ai/workspace`, installed into the
+sandbox at `~/.local/bin/ai-sbx-workspace` by a new `install_sandbox_workspace`,
+alongside the existing mise install. If the image already provides
+`/usr/local/bin/ai-sbx-workspace` (see the image spec) the copy is skipped, and the
+image's copy is built from this same file so the two cannot diverge.
+
+Behaviour:
+
+| Requirement | Detail |
+| --- | --- |
+| Attach-or-create | If session `ai-sbx` exists, attach. Never create a second one |
+| Three windows | `agent`, `edit`, `shell`, in that order |
+| Working directory | All three start in the workspace root |
+| Agent window | Runs `claude --dangerously-skip-permissions` |
+| Edit window | Runs `nvim .` |
+| Shell window | Left at a prompt |
+| Selected window | `agent` |
+
+The agent command is **observed**, not assumed: attaching with `sbx run` and sampling
+the process table inside the sandbox shows `claude --dangerously-skip-permissions`.
+
+Because it is agent-specific, resolve it through a small mapping keyed on
+`CONFIG_AGENT`, defaulting to the bare agent name for agents whose invocation has not
+been observed. Getting this wrong for `claude` would silently change the agent's
+permission model, so the `claude` entry must be exact.
+
+Degrade rather than fail: if `tmux` is missing in the sandbox, print how to install it
+(`AI_SBX_TOOLS`, or the custom image) and fall back to launching the agent directly.
+
+## 2. Dotfiles
+
+### Configuration
+
+| Surface | Values | Default |
+| --- | --- | --- |
+| `AI_SBX_DOTFILES` | `chezmoi`, unset | unset (off) |
+| `~/.config/ai-sbx/dotfiles` | newline-separated target allowlist | required when enabled |
+
+### Mechanism
+
+Host-side render, copy in. No repo clone, no age key, no network inside the sandbox:
+
+```bash
+DEV_CONTAINER=1 chezmoi archive --format tar <target>... |
+    sbx exec -i "$SANDBOX_NAME" tar -x -C "$sandbox_home"
+```
+
+`DEV_CONTAINER=1` is required. The existing `.chezmoi.toml.tmpl` branches on it and
+setting it disables `git.autoCommit` and `git.autoPush` — without it an agent in the
+sandbox could push to the dotfiles repo.
+
+### The allowlist is a security control, not a convenience
+
+`chezmoi archive` **decrypts as it renders**. A full archive of the current source
+contains, in plaintext:
+
+```text
+.config/gh/hosts.yml            GitHub CLI auth tokens
+.npmrc                          npm registry tokens
+.nuget/NuGet/NuGet.Config       NuGet credentials
+.ssh/config
+.mcp.json
+.aider.conf.yml
+```
+
+Copying those in would hand the agent the credentials this project deliberately keeps
+out — the GitHub token is proxy-injected as an unreadable placeholder, and
+`hosts.yml` would defeat that in one step.
+
+Therefore:
+
+1. **Allowlist only.** A denylist rots as new encrypted files appear, and the failure
+   mode is silent credential exfiltration.
+2. **Refuse on overlap.** Enumerate every `encrypted_*` file in `chezmoi source-path`,
+   resolve each with `chezmoi target-path`, and `die` if any resolved target is inside
+   the allowlist. Verified working: all six current entries resolve correctly.
+3. **Scan the rendered archive** for credential shapes before it enters the sandbox,
+   reusing the guard already in the template build script.
+
+Note `.config/fish/conf.d/tokens.fish` is **not** encrypted but is named as though it
+holds secrets. Anything selected must be reviewed once by a human; the tooling cannot
+infer intent from a filename.
+
+### Suggested starting allowlist
+
+```text
+.config/nvim
+.tmux.conf
+.gitconfig
+```
+
+## Tests
+
+Following the existing suite: pure functions and source-level assertions, no sandbox.
+
+| Test | Asserts |
+| --- | --- |
+| launch default | unset `AI_SBX_LAUNCH` → `agent` |
+| launch override | `--launch tmux` beats the variable |
+| launch validation | an unknown value exits non-zero |
+| dispatch | stubbed `sbx` shows `sbx run` for `agent`, `sbx exec -it` for `tmux` |
+| login shell | the tmux branch contains `bash -lc` |
+| agent command | the `claude` mapping is exactly `claude --dangerously-skip-permissions` |
+| launcher | `bash -n` clean, shellcheck clean, creates exactly three windows |
+| dotfiles overlap | an allowlist containing an encrypted target exits non-zero |
+| dotfiles off | unset `AI_SBX_DOTFILES` performs no chezmoi call |
+
+Each must fail when its guard is removed — the same regression check used for the
+non-interactive and multi-line-network tests.
+
+## Acceptance
+
+1. Neither variable set → `run` behaves exactly as today.
+2. `AI_SBX_LAUNCH=tmux` → three windows, agent running in the first, all in the
+   workspace root.
+3. Detach, re-run → reattaches to the same session with the agent's context intact.
+4. In the shell window, `npm ci` in `webui/` still authenticates, proving the
+   environment survived the login shell.
+5. `--launch agent` overrides the variable for one run.
+6. `AI_SBX_DOTFILES=chezmoi` with a valid allowlist → those targets appear in the
+   sandbox and no file from the encrypted set does.
+7. Adding an encrypted target to the allowlist → setup fails with a clear message.
+
+## Out of scope
+
+- A `kind: sandbox` kit that makes `sbx run` itself open tmux. Considered and
+  rejected in the plan: it requires declaring the whole agent and satisfying the base
+  image contract, for a launch preference.
+- Persisting launch mode per repository.
+- Dotfiles managers other than chezmoi.
@@ -3,10 +3,33 @@ set -euo pipefail

 PROGRAM="ai:sbx"
 CONFIG_ROOT="${XDG_CONFIG_HOME:-$HOME/.config}/ai-sbx"
-DEFAULT_AGENT="${AI_SBX_AGENT:-codex}"
+DEFAULT_AGENT="${AI_SBX_AGENT:-claude}"
 DEFAULT_MODE="${AI_SBX_MODE:-clone}"
 DEFAULT_TOKEN_DAYS="${AI_SBX_TOKEN_DAYS:-30}"
 DEFAULT_TEMPLATE="${AI_SBX_TEMPLATE:-}"
+DEFAULT_TOOLS="${AI_SBX_TOOLS:-bun}"
+DEFAULT_NETWORK="${AI_SBX_NETWORK:-}"
+DEFAULT_LAUNCH="${AI_SBX_LAUNCH:-agent}"
+DEFAULT_DOTFILES="${AI_SBX_DOTFILES:-}"
+
+# Rendered dotfiles are checked for these before the archive enters the sandbox.
+# chezmoi archive decrypts as it renders, so this is the last line of defence
+# behind the allowlist rather than the first.
+DOTFILES_CREDENTIAL_PATTERNS=(
+    'gh[pousr]_[A-Za-z0-9]{16,}'
+    'github_pat_[A-Za-z0-9_]{20,}'
+    '-----BEGIN [A-Z ]*PRIVATE KEY-----'
+    'AKIA[0-9A-Z]{16}'
+    '_authToken[[:space:]]*='
+    'aws_secret_access_key'
+)
+
+# VAR|host[,host...]|requirement. Provisioned for every repository when the
+# variable is present in the host environment. "docker" skips the entry on a
+# sandbox that cannot run containers, where the credential would be useless.
+HOST_WIDE_SECRETS=(
+    "LOCALSTACK_AUTH_TOKEN|localstack.cloud,*.localstack.cloud|docker"
+)
 CLAUDE_HOME="${CLAUDE_HOME:-$HOME/.claude}"

 # Only these leave the host. ~/.claude also holds OAuth credentials, shell
@@ -36,14 +59,17 @@ TOKEN_URL_PERMISSIONS=(
    actions=write
    statuses=read
    security_events=write
+    secret_scanning_alerts=read
+    vulnerability_alerts=read
 )

-# GitHub omits these from the pre-fill parameters, so they can only be ticked
-# on the form itself.
-TOKEN_MANUAL_PERMISSIONS=(
-    "Checks: Read"
-    "Dependabot alerts: Read"
-    "Secret scanning alerts: Read"
+# Fine-grained tokens cannot reach the Checks API at all: GitHub's permission
+# reference has no Checks section and lists no check-run endpoint, so there is
+# no box to tick. Both calls below degrade to empty output rather than a
+# permission error, which reads as broken CI unless it is called out.
+TOKEN_LIMITATIONS=(
+    "gh pr checks     shows only commit statuses, not check runs"
+    "gh run view      returns no annotations"
 )

 usage() {
@@ -53,12 +79,14 @@ Usage:
  mise run ai:sbx -- token
  mise run ai:sbx -- refresh
  mise run ai:sbx -- config
-  mise run ai:sbx -- run [-- agent arguments...]
+  mise run ai:sbx -- run [--launch agent|tmux] [-- agent arguments...]
  mise run ai:sbx -- status
  mise run ai:sbx -- remove

-Setup opens a pre-filled GitHub token form in your browser. Use "token" on
-its own to replace an expired or revoked token later.
+Setup opens a pre-filled GitHub token form in your browser, unless a token is
+already stored for the sandbox. The secret store outlives the sandbox, so
+recreating one with --replace keeps its token. Use "token" on its own to
+replace an expired or revoked token.

 Set AI_SBX_TEMPLATE in your mise config to reuse one custom image across
 every repository without repeating --template.
@@ -68,6 +96,31 @@ AGENTS.md, agents, commands, hooks, skills) into the sandbox and installs the
 marketplaces and plugins your host has enabled. Credentials, transcripts and
 history are never copied. Use "config" to re-apply after the host changes.

+Registry credentials are declared per repository in the user's config
+directory as a "secrets" file, one line of VAR|host|command each. The command
+runs on the host and its output becomes an sbx custom secret, so the sandbox
+sees a placeholder and the proxy substitutes the real value.
+LOCALSTACK_AUTH_TOKEN is provisioned for every repository when it is set on
+the host and the sandbox has Docker to make use of it.
+
+AI_SBX_NETWORK lists hosts to allow through the sandbox network policy, comma
+or space separated. Hosts backing a provisioned secret are allowed
+automatically, since a credential for a denied host can never be used.
+
+AI_SBX_LAUNCH selects what "run" attaches to: "agent" starts the agent alone
+and is the default, "tmux" attaches to a three-window workspace (agent, edit,
+shell) that survives detaching. --launch overrides it for one run. Agent
+arguments apply to "agent" only.
+
+AI_SBX_DOTFILES=chezmoi renders the host's chezmoi dotfiles into the sandbox.
+It requires an allowlist of target paths, one per line, in the user's config
+directory as a "dotfiles" file. chezmoi decrypts as it renders, so setup
+refuses to run when an encrypted file resolves inside the allowlist.
+
+AI_SBX_TOOLS lists mise tools installed globally in the sandbox, defaulting
+to bun because several Claude plugins run their hooks under it. Set it to an
+empty string to install none.
+
 Setup and run install mise in the sandbox and resolve the repository's
 pinned tools, so the agent runs the same versions you do. A personal
 mise config that must stay out of the repository goes in the per-repository
@@ -79,7 +132,7 @@ Setup options:
                         May be supplied more than once. A trailing
                         -readonly is stripped from the profile name
                         written into the sandbox.
-  --agent NAME           Sandbox agent. Default: codex
+  --agent NAME           Sandbox agent. Default: claude
  --direct               Mount the host working tree read-write.
  --clone                Give the agent a private in-container clone
                         of the repository, mounted read-only.
@@ -191,6 +244,17 @@ read_token() {
    printf '%s' "$token"
 }

+# Only a token scoped to this sandbox counts. A global one would authenticate
+# the agent too, but reaching every repository the token can reach is exactly
+# what this task exists to prevent, so it is not treated as satisfying setup.
+sandbox_has_github_token() {
+    sbx secret ls 2>/dev/null |
+        awk -v scope="$SANDBOX_NAME" '
+            $1 == scope && $2 == "service" && $3 == "github" { found = 1 }
+            END { exit !found }
+        '
+}
+
 install_github_token() {
    local url
    url="$(token_url)"
@@ -202,16 +266,20 @@ Create a fine-grained token for $REPOSITORY.
 Everything except the repository is pre-filled. On the page:

  1. Repository access -> Only select repositories -> ${REPOSITORY#*/}
-  2. Tick the permissions the form cannot pre-fill:
+  2. Generate token, then paste it below.
+
+Every permission is pre-filled. Fine-grained tokens cannot read check runs,
+so inside the sandbox:
 EOF

-    local permission
-    for permission in "${TOKEN_MANUAL_PERMISSIONS[@]}"; do
-        printf '       %s\n' "$permission" >&2
+    local limitation
+    for limitation in "${TOKEN_LIMITATIONS[@]}"; do
+        printf '  %s\n' "$limitation" >&2
    done

-    cat >&2 <<EOF
-  3. Generate token, then paste it below.
+    cat >&2 <<'EOF'
+
+A 403 will name what it wanted in the X-Accepted-GitHub-Permissions header.

 EOF

@@ -557,6 +625,25 @@ EOF
    done
 }

+# Not @tsv: tab is an IFS whitespace character, so read collapses the empty
+# field an entry without a repo produces and shifts the URL into it.
+host_marketplaces() {
+    jq -r '
+        to_entries[]
+        | [
+            .key,
+            (.value.source.source // ""),
+            (.value.source.repo // ""),
+            (.value.source.url // "")
+          ]
+        | join("|")
+    ' "$1"
+}
+
+host_enabled_plugins() {
+    jq -r '(.enabledPlugins // {}) | to_entries[] | select(.value) | .key' "$1"
+}
+
 marketplace_url() {
    local source_kind="$1"
    local repo="$2"
@@ -634,7 +721,10 @@ install_sandbox_claude_config() {

    # The store is shared by every sandbox, so this seeds all of them at once.
    if [[ -d "$CLAUDE_HOME/skills" ]]; then
-        sbx skills import >/dev/null 2>&1 ||
+        # --force is mandatory: the store is shared, so a second setup finds
+        # skills already there and prompts per skill. With output redirected
+        # the prompt is invisible and setup hangs on stdin forever.
+        sbx skills import --force </dev/null >/dev/null 2>&1 ||
            printf 'Could not import skills into the shared store.\n' >&2
    fi

@@ -671,9 +761,7 @@ install_sandbox_claude_plugins() {
        host="${host%%/*}"

        if [[ "$host" != "github.com" ]]; then
-            sbx policy allow network \
-                --sandbox "$SANDBOX_NAME" "$host" \
-                </dev/null >/dev/null 2>&1 || true
+            allow_sandbox_host "$host"
        fi

        # Without </dev/null sbx exec drains the loop's input and only the
@@ -683,18 +771,7 @@ install_sandbox_claude_plugins() {
            </dev/null >/dev/null 2>&1 ||
            printf 'Could not add marketplace %s (%s).\n' \
                "$name" "$marketplace" >&2
-    done < <(
-        jq -r '
-            to_entries[]
-            | [
-                .key,
-                (.value.source.source // ""),
-                (.value.source.repo // ""),
-                (.value.source.url // "")
-              ]
-            | join("|")
-        ' "$known"
-    )
+    done < <(host_marketplaces "$known")

    local plugin
    while read -r plugin; do
@@ -706,10 +783,208 @@ install_sandbox_claude_plugins() {
        else
            printf 'Could not install plugin %s\n' "$plugin" >&2
        fi
-    done < <(
-        jq -r '(.enabledPlugins // {}) | to_entries[] | select(.value) | .key' \
-            "$settings"
-    )
+    done < <(host_enabled_plugins "$settings")
+}
+
+# A repository declares which registry credentials it needs, but the declaration
+# lives in the user's own config rather than the repository, so a checkout can
+# never choose which host commands run or which secrets get resolved.
+#
+#   VAR | host[,host...] | command printing the value on stdout
+#
+# The command runs on the host, from the repository root, where 1Password and
+# the developer's keychain are available.
+read_secret_declarations() {
+    local file="$REPO_CONFIG_DIR/secrets"
+
+    [[ -f "$file" ]] || return 0
+
+    local line var hosts command
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        line="${line%%#*}"
+        [[ -n "${line//[[:space:]]/}" ]] || continue
+
+        IFS='|' read -r var hosts command <<<"$line"
+
+        var="$(printf '%s' "$var" | xargs)"
+        hosts="$(printf '%s' "$hosts" | xargs)"
+        command="$(printf '%s' "$command" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+
+        [[ -n "$var" && -n "$hosts" && -n "$command" ]] || {
+            printf 'Ignoring malformed secret declaration: %s\n' "$line" >&2
+            continue
+        }
+
+        printf '%s|%s|%s\n' "$var" "$hosts" "$command"
+    done <"$file"
+}
+
+# Derived rather than random so re-running setup does not invalidate the value
+# already exported inside a running sandbox. The placeholder is not a secret;
+# it is the stand-in the proxy swaps for one.
+secret_placeholder() {
+    local var="$1" digest
+
+    digest="$(printf '%s' "$REPOSITORY/$var" | sha256sum | cut -c1-16)"
+    printf 'sbx-cs-%s' "$digest"
+}
+
+allow_sandbox_host() {
+    local host="$1"
+
+    [[ -n "$host" ]] || return 0
+
+    sbx policy allow network --sandbox "$SANDBOX_NAME" "$host" \
+        </dev/null >/dev/null 2>&1 || true
+}
+
+# The default policy denies everything outside common development hosts, so a
+# private registry is unreachable no matter what credential it holds.
+install_sandbox_network() {
+    [[ -n "$DEFAULT_NETWORK" ]] || return 0
+
+    # A multi-line TOML string is a natural way to write a long list, and read
+    # stops at the first newline, so separators are flattened before splitting.
+    local normalized="${DEFAULT_NETWORK//,/ }"
+    normalized="${normalized//$'\n'/ }"
+    normalized="${normalized//$'\r'/ }"
+
+    local -a allow_hosts
+    read -r -a allow_hosts <<<"$normalized"
+
+    ((${#allow_hosts[@]})) || return 0
+
+    local host
+    for host in "${allow_hosts[@]}"; do
+        allow_sandbox_host "$host"
+    done
+
+    printf 'Allowed network access to: %s\n' "${allow_hosts[*]}"
+}
+
+sandbox_has_docker() {
+    sbx exec "$SANDBOX_NAME" \
+        bash -lc 'command -v docker >/dev/null' \
+        </dev/null >/dev/null 2>&1
+}
+
+provision_secret() {
+    local var="$1" hosts="$2" value="$3"
+    local placeholder
+    placeholder="$(secret_placeholder "$var")"
+
+    local -a host_args=()
+    local host
+    for host in ${hosts//,/ }; do
+        host_args+=(--host "$host")
+
+        # A credential for a host the policy denies is dead weight: the request
+        # never leaves the sandbox, so the proxy never substitutes anything.
+        allow_sandbox_host "$host"
+    done
+
+    # Piped rather than --value: the secret would otherwise be visible in the
+    # process list to anything running as this user.
+    printf '%s' "$value" |
+        sbx secret set-custom "$SANDBOX_NAME" \
+            "${host_args[@]}" \
+            --env "$var" \
+            --placeholder "$placeholder" >/dev/null 2>&1 ||
+        {
+            printf 'Could not store %s in the sandbox.\n' "$var" >&2
+            return 1
+        }
+
+    # A sandbox that already exists keeps whatever environment it was created
+    # with, so the placeholder is exported explicitly.
+    sbx exec "$SANDBOX_NAME" bash -c "
+        persistent=/etc/sandbox-persistent.sh
+        marker=$(printf '%q' "# ai-sbx secret $var")
+
+        grep -Fq \"\$marker\" \"\$persistent\" 2>/dev/null && exit 0
+
+        printf '%s\nexport %s=%s\n' \
+            \"\$marker\" $(printf '%q' "$var") $(printf '%q' "$placeholder") \
+            >>\"\$persistent\"
+    " </dev/null >/dev/null 2>&1 || true
+
+    printf 'Provisioned %s for %s\n' "$var" "${hosts//,/, }"
+}
+
+# Credentials worth provisioning for every repository rather than declaring per
+# repository, taken straight from the host environment. LocalStack only matters
+# when the agent can run containers, so it is skipped where Docker is absent.
+install_host_wide_secrets() {
+    local entry var hosts requirement
+
+    for entry in "${HOST_WIDE_SECRETS[@]}"; do
+        IFS='|' read -r var hosts requirement <<<"$entry"
+
+        [[ -n "${!var:-}" ]] || continue
+
+        if [[ "$requirement" == docker ]] && ! sandbox_has_docker; then
+            printf 'Skipping %s: the sandbox has no Docker to run it.\n' "$var" >&2
+            continue
+        fi
+
+        provision_secret "$var" "$hosts" "${!var}" || true
+    done
+}
+
+install_sandbox_secrets() {
+    install_host_wide_secrets
+
+    local declarations
+    declarations="$(read_secret_declarations)" || return 0
+
+    [[ -n "$declarations" ]] || return 0
+
+    local var hosts command value
+
+    while IFS='|' read -r var hosts command; do
+        [[ -n "$var" ]] || continue
+
+        # The resolver prints guidance to stderr naming where to obtain the
+        # credential, which is more useful than anything this task could add.
+        if ! value="$(cd "$REPO_ROOT" && eval "$command" 2>&1)"; then
+            printf 'Could not resolve %s:\n%s\n' "$var" "$value" >&2
+            continue
+        fi
+
+        [[ -n "$value" ]] || {
+            printf 'Resolver for %s printed nothing.\n' "$var" >&2
+            continue
+        }
+
+        provision_secret "$var" "$hosts" "$value" || true
+
+        unset value
+    done <<<"$declarations"
+}
+
+# Plugins bring their own runtime requirements - claude-mem and others run
+# their hooks under bun, which the sandbox image does not carry - and a missing
+# one surfaces as a hook error on every prompt rather than at install time.
+install_sandbox_tools() {
+    local sandbox_home="$1"
+
+    [[ -n "$DEFAULT_TOOLS" ]] || return 0
+
+    local -a tools
+    read -r -a tools <<<"$DEFAULT_TOOLS"
+
+    ((${#tools[@]})) || return 0
+
+    printf 'Installing sandbox tools: %s\n' "${tools[*]}"
+
+    # mise resolves these from GitHub releases, which the default network
+    # policy already allows. $HOME and $@ belong to the sandbox shell.
+    # shellcheck disable=SC2016
+    sbx exec "$SANDBOX_NAME" bash -lc '
+        export PATH="$HOME/.local/bin:$HOME/.local/share/mise/shims:$PATH"
+        mise use -g "$@" && mise reshim
+    ' _ "${tools[@]}" </dev/null >/dev/null 2>&1 ||
+        printf 'Could not install sandbox tools: %s\n' "${tools[*]}" >&2
 }

 install_sandbox_mise() {
@@ -738,6 +1013,8 @@ install_sandbox_mise() {
        sbx cp "$host_mise" "$SANDBOX_NAME:$sandbox_home/.local/bin/mise"
    fi

+    install_sandbox_tools "$sandbox_home"
+
    local personal="$REPO_CONFIG_DIR/mise.local.toml"
    if [[ -f "$personal" ]]; then
        sbx cp "$personal" "$SANDBOX_NAME:$REPO_ROOT/mise.local.toml"
@@ -791,6 +1068,187 @@ EOF
    '
 }

+# A sandbox image ships without a locale, which leaves LC_CTYPE at POSIX. Every
+# multibyte glyph then degrades to a placeholder: Nerd Font icons in the editor
+# render as underscores, and bash printf emits \uXXXX escapes literally. LANG
+# alone is enough, and leaves a user free to override individual categories.
+install_sandbox_locale() {
+    # shellcheck disable=SC2016
+    sbx exec "$SANDBOX_NAME" bash -c '
+        persistent=/etc/sandbox-persistent.sh
+        marker="# BEGIN ai-sbx locale"
+
+        if grep -Fq "$marker" "$persistent" 2>/dev/null; then
+            exit 0
+        fi
+
+        # locale -a spells these inconsistently across distributions, so probe
+        # each one for usability rather than matching its name.
+        for candidate in C.UTF-8 en_US.UTF-8; do
+            if LC_ALL="$candidate" locale >/dev/null 2>&1; then
+                chosen="$candidate"
+                break
+            fi
+        done
+
+        [[ -n "${chosen:-}" ]] || exit 0
+
+        cat >>"$persistent" <<EOF
+# BEGIN ai-sbx locale
+export LANG=$chosen
+# END ai-sbx locale
+EOF
+    ' </dev/null >/dev/null 2>&1 || true
+}
+
+validate_launch_mode() {
+    case "$1" in
+        agent | tmux) ;;
+        *)
+            die "Unknown launch mode: $1 (expected agent or tmux)"
+            ;;
+    esac
+}
+
+# The image may already carry the launcher. Its copy is built from this same
+# file, so the two cannot drift, and skipping keeps a custom image authoritative
+# about its own contents.
+install_sandbox_workspace() {
+    local launcher
+    launcher="$(dirname "${BASH_SOURCE[0]}")/workspace"
+
+    [[ -f "$launcher" ]] ||
+        die "Workspace launcher is missing: $launcher"
+
+    if sbx exec "$SANDBOX_NAME" \
+        bash -c '[[ -x /usr/local/bin/ai-sbx-workspace ]]' \
+        </dev/null >/dev/null 2>&1; then
+        return 0
+    fi
+
+    local sandbox_home
+    # shellcheck disable=SC2016
+    sandbox_home="$(sbx exec "$SANDBOX_NAME" bash -c 'printf %s "$HOME"')"
+
+    [[ -n "$sandbox_home" ]] ||
+        die "Could not determine the sandbox home directory."
+
+    # shellcheck disable=SC2016
+    sbx exec "$SANDBOX_NAME" bash -c 'mkdir -p "$HOME/.local/bin"'
+
+    sbx cp "$launcher" "$SANDBOX_NAME:$sandbox_home/.local/bin/ai-sbx-workspace"
+
+    # shellcheck disable=SC2016
+    sbx exec "$SANDBOX_NAME" bash -c 'chmod 755 "$HOME/.local/bin/ai-sbx-workspace"'
+}
+
+# One target path per line, relative to the home directory. Comments and blank
+# lines are ignored.
+read_dotfiles_allowlist() {
+    local file="$CONFIG_ROOT/dotfiles"
+
+    [[ -f "$file" ]] ||
+        die "AI_SBX_DOTFILES is set but $file does not exist. List one target path per line, for example .config/nvim"
+
+    local line
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        line="${line%%#*}"
+        line="$(printf '%s' "$line" | xargs)"
+
+        [[ -n "$line" ]] || continue
+
+        printf '%s\n' "$line"
+    done <"$file"
+}
+
+# chezmoi archive decrypts as it renders, so an encrypted file inside the
+# allowlist would arrive in the sandbox as plaintext credentials - defeating the
+# proxy-injected GitHub token in a single step. A denylist would rot as new
+# encrypted files appear, and the failure mode is silent, so refuse instead.
+assert_no_encrypted_targets() {
+    local source_dir
+    source_dir="$(chezmoi source-path)" ||
+        die "Could not determine the chezmoi source directory."
+
+    local encrypted target allowed
+    while IFS= read -r encrypted; do
+        [[ -n "$encrypted" ]] || continue
+
+        target="$(chezmoi target-path "$encrypted" 2>/dev/null)" || continue
+        target="${target#"$HOME/"}"
+
+        for allowed in "$@"; do
+            [[ "$target" == "$allowed" || "$target" == "$allowed"/* ]] ||
+                continue
+
+            die "Dotfiles allowlist entry $allowed contains the encrypted file $target, which chezmoi would render in plaintext. Narrow $CONFIG_ROOT/dotfiles."
+        done
+    done < <(find "$source_dir" -type f -name '*encrypted_*' 2>/dev/null)
+}
+
+scan_dotfiles_archive() {
+    local archive="$1" pattern
+
+    for pattern in "${DOTFILES_CREDENTIAL_PATTERNS[@]}"; do
+        grep -aEq -- "$pattern" "$archive" ||
+            continue
+
+        die "The rendered dotfiles archive contains something shaped like a credential (matching /$pattern/). Narrow $CONFIG_ROOT/dotfiles."
+    done
+}
+
+# Rendered on the host, where the age identity already lives, and copied in as a
+# tar. The sandbox needs no dotfiles repository, no key and no network for this.
+install_sandbox_dotfiles() {
+    [[ -n "$DEFAULT_DOTFILES" ]] || return 0
+
+    [[ "$DEFAULT_DOTFILES" == chezmoi ]] ||
+        die "Unknown AI_SBX_DOTFILES value: $DEFAULT_DOTFILES (expected chezmoi)"
+
+    require_command chezmoi
+
+    local -a targets
+    mapfile -t targets < <(read_dotfiles_allowlist)
+
+    ((${#targets[@]})) ||
+        die "The dotfiles allowlist $CONFIG_ROOT/dotfiles is empty."
+
+    assert_no_encrypted_targets "${targets[@]}"
+
+    local -a target_paths=()
+    local target
+    for target in "${targets[@]}"; do
+        target_paths+=("$HOME/$target")
+    done
+
+    local archive
+    archive="$(mktemp)"
+    trap 'rm -f "$archive"' RETURN
+
+    # DEV_CONTAINER=1 is required, not cosmetic: .chezmoi.toml.tmpl branches on
+    # it to disable git.autoCommit and git.autoPush, and without it an agent in
+    # the sandbox could push to the dotfiles repository.
+    DEV_CONTAINER=1 chezmoi archive --format tar "${target_paths[@]}" >"$archive" ||
+        die "chezmoi could not render the dotfiles archive."
+
+    scan_dotfiles_archive "$archive"
+
+    local sandbox_home
+    # shellcheck disable=SC2016
+    sandbox_home="$(sbx exec "$SANDBOX_NAME" bash -c 'printf %s "$HOME"')"
+
+    [[ -n "$sandbox_home" ]] ||
+        die "Could not determine the sandbox home directory."
+
+    sbx exec -i "$SANDBOX_NAME" tar -x -C "$sandbox_home" <"$archive" ||
+        die "Could not unpack the dotfiles archive in $SANDBOX_NAME."
+
+    rm -f "$archive"
+    trap - RETURN
+
+    printf 'Installed dotfiles into %s: %s\n' "$SANDBOX_NAME" "${targets[*]}"
+}
+
 create_sandbox() {
    load_config

@@ -897,7 +1355,7 @@ setup_command() {
    if sandbox_exists; then
        if [[ "$replace" == true ]]; then
            printf 'Removing existing sandbox %s...\n' "$SANDBOX_NAME"
-            sbx rm "$SANDBOX_NAME"
+            sbx rm --force "$SANDBOX_NAME" </dev/null
        else
            printf 'Using existing sandbox %s.\n' "$SANDBOX_NAME"
        fi
@@ -909,12 +1367,26 @@ setup_command() {
        create_sandbox
    fi

-    install_github_token
+    # The secret store outlives the sandbox, so recreating one to change its
+    # image keeps the token. Prompting anyway would train the habit of minting
+    # replacement tokens and never revoking the old ones.
+    if sandbox_has_github_token; then
+        printf 'Keeping the GitHub token already stored for %s. Replace it with: mise run ai:sbx -- token\n' \
+            "$SANDBOX_NAME"
+    else
+        install_github_token
+    fi

    install_sandbox_aws_files

    install_sandbox_claude_config

+    install_sandbox_dotfiles
+
+    install_sandbox_network
+
+    install_sandbox_secrets
+
    install_sandbox_mise

    cat <<EOF
@@ -960,9 +1432,42 @@ config_command() {
        die "Sandbox does not exist. Run: mise run ai:sbx -- setup"

    install_sandbox_claude_config
+
+    install_sandbox_dotfiles
+
+    install_sandbox_network
+
+    install_sandbox_secrets
 }

 run_command() {
+    local launch="$DEFAULT_LAUNCH"
+
+    # Everything after -- belongs to the agent, including anything that looks
+    # like an option of this task.
+    while (($#)); do
+        case "$1" in
+            --launch)
+                (($# >= 2)) || die "--launch requires a value"
+                launch="$2"
+                shift 2
+                ;;
+            --)
+                shift
+                break
+                ;;
+            *)
+                break
+                ;;
+        esac
+    done
+
+    validate_launch_mode "$launch"
+
+    if [[ "$launch" == tmux ]] && (($#)); then
+        die "Agent arguments are only supported with --launch agent; got: $*"
+    fi
+
    load_config

    sandbox_exists ||
@@ -976,8 +1481,16 @@ run_command() {
    # runs every time rather than only at setup.
    install_sandbox_mise

-    if (($#)) && [[ "$1" == "--" ]]; then
-        shift
+    install_sandbox_locale
+
+    if [[ "$launch" == tmux ]]; then
+        install_sandbox_workspace
+
+        # bash -lc is mandatory: /etc/sandbox-persistent.sh is where PATH, the
+        # mise shims, the AWS credentials and every secret placeholder live, and
+        # the tmux server inherits its environment from this shell.
+        exec sbx exec -it -w "$REPO_ROOT" "$SANDBOX_NAME" \
+            bash -lc "ai-sbx-workspace $(printf '%q' "$CONFIG_AGENT")"
    fi

    if (($#)); then
@@ -1030,7 +1543,7 @@ remove_command() {
    load_config

    if sandbox_exists; then
-        sbx rm "$SANDBOX_NAME"
+        sbx rm --force "$SANDBOX_NAME" </dev/null
    fi

    rm -rf "$REPO_CONFIG_DIR"
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Runs inside the sandbox as ai-sbx-workspace. The caller must start it from a
+# login shell: the tmux server inherits this process's environment, so PATH, the
+# mise shims, the AWS credentials and every secret placeholder reach all three
+# windows through it. A non-login shell here loses the lot, and the symptom is
+# "npm cannot authenticate" rather than anything that points at tmux.
+
+SESSION=ai-sbx
+
+# The claude invocation is observed, not assumed: sampling the process table of
+# a sandbox attached with "sbx run" shows this exact command line. Getting it
+# wrong would silently change the agent's permission model, so agents whose
+# invocation has not been observed fall back to the bare name.
+agent_command() {
+    case "$1" in
+        claude)
+            printf '%s' 'claude --dangerously-skip-permissions'
+            ;;
+        *)
+            printf '%s' "$1"
+            ;;
+    esac
+}
+
+main() {
+    local agent="${1:-claude}"
+    local agent_cmd
+    agent_cmd="$(agent_command "$agent")"
+
+    if ! command -v tmux >/dev/null 2>&1; then
+        printf '%s\n' \
+            'tmux is not installed in this sandbox; starting the agent directly.' \
+            '' \
+            'Add tmux to AI_SBX_TOOLS, or use a custom image that carries it:' \
+            '' \
+            '  AI_SBX_TOOLS = "bun tmux neovim"' \
+            '' >&2
+        # Deliberate word splitting: the command comes from the mapping above.
+        # shellcheck disable=SC2086
+        exec $agent_cmd
+    fi
+
+    # Attach-or-create. Detaching and re-running must land back in the same
+    # session with the agent's context intact, which is most of the point.
+    if tmux has-session -t "$SESSION" 2>/dev/null; then
+        exec tmux attach-session -t "$SESSION"
+    fi
+
+    tmux new-session -d -s "$SESSION" -n agent -c "$PWD"
+    tmux new-window -t "$SESSION:" -n edit -c "$PWD"
+    tmux new-window -t "$SESSION:" -n shell -c "$PWD"
+
+    tmux send-keys -t "$SESSION:agent" "$agent_cmd" C-m
+    tmux send-keys -t "$SESSION:edit" 'nvim .' C-m
+
+    tmux select-window -t "$SESSION:agent"
+    exec tmux attach-session -t "$SESSION"
+}
+
+main "$@"
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=tasks/ai/sbx
+source "$(dirname "${BASH_SOURCE[0]}")/../tasks/ai/sbx"
+
+failures=0
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    failures=$((failures + 1))
+}
+
+assert_url() {
+    local kind="$1" repo="$2" url="$3" expected="$4" actual
+
+    if actual="$(marketplace_url "$kind" "$repo" "$url")"; then
+        [[ "$actual" == "$expected" ]] ||
+            fail "marketplace_url $kind '$repo' '$url' gave '$actual', expected '$expected'"
+    else
+        [[ "$expected" == "<fail>" ]] ||
+            fail "marketplace_url $kind '$repo' '$url' failed, expected '$expected'"
+    fi
+}
+
+assert_url github obra/superpowers-marketplace "" \
+    "https://github.com/obra/superpowers-marketplace.git"
+assert_url git "" https://git.example.com/x.git "https://git.example.com/x.git"
+
+assert_url github "" "" "<fail>"
+assert_url git "" "" "<fail>"
+assert_url local /some/path "" "<fail>"
+
+cat >"$work/known_marketplaces.json" <<'EOF'
+{
+  "superpowers-marketplace": {
+    "source": { "source": "github", "repo": "obra/superpowers-marketplace" }
+  },
+  "mroberts": {
+    "source": { "source": "git", "url": "https://git.mroberts.dev/mroberts/claude-plugin.git" }
+  },
+  "bundled": {
+    "source": { "source": "local" }
+  }
+}
+EOF
+
+mapfile -t lines < <(host_marketplaces "$work/known_marketplaces.json")
+
+((${#lines[@]} == 3)) ||
+    fail "expected 3 marketplace lines, got ${#lines[@]}"
+
+IFS='|' read -r name kind repo url <<<"${lines[1]}"
+[[ "$name" == "mroberts" ]] || fail "name mis-parsed: $name"
+[[ "$kind" == "git" ]] || fail "source kind mis-parsed: $kind"
+[[ -z "$repo" ]] || fail "absent repo should be empty, got '$repo'"
+[[ "$url" == "https://git.mroberts.dev/mroberts/claude-plugin.git" ]] ||
+    fail "url shifted into the wrong field: '$url'"
+
+IFS='|' read -r name kind repo url <<<"${lines[2]}"
+[[ "$kind" == "local" ]] || fail "unsupported kind mis-parsed: $kind"
+marketplace_url "$kind" "$repo" "$url" >/dev/null 2>&1 &&
+    fail "a local marketplace should be rejected, not turned into a URL"
+
+cat >"$work/settings.json" <<'EOF'
+{
+  "enabledPlugins": {
+    "caveman@caveman": true,
+    "ponytail@ponytail": true,
+    "disabled-thing@somewhere": false
+  },
+  "other": "ignored"
+}
+EOF
+
+mapfile -t plugins < <(host_enabled_plugins "$work/settings.json")
+
+((${#plugins[@]} == 2)) ||
+    fail "expected 2 enabled plugins, got ${#plugins[@]}: ${plugins[*]}"
+
+printf '%s\n' "${plugins[@]}" | grep -qx 'disabled-thing@somewhere' &&
+    fail "a disabled plugin was treated as enabled"
+
+printf '%s\n' "${plugins[@]}" | grep -qx 'caveman@caveman' ||
+    fail "an enabled plugin is missing"
+
+printf '{}\n' >"$work/empty.json"
+mapfile -t none < <(host_enabled_plugins "$work/empty.json")
+((${#none[@]} == 0)) || fail "empty settings produced ${#none[@]} plugins"
+
+for forbidden in .credentials.json projects transcripts history.jsonl file-history cache backups; do
+    printf '%s\n' "${CLAUDE_CONFIG_ALLOW[@]}" | grep -qx "$forbidden" &&
+        fail "CLAUDE_CONFIG_ALLOW must not carry $forbidden"
+done
+
+printf '%s\n' "${CLAUDE_CONFIG_ALLOW[@]}" | grep -qx skills &&
+    fail "skills must not be copied; it is seeded with 'sbx skills import'"
+
+printf '%s\n' "${CLAUDE_CONFIG_ALLOW[@]}" | grep -qx CLAUDE.md ||
+    fail "CLAUDE_CONFIG_ALLOW should carry CLAUDE.md"
+
+if ((failures)); then
+    printf '%d assertion(s) failed\n' "$failures" >&2
+    exit 1
+fi
+
+printf 'All Claude manifest assertions passed.\n'
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=tasks/ai/sbx
+source "$(dirname "${BASH_SOURCE[0]}")/../tasks/ai/sbx"
+
+failures=0
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    failures=$((failures + 1))
+}
+
+HOME="$work/home"
+CONFIG_ROOT="$work/config"
+SANDBOX_NAME=ai-test
+mkdir -p "$HOME" "$CONFIG_ROOT" "$work/source/dot_config/nvim"
+
+: >"$work/source/dot_config/nvim/encrypted_private_secrets.lua.age"
+: >"$work/source/encrypted_private_dot_npmrc.age"
+
+chezmoi_calls=0
+chezmoi() {
+    chezmoi_calls=$((chezmoi_calls + 1))
+
+    case "$1" in
+        source-path)
+            printf '%s\n' "$work/source"
+            ;;
+        target-path)
+            case "$2" in
+                *nvim*) printf '%s/.config/nvim/secrets.lua\n' "$HOME" ;;
+                *) printf '%s/.npmrc\n' "$HOME" ;;
+            esac
+            ;;
+        archive)
+            printf 'archive\n'
+            ;;
+    esac
+}
+
+sbx() {
+    cat >/dev/null 2>&1 || true
+    printf '%s\n' "$HOME"
+}
+
+printf '%s\n' '.tmux.conf' '# a comment' '' '.gitconfig' >"$CONFIG_ROOT/dotfiles"
+mapfile -t entries < <(read_dotfiles_allowlist)
+[[ "${entries[*]}" == ".tmux.conf .gitconfig" ]] ||
+    fail "the allowlist should drop comments and blanks, got: ${entries[*]}"
+
+if (assert_no_encrypted_targets .config/nvim) 2>/dev/null; then
+    fail "an allowlist entry containing an encrypted target was accepted"
+fi
+
+if (assert_no_encrypted_targets .npmrc) 2>/dev/null; then
+    fail "an allowlist entry that is itself an encrypted target was accepted"
+fi
+
+(assert_no_encrypted_targets .tmux.conf .gitconfig) 2>/dev/null ||
+    fail "an allowlist with no encrypted targets was rejected"
+
+chezmoi_calls=0
+DEFAULT_DOTFILES="" install_sandbox_dotfiles >/dev/null
+((chezmoi_calls == 0)) ||
+    fail "AI_SBX_DOTFILES unset must not call chezmoi at all"
+
+if (DEFAULT_DOTFILES=stow install_sandbox_dotfiles) >/dev/null 2>&1; then
+    fail "an unknown AI_SBX_DOTFILES value was accepted"
+fi
+
+printf 'token: github_pat_%s\n' "$(printf 'a%.0s' {1..30})" >"$work/archive"
+if (scan_dotfiles_archive "$work/archive") 2>/dev/null; then
+    fail "a rendered archive holding a GitHub token was accepted"
+fi
+
+printf 'set -g mouse on\n' >"$work/archive"
+(scan_dotfiles_archive "$work/archive") 2>/dev/null ||
+    fail "a clean archive was rejected"
+
+if ((failures)); then
+    printf '%d assertion(s) failed\n' "$failures" >&2
+    exit 1
+fi
+
+printf 'All dotfiles assertions passed.\n'
@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TASK="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/tasks/ai/sbx"
+
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=tasks/ai/sbx
+source "$TASK"
+
+failures=0
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    failures=$((failures + 1))
+}
+
+SANDBOX_NAME=ai-repo-abc123
+
+listing=""
+sbx() {
+    printf '%s\n' "$listing"
+}
+
+with_listing() {
+    listing="$1"
+    sandbox_has_github_token
+}
+
+full_listing() {
+    cat <<'EOF'
+SCOPE                TYPE      NAME        SECRET
+ai-repo-abc123       service   github      (stored)
+(global)             service   anthropic   (oauth configured)
+
+CUSTOM SECRETS
+SCOPE                TARGETS                   ENV                     PLACEHOLDER          SECRET
+ai-repo-abc123       localstack.cloud          LOCALSTACK_AUTH_TOKEN   sbx-cs-0c2f39c1      ls-vOL***
+EOF
+}
+
+with_listing "$(full_listing)" ||
+    fail "a sandbox-scoped github token was not detected"
+
+with_listing "$(
+    cat <<'EOF'
+SCOPE                TYPE      NAME        SECRET
+(global)             service   anthropic   (oauth configured)
+EOF
+)" && fail "no github token stored, yet setup would have been skipped"
+
+with_listing "$(
+    cat <<'EOF'
+SCOPE                TYPE      NAME        SECRET
+(global)             service   github      (stored)
+EOF
+)" && fail "a global github token must not satisfy a per-repository sandbox"
+
+with_listing "$(
+    cat <<'EOF'
+SCOPE                TYPE      NAME        SECRET
+ai-other-sandbox     service   github      (stored)
+EOF
+)" && fail "another sandbox's github token must not count as this one's"
+
+with_listing "$(
+    cat <<'EOF'
+CUSTOM SECRETS
+SCOPE                TARGETS       ENV      PLACEHOLDER     SECRET
+ai-repo-abc123       github.com    github   sbx-cs-abc      gh***
+EOF
+)" && fail "a custom secret must not be mistaken for the stored service token"
+
+with_listing "" &&
+    fail "empty output should mean no token, not a stored one"
+
+grep -q 'if sandbox_has_github_token; then' "$TASK" ||
+    fail "setup no longer guards install_github_token"
+
+awk '/^token_command\(\)/, /^}/' "$TASK" | grep -q 'install_github_token' ||
+    fail "the token command must always prompt; it is the way to replace one"
+
+awk '/^token_command\(\)/, /^}/' "$TASK" | grep -q 'sandbox_has_github_token' &&
+    fail "the token command must not skip when a token exists"
+
+if ((failures)); then
+    printf '%d assertion(s) failed\n' "$failures" >&2
+    exit 1
+fi
+
+printf 'All GitHub token assertions passed.\n'
@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TASK="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/tasks/ai/sbx"
+
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=tasks/ai/sbx
+source "$TASK"
+
+failures=0
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    failures=$((failures + 1))
+}
+
+mkdir -p "$work/bin"
+cat >"$work/bin/sbx" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >>"$SBX_LOG"
+EOF
+chmod 755 "$work/bin/sbx"
+PATH="$work/bin:$PATH"
+export PATH
+
+SANDBOX_NAME=ai-test
+REPO_ROOT=/workspace/repo
+CONFIG_AGENT=claude
+SBX_LOG="$work/log"
+export SBX_LOG
+
+dispatch() {
+    : >"$SBX_LOG"
+
+    (
+        load_config() { :; }
+        sandbox_exists() { :; }
+        install_sandbox_aws_files() { :; }
+        install_sandbox_mise() { :; }
+        install_sandbox_workspace() { :; }
+
+        run_command "$@"
+    ) >/dev/null 2>&1 || true
+
+    cat "$SBX_LOG"
+}
+
+(
+    unset AI_SBX_LAUNCH
+    # shellcheck source=tasks/ai/sbx
+    source "$TASK"
+    [[ "$DEFAULT_LAUNCH" == agent ]]
+) || fail "AI_SBX_LAUNCH unset should default to agent"
+
+(
+    AI_SBX_LAUNCH=tmux
+    export AI_SBX_LAUNCH
+    # shellcheck source=tasks/ai/sbx
+    source "$TASK"
+    [[ "$DEFAULT_LAUNCH" == tmux ]]
+) || fail "AI_SBX_LAUNCH=tmux was not read into DEFAULT_LAUNCH"
+
+DEFAULT_LAUNCH=agent
+[[ "$(dispatch)" == *"run ai-test"* ]] ||
+    fail "agent mode should dispatch to sbx run: $(dispatch)"
+
+DEFAULT_LAUNCH=tmux
+tmux_dispatch="$(dispatch)"
+[[ "$tmux_dispatch" == *"exec -it -w /workspace/repo ai-test"* ]] ||
+    fail "tmux mode should dispatch to sbx exec -it: $tmux_dispatch"
+[[ "$tmux_dispatch" == *"bash -lc ai-sbx-workspace claude"* ]] ||
+    fail "tmux mode must use a login shell and pass the agent: $tmux_dispatch"
+[[ "$tmux_dispatch" != *"run ai-test"* ]] ||
+    fail "tmux mode should not also call sbx run: $tmux_dispatch"
+
+DEFAULT_LAUNCH=tmux
+[[ "$(dispatch --launch agent)" == *"run ai-test"* ]] ||
+    fail "--launch agent should beat AI_SBX_LAUNCH=tmux"
+
+DEFAULT_LAUNCH=agent
+[[ "$(dispatch --launch tmux)" == *"exec -it"* ]] ||
+    fail "--launch tmux should beat AI_SBX_LAUNCH=agent"
+
+DEFAULT_LAUNCH=agent
+[[ "$(dispatch -- --resume)" == *"run ai-test -- --resume"* ]] ||
+    fail "agent arguments should still reach sbx run"
+
+DEFAULT_LAUNCH=agent
+[[ "$(dispatch -- --launch tmux)" == *"run ai-test -- --launch tmux"* ]] ||
+    fail "--launch after -- belongs to the agent, not to the task"
+
+DEFAULT_LAUNCH=agent
+locale_dispatch="$(dispatch)"
+[[ "$locale_dispatch" == *"BEGIN ai-sbx locale"* ]] ||
+    fail "run should install a UTF-8 locale, or Nerd Font glyphs render as placeholders: $locale_dispatch"
+[[ "$locale_dispatch" == *"LC_ALL=\"\$candidate\" locale"* ]] ||
+    fail "the locale must be probed for usability, not matched by name against locale -a"
+
+if (validate_launch_mode bogus) 2>/dev/null; then
+    fail "an unknown launch mode was accepted"
+fi
+
+if (
+    DEFAULT_LAUNCH=agent
+    load_config() { :; }
+    sandbox_exists() { :; }
+    install_sandbox_aws_files() { :; }
+    install_sandbox_mise() { :; }
+    run_command --launch bogus
+) >/dev/null 2>&1; then
+    fail "run --launch bogus should exit non-zero"
+fi
+
+if (
+    DEFAULT_LAUNCH=tmux
+    load_config() { :; }
+    sandbox_exists() { :; }
+    install_sandbox_aws_files() { :; }
+    install_sandbox_mise() { :; }
+    install_sandbox_workspace() { :; }
+    run_command -- --resume
+) >/dev/null 2>&1; then
+    fail "agent arguments in tmux mode should be rejected, not dropped"
+fi
+
+if ((failures)); then
+    printf '%d assertion(s) failed\n' "$failures" >&2
+    exit 1
+fi
+
+printf 'All launch mode assertions passed.\n'
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=tasks/ai/sbx
+source "$(dirname "${BASH_SOURCE[0]}")/../tasks/ai/sbx"
+
+failures=0
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    failures=$((failures + 1))
+}
+
+SANDBOX_NAME=ai-test
+REPOSITORY=owner/repo
+
+allowed=""
+sbx() {
+    if [[ "$1 $2" == "policy allow" ]]; then
+        allowed+="${*: -1} "
+    fi
+    cat >/dev/null 2>&1 || true
+}
+
+allowed=""
+DEFAULT_NETWORK="a.example.com,b.example.com c.example.com" install_sandbox_network >/dev/null
+for host in a.example.com b.example.com c.example.com; do
+    [[ "$allowed" == *"$host"* ]] ||
+        fail "install_sandbox_network skipped $host (comma and space must both split)"
+done
+
+allowed=""
+DEFAULT_NETWORK="$(printf '*.nuget.org,\nregistry.terraform.io,\nmise.jdx.dev')" \
+    install_sandbox_network >/dev/null
+for host in '*.nuget.org' registry.terraform.io mise.jdx.dev; do
+    [[ "$allowed" == *"$host"* ]] ||
+        fail "multi-line AI_SBX_NETWORK dropped $host"
+done
+
+allowed=""
+DEFAULT_NETWORK="" install_sandbox_network >/dev/null
+[[ -z "${allowed// /}" ]] ||
+    fail "an empty AI_SBX_NETWORK should allow nothing, got: $allowed"
+
+allowed=""
+provision_secret TOKEN "reg.example.com,*.cdn.example.com" secret-value >/dev/null
+[[ "$allowed" == *"reg.example.com"* ]] ||
+    fail "provision_secret did not allow reg.example.com"
+[[ "$allowed" == *"*.cdn.example.com"* ]] ||
+    fail "provision_secret did not allow the wildcard host"
+
+allowed=""
+provision_secret TOKEN '*.localstack.cloud' secret-value >/dev/null
+[[ "$allowed" == *'*.localstack.cloud'* ]] ||
+    fail "wildcard host was mangled: '$allowed'"
+
+allowed=""
+allow_sandbox_host "" >/dev/null
+[[ -z "${allowed// /}" ]] || fail "an empty host should be ignored"
+
+if ((failures)); then
+    printf '%d assertion(s) failed\n' "$failures" >&2
+    exit 1
+fi
+
+printf 'All network policy assertions passed.\n'
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TASK="$(dirname "${BASH_SOURCE[0]}")/../tasks/ai/sbx"
+
+failures=0
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    failures=$((failures + 1))
+}
+
+code() {
+    grep -n '^[^#]*sbx ' "$TASK" | grep -v 'ai:sbx'
+}
+
+require_force() {
+    local pattern="$1" line
+    local found=false
+
+    while IFS= read -r line; do
+        found=true
+        [[ "$line" == *"--force"* ]] ||
+            fail "missing --force, will block on a prompt: ${line#*:}"
+    done < <(code | grep -F "$pattern" || true)
+
+    [[ "$found" == true ]] ||
+        fail "no invocation of '$pattern' found; has it been renamed?"
+}
+
+require_force 'sbx secret set '
+require_force 'sbx skills import'
+require_force 'sbx rm '
+
+while IFS= read -r line; do
+    [[ "$line" == *"</dev/null"* ]] ||
+        fail "missing </dev/null: ${line#*:}"
+done < <(code | grep -F 'sbx skills import' || true)
+
+if ((failures)); then
+    printf '%d assertion(s) failed\n' "$failures" >&2
+    exit 1
+fi
+
+printf 'All non-interactive invocation assertions passed.\n'
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=tasks/ai/sbx
+source "$(dirname "${BASH_SOURCE[0]}")/../tasks/ai/sbx"
+
+failures=0
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    failures=$((failures + 1))
+}
+
+REPOSITORY="CareEvolution/api-portal"
+REPO_CONFIG_DIR="$work"
+
+cat >"$work/secrets" <<'EOF'
+# Registry credentials for this repository
+FONTAWESOME_API_KEY | npm.fontawesome.com | scripts/npm-auth.sh print FONTAWESOME_API_KEY
+
+  PROGET_NPM_TOKEN|proget.careevolution.com|scripts/npm-auth.sh print PROGET_NPM_TOKEN
+MULTI | a.example.com,b.example.com | echo hi   # trailing comment
+
+MISSING_COMMAND | host.example.com
+NO_HOST || echo hi
+EOF
+
+mapfile -t lines < <(read_secret_declarations 2>/dev/null)
+
+((${#lines[@]} == 3)) ||
+    fail "expected 3 valid declarations, got ${#lines[@]}: ${lines[*]}"
+
+IFS='|' read -r var hosts command <<<"${lines[0]}"
+[[ "$var" == "FONTAWESOME_API_KEY" ]] || fail "var mis-parsed: '$var'"
+[[ "$hosts" == "npm.fontawesome.com" ]] || fail "hosts mis-parsed: '$hosts'"
+[[ "$command" == "scripts/npm-auth.sh print FONTAWESOME_API_KEY" ]] ||
+    fail "command mis-parsed: '$command'"
+
+IFS='|' read -r var hosts command <<<"${lines[1]}"
+[[ "$var" == "PROGET_NPM_TOKEN" ]] || fail "unpadded var mis-parsed: '$var'"
+[[ "$hosts" == "proget.careevolution.com" ]] || fail "unpadded host mis-parsed: '$hosts'"
+
+IFS='|' read -r var hosts command <<<"${lines[2]}"
+[[ "$hosts" == "a.example.com,b.example.com" ]] || fail "multi-host mis-parsed: '$hosts'"
+[[ "$command" == "echo hi" ]] || fail "trailing comment not stripped: '$command'"
+
+printf '%s\n' "${lines[@]}" | grep -q MISSING_COMMAND &&
+    fail "a declaration without a command was accepted"
+printf '%s\n' "${lines[@]}" | grep -q NO_HOST &&
+    fail "a declaration without a host was accepted"
+
+REPO_CONFIG_DIR="$work/nonexistent"
+mapfile -t none < <(read_secret_declarations 2>/dev/null)
+((${#none[@]} == 0)) || fail "absent file produced ${#none[@]} declarations"
+
+first="$(secret_placeholder FONTAWESOME_API_KEY)"
+second="$(secret_placeholder FONTAWESOME_API_KEY)"
+[[ "$first" == "$second" ]] || fail "placeholder is not stable: $first vs $second"
+
+[[ "$first" == sbx-cs-* ]] || fail "placeholder lacks the sbx-cs- prefix: $first"
+
+[[ "$(secret_placeholder PROGET_NPM_TOKEN)" != "$first" ]] ||
+    fail "two variables share one placeholder"
+
+REPOSITORY="other/repo"
+[[ "$(secret_placeholder FONTAWESOME_API_KEY)" != "$first" ]] ||
+    fail "placeholder does not vary by repository"
+
+for entry in "${HOST_WIDE_SECRETS[@]}"; do
+    IFS='|' read -r var hosts requirement <<<"$entry"
+
+    [[ -n "$var" ]] || fail "host-wide entry has no variable: $entry"
+    [[ -n "$hosts" ]] || fail "host-wide entry $var has no hosts"
+    [[ "$requirement" == docker || "$requirement" == "-" ]] ||
+        fail "host-wide entry $var has an unknown requirement: '$requirement'"
+done
+
+printf '%s\n' "${HOST_WIDE_SECRETS[@]}" | grep -q '^LOCALSTACK_AUTH_TOKEN|' ||
+    fail "LOCALSTACK_AUTH_TOKEN should be provisioned host-wide"
+
+printf '%s\n' "${HOST_WIDE_SECRETS[@]}" | grep '^LOCALSTACK_AUTH_TOKEN|' |
+    grep -q 'localstack\.cloud' ||
+    fail "LOCALSTACK_AUTH_TOKEN must target localstack.cloud"
+
+if ((failures)); then
+    printf '%d assertion(s) failed\n' "$failures" >&2
+    exit 1
+fi
+
+printf 'All secret declaration assertions passed.\n'
@@ -59,13 +59,24 @@ done < <(printf '%s\n' "${TOKEN_URL_PERMISSIONS[@]}" | cut -d= -f2)
 printf '%s\n' "${TOKEN_URL_PERMISSIONS[@]}" | grep -qx 'workflows=write' ||
    fail "workflows must be requested at write"

-for unsupported in checks= vulnerability_alerts= secret_scanning_alerts= repository=; do
+for unsupported in checks= repository=; do
    [[ "$query" != *"$unsupported"* ]] ||
        fail "URL sends a parameter the form ignores: $unsupported"
 done

-[[ ${#TOKEN_MANUAL_PERMISSIONS[@]} -eq 3 ]] ||
-    fail "expected 3 manually-ticked permissions, found ${#TOKEN_MANUAL_PERMISSIONS[@]}"
+for expected in secret_scanning_alerts=read vulnerability_alerts=read statuses=read actions=write; do
+    [[ "$query" == *"&$expected"* ]] ||
+        fail "permission dropped out of the pre-filled URL: $expected"
+done
+
+((${#TOKEN_LIMITATIONS[@]})) ||
+    fail "the limitations list is empty; the Checks gap must be stated"
+
+printf '%s\n' "${TOKEN_LIMITATIONS[@]}" | grep -q 'gh pr checks' ||
+    fail "the limitations must name gh pr checks"
+
+printf '%s\n' "${TOKEN_LIMITATIONS[@]}" | grep -qi 'tick\|check the box' &&
+    fail "the limitations must not imply Checks can be granted"

 if ((failures)); then
    printf '%d assertion(s) failed\n' "$failures" >&2
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LAUNCHER="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/tasks/ai/workspace"
+
+failures=0
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+fail() {
+    printf 'FAIL: %s\n' "$1" >&2
+    failures=$((failures + 1))
+}
+
+mkdir -p "$work/bin"
+
+cat >"$work/bin/tmux" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >>"$TMUX_LOG"
+
+if [[ "$1" == has-session ]]; then
+    exit "${TMUX_HAS_SESSION:-1}"
+fi
+EOF
+
+cat >"$work/bin/claude" <<'EOF'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >>"$TMUX_LOG"
+EOF
+
+chmod 755 "$work/bin/tmux" "$work/bin/claude"
+
+TMUX_LOG="$work/log"
+export TMUX_LOG
+
+launch() {
+    : >"$TMUX_LOG"
+    PATH="$work/bin:$PATH" bash "$LAUNCHER" "$@" >/dev/null 2>&1
+    cat "$TMUX_LOG"
+}
+
+bash -n "$LAUNCHER" ||
+    fail "the launcher is not syntactically valid"
+
+if command -v shellcheck >/dev/null 2>&1; then
+    shellcheck "$LAUNCHER" ||
+        fail "the launcher is not shellcheck clean"
+fi
+
+log="$(launch claude)"
+
+windows="$(grep -cE 'new-session|new-window' <<<"$log")"
+[[ "$windows" == 3 ]] ||
+    fail "expected exactly three windows, got $windows: $log"
+
+for window in agent edit shell; do
+    grep -qE "(new-session|new-window).* -n $window " <<<"$log" ||
+        fail "no window named $window: $log"
+done
+
+grep -qF 'send-keys -t ai-sbx:agent claude --dangerously-skip-permissions C-m' <<<"$log" ||
+    fail "the claude mapping must be exactly claude --dangerously-skip-permissions: $log"
+
+grep -qF 'send-keys -t ai-sbx:edit nvim . C-m' <<<"$log" ||
+    fail "the edit window should open nvim: $log"
+
+grep -qF 'select-window -t ai-sbx:agent' <<<"$log" ||
+    fail "the agent window should be selected: $log"
+
+grep -qF 'attach-session -t ai-sbx' <<<"$log" ||
+    fail "the launcher should attach to the session: $log"
+
+log="$(launch codex)"
+grep -qF 'send-keys -t ai-sbx:agent codex C-m' <<<"$log" ||
+    fail "an unobserved agent should fall back to its bare name: $log"
+
+TMUX_HAS_SESSION=0
+export TMUX_HAS_SESSION
+log="$(launch claude)"
+if grep -qE 'new-session|new-window' <<<"$log"; then
+    fail "an existing session must be attached to, never rebuilt: $log"
+fi
+grep -qF 'attach-session -t ai-sbx' <<<"$log" ||
+    fail "an existing session should be attached to: $log"
+unset TMUX_HAS_SESSION
+
+mkdir -p "$work/bare"
+# shellcheck disable=SC2016
+printf '#!%s\nprintf %%s "$*" >>"$TMUX_LOG"\n' "$(command -v bash)" \
+    >"$work/bare/claude"
+chmod 755 "$work/bare/claude"
+
+: >"$TMUX_LOG"
+PATH="$work/bare" "$(command -v bash)" "$LAUNCHER" claude >/dev/null 2>&1 ||
+    fail "the launcher should not fail when tmux is missing"
+fallback="$(cat "$TMUX_LOG")"
+[[ "$fallback" == '--dangerously-skip-permissions' ]] ||
+    fail "without tmux the launcher should exec the agent, logged: $fallback"
+
+if ((failures)); then
+    printf '%d assertion(s) failed\n' "$failures" >&2
+    exit 1
+fi
+
+printf 'All workspace launcher assertions passed.\n'
Author	SHA1	Message	Date
mroberts	b5dfae0696	Keep the stored GitHub token when setup runs again The secret store outlives the sandbox, so recreating one to change its image or add a profile does not lose the token. Prompting for a replacement anyway made --replace impractical and trained the habit of minting tokens that are never revoked. Only a token scoped to this sandbox counts. A global one would authenticate the agent too, but reaching every repository it can reach is what this task exists to prevent. The token command still always prompts; it is the way to replace an expired or revoked token.	2026-08-03 16:09:44 -05:00
mroberts	53db7df812	Give the sandbox a UTF-8 locale A sandbox image ships without a locale, leaving LC_CTYPE at POSIX. Every multibyte glyph then degrades to a placeholder, so Nerd Font icons in the editor render as underscores and bash printf emits \uXXXX escapes literally. The locale is probed for usability rather than matched by name, because locale -a spells C.UTF-8 as C.utf8 on glibc and a name match would silently find nothing. LANG alone is set, leaving individual categories overridable.	2026-08-03 15:26:41 -05:00
mroberts	14165503d5	Launch a tmux workspace and carry dotfiles into the sandbox AI_SBX_LAUNCH=tmux (or run --launch tmux) attaches to a three-window tmux session - agent, edit, shell - instead of the bare agent. The launcher is vendored at tasks/ai/workspace and installed into the sandbox, so a custom image and this task cannot drift. It is invoked through a login shell because /etc/sandbox-persistent.sh is where PATH, the mise shims, the AWS credentials and every secret placeholder live, and the tmux server hands that environment to all three windows. AI_SBX_DOTFILES=chezmoi renders the host chezmoi target state and unpacks it into the sandbox, so no dotfiles repository, decryption key or network access is needed inside. chezmoi archive decrypts as it renders, so the target list is an allowlist, encrypted files resolving inside it are refused, and the rendered archive is scanned for credential shapes before it enters the sandbox. Both default to off; with neither set, run behaves exactly as before.	2026-08-03 13:49:24 -05:00
mroberts	ad2b33f984	Split a multi-line AI_SBX_NETWORK correctly A long host list is naturally written as a multi-line TOML string, but read stops at the first newline, so only the first host was ever allowed. The rest failed later as connection errors with nothing pointing back at the list. Newlines and carriage returns are now flattened alongside commas before splitting, and the test covers a multi-line value; it fails without the fix. Also records the measured host requirements for a full Neovim configuration. The Balanced policy already permits github, npm, pypi, crates, go, ubuntu, nodejs, hashicorp releases, Copilot and the LLM APIs, which covers 93 lazy.nvim plugins, both mason registries and all 55 mason packages. Only the .NET and Terraform registries need declaring.	2026-08-03 12:37:53 -05:00
mroberts	2890b1dd98	Open the network policy for hosts a sandbox actually needs Sandboxes default to a deny-everything-else policy, so the registry credentials provisioned as custom secrets were unusable: npm.fontawesome.com, proget.careevolution.com and localstack.cloud were all denied, and the request never left the sandbox for the proxy to substitute a token into. The failure looked like a connection error rather than a policy decision. Provisioning a secret now allows its hosts in the same step, since a credential for a denied host cannot be used by definition. AI_SBX_NETWORK declares any further hosts, comma or space separated, for private registries that back no secret. The marketplace loop's inline policy call moves into the shared helper so the two cannot drift. The Balanced policy already permits github.com, codeload and the githubusercontent hosts, registry.npmjs.org, pypi.org, files.pythonhosted.org, crates.io and the Go proxies, so npm, pip, cargo, go and a plugin-managed Neovim need nothing declared. Only private hosts do.	2026-08-03 10:42:56 -05:00
mroberts	d2b7a5ef63	Provision LOCALSTACK_AUTH_TOKEN for every repository LocalStack is a common enough dependency that declaring it per repository is busywork, and the token is already in the host environment when it is needed at all. It is now provisioned host-wide, through the same custom-secret path as the per-repository declarations, so the value stays out of the sandbox and the proxy substitutes it on requests to localstack.cloud. Provisioning is conditional on the sandbox having Docker. LocalStack runs as a container, so on a sandbox created from a non-docker template the credential would be dead weight, and the entry is skipped with a message rather than stored. An unset variable is skipped silently, which costs nothing on a machine that never uses LocalStack. The provisioning body moves into provision_secret so the host-wide and per-repository paths cannot drift apart.	2026-07-31 12:09:56 -05:00
mroberts	93dc61a024	Provision repository registry credentials as sandbox secrets Repositories need registry tokens to install dependencies, and those live behind 1Password or a keychain that only exists on the host. A secrets file in the user's per-repository config names each variable, the hosts it authenticates to, and a command that prints it; the command runs on the host from the repository root and its output becomes an sbx custom secret. Custom secrets keep the value out of the sandbox entirely: the environment variable is set to a placeholder and the proxy substitutes the real secret into outbound request headers for the declared hosts. A committed .npmrc using ${VAR} interpolation therefore works unchanged while the agent sees only the placeholder. Placeholders are derived from the repository and variable name so re-running setup does not invalidate one already exported into a running sandbox, and the value is piped rather than passed as --value, which would put it in the process list. The declaration lives in user config rather than the repository for the same reason AWS profile approval does: a checkout must not choose which host commands run or which credentials resolve. A failed resolver has its own stderr surfaced, since it names where to obtain the credential, and the remaining secrets still provision. sbx secret set-custom was measured to overwrite silently and has no --force flag, so the non-interactive test now matches sbx secret set precisely rather than by prefix.	2026-07-31 11:42:36 -05:00
mroberts	c195a82b82	Install plugin runtimes into the sandbox Claude plugins bring their own runtime requirements. claude-mem and others run their hooks under bun, which the sandbox image does not carry, so installing plugins left every prompt in the sandbox failing with a Bun not found hook error - after setup had reported success, since the dependency only surfaces when a hook fires. AI_SBX_TOOLS lists mise tools to install globally in the sandbox and defaults to bun. mise is already present and resolves these from GitHub releases, which the default network policy allows. Setting the variable to an empty string installs nothing.	2026-07-31 09:12:00 -05:00
mroberts	6f4ba117b4	Stop setup blocking on invisible sbx confirmation prompts sbx skills import prompts before overwriting each skill already in the shared store. setup called it with stdout and stderr redirected and stdin left attached, so on any second run the prompt was invisible and setup hung indefinitely partway through installing the Claude configuration. sbx rm prompts the same way, which would have blocked --replace and remove once a sandbox was in use. Both now pass --force and read from /dev/null. This is the third instance of the pattern after sbx secret set, which cancelled silently and still exited 0, so a test now asserts at the source level that every prompting subcommand is invoked non-interactively. The test was confirmed to fail when either --force is removed.	2026-07-31 09:04:21 -05:00
mroberts	5e167d3a0d	State the Checks API gap instead of prescribing an impossible tick Fine-grained tokens have no Checks permission. GitHub's permission reference lists no Checks section and no check-run endpoint, and checks is absent from the token form's pre-fill parameters, so the earlier instruction to tick Checks: Read asked for a box that does not exist. A token created with every listed permission still could not read check runs, which is what surfaced this. The prompt now states the consequence rather than offering a remedy: gh pr checks reports commit statuses only and gh run view returns no annotations. Both degrade to empty output rather than a permission error, so without the note they read as a broken CI integration. Job logs are unaffected; they fall under Actions, which is granted. secret_scanning_alerts and vulnerability_alerts move into the pre-filled URL, leaving nothing for the operator to tick beyond repository selection.	2026-07-31 08:48:26 -05:00
mroberts	b8bf9f9eff	Pre-fill the alert permissions and test the plugin manifest parsing Two of the three permissions treated as manual are in fact pre-fillable. The earlier check scraped the rendered docs page, whose table splits those rows in a way the parse missed; the docs source lists secret_scanning_alerts and vulnerability_alerts as supported query parameters. Only checks is genuinely absent, so the manual list shrinks to that one entry. That entry now names what breaks without it. Checks: Read governs the status rollup behind gh pr checks and the annotations behind gh run view, and both degrade to empty results rather than permission errors, so an unticked box reads as a broken CI integration rather than a missing scope. The marketplace and enabled-plugin extraction move out of the install function into host_marketplaces and host_enabled_plugins so they can be exercised directly. The tests cover the pipe separator that keeps an absent repo from shifting a url leftwards, rejection of marketplace sources that are neither github nor git, disabled plugins being excluded, and the allowlist refusing to carry credentials, transcripts or history.	2026-07-31 08:42:28 -05:00
mroberts	dbe6c2e34b	Default the sandbox agent to claude The Claude configuration, plugin and skills support added for sandboxes only applies when the agent is claude, so codex was no longer the sensible default.	2026-07-31 08:39:30 -05:00