fix(cli[load],docs): Tighten lifecycle hook semantics and parity claims

tony · tony · commit 54afda72c4e5 · 2026-03-29T03:51:38.000-05:00
- on_project_start: now only fires on new session creation (not reattach)
- on_project_restart: now only fires on confirmed interactive reattach
  (not detached loads of existing sessions)
- Docs: remove "matches tmuxinator" claim for on_project_exit; document
  it as tmuxp-specific behavior that fires on every detach event
- CHANGES: correct hook descriptions to match new semantics
- Update test to assert detached loads do NOT trigger restart hook
diff --git a/CHANGES b/CHANGES
@@ -69,12 +69,11 @@ $ tmuxp delete old-project
 ```
 
 ### Lifecycle hooks (#1025)
-Workspace configs now support four lifecycle hooks, matching tmuxinator's
-hook system:
+Workspace configs now support four lifecycle hooks inspired by tmuxinator:
 
-- `on_project_start` — runs before session build (every invocation)
-- `on_project_restart` — runs when reattaching to an existing session
-- `on_project_exit` — runs on client detach (via tmux `client-detached` hook)
+- `on_project_start` — runs before session build (new session creation only)
+- `on_project_restart` — runs when reattaching to an existing session (confirmed attach only)
+- `on_project_exit` — runs on client detach (via tmux `client-detached` hook; fires on every detach event)
 - `on_project_stop` — runs before `tmuxp stop` kills the session
 
 ### Config templating (#1025)
diff --git a/docs/configuration/top-level.md b/docs/configuration/top-level.md
@@ -59,8 +59,8 @@ windows:
 
 | Hook | When it runs |
 |------|-------------|
-| `on_project_start` | Before session build, every `tmuxp load` invocation |
-| `on_project_restart` | When reattaching to an existing session |
+| `on_project_start` | Before session build (new session creation only) |
+| `on_project_restart` | When reattaching to an existing session (confirmed attach only) |
 | `on_project_exit` | On client detach (tmux `client-detached` hook) |
 | `on_project_stop` | Before `tmuxp stop` kills the session |
 
@@ -73,11 +73,13 @@ on_project_start:
 ```
 
 ```{note}
-These hooks correspond to tmuxinator's `on_project_start`, `on_project_restart`, `on_project_exit`, and `on_project_stop` keys.
+These hooks are inspired by tmuxinator's lifecycle hooks but have tmuxp-specific semantics.
+`on_project_start` only fires on new session creation (not on reattach).
+`on_project_restart` only fires when you confirm reattaching to an existing session.
 ```
 
 ```{note}
-`on_project_exit` uses tmux's `client-detached` hook, which fires on **any** client detach — including terminal close, SSH disconnect, or manual `tmux detach`. This matches tmuxinator's behavior.
+`on_project_exit` uses tmux's `client-detached` hook, which fires on **any** client detach — including terminal close, SSH disconnect, or manual `tmux detach`. Note: unlike tmuxinator (which fires `on_project_exit` once when the wrapper script exits), tmuxp's hook fires on every detach event for the lifetime of the session.
 ```
 
 ## Pane titles
diff --git a/src/tmuxp/cli/load.py b/src/tmuxp/cli/load.py
@@ -799,21 +799,14 @@ def _cleanup_debug() -> None:
                 color_mode=cli_colors.mode,
             )
         )
-        if _confirmed or detached:
-            if "on_project_start" in expanded_workspace:
-                _hook_cwd = expanded_workspace.get("start_directory")
-                util.run_hook_commands(
-                    expanded_workspace["on_project_start"],
-                    cwd=_hook_cwd,
-                )
-            # Run on_project_restart hook — fires when reattaching
+        # Run on_project_restart hook — only when actually reattaching
+        if _confirmed:
             if "on_project_restart" in expanded_workspace:
                 _hook_cwd = expanded_workspace.get("start_directory")
                 util.run_hook_commands(
                     expanded_workspace["on_project_restart"],
                     cwd=_hook_cwd,
                 )
-        if _confirmed:
             _reattach(builder, cli_colors)
         _cleanup_debug()
         return None
diff --git a/tests/cli/test_load.py b/tests/cli/test_load.py
@@ -1203,13 +1203,14 @@ def test_load_on_project_restart_runs_hook(
     assert session is not None
     assert not marker.exists()
 
-    # Second load triggers on_project_restart (session already exists)
+    # Second detached load does NOT trigger on_project_restart
+    # (restart hook only fires on confirmed interactive reattach)
     load_workspace(
         workspace_file,
         socket_name=server.socket_name,
         detached=True,
     )
-    assert marker.exists()
+    assert not marker.exists()
 
     session.kill()
 
