fix(windows): SessionStart timeout, fast MCP check, terminal banner mirror

Raise SessionStart hook timeout to 60s. Verify MCP in-process when the
hook already runs in .venv. Mirror full banner to stderr on Windows and
write logs/sessionstart_last.json for diagnosis.

Co-authored-by: Cursor <[email protected]>

Author: sbhooley

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## 0.4.0 — 2026-05-18
 
+### Windows SessionStart visibility + timeout
+
+- **SessionStart timeout** raised to **60s** (was 20s; MCP subprocess preflight could exceed it on Windows ARM).
+- **In-process MCP verify** on SessionStart (avoids extra 30s subprocess when the hook already runs in `.venv`).
+- **Windows terminal mirror** — full `[AINL Cortex]` banner printed to stderr as `SessionStart:startup says:` (native Claude often hides hook UI).
+- **`logs/sessionstart_last.json`** — written every SessionStart for offline diagnosis.
+
 ### Windows hook fix + cross-OS self-heal
 
 - **`run_hook.cmd`** — fixed plugin root resolution (`scripts\.` → real root). Restores SessionStart `[AINL Cortex]` banner and stops `scripts\.\scripts\bootstrap_no_python.ps1` PostToolUse errors.

docs/INSTALL_WINDOWS.md

@@ -170,7 +170,7 @@ Usually **`git pull` + `.\setup.cmd -PythonOnly`** is enough. Re-clone only if t
 | Symptom | Fix |
 |---------|-----|
 | PostToolUse hook: `scripts\.\scripts\bootstrap_no_python.ps1` does not exist | Fixed in `run_hook.cmd` (use `git pull` or re-clone). Old batch logic set plugin root to `...\scripts\.` |
-| No `[AINL Cortex]` banner on SessionStart (macOS shows it, Windows does not) | Same bug — SessionStart never ran. After `git pull` (commit **f739b2d+**): `.\setup.cmd -PythonOnly`, quit Claude, `/reload-plugins`. Test: `.\scripts\verify_sessionstart.cmd` — stdout JSON should contain `[AINL Cortex]` |
+| No `[AINL Cortex]` banner on SessionStart (macOS shows it, Windows does not) | **(1)** Use a **new** session — `claude --resume` does **not** re-run SessionStart. Run `claude` fresh or `/clear`. **(2)** Hook may have timed out (fixed: 60s timeout + faster in-process MCP check). **(3)** After `git pull`: `.\setup.cmd -PythonOnly`, quit Claude, `/reload-plugins`. Check `logs\sessionstart_last.json` in the plugin folder. Test: `.\scripts\verify_sessionstart.cmd` |
 | `hooks/hooks.json` still says `python ... run_hook.py` | Run `.\setup.cmd -PythonOnly` — Windows should use `"${CLAUDE_PLUGIN_ROOT}/scripts/run_hook.cmd" startup` |
 | `Remove-Item`: directory in use | Quit Claude Code; stop `python`/`py` under `ainl-cortex`; retry |
 | `python` not found | Reinstall Python with PATH enabled; reopen terminal |

hooks/startup.py

@@ -54,6 +54,53 @@ def _plugin_root() -> Path:
     return Path(__file__).resolve().parent.parent
 
 
+def _write_sessionstart_probe(
+    root: Path,
+    ok: bool,
+    system_message: str,
+    *,
+    error: Optional[str] = None,
+) -> None:
+    """Persist last SessionStart result so operators can verify hooks on Windows."""
+    try:
+        log_dir = root / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "ok": ok,
+            "ts": time.time(),
+            "platform": sys.platform,
+            "plugin_root": str(root),
+            "preview": (system_message or "")[:1200],
+            "error": error,
+        }
+        (log_dir / "sessionstart_last.json").write_text(
+            json.dumps(payload, indent=2),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+
+
+def _mirror_sessionstart_banner(system_message: str) -> None:
+    """
+    macOS Claude Code prints hook systemMessage as ``SessionStart:startup says:``.
+    Windows native builds often omit that UI — mirror the banner to stderr.
+    """
+    if not (system_message or "").strip():
+        return
+    try:
+        from mcp_server.platform_paths import is_windows as _is_windows
+    except Exception:
+        _win = sys.platform == "win32"
+    else:
+        _win = _is_windows()
+    if not _win:
+        return
+    first = system_message.strip().split("\n", 1)[0]
+    print(f"SessionStart:startup says: {first}", file=sys.stderr, flush=True)
+    print(system_message, file=sys.stderr, flush=True)
+
+
 def _hook_cwd() -> Path:
     try:
         from shared.stdin import read_stdin_json
@@ -123,6 +170,31 @@ def _env_for_mcp_test(plugin_root: Path) -> dict:
     return env
 
 
+def verify_mcp_imports_inprocess(plugin_root: Path) -> Tuple[bool, str]:
+    """Fast path when SessionStart already runs inside the plugin venv."""
+    try:
+        if str(plugin_root) not in sys.path:
+            sys.path.insert(0, str(plugin_root))
+        from mcp_server.runtime_bootstrap import bootstrap_runtime
+        from mcp_server.import_compat import (
+            verify_bare_graph_store_import,
+            verify_bare_node_types_import,
+            verify_bare_retrieval_import,
+        )
+
+        bootstrap_runtime(plugin_root, heal_deps=True)
+        ok = (
+            verify_bare_node_types_import()
+            and verify_bare_graph_store_import()
+            and verify_bare_retrieval_import()
+        )
+        if ok:
+            return True, "in-process venv imports OK"
+        return False, "in-process import verify returned false"
+    except Exception as exc:
+        return False, f"in-process: {exc}"[:200]
+
+
 def verify_mcp_imports(plugin_root: Path) -> Tuple[bool, str]:
     """
     Resolves a Python that can import mcp (venv binary preferred; else system
@@ -503,7 +575,9 @@ def main():
         except OSError as e:
             db_s = f"error: {e}"
 
-        mcp_ok, mcp_detail = verify_mcp_imports(root)
+        mcp_ok, mcp_detail = verify_mcp_imports_inprocess(root)
+        if not mcp_ok:
+            mcp_ok, mcp_detail = verify_mcp_imports(root)
         _agent_install_banner = ""
         try:
             sys.path.insert(0, str(root))
@@ -518,7 +592,9 @@ def main():
                 _iok, _imsg = maybe_auto_install_at_session_start(root)
                 _auto_note = _imsg
                 if _iok:
-                    mcp_ok, mcp_detail = verify_mcp_imports(root)
+                    mcp_ok, mcp_detail = verify_mcp_imports_inprocess(root)
+                    if not mcp_ok:
+                        mcp_ok, mcp_detail = verify_mcp_imports(root)
             _agent_install_banner = build_agent_install_banner(
                 root,
                 mcp_ok=mcp_ok,
@@ -919,6 +995,9 @@ def main():
         except Exception:
             pass
 
+        _write_sessionstart_probe(root, True, system_message)
+        _mirror_sessionstart_banner(system_message)
+
         # Transcript: JSON stdout is what Claude documents; also mirror to stderr in raw terminals
         j = json.dumps(out)
         print(j, file=sys.stdout, flush=True)
@@ -931,10 +1010,13 @@ def main():
 
     except Exception as e:
         logger.error("SessionStart error: %s", e)
+        _write_sessionstart_probe(root, False, "", error=str(e))
+        err_msg = f"[AINL Graph Memory] SessionStart error (non-fatal): {e}"
+        _mirror_sessionstart_banner(err_msg)
         out = {
             "continue": True,
             "suppressOutput": False,
-            "systemMessage": f"[AINL Graph Memory] SessionStart error (non-fatal): {e}",
+            "systemMessage": err_msg,
             "hookSpecificOutput": {
                 "hookEventName": "SessionStart",
                 "additionalContext": str(e),

scripts/setup_install.py

@@ -140,7 +140,8 @@ def write_hooks_json(root: Path) -> None:
         "Stop": ["stop"],
     }
     timeouts = {
-        "startup": 20,
+        # SessionStart runs MCP preflight + banner; 20s was too low on Windows ARM.
+        "startup": 60,
         "user_prompt_submit": 5,
         "ainl_detection": 3,
         "user_prompt_expansion": 3,