fix(coding-agent): trigger agent REPL cleanup on compaction

[sethkarten]

Summary

• treat successful compaction as an agent-driven REPL garbage-collection checkpoint
• extend the persisted IPython-state notice with an explicit request to review the live namespace
• preserve variables, imports, and helpers needed for ongoing work while deleting stale variables and large intermediates with del
• ask the agent to run import gc; gc.collect() after cleanup instead of automatically clearing useful kernel state

This complements #551, which evicts compacted session-history payloads from the Node.js process. The subagent runtime cleanup and lifecycle policy remain isolated in #547 and #548.

Tests

• test/suite/agent-session-compaction.test.ts — 28 passed
• npm run check

Stacked on #551.

Note

Trigger kernel REPL cleanup via a maintenance role after compaction commits

• After a compaction is durably saved, AgentSession now runs a host-side kernel maintenance role (kernel-maintenance.ts) that executes cleanup cells against the already-running IPython kernel to reclaim stale REPL objects.
• prepareCompaction now accepts optional customInstructions and returns a maintenanceContextMessages array so the maintenance role has appropriate conversation context.
• A new _boundedKernelMaintenanceContext helper trims that context to fit within a token budget (capped at half the model context window, between 1024 and 32000 tokens), inserting a synthetic notice when truncation occurs.
• Object deletions are disabled when the kernel namespace probe fails or when the maintenance context is incomplete; maintenance is skipped entirely for extension-supplied compactions.
• Behavioral Change: the previous _notifyKernelStateAfterCompaction path that injected a hidden ipython_state message after compaction is removed and replaced by this active cleanup role.

Changes since #552 opened

• Modified kernel maintenance execution during compaction to run planning in parallel with summary generation but defer IPython tool invocation until after compaction commits [c9d4b6b]
• Implemented parallel auto-refinement planning during compaction with commit-gated application [c9d4b6b]
• Added refinement completion messages appended to session transcript after successful refinement operations [c9d4b6b]
• Renamed and generalized unpersisted message tracking from compaction-specific to all status messages [c9d4b6b]
• Removed unused imports and updated test suites to verify parallel maintenance and refinement behavior [c9d4b6b]
• Added infrastructure for deferring compact-triggered auto-refine operations with preserved pre-compaction snapshots [884b930]
• Modified auto-refine scheduling to defer compact-triggered refinements when the agent is busy or under cooldown [884b930]
• Modified refinement application to serialize apply phases across concurrent refinements and discard refinements when compaction fails [884b930]
• Modified compaction flow to include custom instructions in pre-compaction messages and preserve post-compaction continuations for deferred refinements [884b930]
• Updated cleanup methods to handle deferred compact-triggered refinement state [884b930]
• Added tests validating deferred compact-triggered refinement behavior [884b930]
• Decoupled approved review application from concurrent compaction apply gates and trajectory snapshots [45defa8]
• Added post-compaction idle detection and deferred auto-refine scheduling [45defa8]
• Prevented duplicate timer scheduling for pending concurrent compaction refines [45defa8]
• Updated test suite to validate decoupled auto-refine and post-compaction idle behavior [45defa8]
• Changed AgentSession._runSerializedRefineCheckpoint to process committed pending compaction snapshots synchronously at serialized boundaries instead of scheduling interactive timers, with guards to discard snapshots when settings.compact is disabled or commitState.value is false [ef45ddf]
• Extended AgentSession._runSerializedAutoRefineReview, AgentSession._runSerializedRefine, and the underlying plan method to accept and propagate trajectory messages from compaction snapshots through the review and refinement pipeline [ef45ddf]
• Changed AgentSession._drainPendingRefinementForDisposal to route disposal-time draining of committed compact snapshots through the serialized review and refine path [ef45ddf]
• Updated test interface SerializedInternals and added tests verifying serialized boundary consumption of deferred compact snapshots, disposal-time draining behavior, and skipping of uncommitted snapshots [ef45ddf]
• Introduced compaction-operation quiescence gate in AgentSession._runAutoCompaction method [21742f9]
• Added test case validating auto-refine application blocking during pre-prompt auto-compaction [21742f9]
• Modified AgentSession._drainPendingRefinementForDisposal method condition to require pending.commitState.value === true before triggering compact auto-refine review [b872434]
• Added test case validating that uncommitted compact snapshots are discarded during disposal and interval refines proceed [b872434]

^{Macroscope summarized ab2b7d9.}

---

Note

Medium Risk
Touches compaction, parent IPython kernel mutation, and auto-refine scheduling with many concurrency and commit-gating paths; mistakes could delete live REPL state or apply harness edits on failed compactions, though gates and tests target those cases.

Overview
Replaces post-compaction hidden ipython_state notices with an active kernel maintenance role (kernel-maintenance.ts) that plans against the full pre-compaction transcript in parallel with summary generation, but blocks parent ipython tool execution until the compaction entry is durably committed. Failed, cancelled, or extension-owned compactions cannot mutate the kernel; namespace deletes are disabled when the live-name probe fails or context is incomplete.

Compact-triggered auto-refine now snapshots the same pre-compaction trajectory, can plan in parallel, and applies only after a successful commit via an applyGate; deferred snapshots survive busy/cooldown/serialized boundaries and disposal. Successful refinements append a durable session completion message listing harness edits; unpersisted status messages are generalized beyond compaction outcomes.

prepareCompaction gains optional customInstructions and maintenanceContextMessages for the maintenance role. Auto-compaction publishes a _compactionOperation quiescence gate so refinement apply does not race session rewrites.

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

[snimu]

I really like a cleanup phase, but I'm wondering if we should rather make compaction a two-step process, of first cleaning up the kernel and then writing the summary, or the other way around; rather than compacting and then having the new agent clean up the kernel.

That would avoid a situation where the summary references kernel state that the new agent cleans up. Which is mostly fine and should work, but I'm worried that it takes a bit of model capacity to keep the contradiction in mind, and I'd rather have that model capacity spent somewhere else.

My goal is to keep the post-compaction model as fresh and clean as possible and let it focus only on its actual work.

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

[sethkarten]

superseded by v0.5.0