fix: preserve tmux session compatibility

Author: bma-d

skills/bmad-story-automator/data/crash-recovery.md

@@ -36,7 +36,7 @@ truth from story files and `sprint-status.yaml` before retrying.
 project_slug=$("$scripts" tmux-wrapper project-slug)
 PROJECT_HASH=$("$scripts" tmux-wrapper project-hash)
 timestamp=$(date +%y%m%d-%H%M%S)
-session_name="sa-${project_slug}-${PROJECT_HASH}-${timestamp}-e{epic}-s{story_suffix}-{step}-r2"
+session_name="sa-${project_slug}-${timestamp}-e{epic}-s{story_suffix}-{step}-r2"
 
 # Clear stale state (project-scoped v2.0)
 rm -f "/tmp/.sa-${PROJECT_HASH}-session-${session_name}-state.json"

skills/bmad-story-automator/data/tmux-commands.md

@@ -6,19 +6,19 @@
 
 ## Session Names
 
-**Pattern (v3.1 - HASH-SCOPED MULTI-PROJECT):** `sa-{project_slug}-{project_hash}-{YYMMDD}-{HHMMSS}-e{epic}-s{story}-{step}`
+**Pattern:** `sa-{project_slug}-{YYMMDD}-{HHMMSS}-e{epic}-s{story}-{step}`
 
 **Examples:**
-- `sa-myproj-a1b2c3d4-260114-223045-e6-s64-dev` (Project "myproject", Epic 6, Story 6.4, dev step)
-- `sa-webapp-e5f6a7b8-260114-223512-e6-s64-review-r1` (Project "webapp", review cycle 1)
+- `sa-myproj-260114-223045-e6-s64-dev` (Project "myproject", Epic 6, Story 6.4, dev step)
+- `sa-webapp-260114-223512-e6-s64-review-r1` (Project "webapp", review cycle 1)
 
 ### Project Slug for Multi-Project Support
 
-**Why project slug + hash (v3.1):**
+**Why project slug + artifact hash (v3.1):**
 - **Isolates sessions per project** - List only current project's sessions
 - **Prevents cross-project interference** - Won't kill another project's sessions
 - **Enables parallel orchestration** - Run story-automator on multiple projects simultaneously
-- **Avoids same-folder-name collisions** - Worktrees with the same basename still get different hashes
+- **Avoids same-folder-name collisions** - Runtime artifacts are scoped by project hash while public session names keep their legacy shape
 
 **Generate project slug:**
 ```bash
@@ -27,7 +27,7 @@ project_slug=$("$script" tmux-wrapper project-slug)
 project_hash=$("$script" tmux-wrapper project-hash)
 ```
 
-**Example:** Project at `/home/user/my-awesome-project` → `project_slug="myawesom"` plus a stable project hash.
+**Example:** Project at `/home/user/my-awesome-project` → `project_slug="myawesom"` plus a stable project hash for runtime artifacts.
 
 **Why timestamps with seconds (v2.1):**
 - Prevents collisions when multiple sessions spawn in same minute
@@ -66,7 +66,7 @@ session_suffix=$(echo "{story_id}" | tr '.' '-')
 ```
 
 **WRONG:** `sa-epic6-s6.2-review-1` ← Will fail with "can't find pane" error
-**RIGHT:** `sa-myproj-a1b2c3d4-260114-223045-e6-s6-2-review-r1` ← Works correctly
+**RIGHT:** `sa-myproj-260114-223045-e6-s6-2-review-r1` ← Works correctly
 
 ---
 

skills/bmad-story-automator/src/story_automator/core/tmux_runtime.py

@@ -72,7 +72,7 @@ def resolve_command_shell() -> str:
 def generate_session_name(step: str, epic: str, story_id: str, cycle: str = "") -> str:
     stamp = time.strftime("%y%m%d-%H%M%S", time.localtime())
     suffix = story_id.replace(".", "-")
-    name = f"sa-{project_slug()}-{project_hash()}-{stamp}-e{epic}-s{suffix}-{step}"
+    name = f"sa-{project_slug()}-{stamp}-e{epic}-s{suffix}-{step}"
     if cycle:
         name += f"-r{cycle}"
     return name
@@ -141,11 +141,21 @@ def tmux_list_sessions(project_only: bool) -> tuple[list[str], int]:
         return ([], code)
     sessions = [line.strip() for line in output.splitlines() if line.strip().startswith("sa-")]
     if project_only:
-        prefix = f"sa-{project_slug()}-{project_hash()}-"
-        sessions = [line for line in sessions if line.startswith(prefix)]
+        sessions = [line for line in sessions if _matches_current_project_session(line)]
     return (sessions, 0)
 
 
+def _matches_current_project_session(session: str) -> bool:
+    hashed_prefix = f"sa-{project_slug()}-{project_hash()}-"
+    if session.startswith(hashed_prefix):
+        return True
+    legacy_prefix = f"sa-{project_slug()}-"
+    if not session.startswith(legacy_prefix):
+        return False
+    paths = session_paths(session)
+    return any(path.exists() for path in (paths.state, paths.command, paths.runner, paths.output))
+
+
 def monitor_session_state_issue(session: str, project_root: str) -> object | None:
     return serialized_session_state_issue(session_paths(session, project_root).state)
 

tests/test_cli_contracts.py

@@ -202,7 +202,8 @@ def test_name_cycle_uses_cycle_value_not_flag_token(self) -> None:
 
         self.assertEqual(code, 0)
         session = stdout.getvalue().strip()
-        self.assertIn(f"sa-{project_slug(str(self.root))}-{project_hash(str(self.root))}-", session)
+        self.assertIn(f"sa-{project_slug(str(self.root))}-", session)
+        self.assertNotIn(f"sa-{project_slug(str(self.root))}-{project_hash(str(self.root))}-", session)
         self.assertTrue(session.endswith("-review-r2"), session)
         self.assertNotIn("-r--cycle", session)
 
@@ -239,6 +240,27 @@ def test_project_only_session_filter_uses_slug_and_hash(self) -> None:
         self.assertEqual(code, 0)
         self.assertEqual(sessions, [own])
 
+    def test_project_only_session_filter_keeps_current_project_legacy_sessions_with_artifacts(self) -> None:
+        own = f"sa-{project_slug(str(self.root))}-{project_hash(str(self.root))}-260521-101010-e5-s5-3-review"
+        legacy_own = f"sa-{project_slug(str(self.root))}-260521-101012-e5-s5-3-review"
+        legacy_other = f"sa-{project_slug(str(self.root))}-260521-101013-e5-s5-4-review"
+        legacy_state = Path(tempfile.gettempdir()) / f".sa-{project_hash(str(self.root))}-session-{legacy_own}-state.json"
+        legacy_state.write_text("{}", encoding="utf-8")
+        output = "\n".join([own, legacy_own, legacy_other])
+
+        try:
+            with (
+                mock.patch.dict(os.environ, {"PROJECT_ROOT": str(self.root)}),
+                mock.patch("story_automator.core.tmux_runtime.command_exists", return_value=True),
+                mock.patch("story_automator.core.tmux_runtime.run_cmd", return_value=(output, 0)),
+            ):
+                sessions, code = tmux_list_sessions(project_only=True)
+        finally:
+            legacy_state.unlink(missing_ok=True)
+
+        self.assertEqual(code, 0)
+        self.assertEqual(sessions, [own, legacy_own])
+
     def test_kill_all_defaults_to_all_automator_sessions(self) -> None:
         with (
             mock.patch("story_automator.commands.tmux.tmux_list_sessions", return_value=(["sa-one"], 0)) as list_sessions,
@@ -273,11 +295,12 @@ def test_kill_all_all_projects_opt_in(self) -> None:
         self.assertEqual(code, 0)
         list_sessions.assert_called_once_with(False)
 
-    def test_generate_session_name_includes_project_hash(self) -> None:
+    def test_generate_session_name_preserves_legacy_public_shape(self) -> None:
         with mock.patch.dict(os.environ, {"PROJECT_ROOT": str(self.root)}):
             session = generate_session_name("dev", "2", "2.4")
 
-        self.assertIn(f"sa-{project_slug(str(self.root))}-{project_hash(str(self.root))}-", session)
+        self.assertIn(f"sa-{project_slug(str(self.root))}-", session)
+        self.assertNotIn(f"sa-{project_slug(str(self.root))}-{project_hash(str(self.root))}-", session)
         self.assertTrue(session.endswith("-e2-s2-4-dev"), session)