From c57c6a1548d3ba3d4112ab66209c614ae8910c4b Mon Sep 17 00:00:00 2001
From: tonic <tonic@simular.ai>
Date: Thu, 5 Nov 2026 12:19:18 +0800
Subject: [PATCH 1/2] Name the offload refs and conflict branch box, not
 cocoonbox

Refs in the user's repo move to refs/box/ and a conflicting back lands on box/back-<time>. Needs the box agent from simular-ai/box#78, which also accepts the old names.
---
 cli/README.md                | 2 +-
 cli/src/offload/git.js       | 4 ++--
 cli/src/offload/offloader.js | 6 +++---
 cli/test/offload-e2e.test.js | 6 +++---
 4 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/cli/README.md b/cli/README.md
index 664c5ae..722a21e 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -79,7 +79,7 @@ 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.
+- **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 `box/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.
 
diff --git a/cli/src/offload/git.js b/cli/src/offload/git.js
index 4485d03..70e1319 100644
--- a/cli/src/offload/git.js
+++ b/cli/src/offload/git.js
@@ -216,7 +216,7 @@ export class GitRepo {
       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])
+        if (move.old) this.git(['update-ref', `refs/box/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] : [])])
@@ -242,7 +242,7 @@ export class GitRepo {
 
   #branch(box, conflicts, now) {
     const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')
-    const name = `cocoonbox/back-${stamp}`
+    const name = `box/back-${stamp}`
     this.git(['branch', '-f', name, box])
     return { kind: 'branch', branch: name, conflicts }
   }
diff --git a/cli/src/offload/offloader.js b/cli/src/offload/offloader.js
index 0b53c14..63e7b37 100644
--- a/cli/src/offload/offloader.js
+++ b/cli/src/offload/offloader.js
@@ -90,7 +90,7 @@ export class Offloader {
       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}`)
+      refs.push(`refs/box/offload/${id}`, `refs/box/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,
@@ -279,8 +279,8 @@ export class Offloader {
     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}`], {
+      const ref = `refs/box/back/${record.id}`
+      const fetch = await repo.runAsync(['fetch', '-q', `box:${record.dir}`, '+refs/heads/*:refs/box/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}`)
diff --git a/cli/test/offload-e2e.test.js b/cli/test/offload-e2e.test.js
index 5cec366..e92d2ca 100644
--- a/cli/test/offload-e2e.test.js
+++ b/cli/test/offload-e2e.test.js
@@ -52,7 +52,7 @@ function playBoxAgent({ dir, offload_id: id, repo: key }, change) {
   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)
+  git(dir, 'update-ref', `refs/box/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') })
@@ -141,7 +141,7 @@ test('offload warns, then moves the task; back fast-forwards the box commits', {
   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', `refs/box/offload/${r.offload_id}`), git(repo, 'rev-parse', `refs/box/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'))
@@ -195,7 +195,7 @@ test('back applies a clean merge uncommitted when the user worked meanwhile, els
   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.match(conflict.landing, /^conflict: the box's work is on the branch box\/back-/)
   assert.equal(fs.readFileSync(path.join(repo, 'a.txt'), 'utf8'), 'mine\n', 'the work tree is untouched')
 })
 

From 4e6c9ea1958eac04040cd9e8c17aa616093c50c0 Mon Sep 17 00:00:00 2001
From: chenchen <chenchen@simular.ai>
Date: Thu, 5 Nov 2026 12:31:45 +0800
Subject: [PATCH 2/2] Offload to boxes on an image before the ref rename

A box keeps its image until the user upgrades it, and images before
simular-ai/box#78 only know refs/cocoonbox/: they check the snapshot
under refs/cocoonbox/offload/<id> and write the back commit under
refs/cocoonbox/back/<id>. Offload now also sends the snapshot under the
old name (the ref is deleted from the user's repo once sent), and back
falls back to the old back ref when the new one is missing. This works
with no image-version check, since no image carries #78 yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 cli/src/offload/offloader.js         | 26 +++++++++++++++++++----
 cli/test/fakebox/bin/cocoonbox-agent |  7 ++++++-
 cli/test/offload-e2e.test.js         | 31 +++++++++++++++++++++++++---
 3 files changed, 56 insertions(+), 8 deletions(-)

diff --git a/cli/src/offload/offloader.js b/cli/src/offload/offloader.js
index 63e7b37..b555441 100644
--- a/cli/src/offload/offloader.js
+++ b/cli/src/offload/offloader.js
@@ -19,6 +19,12 @@ 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
 
+// Box images before simular-ai/box#78 only know the pre-rename refs: they check the snapshot under
+// refs/cocoonbox/offload/<id> and write the back commit under refs/cocoonbox/back/<id>. Boxes keep their image until the
+// user upgrades it, so offload also sends the snapshot under the old name (dropped here once sent) and back falls back to
+// the old back ref. Newer images take refs/box/ first and ignore the rest.
+const legacyRef = (kind, id) => `refs/cocoonbox/${kind}/${id}`
+
 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
@@ -57,6 +63,7 @@ export class Offloader {
     const excludes = path.join(stage, 'excludes')
     const bundle = path.join(stage, 'offload.bundle')
     const refs = []
+    let legacy = null
     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)'))
@@ -104,6 +111,8 @@ export class Offloader {
         const snapshot = repo.snapshot(index, `box offload ${id}`)
         record.base = snapshot
         repo.git(['update-ref', refs[0], snapshot])
+        legacy = legacyRef('offload', id)
+        repo.git(['update-ref', legacy, snapshot])
         repo.keepIndex(refs[1], index)
         const env = envJson(repo.top, this.env)
         fs.writeFileSync(path.join(stage, 'env.json'), env)
@@ -140,6 +149,7 @@ export class Offloader {
       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 {
+      if (legacy) repo.run(['update-ref', '-d', legacy])
       fs.rmSync(excludes, { force: true })
       fs.rmSync(bundle, { force: true })
     }
@@ -280,10 +290,18 @@ export class Offloader {
       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/box/back/${record.id}`
-      const fetch = await repo.runAsync(['fetch', '-q', `box:${record.dir}`, '+refs/heads/*:refs/box/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}`)
+      const fetchBack = (from) =>
+        repo.runAsync(['fetch', '-q', `box:${record.dir}`, '+refs/heads/*:refs/box/box/*', `+${from}:${ref}`], {
+          extra: { GIT_SSH_COMMAND: this.rsh, GIT_SSH_VARIANT: 'simple', BOX_ENDPOINT: this.rshEnv.BOX_ENDPOINT, BOX_TOKEN: this.rshEnv.BOX_TOKEN },
+        })
+      const fetch = await fetchBack(ref)
+      if (fetch.status !== 0) {
+        // an older box image wrote the back commit only under its pre-rename name
+        const legacy = await fetchBack(legacyRef('back', record.id))
+        if (legacy.status !== 0) {
+          throw new OffloadError('failed', `git fetch from the box failed (${fetch.status}):\n${fetch.error}\nand under the older back ref (${legacy.status}):\n${legacy.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])
diff --git a/cli/test/fakebox/bin/cocoonbox-agent b/cli/test/fakebox/bin/cocoonbox-agent
index 410592e..2111633 100755
--- a/cli/test/fakebox/bin/cocoonbox-agent
+++ b/cli/test/fakebox/bin/cocoonbox-agent
@@ -2,7 +2,8 @@
 // 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.
+// session: a test plays the box agent by committing in the copy and posting `back` with FAKE_POST. FAKE_BOX_LEGACY plays
+// an image before simular-ai/box#78, which checks the snapshot only under refs/cocoonbox/offload/<id>.
 import { execFileSync, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -104,6 +105,10 @@ switch (verb) {
         if (ref && ref.startsWith('refs/')) execFileSync('git', ['-C', dir, 'update-ref', ref, oid])
       }
     }
+    const snapshot = `refs/${process.env.FAKE_BOX_LEGACY ? 'cocoonbox' : 'box'}/offload/${opt('--id')}`
+    if (spawnSync('git', ['-C', dir, 'rev-parse', '-q', '--verify', `${snapshot}^{tree}`]).status !== 0) {
+      reply({ ok: false, code: 'failed', error: `${snapshot} is missing from the copy` }, 1)
+    }
     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: {} })
diff --git a/cli/test/offload-e2e.test.js b/cli/test/offload-e2e.test.js
index e92d2ca..cb27c83 100644
--- a/cli/test/offload-e2e.test.js
+++ b/cli/test/offload-e2e.test.js
@@ -45,14 +45,17 @@ 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) {
+/**
+ * playBoxAgent commits change in the copy, makes S' as the box packer's `post --back` does, and posts back; legacy
+ * names S' as an image before simular-ai/box#78 does.
+ */
+function playBoxAgent({ dir, offload_id: id, repo: key }, change, { legacy = false } = {}) {
   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/box/back/${id}`, snap)
+  git(dir, 'update-ref', `refs/${legacy ? 'cocoonbox' : 'box'}/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') })
@@ -199,6 +202,28 @@ test('back applies a clean merge uncommitted when the user worked meanwhile, els
   assert.equal(fs.readFileSync(path.join(repo, 'a.txt'), 'utf8'), 'mine\n', 'the work tree is untouched')
 })
 
+test('a box on an image before the ref rename takes the offload and hands back', { skip, timeout: 60000 }, async () => {
+  const repo = makeRepo('proj-legacy')
+  fs.writeFileSync((await cli(['offload', 'handover-path'], { cwd: repo })).text.trim(), handover('old image'))
+  const old = await startFakeBox({ workspace: path.join(tmp, 'workspace'), state: path.join(tmp, 'state'), env: { ...IDENT, FAKE_BOX_LEGACY: '1' } })
+  try {
+    const extraEnv = { BOX_ENDPOINT: old.endpoint }
+    const done = await cli(['offload', '--kind', 'claude', '--yes', '--json'], { cwd: repo, extraEnv })
+    assert.equal(done.code, 0, done.stderr + done.text)
+    const r = JSON.parse(done.text)
+    const snap = git(repo, 'rev-parse', `refs/box/offload/${r.offload_id}`)
+    assert.equal(git(r.dir, 'rev-parse', `refs/cocoonbox/offload/${r.offload_id}`), snap, 'the old image gets S under its old name')
+    assert.equal(git(repo, 'for-each-ref', 'refs/cocoonbox/'), '', 'the old name is not kept in the user repo')
+    playBoxAgent(r, { 'a.txt': 'one\nfrom an old box\n' }, { legacy: true })
+    const back = await cli(['back', '--json'], { cwd: repo, extraEnv })
+    assert.equal(back.code, 0, back.stderr + back.text)
+    assert.match(JSON.parse(back.text).landing, /^fast-forward: /)
+    assert.equal(fs.readFileSync(path.join(repo, 'a.txt'), 'utf8'), 'one\nfrom an old box\n')
+  } finally {
+    await old.stop()
+  }
+})
+
 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'))