Multi-step CLI tools that mix local git mutations with remote SSH operations need: (1) deferred irreversible ops or compensating rollback, (2) cold-start as the primary test path, (3) disposable-artifact-aware recovery, (4) Tailscale SSH compatibility for BatchMode checks.
Building advect, a CLI that hands off in-progress git work between machines over Tailscale + SSH. The push command runs ~14 steps: preflight checks, WIP commit, git push, notes sync, handoff file generation, remote pull via SSH, SCP transfer, tmux session creation.
Multi-step CLI commands that mix local git mutations with remote SSH operations are fragile at step boundaries. Three concrete failure modes emerged during first real-world use:
The command commits a WIP and pushes to origin (steps 4-5) before confirming the remote can receive the work (step 11). When the remote pull fails, the WIP commit is orphaned on both local HEAD and origin. The user must manually git reset HEAD~1 + git push --force-with-lease to recover.
Fix pattern: Either defer irreversible operations until after the precondition they depend on (confirm remote is reachable and repo exists before pushing), or implement compensating transactions (on failure: unwrap WIP locally, force-push to restore origin).
The remote pull script assumed the repo already existed on the target. For a tool whose entire purpose is moving work to other machines, "repo doesn't exist yet" is the primary use case, not an edge case. The fix was adding git clone as a third branch alongside "cd + pull" and "add worktree."
Fix pattern: When building tools that operate across machines, test the cold-start path first. The happy path (everything already set up) will work; the first-run path is where assumptions break.
WIP commits marked with [advect:wip] are explicitly disposable, but the pull logic used git pull --ff-only which fails when the remote has a stale WIP from a previous failed attempt. Since WIP commits are disposable by design, the remote should detect the sentinel and git reset --hard origin/<branch> instead of attempting merge/rebase.
Fix pattern: If your protocol creates temporary/disposable artifacts (WIP commits, lock files, staging state), the recovery path must know they're disposable and act accordingly — don't apply normal merge semantics to throwaway state.
SSH preflight used BatchMode=yes to avoid interactive prompts, but Tailscale SSH requires a one-time interactive auth check on first connection. The check fails silently (exit code 255), then succeeds on retry once the auth is cached. This makes the preflight non-deterministic — it depends on whether you've recently SSH'd to that host.
Consideration: For Tailscale-aware tools, either detect Tailscale SSH (check if the host resolves to a 100.x.y.z address) and skip BatchMode, or do a pre-warm connection attempt with a longer timeout before the BatchMode check.