Drain: a 1:1 handoff, with everything the new machine needs checked in

README.md

@@ -62,11 +62,15 @@ The fleet stops cleanly and picks up elsewhere: every session pushes its work an
 
 ```
 DEVTEAM_ROLE=supervisor node docs/devteam/scripts/devteam.mjs drain --reason "moving to a new laptop"
-DEVTEAM_ROLE=supervisor node docs/devteam/scripts/devteam.mjs drain --status    # until "ready to move: yes"
-DEVTEAM_ROLE=supervisor node docs/devteam/scripts/devteam.mjs log-sync          # then land the log:
+# once every session is parked: its own handoff, project/handoffs/supervisor.md, landed as chore drain-handoff
+DEVTEAM_ROLE=supervisor node docs/devteam/scripts/devteam.mjs drain --status    # what's left; repeat until "ready to move: yes"
+DEVTEAM_ROLE=supervisor node docs/devteam/scripts/devteam.mjs observe-spend     # then land the log:
+DEVTEAM_ROLE=supervisor node docs/devteam/scripts/devteam.mjs log-sync
 DEVTEAM_ROLE=supervisor node docs/devteam/scripts/devteam.mjs merge --chore log
 ```
 
+Anything needed for 1:1 parity is checked in and portable; only secrets travel by hand. So `drain --status` also blocks on files left in `run/`, worktrees with unpushed work, the owner's unfinished review drafts, and agent memory outside the repo that isn't folded into knowledge or the supervisor's handoff. When it's ready it prints a parity fingerprint of the log; `undrain` on the new machine prints its own, and they match.
+
 `drain --status` ends with the new machine's checklist, generated from the settings: which `worktree_files` and secret keys to copy, which logins, which tools.
 
 **On the new machine**, in this order:

docs/devteam/process/supervisor.md

@@ -188,15 +188,23 @@ Due `retro_every_days` after the last one, or when a feature has fully merged si
 
 To stop the whole fleet cleanly and pick it up on another computer. Git carries the log once it lands (`project/log`), every ticket and plan branch, and the PRs. Everything else is this machine's: `run/` (the live log, the owner's review results and drafts in `run/questions`, `run/pr` with `forge: "git"`, caches, `dashboard.log`), every session's worktree under `.worktrees/` and whatever is uncommitted or unpushed there, each agent's harness session (its context doesn't move), the `worktree_files` and secret keys, and the tools (agent CLI, `gh`, asdf, tmux, the dashboard). A drain moves what can move into git and lists the rest.
 
+**The rule:** anything the new machine needs for 1:1 parity is checked in and portable. Only secrets (`worktree_files`, the sinks' keys) travel outside git, by hand over a secure channel. Nothing of value may live only in `run/`, a worktree, a stash or an agent's own memory when you stop.
+
 **On the old machine**
 1. `devteam.mjs drain --reason "<why>"`. It logs an act of class `drain` (operational: on no ladder, it grants nothing) naming every worker and planner it tells, and sends each the same `ruling`: commit work in progress (a WIP commit is fine) and push its branch; write a handoff note (`project/tickets/<id>/handoff.md`, or `project/plans/<feature>/handoff.md` for a planner) with what's done, the exact next step, open questions and anything it couldn't commit; commit and push it; `phase parked --note "drained"`; stop (`worker.md` §9). Running `drain` again re-sends it to the sessions not yet parked.
 2. While draining, `worker` and `planner` refuse to start a session (`--force` starts one anyway, and its act says so), the idle-capacity and idle-planning findings are off, and parked sessions are not stale. Answer what's open as usual; ask the owner to finish any review page they saved a draft of.
 3. `devteam.mjs drain --status` until it says **ready to move: yes**. Per session it checks parked, the branch pushed (local equals origin), the worktree clean, and the handoff note on the pushed branch; fleet-wide, that every live log file is on main (else `log-sync`, then `merge --chore log`), spend observed up to now (else `observe-spend`, then land the log again), and every answered review result committed to its PR (`review result <qid> --commit` in that PR's worktree). It warns about drafts that won't move and, with forge git, `run/pr`; it lists open PRs and open owner questions, which move with the forge and the log. The one line that can't land first is the act of merging the log itself; git keeps that merge. The supervisor's own spend after its last `observe-spend` stays behind (a warning).
 4. It ends with the new machine's checklist, generated from the settings and the log: the clone, `.tool-versions` (asdf), the agent CLI and `gh` logins, the `worktree_files` and the secret sinks' keys to copy over a secure channel (never git, chat or the log), tmux, the supervisor start, `undrain`, and the dashboard. Give it to the owner, then stop: close the workers' tmux session and your own.
 
+**Your own handoff.** Once every session is parked, write `project/handoffs/supervisor.md`: what you were in the middle of, what you are waiting on (PRs, CI, the owner), what you told the owner you would do, trials and promises in flight, and anything from your agent's own memory that the next supervisor needs (owner rules belong in knowledge; add them there). Land it: `chore start drain-handoff`, `chore pr drain-handoff --title "Supervisor handoff"`, `merge --chore drain-handoff`. A later drain overwrites it.
+
+**What `drain --status` also blocks on**, so nothing stays behind: no supervisor handoff on main since the drain; agent memory outside the repo changed after that handoff landed; files in `run/` the kit didn't make (move what matters into `project/` with a chore, delete the rest); any worktree under `.worktrees/` with uncommitted work or commits on no remote; an owner's unfinished review draft. Local branches with commits on no remote and stash entries are warned about.
+
+**When it says ready to move: yes** it prints a **parity** fingerprint of the whole log. Give it to the owner with the checklist, then stop: close the workers' tmux session and your own. Anything you log after that stays on this machine.
+
 **On the new machine** (the owner, then you)
 1. The owner clones, installs the pinned tools, logs in to the agent CLI and `gh`, copies the files and keys, and starts you exactly as the README's step 9 does. Your prompt (`prompt supervisor`) sees a drain with no later undrain and opens with what to do.
-2. `devteam.mjs undrain`. If `run/log` is empty or missing it rebuilds it from `project/log` on origin's main, then logs an `undrain` act (with this host) and lifts the drain. It prints each drained session's restart command: `worker <id>` or `planner <feature>`, with `--resume` only where the window and worktree are still here. Run them; a worktree is made from the pushed branch, never from main, and `--resume` where no harness session can exist (its worktree was just made) starts fresh instead and says so.
+2. `devteam.mjs undrain`. It prints the drained supervisor's handoff (read it first) and the log's parity fingerprint, which matches the one the old machine printed when the move is 1:1. If `run/log` is empty or missing it rebuilds it from `project/log` on origin's main, then logs an `undrain` act (with this host) and lifts the drain. It prints each drained session's restart command: `worker <id>` or `planner <feature>`, with `--resume` only where the window and worktree are still here. Run them; a worktree is made from the pushed branch, never from main, and `--resume` where no harness session can exist (its worktree was just made) starts fresh instead and says so.
 3. Make sure the dashboard is running (§11) and tell the owner its address. Then §1 as usual.
 
 **The handoff note.** A restarted session gets its handoff note in its prompt, marked "Handoff from a drained session", only while the note is current: the session was parked by the latest drain and has logged no phase of its own since (the launch's `starting` line doesn't count; a planner, which logs no phases while it works, ends it with any line of its own, such as a message). Once it logs its first phase after the restart, later prompts leave the note out, so a stale note can't mislead a later session. The file is never deleted: it stays in the ticket's (or plan's) folder and lands with the PR, and a later drain overwrites it with a fresh one. Adding or rewriting a handoff note does not void a review verdict.