Workspace(feat[lifecycle]): Add project hooks and stop command

why: Add lifecycle cleanup and restart hooks as a separate layer above runtime config primitives.
what:
- Run start and restart hooks from load while preserving append behavior
- Store exit and stop hook metadata on newly created tmux sessions
- Add tmuxp stop with on_project_stop execution and focused CLI/docs coverage

Author: tony

conftest.py

@@ -114,6 +114,8 @@ def socket_name(request: pytest.FixtureRequest) -> str:
 
 # Modules that actually need tmux fixtures in their doctests
 DOCTEST_NEEDS_TMUX = {
+    "tmuxp.cli.stop",
+    "tmuxp.util",
     "tmuxp.workspace.builder",
 }
 

docs/cli/index.md

@@ -25,6 +25,12 @@ Interactive Python shell with tmux context.
 Export running sessions to config files.
 :::
 
+:::{grid-item-card} tmuxp stop
+:link: stop
+:link-type: doc
+Stop running sessions with cleanup hooks.
+:::
+
 :::{grid-item-card} tmuxp convert
 :link: convert
 :link-type: doc
@@ -53,6 +59,7 @@ load
 shell
 ls
 search
+stop
 ```
 
 ```{toctree}

docs/cli/stop.md

@@ -0,0 +1,38 @@
+(cli-stop)=
+
+(cli-stop-reference)=
+
+# tmuxp stop
+
+Stop (kill) a running tmux session. If the session was created from a workspace
+with `on_project_stop`, that hook runs before the session is killed.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: stop
+```
+
+## Basic Usage
+
+Stop a session by name:
+
+```console
+$ tmuxp stop mysession
+```
+
+Stop the currently attached session:
+
+```console
+$ tmuxp stop
+```
+
+Use a custom socket:
+
+```console
+$ tmuxp stop -L mysocket mysession
+```

docs/configuration/examples.md

@@ -797,6 +797,19 @@ The `synchronize` window key provides a shorthand for enabling
 ```
 ````
 
+## Lifecycle Hooks
+
+Run shell commands at different stages of the session lifecycle:
+
+````{tab} YAML
+```{literalinclude} ../../examples/lifecycle-hooks.yaml
+:language: yaml
+
+```
+````
+
+See {ref}`top-level` for full hook documentation.
+
 ## Pane Titles
 
 Pane title keys turn on tmux pane border titles and label individual panes:

docs/configuration/top-level.md

@@ -41,6 +41,40 @@ Notes:
 
   Above: Use `tmux` directly to attach _banana_.
 
+## Lifecycle Hooks
+
+Workspace configs support four lifecycle hooks:
+
+```yaml
+session_name: myproject
+on_project_start: notify-send "Starting myproject"
+on_project_restart: notify-send "Reattaching to myproject"
+on_project_exit: notify-send "Detached from myproject"
+on_project_stop: notify-send "Stopping myproject"
+windows:
+  - window_name: main
+    panes:
+      -
+```
+
+| Hook | When it runs |
+|------|-------------|
+| `on_project_start` | Before a new session is built. |
+| `on_project_restart` | Before reattaching to an existing session. |
+| `on_project_exit` | When the last client detaches. |
+| `on_project_stop` | Before `tmuxp stop` kills the session. |
+
+Each hook accepts a string command or a list of command strings:
+
+```yaml
+on_project_start:
+  - notify-send "Starting"
+  - ./setup.sh
+```
+
+Hooks run through the shell and block tmuxp until they finish. Hook failures are
+logged and do not stop the tmuxp command.
+
 ## Pane Titles
 
 Enable pane border titles to display labels on each pane:

docs/internals/api/cli/index.md

@@ -19,6 +19,7 @@ ls
 progress
 search
 shell
+stop
 utils
 ```
 

docs/internals/api/cli/stop.md

@@ -0,0 +1,8 @@
+# tmuxp stop - `tmuxp.cli.stop`
+
+```{eval-rst}
+.. automodule:: tmuxp.cli.stop
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

examples/lifecycle-hooks.yaml

@@ -0,0 +1,9 @@
+session_name: lifecycle hooks
+on_project_start: echo "project starting"
+on_project_restart: echo "project restarting"
+on_project_exit: echo "project exiting"
+on_project_stop: echo "project stopping"
+windows:
+  - window_name: main
+    panes:
+      -

src/tmuxp/cli/__init__.py

@@ -57,6 +57,12 @@
     command_shell,
     create_shell_subparser,
 )
+from .stop import (
+    STOP_DESCRIPTION,
+    CLIStopNamespace,
+    command_stop,
+    create_stop_subparser,
+)
 from .utils import tmuxp_echo
 
 logger = logging.getLogger(__name__)
@@ -130,6 +136,13 @@
                 "tmuxp edit myproject",
             ],
         ),
+        (
+            "stop",
+            [
+                "tmuxp stop mysession",
+                "tmuxp stop -L mysocket mysession",
+            ],
+        ),
         (
             "debug-info",
             [
@@ -155,6 +168,7 @@
         "import",
         "search",
         "shell",
+        "stop",
         "debug-info",
     ]
     CLIImportSubparserName: TypeAlias = t.Literal["teamocil", "tmuxinator"]
@@ -262,6 +276,14 @@ def create_parser() -> argparse.ArgumentParser:
     )
     create_freeze_subparser(freeze_parser)
 
+    stop_parser = subparsers.add_parser(
+        "stop",
+        help="stop (kill) a tmux session",
+        description=STOP_DESCRIPTION,
+        formatter_class=formatter_class,
+    )
+    create_stop_subparser(stop_parser)
+
     return parser
 
 
@@ -353,6 +375,11 @@ def cli(_args: list[str] | None = None) -> None:
             args=CLIFreezeNamespace(**vars(args)),
             parser=parser,
         )
+    elif args.subparser_name == "stop":
+        command_stop(
+            args=CLIStopNamespace(**vars(args)),
+            parser=parser,
+        )
     elif args.subparser_name == "ls":
         command_ls(
             args=CLILsNamespace(**vars(args)),