SYS GOLDFISH

Updated 3 weeks ago
╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║   G O L D F I S H   P R O T O C O L                                          ║
║   ◬ S C R E E N   C A P T U R E   +   K I N G D O M   H E R A L D           ║
║                                                                              ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  STATUS: LIVE — Goldfish v2, 6 stages live                                   ║
║  VERIFIED: 2026-03-06 (S166 — moondream→llava confirmed)                    ║
╚══════════════════════════════════════════════════════════════════════════════╝
⫷✦🜛❂⛬🜞Ω🜚⛬❂🜛✦⫸───────────────────────────────────────────⫷✦🜛❂⛬🜞Ω🜚⛬❂🜛✦⫸
 WHAT IT DOES: Goldfish v2. Captures a screenshot every 5 min → osascript
               (zero-hallucination ground truth) + llava:latest (grounded vision)
               → Gemini Flash REST API for one Kingdom Herald sentence → appends
               both to daily log → deletes screenshot → updates
               `AERIS_SHARED_STATE.json` sensor_snapshot fields.
               Screenshot-backup daemon (fswatch→llava) logs CleanShot captures.
               Project: `FORGE_CLAUDE/04_📦_PROJECTS/GOLDFISH_V2/`
────────────────────────────────────────────────────────────────────────────────

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SYSTEM GLYPH
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  GLYPH:        ◬
  UNICODE:      U+25EC · WHITE UP-POINTING TRIANGLE WITH DOT
  MEANING:      Viewfinder snapshot — GOLDFISH captures the screen moment
  WHEN TO USE:  SYS docs, cockpit sensor panel headers, KID tags for
                Goldfish artifacts and digest files
  TAGGING:      KID:FORGE:GOLDFISH:[artifact]|V:STATUS:DATE:OWNER


▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
[ ⚡ ] A R C H I T E C T U R E
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

```
launchd (every 5 min)
  └── ping_hub.sh run goldfish
        └── goldfish.sh
              ├── screencapture -x -t jpg /tmp/forge-goldfish-$$.jpg
              ├── osascript → window titles + app list (zero-hallucination ground truth)
              ├── python3 (inline) → POST http://localhost:11434/api/generate
              │     model: llava:latest → 2-sentence grounded screen description
              ├── rm -f /tmp/forge-goldfish-$$.jpg   ← deleted immediately
              ├── printf '### HH:MM\n<description>\n' >> ~/.forge-sensor/goldfish/YYYY-MM-DD.md
              ├── sqlite3 overmind.db → active missions (top 3, P1 first) + FIRES count
              ├── python3 (inline) → POST Gemini Flash REST API
              │     → 1-sentence Kingdom Herald (≤30 words, ≤60 tokens)
              ├── printf '[HERALD] <sentence>\n\n' >> daily log
              └── python3 (inline) → update AERIS_SHARED_STATE.json sensor_snapshot

launchd (9am / noon / 3pm / 6pm / 9pm)
  └── ping_hub.sh run goldfish-digest
        └── goldfish-digest.sh
              ├── reads last 36 entries from daily log (~3 hours)
              └── Gemini Flash REST API → 3-4 sentence narrative → ~/.forge-sensor/digests/YYYY-MM-DD.md
```


░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
[ ❖ ] K E Y   P A T H S
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

| Component | Path |
|-----------|------|
| Main script | `~/.forge-sensor/scripts/goldfish.sh` |
| Digest script | `~/.forge-sensor/scripts/goldfish-digest.sh` |
| Daily goldfish logs | `~/.forge-sensor/goldfish/YYYY-MM-DD.md` |
| Daily digest logs | `~/.forge-sensor/digests/YYYY-MM-DD.md` |
| Shared state (Aeris) | `~/Desktop/THE_FORGE/AExGO/00_🜍_CORE/AERIS_SHARED_STATE.json` |
| Overmind DB | `~/Desktop/THE_FORGE/FORGE_CLAUDE/04_⚙_MECHANISMS/db/overmind.db` |
| Goldfish plist | `~/Library/LaunchAgents/com.forge.ping.goldfish.plist` |
| Digest plist | `~/Library/LaunchAgents/com.forge.ping.goldfish-digest.plist` |
| Ping hub logs | `~/.forge-ping/logs/goldfish.{log,err}` |
| Temp screenshot | `/tmp/forge-goldfish-$$.jpg` (ephemeral — deleted immediately after moondream reads it) |


▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
[ 🜄 ] L O G   F O R M A T
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒

Each entry in `~/.forge-sensor/goldfish/YYYY-MM-DD.md`:

```
### 16:34
The user is actively working in a terminal...
[HERALD] The Sinner King pokes at the Forge's own nervous system while missions wait.

### 20:18
[capture failed]

```

When `[capture failed]` appears: screencapture exited non-zero (TCC denied). Script continues via `|| true`, Python block catches missing file, writes `[capture failed]`.


▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
[ 🜏 ] K I N G D O M   H E R A L D   V O I C E
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄

Herald = second Gemini Flash call per capture. Receives: moondream description, top 3 active missions from DB, FIRES count (pings with `consecutive_failures >= 2`), hour of day.

- **Identity:** "The Kingdom Herald — the chronicler of the Sinner King." Third person. Dry. Observational. Affectionate. Slightly judgy. Never prescriptive. One sentence, 30 words max.
- **API:** `gemini-2.0-flash:generateContent` via REST. `maxOutputTokens: 60`, `temperature: 0.85`.
- Skipped silently if `GEMINI_API_KEY` unset or DB unavailable.

**Live examples:**
- *"YouTube: 22 minutes. M002 remains untouched. The Kingdom endures."*
- *"Hour three. Eleven files modified. Nothing has shipped. Everything has been considered."*


▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
[ ⌁ ] G O L D F I S H   D I G E S T
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

Runs 5x daily. Reads last 36 non-header, non-HERALD lines (~3 hours). Sends to Gemini Flash with warm journalistic prompt. Output: 3-4 sentences starting with time-of-day context ("this morning", "this evening"...), using "Brandon" as subject. Appended to `~/.forge-sensor/digests/YYYY-MM-DD.md`.


░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
[ ⛬ ] L A U N C H D   D A E M O N S
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

| Label | Trigger | Purpose |
|-------|---------|---------|
| `com.forge.ping.goldfish` | Every 300s | `ping_hub.sh run goldfish` → goldfish.sh |
| `com.forge.ping.goldfish-digest` | 9am, noon, 3pm, 6pm, 9pm | `ping_hub.sh run goldfish-digest` → goldfish-digest.sh |

`RunAtLoad=false` on both. Logs in `~/.forge-ping/logs/`. DB tracking: 45s timeout (goldfish), 120s (digest). Both at 0 consecutive failures as of 2026-02-22.


▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
[ 🜍 ] H O W   I T   F E E D S   A E R I S
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒

goldfish.sh writes to `sensor_snapshot` in `AERIS_SHARED_STATE.json` after each run:

| Field | Content |
|-------|---------|
| `updated_at` | ISO UTC timestamp |
| `goldfish_last` | Last 2 lines of moondream text from today's log |
| `goldfish_herald` | Most recent `[HERALD]` line (prefix stripped) |
| `goldfish_count_today` | Count of `### HH:MM` entries in today's log |
| `git_last_commit` | `git log --oneline -1` on THE_FORGE repo |

pulse.sh includes `AERIS_SHARED_STATE.json` in its preamble on every tick → Aeris sees screen activity in working memory.

**SCRYER Phase 2 connection:** `~/.forge-sensor/goldfish/YYYY-MM-DD.md` and `digests/YYYY-MM-DD.md` are primary input to the Isabelle System nightly synthesis (`yesterday-context.md`).


▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
[ 🜂 ] C O M M O N   C O M M A N D S
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄

```bash
# Manual run
bash ~/.forge-sensor/scripts/goldfish.sh

# Run via ping_hub (same as launchd)
bash ~/Desktop/THE_FORGE/FORGE_CLAUDE/04_⚙_MECHANISMS/core/ping_hub.sh run goldfish

# View today's log
cat ~/.forge-sensor/goldfish/$(date +%Y-%m-%d).md

# Last Herald
grep '^\[HERALD\]' ~/.forge-sensor/goldfish/$(date +%Y-%m-%d).md | tail -1

# Count captures / failures today
grep -c '^### ' ~/.forge-sensor/goldfish/$(date +%Y-%m-%d).md
grep -c '\[capture failed\]' ~/.forge-sensor/goldfish/$(date +%Y-%m-%d).md

# Check ollama + moondream
curl -s http://localhost:11434/api/tags | python3 -c "import sys,json; [print(m['name']) for m in json.load(sys.stdin)['models']]"

# Check sensor_snapshot
python3 -c "import json; s=json.load(open('$HOME/Desktop/THE_FORGE/AExGO/00_🜍_CORE/AERIS_SHARED_STATE.json')); print(json.dumps(s.get('sensor_snapshot',{}), indent=2))"

# View today's digest
cat ~/.forge-sensor/digests/$(date +%Y-%m-%d).md

# Daemon status
launchctl list | grep goldfish
tail -20 ~/.forge-ping/logs/goldfish.err
```


════════════════════════════════════════════════════════════════════════════════
[ 🝓 ] G O T C H A S
════════════════════════════════════════════════════════════════════════════════

- **TCC screencapture permission:** Terminal needs Screen Recording permission in System Settings → Privacy → Screen Recording. **⚠️ GOLDFISH OOS since 2026-03-13** — TCC revoked. `~/.forge-scryer/goldfish.oos` sentinel created to suppress GOLDFISH_HEARTBEAT alerts from scryer-watcher.sh. To restore: (1) System Settings → Privacy → Screen Recording → grant `/bin/bash`, (2) `rm ~/.forge-scryer/goldfish.oos`, (3) verify with `bash ~/.forge-sensor/scripts/goldfish.sh`. v2 uses osascript as primary (zero-hallucination ground truth) which has separate TCC handling. If capture fails, logs `[capture failed]`. Python path in plists: always `/opt/homebrew/bin/python3` (TCC fix S155).
- **`|| true` fix (historical):** Was `|| exit 0` — silently succeeded without writing anything. Changed to `|| true` so Python block handles missing file gracefully.
- **ollama must be running.** goldfish.sh calls `http://localhost:11434/api/generate`. If down, writes `[ollama error: ...]` to log. No crash. Check: `launchctl list | grep ollama`.
- **llava:latest must be pulled (v2).** `ollama pull llava:latest`. Verify: `ollama list`. v2 replaced moondream:1.8b with llava for grounded vision. osascript provides zero-hallucination baseline.
- **Gemini Flash uses REST, not CLI.** `GEMINI_API_KEY` must be in `~/.zshenv` (sourced at line 10 of script). If absent, Herald block skipped entirely.
- **Screenshot is ephemeral by design.** `/tmp/forge-goldfish-$$.jpg` deleted immediately. No images retained. ~1KB/day text output only.
- **Digest excludes HERALD lines.** `goldfish-digest.sh` filters `grep -v '^\[HERALD\]'`. Digest only sees raw moondream text.
- **ping_hub.sh is the real scheduler.** launchd calls `ping_hub.sh run goldfish`, not `goldfish.sh` directly. ping_hub handles DB logging, timeout (45s), and failure tracking.
- **`set -uo pipefail` guards.** `|| true` guards on sqlite3 calls and Aeris state update block.

▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
🜚 SYS_GOLDFISH // THE FORGE // ⛬⚚⛬ THE LAW STANDS.
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
← Back to Kingdom Wiki