Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

add a harness refinements toggle in settings (#3578)

ktf0c2d328ab78
diff --git a/.changes/harness-refinements-setting.md b/.changes/harness-refinements-setting.md
new file mode 100644
index 0000000000..c70a55b2be
--- /dev/null
+++ b/.changes/harness-refinements-setting.md
@@ -0,0 +1,4 @@
+- Add an enabled-by-default, global-only **Harness refinements** toggle in `/settings` → **Agents**. Project settings cannot override it. Turning it off prevents refinement generation and loading saved harness rows into future model requests; existing saved state is preserved.
+- Disabled `refine.run()` requests report a refusal without scheduling work. Plans completed while disabled are discarded. Undelivered digests are deferred until a turn admitted with refinements enabled; toggling does not re-arm a consumed digest.
+- Earlier replies and summary prose may already reflect refinements, and sent requests cannot be recalled. Start a new disabled session for a conversation that has never used saved refinements.
+- Factory execution also requires harness access for stored specs and subagent references: `factory.run()` refuses while refinements are off, including library-machine lookup. It does not start children or change saved state.
diff --git a/crates/pa-cli/src/client_settings.rs b/crates/pa-cli/src/client_settings.rs
index 5aeeaaeded..bfd09b0154 100644
--- a/crates/pa-cli/src/client_settings.rs
+++ b/crates/pa-cli/src/client_settings.rs
@@ -49,6 +49,26 @@ macro_rules! str_setting {
}
impl ClientSettings for CliClientSettings {
+ fn harness_refinements(&self) -> bool {
+ self.manager().get_harness_refinements()
+ }
+
+ fn set_harness_refinements(&self, enabled: bool) -> Result<()> {
+ let mut manager = self.manager();
+ manager.set_harness_refinements(enabled)?;
+ // Adoption bookkeeping stays off the UI input/paint path.
+ if let Ok(runtime) = tokio::runtime::Handle::try_current() {
+ let agent_dir = self.agent_dir.clone();
+ runtime.spawn_blocking(move || {
+ let client = pa_core::session_engine::telemetry::build_client(&manager, &agent_dir);
+ let mut properties = pa_telemetry::Properties::new();
+ properties.set("enabled", serde_json::json!(enabled));
+ client.track("harness refinements changed", properties);
+ });
+ }
+ Ok(())
+ }
+
fn compaction_threshold_percent(&self) -> f64 {
self.manager().get_compaction_threshold_percent()
}
diff --git a/crates/pa-core/src/refinement/mod.rs b/crates/pa-core/src/refinement/mod.rs
index 309a1f00b7..47f168b204 100644
--- a/crates/pa-core/src/refinement/mod.rs
+++ b/crates/pa-core/src/refinement/mod.rs
@@ -301,6 +301,15 @@ pub fn update_harness_state<R>(
harness_state_dir: &Path,
scope: HarnessScope,
update: impl FnOnce(&mut HarnessState) -> R,
+) -> anyhow::Result<(R, PathBuf)> {
+ try_update_harness_state(harness_state_dir, scope, |state| Ok(update(state)))
+}
+
+/// A rejected update must exit before saving, including an apply-time setting gate.
+pub(crate) fn try_update_harness_state<R>(
+ harness_state_dir: &Path,
+ scope: HarnessScope,
+ update: impl FnOnce(&mut HarnessState) -> anyhow::Result<R>,
) -> anyhow::Result<(R, PathBuf)> {
std::fs::create_dir_all(harness_state_dir)?;
let state_path = get_harness_state_path(harness_state_dir);
@@ -311,7 +320,7 @@ pub fn update_harness_state<R>(
std::time::Duration::from_millis(20),
)?;
let mut state = load_harness_state(harness_state_dir, scope);
- let result = update(&mut state);
+ let result = update(&mut state)?;
lock.ensure_owned()?;
let written = save_harness_state(harness_state_dir, &state)?;
Ok((result, written))
@@ -591,6 +600,21 @@ mod tests {
}
}
+ #[test]
+ fn rejected_harness_update_preserves_saved_state() {
+ let dir = tempfile::tempdir().unwrap();
+ let state = empty_harness_state();
+ let path = save_harness_state(dir.path(), &state).unwrap();
+ let before = std::fs::read(&path).unwrap();
+ let result: anyhow::Result<((), PathBuf)> =
+ try_update_harness_state(dir.path(), HarnessScope::Global, |state| {
+ state.schema = 99;
+ anyhow::bail!("disabled before commit")
+ });
+ assert!(result.is_err());
+ assert_eq!(std::fs::read(path).unwrap(), before);
+ }
+
#[test]
fn factory_opt_in_reads_leniently_and_fails_closed() {
let tmp = tempfile::tempdir().unwrap();
diff --git a/crates/pa-core/src/session_engine/branch_summarization.rs b/crates/pa-core/src/session_engine/branch_summarization.rs
index 673d5d24e8..642edab5b4 100644
--- a/crates/pa-core/src/session_engine/branch_summarization.rs
+++ b/crates/pa-core/src/session_engine/branch_summarization.rs
@@ -149,6 +149,14 @@ fn get_message_from_entry(entry: &FileEntry) -> Option<AgentMessage> {
/// is hit. File ops are collected from ALL entries (cumulative tracking).
#[must_use]
pub fn prepare_branch_entries(entries: &[FileEntry], token_budget: u64) -> BranchPreparation {
+ prepare_branch_entries_with_refinements(entries, token_budget, /*enabled*/ true)
+}
+
+fn prepare_branch_entries_with_refinements(
+ entries: &[FileEntry],
+ token_budget: u64,
+ enabled: bool,
+) -> BranchPreparation {
let mut file_ops = FileOperations::default();
// Cumulative tracking from prior branch summaries (never hooked ones).
for entry in entries {
@@ -169,6 +177,17 @@ pub fn prepare_branch_entries(entries: &[FileEntry], token_budget: u64) -> Branc
let Some(message) = get_message_from_entry(entry) else {
continue;
};
+ // Disabled harness content must not consume budget or terminate selection.
+ let message = if enabled {
+ Some(message)
+ } else {
+ super::refinement_gate::without_refinements(vec![message])
+ .into_iter()
+ .next()
+ };
+ let Some(message) = message else {
+ continue;
+ };
extract_file_ops_from_message(&message, &mut file_ops);
let tokens = estimate_tokens(&message);
if token_budget > 0 && total_tokens + tokens > token_budget {
@@ -205,7 +224,23 @@ pub fn build_branch_summary_request(
custom_instructions: Option<&str>,
replace_instructions: bool,
) -> (Vec<AgentMessage>, BranchPreparation) {
- let preparation = prepare_branch_entries(entries, token_budget);
+ build_branch_summary_request_with_refinements(
+ entries,
+ token_budget,
+ custom_instructions,
+ replace_instructions,
+ /*enabled*/ true,
+ )
+}
+
+fn build_branch_summary_request_with_refinements(
+ entries: &[FileEntry],
+ token_budget: u64,
+ custom_instructions: Option<&str>,
+ replace_instructions: bool,
+ enabled: bool,
+) -> (Vec<AgentMessage>, BranchPreparation) {
+ let preparation = prepare_branch_entries_with_refinements(entries, token_budget, enabled);
let messages = if preparation.messages.is_empty() {
Vec::new()
} else {
@@ -371,11 +406,25 @@ pub async fn generate_branch_summary(
128_000
};
let token_budget = context_window.saturating_sub(reserve_tokens);
- let (request_messages, preparation) = build_branch_summary_request(
+ let enabled = match auxiliary {
+ Some(context) => {
+ let context = context.clone();
+ tokio::task::spawn_blocking(move || {
+ let settings =
+ crate::settings::SettingsManager::create(&context.cwd, &context.agent_dir);
+ super::refinement_gate::enabled(Some(&settings))
+ })
+ .await
+ .unwrap_or(false)
+ }
+ None => true,
+ };
+ let (request_messages, preparation) = build_branch_summary_request_with_refinements(
entries,
token_budget,
custom_instructions,
replace_instructions,
+ enabled,
);
if request_messages.is_empty() {
let (read_files, modified_files) = compute_file_lists(&preparation.file_ops);
@@ -416,7 +465,7 @@ pub async fn generate_branch_summary(
return BranchSummaryResult {
error: Some(format!("{error:#}")),
..Default::default()
- }
+ };
}
};
if response.stop_reason == pa_types::ai::StopReason::Aborted {
@@ -481,6 +530,42 @@ mod tests {
})
}
+ #[test]
+ fn disabled_refinement_notices_cannot_exhaust_the_branch_summary_budget() {
+ let tmp = tempfile::tempdir().unwrap();
+ let mut session = crate::session::manager::SessionManager::in_memory(tmp.path());
+ let conversation = user("Earlier conversation about the task");
+ session.append_message(conversation.clone()).unwrap();
+ session
+ .append_custom_message(
+ "refinement_notice",
+ pa_types::ai::UserContent::Text("saved refinement ".repeat(500)),
+ /*display*/ false,
+ None,
+ )
+ .unwrap();
+ let (request, preparation) = build_branch_summary_request_with_refinements(
+ session.retained_entries(),
+ 50,
+ None,
+ /*replace_instructions*/ false,
+ /*enabled*/ false,
+ );
+ assert_eq!(preparation.messages, vec![conversation]);
+ assert!(!request.is_empty());
+ let (enabled_request, _) = build_branch_summary_request_with_refinements(
+ session.retained_entries(),
+ 50,
+ None,
+ /*replace_instructions*/ false,
+ /*enabled*/ true,
+ );
+ assert!(
+ enabled_request.is_empty(),
+ "the enabled legacy budget path selects no older rows"
+ );
+ }
+
#[test]
fn collects_old_branch_to_common_ancestor() {
// root -> u1 -> a1 -> u2 (old leaf)
diff --git a/crates/pa-core/src/session_engine/compact_session.rs b/crates/pa-core/src/session_engine/compact_session.rs
index d2e1ed00d6..270d639a7a 100644
--- a/crates/pa-core/src/session_engine/compact_session.rs
+++ b/crates/pa-core/src/session_engine/compact_session.rs
@@ -128,8 +128,8 @@ pub(crate) struct CompactionAttempt {
cut: CutPointResult,
previous_summary: Option<String>,
recent_state_anchor: Option<String>,
- history: Vec<AgentMessage>,
- turn_prefix_messages: Vec<AgentMessage>,
+ pub(crate) history: Vec<AgentMessage>,
+ pub(crate) turn_prefix_messages: Vec<AgentMessage>,
tokens_before: u64,
details: CompactionDetails,
first_kept_entry: String,
diff --git a/crates/pa-core/src/session_engine/compaction_arms.rs b/crates/pa-core/src/session_engine/compaction_arms.rs
index 0493c2cacb..b1bce19367 100644
--- a/crates/pa-core/src/session_engine/compaction_arms.rs
+++ b/crates/pa-core/src/session_engine/compaction_arms.rs
@@ -262,6 +262,11 @@ impl AgentSession {
// once before the loop would rank the abandoned branch's
// terms. The capture takes the session lock itself, so it
// runs off the prepare hold.
+ if !self.harness_refinements_enabled() {
+ attempt.history = super::refinement_gate::without_refinements(attempt.history);
+ attempt.turn_prefix_messages =
+ super::refinement_gate::without_refinements(attempt.turn_prefix_messages);
+ }
let digest_inputs = self.harness_digest_inputs().await;
compaction_trace::trace("compact.digest_captured", &serde_json::Value::Null);
let attempt_options = crate::session_engine::compact_session::CompactOptions {
@@ -275,11 +280,16 @@ impl AgentSession {
summary_delta: options.summary_delta.clone(),
semantic_edges: options.semantic_edges.clone(),
};
- let prepared = crate::session_engine::compact_session::summarize_attempt(
+ let mut prepared = crate::session_engine::compact_session::summarize_attempt(
&attempt,
&attempt_options,
)
.await?;
+ // A toggle during the summarizer request must not re-inject the captured digest.
+ if !self.harness_refinements_enabled() {
+ prepared.entry.harness_digest = None;
+ prepared.entry.harness_state_fingerprint = None;
+ }
let committed = {
let mut session = self.session.lock().await;
crate::session_engine::compact_session::commit_attempt(
diff --git a/crates/pa-core/src/session_engine/engine.rs b/crates/pa-core/src/session_engine/engine.rs
index 85963eb3e7..800b5a8154 100644
--- a/crates/pa-core/src/session_engine/engine.rs
+++ b/crates/pa-core/src/session_engine/engine.rs
@@ -243,6 +243,7 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
config.cron_store.clone(),
);
+ let refinement_settings = settings.reopen();
let service_tier_preference = settings.get_default_service_tier();
// Captured before `settings` moves into the resource loader: the
// compaction budget and the auto-refine gates.
@@ -347,6 +348,9 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
// serve live views per request.
crate::mcp::McpManager::register_host_handlers(&mcp_manager, &mut handlers);
let turn_boundary = Arc::new(super::turn_boundary::TurnBoundaryRequests::new());
+ let _ = turn_boundary
+ .refinement_settings
+ .set(refinement_settings.reopen());
turn_boundary.register_model_info_handler(&mut handlers, model_info.clone());
let keep_recent_tokens = compaction_settings
.keep_recent_tokens
@@ -560,6 +564,11 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
let (existing_messages, has_thinking_entry, has_service_tier_entry) = {
let session = wiring.session.lock().await;
let messages = super::compact_session::rebuilt_context_after_compaction(&session);
+ let messages = if super::refinement_gate::enabled(Some(&refinement_settings)) {
+ messages
+ } else {
+ super::refinement_gate::without_refinements(messages)
+ };
let has_thinking_entry = session.has_thinking_level();
let has_service_tier_entry = session.has_service_tier();
(messages, has_thinking_entry, has_service_tier_entry)
@@ -639,7 +648,7 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
// else (the harness digest included) becomes a user turn.
convert_to_llm: Some(super::request_timing::instrument_convert_to_llm(
std::sync::Arc::clone(&request_timing_wiring),
- super::messages::engine_convert_to_llm(),
+ super::refinement_gate::convert_to_llm(refinement_settings.reopen()),
)),
// The Rust engine wires no transform, so the instrumented seam
// wraps a pass-through that marks the turn's dispatch moment.
@@ -689,11 +698,22 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
agent.clone(),
wiring.session.clone(),
resources.prompts.clone(),
- Some(digest_context),
+ super::refinement_gate::enabled(Some(&refinement_settings))
+ .then_some(digest_context.clone()),
)
.await?;
session.set_auto_refine(auto_refine_allowed, auto_refine_gates);
session.set_agent_dir(config.agent_dir.clone());
+ // Keep the context descriptor even while disabled, so re-enabling can load it.
+ session.harness_digest = Some(digest_context);
+ session.refinement_settings = Some(refinement_settings);
+ // A disabled startup has never delivered its filtered digest. Defer that
+ // first delivery without re-arming digests already consumed in a live session.
+ if !session.harness_refinements_enabled() {
+ session
+ .digest_pending
+ .store(true, std::sync::atomic::Ordering::SeqCst);
+ }
// Every compaction path reads the session's resolved compaction
// settings (TS `getCompactionSettings`): `/compact` matches the
// `compact.*` turn-boundary tool's `keepRecentTokens`/`reserveTokens`.
diff --git a/crates/pa-core/src/session_engine/harness_digest.rs b/crates/pa-core/src/session_engine/harness_digest.rs
index e1245d7bca..4f7bb203f6 100644
--- a/crates/pa-core/src/session_engine/harness_digest.rs
+++ b/crates/pa-core/src/session_engine/harness_digest.rs
@@ -456,8 +456,13 @@ impl super::AgentSession {
}
/// The deferred first-turn digest as the prompt row that rides the turn's
- /// admission; the pending flag is consumed either way.
+ /// admission; disabled sessions defer the pending flag until enabled.
pub(crate) async fn pending_digest_prompt_row(&self) -> anyhow::Result<Option<AgentMessage>> {
+ // Preserve the pending flag while disabled; a consumed delivery must
+ // never be re-armed merely by toggling the setting off and on.
+ if !self.harness_refinements_enabled() {
+ return Ok(None);
+ }
if !self
.digest_pending
.swap(false, std::sync::atomic::Ordering::SeqCst)
@@ -477,6 +482,9 @@ impl super::AgentSession {
/// relevance terms. `None` when the session carries no harness state; the
/// disk read stays deferred to render time, so a snapshot reads fresh state.
pub(crate) async fn harness_digest_inputs(&self) -> Option<HarnessDigestInputs> {
+ if !self.harness_refinements_enabled() {
+ return None;
+ }
let context = self.harness_digest.clone()?;
let recent_texts = self.recent_message_texts_newest_first().await;
let goal = {
diff --git a/crates/pa-core/src/session_engine/mod.rs b/crates/pa-core/src/session_engine/mod.rs
index e1c1e2b611..b3772c47d1 100644
--- a/crates/pa-core/src/session_engine/mod.rs
+++ b/crates/pa-core/src/session_engine/mod.rs
@@ -28,6 +28,7 @@ pub mod provider_failover;
pub mod provider_park;
pub mod provider_retry;
pub mod refine;
+mod refinement_gate;
pub mod request_timing;
pub mod rlm_host;
pub mod rlm_notices;
@@ -135,6 +136,7 @@ pub struct AgentSession {
/// Whether this session may auto-refine; defaults off until the
/// engine wiring resolves it.
auto_refine_allowed: bool,
+ refinement_settings: Option<crate::settings::SettingsManager>,
/// The resolved auto-refine gates; the compact trigger reads them.
auto_refine: refine::AutoRefineGates,
/// Session-side auto-refine state the transport surfaces arm and
@@ -237,6 +239,7 @@ impl AgentSession {
compaction: std::sync::RwLock::new(compaction::CompactionSettings::default()),
auxiliary_model: None,
auto_refine_allowed: false,
+ refinement_settings: None,
auto_refine: refine::AutoRefineGates::default(),
compact_auto_refine: std::sync::Mutex::default(),
kernel_state: None,
diff --git a/crates/pa-core/src/session_engine/refine.rs b/crates/pa-core/src/session_engine/refine.rs
index 90b8747908..20d6a856e0 100644
--- a/crates/pa-core/src/session_engine/refine.rs
+++ b/crates/pa-core/src/session_engine/refine.rs
@@ -14,7 +14,8 @@ use crate::refinement::executor::{
};
use crate::refinement::{
append_global_refinement, format_refinement_notice_body, load_global_refinement_history,
- load_harness_state, merge_harness_states, update_harness_state, HarnessScope, RefinementResult,
+ load_harness_state, merge_harness_states, try_update_harness_state, HarnessScope,
+ RefinementResult,
};
use crate::session::manager::SessionManager;
@@ -308,6 +309,24 @@ pub async fn execute_refinement_with_rows(
refine_call: crate::refinement::executor::RefinerFn,
agent_dir: Option<&Path>,
) -> anyhow::Result<(RefinementResult, Vec<String>)> {
+ let settings = match agent_dir {
+ Some(dir) => {
+ let cwd = session.get_cwd().to_path_buf();
+ let dir = dir.to_path_buf();
+ Some(
+ tokio::task::spawn_blocking(move || {
+ let settings = crate::settings::SettingsManager::create(&cwd, &dir);
+ anyhow::ensure!(
+ super::refinement_gate::enabled(Some(&settings)),
+ "Harness refinements are disabled in /settings"
+ );
+ Ok::<_, anyhow::Error>(settings)
+ })
+ .await??,
+ )
+ }
+ None => None,
+ };
let RefinementTranscript {
messages,
refinement_history,
@@ -393,14 +412,18 @@ pub async fn execute_refinement_with_rows(
None => false,
};
let (mut result, state_path) = tokio::task::spawn_blocking(move || {
- update_harness_state(&target_dir, target_scope, |state| {
- apply_refinement_plan(
+ try_update_harness_state(&target_dir, target_scope, |state| {
+ anyhow::ensure!(
+ super::refinement_gate::enabled(settings.as_ref()),
+ "Harness refinements were disabled during planning; the result was discarded"
+ );
+ Ok(apply_refinement_plan(
state,
plan,
&core_options,
Some(baseline_state),
factory_enabled,
- )
+ ))
})
})
.await
@@ -481,6 +504,9 @@ impl AgentSession {
turns_since_last_review: u32,
branch_version: u64,
) -> anyhow::Result<Option<AutoRefineReview>> {
+ if !self.harness_refinements_enabled() {
+ return Ok(None);
+ }
// The review reads the same planning inputs the run plans
// against, extracted under this lock from the retained rows.
let (parts, merged_state, history) = {
@@ -698,6 +724,48 @@ mod tests {
})
}
+ #[tokio::test]
+ async fn disabling_refinements_blocks_planning_and_discards_in_flight_results() {
+ let dir = TempDir::new().unwrap();
+ let mut session = persisted_session(&dir);
+ let global_dir = dir.path().join("harness");
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).unwrap();
+ let settings = agent_dir.join("settings.json");
+ std::fs::write(&settings, r#"{"harnessRefinements":false}"#).unwrap();
+ let entries_before = session.retained_entries().to_vec();
+ let error = execute_refinement(
+ &mut session,
+ RefinementTranscript {
+ messages: &[],
+ refinement_history: &[],
+ },
+ &global_dir,
+ &test_model(),
+ &RefineOptions::default(),
+ RefinementSource::User,
+ Box::new(|_, _, _| panic!("disabled refinement must not call the planner")),
+ Some(&agent_dir),
+ )
+ .await
+ .unwrap_err();
+ assert!(error.to_string().contains("disabled"));
+ std::fs::write(&settings, r#"{"harnessRefinements":true}"#).unwrap();
+ let error = execute_refinement(
+ &mut session, RefinementTranscript { messages: &[user_message("remember this")], refinement_history: &[] },
+ &global_dir, &test_model(), &RefineOptions::default(), RefinementSource::SelfRefine,
+ flip_seam(&settings, r#"{"harnessRefinements":false}"#,
+ r#"{"summary":"memory","edits":[{"action":"create","kind":"memory","id":"note","title":"Note","content":"Remember this"}]}"#),
+ Some(&agent_dir),
+ ).await.unwrap_err();
+ assert!(error.to_string().contains("discarded"));
+ assert_eq!(session.retained_entries(), entries_before.as_slice());
+ assert!(!local_harness_state_dir(&session)
+ .join("harness_state.json")
+ .exists());
+ assert!(!global_dir.exists());
+ }
+
#[test]
fn refinement_messages_match_wire_shape() {
let result = RefinementResult {
diff --git a/crates/pa-core/src/session_engine/refinement_gate.rs b/crates/pa-core/src/session_engine/refinement_gate.rs
new file mode 100644
index 0000000000..57b2700c30
--- /dev/null
+++ b/crates/pa-core/src/session_engine/refinement_gate.rs
@@ -0,0 +1,221 @@
+//! The live master switch and model-boundary filtering. Durable history is untouched.
+
+use pa_types::session::AgentMessage;
+
+/// The single live policy read for scheduling, planning, apply, and context delivery.
+pub(crate) fn enabled(settings: Option<&crate::settings::SettingsManager>) -> bool {
+ settings.is_none_or(|settings| settings.reopen().get_harness_refinements())
+}
+
+impl super::AgentSession {
+ pub(crate) fn harness_refinements_enabled(&self) -> bool {
+ enabled(self.refinement_settings.as_ref())
+ }
+}
+
+/// Remove only typed harness rows; never interpret a user's quoted text as metadata.
+pub(crate) fn without_refinements(messages: Vec<AgentMessage>) -> Vec<AgentMessage> {
+ messages
+ .into_iter()
+ .filter_map(|message| match message {
+ AgentMessage::Custom(custom)
+ if matches!(
+ custom.custom_type.as_str(),
+ "harness_digest" | "refinement_notice" | "refinement_outcome"
+ ) =>
+ {
+ None
+ }
+ AgentMessage::CompactionSummary(mut summary) => {
+ summary.harness_digest = None;
+ summary.harness_state_fingerprint = None;
+ Some(AgentMessage::CompactionSummary(summary))
+ }
+ message @ (AgentMessage::User(_)
+ | AgentMessage::Assistant(_)
+ | AgentMessage::ToolResult(_)
+ | AgentMessage::BashExecution(_)
+ | AgentMessage::Custom(_)
+ | AgentMessage::BranchSummary(_)) => Some(message),
+ })
+ .collect()
+}
+
+/// Resolve at every provider request, including tool continuations and retries.
+/// I/O runs off the async worker. Filtering precedes conversion while provenance is typed.
+pub(crate) fn convert_to_llm(
+ settings: crate::settings::SettingsManager,
+) -> pa_agent::agent_loop::ConvertToLlmFn {
+ let settings = std::sync::Arc::new(settings);
+ std::sync::Arc::new(move |messages| {
+ let settings = std::sync::Arc::clone(&settings);
+ Box::pin(async move {
+ let enabled = tokio::task::spawn_blocking(move || enabled(Some(&settings))).await?;
+ let messages = if enabled {
+ messages
+ } else {
+ messages
+ .into_iter()
+ .filter_map(|message| match message {
+ pa_agent::types::AgentMessage::Custom(custom) => {
+ let typed =
+ serde_json::from_value(serde_json::to_value(custom).ok()?).ok()?;
+ without_refinements(vec![typed])
+ .into_iter()
+ .next()
+ .and_then(|row| super::session_message_to_loop(&row))
+ }
+ message @ pa_agent::types::AgentMessage::Standard(_) => Some(message),
+ })
+ .collect()
+ };
+ Ok(super::messages::loop_convert_to_llm(messages))
+ })
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::settings::SettingsManager;
+ use pa_types::ai::{UserContent, UserMessage};
+
+ fn user(text: &str) -> AgentMessage {
+ AgentMessage::User(UserMessage {
+ content: UserContent::Text(text.to_string()),
+ timestamp: 0,
+ rest: serde_json::Map::default(),
+ })
+ }
+
+ #[tokio::test]
+ async fn live_request_gate_filters_saved_rows_and_preserves_quoted_user_content() {
+ let tmp = tempfile::tempdir().unwrap();
+ let mut settings = SettingsManager::create(tmp.path(), tmp.path().join("agent"));
+ let convert = convert_to_llm(settings.reopen());
+ let digest =
+ super::super::harness_digest::harness_digest_prompt_row("saved memory", 1, "fp");
+ let quote =
+ super::super::session_message_to_loop(&user("[harness-digest] quoted user content"))
+ .unwrap();
+ let messages = vec![digest.clone(), quote.clone()];
+ assert_eq!(convert(messages.clone()).await.unwrap().len(), 2);
+ settings.set_harness_refinements(false).unwrap();
+ let expected = super::super::messages::loop_convert_to_llm(vec![quote]);
+ assert_eq!(convert(messages.clone()).await.unwrap(), expected);
+ settings.set_harness_refinements(true).unwrap();
+ assert_eq!(convert(messages).await.unwrap().len(), 2);
+ }
+
+ #[tokio::test]
+ async fn cold_and_resumed_disabled_sessions_omit_saved_harness_context() {
+ let tmp = tempfile::tempdir().unwrap();
+ let agent_dir = tmp.path().join("agent");
+ let mut settings = SettingsManager::create(tmp.path(), &agent_dir);
+ settings.set_harness_refinements(false).unwrap();
+ let model: pa_agent::types::Model = serde_json::from_value(serde_json::json!({
+ "id":"m", "name":"m", "api":"test", "provider":"test", "baseUrl":"http://localhost",
+ "reasoning":false, "cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},
+ "contextWindow":10000, "maxTokens":100
+ }))
+ .unwrap();
+ for resumed in [false, true] {
+ let mut manager = crate::session::manager::SessionManager::in_memory(tmp.path());
+ manager.materialize_session_file(Some(tmp.path().join(if resumed {
+ "resumed"
+ } else {
+ "cold"
+ })));
+ if resumed {
+ manager
+ .append_custom_message(
+ "harness_digest",
+ UserContent::Text("saved memory".to_string()),
+ false,
+ None,
+ )
+ .unwrap();
+ manager.append_message(user("Continue my work")).unwrap();
+ }
+ let provider =
+ std::sync::Arc::new(pa_agent::scripted::ScriptedProvider::new(model.clone()));
+ let engine =
+ super::super::engine::create_session(super::super::engine::SessionEngineConfig {
+ cwd: tmp.path().to_path_buf(),
+ agent_dir: agent_dir.clone(),
+ model: Some(model.clone()),
+ stream_fn: Some(provider.stream_fn()),
+ session_manager: Some(manager),
+ daemonless: true,
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+ assert!(!engine.session.auto_refine_allowed());
+ assert!(engine.session.harness_digest_inputs().await.is_none());
+ assert!(engine
+ .session
+ .pending_digest_prompt_row()
+ .await
+ .unwrap()
+ .is_none());
+ let live = engine.session.agent().state().await.messages;
+ assert_eq!(
+ super::super::messages::loop_convert_to_llm(live).len(),
+ usize::from(resumed)
+ );
+ // Re-enable without a reload (the busy-session case): the next admission loads state.
+ settings.set_harness_refinements(true).unwrap();
+ assert!(engine.session.auto_refine_allowed());
+ assert!(engine
+ .session
+ .pending_digest_prompt_row()
+ .await
+ .unwrap()
+ .is_some());
+ settings.set_harness_refinements(false).unwrap();
+ assert!(engine
+ .session
+ .pending_digest_prompt_row()
+ .await
+ .unwrap()
+ .is_none());
+ settings.set_harness_refinements(true).unwrap();
+ assert!(
+ engine
+ .session
+ .pending_digest_prompt_row()
+ .await
+ .unwrap()
+ .is_none(),
+ "a consumed digest must not be re-armed by disabling and enabling"
+ );
+ settings.set_harness_refinements(false).unwrap();
+ // The history remains inspectable even though it is absent from model context.
+ if resumed {
+ assert!(engine.session.entries().await.iter().any(|entry| matches!(entry,
+ pa_types::session::FileEntry::CustomMessage { payload, .. } if payload.custom_type == "harness_digest")));
+ }
+ }
+ }
+
+ #[test]
+ fn disabled_context_removes_compaction_digest_but_keeps_the_summary() {
+ let summary = pa_types::session::CompactionSummaryMessage {
+ summary: "Earlier decisions still apply".to_string(),
+ tokens_before: 10,
+ retained_message_count: None,
+ custom_instructions: None,
+ harness_digest: Some("saved memory".to_string()),
+ harness_state_fingerprint: Some("fp".to_string()),
+ timestamp: 0,
+ };
+ let mut expected = summary.clone();
+ expected.harness_digest = None;
+ expected.harness_state_fingerprint = None;
+ assert_eq!(
+ without_refinements(vec![AgentMessage::CompactionSummary(summary)]),
+ vec![AgentMessage::CompactionSummary(expected)]
+ );
+ }
+}
diff --git a/crates/pa-core/src/session_engine/turn_boundary.rs b/crates/pa-core/src/session_engine/turn_boundary.rs
index 79bffd5e71..78e3df0f95 100644
--- a/crates/pa-core/src/session_engine/turn_boundary.rs
+++ b/crates/pa-core/src/session_engine/turn_boundary.rs
@@ -67,6 +67,7 @@ pub struct ContextUsage {
/// shared between the host bridge and the turn loop; build it in `Arc` form.
#[derive(Default)]
pub struct TurnBoundaryRequests {
+ pub(super) refinement_settings: std::sync::OnceLock<crate::settings::SettingsManager>,
/// The late-bound runtime; `bind` is first-wins, and `rebind_model_facts`
/// swaps the model facts after a live model switch.
runtime: std::sync::RwLock<Option<Arc<TurnBoundaryRuntime>>>,
@@ -348,6 +349,12 @@ impl TurnBoundaryRequests {
"no active turn; refine can only be requested while a turn is running",
));
}
+ let gate_requests = Arc::clone(&requests);
+ if !tokio::task::spawn_blocking(move || {
+ super::refinement_gate::enabled(gate_requests.refinement_settings.get())
+ }).await? {
+ return Ok(no_active_turn("Harness refinements are disabled in /settings"));
+ }
let mut slot = requests.refine.lock().await;
let merged = match slot.as_ref() {
Some(current) => PendingRefine {
diff --git a/crates/pa-core/src/session_engine/turn_boundary/tests.rs b/crates/pa-core/src/session_engine/turn_boundary/tests.rs
index f5af189ab3..742fd5e491 100644
--- a/crates/pa-core/src/session_engine/turn_boundary/tests.rs
+++ b/crates/pa-core/src/session_engine/turn_boundary/tests.rs
@@ -404,6 +404,64 @@ async fn refine_run_and_status_round_trip_inside_a_tool_call() {
assert!(requests.take_refine().await.is_none());
}
+#[tokio::test]
+async fn disabled_refine_run_reports_refusal_and_does_not_schedule() {
+ let dir = tempfile::tempdir().unwrap();
+ let mut settings =
+ crate::settings::SettingsManager::create(dir.path(), dir.path().join("agent"));
+ settings.set_harness_refinements(false).unwrap();
+ let requests = Arc::new(TurnBoundaryRequests::new());
+ assert!(requests.refinement_settings.set(settings.reopen()).is_ok());
+ let provider = Arc::new(ScriptedProvider::new(agent_model()));
+ let probe = probe_tool(
+ &requests,
+ "probe",
+ "refine.run",
+ json!({"instructions":"remember this"}),
+ );
+ let agent = Arc::new(Agent::new(AgentOptions {
+ initial_state: AgentInitialState {
+ system_prompt: Some("s".to_string()),
+ model: Some(agent_model()),
+ tools: Some(vec![probe.tool.clone()]),
+ ..Default::default()
+ },
+ stream_fn: Some(provider.stream_fn()),
+ ..Default::default()
+ }));
+ requests.bind(TurnBoundaryRuntime {
+ agent: Arc::clone(&agent),
+ session: Arc::new(Mutex::new(session_with_history(false))),
+ context_window: Some(100_000),
+ model_info: model_info(),
+ });
+ provider.push_tool_call_turn(None, vec![("disabled-call", "probe", json!({}))]);
+ provider.push_text_turn("done");
+ agent.prompt("request a refinement").await.unwrap();
+ agent.wait_for_idle().await;
+ assert_eq!(
+ probe.result().await,
+ json!({
+ "scheduled":false,
+ "reason":"Harness refinements are disabled in /settings"
+ })
+ );
+ assert_eq!(requests.take_refine().await, None);
+ // The already-registered handler observes the live setting on the next turn.
+ settings.set_harness_refinements(true).unwrap();
+ provider.push_tool_call_turn(None, vec![("enabled-call", "probe", json!({}))]);
+ provider.push_text_turn("done");
+ agent.prompt("request a refinement again").await.unwrap();
+ agent.wait_for_idle().await;
+ assert_eq!(
+ requests.take_refine().await,
+ Some(PendingRefine {
+ instructions: Some("remember this".to_string()),
+ global: false
+ })
+ );
+}
+
#[tokio::test]
async fn refine_run_validates_and_merges_into_a_pending_request() {
let requests = Arc::new(TurnBoundaryRequests::new());
diff --git a/crates/pa-core/src/session_engine/wiring.rs b/crates/pa-core/src/session_engine/wiring.rs
index 167e1f5e62..862d6905bf 100644
--- a/crates/pa-core/src/session_engine/wiring.rs
+++ b/crates/pa-core/src/session_engine/wiring.rs
@@ -147,7 +147,7 @@ impl AgentSession {
/// Whether the session may run auto-refinement.
pub fn auto_refine_allowed(&self) -> bool {
- self.auto_refine_allowed
+ self.auto_refine_allowed && self.harness_refinements_enabled()
}
/// The resolved auto-refine gates.
diff --git a/crates/pa-core/src/settings/interactive_settings.rs b/crates/pa-core/src/settings/interactive_settings.rs
index a95f17ca42..9163468116 100644
--- a/crates/pa-core/src/settings/interactive_settings.rs
+++ b/crates/pa-core/src/settings/interactive_settings.rs
@@ -7,6 +7,22 @@ use anyhow::{anyhow, Result};
use super::manager::SettingsManager;
impl SettingsManager {
+ /// Global preference controlling refinement creation and context loading (default on).
+ /// Project settings cannot override the user's master switch.
+ #[must_use]
+ pub fn get_harness_refinements(&self) -> bool {
+ self.global_settings().harness_refinements.unwrap_or(true)
+ }
+
+ /// Persist the master harness switch to the global settings scope.
+ ///
+ /// # Errors
+ /// Returns an error when the global scope cannot be saved.
+ pub fn set_harness_refinements(&mut self, enabled: bool) -> Result<()> {
+ self.global_mut().harness_refinements = Some(enabled);
+ self.save_global_scope(&["harnessRefinements"])
+ }
+
/// The percentage ceiling for automatic compaction (default 95%).
#[must_use]
pub fn get_compaction_threshold_percent(&self) -> f64 {
diff --git a/crates/pa-core/src/settings/load.rs b/crates/pa-core/src/settings/load.rs
index 68d8c5dcf8..1e68cc4d0a 100644
--- a/crates/pa-core/src/settings/load.rs
+++ b/crates/pa-core/src/settings/load.rs
@@ -26,6 +26,7 @@ const KNOWN_FIELDS: &[&str] = &[
"theme",
"compaction",
"autoRefine",
+ "harnessRefinements",
"agentTraces",
"factory",
"telemetry",
diff --git a/crates/pa-core/src/settings/persistence_tests.rs b/crates/pa-core/src/settings/persistence_tests.rs
index 725f8e4dbf..b64edbdd93 100644
--- a/crates/pa-core/src/settings/persistence_tests.rs
+++ b/crates/pa-core/src/settings/persistence_tests.rs
@@ -131,6 +131,57 @@ fn resource_save_survives_an_unrelated_later_save() {
);
}
+#[test]
+fn harness_refinements_persist_without_clobbering_other_settings() {
+ let (storage, mut manager) =
+ fixture(r#"{"theme":"light","autoRefine":{"turnInterval":3},"future":{"keep":true}}"#);
+ assert!(manager.get_harness_refinements());
+ manager.set_harness_refinements(false).unwrap();
+ assert!(!manager.reopen().get_harness_refinements());
+ assert_eq!(
+ document(storage.as_ref()),
+ json!({
+ "theme":"light", "autoRefine":{"turnInterval":3}, "future":{"keep":true}, "harnessRefinements":false
+ })
+ );
+ manager.set_harness_refinements(true).unwrap();
+ assert!(manager.reopen().get_harness_refinements());
+}
+
+#[test]
+fn harness_refinements_ignore_project_overrides_and_resolve_global_wrong_types() {
+ let dir = tempfile::tempdir().unwrap();
+ let agent_dir = dir.path().join("agent");
+ let project_dir = dir.path().join(".prime/agent");
+ std::fs::create_dir_all(&agent_dir).unwrap();
+ std::fs::create_dir_all(&project_dir).unwrap();
+ std::fs::write(
+ agent_dir.join("settings.json"),
+ r#"{"harnessRefinements":false}"#,
+ )
+ .unwrap();
+ std::fs::write(
+ project_dir.join("settings.json"),
+ r#"{"harnessRefinements":true}"#,
+ )
+ .unwrap();
+ let mut manager = SettingsManager::create(dir.path(), &agent_dir);
+ assert!(!manager.get_harness_refinements());
+ manager.set_harness_refinements(true).unwrap();
+ std::fs::write(
+ project_dir.join("settings.json"),
+ r#"{"harnessRefinements":false}"#,
+ )
+ .unwrap();
+ assert!(manager.reopen().get_harness_refinements());
+ std::fs::write(
+ agent_dir.join("settings.json"),
+ r#"{"harnessRefinements":"false"}"#,
+ )
+ .unwrap();
+ assert!(manager.reopen().get_harness_refinements());
+}
+
#[test]
fn compaction_percentage_preserves_siblings_and_survives_reload() {
let (storage, mut manager) =
diff --git a/crates/pa-core/src/settings/types.rs b/crates/pa-core/src/settings/types.rs
index 95c4a22175..7a991d7a64 100644
--- a/crates/pa-core/src/settings/types.rs
+++ b/crates/pa-core/src/settings/types.rs
@@ -328,6 +328,8 @@ pub struct Settings {
pub theme: Option<String>,
pub compaction: Option<CompactionSettings>,
pub auto_refine: Option<AutoRefineSettings>,
+ /// Master switch for harness creation and context loading; unset preserves enabled behavior.
+ pub harness_refinements: Option<bool>,
pub agent_traces: Option<AgentTracesSettings>,
pub factory: Option<FactorySettings>,
pub telemetry: Option<TelemetrySettings>,
diff --git a/crates/pa-telemetry/src/catalog.rs b/crates/pa-telemetry/src/catalog.rs
index 2e27adf2a5..f91abb1069 100644
--- a/crates/pa-telemetry/src/catalog.rs
+++ b/crates/pa-telemetry/src/catalog.rs
@@ -1233,10 +1233,17 @@ const UPDATE_EVENTS: &[EventRule] = &[
},
];
+const HARNESS_REFINEMENTS_CHANGED: EventRule = EventRule {
+ name: "harness refinements changed",
+ since: 2,
+ properties: &[("enabled", required(boolean()))],
+};
+
/// Every catalogued event, flattened.
#[must_use]
pub fn catalog() -> Vec<&'static EventRule> {
let mut all: Vec<&'static EventRule> = vec![
+ &HARNESS_REFINEMENTS_CHANGED,
&AGENT_STARTED,
&AGENT_RUN_COMPLETED,
&AGENT_SESSION_ENDED,
diff --git a/crates/pa-tui/src/client_settings.rs b/crates/pa-tui/src/client_settings.rs
index 8de0be2dab..2ca34ea0f8 100644
--- a/crates/pa-tui/src/client_settings.rs
+++ b/crates/pa-tui/src/client_settings.rs
@@ -6,6 +6,18 @@
use anyhow::Result;
pub trait ClientSettings: Send + Sync {
+ /// Master harness refinement switch, enabled by default.
+ fn harness_refinements(&self) -> bool {
+ true
+ }
+ /// Persist the master harness refinement switch.
+ ///
+ /// # Errors
+ /// Returns an error if the settings store fails or is unavailable.
+ fn set_harness_refinements(&self, _enabled: bool) -> Result<()> {
+ anyhow::bail!("Harness refinement settings are unavailable")
+ }
+
/// Automatic compaction percentage ceiling; output headroom may trigger earlier.
fn compaction_threshold_percent(&self) -> f64;
/// Persist the percentage globally.
diff --git a/crates/pa-tui/src/session_ui/settings.rs b/crates/pa-tui/src/session_ui/settings.rs
index dd943e2268..6f03da734f 100644
--- a/crates/pa-tui/src/session_ui/settings.rs
+++ b/crates/pa-tui/src/session_ui/settings.rs
@@ -231,6 +231,7 @@ impl SessionUi {
values.block_images = settings.block_images();
values.skill_commands = settings.enable_skill_commands();
values.builtin_skills = settings.enable_builtin_skills();
+ values.harness_refinements = settings.harness_refinements();
values.hardware_cursor = settings.show_hardware_cursor();
values.editor_padding = settings.editor_padding_x();
values.autocomplete_max_visible = settings.autocomplete_max_visible();
@@ -249,6 +250,7 @@ impl SessionUi {
values.auto_resize_images = true;
values.skill_commands = true;
values.builtin_skills = true;
+ values.harness_refinements = true;
values.idle_eviction_minutes = "90".to_string();
values.mermaid = "streaming".to_string();
values.tree_filter_mode = "user-only".to_string();
@@ -377,6 +379,13 @@ impl SessionUi {
view.editor.set_autocomplete_skill_commands(skills);
self.dirty = true;
}
+ "harness-refinements" => {
+ self.persist_bool_setting(
+ |settings, enabled| settings.set_harness_refinements(enabled),
+ value,
+ view,
+ );
+ }
"builtin-skills" => {
self.persist_bool_setting(
|settings, enabled| settings.set_enable_builtin_skills(enabled),
diff --git a/crates/pa-tui/src/settings_menu/menu_tests.rs b/crates/pa-tui/src/settings_menu/menu_tests.rs
index 03334682d7..368b6f0d15 100644
--- a/crates/pa-tui/src/settings_menu/menu_tests.rs
+++ b/crates/pa-tui/src/settings_menu/menu_tests.rs
@@ -86,7 +86,8 @@ fn tabs_partition_the_settings_rows() {
"skill-commands",
"builtin-skills",
"idle-eviction-minutes",
- "tree-filter-mode"
+ "tree-filter-mode",
+ "harness-refinements",
]
),
]
@@ -648,6 +649,33 @@ fn space_activates_instead_of_typing_into_the_query() {
);
}
+#[test]
+fn harness_refinement_row_cycles_both_values_in_the_agents_tab() {
+ let values = SettingsCurrentValues {
+ harness_refinements: true,
+ ..SettingsCurrentValues::default()
+ };
+ let mut menu = SettingsMenu::new(settings_menu_rows(&values));
+ menu.handle_key("5", &kb());
+ for key in ["h", "a", "r", "n", "e", "s", "s"] {
+ menu.handle_key(key, &kb());
+ }
+ assert_eq!(
+ menu.handle_key("right", &kb()),
+ SettingsMenuAction::Change {
+ id: "harness-refinements",
+ value: "false".to_string()
+ }
+ );
+ assert_eq!(
+ menu.handle_key("left", &kb()),
+ SettingsMenuAction::Change {
+ id: "harness-refinements",
+ value: "true".to_string()
+ }
+ );
+}
+
#[test]
fn threshold_control_uses_five_point_steps_and_wraps_at_preset_boundaries() {
let values = SettingsCurrentValues {
diff --git a/crates/pa-tui/src/settings_menu/mod.rs b/crates/pa-tui/src/settings_menu/mod.rs
index ce1291d4c9..ee84ac102a 100644
--- a/crates/pa-tui/src/settings_menu/mod.rs
+++ b/crates/pa-tui/src/settings_menu/mod.rs
@@ -194,6 +194,14 @@ pub fn settings_menu_rows(current: &SettingsCurrentValues) -> Vec<SettingsMenuRo
values: Some(bool_value()),
submenu: None,
},
+ SettingsMenuRow {
+ id: "harness-refinements",
+ label: "Harness refinements",
+ description: "Create and load harness refinements; prior replies and summaries retain their influence",
+ current: current.harness_refinements.to_string(),
+ values: Some(bool_value()),
+ submenu: None,
+ },
SettingsMenuRow {
id: "builtin-skills",
label: "Built-in skills",
@@ -348,6 +356,7 @@ pub struct SettingsCurrentValues {
pub block_images: bool,
pub skill_commands: bool,
pub builtin_skills: bool,
+ pub harness_refinements: bool,
pub hardware_cursor: bool,
pub editor_padding: u64,
pub autocomplete_max_visible: u64,
diff --git a/crates/pa-tui/src/settings_menu/tabs.rs b/crates/pa-tui/src/settings_menu/tabs.rs
index 85e802f809..3a64f04b94 100644
--- a/crates/pa-tui/src/settings_menu/tabs.rs
+++ b/crates/pa-tui/src/settings_menu/tabs.rs
@@ -57,6 +57,7 @@ const TAB_LAYOUT: &[TabLayout] = &[
"builtin-skills",
"idle-eviction-minutes",
"tree-filter-mode",
+ "harness-refinements",
],
},
];
diff --git a/prime-agent-runtime/src/rlm/harness.py b/prime-agent-runtime/src/rlm/harness.py
index 9b43b8dd70..3b5ccb55e2 100644
--- a/prime-agent-runtime/src/rlm/harness.py
+++ b/prime-agent-runtime/src/rlm/harness.py
@@ -133,6 +133,17 @@ def _agent_dir() -> Path:
return Path(raw).expanduser().resolve()
+def _require_refinements_enabled() -> None:
+ """Read the host's global-only master switch, without caching it."""
+ try:
+ document = json.loads((_agent_dir() / "settings.json").read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return
+ value = document.get("harnessRefinements") if isinstance(document, dict) else None
+ if value is False:
+ raise RuntimeError("Harness refinements are disabled in /settings")
+
+
def _resolve_global_flag(global_: bool = False, extra: dict[str, Any] | None = None) -> bool:
extra = dict(extra or {})
if "global" in extra:
@@ -418,9 +429,13 @@ class HarnessState:
# writes (e.g. the host `/refine` command) and avoid clobbering them.
self._loaded_mtime: int | None = None
self._held_lock: tuple[Path, str] | None = None
- self.load()
+ # The proxy's empty fallback must remain constructible for kernel API
+ # introspection while disabled; every actual read/write still checks the gate.
+ if not in_memory:
+ self.load()
def _ensure_local_writable(self) -> None:
+ _require_refinements_enabled()
if self._local_write_error is not None:
raise RuntimeError(self._local_write_error)
@@ -441,6 +456,7 @@ class HarnessState:
stale snapshot. We re-read whenever the on-disk mtime no longer matches the
value recorded at our last load/save.
"""
+ _require_refinements_enabled()
if self._disk_mtime() != self._loaded_mtime:
self.load()
@@ -522,6 +538,7 @@ class HarnessState:
self._held_lock = None
def load(self) -> "HarnessState":
+ _require_refinements_enabled()
if self.file_path is None or not self.file_path.exists():
self._loaded_mtime = None
return self
@@ -608,6 +625,7 @@ class HarnessState:
return target
def save(self) -> "HarnessState":
+ _require_refinements_enabled()
if self.file_path is None:
# in_memory fallback: nothing to persist.
return self
@@ -1329,6 +1347,7 @@ def get_harness_state(
state_dir: str | Path | None = None, *, global_: bool = False, **kwargs: Any
) -> HarnessState:
"""Return the cached local harness state, or global when requested."""
+ _require_refinements_enabled()
global_ = _resolve_global_flag(global_, kwargs)
file_path = _state_file(state_dir, global_=global_)
scope: HarnessScope = "global" if global_ else "local"
diff --git a/prime-agent-runtime/test/test_harness.py b/prime-agent-runtime/test/test_harness.py
index 2f010b5f29..8f3642348f 100644
--- a/prime-agent-runtime/test/test_harness.py
+++ b/prime-agent-runtime/test/test_harness.py
@@ -1502,8 +1502,6 @@ class HarnessStateTest(unittest.TestCase):
state.list("tool")
-if __name__ == "__main__":
- unittest.main()
class HarnessSearchTest(unittest.TestCase):
@@ -1631,3 +1629,79 @@ class HarnessSearchTest(unittest.TestCase):
state.entries["memory"]["rare"].updated_at = "2026-07-01T00:00:00+00:00"
self.assertEqual([entry.id for entry in state.search("session quantum")], ["rare", "zz_newer", "aa_older", "solo"])
+
+
+class HarnessRefinementsSettingTests(unittest.TestCase):
+ def test_disabled_harness_keeps_kernel_api_introspection_available(self):
+ with tempfile.TemporaryDirectory() as tmp, patch.dict(os.environ, {"PRIME_AGENT_CODING_AGENT_DIR": tmp}):
+ (Path(tmp) / "settings.json").write_text('{"harnessRefinements":false}')
+ # The real kernel bootstrap probes these methods before any cell runs.
+ for method in ("create_memory", "update_memory", "delete_memory", "create_skill", "record_refinement"):
+ self.assertTrue(callable(getattr(package_harness, method)))
+ self.assertTrue(callable(getattr(callable_rlm.harness, method)))
+ with self.assertRaisesRegex(RuntimeError, "disabled in /settings"):
+ package_harness.create_memory("No", "Do not create")
+ with self.assertRaisesRegex(RuntimeError, "disabled in /settings"):
+ package_harness.snapshot()
+
+ def test_project_settings_cannot_override_the_global_master_switch(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ agent_dir = Path(tmp) / "agent"
+ project_dir = Path(tmp) / "project" / ".prime" / "agent"
+ agent_dir.mkdir()
+ project_dir.mkdir(parents=True)
+ (agent_dir / "settings.json").write_text('{"harnessRefinements":false}')
+ project_settings = project_dir / "settings.json"
+ project_settings.write_text('{"harnessRefinements":true}')
+ with patch.dict(os.environ, {"PRIME_AGENT_CODING_AGENT_DIR": str(agent_dir), "PRIME_AGENT_SETTINGS_CWD": str(Path(tmp) / "project")}):
+ with self.assertRaisesRegex(RuntimeError, "disabled in /settings"):
+ HarnessState(Path(tmp) / "harness_state.json", scope="global")
+ (agent_dir / "settings.json").write_text('{"harnessRefinements":true}')
+ project_settings.write_text('{"harnessRefinements":false}')
+ state = HarnessState(Path(tmp) / "harness_state.json", scope="global")
+ state.create_memory("Note", "Global preference wins", id="note")
+ self.assertEqual(state.get("memory", "note").content, "Global preference wins")
+ (agent_dir / "settings.json").write_text('{"harnessRefinements":false}')
+ project_settings.write_text('{"harnessRefinements":true}')
+ with self.assertRaisesRegex(RuntimeError, "disabled in /settings"):
+ state.get("memory", "note")
+ (agent_dir / "settings.json").write_text('{"harnessRefinements":"false"}')
+ self.assertEqual(state.get("memory", "note").content, "Global preference wins")
+
+ def test_disable_blocks_cached_reads_and_writes_without_deleting_state(self):
+ with tempfile.TemporaryDirectory() as tmp, patch.dict(os.environ, {"PRIME_AGENT_CODING_AGENT_DIR": tmp}):
+ settings = Path(tmp) / "settings.json"
+ settings.write_text('{"harnessRefinements":true}')
+ state = get_harness_state(tmp, global_=True)
+ state.create_memory("Note", "Saved memory", id="note")
+ before = state.file_path.read_bytes()
+ settings.write_text('{"harnessRefinements":false}')
+ for action in (lambda: get_harness_state(tmp, global_=True), lambda: state.get("memory", "note"), lambda: state.create_memory("New", "New memory"), state.load, state.save):
+ with self.assertRaisesRegex(RuntimeError, "disabled in /settings"):
+ action()
+ self.assertEqual(state.file_path.read_bytes(), before)
+ settings.write_text('{"harnessRefinements":true}')
+ self.assertEqual(state.get("memory", "note").content, "Saved memory")
+
+ def test_disabled_refinements_refuse_factory_runs_before_launch(self):
+ import asyncio
+ from rlm import factory
+
+ with tempfile.TemporaryDirectory() as tmp, patch.dict(os.environ, {"PRIME_AGENT_CODING_AGENT_DIR": tmp}):
+ settings = Path(tmp) / "settings.json"
+ settings.write_text('{"factory":{"enabled":true},"harnessRefinements":true}')
+ state = HarnessState(Path(tmp) / "harness_state.json")
+ state.create_factory("Saved factory", "Saved spec", id="saved", dag=FACTORY_DAG)
+ before = state.file_path.read_bytes()
+ executor = factory.FactoryExecutor(harness=state)
+ settings.write_text('{"factory":{"enabled":true},"harnessRefinements":false}')
+ with patch.object(factory, "_DEFAULT_EXECUTOR", executor):
+ for name in ("saved", "review-sweep"):
+ with self.assertRaisesRegex(RuntimeError, "disabled in /settings"):
+ asyncio.run(factory.run_factory(name))
+ self.assertEqual(executor._runs, {})
+ self.assertEqual(state.file_path.read_bytes(), before)
+
+
+if __name__ == "__main__":
+ unittest.main()