A bounded mobility utility for carrying branch state and project assets across machines. The v1.0 handoff exists; this page does not claim daily use without evidence.
Mission profile
- Reduce a machine handover to one deliberate command on each side.
- Refuse to act whenever the repository state is ambiguous, instead of guessing.
- Carry the state that Git does not carry: databases, large working assets and untracked material.
- Record which machine owns the work, in a channel that never pollutes project history.
- Block obvious secrets and oversized untracked files before they reach a remote.
Architecture
Verified state
What exists and has been exercised at the time of writing.
- A handoff is two commands: depart on the machine being left, arrive on the machine being taken up.
- Handover state lives in a dedicated Git notes reference, so no BAM file enters the main history.
- Departure runs the configured checks, snapshots SQLite databases through the database API rather than copying files mid-write, commits, pushes and publishes a note recording commit, branch, machine, status and backups.
- Arrival refuses to overwrite a dirty tree, fetches, pulls fast-forward only, restores Git LFS and submodules, restores configured out-of-Git state and takes ownership.
- The working branch is never force-pushed.
- Eight documented conditions stop the tool: divergent branch, an in-progress merge, rebase, cherry-pick or revert, detached HEAD, local modifications on arrival, obvious secrets, oversized untracked files, a failing hook and an invalid checksum during database restore.
- A local safety copy is kept before any database restore.
- Per-project configuration can require tests before departure and run commands after arrival.
- The tool has been exercised across the whole active portfolio in a single status pass.
Stated limits
What this project is not, written here so nobody has to discover it later.
- The v1.0 handoff exists. Daily adoption is not asserted here, because the artefacts cannot evidence it.
- Part of what this tool does is now also covered by the portfolio control plane's worktree hydration and resume. The overlap is stated rather than hidden.
- It is a single-file internal tool with no dedicated repository and no automated test suite of its own.
- It synchronizes repositories that are already cloned. It does not create remote repositories and does not clone an account wholesale.
- It stops on divergence rather than resolving it. The operator still decides what a conflict means.
- The Windows path is documented and installable, but the exercised evidence comes from the Linux side.
The smallest useful piece of infrastructure
BAM exists because the studio runs on two machines and the expensive failure is not a hard drive dying. It is arriving somewhere and discovering that the interesting work stayed behind, uncommitted, on the other desk. One command on departure, one on arrival, and the question stops being interesting.
Refusal is the feature
Most of the tool is conditions under which it declines to act: a divergent branch, an operation already in progress, a detached head, a dirty tree on arrival, a secret in the payload, an untracked file too large to be an accident. It stops and explains rather than improvising. A handoff tool that guesses is worse than no handoff tool.
State Git does not carry
Databases are snapshotted through the database's own API instead of copied mid-write, large working assets move outside Git, and a safety copy is kept before any restore. The ownership record lives in a separate notes reference, which keeps the project history clean of operational chatter.