4. modularize child and kernel lifecycle

[kevinjosethomas]

• moves child lifecycle, usage accounting, tools, extensions, and kernel resources into twelve focused modules with explicit ownership.
• preserves public dispatch, cancellation, and teardown ordering; stacks on 3. modularize session context #2190 and tracks eng-5939.
• 415 tests and repository checks pass; independent review is clear, with exact-revision prime sandbox validation continuing.

---

Note

Medium Risk
Large refactor of session teardown, child cancellation/publication ordering, and kernel replacement gates; regressions would affect orchestration and billing attribution even though behavior is intended to be preserved.

Overview
AgentSession is slimmed down by delegating RLM child orchestration, IPython kernel provisioning, tool registry/ACP MCP handling, and extension reload/bindings to dedicated session/* owners (SessionChildren, SessionChildState, SessionChildUsage, SessionKernel, KernelEnvironment, SessionTools, SessionExtensions, plus child-run, child-projection, and kernel-host-handlers).

Public entry points (runRlmChild, listRlmSubagents, dispose/disposeAsync, tool APIs, reload, ACP MCP replace/release) stay on AgentSession but forward to those owners with the same teardown ordering called out in the README (children complete before kernel disposal; usage flushes at the parent event boundary).

Child spawn/admission, deletion retries, quiescence waits, usage attribution, and snapshot/list projections move out of the monolith into launchChildTask and SessionChildren, while depth/max-depth, parent-reply state, and recap updates live in SessionChildState. Kernel host handlers are composed via createSessionKernelHostHandlers instead of a large inline map in AgentSession.

The package README gains Child agent lifecycle and Tools, extensions, and kernel resources sections documenting file responsibilities and invariants, plus pointers to new test/session/ and regression coverage.

^{Reviewed by Cursor Bugbot for commit b7a44e8. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Modularize child and kernel lifecycle into dedicated session modules

• Extracts AgentSession's child lifecycle, kernel, tool, extension, and usage management into dedicated facade classes under packages/coding-agent/src/session/.
• AgentSession now delegates runtime building, disposal, child orchestration, and prompt rebuilding to SessionKernel, SessionTools, SessionExtensions, SessionChildren, SessionChildState, and SessionChildUsage.
• Updates existing regression and characterization tests to use the new facades and prototype spies rather than direct private-field mutation, and adds new boundary test suites for the extracted modules.
• Risk: SessionChildState.parseDepth now throws a named validation error for invalid non-negative-integer depth configurations instead of accepting them. KernelEnvironment conditionally injects a Serper API key only when the websearch skill is loaded and no inherited environment variable exists.

^{Macroscope summarized b7a44e8.}

[macroscopeapp]

Macroscope skipped reviewing this pull request. Per-review cost limit exceeded (workspace setting).

This review would cost an estimated $14.22, which exceeds your per-review limit of $10.00.

The top 3 files driving up this estimate:

File	Diff Size	Estimate
packages/coding-agent/src/core/agent-session.ts	149.73KB	$7.49
packages/coding-agent/src/session/children.ts	40.99KB	$2.05
packages/coding-agent/src/session/tools.ts	16.02KB	$0.80

Tip

To get this pull request reviewed, you can:

1. Comment @macroscope-app on this PR to request a manual review (monthly spend limits still apply).
2. Exclude the file(s) above from review by adding a pattern to your .macroscope/ignore.md — note that creating this file replaces Macroscope's built-in default ignores rather than extending them.
3. Raise your cost limit in your workspace billing settings.

^{Turn off this reminder going forward}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f43cc8e. Configure here.}

[github-actions]

Prime Agent performance — completed

PR b7a44e8a compared with main 5255a6b8.

Overall: 0 regressed · 0 improved · 17 no clear change.

Metric	Main	This PR	Change
Cold startup	3,173.5 ms	2,936.1 ms	≈ -237.4 ms (-7.48%)
Warm startup	1,810.0 ms	1,674.3 ms	≈ -135.7 ms (-7.50%)
Installation	29.42 s	27.64 s	≈ -1.78 s (-6.05%)
Compressed release artifacts	11.13 MB	11.18 MB	≈ +0.05 MB (+0.47%)
Installed footprint	597.55 MB	597.91 MB	≈ +0.36 MB (+0.06%)
Idle memory, summed RSS	1,138.44 MB	1,129.35 MB	≈ -9.09 MB (-0.80%)

Python runtime

Metric	Main	This PR	Change
Python kernel startup	126.2 ms	120.8 ms	≈ -5.4 ms (-4.26%)
Python cell round trip	0.513 ms	0.495 ms	≈ -0.018 ms (-3.56%)
Empty bash command	10.9 ms	10.7 ms	≈ -0.2 ms (-2.11%)
Bash git status	16.7 ms	16.2 ms	≈ -0.6 ms (-3.45%)
Bash 32 KiB output	11.9 ms	11.4 ms	≈ -0.5 ms (-4.45%)
35 cells / 9 shell calls	164.7 ms	160.8 ms	≈ -3.9 ms (-2.37%)
Python interrupt to done	1.598 ms	1.516 ms	≈ -0.082 ms (-5.11%)
Python state snapshot	25.4 ms	25.5 ms	≈ +0.044 ms (+0.17%)
Python state restore	361.4 ms	347.9 ms	≈ -13.5 ms (-3.74%)
Python idle RSS	33.65 MB	34.95 MB	≈ +1.30 MB (+3.87%)
Python RSS after pandas workload	95.68 MB	97.68 MB	≈ +2.00 MB (+2.09%)

Sandbox cost: ~$0.0912 — no inference calls.
Run, logs, and downloadable raw results

Methodology and samples

Main resolved at 2026-09-11T19:29:33.488906+00:00. Harness 5255a6b8.
Linux x64, 4 vCPU, 8 GB RAM, 20 GB disk; region us.
Image: node:24-bookworm@sha256:be23f54a88d34e8824c741b19b91064094f92c1c97b194144bfc8b50d67258e2.
Stock tools, skills, daemon, and Python bootstrap enabled; fresh homes and a fixed Git fixture.
Onboarding is dismissed; the editor starts without a selected model or submitted prompt.
Medians shown. Arrows require a 20% timing/memory change plus absolute floors and IQR.
These practical noise floors are not a statistical significance test.
Cold means stopped Prime processes; OS filesystem caches are not flushed.
No model requests or credentials. Installation excludes build/setup time.
Installer tarballs use loopback; npm/Python downloads use the network with fresh caches.
Artifact size counts release tarballs; footprint after first use includes registry packages.
MB is decimal. Summed RSS can double-count shared pages; PSS is recorded when available.
Provisioning, setup, and build durations are recorded separately in the raw results.
Kernel probes use the installed JSONL runtime, outside the TUI/TypeScript host.
Per trial: 50 Python cells, 5 calls per shell case, and one 35-cell mix (9 git status calls).
Cell/shell values are batch means; other runtime timings are single operations.
State fixture: a 10,000-row × 8-column integer DataFrame and a 10,000-integer list.
Restore runs in a fresh kernel, including pandas imports; kernel startup is excluded.
Kernel RSS covers the isolated Python process; loaded RSS follows the pandas workload.
Costs estimate full sandbox lifetimes at configured rates, including setup and build.
Budget target: $1; not a billing cap. Checks are informational.

Metric	Main successful/attempted	PR successful/attempted	Main spread	PR spread
Cold startup	10/10	10/10	IQR 146.1 ms	IQR 150.8 ms
Warm startup	10/10	10/10	IQR 62.2 ms	IQR 92.7 ms
Installation	3/3	3/3	range 0.98 s	range 1.47 s
Compressed release artifacts	1/1	1/1	—	—
Installed footprint	1/1	1/1	—	—
Idle memory, summed RSS	10/10	10/10	IQR 32.86 MB	IQR 106.50 MB
Python kernel startup	10/10	10/10	IQR 18.5 ms	IQR 6.3 ms
Python cell round trip	10/10	10/10	IQR 0.128 ms	IQR 0.024 ms
Empty bash command	10/10	10/10	IQR 1.1 ms	IQR 0.9 ms
Bash git status	10/10	10/10	IQR 1.5 ms	IQR 1.7 ms
Bash 32 KiB output	10/10	10/10	IQR 1.4 ms	IQR 1.4 ms
35 cells / 9 shell calls	10/10	10/10	IQR 18.6 ms	IQR 13.6 ms
Python interrupt to done	10/10	10/10	IQR 0.276 ms	IQR 0.194 ms
Python state snapshot	10/10	10/10	IQR 2.6 ms	IQR 2.4 ms
Python state restore	10/10	10/10	IQR 23.4 ms	IQR 39.0 ms
Python idle RSS	10/10	10/10	IQR 3.53 MB	IQR 2.99 MB
Python RSS after pandas workload	10/10	10/10	IQR 3.11 MB	IQR 3.79 MB