From 7a2d88a5f5a927f0d0066cb5f82b0666eaeadfdf Mon Sep 17 00:00:00 2001
From: Chris Farhood <chris@farhood.org>
Date: Sun, 15 Mar 2026 09:28:51 -0400
Subject: [PATCH] Update Countess heartbeat with exact Paperclip API calls

PATCH replaces adapterConfig entirely (no merge), so the heartbeat now
specifies an explicit read-merge-write flow to prevent wiping promptTemplate
and secret env values. Includes exact curl commands and safety rules.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 ceo/HEARTBEAT.md | 41 ++++++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/ceo/HEARTBEAT.md b/ceo/HEARTBEAT.md
index e46ab3c..185abc2 100644
--- a/ceo/HEARTBEAT.md
+++ b/ceo/HEARTBEAT.md
@@ -52,30 +52,41 @@ If `LAST_SHA` is empty or equals `CURRENT_SHA`, skip to step 5. Otherwise:
 
 #### 4c. Apply config changes for each affected agent
 
-For each agent whose `CONFIG.md` changed in the diff:
+**CRITICAL: PATCH on the Paperclip API replaces `adapterConfig` entirely — it does NOT merge. You must always read-merge-write.**
 
-1. Read the agent's `CONFIG.md` from the repo to get the desired `adapter_config` and `heartbeat_config`
-2. Read the agent's current live config from the Paperclip API
-3. Apply the update via the Paperclip API
+For each agent whose files changed in the diff:
 
-**CRITICAL — prompt-wipe safety rules:**
+1. Get the agent's ID from their `CONFIG.md` Identity table
+2. Read the agent's current live config:
 
-- **`claude_local` / `gemini_local` agents**: These load prompts from `instructionsFilePath` (which points to `AGENTS.md`). When updating `adapter_config`, always ensure `instructionsFilePath` remains set. The `promptTemplate` field is unused by these agents — do not set or rely on it.
-- **`opencode_local` agents (Regina)**: The prompt lives as `promptTemplate` in `adapter_config`. When updating Regina's config, you MUST:
-  1. Read her current `adapter_config` from the API first
-  2. Preserve the existing `promptTemplate` value in your update payload
-  3. Preserve the existing `env` block (contains `OPENROUTER_API_KEY`) and `model` field — the UI wipes these on save
-  4. Only overwrite `promptTemplate` if her prompt files actually changed (see 4d below)
+        curl -sf -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+          $PAPERCLIP_API_URL/api/agents/{agentId}
 
-#### 4d. Apply prompt changes for opencode_local agents
+3. Read the desired config from the agent's `CONFIG.md` in the repo
+4. **Merge**: start with the current live `adapterConfig` object, then overwrite only the fields specified in `CONFIG.md`. This preserves any live-only fields (like `promptTemplate`).
+5. Write the merged config back:
+
+        curl -sf -X PATCH "$PAPERCLIP_API_URL/api/agents/{agentId}" \
+          -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+          -H "Content-Type: application/json" \
+          -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+          -d '{"adapterConfig": {MERGED_OBJECT}, "runtimeConfig": {"heartbeat": {FROM_CONFIG_MD}}}'
+
+**Safety rules for the merge:**
+
+- ALWAYS preserve the existing `promptTemplate` from the live config unless you are intentionally updating it (see 4d)
+- ALWAYS preserve `env` values that contain secrets (e.g., Regina's `OPENROUTER_API_KEY`) — the repo has redacted placeholders, do NOT overwrite live secrets with redacted values
+- For `claude_local` / `gemini_local` agents: ensure `instructionsFilePath` is always present in the merged config
+
+#### 4d. Apply prompt changes for opencode_local agents (Regina)
 
 If any of Regina's prompt files (`AGENTS.md`, `SOUL.md`, `HEARTBEAT.md`) changed in the diff:
 
 1. Concatenate the contents of her `AGENTS.md` + `SOUL.md` + `HEARTBEAT.md` (in that order)
-2. Update `promptTemplate` in her `adapter_config` via the Paperclip API
-3. Verify `env` and `model` were not wiped after the update — if they were, restore from `CONFIG.md`
+2. In the merge from step 4c, set `promptTemplate` to this concatenated content (this is the one case where you overwrite `promptTemplate`)
+3. After the PATCH, verify `env` and `model` survived by reading the config back
 
-For `claude_local` / `gemini_local` agents: no prompt action needed — they read `AGENTS.md` from disk via `instructionsFilePath` automatically.
+For `claude_local` / `gemini_local` agents: no prompt action needed — they read from disk via `instructionsFilePath` automatically.
 
 #### 4e. Record sync state