chore(migrations): phase out PROFILE.md from disk on schema_version=1 (tinyhumansai#1734)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sanil-23

src/openhuman/config/schema/load.rs

@@ -738,11 +738,19 @@ impl Config {
                 recovered = config_was_corrupted,
                 "Config loaded"
             );
+            crate::openhuman::migrations::run_pending(&mut config).await;
             Ok(config)
         } else {
+            // Fresh install: there is no legacy on-disk state, so stamp
+            // the workspace at the current schema version up front. This
+            // makes `run_pending` a fast no-op on the first launch
+            // (nothing to migrate) and keeps the "first launch on this
+            // workspace" semantics aligned with "current binary built
+            // this workspace".
             let mut config = Config {
                 config_path: config_path.clone(),
                 workspace_dir,
+                schema_version: crate::openhuman::migrations::CURRENT_SCHEMA_VERSION,
                 ..Default::default()
             };
             config.save().await?;
@@ -762,6 +770,13 @@ impl Config {
                 initialized = true,
                 "Config loaded"
             );
+            // Defensive: still call run_pending. It will see
+            // `schema_version == CURRENT` and return immediately, but
+            // the call site stays symmetric with the existing-config
+            // branch so a future migration that needs to fire on fresh
+            // installs (vanishingly unlikely, but possible) doesn't
+            // require touching this path.
+            crate::openhuman::migrations::run_pending(&mut config).await;
             Ok(config)
         }
     }

src/openhuman/config/schema/types.rs

@@ -28,6 +28,13 @@ pub struct Config {
     pub workspace_dir: PathBuf,
     #[serde(skip)]
     pub config_path: PathBuf,
+    /// Workspace data-schema version. Bumped each time a one-shot data
+    /// migration under [`crate::openhuman::migrations`] runs successfully.
+    /// `#[serde(default)]` so existing `config.toml` files (which predate
+    /// the field) load as version `0` and pick up pending migrations on
+    /// the first launch of the new build.
+    #[serde(default)]
+    pub schema_version: u32,
     pub api_url: Option<String>,
     pub api_key: Option<String>,
     /// Custom LLM inference endpoint (OpenAI-compatible). When set together
@@ -272,6 +279,7 @@ impl Default for Config {
         Self {
             workspace_dir: openhuman_dir.join("workspace"),
             config_path: openhuman_dir.join("config.toml"),
+            schema_version: 0,
             api_url: None,
             api_key: None,
             inference_url: None,

src/openhuman/migrations/mod.rs

@@ -0,0 +1,110 @@
+//! Startup data migrations gated by [`Config::schema_version`].
+//!
+//! Each migration is a one-shot, idempotent transformation of on-disk
+//! data. The runner is invoked from [`Config::load_or_init`] and is a
+//! fast no-op for workspaces whose `schema_version` already matches
+//! [`CURRENT_SCHEMA_VERSION`]. Failures are logged but never block
+//! startup — the next launch retries.
+//!
+//! ## Adding a new migration
+//!
+//! 1. Add a module here (e.g. `mod my_migration;`).
+//! 2. Bump [`CURRENT_SCHEMA_VERSION`].
+//! 3. Extend [`run_pending`] with a `if config.schema_version < N`
+//!    branch that calls the new module and bumps `config.schema_version`
+//!    on success.
+//!
+//! ## Distinction from `crate::openhuman::migration`
+//!
+//! The sibling `migration` (singular) module is a user-triggered RPC
+//! that imports memory from a legacy OpenClaw workspace. This module
+//! (`migrations`, plural) is the automatic schema-version runner that
+//! fires once per workspace on first launch of a new build.
+
+use crate::openhuman::config::Config;
+
+mod phase_out_profile_md;
+
+/// Current target schema version. Bumped alongside every new migration.
+pub const CURRENT_SCHEMA_VERSION: u32 = 1;
+
+/// Run any migrations whose `schema_version` gate hasn't yet been
+/// crossed for this workspace.
+///
+/// Best-effort: failures inside a migration are logged and never
+/// propagate. The `schema_version` is only bumped after a migration
+/// reports success **and** the bump is persisted via [`Config::save`],
+/// so a partial run leaves the gate unchanged and the next launch
+/// retries from the same starting version.
+pub async fn run_pending(config: &mut Config) {
+    if config.schema_version >= CURRENT_SCHEMA_VERSION {
+        log::debug!(
+            "[migrations] schema_version={} already at current={} — nothing to do",
+            config.schema_version,
+            CURRENT_SCHEMA_VERSION
+        );
+        return;
+    }
+
+    log::info!(
+        "[migrations] running pending migrations schema_version={} -> {}",
+        config.schema_version,
+        CURRENT_SCHEMA_VERSION
+    );
+
+    // 0 -> 1: phase out PROFILE.md from persisted session transcripts.
+    //
+    // The migration body is synchronous fs I/O (read_dir + read_to_string +
+    // write across potentially hundreds of files). `run_pending` is called
+    // from `Config::load_or_init`, which runs on a tokio runtime — so we
+    // move the blocking walk onto a dedicated `spawn_blocking` task to
+    // keep the executor responsive.
+    if config.schema_version < 1 {
+        let workspace_dir = config.workspace_dir.clone();
+        let run_result =
+            tokio::task::spawn_blocking(move || phase_out_profile_md::run(&workspace_dir)).await;
+        match run_result {
+            Ok(Ok(stats)) => {
+                let previous_version = config.schema_version;
+                config.schema_version = 1;
+                if let Err(err) = config.save().await {
+                    // Roll the in-memory version back so a subsequent
+                    // `load_or_init` (or future migration) doesn't believe
+                    // we've already crossed this gate when disk still
+                    // says 0. Next launch retries from the same start.
+                    config.schema_version = previous_version;
+                    log::warn!(
+                        "[migrations] phase_out_profile_md ran but config.save failed: \
+                         {err:#} — rolled in-memory schema_version back to {previous_version}, \
+                         will retry on next launch"
+                    );
+                    return;
+                }
+                log::info!(
+                    "[migrations] schema_version bumped to 1 (phase_out_profile_md \
+                     scanned={} cleaned={} skipped={} errors={})",
+                    stats.scanned,
+                    stats.cleaned,
+                    stats.skipped,
+                    stats.errors
+                );
+            }
+            Ok(Err(err)) => {
+                log::warn!(
+                    "[migrations] phase_out_profile_md failed: {err:#} — \
+                     will retry on next launch"
+                );
+            }
+            Err(join_err) => {
+                log::warn!(
+                    "[migrations] phase_out_profile_md blocking task did not complete: \
+                     {join_err} — will retry on next launch"
+                );
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "mod_tests.rs"]
+mod tests;

src/openhuman/migrations/mod_tests.rs

@@ -0,0 +1,149 @@
+use super::*;
+use crate::openhuman::agent::harness::session::transcript::{
+    read_transcript, write_transcript, TranscriptMeta,
+};
+use crate::openhuman::providers::ChatMessage;
+use std::fs;
+use std::path::Path;
+use tempfile::TempDir;
+
+fn tainted_prompt() -> String {
+    "## Identity\n\nYou are an assistant.\n\n\
+     ### PROFILE.md\n\n\
+     style/calm tooling/rust\n\n\
+     ### Tools\n\n- shell\n"
+        .to_string()
+}
+
+fn meta() -> TranscriptMeta {
+    TranscriptMeta {
+        agent_name: "main".into(),
+        dispatcher: "native".into(),
+        created: "2026-05-01T00:00:00Z".into(),
+        updated: "2026-05-01T00:00:00Z".into(),
+        turn_count: 1,
+        input_tokens: 0,
+        output_tokens: 0,
+        cached_input_tokens: 0,
+        charged_amount_usd: 0.0,
+        thread_id: None,
+    }
+}
+
+fn config_in(tmp: &TempDir) -> Config {
+    Config {
+        config_path: tmp.path().join("config.toml"),
+        workspace_dir: tmp.path().join("workspace"),
+        ..Default::default()
+    }
+}
+
+fn seed_tainted_transcript(workspace_dir: &Path) -> std::path::PathBuf {
+    let raw_dir = workspace_dir.join("session_raw");
+    fs::create_dir_all(&raw_dir).unwrap();
+    let path = raw_dir.join("1700000000_main.jsonl");
+    let messages = vec![
+        ChatMessage::system(tainted_prompt()),
+        ChatMessage::user("hello"),
+    ];
+    write_transcript(&path, &messages, &meta(), None).unwrap();
+    path
+}
+
+#[tokio::test]
+async fn run_pending_skips_when_version_current() {
+    let tmp = TempDir::new().unwrap();
+    let path = seed_tainted_transcript(&tmp.path().join("workspace"));
+    let before = fs::read(&path).unwrap();
+
+    let mut config = config_in(&tmp);
+    config.schema_version = CURRENT_SCHEMA_VERSION;
+    run_pending(&mut config).await;
+
+    assert_eq!(config.schema_version, CURRENT_SCHEMA_VERSION);
+    let after = fs::read(&path).unwrap();
+    assert_eq!(before, after, "transcript must be untouched");
+}
+
+#[tokio::test]
+async fn run_pending_runs_phase_out_when_version_zero() {
+    let tmp = TempDir::new().unwrap();
+    let path = seed_tainted_transcript(&tmp.path().join("workspace"));
+
+    let mut config = config_in(&tmp);
+    assert_eq!(config.schema_version, 0);
+    run_pending(&mut config).await;
+
+    assert_eq!(config.schema_version, 1);
+    let session = read_transcript(&path).unwrap();
+    assert!(
+        !session.messages[0].content.contains("### PROFILE.md"),
+        "PROFILE.md block must be stripped, got:\n{}",
+        session.messages[0].content
+    );
+
+    let on_disk = std::fs::read_to_string(&config.config_path).unwrap();
+    assert!(
+        on_disk.contains("schema_version = 1"),
+        "saved config.toml must record schema_version=1, got:\n{on_disk}"
+    );
+}
+
+#[tokio::test]
+async fn run_pending_bumps_version_on_fresh_install() {
+    let tmp = TempDir::new().unwrap();
+    // No session_raw/ at all — pure fresh install.
+    fs::create_dir_all(tmp.path().join("workspace")).unwrap();
+
+    let mut config = config_in(&tmp);
+    run_pending(&mut config).await;
+
+    assert_eq!(config.schema_version, 1);
+    let on_disk = std::fs::read_to_string(&config.config_path).unwrap();
+    assert!(on_disk.contains("schema_version = 1"));
+}
+
+#[tokio::test]
+async fn run_pending_rolls_back_schema_version_when_save_fails() {
+    let tmp = TempDir::new().unwrap();
+    seed_tainted_transcript(&tmp.path().join("workspace"));
+
+    let mut config = config_in(&tmp);
+    // Point config.save() at a path whose parent directory cannot be
+    // created (a regular file occupies that name), forcing save() to
+    // error after the migration body has succeeded.
+    let blocker = tmp.path().join("blocker");
+    fs::write(&blocker, "not a directory").unwrap();
+    config.config_path = blocker.join("nested").join("config.toml");
+
+    assert_eq!(config.schema_version, 0);
+    run_pending(&mut config).await;
+
+    assert_eq!(
+        config.schema_version, 0,
+        "save failed → in-memory schema_version must be rolled back to 0"
+    );
+}
+
+#[tokio::test]
+async fn run_pending_is_a_no_op_on_second_invocation() {
+    let tmp = TempDir::new().unwrap();
+    seed_tainted_transcript(&tmp.path().join("workspace"));
+
+    let mut config = config_in(&tmp);
+    run_pending(&mut config).await;
+    assert_eq!(config.schema_version, 1);
+
+    // Mutate the config file timestamp marker by reading + comparing
+    // before vs after the second invocation.
+    let before = fs::metadata(&config.config_path).unwrap().modified().ok();
+    std::thread::sleep(std::time::Duration::from_millis(20));
+    run_pending(&mut config).await;
+    let after = fs::metadata(&config.config_path).unwrap().modified().ok();
+
+    assert_eq!(config.schema_version, 1);
+    assert_eq!(
+        before, after,
+        "config.toml must not be re-saved on second run"
+    );
+}