Make worker startup timing configurable and harden marker correlation

src/maniple_mcp/config.py

@@ -71,6 +71,14 @@ class IssueTrackerConfig:
     override: IssueTrackerName | None = None
 
 
+@dataclass
+class StartupConfig:
+    """Startup timing controls for worker boot and marker correlation."""
+
+    agent_ready_timeout_seconds: int = 30
+    marker_poll_timeout_seconds: int = 30
+
+
 @dataclass
 class ClaudeTeamConfig:
     """Top-level configuration container for claude-team."""
@@ -81,6 +89,7 @@ class ClaudeTeamConfig:
     terminal: TerminalConfig = field(default_factory=TerminalConfig)
     events: EventsConfig = field(default_factory=EventsConfig)
     issue_tracker: IssueTrackerConfig = field(default_factory=IssueTrackerConfig)
+    startup: StartupConfig = field(default_factory=StartupConfig)
 
 
 def default_config() -> ClaudeTeamConfig:
@@ -159,7 +168,15 @@ def _parse_config(data: dict) -> ClaudeTeamConfig:
     # Validate expected top-level keys before parsing sections.
     _validate_keys(
         data,
-        {"version", "commands", "defaults", "terminal", "events", "issue_tracker"},
+        {
+            "version",
+            "commands",
+            "defaults",
+            "terminal",
+            "events",
+            "issue_tracker",
+            "startup",
+        },
         "config",
     )
     version = _read_version(data.get("version"))
@@ -168,13 +185,15 @@ def _parse_config(data: dict) -> ClaudeTeamConfig:
     terminal = _parse_terminal(data.get("terminal"))
     events = _parse_events(data.get("events"))
     issue_tracker = _parse_issue_tracker(data.get("issue_tracker"))
+    startup = _parse_startup(data.get("startup"))
     return ClaudeTeamConfig(
         version=version,
         commands=commands,
         defaults=defaults,
         terminal=terminal,
         events=events,
         issue_tracker=issue_tracker,
+        startup=startup,
     )
 
 
@@ -291,6 +310,30 @@ def _parse_issue_tracker(value: object) -> IssueTrackerConfig:
     )
 
 
+def _parse_startup(value: object) -> StartupConfig:
+    # Parse startup timing settings.
+    data = _ensure_dict(value, "startup")
+    _validate_keys(
+        data,
+        {"agent_ready_timeout_seconds", "marker_poll_timeout_seconds"},
+        "startup",
+    )
+    return StartupConfig(
+        agent_ready_timeout_seconds=_optional_int(
+            data.get("agent_ready_timeout_seconds"),
+            "startup.agent_ready_timeout_seconds",
+            StartupConfig.agent_ready_timeout_seconds,
+            min_value=1,
+        ),
+        marker_poll_timeout_seconds=_optional_int(
+            data.get("marker_poll_timeout_seconds"),
+            "startup.marker_poll_timeout_seconds",
+            StartupConfig.marker_poll_timeout_seconds,
+            min_value=1,
+        ),
+    )
+
+
 def _ensure_dict(value: object, path: str) -> dict:
     # Ensure sections are JSON objects, defaulting to empty dicts.
     if value is None:

src/maniple_mcp/config_cli.py

@@ -167,6 +167,26 @@ def _apply_env_overrides(data: dict, env: Mapping[str, str]) -> None:
         if parsed is not None:
             data["events"]["stale_threshold_minutes"] = parsed
 
+    agent_ready_timeout_override = get_env_with_fallback(
+        "MANIPLE_AGENT_READY_TIMEOUT_SECONDS",
+        "CLAUDE_TEAM_AGENT_READY_TIMEOUT_SECONDS",
+        env=env,
+    )
+    if agent_ready_timeout_override:
+        parsed = _parse_int_override(agent_ready_timeout_override)
+        if parsed is not None:
+            data["startup"]["agent_ready_timeout_seconds"] = parsed
+
+    marker_poll_timeout_override = get_env_with_fallback(
+        "MANIPLE_MARKER_POLL_TIMEOUT_SECONDS",
+        "CLAUDE_TEAM_MARKER_POLL_TIMEOUT_SECONDS",
+        env=env,
+    )
+    if marker_poll_timeout_override:
+        parsed = _parse_int_override(marker_poll_timeout_override)
+        if parsed is not None:
+            data["startup"]["marker_poll_timeout_seconds"] = parsed
+
 
 def _parse_int_override(raw_value: str) -> int | None:
     # Parse env overrides as integers; invalid values are ignored.
@@ -289,6 +309,8 @@ def _set_nested_value(data: dict, key: str, value: object) -> None:
     "events.max_size_mb": _parse_int,
     "events.recent_hours": _parse_int,
     "events.stale_threshold_minutes": _parse_int,
+    "startup.agent_ready_timeout_seconds": _parse_int,
+    "startup.marker_poll_timeout_seconds": _parse_int,
     "issue_tracker.override": lambda value, field: _parse_optional_literal(
         value,
         field,

src/maniple_mcp/session_state.py

@@ -285,9 +285,9 @@ def generate_marker_message(
 
     return (
         f"{marker}\n\n"
-        "The above is a marker that assists Claude Teams in locating your session - "
-        "respond with ONLY the word 'Identified!' and nothing further. "
-        "Please forgive the interruption."
+        "SYSTEM HANDSHAKE: The marker block above is generated by the worker "
+        "orchestrator for session correlation. Respond with ONLY the single word "
+        "'Identified!' (exact spelling, no punctuation, no extra text), then stop."
     )
 
 

src/maniple_mcp/terminal_backends/tmux.py

@@ -508,10 +508,21 @@ async def start_agent_in_session(
             timeout_seconds=agent_ready_timeout,
         )
         if not agent_ready:
+            # Include recent pane output to make startup failures actionable.
+            excerpt = ""
+            try:
+                pane_text = await self.read_screen_text(handle)
+                tail_lines = pane_text.splitlines()[-25:]
+                if tail_lines:
+                    excerpt = "\nRecent pane output:\n" + "\n".join(tail_lines)
+            except Exception:
+                # Best-effort diagnostics only.
+                excerpt = ""
             raise RuntimeError(
                 f"{cli.engine_id} failed to start in {project_path} within "
                 f"{agent_ready_timeout}s. Check that '{cli.command()}' is "
                 "available and authentication is configured."
+                f"{excerpt}"
             )
 
     async def start_claude_in_session(

src/maniple_mcp/tools/spawn_workers.py

@@ -219,6 +219,7 @@ async def spawn_workers(
         from ..session_state import (
             await_codex_marker_in_jsonl,
             await_marker_in_jsonl,
+            find_jsonl_by_tmux_id,
             generate_marker_message,
         )
 
@@ -232,6 +233,7 @@ async def spawn_workers(
             logger.warning("Invalid config file; using defaults: %s", exc)
             config = default_config()
         defaults = config.defaults
+        startup = config.startup
 
         # Resolve layout from config if not explicitly provided
         if layout is None:
@@ -683,6 +685,7 @@ async def start_agent_for_worker(index: int) -> None:
                     dangerously_skip_permissions=skip_permissions,
                     env=env,
                     stop_hook_marker_id=stop_hook_marker_id,
+                    agent_ready_timeout=float(startup.agent_ready_timeout_seconds),
                 )
 
             await asyncio.gather(*[start_agent_for_worker(i) for i in range(worker_count)])
@@ -735,21 +738,45 @@ async def start_agent_for_worker(index: int) -> None:
                     claude_session_id = await await_marker_in_jsonl(
                         managed.project_path,
                         managed.session_id,
-                        timeout=30.0,
+                        timeout=float(startup.marker_poll_timeout_seconds),
                         poll_interval=0.1,
                     )
                     if claude_session_id:
                         managed.claude_session_id = claude_session_id
                     else:
-                        logger.warning(
-                            f"Marker polling timed out for {managed.session_id}, "
-                            "JSONL correlation unavailable"
-                        )
+                        # Fallback: recover via tmux pane marker search across project dirs.
+                        recovered = False
+                        if managed.terminal_session.backend_id == "tmux":
+                            tmux_match = find_jsonl_by_tmux_id(
+                                managed.terminal_session.native_id,
+                                max_age_seconds=max(
+                                    startup.marker_poll_timeout_seconds * 4,
+                                    300,
+                                ),
+                            )
+                            if (
+                                tmux_match
+                                and tmux_match.internal_session_id == managed.session_id
+                            ):
+                                managed.claude_session_id = tmux_match.jsonl_path.stem
+                                recovered = True
+                                logger.info(
+                                    "Recovered JSONL correlation for %s via tmux pane %s: %s",
+                                    managed.session_id,
+                                    managed.terminal_session.native_id,
+                                    tmux_match.jsonl_path,
+                                )
+
+                        if not recovered:
+                            logger.warning(
+                                "Marker polling timed out for %s, JSONL correlation unavailable",
+                                managed.session_id,
+                            )
                 elif managed.agent_type == "codex":
                     # Poll for Codex marker and cache the JSONL path
                     codex_match = await await_codex_marker_in_jsonl(
                         managed.session_id,
-                        timeout=30.0,
+                        timeout=float(startup.marker_poll_timeout_seconds),
                         poll_interval=0.5,
                     )
                     if codex_match:

tests/test_config.py

@@ -12,6 +12,7 @@
     DefaultsConfig,
     EventsConfig,
     IssueTrackerConfig,
+    StartupConfig,
     TerminalConfig,
     default_config,
     load_config,
@@ -63,6 +64,12 @@ def test_default_issue_tracker(self):
         config = default_config()
         assert config.issue_tracker.override is None
 
+    def test_default_startup(self):
+        """Default startup timing values."""
+        config = default_config()
+        assert config.startup.agent_ready_timeout_seconds == 30
+        assert config.startup.marker_poll_timeout_seconds == 30
+
 
 class TestSaveConfig:
     """Tests for save_config function."""
@@ -104,6 +111,10 @@ def test_saves_all_fields(self, tmp_path: Path):
             terminal=TerminalConfig(backend="tmux"),
             events=EventsConfig(max_size_mb=5, recent_hours=48, stale_threshold_minutes=15),
             issue_tracker=IssueTrackerConfig(override="beads"),
+            startup=StartupConfig(
+                agent_ready_timeout_seconds=60,
+                marker_poll_timeout_seconds=45,
+            ),
         )
         save_config(config, config_path)
         data = json.loads(config_path.read_text())
@@ -119,6 +130,8 @@ def test_saves_all_fields(self, tmp_path: Path):
         assert data["events"]["recent_hours"] == 48
         assert data["events"]["stale_threshold_minutes"] == 15
         assert data["issue_tracker"]["override"] == "beads"
+        assert data["startup"]["agent_ready_timeout_seconds"] == 60
+        assert data["startup"]["marker_poll_timeout_seconds"] == 45
 
     def test_json_is_formatted(self, tmp_path: Path):
         """Saved JSON is indented for readability."""
@@ -210,6 +223,10 @@ def test_roundtrip_preserves_values(self, tmp_path: Path):
             terminal=TerminalConfig(backend="tmux"),
             events=EventsConfig(max_size_mb=2, recent_hours=12, stale_threshold_minutes=30),
             issue_tracker=IssueTrackerConfig(override="beads"),
+            startup=StartupConfig(
+                agent_ready_timeout_seconds=75,
+                marker_poll_timeout_seconds=50,
+            ),
         )
         save_config(original, config_path)
         loaded = load_config(config_path)
@@ -225,6 +242,14 @@ def test_roundtrip_preserves_values(self, tmp_path: Path):
         assert loaded.events.recent_hours == original.events.recent_hours
         assert loaded.events.stale_threshold_minutes == original.events.stale_threshold_minutes
         assert loaded.issue_tracker.override == original.issue_tracker.override
+        assert (
+            loaded.startup.agent_ready_timeout_seconds
+            == original.startup.agent_ready_timeout_seconds
+        )
+        assert (
+            loaded.startup.marker_poll_timeout_seconds
+            == original.startup.marker_poll_timeout_seconds
+        )
 
 
 class TestJsonValidationErrors:
@@ -678,6 +703,46 @@ def test_issue_tracker_override_pebbles(self, tmp_path: Path):
         config = load_config(config_path)
         assert config.issue_tracker.override == "pebbles"
 
+    def test_startup_values_load(self, tmp_path: Path):
+        """startup values are parsed when present."""
+        config_path = tmp_path / "config.json"
+        config_path.write_text(json.dumps({
+            "version": 1,
+            "startup": {
+                "agent_ready_timeout_seconds": 75,
+                "marker_poll_timeout_seconds": 55,
+            },
+        }))
+        config = load_config(config_path)
+        assert config.startup.agent_ready_timeout_seconds == 75
+        assert config.startup.marker_poll_timeout_seconds == 55
+
+    def test_startup_timeout_must_be_integer(self, tmp_path: Path):
+        """startup timeout fields must be integers."""
+        config_path = tmp_path / "config.json"
+        config_path.write_text(json.dumps({
+            "version": 1,
+            "startup": {"agent_ready_timeout_seconds": "slow"},
+        }))
+        with pytest.raises(
+            ConfigError,
+            match="startup.agent_ready_timeout_seconds must be an integer",
+        ):
+            load_config(config_path)
+
+    def test_startup_timeout_must_be_positive(self, tmp_path: Path):
+        """startup timeout fields must be at least 1."""
+        config_path = tmp_path / "config.json"
+        config_path.write_text(json.dumps({
+            "version": 1,
+            "startup": {"marker_poll_timeout_seconds": 0},
+        }))
+        with pytest.raises(
+            ConfigError,
+            match="startup.marker_poll_timeout_seconds must be at least 1",
+        ):
+            load_config(config_path)
+
 
 class TestIOErrors:
     """Tests for IO error handling."""
@@ -736,6 +801,12 @@ def test_issue_tracker_config_defaults(self):
         config = IssueTrackerConfig()
         assert config.override is None
 
+    def test_startup_config_defaults(self):
+        """StartupConfig has correct defaults."""
+        config = StartupConfig()
+        assert config.agent_ready_timeout_seconds == 30
+        assert config.marker_poll_timeout_seconds == 30
+
     def test_claude_team_config_defaults(self):
         """ClaudeTeamConfig has correct nested defaults."""
         config = ClaudeTeamConfig()
@@ -745,3 +816,4 @@ def test_claude_team_config_defaults(self):
         assert isinstance(config.terminal, TerminalConfig)
         assert isinstance(config.events, EventsConfig)
         assert isinstance(config.issue_tracker, IssueTrackerConfig)
+        assert isinstance(config.startup, StartupConfig)