#262 First-class shell-shim support for extensions, with registry-level visibility

Problem

Some extensions (e.g. @hivemq/mudroom) need a host-side shell wrapper — a binary on PATH, a shell function, an alias, a keybinding hook — to provide a usable UX. Today the extension author has to ship a "setup skill" or README, and the user pastes a snippet into .zshrc / .bashrc / fish config by hand. This produces three problems:

1. Inconsistent install experience — every extension that needs a shell wrapper reinvents the wheel.
2. No durable record — the user has no way to see which pulled extensions have planted code in their shell.
3. No registry visibility — swamp extension search and the swamp.club extension page give no hint that an extension expects to modify the user's shell. That is a trust and supply-chain concern: a shim runs on every shell startup, with arbitrary code, but today the only signal is buried in the README.

Proposed solution

1. Manifest support for shell-shim declarations

New top-level field in manifest.yaml:

shellShims:
  - name: mudroom
    kind: function          # function | path | alias
    target: bin/mudroom     # path relative to extension root
    description: "Launch mudroom in a sandboxed container"
    shells: [zsh, bash, fish]

2. Explicit install command

swamp extension shim install <name> and swamp extension shim rm <name> manage the user's shell profile via a swamp-managed block, delimited with sentinel comments so it is idempotent and removable.

swamp extension pull does not auto-install shims — the user opts in explicitly. This preserves the trust boundary: pulling code is one decision, granting it a hook in your shell is a separate one.

3. Registry visibility

swamp.club extension pages show a "Shell shims" section listing every shim the extension declares plus the literal snippet that would be installed.

swamp extension search / swamp extension list --json include a shellShims field (or a [shim] marker in human output) so users can filter and audit before pulling.

4. Local audit command

swamp extension shim list enumerates every shim currently installed across pulled extensions, with the absolute path of each target binary. Surfaces what was previously hidden across three different rc files.

Alternatives

• Status quo (per-extension setup skills / READMEs): fragmented, untracked, no registry visibility. Each extension reinvents the wheel.
• Auto-install on swamp extension pull: rejected. pull should remain a non-side-effecting operation on the user's shell. Requiring an explicit shim install step preserves the trust boundary.
• Out-of-band tooling (Homebrew formulae, dotfiles managers): orthogonal. Works for system-wide installs but fails the tight-coupling case where the shim is a thin wrapper around swamp model method run … calls that need the extension pulled in this repo.

Concrete prior art

@hivemq/mudroom ships a bin/mudroom bash wrapper plus a mudroom-setup skill that walks the user through pasting a shell function into their profile. The function prints mudroom: launching from <path> on every invocation so the user has a runtime signal of which copy is active — that hint exists precisely because there is no swamp-level audit surface today.