Skip to main content
← Back to list
01Issue
BugShippedSwamp CLI
Assigneesstack72

Relationships

#628 doctor extensions: pulled-extension source files reported as orphans that --repair can't evict (nested @swamp/aws/* sibling mis-attribution)

Opened by crudec · 6/11/2026· Shipped 6/11/2026

Summary

swamp doctor extensions --json reports orphanFiles that point at pulled-extension source files under .swamp/pulled-extensions/, but swamp doctor extensions --repair does not evict them — its documented scope is "Prune Tombstoned catalog rows and evict unreferenced bundle files." This leaves a category of reported orphans with no working remediation: --repair skips them and swamp extension pull --force (which overwrites the same files) does not clear them either.

Separately, the orphan attribution appears cross-wired for nested @swamp/aws/* extensions: files under .swamp/pulled-extensions/@swamp/aws/iam/ are attributed to @swamp/aws/s3, and files under .swamp/pulled-extensions/@swamp/aws/s3/ are attributed to @swamp/aws/iam. This sibling mis-attribution looks like it may be the root cause of the files being flagged as orphans at all.

Environment

  • swamp version: 20260611.152058.0-sha.ab13d0a5
  • Both @swamp/aws/iam (v2026.06.08.2) and @swamp/aws/s3 (v2026.06.08.2) are installed/pulled.
  • overallStatus: pass throughout — these orphans are reported but never block.

Steps to reproduce

  1. In a repo with both @swamp/aws/iam and @swamp/aws/s3 pulled, run swamp doctor extensions --json.
  2. Observe orphanFiles containing 31 entries under .swamp/pulled-extensions/@swamp/aws/iam/... and .swamp/pulled-extensions/@swamp/aws/s3/..., each attributed to the sibling extension (counts: 17 → @swamp/aws/s3, 14 → @swamp/aws/iam).
  3. Run swamp doctor extensions --repair --force. It evicts the unreferenced .swamp/bundles/*.js and .swamp/vault-bundles/*.js files (those clear to 0), prints OVERALL: PASS, but the 31 pulled-extensions source orphans remain.
  4. Run swamp extension pull @swamp/aws/iam --force and swamp extension pull @swamp/aws/s3 --force. Files are overwritten, but swamp doctor extensions --json still reports the same 31 orphans.

Expected vs actual

  • Expected: Either the reported orphanFiles are all evictable by --repair (single, consistent remediation), or the diagnostic clearly distinguishes "bundle orphans (evict with --repair)" from "pulled-source orphans (clean with X)" and documents the remediation for each — and re-pulling an extension should reconcile its own source files so they are no longer orphaned.
  • Actual: orphanFiles mixes two categories with no distinguishing field; --repair silently acts on only one category; there is no documented path to clear the pulled-source orphans; and extension pull --force does not clear them. Nested @swamp/aws/* extensions also get cross-attributed to siblings.

Diagnostic narrative (how an agent is led to the wrong fix)

This is the part worth fixing for agent UX. My reasoning went:

  1. Hypothesis — "stale copies": I saw (a) the cross-wired attribution (@swamp/aws/s3 owning @swamp/aws/iam/... paths) and (b) recent pull timestamps, and inferred the orphans were leftover source copies from an earlier pull that the catalog no longer referenced — i.e. the on-disk files were stale relative to the catalog's current pull location.
  2. What that suggested: "Refresh the pull" — run swamp extension pull for both extensions to rewrite the source trees and reconcile them with the catalog.
  3. Why it doesn't work: After pull --force overwrote every listed file, swamp doctor extensions reported the identical 31 orphans. So orphan status is not about file content/staleness; the files are physically present and freshly written yet still "unreferenced." Re-pulling changes the bytes on disk but not whatever catalog↔file linkage makes them orphans — so the hypothesis predicted a fix the tool's own model can't deliver.

What I should have done instead:

  • Read the actual definition of "orphan" before acting. --repair's own help ("evict unreferenced bundle files") already says it targets bundle files, not pulled-extensions source — so re-pull was never going to be the sanctioned remediation, and that was knowable up front from the help text.
  • Tested the hypothesis cheaply before executing a --force mutation — e.g. inspect the catalog↔file mapping or fetch source (troubleshooting Tier 4) to learn what marks a pulled-source file unreferenced — rather than running pull --force and only then discovering it didn't change the orphan set.
  • Treated the cross-wired sibling attribution as a signal of a detector bug (root cause) rather than as evidence supporting a "stale files" story.

Suggested fixes

  1. Fix the nested-namespace orphan detector so @swamp/aws/iam and @swamp/aws/s3 source files are attributed to (and referenced by) their own extension, not the sibling — likely the root cause of the false orphans.
  2. Make orphanFiles self-describing: tag each entry with its category (bundle vs pulled-source) and whether --repair will act on it, so consumers don't infer remediation from path shape.
  3. Either extend --repair to clean pulled-source orphans, or document the supported remediation and have extension pull reconcile its own source files.
02Bog Flow
OPENTRIAGEDIN PROGRESSSHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 3 MOREPR_MERGED+ 1 MORECONTRIBUTOR_NOTIFIED

Shipped

6/11/2026, 7:24:23 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack726/11/2026, 5:57:27 PM
Editable. Press Enter to edit.

stack72 commented 6/11/2026, 7:24:54 PM

Thanks @crudec for reporting this! The fix has been merged and a release is on its way. We appreciate your contribution to swamp.

Sign in to post a ripple.