Adom Bridge

The Adom team has been filing bridge bugs as wiki issues on the bridges' own pages, and it is working remarkably well. On the puppeteer bridge alone, in about two days, that channel produced: a CPU-pegging orphaned-renderer bug that froze a laptop and forced a reboot (#14, #21), a respawn failure that broke the bridge on every idle cycle (#15), a session-tracking bug where windows were open and drivable but reported as zero (#16), a repo-vs-release divergence that would have silently reverted five releases (#19), and a concurrency + readiness report that found a live blocking regression I had shipped hours earlier (#22).

Not one of those would have been found on a maintainer's machine. They came from real installs: different Chrome/Edge combinations, different AD versions, concurrent agents, a macOS box, a stalled download. John's framing, which I think is exactly right: we are about to launch publicly, and it is hard to test all possible scenarios locally, so we really do need callers to report the things we cannot see here.

The ask

Add a section to the Bridge SDK telling every bridge author to invite bug reports in the verb OUTPUT, naming their own wiki repo. This follows directly from the SDK's own first principle — "The AI almost never reads your on-disk SKILL.md. It ALWAYS reads the OUTPUT of a CLI call." The same logic that puts _hint in the response puts the reporting invitation there: the AI holding the failing response is the only party who has the evidence, and right then is the only moment it will act on it.

Proposed content below, tune as you like. Note it should land in all THREE copies of the page (README.md / SKILL.md / bridges-SDK.md) per the standing multi-copy rule.

Ask the AI to report bugs — in the OUTPUT, not the skill file

You cannot reproduce every environment. Your bridge runs on machines with browser installs, OS versions, security policies, hardware and concurrency patterns you will never have locally. The AI driving your bridge is standing on exactly that machine. It is the only party holding the failing response, and the moment it holds it is the only moment it will file anything.

So make the invitation part of your verb output, the same way _hint is.

Return a _reportIssues field naming YOUR page's issue list, with the exact commands:

{
  "success": false,
  "errorCode": "…",
  "_hint": "…",
  "_reportIssues": "THIS MAY BE A <BRIDGE> BUG — PLEASE REPORT IT. Check for a duplicate with `adom-wiki issue list adom/<your-slug>`, then file: `adom-wiki issue create adom/<your-slug> --title \"<one-line symptom>\" --category bug-report --body \"<what you ran, what you expected, what happened, the VERBATIM response JSON, the bridge version from bridge_list, and the OS>\"`. Reports from real machines are the only way this bridge gets correct. (An AD-core problem — the relay, bridge lifecycle, caller identity — belongs on adom/adom-desktop instead.)"
}

When to attach it. Throttle it, or the AI learns to skip it:

A line on every response is noise that trains the caller to ignore the field. A line on every failure is a bug report waiting to be filed.

Make it actionable, not a slogan. "Report bugs" produces nothing. Give the AI: the exact adom-wiki issue create command, your slug, a --category, and a list of what evidence to include (the verbatim response JSON and your bridge version are the two that make a report reproducible). Tell it to check for a duplicate first — a issue list call costs nothing and keeps your page clean.

Route the report to the repo that owns the code. Say explicitly, in the same string, that AD-core problems (the relay//command passthrough, spawn and provisioning, bridge lifecycle, caller identity) go to adom/adom-desktop, not to your page. Bridge authors get this wrong in the other direction too — see the "Filing issues against AD" section — and a misfiled issue is a note to yourself that the people who can fix it never read.

Let the user turn it off. Ship a settings toggle (pup uses browser_configure {reportIssues:"off"}) so a user who finds it noisy can silence it without losing functionality. Default it on: the cost is a few tokens on failures, and the benefit is the bug class you would otherwise ship to every user.

Reference implementation: the puppeteer bridge does this at its single sendJSON chokepoint (v1.9.95), so all ~155 response sites are covered by one place, and it never overwrites a _hint a handler already set.

One related suggestion, lower priority: bridge_list / bridge_info already resolve each bridge's skillPkg from its docs slug. If they also surfaced an issuesRef (adom/<slug>) or a ready reportIssueCommand, an AI could file against the correct repo for ANY bridge without that bridge having to hand-code its own slug, and third-party bridges would get the behavior for free.