Add auto refine review hook

[sethkarten]

Adds an opt-in automatic refine review hook that asks whether existing /refine should run after configured turn intervals or compaction checkpoints.\n\nValidation:\n- npx tsx ../../node_modules/vitest/dist/cli.js --run test/suite/agent-session-queue.test.ts\n- npm run check

Note

Add auto-refine review hook and local/global harness scope to AgentSession

• Adds an optional autoRefineReviewer hook to AgentSessionConfig that gates automatic /refine runs (triggered by turn intervals or compaction) through an LLM or custom callback, returning whether to proceed and optional instructions.
• Introduces local vs. global harness state scoping throughout: HarnessState entries carry a scope field, CRUD methods accept a global_ flag, and subprocess environments now receive both RLM_HARNESS_STATE_DIR (local) and RLM_GLOBAL_HARNESS_STATE_DIR.
• The /refine command gains a --global flag in interactive mode; the flag propagates through the RPC, daemon, and in-process connection layers.
• AgentSession._refine merges global and session-local harness states for planning and persists edits to the appropriate directory based on scope.
• Kernel bootstrap now validates that the Python runtime exposes scope on HarnessEntry and global_ on create_memory/get_harness_state before marking ready.
• Risk: local refinement now requires a persisted session artifact directory and throws if none is available; RLM_HARNESS_STATE_DIR semantics have changed (now local-only, was formerly global).

Changes since #201 opened

• Added AgentSession._localHarnessStateDir() helper method and refactored AgentSession system prompt builder, AgentSession._autoRefineAllowedForSession(), AgentSession._reviewAutoRefine(), AgentSession.refine(), and AgentSession._rlmKernelEnv() to use the helper for resolving local harness state directories [ceba951]
• Added test case verifying that ephemeral RLM session harness paths are loaded into the AgentSession system prompt [ceba951]
• Added serialization of concurrent AgentSession.refine calls to ensure only one refine operation executes at a time [8f9ab3f]
• Implemented cancellation infrastructure for scheduled post-compaction continuation in AgentSession [8f9ab3f]
• Integrated post-compaction continuation cancellation into auto-refine discard and branch change flows [8f9ab3f]
• Added test coverage for post-compaction continuation cancellation and refine serialization [8f9ab3f]
• Added abort and cooldown mechanisms to auto-refine lifecycle in AgentSession [027d0a9]
• Added wait-for-refine-idle synchronization before agent prompting in AgentSession [027d0a9]
• Added local write validation and environment handling to Python harness state in rlm package [027d0a9]
• Extracted harness state and refinement history loading into helper methods in AgentSession [027d0a9]
• Clarified docstring for appendGlobalRefinement utility in coding-agent refinement module [027d0a9]
• Changed AgentSession._invalidatePendingAutoRefineForBranchChange to async and extended to abort any in-progress auto-refine review via controller, discard pending auto-refine state with cancellation of post-compaction continuation, reset assistant turn count and increment branch version, then wait for refine to become idle before proceeding [47689c9]
• Added cancellation of scheduled post-compaction continuation throughout auto-refine lifecycle in AgentSession [47689c9]
• Fixed AgentSession._maybeAutoRefine to set compact auto-refine pending flag to true when no model is selected and reason is 'compact' [47689c9]
• Updated agent-session-queue.test.ts test suite to reflect async signature of _invalidatePendingAutoRefineForBranchChange and added test coverage for compact auto-refine pending state when no model is selected [47689c9]
• Added AbortSignal support to auto-refine review flow [f9c1109]
• Modified turn-interval auto-refine checkpoint preservation during cooldown [f9c1109]
• Modified the AgentSession.compact method to defer cancellation of scheduled post-compaction continuations until after confirming the compaction process will proceed, preventing premature cancellation when compaction is skipped or aborted [99c4b0c]
• Made AgentSession._refine method abortable and disposal-aware [679f3ac]
• Fixed declined compact auto-refine review to preserve turn-interval state when interval is already due [679f3ac]
• Added tests for declined compact auto-refine preservation and in-flight refine disposal [679f3ac]
• Modified AgentSession.compact method to reschedule post-compaction continuations and trigger auto-refine after successful manual compaction [4000abe]
• Added test coverage for post-compaction continuation rescheduling behavior in AgentSession [4000abe]
• Removed call to AgentSession._cancelPostCompactionContinue() after compaction abort check [4b205e9]
• Modified AgentSession._maybeAutoRefine method to fall back to turn-interval review when compact auto-refine is disabled [97a495f]

^{Macroscope summarized f239702.}

---

Note

High Risk
Harness persistence semantics and RLM_HARNESS_STATE_DIR meaning changed (local vs former global default), with broad session/refine/compaction interaction; incorrect scope or rollback targeting could corrupt learned state across sessions.

Overview
Introduces an opt-in auto-refine path (settings default off) that, on main persisted sessions only, runs a model-backed or injectable review gate after assistant-turn intervals and compaction, then may invoke /refine with local-first instructions while respecting cooldowns, busy-agent deferral, branch invalidation, and coordination with post-compaction continue.

Continual harness storage is split into local (session artifact / RLM_HARNESS_STATE_DIR) vs global (RLM_GLOBAL_HARNESS_STATE_DIR); the system prompt and planning merge both, /refine accepts global / --global, rollbacks honor recorded paths and scope, and kernel/Python harness CRUD defaults local with global_=True for cross-session writes. AgentSession serializes concurrent refines, waits for refine idle before new turns, and aborts in-flight refine on dispose.

Docs, prompts, slash-command copy, and bootstrap readiness checks are updated for the new terminology and env semantics.

^{Reviewed by Cursor Bugbot for commit 97a495f. 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.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 99c4b0c. Configure here.}