4. modularize session shell execution

[kevinjosethomas]

• move shell execution, cancellation, lifecycle events, and deferred output into one session feature owner.
• preserve public dispatch and transcript ordering; all 282 focused tests and repository checks pass, with live validation pending.
• stacked on 3. modularize session commit coordination #2187; continues eng-5938 with unchanged shell events and persistence.

---

Note

Medium Risk
Shell execution, abort timing, extension precedence, and deferred transcript ordering are scheduling-sensitive; behavior is intended to be unchanged but the logic moved behind new host wiring.

Overview
Extracts session shell behavior from AgentSession into a dedicated SessionBash owner in session/bash.ts, continuing the session modularization pattern used for scheduling and commit fencing.

AgentSession now constructs SessionBash with host callbacks (cwd/shell settings, extension user_bash interception, event emit, transcript append, input checkpoint notifications, and chained executeBash / recordBashResult so public method wrappers still apply). Public APIs (executeBash, runUserBash, abortBash, pending flush, isBashRunning) delegate without changing event shapes or bashExecution persistence. Bash lifecycle events are typed via SessionBashEvent on the session event union.

Adds focused SessionBash unit tests and documents shell ownership in README.md. One integration test now holds a real in-flight executeBash instead of toggling private bash flags.

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

Note

Extract shell execution logic from AgentSession into SessionBash class

• Moves bash state (abort-controller tracking, user-command slot, deferred messages) and behavior (execution, user-command interception, lifecycle events, recording, cancellation) from AgentSession into a new SessionBash owner class in bash.ts
• SessionBash depends on a SessionBashHost callback interface rather than receiving AgentSession, Agent, kernel, or storage-manager objects, keeping the boundary decoupled
• AgentSession retains public wrapper methods (executeBash, runUserBash, recordBashResult, abortBash) and getters (isBashRunning, hasPendingBashMessages) that delegate to SessionBash
• Extracts ExecuteBashOptions, RunUserBashOptions, and SessionBashEvent types into bash.ts; updates agent-session.ts to use the exported SessionBashEvent union
• Adds focused unit tests for SessionBash in bash.test.ts and updates the prompt handoff race test in agent-session-prompt.test.ts to use a real transient executeBash instead of mutating removed private fields
• Behavioral Change: AgentSession.runUserBashLocked and its private bash fields are removed; any out-of-tree code referencing these private members will break

^{Macroscope summarized 8d79a0a.}

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

[cursor]

Exported host unused outside tests

Low Severity

SessionBashHost is exported, but no production code imports it. That published construction surface is unused outside tests and implies a supported host contract that does not exist. Sibling session owners keep the equivalent host type module-private.

 

^{Triggered by project rule: Review rules}

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