cinna-cli 0.1.3__tar.gz → 0.1.5__tar.gz

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cinna-cli
-Version: 0.1.3
+Version: 0.1.5
 Summary: Local development CLI for Cinna Core agents
 Project-URL: Homepage, https://github.com/opencinna/cinna-cli
 Project-URL: Repository, https://github.com/opencinna/cinna-cli
@@ -127,10 +127,13 @@ Read-only views onto the live sync session (started by `cinna dev`).
 
 Stream a command through the platform to the remote agent environment. Output streams back live; Ctrl+C aborts. Exit code matches the remote process.
 
+Arguments pass through transparently — each token is re-quoted before being sent, so spaces and shell metacharacters inside an argument survive intact. Use ordinary single-level quoting, exactly as for a local command. To run a shell snippet (pipes, redirects, `&&`), pass it to a shell explicitly: `cinna exec bash -c '…'`.
+
 ```bash
 cinna exec python scripts/main.py
 cinna exec pip install pandas
-cinna exec 'bash -c "ls -la"'
+cinna exec bash -c 'ls -la'
+cinna exec python -c 'import sys; print(sys.argv)' "a b"
 ```
 
 ### `cinna status`

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/README.md

@@ -90,10 +90,13 @@ Read-only views onto the live sync session (started by `cinna dev`).
 
 Stream a command through the platform to the remote agent environment. Output streams back live; Ctrl+C aborts. Exit code matches the remote process.
 
+Arguments pass through transparently — each token is re-quoted before being sent, so spaces and shell metacharacters inside an argument survive intact. Use ordinary single-level quoting, exactly as for a local command. To run a shell snippet (pipes, redirects, `&&`), pass it to a shell explicitly: `cinna exec bash -c '…'`.
+
 ```bash
 cinna exec python scripts/main.py
 cinna exec pip install pandas
-cinna exec 'bash -c "ls -la"'
+cinna exec bash -c 'ls -la'
+cinna exec python -c 'import sys; print(sys.argv)' "a b"
 ```
 
 ### `cinna status`

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/docs/README.md

@@ -328,6 +328,23 @@ Two surfaces expose conflicts:
 
 Ctrl+C closes the SSE stream; the platform cleans up the remote process. Interactive stdin (REPLs, debuggers) is out of scope for the current `/exec` endpoint.
 
+### Argument quoting
+
+There are **two shell passes** between the keyboard and the remote process, and only one round of quoting belongs to each:
+
+1. **Local shell** (the caller's terminal / agent Bash tool) splits the command line into argv and strips one layer of quotes. `exec` is declared `nargs=-1`, so Click receives these already-split tokens as a tuple.
+2. **Remote shell** — the platform runs the `command` string through `/bin/sh -c`, re-parsing it a second time.
+
+`exec_cmd` (`main.py`) bridges the two with `shlex.join(command)`: it re-quotes each token so the remote `sh -c` reconstructs the *exact* argv the caller typed. This makes `cinna exec` a transparent passthrough — callers write ordinary single-level quoting, exactly as for a local command:
+
+```bash
+cinna exec python -c 'import sys; print(sys.argv)' "a b" '[{"x":"y z"}]'
+```
+
+The historical `" ".join(command)` dropped the word boundaries that the local shell's quoting had implied, so any argument containing a space or a shell metacharacter (`;`, `(`, `{`, …) was re-split or mis-parsed by the remote shell — e.g. `print(sys.argv)` failing with `/bin/sh: Syntax error: word unexpected (expecting ")")`. Regression coverage: `test_exec_command_requotes_args` in `tests/test_main.py`.
+
+To run an actual remote shell snippet (pipes, redirects, `&&`), pass it explicitly to a shell: `cinna exec bash -c 'a | b > c'`.
+
 ---
 
 ## Bootstrap Flow

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cinna-cli"
-version = "0.1.3"
+version = "0.1.5"
 description = "Local development CLI for Cinna Core agents"
 readme = "README.md"
 requires-python = ">=3.10"

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/src/cinna/bootstrap.py

@@ -272,7 +272,7 @@ def run_setup(setup_input: str, machine_name: str) -> None:
         # in the shared Mutagen daemon.
         if sync_started:
             console.status("Live sync attached — press Ctrl-C to stop.")
-            sync_session.run_foreground(config)
+            sync_session.run_foreground(config, workspace_root)
             console.status("Sync session terminated.")
     finally:
         client.close()

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/src/cinna/client.py

@@ -125,7 +125,9 @@ class PlatformClient:
 
     # --- Remote exec (SSE stream) ---
 
-    def stream_exec(self, agent_id: str, command: str) -> Iterator[dict]:
+    def stream_exec(
+        self, agent_id: str, command: str, timeout: int | None = None
+    ) -> Iterator[dict]:
         """POST /api/v1/cli/agents/{id}/exec — stream command output events.
 
         Yields parsed event dicts. Known shapes:
@@ -137,9 +139,21 @@ class PlatformClient:
 
         The caller is responsible for interpreting `done`/`interrupted` and
         mapping to a process exit code.
+
+        ``timeout`` (seconds) bounds the remote command's wall-clock run
+        time on the platform side. When omitted, the platform applies its
+        default.
         """
         url = f"/api/v1/cli/agents/{agent_id}/exec"
-        payload = {"command": command}
+        payload: dict = {"command": command}
+        if timeout is not None:
+            payload["timeout"] = timeout
+        logger.info(
+            "stream_exec open: agent=%s timeout=%s cmd=%.200s",
+            agent_id,
+            timeout,
+            command,
+        )
         with self._client.stream(
             "POST", url, json=payload, timeout=EXEC_STREAM_TIMEOUT
         ) as response:
@@ -149,15 +163,23 @@ class PlatformClient:
                 self._handle_response(response)
                 return
 
+            logger.debug(
+                "stream_exec connected: agent=%s status=%s", agent_id, response.status_code
+            )
+            event_count = 0
             for line in response.iter_lines():
                 if not line:
                     continue
                 if line.startswith("data: "):
                     data_str = line[6:]
                     try:
+                        event_count += 1
                         yield json.loads(data_str)
                     except json.JSONDecodeError:
                         logger.warning("Could not parse SSE event: %s", data_str[:200])
+            logger.debug(
+                "stream_exec closed: agent=%s events=%d", agent_id, event_count
+            )
 
     def close(self):
         self._client.close()

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/src/cinna/main.py

@@ -1,9 +1,12 @@
 """cinna CLI — local development for Cinna Core agents."""
 
+import logging
 import os
 import platform
+import shlex
 import shutil
 import sys
+import time
 from pathlib import Path
 
 import click
@@ -21,6 +24,8 @@ from cinna.config import (
 from cinna.mcp_proxy import run_mcp_proxy
 from cinna.mutagen_runtime import ensure_mutagen_ready
 
+logger = logging.getLogger("cinna.exec")
+
 
 @click.group()
 @click.version_option(version=__version__)
@@ -106,35 +111,71 @@ def set_token(setup_input: tuple[str, ...], name: str | None):
 
 
 @cli.command(name="exec", context_settings={"ignore_unknown_options": True})
+@click.option(
+    "--timeout",
+    "-t",
+    type=click.IntRange(min=1, max=86400),
+    default=1800,
+    show_default=True,
+    help="Max wall-clock seconds the remote command may run before being killed.",
+)
 @click.argument("command", nargs=-1, required=True)
-def exec_cmd(command: tuple[str, ...]):
+def exec_cmd(timeout: int, command: tuple[str, ...]):
     """Run a command in the remote agent environment.
 
     Output streams back in real time via the platform. Exit code matches the
     remote process's exit code. Ctrl+C aborts the stream.
 
+    Arguments are passed through transparently: each token you type is
+    re-quoted (``shlex.quote``) before being sent, so spaces and shell
+    metacharacters inside an argument survive the remote shell intact. Use
+    ordinary single-level quoting, exactly as for a local command.
+
     Examples:
       cinna exec python scripts/main.py
       cinna exec pip install pandas
       cinna exec bash -c 'ls -la'
+      cinna exec python -c 'import sys; print(sys.argv)' "a b"
+      cinna exec --timeout 3600 python long_backfill.py
+
+    If your remote command takes its own ``--timeout`` flag, separate it
+    from cinna's option with ``--``:
+
+      cinna exec --timeout 3600 -- python tool.py --timeout 30
     """
     root = find_workspace_root()
     config = load_config(root)
 
-    exit_code = _run_remote_exec(config, " ".join(command))
+    exit_code = _run_remote_exec(config, shlex.join(command), timeout=timeout)
     sys.exit(exit_code)
 
 
-def _run_remote_exec(config, command_str: str) -> int:
+def _run_remote_exec(config, command_str: str, timeout: int = 1800) -> int:
     """Drive the /exec SSE stream and mirror events to the local terminal."""
     exit_code = 0
+    exec_id: str | None = None
+    started_at = time.monotonic()
+    stdout_bytes = 0
+    stderr_bytes = 0
+    first_delta_at: float | None = None
+    terminal_event: str = "no-terminal-event"
+
+    logger.info(
+        "exec start: agent=%s timeout=%ds cmd=%r",
+        config.agent_id,
+        timeout,
+        command_str,
+    )
+
     with PlatformClient(config) as client:
         try:
-            for event in client.stream_exec(config.agent_id, command_str):
+            for event in client.stream_exec(
+                config.agent_id, command_str, timeout=timeout
+            ):
                 etype = event.get("type")
                 if etype == "exec_id":
-                    # First event — nothing to print. Remember it in case we
-                    # later ship an /exec-interrupt endpoint.
+                    exec_id = event.get("exec_id")
+                    logger.debug("exec_id assigned: %s", exec_id)
                     continue
                 if etype == "tool_result_delta":
                     chunk = event.get("content", "")
@@ -142,15 +183,45 @@ def _run_remote_exec(config, command_str: str) -> int:
                     target = sys.stderr if stream == "stderr" else sys.stdout
                     target.write(chunk)
                     target.flush()
+                    nbytes = len(chunk.encode("utf-8", errors="replace"))
+                    if stream == "stderr":
+                        stderr_bytes += nbytes
+                    else:
+                        stdout_bytes += nbytes
+                    if first_delta_at is None:
+                        first_delta_at = time.monotonic()
+                        logger.debug(
+                            "exec first output (stream=%s, %d bytes) after %.3fs",
+                            stream, nbytes, first_delta_at - started_at,
+                        )
                 elif etype == "done":
                     exit_code = int(event.get("exit_code", 0))
+                    terminal_event = "done"
+                    logger.debug("exec done event: exit_code=%s", exit_code)
                 elif etype == "interrupted":
                     exit_code = int(event.get("exit_code", 130))
+                    terminal_event = "interrupted"
+                    logger.info("exec interrupted by remote: exit_code=%s", exit_code)
                 elif etype == "error":
-                    console.error(event.get("content", "unknown error"))
+                    msg = event.get("content", "unknown error")
+                    console.error(msg)
                     exit_code = 1
+                    terminal_event = "error"
+                    logger.error("exec remote error: %s", msg)
+                else:
+                    logger.debug("exec unknown event type=%r: %.200s", etype, event)
         except KeyboardInterrupt:
             exit_code = 130
+            terminal_event = "keyboard-interrupt"
+            logger.info("exec interrupted locally (Ctrl-C)")
+
+    duration = time.monotonic() - started_at
+    logger.info(
+        "exec stop: agent=%s exec_id=%s exit_code=%s duration=%.3fs "
+        "stdout=%dB stderr=%dB terminal=%s",
+        config.agent_id, exec_id, exit_code, duration,
+        stdout_bytes, stderr_bytes, terminal_event,
+    )
     return exit_code
 
 

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/src/cinna/sync_session.py

@@ -12,6 +12,7 @@ import shlex
 import shutil
 import subprocess
 import sys
+import time
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -179,6 +180,29 @@ def _looks_like_stale_daemon_error(stderr: str) -> bool:
     return any(marker in text for marker in _STALE_DAEMON_MARKERS)
 
 
+# The backend closes the sync-stream WebSocket with code 1013 ("try again later")
+# while it auto-activates a suspended agent environment. The shim surfaces this
+# as a "received 1013 (try again later)" line and Mutagen reports it as a
+# handshake EOF. Detect it so we can retry transparently instead of dumping the
+# raw stack on the user.
+_AGENT_ENV_WAKING_MARKERS = (
+    "received 1013",
+    "(try again later)",
+)
+
+
+def _looks_like_agent_env_waking(stderr: str, stdout: str = "") -> bool:
+    text = (stderr or "") + "\n" + (stdout or "")
+    return any(marker in text for marker in _AGENT_ENV_WAKING_MARKERS)
+
+
+# Two retries spaced 5s apart give the backend ~10s to finish auto-activation
+# before we give up. Auto-activation polls for "running" status with a 120s
+# deadline server-side, but the WS handshake fails fast — each client retry
+# re-triggers ensure_environment_running and re-polls.
+_WAKING_RETRY_DELAYS_SECONDS = (5, 5)
+
+
 def _restart_daemon(config: CinnaConfig) -> None:
     """Bounce the Mutagen daemon so it picks up our env on next spawn.
 
@@ -278,15 +302,56 @@ def start(config: CinnaConfig, workspace_root: Path) -> SyncStatus:
         str(local_path),
         remote_url,
     ]
-    result = _run_mutagen(args, config, cwd=workspace_root)
-    if result.returncode != 0 and _looks_like_stale_daemon_error(result.stderr):
-        # Daemon was started before our current MUTAGEN_SSH_PATH wiring. Bounce
-        # it and retry once; the second pass runs against a fresh env.
-        _restart_daemon(config)
+
+    stale_daemon_restarted = False
+    waking_attempt = 0  # how many "agent env waking" retries we've already burned
+    while True:
         result = _run_mutagen(args, config, cwd=workspace_root)
-    if result.returncode != 0:
+        if result.returncode == 0:
+            break
+
+        if (
+            not stale_daemon_restarted
+            and _looks_like_stale_daemon_error(result.stderr)
+        ):
+            # Daemon was started before our current MUTAGEN_SSH_PATH wiring.
+            # Bounce it and retry; the second pass runs against a fresh env.
+            _restart_daemon(config)
+            stale_daemon_restarted = True
+            continue
+
+        if _looks_like_agent_env_waking(result.stderr, result.stdout):
+            if waking_attempt < len(_WAKING_RETRY_DELAYS_SECONDS):
+                delay = _WAKING_RETRY_DELAYS_SECONDS[waking_attempt]
+                total = len(_WAKING_RETRY_DELAYS_SECONDS)
+                waking_attempt += 1
+                console.warn(
+                    "Agent environment is not ready yet (waking up?). "
+                    f"Retrying in {delay}s ({waking_attempt}/{total})…"
+                )
+                logger.info(
+                    "Agent env not ready (1013); retry %d/%d after %ds",
+                    waking_attempt, total, delay,
+                )
+                time.sleep(delay)
+                # A failed `sync create` may leave a half-registered session in
+                # the daemon. Terminate it so the retry starts from a clean
+                # slate; ignore the result since "not found" is fine.
+                _run_mutagen(
+                    ["sync", "terminate", session_name(config.agent_id)], config
+                )
+                continue
+            raise click.ClickException(
+                "Cannot reach the agent environment.\n"
+                "The platform reported the environment is still waking up or "
+                "unavailable after several retries.\n"
+                "Open the agent in the platform UI and confirm its environment "
+                "is running, then re-run 'cinna dev'."
+            )
+
         raise click.ClickException(
-            f"Failed to create Mutagen session:\n{result.stderr.strip() or result.stdout.strip()}"
+            "Failed to create Mutagen session:\n"
+            f"{result.stderr.strip() or result.stdout.strip()}"
         )
 
     return status(config)

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/src/cinna/sync_tui.py

@@ -17,6 +17,7 @@ the sync after the TUI closes.
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 import logging
 import os
@@ -199,8 +200,8 @@ class SyncApp(App):
         # 1/5 only do anything on the Conflicts tab with a row highlighted;
         # the actions no-op otherwise so the user can mash them harmlessly.
         # 1 and 5 are spaced apart on the keyboard to make a misfire unlikely.
-        Binding("1", "take_remote", "1 take REMOTE", show=True, priority=True),
-        Binding("5", "take_local", "5 take LOCAL", show=True, priority=True),
+        Binding("1", "take_remote", "take REMOTE", show=True, priority=True),
+        Binding("5", "take_local", "take LOCAL", show=True, priority=True),
     ]
 
     # JSON state comes from a long-running `mutagen sync monitor` subprocess
@@ -289,15 +290,30 @@ class SyncApp(App):
 
     async def on_unmount(self) -> None:
         self._shutting_down = True
-        for task in (self._monitor_task, self._details_task):
-            if task is not None:
-                task.cancel()
         if self._monitor_proc is not None and self._monitor_proc.returncode is None:
             try:
                 self._monitor_proc.terminate()
             except ProcessLookupError:
                 pass
 
+        # Cancel the data loops AND await them. If we return before they finish,
+        # textual closes the asyncio loop while a `mutagen` subprocess is still
+        # running in the background; when that process eventually exits, its
+        # SIGCHLD is dispatched to a closed loop and we get "Loop <...> that
+        # handles pid N is closed" on stderr. Awaiting the tasks here gives
+        # their finally-blocks a chance to fully reap.
+        pending = [t for t in (self._monitor_task, self._details_task) if t is not None]
+        for task in pending:
+            task.cancel()
+        if pending:
+            try:
+                await asyncio.wait_for(
+                    asyncio.gather(*pending, return_exceptions=True),
+                    timeout=2.0,
+                )
+            except asyncio.TimeoutError:
+                logger.debug("data-loop tasks did not finish cleanly within 2s")
+
     def _disable_mouse_tracking(self) -> None:
         """Turn off the mouse-tracking modes textual enabled on startup.
 
@@ -361,6 +377,22 @@ class SyncApp(App):
                 self.query_one("#conflicts-list", OptionList).focus()
             except Exception:
                 pass
+        # Footer reflects bindings as of the last refresh; tab changes flip
+        # whether take_remote/take_local are applicable (see check_action).
+        self.refresh_bindings()
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        # 1/5 only resolve conflicts, which only makes sense on that tab.
+        # Returning False hides them from the footer entirely (None would
+        # leave them grayed out, which is still noisy on the other tabs).
+        if action in ("take_remote", "take_local"):
+            try:
+                active = self.query_one(TabbedContent).active
+            except Exception:
+                return True
+            if active != "conflicts-tab":
+                return False
+        return True
 
     # ── Data loops ────────────────────────────────────────────────────────
 
@@ -456,9 +488,22 @@ class SyncApp(App):
                 env=self._env,
                 start_new_session=True,
             )
-            stdout, _ = await proc.communicate()
         except (FileNotFoundError, OSError) as exc:
             return f"(mutagen unavailable: {exc})"
+
+        try:
+            stdout, _ = await proc.communicate()
+        except asyncio.CancelledError:
+            # The TUI is shutting down; reap the child before it outlives the
+            # event loop and triggers a "Loop ... is closed" SIGCHLD warning.
+            if proc.returncode is None:
+                try:
+                    proc.kill()
+                except ProcessLookupError:
+                    pass
+                with contextlib.suppress(Exception):
+                    await proc.wait()
+            raise
         if proc.returncode != 0:
             return ""
         return stdout.decode("utf-8", errors="replace").strip()

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/tests/test_main.py

@@ -215,7 +215,69 @@ def test_exec_command(mock_load, mock_find, mock_exec, runner, workspace_root, s
 
     result = runner.invoke(cli, ["exec", "python", "scripts/main.py"])
     assert result.exit_code == 0
-    mock_exec.assert_called_once_with(sample_config, "python scripts/main.py")
+    mock_exec.assert_called_once_with(
+        sample_config, "python scripts/main.py", timeout=1800
+    )
+
+
+@patch("cinna.main._run_remote_exec")
+@patch("cinna.main.find_workspace_root")
+@patch("cinna.main.load_config")
+def test_exec_command_requotes_args(
+    mock_load, mock_find, mock_exec, runner, workspace_root, sample_config
+):
+    """Tokens with spaces / shell metacharacters must be re-quoted so the
+    remote shell reconstructs the exact argv the caller intended, rather than
+    re-splitting them. Regression for `cinna exec` mangling quoted arguments.
+    """
+    mock_find.return_value = workspace_root
+    mock_load.return_value = sample_config
+    mock_exec.return_value = 0
+
+    result = runner.invoke(
+        cli,
+        ["exec", "python", "-c", "import sys; print(sys.argv)", "a b", '[{"x":"y z"}]'],
+    )
+    assert result.exit_code == 0
+    mock_exec.assert_called_once_with(
+        sample_config,
+        """python -c 'import sys; print(sys.argv)' 'a b' '[{"x":"y z"}]'""",
+        timeout=1800,
+    )
+
+
+@patch("cinna.main.PlatformClient")
+def test_run_remote_exec_logs_start_and_stop(mock_client_cls, sample_config, caplog):
+    """`cinna exec` must emit start/stop log records — without them this whole
+    code path is invisible in cinna.log, which has previously made remote
+    failures very hard to debug.
+    """
+    import logging
+    from cinna.main import _run_remote_exec
+
+    mock_client = mock_client_cls.return_value.__enter__.return_value
+    mock_client.stream_exec.return_value = iter([
+        {"type": "exec_id", "exec_id": "ex-1"},
+        {"type": "tool_result_delta", "content": "hi\n", "metadata": {"stream": "stdout"}},
+        {"type": "tool_result_delta", "content": "warn\n", "metadata": {"stream": "stderr"}},
+        {"type": "done", "exit_code": 0},
+    ])
+
+    with caplog.at_level(logging.DEBUG, logger="cinna.exec"):
+        exit_code = _run_remote_exec(sample_config, "echo hi")
+
+    assert exit_code == 0
+    messages = [r.getMessage() for r in caplog.records if r.name == "cinna.exec"]
+    assert any(m.startswith("exec start:") and "echo hi" in m for m in messages)
+    assert any("exec_id assigned: ex-1" in m for m in messages)
+    assert any(
+        m.startswith("exec stop:")
+        and "exit_code=0" in m
+        and "stdout=3B" in m
+        and "stderr=5B" in m
+        and "terminal=done" in m
+        for m in messages
+    )
 
 
 @patch("cinna.main.sync_session.run_foreground")

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/tests/test_sync_session.py

@@ -185,3 +185,106 @@ def test_start_retries_after_stale_daemon(mock_run, sample_config, tmp_path):
     assert any(args[:2] == ["daemon", "stop"] for args in mutagen_invocations)
     # Must have invoked sync create at least twice (retry after bounce).
     assert sum(1 for args in mutagen_invocations if args[:2] == ["sync", "create"]) == 2
+
+
+def test_looks_like_agent_env_waking():
+    from cinna.sync_session import _looks_like_agent_env_waking
+
+    real_world_stderr = (
+        "Error: unable to connect to beta: unable to connect to endpoint: "
+        "unable to dial agent endpoint: unable to handshake with agent process: "
+        "unable to receive server magic number: EOF (error output: "
+        "cinna-sync-ssh: ws pump ended: received 1013 (try again later); "
+        "then sent 1013 (try again later))"
+    )
+    assert _looks_like_agent_env_waking(real_world_stderr)
+    assert _looks_like_agent_env_waking("", real_world_stderr)
+    assert not _looks_like_agent_env_waking("auth failed: 401")
+    assert not _looks_like_agent_env_waking("")
+
+
+@patch("cinna.sync_session.time.sleep", lambda _s: None)
+@patch("cinna.sync_session._run_mutagen")
+def test_start_retries_when_agent_env_waking_then_succeeds(
+    mock_run, sample_config, tmp_path
+):
+    """When the backend closes the WS with 1013 ('try again later') because the
+    agent env is auto-activating, the CLI must retry a couple of times before
+    surfacing an error."""
+    from cinna.sync_session import start
+
+    (tmp_path / "workspace").mkdir()
+    waking_err = (
+        "Error: unable to handshake with agent process: "
+        "unable to receive server magic number: EOF (error output: "
+        "cinna-sync-ssh: ws pump ended: received 1013 (try again later))"
+    )
+
+    create_calls = {"n": 0}
+
+    def fake_run(args, *_a, **_kw):
+        first = args[0]
+        second = args[1] if len(args) > 1 else ""
+        if first == "daemon":
+            return MagicMock(returncode=0, stdout="", stderr="")
+        if first == "sync" and second == "list":
+            return MagicMock(returncode=0, stdout="[]", stderr="")
+        if first == "sync" and second == "terminate":
+            return MagicMock(returncode=0, stdout="", stderr="")
+        if first == "sync" and second == "create":
+            create_calls["n"] += 1
+            # First create fails with 1013; second one succeeds.
+            if create_calls["n"] == 1:
+                return MagicMock(returncode=1, stdout="", stderr=waking_err)
+            return MagicMock(returncode=0, stdout="", stderr="")
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    mock_run.side_effect = fake_run
+    start(sample_config, tmp_path)
+
+    assert create_calls["n"] == 2
+    # Between attempts we terminate the half-registered session.
+    invocations = [c.args[0] for c in mock_run.call_args_list]
+    assert any(args[:2] == ["sync", "terminate"] for args in invocations)
+
+
+@patch("cinna.sync_session.time.sleep", lambda _s: None)
+@patch("cinna.sync_session._run_mutagen")
+def test_start_gives_up_with_friendly_error_after_max_waking_retries(
+    mock_run, sample_config, tmp_path
+):
+    """After exhausting the waking-env retries, the user sees a friendly
+    message instead of the raw Mutagen handshake-EOF stack."""
+    import click
+    import pytest
+
+    from cinna.sync_session import start
+
+    (tmp_path / "workspace").mkdir()
+    waking_err = (
+        "unable to handshake with agent process: received 1013 (try again later)"
+    )
+
+    def fake_run(args, *_a, **_kw):
+        first = args[0]
+        second = args[1] if len(args) > 1 else ""
+        if first == "daemon":
+            return MagicMock(returncode=0, stdout="", stderr="")
+        if first == "sync" and second == "list":
+            return MagicMock(returncode=0, stdout="[]", stderr="")
+        if first == "sync" and second == "terminate":
+            return MagicMock(returncode=0, stdout="", stderr="")
+        if first == "sync" and second == "create":
+            return MagicMock(returncode=1, stdout="", stderr=waking_err)
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    mock_run.side_effect = fake_run
+    with pytest.raises(click.ClickException) as exc_info:
+        start(sample_config, tmp_path)
+
+    msg = exc_info.value.format_message()
+    assert "Cannot reach the agent environment" in msg
+    # The raw Mutagen "magic number" / 1013 detail must not be in the surfaced
+    # error — that's the noise we're hiding from the user.
+    assert "1013" not in msg
+    assert "magic number" not in msg

{cinna_cli-0.1.3 → cinna_cli-0.1.5}/uv.lock

@@ -136,7 +136,7 @@ wheels = [
 
 [[package]]
 name = "cinna-cli"
-version = "0.1.3"
+version = "0.1.5"
 source = { editable = "." }
 dependencies = [
     { name = "click" },