# OpenChrome v1.12.5

Release date: 2026-05-25

## Summary

v1.12.5 is the first release cut after the OpenChrome direction was clarified in
SSOT issue #1359: **OpenChrome is a host-neutral MCP browser harness**. The
release keeps the package focused on real Chrome control, deterministic MCP
semantics, and portable evidence that can run under Codex, Claude Code, Hermes
Agent, OpenClaw, and other MCP-capable hosts without assuming a specific agent
runtime.

This patch integrates the full open PR stack that was pending after v1.12.4:

- startup Chrome lifecycle polish for real browser sessions;
- a state-graph and verified-memory pilot foundation;
- automatic skill/episode curation from successful task contracts;
- benchmark smoke and release-gate hardening that avoids overstated competitor
  claims;
- documentation/runbook updates for reproducible benchmark operation.

```
v1.12.4  ->  v1.12.5   (this release)

  12 PRs integrated (#1347 through #1358)
  1 host-neutral direction SSOT used as the merge gate (#1359)
  1 post-merge develop compatibility repair for lifecycle API reuse
  0 MCP tool removals
  0 npm publish performed by this release-prep step
```

---

## Upgrade

```bash
npm install -g openchrome-mcp@1.12.5
openchrome check
openchrome doctor
```

Fresh install:

```bash
npm install -g openchrome-mcp@latest
openchrome check
openchrome info
```

If you use OpenChrome as an MCP server, CLI, or embedded harness, this is a
drop-in patch upgrade from v1.12.4. The new pilot/benchmark pieces are additive
and are gated behind their existing commands, flags, and test contracts.

---

## Breaking changes

**None.** v1.12.5 does not remove or rename MCP tools, transports, CLI commands,
or public configuration options.

Operational notes:

- The release does not publish npm from the release-prep automation. Maintainers
  should run `npm publish` separately after reviewing the tag and release notes.
- Pilot memory/curator behavior remains conservative and evidence-backed. It is
  intended to build portable host-neutral memory artifacts, not host-specific
  automation shortcuts.
- Benchmark additions improve reproducibility and release gating; they should not
  be read as a claim that every full live competitor benchmark is now published.

---

## Direction: host-neutral MCP browser harness

Issue #1359 was used as the final product-direction gate for this release. The
merged work supports the same core position:

1. **Real browser control first.** OpenChrome should remain a reliable MCP layer
   over actual Chrome/CDP behavior rather than becoming a synthetic agent runner.
2. **Host neutrality.** Features should work from different MCP hosts and coding
   agents without depending on Codex-specific, Claude-specific, or local
   orchestration assumptions.
3. **Evidence over claims.** Benchmarks, memory, and replay artifacts must be
   backed by explicit contracts, traces, and failure modes.
4. **Portable learning loops.** Pilot memory should accrete reusable skills from
   verified task outcomes while keeping deterministic schemas and clear
   provenance.

---

## Browser lifecycle and CDP reliability

### Reuse the startup blank tab on first `createPage()` (#1347)

When OpenChrome launches an isolated Chrome instance, Chrome commonly starts
with an initial blank/new-tab target. v1.12.5 teaches the first `createPage()`
path to reuse that startup blank target when it is safe to do so. This avoids an
extra blank tab in isolated launch flows while preserving attach-mode safety.

The behavior is guarded so it does **not** reuse a target when:

- OpenChrome attached to a user-owned Chrome instance;
- a target is already indexed;
- multiple untracked page candidates exist;
- the candidate target is a real site rather than a blank/new-tab URL;
- a non-default browser context is requested;
- resolving the startup target fails.

A post-merge compatibility repair keeps this behavior on the existing public
`CDPClient.getChromeLifecycleMode()` API instead of adding a second private
lifecycle method. This preserves the same lifecycle ownership contract used by
session cleanup and other CDP flows.

---

## Pilot state graph and verified memory foundation

### State graph hash anchor (#1348)

The pilot stack now has a minimal state-graph anchor over task transaction
records. This gives later memory and replay features a stable way to name page
state without coupling to a particular host process.

### DOM skeleton v2 hashing (#1353)

A second state hash mode folds a bounded DOM skeleton into the page-state hash
while keeping the original v1 hash byte-stable. The v2 path is bounded and has
fallback protection so hashing cannot expand without limits.

### Pilot bootstrap lifecycle (#1354)

Pilot startup and shutdown hooks are now idempotent. Embedded server tests and
host integrations can start/stop the server repeatedly without leaking pilot
subscriptions or timers.

### Automatic skill extraction from successful contracts (#1355)

Successful contract-backed task runs can now feed a conservative curator runner
that extracts reusable skill candidates. This is the first step toward verified
memory that is created from actual task evidence rather than free-form agent
summaries.

### Sidecar-backed curator stats and failed-run evidence (#1356)

Curator sidecars now expose stats and record `ok=false` outcomes. Failed-run
artifacts are hardened so negative evidence is available to future selection and
review logic.

### Auto-recall on task start (#1357)

Pilot auto-recall can promote curated skills when a new task starts. The recall
path is gated before pilot imports so non-pilot users do not pay unnecessary
startup or dependency costs.

### Deterministic SKILL.md body generation (#1358)

Curated journal slices can be rendered into deterministic `SKILL.md` bodies.
Sensitive body-builder arguments are redacted so generated memory artifacts do
not accidentally persist credentials or private payloads.

### Selector confidence accretion

The auto-memory layer can accrete selector confidence from task contracts. Exact
selector decay was corrected so repeated evidence adjusts confidence
predictably.

---

## Benchmark and release-gate hardening

v1.12.5 integrates the benchmark PR ladder that was planned after v1.12.4. The
focus is still safe measurement infrastructure and reproducibility, not inflated
headline claims.

### Contract and smoke hardening

- Stress thresholds for loaded runners are stabilized.
- Competitor smoke provenance is pinned and aligned with `COMPETITORS.md`.
- Empty-payload smoke rows are rejected.
- Operator CDP sharing is documented for repeatable smoke runs.

### Measurement axes and live-run gates

- Non-LLM benchmark axes are measured before live promotion.
- Real-world corpus contracts are locked before live episodes.
- Live LLM samples are gated before native execution.
- Native competitors are routed without OpenChrome fallback.
- Real-world tasks are stressed through final postconditions.
- Full benchmark release gates derive task counts from the configured suite and
  perform preflight checks.

### Operator runbook

The smoke runbook now documents the six-way competitor matrix and clarifies CDP
setup expectations for operators. This reduces the chance of accidentally
mixing mock/scaffold evidence with live benchmark evidence.

---

## PRs included

| PR | Area | Result |
| --- | --- | --- |
| #1347 | CDP lifecycle | Reuse isolated startup NTP target on the first safe `createPage()` call. |
| #1348 | Pilot state graph | Add the initial transaction-record node hash anchor. |
| #1349 | Benchmark stack | Merge the full benchmark release-gate ladder into `develop`. |
| #1350 | Benchmark docs | Add the competitor smoke runbook. |
| #1351 | Benchmark pins | Align Playwright smoke registry pins with `COMPETITORS.md`. |
| #1352 | Benchmark sanity | Share operator CDP and reject empty-payload smoke rows. |
| #1353 | State graph v2 | Fold bounded DOM skeleton data into v2 hashes while preserving v1. |
| #1354 | Pilot lifecycle | Make bootstrap/cleanup idempotent. |
| #1355 | Curator | Auto-extract skills from successful contract evidence. |
| #1356 | Curator stats | Add sidecar-backed stats and failed-run logging. |
| #1357 | Auto-recall | Recall promoted curated skills when a task starts. |
| #1358 | Skill body builder | Generate deterministic `SKILL.md` bodies from journal slices. |

---

## Verification

Release preparation verified locally after all PR merges and the post-merge
compatibility repair:

```bash
gh pr list --state open --limit 100 --json number,title,url | jq length
npm run build
npm test -- --runInBand tests/cdp/create-page-startup-reuse.test.ts tests/integration/embedded-server.test.ts
npm run lint:tier
```

Additional pre-merge verification covered:

- pilot state graph, runtime events, curator, auto-memory, and harness flag test
  suites;
- benchmark competitor smoke test and benchmark build path;
- #1347 startup-tab reuse tests and build;
- #1348 embedded-server test after aligning the pilot cleanup mock.

At release-prep time, the latest `develop` push CI for the final compatibility
repair was queued on GitHub Actions, with no known failing local verification.
