fix(codex): harden stop-hook installer runtime

Author: wey-gu

nowledge-mem-codex-plugin/README.md

@@ -27,9 +27,9 @@ Codex does not give this package hard lifecycle hooks like Claude Code or OpenCl
 
 ## Prerequisites
 
-For day-to-day skill usage, `nmem` must be on your PATH.
+For day-to-day skill usage, put `nmem` on your PATH.
 
-For automatic `Stop`-hook capture, the Python interpreter that runs `scripts/install_hooks.py` must also be able to import `nmem_cli`. `uvx --from nmem-cli nmem` is enough for interactive CLI commands, but it does not make `nmem_cli` importable to Codex's hook runtime by itself.
+For automatic `Stop`-hook capture, the Python interpreter that runs `scripts/install_hooks.py` must be able to import `nmem_cli`. `uvx --from nmem-cli nmem` is enough for interactive CLI commands, but it does not make `nmem_cli` importable to Codex's hook runtime by itself.
 
 **Quickest path** (if the Nowledge Mem desktop app is running):
 Settings > Preferences > Developer Tools > Install CLI
@@ -67,7 +67,7 @@ plugins = true
 enabled = true
 ```
 
-Install the bundled Codex hook helper with the same Python interpreter you want Codex to use for the hook runtime:
+Install the bundled Codex hook helper with the same Python you want Codex to use for the hook runtime:
 
 ```bash
 python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py
@@ -216,7 +216,7 @@ If you used `nowledge-mem-codex-prompts` before:
 - **"plugin is not installed"**: Check that the plugin files are at `~/.codex/plugins/cache/local/nowledge-mem/local/` and that `.codex-plugin/plugin.json` exists inside that directory.
 - **Hooks do not fire**: Run `python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py` again, then confirm `~/.codex/hooks.json` exists and `codex_hooks = true` is present under `[features]` in `~/.codex/config.toml`.
 - **Installer says `nmem_cli` is missing**: Run `python3 -m pip install nmem-cli`, then verify `python3 -c "import nmem_cli, nmem_cli.session_import"` succeeds before rerunning `scripts/install_hooks.py`.
-- **No auto-save after a response**: Inspect `~/.codex/log/nowledge-mem-stop-hook.log`. If the log shows repeated skips, check that the installed hook starts with the same `#!python` you used for `scripts/install_hooks.py`, and that `python3 -c "import nmem_cli, nmem_cli.session_import"` succeeds in that interpreter.
+- **No auto-save after a response**: Inspect `~/.codex/log/nowledge-mem-stop-hook.log`. The hook imports directly from Codex's `transcript_path`; if the log shows repeated skips, check that the installed hook starts with the same `#!python` you used for `scripts/install_hooks.py`, and that `python3 -c "import nmem_cli, nmem_cli.session_import"` succeeds in that interpreter.
 - **Only Working Memory runs, but search/distill never show up**: this package is skill-guided, not hook-driven. Merge the package `AGENTS.md` into the project root for stronger repo-specific behavior, and verify you are asking a continuation-style question rather than a fresh isolated one.
 
 ## Links

nowledge-mem-codex-plugin/RELEASING.md

@@ -23,6 +23,8 @@ node nowledge-mem-codex-plugin/scripts/validate-plugin.mjs
 - update expected version checks in `scripts/validate-plugin.mjs`
 - keep install examples on `cp -r .../. ...` so `.codex-plugin/` is copied
 - keep `scripts/install_hooks.py` idempotent
+- keep the installer enforcing a Python runtime that can `import nmem_cli`
+- keep the copied hook pinned to the installer interpreter (`sys.executable`)
 - keep `hooks/nmem-stop-save.py` focused on direct transcript import via `transcript_path`
 - re-run `node nowledge-mem-codex-plugin/scripts/validate-plugin.mjs`
 
@@ -31,6 +33,7 @@ node nowledge-mem-codex-plugin/scripts/validate-plugin.mjs
 After copying the plugin into `~/.codex/plugins/cache/local/nowledge-mem/local/`:
 
 ```bash
+python3 -c "import nmem_cli, nmem_cli.session_import"
 python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py
 codex exec -C . "Reply with exactly OK and nothing else."
 tail -n 20 ~/.codex/log/nowledge-mem-stop-hook.log

nowledge-mem-codex-plugin/scripts/install_hooks.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
 from __future__ import annotations
 
+import importlib.util
 import json
+import re
 import shutil
 import stat
 import sys
@@ -18,19 +20,76 @@
 CONFIG_FILE = CODEX_DIR / "config.toml"
 SOURCE_HOOK = PLUGIN_ROOT / "hooks" / "nmem-stop-save.py"
 INSTALLED_HOOK = HOOKS_DIR / "nowledge-mem-stop-save.py"
+CODEX_HOOKS_KEY_RE = re.compile(r"^\s*codex_hooks\s*=")
+
+
+def backup_invalid_json(path: Path, *, reason: str) -> dict:
+    backup = path.with_name(f"{path.name}.{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}.bak")
+    shutil.move(path, backup)
+    print(f"warning: moved {reason} to {backup}", file=sys.stderr)
+    return {}
 
 
 def load_json(path: Path) -> dict:
     if not path.exists():
         return {}
     try:
-        return json.loads(path.read_text(encoding="utf-8"))
+        payload = json.loads(path.read_text(encoding="utf-8"))
     except json.JSONDecodeError:
-        backup = path.with_name(f"{path.name}.{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}.bak")
-        shutil.move(path, backup)
-        print(f"warning: moved malformed JSON to {backup}", file=sys.stderr)
-        return {}
-
+        return backup_invalid_json(path, reason="malformed JSON")
+    if not isinstance(payload, dict):
+        return backup_invalid_json(path, reason="non-object JSON")
+    return payload
+
+
+def ensure_nmem_cli_runtime_ready() -> None:
+    required_modules = ("nmem_cli", "nmem_cli.session_import")
+    missing = [name for name in required_modules if importlib.util.find_spec(name) is None]
+    if not missing:
+        return
+    missing_text = ", ".join(missing)
+    raise SystemExit(
+        "This installer must be run with a Python interpreter that can import "
+        f"{missing_text}. Install nmem-cli into that interpreter, then rerun "
+        "scripts/install_hooks.py with the same python3."
+    )
+
+
+def normalize_hooks_doc(hooks_doc: dict) -> tuple[dict, list[dict]]:
+    hooks = hooks_doc.get("hooks")
+    if not isinstance(hooks, dict):
+        hooks = {}
+        hooks_doc["hooks"] = hooks
+
+    stop_hooks = hooks.get("Stop")
+    if not isinstance(stop_hooks, list):
+        stop_hooks = []
+
+    normalized_stop_hooks: list[dict] = []
+    for entry in stop_hooks:
+        if not isinstance(entry, dict):
+            continue
+        normalized_entry = dict(entry)
+        if not isinstance(normalized_entry.get("hooks"), list):
+            normalized_entry["hooks"] = []
+        normalized_stop_hooks.append(normalized_entry)
+
+    hooks["Stop"] = normalized_stop_hooks
+    return hooks_doc, normalized_stop_hooks
+
+
+def rewrite_hook_shebang(path: Path) -> None:
+    original = path.read_text(encoding="utf-8")
+    lines = original.splitlines()
+    desired = f"#!{sys.executable}"
+    if lines and lines[0].startswith("#!"):
+        lines[0] = desired
+    else:
+        lines.insert(0, desired)
+    updated = "\n".join(lines)
+    if original.endswith("\n"):
+        updated += "\n"
+    path.write_text(updated, encoding="utf-8")
 
 def save_json(path: Path, payload: dict) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
@@ -40,6 +99,7 @@ def save_json(path: Path, payload: dict) -> None:
 def install_runtime_hook() -> None:
     HOOKS_DIR.mkdir(parents=True, exist_ok=True)
     shutil.copy2(SOURCE_HOOK, INSTALLED_HOOK)
+    rewrite_hook_shebang(INSTALLED_HOOK)
     mode = INSTALLED_HOOK.stat().st_mode
     INSTALLED_HOOK.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
 
@@ -53,8 +113,7 @@ def merge_hooks_json() -> None:
     else:
         hooks_doc = {}
 
-    hooks = hooks_doc.setdefault("hooks", {})
-    stop_hooks = hooks.setdefault("Stop", [])
+    hooks_doc, stop_hooks = normalize_hooks_doc(hooks_doc)
 
     desired = {
         "matcher": ".*",
@@ -68,7 +127,9 @@ def merge_hooks_json() -> None:
 
     replaced = False
     for index, entry in enumerate(stop_hooks):
-        for hook in entry.get("hooks", []):
+        for hook in entry["hooks"]:
+            if not isinstance(hook, dict):
+                continue
             if hook.get("command") == str(INSTALLED_HOOK):
                 stop_hooks[index] = desired
                 replaced = True
@@ -113,7 +174,7 @@ def ensure_codex_hooks_enabled() -> None:
         replaced = False
         for index in range(features_start + 1, features_end):
             stripped = lines[index].strip()
-            if stripped.startswith(f"{target_key} "):
+            if CODEX_HOOKS_KEY_RE.match(stripped):
                 lines[index] = "codex_hooks = true"
                 replaced = True
                 break
@@ -128,6 +189,7 @@ def ensure_codex_hooks_enabled() -> None:
 
 
 def main() -> int:
+    ensure_nmem_cli_runtime_ready()
     install_runtime_hook()
     merge_hooks_json()
     ensure_codex_hooks_enabled()

nowledge-mem-codex-plugin/scripts/refresh_thread_titles.py

@@ -7,14 +7,12 @@
 from pathlib import Path
 from urllib.parse import quote
 
-from nmem_cli import cli
-from nmem_cli.session_import import parse_codex_session_streaming
-
-
 SESSIONS_ROOT = Path.home() / ".codex" / "sessions"
 AGENTS_PREFIX = "# AGENTS.md instructions for "
 GET_TIMEOUT_SECONDS = 10.0
 IMPORT_TIMEOUT_SECONDS = 120.0
+cli = None
+parse_codex_session_streaming = None
 
 
 def load_hook_module():
@@ -30,8 +28,20 @@ def iter_codex_rollouts() -> list[Path]:
     return sorted(SESSIONS_ROOT.rglob("rollout-*.jsonl"))
 
 
+def ensure_nmem_modules() -> tuple[object, object]:
+    global cli, parse_codex_session_streaming
+    if cli is None or parse_codex_session_streaming is None:
+        from nmem_cli import cli as cli_module
+        from nmem_cli.session_import import parse_codex_session_streaming as parser
+
+        cli = cli_module
+        parse_codex_session_streaming = parser
+    return cli, parse_codex_session_streaming
+
+
 def get_thread(thread_id: str) -> dict | None:
-    return cli.api_get_optional(
+    cli_module, _ = ensure_nmem_modules()
+    return cli_module.api_get_optional(
         f"/threads/{quote(thread_id, safe='')}",
         timeout=GET_TIMEOUT_SECONDS,
     )
@@ -101,13 +111,14 @@ def main() -> int:
     args = parser.parse_args()
 
     hook_module = load_hook_module()
+    _, parse_codex = ensure_nmem_modules()
     checked = 0
     refreshed = 0
     errors = 0
 
     for rollout_path in iter_codex_rollouts():
         try:
-            parsed = parse_codex_session_streaming(rollout_path, truncate_large_content=True)
+            parsed = parse_codex(rollout_path, truncate_large_content=True)
             thread_id = parsed["thread_id"]
         except Exception as exc:
             errors += 1
@@ -156,6 +167,9 @@ def main() -> int:
         except SystemExit as exc:
             errors += 1
             print(f"ERROR refresh {thread_id}: exited {exc.code}", flush=True)
+        except Exception as exc:
+            errors += 1
+            print(f"ERROR refresh {thread_id}: {exc}", flush=True)
 
     print(
         json.dumps(

nowledge-mem-codex-plugin/scripts/validate-plugin.mjs

@@ -109,6 +109,7 @@ if (readme !== null) {
     "~/.codex/hooks.json",
     "codex_hooks = true",
     "host-level",
+    "nmem_cli",
   ]) {
     if (!readme.includes(phrase)) {
       fail(`README must mention ${phrase}`);

nowledge-mem-codex-plugin/tests/test_codex_plugin.py

@@ -393,6 +393,33 @@ def test_load_json_recovers_from_malformed_json(self):
         backups = list(self.module.GLOBAL_HOOKS_FILE.parent.glob("hooks.json.*.bak"))
         self.assertEqual(len(backups), 1)
 
+    def test_load_json_recovers_from_non_object_json(self):
+        self.module.GLOBAL_HOOKS_FILE.parent.mkdir(parents=True, exist_ok=True)
+        self.module.GLOBAL_HOOKS_FILE.write_text('["not-an-object"]', encoding="utf-8")
+
+        payload = self.module.load_json(self.module.GLOBAL_HOOKS_FILE)
+
+        self.assertEqual(payload, {})
+        backups = list(self.module.GLOBAL_HOOKS_FILE.parent.glob("hooks.json.*.bak"))
+        self.assertEqual(len(backups), 1)
+
+    def test_merge_hooks_json_normalizes_malformed_stop_section(self):
+        self.module.GLOBAL_HOOKS_FILE.parent.mkdir(parents=True, exist_ok=True)
+        self.module.GLOBAL_HOOKS_FILE.write_text(
+            '{"hooks": {"Stop": {"matcher": ".*"}}}',
+            encoding="utf-8",
+        )
+
+        self.module.merge_hooks_json()
+        payload = self.module.load_json(self.module.GLOBAL_HOOKS_FILE)
+
+        self.assertIsInstance(payload["hooks"]["Stop"], list)
+        self.assertEqual(len(payload["hooks"]["Stop"]), 1)
+        self.assertEqual(
+            payload["hooks"]["Stop"][0]["hooks"][0]["command"],
+            str(self.module.INSTALLED_HOOK),
+        )
+
     def test_ensure_codex_hooks_enabled_only_changes_features_section(self):
         self.module.CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
         self.module.CONFIG_FILE.write_text(
@@ -437,6 +464,19 @@ def test_ensure_codex_hooks_enabled_replaces_indented_key_without_duplication(se
         self.assertNotIn("codex_hooks = false", updated)
         self.assertIn("[features]\ncodex_hooks = true\napps = true\n", updated)
 
+    def test_install_runtime_hook_rewrites_shebang_to_current_python(self):
+        self.module.install_runtime_hook()
+
+        installed = self.module.INSTALLED_HOOK.read_text(encoding="utf-8")
+        self.assertTrue(installed.startswith(f"#!{self.module.sys.executable}\n"))
+
+    def test_ensure_nmem_cli_runtime_ready_exits_when_missing(self):
+        with mock.patch.object(self.module.importlib.util, "find_spec", return_value=None):
+            with self.assertRaises(SystemExit) as exc:
+                self.module.ensure_nmem_cli_runtime_ready()
+
+        self.assertIn("nmem_cli", str(exc.exception))
+
 
 class RefreshThreadTitleTests(unittest.TestCase):
     def setUp(self):
@@ -472,6 +512,37 @@ def test_refresh_thread_restores_original_messages_on_failure(self):
             [{"role": "user", "content": "old"}],
         )
 
+    def test_main_counts_generic_refresh_errors(self):
+        temp_dir = tempfile.TemporaryDirectory()
+        self.addCleanup(temp_dir.cleanup)
+        rollout_path = Path(temp_dir.name) / "rollout-1.jsonl"
+        rollout_path.write_text("placeholder", encoding="utf-8")
+
+        self.module.parse_codex_session_streaming = mock.Mock(
+            return_value={
+                "thread_id": "codex-thread-1",
+                "messages": [{"role": "user", "content": "real request"}],
+                "workspace": "/tmp/project",
+            }
+        )
+        self.module.cli = mock.Mock()
+
+        with mock.patch.object(self.module, "iter_codex_rollouts", return_value=[rollout_path]), \
+             mock.patch.object(
+                 self.module,
+                 "get_thread",
+                 return_value={"thread": {"title": f"{self.module.AGENTS_PREFIX}/tmp/project"}},
+             ), \
+             mock.patch.object(self.module, "refresh_thread", side_effect=RuntimeError("boom")), \
+             mock.patch("sys.argv", ["refresh_thread_titles.py"]), \
+             mock.patch("builtins.print") as print_mock:
+            result = self.module.main()
+
+        self.assertEqual(result, 0)
+        printed_lines = [" ".join(str(arg) for arg in call.args) for call in print_mock.call_args_list]
+        self.assertTrue(any("ERROR refresh codex-thread-1: boom" in line for line in printed_lines))
+        self.assertTrue(any('"errors": 1' in line for line in printed_lines))
+
 
 if __name__ == "__main__":
     unittest.main()