Run the Agent Setup Past a Failed Tool Upgrade, and Skip a Held cswap - #4116

Summary

On Windows, menu option 11, "Update agent setup" (bootstrap.ps1 -AgentSetup), upgraded the agent CLIs and then stopped. The skills, the Claude Code safety kit and the Codex and opencode rules steps never ran.

Root cause

• The tool that failed was cswap, not herdr. Nothing was wrong with herdr: its updater printed "already up to date" on stderr and exited 0.
• Why cswap failed: uv tool upgrade claude-swap upgraded the package in the tool's venv and refreshed the claude-swap.exe launcher. It could not replace cswap.exe, because a running cswap held that file, and Windows lets nothing replace a running executable. uv therefore exited non-zero.
• How that stopped the setup: install-agents.ps1 recorded Failed: cswap and exited 1. The loader's Invoke-Tool then called die. bootstrap.sh's agent_setup has the same abort through set -e.
• Why the summary missed the upgrade: the failure path returns before a version change is recorded. So Changed: left out a cswap that had in fact moved to the new version.

Changes

• Both loaders tolerate a tool failure, and only that.
  • install-agents now exits 3 when a tool failed or was refused while the others still ran. It exits 1 when the run itself refused or stopped, for example a declined prompt, no terminal without --yes, or a usage error.
  • On exit 3, bootstrap.ps1 (Invoke-AgentSetup) and bootstrap.sh (agent_setup) still run the skills, kit and rules steps. Then they print Not current: agent tools (an upgrade failed, see above) on stdout and exit 1.
  • Any other non-zero code stops the setup as before. A failure in the skills, kit or rules step also keeps its current behavior.
• Both install-agents scripts re-read the version after a failed upgrade. A partial upgrade now still appears under Changed:. One shared helper, record_change / Add-VersionChange, replaces the duplicated inline blocks in the self-updater and manager paths.
• install-agents.ps1 skips cswap, with a reason, while a running process holds either cswap launcher. This works like the herdr pane case and runs under -DryRun too. Linux needs no equivalent, since a running binary can be replaced there.
• Docs and the update-host skill now describe the new outcome.
  • The steps in docs/host-setup.md "Agent Setup" and both cswap explanations.
  • The kept-tree paragraph in host-setup/README.md, which now names the install-tools step.
  • update-host's "What the Setup Does" and "Report It", with the generated copies regenerated by build_dist.py.

Tests

• tests/test_bootstrap.py, for both loaders:
  • An agent setup whose tools step exits 3 still runs every later step, prints the not-current line, and exits 1.
  • One whose tools step exits any other code stops there.
  • The stubs now take a FAIL_CODE.
• tests/test_install_agents.py:
  • A failed upgrade that moved the version is still listed under Changed:. This is tested for both scripts.
  • cswap is skipped while a copied-bash process stands in for a running launcher, and a dry run previews that skip.
  • A helper-level test of Get-CswapLauncherHolder against a stubbed Get-Process, which runs natively on Windows.
  • The tool-failure assertions move from exit 1 to exit 3.

Run on this host:

• Native Windows: test_bootstrap.py: 190 ran, OK. test_install_agents.py: OK, its Windows helpers included.
• WSL Ubuntu: the Linux classes of both files pass, apart from 5 failures that the unmodified main worktree shows identically under WSL.
  • 4 are mise cases in test_install_agents.py.
  • 1 is test_every_managed_tool_is_executable, because /mnt/c has no exec bits.
• mcr.microsoft.com/powershell container with Python 3.13 via uv: TestInstallAgentsWindows, 46 ran, OK.
• Docker lint wrapper: shellcheck, shfmt and PSScriptAnalyzer pass. ruff, build_dist.py --check and the prose gate are clean too.

Native verification on Windows 11

These ran from this branch's worktree at 3c1543f, with bootstrap.ps1 -AgentSetup -FromTree <worktree> -Yes, then -AgentStatus -FromTree <worktree>. Host-specific values are replaced with placeholders.

Setup, exit 0:

cswap: at <version>, and a running cswap (process <pid>) holds its launcher, which uv cannot replace while it runs, close it and run this again to update it
  settings -> %USERPROFILE%\.claude\settings.json (autoMode.environment: $defaults added first, so Claude Code's built-in rules apply alongside this host's <n> entries)
  <host> | Windows 11 | hub 3c1543f | payload c0aad5827a70061e | agent-safety v1, fleet-bootstrap v1 | <time>

The $defaults line comes from the first run on this branch, which made the change. Later runs read already current. After that run, autoMode.environment[0] reads $defaults, and every other entry kept its original order, which was compared against a capture taken before the run.

Status, exit 0:

This checkout: payload c0aad5827a70061e, hub 3c1543f
This machine:  <host> | Windows 11 | hub 3c1543f | payload c0aad5827a70061e | agent-safety v1, fleet-bootstrap v1 | <time>
autoMode.environment: <n> untagged entries, with $defaults
CURRENT: this machine matches this checkout.
  codex: CURRENT %USERPROFILE%\.codex\AGENTS.md (config directory present, no codex CLI on PATH)
  opencode: CURRENT %USERPROFILE%\.config\opencode\AGENTS.md
  Not current: fleet skills
  Agent tools: listed above, versions not compared with upstream

Not current: fleet skills is expected here and is not caused by this change. A -FromTree run deliberately leaves the existing skills registration on the bootstrap's kept tree, which still holds the last main install, instead of moving it to a worktree. So the status reads that copy as behind this checkout, and "Every other agent setup step reports current" is not printed. The next -AgentSetup from main after promotion refreshes the kept tree.

The tolerated-failure path did not fire natively, because no tool failed on this host once cswap was skipped. The PowerShell handoff tests cover it natively instead.

Local review

Three local-strict-review passes ran at the frontier tier and were recorded with local_review.py.

• Round 1 raised 3 findings, all introduced, all fixed in 3c1543f:
  • The loaders treated a decline or refusal as an upgrade failure.
  • The cswap skip did not run under -DryRun.
  • update-host did not report a tool failure or skip.
• Round 2, over the full diff at 3c1543f, raised none.
• Round 3, over the full diff at 096d4a8 after the Copilot fixes, raised none.

🤖 Generated with Claude Code