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

[tony]

Summary

Stacked on #1047 to keep lifecycle behavior separate from runtime config primitives.

• add on_project_start, on_project_restart, on_project_exit, and on_project_stop handling
• add tmuxp stop so stored stop hooks run before killing a session
• preserve existing session lifecycle metadata when appending/reusing sessions
• document lifecycle hooks and stop command with focused CLI, builder, util, and config tests

Verification

Ran before commit:

$ rm -rf docs/_build; uv run ruff check . --fix --show-fixes; uv run ruff format .; uv run mypy; uv run py.test --reruns 0 -vvv; just build-docs;

Result: ruff clean, format unchanged, mypy clean, pytest 841 passed, 2 skipped, docs built successfully with the repo's existing warning class.

Stack: depends on #1047. Importer fallback follow-up is stacked on this branch.

[codecov]

Codecov Report

❌ Patch coverage is 81.30081% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.47%. Comparing base (dab7070) to head (3e55df9).
⚠️ Report is 4 commits behind head on parity-runtime-config.

Files with missing lines	Patch %	Lines
src/tmuxp/cli/load.py	55.00%	6 Missing and 3 partials ⚠️
src/tmuxp/util.py	79.31%	4 Missing and 2 partials ⚠️
src/tmuxp/cli/stop.py	91.66%	3 Missing and 1 partial ⚠️
src/tmuxp/workspace/builder.py	84.21%	1 Missing and 2 partials ⚠️
src/tmuxp/workspace/loader.py	85.71%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@                    Coverage Diff                    @@
##           parity-runtime-config    #1048      +/-   ##
=========================================================
+ Coverage                  82.30%   82.47%   +0.16%     
=========================================================
  Files                         28       29       +1     
  Lines                       2594     2704     +110     
  Branches                     502      527      +25     
=========================================================
+ Hits                        2135     2230      +95     
- Misses                       328      336       +8     
- Partials                     131      138       +7     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

Found 1 issue:

1. The lifecycle-hooks documentation states "Hooks run through the shell and block tmuxp until they finish" — true for on_project_start, on_project_restart, and on_project_stop (which run via run_hook_commands/subprocess.run), but false for on_project_exit, which is registered as a tmux client-detached hook via run-shell and fires after tmuxp has already returned. The per-hook table on the same page is accurate; the prose should scope the blocking claim to the three subprocess-driven hooks.

tmuxp/docs/configuration/top-level.md

Lines 74 to 77 in 250222d

	Hooks run through the shell and block tmuxp until they finish. Hook failures are
	logged and do not stop the tmuxp command.

Implementation showing the non-blocking dispatch:

tmuxp/src/tmuxp/workspace/builder.py

Lines 551 to 557 in 250222d

	joined = f"cd {shlex.quote(start_dir)} && {joined}"
	guarded = f"if [ #{{session_attached}} -eq 0 ]; then {joined}; fi"
	self.session.set_hook(
	"client-detached",
	f"run-shell {shlex.quote(guarded)}",
	)

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}