# OpenChrome v1.10.3

Release date: 2026-05-05

## Summary

v1.10.3 is a publish-ready patch release that brings the validated `develop`
line plus the `main` setup fixes into one release candidate.

The release focuses on making real-browser automation less fragile in the places
where users were most likely to get stuck:

- Chrome now launches **headed by default** for `--auto-launch`, with explicit
  headless opt-in for CI, Docker, and daemon-style environments.
- Login and auth-redirect flows are surfaced with structured guidance instead of
  being misreported as ordinary successful navigation.
- OpenChrome-owned Chrome processes are shut down and reaped more reliably,
  including after stdio EOF and ungraceful parent exits.
- User-driven Chrome closes are no longer treated like crashes that should be
  immediately relaunched.
- Launch mode is now explicit: automatic attach/spawn, attach-only, or isolated
  clean-room Chrome.
- Setup now supports OpenCode and resolves Claude CLI npm shims correctly on
  Windows.

This is still prepared as `1.10.3` because the package name, MCP tool surface,
and dependency set remain compatible, but it contains several operator-visible
runtime behavior improvements. Read the compatibility notes before publishing to
production agents.

---

## Why this release exists

After v1.10.2, the resource-cleanup path was much stronger, but user reports and
follow-up PRs exposed a second class of production issues:

1. headless auto-launch was too brittle for login-heavy and bot-protected sites,
2. auth redirects could look like healthy page loads to agents,
3. failed login submissions could still return `success: true`,
4. Chrome processes spawned by OpenChrome could survive shutdown paths that used
   synchronous `process.exit`,
5. closing a visible Chrome window could be interpreted as a crash and relaunched
   by the watchdog,
6. setup automation did not yet cover OpenCode and had Windows-specific Claude
   CLI resolution problems.

v1.10.3 addresses those issues as one release so users can publish from a single
branch that includes both the browser-runtime work and the setup-client fixes.

---

## Highlights

### 1. Auto-launched Chrome is headed by default

`openchrome serve --auto-launch` now starts a visible/headed Chrome by default.
Headless mode is still fully supported, but it is now explicit.

New and updated controls:

| Control | Meaning |
|---|---|
| `--headless` | Explicitly launch headless Chrome. |
| `OPENCHROME_HEADLESS=1` / `true` / `yes` | Explicitly launch headless Chrome. |
| `OPENCHROME_HEADLESS=0` / `false` / `no` | Explicitly launch headed Chrome. |
| `--visible` | Backward-compatible headed alias; retained as a no-op compatibility flag. |
| `--server-mode` | Still forces headless mode for daemon/server deployments. |

Why this matters:

- Many real websites treat headless Chrome differently.
- Login, SSO, CAPTCHA, CDN/WAF, and human-verification flows are more reliable
  in a visible browser.
- New users are less likely to hit silent hangs or anti-bot dead ends on their
  first run.

### 2. Auth redirects are now first-class tool outcomes

Navigation and validation now identify common auth handoff cases instead of
summarizing the login page as if it were the requested page.

Improvements include:

- `validate_page` now preserves `smartGoto` auth redirect information.
- Uppercase URL schemes such as `HTTPS://example.com` are normalized safely.
- `navigate` detects same-site login redirects such as `/protected -> /login`,
  not only cross-domain SSO redirects.
- Structured fields such as `authRedirectKind`, `authRedirectUrl`, and
  `recommendedNextAction` tell the agent when a human login step is needed.
- Ordinary same-site URLs such as `/sessions/123` are covered by negative tests
  so they are not mislabeled as auth handoffs.

This reduces unproductive retry loops where an agent repeatedly reopens a
protected page while still unauthenticated.

### 3. `fill_form` can now report strong login-failure signals

`fill_form` now includes a conservative, site-agnostic login outcome detector.
It only reports a login failure when there is a strong signal, such as:

- the submitted login form is still mounted at the same URL,
- the login form remains alongside an ARIA/error banner,
- the form submission itself failed.

Ambiguous cases such as SPA transitions, 2FA prompts, magic-link flows, and
same-page form unmounts remain `unknown` instead of being forced into false
failures.

### 4. Headed fallback preserves profile context

When a profile-scoped headless navigation escalates to Tier-3 headed fallback,
OpenChrome now keeps the profile identity intact.

Key changes:

- profile-scoped headed pages are registered under distinct
  `headed:profile:<directory>` workers,
- headed fallback is not routed through an existing port-bound headless profile
  worker,
- documentation now states that a successful headed login does not by itself
  prove headless reuse unless the persistent-profile handoff is verified.

This is important for workflows where users log in visibly and then expect later
same-profile automation to reuse the authenticated browser state.

### 5. OpenChrome-owned Chrome shutdown is more reliable

v1.10.3 adds ownership markers and synchronous shutdown helpers so Chrome
processes spawned by OpenChrome are not left behind across agent sessions.

Runtime lifecycle improvements:

- spawned Chrome instances are tagged with ownership metadata,
- stdio EOF triggers best-effort synchronous Chrome termination before exit,
- startup reaping cleans up owned survivors from ungraceful exits,
- session-resume tokens prevent cleanup from killing still-owned resumed
  sessions,
- marker scanning now covers the real marker locations used in production.

This reduces the accumulation of Chrome, Helper, Renderer, and GPU processes
after repeated Claude Code, Codex, or terminal-driven sessions.

### 6. User-driven close is no longer treated as an immediate crash restart

The Chrome process watchdog now classifies exits and suppresses relaunch after a
likely intentional close.

New behavior:

- exits are classified as intentional, clean, crash-like, or unknown,
- the watchdog honors a quiesce window after user-driven closes,
- `OPENCHROME_QUIESCE_MS` and `OPENCHROME_ANTIFLAP_SECONDS` correctly honor
  `0`,
- crash rate limiting remains available for true crash loops.

The practical result: when a user closes a visible Chrome window, OpenChrome no
longer makes the browser feel "uncloseable" by immediately respawning it.

### 7. Launch mode is explicit when auto-launch is enabled

OpenChrome now has a launch-mode resolver and cross-platform process detector.
The default keeps the existing behavior, while advanced users can opt into more
specific behavior.

| Mode | Behavior |
|---|---|
| `auto` | Probe the debug port, attach if Chrome is listening, otherwise spawn Chrome. |
| `attach` | Probe only; fail if Chrome is not already listening. |
| `isolated` | Skip probing and always spawn an OpenChrome-owned Chrome. |

Additional fixes in this area:

- isolated mode avoids pre-bound-port reuse mistakes,
- pending-process reuse paths are tagged correctly,
- kill-on-exit behavior is gated by ownership,
- the resolver has dedicated coverage for cross-platform process detection.

### 8. OpenCode setup support

The CLI now supports OpenCode as a setup/config target.

New setup capabilities:

- `openchrome setup --client opencode`
- `openchrome config --client opencode`
- official OpenCode `mcp.openchrome` local-server config shape,
- typed helpers for preserving sibling `mcp` entries,
- README quick-start and manual config guidance.

This closes the OpenCode setup gap without changing existing Claude, Cursor, or
manual MCP configuration behavior.

### 9. Claude setup works better on Windows

Windows npm global packages expose command shims as `.cmd` files. v1.10.3 adds a
shared Claude CLI resolver so setup and launch paths handle that correctly.

Covered paths:

- Claude version check,
- MCP removal,
- MCP add,
- existing launch/session code that invokes the Claude CLI.

macOS and Linux keep shell-free `claude` execution; Windows uses `claude.cmd`
with shell execution where the npm shim requires it.

### 10. CI and test stability follow-ups

Several release-blocking CI races were fixed while integrating the PR stack:

- health endpoint integration tests now use OS-assigned/randomized ports where
  needed,
- Windows SIGTERM assertions accept the platform's clean signaled termination
  shape,
- HTTP abort-on-disconnect tests destroy the assigned client socket directly,
- disconnect tests wait for real handler execution before asserting abort
  propagation,
- audit logger assertions poll for flushed entries instead of relying on fixed
  50ms sleeps,
- tab health monitor tests use wait-for polling instead of fixed sleeps.

These changes do not add product surface area, but they make the release branch
substantially safer to validate across the Node 18/20/22 and
Ubuntu/macOS/Windows CI matrix.

---

## Configuration and CLI changes

| Setting / flag | Status in v1.10.3 | Notes |
|---|---|---|
| `--headless` | New | Explicit opt-in to headless auto-launch. |
| `OPENCHROME_HEADLESS` | New | Env override for headed/headless resolution. |
| `--visible` | Retained | Backward-compatible headed alias. |
| `--server-mode` | Unchanged | Continues to force headless mode. |
| launch mode resolver | New | Supports `auto`, `attach`, and `isolated` launch policies. |
| `OPENCHROME_QUIESCE_MS` | Fixed | `0` is now honored. |
| `OPENCHROME_ANTIFLAP_SECONDS` | Fixed | `0` is now honored. |
| `openchrome setup --client opencode` | New | Writes OpenCode MCP config. |
| `openchrome config --client opencode` | New | Prints OpenCode MCP config. |

No new runtime dependencies were added.

---

## Compatibility notes

v1.10.3 is intended to remain package/API compatible with v1.10.2, but it has
operator-visible defaults:

- `--auto-launch` now defaults to headed Chrome. Use `--headless`,
  `OPENCHROME_HEADLESS=1`, or `--server-mode` for headless deployments.
- Visible/headed browser windows can now be intentionally closed without the
  watchdog immediately relaunching them.
- Auth redirects and strong login failures may now produce structured action
  required/error outcomes where older versions reported a generic successful
  page/tool result.
- OpenChrome-owned Chrome cleanup is stricter. If you rely on keeping spawned
  Chrome alive after MCP shutdown, use an attach/reuse flow rather than an
  OpenChrome-owned isolated launch.

---

## Operator-impact summary

If you are upgrading from v1.10.2 to v1.10.3, expect:

- more reliable first-run automation on login-heavy websites,
- clearer agent instructions when a human auth handoff is needed,
- fewer stale browser processes after repeated agent sessions,
- less surprising behavior when closing a visible Chrome window,
- explicit control over attach vs isolated Chrome launch semantics,
- easier setup for OpenCode users,
- fewer Windows-specific setup and CI surprises.

---

## Included pull requests

- #653 — Token-efficiency pass, `validate_page` macro, and Tier-1 console capture promotion.
- #654 — `computer` `screenshotFormat` option.
- #656 — README MseeP.ai listing badge.
- #662 — Windows-aware graceful-shutdown audit coverage.
- #663 — Tab health monitor wait-for polling test stabilization.
- #664 — HTTP abort-on-disconnect race hardening.
- #665 — Headed auto-launch default and explicit headless opt-in.
- #666 — Auth redirects and uppercase scheme normalization in `validate_page`.
- #667 — Synchronous Chrome shutdown and ownership-marker reaper.
- #668 — Exit classifier and watchdog quiesce for user-driven Chrome close.
- #669 — Generic login-failure detection in `fill_form`.
- #670 — Launch-mode resolver and cross-platform process detector.
- #674 — OpenCode MCP config helpers.
- #675 — OpenCode setup/config CLI support.
- #676 — Windows Claude CLI resolver for setup paths.
- #677 — Same-site login redirect detection and auth handoff guidance.
- #678 — Profile-context preservation during headed fallback.
- #679 — Documentation for headed login handoff limits.

---

## Verification performed for v1.10.3

Local verification performed during release preparation:

- `npm version 1.10.3 --no-git-tag-version`
- merge conflict resolution for the combined `main` + `develop` release line
- `git diff --check`
- `npm run build`
- `npm run lint` — passed with pre-existing warnings and 0 errors
- `npm test -- --runInBand` — 232 passed suites, 1 skipped suite, 3,702 passed
  tests, 86 skipped tests; Jest then reported an open-handle warning, so the
  already-completed process was terminated after the pass summary
- `npm pack --dry-run` — produced `openchrome-mcp-1.10.3.tgz` metadata, package
  size 1.1 MB, unpacked size 4.6 MB, 1,035 files

Before `npm publish`, run the publish command from this prepared tree and verify
that you are publishing `openchrome-mcp@1.10.3`.

---

## Upgrade recommendation

**Recommended upgrade:** yes, especially for users automating real sites with
login flows, users who prefer visible browser sessions by default, OpenCode
users, and Windows users running `openchrome setup --client claude`.
