2. modularize session runtime

[kevinjosethomas]

• separate scheduling, preparation, dispatch, retries, shell execution, and commit coordination into focused session modules.
• preserve ordering, cancellation, persistence, extension hooks, and public behavior; 545 focused tests and repository checks pass.
• stacked on 1. modularize /goal logic #2184 for eng-5938; combined-head sandbox, benchmark, and review gates remain open.

Note

Extract session runtime components from AgentSession into dedicated modules

• Replaces inline AgentSession state and helpers with SessionInputScheduler, SessionInputDispatcher, SessionCommitFence, TurnPreparer, SessionRetry, and SessionBash instances to modularize the session runtime.
• Adds comprehensive unit test coverage for all new session modules, validating batching, fencing, retry, and dispatch edge cases.
• Updates README.md to document the new session input scheduling and commit coordination architecture.
• Risk: AgentSession delegates internal state management to the new modules in agent-session.ts; any out-of-tree code relying on the removed inline fields or private methods will break.

^{Macroscope summarized f134103.}

---

Note

High Risk
This is a large refactor of core session concurrency (input pump, commit fencing, retries, and bash ordering); regressions would affect admission, cancellation, branch navigation, and idle/passivation semantics even if behavior is intended to be unchanged.

Overview
Pulls the session turn lifecycle out of AgentSession into dedicated session/* modules while keeping the same public APIs, event shapes, recovery format, and ordering rules.

AgentSession now wires SessionInputScheduler (serialized pump, epochs, admission vs queued-work pauses, abort/update-restart suspension), SessionInputDispatcher (action selection, batching, rollback/settlement against the existing action store), SessionCommitFence (FIFO commit leases and reentrancy), TurnPreparer / prepared-actions (execution policies, prepared turns/commands, recovery snapshots), SessionRetry (auto-retry, auth-stale, completion reservation), and SessionBash (user/direct shell runs, deferred transcript output). Inline implementations and types move out of agent-session.ts; waitForPromiseOrAbort moves to utils/wait-for-abort.ts. Recovery and TurnExecutionPolicy exports are re-exported from the session facade.

The README documents ownership boundaries for scheduling, commit coordination, shell commands, retry, and turn preparation. New unit tests under test/session/ (plus scheduler usage in goal-continuation tests) cover fence ordering, bash slot/transient behavior, and related edge cases.

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

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

[github-actions]

Prime Agent performance — completed

PR f1341032 compared with main 1eee2938.

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

Metric	Main	This PR	Change
Cold startup	3,108.8 ms	3,140.8 ms	≈ +32.1 ms (+1.03%)
Warm startup	1,807.2 ms	1,827.6 ms	≈ +20.5 ms (+1.13%)
Installation	28.67 s	29.64 s	≈ +0.97 s (+3.40%)
Compressed release artifacts	11.12 MB	11.14 MB	≈ +0.02 MB (+0.17%)
Installed footprint	597.49 MB	597.57 MB	≈ +0.08 MB (+0.01%)
Idle memory, summed RSS	1,136.64 MB	1,136.88 MB	≈ +0.24 MB (+0.02%)

Python runtime

Metric	Main	This PR	Change
Python kernel startup	125.1 ms	126.3 ms	≈ +1.1 ms (+0.90%)
Python cell round trip	0.557 ms	0.526 ms	≈ -0.031 ms (-5.51%)
Empty bash command	11.6 ms	10.9 ms	≈ -0.7 ms (-6.31%)
Bash git status	17.1 ms	16.3 ms	≈ -0.8 ms (-4.94%)
Bash 32 KiB output	12.1 ms	11.4 ms	≈ -0.7 ms (-6.19%)
35 cells / 9 shell calls	170.8 ms	161.0 ms	≈ -9.8 ms (-5.71%)
Python interrupt to done	1.475 ms	1.459 ms	≈ -0.016 ms (-1.06%)
Python state snapshot	26.7 ms	24.9 ms	≈ -1.8 ms (-6.70%)
Python state restore	356.7 ms	359.2 ms	≈ +2.5 ms (+0.70%)
Python idle RSS	34.48 MB	34.90 MB	≈ +0.42 MB (+1.22%)
Python RSS after pandas workload	98.03 MB	96.60 MB	≈ -1.42 MB (-1.45%)

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

Methodology and samples

Main resolved at 2026-09-10T23:42:51.258326+00:00. Harness 1eee2938.
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 110.8 ms	IQR 128.4 ms
Warm startup	10/10	10/10	IQR 80.7 ms	IQR 115.4 ms
Installation	3/3	3/3	range 2.64 s	range 1.27 s
Compressed release artifacts	1/1	1/1	—	—
Installed footprint	1/1	1/1	—	—
Idle memory, summed RSS	10/10	10/10	IQR 120.31 MB	IQR 119.76 MB
Python kernel startup	10/10	10/10	IQR 10.8 ms	IQR 10.0 ms
Python cell round trip	10/10	10/10	IQR 0.110 ms	IQR 0.046 ms
Empty bash command	10/10	10/10	IQR 1.4 ms	IQR 0.7 ms
Bash git status	10/10	10/10	IQR 1.2 ms	IQR 1.5 ms
Bash 32 KiB output	10/10	10/10	IQR 0.5 ms	IQR 1.4 ms
35 cells / 9 shell calls	10/10	10/10	IQR 16.0 ms	IQR 15.5 ms
Python interrupt to done	10/10	10/10	IQR 0.119 ms	IQR 0.169 ms
Python state snapshot	10/10	10/10	IQR 1.1 ms	IQR 1.2 ms
Python state restore	10/10	10/10	IQR 36.9 ms	IQR 13.2 ms
Python idle RSS	10/10	10/10	IQR 5.27 MB	IQR 3.40 MB
Python RSS after pandas workload	10/10	10/10	IQR 5.55 MB	IQR 3.83 MB