Offer a single SWE node, and let a manifest declare itself superseded

[AbirAbbas]

The catalog advertised two SWE nodes — the Python swe-planner at the repo root and swe-planner-go under //go. Installing SWE should give you one thing, so this collapses them to a single entry named swe-planner, and adds the mechanism that carries an existing install across — the open question the first version of this PR flagged and left unanswered.

One catalog entry

• control-plane/internal/cli/catalog.go — drop the Python entry; the surviving one keeps the fuller product description and is named swe-planner, after the product rather than the implementation. Catalog goes 6 → 5 entries.
• desktop/src/shared/catalog.ts — same collapse in the app's curated list. The two lists have no automated cross-check, so they are edited in lockstep; the desktop card keeps its own wording.
• Docs and skills — the README install command is now the bare repo URL (the manifest redirects), and every example uses the swe-planner node id, so a first-time user's first command after a catalog install actually works. docs/mcp-integration.md, skills/agentfield-use/SKILL.md and its byte-identical skillkit/skill_data mirror updated to match.

superseded_by — a package retires itself, without the control plane knowing who it is

Collapsing the catalog on its own strands anyone who already installed the old node: the entry disappears, and Desktop's update/uninstall path refuses names it cannot find in the catalog. Fixing that must not teach AgentField about any particular node, so the redirect is an optional manifest key rather than a table of names in here:

name: swe-planner
superseded_by: https://github.com/Agent-Field/SWE-AF//go

The value is any installable source af install accepts, including a //subdir selector and an @ref. Installing a superseded package installs the successor instead and replaces the old one. Any node author can rename or replace their own node this way; the control plane stays agnostic, and the product-specific data lives in the product's own repo. Documented in docs/installing-agent-nodes.md — a generic key nobody can find is not much use.

What the user sees when the superseded node is installed — an explicit warning before anything is touched:

⚠️  swe-planner has been superseded by https://github.com/Agent-Field/SWE-AF//go
⚠️  swe-planner is currently installed and WILL BE REPLACED. The successor is installed
    first and node-scoped secrets are carried over; if that fails, what you
    have now is left as it is.
  installing the successor instead

The ordering is the whole design, and each rule has a test:

• The redirect is taken before the force check and before anything is copied, so a redirect never half-installs the package it is redirecting away from.
• The successor installs first, and a failure leaves what the user had exactly as it was — see the safety net below, which is what makes that true when the successor shares the name.
• A successor may carry the same name as its predecessor — a node renaming itself in place. The redirect carries the user's consent into that install rather than tripping the successor's own "already installed (use --force)" check. Nothing needs retiring afterwards and node-scoped secrets are already in the right scope.
• Where the names do differ, node-scoped secrets move before the uninstall — UninstallPackage deletes that scope outright, so every af secrets set KEY --node <old> value would otherwise vanish in the swap. A value already set on the successor wins: the user set that one deliberately, and later. Global secrets are shared and untouched.
• Retiring never fails the install. The successor is already working, so a stubborn leftover prints how to remove it by hand instead of reporting failure.
• Chains are bounded at 3 hops, so two manifests pointing at each other fail loudly instead of cloning forever.

The redirect is a git-install behaviour only. A local-path install ignores it, which is the documented way to install a superseded node on purpose.

Safety net: a failed reinstall no longer eats the package it was replacing

copyPackage clears the destination before the replacement is copied, and long before its dependencies build. Replacing a package in place therefore had a window where a failure in the dependency step — a missing Go toolchain is enough, and that is precisely the machine most likely to hit it — left the user with neither the node they had nor a working new one. The existing directory is now set aside and put back on any failure before the registry is updated.

This is not specific to the redirect: plain af install --force over any installed package had the same hole. The test asserts the predecessor's own files are back on disk after a deliberately failing install, and fails without the fix.

Bug found alongside: the //subdir selector was dropped from the recorded source

updateRegistryWithGit recorded info.URL — the URL after ParseGitURL has split the subdirectory off. That was invisible for the //go selector form, whose caller re-parses the original string, but not when the subdirectory arrives via the --path flag or the install API, both of which pass it alongside a bare URL. Those installs recorded a repo root as their source, so updating a //go-installed node would reinstall the repo root instead — the exact inverse of what this PR exists to do. Kept as its own commit so it can be reviewed on its own terms.

Tests

git_supersede_test.go — redirect to successor; replace an existing install; same-name replace-in-place (registry, files, and the absence of an "already installed" error); secrets surviving a same-name replace; secret migration across a renaming replace, including successor-wins and globals-survive; the no-prior-install case; the bounded cycle; restore-after-a-failed-reinstall; the stash/restore/discard unit; appendSubdirSelector round-tripping back through ParseGitURL; and the --path source recording.

The two behavioural fixes were checked by reverting each and confirming the corresponding test goes red — the restore test reports the predecessor's files simply missing, which is the data loss it exists to prevent.

The pre-existing catalog assertion was Contains(out, "swe-planner"), which "swe-planner-go" also satisfies as a substring — it would not have caught a mistyped name or a re-added Python entry. Both catalog tests now pin the surviving row's name rather than only asserting the other one is absent.

Validation

GOFLAGS=-buildvcs=false go build ./..., go vet ./..., go test ./... (51 packages), and npm ci / npm run typecheck / npm test (387 tests) in desktop/ — all clean.

Verified end to end with a real af install against a local repo carrying the redirect, with the Python node already installed and holding one node-scoped secret:

• warned, then installed the successor as swe-planner — no --force, no error
• the predecessor's files are gone and the successor's are in their place, under the one directory
• the registry holds a single swe-planner entry with its source recorded as …//go, so the next update resolves the same package
• the node-scoped secret and the global one both survived
• no backup residue left in packages/
• the installed node binary, started with NODE_ID unset, registers as node_id: swe-planner

Pairs with Agent-Field/SWE-AF#122, which puts the superseded_by line in the SWE-AF root manifest and renames the node.

🤖 Generated with Claude Code

[github-actions]

📊 Coverage gate

Thresholds from .coverage-gate.toml: per-surface ≥ 84%, aggregate ≥ 85%, max per-surface regression ≤ 1.0 pp, max aggregate regression ≤ 0.50 pp.

Surface	Current	Baseline	Δ
control-plane	87.00%	87.40%	↓ -0.40 pp	🟡
sdk-go	92.70%	92.00%	↑ +0.70 pp	🟢
sdk-python	93.82%	93.73%	↑ +0.09 pp	🟢
sdk-typescript	91.05%	90.42%	↑ +0.63 pp	🟢
web-ui	84.76%	84.79%	↓ -0.03 pp	🟡
aggregate	85.59%	85.75%	↓ -0.16 pp	🟡

✅ Gate passed

No surface regressed past the allowed threshold and the aggregate stayed above the floor.

[github-actions]

📐 Patch coverage gate

Threshold: 80% on lines this PR touches vs origin/main (from .coverage-gate.toml:thresholds.min_patch).

Surface	Touched lines	Patch coverage	Status
control-plane	146	83.00%	✅
sdk-go	0	—	➖ no changes
sdk-python	0	—	➖ no changes
sdk-typescript	0	—	➖ no changes
web-ui	0	—	➖ no changes

✅ Patch gate passed

Every surface whose lines were touched by this PR has patch coverage at or above the threshold.

[santoshkumarradha]

Thanks for tightening the catalog and docs. I don’t think we should merge this as-is because it knowingly strands existing desktop users who already installed : after they upgrade, the app loses the update/uninstall path for that node. Please add a migration path or compatibility handling for the old install before we collapse the catalog entry.

[santoshkumarradha]

Thanks for tightening the catalog and docs. I do not think we should merge this as-is because it knowingly strands existing desktop users who already installed swe-planner: after they upgrade, the app loses the update/uninstall path for that node. Please add a migration path or compatibility handling for the old install before we collapse the catalog entry.