v1.0 tag-cut: fs2 advisory lock against concurrent analyze (STO-01, Day 2)

Cargo.toml

@@ -60,3 +60,10 @@ xgraph = "2.0.0"
 assert_cmd = "2"
 tempfile = "3"
 nix = { version = "0.28", default-features = false, features = ["resource"] }
+# fs2 provides a portable advisory-lock wrapper around POSIX flock(2)
+# (Linux/macOS) and Windows LockFileEx. Used by the cross-process
+# project-lock (STO-01, gap-register entry; ADR-035 declaration discipline
+# for the new lockfile constant). The 0.4 series has been API-stable for
+# years; the crate is lightly maintained upstream but the surface we use
+# (`FileExt::try_lock_exclusive` / `unlock`) is settled.
+fs2 = "0.4"

crates/clarion-cli/Cargo.toml

@@ -23,6 +23,7 @@ clarion-mcp = { path = "../clarion-mcp", version = "1.0.0" }
 clarion-scanner = { path = "../clarion-scanner", version = "1.0.0" }
 clarion-storage = { path = "../clarion-storage", version = "1.0.0" }
 dotenvy.workspace = true
+fs2.workspace = true
 ignore.workspace = true
 rusqlite.workspace = true
 serde.workspace = true
@@ -41,6 +42,7 @@ xgraph.workspace = true
 [dev-dependencies]
 assert_cmd.workspace = true
 clarion-plugin-fixture = { path = "../clarion-plugin-fixture", version = "1.0.0" }
+fs2.workspace = true
 rusqlite.workspace = true
 serde_json.workspace = true
 sha1.workspace = true

crates/clarion-cli/src/analyze.rs

@@ -84,6 +84,19 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
     let analyze_config = AnalyzeConfig::load(&project_root, options.config_path.as_deref())?;
     let analyze_config_json = analyze_config.to_json_string()?;
 
+    // ── Cross-process writer lock (gap-register STO-01) ───────────────────────
+    // Acquire the project-wide advisory lock BEFORE spawning the writer-actor
+    // so two concurrent `clarion analyze` invocations against the same
+    // project root cannot interleave their write transactions. The guard
+    // must outlive `handle.await` at every exit path; binding to a local
+    // here lets it drop with this function's stack frame regardless of
+    // which `return Ok(())` / `bail!` path the run takes.
+    //
+    // The lock is taken AFTER the `.clarion/` directory existence check
+    // above so the "no install" error message remains the user-facing
+    // diagnostic for that case, rather than a lockfile-creation failure.
+    let _project_lock = crate::project_lock::acquire_project_lock(&project_root)?;
+
     // ── Writer actor ──────────────────────────────────────────────────────────
     let (writer, handle) = Writer::spawn(
         db_path.clone(),

crates/clarion-cli/src/http_read.rs

@@ -196,9 +196,8 @@ where
     // local request because both auth knobs are unset and the bind is
     // loopback. On a shared developer host or CI runner this means any
     // local process can read the (non-blocked) catalogue.
-    let warn_unauthenticated_loopback = config.is_loopback_bind()
-        && auth_token.is_none()
-        && identity_secret.is_none();
+    let warn_unauthenticated_loopback =
+        config.is_loopback_bind() && auth_token.is_none() && identity_secret.is_none();
     let (shutdown_tx, shutdown_rx) = oneshot::channel();
     let (ready_tx, ready_rx) = std::sync::mpsc::channel::<Result<HttpReadReady>>();
     let (failure_tx, failure_rx) = mpsc::channel();
@@ -1571,7 +1570,10 @@ mod tests {
 
         impl io::Write for CaptureWriter {
             fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
-                self.buffer.lock().expect("capture lock").extend_from_slice(buf);
+                self.buffer
+                    .lock()
+                    .expect("capture lock")
+                    .extend_from_slice(buf);
                 Ok(buf.len())
             }
             fn flush(&mut self) -> io::Result<()> {
@@ -1616,10 +1618,9 @@ mod tests {
                 token_env: "CLARION_LOOPBACK_NO_TOKEN_TEST_UNSET".to_owned(),
                 identity_token_env: None,
             };
-            let instance_id = crate::instance::parse_instance_id_for_test(
-                "00000000-0000-4000-8000-000000000002",
-            )
-            .expect("parse synthetic instance id");
+            let instance_id =
+                crate::instance::parse_instance_id_for_test("00000000-0000-4000-8000-000000000002")
+                    .expect("parse synthetic instance id");
 
             // Env lookup that returns None for every variable — emulates
             // the operator running `clarion serve` on loopback with no

crates/clarion-cli/src/main.rs

@@ -5,6 +5,7 @@ mod config;
 mod http_read;
 mod install;
 mod instance;
+mod project_lock;
 mod run_lifecycle;
 mod secret_scan;
 mod serve;