oh-my-codex 0.12.6 → 0.13.1

package/Cargo.lock

@@ -32,11 +32,11 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "omx-explore-harness"
-version = "0.12.6"
+version = "0.13.1"
 
 [[package]]
 name = "omx-mux"
-version = "0.12.6"
+version = "0.13.1"
 dependencies = [
  "serde",
  "serde_json",
@@ -44,7 +44,7 @@ dependencies = [
 
 [[package]]
 name = "omx-runtime"
-version = "0.12.6"
+version = "0.13.1"
 dependencies = [
  "omx-mux",
  "omx-runtime-core",
@@ -53,7 +53,7 @@ dependencies = [
 
 [[package]]
 name = "omx-runtime-core"
-version = "0.12.6"
+version = "0.13.1"
 dependencies = [
  "fs2",
  "serde",
@@ -62,7 +62,7 @@ dependencies = [
 
 [[package]]
 name = "omx-sparkshell"
-version = "0.12.6"
+version = "0.13.1"
 dependencies = [
  "omx-mux",
 ]

package/Cargo.toml

@@ -10,7 +10,7 @@ resolver = "2"
 
 [workspace.package]
 
-version = "0.12.6"
+version = "0.13.1"
 
 edition = "2021"
 license = "MIT"

package/README.md

@@ -72,6 +72,7 @@ $team 3:executor "execute the approved plan in parallel"
 ```
 
 That is the main path.
+Before you treat the runtime as ready, run the quick-start smoke test below: `omx doctor` verifies the install shape, while `omx exec` proves the active Codex runtime can actually authenticate and complete a model call from the current environment.
 Start OMX strongly, clarify first when needed, approve the plan, then choose `$team` for coordinated parallel execution or `$ralph` for the persistent completion loop.
 
 ## What OMX is for
@@ -90,12 +91,22 @@ If you want plain Codex with no extra workflow layer, you probably do not need O
 
 - Node.js 20+
 - Codex CLI installed: `npm install -g @openai/codex`
-- Codex auth configured
+- Codex auth configured and visible in the same shell/profile that will run OMX
 - `tmux` on macOS/Linux if you want the recommended durable team runtime
 - `psmux` on native Windows only if you intentionally want the less-supported Windows team path
 
 ### A good first session
 
+After install, check both boundaries:
+
+```bash
+omx doctor
+codex login status
+omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
+```
+
+`omx doctor` catches missing OMX files, hooks, and runtime prerequisites. The real smoke test catches auth, profile, and provider/base-URL problems that only appear when Codex performs an actual request.
+
 Launch OMX the recommended way:
 
 ```bash
@@ -135,10 +146,12 @@ Most users should think of OMX as **better task routing + better workflow + bett
 ## Start here if you are new
 
 1. Run `omx setup`
-2. Launch with `omx --madmax --high`
-3. Use `$deep-interview "..."` when the request or boundaries are still unclear
-4. Use `$ralplan "..."` to approve the plan and review tradeoffs
-5. Choose `$team` for coordinated parallel execution or `$ralph` for persistent completion loops
+2. Run `omx doctor`
+3. Run a real execution smoke test: `codex login status` and `omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"`
+4. Launch with `omx --madmax --high`
+5. Use `$deep-interview "..."` when the request or boundaries are still unclear
+6. Use `$ralplan "..."` to approve the plan and review tradeoffs
+7. Choose `$team` for coordinated parallel execution or `$ralph` for persistent completion loops
 
 ## Recommended workflow
 
@@ -177,7 +190,7 @@ These are operator/support surfaces:
 - `omx setup` installs prompts, skills, AGENTS scaffolding, `.codex/config.toml`, and 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
   - `omx uninstall` removes OMX-managed wrappers from `.codex/hooks.json` but keeps the file when user hooks remain
-- `omx doctor` verifies the install when something seems wrong
+- `omx doctor` verifies the install when something seems wrong; it does not prove that the active Codex profile can make an authenticated model call
 - `omx hud --watch` is a monitoring/status surface, not the primary user workflow
 
 For non-team sessions, native Codex hooks are now the canonical lifecycle surface:
@@ -187,6 +200,24 @@ For non-team sessions, native Codex hooks are now the canonical lifecycle surfac
 
 See [Codex native hook mapping](./docs/codex-native-hooks.md) for the current native / fallback matrix.
 
+
+### Troubleshooting false-green readiness
+
+A green `omx doctor` means the install and local runtime wiring look sane. If real execution still fails, check the environment Codex actually uses:
+
+- Run `codex login status` and `omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"` from the same shell/profile that will launch OMX.
+- In custom HOME, profile, container, or service shells, confirm the active `~/.codex` (or `CODEX_HOME`) is the one with the expected auth and config. Do not assume your normal user `~/.codex` is visible there.
+- If you depend on a local OpenAI-compatible proxy, confirm the active `~/.codex/config.toml` includes the expected `openai_base_url`; otherwise a proxy-issued key can be sent to the default endpoint and fail with `401 Unauthorized`, `Missing bearer or basic authentication in header`, or `Incorrect API key provided`.
+- If `omx doctor --team` or resume reports a stale team such as `resume_blocker` or a missing tmux session, clean the dead runtime state before retrying:
+
+```bash
+omx team shutdown <team-name> --force --confirm-issues
+omx cancel
+omx doctor --team
+```
+
+Only use the forced team shutdown for a team you have confirmed is dead or intentionally abandoned.
+
 ### Explore and sparkshell
 
 - `omx explore --prompt "..."` is for read-only repository lookup
@@ -220,6 +251,7 @@ omx wiki refresh --json
 
 `omx team` works best on macOS/Linux with `tmux`.
 Native Windows remains a secondary path, and WSL2 is generally the better choice if you want a Windows-hosted setup.
+On native Windows, OMX accepts `psmux` as the tmux-compatible binary for the existing tmux-backed paths it already uses.
 
 | Platform | Install |
 | --- | --- |
@@ -250,6 +282,7 @@ If this happens, try:
 - [Skills reference](./docs/skills.html)
 - [Codex native hook mapping](./docs/codex-native-hooks.md)
 - [Integrations](./docs/integrations.html)
+- [Troubleshooting execution readiness](./docs/troubleshooting.md)
 - [OpenClaw / notification gateway guide](./docs/openclaw-integration.md)
 - [Contributing](./CONTRIBUTING.md)
 - [Changelog](./CHANGELOG.md)

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

@@ -12,6 +12,8 @@ const CODEX_BIN_ENV: &str = "OMX_EXPLORE_CODEX_BIN";
 const HARNESS_ROOT_ENV: &str = "OMX_EXPLORE_ROOT";
 const INTERNAL_DIRECT_WRAPPER_FLAG: &str = "--internal-allowlist-direct";
 const INTERNAL_SHELL_WRAPPER_FLAG: &str = "--internal-allowlist-shell";
+const WINDOWS_UNSUPPORTED_ALLOWLIST_MESSAGE: &str =
+    "omx explore built-in harness is not ready on Windows because its allowlist runtime relies on POSIX sh/bash wrappers. Set OMX_EXPLORE_BIN to a compatible custom harness, prefer `omx sparkshell` for shell-native read-only lookups, or run `omx doctor` for readiness details.";
 
 const ALLOWED_DIRECT_COMMANDS: &[&str] = &[
     "rg", "grep", "ls", "find", "wc", "cat", "head", "tail", "pwd", "printf",
@@ -270,7 +272,12 @@ fn resolve_codex_binary() -> String {
 }
 
 fn codex_launch_for_binary(codex_binary: &str) -> Option<CodexLaunch> {
-    let interpreter = read_shebang_interpreter(Path::new(codex_binary))?;
+    let codex_path = Path::new(codex_binary);
+    if let Some(launch) = codex_launch_for_posix_node_shim(codex_path) {
+        return Some(launch);
+    }
+
+    let interpreter = read_shebang_interpreter(codex_path)?;
     let (program, mut leading_args) = resolve_shebang_launch(&interpreter)?;
     leading_args.push(codex_binary.to_string());
     Some(CodexLaunch {
@@ -279,6 +286,21 @@ fn codex_launch_for_binary(codex_binary: &str) -> Option<CodexLaunch> {
     })
 }
 
+fn codex_launch_for_posix_node_shim(codex_path: &Path) -> Option<CodexLaunch> {
+    let shebang = read_shebang_interpreter(codex_path)?;
+    if !is_posix_shell_shebang(&shebang) {
+        return None;
+    }
+
+    let script = read_to_string(codex_path).ok()?;
+    let entrypoint = resolve_posix_node_shim_entrypoint(codex_path, &script)?;
+    let program = resolve_posix_node_shim_program(codex_path, &script)?;
+    Some(CodexLaunch {
+        program: program.display().to_string(),
+        leading_args: vec![entrypoint.display().to_string()],
+    })
+}
+
 fn read_shebang_interpreter(path: &Path) -> Option<String> {
     let file = File::open(path).ok()?;
     let mut reader = BufReader::new(file);
@@ -293,6 +315,85 @@ fn read_shebang_interpreter(path: &Path) -> Option<String> {
         .map(ToOwned::to_owned)
 }
 
+fn is_posix_shell_shebang(shebang: &str) -> bool {
+    let parts: Vec<&str> = shebang.split_whitespace().collect();
+    let interpreter = *parts.first().unwrap_or(&"");
+    if interpreter.ends_with("/env") {
+        return parts
+            .get(1)
+            .is_some_and(|target| is_posix_shell_name(target));
+    }
+    is_posix_shell_name(interpreter)
+}
+
+fn is_posix_shell_name(value: &str) -> bool {
+    matches!(
+        Path::new(value).file_name().and_then(|name| name.to_str()),
+        Some("sh" | "bash" | "dash" | "ash" | "ksh" | "zsh")
+    )
+}
+
+fn resolve_posix_node_shim_entrypoint(codex_path: &Path, script: &str) -> Option<PathBuf> {
+    let basedir = codex_path.parent()?;
+    quoted_shell_segments(script)
+        .into_iter()
+        .filter_map(|segment| strip_basedir_prefix(&segment).map(ToOwned::to_owned))
+        .map(|relative| normalize_path(basedir.join(relative)))
+        .find(|candidate| is_node_entrypoint(candidate))
+}
+
+fn resolve_posix_node_shim_program(codex_path: &Path, script: &str) -> Option<PathBuf> {
+    let basedir = codex_path.parent()?;
+    if quoted_shell_segments(script)
+        .into_iter()
+        .any(|segment| matches!(strip_basedir_prefix(&segment), Some("node")))
+    {
+        let sibling_node = basedir.join("node");
+        if is_usable_host_command(&sibling_node) {
+            return Some(sibling_node);
+        }
+    }
+    resolve_host_command("node")
+}
+
+fn quoted_shell_segments(script: &str) -> Vec<String> {
+    let mut segments = Vec::new();
+    let mut active_quote: Option<char> = None;
+    let mut current = String::new();
+
+    for ch in script.chars() {
+        if let Some(quote) = active_quote {
+            if ch == quote {
+                segments.push(std::mem::take(&mut current));
+                active_quote = None;
+            } else {
+                current.push(ch);
+            }
+            continue;
+        }
+
+        if ch == '\'' || ch == '"' {
+            active_quote = Some(ch);
+        }
+    }
+
+    segments
+}
+
+fn strip_basedir_prefix(segment: &str) -> Option<&str> {
+    segment
+        .strip_prefix("$basedir/")
+        .or_else(|| segment.strip_prefix("${basedir}/"))
+}
+
+fn is_node_entrypoint(path: &Path) -> bool {
+    path.is_file()
+        && matches!(
+            path.extension().and_then(|value| value.to_str()),
+            Some("js" | "cjs" | "mjs")
+        )
+}
+
 fn resolve_shebang_launch(shebang: &str) -> Option<(String, Vec<String>)> {
     let parts: Vec<&str> = shebang.split_whitespace().collect();
     let interpreter = *parts.first()?;
@@ -366,6 +467,9 @@ fn compose_exec_prompt(user_prompt: &str, prompt_contract: &str) -> String {
 }
 
 fn prepare_allowlist_environment() -> Result<AllowlistEnvironment, String> {
+    if let Some(message) = allowlist_platform_diagnostic(env::consts::OS) {
+        return Err(message.to_string());
+    }
     let root = temp_allowlist_dir()?;
     let bin_dir = root.path.join("bin");
     create_dir_all(&bin_dir).map_err(|err| {
@@ -412,6 +516,13 @@ fn prepare_allowlist_environment() -> Result<AllowlistEnvironment, String> {
     })
 }
 
+fn allowlist_platform_diagnostic(os: &str) -> Option<&'static str> {
+    if os.eq_ignore_ascii_case("windows") {
+        return Some(WINDOWS_UNSUPPORTED_ALLOWLIST_MESSAGE);
+    }
+    None
+}
+
 fn temp_allowlist_dir() -> Result<TempDirGuard, String> {
     let dir = env::temp_dir().join(format!(
         "omx-explore-allowlist-{}-{}",
@@ -469,20 +580,39 @@ fn build_direct_wrapper(self_exe: &Path, command: &str) -> Result<String, String
 
 fn resolve_host_command(command: &str) -> Option<PathBuf> {
     let candidate = Path::new(command);
-    if candidate.is_absolute() && candidate.exists() {
+    if candidate.is_absolute() && is_usable_host_command(candidate) {
         return Some(candidate.to_path_buf());
     }
 
     let path = env::var_os("PATH")?;
     for entry in env::split_paths(&path) {
         let resolved = entry.join(command);
-        if resolved.exists() {
+        if is_usable_host_command(&resolved) {
             return Some(resolved);
         }
     }
     None
 }
 
+fn is_usable_host_command(path: &Path) -> bool {
+    let metadata = match path.metadata() {
+        Ok(metadata) => metadata,
+        Err(_) => return false,
+    };
+    if !metadata.is_file() {
+        return false;
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        metadata.permissions().mode() & 0o111 != 0
+    }
+    #[cfg(not(unix))]
+    {
+        true
+    }
+}
+
 fn shell_quote(value: &str) -> String {
     format!("'{}'", value.replace('\'', "'\"'\"'"))
 }
@@ -885,6 +1015,7 @@ mod tests {
 
     #[test]
     fn codex_launch_for_env_node_shebang_uses_host_node_absolute_path() {
+        let _guard = env_lock();
         let root = temp_allowlist_dir().expect("temp root");
         let script_path = root.path.join("codex-script");
         write(&script_path, b"#!/usr/bin/env node\nconsole.log(\"ok\");\n").expect("write script");
@@ -896,6 +1027,162 @@ mod tests {
         assert_eq!(launch.leading_args, vec![script_path.display().to_string()]);
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn codex_launch_for_posix_package_manager_shim_uses_host_node_and_entrypoint() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let host_bin = root.path.join("host-bin");
+        let shim_dir = root.path.join("node_modules").join(".bin");
+        let entrypoint = root
+            .path
+            .join("node_modules")
+            .join("@openai")
+            .join("codex")
+            .join("bin")
+            .join("codex.js");
+        create_dir_all(&host_bin).expect("create host bin");
+        create_dir_all(&shim_dir).expect("create shim dir");
+        create_dir_all(entrypoint.parent().expect("entrypoint parent"))
+            .expect("create entrypoint dir");
+
+        let fake_node = host_bin.join("node");
+        write_executable(&fake_node, "#!/bin/sh\nexit 0\n").expect("write fake node");
+        write(&entrypoint, "console.log('ok');\n").expect("write entrypoint");
+
+        let shim_path = shim_dir.join("codex");
+        write_executable(
+            &shim_path,
+            r#"#!/bin/sh
+basedir=$(dirname "$0")
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node" "$basedir/../@openai/codex/bin/codex.js" "$@"
+fi
+exec node "$basedir/../@openai/codex/bin/codex.js" "$@"
+"#,
+        )
+        .expect("write shim");
+
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var("PATH", &host_bin);
+        }
+
+        let launch =
+            codex_launch_for_binary(shim_path.to_str().expect("shim path")).expect("launch config");
+
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+
+        assert_eq!(launch.program, fake_node.display().to_string());
+        assert_eq!(launch.leading_args, vec![entrypoint.display().to_string()]);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn resolve_host_command_skips_directory_and_non_executable_path_entries() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let bad_bin = root.path.join("bad-bin");
+        let blocked_file_bin = root.path.join("blocked-file-bin");
+        let good_bin = root.path.join("good-bin");
+        create_dir_all(&bad_bin).expect("create bad bin");
+        create_dir_all(&blocked_file_bin).expect("create blocked file bin");
+        create_dir_all(&good_bin).expect("create good bin");
+
+        let blocked_directory = bad_bin.join("node");
+        create_dir_all(&blocked_directory).expect("create blocked directory");
+
+        let blocked_node = blocked_file_bin.join("node");
+        write(&blocked_node, "#!/bin/sh\nexit 0\n").expect("write blocked file node");
+        let executable_node = good_bin.join("node");
+        write_executable(&executable_node, "#!/bin/sh\nexit 0\n").expect("write executable node");
+
+        #[cfg(unix)]
+        {
+            use std::fs;
+            use std::os::unix::fs::PermissionsExt;
+            let mut perms = fs::metadata(&blocked_node)
+                .expect("stat blocked node")
+                .permissions();
+            perms.set_mode(0o644);
+            fs::set_permissions(&blocked_node, perms).expect("chmod blocked node");
+        }
+
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var(
+                "PATH",
+                env::join_paths([
+                    bad_bin.as_path(),
+                    blocked_file_bin.as_path(),
+                    good_bin.as_path(),
+                ])
+                .expect("join path"),
+            );
+        }
+
+        let resolved = resolve_host_command("node");
+
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+
+        assert_eq!(resolved, Some(executable_node));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn codex_launch_for_env_node_shebang_skips_non_executable_earlier_node_entry() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let bad_bin = root.path.join("bad-bin");
+        let good_bin = root.path.join("good-bin");
+        create_dir_all(&bad_bin).expect("create bad bin");
+        create_dir_all(&good_bin).expect("create good bin");
+
+        let blocked_node = bad_bin.join("node");
+        write(&blocked_node, "#!/bin/sh\nexit 0\n").expect("write blocked node");
+        let executable_node = good_bin.join("node");
+        write_executable(&executable_node, "#!/bin/sh\nexit 0\n").expect("write executable node");
+
+        #[cfg(unix)]
+        {
+            use std::fs;
+            use std::os::unix::fs::PermissionsExt;
+            let mut perms = fs::metadata(&blocked_node)
+                .expect("stat blocked node")
+                .permissions();
+            perms.set_mode(0o644);
+            fs::set_permissions(&blocked_node, perms).expect("chmod blocked node");
+        }
+
+        let script_path = root.path.join("codex-script");
+        write(&script_path, b"#!/usr/bin/env node\nconsole.log(\"ok\");\n").expect("write script");
+
+        let original_path = env::var_os("PATH");
+        unsafe {
+            env::set_var(
+                "PATH",
+                env::join_paths([bad_bin.as_path(), good_bin.as_path()]).expect("join path"),
+            );
+        }
+
+        let launch = codex_launch_for_binary(script_path.to_str().expect("script path"))
+            .expect("launch config");
+
+        match original_path {
+            Some(value) => unsafe { env::set_var("PATH", value) },
+            None => unsafe { env::remove_var("PATH") },
+        }
+
+        assert_eq!(launch.program, executable_node.display().to_string());
+        assert_eq!(launch.leading_args, vec![script_path.display().to_string()]);
+    }
+
     #[cfg(unix)]
     fn create_host_bin_with_commands(commands: &[&str]) -> (TempDirGuard, PathBuf) {
         let root = temp_allowlist_dir().expect("temp root");
@@ -972,6 +1259,7 @@ mod tests {
     #[cfg(unix)]
     #[test]
     fn prepare_allowlist_environment_preserves_present_command_wrapper_execution() {
+        let _guard = env_lock();
         let self_exe = env::current_exe().expect("current exe");
         let pwd = resolve_host_command("pwd").expect("host pwd path");
 
@@ -1047,6 +1335,15 @@ mod tests {
         );
     }
 
+    #[test]
+    fn allowlist_platform_diagnostic_blocks_windows_with_actionable_guidance() {
+        let diagnostic = allowlist_platform_diagnostic("windows").expect("windows diagnostic");
+
+        assert!(diagnostic.contains("not ready on Windows"));
+        assert!(diagnostic.contains("OMX_EXPLORE_BIN"));
+        assert!(allowlist_platform_diagnostic("linux").is_none());
+    }
+
     #[test]
     fn validate_direct_command_covers_additional_head_wc_and_tail_rejections() {
         assert!(validate_direct_command("head", &["-".into()]).is_err());

package/dist/adapt/__tests__/foundation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=foundation.test.d.ts.map

package/dist/adapt/__tests__/foundation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation.test.d.ts","sourceRoot":"","sources":["../../../src/adapt/__tests__/foundation.test.ts"],"names":[],"mappings":""}