Skip to content

Move Browser lifecycle and on/off ownership out of core - #4320

Merged
deehw merged 42 commits into
mainfrom
core-browser-2
Nov 16, 2026
Merged

deehw merged 42 commits into
mainfrom
core-browser-2

Conversation

@deehw

@deehw deehw commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Browser lifecycle and on/off state now belong to the Browser service. One bounded agent-lifecycle subscription serves Browser, viewers, search and cleanup and replaces their feature-specific lifecycle ports. Stop/purge revoke pending Browser creation, migration and pane adoption; metadata snapshots omit saved launch credentials while the authoritative Resume record retains them.

This is lifecycle extraction only. Frame parts, Browser stream relay and wake extraction remain separate work; no Browser UI or feature expansion is included.

Design

Reviewed Design.

  • Growth/concurrency: Browser state stays in agent-browser.json and is removed on purge. Existing per-agent queues and generation fences govern writes; generic held delivery is capped at 1,000 events per service and follower bookkeeping tracks live agents and prunes stale entries above 4,096 (this is not a hard live-agent admission cap). No new credential storage or process login.
  • Read cost/scale: subscribers receive changes and one reconnect snapshot. The same architecture closure calculation gives 541 files / 92,882 loaded lines before and 541 / 92,818 after; warmed closure is 647 / 108,894 before and 647 / 108,830 after. These source counts are informational; measured runtime costs appear below.
  • Compatibility/migration: public requests and frames retain their shape. Legacy row flags and old-core service adapters are dated through 2026-12-18. Presence queries are separate from migration evidence; only UNKNOWN_QUERY permits the old-core fallback. Missing or unavailable evidence preserves the stored profile. No backend rollout or history migration.
  • Rollback: older builds retain pre-update row flags; service-only on/off changes are not written back into those old rows. Profile ownership and on-disk Browser schema remain compatible.
  • Audience/identity/failure: existing owner and guest checks remain. Lifecycle snapshots contain copied metadata, never gridLaunch; late, stale or disconnected replies cannot publish authority. Service failures are visible and leave core and unrelated agents running.
  • Platforms: shared TypeScript affects macOS, Linux and Windows. Native evidence here is macOS x64 / Node 24.22.2. Normal PR CI covers Linux unit checks; no native Windows or real Podman performance pass is claimed. No Desktop code changes.

Validation

Final clean head 8e601617b16f0bc64c38408968e12284535c098a integrates main 41b4c12de69b6a6ac918882c047c52c998118c14. The previous head's automatic CI passed (run 43898898273); the merge helper refused safely when main moved. The two incoming changes are independently accepted Herdr/device integration and Desktop log redaction. The merge is clean, with no change to reviewed core, library, engine, harnessd or Browser implementation, dependency locks or validation/build scripts.

  • The combined core/services gate passes 4,816 cases in 253 files, 100% statements/branches/functions/lines, 364.93 s. The initial sandbox run was interrupted after process/socket EPERM/EACCES; the complete native-allowance run is the passing evidence. No assertion was weakened.
  • Prior unchanged-input gates remain harnessd 371 plus one existing skip, portability 1,065 plus ten existing skips, PTY/tmux 14, Resume 484, with 100% applicable coverage. Total combined/reused gate cases: 6,750. Prior native and type evidence is scoped below; final combined-source types/units are required in automatic PR CI.
  • Recorded caller REDs cover lifecycle delivery, launch-key disclosure, Stop during destination adoption, purge during queued migration/source cleanup, and old-core presence versus unresolved migration. Corrected caller checks pass; the previous native input failure remains preserved.
  • Independent Browser review and root review of the clean main integration found no functional blocker. The frozen prior bundle passed 21/21 native cases in services, Browser lifecycle and credential custody (322.92 s), using private daemon/tmux homes. These tested Browser/core inputs are unchanged; this is not a native test of the new device adapter or byte identity of the current full bundle.

Prior native bundle SHA-256: c5a3986e6b4d3c086ba24eb96a633c9325d701219ce210f499eeb6ed69ea9946; original runtime/source proof 55865ad4fc732c69e540a35cad2bf7fe2c2d7b1991c7da125e639635f2fb4acc. Final integration acceptance/provenance SHA-256: cde0951b1f17733f0ef2c51adb06da37fdb37ac5c895a957a955d994f25cabaa.

Runtime cost

One quiet ABBA completed exactly once: baseline 1c3a0ed654bc1f0a4054c07c499e09c569a64953, candidate ab5e73f126fba4ac055eec8f0d4be869e0963ab8; current-main input and credential-safe metadata on both sides. All four children and the orchestrator exited 0, every output stream reached EOF, all 12 phases passed and private fixture teardown passed. No retry, forced GC, dropped sample or parameter change.

Workload: 16 fake agents, two active, two windows/four terminal streams, 30-second empty/idle/active phases, 10-second warm-up. Medians of two fresh processes per side follow; both paired directions and every raw sample are retained.

Phase Core CPU (% of one CPU) Mean RSS (MiB) Peak RSS (MiB) Loop p95 (ms)
empty 0.415 → 0.424 (+2.20%) 99.15 → 102.12 (+3.00%) 99.33 → 102.29 (+2.98%) 12.165 → 12.165 (+0.00%)
populated-idle 1.021 → 1.029 (+0.75%) 162.72 → 156.38 (-3.89%) 163.64 → 157.63 (-3.67%) 12.165 → 12.161 (-0.03%)
active 5.393 → 5.343 (-0.93%) 164.35 → 157.72 (-4.03%) 165.88 → 160.15 (-3.45%) 12.157 → 12.149 (-0.07%)
Phase Master CPU (% of one CPU) Master peak RSS (MiB)
empty 0.017 → 0.033 (+100.02%) 62.28 → 62.33 (+0.09%)
populated-idle 0.033 → 0.017 (-50.00%) 63.82 → 63.91 (+0.14%)
active 0.017 → 0.033 (+100.01%) 63.84 → 63.93 (+0.15%)

Active completion p95 is 6898.8 → 6917.9 ms (+19.1 ms, +0.28%); every process completed eight turns. This includes the deliberately ~5-second fake-engine delay and is not terminal-echo/input-dispatch latency.

The populated-idle median is slightly above the 1% target on both sources (1.0210% before, 1.0286% after); this comparison does not clear that whole-core target or establish 10x headroom. The absolute difference is +0.0076 percentage points. Core active CPU and populated memory fall; empty memory rises by 2.97 MiB. The final design review accepts this lifecycle increment with these mixed costs explicitly retained; whole-core idle acceptance remains open.

Browser is off: this measures core overhead, not rendering or real Podman. CPU is the core process; master observations have coarse ps resolution and are separate. Services, engines and tmux are outside the CPU total, and agent-creation setup is outside the measured 90 seconds. Two processes per side do not establish statistical significance.

The private fixture removes its unused pre-measurement process-environment diagnostic on both sides; measured workload and cadence are unchanged. Earlier slower synthetic-scan/Node26 results stay historical and are not reclassified as passes.

Fixed plan SHA-256: f92e92d0e35972d988afa50b85fc19547f58fd08f476d9ea725c6b1630e9115e; complete summary SHA-256: 8ac33e9ff99436750a4c25b6c85a26a33785e0150b5bab5feeef6b3074abc38a. Final source-equivalence receipt SHA-256: 9f97a5fee07d89b2e083499cb85f7ee788f267cee7513a934419877daad01228. The existing functional and cost evidence is reused only for unchanged inputs; final PR CI remains required.

[
  {
    "check": "cli-core",
    "command": "npm run test:core -- --maxWorkers=2",
    "cwd": "cli",
    "head": "8e601617b16f0bc64c38408968e12284535c098a",
    "status": "passed",
    "passed": 4816,
    "platform": "macos",
    "evidenceSha256": "6df18634733f1ced33ec0efe5ce7530f95c941e29d2b801d2acd4c1060364c9e"
  },
  {
    "check": "cli-harnessd",
    "command": "npm run test:harnessd -- --maxWorkers=2",
    "cwd": "cli",
    "head": "8e601617b16f0bc64c38408968e12284535c098a",
    "status": "passed",
    "passed": 371,
    "platform": "macos",
    "reusedFromHead": "091b740d80ffabf0702863321bd8197a85635a53",
    "reuseEvidenceSha256": "cde0951b1f17733f0ef2c51adb06da37fdb37ac5c895a957a955d994f25cabaa"
  },
  {
    "check": "cli-portability",
    "command": "npm run test:portability -- --maxWorkers=2",
    "cwd": "cli",
    "head": "8e601617b16f0bc64c38408968e12284535c098a",
    "status": "passed",
    "passed": 1065,
    "platform": "macos",
    "reusedFromHead": "091b740d80ffabf0702863321bd8197a85635a53",
    "reuseEvidenceSha256": "cde0951b1f17733f0ef2c51adb06da37fdb37ac5c895a957a955d994f25cabaa"
  },
  {
    "check": "cli-pty",
    "command": "npm run test:terminal-contract",
    "cwd": "cli",
    "head": "8e601617b16f0bc64c38408968e12284535c098a",
    "status": "passed",
    "passed": 14,
    "platform": "macos",
    "reusedFromHead": "091b740d80ffabf0702863321bd8197a85635a53",
    "reuseEvidenceSha256": "cde0951b1f17733f0ef2c51adb06da37fdb37ac5c895a957a955d994f25cabaa"
  },
  {
    "check": "cli-resume",
    "command": "npm run test:resume -- --maxWorkers=2",
    "cwd": "cli",
    "head": "8e601617b16f0bc64c38408968e12284535c098a",
    "status": "passed",
    "passed": 484,
    "platform": "macos",
    "reusedFromHead": "091b740d80ffabf0702863321bd8197a85635a53",
    "reuseEvidenceSha256": "cde0951b1f17733f0ef2c51adb06da37fdb37ac5c895a957a955d994f25cabaa"
  }
]

deehw and others added 11 commits November 15, 2026 08:49
…e browser, viewers, cleanup and search)

Not done: discovery.ts, heldAgentLife(), agentTmp out of the core, typecheck, specs, e2e, docs. The plan and what is
left are in the package notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ent-tmp out, sources typecheck

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…owed agents

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…owed agents

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ages' answers; docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	cli/src/lib/controlResume.golden.spec.ts
#	cli/src/lib/ptyHostBackend.restart.spec.ts
#	docs/design/2026-11-15-core-plan.md
…es its follow

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the Agent Browser's lifecycle and on/off leave the core

Package 2 step 1 of docs/design/2026-11-15-core-plan.md. core/agentLife.ts tells the services that follow agents each
look at a live agent, its end, a stop, a purge and a pane's new agent (CoreApi.agents.follow; follow_agents from a
service's process, services/followLink.ts), holding what one in its own process must not miss for the kinds its process
hears (SERVICE_HOSTS hears). The viewers' attach and detach, the agent cleanup's stops, search's purges and the agent
browser are on it, and their port members are gone. Whose Browser is on is the browser's own (agent-browser.json on),
the row's flag taken in once and dated 2026-12-18. lib/agentTmp.ts leaves the core.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ate file once

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@deehw
deehw marked this pull request as ready for review November 15, 2026 04:02
# Conflicts:
#	cli/src/core/main.ts
#	cli/src/harnessd/services.spec.ts
#	cli/src/harnessd/services.ts
# Conflicts:
#	docs/design/2026-11-15-core-plan.md
# Conflicts:
#	cli/src/core/agents/lifecycle.ts
#	cli/src/core/main.ts
#	cli/src/services/AGENTS.md
…ntinue

# Conflicts:
#	cli/src/core/agents/discovery.spec.ts
#	cli/src/core/agents/discovery.ts
#	cli/src/lib/resumeAgentService.ts
@deehw
deehw marked this pull request as draft November 15, 2026 11:29
@deehw deehw changed the title CLI core: one shape for what happens to agents; the Agent Browser's lifecycle and on/off leave the core Move Browser lifecycle and on/off ownership out of core Nov 16, 2026
@deehw
deehw marked this pull request as ready for review November 16, 2026 15:40
@deehw
deehw merged commit 093e079 into main Nov 16, 2026
28 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant