cloudagent-daemon 0.2.1__py3-none-any.whl

cloudagent_daemon/main_loop.py

@@ -0,0 +1,891 @@
+"""Daemon main loop — wires transport, dispatcher, queues, runner, and IPC.
+
+Sub-plan 1j (v0.2.0): the daemon defaults to SSE+POST transport. The
+WebSocket path is still selectable via ``--transport ws`` for environments
+where SSE causes friction (it shouldn't, but flags are cheap).
+
+Both paths share the same downstream wiring (OutboundQueue, FrameDispatcher,
+SpawnQueue, ClaudeRunner, IPC server) — only the transport plumbing differs.
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import platform
+import socket
+from pathlib import Path
+from typing import Callable
+
+from . import __version__
+from .claude_runner import ClaudeRunner
+from .config import DaemonConfig, DaemonState
+from .frame_dispatch import FrameDispatcher
+from .http_outbound import HTTPOutbound
+from .metrics import MetricsRegistry, get_default as get_default_metrics
+from .metrics_server import MetricsServer
+from .outbound_queue import OutboundQueue
+from .runtime_detect import DetectedRuntime, detect_runtimes
+from .spawn_outbox import SpawnOutbox
+from .spawn_queue import SpawnQueue
+from .sse_client import SSEClient
+from .transport import HTTPTransport
+from .unix_socket import DEFAULT_SOCKET_PATH, UnixSocketServer
+from .workspace import Workspace
+from .ws_client import WSClient, run_forever
+
+logger = logging.getLogger(__name__)
+
+# Heartbeat POST cadence — server's SSE ``:hb`` already keeps the daemon
+# fed, but a pure-receive stream gives the server no liveness signal,
+# hence this complementary daemon→server POST.
+#
+# 1k #61: tightened from 30s → 10s so backend can detect a dead daemon
+# within ≤30s (3 missed heartbeats × 10s). Backend sweep defaults moved
+# to interval=10s, threshold=30s in lockstep — see
+# ``backend/src/cloudagent/harness/host_presence_sweep.py``.
+HEARTBEAT_INTERVAL_SECONDS = 10.0
+# Backwards-compat alias — kept until any external readers (tests, ops
+# scripts) migrate. Internal code uses HEARTBEAT_INTERVAL_SECONDS.
+_HEARTBEAT_INTERVAL_S = HEARTBEAT_INTERVAL_SECONDS
+
+
+# Wave C #2 — outbox stuck watchdog cadence. Scans every agent's
+# ``pending-spawn.jsonl`` for ``received``-without-``done`` entries
+# older than their per-priority threshold (see
+# :data:`spawn_outbox.STUCK_THRESHOLDS_SECONDS`). The first stuck spawn
+# escalates to ``SystemExit(1)`` so launchd respawns the daemon and the
+# boot-replay path re-enqueues. 60s scan period is tight enough that a
+# pathological 30-min default threshold gets caught within ~1 min of
+# crossing the line, slack enough that the scan cost (~1 ms per agent
+# per pass) is negligible.
+OUTBOX_WATCHDOG_INTERVAL_SECONDS = 60.0
+
+
+# ---------------------------------------------------------------------------
+# Wave C #1 — assign / unassign payload → workspace materialisation
+# ---------------------------------------------------------------------------
+
+
+def _identity_from_assign_payload(payload: dict) -> dict | None:
+    """Translate an ``assign`` SSE frame payload into a Workspace identity.
+
+    Returns ``None`` when the payload has no ``agent_id`` (defensive —
+    the dispatcher already drops malformed frames upstream but the
+    daemon shouldn't crash if a future contract change strips fields).
+
+    Defaults mirror :func:`claude_runner._build_lazy_identity` so the
+    eager (assign-driven) and lazy (deliver-driven) workspace creation
+    paths are byte-identical for identical inputs:
+
+    * ``agent_name`` → agent_id when missing
+    * ``is_chief`` → False (security: daemon never auto-promotes)
+    * ``role`` → "staff"
+    * ``workspace_slug`` → "default"
+    * ``reports_to`` → "(unset)"
+    """
+    agent_id = str(payload.get("agent_id") or "")
+    if not agent_id:
+        return None
+    return {
+        "agent_id": agent_id,
+        "agent_name": str(payload.get("agent_name") or agent_id),
+        "is_chief": bool(payload.get("is_chief", False)),
+        "role": str(payload.get("role") or "staff"),
+        "workspace_slug": str(payload.get("workspace_slug") or "default"),
+        "reports_to": str(payload.get("reports_to") or "(unset)"),
+    }
+
+
+async def _handle_assign(workspace, payload: dict) -> str | None:
+    """Materialise an agent workspace from an ``assign`` payload.
+
+    Returns the agent_id on success, ``None`` on no-op (missing
+    agent_id) or :class:`Exception` swallowed (logged with full stack).
+    The caller — :class:`FrameDispatcher` via ``workspace_assign_callback``
+    — does not care about the return value; the value is surfaced for
+    unit tests + structured logging.
+
+    Wave C #1: pre-Wave-C the daemon only learned about agents via the
+    ``/v1/daemon/ready`` snapshot, so a staff created on the server
+    after the daemon started was invisible until launchd kickstart.
+    Backend now pushes ``assign`` frames; this handler is where we land
+    them.
+
+    Task #118 (2026-05-12) — payload may carry ``workspace_root`` (the
+    per-agent cwd override). When present we pass it to
+    ``Workspace.ensure`` so the spawn uses the user's chosen directory.
+    """
+    identity = _identity_from_assign_payload(payload)
+    if identity is None:
+        logger.warning("main_loop._handle_assign: payload missing agent_id; ignoring")
+        return None
+    agent_id = identity["agent_id"]
+    agent_workspace_root = payload.get("workspace_root")
+    if agent_workspace_root is not None and not isinstance(
+        agent_workspace_root, str
+    ):
+        # Defensive: silently drop a malformed (non-string) value
+        # rather than break the assign. Backend validates the shape at
+        # /v1/daemon/ready + on agent create/patch.
+        agent_workspace_root = None
+    try:
+        workspace.ensure(
+            agent_id,
+            identity,
+            agent_workspace_root=agent_workspace_root,
+        )
+    except Exception:
+        logger.exception(
+            "main_loop._handle_assign: workspace.ensure failed agent=%s",
+            agent_id,
+        )
+        return None
+    logger.info(
+        "main_loop._handle_assign: workspace materialised agent=%s role=%s "
+        "is_chief=%s workspace_root=%s (assign frame)",
+        agent_id, identity["role"], identity["is_chief"],
+        agent_workspace_root,
+    )
+    return agent_id
+
+
+async def _outbox_stuck_watchdog(
+    spawn_outbox: SpawnOutbox,
+    *,
+    interval_seconds: float = OUTBOX_WATCHDOG_INTERVAL_SECONDS,
+) -> None:
+    """Wave C #2 — periodically scan the spawn outbox for stuck entries.
+
+    Returns ONLY by raising :class:`SystemExit` so the supervisor in
+    :func:`_run_sse_post` treats it as a fatal task completion and
+    triggers launchd respawn. Per-priority thresholds come from
+    :data:`spawn_outbox.STUCK_THRESHOLDS_SECONDS`.
+
+    Rationale (Wave C audit §6 P0): pre-Wave-C a daemon-side bug that
+    silently dropped spawns left the outbox to grow forever with no
+    upstream signal. The supervisor only saw ``sse`` + ``heartbeat``
+    so an outbox-only failure looked like "healthy idle daemon".
+    Wiring this watchdog into the supervisor closes that observability
+    gap by promoting outbox staleness to a respawn-triggering event.
+    """
+    while True:
+        await asyncio.sleep(interval_seconds)
+        try:
+            stuck = await spawn_outbox.find_stuck()
+        except Exception:  # noqa: BLE001
+            # Defensive — a transient disk read error must not kill
+            # the watchdog (else SystemExit cascades for the wrong
+            # reason). Log and try again next tick.
+            logger.exception(
+                "main_loop._outbox_stuck_watchdog: find_stuck raised; "
+                "will retry next tick"
+            )
+            continue
+        # Wave C #3 — publish the per-scan stuck count even when zero
+        # so /metrics has a stable series. Best-effort: a missing
+        # metrics import (test fixture) must not block the watchdog.
+        try:
+            from cloudagent_daemon.metrics import get_default as _md
+            await _md().set_gauge(
+                "cloudagent_daemon_outbox_stuck", float(len(stuck))
+            )
+        except Exception:  # noqa: BLE001
+            pass
+        if not stuck:
+            continue
+        for entry in stuck:
+            logger.error(
+                "main_loop.outbox_watchdog: STUCK SPAWN agent=%s msg=%s "
+                "age=%.0fs priority=%s threshold=%.0fs — exiting so "
+                "launchd respawns and boot-replay re-enqueues",
+                entry.agent_id,
+                entry.msg_id,
+                entry.age_seconds,
+                entry.priority,
+                entry.threshold_seconds,
+            )
+        raise SystemExit(1)
+
+
+async def _handle_unassign(workspace, payload: dict) -> str | None:
+    """Log an ``unassign`` payload; preserve on-disk workspace files.
+
+    Wave C #1: we deliberately do NOT delete ``~/.cloudagent/agents/<id>/``
+    — MEMORY.md / notes / partial claude session state may be useful
+    post-mortem. Backend re-issuing ``assign`` is enough to re-arm. The
+    ``workspace`` arg is unused today but kept for symmetry with
+    :func:`_handle_assign` and so a future tombstone-marker write
+    (e.g. dropping a ``.meta/unassigned-at.txt``) lives in one place.
+    """
+    agent_id = str(payload.get("agent_id") or "")
+    reason = payload.get("reason")
+    if not agent_id:
+        return None
+    logger.info(
+        "main_loop._handle_unassign: agent=%s reason=%s "
+        "(workspace files preserved on disk)",
+        agent_id, reason,
+    )
+    return agent_id
+
+
+async def run_daemon(
+    cfg: DaemonConfig,
+    state: DaemonState,
+    *,
+    transport: str = "auto",
+    claude_binary: str = "claude",
+    workspace_root: Path | None = None,
+    socket_path: Path | None = None,
+    state_path: Path | None = None,
+    insecure: bool = False,
+    detect_runtimes_fn: Callable[[], list[DetectedRuntime]] | None = None,
+    profile: str | None = None,
+) -> None:
+    """Wire all components and run forever (until cancelled).
+
+    ``transport`` selects the wire:
+      * ``"sse"`` / ``"auto"`` — SSE+POST (v0.2.0+ default).
+      * ``"ws"`` — legacy WebSocket (kept for fallback / regression tests).
+
+    Path overrides (``workspace_root``, ``socket_path``, ``state_path``)
+    default to ``~/.cloudagent/...``; tests inject ``tmp_path`` paths to
+    avoid touching the real home dir. *profile* (M6 multi-profile) is
+    resolved through ``paths.resolve_profile`` so it picks up
+    ``CLOUDAGENT_DAEMON_PROFILE`` from the env when the caller didn't
+    pass an explicit value.
+    """
+    from .paths import resolve_profile
+
+    profile_name = resolve_profile(profile)
+
+    if transport == "ws":
+        await _run_legacy_ws(
+            cfg,
+            state,
+            claude_binary=claude_binary,
+            workspace_root=workspace_root,
+            socket_path=socket_path,
+            state_path=state_path,
+            insecure=insecure,
+            profile=profile_name,
+        )
+        return
+
+    # SSE+POST path (default for v0.2.0+).
+    await _run_sse_post(
+        cfg,
+        state,
+        claude_binary=claude_binary,
+        workspace_root=workspace_root,
+        socket_path=socket_path,
+        state_path=state_path,
+        insecure=insecure,
+        detect_runtimes_fn=detect_runtimes_fn,
+        profile=profile_name,
+    )
+
+
+# ---------------------------------------------------------------------------
+# SSE+POST path (1j default)
+# ---------------------------------------------------------------------------
+
+
+async def _run_sse_post(
+    cfg: DaemonConfig,
+    state: DaemonState,
+    *,
+    claude_binary: str,
+    workspace_root: Path | None,
+    socket_path: Path | None,
+    state_path: Path | None,
+    insecure: bool,
+    detect_runtimes_fn: Callable[[], list[DetectedRuntime]] | None,
+    profile: str = "default",
+) -> None:
+    # Task #118 (2026-05-12) — ``workspace_root`` is the host-level
+    # default for agent cwd, NOT the metadata root. Metadata lives at
+    # the per-profile compiled-in default (``~/.cloudagent/agents/`` for
+    # default profile, ``~/.cloudagent/agents-<name>/`` otherwise) so a
+    # user-chosen project directory never gets polluted with
+    # identity.json / mcp-config / MEMORY.md.
+    workspace = Workspace(host_workspace_root=workspace_root, profile=profile)
+    effective_state_path = state_path or DaemonState.default_path(profile)
+
+    http = HTTPOutbound(cfg.server_url, cfg.machine_api_key, insecure=insecure)
+
+    # Step 1: POST /v1/daemon/ready — replaces the WS hello+ready handshake.
+    runtimes_list = (detect_runtimes_fn or detect_runtimes)()
+    runtimes_payload = [r.to_payload() for r in runtimes_list]
+    # Task #113 (2026-05-12) — surface ``--workspace-root`` to backend
+    # so the fr UI can render "agents live at <path>" on host detail.
+    # When the user didn't pass the flag we omit the field rather
+    # than send the daemon's compiled-in default — backend treats
+    # omission as "no change" (preserves any previously-reported
+    # value, idempotent re-ready).
+    ready_payload: dict = {
+        "daemon_ver": __version__,
+        "runtimes": runtimes_payload,
+        "hostname": socket.gethostname(),
+        "os": platform.system().lower(),
+    }
+    if workspace_root is not None:
+        ready_payload["workspace_root"] = str(workspace_root)
+    try:
+        ready_resp = await http.post(
+            "/v1/daemon/ready",
+            ready_payload,
+        )
+    except Exception:
+        # Ready POST is the gate to everything else; if it fails we have
+        # nothing to do but bail out so the supervisor sees the error.
+        await http.close()
+        raise
+
+    host_id = ready_resp.get("host_id", "")
+    last_acked_seq = int(ready_resp.get("last_acked_seq", 0) or 0)
+    bound_agents = ready_resp.get("agents", []) or []
+    # Task #118 (2026-05-12) — eagerly materialize each bound agent's
+    # workspace so per-agent ``workspace_root`` overrides take effect
+    # BEFORE the first deliver lands (the deliver frame doesn't carry
+    # ``workspace_root`` — only ready / assign do). Idempotent re-
+    # materialization is safe (Workspace.ensure contract).
+    for bound in bound_agents:
+        try:
+            a_id = str(bound.get("agent_id") or "")
+            if not a_id:
+                continue
+            identity = {
+                "agent_id": a_id,
+                "agent_name": a_id,
+                "is_chief": False,
+                "role": "staff",
+                "workspace_slug": "default",
+                "reports_to": "(unset)",
+            }
+            workspace.ensure(
+                a_id,
+                identity,
+                agent_workspace_root=bound.get("workspace_root"),
+            )
+        except Exception:  # noqa: BLE001
+            logger.exception(
+                "main_loop._run_sse_post: failed to materialize bound "
+                "agent=%s (will retry on next deliver)",
+                bound.get("agent_id"),
+            )
+    # 2026-05-15 — detect host change before reconciling seq. When the
+    # ready response carries a host_id different from what state.json
+    # remembers (e.g. user re-installed the daemon against a different
+    # ``--server-url``, or backend recreated the host row), the local
+    # ``last_seq`` is from a different cluster and must be dropped —
+    # otherwise the SSE GET keeps sending stale ``Last-Event-ID`` and
+    # the new cluster's fresh frames silently get deduped.
+    prev_host = state.adopt_host_id(host_id)
+    if prev_host is not None:
+        logger.warning(
+            "daemon host_id changed (was=%s now=%s) — reset local "
+            "seq/dedupe state",
+            prev_host, host_id,
+        )
+
+    # Server is authoritative on last-acked — but never roll BACK the
+    # local state.last_seq if the daemon happens to have processed (and
+    # not yet acked) frames newer than the server has on file.
+    state.last_seq = max(state.last_seq, last_acked_seq)
+    # Persist the host fingerprint immediately. The frame_dispatch path
+    # also saves on every ack, but for a fresh start that processes no
+    # frames we still want state.json on disk so the next launch can
+    # detect mismatch instead of treating itself as first-ever.
+    state.save(effective_state_path)
+
+    # Wave C #3 — metrics registry. Initialized here (after ready POST)
+    # so the SSE client + spawn pipeline can publish into a shared
+    # default registry; the /metrics endpoint scrapes from the same.
+    metrics = get_default_metrics()
+    await metrics.set_gauge(
+        "cloudagent_daemon_agents_bound", float(len(bound_agents))
+    )
+
+    logger.info(
+        "daemon ready: host_id=%s last_acked_seq=%d agents_bound=%d",
+        host_id,
+        last_acked_seq,
+        len(bound_agents),
+    )
+
+    # Step 2: build outbound + components.
+    transport_obj = HTTPTransport(http)
+    pending_tool_calls: dict[str, asyncio.Future] = {}
+    outbound = OutboundQueue(
+        transport=transport_obj, pending_tool_calls=pending_tool_calls
+    )
+
+    # 1k74 — token-level streaming publisher. claude_runner calls this
+    # for every text_delta chunk; we just POST it through the existing
+    # bearer-authenticated httpx client. Backend's endpoint publishes
+    # to Redis without a DB write, so the daemon→backend cost stays
+    # bounded (1 HTTP POST per ~80 chars of model output ≈ a dozen
+    # POSTs for a typical reply). Only wired on the SSE-POST path —
+    # the legacy WS path keeps the pre-1k74 buffered-reply behaviour.
+    async def _publish_partial(
+        session_id: str, agent_id: str, body: str
+    ) -> None:
+        await http.post(
+            "/v1/daemon/publish-partial",
+            {
+                "session_id": session_id,
+                "agent_id": agent_id,
+                "body": body,
+            },
+        )
+
+    # (c) IPC architecture upgrade — shared agent→session memory map.
+    # ClaudeRunner registers the current session_id before spawn and
+    # removes it after. mcp_bridge queries via the ``get_current_session``
+    # IPC op instead of reading a file; file fallback kept for backward
+    # compat (old daemons without this map still work via the file).
+    _agent_to_session: dict[str, str | None] = {}
+
+    runner = ClaudeRunner(
+        outbound=outbound,
+        workspace=workspace,
+        claude_binary=claude_binary,
+        partial_publisher=_publish_partial,
+        agent_to_session=_agent_to_session,
+    )
+
+    async def _queue_full(agent_id: str, message_id: str) -> None:
+        await outbound.send_ack(seq=None, message_id=message_id, status="queue_full")
+
+    # Bug 4 (2026-05-12) — durable spawn outbox so deliver frames acked
+    # but not yet spawned survive daemon crashes. See spawn_outbox.py.
+    spawn_outbox = SpawnOutbox(workspace=workspace)
+    spawn = SpawnQueue(
+        runner=runner,
+        queue_full_callback=_queue_full,
+        spawn_outbox=spawn_outbox,
+    )
+
+    # Boot-time replay: any frames recorded as ``received`` without a
+    # matching ``done`` from the previous run get re-enqueued before we
+    # start accepting new frames. Skipping ack here — server already
+    # ack'd these in the prior run (that's exactly why they're stuck).
+    pending = await spawn_outbox.find_pending()
+    for payload in pending:
+        logger.info(
+            "main_loop: replaying pending spawn agent=%s msg=%s",
+            payload.get("agent_id"),
+            payload.get("message_id"),
+        )
+        await spawn.enqueue(payload)
+
+    # Wave C #1 (2026-05-12) — dynamic agent discovery.
+    #
+    # Pre-Wave-C, ``agents_bound`` was only refreshed on daemon restart
+    # (snapshot from ``/v1/daemon/ready``). A staff created on the
+    # server after the daemon already started would be invisible until
+    # the next launchd kickstart — that's the structural root of Bug 4b
+    # in ``docs/debug/2026-05-12-task-multi-agent-debug.md`` ("StaffPro
+    # 没 runner"). Backend now pushes ``assign`` SSE frames; the
+    # handler bodies live in :func:`_handle_assign` /
+    # :func:`_handle_unassign` so they're directly unit-testable.
+
+    async def _on_assign(payload: dict) -> None:
+        await _handle_assign(workspace, payload)
+
+    async def _on_unassign(payload: dict) -> None:
+        await _handle_unassign(workspace, payload)
+
+    dispatcher = FrameDispatcher(
+        state=state,
+        state_path=effective_state_path,
+        ack_callback=outbound.send_ack,
+        spawn_callback=spawn.enqueue,
+        tool_result_pending=pending_tool_calls,
+        spawn_outbox=spawn_outbox,
+        workspace_assign_callback=_on_assign,
+        workspace_unassign_callback=_on_unassign,
+    )
+
+    from .unix_socket import default_socket_path as _default_socket_path
+
+    sock_path = socket_path or _default_socket_path(profile)
+    sock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    async def ipc_handler(req: dict) -> dict:
+        # 1k #55 — IPC entry/exit logging for multi-tool-wake debugging.
+        ipc_rid = req.get("request_id")
+        op = req.get("op")
+
+        # (c) IPC architecture upgrade — daemon-memory session query.
+        # mcp_bridge sends this at startup to get the current session_id
+        # without reading a file; more reliable than the file-based path.
+        if op == "get_current_session":
+            a = req.get("args") or {}
+            agent_id_q = a.get("agent_id") or ""
+            sid = _agent_to_session.get(agent_id_q)
+            logger.info(
+                "main_loop.ipc_handler: get_current_session agent=%s sid=%s",
+                agent_id_q, sid,
+            )
+            return {"result": {"session_id": sid}}
+
+        if op != "tool_call":
+            logger.warning(
+                "main_loop.ipc_handler: unknown op=%r ipc_rid=%s", op, ipc_rid,
+            )
+            return {"error": {"code": "UNKNOWN_OP", "message": str(op)}}
+        a = req.get("args") or {}
+        logger.info(
+            "main_loop.ipc_handler: ENTER ipc_rid=%s tool=%s agent=%s "
+            "session=%s",
+            ipc_rid, a.get("tool_name"), a.get("agent_id"), a.get("session_id"),
+        )
+        try:
+            result = await outbound.send_tool_call(
+                agent_id=a["agent_id"],
+                session_id=a.get("session_id"),
+                tool_name=a["tool_name"],
+                args=a.get("tool_args") or {},
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.exception(
+                "main_loop.ipc_handler: dispatch raised ipc_rid=%s tool=%s",
+                ipc_rid, a.get("tool_name"),
+            )
+            return {
+                "error": {
+                    "code": "BRIDGE_DISPATCH_FAILED",
+                    "message": f"{type(exc).__name__}: {exc}",
+                }
+            }
+        logger.info(
+            "main_loop.ipc_handler: EXIT ipc_rid=%s tool=%s ok=%s",
+            ipc_rid, a.get("tool_name"), result.get("ok"),
+        )
+        if result.get("ok"):
+            return {"result": result.get("data", {})}
+        return {"error": result.get("error", {"code": "UNKNOWN_ERROR"})}
+
+    ipc_server = UnixSocketServer(sock_path, ipc_handler)
+    await ipc_server.start()
+
+    # Wave C #3 — Prometheus-scrape unix socket. Lives alongside
+    # ``bridge.sock`` under ``~/.cloudagent/daemon/`` with 0o600 perms.
+    # Lifecycle mirrors the IPC server: start now, stop in the
+    # outer-finally cleanup so a daemon restart cycle doesn't leak
+    # stale socket files.
+    metrics_server = MetricsServer(metrics)
+    try:
+        await metrics_server.start()
+    except Exception:
+        # Best-effort — if the metrics socket can't bind (e.g. perms
+        # / readonly home dir) we proceed without /metrics. The
+        # daemon must NOT refuse to serve agents because Prometheus
+        # is down.
+        logger.exception(
+            "main_loop: metrics_server.start failed; /metrics unavailable"
+        )
+        metrics_server = None
+
+    # Step 3: heartbeat task. Best-effort liveness POST every
+    # ``HEARTBEAT_INTERVAL_SECONDS`` (1k #61: 10s) — if the server didn't
+    # already see us via an ack/status frame, this nudges ``last_seen_at``
+    # so the dashboard's online indicator stays green and the host-presence
+    # reaper doesn't flip us to offline.
+    async def heartbeat() -> None:
+        while True:
+            await asyncio.sleep(HEARTBEAT_INTERVAL_SECONDS)
+            try:
+                await http.post("/v1/daemon/heartbeat", {})
+            except asyncio.CancelledError:
+                raise
+            except Exception:  # noqa: BLE001
+                logger.debug("heartbeat POST failed", exc_info=True)
+
+    # Step 4: SSE consumer — the inbound side.
+    sse = SSEClient(
+        cfg.server_url,
+        cfg.machine_api_key,
+        insecure=insecure,
+        last_event_id=str(state.last_seq),
+    )
+    # Wave C #3 — gauges that derive from the SSE client at scrape time.
+    metrics.gauge(
+        "cloudagent_daemon_sse_last_event_age_seconds",
+        "Seconds since the last parsed SSE event arrived.",
+        resolver=lambda: sse.last_event_age_seconds,
+    )
+
+    async def on_frame(frame: dict) -> None:
+        # Wave C #3 — count every frame the dispatcher sees, including
+        # duplicates (which we still ack). Failure modes (raised
+        # exceptions in dispatcher) still propagate to the SSE task.
+        if frame.get("type") == "deliver":
+            await metrics.inc_counter(
+                "cloudagent_daemon_deliver_frames_total"
+            )
+        await dispatcher.dispatch(frame)
+
+    cancelled = False
+    try:
+        # 1k78 — explicit task supervisor in place of ``asyncio.gather``.
+        #
+        # Pre-1k78 we used ``await asyncio.gather(sse.run_forever,
+        # heartbeat)``: documented to propagate any task's first
+        # exception and cancel siblings. In production we observed the
+        # SSE task silently entering a "done" state (never reconnecting,
+        # never raising) while the heartbeat task kept POSTing for
+        # hours — the daemon process was technically alive but useless
+        # because every command sent from the UI piled up in
+        # ``undelivered_frames`` with no consumer. Root cause for the
+        # gather bypass was never pinned (likely an httpx-sse internal
+        # path swallowed an exception), so this defensive supervisor
+        # explicitly polls each task's completion and force-exits the
+        # daemon — letting launchd / systemd auto-respawn it — the
+        # moment either task ends unexpectedly.
+        sse_task = asyncio.create_task(
+            sse.run_forever(on_frame), name="daemon.sse"
+        )
+        heartbeat_task = asyncio.create_task(heartbeat(), name="daemon.heartbeat")
+        # Wave C #2 — outbox stuck self-kill. The watchdog only returns
+        # by raising SystemExit, so the supervisor's FIRST_COMPLETED
+        # treats a stuck spawn the same as a dead SSE: log + respawn.
+        outbox_watchdog_task = asyncio.create_task(
+            _outbox_stuck_watchdog(spawn_outbox),
+            name="daemon.outbox_watchdog",
+        )
+        watched = {sse_task, heartbeat_task, outbox_watchdog_task}
+        try:
+            done, pending = await asyncio.wait(
+                watched, return_when=asyncio.FIRST_COMPLETED
+            )
+            # First task done. If it raised, surface that and abort —
+            # the supervisor's job from here on is to make sure the
+            # daemon doesn't linger in a half-dead state.
+            for t in done:
+                exc = t.exception()
+                if exc is not None and not isinstance(
+                    exc, asyncio.CancelledError
+                ):
+                    logger.error(
+                        "daemon supervisor: task %s died with %r — exiting "
+                        "so launchd respawns",
+                        t.get_name(), exc,
+                    )
+                else:
+                    logger.error(
+                        "daemon supervisor: task %s ended unexpectedly "
+                        "(no exception) — exiting so launchd respawns",
+                        t.get_name(),
+                    )
+            for t in pending:
+                t.cancel()
+            # Drain cancellations so cleanup hooks below get a chance
+            # to run. Don't propagate the underlying error; we're
+            # exiting deliberately.
+            for t in pending:
+                with contextlib.suppress(Exception):
+                    await t
+            # Force non-zero exit so launchd's KeepAlive respawns us.
+            raise SystemExit(1)
+        except asyncio.CancelledError:
+            cancelled = True
+            raise
+    finally:
+        sse.stop()
+        try:
+            await ipc_server.stop()
+        except Exception:  # noqa: BLE001
+            pass
+        if metrics_server is not None:
+            try:
+                await metrics_server.stop()
+            except Exception:  # noqa: BLE001
+                pass
+        if cancelled:
+            await spawn.cancel_all()
+        else:
+            await spawn.shutdown()
+        await transport_obj.close()
+
+
+# ---------------------------------------------------------------------------
+# Legacy WebSocket path (kept for --transport ws)
+# ---------------------------------------------------------------------------
+
+
+async def _run_legacy_ws(
+    cfg: DaemonConfig,
+    state: DaemonState,
+    *,
+    claude_binary: str,
+    workspace_root: Path | None,
+    socket_path: Path | None,
+    state_path: Path | None,
+    insecure: bool,
+    profile: str = "default",
+) -> None:
+    """Pre-1j WebSocket path. Identical to the v0.1.0 main loop body."""
+    # Task #118 (2026-05-12) — see SSE path's matching comment.
+    workspace = Workspace(host_workspace_root=workspace_root, profile=profile)
+    effective_state_path = state_path or DaemonState.default_path(profile)
+
+    pending_tool_calls: dict[str, asyncio.Future] = {}
+    outbound = OutboundQueue(transport=None, pending_tool_calls=pending_tool_calls)
+
+    runner = ClaudeRunner(
+        outbound=outbound, workspace=workspace, claude_binary=claude_binary
+    )
+
+    async def _queue_full(agent_id: str, message_id: str) -> None:
+        await outbound.send_ack(seq=None, message_id=message_id, status="queue_full")
+
+    # Bug 4 — same outbox + replay wiring as the SSE path. Both
+    # transports share the same crash-survival behaviour.
+    spawn_outbox = SpawnOutbox(workspace=workspace)
+    spawn = SpawnQueue(
+        runner=runner,
+        queue_full_callback=_queue_full,
+        spawn_outbox=spawn_outbox,
+    )
+
+    pending = await spawn_outbox.find_pending()
+    for payload in pending:
+        logger.info(
+            "main_loop: replaying pending spawn agent=%s msg=%s",
+            payload.get("agent_id"),
+            payload.get("message_id"),
+        )
+        await spawn.enqueue(payload)
+
+    # Wave C #1 — same assign/unassign wiring as the SSE path.
+    async def _on_assign_ws(payload: dict) -> None:
+        await _handle_assign(workspace, payload)
+
+    async def _on_unassign_ws(payload: dict) -> None:
+        await _handle_unassign(workspace, payload)
+
+    dispatcher = FrameDispatcher(
+        state=state,
+        state_path=effective_state_path,
+        ack_callback=outbound.send_ack,
+        spawn_callback=spawn.enqueue,
+        tool_result_pending=pending_tool_calls,
+        spawn_outbox=spawn_outbox,
+        workspace_assign_callback=_on_assign_ws,
+        workspace_unassign_callback=_on_unassign_ws,
+    )
+
+    from .unix_socket import default_socket_path as _default_socket_path_ws
+
+    sock_path = socket_path or _default_socket_path_ws(profile)
+    sock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    async def ipc_handler(req: dict) -> dict:
+        if req.get("op") != "tool_call":
+            return {"error": {"code": "UNKNOWN_OP", "message": str(req.get("op"))}}
+        a = req.get("args") or {}
+        try:
+            result = await outbound.send_tool_call(
+                agent_id=a["agent_id"],
+                session_id=a.get("session_id"),
+                tool_name=a["tool_name"],
+                args=a.get("tool_args") or {},
+            )
+        except Exception as exc:  # noqa: BLE001
+            return {
+                "error": {
+                    "code": "BRIDGE_DISPATCH_FAILED",
+                    "message": f"{type(exc).__name__}: {exc}",
+                }
+            }
+        if result.get("ok"):
+            return {"result": result.get("data", {})}
+        return {"error": result.get("error", {"code": "UNKNOWN_ERROR"})}
+
+    ipc_server = UnixSocketServer(sock_path, ipc_handler)
+    await ipc_server.start()
+
+    def _client_factory() -> WSClient:
+        return WSClient(
+            server_url=cfg.server_url,
+            api_key=cfg.machine_api_key,
+            insecure=insecure,
+            # Task #113 — propagate workspace_root onto every WS
+            # reconnect's ``ready`` frame so a daemon that auto-
+            # reconnects after a network drop still surfaces the
+            # user-chosen root to backend.
+            workspace_root=(
+                str(workspace_root) if workspace_root is not None else None
+            ),
+        )
+
+    async def _on_connect(client: WSClient) -> None:
+        # ``outbound.ws = client`` is the legacy assignment shape — the new
+        # property setter on OutboundQueue adapts a WSClient into a
+        # Transport (_LegacyWSAdapter) so existing code works unchanged.
+        outbound.ws = client
+        # Same host_id-change reset the SSE path does. Runs BEFORE
+        # ws_client.run_forever calls state_loader → send_resume so a
+        # cluster switch doesn't replay stale Last-Event-ID upstream.
+        prev_host = state.adopt_host_id(client.host_id)
+        if prev_host is not None:
+            logger.warning(
+                "daemon host_id changed (was=%s now=%s) — reset local "
+                "seq/dedupe state",
+                prev_host, client.host_id,
+            )
+            state.save(effective_state_path)
+        logger.info("daemon connected: host_id=%s", client.host_id)
+
+    async def _on_frame(frame: dict) -> None:
+        await dispatcher.dispatch(frame)
+
+    cancelled = False
+    try:
+        # Wave C #2 — same outbox watchdog wiring as the SSE path.
+        # Wrap the WS run_forever + watchdog in a wait(...) so a stuck
+        # spawn here also escalates to launchd-respawn instead of
+        # sitting silently while the WS keeps heart-beating.
+        ws_task = asyncio.create_task(
+            run_forever(
+                client_factory=_client_factory,
+                on_frame=_on_frame,
+                state_loader=lambda: state.last_seq,
+                on_connect=_on_connect,
+            ),
+            name="daemon.ws",
+        )
+        outbox_task = asyncio.create_task(
+            _outbox_stuck_watchdog(spawn_outbox),
+            name="daemon.outbox_watchdog",
+        )
+        watched = {ws_task, outbox_task}
+        done, pending = await asyncio.wait(
+            watched, return_when=asyncio.FIRST_COMPLETED
+        )
+        for t in pending:
+            t.cancel()
+        for t in pending:
+            with contextlib.suppress(Exception):
+                await t
+        # Surface the completed task's exception (if any) so callers /
+        # launchd see the right exit code.
+        for t in done:
+            exc = t.exception()
+            if exc is not None and not isinstance(
+                exc, asyncio.CancelledError
+            ):
+                raise exc
+    except asyncio.CancelledError:
+        cancelled = True
+        raise
+    finally:
+        await ipc_server.stop()
+        if cancelled:
+            await spawn.cancel_all()
+        else:
+            await spawn.shutdown()