code-context-control 2.127.0__tar.gz → 2.128.1__tar.gz

{code_context_control-2.127.0 → code_context_control-2.128.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.127.0
+Version: 2.128.1
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -168,6 +168,8 @@ c3 ui                             # binds the first free port from 3333
 
 Twelve tabs. The dashboard above shows token savings, indexed files, the live session, and a stream of recent tool calls and file changes.
 
+Since v2.128.0 you rarely start it by hand: opening an IDE session in a registered project brings its UI up, and a session proves it is alive with a heartbeat rather than with tool-call traffic — so a quiet session stays live and a closed one disappears at once. Servers a session started are reaped once the session is gone; the ones you started are not. → [Session liveness](https://github.com/drknowhow/code-context-control/blob/main/docs/session-liveness.md)
+
 | Tab | What it's for |
 |---|---|
 | **Dashboard** | Token savings, codebase breakdown, live session counters, recent activity |

{code_context_control-2.127.0 → code_context_control-2.128.1}/README.md

@@ -102,6 +102,8 @@ c3 ui                             # binds the first free port from 3333
 
 Twelve tabs. The dashboard above shows token savings, indexed files, the live session, and a stream of recent tool calls and file changes.
 
+Since v2.128.0 you rarely start it by hand: opening an IDE session in a registered project brings its UI up, and a session proves it is alive with a heartbeat rather than with tool-call traffic — so a quiet session stays live and a closed one disappears at once. Servers a session started are reaped once the session is gone; the ones you started are not. → [Session liveness](https://github.com/drknowhow/code-context-control/blob/main/docs/session-liveness.md)
+
 | Tab | What it's for |
 |---|---|
 | **Dashboard** | Token savings, codebase breakdown, live session counters, recent activity |

{code_context_control-2.127.0 → code_context_control-2.128.1}/cli/_hook_utils.py

@@ -8,6 +8,7 @@ All hook reads/writes of enforcement state MUST go through this module.
 import json
 import os
 import re
+import shlex
 import sys
 import traceback
 from datetime import datetime, timezone
@@ -34,6 +35,27 @@ LEGACY_UNLOCK_FILE = ".c3/unlocked_files.json"
 STATE_WARNINGS: list = []
 
 
+def hook_command_arg(raw) -> str:
+    """Quote one argv element for a hook ``command`` string in settings.
+
+    Windows: a DOUBLE-quoted forward-slash path. Claude Code runs hooks through
+    Git Bash, where ``shlex.quote`` produces SINGLE quotes around a backslash
+    path — cmd.exe does not treat single quotes as quoting, so any path with a
+    space or parentheses (``Claude Code Companion (C3)``) breaks. A
+    double-quoted forward-slash path is parsed correctly by bash AND cmd.
+    Verified 2026-07-26 under Git Bash on Windows 11; the installer in
+    cli/c3.py carries the full investigation, including why no ``cmd.exe /c``
+    wrapper belongs here.
+
+    Anything that writes a hook command — the installer and the hub's
+    migration — must go through this, or the entry it writes is dead on
+    Windows.
+    """
+    if sys.platform == "win32":
+        return '"' + str(raw).replace("\\", "/") + '"'
+    return shlex.quote(str(raw))
+
+
 def ensure_utf8_stdio() -> None:
     """Force UTF-8 on the hook process's stdio pipes.
 

{code_context_control-2.127.0 → code_context_control-2.128.1}/cli/c3.py

@@ -33,7 +33,6 @@ import json
 import logging
 import os
 import re
-import shlex
 import subprocess
 import sys
 import tempfile
@@ -92,7 +91,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.127.0"
+__version__ = "2.128.1"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -5542,10 +5541,10 @@ def cmd_install_mcp(args):
         # the wrapper was never needed. A double-quoted forward-slash path is parsed
         # correctly by bash AND cmd, including paths containing spaces or parentheses
         # (e.g. "Claude Code Companion (C3)"), which is why the wrapper was added.
-        def _hook_arg(raw: str) -> str:
-            if sys.platform == "win32":
-                return '"' + str(raw).replace("\\", "/") + '"'
-            return shlex.quote(str(raw))
+        # Lives in cli/_hook_utils so the hub's hook migration quotes commands
+        # the same way — it used shlex.quote and wrote entries that Windows
+        # could not run.
+        from cli._hook_utils import hook_command_arg as _hook_arg
 
         # v2.42: single dispatcher script per hook event instead of N separate
         # per-hook commands. One interpreter spawn per event; the dispatcher

code_context_control-2.128.1/cli/hook_session_open.py

@@ -0,0 +1,199 @@
+"""SessionStart hook: record that a host session opened (D0b, v2.126.0).
+
+Claude Code's ``SessionStart`` event delivers on stdin::
+
+    {
+      "session_id": "<Claude Code UUID>",
+      "transcript_path": "...",
+      "cwd": "...",
+      "hook_event_name": "SessionStart",
+      "source": "startup" | "resume" | "clear" | "compact"
+    }
+
+Codex's ``SessionStart`` carries its thread id in the same ``session_id``
+field and no ``source``; the dispatcher routes both here (event ``start``).
+
+Records:
+
+- ``{type: "session_open", host_session_id, source: <host>, start_source}``
+  in ``.c3/activity_log.jsonl``. ``source`` is the HOST (``claude`` /
+  ``codex`` / ``gemini``), matching ``session_end``; the payload's own
+  ``source`` (startup / resume / clear) is kept as ``start_source``.
+- a ``session`` notification (``kind="session"``, ``ref_id=host id``,
+  ``info``, title ``Session started <short id>``).
+
+It also brings up the project's UI server when one is not already running
+(``ensure_ui`` below, v2.128.0) — the only place in C3 where "a session
+started" causes "the UI is up". It needs the project to be registered with
+the hub, and it skips a project that already has a live UI port, so a
+``resume`` or ``clear`` never stacks a second server. Opt out with
+``C3_NO_UI_AUTOSTART=1`` or
+``.c3/config.json → {"ui": {"autostart_on_session": false}}``.
+
+``source: "compact"`` writes NOTHING: a compaction is the same session and
+the same MCP process, and a "Session started" toast on every compaction
+would teach the user to ignore the real ones.
+
+The MCP server's own ``session_start`` row is untouched — it carries the C3
+id and, when the host put its id in the environment, ``host_session_id``
+too. This hook is what lets a client see the session before the runtime has
+finished starting (~seconds), and it is the row the desktop's "MCP failed to
+connect" sentinel starts its 30 s clock from.
+
+Returns None always: SessionStart hook stdout becomes model context, and
+this hook has nothing to tell the model.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from cli._hook_utils import detect_host, find_project, log_hook_error  # noqa: E402
+from cli.hook_session_end import short_id  # noqa: E402
+
+_SILENT_SOURCES = {"compact"}
+
+
+def _ui_autostart_enabled(project: Path) -> bool:
+    """Opt-outs, in the order a user reaches for them."""
+    if os.environ.get("C3_NO_UI_AUTOSTART") or os.environ.get("C3_BENCHMARK_MODE"):
+        return False
+    try:
+        cfg = json.loads((project / ".c3" / "config.json").read_text(encoding="utf-8"))
+    except Exception:
+        return True  # no readable config is not a reason to withhold the UI
+    ui = cfg.get("ui")
+    if isinstance(ui, dict) and "autostart_on_session" in ui:
+        return bool(ui.get("autostart_on_session"))
+    return True
+
+
+def _is_registered(pm, project: Path) -> bool:
+    """True when the hub knows this project.
+
+    The UI server is a hub-level surface: a directory the user never
+    registered gets nothing automatic (``c3 ui`` still works). This is also
+    what keeps a test fixture or a scratch clone from growing a web server.
+    """
+    target = os.path.normcase(str(project))
+    for entry in pm._read_projects():
+        raw = str(entry.get("path") or "")
+        if raw and os.path.normcase(raw) == target:
+            return True
+        try:
+            if raw and os.path.normcase(str(Path(raw).resolve())) == target:
+                return True
+        except Exception:
+            continue
+    return False
+
+
+def _ui_running(pm, project: Path) -> bool:
+    """True when a live UI server is already registered for this project.
+
+    This is what keeps `resume` / `clear` — both real SessionStart events —
+    from stacking a second server on every reconnect.
+    """
+    target = os.path.normcase(str(project))
+    for entry in pm._read_registry():
+        raw = str(entry.get("project_path") or "")
+        if not raw:
+            continue
+        try:
+            same = os.path.normcase(str(Path(raw).resolve())) == target
+        except Exception:
+            same = os.path.normcase(raw) == target
+        if same and entry.get("port") and pm._port_alive(entry["port"]):
+            return True
+    return False
+
+
+def ensure_ui(project: Path, host_session_id: str = "") -> str:
+    """Bring up this project's UI server for the session that just opened.
+
+    Nothing else in C3 connected "a session started" to "the UI is running":
+    the hub's sweep only chases projects flagged `autostart_ui`, and before
+    2.128.0 it ran once at hub startup — so a UI was only ever there because
+    an earlier session had left one behind.
+
+    Returns a short reason string (tests and diagnostics read it). Never
+    raises and never prints — SessionStart stdout becomes model context.
+    """
+    try:
+        project = Path(project).resolve()
+    except Exception:
+        project = Path(project)
+    if not _ui_autostart_enabled(project):
+        return "disabled"
+    try:
+        from services.project_manager import ProjectManager
+        pm = ProjectManager()
+        if not _is_registered(pm, project):
+            return "unregistered"
+        if _ui_running(pm, project):
+            return "already-running"
+        # launch_session copies os.environ into the detached child, which is
+        # where cli/server._register_session reads the ownership from.
+        os.environ["C3_UI_OWNER"] = "session"
+        if host_session_id:
+            os.environ["C3_UI_OWNER_SESSION"] = host_session_id
+        result = pm.launch_session(str(project))
+        if result.get("launched"):
+            return "launched"
+        return f"failed: {result.get('error', '')}".strip()
+    except Exception as exc:
+        log_hook_error("hook_session_open", exc)
+        return "error"
+
+
+def run(payload: dict, project_path: Path | None = None):
+    """Core logic — importable by the dispatcher and tests. Returns None."""
+    start_source = str(payload.get("source") or "").strip().lower()
+    if start_source in _SILENT_SOURCES:
+        return None
+    project = find_project(payload, project_path)
+    if project is None:
+        return None
+    host = detect_host(payload)
+    host_sid = str(payload.get("session_id") or "").strip()
+    try:
+        from services.activity_log import ActivityLog
+        ActivityLog(str(project)).log("session_open", {
+            "host_session_id": host_sid,
+            "source": host,
+            "start_source": start_source,
+        })
+    except Exception as exc:
+        log_hook_error("hook_session_open", exc)
+    try:
+        from services.notifications import notify
+        notify(project, agent="session", severity="info",
+               title=f"Session started {short_id(host_sid)}",
+               message=(f"{host} session {host_sid or '?'} started"
+                        + (f" ({start_source})" if start_source else "")),
+               kind="session", ref_id=host_sid)
+    except Exception:
+        pass
+    ensure_ui(project, host_sid)
+    return None
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except Exception as exc:
+        log_hook_error("hook_session_open", exc)
+        sys.exit(0)
+    try:
+        run(data)
+    except Exception as exc:
+        log_hook_error("hook_session_open", exc)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

{code_context_control-2.127.0 → code_context_control-2.128.1}/cli/hub_server.py

@@ -29,6 +29,7 @@ from flask import Flask, jsonify, redirect, request, send_from_directory
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
+from cli._hook_utils import hook_command_arg
 from core.ide import PROFILES, detect_ide, get_profile, load_ide_config, normalize_ide_name
 from services import access_guard
 from services.activity_log import ActivityLog
@@ -71,8 +72,14 @@ _HUB_CONFIG_DEFAULTS = {
     "projects_view": "list",
     "main_view": "projects",
     "oracle_url": "",
+    # Minutes of project silence, with no session heartbeat left, before a UI
+    # server that an IDE session launched is stopped. 0 = never reap.
+    "ui_reap_minutes": 30,
 }
 
+# How often the hub reaps orphaned UI servers and chases autostart projects.
+_UI_SWEEP_INTERVAL_S = 60
+
 
 def _read_hub_config() -> dict:
     cfg = dict(_HUB_CONFIG_DEFAULTS)
@@ -4373,28 +4380,168 @@ def method_not_allowed(e):
 
 # ─── Hook migration ──────────────────────────────────────────────────────────
 
-def _migrate_project_hooks():
-    """Idempotently add new C3 hooks to all registered projects' Claude and Gemini settings.
+def _has_matcher(value: str):
+    return lambda entries: any(e.get("matcher") == value for e in entries)
+
+
+def _has_command(fragment: str):
+    return lambda entries: any(
+        fragment in (hk.get("command") or "")
+        for e in entries
+        for hk in e.get("hooks", [])
+    )
+
+
+def c3_hook_migrations(cli_dir: Path | None = None) -> list:
+    """C3's own hook entries, per settings file and hook event.
+
+    Adding a hook to the installer (``cli/c3.py``) does NOT reach a project
+    that is already installed. The v2.126.0 SessionStart / SessionEnd entries
+    landed in the installer only, so every existing project kept writing no
+    ``session_open`` / ``session_end`` rows at all — 60 projects on the
+    machine this was found on, including C3's own. This table is how they
+    catch up: the hub applies it at startup, additively and idempotently.
 
-    Runs at hub startup so that existing projects pick up hook changes
-    without requiring a manual 'c3 mcp install' on each project.
+    ``present`` decides "C3's entry for this event is already here", so a
+    re-run is a no-op and a user's own entries for the same event survive.
     """
-    cli_dir = Path(__file__).parent
-    hook_c3read_cmd = (
-        f"{shlex.quote(sys.executable)} "
-        f"{shlex.quote(str(cli_dir / 'hook_c3read.py'))}"
+    cli_dir = cli_dir or Path(__file__).parent
+    # hook_command_arg, not shlex.quote: on Windows the latter writes a
+    # single-quoted backslash path that cmd.exe does not unquote, so every
+    # command this table produced for a path with a space — every path under
+    # "1. Projects", say — was dead on arrival. The installer has used the
+    # double-quoted forward-slash form since 2026-07-26; this now matches it.
+    dispatch = (
+        f"{hook_command_arg(sys.executable)} "
+        f"{hook_command_arg(str(cli_dir / 'hook_dispatch.py'))}"
     )
-    new_hook = {
+    c3read_entry = {
         "matcher": "mcp__c3__c3_read",
-        "hooks": [{"type": "command", "command": hook_c3read_cmd}],
+        "hooks": [{
+            "type": "command",
+            "command": (f"{hook_command_arg(sys.executable)} "
+                        f"{hook_command_arg(str(cli_dir / 'hook_c3read.py'))}"),
+        }],
     }
+    c3read_present = _has_matcher("mcp__c3__c3_read")
+    dispatch_present = _has_command("hook_dispatch.py")
+
+    def _lifecycle(event: str, arg: str) -> dict:
+        return {
+            "settings": ".claude/settings.local.json",
+            "event": event,
+            "present": dispatch_present,
+            "entry": {"matcher": "",
+                      "hooks": [{"type": "command",
+                                 "command": f"{dispatch} {arg}"}]},
+        }
 
-    # (settings_path, hook_event) pairs to check per project
-    _HOOK_TARGETS = [
-        (".claude/settings.local.json", "PostToolUse"),
-        (".gemini/settings.json", "AfterTool"),
+    return [
+        {"settings": ".claude/settings.local.json", "event": "PostToolUse",
+         "present": c3read_present, "entry": c3read_entry},
+        {"settings": ".gemini/settings.json", "event": "AfterTool",
+         "present": c3read_present, "entry": c3read_entry},
+        # Claude only — Gemini has no session-lifecycle event to hang these on.
+        _lifecycle("SessionStart", "start"),
+        _lifecycle("SessionEnd", "end"),
     ]
 
+
+def _command_cli_dir(command: str) -> Path | None:
+    """The C3 ``cli/`` directory a hook command points at, if any."""
+    try:
+        tokens = shlex.split(str(command or ""), posix=False)
+    except ValueError:
+        tokens = str(command or "").split()
+    for token in tokens:
+        token = token.strip("'\"")
+        if not token.endswith(".py"):
+            continue
+        candidate = Path(token)
+        if not candidate.name.startswith("hook_"):
+            continue
+        parent = candidate.parent
+        if (parent / "hook_dispatch.py").is_file():
+            return parent
+    return None
+
+
+def detect_project_cli_dir(path: str) -> Path | None:
+    """The ``cli/`` directory this project's existing C3 hooks already use.
+
+    The hub runs from wherever C3 is installed, so building commands from its
+    own location writes install paths into a project that was installed from a
+    checkout — C3's own repo above all, where the working tree IS the runtime.
+    A hook edited there would then change nothing until the next install. Match
+    what the project already points at; the caller falls back to ours.
+    """
+    for rel_settings in (".claude/settings.local.json", ".gemini/settings.json"):
+        settings_path = Path(path) / rel_settings
+        if not settings_path.exists():
+            continue
+        try:
+            with open(settings_path, encoding="utf-8") as f:
+                hooks = (json.load(f).get("hooks") or {})
+        except Exception:
+            continue
+        for entries in hooks.values():
+            for entry in entries or []:
+                for hook in (entry or {}).get("hooks", []):
+                    found = _command_cli_dir((hook or {}).get("command") or "")
+                    if found is not None:
+                        return found
+    return None
+
+
+def migrate_hooks_for_project(path: str, migrations: list | None = None) -> int:
+    """Apply the hook table to one project. Returns settings files changed.
+
+    Never creates a settings file that is not already there: a project with no
+    ``.claude/settings.local.json`` has not been installed for Claude, and the
+    hub is not the place to decide that it should be.
+    """
+    if migrations is None:
+        migrations = c3_hook_migrations(detect_project_cli_dir(path))
+    by_file: dict = {}
+    for migration in migrations:
+        by_file.setdefault(migration["settings"], []).append(migration)
+
+    changed_files = 0
+    for rel_settings, items in by_file.items():
+        settings_path = Path(path) / rel_settings
+        if not settings_path.exists():
+            continue
+        try:
+            with open(settings_path, encoding="utf-8") as f:
+                settings = json.load(f)
+        except Exception:
+            continue
+        changed = False
+        for migration in items:
+            event = migration["event"]
+            existing = list(settings.get("hooks", {}).get(event, []))
+            if migration["present"](existing):
+                continue
+            existing.append(migration["entry"])
+            settings.setdefault("hooks", {})[event] = existing
+            changed = True
+        if not changed:
+            continue
+        try:
+            with open(settings_path, "w", encoding="utf-8") as f:
+                json.dump(settings, f, indent=2)
+            changed_files += 1
+        except Exception:
+            pass
+    return changed_files
+
+
+def _migrate_project_hooks():
+    """Idempotently add missing C3 hooks to every registered project.
+
+    Runs at hub startup so existing projects pick up hook changes without a
+    manual 'c3 install-mcp' per project.
+    """
     try:
         projects = _pm().list_projects()
     except Exception:
@@ -4405,32 +4552,13 @@ def _migrate_project_hooks():
         path = p.get("path", "")
         if not path:
             continue
-        for rel_settings, hook_event in _HOOK_TARGETS:
-            settings_path = Path(path) / rel_settings
-            if not settings_path.exists():
-                continue
-            try:
-                with open(settings_path, encoding="utf-8") as f:
-                    settings = json.load(f)
-            except Exception:
-                continue
-
-            existing = settings.get("hooks", {}).get(hook_event, [])
-            if any(h.get("matcher") == "mcp__c3__c3_read" for h in existing):
-                continue  # already present — skip
-
-            existing.append(new_hook)
-            settings.setdefault("hooks", {})[hook_event] = existing
-            try:
-                with open(settings_path, "w", encoding="utf-8") as f:
-                    json.dump(settings, f, indent=2)
-                updated += 1
-            except Exception:
-                pass
+        # No shared table: each project's entries are built against the cli_dir
+        # that project's existing C3 hooks already point at.
+        updated += migrate_hooks_for_project(path)
 
     if updated:
         logging.getLogger(__name__).info(
-            "[c3] Migrated hook_c3read to %d project settings file(s)", updated
+            "[c3] Migrated C3 hooks into %d project settings file(s)", updated
         )
 
 
@@ -4478,21 +4606,39 @@ def run_hub(
         pass
     _migrate_project_hooks()
 
-    # Auto-launch UI servers for projects with autostart_ui=True
-    def _autostart_ui_servers():
+    # Periodic UI sweep. Before 2.128 this ran ONCE, two seconds after
+    # startup, over autostart_ui projects — so a project whose session started
+    # after the hub (the normal case), or whose UI died mid-session, never got
+    # one. Now it also reaps the session-owned servers whose session is gone.
+    def _ui_sweep_loop():
         import time
         time.sleep(2)  # Give Flask a moment to bind
-        try:
-            pm = _pm()
-            for proj_path in pm.get_autostart_projects():
-                try:
-                    pm.launch_session(proj_path)
-                except Exception:
-                    pass
-        except Exception:
-            pass
+        first_pass = True
+        while True:
+            try:
+                pm = _pm()
+                pm.sweep_registry()
+                wanted = set(pm.get_autostart_projects())
+                if wanted:
+                    for proj in pm.list_projects():
+                        if proj.get("path") not in wanted or proj.get("ui_active"):
+                            continue
+                        # First pass keeps the old contract ("autostart launches
+                        # the UI when the hub starts"); later passes only chase
+                        # projects that actually have a live session.
+                        if not (first_pass or proj.get("session_active")):
+                            continue
+                        try:
+                            pm.launch_session(proj["path"])
+                        except Exception:
+                            pass
+            except Exception:
+                pass
+            first_pass = False
+            time.sleep(_UI_SWEEP_INTERVAL_S)
 
-    threading.Thread(target=_autostart_ui_servers, daemon=True).start()
+    threading.Thread(target=_ui_sweep_loop, daemon=True,
+                     name="c3-hub-ui-sweep").start()
 
     bind_host = str(cfg.get("host", "127.0.0.1") or "127.0.0.1").strip()
     if bind_host not in ("127.0.0.1", "localhost", "::1") and not quiet:

{code_context_control-2.127.0 → code_context_control-2.128.1}/cli/hub_ui/components/project_card.js

@@ -493,7 +493,12 @@ function ProjectCard({ p, isChild, rollup, expanded, onToggleExpand, onChanged,
     } catch (err) { notify('IDE: ' + err.message, 'err'); }
   };
 
-  const portLabel = p.port ? `:${p.port}` : (p.session_active ? 'MCP' : '—');
+  // session_count > 1 = two IDEs / a repo and its worktrees on one project.
+  const sessionCount = p.session_count || (p.session_active ? 1 : 0);
+  const mcpLabel = sessionCount > 1 ? `MCP×${sessionCount}` : 'MCP';
+  const portLabel = p.port
+    ? (sessionCount > 1 ? `:${p.port} · ${mcpLabel}` : `:${p.port}`)
+    : (p.session_active ? mcpLabel : '—');
   const metaText = `${ideLabel(p.ide)} · ${portLabel} · ${p.last_session ? timeAgo(p.last_session) : 'never'}`;
 
   const identity = (

{code_context_control-2.127.0 → code_context_control-2.128.1}/cli/mcp_server.py

@@ -321,6 +321,33 @@ async def lifespan(server):
             **({"host_session_id": _host_sid} if _host_sid else {}),
         })
 
+    # Liveness heartbeat: THIS process is the session, so say so in a file a
+    # reader can trust. Without it the hub has to infer liveness from tool
+    # activity, which calls a quiet-but-open session dead after 20 min and a
+    # closed one live for 20 min. Refreshed on a 60 s daemon thread (same
+    # shape as _bg_convo_sync) and removed in the finally block below.
+    _heartbeat_stop = threading.Event()
+    _live_session_id = str((services.session_mgr.current_session or {}).get("id") or "")
+    if _live_session_id:
+        from services import session_live
+
+        def _do_beat():
+            session_live.beat(services.project_path, _live_session_id,
+                              host_session_id=_host_session_id(services) or "",
+                              ide=_IDE_NAME)
+
+        _do_beat()
+
+        def _bg_heartbeat():
+            while not _heartbeat_stop.wait(timeout=session_live.HEARTBEAT_INTERVAL_S):
+                try:
+                    _do_beat()
+                except Exception:
+                    pass
+
+        threading.Thread(target=_bg_heartbeat, daemon=True,
+                         name="c3-session-heartbeat").start()
+
     # Auto-restore latest snapshot if recent (< 30 min).
     # Deferred to background thread so first tool call isn't blocked.
     # Skipped in benchmark mode to prevent snapshot budget from carrying over between tasks.
@@ -391,6 +418,15 @@ async def lifespan(server):
         yield services
     finally:
         _convo_sync_stop.set()
+        # Stop claiming to be alive before anything slow runs: a reader that
+        # polls during teardown should already see this session as gone.
+        _heartbeat_stop.set()
+        if _live_session_id:
+            try:
+                from services import session_live as _sl
+                _sl.clear(services.project_path, _live_session_id)
+            except Exception:
+                pass
         # Auto-memory: extract remaining learnings and generate session summary.
         if hasattr(services, "auto_memory"):
             try: