Agent Upgrade Suite separates four planes:
- Distribution plane — manifest, system scanner, CLI/TUI/GUI installers, version pins, license material, ledger, doctor, upgrade, and uninstall.
- Harness plane — Claude Code marketplace plugin, DSH Cordis bundle, and Pi extension.
- Capability plane — independent Headroom, agent-browser, and Open Computer Use processes.
- Policy plane — controller ownership, approval equivalence, protected tokens, fail-open compression, and audit metadata.
No adapter reimplements a browser or desktop driver. Adapters translate native Harness calls into argv-safe subprocess calls or MCP requests.
The CLI, TUI, and local Web GUI all call scanSystem() and createInstallPlan(). The UI layers cannot submit arbitrary commands: they provide only validated Harness names, capability names, Claude scope, DeepSeek profile, and the runtime-install toggle. Execution always uses argv arrays with shell: false.
This is distribution policy, not a Claude-only feature. Claude Code, Pi Agent, and DeepSeek Harness all default to a visible compact Chrome for Testing session. The suite removes inherited auto-connect/CDP configuration, selects agent-browser's managed executable, and assigns a task-scoped profile and named session to each Harness. A suite-owned launcher injects one intact --window-size=<width>,<outer-height> argument directly into the Chrome process, bypassing agent-browser 0.34.0's comma-delimited argument parser so the first visible frame is compact. Before launching Chrome, the suite atomically merges the compact native window placement and translate.enabled=false into the managed task profile. This repairs profiles retained by a resumed task or an older plugin version while preserving unrelated browser state; an already-protected profile is left untouched. Headed Chrome 152 on macOS can discard that profile preference, so the launcher also writes the official TranslateEnabled=false policy to Chrome for Testing's dedicated com.google.ChromeForTesting policy domain before spawning Chrome. This domain does not affect the user's personal Google Chrome. The macOS launcher removes the legacy feature switches once the authoritative policy is present; other platforms retain the feature-level prevention.
On macOS the suite ships a universal (arm64 + x86_64) agent-browser 0.34.0 runtime with a narrow Apache-2.0 source modification: every Target.createTarget request serializes background: true. CDP otherwise defaults this field to false, focuses the new target, and can bring Chrome to the operating-system foreground. This fixes the first task page and every later tab new at the source of activation; it does not hide Chrome, resize it after launch, or restore focus after a flash. The exact source diff is retained in patches/agent-browser-0.34.0-background-target.patch, and the unmodified installed runtime remains available for non-macOS platforms and explicit overrides.
agent-browser 0.34.0 also hard-codes Page.bringToFront after changing its internal active target. That CDP command activates Chrome at the operating-system level and can cancel an in-progress IME composition before a focus-restoration poll can run. On macOS each adapter creates a hash-addressed, ad-hoc-signed runtime copy and replaces only that equal-length CDP method marker with an unsupported method. After every explicit tab creation, switch, or close, the adapter reads the authoritative ordered tab list and uses Chrome's AppleScript dictionary to set the matching window's active tab index while the application remains in the background. Before changing anything it matches the complete ordered URL set, and after selection it verifies the active URL. This keeps internal and visible tabs synchronized without activate, Page.bringToFront, synthetic clicks, or a foreground flash. An unexpected binary layout fails closed. AUS_BROWSER_PREVENT_FOCUS=0 is an explicit diagnostic escape hatch.
A first navigation waits out asynchronous Chrome session restoration, enforces one target tab, and then verifies the configured content viewport before returning. Missing managed browser runtime fails closed instead of falling back to the user's personal Chrome. The patched macOS runtime prevents activation at its source, so the proxy does not create a focus-restoration lease that could undo a user's deliberate click into the test browser. The older capture-and-conditional-restore guard remains only for explicit unpatched diagnostic mode. Each Harness owns a separate agent-browser socket directory in a short OS-temporary namespace derived from the suite-home hash and Harness code; this remains below macOS's Unix-socket path limit while preventing collisions. A scoped close --all therefore cannot affect personal agent-browser sessions or another Harness. The Claude sidecar atomically records its exact session and profile. After every completed response, Stop closes all sessions in the Claude-only socket directory, verifies both daemon PID files and processes using the recorded suite-owned profile, retries transient failures, and applies a targeted PID termination only if verification still shows ownership. The lease is cleared only after verification passes. SessionEnd remains a fallback. The profile survives within the task so cookies and storage can be reused without leaving a visible process alive. Headless mode requires explicit opt-in through installer preferences or AUS_BROWSER_VISIBLE=0.
Claude enforces the contract in its MCP proxy. Pi and DSH enforce it inside their native agent_browser adapters. Packaged adapter policy copies are compared byte-for-byte with config/policy.json during distribution validation.
Browser state has a task boundary in addition to a Harness boundary. Claude SessionStart closes a prior suite-owned session for startup and clear, while resume and compact retain the current task; SessionEnd closes the session. Pi and DSH close their prior suite session before the first Browser call in an adapter process, and long-running hosts can expose task transitions with AUS_TASK_ID. Cleanup is scoped to codexification-<harness> and never uses agent-browser's global close --all.
Task cleanup is backed by a first-navigation invariant. After open, the adapter treats its returned CDP targetId as authoritative, lists all tabs, closes every other target, and lists again. The Browser call fails closed unless exactly that one target remains. An explicit tab new transitions the current task into intentional multi-tab mode; accidental startup, restored, or stale tabs never do.
Authentication uses a separate expiring lease rather than weakening the normal task lifecycle. Strong runtime signals (login/OAuth/MFA URL segments, password/MFA controls, QR or CAPTCHA metadata) automatically create auth-handoffs/<harness>.json; an Agent-confirmed explicit tool covers weaker or unusual providers. The lease pins the suite-owned session/profile/socket/tab/target, records a non-secret resume goal, stores the exact profile-owned Chromium main PID, and generates a notification nonce. On macOS the suite first selects the single window matching the complete ordered URL sequence without activation, then launches the branded Codexification helper with open -g. The helper executes the system display notification command inside its app identity so macOS can use the bundled .icns; the displayed reminder contains no site or lease data. If the helper is unavailable, the adapter falls back to /usr/bin/osascript. The browser stays behind the user's current application. Only a later explicit user request invokes agent_upgrade_auth_open or agent_browser_auth_open; that path rereads the 0600 lease, verifies process/tab ownership, activates the exact profile-owned PID through AppKit, and verifies it became frontmost. A denied or suppressed notification never falls back to automatic activation. AUS_AUTH_PRESENTATION=foreground is the explicit compatibility opt-in; silent retains only Harness UI messaging. Claude UserPromptSubmit, Pi before_agent_start, and DeepSeek agent/pre-step are the equivalent wake-up seams: any next user input verifies process and tab ownership, reselects the tab without activation, and injects the resume goal. The Agent must explicitly resolve the lease as success, wait, or cancel. Turn cleanup retains only a live, unexpired waiting lease; session shutdown always clears it.
one distribution
├─ loop module ───── Headroom
├─ browser module ── agent-browser
└─ desktop module ── Open Computer Use
│
├─ Claude Code adapter: marketplace plugin + MCP + startup/provider integration
├─ Pi adapter: native tools + tool_result middleware
└─ DSH adapter: Cordis tools + tools/execute wrapper
Claude Code uses headroom init ... claude and a SessionStart ensure hook for provider-chain optimization. The DSH adapter changes only the model-facing content of a successful large result; its original structured value remains intact. The Pi adapter uses tool_result middleware and returns no patch when optimization is unsafe or unavailable.
- Browser session state remains owned by agent-browser.
- Desktop element mappings remain owned by Open Computer Use.
- Compression/retrieval state remains owned by Headroom.
- Installation state is written atomically to
${AGENT_UPGRADE_HOME:-~/.agent-upgrade-suite}/state.json.
The ledger stores the prior ledger entry to preserve an audit chain. It never stores browser cookies, screenshots, desktop trees, or model credentials.
- Missing sidecar: its MCP entry fails and
doctorreports the exact capability unavailable. - Headroom failure: original tool result continues unchanged.
- Browser failure: desktop control is not activated automatically.
- Desktop failure: no retry occurs through browser or shell.
- Invalid binary override: rejected unless it is an absolute executable path.
The control plane enforces minimum upstream versions during health checks. DSH peer dependencies are pinned to 0.1.0-rc.8 because the Harness is pre-stable. Widening any adapter range requires API review and an end-to-end fixture run.