diff --git a/CLAUDE.md b/CLAUDE.md
index 5451007..6c34089 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -96,7 +96,7 @@ The workflow:
 
 ### APIs Connected
 
-The server connects to the Molecule AI platform REST API. See the platform SDK (`../molecule-sdk-python`) for the underlying API client used.
+The server connects to the Molecule AI platform REST API via its own TypeScript client (`src/api.ts`). It does not use the Python SDK (`molecule-sdk-python`) — the Python SDK is for remote agents that run outside the platform; this server runs as an MCP bridge *on* the operator side.
 
 ### Environment Variables
 
@@ -110,7 +110,7 @@ For local development, copy `.env.example` → `.env` and fill in values.
 
 ### Postgres
 
-Platform data lives in Postgres (source of truth). The server reads data via the platform SDK — it does not connect to Postgres directly.
+Platform data lives in Postgres (source of truth). The server reads data via the platform REST API — it does not connect to Postgres directly.
 
 ## TypeScript Conventions
 
diff --git a/known-issues.md b/known-issues.md
index 5958fbe..96fb27e 100644
--- a/known-issues.md
+++ b/known-issues.md
@@ -180,21 +180,21 @@ test documenting the known `optional().nullable()` zod-to-json-schema quirk.
 ## KI-007 — MCP server heartbeat tools are read-only; actual heartbeat lives in the Python SDK
 
 **File:** `src/tools/remote_agents.ts` (heartbeat tool)
-**Status:** Resolved — clarified scope
+**Status:** ✅ Resolved
 **Severity:** Low
 
-### Clarification
+### Resolution
 The MCP server's remote-agent tools (`list_remote_agents`, `get_remote_agent_state`,
 `check_remote_agent_freshness`, `get_remote_agent_setup_command`) are **read-only
 queries** — they do not drive any background heartbeat loop. The actual
-`run_heartbeat_loop()` that sends heartbeats from a remote agent lives in the
-Python SDK (`molecule_sdk_python/molecule_agent/client.py`).
+`run_heartbeat_loop()` lives in the Python SDK's `molecule_agent/client.py`
+(standalone `molecule-sdk-python` repo).
 
 The heartbeat cleanup issue (heartbeat loop continues after the controlling MCP
-client disconnects) is tracked as **SDK KI-009** in `molecule-sdk-python/known-issues.md`.
-
-### Suggested fix (SDK side)
-Expose a `stop_event` parameter or `stop()` method on `RemoteAgentClient` so the
-callers (MCP client, shell wrapper) can signal the loop to exit cleanly. The
-Python SDK's `run_heartbeat_loop()` should check `threading.Event` or accept a
-`stop_on: asyncio.Event` argument. See `molecule-sdk-python/known-issues.md`.
\ No newline at end of file
+client disconnects) was tracked as **SDK KI-009**. It has been resolved:
+`RemoteAgentClient.run_heartbeat_loop()` and `run_agent_loop()` now accept a
+`stop_event: threading.Event | None` parameter. Callers signal clean shutdown by
+calling `stop_event.set()` from a SIGTERM handler or another thread. The loop
+checks the event at the start of each iteration (before `max_iterations`) and
+exits with return value `"stopped"`. See `molecule-sdk-python`'s
+`known-issues.md` (KI-009 resolved) and `molecule_agent/__init__.py` for usage.
\ No newline at end of file