Merge pull request #22 from karti-ai/feat/team-memory-dynamic-graph

feat(graph): dynamic force-directed Team-memory graph + learning-loop & activity rails

.env.example

@@ -7,8 +7,11 @@ LIVEKIT_API_SECRET=
 
 # --- Gemini (vision + event detection + voice) ---
 GEMINI_API_KEY=
+# GOOGLE_API_KEY= also works as a local alias, but GEMINI_API_KEY is the
+# canonical deployment secret name used by DigitalOcean and docs.
 GEMINI_VISION_MODEL=gemini-2.0-flash
-GEMINI_LIVE_MODEL=gemini-live-2.5-flash
+GEMINI_LIVE_MODEL=gemini-3.1-flash-tts-preview
+GEMINI_EMBEDDING_MODEL=gemini-embedding-001
 
 # --- GitHub (repo state + sync PR artifacts) ---
 GITHUB_TOKEN=
@@ -33,3 +36,18 @@ VITE_BACKEND_URL=http://localhost:8787
 # --- Deployment verification ---
 # Optional override when the deployed SPA and API use different origins.
 FRONTEND_URL=http://localhost:4173
+
+# --- Hermes operations watchdog ---
+PODMAN_PUBLIC_URL=https://165-22-129-249.sslip.io/
+PODMAN_PUBLIC_API_URL=https://165-22-129-249.sslip.io/api/pods
+PODMAN_PUBLIC_HEALTH_URL=https://165-22-129-249.sslip.io/health
+PODMAN_HERMES_REMEDIATE=1
+PODMAN_HERMES_STRICT=0
+PODMAN_HERMES_STATE_DIR=/var/log/podman
+# Optional Discord/Slack/generic webhook for failed watchdog runs.
+PODMAN_ALERT_WEBHOOK_URL=
+
+# --- Hermes git-sync deploy loop ---
+PODMAN_DEPLOY_REMOTE=origin
+PODMAN_DEPLOY_BRANCH=main
+PODMAN_DEPLOY_RESTART_SERVICES=podman-platform-api.service,podman-platform-agent.service,caddy.service

.github/workflows/hermes-verify.yml

@@ -0,0 +1,23 @@
+name: Hermes verify
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.32.1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm -r typecheck
+      - run: pnpm -r build

backend/src/action/hermes.ts

@@ -0,0 +1,39 @@
+import type { Room } from '@livekit/rtc-node';
+import type { Collision, DataMessage, HermesMessage, Intervention } from '@podman/shared';
+import { DATA_TOPIC } from '@podman/shared';
+
+const encoder = new TextEncoder();
+
+function teammateText(collision: Collision, intervention: Intervention): string {
+  return `${collision.engineers.join(', ')}: ${intervention.message}`;
+}
+
+export function createHermesMessage(
+  collision: Collision,
+  intervention: Intervention,
+): HermesMessage {
+  return {
+    id: `hermes_${Date.now()}`,
+    podId: collision.podId,
+    interventionId: intervention.id,
+    recipients: collision.engineers,
+    text: teammateText(collision, intervention),
+    urgency: collision.severity === 'critical' ? 'urgent' : 'normal',
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export async function publishHermesMessage(
+  room: Room,
+  collision: Collision,
+  intervention: Intervention,
+): Promise<void> {
+  const data: DataMessage = {
+    type: 'HERMES_MESSAGE',
+    message: createHermesMessage(collision, intervention),
+  };
+  await room.localParticipant?.publishData(encoder.encode(JSON.stringify(data)), {
+    reliable: true,
+    topic: DATA_TOPIC,
+  });
+}

backend/src/agent.ts

@@ -14,6 +14,7 @@ import sharp from 'sharp';
 import { AccessToken } from 'livekit-server-sdk';
 import { env } from './env.js';
 import { PodMan } from './agent/podman.js';
+import { initMemory } from './memory/db.js';
 
 const POD_ROOM = process.env.POD_ROOM ?? 'demo-pod';
 const HERMES_IDENTITY = 'podman-hermes';
@@ -30,6 +31,10 @@ async function agentToken(room: string): Promise<string> {
 }
 
 async function main() {
+  // MongoDB is mandatory. Verify the connection before joining the room so bad
+  // creds / unreachable Atlas fail loudly at boot, not silently mid-demo.
+  await initMemory();
+
   const room = new Room();
   const podman = new PodMan(room, POD_ROOM);
   await room.connect(env.LIVEKIT_URL, await agentToken(POD_ROOM), {

backend/src/agent/podman.ts

@@ -4,11 +4,17 @@ import { DATA_TOPIC } from '@podman/shared';
 import { analyzeFrame } from '../vision/gemini.js';
 import { detectCollisions } from '../collision/detector.js';
 import { getGithubState } from '../github/client.js';
-import { recordObservation, recordCollision, recordIntervention } from '../memory/store.js';
+import {
+  recordObservation,
+  recordCollision,
+  recordIntervention,
+  updateInterventionStatus,
+} from '../memory/store.js';
 import { getGitStates } from '../memory/db.js';
 import { recallSimilar } from '../memory/vectors.js';
 import { shouldIntervene, preferredAction } from '../memory/policy.js';
 import { speak } from '../voice/live.js';
+import { publishHermesMessage } from '../action/hermes.js';
 
 export class PodMan {
   private contexts = new Map<string, EngineerContext>();
@@ -29,6 +35,7 @@ export class PodMan {
           if (c)
             c.hasUnpushedChanges = msg.report.unpushedCount > 0 || msg.report.dirtyFiles.length > 0;
         }
+        if (msg.type === 'ACK') void updateInterventionStatus(msg.interventionId, msg.status);
       } catch {
         /* ignore malformed */
       }
@@ -54,7 +61,7 @@ export class PodMan {
   }
 
   private async handle(collision: Collision): Promise<void> {
-    const prior = await recallSimilar(collision); // Loop A: vector recall raises confidence
+    const prior = await recallSimilar(collision); // Loop A: exact/vector recall raises confidence
     if (prior) collision.severity = 'critical';
     if (!shouldIntervene(collision, prior)) return; // Loop B: policy gate
 
@@ -64,7 +71,11 @@ export class PodMan {
     const message =
       `${names} are both editing ${collision.file}` +
       (collision.githubState?.unpushed ? ' and one has unpushed changes.' : '.') +
-      (prior ? ` I've seen this conflict pattern before.` : '');
+      (prior?.priorOutcome?.accepted
+        ? ` I've seen this conflict pattern before; last time the team accepted the ${prior.priorIntervention?.suggestedAction.kind.replaceAll('_', ' ') ?? 'suggested'} action.`
+        : prior
+          ? ` I've seen this conflict pattern before.`
+          : '');
 
     const intervention: Intervention = {
       id: `int_${Date.now()}`,
@@ -72,7 +83,14 @@ export class PodMan {
       podId: this.podId,
       kind: 'card',
       message,
-      suggestedAction: { kind: action },
+      suggestedAction: {
+        kind: action,
+        params: {
+          file: collision.file,
+          summary: message,
+          engineers: collision.engineers,
+        },
+      },
       status: 'pending',
       createdAt: new Date().toISOString(),
     };
@@ -83,6 +101,7 @@ export class PodMan {
       reliable: true,
       topic: DATA_TOPIC,
     });
-    await speak(this.room, message); // gemini-3.1-flash-live voice into the room
+    await publishHermesMessage(this.room, collision, intervention);
+    if (collision.severity === 'critical') await speak(this.room, message);
   }
 }

backend/src/env.ts

@@ -5,6 +5,13 @@ function req(name: string): string {
   if (!v) throw new Error(`Missing required env var: ${name}`);
   return v;
 }
+function reqAny(primary: string, aliases: string[] = []): string {
+  for (const name of [primary, ...aliases]) {
+    const v = process.env[name];
+    if (v) return v;
+  }
+  throw new Error(`Missing required env var: ${primary}`);
+}
 function opt(name: string, fallback = ''): string {
   return process.env[name] ?? fallback;
 }
@@ -15,9 +22,10 @@ export const env = {
   LIVEKIT_API_KEY: req('LIVEKIT_API_KEY'),
   LIVEKIT_API_SECRET: req('LIVEKIT_API_SECRET'),
   // Gemini
-  GEMINI_API_KEY: req('GEMINI_API_KEY'),
+  GEMINI_API_KEY: reqAny('GEMINI_API_KEY', ['GOOGLE_API_KEY', 'GOOGLE_GENERATIVE_AI_API_KEY']),
   GEMINI_VISION_MODEL: opt('GEMINI_VISION_MODEL', 'gemini-2.0-flash'),
-  GEMINI_LIVE_MODEL: opt('GEMINI_LIVE_MODEL', 'gemini-live-2.5-flash'),
+  GEMINI_LIVE_MODEL: opt('GEMINI_LIVE_MODEL', 'gemini-3.1-flash-tts-preview'),
+  GEMINI_EMBEDDING_MODEL: opt('GEMINI_EMBEDDING_MODEL', 'gemini-embedding-001'),
   // GitHub
   GITHUB_TOKEN: req('GITHUB_TOKEN'),
   GITHUB_REPO: req('GITHUB_REPO'), // owner/name
@@ -27,6 +35,7 @@ export const env = {
   VOYAGE_EMBEDDING_MODEL: opt('VOYAGE_EMBEDDING_MODEL', 'voyage-4-lite'),
   // Server
   PORT: Number(opt('PORT', '8787')),
+  NUDGE_COOLDOWN_MS: Number(opt('NUDGE_COOLDOWN_MS', '180000')),
 } as const;
 
 export function repoParts(): { owner: string; repo: string } {

backend/src/github/client.ts

@@ -39,13 +39,45 @@ export async function createSyncPr(input: { headBranch: string; file: string; su
     ref: `refs/heads/${branch}`,
     sha: mainRef.object.sha,
   });
+
+  const artifactPath = `podman-sync-artifacts/${branch}.md`;
+  const body = [
+    '# PodMan Sync Artifact',
+    '',
+    `- File: \`${input.file || 'unknown'}\``,
+    `- Source branch hint: \`${input.headBranch || 'not provided'}\``,
+    `- Created: ${new Date().toISOString()}`,
+    '',
+    '## Coordination Summary',
+    '',
+    input.summary || 'PodMan detected a coordination risk before the relevant work was pushed.',
+    '',
+    '## Suggested Next Step',
+    '',
+    'Coordinate ownership before pushing or merging overlapping local work.',
+    '',
+  ].join('\n');
+
+  await gh.rest.repos.createOrUpdateFileContents({
+    owner,
+    repo,
+    branch,
+    path: artifactPath,
+    message: `PodMan sync artifact for ${input.file || 'active work'}`,
+    content: Buffer.from(body).toString('base64'),
+  });
+
   const { data: pr } = await gh.rest.pulls.create({
     owner,
     repo,
     title: `PodMan: sync ${input.file} before collision`,
     head: branch,
     base: 'main',
-    body: input.summary,
+    body: [
+      input.summary,
+      '',
+      `PodMan created a visible sync artifact at \`${artifactPath}\` so the team can coordinate before pushing overlapping work.`,
+    ].join('\n'),
   });
   return pr;
 }

backend/src/graph/demo.ts

@@ -8,24 +8,62 @@ import type { PodGraph } from '@podman/shared';
  * auth* — is the continual-learning story the demo lights up.
  */
 export function createDemoPodGraph(podId: string): PodGraph {
+  const base = Date.now();
+  const at = (secAgo: number): string => new Date(base - secAgo * 1000).toISOString();
   return {
     podId,
     generatedAt: new Date().toISOString(),
+    loop: [
+      { key: 'observe', title: 'OBSERVE', value: '5', detail: '~5/s vision contexts', active: false },
+      { key: 'store', title: 'STORE', value: '124', detail: 'memory vectors · Atlas', active: false },
+      { key: 'predict', title: 'PREDICT', value: '1', detail: 'open risk path', active: true },
+      { key: 'outcome', title: 'OUTCOME', value: '1/0', detail: 'accepted · dismissed', active: false },
+      { key: 'adapt', title: 'ADAPT', value: '3', detail: 'learned owners', active: false },
+    ],
+    activity: [
+      {
+        id: 'demo-learn',
+        at: at(20),
+        kind: 'learned_from',
+        text: 'Memory updated: Karti owns auth.ts (confidence ↑)',
+      },
+      { id: 'demo-out', at: at(24), kind: 'outcome', text: 'Intervention accepted by the pod' },
+      {
+        id: 'demo-warn',
+        at: at(40),
+        kind: 'warns',
+        text: 'PodMan: "Karti & Yahya are both in auth.ts — open a sync PR?" → card sent',
+      },
+      {
+        id: 'demo-col',
+        at: at(58),
+        kind: 'collision',
+        text: 'Critical overlap on auth.ts · Karti + Yahya',
+      },
+      {
+        id: 'demo-edit',
+        at: at(72),
+        kind: 'editing',
+        text: 'Yahya opened auth.ts — unpushed changes',
+      },
+    ],
+    // Kept consistent with the graph below (3 owner engineers, 1 collision file,
+    // 1 of 1 interventions accepted) so the numbers never contradict the picture.
     metrics: [
       {
         label: 'Learned owners',
-        value: '5',
-        detail: 'Ownership edges retained from accepted interventions.',
+        value: '3',
+        detail: 'Distinct owners retained from accepted interventions.',
       },
       {
         label: 'Open risk paths',
-        value: '2',
-        detail: 'auth.ts and the memory API have converging editors.',
+        value: '1',
+        detail: 'File with two or more converging editors.',
       },
       {
         label: 'Accept rate',
-        value: '86%',
-        detail: 'Interventions accepted this session (+14%).',
+        value: '100%',
+        detail: 'Interventions accepted vs total this session.',
       },
     ],
     nodes: [

backend/src/graph/live.ts

@@ -0,0 +1,637 @@
+import type {
+  PodGraph,
+  PodGraphNode,
+  PodGraphEdge,
+  PodGraphMetric,
+  PodGraphNodeKind,
+  PodGraphEdgeKind,
+  PodGraphNodeStatus,
+  LearningStage,
+  LearningStageKey,
+  ActivityEvent,
+  EngineerContext,
+  Collision,
+  Intervention,
+  InterventionOutcome,
+} from '@podman/shared';
+import { collections, getGitStates, getDb } from '../memory/db.js';
+
+/**
+ * Live materializer: build a pod's continual-learning graph from the real
+ * collections the agent writes (pods, engineer_states, observations, collisions,
+ * interventions, outcomes) — NOT the hardcoded demo. See docs/live-ui-spec.md §1.
+ *
+ * Pure-read and best-effort. Returns `null` when there is no real activity yet
+ * (only bare roster), so `loadPodGraph` can fall back to the demo graph.
+ */
+
+const ACTIVE_WINDOW_MS = 90_000;
+const MAX_OBSERVATIONS = 250;
+
+/** Strip a `git status --short` XY code (and rename `old -> new`) to a clean path. */
+export function parseGitStatusPath(line: string): string {
+  let s = line.trim();
+  const arrow = s.indexOf(' -> ');
+  if (arrow !== -1) s = s.slice(arrow + 4);
+  else s = s.replace(/^[ACDMRTU?!]{1,2}\s+/, '');
+  return normalizeFile(s);
+}
+
+/** Normalize a file path so vision (`collisions.file`) and git paths match. */
+export function normalizeFile(f: string): string {
+  return f
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .replace(/^[ACDMRTU?!]{1,2}\s+/, '')
+    .replace(/^\.\//, '');
+}
+
+const MAX_COLLISIONS = 8;
+
+/** Reject "file" values that aren't real source paths — vision/git noise such as
+ *  URLs, env vars, browser/app names, and scratch/test artifacts. */
+const FILE_NOISE =
+  /(:\/\/|^[#~]|\s|\.env\b|\btett\b|test-change|demo-scratch|podman-test|scratch|sslip)/i;
+export function isFilePath(f: string): boolean {
+  if (!f || FILE_NOISE.test(f)) return false;
+  return /\.[a-z0-9]{1,6}$/i.test(f); // must end in a real file extension
+}
+
+/** Engineer names that are test/verification artifacts, not real teammates. */
+const ENGINEER_NOISE = /(^verify\b|^.$|testrepo|-?check\b|\d{4,})/i;
+
+const MAX_FILES = 9;
+
+/** Short, readable node label — last two path segments (full path goes in summary). */
+function shortLabel(file: string): string {
+  const parts = file.split('/').filter(Boolean);
+  return parts.slice(-2).join('/') || file;
+}
+
+const STATUS_RANK: Record<PodGraphNodeStatus, number> = {
+  stable: 0,
+  active: 1,
+  learned: 2,
+  risk: 3,
+};
+
+interface Builder {
+  nodes: Map<string, PodGraphNode>;
+  edges: Map<string, PodGraphEdge>;
+}
+
+function nodeKey(kind: PodGraphNodeKind, key: string): string {
+  return `${kind}:${key}`;
+}
+
+function upsertNode(
+  b: Builder,
+  kind: PodGraphNodeKind,
+  key: string,
+  patch: Partial<Omit<PodGraphNode, 'id' | 'kind' | 'x' | 'y'>>,
+): string {
+  const id = nodeKey(kind, kind === 'engineer' ? key.toLowerCase() : key);
+  const cur = b.nodes.get(id);
+  if (!cur) {
+    b.nodes.set(id, {
+      id,
+      kind,
+      label: patch.label ?? key,
+      summary: patch.summary ?? '',
+      weight: patch.weight ?? 0.6,
+      status: patch.status ?? 'stable',
+      x: 0,
+      y: 0,
+    });
+    return id;
+  }
+  if (patch.label) cur.label = patch.label;
+  if (patch.summary) cur.summary = patch.summary;
+  if (patch.weight && patch.weight > cur.weight) cur.weight = patch.weight;
+  if (patch.status && STATUS_RANK[patch.status] > STATUS_RANK[cur.status])
+    cur.status = patch.status;
+  return id;
+}
+
+function upsertEdge(
+  b: Builder,
+  source: string,
+  target: string,
+  kind: PodGraphEdgeKind,
+  label: string,
+  strength: number,
+): void {
+  const id = `${kind}:${source}->${target}`;
+  const cur = b.edges.get(id);
+  if (!cur) b.edges.set(id, { id, source, target, kind, label, strength });
+  else if (strength > cur.strength) cur.strength = strength;
+}
+
+const COLUMN_X: Record<PodGraphNodeKind, number> = {
+  engineer: 78,
+  file: 300,
+  feature: 360,
+  collision: 470,
+  intervention: 622,
+};
+
+/** Deterministic column layout so the SVG renders stably across refreshes. */
+function layout(nodes: PodGraphNode[]): void {
+  const byKind = new Map<PodGraphNodeKind, PodGraphNode[]>();
+  for (const n of nodes) {
+    const list = byKind.get(n.kind) ?? [];
+    list.push(n);
+    byKind.set(n.kind, list);
+  }
+  for (const [kind, list] of byKind) {
+    list.sort((a, b) => a.id.localeCompare(b.id));
+    const n = list.length;
+    list.forEach((node, i) => {
+      node.x = COLUMN_X[kind];
+      node.y = Math.round(((i + 1) / (n + 1)) * 452) + 10;
+    });
+  }
+}
+
+const SEVERITY_WEIGHT: Record<string, number> = { info: 0.4, warn: 0.7, critical: 1 };
+
+/** Parse any timestamp-ish value to epoch ms (0 when missing/unparseable). */
+function ms(t: string | Date | null | undefined): number {
+  if (!t) return 0;
+  const v = new Date(t).getTime();
+  return Number.isFinite(v) ? v : 0;
+}
+
+const OBSERVE_WINDOW_MS = 60_000;
+
+/**
+ * Live counts for the learning-loop rail (observe→store→predict→outcome→adapt).
+ * The "active" stage is the one whose latest underlying event is most recent —
+ * with deeper stages winning ties so the rail lights up at the furthest point
+ * the pod reached this session. Additive: derived from already-fetched docs.
+ */
+function buildLoop(opts: {
+  now: number;
+  observations: EngineerContext[];
+  collisions: Collision[];
+  outcomes: InterventionOutcome[];
+  riskPaths: number;
+  vectorCount: number;
+  learnedOwners: number;
+}): LearningStage[] {
+  const { now, observations, collisions, outcomes, riskPaths, vectorCount, learnedOwners } = opts;
+
+  const recentObs = observations.filter((o) => now - ms(o.observedAt) < OBSERVE_WINDOW_MS).length;
+  const rate = (recentObs / 60).toFixed(1);
+  const accepted = outcomes.filter((o) => o.accepted).length;
+  const dismissed = outcomes.filter((o) => !o.accepted).length;
+
+  // Latest event time per stage; `store` sits just behind `predict` so a shared
+  // collision timestamp resolves to PREDICT rather than STORE.
+  const latestObs = Math.max(0, ...observations.map((o) => ms(o.observedAt)));
+  const latestCol = Math.max(0, ...collisions.map((c) => ms(c.detectedAt)));
+  const latestOut = Math.max(0, ...outcomes.map((o) => ms(o.recordedAt)));
+  const latestAdapt = Math.max(
+    0,
+    ...outcomes.filter((o) => o.accepted && o.wasRealCollision).map((o) => ms(o.recordedAt)),
+  );
+
+  const refs: Array<[LearningStageKey, number]> = [
+    ['observe', latestObs],
+    ['store', latestCol ? latestCol - 1 : 0],
+    ['predict', latestCol],
+    ['outcome', latestOut],
+    ['adapt', latestAdapt],
+  ];
+  let activeKey: LearningStageKey = 'observe';
+  let best = 0;
+  for (const [k, t] of refs) {
+    if (t > 0 && t >= best) {
+      best = t;
+      activeKey = k;
+    }
+  }
+
+  const stages: Array<Omit<LearningStage, 'active'>> = [
+    { key: 'observe', title: 'OBSERVE', value: String(recentObs), detail: `~${rate}/s vision contexts` },
+    { key: 'store', title: 'STORE', value: String(vectorCount), detail: 'memory vectors · Atlas' },
+    {
+      key: 'predict',
+      title: 'PREDICT',
+      value: String(riskPaths),
+      detail: `open risk path${riskPaths === 1 ? '' : 's'}`,
+    },
+    { key: 'outcome', title: 'OUTCOME', value: `${accepted}/${dismissed}`, detail: 'accepted · dismissed' },
+    {
+      key: 'adapt',
+      title: 'ADAPT',
+      value: String(learnedOwners),
+      detail: `learned owner${learnedOwners === 1 ? '' : 's'}`,
+    },
+  ];
+  return stages.map((s) => ({ ...s, active: s.key === activeKey }));
+}
+
+/**
+ * Merge + time-sort recent events into the activity stream feed. Reuses the same
+ * de-noise (isFilePath / ENGINEER_NOISE / signature collapse) as the graph so
+ * the feed never shows junk paths or test-artifact engineers. Capped to 8.
+ */
+function buildActivity(opts: {
+  observations: EngineerContext[];
+  collisions: Collision[];
+  interventions: Intervention[];
+  outcomes: InterventionOutcome[];
+  ownership: Record<string, string>;
+}): ActivityEvent[] {
+  const { observations, collisions, interventions, outcomes, ownership } = opts;
+  const cleanEng = (n: string): boolean => Boolean(n) && !ENGINEER_NOISE.test(n);
+  const out: ActivityEvent[] = [];
+
+  // editing — newest observation per (engineer, file); observations arrive desc.
+  const seenEdit = new Set<string>();
+  for (const o of observations) {
+    if (!o.engineerId || !cleanEng(o.engineerId)) continue;
+    const file = o.currentFile ? normalizeFile(o.currentFile) : '';
+    if (!isFilePath(file)) continue;
+    const key = `${o.engineerId.toLowerCase()}|${file}`;
+    if (seenEdit.has(key)) continue;
+    seenEdit.add(key);
+    out.push({
+      id: `edit:${o.engineerId}:${file}`,
+      at: o.observedAt,
+      kind: 'editing',
+      text: `${o.engineerId} opened ${shortLabel(file)}${
+        o.hasUnpushedChanges ? ' — unpushed changes' : ''
+      }`,
+    });
+  }
+
+  // collision — collapse by signature, newest first.
+  const seenCol = new Set<string>();
+  for (const c of collisions) {
+    const file = normalizeFile(c.file);
+    if (!isFilePath(file)) continue;
+    const sig = (c as { memorySignature?: string }).memorySignature ?? `${file}#${c.symbol ?? ''}`;
+    if (seenCol.has(sig)) continue;
+    seenCol.add(sig);
+    const engs = c.engineers.filter(cleanEng);
+    if (!engs.length) continue;
+    out.push({
+      id: `col:${c.id}`,
+      at: c.detectedAt,
+      kind: 'collision',
+      text: `${c.severity === 'critical' ? 'Critical overlap' : 'Overlap'} on ${shortLabel(
+        file,
+      )} · ${engs.join(' + ')}`,
+    });
+  }
+
+  // warns — interventions PodMan raised.
+  for (const iv of interventions) {
+    if (!iv.message) continue;
+    const msg = iv.message.length > 64 ? `${iv.message.slice(0, 61)}…` : iv.message;
+    out.push({
+      id: `warn:${iv.id}`,
+      at: iv.createdAt,
+      kind: 'warns',
+      text: `PodMan: "${msg}" → card sent`,
+    });
+  }
+
+  // outcome + learned_from — the supervised learning beat.
+  const colById = new Map(collisions.map((c) => [c.id, c]));
+  const ivById = new Map(interventions.map((i) => [i.id, i]));
+  for (const o of outcomes) {
+    if (!o.accepted) continue;
+    out.push({
+      id: `out:${o.interventionId}`,
+      at: o.recordedAt,
+      kind: 'outcome',
+      text: 'Intervention accepted by the pod',
+    });
+    if (!o.wasRealCollision) continue;
+    const iv = ivById.get(o.interventionId);
+    const col = iv ? colById.get(iv.collisionId) : colById.get(o.collisionId);
+    if (!col) continue;
+    const file = normalizeFile(col.file);
+    if (!isFilePath(file)) continue;
+    const owner =
+      (o as { learnedOwner?: string }).learnedOwner ??
+      ownership[file] ??
+      col.engineers.find(cleanEng) ??
+      col.engineers[0];
+    if (!owner) continue;
+    out.push({
+      id: `learn:${o.interventionId}`,
+      at: o.recordedAt,
+      kind: 'learned_from',
+      text: `Memory updated: ${owner} owns ${shortLabel(file)} (confidence ↑)`,
+    });
+  }
+
+  out.sort((a, b) => ms(b.at) - ms(a.at));
+  return out.slice(0, 8);
+}
+
+export async function materializePodGraph(podId: string): Promise<PodGraph | null> {
+  const c = await collections();
+  const db = await getDb();
+
+  const [pod, observations, collisionDocs, interventionDocs, outcomeDocs, gitStates] =
+    await Promise.all([
+      c.pods.findOne({ id: podId }),
+      c.observations.find({ podId }).sort({ observedAt: -1 }).limit(MAX_OBSERVATIONS).toArray(),
+      c.collisions.find({ podId }).sort({ detectedAt: -1 }).limit(100).toArray(),
+      c.interventions.find({ podId }).toArray(),
+      c.outcomes.find({ podId }).toArray(),
+      getGitStates(podId),
+    ]);
+
+  // Optional supervised ownership map (team_model.ownership: file -> engineer).
+  let ownership: Record<string, string> = {};
+  try {
+    const tm = await db
+      .collection<{ podId: string; ownership?: Record<string, string> }>('team_model')
+      .findOne({ podId });
+    ownership = tm?.ownership ?? {};
+  } catch {
+    /* ownership is optional */
+  }
+
+  const b: Builder = { nodes: new Map(), edges: new Map() };
+  const now = Date.now();
+
+  // 1. Baseline engineer nodes from the roster.
+  for (const name of pod?.members ?? []) {
+    upsertNode(b, 'engineer', name, { label: name });
+  }
+
+  // 2. Vision (observations): who is active and on which file, with confidence.
+  for (const o of observations) {
+    if (!o.engineerId) continue;
+    const recent = o.observedAt && now - new Date(o.observedAt).getTime() < ACTIVE_WINDOW_MS;
+    const eng = upsertNode(b, 'engineer', o.engineerId, {
+      label: o.engineerId,
+      status: recent ? 'active' : undefined,
+    });
+    const file = o.currentFile ? normalizeFile(o.currentFile) : '';
+    if (isFilePath(file)) {
+      const f = upsertNode(b, 'file', file, { label: shortLabel(file), summary: file });
+      upsertEdge(b, eng, f, 'editing', o.activity ?? 'edits', Math.max(0.4, o.confidence ?? 0.5));
+    }
+  }
+
+  // Collisions referenced by accepted outcomes are the "learned" money path — they
+  // always survive the cap so the learned_from beat is never dropped.
+  const priorityCol = new Set<string>();
+  for (const out of outcomeDocs) {
+    if (!out.accepted || !out.wasRealCollision) continue;
+    if (out.collisionId) priorityCol.add(out.collisionId);
+    const iv = interventionDocs.find((i) => i.id === out.interventionId);
+    if (iv?.collisionId) priorityCol.add(iv.collisionId);
+  }
+
+  // 3. Collisions: collapse repeats by signature, keep the most recent, cap to
+  //    MAX_COLLISIONS, skip junk-file collisions. `collisionById` keeps every doc
+  //    (for the outcome join); `colNodeFor` maps each collisionId to its surviving
+  //    collision node (or null when collapsed / capped / filtered out).
+  const collisionById = new Map<string, (typeof collisionDocs)[number]>();
+  const colNodeFor = new Map<string, string | null>();
+  const sigToNode = new Map<string, string>();
+  let distinctCollisions = 0;
+  for (const col of collisionDocs) {
+    collisionById.set(col.id, col);
+    const file = normalizeFile(col.file);
+    const sig =
+      (col as { memorySignature?: string }).memorySignature ?? `${file}#${col.symbol ?? ''}`;
+    const existing = sigToNode.get(sig);
+    if (existing) {
+      colNodeFor.set(col.id, existing);
+      continue;
+    }
+    if (!isFilePath(file)) {
+      colNodeFor.set(col.id, null);
+      continue;
+    }
+    const isPriority = priorityCol.has(col.id);
+    if (!isPriority && distinctCollisions >= MAX_COLLISIONS) {
+      colNodeFor.set(col.id, null);
+      continue;
+    }
+    const cNode = upsertNode(b, 'collision', col.id, {
+      label: shortLabel(file),
+      status: 'risk',
+      weight: SEVERITY_WEIGHT[col.severity] ?? 0.7,
+      summary: `${col.engineers.join(' + ')} on ${file}${
+        (col as { memorySignature?: string }).memorySignature ? ' · seen before' : ''
+      }`,
+    });
+    const fNode = upsertNode(b, 'file', file, {
+      label: shortLabel(file),
+      summary: file,
+      status: 'risk',
+    });
+    upsertEdge(b, fNode, cNode, 'touches', 'hot', 0.6);
+    for (const name of col.engineers) {
+      const eng = upsertNode(b, 'engineer', name, { label: name });
+      upsertEdge(b, eng, cNode, 'collides', 'in', SEVERITY_WEIGHT[col.severity] ?? 0.7);
+    }
+    sigToNode.set(sig, cNode);
+    colNodeFor.set(col.id, cNode);
+    if (!isPriority) distinctCollisions++;
+  }
+
+  // 4. Git truth (engineer_states): mark unpushed work and confirm editing on
+  //    files vision/collisions already surfaced — not the whole repo diff.
+  for (const [name, git] of gitStates) {
+    const files = git.changedFiles.map(parseGitStatusPath).filter(Boolean);
+    const eng = upsertNode(b, 'engineer', name, {
+      label: name,
+      status: files.length > 0 ? 'risk' : 'active',
+      summary: files.length
+        ? `${files.length} changed file(s) on ${git.branch ?? 'detached'}`
+        : `on ${git.branch ?? 'detached'}`,
+      weight: 0.7,
+    });
+    for (const file of files) {
+      const fid = nodeKey('file', file);
+      if (b.nodes.has(fid)) upsertEdge(b, eng, fid, 'editing', 'edits', 0.6);
+    }
+  }
+
+  // 5. Interventions: collapse to one (most recent) per surviving collision.
+  const interventionById = new Map<string, (typeof interventionDocs)[number]>();
+  const ivNodeForCol = new Map<string, string>();
+  const sortedIvs = [...interventionDocs].sort((a, b) =>
+    String(b.createdAt ?? '').localeCompare(String(a.createdAt ?? '')),
+  );
+  for (const iv of sortedIvs) {
+    interventionById.set(iv.id, iv);
+    const colNode = colNodeFor.get(iv.collisionId);
+    if (!colNode || ivNodeForCol.has(colNode)) continue;
+    const ivNode = upsertNode(b, 'intervention', iv.id, {
+      label:
+        iv.suggestedAction?.kind === 'open_sync_pr'
+          ? 'sync PR'
+          : iv.suggestedAction?.kind === 'ping_teammate'
+            ? 'ping'
+            : 'watch',
+      summary: iv.message,
+    });
+    upsertEdge(b, colNode, ivNode, 'warns', 'nudges', 0.85);
+    ivNodeForCol.set(colNode, ivNode);
+  }
+
+  // 6. Outcomes: the supervised learning signal -> learned_from edges + owns.
+  for (const out of outcomeDocs) {
+    if (!out.accepted || !out.wasRealCollision) continue;
+    const iv = interventionById.get(out.interventionId);
+    const col = iv ? collisionById.get(iv.collisionId) : collisionById.get(out.collisionId);
+    if (!col) continue;
+    const file = normalizeFile(col.file);
+    if (!isFilePath(file)) continue;
+    const owner =
+      (out as { learnedOwner?: string }).learnedOwner ?? ownership[file] ?? col.engineers[0];
+    if (!owner) continue;
+    const engNode = upsertNode(b, 'engineer', owner, { label: owner, status: 'learned' });
+    const fNode = upsertNode(b, 'file', file, { label: file });
+    upsertEdge(b, engNode, fNode, 'owns', 'owns', 0.85);
+    const cNode = colNodeFor.get(col.id);
+    const ivNode = cNode ? ivNodeForCol.get(cNode) : undefined;
+    if (ivNode) {
+      const ivObj = b.nodes.get(ivNode);
+      if (ivObj) ivObj.status = 'learned';
+      upsertEdge(b, ivNode, engNode, 'learned_from', `learned: owns ${file}`, 0.6);
+    }
+  }
+
+  // Prune test-artifact engineers, then anything left orphaned by that.
+  const dropNode = (id: string) => {
+    b.nodes.delete(id);
+    for (const [eid, e] of [...b.edges])
+      if (e.source === id || e.target === id) b.edges.delete(eid);
+  };
+  for (const [id, n] of [...b.nodes]) {
+    if (n.kind === 'engineer' && ENGINEER_NOISE.test(n.label)) dropNode(id);
+  }
+  // Collisions with no remaining engineer = test/orphan -> drop.
+  for (const [id, n] of [...b.nodes]) {
+    if (n.kind !== 'collision') continue;
+    if (![...b.edges.values()].some((e) => e.kind === 'collides' && e.target === id)) dropNode(id);
+  }
+  // Cap file nodes to the most-connected (collision files first).
+  const fileNodes = [...b.nodes.values()].filter((n) => n.kind === 'file');
+  if (fileNodes.length > MAX_FILES) {
+    const inCollision = (id: string) =>
+      [...b.edges.values()].some((e) => e.kind === 'touches' && e.source === id);
+    const degree = (id: string) =>
+      [...b.edges.values()].filter((e) => e.source === id || e.target === id).length;
+    fileNodes.sort(
+      (a, z) =>
+        Number(inCollision(z.id)) - Number(inCollision(a.id)) || degree(z.id) - degree(a.id),
+    );
+    for (const n of fileNodes.slice(MAX_FILES)) dropNode(n.id);
+  }
+
+  // Files / interventions left with no edges -> drop.
+  for (const [id, n] of [...b.nodes]) {
+    if (n.kind === 'file' || n.kind === 'intervention') {
+      if (![...b.edges.values()].some((e) => e.source === id || e.target === id))
+        b.nodes.delete(id);
+    }
+  }
+
+  const nodes = [...b.nodes.values()];
+  // No real activity beyond the bare roster -> let the caller fall back to demo.
+  const hasActivity = nodes.some((n) => n.kind !== 'engineer');
+  if (!hasActivity) return null;
+
+  layout(nodes);
+
+  // Metrics are derived from the FINAL de-noised graph (not raw docs) so the
+  // numbers match what's actually on screen. Counting raw collision signatures /
+  // accepted-outcome rows inflates them with test churn (e.g. 50 "risk paths" for
+  // 2 files), which reads as fake — these count distinct visible entities instead.
+  const finalEdges = [...b.edges.values()];
+
+  // Open risk paths = distinct files carrying a surviving collision (the triangles).
+  const riskFiles = new Set<string>();
+  for (const e of finalEdges) {
+    if (e.kind === 'touches' && b.nodes.get(e.source)?.kind === 'file') riskFiles.add(e.source);
+  }
+  const collisionNodeCount = nodes.filter((n) => n.kind === 'collision').length;
+  const riskPaths = riskFiles.size || collisionNodeCount;
+
+  // Learned owners = distinct engineers PodMan retained as owners from accepted
+  // interventions (the owns / learned_from edges actually drawn).
+  const ownerSet = new Set<string>();
+  for (const e of finalEdges) {
+    if (e.kind === 'learned_from') ownerSet.add(e.target);
+    if (e.kind === 'owns') ownerSet.add(e.source);
+  }
+  const learnedOwners = [...ownerSet].filter((id) => b.nodes.get(id)?.kind === 'engineer').length;
+
+  const acceptedReal = outcomeDocs.filter((o) => o.accepted && o.wasRealCollision).length;
+  const totalOutcomes = outcomeDocs.length;
+  const acceptRate = totalOutcomes ? Math.round((acceptedReal / totalOutcomes) * 100) : null;
+
+  const metrics: PodGraphMetric[] = [
+    {
+      label: 'Learned owners',
+      value: String(learnedOwners),
+      detail: 'Distinct owners retained from accepted interventions.',
+    },
+    {
+      label: 'Open risk paths',
+      value: String(riskPaths),
+      detail: `${riskPaths === 1 ? 'File' : 'Files'} with two or more converging editors.`,
+    },
+    {
+      label: 'Accept rate',
+      value: acceptRate == null ? '—' : `${acceptRate}%`,
+      detail: 'Interventions accepted vs total this session.',
+    },
+  ];
+
+  // Stored vectors for the STORE stage: prefer a real memory_vectors count,
+  // fall back to collisions carrying an embedding, then to collision count.
+  let vectorCount = 0;
+  try {
+    vectorCount = await db.collection('memory_vectors').countDocuments({ podId });
+  } catch {
+    /* memory_vectors is optional */
+  }
+  if (!vectorCount)
+    vectorCount = collisionDocs.filter(
+      (c) => (c as { embedding?: number[] }).embedding?.length,
+    ).length;
+  if (!vectorCount) vectorCount = collisionDocs.length;
+
+  const loop = buildLoop({
+    now,
+    observations,
+    collisions: collisionDocs,
+    outcomes: outcomeDocs,
+    riskPaths,
+    vectorCount,
+    learnedOwners,
+  });
+  const activity = buildActivity({
+    observations,
+    collisions: collisionDocs,
+    interventions: interventionDocs,
+    outcomes: outcomeDocs,
+    ownership,
+  });
+
+  return {
+    podId,
+    generatedAt: new Date().toISOString(),
+    nodes,
+    edges: [...b.edges.values()],
+    metrics,
+    loop,
+    activity,
+  };
+}

backend/src/graph/store.ts

@@ -1,6 +1,7 @@
 import type { PodGraph, GraphNodeDoc, GraphEdgeDoc } from '@podman/shared';
 import { getDb } from '../memory/db.js';
 import { createDemoPodGraph } from './demo.js';
+import { materializePodGraph } from './live.js';
 
 interface TeamModelDoc {
   podId: string;
@@ -14,6 +15,14 @@ interface TeamModelDoc {
  * unreachable — so the demo path never depends on a populated DB.
  */
 export async function loadPodGraph(podId: string): Promise<PodGraph> {
+  // 1. Live: materialize from the real collections (observations/collisions/…).
+  try {
+    const live = await materializePodGraph(podId);
+    if (live) return live;
+  } catch (err) {
+    console.warn(`[graph] live materialize failed, falling back: ${(err as Error).message}`);
+  }
+  // 2. Seeded snapshot embedded in team_model.
   try {
     const db = await getDb();
     const doc = await db.collection<TeamModelDoc>('team_model').findOne({ podId });
@@ -21,6 +30,7 @@ export async function loadPodGraph(podId: string): Promise<PodGraph> {
   } catch (err) {
     console.warn(`[graph] loadPodGraph fell back to demo: ${(err as Error).message}`);
   }
+  // 3. Demo (stage safety — never an empty canvas).
   return createDemoPodGraph(podId);
 }
 

backend/src/memory/db.ts

@@ -99,6 +99,7 @@ export async function initMemory(): Promise<void> {
       'collisions.memorySignature',
       () => c.collisions.createIndex({ podId: 1, memorySignature: 1 }),
     ],
+    ['collisions.file', () => c.collisions.createIndex({ podId: 1, file: 1, detectedAt: -1 })],
     ['interventions.collisionId', () => c.interventions.createIndex({ collisionId: 1 })],
     ['outcomes.interventionId', () => c.outcomes.createIndex({ interventionId: 1 })],
   ];

backend/src/memory/policy.ts

@@ -1,17 +1,37 @@
 import type { Collision, SuggestedActionKind } from '@podman/shared';
+import type { RecalledCollision } from './vectors.js';
 
-/**
- * Policy gate: decides whether PodMan should intervene.
- * Stub: always intervene on warn/critical.
- */
-export function shouldIntervene(collision: Collision, _prior: unknown): boolean {
-  return collision.severity !== 'info';
+const lastNudgeByPod = new Map<string, number>();
+
+function cooldownMs(): number {
+  return Number(process.env.NUDGE_COOLDOWN_MS ?? '180000');
 }
 
-/**
- * Preferred action selection based on collision + prior history.
- * Stub: open sync PR for critical, ping teammate otherwise.
- */
-export function preferredAction(collision: Collision, _prior: unknown): SuggestedActionKind {
+/** Policy gate: combines severity, exact recall outcomes, and per-pod cooldown. */
+export function shouldIntervene(collision: Collision, prior: RecalledCollision | null): boolean {
+  if (collision.severity === 'info') return false;
+
+  const priorOutcome = prior?.priorOutcome;
+  if (priorOutcome && !priorOutcome.accepted && !priorOutcome.wasRealCollision) return false;
+
+  const cooldown = cooldownMs();
+  const last = lastNudgeByPod.get(collision.podId) ?? 0;
+  if (cooldown > 0 && Date.now() - last < cooldown && collision.severity !== 'critical') {
+    return false;
+  }
+
+  lastNudgeByPod.set(collision.podId, Date.now());
+  return true;
+}
+
+/** Preferred action selection based on collision severity and prior accepted actions. */
+export function preferredAction(
+  collision: Collision,
+  prior: RecalledCollision | null,
+): SuggestedActionKind {
+  const acceptedKind = prior?.priorOutcome?.accepted
+    ? prior.priorIntervention?.suggestedAction.kind
+    : undefined;
+  if (acceptedKind && acceptedKind !== 'none') return acceptedKind;
   return collision.severity === 'critical' ? 'open_sync_pr' : 'ping_teammate';
 }

backend/src/memory/store.ts

@@ -1,17 +1,25 @@
-import type { EngineerContext, Collision, Intervention, InterventionOutcome } from '@podman/shared';
+import type {
+  EngineerContext,
+  Collision,
+  Intervention,
+  InterventionOutcome,
+  InterventionStatus,
+} from '@podman/shared';
 import { collections } from './db.js';
 import { enrichCollisionMemory } from './vectors.js';
 
 /**
  * Continual-learning memory: persist observations, collisions, interventions,
- * and outcomes to MongoDB so later sessions get sharper. Writes are best-effort
- * — a Mongo hiccup logs a warning rather than crashing the agent/server.
+ * and outcomes to MongoDB so later sessions get sharper. MongoDB is mandatory —
+ * a failed write is surfaced loudly and rethrown, never silently swallowed, so
+ * a broken memory layer can never masquerade as a working one.
  */
 async function persist(name: string, fn: () => Promise<unknown>): Promise<void> {
   try {
     await fn();
   } catch (err) {
-    console.warn(`[memory] ${name} persist failed: ${(err as Error).message}`);
+    console.error(`[memory] ${name} persist FAILED: ${(err as Error).message}`);
+    throw err;
   }
 }
 
@@ -33,8 +41,24 @@ export async function recordIntervention(intervention: Intervention): Promise<vo
   );
 }
 
+export async function updateInterventionStatus(
+  interventionId: string,
+  status: InterventionStatus,
+): Promise<void> {
+  await persist('intervention ack', async () =>
+    (await collections()).interventions.updateOne({ id: interventionId }, { $set: { status } }),
+  );
+}
+
 export async function recordOutcome(outcome: InterventionOutcome): Promise<void> {
-  await persist('outcome', async () => (await collections()).outcomes.insertOne({ ...outcome }));
+  await persist('outcome', async () => {
+    const c = await collections();
+    await c.outcomes.insertOne({ ...outcome });
+    await c.interventions.updateOne(
+      { id: outcome.interventionId },
+      { $set: { status: outcome.accepted ? 'accepted' : 'dismissed' } },
+    );
+  });
 }
 
 /** Document counts per collection — used by the /api/memory/stats endpoint. */

backend/src/memory/vectors.ts

@@ -1,4 +1,4 @@
-import type { Collision } from '@podman/shared';
+import type { Collision, Intervention, InterventionOutcome } from '@podman/shared';
 import { env } from '../env.js';
 import { getDb } from './db.js';
 
@@ -6,18 +6,35 @@ type StoredCollision = Collision & {
   memorySignature?: string;
   memoryText?: string;
   embedding?: number[];
+  embeddingProvider?: string;
+};
+
+export type RecalledCollision = Collision & {
+  priorIntervention?: Intervention;
+  priorOutcome?: InterventionOutcome;
 };
 
 interface VoyageEmbeddingResponse {
   data?: Array<{ embedding?: number[] }>;
 }
 
+interface GeminiEmbeddingResponse {
+  embedding?: { values?: number[] };
+}
+
 function normalize(value: string | undefined): string {
   return (value ?? '').trim().toLowerCase();
 }
 
 function signature(collision: Collision): string {
-  return [normalize(collision.file), normalize(collision.symbol)].filter(Boolean).join('#');
+  return [
+    normalize(collision.file),
+    normalize(collision.symbol),
+    [...collision.engineers].sort().map(normalize).join('+'),
+    'collision',
+  ]
+    .filter(Boolean)
+    .join('#');
 }
 
 function memoryText(collision: Collision): string {
@@ -32,7 +49,30 @@ function memoryText(collision: Collision): string {
     .join('\n');
 }
 
+function cosine(a: number[], b: number[]): number {
+  const n = Math.min(a.length, b.length);
+  let dot = 0;
+  let aNorm = 0;
+  let bNorm = 0;
+  for (let i = 0; i < n; i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    aNorm += av * av;
+    bNorm += bv * bv;
+  }
+  if (!aNorm || !bNorm) return -1;
+  return dot / (Math.sqrt(aNorm) * Math.sqrt(bNorm));
+}
+
 async function embed(text: string, inputType: 'document' | 'query'): Promise<number[] | null> {
+  return (await embedWithVoyage(text, inputType)) ?? embedWithGemini(text, inputType);
+}
+
+async function embedWithVoyage(
+  text: string,
+  inputType: 'document' | 'query',
+): Promise<number[] | null> {
   if (!env.VOYAGE_API_KEY) return null;
   try {
     const res = await fetch('https://api.voyageai.com/v1/embeddings', {
@@ -59,6 +99,38 @@ async function embed(text: string, inputType: 'document' | 'query'): Promise<num
   }
 }
 
+async function embedWithGemini(
+  text: string,
+  inputType: 'document' | 'query',
+): Promise<number[] | null> {
+  try {
+    const taskType = inputType === 'document' ? 'RETRIEVAL_DOCUMENT' : 'RETRIEVAL_QUERY';
+    const res = await fetch(
+      `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(
+        env.GEMINI_EMBEDDING_MODEL,
+      )}:embedContent?key=${encodeURIComponent(env.GEMINI_API_KEY)}`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          content: { parts: [{ text }] },
+          taskType,
+          outputDimensionality: 768,
+        }),
+      },
+    );
+    if (!res.ok) {
+      console.warn(`[memory] gemini embedding failed: ${res.status} ${await res.text()}`);
+      return null;
+    }
+    const body = (await res.json()) as GeminiEmbeddingResponse;
+    return body.embedding?.values ?? null;
+  } catch (err) {
+    console.warn(`[memory] gemini embedding failed: ${(err as Error).message}`);
+    return null;
+  }
+}
+
 export async function enrichCollisionMemory(collision: Collision): Promise<StoredCollision> {
   const text = memoryText(collision);
   const embedding = await embed(text, 'document');
@@ -66,16 +138,45 @@ export async function enrichCollisionMemory(collision: Collision): Promise<Store
     ...collision,
     memorySignature: signature(collision),
     memoryText: text,
-    ...(embedding ? { embedding } : {}),
+    ...(embedding
+      ? { embedding, embeddingProvider: env.VOYAGE_API_KEY ? 'voyage' : 'gemini' }
+      : {}),
   };
 }
 
-async function recallByVector(collision: Collision): Promise<Collision | null> {
+async function attachOutcome(match: StoredCollision): Promise<RecalledCollision> {
+  const db = await getDb();
+  const intervention = await db
+    .collection<Intervention>('interventions')
+    .findOne({ collisionId: match.id }, { sort: { createdAt: -1 }, projection: { _id: 0 } });
+  const outcome = intervention
+    ? await db
+        .collection<InterventionOutcome>('outcomes')
+        .findOne(
+          { interventionId: intervention.id },
+          { sort: { recordedAt: -1 }, projection: { _id: 0 } },
+        )
+    : null;
+  const {
+    memorySignature: _memorySignature,
+    memoryText: _memoryText,
+    embedding: _embedding,
+    embeddingProvider: _embeddingProvider,
+    ...collision
+  } = match;
+  return {
+    ...collision,
+    ...(intervention ? { priorIntervention: intervention } : {}),
+    ...(outcome ? { priorOutcome: outcome } : {}),
+  };
+}
+
+async function recallByVector(collision: Collision): Promise<RecalledCollision | null> {
   const queryVector = await embed(memoryText(collision), 'query');
   if (!queryVector) return null;
 
+  const db = await getDb();
   try {
-    const db = await getDb();
     const [match] = await db
       .collection<StoredCollision>('collisions')
       .aggregate<StoredCollision>([
@@ -93,31 +194,62 @@ async function recallByVector(collision: Collision): Promise<Collision | null> {
         { $project: { _id: 0, embedding: 0 } },
       ])
       .toArray();
-    return match ?? null;
+    return match ? attachOutcome(match) : null;
   } catch (err) {
-    console.warn(`[memory] vector recall unavailable: ${(err as Error).message}`);
-    return null;
+    console.warn(`[memory] atlas vector recall unavailable: ${(err as Error).message}`);
   }
+
+  const candidates = await db
+    .collection<StoredCollision>('collisions')
+    .find(
+      {
+        podId: collision.podId,
+        id: { $ne: collision.id },
+        embedding: { $exists: true },
+      },
+      { projection: { _id: 0 }, limit: 100 },
+    )
+    .toArray();
+  let best: { match: StoredCollision; score: number } | null = null;
+  for (const candidate of candidates) {
+    if (!candidate.embedding?.length) continue;
+    const score = cosine(queryVector, candidate.embedding);
+    if (!best || score > best.score) best = { match: candidate, score };
+  }
+  return best && best.score > 0.5 ? attachOutcome(best.match) : null;
 }
 
-async function recallBySignature(collision: Collision): Promise<Collision | null> {
+async function recallBySignature(collision: Collision): Promise<RecalledCollision | null> {
   const db = await getDb();
   const sig = signature(collision);
-  const match = await db.collection<StoredCollision>('collisions').findOne(
-    {
-      podId: collision.podId,
-      id: { $ne: collision.id },
-      $or: [{ memorySignature: sig }, { file: collision.file }],
-    },
-    { sort: { detectedAt: -1 }, projection: { _id: 0, embedding: 0 } },
-  );
-  return match ?? null;
+  const matches = await db
+    .collection<StoredCollision>('collisions')
+    .find(
+      {
+        podId: collision.podId,
+        id: { $ne: collision.id },
+        $or: [{ memorySignature: sig }, { file: collision.file }],
+      },
+      { sort: { detectedAt: -1 }, projection: { _id: 0, embedding: 0 }, limit: 10 },
+    )
+    .toArray();
+
+  let fallback: RecalledCollision | null = null;
+  for (const match of matches) {
+    const recalled = await attachOutcome(match);
+    if (!fallback) fallback = recalled;
+    if (recalled.priorOutcome?.accepted && recalled.priorOutcome.wasRealCollision) {
+      return recalled;
+    }
+  }
+  return fallback;
 }
 
 /**
- * Recall prior collision patterns. Exact Mongo recall is always available;
- * Voyage + Atlas Vector Search is used first when configured.
+ * Recall prior collision patterns. Atlas Vector Search is preferred when
+ * available; standalone MongoDB falls back to app-side cosine search over
+ * stored embeddings, then exact signature/file matching.
  */
-export async function recallSimilar(collision: Collision): Promise<Collision | null> {
+export async function recallSimilar(collision: Collision): Promise<RecalledCollision | null> {
   return (await recallByVector(collision)) ?? recallBySignature(collision);
 }

backend/src/server.ts

@@ -177,7 +177,11 @@ http.listen(env.PORT, '0.0.0.0', () => {
   console.log(`[server] :${env.PORT}`);
   initMemory()
     .then(() => seedDefaultPods())
-    .catch((e) => console.warn(`[memory] init failed: ${(e as Error).message}`));
+    .catch((e) => {
+      // MongoDB is mandatory — do not run a half-dead API against a broken DB.
+      console.error(`[memory] init FAILED, exiting: ${(e as Error).message}`);
+      process.exit(1);
+    });
 });
 
 let shuttingDown = false;

backend/src/voice/live.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'node:buffer';
 import {
   AudioFrame,
   AudioSource,
@@ -12,6 +13,7 @@ import { env } from '../env.js';
 
 const SAMPLE_RATE = 24_000;
 const CHANNELS = 1;
+const FRAME_SAMPLES = SAMPLE_RATE / 10;
 const encoder = new TextEncoder();
 const ai = new GoogleGenAI({ apiKey: env.GEMINI_API_KEY });
 
@@ -44,6 +46,72 @@ function audioFrames(message: LiveServerMessage): AudioFrame[] {
   return out;
 }
 
+function framesFromPcmBase64(data: string, mimeType?: string): AudioFrame[] {
+  const frame = audioFrameFromBase64(data, mimeType);
+  if (!frame) return [];
+
+  const samples = frame.data;
+  const frames: AudioFrame[] = [];
+  for (let offset = 0; offset < samples.length; offset += FRAME_SAMPLES) {
+    const chunk = samples.subarray(offset, Math.min(offset + FRAME_SAMPLES, samples.length));
+    frames.push(new AudioFrame(chunk, SAMPLE_RATE, CHANNELS, chunk.length / CHANNELS));
+  }
+  return frames;
+}
+
+async function generateTtsFrames(message: string): Promise<AudioFrame[]> {
+  const res = await ai.models.generateContent({
+    model: env.GEMINI_LIVE_MODEL,
+    contents: [{ parts: [{ text: message }] }],
+    config: {
+      responseModalities: [Modality.AUDIO],
+      speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Kore' } } },
+    },
+  });
+  const parts = res.candidates?.[0]?.content?.parts ?? [];
+  return parts.flatMap((part) =>
+    framesFromPcmBase64(part.inlineData?.data ?? '', part.inlineData?.mimeType),
+  );
+}
+
+async function speakWithTts(source: AudioSource, message: string): Promise<void> {
+  for (const frame of await generateTtsFrames(message)) {
+    await source.captureFrame(frame);
+  }
+}
+
+async function speakWithLive(source: AudioSource, message: string): Promise<void> {
+  let done: () => void = () => {};
+  const donePromise = new Promise<void>((resolve) => {
+    done = resolve;
+  });
+  const session: Session = await ai.live.connect({
+    model: env.GEMINI_LIVE_MODEL,
+    config: { responseModalities: [Modality.AUDIO] },
+    callbacks: {
+      onmessage: (event) => {
+        void (async () => {
+          for (const frame of audioFrames(event)) await source.captureFrame(frame);
+          if (event.serverContent?.turnComplete || event.serverContent?.generationComplete) done();
+        })();
+      },
+      onerror: (event) => {
+        console.warn(`[voice] Gemini Live error: ${event.message}`);
+        done();
+      },
+      onclose: done,
+    },
+  });
+
+  session.sendClientContent({
+    turns: [{ role: 'user', parts: [{ text: message }] }],
+    turnComplete: true,
+  });
+
+  await Promise.race([donePromise, new Promise((resolve) => setTimeout(resolve, 15_000))]);
+  session.close();
+}
+
 /**
  * Speak a message into the LiveKit room using Gemini Live audio. A data-channel
  * VOICE_CUE is sent first so clients still get the cue if audio generation or
@@ -60,38 +128,8 @@ export async function speak(room: Room, message: string): Promise<void> {
 
   try {
     const publication = await room.localParticipant.publishTrack(track, options);
-    let done: () => void = () => {};
-    const donePromise = new Promise<void>((resolve) => {
-      done = resolve;
-    });
-    let session: Session | null = null;
-
-    session = await ai.live.connect({
-      model: env.GEMINI_LIVE_MODEL,
-      config: { responseModalities: [Modality.AUDIO] },
-      callbacks: {
-        onmessage: (event) => {
-          void (async () => {
-            for (const frame of audioFrames(event)) await source.captureFrame(frame);
-            if (event.serverContent?.turnComplete || event.serverContent?.generationComplete)
-              done();
-          })();
-        },
-        onerror: (event) => {
-          console.warn(`[voice] Gemini Live error: ${event.message}`);
-          done();
-        },
-        onclose: done,
-      },
-    });
-
-    session.sendClientContent({
-      turns: [{ role: 'user', parts: [{ text: message }] }],
-      turnComplete: true,
-    });
-
-    await Promise.race([donePromise, new Promise((resolve) => setTimeout(resolve, 15_000))]);
-    session.close();
+    if (env.GEMINI_LIVE_MODEL.includes('tts')) await speakWithTts(source, message);
+    else await speakWithLive(source, message);
     if (publication.sid) await room.localParticipant.unpublishTrack(publication.sid, true);
     await source.close();
   } catch (err) {

claude_team_memory_redesign.md

@@ -0,0 +1,293 @@
+# Team Memory Graph — Redesign Brief (fresh-session handoff)
+
+> **You are a fresh Claude Code session with no prior context. Read this whole file first.**
+> Your job: rebuild the **live "Team memory" graph view** so the **light/real-data** version is as
+> polished and functional as the original **dark Bauhaus mock**, and make the graph **dynamic**
+> (force-directed + animated), not the current dead static-column layout.
+> **Do not rewrite the backend materializer — it is good.** The problem is 100% the frontend rendering.
+
+---
+
+## 0. Mission (one paragraph)
+
+PodMan's "Team memory" is a per-pod graph of who owns/edits which files, where work collides, and what
+PodMan learned from accepted interventions — the continual-learning loop made legible in 10 seconds.
+A **dark Bauhaus mock** of this view looks great (clean 3-panel layout, a learning-loop rail, an activity
+stream, a readable graph). The **shipped light version on real data looks terrible** (a hairball of red
+edges, overlapping labels, a static lifeless layout, and it's missing the learning-loop rail + activity
+stream entirely). Make the light version match the mock's structure/polish/functionality, in the app's
+**light shadcn theme**, and make the **graph dynamic** (organic force-directed layout, draggable,
+animated transitions). Keep using **real data** from the existing materializer.
+
+---
+
+## 1. The two reference points
+
+### A. The dark Bauhaus mock = what "good" looks like (target structure)
+
+A single dark card titled **"PODMAN — CONTINUAL-LEARNING OBSERVATORY"** with a `LIVE · POD demo-pod`
+status. Layout:
+
+- **Left rail — WORKFLOW METRICS**: a vertical stack of bordered cards, each a big numeral + an
+  UPPERCASE tracked label + a one-line detail, with a colored left-accent bar:
+  `03 PODS WATCHED`, `05 ENGINEERS LIVE`, `02 COLLISIONS OPEN (▲ auth.ts critical)`,
+  `01 INTERVENTION SENT`, `86% ACCEPT RATE (▲ +14% this session)`, `124 MEMORY VECTORS`.
+- **Center — the GRAPH**: sparse, geometric, readable. Node shapes encode kind
+  (engineer = filled square, file = outlined square, feature = circle, collision = triangle,
+  intervention = diamond). One **risk path is lit** (Karti+Yahya → auth.ts → collision → sync PR →
+  `learned_from`), everything else dimmed. Edges color-coded (`collides` red, `warns` amber/orange,
+  `learned_from` dashed violet, `owns` blue, `editing` paper, `touches` grey).
+- **Right rail — LEARNING LOOP**: a vertical 5-step stepper with the active step highlighted/pulsing:
+  `01 OBSERVE (vision → 5 contexts/s)` → `02 STORE (124 vectors · Atlas)` →
+  `03 PREDICT (2 collisions flagged)` [active] → `04 OUTCOME (1 accepted · 0 dismissed)` →
+  `05 ADAPT (Karti→auth ownership +)`. Arrows between steps.
+- **Bottom-left — ACTIVITY STREAM**: a time-stamped feed with colored kind-tags:
+  `15:48 EDITING Yahya opened auth.ts — unpushed changes detected`,
+  `15:48 COLLISION Critical overlap on auth.ts · Karti + Yahya`,
+  `15:49 WARNS PodMan spoke: "open a sync PR?" → card sent`,
+  `15:49 OUTCOME Sync PR accepted by the pod`,
+  `15:49 LEARNED_FROM Memory updated: Karti owns auth (confidence ↑)`.
+- **Bottom-right — SELECTED NODE**: click a node → kind / name / relationships count / severity / a
+  one-line "why" (`Two engineers editing the same file before push — the signal git can't see.`).
+- **Legend**: engineer / file / feature / collision / intervention · collides / warns / learned_from.
+
+It reads in 10 seconds because it is **sparse, color-coded, and tells the loop story** with the rails +
+stream, not just a node blob. (The full mock HTML/CSS is reproduced in **Appendix A** — port its
+structure to light shadcn.)
+
+### B. The shipped light version = what's wrong (the thing to fix)
+
+Same data, but: a **hairball** — every engineer fans red `collides` edges to ~6 collision triangles
+(all labeled `sync PR`); **file labels overlap** in a dim middle column; the graph uses a **static
+deterministic column layout** (`x` by kind, `y` evenly spread) so it looks dead/lifeless; and it is
+**missing the LEARNING LOOP rail and the ACTIVITY STREAM** entirely — it's just a metrics rail + the bare
+graph + a selected-node panel. (Two already-fixed-on-branch items: garbage collision labels
+`infra/README.md### Running the git watcher` and full-path bleed — see PR #7 / commit `a21a289`,
+`shortLabel` in `live.ts`. Build on top of that, don't redo it.)
+
+---
+
+## 2. The gap to close (light vs mock)
+
+| Mock has                                 | Light version                   | Action                             |
+| ---------------------------------------- | ------------------------------- | ---------------------------------- |
+| Workflow metrics rail                    | ✅ has it (3 metrics)           | keep; restyle to match             |
+| **Learning loop rail (observe→…→adapt)** | ❌ missing                      | **build it** (needs live counts)   |
+| **Activity stream feed**                 | ❌ missing                      | **build it** (needs an event feed) |
+| Selected-node panel                      | ✅ has it                       | keep                               |
+| **Dynamic / animated graph**             | ❌ static columns               | **replace the layout**             |
+| Sparse, lit "risk path"                  | partial (Risk-path mode exists) | improve emphasis + spacing         |
+| Legend                                   | ✅                              | keep                               |
+
+---
+
+## 3. Current architecture (build on this — do NOT rewrite the materializer)
+
+**Backend (good, keep):**
+
+- `backend/src/graph/live.ts` — `materializePodGraph(podId)`: builds the graph from the real Mongo
+  collections (`pods`, `engineer_states`, `observations`, `collisions`, `interventions`, `outcomes`).
+  It already de-noises hard: collapses collisions by `memorySignature`, caps to 8, collapses
+  interventions to one per collision, filters junk files (`isFilePath`), prunes test-artifact engineers
+  (`ENGINEER_NOISE`), caps files to 9, short labels (`shortLabel`). Output is ~20 clean nodes for
+  `demo-pod`. **This is solid — extend it, don't replace it.**
+- `backend/src/graph/store.ts` — `loadPodGraph(podId)`: live materializer → seeded `team_model.graph`
+  → demo fallback (`createDemoPodGraph`). Plus `reachFrom` (`$graphLookup`).
+- Route: `GET /api/pods/:id/graph` returns `PodGraph` (also `/graph/reach/:node`).
+- `backend/src/memory/db.ts` — `collections()`, `getGitStates(podId)`, `getDb()`.
+- WS bus: `backend/src/server.ts` hosts `ws /api/events` (the agent + `/api/outcome` broadcast here).
+
+**Frontend (this is where the work is):**
+
+- `frontend/src/components/GraphView.tsx` — **the thing you redesign** (~90% of the work). Currently:
+  fetches `/api/pods/:id/graph`, renders a bespoke SVG with the static column layout, Risk/Learning/Whole
+  toggles, a metrics rail, a selected-node panel, a legend. Composed from shadcn primitives (`Button`,
+  `Badge`) + Tailwind utilities. Theme-aware via shadcn tokens.
+- `frontend/src/lib/graph.ts` — `fetchPodGraph(podId)`.
+- Opened from each `PodCard`'s `⋯` menu → "Team memory" (`onOpenGraph(pod.id)` in
+  `frontend/src/App.tsx`). It is a conditional render (no route).
+
+**Data contract** (`shared/src/graph.ts`):
+
+```ts
+PodGraph = { podId, generatedAt, nodes: PodGraphNode[], edges: PodGraphEdge[], metrics: PodGraphMetric[] }
+PodGraphNode = { id, kind, label, summary, weight 0..1, status: 'stable'|'active'|'risk'|'learned', x, y }
+//   kind: 'engineer'|'feature'|'file'|'collision'|'intervention'
+PodGraphEdge = { id, source, target, kind, label, strength 0..1 }
+//   kind: 'owns'|'editing'|'touches'|'collides'|'warns'|'learned_from'
+PodGraphMetric = { label, value, detail }
+```
+
+**Theme / components (HARD RULE):** the app is **light shadcn**, built from the **ruixen registry** —
+add primitives with `npx shadcn@latest add "https://ruixen.com/r/[component]"` and compose from
+`@/components/ui/*` (`Button`, `Badge`, `Card`, `Tabs`, `ToggleGroup`, etc.) using the design tokens
+(`var(--card)` / `--foreground` / `--muted-foreground` / `--border`, `--chart-1..5`). Only the SVG/canvas
+graph is bespoke. Match `frontend/src/App.tsx`'s `StatPill`/`BriefLine` utility patterns.
+
+---
+
+## 4. Target design (build this)
+
+A light shadcn page with the **mock's structure**:
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│ Header: "Team memory · What PodMan learned · <pod>"        [← Pods]      │
+├───────────────────────────────────────────────────────────────────────┤
+│ Toggles: Risk path | Learning edges | Whole graph   (keep)              │
+├──────────────┬──────────────────────────────────┬─────────────────────┤
+│ WORKFLOW     │                                  │  LEARNING LOOP        │
+│ METRICS      │        DYNAMIC GRAPH CANVAS        │  observe→store→       │
+│ (cards)      │   (force-directed + animated)     │  predict→outcome→     │
+│              │                                  │  adapt (active pulses)│
+├──────────────┴──────────────────────────────────┴─────────────────────┤
+│ ACTIVITY STREAM (time-tagged feed)        │ SELECTED NODE (detail)      │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+- **Light shadcn** throughout (theme-aware; follows dark mode if the app ever toggles). Keep the
+  geometric **node-shape + color encoding** (it's the legible part) but on light surfaces with the
+  app's hues (engineer blue `#2563eb`, file slate outline `#475569`, feature amber `#d97706`,
+  collision red `#dc2626`, intervention violet `#7c3aed`; edges: collides red, warns amber,
+  learned_from dashed violet, owns blue, editing slate, touches faint slate).
+- **Default to "Risk path"**: light the collision→intervention→`learned_from` chain; dim the rest.
+
+---
+
+## 5. Make the graph DYNAMIC (the headline new requirement)
+
+The static column layout (`live.ts` `layout()` sets `x`/`y` by kind) looks dead. Replace the frontend
+rendering with a **dynamic** graph. Pick one (recommended order):
+
+1. **`d3-force` force-directed (recommended).** Add `d3-force` (small). Run a force simulation on the
+   `PodGraph` nodes/edges: link force (by `edge.strength`), charge/repulsion, center, collision radius
+   (by `node.weight`). Render nodes/edges as SVG, update positions per tick. Make nodes **draggable**
+   (pin on drag). Animate new nodes/edges fading in on data refresh, and the `learned_from` dashed
+   stroke animating. Ignore the server's `x`/`y` (or use them as initial positions). Keep node shapes.
+2. `react-force-graph` / `force-graph` (canvas) — heavier, faster for big graphs; overkill at ~20 nodes
+   but fine.
+3. A custom animated **layered** layout (engineers → files → collisions → interventions columns, but
+   with curved edges, eased position transitions on refresh, and gentle idle motion). Lighter-weight
+   than d3-force; still feels alive if you animate transitions.
+
+**Realtime/dynamic data:** poll `GET /api/pods/:id/graph` every ~5s and **animate the diff** between
+snapshots (don't hard-replace). Optionally subscribe to `ws /api/events` for instant nudges. New
+collisions/interventions should visibly animate in; the `learned_from` edge + gold node should pop on a
+new accepted outcome.
+
+**De-hairball:** even force-directed, ~6 collisions × 3 engineers = many `collides` edges. Mitigate:
+bundle/curve edges, lower non-risk edge opacity, default to Risk-path emphasis, size nodes by `weight`,
+and keep label collision-avoidance (offset labels, hide on overlap, show on hover/select).
+
+---
+
+## 6. Data for the new panels (extend the materializer or add endpoints)
+
+The mock's **Learning Loop** and **Activity Stream** need data the current `PodGraph` doesn't carry. Two
+options: (a) extend `materializePodGraph` to also return `loop` + `activity`, or (b) add small endpoints.
+Recommended: extend the return type (additive to `shared/src/graph.ts`).
+
+- **Learning loop counts** (`observe→store→predict→outcome→adapt`):
+  - observe = recent `observations` count (e.g. last 60s) / rate
+  - store = `memory_vectors` or `collisions.embedding` count (Voyage vectors)
+  - predict = open `collisions` (distinct signatures) count
+  - outcome = `outcomes` accepted vs dismissed counts
+  - adapt = `team_model.ownership` entries / learned owners count
+  - mark the "active" stage = the most recent activity.
+- **Activity stream**: merge + time-sort recent events from `collisions.detectedAt`,
+  `interventions.createdAt`, `outcomes.recordedAt`, `engineer_states.gitUpdatedAt` → a typed feed
+  `{ at, kind: 'editing'|'collision'|'warns'|'outcome'|'learned_from', text }`. Cap to ~8 most recent.
+
+(`backend/src/memory/db.ts` `collections()` gives you `observations/collisions/interventions/outcomes`;
+`getGitStates` gives engineer_states; `team_model` is `db.collection('team_model')`.)
+
+---
+
+## 7. Files to touch
+
+- **`frontend/src/components/GraphView.tsx`** — the redesign (force-directed graph + 3-panel layout +
+  learning-loop rail + activity stream). May split into `GraphCanvas.tsx`, `LearningLoop.tsx`,
+  `ActivityStream.tsx`, `MetricsRail.tsx`.
+- **`frontend/src/lib/graph.ts`** — add fetches for loop/activity if you add endpoints.
+- **`backend/src/graph/live.ts`** (extend, don't rewrite) — emit `loop` + `activity` in the result;
+  keep all the de-noise.
+- **`shared/src/graph.ts`** — add `loop`/`activity` types to `PodGraph` (additive).
+- **deps** — `d3-force` (+ `@types/d3-force`) via pnpm in `frontend`.
+- Possibly add a ruixen primitive (e.g. `timeline`, `stepper`) via the shadcn CLI if one fits.
+
+---
+
+## 8. Constraints & gotchas (READ — these will bite you)
+
+- **The materializer is good — do not rewrite it.** It already de-noises (caps, collapse-by-signature,
+  engineer/file filters, short labels). The bad UI is the **frontend layout/render**, not the data.
+- **PWA service worker caches aggressively** — after any deploy, hard-refresh (Cmd-Shift-R) or test in a
+  private window, or you'll think nothing changed.
+- **Deploy = merge to `main`** (DO `deploy_on_push: true`). `main` is shared by ~4 engineers and moves
+  fast. Work on a branch, open a PR, merge. Don't push to `main` directly.
+- **`learned_from` "money" edge won't render on `demo-pod`** right now — its one accepted outcome is
+  orphaned (points at a collision deleted by test churn). It needs **one intact accept flow** (real
+  collision → intervention → someone clicks Accept) to draw. To demo, seed a clean chain or clear test
+  docs (writes to shared Atlas — confirm scope first).
+- **Atlas creds rotate frequently** — `podman/.env`'s `MONGODB_URI` may be stale; the **deployed env**
+  has the working one. If local Mongo auth fails, that's why.
+- **Build verification**: some sandboxes can't run `pnpm`/`vite`/shadcn deps (`lucide-react`,
+  `@radix-ui`). Verify the frontend with `pnpm build` in a real env or CI before merging. Backend
+  typecheck excludes uninstalled `ws`/`sharp`/`@livekit/rtc-node` noise.
+- **Compose from ruixen/shadcn primitives** (`npx shadcn add ruixen.com/r/[component]`,
+  `@/components/ui/*`); only the SVG/canvas graph is bespoke. Match `StatPill`/`BriefLine` in `App.tsx`.
+- **Light theme + tokens** — never hardcode dark colors for chrome; use `var(--card)/--foreground/…`.
+  Keep fixed semantic hues only for the node/edge kind encoding.
+
+---
+
+## 9. Acceptance criteria
+
+- Light Team-memory page matches the mock's structure: **metrics rail + dynamic graph + learning-loop
+  rail + activity stream + selected-node panel + legend**.
+- **Graph is dynamic**: force-directed (or animated layered), **draggable**, **animates** new
+  nodes/edges and refresh transitions; **no overlapping labels, no hairball**.
+- Reads in 10s; the **risk/money path is obvious** by default.
+- **Light shadcn** theme, theme-aware; composed from ruixen primitives.
+- Uses **real data** from `materializePodGraph`; graceful demo fallback when empty.
+- `pnpm build` + typechecks pass; deploys; verified after a hard-refresh.
+
+---
+
+## 10. Suggested first moves for the new session
+
+1. Read this file + `docs/graph.md` + `docs/live-ui-spec.md` (R1/R2 sections) + `CLAUDE.md`.
+2. `git fetch`; branch off `main` (or `feat/live-graph-glue`, which has the latest graph work).
+3. Hit the live data once: `curl https://165-22-129-249.sslip.io/api/pods/demo-pod/graph` — that's the
+   real `PodGraph` you'll render.
+4. Build a `d3-force` `GraphCanvas` first (replace the static layout), get it draggable + animated.
+5. Add `LearningLoop` + `ActivityStream` (extend the materializer to feed them).
+6. Polish to the mock; `pnpm build`; PR → main → redeploy → hard-refresh.
+
+---
+
+## Appendix A — the dark mock (reference structure to port to light)
+
+The mock is a single dark card. Structure + the exact content to reproduce (in light shadcn):
+
+- Header: brand glyph (blue square + amber circle + red triangle + outlined square) + `PODMAN /
+CONTINUAL-LEARNING OBSERVATORY` + `● LIVE · POD demo-pod`.
+- Grid `180px 1fr 196px`: **metrics rail** | **graph** | **learning-loop rail**.
+- Metrics cards: big `Archivo`-weight numeral, uppercase tracked label, muted detail, colored
+  left-accent (blue/red/yellow/violet/green).
+- Graph: SVG, geometric node shapes by kind, color-coded edges, one lit risk path, dim others; click a
+  node → highlight its incident edges + neighbors, fill the selected-node panel.
+- Learning-loop rail: 5 bordered steps with number + UPPERCASE title + muted sub; the active step has a
+  pulsing left bar; `↓` arrows between.
+- Legend row (node kinds + edge kinds).
+- Activity stream (time + colored tag + text) and selected-node panel below.
+
+Palette used (port to shadcn tokens for chrome; keep these as node/edge hues):
+`bg #0c0c0e`, `panel #141417`, `line #2a2a31`, `paper/text #ECE7DA`, `muted #8d897e`,
+`blue #3B5BFF`, `red #E2403A`, `amber #F6C445`, `violet #8b6cff`, `green #46c07a`.
+For light: chrome → `var(--card)/--foreground/--border/--muted-foreground`; node/edge hues →
+blue `#2563eb`, slate `#475569`, amber `#d97706`, red `#dc2626`, violet `#7c3aed` (light-readable).
+
+> The dark mock was a `show_widget` demo (not a saved file). If you want the literal HTML/CSS, ask the
+> user to paste it, or reconstruct from this appendix — the **structure + content above is the spec**.
+> Goal: same structure, same legibility, **light theme + dynamic graph**.

codex_team_memory_redisgn.md

@@ -0,0 +1,483 @@
+# Team Memory Graph - Codex Redesign Brief
+
+> **Read this whole file before touching code.**
+> This is a fresh-session handoff for rebuilding PodMan's live **Team memory** graph UI.
+> The goal is not to tweak labels or add another filter. The goal is to make the
+> real-data light UI as polished, legible, and functional as the original dark
+> Bauhaus mock, while keeping the graph backed by live MongoDB data.
+
+## 0. Mission
+
+PodMan's Team memory view should make the recursive self-improvement loop visible:
+who is working, which files overlap, where collisions happen, which intervention was
+sent, and what PodMan learned from accepted outcomes.
+
+The current light real-data implementation proves the backend can materialize a graph,
+but the UI does not yet tell the story. It still reads as a static node-link diagram:
+edges dominate, labels collide, the layout feels fixed, and the important loop
+`observe -> store -> predict -> outcome -> adapt` is not visible.
+
+Rebuild the Team memory experience so it has the narrative clarity of the dark
+Bauhaus mock, in the app's light shadcn/ruixen visual system, with a dynamic graph
+that animates and responds to live data changes.
+
+## 1. Current State
+
+Branch context:
+
+- Work is on `feat/live-graph-glue`.
+- The live graph backend exists and should be reused.
+- A PR for the live graph glue already exists, and later commits have continued
+  refining readability.
+- The current file requested by the user is this document:
+  `codex_team_memory_redisgn.md`.
+
+Important existing files:
+
+- `backend/src/graph/live.ts`
+  Builds `PodGraph` from real Mongo collections:
+  `pods`, `engineer_states`, `observations`, `collisions`, `interventions`,
+  and `outcomes`.
+- `backend/src/graph/store.ts`
+  Loads live graph first, then seeded `team_model.graph`, then demo fallback.
+- `shared/src/graph.ts`
+  Defines the graph contract.
+- `frontend/src/components/GraphView.tsx`
+  Current frontend graph rendering. This is the main file to redesign.
+- `frontend/src/lib/graph.ts`
+  Fetches the graph.
+- `frontend/src/App.tsx` and `frontend/src/components/PodCard.tsx`
+  Open Team memory per pod.
+
+Do **not** start by rewriting the backend materializer. It already does the most
+important real-data work: filtering noisy files, collapsing repeated collisions,
+capping graph size, shortening labels, and pruning test engineers. The redesign is
+primarily a frontend information-architecture and interaction problem.
+
+## 2. Reference Screens
+
+### Current Light Real-Data UI
+
+The light UI is technically real and connected to live data, but it fails visually.
+
+Observed problems:
+
+- The graph is too static and column-like.
+- Red collision edges dominate the canvas.
+- Labels overlap and fight for attention.
+- Interventions repeat as a row of identical diamonds.
+- The right panel says "It learned" but does not explain the actual workflow state.
+- The screen lacks an activity stream.
+- The screen lacks the explicit learning-loop rail from the dark mock.
+- The viewer cannot quickly answer:
+  - What happened?
+  - Who collided?
+  - What did PodMan do?
+  - Did the team accept it?
+  - What changed in memory?
+
+The current light version proves data plumbing. It does not yet work as a demo
+surface.
+
+### Dark Bauhaus Mock
+
+The dark mock is the quality target. Do not copy the dark palette wholesale, but
+copy the structure, density, and storytelling.
+
+The mock has:
+
+- A strong title bar:
+  `PODMAN / CONTINUAL-LEARNING OBSERVATORY`
+- A live status indicator:
+  `LIVE - POD demo-pod`
+- A left metrics rail:
+  workflow metrics as compact, high-contrast cards.
+- A center graph:
+  sparse, geometric, readable, with one primary path emphasized.
+- A right learning-loop rail:
+  `Observe -> Store -> Predict -> Outcome -> Adapt`
+- A bottom activity stream:
+  timestamped events with type badges.
+- A selected-node detail panel:
+  kind, relationships, severity, explanation.
+- A legend:
+  node shapes and edge colors.
+
+The mock works because it is not just a graph. It is an observatory. It tells the
+loop story.
+
+## 3. Product Goal
+
+Team memory should be the "it learned" surface.
+
+In a 10-second demo, a viewer should understand:
+
+1. Two engineers are converging on the same file.
+2. PodMan detected the risk before a push.
+3. PodMan suggested an intervention.
+4. The team accepted or dismissed the intervention.
+5. PodMan retained that outcome as memory.
+6. Future collisions become more informed.
+
+The graph should support that story, not overwhelm it.
+
+## 4. Target Layout
+
+Build a light shadcn page with the same conceptual structure as the dark mock.
+
+```text
++--------------------------------------------------------------------------+
+| Header: Team memory - What PodMan learned - <pod>              [<- Pods] |
++--------------------------------------------------------------------------+
+| Mode controls: Risk path | Learning edges | Whole graph                  |
++---------------+--------------------------------------+-------------------+
+| Workflow      |                                      | Learning loop     |
+| metrics       |          Dynamic graph canvas         | Observe           |
+| cards         |                                      | Store             |
+|               |                                      | Predict           |
+|               |                                      | Outcome           |
+|               |                                      | Adapt             |
++---------------+--------------------------------------+-------------------+
+| Activity stream                                | Selected node details   |
++--------------------------------------------------------------------------+
+```
+
+Required panels:
+
+- **Header**
+  - Pod name / id.
+  - Live/generated timestamp.
+  - Back to pods action.
+- **Mode controls**
+  - Risk path.
+  - Learning edges.
+  - Whole graph.
+- **Workflow metrics rail**
+  - Learned owners.
+  - Open risk paths.
+  - Accept rate.
+  - Optional: observations, interventions, memory vectors if available.
+- **Dynamic graph canvas**
+  - Force-directed or animated layered graph.
+  - Geometric node shapes.
+  - Curved or bundled edges.
+  - Labels should not overlap by default.
+  - Hover/select reveals full details.
+- **Learning loop rail**
+  - Observe.
+  - Store.
+  - Predict.
+  - Outcome.
+  - Adapt.
+  - Active/current step should pulse or be highlighted.
+- **Activity stream**
+  - Recent editing, collision, warning, outcome, learned events.
+  - Compact rows with timestamp + colored type badge.
+- **Selected node**
+  - Default state explains the loop.
+  - Selected state shows node kind, name, relationships, severity/status, and
+    why this node matters.
+
+## 5. Visual Direction
+
+Use the app's light shadcn/ruixen design system for chrome.
+
+Hard rules:
+
+- Use `@/components/ui/*` primitives where possible.
+- If a primitive is missing, add it through:
+  `npx shadcn@latest add "https://ruixen.com/r/[component]"`
+- Do not make the entire UI a bespoke CSS island.
+- The graph canvas itself may be bespoke SVG/canvas.
+- The rest should be composed from cards, badges, buttons, tabs/toggles, and
+  utility classes consistent with `App.tsx`.
+
+Keep semantic graph colors:
+
+- Engineer: blue.
+- File: slate outline.
+- Feature: amber circle.
+- Collision: red triangle.
+- Intervention: violet diamond.
+- `collides`: red edge.
+- `warns`: amber/orange edge.
+- `learned_from`: dashed violet edge.
+- `owns`: blue edge.
+- `editing` / `touches`: muted slate.
+
+Use light surfaces:
+
+- Background: app background token.
+- Panels: `card`.
+- Borders: `border`.
+- Text: `foreground`.
+- Supporting copy: `muted-foreground`.
+
+The result should feel like the dark mock translated into the app's light command
+center, not a random analytics dashboard.
+
+## 6. Dynamic Graph Requirement
+
+The current graph is too static. Replace or augment the static column layout.
+
+Preferred implementation:
+
+- Use `d3-force` in the frontend.
+- Initialize nodes from server `x/y` when useful, but let the simulation settle.
+- Use:
+  - link force by edge strength.
+  - charge force for separation.
+  - center force.
+  - collision force based on node radius.
+  - optional x/y bias by kind to preserve rough story flow.
+- Make nodes draggable.
+- Preserve node shape encoding.
+- Animate:
+  - new nodes fading/scaling in.
+  - new edges drawing/fading in.
+  - `learned_from` dashed edge flowing or pulsing.
+  - active collision/intervention pulse.
+
+If `d3-force` is too much for the current branch, use an animated layered layout:
+
+- Engineers left.
+- Files mid-left.
+- Collisions center/right.
+- Interventions right.
+- Curved edges.
+- Smooth transitions between graph snapshots.
+- Gentle idle motion only if it helps.
+
+Do not leave the final version as static fixed columns.
+
+## 7. De-Hairball Rules
+
+Default screen should show the risk path, not every possible relationship.
+
+Rules:
+
+- Default mode: `Risk path`.
+- Whole graph can exist, but it is not the demo default.
+- Dim non-selected/non-risk edges aggressively.
+- Use curved edges or edge bundling.
+- Hide low-priority labels until hover/select.
+- Prefer file basename/short path on canvas.
+- Put full path in selected-node panel.
+- Group repeated collisions by signature.
+- Cap visible collisions/interventions for demo readability.
+- Preserve all data in the payload; choose a readable default projection.
+
+The graph is not an exhaustive database browser. It is a story-first visualization.
+
+## 8. Data Model To Use
+
+Current `PodGraph` contract:
+
+```ts
+interface PodGraph {
+  podId: string;
+  generatedAt: string;
+  nodes: PodGraphNode[];
+  edges: PodGraphEdge[];
+  metrics: PodGraphMetric[];
+}
+```
+
+Node kinds:
+
+- `engineer`
+- `file`
+- `feature`
+- `collision`
+- `intervention`
+
+Edge kinds:
+
+- `owns`
+- `editing`
+- `touches`
+- `collides`
+- `warns`
+- `learned_from`
+
+Statuses:
+
+- `stable`
+- `active`
+- `risk`
+- `learned`
+
+Existing collections behind the materializer:
+
+- `pods`
+- `engineer_states`
+- `observations`
+- `collisions`
+- `interventions`
+- `outcomes`
+
+Important caveat:
+
+The current `demo-pod` accepted outcome chain may be orphaned from test churn.
+If `learned_from` does not show, confirm whether there is an intact:
+
+```text
+collision -> intervention -> accepted outcome
+```
+
+Do not assume the UI is broken until this data chain is verified.
+
+## 9. Extend Data For Missing Panels
+
+The current graph contract does not fully support the dark mock's learning-loop
+rail or activity stream.
+
+Recommended additive extension:
+
+```ts
+interface PodGraphLoopStep {
+  id: 'observe' | 'store' | 'predict' | 'outcome' | 'adapt';
+  label: string;
+  value: string;
+  detail: string;
+  status: 'idle' | 'active' | 'complete';
+}
+
+interface PodGraphActivity {
+  id: string;
+  at: string;
+  kind: 'editing' | 'collision' | 'warns' | 'outcome' | 'learned_from';
+  label: string;
+  detail: string;
+  nodeId?: string;
+  edgeId?: string;
+}
+
+interface PodGraph {
+  ...
+  loop?: PodGraphLoopStep[];
+  activity?: PodGraphActivity[];
+}
+```
+
+Possible data mappings:
+
+- Observe:
+  recent `observations`.
+- Store:
+  stored observations / vectorized collisions / memory documents.
+- Predict:
+  distinct live collisions.
+- Outcome:
+  accepted vs dismissed outcomes.
+- Adapt:
+  learned owners / `learned_from` edges / `team_model.ownership`.
+
+Activity stream source:
+
+- `engineer_states.gitUpdatedAt` -> editing/git state.
+- `collisions.detectedAt` -> collision.
+- `interventions.createdAt` -> warns/intervention.
+- `outcomes.recordedAt` -> outcome.
+- accepted real outcome -> learned_from/adapt event.
+
+Cap activity rows to 8-10.
+
+## 10. Suggested Implementation Plan
+
+1. Create a new branch from the current graph branch or latest `main`.
+2. Read:
+   - this file.
+   - `claude_team_memory_redesign.md`.
+   - `docs/graph.md`.
+   - `docs/live-ui-spec.md` if present.
+   - `frontend/src/components/GraphView.tsx`.
+   - `backend/src/graph/live.ts`.
+3. Add graph UI subcomponents:
+   - `MetricsRail`.
+   - `GraphCanvas`.
+   - `LearningLoopRail`.
+   - `ActivityStream`.
+   - `SelectedNodePanel`.
+4. Implement the dynamic graph canvas first.
+5. Add the learning-loop rail and activity stream.
+6. Polish interaction states:
+   - hover.
+   - selected node.
+   - selected edge/path.
+   - empty/live-loading/offline.
+7. Verify with local live data.
+8. Capture screenshots at desktop and narrow widths.
+9. Run:
+   - `pnpm build` or local `vite build`.
+   - `tsc` for shared/backend/frontend.
+10. Open a PR. Do not push directly to `main`.
+
+## 11. Acceptance Criteria
+
+The redesign is acceptable only when:
+
+- The default view is readable in 10 seconds.
+- The graph is dynamic, not static columns.
+- It includes metrics, graph, learning-loop rail, activity stream, selected-node
+  panel, and legend.
+- The primary risk path is obvious.
+- Labels do not overlap in the default view.
+- Whole graph mode exists but can be visually denser.
+- It uses real data from the materializer.
+- It remains composed from light shadcn/ruixen primitives where possible.
+- It builds successfully.
+- It is verified after a hard refresh because the PWA can cache stale bundles.
+
+## 12. What Not To Do
+
+- Do not make a marketing page.
+- Do not make a generic dashboard.
+- Do not rewrite the backend materializer unless the UI needs a small additive
+  field.
+- Do not return to the dark UI wholesale.
+- Do not keep the static column layout as the final answer.
+- Do not show raw full paths as always-on canvas labels.
+- Do not show every edge at equal opacity.
+- Do not hide the learning loop in copy only; it needs a visible rail or panel.
+
+## 13. Demo Script The UI Should Support
+
+The final UI should support this story:
+
+1. Engineer A and Engineer B work in the same repo.
+2. One has unpushed changes.
+3. PodMan observes the overlap.
+4. A collision node appears and pulses.
+5. PodMan sends a sync PR / warning intervention.
+6. The intervention diamond appears.
+7. The team accepts.
+8. The outcome appears in the activity stream.
+9. A `learned_from` edge appears or pulses.
+10. The learning-loop rail advances to Adapt.
+
+That is the recursive self-improvement moment. Everything else is supporting
+evidence.
+
+## 14. Open Questions For The Implementer
+
+- Should dynamic layout be `d3-force` or animated layered SVG?
+- Should loop/activity be added to `PodGraph` or exposed as separate endpoints?
+- Should the demo seed one intact accepted outcome chain?
+- Should `Whole graph` be hidden behind an explicit "inspect full graph" affordance?
+- Should mobile show a simplified activity-first version instead of the full graph?
+
+Answer these in code comments or PR notes when implementing.
+
+## 15. Final Reminder
+
+The backend now has real graph glue. The UI needs to become a **live learning
+observatory**, not a static graph dump.
+
+Make the light version earn the same reaction as the dark Bauhaus mock:
+
+```text
+I can see what happened.
+I can see what PodMan did.
+I can see what it learned.
+```

docs/PLAN.md

@@ -178,36 +178,41 @@ From the remote plan snapshot and health check on `2026-06-27`:
 - Treat this as operational evidence, not architecture truth. Reverify before
   demo.
 
-### Partial / stubbed
+### Partial / completed since the original audit
 
-- `backend/src/voice/live.ts` logs only; it does not publish real voice/audio
-  into LiveKit yet.
-- Hermes is a product/action/messaging layer in the plan, but the current repo
-  does not yet implement a complete Hermes notification bridge.
-- `backend/src/memory/vectors.ts` is not a real Voyage/Atlas Vector Search
-  implementation yet.
-- Exact-signature recall is the required MVP fallback before vectors.
-- `backend/src/memory/policy.ts` is a simple gate; it does not learn thresholds
-  from outcomes yet.
-- `POST /api/sync-pr` creates a PR artifact path but does not yet build a
-  meaningful sync diff.
-- Frontend `PodView` has only a placeholder intervention area unless/until live
-  intervention rendering is wired.
+- `backend/src/voice/live.ts` now publishes a `VOICE_CUE` fallback and attempts
+  Gemini audio publication into LiveKit. The agent only calls it for critical
+  interventions so voice remains an urgent escalation path.
+- Hermes now has a data-channel teammate message path via `HERMES_MESSAGE` on
+  the existing `podman.intervention` topic. This is the MVP notification bridge,
+  not a Slack/Discord integration.
+- `backend/src/memory/vectors.ts` implements exact-signature recall first and
+  can use Voyage/Gemini embeddings with Atlas Vector Search when configured.
+- Exact-signature recall now attaches prior interventions/outcomes and prefers
+  accepted real collisions, giving the learning beat deterministic MongoDB
+  proof before vector search.
+- `backend/src/memory/policy.ts` now uses severity, per-pod cooldown, and prior
+  outcome history. It is still a simple policy, not a trained threshold model.
+- `POST /api/sync-pr` now creates a visible Markdown sync artifact commit before
+  opening the PR.
+- Frontend `PodView` renders intervention cards, Hermes messages, voice cues,
+  and the accepted sync PR artifact link.
 - Browser screen publishing exists, but the active join path must be proven to
   tag tracks as screen share so the backend agent can filter them correctly. The
   `origin/main` screen-share button appears to address this; local code remains
   behind until that commit is merged.
 - `GIT_REPORT` exists in shared types and agent handling. `scripts/podman-agent.mjs`
   is the finished per-laptop git sidecar — polls every 15 s, upserts git fields
-  to `engineer_states` collection. Not yet wired to publish a `GIT_REPORT` data
-  channel message into the LiveKit room (agent fusion step still needed).
+  to `engineer_states` collection. The backend agent now fuses those Mongo
+  git-state fields into live contexts before collision detection; direct
+  LiveKit `GIT_REPORT` publication from the sidecar remains optional.
 - Background research recommendations are a product requirement and demo goal,
   not an implemented research agent yet.
 - Deployment reliability is partial; API health is reachable, but API/static
   site/worker together must still be reverified before demo.
-- Env docs are inconsistent: backend defaults are `gemini-3.5-flash` and
-  `gemini-3.1-flash-live-preview`, while `.env.example` still lists older
-  Gemini model names.
+- Env docs now align on `gemini-3.5-flash` for vision and
+  `gemini-3.1-flash-tts-preview` for voice. The backend still preserves a Gemini
+  Live path for future available Live models.
 
 ### Not yet proven
 
@@ -667,15 +672,16 @@ Before saying PodMan is demo-ready:
 - [ ] Backend agent subscribes to the screen-share track.
 - [ ] Agent logs at least one parsed Gemini context from a real IDE screen.
 - [x] Local git report supplies dirty/unpushed truth on a schedule (`scripts/podman-agent.mjs` — 15 s poll → MongoDB `engineer_states`). Agent fusion still needed.
-- [ ] Frontend renders a real intervention card.
-- [ ] Hermes notification path works for teammate messages.
+- [x] Frontend renders a real intervention card.
+- [x] Hermes notification path works for teammate messages over the LiveKit data
+      channel.
 - [ ] Voice is heard only for urgent escalation or a fallback is declared.
-- [ ] Outcome ACK writes to MongoDB.
-- [ ] `/api/memory/stats` shows counts increasing.
-- [ ] Second similar situation uses prior memory in the message.
+- [x] Outcome ACK writes to MongoDB and updates intervention status.
+- [x] `/api/memory/stats` shows counts increasing.
+- [x] Second similar situation uses prior exact memory in the message.
 - [ ] Research recommendation card is evidence-backed, or fallback collision demo
       is used.
-- [ ] Sync PR action creates a visible GitHub artifact if used in demo.
+- [x] Sync PR action creates a visible GitHub artifact if used in demo.
 - [ ] DigitalOcean deployment or local fallback is rehearsed.
 - [ ] Backup recording is ready on a separate device.
 

docs/agent-learning/plan.md

@@ -0,0 +1,89 @@
+# Agent Learning Plan
+
+Status: draft  
+Goal: ship a visible recursive self-improvement loop without overbuilding
+
+## Must-Have
+
+1. Store agent runs.
+2. Store trace summaries.
+3. Store active and candidate strategy versions.
+4. Attach verifier or outcome evidence.
+5. Show one strategy improvement in the demo narrative.
+
+## Build Order
+
+### R1: Trace the run
+
+Write one `agent_runs` record for an important coordination decision and append
+trace events for:
+
+- observation
+- recall
+- prediction
+- intervention
+- outcome
+- adaptation
+
+### R2: Version the strategy
+
+Create an active strategy version for one of:
+
+- collision detector threshold
+- intervention routing
+- graph discovery filter
+- card wording prompt
+
+### R3: Score the outcome
+
+Use the simplest verifier:
+
+- accepted real collision = useful
+- dismissed = noisy
+- no response after cooldown = uncertain
+
+### R4: Propose a narrow change
+
+Examples:
+
+- "For this exact signature, prefer sync PR card."
+- "For dismissed docs-only overlaps, suppress voice escalation."
+- "For repeated auth.ts collisions, raise severity."
+
+### R5: Promote or reject
+
+Promote only when evidence is strong enough. Otherwise keep the candidate as
+rejected or open.
+
+## Demo Path
+
+1. Show baseline strategy.
+2. Trigger a collision.
+3. Accept or dismiss the intervention.
+4. Store outcome.
+5. Show a candidate strategy update.
+6. Promote it.
+7. Trigger a similar event.
+8. Show changed behavior.
+
+## Nice-to-Have
+
+- Strategy comparison panel.
+- Model-generated prompt patch with verifier.
+- Vector recall over strategy history.
+- Rollback UI.
+
+## Cut
+
+- Full autonomous code rewriting.
+- Multi-agent strategy debates.
+- Long-term benchmark suite.
+- Training a model.
+
+## Acceptance Criteria
+
+- The demo can point to a MongoDB record proving the agent changed behavior.
+- The changed behavior is visible.
+- The strategy has a parent and evidence.
+- Rejected or failed changes are not deleted.
+

docs/agent-learning/policy.md

@@ -0,0 +1,84 @@
+# Agent Learning Policy
+
+Status: draft  
+Scope: guardrails for recursive self-improvement
+
+## Prime Rule
+
+PodMan may improve its agent behavior only when the improvement is narrow,
+evidence-backed, versioned, and reversible.
+
+## Allowed Learning
+
+PodMan may learn:
+
+- Which prompt version produces clearer interventions.
+- Which detector threshold reduces false positives.
+- Which routing channel gets accepted without being intrusive.
+- Which verifier best predicts user acceptance.
+- Which graph-discovery rule produces cleaner risk paths.
+
+## Disallowed Learning
+
+PodMan must not:
+
+- Promote a strategy because the model says it is better.
+- Rewrite broad system behavior from one example.
+- Hide failures, dismissals, or rejected candidates.
+- Learn from raw screenshots, secrets, or private terminal content.
+- Turn voice into the default route.
+- Create irreversible actions without human approval.
+
+## Promotion Rules
+
+A candidate strategy can become active only when all are true:
+
+1. It has a parent strategy version.
+2. It describes one concrete behavior change.
+3. It has a verifier plan.
+4. It has evidence from a run, outcome, or test.
+5. It improves or fixes the target metric.
+6. It does not increase user interruption without payoff.
+
+## Rejection Rules
+
+Reject and retain the candidate when:
+
+- The verifier regresses.
+- The change is too broad.
+- The evidence is missing.
+- The candidate conflicts with privacy rules.
+- The candidate makes the demo less stable.
+
+## Evidence Strength
+
+| Evidence | Strength | Use |
+| --- | --- | --- |
+| Model opinion | Weak | Proposal only |
+| Trace observation | Medium | Candidate rationale |
+| Human accepted outcome | Strong | Promotion candidate |
+| Human dismissed outcome | Strong | Suppression or rejection |
+| Automated verifier | Strong | Promotion or rejection |
+| Repeated accepted exact signature | Strong | Policy confidence increase |
+
+## Versioning Rules
+
+- Strategy versions are immutable after promotion or rejection.
+- There is one active version per `podId + kind`.
+- A rollback activates the previous version; it does not edit history.
+- Parent-child lineage must be preserved.
+
+## Safety Rules
+
+- Store summaries, not raw sensitive content.
+- Prefer deterministic checks over model judgment.
+- Use exact MongoDB recall before vector recall.
+- Ask for approval before changing code or data with external effects.
+- Treat hackathon demo stability as a hard constraint.
+
+## Demo Honesty
+
+Seeded strategy versions are acceptable when labeled as demo-backed. Do not claim
+a strategy was learned live unless a run and outcome actually created the
+promotion evidence.
+

docs/agent-learning/prompt.md

@@ -0,0 +1,74 @@
+# Agent Learning Prompt
+
+Use this prompt for an agent responsible for improving PodMan's own behavior.
+
+## Prompt
+
+You are PodMan's agent-learning evaluator.
+
+Your job is to inspect a completed agent run, identify one narrow improvement,
+define how to verify it, and decide whether to propose, promote, or reject a
+strategy change.
+
+You must not claim improvement without evidence. You must not propose broad
+rewrites. Keep every change small, reversible, and tied to a run or outcome.
+
+## Inputs
+
+- Current active strategy version.
+- Agent run summary.
+- Trace events.
+- Intervention outcome.
+- Verifier result.
+- Recent false positives or accepted events.
+- Current demo constraints.
+
+## Procedure
+
+1. Identify the target behavior.
+2. Identify the failure or success evidence.
+3. Decide whether a strategy change is warranted.
+4. Propose one narrow change.
+5. Define the verifier.
+6. Decide status: no change, candidate, promote, reject.
+7. Write a short explanation suitable for the Team memory activity stream.
+
+## Output Format
+
+```text
+Target
+- Strategy kind:
+- Active version:
+- Behavior under review:
+
+Evidence
+- Run:
+- Outcome:
+- Verifier:
+- Confidence:
+
+Decision
+- Status:
+- Proposed change:
+- Why this is narrow:
+- Risk:
+
+Verifier
+- Metric:
+- Passing condition:
+- Failing condition:
+
+Memory Write
+- Collection:
+- Record summary:
+- Graph/activity summary:
+```
+
+## Hard Rules
+
+- Exact outcomes beat model opinion.
+- Rejected candidates stay in memory.
+- No raw screenshots or secrets.
+- No broad policy change from one weak signal.
+- No voice-first behavior.
+

docs/agent-learning/spec.md

@@ -0,0 +1,185 @@
+# Agent Learning Spec
+
+Status: draft  
+Scope: how PodMan agents improve their own prompts, policies, detectors, and routing behavior  
+Owner: agent learning / recursive self-improvement
+
+## Purpose
+
+Agent learning is the recursive self-improvement layer. It is not the same as
+team memory. Team memory learns about engineers and work. Agent learning learns
+which agent strategies produce better outcomes.
+
+The demo claim:
+
+1. PodMan tries a coordination strategy.
+2. The run is traced in MongoDB.
+3. A verifier or human outcome scores it.
+4. Gemini or another agent proposes a narrow strategy change.
+5. The new strategy is versioned.
+6. A later run uses the improved strategy and shows a better result.
+
+## Core Objects
+
+### Agent run
+
+One attempt to execute a goal.
+
+```text
+agent_runs
+  runId
+  podId
+  goal
+  trigger
+  strategyVersionId
+  status
+  startedAt
+  completedAt
+  score
+  verifierSummary
+  inputRefs
+  outputRefs
+```
+
+Allowed `status` values:
+
+```text
+running, succeeded, failed, improved, regressed, abandoned
+```
+
+### Trace event
+
+Append-only event log for a run.
+
+```text
+agent_trace_events
+  runId
+  podId
+  step
+  phase
+  eventType
+  inputSummary
+  outputSummary
+  toolName
+  error
+  metrics
+  createdAt
+```
+
+### Strategy version
+
+Versioned prompt, detector rule, policy, verifier, or routing strategy.
+
+```text
+strategy_versions
+  strategyVersionId
+  podId
+  kind
+  name
+  parentVersionId
+  status
+  summary
+  promptText
+  policy
+  verifier
+  metrics
+  createdAt
+  promotedAt
+```
+
+Allowed `kind` values:
+
+```text
+prompt, policy, detector, verifier, routing
+```
+
+Allowed `status` values:
+
+```text
+candidate, active, retired, rejected
+```
+
+### Learning proposal
+
+A candidate change before promotion.
+
+```text
+learning_proposals
+  proposalId
+  podId
+  sourceRunId
+  targetKind
+  parentVersionId
+  proposedChange
+  rationale
+  verifierPlan
+  status
+  createdAt
+  resolvedAt
+```
+
+Allowed `status` values:
+
+```text
+open, accepted, rejected, superseded
+```
+
+## MongoDB Indexes
+
+| Collection | Index | Purpose |
+| --- | --- | --- |
+| `agent_runs` | `{ podId: 1, startedAt: -1 }` | Recent run history |
+| `agent_runs` | `{ podId: 1, strategyVersionId: 1 }` | Compare strategy performance |
+| `agent_trace_events` | `{ runId: 1, step: 1 }` | Reconstruct run |
+| `strategy_versions` | `{ podId: 1, kind: 1, status: 1 }` | Find active strategy |
+| `strategy_versions` | `{ podId: 1, createdAt: -1 }` | Version history |
+| `learning_proposals` | `{ podId: 1, status: 1 }` | Open candidate changes |
+
+## Learning Loop
+
+```text
+observe run -> score run -> propose change -> test candidate -> promote or reject
+```
+
+Agent learning must always connect these records:
+
+```text
+agent_run -> trace_events -> verifier result -> learning_proposal -> strategy_version
+```
+
+## Verifier Contract
+
+Every promoted strategy needs a verifier signal.
+
+Allowed verifier types:
+
+- Human accepted or dismissed outcome.
+- Test pass or fail result.
+- Reduced false positive rate.
+- Reduced intervention count with same or better accepted outcomes.
+- Faster successful run.
+- Better graph discovery precision.
+- Explicit demo operator approval.
+
+Self-evaluation alone is not enough to promote a strategy.
+
+## Relationship to Team Graph
+
+Agent learning can appear in the Team memory graph as activity and loop status,
+but it should not clutter the main risk graph by default.
+
+Graph discovery may show:
+
+- `agent_run` activity in the stream.
+- `strategy_versions` count in the learning loop.
+- A selected-node detail saying a policy changed because a prior outcome was
+  dismissed or accepted.
+
+## Acceptance Criteria
+
+- Every strategy change has a parent.
+- Every promoted strategy cites evidence.
+- Rejected strategies are retained with a reason.
+- Agent traces are append-only.
+- The system can answer: "What changed, why, and did it help?"
+

docs/continual-learning/plan.md

@@ -0,0 +1,69 @@
+# Continual Learning Plan
+
+Status: draft  
+Goal: prove PodMan learns from outcomes in the hackathon demo
+
+## Must-Have Demo Loop
+
+1. Observe two engineers touching the same file.
+2. Store the observation and git state in MongoDB.
+3. Predict a collision.
+4. Send a card or Hermes message.
+5. Record accept or dismiss outcome.
+6. Adapt `team_model`.
+7. Show the learned graph edge or changed future behavior.
+
+## Build Order
+
+### R1: Make exact recall reliable
+
+- Normalize file paths.
+- Build stable memory signatures.
+- Look up prior accepted and dismissed outcomes.
+- Prefer exact recall over vector recall.
+
+### R2: Make outcomes update memory
+
+- Accepted real collision creates or strengthens ownership.
+- Accepted real collision creates `learned_from`.
+- Dismissed outcome lowers confidence or suppresses route.
+
+### R3: Expose loop data to the graph
+
+- Add optional loop snapshot.
+- Add optional activity stream.
+- Keep existing `PodGraph` fields stable.
+
+### R4: Show the observatory
+
+- Render observe/store/predict/outcome/adapt.
+- Show recent activity.
+- Make selected-node detail explain why memory changed.
+
+### R5: Prepare a clean demo chain
+
+- Ensure one collision -> intervention -> accepted outcome exists.
+- Ensure repeated signature recalls prior memory.
+- Verify graph shows learned ownership.
+
+## Nice-to-Have
+
+- Atlas Vector Search over memory summaries.
+- Confidence scoring per ownership edge.
+- Per-file memory timeline.
+- Strategy promotion tied to outcomes.
+
+## Cut
+
+- Raw screenshot storage.
+- Full autonomous training.
+- Broad dashboard metrics.
+- Multi-pod learning generalization.
+
+## Acceptance Criteria
+
+- A judge can see what changed in memory.
+- The second similar event behaves differently.
+- Exact MongoDB records prove the loop.
+- The graph remains legible with real data.
+

docs/continual-learning/policy.md

@@ -0,0 +1,97 @@
+# Continual Learning Policy
+
+Status: draft  
+Scope: what PodMan may learn about a team
+
+## Prime Rule
+
+PodMan learns coordination patterns, not personal surveillance profiles.
+
+## Allowed Memory
+
+PodMan may store:
+
+- File and symbol ownership.
+- Active file overlap.
+- Repeated collision signatures.
+- Intervention history.
+- Accepted and dismissed outcomes.
+- Routing preferences by event type and severity.
+- Summaries of decisions relevant to future coordination.
+
+## Forbidden Memory
+
+PodMan must not store:
+
+- Raw screenshots.
+- Screen recordings.
+- Secrets or credentials.
+- Full terminal logs.
+- Personal performance judgments.
+- Private content unrelated to the coding task.
+
+## Evidence Policy
+
+| Evidence | Can predict? | Can adapt memory? |
+| --- | --- | --- |
+| Vision only | Yes, low confidence | No |
+| Git watcher | Yes | No, unless repeated |
+| GitHub state | Yes | No, unless verified |
+| Accepted real outcome | Yes | Yes |
+| Dismissed outcome | Yes, for suppression | Yes, as negative signal |
+| Verifier result | Yes | Yes |
+
+## Intervention Policy
+
+Use the least intrusive channel:
+
+1. Watch quietly.
+2. Card.
+3. Hermes message.
+4. Voice.
+
+Voice is only for urgent, high-confidence, time-sensitive risks.
+
+## Adaptation Policy
+
+Allowed adaptations:
+
+- Add learned ownership after accepted real outcome.
+- Raise confidence for repeated accepted signatures.
+- Lower confidence for dismissed signatures.
+- Prefer the previously accepted intervention kind.
+- Suppress repeated low-value warnings.
+
+Disallowed adaptations:
+
+- Broad threshold changes from one example.
+- Treating vector similarity as proof.
+- Hiding dismissals.
+- Making interruption more aggressive without evidence.
+
+## Retention Policy
+
+Keep:
+
+- Outcomes.
+- Signatures.
+- Team model memory.
+- Strategy metrics.
+
+Summarize or expire:
+
+- Old observations.
+- Low-confidence vision-only events.
+- Detailed trace text.
+
+Delete immediately:
+
+- Secrets.
+- Accidental raw sensitive captures.
+
+## Demo Policy
+
+Seeded data is acceptable only if the demo script is honest about it. Live
+learning requires a live or staged outcome write that visibly updates the graph
+or future decision.
+

docs/continual-learning/prompt.md

@@ -0,0 +1,87 @@
+# Continual Learning Prompt
+
+Use this prompt for the agent that decides what PodMan should remember from a
+coordination event.
+
+## Prompt
+
+You are PodMan's continual-learning memory agent.
+
+Your job is to inspect observations, collisions, interventions, and outcomes,
+then decide what team memory should be updated. You must separate observed
+facts, inferred risks, human outcomes, and durable learned memory.
+
+Do not claim something was learned unless an accepted real outcome, verifier, or
+human label supports it.
+
+## Inputs
+
+- Pod id.
+- Recent engineer states.
+- Recent observations.
+- Candidate collision.
+- Prior exact-signature memory.
+- Intervention record.
+- Outcome record.
+- Current team model.
+
+## Procedure
+
+1. Normalize file and symbol.
+2. Build exact signature.
+3. Check prior accepted and dismissed outcomes.
+4. Classify the current event.
+5. Decide whether memory should change.
+6. Emit the graph impact.
+7. Write a short explanation.
+
+## Output Format
+
+```text
+Event
+- Signature:
+- Engineers:
+- File:
+- Symbol:
+- Evidence:
+
+Prior Memory
+- Accepted matches:
+- Dismissed matches:
+- Ownership:
+
+Decision
+- Memory action:
+- Confidence:
+- Reason:
+
+Graph Impact
+- Nodes:
+- Edges:
+- Activity text:
+
+Safety
+- Sensitive data present:
+- Redaction needed:
+```
+
+## Memory Actions
+
+Allowed actions:
+
+- no_change
+- strengthen_signature
+- weaken_signature
+- create_learned_owner
+- update_route_preference
+- suppress_signature
+- request_human_label
+
+## Hard Rules
+
+- Exact recall before vector recall.
+- Dismissals are learning signals.
+- `learned_from` requires accepted real outcome.
+- Store summaries, not raw screen content.
+- Prefer less intrusive future behavior when uncertain.
+

docs/continual-learning/spec.md

@@ -0,0 +1,217 @@
+# Continual Learning Spec
+
+Status: draft  
+Scope: how PodMan learns team memory from live work and outcomes  
+Owner: continual learning / Team memory
+
+## Purpose
+
+Continual learning is the product proof that PodMan gets more useful from use.
+It learns team-level coordination memory: ownership, repeated collisions,
+accepted interventions, dismissed noise, and preferred routing.
+
+The visible loop:
+
+```text
+observe -> store -> predict -> outcome -> adapt
+```
+
+## Source Collections
+
+### `engineer_states`
+
+Latest per-engineer state from vision and local git.
+
+Key fields:
+
+- `podId`
+- `name`
+- `currentFile`
+- `changedFiles`
+- `branch`
+- `confidence`
+- `visionUpdatedAt`
+- `gitUpdatedAt`
+- `updatedAt`
+
+### `observations`
+
+Structured perception events.
+
+Key fields:
+
+- `podId`
+- `engineerId`
+- `currentFile`
+- `symbol`
+- `activity`
+- `confidence`
+- `observedAt`
+
+### `collisions`
+
+Predicted risk events.
+
+Key fields:
+
+- `id`
+- `podId`
+- `file`
+- `symbol`
+- `engineers`
+- `severity`
+- `status`
+- `memorySignature`
+- `detectedAt`
+
+### `interventions`
+
+Actions PodMan sent or suggested.
+
+Key fields:
+
+- `id`
+- `podId`
+- `collisionId`
+- `kind`
+- `channel`
+- `message`
+- `suggestedAction`
+- `createdAt`
+
+### `outcomes`
+
+Human or verifier supervision.
+
+Key fields:
+
+- `id`
+- `podId`
+- `interventionId`
+- `collisionId`
+- `accepted`
+- `wasRealCollision`
+- `learnedOwner`
+- `recordedAt`
+
+### `team_model`
+
+Durable pod memory.
+
+Key fields:
+
+- `podId`
+- `graph`
+- `ownership`
+- `collisionSignatures`
+- `interventionPolicy`
+- `updatedAt`
+
+### `memory_vectors`
+
+Optional semantic recall. Exact recall comes first.
+
+Key fields:
+
+- `podId`
+- `sourceKind`
+- `sourceId`
+- `text`
+- `embedding`
+- `embeddingModel`
+- `tags`
+
+## Learning Rules
+
+### Observe
+
+Write structured evidence from vision, git, GitHub, and agent traces.
+
+### Store
+
+Persist source records and materialized summaries. Do not store raw screenshots
+or recordings.
+
+### Predict
+
+Create a collision when multiple engineers converge on the same normalized file
+or symbol and at least one signal shows active or unpushed work.
+
+### Outcome
+
+Record whether the intervention was accepted, dismissed, real, or false.
+
+### Adapt
+
+Only accepted real outcomes can create `learned_from` graph edges. Dismissals
+adapt suppression, routing, or confidence.
+
+## Exact Signature
+
+Use deterministic signatures:
+
+```text
+podId:eventType:normalizedFile:symbol:sortedEngineers
+```
+
+Rules:
+
+- Sort engineer names.
+- Normalize file paths.
+- Use `*` for missing symbol.
+- Never include timestamps.
+
+## UI-Facing Loop Snapshot
+
+The graph response may include:
+
+```text
+loop
+  activeStep
+  steps[]
+    key
+    label
+    value
+    detail
+    status
+```
+
+Step mapping:
+
+| Step | Source |
+| --- | --- |
+| Observe | recent observations and git updates |
+| Store | team model, graph records, memory vectors |
+| Predict | open collisions |
+| Outcome | accepted and dismissed outcomes |
+| Adapt | learned owners, learned edges, strategy changes |
+
+## Activity Stream
+
+The graph response may include:
+
+```text
+activity[]
+  id
+  at
+  kind
+  title
+  detail
+  nodeId
+  edgeId
+```
+
+Allowed `kind` values:
+
+```text
+editing, collision, intervention, outcome, learned, agent
+```
+
+## Acceptance Criteria
+
+- The system can show one accepted outcome changing future memory.
+- Exact recall works without vector search.
+- The Team memory graph can explain the learning loop.
+- Dismissals and false positives are retained.
+- The demo does not rely on raw screenshots or hidden state.
+

docs/digitalocean.md

@@ -69,7 +69,7 @@ LIVEKIT_API_SECRET=...
 
 GEMINI_API_KEY=...
 GEMINI_VISION_MODEL=gemini-2.0-flash
-GEMINI_LIVE_MODEL=gemini-live-2.5-flash
+GEMINI_LIVE_MODEL=gemini-3.1-flash-tts-preview
 
 GITHUB_TOKEN=...
 GITHUB_REPO=karti-ai/podman
@@ -95,6 +95,17 @@ Build once:
 docker build -f infra/Dockerfile -t podman-backend .
 ```
 
+Or use the repository script and verifier:
+
+```bash
+pnpm build:container
+pnpm verify:containers
+```
+
+`verify:containers` uses Docker by default to match `build:container`. To verify
+against a Podman image store instead, run
+`VERIFY_CONTAINER_RUNTIME=podman pnpm verify:containers`.
+
 The image entrypoint runs `node backend/dist/server.js` when
 `PODMAN_PROCESS=server`, and `node backend/dist/agent.js` when
 `PODMAN_PROCESS=agent`. Do not run the combined Hermes supervisor inside App
@@ -170,14 +181,51 @@ The droplet production fallback uses systemd units from `infra/systemd/`:
 ```bash
 sudo install -m 0644 infra/systemd/podman-platform-api.service /etc/systemd/system/
 sudo install -m 0644 infra/systemd/podman-platform-agent.service /etc/systemd/system/
+sudo install -m 0644 infra/systemd/podman-hermes-*.service infra/systemd/podman-hermes-*.timer /etc/systemd/system/
 sudo systemctl daemon-reload
-sudo systemctl enable --now podman-platform-api podman-platform-agent
+sudo systemctl enable --now podman-platform-api podman-platform-agent podman-hermes-watchdog.timer podman-hermes-sync-deploy.timer
 ```
 
 Expected runtime proof:
 
 ```bash
 systemctl is-active podman-platform-api podman-platform-agent
+systemctl is-active podman-hermes-watchdog.timer
+systemctl is-active podman-hermes-sync-deploy.timer
 curl http://127.0.0.1:8787/health
 journalctl -u podman-platform-agent -n 20 --no-pager
+journalctl -u podman-hermes-watchdog -n 40 --no-pager
+```
+
+## Hermes-managed operations layer
+
+The app processes are still supervised by systemd, but Hermes now owns the
+operations loop around them:
+
+- `pnpm hermes:watchdog` checks systemd services, public routes, `/health`,
+  `/api/pods`, and `pnpm deploy:doctor`.
+- `podman-hermes-watchdog.timer` runs that watchdog every five minutes.
+- `podman-hermes-sync-deploy.timer` polls `origin/main` every two minutes. If
+  the tree is clean and the remote moved, it fast-forwards, installs, builds,
+  publishes `frontend/dist` to `/var/www/podman`, restarts the API/agent/Caddy,
+  and runs the strict watchdog.
+- Failed URL checks trigger restarts of the PodMan API, PodMan agent, and Caddy.
+- Failed service checks restart only the unhealthy service.
+- Caddy is validated and reloaded after public route failures.
+- Reports are written to `/var/log/podman/hermes-watchdog-latest.json`.
+- Set `PODMAN_ALERT_WEBHOOK_URL` to send failed reports to Discord, Slack, or a
+  generic webhook receiver.
+- `pnpm hermes:install` installs the timer units and a local pre-push hook that
+  gates major pushes with typecheck, lint, and a non-remediating watchdog check.
+
+The strict gate for production readiness is:
+
+```bash
+pnpm hermes:watchdog:strict
+```
+
+Manual deploy-sync run:
+
+```bash
+pnpm hermes:sync-deploy
 ```

docs/gemini.md

@@ -109,11 +109,11 @@ Respond with the message text only.
 
 ---
 
-## 4. Voice Output — Gemini Live 2.5 via LiveKit
+## 4. Voice Output — Gemini TTS via LiveKit
 
-**Model:** `gemini-live-2.5-flash` (confirm exact ID from LiveKit Agents docs)
+**Model:** `gemini-3.1-flash-tts-preview`
 
-**Integration:** LiveKit Agents framework — Hermes runs as a LiveKit Agent with Gemini Live 2.5 as the voice provider
+**Integration:** Hermes generates Gemini TTS audio and publishes it as a LiveKit audio track. The code still preserves a Gemini Live path for future available Live models.
 
 **Flow:**
 

docs/graph-discovery/plan.md

@@ -0,0 +1,69 @@
+# Graph Discovery Plan
+
+Status: draft  
+Goal: make MongoDB graph discovery visible as a dynamic learning observatory
+
+## Must-Have
+
+1. Keep live materializer as source of graph truth.
+2. Add optional loop and activity fields.
+3. Build a dynamic graph layout.
+4. Default to risk path.
+5. Make selected-node detail explain the story.
+
+## Build Order
+
+### R1: Stabilize discovered graph
+
+- Keep file and engineer noise filters.
+- Keep collision collapse.
+- Keep priority for accepted-outcome paths.
+- Keep graph size capped.
+
+### R2: Add observatory data
+
+- Compute learning-loop snapshot.
+- Compute activity stream.
+- Preserve current graph contract.
+
+### R3: Improve path selection
+
+- Pick one primary risk path.
+- Include learned path when present.
+- Dim unrelated collisions and repeated interventions.
+
+### R4: Render dynamically
+
+- Use `d3-force` or animated layered layout.
+- Make nodes draggable.
+- Curve or bundle edges.
+- Animate `learned_from`.
+
+### R5: Verify with real data
+
+- Fetch live `demo-pod` graph.
+- Confirm labels do not collide badly.
+- Confirm red edges do not dominate.
+- Confirm activity and loop explain the graph.
+
+## Nice-to-Have
+
+- Reachability panel using `$graphLookup`.
+- Hover path previews.
+- Edge bundling by file or collision.
+- Time scrubber for graph snapshots.
+
+## Cut
+
+- Generic analytics dashboard.
+- Large graph database migration.
+- Rendering every historical event.
+- Static fixed-column final layout.
+
+## Acceptance Criteria
+
+- Risk path is obvious in 10 seconds.
+- Learned path is visible when data exists.
+- Whole graph mode exists but is not the default.
+- The graph remains backed by MongoDB, not hardcoded mock data.
+

docs/graph-discovery/policy.md

@@ -0,0 +1,83 @@
+# Graph Discovery Policy
+
+Status: draft  
+Scope: graph hygiene, evidence thresholds, and UI truthfulness
+
+## Prime Rule
+
+The graph must be sparse enough to explain the learning loop and truthful enough
+to audit from MongoDB.
+
+## Node Policy
+
+Create nodes only when they add explanation value.
+
+Allowed:
+
+- Current engineers.
+- Real files.
+- Current or recent collisions.
+- Interventions tied to surviving collisions.
+- Learned ownership paths.
+
+Avoid:
+
+- Test engineers.
+- Scratch files.
+- URLs or environment values misread as files.
+- Repeated identical intervention diamonds.
+- Orphan nodes with no story value.
+
+## Edge Policy
+
+Edges need evidence.
+
+| Edge | Required evidence |
+| --- | --- |
+| `editing` | observation or git state |
+| `touches` | file involved in collision |
+| `collides` | collision prediction |
+| `warns` | intervention record |
+| `learned_from` | accepted real outcome |
+| `owns` | learned or configured ownership |
+
+## De-Hairball Policy
+
+Default mode must not show every relationship equally.
+
+Rules:
+
+- Default to risk path.
+- Collapse repeated collision signatures.
+- Cap files and collisions.
+- Dim non-risk edges.
+- Bundle or curve dense edges.
+- Hide low-priority labels until hover or select.
+- Prefer selected-node explanation over labels everywhere.
+
+## Truthfulness Policy
+
+- Do not show `learned_from` for orphaned or dismissed outcomes.
+- Do not label vector similarity as learned memory.
+- Do not show demo seed as live learning unless labeled.
+- Do not hide false positives from activity or memory.
+
+## Privacy Policy
+
+Graph labels should not expose secrets, raw terminal output, or sensitive file
+contents. File paths are acceptable when they are repo paths and not secret
+values.
+
+## Visual Policy
+
+Semantic colors stay stable:
+
+- Engineer: blue.
+- File: slate.
+- Feature: amber.
+- Collision: red.
+- Intervention: violet.
+- Learned: violet dashed edge.
+
+Chrome should use the app's light shadcn tokens.
+

docs/graph-discovery/prompt.md

@@ -0,0 +1,81 @@
+# Graph Discovery Prompt
+
+Use this prompt for an agent that materializes or reviews PodMan's Team memory
+graph.
+
+## Prompt
+
+You are PodMan's graph discovery agent.
+
+Your job is to turn MongoDB records into a sparse, truthful graph that explains
+the continual-learning loop. Do not maximize node count. Maximize legibility and
+evidence.
+
+The default output should show the risk path and learned path, not every
+possible edge.
+
+## Inputs
+
+- Pod id.
+- Pod roster.
+- Recent engineer states.
+- Recent observations.
+- Collisions.
+- Interventions.
+- Outcomes.
+- Team model.
+- Existing graph nodes and edges.
+
+## Procedure
+
+1. Normalize file paths.
+2. Remove noise.
+3. Create engineer and file nodes.
+4. Collapse repeated collisions by signature.
+5. Preserve accepted-outcome paths.
+6. Create intervention nodes for surviving collisions.
+7. Create learned edges only from accepted real outcomes.
+8. Select the primary risk path.
+9. Build activity and loop summaries.
+10. Explain selected-node stories.
+
+## Output Format
+
+```text
+Graph Summary
+- Pod:
+- Nodes:
+- Edges:
+- Primary risk path:
+- Learned path:
+
+Discovery Decisions
+- Collapsed:
+- Dropped as noise:
+- Preserved because learned:
+
+Loop
+- Observe:
+- Store:
+- Predict:
+- Outcome:
+- Adapt:
+
+Activity
+- Recent events:
+
+Risks
+- Missing evidence:
+- Potential hairball:
+- Demo caveat:
+```
+
+## Hard Rules
+
+- No `learned_from` without accepted real outcome.
+- No raw screenshots or secrets in labels.
+- Do not rewrite the backend materializer unless explicitly asked.
+- Prefer additive graph fields.
+- Default to risk path.
+- Keep whole graph optional.
+

docs/graph-discovery/spec.md

@@ -0,0 +1,146 @@
+# Graph Discovery Spec
+
+Status: draft  
+Scope: how PodMan discovers graph nodes, edges, risk paths, and learning paths from MongoDB  
+Owner: graph discovery / Team memory observatory
+
+## Purpose
+
+Graph discovery turns MongoDB memory into a legible Team memory graph. It is not
+only layout. It decides which relationships matter, which path is highlighted,
+and which evidence explains the graph.
+
+The graph must answer:
+
+1. Who is working?
+2. Which files or symbols overlap?
+3. Where is the risk?
+4. What did PodMan do?
+5. What outcome changed memory?
+
+## Source Data
+
+Graph discovery reads:
+
+- `pods`
+- `engineer_states`
+- `observations`
+- `collisions`
+- `interventions`
+- `outcomes`
+- `team_model`
+- `graph_nodes`
+- `graph_edges`
+- optional `memory_vectors`
+- optional `agent_runs`
+- optional `strategy_versions`
+
+## UI Graph Contract
+
+```text
+PodGraph
+  podId
+  generatedAt
+  nodes
+  edges
+  metrics
+  loop?
+  activity?
+```
+
+Node kinds:
+
+```text
+engineer, feature, file, collision, intervention
+```
+
+Edge kinds:
+
+```text
+owns, editing, touches, collides, warns, learned_from
+```
+
+## Discovery Rules
+
+### Engineer nodes
+
+Create from pod roster, recent observations, git state, or collision membership.
+
+### File nodes
+
+Create only from normalized real file paths. Reject noise such as URLs, env
+values, scratch names, and non-file strings.
+
+### Collision nodes
+
+Create from distinct collision signatures. Collapse repeats. Prioritize
+collisions referenced by accepted outcomes.
+
+### Intervention nodes
+
+Create one visible intervention per surviving collision unless whole-graph mode
+explicitly expands history.
+
+### Learned paths
+
+Create `learned_from` only when an accepted real outcome links an intervention
+to a durable memory update.
+
+## Path Modes
+
+### Risk path
+
+Default mode. Highlight the clearest current chain:
+
+```text
+engineer -> file -> collision -> intervention -> learned owner
+```
+
+Dim unrelated graph material.
+
+### Learning edges
+
+Highlight `learned_from`, `owns`, and the outcomes that produced them.
+
+### Whole graph
+
+Show all materialized nodes and edges with de-emphasized non-critical edges.
+
+## MongoDB Traversal
+
+Use `graph_edges` for reachability:
+
+```text
+source -> target -> next target
+```
+
+Primary traversal questions:
+
+- What risks does this engineer reach?
+- Which files feed this collision?
+- Which intervention came from this collision?
+- Which learned owner came from this intervention?
+
+## Metrics
+
+Minimum metrics:
+
+- Learned owners.
+- Open risk paths.
+- Accept rate.
+
+Optional metrics:
+
+- Observations.
+- Interventions.
+- Memory vectors.
+- Strategy versions.
+
+## Acceptance Criteria
+
+- Default graph is not a hairball.
+- Every visible learned edge has outcome evidence.
+- Every selected node can explain why it matters.
+- Activity stream matches graph events.
+- Graph can be rebuilt from MongoDB source records.
+

docs/graph.md

@@ -76,13 +76,30 @@ Additive routes in `backend/src/server.ts` (shared file — additive only).
 
 - `shared/src/graph.ts` — `PodGraph`, `PodGraphNode/Edge/Metric`, `GraphNodeDoc`, `GraphEdgeDoc`
 - `backend/src/graph/demo.ts` — `createDemoPodGraph(podId)` (grounded in the demo-pod crew)
-- `backend/src/graph/store.ts` — `loadPodGraph`, `seedGraph`, `reachFrom` (`$graphLookup`)
+- `backend/src/graph/live.ts` — **`materializePodGraph(podId)`**: builds the graph from the real
+  collections (pods, engineer_states, observations, collisions, interventions, outcomes)
+- `backend/src/graph/store.ts` — `loadPodGraph` (live → seeded → demo), `seedGraph`, `reachFrom` (`$graphLookup`)
 - `backend/src/graph/seed.ts` — `pnpm graph:seed` (writes demo into `team_model` + graph collections)
 - `frontend/src/lib/graph.ts` — `fetchPodGraph(podId)`
-- `frontend/src/components/GraphView.tsx` — dark-Bauhaus SVG graph (toggle from `App.tsx`)
+- `frontend/src/components/GraphView.tsx` — shadcn-themed SVG graph (theme-aware; toggle from `App.tsx`)
 
-## Demo-first plan
+## Live data → graph mapping
 
-1. Serve `createDemoPodGraph()` from the route (demo-stable, no DB dependency on the demo path).
-2. `pnpm graph:seed` writes the same graph into Mongo so `$graphLookup` is real, not a mock.
-3. Swap `loadPodGraph` to read live `team_model.graph` once the ingest pipeline populates it.
+`materializePodGraph` reads the 5 real collections per pod and emits a `PodGraph`:
+
+| Collection        | Produces                                                                   |
+| ----------------- | -------------------------------------------------------------------------- |
+| `pods.members`    | baseline **engineer** nodes                                                |
+| `engineer_states` | engineer `risk` if unpushed; **file** nodes (git paths parsed); `editing`  |
+| `observations`    | engineer `active`; **file** from `currentFile`; `editing` (strength=conf.) |
+| `collisions`      | **collision** nodes; `collides` (eng→col) + `touches` (file→col)           |
+| `interventions`   | **intervention** nodes; `warns` (col→intervention)                         |
+| `outcomes`        | `learned_from` (intervention→owner) on accepted; flips nodes to `learned`  |
+
+Metrics (learned owners / open risk paths / accept rate) are live counts.
+
+## Fallback order (`loadPodGraph`)
+
+1. **Live** — `materializePodGraph` from the real collections (returns `null` if only bare roster).
+2. **Seeded** — `team_model.graph` (from `pnpm graph:seed`).
+3. **Demo** — `createDemoPodGraph()` (stage safety; never an empty canvas).

docs/livekit.md

@@ -89,11 +89,11 @@ Hermes uses the same endpoint. Grants:
 
 ---
 
-## Gemini Live 2.5 model
+## Gemini voice model
 
-- Model ID: `gemini-live-2.5-flash` — confirm exact ID from LiveKit Agents + Gemini docs at build time
-- LiveKit Agents has native Gemini Live integration — no manual audio encoding needed
-- Hermes passes text string → Agents handles streaming audio publication
+- Model ID: `gemini-3.1-flash-tts-preview`
+- Hermes generates Gemini TTS audio and publishes it as a LiveKit audio track.
+- The backend keeps a Gemini Live path for future model availability, but the verified deployment path uses TTS.
 
 ---
 

docs/superpowers/specs/2026-06-27-podman-design.md

@@ -72,7 +72,7 @@ PodMan is a real-time AI team coordination agent for software teams. Engineers j
 - **Vision:** `gemini-2.0-flash` — screen → `{ currentFile, inferredTask, terminalVisible, recentTerminalOutput, confidence }`
 - **Event detection:** `gemini-2.0-flash` — all engineer states → `{ event, involvedEngineers, file, reason }`
 - **Nudge generation:** `gemini-2.0-flash` — event → spoken message text
-- **Voice:** `gemini-live-2.5-flash` via LiveKit Agents — text → streaming audio
+- **Voice:** `gemini-3.1-flash-tts-preview` via LiveKit audio publication — text → audio
 
 ### MongoDB Atlas (4 collections)
 

frontend/index.html

@@ -4,7 +4,32 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#0b0f17" />
-    <title>PodMan</title>
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>PodMan — the teammate that sees what git can’t</title>
+    <meta
+      name="description"
+      content="PodMan is an ambient AI teammate that watches your pod's screens in realtime and catches merge collisions before anyone pushes."
+    />
+
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="PodMan" />
+    <meta property="og:url" content="https://www.podman.live/" />
+    <meta property="og:title" content="PodMan — the teammate that sees what git can’t" />
+    <meta
+      property="og:description"
+      content="Ambient AI teammate that watches your pod's screens in realtime and catches merge collisions before anyone pushes."
+    />
+    <meta property="og:image" content="https://www.podman.live/og.png" />
+    <meta property="og:image:width" content="1200" />
+    <meta property="og:image:height" content="630" />
+
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="PodMan — the teammate that sees what git can’t" />
+    <meta
+      name="twitter:description"
+      content="Ambient AI teammate that catches merge collisions before anyone pushes."
+    />
+    <meta name="twitter:image" content="https://www.podman.live/og.png" />
   </head>
   <body>
     <div id="root"></div>

frontend/public/favicon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="7" fill="#0b0f17" />
+  <circle cx="25" cy="6.6" r="2.4" fill="#34d399" />
+  <text x="14.5" y="24.5" text-anchor="middle"
+    font-family="ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
+    font-weight="700" font-size="24" fill="#34d399">P</text>
+</svg>

frontend/public/og.svg

@@ -0,0 +1,16 @@
+<svg width="1200" height="630" viewBox="0 0 1200 630" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1200" height="630" fill="#0b0f17" />
+  <g fill="none" stroke="#34d399" opacity="0.12">
+    <circle cx="1050" cy="140" r="70" stroke-width="6" />
+    <circle cx="1050" cy="140" r="140" stroke-width="5" />
+    <circle cx="1050" cy="140" r="215" stroke-width="4" />
+  </g>
+  <rect x="90" y="150" width="104" height="104" rx="24" fill="#0f1629" stroke="#1f2a3a" stroke-width="2" />
+  <circle cx="176" cy="170" r="8.5" fill="#34d399" />
+  <text x="142" y="228" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-weight="bold" font-size="66" fill="#34d399">P</text>
+  <text x="222" y="232" font-family="Helvetica, Arial, sans-serif" font-weight="bold" font-size="68" fill="#e7eaf0">PodMan</text>
+  <text x="92" y="356" font-family="Helvetica, Arial, sans-serif" font-weight="bold" font-size="46" fill="#e7eaf0">The teammate that sees what git can&#8217;t.</text>
+  <text x="92" y="416" font-family="Helvetica, Arial, sans-serif" font-size="34" fill="#9aa4b2">Catches merge collisions before anyone pushes.</text>
+  <rect x="92" y="500" width="13" height="13" rx="3" fill="#34d399" />
+  <text x="118" y="512" font-family="Helvetica, Arial, sans-serif" font-weight="bold" font-size="30" fill="#34d399">podman.live</text>
+</svg>

frontend/src/App.tsx

@@ -268,10 +268,6 @@ export default function App() {
                 <ShieldCheckIcon data-icon="inline-start" />
                 Privacy-limited
               </Badge>
-              <Button variant="outline" onClick={() => setGraphPodId(pods[0]?.id ?? 'demo-pod')}>
-                <BrainCircuitIcon data-icon="inline-start" />
-                Team memory
-              </Button>
               <Button variant="outline" onClick={() => void refresh()} disabled={loading}>
                 <RefreshCwIcon data-icon="inline-start" />
                 Refresh
@@ -342,6 +338,7 @@ export default function App() {
                       onRemoveMember={handleRemoveMember}
                       onUpdate={handleUpdate}
                       onDelete={handleDelete}
+                      onOpenGraph={setGraphPodId}
                     />
                   ))}
                 </div>

frontend/src/components/GraphView.tsx

@@ -1,95 +1,36 @@
-import { useEffect, useMemo, useState, type CSSProperties } from 'react';
-import type { PodGraph, PodGraphNode, PodGraphEdge, PodGraphNodeKind } from '@podman/shared';
-import { fetchPodGraph } from '../lib/graph.js';
+import { useEffect, useMemo, useState } from 'react';
+import type { PodGraph } from '@podman/shared';
+import { fetchPodGraph, backendEventsUrl } from '../lib/graph.js';
+import { Button } from '@/components/ui/button';
+import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+import { GraphCanvas } from './graph/GraphCanvas.js';
+import { MetricsRail } from './graph/MetricsRail.js';
+import { LearningLoop } from './graph/LearningLoop.js';
+import { ActivityStream } from './graph/ActivityStream.js';
+import { SelectedNodePanel } from './graph/SelectedNodePanel.js';
+import { highlightFor, flowNarrative, NODE_LEGEND, EDGE_LEGEND, type Mode } from './graph/encoding.js';
 
-type Mode = 'risk' | 'learn' | 'all';
+const POLL_MS = 5000;
 
-const KIND_COLOR: Record<PodGraphNodeKind, string> = {
-  engineer: '#3B5BFF',
-  file: '#ECE7DA',
-  feature: '#F6C445',
-  collision: '#E2403A',
-  intervention: '#8b6cff',
-};
-
-const EDGE: Record<PodGraphEdge['kind'], { c: string; w: number; dash?: boolean }> = {
-  owns: { c: '#3B5BFF', w: 2.6 },
-  editing: { c: '#ECE7DA', w: 2 },
-  touches: { c: '#5d5d66', w: 1.6 },
-  collides: { c: '#E2403A', w: 3.2 },
-  warns: { c: '#F6C445', w: 3.2 },
-  learned_from: { c: '#8b6cff', w: 2.4, dash: true },
-};
-
-function NodeShape({ node }: { node: PodGraphNode }) {
-  const c = KIND_COLOR[node.kind];
-  const { x, y } = node;
-  switch (node.kind) {
-    case 'engineer':
-      return <rect x={x - 15} y={y - 15} width={30} height={30} fill={c} />;
-    case 'file':
-      return (
-        <rect
-          x={x - 15}
-          y={y - 15}
-          width={30}
-          height={30}
-          fill="none"
-          stroke={c}
-          strokeWidth={2.6}
-        />
-      );
-    case 'feature':
-      return <circle cx={x} cy={y} r={17} fill={c} />;
-    case 'collision':
-      return <polygon points={`${x},${y - 18} ${x + 17},${y + 13} ${x - 17},${y + 13}`} fill={c} />;
-    case 'intervention':
-      return (
-        <polygon points={`${x},${y - 18} ${x + 18},${y} ${x},${y + 18} ${x - 18},${y}`} fill={c} />
-      );
-    default:
-      return null;
+// Note: pm-enter must NOT use animation-fill-mode (both/forwards) — a held final
+// keyframe (opacity:1) would override the .pm-dim cascade and defeat dimming.
+const GRAPH_CSS = `
+  .pm-node{cursor:grab;transition:opacity .25s ease}
+  .pm-node:active{cursor:grabbing}
+  .pm-edge{transition:opacity .25s ease}
+  .pm-lbl{fill:var(--foreground);font-size:11px;font-weight:500;pointer-events:none;
+    paint-order:stroke;stroke:var(--card);stroke-width:3.5px;stroke-linejoin:round}
+  .pm-dim{opacity:.14}
+  .pm-enter{animation:pm-fade .45s ease}
+  .pm-dash{animation:pm-flow 1s linear infinite}
+  .pm-pulse{animation:pm-pulse 1.7s ease-in-out infinite}
+  @keyframes pm-fade{from{opacity:0}to{opacity:1}}
+  @keyframes pm-flow{to{stroke-dashoffset:-26}}
+  @keyframes pm-pulse{0%,100%{opacity:.45}50%{opacity:1}}
+  @media (prefers-reduced-motion:reduce){
+    .pm-enter,.pm-dash,.pm-pulse{animation:none}
   }
-}
-
-interface Highlight {
-  nodes: Set<string>;
-  edges: Set<string>;
-}
-
-function highlightFor(graph: PodGraph, mode: Mode, selected: string | null): Highlight | null {
-  if (selected) {
-    const es = graph.edges.filter((e) => e.source === selected || e.target === selected);
-    return {
-      nodes: new Set([selected, ...es.flatMap((e) => [e.source, e.target])]),
-      edges: new Set(es.map((e) => e.id)),
-    };
-  }
-  if (mode === 'all') return null;
-  const kinds: PodGraphEdge['kind'][] =
-    mode === 'risk' ? ['collides', 'warns', 'learned_from'] : ['learned_from', 'warns'];
-  const collisions = new Set(graph.nodes.filter((n) => n.kind === 'collision').map((n) => n.id));
-  const es = graph.edges.filter(
-    (e) =>
-      kinds.includes(e.kind) ||
-      (mode === 'risk' && (collisions.has(e.target) || collisions.has(e.source))),
-  );
-  return {
-    nodes: new Set(es.flatMap((e) => [e.source, e.target])),
-    edges: new Set(es.map((e) => e.id)),
-  };
-}
-
-const LEGEND: Array<{ label: string; swatch: CSSProperties }> = [
-  { label: 'engineer', swatch: { background: '#3B5BFF' } },
-  { label: 'file', swatch: { border: '2px solid #ECE7DA' } },
-  { label: 'feature', swatch: { background: '#F6C445', borderRadius: '50%' } },
-  {
-    label: 'collision',
-    swatch: { background: '#E2403A', clipPath: 'polygon(50% 0,100% 100%,0 100%)' },
-  },
-  { label: 'intervention', swatch: { background: '#8b6cff', transform: 'rotate(45deg)' } },
-];
+`;
 
 export function GraphView({ podId, onClose }: { podId: string; onClose: () => void }) {
   const [graph, setGraph] = useState<PodGraph | null>(null);
@@ -99,29 +40,67 @@ export function GraphView({ podId, onClose }: { podId: string; onClose: () => vo
 
   useEffect(() => {
     let alive = true;
+    let nudge: number | null = null;
     setGraph(null);
     setError(null);
-    fetchPodGraph(podId)
-      .then((g) => alive && setGraph(g))
-      .catch((e: unknown) => alive && setError(e instanceof Error ? e.message : String(e)));
+    setSelected(null);
+
+    const load = () =>
+      fetchPodGraph(podId)
+        .then((g) => {
+          if (alive) {
+            setGraph(g);
+            setError(null);
+          }
+        })
+        .catch((e: unknown) => {
+          if (alive) setError(e instanceof Error ? e.message : String(e));
+        });
+
+    void load();
+    const poll = window.setInterval(() => void load(), POLL_MS);
+
+    // Best-effort realtime nudge: refetch (debounced) when the agent broadcasts.
+    let ws: WebSocket | null = null;
+    try {
+      ws = new WebSocket(backendEventsUrl());
+      ws.onmessage = () => {
+        if (nudge != null) return;
+        nudge = window.setTimeout(() => {
+          nudge = null;
+          void load();
+        }, 800);
+      };
+    } catch {
+      /* event bus is optional */
+    }
+
     return () => {
       alive = false;
+      window.clearInterval(poll);
+      if (nudge != null) window.clearTimeout(nudge);
+      ws?.close();
     };
   }, [podId]);
 
-  const hi = useMemo(
-    () => (graph ? highlightFor(graph, mode, selected) : null),
-    [graph, mode, selected],
-  );
   const nodeById = useMemo(() => new Map((graph?.nodes ?? []).map((n) => [n.id, n])), [graph]);
-  const sel = selected ? nodeById.get(selected) : undefined;
-  const relCount = selected
-    ? (graph?.edges ?? []).filter((e) => e.source === selected || e.target === selected).length
-    : 0;
+  // A selected node can vanish across a poll/WS refresh. Ignore a stale id so the
+  // graph doesn't dim entirely (highlightFor would otherwise light only a dead id).
+  const liveSelected = selected && nodeById.has(selected) ? selected : null;
+  useEffect(() => {
+    if (selected && graph && !nodeById.has(selected)) setSelected(null);
+  }, [graph, nodeById, selected]);
 
-  const dimNode = (id: string) => (hi ? !hi.nodes.has(id) : false);
-  const dimEdge = (id: string) => (hi ? !hi.edges.has(id) : false);
-  const hotEdge = (id: string) => (hi ? hi.edges.has(id) : false);
+  const highlight = useMemo(
+    () => (graph ? highlightFor(graph, mode, liveSelected) : null),
+    [graph, mode, liveSelected],
+  );
+  const sel = liveSelected ? nodeById.get(liveSelected) : undefined;
+  const relCount = liveSelected
+    ? (graph?.edges ?? []).filter((e) => e.source === liveSelected || e.target === liveSelected)
+        .length
+    : 0;
+  const flow = graph && liveSelected ? flowNarrative(graph, liveSelected) : '';
 
   function pick(next: Mode) {
     setMode(next);
@@ -129,200 +108,111 @@ export function GraphView({ podId, onClose }: { podId: string; onClose: () => vo
   }
 
   return (
-    <div className="pm-graph">
-      <style>{`
-        .pm-graph{--bg:#0c0c0e;--panel:#141417;--line:#2a2a31;--paper:#ECE7DA;--mut:#8d897e;--red:#E2403A;--yel:#F6C445;--vio:#8b6cff;
-          font-family:'Space Grotesk',system-ui,sans-serif;background:var(--bg);color:var(--paper);border:1px solid var(--line);border-radius:14px;overflow:hidden}
-        .pm-graph *{box-sizing:border-box}
-        .pm-hd{display:flex;align-items:center;justify-content:space-between;padding:16px 20px;border-bottom:3px solid var(--paper)}
-        .pm-ttl{font-weight:800;font-size:18px;letter-spacing:.14em;text-transform:uppercase;font-family:Archivo,'Space Grotesk',sans-serif}
-        .pm-sub{font-size:10px;letter-spacing:.3em;color:var(--mut);text-transform:uppercase;margin-top:5px}
-        .pm-x{background:transparent;border:1px solid var(--line);color:var(--paper);font-size:11px;letter-spacing:.1em;text-transform:uppercase;padding:7px 12px;border-radius:2px;cursor:pointer}
-        .pm-x:hover{border-color:var(--paper)}
-        .pm-bar{display:flex;gap:8px;padding:12px 16px;border-bottom:1px solid var(--line);flex-wrap:wrap}
-        .pm-btn{font-size:11px;letter-spacing:.12em;text-transform:uppercase;color:var(--paper);background:transparent;border:1px solid var(--line);padding:7px 12px;cursor:pointer;border-radius:2px}
-        .pm-btn:hover{border-color:var(--paper)}
-        .pm-btn.on{background:var(--red);border-color:var(--red);color:#fff}
-        .pm-grid{display:grid;grid-template-columns:180px 1fr 240px}
-        .pm-col{padding:14px}
-        .pm-railR{border-left:1px solid var(--line);background:#17171b}
-        .pm-st{font-size:11px;letter-spacing:.24em;text-transform:uppercase;color:var(--mut);margin:2px 0 12px}
-        .pm-kpi{border:1px solid var(--line);border-left:5px solid var(--vio);padding:10px 11px;margin-bottom:10px}
-        .pm-num{font-weight:800;font-size:26px;line-height:.9;font-variant-numeric:tabular-nums;font-family:Archivo,sans-serif}
-        .pm-klab{font-size:10px;letter-spacing:.16em;text-transform:uppercase;color:var(--mut);margin-top:6px}
-        .pm-kdet{font-size:10px;color:var(--mut);margin-top:5px;line-height:1.4}
-        .pm-canvas{background:var(--panel);border-left:1px solid var(--line);border-right:1px solid var(--line);min-height:472px}
-        .pm-canvas svg{width:100%;height:auto;display:block}
-        .pm-node{cursor:pointer}
-        .pm-lbl{font-weight:500;font-size:11px;letter-spacing:.06em;fill:var(--paper);text-transform:uppercase}
-        .pm-dim{opacity:.12;transition:opacity .25s}
-        .pm-dkind{font-size:10px;letter-spacing:.24em;text-transform:uppercase;color:var(--mut)}
-        .pm-dname{font-weight:800;font-size:20px;margin:5px 0 8px;font-family:Archivo,sans-serif}
-        .pm-drow{display:flex;justify-content:space-between;font-size:12px;padding:6px 0;border-bottom:1px solid var(--line);color:var(--mut)}
-        .pm-drow b{color:var(--paper);font-weight:500}
-        .pm-note{font-size:12px;color:var(--mut);line-height:1.5;margin-top:10px}
-        .pm-legend{display:flex;gap:14px;flex-wrap:wrap;padding:10px 16px;border-top:1px solid var(--line);font-size:10px;letter-spacing:.06em;text-transform:uppercase;color:var(--mut)}
-        .pm-lg{display:flex;align-items:center;gap:6px}
-        .pm-sw{width:13px;height:13px;display:inline-block}
-        @media(max-width:760px){.pm-grid{grid-template-columns:1fr}.pm-railR{border-left:0;border-top:1px solid var(--line)}.pm-canvas{border:0;border-top:1px solid var(--line)}}
-      `}</style>
+    <div className="min-h-screen bg-background text-foreground">
+      <style>{GRAPH_CSS}</style>
+      <div className="mx-auto w-full max-w-7xl px-4 py-4 sm:px-6 lg:px-8">
+        <div className="overflow-hidden rounded-xl border bg-card text-card-foreground shadow-sm">
+          {/* Header */}
+          <div className="flex items-center justify-between gap-3 border-b px-5 py-4">
+            <div className="min-w-0">
+              <div className="flex items-center gap-2">
+                <h2 className="font-heading text-base font-medium">Team memory</h2>
+                <span className="inline-flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-[0.65rem] font-medium uppercase tracking-wide text-muted-foreground">
+                  <span className="pm-pulse inline-block size-1.5 rounded-full bg-[#16a34a]" />
+                  Live
+                </span>
+              </div>
+              <p className="mt-0.5 truncate text-xs text-muted-foreground">
+                What PodMan learned · {podId}
+              </p>
+            </div>
+            <Button variant="outline" size="sm" onClick={onClose}>
+              ← Pods
+            </Button>
+          </div>
 
-      <div className="pm-hd">
-        <div>
-          <div className="pm-ttl">Team memory</div>
-          <div className="pm-sub">What PodMan learned · {podId}</div>
-        </div>
-        <button className="pm-x" onClick={onClose}>
-          ← Pods
-        </button>
-      </div>
+          {/* Toggles */}
+          <div className="flex flex-wrap items-center gap-2 border-b px-4 py-3">
+            <ToggleGroup
+              type="single"
+              value={mode}
+              onValueChange={(v) => v && pick(v as Mode)}
+              variant="outline"
+              size="sm"
+            >
+              <ToggleGroupItem value="risk">Risk path</ToggleGroupItem>
+              <ToggleGroupItem value="learn">Learning edges</ToggleGroupItem>
+              <ToggleGroupItem value="all">Whole graph</ToggleGroupItem>
+            </ToggleGroup>
+            <span className="ml-auto hidden text-xs text-muted-foreground sm:inline">
+              Drag to rearrange · double-click to release · click to inspect
+            </span>
+          </div>
 
-      <div className="pm-bar">
-        <button
-          className={`pm-btn ${mode === 'risk' && !selected ? 'on' : ''}`}
-          onClick={() => pick('risk')}
-        >
-          Risk path
-        </button>
-        <button
-          className={`pm-btn ${mode === 'learn' && !selected ? 'on' : ''}`}
-          onClick={() => pick('learn')}
-        >
-          Learning edges
-        </button>
-        <button
-          className={`pm-btn ${mode === 'all' && !selected ? 'on' : ''}`}
-          onClick={() => pick('all')}
-        >
-          Whole graph
-        </button>
-      </div>
+          {error && <p className="px-4 py-4 text-sm text-destructive">Graph error: {error}</p>}
+          {!graph && !error && (
+            <p className="px-4 py-10 text-center text-sm text-muted-foreground">Loading graph…</p>
+          )}
 
-      {error && (
-        <p style={{ padding: '16px', color: '#ff7d76', fontSize: 13 }}>Graph error: {error}</p>
-      )}
-      {!graph && !error && (
-        <p style={{ padding: '16px', color: '#8d897e', fontSize: 13 }}>Loading graph…</p>
-      )}
+          {graph && (
+            <>
+              {/* Metrics · graph · learning loop */}
+              <div className="grid gap-4 p-4 lg:grid-cols-[180px_minmax(0,1fr)_212px]">
+                <MetricsRail metrics={graph.metrics} />
 
-      {graph && (
-        <>
-          <div className="pm-grid">
-            <div className="pm-col">
-              <div className="pm-st">Workflow metrics</div>
-              {graph.metrics.map((m) => (
-                <div className="pm-kpi" key={m.label}>
-                  <div className="pm-num">{m.value}</div>
-                  <div className="pm-klab">{m.label}</div>
-                  <div className="pm-kdet">{m.detail}</div>
+                <div className="flex min-h-[440px] flex-col overflow-hidden rounded-xl border bg-card">
+                  <GraphCanvas
+                    graph={graph}
+                    highlight={highlight}
+                    selected={liveSelected}
+                    onSelect={setSelected}
+                  />
                 </div>
-              ))}
-            </div>
 
-            <div className="pm-canvas">
-              <svg viewBox="0 0 720 472" role="img" aria-label="PodMan team-memory graph">
-                {graph.edges.map((e) => {
-                  const a = nodeById.get(e.source);
-                  const b = nodeById.get(e.target);
-                  if (!a || !b) return null;
-                  const s = EDGE[e.kind];
-                  return (
-                    <line
-                      key={e.id}
-                      className={dimEdge(e.id) ? 'pm-dim' : undefined}
-                      x1={a.x}
-                      y1={a.y}
-                      x2={b.x}
-                      y2={b.y}
-                      stroke={s.c}
-                      strokeWidth={hotEdge(e.id) ? s.w + 1.6 : s.w}
-                      strokeDasharray={s.dash ? '7 6' : undefined}
-                      strokeLinecap="round"
-                    />
-                  );
-                })}
-                {graph.nodes.map((n) => (
-                  <g
-                    key={n.id}
-                    className={`pm-node ${dimNode(n.id) ? 'pm-dim' : ''}`}
-                    role="button"
-                    tabIndex={0}
-                    aria-label={`${n.kind}: ${n.label}`}
-                    onClick={() => setSelected((cur) => (cur === n.id ? null : n.id))}
-                    onKeyDown={(ev) => {
-                      if (ev.key === 'Enter' || ev.key === ' ') {
-                        ev.preventDefault();
-                        setSelected((cur) => (cur === n.id ? null : n.id));
-                      }
-                    }}
-                  >
-                    <NodeShape node={n} />
-                    <text className="pm-lbl" x={n.x} y={n.y + 33} textAnchor="middle">
-                      {n.label.toUpperCase()}
-                    </text>
-                  </g>
+                {graph.loop?.length ? (
+                  <LearningLoop stages={graph.loop} />
+                ) : (
+                  <div />
+                )}
+              </div>
+
+              {/* Activity stream · selected node */}
+              <div className="grid gap-4 border-t px-4 py-4 lg:grid-cols-[minmax(0,1fr)_320px]">
+                <div className="rounded-xl border bg-card p-4">
+                  <ActivityStream events={graph.activity ?? []} />
+                </div>
+                <div className="rounded-xl border bg-muted/40 p-4">
+                  <SelectedNodePanel node={sel} relCount={relCount} flow={flow} mode={mode} />
+                </div>
+              </div>
+
+              {/* Legend */}
+              <div className="flex flex-wrap items-center gap-x-3 gap-y-1.5 border-t px-4 py-2.5 text-xs text-muted-foreground">
+                {NODE_LEGEND.map((l) => (
+                  <span key={l.label} className="flex items-center gap-1.5">
+                    <span className="inline-block size-3" style={l.swatch} />
+                    {l.label}
+                  </span>
                 ))}
-              </svg>
-            </div>
-
-            <div className="pm-col pm-railR">
-              {sel ? (
-                <>
-                  <div className="pm-dkind">{sel.kind}</div>
-                  <div className="pm-dname">{sel.label}</div>
-                  <div className="pm-drow">
-                    <span>Status</span>
-                    <b
-                      style={{
-                        color:
-                          sel.status === 'risk'
-                            ? '#E2403A'
-                            : sel.status === 'learned'
-                              ? '#b7a4ff'
-                              : '#ECE7DA',
-                      }}
-                    >
-                      {sel.status}
-                    </b>
-                  </div>
-                  <div className="pm-drow">
-                    <span>Relationships</span>
-                    <b>{relCount}</b>
-                  </div>
-                  <div className="pm-note">{sel.summary}</div>
-                </>
-              ) : (
-                <>
-                  <div className="pm-dkind">Continual learning</div>
-                  <div className="pm-dname">It learned</div>
-                  <div className="pm-note">
-                    Violet <b style={{ color: '#b7a4ff' }}>learned_from</b> edges are ownership
-                    PodMan retained from accepted interventions — the graph gets sharper every
-                    session. Click any node to trace its relationships.
-                  </div>
-                </>
-              )}
-            </div>
-          </div>
-
-          <div className="pm-legend">
-            {LEGEND.map((l) => (
-              <span className="pm-lg" key={l.label}>
-                <span className="pm-sw" style={l.swatch} />
-                {l.label}
-              </span>
-            ))}
-            <span className="pm-lg">
-              <span className="pm-sw" style={{ background: '#E2403A', height: 3 }} />
-              collides
-            </span>
-            <span className="pm-lg">
-              <span className="pm-sw" style={{ background: '#8b6cff', height: 3 }} />
-              learned_from
-            </span>
-          </div>
-        </>
-      )}
+                <span className="mx-1 h-3 w-px bg-border" aria-hidden />
+                {EDGE_LEGEND.map((l) => (
+                  <span key={l.label} className="flex items-center gap-1.5">
+                    <span
+                      className="inline-block h-[3px] w-3.5"
+                      style={
+                        l.dash
+                          ? { backgroundImage: `repeating-linear-gradient(90deg, ${l.color} 0 3px, transparent 3px 6px)` }
+                          : { background: l.color }
+                      }
+                    />
+                    {l.label}
+                  </span>
+                ))}
+              </div>
+            </>
+          )}
+        </div>
+      </div>
     </div>
   );
 }

frontend/src/components/PodCard.tsx

@@ -1,5 +1,12 @@
 import { useState } from 'react';
-import { MoreHorizontalIcon, PlusIcon, Trash2Icon, UserRoundIcon, VideoIcon } from 'lucide-react';
+import {
+  BrainCircuitIcon,
+  MoreHorizontalIcon,
+  PlusIcon,
+  Trash2Icon,
+  UserRoundIcon,
+  VideoIcon,
+} from 'lucide-react';
 import type { Pod, PodInput } from '@podman/shared';
 import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup } from '@/components/ui/avatar';
 import { Badge } from '@/components/ui/badge';
@@ -42,6 +49,7 @@ export function PodCard({
   onRemoveMember: _onRemoveMember,
   onUpdate,
   onDelete,
+  onOpenGraph,
 }: {
   pod: Pod;
   busy: boolean;
@@ -52,6 +60,7 @@ export function PodCard({
   onRemoveMember: (id: string, name: string) => void;
   onUpdate: (id: string, patch: PodInput) => void;
   onDelete: (id: string) => void;
+  onOpenGraph: (id: string) => void;
 }) {
   const [newMember, setNewMember] = useState('');
   const [editing, setEditing] = useState(false);
@@ -100,6 +109,10 @@ export function PodCard({
               </DropdownMenuTrigger>
               <DropdownMenuContent align="end">
                 <DropdownMenuGroup>
+                  <DropdownMenuItem onSelect={() => onOpenGraph(pod.id)}>
+                    <BrainCircuitIcon />
+                    Team memory
+                  </DropdownMenuItem>
                   <DropdownMenuItem onSelect={() => setEditing(true)}>Edit pod</DropdownMenuItem>
                   <DropdownMenuItem
                     variant="destructive"

frontend/src/components/PodView.tsx

@@ -4,6 +4,8 @@ import {
   ArrowLeftIcon,
   CheckIcon,
   CircleDotIcon,
+  ExternalLinkIcon,
+  MessageSquareIcon,
   MonitorUpIcon,
   RadioTowerIcon,
   SparklesIcon,
@@ -80,7 +82,7 @@ export function PodView({
   const [sharing, setSharing] = useState(false);
   const [playingBeat, setPlayingBeat] = useState(false);
   const [note, setNote] = useState<string | null>(null);
-  const { active, respond } = useInterventions(room);
+  const { active, hermes, voiceCue, actionUrl, respond } = useInterventions(room);
 
   const audioRef = useRef<HTMLDivElement>(null);
   const beatRef = useRef<BeatHandle | null>(null);
@@ -181,6 +183,15 @@ export function PodView({
     }
   }
 
+  async function answerIntervention(status: 'accepted' | 'dismissed', accepted: boolean) {
+    setNote(null);
+    try {
+      await respond(status, accepted);
+    } catch (e) {
+      setNote(`Action failed: ${(e as Error).message}`);
+    }
+  }
+
   const podmanPresent = participants.some((p) => p.name.toLowerCase() === 'podman');
 
   return (
@@ -299,6 +310,24 @@ export function PodView({
                         {active.suggestedAction.kind.replaceAll('_', ' ')}
                       </Badge>
                     </div>
+                    {hermes?.interventionId === active.id && (
+                      <div className="rounded-lg border border-dashed p-3">
+                        <div className="mb-1 flex items-center gap-2 text-xs font-medium text-muted-foreground">
+                          <MessageSquareIcon className="size-3.5" />
+                          Hermes message
+                        </div>
+                        <p className="text-sm leading-6">{hermes.text}</p>
+                      </div>
+                    )}
+                    {voiceCue && (
+                      <div className="rounded-lg border border-dashed p-3">
+                        <div className="mb-1 flex items-center gap-2 text-xs font-medium text-muted-foreground">
+                          <Volume2Icon className="size-3.5" />
+                          Voice cue
+                        </div>
+                        <p className="text-sm leading-6">{voiceCue}</p>
+                      </div>
+                    )}
                   </div>
                 ) : (
                   <Empty className="min-h-72 border-0 p-0">
@@ -314,14 +343,28 @@ export function PodView({
                     </EmptyHeader>
                   </Empty>
                 )}
+                {actionUrl && (
+                  <a
+                    href={actionUrl}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="mt-4 flex items-center justify-between gap-3 rounded-lg border bg-muted/30 px-3 py-2 text-sm font-medium hover:bg-muted"
+                  >
+                    Sync PR artifact opened
+                    <ExternalLinkIcon className="size-4" />
+                  </a>
+                )}
               </CardContent>
               {active && (
                 <CardFooter className="justify-end gap-2">
-                  <Button variant="outline" onClick={() => void respond('dismissed', false)}>
+                  <Button
+                    variant="outline"
+                    onClick={() => void answerIntervention('dismissed', false)}
+                  >
                     <XIcon data-icon="inline-start" />
                     Dismiss
                   </Button>
-                  <Button onClick={() => void respond('accepted', true)}>
+                  <Button onClick={() => void answerIntervention('accepted', true)}>
                     <CheckIcon data-icon="inline-start" />
                     Accept
                   </Button>

frontend/src/components/graph/ActivityStream.tsx

@@ -0,0 +1,45 @@
+import type { ActivityEvent } from '@podman/shared';
+import { ScrollArea } from '@/components/ui/scroll-area';
+import { ACTIVITY_TAG } from './encoding.js';
+
+const fmtTime = new Intl.DateTimeFormat([], { hour: '2-digit', minute: '2-digit', hour12: false });
+
+function timeOf(at: string): string {
+  const t = new Date(at).getTime();
+  return Number.isFinite(t) ? fmtTime.format(t) : '--:--';
+}
+
+export function ActivityStream({ events }: { events: ActivityEvent[] }) {
+  return (
+    <div className="flex h-full flex-col">
+      <p className="mb-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+        Activity stream
+      </p>
+      {events.length === 0 ? (
+        <p className="text-sm text-muted-foreground">No activity yet.</p>
+      ) : (
+        <ScrollArea className="h-[176px] pr-3">
+          <ul className="space-y-1.5">
+            {events.map((e) => {
+              const tag = ACTIVITY_TAG[e.kind];
+              return (
+                <li key={e.id} className="pm-enter flex items-start gap-2.5 text-sm">
+                  <span className="mt-0.5 shrink-0 font-mono text-xs tabular-nums text-muted-foreground">
+                    {timeOf(e.at)}
+                  </span>
+                  <span
+                    className="mt-0.5 shrink-0 rounded px-1.5 py-0.5 text-[0.6rem] font-semibold uppercase tracking-wide"
+                    style={{ color: tag.color, background: `${tag.color}1a` }}
+                  >
+                    {tag.label}
+                  </span>
+                  <span className="min-w-0 flex-1 leading-snug text-foreground/90">{e.text}</span>
+                </li>
+              );
+            })}
+          </ul>
+        </ScrollArea>
+      )}
+    </div>
+  );
+}

frontend/src/components/graph/GraphCanvas.tsx

@@ -0,0 +1,333 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ReactElement,
+  type PointerEvent,
+} from 'react';
+import type { PodGraph, PodGraphNode, PodGraphNodeKind } from '@podman/shared';
+import { ForceSim } from './forceSim.js';
+import { EDGE, KIND_COLOR, nodeRadius, type Highlight } from './encoding.js';
+
+const W = 760;
+const H = 480;
+const MARGIN = 48;
+
+/** Map the server's 0..720×0..472 layout into the canvas as a seed position. */
+function mapX(x: number): number {
+  return MARGIN + (Math.max(0, Math.min(720, x)) / 720) * (W - 2 * MARGIN);
+}
+function mapY(y: number): number {
+  return MARGIN + (Math.max(0, Math.min(472, y)) / 472) * (H - 2 * MARGIN);
+}
+
+function linkDistance(kind: string): number {
+  if (kind === 'collides') return 122;
+  if (kind === 'owns') return 104;
+  if (kind === 'learned_from') return 150;
+  return 134;
+}
+function linkStrength(strength: number): number {
+  return Math.max(0.18, Math.min(0.9, strength));
+}
+
+/** Stable +/- so parallel edges between the same pair fan to opposite sides. */
+function curveSign(id: string): number {
+  let h = 0;
+  for (let i = 0; i < id.length; i++) h = (h + id.charCodeAt(i)) % 2;
+  return h === 0 ? 1 : -1;
+}
+
+function edgePath(ax: number, ay: number, bx: number, by: number, id: string): string {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const len = Math.hypot(dx, dy) || 1;
+  const nx = -dy / len;
+  const ny = dx / len;
+  const off = curveSign(id) * len * 0.13;
+  const cx = (ax + bx) / 2 + nx * off;
+  const cy = (ay + by) / 2 + ny * off;
+  return `M${ax.toFixed(1)},${ay.toFixed(1)} Q${cx.toFixed(1)},${cy.toFixed(1)} ${bx.toFixed(1)},${by.toFixed(1)}`;
+}
+
+function nodeShape(
+  kind: PodGraphNodeKind,
+  color: string,
+  cx: number,
+  cy: number,
+  r: number,
+): ReactElement | null {
+  switch (kind) {
+    case 'engineer':
+      return <rect x={cx - r} y={cy - r} width={r * 2} height={r * 2} rx={4} fill={color} />;
+    case 'file':
+      return (
+        <rect
+          x={cx - r}
+          y={cy - r}
+          width={r * 2}
+          height={r * 2}
+          rx={4}
+          fill="var(--card)"
+          stroke={color}
+          strokeWidth={2.4}
+        />
+      );
+    case 'feature':
+      return <circle cx={cx} cy={cy} r={r} fill={color} />;
+    case 'collision':
+      return (
+        <polygon
+          points={`${cx},${cy - r} ${cx + r},${cy + r * 0.78} ${cx - r},${cy + r * 0.78}`}
+          fill={color}
+        />
+      );
+    case 'intervention':
+      return (
+        <polygon points={`${cx},${cy - r} ${cx + r},${cy} ${cx},${cy + r} ${cx - r},${cy}`} fill={color} />
+      );
+    default:
+      return null;
+  }
+}
+
+function showLabel(
+  node: PodGraphNode,
+  dimmed: boolean,
+  hovered: boolean,
+  selected: boolean,
+): boolean {
+  if (hovered || selected) return true;
+  if (dimmed) return false;
+  // Collisions cluster and often share a filename — reveal on hover/select only.
+  if (node.kind === 'collision') return false;
+  return true;
+}
+
+interface DragState {
+  id: string;
+  pointerId: number;
+  moved: boolean;
+}
+
+export function GraphCanvas({
+  graph,
+  highlight,
+  selected,
+  onSelect,
+}: {
+  graph: PodGraph;
+  highlight: Highlight | null;
+  selected: string | null;
+  onSelect: (id: string | null) => void;
+}) {
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  const simRef = useRef<ForceSim | null>(null);
+  if (!simRef.current) simRef.current = new ForceSim(W, H);
+  const rafRef = useRef<number | null>(null);
+  const dragRef = useRef<DragState | null>(null);
+  const sigRef = useRef<string>('');
+  const [, setFrame] = useState(0);
+  const [hovered, setHovered] = useState<string | null>(null);
+
+  const loop = useCallback(() => {
+    const sim = simRef.current;
+    if (!sim) return;
+    const working = sim.tick();
+    setFrame((f) => (f + 1) % 1_000_000);
+    if (working || dragRef.current) {
+      rafRef.current = requestAnimationFrame(loop);
+    } else {
+      rafRef.current = null;
+    }
+  }, []);
+
+  const ensureRaf = useCallback(() => {
+    if (rafRef.current == null) rafRef.current = requestAnimationFrame(loop);
+  }, [loop]);
+
+  // Rebuild the simulation when the graph data changes, preserving positions.
+  useEffect(() => {
+    const sim = simRef.current;
+    if (!sim) return;
+    const nodeInputs = graph.nodes.map((n) => ({
+      id: n.id,
+      radius: nodeRadius(n),
+      seedX: mapX(n.x),
+      seedY: mapY(n.y),
+    }));
+    const linkInputs = graph.edges.map((e) => ({
+      source: e.source,
+      target: e.target,
+      distance: linkDistance(e.kind),
+      strength: linkStrength(e.strength),
+    }));
+    const sig =
+      nodeInputs
+        .map((n) => n.id)
+        .sort()
+        .join(',') +
+      '|' +
+      graph.edges
+        .map((e) => e.id)
+        .sort()
+        .join(',');
+    const first = sigRef.current === '';
+    const changed = sig !== sigRef.current;
+    sim.setData(nodeInputs, linkInputs);
+    if (changed) {
+      sigRef.current = sig;
+      sim.reheat(first ? 1 : 0.5);
+    }
+    // Always (re)arm the loop — ensureRaf is idempotent via the rafRef==null
+    // guard. This must NOT be gated on `changed`: under React StrictMode the
+    // dev double-invoke cancels the frame between effect passes, and pass 2 sees
+    // an unchanged sig, so a `changed`-gated start would leave the sim frozen.
+    if (sim.nodes.length) ensureRaf();
+  }, [graph, ensureRaf]);
+
+  // Clean up the animation frame on unmount.
+  useEffect(() => {
+    return () => {
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+      rafRef.current = null;
+    };
+  }, []);
+
+  function toSvg(evt: PointerEvent): { x: number; y: number } {
+    const svg = svgRef.current;
+    if (!svg) return { x: 0, y: 0 };
+    const ctm = svg.getScreenCTM();
+    if (!ctm) return { x: 0, y: 0 };
+    const p = new DOMPoint(evt.clientX, evt.clientY).matrixTransform(ctm.inverse());
+    return { x: p.x, y: p.y };
+  }
+
+  function onNodePointerDown(evt: PointerEvent, id: string) {
+    evt.stopPropagation();
+    const sim = simRef.current;
+    if (!sim) return;
+    (evt.currentTarget as Element).setPointerCapture(evt.pointerId);
+    dragRef.current = { id, pointerId: evt.pointerId, moved: false };
+    const { x, y } = toSvg(evt);
+    sim.pin(id, x, y);
+    sim.setActive(true);
+    ensureRaf();
+  }
+
+  function onNodePointerMove(evt: PointerEvent) {
+    const drag = dragRef.current;
+    const sim = simRef.current;
+    if (!drag || !sim || drag.pointerId !== evt.pointerId) return;
+    drag.moved = true;
+    const { x, y } = toSvg(evt);
+    sim.pin(drag.id, x, y);
+    ensureRaf();
+  }
+
+  function onNodePointerUp(evt: PointerEvent, id: string) {
+    const drag = dragRef.current;
+    const sim = simRef.current;
+    if (!drag || !sim || drag.pointerId !== evt.pointerId) return;
+    (evt.currentTarget as Element).releasePointerCapture?.(evt.pointerId);
+    sim.setActive(false);
+    // A press that never moved is a click — toggle selection (node stays pinned).
+    if (!drag.moved) onSelect(selected === id ? null : id);
+    dragRef.current = null;
+    ensureRaf();
+  }
+
+  function onNodeDoubleClick(id: string) {
+    const sim = simRef.current;
+    if (!sim) return;
+    sim.unpin(id);
+    sim.reheat(0.5);
+    ensureRaf();
+  }
+
+  const sim = simRef.current;
+  const dimNode = (id: string) => (highlight ? !highlight.nodes.has(id) : false);
+  const dimEdge = (id: string) => (highlight ? !highlight.edges.has(id) : false);
+  const hotEdge = (id: string) => (highlight ? highlight.edges.has(id) : false);
+
+  return (
+    <svg
+      ref={svgRef}
+      viewBox={`0 0 ${W} ${H}`}
+      role="img"
+      aria-label="PodMan team-memory graph — drag nodes to rearrange"
+      className="block h-full max-h-[560px] w-full touch-none select-none"
+      onPointerDown={() => onSelect(null)}
+    >
+      <g>
+        {graph.edges.map((e) => {
+          const a = sim?.get(e.source);
+          const b = sim?.get(e.target);
+          if (!a || !b) return null;
+          const style = EDGE[e.kind];
+          const hot = hotEdge(e.id);
+          return (
+            <path
+              key={e.id}
+              className={`pm-edge pm-enter ${dimEdge(e.id) ? 'pm-dim' : ''} ${e.kind === 'learned_from' ? 'pm-dash' : ''}`}
+              d={edgePath(a.x, a.y, b.x, b.y, e.id)}
+              fill="none"
+              stroke={style.c}
+              strokeWidth={hot ? style.w + 1.4 : style.w}
+              strokeOpacity={hot ? 1 : 0.78}
+              strokeDasharray={style.dash ? '7 6' : undefined}
+              strokeLinecap="round"
+            />
+          );
+        })}
+      </g>
+      <g>
+        {graph.nodes.map((n) => {
+          const p = sim?.get(n.id);
+          if (!p) return null;
+          const r = p.radius;
+          const dimmed = dimNode(n.id);
+          const isHover = hovered === n.id;
+          const isSel = selected === n.id;
+          const color = KIND_COLOR[n.kind];
+          const pinned = p.fx != null;
+          return (
+            <g
+              key={n.id}
+              className={`pm-node pm-enter ${dimmed ? 'pm-dim' : ''}`}
+              role="button"
+              tabIndex={0}
+              aria-label={`${n.kind}: ${n.label}`}
+              onPointerDown={(ev) => onNodePointerDown(ev, n.id)}
+              onPointerMove={onNodePointerMove}
+              onPointerUp={(ev) => onNodePointerUp(ev, n.id)}
+              onDoubleClick={() => onNodeDoubleClick(n.id)}
+              onMouseEnter={() => setHovered(n.id)}
+              onMouseLeave={() => setHovered((cur) => (cur === n.id ? null : cur))}
+              onKeyDown={(ev) => {
+                if (ev.key === 'Enter' || ev.key === ' ') {
+                  ev.preventDefault();
+                  onSelect(selected === n.id ? null : n.id);
+                }
+              }}
+            >
+              {(isSel || isHover) && (
+                <circle cx={p.x} cy={p.y} r={r + 7} fill="none" stroke={color} strokeWidth={2} strokeOpacity={0.5} />
+              )}
+              {pinned && !isSel && !isHover && (
+                <circle cx={p.x} cy={p.y} r={r + 4} fill="none" stroke={color} strokeWidth={1} strokeDasharray="2 3" strokeOpacity={0.4} />
+              )}
+              {nodeShape(n.kind, color, p.x, p.y, r)}
+              {showLabel(n, dimmed, isHover, isSel) && (
+                <text className="pm-lbl" x={p.x} y={p.y + r + 13} textAnchor="middle">
+                  {n.label}
+                </text>
+              )}
+            </g>
+          );
+        })}
+      </g>
+    </svg>
+  );
+}

frontend/src/components/graph/LearningLoop.tsx

@@ -0,0 +1,43 @@
+import type { LearningStage } from '@podman/shared';
+import { BLUE } from './encoding.js';
+
+/**
+ * The continual-learning loop rail: observe → store → predict → outcome → adapt.
+ * The active stage (most-recent activity) gets a pulsing accent bar + ring.
+ */
+export function LearningLoop({ stages }: { stages: LearningStage[] }) {
+  return (
+    <div className="space-y-1">
+      <p className="mb-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+        Learning loop
+      </p>
+      {stages.map((s, i) => (
+        <div key={s.key}>
+          <div
+            className="relative overflow-hidden rounded-lg border bg-card py-2 pl-3.5 pr-3 shadow-sm transition-colors data-[active=true]:bg-accent/40"
+            data-active={s.active}
+            style={s.active ? { boxShadow: `inset 0 0 0 1px ${BLUE}55` } : undefined}
+          >
+            <span
+              aria-hidden
+              className={`absolute inset-y-0 left-0 w-1 ${s.active ? 'pm-pulse' : ''}`}
+              style={{ background: s.active ? BLUE : 'var(--border)' }}
+            />
+            <div className="flex items-baseline justify-between gap-2">
+              <p className="text-[0.7rem] font-medium uppercase tracking-wide text-muted-foreground">
+                <span className="tabular-nums">{String(i + 1).padStart(2, '0')}</span> {s.title}
+              </p>
+              <p className="font-heading text-sm font-semibold tabular-nums">{s.value}</p>
+            </div>
+            <p className="mt-0.5 text-xs leading-snug text-muted-foreground">{s.detail}</p>
+          </div>
+          {i < stages.length - 1 && (
+            <p aria-hidden className="py-0.5 text-center text-xs leading-none text-muted-foreground/60">
+              ↓
+            </p>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}

frontend/src/components/graph/MetricsRail.tsx

@@ -0,0 +1,37 @@
+import type { PodGraphMetric } from '@podman/shared';
+import { BLUE, RED, VIOLET, GREEN, AMBER } from './encoding.js';
+
+const ACCENTS: Array<{ test: RegExp; color: string }> = [
+  { test: /risk|collision|open/i, color: RED },
+  { test: /accept/i, color: GREEN },
+  { test: /learn|owner|adapt/i, color: VIOLET },
+  { test: /vector|memory|store/i, color: AMBER },
+];
+
+function accentFor(label: string, i: number): string {
+  for (const a of ACCENTS) if (a.test.test(label)) return a.color;
+  return [BLUE, RED, VIOLET, GREEN, AMBER][i % 5] ?? BLUE;
+}
+
+export function MetricsRail({ metrics }: { metrics: PodGraphMetric[] }) {
+  return (
+    <div className="space-y-2.5">
+      <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+        Workflow metrics
+      </p>
+      {metrics.map((m, i) => (
+        <div
+          key={m.label}
+          className="rounded-lg border bg-card py-2.5 pl-3 pr-3 shadow-sm"
+          style={{ borderLeftWidth: 3, borderLeftColor: accentFor(m.label, i) }}
+        >
+          <p className="font-heading text-2xl font-semibold leading-none tabular-nums">{m.value}</p>
+          <p className="mt-1.5 text-[0.7rem] font-medium uppercase tracking-wide text-muted-foreground">
+            {m.label}
+          </p>
+          <p className="mt-1 text-xs leading-snug text-muted-foreground">{m.detail}</p>
+        </div>
+      ))}
+    </div>
+  );
+}

frontend/src/components/graph/SelectedNodePanel.tsx

@@ -0,0 +1,63 @@
+import type { PodGraphNode } from '@podman/shared';
+import { Badge } from '@/components/ui/badge';
+import { statusColor, modeBlurb, VIOLET, type Mode } from './encoding.js';
+
+export function SelectedNodePanel({
+  node,
+  relCount,
+  flow,
+  mode,
+}: {
+  node: PodGraphNode | undefined;
+  relCount: number;
+  flow: string;
+  mode: Mode;
+}) {
+  if (!node) {
+    return (
+      <div className="flex h-full flex-col">
+        <p className="mb-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+          {mode === 'learn' ? 'Learning edges' : mode === 'all' ? 'Whole graph' : 'Risk path'}
+        </p>
+        <h3 className="mb-2 font-heading text-base font-medium">What you're looking at</h3>
+        <p className="text-sm leading-relaxed text-muted-foreground">{modeBlurb(mode)}</p>
+        <p className="mt-3 text-sm leading-relaxed text-muted-foreground">
+          Click any node to trace its{' '}
+          <span className="font-medium" style={{ color: VIOLET }}>
+            flow
+          </span>{' '}
+          — what PodMan saw, flagged, and learned. Drag to rearrange.
+        </p>
+      </div>
+    );
+  }
+  return (
+    <div className="flex h-full flex-col">
+      <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+        {node.kind}
+      </p>
+      <h3 className="mb-2 mt-0.5 font-heading text-lg font-medium">{node.label}</h3>
+      <div className="flex items-center justify-between border-b py-1.5 text-sm text-muted-foreground">
+        <span>Status</span>
+        <Badge variant="outline" style={{ color: statusColor(node.status) }}>
+          {node.status}
+        </Badge>
+      </div>
+      <div className="flex items-center justify-between border-b py-1.5 text-sm text-muted-foreground">
+        <span>Relationships</span>
+        <span className="font-medium text-foreground">{relCount}</span>
+      </div>
+      {flow && (
+        <>
+          <p className="mt-2.5 text-[0.7rem] font-medium uppercase tracking-wide text-muted-foreground">
+            Flow
+          </p>
+          <p className="mt-1 text-sm leading-relaxed text-foreground/90">{flow}</p>
+        </>
+      )}
+      {node.summary && node.summary !== flow && (
+        <p className="mt-2 text-xs leading-relaxed text-muted-foreground">{node.summary}</p>
+      )}
+    </div>
+  );
+}

frontend/src/components/graph/encoding.ts

@@ -0,0 +1,209 @@
+import type { CSSProperties } from 'react';
+import type {
+  PodGraph,
+  PodGraphNode,
+  PodGraphEdge,
+  PodGraphNodeKind,
+  ActivityKind,
+} from '@podman/shared';
+
+/**
+ * Fixed, light-readable hues for the node/edge encoding. Kept stable across
+ * light/dark so kinds stay distinguishable; only the chrome uses shadcn tokens.
+ */
+export const BLUE = '#2563eb';
+export const SLATE = '#475569';
+export const SLATE_EDGE = '#94a3b8';
+export const SLATE_FAINT = '#cbd5e1';
+export const AMBER = '#d97706';
+export const RED = '#dc2626';
+export const VIOLET = '#7c3aed';
+export const GREEN = '#16a34a';
+
+/** Tag color + short label per activity-stream kind. */
+export const ACTIVITY_TAG: Record<ActivityKind, { color: string; label: string }> = {
+  editing: { color: SLATE, label: 'EDITING' },
+  collision: { color: RED, label: 'COLLISION' },
+  warns: { color: AMBER, label: 'WARNS' },
+  outcome: { color: GREEN, label: 'OUTCOME' },
+  learned_from: { color: VIOLET, label: 'LEARNED' },
+};
+
+export const KIND_COLOR: Record<PodGraphNodeKind, string> = {
+  engineer: BLUE,
+  file: SLATE,
+  feature: AMBER,
+  collision: RED,
+  intervention: VIOLET,
+};
+
+export interface EdgeStyle {
+  c: string;
+  w: number;
+  dash?: boolean;
+}
+
+export const EDGE: Record<PodGraphEdge['kind'], EdgeStyle> = {
+  owns: { c: BLUE, w: 2.4 },
+  editing: { c: SLATE_EDGE, w: 1.9 },
+  touches: { c: SLATE_FAINT, w: 1.5 },
+  collides: { c: RED, w: 2.8 },
+  warns: { c: AMBER, w: 2.8 },
+  learned_from: { c: VIOLET, w: 2.4, dash: true },
+};
+
+/** Collision/drawing radius for a node — scaled by its 0..1 weight. */
+export function nodeRadius(node: PodGraphNode): number {
+  const base = node.kind === 'collision' || node.kind === 'intervention' ? 14 : 13;
+  return base + Math.max(0, Math.min(1, node.weight)) * 7;
+}
+
+export function statusColor(status: string): string {
+  if (status === 'risk') return RED;
+  if (status === 'learned') return VIOLET;
+  if (status === 'active') return BLUE;
+  return 'var(--muted-foreground)';
+}
+
+export type Mode = 'risk' | 'learn' | 'all';
+
+export interface Highlight {
+  nodes: Set<string>;
+  edges: Set<string>;
+}
+
+/**
+ * The lit set for the current mode/selection. A selected node lights its
+ * incident edges + neighbors; otherwise the mode lights the risk or learning
+ * chain (collision → intervention → learned_from). `all` lights everything.
+ */
+export function highlightFor(graph: PodGraph, mode: Mode, selected: string | null): Highlight | null {
+  if (selected) {
+    const es = graph.edges.filter((e) => e.source === selected || e.target === selected);
+    return {
+      nodes: new Set([selected, ...es.flatMap((e) => [e.source, e.target])]),
+      edges: new Set(es.map((e) => e.id)),
+    };
+  }
+  if (mode === 'all') return null;
+  const kinds: PodGraphEdge['kind'][] =
+    mode === 'risk' ? ['collides', 'warns', 'learned_from'] : ['learned_from', 'warns'];
+  const collisions = new Set(graph.nodes.filter((n) => n.kind === 'collision').map((n) => n.id));
+  const es = graph.edges.filter(
+    (e) =>
+      kinds.includes(e.kind) ||
+      (mode === 'risk' && (collisions.has(e.target) || collisions.has(e.source))),
+  );
+  return {
+    nodes: new Set(es.flatMap((e) => [e.source, e.target])),
+    edges: new Set(es.map((e) => e.id)),
+  };
+}
+
+function joinNames(ids: string[], label: (id: string) => string): string {
+  const u = [...new Set(ids)].map(label);
+  if (u.length <= 1) return u[0] ?? '';
+  if (u.length === 2) return `${u[0]} and ${u[1]}`;
+  return `${u.slice(0, -1).join(', ')} and ${u[u.length - 1]}`;
+}
+
+/**
+ * A plain-English walk of the flow through a node — what PodMan saw, flagged,
+ * suggested, and learned — so clicking a node explains the path, not just shows
+ * attributes. Built by traversing the node's incident edges.
+ */
+export function flowNarrative(graph: PodGraph, nodeId: string): string {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const node = byId.get(nodeId);
+  if (!node) return '';
+  const label = (id: string): string => byId.get(id)?.label ?? id;
+  const out = graph.edges.filter((e) => e.source === nodeId);
+  const inc = graph.edges.filter((e) => e.target === nodeId);
+
+  switch (node.kind) {
+    case 'engineer': {
+      const edits = out.filter((e) => e.kind === 'editing').map((e) => e.target);
+      const collisions = out.filter((e) => e.kind === 'collides');
+      const owns = out.filter((e) => e.kind === 'owns').map((e) => label(e.target));
+      const learned = inc.some((e) => e.kind === 'learned_from');
+      const parts: string[] = [];
+      if (edits.length) parts.push(`${node.label} is working in ${joinNames(edits, label)}.`);
+      if (collisions.length)
+        parts.push(
+          `PodMan flagged ${collisions.length} overlap${collisions.length === 1 ? '' : 's'} involving ${node.label}.`,
+        );
+      if (learned)
+        parts.push(
+          `From an accepted intervention PodMan learned ${node.label} owns ${owns[0] ?? 'this file'} — retained across sessions.`,
+        );
+      else if (owns.length) parts.push(`PodMan has ${node.label} owning ${joinNames(owns, (s) => s)}.`);
+      return parts.join(' ') || `${node.label} has no active flow right now.`;
+    }
+    case 'file': {
+      const editors = inc.filter((e) => e.kind === 'editing' || e.kind === 'owns').map((e) => e.source);
+      const hasCollision = out.some((e) => e.kind === 'touches');
+      const parts: string[] = [];
+      if (editors.length) parts.push(`${node.label} is being edited by ${joinNames(editors, label)}.`);
+      if (hasCollision)
+        parts.push('Two of those edits overlap before push, so PodMan opened a collision on it.');
+      return parts.join(' ') || node.summary || node.label;
+    }
+    case 'collision': {
+      const engineers = inc.filter((e) => e.kind === 'collides').map((e) => e.source);
+      const fileEdge = inc.find((e) => e.kind === 'touches');
+      const file = fileEdge ? label(fileEdge.source) : 'the same file';
+      const intervention = out.find((e) => e.kind === 'warns');
+      let s = `${joinNames(engineers, label) || 'Two engineers'} are both editing ${file} before pushing — the overlap git can't see.`;
+      if (intervention) s += ` PodMan stepped in and suggested a ${label(intervention.target)}.`;
+      return s;
+    }
+    case 'intervention': {
+      const colEdge = inc.find((e) => e.kind === 'warns');
+      const learned = out.find((e) => e.kind === 'learned_from');
+      // Resolve the collision's underlying file via its touches edge (file → collision).
+      let file = '';
+      if (colEdge) {
+        const fileEdge = graph.edges.find((e) => e.kind === 'touches' && e.target === colEdge.source);
+        file = fileEdge ? label(fileEdge.source) : '';
+      }
+      let s = `PodMan offered a ${node.label}${file ? ` for the overlap on ${file}` : ''}.`;
+      if (learned)
+        s += ` The pod accepted it, so PodMan learned ${label(learned.target)} owns ${file || 'the file'} — the graph got sharper.`;
+      return s;
+    }
+    case 'feature': {
+      const contributors = inc.filter((e) => e.kind === 'owns' || e.kind === 'touches').map((e) => e.source);
+      return contributors.length
+        ? `${node.label} is built on work by ${joinNames(contributors, label)}.`
+        : node.summary || node.label;
+    }
+    default:
+      return node.summary ?? '';
+  }
+}
+
+/** Short explainer for the current view when nothing is selected. */
+export function modeBlurb(mode: Mode): string {
+  if (mode === 'learn')
+    return 'The violet learned_from links are ownership PodMan kept from accepted interventions — the graph sharpens every session.';
+  if (mode === 'all')
+    return 'Everyone, every file, and every collision and intervention PodMan is tracking for this pod.';
+  return 'The lit path: files where two editors collide before push → the nudge PodMan sent → what it learned.';
+}
+
+export const NODE_LEGEND: Array<{ label: string; swatch: CSSProperties }> = [
+  { label: 'engineer', swatch: { background: BLUE } },
+  { label: 'file', swatch: { border: `2px solid ${SLATE}` } },
+  { label: 'feature', swatch: { background: AMBER, borderRadius: '50%' } },
+  { label: 'collision', swatch: { background: RED, clipPath: 'polygon(50% 0,100% 100%,0 100%)' } },
+  { label: 'intervention', swatch: { background: VIOLET, transform: 'rotate(45deg)' } },
+];
+
+export const EDGE_LEGEND: Array<{ label: string; color: string; dash?: boolean }> = [
+  { label: 'collides', color: RED },
+  { label: 'warns', color: AMBER },
+  { label: 'learned_from', color: VIOLET, dash: true },
+  { label: 'owns', color: BLUE },
+  { label: 'editing', color: SLATE_EDGE },
+  { label: 'touches', color: SLATE_FAINT },
+];

frontend/src/components/graph/forceSim.ts

@@ -0,0 +1,284 @@
+/**
+ * A tiny dependency-free force-directed layout — the same family of forces as
+ * d3-force (charge repulsion, link springs, centering, collision) integrated
+ * with velocity-Verlet and an annealing `alpha`. Kept in-house so the dynamic
+ * graph adds no new package / lockfile churn to a fast-moving shared `main`.
+ *
+ * Usage: `setData()` (diff-preserving — existing nodes keep their position),
+ * then drive `tick()` from a requestAnimationFrame loop until `settled()`.
+ */
+
+export interface SimNodeInput {
+  id: string;
+  /** Drawing/collision radius. */
+  radius: number;
+  /** Initial position hint (e.g. the server layout), used only for new nodes. */
+  seedX: number;
+  seedY: number;
+}
+
+export interface SimLinkInput {
+  source: string;
+  target: string;
+  /** Preferred rest length of the spring. */
+  distance: number;
+  /** 0..1 spring strength. */
+  strength: number;
+}
+
+export interface SimNode {
+  id: string;
+  x: number;
+  y: number;
+  vx: number;
+  vy: number;
+  /** When non-null the node is pinned (dragged) and forces don't move it. */
+  fx: number | null;
+  fy: number | null;
+  radius: number;
+}
+
+const ALPHA_MIN = 0.001;
+const ALPHA_DECAY = 1 - Math.pow(ALPHA_MIN, 1 / 300); // settle in ~300 ticks
+const FRICTION = 0.62; // velocity retained per tick
+const REPEL = 4400; // charge repulsion strength — must dominate centering or the graph collapses
+const LINK_K = 0.45; // spring stiffness multiplier
+const CENTER_STRENGTH = 0.014; // gentle positional pull — only keeps the cloud roughly centered
+const RECENTER = 0.5; // per-tick centroid recentering (no compression, keeps graph framed)
+const COLLIDE_PAD = 12;
+const COLLIDE_STRENGTH = 1; // hard separation so linked nodes never stack
+const COLLIDE_ITERS = 2;
+const BOUND_PAD = 30; // keep nodes this far inside the canvas edges
+
+export class ForceSim {
+  nodes: SimNode[] = [];
+  links: SimLinkInput[] = [];
+  alpha = 1;
+  private byId = new Map<string, SimNode>();
+  private alphaTarget = 0;
+  private center: { x: number; y: number };
+  private width: number;
+  private height: number;
+
+  constructor(width: number, height: number) {
+    this.width = width;
+    this.height = height;
+    this.center = { x: width / 2, y: height / 2 };
+  }
+
+  settled(): boolean {
+    return this.alpha < ALPHA_MIN && this.alphaTarget === 0;
+  }
+
+  reheat(a = 0.7): void {
+    this.alpha = Math.max(this.alpha, a);
+  }
+
+  /** Hold the simulation warm while dragging, then release. */
+  setActive(active: boolean): void {
+    this.alphaTarget = active ? 0.18 : 0;
+    if (active) this.reheat(0.25);
+  }
+
+  get(id: string): SimNode | undefined {
+    return this.byId.get(id);
+  }
+
+  pin(id: string, x: number, y: number): void {
+    const n = this.byId.get(id);
+    if (n) {
+      n.fx = x;
+      n.fy = y;
+    }
+  }
+
+  unpin(id: string): void {
+    const n = this.byId.get(id);
+    if (n) {
+      n.fx = null;
+      n.fy = null;
+    }
+  }
+
+  /** Replace the graph, preserving the positions/pins of nodes that persist. */
+  setData(nodeInputs: SimNodeInput[], linkInputs: SimLinkInput[]): { added: string[] } {
+    const prev = this.byId;
+    const next = new Map<string, SimNode>();
+    const added: string[] = [];
+    for (const inp of nodeInputs) {
+      const old = prev.get(inp.id);
+      if (old) {
+        old.radius = inp.radius;
+        next.set(inp.id, old);
+      } else {
+        next.set(inp.id, {
+          id: inp.id,
+          x: inp.seedX + (Math.random() - 0.5) * 14,
+          y: inp.seedY + (Math.random() - 0.5) * 14,
+          vx: 0,
+          vy: 0,
+          fx: null,
+          fy: null,
+          radius: inp.radius,
+        });
+        added.push(inp.id);
+      }
+    }
+    this.byId = next;
+    this.nodes = [...next.values()];
+    this.links = linkInputs.filter((l) => next.has(l.source) && next.has(l.target));
+    return { added };
+  }
+
+  /** Advance one step. Returns false when already settled (no work done). */
+  tick(): boolean {
+    if (this.settled()) return false;
+    this.alpha += (this.alphaTarget - this.alpha) * ALPHA_DECAY;
+    const a = this.alpha;
+    this.applyCharge(a);
+    this.applyLinks(a);
+    this.applyCenter(a);
+    for (let k = 0; k < COLLIDE_ITERS; k++) this.applyCollide();
+    const maxX = this.width - BOUND_PAD;
+    const maxY = this.height - BOUND_PAD;
+    for (const n of this.nodes) {
+      if (n.fx != null) {
+        n.x = n.fx;
+        n.vx = 0;
+      } else {
+        n.vx *= FRICTION;
+        n.x += n.vx;
+        if (n.x < BOUND_PAD) {
+          n.x = BOUND_PAD;
+          n.vx = 0;
+        } else if (n.x > maxX) {
+          n.x = maxX;
+          n.vx = 0;
+        }
+      }
+      if (n.fy != null) {
+        n.y = n.fy;
+        n.vy = 0;
+      } else {
+        n.vy *= FRICTION;
+        n.y += n.vy;
+        if (n.y < BOUND_PAD) {
+          n.y = BOUND_PAD;
+          n.vy = 0;
+        } else if (n.y > maxY) {
+          n.y = maxY;
+          n.vy = 0;
+        }
+      }
+    }
+    return true;
+  }
+
+  private applyCharge(alpha: number): void {
+    const ns = this.nodes;
+    for (let i = 0; i < ns.length; i++) {
+      const a = ns[i];
+      if (!a) continue;
+      for (let j = i + 1; j < ns.length; j++) {
+        const b = ns[j];
+        if (!b) continue;
+        let dx = b.x - a.x;
+        let dy = b.y - a.y;
+        let d2 = dx * dx + dy * dy;
+        if (d2 === 0) {
+          dx = (j - i) * 0.5;
+          dy = (i + 1) * 0.4;
+          d2 = dx * dx + dy * dy;
+        }
+        const dist = Math.sqrt(d2);
+        const force = (REPEL * alpha) / d2;
+        const ux = dx / dist;
+        const uy = dy / dist;
+        a.vx -= ux * force;
+        a.vy -= uy * force;
+        b.vx += ux * force;
+        b.vy += uy * force;
+      }
+    }
+  }
+
+  private applyLinks(alpha: number): void {
+    for (const link of this.links) {
+      const s = this.byId.get(link.source);
+      const t = this.byId.get(link.target);
+      if (!s || !t) continue;
+      let dx = t.x - s.x;
+      let dy = t.y - s.y;
+      let d2 = dx * dx + dy * dy;
+      if (d2 === 0) {
+        dx = 0.5;
+        dy = 0.5;
+        d2 = 0.5;
+      }
+      const dist = Math.sqrt(d2);
+      const k = ((dist - link.distance) / dist) * alpha * link.strength * LINK_K;
+      const mx = dx * k * 0.5;
+      const my = dy * k * 0.5;
+      s.vx += mx;
+      s.vy += my;
+      t.vx -= mx;
+      t.vy -= my;
+    }
+  }
+
+  private applyCenter(alpha: number): void {
+    const n = this.nodes.length;
+    if (!n) return;
+    // Recenter the whole cloud so its centroid sits at canvas center (this does
+    // NOT compress the layout — repulsion/links set the spread), plus a gentle
+    // positional pull so stray/isolated nodes don't park against the edge.
+    let cx = 0;
+    let cy = 0;
+    for (const nd of this.nodes) {
+      cx += nd.x;
+      cy += nd.y;
+    }
+    cx = (this.center.x - cx / n) * RECENTER;
+    cy = (this.center.y - cy / n) * RECENTER;
+    for (const nd of this.nodes) {
+      if (nd.fx == null) {
+        nd.x += cx;
+        nd.vx += (this.center.x - nd.x) * CENTER_STRENGTH * alpha;
+      }
+      if (nd.fy == null) {
+        nd.y += cy;
+        nd.vy += (this.center.y - nd.y) * CENTER_STRENGTH * alpha;
+      }
+    }
+  }
+
+  private applyCollide(): void {
+    const ns = this.nodes;
+    for (let i = 0; i < ns.length; i++) {
+      const a = ns[i];
+      if (!a) continue;
+      for (let j = i + 1; j < ns.length; j++) {
+        const b = ns[j];
+        if (!b) continue;
+        let dx = b.x - a.x;
+        let dy = b.y - a.y;
+        const d2 = dx * dx + dy * dy;
+        const min = a.radius + b.radius + COLLIDE_PAD;
+        if (d2 >= min * min) continue;
+        let dist = Math.sqrt(d2);
+        if (dist === 0) {
+          dx = j - i;
+          dy = i + 1;
+          dist = Math.sqrt(dx * dx + dy * dy) || 1;
+        }
+        const push = ((min - dist) / dist) * 0.5 * COLLIDE_STRENGTH;
+        const ox = dx * push;
+        const oy = dy * push;
+        if (a.fx == null) a.x -= ox;
+        if (a.fy == null) a.y -= oy;
+        if (b.fx == null) b.x += ox;
+        if (b.fy == null) b.y += oy;
+      }
+    }
+  }
+}

frontend/src/lib/api.ts

@@ -46,6 +46,20 @@ export async function postOutcome(outcome: InterventionOutcome): Promise<void> {
   if (!res.ok) throw new Error(`outcome post failed: ${res.status}`);
 }
 
+export async function createSyncPr(input: {
+  headBranch?: string;
+  file?: string;
+  summary?: string;
+}): Promise<{ url: string; number: number }> {
+  return json(
+    await fetch(`${BACKEND_URL}/api/sync-pr`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(input),
+    }),
+  );
+}
+
 // --- Pods CRUD ---
 
 export async function listPods(): Promise<Pod[]> {

frontend/src/lib/graph.ts

@@ -8,3 +8,8 @@ export async function fetchPodGraph(podId: string): Promise<PodGraph> {
   if (!res.ok) throw new Error(`graph request failed: ${res.status}`);
   return res.json() as Promise<PodGraph>;
 }
+
+/** WebSocket URL for the live event bus — used to nudge the graph to refetch. */
+export function backendEventsUrl(): string {
+  return `${BACKEND_URL.replace(/^http/, 'ws')}/api/events`;
+}

frontend/src/livekit/useInterventions.ts

@@ -1,18 +1,26 @@
 import { useEffect, useState, useCallback } from 'react';
 import { RoomEvent, type Room } from 'livekit-client';
-import type { DataMessage, Intervention, InterventionStatus } from '@podman/shared';
+import type { DataMessage, HermesMessage, Intervention, InterventionStatus } from '@podman/shared';
 import { DATA_TOPIC } from '@podman/shared';
-import { postOutcome } from '../lib/api';
+import { createSyncPr, postOutcome } from '../lib/api';
 
 export function useInterventions(room: Room | null) {
   const [active, setActive] = useState<Intervention | null>(null);
+  const [hermes, setHermes] = useState<HermesMessage | null>(null);
+  const [voiceCue, setVoiceCue] = useState<string | null>(null);
+  const [actionUrl, setActionUrl] = useState<string | null>(null);
 
   useEffect(() => {
     if (!room) return;
     const onData = (payload: Uint8Array, _p: unknown, _k: unknown, topic?: string) => {
       if (topic !== DATA_TOPIC) return;
       const msg = JSON.parse(new TextDecoder().decode(payload)) as DataMessage;
-      if (msg.type === 'COLLISION') setActive(msg.intervention);
+      if (msg.type === 'COLLISION') {
+        setActive(msg.intervention);
+        setActionUrl(null);
+      }
+      if (msg.type === 'HERMES_MESSAGE') setHermes(msg.message);
+      if (msg.type === 'VOICE_CUE') setVoiceCue(msg.text);
     };
     room.on(RoomEvent.DataReceived, onData);
     return () => {
@@ -23,6 +31,13 @@ export function useInterventions(room: Room | null) {
   const respond = useCallback(
     async (status: InterventionStatus, accepted: boolean) => {
       if (!active) return;
+      if (accepted && active.suggestedAction.kind === 'open_sync_pr') {
+        const pr = await createSyncPr({
+          file: String(active.suggestedAction.params?.file ?? ''),
+          summary: String(active.suggestedAction.params?.summary ?? active.message),
+        });
+        setActionUrl(pr.url);
+      }
       await postOutcome({
         interventionId: active.id,
         collisionId: active.collisionId,
@@ -31,11 +46,17 @@ export function useInterventions(room: Room | null) {
         accepted,
         recordedAt: new Date().toISOString(),
       });
+      await room?.localParticipant.publishData(
+        new TextEncoder().encode(
+          JSON.stringify({ type: 'ACK', interventionId: active.id, status }),
+        ),
+        { reliable: true, topic: DATA_TOPIC },
+      );
       setActive(null);
       return status;
     },
-    [active],
+    [active, room],
   );
 
-  return { active, respond };
+  return { active, hermes, voiceCue, actionUrl, respond };
 }

frontend/src/livekit/useScreenPublish.ts

@@ -1,41 +0,0 @@
-import { useCallback, useRef, useState } from 'react';
-import { Room, Track, createLocalScreenTracks, VideoPresets } from 'livekit-client';
-import { fetchToken } from '../lib/api';
-
-export function useScreenPublish() {
-  const roomRef = useRef<Room | null>(null);
-  const [connected, setConnected] = useState(false);
-  const [sharing, setSharing] = useState(false);
-
-  const join = useCallback(
-    async (pod: string, identity: string, name: string, githubLogin?: string) => {
-      const { token, url } = await fetchToken({ room: pod, identity, name, githubLogin });
-      const room = new Room({ adaptiveStream: true, dynacast: true });
-      await room.connect(url, token);
-      roomRef.current = room;
-      setConnected(true);
-      return room;
-    },
-    [],
-  );
-
-  const startSharing = useCallback(async () => {
-    const room = roomRef.current;
-    if (!room) throw new Error('join the pod first');
-    const tracks = await createLocalScreenTracks({
-      audio: true,
-      resolution: VideoPresets.h1080.resolution,
-    });
-    for (const t of tracks) {
-      await room.localParticipant.publishTrack(t.mediaStreamTrack, {
-        source:
-          t.kind === Track.Kind.Audio ? Track.Source.ScreenShareAudio : Track.Source.ScreenShare,
-      });
-    }
-    await room.localParticipant.setMicrophoneEnabled(true);
-    await room.localParticipant.setCameraEnabled(true);
-    setSharing(true);
-  }, []);
-
-  return { join, startSharing, connected, sharing, room: roomRef };
-}

infra/.do/app.yaml

@@ -48,7 +48,8 @@ services:
       - { key: LIVEKIT_API_SECRET, scope: RUN_TIME, type: SECRET }
       - { key: GEMINI_API_KEY, scope: RUN_TIME, type: SECRET }
       - { key: GEMINI_VISION_MODEL, scope: RUN_TIME, value: gemini-2.0-flash }
-      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-live-2.5-flash }
+      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-3.1-flash-tts-preview }
+      - { key: GEMINI_EMBEDDING_MODEL, scope: RUN_TIME, value: gemini-embedding-001 }
       - { key: GITHUB_TOKEN, scope: RUN_TIME, type: SECRET }
       - { key: GITHUB_REPO, scope: RUN_TIME, value: karti-ai/podman }
       - { key: MONGODB_URI, scope: RUN_TIME, type: SECRET }
@@ -73,7 +74,8 @@ workers:
       - { key: LIVEKIT_API_SECRET, scope: RUN_TIME, type: SECRET }
       - { key: GEMINI_API_KEY, scope: RUN_TIME, type: SECRET }
       - { key: GEMINI_VISION_MODEL, scope: RUN_TIME, value: gemini-2.0-flash }
-      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-live-2.5-flash }
+      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-3.1-flash-tts-preview }
+      - { key: GEMINI_EMBEDDING_MODEL, scope: RUN_TIME, value: gemini-embedding-001 }
       - { key: GITHUB_TOKEN, scope: RUN_TIME, type: SECRET }
       - { key: GITHUB_REPO, scope: RUN_TIME, value: karti-ai/podman }
       - { key: MONGODB_URI, scope: RUN_TIME, type: SECRET }

infra/Caddyfile

@@ -15,5 +15,26 @@
 }
 
 lk.165-22-129-249.sslip.io {
-	reverse_proxy localhost:7880
+	reverse_proxy https://meta-54zzak8x.livekit.cloud {
+		header_up Host meta-54zzak8x.livekit.cloud
+		transport http {
+			tls_server_name meta-54zzak8x.livekit.cloud
+		}
+	}
+}
+
+podman.live, www.podman.live {
+	route {
+		handle /api/* {
+			reverse_proxy 127.0.0.1:8787
+		}
+
+		handle /health {
+			reverse_proxy 127.0.0.1:8787
+		}
+
+		root * /var/www/podman
+		try_files {path} /index.html
+		file_server
+	}
 }

infra/README.md

@@ -4,7 +4,7 @@ Deploy targets for PodMan on DigitalOcean.
 
 - `Dockerfile` — builds the backend runtime image from the monorepo root
 - `app.yaml` — DigitalOcean App Platform spec: static site, API service, agent worker
-- `systemd/` — local droplet service units for the API and agent worker
+- `systemd/` — local droplet service/timer units for the API, agent worker, public healthcheck, and Hermes watchdog
 
 Full deploy spec and env var reference in [`docs/digitalocean.md`](../docs/digitalocean.md).
 
@@ -24,6 +24,16 @@ docker run --env-file backend/.env -e PODMAN_PROCESS=server -p 8787:8787 podman-
 docker run --env-file backend/.env -e PODMAN_PROCESS=agent podman-backend
 ```
 
+The automated check uses Docker by default, matching `pnpm build:container`:
+
+```bash
+pnpm build:container
+pnpm verify:containers
+```
+
+Set `VERIFY_CONTAINER_RUNTIME=podman` to run the same verifier against a Podman
+image store.
+
 ## Local production services
 
 On the demo droplet, serve the API and worker with systemd instead of tmux:
@@ -31,9 +41,10 @@ On the demo droplet, serve the API and worker with systemd instead of tmux:
 ```bash
 sudo install -m 0644 infra/systemd/podman-platform-api.service /etc/systemd/system/
 sudo install -m 0644 infra/systemd/podman-platform-agent.service /etc/systemd/system/
+sudo install -m 0644 infra/systemd/podman-hermes-*.service infra/systemd/podman-hermes-*.timer /etc/systemd/system/
 sudo systemctl daemon-reload
-sudo systemctl enable --now podman-platform-api podman-platform-agent
-sudo systemctl status podman-platform-api podman-platform-agent
+sudo systemctl enable --now podman-platform-api podman-platform-agent podman-hermes-watchdog.timer podman-hermes-sync-deploy.timer
+sudo systemctl status podman-platform-api podman-platform-agent podman-hermes-watchdog.timer podman-hermes-sync-deploy.timer
 ```
 
 The services expect:
@@ -47,6 +58,7 @@ Useful checks:
 ```bash
 curl http://127.0.0.1:8787/health
 journalctl -u podman-platform-api -u podman-platform-agent -f
+journalctl -u podman-hermes-watchdog -f
 ```
 
 ## DigitalOcean deploy
@@ -73,9 +85,34 @@ local LiveKit host.
 
 ```bash
 sudo cp infra/systemd/podman-platform-*.service /etc/systemd/system/
+sudo cp infra/systemd/podman-hermes-watchdog.* /etc/systemd/system/
 sudo systemctl daemon-reload
-sudo systemctl enable --now podman-platform-api podman-platform-agent
-systemctl status podman-platform-api podman-platform-agent
+sudo systemctl enable --now podman-platform-api podman-platform-agent podman-hermes-watchdog.timer
+systemctl status podman-platform-api podman-platform-agent podman-hermes-watchdog.timer
+```
+
+## Hermes operations layer
+
+Hermes is the operations copilot for the droplet. The durable layer is:
+
+- `podman-hermes-watchdog.timer` runs `pnpm hermes:watchdog` every five minutes.
+- `podman-hermes-sync-deploy.timer` polls `origin/main` every two minutes and deploys clean fast-forward changes.
+- `podman-public-healthcheck.timer` keeps the fast public URL restart loop.
+- `/var/log/podman/hermes-watchdog-latest.json` records the latest watchdog report.
+- `.git/hooks/pre-push`, installed by `pnpm hermes:install`, gates major pushes with typecheck, lint, and a non-remediating watchdog check.
+
+Install or refresh all local ops wiring:
+
+```bash
+pnpm hermes:install
+```
+
+Manual one-shot checks:
+
+```bash
+pnpm hermes:watchdog
+pnpm hermes:watchdog:strict
+pnpm hermes:sync-deploy
 ```
 
 ## Fallback (demo safety)

infra/app.yaml

@@ -48,7 +48,8 @@ services:
       - { key: LIVEKIT_API_SECRET, scope: RUN_TIME, type: SECRET }
       - { key: GEMINI_API_KEY, scope: RUN_TIME, type: SECRET }
       - { key: GEMINI_VISION_MODEL, scope: RUN_TIME, value: gemini-2.0-flash }
-      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-live-2.5-flash }
+      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-3.1-flash-tts-preview }
+      - { key: GEMINI_EMBEDDING_MODEL, scope: RUN_TIME, value: gemini-embedding-001 }
       - { key: GITHUB_TOKEN, scope: RUN_TIME, type: SECRET }
       - { key: GITHUB_REPO, scope: RUN_TIME, value: karti-ai/podman }
       - { key: MONGODB_URI, scope: RUN_TIME, type: SECRET }
@@ -73,7 +74,8 @@ workers:
       - { key: LIVEKIT_API_SECRET, scope: RUN_TIME, type: SECRET }
       - { key: GEMINI_API_KEY, scope: RUN_TIME, type: SECRET }
       - { key: GEMINI_VISION_MODEL, scope: RUN_TIME, value: gemini-2.0-flash }
-      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-live-2.5-flash }
+      - { key: GEMINI_LIVE_MODEL, scope: RUN_TIME, value: gemini-3.1-flash-tts-preview }
+      - { key: GEMINI_EMBEDDING_MODEL, scope: RUN_TIME, value: gemini-embedding-001 }
       - { key: GITHUB_TOKEN, scope: RUN_TIME, type: SECRET }
       - { key: GITHUB_REPO, scope: RUN_TIME, value: karti-ai/podman }
       - { key: MONGODB_URI, scope: RUN_TIME, type: SECRET }

infra/systemd/podman-hermes-sync-deploy.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=PodMan Hermes git sync and deploy
+After=network-online.target podman-platform-api.service podman-platform-agent.service caddy.service
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+WorkingDirectory=/root/podman
+Environment=NODE_ENV=production
+Environment=PODMAN_DEPLOY_REMOTE=origin
+Environment=PODMAN_DEPLOY_BRANCH=main
+Environment=PODMAN_HERMES_STATE_DIR=/var/log/podman
+EnvironmentFile=/root/podman/backend/.env
+ExecStart=/usr/bin/node scripts/hermes-sync-deploy.mjs
+Nice=5
+IOSchedulingClass=best-effort

infra/systemd/podman-hermes-sync-deploy.timer

@@ -0,0 +1,11 @@
+[Unit]
+Description=Poll origin/main and let Hermes deploy clean fast-forward changes
+
+[Timer]
+OnBootSec=90s
+OnUnitActiveSec=2min
+AccuracySec=30s
+Unit=podman-hermes-sync-deploy.service
+
+[Install]
+WantedBy=timers.target

infra/systemd/podman-hermes-watchdog.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=PodMan Hermes operations watchdog
+After=network-online.target mongod.service podman-platform-api.service podman-platform-agent.service caddy.service
+Wants=network-online.target mongod.service podman-platform-api.service podman-platform-agent.service caddy.service
+
+[Service]
+Type=oneshot
+WorkingDirectory=/root/podman
+Environment=NODE_ENV=production
+Environment=PODMAN_HERMES_STRICT=0
+Environment=PODMAN_HERMES_REMEDIATE=1
+Environment=PODMAN_HERMES_STATE_DIR=/var/log/podman
+Environment=PODMAN_PUBLIC_URL=https://165-22-129-249.sslip.io/
+EnvironmentFile=/root/podman/backend/.env
+ExecStart=/usr/bin/node scripts/hermes-watchdog.mjs
+Nice=5
+IOSchedulingClass=best-effort

infra/systemd/podman-hermes-watchdog.timer

@@ -0,0 +1,11 @@
+[Unit]
+Description=Run PodMan Hermes operations watchdog every five minutes
+
+[Timer]
+OnBootSec=45s
+OnUnitActiveSec=5min
+AccuracySec=30s
+Unit=podman-hermes-watchdog.service
+
+[Install]
+WantedBy=timers.target

infra/systemd/podman-public-healthcheck.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=PodMan public URL healthcheck
+After=network-online.target mongod.service podman-platform-api.service podman-platform-agent.service caddy.service
+Wants=network-online.target mongod.service podman-platform-api.service podman-platform-agent.service caddy.service
+
+[Service]
+Type=oneshot
+WorkingDirectory=/root/podman
+Environment=PODMAN_PUBLIC_URL=https://165-22-129-249.sslip.io/
+Environment=PODMAN_HEALTH_TIMEOUT_MS=8000
+ExecStart=/usr/bin/node scripts/healthcheck-public.mjs

infra/systemd/podman-public-healthcheck.timer

@@ -0,0 +1,11 @@
+[Unit]
+Description=Run PodMan public URL healthcheck every minute
+
+[Timer]
+OnBootSec=30s
+OnUnitActiveSec=60s
+AccuracySec=10s
+Unit=podman-public-healthcheck.service
+
+[Install]
+WantedBy=timers.target

package.json

@@ -20,11 +20,17 @@
     "doctor": "node scripts/deploy-doctor.mjs",
     "doctor:strict": "node scripts/deploy-doctor.mjs --strict",
     "deploy:static:local": "node scripts/deploy-static-local.mjs",
+    "hermes:watchdog": "node scripts/hermes-watchdog.mjs",
+    "hermes:watchdog:strict": "node scripts/hermes-watchdog.mjs --strict",
+    "hermes:sync-deploy": "node scripts/hermes-sync-deploy.mjs",
+    "hermes:install": "node scripts/install-hermes-ops.mjs",
+    "healthcheck:public": "node scripts/healthcheck-public.mjs",
     "verify": "pnpm lint && pnpm typecheck && pnpm build && pnpm verify:backend && pnpm verify:frontend",
-    "verify:full": "pnpm verify && pnpm build:container && pnpm verify:containers",
+    "verify:full": "pnpm verify && pnpm verify:infra && pnpm build:container && pnpm verify:containers",
     "verify:backend": "node scripts/verify-backend.mjs",
     "verify:containers": "node scripts/verify-containers.mjs",
     "verify:frontend": "node scripts/verify-frontend.mjs",
+    "verify:infra": "node scripts/verify-infra.mjs",
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check ."

scripts/deploy-doctor.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { Buffer } from 'node:buffer';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { MongoClient } from 'mongodb';
@@ -15,7 +16,6 @@ const requiredEnv = [
   'LIVEKIT_URL',
   'LIVEKIT_API_KEY',
   'LIVEKIT_API_SECRET',
-  'GEMINI_API_KEY',
   'GITHUB_TOKEN',
   'GITHUB_REPO',
   'MONGODB_URI',
@@ -33,6 +33,19 @@ function isSet(name) {
   return !!process.env[name]?.trim();
 }
 
+function configuredGeminiKey() {
+  const candidates = ['GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GOOGLE_GENERATIVE_AI_API_KEY'];
+  for (const name of candidates) {
+    const value = process.env[name]?.trim();
+    if (!value) continue;
+    if (/replace|todo|example|your|xxx/i.test(value) || value.length < 20) {
+      throw new Error(`${name} looks like a placeholder or truncated key`);
+    }
+    return { name, value };
+  }
+  throw new Error('GEMINI_API_KEY is not set');
+}
+
 async function check(name, fn) {
   try {
     const detail = await fn();
@@ -205,12 +218,12 @@ async function checkGitHub() {
 }
 
 async function checkGeminiVision() {
-  if (!isSet('GEMINI_API_KEY')) throw new Error('GEMINI_API_KEY is not set');
+  const key = configuredGeminiKey();
   const model = process.env.GEMINI_VISION_MODEL ?? 'gemini-2.0-flash';
   const res = await doFetch(
     `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(
       model,
-    )}:generateContent?key=${encodeURIComponent(process.env.GEMINI_API_KEY)}`,
+    )}:generateContent?key=${encodeURIComponent(key.value)}`,
     {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
@@ -224,19 +237,63 @@ async function checkGeminiVision() {
   return model;
 }
 
-async function checkGeminiLiveListed() {
-  if (!isSet('GEMINI_API_KEY')) throw new Error('GEMINI_API_KEY is not set');
-  const model = process.env.GEMINI_LIVE_MODEL ?? 'gemini-live-2.5-flash';
+async function checkGeminiVoiceModel() {
+  const key = configuredGeminiKey();
+  const model = process.env.GEMINI_LIVE_MODEL ?? 'gemini-3.1-flash-tts-preview';
   const res = await doFetch(
-    `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(
-      process.env.GEMINI_API_KEY,
-    )}`,
+    `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(key.value)}`,
   );
   if (!res.ok) throw new Error(await responseError('Gemini model list', res));
   const body = await res.json();
   const names = (body.models ?? []).map((m) => m.name?.replace(/^models\//, ''));
   if (!names.includes(model)) throw new Error(`${model} not present in Gemini model list`);
-  return model;
+  if (!model.includes('tts')) return model;
+
+  const tts = await doFetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(
+      model,
+    )}:generateContent?key=${encodeURIComponent(key.value)}`,
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: 'Say clearly: PodMan voice check.' }] }],
+        generationConfig: {
+          responseModalities: ['AUDIO'],
+          speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Kore' } } },
+        },
+      }),
+    },
+  );
+  if (!tts.ok) throw new Error(await responseError('Gemini voice check', tts));
+  const ttsBody = await tts.json();
+  const audio = ttsBody.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
+  if (!audio) throw new Error('Gemini voice response had no audio');
+  return `${model}, generated ${Buffer.from(audio, 'base64').byteLength} audio bytes`;
+}
+
+async function checkGeminiEmbeddings() {
+  const key = configuredGeminiKey();
+  const model = process.env.GEMINI_EMBEDDING_MODEL ?? 'gemini-embedding-001';
+  const res = await doFetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(
+      model,
+    )}:embedContent?key=${encodeURIComponent(key.value)}`,
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        content: { parts: [{ text: 'PodMan vector memory check' }] },
+        taskType: 'RETRIEVAL_DOCUMENT',
+        outputDimensionality: 768,
+      }),
+    },
+  );
+  if (!res.ok) throw new Error(await responseError('Gemini embedding check', res));
+  const body = await res.json();
+  const dims = body.embedding?.values?.length;
+  if (!dims) throw new Error('Gemini embedding response had no vector');
+  return `${model}, ${dims} dimensions`;
 }
 
 async function checkVoyage() {
@@ -262,6 +319,16 @@ await check('workspace', checkWorkspace);
 for (const name of requiredEnv) {
   add(`env:${name}`, isSet(name) ? 'ok' : 'fail', isSet(name) ? 'set' : 'missing');
 }
+try {
+  const key = configuredGeminiKey();
+  add(
+    'env:GEMINI_API_KEY',
+    'ok',
+    key.name === 'GEMINI_API_KEY' ? 'set' : `using ${key.name} alias`,
+  );
+} catch (err) {
+  add('env:GEMINI_API_KEY', 'fail', summarizeError(err));
+}
 for (const name of optionalEnv) {
   add(`env:${name}`, isSet(name) ? 'ok' : 'warn', isSet(name) ? 'set' : 'optional');
 }
@@ -281,15 +348,15 @@ await check('livekit room service', checkLiveKitApi);
 await check('mongo ping', checkMongo);
 await check('github repo access', checkGitHub);
 await check('gemini vision model', checkGeminiVision);
-await check('gemini live model listed', checkGeminiLiveListed);
+await check('gemini voice model', checkGeminiVoiceModel);
+await check('gemini embeddings', checkGeminiEmbeddings);
 
 if (isSet('VOYAGE_API_KEY')) {
   await check('voyage embeddings', checkVoyage);
-  await check('atlas vector index', checkVectorIndex);
 } else {
-  add('voyage embeddings', 'warn', 'VOYAGE_API_KEY is optional; exact Mongo recall remains active');
-  add('atlas vector index', 'warn', 'requires VOYAGE_API_KEY and Atlas Search index');
+  add('voyage embeddings', 'warn', 'VOYAGE_API_KEY is optional; Gemini embeddings are active');
 }
+await check('atlas vector index', checkVectorIndex);
 
 const failed = results.filter((r) => r.status === 'fail');
 const warnings = results.filter((r) => r.status === 'warn');

scripts/healthcheck-public.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+
+const rootUrl = process.env.PODMAN_PUBLIC_URL ?? 'https://165-22-129-249.sslip.io/';
+const apiUrl = process.env.PODMAN_PUBLIC_API_URL ?? new URL('/api/pods', rootUrl).toString();
+const timeoutMs = Number(process.env.PODMAN_HEALTH_TIMEOUT_MS ?? 8000);
+const doFetch = globalThis.fetch;
+const { AbortController, clearTimeout, setTimeout } = globalThis;
+const requiredServices = [
+  'mongod.service',
+  'podman-platform-api.service',
+  'podman-platform-agent.service',
+  'caddy.service',
+];
+
+async function fetchOk(url) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await doFetch(url, { signal: controller.signal });
+    return { ok: res.ok, status: res.status };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function run(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+    child.on('error', (error) => resolve({ code: 127, stdout, stderr: error.message }));
+  });
+}
+
+async function runChecked(command, args) {
+  const result = await run(command, args);
+  if (result.code !== 0) {
+    const output = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join('\n');
+    throw new Error(
+      `${command} ${args.join(' ')} failed with ${result.code}${output ? `:\n${output}` : ''}`,
+    );
+  }
+  return result;
+}
+
+async function serviceOk(service) {
+  const result = await run('systemctl', ['is-active', '--quiet', service]);
+  return { ok: result.code === 0, code: result.code };
+}
+
+async function restartServices(reason) {
+  console.error(`[healthcheck] ${reason}; restarting public app services`);
+  for (const service of requiredServices) {
+    await runChecked('systemctl', ['restart', service]);
+  }
+}
+
+const urlChecks = [
+  ['root', rootUrl, await fetchOk(rootUrl).catch((error) => ({ ok: false, error: error.message }))],
+  ['api', apiUrl, await fetchOk(apiUrl).catch((error) => ({ ok: false, error: error.message }))],
+];
+const serviceChecks = await Promise.all(
+  requiredServices.map(async (service) => [
+    `service:${service}`,
+    service,
+    await serviceOk(service),
+  ]),
+);
+const checks = [...urlChecks, ...serviceChecks];
+
+const failed = checks.filter(([, , result]) => !result.ok);
+if (failed.length) {
+  await restartServices(
+    failed
+      .map(([name, url, result]) => `${name} ${url} ${result.status ?? result.error}`)
+      .join('; '),
+  );
+  const retryUrlChecks = [
+    [
+      'root',
+      rootUrl,
+      await fetchOk(rootUrl).catch((error) => ({ ok: false, error: error.message })),
+    ],
+    ['api', apiUrl, await fetchOk(apiUrl).catch((error) => ({ ok: false, error: error.message }))],
+  ];
+  const retryServiceChecks = await Promise.all(
+    requiredServices.map(async (service) => [
+      `service:${service}`,
+      service,
+      await serviceOk(service),
+    ]),
+  );
+  const retry = [...retryUrlChecks, ...retryServiceChecks];
+  const stillFailed = retry.filter(([, , result]) => !result.ok);
+  console.log(JSON.stringify({ ok: stillFailed.length === 0, checks, retry }, null, 2));
+  process.exit(stillFailed.length === 0 ? 0 : 1);
+}
+
+console.log(JSON.stringify({ ok: true, checks }, null, 2));

scripts/hermes-sync-deploy.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+
+const branch = process.env.PODMAN_DEPLOY_BRANCH ?? 'main';
+const remote = process.env.PODMAN_DEPLOY_REMOTE ?? 'origin';
+const services = (
+  process.env.PODMAN_DEPLOY_RESTART_SERVICES ??
+  ['podman-platform-api.service', 'podman-platform-agent.service', 'caddy.service'].join(',')
+)
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+const report = {
+  ok: false,
+  branch,
+  remote,
+  startedAt: new Date().toISOString(),
+  completedAt: '',
+  changed: false,
+  from: '',
+  to: '',
+  steps: [],
+};
+
+function run(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: { ...process.env, ...options.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('close', (code, signal) => resolve({ code, signal, stdout, stderr }));
+    child.on('error', (error) =>
+      resolve({ code: 127, signal: null, stdout, stderr: error.message }),
+    );
+  });
+}
+
+function detail(result, max = 1600) {
+  return [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join('\n').slice(-max);
+}
+
+async function step(name, command, args, options) {
+  const result = await run(command, args, options);
+  const ok = result.code === 0;
+  report.steps.push({ name, ok, detail: detail(result) });
+  if (!ok) throw new Error(`${name} failed`);
+  return result;
+}
+
+async function gitOutput(args) {
+  const result = await run('git', args);
+  if (result.code !== 0) throw new Error(`git ${args.join(' ')} failed: ${detail(result)}`);
+  return result.stdout.trim();
+}
+
+async function main() {
+  const currentBranch = await gitOutput(['branch', '--show-current']);
+  if (currentBranch !== branch)
+    throw new Error(`expected branch ${branch}, found ${currentBranch}`);
+
+  await step('fetch', 'git', ['fetch', remote, branch]);
+  const dirty = await gitOutput(['status', '--porcelain']);
+  if (dirty) throw new Error(`working tree is dirty; refusing auto-deploy:\n${dirty}`);
+
+  const local = await gitOutput(['rev-parse', 'HEAD']);
+  const upstream = await gitOutput(['rev-parse', `${remote}/${branch}`]);
+  report.from = local;
+  report.to = upstream;
+
+  if (local === upstream) {
+    report.ok = true;
+    report.completedAt = new Date().toISOString();
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  await step('fast-forward', 'git', ['merge', '--ff-only', `${remote}/${branch}`]);
+  report.changed = true;
+  await step('install', 'pnpm', ['install', '--frozen-lockfile'], {
+    env: { CI: 'true' },
+  });
+  await step('build', 'pnpm', ['build']);
+  await step('deploy static', 'pnpm', ['deploy:static:local']);
+  for (const service of services)
+    await step(`restart ${service}`, 'systemctl', ['restart', service]);
+  await step('hermes watchdog', 'pnpm', ['hermes:watchdog:strict']);
+
+  report.ok = true;
+  report.completedAt = new Date().toISOString();
+  console.log(JSON.stringify(report, null, 2));
+}
+
+try {
+  await main();
+} catch (error) {
+  report.ok = false;
+  report.completedAt = new Date().toISOString();
+  report.error = error instanceof Error ? error.message : String(error);
+  console.error(JSON.stringify(report, null, 2));
+  process.exit(1);
+}

scripts/hermes-watchdog.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { config as loadEnv } from 'dotenv';
+
+const envPath = process.env.DOTENV_CONFIG_PATH ?? (existsSync('.env') ? '.env' : 'backend/.env');
+loadEnv({ path: envPath, quiet: true });
+
+const { AbortController, clearTimeout, fetch, setTimeout } = globalThis;
+const args = new Set(process.argv.slice(2));
+const remediate = !args.has('--no-remediate') && process.env.PODMAN_HERMES_REMEDIATE !== '0';
+const strict = args.has('--strict') || process.env.PODMAN_HERMES_STRICT === '1';
+const jsonOnly = args.has('--json');
+const rootUrl = process.env.PODMAN_PUBLIC_URL ?? 'https://165-22-129-249.sslip.io/';
+const apiUrl = process.env.PODMAN_PUBLIC_API_URL ?? new URL('/api/pods', rootUrl).toString();
+const healthUrl = process.env.PODMAN_PUBLIC_HEALTH_URL ?? new URL('/health', rootUrl).toString();
+const timeoutMs = Number(process.env.PODMAN_HERMES_TIMEOUT_MS ?? 8000);
+const stateDir = process.env.PODMAN_HERMES_STATE_DIR ?? '/var/log/podman';
+const services = (
+  process.env.PODMAN_HERMES_SERVICES ??
+  [
+    'mongod.service',
+    'podman-platform-api.service',
+    'podman-platform-agent.service',
+    'caddy.service',
+  ].join(',')
+)
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+const report = {
+  ok: false,
+  strict,
+  remediate,
+  startedAt: new Date().toISOString(),
+  completedAt: '',
+  checks: [],
+  remediation: [],
+  logs: {},
+};
+
+function addCheck(name, ok, detail = '') {
+  report.checks.push({ name, ok, detail });
+  return ok;
+}
+
+function summarizeOutput(result, max = 1200) {
+  return [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join('\n').slice(-max);
+}
+
+function run(command, args = [], options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: { ...process.env, ...options.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 2000).unref();
+    }, options.timeoutMs ?? timeoutMs);
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal, stdout, stderr });
+    });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      resolve({ code: 127, signal: null, stdout, stderr: error.message });
+    });
+  });
+}
+
+async function fetchWithTimeout(url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    const text = await res.text().catch(() => '');
+    return { ok: res.ok, status: res.status, text: text.slice(0, 300) };
+  } catch (error) {
+    return { ok: false, status: 0, text: error instanceof Error ? error.message : String(error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function checkUrls() {
+  for (const [name, url] of [
+    ['public root', rootUrl],
+    ['public health', healthUrl],
+    ['public api', apiUrl],
+  ]) {
+    const result = await fetchWithTimeout(url);
+    addCheck(name, result.ok, `${url} -> ${result.status || result.text}`);
+  }
+}
+
+async function checkServices() {
+  for (const service of services) {
+    const active = await run('systemctl', ['is-active', '--quiet', service], { timeoutMs: 5000 });
+    addCheck(`service:${service}`, active.code === 0, `systemctl is-active exit ${active.code}`);
+  }
+}
+
+async function checkDoctor() {
+  const doctorArgs = ['deploy:doctor'];
+  if (strict) doctorArgs[0] = 'deploy:doctor:strict';
+  const result = await run('pnpm', doctorArgs, {
+    timeoutMs: Number(process.env.PODMAN_HERMES_DOCTOR_TIMEOUT_MS ?? 120000),
+  });
+  const ok = result.code === 0 && /"ok":\s*true/.test(result.stdout);
+  addCheck(`pnpm ${doctorArgs[0]}`, ok, summarizeOutput(result, 2000));
+}
+
+async function collectLogs(failedServices = services) {
+  for (const service of failedServices) {
+    const result = await run('journalctl', ['-u', service, '-n', '80', '--no-pager'], {
+      timeoutMs: 8000,
+    });
+    report.logs[service] = summarizeOutput(result, 6000);
+  }
+}
+
+async function restart(service) {
+  const result = await run('systemctl', ['restart', service], { timeoutMs: 20000 });
+  report.remediation.push({
+    action: `restart ${service}`,
+    ok: result.code === 0,
+    detail: summarizeOutput(result),
+  });
+  return result.code === 0;
+}
+
+async function validateCaddy() {
+  if (!existsSync('/etc/caddy/Caddyfile')) return;
+  const result = await run('caddy', ['validate', '--config', '/etc/caddy/Caddyfile'], {
+    timeoutMs: 10000,
+  });
+  report.remediation.push({
+    action: 'caddy validate',
+    ok: result.code === 0,
+    detail: summarizeOutput(result),
+  });
+  if (result.code === 0) {
+    const reload = await run('systemctl', ['reload', 'caddy.service'], { timeoutMs: 10000 });
+    report.remediation.push({
+      action: 'reload caddy.service',
+      ok: reload.code === 0,
+      detail: summarizeOutput(reload),
+    });
+  }
+}
+
+async function remediateFailures() {
+  const failed = report.checks.filter((c) => !c.ok);
+  if (!failed.length || !remediate) return;
+
+  const failedServiceNames = failed.map((c) => c.name.match(/^service:(.+)$/)?.[1]).filter(Boolean);
+
+  if (failedServiceNames.length) {
+    for (const service of failedServiceNames) await restart(service);
+  } else {
+    for (const service of services.filter((s) => s !== 'mongod.service')) await restart(service);
+  }
+
+  if (failed.some((c) => c.name.includes('public'))) await validateCaddy();
+  await delay(3000);
+}
+
+async function writeReport() {
+  report.completedAt = new Date().toISOString();
+  report.ok = report.checks.every((c) => c.ok);
+  await mkdir(stateDir, { recursive: true });
+  const payload = JSON.stringify(report, null, 2);
+  await writeFile(join(stateDir, 'hermes-watchdog-latest.json'), payload);
+  await writeFile(join(stateDir, `hermes-watchdog-${Date.now()}.json`), payload);
+  return payload;
+}
+
+async function alert(payload) {
+  const url = process.env.PODMAN_ALERT_WEBHOOK_URL;
+  if (!url || report.ok) return;
+  const failed = report.checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.detail}`);
+  const text = `PodMan Hermes watchdog failed ${failed.length} check(s):\n${failed.join('\n')}`;
+  try {
+    await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        content: text,
+        text,
+        username: 'PodMan Hermes',
+        report: JSON.parse(payload),
+      }),
+    });
+  } catch (error) {
+    report.remediation.push({
+      action: 'send alert',
+      ok: false,
+      detail: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+await checkServices();
+await checkUrls();
+await checkDoctor();
+
+const firstFailed = report.checks.filter((c) => !c.ok);
+await remediateFailures();
+
+if (firstFailed.length && remediate) {
+  report.checks.push({ name: 'retry boundary', ok: true, detail: 'after remediation' });
+  await checkServices();
+  await checkUrls();
+  await checkDoctor();
+}
+
+await collectLogs(
+  report.checks
+    .filter((c) => !c.ok)
+    .map((c) => c.name.match(/^service:(.+)$/)?.[1])
+    .filter(Boolean),
+);
+
+const payload = await writeReport();
+await alert(payload);
+
+if (!jsonOnly) {
+  for (const check of report.checks) {
+    console.log(
+      `${check.ok ? 'OK  ' : 'FAIL'} ${check.name}${check.detail ? ` - ${check.detail}` : ''}`,
+    );
+  }
+  for (const action of report.remediation) {
+    console.log(`${action.ok ? 'OK  ' : 'FAIL'} remediate:${action.action}`);
+  }
+}
+console.log(payload);
+process.exit(report.ok || !strict ? 0 : 1);

scripts/install-hermes-ops.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { chmod, copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+const root = process.cwd();
+const dryRun = process.argv.includes('--dry-run');
+
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit' });
+    child.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`${command} exited ${code}`)),
+    );
+    child.on('error', reject);
+  });
+}
+
+async function installFile(source, target, mode = 0o644) {
+  console.log(`${dryRun ? 'would install' : 'install'} ${source} -> ${target}`);
+  if (dryRun) return;
+  await copyFile(source, target);
+  await chmod(target, mode);
+}
+
+async function installGitHook() {
+  const hookDir = `${root}/.git/hooks`;
+  if (!existsSync(hookDir)) return;
+  const hook = `#!/usr/bin/env bash
+set -euo pipefail
+cd "${root}"
+echo "[hermes] running pre-push verification"
+pnpm -r typecheck
+pnpm lint
+pnpm hermes:watchdog -- --no-remediate --json >/tmp/podman-hermes-pre-push.json
+echo "[hermes] pre-push verification passed"
+`;
+  console.log(`${dryRun ? 'would write' : 'write'} ${hookDir}/pre-push`);
+  if (dryRun) return;
+  await writeFile(`${hookDir}/pre-push`, hook);
+  await chmod(`${hookDir}/pre-push`, 0o755);
+}
+
+await installFile(
+  'infra/systemd/podman-hermes-watchdog.service',
+  '/etc/systemd/system/podman-hermes-watchdog.service',
+);
+await installFile(
+  'infra/systemd/podman-hermes-watchdog.timer',
+  '/etc/systemd/system/podman-hermes-watchdog.timer',
+);
+await installFile(
+  'infra/systemd/podman-hermes-sync-deploy.service',
+  '/etc/systemd/system/podman-hermes-sync-deploy.service',
+);
+await installFile(
+  'infra/systemd/podman-hermes-sync-deploy.timer',
+  '/etc/systemd/system/podman-hermes-sync-deploy.timer',
+);
+await installFile(
+  'infra/systemd/podman-public-healthcheck.service',
+  '/etc/systemd/system/podman-public-healthcheck.service',
+);
+await installFile(
+  'infra/systemd/podman-public-healthcheck.timer',
+  '/etc/systemd/system/podman-public-healthcheck.timer',
+);
+
+await mkdir('/var/log/podman', { recursive: true });
+await installGitHook();
+
+if (!dryRun) {
+  await run('systemctl', ['daemon-reload']);
+  await run('systemctl', ['enable', '--now', 'podman-hermes-watchdog.timer']);
+  await run('systemctl', ['enable', '--now', 'podman-hermes-sync-deploy.timer']);
+  await run('systemctl', ['enable', '--now', 'podman-public-healthcheck.timer']);
+  await run('systemctl', [
+    'status',
+    '--no-pager',
+    'podman-hermes-watchdog.timer',
+    'podman-hermes-sync-deploy.timer',
+    'podman-public-healthcheck.timer',
+  ]);
+}
+
+console.log(JSON.stringify({ ok: true, installed: !dryRun }, null, 2));

scripts/verify-backend.mjs

@@ -155,8 +155,52 @@ async function verifyMemoryRecall() {
     detectedAt: new Date().toISOString(),
   };
   await recordCollision(seed);
+  const { getDb } = await import('../backend/dist/memory/db.js');
+  const db = await getDb();
+  const stored = await db.collection('collisions').findOne({ id: seed.id });
+  if (!Array.isArray(stored?.embedding) || stored.embedding.length < 1) {
+    fail('memory collision was not enriched with an embedding');
+  }
   const recalled = await recallSimilar({ ...seed, id: `${seed.id}_query` });
   if (!recalled) fail('memory recall did not find seeded collision');
+  const vectorRecalled = await recallSimilar({
+    ...seed,
+    id: `${seed.id}_vector_query`,
+    file: 'src/nearby-memory.ts',
+    symbol: 'nearbyMemory',
+  });
+  if (!vectorRecalled) fail('vector memory recall did not find semantically similar collision');
+}
+
+async function verifyGraph() {
+  process.env.LIVEKIT_URL = env.LIVEKIT_URL;
+  process.env.LIVEKIT_API_KEY = env.LIVEKIT_API_KEY;
+  process.env.LIVEKIT_API_SECRET = env.LIVEKIT_API_SECRET;
+  process.env.GEMINI_API_KEY = env.GEMINI_API_KEY;
+  process.env.GITHUB_TOKEN = env.GITHUB_TOKEN;
+  process.env.GITHUB_REPO = env.GITHUB_REPO;
+  process.env.MONGODB_URI = env.MONGODB_URI;
+
+  const podId = `verify-graph-${Date.now()}`;
+  const { seedGraph } = await import('../backend/dist/graph/store.js');
+  await seedGraph(podId);
+
+  const graph = await json(await doFetch(`${baseUrl}/api/pods/${encodeURIComponent(podId)}/graph`));
+  if (!Array.isArray(graph.nodes) || graph.nodes.length < 1)
+    fail('graph endpoint returned no nodes');
+  if (!Array.isArray(graph.edges) || graph.edges.length < 1)
+    fail('graph endpoint returned no edges');
+
+  const reach = await json(
+    await doFetch(
+      `${baseUrl}/api/pods/${encodeURIComponent(podId)}/graph/reach/${encodeURIComponent(
+        'engineer:karti',
+      )}`,
+    ),
+  );
+  if (!Array.isArray(reach.reaches) || reach.reaches.length < 1) {
+    fail('graph reachability endpoint returned no reachable edges');
+  }
 }
 
 async function verifyGitWatcher() {
@@ -206,6 +250,7 @@ try {
   await verifyApi();
   await verifyCollisionAndMessages();
   await verifyMemoryRecall();
+  await verifyGraph();
   await verifyGitWatcher();
   console.log(
     JSON.stringify(
@@ -213,7 +258,15 @@ try {
         ok: true,
         baseUrl,
         mongoUri,
-        checks: ['health', 'token', 'pod-crud', 'collision', 'memory-recall', 'git-watcher'],
+        checks: [
+          'health',
+          'token',
+          'pod-crud',
+          'collision',
+          'memory-recall',
+          'graph',
+          'git-watcher',
+        ],
       },
       null,
       2,

scripts/verify-containers.mjs

@@ -5,6 +5,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { config as loadEnv } from 'dotenv';
 
 const image = process.env.VERIFY_CONTAINER_IMAGE ?? 'podman-backend';
+const runtime = process.env.VERIFY_CONTAINER_RUNTIME ?? 'docker';
 const port = Number(process.env.VERIFY_CONTAINER_PORT ?? 8799);
 const baseUrl = `http://127.0.0.1:${port}`;
 const runId = `${process.pid}-${Date.now()}`;
@@ -21,14 +22,19 @@ const containerEnv = {
   LIVEKIT_API_KEY: process.env.LIVEKIT_API_KEY ?? 'verify-key',
   LIVEKIT_API_SECRET: process.env.LIVEKIT_API_SECRET ?? 'verify-secret',
   GEMINI_API_KEY: process.env.GEMINI_API_KEY ?? 'verify-gemini',
+  GEMINI_VISION_MODEL: process.env.GEMINI_VISION_MODEL ?? 'gemini-2.0-flash',
+  GEMINI_LIVE_MODEL: process.env.GEMINI_LIVE_MODEL ?? 'gemini-3.1-flash-tts-preview',
+  GEMINI_EMBEDDING_MODEL: process.env.GEMINI_EMBEDDING_MODEL ?? 'gemini-embedding-001',
   GITHUB_TOKEN: process.env.GITHUB_TOKEN ?? 'verify-github',
   GITHUB_REPO: process.env.GITHUB_REPO ?? 'karti-ai/podman',
   MONGODB_URI: process.env.MONGODB_URI ?? 'mongodb://127.0.0.1:27017/podman',
+  VOYAGE_API_KEY: process.env.VOYAGE_API_KEY ?? '',
+  VOYAGE_EMBEDDING_MODEL: process.env.VOYAGE_EMBEDDING_MODEL ?? 'voyage-4-lite',
 };
 
-function runPodman(args, options = {}) {
+function runContainer(args, options = {}) {
   return new Promise((resolve) => {
-    const child = spawn('podman', args, {
+    const child = spawn(runtime, args, {
       stdio: ['ignore', 'pipe', 'pipe'],
       ...options,
     });
@@ -61,12 +67,15 @@ function fail(message) {
 }
 
 async function assertPodmanAvailable() {
-  const result = await runPodman(['--version']);
-  if (result.code !== 0) fail(`podman is not available: ${result.stderr.trim()}`);
+  const result = await runContainer(['--version']);
+  if (result.code !== 0) fail(`${runtime} is not available: ${result.stderr.trim()}`);
 }
 
 async function assertImageExists() {
-  const result = await runPodman(['image', 'exists', image]);
+  const result =
+    runtime === 'podman'
+      ? await runContainer(['image', 'exists', image])
+      : await runContainer(['image', 'inspect', image]);
   if (result.code !== 0) {
     fail(
       `container image "${image}" does not exist locally; build it before running this verifier`,
@@ -75,18 +84,23 @@ async function assertImageExists() {
 }
 
 async function removeContainer(name) {
-  await runPodman(['rm', '-f', name]);
+  await runContainer(['rm', '-f', name]);
 }
 
 async function startContainer(name, extraEnv) {
   await removeContainer(name);
-  const result = await runPodman([
+  const networkArgs =
+    runtime === 'podman'
+      ? ['--network', 'host']
+      : extraEnv.PODMAN_PROCESS === 'server'
+        ? ['--publish', `127.0.0.1:${port}:${port}`]
+        : [];
+  const result = await runContainer([
     'run',
     '--detach',
     '--name',
     name,
-    '--network',
-    'host',
+    ...networkArgs,
     ...envArgs(extraEnv),
     image,
   ]);
@@ -96,7 +110,7 @@ async function startContainer(name, extraEnv) {
 }
 
 async function stopContainer(name) {
-  await runPodman(['stop', '--time', '3', name]);
+  await runContainer(['stop', '--time', '3', name]);
   await removeContainer(name);
 }
 
@@ -125,7 +139,7 @@ async function waitForApi() {
     }
     await delay(500);
   }
-  const logs = await runPodman(['logs', apiContainer]);
+  const logs = await runContainer(['logs', apiContainer]);
   fail(
     `API container did not become healthy at ${baseUrl}: ${lastError}\n${logs.stdout}${logs.stderr}`,
   );
@@ -154,11 +168,11 @@ async function verifyAgentContainer() {
 
   let output = '';
   for (let i = 0; i < 60; i++) {
-    const logs = await runPodman(['logs', agentContainer]);
+    const logs = await runContainer(['logs', agentContainer]);
     output = `${logs.stdout}${logs.stderr}`;
     if (output.includes('podman-hermes joined room')) return;
 
-    const inspect = await runPodman([
+    const inspect = await runContainer([
       'inspect',
       '--format',
       '{{.State.Running}} {{.State.ExitCode}}',
@@ -182,10 +196,17 @@ try {
     JSON.stringify(
       {
         ok: true,
+        runtime,
         image,
         baseUrl,
         containers: [apiContainer, agentContainer],
-        checks: ['image-exists', 'api-health', 'api-pods', 'agent-joined-room'],
+        checks: [
+          'image-exists',
+          'api-health',
+          'api-pods',
+          'agent-joined-room',
+          'gemini-model-envs',
+        ],
       },
       null,
       2,

scripts/verify-frontend.mjs

@@ -1,12 +1,27 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { TextEncoder } from 'node:util';
 import { chromium } from 'playwright';
 import { setTimeout as delay } from 'node:timers/promises';
+import { config as loadEnv } from 'dotenv';
+import { RoomServiceClient } from 'livekit-server-sdk';
 
+loadEnv({ path: 'backend/.env', quiet: true });
 const frontendUrl = process.env.FRONTEND_URL ?? 'http://127.0.0.1:4173/';
 const shouldStartPreview = !process.env.FRONTEND_URL;
 const doFetch = globalThis.fetch;
 const verifyMember = `Verify ${process.pid}`;
+const apiBase = process.env.BACKEND_URL
+  ? process.env.BACKEND_URL.replace(/\/$/, '')
+  : process.env.FRONTEND_URL
+    ? new URL(process.env.FRONTEND_URL).origin
+    : 'http://localhost:8787';
+const { DATA_TOPIC } = await import('../shared/dist/messages.js').catch(() => ({
+  DATA_TOPIC: 'podman.intervention',
+}));
+const backendRequire = createRequire(new URL('../backend/package.json', import.meta.url));
+const { Room } = backendRequire('@livekit/rtc-node');
 
 async function stopChild(child) {
   if (!child || child.exitCode !== null || child.signalCode !== null) return;
@@ -42,6 +57,117 @@ async function waitForPreview() {
   throw new Error(`frontend preview did not become ready at ${frontendUrl}`);
 }
 
+async function fetchJson(path, init) {
+  const res = await doFetch(`${apiBase}${path}`, init);
+  const text = await res.text();
+  const body = text ? JSON.parse(text) : null;
+  if (!res.ok) throw new Error(`${path} returned ${res.status}: ${text}`);
+  return body;
+}
+
+async function connectPublisher(roomName) {
+  const { token, url } = await fetchJson('/api/token', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      room: roomName,
+      identity: `verify-agent-${process.pid}`,
+      name: 'PodMan',
+    }),
+  });
+  const room = new Room();
+  await room.connect(url, token, { autoSubscribe: true });
+  return room;
+}
+
+async function publishIntervention(room, podId) {
+  const now = new Date().toISOString();
+  const id = `verify-${process.pid}-${Date.now()}`;
+  const intervention = {
+    id: `int-${id}`,
+    collisionId: `col-${id}`,
+    podId,
+    kind: 'card',
+    message: 'Verification collision: two engineers are editing frontend/src/App.tsx.',
+    suggestedAction: { kind: 'sync_before_push' },
+    status: 'pending',
+    createdAt: now,
+  };
+  const message = {
+    type: 'COLLISION',
+    collision: {
+      id: intervention.collisionId,
+      podId,
+      file: 'src/App.tsx',
+      engineers: ['Verify', 'PodMan'],
+      severity: 'warn',
+      githubState: { branch: 'verify', unpushed: true, prs: [] },
+      detectedAt: now,
+    },
+    intervention,
+  };
+  await room.localParticipant.publishData(new TextEncoder().encode(JSON.stringify(message)), {
+    reliable: true,
+    topic: DATA_TOPIC,
+  });
+  return intervention;
+}
+
+async function publishDataMessage(room, message) {
+  await room.localParticipant.publishData(new TextEncoder().encode(JSON.stringify(message)), {
+    reliable: true,
+    topic: DATA_TOPIC,
+  });
+}
+
+async function waitForInterventionCard(page, room, podId) {
+  const cardText = 'Verification collision: two engineers are editing frontend/src/App.tsx.';
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    const intervention = await publishIntervention(room, podId);
+    try {
+      await page.getByText(cardText).waitFor({ timeout: 5_000 });
+      return intervention;
+    } catch (error) {
+      if (attempt === 3) throw error;
+      await delay(500);
+    }
+  }
+}
+
+function liveKitService() {
+  if (!process.env.LIVEKIT_URL || !process.env.LIVEKIT_API_KEY || !process.env.LIVEKIT_API_SECRET) {
+    throw new Error('screen publication verification requires LIVEKIT_* env vars');
+  }
+  const httpUrl = process.env.LIVEKIT_URL.replace(/^wss:/, 'https:').replace(/^ws:/, 'http:');
+  return new RoomServiceClient(
+    httpUrl,
+    process.env.LIVEKIT_API_KEY,
+    process.env.LIVEKIT_API_SECRET,
+  );
+}
+
+function hasScreenShareTrack(participant) {
+  return (participant.tracks ?? []).some((track) => {
+    const source = JSON.stringify(track).toLowerCase();
+    return source.includes('screen') || source.includes('share');
+  });
+}
+
+async function waitForPublishedScreenShare(roomName) {
+  const service = liveKitService();
+  let lastParticipants = [];
+  for (let i = 0; i < 30; i++) {
+    lastParticipants = await service.listParticipants(roomName);
+    if (lastParticipants.some(hasScreenShareTrack)) return;
+    await delay(500);
+  }
+  throw new Error(
+    `LiveKit room service did not list a screen-share publication in ${roomName}: ${JSON.stringify(
+      lastParticipants,
+    ).slice(0, 1000)}`,
+  );
+}
+
 let preview = null;
 if (shouldStartPreview) {
   preview = spawn(
@@ -57,6 +183,37 @@ if (shouldStartPreview) {
 
 const browser = await chromium.launch({ headless: true });
 const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
+await page.addInitScript(() => {
+  globalThis.__podmanVerifyScreens = [];
+  Object.defineProperty(globalThis.navigator, 'mediaDevices', {
+    configurable: true,
+    value: {
+      ...(globalThis.navigator.mediaDevices ?? {}),
+      async getDisplayMedia() {
+        const canvas = globalThis.document.createElement('canvas');
+        canvas.width = 640;
+        canvas.height = 360;
+        const ctx = canvas.getContext('2d');
+        if (!ctx) throw new Error('canvas context unavailable');
+        let frame = 0;
+        const draw = () => {
+          frame += 1;
+          ctx.fillStyle = '#fff';
+          ctx.fillRect(0, 0, canvas.width, canvas.height);
+          ctx.fillStyle = '#111';
+          ctx.font = '28px sans-serif';
+          ctx.fillText('PodMan verification screen', 32, 72);
+          ctx.fillText(`frame ${frame}`, 32, 120);
+        };
+        draw();
+        const interval = globalThis.setInterval(draw, 200);
+        const stream = canvas.captureStream(5);
+        globalThis.__podmanVerifyScreens.push({ canvas, stream, interval });
+        return stream;
+      },
+    },
+  });
+});
 
 const consoleErrors = [];
 const pageErrors = [];
@@ -86,8 +243,20 @@ try {
   if (!hasPodCards) throw new Error('pod cards did not render');
   if (hasOverlay) throw new Error('Vite error overlay is visible');
 
-  await page.getByPlaceholder('Your name').first().fill(verifyMember);
-  await page.getByRole('button', { name: 'Add and join' }).first().click();
+  await page.getByRole('button', { name: 'Team memory' }).click();
+  await page.getByText('Workflow metrics').waitFor({ timeout: 15_000 });
+  await page.getByText('Learning edges').waitFor({ timeout: 15_000 });
+  await page.getByRole('img', { name: 'PodMan team-memory graph' }).waitFor({ timeout: 15_000 });
+  await page.getByRole('button', { name: 'engineer: Karti' }).click();
+  await page.getByText('Learned owner of auth; backend + DB wiring.').waitFor({ timeout: 15_000 });
+  await page.getByRole('button', { name: 'Whole graph' }).click();
+  await page.getByRole('button', { name: /Pods/i }).click();
+
+  const frontendPodCard = page
+    .getByText('Frontend Pod', { exact: true })
+    .locator('xpath=ancestor::*[.//input[@placeholder="Your name"]][1]');
+  await frontendPodCard.getByPlaceholder('Your name').fill(verifyMember);
+  await frontendPodCard.getByRole('button', { name: 'Add and join' }).click();
   await page.getByRole('button', { name: 'Share screen' }).waitFor({ timeout: 15_000 });
 
   const joinedText = await page.locator('body').innerText();
@@ -99,6 +268,49 @@ try {
   if (!hasPodView) {
     throw new Error(`pod detail controls did not render after join: ${joinedText.slice(0, 500)}`);
   }
+
+  await page.getByRole('button', { name: 'Share screen' }).click();
+  await page.getByRole('button', { name: 'Stop sharing' }).waitFor({ timeout: 15_000 });
+  await page.getByText(/Screen\s*published/i).waitFor({ timeout: 15_000 });
+  await waitForPublishedScreenShare('frontend-pod');
+  await page.getByRole('button', { name: 'Stop sharing' }).click();
+  await page.getByRole('button', { name: 'Share screen' }).waitFor({ timeout: 15_000 });
+
+  const publisher = await connectPublisher('frontend-pod');
+  try {
+    const intervention = await waitForInterventionCard(page, publisher, 'frontend-pod');
+    await publishDataMessage(publisher, {
+      type: 'HERMES_MESSAGE',
+      message: {
+        id: `hermes-${process.pid}`,
+        podId: 'frontend-pod',
+        interventionId: intervention.id,
+        recipients: ['Verify'],
+        text: 'Hermes verification message routed to the team.',
+        urgency: 'normal',
+        createdAt: new Date().toISOString(),
+      },
+    });
+    await publishDataMessage(publisher, {
+      type: 'VOICE_CUE',
+      text: 'Voice cue verification for urgent escalation.',
+    });
+    await page.getByText('Hermes message').waitFor({ timeout: 15_000 });
+    await page.getByText('Hermes verification message routed to the team.').waitFor({
+      timeout: 15_000,
+    });
+    await page.getByText('Voice cue', { exact: true }).waitFor({ timeout: 15_000 });
+    await page.getByText('Voice cue verification for urgent escalation.').waitFor({
+      timeout: 15_000,
+    });
+    await page.getByRole('button', { name: 'Dismiss' }).click();
+    await page.getByText('No collision detected').waitFor({ timeout: 15_000 });
+  } finally {
+    await publisher.disconnect();
+  }
+
+  await page.getByRole('button', { name: 'Leave pod' }).click();
+
   if (consoleErrors.length) throw new Error(`console errors: ${consoleErrors.join(' | ')}`);
   if (pageErrors.length) throw new Error(`page errors: ${pageErrors.join(' | ')}`);
   if (failedRequests.length) throw new Error(`failed requests: ${failedRequests.join(' | ')}`);
@@ -108,8 +320,12 @@ try {
       {
         ok: true,
         frontendUrl,
+        apiBase,
         bodyLength: bodyText.length,
+        graph: true,
         joined: true,
+        screenShare: 'livekit-published',
+        intervention: 'collision-hermes-voice',
         member: verifyMember,
       },
       null,
@@ -117,12 +333,11 @@ try {
     ),
   );
 } finally {
-  const apiBase = process.env.FRONTEND_URL
-    ? new URL(process.env.FRONTEND_URL).origin
-    : 'http://localhost:8787';
   await doFetch(`${apiBase}/api/pods/frontend-pod/members/${encodeURIComponent(verifyMember)}`, {
     method: 'DELETE',
   }).catch(() => {});
   await browser.close();
   await stopChild(preview);
 }
+
+process.exit(0);

scripts/verify-infra.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function requireText(haystack, needle, label) {
+  if (!haystack.includes(needle)) fail(`${label} missing: ${needle}`);
+}
+
+function sectionBetween(text, start, end) {
+  const startAt = text.indexOf(start);
+  if (startAt === -1) fail(`section not found: ${start}`);
+  const endAt = end ? text.indexOf(end, startAt + start.length) : -1;
+  return text.slice(startAt, endAt === -1 ? undefined : endAt);
+}
+
+function requireEnvKeys(section, keys, label) {
+  for (const key of keys) {
+    requireText(section, `key: ${key}`, label);
+  }
+}
+
+const [appSpec, doSpec, dockerfile, digitalOceanDocs] = await Promise.all([
+  readFile('infra/app.yaml', 'utf8'),
+  readFile('infra/.do/app.yaml', 'utf8'),
+  readFile('infra/Dockerfile', 'utf8'),
+  readFile('docs/digitalocean.md', 'utf8'),
+]);
+
+if (appSpec !== doSpec) {
+  fail('infra/.do/app.yaml must stay identical to infra/app.yaml');
+}
+
+const web = sectionBetween(appSpec, 'static_sites:', 'services:');
+const api = sectionBetween(appSpec, '  - name: api', 'workers:');
+const worker = sectionBetween(appSpec, '  - name: podman-agent');
+
+requireText(web, 'output_dir: frontend/dist', 'web static site');
+requireText(web, 'value: ${APP_URL}', 'web static site VITE_BACKEND_URL');
+requireEnvKeys(web, ['VITE_BACKEND_URL', 'VITE_LIVEKIT_URL'], 'web static site envs');
+
+requireText(api, 'dockerfile_path: infra/Dockerfile', 'api service');
+requireText(api, 'http_port: 8787', 'api service');
+requireText(api, 'http_path: /health', 'api service health check');
+requireText(api, 'path: /api', 'api service route');
+requireText(api, 'preserve_path_prefix: true', 'api service route');
+requireText(api, 'value: server', 'api service PODMAN_PROCESS');
+
+requireText(worker, 'dockerfile_path: infra/Dockerfile', 'worker');
+requireText(worker, 'value: agent', 'worker PODMAN_PROCESS');
+requireText(worker, 'value: demo-pod', 'worker POD_ROOM');
+if (worker.includes('health_check:') || worker.includes('http_port:')) {
+  fail('podman-agent must remain a worker, not a health-checked HTTP service');
+}
+
+const runtimeKeys = [
+  'LIVEKIT_URL',
+  'LIVEKIT_API_KEY',
+  'LIVEKIT_API_SECRET',
+  'GEMINI_API_KEY',
+  'GEMINI_VISION_MODEL',
+  'GEMINI_LIVE_MODEL',
+  'GEMINI_EMBEDDING_MODEL',
+  'GITHUB_TOKEN',
+  'GITHUB_REPO',
+  'MONGODB_URI',
+];
+requireEnvKeys(api, ['PODMAN_PROCESS', 'PORT', ...runtimeKeys], 'api service envs');
+requireEnvKeys(worker, ['PODMAN_PROCESS', 'POD_ROOM', ...runtimeKeys], 'worker envs');
+
+requireText(dockerfile, 'ENV PODMAN_PROCESS=server', 'Dockerfile');
+requireText(dockerfile, 'node backend/dist/agent.js', 'Dockerfile');
+requireText(dockerfile, 'node backend/dist/server.js', 'Dockerfile');
+requireText(dockerfile, 'EXPOSE 8787', 'Dockerfile');
+
+requireText(digitalOceanDocs, 'docker run --env-file backend/.env', 'DigitalOcean docs');
+requireText(digitalOceanDocs, '`/api` with `preserve_path_prefix: true`', 'DigitalOcean docs');
+requireText(
+  digitalOceanDocs,
+  '`podman-agent`: background LiveKit/Gemini worker',
+  'DigitalOcean docs',
+);
+
+console.log(
+  JSON.stringify(
+    {
+      ok: true,
+      checks: [
+        'app-spec-mirror',
+        'static-site-envs',
+        'api-route-preserves-prefix',
+        'worker-split',
+        'runtime-env-keys',
+        'docker-entrypoint',
+        'digitalocean-docs',
+      ],
+    },
+    null,
+    2,
+  ),
+);

shared/src/graph.ts

@@ -48,6 +48,36 @@ export interface PodGraphMetric {
   detail: string;
 }
 
+/** The five stages of PodMan's continual-learning loop, in order. */
+export type LearningStageKey = 'observe' | 'store' | 'predict' | 'outcome' | 'adapt';
+
+/** One stage of the learning-loop rail (observe→store→predict→outcome→adapt). */
+export interface LearningStage {
+  key: LearningStageKey;
+  /** UPPERCASE display title, e.g. "OBSERVE". */
+  title: string;
+  /** Headline figure for the stage, e.g. "5/s" or "124". */
+  value: string;
+  /** One-line detail under the title. */
+  detail: string;
+  /** True for the single most-recently-active stage (pulses in the UI). */
+  active: boolean;
+}
+
+/** Kind of an activity-stream entry (drives the colored tag). */
+export type ActivityKind = 'editing' | 'collision' | 'warns' | 'outcome' | 'learned_from';
+
+/** One time-tagged entry in the activity stream. */
+export interface ActivityEvent {
+  /** Stable id (source doc id + kind) so the UI can animate diffs. */
+  id: string;
+  /** ISO timestamp the event happened. */
+  at: string;
+  kind: ActivityKind;
+  /** Human-readable line, e.g. "Yahya opened auth.ts — unpushed changes". */
+  text: string;
+}
+
 /** A point-in-time render of a pod's team_model. */
 export interface PodGraph {
   podId: string;
@@ -56,6 +86,10 @@ export interface PodGraph {
   nodes: PodGraphNode[];
   edges: PodGraphEdge[];
   metrics: PodGraphMetric[];
+  /** Continual-learning loop counts (observe→…→adapt). Additive/optional. */
+  loop?: LearningStage[];
+  /** Recent activity feed, most-recent first, capped ~8. Additive/optional. */
+  activity?: ActivityEvent[];
 }
 
 /** One node as a standalone document in the `graph_nodes` collection. */

shared/src/index.ts

@@ -9,6 +9,7 @@ export type {
   SuggestedActionKind,
 } from './intervention.js';
 export * from './messages.js';
+export type { HermesMessage } from './messages.js';
 export type {
   PodGraph,
   PodGraphNode,
@@ -17,6 +18,10 @@ export type {
   PodGraphNodeKind,
   PodGraphEdgeKind,
   PodGraphNodeStatus,
+  LearningStage,
+  LearningStageKey,
+  ActivityEvent,
+  ActivityKind,
   GraphNodeDoc,
   GraphEdgeDoc,
 } from './graph.js';

shared/src/messages.ts

@@ -7,10 +7,22 @@ export const DATA_TOPIC = 'podman.intervention' as const;
 /** Wire messages exchanged between the PodMan agent and engineer PWAs. */
 export type DataMessage =
   | { type: 'COLLISION'; collision: Collision; intervention: Intervention }
+  | { type: 'HERMES_MESSAGE'; message: HermesMessage }
   | { type: 'VOICE_CUE'; text: string }
   | { type: 'ACK'; interventionId: string; status: InterventionStatus; note?: string }
   | { type: 'GIT_REPORT'; report: LocalGitReport };
 
+/** A targeted teammate/project-channel notification from the Hermes action layer. */
+export interface HermesMessage {
+  id: string;
+  podId: string;
+  interventionId: string;
+  recipients: string[];
+  text: string;
+  urgency: 'normal' | 'urgent';
+  createdAt: string;
+}
+
 /** Outcome of an intervention — the supervision signal for policy learning. */
 export interface InterventionOutcome {
   interventionId: string;