cli/load(fix[hooks]): Run on_project_start only for new session builds

why: on_project_start had been triggered before dispatch, so it also ran for paths that reused an existing session. That made --here rebuilds and interactive append flows execute a hook documented as new-session-only.

what:
- Move on_project_start execution into the attached and detached new-session load paths
- Keep --here rebuilds inside tmux and append flows from invoking the hook
- Preserve the outside-tmux --here fallback behavior, which still creates a new session
- Add dispatch tests for attached, detached, append, and here routing
- Add an on_project_exit guard assertion and fix the loader doctest ellipsis
- Update the related load, comparison, and configuration docs to match current behavior

Author: tony

docs/cli/load.md

@@ -265,7 +265,7 @@ $ tmuxp load --here .
 When used, tmuxp builds the workspace panes inside the current window rather than spawning a new session.
 
 ```{note}
-`--here` sends shell commands (such as `cd` and `export` for environment variables) directly to the active pane via `send-keys`. The pane must be running a POSIX-compatible shell (bash, zsh, etc.). If the active pane is running a non-shell program (e.g., `vim`, `python`), those commands will be interpreted as input to that program.
+When `--here` needs to provision a directory, environment, or shell, tmuxp uses tmux primitives (`set-environment` and `respawn-pane`) instead of typing `cd` / `export` into the pane. If provisioning is needed, tmux will replace the active pane process before the workspace commands run, so long-running child processes in that pane can be terminated.
 ```
 
 ## Skipping shell_command_before

docs/comparison.md

@@ -74,17 +74,20 @@ teamocil parses YAML into `Session`/`Window`/`Pane` objects, each producing `Com
 
 | Hook | tmuxp | tmuxinator | teamocil |
 |---|---|---|---|
-| Every start invocation | `on_project_start` | `on_project_start` | (none) |
-| First start only | `before_script` | `on_project_first_start` | (none) |
+| Every start invocation | (none) | `on_project_start` | (none) |
+| New session creation only | `on_project_start` | `on_project_first_start` | (none) |
+| Before first script | `before_script` | (none) | (none) |
 | On reattach | `on_project_restart` + Plugin: `reattach()` | `on_project_restart` | (none) |
-| On exit/detach | `on_project_exit` (tmux `client-detached` hook) | `on_project_exit` | (none) |
+| On last client detach | `on_project_exit` (guarded `client-detached` hook) | `on_project_exit` | (none) |
 | On stop/kill | `on_project_stop` (via `tmuxp stop`) | `on_project_stop` | (none) |
 | Before workspace build | Plugin: `before_workspace_builder()` | (none) | (none) |
 | On window create | Plugin: `on_window_create()` | (none) | (none) |
 | After window done | Plugin: `after_window_finished()` | (none) | (none) |
 | Deprecated pre | (none) | `pre` (deprecated → `on_project_start`+`on_project_restart`; runs before session create) | (none) |
 | Deprecated post | (none) | `post` (deprecated → `on_project_stop`+`on_project_exit`; runs after attach on every invocation) | (none) |
 
+tmuxp's lifecycle hook names are intentionally close to tmuxinator's, but `on_project_start` is limited to new-session creation and `on_project_exit` is guarded so teardown only runs when the last client detaches.
+
 ### Window-Level
 
 | Key | tmuxp | tmuxinator | teamocil |

docs/configuration/top-level.md

@@ -61,7 +61,7 @@ windows:
 |------|-------------|
 | `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_exit` | When the last client detaches (tmux `client-detached` hook) |
 | `on_project_stop` | Before `tmuxp stop` kills the session |
 
 Each hook accepts a string (single command) or a list of strings (multiple commands run sequentially).
@@ -74,12 +74,12 @@ on_project_start:
 
 ```{note}
 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_start` only fires on new session creation (not on reattach, append, or `--here`).
 `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`. 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.
+`on_project_exit` uses tmux's `client-detached` hook, but tmuxp guards it with `#{session_attached} == 0` so the command only runs when the **last** client detaches. This avoids repeated teardown in multi-client sessions. Unlike tmuxinator's wrapper-process hook, tmuxp keeps the hook on the session itself for the session lifetime.
 ```
 
 ## Pane titles

src/tmuxp/cli/load.py

@@ -278,6 +278,7 @@ def _reattach(builder: WorkspaceBuilder, colors: Colors | None = None) -> None:
 def _load_attached(
     builder: WorkspaceBuilder,
     detached: bool,
+    pre_build_hook: t.Callable[[], None] | None = None,
     pre_attach_hook: t.Callable[[], None] | None = None,
 ) -> None:
     """
@@ -287,10 +288,15 @@ def _load_attached(
     ----------
     builder: :class:`workspace.builder.WorkspaceBuilder`
     detached : bool
+    pre_build_hook : callable, optional
+        called immediately before ``builder.build()`` for new-session load paths.
     pre_attach_hook : callable, optional
         called after build, before attach/switch_client; use to stop the spinner
         so its cleanup sequences don't appear inside the tmux pane.
     """
+    if pre_build_hook is not None:
+        pre_build_hook()
+
     builder.build()
     assert builder.session is not None
 
@@ -311,6 +317,7 @@ def _load_attached(
 def _load_detached(
     builder: WorkspaceBuilder,
     colors: Colors | None = None,
+    pre_build_hook: t.Callable[[], None] | None = None,
     pre_output_hook: t.Callable[[], None] | None = None,
 ) -> None:
     """
@@ -321,9 +328,14 @@ def _load_detached(
     builder: :class:`workspace.builder.WorkspaceBuilder`
     colors : Colors | None
         Optional Colors instance for styled output.
+    pre_build_hook : Callable | None
+        Called immediately before ``builder.build()`` for new-session load paths.
     pre_output_hook : Callable | None
         Called after build but before printing, e.g. to stop a spinner.
     """
+    if pre_build_hook is not None:
+        pre_build_hook()
+
     builder.build()
 
     assert builder.session is not None
@@ -400,6 +412,7 @@ def _dispatch_build(
     answer_yes: bool,
     cli_colors: Colors,
     here: bool = False,
+    pre_build_hook: t.Callable[[], None] | None = None,
     pre_attach_hook: t.Callable[[], None] | None = None,
     on_error_hook: t.Callable[[], None] | None = None,
     pre_prompt_hook: t.Callable[[], None] | None = None,
@@ -424,6 +437,8 @@ def _dispatch_build(
         Colors instance for styled output.
     here : bool
         Use current window for first workspace window.
+    pre_build_hook : callable, optional
+        Called before the build only for code paths that create a new session.
     pre_attach_hook : callable, optional
         Called before attach/switch_client (e.g. stop spinner).
     on_error_hook : callable, optional
@@ -465,7 +480,12 @@ def _dispatch_build(
     """
     try:
         if detached:
-            _load_detached(builder, cli_colors, pre_output_hook=pre_attach_hook)
+            _load_detached(
+                builder,
+                cli_colors,
+                pre_build_hook=pre_build_hook,
+                pre_output_hook=pre_attach_hook,
+            )
             return _setup_plugins(builder)
 
         if here:
@@ -479,21 +499,36 @@ def _dispatch_build(
                     cli_colors.warning("[Warning]")
                     + " --here requires running inside tmux; loading normally",
                 )
-                _load_attached(builder, detached, pre_attach_hook=pre_attach_hook)
+                _load_attached(
+                    builder,
+                    detached,
+                    pre_build_hook=pre_build_hook,
+                    pre_attach_hook=pre_attach_hook,
+                )
 
             return _setup_plugins(builder)
 
         if append:
             if "TMUX" in os.environ:  # tmuxp ran from inside tmux
                 _load_append_windows_to_current_session(builder)
             else:
-                _load_attached(builder, detached, pre_attach_hook=pre_attach_hook)
+                _load_attached(
+                    builder,
+                    detached,
+                    pre_build_hook=pre_build_hook,
+                    pre_attach_hook=pre_attach_hook,
+                )
 
             return _setup_plugins(builder)
 
         # append and answer_yes have no meaning if specified together
         if answer_yes:
-            _load_attached(builder, detached, pre_attach_hook=pre_attach_hook)
+            _load_attached(
+                builder,
+                detached,
+                pre_build_hook=pre_build_hook,
+                pre_attach_hook=pre_attach_hook,
+            )
             return _setup_plugins(builder)
 
         if "TMUX" in os.environ:  # tmuxp ran from inside tmux
@@ -507,13 +542,27 @@ def _dispatch_build(
             choice = prompt_choices(msg, choices=options, color_mode=cli_colors.mode)
 
             if choice == "y":
-                _load_attached(builder, detached, pre_attach_hook=pre_attach_hook)
+                _load_attached(
+                    builder,
+                    detached,
+                    pre_build_hook=pre_build_hook,
+                    pre_attach_hook=pre_attach_hook,
+                )
             elif choice == "a":
                 _load_append_windows_to_current_session(builder)
             else:
-                _load_detached(builder, cli_colors)
+                _load_detached(
+                    builder,
+                    cli_colors,
+                    pre_build_hook=pre_build_hook,
+                )
         else:
-            _load_attached(builder, detached, pre_attach_hook=pre_attach_hook)
+            _load_attached(
+                builder,
+                detached,
+                pre_build_hook=pre_build_hook,
+                pre_attach_hook=pre_attach_hook,
+            )
 
     except exc.TmuxpException as e:
         if on_error_hook is not None:
@@ -811,8 +860,9 @@ def _cleanup_debug() -> None:
         _cleanup_debug()
         return None
 
-    # Run on_project_start hook — fires before new session build
-    if "on_project_start" in expanded_workspace:
+    def _run_on_project_start() -> None:
+        if "on_project_start" not in expanded_workspace:
+            return
         _hook_cwd = expanded_workspace.get("start_directory")
         util.run_hook_commands(
             expanded_workspace["on_project_start"],
@@ -828,6 +878,7 @@ def _cleanup_debug() -> None:
             answer_yes,
             cli_colors,
             here=here,
+            pre_build_hook=_run_on_project_start,
         )
         if result is not None:
             summary = ""
@@ -905,6 +956,7 @@ def _emit_success() -> None:
             answer_yes,
             cli_colors,
             here=here,
+            pre_build_hook=_run_on_project_start,
             pre_attach_hook=_emit_success,
             on_error_hook=spinner.stop,
             pre_prompt_hook=spinner.stop,

src/tmuxp/workspace/loader.py

@@ -41,7 +41,7 @@ def _validate_template_values(context: dict[str, str]) -> None:
     --------
     >>> _validate_template_values({"key": "simple"})
 
-    >>> _validate_template_values({"key": "foo: bar"})
+    >>> _validate_template_values({"key": "foo: bar"})  # doctest: +ELLIPSIS
     Traceback (most recent call last):
         ...
     ValueError: --set value for 'key' contains YAML-unsafe characters ...