oh-my-codex 0.20.1 → 0.20.3

package/Cargo.lock

@@ -32,7 +32,7 @@ checksum = "6b947ae49db0d222b1dbc6b113ce7248a3fc3a6ca21b696717bfc000ba4484d8"
 
 [[package]]
 name = "omx-api"
-version = "0.20.1"
+version = "0.20.3"
 dependencies = [
  "serde",
  "serde_json",
@@ -40,14 +40,14 @@ dependencies = [
 
 [[package]]
 name = "omx-explore-harness"
-version = "0.20.1"
+version = "0.20.3"
 dependencies = [
  "libc",
 ]
 
 [[package]]
 name = "omx-mux"
-version = "0.20.1"
+version = "0.20.3"
 dependencies = [
  "serde",
  "serde_json",
@@ -55,8 +55,9 @@ dependencies = [
 
 [[package]]
 name = "omx-runtime"
-version = "0.20.1"
+version = "0.20.3"
 dependencies = [
+ "fs2",
  "omx-mux",
  "omx-runtime-core",
  "serde_json",
@@ -64,7 +65,7 @@ dependencies = [
 
 [[package]]
 name = "omx-runtime-core"
-version = "0.20.1"
+version = "0.20.3"
 dependencies = [
  "fs2",
  "serde",
@@ -73,7 +74,7 @@ dependencies = [
 
 [[package]]
 name = "omx-sparkshell"
-version = "0.20.1"
+version = "0.20.3"
 dependencies = [
  "omx-mux",
 ]

package/Cargo.toml

@@ -11,7 +11,7 @@ resolver = "2"
 
 [workspace.package]
 
-version = "0.20.1"
+version = "0.20.3"
 
 edition = "2021"
 rust-version = "1.73"

package/README.md

@@ -92,6 +92,15 @@ Choose the setup scope deliberately:
 - Use `omx setup --scope user` for user-level Codex setup when you are not preparing the current directory as an OMX project.
 - Avoid running project-scoped setup from a broad home directory or operating hub unless that directory is intentionally the project under review. A home-level `AGENTS.md` often contains global safety and routing rules; keep project-specific OMX runtime guidance in the real repository instead.
 
+### Persisting an explicit AGENTS merge policy
+
+`omx setup --merge-agents`, `omx setup --no-merge-agents`, and `omx setup --clear-merge-agents-policy` are the only policy selectors; use their bare forms (not `=value` spellings). Repeating an identical selector is harmless, but mixing set and clear choices fails before setup changes anything. An explicit set overrides a saved policy. A successful explicit set records `mergeAgents: true` or `false` in the current working root's `./.omx/setup-scope.json`, even when setup scope is `user`; it never becomes a global user preference or leaks to another root. Later `omx update` replays a valid matching policy for both immediate and deferred refreshes.
+
+`true` takes the existing merge branch. `false` only suppresses that branch: it does not promise preservation, replacement, or any new safety mode, so the existing prompt, skip, managed-refresh, plugin-default, and force behavior still applies. A matching-scope review retains the policy while unrelated settings change. Reset or a scope change removes the inherited policy unless the same setup run explicitly sets `true` or `false`; clear always removes the policy and cannot be combined with a set selector. Malformed, unknown, nonboolean, or wrong-scope saved data is ignored safely.
+
+`--force` is independent and transient: it is neither recorded nor replayed, and does not override an explicit merge policy. Setup atomically commits explicit set or clear intent only after all setup work succeeds, including when active-session or plugin-symlink safeguards skip the current `AGENTS.md` write, so the next refresh can honor the requested policy. This does not make merge the default or revive the rejected #2892 merge-by-default approach. Older OMX versions safely ignore the field, but may erase it when rewriting their known setup preferences.
+
+
 **Codex plugin install note:** this repo also ships an official Codex plugin layout at `plugins/oh-my-codex` with marketplace metadata in `.agents/plugins/marketplace.json`. That plugin bundles the mirrored skill surface plus plugin-scoped companion metadata for official Codex lifecycle hooks, optional MCP compatibility servers, and apps. It is still **not** a replacement for the global `oh-my-codex` CLI plus scoped setup: plugin-scoped hooks launch the installed `omx` CLI, legacy setup mode installs native agents and prompts, and plugin setup mode relies on plugin discovery for bundled skills while archiving/removing legacy OMX-managed prompts/native-agent TOMLs so stale role files cannot shadow plugin behavior. Plugin mode still needs a persistent scope `AGENTS.md` (`~/.codex/AGENTS.md` for user setup or `./AGENTS.md` for project setup) as the durable orchestration guidance layer; session-scoped AGENTS files only compose that durable guidance with runtime overlays and are not a replacement.
 
 Then work normally inside Codex:
@@ -156,6 +165,32 @@ created and recovered. `--worktree` also moves the launch into a separate git
 checkout, which is the safer default when using `--madmax`. Replace
 `feat/task` with a branch-like name for the task.
 
+### Concurrent standard conversations
+
+A standard launch owns one writable session pointer under its selected `OMX_ROOT`. A second ordinary `omx` launch from the same checkout therefore fails closed instead of sharing or silently changing that root. Give each additional conversation an explicit, distinct root:
+
+```bash
+omx
+OMX_ROOT="$HOME/.omx/instances/second-conversation" omx
+OMX_ROOT="$HOME/.omx/instances/third-conversation" omx
+```
+
+PowerShell:
+
+```powershell
+$env:OMX_ROOT = "$HOME/.omx/instances/second-conversation"
+omx
+```
+
+Command Prompt:
+
+```bat
+set "OMX_ROOT=%USERPROFILE%\.omx\instances\second-conversation"
+omx
+```
+
+User-specified roots are literal: launching twice with the same explicit `OMX_ROOT` remains a fatal owner conflict. Separate checkouts have separate default roots, while `--worktree` and `--madmax` keep their existing isolation behavior.
+
 ### Madmax and worktree launch safety
 
 `--madmax` is OMX shorthand for Codex
@@ -333,7 +368,7 @@ These are operator/support surfaces:
 - Scoped setup installs prompts, skills, AGENTS scaffolding, `.codex/config.toml`, and (for legacy installs or older Codex without `plugin_hooks`) OMX-managed native Codex hooks in `.codex/hooks.json`
   - setup refresh preserves non-OMX hook entries in `.codex/hooks.json` and only rewrites OMX-managed wrappers
   - plugin setup keeps `AGENTS.md` as persistent durable guidance even though bundled skills/hooks come from the plugin cache; `omx doctor` treats a missing persistent scope `AGENTS.md` in plugin mode as a failed check because the session-scoped AGENTS file would otherwise contain only runtime overlay guidance
-  - `omx setup --scope project --merge-agents` preserves existing project `AGENTS.md` guidance while inserting or refreshing generated OMX sections between `<!-- OMX:AGENTS:START -->` / `<!-- OMX:AGENTS:END -->`; without `--merge-agents` or `--force`, non-interactive setup keeps skipping existing `AGENTS.md` files
+  - `omx setup --merge-agents` preserves existing project `AGENTS.md` guidance while inserting or refreshing generated OMX sections between `<!-- OMX:AGENTS:START -->` / `<!-- OMX:AGENTS:END -->`; `--no-merge-agents` records an explicit contextual non-merge choice, and `--clear-merge-agents-policy` always removes the recorded choice and cannot combine with a set selector. The policy is stored per working root (even for user scope), replayed by immediate and deferred updates only when its saved scope is valid and matches, and is never a force/default policy.
   - `omx uninstall` removes OMX-managed wrappers from `.codex/hooks.json` but keeps the file when user hooks remain
 - `omx update` checks npm immediately, installs the newest global OMX build, then reruns the same interactive setup refresh path
 - launch-time update checks are throttled and prompt by default; use `OMX_AUTO_UPDATE=0` to disable them or `OMX_AUTO_UPDATE=defer` to schedule deferred updates without a prompt

package/crates/omx-runtime/Cargo.toml

@@ -9,5 +9,6 @@ repository.workspace = true
 [dependencies]
 omx-mux = { path = "../omx-mux" }
 omx-runtime-core = { path = "../omx-runtime-core" }
+fs2 = "0.4"
 serde_json = "1"
 

package/crates/omx-runtime/src/main.rs

@@ -1,3 +1,4 @@
+use fs2::FileExt;
 use omx_mux::{canonical_contract_summary, MuxAdapter, MuxOperation, MuxTarget, TmuxAdapter};
 use omx_runtime_core::{runtime_contract_summary, RuntimeCommand, RuntimeEngine};
 use std::env;
@@ -71,9 +72,31 @@ fn run() -> Result<(), String> {
             let json_input = second.ok_or("exec requires a JSON command argument")?;
             let state_dir = args.iter().find_map(|a| a.strip_prefix("--state-dir="));
             let compact = args.iter().any(|a| a == "--compact");
+            let _mutation_lock = if let Some(dir) = state_dir {
+                std::fs::create_dir_all(dir).map_err(|e| e.to_string())?;
+                let lock =
+                    std::fs::File::create(std::path::Path::new(dir).join("runtime-mutation.lock"))
+                        .map_err(|e| e.to_string())?;
+                lock.lock_exclusive().map_err(|e| e.to_string())?;
+                Some(lock)
+            } else {
+                None
+            };
             let mut engine = match state_dir {
-                Some(dir) => RuntimeEngine::load(dir)
-                    .unwrap_or_else(|_| RuntimeEngine::new().with_state_dir(dir)),
+                Some(dir) => match RuntimeEngine::load(dir) {
+                    Ok(engine) => engine,
+                    Err(error) => {
+                        let has_persisted_state = ["events.json", "snapshot.json", "mailbox.json"]
+                            .iter()
+                            .any(|name| std::path::Path::new(dir).join(name).exists());
+                        if has_persisted_state {
+                            return Err(format!(
+                                "failed to load authoritative runtime state: {error}"
+                            ));
+                        }
+                        RuntimeEngine::new().with_state_dir(dir)
+                    }
+                },
                 None => RuntimeEngine::new(),
             };
 

package/crates/omx-runtime/tests/execution.rs

@@ -178,6 +178,56 @@ fn exec_with_state_dir_persists() {
     let _ = std::fs::remove_dir_all(&dir);
 }
 
+#[test]
+fn exec_rejects_missing_seen_ledger_after_persisted_dispatch_history() {
+    let dir = std::env::temp_dir().join("omx-runtime-test-exec-missing-seen-ledger");
+    let _ = std::fs::remove_dir_all(&dir);
+    let state_arg = format!("--state-dir={}", dir.display());
+    let queued = Command::new(env!("CARGO_BIN_EXE_omx-runtime"))
+        .args([
+            "exec",
+            r#"{"command":"QueueDispatch","request_id":"request-1","target":"worker"}"#,
+            &state_arg,
+        ])
+        .output()
+        .expect("queued dispatch");
+    assert!(queued.status.success());
+    std::fs::remove_file(dir.join("dispatch-seen.json")).expect("removed seen ledger");
+
+    let reloaded = Command::new(env!("CARGO_BIN_EXE_omx-runtime"))
+        .args(["exec", r#"{"command":"CaptureSnapshot"}"#, &state_arg])
+        .output()
+        .expect("reloaded persisted state");
+    assert!(!reloaded.status.success());
+    assert!(String::from_utf8_lossy(&reloaded.stderr).contains("missing dispatch seen ledger"));
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn exec_ignores_dispatch_compat_without_authoritative_runtime_state() {
+    let dir = std::env::temp_dir().join("omx-runtime-test-dispatch-compat-only");
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    std::fs::write(dir.join("dispatch.json"), "[]\n").unwrap();
+
+    let cmd_json = r#"{"command":"CaptureSnapshot"}"#;
+    let state_arg = format!("--state-dir={}", dir.display());
+    let output = Command::new(env!("CARGO_BIN_EXE_omx-runtime"))
+        .args(["exec", cmd_json, &state_arg])
+        .output()
+        .expect("ran omx-runtime");
+
+    assert!(
+        output.status.success(),
+        "dispatch compatibility output must not poison fresh authoritative state: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert!(dir.join("events.json").exists());
+    assert!(dir.join("snapshot.json").exists());
+
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
 #[test]
 fn snapshot_from_state_dir_reads_persisted_state() {
     let dir = std::env::temp_dir().join("omx-runtime-test-snapshot-statedir");
@@ -210,3 +260,172 @@ fn snapshot_from_state_dir_reads_persisted_state() {
 
     let _ = std::fs::remove_dir_all(&dir);
 }
+
+#[test]
+fn exec_compact_immediately_persists_only_nonterminal_dispatch_records() {
+    let dir = std::env::temp_dir().join("omx-runtime-test-exec-compact-dispatch");
+    let _ = std::fs::remove_dir_all(&dir);
+    let state_arg = format!("--state-dir={}", dir.display());
+    let run_exec = |json: &str, compact: bool| {
+        let mut command = Command::new(env!("CARGO_BIN_EXE_omx-runtime"));
+        command.args(["exec", json, &state_arg]);
+        if compact {
+            command.arg("--compact");
+        }
+        let output = command.output().expect("ran omx-runtime");
+        assert!(
+            output.status.success(),
+            "exec failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    };
+
+    run_exec(
+        r#"{"command":"QueueDispatch","request_id":"pending","target":"worker-pending"}"#,
+        false,
+    );
+    run_exec(
+        r#"{"command":"QueueDispatch","request_id":"notified","target":"worker-notified"}"#,
+        false,
+    );
+    run_exec(
+        r#"{"command":"MarkNotified","request_id":"notified","channel":"tmux"}"#,
+        false,
+    );
+    run_exec(
+        r#"{"command":"QueueDispatch","request_id":"delivered","target":"worker-delivered"}"#,
+        false,
+    );
+    run_exec(
+        r#"{"command":"MarkNotified","request_id":"delivered","channel":"tmux"}"#,
+        false,
+    );
+    run_exec(
+        r#"{"command":"MarkDelivered","request_id":"delivered"}"#,
+        false,
+    );
+    run_exec(r#"{"command":"CaptureSnapshot"}"#, false);
+    run_exec(
+        r#"{"command":"QueueDispatch","request_id":"failed","target":"worker-failed"}"#,
+        false,
+    );
+    run_exec(
+        r#"{"command":"MarkFailed","request_id":"failed","reason":"target unavailable"}"#,
+        true,
+    );
+
+    let duplicate = Command::new(env!("CARGO_BIN_EXE_omx-runtime"))
+        .args([
+            "exec",
+            r#"{"command":"QueueDispatch","request_id":"failed","target":"replacement"}"#,
+            &state_arg,
+        ])
+        .output()
+        .expect("ran duplicate dispatch exec");
+    assert!(!duplicate.status.success());
+    assert!(String::from_utf8_lossy(&duplicate.stderr)
+        .contains("duplicate dispatch request id: failed"));
+    assert!(dir.join("dispatch-seen.json").exists());
+
+    let dispatch: serde_json::Value = serde_json::from_str(
+        &std::fs::read_to_string(dir.join("dispatch.json")).expect("read immediate dispatch view"),
+    )
+    .expect("valid dispatch JSON");
+    let records = dispatch["records"]
+        .as_array()
+        .expect("dispatch records array");
+    assert_eq!(records.len(), 2);
+    assert_eq!(records[0]["request_id"], "pending");
+    assert_eq!(records[0]["status"], "pending");
+    assert_eq!(records[1]["request_id"], "notified");
+    assert_eq!(records[1]["status"], "notified");
+
+    run_exec(r#"{"command":"CaptureSnapshot"}"#, false);
+    let reloaded_dispatch: serde_json::Value = serde_json::from_str(
+        &std::fs::read_to_string(dir.join("dispatch.json"))
+            .expect("read reload-persisted dispatch view"),
+    )
+    .expect("valid reload-persisted dispatch JSON");
+    let reloaded_records = reloaded_dispatch["records"]
+        .as_array()
+        .expect("reload-persisted dispatch records array");
+    assert_eq!(reloaded_records.len(), records.len());
+    for (immediate, reloaded) in records.iter().zip(reloaded_records) {
+        for field in ["request_id", "target", "status", "metadata", "reason"] {
+            assert_eq!(reloaded[field], immediate[field], "semantic field {field}");
+        }
+    }
+
+    let snapshot: serde_json::Value = serde_json::from_str(
+        &std::fs::read_to_string(dir.join("snapshot.json"))
+            .expect("read reload-persisted snapshot"),
+    )
+    .expect("valid reload-persisted snapshot JSON");
+    assert_eq!(snapshot["backlog"]["pending"], 1);
+    assert_eq!(snapshot["backlog"]["notified"], 1);
+    assert_eq!(snapshot["backlog"]["delivered"], 0);
+    assert_eq!(snapshot["backlog"]["failed"], 0);
+
+    let events: serde_json::Value = serde_json::from_str(
+        &std::fs::read_to_string(dir.join("events.json")).expect("read compacted events"),
+    )
+    .expect("valid events JSON");
+    let events = events.as_array().expect("events array");
+    assert!(events
+        .iter()
+        .any(|event| event["event"] == "SnapshotCaptured"));
+    assert!(events
+        .iter()
+        .all(|event| { event["request_id"] != "delivered" && event["request_id"] != "failed" }));
+
+    let event_request_ids: Vec<&str> = events
+        .iter()
+        .filter_map(|event| event["request_id"].as_str())
+        .collect();
+    assert_eq!(event_request_ids, vec!["pending", "notified", "notified"]);
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn concurrent_exec_queue_accepts_exactly_one_request_id() {
+    let dir = std::env::temp_dir().join("omx-runtime-test-concurrent-dispatch-id");
+    let _ = std::fs::remove_dir_all(&dir);
+    let state_arg = format!("--state-dir={}", dir.display());
+    let barrier = std::sync::Arc::new(std::sync::Barrier::new(3));
+    let mut workers = Vec::new();
+    for target in ["worker-a", "worker-b"] {
+        let barrier = std::sync::Arc::clone(&barrier);
+        let state_arg = state_arg.clone();
+        workers.push(std::thread::spawn(move || {
+            barrier.wait();
+            Command::new(env!("CARGO_BIN_EXE_omx-runtime"))
+                .args([
+                    "exec",
+                    &format!(
+                        r#"{{"command":"QueueDispatch","request_id":"concurrent","target":"{target}"}}"#
+                    ),
+                    &state_arg,
+                ])
+                .output()
+                .expect("ran concurrent dispatch exec")
+                .status
+                .success()
+        }));
+    }
+    barrier.wait();
+    assert_eq!(
+        workers
+            .into_iter()
+            .map(|worker| worker.join().unwrap())
+            .filter(|accepted| *accepted)
+            .count(),
+        1
+    );
+    let dispatch: serde_json::Value = serde_json::from_str(
+        &std::fs::read_to_string(dir.join("dispatch.json")).expect("read dispatch view"),
+    )
+    .expect("valid dispatch JSON");
+    assert_eq!(dispatch["records"].as_array().unwrap().len(), 1);
+    assert_eq!(dispatch["records"][0]["request_id"], "concurrent");
+    let _ = std::fs::remove_dir_all(&dir);
+}

package/crates/omx-runtime-core/src/dispatch.rs

@@ -39,6 +39,12 @@ pub struct DispatchRecord {
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum DispatchError {
+    DuplicateRequestId {
+        request_id: String,
+    },
+    InvalidRequestId {
+        request_id: String,
+    },
     NotFound {
         request_id: String,
     },
@@ -52,6 +58,12 @@ pub enum DispatchError {
 impl fmt::Display for DispatchError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
+            Self::DuplicateRequestId { request_id } => {
+                write!(f, "duplicate dispatch request id: {request_id}")
+            }
+            Self::InvalidRequestId { request_id } => {
+                write!(f, "invalid dispatch request id: {request_id:?}")
+            }
             Self::NotFound { request_id } => {
                 write!(f, "dispatch record not found: {request_id}")
             }
@@ -85,9 +97,20 @@ impl DispatchLog {
         request_id: impl Into<String>,
         target: impl Into<String>,
         metadata: Option<serde_json::Value>,
-    ) {
+    ) -> Result<(), DispatchError> {
+        let request_id = request_id.into();
+        if request_id.is_empty() {
+            return Err(DispatchError::InvalidRequestId { request_id });
+        }
+        if self
+            .records
+            .iter()
+            .any(|record| record.request_id == request_id)
+        {
+            return Err(DispatchError::DuplicateRequestId { request_id });
+        }
         self.records.push(DispatchRecord {
-            request_id: request_id.into(),
+            request_id,
             target: target.into(),
             status: DispatchStatus::Pending,
             created_at: now_iso(),
@@ -97,6 +120,7 @@ impl DispatchLog {
             reason: None,
             metadata,
         });
+        Ok(())
     }
 
     pub fn mark_notified(
@@ -156,6 +180,23 @@ impl DispatchLog {
         &self.records
     }
 
+    pub fn request_ids(&self) -> impl Iterator<Item = &str> {
+        self.records.iter().map(|record| record.request_id.as_str())
+    }
+
+    pub fn contains_request_id(&self, request_id: &str) -> bool {
+        self.records
+            .iter()
+            .any(|record| record.request_id == request_id)
+    }
+
+    /// Remove records that have reached a terminal delivery state.
+    pub fn prune_terminal_records(&mut self) {
+        self.records.retain(|record| {
+            record.status != DispatchStatus::Delivered && record.status != DispatchStatus::Failed
+        });
+    }
+
     pub fn to_backlog_snapshot(&self) -> BacklogSnapshot {
         let mut snapshot = BacklogSnapshot::default();
         for record in &self.records {
@@ -248,7 +289,7 @@ mod tests {
     #[test]
     fn queue_and_transition_happy_path() {
         let mut log = DispatchLog::new();
-        log.queue("req-1", "worker-1", None);
+        log.queue("req-1", "worker-1", None).unwrap();
         assert_eq!(log.records().len(), 1);
         assert_eq!(log.records()[0].status, DispatchStatus::Pending);
 
@@ -262,7 +303,7 @@ mod tests {
     #[test]
     fn mark_failed_from_notified() {
         let mut log = DispatchLog::new();
-        log.queue("req-1", "worker-1", None);
+        log.queue("req-1", "worker-1", None).unwrap();
         log.mark_notified("req-1", "tmux").unwrap();
         log.mark_failed("req-1", "send_error").unwrap();
         assert_eq!(log.records()[0].status, DispatchStatus::Failed);
@@ -271,7 +312,7 @@ mod tests {
     #[test]
     fn invalid_transition_errors() {
         let mut log = DispatchLog::new();
-        log.queue("req-1", "worker-1", None);
+        log.queue("req-1", "worker-1", None).unwrap();
 
         // Can't deliver from pending
         let err = log.mark_delivered("req-1").unwrap_err();
@@ -282,7 +323,7 @@ mod tests {
     fn mark_failed_from_pending() {
         // Matches TS behavior: pending -> failed allowed for target resolution failures
         let mut log = DispatchLog::new();
-        log.queue("req-1", "worker-1", None);
+        log.queue("req-1", "worker-1", None).unwrap();
         log.mark_failed("req-1", "target_resolution_failed")
             .unwrap();
         assert_eq!(log.records()[0].status, DispatchStatus::Failed);
@@ -298,9 +339,9 @@ mod tests {
     #[test]
     fn backlog_snapshot_counts() {
         let mut log = DispatchLog::new();
-        log.queue("req-1", "w1", None);
-        log.queue("req-2", "w2", None);
-        log.queue("req-3", "w3", None);
+        log.queue("req-1", "w1", None).unwrap();
+        log.queue("req-2", "w2", None).unwrap();
+        log.queue("req-3", "w3", None).unwrap();
         log.mark_notified("req-2", "tmux").unwrap();
         log.mark_notified("req-3", "tmux").unwrap();
         log.mark_delivered("req-2").unwrap();
@@ -313,11 +354,34 @@ mod tests {
         assert_eq!(snap.failed, 1);
     }
 
+    #[test]
+    fn prune_terminal_records_keeps_pending_and_notified_records() {
+        let mut log = DispatchLog::new();
+        log.queue("pending", "w1", None).unwrap();
+        log.queue("notified", "w2", None).unwrap();
+        log.queue("delivered", "w3", None).unwrap();
+        log.queue("failed", "w4", None).unwrap();
+        log.mark_notified("notified", "tmux").unwrap();
+        log.mark_notified("delivered", "tmux").unwrap();
+        log.mark_delivered("delivered").unwrap();
+        log.mark_failed("failed", "target resolution failed")
+            .unwrap();
+
+        log.prune_terminal_records();
+
+        assert_eq!(log.records().len(), 2);
+        assert_eq!(log.records()[0].request_id, "pending");
+        assert_eq!(log.records()[0].status, DispatchStatus::Pending);
+        assert_eq!(log.records()[1].request_id, "notified");
+        assert_eq!(log.records()[1].status, DispatchStatus::Notified);
+    }
+
     #[test]
     fn queue_with_metadata_round_trips() {
         let mut log = DispatchLog::new();
         let meta = serde_json::json!({"priority": "high", "tags": ["urgent"]});
-        log.queue("req-meta", "worker-1", Some(meta.clone()));
+        log.queue("req-meta", "worker-1", Some(meta.clone()))
+            .unwrap();
 
         assert_eq!(log.records()[0].metadata, Some(meta.clone()));
 
@@ -327,4 +391,26 @@ mod tests {
         assert_eq!(loaded.records()[0].metadata, Some(meta));
         assert_eq!(loaded.records()[0].request_id, "req-meta");
     }
+
+    #[test]
+    fn queue_rejects_duplicate_request_id_after_terminal_transition() {
+        let mut log = DispatchLog::new();
+        log.queue("req-1", "worker-1", None).unwrap();
+        log.mark_failed("req-1", "target unavailable").unwrap();
+
+        let err = log.queue("req-1", "worker-2", None).unwrap_err();
+        assert!(
+            matches!(err, DispatchError::DuplicateRequestId { request_id } if request_id == "req-1")
+        );
+        assert_eq!(log.records().len(), 1);
+    }
+
+    #[test]
+    fn queue_rejects_empty_request_id() {
+        let mut log = DispatchLog::new();
+        assert!(matches!(
+            log.queue("", "worker", None),
+            Err(DispatchError::InvalidRequestId { request_id }) if request_id.is_empty()
+        ));
+    }
 }