orca/docs/renderer-memory-profile-2026-06-01.md

# Renderer Memory Profile, 2026-06-01

## Scope

This profile investigated high Orca renderer memory while working in
`/Users/nwparker/orca/workspaces/orca/goal`. The user suspected the browser
might not actually have an open tab, so the investigation checked browser,
renderer, terminal, and Resource Usage attribution paths separately.

## Live Evidence

- Orca runtime was reachable through the packaged CLI fallback. The public
  `/usr/local/bin/orca` shim pointed at a removed development app path, so it
  failed before contacting the runtime.
- `orca tab list --worktree all --json` returned `tabs: []`. There were no live
  Orca browser tabs in the measured session.
- The live packaged app had one renderer process and no separate browser guest
  renderer process. A later `ps` sample showed:
  - main process: 390 MB RSS
  - renderer process: 460 MB RSS, about 40 percent CPU
  - GPU process: 145 MB RSS
  - network service: 59 MB RSS
  - audio service: 48 MB RSS
- `sample` on the renderer showed V8, IPC, and deserialization stacks while the
  renderer was busy. It did not show browser guest activity.
- `vmmap -summary` on the renderer showed about 218 MB physical footprint and a
  373 MB peak, while total resident accounting was about 1.7 GB. Most of that
  larger number was shared Electron/Chromium mappings, especially read-only
  library mappings.
- `orca terminal list --worktree active --json` showed the active Codex terminal
  preview retaining repeated status redraw fragments such as repeated
  `Working` text. The retained terminal tail buffers were bounded, but the
  text normalization path was treating redraw controls as append-only text.

## Findings

1. Browser tabs were not the live-session memory source. The session had no
   browser tabs and no browser guest renderer process.
2. The browser-pane retention fix is still useful: inactive worktree browser
   webviews are now unmounted so Chromium can release guest renderers. Browser
   state remains in Orca, and automation-visible webviews stay mounted so
   agent-browser can keep driving them.
3. Resource Usage was using `app.getAppMetrics().memory.workingSetSize` for
   Orca app buckets. On macOS this can count large shared Electron/Chromium
   mappings and make the renderer look much larger than its private footprint.
4. The active terminal path was producing noisy previews from TUI redraws. This
   explains the high active renderer churn observed during the profile, even
   though the terminal memory buffers were already capped.

## Changes Made

- Browser panes now mount their backing webview only when the pane is active or
  automation-visible. This sleeps inactive worktree browser guest renderers
  without sleeping the main Orca renderer.
- Browser crash breadcrumbs now include webview counts, parked webview counts,
  hidden webviews, and registered browser guest counts.
- The memory collector now prefers the existing host process RSS sweep for
  Electron app bucket memory, falling back to Electron working-set data only
  when a host row is missing.
- Terminal preview retention now applies carriage-return and backspace redraw
  controls before appending text to the retained preview tail.

## Validation

- Browser overlay, webview registry, and crash diagnostics tests passed.
- Browser tab e2e tests passed.
- Memory collector tests passed, including host RSS preference and fallback
  coverage.
- Runtime terminal tests passed for carriage-return and backspace redraw
  normalization, plus the existing bounded partial-tail coverage.

## Remaining Risk

The current packaged Orca app was not running this worktree's patched code
during the live profile. The fixes are covered by unit and e2e tests, but the
next packaged build should be re-profiled under the same active Codex TUI load
to confirm the Resource Usage display and terminal previews match the expected
lower-churn behavior.

## Follow-up: CLI Profiling Blocker

Continuing the profile after this change confirmed the public
`/usr/local/bin/orca` command was still broken because it was a regular
generated launcher file pointing at a removed development build. The CLI
installer previously self-healed stale symlinks, but treated regular files as
conflicts. That meant Settings could not replace an Orca-owned stale launcher,
forcing profiling to use the packaged CLI fallback.

The follow-up fix teaches the installer to recognize only generated Orca Unix
launcher files as stale and replaceable. Arbitrary regular files at the command
path remain conflicts.

## Follow-up: Repeatable Memory Diagnostics

The next profiling blocker was repeatability: collecting a useful memory sample
still required combining Resource Usage IPC, terminal lists, browser tab state,
and host process output by hand. This branch adds `orca diagnostics memory`,
which exposes the existing main-process memory collector through runtime RPC.

The command returns the same `MemorySnapshot` shape used by Resource Usage when
run with `--json`, including host memory, Orca app process buckets, worktree
terminal memory, per-session process roots, and history samples. Text output
prints a compact point-in-time summary and the top worktrees by retained
terminal memory.

## Follow-up: Agent-Browser Paintability Guard

The browser parking fix depends on automation-visible panes staying paintable
without activating the user's worktree. The renderer bridge previously waited
for two animation frames before creating the automation visibility lease, so the
paint wait happened while the parked webview was still hidden. Non-screenshot
agent-browser commands could therefore start immediately after the lease was
created, before React had made the hidden pane paintable.

The follow-up changes the order: create the automation visibility lease first,
then wait for paint while the pane is actually visible to automation. A
renderer-side timeout releases the lease if paint never arrives, so a hung RAF
does not pin an inactive browser pane indefinitely.

## Follow-up: Browser Registration Readiness

One remaining automation race was the wake path for parked or restored browser
tabs. Runtime browser commands asked the renderer to mount a hidden browser
pane, then waited a fixed 500 ms before reading the agent-browser tab registry.
On slow webview startup, that could still race `registerGuest` and make
agent-browser report no tab even though the tab was in the process of mounting.

The follow-up extends the existing tab-registration wait from page-specific
creation to worktree/global wake flows. Runtime commands now wait for the
renderer's actual `browser:registerGuest` IPC before routing automation, with
the same timeout fallback used by tab creation.

## Follow-up: Worktree Activation No-Op Fanout

The next renderer-store check found that repeated activation of an already
active, already-reconciled worktree could still publish a new Zustand root state
because `setActiveWorktree` rebuilt `activeTabTypeByWorktree` even when its
stored value was unchanged. That woke every store subscriber, including session
persistence and runtime graph sync, for a visible no-op.

The follow-up preserves the existing state reference when all derived active
fields, unread state, and first-activation bookkeeping are unchanged. A
regression test subscribes to the store and asserts that reselecting the
already-active reconciled worktree does not notify subscribers.

## Follow-up: Activation Helper Visit Writes

After the store-level no-op fix, the higher-level `activateAndRevealWorktree`
helper could still restamp focus-recency and append navigation history for a
plain reselect of the already-active worktree in terminal view. That path did
not change the visible workspace, but the recency stamp is part of the persisted
session payload and can still wake the session writer.

The follow-up skips only that true no-op visit write. Activations that switch
repo, leave another app view, or carry startup/setup/default-tab work still
record the visit, and the sidebar reveal still runs for the no-op case.

## Follow-up: ANSI Terminal Redraw Controls

The installed app used for the continuation profile still predates the merged
memory diagnostics and terminal-preview fixes, but its live active terminal
preview continued to show redraw noise and there were still no browser tabs.
That kept the remaining source-backed target on retained terminal previews.

The previous preview fix handled carriage-return and backspace redraws, but
not ANSI CSI erase/cursor sequences commonly emitted by spinner-style TUIs.
The follow-up extends the retained-preview line model to strip formatting/OSC
metadata and apply line erase plus horizontal cursor movement before retaining
the text tail. The regression test covers cursor-left overwrite, erase-line
without a carriage return, SGR/private cursor controls, OSC title metadata, and
the existing terminal read cursor metadata.