# OpenChrome v1.10.2

Release date: 2026-04-23

## Summary

v1.10.2 is a **patch release** focused on long-running process hygiene and
steady-state resource usage.

This release pulls the validated `develop`-line runtime cleanup into the next
publishable package and adds three follow-up resource fixes that were still open
on the upstream tracker:

- stdio parent-death self-exit to prevent orphaned `openchrome-mcp` servers
- bounded cookie caches to cap stale per-instance heap growth
- health endpoint gating so stdio instances stop binding an unused HTTP socket
- idle-adaptive background monitoring plus an opt-in idle-timeout exit path

The net effect is a release that is quieter when idle, cheaper to keep around
for long sessions, and less likely to leave behind stray OpenChrome/Chrome
processes after abrupt client shutdown.

---

## Why this patch release exists

After v1.10.1, the codebase still had a few long-running-instance problems on
its integration branch:

1. stdio-launched servers could outlive the MCP client chain that created them,
2. cookie-bridge caches could retain stale entries for too long,
3. every stdio instance still bound a health listener that no stdio client used,
4. several self-healing monitors kept polling at full rate even after long idle
   periods, and there was still no operator-controlled "exit when truly idle"
   mode.

v1.10.2 addresses those gaps without changing the public MCP surface or adding
new runtime dependencies.

---

## Highlights

### 1. Stdio parent death now tears down the server instead of leaving it orphaned

OpenChrome now includes the parent-process watcher work from the post-v1.10.1
`develop` line.

In stdio mode, the server watches its launching parent chain and exits cleanly
when that parent disappears without closing the stdio pipe. This closes the
common orphan path where an editor, agent host, tmux pane, or wrapper crashes
and leaves `openchrome-mcp` running indefinitely.

Operationally:

- enabled by default in stdio mode
- skipped in `--transport http` and `--transport both`
- can be disabled with `OPENCHROME_PPID_WATCH=0`
- interval remains configurable with `OPENCHROME_PPID_WATCH_INTERVAL_MS`

This feature hardens the **MCP-client → openchrome** shutdown direction, while
OpenChrome's existing exit hooks continue to handle the **openchrome → Chrome**
cleanup direction.

### 2. Cookie caches are now bounded and stale entries are purged eagerly

`CDPClient` previously held two process-lifetime cookie caches that only shrank
reliably on target-destroy events.

v1.10.2 now:

- caps `cookieSourceCache` at 64 entries
- caps `cookieDataCache` at 16 entries
- deletes TTL-expired entries on read miss instead of leaving them resident
- preserves the existing TTL and `onTargetDestroyed` behavior

This keeps long-running cookie-bridge workloads from accumulating stale cookie
arrays indefinitely and reduces memory growth without changing the public API.

### 3. Stdio mode no longer binds the health endpoint by default

The `/health` and `/metrics` listener is now gated by transport mode.

New default behavior:

- `--transport stdio` → health endpoint **off** by default
- `--transport http` / `both` → health endpoint **on** by default

Overrides:

- `OPENCHROME_HEALTH_ENDPOINT=1` forces it on
- `OPENCHROME_HEALTH_ENDPOINT=0` forces it off

This removes one unnecessary listening socket and its associated server object
from every stdio instance while preserving daemon-mode observability.

### 4. Self-healing monitors now relax when the server has been quiet

Several long-lived monitors now switch from active cadence to relaxed cadence
when OpenChrome has been quiet for a full idle window.

Affected areas include:

- event loop watchdog
- Chrome process watchdog
- tab health probing
- Chrome RSS monitor
- disk monitor
- browser state snapshots
- session-state persistence debounce

The release fixes the integration blockers that were still present on the draft
idle-adaptive branch:

- monitors now treat process startup as the initial active edge, so they do not
  fall into idle cadence immediately on boot
- legacy timer tests were migrated to the new timeout-chain scheduling model
- the shutdown path now safely handles multiple exit triggers through a single
  reentrancy guard

### 5. OpenChrome can now self-exit when truly idle — but only when you opt in

A new CLI/env-controlled idle timeout is available:

- `--idle-timeout=<duration>`
- `OPENCHROME_IDLE_TIMEOUT_MS=<ms>`

When configured, OpenChrome exits with code 0 only if:

- the idle window has elapsed, and
- there are zero active sessions

This is disabled by default. It is meant for operators who want ephemeral agent
sessions to clean themselves up after inactivity without turning daemon-mode
installs into short-lived processes by accident.

---

## Configuration changes

| Setting | Default | Purpose |
|---|---|---|
| `OPENCHROME_PPID_WATCH` | `1` in stdio mode | Disable with `0` to turn off the parent watcher. |
| `OPENCHROME_PPID_WATCH_INTERVAL_MS` | `2000` | Parent watcher poll interval. |
| `OPENCHROME_HEALTH_ENDPOINT` | transport-dependent | `1`/`true` forces on, `0`/`false` forces off. |
| `OPENCHROME_IDLE_ADAPTIVE` | `1` | Set to `0` to keep all adaptive monitors at active cadence. |
| `OPENCHROME_IDLE_TIMEOUT_MS` | unset | Opt-in idle self-exit window in milliseconds. |
| `--idle-timeout=<duration>` | unset | Opt-in idle self-exit window (`500ms`, `90s`, `30m`, `1h`). |

No new dependencies were added.

---

## Operator-impact summary

If you are upgrading from v1.10.1 to v1.10.2, the most important practical
changes are:

- fewer orphaned stdio OpenChrome processes after host/editor crashes
- bounded memory growth for long-running cookie-copy workflows
- one less listening socket per stdio instance
- less background polling after OpenChrome has been quiet for several minutes
- an optional way to auto-exit truly idle agent sessions

---

## Compatibility notes

v1.10.2 is intended as a backward-compatible patch release.

Notable behavior changes to be aware of:

- stdio mode no longer exposes the health endpoint unless you opt in
- idle-adaptive monitoring is enabled by default, but only changes polling
  cadence after a full quiet window; it does not remove the monitors
- idle-timeout is entirely opt-in and does nothing unless configured

HTTP and dual-transport daemon use cases keep their existing health/metrics
behavior by default.

---

## Verification performed for v1.10.2

The integrated release branch was validated with fresh repository checks.

### Build / static checks
- `npm run lint`
- `npm run build`

### Full regression verification
- `npm test -- --runInBand`

### Key targeted coverage added/validated in this release
- `tests/cdp/cookie-cache.test.ts`
- `tests/utils/health-endpoint-gating.test.ts`
- `tests/integration/health-endpoint-gating.test.ts`
- `tests/integration/idle-adaptive-monitoring.test.ts`
- `tests/integration/idle-timeout.test.ts`
- `tests/integration/shutdown-reentrancy.test.ts`

---

## Upgrade recommendation

**Recommended upgrade:** yes, especially for users who keep many stdio sessions
alive across a workday or who have seen orphaned OpenChrome/Chrome processes
after abrupt host shutdown.
