diff --git a/README.md b/README.md
index 5a5df3e..8e5b1bf 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,10 @@ Most agents need no plugin: add the MCP server `https://mcp.box.simular.ai/mcp`
 | Any of Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Hermes, OpenClaw, VS Code (and steps for Claude Desktop) | [`cli/`](cli/) | OAuth; personal key with `--auth key` for Hermes and OpenClaw | `npx @simular-ai/box connect` (check with `npx @simular-ai/box doctor`) |
 | Hermes Agent | [`hermes/`](hermes/) | Personal key (`cb_...`) in `MCP_BOX_API_KEY`; OAuth optional | [hermes/README.md](hermes/README.md) |
 
+## Offload: move a coding task into your box and back
+
+Going offline in the middle of a task? In Claude Code with the plugin, `/box:offload` hands the task to a fresh Claude Code (or Codex, Cursor) session in your box, which keeps working while you are away; `/box:back` brings its commits and its written hand-over home and merges them. Any other agent or a plain terminal uses `npx @simular-ai/box offload` and `npx @simular-ai/box back`. Setup and details: [cli/README.md](cli/README.md#offload).
+
 ## Adding an agent
 
 Add a folder named after the agent with its own manifest, MCP config and, where the agent supports skills, a copy of `claude/skills/box/SKILL.md`. Point it at `https://mcp.box.simular.ai/mcp`. Use OAuth sign-in where the agent supports it; otherwise read a personal key from an environment variable or the agent's own credentials store, never from a file in the package. Add a row above.
diff --git a/claude/.claude-plugin/plugin.json b/claude/.claude-plugin/plugin.json
index b512aab..af3d7de 100644
--- a/claude/.claude-plugin/plugin.json
+++ b/claude/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "box",
   "displayName": "box by Simular",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Give Claude a computer of its own: a cloud Linux desktop with Chrome and a shell that it drives over MCP, while your own computer stays free. You sign in once in the browser; no key to paste.",
   "author": {
     "name": "Simular",
diff --git a/claude/commands/back.md b/claude/commands/back.md
new file mode 100644
index 0000000..9d67e1e
--- /dev/null
+++ b/claude/commands/back.md
@@ -0,0 +1,5 @@
+---
+description: Bring the task back from my box and continue it here
+---
+
+Use the box-offload skill: BACK. $ARGUMENTS
diff --git a/claude/commands/offload.md b/claude/commands/offload.md
new file mode 100644
index 0000000..c7efe9a
--- /dev/null
+++ b/claude/commands/offload.md
@@ -0,0 +1,5 @@
+---
+description: Move this coding task into my box, where an agent keeps working on it
+---
+
+Use the box-offload skill: OFFLOAD this task to my box. $ARGUMENTS
diff --git a/claude/skills/box-offload/SKILL.md b/claude/skills/box-offload/SKILL.md
new file mode 100644
index 0000000..1a99c19
--- /dev/null
+++ b/claude/skills/box-offload/SKILL.md
@@ -0,0 +1,95 @@
+---
+name: box-offload
+description: Hand this coding task to an agent in the user's box (their cloud computer) and take it back. Use when the user says offload, "move this to my box", "keep working while I'm away", "I'm back" or "bring it back", or when a message is exactly OFFLOAD or BACK.
+---
+
+The agent in the box starts fresh. It knows only what your hand-over says, plus the repo.
+Write the hand-over as if for a capable engineer who has never seen this conversation.
+`box` below is `npx -y @simular-ai/box@^0.2.0`. Run it in the repo the user works in. It does every
+mechanical step: never copy files or secrets yourself, never print a secret, never edit the
+files it writes.
+
+## OFFLOAD
+
+1. Finish the step you are in, or stop at a safe point. Do not start new work.
+2. Run `box offload handover-path` in the repo and write the hand-over to the path it
+   prints, with the template below. Fill every section; write "none" for an empty one. Be
+   concrete: exact commands, versions you saw, file paths, error messages, decisions with
+   their reasons. Under "Secrets needed" give names only, never values.
+3. Run `box offload --kind claude` (or the CLI the user asked for in the box:
+   `codex`, `cursor`). Add `--box NAME` when the user names a box.
+   - "not signed in": ask the user to run `box login` in their terminal (it opens the
+     browser), then run offload again.
+   - Exit 3 is a block: stop and tell the user why, one line per finding. If the box CLI is
+     missing or signed out, tell the user to run, in their own terminal,
+     `box offload install-cli --kind <K>` and then `box offload sign-in --kind <K>`
+     (the sign-in asks them to approve in the browser and paste a code, so you cannot do it).
+   - Exit 4 is warnings: tell the user each one, and run again with `--yes` only when they
+     agree, or said beforehand to go ahead.
+   - For a secret it warns about, ask the user; only they opt one in
+     (`box offload secrets add file:.env`). Never opt in on your own.
+4. When it prints `offloaded`, tell the user the box, that its agent runs with permission
+   prompts bypassed, and that `/box:back` returns the work. End your turn and make no more
+   changes to this repo.
+5. On exit 1, report its last line. Nothing changed on this computer; do not retry by hand.
+
+While the task is in the box, `box offload inbox` shows what the box agent posted
+(progress, questions), `box offload send "<answer>"` answers it, and
+`box offload status` shows whether it is working. The user can watch its terminal with
+the `rsh -t ... tmux attach` line offload printed.
+
+## BACK
+
+Run `box back` in the repo. It waits for the box agent to go idle, then up to 10 minutes in
+all for its hand-over, then lands the box's work against the snapshot taken at the offload.
+Report how the code landed, as its first line says: fast-forward (the branch now points at
+the box's commit), merged (the branch moved to the box's commit, or the box's changes applied
+uncommitted, with any uncommitted paths listed), unchanged, or a branch with conflicts, where
+your work tree is untouched. If it says nothing of this repo is in a box and names a
+`back.md`, the work has landed already: read that file as the hand-over. Then check the
+hand-over's claims against `git log` and `git diff`, run its verify commands, and continue
+from its next steps.
+
+## Hand-over template
+
+```markdown
+# Hand-over: <one-line goal>
+
+From: <local | box>   Agent: <claude|codex|cursor>   Repo: <path>   Branch: <branch> @ <short sha>
+
+## Goal and definition of done
+<what the user asked for, in their words where it matters; what "done" means>
+
+## User preferences and constraints
+<style, scope limits, things the user said not to do, deadlines; or none>
+
+## Current state
+<where the work stands in one paragraph: what works, what is broken, what is half-done>
+
+## Decisions made
+- <decision> — <why>; rejected: <alternative and why>
+
+## Files touched
+- `<path>` — <what changed and why; whether it is finished>
+
+## Next steps
+1. <the very next action, specific enough to start without asking>
+2. <…>
+
+## Commands
+- Build: `<command>`   Test: `<command>`   Lint: `<command>`   Run: `<command>`
+- Verify the current state: `<command>` → <what passing looks like>
+
+## Environment facts
+- Tools and versions: <go 1.26.x, rustc 1.9x, node 22.x, …; where each came from>
+- Services: <local databases, ports, docker compose services; or none>
+- Hosts: <APIs or internal hosts the task calls; or none>
+- Secrets needed: <names only, never values; or none>
+- Installed during this session: <packages and tools added; or none>
+
+## Gotchas learned
+- <non-obvious things that cost time: flaky tests, a wrong doc, a tool quirk>
+
+## Open questions
+- <what needs the user, and what to do meanwhile>
+```
diff --git a/cli/README.md b/cli/README.md
index 7604d7e..664c5ae 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -56,9 +56,36 @@ Without `BOX_TOKEN`, an interactive run asks for the key with hidden input. The
 
 It prints a fix for each problem. `--json` prints a machine-readable report; the exit code is 1 when something needs fixing. OAuth sign-ins are stored by each app, so doctor can't see whether you've signed in.
 
+## Offload
+
+Move the coding task you are working on into your box, let an agent there keep going while you are away, and bring the work back. This is upstream cocoonbox's Offload (design §27), with the same box side.
+
+```bash
+npx @simular-ai/box login                                   # once: sign this CLI in to box in the browser
+npx @simular-ai/box offload install-cli --kind claude       # once per box: the vendor's official installer, in the box
+npx @simular-ai/box offload sign-in --kind claude           # once per box: Claude Code's own login, run in the box
+```
+
+Then, in Claude Code with the `box` plugin, `/box:offload` and later `/box:back`. Elsewhere, write the hand-over to the path `offload handover-path` prints (or paste the request `offload --handover-prompt --kind codex` prints into your agent), then:
+
+```bash
+npx @simular-ai/box offload --kind claude     # preflight, copy the repo, start the box agent from the hand-over
+npx @simular-ai/box offload inbox             # what the box agent posted; offload send "..." answers it
+npx @simular-ai/box back                      # wait for its hand-over, fetch its commits, merge them here
+```
+
+How it works:
+
+- **Sign-in.** `login` signs the CLI in as the relay's first-party `cocoonbox-cli` client: the consent page opens in your browser, the answer comes back to a one-time listener on `127.0.0.1` (PKCE, `state` and issuer checked), and the CLI gets a device token of its own, listed under Keys -> Devices and revoked there or with `logout`. It is kept in `~/.simular-box/credentials.json` (`0600`, directory `0700`; `BOX_HOME` moves it). `BOX_TOKEN=cb_...` (a personal key) wins over it, for CI or a server. `login --token -` reads a personal key from stdin or a hidden prompt. A token is never accepted as an argument or printed.
+- **The box CLI has its own login.** `offload sign-in` runs the vendor's login (`claude auth login`, `codex login --device-auth`, `cursor-agent login`) on a terminal in the box, relayed to yours, with the box's browser kept shut. The first https link it prints on that vendor's own sign-in hosts opens in your browser, once; no other link from the box is opened. Approve, then paste the code into your terminal. Nothing is copied from this computer.
+- **Transport.** Everything goes over `Session.Exec` on the relay's gRPC: `npx @simular-ai/box rsh` is an ssh-like remote shell (`rsync -e`, `GIT_SSH_COMMAND`). An offload is three Execs: `begin` (box checks), rsync of the work tree and `.git` without objects, and `send`, whose stream carries the hand-over, `env.json`, the history as a git bundle and any opted-in secrets.
+- **Back.** It waits for the box agent to go idle (a hand-over request pasted while it is ending a turn can be lost; `back --interrupt` stops its current step instead), then up to 10 minutes in all for its hand-over, fetches the box's commits over `rsh`, and lands them against the snapshot taken at offload: a fast-forward when your repo has not changed, else a clean merge applied uncommitted (never touching a file you changed meanwhile), else the branch `cocoonbox/back-<time>` with your work tree untouched.
+- **Preflight.** It blocks on a non-git directory, a box missing `git`/`rsync`/`tmux`/`mise`, a missing or signed-out box CLI, an offload not yet brought back, and macOS-only commands. It warns (go on with `--yes`) about local services and VPN-only hosts the box cannot reach, git-ignored `.env*` files and other secrets (opt one in with `offload secrets add file:.env`; values travel only in the Exec stream and land on a tmpfs in the box), LFS and submodules, and a copy over 500 MB.
+- **Limits.** macOS and Linux (needs `git` and `rsync`); git repositories only; the box agent commits but never pushes; one session per repo and three per box; the box agent runs with permission prompts bypassed.
+
 ## Other endpoints
 
-`BOX_MCP_URL` points everything at another endpoint (for example staging): `BOX_MCP_URL=https://… npx @simular-ai/box connect`. When box's endpoint moves, a new CLI version changes the default and `connect` updates each app: it rewrites a `box` entry that points at the old address and, for Claude Code, updates the `box@simular-box` plugin. Apps may then ask you to sign in to box again. box moved from `relay.simular.cloud` to `mcp.box.simular.ai` on 2026-11-04; `doctor` flags an app still on the old address.
+`BOX_MCP_URL` points everything at another endpoint (for example staging): `BOX_MCP_URL=https://… npx @simular-ai/box connect`. Offload, `login` and `rsh` use its origin, or `BOX_ENDPOINT` when set. When box's endpoint moves, a new CLI version changes the default and `connect` updates each app: it rewrites a `box` entry that points at the old address and, for Claude Code, updates the `box@simular-box` plugin. Apps may then ask you to sign in to box again. box moved from `relay.simular.cloud` to `mcp.box.simular.ai` on 2026-11-04; `doctor` flags an app still on the old address.
 
 ## Development
 
diff --git a/cli/package-lock.json b/cli/package-lock.json
index f54aecc..857ccae 100644
--- a/cli/package-lock.json
+++ b/cli/package-lock.json
@@ -1,15 +1,17 @@
 {
   "name": "@simular-ai/box",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@simular-ai/box",
-      "version": "0.1.3",
+      "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "0.11.0",
+        "@grpc/grpc-js": "1.14.6",
+        "@grpc/proto-loader": "0.8.1",
         "cross-spawn": "7.0.6",
         "jsonc-parser": "3.3.1",
         "smol-toml": "1.9.1",
@@ -205,6 +207,37 @@
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
       }
     },
+    "node_modules/@grpc/grpc-js": {
+      "version": "1.14.6",
+      "resolved": "https://registry.npmjs.org/@grpc/grpc-js/-/grpc-js-1.14.6.tgz",
+      "integrity": "sha512-SgC/B3/VZ8lTyOZ4Cwk6f1skWhmkNAaVfiX90qd5u1rRXGKk1//8FTUEN9GvOUq7rfWIqAYkA3CoyumYVpOS6g==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@grpc/proto-loader": "^0.8.0",
+        "@js-sdsl/ordered-map": "^4.4.2"
+      },
+      "engines": {
+        "node": ">=12.10.0"
+      }
+    },
+    "node_modules/@grpc/proto-loader": {
+      "version": "0.8.1",
+      "resolved": "https://registry.npmjs.org/@grpc/proto-loader/-/proto-loader-0.8.1.tgz",
+      "integrity": "sha512-wtF6h+DY6M3YaDBPAmvuuA6jV8Sif9MjtOI5euKFWRgCDl5PeDpPsHR9u2l6St5ceY8AZgoNDww5+HvEsXFsGg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "lodash.camelcase": "^4.3.0",
+        "long": "^5.0.0",
+        "protobufjs": "^7.5.5",
+        "yargs": "^17.7.2"
+      },
+      "bin": {
+        "proto-loader-gen-types": "build/bin/proto-loader-gen-types.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/@humanfs/core": {
       "version": "0.19.2",
       "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.2.tgz",
@@ -271,6 +304,73 @@
         "url": "https://github.com/sponsors/nzakas"
       }
     },
+    "node_modules/@js-sdsl/ordered-map": {
+      "version": "4.4.2",
+      "resolved": "https://registry.npmjs.org/@js-sdsl/ordered-map/-/ordered-map-4.4.2.tgz",
+      "integrity": "sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/js-sdsl"
+      }
+    },
+    "node_modules/@protobufjs/aspromise": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
+      "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/base64": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz",
+      "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/codegen": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz",
+      "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/eventemitter": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz",
+      "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/fetch": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz",
+      "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.1"
+      }
+    },
+    "node_modules/@protobufjs/float": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz",
+      "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/path": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz",
+      "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/pool": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz",
+      "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/utf8": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.2.tgz",
+      "integrity": "sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==",
+      "license": "BSD-3-Clause"
+    },
     "node_modules/@types/estree": {
       "version": "1.0.10",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.10.tgz",
@@ -285,6 +385,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/node": {
+      "version": "26.6.6",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.6.tgz",
+      "integrity": "sha512-MzQj+8Kx3XI40OmUAE6Qoh58ZMNstNNMwn2nfd3qWsfe7nDNSqJNzes4njhz6AHwrSHOffSLwXU6yb474Q4aog==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~8.9.0"
+      }
+    },
     "node_modules/acorn": {
       "version": "8.19.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz",
@@ -325,11 +434,19 @@
         "url": "https://github.com/sponsors/epoberezkin"
       }
     },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/ansi-styles": {
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
       "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "color-convert": "^2.0.1"
@@ -393,11 +510,24 @@
         "url": "https://github.com/chalk/chalk?sponsor=1"
       }
     },
+    "node_modules/cliui": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
+      "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.1",
+        "wrap-ansi": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
       "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "color-name": "~1.1.4"
@@ -410,7 +540,6 @@
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
       "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/concat-map": {
@@ -459,6 +588,21 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/escape-string-regexp": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
@@ -699,6 +843,15 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
     "node_modules/glob-parent": {
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz",
@@ -782,6 +935,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/is-glob": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
@@ -891,6 +1053,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/lodash.camelcase": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/lodash.camelcase/-/lodash.camelcase-4.3.0.tgz",
+      "integrity": "sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==",
+      "license": "MIT"
+    },
     "node_modules/lodash.merge": {
       "version": "4.6.2",
       "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz",
@@ -898,6 +1066,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/long": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
+      "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
+      "license": "Apache-2.0"
+    },
     "node_modules/minimatch": {
       "version": "3.1.5",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
@@ -1023,6 +1197,29 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/protobufjs": {
+      "version": "7.6.6",
+      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.6.tgz",
+      "integrity": "sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg==",
+      "hasInstallScript": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.2",
+        "@protobufjs/base64": "^1.1.2",
+        "@protobufjs/codegen": "^2.0.5",
+        "@protobufjs/eventemitter": "^1.1.1",
+        "@protobufjs/fetch": "^1.1.1",
+        "@protobufjs/float": "^1.0.2",
+        "@protobufjs/path": "^1.1.2",
+        "@protobufjs/pool": "^1.1.0",
+        "@protobufjs/utf8": "^1.1.1",
+        "@types/node": ">=13.7.0",
+        "long": "^5.3.2"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/punycode": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
@@ -1033,6 +1230,15 @@
         "node": ">=6"
       }
     },
+    "node_modules/require-directory": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
+      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/resolve-from": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz",
@@ -1082,6 +1288,32 @@
         "url": "https://github.com/sponsors/cyyynthia"
       }
     },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/strip-json-comments": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
@@ -1121,6 +1353,12 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/undici-types": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
+      "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
+      "license": "MIT"
+    },
     "node_modules/uri-js": {
       "version": "4.4.1",
       "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz",
@@ -1156,6 +1394,32 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/wrap-ansi": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/yaml": {
       "version": "2.9.1",
       "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
@@ -1171,6 +1435,33 @@
         "url": "https://github.com/sponsors/eemeli"
       }
     },
+    "node_modules/yargs": {
+      "version": "17.7.3",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.3.tgz",
+      "integrity": "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==",
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^8.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.3",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^21.1.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "21.1.1",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/yocto-queue": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
diff --git a/cli/package.json b/cli/package.json
index 9537df6..c4d77c5 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@simular-ai/box",
-  "version": "0.1.3",
-  "description": "Connect box by Simular (a cloud computer your AI agent drives over MCP) to Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Hermes, OpenClaw and more in one command.",
+  "version": "0.2.0",
+  "description": "Connect box by Simular (a cloud computer your AI agent drives over MCP) to Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Hermes, OpenClaw and more in one command, and move a coding task into your box and back (offload / back).",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "bin/",
     "src/",
+    "proto/",
     "README.md",
     "LICENSE"
   ],
@@ -24,6 +25,8 @@
   },
   "dependencies": {
     "@clack/prompts": "0.11.0",
+    "@grpc/grpc-js": "1.14.6",
+    "@grpc/proto-loader": "0.8.1",
     "cross-spawn": "7.0.6",
     "jsonc-parser": "3.3.1",
     "smol-toml": "1.9.1",
diff --git a/cli/proto/README.md b/cli/proto/README.md
new file mode 100644
index 0000000..3534011
--- /dev/null
+++ b/cli/proto/README.md
@@ -0,0 +1,6 @@
+# Vendored protos
+
+Copied unchanged from [simular-ai/box](https://github.com/simular-ai/box) `proto/` at `f452665cb144286ec100c3ad28cf3fa796851767`:
+`cocoonbox/agent/v1/session.proto` (Session.Exec), `cocoonbox/agent/v1/agents.proto` (imported by it) and
+`cocoonbox/control/v1/boxes.proto` (Boxes.List / Ensure). `@grpc/proto-loader` reads them at run time; nothing is
+generated. Refresh them by copying the same files again when the relay's wire changes.
diff --git a/cli/proto/cocoonbox/agent/v1/agents.proto b/cli/proto/cocoonbox/agent/v1/agents.proto
new file mode 100644
index 0000000..607c53d
--- /dev/null
+++ b/cli/proto/cocoonbox/agent/v1/agents.proto
@@ -0,0 +1,212 @@
+syntax = "proto3";
+
+package cocoonbox.agent.v1;
+
+option go_package = "github.com/simular-ai/box/api/gen/cocoonbox/agent/v1;agentv1";
+
+// Agents and Session are served by cocoonbox-agent inside the box. Clients
+// reach them through the edge with `authorization: Bearer <user token>` and
+// `x-cocoonbox-box: <box id>`; the edge forwards the call unchanged.
+service Agents {
+  rpc Create(CreateAgentRequest) returns (Agent);
+  rpc List(ListAgentsRequest) returns (ListAgentsResponse);
+  // Send queues a user turn. Duplicate client_nonce values return the first result.
+  rpc Send(SendRequest) returns (SendResponse);
+  rpc Transcript(TranscriptRequest) returns (TranscriptPage);
+  rpc Respond(RespondRequest) returns (RespondResponse);
+  rpc Cancel(CancelRequest) returns (CancelResponse);
+  // Rename sets the agent's name; an automatic title never replaces it.
+  rpc Rename(RenameAgentRequest) returns (Agent);
+  // Delete cancels the agent's running turn and removes the agent with its
+  // transcript. An mcp:* agent whose MCP session is open is refused with
+  // FAILED_PRECONDITION; an unknown agent gets NOT_FOUND.
+  rpc Delete(DeleteAgentRequest) returns (DeleteAgentResponse);
+  // End closes the MCP session that drives agent_id, or every MCP session of
+  // share_id; the agents and their transcripts stay. An agent_id without an
+  // open session gets NOT_FOUND.
+  rpc End(EndRequest) returns (EndResponse);
+}
+
+enum AgentStatus {
+  AGENT_STATUS_UNSPECIFIED = 0;
+  AGENT_STATUS_IDLE = 1;
+  AGENT_STATUS_RUNNING = 2;
+  AGENT_STATUS_WAITING_FOR_USER = 3;
+  AGENT_STATUS_FAILED = 4;
+}
+
+enum Role {
+  ROLE_UNSPECIFIED = 0;
+  ROLE_USER = 1;
+  ROLE_ASSISTANT = 2;
+  ROLE_TOOL = 3;
+  ROLE_SYSTEM = 4;
+}
+
+message Agent {
+  string id = 1;
+  string name = 2;
+  AgentStatus status = 3;
+  string main_model = 4;
+  int64 created_at_ms = 5;
+  int64 updated_at_ms = 6;
+}
+
+message CreateAgentRequest {
+  // Empty names the agent after the first line of its first message, cut to
+  // 24 characters; until then its name is "agent".
+  string name = 1;
+  string client_nonce = 2;
+  // Empty selects the box default.
+  string main_model = 3;
+}
+
+message ListAgentsRequest {}
+
+message ListAgentsResponse {
+  repeated Agent agents = 1;
+}
+
+message Attachment {
+  string name = 1;
+  string mime_type = 2;
+  bytes data = 3;
+}
+
+message SendRequest {
+  string agent_id = 1;
+  string text = 2;
+  repeated Attachment attachments = 3;
+  string client_nonce = 4;
+}
+
+message SendResponse {
+  string turn_id = 1;
+}
+
+message TranscriptRequest {
+  string agent_id = 1;
+  // Entries with seq > after_seq, oldest first.
+  uint64 after_seq = 2;
+  uint32 limit = 3;
+}
+
+message TranscriptPage {
+  repeated TranscriptEntry entries = 1;
+  bool has_more = 2;
+}
+
+message TranscriptEntry {
+  uint64 seq = 1;
+  string agent_id = 2;
+  string turn_id = 3;
+  Role role = 4;
+  int64 at_ms = 5;
+  oneof body {
+    TextBlock text = 10;
+    ReasoningBlock reasoning = 11;
+    ToolCall tool_call = 12;
+    ToolResult tool_result = 13;
+    ApprovalRequest approval = 14;
+    TurnEnd turn_end = 15;
+    // The turn's usage so far, recorded after each completed model call; TurnEnd.usage is the final sum.
+    Usage usage = 16;
+  }
+}
+
+message TextBlock {
+  string text = 1;
+  // Set when the text belongs to a subagent, e.g. "computer".
+  string subagent = 2;
+  // Index of the streamed block within its turn; matches TextDelta.block.
+  uint32 block = 3;
+}
+
+message ReasoningBlock {
+  string text = 1;
+  // Index of the streamed block within its turn; matches ReasoningDelta.block.
+  uint32 block = 2;
+  string subagent = 3;
+}
+
+message ToolCall {
+  string call_id = 1;
+  string name = 2;
+  string arguments_json = 3;
+  // Set when the call belongs to a subagent, e.g. "computer".
+  string subagent = 4;
+}
+
+message ToolResult {
+  string call_id = 1;
+  bool is_error = 2;
+  string text = 3;
+  // PNG when the tool produced a screenshot.
+  bytes image = 4;
+}
+
+message ApprovalRequest {
+  string approval_id = 1;
+  string summary = 2;
+  // "take_over": the agent hands the screen to the user (login, captcha, payment).
+  // "connector": a Connect tool call that needs the user's approval; approval_id is the broker's apr_… id,
+  // which the app answers with Connectors.Approve and then Agents.Respond.
+  string kind = 3;
+}
+
+message TurnEnd {
+  bool ok = 1;
+  string error = 2;
+  Usage usage = 3;
+}
+
+message Usage {
+  uint64 input_tokens = 1;
+  uint64 output_tokens = 2;
+  uint64 cached_input_tokens = 3;
+  repeated ModelUsage models = 4;
+}
+
+message ModelUsage {
+  string model = 1;
+  uint64 calls = 2;
+  uint64 input_tokens = 3;
+  uint64 output_tokens = 4;
+  uint64 cached_input_tokens = 5;
+}
+
+message RespondRequest {
+  string agent_id = 1;
+  string approval_id = 2;
+  bool approve = 3;
+  string text = 4;
+}
+
+message RespondResponse {}
+
+message CancelRequest {
+  string agent_id = 1;
+}
+
+message CancelResponse {}
+
+message RenameAgentRequest {
+  string agent_id = 1;
+  // Trimmed; empty is INVALID_ARGUMENT.
+  string name = 2;
+}
+
+message DeleteAgentRequest {
+  string agent_id = 1;
+}
+
+message DeleteAgentResponse {}
+
+message EndRequest {
+  oneof target {
+    string agent_id = 1;
+    string share_id = 2;
+  }
+}
+
+message EndResponse {}
diff --git a/cli/proto/cocoonbox/agent/v1/session.proto b/cli/proto/cocoonbox/agent/v1/session.proto
new file mode 100644
index 0000000..88266f4
--- /dev/null
+++ b/cli/proto/cocoonbox/agent/v1/session.proto
@@ -0,0 +1,232 @@
+syntax = "proto3";
+
+package cocoonbox.agent.v1;
+
+import "cocoonbox/agent/v1/agents.proto";
+
+option go_package = "github.com/simular-ai/box/api/gen/cocoonbox/agent/v1;agentv1";
+
+service Session {
+  rpc Hello(HelloRequest) returns (HelloResponse);
+  // Events streams live changes; reconnect with the last seen offset.
+  rpc Events(EventsRequest) returns (stream Event);
+  // Screen carries raw RFB bytes between the client and the box's VNC server.
+  // The first client frame must be `open`; the stream ends when either side closes.
+  rpc Screen(stream ScreenClientFrame) returns (stream ScreenServerFrame);
+  // ActiveOrigin returns the origin of the active tab of the box's Chrome.
+  rpc ActiveOrigin(ActiveOriginRequest) returns (ActiveOriginResponse);
+  // FillCredential fills the sign-in form of the active tab when its origin
+  // equals `origin` (scheme, host and port), else FAILED_PRECONDITION. App
+  // only: it is no MCP tool, and its values are never logged or recorded.
+  rpc FillCredential(FillCredentialRequest) returns (FillCredentialResponse);
+  // Exec runs a command as the desktop user and carries its stdin, stdout and
+  // stderr. The first client frame must be `start`. `eof`, or the client
+  // half-closing the stream, closes the command's stdin. The last server frame
+  // is `exit_code`. Cancelling the stream kills the command's process group.
+  // Owner only.
+  rpc Exec(stream ExecClientFrame) returns (stream ExecServerFrame);
+}
+
+message ExecClientFrame {
+  oneof body {
+    ExecStart start = 1;
+    bytes stdin = 2;
+    ExecEof eof = 3;
+    // Sent to the command's process group.
+    ExecSignal signal = 4;
+    // The terminal size of a command started with `tty`.
+    ExecWindow resize = 5;
+  }
+}
+
+message ExecStart {
+  // Run by a login shell, `bash -lc`, in /workspace, as rsh and ssh run a
+  // remote command.
+  string command = 1;
+  // Present: the command runs on a pseudo-terminal, and stdout carries its
+  // stderr too.
+  ExecTty tty = 2;
+}
+
+message ExecTty {
+  // TERM for the command.
+  string term = 1;
+  ExecWindow window = 2;
+  // The terminfo source of `term` (`infocmp -x` output), at most 256 KiB. A box
+  // without an entry for `term` compiles it into the user's ~/.terminfo;
+  // without one, or when it does not compile, the command gets xterm-256color.
+  string terminfo = 3;
+}
+
+message ExecWindow {
+  uint32 rows = 1;
+  uint32 cols = 2;
+}
+
+message ExecEof {}
+
+enum ExecSignal {
+  EXEC_SIGNAL_UNSPECIFIED = 0;
+  EXEC_SIGNAL_INT = 1;
+  EXEC_SIGNAL_TERM = 2;
+}
+
+message ExecServerFrame {
+  oneof body {
+    bytes stdout = 1;
+    bytes stderr = 2;
+    // The command's exit status, or 128 plus the signal that ended it.
+    int32 exit_code = 3;
+  }
+}
+
+message HelloRequest {
+  string client_version = 1;
+}
+
+message HelloResponse {
+  string agent_version = 1;
+  // The screen size the image boots at: 1280x800 on a desktop, 720x1280 on
+  // Android. A later change in the box, such as `wm size`, is not reflected.
+  uint32 screen_width = 2;
+  uint32 screen_height = 3;
+  repeated string models = 4;
+  string default_main_model = 5;
+  Automation automation = 6;
+}
+
+// Automation is what the box's screen is, from the guide its image holds.
+enum Automation {
+  AUTOMATION_UNSPECIFIED = 0;
+  // A desktop driven through cua-driver only.
+  AUTOMATION_PLAIN = 1;
+  // A desktop that runs GUI plans and scripts on the desk runtime.
+  AUTOMATION_DESK = 2;
+  // An Android phone in the box, driven through adb.
+  AUTOMATION_ANDROID = 3;
+}
+
+message ActiveOriginRequest {}
+
+message ActiveOriginResponse {
+  // As `location.origin`, e.g. "https://example.com" or "http://127.0.0.1:8080".
+  string origin = 1;
+}
+
+message FillCredentialRequest {
+  string origin = 1;
+  string username = 2;
+  oneof secret {
+    string password = 3;
+    // A one-time code, filled into the page's code field.
+    string code = 4;
+  }
+  bool submit = 5;
+}
+
+message FillCredentialResponse {
+  // The kinds of field filled: "username", "password", "code".
+  repeated string filled = 1;
+  bool submitted = 2;
+}
+
+message EventsRequest {
+  // Last Event.offset seen; 0 starts from now.
+  uint64 from_offset = 1;
+}
+
+message Event {
+  uint64 offset = 1;
+  oneof body {
+    TranscriptEntry transcript = 10;
+    Agent agent = 11;
+    ComputerAction computer_action = 12;
+    TextDelta text_delta = 13;
+    ReasoningDelta reasoning_delta = 14;
+    AgentDeleted agent_deleted = 15;
+    OffloadUpdate offload = 16;
+  }
+}
+
+// OffloadUpdate says a box CLI session of an offloaded repo posted to its
+// outbox or changed status. It carries no message text; `cocoonbox-agent
+// offload read` returns that.
+message OffloadUpdate {
+  // The repo key.
+  string repo = 1;
+  // The directory name under /workspace.
+  string name = 2;
+  // The box CLI: "claude", "codex" or "cursor".
+  string cli = 3;
+  string offload_id = 4;
+  // Unspecified for a status change.
+  OffloadEntry entry = 5;
+  // The outbox seq of `entry`; 0 for a status change.
+  uint64 seq = 6;
+  OffloadStatus status = 7;
+}
+
+enum OffloadEntry {
+  OFFLOAD_ENTRY_UNSPECIFIED = 0;
+  OFFLOAD_ENTRY_PROGRESS = 1;
+  OFFLOAD_ENTRY_QUESTION = 2;
+  OFFLOAD_ENTRY_BACK = 3;
+  OFFLOAD_ENTRY_BLOCKED = 4;
+}
+
+enum OffloadStatus {
+  OFFLOAD_STATUS_UNSPECIFIED = 0;
+  OFFLOAD_STATUS_WORKING = 1;
+  OFFLOAD_STATUS_IDLE = 2;
+  OFFLOAD_STATUS_WAITING_FOR_USER = 3;
+  OFFLOAD_STATUS_BLOCKED = 4;
+  OFFLOAD_STATUS_STOPPED = 5;
+}
+
+// AgentDeleted says the agent and its transcript are gone.
+message AgentDeleted {
+  string agent_id = 1;
+}
+
+// TextDelta is a live fragment of an assistant text block. Deltas are not
+// replayed on reconnect; the complete block follows as a TranscriptEntry whose
+// TextBlock carries the same (turn_id, block).
+message TextDelta {
+  string agent_id = 1;
+  string turn_id = 2;
+  uint32 block = 3;
+  string text = 4;
+  string subagent = 5;
+}
+
+// ReasoningDelta is TextDelta for reasoning blocks.
+message ReasoningDelta {
+  string agent_id = 1;
+  string turn_id = 2;
+  uint32 block = 3;
+  string text = 4;
+  string subagent = 5;
+}
+
+// ComputerAction mirrors an input the agent is about to inject, so the client
+// can highlight it on the live view.
+message ComputerAction {
+  string agent_id = 1;
+  string action = 2;
+  int32 x = 3;
+  int32 y = 4;
+  string text = 5;
+}
+
+message ScreenClientFrame {
+  oneof body {
+    ScreenOpen open = 1;
+    bytes data = 2;
+  }
+}
+
+message ScreenOpen {}
+
+message ScreenServerFrame {
+  bytes data = 1;
+}
diff --git a/cli/proto/cocoonbox/control/v1/boxes.proto b/cli/proto/cocoonbox/control/v1/boxes.proto
new file mode 100644
index 0000000..213a198
--- /dev/null
+++ b/cli/proto/cocoonbox/control/v1/boxes.proto
@@ -0,0 +1,284 @@
+syntax = "proto3";
+
+package cocoonbox.control.v1;
+
+option go_package = "github.com/simular-ai/box/api/gen/cocoonbox/control/v1;controlv1";
+
+// Boxes is served by cocoonbox-api (the edge). Callers authenticate with
+// `authorization: Bearer <user token>`.
+service Boxes {
+  // Ensure creates the caller's box, or wakes it, and returns immediately.
+  // Idempotent per (box, flavor). Progress arrives on WatchOperation.
+  rpc Ensure(EnsureRequest) returns (EnsureResponse);
+  // Create adds a box to the caller's boxes and starts it, within the user's
+  // box quota and the api's running limit.
+  rpc Create(CreateBoxRequest) returns (EnsureResponse);
+  rpc Rename(RenameBoxRequest) returns (Box);
+  // Delete removes the box's machine, the box and its saved state; with the
+  // owner's last box the owner's whole state goes.
+  rpc Delete(BoxRef) returns (Operation);
+  rpc Get(GetBoxRequest) returns (Box);
+  rpc List(ListBoxesRequest) returns (ListBoxesResponse);
+  // Watch sends the caller's boxes as List does, at once and again after any
+  // of them changes, by any client or by the api. Watching never wakes a box.
+  rpc Watch(WatchBoxesRequest) returns (stream ListBoxesResponse);
+  rpc Hibernate(BoxRef) returns (Operation);
+  rpc WatchOperation(WatchOperationRequest) returns (stream OperationEvent);
+  // SaveState writes a quiesced snapshot of the box's user state (home,
+  // /workspace, agent.db) to object storage. The browser closes for the copy.
+  rpc SaveState(BoxRef) returns (Operation);
+  // Rebase moves the box to another image and carries its user state over:
+  // quiesced save, new machine from the image, restore, switch, delete the old
+  // machine. The box id stays the same; running programs restart.
+  rpc Rebase(RebaseRequest) returns (Operation);
+  // ListSnapshots lists the box's kept snapshots, newest first.
+  rpc ListSnapshots(BoxRef) returns (ListSnapshotsResponse);
+  // BrowseSnapshot lists one directory of a kept snapshot; the box may be
+  // hibernated.
+  rpc BrowseSnapshot(BrowseSnapshotRequest) returns (BrowseSnapshotResponse);
+  // RestorePaths copies files and folders of a kept snapshot into
+  // ~/Restored/<save time>/ in the running box (PHASE_RESTORING_FILES).
+  // Nothing outside that folder changes and nothing restarts.
+  rpc RestorePaths(RestorePathsRequest) returns (Operation);
+  // SetWakeSchedule replaces the box's wake schedule. A minute before each
+  // time of cron in tz, the api wakes the box when it is hibernated. After
+  // awake_for it hibernates the box again, unless a client reached the box
+  // since that wake or an operation runs. The api keeps no routine: the box
+  // runs its own timers.
+  rpc SetWakeSchedule(SetWakeScheduleRequest) returns (WakeSchedule);
+  // ListWakeSchedules lists the wake schedules of the caller's boxes.
+  rpc ListWakeSchedules(ListWakeSchedulesRequest) returns (ListWakeSchedulesResponse);
+  // ClearWakeSchedule removes the box's wake schedule; a box the alarm woke
+  // stays up.
+  rpc ClearWakeSchedule(BoxRef) returns (ClearWakeScheduleResponse);
+  rpc Usage(UsageRequest) returns (UsageResponse);
+}
+
+enum BoxState {
+  BOX_STATE_UNSPECIFIED = 0;
+  BOX_STATE_STARTING = 1;
+  BOX_STATE_RUNNING = 2;
+  BOX_STATE_HIBERNATING = 3;
+  BOX_STATE_HIBERNATED = 4;
+  BOX_STATE_FAILED = 5;
+}
+
+enum Phase {
+  PHASE_UNSPECIFIED = 0;
+  PHASE_CREATING = 1;
+  PHASE_WAKING = 2;
+  PHASE_SNAPSHOTTING = 3;
+  PHASE_DONE = 4;
+  PHASE_FAILED = 5;
+  // Uploading the user state to object storage.
+  PHASE_SAVING = 6;
+  // Writing the user state into a new machine.
+  PHASE_RESTORING = 7;
+  // Removing the box's machine.
+  PHASE_DELETING = 8;
+  // Copying files of a snapshot into the running box.
+  PHASE_RESTORING_FILES = 9;
+}
+
+enum EntryKind {
+  ENTRY_KIND_UNSPECIFIED = 0;
+  ENTRY_KIND_FILE = 1;
+  ENTRY_KIND_DIR = 2;
+  ENTRY_KIND_SYMLINK = 3;
+}
+
+message BoxRef {
+  string box_id = 1;
+}
+
+message Flavor {
+  uint32 vcpus = 1;
+  uint32 memory_mib = 2;
+  uint32 disk_gib = 3;
+}
+
+message Box {
+  string id = 1;
+  BoxState state = 2;
+  string image = 3;
+  Flavor flavor = 4;
+  string failure_reason = 5;
+  int64 created_at_ms = 6;
+  // Time of the latest user-state snapshot in object storage; 0 before the first.
+  int64 last_saved_at_ms = 7;
+  // Image a new box gets today, and the default Rebase target; differs from image when an upgrade is available.
+  string latest_image = 8;
+  // Unique among the user's boxes.
+  string name = 9;
+}
+
+message Operation {
+  string id = 1;
+  string box_id = 2;
+}
+
+message EnsureRequest {
+  Flavor flavor = 1;
+  // Empty selects the user's first box, and creates one when the user has none.
+  string box_id = 2;
+}
+
+message CreateBoxRequest {
+  string name = 1;
+  // Empty selects the current default image.
+  string image = 2;
+  Flavor flavor = 3;
+}
+
+message RenameBoxRequest {
+  string box_id = 1;
+  string name = 2;
+}
+
+message EnsureResponse {
+  Box box = 1;
+  // Empty when the box is already running.
+  Operation operation = 2;
+}
+
+message RebaseRequest {
+  string box_id = 1;
+  // Target image; empty selects the current default image.
+  string image = 2;
+}
+
+message GetBoxRequest {
+  string box_id = 1;
+}
+
+message ListBoxesRequest {}
+
+message ListBoxesResponse {
+  repeated Box boxes = 1;
+  // Images CreateBoxRequest.image may name, the default image first; the
+  // family of one is the name before ':'.
+  repeated string offered_images = 2;
+}
+
+message WatchBoxesRequest {}
+
+message WatchOperationRequest {
+  string operation_id = 1;
+  // Resume after this offset; empty replays from the start.
+  string from_offset_key = 2;
+}
+
+message OperationEvent {
+  string operation_id = 1;
+  Phase phase = 2;
+  string detail = 3;
+  string offset_key = 4;
+  int64 at_ms = 5;
+  BoxState box_state = 6;
+  // Transfer progress while saving or restoring; 0 otherwise.
+  uint64 done_bytes = 7;
+  uint64 total_bytes = 8;
+}
+
+message Snapshot {
+  string id = 1;
+  int64 saved_at_ms = 2;
+  bool quiesced = 3;
+  uint64 files = 4;
+  uint64 logical_bytes = 5;
+  // Files new, changed or removed since the save before; absent for saves by
+  // agents older than this field.
+  optional uint64 changed_files = 6;
+  // Plaintext bytes of the chunks this save added to the store.
+  uint64 added_bytes = 7;
+}
+
+message ListSnapshotsResponse {
+  repeated Snapshot snapshots = 1;
+}
+
+message BrowseSnapshotRequest {
+  string box_id = 1;
+  string snapshot_id = 2;
+  // A box path such as /home/user/Documents; empty lists the roots.
+  string dir = 3;
+}
+
+message SnapshotEntry {
+  // The box path.
+  string path = 1;
+  EntryKind kind = 2;
+  uint64 size = 3;
+  int64 mtime_ms = 4;
+}
+
+message BrowseSnapshotResponse {
+  repeated SnapshotEntry entries = 1;
+  // The directory holds more entries than one answer carries.
+  bool truncated = 2;
+}
+
+message RestorePathsRequest {
+  string box_id = 1;
+  string snapshot_id = 2;
+  // Box paths of files or folders, each under /home/user or /workspace.
+  repeated string paths = 3;
+}
+
+message WakeSchedule {
+  string box_id = 1;
+  // Five fields: minute, hour, day of month, month, day of week.
+  string cron = 2;
+  // IANA zone name of cron, such as Asia/Singapore.
+  string tz = 3;
+  uint32 awake_for_s = 4;
+  // The next time of cron; the wake comes a minute before it.
+  int64 next_at_ms = 5;
+  // The latest wake of this schedule from hibernation; 0 before the first.
+  int64 last_wake_at_ms = 6;
+}
+
+message SetWakeScheduleRequest {
+  string box_id = 1;
+  string cron = 2;
+  string tz = 3;
+  // 0 selects the default, 15 minutes.
+  uint32 awake_for_s = 4;
+}
+
+message ListWakeSchedulesRequest {}
+
+message ListWakeSchedulesResponse {
+  repeated WakeSchedule schedules = 1;
+}
+
+message ClearWakeScheduleResponse {}
+
+message UsageRequest {}
+
+message UsageResponse {
+  UsagePeriod today = 1;
+  UsagePeriod month = 2;
+  int64 daily_cap_micros = 3;
+  bool default_cap = 4;
+  int64 remaining_today_micros = 5;
+}
+
+message UsagePeriod {
+  int64 since_ms = 1;
+  int64 requests = 2;
+  int64 prompt_tokens = 3;
+  int64 completion_tokens = 4;
+  int64 total_tokens = 5;
+  int64 cost_micros = 6;
+  repeated ModelUsage models = 7;
+}
+
+message ModelUsage {
+  string model = 1;
+  int64 requests = 2;
+  int64 prompt_tokens = 3;
+  int64 completion_tokens = 4;
+  int64 total_tokens = 5;
+  int64 cost_micros = 6;
+}
diff --git a/cli/src/args.js b/cli/src/args.js
index 2a07ec1..704c2b5 100644
--- a/cli/src/args.js
+++ b/cli/src/args.js
@@ -1,6 +1,8 @@
 // Tiny argument parser: no dependency for a handful of flags.
-const BOOLEAN = new Set(['yes', 'json', 'dry-run', 'help', 'version', 'all'])
-const VALUE = new Set(['client', 'auth', 'name'])
+const BOOLEAN = new Set(['yes', 'json', 'dry-run', 'help', 'version', 'all', 'interrupt', 'handover-prompt'])
+const VALUE = new Set(['client', 'auth', 'name', 'box', 'kind', 'dir', 'handover', 'wait', 'endpoint'])
+// Value flags that take one value (the rest are lists: --client a,b).
+const SINGLE = new Set(['name', 'box', 'kind', 'dir', 'handover', 'wait', 'endpoint'])
 const ALIASES = { y: 'yes', h: 'help', v: 'version', c: 'client' }
 
 export function parseArgs(argv) {
@@ -24,11 +26,15 @@ export function parseArgs(argv) {
       else if (VALUE.has(name)) {
         if (value === undefined) value = argv[++i]
         if (value === undefined || value.startsWith('-')) throw new Error(`--${name} needs a value`)
-        if (name === 'name') out.flags.name = value
+        if (SINGLE.has(name)) out.flags[name] = value
         else if (name === 'auth') {
           if (value !== 'oauth' && value !== 'key') throw new Error('--auth must be oauth or key')
           out.flags.auth = value
         } else out.flags[name] = [...(out.flags[name] || []), ...value.split(',').map((s) => s.trim()).filter(Boolean)]
+      } else if (name === 'token' && (value ?? argv[i + 1]) === '-') {
+        // login --token -: the token comes from stdin or a hidden prompt, never from argv
+        if (value === undefined) i++
+        out.flags.token = '-'
       } else if (name === 'key' || name === 'token') {
         throw new Error('pass the key in the BOX_TOKEN environment variable or at the prompt, never as an argument (it would end up in shell history)')
       } else throw new Error(`unknown option ${arg}`)
diff --git a/cli/src/box/browser.js b/cli/src/box/browser.js
new file mode 100644
index 0000000..822c331
--- /dev/null
+++ b/cli/src/box/browser.js
@@ -0,0 +1,34 @@
+import { spawn as nodeSpawn } from 'node:child_process'
+
+// openBrowser opens one http(s) URL in this computer's browser without any shell: the URL may come from a box's output,
+// so a shell metacharacter in it (& | ^ % on Windows' cmd) must never be interpreted. Each platform's opener takes the
+// URL as one argv element: macOS open(1), xdg-open (which passes "$1" quoted), and on Windows rundll32's
+// url.dll,FileProtocolHandler, the shell-free opener behind ShellExecute. BROWSER, when set, is run the same way.
+
+/** browserCommand is the opener and its argv for url, or null when url is no http(s) URL. */
+export function browserCommand(url, { env = process.env, platform = process.platform } = {}) {
+  let href
+  try {
+    const parsed = new URL(url)
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return null
+    href = parsed.href
+  } catch {
+    return null
+  }
+  if (env.BROWSER) return [env.BROWSER, [href]]
+  if (platform === 'darwin') return ['open', [href]]
+  if (platform === 'win32') return ['rundll32', ['url.dll,FileProtocolHandler', href]]
+  return ['xdg-open', [href]]
+}
+
+export function openBrowser(url, { env = process.env, platform = process.platform, spawn = nodeSpawn } = {}) {
+  const command = browserCommand(url, { env, platform })
+  if (!command) return false
+  try {
+    // shell: false is the default; it is spelled out because the URL must never reach a shell
+    spawn(command[0], command[1], { stdio: 'ignore', detached: true, shell: false, windowsVerbatimArguments: false }).on('error', () => {}).unref()
+    return true
+  } catch {
+    return false // the URL is printed too
+  }
+}
diff --git a/cli/src/box/connection.js b/cli/src/box/connection.js
new file mode 100644
index 0000000..d1094de
--- /dev/null
+++ b/cli/src/box/connection.js
@@ -0,0 +1,181 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import grpc from '@grpc/grpc-js'
+import protoLoader from '@grpc/proto-loader'
+
+// The protos are copied from simular-ai/box proto/ (see proto/README.md); the wire is the relay's native gRPC.
+const PROTO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'proto')
+const HEADER_BOX = 'x-cocoonbox-box'
+// Exec chunks are at most 64 KiB on every hop (contracts.md "Remote command").
+export const CHUNK = 64 << 10
+// A box agent frame is far below this; the edge allows the same.
+const MAX_MESSAGE = 16 << 20
+
+let services
+export function loadServices() {
+  if (services) return services
+  const def = protoLoader.loadSync(['cocoonbox/agent/v1/session.proto', 'cocoonbox/control/v1/boxes.proto'], {
+    includeDirs: [PROTO_ROOT],
+    keepCase: true,
+    longs: Number,
+    enums: String,
+    defaults: false,
+    oneofs: true,
+  })
+  const pkg = grpc.loadPackageDefinition(def)
+  services = { Session: pkg.cocoonbox.agent.v1.Session, Boxes: pkg.cocoonbox.control.v1.Boxes }
+  return services
+}
+
+/** describe turns a gRPC error into one line for a person. */
+export function describe(err) {
+  if (err && typeof err.code === 'number') {
+    const name = Object.keys(grpc.status).find((k) => grpc.status[k] === err.code) || String(err.code)
+    if (err.code === grpc.status.UNAUTHENTICATED) return `box refused the sign-in (${err.details}); run: npx @simular-ai/box login`
+    return `${name}: ${err.details || err.message}`
+  }
+  return err?.message || String(err)
+}
+
+/**
+ * BoxConnection is the CLI's gRPC channel to the relay: Boxes for the box list and wake, Session.Exec to run a command
+ * in a box. The token travels only in call metadata.
+ */
+export class BoxConnection {
+  constructor(endpoint, token) {
+    const url = new URL(endpoint)
+    const target = `${url.hostname}:${url.port || (url.protocol === 'https:' ? 443 : 80)}`
+    const creds = url.protocol === 'https:' ? grpc.credentials.createSsl() : grpc.credentials.createInsecure()
+    const { Session, Boxes } = loadServices()
+    const options = {
+      'grpc.max_receive_message_length': MAX_MESSAGE,
+      'grpc.max_send_message_length': MAX_MESSAGE,
+      // HTTP/2 pings while a call is open, so a half-open stream (sleep, a network change) fails within ~45 s instead of
+      // holding a raw terminal; the relay's load balancer answers them, and no ping goes out on an idle channel.
+      'grpc.keepalive_time_ms': 30000,
+      'grpc.keepalive_timeout_ms': 15000,
+      'grpc.keepalive_permit_without_calls': 0,
+    }
+    this.endpoint = endpoint
+    this.token = token
+    this.boxes = new Boxes(target, creds, options)
+    // Session shares the Boxes channel's options but is its own client, so a stalled Exec never holds a Boxes call.
+    this.session = new Session(target, creds, options)
+  }
+
+  metadata(box) {
+    const md = new grpc.Metadata()
+    md.set('authorization', `Bearer ${this.token}`)
+    if (box) md.set(HEADER_BOX, box)
+    return md
+  }
+
+  #unary(method, request) {
+    return new Promise((resolve, reject) => {
+      this.boxes[method](request, this.metadata(), { deadline: Date.now() + 30000 }, (err, res) => (err ? reject(err) : resolve(res)))
+    })
+  }
+
+  async listBoxes() {
+    const res = await this.#unary('List', {})
+    return res.boxes || []
+  }
+
+  async ensure(boxId) {
+    return this.#unary('Ensure', { box_id: boxId })
+  }
+
+  /** waitRunning polls the box list until boxId runs, for at most timeoutMs. */
+  async waitRunning(boxId, { timeoutMs = 180000, intervalMs = 2000, onState = () => {} } = {}) {
+    const deadline = Date.now() + timeoutMs
+    let last = ''
+    for (;;) {
+      const box = (await this.listBoxes()).find((b) => b.id === boxId)
+      if (!box) throw new Error(`box ${boxId} is gone`)
+      if (box.state === 'BOX_STATE_RUNNING') return box
+      if (box.state === 'BOX_STATE_FAILED') throw new Error(`box ${box.name} failed to start${box.failure_reason ? `: ${box.failure_reason}` : ''}`)
+      if (box.state !== last) onState(box.state)
+      last = box.state
+      if (Date.now() > deadline) throw new Error(`box ${box.name} is still ${stateName(box.state)} after ${Math.round(timeoutMs / 1000)} s`)
+      await new Promise((r) => setTimeout(r, intervalMs))
+    }
+  }
+
+  /**
+   * exec runs start (`{command, tty?}`) in box. input is an async iterable of client frames after start
+   * (`{stdin}`, `{eof: {}}`, `{signal}`, `{resize}`); it is read one frame at a time as the stream drains, so a slow box
+   * slows the reader. onOutput(buffer, isStderr) may return a promise, which pauses the stream until it settles.
+   * Resolves to the exit code, or null when the stream ended without one. The returned `call` lets a caller cancel.
+   */
+  exec(box, start, input, onOutput, { onCall = () => {} } = {}) {
+    return new Promise((resolve, reject) => {
+      const call = this.session.Exec(this.metadata(box))
+      onCall(call)
+      let code = null
+      let settled = false
+      const done = (fn, v) => {
+        if (settled) return
+        settled = true
+        fn(v)
+      }
+      call.on('data', (frame) => {
+        if (frame.body === 'exit_code') code = frame.exit_code ?? 0
+        else if (frame.body === 'stdout' || frame.body === 'stderr') {
+          const pending = onOutput(frame[frame.body] || Buffer.alloc(0), frame.body === 'stderr')
+          if (pending && typeof pending.then === 'function') {
+            call.pause()
+            pending.then(() => call.resume(), (err) => {
+              call.cancel()
+              done(reject, err)
+            })
+          }
+        }
+      })
+      call.on('error', (err) => {
+        // A cancel after the exit code is ours; anything else is the transport's.
+        if (code !== null && err.code === grpc.status.CANCELLED) return done(resolve, code)
+        done(reject, err)
+      })
+      call.on('end', () => done(resolve, code))
+      const write = (frame) =>
+        new Promise((res) => {
+          if (call.write(frame)) res()
+          else call.once('drain', res)
+        })
+      ;(async () => {
+        await write({ start })
+        for await (const frame of input) {
+          if (settled) return
+          await write(frame)
+        }
+        call.end()
+      })().catch((err) => {
+        call.cancel()
+        done(reject, err)
+      })
+    })
+  }
+
+  close() {
+    this.boxes.close()
+    this.session.close()
+  }
+}
+
+export function stateName(state) {
+  return String(state || '').replace(/^BOX_STATE_/, '').toLowerCase() || 'unknown'
+}
+
+/** frames turns parts (Buffers, or {file} paths read lazily) into stdin frames of at most CHUNK bytes, then eof. */
+export async function* frames(parts) {
+  for (const part of parts) {
+    if (Buffer.isBuffer(part)) {
+      for (let i = 0; i < part.length; i += CHUNK) yield { stdin: part.subarray(i, i + CHUNK) }
+    } else if (part && part.file) {
+      const stream = fs.createReadStream(part.file, { highWaterMark: CHUNK })
+      for await (const chunk of stream) yield { stdin: chunk }
+    }
+  }
+  yield { eof: {} }
+}
diff --git a/cli/src/box/endpoint.js b/cli/src/box/endpoint.js
new file mode 100644
index 0000000..45431dc
--- /dev/null
+++ b/cli/src/box/endpoint.js
@@ -0,0 +1,20 @@
+import path from 'node:path'
+import { DEFAULT_MCP_URL } from '../constants.js'
+
+/** The relay origin for gRPC, OAuth and the CLI's own token: BOX_ENDPOINT, else the origin of BOX_MCP_URL, else prod. */
+export function endpointUrl(env = process.env) {
+  const raw = (env.BOX_ENDPOINT || '').trim() || new URL((env.BOX_MCP_URL || '').trim() || DEFAULT_MCP_URL).origin
+  const url = new URL(raw)
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) {
+    throw new Error(`the box endpoint must be https (or http on localhost): ${raw}`)
+  }
+  return url.origin
+}
+
+/**
+ * Where the CLI keeps its state: BOX_HOME, else ~/.simular-box (0700). It holds the CLI's token (credentials.json, 0600)
+ * and offload/, the records of offloads in flight.
+ */
+export function boxHome(env = process.env, home = env.HOME || env.USERPROFILE) {
+  return env.BOX_HOME || path.join(home, '.simular-box')
+}
diff --git a/cli/src/box/login.js b/cli/src/box/login.js
new file mode 100644
index 0000000..893c5b4
--- /dev/null
+++ b/cli/src/box/login.js
@@ -0,0 +1,123 @@
+import crypto from 'node:crypto'
+import http from 'node:http'
+import os from 'node:os'
+
+// BrowserLogin signs the CLI in as the relay's first-party client (RFC 8252), as upstream's `cocoonbox login`: it opens
+// the consent page, takes the answer on a loopback port of its own, and redeems the code with PKCE for a device token,
+// which has no expiry and no refresh token and is revoked under Keys -> Devices.
+
+export const CLI_CLIENT = 'cocoonbox-cli'
+const AUTHORIZE_PATH = '/cb/oauth/authorize'
+const TOKEN_PATH = '/oauth/token'
+const REVOKE_PATH = '/oauth/revoke'
+const MAX_DEVICE_NAME = 64
+const PAGE = '<!doctype html><meta charset=utf-8><title>box</title><p>box has the answer. You can close this tab and return to the terminal.'
+
+const urlSafe = (buf) => buf.toString('base64url')
+
+export function challenge(verifier) {
+  return urlSafe(crypto.createHash('sha256').update(verifier).digest())
+}
+
+/** deviceName is this computer's name as the consent page and the Devices list show it. */
+export function deviceName(host = os.hostname()) {
+  const name = host.endsWith('.local') ? host.slice(0, -6) : host
+  let out = ''
+  for (const ch of name) {
+    if (Buffer.byteLength(out + ch) > MAX_DEVICE_NAME) break
+    out += ch
+  }
+  return out
+}
+
+export function authorizeUrl(endpoint, { redirect, challenge: chal, state, device }) {
+  const url = new URL(endpoint + AUTHORIZE_PATH)
+  url.search = new URLSearchParams({
+    response_type: 'code',
+    client_id: CLI_CLIENT,
+    redirect_uri: redirect,
+    scope: 'account',
+    code_challenge: chal,
+    code_challenge_method: 'S256',
+    state,
+    device_name: device,
+  }).toString()
+  return url.toString()
+}
+
+/** listen opens 127.0.0.1 on a free port and resolves the query of the first GET /callback. */
+function listen() {
+  let deliver
+  const answered = new Promise((resolve) => (deliver = resolve))
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1')
+    if (req.method !== 'GET' || url.pathname !== '/callback') {
+      res.writeHead(404).end()
+      return
+    }
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }).end(PAGE)
+    deliver(url.searchParams)
+  })
+  return new Promise((resolve, reject) => {
+    server.once('error', (err) => reject(new Error(`cannot listen on 127.0.0.1: ${err.message}`)))
+    server.listen(0, '127.0.0.1', () => resolve({ server, port: server.address().port, answered }))
+  })
+}
+
+async function post(endpoint, pathname, fields, fetchImpl = fetch) {
+  const res = await fetchImpl(endpoint + pathname, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(fields).toString(),
+    signal: AbortSignal.timeout(15000),
+  })
+  let body = {}
+  try {
+    body = await res.json()
+  } catch {
+    // an empty or non-JSON answer
+  }
+  return { status: res.status, body }
+}
+
+/**
+ * browserLogin runs the sign-in: open(url) shows the consent page; the promise resolves to the device token.
+ * The token is returned to the caller only; it is never printed or logged here.
+ */
+export async function browserLogin(endpoint, { open, timeoutMs = 600000, device = deviceName(), fetchImpl } = {}) {
+  const { server, port, answered } = await listen()
+  try {
+    const verifier = urlSafe(crypto.randomBytes(32))
+    const state = urlSafe(crypto.randomBytes(16))
+    const redirect = `http://127.0.0.1:${port}/callback`
+    await open(authorizeUrl(endpoint, { redirect, challenge: challenge(verifier), state, device }))
+    let timer
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error('no answer from the browser in time')), timeoutMs)
+    })
+    const answer = await Promise.race([answered, timeout]).finally(() => clearTimeout(timer))
+    if (answer.get('state') !== state) throw new Error('the browser brought back an answer to another sign-in')
+    const iss = answer.get('iss')
+    if ((iss || '').toLowerCase() !== endpoint.toLowerCase()) throw new Error(`the answer came from ${iss || 'an unnamed issuer'}, not ${endpoint}`)
+    if (answer.get('error')) throw new Error(`the sign-in was denied: ${answer.get('error_description') || answer.get('error')}`)
+    const code = answer.get('code')
+    if (!code) throw new Error('the answer carries no code')
+    const { status, body } = await post(
+      endpoint,
+      TOKEN_PATH,
+      { grant_type: 'authorization_code', code, client_id: CLI_CLIENT, redirect_uri: redirect, code_verifier: verifier },
+      fetchImpl,
+    )
+    if (status !== 200 || !body.access_token) throw new Error(`the server refused the sign-in: ${body.error_description || `HTTP ${status}`}`)
+    return body.access_token
+  } finally {
+    server.close()
+    server.closeAllConnections?.()
+  }
+}
+
+/** revoke ends a device token at the server; a token that is no device's is left alone (RFC 7009). */
+export async function revoke(endpoint, token, { fetchImpl } = {}) {
+  const { status } = await post(endpoint, REVOKE_PATH, { token, client_id: CLI_CLIENT }, fetchImpl)
+  if (status !== 200) throw new Error(`the server answered HTTP ${status} to the revoke`)
+}
diff --git a/cli/src/box/rsh.js b/cli/src/box/rsh.js
new file mode 100644
index 0000000..60f1f67
--- /dev/null
+++ b/cli/src/box/rsh.js
@@ -0,0 +1,314 @@
+import fs from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { describe, stateName } from './connection.js'
+
+// rsh runs a command in a box with this process's stdin, stdout and stderr, ssh-style, so rsync and git can use it as their
+// remote shell (contracts.md "Remote command", upstream `cocoonbox rsh`). It exits with the command's code, or 255 for its
+// own failures.
+
+export const RSH_USAGE = 'usage: npx @simular-ai/box rsh [--box NAME|ID] [-t] [-l USER] [HOST] COMMAND...'
+export const RSH_FAILURE = 255
+const MAX_TERMINFO = 256 << 10
+
+/** parseRsh splits rsh's argv into options and the words after them. */
+export function parseRsh(argv) {
+  const options = {}
+  let i = 0
+  for (; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--') {
+      i++
+      break
+    }
+    if (!a.startsWith('-')) break
+    if (a === '-t') {
+      options.tty = true
+      continue
+    }
+    if (!['--box', '--endpoint', '-l'].includes(a) || i + 1 >= argv.length) throw new Error(`unknown option ${a}\n${RSH_USAGE}`)
+    options[a.replace(/^-+/, '')] = argv[++i]
+  }
+  return { options, words: argv.slice(i) }
+}
+
+/**
+ * pickBox resolves the box and drops rsync's or git's host word. --box wins: a first word that is `box` or names one of
+ * the user's boxes is dropped as the host. Without --box, the first word names the box.
+ */
+export function pickBox(boxes, boxRef, words) {
+  const host = (w) => w.split('@').pop()
+  const named = (w) => boxes.find((b) => b.id === host(w) || b.name === host(w))
+  const rest = [...words]
+  let box
+  if (boxRef) {
+    box = boxes.find((b) => b.id === boxRef || b.name === boxRef)
+    if (!box) throw new Error(`no box named ${boxRef}; yours: ${boxes.map((b) => b.name).join(', ') || 'none'}`)
+    if (rest.length && (host(rest[0]) === 'box' || named(rest[0]))) rest.shift()
+  } else {
+    box = rest.length ? named(rest[0]) : null
+    if (!box) throw new Error(`name the box with --box or as the host\n${RSH_USAGE}`)
+    rest.shift()
+  }
+  return { box, command: rest.join(' ') }
+}
+
+/** wake ensures box runs, reporting progress on stderr, and returns it as the list then shows it. */
+export async function wake(connection, box, stderr = process.stderr) {
+  if (box.state === 'BOX_STATE_RUNNING') return box
+  stderr.write(`box: waking ${box.name}\n`)
+  await connection.ensure(box.id)
+  return connection.waitRunning(box.id, { onState: (s) => stderr.write(`box: ${box.name} is ${stateName(s)}\n`) })
+}
+
+/** terminfo is the local `infocmp -x` source of term, which a box without the entry compiles; empty when there is none. */
+export function terminfo(term) {
+  if (!term) return ''
+  const r = spawnSync('infocmp', ['-x', term], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+  if (r.status !== 0 || Buffer.byteLength(r.stdout || '') > MAX_TERMINFO) return ''
+  return r.stdout
+}
+
+/**
+ * Input is the frames sent after start: stdin chunks pulled one at a time as the stream asks (so a chunk or two at most
+ * wait in memory), then eof; signals and window sizes jump the queue.
+ */
+export class Input {
+  /** filter, when given, maps each stdin chunk (the tty escape); it may end the input by returning disconnect. */
+  constructor(stdin, { filter } = {}) {
+    this.filter = filter
+    this.urgent = []
+    this.wake = null
+    this.reader = stdin ? stdin[Symbol.asyncIterator]() : null
+    this.pending = null
+    this.ended = !stdin
+    this.eofSent = false
+  }
+
+  send(frame) {
+    this.urgent.push(frame)
+    const wake = this.wake
+    this.wake = null
+    wake?.()
+  }
+
+  #nextUrgent() {
+    return new Promise((resolve) => (this.wake = resolve))
+  }
+
+  async *[Symbol.asyncIterator]() {
+    for (;;) {
+      if (this.urgent.length) {
+        yield this.urgent.shift()
+        continue
+      }
+      if (this.ended) {
+        if (!this.eofSent) {
+          this.eofSent = true
+          yield { eof: {} }
+          continue
+        }
+        // after eof only signals and sizes go
+        await this.#nextUrgent()
+        continue
+      }
+      const urgent = this.#nextUrgent().then(() => null)
+      this.pending ??= this.reader.next().then((v) => ({ v }))
+      const got = await Promise.race([this.pending, urgent])
+      if (!got) continue
+      this.pending = null
+      if (got.v.done) {
+        this.ended = true
+        continue
+      }
+      let data = Buffer.isBuffer(got.v.value) ? got.v.value : Buffer.from(got.v.value)
+      if (this.filter) {
+        const r = this.filter(data)
+        data = r.data
+        if (r.disconnect) {
+          if (data.length) yield { stdin: data }
+          // stop reading; the caller cancels the stream
+          this.ended = true
+          this.eofSent = true
+          continue
+        }
+      }
+      if (data.length) yield { stdin: data }
+    }
+  }
+}
+
+const TILDE = 0x7e
+const DOT = 0x2e
+
+/**
+ * escapeFilter is ssh's escape for a raw terminal: `~.` at the start of a line disconnects, `~~` sends one `~`, and a
+ * `~` before anything else is sent as typed. Raw mode sends Ctrl-C to the box, so this is the way out of a stuck stream.
+ */
+export function escapeFilter(onDisconnect) {
+  let lineStart = true
+  let pending = false
+  return (buf) => {
+    const out = []
+    for (const b of buf) {
+      if (pending) {
+        pending = false
+        if (b === DOT) {
+          onDisconnect()
+          return { data: Buffer.from(out), disconnect: true }
+        }
+        out.push(TILDE)
+        if (b === TILDE) {
+          lineStart = false
+          continue
+        }
+      } else if (lineStart && b === TILDE) {
+        pending = true
+        continue
+      }
+      out.push(b)
+      lineStart = b === 0x0d || b === 0x0a
+    }
+    return { data: Buffer.from(out), disconnect: false }
+  }
+}
+
+/** writeTo writes data to a stream and resolves when it may take more, so a slow local reader slows the box. */
+export function writeTo(stream, data) {
+  if (stream.destroyed || stream.writableEnded) return undefined
+  if (stream.write(data)) return undefined
+  return new Promise((resolve) => {
+    const done = () => {
+      stream.off('drain', done)
+      stream.off('close', done)
+      resolve()
+    }
+    stream.once('drain', done)
+    stream.once('close', done)
+  })
+}
+
+/**
+ * attach runs start in box on this process's terminal or pipes. tap(buffer) sees every output chunk (sign-in watches for
+ * its link). Resolves to the exit code; a second INT or TERM rejects with code 255.
+ */
+export async function attach(connection, boxId, start, { tty = false, tap = () => {}, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr } = {}) {
+  let call
+  let ended = null // why this side ended the stream: 'escape' or 'pipe'
+  const end = (why) => {
+    if (ended) return
+    ended = why
+    call?.cancel()
+  }
+  const raw = tty && stdin?.isTTY
+  const input = new Input(stdin, { filter: raw ? escapeFilter(() => end('escape')) : undefined })
+  const restore = []
+  // A closed local reader (`rsh box cat big | head`) ends the stream quietly with 255, as ssh does, instead of a crash.
+  const onPipeError = (err) => {
+    if (err?.code === 'EPIPE' || err?.code === 'ERR_STREAM_DESTROYED') end('pipe')
+  }
+  for (const s of [stdout, stderr]) {
+    s.on('error', onPipeError)
+    restore.push(() => s.off('error', onPipeError))
+  }
+  if (tty) {
+    if (raw) {
+      stderr.write('box: ~. at the start of a line disconnects\r\n')
+      stdin.setRawMode(true)
+      restore.push(() => stdin.setRawMode(false))
+      const onResize = () => input.send({ resize: { rows: stdout.rows || 24, cols: stdout.columns || 80 } })
+      process.on('SIGWINCH', onResize)
+      restore.push(() => process.off('SIGWINCH', onResize))
+    }
+  }
+  let forwarded = false
+  const onSignal = (name) => () => {
+    if (forwarded) {
+      call?.cancel()
+      for (const r of restore.splice(0)) r()
+      process.exit(RSH_FAILURE)
+    }
+    forwarded = true
+    input.send({ signal: name })
+  }
+  const int = onSignal('EXEC_SIGNAL_INT')
+  const term = onSignal('EXEC_SIGNAL_TERM')
+  process.on('SIGINT', int)
+  process.on('SIGTERM', term)
+  restore.push(() => {
+    process.off('SIGINT', int)
+    process.off('SIGTERM', term)
+  })
+  try {
+    return await connection.exec(
+      boxId,
+      start,
+      input,
+      (data, isStderr) => {
+        if (ended) return undefined
+        tap(data)
+        return writeTo(isStderr ? stderr : stdout, data)
+      },
+      { onCall: (c) => (call = c) },
+    )
+  } catch (err) {
+    if (!ended) throw err
+    if (ended === 'escape') stderr.write('\r\nbox: disconnected\r\n')
+    return RSH_FAILURE
+  } finally {
+    for (const r of restore.splice(0)) r()
+    stdin?.pause?.()
+  }
+}
+
+/** rsh is the `rsh` command; it never returns, exiting with the remote code or 255. */
+export async function rsh(argv, { connect, env = process.env }) {
+  const report = env.BOX_RSH_REPORT
+  const fail = (message) => {
+    if (report) {
+      try {
+        fs.writeFileSync(report, `failed: ${message.split('\n')[0]}\n`)
+      } catch {
+        // the caller only reads it when present
+      }
+    }
+    process.stderr.write(`box rsh: ${message}\n`)
+    return RSH_FAILURE
+  }
+  let parsed
+  try {
+    parsed = parseRsh(argv)
+  } catch (err) {
+    return fail(err.message)
+  }
+  let connection
+  try {
+    connection = connect(parsed.options.endpoint)
+    const boxes = await connection.listBoxes()
+    const { box, command } = pickBox(boxes, parsed.options.box, parsed.words)
+    if (!command) return fail(`no command: rsh runs a command, not a login shell\n${RSH_USAGE}`)
+    await wake(connection, box)
+    const start = { command }
+    let tty = false
+    if (parsed.options.tty) {
+      if (process.stdin.isTTY) {
+        const t = env.TERM || ''
+        start.tty = { term: t, window: { rows: process.stdout.rows || 24, cols: process.stdout.columns || 80 }, terminfo: terminfo(t) }
+        tty = true
+      } else process.stderr.write('box rsh: no terminal for the command because stdin is not a terminal\n')
+    }
+    const code = await attach(connection, box.id, start, { tty })
+    if (code === null) return fail('the box ended the command without an exit code')
+    if (report) {
+      try {
+        fs.writeFileSync(report, `exit ${code}\n`)
+      } catch {
+        // best effort
+      }
+    }
+    return code
+  } catch (err) {
+    return fail(describe(err))
+  } finally {
+    connection?.close()
+  }
+}
diff --git a/cli/src/box/token-store.js b/cli/src/box/token-store.js
new file mode 100644
index 0000000..e68e8ff
--- /dev/null
+++ b/cli/src/box/token-store.js
@@ -0,0 +1,61 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const TOKEN_ENV = 'BOX_TOKEN'
+
+/**
+ * TokenStore keeps the CLI's own box token per endpoint in <boxHome>/credentials.json, mode 0600 in a 0700 directory,
+ * as gh and Claude Code do on Linux. BOX_TOKEN (a personal key, cb_...) wins over the file and is never written.
+ * It is one small interface, so an OS keychain backend can replace the file later without touching the callers.
+ */
+export class TokenStore {
+  constructor(dir, env = process.env) {
+    this.dir = dir
+    this.file = path.join(dir, 'credentials.json')
+    this.env = env
+  }
+
+  /** saved is the token login stored for endpoint, ignoring BOX_TOKEN: {token, source: 'browser' (a device token) | 'paste'}. */
+  saved(endpoint) {
+    const entry = this.#read()[endpoint]
+    return entry?.token ? { token: entry.token, source: entry.source || 'paste' } : null
+  }
+
+  /** get is the token calls use: BOX_TOKEN ({source: 'env'}) when set, else the saved one, else null. */
+  get(endpoint) {
+    const fromEnv = (this.env[TOKEN_ENV] || '').trim()
+    return fromEnv ? { token: fromEnv, source: 'env' } : this.saved(endpoint)
+  }
+
+  set(endpoint, token, source) {
+    const all = this.#read()
+    all[endpoint] = { token, source, saved_at: new Date().toISOString() }
+    this.#write(all)
+  }
+
+  remove(endpoint) {
+    const all = this.#read()
+    if (!(endpoint in all)) return false
+    delete all[endpoint]
+    this.#write(all)
+    return true
+  }
+
+  #read() {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.file, 'utf8'))
+      return parsed && typeof parsed === 'object' ? parsed : {}
+    } catch {
+      return {}
+    }
+  }
+
+  #write(all) {
+    fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 })
+    fs.chmodSync(this.dir, 0o700)
+    const tmp = `${this.file}.${process.pid}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(all, null, 2) + '\n', { mode: 0o600 })
+    fs.chmodSync(tmp, 0o600)
+    fs.renameSync(tmp, this.file)
+  }
+}
diff --git a/cli/src/cli.js b/cli/src/cli.js
index 017a14f..5bc74f4 100644
--- a/cli/src/cli.js
+++ b/cli/src/cli.js
@@ -5,6 +5,7 @@ import { createContext } from './context.js'
 import { CLIENTS, findClient } from './clients/index.js'
 import { DEFAULT_MCP_URL, KEY_ENV, KEYS_URL, WATCH_URL, INSTALL_URL, SUPPORT_EMAIL, EXAMPLE_PROMPTS, isOldUrl, looksLikeKey, validServerName } from './constants.js'
 import { probeEndpoint, checkKey } from './probe.js'
+import { OFFLOAD_HELP, boxContext, login, logout, rshCommand, offload, back } from './offload/commands.js'
 
 const VERSION = createRequire(import.meta.url)('../package.json').version
 
@@ -15,6 +16,8 @@ Usage:
   npx @simular-ai/box doctor  [--client <ids>] [--json]
   npx @simular-ai/box remove  [--client <ids>] [--yes] [--dry-run]
 
+${OFFLOAD_HELP}
+
 Clients: ${CLIENTS.map((c) => c.id).join(', ')}
 
 Options:
@@ -33,6 +36,8 @@ Set BOX_MCP_URL to use another box endpoint (default ${DEFAULT_MCP_URL}).
 `
 
 export async function main(argv, { env = process.env, stdout = process.stdout, isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY) } = {}) {
+  // rsh is rsync's and git's remote shell: its words after the options are the remote command, so they are not parsed here.
+  if (argv[0] === 'rsh') return rshCommand(boxContext(env), argv.slice(1))
   const args = parseArgs(argv)
   if (args.flags.version) {
     stdout.write(`${VERSION}\n`)
@@ -55,6 +60,14 @@ export async function main(argv, { env = process.env, stdout = process.stdout, i
     case 'remove':
     case 'uninstall':
       return remove(ctx, args.flags, { interactive })
+    case 'login':
+      return login(boxContext(env), args.flags, { stdout })
+    case 'logout':
+      return logout(boxContext(env), args.flags, { stdout })
+    case 'offload':
+      return offload(boxContext(env), args.flags, args.rest, { stdout })
+    case 'back':
+      return back(boxContext(env), args.flags, { stdout })
     default:
       throw new Error(`unknown command "${args.command}"; run with --help`)
   }
diff --git a/cli/src/offload/commands.js b/cli/src/offload/commands.js
new file mode 100644
index 0000000..833e215
--- /dev/null
+++ b/cli/src/offload/commands.js
@@ -0,0 +1,415 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { openBrowser } from '../box/browser.js'
+import { BoxConnection, describe } from '../box/connection.js'
+import { boxHome, endpointUrl } from '../box/endpoint.js'
+import { browserLogin, revoke } from '../box/login.js'
+import { attach, rsh, wake } from '../box/rsh.js'
+import { TokenStore, TOKEN_ENV } from '../box/token-store.js'
+import { GitRepo, OffloadError, landingSummary } from './git.js'
+import { HANDOVER_TEMPLATE, currentKind, findSignInLink, kind as kindOf, loginCommand, tmuxSession } from './model.js'
+import { Offloader } from './offloader.js'
+import { quote } from './run.js'
+import { OffloadStore } from './store.js'
+
+// The box-side commands of the CLI: login/logout, rsh, offload, back, and the box CLI's install and sign-in. They follow
+// upstream cocoonbox's CLI (macos/Sources/CocoonBoxCLI/main.swift) and its app's "Install in box" / "Sign in in the box".
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'simular-box.js')
+export const CMD = 'npx @simular-ai/box'
+
+export const OFFLOAD_HELP = `Offload (move a coding task into your box and back):
+  login [--token -]                     sign this CLI in to box in the browser (a device token, revocable
+                                        under Keys -> Devices); --token - reads a personal key (cb_...)
+                                        from stdin or a hidden prompt. Kept in ~/.simular-box (0600)
+  logout                                forget the token, and revoke it when login made it
+  rsh [--box NAME|ID] [-t] [HOST] COMMAND...
+                                        run COMMAND in a box with this stdin/stdout/stderr (rsync's and
+                                        git's remote shell); exits with its code, or 255
+  offload [--box B] [--kind claude|codex|cursor] [--dir PATH] [--handover FILE] [--yes] [--json]
+                                        move this repo's task into a box: preflight, copy, and a fresh box
+                                        CLI session that starts from the hand-over
+  offload handover-path                 print where to write the hand-over
+  offload --handover-prompt [--kind K]  print the request to paste into Codex or another CLI
+  offload inbox [--wait S] [--all] [--json]   what the box agent posted since the last look
+  offload status [--all] [--json]       the box CLI session of this repo, or of every repo
+  offload send [--interrupt] [TEXT...]  give the box agent a message (TEXT, else stdin)
+  offload secrets [add|remove ENTRY]    this repo's opted-in secrets: file:PATH, aws, kube, gcloud, ssh:KEY
+  offload install-cli [--box B] [--kind K]   install the box CLI with the vendor's official installer
+  offload sign-in [--box B] [--kind K]  run the box CLI's own login in the box on this terminal; its
+                                        sign-in link opens in this computer's browser
+  back [--interrupt] [--json]           bring the task back: the box agent's hand-over and its commits,
+                                        merged against the offload's snapshot; it first waits for the box
+                                        agent to go idle (--interrupt stops its current step instead)
+
+offload and back exit 0 when done, 1 on a failure (nothing changed here), 3 when the preflight blocks,
+and 4 when it warns and --yes was not given: ask the user, then run again with --yes.`
+
+/** Box is the CLI's context for box calls: endpoint, token store and offload store. */
+export function boxContext(env = process.env) {
+  const home = boxHome(env)
+  return {
+    env,
+    home,
+    tokens: new TokenStore(home, env),
+    store: new OffloadStore(home),
+    endpoint: (override) => (override ? endpointUrl({ BOX_ENDPOINT: override }) : endpointUrl(env)),
+  }
+}
+
+export function connect(ctx, override) {
+  const endpoint = ctx.endpoint(override)
+  const saved = ctx.tokens.get(endpoint)
+  if (!saved) throw new Error(`not signed in to ${endpoint}; run: ${CMD} login`)
+  return new BoxConnection(endpoint, saved.token)
+}
+
+// ---------- login ----------
+
+export async function login(ctx, flags, { stdin = process.stdin, stderr = process.stderr, stdout = process.stdout } = {}) {
+  const endpoint = ctx.endpoint(flags.endpoint)
+  let token
+  let source
+  if (flags.token !== undefined) {
+    if (flags.token !== '-') throw new Error('--token takes -: paste the token on stdin or at the prompt, never as an argument')
+    token = await readSecret(stdin, stderr, 'box personal key (cb_...): ')
+    source = 'paste'
+  } else {
+    token = await browserLogin(endpoint, {
+      open: (url) => {
+        stderr.write(`box: allow this computer in the browser; if no page opened, open\n  ${url}\n`)
+        openBrowser(url, { env: ctx.env })
+      },
+    })
+    source = 'browser'
+  }
+  if (!token) throw new Error('no token given')
+  const connection = new BoxConnection(endpoint, token)
+  try {
+    await connection.listBoxes()
+  } catch (err) {
+    if (source === 'browser') await revoke(endpoint, token).catch(() => {})
+    throw new Error(describe(err))
+  } finally {
+    connection.close()
+  }
+  const previous = ctx.tokens.saved(endpoint)
+  ctx.tokens.set(endpoint, token, source)
+  // A replaced device token would otherwise stay live with nothing holding it.
+  if (previous?.source === 'browser' && previous.token !== token) await revoke(endpoint, previous.token).catch(() => {})
+  if ((ctx.env[TOKEN_ENV] || '').trim()) stderr.write(`box: note: ${TOKEN_ENV} is set and wins over the saved token\n`)
+  stdout.write(`signed in to ${endpoint}\n`)
+  return 0
+}
+
+export async function logout(ctx, flags, { stdout = process.stdout } = {}) {
+  const endpoint = ctx.endpoint(flags.endpoint)
+  const saved = ctx.tokens.saved(endpoint)
+  let note = ''
+  if (saved?.source === 'browser') {
+    try {
+      await revoke(endpoint, saved.token)
+    } catch (err) {
+      note = ` (the server did not revoke the device token: ${err.message}; revoke it under Keys -> Devices at https://box.simular.ai/keys)`
+    }
+  }
+  ctx.tokens.remove(endpoint)
+  stdout.write(`signed out${note}\n`)
+  return note ? 1 : 0
+}
+
+async function readSecret(stdin, stderr, prompt) {
+  if (!stdin.isTTY) {
+    let data = ''
+    for await (const chunk of stdin) data += chunk
+    return data.split('\n')[0].trim()
+  }
+  stderr.write(prompt)
+  stdin.setRawMode(true)
+  stdin.resume()
+  return new Promise((resolve, reject) => {
+    let value = ''
+    const onData = (buf) => {
+      for (const ch of buf.toString('utf8')) {
+        if (ch === '\r' || ch === '\n') return finish(null, value.trim())
+        if (ch === '\u0003') return finish(new Error('cancelled'))
+        if (ch === '\u007f') value = value.slice(0, -1)
+        else value += ch
+      }
+    }
+    const finish = (err, v) => {
+      stdin.off('data', onData)
+      stdin.setRawMode(false)
+      stdin.pause()
+      stderr.write('\n')
+      if (err) reject(err)
+      else resolve(v)
+    }
+    stdin.on('data', onData)
+  })
+}
+
+// ---------- rsh ----------
+
+export function rshCommand(ctx, argv) {
+  return rsh(argv, { connect: (override) => connect(ctx, override), env: ctx.env })
+}
+
+// ---------- offload ----------
+
+/** offloadKey is the repo key of --dir or the working directory; for an offload in flight it falls back to the record of the same top level. */
+function offloadKey(ctx, flags, { inFlight = false } = {}) {
+  const dir = path.resolve(flags.dir || process.cwd())
+  const repo = GitRepo.open(dir, ctx.env)
+  if (!repo) throw new OffloadError('failed', `${dir} is not in a git repository`)
+  if (!inFlight || ctx.store.record(repo.key)) return repo.key
+  return ctx.store.records().filter((r) => r.top === repo.top).pop()?.repo || repo.key
+}
+
+async function runningBox(connection, ref) {
+  const boxes = await connection.listBoxes()
+  const box = ref ? boxes.find((b) => b.id === ref || b.name === ref) : boxes[0]
+  if (!box) throw new Error(ref ? `no box named ${ref}` : 'no box yet; create one at https://box.simular.ai')
+  return wake(connection, box)
+}
+
+function offloader(ctx, connection, box, stderr) {
+  const rsh = [process.execPath, BIN].map(quote).join(' ') + ` rsh --box ${quote(box.id)}`
+  return new Offloader({ connection, box, store: ctx.store, rsh, env: ctx.env, progress: (l) => stderr.write(`${l}\n`) })
+}
+
+function printFindings(findings, out) {
+  for (const f of findings) out.write(`${f.outcome.padEnd(8)}${f.check}: ${f.detail}\n`)
+}
+
+const json = (out, obj) => out.write(JSON.stringify(obj, null, 2) + '\n')
+
+export function offloadFailed(err, flags, { stdout, stderr }) {
+  const code = err.kind === 'refused' ? 3 : err.kind === 'needsYes' ? 4 : 1
+  if (flags.json) {
+    json(stdout, { ok: false, code: code === 3 ? 'refused' : code === 4 ? 'confirm' : 'failed', error: err.message, findings: err.findings })
+  } else {
+    printFindings(err.findings, stdout)
+    if (err.findings.some((f) => f.outcome === 'block' && f.check.includes('cli'))) {
+      const k = `--kind ${flags.kind || currentKind(process.env) || '<claude|codex|cursor>'}${flags.box ? ` --box ${flags.box}` : ''}`
+      stdout.write(`Install or sign in the box CLI from your own terminal: ${CMD} offload install-cli ${k} (when it is missing), then ${CMD} offload sign-in ${k}\n`)
+    }
+    stderr.write(`box: ${err.message}${code === 1 ? '; nothing changed on this computer' : ''}\n`)
+  }
+  return code
+}
+
+export function handoverPrompt(handoverPath, kindName) {
+  const k = kindOf(kindName)
+  return `OFFLOAD: move this task into my box, where a fresh ${k.title} session continues it while I am away. It knows only what your hand-over says, plus the repo.
+1. Finish the step you are in, or stop at a safe point. Do not start new work.
+2. Write a hand-over of this session to ${handoverPath} with the template below. Fill every section; write "none" for an empty one. Be concrete: exact commands, versions, paths, errors, decisions with their reasons. Names only for secrets, never values. The file is outside this repo: if your sandbox refuses the write, ask me to approve it.
+3. Run in this repo: ${CMD} offload --kind ${kindName}
+   It needs the network: if your sandbox refuses, ask me to approve it. Exit 3 is a block: tell me why, one line per finding. Exit 4 is warnings: tell me each one and run again with --yes only if I agree. Exit 1: tell me its last line.
+4. When it prints "offloaded", tell me the box, end your turn and change nothing more in this repo. \`${CMD} back\` in this repo brings the work back.
+
+${HANDOVER_TEMPLATE}`
+}
+
+export async function offload(ctx, flags, rest, io = {}) {
+  const stdout = io.stdout || process.stdout
+  const stderr = io.stderr || process.stderr
+  const sub = ['handover-path', 'inbox', 'status', 'send', 'secrets', 'install-cli', 'sign-in'].includes(rest[0]) ? rest[0] : null
+  const words = sub ? rest.slice(1) : rest
+  try {
+    if (sub === 'handover-path') {
+      stdout.write(ctx.store.handover(offloadKey(ctx, flags)) + '\n')
+      return 0
+    }
+    if (sub === 'secrets') return secretsCommand(ctx, flags, words, stdout)
+    const kindName = flags.kind || currentKind(ctx.env)
+    if (flags.kind) kindOf(flags.kind)
+    if (flags['handover-prompt']) {
+      stdout.write(handoverPrompt(ctx.store.handover(offloadKey(ctx, flags)), kindName || 'codex') + '\n')
+      return 0
+    }
+    if (sub === 'install-cli' || sub === 'sign-in') return boxCli(ctx, flags, sub, kindName, { stdout, stderr })
+    const connection = connect(ctx, flags.endpoint)
+    try {
+      if (sub) return await inboxCommand(ctx, flags, sub, words, connection, { stdout, stderr })
+      if (!kindName) throw new OffloadError('failed', 'name the box CLI with --kind claude, codex or cursor')
+      const key = offloadKey(ctx, flags)
+      const file = flags.handover ? path.resolve(flags.handover) : ctx.store.handover(key)
+      let handover
+      try {
+        handover = fs.readFileSync(file, 'utf8')
+      } catch {
+        throw new OffloadError('failed', `no hand-over at ${file}; write it there first (${CMD} offload handover-path)`)
+      }
+      const box = await runningBox(connection, flags.box)
+      const outcome = await offloader(ctx, connection, box, stderr).offload({ directory: path.resolve(flags.dir || process.cwd()), kind: kindName, handover, yes: Boolean(flags.yes) })
+      const r = outcome.record
+      if (flags.json) {
+        json(stdout, {
+          ok: true, box: box.name, box_id: box.id, dir: r.dir, tmux: tmuxSession(r), offload_id: r.id, repo: r.repo, accepted: outcome.accepted,
+          sent_bytes: outcome.sent, findings: outcome.findings, timings_ms: Object.fromEntries(outcome.timings),
+        })
+        return 0
+      }
+      printFindings(outcome.findings, stdout)
+      stdout.write(`offloaded to ${box.name}: ${outcome.cli}\n`)
+      stdout.write(`  copy ${r.dir}, tmux ${tmuxSession(r)}, offload ${r.id}\n`)
+      stdout.write(`  sent ${(outcome.sent / 1e6).toFixed(1)} MB; ${outcome.timings.map(([s, ms]) => `${s} ${(ms / 1000).toFixed(1)} s`).join(', ')}\n`)
+      if (!outcome.accepted) stdout.write(`  the box CLI has not taken the hand-over yet; watch it with \`${CMD} offload status\`\n`)
+      stdout.write(`  watch its terminal: ${CMD} rsh -t --box ${box.name} tmux attach -t ${tmuxSession(r)}\n`)
+      stdout.write(`Bring it back with /box:back or \`${CMD} back\`.\n`)
+      return 0
+    } finally {
+      connection.close()
+    }
+  } catch (err) {
+    if (err instanceof OffloadError) return offloadFailed(err, flags, { stdout, stderr })
+    throw new Error(describe(err))
+  }
+}
+
+async function inboxCommand(ctx, flags, sub, words, connection, { stdout }) {
+  const all = Boolean(flags.all)
+  const key = all && sub === 'status' ? null : offloadKey(ctx, flags, { inFlight: true })
+  const record = key ? ctx.store.record(key) : null
+  const box = await runningBox(connection, flags.box || record?.box)
+  const packer = offloader(ctx, connection, box, process.stderr)
+  if (sub === 'status') {
+    const sessions = await packer.status(key)
+    if (flags.json) return json(stdout, { sessions: sessions.map((s) => ({ repo: s.repo, name: s.name, cli: s.cli, offload_id: s.offload_id, status: s.status, hooks_silent: Boolean(s.hooks_silent) })) }), 0
+    if (!sessions.length) stdout.write('no box CLI session\n')
+    for (const s of sessions) {
+      stdout.write(`${s.name} ${s.cli} ${s.status} offload ${s.offload_id} (repo ${s.repo})${s.hooks_silent ? '; its hooks do not run, so the status comes from its transcript' : ''}\n`)
+    }
+    return 0
+  }
+  if (sub === 'send') {
+    let text = words.join(' ')
+    if (!text) for await (const chunk of process.stdin) text += chunk
+    if (!text.trim()) throw new OffloadError('failed', 'no message')
+    const delivery = await packer.send(key, text, Boolean(flags.interrupt))
+    if (flags.json) json(stdout, { delivery })
+    else stdout.write(`sent to the box agent: ${delivery}\n`)
+    return 0
+  }
+  // inbox
+  const since = all ? 0 : record?.seen || 0
+  const wait = flags.wait ? Number(flags.wait) : undefined
+  let { entries, status } = await packer.read(key, since, wait)
+  let newest = entries.length ? entries[entries.length - 1].seq : since
+  if (!all && record) {
+    const current = (e) => e.offload_id === record.id || !e.offload_id
+    if (entries.length && !entries.some(current)) {
+      ;({ entries, status } = await packer.read(key, newest, wait))
+      newest = entries.length ? entries[entries.length - 1].seq : newest
+    }
+    entries = entries.filter(current)
+  }
+  if (record && newest > (record.seen || 0)) ctx.store.save({ ...record, seen: newest })
+  if (flags.json) return json(stdout, { status, entries }), 0
+  if (!entries.length) stdout.write(`nothing new from the box agent (${status || 'no session'})\n`)
+  for (const e of entries) stdout.write(`#${e.seq} ${e.kind} at ${new Date(e.time_ms).toLocaleTimeString()}\n${e.body}\n\n`)
+  return 0
+}
+
+function secretsCommand(ctx, flags, words, stdout) {
+  const key = offloadKey(ctx, flags)
+  let entries = ctx.store.secrets(key)
+  if (words.length) {
+    const [action, entry] = words
+    if (!['add', 'remove'].includes(action) || words.length !== 2) throw new OffloadError('failed', `usage: ${CMD} offload secrets [add|remove ENTRY]`)
+    const rel = entry.startsWith('file:') || entry.startsWith('ssh:') ? entry.slice(entry.indexOf(':') + 1) : null
+    if (rel !== null && (!rel || path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..'))) {
+      throw new OffloadError('failed', `${entry}: name a path inside the repo (file:) or a key in ~/.ssh (ssh:), without ..`)
+    }
+    if (!(entry.startsWith('file:') || entry.startsWith('ssh:') || ['aws', 'kube', 'gcloud'].includes(entry))) {
+      throw new OffloadError('failed', 'an entry is file:PATH, aws, kube, gcloud or ssh:KEY')
+    }
+    entries = entries.filter((e) => e !== entry)
+    if (action === 'add') entries.push(entry)
+    ctx.store.setSecrets(key, entries)
+  }
+  stdout.write((entries.length ? entries.join('\n') : 'no secrets opted in') + '\n')
+  return 0
+}
+
+export async function back(ctx, flags, io = {}) {
+  const stdout = io.stdout || process.stdout
+  const stderr = io.stderr || process.stderr
+  try {
+    const key = offloadKey(ctx, flags, { inFlight: true })
+    const record = ctx.store.record(key)
+    if (!record) {
+      const last = path.join(ctx.store.root, key, 'back.md')
+      const st = fs.existsSync(last) ? fs.statSync(last) : null
+      throw new OffloadError('failed', 'nothing of this repo is in a box' + (st ? `; the hand-over brought back at ${st.mtime.toLocaleString()} is in ${last}` : ''))
+    }
+    const connection = connect(ctx, flags.endpoint)
+    try {
+      const box = await runningBox(connection, record.box)
+      const outcome = await offloader(ctx, connection, box, stderr).back(key, {
+        interrupt: Boolean(flags.interrupt),
+        onEntry: (e) => stderr.write(`box agent ${e.kind} #${e.seq}${e.kind === 'question' ? ':\n' + e.body : ''}\n`),
+      })
+      const landing = outcome.landing ? landingSummary(outcome.landing) : 'no repo'
+      if (flags.json) return json(stdout, { ok: true, landing, handover: outcome.handover, file: outcome.file, offload_id: record.id }), 0
+      stdout.write(`${landing}\nThe box agent's hand-over (also in ${outcome.file}):\n\n${outcome.handover}\n`)
+      return 0
+    } finally {
+      connection.close()
+    }
+  } catch (err) {
+    if (err instanceof OffloadError) return offloadFailed(err, flags, { stdout, stderr })
+    throw new Error(describe(err))
+  }
+}
+
+// ---------- the box CLI: install and sign in ----------
+
+async function boxCli(ctx, flags, sub, kindName, { stdout, stderr }) {
+  if (!kindName) throw new OffloadError('failed', 'name the box CLI with --kind claude, codex or cursor')
+  const k = kindOf(kindName)
+  const connection = connect(ctx, flags.endpoint)
+  try {
+    const box = await runningBox(connection, flags.box)
+    if (sub === 'install-cli') {
+      // The vendor's official installer, as the box's desktop user into its home, so it stays across saves and upgrades.
+      stderr.write(`box: installing ${k.title} in ${box.name}: ${k.install}\n`)
+      const code = await attach(connection, box.id, { command: k.install }, { stdin: null })
+      if (code !== 0) {
+        stderr.write(`box: the installer failed (exit ${code})\n`)
+        return 1
+      }
+      stdout.write(`installed ${k.title} in ${box.name}; next: ${CMD} offload sign-in --kind ${kindName}${flags.box ? ` --box ${flags.box}` : ''}\n`)
+      return 0
+    }
+    if (!process.stdin.isTTY) throw new OffloadError('failed', 'sign-in needs a terminal: the CLI asks you to paste a code')
+    // The CLI's own login on a terminal in the box. Its first https link on the vendor's own hosts opens here, once; the
+    // box is untrusted, so no other link from its output is opened. The login stays in the box.
+    stderr.write(`box: signing ${k.title} in inside ${box.name}. Approve in the browser, then paste the code here.\n`)
+    let seen = ''
+    let opened = false
+    const tap = (data) => {
+      if (opened) return
+      seen = (seen + data.toString('utf8')).slice(-(64 << 10))
+      const link = findSignInLink(seen, kindName)
+      if (!link) return
+      opened = true
+      openBrowser(link, { env: ctx.env })
+      stderr.write(`\r\nbox: opened the sign-in page in your browser (${new URL(link).hostname})\r\n`)
+    }
+    const term = ctx.env.TERM || ''
+    const code = await attach(
+      connection,
+      box.id,
+      { command: loginCommand(kindName), tty: { term, window: { rows: process.stdout.rows || 24, cols: process.stdout.columns || 80 } } },
+      { tty: true, tap },
+    )
+    stdout.write(code === 0 ? `\nsigned ${k.title} in inside ${box.name}\n` : `\nthe sign-in ended with exit ${code}\n`)
+    return code === 0 ? 0 : 1
+  } finally {
+    connection.close()
+  }
+}
+
diff --git a/cli/src/offload/env-probe.js b/cli/src/offload/env-probe.js
new file mode 100644
index 0000000..990940e
--- /dev/null
+++ b/cli/src/offload/env-probe.js
@@ -0,0 +1,69 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { runSync } from './run.js'
+
+// EnvProbe writes env.json: the versions this computer runs of the tools the repo uses, its package manager, and which
+// toolchain files and lockfiles it has (contracts.md "Environment"). Ported from upstream OffloadEnvironment.swift.
+
+export const FILES = [
+  '.mise.toml', 'mise.toml', '.tool-versions', '.nvmrc', '.node-version', '.python-version', '.go-version', 'rust-toolchain',
+  'rust-toolchain.toml', 'go.mod', 'package.json', 'Cargo.toml', '.devcontainer/devcontainer.json', 'flake.nix', 'shell.nix',
+]
+export const LOCKFILES = ['go.sum', 'Cargo.lock', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'uv.lock']
+
+const TOOLS = [
+  { name: 'go', markers: ['go.mod', 'go.sum', '.go-version'], argv: ['go', 'env', 'GOVERSION'] },
+  { name: 'rust', markers: ['Cargo.toml', 'rust-toolchain', 'rust-toolchain.toml'], argv: ['rustc', '-V'] },
+  { name: 'node', markers: ['package.json', '.nvmrc', '.node-version', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'], argv: ['node', '-v'] },
+  { name: 'python', markers: ['pyproject.toml', 'requirements.txt', 'setup.py', 'uv.lock', '.python-version'], argv: ['python3', '-V'] },
+]
+const MANAGERS = [
+  { lockfile: 'pnpm-lock.yaml', name: 'pnpm', argv: ['pnpm', '-v'] },
+  { lockfile: 'yarn.lock', name: 'yarn', argv: ['yarn', '-v'] },
+  { lockfile: 'package-lock.json', name: 'npm', argv: ['npm', '-v'] },
+  { lockfile: 'uv.lock', name: 'uv', argv: ['uv', '--version'] },
+]
+
+export function envJson(top, env) {
+  const exists = (name) => fs.existsSync(path.join(top, name))
+  const tools = {}
+  for (const tool of TOOLS) {
+    if (!tool.markers.some(exists)) continue
+    const v = version(tool.argv, env)
+    if (v) tools[tool.name] = v
+  }
+  const managers = {}
+  let pinned = null
+  try {
+    pinned = JSON.parse(fs.readFileSync(path.join(top, 'package.json'), 'utf8')).packageManager
+  } catch {
+    // no package.json
+  }
+  if (typeof pinned === 'string' && pinned.includes('@')) {
+    const at = pinned.indexOf('@')
+    managers[pinned.slice(0, at)] = pinned.slice(at + 1).split('+')[0]
+  } else {
+    for (const m of MANAGERS) {
+      if (!exists(m.lockfile)) continue
+      const v = version(m.argv, env)
+      if (v) managers[m.name] = v
+    }
+  }
+  const sorted = (o) => Object.fromEntries(Object.entries(o).sort(([a], [b]) => (a < b ? -1 : 1)))
+  return JSON.stringify({ files: FILES.filter(exists), lockfiles: LOCKFILES.filter(exists), package_managers: sorted(managers), tools: sorted(tools), v: 1 })
+}
+
+/** version takes the first version-looking word of a tool's output: go1.26.5, rustc 1.88.0, v22.11.0, Python 3.12.7. */
+export function version(argv, env) {
+  const r = runSync(argv, { env, timeoutMs: 10000 })
+  if (r.status !== 0) return null
+  return parseVersion(r.text)
+}
+
+export function parseVersion(text) {
+  for (const word of text.split(/\s+/)) {
+    const trimmed = word.replace(/^[^0-9]+/, '')
+    if (/^[0-9]/.test(trimmed) && trimmed.includes('.')) return trimmed
+  }
+  return null
+}
diff --git a/cli/src/offload/git.js b/cli/src/offload/git.js
new file mode 100644
index 0000000..4485d03
--- /dev/null
+++ b/cli/src/offload/git.js
@@ -0,0 +1,273 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { repoKey } from './model.js'
+import { runSync, run } from './run.js'
+
+// GitRepo runs git in one work tree for the packer: the snapshot, the ignored list, the bundle and the merge at back.
+// Ported from upstream loomhand/cocoonbox macos/Sources/CocoonBoxKit/OffloadGit.swift.
+
+export class OffloadError extends Error {
+  constructor(kind, message, { findings = [], reply } = {}) {
+    super(message)
+    this.kind = kind // handover | refused | needsYes | box | failed
+    this.findings = findings
+    this.reply = reply
+  }
+}
+
+const IDENT = { GIT_AUTHOR_NAME: 'box', GIT_AUTHOR_EMAIL: 'box@localhost', GIT_COMMITTER_NAME: 'box', GIT_COMMITTER_EMAIL: 'box@localhost' }
+
+export class GitRepo {
+  constructor(top, env) {
+    this.top = top
+    this.env = env
+  }
+
+  /** open finds the top level of the repository dir is in; null outside one. */
+  static open(dir, env = process.env) {
+    const r = runSync(['git', '-C', dir, 'rev-parse', '--show-toplevel'], { env })
+    if (r.status !== 0 || !r.text) return null
+    return new GitRepo(r.text, env)
+  }
+
+  run(args, { input, extra = {} } = {}) {
+    return runSync(['git', '-C', this.top, ...args], { env: { ...this.env, ...extra }, input })
+  }
+
+  runAsync(args, { extra = {} } = {}) {
+    return run(['git', '-C', this.top, ...args], { env: { ...this.env, ...extra } })
+  }
+
+  git(args, opts) {
+    const r = this.run(args, opts)
+    if (r.status !== 0) throw new OffloadError('failed', `git ${args.slice(0, 2).join(' ')}: ${r.error.split('\n').pop() || `exit ${r.status}`}`)
+    return r.text
+  }
+
+  verify(rev) {
+    const r = this.run(['rev-parse', '-q', '--verify', `${rev}^{commit}`])
+    return r.status === 0 ? r.text : null
+  }
+
+  get head() {
+    return this.verify('HEAD')
+  }
+
+  /** root is the oldest root commit of HEAD, empty for an unborn HEAD. */
+  get root() {
+    if (!this.head) return ''
+    const r = this.run(['rev-list', '--max-parents=0', 'HEAD'])
+    return r.status === 0 ? r.text.split('\n').pop() : ''
+  }
+
+  get key() {
+    return repoKey(this.top, this.root)
+  }
+
+  /** linked is true for a linked worktree, whose .git is a file naming a local path. */
+  get linked() {
+    try {
+      return fs.statSync(path.join(this.top, '.git')).isFile()
+    } catch {
+      return false
+    }
+  }
+
+  gitPath(name) {
+    const p = this.git(['rev-parse', '--git-path', name])
+    return path.isAbsolute(p) ? p : path.join(this.top, p)
+  }
+
+  /** snapshot commits the work tree, tracked and untracked files that are not ignored, through a temporary index over HEAD's tree. */
+  snapshot(index, message) {
+    fs.rmSync(index, { force: true })
+    try {
+      const real = this.gitPath('index')
+      if (fs.existsSync(real)) fs.copyFileSync(real, index)
+      const extra = { GIT_INDEX_FILE: index }
+      const head = this.head
+      if (head) {
+        if (this.run(['read-tree', '-m', head], { extra }).status !== 0) this.git(['read-tree', head], { extra })
+      } else this.git(['read-tree', '--empty'], { extra })
+      this.git(['add', '-A'], { extra })
+      const tree = this.git(['write-tree'], { extra })
+      return this.git(['commit-tree', tree, ...(head ? ['-p', head] : []), '-m', message], { extra: IDENT })
+    } finally {
+      fs.rmSync(index, { force: true })
+    }
+  }
+
+  /** keepIndex points ref at a commit of the index's tree, so a bundle carries staged content no other ref reaches. */
+  keepIndex(ref, scratch) {
+    fs.rmSync(scratch, { force: true })
+    try {
+      const real = this.gitPath('index')
+      if (!fs.existsSync(real)) return
+      fs.copyFileSync(real, scratch)
+      const w = this.run(['write-tree'], { extra: { GIT_INDEX_FILE: scratch } })
+      if (w.status !== 0) return // a conflicted index is left out
+      this.git(['update-ref', ref, this.git(['commit-tree', w.text, '-m', 'box index'], { extra: IDENT })])
+    } finally {
+      fs.rmSync(scratch, { force: true })
+    }
+  }
+
+  /** ignored lists the git-ignored entries, directories ending in /, relative to the top level. */
+  ignored() {
+    const r = this.run(['ls-files', '-z', '-o', '-i', '--exclude-standard', '--directory'])
+    if (r.status !== 0) throw new OffloadError('failed', `git ls-files: ${r.error}`)
+    return r.out.toString('utf8').split('\0').filter(Boolean)
+  }
+
+  /** bundle writes every ref's history the box lacks to file; false when there is none. */
+  bundle(file, notRefs) {
+    fs.rmSync(file, { force: true })
+    const known = notRefs.length
+      ? this.run(['cat-file', '--batch-check'], { input: notRefs.map((r) => r + '\n').join('') })
+          .text.split('\n')
+          .filter((l) => l && !l.endsWith(' missing'))
+          .map((l) => l.split(' ')[0])
+      : []
+    const r = this.run(['bundle', 'create', '-q', file, '--all', ...(known.length ? ['--not', ...known] : [])])
+    if (r.status === 0) return true
+    if (r.error.includes('empty bundle')) return false
+    throw new OffloadError('failed', `git bundle: ${r.error}`)
+  }
+
+  // ---------- back ----------
+
+  /**
+   * land brings the box's snapshot S' home against base S: a fast-forward when this repo still equals S, else a clean
+   * three-way merge applied uncommitted that leaves the user's uncommitted paths alone, else a branch at S' with this
+   * work tree untouched. Returns {kind: unchanged|fastForward|merged|branch, files?, branch?, conflicts?}; fastForward and
+   * merged also carry head (the box's commit HEAD's branch moved to, else null) and uncommitted (paths the work tree holds
+   * beyond that HEAD).
+   */
+  land({ id, base, box, index, now = new Date() }) {
+    const start = this.verify(base + '^')
+    const boxHead = this.verify(box + '^')
+    const head = this.head
+    const local = this.snapshot(index, 'box local')
+    const tree = (c) => this.git(['rev-parse', c + '^{tree}'])
+    const [baseTree, localTree, boxTree] = [tree(base), tree(local), tree(box)]
+    if (boxTree === baseTree && boxHead === start) return { kind: 'unchanged' }
+    const follows = boxHead ? (start ? boxHead === start || this.run(['merge-base', '--is-ancestor', start, boxHead]).status === 0 : true) : false
+    const move = boxHead && boxHead !== head && head === start && follows ? { old: head, new: boxHead } : null
+    // uncommitted lists what the work tree now holds that the (possibly moved) HEAD does not
+    const uncommitted = (to) => {
+      const at = move ? move.new : head
+      return this.git(['diff-tree', '-r', '--name-only', '--no-renames', at ? tree(at) : this.git(['mktree'], { input: '' }), to]).split('\n').filter(Boolean)
+    }
+    if (head === start && localTree === baseTree && (follows || !boxHead)) {
+      if (!this.#settle({ id, from: base, to: box, move, scratch: index })) return this.#branch(box, [], now)
+      return { kind: 'fastForward', head: move ? move.new : null, uncommitted: uncommitted(boxTree) }
+    }
+    const merge = this.run(['merge-tree', '--write-tree', '--name-only', `--merge-base=${base}`, local, box])
+    const lines = merge.out.toString('utf8').replace(/\n$/, '').split('\n')
+    if (merge.status !== 0 || !lines[0]) {
+      const conflicts = []
+      if (merge.status === 1) for (const l of lines.slice(1)) {
+        if (!l) break
+        conflicts.push(l)
+      }
+      return this.#branch(box, conflicts, now)
+    }
+    const merged = lines[0]
+    const files = this.git(['diff-tree', '-r', '--name-only', '--no-renames', localTree, merged]).split('\n').filter(Boolean)
+    const headTree = head ? tree(head) : this.git(['mktree'], { input: '' })
+    const dirty = new Set(this.git(['diff-tree', '-r', '--name-only', '--no-renames', headTree, localTree]).split('\n').filter(Boolean))
+    const touched = files.filter((f) => dirty.has(f))
+    if (touched.length) return this.#branch(box, touched, now)
+    if (!this.#settle({ id, from: localTree, to: merged, move, scratch: index })) return this.#branch(box, [], now)
+    return { kind: 'merged', files, head: move ? move.new : null, uncommitted: uncommitted(merged) }
+  }
+
+  // settle moves the work tree between trees and, with move, HEAD's branch and the index; the index is built aside under
+  // git's index.lock first, so a held lock or a patch that does not apply changes nothing.
+  #settle({ id, from, to, move, scratch }) {
+    let lock = null
+    try {
+      if (move) {
+        fs.rmSync(scratch, { force: true })
+        try {
+          const real = this.gitPath('index')
+          if (fs.existsSync(real)) fs.copyFileSync(real, scratch)
+          const extra = { GIT_INDEX_FILE: scratch }
+          let carried = false
+          if (move.old) {
+            const patch = this.#diff(move.old, move.new)
+            carried = !patch.length || this.run(['apply', '--cached', '--binary', '--whitespace=nowarn', '-'], { input: patch, extra }).status === 0
+          }
+          if (!carried) this.git(['read-tree', '-m', move.new], { extra })
+          const lockPath = this.gitPath('index.lock')
+          let fd
+          try {
+            fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644)
+          } catch {
+            throw new OffloadError('failed', `another git command holds ${lockPath}; nothing changed, try again`)
+          }
+          lock = lockPath
+          fs.writeSync(fd, fs.readFileSync(scratch))
+          fs.closeSync(fd)
+        } finally {
+          fs.rmSync(scratch, { force: true })
+        }
+      }
+      const patch = this.#diff(from, to)
+      if (patch.length && this.run(['apply', '--binary', '--whitespace=nowarn', '-'], { input: patch }).status !== 0) return false
+      if (move && lock) {
+        if (move.old) this.git(['update-ref', `refs/cocoonbox/pre-back/${id}`, move.old])
+        const sym = this.run(['symbolic-ref', '-q', 'HEAD'])
+        const ref = sym.status === 0 && sym.text ? [sym.text] : ['--no-deref', 'HEAD']
+        this.git(['update-ref', '-m', 'box back', ...ref, move.new, ...(move.old ? [move.old] : [])])
+        fs.renameSync(lock, this.gitPath('index'))
+        lock = null
+        this.run(['update-index', '-q', '--refresh'])
+      }
+      return true
+    } finally {
+      if (lock) fs.rmSync(lock, { force: true })
+    }
+  }
+
+  // diff is a binary patch between two trees that the user's diff settings cannot change.
+  #diff(from, to) {
+    const r = this.run([
+      'diff-tree', '-p', '--binary', '--full-index', '--no-renames', '--no-ext-diff', '--no-textconv', '--no-color',
+      '--src-prefix=a/', '--dst-prefix=b/', from, to,
+    ])
+    if (r.status !== 0) throw new OffloadError('failed', `git diff-tree: ${r.error}`)
+    return r.out
+  }
+
+  #branch(box, conflicts, now) {
+    const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')
+    const name = `cocoonbox/back-${stamp}`
+    this.git(['branch', '-f', name, box])
+    return { kind: 'branch', branch: name, conflicts }
+  }
+}
+
+const left = (paths) => (paths && paths.length ? `; uncommitted: ${paths.join(', ')}` : '')
+
+export function landingSummary(l) {
+  switch (l.kind) {
+    case 'unchanged':
+      return 'unchanged: the box made no change'
+    case 'fastForward':
+      return l.head
+        ? `fast-forward: this branch now points at the box's commit ${l.head.slice(0, 7)}${left(l.uncommitted)}`
+        : `fast-forward: the box made no commit; its changes are applied uncommitted (${(l.uncommitted || []).join(', ')})`
+    case 'merged':
+      return l.head
+        ? `merged: this branch now points at the box's commit ${l.head.slice(0, 7)}; the changes you made meanwhile are kept${left(l.uncommitted)}`
+        : `merged: the box's changes are applied uncommitted (${l.files.join(', ')})`
+    case 'branch':
+      return (
+        `conflict: the box's work is on the branch ${l.branch}; your work tree is untouched` +
+        (l.conflicts.length ? ` (it conflicts with, or would change your uncommitted, ${l.conflicts.join(', ')})` : '')
+      )
+    default:
+      return l.kind
+  }
+}
diff --git a/cli/src/offload/model.js b/cli/src/offload/model.js
new file mode 100644
index 0000000..494d983
--- /dev/null
+++ b/cli/src/offload/model.js
@@ -0,0 +1,192 @@
+import crypto from 'node:crypto'
+import path from 'node:path'
+
+// Ported from upstream loomhand/cocoonbox macos/Sources/CocoonBoxKit/Offload.swift and SignInLink.swift
+// (contracts.md "Offload"). The box side is cocoonbox-agent's, unchanged in simular-ai/box.
+
+/** The box CLIs a task can continue in. */
+export const KINDS = {
+  claude: {
+    title: 'Claude Code',
+    executable: 'claude',
+    install: 'curl -fsSL https://claude.ai/install.sh | bash',
+    login: 'claude auth login',
+    hosts: ['claude.ai', 'claude.com', 'anthropic.com'],
+  },
+  codex: {
+    title: 'Codex',
+    executable: 'codex',
+    install: 'curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | CODEX_NON_INTERACTIVE=1 sh',
+    login: 'codex login --device-auth',
+    hosts: ['auth.openai.com', 'chatgpt.com'],
+  },
+  cursor: {
+    title: 'Cursor',
+    executable: 'cursor-agent',
+    install: 'curl -fsSL https://cursor.com/install | bash',
+    login: 'cursor-agent login',
+    hosts: ['cursor.com'],
+  },
+}
+
+export function kind(name) {
+  const k = KINDS[name]
+  if (!k) throw new Error('--kind is claude, codex or cursor')
+  return { name, ...k }
+}
+
+/** loginCommand keeps the box's browser shut, so the user approves on this computer. */
+export function loginCommand(name) {
+  return `BROWSER=true NO_OPEN_BROWSER=1 ${kind(name).login}`
+}
+
+/** currentKind is the coding agent this process runs under; only Claude Code says so. */
+export function currentKind(env) {
+  return env.CLAUDECODE === '1' ? 'claude' : null
+}
+
+// ---------- hand-over ----------
+
+export const HANDOVER_TITLE = '# Hand-over: '
+export const HANDOVER_HEADINGS = [
+  '## Goal and definition of done',
+  '## User preferences and constraints',
+  '## Current state',
+  '## Decisions made',
+  '## Files touched',
+  '## Next steps',
+  '## Commands',
+  '## Environment facts',
+  '## Gotchas learned',
+  '## Open questions',
+]
+export const HANDOVER_LIMIT = 256 << 10
+
+export const HANDOVER_TEMPLATE = `# Hand-over: <one-line goal>
+
+From: <local | box>   Agent: <claude|codex|cursor>   Repo: <path>   Branch: <branch> @ <short sha>
+
+## Goal and definition of done
+<what the user asked for, in their words where it matters; what "done" means>
+
+## User preferences and constraints
+<style, scope limits, things the user said not to do, deadlines; or none>
+
+## Current state
+<where the work stands in one paragraph: what works, what is broken, what is half-done>
+
+## Decisions made
+- <decision> — <why>; rejected: <alternative and why>
+
+## Files touched
+- \`<path>\` — <what changed and why; whether it is finished>
+
+## Next steps
+1. <the very next action, specific enough to start without asking>
+2. <…>
+
+## Commands
+- Build: \`<command>\`   Test: \`<command>\`   Lint: \`<command>\`   Run: \`<command>\`
+- Verify the current state: \`<command>\` → <what passing looks like>
+
+## Environment facts
+- Tools and versions: <go 1.26.x, rustc 1.9x, node 22.x, …; where each came from>
+- Services: <local databases, ports, docker compose services; or none>
+- Hosts: <APIs or internal hosts the task calls; or none>
+- Secrets needed: <names only, never values; or none>
+- Installed during this session: <packages and tools added; or none>
+
+## Gotchas learned
+- <non-obvious things that cost time: flaky tests, a wrong doc, a tool quirk>
+
+## Open questions
+- <what needs the user, and what to do meanwhile>
+`
+
+/** handoverProblems lists what breaks the template; empty for a valid hand-over. */
+export function handoverProblems(text) {
+  const problems = []
+  if (Buffer.byteLength(text) > HANDOVER_LIMIT) problems.push(`larger than ${HANDOVER_LIMIT >> 10} KiB`)
+  const lines = text.split('\n').map((l) => (l.endsWith('\r') ? l.slice(0, -1) : l))
+  if (!(lines[0] || '').startsWith(HANDOVER_TITLE)) problems.push(`the first line does not start with "${HANDOVER_TITLE}"`)
+  for (const heading of HANDOVER_HEADINGS) {
+    const count = lines.filter((l) => l.trim() === heading).length
+    if (count === 0) problems.push(`missing "${heading}"`)
+    if (count > 1) problems.push(`"${heading}" appears ${count} times`)
+  }
+  return problems
+}
+
+/** section returns the lines under heading, up to the next ## heading. */
+export function section(text, heading) {
+  let inside = false
+  const out = []
+  for (const line of text.split('\n')) {
+    const t = line.trim()
+    if (t.startsWith('## ')) {
+      inside = t === heading
+      continue
+    }
+    if (inside) out.push(line)
+  }
+  return out
+}
+
+// ---------- names ----------
+
+const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex')
+
+/** repoKey is the first 12 hex of sha256 of the top level and the oldest root commit of HEAD. */
+export function repoKey(top, root) {
+  return sha256(`${top}\n${root}`).slice(0, 12)
+}
+
+/** copyName is the box copy's name before the box adds a -2, -3 suffix. */
+export function copyName(top) {
+  const mapped = [...path.basename(top)].map((c) => (/[A-Za-z0-9._-]/.test(c) ? c : '-')).join('')
+  const name = mapped.replace(/^\.+/, '').slice(0, 64)
+  return name || 'repo'
+}
+
+export function newId() {
+  return crypto.randomBytes(6).toString('hex')
+}
+
+export function tmuxSession(record) {
+  return `cb-off-${record.repo}-${record.kind}`
+}
+
+// ---------- sign-in link ----------
+
+// The box is untrusted: only an https link on the vendor's own hosts may open in the local browser.
+// eslint-disable-next-line no-control-regex
+const OSC8 = /\x1B\]8;[^;\x07\x1B]*;([^\x07\x1B]+)(?:\x07|\x1B\\)/g
+// eslint-disable-next-line no-control-regex
+const ESCAPES = /\x1B(?:\][^\x07\x1B]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|[@-Z\\-_])/g
+// A link is only RFC 3986 URL characters; quotes, spaces, control bytes, ^ | < > \ { } and backticks end it.
+const LINK = /https:\/\/[A-Za-z0-9\-._~:/?#[\]@!$&*+,;=%]+/g
+const WHOLE_LINK = /^https:\/\/[A-Za-z0-9\-._~:/?#[\]@!$&*+,;=%]+$/
+
+/** findSignInLink returns the first allowed link in output: an OSC 8 target, else a link in the text without escapes. */
+export function findSignInLink(output, kindName) {
+  const targets = [...output.matchAll(OSC8)].map((m) => m[1])
+  const text = output.replace(ESCAPES, '')
+  const links = [...text.matchAll(LINK)].map((m) => m[0].replace(/[.,;:!?)\]}]+$/, ''))
+  for (const candidate of [...targets, ...links]) {
+    // the parsed, normalized form is what opens; a target with characters outside a URL's is skipped
+    if (WHOLE_LINK.test(candidate) && signInAllowed(candidate, kindName)) return new URL(candidate).href
+  }
+  return null
+}
+
+export function signInAllowed(link, kindName) {
+  let url
+  try {
+    url = new URL(link)
+  } catch {
+    return false
+  }
+  if (url.protocol !== 'https:' || url.username || url.password) return false
+  const host = url.hostname.toLowerCase()
+  return kind(kindName).hosts.some((h) => host === h || host.endsWith('.' + h))
+}
diff --git a/cli/src/offload/offloader.js b/cli/src/offload/offloader.js
new file mode 100644
index 0000000..0b53c14
--- /dev/null
+++ b/cli/src/offload/offloader.js
@@ -0,0 +1,392 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { frames } from '../box/connection.js'
+import { envJson } from './env-probe.js'
+import { GitRepo, OffloadError } from './git.js'
+import { copyName, handoverProblems, kind as kindOf, newId } from './model.js'
+import { finding, imageFinding, localFindings, sizeFinding } from './preflight.js'
+import { quote, run, runSync } from './run.js'
+import { tarParts } from './tar.js'
+
+// Offloader is the local packer (design.md §27): the preflight, the snapshot, the transfer and the way back, over
+// Session.Exec to `cocoonbox-agent offload` in the box and rsync and git over `rsh`. Ported from upstream
+// loomhand/cocoonbox macos/Sources/CocoonBoxKit/Offloader.swift.
+
+export const BACK_WAIT_S = 600
+// How long a BACK may go without any hook from the box CLI before it is pasted again.
+export const BACK_RETRY_S = 60
+// How often back polls the box CLI's status while it waits for it to go idle before asking for the hand-over.
+export const IDLE_POLL_MS = 2000
+
+export class Offloader {
+  /**
+   * rsh is the remote-shell command rsync and git run (this CLI's `rsh --box <id>`); its children get the endpoint and
+   * token through env, never argv.
+   */
+  constructor({ connection, box, store, rsh, env, progress = () => {} }) {
+    this.connection = connection
+    this.box = box
+    this.store = store
+    this.rsh = rsh
+    this.env = env
+    // Only rsync and git, which run this CLI's rsh, get the token; the preflight's and the probe's tools never see it.
+    this.rshEnv = { ...env, BOX_ENDPOINT: connection.endpoint, BOX_TOKEN: connection.token }
+    this.progress = progress
+  }
+
+  // ---------- offload ----------
+
+  async offload({ directory, kind, handover, yes }) {
+    const problems = handoverProblems(handover)
+    if (problems.length) throw new OffloadError('handover', `the hand-over breaks the template: ${problems.join('; ')}`)
+    kindOf(kind)
+    const timings = []
+    let lap = Date.now()
+    const mark = (step) => {
+      timings.push([step, Date.now() - lap])
+      lap = Date.now()
+    }
+    const findings = []
+    const img = imageFinding(this.box.image)
+    if (img) findings.push(img)
+    const repo = GitRepo.open(directory, this.env)
+    if (!repo) throw new OffloadError('refused', 'refused by the preflight; nothing changed', { findings: [finding('git', 'block', `${directory} is not in a git repository`)] })
+    const key = repo.key
+    const stage = this.store.directory(key)
+    const excludes = path.join(stage, 'excludes')
+    const bundle = path.join(stage, 'offload.bundle')
+    const refs = []
+    try {
+      if (runSync(['rsync', '--version'], { env: this.env }).status !== 0) {
+        findings.push(finding('rsync', 'block', 'rsync is not installed on this computer; offload copies the repo with it (macOS ships it; on Linux install the rsync package)'))
+      }
+      findings.push(...(await localFindings(repo, { handover, optedIn: this.store.secrets(key), env: this.env })))
+      fs.writeFileSync(excludes, repo.ignored().map((p) => '/' + escape(p) + '\n').join(''))
+      if (!this.store.sizeConfirmed(key)) {
+        const size = sizeFinding(this.dryRun(repo, excludes, stage))
+        if (size) findings.push(size)
+      }
+      mark('preflight')
+      if (findings.some((f) => f.outcome === 'block')) throw refused(findings)
+
+      const id = newId()
+      const name = copyName(repo.top)
+      let begin
+      try {
+        begin = await this.verb(['begin', '--repo', key, '--name', name, '--kind', kind, '--id', id])
+      } catch (err) {
+        if (err instanceof OffloadError && err.kind === 'box' && err.reply?.code === 'refused') {
+          const refusal = replyFindings(err.reply)
+          throw refused([...findings, ...(refusal.length ? refusal : [finding('box', 'block', err.message)])])
+        }
+        throw err
+      }
+      findings.push(...replyFindings(begin))
+      mark('begin')
+      if (findings.some((f) => f.outcome === 'block')) throw refused(findings)
+      if (!yes && findings.length) throw new OffloadError('needsYes', "the preflight has warnings; go on only with the user's yes (--yes)", { findings })
+      const dir = begin.dir
+      if (!dir) throw new OffloadError('failed', 'begin named no directory')
+      if (Array.isArray(begin.ignored) && begin.ignored.length) fs.appendFileSync(excludes, begin.ignored.map((p) => '/' + escape(p) + '\n').join(''))
+
+      refs.push(`refs/cocoonbox/offload/${id}`, `refs/cocoonbox/index/${id}`)
+      const record = {
+        id, repo: key, box: this.box.id, box_name: this.box.name, name, dir, kind, base: null, top: repo.top,
+        started_at_ms: Date.now(), seen: 0,
+      }
+      let sent = 0
+      let sending = false
+      let reply
+      try {
+        const members = [['handover.md', Buffer.from(handover)]]
+        const index = path.join(stage, 'snapshot.index')
+        const snapshot = repo.snapshot(index, `box offload ${id}`)
+        record.base = snapshot
+        repo.git(['update-ref', refs[0], snapshot])
+        repo.keepIndex(refs[1], index)
+        const env = envJson(repo.top, this.env)
+        fs.writeFileSync(path.join(stage, 'env.json'), env)
+        members.push(['env.json', Buffer.from(env)])
+        mark('snapshot')
+        sent = await this.rsync(repo, dir, excludes)
+        mark('rsync')
+        if (repo.bundle(bundle, Object.values(begin.refs || {}))) {
+          members.push(['offload.bundle', { file: bundle }])
+          sent += fs.statSync(bundle).size
+        }
+        if (repo.linked) {
+          members.push(['HEAD', fs.readFileSync(repo.gitPath('HEAD'))])
+          members.push(['index', fs.readFileSync(repo.gitPath('index'))])
+        }
+        for (const [n, data] of this.secrets(this.store.secrets(key), repo.top)) members.push([n, data])
+        mark('bundle')
+        this.store.save(record)
+        sending = true
+        reply = await this.verb(['send', '--repo', key, '--kind', kind, '--id', id], tarParts(members))
+        mark('send')
+      } catch (err) {
+        // a send cut off in transit may have started the box CLI, so its record stays for back
+        if (sending && !(err instanceof OffloadError)) {
+          throw new OffloadError('failed', `the connection broke while the box took the task (${err.message}); check \`npx @simular-ai/box offload status\`, then offload again or bring it back`)
+        }
+        this.store.remove(key)
+        for (const ref of refs) repo.run(['update-ref', '-d', ref])
+        throw err
+      }
+      if (findings.some((f) => f.check === 'size')) this.store.confirmSize(key)
+      const cli = begin.cli || {}
+      if (cli.hooks_blocked) this.progress(`warning: ${cli.hooks_blocked} turns off the hooks the box reads the CLI's status from; it reads the transcript instead`)
+      const account = cli.account ? `, signed in as ${cli.account}` : ''
+      return { record, accepted: Boolean(reply.accepted), findings, cli: `${kindOf(kind).title} ${cli.version || ''}`.trim() + account, timings, sent }
+    } finally {
+      fs.rmSync(excludes, { force: true })
+      fs.rmSync(bundle, { force: true })
+    }
+  }
+
+  /** rsync copies the work tree and .git without its objects, leaving the box's ignored files alone; returns the bytes sent. */
+  async rsync(repo, dir, excludes) {
+    const report = path.join(path.dirname(excludes), 'rsh-report')
+    fs.rmSync(report, { force: true })
+    try {
+      const argv = ['rsync', '-az', '--stats', '--delete', `--exclude-from=${excludes}`, '--exclude=/.git/objects/', ...(repo.linked ? ['--exclude=/.git'] : []), '-e', this.rsh, repo.top + '/', `box:${dir}/`]
+      const r = await run(argv, { env: { ...this.rshEnv, BOX_RSH_REPORT: report } })
+      if (r.status !== 0) {
+        let side = 'rsh never reported, so it did not start or was killed'
+        try {
+          const text = fs.readFileSync(report, 'utf8')
+          const [head, ...rest] = text.split('\n')
+          const tail = rest.join('\n').trim()
+          side = (head.startsWith('exit ') ? `the box command exited ${head.slice(5)}` : `rsh ${head}`) + (tail ? `, with stderr:\n${tail}` : '')
+        } catch {
+          // no report
+        }
+        throw new OffloadError('failed', `rsync to the box failed (${r.status}); ${side}\nrsync stderr:\n${r.error}`)
+      }
+      const line = r.text.split('\n').find((l) => l.startsWith('Total sent:') || l.startsWith('Total bytes sent:')) || ''
+      return Number(line.replace(/[^0-9]/g, '')) || 0
+    } finally {
+      fs.rmSync(report, { force: true })
+    }
+  }
+
+  /** dryRun is the bytes rsync would send to an empty copy. */
+  dryRun(repo, excludes, stage) {
+    const empty = fs.mkdtempSync(path.join(stage, 'dry-run-'))
+    try {
+      const argv = ['rsync', '-an', '--stats', `--exclude-from=${excludes}`, '--exclude=/.git/objects/', ...(repo.linked ? ['--exclude=/.git'] : []), repo.top + '/', empty + '/']
+      const res = runSync(argv, { env: this.env }).text
+      const line = res.split('\n').find((l) => l.startsWith('Total transferred file size:')) || ''
+      return Number(line.replace(/[^0-9]/g, '')) || 0
+    } finally {
+      fs.rmSync(empty, { recursive: true, force: true })
+    }
+  }
+
+  /** secrets reads the opted-in entries as stream members; values never reach argv, the environment or a log. */
+  secrets(entries, top) {
+    const home = this.env.HOME || os.homedir()
+    const read = (file, name) => {
+      try {
+        return [name, fs.readFileSync(file)]
+      } catch {
+        throw new OffloadError('failed', `the opted-in secret ${name} is missing on this computer (${file})`)
+      }
+    }
+    return entries.flatMap((entry) => {
+      if (entry.startsWith('file:')) return [read(path.join(top, entry.slice(5)), 'secrets/file/' + entry.slice(5))]
+      if (entry === 'aws') return [read(path.join(home, '.aws/credentials'), 'secrets/aws')]
+      if (entry === 'kube') return [read((this.env.KUBECONFIG || '').split(':')[0] || path.join(home, '.kube/config'), 'secrets/kube')]
+      if (entry === 'gcloud') {
+        const root = path.join(home, '.config/gcloud')
+        const out = []
+        const walk = (dir) => {
+          let list = []
+          try {
+            list = fs.readdirSync(dir, { withFileTypes: true })
+          } catch {
+            return
+          }
+          for (const d of list) {
+            const full = path.join(dir, d.name)
+            const rel = path.relative(root, full)
+            if (rel.startsWith('logs')) continue
+            if (d.isDirectory()) walk(full)
+            else if (d.isFile()) out.push(read(full, 'secrets/gcloud/' + rel))
+          }
+        }
+        walk(root)
+        return out
+      }
+      if (entry.startsWith('ssh:')) return [read(path.join(home, '.ssh', entry.slice(4)), 'secrets/ssh/' + entry.slice(4))]
+      throw new OffloadError('failed', `unknown secret entry ${entry}`)
+    })
+  }
+
+  // ---------- back ----------
+
+  /** back asks the box agent for its hand-over, waits for it, fetches the box's commits and lands them against S, then ends the box CLI session. */
+  async back(key, { interrupt = false, onEntry = () => {}, waitS = BACK_WAIT_S, retryS = BACK_RETRY_S, pollMs = IDLE_POLL_MS } = {}) {
+    const record = this.store.record(key)
+    if (!record) throw new OffloadError('failed', 'nothing of this repo is in the box')
+    let { entries } = await this.read(key, 0)
+    let back = [...entries].reverse().find((e) => e.kind === 'back' && e.offload_id === record.id)
+    let since = Math.max(0, ...entries.map((e) => e.seq))
+    // A pasted BACK that the box CLI never took (seen on prod: the paste vanished and the session stayed "working" with no
+    // hook) is pasted again once, with --interrupt so it is not queued behind that phantom turn.
+    let hookBefore = null
+    let retryAt = null
+    const deadline = Date.now() + waitS * 1000
+    if (!back) {
+      // BACK pasted while the box CLI is still ending a turn can vanish (delivery_unconfirmed), so wait for it to be idle;
+      // --interrupt stops the current step anyway and skips the wait.
+      if (!interrupt) await this.#untilIdle(key, deadline, waitS, pollMs)
+      hookBefore = await this.#hookAt(key)
+      const sent = await this.verb(['send', '--repo', key, '--back', ...(interrupt ? ['--interrupt'] : [])], [Buffer.alloc(0)])
+      this.progress('asked the box agent for its hand-over; waiting')
+      // only a paste into an idle CLI can vanish; a queued BACK waits for a real turn to end
+      if (sent.delivery === 'pasted') retryAt = Date.now() + retryS * 1000
+    }
+    while (!back) {
+      let left = Math.max(1, Math.ceil((deadline - Date.now()) / 1000))
+      if (retryAt) left = Math.min(left, Math.max(1, Math.ceil((retryAt - Date.now()) / 1000)))
+      const res = await this.read(key, since, left)
+      for (const entry of res.entries) {
+        since = Math.max(since, entry.seq)
+        if (entry.offload_id === record.id || !entry.offload_id) onEntry(entry)
+        if (entry.kind === 'blocked') throw new OffloadError('failed', `back is blocked in the box: ${entry.body}`)
+      }
+      back = [...res.entries].reverse().find((e) => e.kind === 'back' && e.offload_id === record.id)
+      if (!back && res.status === 'stopped') throw new OffloadError('failed', 'the box CLI session stopped without handing the work back')
+      if (!back && retryAt && Date.now() >= retryAt) {
+        retryAt = null
+        if (res.status === 'working' && (await this.#hookAt(key)) === hookBefore) {
+          this.progress('the box CLI has not taken BACK; asking again')
+          await this.verb(['send', '--repo', key, '--back', '--interrupt'], [Buffer.alloc(0)])
+        }
+      }
+      if (!back && Date.now() >= deadline) {
+        throw new OffloadError(
+          'failed',
+          `the box agent has not handed the work back after ${Math.round(waitS / 60)} min (status ${res.status}); BACK stays queued for its next idle. Run back again later, or back --interrupt to stop its current step`,
+        )
+      }
+    }
+    const file = this.store.back(key)
+    fs.writeFileSync(file, back.body)
+    let landing = null
+    if (record.base && record.top) {
+      const repo = GitRepo.open(record.top, this.env)
+      if (!repo) throw new OffloadError('failed', `${record.top} is no longer a git repository`)
+      const ref = `refs/cocoonbox/back/${record.id}`
+      const fetch = await repo.runAsync(['fetch', '-q', `box:${record.dir}`, '+refs/heads/*:refs/cocoonbox/box/*', `+${ref}:${ref}`], {
+        extra: { GIT_SSH_COMMAND: this.rsh, GIT_SSH_VARIANT: 'simple', BOX_ENDPOINT: this.rshEnv.BOX_ENDPOINT, BOX_TOKEN: this.rshEnv.BOX_TOKEN },
+      })
+      if (fetch.status !== 0) throw new OffloadError('failed', `git fetch from the box failed (${fetch.status}):\n${fetch.error}`)
+      landing = repo.land({ id: record.id, base: record.base, box: ref, index: path.join(this.store.directory(key), 'snapshot.index') })
+    }
+    await this.verb(['end', '--repo', key])
+    this.store.remove(key)
+    return { record, handover: back.body, file, landing }
+  }
+
+  /**
+   * untilIdle returns once the repo's box CLI session has been idle (or blocked, after an unconfirmed delivery) on two
+   * polls in a row, or at once when the box reports no session status. It fails on a stopped session, and when the
+   * session is still busy at the deadline, before anything was sent.
+   */
+  async #untilIdle(key, deadline, waitS, pollMs) {
+    let readyBefore = false
+    let said = false
+    for (;;) {
+      const status = (await this.status(key)).find((x) => x.repo === key)?.status || ''
+      if (status === 'stopped') throw new OffloadError('failed', 'the box CLI session stopped without handing the work back')
+      const ready = !status || status === 'idle' || status === 'blocked'
+      if (ready && (readyBefore || !status)) return
+      readyBefore = ready
+      if (!ready && !said) {
+        this.progress(`the box agent is ${status}; waiting for it to go idle before asking for its hand-over`)
+        said = true
+      }
+      if (Date.now() >= deadline) {
+        throw new OffloadError(
+          'failed',
+          `the box agent is still ${status} after ${Math.round(waitS / 60)} min; nothing was sent. Run back again later, or back --interrupt to stop its current step and hand back now`,
+        )
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.max(0, Math.min(pollMs, deadline - Date.now()))))
+    }
+  }
+
+  /** hookAt is when the repo's box CLI last ran a hook, from `offload status`; null when unknown. */
+  async #hookAt(key) {
+    try {
+      return (await this.status(key)).find((x) => x.repo === key)?.hook_at_ms ?? null
+    } catch {
+      return null
+    }
+  }
+
+  // ---------- inbox ----------
+
+  async read(key, since, wait) {
+    const reply = await this.verb(['read', '--repo', key, '--since', String(since), ...(wait ? ['--wait', String(wait)] : [])])
+    return { entries: reply.entries || [], status: reply.status || '' }
+  }
+
+  async status(key) {
+    const reply = await this.verb(['status', ...(key ? ['--repo', key] : [])])
+    return reply.sessions || []
+  }
+
+  /** send hands the box agent a message: pasted when it is idle, queued while it works. */
+  async send(key, message, interrupt) {
+    const reply = await this.verb(['send', '--repo', key, '--message', ...(interrupt ? ['--interrupt'] : [])], [Buffer.from(message)])
+    return reply.delivery || ''
+  }
+
+  // ---------- transport ----------
+
+  async verb(args, input = []) {
+    const command = 'cocoonbox-agent offload ' + args.map(quote).join(' ')
+    const { code, out, err } = await this.exec(command, input)
+    const line = out.toString('utf8').split('\n').filter(Boolean).pop() || ''
+    let reply
+    try {
+      reply = JSON.parse(line)
+    } catch {
+      const reason = err.split('\n').filter(Boolean).pop() || `exit ${code}`
+      throw new OffloadError('failed', `the box cannot run \`cocoonbox-agent offload ${args[0]}\` (${reason}); upgrade the box (npx @simular-ai/box doctor)`)
+    }
+    if (code !== 0 || reply.ok !== true) throw new OffloadError('box', `the box said ${reply.code || 'failed'}: ${reply.error || `exit ${code}`}`, { reply })
+    return reply
+  }
+
+  async exec(command, input = []) {
+    const out = []
+    let err = ''
+    const code = await this.connection.exec(this.box.id, { command }, frames(input), (data, isStderr) => {
+      if (!isStderr) return void out.push(data)
+      const text = data.toString('utf8')
+      err += text
+      for (const l of text.split('\n')) if (l) this.progress(l)
+    })
+    if (code === null) throw new OffloadError('failed', `the box ended \`${command.slice(0, 60)}\` without an exit code`)
+    return { code, out: Buffer.concat(out), err }
+  }
+}
+
+function refused(findings) {
+  return new OffloadError('refused', 'refused by the preflight; nothing changed', { findings })
+}
+
+/** replyFindings reads a box reply's findings, in begin's output and in its refusal. */
+export function replyFindings(reply) {
+  return (reply.findings || []).map((f) => finding(f.check || 'box', ['block', 'warn', 'confirm'].includes(f.outcome) ? f.outcome : 'warn', f.detail || ''))
+}
+
+/** escape makes a path a literal rsync pattern. */
+export function escape(p) {
+  return p.replace(/[*?[\\]/g, (c) => '\\' + c)
+}
diff --git a/cli/src/offload/preflight.js b/cli/src/offload/preflight.js
new file mode 100644
index 0000000..f5be727
--- /dev/null
+++ b/cli/src/offload/preflight.js
@@ -0,0 +1,290 @@
+import dns from 'node:dns'
+import fs from 'node:fs'
+import path from 'node:path'
+import { section } from './model.js'
+import { runSync } from './run.js'
+
+// The local half of the offload preflight (contracts.md "Offload", Preflight), ported from upstream OffloadPreflight.swift.
+// A block stops with nothing changed; a warn, or a confirm (a warn naming the size), goes on only with the user's yes.
+// The lsof and scutil checks run where those tools exist (macOS, most Linux); elsewhere they find nothing.
+
+export const SIZE_LIMIT = 500_000_000
+const MAC_TOOLS = new Set(['xcodebuild', 'xcrun', 'security', 'launchctl', 'open'])
+const APPLE_PLATFORMS = new Set(['macOS', 'iOS', 'tvOS', 'watchOS', 'visionOS', 'macCatalyst', 'driverKit'])
+const COMMON_NAMES = new Set([
+  'HOME', 'PATH', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'TMPDIR', 'PWD', 'LANG', 'LC_ALL', 'CI', 'DEBUG', 'EDITOR', 'TZ',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_DATA_HOME',
+])
+
+export const finding = (check, outcome, detail) => ({ check, outcome, detail })
+
+/** imageFinding blocks an upstream cbdesk image older than v22; our sbxdesk images all carry the box packer, and begin checks the rest. */
+export function imageFinding(image) {
+  const m = /^cbdesk:v(\d+)/.exec(image || '')
+  if (!m || Number(m[1]) >= 22) return null
+  return finding('image', 'block', `the box runs ${image}, older than cbdesk:v22; upgrade the box first`)
+}
+
+export async function localFindings(repo, { handover, optedIn, env }) {
+  const files = repo.run(['ls-files', '-z', '-c', '-o', '--exclude-standard']).out.toString('utf8').split('\0').filter(Boolean)
+  let ignored = []
+  try {
+    ignored = repo.ignored()
+  } catch {
+    // reported by the caller's own ignored() call
+  }
+  const texts = configTexts(repo.top)
+  return [
+    ...macOSOnly(repo.top, files, handover),
+    ...services(texts, repo.top, env),
+    ...(await vpnHosts(repo, texts, env)),
+    ...secrets(repo, ignored, handover, optedIn, env),
+    ...carried(repo.top),
+  ]
+}
+
+// ---------- macOS-only work ----------
+
+export function macOSOnly(top, files, handover) {
+  const used = [...new Set(commands(handover).filter((c) => MAC_TOOLS.has(c)))].sort()
+  if (used.length) return [finding('macos-only', 'block', `the hand-over's Commands run ${used.join(', ')}, which the box (Linux) lacks`)]
+  const markers = new Set()
+  for (const file of files) {
+    const parts = file.split('/')
+    const bundle = parts.find((p) => p.endsWith('.xcodeproj') || p.endsWith('.xcworkspace'))
+    if (bundle) markers.add(bundle)
+    if (parts[parts.length - 1] === 'Podfile') markers.add(file)
+    if (parts[0] === 'fastlane' && parts.length > 1) markers.add('fastlane/')
+  }
+  try {
+    if (appleOnly(fs.readFileSync(path.join(top, 'Package.swift'), 'utf8'))) markers.add('Package.swift')
+  } catch {
+    // no manifest
+  }
+  if (!markers.size) return []
+  return [finding('macos-only', 'warn', `the repo has an Apple target (${[...markers].sort().slice(0, 4).join(', ')}); the box cannot build or run it`)]
+}
+
+/** commands lists the programs the hand-over's Commands section runs, from its code spans. */
+export function commands(handover) {
+  const spans = section(handover, '## Commands').join('\n').split('`')
+  const out = []
+  spans.forEach((span, i) => {
+    if (i % 2 === 0) return
+    for (const part of span.split(/[;|&\n]/)) {
+      const word = part.split(' ').filter(Boolean).find((w) => !w.includes('=') && !['sudo', 'env', 'time', 'exec', '$'].includes(w))
+      if (word) out.push(path.posix.basename(word))
+    }
+  })
+  return out
+}
+
+export function appleOnly(manifest) {
+  const start = manifest.indexOf('platforms:')
+  if (start < 0) return false
+  const open = manifest.indexOf('[', start)
+  const close = open < 0 ? -1 : manifest.indexOf(']', open)
+  if (open < 0 || close < 0) return false
+  const list = manifest.slice(open, close + 1)
+  const names = [...list.matchAll(/\.([A-Za-z]+)\(/g), ...list.matchAll(/\.([A-Za-z]+)\s*[,\]]/g)].map((m) => m[1])
+  return names.length > 0 && names.every((n) => APPLE_PLATFORMS.has(n))
+}
+
+// ---------- local services and hosts ----------
+
+/** configTexts is the repo's .env* files, compose files and top-level config, which name services and hosts. */
+export function configTexts(top) {
+  let names = []
+  try {
+    names = fs.readdirSync(top)
+  } catch {
+    return []
+  }
+  names = names.filter((name) => {
+    const lower = name.toLowerCase()
+    return (
+      lower.startsWith('.env') || lower.startsWith('docker-compose') || lower.startsWith('compose.') ||
+      ['.toml', '.yaml', '.yml', '.json', '.ini', '.conf', '.properties'].some((s) => lower.endsWith(s))
+    )
+  })
+  try {
+    names.push(...fs.readdirSync(path.join(top, 'config')).map((n) => 'config/' + n))
+  } catch {
+    // no config/
+  }
+  const out = []
+  for (const name of names.sort()) {
+    try {
+      const st = fs.statSync(path.join(top, name))
+      if (!st.isFile() || st.size > 256 << 10) continue
+      out.push({ name, text: fs.readFileSync(path.join(top, name), 'utf8') })
+    } catch {
+      // unreadable
+    }
+  }
+  return out
+}
+
+export function services(texts, top, env) {
+  const findings = []
+  const lsof = runSync(['lsof', '-nP', '-iTCP', '-sTCP:LISTEN', '-F', 'cn'], { env, timeoutMs: 5000 })
+  if (lsof.status === 0) {
+    const listening = new Map()
+    let command = ''
+    for (const line of lsof.text.split('\n')) {
+      if (line.startsWith('c')) command = line.slice(1)
+      if (line.startsWith('n')) {
+        const port = Number(line.split(':').pop())
+        if (Number.isInteger(port)) listening.set(port, command)
+      }
+    }
+    for (const [port, cmd] of [...listening].sort((a, b) => a[0] - b[0])) {
+      const file = texts.find((t) => namesPort(port, t.text))?.name
+      if (file) findings.push(finding('services', 'warn', `${cmd} listens on port ${port} on this computer, and ${file} names it; the box cannot reach it`))
+    }
+  }
+  const compose = runSync(['docker', 'compose', 'ls', '--format', 'json'], { env, timeoutMs: 5000 })
+  if (compose.status === 0) {
+    try {
+      for (const project of JSON.parse(compose.text)) {
+        if (String(project.ConfigFiles || '').includes(top + '/')) {
+          findings.push(finding('services', 'warn', `the docker compose project ${project.Name || ''} of this repo runs on this computer; the box has no container runtime`))
+        }
+      }
+    } catch {
+      // not JSON
+    }
+  }
+  return findings
+}
+
+export function namesPort(port, text) {
+  const p = String(port)
+  return [
+    new RegExp(`(localhost|127\\.0\\.0\\.1|0\\.0\\.0\\.0|\\[::1\\]):${p}\\b`),
+    new RegExp(`port"?\\s*[:=]\\s*["']?${p}\\b`, 'i'),
+    new RegExp(`["' -]${p}:[0-9]+`),
+  ].some((re) => re.test(text))
+}
+
+export async function vpnHosts(repo, texts, env, { resolve = resolveHost } = {}) {
+  const hosts = []
+  const remotes = repo.run(['remote', '-v']).text
+  for (const line of remotes.split('\n')) {
+    const url = (line.split('\t')[1] || '').split(' ')[0]
+    if (!url) continue
+    try {
+      const u = new URL(url)
+      if (u.hostname) {
+        hosts.push(u.hostname)
+        continue
+      }
+    } catch {
+      // scp-like host:path
+    }
+    const at = url.split(':')[0]
+    hosts.push(at.split('@').pop())
+  }
+  for (const { text } of texts) for (const m of text.matchAll(/[a-z][a-z0-9+.-]*:\/\/(?:[^@/\s"']+@)?([A-Za-z0-9.-]+)/g)) hosts.push(m[1])
+  const split = splitDomains(env)
+  const findings = []
+  const seen = new Set()
+  for (const host of hosts.map((h) => h.toLowerCase())) {
+    if (seen.has(host) || seen.size >= 20) continue
+    seen.add(host)
+    if (host === 'localhost' || host.startsWith('127.') || !host.includes('.')) continue
+    const domain = split.find((d) => host === d || host.endsWith('.' + d))
+    if (domain) {
+      findings.push(finding('vpn-hosts', 'warn', `${host} resolves through this computer's split DNS for ${domain} (a VPN); the box cannot reach it`))
+      continue
+    }
+    const addresses = await resolve(host)
+    if (addresses?.length && addresses.every(isPrivate)) {
+      findings.push(finding('vpn-hosts', 'warn', `${host} resolves to a private address (${addresses[0]}); the box cannot reach it`))
+    }
+  }
+  return findings
+}
+
+/** splitDomains is the domains of macOS's supplemental resolvers, as `scutil --dns` lists them; none elsewhere. */
+export function splitDomains(env) {
+  const r = runSync(['scutil', '--dns'], { env, timeoutMs: 5000 })
+  if (r.status !== 0) return []
+  return r.text
+    .split('\n')
+    .map((line) => {
+      const i = line.indexOf(':')
+      if (i < 0) return null
+      const [k, v] = [line.slice(0, i).trim(), line.slice(i + 1).trim()]
+      return k === 'domain' && !v.endsWith('.arpa') && v !== 'local' ? v.toLowerCase() : null
+    })
+    .filter(Boolean)
+}
+
+function resolveHost(host) {
+  return Promise.race([
+    dns.promises.lookup(host, { all: true }).then((a) => a.map((x) => x.address), () => null),
+    new Promise((r) => setTimeout(() => r(null), 2000).unref()),
+  ])
+}
+
+export function isPrivate(address) {
+  const lower = address.toLowerCase()
+  if (lower.includes(':')) return lower.startsWith('fc') || lower.startsWith('fd') || lower.startsWith('fe80')
+  const o = address.split('.').map(Number)
+  if (o.length !== 4 || o.some((x) => !Number.isInteger(x))) return false
+  return o[0] === 10 || (o[0] === 172 && o[1] >= 16 && o[1] <= 31) || (o[0] === 192 && o[1] === 168) || (o[0] === 100 && o[1] >= 64 && o[1] <= 127)
+}
+
+// ---------- secrets, LFS and submodules ----------
+
+export function secrets(repo, ignored, handover, optedIn, env) {
+  const findings = []
+  for (const p of ignored) {
+    if (!p.endsWith('/') && path.posix.basename(p).startsWith('.env') && !optedIn.includes('file:' + p)) {
+      findings.push(finding('secrets', 'warn', `${p} is git-ignored and stays on this computer; if the box needs it, opt it in: npx @simular-ai/box offload secrets add file:${p}`))
+    }
+  }
+  const line = section(handover, '## Environment facts').find((l) => l.includes('Secrets needed:'))
+  const needed = line ? line.split('Secrets needed:').pop().trim() : ''
+  if (needed && !needed.toLowerCase().startsWith('none') && !optedIn.length) {
+    findings.push(finding('secrets', 'warn', `the hand-over needs secrets (${needed}) and none are opted in for this repo`))
+  }
+  const pattern = `(os\\.Getenv\\(|process\\.env\\.|process\\.env\\[|env::var\\(|os\\.environ\\.get\\(|os\\.environ\\[|os\\.getenv\\()["']?[A-Z][A-Z0-9_]+`
+  const grep = repo.run(['grep', '-h', '-o', '-I', '-E', pattern]).text
+  const provided = new Set()
+  for (const entry of optedIn.filter((e) => e.startsWith('file:'))) {
+    let text = ''
+    try {
+      text = fs.readFileSync(path.join(repo.top, entry.slice(5)), 'utf8')
+    } catch {
+      // missing; offload reports it
+    }
+    for (const l of text.split('\n')) {
+      const name = l.split('=')[0].replace('export ', '').trim()
+      if (name) provided.add(name)
+    }
+  }
+  const read = new Set(grep.split('\n').map((m) => m.split(/[(.["']/).filter(Boolean).pop()).filter(Boolean))
+  const unset = [...read].filter((n) => env[n] !== undefined && !COMMON_NAMES.has(n) && !provided.has(n)).sort()
+  if (unset.length) findings.push(finding('secrets', 'warn', `the code reads ${unset.slice(0, 10).join(', ')}, set on this computer and unset in the box`))
+  return findings
+}
+
+export function carried(top) {
+  const findings = []
+  try {
+    if (fs.readFileSync(path.join(top, '.gitattributes'), 'utf8').includes('filter=lfs')) {
+      findings.push(finding('lfs', 'warn', 'Git LFS files are not carried; the box copy holds their pointers'))
+    }
+  } catch {
+    // none
+  }
+  if (fs.existsSync(path.join(top, '.gitmodules'))) findings.push(finding('submodules', 'warn', 'submodule contents are not carried; the box copy holds only their commits'))
+  return findings
+}
+
+export function sizeFinding(bytes) {
+  if (bytes <= SIZE_LIMIT) return null
+  return finding('size', 'confirm', `about ${(bytes / 1e6).toFixed(0)} MB to send to the box`)
+}
diff --git a/cli/src/offload/run.js b/cli/src/offload/run.js
new file mode 100644
index 0000000..e04103e
--- /dev/null
+++ b/cli/src/offload/run.js
@@ -0,0 +1,47 @@
+import { spawn, spawnSync } from 'node:child_process'
+
+/** runSync runs argv on env's PATH with input, collecting stdout and stderr as Buffers. */
+export function runSync(argv, { cwd, env = process.env, input, timeoutMs } = {}) {
+  const res = spawnSync(argv[0], argv.slice(1), { cwd, env, input, timeout: timeoutMs, maxBuffer: 1 << 30 })
+  return {
+    status: res.error ? 127 : (res.status ?? 1),
+    out: res.stdout || Buffer.alloc(0),
+    err: res.stderr || Buffer.from(res.error ? String(res.error.message) : ''),
+    get text() {
+      return this.out.toString('utf8').trim()
+    },
+    get error() {
+      return this.err.toString('utf8').trim()
+    },
+  }
+}
+
+/** run is runSync without blocking the event loop, for commands that call back into this CLI (rsync and git over rsh). */
+export function run(argv, { cwd, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(argv[0], argv.slice(1), { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] })
+    const out = []
+    const err = []
+    child.stdout.on('data', (d) => out.push(d))
+    child.stderr.on('data', (d) => err.push(d))
+    child.on('error', (e) => err.push(Buffer.from(e.message)))
+    child.on('close', (code) =>
+      resolve({
+        status: code ?? 1,
+        out: Buffer.concat(out),
+        err: Buffer.concat(err),
+        get text() {
+          return this.out.toString('utf8').trim()
+        },
+        get error() {
+          return this.err.toString('utf8').trim()
+        },
+      }),
+    )
+  })
+}
+
+/** quote makes word one shell word for the box's bash -lc. */
+export function quote(word) {
+  return /^[A-Za-z0-9\-_./=:]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`
+}
diff --git a/cli/src/offload/store.js b/cli/src/offload/store.js
new file mode 100644
index 0000000..c9778d5
--- /dev/null
+++ b/cli/src/offload/store.js
@@ -0,0 +1,99 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+// OffloadStore keeps this computer's side of offloads under <boxHome>/offload (0700): per repo key handover.md, env.json,
+// back.md and offload.json while an offload is in flight; repos.json (0600) keeps opted-in secret entries (names and paths
+// only, never a value) and whether the user said yes to the size confirm. Ported from upstream OffloadStore.
+export class OffloadStore {
+  constructor(boxHome) {
+    this.root = path.join(boxHome, 'offload')
+  }
+
+  directory(key) {
+    const dir = path.join(this.root, key)
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    fs.chmodSync(path.dirname(this.root), 0o700)
+    fs.chmodSync(this.root, 0o700)
+    fs.chmodSync(dir, 0o700)
+    return dir
+  }
+
+  handover(key) {
+    return path.join(this.directory(key), 'handover.md')
+  }
+
+  back(key) {
+    return path.join(this.directory(key), 'back.md')
+  }
+
+  record(key) {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(this.root, key, 'offload.json'), 'utf8'))
+    } catch {
+      return null
+    }
+  }
+
+  save(record) {
+    writeAtomic(path.join(this.directory(record.repo), 'offload.json'), JSON.stringify(record, null, 2) + '\n', 0o600)
+  }
+
+  remove(key) {
+    fs.rmSync(path.join(this.root, key, 'offload.json'), { force: true })
+  }
+
+  /** records lists every offload in flight, oldest first. */
+  records() {
+    let keys = []
+    try {
+      keys = fs.readdirSync(this.root)
+    } catch {
+      return []
+    }
+    return keys
+      .map((k) => this.record(k))
+      .filter(Boolean)
+      .sort((a, b) => a.started_at_ms - b.started_at_ms)
+  }
+
+  secrets(key) {
+    return this.#repos()[key]?.secrets || []
+  }
+
+  setSecrets(key, entries) {
+    this.#update(key, (s) => (s.secrets = entries))
+  }
+
+  sizeConfirmed(key) {
+    return Boolean(this.#repos()[key]?.size_confirmed)
+  }
+
+  confirmSize(key) {
+    this.#update(key, (s) => (s.size_confirmed = true))
+  }
+
+  #update(key, change) {
+    const all = this.#repos()
+    const settings = all[key] || { secrets: [], size_confirmed: false }
+    change(settings)
+    if (!settings.secrets.length && !settings.size_confirmed) delete all[key]
+    else all[key] = settings
+    fs.mkdirSync(this.root, { recursive: true, mode: 0o700 })
+    writeAtomic(path.join(this.root, 'repos.json'), JSON.stringify(all, null, 2) + '\n', 0o600)
+  }
+
+  #repos() {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(this.root, 'repos.json'), 'utf8')) || {}
+    } catch {
+      return {}
+    }
+  }
+}
+
+function writeAtomic(file, text, mode) {
+  const tmp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, text, { mode })
+  fs.chmodSync(tmp, mode)
+  fs.renameSync(tmp, file)
+}
diff --git a/cli/src/offload/tar.js b/cli/src/offload/tar.js
new file mode 100644
index 0000000..f678212
--- /dev/null
+++ b/cli/src/offload/tar.js
@@ -0,0 +1,50 @@
+import fs from 'node:fs'
+
+// The send stream is a ustar archive of regular files, with a pax header for a path over 100 bytes (contracts.md "Send
+// stream"). tarParts returns Exec stdin parts: Buffers and {file} parts that frames() reads lazily, so a large bundle is
+// never held in memory. Ported from upstream ExecFrames.tar.
+
+export function tarParts(members, { now = Math.floor(Date.now() / 1000) } = {}) {
+  const parts = []
+  for (const [name, part] of members) {
+    const size = Buffer.isBuffer(part) ? part.length : fs.statSync(part.file).size
+    if (Buffer.byteLength(name) > 100) {
+      let length = 0
+      let record = ''
+      do {
+        length = Buffer.byteLength(record)
+        record = `${length} path=${name}\n`
+      } while (Buffer.byteLength(record) !== length)
+      parts.push(Buffer.concat([header('PaxHeader', length, 'x', now), pad(Buffer.from(record))]))
+    }
+    parts.push(header(Buffer.from(name).subarray(0, 100).toString('utf8'), size, '0', now))
+    parts.push(part)
+    parts.push(Buffer.alloc((512 - (size % 512)) % 512))
+  }
+  parts.push(Buffer.alloc(1024))
+  return parts
+}
+
+function pad(buf) {
+  return Buffer.concat([buf, Buffer.alloc((512 - (buf.length % 512)) % 512)])
+}
+
+export function header(name, size, type, now) {
+  const block = Buffer.alloc(512)
+  const put = (text, offset) => Buffer.from(text).copy(block, offset)
+  const octal = (value, offset, width) => put(value.toString(8).padStart(width - 1, '0'), offset)
+  put(name, 0)
+  octal(0o600, 100, 8)
+  octal(0, 108, 8)
+  octal(0, 116, 8)
+  octal(size, 124, 12)
+  octal(now, 136, 12)
+  put('        ', 148)
+  put(type, 156)
+  put('ustar\u000000', 257)
+  let sum = 0
+  for (const b of block) sum += b
+  octal(sum, 148, 7)
+  block[155] = 0x20
+  return block
+}
diff --git a/cli/test/fakebox/bin/cocoonbox-agent b/cli/test/fakebox/bin/cocoonbox-agent
new file mode 100755
index 0000000..410592e
--- /dev/null
+++ b/cli/test/fakebox/bin/cocoonbox-agent
@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// A fake box packer for tests: the `cocoonbox-agent offload` verbs as contracts.md "Offload" states them, with the box
+// copy under $FAKE_BOX_WORKSPACE and the inbox and outbox as files under $FAKE_BOX_STATE. It does what the CLI depends
+// on (begin's refs, send's tar stream with the bundle indexed by `git index-pack --fix-thin`, read, end) and no CLI
+// session: a test plays the box agent by committing in the copy and posting `back` with FAKE_POST.
+import { execFileSync, spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const [verb, ...args] = process.argv.slice(3)
+const opt = (name) => {
+  const i = args.indexOf(name)
+  return i < 0 ? undefined : args[i + 1]
+}
+const has = (name) => args.includes(name)
+const state = process.env.FAKE_BOX_STATE
+const reply = (obj, code = 0) => {
+  process.stdout.write(JSON.stringify(obj) + '\n')
+  process.exit(code)
+}
+const repo = opt('--repo')
+const file = (name) => path.join(state, `${repo}.${name}.json`)
+const load = (name, fallback) => {
+  try {
+    return JSON.parse(fs.readFileSync(file(name), 'utf8'))
+  } catch {
+    return fallback
+  }
+}
+const save = (name, v) => fs.writeFileSync(file(name), JSON.stringify(v))
+
+function stdin() {
+  return fs.readFileSync(0)
+}
+
+function untar(buf) {
+  const members = {}
+  let off = 0
+  let longName = null
+  while (off + 512 <= buf.length) {
+    const h = buf.subarray(off, off + 512)
+    if (h.every((b) => b === 0)) break
+    const name = h.subarray(0, 100).toString('utf8').replace(/\0.*$/s, '')
+    const size = parseInt(h.subarray(124, 136).toString('utf8').replace(/\0.*$/s, '').trim(), 8)
+    const type = String.fromCharCode(h[156])
+    const body = buf.subarray(off + 512, off + 512 + size)
+    off += 512 + Math.ceil(size / 512) * 512
+    if (type === 'x') {
+      longName = /path=(.*)\n/.exec(body.toString('utf8'))[1]
+      continue
+    }
+    members[longName || name] = Buffer.from(body)
+    longName = null
+  }
+  return members
+}
+
+switch (verb) {
+  case 'begin': {
+    if (process.env.FAKE_BEGIN_BLOCK) {
+      reply({ ok: false, code: 'refused', error: 'the box CLI is signed out', findings: [{ check: 'cli', outcome: 'block', detail: 'claude is signed out' }], cli: {} }, 3)
+    }
+    const dir = path.join(process.env.FAKE_BOX_WORKSPACE, opt('--name'))
+    fs.mkdirSync(dir, { recursive: true })
+    let refs = {}
+    if (fs.existsSync(path.join(dir, '.git', 'objects'))) {
+      const out = spawnSync('git', ['-C', dir, 'for-each-ref', '--format=%(refname) %(objectname)'], { encoding: 'utf8' }).stdout
+      for (const line of out.split('\n').filter(Boolean)) {
+        const [ref, oid] = line.split(' ')
+        refs[ref] = oid
+      }
+    }
+    save('session', { id: opt('--id'), dir, kind: opt('--kind') })
+    reply({ ok: true, dir, copy: Object.keys(refs).length ? 'mirror' : 'absent', refs, cli: { kind: opt('--kind'), version: '9.9.9', signed_in: true, account: 'test@example.com' }, ignored: [], findings: [] })
+    break
+  }
+  case 'send': {
+    const input = stdin()
+    if (has('--back') || has('--message')) {
+      const inbox = load('inbox', [])
+      inbox.push({ back: has('--back'), body: input.toString('utf8') })
+      save('inbox', inbox)
+      reply({ ok: true, seq: inbox.length, delivery: 'pasted' })
+    }
+    const session = load('session', null)
+    if (!session || session.id !== opt('--id')) reply({ ok: false, code: 'refused', error: 'another offload holds the copy' }, 3)
+    const members = untar(input)
+    fs.writeFileSync(path.join(state, `${repo}.handover.md`), members['handover.md'] || '')
+    fs.writeFileSync(path.join(state, `${repo}.env.json`), members['env.json'] || '')
+    const secrets = Object.keys(members).filter((n) => n.startsWith('secrets/'))
+    fs.writeFileSync(path.join(state, `${repo}.secrets.json`), JSON.stringify(secrets))
+    const dir = session.dir
+    fs.mkdirSync(path.join(dir, '.git', 'objects', 'pack'), { recursive: true })
+    fs.mkdirSync(path.join(dir, '.git', 'objects', 'info'), { recursive: true })
+    const bundle = members['offload.bundle']
+    if (bundle) {
+      // header lines up to a blank line, then the pack
+      const end = bundle.indexOf('\n\n')
+      const header = bundle.subarray(0, end).toString('utf8').split('\n').slice(1)
+      execFileSync('git', ['-C', dir, 'index-pack', '--stdin', '--fix-thin'], { input: bundle.subarray(end + 2), stdio: ['pipe', 'ignore', 'inherit'] })
+      for (const line of header) {
+        if (line.startsWith('-') || line.startsWith('@')) continue
+        const [oid, ref] = line.split(' ')
+        if (ref && ref.startsWith('refs/')) execFileSync('git', ['-C', dir, 'update-ref', ref, oid])
+      }
+    }
+    execFileSync('git', ['-C', dir, 'update-index', '-q', '--refresh'], { stdio: 'ignore' })
+    save('session', { ...session, started: true })
+    reply({ ok: true, delivery: 'started', accepted: true, tmux: `cb-off-${repo}-${opt('--kind')}`, timings_ms: {} })
+    break
+  }
+  case 'read': {
+    const since = Number(opt('--since') || 0)
+    const outbox = load('outbox', [])
+    reply({ ok: true, entries: outbox.filter((e) => e.seq > since), status: 'idle' })
+    break
+  }
+  case 'status':
+    reply({ ok: true, sessions: [] })
+    break
+  case 'end':
+    save('ended', true)
+    reply({ ok: true })
+    break
+  default:
+    reply({ ok: false, code: 'usage', error: `unknown verb ${verb}` }, 2)
+}
diff --git a/cli/test/fakebox/fake-box.js b/cli/test/fakebox/fake-box.js
new file mode 100644
index 0000000..eefcf5b
--- /dev/null
+++ b/cli/test/fakebox/fake-box.js
@@ -0,0 +1,93 @@
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import grpc from '@grpc/grpc-js'
+import { loadServices } from '../../src/box/connection.js'
+
+// FakeBox is a local stand-in for the relay and one box: Boxes.List/Ensure, and Session.Exec running `bash -c` in a
+// workspace directory with a fake `cocoonbox-agent` first on PATH. It checks the bearer token and the box header as the
+// edge does, so the CLI's real gRPC, rsh, rsync and git paths run against it.
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+export const TOKEN = 'cb_test_token'
+
+export async function startFakeBox({ workspace, state, box = { id: 'cb-test', name: 'main', state: 'BOX_STATE_RUNNING', image: 'sbxdesk:v7' }, env = {} }) {
+  const { Session, Boxes } = loadServices()
+  const server = new grpc.Server()
+  const calls = []
+  const authed = (call) => {
+    const auth = call.metadata.get('authorization')[0]
+    if (auth !== `Bearer ${TOKEN}`) return { code: grpc.status.UNAUTHENTICATED, details: auth ? 'invalid bearer token' : 'missing bearer token' }
+    return null
+  }
+  server.addService(Boxes.service, {
+    List(call, cb) {
+      const err = authed(call)
+      if (err) return cb(err)
+      calls.push('List')
+      cb(null, { boxes: [box] })
+    },
+    Ensure(call, cb) {
+      const err = authed(call)
+      if (err) return cb(err)
+      calls.push('Ensure')
+      box.state = 'BOX_STATE_RUNNING'
+      cb(null, { box })
+    },
+  })
+  server.addService(Session.service, {
+    Exec(call) {
+      const err = authed(call)
+      if (err) return call.destroy(Object.assign(new Error(err.details), err))
+      if (call.metadata.get('x-cocoonbox-box')[0] !== box.id) {
+        return call.destroy(Object.assign(new Error('no such box'), { code: grpc.status.NOT_FOUND }))
+      }
+      let child = null
+      call.on('data', (frame) => {
+        if (!child) {
+          if (frame.body !== 'start') return call.destroy(Object.assign(new Error('first frame must be start'), { code: grpc.status.INVALID_ARGUMENT }))
+          calls.push(frame.start.command)
+          child = spawn('bash', ['-c', frame.start.command], {
+            cwd: workspace,
+            detached: true,
+            env: { ...process.env, ...env, PATH: `${path.join(HERE, 'bin')}:${process.env.PATH}`, FAKE_BOX_STATE: state, FAKE_BOX_WORKSPACE: workspace },
+          })
+          child.stdin.on('error', () => {})
+          child.stdout.on('data', (d) => {
+            if (!call.write({ stdout: d })) {
+              child.stdout.pause()
+              call.once('drain', () => child.stdout.resume())
+            }
+          })
+          child.stderr.on('data', (d) => call.write({ stderr: d }))
+          child.on('close', (code, signal) => {
+            call.write({ exit_code: code ?? 128 + (signal === 'SIGINT' ? 2 : 15) })
+            call.end()
+          })
+          return
+        }
+        if (frame.body === 'stdin') child.stdin.write(frame.stdin)
+        else if (frame.body === 'eof') child.stdin.end()
+        else if (frame.body === 'signal') {
+          try {
+            process.kill(-child.pid, frame.signal === 'EXEC_SIGNAL_INT' ? 'SIGINT' : 'SIGTERM')
+          } catch {
+            // gone
+          }
+        }
+      })
+      call.on('end', () => child?.stdin.end())
+      call.on('cancelled', () => {
+        try {
+          process.kill(-child.pid, 'SIGKILL')
+        } catch {
+          // gone
+        }
+      })
+    },
+  })
+  const port = await new Promise((resolve, reject) =>
+    server.bindAsync('127.0.0.1:0', grpc.ServerCredentials.createInsecure(), (err, p) => (err ? reject(err) : resolve(p))),
+  )
+  return { endpoint: `http://127.0.0.1:${port}`, calls, box, stop: () => new Promise((r) => server.tryShutdown(r)) }
+}
diff --git a/cli/test/offload-e2e.test.js b/cli/test/offload-e2e.test.js
new file mode 100644
index 0000000..5cec366
--- /dev/null
+++ b/cli/test/offload-e2e.test.js
@@ -0,0 +1,217 @@
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn, execFileSync } from 'node:child_process'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { startFakeBox, TOKEN } from './fakebox/fake-box.js'
+import { HANDOVER_TEMPLATE } from '../src/offload/model.js'
+
+// Offload and back end to end against a fake box: the CLI's real gRPC Exec, rsh as rsync's and git's remote shell, the
+// tar stream with the bundle, and the merge at back. Needs bash, git and rsync (macOS and Linux CI have them).
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'simular-box.js')
+const skip = process.platform === 'win32' || !hasRsync() ? 'needs bash, git and rsync' : false
+
+function hasRsync() {
+  try {
+    execFileSync('rsync', ['--version'], { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+let tmp, box, env
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', env: { ...process.env, ...IDENT } }).trim()
+const IDENT = { GIT_AUTHOR_NAME: 't', GIT_AUTHOR_EMAIL: 't@x', GIT_COMMITTER_NAME: 't', GIT_COMMITTER_EMAIL: 't@x' }
+
+function cli(args, { cwd, input, extraEnv = {} } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [BIN, ...args], { cwd, env: { ...env, ...extraEnv } })
+    const out = []
+    const err = []
+    child.stdout.on('data', (d) => out.push(d))
+    child.stderr.on('data', (d) => err.push(d))
+    child.on('close', (code) => resolve({ code, stdout: Buffer.concat(out), text: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8') }))
+    if (input !== undefined) child.stdin.end(input)
+    else child.stdin.end()
+  })
+}
+
+function handover(goal) {
+  return HANDOVER_TEMPLATE.replace('<one-line goal>', goal)
+}
+
+/** playBoxAgent commits change in the copy, makes S' as the box packer's `post --back` does, and posts back. */
+function playBoxAgent({ dir, offload_id: id, repo: key }, change) {
+  for (const [file, text] of Object.entries(change)) fs.writeFileSync(path.join(dir, file), text)
+  git(dir, 'add', '-A')
+  git(dir, 'commit', '-qm', 'box work')
+  const tree = git(dir, 'rev-parse', 'HEAD^{tree}')
+  const snap = git(dir, 'commit-tree', tree, '-p', 'HEAD', '-m', 'back')
+  git(dir, 'update-ref', `refs/cocoonbox/back/${id}`, snap)
+  const outbox = path.join(tmp, 'state', `${key}.outbox.json`)
+  const entries = fs.existsSync(outbox) ? JSON.parse(fs.readFileSync(outbox, 'utf8')) : []
+  entries.push({ seq: entries.length + 1, kind: 'back', offload_id: id, cli: 'claude', time_ms: Date.now(), body: handover('done in the box') })
+  fs.writeFileSync(outbox, JSON.stringify(entries))
+}
+
+function makeRepo(name) {
+  const repo = path.join(tmp, name)
+  fs.mkdirSync(repo)
+  git(repo, 'init', '-q', '-b', 'main')
+  fs.writeFileSync(path.join(repo, 'a.txt'), 'one\n')
+  fs.writeFileSync(path.join(repo, 'b.txt'), 'bee\n')
+  fs.writeFileSync(path.join(repo, '.gitignore'), 'node_modules/\n.env\n')
+  git(repo, 'add', '-A')
+  git(repo, 'commit', '-qm', 'init')
+  return repo
+}
+
+before(async () => {
+  if (skip) return
+  tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'box-offload-e2e-')))
+  for (const d of ['workspace', 'state', 'home']) fs.mkdirSync(path.join(tmp, d))
+  box = await startFakeBox({ workspace: path.join(tmp, 'workspace'), state: path.join(tmp, 'state'), env: IDENT })
+  env = { PATH: process.env.PATH, HOME: path.join(tmp, 'home'), BOX_HOME: path.join(tmp, 'home', '.simular-box'), BOX_ENDPOINT: box.endpoint, BOX_TOKEN: TOKEN, ...IDENT }
+})
+
+after(async () => {
+  if (skip) return
+  await box.stop()
+  fs.rmSync(tmp, { recursive: true, force: true })
+})
+
+test('rsh passes bytes, exit codes and stderr, and drops rsync host words', { skip, timeout: 60000 }, async () => {
+  const data = crypto.randomBytes(300 << 10)
+  const cat = await cli(['rsh', '--box', 'main', 'box', 'cat'], { input: data })
+  assert.equal(cat.code, 0)
+  assert.ok(cat.stdout.equals(data), 'cat returns the bytes unchanged')
+  const exit = await cli(['rsh', 'main', 'echo out; echo err >&2; exit 42'])
+  assert.equal(exit.code, 42)
+  assert.equal(exit.text, 'out\n')
+  assert.match(exit.stderr, /err/)
+  const none = await cli(['rsh', '--box', 'main'])
+  assert.equal(none.code, 255)
+  // a closed local reader ends rsh quietly with 255 (no stack trace), and the box command is cancelled
+  const pipe = await new Promise((resolve) => {
+    const child = spawn('bash', ['-c', `"${process.execPath}" "${BIN}" rsh --box main 'yes | head -c 50000000' | head -c 10 >/dev/null; echo "rc=\${PIPESTATUS[0]}"`], { env })
+    let out = ''
+    let err = ''
+    child.stdout.on('data', (d) => (out += d))
+    child.stderr.on('data', (d) => (err += d))
+    child.on('close', () => resolve({ out, err }))
+  })
+  assert.match(pipe.out, /rc=255/)
+  assert.ok(!/\n\s+at /.test(pipe.err), pipe.err)
+  const bad = await cli(['rsh', '--box', 'main', 'true'], { extraEnv: { BOX_TOKEN: 'cb_wrong' } })
+  assert.equal(bad.code, 255)
+  assert.match(bad.stderr, /invalid bearer token/)
+  assert.ok(!bad.stderr.includes('cb_wrong'), 'the token is never printed')
+})
+
+test('offload warns, then moves the task; back fast-forwards the box commits', { skip, timeout: 60000 }, async () => {
+  const repo = makeRepo('proj')
+  fs.writeFileSync(path.join(repo, 'a.txt'), 'one\nuncommitted\n')
+  fs.writeFileSync(path.join(repo, 'new.txt'), 'untracked\n')
+  fs.writeFileSync(path.join(repo, '.env'), 'SECRET=1\n')
+  fs.mkdirSync(path.join(repo, 'node_modules'))
+  fs.writeFileSync(path.join(repo, 'node_modules', 'big.js'), 'x')
+
+  const where = (await cli(['offload', 'handover-path'], { cwd: repo })).text.trim()
+  assert.ok(where.startsWith(env.BOX_HOME))
+  fs.writeFileSync(where, handover('finish the thing'))
+
+  const warned = await cli(['offload', '--kind', 'claude', '--json'], { cwd: repo })
+  assert.equal(warned.code, 4, warned.stderr)
+  const w = JSON.parse(warned.text)
+  assert.equal(w.code, 'confirm')
+  assert.ok(w.findings.some((f) => f.check === 'secrets' && f.detail.includes('.env')))
+
+  const done = await cli(['offload', '--kind', 'claude', '--yes', '--json'], { cwd: repo })
+  assert.equal(done.code, 0, done.stderr + done.text)
+  const r = JSON.parse(done.text)
+  assert.equal(r.accepted, true)
+  const copy = r.dir
+  assert.equal(fs.readFileSync(path.join(copy, 'a.txt'), 'utf8'), 'one\nuncommitted\n')
+  assert.equal(fs.readFileSync(path.join(copy, 'new.txt'), 'utf8'), 'untracked\n')
+  assert.ok(!fs.existsSync(path.join(copy, '.env')), 'ignored files stay here')
+  assert.ok(!fs.existsSync(path.join(copy, 'node_modules')))
+  // the bundle carried history and S
+  assert.equal(git(copy, 'rev-parse', `refs/cocoonbox/offload/${r.offload_id}`), git(repo, 'rev-parse', `refs/cocoonbox/offload/${r.offload_id}`))
+  assert.equal(git(copy, 'rev-parse', 'HEAD'), git(repo, 'rev-parse', 'HEAD'))
+  assert.equal(fs.readFileSync(path.join(tmp, 'state', `${r.repo}.handover.md`), 'utf8'), handover('finish the thing'))
+  const envJson = JSON.parse(fs.readFileSync(path.join(tmp, 'state', `${r.repo}.env.json`), 'utf8'))
+  assert.equal(envJson.v, 1)
+
+  // the record is 0600 in a 0700 directory
+  const rec = path.join(env.BOX_HOME, 'offload', r.repo, 'offload.json')
+  assert.equal(fs.statSync(rec).mode & 0o777, 0o600)
+  assert.equal(fs.statSync(path.dirname(rec)).mode & 0o777, 0o700)
+
+  playBoxAgent(r, { 'a.txt': 'one\nuncommitted\nfrom the box\n' })
+  const back = await cli(['back', '--json'], { cwd: repo })
+  assert.equal(back.code, 0, back.stderr + back.text)
+  const b = JSON.parse(back.text)
+  assert.match(b.landing, /^fast-forward: this branch now points at the box's commit [0-9a-f]{7}$/)
+  assert.equal(fs.readFileSync(path.join(repo, 'a.txt'), 'utf8'), 'one\nuncommitted\nfrom the box\n')
+  assert.equal(git(repo, 'log', '-1', '--format=%s'), 'box work')
+  assert.equal(git(repo, 'status', '--porcelain'), '')
+  assert.equal(fs.readFileSync(path.join(repo, '.env'), 'utf8'), 'SECRET=1\n')
+  assert.ok(!fs.existsSync(rec), 'back removes the record')
+  // the three offload Execs, rsync and git over rsh, and the back verbs all went through Session.Exec
+  assert.ok(box.calls.some((c) => c.startsWith('cocoonbox-agent offload begin')))
+  assert.ok(box.calls.some((c) => /^rsync --server/.test(c)), box.calls.join('\n'))
+  assert.ok(box.calls.some((c) => /^git-upload-pack /.test(c)), box.calls.join('\n'))
+  assert.ok(box.calls.some((c) => c.startsWith('cocoonbox-agent offload end')))
+  const again = await cli(['back'], { cwd: repo })
+  assert.equal(again.code, 1)
+  assert.match(again.stderr, /back\.md/)
+})
+
+test('back applies a clean merge uncommitted when the user worked meanwhile, else a branch', { skip, timeout: 60000 }, async () => {
+  const repo = makeRepo('proj2')
+  const where = (await cli(['offload', 'handover-path'], { cwd: repo })).text.trim()
+  fs.writeFileSync(where, handover('second'))
+  const done = await cli(['offload', '--kind', 'claude', '--yes', '--json'], { cwd: repo })
+  assert.equal(done.code, 0, done.stderr)
+  const r = JSON.parse(done.text)
+  fs.writeFileSync(path.join(repo, 'b.txt'), 'bee\nlocal edit\n')
+  playBoxAgent(r, { 'a.txt': 'one\nbox edit\n' })
+  const back = JSON.parse((await cli(['back', '--json'], { cwd: repo })).text)
+  assert.match(back.landing, /^merged: this branch now points at the box's commit [0-9a-f]{7}; the changes you made meanwhile are kept; uncommitted: b\.txt$/)
+  assert.equal(git(repo, 'log', '-1', '--format=%s'), 'box work', 'HEAD moved to the box commit')
+  assert.equal(fs.readFileSync(path.join(repo, 'a.txt'), 'utf8'), 'one\nbox edit\n')
+  assert.equal(fs.readFileSync(path.join(repo, 'b.txt'), 'utf8'), 'bee\nlocal edit\n')
+
+  // a conflict: the box changes the file the user also changed
+  fs.writeFileSync(where, handover('third'))
+  git(repo, 'add', '-A')
+  git(repo, 'commit', '-qm', 'local')
+  const third = JSON.parse((await cli(['offload', '--kind', 'claude', '--yes', '--json'], { cwd: repo })).text)
+  fs.writeFileSync(path.join(repo, 'a.txt'), 'mine\n')
+  playBoxAgent(third, { 'a.txt': 'theirs\n' })
+  const conflict = JSON.parse((await cli(['back', '--json'], { cwd: repo })).text)
+  assert.match(conflict.landing, /^conflict: the box's work is on the branch cocoonbox\/back-/)
+  assert.equal(fs.readFileSync(path.join(repo, 'a.txt'), 'utf8'), 'mine\n', 'the work tree is untouched')
+})
+
+test('a box-side block exits 3 and names the box CLI commands', { skip, timeout: 60000 }, async () => {
+  const repo = makeRepo('proj3')
+  fs.writeFileSync((await cli(['offload', 'handover-path'], { cwd: repo })).text.trim(), handover('blocked'))
+  // the block comes from begin; run the fake agent with FAKE_BEGIN_BLOCK through a box restarted with it
+  const blocked = await startFakeBox({ workspace: path.join(tmp, 'workspace'), state: path.join(tmp, 'state'), env: { ...IDENT, FAKE_BEGIN_BLOCK: '1' } })
+  try {
+    const res = await cli(['offload', '--kind', 'claude'], { cwd: repo, extraEnv: { BOX_ENDPOINT: blocked.endpoint } })
+    assert.equal(res.code, 3, res.stderr)
+    assert.match(res.text, /block\s+cli: claude is signed out/)
+    assert.match(res.text, /offload sign-in --kind claude/)
+  } finally {
+    await blocked.stop()
+  }
+  const bad = await cli(['offload', '--kind', 'claude', '--handover', path.join(tmp, 'nope.md')], { cwd: repo })
+  assert.equal(bad.code, 1)
+})
diff --git a/cli/test/offload-unit.test.js b/cli/test/offload-unit.test.js
new file mode 100644
index 0000000..602b305
--- /dev/null
+++ b/cli/test/offload-unit.test.js
@@ -0,0 +1,363 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import http from 'node:http'
+import os from 'node:os'
+import path from 'node:path'
+import { parseArgs } from '../src/args.js'
+import { endpointUrl } from '../src/box/endpoint.js'
+import { authorizeUrl, browserLogin, challenge, deviceName } from '../src/box/login.js'
+import { parseRsh, pickBox } from '../src/box/rsh.js'
+import { TokenStore } from '../src/box/token-store.js'
+import { HANDOVER_TEMPLATE, copyName, findSignInLink, handoverProblems, loginCommand, repoKey } from '../src/offload/model.js'
+import { appleOnly, commands, imageFinding, isPrivate, macOSOnly, namesPort } from '../src/offload/preflight.js'
+import { parseVersion } from '../src/offload/env-probe.js'
+import { escape } from '../src/offload/offloader.js'
+import { tarParts } from '../src/offload/tar.js'
+
+const tmpdir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'box-unit-'))
+
+test('hand-over template: the template itself passes; missing, repeated and title problems are listed', () => {
+  const good = HANDOVER_TEMPLATE.replace('<one-line goal>', 'x')
+  assert.deepEqual(handoverProblems(good), [])
+  const missing = good.replace('## Gotchas learned\n', '')
+  assert.deepEqual(handoverProblems(missing), ['missing "## Gotchas learned"'])
+  assert.deepEqual(handoverProblems('x\n' + good), ['the first line does not start with "# Hand-over: "'])
+  assert.match(handoverProblems(good + '\n## Commands\n').join(), /appears 2 times/)
+  assert.match(handoverProblems(good + 'x'.repeat(256 << 10)).join(), /larger than 256 KiB/)
+})
+
+test('names: repo key, copy name', () => {
+  assert.equal(repoKey('/a/b', 'abc'), repoKey('/a/b', 'abc'))
+  assert.equal(repoKey('/a/b', '').length, 12)
+  assert.notEqual(repoKey('/a/b', 'x'), repoKey('/a/c', 'x'))
+  assert.equal(copyName('/x/my repo!'), 'my-repo-')
+  assert.equal(copyName('/x/..hidden'), 'hidden')
+  assert.equal(copyName('/x/' + 'a'.repeat(80)).length, 64)
+  assert.equal(copyName('/x/日本'), '--')
+})
+
+test('sign-in link: only https on the vendor hosts, OSC 8 targets first, escapes stripped', () => {
+  const osc = '\x1b]8;;https://claude.ai/oauth/authorize?code=1\x07click\x1b]8;;\x07'
+  assert.equal(findSignInLink(`Visit ${osc}`, 'claude'), 'https://claude.ai/oauth/authorize?code=1')
+  assert.equal(findSignInLink('go to \x1b[1mhttps://auth.openai.com/codex/device\x1b[0m.', 'codex'), 'https://auth.openai.com/codex/device')
+  assert.equal(findSignInLink('https://evil.example/claude.ai http://claude.ai/x https://claude.ai.evil.com/', 'claude'), null)
+  assert.equal(findSignInLink('https://user:pw@claude.ai/', 'claude'), null)
+  assert.equal(findSignInLink('https://console.anthropic.com/oauth', 'claude'), 'https://console.anthropic.com/oauth')
+  assert.equal(findSignInLink('https://claude.ai/x', 'codex'), null)
+  assert.equal(loginCommand('claude'), 'BROWSER=true NO_OPEN_BROWSER=1 claude auth login')
+})
+
+test('tar stream: a ustar archive with a pax path that system tar reads', () => {
+  const dir = tmpdir()
+  const big = path.join(dir, 'big.bin')
+  fs.writeFileSync(big, Buffer.alloc(70000, 7))
+  const long = 'secrets/file/' + 'd/'.repeat(60) + 'x.env'
+  const parts = tarParts([['handover.md', Buffer.from('hi\n')], ['offload.bundle', { file: big }], [long, Buffer.from('S=1\n')]])
+  const buf = Buffer.concat(parts.map((p) => (Buffer.isBuffer(p) ? p : fs.readFileSync(p.file))))
+  assert.equal(buf.length % 512, 0)
+  const tarFile = path.join(dir, 'x.tar')
+  fs.writeFileSync(tarFile, buf)
+  const out = path.join(dir, 'out')
+  fs.mkdirSync(out)
+  execFileSync('tar', ['-xf', tarFile, '-C', out])
+  assert.equal(fs.readFileSync(path.join(out, 'handover.md'), 'utf8'), 'hi\n')
+  assert.equal(fs.statSync(path.join(out, 'offload.bundle')).size, 70000)
+  assert.equal(fs.readFileSync(path.join(out, long), 'utf8'), 'S=1\n')
+})
+
+test('token store: 0600 file in a 0700 dir; BOX_TOKEN wins and is never written', () => {
+  const dir = path.join(tmpdir(), '.simular-box')
+  const store = new TokenStore(dir, {})
+  assert.equal(store.get('https://e'), null)
+  store.set('https://e', 'cb_x', 'browser')
+  if (process.platform !== 'win32') {
+    // Windows has no POSIX modes; the file sits in the user's profile
+    assert.equal(fs.statSync(store.file).mode & 0o777, 0o600)
+    assert.equal(fs.statSync(dir).mode & 0o777, 0o700)
+  }
+  assert.deepEqual(store.get('https://e'), { token: 'cb_x', source: 'browser' })
+  const env = new TokenStore(dir, { BOX_TOKEN: 'cb_env' })
+  assert.deepEqual(env.get('https://e'), { token: 'cb_env', source: 'env' })
+  assert.deepEqual(env.saved('https://e'), { token: 'cb_x', source: 'browser' })
+  assert.ok(!fs.readFileSync(store.file, 'utf8').includes('cb_env'))
+  assert.equal(store.remove('https://e'), true)
+  assert.equal(store.get('https://e'), null)
+})
+
+test('endpoint: BOX_ENDPOINT, else the origin of BOX_MCP_URL, else prod; https only off localhost', () => {
+  assert.equal(endpointUrl({}), 'https://mcp.box.simular.ai')
+  assert.equal(endpointUrl({ BOX_MCP_URL: 'https://staging.relay.simular.cloud/mcp' }), 'https://staging.relay.simular.cloud')
+  assert.equal(endpointUrl({ BOX_ENDPOINT: 'http://127.0.0.1:9' }), 'http://127.0.0.1:9')
+  assert.throws(() => endpointUrl({ BOX_ENDPOINT: 'http://relay.example' }), /https/)
+})
+
+test('args: offload flags; a token is never an argument except --token -', () => {
+  const a = parseArgs(['offload', 'send', '--interrupt', 'hello', 'there', '--box', 'main'])
+  assert.deepEqual(a.rest, ['send', 'hello', 'there'])
+  assert.equal(a.flags.box, 'main')
+  assert.equal(a.flags.interrupt, true)
+  assert.equal(parseArgs(['login', '--token', '-']).flags.token, '-')
+  assert.throws(() => parseArgs(['login', '--token', 'cb_secret']), /never as an argument/)
+  assert.throws(() => parseArgs(['login', '--token=cb_secret']), /never as an argument/)
+})
+
+test('rsh: options, host words and box choice', () => {
+  assert.deepEqual(parseRsh(['--box', 'main', '-t', 'box', 'ls', '-la']), { options: { box: 'main', tty: true }, words: ['box', 'ls', '-la'] })
+  assert.deepEqual(parseRsh(['-l', 'user', 'main', '--', 'x']).words, ['main', '--', 'x'])
+  assert.throws(() => parseRsh(['-x']), /unknown option/)
+  const boxes = [{ id: 'cb-1', name: 'main' }, { id: 'cb-2', name: 'other' }]
+  assert.equal(pickBox(boxes, 'cb-1', ['box', 'rsync', '--server']).command, 'rsync --server')
+  assert.equal(pickBox(boxes, 'main', ['u@other', 'ls']).command, 'ls')
+  assert.equal(pickBox(boxes, 'main', ['ls']).command, 'ls')
+  assert.equal(pickBox(boxes, null, ['other', 'git-upload-pack', "'/w/r'"]).box.id, 'cb-2')
+  assert.throws(() => pickBox(boxes, null, ['nobox', 'ls']), /name the box/)
+  assert.throws(() => pickBox(boxes, 'zzz', ['ls']), /no box named/)
+})
+
+test('preflight pieces', () => {
+  assert.equal(imageFinding('sbxdesk:v7'), null)
+  assert.equal(imageFinding('cbdesk:v22'), null)
+  assert.equal(imageFinding('cbdesk:v21').outcome, 'block')
+  const h = HANDOVER_TEMPLATE.replace('- Build: `<command>`', '- Build: `xcodebuild -scheme X && sudo /usr/bin/open .`')
+  assert.deepEqual(commands(h).filter((c) => c === 'xcodebuild' || c === 'open'), ['xcodebuild', 'open'])
+  assert.equal(macOSOnly('/nonexistent', [], h)[0].outcome, 'block')
+  assert.equal(macOSOnly('/nonexistent', ['App.xcodeproj/project.pbxproj'], HANDOVER_TEMPLATE)[0].outcome, 'warn')
+  assert.equal(appleOnly('platforms: [.macOS(.v14), .iOS(.v17)]'), true)
+  assert.equal(appleOnly('platforms: [.macOS(.v14), .linux]'), false)
+  assert.equal(namesPort(5432, 'DATABASE_URL=postgres://localhost:5432/x'), true)
+  assert.equal(namesPort(5432, 'nothing'), false)
+  assert.ok(isPrivate('10.1.2.3') && isPrivate('192.168.0.1') && isPrivate('100.64.0.1') && isPrivate('fd00::1'))
+  assert.ok(!isPrivate('8.8.8.8'))
+  assert.equal(parseVersion('go version go1.26.5 darwin/arm64'), '1.26.5')
+  assert.equal(parseVersion('v22.11.0'), '22.11.0')
+  assert.equal(escape('a*b?[c]\\d'), 'a\\*b\\?\\[c]\\\\d')
+})
+
+test('browser login: PKCE, state and issuer checked, the code redeemed for a device token', async () => {
+  let issuer
+  let seen
+  const server = http.createServer((req, res) => {
+    let body = ''
+    req.on('data', (d) => (body += d))
+    req.on('end', () => {
+      seen = Object.fromEntries(new URLSearchParams(body))
+      res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ access_token: 'cb_device', token_type: 'Bearer' }))
+    })
+  })
+  await new Promise((r) => server.listen(0, '127.0.0.1', r))
+  issuer = `http://127.0.0.1:${server.address().port}`
+  let authUrl
+  try {
+    const token = await browserLogin(issuer, {
+      device: 'laptop',
+      open: async (url) => {
+        authUrl = new URL(url)
+        const q = authUrl.searchParams
+        // the consent page redirects back with the code, the state and the issuer
+        const back = new URL(q.get('redirect_uri'))
+        back.search = new URLSearchParams({ code: 'c1', state: q.get('state'), iss: issuer }).toString()
+        setTimeout(() => fetch(back), 10)
+      },
+    })
+    assert.equal(token, 'cb_device')
+    assert.equal(authUrl.pathname, '/cb/oauth/authorize')
+    assert.equal(authUrl.searchParams.get('client_id'), 'cocoonbox-cli')
+    assert.equal(authUrl.searchParams.get('scope'), 'account')
+    assert.equal(authUrl.searchParams.get('device_name'), 'laptop')
+    assert.match(authUrl.searchParams.get('redirect_uri'), /^http:\/\/127\.0\.0\.1:\d+\/callback$/)
+    assert.equal(seen.grant_type, 'authorization_code')
+    assert.equal(seen.code, 'c1')
+    assert.equal(challenge(seen.code_verifier), authUrl.searchParams.get('code_challenge'))
+    await assert.rejects(
+      browserLogin(issuer, {
+        open: async (url) => {
+          const q = new URL(url).searchParams
+          setTimeout(() => fetch(`${q.get('redirect_uri')}?code=c&state=wrong&iss=${encodeURIComponent(issuer)}`), 10)
+        },
+      }),
+      /another sign-in/,
+    )
+    await assert.rejects(
+      browserLogin(issuer, {
+        open: async (url) => {
+          const q = new URL(url).searchParams
+          setTimeout(() => fetch(`${q.get('redirect_uri')}?code=c&state=${q.get('state')}&iss=https://evil.example`), 10)
+        },
+      }),
+      /not http/,
+    )
+  } finally {
+    server.close()
+  }
+  assert.equal(deviceName('mac.local'), 'mac')
+  assert.ok(authorizeUrl('https://e', { redirect: 'r', challenge: 'c', state: 's', device: 'd' }).startsWith('https://e/cb/oauth/authorize?'))
+})
+
+test('browser: one argv element, no shell, on every platform; win32 never goes through cmd', async () => {
+  const { browserCommand, openBrowser } = await import('../src/box/browser.js')
+  const evil = 'https://claude.ai/x?a=1&calc|whoami^%PATH%'
+  for (const platform of ['win32', 'darwin', 'linux']) {
+    const [cmd, args] = browserCommand(evil, { env: {}, platform })
+    assert.notEqual(cmd, 'cmd')
+    assert.equal(args[args.length - 1], new URL(evil).href, platform)
+    assert.ok(!args.some((a) => a === '/c'))
+  }
+  assert.deepEqual(browserCommand(evil, { env: {}, platform: 'win32' }), ['rundll32', ['url.dll,FileProtocolHandler', new URL(evil).href]])
+  assert.equal(browserCommand('file:///etc/passwd', { env: {} }), null)
+  assert.equal(browserCommand('javascript:alert(1)', { env: {} }), null)
+  const seen = []
+  const fakeSpawn = (cmd, args, opts) => {
+    seen.push({ cmd, args, opts })
+    return { on: () => ({ unref() {} }) }
+  }
+  assert.equal(openBrowser(evil, { env: {}, platform: 'win32', spawn: fakeSpawn }), true)
+  assert.equal(seen[0].opts.shell, false)
+  assert.equal(seen[0].args.length, 2)
+})
+
+test('browser: a real opener gets the URL as one argument and no shell runs its metacharacters', { skip: process.platform === 'win32' }, async () => {
+  const { openBrowser } = await import('../src/box/browser.js')
+  const dir = tmpdir()
+  const out = path.join(dir, 'argv.json')
+  const pwned = path.join(dir, 'pwned')
+  const opener = path.join(dir, 'opener')
+  fs.writeFileSync(opener, `#!${process.execPath}\nrequire('fs').writeFileSync(${JSON.stringify(out)}, JSON.stringify(process.argv.slice(2)))\n`, { mode: 0o755 })
+  const evil = `https://claude.ai/x?a=1&touch ${pwned};touch ${pwned}|touch ${pwned}^%PATH%$(touch ${pwned})`
+  assert.equal(openBrowser(evil, { env: { BROWSER: opener } }), true)
+  for (let i = 0; i < 100 && !fs.existsSync(out); i++) await new Promise((r) => setTimeout(r, 20))
+  const argv = JSON.parse(fs.readFileSync(out, 'utf8'))
+  assert.deepEqual(argv, [new URL(evil).href])
+  assert.ok(!fs.existsSync(pwned))
+})
+
+test('sign-in link: the normalized URL; | ^ and quotes end a link, a target with them is skipped', () => {
+  assert.equal(findSignInLink('open https://claude.ai/x?&calc now', 'claude'), 'https://claude.ai/x?&calc')
+  assert.equal(findSignInLink('https://claude.ai/x|calc', 'claude'), 'https://claude.ai/x')
+  assert.equal(findSignInLink('https://claude.ai/x^calc', 'claude'), 'https://claude.ai/x')
+  assert.equal(findSignInLink('\x1b]8;;https://claude.ai/x|calc\x07t\x1b]8;;\x07', 'claude'), null)
+  assert.equal(findSignInLink('https://CLAUDE.ai/a%20b', 'claude'), 'https://claude.ai/a%20b')
+})
+
+test('tty escape: ~. at line start disconnects, ~~ sends ~, other ~ pass through', async () => {
+  const { escapeFilter } = await import('../src/box/rsh.js')
+  let gone = 0
+  const f = escapeFilter(() => gone++)
+  assert.deepEqual(f(Buffer.from('a~b')), { data: Buffer.from('a~b'), disconnect: false })
+  assert.deepEqual(f(Buffer.from('\r~~x')), { data: Buffer.from('\r~x'), disconnect: false })
+  assert.deepEqual(f(Buffer.from('\r~')), { data: Buffer.from('\r'), disconnect: false })
+  assert.deepEqual(f(Buffer.from('q')), { data: Buffer.from('~q'), disconnect: false })
+  assert.equal(gone, 0)
+  assert.deepEqual(f(Buffer.from('\r~.')), { data: Buffer.from('\r'), disconnect: true })
+  assert.equal(gone, 1)
+  const g = escapeFilter(() => gone++)
+  assert.equal(g(Buffer.from('~.')).disconnect, true, 'the first byte is a line start')
+})
+
+test('back pastes BACK again once when the box CLI never took it, and only after a paste', async () => {
+  const { Offloader } = await import('../src/offload/offloader.js')
+  const { OffloadStore } = await import('../src/offload/store.js')
+  const home = tmpdir()
+  const store = new OffloadStore(home)
+  store.save({ id: 'id1', repo: 'k1', box: 'b', box_name: 'main', name: 'r', dir: '/w/r', kind: 'claude', base: null, top: null, started_at_ms: 0, seen: 0 })
+  const run = async (firstDelivery) => {
+    const sends = []
+    let posted = false
+    class Fake extends Offloader {
+      async verb(args) {
+        if (args[0] === 'status') return { sessions: [{ repo: 'k1', status: sends.length ? 'working' : 'idle', hook_at_ms: 5 }] }
+        if (args[0] === 'send') {
+          sends.push(args.slice(3).join(' '))
+          if (sends.length === 2) posted = true
+          return { delivery: sends.length === 1 ? firstDelivery : 'pasted' }
+        }
+        if (args[0] === 'read') {
+          await new Promise((r) => setTimeout(r, 20))
+          return { status: 'working', entries: posted ? [{ seq: 1, kind: 'back', offload_id: 'id1', body: '# Hand-over: x' }] : [] }
+        }
+        return { ok: true }
+      }
+    }
+    const f = new Fake({ connection: { endpoint: 'e', token: 't' }, box: { id: 'b' }, store, rsh: 'x', env: {} })
+    const out = await f.back('k1', { retryS: 0.05, waitS: 1, pollMs: 5 }).catch((e) => e)
+    store.save({ id: 'id1', repo: 'k1', box: 'b', box_name: 'main', name: 'r', dir: '/w/r', kind: 'claude', base: null, top: null, started_at_ms: 0, seen: 0 })
+    return { sends, out }
+  }
+  const pasted = await run('pasted')
+  assert.deepEqual(pasted.sends, ['--back', '--back --interrupt'])
+  assert.equal(pasted.out.handover, '# Hand-over: x')
+  const queued = await run('queued')
+  assert.deepEqual(queued.sends, ['--back'], 'a queued BACK is never re-sent')
+  assert.match(queued.out.message, /has not handed the work back/)
+})
+
+test('back waits for the box agent to be idle twice in a row before asking for its hand-over', async () => {
+  const { Offloader } = await import('../src/offload/offloader.js')
+  const { OffloadStore } = await import('../src/offload/store.js')
+  const home = tmpdir()
+  const store = new OffloadStore(home)
+  const record = { id: 'id1', repo: 'k1', box: 'b', box_name: 'main', name: 'r', dir: '/w/r', kind: 'claude', base: null, top: null, started_at_ms: 0, seen: 0 }
+  const run = async (statuses, opts) => {
+    store.save(record)
+    const log = []
+    let i = 0
+    let sent = false
+    class Fake extends Offloader {
+      async verb(args) {
+        if (args[0] === 'status') {
+          const status = statuses[Math.min(i++, statuses.length - 1)]
+          log.push(`status ${status}`)
+          return { sessions: status === null ? [] : [{ repo: 'k1', status, hook_at_ms: 1 }] }
+        }
+        if (args[0] === 'send') {
+          log.push(`send ${args.slice(3).join(' ')}`)
+          sent = true
+          return { delivery: 'accepted' }
+        }
+        if (args[0] === 'read') return { status: 'idle', entries: sent ? [{ seq: 1, kind: 'back', offload_id: 'id1', body: '# Hand-over: x' }] : [] }
+        return { ok: true }
+      }
+    }
+    const progress = []
+    const f = new Fake({ connection: { endpoint: 'e', token: 't' }, box: { id: 'b' }, store, rsh: 'x', env: {} })
+    f.progress = (m) => progress.push(m)
+    const out = await f.back('k1', { waitS: 0.3, pollMs: 5, ...opts }).catch((e) => e)
+    return { log, out, progress }
+  }
+  const busy = await run(['working', 'working', 'idle', 'working', 'idle', 'idle'])
+  assert.deepEqual(busy.log.filter((l) => l.startsWith('status')).slice(0, 6), ['status working', 'status working', 'status idle', 'status working', 'status idle', 'status idle'])
+  // one more status read after the wait records the hook time for the pasted-retry check
+  assert.equal(busy.log.indexOf('send --back'), 7, 'BACK goes out only after two idle polls in a row')
+  assert.equal(busy.out.handover, '# Hand-over: x')
+  assert.match(busy.progress[0], /waiting for it to go idle/)
+
+  const blocked = await run(['blocked', 'blocked'])
+  assert.equal(blocked.log.indexOf('send --back'), 3, 'a session blocked by an unconfirmed delivery takes BACK again')
+
+  const unknown = await run([null])
+  assert.equal(unknown.log.indexOf('send --back'), 2, 'a box that reports no session status is not waited on')
+
+  const never = await run(['working'])
+  assert.ok(!never.log.some((l) => l.startsWith('send')), 'nothing is sent when it never goes idle')
+  assert.match(never.out.message, /still working after .* nothing was sent.*back --interrupt/)
+
+  const stopped = await run(['stopped'])
+  assert.match(stopped.out.message, /stopped without handing the work back/)
+
+  const interrupt = await run(['working'], { interrupt: true })
+  assert.deepEqual(interrupt.log.filter((l) => l.startsWith('send')), ['send --back --interrupt'], '--interrupt skips the wait')
+})
+
+test('landing summaries say where HEAD went and what is left uncommitted', async () => {
+  const { landingSummary } = await import('../src/offload/git.js')
+  const head = 'ae472b8c0ffee00000000000000000000000000'
+  assert.equal(landingSummary({ kind: 'fastForward', head, uncommitted: [] }), "fast-forward: this branch now points at the box's commit ae472b8")
+  assert.equal(landingSummary({ kind: 'fastForward', head, uncommitted: ['b.txt'] }), "fast-forward: this branch now points at the box's commit ae472b8; uncommitted: b.txt")
+  assert.equal(landingSummary({ kind: 'fastForward', head: null, uncommitted: ['a.txt'] }), "fast-forward: the box made no commit; its changes are applied uncommitted (a.txt)")
+  assert.equal(
+    landingSummary({ kind: 'merged', files: ['calc.py'], head, uncommitted: ['__pycache__/calc.pyc'] }),
+    "merged: this branch now points at the box's commit ae472b8; the changes you made meanwhile are kept; uncommitted: __pycache__/calc.pyc",
+  )
+  assert.equal(landingSummary({ kind: 'merged', files: ['a.txt'], head: null, uncommitted: ['a.txt'] }), "merged: the box's changes are applied uncommitted (a.txt)")
+})