#227 Opt-in background autoupdate for the swamp binary (configurable cadence + risk tolerance)

Problem

Today, the swamp binary updates only when a user explicitly runs swamp update. In practice users routinely run versions that are days or weeks behind master. Multiple times today this session we hit issues that were already fixed in a newer build — only discovered after reproducing, filing tickets, and noticing the version delta. Each round costs real time on both the user side and the maintainer side.

Failure modes of the current "pull manually" model:

• Users forget to run swamp update for weeks, so they hit known and already-fixed bugs.
• Multi-person teams drift to inconsistent versions, making bug repros hard.
• "Have you run swamp update?" becomes the universal first response in support — wasting time on both sides.

Proposed solution

Add an opt-in background autoupdater with two configurable settings:

1. Cadence — how often the agent checks for updates. Options: daily, weekly, manual (off). Default for opt-in users: daily.
2. Risk tolerance / channel — which release stream to follow. Options: stable (released versions only), latest (every successful main build, including pre-release). Default: stable.

Platform-native scheduling:

• macOS: launchd LaunchAgent (~/Library/LaunchAgents/club.swamp.autoupdate.plist)
• Linux: systemd --user timer or fallback cron
• Windows: Task Scheduler

Configuration uniform across platforms via existing config plumbing:

swamp config set update.auto enabled
swamp config set update.cadence daily
swamp config set update.channel stable

Or interactively:

$ swamp update --setup-auto
? How often should swamp check for updates? (daily/weekly/manual) [daily]: 
? Which channel? (stable/latest) [stable]: 
✓ Installed launchd agent at ~/Library/LaunchAgents/club.swamp.autoupdate.plist
✓ Next check scheduled: tomorrow 09:00 local

swamp update (manual) should remain the default and primary path. Autoupdate is purely opt-in — never auto-enabled.

Why opt-in matters

Some users — especially CI environments and shared infrastructure — explicitly need pinned binaries. Defaulting to off keeps the current invariant intact for them. Casual local users opt in once and the "stale binary" problem goes away permanently.

Signals it works

• After autoupdate is enabled and a new release ships, the user's swamp --version reflects the new build on their next invocation, without manual intervention.
• The autoupdater logs to a known location (e.g. ~/.swamp/log/autoupdate.log or platform-equivalent) so users can audit "when did my version change?" and triage post-update breakage.
• swamp update --setup-auto status reports the current schedule, last check, last upgrade, and next scheduled check.

Suggested companion skill

A swamp-autoupdate skill would let agents walk users through the choice during onboarding — asking cadence and risk tolerance, then writing the config. Slots naturally next to swamp-getting-started.

Alternatives considered

• Auto-update on every invocation (like some package managers do): too disruptive — would slow every command and add network dependency at runtime.
• Stale-version warning on invocation: easier to implement but does not actually solve the "I forgot" problem; users dismiss warnings.
• Stick with the manual-only model + better release notifications: viable, but does not close the gap for users who do not monitor announcements.

Environment / motivation

Observed today: ran into already-fixed behaviors against swamp 20260504.140403.0-sha.d4c9188f, then a manual swamp update jumped me to 20260504.162725.0-sha.51f43769 — a build from earlier the same day. That is the gap the autoupdater would have closed automatically.