← back to Norma

Norma instagram-agent: add RECOVERY.md (deps-location gotcha, auth, durability)

46eb6389fdc0524cada8afff79e719a6d13fbec5 · 2026-07-10 11:35:53 -0700 · Steve Abrams

Documents the shared/node_modules dependency-resolution gotcha the contrarian
flagged: npm install in agents/shared/ (not the agent dir) when non-dotenv deps
go missing. Also records the .env/empty-password trap + reboot durability + the
dw-uptime-probe watchlist follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Files touched

• A agents/instagram-agent/RECOVERY.md

Diff

commit 46eb6389fdc0524cada8afff79e719a6d13fbec5
Author: Steve Abrams <steve@designerwallcoverings.com>
Date:   Fri Jul 10 11:35:53 2026 -0700

    Norma instagram-agent: add RECOVERY.md (deps-location gotcha, auth, durability)
    
    Documents the shared/node_modules dependency-resolution gotcha the contrarian
    flagged: npm install in agents/shared/ (not the agent dir) when non-dotenv deps
    go missing. Also records the .env/empty-password trap + reboot durability + the
    dw-uptime-probe watchlist follow-up.
    
    Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 agents/instagram-agent/RECOVERY.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/agents/instagram-agent/RECOVERY.md b/agents/instagram-agent/RECOVERY.md
new file mode 100644
index 0000000..74a8180
--- /dev/null
+++ b/agents/instagram-agent/RECOVERY.md
@@ -0,0 +1,25 @@
+# Norma instagram-agent — ops / recovery
+
+- **pm2 name:** `norma-instagram`  ·  **port:** `127.0.0.1:9810`  ·  runs in **simulation mode** until `IG_USER_ID` + `IG_ACCESS_TOKEN` are set.
+- **Auth:** Basic auth on every route except `/health`. Creds from `.env` (`AUTH_USERNAME`/`AUTH_PASSWORD`), fleet-standard `admin` / `DW2024!`. `.env` is gitignored — if it's missing, the password silently defaults to **empty string** and `admin`/`DW2024!` will be rejected 403. Recreate `.env` if that happens.
+- **Surfaces:** read-only dashboard at `GET /` (behind auth); JSON API `/api/status`, `/api/audit?limit=N`, `/api/cron/status`, `POST /api/cron/{start,stop}`, `POST /api/skill/{reel,story}`; `GET /health` (no auth). Control skill: `instagram-account-manager`.
+
+## Dependency-recovery gotcha (READ THIS)
+This agent's own `node_modules/` contains **only `dotenv`**. Everything else
+(express, helmet, node-cron, pg, …) resolves from the **shared** base:
+`~/Projects/Norma/agents/shared/node_modules/`.
+
+So if the agent crash-loops on `Cannot find module '<x>'`:
+- `x` is `dotenv` → `npm install` **here** (`agents/instagram-agent/`).
+- `x` is anything else (express/helmet/etc.) → `npm install` in **`agents/shared/`**, NOT here.
+
+`pm2 save` persists *what* to start, not the ability to start — if deps vanish,
+pm2 + fleet-keepalive will crash-loop then silently back off (no alert). If the
+agent shows `errored` in `pm2 ls`, check `pm2 logs norma-instagram --err` for a
+`MODULE_NOT_FOUND` and reinstall in the correct directory per above.
+
+## Reboot durability
+In the pm2 resurrect dump (`pm2 save` done) + watched every 60s by
+`com.steve.fleet-keepalive` (restarts on crash / 5xx / dead port; treats the
+401 auth gate as healthy). **Follow-up worth doing:** add `norma-instagram` to
+the `dw-uptime-probe` watchlist so a silent backoff raises an alert.

← 3dbea14 agent-base: fix route shadowing + server-render status dashb  ·  back to Norma  ·  Norma dashboard: enrich GET / with insights + media grid (ca a1a4ebc →