docs: add git watcher script task + update engineer_states schema

- PLAN.md: add task 2b — scripts/podman-agent.mjs writes git signals directly to MongoDB (changedFiles, diffStat, branch, recentCommit) every 15s; Hermes reads merged vision+git state for event detection - mongodb.md: extend engineer_states with git fields, document two-writer upsert pattern (vision fields vs git fields, no conflict) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FFbfi4Cmb7BY75Wtne7bZn
2026-06-27 15:39:08 -07:00
parent 3fc19194f2
commit 9ad65331c3
2 changed files with 51 additions and 11 deletions
@@ -28,7 +28,7 @@ Engineers join a LiveKit room with earbuds. Each engineer's browser PWA captures
 ---

 ### 2. PWA frame capture
-**Owner:** Zander | **Est:** 1.5h | **Depends on:** task 1 stub
+**Owner:** Shakthi | **Est:** 1.5h | **Depends on:** task 1 stub

 - [ ] After joining pod, start capture loop: `setInterval` every 30s
 - [ ] `getDisplayMedia` already running — grab frame from existing screen track via `ImageBitmap` → `OffscreenCanvas` → `toBlob('image/jpeg', 0.7)`
@@ -40,6 +40,32 @@ Engineers join a LiveKit room with earbuds. Each engineer's browser PWA captures

 ---

+### 2b. Local git watcher script
+**Owner:** Ramis | **Est:** 1.5h | **Depends on:** task 1, task 3 (schema)
+
+A tiny Node.js script each engineer runs once in a terminal on their machine. Writes git signals **directly to MongoDB Atlas** every 15s — no HTTP to Hermes. Hermes reads merged state (vision + git) from Atlas when running event detection.
+
+- [ ] `scripts/podman-agent.mjs` — CLI script, no extra dependencies beyond Node.js + `mongodb` driver
+- [ ] Args: `--name alice --pod demo-pod` (reads `MONGODB_URI` from env or `.env` in repo root)
+- [ ] Every 15s: shell out to `git status --short`, `git diff --stat HEAD`, `git log --oneline -1`, `git branch --show-current`
+- [ ] Upsert into `engineer_states` (same collection as vision pipeline) — update only git fields, leave vision fields untouched:
+  ```ts
+  { $set: { changedFiles, diffStat, recentCommit, branch, gitUpdatedAt } }
+  ```
+- [ ] On startup: log `[podman-agent] alice connected to demo-pod — watching git every 15s`
+- [ ] Graceful exit on Ctrl+C
+
+**Usage:**
+```bash
+node scripts/podman-agent.mjs --name alice --pod demo-pod
+```
+
+**Why MongoDB-direct (not POST /ingest):** git signals and vision signals update at different rates and from different sources. MongoDB is the shared state bus — Hermes reads merged state, not two separate streams.
+
+**Files:** `scripts/podman-agent.mjs` (new)
+
+---
+
 ### 3. MongoDB state layer
 **Owner:** Karti | **Est:** 1.5h | **Depends on:** task 1

@@ -103,7 +129,7 @@ Highest integration risk — do as a team.
 ---

 ### 7. PWA active session UI
-**Owner:** Zander | **Est:** 1.5h | **Depends on:** tasks 2, 6
+**Owner:** Shakthi | **Est:** 1.5h | **Depends on:** tasks 2, 6

 - [ ] Active session screen (post-join — replace current "Connected" placeholder)
 - [ ] Teammate status cards: name, inferred file, inferred task — polled from backend via `GET /pods/:podId/state` or updated via data channel
@@ -164,7 +190,7 @@ Highest integration risk — do as a team.
 | **Karti** | 1 (env + health), 3 (MongoDB layer), 10 (state endpoint) | ~3–4h |
 | **Ramis** | 4 (Gemini Vision pipeline), part of 2 (capture help) | ~3h |
 | **Yahya** | 5 (event detector + nudge generator), 9 (duplicate work) | ~3h |
-| **Zander** | 2 (PWA frame capture), 7 (active session UI) | ~3h |
+| **Shakthi** | 2 (PWA frame capture), 7 (active session UI) | ~3h |
 | **Everyone** | 6 (Gemini Live + LiveKit Agents voice) | ~2h |

 ---
@@ -8,25 +8,39 @@ MongoDB Atlas is PodMan's shared memory. It stores live engineer state, the owne

 ### `engineer_states`

-Latest context per engineer. Upserted on every successful `/ingest` call.
+Latest context per engineer. Two writers, one collection — vision pipeline upserts vision fields, git watcher script upserts git fields independently. Hermes reads the merged document for event detection.

 ```ts
 {
-  _id: string,                    // engineerId (stable across sessions)
+  _id: string,                       // engineerId (stable across sessions)
  podId: string,
-  name: string,                   // display name
-  currentFile: string | null,     // from Gemini Vision
-  inferredTask: string | null,    // from Gemini Vision
+  name: string,                      // display name
+
+  // --- Vision fields (written by Hermes via POST /ingest) ---
+  currentFile: string | null,        // active file inferred from screen
+  inferredTask: string | null,       // what engineer appears to be doing
  terminalVisible: boolean,
  recentTerminalOutput: string | null,
-  confidence: number,             // last frame confidence (0–1)
-  updatedAt: Date
+  confidence: number,                // Gemini Vision confidence (0–1)
+  visionUpdatedAt: Date,
+
+  // --- Git fields (written directly by scripts/podman-agent.mjs) ---
+  changedFiles: string[],            // files with uncommitted changes (git status)
+  diffStat: string | null,           // e.g. "auth/middleware.ts | 24 +++++"
+  recentCommit: string | null,       // most recent commit message
+  branch: string | null,             // current branch name
+  gitUpdatedAt: Date,
+
+  // --- Shared ---
+  updatedAt: Date                    // most recent write from either source
 }
 ```

 **Index:** `{ podId: 1, updatedAt: -1 }`

-**Usage:** Hermes reads all documents for a given `podId` after each update to run event detection across the full team.
+**Two writers, no conflict:** vision upsert uses `$set` on vision fields only; git upsert uses `$set` on git fields only. MongoDB upsert semantics merge them cleanly.
+
+**Usage:** Hermes reads all documents for a given `podId` after each update to run event detection. Both vision and git context are available in the same document — `changedFiles` provides ground truth, `currentFile` provides screen context.

 ---