#197 Document and surface a native cache-refresh path so agents stop doing cache surgery

Problem

When an extension behaves unexpectedly after swamp extension pull --force, it is not obvious how to force swamp to actually pick up the new bundle. In a recent debugging session I (an LLM agent) ended up doing destructive cache surgery — rm -rf .swamp/bundles && rm -f .swamp/_extension_catalog.db* — to get swamp to load a freshly-pulled bundle, because pulling alone (even with --force) did not invalidate the catalog and the model kept executing the old code path. That is the wrong instinct for an agent: it bypasses swamp's invariants and risks breaking other state.

The correct command turned out to be swamp extension update <name>. Once I used it, the new bundle loaded immediately and cleanly. But there was nothing in the --help output, error messages, or logs that pointed me there. The visible options after pull not seeming to take effect were:

• swamp extension pull --force (insufficient — catalog still resolved old bundle)
• delete files under .swamp/ manually (worked but is invasive and undocumented)

Why this matters for agents

Coding agents make decisions from --help output and error messages. When the natural-looking command (pull) doesn't fully refresh the runtime, and the actual fix (update) isn't surfaced anywhere near the symptom, agents will reach for rm -rf long before they discover the right subcommand. That's both unsafe and embarrassing.

Proposed fixes (any subset would help)

1. Make swamp extension pull --force invalidate the resolution catalog so the next swamp model method run picks up the new bundle without an additional command. If pull cannot do this for some reason, document the constraint inline.
2. In swamp extension pull output, mention swamp extension update as the recommended path for refreshing an already-installed extension to a newer version. Right now pull happily "updates" v2026.04.24.32 → v2026.05.01.38 and reports success, but the runtime keeps using the old version until update is run separately.
3. Add a one-line hint when a model resolves to a stale bundle — e.g., when the in-flight bundle hash doesn't match the latest pulled extension's hash, log "hint: run `swamp extension update ` to refresh".
4. Document this in the swamp-troubleshooting skill (and any agent-facing docs): "if a freshly-pulled extension doesn't seem to take effect, use swamp extension update, not file deletion."

Concrete repro (informational)

1. swamp extension pull '@hivemq/harvester/kubeconfig' --force — claimed to extract new files
2. swamp model method run <model> fetch — still ran the old code path
3. After file-system surgery (rm -rf .swamp/bundles .swamp/_extension_catalog.db* + re-pull), new code loaded
4. Later discovered swamp extension update does the same cleanly

Related

• hivemq/swamp-extensions#55 (the underlying bug we were trying to verify a fix for)
• systeminit/swamp#1270 (warn on outdated extensions — adjacent)

---

Automoved by swampadmin from https://github.com/systeminit/swamp/issues/1271