Parallel multi-session is blocked by design — land the #1474 self-healing stack + make the opt-in broker path reachable (SSOT #1359 / audit #1457 alignment)

[shaun0927]

Investigation context: openchrome-mcp 1.12.7 (npm latest), Node v20.19.6, macOS (Darwin 25.3.0, arm64), MCP host = Claude Code with the global registration openchrome serve --auto-launch (stdio, default port 9222, default profile ~/.openchrome/profile). This issue consolidates a root-cause analysis with a direction/SSOT alignment review of the fixes already in flight, and catalogs additional wiring gaps found during the investigation. It is meant to sit under the SSOT (#1359) / audit (#1457) umbrella and to act as the tracking issue for the #1474 stack + follow-ups.

TL;DR

• Parallel multi-session is structurally blocked, by design — not a regression. Since Stabilize shared-profile controller ownership #1376 introduced the per-(port, userDataDir) controller-owner lock, N identically-registered sessions resolve to 1 working owner + (N−1) hard failures surfaced to the host as a bare Failed to reconnect to openchrome: -32000.
• This is the intended safety posture: Stabilize shared-profile controller ownership #1376 deliberately refuses a second direct controller because multiple direct controllers race on CDP target cleanup/reconnect (stale targets / MCP disconnects). The shared-owner replacement (--broker/--connect-broker, Introduce broker discovery and stdio proxy #1379) is opt-in by recorded decision (roadmap docs(roadmap): resolve SSOT open questions — graduation gate, VSL name, broker policy (#1457 PR-9) #1463 D3), so making the broker the default would contradict the SSOT.
• The genuine defects are therefore (a) the default path deadlocks and gives an opaque error, and (b) the opt-in shared path is built but under-wired/under-discoverable. The first is already addressed by the Parallel sessions deadlock on controller lock: half-zombie owner holds lock forever, host sees only -32000 #1474 stack (fix(reliability): health-aware controller lock — take over half-zombie owner instead of deadlocking (#1474) #1477 → fix(reliability): release controller lock on irrecoverable Chrome death (#1474) #1478 → feat(observability): surface DuplicateController remediation over MCP instead of bare -32000 (#1474) #1479, all OPEN, stacked, MERGEABLE). The second is the "primitives built, wiring/enforcement missing" pattern from the audit (Audit: SSOT (#1359) pillar gap analysis — primitives built, wiring/enforcement missing; develop↔main divergence #1457) and needs the follow-ups proposed below.
• Ask: land the Parallel sessions deadlock on controller lock: half-zombie owner holds lock forever, host sees only -32000 #1474 stack on develop, then close the remaining wiring/discoverability gaps (G1–G4) so concurrent hosts have a reachable, documented, portable path — without changing the opt-in default that D3 froze.

---

1. Symptom & deterministic repro

With ≥2 concurrent host sessions sharing one global registration (openchrome serve --auto-launch, same port+profile):

• Every session except the first reports, repeatedly and deterministically: Failed to reconnect to openchrome: -32000.
• It does not self-recover. If the winning owner becomes a half-zombie (MCP alive, Chrome/CDP dead), all sessions are starved indefinitely.

Captured on the investigation machine (one healthy owner holding the lock):

~/.openchrome/locks/port-9222-Users_<user>_.openchrome_profile.json
{ "pid": 24035, "version": "1.12.7", "port": 9222,
  "userDataDir": "/Users/<user>/.openchrome/profile",
  "lifecycleMode": "auto", "transportMode": "stdio", ... }

A second serve --auto-launch against the same key prints a rich remediation to stderr and exit(2)s before the MCP handshake — so the host discards it and the user only ever sees -32000.

---

2. Root cause (two-part)

1. Default serve --auto-launch is single-owner-per-(port, userDataDir) with no broker auto-attach fallback. acquireControllerLock() (src/utils/controller-lock.ts) creates ~/.openchrome/locks/<key>.json with openSync(..., 'wx'); the second process gets EEXIST → DuplicateControllerError → refuse to start. With N identical registrations, N−1 are structurally guaranteed to fail.
2. The lock treats "owner PID alive" as "owner healthy." No CDP-reachability probe, no heartbeat/lease/TTL on the default owner. A half-zombie owner holds the lock forever; the orphaned managed Chrome (and Tier-3 headed-fallback children on basePort+100, e.g. 9322, plus headless 9666) can linger un-reaped.

Code anchors: src/utils/controller-lock.ts, src/utils/duplicate-controller-diagnostics.ts, src/chrome/launcher.ts (SingletonLock), src/chrome/process-watchdog.ts, src/chrome/headed-fallback.ts, src/chrome/auto-connect.ts (note: explicitly refuses to attach to the managed ~/.openchrome/profile, so the managed profile always takes launch mode).

---

3. Why this is by-design (not a regression)

• Stabilize shared-profile controller ownership #1376 "Stabilize shared-profile controller ownership" (merged 2026-05-27) added the owner lock on purpose: "independent MCP processes pointing at the same (port, userDataDir) can race on target cleanup/reconnect and cause stale sessions or MCP disconnects." The lock converts flaky concurrent into deterministic single-owner.
• The in-code remediation is explicit: "Refusing to start a second direct controller … use the future broker/shared-owner topology when available."
• Introduce broker discovery and stdio proxy #1379 shipped that topology's foundation (--broker HTTP owner + --connect-broker stdio proxy, discovery under ~/.openchrome/brokers).
• Roadmap docs(roadmap): resolve SSOT open questions — graduation gate, VSL name, broker policy (#1457 PR-9) #1463 D3 (broker policy) records the shipped decision: broker is opt-in (--broker/--connect-broker), discovery via ~/.openchrome/brokers, sliding idle-TTL lease expiry (PR-3 feat(session): sliding idle-TTL target leases — reclaim crashed-client tabs (#1457 PR-3) #1460; default session exempt), multi-tenant requires explicit trust config.

Implication for the fix direction: the SSOT-aligned move is not "make broker the default." It is "make the default single-owner path self-healing + observable, and make the opt-in broker path reachable, portable, and documented."

---

4. The fix already in flight — #1474 stack

Issue #1474 ("Parallel sessions deadlock on controller lock; host sees only -32000", OPEN) is the canonical bug. Three stacked PRs (all OPEN, all MERGEABLE, base develop):

PR	Role	Base	What it does	Self-sufficiency
#1477	1/3 — reactive	develop	acquireControllerLockWithHealthCheck(): on live-owner collision, probe owner CDP /json/version; if unreachable past a boot-grace window, atomically take over the stale lock. Healthy owner never evicted. src/index.ts awaits it on --auto-launch.	"This PR alone closes the reported deadlock."
#1478	2/3 — proactive	fix/1474-controller-lock-health-aware (#1477)	owner-self-release.ts: on terminal watchdog-exhausted, release the lock and exit 70 so the host respawns a fresh owner. Anti-flap: only the terminal event surrenders ownership; chrome-died/single relaunch-failed do not.	Complements #1477
#1479	3/3 — observability	fix/1474-owner-self-release (#1478)	duplicate-controller-error-server.ts: a degraded stdio responder that completes initialize then surfaces remediation via portable MCP surfaces — notifications/message, a diagnostic tool, and a structured JSON-RPC error (data: port, profile, owner pid, lock path, ordered remediations) — instead of bare -32000.	Independent value

Stacking/merge order: #1477 → #1478 → #1479.

---

5. Alignment analysis vs SSOT #1359 / audit #1457 / roadmap #1463

SSOT #1359 = "host-neutral MCP browser harness for real Chrome; the MCP protocol is the product boundary; no hidden host-specific behavior." Audit #1457 = "direction adherence high; achievement gated by primitives built, wiring/enforcement missing; + develop↔main divergence (Pillar B stack on main, absent on develop)."

PR / item	Aligned?	Rationale against direction & SSOT
#1477 health-aware takeover	✅ Strong	Turns Pillar-B safety primitive (controller-lock) from advisory/deadlock-prone into enforcing + self-healing. Exactly the audit's "wire the primitive to the real call path" remedy. Preserves single-owner invariant (no split-brain via boot-grace + multi-probe). Does not change the opt-in default → respects D3.
#1478 owner self-release	✅ Strong	Same Pillar-B reliability axis; makes lifecycle facts truthful (a dead owner stops claiming ownership). Anti-flap guard keeps it conservative. No new host-specific behavior.
#1479 MCP-visible remediation	✅ Strong + directly SSOT-core	Moves the failure story from discarded stderr onto portable MCP surfaces (notification + tool + structured error data). This is the literal product boundary of #1359: "a feature belongs in OpenChrome only if exposed through portable MCP surfaces." Best alignment of the three.
Keeping broker opt-in (no default change)	✅ Required	D3 froze broker as opt-in; default session exempt from TTL. Auto-electing broker in the default path would contradict the recorded decision and the "no hidden behavior" non-identity.
Targeting develop	✅ Correct, but verify divergence	#1457 M0 flagged the Pillar-B stack as main-only / absent on develop; back-merge #1455 has since merged (2026-05-29). Confirm src/utils/controller-lock.ts et al. now exist on develop so the stack rebases cleanly and doesn't reintroduce divergence.

Verdict: the #1474 stack is on-direction and SSOT-consistent. It fixes (a) the deadlock and (b) the observability gap without disturbing the opt-in broker policy. It is the "enforcement/wiring" the audit asked for, applied to Pillar B. Recommendation: merge #1477 → #1478 → #1479 as-is.

---

6. Remaining gaps NOT covered by the #1474 stack (newly found)

The #1474 stack makes the default path safe and legible, and auto-recovers a dead owner — but it still leaves (N−1) concurrent sessions non-functional (they get a clear error instead of a cryptic one). For hosts that genuinely want concurrent sessions, the opt-in broker path must be reachable, portable, and documented. These are "wiring/enforcement missing" items in the #1457 sense:

• G1 — Broker flags are hidden in the user-facing CLI (discoverability/Pillar A). node dist/index.js serve --help lists --broker/--connect-broker, but the bin wrapper openchrome serve --help does not (the --pilot, --hybrid, etc. show, broker does not). The one documented escape hatch is invisible at the surface most operators read. → Reconcile the two help surfaces.
• G2 — Orphan Chrome leak on owner death (Pillar B isolation/cleanup). When an owner dies/half-zombies, Tier-3 headed-fallback children (basePort+100, e.g. 9322) and headless instances (e.g. 9666) can survive un-reaped; reap-orphans does not collect them. → Extend reaper + watchdog teardown to cover fallback/headless descendants and verify owner-self-release (fix(reliability): release controller lock on irrecoverable Chrome death (#1474) #1478) triggers full child cleanup.
• G3 — No portable host-registration recipe for concurrent sharing (Pillar A). Today an operator must hand-author: one serve --auto-launch --broker owner first, then switch every session's registration to serve --connect-broker. --connect-broker exit(2)s if no broker is published (no auto-start), and the chicken-and-egg/SPOF are undocumented. → Have mcp-client-config emit a broker-topology registration (owner + client) and document the recipe in README; surface the "no broker found — start one with …" hint over MCP (per feat(observability): surface DuplicateController remediation over MCP instead of bare -32000 (#1474) #1479's pattern), not just stderr.
• G4 — (Optional) explicit opt-in convenience auto-elect — must NOT change the default. A first-session-becomes-owner / others-auto-connect-as-clients mode would remove the manual ordering for concurrent users, but per D3 it can only ship as an explicit opt-in (e.g. --auto-broker), never as the default --auto-launch behavior. Gate behind a flag + trust config; lease/TTL already exists (feat(session): sliding idle-TTL target leases — reclaim crashed-client tabs (#1457 PR-3) #1460). Treat as a separate proposal, not part of the Parallel sessions deadlock on controller lock: half-zombie owner holds lock forever, host sees only -32000 #1474 stack.

---

7. Proposed action plan (phased)

• Phase 1 — land the deadlock/observability fix (no behavior-policy change). Review/merge fix(reliability): health-aware controller lock — take over half-zombie owner instead of deadlocking (#1474) #1477 → fix(reliability): release controller lock on irrecoverable Chrome death (#1474) #1478 → feat(observability): surface DuplicateController remediation over MCP instead of bare -32000 (#1474) #1479 onto develop. Confirm post-chore(release): back-merge main into develop (reconcile divergence) #1455 develop carries the controller-lock/broker primitives so the stack applies cleanly. Outcome: no more permanent deadlock; no more bare -32000; half-zombie owners auto-recover.
• Phase 2 — make the opt-in broker path reachable & portable. G1 (help parity) + G3 (generated broker-topology registration + README recipe + MCP-surfaced "no broker" hint). Outcome: concurrent hosts have a documented, copy-pasteable path that stays within the MCP product boundary.
• Phase 3 — isolation/cleanup hardening. G2 (reap fallback/headless descendants on owner death; verify via fix(reliability): release controller lock on irrecoverable Chrome death (#1474) #1478 path). Outcome: no orphan-Chrome accumulation across owner churn.
• Phase 4 (optional, separate decision) — explicit --auto-broker opt-in. G4, only if D3 is revisited to permit a convenience mode; ship behind a flag + trust config, default unchanged.

---

8. Acceptance criteria

• With the default registration and ≥3 concurrent sessions, a host receives a structured, actionable MCP error (not bare -32000) on the non-owner sessions. (feat(observability): surface DuplicateController remediation over MCP instead of bare -32000 (#1474) #1479)
• Killing the owner's Chrome (half-zombie) lets another session acquire ownership within the grace window with no manual lock deletion. (fix(reliability): health-aware controller lock — take over half-zombie owner instead of deadlocking (#1474) #1477 + fix(reliability): release controller lock on irrecoverable Chrome death (#1474) #1478)
• A genuinely healthy owner is never evicted under contention (no split-brain/flap). (fix(reliability): health-aware controller lock — take over half-zombie owner instead of deadlocking (#1474) #1477 guardrails)
• openchrome serve --help (bin) lists --broker/--connect-broker. (G1)
• Documented broker-topology registration enables ≥2 sessions to operate concurrently against one shared Chrome via --connect-broker. (G3)
• After owner death, no orphan Chrome (managed, headed-fallback, or headless) remains. (G2)
• Default --auto-launch behavior and broker opt-in policy are unchanged unless an explicit new flag is introduced. (D3 compliance)

---

9. Evidence appendix (investigation machine)

• Live owner lock: ~/.openchrome/locks/port-9222-...profile.json → pid 24035, v1.12.7, stdio/auto.
• Managed Chrome: pid 95492 --remote-debugging-port=9222 --user-data-dir=~/.openchrome/profile (+ watchdog pid 95493 that SIGKILLs Chrome on owner death).
• Orphans observed: pid 805 (headed-fallback, port 9322), pid 32230 (--headless=new, port 9666) — un-reaped (relates to G2).
• auto-connect.ts boundary confirmed: refuses to attach to the managed profile → managed profile always launch-mode (relevant to why no implicit sharing exists today).

Refs: SSOT #1359 · audit #1457 · back-merge #1455 · controller-lock #1376 · diagnostics #1377 · broker foundation #1379 · lease TTL #1460 · roadmap/D3 #1463 · deadlock bug #1474 · fixes #1477/#1478/#1479.

[shaun0927]

Decision: root regression pinned + finalized PR program

Following the investigation, this comment records (1) the exact regression, (2) the chosen direction, and (3) the finalized PR count and scope.

1. Root regression — confirmed by git archaeology

• Parallel multi-session used to work: pre-regression, serve --auto-launch ran the launcher in auto mode, which probed waitForDebugPort(port, 5000) and, when Chrome already held the port, attached to the existing Chrome. N sessions ⇒ first launches Chrome on 9222, the rest all attach to the same Chrome over CDP. It worked, but every process believed it owned lifecycle/cleanup/reconnect → stale targets, accidental tab closure, reconnect races (the motivation in feat: prevent duplicate OpenChrome controllers for the same Chrome profile #1367).
• Regression PR: Stabilize shared-profile controller ownership #1376 (feat/1367-duplicate-controller-lock, closes feat: prevent duplicate OpenChrome controllers for the same Chrome profile #1367), commit 664ffa36 "Prevent duplicate direct Chrome controllers" (merged 2026-05-27). It inserted, into the --auto-launch path, before the launcher's attach-to-existing logic:

  controllerLock = acquireControllerLock({ port, userDataDir, ... })
    → DuplicateControllerError → console.error(...) → process.exit(2)
  

  The parent commit 664ffa36^ had no such guard. So Stabilize shared-profile controller ownership #1376 converted "flaky concurrent auto-attach" into "deterministic single-owner; second session refused," and—because the broker replacement was left opt-in/un-wired—surfaced to hosts as a bare -32000.

This is working-as-designed for #1367's safety goal, but it is the precise point where the previously-working parallel behavior regressed.

2. Chosen direction — auto-elect coordinated sharing (option ②)

#1367 itself states the intended end-state: "Multiple sessions may share a Chrome/profile, but they must do so through one coordinated owner/broker." The fix is therefore not to revert the lock, but to wire the elected owner + auto-connecting clients so coordinated sharing happens by default:

serve --auto-launch:
  acquire controller lock
    ├─ win            → become broker OWNER (run Chrome+watchdog+lifecycle, publish broker discovery)
    ├─ live healthy   → auto-switch to broker CLIENT (--connect-broker proxy), instead of exit(2)
    └─ half-zombie    → take over the stale lock (#1477) and promote to owner

Clients own no lifecycle, so #1367's races cannot recur; sharing is restored without manual broker setup. The only policy tension is roadmap D3 ("broker is opt-in"); this is reconciled in PR S1 by recording auto-elect as the SSOT end-state of #1359/#1367 (coordinated sharing), with --allow-unsafe-shared-attach remaining the only racy direct-attach escape.

3. Finalized PR program — 9 PRs total = 3 existing (prerequisite) + 6 new

Prerequisite — already open, merge first (the #1474 stack), no new authoring:

PR	Scope	Base / stack
#1477	health-aware lock: take over half-zombie owner	develop
#1478	owner self-release on terminal watchdog-exhausted	on #1477
#1479	surface DuplicateController remediation over MCP	on #1478

New — to author (6). Group S is git-stacked on #1479; group I is independent on develop.

#	Title (scope)	Base / dep	Key files	Size
S1	docs(roadmap): amend D3 to sanction default auto-elect coordinated sharing; keep --connect-broker manual + unsafe-attach escape	develop; gates S2–S4	docs/roadmap/*	XS
S2	feat(broker): elected --auto-launch owner auto-publishes broker (HTTP daemon + ~/.openchrome/brokers discovery)	on #1479; needs S1	src/index.ts, src/broker/{discovery,lifecycle}.ts	M
S3	feat(broker): auto-elect clients — on healthy-owner collision, proxy via BrokerProxyStdioBridge instead of exit(2) (this PR restores parallel)	on S2	src/index.ts, src/transports/broker-proxy.ts, src/utils/controller-lock.ts	M
S4	feat(reliability): client re-election on broker/owner death (kills the SPOF) — loser re-acquires lock and promotes	on S3; uses #1477/#1478	src/chrome/owner-self-release.ts, src/utils/controller-lock.ts, src/index.ts	M
I1	fix(cli)+docs: expose --broker/--connect-broker in bin serve --help (G1) + emit broker topology in mcp-client-config + README recipe (G3)	develop	src/index.ts/help reg, src/cli/mcp-client-config.ts, README*	S
I2	fix(isolation): reap headed-fallback/headless descendants (9322/9666) on owner teardown (G2)	develop	src/tools/reap-orphans.ts, src/chrome/{headed-fallback,process-watchdog}.ts	S

Dependency summary: #1477→#1478→#1479 → S1 (policy gate) → S2→S3→S4; I1, I2 land any time in parallel.
"Stable parallel" is reached at S3 (functional) and hardened at S4 (no SPOF). I1/I2 are quality/discoverability/cleanup.

Acceptance (program-level)

• ≥3 concurrent default-registered sessions all drive Chrome simultaneously via one auto-elected owner (S2+S3).
• Closing/killing the owner session promotes a client to owner within the grace window; survivors keep working (S4, on fix(reliability): health-aware controller lock — take over half-zombie owner instead of deadlocking (#1474) #1477/fix(reliability): release controller lock on irrecoverable Chrome death (#1474) #1478).
• A healthy owner is never evicted; no split-brain/flap (fix(reliability): health-aware controller lock — take over half-zombie owner instead of deadlocking (#1474) #1477 guardrails).
• openchrome serve --help lists broker flags; generated config can emit the topology (I1).
• No orphan Chrome (managed / headed-fallback / headless) after owner churn (I2).
• Default behavior change is sanctioned by an explicit D3 amendment (S1) — no hidden host-specific behavior (SSOT SSOT: OpenChrome as a host-neutral MCP browser harness #1359 compliance).

Regression refs: #1376 / 664ffa36 / closes #1367. Direction refs: SSOT #1359 · audit #1457 · roadmap-D3 #1463 · lease-TTL #1460 · deadlock #1474 (#1477/#1478/#1479).

[shaun0927]

✅ PR program opened — all 6 new PRs up, builds + tests + end-to-end smokes green

The full #1480 program is implemented and pushed. Existing prerequisite stack
(#1477 → #1478 → #1479) merges first; the 6 new PRs:

PR	Scope	Base	Validation
#1481 S1	docs: D3 Q1′ amendment (default auto-elect, regression pinned to #1376/664ffa36)	develop	docs
#1482 I1	cli: expose --broker/--connect-broker in serve --help + allowUnknownOption	develop	build:cli ✓, help ✓
#1483 I2	chrome: ownership marker on headed-fallback so the reaper reclaims it	develop	build ✓, headed tests 61→64 ✓
#1484 S2	broker: lock winner auto-elects as broker owner (transport both, publish, loopback-auth fix)	feat/1474-duplicate-controller-mcp-error (#1479)	build ✓, +14 unit, broker/lock 23 ✓, owner smoke ✓
#1485 S3	broker: loser attaches as --connect-broker client instead of failing fast	S2 (#1484)	build ✓, 58 ✓, 2-process smoke ✓
#1486 S4	broker: re-elect on owner death (removes SPOF)	S3 (#1485)	build ✓, +5 unit, 78 ✓, kill-owner smoke ✓

Proven end-to-end (real processes, opt-in --auto-elect)

# owner
[openchrome] Broker metadata: http://127.0.0.1:9731/mcp (auto-elected)
# second session, same (port, profile), while owner alive
[openchrome] Refusing to start a second direct controller ...
[openchrome] auto-elect: attaching as broker client -> http://127.0.0.1:9731/mcp   # was -32000 on develop
# kill the owner
[openchrome] auto-elect: broker owner is gone; re-electing (host will respawn this session)

Safety / SSOT

• All behavior is gated behind opt-in --auto-elect / OPENCHROME_AUTO_ELECT=1;
  with it unset, the touched paths are byte-for-byte the prior fail-fast default
  (zero blast radius).
• Exactly one direct CDP owner per (port, userDataDir) is preserved — surplus
  sessions are coordinated clients, never independent controllers (feat: prevent duplicate OpenChrome controllers for the same Chrome profile #1367 invariant).
• The default-flip of --auto-elect is intentionally not in these PRs; it
  stays a separate, deliberate decision once the stack lands and the multi-session
  smoke is reproduced in CI (D3 Q1′ Status).

Suggested merge order

#1482, #1483 (independent, develop) any time · #1481 (policy gate) · then
#1477 → #1478 → #1479 → #1484 → #1485 → #1486.

S4 follow-up note

S4's host-respawn re-election was validated by observing the client detect owner
death and exit for re-election; the respawn→new-owner hop is host-driven and is
worth a CI integration test that scripts a fake host respawn.