做到一半的代理任务要换台机器接着干：怎么交接才不丢东西？（中英切换）

Same three-person team, same seven computers: machines 1–3 develop, 4 and 5 review, 6 does Windows validation, 7 handles merging and ops.

Monday, 4 p.m. The agent on machine 1 is working on feat/cny-rounding: round CNY amounts half-up, keep zero decimals for JPY. It is about halfway done, and machine 1 looks like this. The branch was pushed once, and there are 2 more commits that weren't. In src/rounding.py, ROUND_HALF_EVEN has been changed to ROUND_HALF_UP and staged. One line of the test file has changed but isn't staged. src/money_ctx.py and a CSV of test cases are new and untracked. src/legacy_round.py has been git rm'd. A "bankers-rounding table" experiment sits in the stash. The ignored .wip/notes.md holds the most valuable sentence of all: "with HALF_EVEN everywhere, invoice 2019-0042 is off by one cent and finance rejects it." There is also a .env.local holding the invoice API token, and 3 MB of cache.

Xiao Li has to go to a meeting, and the agent on machine 2 needs to pick the task up. The three obvious ways are: push the branch; git add -A, commit a WIP and push; or copy the whole directory over. I scripted this exact state and handed it off with each of those three methods plus one I wrote myself, then compared every file hash on machine 2.

My position: a handoff is two jobs. The code state has to move completely and safely, and the reasoning has to be compressed into one page that must be filled in. And only one machine at a time may be working on the task. Git can move code, but it only knows about commits. The index, untracked files, the stash and ignored notes exist only on that machine. So does the agent's conversation transcript, and it is tied to paths and accounts. Below are the measurements, the two scripts I wrote, and two places where I got them wrong.

Four handoff methods, and what each one leaves on machine 2

The toy repo, the branch and machine 1's state are all generated by lab/build.sh; every method starts from a fresh copy of the same state. The remote is a bare repo with a post-receive hook that logs a "review trigger" for every push to refs/heads/*, to simulate machines 4 and 5 listening for branch pushes and starting a review whenever new code arrives.

A: push the branch. When machine 2 pulls, only the 2 commits arrive. The staged rounding change, the test change, the two new files, the deletion, the stash and the notes are all gone. Machine 2's agent faces a clean tree. It will redo the HALF_EVEN swap from scratch and never learn about invoice 2019-0042. As a bonus, the push triggered a review, and machine 4 went off to review half-finished work.

B: WIP commit, then push. This is the method I see most. All file contents arrive, but after git reset HEAD~1 on machine 2, whatever was staged and whatever wasn't all comes back as "unstaged." That distinction is information in itself: the agent staged the rounding change because it meant "this part is settled," while the test line was still being tried. The ignored notes and the stash are lost again, and review is triggered again.

Worse is when both machines keep working. I had machine 2 commit "m2: JPY zero decimals" and push. Then I had machine 1's agent, which hadn't stopped, do what it habitually does: --amend and push -f. The remote's last three commits ended up as "WIP handoff / add rounding table / add per_currency". Machine 2's commit was gone, with no error. This is not a rare case: an agent does not stop just because its human walked away.

C: copy the whole directory, with rsync or a sync drive. Everything arrives, including the stash and the index: 3,033,115 bytes in total. The problem is that nothing gets filtered. The token in .env.local lands on machine 2, and so does the 3 MB cache. Copying also does nothing to prevent two machines working at once; machine 1's agent can still push.

D: wip-handoff / wip-takeover. On machine 2, every file hash, the index, the deletion and the stash count match machine 1. The only difference is that .env.local isn't there. The handoff itself triggered no review; review starts only when machine 2 pushes normally after taking over.

D was refused by its own checks on the first two attempts. The first time, HANDOFF.md was still the template and its "Next" section said TODO. For the second attempt I simulated two things agents commonly do: leave an 8 MB database dump in the directory, and write a token starting with ghp_ into a test fixture. With B or C both of those would have travelled along, and B would have pushed them to GitHub.

Mechanism: what goes in Git, and what goes on the side channel

The idea is to keep the handoff in refs outside refs/heads/. Git lets you push any ref under refs/, and GitHub accepts them. I pushed a refs/wip/probe to this blog's private repo: the push succeeded, a fresh git clone doesn't bring it down, and I deleted it after testing. One thing I didn't verify: GitHub's docs describe the push event in terms of branches and tags, and I haven't tested on a repo with workflows whether a custom ref triggers Actions.

A handoff writes three kinds of refs:

• refs/wip/snap/<branch>: the snapshot commit. Its first parent is HEAD, its second parent records the index, and its own tree is the working tree plus untracked files plus any ignored files listed in .wip/carry. That's the same structure git stash uses. The difference is that it is built with a temporary index file, so machine 1's working tree, index and branch don't change by a single byte.
• refs/wip/lease/<branch>: the lease. An empty-tree commit whose message says owner=m2 snap=<snapshot sha>.
• refs/wip/stash/<branch>/N: the stash entries.

The snapshot, the lease and the stashes are written in a single git push --atomic. The lease uses --force-with-lease=<lease>:<old value> as a compare-and-swap: the remote lease must still have the value I read, or the whole push fails. When machine 2 restores, it first checks that the lease names it, that the snapshot sha in the lease matches the snapshot it fetched, and that its local working tree is clean. Then git read-tree -u --reset restores the working tree, git read-tree restores the index, and git stash store puts the stashes back.

Preventing two machines from working at once has two layers. The lease ensures only one machine at a time can take the task over or hand it on. The pre-push hook makes machine 1 check the lease before pushing refs/heads/feat/cny-rounding, and refuses if the owner isn't machine 1. In the lab, machine 1's agent pushing again, machine 1 changing its mind and handing to machine 3, and machine 3 trying to take over were all refused.

For the reasoning half I chose a one-page HANDOFF.md that must be filled in, with three sections: Next, Tried and failed, Do not touch. The script only checks that all three have content and no TODO. Whether the content is any good still depends on whoever writes it.

Should the agent's transcript move too?

I looked at how Claude Code 2.1.292 on the box stores sessions. They live under ~/.claude/projects/, in a directory named after the working directory with / replaced by -, for example -tmp-cctest/<session id>.jsonl. Every line carries the absolute cwd, the gitBranch, and the environment description from that moment. In other words, the transcript is tied to "which machine, which path." Machine 6 runs Windows, where even the path format differs.

Others have already done this thoroughly. SameSession encrypts the native session transcript and workspace state into isolated Git refs, and uses a compare-and-swap lease to stop two machines resuming at once. The idea is very close to mine, and its design doc honestly says the lease only "prevents accidental concurrent resumes" and is not distributed consensus. One difference: for compatibility across hosting providers it stores data under branch refs like refs/heads/same-session/... by default. In a pipeline where every branch push starts a review, machines 4 and 5 would need to filter that prefix out first. agent-handoff sends the session, the branch and uncommitted changes straight to the other machine over SSH and rewrites the old paths inside the transcript.

I ended up not moving the transcript, for three reasons. First, on these seven machines a handoff often means a different person, not just a different machine; machine 2 might be on Xiao Wang's account. The transcript holds every file the other agent read and the output of every command it ran, and someone should look at it before it goes to another person. Second, most of a long session is detours, and the agent taking over needs conclusions. Third, the transcript format is the vendor's internal implementation; SameSession's own README warns it can change. If it is one person moving between two of their own machines, and the context of a long session is genuinely valuable, SameSession is a better fit than my script.

The two things I got wrong

First: the receiver couldn't push. The first version of wip-takeover rebuilt the branch with checkout -B and didn't set an upstream. After machine 2 committed, git push failed with "has no upstream branch." An agent hitting that error usually runs git push -u origin HEAD, which is fine most of the time. Now the script fetches the remote branch first and runs --set-upstream-to; if the remote doesn't have the branch yet, it writes branch.<branch>.remote and merge directly.

The second was more dangerous: the lease did nothing. The first version built the refspecs as "${REFS[@]/#/+}", putting a + in front of every one. I assumed --force-with-lease would still protect the lease, then tested it on its own: with a + in front of the refspec, the old value given to --force-with-lease is simply ignored, and a stale value still force-pushes successfully. The lab didn't catch this at first because it ran serially, so every push read the latest lease.

I added a race test, lab/race.sh: two terminals on the same machine 1 hand off almost simultaneously, one to m2 and one to m3. The second pauses 2 seconds after reading the lease, while the first finishes its push. The first version reported "success" on both sides in 5 of 5 runs, the lease ended up with m3, and m2 had been told it was taking over. After the fix, exactly one side succeeded in each of the 5 runs, and the other got stale info. The change is one spot:

-REFS=("$WCOMMIT:$SNAP" "$LCOMMIT:$LEASE")
-git push -q --atomic --force-with-lease="$LEASE:$OLD" "$REMOTE" "${REFS[@]/#/+}"
+# no "+" on the lease refspec: with it, --force-with-lease stops working
+REFS=("+$WCOMMIT:$SNAP" "$LCOMMIT:$LEASE")
+git push -q --atomic --force-with-lease="$LEASE:$OLD" "$REMOTE" "${REFS[@]}"

One smaller episode: when I deleted the merged branch from machine 2, the pre-push hook stopped me, because that terminal had no MACHINE_ID set. The hook also applies to branch deletions, which is correct. Deleting branches after merge is better left to GitHub's automatic deletion, or done on machine 7.

The scripts

Sender:

scripts/wip-handoff

#!/usr/bin/env bash
# wip-handoff --to <machine>
# Snapshot the current branch's in-flight state (unpushed commits, staged,
# unstaged, untracked, deletions, files listed in .wip/carry) into
# refs/wip/snap/<branch>, and move the lease refs/wip/lease/<branch> to <machine>.
# Never touches your working tree, index, branch, or refs/heads on the remote.
set -euo pipefail
die(){ echo "wip-handoff: $*" >&2; exit 1; }
TO=""; while [ $# -gt 0 ]; do case "$1" in --to) TO="$2"; shift 2;; *) die "unknown arg $1";; esac; done
ME="${MACHINE_ID:-$(git config --get wip.machine || true)}"
[ -n "$ME" ] || die "set MACHINE_ID or git config wip.machine"
[ -n "$TO" ] || die "--to <machine> required"
REMOTE="${WIP_REMOTE:-origin}"
MAX_BYTES="${WIP_MAX_BYTES:-5242880}"
BR="$(git symbolic-ref --short HEAD)" || die "detached HEAD"
TOP="$(git rev-parse --show-toplevel)"; cd "$TOP"
SNAP="refs/wip/snap/$BR"; LEASE="refs/wip/lease/$BR"

# 1. intent: a handoff without "why" and "next" is just a tarball
H=.wip/HANDOFF.md
[ -f "$H" ] || die "write $H first (sections: ## Next, ## Tried and failed, ## Do not touch)"
for s in "## Next" "## Tried and failed" "## Do not touch"; do
  body="$(awk -v s="$s" 'index($0,s)==1{f=1;next} /^## /{f=0} f' "$H" | grep -v '^[[:space:]]*$' | grep -v 'TODO' || true)"
  [ -n "$body" ] || die "$H: section '$s' is empty or TODO"
done

# 2. lease: only the current owner (or nobody) may hand off
OLD="$(git ls-remote "$REMOTE" "$LEASE" | cut -f1)"
if [ -n "$OLD" ]; then
  git fetch -q "$REMOTE" "+$LEASE:refs/wip-remote/lease/$BR"
  OWNER="$(git log -1 --format=%B "refs/wip-remote/lease/$BR" | sed -n 's/^owner=//p')"
  [ "$OWNER" = "$ME" ] || die "lease for $BR is held by $OWNER, not $ME"
fi

sleep "${WIP_TEST_PAUSE:-0}"   # test hook: widen the read-then-push window (lab/race.sh)

# 3. build snapshot: I = current index, W = worktree + untracked + .wip/carry
HEADC="$(git rev-parse HEAD)"
ITREE="$(git write-tree)"
ICOMMIT="$(git commit-tree "$ITREE" -p "$HEADC" -m "wip index $BR")"
TMPIDX="$(mktemp)"; trap 'rm -f "$TMPIDX"' EXIT
cp "$(git rev-parse --git-path index)" "$TMPIDX"
export GIT_INDEX_FILE="$TMPIDX"
git add -A
git add -f "$H"
if [ -f .wip/carry ]; then
  grep -v '^\s*#' .wip/carry | grep -v '^\s*$' | while read -r p; do git add -f -- "$p"; done
fi
WTREE="$(git write-tree)"
unset GIT_INDEX_FILE

# 4. guards on what would leave this machine
CHANGED="$(git diff --name-only --no-renames "$HEADC" "$WTREE")"
bad=""
while IFS= read -r f; do
  [ -n "$f" ] || continue
  case "$f" in .env|.env.*|*/.env|*/.env.*|*.pem|*id_rsa*) bad="$bad\n  secret-looking file: $f";; esac
  sz="$(git cat-file -s "$WTREE:$f" 2>/dev/null || echo 0)"
  [ "$sz" -le "$MAX_BYTES" ] || bad="$bad\n  too large ($sz bytes): $f  (add to .gitignore or raise WIP_MAX_BYTES)"
done <<< "$CHANGED"
hits="$(git diff "$HEADC" "$WTREE" | grep '^+' | grep -nE 'gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{40,}|AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9_-]{20,}|-----BEGIN [A-Z ]*PRIVATE KEY' || true)"
[ -z "$hits" ] || bad="$bad\n  token-looking content in diff:\n$(echo "$hits" | cut -c1-80 | sed 's/^/    /')"
[ -z "$bad" ] || die "refusing to snapshot:$(printf "$bad")"

STASHES="$(git stash list --format=%H 2>/dev/null || true)"
NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
WCOMMIT="$(printf 'wip snapshot %s\n\nbranch=%s\nfrom=%s\nto=%s\nbase=%s\nat=%s\nstashes=%s\n' \
  "$BR" "$BR" "$ME" "$TO" "$HEADC" "$NOW" "$(echo $STASHES | wc -w)" \
  | git commit-tree "$WTREE" -p "$HEADC" -p "$ICOMMIT")"
EMPTY="$(git hash-object -t tree /dev/null)"
LCOMMIT="$(printf 'lease %s\n\nowner=%s\nfrom=%s\nsnap=%s\nat=%s\n' "$BR" "$TO" "$ME" "$WCOMMIT" "$NOW" | git commit-tree "$EMPTY")"

# 5. one atomic push: snapshot + lease (compare-and-swap on the lease)
# NOTE: no "+" on the lease refspec -- a "+" silently overrides --force-with-lease.
REFS=("+$WCOMMIT:$SNAP" "$LCOMMIT:$LEASE")
i=0; for s in $STASHES; do REFS+=("+$s:refs/wip/stash/$BR/$i"); i=$((i+1)); done
git push -q --atomic --force-with-lease="$LEASE:$OLD" "$REMOTE" "${REFS[@]}" \
  || die "push rejected (someone moved the lease?)"
git config "wip.branch.$BR.handedoff" "$TO"
echo "handed off $BR -> $TO  snap=${WCOMMIT:0:10} base=${HEADC:0:10} files=$(echo "$CHANGED" | grep -c . || true) stashes=$i"
echo "stop the agent on this machine now; pushes to $BR from $ME are blocked by the pre-push hook."

Receiver:

scripts/wip-takeover

#!/usr/bin/env bash
# wip-takeover <branch>
# On the receiving machine: fetch refs/wip/snap/<branch>, check the lease names
# this machine, recreate branch + index + worktree exactly, print HANDOFF.md.
set -euo pipefail
die(){ echo "wip-takeover: $*" >&2; exit 1; }
BR="${1:-}"; [ -n "$BR" ] || die "usage: wip-takeover <branch>"
ME="${MACHINE_ID:-$(git config --get wip.machine || true)}"; [ -n "$ME" ] || die "set MACHINE_ID"
REMOTE="${WIP_REMOTE:-origin}"
cd "$(git rev-parse --show-toplevel)"
git fetch -q "$REMOTE" "+refs/wip/snap/$BR:refs/wip-remote/snap/$BR" "+refs/wip/lease/$BR:refs/wip-remote/lease/$BR" \
  || die "no handoff for $BR on $REMOTE"
L="refs/wip-remote/lease/$BR"; W="refs/wip-remote/snap/$BR"
OWNER="$(git log -1 --format=%B "$L" | sed -n 's/^owner=//p')"
[ "$OWNER" = "$ME" ] || die "lease for $BR names $OWNER, not $ME"
[ "$(git log -1 --format=%B "$L" | sed -n 's/^snap=//p')" = "$(git rev-parse "$W")" ] || die "lease and snapshot disagree; ask the sender to re-run wip-handoff"
[ -z "$(git status --porcelain --untracked-files=all)" ] || die "working tree not clean; commit or stash first"
BASE="$(git rev-parse "$W^1")"; ITREE="$(git rev-parse "$W^2^{tree}")"
if git rev-parse -q --verify "refs/heads/$BR" >/dev/null; then
  git merge-base --is-ancestor "refs/heads/$BR" "$BASE" || die "local $BR has commits not in the snapshot; resolve by hand"
fi
git checkout -q -B "$BR" "$BASE"
git read-tree -u --reset "$W"      # worktree := snapshot (adds, edits, deletions)
git read-tree "$ITREE"             # index := what the sender had staged
n=0
git fetch -q "$REMOTE" "+refs/wip/stash/$BR/*:refs/wip-remote/stash/$BR/*" 2>/dev/null || true
for s in $(git for-each-ref --format='%(objectname)' --sort=-refname "refs/wip-remote/stash/$BR/"); do
  git stash store -m "from handoff" "$s"; n=$((n+1)); done
# the branch itself may exist on the remote (pushed before the handoff): track it
if git fetch -q "$REMOTE" "+refs/heads/$BR:refs/remotes/$REMOTE/$BR" 2>/dev/null; then
  git branch -q --set-upstream-to="$REMOTE/$BR" "$BR"
else
  git config "branch.$BR.remote" "$REMOTE"; git config "branch.$BR.merge" "refs/heads/$BR"
fi
git config "wip.branch.$BR.handedoff" ""
echo "took over $BR at base ${BASE:0:10}; restored stashes=$n"
echo "----- .wip/HANDOFF.md -----"; cat .wip/HANDOFF.md

Hook installed on machines 1–3:

hooks/pre-push

#!/usr/bin/env bash
# Refuse to push refs/heads/<b> unless this machine holds refs/wip/lease/<b>
# (or there is no lease). Install: cp hooks/pre-push .git/hooks/ && chmod +x
ME="${MACHINE_ID:-$(git config --get wip.machine)}"
remote="$1"
while read -r lref lsha rref rsha; do
  case "$rref" in refs/heads/*) b="${rref#refs/heads/}";; *) continue;; esac
  l="$(git ls-remote "$remote" "refs/wip/lease/$b" | cut -f1)"
  [ -n "$l" ] || continue
  git fetch -q "$remote" "+refs/wip/lease/$b:refs/wip-remote/lease/$b"
  owner="$(git log -1 --format=%B "refs/wip-remote/lease/$b" | sed -n 's/^owner=//p')"
  if [ "$owner" != "$ME" ]; then
    echo "pre-push: $b was handed off to $owner; $ME may not push it. (wip-takeover on $ME first, or ask $owner to hand it back)" >&2
    exit 1
  fi
done
exit 0

Rules for the dev machines' AGENTS.md:

templates/AGENTS-handoff.md

## Handing off unfinished work (machines 1-3)
- Never push a "WIP" commit to a branch to move work to another machine; review machines 4/5 pick up every branch push.
- To hand off: stop, update .wip/HANDOFF.md (Next / Tried and failed / Do not touch, no TODO left), then run
  `wip-handoff --to <machine>`. If it refuses (big file, token, empty section), fix the cause; never raise limits silently.
- Put local-only notes you want carried in .wip/carry (one path per line). .env* never travels.
- On the receiving machine run `wip-takeover <branch>` in a clean clone, read the printed HANDOFF.md before editing anything.
- If `git push` says the branch was handed off, stop working on it. Do not delete the lease or the hook.

Costs, and when not to use this

• The pre-push hook can't stop --no-verify. It's a seatbelt, not a lock. An agent that really wants to push still can. GitHub's branch protection and rulesets are configured by branch name and by person; there's no way to express "only the lease owner may push," and I found no server-side option. For a harder guarantee, stop the agent process on machine 1 after the handoff, or remove its push access to the branch.
• Anyone who can read the repo can fetch refs/wip/*. Don't use this on public repos, and on private ones think about what's in the snapshot. The secret check is a few regexes plus a filename rule for .env*; it doesn't know other formats.
• The refs don't show in GitHub's web UI and need cleaning up after merge. The kit includes wip-prune, which runs on machine 7 and deletes refs/wip/* for branches that no longer exist on the remote. Deleting a ref doesn't make the objects disappear from the server right away.
• Not for large files or binary artifacts. Files over 5 MB are refused by default, on purpose. If what needs to move is model weights or build output, put it in object storage and write the location in HANDOFF.md.
• For the same person briefly leaving their desk, none of this is needed. Use Claude Code's Remote Control or SSH plus tmux: the process stays on the original machine and you keep watching from another device.
• For small tasks under half an hour, starting over is cheaper. Having machine 2 start from the issue is faster than restoring half-finished work, and it doesn't inherit machine 1's wrong assumptions.
• Machine 6 runs Windows, and I haven't tested these scripts under Git Bash.

The most common objection: just push a WIP commit and have the receiver reset. It takes ten seconds, so why bother with refs, leases and hooks? With one dev machine, no automated review, and a handoff once or twice a month, that objection fully holds. With seven machines, two of them starting a review on every branch push, and agents that don't stop on their own, a WIP commit brings three problems. Machine 4 reviews half-finished work for nothing. Tokens and dumps get pushed to GitHub. A force-push overwrites the other machine's commit without an error. The first and last actually happened in the lab. The middle one happens as soon as an agent leaves behind the two files D hit on its second attempt, because git add -A takes everything it sees. Each costs more than running one extra script.

What you can do tomorrow

1. Unpack the kit below and run bash lab/run_all.sh to see in lab/out/ what each of the four methods loses. Then run bash lab/race.sh "$PWD/scripts/wip-handoff" 5 and confirm only one side succeeds each time.
2. On machines 1–3, run git config wip.machine m1 (m2 and m3 likewise), copy hooks/pre-push into .git/hooks/, and put scripts/ on PATH.
3. Add the rules above to the dev machines' AGENTS.md, and put templates/HANDOFF.md in the repo.
4. Add a wip-prune line to machine 7's routine jobs.
5. Next time someone has to leave mid-task, don't push a WIP commit. Write HANDOFF.md first, then run wip-handoff --to m2.

My conclusion: when several machines share work, the things most easily lost are the ones that never entered Git, and the most dangerous situation is two machines each believing the task is theirs. Move the code state completely through Git side refs, compress the reasoning into one page that must be filled in, and use a compare-and-swap lease so that only one machine at a time is working. Today you can unpack the kit, run the lab once in /tmp, and then try one real handoff in the repo where your team hands off most often.

All scripts, the hook, templates, lab build scripts and the race test: wip-handoff-kit.tar.gz.