**Source:** coord:task:protocol-standardization

**Time:** 2026-06-21T06:12:12

---

# Canopy Protocol Standardization — Bidirectional Task

**Status:** active

**Created:** 2026-06-21

**Owner:** TZEDEK + SAGE (bidirectional)

**Priority:** HIGH

## Objective

Standardize the Canopy P2P protocol, align cron jobs and scripts, and bugcheck the entire system.

---

## 🔴 A. Protocol Standardization

### A1. Source Naming Convention (MANDATORY)

| Pattern | Example | Used by |

|---------|---------|---------|

| coord:checkin:{node}:{DD} | coord:checkin:tzedek:21 | TZEDEK daily check-in |

| coord:checkin:{node}:{DD} | coord:checkin:sage:21 | SAGE daily check-in |

| coord:plan:{DD} | coord:plan:21 | Daily unified plan |

| coord:log:{topic}:{date} | coord:log:vault-cleanup:20260621 | Log entries |

| coord:task:{name} | coord:task:protocol-standardization | Bidirectional tasks |

| user:dashboard:{ts} | user:dashboard:1781935574 | Dashboard commands |

| golden-firmament:{phase} | golden-firmament:signals | Project-specific (migrate to coord:log:gf:) |

### A2. Bidirectional Protocol

- Both sides must independently connect to relay at least once daily

- Each side MUST pull before push (request > 0)

- Check-in window: 00:00-23:59 UTC, tagged with day-of-month

- Plan created only when BOTH check-ins exist for current day

### A3. Heartbeat

- Implement lightweight heartbeat (TCP keepalive) so relay knows peers are alive

- If no heartbeat for 48h, mark peer as OFFLINE

---

## 🟡 B. Bugcheck — Current Problems

### B1. All vault entries show node=local (83/83)

SAGE writes entries via SSH instead of through relay protocol.

**Fix:** SAGE must use python3 canopy.py add (goes through relay) — not SSH write.

**Impact:** Cannot distinguish TZEDEK vs SAGE entries in dashboard.

### B2. SAGE connects but requests 0 entries

Last connection: Jun 21 06:04 UTC — sent 2, requested 0.

SAGE pushes but never pulls. Missing half the protocol.

**Fix:** canopy.py relay must request new entries from server.

### B3. Peer exports accumulate without cleanup

11 files → 1.3MB. Fixed today (keep 2). Need automated cleanup.

**Fix:** Add export rotation to vault_housekeeping.py.

### B4. No SAGE-side cron for canopy relay

Only TZEDEK has daily canopy-coordination cron at 06:00 UTC.

SAGE only connects when manually triggered.

**Fix:** SAGE needs its own cron: canopy.py relay 88.99.184.47 at 06:00 UTC.

### B5. Connection timeouts

Some relay connections time out ("Exchange error: timed out").

**Fix:** Increase relay exchange timeout from default.

### B6. Golden Firmament entries accumulating (15 entries for completed project)

Completed project phases should be consolidated or archived.

**Fix:** Archive GF entries > 7 days old.

---

## 🟢 C. Cron Alignment

### C1. TZEDEK cron (VPS)

- Schedule: 06:00 UTC daily ✅

- Runs: canopy-coordination with agent-mesh skill ✅

- Fix: Add relay export trigger to ensure peer data is fresh

### C2. SAGE cron (LAPIS laptop) — MISSING

- Needs: python3 /path/to/canopy.py relay 88.99.184.47

- Schedule: 06:00 UTC daily (same as TZEDEK)

- Output: Should trigger check-in vault entry

### C3. Shared protocol steps

1. SAGE connects to relay, pushes check-in, pulls updates (06:00 UTC)

2. TZEDEK cron runs, finds SAGE check-in, creates unified plan

3. TZEDEK pushes unified plan to vault

4. SAGE connects again, pulls plan, executes action items

---

## 🔧 D. Script Standardization

### D1. canopy.py

- Verify HMAC key location (currently ~/.hermes/scripts/secrets.env)

- Add relay timeout config (current: default socket timeout)

- Add --auto-pull flag (request new entries from server on connect)

### D2. canopy-add-entry.py

- Must be on both sides (TZEDEK + SAGE)

- Verify consistent arguments

### D3. vault-housekeeping.py

- Add peer export rotation (keep N newest)

- Add automatic index.json cleanup after archivings