Artifact / Function Map

Runner, Observer, Prompt Submission, and State Call Map

Focused review map for the messy path around prompt admission, active-run lifecycle, tmux submission, observer delivery, transcript normalization, and persisted runtime state. Level here means review depth, not TypeScript nesting: level 1 is the main entry or owner surface, then deeper helper layers fan out from it.

Primary Review Goal Spot duplication, confusing names, mixed ownership, deep heuristics
Core Slices prompt flow, steer flow, observer flow, tmux truth, runtime state, transcript cleanup
Key Files 8 files in the call-critical slice
Why This Exists Make deep helper sprawl reviewable without hopping file-by-file

Immediate Review Hotspots

The map below is not just an inventory. It is arranged to make hidden duplication and ownership leaks obvious. The most suspicious areas are already called out here before the full table.

Duplicate Submit Path
Two different entry stories converge on the same tmux submit primitive.
  • Normal prompt: executePromptDelivery -> enqueuePrompt -> executePrompt -> startRunMonitor -> monitorTmuxRun -> submitTmuxSessionInput
  • Steer or inject: submitSessionInput -> RunnerService.submitSessionInput -> submitTmuxSessionInput
  • The shared low-level truth is good, but the service names above it are misleading and asymmetrical.
Mixed Lifecycle Truth
SessionService.startRunMonitor owns too much at once.
  • It creates callbacks, mutates steeringReady, writes persisted runtime state, emits observer updates, and decides terminal settlement.
  • That means monitor signals, lifecycle truth, and surface delivery are entangled through callback glue.
Observer Split
Observer handling spans runtime core and channel rendering.
  • notifyRunObservers decides which updates should fire.
  • executePromptDelivery.onUpdate separately decides which ones become visible, when to hand off, and when to suppress.
  • This is a likely source of hidden side effects and stale preview bugs.
Heuristic Wall
cleanInteractionSnapshot fans out into many runner-specific heuristics.
  • Prompt stripping, chrome dropping, message block unwrapping, wrap repair, duplicate collapse.
  • It is useful but deep, heuristic-heavy, and easy to drift away from lifecycle truth.
State Writes Everywhere
Runtime state is mutated from multiple layers.
  • SessionService writes running, detached, idle.
  • RunnerService touches and clears session state during startup, interrupt, transcript capture, and direct submit.
  • executePromptDelivery writes reply and final markers through recordConversationReply.
Naming Drift
submitSessionInput sounds generic but is currently a session injection path.
  • Normal prompt flow does not use it.
  • Its current meaning is closer to injectSessionInput than a canonical prompt submit API.

Core Flows To Review First

Normal Prompt Flow
src/channels/message/interaction-processing.ts > executePromptDelivery > src/agents/runtime/agent-service.ts > AgentService.enqueuePrompt > src/agents/session/session-service.ts > SessionService.executePrompt > SessionService.startRunMonitor > src/runners/tmux/run-monitor.ts > monitorTmuxRun > src/runners/tmux/session-handshake.ts > submitTmuxSessionInput
Steer / Direct Inject Flow
src/channels/message/interaction-processing.ts > processChannelInteraction steer branches > src/agents/runtime/agent-service.ts > AgentService.submitSessionInput > src/agents/runtime/runner-service.ts > RunnerService.submitSessionInput > src/runners/tmux/session-handshake.ts > submitTmuxSessionInput
Observer / Preview Flow
SessionService.notifyRunObservers > observer.onUpdate callback registered by executePromptDelivery > preview render or suppress logic > recordConversationReply / message-tool handoff / queue-start rendering
Meaningful Output Flow
monitorTmuxRun > deriveRunningInteractionText > cleanInteractionSnapshot > prompt stripping / chrome stripping / unwrap helpers / duplicate collapse > extractScrolledAppend
Startup / Resume Truth Flow
RunnerService.ensureSessionReady > waitForTmuxSessionBootstrap > finalizeSessionStartup > verifySessionReady > syncSessionIdentity or touchSessionEntry

Full Function Table

Search works across file, function, description, tags, called-by, and call-chain text. Use the filters to isolate deep heuristics, state sinks, tmux submit paths, or observer logic.

high complexity or high confusion mixed responsibility or likely duplication deep helper chain level = review depth from owner surface
File / Function Level Description Called By Functions Call Functions Concerns / Tags

Suggested review order: executePromptDelivery, SessionService.executePrompt, SessionService.startRunMonitor, monitorTmuxRun, submitTmuxSessionInput, RunnerService.ensureSessionReady, then the normalization chain rooted at cleanInteractionSnapshot.