# Bridge features the native-browser bridge needs

Running tracker of ab fixes/features surfaced while building this bridge. Status as of 2026-06-19.

## Shipped
- **1.8.148** — WGC per-window recorder (`desktop_record_window_*`); foreground-steal fix;
  spawn-storm backoff; `send_files` honors `dest`; `pull_file` path resolution.
- **1.8.149** — control-API discovery contract (`ADOM_DIRECT_API_URL` env injected into spawned
  bridges; `~/.adom/direct-api-port` = `host:port`); `bridge_install` cache-lock retry.
- Containment **Phase 1** green-lit (kill-switch + `--safe-mode` + crash-loop guard + headroom gate).

## Open — first-class verbs to kill `shell_execute` inline-quoting friction
The #1 time-sink integrating this bridge is shell-quoting through JSON→bash→cmd→PowerShell.
Each verb below replaces a class of quoting pain hit repeatedly this session:
1. **`run_script`** {interpreter: powershell|cmd|node|python, body, args?, cwd?} → {stdout,stderr,exitCode}.
   ab writes `body` to a temp file + runs it. THE big one — I currently `send_files` a `.ps1` then
   `shell_execute -File` it as a workaround, every time.
2. **`read_file` / `write_file`** (text or base64, absolute path, resolved in ab's own context —
   fixes intermittent `%USERPROFILE%` non-expansion in `shell_execute`).
3. **`registry_get/set/delete`** (HKCU/HKLM) — replaces `reg query/add/delete` backslash-escaping
   (native-messaging host registration was painful + error-prone).
4. **`process_list`** {nameFilter?, pidFilter?} → [{pid,name,commandLine,parentPid,handles,memory}].
   Replaces `tasklist`/`wmic`/`Get-Process`; `wmic` CommandLine returned empty (privilege). Needed
   the whole incident debug. (Also feeds the Phase-2 watchdog.)
5. **`process_kill`** {pid|name}.
6. **`net_stats`** → {tcpTotal, listening, established, timeWait, ephemeralHeadroom, perPid:{...}}.
   Replaces `netstat`/`Get-NetTCPConnection` counting; identical to what the containment watchdog needs.
7. **`launch_process`** {path, args:[], env?, cwd?, window?} → {pid}. Args as an ARRAY (no quoted-string
   parsing); replaces `Start-Process` arg-array pain.

## Open — bridge lifecycle question
- Does ab keep an on-demand-spawned bridge **alive**, or tear it down when idle with no connected
  client? The `native-browser` bridge must **persist** so the Chrome-launched native host can dial it
  (host.json port). Observed: after an `nbrowser_*` call the bridge process is gone (node=0), which
  may be why the extension's host can't establish a steady connection. Need the contract.

## Bridge-side TODO (mine, not ab)
- Wire `ADOM_DIRECT_API_URL` env discovery (1.8.149 contract) into the bridge's `discoverAdDirectPort`.
- Harden the host singleton: a stale `host.pid` whose PID was **reused** by a non-host process caused
  every new host to exit (false positive). Verify the incumbent PID is actually a node/native-host
  process before deferring; otherwise take over.
