perf(deploy): cut a quarter of a deploy's SSH round trips

[mhenrixon]

Summary

PR 5 of #154: fix the overhead the deploy report's per-phase command counts revealed. Every change here is a reduction the table measured, and the table is how each was verified afterwards — no fix landed that the numbers did not justify.

Measured on the integration harness (3 hosts, 2 app hosts), same stack before and after. The Acquire server lock rows nest inside the phase above them, so they are not summed twice:

Phase	before	after
Build and push app image	19 ssh	15
Acquire deploy lock	4	4
Ensure dash-proxy	32	29
└ Acquire server lock	5	2
Detect stale containers	4	4
Boot	30	24
└ web vm1 / vm2	9 each	7 each
Prune	21	10
└ Acquire server lock	5	2
distinct round trips	110	86 (−22%)

A redeploy goes 67 → 57 (−15%): Build and push 25 → 21, Boot 34 → 28.

What changed

• Dash::Commands::App#boot_state — the container-clash check and the running-version read become one command, chained with ; and split on a separator. Boot −1 per host.
• Dash::Commands::Auditor#record_then — an audit line and the action it describes in one shell string, still in that order. Used by the boot, the latest-image tag, the image pull and both prune sweeps.
• Dash::Commands::Builder::Base#clean_then_pull — drop the stale image and pull in one command; the removal stays best-effort (|| true).
• Dash::Cli::Base#ensure_run_directory — sweep each host once per process instead of once per lock acquire. Both Acquire server lock rows 5 → 2.

Nothing new is executed and no ordering semantics change: the audit is still written before the action it describes, the health barrier is untouched, and no capture is folded into anything.

One user-visible change: folded audit lines now print at INFO as part of the command they lead, where they used to run at verbosity: :debug and were invisible. The audit log content and dash audit are unchanged.

Measured, not fixed — follow-up

Ensure dash-proxy is the single largest row (32 ssh, 12.8s, ahead of Boot and Prune) and is deliberately left alone. Its round trips are the staged-rename migrations — LegacyRename, copy_legacy_config_volume, the kamal-proxy container and kamal-proxy-net teardown — four executes per host of pure legacy checking on every boot, plus drift detection. Folding them changes migration semantics that CLAUDE.md freezes until stage 3c, and the issue's candidate list does not include them. Worth its own issue once 3c lands.

Test plan

• bundle exec ruby -Itest -e 'Dir["test/**/*_test.rb"].grep_v(/integration/).each { |f| require File.expand_path(f) }' — 1873 runs, 0 failures
• bundle exec rubocop --parallel — no offenses
• bin/test (full suite, Docker + published proxy image) — 1892 runs, 6046 assertions, 0 failures
• Real deploy + redeploy through the integration harness, before and after, tables above
• Clash path verified against a real deploy: a same-version redeploy renames the clashing container and stops the renamed one, not the container the boot just started
• New round-trip-count assertions in prune_test, build_test and app_test pin the reductions
• The cost-guard sequence in test/cli/main_test.rb is unchanged

Deviations & judgment calls

Deviations

• Proxy boot is the largest row and is left alone. See "Measured, not fixed" above. Reported rather than changed, because the round trips there are frozen migration logic.
• The cost-guard sequence is unchanged. It pins only the commands deploy issues itself (subcommands are stubbed), and every reduction here lands in a subcommand. Round-trip-count assertions were added to the suites that do own those commands, so the reductions are pinned where the guard cannot see them.
• validate_image keeps its own round trip. The issue asked for clean + pull in one command; folding validate_image in as well would put the pull under that command's trailing || (echo "... missing the 'service' label" && exit 1), so a failed pull would report a missing label. 4 → 2 per host rather than 4 → 1.

Discoveries

• old_version_renamed_if_clashing had an ordering dependency the issue did not name. Combining the two captures means the running version is read before the clashing container is renamed. When the clash IS the running container, the old version to stop afterwards is the name it was renamed to — stopping the name that was read would stop the container the boot just started. Handled by substituting renamed_version when the read version equals the version being deployed, which is exactly what the second capture used to return. Unit-tested, and verified against the harness with a same-version redeploy.
• ensure_run_directory had to memoise per host, not per process. The issue said "memoise per process (DASH.run_directory_ensured)". A boolean is wrong: dash upgrade narrows DASH.hosts with with_specific_hosts between lock acquires, so a flag would skip the sweep for a host that was never in scope when it was set. Tracks the host set instead.
• test/cli/build_test.rb:142 failed on any clean checkout, and has since feat(report): measure every build step from the buildx stream dash already reads #156. stdouted strips, eating the two-space indent of Build when that header is the first line printed. CI only passes because the workflow runs rm Gemfile.lock before the suite, so Dash::Git.uncommitted_changes prints a line above it — exactly the host-dependence .claude/rules/testing.md forbids. In path (this PR edits the pull_on_hosts expectations in the same file), so fixed here: the capture no longer strips, and the two report tests stub uncommitted_changes so the checkout's state cannot decide the output.

Judgment calls

• Auditor#record_then(line, *commands) rather than a combine at each call site: five call sites wanted the same shape, and it keeps shell building in the Commands layer where .claude/rules/coding-style.md puts it.
• Folded audits print at INFO now. Called out above; the alternative (keeping them at debug) would mean not folding them at all.
• BOOT_STATE_SEPARATOR = "--%--": % is not legal in a docker tag and container ids are hex, so neither answer can forge the separator line.

Refs #154

https://claude.ai/code/session_01MKyeeYAuG4fR11sBmJa8dm

---

Summary by cubic

Cuts a deploy's SSH round trips by 22% (110 → 86), the reductions #154's report exposed, by folding independent commands into single shell strings and sweeping the run directory once per host per process. A redeploy goes 67 → 57.

Notes for review

• The clash check and running-version read now share a round trip, so the running version is read before the rename; when they're the same container, the boot stops the renamed one.
• Folded audit lines now print at INFO as part of the command they lead; the audit log and dash audit are unchanged.
• clean_then_pull groups the best-effort clean in parentheses so a failed audit write cannot fall into the || true and pull anyway.
• validate_image keeps its own round trip so a failed pull doesn't report a missing service label.
• Ensure dash-proxy is left alone deliberately — its round trips are frozen migration logic.
• Fixes test issues: the build_test report assertions only held on a dirty checkout, and recorded_commands now stops recording where its block ends.

^{Written for commit e137dfb. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 17 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 7 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}