5. modularize session coordination

[kevinjosethomas]

This is part of the stack giving Prime Agent session features explicit owners. This PR extracts input, turn, model, and history coordination and groups session modules by feature. AgentSession remains the public entry point and coordinates operations across those owners.

Goal state, command parsing, persistence, continuation, and contracts live together under src/session/goals. Owners keep state transitions, cancellation, and cleanup together and expose narrow dependencies. The architecture guide, source map, and AGENTS.md record these conventions. Public session APIs, goal payloads, and persisted formats remain unchanged.

The stack is rebased on main at 5255a6b, including withdrawal of background-command notices after their result is consumed. Repository checks pass on every PR head. Focused queue, kernel, refinement, side-question, and UI regressions pass; eight local background-bash integration cases require the missing Python runtime environment. GitHub checks and benchmarks must finish on the updated commits, and Macroscope's full correctness review remains blocked by its per-review cost limit.

Stacked on #2192; tracks ENG-5938.

---

Note

Low Risk
Documentation-only changes with no runtime or protocol impact; they document boundaries already reflected in the session module layout.

Overview
Adds source organization rules to AGENTS.md, pointing contributors at the architecture guide and src/README.md source map and requiring ownership/API/dependency analysis before structural PRs.

Introduces a new Source Ownership and Module Boundaries section in architecture.md (where session features live under session/<feature>/, single authoritative state, narrow dependencies, and how to review extractions).

Rewrites packages/coding-agent/src/README.md to match the modular layout: goals and shared contracts under session/goals/ (including continuation.ts and contracts.ts instead of core/goals.ts), plus updated paths and ownership tables for session/input/, session/turns/, session/context/, session/children/, session/kernel/, session/models/, session/tools/, and related test locations (test/session/goals/).

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

Note

Modularize session coordination into dedicated service modules

Breaks the monolithic AgentSession class into focused coordinator modules under session/turns/, session/input/, session/goals/, session/context/, session/kernel/, session/models/, session/children/, session/compaction/, session/refinement/, session/tools/, and session/extensions/. AgentSession now composes these services through host-contract interfaces and delegates via pass-through wrappers.

• New coordinators include SessionTurnPolicy, SessionTurnExecution, SessionEvents, SessionCommandExecution, SessionAutonomousContinuation, SessionGoalContinuation, SessionModelSelection, SessionInputAdmission, SessionActionQueue, SessionActionRecovery, SessionMessageDelivery, SessionPendingContext, SessionHistoryNavigation, SessionContextView, SessionExport, and SessionHarnessContext.
• New host-request handlers cover RLM heartbeat CRUD, agent messaging, agent observation, goal, and compaction requests with validation and serialization.
• Adds architecture and source-ownership documentation in architecture.md and README.md, plus new regression test suites for session finishing boundaries, input turns, and model history.
• Risk: all internal AgentSession private-state access paths moved to nested owner objects; out-of-tree code referencing direct session fields (e.g. session.eventQueue, session.autonomousState) will break. Tests updated to new shapes but no backward-compat shims remain.

^{Macroscope summarized 254666f.}

[macroscopeapp]

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

This review would cost an estimated $25.97, 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	253.75KB	$12.69
packages/coding-agent/src/README.md	26.59KB	$1.33
packages/coding-agent/src/session/input/prompt-submission.ts	24.36KB	$1.22

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}

[github-actions]

Prime Agent performance — partial

PR 254666f2 compared with main 5255a6b8.

Overall: 1 regressed · 0 improved · 15 no clear change · 1 incomplete.

Metric	Main	This PR	Change
Cold startup	3,100.7 ms	3,105.0 ms	≈ +4.2 ms (+0.14%)
Warm startup	1,824.7 ms	1,781.6 ms	-43.0 ms (-2.36%); incomplete
Installation	29.52 s	30.83 s	≈ +1.31 s (+4.44%)
Compressed release artifacts	11.13 MB	11.23 MB	$\textcolor{#ab6a65}{\textsf{↑ +0.11 MB (+0.94\%)}}$
Installed footprint	597.55 MB	598.30 MB	≈ +0.75 MB (+0.13%)
Idle memory, summed RSS	1,138.51 MB	1,030.46 MB	≈ -108.05 MB (-9.49%)

Python runtime

Metric	Main	This PR	Change
Python kernel startup	125.6 ms	124.6 ms	≈ -1.0 ms (-0.80%)
Python cell round trip	0.514 ms	0.517 ms	≈ +0.003 ms (+0.53%)
Empty bash command	11.8 ms	11.6 ms	≈ -0.3 ms (-2.39%)
Bash git status	17.1 ms	16.3 ms	≈ -0.8 ms (-4.77%)
Bash 32 KiB output	11.1 ms	11.2 ms	≈ +0.098 ms (+0.88%)
35 cells / 9 shell calls	159.1 ms	159.6 ms	≈ +0.6 ms (+0.37%)
Python interrupt to done	1.464 ms	1.499 ms	≈ +0.035 ms (+2.41%)
Python state snapshot	25.0 ms	25.2 ms	≈ +0.2 ms (+0.91%)
Python state restore	340.9 ms	361.0 ms	≈ +20.1 ms (+5.91%)
Python idle RSS	35.85 MB	36.21 MB	≈ +0.36 MB (+1.02%)
Python RSS after pandas workload	98.40 MB	98.41 MB	≈ +0.01 MB (+0.01%)

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

Methodology and samples

Main resolved at 2026-09-11T19:29:36.806220+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 97.3 ms	IQR 191.5 ms
Warm startup	10/10	9/9	IQR 103.3 ms	IQR 59.8 ms
Installation	3/3	3/3	range 1.84 s	range 0.65 s
Compressed release artifacts	1/1	1/1	—	—
Installed footprint	1/1	1/1	—	—
Idle memory, summed RSS	10/10	10/10	IQR 112.39 MB	IQR 117.02 MB
Python kernel startup	10/10	10/10	IQR 6.5 ms	IQR 5.5 ms
Python cell round trip	10/10	10/10	IQR 0.074 ms	IQR 0.044 ms
Empty bash command	10/10	10/10	IQR 1.6 ms	IQR 1.3 ms
Bash git status	10/10	10/10	IQR 1.5 ms	IQR 0.7 ms
Bash 32 KiB output	10/10	10/10	IQR 0.7 ms	IQR 0.4 ms
35 cells / 9 shell calls	10/10	10/10	IQR 19.6 ms	IQR 3.9 ms
Python interrupt to done	10/10	10/10	IQR 0.117 ms	IQR 0.127 ms
Python state snapshot	10/10	10/10	IQR 2.1 ms	IQR 3.3 ms
Python state restore	10/10	10/10	IQR 32.1 ms	IQR 23.8 ms
Python idle RSS	10/10	10/10	IQR 1.88 MB	IQR 3.84 MB
Python RSS after pandas workload	10/10	10/10	IQR 1.67 MB	IQR 4.52 MB

Failures:

• pr measure 2: RuntimeError
• PR: CalledProcessError: Command '['/usr/sbin/runuser', '-u', 'benchmark1', '--', 'prime-agent', 'stop', '36d87dc1ed02', '--json']' returned non-zero exit status 1.