fix(cli)!: remove browser fork, add adapter override to hosted mode

[ankitranjan7]

What

webcmd browser fork was an undocumented alias bound to the same handler as webcmd adapter override, and it leaked the alias in its own error message:

$ webcmd browser fork hackernews
Error: Usage: webcmd adapter override <site>/<command> (got "hackernews")

The caller is told the usage of a command they did not run. browser fork appears nowhere in docs/, skills/, README.md, or CHANGELOG.md — it was only ever reachable by guessing. It also sat in the browser namespace behind a require-existing session policy for what is a local file copy.

This removes it from the local CLI and from the hosted browser catalog.

adapter override in hosted mode (second commit)

browser fork turned out to be hosted's only fork path. adapter override was never routed in hosted mode — src/hosted/runner.ts matched only source, path, and help — and cloud's forkSystemAdapterCommand had exactly one caller: the fork browser action. Removing browser fork alone would have taken hosted's fork capability away with no replacement.

So the second commit routes adapter override <site>/<command> in hosted mode to a new POST /v1/adapters/override. After both commits the command means the same thing in either mode: fork an installed upstream command into a private copy you can edit, refusing commands that are not installed upstream and commands already forked.

Storage differs, so the output does:

	local	hosted
writes	~/.webcmd/clis/<site>/<cmd>.js + .base copy	tenant-private adapter package
prints	yours: / base: paths	package: id + source: file
edit with	the path from adapter path	adapter source get|put
not upstream	"not provided by an installed plugin"	HOSTED_ADAPTER_FORK_SOURCE_INVALID
already forked	"an override already exists at …"	HOSTED_ADAPTER_FORK_ALREADY_EXISTS

Behaviour after

$ webcmd browser fork hackernews
error: 'webcmd browser fork' was removed. Use: webcmd adapter override <site>/<command>
# exit 2

$ webcmd browser click x
error: unknown command 'click'
# exit 2  (was 1)

Unknown browser subcommands now exit 2 (USAGE_ERROR) instead of 1.

Why fork stays in BROWSER_SUBCOMMAND_NAMES

rejectPositionalBrowserSessionArgv reads any unreserved token after browser as the retired positional-session grammar. Dropping fork from that set would answer webcmd browser fork hackernews with:

error: Browser sessions are root selectors. Use: webcmd --session fork browser hackernews

— worse than what we started with. Retired names stay listed so commander can report them properly. The set was already a superset of the declared subcommands (~40 names, 7 real); the comment now says that is deliberate instead of asking the next person to "keep in sync".

Also

Corrects the usage string in the adapter-shadow hint, which advertised adapter override <site> <command> (two positionals) for a command that takes one <site>/<command>.

Hosted impact

Hosted impact: C — webcmd-cloud change required
Trigger: 3.4 browser command surface (src/browser/command-catalog.ts)
Cloud files: src/default-adapters/source.ts:268, src/live-gates/cli-gates.ts:14
Why: cloud asserts the exact list ['bind','close','fork','init','run','snapshot','tabs','verify']
     and the count browserCommands: 8. Removing fork throws BrowserRunProtocolMismatchError.
Sequencing: land the cloud PR before `npm run bump:webcmd`.

The cloud side is agentrhq/webcmd-cloud#50, which serves POST /v1/adapters/override, drops the fork action, and re-pins the parity digests. Without it the hosted adapter override here 404s.

Order: merge this → bump PINNED_WEBCMD_SHA in cloud → merge webcmd-cloud#50.

Known window: between this release and the cloud deploy, hosted mode has no fork command — browser fork is gone and adapter override 404s until webcmd-cloud#50 ships. Accepted deliberately rather than splitting the PRs; keep the two merges close together.

Verification

• npm run typecheck — clean
• npm test — 5682 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated to this change
• npm run check:hosted-contract — passes; regenerated hosted-contract.json now lists 7 browser commands
• npm run check:codex-plugin — passes

Cross-repo, per §7 of .github/hosted-impact-review.md: packed this branch, installed it into webcmd-cloud, ran cloud's full suite against it — 1189 passed, 0 failed.

Follow-ups from the same audit (not in this PR)

• runCli() has no error handler, so adapter path, adapter source get|put, site fixture get, and session close <bad-id> dump raw Node stack traces
• webcmd adapter path <site>/<cmd> fails for every command that is not already a local override — the documented private-fork workflow
• Adapter error envelopes are always YAML, even under -f json
• --help -f yaml is missing on site, skills, session, external

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.