6. consolidate session feature ownership

[kevinjosethomas]

Context

This continues the coding-agent cleanup stack by finishing feature ownership after the earlier session extractions. Compaction, refinement and input still had implementations split between core and session, making related behavior difficult to find and change together.

Changes

Consolidates context algorithms, refinement planning and persistence, input actions, autonomy and child request contracts under their session owners. Separates daemon residency policy from the action queue and model search/shell requests from child handling. Public exports and historical import paths remain available through explicit compatibility exports. Validation rules, autonomous argument parsing, persistence, protocol and session behavior are preserved. Adds reusable refactoring conventions and the remaining migration ledger. The CI trigger now accepts stacked PR targets with its existing contributor checks and jobs unchanged.

Validation

Full repository checks and the complete GitHub CI matrix pass at c3311d9. The combined session suite passed 343 tests. Paired Prime Sandboxes exercised installed TUI input, CLI/daemon refinement ordering, real Python execution/interrupt/snapshot/restore, SDK exports and historical declarations against the pinned base. Independent review found no actionable regression. Initial SDK-name and missing-goal-interpreter fixture failures are retained in the evidence; separate corrections passed, including the unchanged goal assertions at the final stack head. Two live-provider compaction cases remain intentionally unexecuted.

The sandbox-tested product pin is c7b0f53; c3311d9 changes only the CI trigger. All sandbox resources were deleted. Current-head Bugbot passes and its compatibility-alias thread was resolved with the required compatibility rationale. Macroscope skipped at its cost cap, no new-head CodeQL check is present, and the automated benchmark report is complete. It flags +0.14 MB compressed artifacts (+1.22%) against then-current main b53c2e9; the other 16 metrics show no clear change under the harness thresholds. This compares the cumulative stack against main, not this follow-up in isolation. No performance improvement is claimed.

ENG-5934, ENG-5938. Stacked on #2194; kernel/runtime ownership follows in #2250.

Note

Consolidate session feature ownership by moving agent-session, context, and input modules from core/ to session/

• Moves agent-session, autonomy, compaction, context messages, input actions, refinement, child runtime contracts, and model search from core/ into dedicated session/ subpackages, leaving compatibility forwarding modules behind
• Adds new utilities for token estimation (estimateContextTokens, estimateTokens), usage accounting (addAssistantUsage, subtractAssistantUsage, cloneUsage), prompt admission cancellation (PromptAdmissionCancelledError), RLM host request adapters (createRlmRunHostHandler, createRlmFindModelsHostHandler), and worker residency policies (canPassivateSession, canEvictWorker)
• Fixes idle input-pump spin: SessionInputCheckpoints now waits on the host's isBusyForInputPump predicate instead of directly checking scheduler suspension, preventing CPU spinning when bash, compaction, or retry work blocks queued input
• Adds compatibility tests asserting export-name and object-identity equivalence between legacy core/ paths and new session/ paths; adds a regression test for the idle-spin fix
• Risk: many import paths change across the codebase; out-of-tree consumers importing from core/ still work via forwarding modules but receive deprecation-by-redirect. The SessionInputCheckpoints busy check is now delegated to isBusyForInputPump on the checkpoint host — any host implementation missing this predicate will break.

^{Macroscope summarized 17e4ccc.}

---

Note

Medium Risk
Large import-path and ownership refactor across session input scheduling and compaction/refinement boundaries, with one targeted idle-wait behavior change; mitigated by compatibility re-exports but easy to miss host wiring for isBusyForInputPump.

Overview
This PR relocates session execution from core/ into session/ feature folders (input, autonomy, compaction, refinement, context, children) while core/agent-session.ts and related modules become thin re-export facades so supported import paths and public API shapes stay the same.

Responsibility splits move the action queue to session/input/action-store.ts, prepared-action contracts to session/input/prepared-actions.ts, autonomous runtime to session/autonomy/, and daemon worker passivation/eviction out of the queue into modes/daemon/workers/residency-policy.ts. Compaction/refinement algorithms and shared context helpers land with their session owners instead of staying split across core/.

Behavior fix: SessionInputCheckpoints.waitForIdleOrSettlement now waits on activity when the input pump is blocked (bash, compaction, retry) via isBusyForInputPump, instead of spinning while queued input cannot dispatch.

Docs/CI: adds docs/refactoring.md and source-organization-plan.md, updates architecture/source-map guidance, and drops the pull_request branch filter on CI so stacked PR targets still run checks.

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

[github-actions]

Prime Agent performance — completed

PR 17e4cccd compared with main 878410b3.

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

Metric	Main	This PR	Change
Cold startup	1,589.9 ms	1,788.1 ms	≈ +198.3 ms (+12.47%)
Warm startup	993.4 ms	1,106.9 ms	≈ +113.5 ms (+11.42%)
Installation	15.96 s	16.71 s	≈ +0.75 s (+4.69%)
Compressed release artifacts	70.11 MB	70.34 MB	≈ +0.23 MB (+0.33%)
Installed footprint	571.97 MB	572.78 MB	≈ +0.81 MB (+0.14%)
Idle memory, summed RSS	1,203.88 MB	1,208.47 MB	≈ +4.59 MB (+0.38%)

Python runtime

Metric	Main	This PR	Change
Python kernel startup	146.4 ms	154.3 ms	≈ +7.9 ms (+5.39%)
Python cell round trip	0.683 ms	0.687 ms	≈ +0.004 ms (+0.61%)
Empty bash command	14.2 ms	13.9 ms	≈ -0.3 ms (-2.01%)
Bash git status	20.8 ms	20.9 ms	≈ +0.012 ms (+0.06%)
Bash 32 KiB output	14.4 ms	14.1 ms	≈ -0.2 ms (-1.53%)
35 cells / 9 shell calls	206.5 ms	206.3 ms	≈ -0.2 ms (-0.11%)
Python interrupt to done	1.770 ms	1.801 ms	≈ +0.031 ms (+1.73%)
Python state snapshot	29.8 ms	30.5 ms	≈ +0.8 ms (+2.58%)
Python state restore	424.1 ms	429.6 ms	≈ +5.4 ms (+1.28%)
Python idle RSS	34.60 MB	34.83 MB	≈ +0.23 MB (+0.65%)
Python RSS after pandas workload	96.73 MB	97.84 MB	≈ +1.10 MB (+1.14%)

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

Methodology and samples

Main resolved at 2026-09-13T05:48:33.322113+00:00. Harness 878410b3.
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. Performance changes are informational.
Failed or incomplete execution fails the workflow; saved artifacts remain available.
Each side stops a phase after 2 identical consecutive failures.
Skipped trials are not attempted samples. Warm startup requires a successful cold launch.

Metric	Main successful/attempted	PR successful/attempted	Main spread	PR spread
Cold startup	10/10	10/10	IQR 143.6 ms	IQR 381.2 ms
Warm startup	10/10	10/10	IQR 78.2 ms	IQR 100.0 ms
Installation	3/3	3/3	range 2.44 s	range 4.55 s
Compressed release artifacts	1/1	1/1	—	—
Installed footprint	1/1	1/1	—	—
Idle memory, summed RSS	10/10	10/10	IQR 14.60 MB	IQR 4.89 MB
Python kernel startup	10/10	10/10	IQR 20.4 ms	IQR 13.3 ms
Python cell round trip	10/10	10/10	IQR 0.197 ms	IQR 0.086 ms
Empty bash command	10/10	10/10	IQR 1.1 ms	IQR 2.4 ms
Bash git status	10/10	10/10	IQR 3.3 ms	IQR 2.1 ms
Bash 32 KiB output	10/10	10/10	IQR 2.1 ms	IQR 2.2 ms
35 cells / 9 shell calls	10/10	10/10	IQR 15.6 ms	IQR 29.6 ms
Python interrupt to done	10/10	10/10	IQR 0.232 ms	IQR 0.472 ms
Python state snapshot	10/10	10/10	IQR 5.2 ms	IQR 3.8 ms
Python state restore	10/10	10/10	IQR 26.5 ms	IQR 47.3 ms
Python idle RSS	10/10	10/10	IQR 1.68 MB	IQR 3.58 MB
Python RSS after pandas workload	10/10	10/10	IQR 2.74 MB	IQR 3.64 MB

[macroscopeapp]

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

This review would cost an estimated $50.56, 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	124.34KB	$6.22
packages/coding-agent/src/session/agent-session.ts	123.46KB	$6.17
packages/coding-agent/src/core/refinement/refinement.ts	48.57KB	$2.43

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]

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 c7b0f53. Configure here.}

[Dmatut7]

Hi — downstream line here (we run a fork with ~100 reliability commits on your 0.9.x; full context in Discussion #2239). We've been studying this refactor stack in detail because our fixes will need re-homing once it lands. The stack's shape is genuinely helpful for that. Four seams would make the re-home purely additive on our side, if they fit your plans:

1. A residency predicate on the session coordinator (something like "is this session busy with queued/in-flight work") that we can hook our stall-watchdog exemption into — right now our liveness vouch has to reach into turn internals.
2. A delivery idempotency key on the agent-message path (sender-minted message id honored across retries) — we built one downstream after production duplicate deliveries; if yours lands with a different shape we'd rather align early.
3. A retry/stream seam on the supervisor catch-up path (we added bounded retry + gap detection after 708 production "failed to catch up" events).
4. A kernel liveness contract (an explicit "the kernel is alive but busy" signal distinct from output) — we added an out-of-band heartbeat for this after 144 production watchdog kills of healthy long-running cells.

And one heads-up in return: the stack's current tip still carries the waitForIdle spin defect you fixed in #2151 — session/input/input-checkpoints.ts uses the narrow predicate again, so a session that is idle-but-externally-busy spins the event loop at 100% CPU. Easy to verify against #2151's test.

Happy to share our implementations of any of the four (each has regression tests). Thanks for doing this split — the god object needed to go.

[kevinjosethomas]

hey @Dmatut7! Sorry for the inconvenience here-- we were shipping really fast, but now I'm taking the time to clean up the codebase, especially starting with the agent-session class 😅

I'll take a look at your 4 suggestions and see if we can add to the stack or a future PR. Thanks for reaching out! and would love to hop on a call and learn about your usecases with Prime Agent if you're available :)